Expand verification roadmap positioning

README.md

@@ -7,9 +7,10 @@ team already owns: component mappings, token rules, source paths, content
 sidecars, asset references, font requirements, verification recipes, and
 buyer-facing proof reports.
 
-Tessellate does not ask teams to trust generated UI. It gives them a receipt:
-what the Figma source said, what the implementation rendered, where parity
-held, what blocked parity, and what to fix next.
+Tessellate is the verification layer and repo-aware source map between Figma,
+design systems, and AI agents. It does not ask teams to trust generated UI. It
+gives them a receipt: what the Figma source said, what the implementation
+rendered, where parity held, what blocked parity, and what to fix next.
 
 This repository is the product and integration surface for Tessellate. It
 contains docs, schemas, examples, and neutral registry fixtures that teams can
@@ -25,6 +26,9 @@ Tessellate is one system:
 | Inlay | Applies user-configured brand-font substitution inside Figma Desktop |
 | Surface | Translates selected components, sections, pages, windows, or documents into scoped handoff artifacts |
 | Surface Receipt | Reports visual parity, source mapping, unresolved fonts/assets, confidence, and the implementation fix list |
+| Source map | Links rendered regions back to Figma nodes, code, mappings, tokens, fonts, assets, and diagnostics |
+| Design System Drift Map | Audits files for unmapped components, rogue fonts, token mismatches, repeated patterns, and unreachable assets |
+| CI receipt gate | Publishes receipts on implementation reviews and fails above the configured parity threshold |
 | Curations | Publishes per-curation token, CSS variable, mapping, and preview contracts for multi-brand systems |
 | Repo context | Reads customer-owned registry, token, component, font, and asset metadata |
 | Agent handoff | Produces structured bundles an engineer, MCP host, or AI agent can apply without guessing |
@@ -67,6 +71,10 @@ Start with:
 - [Inlay](./docs/inlay.md)
 - [Surface](./docs/surface.md)
 - [Surface Receipts](./docs/receipts.md)
+- [Figma Source Map](./docs/source-map.md)
+- [Design System Drift Map](./docs/drift.md)
+- [CI Receipt Gate](./docs/ci.md)
+- [Agent Handoff](./docs/agent-handoff.md)
 - [Curations](./docs/curations.md)
 - [Surface design-system context schema](./schemas/surface-design-system-context.schema.json)
 - [Example Surface context](./examples/surface-design-system-context.json)

docs/agent-handoff.md

@@ -0,0 +1,44 @@
+# Agent Handoff
+
+Agent Handoff is Tessellate's structured implementation bundle for engineers,
+MCP hosts, and AI agents. It gives an agent the Figma context, repo context,
+verification target, and diagnostics needed to implement without guessing.
+
+## Standard Bundle
+
+The handoff standard should include:
+
+- `surface-frame.json`
+- `content.json`
+- `surface-assets.json`
+- `font-requirements.json`
+- `surface-suggestions.json`
+- `surface-action-plan.json`
+- `verify-recipe.json`
+- `source-map.json`
+- Reference images and render outputs when available
+
+The files should be stable enough for Codex, Claude Code, Cursor, VS Code MCP,
+Playwright visual diff tooling, Storybook workflows, and other agent hosts to
+consume through the same contract.
+
+## Agent Responsibilities
+
+An agent should be able to:
+
+- Read the selected Figma structure.
+- Resolve mapped components.
+- Respect token proposals and naming rules.
+- Load required font and asset metadata.
+- Apply the fix list.
+- Re-run verification and update the receipt.
+
+The bundle should identify what is safe to patch automatically and what needs a
+design-system maintainer decision.
+
+## Compatibility Badge
+
+Tessellate integrations can advertise compatibility when they can consume the
+bundle, preserve source-node traceability, and return a Surface Receipt after
+implementation. Compatibility should mean the agent can apply without guessing,
+not merely read a screenshot.

docs/ci.md

@@ -0,0 +1,43 @@
+# CI Receipt Gate
+
+The CI receipt gate turns Surface verification into a pull request artifact.
+It lets engineering teams enforce visual parity and design-system contract
+health after implementation changes land in code.
+
+## Goal
+
+A repository should be able to run a command equivalent to:
+
+```sh
+tessellate verify surface ./surface-handoff
+```
+
+The command should render the implementation, compare it against the
+Figma/reference image, publish a Surface Receipt, and fail above threshold.
+
+## Pull Request Artifact
+
+The CI output should attach:
+
+- Surface Receipt summary.
+- Figma source reference.
+- Implementation render.
+- Diff image or pixel-diff score.
+- Source map.
+- Drift findings.
+- Fix list.
+
+This makes Tessellate visible where implementation work is reviewed: pull
+requests, review comments, and release checks.
+
+## Failure Rules
+
+The gate should fail when:
+
+- Pixel diff exceeds the configured threshold.
+- Required artifacts are missing.
+- Required fonts or assets are unresolved and marked critical.
+- The source map cannot connect rendered output back to required source nodes.
+
+Warnings should remain visible without blocking when the repo policy allows
+manual review.

