Remove completed planning documents

This commit is contained in:
2026-11-22 09:51:45 +00:00
parent f069a10c78
commit 7faa4a0506
9 changed files with 7 additions and 5543 deletions

View File

@@ -49,7 +49,7 @@ implementing changes. It owns implementation discipline and local commit rules.
| Output, accepted-result reuse, or debug artifacts | [Run State Internals](internal/state.md), [Operations](operations.md), and [Configuration](config.md) | These separate implementation details, operator behavior, and configuration contracts. |
| External input formats, artifact schemas, or durable output files | [Integration Contracts](integrations/) | Integration documents define external and durable data contracts. |
| Repository-specific release commands or diagnostics | [Source Releases](release.md) | The runbook supplies publication commands and recovery procedures. |
| Implementation status or future scope | [Implementation plan](roadmap/implementation.md), [native migration target](roadmap/promptkit.md), and [separate backlog](roadmap/future.md) | The plan records verified work and remaining acceptance; the target owns cutover requirements and the backlog keeps other work separate. Implemented behavior belongs in canonical documentation. |
| Future scope and planning | [Future work](roadmap/future.md) | The backlog records proposed work; active feature and implementation plans live alongside it when present. Implemented behavior belongs in canonical documentation. |
For an existing subsystem, also inspect its focused tests and the package-local
types and contracts before changing behavior.

View File

@@ -1,322 +0,0 @@
# Policy Alignment Implementation Plan
## Purpose And Execution Contract
Implement [Standard Repository Policy Alignment](policy.md). That feature
roadmap owns the target policy choices and justified Notarius exceptions; this
document owns implementation order. It replaces the completed kit-upgrade plan,
not the implementation or contracts delivered by that earlier work.
Each numbered stage is one bounded prompt for a gpt-5.6-terra coding agent.
Complete stages in order. Inspect the worktree before each stage, preserve
unrelated work, validate the resulting documentation, and commit the coherent
stage under agent policy. Report changed files, checks, and any concrete blocker.
Do not push, tag, publish, or retire unrelated roadmaps.
This is a documentation/policy migration. Do not change application code,
dependency pins, tests, release scripts, runtime contracts, or release gates.
No production credentials or model calls are needed.
## Fixed Sources And Adoption Rules
Use upstream full commit
`d84a38ebab26f048cafbe59a2246700c35d29843` throughout.
Begin with its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Read applicable local policies through `docs/development.md`; when revising a
policy, also read the upstream counterpart and affected cross-policy provisions.
Do not reconstruct historical adoption baselines.
Retrieve pinned files through public URLs or `git show` against that exact
commit in an available checkout. Do not use an unverified sibling working tree
or silently select newer upstream content. An unavailable source is a concrete
blocker to copying it accurately, not a reason to invent its text.
For every adopted policy:
- Copy upstream wording verbatim except for required template removal and the
agreed, substantive project-specific customizations in the feature roadmap.
- Retain its upstream Base Policy Version; set Last Updated to the actual date
the local document is adopted, not the review date by habit.
- Add Upstream Source pointing to its own file at the full selected commit:
`https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md`.
- Remove the entire Base Policy Template section and perform its instructions.
Keep upstream generic rules outside it, including commit-pinned example links.
- Explain substantive local exceptions briefly where they apply, or retain an
existing rationale/ADR link. Do not create an exception registry or preserve
stylistic paraphrases merely because they already exist.
Current public project and adoption-guide links are discovery links; they may
follow main. Source, example, and attribution links stay commit-pinned. Preserve
accurate preexisting example pins supplied by the selected OSS template.
Metadata must reflect only documents actually adopted by the current stage.
The transition may temporarily contain mixed versions without claiming otherwise.
## Stage 1 — Establish Provenance And Copied-Policy Licensing
**Status:** Complete (2026-09-28).
**Goal:** Establish the self-contained adoption and licensing foundation.
One prompt limited to two short policies and their actual notice materials.
**Read:** Selected upstream `docs/policy/meta.md` (1.0),
`docs/policy/oss.md` (1.8), `COPYRIGHT`,
`examples/licensing/policy-attribution.md`, and the adoption guide;
local `COPYRIGHT`, `LICENSE`, and the feature roadmap.
**Files:** Create `docs/policy/meta.md`, `docs/policy/oss.md`,
`docs/oss/attribution.md`, and
`docs/oss/licenses/CC-BY-SA-4.0.txt`; update `COPYRIGHT`.
1. Adopt meta and OSS using the fixed-source rules. Keep public discovery URLs
in meta and link to the existing local developer guide and new attribution.
Point project-specific OSS context to Notarius's grant and release runbook;
do not import generic example projects.
2. Create attribution with `# Open Source Attribution Notices` followed by
the canonical policy entry. Replace all three UPSTREAM_COMMIT placeholders.
Initially identify the two newly adopted policy files as adapted material.
Later stages expand this statement as their material is actually adopted;
do not imply that the older five files have already been refreshed.
3. Copy the complete CC BY-SA 4.0 standard text from the pinned reference asset.
Preserve the canonical copyright/SPDX/notices/source arrangement and its
modification indication. Do not add research or compliance prose.
4. Add a distinct scope statement to COPYRIGHT: policy material adapted from
Standard Repository Policies remains CC-BY-SA-4.0, with attribution defining
the affected material. Keep the existing GPL-3.0-or-later application grant,
warranty disclaimer, and third-party statement; leave root LICENSE unchanged.
5. Do not create placeholder dependency entries. Dependency inventory is assigned
to Stages 4–5, and remains tracked here rather than asserted complete.
**Acceptance:** Both policies have correct versions, date, file-specific source
links, and no template-only section. All new relative links resolve. Attribution
describes this stage's actual material, and code licensing is unchanged.
**Validation:** Compare copied policy bodies and license text to the pinned
sources; inspect deliberate substitutions. Run `git diff --check` and review
the COPYRIGHT diff. No Go tests are needed.
## Stage 2 — Standardize General Policies And Selective Orientation
**Status:** Complete (2026-09-28).
**Goal:** Adopt the general rules and their reading workflow. One prompt:
three largely verbatim policy updates plus small orientation edits.
**Read:** Local agent/testing/documentation policies; pinned upstream versions
1.3, 1.3, and 1.11 respectively; upstream `agents/AGENTS.md` and the adoption
guide's Policy Reading Guide; local `AGENTS.md` and `docs/development.md`.
**Files:** Update `docs/policy/agents.md`, `testing.md`,
`documentation.md`, root `AGENTS.md`, `docs/development.md`, and
`docs/oss/attribution.md`.
1. Adopt agent and testing substantive wording without local paraphrases.
Remove the redundant agent preamble, additional generic contract-preservation
prose, and ADR-0017 illustration. Its decision remains in architecture/ADR;
this is not permission to change it.
2. Adopt documentation wording and ownership rows. Customize the consumer row
for existing subprocess guidance, not a hypothetical public Go API.
Omit the inapplicable HTTP contract row; preserve applicable CLI/config/
operations/integration/internal ownership. Remove the local duplicate
implementation-details-versus-policy section.
3. Base root AGENTS.md on upstream `agents/AGENTS.md`, not upstream root
AGENTS.md. Preserve applicable existing instructions. Require orientation
through the developer guide and agent policy, but not full-suite reading.
4. Add the adoption guide's seven-row selective Policy Reading Guide and its
selection/reuse/scope-expansion rules to docs/development.md. Retain existing
subsystem navigation and validation guidance; remove redundant competing
policy-trigger rows from the old table rather than creating two authorities.
5. Expand the attribution material statement to identify the newly refreshed
policy files, adapted AGENTS.md, and copied policy-reading-guide portion of
docs/development.md. Do not license the unrelated remainder as copied policy.
Ensure the COPYRIGHT scope statement covers these identified portions.
**Acceptance:** General rules match upstream, except required documentation
ownership customization. All seven policy triggers are available; existing
subsystem links still work. Reading is selective and public discovery is reachable.
No test changes or stricter testing/commit requirements were introduced.
**Validation:** Diff each policy against its pinned source, inspect AGENTS and
developer-guide navigation, check attribution scope and relative links, and run
`git diff --check`. Search affected files for leftover template instructions.
## Stage 3 — Align Architecture And Release Policies Without Contract Changes
**Status:** Complete (2026-09-28).
**Goal:** Complete the customized policies and release navigation. One prompt
focused on preserving existing decisions rather than redesigning them.
**Read:** Local architecture and release policies, docs/release.md, relevant
linked ADRs; pinned upstream architecture 1.3 and release 1.4. Use
docs/internal/overview.md and existing canonical contracts only where needed to
resolve an ownership question.
**Files:** Update `docs/policy/architecture.md`, `docs/policy/release.md`,
`docs/release.md`, and `docs/oss/attribution.md`.
1. Adopt upstream general architecture ownership/approach guidance. Replace its
application-specific template guidance with Notarius's existing decisions.
Preserve the feature roadmap's enumerated pipeline, module, assets, domain,
identity, validation/retry, scheduling, configuration/provenance, state,
secret-handling, permissions, platform, and distribution contracts.
Keep existing application-specific sections unless an edit is necessary for
the adopted structure; do not turn this into a broad architecture rewrite.
2. Adopt release wording with narrow project customizations: source only,
lightweight tags, main/origin, branch-before-tag, no prereleases, and no
hosted/asynchronous deliverables. Keep the native CLI/version check and
GOWORK=off rationale. Preserve the historical no-retrospective-notes decision.
Retain unchanged generic requirements verbatim.
3. Add the OSS footer rule for new notes. Update the runbook with a copyable
three-link COPYRIGHT | LICENSE | ATTRIBUTION footer using absolute
`https://gitea.maximumdirect.net/eric/notarius/src/tag/<version>/...` paths.
Explain substitution of the selected release tag and local path checking.
Do not require a future tag to resolve or change publication scripts.
4. Expand policy attribution to the complete adopted docs/policy set, retaining
the AGENTS/developer-guide scope from Stage 2 and any relevant adaptation
indications. All seven per-document source links now identify this adoption.
**Acceptance:** Existing architecture and release choices are unchanged and their
local reasons remain clear. Upstream generic wording is used where applicable.
There are no new gates, platforms, artifacts, retrospective notes, or ADR edits.
**Validation:** Review policy diffs specifically for added/removed requirements,
check runbook agreement and affected links, and run `git diff --check`.
Do not run a release/publication command. No runtime tests are warranted.
## Stage 4 — Attribute The Kit Dependencies And Catalogs
**Status:** Complete (2026-09-28).
**Goal:** Add the first bounded group of component notices: ConfigKit,
PromptKit, and their two backend catalogs. One prompt for four related projects.
**Read:** Adopted OSS policy; go.mod/go.sum, resolved build dependency metadata;
exact selected module COPYRIGHT/LICENSE/NOTICE/attribution files and VCS metadata.
The reviewed pins are ConfigKit v0.4.1, PromptKit v0.11.1, and both catalog
modules v2.20260926.0; verify the actual selected versions before writing.
**Files:** Update `docs/oss/attribution.md`; add applicable texts under
`docs/oss/licenses/`.
1. Use read-only discovery such as `GOWORK=off go list -m -json all`,
`GOWORK=off go list -deps ./cmd/notarius`, and selected module contents.
Dependency acquisition may populate the module cache but must not change
dependency pins or introduce a local replace directive.
2. Establish each selected version's exact source commit from module/VCS
metadata; peel annotated tags to commits. Do not substitute a tag object ID,
main-branch head, assumed sibling HEAD, or version tag in attribution URLs.
3. Add factual House Format entries with supplied copyright statements,
applicable SPDX expressions, local standard-text links, required upstream
notice links, and exact-commit Source links. Preserve alternatives and
exceptions; determine scope from contents rather than filenames.
4. Include LGPLv3 and its GPLv3 companion for the kit grants, and MIT for the
catalogs where confirmed by the pinned sources. Reuse shared local standard
texts; leave root project LICENSE unchanged.
5. Inspect upstream dependency inventories for leads, but do not copy them
wholesale or treat them as substitutes for Notarius's own inclusion scope.
Hand remaining selected third-party components to Stage 5 through the stage
report, not editorial prose in attribution.
**Acceptance:** These four components have verified source/notice links and
complete applicable local texts. No dependency changes, guessed notices, or
new distribution obligations were invented.
**Validation:** Check exact revision correspondence, upstream filenames, every
new local license link, and byte fidelity of standard texts. Run
`git diff --check`; confirm go.mod/go.sum are unchanged. Report discovery
commands and evidence; do not add a persistent inventory tool or audit artifact.
## Stage 5 — Complete Attribution And Connect Reader Navigation
**Status:** Complete (2026-09-28).
**Goal:** Finish remaining incorporated-component coverage and canonical
navigation. One prompt for the remaining small dependency set and doc links.
**Read:** Adopted OSS policy, remaining selected module/source notices,
README.md, integration guides, and repository evidence of copied code/assets.
Start with jsonschema/v6 v6.0.2, x/text v0.40.0, yaml.v3 v3.0.1, and yaml/v4
v4.0.0-rc.6, then resolve any additional actual incorporation revealed by
Stage 4. A go.sum entry alone is not proof of incorporation.
**Files:** Update `docs/oss/attribution.md`, applicable
`docs/oss/licenses/*`, `README.md`,
`docs/integrations/pkg-configkit.md`, and
`docs/integrations/pkg-promptkit.md`.
1. Inspect direct/transitive incorporation and copied material separately.
Apply the same exact-revision, factual-entry, and faithful-text rules as
Stage 4. Include relevant components, not every tool used in development.
Do not add generic entries with unresolved versions or copyrights.
2. Use the OSS format for omitted copyright/SPDX fields where the source
supplies no applicable value. Preserve required project-specific notices.
Raise only a concrete unresolved obligation or rights issue; do not seek
blanket approval for the already selected linked-notice arrangement.
3. End README with the prescribed GPL-v3-or-later COPYRIGHT link and the
Open Source attribution notices link. Do not imply that every incorporated
component or document has the application's license.
4. Replace competing license/notice paragraphs in both integration guides with
concise links to the relevant canonical attribution anchors. Keep dependency
pins, behavior, compatibility, and public API links in the guides.
5. Keep the attribution document to its title and factual component entries.
Do not include the inventory research, legal conclusions, or completion logs.
Do not copy unused upstream examples or standard licenses.
**Acceptance:** Attribution covers the verified relevant components and copied
policy material, with only applicable texts. README and integration links point
to the canonical inventory; no user-visible API or dependency settings change.
**Validation:** Review coverage against resolved dependencies and inspected
copied-material evidence, validate affected relative/source links and text
fidelity, and run `git diff --check`. No Go suite, scanner, or SBOM is required
solely for documentation changes.
## Stage 6 — Verify The Complete Adoption
**Status:** Complete (2026-09-28).
**Goal:** Perform the cross-document check and correct scoped documentation
defects. One prompt; no fresh feature work or automated policy-sync system.
**Read:** The feature roadmap; the seven resulting policies and their pinned
sources; AGENTS.md, developer guide, COPYRIGHT, README, attribution/license
materials, release runbook, and affected integration links.
**Work and acceptance:**
1. Compare all seven policies directly against the selected revision. Classify
remaining differences as metadata, template removal, required customization,
or a feature-roadmap exception. Replace accidental paraphrases with upstream
wording. Preserve established local requirements.
2. Confirm versions 1.3/1.3/1.11/1.3/1.4/1.0/1.8 for agents, architecture,
documentation, testing, release, meta, and OSS respectively. Verify each
Upstream Source targets its own file and Last Updated reflects actual work.
3. Confirm discovery links follow public project/main-guide URLs while adopted
source, examples, and component attribution remain accurately commit-pinned.
Check no placeholder UPSTREAM_COMMIT, template-only section, or local
checkout-dependent reference remains in adopted materials.
4. Check selective policy routing, local authority, canonical documentation
ownership, copied-material scope/modification status, unchanged application
grant/root LICENSE, and directly reachable license/companion texts.
5. Verify source-only publication, selected gates, optional diagnostics,
release completion, and prospective-only footer guidance still agree.
Do not modify historical notes, accepted ADRs, or scripts to satisfy this check.
6. Review changed-file scope: only intended policy, notice, and supporting
documentation files should have changed. Correct in-scope documentation
defects, report unresolved concrete issues, and leave unrelated roadmap
retirement and release preparation to an explicit later request.
**Validation:** Run `git diff --check`; inspect file/link destinations and
compare local standard texts with verified sources. A search for
`Base Policy Template` or `UPSTREAM_COMMIT` in adopted files should be empty;
do not confuse explanatory roadmap text with an unfilled adopted template.
No production tests, new test framework, recurring synchronization gate, or
release execution is needed.
## Open Questions
None at the agreed baseline. Policy choices and exceptions are settled.
A newly discovered concrete notice/source or rights issue should be reported
with evidence and viable treatments rather than resolved by inventing a broader
requirement. That contingency does not authorize reopening settled policies.

