eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare Notarius v0.8.1 source release

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 03:04:04 +00:00
parent 122f36bc68
commit 9790579b51
5 changed files with 31 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
docs/roadmap/archive/implementation.md Normal file
View File

@@ -0,0 +1,322 @@
# 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.

252
docs/roadmap/archive/policy.md Normal file
View File

@@ -0,0 +1,252 @@
# 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.

124
docs/roadmap/archive/remediation.md Normal file
View File

@@ -0,0 +1,124 @@
# 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.

337
docs/roadmap/archive/upgrade-kit.md Normal file
View File

@@ -0,0 +1,337 @@
# 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.