@anhth2/spec-driven-dev-plugin 0.11.0 → 0.12.0

package/commands/qc-run-test.md

@@ -92,7 +92,7 @@ Wait for explicit "Y" or "N" from the user before continuing.
 - "N" → stop and ask what the user wants to change.
 
 
-*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.refinement_dir}/qc/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
+*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.qc_dir}/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -133,6 +133,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -145,6 +147,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -189,6 +193,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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.
 
@@ -407,7 +412,7 @@ Stack rules (MANDATORY — from `modules/qc-playwright/stack-profile.yaml`):
 - Cover **100%** of TCs in the file — every TC ends Pass/Fail/Skip (none left Draft).
 - Classify each FAIL: script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass).
 
-## Skills — pick the layer, load ONE file (`skills/qc/qa-runner/`)
+## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-runner/`)
 
 `functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
 `non-functional.md`, `exploratory/session.md`.
@@ -431,6 +436,12 @@ After the run, update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row
 |--------|-------|
 | `qc_status` | `pass` if all QC tests for this SC passed · `fail` if any failed · `skip` if all skipped/xfail · `not_run` if no QC test covers it |
 | `qc_run_at` | today `YYYY-MM-DD` |
+| `qc_owner` | **who the SC is waiting on** (the PM/PO "pending" view): `dev` if FAIL = product-gap (real defect → dev fixes) · `po` if `skip`/`not_run` because an **open `DOC_GAPS` 🔴 Blocker** prevents testing (PO must clarify PRD/BDD) · `—` if `pass`, or FAIL = script-bug (QC's own to fix — transient) |
+| `qc_blocked_by` | linked artifact: `GAP-{id}` when blocked by a spec gap (set here) · `BUG-{id}` once `/report-bug` is filed for the product-gap (backfilled by `/report-bug`) · `—` otherwise |
+
+Set `qc_owner`/`qc_blocked_by` together with `qc_status`. On `pass`, **clear** both to `—`.
+For a product-gap FAIL, set `qc_owner=dev` now; the `BUG-{id}` is backfilled into `qc_blocked_by`
+when QC runs the `/report-bug` that `/qc-report` prompts.
 
 Leave all other columns unchanged — **never** touch `dev_selftest`/`dev_selftest_at`
 (owned by `/dev-run-test`). `qc_status` (official QC) and `dev_selftest` (dev smoke) are

package/commands/qc-run-test.tmpl

@@ -11,7 +11,7 @@ ported_from: ai-automation-qc-base
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.refinement_dir}/qc/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
+*Note: For this command, the target in Step 1 is a UC-ID. Read the reviewed `.Test.md` from `{paths.qc_dir}/{UC-ID}/test-cases/`. This command uses the **qc-playwright** stack module (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — independent of the dev implementation module.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -31,7 +31,7 @@ Stack rules (MANDATORY — from `modules/qc-playwright/stack-profile.yaml`):
 - Cover **100%** of TCs in the file — every TC ends Pass/Fail/Skip (none left Draft).
 - Classify each FAIL: script-bug (fix selector/logic) vs product-gap (keep FAIL + evidence, never fake-pass).
 
-## Skills — pick the layer, load ONE file (`skills/qc/qa-runner/`)
+## Skills — pick the layer, load ONE file (`{paths.qc_skills_dir}/qa-runner/`)
 
 `functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
 `non-functional.md`, `exploratory/session.md`.
@@ -55,6 +55,12 @@ After the run, update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row
 |--------|-------|
 | `qc_status` | `pass` if all QC tests for this SC passed · `fail` if any failed · `skip` if all skipped/xfail · `not_run` if no QC test covers it |
 | `qc_run_at` | today `YYYY-MM-DD` |
