152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# 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.
|