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
|
||||
|
||||
Reference in New Issue
Block a user