task-pipeline-skill 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## v1.3.0 — 2026-07-29
+
+**One design file, in a named team, decided before anything is drawn.** Left to
+drawing time, "where do I put this?" is answered by whichever agent is holding the
+brush, and the answer is usually *create a new file* — which is how a project
+acquires three files called some variation of "Design", each with real work in it
+and no way to tell which one the team actually opens.
+
+The duplicate is **silent by construction**: the second file is internally
+consistent, its frames are named correctly, and the UX linter is green. Nothing
+downstream notices that half the design now lives where nobody looks.
+
+### Added — the design destination is a stage-0 decision
+- **New sweep row `3 Design file`** (in both homes — `grill.md`'s table, which the
+  grill reads, and `templates/brief.md`, which records the answer): **which
+  team/org, by name, and which file.** Three legal answers: the file already
+  recorded, a URL the operator supplies, or **creation in that named team,
+  explicitly authorized**.
+- **Creation follows the deploy-authorization floor.** *"Create the design file in
+  team `Acme Product`"* authorizes one creation in one place; a vague "set up Figma
+  for me" authorizes nothing, because deciding *where* on its own is the entire
+  failure. `grill.md` → **The design destination** is the new doctrine section.
+- **The team is recorded, not just the file.** A file URL identifies a file; it does
+  not say whose workspace it lives in. super-ux runs `whoami` and asks which team
+  when there are several — but nothing wrote the answer down, and a design that
+  lands in someone's personal drafts is invisible to everyone who needs it.
+- **Two rules that make it stick:** never create while a recorded file resolves;
+  and **if the recorded file does not resolve, stop and ask — never create a
+  replacement.** "I couldn't open it so I made a new one" is simultaneously the
+  duplicate and a hidden permissions problem that a new file does not fix.
+- **Written before the first frame, not after.** A file created and then lost to a
+  crashed context is worse than none: it exists, it is empty, nobody knows it is
+  there.
+
+### Added — the check that catches it mechanically
+- Deep links are `figma.com/design/:fileKey/…`, so **comparing every `screens.md`
+  frame link's key against the canonical record is a string match**, not a
+  judgement. A differing key *is* a second file. This is now the stage-3 gate and
+  the audit ladder's **`→F`** seam; if it ever fires twice, it belongs in the host's
+  lint, per the repeats-twice rule.
+
+### Changed
+- **Canonical record: `docs/ux/foundation.md` → *Design tooling*** — super-ux owns
+  that section, it is per-project and it survives every run, which is exactly what
+  "the agents always know which file" requires. The brief holds the **decision and
+  the authorization** and points at it; it is a record, **not a second registry**,
+  and if the two disagree `foundation.md` wins. On a project with no `docs/ux/` the
+  brief is canonical instead, and **stage 9 writes the destination into the host's
+  own docs** (`conventions.md`) so the next run finds it without asking.
+- **Creating** a shared design file joins the outward list beside *editing* one —
+  it is the stronger of the two, and it is the one that duplicates.
+
+### Validator
+- The shipped intake gate must settle the design destination; a config where stage 0
+  never names the team or the file now fails. Proven against a planted defect and
+  shipped with a CI negative self-test.
+
+## v1.2.0 — 2026-07-29
+
+The pipeline already knew about Figma — but only second-hand, through super-ux, and
+**every one of its own promises had a Figma-shaped hole**. None of these required it
+to learn Figma; super-ux owns that completely and keeps owning it.
+
+### Fixed — four holes in the pipeline's own promises
+- **The sweep never asked about the design surface.** super-ux asks "Figma or
+  text-only" once per project and stores the answer — but that first ask lands
+  *mid-run*, in the very run the sweep exists to make uninterrupted. Worse: when the
+  Figma MCP is absent, super-ux correctly recommends it and then **continues
+  text-only on its own, never blocking**. That is a scope change nobody agreed to —
+  a UI feature ships "described" instead of "designed" and no gate says so. New sweep
+  row **`3 Design surface`**: Figma on or text-only, is the MCP connected, and *if it
+  isn't, ship text-only or stop and connect it?*
+- **The single-preflight promise was broken for UI tasks.** `companion-skills.md`
+  guarantees ONE block — companions plus the model — so the operator arms the whole
+  run in one exchange. The Figma MCP is a companion stage 3 needs, and its check
+  happened later, inside the stage. It is now in the matrix and in the preflight
+  block, flagged only when the task is user-facing *and* the project designs
+  visually (read `docs/ux/foundation.md` → Design tooling first; no record means the
+  choice itself is a stage-0 question).
+- **The audit ladder had no rung for the frame.** Added as **`F`** — deliberately
+  *conditional and parallel*, not a step in the sequence, so `L0→L7` keeps its
+  numbering. A frame is **a second statement of the same surface, made in pictures.**
+  super-ux's linter proves a frame link exists, is named `SCR-NN/<Screen>/<state>`
+  and isn't stale; **it cannot read the picture.** A frame can pass every lint there
+  is while promising a retention window, a credit meter or a pricing tier the spec
+  never described and the code never built — a rendered claim about the product,
+  seen by more people than the spec, and often the version stakeholders believe.
+  Compare frames to frames and they agree; compare specs to specs and they agree;
+  the defect lives in the seam. Two new seam questions: **`L2→F`** does the frame
+  render what the spec says, and **`F→L7`** did what shipped stay matched to it. The
+  spec is the contract — name the document you propose to move instead of quietly
+  redrawing.
+- **Editing a shared design file was missing from the outward list.** Frames are
+  read by designers and stakeholders; drawing in one is publishing, not local work.
+  It now sits beside deploy, publish, repo-create and opening a PR — the list an
+  agent actually reads.
+
+### Added — validator
+- **Autonomy-sweep drift guard.** The sweep lives twice: `grill.md`'s table is what
+  the agent *reads* while interviewing, `templates/brief.md`'s is what it *writes*.
+  A row added to one and not the other is a question never asked, or an answer with
+  nowhere to land. The validator now compares the stage numbers the two tables cover
+  and fails on a difference. Proven against two planted defects (a stage present
+  only in the grill; a stage dropped only from the brief) plus an unmodified control,
+  and shipped with a CI negative self-test. **Scope, stated honestly: it catches
+  stage-level drift, not row-level** — a row added under a stage number both tables
+  already mention passes.
+
+### Changed
+- The boundary is now written down in both directions: super-ux owns *how* to design
+  (the choice, the MCP preflight, frame naming, the drift linter); task-pipeline owns
+  *when to ask, what counts as degradation, and how to check afterwards that the
+  picture and the product still say the same thing*.
+
 ## v1.1.1 — 2026-07-29
 
 Version bump only — a fresh npm artifact for the v1.1.0 content. **No changes to

