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

package/commands/review-tech-docs.md

@@ -182,6 +182,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).
 
 ---
 
@@ -275,6 +306,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.
@@ -290,7 +340,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}
 ```
 
@@ -422,6 +474,59 @@ Check all standard sections are present and non-empty:
 
 → All T6 missing-section findings are **auto-fixable**: AI adds skeleton section with prompts.
 
+### T7 — Cross-Team API Contract Review
+
+*Only applies when ALL of the following are true:*
+*1. Source BDD has `@trace.platform: system`.*
+*2. Tech-doc header does NOT have `@trace.api_source: existing`.*
+
+*If `@trace.api_source: existing` → **skip T7 entirely**. Contract đã được PO xác định trong PRD — không có API design mới để đồng thuận.*
+
+This dimension ensures FE, App, and BE teams all agree on the API contract before implementation starts.
+
+**Step 1 — Check sign-off status in tech-doc header:**
+
+Read the `@trace.sign_off` block in the tech doc header. If absent → add it as a finding (auto-fixable: add skeleton).
+
+```yaml
+# @trace.sign_off:
+#   be_team:  pending    # author — set to "done" when BE satisfied with design
+#   fe_team:  pending    # FE/Web — must confirm contract matches web BDD expectations
+#   app_team: pending    # App — must confirm contract matches app BDD expectations (if applicable)
+#   sa:       pending    # SA/Tech Lead — final approval
+```
+
+**Step 2 — Contract vs BDD cross-check:**
+
+Load the web and app BDDs for this TICKET-ID (from `{paths.specs_dir}/{domain}/web/` and `{paths.specs_dir}/{domain}/app/` in the spec submodule or spec repo).
+
+For each platform BDD, verify the tech doc's API contract satisfies the BDD's `Then` clauses:
+
+| Check | Severity |
+|---|---|
+| Response fields in API contract don't cover what web BDD `Then` expects | Critical |
+| Response fields in API contract don't cover what app BDD `Then` expects | Critical |
+| Error response shape doesn't match what platform BDDs expect | Major |
+| System BDD `@system.resolution` annotation contradicts the API contract design | Critical |
+
+**Step 3 — Pending sign-off report:**
+
+After the review, list which sign-offs are still `pending`:
+
+```
+⏳ Pending sign-offs before tech docs can be approved:
+  fe_team  — FE/Web team must confirm API contract matches web BDD expectations
+  app_team — App team must confirm API contract matches app BDD expectations
+  sa       — SA/Tech Lead final approval
+
+Once sign-offs are collected → update @trace.sign_off in tech doc header, then re-run /review-tech-docs.
+Tech docs cannot be set to "approved" while any required sign-off is pending.
+```
+
+**Approval gate:**
+- If `be_team: done` AND `fe_team: done` AND `app_team: done` (or N/A) AND `sa: done` → tech docs may be set to `approved`
+- Otherwise → `@trace.status` stays `in-review` — `generate-code` is blocked
+
 ---
 
 ## Write Findings File
@@ -435,12 +540,22 @@ domain: "{domain}"
 generated_at: "{ISO datetime}"
 review_type: "tech-design"
 status: "pending_review"
+is_system_bdd: {true | false}  # true if source BDD has @trace.platform: system
+
+sign_off:                       # only present when is_system_bdd: true
+  be_team:  pending             # read from @trace.sign_off in tech-doc header
+  fe_team:  pending
+  app_team: pending             # "n/a" if project has no app platform
+  sa:       pending
+sign_off_gate: blocked          # blocked | ready — "ready" only when all required are "done"
 
 findings:
   - id: "F001"
-    check_id: "T1"           # T1–T6
+    check_id: "T1"           # T1–T7
     severity: "critical"     # critical | major | minor
     section: "{section heading or component name where issue was found}"
+    uc_id: "{UC-ID}"         # same as top-level uc_id (the UC this tech-doc designs)
+    quote: "{verbatim snippet copied EXACTLY from the tech-doc at the issue location, ≤120 chars}"
     finding: "{clear description of the violation or gap}"
     suggestion: "{specific fix — AI applies this in --resume if accepted}"
     auto_fixable: false      # true = AI can apply; false = human must write decision in note
@@ -452,8 +567,14 @@ summary:
   auto_fixable: {N}
   requires_human_decision: {N}
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
+  sign_off_gate: "{blocked — pending: fe_team, app_team, sa | ready}"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the tech-doc at the exact spot
+> the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Report
 
 # Report Footer — Standard Command Output Format
@@ -503,6 +624,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:
 ```