View File

@@ -1,252 +0,0 @@
# Standard Repository Policy Alignment
## Purpose
Bring Notarius's adopted policies into alignment with Standard Repository
Policies, using identical upstream language wherever a substantive,
project-specific decision does not require customization. Preserve Notarius's
application contracts, operator choices, selected code license, and source-only
release process.
This roadmap defines the agreed target and update scope. It does not itself
adopt policies, alter runtime behavior, or authorize a release.
## Selected Upstream Revision And Current Baseline
The agreed review, performed on 2026-09-28, uses full upstream commit
`d84a38ebab26f048cafbe59a2246700c35d29843` of
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
Follow the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Use that fixed revision for implementation, not whichever revision is then on
`main`.
The comparison is between the current Notarius documents and that revision.
Historical adoption baselines need not be reconstructed or assessed. Introducing
source metadata records the revision actually incorporated by this update, not
a claim about previous adoptions.
Notarius currently has five policies, no `meta.md` or `oss.md`, and no
`docs/oss/` attribution collection. Its current agent entry point and developer
guide provide orientation but lack the complete selective policy-reading guide.
The project grant is GPL-3.0-or-later; root `LICENSE` contains the GPLv3 text.
README licensing navigation and prospective release-footer instructions are
missing.
Public upstream discovery and attribution are now expressly approved. This
supersedes the earlier instruction to omit references to the policy source;
local checkout paths are neither necessary nor appropriate public references.
## Alignment Rules
- Start from the selected upstream wording, not a paraphrase of it. Adopt
non-substantive wording changes verbatim.
- Retain local variations only for substantive, locally significant
requirements or decisions. Explain their purpose in the relevant policy
section or link to existing rationale; do not add a separate exception registry.
- Follow each template's adoption instructions and remove its entire
`Base Policy Template` section. Replace required project-specific guidance
rather than leaving template instructions in an adopted policy.
- Preserve deliberately selected contracts. Simplifying duplicate wording does
not authorize changing architecture, runtime behavior, or release mechanics.
- Keep local policies authoritative. Upstream changes take effect only through
deliberate adoption; no automatic synchronization is introduced.
## Target Policy Set And Justified Customizations
| Local file | Current version | Target version | Required treatment |
| --- | --- | --- | --- |
| `docs/policy/agents.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Remove redundant local preamble and the ADR-0017 illustration; architecture already owns the deployment-permissions decision. No substantive exception is needed. |
| `docs/policy/architecture.md` | 1.1 | 1.3 | Adopt general purpose, ownership, architectural approach, and constraint-versus-implementation guidance while retaining the application-specific decisions described below. |
| `docs/policy/testing.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Existing risk-based testing remains intact; no project-specific exception or test rewrite is needed. |
| `docs/policy/documentation.md` | 1.3 | 1.11 | Adopt upstream wording and licensing/provenance ownership rows. Customize consumer ownership for subprocess use and omit the inapplicable HTTP-contract row. Remove the duplicate local implementation-details-versus-policy section; agent policy owns that rule. |
| `docs/policy/release.md` | 1.1 | 1.4 | Adopt upstream wording with the existing source-only choices and selected gates below. Add prospective OSS-footer guidance. |
| `docs/policy/meta.md` | Absent | 1.0 | Add upstream substantive wording, including public discovery links, local authority, and local attribution navigation. |
| `docs/policy/oss.md` | Absent | 1.8 | Add upstream substantive wording, commit-pinned example links, and required Notarius context through canonical documents. |
No existing policy remains entirely unchanged: all five need wording and/or
provenance updates. This does not imply new substantive testing or agent rules.
### Architecture Exceptions
The architecture template expressly requires application-specific content.
Retain Notarius's fixed stage sequence rather than an arbitrary DAG,
artifact-family ownership across stages, domain-neutral framework, inward
dependency direction, external adapter boundaries, and content-only assets
package. Retain adopted validation/retry, scheduling, identity, evidence,
configuration, and provenance contracts.
Preserve operator-owned filesystem access policy and the separately adopted
correctness boundaries, cache/checkpoint eligibility, output/debug lifecycle,
secret handling, and platform/distribution decisions. These express existing
product requirements and ADR-backed choices, not stylistic variations.
Use existing architecture and ADRs as their authority; this migration does not
authorize strengthening or weakening them.
Keep concrete package inventories and implementation mechanics in their current
internal-documentation homes. No architecture redesign, new threat model, or
new abstraction is part of this work.
### Documentation Exceptions
Notarius's consumer interface is primarily a subprocess CLI, not a public Go
API. Retain `docs/consumers/` ownership for that workflow and its consumer
responsibilities. Retain integration contracts as the owners of durable receipt
and artifact shapes. No HTTP service documentation or placeholder API document
is needed.
Other editorial variations should use upstream language, including the current
versus future behavior and accepted-ADR rules. Preserve their meaning without
retaining duplicate local formulations.
### Release Exceptions
Preserve source-only delivery, lightweight tags, `main` on `origin`,
branch-before-tag publication, and no prereleases. There are no binaries,
hosted release objects, or asynchronous artifacts to publish or recover.
Use upstream generic language where applicable, but do not introduce those
channels or atomic-push requirements.
Retain the native CLI build and injected-version check with `GOWORK=off`:
it protects the executable entry point and release version, which package tests
alone do not verify. Preserve its documented rationale and existing optional
diagnostics. No additional validation gate is warranted.
Retain the decision not to create retrospective notes for v0.1.0, v0.2.0, or
v0.3.0. Apply new footer formatting prospectively; do not rewrite published
history to retrofit it.
## Provenance And Selective Reading
Each of the seven policies must retain its actual target `Base Policy Version`,
set `Last Updated` to its actual local adoption date, and add an
`Upstream Source` link to its own source file. For example:
```text
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md
```
Substitute the correct filename for each policy; do not link every header to
the repository root or adoption guide. Retain provenance through subsequent
local edits.
Use current public discovery URLs in `meta.md`:
- https://gitea.maximumdirect.net/eric/policy
- https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md
Discovery links intentionally follow the current project and guide.
Adopted-source, example, and attribution links identify immutable commits.
The OSS template already includes commit-pinned example references; retain
accurate pinned references rather than converting them to branch links.
Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
existing instructions. Direct readers to `docs/development.md`, require agent
policy before recommending/planning/implementing changes, and explicitly avoid
reading the whole policy suite by default.
Merge the upstream adoption guide's Policy Reading Guide into
`docs/development.md`. Include all seven task triggers, especially policy
updates, dependency/licensing changes, validation selection, and compatibility
decisions. Preserve focused subsystem navigation without duplicating policy
triggers across competing tables. Reuse policies already in context, expand
reading when scope expands, and read affected cross-policy provisions when
revising a policy.
## Licensing And Attribution Target
### Copied Policy Material
Follow the selected upstream grant and canonical policy-attribution example:
- Create `docs/oss/attribution.md` with the House Format title and insert the
Standard Repository Policies entry using the selected full commit for its
source, COPYRIGHT, and LICENSE URLs.
- Identify actual copied/adapted material and modification status. Include
`docs/policy/`, the adapted root `AGENTS.md`, and the copied policy-reading
guide within `docs/development.md` as applicable. Do not claim unrelated
developer documentation was copied or relicense unrelated material.
- Preserve supplied copyright, license, and disclaimer notices through the
specified arrangement; keep the entry factual rather than adding compliance
or research commentary.
- Copy the complete, verbatim `CC-BY-SA-4.0.txt` to `docs/oss/licenses/`.
- Add the separately licensed policy-material scope to `COPYRIGHT`, pointing
to attribution for exact scope and notices. Adapted policy material remains
CC-BY-SA-4.0; application code remains GPL-3.0-or-later. Leave root `LICENSE`
unchanged.
The upstream licensing-format examples are CC0; using their original formatting
alone does not require a separate attribution entry. This does not exempt
copied policy prose from its stated terms.
### Incorporated Dependencies And Assets
Complete the previously planned inventory of relevant direct/transitive
dependencies and copied code/assets using `go.mod`, resolved build dependencies,
and exact pinned source contents. Neither direct imports alone nor every
`go.sum` entry defines the inventory.
Current starting points are ConfigKit v0.4.1, PromptKit v0.11.1, both PromptKit
backend catalogs v2.20260926.0, jsonschema/v6 v6.0.2, x/text v0.40.0, yaml.v3
v3.0.1, and yaml/v4 v4.0.0-rc.6. Verify actual incorporation, terms, notices,
and exact commits; this list is not a pre-approved attribution inventory.
Use the upstream OSS House Format without editorial elaboration. Copy only
applicable standard and companion license texts, retaining their wording.
Link component-specific notices and sources at the exact imported commit.
Apply the upstream house interpretation of linked notices without inventing
extra local-copy requirements, recurring approvals, or licensing conclusions.
Handle a concrete uncovered obligation separately if one is discovered.
### Navigation And Canonical Ownership
- End `README.md` with the project-grant and attribution links prescribed by
OSS policy, using Notarius's GPL-3.0-or-later grant.
- Update `docs/release.md` with a copyable prospective
`COPYRIGHT | LICENSE | ATTRIBUTION` footer using absolute Notarius URLs at
the release tag or corresponding immutable source revision. Check intended
local paths before publication; do not require an unpublished tag to resolve.
- Update `docs/integrations/pkg-configkit.md` and
`docs/integrations/pkg-promptkit.md` to link to canonical attribution rather
than maintaining competing notice inventories. Keep behavioral/API references
in those integration guides.
## Local Materials And Upstream-Only References
Keep the seven adopted policies, adapted agent entry point, project-specific
developer guide, actual notices, and applicable license texts locally.
Keep the upstream README, root AGENTS.md, contributor guide, adoption guide,
and example collection upstream. Link to them when appropriate instead of
copying an additional documentation tree. Do not copy unused license texts,
example projects, or placeholder documents. Root Notarius `AGENTS.md` is based
on upstream `agents/AGENTS.md`, not upstream's own contributor instructions.
## Implementation Ownership
[Implementation Plan](implementation.md) owns the ordered work stages and their
validation. This document owns the target end state, scope, and policy choices.
## Scope Boundaries And Acceptance
- No application code, dependency pins, tests, release scripts, or published
history change merely to adopt policy wording.
- No new ADR, recurring policy-sync job, SBOM, scanner, blanket header sweep,
security audit, platform matrix, approval round, or release gate is required.
- All seven policies use the selected versions and correct file-specific source
links, with actual adoption dates and no remaining template-only sections.
- Non-substantive differences use upstream wording; substantive variations are
confined to justified Notarius responsibilities and decisions.
- Orientation supports selective reading and public upstream discovery without
requiring a sibling checkout.
- Attribution accurately identifies copied material, modifications, selected
dependency revisions, notices, and faithful local license texts. Application
and policy-material license scopes remain distinct.
- Canonical navigation works without duplicate notice inventories, nonexistent
interface documents, or copied upstream guide/example collections.
- Validate affected relative and public links, metadata targets, license-text
fidelity, and `git diff --check`. Ordinary document review is sufficient;
production model runs and new runtime tests are not warranted.
- Resolve only concrete newly discovered rights or scope issues with the user;
do not reopen settled choices through blanket approval requirements.
There are no blocking open design decisions at the agreed review baseline.

