@event4u/agent-config 14.19.0 → 14.21.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-299-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-120-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-203-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-118-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
+[![Skills](https://img.shields.io/badge/Skills-299-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-120-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-204-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-118-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/) <!-- claim:published-artifact-counts -->
 
 <sub>**How these are counted** — one canonical counter, `agent-config` → `update_counts --check`, re-derives all six from the tree and fails CI on a drift of one. Two bases are not what the linked directory shows, so they are stated here rather than left to be inferred: **Commands 202** counts every command file **recursively** (the linked directory holds 61 at its top level), and **Rules 120** counts the **source** rules while the linked projection holds 119 — one rule is dormant and is not projected. **Personas 29** excludes the directory README. Counts are of files and directories: none of them measures quality, activation, or adoption. <!-- claim:published-artifact-counts --></sub>
 

package/agents/templates/.ai-council.yml.example

@@ -393,6 +393,16 @@ members:
 
   gemini:
     enabled: false
+    # HONEST NULL, not a probe result (road-to-admissible-council-seats 1.2).
+    # `council:status` prints this line, so the seat is no longer silently off.
+    disabled_reason: >-
+      honest null 2026-09-07 — the CLI headless contract could not be
+      established: the free tier on the probing machine fails with
+      IneligibleTierError before the run reaches the point where a piped stdin
+      alone would decide it, so whether the gemini CLI stays non-interactive
+      without -p/--prompt is UNKNOWN, not false. The api transport for this
+      provider became live in the same change; this seat stays off until the
+      contract is observed on a machine that can reach it.
     # not-listed: gemini — the `gemini` CLI is installed here and its `--help` exposes only `-m, --model <string>` — no listing subcommand and no documented "latest" alias, so no sentinel could be substituted. An honest null for this provider, not a guess.
     # The pin is therefore stamped as-of the drain date with NO refresh claimed;
     # `verified_at` records when a human last looked, which is the only thing it

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

@@ -8,7 +8,7 @@ replaces: []
 visibility: visible
 skills: [agent-docs-writing]
 description: Pick a recent session, generate a handoff from its transcript, and seed a fresh session with it — or summarize the live conversation for copy-paste.
-argument-hint: "[--print | --file | with tasks]"
+argument-hint: "[--print | with tasks]"
 suggestion:
   eligible: true
   trigger_description: "user asks for an agent handoff, to resume/continue a previous session in a fresh chat, or a context-summary to paste into a new chat"
@@ -114,10 +114,51 @@ Roadmap: {roadmap file if active, or "none"}
 ## Key decisions
 - {important decisions made during this conversation}
 
+## Least confident
+- {the claim in this handoff you are least sure of} — verify: {command or
+  observable state that would confirm or kill it}
+
+## Biggest thing missed
+- {what a reviewer would most likely find that you did not} — verify: {command}
+
+## Breaks in three months because
+- {the assumption most likely to expire, and what expires it} — verify: {command}
+
+## Not done
+- {work inside the stated scope that did not land} — verify: {command}
+
 ## Relevant files
 - {list of files that were edited or are important for context}
 ```
 
+### The four self-critique sections — why every line carries a `verify:`
+
+Every other section states what HAPPENED. None of them says what the outgoing
+session is **least sure of**, which is the one thing the incoming session cannot
+reconstruct and the one thing that decides where it should look first.
+
+Each line in those four sections MUST name the command or observable state that
+would confirm or kill it. An unverifiable line of self-doubt is filler: it reads
+as diligence, costs the next session a read, and cannot be acted on. `none` is
+accepted as the whole body of a section — an honest "nothing here" is an answer
+— and blankness is not, exactly as `## Open questions` already treats the same
+distinction. Nothing enforces either direction: the handoff artifact validator
+that would have was retired with `HANDOFF.md`, so the contract is model-carried
+here.
+
+### Capture, do not chase
+
+A finding surfaced **while writing the handoff** is written down, never fixed in
+the handoff turn. The handoff exists because the session is ending, so a fix
+started there is the least-verified change in the whole run — it lands after the
+verification budget is spent, with no room to prove it.
+
+The destination is a `model-noticed` self-repair record: `upsertFinding` in
+`src/scripts/_lib/self_repair_store.ts`, carrying a `target` from the closed
+`rule: | skill: | command: | hook:` vocabulary so the finding is joined to the
+asset it is about. Put the same finding in `## Not done` with its `verify:`, so
+the next session sees it without having to query the store.
+
 The CLI generator emits the same section set (minus the live-only
 *Repeatable workflow* / *Feedback history* refinements) — the template above
 stays the single source of the section contract.
@@ -150,46 +191,6 @@ block (e.g. *"Copy this into a new chat:"*) and nothing after — no follow-up
 questions, no numbered options. The picker in Step 2 is the one exception:
 it is the flow's single question, asked BEFORE any handoff is generated.
 
-## 2b. File-artifact mode — `HANDOFF.md` (optional, host-neutral)
-
-On `/agent-handoff --file` (or when a workflow skill's phase boundary asks
-for a standing handoff), ALSO write the contract to
-`agents/runtime/state/HANDOFF.md` (gitignored runtime state — plain
-Markdown, no host API). Required fields, in order:
-
-```
-# HANDOFF
-## Mode
-{current workflow mode/phase, e.g. Implement (TDD)}
-## Contract received
-{what the previous phase handed over}
-## Contract owed
-{what the current phase must produce before yielding}
-## Decisions
-- {decision taken, with one-line rationale} {optionally close the line with
-  `[reversible]` or `[irreversible]` — those two spellings exactly}
-## Open questions
-- {unresolved items the next session must not silently drop — each as a
-  question ending in `?`; write `none` when there genuinely are none}
-## Next command
-{the single command or step to run first on resume}
-```
-
-**Resume rule:** a workflow skill's step 0 checks for this file and resumes
-from its contract (mode-inference table) instead of re-deriving state; a
-long phase refreshes the file before yielding. Validated by
-`lint_handoffs.ts` when present — a missing required field is red, and so is an
-`## Open questions` section that answers neither way (blank, or a bare `TBD` /
-`TODO` / `...`). A `?`-terminated question passes; so does an explicit `none` —
-the check exists to stop a blank section reading as an all-clear, not to force a
-question where there is none.
-
-**Critical-planning-file safety protocol** (applies to HANDOFF.md and agent
-roadmap edits): read the current file FIRST; take a timestamped backup copy
-next to it (`HANDOFF.md.<ts>.bak`) before overwrite; duplicate-check before
-appending (never double-append a section); preserve the section structure;
-post-verify the write by re-reading the required fields.
-
 ## Detection — when natural-language triggers count as explicit
 
 The user does not need to type `/agent-handoff` literally. Treat as

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

@@ -22,7 +22,7 @@ packs:
 Turn a file someone dropped in `agents/tmp/` into either a roadmap this repo can
 execute, or a written reason it was dropped.
 
-The sibling [`/analyze:reference-repo`](reference-repo.md) does this for an
+The sibling [`/analyze:repo`](repo.md) does this for an
 **external** repository. This does it for a **local artifact** — a review, a
 prompt, a feature spec, a transcript, a persona, a competitor teardown — and the
 difference matters: an inbox file is a **frozen snapshot of an opinion about a

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.