@anhth2/spec-driven-dev-plugin 0.9.2 → 0.10.0

package/core/commands/refine-prd.md

@@ -163,7 +163,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -175,7 +175,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -206,7 +206,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
 - File write operations (test files, trace TSVs) use paths **relative to** `service_root`
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
@@ -299,7 +299,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -363,15 +363,164 @@ Proceed to the next step of the calling command.
 
 ---
 
-## Analyze — 4 Lenses (run all four)
+## Review Procedure
+# Exhaustive Review Fan-Out + Completeness Convergence
 
-**QA Lens**: Are ACs testable? Edge cases specified? Boundary conditions defined?
+**Why this exists:** A single-pass review never lists every issue at once — the model
+stops at "enough" findings, so each later review round surfaces *new* problems
+(whack-a-mole). This procedure forces the review to **converge in one command run**:
+fan out across review dimensions in parallel, then loop a completeness critic until a
+round produces nothing new, *before* writing the findings file.
 
-**DEV Lens**: Are API inputs/outputs clear? Business rules unambiguous? Cross-service deps fully described? Any technical risk?
+The calling command supplies two things:
+- **DIMENSIONS** — the list of review dimensions to fan out over
+  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
+- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
 
-**SA Lens**: Fits existing architecture? Security/auth implications? Data modeling clear?
+> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
+> procedure is **skipped** — the orchestrator is already running one dimension/UC per
+> sub-agent. Run the command's checks directly on the scoped section and return findings.
 