View File

@@ -1,124 +0,0 @@
# Kit Upgrade Review Remediation
## Resolution
Completed 2026-09-26. No production changes were needed.
- `internal/framework/llm/promptkit_observation_test.go` now covers retries in
both initial and repair generations, aggregate versus legacy accounting,
unknown/known-zero/partial usage, retry-wait cancellation, exhausted execution,
preparation failure, and overlapping request isolation.
- `internal/framework/pipeline/debug_execution_test.go` exercises the real
scheduled client and debug wrapper together. It verifies returned and persisted
summaries for provider errors and cancellation without a body, split debug and
fallback content, terminal references, and explicit usage-presence JSON fields.
- Temporary regression probes confirmed that discarding failed responses in the
scheduler and collapsing usage presence into known zero cause the new tests
to fail. Those probes were reverted.
- Focused LLM/pipeline tests, their race-enabled suites, and
`GOWORK=off go test ./...` passed. Existing no-debug and redaction coverage was
retained. Runtime budgets, scheduler policy, and output contracts are unchanged.
The original finding below is retained as review context.
## Review Scope
Reviewed implementation commits `31b48d2` through `7ac9d94` against
[the feature roadmap](upgrade-kit.md) and the completed upgrade work recorded
in those commits.
The review covered configuration selection/defaults, production client wiring,
error translation, execution observation, scheduler/debug propagation, current
documentation, and tests. No production model calls were made.
The implemented architecture is consistent with the intended design: ConfigKit
v0.4.0 owns composition and overlay provenance behind the configuration boundary;
PromptKit v0.11.0 owns transient retries and structural repairs behind the LLM
adapter. Notarius retains stage retry/disposition policy, completion-scoped
scheduling, application-owned error/observation types, and opt-in debug output.
No new runtime defect or unrequested restriction was established in this review.
## Finding 1 — Complete The Missing Retry And Observation Verification
**Priority:** Medium. This is a verification gap, not a demonstrated runtime
failure. Stages 5–7 are marked complete, but their consequential cross-boundary
acceptance tests were not implemented.
### Evidence And Risk
- `internal/framework/llm/promptkit_client_test.go:58` adds only a successful,
single-attempt observation assertion with positive prompt-token usage. It
does not exercise absent versus partial/known-zero usage, failed/canceled
execution summaries, preparation failure, or concurrent request isolation.
- `TestPromptKitClientAppliesConfiguredBuiltInTransientRetries` covers basic
status recovery, explicit zero, exhaustion, and a noneligible status. It
discards the response, so does not protect terminal accounting. There is no
combined transient-retry/structural-repair scenario or cancellation while
waiting on Retry-After.
- `internal/framework/llm/scheduled_client.go:40` now preserves a response when
the inner call fails. No corresponding test protects that behavior. Returning
an empty response again would silently remove precisely the failed-call
observations this feature is intended to retain.
- `internal/framework/pipeline/debug.go:267` and `:277` add execution summaries
to response artifacts and call references, plus fallback/content-splitting
propagation. Neither the debug nor terminal-debug tests were extended to
exercise these fields. Passing existing tests does not prove that failed-call
metadata reaches persisted records.
These are Notarius-owned integration risks, not a request to re-test PromptKit's
backoff algorithm. Losing failed-call observations or misrepresenting incomplete
usage would be difficult to detect in ordinary successful runs. A focused set
of behavioral tests is justified under the testing policy.
### Required Remediation
Use existing test assets, local HTTP fixtures, scheduler wrappers, and debug
recorders. Combine related assertions; no fixed test count or new test framework
is required.
1. Add an adapter scenario with a transient failure, a structurally invalid
completion, and a successful repair. Exercise retries in both generations
with small explicit budgets, and assert terminal attempts/retries/repair
counts without double-counting. Use controlled usage fields to distinguish
known zero, unknown, and partial aggregate usage. Preserve legacy usage
semantics independently.
2. Cover failed and canceled completions, including cancellation during a
Retry-After wait. Verify caller cancellation identity, bounded completion,
and retained execution metadata. Use signaling and a generous bounded test
timeout, not exact sleep durations or jitter assertions. Cover a preparation
failure with no execution summary. Add a small concurrent-call check for
request-local summary isolation, which race tests alone do not prove.
3. Exercise an error response through the real scheduled client and existing
debug wrapper/recorder seams. Assert that the summary reaches response
artifacts and terminal call references even without a provider response
body. Cover the content-splitting/fallback path with a representative response.
Reuse existing no-debug and redaction tests rather than duplicating their
whole inventories. Keep new summary assertions metadata-only.
Retain existing scheduler policy, stage/validator budgets, cancellation
disposition, warning semantics, and debug opt-in behavior. Do not introduce a
total deadline, new retry caps, telemetry artifacts, or live API requirements
to make these tests easier. Fix production code only if these checks reveal a
violation of the already selected behavior.
**Acceptance:** The added tests fail if failed responses lose their execution
summary at an adapter/wrapper boundary, usage presence is collapsed into zero,
or retry/repair totals are double-counted. They pass with the intended behavior
and provide evidence for the previously unverified stage acceptance criteria.
**Validation:** Run focused LLM/pipeline tests, race-enabled tests for those
packages, and `GOWORK=off go test ./...`. No production credentials are needed.
## Checks Completed During Review
- `GOWORK=off go test ./...`
- `GOWORK=off go vet ./...`
- `GOWORK=off go build ./...`
- `GOWORK=off go mod tidy -diff`
- `GOWORK=off go test -race ./internal/framework/llm ./internal/framework/pipeline`
- CLI configuration validation for the minimal and complete examples, including
the complete example with `--config-overlay development`.
- `git diff --check`
All passed. Existing green tests do not substitute for the missing behavioral
coverage above. Temporary diagnostic test material used during review was
removed; no application code was changed.

