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

package/commands/generate-spec-manifest.tmpl

@@ -0,0 +1,164 @@
+# /generate-spec-manifest — Generate Spec Manifest for External Agents
+
+Scans all spec files and writes a `spec-manifest.yaml` at the project root.
+This file is for **external agents only** (e.g. tester's agent) — it is not committed to git.
+
+## Gate
+
+{{include:steps/gate.md}}
+
+*Note: For this command, there is no target file — it scans the entire project. Ignore `$ARGUMENTS` unless a domain filter is passed.*
+
+## Context
+
+{{include:steps/context-loader.md}}
+
+---
+
+## Process
+
+### Step 1 — Determine scan roots
+
+Read `project-context.yaml` to determine mode and paths:
+
+**Umbrella mode** (`setup.mode: umbrella`):
+```
+spec_root      = {setup.spec_source}              ← PO's spec submodule
+prd_glob       = {spec_root}/specs/prd/**/*.md
+pdd_glob       = {spec_root}/specs/product-definition/**/*.md
+services       = {services}                        ← map of domain → paths
+```
+
+**Single-service mode** (no `setup.mode`):
+```
+spec_root      = .
+prd_glob       = {paths.prd_dir}/**/*.md
+pdd_glob       = {paths.product_definitions_dir}/**/*.md
+services       = { default: { specs_dir: {paths.specs_dir}, tech_docs_dir: {paths.tech_docs_dir} } }
+```
+
+If a domain filter was passed in `$ARGUMENTS` → only scan PRDs matching that domain.
+
+---
+
+### Step 2 — Scan PRD files
+
+For each `.md` file matched by `prd_glob`:
+
+1. Read the file metadata table:
+   - `TICKET-ID` from `| **PRD ID** |`
+   - `domain` from `| **Domain** |`
+   - `status` from `| **Status** |`
+   - `version` from `| **Version** |`
+2. Also read frontmatter `@trace.domain` if present (use this over metadata table domain if both exist)
+3. Record: `{ ticket_id, domain, status, version, prd_path }` — path relative to manifest root
+
+Skip files where `TICKET-ID` cannot be determined.
+
+---
+
+### Step 3 — Match PDD files
+
+For each TICKET-ID found in Step 2:
+
+Search `pdd_glob` for a file whose name contains the TICKET-ID (e.g. `FT-001-*.md`).
+- Found → record `pdd_path` (relative to manifest root)
+- Not found → record `pdd: null`
+
+---
+
+### Step 4 — Match BDD and Tech-Doc files per service
+
+For each TICKET-ID, for each service in `services` map:
+
+**BDD:**
+- Glob `{service.specs_dir}/**/{TICKET-ID}*.feature`
+- Also check files containing `@trace.prd: {TICKET-ID}` in frontmatter if glob returns nothing
+- Found → record path under `bdd.{service_key}`
+- Not found → omit key (do not write `null` for services with no BDD yet)
+
+**Tech-docs:**
+- Glob `{service.tech_docs_dir}/**/{TICKET-ID}*.md`
+- Also check files containing `@trace.prd: {TICKET-ID}` if glob returns nothing
+- Found → record path under `tech_docs.{service_key}`
+- Not found → omit key
+
+All paths relative to manifest root (umbrella root or project root).
+
+---
+
+### Step 5 — Write spec-manifest.yaml
+
+Write to `{manifest_root}/spec-manifest.yaml` (overwrite if exists).
+
+Format:
+
+```yaml
+# Auto-generated by /generate-spec-manifest — DO NOT edit manually
+# To regenerate: /generate-spec-manifest
+# This file is excluded from git — see .gitignore
+
+version: "1.0"
+generated_at: "{YYYY-MM-DD}"
+project_mode: "{umbrella | single}"
+
+features:
+  {TICKET-ID}:
+    domain: {domain}
+    status: {status}
+    prd_version: "{version}"
+    prd: "{prd_path}"
+    pdd: "{pdd_path}"               # omit if null
+    tech_docs:
+      {service_key}: "{path}"       # only include services where file was found
+    bdd:
+      {service_key}: "{path}"       # only include services where file was found
+```
+
+Sort features by TICKET-ID alphabetically.
+Omit `tech_docs` block entirely if no tech-doc found for any service.
+Omit `bdd` block entirely if no BDD found for any service.
+
+---
+
+### Step 6 — Ensure .gitignore
+
+Check `{manifest_root}/.gitignore`:
+- If `spec-manifest.yaml` is already listed → no action
+- If not → append the following to `.gitignore`:
+
+```
+# Auto-generated — do not commit
+spec-manifest.yaml
+```
+
+Print: `✅ spec-manifest.yaml added to .gitignore`
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-spec-manifest Complete
+---
+Status  : ✅ Complete
+Output  : spec-manifest.yaml  ({N} features)
+Mode    : {umbrella | single}
+.gitignore : ✅ spec-manifest.yaml excluded
+
+Summary:
+  {N} PRDs scanned  ({A} approved, {D} draft)
+  {N} PDDs matched
+  {N} BDD files matched  (across {S} services)
+  {N} Tech-doc files matched  (across {S} services)
+
+  ⚠️  {N} PRDs with no matching BDD:
+    - {TICKET-ID} ({domain}) — run /generate-bdd first
+  ⚠️  {N} PRDs with no matching tech-docs:
+    - {TICKET-ID} ({domain}) — run /generate-tech-docs first
+
+Next   : Share spec-manifest.yaml path with tester agent
+         Regenerate anytime: /generate-spec-manifest
+```

package/commands/generate-tech-docs.md

@@ -152,6 +152,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`
@@ -163,11 +164,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`.
@@ -258,6 +323,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.
@@ -273,6 +357,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}
 ```
 
@@ -294,6 +381,22 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## Brownfield Check
+
+Read the source `.feature` file header for `@trace.api_source`.
+Also check the source PRD Metadata table for `| **API Source** | existing |`.
+
+| Value | Mode |
+|-------|------|
+| `existing` | **Reverse-document** — API đã tồn tại; mô tả lại as-is, note gaps, không cần design mới |
+| absent / other | **Greenfield** — thiết kế API từ đầu |
+
+Store `active_mode = {reverse-document | greenfield}`.
+
+If `active_mode = reverse-document` → load bảng "Existing API Contract" từ PRD làm input cho §2.
+
 ---
 
 ## CHECKPOINT — Tech Design Plan
@@ -306,13 +409,14 @@ Tech Design Plan — {UC-ID}
 UC       : {UC-ID} — {feature title}
 Service  : {trace.service}
 Module   : {trace.module}
+Mode     : {Reverse-document (API đã tồn tại) | Greenfield (thiết kế mới)}
 Scenarios: {N} scenarios
 BDD ver  : {trace.bdd_version}
 Output   : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
 
 Sections to generate:
   §1 Overview
-  §2 API Endpoints   ({N} endpoints inferred from scenarios)
+  §2 API Endpoints   ({Reverse-document: mô tả lại từ PRD contract | Greenfield: infer từ scenarios})
   §3 Data Model      ({entities from core-entities.md relevant to this UC})
   §4 Service Flow
   §5 Business Rules  ({N} BRs from feature header)
@@ -344,11 +448,15 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 @trace.bdd_version: {read @trace.bdd_version from the .feature file header}
 @trace.revision: 1
 @trace.status: draft
+@trace.api_source: {existing | —}
 @trace.generated_at: {YYYY-MM-DD}
 ---
 
 ## §1. Overview
 ## §2. API Endpoints
+  *Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
+  *Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD.
+    Ghi chú gaps nếu contract thực tế khác với BDD expectations.
   | Method | Path | Auth/Role | Request | Response |
 ## §3. Data Model
   Key entities and relationships.
@@ -406,7 +514,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}`        |
@@ -420,6 +529,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:
 ```

