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

package/commands/generate-code.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}
 ```
 
@@ -330,6 +382,39 @@ Read:
 
 ---
 
+## Phase Detection
+
+Parse `$ARGUMENTS` for a `--phase` flag:
+
+| Flag | Meaning |
+|---|---|
+| `--phase=ui` | FE Phase 1 — generate UI + mock API layer from System BDD contract |
+| `--phase=integration` | FE Phase 2 — replace mock adapter with real API calls from tech docs |
+| *(none)* | Default — full implementation (BE or full-stack without mock split) |
+
+**If `--phase` is set — confirm platform:**
+Read `@trace.platform` from the feature file header.
+- If `system` → warn: "`--phase` flag is not applicable for system BDD (BE-facing). Proceeding with default mode." Treat as no flag.
+- If `web` or `app` → continue with phase logic below.
+
+**If `--phase=ui`:**
+Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
+Extract all `Then` clauses → collect implied response shapes and error states.
+If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
+
+**If `--phase=integration`:**
+Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
+If `draft` or `in-review` → warn:
+```
+⚠ Tech docs for {UC-ID} are {status}.
+  BE may not have a stable API contract yet.
+  Proceeding — ensure BE endpoint is deployed or confirm contract manually.
+```
+Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
+If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
+
+---
+
 ## Read Trace State
 
 Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
@@ -374,6 +459,7 @@ Ticket   : {TICKET_ID if known}
 Domain   : {domain}
 UC       : {UC-ID} only  ← other feature files in this folder are NOT read
 Tech     : {language} / {framework}
+Phase    : {UI — mock layer | Integration — real API | Default — full}   ← omit if no --phase flag
 Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
 Layer    : {from CLAUDE.md §2}
 
@@ -420,6 +506,53 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
 
+## Mock API Layer (`--phase=ui` only)
+
+*Skip this section entirely if `--phase` is not `ui`.*
+
+Using the System BDD `Then` clauses loaded in Phase Detection:
+
+1. **Extract fixture data** per scenario — success responses + error responses.
+2. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+   - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
+   - Each method returns fixture data matching the BDD `Then` clause
+   - Include both success and error states (map to error scenarios in BDD)
+   - Traceability tags:
+     ```
+     @trace.mock_for={UC-ID}
+     @trace.system_bdd={paths.specs_dir}/{domain}/system/{UC-ID}*.feature
+     ```
+3. **Wire into service/hook layer** via environment flag or DI:
+   ```
+   const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
+   ```
+   - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
+
+> Tester uses the mock adapter to test all FE scenarios without waiting for BE.
+> Mock fixture data is derived directly from System BDD — BDD is the source of truth.
+
+---
+
+## Integration Phase (`--phase=integration` only)
+
+*Skip this section entirely if `--phase` is not `integration`.*
+
+1. **Read tech-doc API contract** from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` — extract endpoints, request/response shapes, error codes.
+2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
+3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
+   - Implements the same `{UC-ID}ApiPort` interface as mock adapter
+   - Makes real HTTP calls to endpoints from tech-doc contract
+   - Maps response fields to the same shapes the mock adapter returned
+   - Traceability tags:
+     ```
+     @trace.implements={UC-ID}-SC{N}
+     @trace.tech_doc_revision={read from tech-doc header}
+     ```
+4. **Flip wire-up**: switch DI binding / env flag so service/hook uses `{UC-ID}ApiAdapter` (real) instead of mock.
+5. **Do NOT delete mock adapter** — keep it for unit testing.
+
+---
+
 ## Self-Review (3 rounds)
 - [ ] Every scenario has a corresponding endpoint
 - [ ] @trace.implements on every endpoint
@@ -442,6 +575,7 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `implemented_by` | `{ControllerClass}.{methodName}` |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
 | `tech_doc_revision` | `@trace.revision` from tech-doc header, or `—` if no tech-doc |
+| `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
 Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
@@ -502,6 +636,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:
 ```
@@ -516,7 +655,20 @@ Next   : {suggested command with example arguments}
 /generate-code Complete — {UC-ID}
 Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
+Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
+fe_phase : {ui | integrated | —}
+
 Next:
-  First generation for this UC → /review-code {UC-ID}   ← code review required before tests
-  Re-generation (already reviewed) → /generate-tests {UC-ID}
+  --phase=ui done:
+    → Notify tester: FE is testable via mock adapter
+    → Collect BE sign-offs → /review-tech-docs {tech-design-file}
+    → When BE ready → /generate-code {feature-file} --phase=integration
+
+  --phase=integration done:
+    → /review-code {UC-ID}   ← code review required
+    → /generate-tests {UC-ID}  ← integration test suite
+
+  Default (no phase flag):
+    → /review-code {UC-ID}   ← code review required before tests
+    → /generate-tests {UC-ID}
 ```

package/commands/generate-code.tmpl

@@ -30,6 +30,39 @@ Read:
 
 ---
 
+## Phase Detection
+
+Parse `$ARGUMENTS` for a `--phase` flag:
+
+| Flag | Meaning |
+|---|---|
+| `--phase=ui` | FE Phase 1 — generate UI + mock API layer from System BDD contract |
+| `--phase=integration` | FE Phase 2 — replace mock adapter with real API calls from tech docs |
+| *(none)* | Default — full implementation (BE or full-stack without mock split) |
+
+**If `--phase` is set — confirm platform:**
+Read `@trace.platform` from the feature file header.
+- If `system` → warn: "`--phase` flag is not applicable for system BDD (BE-facing). Proceeding with default mode." Treat as no flag.
+- If `web` or `app` → continue with phase logic below.
+
+**If `--phase=ui`:**
+Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
+Extract all `Then` clauses → collect implied response shapes and error states.
+If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
+
+**If `--phase=integration`:**
+Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
+If `draft` or `in-review` → warn:
+```
+⚠ Tech docs for {UC-ID} are {status}.
+  BE may not have a stable API contract yet.
+  Proceeding — ensure BE endpoint is deployed or confirm contract manually.
+```
+Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
+If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
+
+---
+
 ## Read Trace State
 
 Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
@@ -74,6 +107,7 @@ Ticket   : {TICKET_ID if known}
 Domain   : {domain}
 UC       : {UC-ID} only  ← other feature files in this folder are NOT read
 Tech     : {language} / {framework}
+Phase    : {UI — mock layer | Integration — real API | Default — full}   ← omit if no --phase flag
 Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
 Layer    : {from CLAUDE.md §2}
 
@@ -120,6 +154,53 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
 
+## Mock API Layer (`--phase=ui` only)
+
+*Skip this section entirely if `--phase` is not `ui`.*
+
+Using the System BDD `Then` clauses loaded in Phase Detection:
+
+1. **Extract fixture data** per scenario — success responses + error responses.
+2. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+   - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
+   - Each method returns fixture data matching the BDD `Then` clause
+   - Include both success and error states (map to error scenarios in BDD)
+   - Traceability tags:
+     ```
+     @trace.mock_for={UC-ID}
+     @trace.system_bdd={paths.specs_dir}/{domain}/system/{UC-ID}*.feature
+     ```
+3. **Wire into service/hook layer** via environment flag or DI:
+   ```
+   const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
+   ```
+   - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
+
+> Tester uses the mock adapter to test all FE scenarios without waiting for BE.
+> Mock fixture data is derived directly from System BDD — BDD is the source of truth.
+
+---
+
+## Integration Phase (`--phase=integration` only)
+
+*Skip this section entirely if `--phase` is not `integration`.*
+
+1. **Read tech-doc API contract** from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` — extract endpoints, request/response shapes, error codes.
+2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
+3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
+   - Implements the same `{UC-ID}ApiPort` interface as mock adapter
+   - Makes real HTTP calls to endpoints from tech-doc contract
+   - Maps response fields to the same shapes the mock adapter returned
+   - Traceability tags:
+     ```
+     @trace.implements={UC-ID}-SC{N}
+     @trace.tech_doc_revision={read from tech-doc header}
+     ```
+4. **Flip wire-up**: switch DI binding / env flag so service/hook uses `{UC-ID}ApiAdapter` (real) instead of mock.
+5. **Do NOT delete mock adapter** — keep it for unit testing.
+
+---
+
 ## Self-Review (3 rounds)
 - [ ] Every scenario has a corresponding endpoint
 - [ ] @trace.implements on every endpoint
@@ -142,6 +223,7 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `implemented_by` | `{ControllerClass}.{methodName}` |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
 | `tech_doc_revision` | `@trace.revision` from tech-doc header, or `—` if no tech-doc |
+| `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
 Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
@@ -161,7 +243,20 @@ git commit -m "{commit_format}: {description}"
 /generate-code Complete — {UC-ID}
 Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
+Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
+fe_phase : {ui | integrated | —}
+
 Next:
-  First generation for this UC → /review-code {UC-ID}   ← code review required before tests
-  Re-generation (already reviewed) → /generate-tests {UC-ID}
+  --phase=ui done:
+    → Notify tester: FE is testable via mock adapter
+    → Collect BE sign-offs → /review-tech-docs {tech-design-file}
+    → When BE ready → /generate-code {feature-file} --phase=integration
+
+  --phase=integration done:
+    → /review-code {UC-ID}   ← code review required
+    → /generate-tests {UC-ID}  ← integration test suite
+
+  Default (no phase flag):
+    → /review-code {UC-ID}   ← code review required before tests
+    → /generate-tests {UC-ID}
 ```

