@event4u/agent-config 14.20.0 → 14.21.0

package/dist/agent-src/commands/analyze/{reference-repo.md → repo.md}

@@ -1,13 +1,20 @@
 ---
 model_tier: high
-name: analyze-reference-repo
+name: analyze-repo
 pack: analysis-workbench
 visibility: internal
-sub: reference-repo
+sub: repo
 cluster: analyze
+replaces: [analyze-reference-repo, analyze:reference-repo]
 skills: [project-analyzer, learning-to-rule-or-skill]
 description: Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project.
-argument-hint: "<repo-url | owner/repo | archive-url> [--focus=<area>] [--deep] [--no-roadmap]"
+argument-hint: "<repo-url|owner/repo|archive> [--mode=plan|execute] [--loops=N] [--focus=<area>] [--deep] [--refresh] [--no-roadmap]"
+limits:
+  mode_default: plan
+  max_iterations: 3
+  hard_ceiling: 5
+  no_gain_stop: 2
+  target_metric: required
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -17,7 +24,7 @@ packs:
   - meta
 ---
 
-# analyze-reference-repo
+# analyze-repo
 
 Analyze a **different** repository (a competitor, a reference implementation, or
 a project the user admires) and produce a structured document that anchors on
@@ -35,26 +42,83 @@ The user provides a repository URL — a full GitHub URL
 
 Optional arguments:
 
+- `--mode=plan|execute` — `plan` is the **default** (§ Enforced limits).
+- `--loops=N` — refinement-loop budget. **Default: 3**; hard ceiling 5.
 - `--focus=<area>` — restrict analysis to one axis (e.g. `installer`,
   `skills`, `mcp`, `governance`, `ci`). Default: full-surface.
+- `--refresh` — re-resolve the reference's head revision (§ 2a). Without it a
+  re-run reads the revision already pinned in the local manifest.
 - `--deep` — bounded deep-verification tier (§ 2b). Read-only clone at a pinned
   SHA, never executed. Requires a non-empty anchor table.
 - `--no-roadmap` — skip the roadmap-draft step.
 
+## Enforced limits
+
+The frontmatter `limits:` block is the machine-readable pin
+(`tests/scripts/analyze_repo_limits.test.ts` fails when flow and pin drift);
+the steps below are the enforcement — each limit is a step the run MUST
+execute, not advice.
+
+### Execution mode — plan-only default (`mode_default: plan`)
+
+`--mode=plan` is the **default**: run §§ 1-6 — pin, fetch, extract, probe,
+compare, classify, converge, write the local artifacts — then present the
+result and STOP. No roadmap landing, no ledger rows, no tracked write of any
+kind. `--mode=execute` must be **explicitly present in the invocation** to
+reach §§ 7-8; treat its absence as plan mode even when conversation momentum
+suggests otherwise. Execute mode does not remove the per-write confirmations in
+§§ 7-8 — it only makes them reachable.
+
+### Pre-registered target metric — required before loop 1 (`target_metric: required`)
+
+Before loop 1 may run, the analysis document MUST carry a `Target metric` line
+naming the metric of § 5c, its **measured baseline** taken from the seed pass,
+and the predicted direction. No baseline → REFUSE to enter loop 1 with:
+`target metric not pre-registered — record the seed-pass baseline first`. The
+metric named before loop 1 is the metric every loop is scored against; loops
+never move the goalposts.
+
+### Loop budget (`max_iterations: 3`, `hard_ceiling: 5`)
+
+`--loops=N` caps the refinement loops. **Default: 3** — one loop per lens
+(§ 5b), which is what makes three the budget rather than a round number.
+Hard ceiling: 5 — a larger `--loops` value is clamped to 5 with a warning.
+
+**Halt-on-spin tripwire (`no_gain_stop: 2`), checked after every loop and
+overriding the budget:**
+
+- **Two consecutive zero-delta loops → STOP** before the next lens runs, and
+  say which two loops produced no delta and on which metric. Spinning without
+  gain is the failure the metric exists to catch.
+- A verdict table still contested at the ceiling stops the run with a
+  maintainer question (§ 5b) — never silently.
+- A single zero-delta loop **never** cancels the remaining lenses. It is a
+  signal about that lens, not a prediction about the next one.
+
+### Read ceiling per loop
+
+Loop *n* cannot read deeper than the seed pass without a local clone, so
+`--deep` (§ 2b) becomes the **default whenever the loop runs**. The three-part
+read ceiling of § 2b applies per loop, and the loop that hits it logs one
+read-ceiling line naming the bound that fired.
+
 ## Steps
 
