Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ The agent-kit files are canonical. Edit these, never their generated copies unde
| `design/00-brief.md` | Product vision, scope, non-goals, MVP, and definition of done |
| `design/10-design.md` | Architecture plus observability, extensibility, replay, capture, client, and content-pack design |
| `design/20-contract.md` | Core and all kind contracts, including exact types and invariants |
| `design/30-slices.md` | The W-numbered vertical delivery ledger; W ids are retained because repository history already cites them |
| `design/30-slices.md` | The vertical delivery ledger in the kit's format: live `## S<n>` slices above `## Landed`, where all 125 W-numbered units are retired to one row each |
| `design/90-decisions.md` | Decision history, deferred items, and judgement calls to revisit |

Each file contains marked human-document blocks. `build/ConvertTo-HumanDocumentation.ps1`
Expand Down Expand Up @@ -93,7 +93,7 @@ they are outputs, not editing surfaces.
| `06-extensibility.md` | Where the engine can be extended: the **ports** a host supplies (`IdSource`, stores, `Emitter`, `Clock`, `ExperimentSource`), the two composition roots, and the rule that decides — *a host may supply anything that cannot change `serialize()` output*, which makes the determinism boundary the trust boundary. Kinds stay engine-owned per architecture N2 |
| `05-observability.md` | Logging and tracing as a **separate channel** from `StateChange`: the clock-free `EngineEvent`, the per-resolution emitter handle, sinks, and the boundary that stamps time and trace ids. The invariant is that dropping every event changes nothing |
| `MVP.md` | The smallest slice that proves the platform, + Definition of Done (finalized) |
| `TODO.md` | The MVP as ordered **units of work** (W0–W19), each with contract refs, dependencies, and done-criteria; the MVP boundary is marked |
| `TODO.md` | The delivery ledger: open items carried forward, and one Landed row per retired W unit with its pull requests and criteria range |
| `OPEN-QUESTIONS.md` | Living register of unknowns, gaps, deferred decisions. §1 is now a **decision log** — the eight MVP-blocking gaps are all resolved; start here for the reasoning behind a contract |

## The Code — `src/engine/`
Expand Down Expand Up @@ -331,8 +331,8 @@ Two distinctions that are easy to get wrong:

- **Non-goals are binding.** Anything listed as a non-goal in `01-vision.md` §5 is out of
scope even if it looks trivial, even if you are already touching that file.
- **One unit at a time.** Do not start W<n+1> because you noticed something while doing
W<n>. Write it to `90-decisions.md`'s open register instead.
- **One unit at a time.** Do not start S<n+1> because you noticed something while doing
S<n>. Write it to `90-decisions.md`'s open register instead.
- **No new dependencies** without a decision-log entry naming the alternatives rejected and
why.
- **No new public interfaces** that are not in `20-contract.md`. If you need one, stop and
Expand Down Expand Up @@ -388,8 +388,10 @@ separate `slice`, `check`, `pr`, `resolve`, `track`, `docs`, `hold` or `resume`.
`design/00-brief.md`, `10-design.md`, `20-contract.md`, `30-slices.md`, and `90-decisions.md`
are the canonical inputs. This repository extends the generic kit in two deliberate ways:

- Existing W identifiers remain the slice ids. Renumbering them to S would break plans, tests,
issues, changelog entries, and merged history without changing the work.
- W identifiers are history. Every W unit is retired to a row under `## Landed` with an
`<a id="w<n>">` anchor, so existing links still resolve; plans, tests, issues, changelog
entries and merged history keep citing them unchanged. New slices are `## S<n>`, numbered from
S121 so no S id is ever mistaken for a W id.
- The design and contract files contain marked, independently generated human pages. Commands
must read the complete canonical file, including every marked block relevant to the task.

Expand Down
2 changes: 1 addition & 1 deletion agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ README, whose status is deliberately coarse.

- **After a work-unit PR merges or the changelog gains an entry:** update the delivered count,
completed chapter grouping, current checkpoint, and evidence URL in `roadmapData.ts`. Count
`### [x] W…` headings in `design/30-slices.md`, then explicitly account for any merged
Landed rows in `design/30-slices.md` that are not cancelled, plus `Status: done` S slices, then explicitly account for any merged
units that the ledger has not yet recorded in the `completedBeyondTodo` exception list. Update
the page before describing the new unit as delivered anywhere public. Reconcile `README.md`'s
coarse status at the same time if it has become misleading, then regenerate
Expand Down
6 changes: 6 additions & 0 deletions build/Test-Documentation.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,12 @@ function Get-DocumentationAnchor {
$counts = @{}

foreach ($line in $masked) {
# An inline <a id="..."></a> is an anchor too: the retired-slice rows in
# design/30-slices.md carry one each, so links to #w<n> outlive the headings.
foreach ($inline in [regex]::Matches($line, '<a\s+id="([^"]+)"\s*>')) {
$null = $anchors.Add($inline.Groups[1].Value)
}

$match = [regex]::Match($line, '^\s{0,3}#{1,6}\s+(.+?)\s*$')
if (-not $match.Success) {
continue
Expand Down
Loading
Loading