@anhth2/spec-driven-dev-plugin 0.7.0 → 0.9.0

package/commands/report-bug.tmpl

@@ -0,0 +1,131 @@
+# /report-bug — File a Spec-Traced Bug (Tester-Facing)
+
+For **testers**. Produces a structured bug report with full spec context, classifies the likely
+layer, and saves it for handoff to the dev team.
+
+**READ-ONLY on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
+Fixing is the dev's job (`/fix-bug`); writing scenarios is `/propose-scenario`.
+
+Usage: `/report-bug {UC-ID or TICKET} {short description}`
+Example: `/report-bug FT-001 account locks after 6 failed logins, spec says 5`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID / TICKET from `$ARGUMENTS`. Resolve the matching `.feature` file if one exists; if not, continue — a bug can still be filed.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Resolve Spec Context
+
+Locate the spec chain for the bug's UC/TICKET. Prefer `spec-manifest.yaml` (umbrella/tester setup) if present; else use resolved `paths`.
+
+Gather and store:
+- `prd_path` + current PRD `Version`
+- `bdd_path` (the `.feature` for this UC) + the specific **failing scenario** title, if one matches
+- `tech_doc_path` (if any)
+- `service` / domain
+
+If no `.feature` scenario matches the reported behavior → set `coverage_gap = true` (the behavior is untested by BDD).
+
+## Step 2 — Gather Bug Details
+
+If not already in `$ARGUMENTS`, ask the tester (one compact prompt):
+
+```
+File a bug — answer what you can:
+  1. Where does it occur? (endpoint / screen / flow)
+  2. Steps to reproduce?
+  3. Expected (per spec) vs Actual?
+  4. Error / log / status code?
+  5. Environment? (staging / prod / local)
+```
+
+## Step 3 — Identify the AC Violated
+
+Read the PRD acceptance criteria for this UC. Match the bug to the specific **AC** it violates
+(e.g. `AC3: "5 failed logins → lock 30m"`). Quote it verbatim. If the behavior maps to no AC →
+note "No AC covers this" and treat as a possible PRD gap.
+
+## Step 4 — Classify Likely Layer (BUG_FLOW)
+
+Apply the BUG_FLOW decision table to suggest where the root cause likely is — this routes the bug:
+
+| If… | Likely layer | Route to |
+|------|-------------|----------|
+| Code contradicts a BDD scenario | **Code bug** (Case 1) | Dev → `/fix-bug` |
+| BDD scenario contradicts PRD AC | **BDD bug** (Case 2) | Dev/PO fix BDD |
+| PRD AC is ambiguous / silent | **PRD ambiguity** (Case 3) | PO clarifies PRD |
+| Behavior correct but **no scenario covers it** | **BDD coverage gap** | Tester → `/propose-scenario` |
+| UI ≠ Design Spec | **Design Spec bug** (Case 5) | Dev/Designer |
+| Env / data only | **Environment** (Case 6) | DevOps |
+
+State the classification as a suggestion (dev confirms during `/fix-bug`).
+
+## Step 5 — Write the Report
+
+Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
+Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
+
+## Step 6 — Handoff (so PO/Dev actually see it)
+
+The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
+
+Determine the repo that owns `{paths.bug_reports_dir}`:
+- Umbrella mode → the spec submodule at `{spec_source}`
+- Single-service → the current repo
+
+Then commit + push **that** repo:
+
+```bash
+cd {spec_source}              # umbrella: the spec submodule; single-service: omit
+git add feedback/bug-reports/{BUG-ID}.md
+git commit -m "qa(bug): {BUG-ID} — {short description}"
+git push                      # → PO/Dev see it on their next /sync
+```
+
+- If the tester lacks push rights to the spec repo → open a PR / MR instead, or hand the file to whoever owns it. Print this fallback.
+- Print the exact commands if you do not run them automatically.
+
+> PO/Dev are notified through their normal routine: `/sync` lists newly-pulled bug reports.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
+
+Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+
+Spec context
+  PRD      : {prd_path} (v{prd_version})
+  BDD      : {bdd_path} → Scenario: "{scenario title}"   {or: ⚠️ no scenario covers this}
+  Tech Doc : {tech_doc_path}
+
+AC violated
+  {AC-N}: "{AC text}"
+
+Expected (per spec) : {expected}
+Actual              : {actual}
+Steps to reproduce  : {1..N}
+Environment         : {env}
+
+Likely layer : {Code | BDD | PRD | Design Spec | Env}  →  {route}
+
+Handoff : {✅ committed + pushed to spec repo | ⚠️ run the git commands above / open a PR}
+
+---
+Status : ✅ Complete (read-only on specs/code — only wrote the feedback file)
+Output Artifacts: created {paths.bug_reports_dir}/{BUG-ID}.md (pushed to shared spec repo)
+Next   :
+  - PO/Dev will see this on their next /sync
+  - Code bug      → dev runs /fix-bug {BUG-ID}
+  - PRD ambiguity → PO (BUG_FLOW Case 3)
+  - Coverage gap  → /propose-scenario {UC-ID}
+```

package/commands/review-code.md

@@ -133,6 +133,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -144,11 +145,75 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `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`
+- 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).
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -239,6 +304,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -254,6 +338,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -355,7 +442,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -369,6 +457,11 @@ Suggest the logical next command based on workflow phase:
 | /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
 
 Format the footer as:
 ```
