Refresh native workflow orientation and planning status

This commit is contained in:
2026-11-22 06:57:27 +00:00
parent b76d511571
commit 633ebd282f
7 changed files with 165 additions and 111 deletions

View File

@@ -7,12 +7,18 @@ PromptKit/ConfigKit/CommandKit adoption, continuation, admission, cache, output,
and debug decisions. Items below are ordered roughly by value and specificity,
not as committed release dates or prerequisites for that migration.
Native shared loading/commands, complete assessment/continuation, concurrent
ready lane completion, accepted-result reuse, and private capture are implemented;
see the [implementation evidence](implementation.md) for final acceptance status.
They are not deferred platform work. Human model-quality evaluation, broader
reference/context policies, and storage/distribution extensions below remain separate.
## Near-Term D&D Pipeline
### Evaluate Spell Extraction And Normalization
- Evaluate extraction, normalization, and correction quality against a
human-reviewed transcript set before and after the native migration.
human-reviewed transcript set, comparing retained baselines with the native path.
- Maintain a small set of human-reviewed transcripts and outputs for prompt,
validator, and normalizer development. Treat model-quality review as an
iterative human evaluation aid, not a deterministic correctness gate.
@@ -78,9 +84,9 @@ The sections below keep broader extensions deferred.
benefits from model judgment and deterministic checks are insufficient.
- Consider additional validator diagnostic views only if a concrete need remains
after the selected [native observations and debug capture](promptkit.md#inspection-and-execution-bookkeeping).
- Add validator compatibility metadata if deployments need config-time proof
that a validator is suitable for a particular stage, module, or artifact
kind.
- Existing typed resolution already checks validator target, artifact kind,
and exact Go-type compatibility. Add further semantic suitability metadata
only if a deployment needs a contract beyond those implemented checks.
- Add media-type validators when non-JSON artifact representations are
introduced.
@@ -88,8 +94,9 @@ The sections below keep broader extensions deferred.
- Make prior-run artifacts easier to bind as references without changing the
existing module-facing reference-item contract.
- Add structured or parsed references, such as typed NPC registries, rosters,
or spell catalogs, when opaque UTF-8 prompt material is no longer sufficient.
- Existing registry/catalog consumers already parse and validate typed contextual
projections. Consider a framework-level parsed-reference facility only when
concrete consumers need shared behavior beyond those module-owned resolvers.
- Add per-slot or per-chunk inclusion policies so large references are not
repeated in every prompt unnecessarily.
- Add token budgeting and model context-window management for reference
@@ -146,7 +153,8 @@ section only after a concrete workflow, contract, and priority emerge.
- Additional input adapters, such as Markdown or note-export formats.
- Additional output encoders.
- Concurrent cross-lane entity normalization or broader workflow composition.
- Broader workflow composition only when a concrete need justifies revisiting
the fixed-shape pipeline decision; ready cross-lane completion already runs concurrently.
- Batching or specialized context-window controls for LLM-backed validators.
### Distribution And Operations

View File

@@ -5,9 +5,10 @@
Implement the complete target in [Native PromptKit And CommandKit Migration](promptkit.md).
That feature roadmap owns product choices, defaults, ownership, and acceptance
semantics. This document owns execution order and stage completion. Completion
markers below record finished stages. The inspected application baseline is Notarius commit
`b3664d587914b1d7b0377f25fa377b57fa97c815`; its recent roadmap commits have not
implemented the migration.
markers below record finished stages. The inspected pre-migration application
baseline was Notarius commit `b3664d587914b1d7b0377f25fa377b57fa97c815`.
The completed stages below record the landed implementation and checks;
the final whole-roadmap acceptance audit remains pending until Stage 46.
Each numbered stage is one implementation prompt for a Luna coding agent.
Execute stages in integer order as one end-to-end sprint. Intermediate stages
@@ -2187,6 +2188,30 @@ compare claims with Stage 37's assembled boundary tests.
## Stage 45: Refresh Orientation And Reconcile Planning Status
**Status:** Complete. README now uses the maintained minimal configuration and
transcript with native required input syntax and links both examples, current
contracts, kit integration, and migration guidance. Updated contributor routing
and the internal package map for the shared native load/engine, preflight, typed
producer/assessment, ready workers, accepted-result store, evidence, and recorder;
removed navigation to deleted adapter/reporting/checkpoint packages.
Reconciled backlog wording for implemented compatibility checks, typed reference
projections, and concurrent lane completion while retaining human quality review,
larger reconciliation/context, distribution, and storage work separately. The
feature roadmap now distinguishes implemented choices/evidence from the still
pending final acceptance audit; retained its target/removal/acceptance scope and
historical baseline/comparison. Native library navigation is release-pinned.
Found and repaired one current Seriatim fixture link during the stale-name search.
Both actual example pipelines pass direct offline preflight with credentials
unset; maintained minimal/complete/development example and shared-reference tests
pass using native provider fakes. All 149 local links/anchors and 16 selected
upstream destinations/anchors in the changed documents resolve; eleven dated
Audita comparison links remain classified historical evidence, not current owner
navigation. Current-doc/example removal searches leave only explicit migration
guidance; `git diff --check` passes. No code, schema, release, archive, or runtime
data changed. Stage 46 and full-goal acceptance remain unmarked/pending.
**Goal:** entry points lead to current docs and preserve separate future scope.
**Inspect/change:** `docs/internal/overview.md`, `docs/development.md`, `README.md`,

View File

@@ -13,8 +13,12 @@ accepted-artifact caching, and artifact-first output. It owns the selected targe
decision status, removal inventory, acceptance criteria, and supporting evidence.
The earlier discussion documents are retired; Git history preserves the discussion.
The [implementation plan](implementation.md) owns the ordered, prompt-sized stages.
The migration is pending; recording these decisions has not changed application
behavior. Unrelated future work remains in the [separate backlog](future.md).
The native cutover and canonical documentation are implemented, with completion
evidence recorded in that plan. The final whole-roadmap acceptance audit remains
pending; implementation markers do not substitute for that verification.
Current behavior belongs in [Configuration](../config.md), [CLI Reference](../cli.md),
[Operations](../operations.md), and [native migration guidance](../consumers/native-migration.md).
Unrelated future work remains in the [separate backlog](future.md).
Notarius predates many modern PromptKit capabilities: the library grew out of
mechanics shared by Notarius and related applications. Historical duplication
@@ -36,7 +40,7 @@ adapters while those boundaries are already being replaced.
## Baseline And Dependency Target
At Notarius revision `12eeb6369e40746b2c18c55397a289a1e1b5908d`, the application
uses configuration version 5 and Go 1.27. Its dependencies include old-path
used configuration version 5 and Go 1.27. Its dependencies included old-path
PromptKit v0.12.0 and ConfigKit v0.5.0, new-path ConfigKit v1.2.0, go-yaml
v4.0.0-rc.6, and two external PromptKit provider catalogs.
@@ -56,9 +60,10 @@ Published tags and dependency manifests were verified, and the modules resolved
together without local replacements in an isolated consumer module. Maintained
composed-CLI and offline-preparation examples and focused message-hash,
configuration-handoff, and schema tests passed without live provider calls.
These checks verify the upstream combination, not the unfinished Notarius
migration. See the
[integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection)
Those checks established the upstream baseline; subsequent Notarius implementation
evidence is recorded in the plan, with final acceptance pending. See the
[current integration boundary](../integrations/pkg-commandkit.md) and
[integration version guidance](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md#module-selection)
and tagged [release notes][release], [migration guide][migration],
[format reference][formats], and [Go consumer guide][consumer].
@@ -152,8 +157,9 @@ can be refined against representative extraction and normalization during
implementation; ownership and placement are settled. U4 selects prompt roles and
guidance ownership below; U5 selects retry controls and the correction budget.
U6 selects strict-by-default handling and module-owned fallbacks below;
configuration precedence and fallback behavior are resolved. Implementation is
pending.
configuration precedence and fallback behavior are implemented. See
[Pipeline Internals](../internal/pipeline.md) and the plan's completed operation/
module work; final acceptance remains pending.
Retain the fixed `input -> chunk -> extract -> merge -> normalize -> output`
shape, ordered steps and generated references, typed artifact-family boundaries,
@@ -431,7 +437,8 @@ contracts. Retire private schema keys, registration records, hashes, and copied
identity/version/name metadata whose only consumers were adapters, checkpoints,
or reporting. No independent schema metadata system replaces them.
Implementation is pending. Verify native preparation of embedded and operator
Native preparation is implemented and covered by asset/operator-schema tests
recorded in the plan. Final verification must confirm embedded and operator
prompt definitions, shared-file paths, schema selection from embedded and external
roots, source-relative/inline selection, and complete request-contract replacement
where actually used. Missing or invalid schemas follow native preparation
@@ -519,8 +526,9 @@ apply U6's strict/permissive handling when no acceptable result is obtained.
Ownership, response contracts, and default profile behavior are resolved. Refine
exact template prose, correction IDs, and necessary operation-specific inputs
while implementing representative workflows. Implementation is pending; U5 selects
semantic budgets and U6 selects strict-by-default terminal handling and fallbacks.
within implemented module boundaries. The plan records producer/prompt/assessment
coverage; final verification remains pending. U5 selects semantic budgets and U6
selects strict-by-default terminal handling and fallbacks.
#### Execution And Assessment Flow
@@ -647,7 +655,8 @@ for semantic correction becomes `max_additional_turns`; native transport control
and prompt-owned structural customization cover their own concerns. Remove
non-LLM retry settings without a replacement generic allowance. Do not promise
equivalent total provider-attempt counts. U5 is resolved; U6 selects strict-by-default
handling and module-owned fallbacks. Implementation is pending.
handling and module-owned fallbacks. Native producer/assessment integration and
removal of outer retries are implemented; see the plan's completion evidence.
#### Terminal Outcomes And Module Fallbacks (U6 Resolved)
@@ -809,7 +818,8 @@ new shared limit, but its scope now includes lane completion. Do not automatical
translate a cross-backend ceiling into per-backend limits or preserve worker
inheritance/caps from that field. Provide a native limited-backend example with
usable queue capacity, without requiring operators to override the upstream
queue default. U7 is resolved; implementation remains pending.
queue default. U7 is implemented with focused worker/admission and assembled
coverage recorded in the plan; final acceptance remains pending.
### Accepted-Artifact Cache (U8 Resolved)
@@ -955,8 +965,8 @@ source partition to request-content-based plan reuse.
Remove checkpoint identities, dependency fingerprints, invocation-wide barriers,
recovery bookkeeping, and the separate canonical-plan lookup/publication policy.
Retain domain plan interpretation and materialization without retaining a second
cache mechanism. U8 is resolved; implementation remains pending using U1's
selected upstream hash capability.
cache mechanism. U8 is implemented using U1's selected upstream hash capability;
store, producer/plan, and assembled recovery coverage is recorded in the plan.
### Inspection And Execution Bookkeeping
@@ -1219,29 +1229,32 @@ support, applicability, and outcome distinctions.
## Decision Status
U1–U10 are resolved. There are no remaining open architectural or dependency
choices in this roadmap. Observer wiring, debug filenames, routine API placement,
and serialization details remain implementation work within the selected designs.
IDs retain continuity with the earlier roadmap. Implementation status and ordered
stages are tracked in the [implementation plan](implementation.md).
choices in this roadmap. Native loading/execution/commands, accepted-result reuse,
artifact-first reporting, capture, examples, and documentation are implemented.
Observer wiring, private debug representations, and routine API placement are
concrete implementation choices, not deferred architecture. The final assembled
acceptance/removal/link audit remains pending in the [implementation plan](implementation.md).
IDs retain continuity with the earlier roadmap.
**U1 resolved:** The [reviewed dependency set](#baseline-and-dependency-target)
selects PromptKit v0.24.0, ConfigKit v1.4.0, ckconfig v0.10.0, ckprompt v0.11.0,
and CommandKit v0.7.0. Native `MessageContentHash` satisfies the cache requirement;
typed result handoff and focused inspection enable one application-owned load.
The native resource layout, schema selections, and `OutputContractInput`
API are part of the selected target. Upstream combination checks
passed; assembled Notarius acceptance remains implementation work.
API are implemented. Upstream and focused assembled checks passed as recorded
in the plan; the final full acceptance audit remains pending.
**U2 resolved:** Ordinary embedded assets, prompt-declared output contracts,
native schema-source selection, and removal of duplicate schema/filesystem
machinery are selected in [the schema design](#prompt-assets-and-response-schemas-u2-resolved).
Implementation remains pending; U4 selects prompt roles and contracts, and U5
The native assets and schema selection are implemented with preparation and
operator-contract coverage in the plan. U4 selects prompt roles/contracts, and U5
selects native repair delegation and the application correction allowance.
**U3 resolved:** Typed stage boundaries, composition-root engine construction,
and the shared pipeline producer helper with module functions and a pipeline
assessment callback are selected in [the execution design](#module-execution-and-assessment-u3-resolved).
Concrete signatures remain implementation details within that ownership.
The typed operation/helper signatures are implemented within that ownership.
U4/U5 select prompt/guidance and retry behavior; U6 selects terminal
handling, configuration precedence, and module-owned fallbacks.
@@ -1249,8 +1262,8 @@ handling, configuration precedence, and module-owned fallbacks.
schemas, default profile behavior, validator-owned guidance, and complete
applicable-chain assessment are selected in
[the prompt and guidance design](#prompt-roles-and-correction-guidance-u4-resolved).
Exact template prose and operation-specific inputs remain implementation work
within that ownership. U5 selects budgets; U6 selects strict/permissive handling.
Native prompt pairs and operation-specific inputs are implemented within that
ownership. U5 selects budgets; U6 selects strict/permissive handling.
**U5 resolved:** `max_additional_turns` defaults to `2`, with binding over
pipeline precedence and explicit zero disabling correction. Native transient and
@@ -1269,7 +1282,8 @@ application default, including normalization; there are no module-declared
defaults. `mode` resolves module binding, then pipeline, then that default.
Chunking falls back to one whole-transcript chunk; spell extraction uses its empty
artifact, and normalization uses safe final-response groups or merged input.
Module-specific construction details remain implementation work.
Module-owned construction and terminal-mode coverage are implemented; see the
plan and [D&D guide](../internal/dnd.md#planning-scene-validation-and-fallback-limits).
**U7 resolved:** [One pipeline worker pool and native admission](#admission-and-pipeline-workers-u7-resolved)
replace the separate worker pools and application LLM scheduler.
@@ -1297,10 +1311,11 @@ fallbacks. Preserve run-specific domain artifact paths and schemas; retire index
manifest, and reporting-only sidecars and migrate consumers to documented paths.
Observer wiring and [debug filenames/layout](#inventory-and-depth) are explicitly
implementation choices, not unresolved architecture or stable debug contracts.
Implementation remains pending.
Implemented native observations/capture/publication and reporting tests are
recorded in the plan; final acceptance remains pending.
**U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight,
output, debug policy, and coordinated cutover sequencing are selected above.
output, and debug policy are implemented as selected above.
CommandKit belongs to the coordinated cutover. CLI compatibility is a non-goal;
existing artifact schemas remain domain contracts. Any actual artifact-format
change discovered during implementation needs an explicit compatibility decision,
@@ -1444,22 +1459,22 @@ tagged PromptKit links below preserve the reviewed baseline.
### Native Library Guidance
- [CommandKit consumer guide](../../../commandkit/docs/consumers/guide.md) and
[CLI conventions](../../../commandkit/docs/cli.md): module selection, native
- [CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md) and
[CLI conventions](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md): module selection, native
aliases/inputs, shared loaders, reporting modes, outcomes, and delivery failures.
- [ckconfig](../../../commandkit/integrations/ckconfig/README.md) and
[ckprompt](../../../commandkit/integrations/ckprompt/README.md): standard suites
- [ckconfig](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/README.md) and
[ckprompt](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/README.md): standard suites
supplied with application loaders and request builders.
- [ConfigKit v1.4.0 release notes][configkit-release]: typed result handoff and
focused inspection over the original load's provenance and resource contexts.
- [ckconfig v0.10.0][ckconfig-release] and [ckprompt v0.11.0][ckprompt-release]:
the selected integration compatibility and API changes.
- [Shared-loading guidance][consumer-loading] and the
[composed CLI example](../../../commandkit/integrations/ckprompt/examples/composed/main.go):
[composed CLI example](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/examples/composed/main.go):
composed rules, explicit bundled resources, one application result, native
engine construction, and focused standard scopes.
- [PromptKit consumer guide][consumer] and
[capacity behavior](../../../promptkit/docs/internal/capacity.md): native
[capacity behavior](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/internal/capacity.md): native
preparation/execution, continuation, observations, and admission.
### Audita Comparison
@@ -1494,5 +1509,5 @@ completion of Notarius's migration acceptance checks.
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[consumer-loading]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load
[configkit-release]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md
[ckconfig-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/docs/releases/v0.10.0.md
[ckprompt-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/docs/releases/v0.11.0.md
[ckconfig-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/docs/releases/v0.10.0.md
[ckprompt-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/docs/releases/v0.11.0.md