Consolidate documentation ownership
This commit is contained in:
@@ -1,130 +0,0 @@
|
||||
# Documentation Policy Migration
|
||||
|
||||
The documentation ownership policy has been revised to assign each topic to one
|
||||
canonical document. This roadmap organizes the likely migration work into three
|
||||
ordered passes.
|
||||
|
||||
This is a planning inventory, not a review of the current documents. Each item
|
||||
must be verified before content is moved, removed, or rewritten. Complete the
|
||||
passes in order so canonical content is established before non-owning copies are
|
||||
removed.
|
||||
|
||||
## Pass 1: User And Operator Contracts
|
||||
|
||||
Establish the canonical externally observable facts first. These documents will
|
||||
become the targets linked from developer and internal documentation in the next
|
||||
pass.
|
||||
|
||||
### Product And CLI
|
||||
|
||||
- Audit `README.md` so it owns product orientation and the single minimal
|
||||
end-to-end quickstart without becoming a command or configuration reference.
|
||||
- Audit `docs/cli.md` for material owned by the README, configuration reference,
|
||||
or operations guide.
|
||||
- Keep commands, arguments, flags, invocation semantics, and exit codes
|
||||
canonical in `docs/cli.md`.
|
||||
|
||||
### Configuration And Examples
|
||||
|
||||
- Audit `docs/config.md` for complete example files, CLI syntax, runtime state
|
||||
lifecycle, or implementation detail.
|
||||
- Keep fields, defaults, precedence, environment overrides, validation, and
|
||||
user-selectable module and validator keys canonical in `docs/config.md`.
|
||||
- Audit minimal and production-oriented configuration examples, moving complete
|
||||
copyable files under `examples/` and leaving only small illustrative fragments
|
||||
in reference documentation.
|
||||
- Inventory complete configuration, input, command, and output examples embedded
|
||||
in prose documents.
|
||||
- Select one maintained copy for each complete artifact under `examples/` where
|
||||
practical, and verify important examples through automated tests.
|
||||
|
||||
### Operations And Integrations
|
||||
|
||||
- Audit `docs/operations.md` for duplicated CLI syntax, configuration field
|
||||
definitions, logical output schemas, or implementation mechanics.
|
||||
- Keep runtime workflows, physical state, retention, recovery, permissions, and
|
||||
operational limits canonical in `docs/operations.md`.
|
||||
- Audit `docs/integrations/` so external formats, protocols, logical output
|
||||
paths, schemas, media types, and compatibility rules have one canonical home.
|
||||
- Separate logical output bundle contracts from physical runtime placement and
|
||||
lifecycle.
|
||||
|
||||
### Pass 1 Completion
|
||||
|
||||
- Confirm that README, CLI, configuration, operations, integrations, and
|
||||
examples have non-overlapping ownership.
|
||||
- Validate user-facing commands, fields, defaults, keys, schemas, paths, and
|
||||
maintained examples against implemented behavior.
|
||||
- Validate links among the user and operator documents.
|
||||
|
||||
## Pass 2: Developer And Internal Documentation
|
||||
|
||||
Use the canonical contracts established in Pass 1 to remove duplicated facts
|
||||
from contributor and implementation documentation.
|
||||
|
||||
### Orientation And Architecture
|
||||
|
||||
- Audit `docs/development.md` so it routes contributors without maintaining a
|
||||
parallel package inventory or architectural description.
|
||||
- Audit `docs/internal/overview.md` so it owns the implemented component map
|
||||
without restating normative architecture.
|
||||
- Audit `docs/policy/architecture.md` so it contains current normative
|
||||
architecture without implementation inventory, decision history, or future
|
||||
behavior.
|
||||
|
||||
### Internal Components
|
||||
|
||||
- Audit internal component documents for repeated configuration definitions,
|
||||
external input or output schemas, operator procedures, and global
|
||||
architectural invariants.
|
||||
- Replace duplicated external schemas or field definitions with links to the
|
||||
canonical configuration or integration contracts from Pass 1.
|
||||
- Keep implementation flow, internal collaborators, state transitions,
|
||||
package-local guarantees, failures, and relevant tests in focused internal
|
||||
documents.
|
||||
- Identify task-specific contributor recipes that need a focused internal home
|
||||
rather than the developer landing page.
|
||||
- Retain production module and validator implementation details in module
|
||||
internals while linking user-selectable keys to `docs/config.md`.
|
||||
|
||||
### Pass 2 Completion
|
||||
|
||||
- Confirm that development routes, architecture governs, internal overview
|
||||
inventories, and focused internal docs explain implementation.
|
||||
- Confirm that developer documents link to configuration, operations, and
|
||||
integration contracts rather than redefining them.
|
||||
- Validate developer-facing links and relevant focused tests.
|
||||
|
||||
## Pass 3: Lifecycle And Final Deduplication
|
||||
|
||||
Finish the migration by reconciling historical and future documentation, then
|
||||
perform a repository-wide ownership audit.
|
||||
|
||||
### ADR And Roadmap Lifecycle
|
||||
|
||||
- Audit roadmap files for implemented behavior or completed status summaries
|
||||
that should be removed or replaced with links to current canonical docs.
|
||||
- Ensure ADRs own architectural rationale and supersession history without
|
||||
becoming current behavior references or implementation trackers.
|
||||
- Ensure accepted but unimplemented ADR decisions link to roadmap-owned
|
||||
implementation status where appropriate.
|
||||
- Distinguish rejected architectural alternatives in ADRs from rejected product
|
||||
ideas in roadmap files.
|
||||
|
||||
### Repository-Wide Audit
|
||||
|
||||
- Inventory repeated commands, flags, defaults, module keys, validator keys,
|
||||
file names, paths, schemas, retry semantics, and runtime guarantees.
|
||||
- Assign each repeated fact to the canonical owner defined by the policy.
|
||||
- Replace non-owning copies with short summaries and links where navigation is
|
||||
useful.
|
||||
- Retain only minimal illustrative snippets in prose and link them to maintained
|
||||
examples.
|
||||
- Validate local links and remove references to deleted or relocated material.
|
||||
|
||||
### Pass 3 Completion
|
||||
|
||||
- Confirm that every contractual or volatile fact has one canonical owner.
|
||||
- Confirm that roadmap files contain future work and implementation status, ADRs
|
||||
contain decision rationale, and current docs contain implemented behavior.
|
||||
- Run final link, example, and documentation consistency checks.
|
||||
@@ -25,7 +25,7 @@ future work only.
|
||||
- Production LLM-backed validators when there is a concrete review policy that
|
||||
benefits from model judgment.
|
||||
- Validator diagnostics and timing summaries if operators need more detail than
|
||||
`manifest.json`, `rejected.json`, and `warnings.json` provide.
|
||||
the current [durable output bundle](../integrations/json-output.md) provides.
|
||||
- Media-type validators for non-JSON module outputs when such modules are
|
||||
introduced.
|
||||
- Validator compatibility metadata if real deployments need config-time
|
||||
@@ -42,8 +42,7 @@ future work only.
|
||||
- Optional generated example output fixtures with a regeneration procedure.
|
||||
- Additional diagnostics or reporting views if operator workflows need them.
|
||||
|
||||
## Non-Goals To Revisit Deliberately
|
||||
## Candidate Workspace Work
|
||||
|
||||
- A general workflow language.
|
||||
- Structural module selection through ad hoc run flags.
|
||||
- Storing secrets in config files, diagnostics, manifests, or examples.
|
||||
Workspace storage, cleanup, archival, and reuse candidates are tracked in the
|
||||
[Workspace Future Work](workspace.md) roadmap.
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
# Workspace Implementation Status
|
||||
|
||||
The workspace implementation described by this roadmap has landed. Current
|
||||
behavior is documented in the canonical current-behavior docs:
|
||||
|
||||
- [Configuration](../config.md)
|
||||
- [CLI Reference](../cli.md)
|
||||
- [Operations](../operations.md)
|
||||
- [Diagnostics Internals](../internal/diagnostics.md)
|
||||
- [Pipeline Internals](../internal/pipeline.md)
|
||||
|
||||
Implemented behavior includes:
|
||||
|
||||
- `workspace.directory` as the root for Notarius-owned local state;
|
||||
- workspace diagnostics under `<workspace.directory>/diagnostics/<run-id>/`;
|
||||
- compatibility for legacy `diagnostics.work_dir`, `diagnostics.retention`,
|
||||
`NOTARIUS_WORK_DIR`, and `NOTARIUS_DIAGNOSTICS_RETENTION`;
|
||||
- checkpoint writes under `<workspace.directory>/checkpoints/` when resume
|
||||
checkpointing is enabled;
|
||||
- explicit checkpoint reuse through `notarius run --resume`;
|
||||
- debug artifacts under `<workspace.directory>/debug/<run-id>/` when debug
|
||||
output is enabled;
|
||||
- independent resume and debug settings.
|
||||
|
||||
Deferred workspace ideas remain in [Workspace Roadmap](workspace.md).
|
||||
@@ -1,26 +1,14 @@
|
||||
# Workspace Roadmap Status
|
||||
# Workspace Future Work
|
||||
|
||||
The local workspace feature has been implemented. Current behavior is documented
|
||||
in [Configuration](../config.md), [CLI Reference](../cli.md),
|
||||
[Operations](../operations.md), and the relevant internal docs.
|
||||
Current workspace settings and operating behavior are documented in
|
||||
[Configuration](../config.md#workspace) and
|
||||
[Operations](../operations.md). This roadmap contains only candidate additions
|
||||
to that behavior.
|
||||
|
||||
The implemented workspace provides one configurable root for Notarius-owned
|
||||
local state:
|
||||
## Candidate Work
|
||||
|
||||
```text
|
||||
<workspace.directory>/
|
||||
diagnostics/
|
||||
checkpoints/
|
||||
debug/
|
||||
```
|
||||
|
||||
Implemented behavior includes workspace-backed diagnostics, checkpoint writing,
|
||||
explicit checkpoint reuse through `notarius run --resume`, workspace debug
|
||||
artifacts, safe workspace-relative writes, and compatibility for legacy
|
||||
diagnostics configuration.
|
||||
|
||||
## Deferred Work
|
||||
|
||||
Default-idempotent `run` behavior with a force override, remote workspace
|
||||
storage, workspace garbage collection, archival policy, and cross-machine resume
|
||||
remain deferred.
|
||||
- Default-idempotent run behavior with an explicit force override.
|
||||
- Remote workspace storage.
|
||||
- Workspace garbage collection.
|
||||
- Workspace archival policy.
|
||||
- Cross-machine checkpoint reuse.
|
||||
|
||||
Reference in New Issue
Block a user