2101 lines
133 KiB
Markdown
2101 lines
133 KiB
Markdown
# 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
|
||
semantics. This document owns execution order and stage completion. Completion
|
||
markers below record finished stages. The inspected application baseline is Notarius commit
|
||
`b3664d587914b1d7b0377f25fa377b57fa97c815`; its recent roadmap commits have not
|
||
implemented the migration.
|
||
|
||
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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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
|
||
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
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
**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.
|