2026-11-21 22:24:16 +00:00
# Native Migration Implementation Plan
## Purpose And Execution Rules
Implement the complete target in [Native PromptKit And CommandKit Migration ](promptkit.md ).
That feature roadmap owns product choices, defaults, ownership, and acceptance
2026-11-21 22:39:39 +00:00
semantics. This document owns execution order and stage completion. Completion
markers below record finished stages. The inspected application baseline is Notarius commit
2026-11-21 22:24:16 +00:00
`b3664d587914b1d7b0377f25fa377b57fa97c815` ; its recent roadmap commits have not
implemented the migration.
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
may leave callers, tests, or packages unbuildable. Do not spend prompts preserving
intermediate compilation with compatibility adapters, duplicate loaders, aliases
for retired inputs, or replacement completion abstractions. Final compilation,
behavior, and documentation must satisfy the entire target. The native `run`
alias is a selected new interface, not a legacy forwarding implementation.
Before each stage, read `docs/development.md` , follow its applicable policy links,
and inspect the stage's named source and focused tests. Prefer the codebase
knowledge graph for code discovery. Use the selected upstream public APIs and
maintained examples, not old dependency APIs inferred from current Notarius code.
Keep code and tests scoped to that stage. Commit each completed nonempty unit
under the agent policy, accurately recording any checks blocked by not-yet-migrated
callers. Do not claim a blocked test passed. Later stages own the corresponding
integration; do not omit their work because an earlier package check was blocked.
The validation commands below are focused checks, not additional permanent
release gates. Run them when their dependencies can compile; otherwise inspect
the affected code, record the concrete dependency blocker, and continue the
sprint. Stage 46 requires the complete assembled repository to pass. Test with
real kits and a fake `promptkit.LLMClient` or local fake HTTP provider, as appropriate.
No ordinary test requires real credentials, a production transcript, paid inference,
or an external service. Dependency acquisition is separate from offline testing.
No stage authorizes a release, push, tag, deployment, rewrite of published history,
or changes to sibling repositories. Do not delete legacy cache data on disk.
Do not add security restrictions, filesystem permission policy, schema changes,
backend limits, retry caps, or public reporting guarantees beyond the feature
roadmap. Retain deterministic domain correctness and the existing intrinsic
artifact schemas; retire only machinery and contracts the roadmap replaces.
## Settled Design And Implementation Boundaries
- Use PromptKit `v0.24.0` , ConfigKit `v1.4.0` , CommandKit `v0.7.0` , ckconfig
`v0.10.0` , and ckprompt `v0.11.0` from their `go.maximumdirect.net` paths.
Keep the Go consumer minimum `1.27.0` ; use stable go-yaml v4 and selected
transitive versions from the feature roadmap.
- Version 6 is the sole application configuration version. One application-owned
ConfigKit result supplies native PromptKit settings, engine construction, and
both inspection scopes. Composition-root loaders live in `internal/cli` .
- Use ordinary `assets` embedding, native source contexts, and
`promptkit.collections.notarius` . Prompt declarations own default output
contracts. PromptKit owns schema preparation and structural repair.
- Keep typed stage interfaces. Model-executing code receives the shared native
engine. A small producer helper in `internal/framework/pipeline` accepts ordinary
module request/interpretation/correction/fallback functions and the pipeline's
typed assessment callback. No new LLM service interface or execution-plan language.
- The pipeline assesses each initial/revised candidate once through the whole
applicable validator chain. Native coordination owns growing conversation
history and turn iteration. `max_additional_turns` resolves binding, pipeline,
then `2` ; explicit zero disables semantic correction. Native transient and
structural-repair defaults remain unspecified by Notarius.
- `mode` resolves producer binding, pipeline, then `strict` . A permissive fallback
is qualified output, not ordinary acceptance. Cancellation stops without fallback.
Fallback and affected dependent work skip cache lookup and storage.
- `concurrency.workers` , default `64` , bounds one shared ready-job pool for
extraction and lane completion. Native backend admission is independent; no
injected backend limits or replacement global LLM ceiling.
- Cache only final accepted artifacts/plans under the initial prepared
`MessageContentHash` . The key has no extra dimensions. Hits get ordinary decode/
usability checks and no new semantic assessment. `auto` , `bypass` , and `refresh`
use the roadmap's exact precedence; cache I/O is best effort.
- Publish domain artifacts at their existing run-specific paths. Report one small
native completion value, including a positive `fallback_count` when applicable.
Retire required manifests, receipts, index files, and reporting sidecars.
- Use one invocation `ExecutionGroup` , native observations, and optional convenient
debug evidence. Detailed debug is not a public serialization contract. Preserve
native credential omissions and ConfigKit secret-aware inspection; do not add
heuristic content rewriting.
Implementation details such as private helper names and debug filenames may be
refined without changing these choices. Put application outcome/callback types
where typed stage contracts can use them without a `contracts -> pipeline` import
cycle. Do not pass pipeline collaborators through hidden process globals. Modules
still receive no physical roots or CommandKit reporters.
### Domain Fallback Construction
Use this construction guidance in the corresponding module stages, under U6:
| Producer | Supported fallback construction |
| --- | --- |
| D&D scene chunker | One plan entry covering the complete source in document order; use normal materialization and source-addressing rules. |
| Spell, registry, occurrence, combat-turn, and enemy-event extraction | The family's codec-valid empty collection, retaining required top-level shape and any deterministically required context. No invented entity or event. |
| Scene-description extraction | Use the final usable candidate only when it satisfies intrinsic shape, source identity, and downstream consumption invariants. Its artifact requires at least one scene, so an empty list is not a valid fallback. If no such final candidate exists, fail fallback construction; do not fabricate kind/title/summary or change the schema. |
| Semantic registry normalization | Apply compatible safe groups from the final usable proposal afresh to fixed originals, preserving other originals separately. With no usable final proposal, use the deterministic merged input. |
| Deterministic merge/normalization | Reuse suitable incoming/merged data only when the module can construct an invariant-preserving result. An operation error or inability to construct that result fails normally; there is no generic retry. |
Necessary fallback checks belong to the module; they do not rerun the configured
ordinary validator chain. This table does not promise that every operation can
recover from every failure. Insufficient reconciliation candidates can remain
an ordinary deterministic success; exceeding a required semantic preparation
limit is not silently presented as normally validated model work.
## Stage 1: Select Dependencies And Update Their Notices
2026-11-21 22:39:39 +00:00
**Status:** Complete. Selected releases resolve together with `GOWORK=off go list
-m all`; Go remains ` 1.27.0`, with no replacements. Updated commit-pinned notices
for the selected kits and changed runtime dependencies. `git diff --check` passed.
Application API migration remains assigned to the subsequent stages; no application
compilation claim is made here.
2026-11-21 22:24:16 +00:00
**Goal:** make the reviewed upstream APIs available without a compatibility patch.
**Inspect/change:** `go.mod` , `go.sum` , `docs/oss/attribution.md` ; selected kit
`go.mod` , `COPYRIGHT` , `LICENSE` , and release notes. Read the roadmap's dependency
and evidence sections. Consult the composed CLI example under
`../commandkit/integrations/ckprompt/examples/composed/` as a reference, not a new
Notarius dependency.
**Work:** add the five selected vanity-path dependencies, retain Go `1.27.0` ,
and let Go resolve the reviewed stable YAML/jsonschema versions. Convert import
paths as their callers migrate; do not patch upstream or keep permanent `replace`
directives. Old-path dependencies may remain temporarily while old callers exist;
Stage 35 removes them. Add/update factual attribution with exact selected upstream
commit links and required license material under the OSS policy.
**Acceptance:** all five selected modules resolve together using declared
versions; no sibling workspace substitutes for a release. Notices describe actual
incorporated dependencies. API incompatibilities are identified as migration work,
not hidden by shims.
**Validation:** `GOWORK=off go list -m all` , inspect `git diff -- go.mod go.sum
docs/oss/attribution.md`, and ` git diff --check`. Do not require the old application
to compile against the new APIs yet.
## Stage 2: Introduce The Native Version 6 Configuration Definition
2026-11-21 22:42:35 +00:00
**Status:** Complete. Native settings and composed rules retain the original
application result for direct engine handoff. Version 6 numeric/string loads,
version 5 rejection, application origins, native inheritance, imported message
origins, and secret-aware inspection are covered by the passing
`GOWORK=off go test ./internal/core/config` . `git diff --check` passed.
The old CLI compile check is blocked by old-path ConfigKit importing the removed
`go.yaml.in/yaml/v4/plugin/limit` ; later caller migration and dependency removal
own that integration. Source assembly remains assigned to Stage 5.
2026-11-21 22:24:16 +00:00
**Goal:** preserve one typed ConfigKit load and its original result evidence.
**Inspect/change:** `internal/core/config/document.go` , `load.go` ,
`loaded_config.go` , `document_normalizer.go` , `operational_document.go` , and their
definition/loading tests; PromptKit `Configure` , `Settings` , and `NewFromConfig` .
**Work:** replace `PromptKitDocument` with native `promptkit.Settings` at
`yaml:"promptkit"` , compose the application definition with `promptkit.Configure` ,
and select application version 6 only. Retain the native `configkit.Result` for
handoff and inspection rather than reserializing settings. Preserve application
pipeline normalization, ConfigKit discovery/import/version semantics, and
source-relative application paths. Remove `profile_file` , `profile_dir` , and
`local_backend` consumption; add no separate PromptKit configuration file setting.
Runtime-only client options belong in native `RuntimeConfig` , and invocation
transient-retry overrides use ckprompt's native request override. Do not recreate
the removed configuration wrapper to hold library behavior.
**Acceptance:** `version: 6` and its native string equivalent follow ConfigKit's
version handling; version 5 has no compatibility translation. PromptKit rules,
including resource identity and secret marking, participate in the same definition.
The whole result can be supplied to `NewFromConfig` without another load.
**Validation:** focused `go test ./internal/core/config` ; test typed `/promptkit`
handoff and unchanged source-origin semantics. Source assembly is completed in
Stage 5; no fake result or YAML round-trip is an acceptable substitute.
## Stage 3: Resolve The New Application Controls
2026-11-21 22:49:41 +00:00
**Status:** Complete. Added omission-aware producer controls and final resolution,
invocation-wide cache precedence, independent positive workers, source-relative
state roots, and explicit-empty debug behavior. Removed the superseded application
retry/repair/failure-policy and nested cache configuration surfaces. Updated
focused loading, inheritance, directory, and resolution coverage.
The isolated cache-root test and `git diff --check` pass. Full focused package
tests are blocked by not-yet-migrated pipeline preparation, attempts, and debug
callers of removed fields/types (for example `ValidationPolicy` and `Retries` ),
plus old-path ConfigKit's removed YAML `plugin/limit` import. Their scheduled
caller migration and final whole-tree validation remain required; these tests
are not claimed as passing.
2026-11-21 22:24:16 +00:00
**Goal:** define the selected budgets, modes, workers, and state paths once.
**Inspect/change:** configuration document/runtime conversion and validation,
`internal/framework/pipeline/profile.go` , `options.go` , `validation_policy.go` ,
and policy-resolution tests.
**Work:** add omission-aware pipeline/binding `mode` , `max_additional_turns` , and
`cache` ; root `cache_directory` ; and positive `concurrency.workers` . Resolve the
roadmap's precedence/defaults, including explicit zero turns, strict normalization,
and the CLI cache override taking precedence over every binding. Remove producer/
validator `retries` , application structural-repair fields, failure-category
policies, nested legacy cache settings, `total_llm` , and extraction-worker coupling.
Use native source origins for nonempty config paths. Preserve explicit empty debug
directory as capture-disabled; omitted debug root is `/tmp/notarius-debug` .
Omitted/empty cache root uses `os.UserCacheDir()/notarius` ; a configured root is exact.
**Acceptance:** resolved operations contain final controls rather than repeating
inheritance at execution. Tests distinguish omission, zero, and explicit values.
There are no module-declared permissive defaults, new maximum worker/turn caps,
backend settings derived from workers, or replacement non-LLM retry options.
**Validation:** focused configuration and pipeline resolution tests, including
binding-over-pipeline mode/turn/cache selection, invocation cache selection,
worker positivity, and explicit-empty path behavior.
## Stage 4: Convert Embedded Initial Resources And Schema Declarations
2026-11-21 22:52:46 +00:00
**Status:** Complete. Converted all 16 initial/validator/reconciliation prompt
declarations and the extraction profile to native identified lists. The embedded
`assets/notarius.yml` imports them into the `notarius` collection with its own
filesystem-rooted schemas. Real shared-file paths replace virtual mounts; schema
bytes, prose, message order, and cache hints are unchanged. Native offline loading
and preparation of every declaration pass in `GOWORK=off go test ./assets` ,
including exact loaded-schema comparisons and selected profile defaults.
`git diff --check` passed. Module caller/manifest migration remains in its assigned
later stages; no intermediate whole-tree compilation claim is made.
2026-11-21 22:24:16 +00:00
**Goal:** native declarations become the only default prompt/schema assembly.
**Inspect/change:** existing `assets/**/prompts/prompt.yaml` ,
`assets/dnd/profiles/dnd-extraction.yaml` , `assets/package.go` , and old prompt/schema
manifest tests. Inspect all current content-file paths before changing them.
**Work:** convert initial producer, validator, and generic reconciliation prompts
to native identified lists in the `notarius` collection, retaining local IDs and
using qualified prompt/profile references. Add one ordinary embedded native source
that imports the resources and declares the collection schema root from the assets
filesystem context. Use real relative paths to shared files, not `sharedassets`
mounts. Set each prompt's response format, validation mode, and schema selection;
remove explicit `repair_attempts` . Keep the default extraction profile's current
model, timeout, service tier, unset reasoning, and unqualified `openrouter` backend.
Remove old resource-version selectors; no new PromptKit version header is needed.
**Acceptance:** every existing LLM-facing schema is still self-contained and
selected from its actual asset location. Intrinsic artifact schemas remain
unchanged. Shared prose/order/cache controls are preserved except for deliberate
conversation wording changes made with each correction pair later. The assets
Go package remains a content-only leaf, without a behavioral registry.
**Validation:** native ConfigKit load plus PromptKit construction/preparation with
fake request inputs; cover real shared-file paths and the embedded schema root.
Do not add prose snapshots or fixed shared-prefix-length tests.
## Stage 5: Assemble One Application Load And Native Engine
2026-11-21 22:56:14 +00:00
**Status:** Complete. Added invocation-owned selection/result/engine reuse and
one native layered application load with bundled, embedded, and strict peer
operator underlays. Native main-relative imports anchor optional companions to
the selected main source; explicit-empty configuration paths fail. Added real
temporary-file coverage for selection differences, companions/conflicts,
inheritance/imports, captured messages, selective resource replacement, and native
schema contexts. `git diff --check` and the existing native asset tests pass.
CLI/config test execution remains blocked by the recorded legacy YAML import
and pipeline callers of retired policy/retry types. Old command-handler tests
also await the command replacement in Stage 6; no blocked test is claimed passing.
Native standard-command and run wiring remain in their assigned later stages.
2026-11-21 22:24:16 +00:00
**Goal:** runtime and standard commands consume the same selected resources.
**Inspect/change:** `internal/cli/configkit_load.go` ,
`internal/core/config/loaded_config.go` , new focused CLI loader/engine files, and
old `internal/framework/llm` source assembly. Read upstream shared-loading guidance.
**Work:** select the actual application main source using the existing explicit/
environment/native discovery policy. Reject explicitly empty `--config` rather
than discovering another file. Assemble bundled OpenRouter, embedded Notarius,
and operator companions as ordered underlays of the one application load.
Discover optional `prompts.yml` and recursive `.yml` /`.yaml` files in `prompts/`
beside that selected main source, in one strict operator peer group. Preserve
native imports/destinations/source contexts; do not fall back to the working
directory or hide malformed operator sources. Main imports, overlay, and explicit
overrides retain native precedence. Construct `NewFromConfig` from the successful
whole result, with runtime-only options, without callbacks/loading happening again.
**Acceptance:** invocation-owned reuse distinguishes complete selections,
including overlay/overrides and the two sides of `config diff` . Changes to source
files after capture do not mutate an engine. Shared loaders create no run storage.
No duplicate asset registry, settings reparse, or persistent loader cache remains
on the new path.
**Validation:** focused CLI/config tests using real temporary files: absent
companions, file+directory conflicts, selective replacement, native inheritance,
imports, source-relative messages, embedded/external schema roots, inline/
source-relative schemas, and missing-file behavior after root replacement.
## Stage 6: Install CommandKit And The Standard Configuration Suite
2026-11-21 22:59:46 +00:00
**Status:** Complete. Added the lazy native application constructor, generated
help/version and Bash/Zsh/Fish completion, and shared `app` /focused `promptkit`
ckconfig scopes with native overrides and comparison. The executable supplies
the release-linked build identity directly. Removed the manual configuration
handlers, dispatcher, and assembled help. Added focused built-in, scope/report,
explicit-empty selection, and diff-status tests.
Build-info/asset tests and `git diff --check` pass. CLI tests and executable
subprocess checks remain blocked by the previously recorded legacy YAML import
and not-yet-migrated pipeline consumers; final assembled verification must run
them. PromptKit-suite convenience aliases are installed with that suite in Stage 7.
2026-11-21 22:24:16 +00:00
**Goal:** one native application constructor replaces manual command plumbing.
**Inspect/change:** `cmd/notarius` , `internal/cli/run.go` , `configkit_commands.go` ,
`configkit_load.go` , `internal/buildinfo` , and new focused command-composition files.
**Work:** declare application identity, native help/version, Bash/Zsh/Fish completion,
and presentation through CommandKit. Install ckconfig scopes named `app` and
`promptkit` , using the shared result and native focused-subtree adapter where
appropriate. Install native validation/show/sources/explain/diff and convenience
aliases. Preserve native causes/outcome classification and supplied-value inputs.
Construction itself performs no configuration load, engine build, or storage I/O.
Retire the old configuration command handlers rather than keeping two surfaces.
**Acceptance:** help/version/completion work without any config or API key;
configuration commands use native report values and the same load evidence.
`config diff` does not accidentally compare a memoized selection to itself.
Release-linked version identity remains available at the real executable boundary.
**Validation:** focused CLI tests and representative subprocess invocations for
help/version/completion, one app-scope explanation, one focused PromptKit report,
and diff status `3` . Test semantics, not entire upstream help text.
## Stage 7: Install ckprompt And Reusable Run Overrides
2026-11-21 23:02:57 +00:00
**Status:** Complete. Installed native resource listings/inspection, requirements,
request validation/preparation, namespace selection, and explicit smoke operations
with ckprompt's builders and scoped convenience aliases. Added reusable native
profile/session/execution flag input and request application, including omitted
versus empty reasoning and native transient-retry overrides. Removed the copied
CLI profile-inspection path and replaced its tests with native command coverage.
The isolated real-kit override test, build-info/asset tests, and
`git diff --check` pass. Assembled CLI inspection/preview/fake-provider smoke tests
remain blocked by the recorded legacy dependency/caller compilation blockers;
their results are not claimed passing. Full pipeline binding remains Stage 33.
2026-11-21 22:24:16 +00:00
**Goal:** adopt the full selected native diagnostics and execution input suite.
**Inspect/change:** CLI composition from Stage 6, old `promptkit_profiles.go` , and
ckprompt's maintained composed example and public integration declarations.
**Work:** use `FromEngine` , request validation/preparation, smoke integration, and
the shared loaders to install all selected resource listings/inspection,
requirements, preview, and explicit smoke checks. Use upstream request builders
unless an application callback is genuinely needed; preserve supplied inputs.
Expose ckprompt's reusable profile/session/execution flags for pipeline run-wide
overrides, carrying omission and explicit empty reasoning distinctly. Use native
`--llm-profile` and `--llm-session-id` ; remove copied profile inspectors and
effective-parameter reports. Do not build new native-command wrappers or probes.
**Acceptance:** standard inspection needs no transcript/provider call. Concrete
request validation/preview performs native request preparation; smoke work is
explicit only and preserves supported/applicable/result distinctions. The reusable
override value can reach every producer, validator, and correction without
mutating captured configuration. Native transient retries replace the former
application-specific override machinery.
**Validation:** focused CLI tests with a fake provider: listings, partial profile,
explicit preview inputs, no implicit smoke, supplied false/zero/empty values, and
one explicit smoke outcome. Full pipeline binding is completed in Stage 33.
## Stage 8: Define Typed Producer Collaboration And Resource Dependencies
2026-11-21 23:12:01 +00:00
**Status:** Complete. Construction now passes the shared native engine. Typed
producer requests carry explicit assessment callbacks, resolved controls, native
execution options, and incoming reuse eligibility; results carry accepted/fallback
disposition, reason, and eligibility without a completion facade. Validators receive
native execution options only. Static prompt-ID dependencies replace correction
transport capabilities and are copied through registration, resolution, and
preparation. Exact artifact type, codec/evidence, option, and reference checks remain.
Added registry callback/native-option, incompatible-type, dependency-isolation, and
preparation coverage. Contracts tests/vet and `git diff --check` pass. Pipeline
tests remain blocked by old ConfigKit's removed YAML `plugin/limit` import; its
production build also encounters unmigrated policy/normalize-retry consumers.
Their scheduled migration remains required; blocked tests are not claimed passing.
2026-11-21 22:24:16 +00:00
**Goal:** expose only the application contracts required by native execution.
**Inspect/change:** `internal/framework/contracts/{contracts,typed_pipeline}.go` ,
pipeline construction/registries/preparation, module specifications, and typed
registration tests.
**Work:** replace `ModuleDependencies.LLM` with the shared native engine for
model-executing modules. Add small typed operation collaboration/outcome types
for the pipeline assessment callback, accepted/fallback disposition, fallback
reason, and reuse eligibility. Pass native execution overrides/observers without
creating another completion request/result facade. Adapt typed method arguments
or call options to carry the assessment callback explicitly without an import
cycle. Add static initial/correction prompt dependencies using the same IDs as
request builders; keep dynamic selection runtime-checked. Validators remain
assessment modules, not producer-loop participants.
**Acceptance:** artifact exact-type checks, codec/evidence compatibility, and
module option/reference validation remain intact. New dependency declarations
are small ID selections, not asset manifests, schema registries, or fingerprints.
Pure domain types and deterministic helpers acquire no PromptKit dependency merely
because surrounding producers do.
**Validation:** focused contracts/registry/preparation tests, including incompatible
typed registrations and statically declared correction dependencies. This stage
need not migrate every module caller.
## Stage 9: Centralize Candidate Assessment And Terminal Disposition
2026-11-21 23:20:17 +00:00
**Status:** Complete. Replaced retrying validator execution and the producer
attempt state machine with one ordered assessment path and strict/permissive
terminal handling. Typed and materialized-chunk assessors give each validator
detached candidate/context views and preserve rejection guidance separately from
failed/unavailable assessments and their native causes. Guidance aggregation has
no hard-coded correction assignment. Fallback construction runs once without
ordinary revalidation, never on caller cancellation, and cannot claim acceptance
or reuse eligibility. Added complete-chain, revised/unchanged candidate, isolation,
guidance-contract, unavailable-assessment, timeout, and cancellation coverage.
Contracts tests/vet, isolated terminal-mode tests, and `git diff --check` pass.
Full pipeline tests remain blocked by the recorded old ConfigKit YAML import;
production compilation also awaits migration of runner/debug/diagnostic consumers
of removed attempt/report types. No blocked test is claimed passing; runner and
native continuation integration remain assigned to Stages 10– 11.
2026-11-21 22:24:16 +00:00
**Goal:** use one complete assessment path for initial and revised candidates.
**Inspect/change:** `validation_executor.go` , `validation_policy.go` ,
`producer_attempts.go` , typed validator execution, and validation-isolation tests.
**Work:** remove the validator invocation retry loop. Invoke each applicable
validator once per candidate through its public boundary, in configured order,
with immutable candidate views. Collect all rejections/guidance despite earlier
rejections; distinguish reject, fail, and unavailable/skip. Preserve actionable
`CorrectionGuidance` separately from reason codes and operator prose. Expose one
typed assessor to the producer helper. Apply resolved strict/permissive handling
to terminal nonacceptance; unavailable assessment is not a semantic defect.
Fallback construction checks remain module-owned, outside ordinary revalidation.
**Acceptance:** repeated/unchanged corrected candidates still run the complete
chain. A producer does not acquire acceptance from native execution success alone.
No reason-code text becomes correction instructions, no validator rerun extends
native structural repair, and no final duplicate assessment occurs.
**Validation:** focused pipeline tests for two independent rejections, earlier
approval followed by a changed candidate, isolated typed validator views,
unavailable assessment, guidance contract errors, and cancellation.
## Stage 10: Implement The Small Native Producer Helper
2026-11-21 23:30:45 +00:00
**Status:** Complete. Added one typed helper using native Run/Coordinate and
module-owned interpretation/correction/fallback functions. It checks native
structural status before interpretation, reuses the initial assessment on the
first coordination callback, and assesses every delivered revision once,
including the final allowed turn. Native coordination owns history and budget.
Execution/profile/session selections and existing observers/preparation callbacks
are preserved without duplicate enrollment. Failed continuations cannot recover
earlier candidates; caller cancellation and undelivered responses never become
acceptance or fallback. Real-engine offline fake-provider tests cover acceptance,
zero turns, final-turn acceptance, exhaustion, nil-error structural failure,
operational/unavailable failures, interpretation guidance, cancellation, and
typed native operation timeouts. File-scoped helper tests/vet/race checks and
contracts tests pass. Full pipeline tests remain blocked by the recorded legacy
ConfigKit YAML import and unmigrated consumers; no whole-package success is
claimed. Runner integration, caching, and capture remain in their assigned stages.
2026-11-21 22:24:16 +00:00
**Goal:** delegate turn iteration while retaining typed Notarius acceptance.
**Inspect/change:** a focused helper alongside pipeline assessment; upstream
`Coordinate` , `RunRequest` , prepared execution, and native validation status.
**Work:** accept the module's initial native request, interpretation, correction
builder, supported fallback functions, and the pipeline assessor. Use `Engine.Run`
for uncached work with exchange capture when correction/debug needs it. Check
native errors and `ValidationFailed` before interpretation, including nil-Go-error
failure results. Assess the initial usable candidate, then coordinate actionable
correction from its captured exchange with native `AdditionalTurns` . On the
initial coordination callback, use existing findings; do not reassess the initial
response. Assess each newly delivered result exactly once, including the final
allowed turn. Return typed acceptance/fallback state, not a second retry protocol.
If a continuation fails without a usable response, do not retain an earlier
proposal as the terminal fallback source; use the module's no-usable-response
fallback direction.
**Acceptance:** native coordination alone counts turns and carries history.
Acceptance stops early; exhausted/stopped are not acceptance. Structural terminal
failure and unavailable assessment do not generate invented semantic guidance.
Cancellation and `Undelivered` do not produce acceptance, fallback, or cache writes.
Distinguish caller cancellation from native execution failures using caller context
state and native typed causes rather than flattening every timeout into cancellation.
No earlier-candidate recovery, cross-turn plan union, or manual assistant replay.
**Validation:** real PromptKit with a fake provider: initial acceptance, zero turns,
correction acceptance, final-turn acceptance, exhaustion, validation failure with
nil error, operational failure, and cancellation before callback delivery.
Stage 27 adds cache selection to this same helper, not a parallel executor.
## Stage 11: Connect Typed Runner Operations And Eligibility Propagation
2026-11-21 23:48:51 +00:00
**Status:** Complete. Runner operations now carry resolved controls, native
execution options, and operation-scoped assessors. The runner consumes native
helper outcomes without outer retries or revalidation; deterministic modules
produce once and are assessed directly, with an optional module-owned fallback
function. Final codec/source checks remain mandatory. Fallback eligibility follows
chunk ancestry, lane results, and actual generated-reference consumers without
tainting unrelated work; emitting operations contribute once to fallback_count.
Removed superseded attempt/correction hooks and their debug/policy projections.
The pipeline production package builds. All production files plus the focused
typed registry, codec, assessment, native-helper, and runner tests pass, including
focused vet/race checks; contracts tests and `git diff --check` also pass.
The complete pipeline test package still imports retired dependencies/fixtures
and is not claimed passing. Production module migration, worker-pool replacement,
legacy-store removal, publication, and full capture remain in their assigned stages.
2026-11-21 22:24:16 +00:00
**Goal:** the runner supplies assessment once and consumes the returned outcome.
**Inspect/change:** `runner_typed.go` , `typed_execution.go` , `runner.go` ,
`runner_chunk_plan.go` , `handoff.go` , and the old state/correction hooks.
**Work:** bind each resolved producer's assessor and controls to its operation,
route LLM producers through the shared helper, and retain a direct production/
assessment path for deterministic stages. Remove outer assessment/retry calls
around helper-owned assessment. Carry fallback and cache-eligibility facts through
extract -> merge -> normalize and generated reference handoffs. A chunk fallback
affects all derived lane work; a lane fallback affects that lane and actual
consumers, not unrelated siblings. Keep only the small facts needed for outcomes,
fallback counting, and reuse suppression, without dependency fingerprints.
**Acceptance:** generated references may carry valid fallback artifacts with
explicit reuse ineligibility. Stable ordering, exact codec handoff, required
references, and fixed pipeline steps remain intact. Each actual fallback operation
contributes once; affected downstream operations are not themselves counted unless
they also emit a fallback.
**Validation:** focused runner/handoff tests using small typed modules: full-chain
assessment once, deterministic single execution, chunk/lane/generated-reference
eligibility propagation, unrelated predecessors unaffected, and cancellation.
Native production modules are migrated in Stages 12– 23.
## Stage 12: Migrate Spell Extraction As The Representative Producer
2026-11-22 00:02:13 +00:00
**Status:** Complete. Spell extraction now prepares fixed transcript/reference,
catalog, and NPC projections once and uses the shared native producer helper.
Added the same-schema/default-profile correction prompt, enduring system
principles, explicit run/profile/session propagation, static dependencies, and
the codec-valid empty fallback. Removed spell completion/asset/schema registries
and manifest/fingerprint metadata; retained private-response interpretation and
source-order canonicalization. Migrated focused tests to a native provider fake
and added a leaf-assembled generic-chunker spell contract covering complete ordered
assessment, final correction, strict exhaustion, permissive output, and exact
continuation history without repeated references.
Native asset, catalog/shape, isolated schema/input-helper, and focused pipeline
tests pass; runnable asset/catalog/shape vet/race checks and production pipeline/
generic/Seriatim builds pass. Full spell/shared/source-validator tests, including
the new assembled contract, are blocked at setup by shared legacy asset helpers
importing old-path ConfigKit's removed YAML `plugin/limit` . Those tests are not
claimed passing. Central registration and remaining legacy fixtures/dependencies
remain assigned to Stages 24 and 35, with final assembled verification required.
2026-11-21 22:24:16 +00:00
**Goal:** prove native extraction with the real typed module and validators.
**Inspect/change:** `internal/modules/dnd/extract/spells` , shared extraction input
helpers, spell catalog projection, spell validators, and `assets/dnd/spells` .
**Work:** prepare transcript, catalog, references, and NPC resolution once; build
native initial requests and interpret native results through the helper. Preserve
source-reference ordering/swapping, contextual entity resolution, spell identity,
catalog semantics, and exact artifact encoding. Add `notarius/dnd.spells.repair`
using the same schema and default profile as the initial prompt. Put enduring
principles in the initial system context and only findings/new correction
assignment in the follow-up. Keep explicit profile/run overrides on both requests.
Implement the valid empty spell fallback and static dependencies.
**Acceptance:** one generic-chunker spell pipeline exercises native production,
ordered validation, correction, strict failure, and permissive empty output.
Source/ref input bytes are not regenerated during continuation. The helper owns
the operation and the runner does not validate it again.
**Validation:** `go test ./internal/modules/dnd/extract/spells
./internal/modules/dnd/validate/spells/...`; adapt the assembled spell contract
test to a native provider fake, including catalog rejection and final correction.
## Stage 13: Refactor The Shared Reconciliation Core
2026-11-22 00:07:05 +00:00
**Status:** Complete. Removed the reconciliation execution service and its
private completion/correction transport, retry classifications, asset/schema
registration, metadata, and fingerprints. The core now exposes fixed owned
preparation bytes, native initial/follow-up request builders, proposal decoding,
and the existing independent safety assessment/application functions. Candidate
handles, declared ranges, bounded source windows, group-safety rules, typed
application, and actionable issue prose remain; the follow-up asset owns the
replacement assignment rather than an application retry message builder.
Added the generic native correction pair with the unchanged response schema and
matching unset profile defaults, moving enduring protocol/policy into initial
system context. Retained domain-neutral regressions and added native provider/
preparation, structural-failure, fixed-material, and successive-proposal tests.
The complete reconciliation and asset tests, vet, race checks, and
`git diff --check` pass. Domain normalizer and central registration consumers of
the removed APIs remain assigned to Stages 14– 15 and 24; no whole-tree compilation
claim is made at this intermediate boundary.
2026-11-21 22:24:16 +00:00
**Goal:** separate one-time evidence preparation from proposal interpretation.
**Inspect/change:** `internal/framework/semanticreconcile/{engine,preparation,
proposal,application,schema}.go` and relevant tests; generic normalization prompt assets.
**Work:** expose reusable preparation, native request construction, and proposal
decoding/assessment as ordinary functions. Keep fixed candidate-number mappings,
range declarations, namespace guidance, bounded source windows, proposal safety,
and model-facing issue prose. Remove the core's old completion client/correction
transport and response-schema registration/identity machinery. The module's
producer helper invocation owns native execution; do not create a replacement
reconciliation service/exchange wrapper. Convert the generic default prompt and
add its correction pair, reusing the same response schema and native defaults.
**Acceptance:** each operation prepares candidates/windows once and applies every
complete proposal afresh to those originals. Unknown/overlapping handles and
unsafe groups remain rejected. No source evidence or opaque identity is copied by
the model. Pure proposal assessment/application remains independently testable.
**Validation:** `go test ./internal/framework/semanticreconcile` ; retain the
candidate-number, group-safety, deterministic ordering, limits, and source-window
behavioral tests. Native structural failures terminate at the kit boundary, not
as a request to restart the core.
## Stage 14: Migrate Item Registry Normalization
2026-11-22 00:17:58 +00:00
**Status:** Complete. Item normalization now uses one fixed preprocessing and
reconciliation preparation, native initial/correction requests, and the shared
producer helper. Each response applies its own safe proposal to original records
before operation-scoped assessment. Currency compatibility, identity derivation,
evidence ordering, and domain diagnostics remain. Added the same-schema/default-
profile correction declaration and static dependencies; removed module retries,
completion/asset registration, and manifest/fingerprint metadata.
Permissive output uses only the final safe candidate or the supplied merged
artifact after a result-less failure. Fallback construction checks codec, registry
identity, and source usability without ordinary revalidation. Preparation limits
honor resolved mode; insufficient candidates use the existing assessment path
without native requests. Exposed/factored the existing terminal/no-model assessment
functions for these real callers rather than duplicating acceptance policy.
Retained domain regressions and added native-fake correction, final safe partial,
unchanged-candidate, failed-continuation/no-earlier-recovery, structural-failure,
mode/limit, no-model, fallback-usability, override, and cancellation tests.
Focused pipeline tests/vet/race, terminal tests, complete reconciliation/asset and
item-shape tests/vet/race, production framework builds, and `git diff --check`
pass. Item-normalizer/codec/identity/source-validator tests remain blocked at
setup by shared legacy asset helpers importing old ConfigKit's removed YAML
`plugin/limit` ; the new module tests are not claimed passing. Their full execution
remains required after scheduled dependency cleanup and in final verification.
2026-11-21 22:24:16 +00:00
**Goal:** prove a complete native normalization operation and safe fallback.
**Inspect/change:** `internal/modules/dnd/normalize/itemregistry` , its validators/
codec/identity helpers, and `assets/dnd/item-registry/normalize` .
**Work:** connect the core functions to the typed producer helper. Preprocess
fixed originals once, use initial/correction requests with fixed handles, and
apply each proposal afresh before the complete normalization assessment. Add the
domain correction prompt and dependencies. Treat preparation-limit inability and
unusable native output through resolved strict/permissive handling, without
automatic permissive defaults. On permissive exhaustion apply only safe groups
from the final usable proposal; otherwise retain the deterministic merged input.
Reuse already available merged data, never rerun deterministic stages to get it.
**Acceptance:** a failed correction cannot mutate originals, union earlier groups,
or silently claim complete semantic success. Insufficient candidates avoid a model
call as before. Reuse eligibility distinguishes ordinary accepted normalization
from final safe partial/deterministic fallback.
**Validation:** focused item-normalizer tests with a native fake provider: initial
success, repaired proposal, unsafe final groups, strict failure, permissive
preservation, unchanged-candidate reassessment, and cancellation.
## Stage 15: Migrate NPC And Location Registry Normalization
2026-11-22 00:27:34 +00:00
**Status:** Complete. Both normalizers now use the shared native producer helper
and fixed one-time reconciliation preparation. Each response applies its own safe
groups afresh to the original records, before typed operation assessment. Added
same-schema/default-profile correction prompts and static dependencies; removed
retry transport, schema/policy fingerprints, and manifest-only asset registration.
Name-based NPC identity, evidence-anchored location identity, canonical naming,
source ordering, and domain application rules remain unchanged. Strict handling
does not silently fall back; permissive output uses only the final safe candidate
or the supplied merged artifact, with codec/identity/source construction checks.
Retained domain regressions and added native provider coverage for correction,
unchanged reassessment, final-only safe groups, failed continuation without prior
proposal recovery, structural failure, overrides/history, cancellation, and
unusable fallbacks. Native prompt-pair checks run in the content package without
depending on legacy module helpers.
Asset/reconciliation tests, vet/race checks, focused pipeline producer/runner
tests, production framework builds, and `git diff --check` pass. Both normalizer
package tests remain blocked at setup by shared legacy asset helpers importing
old ConfigKit's removed YAML `plugin/limit` ; their new tests are not claimed
passing. Scheduled dependency cleanup and final whole-tree validation must run
them and close that blocker.
2026-11-21 22:24:16 +00:00
**Goal:** apply the proven normalizer path without domain-policy drift.
**Inspect/change:** `internal/modules/dnd/normalize/{npcregistry,locationregistry}`
and their normalization assets, identity/grounding helpers, and focused tests.
**Work:** migrate these two parallel consumers using Stages 13– 14's shared core
and producer helper. Preserve each family's canonical naming, proper-name scope,
source grounding, identity computation, compatible-group checks, and output order.
Add each domain correction prompt with the same initial schema/default profile;
retain generic protocol/candidate presentation as ordinary shared files. Remove
their retry directives, schema/policy fingerprints, and manifest-only metadata.
**Acceptance:** all three registry normalizers share execution and preparation
mechanics but retain their typed application rules. Every turn operates on the
same candidate namespace. Final safe-group/deterministic fallbacks are explicit,
strict remains default, and model errors do not trigger an outer restart.
**Validation:** `go test ./internal/modules/dnd/normalize/npcregistry
./internal/modules/dnd/normalize/locationregistry`; adapt boundary tests to native
provider fakes and retain domain identity/reconciliation regression coverage.
## Stage 16: Migrate D&D Scene Planning And Chunk Assessment
2026-11-22 00:34:33 +00:00
**Status:** Complete. Scene planning now prepares the full transcript/reference
inputs once and uses the shared native producer helper with initial/correction
prompts, matching schema/profile defaults, and static dependencies. Enduring
scene principles remain in initial system context. Removed the private completion,
response-schema/asset registration, and manifest metadata paths. Existing
source-order, coverage, gap/overlap, and boundary interpretation rules remain.
Unresolvable boundaries supply actionable correction guidance; unusable native
structural results never become semantic candidates. Permissive terminal handling
constructs one unannotated whole-source plan using normal materialization; invalid
input, cancellation, and fallback-construction failures do not publish a fallback.
The runner already binds materialization and complete chunk assessment to the
native operation without an outer attempt/replay loop. Added a runnable runner
contract proving ordered full-chain assessment through final-turn acceptance,
strict/permissive exhaustion, no fallback revalidation, and derived reuse exclusion.
Migrated scene regressions to a native provider fake and added correction/history,
override, structural-failure, whole-source fallback, and cancellation cases.
Scene prompt-pair/schema checks run in the asset package.
Asset/source tests and vet/race checks, focused pipeline tests and vet/race checks,
and `git diff --check` pass. Scene-chunker package tests remain blocked at setup
by shared legacy helpers importing old ConfigKit's removed YAML `plugin/limit` ;
their runtime results are not claimed passing. Scheduled dependency cleanup and
final verification must execute them. Chunk-cache replacement remains Stage 28.
2026-11-21 22:24:16 +00:00
**Goal:** one native chunk producer with deterministic materialization.
**Inspect/change:** `internal/modules/dnd/chunk/scenes` , chunk-plan interpretation/
materialization in the runner, chunk validation, and `assets/dnd/scenes` .
**Work:** prepare the full transcript once, produce/interpret a complete native
plan, materialize it through existing source-addressing checks, and assess it
through the pipeline's chunk validator chain. Add the scene-plan correction
prompt using its initial schema/profile. Implement the permissive one-whole-source
plan and materialize it normally; do not fabricate scene descriptions/tags or add
deterministic slicing. Retain source order for nonconsecutive unit IDs. Remove
outer attempt/replay logic around plan generation. Stage 28 replaces storage.
**Acceptance:** malformed or unusable plans never become ordinary acceptance.
Every revised usable plan gets complete chunk assessment, including the final
turn. A fallback preserves the full source and marks all derived work ineligible
for cache reuse. Empty/invalid input and fallback-construction errors fail normally.
**Validation:** focused scene chunker, chunk materialization, and chunk-validator
tests with a fake native provider, including reversed/resolvable ranges, invalid
units, full-source fallback, final-turn acceptance, and cancellation.
## Stage 17: Migrate The Combat-Semantics LLM Validator
2026-11-22 00:42:20 +00:00
**Status:** Complete. The validator now makes one native request on the shared
engine, preserving the validator profile/default, session, execution overrides,
transient-retry override, observer, and preparation callback. Static prompt
dependencies replace asset/schema registration and manifest/fingerprint metadata.
Native errors and failed validation status are checked before decoding; execution
and interpretation failures produce an unavailable assessment with inspectable
causes, not semantic rejection or invented correction guidance. Cancellation
does not deliver a judgment. Successful classification retains the original
combat policy, scene-local transcript boundary, explanation checks, and actionable
producer guidance. Interpretation and its existing cases are independently
testable; evaluation fixtures and schema/policy assets are unchanged.
Added native provider tests for judgments, override/input isolation, nil-error
failed validation, unavailable provider/capacity, interpretation failure,
cancellation, and nested same-backend admission. A runnable framework contract
proves complete ordered native assessment on a backend limited to one active call,
without holding producer admission or repeating the final chain.
Asset tests/vet/race, independent interpretation/evaluation tests/vet/race,
focused pipeline tests/vet/race, and `git diff --check` pass. The concrete
validator package remains blocked at setup by shared legacy asset helpers
importing old ConfigKit's removed YAML `plugin/limit` ; its native runtime tests
are not claimed passing. Scheduled dependency cleanup and final verification
must execute them. No validator-owned semantic continuation loop was added.
2026-11-21 22:24:16 +00:00
**Goal:** validators use native execution without another semantic retry loop.
**Inspect/change:** `internal/modules/dnd/validate/scenedescriptions/combat_semantics` ,
its prompt/schema assets, registration, and evaluator tests.
**Work:** build a native request using the shared engine and run-wide overrides.
Use the configured validator profile/default and native output contract. Check
errors and failed structural validation before decoding. Return domain rejection
with actionable correction guidance, or an unavailable assessment when execution/
interpretation cannot complete. Preserve scene-local contextual inputs and the
combat policy. Remove validator retry/repair fields and private schema/client
adapters; do not give the validator its own producer coordination loop.
**Acceptance:** native structural repair may occur internally, but Notarius
invokes the validator only once for each producer candidate. Capacity/provider
failures are unavailable assessment, not semantic rejection. A successful rejection
supplies useful prose to the scene producer and no opaque diagnostic code.
**Validation:** focused validator and ordered-chain tests for approve, reject,
malformed/failed validation, nil-error failure status, unavailable provider, and
nested same-backend admission with a limit of one.
## Stage 18: Migrate The Three Registry Extractors
2026-11-22 00:50:54 +00:00
**Status:** Complete. NPC, item, and location extraction now use native initial/
correction requests through the shared typed producer helper. Transcript and
campaign reference materials are captured once per chunk; every response uses
the existing family-specific canonicalizer and deterministic identity rules.
Added same-schema/default-profile correction pairs and static dependencies,
moving enduring identity/evidence/domain principles into initial system context.
Private completion, schema/asset registration, and manifest/fingerprint metadata
were removed. Canonical naming, currency scope, same-name location anchors,
source-order/evidence behavior, and production validator-chain declarations are
unchanged. Each family has a codec-valid nonnil empty fallback, qualified by the
resolved mode/outcome and excluded from reuse, rather than an invented entity.
Retained domain regressions with native provider fakes and added per-family
citation correction through real typed validators, fixed input/history and run
override checks, strict/permissive exhaustion, ordinary empty acceptance, failed
continuation, structural failure, and cancellation coverage. Prompt-pair and
structural-versus-semantic schema checks run independently in the asset package.
Asset/shape tests and vet/race checks, focused pipeline tests, and
`git diff --check` pass. Updated the location-shape spec comparison for the
slice-bearing native dependency declaration. All three extractor package tests
remain blocked at setup by shared legacy asset helpers importing old ConfigKit's
removed YAML `plugin/limit` ; their new runtime tests are not claimed passing.
Scheduled dependency cleanup and final assembled verification must execute them.
2026-11-21 22:24:16 +00:00
**Goal:** canonical noun extraction follows the representative native path.
**Inspect/change:** `internal/modules/dnd/extract/{npcregistry,itemregistry,
locationregistry}`, their extraction assets and shared citation/identity helpers.
**Work:** migrate the three parallel list producers to native builders,
interpretation, and the shared helper. Add domain correction prompts, static
dependencies, and codec-valid empty fallbacks. Prepare transcript/reference
material once per chunk. Keep proper-name scope, item/currency identity rules,
source evidence resolution, deterministic IDs, and required validator chains.
Remove per-module prompt/schema manifests and completion metadata, without
consolidating unlike domain interpretation rules.
**Acceptance:** each produces its existing typed durable artifact and preserves
source refs/identity across correction. Empty fallback is distinguished from a
normally accepted empty extraction. No module implements its own turn loop or
pins structural repair.
**Validation:** focused tests for all three extractor packages and one
representative correction/fallback case each, using the shared native fake pattern
from Stage 12. Retain meaningful per-family grounding and identity regressions.
## Stage 19: Migrate NPC And Location Occurrence Extraction
2026-11-22 01:03:06 +00:00
**Status:** Complete. Both occurrence producers now use fixed transcript/registry
materials, native initial/correction requests, and the shared typed producer
helper. Added same-schema/default-profile correction pairs and static prompt
dependencies; removed private completion, schema/asset registration, and
manifest/fingerprint metadata. Names-only NPC resolution and complete ordered
contextual location selectors retain deterministic durable identity, supported
kinds, source-order canonicalization, and current-transcript evidence. Unknown
or ambiguous selections supply actionable interpretation guidance before typed
assessment rather than guessing an identity or returning partial output.
Permissive fallbacks are codec-valid nonnil empty collections, explicitly
qualified and reuse-ineligible; accepted work inherits incoming ineligibility.
Retained domain regressions with native provider fakes and added fixed resolution/
history, source correction, run override, strict/permissive, failed continuation,
structural-failure, and cancellation cases. Prompt-pair/schema tests run in the
content package. Asset and shape tests/vet/race checks, independent NPC response
model tests/race checks, focused pipeline tests, and `git diff --check` pass.
Updated the location-occurrence shape spec comparison for slice-bearing native
dependencies. Both full extractor packages remain blocked at setup by shared
legacy helpers importing old ConfigKit's removed YAML `plugin/limit` ; their
native runtime tests are not claimed passing. Scheduled dependency cleanup and
final whole-tree verification must run those tests.
2026-11-21 22:24:16 +00:00
**Goal:** registry-consuming occurrence lanes retain contextual resolution.
**Inspect/change:** `internal/modules/dnd/extract/{npcoccurrences,locationoccurrences}` ,
their assets, registry resolvers, and source/registry validators.
**Work:** build initial native requests from fixed chunk/registry material;
interpret contextual selections and attach durable IDs deterministically. Add
the two correction pairs and empty occurrence fallbacks. Keep occurrence kinds,
unknown/ambiguous reference handling, accepted source citations, and compatible
generated-reference expectations. Pass profiles/session/overrides unchanged.
**Acceptance:** model responses never reproduce opaque application IDs. Source
context and registry resolution remain fixed throughout each correction exchange.
Fallback effects propagate to actual later consumers without invalidating
unrelated registry/predecessor artifacts.
**Validation:** focused NPC/location occurrence tests covering contextual matches,
ambiguous selection, invalid source refs, corrected final candidate, and fallback.
Do not relax existing domain invariants merely to make the migration tests pass.
## Stage 20: Migrate Item Occurrence Extraction
2026-11-22 01:08:02 +00:00
**Status:** Complete. Item occurrences now use native initial/correction requests
through the shared typed producer helper with fixed transcript and names-only
registry materials. Added the same-schema/default-profile correction pair and
static dependencies; removed private completion, prompt/schema registration,
and manifest/fingerprint machinery. Existing private nullable-field mapping,
quantity copying, holder rules, canonical identity, source references, and event
ordering remain unchanged. Unknown selections provide module-authored guidance
before typed assessment, without partial output or invented items. Permissive
terminal output is an explicit codec-valid empty list, not a repaired holder or
ordinary acceptance. Profile/session/execution selections and incoming reuse
ineligibility are preserved. Migrated the holder regression to a native provider
fake with all four typed validators, exact defective-response history, contextual
guidance, final-turn acceptance, and no duplicate final assessment. Added terminal
mode, unknown-item, failed-continuation, structural-failure, cancellation, all-kind,
ordering, and durable nullable-holder cases. Native prompt-pair/holder-principle
and unchanged structural-schema tests run independently in the assets package.
Asset tests/vet/race checks, focused pipeline tests, and `git diff --check` pass.
The extractor and all five occurrence-validator package checks remain blocked at
setup by shared legacy helpers importing old ConfigKit's removed YAML
`plugin/limit` ; the new native runtime tests are not claimed passing. Scheduled
dependency cleanup and final assembled verification must execute those tests.
2026-11-21 22:24:16 +00:00
**Goal:** retain the smaller-model holder reliability fixes in the native path.
**Inspect/change:** `internal/modules/dnd/extract/itemoccurrences` , associated
holder/registry/source validators and assets, and holder regression tests.
**Work:** use native initial/correction requests and fixed item registry context.
Preserve `discovered` , `acquired` , `lost` , `consumed` , and `transferred` semantics,
the private response-to-durable holder mapping, party-member handling, and
source-grounded deterministic entity resolution. Add the same-schema correction
pair and valid empty fallback; keep module interpretation guidance separate from
operator messages. Remove only execution/asset registration machinery.
**Acceptance:** existing acquired/from/to reliability behavior and event ordering
survive. No additional optional model-facing schema fields, synthesized holders,
opaque model IDs, or durable artifact changes are introduced.
**Validation:** focused item occurrence extractor/validator tests with native
provider fakes, including the previously reported incompatible-holder regression,
correction acceptance, empty fallback, and final semantic rejection.
## Stage 21: Migrate Combat-Turn Extraction
2026-11-22 01:13:57 +00:00
**Status:** Complete. Combat extraction now uses one fixed source/NPC projection,
native initial/correction requests, and the shared typed producer helper. Added
the same-schema/default-profile correction pair and static prompt dependencies;
removed private completion, schema/asset registration, and manifest/fingerprint
metadata. Actor/turn-kind semantics, unmatched actors, document-order endpoint
normalization, evidence canonicalization, and exact scene eligibility remain.
Noncombat and unavailable/mismatched scene paths assess their deterministic empty
result directly, retaining the existing warning where applicable, without native
preparation, a model call, or a synthetic cache entry. Explicit outcomes inherit
incoming reuse eligibility. Permissive model failures emit only a qualified,
codec-valid empty combat list; cancellation emits no fallback.
Retained domain/gating regressions with native provider fakes and added complete
ordered-chain correction, fixed eligibility/context/history, override, zero-turn
reversed-endpoint, strict/permissive, failed-continuation, structural-failure, and
cancellation cases. Added a leaf-assembled generic-chunker combat pipeline test
for combat, narrative, recap, meta, and mismatched scenes using provider invocation
counts. Native prompt-pair and unchanged structural-schema checks run in assets.
Asset/shape tests and vet/race checks, independent response-model tests/vet/race,
and `git diff --check` pass. Full combat extractor, source/invariant validator,
and integration package checks remain blocked at setup by shared legacy helpers
importing old ConfigKit's removed YAML `plugin/limit` ; native module and assembled
runtime tests are not claimed passing. Scheduled dependency cleanup and final
verification must execute them; remaining old integration fixtures retain their
assigned migration scope.
2026-11-21 22:24:16 +00:00
**Goal:** native combat production preserves scene eligibility and evidence rules.
**Inspect/change:** `internal/modules/dnd/extract/combatturns` , combat validators,
scene-description reference selection, and combat prompt assets.
**Work:** migrate initial native requests, result interpretation, correction pair,
and empty fallback. Preserve combat-only scene eligibility, actor/turn-kind rules,
source-order endpoint normalization, and source/registry context. Skipped
ineligible chunks remain deterministic no-model outcomes, not invented native
requests or synthetic cache entries.
**Acceptance:** no combat model call is made for an ineligible scene; correction
uses the same fixed operation inputs and schema. The prior resolvable reversed-
endpoint reliability behavior remains without new semantic retry cost.
**Validation:** focused combat extractor/validator tests and assembled combat
eligibility coverage with a native fake provider. Check no-call cases by provider
invocations, not by obsolete completion-interface mocks.
## Stage 22: Migrate Enemy-Event Extraction
2026-11-22 01:20:46 +00:00
**Status:** Complete. Enemy extraction now uses fixed source/reference projections,
native initial/correction requests, and the shared typed producer helper. Added
same-schema/default-profile correction assets and static dependencies; removed
private completion, schema/asset registration, and manifest/fingerprint metadata.
NPC, scene, combat-turn, and combat-opponent reference compatibility, source-free
grounding, contextual subject names, engagement checks, and source-order mapping
remain unchanged. Ineligible scenes produce directly assessed empty results
without native requests, preserving existing unavailable-classification warnings.
Permissive terminal output is an explicit codec-valid empty event list; accepted
work consuming fallback references retains incoming reuse ineligibility.
Retained grounding/domain regressions with native provider fakes and added
full-chain engagement/source correction, fixed multi-artifact context/history,
run selections, empty predecessor handoffs, strict/permissive exhaustion,
failed continuation, structural failure, and cancellation cases. Added a
leaf-assembled native pipeline test retaining the intrinsic codec boundary even
with explicit empty validator chains, and migrated the existing CLI codec
contract's typed request. Native prompt-pair, required-input, and unchanged-schema
checks run in assets. Asset tests/vet/race checks, focused pipeline tests, and
`git diff --check` pass. Extractor, validator, codec, and assembled CLI package
checks remain blocked at setup by shared legacy helpers importing old ConfigKit's
removed YAML `plugin/limit` ; their new runtime tests are not claimed passing.
Scheduled dependency cleanup and final verification must execute those tests.
2026-11-21 22:24:16 +00:00
**Goal:** preserve multi-artifact grounding while changing execution ownership.
**Inspect/change:** `internal/modules/dnd/extract/enemyevents` , grounding/mapping
helpers, its validators, and enemy-event assets.
**Work:** move the module to the shared helper and native initial/correction pair.
Keep NPC/scene/combat-turn/NPC-occurrence references, evidence intersection,
engagement checks, contextual names, and durable event order. Prepare reference
projections once per operation; use the codec-valid empty event fallback. Remove
its private completion and manifest/fingerprint metadata.
**Acceptance:** an operator override applies to initial, correction, and nested
validation without changing domain reference compatibility. Failed/fallback
predecessors affect reuse eligibility but valid fallback references remain usable
in the current run. No fabricated enemy event or expanded extraction scope.
**Validation:** focused enemy-event extraction/validation tests plus the assembled
enemy-event codec contract, using a native provider fake and current typed codecs.
## Stage 23: Migrate Scene-Description Extraction
2026-11-22 01:26:49 +00:00
**Status:** Complete. Scene descriptions now use native initial/correction
requests through the shared typed producer helper with fixed transcript/reference
materials and captured chunk identity/range. Added matching schema/default-profile
correction assets and static dependencies; removed private completion, schema/
asset registration, and manifest/fingerprint metadata. The existing one-scene
mapping, kind/title/summary contract, and trimming remain unchanged.
Permissive fallback construction uses only the final usable candidate and checks
the unchanged durable codec, exact current chunk identity/range, trimmed fields,
and current-source addressing. It does not rerun ordinary semantic validators,
invent a classification/prose, publish an empty collection, or recover an earlier
candidate after a result-less/structurally failed correction. Strict handling and
cancellation publish no fallback. Added native-provider coverage with the real
combat-semantics validator for ordered complete-chain correction, validator versus
producer profiles, shared run overrides/session, exact history, qualified final-only
semantic fallback, unusable final responses, failed continuation, and cancellation.
Retained mapping/reference/registration regressions and moved native prompt-pair/
unchanged-schema checks to assets. Independently runnable fallback tests cover
missing/empty/multiple scenes, identity/range/shape failures, and defensive ownership.
Asset, shape, source-reference, invariant, codec, and isolated fallback tests and
vet/race checks pass, as do focused pipeline tests and `git diff --check` .
Full extractor and combat-semantics package checks remain blocked at setup by
shared legacy helpers importing old ConfigKit's removed YAML `plugin/limit` ;
their new native runtime tests are not claimed passing. Scheduled cleanup and
final assembled verification must execute them.
2026-11-21 22:24:16 +00:00
**Goal:** retain the required scene artifact while making fallback limits explicit.
**Inspect/change:** `internal/modules/dnd/extract/scenedescriptions` , its codec,
shape/source/invariant validators, semantic validator integration, and assets.
**Work:** use native initial/correction requests with one description for the
operation's source range as currently required. Preserve deterministic scene IDs
and source ranges; keep the kind/title/summary contract unchanged. Add the
domain correction prompt and same-schema/profile dependency pair. Implement the
fallback rule in this plan's table: only a final usable candidate meeting the
intrinsic artifact/downstream invariants can be qualified fallback output. If
the final execution yields no usable scene, fail fallback construction rather
than emitting an empty list, inventing a classification, or recovering an earlier
candidate. Ordinary semantic revalidation is not a fallback prerequisite.
**Acceptance:** strict rejection fails; permissive handling never publishes an
invalid scene artifact or claims semantic approval. A rejected combat judgment's
guidance reaches correction, and every revised scene gets the full chain.
**Validation:** focused scene-description/semantic-validator tests with native
fakes: correction, valid-but-semantically-rejected final fallback, structurally
unusable final response, no prior-candidate recovery, and source identity.
## Stage 24: Finish Deterministic Stage Paths And Production Registration
2026-11-22 01:35:23 +00:00
**Status:** Complete. D&D, generic, and Seriatim family registration now accepts
only typed module registries; removed prompt/schema/fallback-profile registration
and adapted composition callers. Raw codecs, evidence projectors, all domain
validator defaults, and typed append/noop variants remain intact. Added native
embedded-resource dependency coverage for registered producers and validators.
Moved prompt-composition/schema-compatibility checks to the content package,
using real native preparation without private asset assembly or prefix snapshots.
Deterministic producers already run directly through the migrated runner; updated
the Seriatim typed fixtures to run without an engine and added direct merge-error
and noop-value/cancellation coverage. No synthetic requests or outer retries were
introduced; ordinary errors remain errors even in permissive mode.
All generic and Seriatim package tests, scene-normalizer tests, native asset tests,
focused typed pipeline tests, selected vet/race checks, and `git diff --check`
pass. The D&D registrar, six other deterministic normalizers, and full module
integration tests remain blocked at setup by shared legacy asset helpers importing
old ConfigKit's removed YAML `plugin/limit` ; their results, including the new
registration dependency test, are not claimed passing. Scheduled legacy cleanup
and final assembled verification must execute them. Old CLI runtime asset/client
wiring remains assigned to its later migration stages.
2026-11-21 22:24:16 +00:00
**Goal:** all non-LLM work runs directly, and production registration is asset-free.
**Inspect/change:** generic unit chunker/append-order merger/noop normalizer,
deterministic D&D normalizers, Seriatim adapter, D&D/generic registrars, typed runner,
and module integration fixtures.
**Work:** remove outer retries and obsolete correction/repair arguments from
deterministic operations. Preserve typed merge/normalize rules, ordering, domain
validators, generated references, evidence projectors, and raw artifact codecs.
Use resolved mode only for rejected candidates with a supported module fallback;
ordinary parse/materialization/application/encoding errors propagate normally.
Register modules, validator defaults, and static dependencies without registering
prompt files, schemas, or fallback profiles. Complete migration of every LLM role
identified in Stages 12– 23, not just the examples.
**Acceptance:** there is no synthetic PromptKit request for deterministic work
or generic retry setting. Durable artifact-schema validation remains; removing
duplicate model-response schema validation does not remove this application
boundary. Pipeline default-chain replacement, including explicit empty chains,
and exact typed registration still work.
**Validation:** focused generic/D&D deterministic normalizer, registrar, Seriatim,
and typed integration tests; retain data-integrity tests and remove tests whose
only purpose was the retired generic retry/asset API.
## Stage 25: Replace Worker Pools And Remove The Global LLM Scheduler
2026-11-22 01:45:31 +00:00
**Status:** Complete. One lazy coordinator now dispatches ready extraction and
merge/normalize continuations through the same bounded pool. Ready continuations
can run while unrelated extraction remains; prerequisite waits occupy no worker.
Cancellation disables dispatch, drains every dispatched result, and joins workers.
Stable output/error ordering and sequential step barriers remain. Replaced
extraction-only worker inputs with shared workers, using the selected default of
64 consistently with configuration. Removed the global scheduler/scheduled client
and their obsolete tests and CLI wrapping; native engine admission is independent.
Migrated retained concurrency fixtures and replaced legacy scheduler integration
coverage with real native-helper/backend tests. New tests cover mixed-job limits,
serial work, independent backend limits, nested same-backend validation, strict/
permissive capacity failure without another queue, and cancellation/admission reuse.
The mixed-job regression demonstrably fails with the old pools (peak 3 under
limit 2) and passes with the replacement. Focused pipeline tests/vet and repeated
race checks pass, as do generic/Seriatim/contracts/reconciliation tests and worker
configuration tests. Production pipeline/config builds and `git diff --check`
pass. Full CLI/module integration still stops at the legacy YAML `plugin/limit`
import. The full pipeline suite now reaches remaining retired fixtures such as
`NormalizeRetry` /`runProducerAttempts` ; cleanup remains required. After migrating
the configuration extractor fixture, full configuration tests compile but expose
three stale assertions: two use literal backslash-x00 rather than NUL paths, and
one reads the unresolved binding turn pointer rather than resolved controls.
Those full-suite results are not claimed passing; scheduled fixture cleanup and
final verification must close them.
2026-11-21 22:24:16 +00:00
**Goal:** one ready-job limit and native backend admission govern concurrent work.
**Inspect/change:** `runner_concurrent.go` , synchronized collaborators,
CLI runtime construction, old `llm/scheduler.go` , and concurrency/cancellation tests.
**Work:** use the existing coordinator to dispatch ready extraction and ready
merge/normalize jobs to one worker pool controlled by `concurrency.workers` .
Lane completion becomes ready only after all of that lane's extract jobs finish.
Never occupy a worker while waiting for prerequisites, or acquire another worker
for nested validation/correction. Keep sequential input/chunking/publication and
ordered steps. Remove scheduled-client/global permit plumbing and worker coupling;
share the same native engine across every role. Handle native capacity failures
through the producing operation's mode without another queue or backoff.
**Acceptance:** one worker can complete a multi-lane pipeline without deadlock.
The limit bounds both job types together, independent of backend settings.
Completion timing cannot choose public order or the terminal scoped error.
Cancellation stops dispatch, drains started work, and releases native admission.
**Validation:** focused runner concurrency tests with test-controlled worker and
backend limits, including overlap, serial work, ready-lane interleaving, nested
same-backend validation, capacity failure, and cancellation. Use focused race
testing when supported; it is a migration check, not a new release requirement.
## Stage 26: Implement The Small Accepted-Artifact Filesystem Cache
2026-11-22 01:52:21 +00:00
**Status:** Complete. Added a narrow accepted-artifact cache collaborator and
filesystem implementation storing unchanged JSON bytes at the selected root
under the opaque native hash plus `.json` . Construction/lookup create no cache
directories. Auto reads/writes, bypass performs no cache I/O, and refresh skips
lookup and replaces only a newly supplied valid result; failed writes preserve
previous acceptance. Missing entries are ordinary misses, while malformed,
unreadable, non-file, and unsafe entries return diagnostic misses. Caller-owned
typed decoding/usability and best-effort warning handling remain in the next
integration stage. Reused confined atomic process-permission writes without new
permission policy, envelopes, fingerprints, expiry, or legacy data migration.
Real-filesystem tests cover raw-byte identity, exact root/hash placement, modes,
failed refresh, cancellation, concurrent complete replacement, temporary-file
cleanup, narrow paths/symlinks, unchanged legacy records, umask/setgid inheritance,
and unchanged provisioned root permissions. Cache/fileio/contracts tests, vet,
race checks, focused pipeline tests, and `git diff --check` pass.
2026-11-21 22:24:16 +00:00
**Goal:** one best-effort cache facility replaces complex persistent records.
**Inspect/change:** existing `internal/core/fileio` and cache permission/path tests;
add a focused accepted-artifact store under `internal/framework` or the existing
state area, with a narrow lookup/write collaborator for pipeline use.
**Work:** read/write accepted artifact bytes at `<cache_directory>/<hash>.json` ,
using the native opaque hash unchanged. Use ordinary temporary-file/rename
publication and existing proportionate path/permission correctness helpers.
Keep roots at the CLI/state boundary. The caller owns typed codec/usability
checks. Missing entries are normal misses; unreadable/malformed/unusable entries
are misses with diagnostics. Failed writes warn without failing successful work.
Implement `auto` , `bypass` , and `refresh` I/O semantics; bypass creates no directory.
Refresh cannot remove a previous entry before a newly accepted replacement exists.
Do not add envelopes, manifests, key prefixes, expiry, migration, or collection.
**Acceptance:** records contain only the accepted artifact/plan; no execution,
configuration, transcript copy, acceptance ledger, or historical usage is required.
Creation respects umask/setgid/default ACLs under ADR-0017, without permission
convergence or added access restrictions. Legacy stores are left untouched.
**Validation:** focused real-temp-filesystem tests for hit/miss, unusable data,
read/write failure diagnostics, atomic replacement, modes, narrow paths, and
ordinary creation permissions. Reuse existing safety coverage where applicable.
## Stage 27: Cache Final Typed Producer Artifacts Under The Initial Request
2026-11-22 02:10:05 +00:00
**Status:** Complete. Eligible producer operations now prepare the initial native
request once, retain its detached details and opaque MessageContentHash, and
execute that same handle on a miss. Auto hits decode the expected durable artifact
with ordinary source-addressing checks and return without interpretation,
assessment, execution events, historical usage, or exchange replay. Prepared
handles are discarded on every unused exit. Only final ordinary acceptance writes
the applied typed value under the initial key, including after correction;
refresh skips lookup and failed refresh preserves previous acceptance. Bypass,
fallback, cancellation, and incoming ineligibility perform no cache writes, with
bypass/ineligibility using ordinary native execution without cache preparation.
Bound typed codecs and optional exact-type evidence projections through runner
extraction/merge/normalization and registry specialization. Cache failures produce
scoped process warnings without failing successful work; artifact encoding and
capture failures remain ordinary errors. Transient scoped cache observations retain
prepared evidence on hits without establishing a persisted cache/report contract.
Real native fake-provider/filesystem tests cover corrected applied output, fixed
initial keys, settings/session reuse versus content misses, frozen prepared
execution, no reassessment/execution on hits, unusable data, source/type checks,
all terminal exclusions, failed refresh, cancellation during hit delivery,
best-effort warning publication, merge/normalization reuse, and predecessor reuse
after downstream failure. Focused pipeline tests/vet/repeated race checks, cache/
contracts/generic/Seriatim/reconciliation tests, selected vet/race checks, production
framework builds, and `git diff --check` pass. Full pipeline tests still encounter
retired fixtures such as NormalizeRetry/runProducerAttempts; CLI/module integration
still stops at old ConfigKit's removed YAML `plugin/limit` import. Those full
suites are not claimed passing. Chunk-plan cache integration and legacy checkpoint
execution removal remain the next stage; physical CLI runtime wiring retains its
assigned later scope.
2026-11-21 22:24:16 +00:00
**Goal:** integrate caching into the same native producer helper.
**Inspect/change:** the helper, typed artifact codecs, operation eligibility,
resolved cache controls, and cache store from Stage 26.
**Work:** for eligible cacheable LLM work in auto/refresh, prepare the initial
request with `PrepareExecution` ; obtain `Details().MessageContentHash` , retain
the prepared details, and keep that key for the complete operation. In auto,
decode/usability-check a found artifact and discard the prepared handle on a hit.
On a miss execute that exact prepared handle using `RunPrepared` , then use the
same interpretation/assessment/coordination path. After final ordinary acceptance,
encode the final typed artifact and write it under the initial key. Normalizers
store the applied artifact, not the reconciliation proposal. Dispose of unused
handles on every exit. Bypass/ineligible work uses ordinary native execution and
performs no cache I/O. Capture must not cause another preparation.
**Acceptance:** a hit makes no model calls, semantic validation, exchange replay,
or historical usage claims. Models/settings/session/cache hints/schema metadata
add no key dimensions; only the upstream ordered message-content value selects
reuse. Changed policy can deliberately reuse old artifacts until refresh/bypass.
Ordinary usability includes compatibility with the expected codec and current
source addressing; it does not rerun the configured domain/semantic validator chain.
Failed/rejected/incomplete/fallback and affected dependent operations neither
load nor store entries. Corrected accepted output uses the initial key.
**Validation:** focused helper/store tests: content changes miss, settings-only
changes can hit, ordinary usability failure misses, late accepted write, no write
after terminal failure/cancellation/fallback, eligible predecessor reuse, and
native prepared details retained on a hit without an execution event.
## Stage 28: Unify Chunk-Plan Reuse And Remove Checkpoint Execution Paths
2026-11-22 02:24:45 +00:00
**Status:** Complete. Native chunk producers now use the same accepted-result
cache as typed artifacts, storing only the final domain plan under the initial
native message-content hash after materialization and complete assessment.
Hits decode and rematerialize against the current source without semantic
reassessment; unusable entries miss without entering conversation history.
Deterministic chunkers remain uncached. Removed source-digest plan lookup,
checkpoint collaborators/transitions, dependency fingerprint collection,
required-lane hydration, resume barriers, and recomputation policy from runner,
preparation, handoffs, and CLI cache composition. The CLI cache collaborator now
uses the resolved unified root; full native run wiring remains Stage 33.
Replaced canonical-partition/checkpoint tests with native-provider/filesystem
coverage for final correction, content/reference changes, settings-only reuse,
current-source rematerialization, unusable ranges/data, cache modes, terminal
exclusions, failed refresh, and unchanged legacy files. Retained current chunk-map
handoff/schema and deterministic provenance checks. Focused pipeline tests/vet/
repeated race checks, cache/contracts/source/chunk-map/generic/Seriatim/
reconciliation tests, production pipeline/cache/config builds, and
`git diff --check` pass. Full pipeline tests still stop at retired fixtures
(including checkpoint helpers and NormalizeRetry); CLI setup still stops at old
ConfigKit's removed YAML plugin/limit import. Those suites are not claimed
passing. Stage 35 owns remaining obsolete stores, module fingerprint declarations,
and fixture cleanup; final assembled verification remains required.
2026-11-21 22:24:16 +00:00
**Goal:** LLM chunk plans use the same accepted-result cache and no second store.
**Inspect/change:** `runner_chunk_plan.go` , `chunk_cache.go` , `chunk_plan_store.go` ,
checkpoint hooks in runner/preparation/handoff, CLI cache composition, and old
`internal/framework/{chunkplan,checkpoint}` consumers.
**Work:** cache a generated plan only after materialization and complete chunk
assessment/continuation acceptance, under its initial request's native hash.
On a hit decode/rematerialize it against the current source with ordinary
structural/source-reference usability checks, without semantic revalidation.
An unusable cached plan is a miss, not a defective assistant response. Keep
deterministic chunkers uncached without synthetic requests. Remove source-digest
plan lookup/publication, checkpoint event/state transitions, stage/dependency
fingerprints, resume barriers, and recomputation bookkeeping from execution.
Old records are unread and unmodified, even below the selected new cache root.
**Acceptance:** changed chunk request messages can select a different plan;
source identity alone no longer pins a partition. Default reruns reuse accepted
predecessors without `--resume` . Chunk fallback and dependent work skip reuse.
No checkpoint identity is retained solely to fill diagnostics.
**Validation:** focused chunk/runner/cache tests with fake providers: matching
plan reuse, changed references/prompt text, settings-only reuse, invalid cached
source ranges, strict/permissive outcomes, bypass/refresh, and legacy files left
unchanged. Remove old canonical-partition/resume-policy tests as superseded.
## Stage 29: Publish Only Domain Artifacts At Existing Paths
2026-11-22 02:34:40 +00:00
**Status:** Complete. The JSON encoder now returns only lane artifacts and
explicitly enabled, available chunk-map/evidence-context files, preserving lane
filename mapping, JSON payloads, intrinsic metadata, codec checks, and auxiliary
schemas. Removed index/manifest/rejected/warnings/diagnostics sidecar generation,
the reporting-model package, manifest/profile/validation ledgers, and reporting-only
output inputs. Runner results expose deliverable files, process diagnostics, and
fallback count; intermediate normalized values remain private for ordered handoffs
and evidence construction. ArtifactCount counts deliverable files only.
Retained filename/collision, JSON/number, auxiliary codec, source ordering/window,
projection/type, ownership, and disabled-output coverage. Added explicit auxiliary
selection/count and no-sidecar checks, migrated evidence preparation fixtures,
and verified evidence reconstruction from a native cached normalization without
semantic reassessment. The Seriatim runner contract now checks the real JSON
domain artifact instead of a manifest or fake output.
Focused pipeline tests/vet/repeated race checks, generic/Seriatim/contracts/cache/
source/asset/chunk-map/evidence tests, selected vet/race checks, production
pipeline/generic/Seriatim/config builds, and git diff checks pass. Independently
runnable candidate-JSON, combat-turn, NPC-occurrence, scene-description, and
source-range codec tests pass. Full pipeline/CLI and remaining D&D codec suites
still encounter unmigrated callers of the removed reporting package, the old
ConfigKit YAML plugin/limit import, or retired fingerprint declarations. Those
suites are not claimed passing; scheduled command/debug integration and Stage 35
cleanup must close the blockers before final verification. Native completion
reporting and physical publication/failure outcomes remain Stage 34.
2026-11-21 22:24:16 +00:00
**Goal:** simplify the logical output boundary without changing payload contracts.
**Inspect/change:** `internal/modules/generic/output/json/encoder.go` ,
`internal/core/artifacts` , output contracts/runner result assembly, evidence output,
and chunk-map publication. Inspect the existing lane filename mapping.
**Work:** keep run-specific `lanes/<safe-lane-id>.json` , optional `chunk-map.json` ,
and optional `evidence-context.json` . Preserve domain schemas, exact lane mapping,
and union-of-cited-source-segments evidence behavior. Remove mandatory index,
manifest, rejected/warnings/diagnostics sidecar generation and reporting-only
models/metadata. Return the small application outcome and logical deliverable
files needed for publication, fallback disclosure, and optional capture.
Intrinsic domain metadata remains intrinsic, not discarded as reporting data.
**Acceptance:** codecs and normal downstream use need no metadata bundle or
persisted receipt. Artifact count includes actual published domain deliverables,
including reused artifacts and enabled auxiliaries, not intermediates/cache/debug.
Fallback artifacts retain required downstream shape without normal-acceptance claims.
**Validation:** focused encoder/evidence/chunk-map/codec tests verifying preserved
payloads and paths, no mandatory sidecars, optional artifact inclusion, accurate
counting, and evidence source order/window behavior.
## Stage 30: Build The Debug Recorder And Session Lifecycle
2026-11-22 02:49:48 +00:00
**Status:** Complete. Replaced summary/trace allocation and separate terminal
writers with one run-scoped recorder for incremental JSON/text evidence and one
terminal outcome. Allocation creates the absolute run directory and atomically
updates a relative latest link at start; completion never retargets it. Failed
starts retain an available directory rather than deleting captured data.
The recorder is concurrency-safe, retains callback errors for boundary checks,
preserves primary causes alongside capture failures, and finalizes once without
rewriting evidence on repeated calls. Finalization failures are errors, including
after artifact publication; a later presentation failure remains reportable.
Added reusable native debug/debug-dir input binding and selection, preserving
quiet/debug ordering, explicit false/empty values, configured/default roots,
invocation-relative overrides, and nonempty overrides over empty configuration.
Disabled capture performs no allocation or latest update. Removed the legacy
summary/terminal factories and routed run-path allocation/finalization through
the new lifecycle before engine/preflight and before successful presentation.
Real-filesystem lifecycle/concurrency/failure tests, isolated real-CommandKit
flag/selection tests, focused pipeline tests, selected vet/race checks, production
debug/bundle/pipeline/config builds, and git diff checks pass. Full CLI/pipeline
package checks remain blocked at setup by unmigrated imports of the removed
reporting package and old ConfigKit's YAML plugin/limit dependency; their results
are not claimed passing. Full native evidence/observation wiring remains Stage 31,
native run-handler composition remains Stage 33, and final publication/report
outcome integration remains Stage 34. Remaining obsolete fixtures are Stage 35
cleanup, not a reason to restore the old writers.
2026-11-21 22:24:16 +00:00
**Goal:** requested capture has one simple recorder and explicit failure semantics.
**Inspect/change:** `internal/core/debugbundle` , `internal/framework/debug` ,
pipeline debug collaborators, run IDs, and CLI debug/state composition.
**Work:** replace the old summary/trace hierarchy with an application recorder
for run context, operation evidence, and one final outcome. Implement
`<debug-root>/<run-id>/` and start-time relative `latest` , without completion-time
retargeting. Resolve the selected native debug boolean and CLI/config/empty/default
directory semantics. Allocate only on the run path after config/run identity and
before engine construction/preflight. Persist incrementally and finalize once.
Allocation/link failure prevents model work; recording failure surfaces at normal
boundaries; finalization failure fails the invocation. Preserve an existing primary
failure and available data/publication paths; never retry a model for capture failure.
**Acceptance:** a configured directory alone never enables capture; explicit empty
disables it; a nonempty CLI override can re-enable it. Disabled runs leave `latest`
untouched. Quiet mode and capture selection are independent. No automatic bundle
deletion, fallback directory, capture-depth setting, or new filesystem framework.
**Validation:** focused temp-filesystem lifecycle tests: absent/empty/nonempty
selection, start failure, failed run retention, concurrent start/link semantics,
incremental recording failure, finalization failure, and no completion retarget.
## Stage 31: Attach Native Execution Facts And Complete Debug Evidence
2026-11-22 03:19:43 +00:00
**Status:** Complete. Runner invocations now enroll initial, coordinated, and
nested validator executions in one native ExecutionGroup, preserving native
identity, terminal coverage, and unknown usage without copied totals. Scoped
capture composes existing observers and lightweight preparation callbacks, reuses
split-preparation details on hits, and records native events, prepared contracts,
results, exact response text, and full readable exchanges. Undelivered responses
are explicitly unassessed; result-less and preparation failures retain availability
and error evidence. Capture failures preserve primary causes and cannot trigger
semantic retries or permissive fallback.
Added frozen secret-aware application/PromptKit configuration and source snapshots,
resolved composition, self-contained source/reference/incoming-artifact inputs,
codec candidates, complete findings/guidance, interpretation and correction inputs,
normalization originals/mappings/proposals, deterministic/fallback outcomes, and
cache decisions/artifact bytes. Native credential omissions and exact adopted
configuration sensitivity paths are preserved without scanning application text;
runtime options are not reserialized outside native inspection. Removed the old
completion decorator, synthetic IDs, duplicate accounting, and heuristic content
scrubbing. Evidence is written incrementally without whole-run content retention.
Focused native helper/runner/assessment tests, isolated real-kit configuration
capture tests, vet, repeated race checks, recorder/cache/contracts/generic/Seriatim/
reconciliation/asset tests, production framework/config builds, and diff checks
pass. Concrete D&D normalizer/validator and full CLI/pipeline suites remain blocked
at setup by legacy removed reporting-package imports and old ConfigKit's YAML
plugin/limit dependency; their runtime results, including the new normalization
capture regression, are not claimed passing. Scheduled cleanup and final verification
must execute them. Native run-handler composition and final reporting remain in
their assigned later stages.
2026-11-21 22:24:16 +00:00
**Goal:** use native observations/snapshots instead of parallel execution accounting.
**Inspect/change:** helper/validator request observers, runner operation boundaries,
new recorder, old `pipeline/debug.go` , and PromptKit observation/exchange APIs.
**Work:** create one invocation `ExecutionGroup` . Enroll the initial request once,
continuations once through `CoordinateRequest.Observer` , and nested validators
once on their own requests; do not also attach the same group to continuation
requests. Compose scope-aware diagnostic/capture observers without replacing
existing ones. Use native RunID/ParentRunID and totals, preserving unknown usage
and terminal coverage. Keep `OnPrepared` lightweight; retain its detached details
for normal boundary writes. For split prepared/cache paths use existing details.
Record the roadmap's full available inventory: effective secret-aware config and
composition; parsed source; self-contained source/reference/normalization inputs;
prepared requests/output contracts; native events/results/raw response text;
all visible exchanges/readable messages; typed candidates, findings/guidance,
correction inputs, fallbacks, deterministic results, and cache decisions. Label
unassessed `Undelivered` responses and failures lacking prepared/result evidence.
Use convenient indented JSON/text without truncation, fabricated provider bodies,
heuristic scrubbing, or whole-run content accumulation. Exact filenames stay private.
**Acceptance:** native totals count executions rather than producer attempts;
cache hits add none. Debug needs no second prepare or model call. Shared callbacks
are concurrency-safe; observer write failures reach the next boundary. ConfigKit
secrets/native credentials remain omitted without rewriting ordinary application
content. No duplicate usage accumulator, synthetic call-ID model, or profile ledger.
**Validation:** focused helper/recorder tests for initial+continuation+nested calls,
result-less terminal failures, cache hit details, canceled/undelivered turns,
full untruncated selected content, native credential omissions, and concurrent
operations. Check meaningful evidence, not the complete native JSON shape.
## Stage 32: Add Offline Preflight And Pipeline Inspection Commands
2026-11-22 03:32:31 +00:00
**Status:** Complete. Added native pipeline list/show/validate declarations using
the shared captured application load. List enumerates sorted configuration IDs
without constructing a catalog or engine. Show uses ordinary domain resolution
and reports steps, lanes, modules, controls, validator chains, prompt declarations,
and reference bindings without expanding profiles or serializing runtime options.
Validation resolves the same domain contracts and supplies the captured engine
only for selected model work. The new preflight package inspects every known
initial/correction/validator/input/output prompt and explicit/applicable default
profile, preserves native causes, and aggregates pipeline/step/lane/validator
context. Partial profiles pass; undeclared dynamic selections remain runtime
checks. No request preparation, transcript/reference reads, credential lookup,
provider call, module construction, or run-storage creation is involved.
Focused real-kit preflight and CLI command tests, vet, repeated race checks,
focused pipeline tests, production preflight/pipeline/config builds, and diff
checks pass. Native configuration validation retains no pipeline-specific mode;
added assembled help/config-command regressions. The full CLI suite, including
those assembled regressions, remains blocked at setup by removed reporting-package
imports and old ConfigKit's YAML plugin/limit dependency; it is not claimed passing.
Scheduled cleanup and final verification must execute it. Native run-handler
composition will reuse this preflight boundary in Stage 33.
2026-11-21 22:24:16 +00:00
**Goal:** execution and inspection share domain resolution and known dependencies.
**Inspect/change:** new `internal/preflight` , CLI pipeline declarations, catalog,
profile/reference/module resolution, and existing explicit-profile preflight tests.
**Work:** implement `pipeline list` , `show <pipeline-id>` , and
`validate <pipeline-id>` . List only enumerates configuration. Show reports resolved
steps/lanes/modules/validators/references without building an engine merely to
expand every profile. Validation reuses resolver checks and, when LLM dependencies
are selected, the same captured engine and static module declarations as runtime.
Check initial/correction/validator prompts, explicit/applicable/default profiles,
and known dependencies with pipeline/stage/lane context. Remove the old pipeline
mode of `config validate` ; that standard command validates resolved configuration.
**Acceptance:** offline preflight needs no input transcript, reference file bytes,
credential values, provider call, output/cache/debug root, or synthetic request.
Valid partial profiles pass. Dynamic request selections are checked at runtime.
Preflight does not load configuration, register modules, construct engines, or
render CLI reports; it accepts those collaborators/data from composition.
**Validation:** focused preflight/CLI tests for known missing prompt/profile,
validator and correction dependencies, defaults with no explicit profile, valid
partial profile, no-credential/no-transcript operation, and useful scope context.
## Stage 33: Wire Native Pipeline Run Inputs And Runtime Composition
2026-11-22 03:51:08 +00:00
**Status:** Complete. Installed native `pipeline run` and its CommandKit `run`
alias with typed required input, literal repeated lanes, output/cache selection,
reference binds/unbinds, debug controls, and native resource/execution overrides.
One captured application result and engine serve preflight and every model role.
Reference expansion preserves specificity, required slots, generated conflicts,
and CLI/config file origins. Generated sessions remain input-based; explicit
empty profile/session/reasoning and false/zero inputs preserve native behavior.
Debug allocation precedes engine/preflight, which precedes source execution.
Removed the old run dispatcher/parsers/help, retired flags, and legacy runtime
client/asset construction. Retained confined publication helpers for the next
reporting integration. Real-kit/fake-provider run/reference/session/override tests,
focused pipeline and configuration tests, supporting preflight/assets/contracts/
cache/debug/generic/Seriatim tests, focused vet/race checks, and diff checks pass.
Full CLI/executable checks, including the new subprocess route tests, remain
blocked at setup by `run_result.go` importing the removed reporting package and
old ConfigKit importing YAML's removed `plugin/limit` . The full profile test file
also retains retired `CorrectionProtocol` fixtures. Those checks are not claimed
passing; Stages 34– 35 own their remaining integration and fixture cleanup, and
final assembled verification must execute them. Native completion reporting and
publication/presentation failure outcomes remain Stage 34.
2026-11-21 22:24:16 +00:00
**Goal:** the executable runs the migrated pipeline through one native handler.
**Inspect/change:** CLI application/pipeline commands, `run.go` , catalog,
reference selectors, `session.go` , run IDs, configuration/engine/state loaders,
and `cmd/notarius` .
**Work:** install `pipeline run <pipeline-id> --input-file PATH` and
`commandkit.Alias("run", "pipeline run")` . Use typed supplied values for `--lane` ,
`--output-dir` , `--cache` , references/unbinds, debug directory, and ckprompt
overrides. Keep repeated lanes literal (commas are not separators); validate every
singleton occurrence and retain the last successfully parsed value. Expand
reference selectors before framework resolution using the existing specificity,
required-slot, external/generated-conflict, and file-origin policies. Preserve
deterministic input-based session generation, independent of references, and
native explicit session override behavior. Apply run-wide profile/execution
overrides to producers, validators, and continuation requests.
Reuse the one loaded selection and one engine, resolve/preflight before source
execution, then materialize references and prepare typed modules. Allocate requested
debug before engine/preflight as specified; keep all physical roots at composition.
Remove old dispatch, assembled help, parsers, comma `--only` , bespoke `--json` ,
reasoning-clearing flag, resume/recompute/chunk-cache flags, and legacy aliases.
**Acceptance:** native alias and canonical route invoke the same declarations/
handler; `--` , operands, repeated flags, modes, and supplied empty/false/zero retain
upstream behavior. No forwarding command, recursive command invocation, fallback
to another config for explicit empty input, or request override mutation of config.
**Validation:** focused command/reference/session tests and subprocess cases for
the two run routes, multi-reference input, literal comma lane, required input,
native overrides reaching all roles, explicit empty reasoning/debug path, and
input-hash session stability across changed reference bundles.
## Stage 34: Finish Publication, Native Completion Reports, And Failure Outcomes
2026-11-22 04:05:44 +00:00
**Status:** Complete. Replaced the receipt/encoder/index and validation-ledger
reporting model with one native completion value and text template. Publication
and requested capture finish before reporting; JSON/YAML share the same value,
omit zero fallback counts and disabled debug paths, and never create reporting
sidecars. Qualified fallback summaries remain visible independently of warning
verbosity. Native progress, configuration diagnostics, and process findings use
stderr without promoting domain advisories to warnings. Operation causes remain
separate from native rendering/output/diagnostic delivery evidence. Failed capture
or presentation retains published files and available paths without model retries
or repeat terminalization. Identifiable preflight selections now retain a typed
classification alongside native causes; cancellation and unknown/mixed failures
remain operational. Replaced obsolete receipt tests with real-kit/fake-provider
coverage for formats, counts, native modes/progress, quiet rendering failure,
partial/failed stdout, failed diagnostics, cancellation, publication/capture
ordering, and primary/capture/delivery cause preservation.
Focused CLI/pipeline tests, supporting preflight/debug/cache/contracts/assets/
generic/Seriatim tests, focused vet/race checks, and diff checks pass. Added real
executable format/fallback tests using a local fake HTTP provider; their setup and
the full CLI/executable checks remain blocked by legacy `framework/llm` importing
the removed reporting package and old ConfigKit's removed YAML `plugin/limit`
dependency. Those subprocess results are not claimed passing. Stage 35 owns
remaining legacy code/dependency/fixture removal and whole-tree compilation;
assembled and final verification must execute the pending checks.
2026-11-21 22:24:16 +00:00
**Goal:** subprocesses receive artifacts plus the selected small native report.
**Inspect/change:** `run_result.go` , `run_terminal.go` , physical output placement,
CommandKit reporter/outcomes, debug finalization, and subprocess receipt tests.
**Work:** publish domain files in the existing run-specific destination, finish
requested capture, then call `Reporter.Report` with pipeline, artifact_count,
absolute output_directory, optional debug_directory, and positive-only
fallback_count. Supply the selected human text template from that same value.
Remove separate encoders, receipt/error envelopes, automatic report persistence,
warning-count summaries, and durable execution ledgers. Send native diagnostics
to stderr and results to stdout, preserving quiet/mode/progress semantics and
fallback qualification even when warnings are hidden.
Map native outcomes: completion `0` , operational/cancellation/publication/
presentation failure `1` , identifiable invalid invocation/configuration `2` , native
diff differences `3` . Preserve typed underlying causes and distinguish operation
failure from report/diagnostic delivery failure. A post-publication capture/report
failure identifies available artifact/debug paths, returns nonzero, and does not
rerun or remove valid artifacts. Failed stdout may be partial; consumers check status.
**Acceptance:** `--format json --verbose` has report-only valid JSON on stdout
for success. Positive fallback_count counts emitting operations once, not affected
artifacts, attempts, or validators. Quiet suppresses stdout but not useful failure
explanations. Native standard commands have no Notarius-wide envelope.
**Validation:** focused subprocess tests for text/JSON/YAML success, fallback and
zero omission, verbose stderr, quiet/debug order, render/delivery failure,
publication then capture failure, useful exit categories, and no reporting sidecars.
## Stage 35: Remove Superseded Machinery And Restore Whole-Tree Compilation
2026-11-22 04:19:23 +00:00
**Status:** In progress. Removed the retired LLM wrapper, asset/schema registries,
prompt filesystem/mount helpers, copied completion/correction/debug contracts,
old checkpoint/chunk-plan source packages, and reporting-only module fingerprint
methods. No runtime output/cache/debug files were removed. Preserved typed
2026-11-22 04:54:27 +00:00
validation-result checks, intrinsic artifact schemas, domain codecs, reference
compatibility, and source/identity rules. Corrected stale source/JSON fixture
expectations and the configuration NUL/resolved-control assertions.
All framework, module (including the complete integration package), and
configuration tests now compile and pass. Migrated retained resolution,
construction, reference materialization, typed handoff, codec, source/annotation
isolation, diagnostics, and session coverage. Cross-family contracts live in the
black-box module integration package and use real production registration and
native provider fakes; the unchanged import-boundary tests pass. Published domain
and evidence files replace retired manifests and intermediate-output ledgers.
Spell, NPC, location, occurrence, combat, and grounded-pipeline fixtures retain
canonical identity, contextual selection, source chronology, scene eligibility,
complete correction/revalidation, and evidence-union behavior. Invalid combat
enums fail at the native structural boundary rather than bypassing its schema.
Removed tests tied solely to superseded outer retries, checkpoint provenance,
manifests, and attempt-debug wrappers; native producer/cache/assessment/capture
tests own the replacement behavior. Complete pipeline and integration repeated
race checks pass, as do framework/integration vet checks.
The production executable builds. Real executable route and text/JSON/YAML/
fallback checks passed with a local fake HTTP provider after removal of the old
runtime wrapper. Focused native CLI tests pass, but the full CLI suite and
2026-11-22 05:01:09 +00:00
whole-tree compilation remain blocked by legacy CLI fixtures/imports.
Migrated the shared production CLI fixture to the real native application loader,
engine, provider requests, version 6 test inputs, and native pipeline validation.
Retained catalog/typed registration, validator-chain replacement, reference
materialization/limits, configured backend selection, scene description profile
selection, source ranges, and published chunk-map provenance. Provider observations
and codec-decoded files replace profile manifests and normalized-output ledgers.
Oversized references prevent model work/publication without requiring the retired
runtime-factory construction order. Removed only tests of deleted asset/fingerprint
factories; native captured-loading tests cover shared configuration ownership.
Focused production CLI tests, vet, and repeated race checks pass. Whole CLI setup now stops at
remaining fixtures importing the removed reporting package, rather than the
legacy ConfigKit YAML import. Remaining CLI test migration, dependency tidy/
old-path removal, notice reconciliation, and whole-tree validation are required
before completion. This stage is not marked finished.
2026-11-22 04:45:39 +00:00
2026-11-22 05:07:00 +00:00
Assembled spell tests now exercise the real native extractor and continuation
history rather than a synthetic model-candidate/correction protocol. Retained
merged-cast ordering, canonicalization, evidence, explicit validator overrides,
and process/advisory distinctions. Native catalog correction tests cover selected
turn exhaustion and corrected overlay acceptance; strict terminal rejection
publishes no artifact. Catalog materialization retains raw-reference provenance
and semantic recognition across reordered overlay bytes, and the native CLI
publishes the grounded overlay spell. Deleted only superseded checkpoint-identity/
resume and manifest/sidecar assertions and their helpers. Focused assembled spell/
catalog tests, vet, and repeated race checks pass; remaining CLI fixtures and final
compilation are still required.
2026-11-22 05:16:24 +00:00
Configuration/discovery/inspection fixtures now use native scopes, rooted paths,
overlays, supplied overrides, pipeline validation, and profile inspection.
Retained source-relative discovery, inherited pipeline composition, source
diagnostics, secret-aware configuration views, no implicit provider work, and
presentation failures. Native validation may report failed scopes on stdout;
tests no longer impose the retired application's empty-error-output convention.
Fixed stale fixtures to include bundled profiles and use PromptKit's native
smoke-test kind rather than a command spelling. Focused native command/configuration
tests, vet, and repeated race checks pass. Whole CLI compilation still awaits
the remaining run/state, enemy-event, reference, and example fixture cleanup.
2026-11-22 05:24:30 +00:00
Run/state contracts now use real native execution, domain files, and the unified
accepted-artifact cache rather than a synthetic completion/checkpoint harness.
Retained root independence, all cache modes, group-accessible reuse, narrow run
identities, output/debug collision protection, selected-data capture, failure
retention, discovery, and overlay origins. Reference-selector contracts retain
scope/specificity, unbinding, type variants, and generated-reference protection
without constructing modules. Moved the complete-example selector contract beside
the other example tests; maintained example migration remains Stage 36.
Focused native run/state/reference tests and vet pass; repeated race checks for
the run/state and command/configuration set pass. Remaining enemy-event/example
fixtures, dependency tidy/notices, and whole-tree compilation are still required.
2026-11-21 22:24:16 +00:00
**Goal:** delete the old architecture rather than leave dormant alternatives.
**Inspect/change:** all production/test callers of the feature roadmap's removal
inventory; `internal/framework/llm` , `promptfs` , `readonlyfs` consumers,
checkpoint/chunkplan stores, private completion/correction/schema types,
manifest/receipt models, and old CLI tests/dependencies.
**Work:** remove now-unused adapters, schedulers, asset/schema registries,
flattening/mount helpers, effective-YAML walking, fingerprints, manual correction
transport/capability checks, generic retries, profile/usage conversions, debug
wrappers, state ledgers, and old command surfaces. Retain useful pure helpers only
where a current consumer needs them, in the actual owning package. Do not keep an
empty `internal/framework/llm` for construction. Adapt remaining tests to native
provider boundaries and final contracts; delete tests solely asserting retired
behavior, not tests protecting unchanged domain correctness. Run tidy and remove
old-path kits/catalogs after their last imports disappear; reconcile notices.
**Acceptance:** every package and test compiles with the declared dependencies.
Production code has one native path and no legacy compatibility scaffold. Removal
does not delete output/cache/debug directories or rewrite accepted ADR decisions.
Pure domain/codecs remain free of unnecessary library dependencies.
**Validation:** `GOWORK=off go mod tidy` , `GOWORK=off go test ./... -run '^$'` ,
`go list -m all` , and scoped code searches for the removal inventory. Classify
historical release/ADR/archive mentions rather than blindly deleting text matches.
## Stage 36: Migrate The Maintained Minimal And Complete Examples
**Goal:** two useful D&D configurations demonstrate the final native workflow.
**Inspect/change:** `examples/dnd-{minimal,complete}.config.yml` , pipeline imports,
profiles/overlay files, transcript/reference fixtures, and
`internal/cli/example_contract_test.go` .
**Work:** organize the two examples as `examples/dnd-minimal/config.yml` and
`examples/dnd-complete/config.yml` , moving their required imports/fixtures and
fixing paths. Separate directories prevent the complete example's companion
resources from changing the minimal example. Minimal uses embedded defaults and
a simple pipeline. Complete uses every configured D&D family and ordered generated
references, with optional chunk-map/evidence output; demonstrate native companion
profiles, inheritance/operator override, and a limited backend without overriding
the native queue default unnecessarily. Use version 6, qualified IDs, new worker/
cache/mode/turn controls, and no old retry/structural-repair fields. Replace the old
development variant with a native profile/prompt customization or semantic-budget
example, not a compatibility translation. Keep all files secret-free.
**Acceptance:** both actual config paths load, resolve, and pass offline pipeline
preflight without credential values. Imported paths are declaration-relative.
The minimal example has no accidental companion dependency. Retire superseded
copyable configurations, retaining useful shared test/reference data as needed.
**Validation:** maintained example-loading tests plus native configuration and
pipeline validate commands for both paths. Fake-provider integration can exercise
them; live OpenRouter/local services are not default validation requirements.
## Stage 37: Verify Assembled Recovery And Native Command Workflows
**Goal:** prove the cross-boundary behavior most likely to regress in this cutover.
**Inspect/change:** CLI assembled/command/cache contracts, module integration
tests, and new provider-boundary fixtures. Consolidate existing coverage rather
than creating a second comprehensive fixture framework.
**Work:** exercise a representative ordered multi-step pipeline with typed
generated references and one native engine. Include the representative extractor,
normalizer, LLM validator, and deterministic paths. Add focused assembled cases
for downstream failure/fix/rerun reuse, correction stored under the initial key,
fallback taint across handoffs versus unaffected predecessors, chunk-plan reuse,
refresh failure preserving an old entry, native limited-backend admission and
serial workers, debug on hits/failure, and report/stream outcomes. Ensure no
unexpected external calls in help/inspection/preflight, or duplicate preparation
for debug. Cover custom operator schemas/contracts through real preparation;
where an actual request-level override is needed, use a complete native
`OutputContractInput` with `RepairAttempts` unset unless the operator supplied it.
**Acceptance:** behavior follows the feature roadmap's full acceptance matrix,
including result-less failures, unknown usage, native status distinctions, final
turn assessment, all-validators guidance, source/session/reference preservation,
and unchanged intrinsic payloads. Avoid duplicating upstream parser/renderer/
retry tests, pinning upstream default attempt counts, or snapshotting full help/
native debug objects. No production model-quality claim is inferred from fakes.
**Validation:** `GOWORK=off go test ./internal/cli ./internal/modules/integration
./internal/framework/pipeline ./internal/framework/semanticreconcile`; run focused
race checks for shared observers/coordinator when practical. Stage 46 owns the
complete final suite after documentation and remaining corrections.
## Stage 38: Record Successor Decisions And Align Architecture Policy
**Goal:** document deliberate boundary changes without rewriting their history.
**Inspect/change:** `docs/policy/architecture.md` , ADRs 0005– 0007, 0011, 0014,
0016, 0019, and the retained 0012/0013/0015/0017/0020 decisions. Inspect the current
next ADR number before adding sequential records.
**Work:** write concise successor ADRs for (1) native kit composition/execution/
admission and prompt-declared assets, (2) native continuation with application
assessment/modes, (3) unified accepted-artifact caching, and (4) artifact-first
publication/native reporting and debug ownership. Use the next available numbers,
starting at 0021 if none have since been added. Change earlier statuses/links to
identify full or partial supersession, preserving accepted decision bodies and
retained content-only asset, contextual-ID, process-warning, deployment-permission,
and ConfigKit ownership decisions. Architecture now describes native library
types as an intentional execution boundary, one worker pool/native admission,
new retry/fallback/cache semantics, optional diagnostic records, and current
output/debug responsibilities.
**Acceptance:** no current policy still mandates the retired private LLM API,
global scheduler, latest-only replay, source-only plan partition, checkpoint
resume, manifests, or heuristic sanitization. Retained source/domain/type and
filesystem correctness boundaries remain, with no new access policy, storage
guarantee, release gate, or public debug format. Keep policy provenance headers
accurate; this is a local architecture update, not a new upstream policy adoption.
**Validation:** review each changed invariant against the feature roadmap and
implemented behavior. Check ADR status links and accepted-body preservation;
`git diff --check` . Do not rewrite historical release notes or archived roadmaps.
## Stage 39: Rewrite Canonical Configuration And CLI References
**Goal:** operators can configure and invoke only the implemented native surface.
**Inspect/change:** `docs/config.md` , `docs/cli.md` , final command declarations,
ConfigKit definition, resolver tests, and the two maintained examples.
**Work:** document native discovery and companions under one result; version 6;
qualified resources, replacement/inheritance/null semantics and schema roots;
native profile/backend controls; worker and semantic-turn controls; strict/
permissive precedence; and cache settings. Explain no backend concurrency default
is injected and no independent Notarius structural-repair count is pinned.
Document new pipeline commands/alias, required operands, supplied values, repeated
lanes/references, run-wide ckprompt flags, native formats/modes/progress, stdout/
stderr, and outcome codes. Link upstream-owned standard command semantics where
appropriate, with short Notarius-specific selection examples rather than a
copied upstream manual. Link full copyable files in `examples/` .
**Acceptance:** current references describe implemented behavior only. Retired
flags/fields occur solely in clearly identified migration material, not usable
syntax. Config fields/defaults belong in the configuration owner, invocation
syntax in the CLI owner; neither duplicates physical state or artifact schemas.
**Validation:** compare documented commands with native help and focused parser/
loading tests. Check relative links/anchors and example paths. Test omitted and
explicit values through declarations, not prose-based change detectors.
## Stage 40: Update Operations And Downstream Consumer Contracts
**Goal:** explain the intentional persistence and subprocess breaking changes.
**Inspect/change:** `docs/operations.md` , `docs/consumers/{subprocess,dnd-pipeline}.md` ,
`docs/integrations/run-result.md` , JSON/chunk-map/evidence integration contracts,
and any release-runbook command references affected by the CLI cutover.
**Work:** describe the independent output/cache/debug roots, per-user cache default
and `/var/cache/notarius` system convention, reuse modes, best-effort I/O, unchanged
legacy data, and explicit refresh for policy/model experiments. Explain fallback
qualification and reuse exclusion, whole-source chunk fallback, debug selection/
empty paths/start-time `latest` , retained evidence, and capture/publication failure.
Delete the superseded persisted receipt contract and replace consumer links with
the CLI report contract plus documented domain paths; do not create a new manifest
contract. Consumers check status, optionally decode the small report, then read
configured lane/auxiliary paths. Note partial stdout on delivery failure and valid
artifacts after post-publication failure.
Add `docs/consumers/native-migration.md` covering old-to-new commands,
configuration/resources/catalog IDs, native retry intent, removed transient/repair
wrapper controls, workers/admission, cache reuse, and receipt traversal replacement.
Link it from canonical entry points. Exact old provider-attempt parity and automatic
cache conversion are not promised. Keep tagged release notes unchanged; preparing
or publishing a new release is outside this sprint.
**Acceptance:** the complete D&D subprocess workflow uses `--input-file` ,
`--output-dir` , and pipeline-level references as first-class inputs. Documentation
does not require removed sidecars, depend on debug layout as an API, claim cache
revalidation, or add new provisioning/retention restrictions. Artifact contracts
preserve their payload schemas and logical paths.
**Validation:** exercise maintained subprocess examples with a fake provider and
compare resulting files/report. Check all references to the removed receipt,
old cache families, and legacy flags; retain necessary migration/history mentions.
## Stage 41: Refresh Configuration, CLI, And LLM Internal Guides
**Goal:** explain the actual native composition and execution boundary.
**Inspect/change:** `docs/internal/{configuration,cli,llm}.md` ; the final
configuration definition, composition-root loaders, command declarations, engine
construction, and native producer/validator call sites.
**Work:** document one result handoff, source assembly, invocation reuse, standard
suite wiring, request overrides, native execution/continuation, and application
interpretation. Keep `llm.md` as an integration-focused explanation even though
its old package is removed. Link canonical operator and upstream contracts rather
than reproducing their fields, flags, or library mechanics. Remove old schemas/
asset registration, provider-neutral adapters, scheduler, profile recording, and
inspection-conversion descriptions.
**Acceptance:** a contributor can locate the current owner without being sent to
a deleted wrapper. Native execution types are explicit; pure domain types remain
separate. Volatile public details have one canonical owner.
**Validation:** inspect the named packages and focused tests for every flow;
check cross-links and stale package references.
## Stage 42: Refresh Pipeline And State Internal Guides
**Goal:** explain acceptance, concurrency, recovery, and capture as implemented.
**Inspect/change:** `docs/internal/{pipeline,state}.md` ; typed helper/assessment,
worker coordinator, eligibility propagation, cache/store, recorder, and publication.
**Work:** document initial/revised assessment, native semantic continuation,
strict/permissive terminal handling, supported fallback, ready-job workers,
generated-reference eligibility, accepted-artifact/plan reuse, and output/debug
ownership. Remove checkpoint fingerprints/resume, old chunk-plan canonicalization,
duplicate usage/debug wrappers, required manifest/receipt, and generic retry flows.
Link public state controls, artifact paths, and output contract definitions.
**Acceptance:** current-flow descriptions distinguish native execution success,
domain acceptance, qualified fallback, reuse, and publication. No internal guide
promises a public debug layout or cache revalidation policy that does not exist.
**Validation:** compare diagrams/prose with runner/cache/recorder and focused
tests; verify no stale state collaborator or operation ordering is carried forward.
## Stage 43: Refresh Module And D&D Contributor Guides
**Goal:** future modules can follow the native architecture without copying drift.
**Inspect/change:** `docs/internal/{modules,dnd}.md` ; production registration,
representative spell producer, registry normalizers, scene chunker/validator,
native initial/correction assets, codecs, and shared domain helpers.
**Work:** show how a module prepares fixed inputs, builds initial/correction native
requests, interprets results, supplies fallback, and receives pipeline assessment.
Document static dependency declarations and native prompt/schema ownership instead
of manifests/registration. Explain one-time normalization handles, fresh proposal
application, domain guidance, unchanged contextual-ID/source-reference rules, and
deterministic paths without synthetic requests. Link durable schemas and public
module configuration rather than repeating them.
**Acceptance:** the extension recipe works for the actual typed interfaces and
retains artifact-family/domain boundaries. It requires no private completion
interface, schema registry, fingerprint, or module-owned retry engine.
**Validation:** walk the recipe against one extraction and one normalization
implementation; inspect native asset paths/IDs and retained domain regression tests.
## Stage 44: Align The Kit Integration Contracts
**Goal:** describe Notarius's actual use of all three native libraries.
**Inspect/change:** `docs/integrations/{pkg-configkit,pkg-promptkit}.md` ; create
`docs/integrations/pkg-commandkit.md` for the implemented CLI integration. Inspect
selected public APIs, final module versions, source/engine loaders, standard suite
wiring, request execution, and reporting.
**Work:** update supported integration/version references and Notarius's supplied
configuration, source contexts, runtime/request values, outcomes, and ownership.
Document the single application result/focused views, native prompt/schema
selection, continuation/admission, and standard CLI composition at the consumer
boundary. Link tagged upstream guides for native mechanics and canonical local
docs for product policy. Describe no unused future API, full copied upstream
manual, compatibility adapter, or private implementation as a public protocol.
**Acceptance:** the integration docs agree with declared dependencies and current
calls; CommandKit/ckconfig/ckprompt adoption is complete, not deferred. Notices and
integration source links resolve to the intended components/revisions.
**Validation:** inspect imports/call sites and local/upstream link destinations;
compare claims with Stage 37's assembled boundary tests.
## Stage 45: Refresh Orientation And Reconcile Planning Status
**Goal:** entry points lead to current docs and preserve separate future scope.
**Inspect/change:** `docs/internal/overview.md` , `docs/development.md` , `README.md` ,
and `docs/roadmap/future.md` , plus status in this plan and the feature roadmap.
**Work:** update package inventory/navigation for the actual composition root,
producer helper, cache, and recorder. Remove obsolete receipt/LLM-package reading
directions. Give README the shortest valid native `notarius run` quickstart and
links to the two examples, current reference docs, and migration guide. Link the
new kit integration contract where useful. Reconcile backlog items implemented
by this cutover without adding deferred features. Mark stages complete only from
actual evidence; leave final verification pending until Stage 46. Do not delete
the active plan/feature roadmap or prepare a release in this stage.
**Acceptance:** orientation describes implemented behavior and routes to canonical
owners. Future scope stays in the backlog; historical ADR/release/archive records
are not rewritten to match new syntax.
**Validation:** check quickstart/example paths and navigation, then search current
docs/examples for stale names while retaining meaningful migration/history mentions.
## Stage 46: Verify The Complete Native Cutover
**Goal:** finish only when the full end state is supported by current evidence.
**Inspect/change:** the assembled repository, feature roadmap acceptance matrix
and removal inventory, stage evidence, maintained examples, dependencies/notices,
and documentation links. Make final focused corrections where evidence exposes
an actual gap; do not invent another feature or compatibility layer.
**Work:** verify every acceptance row against tests or direct inspection of its
owning boundary. Close compilation blockers recorded during intermediate stages.
Confirm all production LLM roles use the one engine/native path, domain artifacts
are unchanged, new standard commands/loaders share configuration, and no completed
decision remains deferred to a later CommandKit adoption. Confirm old adapters,
retry loops, global limits, schema registration, both legacy caches, required
reporting sidecars, and copied accounting have no current consumers. Review
dependency attribution and absence of permanent replacement modules.
Run final development checks with declared dependencies and no sibling workspaces:
```sh
GOWORK=off go test ./...
GOWORK=off go vet ./...
GOWORK=off go build ./cmd/notarius
git diff --check
```
Use a temporary binary destination if an ordinary build would leave an untracked
binary. Also run maintained example/preflight and representative native help/
version/completion/format checks not already covered by the default suite.
Inspect removal matches in current Go/config/example files, rather than requiring
historical docs to contain none. Check local links with a small read-only checker
or manual verification if the repository has no link-check facility.
**Acceptance:** final tests/vet/build pass; retained domain regressions and all
meaningful cross-boundary cases have coverage; examples and canonical docs agree
with the executable. Native timeout/cancellation, structural-failure status,
final-turn assessment, fallback disclosure/eligibility, cache hits, worker liveness,
and post-publication errors are verified. No live-model run, production key,
release publication, permanent new gate, or comprehensive performance benchmark
is required. Report any genuinely unverified result instead of declaring success.
## Coverage Map
| Feature-roadmap target | Primary stages |
| --- | --- |
| U1 dependency baseline and native handoff | 1– 7, 35 |
| U2 embedded/native prompt and schema ownership | 4– 5, 12– 24, 35 |
| U3 typed modules and shared producer assessment | 8– 12, 24 |
| U4 prompt pairs, guidance, complete revalidation | 9– 23, 37 |
| U5 native retries and semantic-turn allowance | 3, 9– 10, 13– 24 |
| U6 strict/permissive outcomes and supported fallbacks | 3, 9– 24, 27– 28, 34, 37 |
| U7 workers and native backend admission | 3, 17, 25, 37 |
| U8 accepted-artifact and chunk-plan cache | 3, 11, 26– 28, 37 |
| U9 native execution facts, artifact delivery, capture | 11, 29– 31, 34, 37 |
| U10 complete native CLI and shared offline preflight | 5– 7, 32– 34, 36– 37 |
| Successor decisions, canonical docs, migration, backlog | 38– 45 |
| Entire acceptance matrix and removal inventory | 35, 37, 46 |
No architectural decisions remain open for this implementation. Private API names,
debug filenames, and routine serialization choices stay within the selected
boundaries; they do not require another decision cycle or stronger contracts.