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

package/core/commands/generate-tech-docs.md

@@ -196,13 +196,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -453,25 +454,49 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 ---
 
 ## §1. Overview
+
+{Tóm tắt ngắn: UC này implement gì, scope kỹ thuật chính.}
+
 ## §2. API Endpoints
-  *Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
-  *Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD.
-    Ghi chú gaps nếu contract thực tế khác với BDD expectations.
-  | Method | Path | Auth/Role | Request | Response |
+
+*Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
+*Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD. Ghi chú gaps nếu contract thực tế khác với BDD expectations.
+
+| Method | Path | Auth/Role | Request | Response |
+|--------|------|-----------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/...} | {Bearer / role} | `{ field: type }` | `{ field: type }` |
+
 ## §3. Data Model
-  Key entities and relationships.
+
+Key entities and relationships.
+
 ## §4. Service Flow
-  {Client} → Controller → {Facade/Service} → {Repository}
+
+{Client} → Controller → {Facade/Service} → {Repository}
+
 ## §5. Business Rules Implementation
-  | BR-ID | Rule | Implementation approach |
+
+| BR-ID | Rule | Implementation approach |
+|-------|------|-------------------------|
+| {UC-ID}-BR1 | {rule} | {approach} |
+
 ## §6. Error Handling
-  | Scenario | Exception | HTTP Status |
+
+| Scenario | Exception | HTTP Status |
+|----------|-----------|-------------|
+| {scenario} | {ExceptionClass} | {4xx/5xx} |
+
 ## §7. Database Changes
-  Migration scripts or schema changes.
+
+Migration scripts or schema changes.
+
 ## §8. Caching Strategy
-  What to cache, TTL, invalidation triggers.
+
+What to cache, TTL, invalidation triggers.
+
 ## §9. Cross-Service Dependencies
-  External calls, events produced/consumed.
+
+External calls, events produced/consumed.
 
 ## Changelog
 
@@ -480,6 +505,21 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
+## Publish — share the contract (umbrella + shared spec repo)
+
+If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the tech-doc was just written **inside the spec submodule**. It is the cross-team **API contract** — FE/App read it via their own `/sync`. Publish it so they can (2-layer commit):
+
+```bash
+cd {spec_source}
+git add specs/tech-docs/{domain}/{UC-ID}-tech-design.md
+git commit -m "docs({UC-ID}): tech design / API contract"
+git push origin {spec_branch}          # the branch FE/App track in .gitmodules
+cd -
+git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} tech design)"
+```
+
+If `tech_docs_dir` is **local** (single-service, or per-service routing in a multi-service umbrella), skip this — no cross-repo publish needed.
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -549,5 +589,6 @@ Next   : {suggested command with example arguments}
 File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
 Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
       ← SA/Lead review required before code generation
+      → if tech-docs live in the shared spec repo: commit + push to the spec submodule (see Publish above) so FE/App `/sync` can read the contract
       → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
 ```

package/core/commands/generate-tests.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/learn.md

@@ -184,13 +184,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/propose-scenario.md

@@ -184,13 +184,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/refine-prd.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -389,7 +390,9 @@ findings:
   - id: "F001"
     lens: "QA"           # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
-    section: "§6. Acceptance Criteria"
+    section: "§6. Acceptance Criteria"   # human-readable heading/section label
+    uc_id: "{TICKET-ID}-UC{N}"           # UC this finding belongs to; "" if PRD-global (scope, metrics, problem statement)
+    quote: "{verbatim snippet copied EXACTLY from the PRD at the issue location, ≤120 chars}"
     finding: "{description of gap or issue}"
     suggestion: "{specific actionable improvement}"
     auto_fixable: false  # true = AI applies in --resume; false = human must write decision in note
@@ -402,6 +405,12 @@ summary:
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the PRD at the exact spot the
+> issue occurs — do NOT paraphrase; it is matched against the document to locate the line. Set
+> `uc_id` to the owning Use Case (or `""` for PRD-global findings). These let a reviewer click a
+> finding in the Review Board and jump straight to the precise location in the source PRD.
+
 ## Report
 
 # Report Footer — Standard Command Output Format

package/core/commands/report-bug.md

@@ -184,13 +184,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/review-code.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/review-context.md

@@ -182,13 +182,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -563,6 +564,8 @@ findings:
     check_id: "P1"           # P1-P5 for PRD; B1-B6 for BDD
     severity: "critical"     # critical | major | minor
     section: "{section or scenario ID where issue was found}"
+    uc_id: "{UC-ID this finding belongs to — PRD: the UC heading; BDD: @trace.id; \"\" if global}"
+    quote: "{verbatim snippet copied EXACTLY from the reviewed file at the issue location, ≤120 chars}"
     finding: "{clear description of the issue}"
     suggestion: "{specific actionable fix — AI will apply this in --resume if accepted}"
     auto_fixable: true       # true = AI can apply; false = human must write note in Review Board
@@ -576,6 +579,12 @@ summary:
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the reviewed file at the exact
+> spot the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> Set `uc_id` to the owning Use Case (`@trace.id` for BDD, the UC heading for PRD; `""` if global).
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Post-Analysis Routing
 
 After running all checks and writing the findings file:

package/core/commands/review-tech-docs.md

@@ -179,13 +179,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -554,6 +555,8 @@ findings:
     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
@@ -568,6 +571,11 @@ summary:
   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
@@ -717,4 +725,5 @@ Sign-off : {✅ All done — status set to approved
 Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
 Next: {/generate-code {feature-file}  ← only if status = approved
       | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
+      → if the tech-doc lives in the shared spec repo: commit + push it to the spec submodule so FE/App `/sync` the updated contract
 ```

