From 5e96790d850bc29e0810f680fb249e113031d5ee Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 31 Jul 2026 01:59:13 +0000 Subject: [PATCH] Correct documentation refresh findings --- docs/internal/app-orchestration.md | 5 +- docs/internal/scriptorium-adapter.md | 2 +- docs/internal/state.md | 2 +- docs/policy/architecture.md | 24 +- docs/roadmap/implementation.md | 630 --------------------------- 5 files changed, 20 insertions(+), 643 deletions(-) delete mode 100644 docs/roadmap/implementation.md diff --git a/docs/internal/app-orchestration.md b/docs/internal/app-orchestration.md index 34dcbee..9683649 100644 --- a/docs/internal/app-orchestration.md +++ b/docs/internal/app-orchestration.md @@ -40,8 +40,9 @@ ordered work: 3. Build and save the prompt data package, run Scriptorium render preflight, save any preflight result, and save initial metadata. 4. Produce managed Markdown according to the report generation mode. -5. Finalize metadata, optionally make an output copy, and optionally notify - Distributor from the managed report path. +5. Optionally make an output copy, save final metadata, optionally notify + Distributor from the managed report path, and save metadata again when a + notification path is produced. Direct-Markdown reports prepare the managed report and invoke the Scriptorium run boundary. Generated-text-template reports look up their catalog definition, diff --git a/docs/internal/scriptorium-adapter.md b/docs/internal/scriptorium-adapter.md index 67791fa..e06b52d 100644 --- a/docs/internal/scriptorium-adapter.md +++ b/docs/internal/scriptorium-adapter.md @@ -1,6 +1,6 @@ # Scriptorium Adapter Internals -`internal/adapters/scriptorium` translates Weather Reporter render requests to +`internal/adapters/scriptorium` translates Weatherreporter render requests to Scriptorium process arguments and translates process results back to local types. The external CLI and output contract belongs to the [Scriptorium integration guide](../integrations/scriptorium.md); prompts, diff --git a/docs/internal/state.md b/docs/internal/state.md index 44bea39..c58730d 100644 --- a/docs/internal/state.md +++ b/docs/internal/state.md @@ -53,7 +53,7 @@ writes use `fileutil.WriteJSONAtomic`, so readers do not observe a partially written state file. The data package itself follows the shared -[weather-data contract](weather-data.md). Report text, templates, and external +[prompt-input contract](prompt-input.md). Report text, templates, and external delivery payloads remain owned by their respective packages and integration references. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index b890431..eefde26 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -17,9 +17,10 @@ mechanics must preserve. Weatherreporter is a deterministic weather briefing and report-preparation CLI. It consumes normalized weather data, derives report facts and module snapshots, builds curated prompt packages, compares structured snapshots with prior runs, -invokes Scriptorium for bounded generated text, renders managed Markdown -reports, persists inspectable artifacts, and can upload completed reports -through Distributor. +and invokes Scriptorium either to produce managed Markdown directly or to +produce bounded generated-text prose for repository-owned templates. It +persists inspectable artifacts and can upload completed reports through +Distributor. The application is intentionally a small, explicit, dependency-light Go program. Add abstraction only when it protects a real boundary, makes an @@ -32,8 +33,9 @@ The primary flow is: 3. normalized weather collection; 4. deterministic fact derivation and module construction; 5. structured prior-snapshot comparison; -6. curated prompt input and generated-text processing; -7. managed Markdown rendering and metadata persistence; and +6. curated prompt input and report-mode-specific Scriptorium processing; +7. generated-text validation when applicable, managed Markdown production, + and metadata persistence; and 8. optional notification using managed report artifacts. Inspection is a separate read-only flow over persisted state. It must not @@ -128,10 +130,14 @@ lookup. Keep weather derivation and path construction out of templates. weather facts. - LLM prompts receive curated module-based packages rather than raw, unbounded source payloads. -- Generated text is limited to defined prose slots, validated before use, and - rendered through typed or otherwise explicit contexts. -- Templates arrange validated prose and deterministic facts; they do not - perform meteorological derivation. +- For generated-text-template reports, generated text is limited to defined + prose slots, validated before use, and rendered through typed or otherwise + explicit contexts. +- Direct-Markdown reports receive the same curated prompt-package boundary but + produce managed Markdown directly through Scriptorium rather than the + generated-text schema and repository-template workflow. +- Repository-owned templates arrange validated prose and deterministic facts; + they do not perform meteorological derivation. ### Reports And Comparison diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 92b31e1..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,630 +0,0 @@ -# Documentation Refresh Implementation Plan - -## Status - -Accepted for implementation. - -This is a temporary, staged coordination plan for refreshing Weatherreporter's -current documentation. Implement each stage in order. Do not treat this file as -a current-behavior reference. - -## Objective - -Bring every maintained document and example into agreement with: - -- the implemented Go application; -- the canonical ownership rules in `docs/policy/documentation.md`; -- the architectural boundaries in `docs/policy/architecture.md`; -- the testing rules in `docs/policy/testing.md`; and -- the contributor routing in `docs/development.md`. - -The completed documentation set must be concise, task-oriented, free of stale -or duplicate contracts, and verifiably consistent with the executable sources -of truth. - -## Scope And Constraints - -This is a documentation-only refresh. - -- Do not add or change product behavior. -- Do not modify Go code, schemas, prompts, or templates to make documentation - claims true. -- `examples/*.yml` may be corrected when they disagree with implemented - configuration, because examples are maintained documentation artifacts. -- If code and documentation disagree, document implemented and tested behavior. -- If code appears to violate an architecture or safety policy, do not conceal - the conflict with prose and do not fix it during this refresh. Record the - conflict in this plan's implementation notes and report it to the maintainer. -- Do not implement any work from `docs/roadmap/future.md` or - `docs/roadmap/promptkit.md`. -- Preserve the exact contents of `AGENTS.md`. -- Treat `docs/policy/*.md` and `docs/development.md` as the governing baseline. - Change them only to repair a link made stale by this refresh; do not reopen - their substantive decisions. -- Do not create `docs/internal/overview.md`; `docs/development.md` owns the - current concise package inventory. -- Do not introduce a release guide, public API guide, consumer guide, or ADR - unless a separate maintainer decision expands this plan. -- Preserve unrelated working-tree changes and do not commit unless explicitly - instructed. - -## Executable Authorities - -Use codebase-memory graph tools before text search for code discovery. Index the -repository first if needed, use `search_graph` to locate symbols, -`trace_path` for dependencies and impact, and `get_code_snippet` for exact -source. Use graph-augmented `search_code` or `rg` for literal flags, paths, -errors, schemas, asset names, and configuration values. - -The primary authorities for this refresh are: - -| Contract | Executable authority | -| --- | --- | -| CLI commands, flags, help, and dispatch | `internal/cli/root.go`, `internal/report/names.go`, and `internal/cli/root_test.go` | -| CLI JSON summaries and stdout/stderr behavior | `internal/cli/output.go`, `internal/cli/result.go`, and their tests | -| Configuration fields, defaults, loading, precedence, secrets, templates, and validation | `internal/config/*.go` and `internal/config/config_test.go` | -| Report IDs, modes, periods, modules, output names, comparison, and Distributor paths | `internal/report/*.go` and `internal/report/period_test.go` | -| Application generation, batch, inspection, persistence, and notification order | `internal/app/*.go`, `internal/app/*_test.go`, and `internal/cli/root_test.go` | -| Weather collection and external Weather API behavior | `internal/collect`, `internal/weatherdata`, `internal/adapters/weatherapi`, fixtures, and focused tests | -| Facts, forecast derivation, modules, and Recent Changes | `internal/facts`, `internal/forecast`, `internal/module`, `internal/briefing`, `internal/changes`, and focused tests | -| Prompt packages and Scriptorium invocation | `internal/promptinput`, `internal/adapters/scriptorium`, and focused tests | -| Generated text, render contexts, templates, and schemas | `internal/generatedtext`, `internal/reporttemplate`, embedded assets, and focused tests | -| Workspace paths, metadata, atomic writes, prior lookup, and inspection | `internal/state`, `internal/fileutil`, and focused tests | -| Distributor bundle, upload, polling, redaction, and notification behavior | `internal/adapters/distributor`, `internal/app/batch_notification.go`, `go.mod`, and focused tests | - -Sibling repositories may be used only as secondary integration references. -Weatherreporter's pinned dependency, adapter code, and tests determine the -subset this repository actually uses. Do not copy broad upstream manuals into -this repository. - -## Rules For Every Stage - -For each stage: - -1. Read the task-specific entries in `docs/development.md`. -2. Inspect the listed executable authorities and focused tests. -3. Update only the files assigned to the stage, plus this plan's stage status - if progress tracking is requested. -4. Keep exact facts in their canonical owner. Replace duplicate detail with a - short stable summary and a relative link. -5. Describe implemented behavior only outside `docs/roadmap/`. -6. Keep examples synthetic, valid, and secret-free. -7. Use language tags on every fenced block. -8. Run the stage validation before proceeding. -9. Do not reinterpret surprising behavior as intent; tests and executable - contracts take precedence over old prose. - -## Stage 1: Inventory And Mechanical Hygiene - -### Files - -- `README.md` -- all Markdown files under `docs/` -- `examples/*.yml` - -### Work - -1. Classify every document under the ownership table in - `docs/policy/documentation.md`. Do not create a separate permanent inventory - document. -2. Identify duplicated exact contracts, stale paths, broken links, untagged - code fences, and current-state claims in the wrong document. -3. Repair mechanical link and path defects that do not require content - redesign. -4. In `docs/integrations/distributor/pkg-bundle.md`, remove the broken local - link to `../integrations/source-bundle.md`. Identify the upstream canonical - file as `docs/integrations/source-bundle.md` in the Distributor repository - using prose or code formatting, not a nonexistent repository-relative link. -5. In `docs/integrations/distributor/pkg-upload.md`, do the same for the broken - `../integrations/http-upload.md` link. -6. Confirm that no document references the retired development-policy path. -7. Defer substantive rewrites to the assigned later stage; this stage should - establish a clean mechanical baseline. - -### Acceptance - -- Every repository-relative link target exists. -- All fenced blocks have language tags. -- No stale development-policy reference remains. -- No future feature is presented as current behavior outside `docs/roadmap/`. -- `git diff --check` passes. - -## Stage 2: CLI, Configuration, And Examples - -### Files - -- `docs/cli.md` -- `docs/config.md` -- `examples/minimal-config.yml` -- `examples/config.yml` - -### CLI Work - -1. Regenerate the command inventory from `go run ./cmd/weatherreporter --help` - and verify it against `internal/cli/root.go` and report command-name tests. -2. Keep this document's order: - - shortest useful command; - - command overview and complete usage; - - stdout, stderr, JSON summary, quiet-mode, and exit behavior; - - complete flag reference; - - concise invocation examples; and - - inspection commands. -3. Keep exact command syntax and output semantics here. Move or replace - operational workflow explanations with links to `operations.md`. -4. Verify all seven generate commands, both batch commands, and every inspect - command. -5. Verify command-specific restrictions: required Daily date, optional Today - date, Storm bounds, Hourly restrictions, generate output copies, batch - output directories, and inspection quiet-mode rejection. - -### Configuration Work - -1. Compare every documented field and default with `Config`, `Defaults`, - loading, secret loading, report overrides, notification templates, and - validation code. -2. Keep discovery, precedence, fields, defaults, accepted values, validation - rules, secret-supply behavior, and links to examples here. -3. Keep operational notification sequencing, filesystem lifecycle, and - recovery in `operations.md`; summarize and link rather than duplicate them. -4. Verify report-module override keys against the report registry and module - registry. -5. Verify every template placeholder accepted by Distributor notification - configuration. - -### Example Work - -1. Ensure both examples contain only implemented fields and synthetic - endpoints. -2. Keep `minimal-config.yml` genuinely minimal. -3. Keep `config.yml` production-oriented and representative without becoming a - second field reference. -4. Do not add credentials, private endpoints, or generated reports. - -### Validation - -```sh -go run ./cmd/weatherreporter --help -go test ./internal/cli ./internal/config ./internal/report ./internal/module -git diff --check -``` - -The config tests must load the maintained examples successfully. - -## Stage 3: README And Operations - -### Files - -- `README.md` -- `docs/operations.md` - -### README Work - -Keep the README short and in this order: - -1. concise product description; -2. one-sentence value proposition; -3. the shortest successful generation command; and -4. links to CLI, configuration, operations, troubleshooting, development, and - architecture documentation. - -Do not add a complete command list, configuration fields, workspace layout, or -future Promptkit behavior. - -### Operations Work - -1. Verify generation and batch workflow order against `internal/app`. -2. Verify the physical workspace tree, artifact names, RunID placement, - metadata links, notification artifact placement, and prior lookup against - `internal/state`. -3. Verify output-copy behavior and the rule that managed reports are the only - upload sources. -4. Verify single-report and batch notification sequencing, skip conditions, - failure accounting, and inspectable artifacts. -5. Verify inspection is read-only and identify exactly which artifacts each - command reads. -6. Keep normal operation, state lifecycle, inspection, recovery, and - operational caveats here. -7. Replace complete flag or config-field definitions with links to their - canonical references. -8. Keep only the minimal commands needed to illustrate an operational - procedure. - -### Validation - -```sh -go test ./internal/app ./internal/state ./internal/cli -go run ./cmd/weatherreporter --help -git diff --check -``` - -## Stage 4: Troubleshooting - -### File - -- `docs/troubleshooting.md` - -### Work - -1. Verify every documented symptom and diagnostic fragment against current - errors and failure tests. -2. Use one consistent entry shape: - - symptom; - - likely cause; - - diagnostic step or command; - - safe fix; and - - links to canonical references. -3. Keep symptom-oriented diagnosis here. Remove repeated normal workflows, - full endpoint inventories, config-field definitions, and artifact schemas. -4. Preserve the distinction between pre-run failures, collection failures, - Scriptorium preparation/run failures, generated-text validation failures, - template failures, report failures, batch partial failures, skipped batch - uploads, Distributor failures, secret loading, and state lookup failures. -5. Use exact error text only when it is a stable operator-facing contract; - otherwise use the smallest stable identifying fragment. -6. Ensure fixes are safe, narrow, and do not recommend broad workspace - deletion or expose secret values. - -### Validation - -```sh -go test ./internal/cli ./internal/config ./internal/app ./internal/state -go test ./internal/adapters/weatherapi ./internal/adapters/scriptorium ./internal/adapters/distributor -git diff --check -``` - -## Stage 5: Report Template Guide - -### File - -- `docs/templates.md` - -### Work - -1. Verify top-level templates, shared partials, schema IDs, prompt sources, and - registered template functions against `internal/reporttemplate`. -2. Verify every documented render-context field against - `internal/generatedtext`; remove fields that are absent and add implemented - fields needed by maintainers. -3. Keep the maintainer-facing editing rules, context contracts, and minimal - template examples here. -4. Clearly distinguish deterministic module values, collected/derived facts, - and validated GeneratedText prose. -5. Keep weather derivation and generated-text validation mechanics in their - internal owners; summarize and link from this guide. -6. Avoid duplicating the full JSON schema bodies or package implementation - flow. - -### Validation - -```sh -go test ./internal/reporttemplate ./internal/generatedtext ./internal/app -git diff --check -``` - -## Stage 6: Weather API Integration - -### File - -- `docs/integrations/weatherapi.md` - -### Work - -1. Verify URL joining, query parameters, timeout and retry behavior, response - envelope, endpoint set, decoding, source identity, warnings, and - required/optional source behavior against the adapter, collection layer, - fixtures, and tests. -2. Keep the external Weather API contract and compatibility assumptions here. -3. Move internal normalization and orchestration mechanics to links pointing at - the relevant internal documents. -4. Document only endpoints and fields Weatherreporter currently consumes. - -### Validation - -```sh -go test ./internal/adapters/weatherapi ./internal/collect ./internal/weatherdata -git diff --check -``` - -## Stage 7: Scriptorium Integration - -### File - -- `docs/integrations/scriptorium.md` - -### Work - -1. Verify the exact `render` and `run` invocations, argument ordering, - timeouts, output paths, result decoding, stderr handling, cancellation, and - failure behavior against the adapter and tests. -2. Keep the external CLI contract here and link to internal prompt-input, - adapter, generated-text, and orchestration mechanics. -3. Describe Scriptorium as the implemented runtime. Do not mention the proposed - Promptkit replacement outside `docs/roadmap/promptkit.md`. -4. Do not copy Scriptorium's general manual; document only the commands and - result fields Weatherreporter uses. - -### Validation - -```sh -go test ./internal/adapters/scriptorium ./internal/promptinput ./internal/app -git diff --check -``` - -## Stage 8: Distributor Integration - -### Files - -- `docs/integrations/distributor/api.md` -- `docs/integrations/distributor/pkg-bundle.md` -- `docs/integrations/distributor/pkg-upload.md` - -### Work - -1. Rewrite these as concise references to the exact Distributor surface used - by Weatherreporter: - - `api.md` owns accepted upload, authentication, idempotency, run status, - terminal failure, and retention assumptions used by the adapter; - - `pkg-bundle.md` owns the bundle file mapping and path constraints used by - Weatherreporter; - - `pkg-upload.md` owns the client construction, upload, retry, conflict, and - status operations used by the adapter. -2. Remove generic producer tutorials, broad upstream feature descriptions, - unrelated examples, and claims Weatherreporter does not rely on. -3. Verify the pinned module version in `go.mod` and the adapter's actual calls. -4. Use the sibling Distributor repository only to confirm the pinned API. Do - not make Weatherreporter documentation depend on sibling-relative links. -5. Keep internal request construction, redaction, polling decisions, and app - notification order in internal documents. -6. Ensure all local links resolve and upstream canonical paths are identified - without pretending those files exist in this repository. - -### Validation - -```sh -go test ./internal/adapters/distributor ./internal/app ./internal/config -git diff --check -``` - -## Stage 9: CLI, Collection, And App Internals - -### Files - -- `docs/internal/cli.md` -- `docs/internal/collect.md` -- `docs/internal/app-orchestration.md` - -### Work - -Verify purpose, inputs and outputs, ownership boundaries, workflow composition, -failure propagation, focused tests, and invariants. Keep public CLI syntax in -`docs/cli.md`, Weather API wire behavior in its integration document, and -physical state layout in `docs/operations.md` or `docs/internal/state.md`. - -The app document may retain explicit workflow ordering because orchestration is -its owned internal contract. It must not duplicate complete config, CLI, or -external protocol references. - -### Validation - -```sh -go test ./internal/cli ./internal/collect ./internal/app -git diff --check -``` - -## Stage 10: State, Source, And Adapter Internals - -### Files - -- `docs/internal/state.md` -- `docs/internal/weather-data.md` -- `docs/internal/scriptorium-adapter.md` -- `docs/internal/distributor-adapter.md` - -### Work - -1. Verify each document against its package and focused tests. -2. Keep state path derivation, metadata ownership, prior lookup, atomic writes, - and inspection mechanics in the state document. -3. Keep normalized bundle, source metadata, and warning semantics in the - weather-data document. -4. Keep argv/result translation in the Scriptorium adapter document and - dependency/client translation in the Distributor adapter document. -5. Link external contracts and user-facing references rather than repeating - them. - -### Validation - -```sh -go test ./internal/state ./internal/weatherdata -go test ./internal/adapters/scriptorium ./internal/adapters/distributor -git diff --check -``` - -## Stage 11: Deterministic Domain Internals - -### Files - -- `docs/internal/facts.md` -- `docs/internal/forecast-derivation.md` -- `docs/internal/changes.md` - -### Work - -Verify fact ownership, derivation inputs, period and daypart behavior, -thresholds, comparison strategies, missing-data behavior, failures, tests, and -invariants. Keep these documents deterministic and independent of CLI, -filesystem, subprocess, and transport mechanics. Link configuration defaults -instead of restating them. - -### Validation - -```sh -go test ./internal/facts ./internal/forecast ./internal/changes ./internal/timeutil -git diff --check -``` - -## Stage 12: Reports, Modules, Briefing, And Prompt Input - -### Files - -- `docs/internal/report-registry.md` -- `docs/internal/module.md` -- `docs/internal/briefing.md` -- `docs/internal/prompt-input.md` - -### Work - -1. Verify all report definitions, registry fields, valid periods, batch - membership, comparison policy, output naming, module defaults, and - Distributor path declarations. -2. Verify registered module IDs, options, rich values, prompt exports, - composition by report, and missing-source behavior. -3. Verify prompt package schema, ordering, metadata, serialization, validation, - and the boundary between rich module values and prompt-facing exports. -4. Keep exact CLI command syntax, config defaults, integration protocol, and - rendered template contracts in their canonical owners. -5. Prefer tables for report-to-module or report-to-mode mappings where they - materially reduce repeated prose. - -### Validation - -```sh -go test ./internal/report ./internal/module ./internal/briefing ./internal/promptinput -git diff --check -``` - -## Stage 13: Generated Text And Template Internals - -### Files - -- `docs/internal/generatedtext.md` -- `docs/internal/reporttemplate.md` - -### Work - -Verify catalog registration, schema selection, decoding and validation, -generated-text types, render-context construction, embedded asset lookup, -template parsing, partials, failure behavior, and invariants. Keep the complete -maintainer-facing context-field reference in `docs/templates.md`; internal -documents should explain implementation and link to that contract. - -### Validation - -```sh -go test ./internal/generatedtext ./internal/reporttemplate ./internal/app -git diff --check -``` - -## Stage 14: Roadmap Review - -### Files - -- `docs/roadmap/future.md` -- `docs/roadmap/promptkit.md` - -### Work - -1. Ensure every roadmap item is explicitly unimplemented, proposed, accepted, - deferred, or rejected. -2. Remove or rewrite work that has already been implemented. -3. Keep current-state summaries minimal and link to canonical current - documentation instead of reproducing it. -4. In `future.md`, correct the Distributor enhancement introduction so it - acknowledges implemented single-report and batch notification without - maintaining their detailed current contract. -5. Preserve the Promptkit roadmap as future migration policy. Do not implement - it, resolve its product-design open questions, or describe it as current. -6. Ensure future architecture does not leak into README, user/operator docs, - integrations, or current internal docs. - -### Validation - -```sh -rg -n "Promptkit|promptkit" README.md docs \ - --glob "*.md" --glob "!docs/roadmap/**" -git diff --check -``` - -The Promptkit search must return no current-state documentation matches. - -## Stage 15: Cross-Document Consistency And Final Validation - -### Semantic Review - -Verify these cross-document facts have one exact owner and consistent summaries -elsewhere: - -- seven generate report commands; -- four generated-text-template reports and three direct-Markdown reports; -- morning and evening batch membership and future Daily eligibility; -- configuration precedence and defaults; -- module and report IDs; -- managed workspace and notification paths; -- Recent Changes structured comparison; -- Scriptorium preflight and run behavior; -- single-report and batch Distributor behavior; -- output copies versus managed upload sources; and -- inspection's read-only behavior. - -Remove duplicate exact tables or narratives from non-owning documents. Preserve -short task-relevant summaries and relative links. - -### Link Validation - -Check every Markdown link in `README.md` and `docs/`. Repository-relative -targets and changed heading anchors must resolve. No maintained document may -depend on sibling checkout paths. - -At minimum, run a repository-relative target check equivalent to: - -```sh -find README.md docs -type f -name "*.md" -print0 | - while IFS= read -r -d "" file; do - dir=$(dirname "$file") - rg -o '\]\([^)]+\)' "$file" | - sed -E 's/^\]\(([^)#]+)(#[^)]+)?\)$/\1/' | - while IFS= read -r target; do - case "$target" in - http:*|https:*|mailto:*) continue - esac - test -z "$target" || test -e "$dir/$target" || - printf '%s -> %s\n' "$file" "$target" - done - done -``` - -Manually verify anchors on every changed link because the target check does not -validate fragments. - -### Final Commands - -```sh -go test ./... -go run ./cmd/weatherreporter --help -git diff --check -``` - -Review `git diff --name-only` and confirm the refresh changed only Markdown and -maintained YAML examples. Confirm no secrets, private endpoints, generated -artifacts, code changes, `go.work`, or local module replacements were added. - -## Completion Criteria - -The refresh is complete when: - -- every document has one clear canonical owner; -- current user and operator documentation matches implemented behavior; -- CLI and configuration references are complete and verified; -- examples load and contain no secrets; -- operation, recovery, template, and integration contracts are accurate; -- internal documents preserve package boundaries without duplicating public - references; -- roadmaps contain only future or coordination material; -- all repository-relative links and changed anchors resolve; -- all validation commands pass; and -- no unresolved architecture-policy conflict was hidden or implemented as part - of the documentation work. - -After all stages are accepted, remove this temporary implementation plan in a -final documentation-only change. Do not move its task sequencing or completion -history into current-state documentation.