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

package/commands/generate-design-spec.md

@@ -163,7 +163,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -175,7 +175,7 @@ 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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - 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`
@@ -206,7 +206,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `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`
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) 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).
@@ -221,19 +221,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -299,7 +321,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -333,7 +355,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -399,19 +422,6 @@ Using `active_module` and `platform_type` derived from context loading:
 
 ---
 
-## Figma Check
-
-Ask:
-
-```
-Do you have a Figma link for this feature? (paste URL or press Enter to skip)
-```
-
-- If URL provided → store as `figma_url`.
-- If skipped → `figma_url = "TBD"`. Add AI Assumption: "Figma link not provided — all screen descriptions are text-based. Link must be added and verified before Design Spec sign-off."
-
----
-
 ## Screen Discovery
 
 From the PRD's Section 4 (User Flow + Wireframe), extract all screen / page / modal names mentioned.
@@ -432,6 +442,54 @@ Wait for confirmation. Store the confirmed list as `screen_list`.
 
 ---
 
+## Figma Frame Links *(mandatory — one readable node-level link per screen)*
+
+A Design Spec is only as good as the design it points to. The AI **cannot read a plain
+file link** (`figma.com/design/{fileKey}/...` with no `node-id`) — it needs a
+**node-level link to each specific frame** so it can fetch that frame's real layout,
+components, and tokens via the Figma MCP. So collect one link **per screen**, not one
+link for the whole feature.
+
+**Ask the PO, listing every screen in `screen_list`:**
+
+```
+Paste the Figma frame link for each screen below.
+
+  In Figma: select the frame → right-click → "Copy link to selection"
+  (the URL must contain  ?node-id=...  — that is the per-frame link the AI can read)
+
+  1. {Screen 1} : ____
+  2. {Screen 2} : ____
+  ...
+
+If a screen has no design yet, type  none  for that screen.
+```
+
+**For each answer:**
+
+1. **Validate format** — the URL must match `figma.com/design/{fileKey}/...?node-id={nodeId}`.
+   - Valid → store as `figma_frames[{screen}] = {url}`, parse out `fileKey` + `nodeId`.
+   - A file link with **no `node-id`** → reject it: "This link points to the whole file, not a frame. Re-copy via right-click → Copy link to selection." Re-ask for that screen.
+   - `none` → `figma_frames[{screen}] = "TBD"`, mark that screen ❌ Missing.
+
+2. **Fetch the frame via Figma MCP** (only for valid links) — call `get_design_context`
+   (and `get_screenshot` when useful) with the parsed `fileKey` + `nodeId` to read the
+   real layout, component names, and design tokens. Ground every Screen Spec in this
+   fetched data; do **not** invent layout the frame does not show. If a fetch fails
+   (permission / not found) → treat that screen as ❌ Missing and note the fetch error.
+
+3. Derive the feature-level `figma_url` = the file link (without `node-id`) shared by the
+   frames, for the Metadata row. If frames span multiple files, list each.
+
+**Mandatory gate (does not abort — produces a draft):**
+- If **any** screen is ❌ Missing → the spec is generated as a **draft** with those screens
+  flagged, but `Status` stays `draft` and **sign-off / `/generate-bdd` is blocked** until
+  every screen has a readable, fetched frame link. Record `missing_frames = [screens]`.
+- Add one AI Assumption per missing screen: "No readable Figma frame for {screen} — spec
+  for this screen is text-only and must not be signed off until a `node-id` link is added."
+
+---
+
 ## CHECKPOINT
 
 ```
@@ -443,9 +501,13 @@ Module      : {active_module}
 Service     : {active_service}
 Domain      : {domain}
 Screens     : {N} — {comma-separated screen_list}
