feat(vibe): Test named mechanisms and decision provenance in vibe sessions

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the claude-plugins project will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Entries are listed newest-first; each plugin section is treated as released when merged to `main`.
 
+### vibe v1.0.48
+
+#### Added
+- The handoff guardrails reviewer checks each new poller, interval, background lane, socket, cross-process channel, route, table, cursor, or write into another tool's files: the existing mechanism that could do the job and why it was not used, what its cost scales with at 10x and 100x, and its per-device idle cost. Idle-scaled cost when an activity-scaled design meets the outcome, or a write into another tool's data with no cited human decision, is blocking; a ticket's Decisions section counts as that decision only when it traces to a human statement, and an untraced one is an `engineering decision` finding. It checks the session plan's Cost Scaling table against the diff.
+- An `Engineering decision: <question>; built: <...>; evidence: <...>` item on the live ticket's Engineering checklist, with placement rules in the ticket template and the ticket worker.
+- A closedloop-graph route for channels that already connect two surfaces, with an existing-channels `code_grep` in the change and backend workers' required calls when the work is periodic or cross-surface.
+- `test_vibe_mechanism_provenance_contract.py` pins these rules.
+- `tools/python/vibe_contract_text.py` holds the `flat`, `section`, `paragraph`, and `agent` helpers every vibe contract test now imports instead of keeping its own copy. `section` stops at the next heading of the same or a higher level and matches its heading at the start of a line, preferring an exact line; `paragraph` also splits list items; `agent` returns the raw text.
+
+#### Changed
+- The change worker treats a mechanism a ticket or PRD names as a proposal: when it is dominated, it builds the better option that meets the outcome and logs the swap as an `Engineering decision`, never as a question for the person. Plans that add periodic or cross-surface work carry a Cost Scaling table per cl-execute's `planning-and-gates.md`.
+- The requirements worker tags ticket text that names a mechanism `mechanism (proposal)` instead of an acceptance criterion.
+- A handoff finding that a mechanism, a one-way door, or an unratified or conflicting decision needs a human decision is never resolved, downgraded, or absorbed by the writer; it goes on the Engineering checklist.
+- `quality-loop.md` defines a settled decision as one that traces to a human statement (who, where, which question). An unratified or conflicting one goes through the product necessity gate or becomes an `Engineering decision`, and conflicts are never resolved by recency. Every "never re-ask a settled decision" points to this definition.
+- Frozen rows describe user-visible behavior, never mechanism.
+
 ### vibe v1.0.47
 
 #### Added

plugins/vibe/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vibe",
   "description": "Vibe sessions, handoff, seed refresh, and ClosedLoop ticket workflows",
-  "version": "1.0.47",
+  "version": "1.0.48",
   "dependencies": ["closedloop-core"],
   "author": {"name": "ClosedLoop", "email": "support@closedloop.ai"}
 }

plugins/vibe/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe",
-  "version": "1.0.47",
+  "version": "1.0.48",
   "description": "Vibe sessions, handoff, seed refresh, and ClosedLoop ticket workflows",
   "author": {"name": "ClosedLoop", "email": "support@closedloop.ai"},
   "homepage": "https://github.com/closedloop-ai/claude-plugins",

plugins/vibe/README.md

@@ -318,7 +318,8 @@ claude plugin eval . --eval-dir vibe/evals --tag visual-cues --scaffold --allow-
 
 Version `1.0.14` contains 10 skills and 16 agents. It has no standalone
 commands, hooks, root-level shell scripts, or production Python tools under
-`tools/python/`; that directory contains two skill-contract test modules.
+`tools/python/`; that directory contains the skill-contract test modules and
+`vibe_contract_text.py`, the text helpers they share.
 Runtime helpers and tests live alongside their owning skills, including vibe
 session and prototype records, local-plan publication guards, bundled persistent
 writer state, Claude launch/resume and shared main-sync publication helpers,