-### 1. Confirm scope
+### 1. Resolve scope from the invocation — do not ask
 
-Before touching anything, ask:
+Scope comes from the arguments, never from a prompt. A bare repository argument
+means **full scope**; `--focus=<area>` means focused. **Ask nothing before the
+first fetch.** The four-option menu this step used to open with cost one prompt
+per repository in a batch, which is a prompt the invocation had already
+answered.
 
-> Found reference: `<owner/repo>`.
->
-> 1. Full comparison — all axes (default)
-> 2. Focused — one axis (I'll ask which)
-> 3. Quick scan — README + top-level layout only
-> 4. Cancel
+The one question that survives is an **unresolvable repository identity** — the
+argument matches no repository, or matches more than one. That is a genuine
+ambiguity the invocation did not settle, and it halts before any fetch.
 
-Wait for the user's choice.
+Everything the menu's "Cancel" option protected is protected elsewhere: the
+write-acts of §§ 7-8 keep their own confirmations, and plan mode (§ Enforced
+limits) is the default, so a run that is never confirmed writes nothing tracked.
 
 ### 1b. Anchor table first
 
@@ -81,6 +145,26 @@ Use `web-fetch` for rendered files, GitHub REST (`/repos/{o}/{r}/contents/{p}`)
 for listings. **Max 40 fetches** — if more is needed, ask which subtree to
 expand.
 
+### 2a. Pin the upstream revision — once, before any reasoning
+
+The **seed pass** resolves the reference's head revision exactly once and
+records it in the local manifest (§ 6). Every loop of § 5b reads **that same
+revision**. Only `--refresh` re-resolves it.
+
+Why once: a loop that re-resolves is comparing two different repositories and
+calling the difference a finding. Convergence over a moving target is not
+convergence, and a delta produced by an upstream commit that landed between
+loop 1 and loop 2 is upstream's news, not this analysis's.
+
+Record in the iteration record, once per pass: `revision: <sha>` — the **same**
+value on every pass of a run. A pass whose recorded revision differs from the
+seed pass's is a defect in the run, not a finding about the reference.
+
+Because loop *n* cannot read deeper than the seed pass without a local clone,
+`--deep` (§ 2b) is the default whenever the loop runs. Each loop that hits the
+§ 2b three-part read ceiling logs **one** read-ceiling line naming the bound
+that fired and the loop it fired in.
+
 ### 2b. Deep verification tier — `--deep`, opt-in
 
 Forty top-level fetches cannot reach a fact buried in an implementation file, so
@@ -179,38 +263,111 @@ mentions a ledger word — a check that mostly fires wrongly gets waved through.
 A **checklist obligation**, not a CI gate: `check_claims` guards the ledger's
 integrity, never a proposal against it.
 
-### 5b. Converge the verdict table
+### 5b. Three loops, three different questions
+
+One pass is a draft, not an analysis — but three passes asking the same
+question are three rewordings, which costs three times the fetches and produces
+prose churn. So the loops are **not** repetitions of one critique. Each has its
+own lens, and the lens is what makes the loop worth its cost:
+
+| Loop | Lens | The question it asks, and only it |
+|---|---|---|
+| 1 | **Coverage** | What was missed? What was wrongly marked absent? Which rows rest on a weak anchor — no `file:line`, or one that no longer resolves? |
+| 2 | **Adversary** | Was the *form* copied instead of the principle? Is this only *different* rather than *better*? Does this package already solve it elsewhere? What does it cost in tokens, surface and maintenance? |
+| 3 | **Convergence** | Resolve contradictions between the first two. Fold duplicates. Cut the speculative. Bind every remaining line to evidence on **both** sides. |
+
+Each loop takes as input **both** the previous analysis **and** the previous
+roadmap draft — a finding that changed the analysis but not the roadmap is a
+finding the run has not finished acting on.
+
+Each loop appends its own **delta block** to `## Iteration record`, naming its
+lens, with one row per change and a reason per row:
+
+```markdown
+### Loop {n} — {Coverage | Adversary | Convergence}   ·   revision: {sha}
+
+| Change | Row | From → To | Reason |
+|---|---|---|---|
+| added / removed / flipped / folded | … | … | … |
+```
 
-One pass is a draft, not an analysis. Critique the verdict table at least
-**twice**: pass 2 applies solution-minimalism and the § 5 bound-claim gate to
-pass 1's ADOPT rows, using the § 3b probe findings as input. Record every flip
-with its reason in `## Iteration record`. **DONE** = a pass produces **zero**
-verdict changes. Cap at four passes; a table still flipping at four is itself
-the finding — mark it `contested — needs maintainer judgement`, never stop
+**A loop whose delta block has no added, removed, flipped or folded entry is
+recorded as a zero-delta loop, never omitted.** An omitted block is
+indistinguishable from a loop that never ran, and the halt rule below counts
+zero-delta loops — so omitting one silently disarms the tripwire.
+
+A verdict table still contested at the ceiling is itself the finding — mark it
+`contested — needs maintainer judgement` and stop with the question, never
 silently.
 
+### 5c. The target metric is a decision-quality measure
+
+The metric is:
+
+> the count of ADOPT/ADAPT rows carrying a concrete `file:line` on **both** the
+> reference side and this package's side.
+
+Not the number of rows, not the length of the document, not the count of
+findings. An output-volume metric rewards a loop for saying more, which is
+precisely the churn the three lenses exist to prevent; this metric only moves
+when a verdict became *decidable* — someone can now go and look at both ends.
+
+Its baseline is measured on the seed pass and pre-registered before loop 1
+(§ Enforced limits). The halt rules that read it:
+
+- **Two consecutive zero-delta loops → STOP** before the next lens runs, naming
+  the two loops and the metric. Spin, not convergence.
+- **A single zero-delta loop never cancels the remaining lenses.** Loop 1
+  finding nothing to add on Coverage says nothing about whether the Adversary
+  lens will find something to remove — the lenses ask different questions, so
+  one lens's silence is not evidence about the next.
+- A contested table stops the run with a maintainer question (§ 5b).
+
 A contested table is a **published finding, not an adoption proposal**: the
 reference surface holds elements this repo cannot mechanically classify, and no
 automation converts that into an ADOPT decision. Convergence is an analyst
 obligation with a recorded trail — **never an LLM-as-judge gate**, never a
 script.
 
-### 6. Write the analysis document
+### 6. Write the analysis document — under the opaque id, in the local area
+
+**Target: `agents/.harvest-local/repo/<opaque-id>/analysis.md`.** Every pass and
+loop artifact of a run lives under that one directory, and the run writes
+nothing under `agents/evidence/analysis/`.
+
+The old target was `agents/evidence/analysis/compare-<slug>.md` with
+`<slug>` = `<owner>-<repo>`, which put the reference's identity into a path.
+`.gitignore` covers `compare-*.md` under the evidence directory but nothing
+else there, so any other filename in that directory would have been unprotected
+by construction — the protection was a glob, not a boundary.
+`agents/.harvest-local/` is a whole gitignored directory, so the boundary is the
+directory rather than a pattern one rename defeats.
+
+**The opaque id.** Derived by
+`./scripts-run src/scripts/harvest_reference_tokens` from the canonical
+repository identity **and** the pinned revision of § 2a: `sha256(identity +
+"@" + revision)`, first 16 hex characters. Two consequences that are the point
+of including the revision: the id is **stable** across two runs at the same
+revision, so a resumed or repeated run lands in the same directory; and it
+**differs** across revisions, so one repository at two historical pins is two
+pieces of evidence rather than one overwriting the other.
+
+**The plaintext lives in exactly one place** — `identity` in the local
+manifest, `agents/.harvest-local/manifest.jsonl`, inside the same gitignored
+directory. Nothing else in the run resolves an opaque id back to a name.
 
-Target: `agents/evidence/analysis/compare-<slug>.md` (create the directory if
-missing, with `.gitkeep` — same convention as `project-analyzer`). Slug rule:
-`<owner>-<repo>` lowercased, non-alphanumeric → `-`, collapse runs. Structure:
+Structure:
 
 ```markdown
 # Reference analysis: {owner}/{repo}
 
 > One-sentence framing of why this reference matters.
 
-- **Source:** https://github.com/{owner}/{repo}
+- **Source:** `opaque:{opaque-id}` — resolvable only via the local manifest
 - **Fetched commit:** {sha} ({date})
 - **Own-tree SHA:** {sha}
 - **Focus:** {full | area}  ·  **Depth:** {surface | deep}
-- **Analyst:** agent via `/analyze-reference-repo`
+- **Analyst:** agent via `/analyze-repo`
 
 ## Anchor table
 
@@ -231,9 +388,31 @@ missing, with `.gitkeep` — same convention as `project-analyzer`). Slug rule:
 | Artifact | Our consumer (file:line) | Discovered? | Validates? | Exact failing axes or error |
 |---|---|---|---|---|
 
+## Target metric
+
+- **Metric:** ADOPT/ADAPT rows with a `file:line` on both sides (§ 5c)
+- **Seed-pass baseline:** {n}   ·   **Predicted direction:** up
+
 ## Iteration record
 
-| Pass | Row | From → To | Reason |
+`revision: {sha}` — the § 2a pin, identical on every pass below.
+
+One delta block per loop, in order, each naming its lens. A zero-delta loop
+keeps its block and records the zero (§ 5b).
+
+### Loop 1 — Coverage   ·   revision: {sha}
+
+| Change | Row | From → To | Reason |
+|---|---|---|---|
+
+### Loop 2 — Adversary   ·   revision: {sha}
+
+| Change | Row | From → To | Reason |
+|---|---|---|---|
+
+### Loop 3 — Convergence   ·   revision: {sha}
+
+| Change | Row | From → To | Reason |
 |---|---|---|---|
 
 ## Findings
@@ -270,6 +449,9 @@ omit the section entirely when every row extends something that exists.}
   does not fit — a seed that skipped this line is not ready to hand over}
 
 ## Open questions for the maintainer
+{Each line is a question to ask the maintainer directly, one at a time, when
+this report is handed over — the section records what is owed, it does not
+discharge it.}
 ```
 
 The `## Seeds` section is the handoff shape
@@ -282,19 +464,52 @@ it makes the four-surface overlap scan that
 requires visible at handoff time, when the analysis is still open, instead of
 re-derived later by whoever picks the seed up.
 
-### 7. Offer next steps
+### 7. Offer next steps — execute mode only
 
-After writing the file, present:
+**Plan mode stops here** (§ Enforced limits). `--mode=execute` makes this step
+reachable; it does not make it automatic.
 
-> Analysis written to `agents/evidence/analysis/compare-{slug}.md`.
+> Analysis written to `agents/.harvest-local/repo/{opaque-id}/analysis.md`.
 >
-> 1. Draft roadmap from ADOPT/ADAPT — `agents/roadmaps/adopt-{slug}.md`
+> 1. Draft roadmap from ADOPT/ADAPT — `agents/roadmaps/road-to-{defect}.md`
 > 2. Merge findings into an existing roadmap — say which
 > 3. Stop here
 > 4. Deep-dive on one axis — say which
 
 Never create the roadmap without explicit confirmation.
 
+#### The landed roadmap is named after the defect, never after the source
+
+A tracked filename is a published string. `adopt-{owner}-{repo}.md` publishes
+the reference's identity in the one surface no `.gitignore` can retract, and it
+also names the wrong thing: the roadmap exists because **this package has a
+gap**, not because some other project exists.
+
+- **Filename:** derived from the capability gap —
+  `agents/roadmaps/road-to-<the-thing-we-lack>.md`. It contains neither the
+  owner nor the repository name. If the only name you can think of is the
+  reference's, the finding is not yet understood well enough to land.
+- **Header:** carries a provenance block with an **encrypted token**
+  (`ENC1:` via `src/scripts/_lib/link_crypto.ts`), never the plaintext URL —
+  the form
+  [`source-confidentiality`](../../../../rules/source-confidentiality.md)
+  requires of a tracked roadmap that cites a source. Sources are referenced as
+  *Source A / B / C* in the prose.
+- **Verified by:** `./scripts-run src/scripts/check_no_external_sources`, which
+  is the deterministic backstop rather than the discipline itself.
+
+#### Never hand a subagent a plaintext URL
+
+Under the harvester (`/analyze:roadmap-repos`) the orchestrator passes the
+subagent **the opaque id and nothing else**. The subagent reads the URL from the
+local manifest itself, so the plaintext never appears in a dispatch argument.
+
+The cost is one indirection, and it is taken **on precaution**: whether a given
+host retains a subagent's arguments in a transcript or audit log is
+host-dependent and was not verifiable from this tree. That is stated rather than
+asserted away — the indirection is cheap enough not to need a proven threat, and
+claiming a proven one would be a claim this package cannot support.
+
 ### 8. Close the loop — offer the ledger rows
 
 **Only after a roadmap draft is accepted** (option 1 or 2 above). This step
@@ -313,7 +528,7 @@ One row per **anchored ADOPT or ADAPT** finding, and nothing else:
 |---|---|
 | `harvest_id` | a kebab-case slug for the mechanism |
 | `stated_in` | the roadmap file the user just accepted |
-| `source_ref` | the reference's `<url>@<sha>` — the § 2 pin, already recorded in the document header |
+| `source_ref` | `opaque:<id>` or an `ENC1:` token — never the plaintext URL; the § 2a pin is inside the id |
 | `evidence_locator` | the reference-side `file:line` from that row of the comparison matrix |
 | `harvested_at` | today |
 | `verdict` | `adopt` or `adapt` |

package/dist/agent-src/commands/analyze/roadmap-repos.md

@@ -0,0 +1,129 @@
+---
+model_tier: medium
+name: analyze-roadmap-repos
+pack: analysis-workbench
+visibility: internal
+sub: roadmap-repos
+cluster: analyze
+type: orchestrator
+replaces: []
+skills: [subagent-orchestration]
+description: Walk the roadmap estate's encrypted reference tokens and feed each unique repository through analyze-repo, one subagent at a time, without producing one roadmap per repository.
+argument-hint: "[--limit=N] [--resume] [--refresh] [--mode=plan|execute]"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# analyze-roadmap-repos
+
+The thin harvester in front of [`analyze-repo`](repo.md). It walks the roadmap
+estate's encrypted reference tokens, resolves each to a repository identity, and
+feeds the unique ones through the analysis command one at a time.
+
+**This command contains no analysis instruction and never will.** It resolves,
+dispatches, and folds. Every judgement about a reference — what to fetch, what
+to compare, what to adopt, how to converge — belongs to `analyze-repo`, which
+owns the loop contract and its limits. A second copy of that reasoning here
+would be a second implementation to keep in step with the first, which is the
+condition step 1.1 of its roadmap removed.
+
+## Steps
+
+### 1. Discovery — run the script, read the manifest
+
+```bash
+./scripts-run src/scripts/harvest_reference_tokens --dry-run          # census only
+./scripts-run src/scripts/harvest_reference_tokens --resume --limit=N # write the manifest
+```
+
+The script is the only discovery mechanism: it extracts the `ENC1:` tokens
+across the five estate levels, decrypts them, classifies each resolved URL,
+canonicalizes the repositories, deduplicates on identity plus pinned revision,
+and writes `agents/.harvest-local/manifest.jsonl`.
+
+It **refuses without a link-encryption key** rather than reporting a short
+census — a classification of zero repositories that actually means "nobody could
+look" is the failure mode this whole pass exists to avoid.
+
+Read the manifest. Do not re-derive any of it here.
+
+### 2. Dispatch — one subagent per repository, sequential
+
+For each manifest entry with status `pending`, in manifest order, up to the
+batch limit:
+
+- Spawn **one subagent** and have it run `/analyze:repo` for that entry.
+- Pass the subagent **the opaque id only** — never a resolved URL. The subagent
+  reads the URL from `agents/.harvest-local/manifest.jsonl` itself. One
+  indirection, taken on precaution (`analyze-repo` § 7).
+- **Sequential, never a fan-out.** Over a hundred identities at four passes each
+  cannot share one session, and every external fetch is spent deliberately. The
+  manifest is the only shared state between subagents.
+- Write the entry's status back as the run progresses: `running`, then `done` or
+  `failed`. A batch interrupted mid-flight resumes from those statuses.
+
+Default batch limit is **small**. A harvester that walks the whole estate in one
+invocation spends a hundred repositories' worth of fetches on a decision nobody
+took.
+
+### 3. Ownership fold — one gap, one roadmap
+
+After the batch, and never during it, run the fold pass of
+[`analyze-repo`](repo.md) § 7 across the batch's findings as a set. Consult
+`src/scripts/roadmap_context.ts` and the run's own candidate registry, then pick
+exactly one disposition per repository:
+
+| Disposition | When |
+|---|---|
+| no action | the finding is REJECT or ALREADY throughout |
+| already planned | an active roadmap already owns the gap |
+| extend an existing roadmap | the gap belongs to an owner that exists |
+| create a follow-up | the gap belongs under an owner but is out of its scope |
+| create new | no owner exists |
+| contested | two owners claim it — stop and ask |
+
+**Three repositories showing the same gap strengthen the evidence on one owning
+roadmap. They never create three.** That is the whole reason this command exists
+rather than a loop that invokes `analyze-repo` and keeps whatever it returns.
+
+### 4. Landing — local-only
+
+The batch's consolidated result is written to `agents/.harvest-local/` and
+nowhere else. **No per-run consolidate roadmap takes an active top-level estate
+slot** — decided 2026-09-06 under the maintainer's standing delegation, recorded
+in `road-to-bounded-reference-harvest-loop` § Blockers. A recurring process that
+takes a slot per run converts the estate ratchet's allowance into a standing
+exemption, which removes the pressure the ratchet exists to apply.
+
+Accepted consequence, stated rather than hidden: **no batch is visible in the
+roadmap dashboard.** Any roadmap the fold pass does land is an ordinary estate
+entry landed for a named capability gap, and is subject to the estate gate like
+any other.
+
+## Safety
+
+- Read-only on every reference. The no-execute invariant of `analyze-repo`
+  § Safety binds every subagent this command spawns.
+- No plaintext repository URL is ever passed as a dispatch argument.
+- Nothing tracked is written by this command itself.
+- Hard-Floor actions stay this-turn gated. A batch authorizes fetches, never a
+  commit, a push or a merge.
+
+## When **not** to use
+
+- One known reference → [`analyze-repo`](repo.md) directly. The harvester's only
+  job is the estate walk.
+- Analyzing this repository → `/project-analyze`.
+- A dropped local artifact → [`/analyze:inbox`](inbox.md).
+
+## Related
+
+- Command: [`analyze-repo`](repo.md) — the analysis engine this dispatches to.
+- Script: `src/scripts/harvest_reference_tokens.ts` — discovery, the only one.
+- Rule: [`source-confidentiality`](../../../../rules/source-confidentiality.md)
+  — why the identities stay in the gitignored area.

package/dist/agent-src/commands/analyze.md

@@ -2,13 +2,13 @@
 model_tier: medium
 name: analyze
 disable-model-invocation: true
-argument-hint: "[postmortem|premortem|decision|near-miss|incident|reference-repo|inbox] [subject]"
+argument-hint: "[postmortem|premortem|decision|near-miss|incident|repo|roadmap-repos|inbox] [subject]"
 pack: analysis-workbench
 intent: "Analysis dispatcher — classify input by keywords, propose a weighted framework path, let the user pick"
-routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-reference-repo, analyze-inbox, analyze-conformance]
+routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-repo, analyze-roadmap-repos, analyze-inbox, analyze-conformance]
 replaces: []
 visibility: advanced