-Figma       : {figma_url}
+Figma       : {linked}/{N} screens have readable frame links{; missing: comma-separated missing_frames}
 Output path : {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md
 
+{If missing_frames non-empty}:
+⚠️  {count} screen(s) without a readable Figma frame link — these will be generated as
+   text-only drafts and the spec cannot be signed off until their node-id links are added.
+
 Generate? (Y/N)
 ```
 
@@ -470,6 +532,15 @@ Apply these rules consistently when generating all sections:
   - `app` / `app-ios` / `app-android` → include gestures, safe area, minimum touch targets, navigation pattern, deep links, permissions, offline behavior.
   - Only generate the section relevant to `active_platform`. Omit the other platform's section entirely.
 
+**Figma grounding (mandatory):**
+- For every screen with a fetched frame (`figma_frames[screen]` is a valid link), base the
+  Layout, Component Inventory, and Screen States on the **fetched Figma data** — real
+  component names, real tokens, real frame structure. Do not contradict or invent layout.
+- Use the exact per-screen `figma_frames[screen]` URL in the Screen Inventory, each Screen
+  Spec header, and the Figma Summary — never a synthetic `{figma_url}#screen1` fragment.
+- For ❌ Missing screens: generate a text-only draft from the PRD, prefix the Screen Spec
+  with `> [DRAFT — no Figma frame; do not sign off]`, and leave the Figma cell as ❌ Missing.
+
 **Screen states (mandatory per screen):**
 - Every screen must document at minimum: `default`, `loading`, `error`.
 - Add `empty` when the screen can display zero-data state.
@@ -499,7 +570,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}]({relative-path-to-prd.md})                      |
-| **Figma**          | {figma_url}                                                   |
+| **Figma**          | {figma_url — feature file link} ({linked}/{N} frames linked)  |
 | **Author**         | {PO name or "AI-assisted"}                                    |
 | **Created**        | {YYYY-MM-DD}                                                  |
 | **Updated**        | {YYYY-MM-DD}                                                  |
@@ -510,8 +581,8 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 | # | Screen Name | Entry Point | Figma Frame | Notes |
 |---|-------------|-------------|-------------|-------|
-| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_url}#screen1) | |
-| 2 | {Screen 2}  | {entry point} | [Frame]({figma_url}#screen2) | |
+| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_frames[Screen 1]}) | |
+| 2 | {Screen 2}  | {entry point} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | |
 
 ---
 
@@ -524,7 +595,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 ## Screen 1: {Screen Name}
 
-**Figma**: [{Frame name}]({figma_frame_url})
+**Figma**: [{Frame name}]({figma_frames[Screen 1]})   <!-- ❌ Missing → prefix this screen with `> [DRAFT — no Figma frame; do not sign off]` -->
 
 ### Layout
 
@@ -680,10 +751,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 ## Figma Summary
 
-| Screen          | Figma Frame                   | Designer Status        |
-|-----------------|-------------------------------|------------------------|
-| {Screen 1}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
-| {Screen 2}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
+| Screen          | Figma Frame                          | Link / Fetch Status                  |
+|-----------------|--------------------------------------|--------------------------------------|
+| {Screen 1}      | [Link]({figma_frames[Screen 1]})     | ✅ Linked & fetched                  |
+| {Screen 2}      | —                                    | ❌ Missing — no node-id link provided |
 
 ## Design Tokens Referenced
 
@@ -705,6 +776,7 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 > PO must review and confirm before sign-off.
 
 - {Assumption 1 — [AI DRAFT]}
+- {One per ❌ Missing screen: "No readable Figma frame for {screen} — text-only draft; blocks sign-off until a node-id link is added."}
 
 ---
 
@@ -716,9 +788,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 <!--
   NEXT STEPS:
-  1. Share with Designer — verify Figma links, update component inventory.
-  2. PO + Designer sign off: change Status → "approved".
-  3. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
+  1. Fill any ❌ Missing Figma frame links (node-id links) — re-run to fetch & ground them.
+  2. Share with Designer — verify Figma links, update component inventory.
+  3. PO + Designer sign off: change Status → "approved" (only allowed when 0 screens are ❌ Missing).
+  4. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
 -->
 ````
 
