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:

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

7.1 KiB Raw Blame History Unescape Escape