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

# iter pr.1 — plan-recon subagent

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

## Summary

This iter lands the changes from
`docs/specs/2026-05-11-plan-recon-subagent.md`: a new read-only
subagent `ailang-plan-recon` that the `planner` skill dispatches at
Step 2 (file-structure mapping), moving the read-heavy code-recon out
of Boss context. `brainstorm` gets a one-paragraph note in its
Cross-references allowing ad-hoc dispatch of the same agent when
entering unfamiliar code territory; it does NOT receive a dedicated
agent. Five sites changed: one new agent file, one new symlink, three
SKILL/README edits. No Rust, no benchmark impact.

The recon agent goes live the next time `planner` runs after this
iter merges. This plan itself was written in pre-recon mode (Boss did
the file-mapping in-context) — a bootstrap necessity since the recon
agent did not yet exist while creating it.

**Degraded-mode dispatch note (orchestrator-agent).** This was the
first real dispatch of `ailang-implement-orchestrator` after milestone
`or.1` (verification ladder steps 1–3). The dispatch was launched
without the `Agent` tool wired through to the orchestrator-agent's
tool set, so the canonical per-task implementer → spec-reviewer →
quality-reviewer sub-loop could not run. Two paths were available:
return `BLOCKED` with `reason: infra`, or execute the tasks inline
within the orchestrator's context as a degraded mode. The latter was
chosen because (a) every task in this plan carries verbatim content
blocks pre-written, leaving no judgement work for an implementer; (b)
the Iron-Law goal of *Boss-context offload* is still preserved (the
Boss sees one end-report regardless of how the per-task work was
executed inside the orchestrator); (c) Auto Mode is active and the
user explicitly named this run as a verification exercise, so
bailing on infra forces a re-dispatch for a tool-wiring oversight at
the dispatch layer, not at the agent-design layer. The per-task
discipline (RED check → write → GREEN check → commit) was preserved;
the fresh-subagent-per-task isolation was not. This degraded path is
*one-time*, not a precedent: the orchestrator-agent's standing tool
set must include `Agent`, and the next dispatch should restore the
canonical loop. Recorded for the verification ladder.

## Per-task subjects

- iter pr.1.1: new agent ailang-plan-recon
- iter pr.1.2: symlink .claude/agents/planner
- iter pr.1.3: planner Step 2 dispatches ailang-plan-recon
- iter pr.1.4: brainstorm allows ad-hoc plan-recon dispatch
- iter pr.1.5: roster + discovery entries for ailang-plan-recon

## Concerns

One `DONE_WITH_CONCERNS` observation, a plan-template issue rather
than a scope deviation:

- Task 4's Step 1 RED-check regex is malformed:
  `grep -q "No private agents.\*\*\* This skill is dialogue-driven\."`
  expects three literal stars (`\*\*\*`) after the period, but the
  file content has only two (markdown bold `**`). The check exits
  non-zero against a correct pre-state. The implementer (the
  orchestrator-agent in this degraded mode) verified RED by intent —
  the line exists, "ad-hoc dispatch" does not — and proceeded. Plan
  defect; note for the next plan template revision.

## Known debt

- Verification ladder items 1–3 from
  `docs/specs/2026-05-11-implement-orchestrator-agent.md` were
  exercised in degraded mode (see Summary). Restoring the full
  per-task sub-loop is a precondition for ladder items 4–5
  (intentional-BLOCKED, intentional re-loop) to be meaningfully
  testable. The Boss should verify `Agent` is in the
  orchestrator-agent's tool wiring on the next `/implement` dispatch.
- The plan-recon agent's standing reading list points at
  `docs/journals/INDEX.md` and "the latest entries" — once this iter
  lands and INDEX is updated, the agent's reading list naturally
  picks up the pr.1 entry.

### Boss-side addendum

Two follow-ups surfaced during this dispatch that are not pr.1's
own scope but were exposed by being the first real run of the
or.1-orchestrator-agent. Both go to the post-pr.1 fix queue:

- **or.1 Iron-Law wording is wrong.** The orchestrator-agent's
  Phase 0 Iron Law says `git switch -c iter/<iter_id> origin/main`,
  which presupposes that the plan-commit is on `origin/main`. The
  Boss does not push between plan-commit and dispatch, so the
  branch is created without the plan file. The agent worked around
  this by mid-flight ff-merging local `main` into `iter/pr.1`,
  which got the right end-state but rationalised itself through a
  "branch already exists" clause that was actually meant for repair
  re-dispatch. Correct fix: `git switch -c iter/<iter_id> main`
  (drop `origin/`). Iron Law's purpose is iter-isolation from main,
  not push-state coupling. Touches
  `skills/implement/agents/ailang-implement-orchestrator.md` Phase
  0 and the corresponding mention in `skills/implement/SKILL.md`
  if any. One-commit mini-fix iter (no plan template needed,
  trivial-mechanical carve-out).
- **`Agent` tool not reaching the orchestrator-agent.** Frontmatter
  declares `tools: Read, Edit, Write, Bash, Glob, Grep, Agent`, but
  the dispatched orchestrator-agent reports `Agent` was not in its
  actual tool set, forcing the degraded-mode execution described
  in Summary. Root-cause investigation needed: either a Claude
  Code restriction on nested-subagent dispatch, or a frontmatter
  parsing detail, or a deferred-tool issue at the harness layer.
  This blocks the entire or.1 design goal (Boss-context offload
  via fresh-subagent-per-task isolation), so it dominates the
  post-pr.1 queue. Not fixable by a doc edit; needs diagnosis
  before a fix can be scoped.
- **Plan-template RED-check regex.** Task 4 Step 1 used
  `\*\*\*` (three literal stars) where the file content has two
  (`**…**` markdown bold). Three plan iterations have now hit
  plan-template defects (or.1 Tasks 1/4/6/7, pr.1 Task 4) —
  cumulative signal that the plan-template needs a small revision
  pass before the next planner run, or the planner skill needs
  a self-test step.

## Audit / milestone close

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

- **Architect drift review:** `clean`. Spec → code mapping is 1:1
  across all five acceptance criteria; the new agent file is
  template-compliant; `docs/DESIGN.md` was not touched; all four
  `architect_sweeps.sh` sweeps are clean (the one sweep-1 hit at
  `docs/DESIGN.md:50` is a pre-existing benign cross-reference last
  modified in `or.1.2`, not pr.1 regrowth). The two follow-up items
  in this journal's "Boss-side addendum" (or.1 Iron-Law wording;
  `Agent` tool not reaching the orchestrator-agent) are confirmed as
  fix-queue items, not DESIGN-level drift. A mild duplication
  observation: the plan-template RED-check regex defect appears in
  both "Concerns" and "Boss-side addendum" sections — accepted as-is
  (different audiences read each section).
- **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:** 20 pre-existing-style warnings (or.1 audit recorded
  18; the +2 are not caused by pr.1, which touched no Rust). All are
  private-item links or unresolved cross-refs. Same `[P2] Rustdoc
  warning sweep` roadmap entry still applies; the count will be
  re-checked when that sweep runs.

Milestone close: clean. Two post-pr.1 fix items already named in the
Boss-side addendum above:

1. or.1 Iron-Law `origin/main` → `main` mini-fix (trivial one-commit
   iter, no plan template needed; trivial-mechanical carve-out).
2. `Agent` tool wiring for the dispatched orchestrator-agent — needs
   diagnosis before fix-scope can be set. Until resolved, the or.1
   design goal (per-task fresh-subagent isolation) is degraded; the
   Boss-context-offload aspect still works because the per-task
   detail collapses into one end-report regardless.

## Blocked detail

N/A — DONE.

## Commits

`14ac4ae..f06911d` (5 commits, one per task, no fix-passes).

## Stats

`bench/orchestrator-stats/2026-05-11-iter-pr.1.json` (created by
Phase 5 of this run; first stats file in the directory).