[codex] add figma metadata shard capture

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## Unreleased
+## [0.1.5] - 2026-07-03
+
+### Added
+
+- Added `capture_figma_metadata_shards.py` to stage sharded Figma `get_metadata` captures into canonical raw metadata shards, index, and node inventory artifacts without passing large provider responses through agent context.
+- Added IA-matrix preview readiness checks that require page visual-state enumerations, page IA matrices, component visual-state enumerations, component IA matrices with interaction refs, and coverage evidence conclusions.
+- Added structured UI/visual asset source-of-truth checks that block evidence packets, preview HTML, screenshots, and visual diffs from being used as `source_refs` or `evidence_refs`.
 
 ## [0.1.4] - 2026-07-01
 

README.md

@@ -1,6 +1,8 @@
 # Spec Kit Intake Extension
 
-Extract, normalize, and validate SDD-ready intake artifacts from PRDs, visual designs, visual requirements/spec structured asset packages, optional preview evidence, test cases, and other software sources before downstream Spec Kit workflows project them into requirements.
+Extract, normalize, and validate SDD-ready intake artifacts from PRDs, visual designs, structured UI/visual assets, optional preview evidence, test cases, and other software sources before downstream Spec Kit workflows project them into requirements.
+
+For UI intake, the structured UI/visual asset is the source of truth. Evidence packets support confidence, and preview HTML supports human reading of page-component IA; neither may create, override, or replace structured asset records.
 
 The first goal of intake is not to generate requirements. It is to preserve as much input information as possible and turn it into structured material that SDD `specify` can consume accurately.
 
@@ -15,7 +17,7 @@ Intake artifacts are validated in two layers: JSON Schema checks enforce the req
 - Static images such as PNG, JPG, WebP, and exported screens
 - PDF design packs and annotated review documents
 - Figma files, pages, frames, nodes, components, variables, and exported screenshots
-- Optional Figma-derived component matrix preview and coverage review helpers with traceable component, state, variant, viewport, and screenshot coverage
+- Optional Figma-derived IA matrix preview and coverage review helpers with traceable page, component, visual-state, interaction, variant, viewport, and screenshot coverage
 - Visual requirements/spec structured asset packages with CI-friendly DOM, ARIA, token, state, locator, relation, and assertion facts
 - Existing test cases, Gherkin files, QA exports, and test management spreadsheets
 
@@ -27,7 +29,7 @@ Intake commands are organized by vertical source domain. Each domain uses the sa
 | --- | --- | --- | --- |
 | PRD | product briefs, Markdown PRDs, exported docs, PDFs, issue or epic links, mixed stakeholder notes | `prd-intake.yaml` | source identity, product intent traceability, scope boundaries, acceptance evidence, clarification gaps |
 | Visual design | static images, wireframes, PDF design packs, Markdown design briefs, Figma files or selected nodes | `visual-requirements.yaml` and `visual-spec-package/` | source integrity, Figma-backed resource traceability, fidelity rules, visual requirement traceability, structured visual spec readiness, CI-low-cost assertion readiness |
-| Figma preview helper | Figma files or selected nodes projected into component matrix review surfaces | `previews/component-matrix-preview.html` plus coverage YAML | Figma component coverage, component-state coverage, variant coverage, viewport screenshots, known gaps |
+| Figma preview helper | Figma files or selected nodes projected into IA matrix review surfaces | `previews/component-matrix-preview.html` plus coverage YAML | Figma page coverage, component coverage, visual-state coverage, fused interaction coverage, variant coverage, viewport screenshots, known gaps |
 | Test cases | automated tests, Gherkin files, manual QA cases, spreadsheets, test management exports, bug or issue repro steps | `test-case-intake.yaml` | scenario traceability, assertion extraction, fixture evidence, coverage gaps, flaky or skipped case reporting |
 
 Vertical instructions should never convert source evidence directly into downstream-owned requirement IDs, implementation tasks, or code component names. They produce provider-neutral intake facts that downstream workflows can consume with source refs intact.