-description: Analysis orchestrator — confidence-weighted suggester that routes to postmortem, premortem, decision-review, near-miss, incident, reference-repo, or inbox-artifact analysis.
+description: Analysis orchestrator — confidence-weighted suggester that routes to postmortem, premortem, decision-review, near-miss, incident, repo, or inbox-artifact analysis.
 cluster: analyze
 type: orchestrator
 suggestion:
@@ -37,7 +37,8 @@ to the chosen sub-command. Never auto-selects silently.
 | `/analyze:decision` | `analyze/decision/command.md` | Audit a past architectural decision (did it hold?) |
 | `/analyze:near-miss` | `analyze/near-miss/command.md` | Post-mortem for a near-miss (same flow, lighter severity framing) |
 | `/analyze:incident` | `analyze/incident/command.md` | Full incident flow: commander → RCA → post-mortem → memory candidate |
-| `/analyze:reference-repo` | `analyze/reference-repo/command.md` | Deep-dive an external reference repo (competitor, inspiration, peer) → structured comparison + adoption plan |
+| `/analyze:repo` | `analyze/repo/command.md` | Deep-dive an external reference repo (competitor, inspiration, peer) → structured comparison + adoption plan |
+| `/analyze:roadmap-repos` | `analyze/roadmap-repos/command.md` | Walk the estate's encrypted reference tokens and feed each unique repo through `repo`, one subagent at a time |
 | `/analyze:inbox` | `analyze/inbox/command.md` | Deep-dive a LOCAL artifact dropped in `agents/tmp/` (review, prompt, spec, transcript) → claim verification + step reproduction against the current tree + artefact mapping + roadmap |
 | `/analyze:conformance` | `analyze/conformance/command.md` | Audit recent local sessions for rule violations → deterministic scan + subagent passes, root-caused per class, and a roadmap for what is mechanisable |
 
