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

package/commands/update-framework.tmpl

@@ -0,0 +1,151 @@
+# /update-framework — Update the Spec-Driven Dev Framework
+
+Upgrades the **framework tooling** (`.agent/commands/`, `steps/`, `modules/`, `hooks/`, `rules/`, `templates/`, `skills/`) to the latest published version from npm.
+
+> **Not the same as `/sync`.**
+> - `/sync` → pulls **project content** (submodule code/specs) + refreshes Living Docs. Run daily.
+> - `/update-framework` → upgrades the **framework command files themselves**. Run occasionally, when a new framework version ships.
+
+This command wraps `npx @anhth2/spec-driven-dev-plugin@latest --init`. It requires network + npm access.
+
+---
+
+## Step 0 — Detect Current State
+
+1. Read `.agent/FRAMEWORK_VERSION` → current installed version.
+   - If missing → this project was not installed via `--init`. Stop:
+     ```
+     ❌ .agent/FRAMEWORK_VERSION not found.
+        This project was not set up with the framework installer.
+        Run: npx @anhth2/spec-driven-dev-plugin --init
+     ```
+
+2. Read `.agent/project-context.yaml` → extract `setup.mode` (`umbrella` / absent = single) and `services`.
+
+3. List `.agent/modules/` → record installed module names (these must be re-passed on upgrade so they update too).
+
+Print:
+```
+Current framework : v{current}
+Mode              : {umbrella | single-service}
+Installed modules : {list or "none"}
+```
+
+---
+
+## Step 1 — Check Latest Version
+
+Run:
+```bash
+npm view @anhth2/spec-driven-dev-plugin version
+```
+
+Compare `current` vs `latest`:
+
+| Result | Action |
+|--------|--------|
+| Network/registry unreachable | Warn `⚠️ Could not reach npm registry — check connection.` and stop |
+| `current == latest` | Print `✅ Already up to date (v{current}). Nothing to do.` and stop |
+| `latest > current` | Print `Update available: v{current} → v{latest}` and continue |
+
+Ask: `Proceed with upgrade? (Y/N)` — wait for `Y`.
+
+---
+
+## Step 2 — Umbrella Awareness *(umbrella mode only)*
+
+If `setup.mode == umbrella`, print this note before upgrading:
+
+```
+ℹ️ Umbrella mode — framework tooling lives ONLY at this umbrella root.
+   Service submodules contain just .agent/project-context.yaml (config), not
+   command files — they read commands from the umbrella root. No per-service
+   framework update is needed here.
+
+   Exception: if a teammate opens Claude Code directly INSIDE a service repo
+   (outside the umbrella), that repo has its own .agent/ — its owning team runs
+   /update-framework there independently.
+```
+
+---
+
+## Step 3 — Pre-flight Git Check
+
+Run `git status --short .agent/ .claude/commands/`.
+
+If there are uncommitted changes in those paths:
+```
+⚠️ Uncommitted changes in .agent/ or .claude/commands/.
+   The upgrade overwrites framework files. Commit or stash first so you can
+   cleanly review the upgrade diff:
+     git add .agent/ .claude/commands/ && git commit -m "wip"  (or git stash)
+```
+Ask whether to continue anyway `(Y/N)`. Default to stopping.
+
+---
+
+## Step 4 — Run the Upgrade
+
+Build the module flags from Step 0 (one `--module {name}` per installed module), then run:
+
+```bash
+npx -y @anhth2/spec-driven-dev-plugin@latest --init {--module X ...}
+```
+
+This **overwrites** (refreshes to the new version):
+- `.agent/commands/`, `.agent/steps/`, `.agent/hooks/`, `.agent/rules/`, `.agent/templates/`, `.agent/skills/`, `.agent/modules/{installed}/`
+- `.agent/FRAMEWORK_VERSION`
+- `.claude/commands/` shortcuts
+
+This **does NOT touch** (your content is safe):
+- `.agent/project-context.yaml`
+- `CLAUDE.md`
+- `specs/domain-knowledge/` (business-dictionary, core-entities)
+- `.trace/`
+
+If the npx command exits non-zero → print the error and stop with `❌`.
+
+---
+
+## Step 5 — Review Changes
+
+Run:
+```bash
+git diff --stat .agent/ .claude/commands/
+```
+
+Summarize for the user:
+- **New commands** — `.md` files present now but not before
+- **Updated commands** — files with changed content
+- **Removed commands** — files deleted in the new version
+
+If a new command appeared (e.g. a new slash command), call it out explicitly so the user knows it is now available.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/update-framework — v{current} → v{latest}
+
+✅ Framework upgraded
+   Updated : {N} command files, {M} step files
+   New     : {list any new commands, e.g. /some-new-command}
+   Removed : {list any removed commands, or "none"}
+
+Your content was preserved:
+   project-context.yaml, CLAUDE.md, domain-knowledge/, .trace/ — untouched
+
+Review & commit:
+   git diff .agent/
+   git add .agent/ .claude/commands/
+   git commit -m "chore: upgrade spec-driven-dev v{current} → v{latest}"
+   {umbrella mode: this is the umbrella root — service submodules need no framework update}
+
+---
+Status : ✅ Complete | ⚠️ Warnings
+Output Artifacts: refreshed .agent/ framework files, .claude/commands/ shortcuts
+Next   : review git diff, then commit | /sync to refresh project content
+```

package/commands/validate-traces.md

@@ -180,6 +180,37 @@ If `services` section is present:
 - 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).
 
 ---
 
@@ -273,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.
@@ -288,7 +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}
 ```
 