plugins/vibe/agents/vibe-change-worker.md

@@ -78,9 +78,13 @@ Load core `plan-structure` by name (`$plan-structure` in Codex or
 write the exact-template local plan under `.closedloop-ai/vibe-plans/`.
 Never upload it, paste it into the ticket, commit it or deploy it. Name scope,
 owners, dependencies and checks, including every NEW Storybook component the
-request needs (or none). The plan gets no review: build in the same turn
-right after it (`quality-loop.md`, "Lean build loop"). No technical plan goes
-to the person running the session for approval.
+request needs (or none). When the plan adds periodic or cross-surface work (a
+poller, interval, background lane, socket, subscription, feed or watcher), it
+carries a Cost Scaling table with the columns and rules in
+`../skills/cl-execute/references/planning-and-gates.md`, "Cost Scaling".
+The plan gets no review: build in the same turn right after it
+(`quality-loop.md`, "Lean build loop"). No technical plan goes to the person
+running the session for approval.
 
 Always load named core decision-table (`$decision-table` in Codex or
 `/closedloop-core:decision-table` in Claude Code) and create or extend the
@@ -102,10 +106,25 @@ is never an engineering escalation or a question for the person. Any other
 unverifiable binding remains BLOCKED internally.
 
 Research any product uncertainty through graph and live prior decisions first.
-Apply a settled ruling, never ask it again. Only an absolutely necessary
-unresolved product question returns `NEEDS_PERSON`, with sources checked and
-full context. Resolve technical ownership/backend/adapter questions yourself
-from source and read-only advice, never by shrinking requested scope.
+Apply a settled ruling, never ask it again; settled means traced to a human
+statement (`quality-loop.md`, "Communication and product questions"). Only an
+absolutely necessary unresolved product question returns `NEEDS_PERSON`, with
+sources checked and full context. Resolve technical ownership/backend/adapter
+questions yourself from source and read-only advice, never by shrinking
+requested scope.
+
+Only the outcome a ticket or PRD asks for binds the session. A mechanism it
+names (a poller, feed, lane, socket, route, table, cursor, or a write into
+another tool's data) is a proposal held to the same test as one you invent.
+If it is dominated (its cost scales with installs or idle time while an
+alternative scales with activity, or a supported interface exists for a write
+into another tool's data), build the better option that meets the outcome and
+log the swap in the change log as `Engineering decision: <question>; built:
+<what you built instead>; evidence: <files, records or finding>` for the live
+ticket's Engineering checklist (`ticket-template.md`, "Engineering
+decisions"). It is never `NEEDS_PERSON`. Raising and recording it is neither
+instruction inflation nor manufactured ambiguity: those rules protect settled
+rulings, and an unexamined mechanism is not one.
 
 When part of a request needs a change in a path you may never edit
 (`../skills/vibe/references/guardrails.md`, "What may change": the Never

plugins/vibe/agents/vibe-guardrails-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: vibe-guardrails-reviewer
-description: Reviews a vibe session's symphony-alpha diff (its redeploy commits and uncommitted work) against the vibe guardrails that need judgment rather than a path check (component reuse, design tokens, code placement, user-visible copy provenance, accessibility, fake data, repo conventions, shared-owner placement and its red flags, Storybook taxonomy placement and precedent placement, test files the session wrote or edited and whether each test repair left every assertion unchanged, checks made to pass by changing them). Read-only; returns findings with file and line evidence and the compliant alternative. Runs only at handoff, never during the build loop.
+description: Reviews a vibe session's symphony-alpha diff (its redeploy commits and uncommitted work) against the vibe guardrails that need judgment rather than a path check (component reuse, design tokens, code placement, user-visible copy provenance, accessibility, fake data, repo conventions, shared-owner placement and its red flags, Storybook taxonomy placement and precedent placement, test files the session wrote or edited and whether each test repair left every assertion unchanged, checks made to pass by changing them, and each new mechanism's reuse and cost scaling). Read-only; returns findings with file and line evidence and the compliant alternative. Runs only at handoff, never during the build loop.
 model: sonnet
 tools: Read, Grep, Glob, Bash, Skill
 ---
@@ -135,6 +135,25 @@ closedloop-graph is required, per `../skills/vibe/references/closedloop-graph.md
     This is not a mechanical check: stories for one shared capability can
     live both beside the shared component and in page sections, so only the
     reported precedents tell whether a page-scoped story mirrors them.
+12. Mechanisms: for each new poller, interval, background lane, socket,
+    cross-process channel, route, table or cursor in the diff, and each write
+    into files another tool owns, name the existing mechanism that does or
+    could do the job (`closedloop-graph.md`, the row for channels that
+    already connect two surfaces) and why it was not used. State what its
+    steady-state cost scales with (installs or idle clients, connected
+    clients, active sessions, events) at 10x and 100x, and its per-device idle
+    cost (timer wakeups, network and disk while nothing is active, on
+    battery). Never argue from current fleet size. Cost that scales with idle
+    clients when an activity-scaled design meets the outcome is blocking, and
+    so is a write into another tool's data with no cited human decision. A
+    decision recorded in a ticket or plan counts only when it traces to a
+    human statement (who, where, which question; `quality-loop.md`,
+    "Communication and product questions"): a Decisions section alone is a
+    record, not a ruling, and an untraced one is an `engineering decision`
+    finding. A mechanism the ticket named is held to the same test
+    (`vibe-change-worker.md`, "Plan before code"). When the session's local
+    plan has a Cost Scaling table, check it against the diff; a row that does
+    not match what was built is a finding.
 
 For publication, verify the SAME source actor's `main-sync-inputs` evidence
 before capture and after the committed merge. Canonical private diagnostics
@@ -148,6 +167,10 @@ and the Root validation witness confer no test-authoring or E2E authority.
 Return a list. Each item: `severity` (blocking or advisory), `file:line`,
 the problem in one sentence, the evidence (quote the line), and the compliant
 fix. Blocking means engineering would have to rewrite it or a repo gate will
-fail. Return "No findings" when there are none. Do not pad the list. End
+fail. Mark a finding that needs a human decision (a mechanism choice, a
+one-way door, or an unratified or conflicting decision) `engineering
+decision`; handoff records it for engineering
+(`../skills/handoff/SKILL.md`, section 6), never for the person. Return "No
+findings" when there are none. Do not pad the list. End
 with the Graph block. Your findings go to the orchestrator, which routes the
 fixes to a worker; the person is not involved.

plugins/vibe/agents/vibe-requirements-worker.md

@@ -26,7 +26,8 @@ do not fabricate a table or claim it existed before code that already landed.
 Read `../skills/vibe/references/quality-loop.md`. Keep the brief internal;
 research product questions through graph and live decisions first, and return
 only absolutely necessary unresolved questions. Never ask a technical question,
-re-ask settled scope, or produce an upfront summary for the person.
+re-ask settled scope (`quality-loop.md`, "Communication and product
+questions"), or produce an upfront summary for the person.
 
 ## Do
 
@@ -36,7 +37,13 @@ re-ask settled scope, or produce an upfront summary for the person.
    of the ticket AND of its PRD, each quoted exactly with its source slug,
    any design or prototype links, and any decisions in comments. These seed
    the session's acceptance criteria list (`quality-loop.md`, "Acceptance
-   criteria before ready").
+   criteria before ready"). Tag ticket text that names an implementation
+   mechanism (a poller, feed, lane, socket, route, table, cursor, or a write
+   into another tool's data) `mechanism (proposal)`, never an acceptance
+   criterion, so the session checks the outcome and not the named mechanism. A
+   recorded decision is settled only when it traces to a human statement
+   (`quality-loop.md`, "Communication and product questions"); report each
+   with its source, and an unratified or conflicting one as not settled.
 2. Description: `query_collisions` and `search_nodes` with the description,
    and `fts_search` on its key terms, to find an existing ticket or PRD that
    already covers it.
@@ -92,8 +99,9 @@ as our copy. End with the Graph block.
 `DONE` with: a two or three sentence summary in plain words, which the
 orchestrator keeps internal and which never names a screen to start
 on; the requirements as a short list quoted from their source (never
-invented); every acceptance criterion of the ticket and its PRD, quoted
-exactly with its source slug, or "none stated"; the route and FEATURE_MAP id where the relevant code lives, for
+invented), each named mechanism tagged `mechanism (proposal)`; every
+acceptance criterion of the ticket and its PRD, quoted exactly with its source
+slug, or "none stated"; the route and FEATURE_MAP id where the relevant code lives, for
 change workers (not shown to the person); overlapping or in-flight tickets
 (slug and title); and whether this is a change to an existing screen or a
 net-new screen. Or

plugins/vibe/agents/vibe-ticket-worker.md

@@ -217,6 +217,9 @@ historical inspections accurately. Preserve the existing grading block.
    entry in the change log once, as an unchecked item at the end of the
    Engineering checklist in its logged shape
    (`../skills/vibe/references/ticket-template.md`, "Engineering needed").
+   Place each `Engineering decision` entry in the change log once, as an
+   unchecked item at the end of the Engineering checklist in its logged shape
+   (`../skills/vibe/references/ticket-template.md`, "Engineering decisions").
    Place each file in the inventory's `compileOnlyV1Repairs` once, as an
    unchecked item at the end of the Engineering checklist in the template's
    shape (`../skills/vibe/references/ticket-template.md`, "Compile-only v1.0

plugins/vibe/skills/handoff/SKILL.md

@@ -320,7 +320,8 @@ helper edits source. A `forbidden` or outside-allowed path the request
 genuinely needed is removed and logged as
 `Engineering needed (forbidden path)` (`../vibe/references/guardrails.md`,
 "What may change"), and the ticket worker puts it on the Engineering
-checklist. A removal never silently undoes a visible change the person
+checklist. A finding marked `engineering decision` follows step 6's rule
+for decisions. A removal never silently undoes a visible change the person
 already saw (operator ruling, 2026-10-15: an approved bold heading needed a
 font generator outside the allowed paths and handoff reverted it without a
 word). When it does, tell the person in one plain line which part will
@@ -426,6 +427,15 @@ which verifies and corrects them; recheck its current result and repeat
 validation. A coverage gap goes on the missing tests list; nobody writes a
 test here.
 
+A finding from any handoff reviewer, step 3's guardrails check included,
+that a mechanism, a one-way door, or an unratified or conflicting decision
+needs a human decision is never the writer's to resolve, downgrade or
+absorb, including after verification. The SAME writer logs it in the change
+log as `Engineering decision: <question>; built: <what the session built>;
+evidence: <files, records or finding>`, and the ticket worker puts it on the
+live ticket's Engineering checklist (`../vibe/references/ticket-template.md`,
+"Engineering decisions"), never to the person.
+
 ### Browser E2E and the repository's QA passes
 
 These run here and never in the build loop (operator ruling,

plugins/vibe/skills/vibe/SKILL.md

@@ -59,7 +59,9 @@ new Storybook components and the endings line in a new session's first
 reply), are the only other messages, and none of them waits.
 Research product questions through closedloop-graph and live evidence first;
 interrupt only for an absolutely necessary unresolved product question, one at
-a time with full context. Never re-ask a settled decision.
+a time with full context. Never re-ask a settled decision; a decision is
+settled only when it traces to a human statement
+(`references/quality-loop.md`, "Communication and product questions").
 
 This skill only works in a `closedloop-ai/symphony-alpha` checkout.