Remove completed documentation alignment roadmaps

2026-08-09 22:02:07 +00:00
parent c3c14e7468
commit df58595d1e
2 changed files with 0 additions and 899 deletions
--- a/docs/roadmap/documentation.md
+++ b/docs/roadmap/documentation.md
@@ -1,355 +0,0 @@
 # Documentation Policy And Structure Alignment
 ## Status
 Completed.
 ## Purpose
 Align Narratio's documentation policy, organization, and maintenance practices
 with the current Notarius approach while preserving Narratio-specific product,
 operational, and integration needs.
 The resulting documentation set should assign each authoritative topic to one
 canonical owner, distinguish current behavior from future work, make audience
 boundaries explicit, and minimize duplicated contracts that can drift as the
 application changes.
 This roadmap defines the scope and intended final state. Execution guidance is
 maintained separately in the [Implementation Plan](implementation.md).
 ## Motivation
 Narratio already has substantial user, operator, integration, and internal
 documentation, but its documentation policy predates the current Notarius
 policy. The existing policy prescribes document profiles and detailed outlines
 without defining ownership boundaries precisely enough. Several policy files
 also refer to obsolete or nonexistent paths, and some concrete inventories and
 contract details are repeated across documents.
 The alignment should retain useful Narratio documentation while adopting the
 stronger Notarius principles:
 - one canonical owner for each authoritative fact;
 - current behavior outside the roadmap and future behavior inside it;
 - audience-appropriate detail;
 - maintained, valid, secret-free examples;
 - explicit boundaries among user, operator, integration, architecture, and
  internal documentation;
 - a defined lifecycle for architectural decision records; and
 - verification of documentation against implemented behavior.
 ## Target Documentation Model
 ### Canonical Ownership
 The final documentation policy should assign the following responsibilities.
 | Topic | Canonical owner | Intended responsibility |
 | --- | --- | --- |
 | Product orientation and minimal end-to-end quickstart | `README.md` | Explain what Narratio is, why it is useful, show the shortest successful invocation, and route readers onward. |
 | Contributor entry point | `docs/development.md` | Provide a task-oriented reading guide, baseline validation commands, and links to canonical policies and contracts. |
 | Current application architecture | `docs/policy/architecture.md` | Define system shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. |
 | Documentation organization | `docs/policy/documentation.md` | Define canonical ownership, audience boundaries, maintenance rules, and the ADR and document lifecycle. |
 | Testing policy | `docs/policy/testing.md` | Define test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, and test lifecycle decisions. |
 | CLI contract | `docs/cli.md` | Define commands, arguments, flags, invocation semantics, output conventions, and exit behavior. |
 | Configuration contract | `docs/config.md` | Define discovery, precedence, schemas, fields, defaults, environment overrides, and validation rules. |
 | Operations | `docs/operations.md` | Define runtime workflows, physical state layout, resume, cleanup, permissions, recovery, and operational limits. |
 | Troubleshooting | `docs/troubleshooting.md` | Provide symptom-driven diagnosis and safe remedies, linking to the owning CLI, configuration, operations, or integration contract. |
 | External and durable integration contracts | `docs/integrations/` | Define the external formats, protocols, logical artifact shapes, and compatibility behavior Narratio relies on. |
 | Implemented component inventory | `docs/internal/overview.md` | Inventory current packages and components, summarize their implemented responsibilities, and route readers to focused internal documents. |
 | Internal component behavior | Other files under `docs/internal/` | Explain implementation flow, internal collaborators, state transitions, package-local guarantees and failures, and relevant tests. |
 | Architectural decision history | `docs/adr/` | Record significant decisions, alternatives, rationale, consequences, and supersession history when ADRs are warranted. |
 | Future work and implementation status | `docs/roadmap/` | Describe proposed, accepted, deferred, rejected, or completed work and its implementation status. |
 | Complete copyable artifacts | `examples/` | Hold maintained configuration, inputs, and other files intended to be copied or run. |
 Documents for interfaces that Narratio does not expose should not be created as
 placeholders. In particular, public API or consumer documentation should be
 added only if a corresponding public interface exists.
 ### Structural Parity With Notarius
 Narratio should follow the current Notarius policy layout where the same
 responsibility exists. In the aligned structure:
 - `docs/internal/overview.md` is the internal component inventory;
 - `docs/development.md` is the first-read contributor landing page;
 - all navigation and relative links use those canonical paths;
 - `docs/adr/` and sequentially numbered ADR filenames are used when architectural
  decisions need durable records; and
 - Narratio-specific canonical documents remain, including the troubleshooting
  guide, stage documentation, and integration contracts.
 Structural parity does not require placeholder documents, removal of useful
 Narratio-specific material, or identical prose where the applications have
 different contracts.
 ## Policy Alignment
 ### Documentation Policy
 The documentation policy should follow the current Notarius policy, adapted to
 Narratio. It should:
 - define one canonical owner for every contract or authoritative fact;
 - identify volatile details that must not be maintained in multiple places;
 - permit non-owning documents to provide only short, stable summaries with
  links;
 - describe implemented behavior only outside `docs/roadmap/`;
 - allow accepted ADRs to precede implementation without presenting the
  decision as implemented behavior;
 - distinguish user, operator, contributor, integration, and internal detail;
 - require complete copyable files to live under `examples/`;
 - define documentation security and privacy requirements;
 - specify ownership boundaries for orientation, CLI, configuration,
  operations, troubleshooting, integrations, architecture, and internals;
 - define the ADR format and supersession rules; and
 - require contract, example, link, and sensitive-data checks when behavior or
  documentation changes.
 ### Architecture Policy
 The architecture policy should remain the normative owner of Narratio's system
 boundaries and invariants rather than a concrete package inventory or secondary
 testing and documentation policy. It should:
 - preserve Narratio's explicit, stage-driven orchestration model;
 - preserve adapter, manifest, artifact, path-safety, publish-commit, security,
  privacy, and determinism invariants;
 - link to the testing and documentation policies for their general rules;
 - link to internal documentation for implemented component mechanics;
 - link to external contracts rather than redefining them; and
 - use the canonical `docs/policy/` paths consistently.
 ### Testing Policy
 The copied Notarius testing policy is Narratio's canonical testing policy. Its
 place in the documentation set requires:
 - linking it from architecture and contributor guidance;
 - removing or reducing duplicated general test philosophy elsewhere;
 - retaining subsystem-specific test guidance only where it helps maintain a
  concrete contract; and
 - ensuring project commands and examples remain accurate for Narratio.
 The alignment should not require Narratio and Notarius to have identical test
 suites. The shared policy governs how Narratio evaluates test value,
 boundaries, doubles, regression protection, coverage, and sufficiency.
 ### Contributor Policy
 The development document should be a concise contributor entry point. It should
 route maintainers and coding agents to canonical documentation based on the
 task at hand and provide the minimum repository orientation and validation
 commands needed to begin work.
 Detailed package inventories belong in `docs/internal/overview.md`;
 architecture rules belong in the architecture policy; application contracts
 belong in their user, operator, or integration documents; and general testing
 rules belong in the testing policy. Any retained change recipes should avoid
 redefining those owners.
 ## Documentation Set Alignment
 ### README And Navigation
 Keep the README short and outward-facing. It should own product orientation and
 one minimal successful workflow, then link to the CLI, configuration,
 operations, troubleshooting, contributor, architecture, testing, integration,
 and internal entry points as appropriate.
 Navigation should use the final canonical paths and should not rely on obsolete
 aliases or duplicate index files.
 ### CLI, Configuration, And Operations
 Separate these contracts consistently:
 - CLI documentation answers how Narratio is invoked and what its command-line
  interface means;
 - configuration documentation answers how configuration is discovered,
  interpreted, defaulted, overridden, and validated; and
 - operations documentation answers what happens to runtime state and how an
  operator runs, resumes, cleans, diagnoses, or recovers the application.
 Cross-cutting workflows should have one task-oriented owner and link to the
 other contracts rather than copying their flags, fields, defaults, or path
 definitions.
 ### Troubleshooting
 Keep troubleshooting as a Narratio-specific canonical document. Each entry
 should begin from an observable symptom and provide a likely cause, a safe
 diagnostic step, a safe remedy, and links to the canonical contract or
 operational procedure.
 Troubleshooting should not become a second CLI, configuration, or operations
 reference.
 ### Integrations
 Integration documents should own the externally observable contracts Narratio
 uses: subprocess behavior, file formats, protocols, logical artifact paths and
 schemas, compatibility expectations, and upstream or downstream
 responsibilities.
 They should describe only the portions of WhisperX, Seriatim, Audita,
 Scriptorium, object storage, or future integrations that Narratio actually
 depends on. Internal adapter mechanics belong under `docs/internal/`, while
 configuration defaults, CLI syntax, and physical runtime placement remain with
 their respective owners.
 ### Internal Documentation
 `docs/internal/overview.md` is the canonical implemented component inventory. It
 should summarize current components and route readers to focused documents
 without restating normative architecture.
 Focused internal documents should describe implemented behavior at useful
 component boundaries, including collaborators, data and state transitions,
 failures, and tests worth consulting. They may identify an external field,
 file, or protocol when explaining a dependency, but should link to the
 canonical contract for its definition.
 The internal set should be reviewed for duplicate definitions of:
 - stage order and stage contracts;
 - manifest states and transitions;
 - artifact identities, paths, and schemas;
 - workspace and object-storage layout;
 - restore, resume, cleanup, and publish behavior;
 - adapter invocation and compatibility rules; and
 - configuration fields and defaults.
 ### Examples
 Complete copyable configuration and input files should remain under
 `examples/`. Documentation may include small illustrative fragments, but it
 should link to maintained examples instead of embedding alternate complete
 files.
 Examples should remain secret-free, loadable, valid, and covered by automated
 tests where practical. Their commands, filenames, fields, defaults, and
 templates must agree with implemented Narratio behavior.
 ### Roadmaps And ADRs
 Roadmaps should own future work, implementation status, and sequencing. They
 must not be treated as current behavior references. When roadmap work lands,
 the relevant current-behavior documents should be updated in the same change,
 and the roadmap status should accurately reflect completion.
 Use ADRs for significant architectural decisions whose context, alternatives,
 and consequences should remain durable. Use the lightweight Nygard structure:
 title, status, date, context, decision, alternatives considered, and
 consequences. Accepted decision content is immutable; a later change should
 supersede it with a new ADR. Rejected architectural alternatives belong in the
 ADR, while rejected product ideas remain roadmap material.
 No empty `docs/adr/` directory or retrospective ADR catalog is required merely
 to satisfy structural parity.
 ## Canonical-Ownership Audit
 The existing documentation should be audited for repeated authoritative facts,
 with priority given to details most likely to drift:
 - commands, arguments, flags, output conventions, and exit behavior;
 - configuration discovery, fields, defaults, environment variables, and
  validation rules;
 - stage order, prerequisites, invalidation, skip, force, resume, and failure
  semantics;
 - manifest states, artifact identities, and publish commit behavior;
 - local workspace, cache, spool, log, report, and remote object paths;
 - integration arguments, formats, schemas, timeouts, and compatibility rules;
  and
 - security, credential, permission, and sensitive-artifact handling.
 For each repeated fact, choose the canonical owner defined by policy. Remove
 the duplicate definition or reduce it to the smallest stable summary needed
 for orientation, with a link to the owner.
 This audit should preserve useful task-oriented guidance. Canonical ownership
 means eliminating parallel contract definitions, not forcing readers to
 assemble every workflow from isolated reference fragments.
 ## Intended Final State
 When this roadmap is complete:
 - Narratio's documentation policy closely matches the current Notarius policy
  in principles, organization, terminology, and lifecycle rules;
 - every authoritative documentation topic has one stated canonical owner;
 - `docs/internal/overview.md` is the internal component index and no references
  to `docs/internal/README.md` remain;
 - all policy and navigation links use real canonical paths;
 - architecture, documentation, testing, and contributor policies have distinct
  responsibilities and link to one another;
 - current-behavior documentation contains no unimplemented claims;
 - roadmap documents clearly own future behavior and implementation status;
 - user and operator documents avoid unnecessary implementation detail;
 - internal documents do not redefine external or user-facing contracts;
 - volatile commands, fields, defaults, schemas, paths, and guarantees are not
  maintained authoritatively in multiple places;
 - complete examples live under `examples/` and remain valid and secret-free;
 - the documentation remains concise enough to navigate but complete enough for
  users, operators, developers, integrators, and coding agents; and
 - future behavior changes can identify the documentation that must change by
  consulting the ownership table.
 ## Validation
 Completion should include:
 - a repository-wide review of Markdown links and canonical paths;
 - verification of documented commands and flags against the CLI
  implementation;
 - verification of configuration fields, defaults, environment overrides, and
  validation rules against the configuration implementation;
 - verification of stage, manifest, artifact, restore, resume, cleanup, and
  publish claims against implemented behavior;
 - validation of maintained examples through existing runtime config paths and
  tests;
 - `go test ./...`;
 - confirmation that non-owning documents summarize and link rather than
  redefine volatile contracts;
 - confirmation that unimplemented behavior appears only under
  `docs/roadmap/`, subject to the accepted-ADR exception; and
 - a review for credentials, private campaign content, sensitive environment
  data, and private infrastructure details.
 If the repository has no automated Markdown link checker, validation should use
 a focused, reproducible scripted link check supplemented by manual review of
 directory links and anchors.
 ## Acceptance Criteria
 - `docs/policy/documentation.md` expresses the Narratio-adapted canonical
  ownership model and boundary rules from the current Notarius policy.
 - `docs/policy/architecture.md`, `docs/policy/testing.md`, and
  `docs/development.md` have clear, non-overlapping responsibilities.
 - `docs/policy/development.md` has moved to `docs/development.md`, with all
  inbound links updated.
 - `docs/internal/README.md` has been renamed to
  `docs/internal/overview.md`, with all inbound links updated.
 - README, CLI, configuration, operations, troubleshooting, integration,
  internal, roadmap, example, and ADR responsibilities match the ownership
  model.
 - No known obsolete documentation paths remain.
 - High-volatility contracts have one authoritative definition.
 - Current and future behavior are clearly separated.
 - Maintained examples and documented commands agree with the implementation.
 - Documentation validation and the full Go test suite pass, or any unrelated
  pre-existing failure is recorded precisely.
 ## Non-Goals
 - Changing Narratio runtime behavior solely to make existing documentation
  true.
 - Implementing features described by other roadmap documents.
 - Rewriting every document for stylistic uniformity when its ownership and
  content are already correct.
 - Copying Notarius product, CLI, configuration, integration, or internal
  contracts into Narratio.
 - Creating placeholder API, consumer, ADR, or integration documents for
  interfaces that do not exist.
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,544 +0,0 @@
 # Documentation Policy And Structure Implementation Plan
 ## Status
 Completed.
 ## Objective
 Implement the target documentation model defined in
 [Documentation Policy And Structure Alignment](documentation.md). This is a
 documentation-only effort: do not change Go code, runtime behavior,
 configuration schemas, generated assets, or application features while
 following this plan.
 Complete the stages below in order. Treat each stage as an independently
 reviewable change boundary and run its stated checks before proceeding. Preserve
 the technical intent of the feature roadmap and the existing current-behavior
 documentation unless repository evidence shows that it is stale.
 ## Governing Decisions
 - Use `../notarius/docs/policy/documentation.md` as the structural and policy
  baseline for Narratio's documentation policy, adapting project names,
  canonical paths, and Narratio-specific document types.
 - Keep architecture, documentation, and testing under `docs/policy/`.
 - Move contributor orientation from `docs/policy/development.md` to
  `docs/development.md`.
 - Rename `docs/internal/README.md` to `docs/internal/overview.md`.
 - Replace the root `AGENTS.md` with the exact two-line content specified in
  Stage 4.
 - Keep `docs/troubleshooting.md` as a Narratio-specific canonical owner even
  though the current Notarius ownership table has no corresponding row.
 - Add `docs/integrations/whisperx.md`; WhisperX is an implemented external HTTP
  boundary and is the only current first-class integration missing a focused
  integration contract.
 - Keep directory index filenames not otherwise selected by this plan unchanged.
  In particular, do not rename `docs/integrations/README.md`.
 - Do not create `docs/adr/` until Narratio has an ADR to record. Do not create
  placeholder API or consumer documentation.
 - Do not copy Notarius product or runtime contracts. Use Notarius only as the
  policy and information-architecture model.
 - Outside `docs/roadmap/`, describe implemented behavior only. Roadmaps may
  describe proposed behavior but must not be cited as current contracts.
 - When documentation and implementation disagree, inspect the implementation
  and tests and make current-behavior documentation accurate. Do not alter code
  in this effort. Record a genuine runtime defect or unresolved ambiguity for
  separate work rather than silently documenting desired behavior as current.
 - Do not add a documentation tool dependency solely for this migration. Use
  repository scripts only if they already exist; otherwise use the validation
  procedure in Stage 8.
 ## Stage 1: Replace The Documentation Policy
 ### Goal
 Make `docs/policy/documentation.md` the authoritative Narratio documentation
 ownership and lifecycle policy before changing the rest of the documentation.
 ### Work
 1. Read the complete current files:
   - `../notarius/docs/policy/documentation.md`;
   - `docs/roadmap/documentation.md`;
   - `docs/policy/documentation.md`; and
   - the current Narratio documentation tree.
 2. Replace `docs/policy/documentation.md` with a Narratio-adapted version of the
   current Notarius policy. Preserve the Notarius section model:
   - Purpose;
   - Core Rules;
   - Canonical Ownership;
   - Boundary Rules;
   - Architecture Decision Records; and
   - Maintenance.
 3. Make these Narratio-specific adaptations:
   - use Narratio rather than Notarius throughout;
   - set the contributor owner to `docs/development.md`;
   - set architecture, documentation, and testing owners to their files under
     `docs/policy/`;
   - set the implemented component inventory to
     `docs/internal/overview.md`;
   - retain the Notarius conditional rows for public HTTP and consumer
     documentation;
   - add a troubleshooting row assigning symptom-driven diagnosis and safe
     remedies to `docs/troubleshooting.md` while keeping commands,
     configuration, and operational procedures with their existing owners;
   - retain `docs/integrations/` as the owner of external and durable contracts;
     and
   - retain the rule that nonexistent interface-specific documents are not
     required until the interface exists.
 4. In the boundary rules, explicitly separate:
   - README orientation, contributor routing, normative architecture, and the
     implemented internal inventory;
   - CLI invocation, configuration meaning, operations, and troubleshooting;
   - integration contracts and internal implementation; and
   - documentation security rules, application security invariants,
     credential-supply mechanisms, operational handling, and internal
     mechanisms.
 5. Preserve the lightweight Nygard ADR format and supersession rules from the
   Notarius policy. Do not create an ADR directory in this stage.
 6. Remove the old documentation profiles, prescribed per-document outlines,
   and obsolete paths rather than appending the new policy beneath them.
 ### Checks
 - Search the finished policy for `Notarius`, `docs/architecture.md`,
  `docs/policy/development.md`, and `docs/internal/README.md`; none should
  remain.
 - Confirm every canonical owner in the feature roadmap appears consistently in
  the policy.
 - Run `git diff --check -- docs/policy/documentation.md`.
 ### Completion Criteria
 - The policy closely follows the current Notarius policy while expressing the
  Narratio-specific ownership model.
 - It describes target canonical paths even when a later stage will perform the
  physical rename.
 - It contains no implementation sequence or future runtime claim.
 ## Stage 2: Refocus The Architecture Policy
 ### Goal
 Make `docs/policy/architecture.md` the concise normative owner of Narratio's
 current system shape, dependency boundaries, invariants, safety properties,
 and non-goals.
 ### Work
 1. Review the current architecture policy, the feature roadmap, the new
   documentation policy, `../notarius/docs/policy/architecture.md`, and the
   current internal overview and focused internal documents.
 2. Rewrite or reorganize `docs/policy/architecture.md` using the Notarius
   architecture policy as a style and ownership reference, not as a source of
   Narratio runtime facts.
 3. Preserve and clearly state Narratio's existing normative decisions:
   - a small, explicit, stage-driven orchestrator rather than a generic DAG or
     workflow engine;
   - Narratio ownership of orchestration, configuration resolution, run and
     session state, artifact and path modeling, manifests, resume, and publish;
   - isolation of WhisperX, Seriatim, Audita, Scriptorium, notification, and
     object-storage details behind adapters;
   - strict, centralized configuration and narrow templating;
   - centralized local and remote path construction and confined writes;
   - manifest-driven stage progress and transactional stage completion;
   - the remote publish commit boundary in which `current/run_id.txt` is
     written last;
   - private campaign-data and secret-handling invariants;
   - deterministic ordering and repeatable orchestration where practical; and
   - the existing architectural non-goals.
 4. Keep package names and concrete component inventories out of architecture
   except where a name is essential to express a boundary. Route concrete
   ownership to `../internal/overview.md` and focused internal docs.
 5. Replace the general testing inventory with a short architectural testing
   expectation and a link to `testing.md`. Package- or subsystem-specific test
   details belong in internal docs when useful.
 6. Replace documentation-rule duplication with a short requirement and a link
   to `documentation.md`.
 7. Link operational layout and lifecycle statements to `../operations.md` and
   external contract statements to `../integrations/` where useful. Do not
   duplicate their complete contracts.
 8. Remove all obsolete references, especially
   `docs/documentation/policy.md` and `docs/architecture.md`.
 9. Do not invent ADR links. Mention `docs/adr/` only as the future home of
   significant decision history.
 ### Checks
 - Search the file for `docs/documentation/policy.md`, `docs/architecture.md`,
  and `docs/internal/README.md`; none should remain.
 - Confirm links resolve relative to `docs/policy/`.
 - Compare every retained invariant with the existing architecture policy and
  relevant current internal documentation; no invariant may be weakened by
  omission merely to shorten the document.
 - Run `git diff --check -- docs/policy/architecture.md`.
 ### Completion Criteria
 - Architecture owns normative system rules but not the package inventory,
  general testing policy, documentation policy, CLI reference, configuration
  reference, or operational procedures.
 - Existing Narratio safety and publish invariants remain explicit.
 ## Stage 3: Move And Rewrite The Contributor Guide
 ### Goal
 Create the canonical first-read contributor landing page at
 `docs/development.md` and remove its obsolete policy location.
 ### Work
 1. Move `docs/policy/development.md` to `docs/development.md` using a normal
   repository rename so history remains recognizable.
 2. Rewrite it as a concise, table-of-contents-adjacent landing page modeled on
   `../notarius/docs/development.md`, adapted entirely to Narratio.
 3. Begin with a short orientation stating that Narratio is a stage-driven Go
   orchestrator and route readers to:
   - `README.md` for product context;
   - `policy/architecture.md` for normative system boundaries; and
   - `internal/overview.md` for implemented component ownership.
 4. Add a `What To Read` table with task-specific routes for at least:
   - locating current component ownership;
   - architecture, boundaries, invariants, or safety changes;
   - documentation changes;
   - adding, reviewing, rewriting, or deleting tests;
   - CLI behavior;
   - configuration loading or user-visible configuration;
   - session workflow, restore, status, cleanup, and object storage;
   - stage behavior and pipeline sequencing;
   - adapters and external contracts;
   - manifests, artifacts, workspace paths, and publish behavior;
   - examples; and
   - proposed or unimplemented behavior.
 5. For each row, link both the internal implementation guide and public or
   external contract when those have distinct ownership. Do not restate their
   rules in the table.
 6. End with concise validation guidance:
   - use focused package tests while iterating;
   - run `go test ./...`;
   - run `go vet ./...`; and
   - run `go build ./cmd/narratio` for repository-wide changes.
 7. Remove the old repository-layout inventory, detailed change playbooks,
   dependency policy, and duplicated coding conventions. Route those topics to
   architecture, internal documentation, public contracts, examples, and the
   testing or documentation policy instead.
 8. Update direct references to the contributor guide in files already changed
   in Stages 1 and 2 if any transitional link remains. Broader navigation is
   handled in Stage 5.
 ### Checks
 - Confirm `docs/development.md` exists and
  `docs/policy/development.md` does not.
 - Confirm all links in the new file resolve relative to `docs/`.
 - Confirm the guide contains no package inventory or second definition of a
  public contract.
 - Run `git diff --check -- docs/development.md`.
 ### Completion Criteria
 - A new maintainer or coding agent can choose the correct canonical reading
  path from one short document.
 - The contributor guide is navigational rather than a fourth normative policy.
 ## Stage 4: Replace The Repository Agent Instruction
 ### Goal
 Make `AGENTS.md` a stable pointer to the task-specific contributor guide.
 ### Work
 Replace the entire root `AGENTS.md` contents with exactly these two lines,
 including the line break and final period:
 ```text
 Please review `docs/development.md` for initial orientation in this repository
 and follow its task-specific reading guide.
 ```
 Do not retain the previous instruction, add headings, add generated markers, or
 append repository policy details.
 ### Checks
 - Run `git diff --check -- AGENTS.md`.
 - Verify exact content with:
  ```sh
  diff -u <(printf '%s\n' 'Please review `docs/development.md` for initial orientation in this repository' 'and follow its task-specific reading guide.') AGENTS.md
  ```
 ### Completion Criteria
 - The comparison is empty and `AGENTS.md` contains no other text.
 ## Stage 5: Align Structural Entry Points And Navigation
 ### Goal
 Complete the selected structural parity changes and make every primary entry
 point use the new canonical paths.
 ### Work
 1. Rename `docs/internal/README.md` to `docs/internal/overview.md`.
 2. Refocus the renamed file as the implemented component inventory:
   - state its boundary against architecture and public/operator contracts;
   - show the high-level execution path from `cmd/narratio` through
     `internal/app`, configuration and composition, stages and adapters,
     manifests and artifacts, and durable outputs;
   - provide a compact component table for the executable, app orchestration,
     configuration, stages, adapters, manifests, artifacts/path safety,
     previous-session cache, logging, and artifact policy; and
   - retain links to every focused internal document.
 3. Keep the canonical stage order in the internal overview only as an
   implemented inventory summary. Link to stage documents for mechanics and to
   CLI/operations for user-visible execution semantics.
 4. Update `README.md` while keeping it short:
   - preserve Narratio's product description and minimal successful command;
   - link to `docs/development.md` and `docs/internal/overview.md`;
   - include the documentation, architecture, and testing policies in a
     maintainer-oriented portion of the link list without turning the README
     into contributor guidance; and
   - retain user links to CLI, configuration, operations, troubleshooting,
     integrations, and examples.
 5. Update all references throughout `README.md`, `docs/`, and roadmap files from
   `docs/policy/development.md` to `docs/development.md`, and from
   `docs/internal/README.md` to `docs/internal/overview.md`. Fix relative links
   according to the referencing file's directory rather than performing a
   blind textual replacement.
 6. Correct other obsolete structural references already known in
   `docs/roadmap/notarius-extract-stage.md`, including `docs/architecture.md`,
   so it points to `docs/policy/architecture.md` and the now-existing
   `docs/development.md`. Do not change that roadmap's feature design or claim
   that extraction is implemented.
 7. Keep `docs/integrations/README.md` as the integrations index for now; update
   its links and ownership language as necessary, but do not rename it.
 ### Checks
 - Search the repository documentation, excluding this implementation plan and
  its feature roadmap, for `docs/policy/development.md`,
  `docs/internal/README.md`, `docs/architecture.md`, and
  `docs/documentation/policy.md`; none should remain. The two planning documents
  may name old paths when specifying the required migrations.
 - Confirm `README.md`, `docs/development.md`, and
  `docs/internal/overview.md` form a coherent orientation chain.
 - Run `git diff --check` for all changed Markdown files.
 ### Completion Criteria
 - The physical file layout matches the canonical ownership table.
 - All primary entry points and known inbound links use the new locations.
 - No compatibility stub is left at either old path.
 ## Stage 6: Audit User, Operator, And Integration Contracts
 ### Goal
 Give volatile public and external facts one canonical owner while preserving
 useful task-oriented guidance.
 ### Work
 1. Review `docs/cli.md`, `docs/config.md`, `docs/operations.md`,
   `docs/troubleshooting.md`, every file under `docs/integrations/`, maintained
   examples, and the corresponding Go implementations and tests.
 2. For code discovery, follow repository instructions: use the codebase
   knowledge graph first, then use text search for literal commands, fields,
   defaults, paths, messages, Markdown, YAML, and other non-code content.
 3. Make ownership conform to policy:
   - CLI owns commands, arguments, flags, invocation semantics, output
     conventions, and exits;
   - configuration owns discovery, precedence, fields, defaults, environment
     overrides, and validation;
   - operations owns runtime workflows, physical local and remote layout,
     resume, cleanup, permissions, recovery, and operational limits;
   - troubleshooting owns symptom-led diagnosis and safe fixes, linking rather
     than redefining other contracts; and
   - integrations own external protocols, file formats, request/result shapes,
     logical durable outputs, and compatibility behavior.
 4. Preserve concise cross-cutting workflows in the document whose audience
   owns the task. Replace repeated volatile definitions with stable summaries
   and direct links.
 5. Create `docs/integrations/whisperx.md`. Derive its current contract from
   `internal/adapters/whisperx`, `internal/stage/transcribe.go`, configuration,
   and tests. Cover only:
   - Narratio's purpose for the integration;
   - the HTTP adapter boundary;
   - request and response expectations;
   - retry, timeout, cancellation, validation, and failure semantics;
   - deterministic or concurrency behavior that is externally relevant; and
   - links to configuration for operator-selected values and to internal docs
     for implementation mechanics.
   Do not duplicate the configuration field table or physical workspace paths.
 6. Add WhisperX to `docs/integrations/README.md` and correct the index's
   description: integration contracts are externally observable boundaries,
   not merely implementation-level references.
 7. Review the Audita, Scriptorium, and Seriatim documents for the same boundary.
   Keep their protocol and data contracts; move or replace configuration field
   definitions and internal runner wiring with links when duplicated.
 8. Verify every documented command, flag, field, default, environment
   override, exit behavior, path, and integration guarantee against code or a
   focused test. If a current fact cannot be verified, remove unsupported
   specificity or record the issue for separate follow-up.
 ### Checks
 - Compare CLI command and flag inventories with `internal/app` command parsing
  and its tests.
 - Compare configuration tables with `internal/config` structs, defaults,
  normalization, loading, validation, and tests.
 - Compare operational path and lifecycle claims with `internal/artifacts`,
  `internal/manifest`, `internal/app`, `internal/stage`, and their tests.
 - Compare each integration contract with its adapter and stage boundary tests.
 - Confirm troubleshooting entries use symptom, likely cause, diagnostic step,
  safe fix, and relevant links.
 - Run focused tests only when needed to verify a disputed contract; no code
  changes are authorized.
 - Run `git diff --check` for changed documentation.
 ### Completion Criteria
 - Each volatile user, operator, and integration fact has one authoritative
  definition.
 - The new WhisperX contract is discoverable and implementation-accurate.
 - Task-oriented workflows remain usable without maintaining parallel reference
  tables.
 ## Stage 7: Audit Internal Documentation And Examples
 ### Goal
 Make internal documents explain implementation without redefining architecture,
 public contracts, external contracts, or future work, and confirm maintained
 examples remain canonical.
 ### Work
 1. Review every focused file under `docs/internal/` against its current package
   implementation and focused tests.
 2. For each internal document, retain or establish:
   - purpose and implemented owner;
   - internal collaborators and execution flow;
   - inputs, outputs, and state transitions expressed at the internal boundary;
   - package-local guarantees, failures, and safety invariants;
   - links to relevant tests or test areas when they materially help a
     maintainer; and
   - links to public, operator, configuration, or integration contracts rather
     than duplicate definitions.
 3. Audit the highest-drift topics explicitly:
   - canonical stage order, prerequisites, invalidation, skip, force, resume,
     and failure behavior;
   - session and run manifest states and transitions;
   - artifact identities, resolution rules, checksums, and current-state
     pointers;
   - workspace, cache, spool, logs, reports, and object-storage keys;
   - restore discovery, planning, conflict handling, execution, and reporting;
   - publish upload ordering and commit semantics;
   - adapter composition and subprocess behavior; and
   - path confinement, deletion, and cleanup safety.
 4. Where the same internal fact appears in several focused documents, select
   the component that owns it and use links from consumers. Do not over-prune a
   short invariant when repeating it is necessary to prevent an unsafe local
   change; in that case, state the invariant briefly and link to its normative
   owner.
 5. Review all complete YAML and input artifacts under `examples/`:
   - keep complete copyable files there rather than in prose;
   - ensure documentation links to them rather than maintaining full duplicate
     examples;
   - confirm they contain no credentials or private campaign content; and
   - verify they load and validate through existing tests where such coverage
     already exists.
 6. Do not modify application code or invent new test infrastructure. A missing
   example test may be recorded for later code work; it is not in scope for
   this documentation-only implementation.
 ### Checks
 - Search internal docs for duplicated configuration field/default tables, CLI
  flag tables, complete external schemas, and physical operations procedures;
  replace inappropriate copies with links.
 - Compare the stage inventory in `docs/internal/overview.md` with the
  implemented stage registry.
 - Run the existing example/config validation tests identified in
  `docs/development.md` or the current test suite.
 - Run `git diff --check` for changed documentation and examples.
 ### Completion Criteria
 - Internal documentation is an accurate component-level implementation guide.
 - Architecture and public/external contracts remain authoritative at their
  respective boundaries.
 - Complete examples are centralized, valid, discoverable, and secret-free.
 ## Stage 8: Perform Repository-Wide Validation And Close The Roadmap
 ### Goal
 Verify the migrated documentation as a coherent whole and record completion
 only after every acceptance criterion is satisfied.
 ### Work
 1. Review `README.md`, `AGENTS.md`, `docs/development.md`, all policy files,
   all user/operator references, all integration and internal documents, all
   roadmaps, and all maintained examples as one navigation system.
 2. Search for obsolete paths and project-name leakage:
   ```sh
   rg -n 'docs/policy/development\.md|docs/internal/README\.md|docs/architecture\.md|docs/documentation/policy\.md' README.md AGENTS.md docs --glob '!docs/roadmap/implementation.md' --glob '!docs/roadmap/documentation.md'
   rg -n 'Notarius' README.md AGENTS.md docs --glob '!docs/roadmap/notarius-extract-stage.md'
   ```
   The first search must return no matches. Review every match from the second;
   Narratio may legitimately mention the Notarius product or integration, but
   copied Notarius policy language must not remain.
 3. Validate local Markdown file and directory links with a reproducible script
   that scans `README.md`, `AGENTS.md`, and `docs/**/*.md`, resolves relative
   targets from each source file, strips anchors and query fragments, ignores
   external URLs and pure anchors, and fails for missing local targets. Use an
   existing repository checker if present. Otherwise run a temporary script
   without adding it or a new dependency to the repository.
 4. Manually inspect anchor links and directory links because a basic local-path
   checker may not validate them fully.
 5. Check formatting and whitespace:
   ```sh
   git diff --check
   ```
 6. Run the complete existing validation suite:
   ```sh
   go test ./...
   go vet ./...
   go build ./cmd/narratio
   ```
 7. Review the feature roadmap acceptance criteria one by one. Confirm that:
   - canonical ownership is explicit and reflected by actual content;
   - current behavior and future roadmap work are separated;
   - examples and commands match implementation;
   - no sensitive data was introduced;
   - no obsolete path or compatibility stub remains; and
   - this effort changed documentation only.
 8. If all criteria and checks pass, change the status in
   `docs/roadmap/documentation.md` from `Proposed.` to `Completed.` and change
   this plan's status from `Proposed.` to `Completed.`. Do not mark either
   complete while required work or an unexplained validation failure remains.
 9. If a validation failure predates this work and is demonstrably unrelated,
   record the exact command, failure, and evidence in the implementation handoff
   rather than changing application code. Documentation-link or content failures
   introduced or exposed by this migration must be fixed before completion.
 ### Completion Criteria
 - All Stage 8 searches and documentation checks pass.
 - `go test ./...`, `go vet ./...`, and `go build ./cmd/narratio` pass, or a
  precisely evidenced unrelated pre-existing failure is reported.
 - Both roadmap documents are marked `Completed.` only after the intended final
  state is present.
 - The final handoff lists changed documents, validation commands and results,
  and any explicitly out-of-scope follow-up without claiming unperformed work.