task-pipeline-skill 1.47.2 → 1.48.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## v1.48.0 — a screen is the frame implemented, and four mechanisms this project owed itself
+
+**A screen is the frame, implemented.** Until now Figma was an address and a link: the
+brief recorded which file, `screens.md` carried frame URLs, the linter checked they were
+not stale. Nothing said the screen is **built from** it. Now the order of authority is
+fixed — `super-ux` says what the screen does, the **frame** says what it is made of, and
+`sheleg-design` says how it looks and moves **where the frame is silent**, after the file
+and never instead of it.
+
+Made concrete rather than aspirational: the composition is compared against the node
+tree, not recalled; layout is read from `get_design_context`, because from a screenshot
+it is recovered approximately and approximate is indistinguishable from exact in a
+report; a node with a Code Connect mapping is used, not reimplemented, since a rewrite
+is a silent fork of the design system; and a raw hex where a variable exists is a token
+that has quietly split in two.
+
+With the honest boundary that keeps it followable: **a frame is one width.** Behaviour
+at other breakpoints, and states the frame never draws — error, empty, loading — are
+decisions that get **recorded**, not guessed. Without that line the rule is broken on
+day one and then ignored entirely.
+
+**No frame for a screen: build it, name it, offer to draw it, mark what gets drawn.**
+Figma stays a recommendation whose absence is named and never blocks. The screen comes
+from the style pack, the spec says so screen by screen, and the run offers to draw the
+missing frames into the file the brief already named — which screens, where, from what,
+so the size is visible before anyone says go. Drawing happens only on an explicit go,
+and whatever is drawn is marked as coming from implementation. **A designer must be able
+to tell a decision from a generation**; an unmarked generated frame is the same false
+confidence as an unproven green.
+
+**Another agent may be in this repository right now.** Isolation used to mean *your*
+passes not colliding with each other. It now also means someone else's: a worktree per
+agent, always, because sharing a checkout is what turns two independent changes into one
+corrupted state — a copy taken mid-write, an edit staged into another commit, a branch
+switched under a running test. And a lease before any shared register where the project
+carries `.claude/agent-sync.json`, because a worktree separates files and answers nothing
+about who may edit the board.
+
+With the asymmetry that keeps the rule from becoming a licence: **on finding the other
+agent mid-run, leave their work alone.** Their uncommitted edits are not yours to stage,
+revert or stash. Put a ref on your own committed work so a branch reset cannot lose it,
+and continue in a worktree of your own — ending someone else's work to unblock yours is
+what `residue.md` refuses, one layer up.
+
+This is measured, not feared. One session produced four version collisions, a `files[]`
+entry dropped silently by a merge and caught only by the validator, and a test run that
+failed because a probe copied the tree while another agent was writing to it. This
+repository now carries the coordination config it was telling every other project to keep.
+
+**Four mechanisms this project had decided on and never built.**
+
+`DEC-0001` ruled that `SURFACED: 0` is checked against what the run filed — a run that
+opened a board row and reports nothing surfaced contradicts its own artefacts, and the
+`Source` column makes that computable. The decision was recorded and nothing implemented
+it, which is R-006's own subject applied to a decision instead of a finding. It is a
+check now, and it carries its residual in the same breath: it kills the silent zero, not
+the blind spot.
+
+`R-006` has been in force for four releases because nothing could read the distinction
+it draws. Stage 10 now records, per finding, **one of two words** — `behaviour` or
+`reporting`. A row saying `reporting` stays open on the board; only `behaviour` closes it.
+
+**The release path now runs the suite it advertises.** Two releases shipped over a red
+suite because the negatives ran on the PR and never on the tag. A tag is not evidence.
+
+**And a version number already spoken for now fails at the commit rather than at the
+merge.** Four collisions in one session, each costing a renumber of a whole branch.
+
+Guards: 294 → **309**.
+
 ## v1.47.2 — the body stopped retelling its own references
 
 `Prerequisites` was 2585 of the body's 6585 tokens, and most of it was a second

package/HOW-IT-WORKS.md

@@ -5,7 +5,7 @@ explains the machine — what routes a request into it, what each stage refuses
 let past, and what makes any claim it prints believable. The README sells it and
 tells you how to install it; this file tells you how it thinks.
 
-> **Version 1.47.1.** The "What changed" section at the bottom carries the last
+> **Version 1.48.0.** The "What changed" section at the bottom carries the last
 > few releases. Everything above it describes the pipeline as it is *now*, not as
 > it was designed.
 
@@ -238,7 +238,7 @@ This is the part most pipelines skip, and it is the reason this one is trustwort
 rather than merely tidy.
 
 **Every guard is proven against a planted defect.** `npm run test:all` breaks the
