|
|
|
|
@@ -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.
|