package/README.md

@@ -297,6 +297,20 @@ Bottom-up is not taste: a missing artefact low on the ladder makes everything ab
 it meaningless, so top-down you spend the pass polishing a surface for a contract
 that does not exist.
 
+**The frame is a rung too, where the project designs visually.** super-ux owns the
+frame completely — the Figma on/off choice, the MCP preflight, the
+`SCR-NN/<Screen>/<state>` naming, and a linter that catches a missing, misnamed or
+stale link. What no linter can check is **what the frame says.** A link can be
+present, correctly named and fresh while the picture behind it promises a retention
+window, a credit meter or a pricing tier the spec never described and the code
+never built — a rendered claim about the product, seen by more people than the
+spec, and often the version stakeholders believe. Compare frames to frames and they
+agree; compare specs to specs and they agree; the defect lives in the seam. So the
+walk adds two questions on UI work: *does the frame render what the spec says*, and
+*does what shipped still match the frame*. The spec is the contract — say which
+document you propose to move, and remember that **editing a shared design file is
+outward**, like a PR or a deploy.
+
 Three rules keep the audit from becoming another loop:
 
 - **Every pass changes the axis, not the effort.** A searching pass doesn't
@@ -343,6 +357,34 @@ in their DoD. Scenarios come before interface.
 /plugin install super-ux@super-ux
 ```
 
+**Figma is super-ux's, and the decision about it is stage 0's.** super-ux mirrors
+every `SCR-` screen and state into a frame when the project designs visually, and
+it handles all of it: the on/off choice, the MCP preflight, the naming contract,
+the drift linter. task-pipeline only settles the part that would otherwise
+interrupt a run — *is Figma on, is the MCP connected, and if it isn't, do we ship
+text-only or stop and connect it?* That last clause matters: super-ux recommends
+the MCP and then **continues text-only on its own, never blocking**, so an unasked
+question quietly narrows the delivery from "designed" to "described". The stage-0
+sweep decides it, and the preflight block flags the missing MCP in the same
+exchange as everything else.
+
+**One file, in a named team, decided before anything is drawn.** Left to drawing
+time, "where do I put this?" gets answered by whichever agent is holding the brush,
+and the answer is usually *create a new file* — which is how a project acquires
+three files called some variation of "Design", each with real work in it. So the
+sweep settles the **team or organization by name** (a file URL says which file, not
+whose workspace — a design that lands in someone's personal drafts is invisible to
+everyone who needs it) and **the file**: the one already recorded, a URL you supply,
+or creation in that named team, explicitly authorized the same way a deploy target
+is. Two rules make it stick: **never create while a recorded file resolves**, and
+**if the recorded file doesn't resolve, stop and ask — never create a replacement**,
+because "I couldn't open it so I made a new one" is both the duplicate and a hidden
+permissions problem. The URL is written to the project's canonical record —
+`docs/ux/foundation.md` → *Design tooling*, or the repo's own docs when there's no
+UX chain — **before the first frame**, and the audit's `F` rung then checks it
+mechanically: every `screens.md` deep link is `figma.com/design/:fileKey/…`, so a
+key that differs from the recorded one is a second file, caught by a string match.
+
 ### Model policy — one model, confirmed once
 
 The default recommendation is *the most capable reasoning model the environment

package/cursor/rules/task-pipeline.mdc

@@ -66,7 +66,22 @@ mid-flight questions:
    in play and whether stage 9 may write to them**; UI verdict; base branch, branch policy,
    commit convention, task tracker; the test command and what "green" means; the
    lint command; the deploy target, release toggle and **deploy authorization**;
-   where logs/health live; which docs and runbooks this change updates. Each item
+   where logs/health live; which docs and runbooks this change updates. For UI
+   tasks also: **is the design done visually (Figma) or text-only, is the Figma MCP
+   connected, and if it isn't — ship text-only or stop and connect it?** The UX
+   chain degrades to text-only on its own and never blocks, so an unasked question
+   there silently ships a UI feature with no mockups. **And with Figma on, settle
+   the destination here, never at drawing time: which team/org by name, and which
+   file** — the one already recorded, a URL the user gives, or *creation in that
+   named team, explicitly authorized*. A file URL says which file, not whose
+   workspace, and a design that lands in someone's personal drafts is invisible to
+   the people who need it. **Never create a file while a recorded one resolves; if
+   it doesn't resolve, stop and ask — never create a replacement**, because "I
+   couldn't open it so I made a new one" is how a project ends up with three design
+   files and hides a permissions problem at the same time. Write the URL into the
+   project's own record (`docs/ux/foundation.md` → Design tooling if the UX chain
+   exists, otherwise the repo's `CLAUDE.md`/README) **before the first frame** — a
+   file created and then lost to a crashed context is worse than none. Each item
    gets an answer or an explicit "stop and ask me here" — an unasked question is a
    scheduled interruption.
 
@@ -167,13 +182,25 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
     bottom-up through its rungs — recorded decision → spec section → contract *and
     its failure behavior* → plan task with a satisfiable DoD → the change in the
     tree → an **executed** named assertion → the surface a user reaches, and its
-    docs — checking the seam between each pair: does the decision reach the spec;
+    docs, **plus, on UI work designed visually, the frame as a second parallel
+    statement of the same surface** — checking the seam between each pair: does the
+    decision reach the spec;
     does the section say what happens when the contract fails; does every contract
     have a task; did the DoD land in the diff; would that test still pass with the
     production code deleted; can a user reach this and does a doc say so; and
     finally, does what shipped satisfy the requirement's own *statement* rather
-    than the task's instructions. Order findings **by seam, not by file** — the
-    seam tells you which layer of your process leaks. Every absence becomes a new
+    than the task's instructions. **And for a frame: does it render what the spec
+    says, and does what shipped still match it?** A UX linter proves a frame link
+    exists, is named right and isn't stale — it cannot read the picture, so a frame
+    promising a retention window, a credit meter or a tier nobody built passes
+    every lint there is, while being the version stakeholders believe. The spec is
+    the contract: say which document you propose to move, don't quietly redraw, and
+    remember that editing a shared design file is outward. **Also check the file,
+    not just the frames:** deep links are `figma.com/design/:fileKey/…`, so
+    comparing each screen link's key against the recorded destination is a string
+    match — a differing key is a second design file with real work in it, and
+    nothing else notices, because that file is internally consistent and its frames
+    are named correctly. Order findings **by seam, not by file** — the seam tells you which layer of your process leaks. Every absence becomes a new
     REQ row with its check **before** the table is written; appending afterwards is
     how acceptance goes green over a gap. Findings owned by a lower layer go back
     there (spec → stage 3, plan → stage 4).
@@ -190,7 +217,10 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
 Cross-cutting: answer from the brief's autonomy section rather than re-asking, log every deferral in the ledger, never narrow the task silently, track
 tasks, conventional commits, honest degradation (never claim a failed/skipped step
 succeeded), and get explicit go before any outward/irreversible action (deploy,
-publish, repo create).
+publish, repo create, **editing a shared design file** — frames are read by
+designers and stakeholders, so drawing in one is publishing, not local work — and
+above all **creating** one, which needs a named team and never happens while a
+recorded file resolves).
 
 **Loop guard — break churn instead of iterating.** Every repeating pass (a fix
 round, a re-entered stage, the next module) logs one line per touched file: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "task-pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "author": {
     "name": "ssheleg"
   },

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -23,7 +23,7 @@ applying the
 grill's **domain awareness** (challenge terms against `CONTEXT.md`, sharpen fuzzy
 language, ADRs for hard-to-reverse calls) and covering the **autonomy sweep** (what
 would otherwise stop stages 1→10: docs sources incl. doc repos and the wiki, branch/tracker
-policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets) —
+policy, test and lint commands, deploy target and authorization, log locations, docs/wiki targets, and for UI tasks whether the design is done visually in Figma or text-only, whether the Figma MCP is connected, and — if it isn't — whether to ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; **and with Figma on, the design destination: which team/org by name and which file** — the recorded one, a URL the operator gives, or creation in that named team explicitly authorized, written into the project's canonical record before the first frame, because a destination decided at drawing time is how a project ends up with three design files and no way to tell which is real. **Never create while a recorded file resolves; if it doesn't resolve, stop and ask — never create a replacement**) —
 until the brief is locked — including the **REQ table**, the request as an addressable list where every row names how it is verified — so the rest runs autonomously and the final stage can account for all of it. The list is frozen: adding is free, removing needs the operator's agreement. Anything deferred goes into the carry-over ledger the moment it's said. For any user-facing task, recommend/use
 **super-ux**. **If the brief describes a platform rather than a change**, stage 2 also cuts it into modules (`references/decomposition.md`) — module map committed, walking skeleton first, every REQ in exactly one module — and stages 3→10 then run per module, one brick at a time. **If any loop starts undoing an earlier pass** (same file edited twice for the same reason, a closed finding returning, a third entry into one stage), stop and run the loop guard (`references/loop-guard.md`): name both shapes, escalate to the layer that owns the conflict, re-plan the check as an ordered list, then go item by item. **The closing stage opens with the ladder walk** (`references/audit.md`): the REQ table finds what was named and lost, but a comparison needs two sides and an absence has one — so walk each REQ bottom-up through its rungs (decision → spec section → contract *and its failure behavior* → task → change → executed test → surface/docs), check the seam at each step, order findings by seam rather than by file, and turn every absence into a new REQ row **before** the coverage table is written. A green from a check nobody has watched fail against a planted defect is not evidence; a finding class seen twice becomes a script rather than a third ledger row; and the carry-over ledger's counts are printed beside every gate verdict, so "green" never reads as "verified". If a searching pass starts finding mostly what the previous pass's own fixes broke, the axis is exhausted — rotate it, don't look harder. Honor every stage gate by its type (`auto` = verify yourself;
 `manual` = wait for explicit go). Confirm the **model once at preflight** —

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -170,7 +170,10 @@ Three things the grill does beyond clarifying the request:
    tracker + conventional commits per host conventions; worktree isolation for the
    build, integrated back per the brief's branch policy before stage 7; honest
    degradation (never claim a failed/skipped step succeeded);
-   outward/irreversible actions (deploy, publish, repo create, opening a PR) need explicit
+   outward/irreversible actions (deploy, publish, repo create, opening a PR,
+   **editing a shared design file — frames are read by designers and stakeholders,
+   so drawing in one is publishing — and above all *creating* one, which needs a
+   named team and never happens while a recorded file resolves**) need explicit
    operator go — or a **specific** standing authorization recorded in the brief
    (named target + preconditions; a vague "do everything" is not one).
 

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -15,7 +15,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded."
       }
     },
     {
@@ -57,11 +57,12 @@
         "super-ux:ux-flows",
         "super-ux:ux-scenarios",
         "super-ux:ux-lint",
+        "figma",
         "task-pipeline:spec"
       ],
       "gate": {
         "type": "manual",
-        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID. Every spec section carries covers: REQ-... and every REQ appears in at least one section."
+        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID. Every spec section carries covers: REQ-... and every REQ appears in at least one section. With Figma on: the destination the brief named was used — the canonical record (docs/ux/foundation.md -> Design tooling) holds exactly one file, no file was created while a recorded one resolved, and every screens.md frame link carries that same :fileKey (a string match, not a judgement — a differing key means the run drew in a second file nobody will open)."
       }
     },
     {

package/plugins/task-pipeline/skills/task-pipeline/references/audit.md

@@ -74,6 +74,7 @@ absence findable.
 | **L5** | Change | the commits — the thing actually in the tree |
 | **L6** | Test | an **executed** assertion, by name — never "the tests pass" |
 | **L7** | Surface | what a user reaches: scenario, screen state, CLI output, runbook |
+| **F** | Frame — *conditional* | UI work with Figma on: one frame per `SCR-NN/<Screen>/<state>`, **in the one file the project recorded**. Not a step in the sequence — a **second, parallel statement of the same surface**, made in pictures |
 
 **Audit the seams, not the artifacts.** Each rung is internally consistent most of
 the time — that is exactly what the horizontal pass is good at, and it has already
@@ -89,10 +90,49 @@ done it. What survives lives between rungs:
 | L5→L6 | is there an executed observable? | "tests pass"; a test that still passes with the production code deleted |
 | L6→L7 | can a user reach it, and does a doc say so? | shipped behavior with no scenario, no `--help` line, no runbook entry |
 | L7→L0 | does the shipped surface satisfy the requirement's **statement**? | it does what the task said and not what the requirement meant |
+| L2→F | *(UI)* does the frame render what the spec **says**? | a frame that promises a capability, limit or number the product does not have |
+| F→L7 | *(UI)* did what shipped match the frame, or did the frame become fiction? | the frame is still the design of record and no longer describes anything that exists |
+| →F | *(UI)* is every frame **in the recorded file**? | a second design file nobody opens, holding real work — the check is a `:fileKey` string match, so it is a gate, not an opinion |
 
-The last seam is stage 10's question, expressed as a seam. When it fails, the run
+The L7→L0 seam is stage 10's question, expressed as a seam. When it fails, the run
 did every instruction correctly and delivered the wrong thing.
 
+### The frame is a second claim, and nothing compares it to the first
+
+Where the project designs in Figma, **super-ux owns the frame entirely** — the
+on/off choice, the MCP preflight, the `SCR-NN/<Screen>/<state>` naming, and a
+linter that catches a missing link, a broken trace or a stale one. That is a lot,
+and none of it is this file's business.
+
+What no linter can check is **what the frame says.** A frame link can be present,
+correctly named, non-stale — and the picture behind it can state a retention
+window, a credit meter, a pricing tier or a button whose promise the spec never
+made and the code never implements. It is a *claim about the product*, rendered,
+usually seen by more people than the spec, and frequently the thing a stakeholder
+believes. Compare frames to frames and they are consistent; compare specs to specs
+and they are consistent; the defect lives in the seam, and only a walk finds it.
+
+So on UI work with Figma on, the walk carries one extra step in each direction:
+read the frame against the spec section that covers its `SCR-` id (`L2→F`), then
+against what actually shipped (`F→L7`). A mismatch is a finding like any other —
+and it is usually the **frame** that must change, because the spec is the contract.
+Say which one you are proposing to move, and why, rather than quietly redrawing.
+
+**Editing someone else's Figma file is outward.** Frames live in a shared file that
+designers and stakeholders read; changing one is publishing, not local work.
+Propose the change, get an explicit go, and only then draw — the same rule as a PR,
+a deploy, or docs in another repository. **Creating** one is stronger still: it
+needs a named team and an explicit authorization recorded at intake
+([`grill.md`](grill.md) → *The design destination*).
+
+**And check the file, not just the frames.** Every deep link is
+`figma.com/design/:fileKey/…`, so comparing each `screens.md` link's key against
+the canonical record (`docs/ux/foundation.md` → *Design tooling*) is a string
+match. A key that differs is a **second file with real work in it** — the failure
+that starts with one agent unable to open the recorded file and quietly making a
+new one. Nothing else in the chain notices: the new file is internally consistent,
+its frames are named correctly, and the linter is green.
+
 ## How one audit pass runs
 
 **Scope: one deliverable, all rungs.** One REQ, one module, one capability. Not
@@ -222,3 +262,6 @@ a script — and if it cannot be, **that is the finding: write the check.**
 | "Findings grouped by file are easier to fix" | And impossible to learn from. Group by seam; the seam names which layer of your process leaks. |
 | "The ledger has it, we won't forget" | Only if it is printed beside every verdict. Unprinted, it is a TODO, and TODOs are invisible by construction. |
 | "This is out of scope for the audit" | Then it is a carry-over row with a home, right now. An audit that silently declines findings is worse than none. |
+| "The UX linter is green, the frames are fine" | It proved the links exist, are named right and aren't stale. It cannot read the picture. A frame that promises a feature nobody built passes every lint there is. |
+| "The frame is wrong, I'll just redraw it" | Editing a shared design file is outward, and the spec is the contract. Say which document you are moving and get the go. |
+| "I couldn't open the recorded file, so I made a new one" | That is the duplicate, and it hides a permissions problem a new file does not fix. Unreachable means stop and ask. |

package/plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md

@@ -30,6 +30,7 @@ better, plus one that is required only for user-facing work.
 |---|---|---|---|
 | **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
 | **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
+| **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
@@ -62,6 +63,11 @@ Pipeline companions (stage doctrine is built in — nothing to install for it):
                            /plugin marketplace add ssheleg/super-ux
                            /plugin install super-ux@super-ux
   ✓ context7           — ready
+  ✗ Figma MCP          — this task is user-facing and the project designs in Figma
+                         (docs/ux/foundation.md → Design tooling). Without it the
+                         UX chain still runs, text-only — no mockups this run:
+                           connect the Figma MCP via /mcp
+                         (say "text-only is fine" and I'll record that instead)
   ✗ obsidian-wiki      — recommended: stage 0 queries it before grilling you,
                          stage 9 syncs back what this run learned:
                            pip install obsidian-wiki
@@ -82,6 +88,17 @@ Rules:
   `wiki-query`/`wiki-update`. Present → say `✓ ready` and use it in the harvest.
   Absent → print the two install lines **once** and continue; never ask twice in a
   run and never block a stage on it ([`knowledge-sources.md`](knowledge-sources.md)).
+- **Figma MCP**: flag it only when the task is user-facing **and** the project
+  designs visually — read `docs/ux/foundation.md` → *Design tooling* first; no
+  record yet means the choice itself is a stage-0 question (super-ux's default is
+  on). Detect the official Figma MCP tools; **how** frames get built, named and
+  linted is entirely super-ux's — its own `figma-integration.md` and
+  `figma-structure.md` own that — while this preflight only decides whether the run
+  has the capability
+  and, if not, what ships instead. That last part is the point: super-ux recommends
+  the MCP and then *continues text-only on its own*, so without a recorded answer
+  the run silently narrows from "designed" to "described". The sweep row is
+  `3 Design surface` ([`grill.md`](grill.md) → *The autonomy sweep*).
 - **Never gate any stage on an install** except the stage-3 UX track on a UI task.
 - Optional tools missing → state the fallback, don't block.
 - Re-detect after the operator installs; don't assume.

package/plugins/task-pipeline/skills/task-pipeline/references/conventions.md

@@ -38,6 +38,12 @@ found, surface it and **ask** rather than guessing.
   proved stale is already listed there with what's wrong.
 - Host self-update rules (module docs, runbooks, agent-self cards, etc.) — update
   in the same change. Fix dangling links.
+- **The design destination, on a project with no `docs/ux/`.** When the work uses
+  Figma but super-ux isn't in play, there is no `foundation.md` to hold the file, so
+  the brief is canonical — and a brief is per-run. Write the team and the file URL
+  into the host's own docs (`CLAUDE.md`, or the README) in this change, so the next
+  run reads the destination instead of creating a second file
+  ([`grill.md`](grill.md) → *The design destination*).
 - **Wiki:** [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — the
   `wiki-update` skill (resolves the vault via `~/.obsidian-wiki/config`). Detect it
   the same way the harvest does; if absent, recommend it once

package/plugins/task-pipeline/skills/task-pipeline/references/grill.md

@@ -134,6 +134,8 @@ explicit "stop and ask me here":
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
 | 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
 | 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |
+| 3 Design surface | UI tasks only: **Figma on or text-only** (super-ux's project-level choice, default on — check `docs/ux/foundation.md` → *Design tooling* before asking); is the Figma MCP connected; **and if it isn't — ship text-only, or stop here and connect it?** super-ux degrades to text-only on its own and never blocks, which means an unasked question here silently ships a UI feature with no mockups |
+| 3 Design file | Figma on only: **exactly which file, in which team/org** — the recorded one, or a URL the operator gives, or *create one in a named team* with that creation explicitly authorized. A destination decided at drawing time is how a project ends up with three "design" files and no way to tell which is real. See *The design destination* below |
 | 4–5 Dev | base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker |
 | 5 Integration | how the branch lands (merge / PR + approver / "leave it unmerged"); parallel fan-out wanted (one worktree per implementer)? |
 | 6 Tests | the test command; what "green" means here; known-red baseline; coverage expectation |
@@ -149,6 +151,58 @@ preconditions ("staging once lint and the full suite are green; production alway
 asks"). Specific and recorded → it satisfies the stage-7 manual gate. Broader,
 absent or ambiguous → stage 7 stops and asks.
 
+## The design destination — one file, decided here, never invented later
+
+When the project designs in Figma, **the destination is a stage-0 decision, not a
+stage-3 side effect.** Left to drawing time, the question "where do I put this?"
+gets answered by whichever agent happens to be holding the brush, and the answer is
+usually *create a new file* — which is how a project acquires three files called
+some variation of "Design", each with real work in it and no way to tell which one
+the team actually opens.
+
+**Settle three things, in this order:**
+
+1. **Is there already a file?** Read `docs/ux/foundation.md` → *Design tooling*
+   first. A recorded, resolving file ends the question — record "use the recorded
+   file" and move on. Do not ask the operator something the project already answered.
+2. **Which team / organization**, by name. A file URL identifies a file; it does not
+   say whose workspace it lives in, and a design that lands in someone's personal
+   drafts instead of the team space is invisible to everyone who needs it. When the
+   operator belongs to several teams, the choice is theirs and it gets written down —
+   `whoami` tells you which are available, it does not tell you which is right.
+3. **Which file** — an existing URL the operator supplies, or **creation in that
+   named team, explicitly authorized.**
+
+**Creating a file in a shared workspace is outward and irreversible enough to need a
+named target.** It follows the same floor as deploy authorization above: *"create
+the design file in team `Acme Product`"* authorizes one creation in one place. A
+vague "set up Figma for me" does not — the whole failure this row prevents is an
+agent deciding *where* on its own.
+
+**Two rules that make it stick:**
+
+- **Never create when a recorded file resolves.** Check before you create, every
+  time, in every run.
+- **If the recorded file does not resolve** — deleted, moved, no access — **stop and
+  ask. Never create a replacement.** A replacement is exactly the duplicate this
+  section exists to prevent, and "I couldn't open it so I made a new one" is how it
+  always happens. An unreachable file is usually a permissions problem, which a new
+  file does not solve and does hide.
+
+**Where it lives, and which copy wins.** `docs/ux/foundation.md` → *Design tooling*
+is **canonical** — super-ux owns that section, it is per-project, and it survives
+every run, which is exactly what "the agents always know which file" requires. The
+brief records the **decision and the authorization** and points at it; it is a
+record, not a second registry. If the two ever disagree, `foundation.md` wins and
+the brief is the thing that was stale. On a project with no `docs/ux/` at all, the
+brief is canonical instead, and **stage 9 writes the destination into the host's own
+docs** (`CLAUDE.md` or the README) so the next run finds it without asking.
+
+**Write it down before drawing, not after.** The URL goes into the canonical record
+the moment the file is chosen or created — before the first frame. A file created
+and then lost to a crashed context is worse than no file: it exists, it is empty,
+and nobody knows it is there.
+
 ## The REQ spine — the grill's other hard output
 
 Prose scope is not checkable. Before the brief is confirmed, the grill must turn

package/plugins/task-pipeline/skills/task-pipeline/references/spec.md

@@ -21,6 +21,14 @@ Runs on **super-ux** — the one companion this pipeline recommends by name
 ([`companion-skills.md`](companion-skills.md)). If it isn't installed on a UI task,
 give the install line and stop; don't improvise a half-chain.
 
+0. **The design destination is already decided — read it, don't re-open it.** When
+   Figma is on, the stage-0 brief names the team/org and the file
+   ([`grill.md`](grill.md) → *The design destination*), and
+   `docs/ux/foundation.md` → *Design tooling* is the canonical record. Confirm the
+   recorded file **resolves** before any drawing. **Never create a file when a
+   recorded one resolves; if it doesn't resolve, stop and ask — never create a
+   replacement.** A creation happens at most once per project, in the team the
+   brief names, and its URL goes into the canonical record before the first frame.
 1. `/ux` — the single super-ux entry: reports which `docs/ux/` layers exist,
    repairs the skeleton, records the Figma on/off choice, recommends the next
    action. Never make the operator pick skills.
@@ -141,4 +149,11 @@ designed, validated and approved; `/ux-lint` green; every user-facing requiremen
 traced to a scenario ID — or an explicit waiver from the operator recorded in the
 spec.
 
+With Figma on, one more, and it is mechanical: **the canonical record names a file,
+and every frame link in `screens.md` carries that same file key.** Deep links are
+`figma.com/design/:fileKey/…`, so this is a string comparison, not a judgement — a
+link whose key differs points at a *second* file, which means the run drew
+somewhere nobody will look. Same check at the audit's `F` rung
+([`audit.md`](audit.md)); if it ever fires twice, it belongs in the host's lint.
+
 No plan starts before this gate passes.

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -131,6 +131,13 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   ssheleg/super-ux` → `/plugin install super-ux@super-ux`, or `npx skills add
   ssheleg/super-ux`). super-ux builds a traced chain — walk it top-down (see its
   `system-map.md`):