-thing each of the **294** checks is about, and requires that check to reject it. A
+thing each of the **309** checks is about, and requires that check to reject it. A
 guard that has never been watched failing is not a guard; it is a comment.
 
 **The neighbour probe.** A check has a *subject* — the rule it is about — and
@@ -291,6 +291,17 @@ a run diverges  →  retro entry  →  retro.publish  →  upstream issue
 
 ## What changed, by version
 
+### v1.48.0 — a screen is the frame implemented, and four mechanisms this project owed itself
+Figma stops being an address and becomes the source: composition compared against the
+node tree, layout read rather than eyeballed, Code Connect used rather than rewritten,
+tokens naming their variables — with the honest boundary that a frame is one width, and
+a no-frame branch that builds, names, offers to draw, and marks what it drew.
+Plus a worktree per agent and a lease before any shared
+register — measured at four version collisions in one session — the
+SURFACED contradiction check DEC-0001 decided and nobody built, R-006 made readable, a
+release path that runs its own suite, and a version guard that fails at the commit
+rather than at the merge. Guards: 294 → 309.
+
 ### v1.47.1 — the fixes a reader found, which three releases shipped without
 Three releases went out from another session while this branch was reviewed, and
 each carried the same defects forward: the doc map forbidding the decisions register

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.47.2 |
+| **Version** | 1.48.0 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.47.2",
+  "version": "1.48.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

@@ -2,7 +2,7 @@
   "name": "task-pipeline",
   "displayName": "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 closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.47.2",
+  "version": "1.48.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -311,6 +311,11 @@ table substitute for that answer.
    its four registers with their ids. A run that cannot say what happened has not
    finished; it has stopped. This file is the one stage 10 opens, and it carried every
    other criterion while omitting this one for a release.
+12a. **Every finding closed in this run records which changed — the behaviour or
+   only the reporting.** One of two words per finding, `behaviour` or `reporting`,
+   beside its id. Reporting a gap honestly is not fixing it, and the two have
+   looked identical in every close-out that did not say which. A finding whose row
+   says `reporting` stays open on the board with its id; only `behaviour` closes it.
 13. **The run has given the environment back** ([`residue.md`](residue.md)) — all
    eight classes enumerated **by class, never by one tool**, everything this run
    started ended in dependency order, each teardown verified by **re-enumerating

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

@@ -41,9 +41,11 @@ reviewer's.
 ## Contents
 
 - 1. Isolation
+- 1a. Another agent may be in this repository right now
 - 2. Workspace and ledger
 - 3. Models
 - 4. The task loop
+- 4a. A screen is the frame, implemented
 - 5. Final whole-branch review
 - 6. Integrate, then finish
 - GATE (auto)