package/commands/generate-tech-docs.tmpl

@@ -31,6 +31,22 @@
 
 ---
 
+## Brownfield Check
+
+Read the source `.feature` file header for `@trace.api_source`.
+Also check the source PRD Metadata table for `| **API Source** | existing |`.
+
+| Value | Mode |
+|-------|------|
+| `existing` | **Reverse-document** — API đã tồn tại; mô tả lại as-is, note gaps, không cần design mới |
+| absent / other | **Greenfield** — thiết kế API từ đầu |
+
+Store `active_mode = {reverse-document | greenfield}`.
+
+If `active_mode = reverse-document` → load bảng "Existing API Contract" từ PRD làm input cho §2.
+
+---
+
 ## CHECKPOINT — Tech Design Plan
 
 Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display and wait for Y:
@@ -41,13 +57,14 @@ Tech Design Plan — {UC-ID}
 UC       : {UC-ID} — {feature title}
 Service  : {trace.service}
 Module   : {trace.module}
+Mode     : {Reverse-document (API đã tồn tại) | Greenfield (thiết kế mới)}
 Scenarios: {N} scenarios
 BDD ver  : {trace.bdd_version}
 Output   : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
 
 Sections to generate:
   §1 Overview
-  §2 API Endpoints   ({N} endpoints inferred from scenarios)
+  §2 API Endpoints   ({Reverse-document: mô tả lại từ PRD contract | Greenfield: infer từ scenarios})
   §3 Data Model      ({entities from core-entities.md relevant to this UC})
   §4 Service Flow
   §5 Business Rules  ({N} BRs from feature header)
@@ -79,11 +96,15 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 @trace.bdd_version: {read @trace.bdd_version from the .feature file header}
 @trace.revision: 1
 @trace.status: draft
+@trace.api_source: {existing | —}
 @trace.generated_at: {YYYY-MM-DD}
 ---
 
 ## §1. Overview
 ## §2. API Endpoints
+  *Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
+  *Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD.
+    Ghi chú gaps nếu contract thực tế khác với BDD expectations.
   | Method | Path | Auth/Role | Request | Response |
 ## §3. Data Model
   Key entities and relationships.

package/commands/generate-tests.md

@@ -131,6 +131,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`
@@ -142,11 +143,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`.
@@ -237,6 +302,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.
@@ -252,6 +336,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}
 ```
 
@@ -762,7 +849,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}`        |
@@ -776,6 +864,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:
 ```