View File

@@ -1,337 +0,0 @@
# ConfigKit And PromptKit Upgrades
## Purpose
Adopt ConfigKit v0.4.0 and PromptKit v0.11.0 in one coordinated work set:
- Consistently call ConfigKit's selected configuration layer an **overlay**,
distinct from PromptKit LLM profiles.
- Adopt configurable transient HTTP retries, provider-neutral failure
classifications, and execution observations from PromptKit.
Preserve application/framework boundaries and keep the two upgrades as distinct
implementation workstreams. Neither requires a redesign of pipeline execution.
This feature roadmap records the target state and scope. Its original
implementation plan was completed and later replaced by a new work plan.
Neither document authorized release publication.
## Current Baseline
The reviewed baseline is Notarius v0.7.1 (`53d9284`):
- `go.mod` pins ConfigKit v0.3.0 and PromptKit v0.10.0.
- `internal/core/config/load.go` passes `LoadOptions.Profile` into
`configkit.Options[Document].Profile`.
- `--config-profile` selects `profiles/<name>.yml` beneath the configuration
root for `run`, `config validate`, `config effective`, `config explain`, and
`pipelines list`.
- The maintained selected-layer example is
`examples/profiles/development.yml`; configuration and CLI tests create
equivalent directories and exercise selection and inspection.
- ConfigKit owns composition and inspection metadata. Notarius owns its
version 5 document, defaults, validation, source-relative path resolution,
runtime conversion, and CLI discovery.
A dependency-only trial against v0.4.0 fails to compile at `load.go:33` because
`configkit.Options.Profile` no longer exists. The review found no direct
Notarius references to `LayerProfile`, `CodeProfile*`, or `LoadSecretsDir`.
An isolated dependency-only trial against PromptKit v0.11.0 passes the complete
Notarius test suite and `go vet ./...`. That proves baseline compatibility, not
adoption of the new controls or observations. The current adapter does not
configure transient retries or attach an execution observer. It classifies
generation errors broadly and records successful-result usage and structural
repair counts. The outer scheduler holds a permit for the whole completion.
## Upstream Changes
### ConfigKit v0.4.0
The [ConfigKit v0.4.0 release guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.4.0/docs/releases/v0.4.0.md)
defines four breaking naming changes:
| Surface | Previous | Target |
| --- | --- | --- |
| Selection API | `Options.Profile` | `Options.Overlay` |
| Selected file | `profiles/<name>.yml` | `overlays/<name>.yml` |
| Provenance layer | `LayerProfile` / `profile` | `LayerOverlay` / `overlay` |
| Diagnostic identifiers | `CodeProfile*` / `profile.*` | `CodeOverlay*` / `overlay.*` |
There are no legacy aliases or directory fallback. Explicit imports from a
directory named `profiles` remain valid ordinary imports. Merge rules,
precedence, lifecycle, source-origin APIs, minimum Go version, and YAML parser
dependency are unchanged.
The intervening v0.3.1 release makes the opt-in `LoadSecretsDir` API ignore
dot-prefixed entries. Notarius does not use this API; adding secrets-directory
bootstrap is outside this work.
### PromptKit v0.11.0
The [PromptKit v0.11.0 release guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/releases/v0.11.0.md)
introduces additive runtime APIs and one changed default:
- Built-in generation defaults to two additional transient HTTP attempts for
statuses 429, 500, 502, 503, and 504. Engine and request controls can override
the count, including zero. Injected `LLMClient` implementations are not
automatically replayed; a custom HTTP client on the built-in path still is.
- Backoff is cancellable and honors valid provider `Retry-After` timing.
Generation and HTTP timeouts apply per attempt; the caller context bounds
the whole operation. Transport failures, malformed responses, other HTTP
statuses, and invalid generated content are not transient-retry candidates.
- `RunRequest.Observer` reports lifecycle metadata, attempts, waits, outcomes,
and presence-aware usage, including work before a failed execution. It works
with prepared execution; preparation itself emits no execution events.
- `ErrTransport`, `ErrMalformedResponse`, `ErrRetriesExhausted`, and
`RetryExhaustedError` support typed classification without parsing error text.
- The license changes to LGPL-3.0-or-later. Catalog selections and the minimum
Go version are unchanged from v0.10.0.
## Target End State
### Dependency And Ownership
Pin ConfigKit v0.4.0 and PromptKit v0.11.0 and tidy the dependency graph.
Continue using only ConfigKit's
public root API behind `internal/core/config`. No compatibility parser,
application-owned composition engine, or new configuration abstraction is
needed. PromptKit remains behind `internal/framework/llm`; its types must not
leak into domain modules or pipeline contracts. Retain the existing prepared
execution path, profile choices, and D&D model settings.
### Consistent Overlay Selection
- Replace the configuration-selection CLI flag with `--config-overlay` on all
commands that currently accept `--config-profile`.
- Rename application-owned fields, variables, helpers, help text, and test
descriptions that specifically represent this selection to overlay terms.
- Pass the selection through `configkit.Options.Overlay`.
- Select files only from `overlays/<name>.yml`, following ConfigKit's contract.
- Preserve empty and `default` selection as the composed base configuration
without a selected overlay.
- Use a clean cutover: no old CLI alias, directory fallback, automatic file
moves, or custom migration machinery. Normal unknown-flag handling is
sufficient for the retired flag; explain migration in documentation.
This rename is deliberately narrow. Preserve `llm_profile`, `--llm-profile`,
`promptkit.profile_dir`, `promptkit.profile_file`, `base_profile`, embedded
`dnd-extraction` profiles, and `examples/llm-profiles/`. Other application
concepts named `Profile`, including pipeline/runtime types, must not be renamed
merely because they share the word.
### Preserved Behavior
Retain configuration version 5, with the additive retry setting described below.
Preserve existing defaults other than the explicitly adopted transient retry policy,
imports, overlay merge behavior (including sequence replacement), explicit CLI
override precedence, strict decoding, domain validation, and secret redaction.
Do not add new restrictions or relax existing explicit contracts as part of the
rename.
Relative paths continue to resolve from the file supplying the surviving
declaration, including overlay files. Invocation-relative CLI paths and
main-file-relative built-in defaults retain their current behavior.
Effective configuration, explanations, and configuration-load diagnostics use
the new upstream overlay provenance and diagnostic vocabulary. Preserve source
file labels and actionable error context; do not translate the new metadata
back into legacy profile terminology.
Pipeline stage order, semantic acceptance, LLM selection, domain artifact
schemas, and subprocess result receipts remain unchanged. No blanket checkpoint
invalidation is added merely for the ConfigKit rename. Update the existing
PromptKit-version identity used by checkpoint fingerprinting with its dependency
pin, following the current adapter convention; no cache redesign is needed.
### Transient Retry Policy
Expose `promptkit.transient_retries` as a nonnegative integer setting with a
Notarius default of **2 additional attempts**. Explicit zero disables transient
retries. Apply the resolved setting to the shared PromptKit engine so modules,
normalizers, validators, and semantic correction calls receive the same policy.
Include the effective value in configuration inspection. Do not impose an
arbitrary application maximum or add per-binding controls in this work set.
Maintain three separate budgets and owners:
| Budget | Owner | Repeated work |
| --- | --- | --- |
| Transient retries | PromptKit | The same generation request after eligible HTTP failures |
| Structural repairs | PromptKit | A corrective generation for invalid structured output |
| Producer/validator retries | Notarius | The configured stage or validator operation, with semantic feedback where applicable |
Do not silently reduce, repurpose, or remove existing stage/validator budgets.
Each structural repair generation receives its own transient budget. For a
single-completion producer, two additional stage attempts, one structural
repair, and two transient retries permit up to 18 HTTP attempts, excluding any
separate validator calls. Document this multiplication and the possibility of
additional cost; retries do not imply exactly-once provider execution.
Preserve caller cancellation throughout generation and waiting. Do not describe
a profile's generation timeout as a total completion deadline: provider
`Retry-After` can extend waits beyond local backoff, and each HTTP attempt has
its own timeout. A new total-deadline configuration surface is outside this
upgrade; accurately document the current controls and limitations.
Retain Notarius's completion-scoped scheduler permit during upstream backoff.
PromptKit releases its active backend permit during that wait, but this does
not release the outer Notarius permit. This remains bounded and correct; do
not add an attempt-level scheduler redesign.
### Provider-Neutral Failure Diagnostics
Translate the new typed errors into application-owned classifications for
transport failures and malformed provider responses. Represent transient retry
exhaustion separately from its underlying failure/status, retaining the actual
attempt count where available. Preserve existing HTTP-status reporting,
capacity classification, cancellation, deadline handling, and redaction.
Do not turn a malformed provider envelope into a semantic rejection or confuse
it with a structurally invalid model response. Do not expose PromptKit error
types across the adapter boundary or parse prose to recover classifications.
Existing stage disposition policies continue to decide what happens after a
completion fails; this work does not redesign those policies.
### Execution Observations
Attach a request-local observer through the existing prepared-execution path.
Translate selected metadata into Notarius-owned completion/debug summaries:
- dispatched attempt, transient retry, and structural repair-call counts;
- capacity-wait, generation, retry-delay, and total execution durations;
- terminal outcome, failure classification, HTTP status, and exhaustion state;
- observed token counts with explicit known/complete indicators.
Retain available summaries on failed completions, including cancellation, rather
than discarding them with the absent `RunResult`. Preparation failures have no
execution observation; do not fabricate one. Keep existing successful-result
usage fields and their meanings unchanged. Observation totals are separate
presence-aware metadata, not a second set of tokens to add to existing usage.
Unknown counts are not known zero; partial totals are not a billing ledger.
Use lightweight per-request accumulation with no unbounded event history or
asynchronous queue. Callbacks are synchronous: avoid blocking I/O or acquisition
of scheduler resources inside them, and isolate concurrent requests. Persist
the projection through the existing opt-in debug path, including safe terminal
summaries where applicable. Do not serialize upstream event structs directly;
their JSON layout is not a public contract. Allowlist metadata and preserve
existing identifier/content handling and redaction boundaries.
Successful transient recovery is ordinary success, not a warning. This work
does not add routine console messages, change the warning policy, introduce a
new durable telemetry artifact, or add complete cost accounting.
## Required Changes
### Code And Examples
- Update `go.mod` and `go.sum` and the configuration loader/options boundary.
- Update CLI selection plumbing in `internal/cli/run.go` and
`configkit_commands.go`, including usage, flag parsing, argument classification,
explicit empty-value handling, and error paths.
- Move the maintained example to `examples/overlays/development.yml` and update
example discovery and related fixtures. Inspect relative paths when moving
files; do not assume all occurrences of `profiles` are configuration overlays.
- Update affected configuration and CLI tests, particularly document paths,
operational defaults, safe inspection, command selection, diagnostic source
labels, run contracts, and maintained-example coverage.
- Add the retry setting through the typed configuration document, defaults,
validation, runtime conversion, and CLI client-construction boundary. Update
the complete example to demonstrate it without adding unnecessary settings
to the minimal example.
- Update the PromptKit adapter's engine construction, request observation,
error conversion, and checkpoint version identity. Extend transport-neutral
response/debug contracts only with the application-owned metadata needed.
- Carry observations through the pipeline debug wrapper and safe terminal
reporting without double-counting usage or losing failed-call summaries.
### Documentation
Update current documentation with the implementation, keeping canonical
ownership under [Documentation Policy](../../policy/documentation.md):
- `docs/cli.md`: new flag on every affected command and matching help behavior.
- `docs/config.md`: overlay terminology, directory layout, precedence, and the
explicit distinction from LLM profiles; transient retry setting and default.
- `docs/integrations/pkg-configkit.md`: pinned release and supported upstream
naming/inspection contract.
- `docs/internal/configuration.md` and relevant CLI internals: new selection
terminology and unchanged boundaries.
- `docs/consumers/subprocess.md` and any other current callers/examples: updated
invocation syntax. Review operations and README references where applicable.
- `docs/integrations/pkg-promptkit.md`: updated pin, typed errors, observer
support, and retry contract. Refresh pinned upstream links, including its
relocated release-policy document.
- `docs/internal/llm.md` and relevant pipeline/debug internals: observation
projection, failure handling, scheduler interaction, and separate retry
budgets. Remove the obsolete claim that PromptKit has no provider retry loop.
- `docs/operations.md`: latency/cost implications, timeout limits, opt-in debug
evidence, and how to disable transient retries.
Preserve historical release notes and the accepted text of ADR-0018. Its
ConfigKit ownership decision remains valid; a terminology migration alone does
not require a new ADR or supersession. Current documentation must not portray
the old dependency pin as the current supported version.
Record PromptKit's LGPL-3.0-or-later change in the integration documentation and
eventual release note. Review its notices and distribution implications within
Notarius's source-only release model. Do not silently relicense Notarius, copy
upstream release policy into this repository, or introduce binary packaging.
Any future binary distribution needs its own license-compliance review.
## Operator Migration And Release Impact
This work belongs in the next **minor** Notarius release, not a patch, because
both the documented selected-file layout and CLI syntax change.
Operators move selected configuration files from `profiles/` to `overlays/`
and replace `--config-profile` with `--config-overlay` in scripts, service
definitions, and subprocess callers. Preserve unrelated PromptKit profile
directories and explicit imports. Review relative paths and explicit imports
that refer to moved files. No YAML body version migration is required.
The eventual release note must explain this cutover, the newly enabled transient
retries and zero-value opt-out, and the dependency license change. PromptKit's
catalogs are unchanged from v0.10.0; this upgrade adds no further profile-name
migration or change to the D&D model defaults. Release preparation,
tagging, and publication remain a separately requested task under
[Source Releases](../../release.md).
## Acceptance And Verification
- Notarius builds against ConfigKit v0.4.0 and PromptKit v0.11.0 without
compatibility shims.
- All five affected commands use the new flag; non-default overlay selection,
omitted selection, empty selection, and `default` retain their intended
behavior. The old flag is not accepted.
- Selected overlays load from the new directory. A legacy-only selected file
does not silently load; ordinary explicit imports remain supported.
- Representative tests demonstrate overlay precedence, CLI overrides,
declaration-relative paths, redacted inspection, and source-aware failures.
- Maintained examples validate, including the development overlay. LLM profile
loading and defaults remain unaffected.
- Tests prove the default transient retry policy, explicit zero, configured
counts, and negative-value rejection through the relevant configuration and
adapter boundaries. Use local HTTP test servers for eligible/noneligible
statuses, exhaustion, cancellation, and interaction with structural repair;
an injected LLM fake alone does not exercise built-in HTTP retries.
- Provider-neutral errors preserve underlying status and cancellation identity
without leaking credentials or upstream types.
- Observations are available for success and failure, preserve unknown versus
known-zero usage, avoid aggregate double-counting, and stay isolated under
concurrent completions. Successful retry recovery emits no warning.
- Representative scheduler/repair/retry checks preserve bounded execution and
cancellation; use existing coverage where it already proves the contract.
- Current documentation, help text, examples, and tests agree. Searches for old
vocabulary are reviewed semantically, excluding intentional historical and
LLM-profile references rather than enforcing a blanket text ban.
- Run focused `go test ./internal/core/config ./internal/cli ./internal/framework/llm ./internal/framework/pipeline`, followed by
`go test ./...`, `go vet ./...`, `go build ./...`, `go mod tidy -diff`, and
`git diff --check`, with `GOWORK=off`. Run race-enabled tests for the modified
adapter, scheduler, and observation integration. Validate both maintained configurations
and the complete configuration with `--config-overlay development`.
Use existing behavioral tests where possible, following
[Testing Policy](../../policy/testing.md). No live model calls or production API
credentials are needed to validate this migration.

