Verify the native cutover and complete the implementation roadmap

This commit is contained in:
2026-11-22 07:11:50 +00:00
parent 633ebd282f
commit 75444b8ef3
8 changed files with 102 additions and 31 deletions

View File

@@ -65,7 +65,7 @@ are unchanged: discovered has no holder; acquired requires `to`; lost and
consumed require `from`; transferred requires distinct non-`party` holders.
The only current downstream compatibility requirement is its registry handoff;
the normalized occurrence list is otherwise published for callers. See
[Configuration](../config.md#d-d-reference-slots) for the binding and
[Configuration](../config.md#dd-reference-slots) for the binding and
[JSON output](json-output.md) for publication.
See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact

View File

@@ -90,6 +90,6 @@ into the unchanged exact durable ID/name pair. The registry’s source reference
are never occurrence evidence. Unknown or ambiguous selections are rejected by
the occurrence contract. See the
[item-occurrence artifact](dnd-item-occurrence-artifacts.md) for that strict
wire contract, [Configuration](../config.md#d-d-reference-slots) for binding
wire contract, [Configuration](../config.md#dd-reference-slots) for binding
rules and validator selection, and the [JSON output contract](json-output.md)
for publication.

View File

@@ -80,7 +80,7 @@ are rejected rather than guessed or reassigned. The current transcript is the
only evidence source for an occurrence; registry evidence and provenance never
become occurrence evidence.
See [Configuration](../config.md#d-d-reference-slots) for the selectable slot
See [Configuration](../config.md#dd-reference-slots) for the selectable slot
and generated-handoff compatibility, [D&D module internals](../internal/dnd.md)
for implementation behavior, and the [JSON output contract](json-output.md)
for publication.

View File

@@ -86,7 +86,7 @@ Occurrence consumers receive names-only grounding; Notarius resolves the
selected canonical name and writes the unchanged exact durable ID/name pair.
Spells, combat turns, and the [enemy-event artifact](dnd-enemy-event-artifacts.md)
also receive names-only grounding for actor or subject display. None of these
projections supply later-artifact evidence. [Configuration](../config.md#d-d-reference-slots)
projections supply later-artifact evidence. [Configuration](../config.md#dd-reference-slots)
owns the `npc_registry` binding rules.
The [JSON output contract](json-output.md) defines publication, and
[D&D module internals](../internal/dnd.md) owns pipeline mechanics.

View File

@@ -17,7 +17,7 @@ in [Configuration](../config.md#references-and-ordered-handoffs).
| Base catalog | Embedded D&D 5e 2014 SRD catalog |
At most one overlay document may be bound. The maintained example is
[dnd-spell-catalog.json](../../examples/dnd-spell-catalog.json).
[spell-catalog.json](../../examples/dnd-complete/spell-catalog.json).
## Wire Shape

View File

@@ -7,8 +7,8 @@ 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 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.
All stages below are complete. Their markers record the landed work and checks;
Stage 46 records the completed whole-roadmap acceptance audit.
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
@@ -2235,6 +2235,79 @@ docs/examples for stale names while retaining meaningful migration/history menti
## Stage 46: Verify The Complete Native Cutover
**Status:** Complete. Audited every feature acceptance row against current
owning code, focused assertions, assembled/executable tests, and the checks below.
All earlier intermediate compilation/fixture blockers are closed: the full
default suite compiles and passes, including maintained examples and the concrete
module/validator/recovery tests previously recorded as blocked.
Final checks pass with Go `1.27.0`, declared dependencies, and `GOWORK=off`:
`go test ./...`, `go vet ./...`, a fresh temporary `go build -trimpath` executable,
and `git diff --check`. Repeated focused race checks pass for mixed ready jobs,
backend admission/cancellation, shared native capture, recorder/allocation, and
assembled recovery/fallback. Twenty-five direct offline executable checks pass
with the OpenRouter credential unset: help/version, all three completions,
configuration scopes/sources/explanation/diff, native resources/requirements,
minimal/complete/development/overlay preflight, and native JSON/YAML values.
Provider-boundary and real subprocess tests supply success/fallback formats,
stream separation, required-input/alias behavior, and post-publication failures
without paid inference.
The 252-file production inventory has fourteen native helper consumers (scene
planning, all ten extractors, three semantic normalizers), one direct native LLM
validator, and one composition-root engine constructor. Removed adapters,
schedulers, prompt/schema registries, generic retries, checkpoint/plan stores,
reporting sidecars, and copied accounting have no production consumers or tracked
legacy packages. Remaining test matches are explicit retired-input rejection,
unchanged legacy-data assertions, and deliberately selected native test budgets,
not pinned upstream defaults. Replaced the stale chunk-plan import-boundary fixture
with the current accepted-result store and removed its redundant special-case
guard; the existing generic framework boundary remains tested and unchanged.
Compared schemas and D&D codec files byte-for-byte with the inspected baseline:
no differences. Reviewed module selection/build metadata and all eleven selected
dependency notices against their module-cache release hashes; no replacement
modules or old-path kits/catalog dependencies remain. Successor ADR changes alter
earlier status links only, preserving accepted bodies; releases/archives remain
historical. No output/cache/debug data was migrated or deleted.
The read-only documentation check covers all 84 Markdown files, excluding literal
code-block examples from link interpretation. Current local destinations/anchors
resolve after fixing four stale D&D configuration anchors and the moved catalog
example link. Seven links in historical release notes intentionally refer to
retired checkout paths/headings; those records were preserved rather than
rewritten. Dated sibling comparison material remains evidence, not a current
implementation dependency. Selected upstream guide/source destinations were
checked against the exact module sources during the integration audit.
Acceptance evidence was checked at these owners, not inferred from test names
or a successful build alone:
| Feature acceptance row | Current evidence |
| --- | --- |
| Configuration/assets | [Typed definition/handoff](../../internal/core/config/native_settings_test.go), [main-relative source/peer/replacement cases](../../internal/cli/native_load_test.go), [operator schema execution](../../internal/cli/native_schema_load_test.go), and [every embedded declaration prepared](../../assets/package_test.go). |
| Commands/loaders | [Lazy native app/scopes/diff](../../internal/cli/application_test.go), [run inputs and shared roles](../../internal/cli/pipeline_run_test.go), [native overrides](../../internal/cli/execution_overrides_test.go), and [real executable routes](../../internal/cli/native_process_test.go). |
| Preflight/inspection | [Known/default/dynamic resources and partial profiles](../../internal/preflight/preflight_test.go) and [one-load offline commands without execution inputs/storage](../../internal/cli/pipeline_commands_test.go). |
| Domain workflow | [Spell pipeline contracts](../../internal/modules/integration/), [fresh typed normalization](../../internal/modules/dnd/normalize/itemregistry/native_execution_test.go), [candidate isolation/whole chains](../../internal/framework/pipeline/candidate_assessment_test.go), and [runner outcomes](../../internal/framework/pipeline/runner_operation_test.go). |
| Prompt/guidance contracts | [Native paired assets](../../assets/package_test.go), [correction defaults versus explicit selections/history](../../internal/framework/pipeline/producer_test.go), [complete ordered findings](../../internal/framework/pipeline/candidate_assessment_test.go), and [real combat judgment guidance](../../internal/modules/dnd/extract/scenedescriptions/native_execution_test.go). |
| Retry controls | [Presence/default/zero/precedence](../../internal/framework/pipeline/validation_policy_test.go), [loaded controls](../../internal/core/config/validation_policy_contract_test.go), [early/final-turn acceptance](../../internal/framework/pipeline/producer_test.go), and absent bundled repair counts in native declarations. |
| Non-LLM failure handling | [One deterministic production/error path](../../internal/framework/pipeline/runner_operation_test.go), direct generic/Seriatim modules, and [rejection of retired controls](../../internal/core/config/operational_document_test.go). |
| Continuation/failures | [Nil-error failed status, no prior recovery, native timeout/caller distinction](../../internal/framework/pipeline/producer_test.go), [unassessed undelivered/callback failures](../../internal/framework/pipeline/native_capture_test.go), and [direct validator failures](../../internal/modules/dnd/validate/scenedescriptions/combat_semantics/native_execution_test.go). |
| Strict/permissive outcomes | [Terminal handling](../../internal/framework/pipeline/producer_outcome.go), [runner counts/eligibility](../../internal/framework/pipeline/runner_operation_test.go), [whole-source plan fallback](../../internal/modules/dnd/chunk/scenes/chunker_test.go), and [final-only valid scene fallback/failure](../../internal/modules/dnd/extract/scenedescriptions/native_execution_test.go). |
| Admission/workers | [Mixed ready jobs, independent limits, serial/nested liveness, capacity modes, cancellation release](../../internal/framework/pipeline/ready_jobs_test.go), [stable ordering/draining](../../internal/framework/pipeline/runner_concurrency_test.go), and [nested same-backend assessment](../../internal/framework/pipeline/native_assessment_test.go). |
| Accepted-artifact cache | [Initial-key late applied-value writes, frozen handles, settings hits/content misses, terminal exclusions](../../internal/framework/pipeline/producer_cache_test.go), [typed usability and warning publication](../../internal/framework/pipeline/runner_cache_test.go), and [assembled recovery/actual dependents](../../internal/cli/recovery_contract_test.go). |
| Chunk-plan reuse | [Final plan key, current-source rematerialization, no semantic reassessment, changed-message partitions, and deterministic exclusion](../../internal/framework/pipeline/chunk_plan_cache_test.go). |
| Cache controls/migration | [Loaded roots](../../internal/core/config/operational_document_test.go), [resolved invocation precedence](../../internal/framework/pipeline/validation_policy_test.go), [raw atomic store/modes/legacy retention](../../internal/framework/artifactcache/filesystem_test.go), and [failed refresh/qualified lineage](../../internal/cli/recovery_contract_test.go). |
| Output/outcomes | [Domain-only encoder](../../internal/modules/generic/output/json/encoder_test.go), [native formats/counts/quiet/delivery/capture failures](../../internal/cli/run_result_command_test.go), [executable fake HTTP formats](../../internal/cli/native_process_test.go), and unchanged intrinsic schema/codec comparison. |
| Execution observations | [Once-only native enrollment, unknown usage, parent identity, result-less failures, and no hit executions](../../internal/framework/pipeline/native_capture_test.go) and [assembled native group facts](../../internal/cli/recovery_contract_test.go). |
| Debug controls/lifecycle | [Supplied empty/boolean selection](../../internal/cli/run_debug_test.go), [start-time relative latest/allocation failure](../../internal/core/debugbundle/bundle_test.go), [one incremental recorder/retained causes](../../internal/framework/debug/recorder_test.go), and [publication/capture ordering](../../internal/cli/run_result_command_test.go). |
| Debug evidence | [Full native snapshots/exchanges and hit/failure availability](../../internal/framework/pipeline/native_capture_test.go), [operation/normalization inputs](../../internal/framework/pipeline/operation_capture_test.go), [fixed mappings/proposals](../../internal/modules/dnd/normalize/itemregistry/native_execution_test.go), and [exact secret-aware projection without content rewriting](../../internal/cli/run_capture_test.go). |
| End-to-end migration | [Maintained minimal/complete/development workflows and explicit shared references](../../internal/cli/example_contract_test.go), [ordered failure/fix/reuse and fallback](../../internal/cli/recovery_contract_test.go), native executable checks, and current [migration guidance](../consumers/native-migration.md). |
All required implementation, documentation, and verification work is complete.
No live-model quality claim, real credential, release, tag, push, new permanent
gate, or deferred backlog feature was needed or introduced.
**Goal:** finish only when the full end state is supported by current evidence.
**Inspect/change:** the assembled repository, feature roadmap acceptance matrix

View File

@@ -13,9 +13,10 @@ 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 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.
The native cutover, canonical documentation, and final whole-roadmap acceptance
audit are complete. The implementation plan records the owning evidence and
successful assembled checks; no live-model quality or release-publication claim
is implied.
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).
@@ -61,7 +62,7 @@ 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.
Those checks established the upstream baseline; subsequent Notarius implementation
evidence is recorded in the plan, with final acceptance pending. See the
evidence and final acceptance are recorded in the plan. 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],
@@ -159,7 +160,7 @@ 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 implemented. See
[Pipeline Internals](../internal/pipeline.md) and the plan's completed operation/
module work; final acceptance remains pending.
module work and completed final acceptance evidence.
Retain the fixed `input -> chunk -> extract -> merge -> normalize -> output`
shape, ordered steps and generated references, typed artifact-family boundaries,
@@ -438,8 +439,8 @@ identity/version/name metadata whose only consumers were adapters, checkpoints,
or reporting. No independent schema metadata system replaces them.
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
recorded in the plan. Final verification confirmed 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
behavior. No new schema check requiring synthetic requests is added to offline
@@ -527,7 +528,7 @@ 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
within implemented module boundaries. The plan records producer/prompt/assessment
coverage; final verification remains pending. U5 selects semantic budgets and U6
coverage and successful final verification. U5 selects semantic budgets and U6
selects strict-by-default terminal handling and fallbacks.
#### Execution And Assessment Flow
@@ -730,8 +731,8 @@ Record why fallback was used and expose that qualification in the ordinary
completion report, even when diagnostic verbosity hides individual warnings.
Use the same application outcome for reporting and optional debug detail. Keep
conversation state in process, outside ordinary artifact/cache payloads;
explicitly requested detailed debug is separate. U6 is resolved; module-specific
construction remains implementation work.
explicitly requested detailed debug is separate. U6 and module-specific
construction are implemented; the plan records terminal-mode and domain coverage.
### Admission And Pipeline Workers (U7 Resolved)
@@ -819,7 +820,7 @@ 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 implemented with focused worker/admission and assembled
coverage recorded in the plan; final acceptance remains pending.
coverage and final acceptance recorded in the plan.
### Accepted-Artifact Cache (U8 Resolved)
@@ -1232,8 +1233,8 @@ U1–U10 are resolved. There are no remaining open architectural or dependency
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).
concrete implementation choices, not deferred architecture. The completed assembled
acceptance/removal/link audit is recorded in the [implementation plan](implementation.md).
IDs retain continuity with the earlier roadmap.
**U1 resolved:** The [reviewed dependency set](#baseline-and-dependency-target)
@@ -1242,7 +1243,7 @@ and CommandKit v0.7.0. Native `MessageContentHash` satisfies the cache requireme
typed result handoff and focused inspection enable one application-owned load.
The native resource layout, schema selections, and `OutputContractInput`
API are implemented. Upstream and focused assembled checks passed as recorded
in the plan; the final full acceptance audit remains pending.
in the plan, including successful final full acceptance.
**U2 resolved:** Ordinary embedded assets, prompt-declared output contracts,
native schema-source selection, and removal of duplicate schema/filesystem
@@ -1312,7 +1313,7 @@ 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.
Implemented native observations/capture/publication and reporting tests are
recorded in the plan; final acceptance remains pending.
recorded with successful final acceptance in the plan.
**U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight,
output, and debug policy are implemented as selected above.

View File

@@ -274,15 +274,15 @@ func TestImportBoundaryRules(t *testing.T) {
wantError: true,
},
{
name: "chunkplan production may import framework",
filename: "internal/framework/chunkplan/store.go",
sourcePackage: "chunkplan",
name: "artifact cache production may import framework",
filename: "internal/framework/artifactcache/filesystem.go",
sourcePackage: "artifactcache",
importPath: internalImportPrefix + "framework/contracts",
},
{
name: "chunkplan production cannot import modules",
filename: "internal/framework/chunkplan/store.go",
sourcePackage: "chunkplan",
name: "artifact cache production cannot import modules",
filename: "internal/framework/artifactcache/filesystem.go",
sourcePackage: "artifactcache",
importPath: moduleImportPrefix + "dnd",
wantError: true,
},
@@ -424,9 +424,6 @@ func validateImport(filename string, sourcePackage string, importPath string) er
if strings.HasPrefix(filename, "internal/core/source/") && strings.HasPrefix(importPath, moduleImportPrefix) {
return importBoundaryViolation(filename, importPath, "core/source production code must not import framework or module implementations")
}
if strings.HasPrefix(filename, "internal/framework/chunkplan/") && strings.HasPrefix(importPath, moduleImportPrefix) {
return importBoundaryViolation(filename, importPath, "framework/chunkplan production code must not import module implementations")
}
if strings.HasPrefix(filename, "internal/framework/") || strings.HasPrefix(filename, "internal/core/") {
return importBoundaryViolation(filename, importPath, "core and framework production code must not import module implementations")
}