Remove completed planning documents
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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.
|
||||
Reference in New Issue
Block a user