View File

@@ -2,16 +2,8 @@
Current Notarius behavior is documented in the canonical README, CLI,
configuration, operations, internal, and integration docs. This backlog records
future work outside the [native migration roadmap](promptkit.md), which owns
PromptKit/ConfigKit/CommandKit adoption, continuation, admission, cache, output,
and debug decisions. Items below are ordered roughly by value and specificity,
not as committed release dates or prerequisites for that migration.
Native shared loading/commands, complete assessment/continuation, concurrent
ready lane completion, accepted-result reuse, and private capture are implemented;
see the [implementation evidence](implementation.md) for final acceptance status.
They are not deferred platform work. Human model-quality evaluation, broader
reference/context policies, and storage/distribution extensions below remain separate.
proposed extensions to that implementation. Items below are ordered roughly by
value and specificity, not as committed release dates.
## Near-Term D&D Pipeline
@@ -57,12 +49,12 @@ The sections below keep broader extensions deferred.
- Consider a dedicated semantic-policy selection option for a typed
reconciliation module when a concrete operator workflow needs more than the
migration's [native prompt replacement](promptkit.md#configuration-sources-and-prompt-assets).
[native prompt replacement](../config.md#promptkit-profiles).
- Use native prompt IDs and sources while retaining typed interpretation and
deterministic safety rules. Define any additional configuration and domain
compatibility checks from that workflow; do not recreate asset registration,
prompt fingerprints, or checkpoint dependency tracking.
- Reuse the selected [accepted-artifact cache policy](promptkit.md#accepted-artifact-cache-u8-resolved)
- Reuse the [accepted-artifact cache policy](../operations.md#accepted-result-cache-and-recovery)
when evaluating policy changes and the need for explicit refresh.
### Broader Reconciliation Inputs And Module Selection
@@ -83,7 +75,7 @@ The sections below keep broader extensions deferred.
- Add production LLM-backed validators only when a concrete review policy
benefits from model judgment and deterministic checks are insufficient.
- Consider additional validator diagnostic views only if a concrete need remains
after the selected [native observations and debug capture](promptkit.md#inspection-and-execution-bookkeeping).
with the existing [native observations and debug capture](../internal/llm.md#native-evidence-and-sensitive-data).
- Existing typed resolution already checks validator target, artifact kind,
and exact Go-type compatibility. Add further semantic suitability metadata
only if a deployment needs a contract beyond those implemented checks.
@@ -128,7 +120,7 @@ Define compatibility and migration policy before generated-reference chains
must span multiple schema versions or long-lived historical artifacts. The
policy should address stable identifier semantics, when an older artifact may
be decoded or adapted, and when consumers need regenerated artifacts. For cached
artifacts, use the [selected reuse policy](promptkit.md#accepted-artifact-cache-u8-resolved)
artifacts, use the [current reuse policy](../operations.md#accepted-result-cache-and-recovery)
and explicit refresh where needed. Do not add a general migration framework
until an actual contract change requires one.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@@ -1,607 +0,0 @@
# Native Migration Review Remediation
## Scope And Baseline
Review date: 2026-11-22.
Reviewed commit: `75444b8ef300ca8efee57d7a2271d21ce258b49c`.
Integration follow-up baseline: `fd134e85e54c6e0f74aab5c77df5bada7c1b1e6a`.
The follow-up baseline adds only the initial review findings; application code
is unchanged between these revisions.
Algorithmic follow-up baseline: `fdaf39162b46b528fddcd8a4cad18a09e1daf661`.
Only this findings document changed after the application baseline above.
This review followed the 46 stages in [the implementation plan](implementation.md)
against the [native migration target](promptkit.md), current owning code,
focused tests, maintained examples, and canonical documentation. The migration
is substantially complete. Findings 1–2 come from the initial review. Findings
3–5 come from an integration pass. Findings 6–9 and the complexity note on
Finding 1 come from a stage-ordered algorithmic pass. The latter are refactoring
opportunities for consideration, not measured production bottlenecks or new
performance guarantees. None calls for another compatibility layer or application
execution abstraction. The evidence below describes the reviewed baselines;
per-finding completion markers record the subsequent remediation work.
## Finding 1: Retain Genuine Native Timeouts During Concurrent Error Selection
**Status: Complete.** Operational deadlines participate in linear minimum
selection; sibling cancellation noise and authoritative caller cancellation are
preserved. Pipeline tests and race checks pass.
Priority: P2. Relevant stages: 10, 25, 37, and 46.
### Evidence And Impact
[`selectRunError`](../../internal/framework/pipeline/runner_concurrent.go),
lines 398–428 at the reviewed revision, suppresses every error matching
`context.Canceled` or `context.DeadlineExceeded` when any other failure is
available. This retained cancellation filter does not distinguish a canceled
sibling from an independently failed native operation.
A native PromptKit operation timeout matches both
`promptkit.ErrOperationTimeout` and `context.DeadlineExceeded`, even when the
caller context remains active. Consequently, a genuine timeout in an earlier
stage/lane/chunk scope is discarded in favor of a later non-context error,
rather than participating in the runner's stable scope ordering. The returned
cause then loses that native timeout identity.
The producer helper itself handles this distinction correctly; the gap is at
the concurrent runner's final selection boundary. A temporary review test used
the real PromptKit engine with a fake provider, obtained an actual native
operation timeout with an active caller, and supplied it as the earlier of two
scoped failures. The selector returned the later error instead. Existing helper
timeout coverage does not exercise this aggregation boundary.
### Required Change
Refine error selection so genuine operational deadline/timeout failures remain
eligible for the existing stable scope ordering. Distinguish them from
runner-induced sibling cancellation using the relevant context state and native
causes. Preserve authoritative caller cancellation and suppression of derivative
cancellation noise. An active caller's deadline-shaped operation failure must
not be discarded merely because it matches `context.DeadlineExceeded`.
Keep this a small runner correction; no new timeout controls, retry loop, or
application error taxonomy is needed.
### Acceptance
- With an active caller, an earlier-scoped native operation timeout and a later
ordinary failure select the timeout and retain its native `errors.Is` identity.
- A non-caller provider deadline also remains a genuine operational failure.
- Caller cancellation/deadline and runner-induced sibling cancellation retain
their intended precedence/noise handling.
- Ordinary multi-failure ordering and worker cancellation/draining remain intact.
- Add focused behavioral coverage at the runner error-selection boundary, using
the existing native timeout fixture where useful. Run the pipeline tests and
their concurrency/race checks.
### Algorithmic Follow-up: Select A Minimum Instead Of Sorting
With `E` collected errors, the current selector comparison-sorts all eligible
records by `(stage, lane, chunk)` solely to return the first. It performs
`O(E log E)` comparisons; stable sorting can also incur additional superlinear
data movement. After eligibility classification, a minimum scan takes `O(E)`
comparisons and constant auxiliary space; error-chain classification costs remain
separate. Keep the first occurrence on equal keys, matching stable-sort behavior.
This can accompany the correctness
fix without changing error precedence or cancellation semantics. Its practical
impact is smaller than the document/cache indexing findings below.
## Finding 2: Narrow The Documented Empty-Validator-Chain Guarantee
**Status: Complete.** Architecture, configuration, pipeline internals, and the
active plan now distinguish intrinsic checks from configurable citation checks.
Documentation links and whitespace were checked; runtime behavior is unchanged.
Priority: P2. Relevant stages: 11, 38, 39, and 42.
### Evidence And Impact
Three current documents make source checking sound unconditional:
- [Architecture policy](../policy/architecture.md), lines 229–232: intrinsic
codec/source correctness still applies with an empty chain.
- [Configuration reference](../config.md), lines 350–356: intrinsic typed
codec/source checks remain with an empty configured chain.
- [Pipeline internals](../internal/pipeline.md), lines 75–77: an empty chain
cannot remove intrinsic source-addressing checks.
Intrinsic durable-codec validation does remain. However, ordinary artifact
checks that cited units exist in the current source or lie within an extraction
chunk are supplied by the configured source-reference validators; final artifact
serialization does not independently perform those checks. See
[`serializeArtifact`](../../internal/framework/pipeline/runner_typed.go) and
the configured [candidate assessor](../../internal/framework/pipeline/candidate_assessment.go).
A temporary offline native-CLI probe configured `dnd/spells` extraction and
`noop` normalization with `validators: []`, disabled cache use, and supplied a
schema-valid spell citation to unit 999 against a transcript containing only
unit 1. The command succeeded and published that citation. This does not show a
failure of the default validator chains: the probe explicitly replaced them.
It demonstrates that the broad documented guarantee is stronger than the
implemented configurable validation boundary.
### Required Change
Align the three documents with the actual, selected boundary. Distinguish:
- intrinsic durable-codec/schema validation;
- source-document validation and chunk-plan materialization;
- checks a particular module necessarily performs while interpreting,
constructing fallback, or decoding a cache hit; and
- artifact citation existence/containment checks supplied by configured
validators.
State that an explicit empty/replacement chain can omit those ordinary artifact
source-reference checks. Link to the canonical default-chain/configuration
description rather than repeating detailed validator inventories.
Preserve operator replacement of validator chains. Do not add a mandatory
artifact validator, prohibit empty chains, or make every codec consult the
source document merely to satisfy the stronger wording. Those would expand the
requested contract. The Stage 11 completion summary's claim of mandatory final
codec/source checks should be qualified consistently while the active plan is
retained.
### Acceptance
- The architecture, configuration reference, pipeline guide, and active plan
distinguish unconditional codec checks from configurable citation validation.
- They do not imply that disabling validators disables source parsing,
materialization, or necessary module/fallback/cache construction checks.
- Existing default chains, explicit chain replacement, and runtime behavior
remain unchanged.
- Review related current documentation for the same overbroad claim. No new
prose-snapshot or mandatory-source-validation test is needed for this
documentation correction.
## Finding 3: Rebind Cached Scene Identity To The Current Chunk Plan
**Status: Complete.** Scene hits require one exact current-range scene and
reattach its current ordinal identity without model work or reassessment.
Expansion/collapse integration regressions and scene-module tests pass.
Priority: P1. Relevant stages: 11, 23, 27–29, and 37.
### Evidence And Impact
The new message-content cache interacts incorrectly with the existing
position-derived scene identity:
- [`MaterializeChunkPlan`](../../internal/core/source/chunk_plan.go), lines
169–179, renders only source units into chunk content, while assigning
`chunk-000001`, etc. from the range's position in the plan.
- [Scene extraction](../../internal/modules/dnd/extract/scenedescriptions/extractor.go)
deterministically attaches the current chunk ID and range in `mapResponse`.
The model does not supply this identity, and the ID is not rendered into the
initial scene-description messages.
- [`artifactProducerCache`](../../internal/framework/pipeline/runner_cache.go),
lines 21–37, decodes a hit and checks cited source units, but does not rebind
its scene identity. The hit bypasses extraction interpretation and assessment.
Changing an earlier scene boundary can therefore renumber an unchanged later
scene without changing that later scene's prompt hash. Its old accepted artifact
is a legitimate content-key hit, but its stored scene ID belongs to the old plan.
A temporary native-CLI integration probe used real scene planning, extraction,
merging, normalization, default validators, and a filesystem cache. The chunk
binding used `cache: refresh`; scene extraction used ordinary `auto`. The fake
provider returned these two valid plans for the same three-unit transcript:
1. `[1–2], [3]`, followed by `[1], [2], [3]`: the second run failed normalization
with `scene ID "chunk-000002" has conflicting records`.
2. The reverse change: the second run succeeded but published IDs
`chunk-000001` and `chunk-000003` for a two-chunk plan. The last ID should have
been `chunk-000002`.
Both cases pass with invocation-wide cache bypass. The unchanged suffix was
reused in the failing cases, as confirmed by provider-call counts. This is not
an invalid generated plan or intentionally skipped semantic revalidation.
The stale ID also conflicts with the existing [scene registry's exact match](../../internal/modules/dnd/scenedescriptions/registry/registry.go):
combat/enemy consumers require both the current chunk ID and range, so a stale
scene can become unavailable classification and suppress downstream extraction.
### Required Change
Add the missing current-operation adaptation at the scene cache-hit boundary.
For a usable single-scene artifact describing the exact current range,
deterministically reattach the current chunk identity while retaining its accepted
kind/title/summary. If a cached artifact cannot be safely adapted, treat it as an
unusable miss before returning it as accepted work.
Keep domain-specific adaptation with the scene module, using the supplied typed
cache collaboration or a small extension to that boundary if needed. Preserve
the content-only native cache key and no-semantic-reassessment policy. Do not
render an internal scene ID into the prompt, add a partition fingerprint/key
dimension, restore canonical source-only chunking, or ask the model to copy IDs.
Review other current cached artifacts for equivalent operation-derived fields;
do not invent a generic identity framework for families that do not need one.
### Acceptance
- Repartitioning earlier units can move an unchanged later scene to a different
chunk ordinal without duplicate or stale scene IDs in the published artifact.
- Current scene IDs/ranges match the chunk map and remain usable by the existing
combat/enemy eligibility resolver.
- The unchanged scene can reuse its accepted semantic content without another
model call or validator assessment when deterministic adaptation is safe.
- Wrong-range, multi-scene, or otherwise unusable entries are not silently
rebound into valid-looking scenes; they miss normally.
- Add assembled two-run expansion/collapse coverage using the existing native
fake-provider/cache setup, and retain ordinary same-plan hit coverage.
## Finding 4: Bound Framework-Generated Fallback Diagnostic Messages
**Status: Complete.** Framework fallback/cache samples share bounded UTF-8
rendering without changing full outcome evidence or module diagnostic checks.
Multibyte/invalid-UTF-8 regressions and a typed spell CLI fallback probe pass.
Priority: P2. Relevant stages: 9, 11, 24, 29, and 34.
### Evidence And Impact
[`FinishProducerFailure`](../../internal/framework/pipeline/producer_outcome.go)
retains the complete failure text in `ProducerOutcome.FallbackReason` after a
supported permissive fallback is successfully constructed.
[`operationDiagnosticGroups`](../../internal/framework/pipeline/runner_operation.go),
lines 51–58, copies that text unchanged into a framework-generated warning sample.
The existing [diagnostic contract](../../internal/framework/contracts/diagnostics.go)
requires valid UTF-8 and a maximum sample-message size of 4096 bytes.
Native errors and joined assessment errors are not bounded diagnostic samples.
Even individually bounded domain validator messages can exceed the sample limit
after joining several findings and adding validator context. The new fallback
bridge thus creates invalid diagnostics from otherwise valid operation outcomes.
A temporary offline native-CLI probe ran a minimal spell pipeline in permissive
mode with a fake provider returning a long ordinary error. The valid empty spell
fallback was constructed, but the run then failed with
`producer diagnostic 0: diagnostic sample 0: diagnostic sample message exceeds maximum length`.
The failure occurs even with ordinary visibility hiding optional warnings.
### Required Change
Render the framework's fallback warning into a bounded, valid-UTF-8 sample before
promoting it. Reuse or factor the small bounding behavior already present in
[`producerCacheObserver`](../../internal/framework/pipeline/runner_cache.go)
rather than adding a second diagnostic system.
Bound only the generated diagnostic sample, leaving the original error/outcome
text and requested evidence unchanged. This is operator diagnostic presentation,
not model correction guidance. Preserve validation of module-supplied diagnostics;
do not raise/remove the existing cap or suppress genuine malformed-module
contracts to work around the framework's own unbounded sample.
### Acceptance
- A supported permissive fallback still publishes qualified output when its
native or aggregated-assessment cause exceeds the diagnostic sample limit.
- The generated warning is nonblank, bounded, and valid UTF-8, including at a
multibyte truncation boundary.
- Strict handling, caller cancellation, fallback counting/reuse exclusion,
full requested evidence, and module-diagnostic validation remain unchanged.
- Add focused fallback-to-diagnostic integration coverage, including a real
typed producer path with a fake long native error. No model retry is added.
## Finding 5: Remove The Disconnected Legacy LLM Error Contract
**Status: Complete.** Removed the unused legacy error taxonomy and its self-test;
current execution retains native PromptKit errors and application assessment/
capture errors. Contracts, pipeline, CLI, and module integration tests pass.
Priority: P3. Relevant stages: 8, 24, 35, and 44.
### Evidence And Impact
At the reviewed baseline, `internal/framework/contracts/errors.go` still
defines the pre-migration `ErrInvalidStructuredOutput`, `ErrLLMCapacityExceeded`,
`ErrLLMGeneration`, `LLMGenerationError`, constructors, and copied failure/attempt
metadata. Current producers and validators retain native PromptKit errors instead.
Graph/code searches find this old taxonomy only in that file and its
self-test (`internal/framework/contracts/errors_test.go`), not in an active
application consumer.
This is leftover contract surface from the removed adapter, not a second active
execution path. It nevertheless presents obsolete sentinels and metadata accessors
as available framework conventions, although matching actual native failures
against them no longer works. Stage 35's hard-cutover cleanup is incomplete here.
### Required Change And Acceptance
Remove the unused legacy error definitions and their self-test. Keep native
`errors.Is`/`errors.As` behavior and the separate, actively used application
assessment/capture error types. Do not bridge native errors into these retired
sentinels or add aliases for compatibility. Verify no current callers remain and
run contracts, pipeline, CLI, and module integration tests after removal.
## Finding 6: Use Indexed Source Validation In The Chunk-Plan Hot Path
**Status: Complete.** Document validation builds one unit-position map, and plan
materialization reuses checked endpoints without rescanning or duplicate
framework validation. Source, chunk-map, and pipeline tests cover retained
ordering, ownership, malformed-input behavior, and nonmonotonic IDs.
Priority: P2. Relevant stages: 16, 24, 28–29, and 37.
### Evidence And Complexity
The supporting [source validation code](../../internal/core/source/validation.go)
predates this migration, but the new chunk-plan assessment/cache path repeatedly
uses it. `ValidateDocument`, lines 95–101, validates each unit's self-reference
with `ValidateRef`. That helper resolves both endpoints through the linear
`UnitIndex` scan. For a valid document of `N` units, the second validation pass
alone makes `2 * (1 + ... + N) = N(N+1)` unit-ID comparisons: `Theta(N^2)` work.
[`ValidateChunkPlan` and `MaterializeChunkPlan`](../../internal/core/source/chunk_plan.go)
also repeatedly scan the source for each of `C` ranges. A materialization thus
performs `O(N^2 + CN)` source-position work in addition to field checking,
annotation processing, metadata ownership, and payload encoding.
The pipeline's
[`validateAndMaterializeChunkPlan`](../../internal/framework/pipeline/chunk_validation.go)
validates once explicitly and then calls a materializer that validates again.
The [new plan path](../../internal/framework/pipeline/runner_chunk_plan.go)
invokes this during assessment, cache encode/decode, and final delivery. Cached
plans therefore retain this deterministic cost even without inference.
### Potential Refactoring
Use the existing immutable `source.DocumentIndex` for bulk endpoint lookups.
Build/reuse a unit-position map while validating the document, then check its
self-references in linear expected time. Share resolved positions through a
small private validation/materialization helper so materialization does not
rescan endpoints or repeat the same validation unnecessarily. Keep standalone
public validation/materialization entry points correctly validating their inputs.
The attainable position-lookup cost is `O(N + C)` expected work with `O(N)`
index space. Field/payload inspection, annotation canonicalization, metadata
ownership, and JSON encoding remain separate costs. This does not promise linear
total output size: permitted overlapping generic ranges can themselves require
superlinear copied output. Repeated materialization of accepted plans can be
reduced where already-owned checked chunks are available, without retaining a
whole-run ledger or removing necessary current-source checks.
### Preserve And Verify
Preserve document-order semantics for nonconsecutive/nonmonotonic unit IDs,
duplicate/missing/wrong-source/reversed-reference rejection, annotation handling,
deep ownership, and deterministic chunk IDs. Generic plans still permit their
existing gaps/overlaps; D&D coverage rules remain with scene interpretation and
configured validators. No stricter plan format or new size limit is needed.
Use the existing source validation/materialization, chunk-plan operation/cache,
and chunk-map tests. Add only missing behavioral regressions; source inspection
or optional synthetic operation counts can verify the scaling change without
wall-clock thresholds or production data.
## Finding 7: Share A Lazy Source Index Across Artifact Cache Decoders
**Status: Complete.** Run-scoped decoders share a concurrency-safe lazy immutable
index, acquired only when a decoded hit has evidence to check. Concurrent-hit
runner coverage and the pipeline race suite pass; cache modes and usability
checks remain unchanged.
Priority: P2. Relevant stages: 11, 21–22, and 27–28.
### Evidence And Complexity
[`artifactProducerCache`](../../internal/framework/pipeline/runner_cache.go),
line 17, eagerly creates a full `DocumentIndex` for each model-backed operation
whenever a store collaborator exists. It does so before the producer helper
checks bypass/refresh mode, incoming reuse eligibility, or whether a module takes
a legitimate no-model branch. Cold misses also never use the resulting index.
For `J` such operations against `N` source units, this adds `Theta(JN)` index
construction work. With a fixed number of lanes and chunks proportional to
transcript length, that cache-specific term becomes quadratic in `N`.
Concurrent operations can retain `O(min(J,W)N)` cache index entries while waiting
for model work, where `W` is the active worker bound. This is separate from
codec decoding and domain/validator input ownership costs.
### Potential Refactoring
Supply the cache decoders with one run-scoped, immutable source-position index.
Acquire it lazily only when a decoded hit actually needs evidence checks, using
ordinary concurrency-safe initialization. The cache-specific work becomes
`O(N + R)` for all hits, where `R` is the total number of checked cached source
references, with `O(N)` shared index space. Runs with no such checks need not
construct the cache index at all.
This is a small in-memory collaborator, not another persistent cache or source
identity framework. Keep the native message-content key, modes, hit validation,
fallback eligibility, and no-semantic-reassessment policy. Finding 3's scene
identity adaptation is a separate usability concern; shared indexing must not
replace it. Other intentional domain/validator snapshots need not be weakened.
### Preserve And Verify
Retain wrong-source/missing/reversed citation rejection on hits, normal misses,
refresh/bypass/ineligible/no-model behavior, and canceled-hit delivery. Exercise
concurrent hits with the existing cache/runner tests and race checks. Do not add
a public index-build-count contract or a timing-based release gate.
## Finding 8: Index Debug Sensitivity Paths Once
**Status: Complete.** A single historical-path traversal groups marked suffixes
by exact native resource prefix before resource association. Capture regressions
and race checks pass, including mixed root/collection resources, escaped keys,
nested arrays, and native snapshot ownership.
Priority: P3. Relevant stages: 30–31 and 33.
### Evidence And Complexity
[`newRunEvidenceRecorder`](../../internal/cli/run_capture.go), lines 64–91,
collects all `H` historical configuration paths, then scans that full list for
each of `P` profiles/backends across root and collection resources. Prefix
matching therefore performs `O(PH)` work, plus path-string processing. With a
roughly fixed number of fields per resource, `H` grows with `P`, yielding a
quadratic resource-count term.
The caller correctly constructs this recorder only when capture is enabled.
This finding concerns debug startup for large native configurations, not an
unconditional cost on ordinary runs.
### Potential Refactoring
Walk metadata paths once and group relevant sensitive suffixes by their exact
resource prefix. Then associate those groups with root/qualified resource IDs in
one resource traversal. This takes `O(H + P)` path/resource visits, plus processing
the path characters and retained masks, rather than rescanning every unrelated
configuration path for every resource.
Retain native sensitivity classification, correct JSON-pointer segment unescaping,
root/collection distinctions, nested maps/arrays, and nonmutation of native
snapshots. Do not replace exact metadata with credential-like string searches or
broaden omission policy. Use the existing configuration/native capture tests;
add a mixed-resource case only if needed to verify equivalent mask routing.
## Finding 9: Traverse Dense Chunk Results Without Sorting Their Keys
**Status: Complete.** Lane assembly traverses the materializer's dense ordinals
directly, retaining artifact/diagnostic order, fallback counts, and reuse
eligibility without allocating or sorting a temporary key slice. Pipeline
concurrency/ready-job tests and race checks pass.
Priority: P3. Relevant stages: 11, 25, and 37.
### Evidence And Complexity
[`finalizeLaneExtract`](../../internal/framework/pipeline/runner_concurrent.go),
lines 333–349, copies result-map keys to a new slice and sorts them before
assembling the lane. For `C` chunks this costs `O(C log C)` comparisons and
`O(C)` temporary key storage per lane.
The runner's chunks are already assigned contiguous zero-based indexes by
`MaterializeChunkPlan`; successful finalization occurs only after all of that
lane's jobs return. The required order is therefore known, not arbitrary.
### Potential Refactoring And Verification
Traverse the known ordinal range directly for `O(C)` expected map-lookup work
and no temporary key slice, or use an indexed result slice if it simplifies
storage. Keep all artifact/diagnostic ordering, fallback counts, eligibility,
failure handling, cancellation draining, and ready-job scheduling unchanged.
No new chunker restriction is required: dense ordinals are already produced by
the existing materializer, regardless of transcript unit-ID spacing.
The current runner concurrency and ready-job tests cover out-of-order completion
and public result order. Reuse those checks; do not couple tests to a particular
map/slice representation or add another scheduler.
## Review Coverage And Verification
Owning boundaries were inspected in implementation order:
| Stages | Reviewed boundary |
| --- | --- |
| 1–7 | Declared dependencies/notices, native resources/schemas, one ConfigKit result and engine, CommandKit/ckconfig/ckprompt construction and supplied values. |
| 8–11 | Typed production/assessment, full ordered validator chains, native continuation and terminal disposition, runner handoffs and eligibility. |
| 12–24 | All ten D&D extractors, three semantic registry normalizers, scene planning, direct combat-semantic validation, deterministic paths and registration. |
| 25–28 | Ready-job workers, native admission, accepted-artifact cache, prepared handles/initial keys, current-source cache usability and chunk-plan materialization. |
| 29–34 | Domain-only publication, incremental requested capture, offline preflight/inspection, run composition, native reports and failure outcomes. |
| 35–37 | Removal inventory, maintained examples, assembled recovery and subprocess coverage. |
| 38–46 | Successor ADRs and historical-body preservation, canonical references, operations/consumer/migration/internal/integration guides, orientation and final acceptance evidence. |
Checks completed during the initial review:
- `GOWORK=off GOPROXY=off go test ./...` passed.
- `GOWORK=off GOPROXY=off go vet ./...` passed.
- A fresh `GOWORK=off GOPROXY=off go build` to a temporary binary passed.
- `GOWORK=off GOPROXY=off go test -race ./internal/framework/pipeline
./internal/cli` passed.
- Offline executable checks passed for version, minimal/complete pipeline
preflight, and native prompt requirements; native diff check returned its
expected differences status (3).
- The migration diff contains no changes to model-facing JSON schemas or D&D
intrinsic codec schema files. Historical ADR decision bodies are retained;
supersession edits are confined to status descriptions.
- Temporary Go-overlay probes reproduced Findings 1–2 without modifying
repository code or tests. Their deliberately failing assertions are review
evidence, separate from the passing default suite.
The integration follow-up inspected the stage boundaries above against the
retained source/chunk identity, domain codecs/validators, generated references,
diagnostic limits, physical publication, and subprocess contracts. It reused
the earlier full-suite/vet/build/race results only after confirming that the
application code and dependencies were unchanged. Additional checks were:
- `GOWORK=off GOPROXY=off go test ./internal/core/config
./internal/framework/pipeline ./internal/framework/semanticreconcile
./internal/modules/integration ./internal/cli` passed.
- Real native-CLI/fake-provider Go-overlay probes reproduced both directions of
scene repartitioning in Finding 3. Both corresponding bypass controls passed.
- A native-CLI/fake-provider overlay probe reproduced the long-error permissive
fallback failure in Finding 4.
- Graph/code searches confirmed that Finding 5's legacy taxonomy has no active
callers outside its own definition/self-test.
These probes live only in a temporary review directory. No production code,
test, configuration, schema, or existing canonical documentation was changed.
The algorithmic pass followed the same stage order, inspecting actual loop/call
costs rather than treating nested-loop graph metadata as proof of a bottleneck:
- Stages 1–7: native loading/delegation, bounded invocation-selection reuse,
resource/input construction, and absence of a second application load.
- Stages 8–11: candidate serialization/isolation, complete-chain traversal,
native helper control flow, and runner/handoff state.
- Stages 12–24: fixed extraction mappings, bounded reconciliation preparation,
interval coalescing, indexed duplicate/group application, direct validators,
deterministic paths, and the source/materialization costs in Finding 6.
- Stages 25–29: constant-work ready-job dispatch, result/error ordering,
filesystem byte traversal, source-index lifetime, and reuse/auxiliary assembly.
- Stages 30–34: incremental capture, sensitivity-path routing, preflight,
command composition, diagnostics, and publication.
- Stages 35–46: retained/removal boundaries, example/assembled coverage, and
documentation consistency with the algorithms and selected policies above.
Explicitly selected behavior was not reopened: complete validation on every
candidate, fresh normalization application to fixed originals, native growing
history, content-only cache identity, no semantic reassessment on hits, the ready-
job scheduling policy, and self-contained debug records even when content repeats.
The earlier expressly recommended per-handoff output index was also left alone.
Sorting genuinely unordered citations/intervals and collision-safe indexed domain
grouping are not findings merely because they contain loops or comparisons.
Complexity claims in Findings 6–9 follow from the current source and call sites;
they are not throughput estimates. Position-map costs use ordinary expected
hash-map complexity; retained field/payload processing is accounted for separately.
The existing
offline suites for `internal/core/source`, `internal/framework/pipeline`,
`internal/framework/artifactcache`, `internal/framework/semanticreconcile`, and
`internal/cli` passed again. No production workload or performance data was needed,
and no new benchmark, timing assertion, or permanent gate was added.
No live provider inference was performed. This review does not establish
production model quality or performance. Intentional changes such as the hard
configuration/CLI cutover, native retry ownership, content-only cache identity,
no semantic reassessment on hits, explicit permissive fallback, and native
diagnostic visibility are part of the agreed target, not regressions.
## Remediation Completion
All nine findings are addressed in focused commits, with completion markers at
their owning findings above. Final verification after the code changes passed:
- `GOWORK=off GOPROXY=off go test ./...`.
- `GOWORK=off GOPROXY=off go vet ./...`.
- A fresh `GOWORK=off GOPROXY=off go build` to a temporary binary.
- Race tests for `internal/framework/pipeline`, `internal/framework/chunkmap`,
`internal/core/source`, `internal/cli`, and
`internal/modules/dnd/extract/scenedescriptions`.
- Executable `version`, offline pipeline validation of both maintained D&D
examples, and native spell prompt-requirements inspection.
- `git diff --check`, this document's local link destinations, and the affected
configuration-reference anchors.
The scene-cache regression covers both repartitioning directions, bypass
controls, current IDs, actual reuse without reassessment, and unusable hits.
The fallback regression exercises a real typed spell pipeline with a fake long
provider failure; focused checks retain full causes and module diagnostics.
Source/cache/capture regressions cover nonmonotonic unit order, concurrent hits,
and exact sensitivity routing without native snapshot mutation. No production
inference, new permanent validation gate, or performance guarantee was added.