+| `qc_owner` | **who the SC is waiting on** (the PM/PO "pending" view): `dev` if FAIL = product-gap (real defect → dev fixes) · `po` if `skip`/`not_run` because an **open `DOC_GAPS` 🔴 Blocker** prevents testing (PO must clarify PRD/BDD) · `—` if `pass`, or FAIL = script-bug (QC's own to fix — transient) |
+| `qc_blocked_by` | linked artifact: `GAP-{id}` when blocked by a spec gap (set here) · `BUG-{id}` once `/report-bug` is filed for the product-gap (backfilled by `/report-bug`) · `—` otherwise |
+
+Set `qc_owner`/`qc_blocked_by` together with `qc_status`. On `pass`, **clear** both to `—`.
+For a product-gap FAIL, set `qc_owner=dev` now; the `BUG-{id}` is backfilled into `qc_blocked_by`
+when QC runs the `/report-bug` that `/qc-report` prompts.
 
 Leave all other columns unchanged — **never** touch `dev_selftest`/`dev_selftest_at`
 (owned by `/dev-run-test`). `qc_status` (official QC) and `dev_selftest` (dev smoke) are

package/commands/refine-prd.md

@@ -125,6 +125,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -137,6 +139,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -181,6 +185,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/commands/report-bug.md

@@ -1,6 +1,8 @@
-# /report-bug — File a Spec-Traced Bug (Tester-Facing)
+# /report-bug — File a Spec-Traced Bug (Tester & QC-Facing)
 
-For **testers**. Produces a structured bug report with full spec context, classifies the likely
+For **testers and QC** — including **product-gaps** surfaced by the `/qc-*` pipeline
+(`/qc-run-test` FAIL classified product-gap, or a `DOC_GAPS` spec-defect blocker from
+`/qc-analyze`). Produces a structured bug report with full spec context, classifies the likely
 layer, and saves it for handoff to the dev team.
 
 **READ-ONLY on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
@@ -134,6 +136,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -146,6 +150,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -190,6 +196,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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.
 
@@ -446,6 +453,17 @@ State the classification as a suggestion (dev confirms during `/fix-bug`).
 Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
 Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
 
+## Step 5.5 — Backfill the trace (pending-view link)
+
+If Step 1 matched a specific failing scenario `{UC-ID}-SC{N}` **and** a trace row exists in
+`{paths.trace_dir}/{UC-ID}.tsv`, update **only** that row so the PO/PM "waiting-on" view points
+to this bug — leave every other column (incl. `qc_status`) unchanged:
+- `qc_blocked_by` = `{BUG-ID}`
+- `qc_owner` = `dev` if likely layer ∈ {Code, BDD, Design Spec, Env} · `po` if likely layer = PRD ambiguity
+
+Skip silently if no SC matched or no trace file/row exists (a bug can still be filed). This is
+the only write this command makes to operational state — it still **never** edits PRD/BDD/code.
+
 ## Step 6 — Handoff (so PO/Dev actually see it)
 
 The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
@@ -545,6 +563,7 @@ Next   : {suggested command with example arguments}
 🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
 
 Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` by /fix-bug, `Closed` after /qc-run-test re-verify pass)
 
 Spec context
   PRD      : {prd_path} (v{prd_version})

package/commands/report-bug.tmpl

@@ -1,6 +1,8 @@
-# /report-bug — File a Spec-Traced Bug (Tester-Facing)
+# /report-bug — File a Spec-Traced Bug (Tester & QC-Facing)
 
-For **testers**. Produces a structured bug report with full spec context, classifies the likely
+For **testers and QC** — including **product-gaps** surfaced by the `/qc-*` pipeline
+(`/qc-run-test` FAIL classified product-gap, or a `DOC_GAPS` spec-defect blocker from
+`/qc-analyze`). Produces a structured bug report with full spec context, classifies the likely
 layer, and saves it for handoff to the dev team.
 
 **READ-ONLY on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
@@ -70,6 +72,17 @@ State the classification as a suggestion (dev confirms during `/fix-bug`).
 Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
 Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
 
+## Step 5.5 — Backfill the trace (pending-view link)
+
+If Step 1 matched a specific failing scenario `{UC-ID}-SC{N}` **and** a trace row exists in
+`{paths.trace_dir}/{UC-ID}.tsv`, update **only** that row so the PO/PM "waiting-on" view points
+to this bug — leave every other column (incl. `qc_status`) unchanged:
+- `qc_blocked_by` = `{BUG-ID}`
+- `qc_owner` = `dev` if likely layer ∈ {Code, BDD, Design Spec, Env} · `po` if likely layer = PRD ambiguity
+
+Skip silently if no SC matched or no trace file/row exists (a bug can still be filed). This is
+the only write this command makes to operational state — it still **never** edits PRD/BDD/code.
+
 ## Step 6 — Handoff (so PO/Dev actually see it)
 
 The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
@@ -102,6 +115,7 @@ git push                      # → PO/Dev see it on their next /sync
 🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
 
 Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` by /fix-bug, `Closed` after /qc-run-test re-verify pass)
 
 Spec context
   PRD      : {prd_path} (v{prd_version})

