Audit Stage 1 documentation scope and fix broken references

README.md

@@ -16,7 +16,7 @@ This command requires discoverable `pipeline.yml` and `session.yml` files (or ex
 - [CLI Reference](docs/cli.md)
 - [Operations and Recovery](docs/operations.md)
 - [Troubleshooting](docs/troubleshooting.md)
-- [Development Guide](docs/development.md)
+- [Development Guide](docs/policy/development.md)
-- [Architecture Principles](docs/architecture.md)
+- [Architecture Principles](docs/policy/architecture.md)
 - [Internal Component Contracts](docs/internal/README.md)
 - [Config Examples](examples/)

docs/integrations/README.md

@@ -12,4 +12,4 @@ Implemented-only reference notes for the external systems Narratio currently int
 - `scriptorium.md`: Scriptorium run/render adapter contract.
 
 ## Canonical Owner
-`docs/integrations/` is the canonical home for external integration reference notes per `docs/documentation/policy.md`.
+`docs/integrations/` is the canonical home for external integration reference notes per `docs/policy/documentation.md`.

docs/internal/README.md

@@ -26,4 +26,4 @@ Implementation-accurate contracts for workspace/state, manifests, stages, artifa
 - `../integrations/README.md`: canonical location for external integration contracts (`audita.md`, `seriatim.md`, `scriptorium.md`).
 
 ## Canonical Owner
-`docs/internal/` is the canonical home for implemented internals per `docs/documentation/policy.md`.
+`docs/internal/` is the canonical home for implemented internals per `docs/policy/documentation.md`.

docs/roadmap/documentation-stage1-audit.md

@@ -0,0 +1,105 @@
+# 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.

internal/app/commands_test.go

@@ -119,7 +119,7 @@ func TestExecuteRunStageArchiveAliasFails(t *testing.T) {
 		t.Fatal("exit code = 0, want non-zero")
 	}
 	if !strings.Contains(stderr.String(), `unknown stage "archive"`) {
-		t.Fatalf("stderr = %q, want unknown archive stage error", stderr.String())
+		t.Fatalf("stderr = %q, want unknown stage alias error", stderr.String())
 	}
 }
 

internal/app/operator_helpers_test.go

@@ -851,13 +851,13 @@ func TestExecuteStatusReportsRemoteArtifactCatalogErrorsWithoutFailing(t *testin
 	}
 	out := stdout.String()
 	if !strings.Contains(out, "Remote publish: missing or unavailable:") {
-		t.Fatalf("stdout = %q, want remote archive unavailable state", out)
+		t.Fatalf("stdout = %q, want remote publish unavailable state", out)
 	}
 	if !strings.Contains(out, "Remote outputs:") || !strings.Contains(out, "narratio.transcript.final_trimmed remote=error") {
 		t.Fatalf("stdout = %q, want remote output error state", out)
 	}
 	if !strings.Contains(out, "Publish locks: error:") {
-		t.Fatalf("stdout = %q, want archive locks error", out)
+		t.Fatalf("stdout = %q, want publish locks error", out)
 	}
 }
 
@@ -872,7 +872,7 @@ func TestExecuteArchiveLoadsRemoteLocks(t *testing.T) {
 
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
 	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze"} {
-		// The archive stage only checks the manifest statuses and source files.
+		// The publish stage only checks the manifest statuses and source files.
 		_ = stageName
 	}
 	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "final.trimmed.json"), `{"segments":[]}`)