@tyroneross/build-loop 0.36.0 → 0.43.0

package/README.md

@@ -38,14 +38,16 @@ For the **living, auto-generated diagram** of how the loop actually wires up in
 
 ## Quick start
 
-Install for all three host surfaces on macOS:
+Install the plugin from the marketplace. In Claude Code:
 
-```bash
-npm install -g @tyroneross/build-loop@0.36.0
-build-loop-install --host all
+```text
+/plugin marketplace add tyroneross/build-loop
+/plugin install build-loop@build-loop
 ```
 
-Then, in a Claude Code session inside your project, hand the loop a task:
+In Codex, add the same git marketplace with `/plugin marketplace add` and install `build-loop`. Then **restart the host** so it loads the plugin.
+
+build-loop has **no runtime CLI** — the loop runs *inside* your agent host. The plugin ships the skills, agents, and hooks it drives; there is no `build-loop` binary to run. After restart, in a session inside your project, hand the loop a task:
 
 ```text
 /build-loop:run add billing settings with tests
@@ -55,23 +57,41 @@ What you observe: the agent prints a short status line per phase (`[Phase 1: Ass
 
 You do not pick a mode. `/build-loop:run` auto-routes build, fix, refactor, optimize, research, and test requests to the right path.
 
+### Groundwork exchange
+
+When a project contains `.designdoc/build-request.json` (or sets `GROUNDWORK_BUILD_REQUEST`), Build Loop validates that request against its adjacent canonical `spec.json` before planning. It preserves Groundwork's ordered tasks, dependency graph, acceptance criteria, and external manual actions as the build boundary.
+
+After implementation and verification, Review-G writes `.designdoc/implementation-map.json`. The map binds each reported task, component, contract, or requirement and its repository-local evidence to the original request, Spec, and task digests. Build Loop reports implementation evidence; Groundwork remains the authority for desired state and calculates convergence.
+
+The exchange adapter ships with identical bytes for Claude Code and Codex at `scripts/groundwork_exchange.py`. Run `python3 scripts/groundwork_exchange.py --help` for the validation and emission commands.
+
 ## Install
 
-`build-loop-install` runs the package's helpers from the installed npm package:
+The plugin installs and updates through the host's **native marketplace** — no npm step, no global install, no `sudo`:
+
+```text
+/plugin marketplace add tyroneross/build-loop   # Claude Code or Codex
+/plugin install build-loop@build-loop
+```
+
+The host owns install, versioning, and `/plugin update`. Restart the host to load a freshly installed or updated plugin. On first session build-loop seeds a memory scaffold at `~/.build-loop-memory` (constitution, MEMORY.md, indexes).
 
-- Syncs the Claude Code cache from the package root.
-- Syncs the Codex cache from `plugin-artifacts/codex`, the slim Codex install artifact.
-- Bootstraps the build-loop memory root with public templates.
-- Leaves publishing, GitHub releases, and production deploys to explicit release commands.
+<details>
+<summary>Alternative: npm installer (exact-pin / offline / pre-marketplace hosts)</summary>
 
-For GitHub Packages, authenticate first and point the `@tyroneross` scope at the GitHub registry:
+The legacy `build-loop-install` binary syncs the same files into the host caches manually. Prefer the marketplace above; use this only to pin an exact version or on a host without marketplace support.
 
+<!-- x-release-please-start-version -->
 ```bash
-npm config set @tyroneross:registry https://npm.pkg.github.com
-npm login --scope=@tyroneross --registry=https://npm.pkg.github.com
-npm install -g @tyroneross/build-loop@0.36.0
+npm install -g @tyroneross/build-loop@0.43.0
 build-loop-install --host all
 ```
+<!-- x-release-please-end -->
+
+Global install needs a writable npm prefix. If `npm -g` fails with `EACCES` (Node from the official `.pkg` installer targets root-owned `/usr/local`), avoid the global install entirely with `npx @tyroneross/build-loop build-loop-install --host all`, or set a user prefix: `npm config set prefix ~/.local`.
+
+GitHub Packages is for private/pinned builds only — not needed for the public install. To use it: `npm config set @tyroneross:registry https://npm.pkg.github.com` then `npm login --scope=@tyroneross --registry=https://npm.pkg.github.com`.
+</details>
 
 Installer options:
 
@@ -86,6 +106,37 @@ Installer options:
 | `--dry-run` | Show cache sync actions without writing. |
 | `--json` | Emit one machine-readable result. |
 
+### Confirm it loaded
+
+The plugin has no runtime CLI, so a successful install is not visible from the shell.
+Check inside the host instead. After restarting it, run:
+
+```text
+/build-loop:run what version of build-loop is loaded and where did it load from
+```
+
+A working install answers with a version and a plugin path. If the command is not
+offered at all, the host did not load the plugin — restart it once more, then check
+that `/plugin` lists `build-loop` as installed and enabled.
+
+### Uninstall
+
+```text
+/plugin uninstall build-loop@build-loop     # Claude Code or Codex
+```
+
+Your memory store is deliberately left behind: it lives outside the plugin at
+`~/.build-loop-memory` (or wherever `BUILD_LOOP_MEMORY_ROOT` points), so
+reinstalling keeps every decision, lesson, and retrospective. Delete that directory
+yourself if you want the history gone. Per-project run state lives in each repo's
+gitignored `.build-loop/` and can be removed with the project.
+
+If you used the npm installer, also remove the global package:
+
+```bash
+npm uninstall -g @tyroneross/build-loop
+```
+
 Local development install:
 
 ```bash
@@ -100,7 +151,7 @@ python3 scripts/install_memory.py --ensure-project build-loop
 
 ## Commands
 
-`/build-loop:run` is the only command. Describe the task in plain language — build, fix, refactor, optimize, research, debug, test, root-cause, retrospective, or plan — and the orchestrator classifies intent and routes to the right internal mode. You never pick a mode or a flag.
+`/build-loop:run` is the command you will use. Describe the task in plain language — build, fix, refactor, optimize, research, debug, test, root-cause, retrospective, or plan — and the orchestrator classifies intent and routes to the right internal mode. You never pick a mode or a flag.
 
 ```text
 /build-loop:run add billing settings with tests
@@ -108,28 +159,34 @@ python3 scripts/install_memory.py --ensure-project build-loop
 /build-loop:run reduce API latency                       # routes to the optimize loop
 /build-loop:run compare queue providers                  # routes to research (no commits)
 /build-loop:run self-improve against recent runs         # runs Phase 6 Learn alone
+/build-loop:feedback the plan step skipped my constraint  # files a GitHub issue on build-loop
 ```
 
 Debugging is also auto-invoked by the loop itself on a review failure. The former mode and utility commands (`debug`, `research-run`, `test`, `self-improve`, `debugger*`, `assess`) are now internal, reached by intent rather than as separate commands.
 
+Build Loop includes the Coding Debugger core natively. The loop searches before investigation and stores verified fixes afterward through `bin/build-loop-debugger.js`; both operations use the existing project-local `.claude/memory/` structured store. The standalone debugger package and MCP server are not required.
+
 ## Host surfaces
 
 The repo ships three agent surfaces from one source:
 
 - **Claude Code plugin**: plugin metadata, commands, hooks, and `agents/*.md`.
-- **Codex plugin**: Codex metadata plus a slim public skill entrypoint (`plugin-artifacts/codex/`).
+- **Codex plugin**: Codex metadata plus a slim public skill entrypoint (`codex-skills/build-loop/SKILL.md`), installed from the repository root.
 - **Host-neutral [`AGENTS.md`](AGENTS.md)**: the same loop methodology for any AGENTS.md-aware tool (Copilot, Cursor, and others), with no Claude-specific integration required.
 
-Surface counts in this release: one command (`/build-loop:run`), 44 skills, 28 agents.
+Surface counts in this release: two commands (`/build-loop:run` and `/build-loop:feedback`), 55 skills, 29 agents. Every skill, what it is for, and how an agent reaches it is listed in [`docs/SKILL-INDEX.md`](docs/SKILL-INDEX.md) — generated from the skills' own frontmatter, so it cannot drift from what ships. `scripts/test_readme_surface_claims.py` holds the counts on this line to the same source.
 
 ## Agent start protocol
 
 Start every build-loop repo session by checking Rally for coordination state: peers, claims, handoffs, and soft file conflicts. Rally verifies nothing on its own, so confirm code, package, version, and release truth from git, tests, manifests, registries, or GitHub directly.
 
 ```bash
-rally enter --tool claude_code --json
-rally next --tool claude_code --json
-rally check before-write --tool claude_code --path README.md --strict --json
+BASE_TOOL="${BUILD_LOOP_RALLY_TOOL:-claude_code}" # choose this host family
+RALLY_SESSION_ID="$(python3 scripts/rally_point/actor_identity.py --tool "$BASE_TOOL" --field session-id)"
+RALLY_TOOL="$(python3 scripts/rally_point/actor_identity.py --tool "$BASE_TOOL" --session-id "$RALLY_SESSION_ID")"
+rally enter --tool "$RALLY_TOOL" --session-id "$RALLY_SESSION_ID" --json
+rally next --tool "$RALLY_TOOL" --json
+rally check before-write --tool "$RALLY_TOOL" --path README.md --strict --json
 ```
 
 If the Rally binary is not installed, proceed without it. Full coordination rules: [`references/coordination-rules.md`](references/coordination-rules.md).
@@ -156,7 +213,9 @@ These tables index agent roles. None of them are commands you run directly. Core
 
 Each agent declares a `(segment, tier)` role that resolves to a concrete model at dispatch. Selection runs on two axes: a work-role **segment** (Generative Reasoning, Agentic Execution, Representation/Retrieval, Governance/Evaluation, plus dormant Realtime, Perception, and Generative Media lanes) and a seven-rung **capability tier** ladder (T0 through T5, plus T-S for specialist infrastructure). Both axes are encoded as data in [`references/model-taxonomy.json`](references/model-taxonomy.json), the **index** that is the durable source of truth. The `(segment, tier)` role is the KEY into that index; an agent's `model:` frontmatter is the index-DERIVED recommended fallback for the active host, kept in sync by [`scripts/sync_agent_model_defaults.py`](scripts/sync_agent_model_defaults.py) (never hand-edited). At dispatch the orchestrator resolves the role LIVE through [`scripts/resolve_agent_model.py`](scripts/resolve_agent_model.py) and OVERRIDES the frontmatter, so the running model always reflects the current index + availability. The `Tier` column below shows the legacy token (`Frontier`, `Thinking`, `Code`, `Pattern`), which aliases onto `T1`, `T2`, `T3`, `T4`, and the concrete model is an Anthropic fresh-install default. The index is **user-editable and chat-maintainable**: a new or different-provider model is adopted by classifying it once and reordering the cell, with no agent edits. Then `sync_agent_model_defaults.py --apply` regenerates the recommended `model:` values. Full mapping: [`references/model-tier-mapping.md`](references/model-tier-mapping.md).
 
-Resolution is availability-aware across dispatches: a model observed unavailable at dispatch (a provider outage) is recorded so the role falls back to the next host-reachable model in its tier — a frontier/judgment role degrades at most to the thinking tier, and a model the current host cannot dispatch is never offered. Outage records carry a timestamp and auto-expire after a TTL (`BUILD_LOOP_OUTAGE_TTL_SECONDS`, default 1800s), so a recovered model is picked up again without a manual clear. Recording and clearing run through [`scripts/dispatch_fallback.py`](scripts/dispatch_fallback.py); expiry is pruned on read in [`scripts/model_resolver.py`](scripts/model_resolver.py).
+Resolution is availability-aware across dispatches: a model observed unavailable at dispatch (a provider outage) is recorded so the role falls back to the next host-reachable model in its tier — a frontier/judgment role degrades at most to the thinking tier, and a model the current host cannot dispatch is never offered. Outage records carry a timestamp and auto-expire after a TTL (`BUILD_LOOP_OUTAGE_TTL_SECONDS`, default 1800s), so a recovered model is picked up again without a manual clear. Recording and clearing run through [`scripts/dispatch_fallback.py`](scripts/dispatch_fallback.py); expiry is pruned on read in [`scripts/model_resolver.py`](scripts/model_resolver.py). Resolution is also **host-capability aware**: a local model whose declared `min_ram_gb` exceeds the machine's RAM is folded into the unavailable set, so a 16GB laptop is never routed at a 30B coding model. A host whose RAM cannot be read filters nothing — absence of a reading is not evidence of a small machine.
+
+Any host can query the index **without a Python import** via [`scripts/model_index.py`](scripts/model_index.py) — `resolve`, `tiers`, `segments`, `models`, `agent`, and `export {json,env,toml}`. It runs from any working directory, takes `--json` on every subcommand, and stamps each payload with the taxonomy's schema version and content fingerprint so a consumer can detect staleness. `export --format env` emits `BUILDLOOP_MODEL_*` variables for a shell or a non-Claude agent profile. The contract is documented in [`references/model-index-contract.md`](references/model-index-contract.md).
 
 ### Lead / workflow agents
 
@@ -196,6 +255,7 @@ Resolution is availability-aware across dispatches: a model observed unavailable
 | `ui-validator` | UI behavior, state, accessibility, layout, console, and rendering evidence validation. | Code |
 | `root-cause-investigator` | Causal-tree investigation for persistent or ambiguous failures. | inherit |
 | `mock-scanner` | Production-path scan for placeholder, fake, fixture, and mock data. | Pattern |
+| `leak-scanner` | Lifecycle accounting for memory/resource leaks in long-lived code paths (unbounded maps, eviction predicates, spawn-without-reap, retain cycles, uncapped buffers). | Code |
 
 ### Learning agents
 
@@ -220,7 +280,7 @@ It is for developers running AI coding agents on non-trivial changes: features,
 
 ### What is the fastest way to try it?
 
-`npm install -g @tyroneross/build-loop@0.36.0`, then `build-loop-install --host all`, then `/build-loop:run <your task>` inside a project. See [Quick start](#quick-start).
+`npm install -g @tyroneross/build-loop@0.43.0`, then `build-loop-install --host all`, then `/build-loop:run <your task>` inside a project. See [Quick start](#quick-start). <!-- x-release-please-version -->
 
 ### How is it different from just letting an agent code directly?
 
@@ -242,7 +302,17 @@ Consumer projects store run state under `.build-loop/`:
   backlog/
 ```
 
-Add `.build-loop/` to a consumer project's `.gitignore` unless the repo intentionally tracks selected backlog or plan files.
+Add `.build-loop/` to a consumer project's `.gitignore`. In a **public** repo, treat that as mandatory rather than optional: [`references/public-repository-documentation-boundary.md`](references/public-repository-documentation-boundary.md) §3 names `.build-loop/` working state and deferred-work lists as private, and this repo's own `check_runtime_memory_tracking` hook blocks a commit that tracks them.
+
+### Publishing a repo that build-loop has run in
+
+[`scripts/doc_boundary.py`](scripts/doc_boundary.py) grades a documentation tree against that policy and sorts every tracked doc into the policy's own buckets — `public_current`, `private_archived`, `public_removed`, `blocked`:
+
+```bash
+python3 scripts/doc_boundary.py --repo . --json     # exit 0 clean, 1 findings, 2 error
+```
+
+It honors the policy's rule that *"naming is evidence, not the decision"*: a `high` verdict needs a path signal **and** a content signal to agree, so a filename alone caps at `needs_review` and never convicts on its own. Only decided findings drive a non-zero exit; `needs_review` is advisory and expects a human read. Private repos are reported but never failed. Before removing anything it flags, archive it first — §4 requires a private-memory receipt, and a removal without one is not a passing review.
 
 build-loop memory defaults to `~/.build-loop-memory` on a fresh machine, or an existing `~/dev/git-folder/build-loop-memory` when present. Bootstrap or inspect it:
 
@@ -253,12 +323,11 @@ python3 scripts/install_memory.py --check
 
 ## Codex surface
 
-The Codex package exposes one public entrypoint skill through the slim artifact:
+The Codex package installs from the repository root and exposes one public entrypoint skill:
 
 ```text
-plugin-artifacts/codex/
-  .codex-plugin/plugin.json
-  skills/build-loop/SKILL.md
+.codex-plugin/plugin.json     # "skills": "./codex-skills"
+codex-skills/build-loop/SKILL.md
 ```
 
 The full `skills/` tree still ships for Claude Code and for internal references. Codex loads helper instructions only when the public build-loop skill asks for them.
@@ -266,7 +335,7 @@ The full `skills/` tree still ships for Claude Code and for internal references.
 Check installed cache sync and prune stale versions:
 
 ```bash
-python3 scripts/check_cache_sync.py --host codex --source plugin-artifacts/codex
+python3 scripts/check_cache_sync.py --host codex --source .
 python3 scripts/check_cache_sync.py --host claude --source .
 python3 scripts/prune_plugin_cache.py --source . --host all --apply
 ```
@@ -281,7 +350,6 @@ For a plugin/package release, keep these version surfaces in lockstep:
 - `.claude-plugin/marketplace.json`
 - `.codex-plugin/plugin.json`
 - `.agents/plugins/marketplace.json`
-- `plugin-artifacts/codex/.codex-plugin/plugin.json`
 
 Build and verify, then verify the release surface after tag/push:
 
@@ -289,9 +357,9 @@ Build and verify, then verify the release surface after tag/push:
 npm run build
 python3 scripts/test_plugin_manifest.py
 python3 scripts/test_agent_surface_policy.py
-npm run codex:build-artifact
+python3 scripts/reference_pointer_lint.py
 npm pack --dry-run --json
-python3 scripts/verify_release_surface.py --version v0.36.0 --branch main --remote origin --json
+python3 scripts/verify_release_surface.py --version v0.43.0 --branch main --remote origin --json  # x-release-please-version
 ```
 
 Publishing to GitHub Packages, npmjs, or GitHub Releases is a release action. Run it only when explicitly requested by the human owner.

package/agents/advisor.md

@@ -14,7 +14,7 @@ description: |
   <example>
   Context: Phase 2 of a high-stakes build (riskSurfaceChange + synthesisDensity 7). The orchestrator wants the plan authored at Frontier, not inline on Opus.
   user: "Author the Phase 2 plan for the auth-refactor build at frontier tier"
-  assistant: "Dispatching the advisor agent. It reads intent.md + goal.md + the architecture baseline, walks the spec-writing checklist, and writes the plan to docs/plans/. plan-critic + scope-auditor then verify it before any implementer runs."
+  assistant: "Dispatching the advisor agent. It reads intent.md + goal.md + the architecture baseline, walks the spec-writing checklist, and writes the plan to .build-loop/plans/. plan-critic + scope-auditor then verify it before any implementer runs."
   </example>
 
   <example>
@@ -22,7 +22,7 @@ description: |
   user: "The plan no longer fits — re-plan chunk 4 with the failure evidence"
   assistant: "Dispatching the advisor agent in re-plan mode. It reads the failure evidence + the diff vs the current plan, diagnoses planning-miss vs execution-miss, and (on planning-miss) emits corrected instructions: a diff against the prior plan plus the evidence that justifies the change."
   </example>
-model: fable
+model: opus
 tier: frontier
 segment: generative_reasoning
 color: gold
@@ -62,7 +62,7 @@ Load the canonical protocol rather than re-deriving it: **`Skill("build-loop:spe
 5. **Name the falsifier** for each F-criterion — the concrete check that would prove the criterion failed.
 6. **Approach lenses** for non-trivial architecture/workflow/interface decisions: clean-sheet best answer, current-constraints answer, and the bridge between them.
 
-Write the plan to `docs/plans/<feature-slug>.md` (or the path the orchestrator names) and/or `.build-loop/` artifacts. **You write only plan artifacts** — your `Write` access is scoped to `docs/plans/**` and `.build-loop/**`; you do not touch source files (that is the implementer's job, verified separately).
+Write the plan to `.build-loop/plans/<feature-slug>.md` (or the path the orchestrator names). **You write only plan artifacts** — your `Write` access is scoped to `.build-loop/**`; you do not touch source files (that is the implementer's job, verified separately), and you never write a plan into `docs/`.
 
 ## Re-planning on a planning miss (the remediation contract)
 
@@ -102,7 +102,7 @@ Return a condensed envelope to the orchestrator:
 
 ```
 mode: author | re-plan
-plan_path: docs/plans/<slug>.md
+plan_path: .build-loop/plans/<slug>.md
 diagnosis: planning-miss | execution-miss | n/a   # re-plan mode only
 instructions_diff: <summary of the plan delta>     # re-plan mode only
 trigger: <objective verifier signal that summoned/advanced you>

package/agents/alignment-checker.md

@@ -43,8 +43,8 @@ Read the spec FIRST, then the item. Same anti-position-bias rationale as indepen
 
 1. `Read(workdir + "/.build-loop/intent.md")` — north star, update intent, user value, **non-goals**.
 2. `Read(workdir + "/.build-loop/goal.md")` — the current goal text.
-3. `Read("~/dev/git-folder/build-loop-memory/constitution.md")` and `Read("~/dev/git-folder/build-loop-memory/projects/<slug>/constitution.md")` — global/project rules (must-not-violate). Phase 1 already eager-loaded; you re-read for current state.
-3a. `Read("~/dev/git-folder/build-loop-memory/projects/<slug>/charter.md")` (or the repo mirror `.build-loop/charter.md`) — OPTIONAL (absent for low-stakes projects). Read its **Posture → priority_order** when present: the ranked tie-breaker (security/reliability/speed/cost/simplicity/polish + notes).
+3. Recall the global and project constitution from the memory store root (`scripts/memory_facade.py recall()`, or `_paths.memory_store_root()` for direct file paths) — `constitution.md` and `projects/<slug>/constitution.md` — global/project rules (must-not-violate). Any missing artifact is `(none found)` — not an error; state explicitly which ones were missing. Phase 1 already eager-loaded; you re-read for current state.
+3a. `Read("<memory-store-root>/projects/<slug>/charter.md")` (or the repo mirror `.build-loop/charter.md`) — OPTIONAL (absent for low-stakes projects). Read its **Posture → priority_order** when present: the ranked tie-breaker (security/reliability/speed/cost/simplicity/polish + notes).
 4. `Read(workdir + "/.build-loop/prd.md")` — optional. Repo-level PRD if user dropped one. Skip silently if absent.
 5. `Read(workdir + "/prd.md")` — optional repo-root PRD. Same fallthrough.
 6. `Read(item_path)` — the candidate item itself. Read body only after anchors.

package/agents/architecture-scout.md

@@ -19,7 +19,7 @@ You are the build-loop architecture scout. The orchestrator dispatches you with
 |---|---|---|---|
 | `baseline` | none | Refresh ACP, surface top hotspots + recent violations + in-scope lessons. | `{kind: "hotspot", component, blast_radius, layer}`, `{kind: "violation", rule, components, first_seen}`, `{kind: "lesson", id, signature}` |
 | `chunk-impact` | `files: [...]` | Slice ACP to those files + reverse-deps depth=1; recommend chunk parallelism. | `{kind: "impact", file, reverse_deps, layer, parallel_safe_with: [chunk_ids]}` |
-| `review-rules` | none (post-Execute) | Run rules check, diff against `known_violations.json`, write decisions for new ones. | `{kind: "violation", rule, components, decision_id, severity}` |
+| `review-rules` | none (post-Execute) | Run rules check, diff against `known_violations.json`, write decisions for new ones. Surface `shallow_module` (thin pass-through: high fan-out, low fan-in) as an advisory `severity: warn` finding — never blocking. | `{kind: "violation", rule, components, decision_id, severity}` (rule ∈ orphan\|circular_dependency\|layer_violation\|hotspot\|shallow_module) |
 | `iterate-subgraph` | `failing_files: [...]` | Compute subgraph + trace; recommend fix scope. | `{kind: "impact", file, downstream, upstream, fix_scope_files: [...]}` |
 | `learn-sync` | none (Phase 6) | Promote new lessons + sync NavGator lessons to Postgres. | `{kind: "lesson", id, source, action: "promoted|synced"}` |
 | `enrich` | none (Phase 1/4) | Run the native enriched scan, then label each `semantic_todo` site. | `{kind: "enriched", node_id, type, model_class, purpose}` |
@@ -76,11 +76,11 @@ If your findings exceed the budget, truncate the `findings[]` array and add `"_t
 
 ### `review-rules` (Phase 4 Review-D)
 
-1. `python -m build_loop.architecture rules --json` — capture stdout.
+1. `python -m build_loop.architecture rules --json` — capture stdout. Native `check_rules` emits `orphan`, `circular_dependency`, `layer_violation`, `hotspot`, and `shallow_module` (thin pass-through — high fan-out, low fan-in; `severity: warn`, advisory).
 2. Read `.episodic/architecture/known_violations.json` if present (no-op gracefully if absent).
 3. Diff: each new violation → invoke `scripts/capture_arch_violation.py` (Chunk 6 will provide; if missing, log to `findings[].side_effects` with `"capture_arch_violation_missing"` and skip).
-4. `summary`: new vs known counts, blocking vs warning.
-5. Recommend `route: "iterate"` if any new violation is `severity >= "blocker"`; else `route: "continue"`.
+4. `summary`: new vs known counts, blocking vs warning. Surface every new `shallow_module` finding in `findings[]` (kind `violation`, rule `shallow_module`) and name the shallow components in `follow_up` so Phase-4 guidance can advise deepening them — it is **advisory only**, never a `route: iterate` trigger.
+5. Recommend `route: "iterate"` if any new violation is `severity >= "blocker"`; else `route: "continue"`. `shallow_module` (warn) never routes to iterate.
 
 ### `iterate-subgraph` (Phase 5 Iterate)