@@ -77,6 +79,9 @@ Figma metadata artifacts are required for Figma visual-design sources. Image, PD
 Machine-readable JSON Schemas live under `templates/schemas/` and are used by the validators before readiness rules run. Preview helpers are defined by `templates/intake-visual-previews-contract.md` and use `component-coverage.schema.json` and `viewport-coverage.schema.json`. Visual spec packages use `visual-spec-package.schema.json` and `visual-spec-assertions.schema.json`.
 
 All intake commands provide capture instructions, evidence contracts, and readiness validation. Visual design validation additionally checks visual fidelity and Figma metadata parity.
+Visual validators reject evidence packets, preview HTML, screenshots, and visual diffs when they appear in source-of-truth fields such as `source_refs` or `evidence_refs`; use preview-specific helper refs for those supporting artifacts.
+Figma metadata capture should use bounded shards: stage raw `get_metadata` response files with `scripts/python/capture_figma_metadata_shards.py` so large provider responses are written to disk and only shard paths, hashes, completeness, and inventory parity flow into the intake index.
+Keep raw capture files outside the target `visual-design/` directory before staging, and pass one `--node-id` per selected root when a capture spans multiple roots.
 Component matrix preview validation is owned by `scripts/python/validate_visual_previews.py`, including cross-file checks for preview refs, visual spec refs, screenshots, component coverage, viewport coverage, and known gaps.
 Visual spec package validation is owned by `scripts/python/validate_visual_spec_package.py`, including source readiness, schema, cross-reference, locator, downstream-ownership, provider-evidence, product-ambiguity, design-source resource traceability, and CI assertion checks.
 
@@ -99,7 +104,7 @@ specify extension add --dev C:/Users/24598/Documents/github/spec-kit-intake
 From a Spec Kit project:
 
 ```bash
-specify extension add intake --from https://github.com/bigsmartben/spec-kit-intake/archive/refs/tags/v0.1.4.zip
+specify extension add intake --from https://github.com/bigsmartben/spec-kit-intake/archive/refs/tags/v0.1.5.zip
 ```
 
 Release artifacts must include source-backed provenance for the `bigsmartben/spec-kit` integration fork. The release workflow uploads `release-provenance.json` with:
@@ -150,18 +155,19 @@ For irregular Figma sources, intake may generate bounded candidate completions,
 
 ## Figma Preview Helper Readiness Gate
 
-Figma-derived component matrix preview evidence passes only when:
+Figma-derived IA matrix preview evidence passes only when:
 
 - upstream Figma visual-design intake is ready
-- every required component set, component instance, variant prop, state, size, density, theme, content sample, resource, and viewport is covered or recorded as a blocking missing record
-- the minimum acceptance grain is covered: component instance, state, content sample, container constraint, and viewport
-- required preview cells link back to Figma refs, `visual-spec.yaml` items, `component-coverage.yaml` records, and screenshot or diff evidence when available
+- `component-matrix-preview.html` is structured as: IA matrix overview; for each page, visual state enumeration plus page IA matrix; for each component, visual state enumeration plus component IA matrix with event interaction information; coverage evidence conclusion
+- every required page, component set, component instance, variant prop, state, size, density, theme, content sample, interaction, resource, and viewport is covered or recorded as a blocking missing record
+- the minimum acceptance grain is covered: page state, page IA row, component instance, component state, component IA row, interaction event, content sample, container constraint, and viewport
+- required preview cells and interaction rows link back to Figma refs, `visual-spec.yaml` items, `component-coverage.yaml` records, and screenshot or diff evidence when available
 - component coverage is expressed in `previews/component-coverage.yaml`
 - viewport coverage is expressed in `previews/viewport-coverage.yaml`
 - screenshot coverage and visual-diff status are recorded
 - known gaps are explicit and no blocking gap remains unresolved
 