+  0. **Destination first, when Figma is on.** The brief already names the team/org
+     and the file; `docs/ux/foundation.md` → *Design tooling* is the canonical
+     record. Confirm it **resolves** before drawing. **Never create a file while a
+     recorded one resolves; if it doesn't resolve, stop and ask — never create a
+     replacement** (that is the duplicate, and it hides a permissions problem).
+     A creation happens at most once, in the named team, and its URL is written to
+     the canonical record before the first frame.
   1. `/ux` (the only super-ux entry) — reports which `docs/ux/` layers exist,
      repairs the skeleton, records the Figma on/off choice, recommends the next
      action. Never make the operator pick skills.
@@ -162,7 +169,10 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   additionally: the super-ux chain (foundation → flows → screens → scenarios) is
   designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
   the linter passes; every user-facing spec requirement traces to a scenario ID
-  (or an explicit v1-mode/tiny-project waiver by the operator). No plan (stage 4)
+  (or an explicit v1-mode/tiny-project waiver by the operator). **With Figma on:
+  the canonical record names one file, and every `screens.md` frame link carries
+  that same `:fileKey`** — a string match, not a judgement; a differing key means
+  the run drew in a second file nobody will open. No plan (stage 4)
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
@@ -267,7 +277,12 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   comparison needs two sides and an absence has one. So before the table: walk each
   REQ bottom-up through its rungs (decision → spec section → contract **and its
   failure behavior** → task → change → executed test → surface/docs), check the
