next phase

This commit is contained in:
ari committed 2026-10-19 16:43:35 -04:00
1 parent 6387f4455b
commit 782e5dc440
14 files changed
+1280 -27

No files matched your search

+25 -7
View File
@@ -11,15 +11,33 @@ Where other things live:
| Long-form docs | [`../docs/`](../docs/README.md) |
| Records of finished workstreams | [`../docs/workstreams/`](../docs/workstreams/) |
## Phase folder layout
Each phase is a folder `plan/<short-name>/` (for example `plan/phase-5-consolidator/`) so workstreams can be worked in parallel by separate agents or people:
| File | Purpose |
|---|---|
| `README.md` | Phase overview: goal, scope, grounding in code, workstream index (ID, file, owner, depends on, can start when, owned files), dependency graph, parallel lanes, risks, verification, exit criteria |
| `contracts.md` | Shared interfaces (types, traits, fakes, REST/MCP/OTel shapes, config surface) that let streams start against fakes before their dependency lands |
| `decisions.md` | Open-decisions table and decision records |
| `ws-<x>-<name>.md` | One file per workstream: header table, goal, tasks, inputs, done when, handoff, log |
Rules:
- **Do not touch**: a workstream edits only the files in its "Owned files" row. Other streams' files are in its "Do not touch" row. For the few shared files (for example `src/state.rs`, `src/api/mod.rs`, `flake.nix`) the header names the integration seam and which stream edits it first; prefer one stream wiring the seam up front so the rest only fill their own files.
- **Contracts change only through `contracts.md`**: edit it first, then add a dated note to the Log of every affected workstream file.
- **Claim a workstream** by setting its `Owner` field (name or agent id) and committing that change before starting; set `Status` as you go. Do not start a stream whose "Can start when" is not met unless you work against the contracts and fakes.
- Log progress, discoveries and handoffs in the workstream's own `Log` (dated), not in other files.
## Proposing a phase plan
1. Copy [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>.md` (for example `plan/phase-5-alerting.md`).
2. Fill in:
1. Copy the folder layout from [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>/` (for example `plan/phase-5-alerting/`).
2. Fill in the phase `README.md`:
- **Goal**: what changes for users or operators, in a few sentences.
- **Scope**: what is in, and explicitly what is out.
- **Workstreams**: independent tracks with owned files, dependencies and done criteria, so they can run in parallel without merge conflicts.
- **Open decisions**: questions that need a human call, each with options and a recommendation.
- **Workstream index** and **parallel lanes**: independent tracks with owned files, dependencies and what can run from day one, so they run in parallel without merge conflicts.
- **Exit criteria**: how you will know the phase is done (commands to run, behaviour to demonstrate).
3. Review and settle the open decisions in the plan file.
4. When the plan is accepted, move the work into [`../TODO.md`](../TODO.md): add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
5. When the phase finishes, move the plan file (and any per-workstream notes) to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.
3. Write `contracts.md` for anything two streams share, and `decisions.md` for questions that need a human call, each with options and a recommendation. If a stream would block on another, add a small first task that lands the shared stubs (for example a fake).
4. Review and settle the open decisions in `decisions.md`.
5. When the plan is accepted, move the work into [`../TODO.md`](../TODO.md): add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
6. When the phase finishes, move the whole phase folder to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.