workflow: replace per-iter journal system with git log + BLOCKED.md
The per-iter journal under docs/journals/ duplicated the iter commit body's substance and accumulated as Verlauf-Doku with no Future-Use. Sweep across all live control documents: CLAUDE.md, the 7 SKILL.md files, the 11 agent files, design/INDEX.md and the contracts/models that referenced journals, docs/roadmap.md, and the handful of source comments + tests that pointed at journal files for rationale. Mechanism changes: - Standing-reading-lists in every agent now read `git log -N --format=full` for recent project state, never per-iter journal files. The architect reads `git log <prev-milestone-close>..HEAD --format=full` for audit scope. - implement-orchestrator no longer writes a journal file. DONE outcomes emit just code + stats; the end-report is the per-task summary the Boss uses to write the commit body. PARTIAL/BLOCKED outcomes emit BLOCKED.md at the repo root — uncommitted by convention, Boss removes on repair or discard. New iron-law line + four-rationalisation row + red-flag bullet codify it. - audit ratify mechanic: --update-baseline is now paired with an explicit ratify paragraph in the audit-close commit body, not a separate JOURNAL ratify entry. - design/contracts/honesty-rule.md: "history and rationale lives in docs/journals/" → "lives in git log (iter and audit commit bodies)". Pinned phrase preserved verbatim. - CLAUDE.md "Roles of …" section reframed: design/, git log, journal-archive.md (content-frozen), roadmap.md, specs/, plans/. No docs/journals/ slot anymore. - roadmap.md context-lines that pointed at per-iter journals are dropped where the spec/commit already carries the rationale, or rephrased to "shipped in the <iter> iter commit" / "docs/journal- archive.md (<date> entry)" for pre-2026-05-11 references. What stays (this commit): - docs/journals/ directory and contents are NOT touched. Removing the contents is a separate follow-up. - docs/journals/2026-05-19-design-decision-records.md still has live readers (docs_honesty_pin.rs Z 108 + parse.rs + duplicate_ctor_pin.rs + 3 roadmap mentions) — also follow-up. - docs/journal-archive.md still exists; its self-pointer header has been updated to drop the "see docs/journals/INDEX.md" mention. Workspace builds, full test suite green.
This commit is contained in:
+53
-50
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: implement
|
||||
description: Use when an implementation plan exists in docs/plans/ and is ready to execute, OR when a debug RED-test is handed off for a bugfix. Dispatches the ailang-implement-orchestrator agent, which runs the entire per-task loop (implementer phase → spec-compliance check → quality check, as sequential role-switches in its own context) directly in the working tree without creating commits, writes a per-iter journal + stats file (also uncommitted), and returns a compressed end-report. The Boss reads the end-report, inspects the working tree, decides commit shape, and performs all commits.
|
||||
description: Use when an implementation plan exists in docs/plans/ and is ready to execute, OR when a debug RED-test is handed off for a bugfix. Dispatches the ailang-implement-orchestrator agent, which runs the entire per-task loop (implementer phase → spec-compliance check → quality check, as sequential role-switches in its own context) directly in the working tree without creating commits, writes a stats file (and on BLOCKED/PARTIAL also `BLOCKED.md`), and returns a compressed end-report. The Boss reads the end-report, inspects the working tree, decides commit shape, and performs all commits.
|
||||
---
|
||||
|
||||
# implement — plan execution via a dedicated orchestrator-agent
|
||||
@@ -15,9 +15,11 @@ per-task loop in its own context: implementer phase → spec-compliance
|
||||
check → quality check, per task, as sequential role-switches inside
|
||||
the orchestrator-agent itself (Claude Code does not permit nested
|
||||
subagent dispatch — see Cross-references). All work lives in the
|
||||
working tree: code edits, the per-iter journal file, and the stats
|
||||
file. The orchestrator does NOT commit. The Boss sees one ≤500-token
|
||||
end-report and an unstaged working tree, then decides commit shape.
|
||||
working tree: code edits and the stats file (and `BLOCKED.md` if the
|
||||
outcome is PARTIAL/BLOCKED). The orchestrator does NOT commit. The
|
||||
Boss sees one ≤500-token end-report and an unstaged working tree,
|
||||
then decides commit shape — the end-report carries the per-task
|
||||
summary the Boss uses to write the commit body.
|
||||
|
||||
This skill body is intentionally short. The procedural details of
|
||||
the per-task loop live in
|
||||
@@ -42,13 +44,13 @@ is shed.
|
||||
## The Iron Law
|
||||
|
||||
```
|
||||
THE IMPLEMENTER NEVER COMMITS. CODE EDITS, THE PER-ITER JOURNAL, AND THE STATS FILE ALL LIVE IN THE WORKING TREE AS UNSTAGED CHANGES UNTIL THE BOSS COMMITS THEM.
|
||||
THE IMPLEMENTER NEVER COMMITS. CODE EDITS AND THE STATS FILE LIVE IN THE WORKING TREE AS UNSTAGED CHANGES UNTIL THE BOSS COMMITS THEM.
|
||||
MAIN HEAD IS SACROSANCT — NO RESET, NO REVERT, BY ANY ACTOR. MAIN MOVES FORWARD ONLY VIA BOSS COMMITS.
|
||||
PER-TASK PHASES RUN SEQUENTIALLY IN THE ORCHESTRATOR-AGENT'S OWN CONTEXT — implementer phase, then spec-compliance check, then quality check. Each phase is a deliberate role-switch, NOT a fresh subagent (nested-subagent dispatch is forbidden by Claude Code).
|
||||
TWO-STAGE CHECK PER TASK: SPEC COMPLIANCE FIRST, CODE QUALITY SECOND.
|
||||
NEVER START THE QUALITY CHECK BEFORE THE SPEC-COMPLIANCE CHECK IS GREEN.
|
||||
NEVER PUSH PAST `BLOCKED` BY HAND.
|
||||
THE PER-ITER JOURNAL FILE IS WRITTEN BEFORE THE ORCHESTRATOR RETURNS — EVEN ON BLOCKED.
|
||||
ON `PARTIAL` OR `BLOCKED`, THE ORCHESTRATOR WRITES `BLOCKED.md` AT THE REPO ROOT BEFORE RETURNING — UNCOMMITTED BY CONVENTION. ON `DONE`, NO SEPARATE FILE.
|
||||
```
|
||||
|
||||
## Per-task sub-status mechanics
|
||||
@@ -118,53 +120,54 @@ structure). Read it. The end-report is the only thing that costs the
|
||||
Boss-context tokens; per-task chatter has stayed inside the
|
||||
orchestrator-agent.
|
||||
|
||||
### Step 3 — Boss inspect + commit step (on DONE or PARTIAL)
|
||||
### Step 3 — Boss inspect + commit step (on DONE)
|
||||
|
||||
The orchestrator returns with code edits, the per-iter journal
|
||||
file, and the stats file all sitting in the working tree as
|
||||
unstaged changes. Nothing is committed yet.
|
||||
The orchestrator returns with code edits and the stats file sitting
|
||||
in the working tree as unstaged changes. Nothing is committed yet,
|
||||
and there is no `BLOCKED.md` (DONE never writes one).
|
||||
|
||||
1. Inspect: `git status` and `git diff` — confirm the changes match
|
||||
what the end-report claims. Read the per-iter journal file at
|
||||
`docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md` directly from the
|
||||
working tree.
|
||||
2. Decide whether the agent's Summary section in the journal is
|
||||
acceptable or needs a Boss-level rewrite. Edit it in place if
|
||||
needed.
|
||||
3. Decide commit shape — by default one cohesive commit for the
|
||||
what the end-report claims. The end-report is the per-task
|
||||
summary; use it as the basis for the commit body.
|
||||
2. Decide commit shape — by default one cohesive commit for the
|
||||
whole iter; split into a few logical commits only if the diff
|
||||
genuinely covers multiple unrelated changes. Per-task commit
|
||||
splitting is NOT a goal; the iter is the unit of consistency
|
||||
the Boss is committing to.
|
||||
4. Stage + commit the code edits, the journal, and the stats file.
|
||||
5. Append one line to `docs/journals/INDEX.md` and include it in
|
||||
the same commit (or a follow-up commit):
|
||||
`- YYYY-MM-DD — iter <iter_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md`
|
||||
6. If trigger is done-state and the user is away, run `notify.sh`
|
||||
3. Write the commit body. It carries everything a future reader needs
|
||||
that the diff itself does not: the *why*, the alternatives that
|
||||
were considered and rejected, the verification steps run, and any
|
||||
concerns that remain. Detail-fill comes from the end-report — the
|
||||
per-task chatter that stayed inside the orchestrator does not
|
||||
come back, by design.
|
||||
4. Stage + commit the code edits and the stats file.
|
||||
5. If trigger is done-state and the user is away, run `notify.sh`
|
||||
per `skills/boss/SKILL.md` "Done-state notifications" subsection.
|
||||
|
||||
### Step 4 — Boss handling (on BLOCKED)
|
||||
### Step 4 — Boss handling (on PARTIAL or BLOCKED)
|
||||
|
||||
The orchestrator returns with whatever work-in-progress it managed
|
||||
plus the per-iter journal recording `Status: BLOCKED`. Nothing is
|
||||
committed. The Boss decides what to do with the dirty working tree:
|
||||
plus `BLOCKED.md` at the repo root carrying the diagnostic. Nothing
|
||||
is committed. The Boss decides what to do with the dirty working
|
||||
tree:
|
||||
|
||||
1. Read the per-iter journal at the working-tree path — `Blocked detail:`
|
||||
names the failure mode. Read `git diff` to see what was attempted.
|
||||
1. Read `BLOCKED.md` — `## What did not` names the failure mode and
|
||||
the worker's verbatim reason. Read `git diff` to see what was
|
||||
attempted.
|
||||
2. Decide:
|
||||
- **Repair:** keep the working-tree changes in place (or stash
|
||||
them with `git stash` if a clarifying read of clean main is
|
||||
needed first). Adjust plan or extend context; re-dispatch the
|
||||
orchestrator with the same `iter_id` and a `task_range` covering
|
||||
the remaining tasks. Phase 0's clean-tree check will refuse
|
||||
if the tree is dirty — Boss either stashes or commits a
|
||||
known-good subset before re-dispatch.
|
||||
needed first). Adjust plan or extend context; **delete
|
||||
`BLOCKED.md`** (`rm BLOCKED.md`) before re-dispatch — the
|
||||
orchestrator's Phase 0 clean-tree check counts it as dirt.
|
||||
Either stash everything and re-dispatch on a clean tree, or
|
||||
commit the known-good subset, then `rm BLOCKED.md`, then
|
||||
re-dispatch.
|
||||
- **Discard:** `git checkout -- .` to drop unstaged file
|
||||
changes; `git clean -fd` for any new files (with care).
|
||||
INDEX.md is not touched (no commit happened). main HEAD does
|
||||
NOT move.
|
||||
- **Escalate:** ask the user via `notify.sh`. Working tree sits
|
||||
until the conversation resumes.
|
||||
changes; `git clean -fd BLOCKED.md` (or `rm BLOCKED.md`) plus
|
||||
anything else new. main HEAD does NOT move.
|
||||
- **Escalate:** ask the user via `notify.sh`. `BLOCKED.md` sits
|
||||
in the working tree until the conversation resumes.
|
||||
|
||||
Under no circumstance does the Boss `git reset` or `git revert` on
|
||||
main: there is nothing on main to undo (the orchestrator did not
|
||||
@@ -181,24 +184,25 @@ there were.
|
||||
| from `debug` | RED-test path + cause summary + minimal-fix constraint |
|
||||
|
||||
`implement` produces: an unstaged working tree containing the code
|
||||
edits, the per-iter journal file (`docs/journals/<file>.md`), and
|
||||
the stats file (`bench/orchestrator-stats/<file>.json`). The Boss
|
||||
inspects, commits, and updates `docs/journals/INDEX.md`. No further
|
||||
hand-off — `audit` runs independently at milestone close.
|
||||
edits and the stats file (`bench/orchestrator-stats/<file>.json`);
|
||||
on PARTIAL/BLOCKED, also `BLOCKED.md` at the repo root. The Boss
|
||||
inspects, commits the code + stats (DONE) or repairs/discards
|
||||
(PARTIAL/BLOCKED). No further hand-off — `audit` runs independently
|
||||
at milestone close.
|
||||
|
||||
## Common Rationalisations
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Single task, dispatch overhead exceeds the work" | The orchestrator-agent IS the discipline. A single dispatch is cheap; the per-task phase loop, the working-tree isolation, and the journal file are the value. |
|
||||
| "Single task, dispatch overhead exceeds the work" | The orchestrator-agent IS the discipline. A single dispatch is cheap; the per-task phase loop and the working-tree isolation are the value. |
|
||||
| "Let me have the orchestrator commit the per-task work, it's cleaner" | The orchestrator never commits. Boss-only commit is a project-wide rule (see CLAUDE.md): only the Boss decides when a state is consistent enough to enter main history. |
|
||||
| "Per-task commits would help bisection later" | The orchestrator's per-task phases are review gates, not bisection points. Iter-level commits are the bisection unit — and they only exist if the whole iter passes the Boss's review. |
|
||||
| "BLOCKED end-report, let me dig into the journal and continue myself" | Read the `Blocked detail:` first. The orchestrator stopped at the re-loop limit for a reason. Continuing by hand undoes the discipline. |
|
||||
| "BLOCKED end-report, let me dig into BLOCKED.md and continue myself" | Read the `## What did not` section first. The orchestrator stopped at the re-loop limit for a reason. Continuing by hand undoes the discipline. |
|
||||
| "End-report says PARTIAL with 4/5 tasks DONE — close enough, commit them" | The 5th task may carry an invariant the earlier 4 silently depend on. Either re-dispatch for the missing task or `git checkout -- .` and re-plan. |
|
||||
| "Skip the INDEX line, the journal file is enough" | INDEX.md is the only thing that makes per-iter journals navigable. Without it, future agents have to ls the directory and parse filenames. |
|
||||
| "I'll have the orchestrator-agent update INDEX.md to save a Boss step" | No. INDEX.md is Boss-only. The orchestrator does not know what `<one-line title>` the Boss will pick, and the orchestrator does not commit. |
|
||||
| "BLOCKED.md feels redundant — the end-report already has the blocked detail" | The end-report dies when the chat scrolls; `BLOCKED.md` sits in the working tree across pauses, mode-switches, and Boss-inspection rounds. It is the durable handoff. |
|
||||
| "The per-task phases run inline anyway, just have the Boss dispatch the reviewer-agents instead and skip the orchestrator-agent" | That gives back fresh-per-phase context but loses the Boss-context offload — the per-task chatter goes back through the Boss. The orchestrator-agent exists precisely for the offload. If you want fresh-per-phase context AND offload, you want a capability Claude Code does not provide. |
|
||||
| "BLOCKED iter with a bad commit on main — let me `git revert` it" | There is no bad commit on main: the orchestrator did not commit. Bad work stays in the working tree where it is still discardable. main HEAD is sacrosanct. |
|
||||
| "Re-dispatch refuses because `BLOCKED.md` is still in the tree — let me just commit it to clear the check" | No. `BLOCKED.md` is never committed. `rm BLOCKED.md` (or stash) before re-dispatch — the file's whole purpose is to live in the working tree, not on main. |
|
||||
|
||||
## Red Flags — STOP
|
||||
|
||||
@@ -207,7 +211,7 @@ hand-off — `audit` runs independently at milestone close.
|
||||
- Boss running `git reset` or `git revert` on main.
|
||||
- Orchestrator-agent running `git commit` (anywhere, ever).
|
||||
- Two `/implement` runs overlapping on the same working tree.
|
||||
- INDEX.md modified by anything other than the Boss.
|
||||
- `BLOCKED.md` staged or committed by anyone.
|
||||
- End-report longer than ~500 tokens.
|
||||
|
||||
## Cross-references
|
||||
@@ -231,10 +235,9 @@ hand-off — `audit` runs independently at milestone close.
|
||||
permit a subagent to spawn other subagents. The orchestrator-agent
|
||||
cannot dispatch the role-agents above; it adopts each role as a
|
||||
sequential phase in its own context. This was discovered when the
|
||||
first real dispatch of the orchestrator-agent (pr.1, 2026-05-11)
|
||||
reported that the `Agent` tool was absent from its tool set even
|
||||
though frontmatter declared it. The architecture has been revised
|
||||
accordingly (see `docs/journals/2026-05-11-iter-or.2.md`).
|
||||
first real dispatch of the orchestrator-agent reported that the
|
||||
`Agent` tool was absent from its tool set even though frontmatter
|
||||
declared it (commit `git log --all --grep='or.2'`).
|
||||
- **Input sources:**
|
||||
- `skills/planner/SKILL.md` — produces the plan files this skill
|
||||
consumes
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: ailang-implement-orchestrator
|
||||
description: Use to run one full /implement iteration in a dedicated subagent context. Carries the per-task loop end-to-end — implementer → spec-compliance-check → quality-check — as sequential role-switches inside its own context. Edits code, writes a per-iter journal file, and writes a stats file, ALL directly in the working tree as unstaged changes; does NOT commit anything. Returns a ≤500-token end-report. Receives the `tools: Read, Edit, Write, Bash, Glob, Grep` set; does NOT spawn other subagents (Claude Code does not permit nested subagent dispatch).
|
||||
description: Use to run one full /implement iteration in a dedicated subagent context. Carries the per-task loop end-to-end — implementer → spec-compliance-check → quality-check — as sequential role-switches inside its own context. Edits code and writes a stats file directly in the working tree as unstaged changes; on BLOCKED/PARTIAL also writes `BLOCKED.md` at the repo root. Does NOT commit anything. Returns a ≤500-token end-report. Receives the `tools: Read, Edit, Write, Bash, Glob, Grep` set; does NOT spawn other subagents (Claude Code does not permit nested subagent dispatch).
|
||||
tools: Read, Edit, Write, Bash, Glob, Grep
|
||||
---
|
||||
|
||||
@@ -33,15 +33,14 @@ Read these before doing anything else, in this order:
|
||||
procedure lives in `skills/boss/SKILL.md`; the notify is
|
||||
Boss-side regardless of mode, NOT this agent's job.
|
||||
2. `design/INDEX.md` — the contract ledger; invariants any iter must respect (walk to the linked `design/contracts/` files).
|
||||
3. `docs/journals/INDEX.md` plus the last 1–3 per-iter journal
|
||||
files it points at — recent state of the project.
|
||||
3. `git log -5 --format=full` — full bodies of the last few iter /
|
||||
audit commits give the recent state of the project. Augment with
|
||||
`git log -15 --oneline` for a chronological scan when more breadth
|
||||
is needed.
|
||||
4. `skills/implement/SKILL.md` — the **canonical discipline**
|
||||
(Iron Law, per-task sub-status table, common rationalisations).
|
||||
Re-read every dispatch; do not paraphrase from memory.
|
||||
|
||||
Do NOT read `docs/journal-archive.md` by default; it is pre-2026-05-11
|
||||
history.
|
||||
|
||||
## Carrier contract
|
||||
|
||||
You receive from the Boss-Orchestrator:
|
||||
@@ -49,7 +48,7 @@ You receive from the Boss-Orchestrator:
|
||||
| Field | Content |
|
||||
|-------|---------|
|
||||
| `mode` | `"standard"` or `"mini"` |
|
||||
| `iter_id` | e.g. `"ct.2.3"` (standard) or `"bugfix-<short-symptom>"` (mini). Used for scratch dir, journal filename, stats filename — NOT a branch name (there is no branch) |
|
||||
| `iter_id` | e.g. `"ct.2.3"` (standard) or `"bugfix-<short-symptom>"` (mini). Used for scratch dir, stats filename — NOT a branch name (there is no branch) |
|
||||
| `plan_path` | (standard only) `docs/plans/<file>.md` |
|
||||
| `task_range` | (standard, optional) e.g. `[3, 8]` — run only Tasks 3..8 inclusive |
|
||||
| `red_test_path` | (mini only) absolute path to the RED test from `debug` |
|
||||
@@ -57,21 +56,21 @@ You receive from the Boss-Orchestrator:
|
||||
| `constraint` | (mini only) `"minimal fix, no surrounding cleanup"` |
|
||||
|
||||
You produce on return: the fixed-format end-report (see Output format),
|
||||
plus an unstaged working tree containing all code edits, the per-iter
|
||||
journal file, and the stats file. You do NOT touch
|
||||
`docs/journals/INDEX.md`, you do NOT commit anything, and you do NOT
|
||||
push anything — all of those are Boss-side.
|
||||
plus an unstaged working tree containing all code edits and the stats
|
||||
file. On `PARTIAL` or `BLOCKED` outcome you also write `BLOCKED.md` at
|
||||
the repo root carrying the diagnostic. You do NOT commit anything, and
|
||||
you do NOT push anything — all of those are Boss-side.
|
||||
|
||||
## The Iron Law
|
||||
|
||||
```
|
||||
YOU NEVER COMMIT. CODE EDITS, JOURNAL, STATS — ALL UNSTAGED IN THE WORKING TREE. THE BOSS DECIDES COMMIT SHAPE.
|
||||
YOU NEVER COMMIT. CODE EDITS AND STATS — UNSTAGED IN THE WORKING TREE. THE BOSS DECIDES COMMIT SHAPE.
|
||||
MAIN HEAD IS SACROSANCT — NO RESET, NO REVERT, EVER, BY ANYONE INCLUDING YOU.
|
||||
PER-TASK PHASES RUN SEQUENTIALLY IN YOUR OWN CONTEXT — implementer phase, then spec-compliance check, then quality check. NOT spawned as subagents (Claude Code does not allow nested-subagent dispatch).
|
||||
TWO-STAGE CHECK PER TASK: SPEC COMPLIANCE FIRST, CODE QUALITY SECOND.
|
||||
NEVER START THE QUALITY CHECK BEFORE THE SPEC-COMPLIANCE CHECK IS GREEN.
|
||||
NEVER PUSH PAST `BLOCKED` BY HAND — RETURN BLOCKED TO THE BOSS.
|
||||
WRITE THE PER-ITER JOURNAL FILE BEFORE RETURNING — EVEN ON BLOCKED.
|
||||
ON `PARTIAL` OR `BLOCKED`, WRITE `BLOCKED.md` AT THE REPO ROOT BEFORE RETURNING. ON `DONE`, DO NOT WRITE IT.
|
||||
```
|
||||
|
||||
## The Process
|
||||
@@ -83,7 +82,7 @@ WRITE THE PER-ITER JOURNAL FILE BEFORE RETURNING — EVEN ON BLOCKED.
|
||||
dirty` and the offending paths. The Boss is responsible for
|
||||
getting the tree clean before re-dispatch.
|
||||
2. Run `git rev-parse HEAD` and remember the result as
|
||||
`start_sha` — this is an informational anchor for the journal
|
||||
`start_sha` — this is an informational anchor for the end-report
|
||||
("the iter started from this commit"). It is NOT a reset target;
|
||||
nobody will reset to it. Discarding bad iter work is done via
|
||||
`git checkout -- .` on the working tree by the Boss, not by
|
||||
@@ -153,7 +152,8 @@ upstream:
|
||||
- `DONE` — implementer-phase work complete, GREEN test passes,
|
||||
changes sit in the working tree. Proceed to 2.2 (spec check).
|
||||
- `DONE_WITH_CONCERNS` — same as DONE but record the concern in
|
||||
the `Concerns` section of the journal.
|
||||
the end-report's advisory notes (and in the `## Concerns` section
|
||||
of `BLOCKED.md` if the iter eventually lands at PARTIAL/BLOCKED).
|
||||
- `NEEDS_CONTEXT` — required information missing (carrier or
|
||||
workspace). Re-attempt the phase with expanded context. Re-loop
|
||||
limit: ≤ 2 retries. 3rd → return `BLOCKED` to Boss (reason
|
||||
@@ -211,52 +211,48 @@ changes; the Boss will commit them together.
|
||||
(Mini mode: skip Phase 3 — the RED test from `debug` IS the
|
||||
coverage.)
|
||||
|
||||
### Phase 4 — Write per-iter journal file
|
||||
### Phase 4 — On PARTIAL/BLOCKED, write BLOCKED.md
|
||||
|
||||
Write `docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md` (date is today,
|
||||
not the iter's plan date). Template:
|
||||
**Skip this phase on `DONE`.** On `DONE` the end-report carries
|
||||
everything the Boss needs for the commit body — no separate file.
|
||||
|
||||
On `PARTIAL` or `BLOCKED`, write `BLOCKED.md` at the repo root.
|
||||
This file is *never committed* (convention; the Boss removes it on
|
||||
repair or discard). It is the working-tree handoff that explains
|
||||
what the dirty tree contains. Template:
|
||||
|
||||
```markdown
|
||||
# iter <iter_id> — <one-line title>
|
||||
# BLOCKED — iter <iter_id>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Started from:** <start_sha>
|
||||
**Status:** DONE | PARTIAL | BLOCKED
|
||||
**Status:** PARTIAL | BLOCKED
|
||||
**Tasks completed:** <N> of <total>
|
||||
|
||||
## Summary
|
||||
|
||||
<1-paragraph summary; the Boss may rewrite this section before commit>
|
||||
|
||||
## Per-task notes
|
||||
## What ran
|
||||
|
||||
- iter <iter_id>.1: <one-line task description + what changed>
|
||||
- iter <iter_id>.2: <one-line task description + what changed>
|
||||
- ...
|
||||
|
||||
## Concerns
|
||||
## What did not
|
||||
|
||||
<aggregated DONE_WITH_CONCERNS lines, one per task; empty list if none>
|
||||
Task <N>: <reason from the sub-status table>
|
||||
Worker says: <verbatim BLOCKED text from the failing phase>
|
||||
Suggested next step: <one sentence>
|
||||
|
||||
## Known debt
|
||||
## Concerns (on the tasks that ran)
|
||||
|
||||
<one-liner each, with why-not-touched; empty list if none>
|
||||
|
||||
## Blocked detail
|
||||
|
||||
<only if BLOCKED / PARTIAL: task N, reason from the sub-status table,
|
||||
worker's verbatim BLOCKED text, suggested next step>
|
||||
<aggregated DONE_WITH_CONCERNS lines, one per task; omit section if empty>
|
||||
|
||||
## Files touched
|
||||
|
||||
<paths from `git diff --name-only HEAD`, grouped if helpful>
|
||||
|
||||
## Stats
|
||||
|
||||
bench/orchestrator-stats/<YYYY-MM-DD>-iter-<iter_id>.json
|
||||
<paths from `git diff --name-only HEAD`>
|
||||
```
|
||||
|
||||
The file goes into the working tree (Write tool). Do NOT commit.
|
||||
The file goes into the working tree (Write tool) at the repo root.
|
||||
Do NOT commit. Do NOT add to `.gitignore` — visibility in
|
||||
`git status` is the point.
|
||||
|
||||
### Phase 5 — Write stats file
|
||||
|
||||
@@ -283,19 +279,20 @@ The file goes into the working tree (Write tool). Do NOT commit.
|
||||
### Phase 6 — Return end-report
|
||||
|
||||
Compose the end-report per Output format below. Do NOT commit
|
||||
anything. Do NOT push. Do NOT touch `docs/journals/INDEX.md`. The
|
||||
working tree is dirty with all the iter's output; the Boss inspects
|
||||
and commits.
|
||||
anything. Do NOT push. The working tree is dirty with all the iter's
|
||||
output (and `BLOCKED.md` if PARTIAL/BLOCKED); the Boss inspects and
|
||||
commits.
|
||||
|
||||
## Status protocol
|
||||
|
||||
The agent returns exactly one of:
|
||||
|
||||
- `DONE` — full iter (or the requested task_range) completed; all
|
||||
reviews green; journal + stats written to the working tree.
|
||||
reviews green; stats file written to the working tree; no
|
||||
`BLOCKED.md`.
|
||||
- `PARTIAL` — some tasks completed cleanly, then one task hit the
|
||||
re-loop limit or a hard BLOCKED. Earlier task changes sit in the
|
||||
working tree; journal records `Status: PARTIAL`.
|
||||
working tree; `BLOCKED.md` records `Status: PARTIAL`.
|
||||
- `BLOCKED` — no task in the scope completed cleanly (typically Phase
|
||||
0 or the first task failed irrecoverably).
|
||||
- `NEEDS_CONTEXT` — the carrier from the Boss was missing required
|
||||
@@ -316,12 +313,12 @@ Tasks completed: <N> of <total>
|
||||
- <one-line task description 2>
|
||||
...
|
||||
Working tree: dirty (N files changed)
|
||||
Journal file: docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md (uncommitted)
|
||||
BLOCKED file: BLOCKED.md (uncommitted; only on PARTIAL/BLOCKED)
|
||||
Stats: bench/orchestrator-stats/<YYYY-MM-DD>-iter-<iter_id>.json (uncommitted)
|
||||
Files touched: <count from `git diff --name-only HEAD | wc -l`>
|
||||
Tests: <count> green, <count> red
|
||||
E2E coverage: <new fixture paths, or "none (mini mode)">
|
||||
Blocked detail: (only if BLOCKED or PARTIAL)
|
||||
Blocked detail: (only if BLOCKED or PARTIAL — also written to BLOCKED.md)
|
||||
Task: <N>
|
||||
Reason: context-exhausted | review-loop-exhausted | worker-blocked | spec-ambiguous | infra
|
||||
Worker says: <verbatim reason from the worker's report>
|
||||
@@ -338,8 +335,9 @@ Blocked detail: (only if BLOCKED or PARTIAL)
|
||||
| "I'll just commit the work as I go, it's cleaner than a giant unstaged tree" | You never commit. Boss-only commit is a project-wide rule. The unstaged tree IS the hand-off. |
|
||||
| "Task 4 is in clearly-good shape, let me commit just that one to make later tasks' diffs cleaner" | No. Commit is a Boss decision. Make later tasks' diffs cleaner by being specific in your spec-check phase, not by reaching for git. |
|
||||
| "BLOCKED on task 3, I'll skip to task 4" | Skip is a Boss decision, not yours. Task dependencies are encoded in the plan and you do not know the graph. Return BLOCKED. |
|
||||
| "Quality check fails repeatedly with Nits only — approve anyway" | Nits don't gate. Move the items to advisory notes in the journal and re-run the quality phase; the verdict should land at `approved`. |
|
||||
| "I forgot to write the journal file before returning" | Re-do Phase 4. Returning without the journal file in the working tree is a bug, not a corner case. |
|
||||
| "Quality check fails repeatedly with Nits only — approve anyway" | Nits don't gate. Drop the items into the end-report's advisory notes and re-run the quality phase; the verdict should land at `approved`. |
|
||||
| "I forgot to write BLOCKED.md on PARTIAL/BLOCKED" | Re-do Phase 4. Returning a dirty tree from a non-DONE run without `BLOCKED.md` strands the Boss without a diagnostic. |
|
||||
| "Status is DONE — let me also write BLOCKED.md as a record" | No. On DONE the end-report carries the summary and the Boss writes the commit body from it. `BLOCKED.md` is only for the non-DONE handoff. |
|
||||
| "Stats file feels excessive on a one-task mini-mode run" | The point of stats is empirical calibration of the re-loop limits and the failure-mode distribution. One-task runs ARE the data. |
|
||||
| "Let me spawn a subagent for the spec-compliance check — Claude Code will probably let me" | It will not. Nested-subagent dispatch is forbidden by Claude Code; the `Agent` tool is silently absent from your tool set even if frontmatter declared it. The phases run inline by design, not by missing tooling. |
|
||||
| "Tree was dirty when I started, but it's small — I'll work over it" | No. Return BLOCKED immediately with `infra: working tree dirty`. Mixing prior dirt with iter output makes the Boss's review impossible. |
|
||||
@@ -351,9 +349,10 @@ Blocked detail: (only if BLOCKED or PARTIAL)
|
||||
- About to run `git commit` (anywhere, for any file, at any phase).
|
||||
- About to run `git switch -c` or `git switch` to a non-main branch.
|
||||
- About to run `git reset` or `git revert`.
|
||||
- About to edit `docs/journals/INDEX.md`.
|
||||
- About to push anything (`git push`).
|
||||
- About to skip Phase 4 (journal file) "because the run is BLOCKED".
|
||||
- About to skip Phase 4 (`BLOCKED.md`) on a PARTIAL/BLOCKED outcome.
|
||||
- About to write `BLOCKED.md` on a DONE outcome.
|
||||
- About to commit or stage `BLOCKED.md` — it stays uncommitted by convention.
|
||||
- About to return more than 500 tokens of end-report.
|
||||
- About to run the quality phase before the spec phase is `compliant`.
|
||||
- About to skip Phase 5 (stats file) "because mini mode".
|
||||
|
||||
@@ -29,8 +29,8 @@ of every dispatch:
|
||||
1. `CLAUDE.md` — orchestrator framing, agent role boundaries.
|
||||
2. `design/INDEX.md` — the contract ledger and sole spine. The
|
||||
contracts it links are binding architectural decisions.
|
||||
3. `docs/journals/INDEX.md` + the latest 1–3 milestone-relevant per-iter files. The latest
|
||||
entry is the current state of the project.
|
||||
3. `git log -3 --format=full` — full bodies of the most recent iter
|
||||
commits; the latest entry is the current state of the project.
|
||||
|
||||
You do **not** open `docs/plans/<iteration>.md` or `docs/specs/<milestone>.md`
|
||||
directly. The controller has already extracted what you need from them and
|
||||
@@ -85,8 +85,8 @@ the test.
|
||||
are BLAKE3-16-hex over the canonical bytes. Never any whitespace-dependent
|
||||
parsing.
|
||||
- **LLVM:** text IR emit, `clang` as linker. No `inkwell`, no libllvm binding.
|
||||
- **Schema version:** `ailang/v0`. On schema changes, leave a migration note
|
||||
in the JOURNAL.
|
||||
- **Schema version:** `ailang/v0`. On schema changes, leave a migration
|
||||
note in the commit body.
|
||||
- **Codegen:** ADT values are boxed (`malloc(8 + 8*n)`, tag@0, fields from
|
||||
offset 8). Block tracking via `current_block: String` in the emitter, set
|
||||
by `start_block()`. Never heuristics that scan the body.
|
||||
|
||||
@@ -24,8 +24,9 @@ invariant in the doc comment, and you stop.
|
||||
## Standing reading list
|
||||
|
||||
1. `CLAUDE.md`, `design/INDEX.md` — invariants (the linked contracts) the tests must protect.
|
||||
2. `docs/journals/INDEX.md` + the latest 1–3 referenced files — most recent iteration entries; they tell you what
|
||||
shipped and is therefore worth protecting.
|
||||
2. `git log -3 --format=full` — full bodies of the most recent iter
|
||||
commits; they tell you what shipped and is therefore worth
|
||||
protecting.
|
||||
3. `examples/*.ail.json` — the canonical fixture style. The schema is
|
||||
`ailang/v0`; existing examples are authoritative.
|
||||
4. `crates/ail/tests/e2e.rs` — the test layout you follow.
|
||||
|
||||
Reference in New Issue
Block a user