-  seam at each step, and order the findings **by seam, not by file**. An absence
+  seam at each step, and order the findings **by seam, not by file**. On UI work
+  designed visually, the frame is a **second, parallel statement of the same
+  surface**: read it against the spec section that covers its `SCR-` id and against
+  what shipped. The super-ux linter proves a frame link exists, is named right and
+  is not stale — it cannot read the picture, so a frame promising a limit, a meter
+  or a tier nobody built passes every lint there is. An absence
   becomes a **new REQ row with its check** and *then* the table is written;
   appending after the table is how acceptance goes green over a gap. Findings that
   belong to a lower layer go back to that layer (spec → stage 3, plan → stage 4).

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -83,6 +83,8 @@ is not neutral — it is a scheduled interruption.
 | 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
 | 2 Decompose | Platform (several capabilities/surfaces) or one module? If platform — deploy cadence: per module, or once at the end | … |
 | 2–3 Spec | UI verdict (arms super-ux); scenario-tracing waiver, if any | … |
+| 3 Design surface | UI only: Figma on or text-only (check `docs/ux/foundation.md` → Design tooling first); Figma MCP connected? **If not — ship text-only, or stop and connect it?** | … (super-ux never blocks on a missing MCP, so an unanswered row here ships the feature without mockups) |
+| 3 Design file | Figma on only: **which team/org + which file** — existing URL, or "create one in team `<name>`" **with creation authorized**. Canonical record: `docs/ux/foundation.md` → Design tooling | … (team: `<name>` · file: `<url>` \| `create in <team>, authorized` — never create when a recorded file resolves) |
 | 4–5 Dev | Base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker | … |
 | 5 Integration | How the branch lands — direct merge, PR (who approves), or "leave it, I'll merge"; is parallel fan-out (one worktree per implementer) wanted? | … |
 | 6 Tests | Test command; what "green" means; known-red baseline; coverage expectation | … |