@@ -404,3 +497,99 @@ If NEEDS_FIX ❌:
   - Logic / architecture issue             → /fix-bug {TICKET_ID}
   - Spec mismatch (code ≠ scenario)        → /generate-code {feature-file}  (re-gen affected UC)
 ```
+
+---
+
+## Offer to Record Lessons (optional)
+
+For each **Critical/Major** finding that represents a **repeatable AI mistake** during code generation
+(an architecture/standards violation the AI is likely to make again — NOT a one-off typo or an external cause), ask:
+
+```
+Finding "{issue}" looks like a repeatable mistake.
+Record it as a project lesson so /generate-code won't repeat it? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `category=code-gen`, `source=/review-code {UC-ID}`,
+`scope` = the affected domain or file glob.
+
+# Capture Lesson — Record a Recurring Mistake as a Guardrail
+
+Reusable procedure to persist a "lesson" so the AI does not repeat a mistake in this project.
+Used by `/learn` (manual) and offered by `/review-code`, `/fix-bug`, `/debug` (auto).
+
+> **Project memory, not model training.** A lesson is plain text injected into context at the
+> start of every command (context-loader Step 6.7). Functionally this stops the repeat — the AI
+> sees the guardrail before it generates. No model weights change.
+
+## L1 — Resolve the lessons file
+
+Resolve `lessons_path` in this order:
+1. `paths.lessons_file` from loaded context (may be service-overridden in umbrella mode, Step 1.6)
+2. Default `specs/domain-knowledge/lessons-learned.md` (single-service)
+3. In umbrella/service mode (when `service_root` is set) default `{service_root}/.agent/project-lessons.md`
+
+## L2 — Build the lesson
+
+Gather these fields — from `$ARGUMENTS` (for `/learn`) or from the calling command's findings
+(for `/review-code`, `/fix-bug`, `/debug`):
+
+| Field | Meaning |
+|-------|---------|
+| `category` | one of: `code-gen` \| `bdd` \| `tech-docs` \| `tests` \| `prd` \| `general` |
+| `title` | short phrase naming the mistake |
+| `mistake` | concretely, what the AI did wrong |
+| `rule` | imperative correction — "Always …" / "Never …" — testable, not vague |
+| `scope` | where it applies: a domain, a file glob (e.g. `*Controller.*`), or `all` |
+| `source` | how captured: `/learn` \| `/review-code {UC-ID}` \| `/fix-bug {TICKET}` \| `/debug` |
+
+If `rule` is vague (e.g. "be careful"), rewrite it into a concrete, checkable instruction before saving.
+
+## L3 — De-duplicate
+
+Read existing lessons in `lessons_path`. If one already covers the same mistake:
+- **Refine** that entry (tighten the Rule, widen/narrow Scope, bump Date, append the new Source) — do NOT add a duplicate.
+
+Otherwise assign the next id `L-{NNN}` = (highest existing number + 1), zero-padded to 3 digits.
+
+## L4 — Write
+
+If `lessons_path` does not exist, create it with this header first:
+
+```markdown
+# Project Lessons — Learned Guardrails
+
+> Mistakes the AI must NOT repeat in this project. Loaded by context-loader at the start of
+> every command and treated as hard constraints (same priority as CLAUDE.md coding standards).
+> Add with /learn, or accept the prompt during /review-code, /fix-bug, /debug.
+> Commit this file so the whole team shares the guardrails.
+
+| Category | Applies to |
+|----------|-----------|
+| code-gen | /generate-code output |
+| bdd | /generate-bdd output |
+| tech-docs | /generate-tech-docs output |
+| tests | /generate-tests output |
+| prd | /generate-prd, /refine-prd output |
+| general | every command |
+
+---
+```
+
+Insert the new lesson directly under the `---` separator (**newest first**), in this exact shape:
+
+```markdown
+### L-{NNN} — [{category}] {title}
+- **Date**: {today YYYY-MM-DD}
+- **Scope**: {scope}
+- **Mistake**: {mistake}
+- **Rule**: {rule}
+- **Source**: {source}
+
+```
+
+## L5 — Confirm
+
+Print: `📝 Lesson {id} recorded → {lessons_path}  ([{category}] {title})`
+Then remind: `Commit {lessons_path} so the team shares this guardrail.`
+

