AILang/docs/journals/2026-05-11-iter-disc.1.md

iter disc.1 — boss-only commits and main-as-quarantine

Date: 2026-05-11 Started from: 841d65d Status: DONE Tasks completed: 10 of 10 (Boss-direct implementation; no orchestrator dispatch)

Summary

Skill-system-wide discipline update. Two project-wide rules are now explicit:

1. Only the Boss commits. No skill agent — implementer, brainstormer, planner, debugger, fieldtester, docwriter, architect, bencher — performs git commit. Agents write all their artefacts into the working tree as unstaged changes; the Boss inspects, decides commit shape (typically one cohesive iter commit, occasionally a few logical commits), and commits.
2. main HEAD is sacrosanct. No actor — Boss or agent — runs git reset or git revert on main. Bad work stays in the working tree where it is still discardable via git checkout -- <paths>; main moves forward only via Boss commits.

The two rules together force a working-tree-as-quarantine discipline: nothing half-baked enters main, because nothing can be taken back off main. The implement skill loses its iter/<iter_id> branch-per-iter mechanic entirely; per-task agent commits are also gone — Phase 4 of the orchestrator-agent now writes the per-iter journal and the stats file into the working tree (Write tool) but does not commit them.

Per-task notes

• disc.1.1: skills/implement/SKILL.md — Iron Law rewritten ("IMPLEMENTER NEVER COMMITS" replaces "ONE BRANCH PER ITER"; "MAIN HEAD IS SACROSANCT" added). Step 3 "Boss merge step" renamed and rewritten as "Boss inspect + commit step" (no fast-forward; Boss reads git status / git diff, decides commit shape, commits). Step 4 (BLOCKED) rewritten: Working-Tree inspect, Repair re-dispatch or Discard via git checkout -- ., no branch deletion. Description, Overview, Rationalisations, Red Flags updated.
• disc.1.2: skills/implement/agents/ailang-implement-orchestrator.md rewritten — Phase 0 is now a clean-tree check (git status --porcelain must be empty), records start_sha informationally (not as reset target), refuses to proceed on a dirty tree. All git commit invocations removed. Phase 4 (journal) and Phase 5 (stats) write to the working tree via the Write tool, no commit. End-report Branch-field replaced by Working tree: dirty (N files) and (uncommitted) markers on file paths.
• disc.1.3: skills/implement/agents/ailang-implementer.md, ailang-tester.md — commit steps in The Process removed. Red-Flag "commit on red tests" replaced by the broader "never commits, ever". Self-review now operates on git diff HEAD with git checkout -- <path> for undo.
• disc.1.4: skills/implement/agents/ailang-spec-reviewer.md, ailang-quality-reviewer.md — Carrier fields pre_task_sha / head_sha replaced by diff_command (default git diff HEAD). The full working-tree diff accumulates across tasks; reviewers focus on the current task's footprint via the task block's file list (or an optional task_footprint_hint).
• disc.1.5: skills/brainstorm/SKILL.md — Step 8 spec-commit block removed; brainstorm writes the spec, user reviews, Boss commits. The Step-7.5 retire-on-BLOCK procedure was rewritten too: it now deletes the working-tree spec file (Bash rm, not git rm, since the file was never committed) and appends a roadmap entry; Boss commits the roadmap edit.
• disc.1.6: skills/planner/SKILL.md — Step 6 plan-commit block removed; planner writes the plan, hand-off carries the filepath, Boss commits. Plan-template tasks lose their per-task "Step 5: Commit" — tasks are now 4 steps (write-failing- test, verify-fail, write-impl, verify-pass) and leave work in the working tree for the iter-level Boss commit. The "Bundle Tasks 3 and 4" rationalisation reframed: tasks are units of review, not units of commit.
• disc.1.7: skills/debug/SKILL.md, skills/debug/agents/ailang-debugger.md — debugger writes the RED test to the working tree (uncommitted) and hands off. The Boss chooses between two flows for implement-mini: commit the RED separately for an audit-trail before dispatching mini-mode (clean-tree mini gets the RED via HEAD diff), or commit RED+GREEN together at the end (Boss decides before dispatching).
• disc.1.8: skills/fieldtest/SKILL.md, skills/fieldtest/agents/ailang-fieldtester.md — Phase 5 commit block removed; fieldtester writes .ailx files, .ail.json files, and the spec to the working tree; Boss commits with the suggested subject fieldtest: <milestone> — <N> examples, <K> findings.
• disc.1.9: skills/docwriter/agents/ailang-docwriter.md — Iron Law extended with "YOU NEVER COMMIT"; Red-Flag added. skills/audit/SKILL.md — Step 4 reframed to name the Boss as the actor who commits tidy fixes / ratify baselines / clean closes. Other audit-agent files (architect, bencher) had no commit invocations and are unchanged in this dispatch.
• disc.1.10: skills/README.md — Conventions section gained two new bullets ("Only the Boss commits", "main HEAD is sacrosanct"). Skill-table Output column updated for implement, docwriter, fieldtest, debug to say "uncommitted in the working tree". CLAUDE.md Direction-freedom subsection rewritten (recovery is no longer about reverting commits; it is about discarding bad working-tree state). New "Commit discipline and main-branch sanctity" subsection added, stating both rules in CLAUDE.md form.

