credential-supply mechanisms, operational handling, and internal
mechanisms.
5. Preserve the lightweight Nygard ADR format and supersession rules from the
Notarius policy. Do not create an ADR directory in this stage.
6. Remove the old documentation profiles, prescribed per-document outlines,
and obsolete paths rather than appending the new policy beneath them.
### Checks
- Search the finished policy for `Notarius`, `docs/architecture.md`,
`docs/policy/development.md`, and `docs/internal/README.md`; none should
remain.
- Confirm every canonical owner in the feature roadmap appears consistently in
the policy.
- Run `git diff --check -- docs/policy/documentation.md`.
### Completion Criteria
- The policy closely follows the current Notarius policy while expressing the
Narratio-specific ownership model.
- It describes target canonical paths even when a later stage will perform the
physical rename.
- It contains no implementation sequence or future runtime claim.
## Stage 2: Refocus The Architecture Policy
### Goal
Make `docs/policy/architecture.md` the concise normative owner of Narratio's
current system shape, dependency boundaries, invariants, safety properties,
and non-goals.
### Work
1. Review the current architecture policy, the feature roadmap, the new
documentation policy, `../notarius/docs/policy/architecture.md`, and the
current internal overview and focused internal documents.
2. Rewrite or reorganize `docs/policy/architecture.md` using the Notarius
architecture policy as a style and ownership reference, not as a source of
Narratio runtime facts.
3. Preserve and clearly state Narratio's existing normative decisions:
- a small, explicit, stage-driven orchestrator rather than a generic DAG or
workflow engine;
- Narratio ownership of orchestration, configuration resolution, run and
session state, artifact and path modeling, manifests, resume, and publish;
- isolation of WhisperX, Seriatim, Audita, Scriptorium, notification, and
object-storage details behind adapters;
- strict, centralized configuration and narrow templating;
- centralized local and remote path construction and confined writes;
- manifest-driven stage progress and transactional stage completion;
- the remote publish commit boundary in which `current/run_id.txt` is
written last;
- private campaign-data and secret-handling invariants;
- deterministic ordering and repeatable orchestration where practical; and
- the existing architectural non-goals.
4. Keep package names and concrete component inventories out of architecture
except where a name is essential to express a boundary. Route concrete
ownership to `../internal/overview.md` and focused internal docs.
5. Replace the general testing inventory with a short architectural testing
expectation and a link to `testing.md`. Package- or subsystem-specific test
details belong in internal docs when useful.
6. Replace documentation-rule duplication with a short requirement and a link
to `documentation.md`.
7. Link operational layout and lifecycle statements to `../operations.md` and
external contract statements to `../integrations/` where useful. Do not
duplicate their complete contracts.
8. Remove all obsolete references, especially
`docs/documentation/policy.md` and `docs/architecture.md`.
9. Do not invent ADR links. Mention `docs/adr/` only as the future home of
significant decision history.
### Checks
- Search the file for `docs/documentation/policy.md`, `docs/architecture.md`,
and `docs/internal/README.md`; none should remain.
- Confirm links resolve relative to `docs/policy/`.
- Compare every retained invariant with the existing architecture policy and
relevant current internal documentation; no invariant may be weakened by
omission merely to shorten the document.
- Run `git diff --check -- docs/policy/architecture.md`.
### Completion Criteria
- Architecture owns normative system rules but not the package inventory,
general testing policy, documentation policy, CLI reference, configuration
reference, or operational procedures.
- Existing Narratio safety and publish invariants remain explicit.
## Stage 3: Move And Rewrite The Contributor Guide
### Goal
Create the canonical first-read contributor landing page at
`docs/development.md` and remove its obsolete policy location.
### Work
1. Move `docs/policy/development.md` to `docs/development.md` using a normal
repository rename so history remains recognizable.
2. Rewrite it as a concise, table-of-contents-adjacent landing page modeled on
`../notarius/docs/development.md`, adapted entirely to Narratio.
3. Begin with a short orientation stating that Narratio is a stage-driven Go
orchestrator and route readers to:
-`README.md` for product context;
-`policy/architecture.md` for normative system boundaries; and
-`internal/overview.md` for implemented component ownership.
4. Add a `What To Read` table with task-specific routes for at least:
- locating current component ownership;
- architecture, boundaries, invariants, or safety changes;
- documentation changes;
- adding, reviewing, rewriting, or deleting tests;
- CLI behavior;
- configuration loading or user-visible configuration;
- session workflow, restore, status, cleanup, and object storage;
- stage behavior and pipeline sequencing;
- adapters and external contracts;
- manifests, artifacts, workspace paths, and publish behavior;
- examples; and
- proposed or unimplemented behavior.
5. For each row, link both the internal implementation guide and public or
external contract when those have distinct ownership. Do not restate their
rules in the table.
6. End with concise validation guidance:
- use focused package tests while iterating;
- run `go test ./...`;
- run `go vet ./...`; and
- run `go build ./cmd/narratio` for repository-wide changes.
7. Remove the old repository-layout inventory, detailed change playbooks,
dependency policy, and duplicated coding conventions. Route those topics to
architecture, internal documentation, public contracts, examples, and the
testing or documentation policy instead.
8. Update direct references to the contributor guide in files already changed
in Stages 1 and 2 if any transitional link remains. Broader navigation is
handled in Stage 5.
### Checks
- Confirm `docs/development.md` exists and
`docs/policy/development.md` does not.
- Confirm all links in the new file resolve relative to `docs/`.
- Confirm the guide contains no package inventory or second definition of a
public contract.
- Run `git diff --check -- docs/development.md`.
### Completion Criteria
- A new maintainer or coding agent can choose the correct canonical reading
path from one short document.
- The contributor guide is navigational rather than a fourth normative policy.
## Stage 4: Replace The Repository Agent Instruction
### Goal
Make `AGENTS.md` a stable pointer to the task-specific contributor guide.
### Work
Replace the entire root `AGENTS.md` contents with exactly these two lines,
including the line break and final period:
```text
Please review `docs/development.md` for initial orientation in this repository
and follow its task-specific reading guide.
```
Do not retain the previous instruction, add headings, add generated markers, or
append repository policy details.
### Checks
- Run `git diff --check -- AGENTS.md`.
- Verify exact content with:
```sh
diff -u <(printf '%s\n' 'Please review `docs/development.md` for initial orientation in this repository' 'and follow its task-specific reading guide.') AGENTS.md
```
### Completion Criteria
- The comparison is empty and `AGENTS.md` contains no other text.
## Stage 5: Align Structural Entry Points And Navigation
### Goal
Complete the selected structural parity changes and make every primary entry
point use the new canonical paths.
### Work
1. Rename `docs/internal/README.md` to `docs/internal/overview.md`.
2. Refocus the renamed file as the implemented component inventory:
- state its boundary against architecture and public/operator contracts;
- show the high-level execution path from `cmd/narratio` through
`internal/app`, configuration and composition, stages and adapters,
manifests and artifacts, and durable outputs;
- provide a compact component table for the executable, app orchestration,