package/commands/review-code.tmpl

@@ -85,3 +85,20 @@ If NEEDS_FIX ❌:
   - Logic / architecture issue             → /fix-bug {TICKET_ID}
   - Spec mismatch (code ≠ scenario)        → /generate-code {feature-file}  (re-gen affected UC)
 ```
+
+---
+
+## Offer to Record Lessons (optional)
+
+For each **Critical/Major** finding that represents a **repeatable AI mistake** during code generation
+(an architecture/standards violation the AI is likely to make again — NOT a one-off typo or an external cause), ask:
+
+```
+Finding "{issue}" looks like a repeatable mistake.
+Record it as a project lesson so /generate-code won't repeat it? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `category=code-gen`, `source=/review-code {UC-ID}`,
+`scope` = the affected domain or file glob.
+
+{{include:steps/capture-lesson.md}}

package/commands/review-context.md

@@ -138,6 +138,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -149,11 +150,75 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `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`
+- 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).
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -244,6 +309,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -259,6 +343,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -301,6 +388,44 @@ Derive the output findings filename:
 
 ## PRD Review Mode
 
+### P0 — Umbrella Routing Check (umbrella mode only)
+
+*Skip this check entirely if `setup.mode` is not `"umbrella"` (i.e., `services` section absent from project-context.yaml).*
+
+When `setup.mode = umbrella`, the PRD must have correct routing metadata so context-loader Step 1.5 can direct generated output to the right service submodule. Run these checks **before P1–P5**:
+
+**P0.1 — `@trace.domain` presence**
+- Read the PRD frontmatter block (lines starting with `@trace.` at top of file)
+- If `@trace.domain` is **absent** → **critical** finding:
+  - `finding`: "`@trace.domain` is missing. Dev team's umbrella routing depends on this field to route BDD and code output to the correct service submodule."
+  - `suggestion`: "Add `@trace.domain: {domain}` to the PRD frontmatter. Use one of the domain keys defined in the umbrella's `project-context.yaml` services section."
+  - `auto_fixable: false` — PO must confirm the correct domain name
+
+**P0.2 — `@trace.domain` matches a service key**
+- If `@trace.domain` is present, check if its value matches any key in the `services` section of project-context.yaml
+- If **no match found** → **critical** finding:
+  - `finding`: "`@trace.domain: {value}` does not match any key in the umbrella's `services` config. Routing will fall back to default paths and BDD may be generated to the wrong location."
+  - `suggestion`: "Either update `@trace.domain` to match an existing service key ({list known keys}), or add a new entry to `services` in project-context.yaml for domain `{value}`."
+  - `auto_fixable: false`
+- If `services` section is not yet configured (empty/placeholder) → **major** finding:
+  - `finding`: "Umbrella `services` section is not yet configured. Cannot verify domain routing."
+  - `suggestion`: "Update `.agent/project-context.yaml` services section with domain-to-submodule mapping before generating BDD."
+  - `auto_fixable: false`
+
+**P0.3 — `@trace.status` check**
+- If `@trace.status` is absent → **minor**, `auto_fixable: true` (add `@trace.status: draft`)
+- If `@trace.status: draft` → **major**, `auto_fixable: false`:
+  - `finding`: "PRD status is `draft`. Dev team should not generate BDD from an unapproved PRD."
+  - `suggestion`: "PO/SA should review and update status to `approved` before dev team proceeds."
+
+> **P0 is a gate check:** If P0.1 or P0.2 yields a critical finding, display a warning before proceeding:
+> ```
+> ⚠️  ROUTING WARNING: @trace.domain issue detected.
+>    BDD/code generated from this PRD may land in the wrong service submodule.
+>    Resolve P0 findings before running /generate-bdd.
+> ```
+> Then continue with P1–P5 (do not abort — PO may be reviewing early-stage PRDs).
+
 ### P1 — Terminology Check (Business Dictionary)
 
 Load `{paths.business_dictionary}`.