@@ -519,9 +645,17 @@ UC: {UC-ID} | Domain: {domain}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Auto-fixable: {N} | Needs human decision: {N}
 
+Sign-off gate (system BDD only):
+  be_team  : {done | pending}
+  fe_team  : {done | pending}   ← {name / "needs sign-off" }
+  app_team : {done | pending | n/a}
+  sa       : {done | pending}
+  Gate     : {🔒 BLOCKED — pending: fe_team, sa | ✅ READY}
+
 Findings file: {paths.refinement_dir}/{uc-id}-tech-review-findings.yaml
 Next: Open in Review Board → Accept/Modify/Reject each finding
       Then run: /review-tech-docs --resume {tech-design-file}
+      After all sign-offs collected → update @trace.sign_off in tech doc, re-run review
 ```
 
 ---
@@ -556,7 +690,10 @@ Review Board "Modify" note. Apply exactly what the note says. Do not invent the
 
 Edit the tech-doc file directly:
 1. Find `@trace.revision:` in the header — increment its integer value by 1.
-2. Find `@trace.status:` in the header — set its value to `draft`.
+2. Find `@trace.status:` in the header:
+   - If sign_off_gate = `ready` (all sign-offs done) → set to `approved`
+   - Otherwise → set to `in-review` (blocks `/generate-code`)
+3. If `@trace.sign_off` block is absent and this is a system BDD tech doc → add it with all values `pending`.
 
 Write both changes to the file.
 
@@ -578,8 +715,13 @@ Changes:
   - {change 2}
 
 Revision : {old} → {new}
-Status   : reset to draft (re-approval required)
+Status   : {approved | in-review}
+
+Sign-off : {✅ All done — status set to approved
+           | 🔒 Pending: fe_team, sa — status set to in-review
+              Update @trace.sign_off in tech doc when each team confirms, then re-run /review-tech-docs}
 
 Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
-Next: /generate-code {feature-file}
+Next: {/generate-code {feature-file}  ← only if status = approved
+      | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
 ```

package/commands/review-tech-docs.tmpl

@@ -122,6 +122,59 @@ Check all standard sections are present and non-empty:
 
 → All T6 missing-section findings are **auto-fixable**: AI adds skeleton section with prompts.
 
+### T7 — Cross-Team API Contract Review
+
+*Only applies when ALL of the following are true:*
+*1. Source BDD has `@trace.platform: system`.*
+*2. Tech-doc header does NOT have `@trace.api_source: existing`.*
+
+*If `@trace.api_source: existing` → **skip T7 entirely**. Contract đã được PO xác định trong PRD — không có API design mới để đồng thuận.*
+
+This dimension ensures FE, App, and BE teams all agree on the API contract before implementation starts.
+
+**Step 1 — Check sign-off status in tech-doc header:**
+
+Read the `@trace.sign_off` block in the tech doc header. If absent → add it as a finding (auto-fixable: add skeleton).
+
+```yaml
+# @trace.sign_off:
+#   be_team:  pending    # author — set to "done" when BE satisfied with design
+#   fe_team:  pending    # FE/Web — must confirm contract matches web BDD expectations
+#   app_team: pending    # App — must confirm contract matches app BDD expectations (if applicable)
+#   sa:       pending    # SA/Tech Lead — final approval
+```
+
+**Step 2 — Contract vs BDD cross-check:**
+
+Load the web and app BDDs for this TICKET-ID (from `{paths.specs_dir}/{domain}/web/` and `{paths.specs_dir}/{domain}/app/` in the spec submodule or spec repo).
+
+For each platform BDD, verify the tech doc's API contract satisfies the BDD's `Then` clauses:
+
+| Check | Severity |
+|---|---|
+| Response fields in API contract don't cover what web BDD `Then` expects | Critical |
+| Response fields in API contract don't cover what app BDD `Then` expects | Critical |
+| Error response shape doesn't match what platform BDDs expect | Major |
+| System BDD `@system.resolution` annotation contradicts the API contract design | Critical |
+
+**Step 3 — Pending sign-off report:**
+
+After the review, list which sign-offs are still `pending`:
+
+```
+⏳ Pending sign-offs before tech docs can be approved:
+  fe_team  — FE/Web team must confirm API contract matches web BDD expectations
+  app_team — App team must confirm API contract matches app BDD expectations
+  sa       — SA/Tech Lead final approval
+
+Once sign-offs are collected → update @trace.sign_off in tech doc header, then re-run /review-tech-docs.
+Tech docs cannot be set to "approved" while any required sign-off is pending.
+```
+
+**Approval gate:**
+- If `be_team: done` AND `fe_team: done` AND `app_team: done` (or N/A) AND `sa: done` → tech docs may be set to `approved`
+- Otherwise → `@trace.status` stays `in-review` — `generate-code` is blocked
+
 ---
 
 ## Write Findings File