-The preview validator emits blocker codes such as `VISUAL_PREVIEW_SOURCE_INTAKE_BLOCKED`, `VISUAL_PREVIEW_REQUIRED_ARTIFACT_MISSING`, `VISUAL_PREVIEW_SCHEMA_INVALID`, `VISUAL_PREVIEW_FIGMA_NODE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_COMPONENT_STATE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_PAGE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_ASSET_TRACEABILITY_INCOMPLETE`, `VISUAL_PREVIEW_VIEWPORT_CAPTURE_INCOMPLETE`, `VISUAL_PREVIEW_VISUAL_DIFF_BLOCKED`, and `VISUAL_PREVIEW_KNOWN_GAP_UNRESOLVED`.
+The preview validator emits blocker codes such as `VISUAL_PREVIEW_SOURCE_INTAKE_BLOCKED`, `VISUAL_PREVIEW_REQUIRED_ARTIFACT_MISSING`, `VISUAL_PREVIEW_SCHEMA_INVALID`, `VISUAL_PREVIEW_FIGMA_NODE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_COMPONENT_STATE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_IA_MATRIX_INCOMPLETE`, `VISUAL_PREVIEW_PAGE_COVERAGE_INCOMPLETE`, `VISUAL_PREVIEW_ASSET_TRACEABILITY_INCOMPLETE`, `VISUAL_PREVIEW_VIEWPORT_CAPTURE_INCOMPLETE`, `VISUAL_PREVIEW_VISUAL_DIFF_BLOCKED`, and `VISUAL_PREVIEW_KNOWN_GAP_UNRESOLVED`.
 
 ## Visual Spec Package Readiness Gate
 
@@ -174,7 +180,7 @@ The visual requirements/spec structured asset package passes only when:
 - assertions reference existing visual spec items and include ready `ci_low_cost` checks
 - missing provider evidence and product ambiguity are represented with distinct blocker paths
 - locator strategies avoid implementation-owned CSS selectors, XPath, generated class names, downstream test IDs, code component names, tasks, or requirement IDs
-- component matrix previews, screenshots, and visual diffs remain helper evidence rather than the target deliverable
+- IA matrix previews, screenshots, and visual diffs remain helper evidence rather than the target deliverable
 
 The visual spec package validator emits blocker codes such as `VISUAL_SPEC_SOURCE_INTAKE_BLOCKED`, `VISUAL_SPEC_REQUIRED_ARTIFACT_MISSING`, `VISUAL_SPEC_SCHEMA_INVALID`, `VISUAL_SPEC_INTAKE_INCOMPLETE`, `VISUAL_SPEC_PROVIDER_EVIDENCE_MISSING`, `VISUAL_SPEC_PRODUCT_AMBIGUITY_UNRESOLVED`, `VISUAL_SPEC_ASSERTION_COVERAGE_INCOMPLETE`, `VISUAL_SPEC_LOCATOR_STRATEGY_INVALID`, `VISUAL_SPEC_DOWNSTREAM_OWNERSHIP_LEAK`, and `VISUAL_SPEC_READY_WITHOUT_EVIDENCE`.
 
@@ -192,7 +198,19 @@ Validate visual-design artifacts:
 python scripts/python/validate_visual_design_intake.py specs/<feature>/intake/visual-design
 ```
 
-Validate component matrix preview helpers:
+Stage sharded Figma metadata captures before validation:
+
+```bash
+python scripts/python/capture_figma_metadata_shards.py specs/<feature>/intake/visual-design \
+  --metadata-source ./figma-metadata-raw \
+  --file-url <figma-file-url> \
+  --file-key <figma-file-key> \
+  --page-id <figma-page-id> \
+  --node-id <selected-root-node-id> \
+  --overwrite
+```
+
+Validate IA matrix preview helpers:
 
 ```bash
 python scripts/python/validate_visual_previews.py specs/<feature>/intake/visual-design/previews