package/commands/review-code.md

@@ -127,6 +127,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -139,6 +141,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -183,6 +187,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/commands/review-context.md

@@ -132,6 +132,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -144,6 +146,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -188,6 +192,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/commands/review-tech-docs.md

@@ -129,6 +129,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -141,6 +143,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -185,6 +189,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/commands/sync.md

@@ -144,9 +144,9 @@ Collect from output:
 
 ---
 
-## Step 1d — Surface Tester Feedback *(new bug reports / scenario proposals)*
+## Step 1d — Surface Tester/QC Feedback *(bug reports / scenario proposals / PRD change requests)*
 
-Tester `/report-bug` and `/propose-scenario` commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+Tester & QC `/report-bug`, `/propose-scenario` (incl. Case B PRD change requests) commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
 
 - **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
 - **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
@@ -158,22 +158,25 @@ Pick the repo + range that pulled the feedback:
 If `feedback/` does not exist in REPO → skip silently.
 
 ```bash
-git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/ feedback/prd-change-requests/
 ```
 
-For each entry, read its title/summary and report:
+For each entry, read its title/summary + `State` and report. **Bug reports: surface only `State: Open`** as needing attention; list `Fixed`/`Closed` separately (or omit) so the PO/PM sees what's still pending:
 ```
-📥 New tester feedback (pulled this sync):
-   Bug reports:
-     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code]
+📥 New feedback (pulled this sync):
+   Bug reports (open):
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code · waiting: dev]
+   Bug reports (fixed, awaiting QC re-verify): BUG-20260605-02
    Scenario proposals:
      FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+   PRD change requests:
+     FT-001-bulk-export.md  → new requirement, needs an AC  (waiting: PO)
 ```
 
-If none changed → print `📥 Tester feedback: none new this sync`.
+If none changed → print `📥 Feedback: none new this sync`.
 
 If the reader is a PO/Dev, add a one-line nudge:
-`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD.`
+`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal via /generate-bdd · or add an AC to the PRD.`
 
 ---
 

package/commands/sync.tmpl

@@ -144,9 +144,9 @@ Collect from output:
 
 ---
 
-## Step 1d — Surface Tester Feedback *(new bug reports / scenario proposals)*
+## Step 1d — Surface Tester/QC Feedback *(bug reports / scenario proposals / PRD change requests)*
 
-Tester `/report-bug` and `/propose-scenario` commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+Tester & QC `/report-bug`, `/propose-scenario` (incl. Case B PRD change requests) commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
 
 - **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
 - **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
@@ -158,22 +158,25 @@ Pick the repo + range that pulled the feedback:
 If `feedback/` does not exist in REPO → skip silently.
 
 ```bash
-git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/ feedback/prd-change-requests/
 ```
 
-For each entry, read its title/summary and report:
+For each entry, read its title/summary + `State` and report. **Bug reports: surface only `State: Open`** as needing attention; list `Fixed`/`Closed` separately (or omit) so the PO/PM sees what's still pending:
 ```
-📥 New tester feedback (pulled this sync):
-   Bug reports:
-     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code]
+📥 New feedback (pulled this sync):
+   Bug reports (open):
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code · waiting: dev]
+   Bug reports (fixed, awaiting QC re-verify): BUG-20260605-02
    Scenario proposals:
      FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+   PRD change requests:
+     FT-001-bulk-export.md  → new requirement, needs an AC  (waiting: PO)
 ```
 
-If none changed → print `📥 Tester feedback: none new this sync`.
+If none changed → print `📥 Feedback: none new this sync`.
 
 If the reader is a PO/Dev, add a one-line nudge:
-`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD.`
+`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal via /generate-bdd · or add an AC to the PRD.`
 
 ---
 

package/commands/validate-traces.md

@@ -127,6 +127,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -139,6 +141,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -183,6 +187,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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.
 
@@ -467,7 +472,7 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 *Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
 
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
-Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at` (owned by `/qc-run-test`); this command only reads them for the report.
+Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (owned by `/qc-run-test` + `/report-bug`); this command only reads them for the report.
 
 ### Step 7 — Compute dashboard aggregates
 
@@ -494,6 +499,9 @@ qc_skipped       = rows where qc_status == skip
 qc_not_run       = rows where qc_status in (not_run, —)
 # qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
 # shown alongside — never merged with — dev_selftest.
+waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
+waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
+# qc_owner + qc_blocked_by answer "case nào đang chờ ai" — surface as a "Waiting on" column.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 ```
 
@@ -528,6 +536,8 @@ Schema:
     "qc_failing": 0,
     "qc_skipped": 0,
     "qc_not_run": 0,
+    "waiting_dev": 0,
+    "waiting_po": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -557,6 +567,8 @@ Schema:
               "dev_selftest_at": "<YYYY-MM-DD or null>",
               "qc_status": "pass | fail | skip | not_run",
               "qc_run_at": "<YYYY-MM-DD or null>",
+              "qc_owner": "dev | po | null",
+              "qc_blocked_by": "<BUG-id / GAP-id or null>",
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
@@ -621,7 +633,8 @@ Schema:
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
+- **Backward-compat (older 19-col TSV):** if `qc_owner` / `qc_blocked_by` columns are **absent** from the header (a pre-upgrade TSV), treat them as `null` — do not error. The next `/generate-bdd` re-gen upgrades the header to include them.
 
 ### Step 8b — Living Docs Sync *(umbrella mode only)*
 

package/commands/validate-traces.tmpl

@@ -91,7 +91,7 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 *Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
 
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
-Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at` (owned by `/qc-run-test`); this command only reads them for the report.
+Do **not** modify `dev_selftest`/`dev_selftest_at` (owned by `/dev-run-test`) or `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (owned by `/qc-run-test` + `/report-bug`); this command only reads them for the report.
 
 ### Step 7 — Compute dashboard aggregates
 
@@ -118,6 +118,9 @@ qc_skipped       = rows where qc_status == skip
 qc_not_run       = rows where qc_status in (not_run, —)
 # qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
 # shown alongside — never merged with — dev_selftest.
+waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
+waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
+# qc_owner + qc_blocked_by answer "case nào đang chờ ai" — surface as a "Waiting on" column.
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 ```
 
@@ -152,6 +155,8 @@ Schema:
     "qc_failing": 0,
     "qc_skipped": 0,
     "qc_not_run": 0,
+    "waiting_dev": 0,
+    "waiting_po": 0,
     "tech_docs_count": 0
   },
   "prds": [
@@ -181,6 +186,8 @@ Schema:
               "dev_selftest_at": "<YYYY-MM-DD or null>",
               "qc_status": "pass | fail | skip | not_run",
               "qc_run_at": "<YYYY-MM-DD or null>",
+              "qc_owner": "dev | po | null",
+              "qc_blocked_by": "<BUG-id / GAP-id or null>",
               "prd_version": "<prd version when BDD was generated>",
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
@@ -245,7 +252,8 @@ Schema:
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
 - Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
-- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
+- **Backward-compat (older 19-col TSV):** if `qc_owner` / `qc_blocked_by` columns are **absent** from the header (a pre-upgrade TSV), treat them as `null` — do not error. The next `/generate-bdd` re-gen upgrades the header to include them.
 
 ### Step 8b — Living Docs Sync *(umbrella mode only)*
 

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

package/core/commands/debug.md

@@ -128,6 +128,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -140,6 +142,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -184,6 +188,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/define-product.md

@@ -125,6 +125,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -137,6 +139,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -181,6 +185,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/dev-gen-test.md

@@ -131,6 +131,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -143,6 +145,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -187,6 +191,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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/dev-run-test.md

@@ -131,6 +131,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -143,6 +145,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -187,6 +191,7 @@ If `services` section is present:
 - 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`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **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.