@@ -733,7 +806,9 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 - [ ] Only the platform-relevant section generated in Section 4
 - [ ] AC-UI items are testable (clear pass/fail, not "looks good")
 - [ ] Business PRD cross-reference link is valid relative path
-- [ ] If `figma_url = "TBD"` → AI Assumption added in Appendix
+- [ ] Every screen has a node-level Figma frame link (`?node-id=`) — and screens with a link were fetched via Figma MCP and used to ground the spec
+- [ ] Each ❌ Missing screen is flagged in-spec (`> [DRAFT — no Figma frame...]`), listed in Figma Summary, and has an AI Assumption
+- [ ] If any screen is ❌ Missing → Status stays `draft` and the Output below blocks `/generate-bdd`
 
 ---
 
@@ -775,15 +850,22 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {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}` |
@@ -801,12 +883,25 @@ Next   : {suggested command with example arguments}
 ```
 
 
+{If missing_frames is empty}:
 ```
 /generate-design-spec Complete — {TICKET-ID} [{active_platform}]
 ---
-Status : ✅ Complete
+Status : ✅ Complete — all {N} screens linked & fetched from Figma
 Output Artifacts:
   created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
-Next   : Share with Designer → add Figma links → PO + Designer sign-off (Status: approved)
+Next   : Share with Designer → PO + Designer sign-off (Status: approved)
          → /generate-bdd {prd-file}  (generates BDD per service; reads AC-UI from Design Spec)
 ```
+
+{If missing_frames is non-empty}:
+```
+/generate-design-spec Complete (DRAFT) — {TICKET-ID} [{active_platform}]
+---
+Status : ⚠️ Warnings — {count} screen(s) without a readable Figma frame: {comma-separated missing_frames}
+Output Artifacts:
+  created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
+Next   : 🔒 Sign-off & /generate-bdd are BLOCKED until every screen has a node-id Figma link.
+         1. In Figma: select each missing frame → right-click → Copy link to selection
+         2. Re-run /generate-design-spec {prd-file} → AI fetches & grounds the new frames
+```

package/commands/generate-design-spec.tmpl

@@ -46,19 +46,6 @@ Using `active_module` and `platform_type` derived from context loading:
 
 ---
 
-## Figma Check
-
-Ask:
-
-```
-Do you have a Figma link for this feature? (paste URL or press Enter to skip)
-```
-
-- If URL provided → store as `figma_url`.
-- If skipped → `figma_url = "TBD"`. Add AI Assumption: "Figma link not provided — all screen descriptions are text-based. Link must be added and verified before Design Spec sign-off."
-
----
-
 ## Screen Discovery
 
 From the PRD's Section 4 (User Flow + Wireframe), extract all screen / page / modal names mentioned.
@@ -79,6 +66,54 @@ Wait for confirmation. Store the confirmed list as `screen_list`.
 
 ---
 
