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

@@ -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