narratio/docs/roadmap/documentation-stage1-audit.md

Documentation Pass: Stage 1 Audit

Status: Completed (2026-05-23)

Scope Reviewed

• All non-policy documentation files under docs/
• README.md
• Documentation references to maintained examples/ files
• Documentation-related expectations in tests under internal/**

File Inventory and Canonical Scope

File	Intended audience	Canonical scope (per policy)	Primary source-of-truth anchors
README.md	Users, operators	Project orientation and links	cmd/narratio, internal/app/commands.go, docs index files
docs/cli.md	Users, operators	CLI syntax, flags, command workflows	internal/app/*.go, internal/app/*_test.go
docs/config.md	Operators, advanced users	Config discovery, schema, defaults, examples	internal/config/*.go, internal/config/*_test.go, examples/*
docs/operations.md	Operators	Run/resume/publish/restore/cleanup workflows	internal/app/runner.go, internal/app/restore*.go, internal/stage/archive.go, internal/artifacts/*.go
docs/troubleshooting.md	Operators	Failure diagnosis and safe fixes	internal/app, internal/stage, related tests
docs/internal/README.md	Developers, LLM coding agents	Internal docs index and scope boundaries	docs/internal/*.md, policy docs
docs/internal/adapters.md	Developers, LLM coding agents	Adapter boundaries and ownership	internal/adapters/*, internal/stage/*
docs/internal/artifacts.md	Developers, LLM coding agents	Artifact catalog and source resolution contracts	internal/artifacts/*, internal/stage/analyze.go, internal/stage/prepare_previous.go
docs/internal/command-restore.md	Developers, LLM coding agents	Restore command architecture and contracts	internal/app/restore*.go, internal/app/restore*_test.go
docs/internal/manifest.md	Developers, LLM coding agents	Session/run manifest contracts and transitions	internal/manifest/*, internal/app/runner.go, internal/stage/*
docs/internal/stage-prepare.md	Developers, LLM coding agents	Prepare stage IO and invariants	internal/stage/prepare.go, internal/stage/prepare*_test.go
docs/internal/stage-transcribe.md	Developers, LLM coding agents	Transcribe stage IO and invariants	internal/stage/transcribe.go, internal/stage/transcribe_test.go
docs/internal/stage-merge.md	Developers, LLM coding agents	Merge stage IO and invariants	internal/stage/merge.go, internal/stage/merge_test.go
docs/internal/stage-polish.md	Developers, LLM coding agents	Polish stage IO and invariants	internal/stage/polish.go, internal/stage/polish_test.go
docs/internal/stage-normalize.md	Developers, LLM coding agents	Normalize stage IO and invariants	internal/stage/normalize.go, internal/stage/normalize_test.go
docs/internal/stage-trim.md	Developers, LLM coding agents	Trim stage IO and invariants	internal/stage/trim.go, internal/stage/trim_test.go
docs/internal/stage-analyze.md	Developers, LLM coding agents	Analyze stage artifact execution and selection	internal/stage/analyze.go, internal/stage/analyze_test.go
docs/internal/stage-publish.md	Developers, LLM coding agents	Publish-stage commit/upload invariants	internal/stage/archive.go, internal/stage/archive_test.go
docs/internal/storage.md	Developers, LLM coding agents	Storage adapter contracts and semantics	internal/adapters/storage/*, internal/app/object_store.go
docs/internal/workspace.md	Developers, LLM coding agents	Local workspace/session/run path model	internal/artifacts/*, internal/app/runner.go, internal/stage/run_local.go
docs/integrations/README.md	Developers, LLM coding agents	Integration docs index	docs/integrations/*.md
docs/integrations/audita.md	Developers, integration maintainers	Audita adapter contract	internal/adapters/audita/*, internal/stage/polish.go
docs/integrations/seriatim.md	Developers, integration maintainers	Seriatim adapter contract	internal/adapters/seriatim/*, internal/stage/merge.go, internal/stage/normalize.go, internal/stage/trim.go
docs/integrations/scriptorium.md	Developers, integration maintainers	Scriptorium adapter contract	internal/adapters/scriptorium/*, internal/stage/analyze.go, internal/stage/trim.go
docs/roadmap/documentation.md	Developers, maintainers	Planning and implementation sequencing for documentation pass	N/A (planning artifact)
docs/roadmap/documentation-stage1-audit.md	Developers, maintainers	Stage-1 inventory and source-of-truth audit record	N/A (planning artifact)

Source-of-Truth Mapping Summary

• CLI behaviors and command names are grounded in internal/app/commands.go and command handlers in internal/app/*.go.
• Stage order and canonical stage names are grounded in internal/stage/placeholders.go (prepare -> transcribe -> merge -> polish -> normalize -> trim -> analyze -> publish -> notify).
• Publish behavior and current-pointer commit semantics are grounded in internal/stage/archive.go.
• Config schema/defaults/validation are grounded in internal/config/*.
• Local/remote paths, publish keys, and workspace layout are grounded in internal/artifacts/*.
• Restore behavior and report contracts are grounded in internal/app/restore*.go.
• Maintained examples and schema compatibility are grounded in examples/* plus internal/config/load_validate_test.go (TestExamplesLoadAndValidate).

Findings

Broken or stale references

1. README.md linked to non-existent files:
   • docs/development.md
   • docs/architecture.md
2. docs/internal/README.md and docs/integrations/README.md linked to non-existent path:
   • docs/documentation/policy.md

Stage-1 fix applied:

• Updated those links to existing policy docs under docs/policy/.

Stale terminology sweep

Sweep terms used: archive, promote, promoted, promote_artifacts, run-stage archive.

Findings:

• User-facing docs in scope did not show obvious stale command examples requiring immediate correction.
• Internal code and tests still contain historical archive identifiers while user-facing command/stage naming is publish (for example, internal/stage/archive.go type names). This is acceptable for now but should be normalized deliberately, not incidentally.

Stage-1 fix applied:

• Updated clearly stale publish-related wording in test expectation messages/comments:
  • internal/app/commands_test.go
  • internal/app/operator_helpers_test.go

Example path validation

• All examples/... paths referenced from non-policy docs resolve to existing files.
• internal/config/load_validate_test.go includes TestExamplesLoadAndValidate and points to current example files.

Roadmap leakage into current-behavior docs

• No obvious roadmap-only behavior leakage found in non-roadmap docs during this sweep.

Duplicate content and scope drift

• No severe duplication requiring immediate rewrite in this stage.
• Existing docs still need full content rewrite for 1.0 readiness in later stages (user/operator first, then internal/integrations), as planned.

Canonical-home inconsistency to resolve in rewrite stages

• Policy canonical-home language names docs/architecture.md and docs/development.md, while current repository stores those policy documents under docs/policy/.
• Stage 1 preserves repository behavior by fixing broken links to existing files. Later rewrite stages should converge canonical-home paths and references consistently across docs.

Stage-1 Completion Check

Completed for this stage:

• Full non-policy file inventory with audience and scope mapping.
• Source-of-truth crosswalk to code/tests.
• Stale-term, link, and example-path sweeps.
• Documentation-related stale test wording corrections.
• Minimal fixes only; broad rewrites intentionally deferred.