238 lines
7.7 KiB
Markdown
238 lines
7.7 KiB
Markdown
# Roadmap: 1.0 Documentation Pass
|
|
|
|
Status: Planned
|
|
|
|
## Goal
|
|
|
|
Prepare Narratio documentation for a 1.0 release by reviewing and rewriting
|
|
every non-policy document under `docs/` against the implemented codebase.
|
|
|
|
The finished documentation set should be accurate, concise, complete for its
|
|
audience, and compliant with:
|
|
|
|
- `docs/policy/documentation.md`
|
|
- `docs/policy/architecture.md`
|
|
- `docs/policy/development.md`
|
|
|
|
Do not modify files under `docs/policy/` during this pass.
|
|
|
|
Current behavior belongs in canonical docs. Future, planned, aspirational, or
|
|
unimplemented behavior belongs only under `docs/roadmap/`.
|
|
|
|
## Scope
|
|
|
|
In scope:
|
|
|
|
- `docs/*.md`
|
|
- `docs/internal/*.md`
|
|
- `docs/integrations/*.md`
|
|
- `docs/roadmap/*.md`
|
|
- documentation references to files under `examples/`
|
|
- test expectation fixes when the documentation review exposes stale or
|
|
incorrect doc/example/path expectations
|
|
|
|
Out of scope:
|
|
|
|
- product/runtime code changes
|
|
- feature implementation
|
|
- edits under `docs/policy/`
|
|
- adding roadmap behavior to current-behavior docs before that behavior is
|
|
implemented
|
|
|
|
## Implementation Stages
|
|
|
|
### Stage 1: Inventory and Source-of-Truth Audit
|
|
|
|
Status: Planned
|
|
|
|
Create a file-by-file inventory of all non-policy docs before rewriting.
|
|
|
|
Implementation requirements:
|
|
|
|
- List every non-policy documentation file and assign its intended audience.
|
|
- Identify each document's canonical scope using `docs/policy/documentation.md`.
|
|
- Compare docs against the current code and tests, especially:
|
|
- `internal/app`
|
|
- `internal/config`
|
|
- `internal/stage`
|
|
- `internal/artifacts`
|
|
- `examples`
|
|
- relevant tests under `internal/**`
|
|
- Record stale terminology, broken links, stale example paths, duplicate
|
|
content, and roadmap-only behavior that leaked into current-behavior docs.
|
|
- Record stale test expectations related to docs, examples, paths, or command
|
|
text.
|
|
- Do not rewrite content in this stage except obvious broken links or test
|
|
corrections needed to make documentation validation meaningful.
|
|
|
|
Acceptance criteria:
|
|
|
|
- The rewrite has a concrete file inventory and source-of-truth map.
|
|
- The team knows which docs are canonical and which should link elsewhere.
|
|
- Known stale terms and broken references are identified before broad edits.
|
|
|
|
### Stage 2: User and Operator Docs
|
|
|
|
Status: Planned
|
|
|
|
Rewrite the user-facing and operator-facing docs first.
|
|
|
|
Implementation requirements:
|
|
|
|
- Rewrite these docs as fresh, concise current-behavior references:
|
|
- `README.md`, if present
|
|
- `docs/cli.md`
|
|
- `docs/config.md`
|
|
- `docs/operations.md`
|
|
- `docs/troubleshooting.md`
|
|
- Verify every command, flag, config field, discovery rule, path, and workflow
|
|
against implemented behavior.
|
|
- Cover implemented 1.0 behavior, including:
|
|
- campaign registry selection;
|
|
- concrete session loading and template-driven `session init`;
|
|
- session-oriented helper commands;
|
|
- clean, restore, analyze, and publish workflows;
|
|
- artifact selection behavior;
|
|
- locks and published output behavior;
|
|
- workspace, spool, and cache behavior;
|
|
- secrets loading and S3-backed operation.
|
|
- Keep examples short and link to maintained files under `examples/` instead
|
|
of duplicating large config blocks.
|
|
- Fix tests only when they assert stale doc paths, example paths, command
|
|
names, or current-behavior text.
|
|
|
|
Acceptance criteria:
|
|
|
|
- User/operator docs are task-oriented and match actual CLI/config behavior.
|
|
- Current-behavior docs do not depend on roadmaps for normal usage.
|
|
- No current-behavior doc describes unimplemented roadmap items.
|
|
|
|
### Stage 3: Internal Developer Docs
|
|
|
|
Status: Planned
|
|
|
|
Rewrite implemented internal component docs after public docs stabilize.
|
|
|
|
Implementation requirements:
|
|
|
|
- Rewrite:
|
|
- `docs/internal/README.md`
|
|
- `docs/internal/adapters.md`
|
|
- `docs/internal/artifacts.md`
|
|
- `docs/internal/command-restore.md`
|
|
- `docs/internal/manifest.md`
|
|
- `docs/internal/stage-*.md`
|
|
- `docs/internal/storage.md`
|
|
- `docs/internal/workspace.md`
|
|
- Verify stage docs against current stage names, stage ordering, manifest
|
|
records, declared inputs/outputs, adapters, path helpers, storage behavior,
|
|
publish/current-state behavior, restore behavior, cache behavior, and
|
|
workspace cleanup.
|
|
- Keep implementation details in `docs/internal/`, not in user-facing docs.
|
|
- Avoid turning internal docs into duplicate config or CLI references; link to
|
|
canonical docs when needed.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Internal docs are accurate enough for developers and LLM coding agents to
|
|
change the system safely.
|
|
- Stage and adapter boundaries match `docs/policy/architecture.md`.
|
|
- Manifest, path, storage, and publish invariants are explicit and current.
|
|
|
|
### Stage 4: Integrations and Examples
|
|
|
|
Status: Planned
|
|
|
|
Review integration docs and maintained examples after core docs are rewritten.
|
|
|
|
Implementation requirements:
|
|
|
|
- Rewrite:
|
|
- `docs/integrations/README.md`
|
|
- `docs/integrations/audita.md`
|
|
- `docs/integrations/scriptorium.md`
|
|
- `docs/integrations/seriatim.md`
|
|
- Verify integration docs against current adapter contracts and expected
|
|
downstream tool behavior.
|
|
- Confirm every referenced example file exists.
|
|
- Confirm examples match current schema and command usage.
|
|
- Run or rely on example validation tests.
|
|
- Fix tests when they reference moved, renamed, or intentionally retired
|
|
examples.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Integration docs describe only implemented adapter expectations.
|
|
- Maintained examples are valid, secret-free, and linked from canonical docs.
|
|
- Example validation tests reflect the documented example set.
|
|
|
|
### Stage 5: Roadmap Cleanup and Final Sweep
|
|
|
|
Status: Planned
|
|
|
|
Clean up roadmap state and run final documentation validation.
|
|
|
|
Implementation requirements:
|
|
|
|
- Review `docs/roadmap/**` for implemented items that should be marked
|
|
implemented, retired, or left planned.
|
|
- Keep historical and planned behavior in roadmaps only.
|
|
- Run final link/path/term sweeps.
|
|
- Run validation commands:
|
|
- `go test ./internal/config -run TestExamplesLoadAndValidate -v`
|
|
- `go test ./internal/app -run TestExecute -v`
|
|
- `go test ./...`
|
|
|
|
Acceptance criteria:
|
|
|
|
- All non-policy docs are current for the 1.0 release.
|
|
- Roadmaps do not serve as required user/operator documentation.
|
|
- Tests pass after allowed documentation-related test expectation fixes.
|
|
|
|
## Required Checks
|
|
|
|
Run searches for stale terminology and references during the pass.
|
|
|
|
Stale terminology:
|
|
|
|
- `archive`
|
|
- `promote`
|
|
- `promoted`
|
|
- `promote_artifacts`
|
|
- legacy campaign path/discovery language
|
|
- old transcript names and paths
|
|
- removed CLI commands or aliases
|
|
|
|
Broken or stale references:
|
|
|
|
- missing local doc links;
|
|
- stale `examples/` paths;
|
|
- stale internal doc filenames;
|
|
- references to `docs/policy/**` as editable targets;
|
|
- command examples that no longer match the CLI.
|
|
|
|
Policy checks:
|
|
|
|
- Current-behavior docs mention only implemented behavior.
|
|
- Planned behavior appears only under `docs/roadmap/`.
|
|
- Docs do not expose raw secrets or recommend storing secrets in config.
|
|
- Docs use canonical homes:
|
|
- `docs/config.md` for config schema;
|
|
- `docs/cli.md` for command syntax;
|
|
- `docs/operations.md` for operator workflows;
|
|
- `docs/troubleshooting.md` for failure diagnosis;
|
|
- `docs/internal/` for implementation contracts;
|
|
- `docs/integrations/` for downstream tool integration notes;
|
|
- `docs/roadmap/` for future work.
|
|
|
|
## Assumptions
|
|
|
|
- `docs/policy/**` is read-only for this documentation pass.
|
|
- This pass is for 1.0 release readiness, not feature implementation.
|
|
- Product and runtime code changes are out of scope.
|
|
- Test fixes are in scope when they correct stale documentation, example, path,
|
|
command, or current-behavior expectations uncovered during the review.
|
|
- Roadmap files may remain as planning and historical records.
|
|
- Current-behavior docs must be sufficient for normal use without requiring
|
|
readers to consult roadmaps.
|