From df58595d1eccb9163efa3a3a42870440df689073 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 22:02:07 +0000 Subject: [PATCH] Remove completed documentation alignment roadmaps --- docs/roadmap/documentation.md | 355 --------------------- docs/roadmap/implementation.md | 544 --------------------------------- 2 files changed, 899 deletions(-) delete mode 100644 docs/roadmap/documentation.md delete mode 100644 docs/roadmap/implementation.md diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md deleted file mode 100644 index 40da561..0000000 --- a/docs/roadmap/documentation.md +++ /dev/null @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 9926f79..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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.