@@ -314,12 +366,33 @@ Proceed to the next step of the calling command.
 
 ## Process
 
+### Step 0 — Umbrella Mode Detection
+
+Check whether `services` array exists in `project-context.yaml`.
+
+**If `services` exists (umbrella mode):**
+- Resolve the trace dir for each service:
+  - Use `services[N].trace_dir` if explicitly set
+  - Otherwise default to `{services[N].path}/.trace`
+- Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
+- Set `umbrella_root_trace = ".trace"` (at umbrella workspace root)
+- Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
+
+**If no `services` key (single-service mode):**
+- Set `all_trace_dirs = [ {paths.trace_dir} ]`
+- No umbrella sync needed
+
+---
+
 ### Step 1 — Load TSV data
 
-Read all `{paths.trace_dir}/{UC-ID}.tsv` files matching the target domain (or all domains if no domain filter).
+**Umbrella mode:** read all `{trace_dir}/{UC-ID}.tsv` files from every dir in `all_trace_dirs`. For each TSV, tag its rows with the originating service name.
+
+**Single-service mode:** read all `{paths.trace_dir}/{UC-ID}.tsv` files matching the target domain (or all domains if no domain filter).
+
 Each file gives the persisted trace state for that UC.
 
-**If no `.tsv` files found** in `{paths.trace_dir}`:
+**If no `.tsv` files found** in any of the trace dirs:
 - Scan all `{paths.specs_dir}/**/*.feature` files in the target domain to build an in-memory list of all scenarios.
 - Treat all scenarios as `UNTRACKED` (no code generated yet).
 - Print: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
@@ -499,6 +572,36 @@ Schema:
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
 - **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`
 
+### Step 8b — Umbrella Living Docs Sync *(umbrella mode only)*
+
+*Skip this step in single-service mode.*
+
+After writing each service's `trace-report.json`, sync trace files to the umbrella root so the Living Docs VS Code panel (opened at umbrella root) can read them:
+
+1. Create directory `{umbrella_root_trace}/` if it does not exist (`mkdir -p .trace`).
+
+2. **Copy TSV files** from each service trace dir to umbrella trace dir with service namespace:
+   ```
+   {service.path}/.trace/{UC-ID}.tsv  →  .trace/{service-name}/{UC-ID}.tsv
+   ```
+   Overwrite if exists. Do not delete files in `.trace/` that no longer have a service source — they may be from a previous run.
+
+3. **Write aggregated `trace-report.json`** to `{umbrella_root_trace}/trace-report.json`:
+   - Merge all per-service `trace-report.json` data into one document
+   - Add `"service"` field to each scenario row
+   - Recalculate summary aggregates across all services
+
+4. **Print sync summary:**
+   ```
+   Umbrella sync → .trace/
+     user-service  : {N} TSV files copied
+     order-service : {N} TSV files copied
+     trace-report.json: merged ({total} scenarios across {S} services)
+   Living Docs panel will reflect this data immediately.
+   ```
+
+> **Note:** `.trace/` at umbrella root is a **read-only mirror** — do NOT commit it to the umbrella repo. Add `.trace/` to the umbrella's `.gitignore`. Authoritative trace state lives in each service submodule's `.trace/` dir and is committed there.
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -548,6 +651,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:
 ```
@@ -595,4 +703,9 @@ Recommendations:
   - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
   - /generate-tests {UC-ID}     for GAP (missing tests)
   - /generate-bdd {prd-file}    for PRD version drift