Concerns

(empty)

Known debt

• Three historical files describe the obsolete branch-per-iter discipline: docs/specs/2026-05-11-implement-orchestrator-agent.md, docs/journals/2026-05-11-iter-pr.1.md, docs/plans/2026-05-11-orchestrator-refactor.md. They are zeitliche records and are left intact; this journal entry is the forward-pointer that supersedes them. A future tidy iter could add "Superseded by" banners, but the journal-archive convention is append-only history.
• The implement orchestrator's Phase 0 refuses to run on a dirty tree. The first real dispatch under the new discipline may surface friction around this (e.g. Boss prepared scratch files before dispatch). Capture in that iter's journal.

Blocked detail

(none — DONE)

Files touched

• CLAUDE.md
• skills/README.md
• skills/audit/SKILL.md
• skills/brainstorm/SKILL.md
• skills/debug/SKILL.md
• skills/debug/agents/ailang-debugger.md
• skills/docwriter/agents/ailang-docwriter.md
• skills/fieldtest/SKILL.md
• skills/fieldtest/agents/ailang-fieldtester.md
• skills/implement/SKILL.md
• skills/implement/agents/ailang-implement-orchestrator.md
• skills/implement/agents/ailang-implementer.md
• skills/implement/agents/ailang-quality-reviewer.md
• skills/implement/agents/ailang-spec-reviewer.md
• skills/implement/agents/ailang-tester.md
• skills/planner/SKILL.md
• docs/journals/2026-05-11-iter-disc.1.md (this file)
• docs/journals/INDEX.md

Motivation

On 2026-05-11 iter 23.4 (eq/ord prelude — Free-Fns) BLOCKED three times. A retrospective brainstorm produced a corrected spec; the implement-orchestrator was dispatched on the revised plan and immediately BLOCKED at Phase 0 with a branch-state mismatch: an existing iter/23.4 branch carried prep2 + prep3 commits that the spec falsely claimed lived on main. They had never been fast-forwarded; they were stranded on the iter-branch when the iter was abandoned. The grounding-check agent had passed the spec because it verified main-behaviour-via-green-tests, not git-reachability of named commit SHAs.

The user identified the structural root cause: branch-per-iter plus manual Boss-merge plus iter-stacking allows work to strand on a branch that nobody integrates. The discipline correction is this iter:

• Drop the branch mechanic in implement entirely.
• Centralise commit authority on the Boss across every skill.
• Make main forward-only by policy: no reset, no revert, by anyone.

Per-task agent commits were eh too many (user phrasing: "es wird eh viel zu viel commitet") — the new policy eliminates them as a side-effect.

Forward pointer

Step 5 of the 2026-05-11 recovery plan: re-attempt the eq/ord prelude mono-pass unification (iter 23.4 in the corrected spec docs/specs/2026-05-11-23-eq-ord-prelude.md), now under the discipline this iter installs. A fresh plan is written first; the implement-orchestrator is dispatched against it; the Boss inspects + commits at the end. No branches, no agent commits.

Stats

None — this iter was Boss-direct implementation (no orchestrator dispatch; no stats file written).