docs/drift.md

@@ -0,0 +1,39 @@
+# Design System Drift Map
+
+Design System Drift Map is the audit view for design-system teams. It scans a
+Figma file or Surface handoff and shows where the work has drifted away from the
+connected repo contract.
+
+## What It Finds
+
+A drift map should report:
+
+- Unmapped components.
+- Rogue fonts.
+- Token mismatches.
+- Unapproved colors.
+- Repeated patterns not mapped to semantic components.
+- Assets missing repository destinations.
+- Frames that cannot pass visual verification.
+- Missing source metadata for licensed fonts.
+
+## Why It Matters
+
+Teams adopting AI coding agents need a way to decide whether output is safe to
+review or merge. Drift maps create that first filter before a person spends time
+checking spacing, typography, token usage, and component choices by hand.
+
+## Output
+
+The drift map should group findings by severity and owner:
+
+| Category | Example action |
+| --- | --- |
+| Component drift | Map the node to an existing component or approve a generated one |
+| Token drift | Replace hardcoded values with configured token proposals |
+| Font drift | Load an Inlay profile or add font-source metadata |
+| Asset drift | Add a repository destination or mark the asset manual |
+| Pattern drift | Convert repeated rows to a semantic component |
+
+Findings should link into the Surface Receipt and Figma Source Map so every
+warning has a visual region, source node, and suggested remediation path.

docs/receipts.md

@@ -31,6 +31,7 @@ Every buyer-facing receipt should include:
 | Assets | Required media, repository targets, raw URLs, and unresolved assets |
 | Tokens | Proposed token names, values, source nodes, and approval state |
 | Fix list | Ordered implementation actions required to improve parity |
+| Source map | Links to Figma nodes, generated code locations, tokens, mappings, fonts, assets, and diagnostics |
 
 ## Receipt Score
 
@@ -77,3 +78,51 @@ the risk, and the next action:
 
 This turns the receipt into a working queue for developers, AI agents, and
 design-system maintainers.
+
+## Remediation Actions
+
+Receipt diagnostics should become auto-fix candidates whenever the next action
+is deterministic and safe to present for approval. Examples:
+
+- Add missing font metadata to the Surface context or Inlay profile.
+- Replace a fragile glyph mark with a vector asset.
+- Map a repeated row pattern to an existing semantic component.
+- Approve a proposed component name.
+- Move a proposed token into the configured token family.
+- Generate a patch-ready implementation note for a connected agent.
+
+The receipt should distinguish between a safe auto-fix, a suggested patch, and a
+manual design-system decision.
+
+## Interactive Viewer
+
+The receipt should also be viewable as an interactive viewer:
+
+- Left panel: Figma source reference.
+- Center panel: Tessellate render.
+- Right panel: diff, diagnostics, and fix list.
+- Inspector: selected node, code location, token, font, asset, and diagnostic
+  state from the source map.
+
+The viewer turns JSON artifacts into something designers, developers, and
+product leads can review without reading raw manifests.
+
+## Parity Benchmark
+
+Tessellate should publish a public parity benchmark for representative surfaces:
+
+- Marketing hero.
+- Email receipt.
+- Dashboard.
+- Dense table.
+- Mobile screen.
+- Editorial cover.
+- Component library page.
+- Text-heavy layout.
+- Image-heavy layout.
+- Nested auto-layout surface.
+
+The benchmark should score visual parity, semantic component use, token
+correctness, asset handling, font handling, accessibility preservation, and
+setup effort. The benchmark should emphasize proof: the receipt explains why a
+surface passed, failed, or needs remediation.

docs/repo-setup.md

@@ -62,6 +62,23 @@ Each mapping entry should include:
 See [`mappings.md`](./mappings.md) and the neutral mapping fixtures in
 [`../mappings/`](../mappings) for the JSON shape.
 
+## Scan My Repo
+
+Manual setup is the enterprise-control path, but Tessellate should also support
+a lower-friction discovery flow:
+
+1. User connects a repository.
+2. Tessellate scans likely component roots, token files, Storybook metadata,
+   font references, and asset folders.
+3. Tessellate proposes mapping registries, Surface context fields, Inlay
+   profiles, token family config, and import roots.
+4. User approves the generated metadata.
+5. Tessellate writes the approved config back to the repo through an explicit
+   repository workflow.
+
+The scan should propose metadata, not silently own it. The repo remains the
+source of truth.
+
 ## 2. Create The Surface Context
 
 Create a Surface design-system context that validates against