+
+[Umbrella mode only]
+Living Docs synced → .trace/ (umbrella root)
+  Tip: run /validate-traces after each codegen session to refresh the panel.
+  .trace/ at umbrella root is a mirror — do not commit it (add to .gitignore).
 ```

package/commands/validate-traces.tmpl

@@ -14,12 +14,33 @@ Read-only check of coverage between specs, code, and tests — including PRD ver
 
 ## Process
 
+### Step 0 — Umbrella Mode Detection
+
+Check whether `services` array exists in `project-context.yaml`.
+
+**If `services` exists (umbrella mode):**
+- Resolve the trace dir for each service:
+  - Use `services[N].trace_dir` if explicitly set
+  - Otherwise default to `{services[N].path}/.trace`
+- Set `all_trace_dirs = [ dir1, dir2, ... ]` — one per service
+- Set `umbrella_root_trace = ".trace"` (at umbrella workspace root)
+- Step 1 will read TSVs from ALL dirs in `all_trace_dirs`, tagged by service name
+
+**If no `services` key (single-service mode):**
+- Set `all_trace_dirs = [ {paths.trace_dir} ]`
+- No umbrella sync needed
+
+---
+
 ### Step 1 — Load TSV data
 
-Read all `{paths.trace_dir}/{UC-ID}.tsv` files matching the target domain (or all domains if no domain filter).
+**Umbrella mode:** read all `{trace_dir}/{UC-ID}.tsv` files from every dir in `all_trace_dirs`. For each TSV, tag its rows with the originating service name.
+
+**Single-service mode:** read all `{paths.trace_dir}/{UC-ID}.tsv` files matching the target domain (or all domains if no domain filter).
+
 Each file gives the persisted trace state for that UC.
 
-**If no `.tsv` files found** in `{paths.trace_dir}`:
+**If no `.tsv` files found** in any of the trace dirs:
 - Scan all `{paths.specs_dir}/**/*.feature` files in the target domain to build an in-memory list of all scenarios.
 - Treat all scenarios as `UNTRACKED` (no code generated yet).
 - Print: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
@@ -199,6 +220,36 @@ Schema:
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
 - **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`
 
+### Step 8b — Umbrella Living Docs Sync *(umbrella mode only)*
+
+*Skip this step in single-service mode.*
+
+After writing each service's `trace-report.json`, sync trace files to the umbrella root so the Living Docs VS Code panel (opened at umbrella root) can read them:
+
+1. Create directory `{umbrella_root_trace}/` if it does not exist (`mkdir -p .trace`).
+
+2. **Copy TSV files** from each service trace dir to umbrella trace dir with service namespace:
+   ```
+   {service.path}/.trace/{UC-ID}.tsv  →  .trace/{service-name}/{UC-ID}.tsv
+   ```
+   Overwrite if exists. Do not delete files in `.trace/` that no longer have a service source — they may be from a previous run.
+
+3. **Write aggregated `trace-report.json`** to `{umbrella_root_trace}/trace-report.json`:
+   - Merge all per-service `trace-report.json` data into one document
+   - Add `"service"` field to each scenario row
+   - Recalculate summary aggregates across all services
+
+4. **Print sync summary:**
+   ```
+   Umbrella sync → .trace/
+     user-service  : {N} TSV files copied
+     order-service : {N} TSV files copied
+     trace-report.json: merged ({total} scenarios across {S} services)
+   Living Docs panel will reflect this data immediately.
+   ```
+
+> **Note:** `.trace/` at umbrella root is a **read-only mirror** — do NOT commit it to the umbrella repo. Add `.trace/` to the umbrella's `.gitignore`. Authoritative trace state lives in each service submodule's `.trace/` dir and is committed there.
+
 ## Output
 
 {{include:steps/report-footer.md}}
@@ -240,4 +291,9 @@ Recommendations:
   - /generate-code {UC-ID}      for DRIFT and UNTRACKED scenarios
   - /generate-tests {UC-ID}     for GAP (missing tests)
   - /generate-bdd {prd-file}    for PRD version drift
+
+[Umbrella mode only]
+Living Docs synced → .trace/ (umbrella root)
+  Tip: run /validate-traces after each codegen session to refresh the panel.
+  .trace/ at umbrella root is a mirror — do not commit it (add to .gitignore).
 ```

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

package/core/commands/debug.md

@@ -181,6 +181,37 @@ If `services` section is present:
 - 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).
 
 ---
 
@@ -274,6 +305,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.
@@ -289,7 +339,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}
 ```
 
@@ -562,6 +614,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:
 ```
@@ -594,3 +651,98 @@ See CLAUDE.md §{section}
 - To fully fix → /fix-bug {TICKET_ID}
 - Just needed analysis → done
 ```
+
+---
+
+## Offer to Record a Lesson (optional)
+
+If the root cause is a **mistake the AI made when generating code and could repeat**
+(not an environment/config issue or external cause), ask:
+
+```
+This looks like a repeatable AI mistake. Record it as a project lesson? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `source=/debug`, an appropriate `category`
+(usually `code-gen`), and `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/core/commands/define-product.md

@@ -178,6 +178,37 @@ If `services` section is present:
 - 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).
 
 ---
 
@@ -271,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.
@@ -286,7 +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}
 ```
 
@@ -496,6 +548,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:
 ```