@@ -135,12 +188,22 @@ domain: "{domain}"
 generated_at: "{ISO datetime}"
 review_type: "tech-design"
 status: "pending_review"
+is_system_bdd: {true | false}  # true if source BDD has @trace.platform: system
+
+sign_off:                       # only present when is_system_bdd: true
+  be_team:  pending             # read from @trace.sign_off in tech-doc header
+  fe_team:  pending
+  app_team: pending             # "n/a" if project has no app platform
+  sa:       pending
+sign_off_gate: blocked          # blocked | ready — "ready" only when all required are "done"
 
 findings:
   - id: "F001"
-    check_id: "T1"           # T1–T6
+    check_id: "T1"           # T1–T7
     severity: "critical"     # critical | major | minor
     section: "{section heading or component name where issue was found}"
+    uc_id: "{UC-ID}"         # same as top-level uc_id (the UC this tech-doc designs)
+    quote: "{verbatim snippet copied EXACTLY from the tech-doc at the issue location, ≤120 chars}"
     finding: "{clear description of the violation or gap}"
     suggestion: "{specific fix — AI applies this in --resume if accepted}"
     auto_fixable: false      # true = AI can apply; false = human must write decision in note
@@ -152,8 +215,14 @@ summary:
   auto_fixable: {N}
   requires_human_decision: {N}
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
+  sign_off_gate: "{blocked — pending: fe_team, app_team, sa | ready}"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the tech-doc at the exact spot
+> the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Report
 
 {{include:steps/report-footer.md}}
@@ -164,9 +233,17 @@ UC: {UC-ID} | Domain: {domain}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Auto-fixable: {N} | Needs human decision: {N}
 
+Sign-off gate (system BDD only):
+  be_team  : {done | pending}
+  fe_team  : {done | pending}   ← {name / "needs sign-off" }
+  app_team : {done | pending | n/a}
+  sa       : {done | pending}
+  Gate     : {🔒 BLOCKED — pending: fe_team, sa | ✅ READY}
+
 Findings file: {paths.refinement_dir}/{uc-id}-tech-review-findings.yaml
 Next: Open in Review Board → Accept/Modify/Reject each finding
       Then run: /review-tech-docs --resume {tech-design-file}
+      After all sign-offs collected → update @trace.sign_off in tech doc, re-run review
 ```
 
 ---
@@ -201,7 +278,10 @@ Review Board "Modify" note. Apply exactly what the note says. Do not invent the
 
 Edit the tech-doc file directly:
 1. Find `@trace.revision:` in the header — increment its integer value by 1.
-2. Find `@trace.status:` in the header — set its value to `draft`.
+2. Find `@trace.status:` in the header:
+   - If sign_off_gate = `ready` (all sign-offs done) → set to `approved`
+   - Otherwise → set to `in-review` (blocks `/generate-code`)
+3. If `@trace.sign_off` block is absent and this is a system BDD tech doc → add it with all values `pending`.
 
 Write both changes to the file.
 
@@ -223,8 +303,13 @@ Changes:
   - {change 2}
 
 Revision : {old} → {new}
-Status   : reset to draft (re-approval required)
+Status   : {approved | in-review}
+
+Sign-off : {✅ All done — status set to approved
+           | 🔒 Pending: fe_team, sa — status set to in-review
+              Update @trace.sign_off in tech doc when each team confirms, then re-run /review-tech-docs}
 
 Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
-Next: /generate-code {feature-file}
+Next: {/generate-code {feature-file}  ← only if status = approved
+      | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
 ```