@@ -93,6 +95,36 @@ download`), then run the test command from the brief's autonomy sweep. A dirty
 baseline makes every later failure ambiguous: report failures and let the operator
 decide whether to proceed.
 
+## 1a. Another agent may be in this repository right now
+
+Isolation above is about *your* passes not colliding with each other. This is about
+someone else's.
+
+**Check before you start, and check by looking rather than by assuming.** A second
+agent leaves traces: uncommitted changes you did not make, a branch that moved under
+you, a version number that was free an hour ago and is taken now. The cost is not
+hypothetical — one session measured four version collisions, a `files[]` entry dropped
+silently by a merge, and a test run that failed because a probe copied the tree while
+someone else was writing to it.
+
+**Two mechanisms, and they answer different questions.**
+
+1. **A worktree per agent, always.** Sharing a checkout is what turns two independent
+   changes into one corrupted state: a copy taken mid-write, an edit staged into
+   somebody else's commit, a branch switched under a running test. `git worktree add`
+   costs nothing and removes the class outright. Never work in a tree another agent is
+   editing, even briefly, even to "just check something".
+2. **A lease before any shared register.** Where the project has
+   `.claude/agent-sync.json`, the board, the decisions register, the open questions and
+   the roadmap are claimed before they are edited — that is what the file is for. Where
+   it does not exist, say so in the brief rather than discovering it at merge time.
+
+**What to do when you find the other agent mid-run:** stop, name what you found, and
+leave their work alone. Their uncommitted edits are not yours to stage, revert or
+stash. Your own committed work is safe; put a ref on it so a branch reset cannot lose
+it, and continue in a worktree of your own. Ending someone else's work to unblock
+yourself is the same asymmetry `residue.md` refuses, one layer up.
+
 ## 2. Workspace and ledger
 
 Conversation memory does not survive compaction. A controller that lost its place
@@ -392,6 +424,60 @@ When the review is clean — or every open finding is parked with a ruling at th
 Mark the todo complete, move on. Never start the next task while Critical/Important
 findings are neither fixed nor parked-with-ruling at the cap.
 
+## 4a. A screen is the frame, implemented
+
+When Figma is connected, a screen is not *informed by* the design file — it **is** the
+frame, in code. Values, structure and composition all come from the file, and the order
+of authority is fixed:
+
+| Question | Answer comes from |
+|---|---|
+| what the screen **does** — states, errors, empties | `super-ux`'s scenarios |
+| what it is **made of** — elements, hierarchy, layout, tokens | **the frame** |
+| how it **looks and moves** where the frame is silent | `sheleg-design` |
+
+`sheleg-design` runs **after** the file, never instead of it. It owns rhythm, motion and
+motion's degradation to stillness — the things a frame does not carry. Put it first and
+it invents what was already decided.
+
+**Five things this makes concrete.**
+
+1. **The composition is compared, not recalled.** A frame has a node tree
+   (`get_metadata`). Every node has a counterpart in the screen, and nothing is present
+   that the frame does not have. A missing element is incomplete; an invented one is a
+   divergence, not an improvement.
+2. **Layout is read, not eyeballed.** Auto-layout direction, gaps, padding and
+   constraints come from `get_design_context`. From a screenshot they are recovered
+   approximately, and approximate is indistinguishable from exact in a report.
+3. **A component with a Code Connect mapping is not rewritten.** If
+   `get_code_connect_map` names a code component for that node, the screen uses it.
+   Reimplementing it is a silent fork of the design system.
+4. **A token names its variable.** A raw hex or px where the file has a variable is a
+   token that has quietly split in two. `get_variable_defs` is the canon; a screenshot
+   is a way to *look*, never a way to *know*.
+5. **The frame is a contract at its own width.** It is one width and said nothing about
+   the others, so behaviour at other breakpoints — and states the frame does not draw,
+   like error, empty and loading — is a **decision that gets recorded**, not guessed.
+   Without this the rule is either unfollowable or vacuous.
+
+**When there is no frame for a screen — build it, name it, offer to draw it.**
+
+Figma is a recommendation like the graph and the wiki: its absence is named and never
+blocks. So the screen is built from `sheleg-design`'s style pack, the spec records
+*"no frame — source: sheleg-design"*, and the run **offers to draw the missing screens**
+into the file the brief already named. Concretely: which screens, where they land, what
+they are drawn from — so the operator sees the size before saying go.
+
+Drawing happens **only on an explicit go**, into the recorded destination, never into a
+new file. And whatever is drawn is **marked as coming from implementation** — its own
+page or a naming convention that says so. A designer opening the file must be able to
+tell what a person decided from what a run generated; an unmarked generated frame is the
+same false confidence as an unproven green.
+
+**Deviation is a line, not a silence.** Where the implementation must differ — a
+platform constraint, an accessibility floor, a breakpoint — write what and why.
+Otherwise *"built from the frame"* and *"built to look like it"* read identically.
+
 ## 5. Final whole-branch review
 
 After the last task: build a package over `MERGE_BASE`..`HEAD`

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

@@ -303,6 +303,12 @@ Three things make the line worth writing rather than a habit:
 - **It records how many classes were enumerated.** `8/8` and `7/8, unlooked:
   containers` are different facts, and a run without container tooling must print
   the second rather than a clean zero it did not earn.
+- **`SURFACED: 0` is checked against what the run filed.** A run that opened a board
+  row, a carry-over row, an open question or a retro entry has provably surfaced
+  something; reporting zero contradicts its own artefacts, and that disagreement is
+  computable from the `Source` column every board row carries. The residual belongs
+  in the same sentence: a run can surface something, file it nowhere, report zero,
+  and **nothing will notice** — this check kills the silent zero, not the blind spot.
 - **It is a disclosure, never a ratchet.** No floor, no direction, no target. A
   build stage legitimately holding a worktree and a database prints `2` and
   passes; a run that tears its database down to make the number tidy and brings

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

@@ -54,6 +54,13 @@ give the install line and stop; don't improvise a half-chain.
 5. **Run the linter** (`/ux-lint`, i.e. `python3 docs/ux/lint.py`). It must pass:
    no drift, no orphans, no broken traces, no stale Figma links.
 
+**The screen's source of truth is recorded here, not assumed.** Figma on → the frame
+supplies composition, layout and tokens, and `sheleg-design` supplies only what the
+frame is silent about. Figma off, or no frame for this screen → the style pack is the
+source and the spec says so, screen by screen. A screen whose values were taken from a
+screenshot is named as such: *sighted* and *read from the file* are different claims
+([`build.md`](build.md) → *A screen is the frame, implemented*).
+
 These skills are **idempotent** — extend the existing `docs/ux/` layers, never
 rebuild them. If the chain already exists and is validated (typically when the run
 entered from super-ux), verify it and embed it; build only what's missing.