package/core/commands/run-tests.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/smoke-test.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/validate-traces.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/modules/android-compose/module.yaml

@@ -0,0 +1,13 @@
+name: "Android (Jetpack Compose)"
+version: "1.0.0"
+description: "Native Android development with Jetpack Compose + Kotlin"
+language: "Kotlin"
+framework: "Jetpack Compose"
+stack_type: "mobile"
+default_layer_order:
+  - Domain models
+  - Repository (data layer)
+  - UseCase (domain logic)
+  - ViewModel (StateFlow<UiState>)
+  - Composable screens (presentation)
+test_framework: "JUnit5 + MockK + Turbine"

package/core/modules/android-compose/stack-profile.yaml

@@ -0,0 +1,57 @@
+build:
+  compile: "./gradlew assembleRelease"
+  test: "./gradlew test"
+  run: "./gradlew installDebug / Open in Android Studio → Run"
+  lint: "./gradlew lint"
+
+architecture:
+  style: "MVVM + Clean Architecture (Composable → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Composables are pure UI functions — no business logic, no direct suspend calls"
+    - "ViewModels expose StateFlow<UiState>; Composables collect via collectAsStateWithLifecycle()"
+    - "UseCases are single-responsibility classes injected into ViewModels"
+    - "Repositories are interfaces; implementations live in the data layer"
+    - "Dependency injection via Hilt"
+    - "Never launch coroutines from a Composable directly — use LaunchedEffect or ViewModel"
+  folder_structure: |
+    src/main/java/{package}/
+    ├── core/
+    │   ├── network/      ← Retrofit instance, interceptors
+    │   ├── theme/        ← MaterialTheme, Color, Type, Shape
+    │   └── utils/
+    ├── shared/
+    │   └── components/   ← reusable Composables (AppButton, AppTextField...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── ui/           ← Composable screens + components
+    │       ├── viewmodel/    ← ViewModel + UiState
+    │       ├── domain/       ← UseCases, domain models
+    │       └── data/         ← Repository impl, data sources
+
+coding_standards:
+  naming:
+    composables: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      screen: "{Feature}Screen.kt"
+      viewmodel: "{Feature}ViewModel.kt"
+      usecase: "{Feature}UseCase.kt"
+  patterns:
+    state_management: "StateFlow<UiState> in ViewModel"
+    navigation: "Jetpack Navigation Compose"
+    networking: "Retrofit + OkHttp"
+    serialization: "Kotlinx Serialization or Gson"
+    di: "Hilt"
+    async: "Kotlin Coroutines + Flow"
+
+testing:
+  unit: "JUnit5 + MockK + Turbine (Flow testing)"
+  ui: "Compose UI Test (composeTestRule)"
+  patterns:
+    - "Test ViewModel with fake repositories and TestCoroutineDispatcher"
+    - "UI tests use semantics matchers — set Modifier.testTag() on Composables"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/core/modules/flutter/module.yaml

@@ -0,0 +1,14 @@
+name: "Flutter"
+version: "1.0.0"
+description: "Cross-platform mobile (iOS + Android) with Flutter/Dart"
+language: "Dart"
+framework: "Flutter"
+stack_type: "mobile"
+default_layer_order:
+  - Models / entities (domain)
+  - Repositories (data layer)
+  - Use cases (domain logic)
+  - BLoC / Cubit or Riverpod providers (state)
+  - Widgets (presentation)
+  - Pages / screens
+test_framework: "flutter_test + mocktail"

package/core/modules/flutter/stack-profile.yaml

@@ -0,0 +1,59 @@
+build:
+  compile: "flutter build apk / flutter build ios"
+  test: "flutter test"
+  run: "flutter run"
+  lint: "flutter analyze"
+
+architecture:
+  style: "Feature-based (presentation → domain → data)"
+  key_rules:
+    - "Widget tree is pure UI — business logic lives in BLoC/Cubit or Riverpod providers"
+    - "Repositories abstract data sources; services contain domain logic"
+    - "State management: BLoC (complex flows) or Riverpod (simple/medium)"
+    - "Never call API directly inside a Widget build() method"
+    - "Shared UI widgets in lib/shared/widgets/, feature widgets in lib/features/{name}/presentation/"
+    - "Use const constructors wherever possible for performance"
+  folder_structure: |
+    lib/
+    ├── core/
+    │   ├── theme/        ← AppTheme, colors, text styles
+    │   ├── router/       ← GoRouter or auto_route
+    │   └── utils/
+    ├── shared/
+    │   └── widgets/      ← reusable UI widgets (AppButton, AppInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── data/         ← repositories, data sources, models
+    │       ├── domain/       ← entities, use cases, repo interfaces
+    │       └── presentation/ ← pages, widgets, BLoC/Cubit
+    └── main.dart
+
+coding_standards:
+  naming:
+    widgets: "PascalCase (e.g., OrderListPage, CreateOrderForm)"
+    blocs: "PascalCase + Bloc/Cubit suffix (e.g., OrderListCubit)"
+    repositories: "PascalCase + Repository suffix (e.g., OrderRepository)"
+    files:
+      page: "{feature}_page.dart"
+      widget: "{feature}_widget.dart"
+      cubit: "{feature}_cubit.dart"
+      repository: "{feature}_repository.dart"
+      model: "{feature}_model.dart"
+  patterns:
+    state_management: "BLoC / Cubit (flutter_bloc) or Riverpod"
+    navigation: "GoRouter or auto_route"
+    networking: "Dio with interceptors"
+    serialization: "json_serializable / freezed"
+
+testing:
+  unit: "flutter_test + mocktail"
+  widget: "flutter_test WidgetTester"
+  integration: "integration_test package"
+  patterns:
+    - "Test BLoC/Cubit in isolation with fake repositories"
+    - "Widget tests pump the widget tree and find by key or semantics label"
+    - "Use goldenFileComparator for snapshot tests of complex widgets"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/core/modules/ios-swiftui/module.yaml

@@ -0,0 +1,13 @@
+name: "iOS (SwiftUI)"
+version: "1.0.0"
+description: "Native iOS development with SwiftUI + Swift"
+language: "Swift"
+framework: "SwiftUI"
+stack_type: "mobile"
+default_layer_order:
+  - Models / entities
+  - Repository (data sources)
+  - UseCase (business operations)
+  - ViewModel (ObservableObject state)
+  - View (SwiftUI presentation)
+test_framework: "XCTest + Quick/Nimble"

package/core/modules/ios-swiftui/stack-profile.yaml

@@ -0,0 +1,55 @@
+build:
+  compile: "xcodebuild -scheme {AppName} -configuration Release"
+  test: "xcodebuild test -scheme {AppName}"
+  run: "Open in Xcode → Run (⌘R)"
+  lint: "swiftlint"
+
+architecture:
+  style: "MVVM + Clean Architecture (View → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Views are pure SwiftUI — no business logic, no direct API calls"
+    - "ViewModels are ObservableObject classes; bind via @StateObject / @ObservedObject"
+    - "UseCases encapsulate single business operations"
+    - "Repositories abstract data sources (network, cache, local DB)"
+    - "Dependency injection via environment or constructor injection"
+    - "Use Combine or async/await for async flows — never DispatchQueue in ViewModel"
+  folder_structure: |
+    Sources/
+    ├── Core/
+    │   ├── Network/      ← URLSession wrapper, interceptors
+    │   ├── Theme/        ← Color, Font, Spacing tokens
+    │   └── Utils/
+    ├── Shared/
+    │   └── Components/   ← reusable SwiftUI views (AppButton, AppTextField...)
+    ├── Features/
+    │   └── {Domain}/
+    │       ├── Views/
+    │       ├── ViewModels/
+    │       ├── UseCases/
+    │       └── Repository/
+
+coding_standards:
+  naming:
+    views: "PascalCase + View suffix (e.g., OrderListView, CreateOrderView)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      view: "{Feature}View.swift"
+      viewmodel: "{Feature}ViewModel.swift"
+      usecase: "{Feature}UseCase.swift"
+  patterns:
+    async: "async/await + Combine"
+    navigation: "NavigationStack (iOS 16+)"
+    persistence: "Core Data or SwiftData"
+    networking: "URLSession or Alamofire"
+
+testing:
+  unit: "XCTest + Quick/Nimble"
+  ui: "XCUITest"
+  patterns:
+    - "Test ViewModel by injecting mock repositories"
+    - "UI tests use accessibility identifiers — set .accessibilityIdentifier on Views"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"

package/core/modules/nuxt/module.yaml

@@ -0,0 +1,14 @@
+name: "Nuxt"
+version: "1.0.0"
+description: "Nuxt 3 with SSR/SSG, Composition API, Pinia, and useFetch"
+language: "TypeScript"
+framework: "Nuxt 3"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - Server API routes (server/api/)
+  - Composables (useFetch / useAsyncData)
+  - State store (Pinia)
+  - UI components (presentational)
+  - Page components (pages/)
+test_framework: "Vitest + Vue Test Utils + @nuxt/test-utils"