@@ -493,7 +618,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -507,6 +633,11 @@ Suggest the logical next command based on workflow phase:
 | /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
 
 Format the footer as:
 ```
@@ -561,6 +692,7 @@ For each finding where `auto_fixable: true`, in order (critical → major → mi
 
 | check_id | What to apply |
 |----------|--------------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
 | P1 (Banned term) | Replace every banned term occurrence with canonical term |
 | P4 (Structure) | Add missing section/metadata skeleton |
 
@@ -637,6 +769,7 @@ Apply in order: critical → major → minor.
 **For PRD findings:**
 | check_id | What to do |
 |----------|-----------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
 | P1 (Banned term) | Replace every occurrence of banned term with canonical term |
 | P2 (Ambiguity) | Apply the fix stated in `suggestion` or `modified` note |
 | P3 (Conflict) | Apply the resolution stated in the modified note |

package/commands/review-context.tmpl

@@ -36,6 +36,44 @@ Derive the output findings filename:
 
 ## PRD Review Mode
 
+### P0 — Umbrella Routing Check (umbrella mode only)
+
+*Skip this check entirely if `setup.mode` is not `"umbrella"` (i.e., `services` section absent from project-context.yaml).*
+
+When `setup.mode = umbrella`, the PRD must have correct routing metadata so context-loader Step 1.5 can direct generated output to the right service submodule. Run these checks **before P1–P5**:
+
+**P0.1 — `@trace.domain` presence**
+- Read the PRD frontmatter block (lines starting with `@trace.` at top of file)
+- If `@trace.domain` is **absent** → **critical** finding:
+  - `finding`: "`@trace.domain` is missing. Dev team's umbrella routing depends on this field to route BDD and code output to the correct service submodule."
+  - `suggestion`: "Add `@trace.domain: {domain}` to the PRD frontmatter. Use one of the domain keys defined in the umbrella's `project-context.yaml` services section."
+  - `auto_fixable: false` — PO must confirm the correct domain name
+
+**P0.2 — `@trace.domain` matches a service key**
+- If `@trace.domain` is present, check if its value matches any key in the `services` section of project-context.yaml
+- If **no match found** → **critical** finding:
+  - `finding`: "`@trace.domain: {value}` does not match any key in the umbrella's `services` config. Routing will fall back to default paths and BDD may be generated to the wrong location."
+  - `suggestion`: "Either update `@trace.domain` to match an existing service key ({list known keys}), or add a new entry to `services` in project-context.yaml for domain `{value}`."
+  - `auto_fixable: false`
+- If `services` section is not yet configured (empty/placeholder) → **major** finding:
+  - `finding`: "Umbrella `services` section is not yet configured. Cannot verify domain routing."
+  - `suggestion`: "Update `.agent/project-context.yaml` services section with domain-to-submodule mapping before generating BDD."
+  - `auto_fixable: false`
+
+**P0.3 — `@trace.status` check**
+- If `@trace.status` is absent → **minor**, `auto_fixable: true` (add `@trace.status: draft`)
+- If `@trace.status: draft` → **major**, `auto_fixable: false`:
+  - `finding`: "PRD status is `draft`. Dev team should not generate BDD from an unapproved PRD."
+  - `suggestion`: "PO/SA should review and update status to `approved` before dev team proceeds."
+
+> **P0 is a gate check:** If P0.1 or P0.2 yields a critical finding, display a warning before proceeding:
+> ```
+> ⚠️  ROUTING WARNING: @trace.domain issue detected.
+>    BDD/code generated from this PRD may land in the wrong service submodule.
+>    Resolve P0 findings before running /generate-bdd.
+> ```
+> Then continue with P1–P5 (do not abort — PO may be reviewing early-stage PRDs).
+
 ### P1 — Terminology Check (Business Dictionary)
 
 Load `{paths.business_dictionary}`.
@@ -242,6 +280,7 @@ For each finding where `auto_fixable: true`, in order (critical → major → mi
 
 | check_id | What to apply |
 |----------|--------------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
 | P1 (Banned term) | Replace every banned term occurrence with canonical term |
 | P4 (Structure) | Add missing section/metadata skeleton |
 
@@ -318,6 +357,7 @@ Apply in order: critical → major → minor.
 **For PRD findings:**
 | check_id | What to do |
 |----------|-----------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
 | P1 (Banned term) | Replace every occurrence of banned term with canonical term |
 | P2 (Ambiguity) | Apply the fix stated in `suggestion` or `modified` note |
 | P3 (Conflict) | Apply the resolution stated in the modified note |