package/commands/generate-design-spec.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}
 ```
 
@@ -733,6 +785,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-prd.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}
 ```
 
@@ -384,6 +436,7 @@ Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below
 | **Domain**    | {domain}                         |
 | **Created**   | {YYYY-MM-DD}                     |
 | **Updated**   | {YYYY-MM-DD}                     |
+| **API Source** | *(bỏ trống nếu greenfield — thêm `existing` nếu API đã tồn tại trên hệ thống)* |
 
 ---
 
@@ -397,13 +450,14 @@ Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below
 
 ## a. User Story
 
-As a {User role}
-I want to {User goal}
-So that {Business value}
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
 
 ## b. Scope
 
-In Scope
+**In Scope**
+
 - {Function 1}
 - {Function 2}
 
@@ -411,24 +465,36 @@ In Scope
 
 # 2. Acceptance Criteria
 
-AC1: {Acceptance criterion — testable, observable, no UI details}
-AC2: {Acceptance criterion}
+- **AC1:** {Acceptance criterion — testable, observable, no UI details}
+- **AC2:** {Acceptance criterion}
 
 ---
 
 # 3. Use Case
 
 #### {TICKET-ID}-UC1: {Use Case Name}
-Actor: {User performing the action}
-Description: {Business scenario description — 1 sentence}
-Pre-condition: {Condition that must be true BEFORE use case begins}
-Post-condition: {State / result AFTER use case completes}
 
-Business Rule
-| ID                      | Business Rule                        | Business Logic                            |
-|-------------------------|--------------------------------------|-------------------------------------------|
-| {TICKET-ID}-UC1-BR1     | {Rule — WHAT the system must do}    | - Logic 1<br/>- Logic 2<br/>- Logic 3    |
-| {TICKET-ID}-UC1-BR2     | {Rule}                               | - Logic                                  |
+- **Actor:** {User performing the action}
+- **Description:** {Business scenario description — 1 sentence}
+- **Pre-condition:** {Condition that must be true BEFORE use case begins}
+- **Post-condition:** {State / result AFTER use case completes}
+
+**Business Rule**
+
+| ID | Business Rule |
+|----|---------------|
+| {TICKET-ID}-UC1-BR1 | {Rule — WHAT the system must do} |
+| {TICKET-ID}-UC1-BR2 | {Rule} |
+
+**Business Logic**
+
+**{TICKET-ID}-UC1-BR1:**
+- Logic 1
+- Logic 2
+- Logic 3
+
+**{TICKET-ID}-UC1-BR2:**
+- Logic
 
 ---
 
@@ -450,11 +516,16 @@ flowchart TD
 
 **Screen 1: {Screen Name}**
 
-| Component      | Details                                                         |
-|----------------|-----------------------------------------------------------------|
-| **Screen**     | {Screen name}                                                   |
-| **Components** | - {Component 1}<br/>- {Component 2}<br/>- {Component 3}        |
-| **Actions**    | - {Action 1} → {Result}<br/>- {Action 2} → {Result}           |
+**Screen:** {Screen name}
+
+**Components:**
+- {Component 1}
+- {Component 2}
+- {Component 3}
+
+**Actions:**
+- {Action 1} → {Result}
+- {Action 2} → {Result}
 
 ---
 
@@ -468,6 +539,23 @@ flowchart TD
 
 - {[TICKET-ID](./TICKET-ID-slug.md) — relationship description}
 
+## Existing API Contract *(chỉ điền khi API Source = existing)*
+
+> API đã tồn tại trên hệ thống. PO ghi lại contract để BDD generation dùng trực tiếp —
+> không cần tổng hợp từ FE/App BDD, không cần T7 sign-off gate.
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
+
+---
+
 ## AI Assumptions
 
 > Assumptions AI made when information was incomplete. Needs PO review and confirmation.
@@ -487,6 +575,7 @@ flowchart TD
 - [ ] No banned terms (if dictionary exists)
 - [ ] User Flow includes error path / exception path
 - [ ] Wireframe covers all screens related to Use Cases
+- [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
 
 ## Changelog Section (append at end of PRD)
 
@@ -551,6 +640,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:
 ```