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).