-**PO Lens**: Scope bounded? Priorities clear? Success metrics defined? Scope creep risk?
+---
+
+## Phase 1 — Parallel dimension scan
+
+**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
+fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
+same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
+granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+
+| Target size | Granularity | Agent count |
+|-------------|-------------|-------------|
+| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
+| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+
+The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
+single UC — which is what prevents misses on big PRDs.
+
+> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
+> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
+> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
+> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
+> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
+> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+
+### Agent cap — batch UCs when the fan-out gets too wide
+
+`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
+agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+
+1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
+2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
+   - Else split the scope list into `groups` contiguous buckets of roughly equal size
+     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
+     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
+3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+
+A batched agent reviews several UCs at once — still scoped far tighter than the whole
+file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
+more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+
+Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
+run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
+through its **one** dimension only — deeper coverage than one session juggling every
+dimension at once (avoids lost-in-the-middle).
+
+Sub-agent prompt template (fill the braces):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Completeness-critic convergence loop
+
+This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
+findings**, or a hard cap of **3 rounds**, whichever comes first:
+
+1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
+   - the full target file (`{target_file}`),
+   - the current `ALL_FINDINGS` list (so it knows what is already captured),
+   - the same slim context.
+   Prompt it:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
+3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
+4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+
+Record `convergence_rounds` (how many critic rounds ran) for the report.
+
+---
+
+## Phase 3 — Dedup, resolve conflicts, merge
+
+Sub-agents run **blind to each other** (independence = diverse coverage). They never
+talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
+the orchestrator**, where the full set is visible.
+
+1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
+   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
+   richer `suggestion`; if they differ on severity, keep the **higher** severity.
+2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
+   contradictions (two findings whose `suggestion`s cannot both be applied, or that
+   propose opposite fixes for the same spot):
+   - If the two suggestions can be **merged** into one coherent fix → merge them into a
+     single finding.
+   - If they are **mutually exclusive** → emit **one** finding that states both options
+     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) so a human picks — never silently drop one side.
+   - If a finding is **invalidated** by another (e.g. a structural finding says a section
+     is missing, but another quotes content from it) → drop the invalid one.
+3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
+4. **Assign stable IDs** `F001, F002, …` in that sorted order.
+5. Map each finding's `dimension` into the command's schema field
+   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
+6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
+
+In the command's final report, add one line:
+```
+Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+```
+
+
+---
+
+## Analyze — 4 Lenses (fan out over all four, then converge)
+
+Run the review through the **Review Procedure** above (`steps/review-fanout.md`).
+
+**DIMENSIONS** = the 4 lenses below — fan out one sub-agent per lens, each scanning the
+full PRD through its single lens:
+
+- **QA Lens**: Are ACs testable? Edge cases specified? Boundary conditions defined?
+- **DEV Lens**: Are API inputs/outputs clear? Business rules unambiguous? Cross-service deps fully described? Any technical risk?
+- **SA Lens**: Fits existing architecture? Security/auth implications? Data modeling clear?
+- **PO Lens**: Scope bounded? Priorities clear? Success metrics defined? Scope creep risk?
+
+The completeness-critic loop (Phase 2) is what guarantees the findings file is complete
+in one run — re-running `/refine-prd` should surface **0 new** findings. Map each
+dimension into the `lens` field of the schema below.
 
 ## Output File
 
@@ -451,13 +600,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |

package/core/commands/report-bug.md

@@ -172,7 +172,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -184,7 +184,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -215,7 +215,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
 - File write operations (test files, trace TSVs) use paths **relative to** `service_root`
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
@@ -308,7 +308,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -487,13 +487,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |

package/core/commands/review-code.md

@@ -165,7 +165,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -177,7 +177,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -208,7 +208,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
 - File write operations (test files, trace TSVs) use paths **relative to** `service_root`
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
@@ -301,7 +301,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -449,13 +449,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
@@ -491,7 +491,7 @@ Output Artifacts: none (read-only)
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
 
 If APPROVED ✅:
-  Next: /generate-tests {UC-ID}
+  Next: /dev-gen-test {UC-ID}
 
 If NEEDS_FIX ❌:
   - Small fix (1–3 lines, no logic change) → fix inline → re-run /review-code {UC-ID}
@@ -570,7 +570,7 @@ If `lessons_path` does not exist, create it with this header first:
 | code-gen | /generate-code output |
 | bdd | /generate-bdd output |
 | tech-docs | /generate-tech-docs output |
-| tests | /generate-tests output |
+| tests | /dev-gen-test output |
 | prd | /generate-prd, /refine-prd output |
 | general | every command |
 

package/core/commands/review-context.md

@@ -170,7 +170,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -182,7 +182,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -213,7 +213,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
 - File write operations (test files, trace TSVs) use paths **relative to** `service_root`
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
@@ -306,7 +306,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -387,6 +387,154 @@ Derive the output findings filename:
 
 ---
 
+## Review Procedure
+# Exhaustive Review Fan-Out + Completeness Convergence
+
+**Why this exists:** A single-pass review never lists every issue at once — the model
+stops at "enough" findings, so each later review round surfaces *new* problems
+(whack-a-mole). This procedure forces the review to **converge in one command run**:
+fan out across review dimensions in parallel, then loop a completeness critic until a
+round produces nothing new, *before* writing the findings file.
+
+The calling command supplies two things:
+- **DIMENSIONS** — the list of review dimensions to fan out over
+  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
+- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
+
+> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
+> procedure is **skipped** — the orchestrator is already running one dimension/UC per
+> sub-agent. Run the command's checks directly on the scoped section and return findings.
+
+---
+
+## Phase 1 — Parallel dimension scan
+
+**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
+fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
+same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
+granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+
+| Target size | Granularity | Agent count |
+|-------------|-------------|-------------|
+| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
+| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+
+The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
+single UC — which is what prevents misses on big PRDs.
+
+> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
+> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
+> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
+> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
+> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
+> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+
+### Agent cap — batch UCs when the fan-out gets too wide
+
+`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
+agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+
+1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
+2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
+   - Else split the scope list into `groups` contiguous buckets of roughly equal size
+     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
+     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
+3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+
+A batched agent reviews several UCs at once — still scoped far tighter than the whole
+file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
+more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+
+Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
+run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
+through its **one** dimension only — deeper coverage than one session juggling every
+dimension at once (avoids lost-in-the-middle).
+
+Sub-agent prompt template (fill the braces):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Completeness-critic convergence loop
+
+This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
+findings**, or a hard cap of **3 rounds**, whichever comes first:
+
+1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
+   - the full target file (`{target_file}`),
+   - the current `ALL_FINDINGS` list (so it knows what is already captured),
+   - the same slim context.
+   Prompt it:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
+3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
+4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+
+Record `convergence_rounds` (how many critic rounds ran) for the report.
+
+---
+
+## Phase 3 — Dedup, resolve conflicts, merge
+
+Sub-agents run **blind to each other** (independence = diverse coverage). They never
+talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
+the orchestrator**, where the full set is visible.
+
+1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
+   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
+   richer `suggestion`; if they differ on severity, keep the **higher** severity.
+2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
+   contradictions (two findings whose `suggestion`s cannot both be applied, or that
+   propose opposite fixes for the same spot):
+   - If the two suggestions can be **merged** into one coherent fix → merge them into a
+     single finding.
+   - If they are **mutually exclusive** → emit **one** finding that states both options
+     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) so a human picks — never silently drop one side.
+   - If a finding is **invalidated** by another (e.g. a structural finding says a section
+     is missing, but another quotes content from it) → drop the invalid one.
+3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
+4. **Assign stable IDs** `F001, F002, …` in that sorted order.
+5. Map each finding's `dimension` into the command's schema field
+   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
+6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
+
+In the command's final report, add one line:
+```
+Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+```
+
+
+**How the checks below map onto the procedure:**
+- **DIMENSIONS** = the check groups for the detected mode — PRD: `P1, P2, P4, P5`; BDD: `B1, B2, B3, B4, B5, B6`. Fan out one sub-agent per check group, each scanning the full target file for just that group.
+- **Orchestrator-run checks (not fanned out):** `P0` (umbrella routing) and `P3` (cross-PRD conflict) need config / other-PRD context — the orchestrator runs these itself **before** the fan-out and adds their results to `ALL_FINDINGS`.
+- The completeness-critic loop (Phase 2) guarantees the findings file is complete in one run — re-running `/review-context` should surface **0 new** findings. Map each dimension into the `check_id` field of the schema below.
+
+---
+
 ## PRD Review Mode
 
 ### P0 — Umbrella Routing Check (umbrella mode only)
@@ -633,13 +781,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
@@ -690,7 +838,7 @@ to the findings file as usual and left `status: pending`.
 
 ### Phase 1 — Run analysis
 
-Run all checks (P1–P5 or B1–B6) exactly as in the default mode.
+Run all checks via the **Review Procedure** (fan-out + completeness loop) exactly as in the default mode.
 Write the findings file with all `status: "pending"` as usual.
 
 ### Phase 2 — Apply auto-fixable findings