docs/source-map.md

@@ -0,0 +1,66 @@
+# Figma Source Map
+
+The Figma Source Map is Tessellate's traceability layer. It should let a team
+inspect a rendered region and see why it exists, where it came from, and what
+repo fact controls it.
+
+## Purpose
+
+Surface Receipts prove fidelity. Source maps explain fidelity.
+
+Each mapped output region should trace back to:
+
+- Figma node id.
+- Figma layer name.
+- Generated code line or component location.
+- Component mapping.
+- Token proposal.
+- Font source.
+- Asset source.
+- Diagnostic status.
+
+The source map is the bridge between visual evidence and implementation work.
+
+## Shape
+
+A source map entry should be explicit enough for a person or agent to act:
+
+```json
+{
+  "figmaNodeId": "12:34",
+  "layerName": "Billing row",
+  "renderRegion": { "x": 24, "y": 180, "width": 420, "height": 56 },
+  "component": {
+    "name": "BillingSummaryRow",
+    "source": "packages/design-system/BillingSummaryRow.tsx"
+  },
+  "code": {
+    "file": "surface/BillingSummary.tsx",
+    "line": 42
+  },
+  "tokens": ["surface.billing.row.border", "surface.billing.label.typography"],
+  "font": {
+    "family": "Inter",
+    "status": "resolved"
+  },
+  "asset": null,
+  "diagnostics": []
+}
+```
+
+## Viewer Behavior
+
+The interactive viewer should use the source map to support:
+
+- Click a visual region and inspect the Figma node.
+- Click a diagnostic and highlight the affected render area.
+- Jump from a source node to the generated code line.
+- Show which token proposal controls a color, radius, spacing, or type style.
+- Show whether a font or asset was resolved before parity was judged.
+
+## Agent Contract
+
+Agents should consume the same map. If a receipt says a row should become a
+semantic component, the map should provide the node ids, code region, token
+proposals, and diagnostic context needed for the agent to patch the
+implementation without guessing.

scripts/__tests__/product-posture.test.mjs

@@ -5,6 +5,9 @@ import test from "node:test";
 const PRODUCT_TEXT_FILES = [
   "README.md",
   "docs/install.md",
+  "docs/agent-handoff.md",
+  "docs/ci.md",
+  "docs/drift.md",
   "docs/inlay.md",
   "docs/mappings.md",
   "docs/repo-setup.md",
@@ -121,6 +124,45 @@ test("product positioning leads with verification receipts, not broad Figma-to-c
   assert.match(receipts, /implementation confidence/i);
 });
 
+test("product roadmap emphasizes source maps, drift, CI receipts, and agent handoff", () => {
+  const root = readFileSync("README.md", "utf8");
+  const sourceMap = readFileSync("docs/source-map.md", "utf8");
+  const drift = readFileSync("docs/drift.md", "utf8");
+  const ci = readFileSync("docs/ci.md", "utf8");
+  const agent = readFileSync("docs/agent-handoff.md", "utf8");
+  const repoSetup = readFileSync("docs/repo-setup.md", "utf8");
+
+  assert.match(root, /verification layer and repo-aware source map/i);
+  assert.match(root, /Design System Drift Map/i);
+  assert.match(root, /CI receipt gate/i);
+
+  assert.match(sourceMap, /Figma node id/i);
+  assert.match(sourceMap, /generated code line/i);
+  assert.match(sourceMap, /diagnostic status/i);
+
+  assert.match(drift, /unmapped components/i);
+  assert.match(drift, /rogue fonts/i);
+  assert.match(drift, /token mismatches/i);
+
+  assert.match(ci, /pull request artifact/i);
+  assert.match(ci, /fail above threshold/i);
+
+  assert.match(agent, /surface-frame\.json/i);
+  assert.match(agent, /source-map\.json/i);
+  assert.match(agent, /agent can apply without guessing/i);
+
+  assert.match(repoSetup, /Scan My Repo/i);
+  assert.match(repoSetup, /proposes mapping registries/i);
+});
+
+test("receipt roadmap includes remediation, viewer, and public parity benchmarks", () => {
+  const receipts = readFileSync("docs/receipts.md", "utf8");
+
+  assert.match(receipts, /auto-fix/i);
+  assert.match(receipts, /interactive viewer/i);
+  assert.match(receipts, /parity benchmark/i);
+});
+
 test("product copy avoids generic Figma-to-code magic claims", () => {
   const banned = [
     /Figma-to-code/i,