Update Notarius integration and plan references
This commit is contained in:
546
docs/roadmap/implementation.md
Normal file
546
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,546 @@
|
||||
# Notarius v0.6 CLI References Implementation Plan
|
||||
|
||||
## Purpose And Status
|
||||
|
||||
This is the executable implementation plan for the accepted target state in
|
||||
[Notarius v0.6 CLI Reference Integration](notarius-v0.6-cli-references.md). It
|
||||
is written for a `gpt-5.6-terra` coding agent that will implement exactly one
|
||||
pending stage per prompt, in order.
|
||||
|
||||
The feature roadmap owns user intent, architectural boundaries, settled policy,
|
||||
and the target end state. This document owns delivery order, concrete changes,
|
||||
test allocation, and implementation status. Do not restate or change a roadmap
|
||||
decision here during implementation; if current Notarius v0.6.0 evidence
|
||||
contradicts the roadmap, stop and record the conflict instead of inventing a
|
||||
different contract.
|
||||
|
||||
| Stage | Outcome | Status |
|
||||
| ---: | --- | --- |
|
||||
| 1 | Add the reference-selector and configuration vocabulary, including optional spell-catalog inputs. | Pending |
|
||||
| 2 | Materialize and inventory the optional spell catalog through the prepare and operator lifecycle. | Pending |
|
||||
| 3 | Centralize manifest-authoritative prepared-input resolution and migrate analyze to it. | Pending |
|
||||
| 4 | Add deterministic Notarius v0.6 reference arguments at the subprocess adapter boundary. | Pending |
|
||||
| 5 | Resolve references in extract and bind fingerprints, resume, and metadata to their identities. | Pending |
|
||||
| 6 | Prove assembled extraction lifecycle and downstream invalidation behavior. | Pending |
|
||||
| 7 | Update canonical documentation and maintained examples for the completed feature. | Pending |
|
||||
| 8 | Perform compatibility, quality, and repository-wide closure validation. | Pending |
|
||||
|
||||
## Governing Decisions
|
||||
|
||||
The following requirements are settled and are not questions for the
|
||||
implementing agent:
|
||||
|
||||
1. `pipeline.notarius.references` is a map whose key is a Notarius v0.6 CLI
|
||||
reference selector and whose value is a prepared Narratio source ID. It is
|
||||
not a map of paths.
|
||||
2. Every configured binding is required. There is no per-entry `required`
|
||||
field. An optional Notarius reference is omitted by omitting the map entry.
|
||||
An empty or omitted map remains valid for custom pipelines and backward
|
||||
compatibility.
|
||||
The map is limited by the centrally declared configuration constant
|
||||
`MaxNotariusReferenceBindings = 256`, which is far above the four-entry
|
||||
maintained D&D case while bounding argv and manifest growth.
|
||||
3. The supported prepared reference sources are
|
||||
`narratio.input.party`, `narratio.input.players`,
|
||||
`narratio.input.glossary`, and `narratio.input.spell_catalog`.
|
||||
Arbitrary Notarius slot names and qualified selectors may bind those sources;
|
||||
direct paths and later-stage artifacts may not.
|
||||
4. Campaign and session `spell_catalog_file` are optional. A session value
|
||||
overrides the campaign value; an empty session value inherits the campaign
|
||||
value. A `narratio.input.spell_catalog` reference binding requires an
|
||||
effective configured file.
|
||||
5. Prepared sources are authoritative only when the current session manifest
|
||||
records the matching canonical input and checksum. Consumers do not fall
|
||||
back to campaign/session source paths or accept an incidental workspace file.
|
||||
6. Narratio passes absolute prepared-file paths to Notarius. Fingerprints and
|
||||
metadata use the canonical workspace-relative path identity together with
|
||||
selector, source ID, SHA-256 checksum, and size so workspace relocation does
|
||||
not become the only identity signal.
|
||||
7. External CLI references are sorted by normalized selector. They override
|
||||
matching external references in the Notarius configuration. Narratio never
|
||||
emits `--without-reference`, the deprecated `roster` alias, or CLI bindings
|
||||
for generated D&D artifact handoffs.
|
||||
8. Notarius remains authoritative for whether a selected target declares a
|
||||
slot, accepted reference media types and sizes, generated-handoff collisions,
|
||||
pipeline topology, and D&D payload schemas. Narratio validates selector
|
||||
structure and its own source contract only.
|
||||
9. Notarius v0.6.0 is the minimum supported CLI contract when references are
|
||||
configured. Do not add version-string parsing or an automatic per-session
|
||||
`notarius config validate` subprocess.
|
||||
10. The existing receipt-v2, bundle-confinement, diagnostic, ten-lane selection,
|
||||
immutable promotion, and analysis-source behavior must remain intact.
|
||||
11. The default test suite remains offline, deterministic, and independent of
|
||||
a sibling checkout or installed Notarius binary. A real v0.6.0 smoke run is
|
||||
useful supplementary evidence when locally available, not a default-suite
|
||||
dependency.
|
||||
12. Add no external Go dependency for this feature. Use narrow owner-specific
|
||||
types and existing file, path, artifact, manifest, adapter, and stage
|
||||
facilities.
|
||||
|
||||
## Instructions For Every Stage
|
||||
|
||||
For each implementation prompt, the coding agent must:
|
||||
|
||||
1. Read `docs/development.md`, all three files under `docs/policy/`, the feature
|
||||
roadmap, this plan, and the stage-specific documents and source named below.
|
||||
Inspect the current tree because earlier stages may have changed names or
|
||||
ownership boundaries.
|
||||
2. Use the repository knowledge graph first for code discovery and call tracing;
|
||||
use text search for documentation, configuration, examples, string literals,
|
||||
and evidence the graph cannot supply.
|
||||
3. Confirm the worktree state and preserve unrelated changes. Implement only the
|
||||
current stage. Do not begin a later stage merely because an adjacent file is
|
||||
open.
|
||||
4. Keep production code, focused tests, fakes, and fixtures consistent within
|
||||
the stage. Remove superseded helpers when their final caller migrates. Do not
|
||||
retain two competing source maps, path resolvers, fingerprint paths, or
|
||||
subprocess argument builders.
|
||||
5. Follow the testing policy's ownership rule. Parser/config tests own selector
|
||||
and configuration cases; artifact tests own prepared-file identity and
|
||||
integrity; adapter tests own exact arguments; stage tests own orchestration and
|
||||
resume; application tests own lifecycle invalidation. Do not repeat every
|
||||
lower-level case at higher levels.
|
||||
6. Keep errors actionable and content-free. They may identify a selector,
|
||||
Narratio source ID, canonical path, or checksum mismatch, but must not include
|
||||
reference contents. Preserve ordinary group-workspace permissions and
|
||||
restrictive API-key handling.
|
||||
7. Run `gofmt` on changed Go files and focused tests while iterating. Before
|
||||
marking any stage complete, run at minimum:
|
||||
|
||||
```sh
|
||||
go test ./...
|
||||
go test -race ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
go test ./internal/doccheck
|
||||
go test ./internal/config -run '^TestExamplesLoadAndValidate$'
|
||||
```
|
||||
|
||||
Default tests must not contact live services or require credentials.
|
||||
8. Compare the final diff against the stage goal and exit criteria. Update only
|
||||
the current stage's status row from `Pending` to `Completed`. Do not mark a
|
||||
stage complete while a required check fails or required behavior is absent.
|
||||
Intermediate commits are implementation-branch state and must not be released
|
||||
before Stage 7 has reconciled current-behavior documentation.
|
||||
|
||||
## Stage 1 — Reference And Configuration Vocabulary
|
||||
|
||||
**Read first:** `docs/config.md`, `docs/integrations/notarius.md`,
|
||||
`internal/config/config.go`, `internal/config/defaults.go`,
|
||||
`internal/config/load.go`, `internal/config/validate.go`,
|
||||
`internal/config/notarius_test.go`, `internal/config/campaign_config_test.go`,
|
||||
and `internal/artifactpolicy/policy.go` and its tests. Read the tagged Notarius
|
||||
v0.6.0 `docs/cli.md` reference-selector section from `../notarius` when that
|
||||
checkout is available; otherwise use the canonical link from the feature
|
||||
roadmap.
|
||||
|
||||
**Depends on:** None.
|
||||
|
||||
**Goal:** Establish one normalized reference-selector grammar and the strict
|
||||
configuration model needed by later stages, without adding path-valued Notarius
|
||||
configuration or making spell catalogs mandatory for every campaign.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Add a small dependency-free `internal/notariusref` package as the contract
|
||||
owner for Notarius reference selector normalization. Its exported normalizer
|
||||
must trim the selector and each component, reject empty components and `=`,
|
||||
and accept only the v0.6 forms `slot`,
|
||||
`chunk.slot`, `lane.slot`, `lane.extract.slot`, `lane.merge.slot`, and
|
||||
`lane.normalize.slot`. A three-component selector accepts only `extract`,
|
||||
`merge`, or `normalize` in its middle component. Do not check the selector
|
||||
against a Notarius module or lane registry.
|
||||
- Add `References map[string]string` with YAML key `references` to
|
||||
`config.NotariusConfig`. During enabled Notarius validation, sort raw keys,
|
||||
normalize each selector through the shared contract, trim each source value,
|
||||
reject empty values and normalized-selector collisions, require each value to
|
||||
be one of the four prepared reference sources, and replace the config map with
|
||||
its normalized form. Enforce the named, centrally discoverable
|
||||
`config.MaxNotariusReferenceBindings` limit of 256 entries with an error that
|
||||
identifies the field and limit. Keep a nil/empty map valid. Rely on strict YAML
|
||||
decoding to reject duplicate identical keys, but explicitly reject distinct
|
||||
raw keys that normalize to one selector.
|
||||
- Add `SpellCatalogFile string` with YAML key `spell_catalog_file` to campaign
|
||||
inputs and session inputs, plus `SpellCatalogFile ResolvedInputFile` to
|
||||
resolved stable inputs. Merge it with the existing session-over-campaign
|
||||
helper. It is not part of the campaign-required input set. Reject a non-empty
|
||||
configured scalar that becomes empty after trimming.
|
||||
- Add `artifactpolicy.SourceInputSpellCatalog` and make the artifact-policy
|
||||
owner describe all four prepared reference sources, including their canonical
|
||||
manifest kind and filename. Use that owner for stable-source recognition
|
||||
instead of adding a second switch in configuration validation. Preserve the
|
||||
existing three source IDs and their behavior.
|
||||
- Extend cross-configuration validation so a normalized reference to
|
||||
`narratio.input.spell_catalog` requires a non-empty effective resolved
|
||||
`spell_catalog_file`. Existing campaign requirements already guarantee party,
|
||||
players, and glossary declarations. Do not check filesystem existence during
|
||||
configuration validation.
|
||||
- If analyze's current private filename switch must change to keep the tree
|
||||
behaviorally coherent, make it delegate to the artifact-policy descriptor and
|
||||
recognize spell catalog; Stage 3 will replace the filesystem-only resolver.
|
||||
|
||||
**Tests and exit criteria:** At the contract/config owners, cover every accepted
|
||||
selector shape; zero, empty, excess, invalid-stage, and `=` forms; whitespace
|
||||
normalization; normalized collisions; unsupported and empty source IDs; nil and
|
||||
empty maps; exactly the configured binding limit and limit plus one; strict
|
||||
unknown fields; campaign inheritance and session override; optional omission;
|
||||
and the cross-config missing-spell-catalog failure. Prefer table-driven parser
|
||||
and validator tests over assertions against private helper structure. Existing
|
||||
configuration and example tests must still pass without adding spell catalogs
|
||||
to every campaign. The codebase has one selector grammar owner and one
|
||||
prepared-source descriptor owner.
|
||||
|
||||
## Stage 2 — Spell Catalog Prepare And Operator Lifecycle
|
||||
|
||||
**Read first:** `docs/internal/stage-prepare.md`, `docs/internal/workspace.md`,
|
||||
`docs/operations.md`, `internal/stage/prepare.go` and its tests,
|
||||
`internal/app/operator_inspection.go`, `internal/app/operator_findings.go` and
|
||||
their focused tests, `internal/manifest/manifest.go`, and the relevant confined
|
||||
file-operation helpers.
|
||||
|
||||
**Depends on:** Stage 1.
|
||||
|
||||
**Goal:** Make the effective optional spell catalog a normal prepared session
|
||||
input with canonical storage, checksum/provenance, safe stale-file handling, and
|
||||
operator visibility.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Resolve `StableInputs.SpellCatalogFile` with the same origin-preserving
|
||||
campaign/session behavior as the five existing stable inputs. When configured,
|
||||
require a regular readable source, copy it atomically to
|
||||
`inputs/spell_catalog.json`, preserve ordinary workspace permissions, and add
|
||||
one manifest input record with kind `spell_catalog`, canonical destination,
|
||||
checksum, and `campaign_config` or `session_config` source provenance.
|
||||
- Treat the input as optional when no effective path is configured. Do not call
|
||||
the required-input path resolver with an empty value and do not create a
|
||||
manifest record. Remove an obsolete canonical `inputs/spell_catalog.json`
|
||||
without following it when a forced prepare transitions from configured to
|
||||
absent; refuse to recursively remove a directory or other ambiguous object at
|
||||
that exact file path.
|
||||
- Include a configured spell catalog in operator inspection and validation
|
||||
findings. Omission is not an error unless Stage 1 cross-configuration policy
|
||||
says the enabled Notarius reference requires it. Reuse the common resolved
|
||||
stable-input enumeration where practical instead of extending parallel
|
||||
hand-written lists in several functions.
|
||||
- Adjust input-slice capacity, deterministic ordering, test fixtures, and any
|
||||
manifest assumptions affected by the optional sixth stable file. Do not parse
|
||||
or schema-validate the JSON payload in Narratio; Notarius owns that contract.
|
||||
|
||||
**Tests and exit criteria:** Through prepare and operator package behavior, cover
|
||||
campaign and session source provenance, canonical destination bytes and
|
||||
checksum, optional omission, missing configured source, replacement after source
|
||||
change, safe removal when configuration is removed, rejection of an ambiguous
|
||||
destination object, deterministic manifest ordering, and operator reporting.
|
||||
Do not duplicate selector-validation cases from Stage 1. Existing sessions with
|
||||
no spell catalog remain valid and produce no stale manifest entry.
|
||||
|
||||
## Stage 3 — Manifest-Authoritative Prepared Input Resolution
|
||||
|
||||
**Read first:** `docs/internal/artifacts.md`, `docs/internal/manifest.md`,
|
||||
`docs/internal/stage-analyze.md`, `internal/artifacts/artifact_resolver.go`,
|
||||
`internal/artifacts/resolve.go`, `internal/artifacts/checksum.go`, their tests,
|
||||
and the prepared stable-input resolution path in `internal/stage/analyze.go` and
|
||||
`internal/stage/analyze_test.go`.
|
||||
|
||||
**Depends on:** Stage 2.
|
||||
|
||||
**Goal:** Give analyze and extract one integrity-checked resolver for prepared
|
||||
stable sources so neither stage trusts incidental files or reconstructs its own
|
||||
source-to-filename table.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Add an artifacts-owned `PreparedInputIdentity` contract containing source ID,
|
||||
manifest kind, absolute canonical path, slash-separated path relative to the
|
||||
session root, SHA-256 checksum, and byte size. Add one resolver that accepts
|
||||
session paths, the current session manifest, and a stable source ID. Provide a
|
||||
typed or sentinel absence classification so callers can distinguish no current
|
||||
manifest record from corrupt or unsafe recorded evidence.
|
||||
- Derive kind and filename exclusively from the artifact-policy descriptor. The
|
||||
resolver must require exactly one current manifest input record with the
|
||||
expected kind and canonical path; resolve/rebase recorded local paths through
|
||||
existing session-local path safety helpers; require the result to equal the
|
||||
canonical file below `inputs/`; reject escapes, symlinks, non-regular files,
|
||||
empty files, missing checksums, duplicate records, and checksum mismatches; and
|
||||
calculate size without loading the complete file into memory. Do not fall back
|
||||
to the configured campaign/session path or accept canonical file presence
|
||||
without manifest evidence. Zero matching manifest records is the typed absent
|
||||
case; once a record exists, a missing or invalid file is an integrity error,
|
||||
not optional absence.
|
||||
- Return owner-neutral errors from `internal/artifacts`. At stage boundaries,
|
||||
wrap unavailable or stale prepared inputs with the source ID and actionable
|
||||
`narratio run-stage prepare <session_id> --force` guidance. Do not include file
|
||||
contents.
|
||||
- Replace analyze's private prepared-source filename switch and filesystem-only
|
||||
resolver with the shared artifact resolver. Preserve required-versus-optional
|
||||
Scriptorium input behavior: a typed absent optional source is omitted, an
|
||||
absent required source fails with prepare guidance, and invalid recorded
|
||||
evidence fails regardless of optionality. Make `narratio.input.spell_catalog`
|
||||
usable wherever another prepared Scriptorium source is accepted.
|
||||
|
||||
**Tests and exit criteria:** Artifact-package tests own valid resolution and the
|
||||
missing-record, duplicate-record, wrong-kind/path, traversal/rebase, symlink,
|
||||
non-regular, empty, missing-checksum, and checksum-mismatch boundaries. Analyze
|
||||
tests need only prove required/optional stage behavior and successful use of the
|
||||
shared source, including spell catalog; do not repeat the artifact resolver's
|
||||
full matrix. Remove the old filename/path resolver after its final caller moves.
|
||||
|
||||
## Stage 4 — Notarius Adapter Reference Arguments
|
||||
|
||||
**Read first:** `docs/internal/adapters.md`, `docs/integrations/notarius.md`,
|
||||
`internal/adapters/notarius/runner.go`, `fake.go`, `subprocess.go`, and focused
|
||||
adapter tests. Re-read the Notarius v0.6.0 subprocess and CLI reference-selector
|
||||
contracts from the tagged sibling checkout when available.
|
||||
|
||||
**Depends on:** Stage 1.
|
||||
|
||||
**Goal:** Extend the transport-neutral Notarius request and production adapter
|
||||
to emit safe, exact, repeatable v0.6 `--reference` arguments without changing
|
||||
receipt or bundle ingestion.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Add a transport-neutral reference binding containing normalized selector and
|
||||
absolute path, and add an ordered slice of those bindings to `RunRequest`.
|
||||
Keep source IDs and manifest identities out of the adapter contract; those are
|
||||
stage policy.
|
||||
- Validate each adapter binding before process launch: normalize/validate the
|
||||
selector through the shared Stage 1 contract, require a non-empty absolute
|
||||
path, reject duplicate normalized selectors, and avoid mutating the caller's
|
||||
slice. Do not open or parse the reference file in the adapter.
|
||||
- Build arguments as repeated pairs `--reference`,
|
||||
`<normalized-selector>=<absolute-path>` after `--output-dir` and before
|
||||
`--json`. Preserve one argument for the combined selector/path value so spaces,
|
||||
additional `=` characters within the path portion, and platform separators do
|
||||
not involve shell interpretation. The request order is authoritative; Stage 5
|
||||
will supply sorted bindings.
|
||||
- Preserve current executable, environment, timeout, cancellation, diagnostic,
|
||||
receipt-v2, bounded-read, confinement, and bundle-discovery behavior. Do not
|
||||
add `--without-reference`, generated reference arguments, version probing, or
|
||||
configuration preflight.
|
||||
- Update the fake only as required to retain and expose the extended request.
|
||||
|
||||
**Tests and exit criteria:** Adapter tests own exact argv with zero and multiple
|
||||
references, position before `--json`, spaces and `=` in paths, selector
|
||||
normalization, duplicate/invalid selector rejection, relative/empty path
|
||||
rejection, and no subprocess start after request-validation failure. Existing
|
||||
receipt-v2 and bundle fixture tests must remain unchanged in meaning and pass.
|
||||
Do not assert stage-level source sorting here beyond preserving the request
|
||||
order.
|
||||
|
||||
## Stage 5 — Extract Reference Identity, Invocation, And Resume
|
||||
|
||||
**Read first:** `docs/internal/stage-extract.md`,
|
||||
`docs/integrations/notarius.md`, `docs/internal/manifest.md`,
|
||||
`internal/stage/extract.go`, `internal/stage/extract_resume.go`, their focused
|
||||
tests, the Stage 3 prepared-input identity contract, and the Stage 4 Notarius
|
||||
request contract.
|
||||
|
||||
**Depends on:** Stages 3 and 4.
|
||||
|
||||
**Goal:** Make configured references part of the actual extraction invocation
|
||||
and durable reuse contract, using one resolution path for initial execution and
|
||||
resume validation.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Add one extract-owned reference-resolution helper used by both `Run` and
|
||||
`ValidateResume`. Iterate normalized config bindings in lexical selector
|
||||
order, resolve each source through the Stage 3 manifest-authoritative resolver,
|
||||
and produce both adapter bindings and immutable reference identities. Resolve
|
||||
every reference before creating run-local receipt, log, output, or promotion
|
||||
directories and before invoking the adapter.
|
||||
- Define the fingerprint/metadata identity as normalized selector, source ID,
|
||||
canonical session-relative slash path, SHA-256 checksum, and byte size. Do not
|
||||
include contents or original campaign/session absolute paths. Pass only
|
||||
selector and absolute prepared path to the adapter.
|
||||
- Extend the extraction fingerprint document with the sorted reference
|
||||
identities. Keep all existing binary, config path, pipeline, timeout, working
|
||||
directory, trimmed-transcript identity, and required-output identities. The
|
||||
result must be independent of YAML map iteration order and must change for a
|
||||
selector, source, relative path, checksum, or size change.
|
||||
- Persist `reference_count` and a bounded deterministic `references` metadata
|
||||
list on successful extraction. Each entry contains exactly `selector`,
|
||||
`source_id`, `path`, `checksum`, and `size_bytes`. Empty bindings produce count
|
||||
zero and an empty list. Do not duplicate Notarius reference payloads or
|
||||
downstream error messages.
|
||||
- Make resume recompute current reference identities through the same helper
|
||||
before comparing the configuration fingerprint. A valid changed prepared
|
||||
input yields a fingerprint mismatch and a non-resumable result so extraction
|
||||
reruns. Missing, unsafe, or checksum-inconsistent current input is an error
|
||||
with prepare-force guidance because immediately rerunning extract cannot
|
||||
succeed. Do not silently reuse the old bundle.
|
||||
- Preserve explicit disabled-stage skip without resolving references. Preserve
|
||||
required lane selection, immutable promotion, receipt identity, and bundle
|
||||
evidence behavior.
|
||||
|
||||
**Tests and exit criteria:** Stage tests own sorted request construction for all
|
||||
four D&D bindings, zero bindings, failure before adapter invocation for an
|
||||
unavailable source, content-free metadata, and fingerprint changes for each
|
||||
identity field while remaining stable across map order. Resume tests must prove
|
||||
reuse with unchanged references, non-reuse after a valid prepared-reference
|
||||
change, hard failure for missing or checksum-invalid current evidence, and no
|
||||
reference resolution when disabled. Use the fake adapter; do not duplicate exact
|
||||
subprocess argv cases from Stage 4.
|
||||
|
||||
## Stage 6 — Assembled Lifecycle And Invalidation Coverage
|
||||
|
||||
**Read first:** `docs/internal/overview.md`, `docs/internal/manifest.md`,
|
||||
`docs/internal/stage-extract.md`, `docs/internal/stage-prepare.md`,
|
||||
`internal/app/runner.go`,
|
||||
`internal/app/extract_lifecycle_test.go`, and representative full pipeline and
|
||||
stage fixtures. Inspect existing downstream invalidation tests before adding
|
||||
new cases.
|
||||
|
||||
**Depends on:** Stage 5.
|
||||
|
||||
**Goal:** Prove at the application boundary that prepared campaign context
|
||||
reaches Notarius and that reference changes cannot leave extraction or later
|
||||
analysis falsely current.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Extend the smallest existing assembled runner fixture to execute prepare and
|
||||
extract with party, players, glossary, and spell catalog bindings. Assert that
|
||||
the fake Notarius request receives the four canonical prepared absolute paths,
|
||||
not the original campaign/session source paths, and that the successful
|
||||
manifest records bounded reference identity.
|
||||
- Add one lifecycle regression covering a valid reference-content change:
|
||||
rerun/force prepare so the manifest and prepared checksum change, then verify
|
||||
extract resume is rejected, Notarius runs again, and succeeded canonical
|
||||
downstream stages are invalidated according to the existing stage-order
|
||||
policy. Assert outcomes, not private runner call choreography.
|
||||
- Add one representative session override case to prove the overridden prepared
|
||||
bytes/checksum reach extraction. Do not repeat all four configuration merge
|
||||
cases or artifact-integrity failures already owned by earlier stages.
|
||||
- Confirm an empty reference map preserves the pre-v0.6 invocation behavior and
|
||||
that all ten configured D&D lanes remain registered as the same
|
||||
`narratio.extraction.<key>` sources available to analyze.
|
||||
- Fix production integration defects exposed by these assembled tests without
|
||||
broadening the feature or adding a DAG, generic reference workflow, or direct
|
||||
Notarius payload parsing.
|
||||
|
||||
**Tests and exit criteria:** The application-level tests must be deterministic,
|
||||
offline, and fake only the external Notarius boundary. They must credibly fail
|
||||
if Narratio passes original paths, omits one configured reference, reuses stale
|
||||
extraction, or loses a configured lane, while remaining insensitive to private
|
||||
helper structure and exact non-contractual diagnostics. Earlier focused suites
|
||||
and the repository baseline remain green.
|
||||
|
||||
## Stage 7 — Canonical Documentation And Maintained Examples
|
||||
|
||||
**Read first:** `docs/policy/documentation.md`, `docs/config.md`,
|
||||
`docs/operations.md`, `docs/troubleshooting.md`,
|
||||
`docs/integrations/notarius.md`, `docs/internal/overview.md`,
|
||||
`docs/internal/adapters.md`, `docs/internal/artifacts.md`,
|
||||
`docs/internal/stage-prepare.md`, `docs/internal/stage-extract.md`,
|
||||
`docs/internal/stage-analyze.md`, `examples/README.md`, and all maintained
|
||||
pipeline, campaign, and session examples affected by the new fields.
|
||||
|
||||
**Depends on:** Stage 6.
|
||||
|
||||
**Goal:** Move the completed behavior from roadmap-only future state into its
|
||||
canonical current-behavior owners and provide valid copyable D&D examples
|
||||
without duplicating volatile Notarius contracts.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Update `docs/config.md` with `pipeline.notarius.references`, its selector-to-
|
||||
source shape, normalization/validation rules, required-by-presence behavior,
|
||||
supported stable source IDs, and campaign/session `spell_catalog_file`
|
||||
precedence and optionality. Keep complete copyable YAML in `examples/`.
|
||||
- Update `docs/integrations/notarius.md` to the v0.6.0 baseline and exact
|
||||
repeatable-reference invocation boundary. Explain absolute CLI paths,
|
||||
precedence over configured external paths, the four maintained external D&D
|
||||
slots, the generated-handoff exclusion, and unchanged receipt-v2/ten-lane
|
||||
output compatibility. Link to Notarius's canonical v0.6 CLI and D&D consumer
|
||||
docs instead of copying its target/module matrix.
|
||||
- Update operations and troubleshooting with prepared input location,
|
||||
fingerprint/rerun consequences, operator inspection, missing-reference
|
||||
diagnosis, and Notarius undeclared-slot/generated-collision failures. Update
|
||||
internal component documents only with implemented ownership and flow; do not
|
||||
duplicate configuration field definitions there.
|
||||
- Add a valid, secret-free sample spell catalog following Notarius v0.6's
|
||||
published overlay schema, add `spell_catalog_file` to the sample campaign, and
|
||||
configure all four external reference bindings in the complete annotated D&D
|
||||
pipeline. Add the same bindings to other Notarius-enabled maintained examples
|
||||
only when their selected pipeline declares them; do not add a Notarius section
|
||||
to examples that intentionally omit extraction.
|
||||
- Ensure the maintained command snippets place repeated `--reference` arguments
|
||||
before `--json`, use `party` rather than `roster`, and never show generated
|
||||
handoffs on the CLI. Remove stale v0.5 compatibility wording where it refers to
|
||||
the supported invocation baseline.
|
||||
|
||||
**Tests and exit criteria:** Run documentation-link checks and the example
|
||||
loader explicitly. Verify every changed example is accepted by strict config
|
||||
validation, contains no credentials or private infrastructure values, and has
|
||||
one canonical owner for each volatile fact. Search current-behavior docs and
|
||||
examples for stale v0.5 invocation wording, deprecated `roster` emission, and
|
||||
generated D&D CLI handoff examples. Do not mark the roadmap itself implemented;
|
||||
its status remains target-state context until the implementation sprint is
|
||||
reviewed and closed.
|
||||
|
||||
## Stage 8 — Compatibility And Quality Closure
|
||||
|
||||
**Read first:** The feature roadmap, every completed stage diff, the final
|
||||
current-behavior docs, `.woodpecker/verify.yml`, `.woodpecker/release.yml`, and
|
||||
`.woodpecker/shuffle.yml`. Re-read the tagged Notarius v0.6.0
|
||||
`docs/consumers/dnd-pipeline.md`, `docs/cli.md`, and linked spell-catalog overlay
|
||||
contract when the sibling checkout is available.
|
||||
|
||||
**Depends on:** Stage 7.
|
||||
|
||||
**Goal:** Verify the delivered code matches the accepted boundary, remains
|
||||
compatible with all ten default D&D artifacts, and is ready for review without
|
||||
dead compatibility paths or duplicated policy.
|
||||
|
||||
**Work:**
|
||||
|
||||
- Audit the final diff against every target-state and out-of-scope statement in
|
||||
the feature roadmap. Confirm only four external prepared sources are exposed,
|
||||
custom selectors remain possible, every configured binding is required, and
|
||||
no Notarius pipeline topology or generated-handoff logic moved into Narratio.
|
||||
- Trace initial extract and resume paths to confirm both use the same prepared
|
||||
identity and reference resolution, the adapter is the sole argv builder, and
|
||||
artifact policy is the sole source-to-kind/filename vocabulary. Remove dead
|
||||
helpers, redundant switches, stale fixtures, and low-value duplicate tests
|
||||
found during this review.
|
||||
- Confirm the complete D&D example still declares and validates the exact ten
|
||||
output lanes and that analyze can consume those sources after reference-
|
||||
enabled extraction. Confirm empty-reference custom pipelines remain supported.
|
||||
- If a local Notarius v0.6.0 binary and its required offline/test configuration
|
||||
are already available, perform a non-credentialed smoke invocation with all
|
||||
four reference flags and record the result in the implementation handoff. Do
|
||||
not download tools, contact paid providers, add a default test dependency, or
|
||||
block completion solely because this supplementary environment is absent.
|
||||
- Run the repository baseline plus the scheduled shuffled suite and release
|
||||
cross-build commands:
|
||||
|
||||
```sh
|
||||
go test ./...
|
||||
go test -race ./...
|
||||
go test -race -shuffle=on -count=3 ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
go test ./internal/doccheck
|
||||
go test ./internal/config -run '^TestExamplesLoadAndValidate$'
|
||||
narratio_cross_dir="$(mktemp -d)"
|
||||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-linux-amd64" ./cmd/narratio
|
||||
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-darwin-amd64" ./cmd/narratio
|
||||
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-windows-amd64.exe" ./cmd/narratio
|
||||
```
|
||||
|
||||
Cross-builds are compilation evidence only; do not claim native macOS or
|
||||
Windows runtime validation.
|
||||
|
||||
**Tests and exit criteria:** Every required command passes, `git diff --check`
|
||||
is clean, the worktree contains no unintended generated test artifacts, and the
|
||||
implementation is traceably complete against the roadmap. Summarize any
|
||||
unavailable supplementary smoke evidence without treating it as a product
|
||||
question or silently weakening the default suite.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None. The feature roadmap and governing decisions above are sufficient to
|
||||
implement the plan without additional product or architecture choices.
|
||||
Reference in New Issue
Block a user