+## Figma Frame Links *(mandatory — one readable node-level link per screen)*
+
+A Design Spec is only as good as the design it points to. The AI **cannot read a plain
+file link** (`figma.com/design/{fileKey}/...` with no `node-id`) — it needs a
+**node-level link to each specific frame** so it can fetch that frame's real layout,
+components, and tokens via the Figma MCP. So collect one link **per screen**, not one
+link for the whole feature.
+
+**Ask the PO, listing every screen in `screen_list`:**
+
+```
+Paste the Figma frame link for each screen below.
+
+  In Figma: select the frame → right-click → "Copy link to selection"
+  (the URL must contain  ?node-id=...  — that is the per-frame link the AI can read)
+
+  1. {Screen 1} : ____
+  2. {Screen 2} : ____
+  ...
+
+If a screen has no design yet, type  none  for that screen.
+```
+
+**For each answer:**
+
+1. **Validate format** — the URL must match `figma.com/design/{fileKey}/...?node-id={nodeId}`.
+   - Valid → store as `figma_frames[{screen}] = {url}`, parse out `fileKey` + `nodeId`.
+   - A file link with **no `node-id`** → reject it: "This link points to the whole file, not a frame. Re-copy via right-click → Copy link to selection." Re-ask for that screen.
+   - `none` → `figma_frames[{screen}] = "TBD"`, mark that screen ❌ Missing.
+
+2. **Fetch the frame via Figma MCP** (only for valid links) — call `get_design_context`
+   (and `get_screenshot` when useful) with the parsed `fileKey` + `nodeId` to read the
+   real layout, component names, and design tokens. Ground every Screen Spec in this
+   fetched data; do **not** invent layout the frame does not show. If a fetch fails
+   (permission / not found) → treat that screen as ❌ Missing and note the fetch error.
+
+3. Derive the feature-level `figma_url` = the file link (without `node-id`) shared by the
+   frames, for the Metadata row. If frames span multiple files, list each.
+
+**Mandatory gate (does not abort — produces a draft):**
+- If **any** screen is ❌ Missing → the spec is generated as a **draft** with those screens
+  flagged, but `Status` stays `draft` and **sign-off / `/generate-bdd` is blocked** until
+  every screen has a readable, fetched frame link. Record `missing_frames = [screens]`.
+- Add one AI Assumption per missing screen: "No readable Figma frame for {screen} — spec
+  for this screen is text-only and must not be signed off until a `node-id` link is added."
+
+---
+
 ## CHECKPOINT
 
 ```
@@ -90,9 +125,13 @@ Module      : {active_module}
 Service     : {active_service}
 Domain      : {domain}
 Screens     : {N} — {comma-separated screen_list}
-Figma       : {figma_url}
+Figma       : {linked}/{N} screens have readable frame links{; missing: comma-separated missing_frames}
 Output path : {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md
 
+{If missing_frames non-empty}:
+⚠️  {count} screen(s) without a readable Figma frame link — these will be generated as
+   text-only drafts and the spec cannot be signed off until their node-id links are added.
+
 Generate? (Y/N)
 ```
 
@@ -117,6 +156,15 @@ Apply these rules consistently when generating all sections:
   - `app` / `app-ios` / `app-android` → include gestures, safe area, minimum touch targets, navigation pattern, deep links, permissions, offline behavior.
   - Only generate the section relevant to `active_platform`. Omit the other platform's section entirely.
 
+**Figma grounding (mandatory):**
+- For every screen with a fetched frame (`figma_frames[screen]` is a valid link), base the
+  Layout, Component Inventory, and Screen States on the **fetched Figma data** — real
+  component names, real tokens, real frame structure. Do not contradict or invent layout.
+- Use the exact per-screen `figma_frames[screen]` URL in the Screen Inventory, each Screen
+  Spec header, and the Figma Summary — never a synthetic `{figma_url}#screen1` fragment.
+- For ❌ Missing screens: generate a text-only draft from the PRD, prefix the Screen Spec
+  with `> [DRAFT — no Figma frame; do not sign off]`, and leave the Figma cell as ❌ Missing.
+
 **Screen states (mandatory per screen):**
 - Every screen must document at minimum: `default`, `loading`, `error`.
 - Add `empty` when the screen can display zero-data state.
@@ -146,7 +194,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}]({relative-path-to-prd.md})                      |
-| **Figma**          | {figma_url}                                                   |
+| **Figma**          | {figma_url — feature file link} ({linked}/{N} frames linked)  |
 | **Author**         | {PO name or "AI-assisted"}                                    |
 | **Created**        | {YYYY-MM-DD}                                                  |
 | **Updated**        | {YYYY-MM-DD}                                                  |
@@ -157,8 +205,8 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 | # | Screen Name | Entry Point | Figma Frame | Notes |
 |---|-------------|-------------|-------------|-------|
-| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_url}#screen1) | |
-| 2 | {Screen 2}  | {entry point} | [Frame]({figma_url}#screen2) | |
+| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_frames[Screen 1]}) | |
+| 2 | {Screen 2}  | {entry point} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | |
 
 ---
 
@@ -171,7 +219,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 ## Screen 1: {Screen Name}
 
-**Figma**: [{Frame name}]({figma_frame_url})
+**Figma**: [{Frame name}]({figma_frames[Screen 1]})   <!-- ❌ Missing → prefix this screen with `> [DRAFT — no Figma frame; do not sign off]` -->
 
 ### Layout
 
@@ -327,10 +375,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 ## Figma Summary
 
-| Screen          | Figma Frame                   | Designer Status        |
-|-----------------|-------------------------------|------------------------|
-| {Screen 1}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
-| {Screen 2}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
+| Screen          | Figma Frame                          | Link / Fetch Status                  |
+|-----------------|--------------------------------------|--------------------------------------|
+| {Screen 1}      | [Link]({figma_frames[Screen 1]})     | ✅ Linked & fetched                  |
+| {Screen 2}      | —                                    | ❌ Missing — no node-id link provided |
 
 ## Design Tokens Referenced
 
@@ -352,6 +400,7 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 > PO must review and confirm before sign-off.
 
 - {Assumption 1 — [AI DRAFT]}
+- {One per ❌ Missing screen: "No readable Figma frame for {screen} — text-only draft; blocks sign-off until a node-id link is added."}
 
 ---
 
@@ -363,9 +412,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 <!--
   NEXT STEPS:
-  1. Share with Designer — verify Figma links, update component inventory.
-  2. PO + Designer sign off: change Status → "approved".
-  3. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
+  1. Fill any ❌ Missing Figma frame links (node-id links) — re-run to fetch & ground them.
+  2. Share with Designer — verify Figma links, update component inventory.
+  3. PO + Designer sign off: change Status → "approved" (only allowed when 0 screens are ❌ Missing).
+  4. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
 -->
 ````
 
@@ -380,7 +430,9 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 - [ ] Only the platform-relevant section generated in Section 4
 - [ ] AC-UI items are testable (clear pass/fail, not "looks good")
 - [ ] Business PRD cross-reference link is valid relative path
-- [ ] If `figma_url = "TBD"` → AI Assumption added in Appendix
+- [ ] Every screen has a node-level Figma frame link (`?node-id=`) — and screens with a link were fetched via Figma MCP and used to ground the spec
+- [ ] Each ❌ Missing screen is flagged in-spec (`> [DRAFT — no Figma frame...]`), listed in Figma Summary, and has an AI Assumption
+- [ ] If any screen is ❌ Missing → Status stays `draft` and the Output below blocks `/generate-bdd`
 
 ---
 
@@ -388,12 +440,25 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 {{include:steps/report-footer.md}}
 
+{If missing_frames is empty}:
 ```
 /generate-design-spec Complete — {TICKET-ID} [{active_platform}]
 ---
-Status : ✅ Complete
+Status : ✅ Complete — all {N} screens linked & fetched from Figma
 Output Artifacts:
   created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
-Next   : Share with Designer → add Figma links → PO + Designer sign-off (Status: approved)
+Next   : Share with Designer → PO + Designer sign-off (Status: approved)
          → /generate-bdd {prd-file}  (generates BDD per service; reads AC-UI from Design Spec)
 ```
+
+{If missing_frames is non-empty}:
+```
+/generate-design-spec Complete (DRAFT) — {TICKET-ID} [{active_platform}]
+---
+Status : ⚠️ Warnings — {count} screen(s) without a readable Figma frame: {comma-separated missing_frames}
+Output Artifacts:
+  created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
+Next   : 🔒 Sign-off & /generate-bdd are BLOCKED until every screen has a node-id Figma link.
+         1. In Figma: select each missing frame → right-click → Copy link to selection
+         2. Re-run /generate-design-spec {prd-file} → AI fetches & grounds the new frames
+```