package/commands/run-tests.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}
 ```
 
@@ -317,6 +369,31 @@ Use it to select the correct run command and error analysis table below.
 
 ---
 
+## Submodule Working Directory
+
+*Skip this section if `service_root` is not set (single-service mode).*
+
+When running in **umbrella/submodule mode** (`service_root` was resolved in context-loader Step 1.6):
+
+- All commands in the **Run** section below must execute from within `{service_root}/`
+- `conventions.test_command` was loaded from `{service_root}/.agent/project-context.yaml` — already service-specific
+- Prefix every shell command with `cd {service_root} &&`:
+
+```bash
+cd {service_root}
+
+# Then run any of the commands in the Run section below, e.g.:
+{conventions.test_command}
+mvn test -Dtest={ClassName}            # java-spring
+go test ./... -run Test{FunctionName}  # golang
+npx vitest run src/...                 # web-frontend
+flutter test test/{domain}/...         # flutter
+```
+
+> **Why cd?** Claude Code session is opened at umbrella root. Each service submodule has its own build tool, test runner, and dependency tree — tests must run from inside the service directory.
+
+---
+
 ## Run
 
 ### If `platform_type = backend`
@@ -494,6 +571,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/run-tests.tmpl

@@ -17,6 +17,31 @@ Use it to select the correct run command and error analysis table below.
 
 ---
 
+## Submodule Working Directory
+
+*Skip this section if `service_root` is not set (single-service mode).*
+
+When running in **umbrella/submodule mode** (`service_root` was resolved in context-loader Step 1.6):
+
+- All commands in the **Run** section below must execute from within `{service_root}/`
+- `conventions.test_command` was loaded from `{service_root}/.agent/project-context.yaml` — already service-specific
+- Prefix every shell command with `cd {service_root} &&`:
+
+```bash
+cd {service_root}
+
+# Then run any of the commands in the Run section below, e.g.:
+{conventions.test_command}
+mvn test -Dtest={ClassName}            # java-spring
+go test ./... -run Test{FunctionName}  # golang
+npx vitest run src/...                 # web-frontend
+flutter test test/{domain}/...         # flutter
+```
+
+> **Why cd?** Claude Code session is opened at umbrella root. Each service submodule has its own build tool, test runner, and dependency tree — tests must run from inside the service directory.
+
+---
+
 ## Run
 
 ### If `platform_type = backend`

package/commands/setup-ai-first.md

@@ -417,6 +417,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:
 ```
@@ -453,11 +458,16 @@ Next:
      - Update services[].path to match actual submodule directory names
      - Update services domain keys to match @trace.domain in your PRD files
      - Confirm spec_source path is correct
-  2. Ensure spec submodule is initialized:
-     git submodule update --init --recursive
-  3. Pull latest specs from PO before generating:
-     git submodule update --remote {spec_source}
-  4. Start generating:
+
+  2. Run /sync — one command that handles everything else:
+     /sync
+     → git pull + submodule init + spec submodule update
+     → Auto-create .agent/project-context.yaml for each service submodule
+       (detects module from pom.xml / go.mod / package.json / pubspec.yaml etc.)
+     → Sync Living Docs panel
+     → Refresh spec-manifest.yaml
+
+  3. Start generating:
      /generate-bdd {spec_source}/specs/prd/{domain}/TICKET-ID-prd.md
 ```
 

package/commands/setup-ai-first.tmpl

@@ -317,11 +317,16 @@ Next:
      - Update services[].path to match actual submodule directory names
      - Update services domain keys to match @trace.domain in your PRD files
      - Confirm spec_source path is correct
-  2. Ensure spec submodule is initialized:
-     git submodule update --init --recursive
-  3. Pull latest specs from PO before generating:
-     git submodule update --remote {spec_source}
-  4. Start generating:
+
+  2. Run /sync — one command that handles everything else:
+     /sync
+     → git pull + submodule init + spec submodule update
+     → Auto-create .agent/project-context.yaml for each service submodule
+       (detects module from pom.xml / go.mod / package.json / pubspec.yaml etc.)
+     → Sync Living Docs panel
+     → Refresh spec-manifest.yaml
+
+  3. Start generating:
      /generate-bdd {spec_source}/specs/prd/{domain}/TICKET-ID-prd.md
 ```
 

package/commands/smoke-test.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}
 ```
 
@@ -548,6 +600,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:
 ```