diff --git a/audit/SKILL.md b/audit/SKILL.md index ad6cc44..d30873c 100644 --- a/audit/SKILL.md +++ b/audit/SKILL.md @@ -116,7 +116,7 @@ The orchestrator picks per item: | Field | Content | |-------|---------| | `drift_items` | prioritised list (path + 1-line justification) from architect | -| `regression_results` | per script: exit code + raw output | +| `regression_results` | per script: exit code + **raw output verbatim** (no rounding, no summarisation — the orchestrator second-guesses with the full numbers) | | `recommendation` | per-item: `fix` / `ratify` / `carry-on` | The orchestrator decides the per-item outcome; `audit` does diff --git a/audit/agents/bencher.md b/audit/agents/bencher.md index 78b110d..25b828b 100644 --- a/audit/agents/bencher.md +++ b/audit/agents/bencher.md @@ -68,19 +68,25 @@ NO POLICY VERDICTS. THE ORCHESTRATOR DECIDES; YOU SUPPLY EVIDENCE. ## Standard methodology Every measurement starts with a hypothesis stated as a -falsifiable claim, not a vague comparison. Examples (the -specific subject varies per project): +falsifiable claim, not a vague comparison. The subject +varies per project (allocator variants, query plans, +request handlers, parsing strategies, codec implementations, +cache layers, …); the *shape* of a useful hypothesis does +not: -- "Variant A's p99 per-operation latency is within 2× of - median under continuous pressure with a >100 MB working - set." -- "Optimisation X reduces total resource consumption by ≥80% - on the canonical fixture vs the same fixture without it." -- "Variant A allows running the long-form workload without - resource exhaustion; the unoptimised variant exhausts - before completion." -- "Variant A's overhead vs the raw-cost floor on the canonical - fixture is within ±15% of the recorded baseline." +- **Tail-latency under pressure:** "Subject A's p99 + per-operation latency is within 2× of its median under + continuous pressure with a >100 MB working set." +- **Count / volume reduction:** "Optimisation X reduces + total resource consumption by ≥80% on a workload that + exercises the optimised code path vs the same workload + bypassing it." +- **Scalability ceiling:** "Subject A successfully + processes a 10-million-element workload without resource + exhaustion; the unoptimised variant fails below 1 million." +- **Overhead vs floor:** "Subject A's overhead vs the + raw-cost floor on the canonical fixture is within ±15% of + the recorded baseline." Then design the workload to *exercise* the claim. Specifically: diff --git a/brainstorm/SKILL.md b/brainstorm/SKILL.md index 8146f88..975d935 100644 --- a/brainstorm/SKILL.md +++ b/brainstorm/SKILL.md @@ -259,16 +259,33 @@ Orchestrator interpretation: 1. Delete the just-written spec file from the working tree (`rm ` — a shell delete on the working tree, NOT `git rm`; the file was never committed). -2. Open a backlog issue (via the command configured under - `git.issue_tracker.list_cmd`'s sibling create command — - typically `tea issues create` for Gitea, `gh issue create` - for GitHub) pointing forward to a future re-brainstorm, - under the appropriate priority bucket. +2. Open a backlog issue (via the project's issue-tracker + create command — `tea issues create` for Gitea, + `gh issue create` for GitHub, analogous for Linear / + Jira / etc.) pointing forward to a future re-brainstorm. + Include in the issue: + + - **Title:** one-line identity of the deferred work + - **Label:** matching the project's vocabulary (often + `feature` / `bug` / `idea`; promote to `BLOCKER` if + the unratified mechanism is on a core-functionality + path) + - **Body:** short description, plus two structured + lines: + - `depends on: ` + - `context: ` + + If the deferred work is large enough to need its own + spec on resumption — multi-iteration scope, cross- + subsystem — file it as a **milestone container** + instead (Gitea milestones, GitHub milestones, Linear + projects, whatever the project's tracker calls a + long-running work scope), not as a single issue. 3. Tell the user the spec was retired and which backlog - issue was filed (include the issue number). No commit is - needed for the backlog entry — the issue tracker is the - live store. + entry was filed (include the issue or milestone number). + No commit is needed for the backlog entry — the issue + tracker is the live store. After the failure-mode procedure runs, the brainstorm session ENDS. There is no Step 8, no Step 9. The idea is diff --git a/implement/agents/implementer.md b/implement/agents/implementer.md index e0e6537..ee15b36 100644 --- a/implement/agents/implementer.md +++ b/implement/agents/implementer.md @@ -95,11 +95,29 @@ is yes — write the test. The binding architectural rules of the project are declared in `CLAUDE.md` and (if the project has one) the design -ledger at `paths.design_ledger`. Read them as part of the -standing reading list. Respect them in the diff. If the -task text appears to ask for something a binding rule -forbids, return `BLOCKED` with the contradiction named — do -not silently substitute. +ledger at `paths.design_ledger`. The specific rules are +project-specific, but they typically cover: + +- **Determinism contracts.** Canonical forms, sort orders, + hash schemes, anything where the project commits to a + fixed byte-level output. +- **Backend / foreign-function constraints.** Which library + calls are forbidden, which are required, which version + is pinned. +- **Schema / format versions.** What `v0` / `v1` shapes + are, what counts as a breaking change, what migration + notes a schema bump requires. +- **Memory / resource models.** Reference counting, + ownership, lifetime invariants, capacity bounds. +- **Effect / capability discipline.** What functions may + perform IO / network / unsafe, how effect annotations + flow. + +Read the project's rules as part of the standing reading +list. Respect them in the diff. If the task text appears +to ask for something a binding rule forbids, return +`BLOCKED` with the contradiction named — do not silently +substitute. ## The Process diff --git a/templates/CLAUDE.md.fragment b/templates/CLAUDE.md.fragment index 786bcfd..14f0b72 100644 --- a/templates/CLAUDE.md.fragment +++ b/templates/CLAUDE.md.fragment @@ -67,3 +67,22 @@ debug skill is mandatory for any observable misbehaviour (failing test, segfault, wrong stdout, panic). See the debug SKILL.md and debugger agent for the Iron Law and four-phase process. + +## Lockstep-invariant pairs (optional) + +Some projects have cross-file pairings where a change in one +location must be mirrored in another — a new arm in one +without the matching update in the other ships silently +broken. The `architect` agent walks these pairs during +audit drift review, and `plan-recon` consults this section +when computing the cross-references column of a file-map. + +Projects that have such pairings enumerate them as a table +in this section. Projects that don't, omit the section +entirely (both agents handle absence gracefully). + +Example shape: + +| Pair | Failure mode | +|------|--------------| +| `:` ↔ `:` | |