@@ -63,7 +64,7 @@ match:
 | "pre-mortem", "what could go wrong", "imagine failure", "vor dem Start" | `premortem` |
 | "decision review", "ADR", "did this hold up", "rückblick Architektur" | `decision` |
 | "production is down", "active incident", "Vorfall", "Prod ist down" | `incident` |
-| external repo URL / `owner/repo`, "how does X do this", "compare with that repo", "competitor" | `reference-repo` |
+| external repo URL / `owner/repo`, "how does X do this", "compare with that repo", "competitor" | `repo` |
 
 Assign a confidence level (high / medium / low) per framework based on
 signal count. A framework with zero signals gets `low`.
@@ -81,7 +82,7 @@ escape:
 > 3. [low] Pre-mortem (`/analyze:premortem`) — imagined-failure analysis before committing
 > 4. [low] Decision review (`/analyze:decision`) — did a past architectural decision hold up?
 > 5. [low] Incident (`/analyze:incident`) — full live-incident coordination + RCA + post-mortem
-> 6. [low] Reference repo (`/analyze:reference-repo`) — deep-dive an external repo → comparison + adoption plan
+> 6. [low] Reference repo (`/analyze:repo`) — deep-dive an external repo → comparison + adoption plan
 > 7. Describe in your own words — I'll re-classify
 
 **Empfehlung:** 1
@@ -113,7 +114,11 @@ and ask which one was intended. One question, no guessing.
   this turn.
 - **Do NOT commit, push, or open a PR** unless a sub-command
   explicitly authorizes it.
-- **Do NOT chain sub-commands.** One `/analyze <sub>` per turn.
+- **Do NOT chain sub-commands.** One `/analyze <sub>` per turn. **Exactly one
+  exception:** `roadmap-repos` invokes `repo` once per repository, each in its
+  own subagent, sequentially — never in the orchestrator's own turn and never as
+  a fan-out. It is the only sub-command permitted to invoke another, and it may
+  invoke only `repo`.
 - **Memory loop applies** — every sub-command that produces an
   analysis output MUST draft a memory candidate via
   `/memory propose` per