# iter or.1 — orchestrator-refactor

**Date:** 2026-05-11
**Branch:** iter/or.1
**Status:** DONE
**Tasks completed:** 7 of 7

## Summary

This iter lands the three coupled changes from
`docs/specs/2026-05-11-implement-orchestrator-agent.md`:

1. **Boss-context offload.** A new agent
   `skills/implement/agents/ailang-implement-orchestrator.md` owns
   one full `/implement` iter end-to-end — per-task implementer →
   spec-reviewer → quality-reviewer loop, with the canonical
   re-loop limits — running in its own context. The Boss now
   dispatches one subagent and receives a ≤500-token end-report.
2. **Iter isolation via branches.** Each `/implement` run owns a
   dedicated `iter/<iter_id>` branch, created from `origin/main`
   in Phase 0 of the orchestrator-agent. Integration is a Boss-side
   `git switch main && git merge --ff-only` after reading the
   end-report.
3. **Per-iter journals.** `docs/JOURNAL.md` (14k lines) is renamed
   to `docs/journal-archive.md` with an archived-status header.
   Going forward, each iter writes its own file under
   `docs/journals/<YYYY-MM-DD>-iter-<id>.md`; the Boss appends a
   one-line pointer to `docs/journals/INDEX.md` at merge time.
   This file is the first such per-iter journal.

The orchestrator-agent goes live on the *next* `/implement` run after
this iter lands. This iter itself was executed in the pre-refactor
mode (Boss dispatched workers directly) — a bootstrap necessity since
the new agent did not yet exist while creating it.

Model selection was unchanged: every dispatch this iter used Opus 4.7.
The token savings come from token-volume relocation, not from
intelligence downgrade.

## Per-task subjects

- iter or.1.1: migrate JOURNAL.md to journal-archive.md + docs/journals/
- iter or.1.2: repoint top-level docs to docs/journals/ + journal-archive.md
- iter or.1.2-fix: address quality-review minor + nit
- iter or.1.3: repoint skill + agent reading lists to docs/journals/
- iter or.1.3-fix: address quality-review minors (architect / audit phrasing)
- iter or.1.4: carrier switch task_text -> task_text_path
- iter or.1.5: new agent ailang-implement-orchestrator
- iter or.1.6: rewrite skills/implement/SKILL.md to delegate to orchestrator-agent
- iter or.1.6-fix: correct git rebase syntax + README cross-ref wording
- iter or.1.6-fix2: SKILL.md description drift + self-contained exception ref
- iter or.1.7: document ailang-implement-orchestrator as named exception

## Concerns

Three `DONE_WITH_CONCERNS` observations across the iter, all
plan-template issues rather than scope deviations:

- Task 1: the plan's Step 6 listed `git add docs/JOURNAL.md` after
  a `git mv`; this errors because the path is already gone from the
  working tree. The implementer dropped the dead path. Plan defect.
- Task 4: the plan's per-step instructions enumerated only the
  carrier-contract row, but the plan's Step 6 verification clause
  (`grep -n "task_text\b" → empty`) required visiting every body-prose
  mention of `task_text` too. The implementer correctly expanded
  scope to satisfy the verification; rewrites preserved semantics.
- Task 6: the plan's Step 1 verbatim content is 194 lines; Step 2's
  sanity check expected 110–160. Step 1 is canonical; the sanity
  range was my optimistic estimate when writing the plan. The
  implementer correctly followed Step 1.
- Task 7: the plan's Step 3 grep expected 1 match for
  `ailang-implement-orchestrator`, but the new exception paragraph
  itself names the agent, so the actual count is 2. Same shape of
  plan-template error.

None of these affect correctness; all are notes for the next plan
template revision.

## Known debt

- Two bare `JOURNAL` uppercase mentions remain in `CLAUDE.md` at
  lines 285/287 (the "answer three questions" closing paragraph).
  They refer conceptually to the historical log, but the surface
  reading is slightly stale now that JOURNAL is no longer a file.
  Out of scope for Task 2's enumerated sites; carry-on observation.
- "Boss" / "Boss-Orchestrator" vocabulary is introduced in the new
  `skills/implement/SKILL.md` and `ailang-implement-orchestrator.md`
  to distinguish from "the orchestrator-agent". `CLAUDE.md` uses
  "orchestrator" throughout. The distinction is intentional, but a
  one-line glossary entry in `CLAUDE.md` would prevent term drift
  in future docs.
- Verification ladder steps 1–5 (real-orchestrator-agent dispatch
  exercise) are deferred to the first real `/implement` run after
  this iter merges. Steps 6–8 (intentional-BLOCKED, intentional
  re-loop, manual Boss-merge replay) get checked off when those
  failure modes arise organically.

## Blocked detail

N/A — DONE.

## Commits

`1891030..92e39bb` (11 commits including 4 quality-review-fix
follow-ups; the per-task pattern was DONE/DONE-WITH-CONCERNS →
spec-reviewer compliant → quality-reviewer approved-or-fixed-then-
approved, per the implement skill's two-stage review).

## Stats

Not produced this iter — `bench/orchestrator-stats/` is a new
artefact introduced by the orchestrator-agent (Phase 5 of its
process). This iter was executed in pre-refactor mode by the Boss
directly, so no stats file exists. The first stats file will be
written by the orchestrator-agent on the next real `/implement` run.

## Audit / milestone close

Audit ran post-iter (skill-system mandatory at milestone close).

- **Architect drift review:** `drift_found`. Live docs and a handful
  of concept-noun sites still mentioned `JOURNAL.md` as if it were a
  current path. Highest-impact misses were `docs/WhatsNew.md` (live
  changelog framing-text — wrongly carved out of the Task 3 plan as
  "dated artifact"), `docs/roadmap.md` lines 25-27 (live convention
  text), and four bare `JOURNAL` mentions in `CLAUDE.md` (lines 108,
  267, 285, 287). Five concept-noun spots in
  `skills/audit/agents/ailang-architect.md` (Iron Law line 100 was
  already correct; the others were process descriptions). All
  resolved inline via `iter or.1.tidy` (single commit, four files).
  Spec-vs-shipped divergences (the spec still prescribes the invalid
  `git rebase ... onto main` and lists 3 blocked reasons where the
  agent ships 5) were intentionally left as-is — specs are dated
  artefacts capturing design at time of writing; the per-iter journal
  is the running annotation.
- **Bench-regression check:** `bench/check.py` 63 metrics stable
  (exit 0); `bench/compile_check.py` 24 metrics stable (exit 0);
  `bench/cross_lang.py` 25 metrics stable (exit 0). No language code
  changed; the green result was expected and confirms it.
- **Rustdoc:** 18 pre-existing warnings (2 in `ailang-core`, 16 in
  `ailang-check`) about private-item links and unresolved cross-refs.
  None caused by this iter. Deferred to a future docwriter sweep.

Milestone close: clean after `or.1.tidy`. Three roadmap follow-ups
worth noting:
- WhatsNew.md should NOT be carved out as "dated artifact" in any
  future doc-sweep plan; it is a live changelog.
- A separate docwriter sweep for the 18 pre-existing rustdoc warnings.
- Once a real `/implement` run goes through the new orchestrator-agent,
  ladders 1–5 of the verification ladder in `docs/specs/
  2026-05-11-implement-orchestrator-agent.md` are checked off.
