From 54228055c84febfa355d63f771fd18fe5feda1e7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 23 May 2026 12:43:50 +0000 Subject: [PATCH] Audit Stage 1 documentation scope and fix broken references --- README.md | 4 +- docs/integrations/README.md | 2 +- docs/internal/README.md | 2 +- docs/roadmap/documentation-stage1-audit.md | 105 +++++++++++++++++++++ internal/app/commands_test.go | 2 +- internal/app/operator_helpers_test.go | 6 +- 6 files changed, 113 insertions(+), 8 deletions(-) create mode 100644 docs/roadmap/documentation-stage1-audit.md diff --git a/README.md b/README.md index 7c9a327..4bcc0d9 100644 --- a/README.md +++ b/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) -- [Architecture Principles](docs/architecture.md) +- [Development Guide](docs/policy/development.md) +- [Architecture Principles](docs/policy/architecture.md) - [Internal Component Contracts](docs/internal/README.md) - [Config Examples](examples/) diff --git a/docs/integrations/README.md b/docs/integrations/README.md index 3d1d4ab..ac3b456 100644 --- a/docs/integrations/README.md +++ b/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`. diff --git a/docs/internal/README.md b/docs/internal/README.md index 28bed9c..3c2f02b 100644 --- a/docs/internal/README.md +++ b/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`. diff --git a/docs/roadmap/documentation-stage1-audit.md b/docs/roadmap/documentation-stage1-audit.md new file mode 100644 index 0000000..343699f --- /dev/null +++ b/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. diff --git a/internal/app/commands_test.go b/internal/app/commands_test.go index 9dc210c..f74c333 100644 --- a/internal/app/commands_test.go +++ b/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()) } } diff --git a/internal/app/operator_helpers_test.go b/internal/app/operator_helpers_test.go index ca546b4..75b2e13 100644 --- a/internal/app/operator_helpers_test.go +++ b/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":[]}`)