iter disc.1: boss-only commits + main-as-quarantine (no branches in implement)

Two project-wide rules are now explicit across every skill:

1. Only the Boss commits. No skill agent (implementer,
   brainstormer, planner, debugger, fieldtester, docwriter,
   architect, bencher) runs `git commit`. Agents write their
   artefacts to the working tree as unstaged changes; the Boss
   inspects, decides commit shape, and commits.
2. main HEAD is sacrosanct. No actor runs `git reset` or
   `git revert` on main. Bad work stays in the working tree
   where it is still discardable via `git checkout -- <paths>`.

Implement loses the `iter/<iter_id>` branch mechanic entirely;
Phase 0 of the orchestrator-agent now does a clean-tree check
and refuses to start on a dirty tree. Per-task agent commits
are removed everywhere; reviewers operate against
`git diff HEAD` instead of `pre_task_sha..head_sha`.

Motivation: 2026-05-11 iter 23.4 stranded prep2/prep3 commits on
an iter-branch that never integrated to main, then a corrected
spec falsely claimed those commits had shipped. Branch-per-iter
+ manual-Boss-merge + iter-stacking made the strand structurally
possible. See docs/journals/2026-05-11-iter-disc.1.md for the
full per-task notes and motivation.
This commit is contained in:
2026-05-11 22:44:43 +02:00
parent 841d65d88c
commit 51da9fab53
18 changed files with 552 additions and 248 deletions
+14 -6
View File
@@ -1,6 +1,6 @@
---
name: debug
description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic, or any observable misbehaviour. Bug fixes are RED-first TDD; no fix is attempted before the failing test is committed. Mandatory for any bug, including ones that look trivial.
description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic, or any observable misbehaviour. Bug fixes are RED-first TDD; no fix is attempted before the failing test exists in the working tree. Mandatory for any bug, including ones that look trivial.
---
# debug — RED-first bug diagnoser
@@ -57,10 +57,17 @@ Dispatch `ailang-debugger` with:
| `repro_known` | One-line repro if known, otherwise the agent finds one |
| `recent_iter` | Iteration that last touched the suspected area (often `git log` tail) |
The agent commits the RED test as `test: red for <symptom>` and reports
the handoff carrier for `implement` mini-mode. The agent does NOT write
the fix — splitting RED (this skill) and GREEN (`implement` mini-mode)
across two dispatches keeps the diagnosis honest.
The agent writes the RED test to the working tree (uncommitted) and
reports the handoff carrier for `implement` mini-mode. The agent does
NOT commit anything, and does NOT write the fix — splitting RED (this
skill) and GREEN (`implement` mini-mode) across two dispatches keeps
the diagnosis honest. The Boss decides whether to commit the RED test
as a separate audit-trail commit before dispatching `implement` mini-
mode, or to hand the dirty working tree directly to mini-mode (the
mini-mode orchestrator's Phase-0 clean-tree check will refuse the
latter — so for an audit-trail-preserving flow the Boss commits the
RED test first; for a streamlined-fix flow the Boss commits the
combined RED+GREEN at the end of mini-mode).
## Handoff Contract
@@ -82,7 +89,8 @@ scope for the bug-fix iteration and gets queued for a separate one.
Common Rationalisations table, and the Red Flags list. The
orchestrator does not execute these phases directly.
- **Hand-off target:** `skills/implement/SKILL.md` — runs the GREEN
side after the RED test is committed.
side after the Boss has decided whether to commit the RED test
separately or as part of the final fix commit.
- **Project source:** former CLAUDE.md "Bug fixes — TDD, always"
section is now superseded by this file; CLAUDE.md keeps a one-line
pointer.
+19 -13
View File
@@ -14,11 +14,14 @@ segfault, wrong stdout, panic, observable misbehaviour.
## What this role is for
Bug diagnosis is RED-first. Your output is a *committed failing test* plus a
1-2 sentence cause summary. The fix itself is `skills/implement`'s job, run
in mini-mode. Splitting RED and GREEN across two dispatches keeps the
diagnosis honest: the test is written before any fix is attempted, so it
genuinely captures the symptom, not the post-fix code path.
Bug diagnosis is RED-first. Your output is a *failing test in the working
tree* (uncommitted) plus a 1-2 sentence cause summary. The fix itself is
`skills/implement`'s job, run in mini-mode. You never commit anything;
the Boss decides whether to commit the RED test separately as an audit-
trail commit or to roll it into the final fix commit. Splitting RED
and GREEN across two dispatches keeps the diagnosis honest: the test
is written before any fix is attempted, so it genuinely captures the
symptom, not the post-fix code path.
## Standing reading list
@@ -94,8 +97,10 @@ Each phase completes before the next starts.
- automated, deterministic — same input always same output
- doc comment names the *property* the test protects, not the symptom
3. Run the test. Confirm it fails with the symptom the carrier described.
4. Commit the failing test as a separate commit:
`git commit -m "test: red for <symptom>"`.
4. Leave the failing test in the working tree as an unstaged change.
You do NOT commit. The Boss decides commit shape; the suggested
subject if the Boss elects to commit the RED separately is
`test: red for <symptom>`.
### Phase 4 — Hand off
@@ -120,9 +125,10 @@ orchestrator escalates.
End every report with exactly one of:
- `DONE` — RED test committed, cause documented, ready for `implement`
mini-mode. Provide the handoff carrier (see Output format).
- `DONE_WITH_CONCERNS` — RED test committed, but during diagnosis you
- `DONE` — RED test in the working tree (uncommitted), cause documented,
ready for `implement` mini-mode. Provide the handoff carrier (see
Output format).
- `DONE_WITH_CONCERNS` — RED test in the working tree, but during diagnosis you
noticed a related issue the orchestrator should know about (e.g. another
test would also fail under this code path; the bug shipped in iteration N
but the JOURNAL entry didn't flag the risk).
@@ -140,7 +146,7 @@ At most 250 words, structured:
- **Symptom:** exact error / wrong output (verbatim).
- **Repro:** the one-line command.
- **Cause:** file + function + why (1-2 sentences).
- **RED test:** path to the new test + commit SHA.
- **RED test:** path to the new test in the working tree (uncommitted).
- **Handoff carrier for `implement` mini-mode:**
- `red_test_path`: absolute path
- `cause_summary`: 1-2 sentences
@@ -164,7 +170,7 @@ At most 250 words, structured:
| "I'll write the fix and the test together" | Test-after proves nothing about whether the test would have caught the pre-fix bug. RED before GREEN — always. |
| "The cause is obviously the new tag-extract emit" | Confident guesses paper over real causes. Phase 1 is data-flow tracing, not guessing. |
| "Two RED tests both mis-pinned the symptom; third try is the right one" | Two failures means the hypothesis space is wrong. Phase 4.5 fires now, not after the third try. |
| "End-of-day, just commit a fix and write the test tomorrow" | End-of-day pressure is the worst time for shotgun fixes. Clean tree + open bug > three speculative half-fixes. |
| "End-of-day, just drop a fix into the working tree and write the test tomorrow" | End-of-day pressure is the worst time for shotgun fixes. Clean tree + open bug > three speculative half-fixes. Diagnosis is RED-first; the fix is a separate dispatch. |
| "This bug is trivial, the existing tests will catch regressions" | The existing tests already passed while this bug shipped. By definition they don't cover it. |
| "I can fix and verify in one go and be done" | The skill explicitly splits RED (you) and GREEN (`implement` mini-mode). Don't collapse them; the split is the whole point. |
@@ -177,4 +183,4 @@ At most 250 words, structured:
- "Pattern says X but I'll adapt it differently"
- *"One more hypothesis"* (when ≥ 2 already failed)
- About to apply ANY edit outside the new test file
- About to commit a fix in this dispatch
- About to run `git commit` (anywhere, ever — you never commit)