baldart 4.92.0 → 4.93.0

package/framework/.claude/skills/prd/references/audit-teammate-prompt.md

@@ -0,0 +1,144 @@
+# Audit Teammate Contract (Step 6.6) — AGENT-FACING SPEC
+
+> **Who reads this file: the audit TEAMMATES** spawned at audit-phase Step 6.6c, in
+> their own context windows. The `/prd` orchestrator passes this file **BY PATH** in
+> the spawn prompt and MUST NOT load it into its own context — in a teammate this
+> spec costs one cheap Read; in the orchestrator it would ride every subsequent
+> full-window API call for the rest of the run (context economy).
+
+## Identity
+
+You are a SKEPTICAL auditor for a pre-development audit team ("check-audit").
+Your default stance is that the card is NOT ready for implementation.
+Do not rationalize away issues. Do not give benefit of the doubt.
+If something COULD be a problem, flag it. The challenge pass (later) will filter false positives.
+Your job is RECALL, not precision — catch everything, filter later.
+
+## Your Workflow
+
+1. Call `TaskList` to see your assigned tasks.
+2. For each task (in ID order):
+   a. Call `TaskGet` to read the full task description (card YAML + adjacent cards + file paths).
+   a2. **Claim the task**: if `claimed_by` is already set to a name other than yours, SKIP this task (another worker owns it). Otherwise set `claimed_by: <your name>` via `TaskUpdate`, then re-read via `TaskGet` to confirm your claim held; if a different name won the race, SKIP.
+   b. Mark task as `in_progress` via `TaskUpdate`.
+   c. Read any source files or PRDs referenced in the task (use Read tool).
+   d. Perform your audit (see § "Audit Instructions per role" — apply YOUR role's section).
+   e. Run the Challenge Pass on your findings (see below).
+   f. Run Severity Calibration on surviving findings (see below).
+   g. **Write findings into the task description** via `TaskUpdate` — append a `## FINDINGS` section.
+   h. Send a brief notification to orchestrator via `SendMessage` (task ID + one-line summary only).
+   i. Mark task as `completed` via `TaskUpdate`.
+3. After all tasks: send "all tasks complete" to orchestrator.
+
+**IMPORTANT**: Always write findings to task description (step g) before notification (step h). Task description is durable; message is just a ping.
+
+> **Codex runtime**: when the run is file-backed (no task spine), the same workflow
+> applies over the task files at `…/sessions/<slug>-audit/tasks/` — claim by writing
+> `claimed_by`, persist findings to `audit/findings/<agent>-<CARD-ID>.json`. Binding:
+> `framework/agents/runtime-portability-protocol.md` § state-spine.
+
+## Audit Instructions per role
+
+Apply the ONE section matching the role declared in your spawn prompt.
+
+### plan-auditor (card grounding)
+
+This is the Claude-side, codebase-grounded counterpart to the cross-model Codex plan audit (6.6d) — it brings what Codex lacks: project memory (`.claude/agent-memory/plan-auditor/MEMORY.md`) and the card-native `[Target: <field>]` tagging this audit consumes. Apply the **full BACKLOG CARD ATTACK SURFACE** (INVEST, requirements-smell detection, persistence-specific checks per `stack.database`, card-structure checks) against each card's `.yml`, reading the existing files in `files_likely_touched` to ground claims about conflicts with existing patterns, missing reuse opportunities, and convention alignment (per `identity.design_philosophy`, project lint/type-check rules, `identity.language`). Check `## Adjacent Cards` for parallel file modifications and missing `depends_on` edges.
+
+> **Mode (team-aware — read first)**: you are running inside the coordinating `check-audit` team, so you MUST behave as in QUICK mode for *spawning* while keeping FULL card-attack-surface *coverage*:
+> - **Do NOT spawn `codebase-architect`** for grounding — `/prd` already primed codebase context at kickoff (context-primer) and you read `files_likely_touched` directly. A re-spawn here is wasteful and forbidden.
+> - **Do NOT auto-spawn specialists** (`security-reviewer` / `api-perf-cost-auditor` / `ui-expert`) — they run as first-class teammates in this same team whenever their signal fires (6.6c). Consume their findings at merge time; never double-spawn.
+> - **Output-format override** (symmetric with the security-reviewer / api-perf-cost-auditor overrides below): produce findings in the teammate contract format (`### [CARD-ID] — Plan Audit Findings` with `[Target: <field>]` tags written to a `## FINDINGS` section via `TaskUpdate`) — NOT plan-auditor's native 10-section OUTPUT FORMAT (Hardened Plan, Pre-Mortem, Risk Register, YAML schema dump). The `[Target: <field>]` tag system is native to plan-auditor, so the only change is the wrapping heading + `## FINDINGS` section.
+> - Never suppress a `git_strategy: TBD`, missing-auth, `claimed_path_collision`, `adr_required_missing`, or prompt-injection finding (plan-auditor's never-suppress list still binds here).
+
+### doc-reviewer
+
+Check documentation links, PRD references are valid and aligned, planned changes requiring doc updates not mentioned. Verify `files_likely_touched` includes doc files. Check `areas` completeness. Flag `git_strategy: TBD`. Include Obsidian trigger assessment (section H) in findings — evaluate whether the planned docs will require KB sync. If `.claude/skills/doc-reviewer-support/references/obsidian-integration.md` is present, use its criteria; otherwise apply a minimal check: does the card introduce new or significantly modified public documentation that should appear in the knowledge base? Proceed with a notice if the file is absent.
+
+### api-perf-cost-auditor (only when `perf_review_needed: true`)
+
+Apply the 5-gate protocol from `api-perf-gate.md` (sibling file in this same `references/` dir — read it). Read referenced source files. Universal checks: unbounded reads, N+1 queries, fan-out writes, missing pagination, offset pagination, listener vs polling costs, payload size limits per `stack.deployment`, transaction hotspots. Stack-specific addenda apply per `stack.database` + `stack.framework` (same file). **Output format override**: produce findings in the teammate contract format (`### [CARD-ID] — Performance Findings` with `[Target: <field>]` tags and a `## FINDINGS` section written via `TaskUpdate`) rather than the native `PERF AUDIT DONE` verdict line + YAML schema, so findings merge correctly at Step 6.7 (symmetric with the `security-reviewer` override below).
+
+### security-reviewer (only when `security_review_needed: true`)
+
+Apply the full security-reviewer methodology. Focus on: auth gaps, input validation, multi-tenant isolation, persistence-layer access rules alignment (Firestore rules / Supabase RLS / Mongo validator / DynamoDB IAM — per `stack.database`), sensitive data exposure, webhook validation, rate limiting, IDOR risks. **Output format override**: produce findings in the teammate contract format (`### [CARD-ID] — Security Findings` with `[Target: <field>]` tags and `## FINDINGS` section written via `TaskUpdate`) rather than the native `# Security Review Summary` format, so findings merge correctly at Step 6.7.
+
+## Output Format (mandatory evidence quotes)
+
+For each card, return findings as:
+
+### [CARD-ID] — {Agent Role} Findings
+
+- [ ] **Finding title** — Description of the issue, risk, or gap. (Severity: HIGH/MEDIUM/LOW) [Target: <field>]
+  > **Evidence:** "<exact quote from the card YAML, PRD, or source file>"
+  > **Source:** `<file path or field name>`
+
+**MANDATORY**: Every finding MUST include an evidence quote — a direct excerpt that grounds it. Findings without quotable evidence MUST be discarded. State: "Considered but discarded — no quotable evidence found."
+
+If no findings: "No issues found for [CARD-ID]."
+
+### `[Target: <field>]` tag reference (mandatory on every finding)
+
+| Target tag | When to use |
+|---|---|
+| `[Target: requirements]` | Missing or wrong requirement text |
+| `[Target: acceptance_criteria]` | Missing AC, vague AC needing rewrite |
+| `[Target: definition_of_done]` | Missing DoD checkbox |
+| `[Target: files_likely_touched]` | Missing file path |
+| `[Target: depends_on]` | Missing dependency card ID |
+| `[Target: areas]` | Missing area entry (api, docs, data, ui) |
+| `[Target: git_strategy]` | `git_strategy: TBD` or wrong value |
+| `[Target: unknowns]` | Unresolved unknown to surface |
+| `[Target: existing_patterns]` | Missing or stale pattern reference |
+| `[Target: validation_commands]` | Missing verification command |
+| `[Target: anti_patterns]` | Missing DO NOT constraint |
+| `[Target: scope_boundaries]` | Missing scope boundary item |
+| `[Target: input_output_examples]` | Missing or incorrect I/O example |
+| `[Target: error_handling]` | Missing failure mode spec |
+| `[Target: reuse_analysis]` | Missing reuse opportunity or wrong path |
+| `[Target: notes]` | LOW severity only — informational |
+
+## Challenge Pass (mandatory before reporting)
+
+After generating initial findings, challenge EACH one:
+
+"What is the strongest argument that this is a false positive?"
+
+Consider:
+- Is this already handled elsewhere in the codebase?
+- Is this a convention in this project I'm unfamiliar with?
+- Is the card intentionally deferring this to a later card?
+- Am I applying a generic best practice that doesn't fit this context?
+
+**Suppress the finding if the FP argument is convincing.** Record suppressed findings:
+
+<details>
+<summary>Suppressed findings (N items — challenge pass)</summary>
+- **Finding title** — FP argument: <why suppressed>
+</details>
+
+## Severity Calibration (after challenge pass)
+
+Severity is **ABSOLUTE, per finding, anchored to its evidenced consequence** — never a relative ranking, never a quota. (Positional bands like "top 20% → HIGH" manufacture mandatory findings on clean plans and demote real defects on large batches; both are calibration failures.)
+
+For each surviving finding ask: *"what happens if the card is implemented exactly as written?"*
+
+- **HIGH** — implementing the card as written produces a defect: data loss, security bypass, breaking change, wrong behavior against a stated AC, an unimplementable AC (e.g. its seam file is outside the card's ownership), or a missing `depends_on` that creates a cross-card conflict. A HIGH MUST cite its evidence (card field/line + the code path that proves it); no evidence citation → cap at MEDIUM.
+- **MEDIUM** — the card is implementable but a gap will plausibly cost a review cycle: missing doc/file in `files_likely_touched`, vague-but-inferable AC, missing validation command.
+- **LOW** — informational, no behavioral consequence (naming, style, nice-to-have).
+
+Zero HIGH — or zero findings at all — on a well-formed card is a legitimate, reportable outcome. Do NOT stretch severities to fill bands.
+
+### Severity Calibration Examples
+
+**HIGH** (must fix before implementation):
+- "acceptance_criteria says 'user can see <list>' but doesn't specify pagination → unbounded persistence-layer read"
+  > Evidence: "AC-2: <persona from identity.audience_segments[]> views <entity>" — no limit/pagination mentioned
+
+**MEDIUM** (should fix, skip if ambiguous):
+- "files_likely_touched missing the API route doc update"
+  > Evidence: files_likely_touched lists "src/app/api/v1/<domain>/route.ts" but not "${paths.references_dir}/api/<domain>.md"
+
+**LOW** (note only):
+- "Card title could be more descriptive"
+  > Evidence: title is "Booking API" — functional but generic

package/framework/.claude/skills/prd/references/discovery-phase.md

@@ -589,17 +589,34 @@ user's own folder outside the worktree — never modify or clean it; only read.
 
 Then continue to Step 1.6.5 with the selected subset.
 
-### 1.6.5 — Mockup analysis (MANDATORY before Discovery)
-
-Analyze ALL provided mockups (visual analysis for chat images, Read for copied files
-that are textual like HTML/SVG). Populate `## UI Design` in the state file using the
-**Mockup analysis schema** (see appendix at the end of this file).
-
-When `features.has_design_system: true`, BLOCKING reads of `${paths.design_system}/INDEX.md`
-and `${paths.design_system}/tokens-reference.md` apply BEFORE running the alignment
-check — same protocol as Step 3 (UI Design). Flag every hardcoded value (hex / shadow /
-radius / spacing) that conflicts with a known token as a violation in
-`mockup_analysis.design_system_alignment.violations[]`.
+### 1.6.5 — Mockup analysis (MANDATORY before Discovery — DELEGATED, mockup bytes never in the orchestrator)
+
+**HARD RULE — the orchestrator MUST NOT Read the mockup files** (images OR HTML/SVG
+bundles). A decoded mockup read in the main context rides EVERY subsequent
+full-window API call for the rest of the run (measured on a real session: ~208KB
+dragged through the cache for ~300 events). The only exception is a mockup pasted
+directly in chat as an image — that is already in context; analyze it inline.
+
+For all on-disk mockups, **spawn ONE `ui-expert` subagent in read-only analysis
+mode** with this brief:
+- the mockup file paths (`mockups.canonical_paths[]`) — the agent Reads them in ITS
+  context (it is multimodal: images render, HTML is read as text);
+- the schema to fill: instruct it to open THIS file
+  (`references/discovery-phase.md`) and read ONLY the section
+  `## Appendix — Mockup analysis schema` (Grep the heading, Read from that offset);
+- when `features.has_design_system: true`: the paths of
+  `${paths.design_system}/INDEX.md` and `${paths.design_system}/tokens-reference.md`
+  (BLOCKING reads for the agent — same protocol as Step 3), with the instruction to
+  flag every hardcoded value (hex / shadow / radius / spacing) that conflicts with a
+  known token as a violation in `mockup_analysis.design_system_alignment.violations[]`;
+- **ROLE BOUNDARY**: analysis only — no code, no file writes, no Task spawns. Its
+  final message is the filled `mockup_analysis` YAML and NOTHING else (COMPACT
+  return contract).
+
+The orchestrator persists the returned YAML into `## UI Design` in the state file
+verbatim. If the agent's YAML is malformed, re-spawn once with the error; on a
+second failure, fall back to inline analysis (and say so — the fallback is visible,
+never silent).
 
 ### 1.6.6 — Output and handoff to Discovery
 

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -6,15 +6,26 @@
 
 Mark task 5 as `in_progress`.
 
-0. **Agent Specialization Audit (runs FIRST, blocks if any failure)** — for each generated child card (epics are skipped):
+0. **Agent Specialization Audit (runs FIRST, blocks if any failure)** — two layers:
 
-   a. **`owner_agent` enum check (BLOCKING)** — read the `owner_agent` field. It MUST equal one of:
-      ```
-      coder | ui-expert | plan | visual-designer | motion-expert
-      ```
-      Empty string, missing field, `claude`, or any other value = **BLOCKER**.
-      Message to the user: `"Card <ID> has owner_agent: '<value>' — must be one of {coder, ui-expert, plan, visual-designer, motion-expert}. Fix the card YAML before commit."`
-      Halt the audit. No subsequent checks run on a card that fails this gate.
+   **0-i. Deterministic gate — EXECUTED, never recited (BLOCKING).** Run the framework validator in `/prd` mode on EVERY generated card (epics included — it is profile-aware):
+
+   ```bash
+   node .framework/framework/scripts/validate-card-baseline.js --prd \
+     "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
+   ```
+   (resolve the script path for your install; only if it is genuinely unreachable, fall back to reciting the checks below — and say so explicitly in the audit log).
+
+   Exit 1 = **BLOCKER**: print the per-field errors verbatim, fix the card YAML, re-run until exit 0. No subsequent checks run on a card while it fails this gate. The script covers deterministically:
+   - **`owner_agent` enum** — must be one of `{coder, ui-expert, plan, visual-designer, motion-expert}` (empty/missing/`claude` = blocker);
+   - **`review_profile` enum + epic `skip`** — `skip|light|balanced|deep`; missing/empty = blocker (the card-writer must compute it via `prd-card-writer.md § Rule C`); epics MUST be `skip`;
+   - **conditional `requirements` presence (PO1)** — a child/standalone card with non-empty `acceptance_criteria` + `scope` MUST carry `requirements` (a fresh `/prd` card without them shifts a measured ~3–4M-token back-fill into `/new`'s orchestrator — see `card-schema.md` § "Authoring completeness invariants");
+   - **unresolved `[NEEDS CLARIFICATION: …]` markers** — a card carrying a planning ambiguity is NOT implementable. Resolve each marker (with the user via `AskUserQuestion` when it needs a human answer, or from Discovery/PRD material when it does not), edit the card, re-run;
+   - the universal field-state matrix + remaining enums (`card-schema.md`).
+
+   **Why executed and not recited:** the prose version of this gate has already failed silently on a real run (a whole card family shipped with zero audit trail). A recited check degrades under context pressure; an executed one cannot.
+
+   **0-ii. Semantic checks (the model reads the cards — not scriptable):**
 
    b. **UI-only scope heuristic (WARN — soft gate, not blocking)** — for each card with `owner_agent: ui-expert`:
       - Concatenate `scope.summary`, `requirements[]`, and `acceptance_criteria[]` into one lowercase string.
@@ -24,23 +35,7 @@ Mark task 5 as `in_progress`.
       - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
       - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected. **[SEMANTIC — not purely deterministic]** Determining whether a marker substring is (a) inside a YAML quoted string and (b) that string contains one of the escape phrases requires contextual interpretation across multiple YAML quoting styles (single-quote, double-quote, block scalar). FP posture: when in doubt, log the WARN and let the human decide — do not suppress a WARN based on uncertain quoting analysis.
 
-   c. **`review_profile` enum check (BLOCKING)** — read the `review_profile` field on each child card. It MUST equal one of:
-      ```
-      skip | light | balanced | deep
-      ```
-      - **Missing or empty** = **BLOCKER** — the card-writer must compute it via `prd-card-writer.md § Rule C` (the SSOT mapping table). Message: `"Card <ID> has no review_profile — compute it from Rule C (skip|light|balanced|deep) before commit."`
-      - **Out-of-enum value** = **BLOCKER**. Message: `"Card <ID> has review_profile: '<value>' — must be one of {skip, light, balanced, deep}."`
-      - **Consistency WARN (soft)**: a `feature`/`enhancement` card with `review_profile: light` may violate Rule C. Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — verify against Rule C in prd-card-writer.md."` **Do NOT auto-bump the field** — `review_profile` is computed by `prd-card-writer` (Rule C); see `prd-card-writer.md` for the criteria. This is a soft gate: log the warning and surface it for human review.
-      - **Epics**: `review_profile` MUST be `skip` (trackers have no code work). Any other value = WARN, normalize to `skip`.
-
-   d. **`requirements` presence (BLOCKING — PO1)** — for each CHILD/STANDALONE card whose
-      `acceptance_criteria` AND `scope` are both non-empty, `requirements` MUST be present and
-      non-empty. A freshly authored `/prd` card with derivable material but no `requirements` is an
-      authoring miss that shifts a measured ~3–4M-token back-fill into `/new`'s orchestrator context
-      (see `card-schema.md` § "Authoring completeness invariants"). `/prd` fixes it now for free.
-      Message: `"Card <ID> has acceptance_criteria + scope but no requirements — emit requirements
-      (faithful restatement of AC + scope) before commit."` (The `/new` conditional back-fill remains
-      only as the safety net for legacy / externally-authored cards.)
+   c. **Rule C consistency (WARN — soft gate)**: a `feature`/`enhancement` card with `review_profile: light` may violate Rule C. Log `"[REVIEW-PROFILE-WARN] Card <ID> is feature/enhancement but review_profile: light — verify against Rule C in prd-card-writer.md."` **Do NOT auto-bump the field** — `review_profile` is computed by `prd-card-writer` (Rule C); see `prd-card-writer.md` for the criteria. This is a soft gate: log the warning and surface it for human review. (The enum/presence/epic-`skip` checks are handled deterministically by 0-i.)
 
    e. **files_likely_touched coverage (BLOCKING — P1/P2 closure)** — two sub-checks:
       - **⊆ coverage (P2):** every file path named in a card's `requirements` /
@@ -58,9 +53,10 @@ Mark task 5 as `in_progress`.
         no card — assign it to a card's files_likely_touched."`
       Both are SEMANTIC (path extraction from prose / ISA needs interpretation) — bias toward flagging.
 
-   **Gate**: every card has `owner_agent` AND `review_profile` in their enums, `requirements` present when
-   derivable (d), and full files_likely_touched coverage (e). WARN entries from checks (b)/(c) are noted in
-   the audit log; user may accept them after review. The (d)/(e) BLOCKERs must be fixed before commit.
+   **Gate**: the 0-i validator exits 0 on every card (enums, conditional `requirements`, zero
+   `[NEEDS CLARIFICATION]` markers) AND full files_likely_touched coverage (e). WARN entries from
+   checks (b)/(c) are noted in the audit log; user may accept them after review. The 0-i and (e)
+   BLOCKERs must be fixed before commit.
 
 1. **Field Name Audit (runs after item 0 — only when item 0 passes for a given card; skipped for cards blocked in item 0)** — for each generated card:
 
@@ -132,37 +128,37 @@ created by Step 1 (HARD RULE 17). `$WORKTREE_PATH` is set in the state file.
    (`paths.metrics` default: `docs/metrics`), which must be part of the same commit.
    Non-blocking: if it fails, log "Metrics Log: SKIPPED" in the progress bar and continue.
 
-5b. **Holistic-audit provenance backstop (BLOCKING on the STAMP, never on the PRD).**
-   The per-card stamp write in `audit-phase.md` Step 6.9.4 is model-driven and is the
-   single most-omitted step under context pressure. When it is skipped, every card
-   ships WITHOUT `metadata.holistic_audit` — and `/new` (`implement.md` Phase 1 step 4,
-   P1) + `new2` then spawn the plan-auditor on **every** card even when the batch is
-   implemented immediately after this audit (nothing changed). Step 6 is complete (its
-   gate passed), so the audit genuinely ran: this is the authoritative, deterministic
-   point to guarantee the stamp lands. **Do NOT re-derive the semantics** — reuse the
-   run-level values and the YAML block DEFINED in `audit-phase.md` § "Holistic-audit
-   provenance stamp".
-   - Recompute the three run-level values ONCE (same snippet as audit-phase.md), inside
-     `$WORKTREE_PATH`:
-     ```bash
-     HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-     HOLISTIC_AUDITED_COMMIT="$(git -C "$WORKTREE_PATH" merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git -C "$WORKTREE_PATH" rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
-     # audited_set = the sorted Step-5 child card IDs (the joint cross-card scope).
-     ```
-   - For EACH **non-EPIC** card from Step 5: if it lacks `metadata.holistic_audit` with a
-     non-empty `audited_commit`, WRITE the block (additive — never overwrite other
-     `metadata` keys). A card that already carries it (from Step 6.9.4) is untouched —
-     **idempotent**. EPIC-parent cards are excluded (they carry `planning_session` only —
-     `card-schema.md`).
-   - Re-read one backfilled card to verify the block landed. Log
-     `holistic_audit provenance: N/N cards stamped (M backfilled here)`.
+5b. **Holistic-audit provenance backstop (BLOCKING on the STAMP, never on the PRD) —
+   EXECUTED via script.** The per-card stamp write in `audit-phase.md` Step 6.9.4 is
+   model-driven and is the single most-omitted step under context pressure; when it is
+   skipped, every card ships WITHOUT `metadata.holistic_audit` — and `/new`
+   (`implement.md` Phase 1 step 4, P1) + `new2` then spawn the plan-auditor on **every**
+   card even when the batch is implemented immediately after this audit. Step 6 is
+   complete (its gate passed), so the audit genuinely ran: guarantee the stamp lands by
+   RUNNING the deterministic stamper (semantics defined in `audit-phase.md`
+   § "Holistic-audit provenance stamp" — the script only mechanizes the write):
+   ```bash
+   HOLISTIC_AUDITED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+   HOLISTIC_AUDITED_COMMIT="$(git -C "$WORKTREE_PATH" merge-base HEAD "${git.trunk_branch}" 2>/dev/null || git -C "$WORKTREE_PATH" rev-parse "${git.trunk_branch}" 2>/dev/null || echo "")"
+   # --set = the sorted Step-5 child card IDs (the joint cross-card scope), comma-separated.
+   node .framework/framework/scripts/stamp-holistic-audit.js \
+     --at "$HOLISTIC_AUDITED_AT" --commit "$HOLISTIC_AUDITED_COMMIT" \
+     --set "<ID1,ID2,...>" "$WORKTREE_PATH/${paths.backlog_dir}"/FEAT-XXXX-*.yml
+   ```
+   The script is **idempotent** (a card already stamped by Step 6.9.4 is untouched),
+   **additive** (never overwrites other `metadata` keys), skips EPIC cards (they carry
+   `planning_session` only — `card-schema.md`), and verifies its own writes. Log its
+   summary line (`holistic_audit provenance: N/N non-epic cards stamped (M written
+   here, …)`) in the audit log. Only if the script is genuinely unreachable in this
+   install, fall back to the manual per-card write per `audit-phase.md` § "Holistic-audit
+   provenance stamp" — and say so explicitly.
    **Fail-safe (unchanged contract):** the stamp is an OPTIMIZATION hint, never a
    *correctness* gate — if `HOLISTIC_AUDITED_COMMIT` resolves to `""` (git genuinely
-   unavailable), write it explicitly as `""` so `/new` treats it as drift and RUNS the
-   plan-auditor. **NEVER block or abort the PRD over the stamp**; the only thing this gate
-   blocks is shipping cards with the stamp SILENTLY absent. Runtime-neutral (bash + YAML
-   edits) → identical on Claude and Codex. The backfilled YAMLs are staged by item 6's
-   existing `FEAT-XXXX-*.yml` glob.
+   unavailable), the script writes it explicitly as `""` so `/new` treats it as drift and
+   RUNS the plan-auditor. **NEVER block or abort the PRD over the stamp**; the only thing
+   this gate blocks is shipping cards with the stamp SILENTLY absent. Runtime-neutral
+   (node + YAML edits) → identical on Claude and Codex. The backfilled YAMLs are staged
+   by item 6's existing `FEAT-XXXX-*.yml` glob.
 
 6. Stage ONLY PRD session artefacts by explicit file name (NEVER `git add .`
    or `git add -A`):

package/framework/.claude/skills/ui-implement/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.1 — 2026-07-02
+
+- Return Contract (SKILL.md): documentati i campi `bindings` + `lane_coverage`/`lanes`
+  del JSON programmatico (lo schema resta SSOT in references/integration.md).
+
 ## 1.1.0 — 2026-07-02
 
 - **Binding-compliance gate (Step 5b)**: nuovo script deterministico

package/framework/.claude/skills/ui-implement/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-implement
 effort: medium
-version: 1.1.0
+version: 1.1.1
 description: >
   Implement an ALREADY-APPROVED mockup into the codebase end-to-end and
   self-verify its fidelity. Takes a mockup in any channel — a Claude Design
@@ -233,7 +233,12 @@ older install), `/new` falls back to an inline **coarse** build brief + a direct
 
 **Mode:** COMPACT (default). Your final message is bounded — verdict
 (`passed | blocked | overridden | skipped | error`) + the chosen build workflow +
-key findings as `path:line` + `Report: <path>`. Persist the long form (the
+key findings as `path:line` + `Report: <path>`. The programmatic JSON ALSO carries
+(since 1.1.1): `bindings` (the Step 5b `check-bindings.mjs` one-line result, when
+the card has `component_bindings`) and `lane_coverage` + `lanes` (forwarded from
+the internal `/e2e-review` report) — full schema:
+[references/integration.md](references/integration.md) § Return contract (the
+SSOT; do not restate it here). Persist the long form (the
 `/e2e-review` report + tracker), return the short form. FULL narrative only when the
 user invoked you directly. Schema + persist-then-summarize rule:
 `framework/agents/return-contract-protocol.md`.

package/framework/.claude/workflows/new2.js

@@ -283,7 +283,7 @@ try {
   preflight = await agentSafe(
     `You are the deterministic PRE-FLIGHT for an autonomous /new batch (variant new2). Follow ${REF}/setup.md (Phase 0 + Pre-flight) and ${REF}/implement.md (Phase 1 depends-on gate) for the SEMANTICS, but replace EVERY AskUserQuestion with the deterministic policy below. You run all git/bash yourself (the workflow cannot).\n\n` +
       `${projectBrief}\n\nCards in batch (Read each YAML):\n${cardPaths.join('\n')}\nCard IDs: ${cardIds.join(' ')}\n\n` +
-      `Create/maintain the recovery tracker at "$(git -C ${MAIN} rev-parse --git-common-dir)/baldart/run/batch-tracker-${firstCard}.md" (mkdir -p its dir first; per setup.md § Context Tracking — DURABLE location, v4.91.0: /tmp is volatile and a paused/overnight run lost it — B4).\n\n` +
+      `Create/maintain the recovery tracker at "$(git -C "${MAIN}" rev-parse --git-common-dir)/baldart/run/batch-tracker-${firstCard}.md" (mkdir -p its dir first; per setup.md § Context Tracking — DURABLE location, v4.91.0: /tmp is volatile and a paused/overnight run lost it — B4).\n\n` +
       `ROLE BOUNDARY (specialization integrity): you are the OPS/GIT agent. You NEVER edit source or doc files — any needed content change belongs to the coder specialist; report it instead.\n\n` +
       `DETERMINISTIC GATE POLICIES (NO user prompts):\n` +
       `• G1 dirty-tree (main repo ${MAIN}): partition framework-managed noise exactly as setup.md step 3 ($METRICS=${METRICS}, .baldart/generated|state.json|skill-conflicts.json — NOT overlays/). Genuine user work → auto-stash 'baldart-new2-${firstCard}' (main checkout) and record the label. Never commit/abort/prompt.\n` +
@@ -614,7 +614,7 @@ async function runCard(cardId, cardPath) {
         `Return: { epic, buildBlocked, blockedGate, unmetACs:[{n,text}], scopeFiles, mayEditPaths, revertedOutOfOwnership:[paths], fileDiffViolation, note }`,
       { label: `implement:${cardId}`, phase: 'Implement', agentType: ownerAgent,
         schema: { type: 'object', required: ['epic', 'buildBlocked', 'unmetACs', 'scopeFiles'], additionalProperties: true,
-          properties: { epic: { type: 'boolean' }, buildBlocked: { type: 'boolean' }, blockedGate: { type: 'string' }, unmetACs: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeFiles: { type: 'array', items: { type: 'string' } }, mayEditPaths: { type: 'array', items: { type: 'string' } }, revertedOutOfOwnership: { type: 'array', items: { type: 'string' } }, fileDiffViolation: { type: 'boolean' }, note: { type: 'string' } } } }
+          properties: { epic: { type: 'boolean' }, buildBlocked: { type: 'boolean' }, blockedGate: { type: 'string' }, unmetACs: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeFiles: { type: 'array', items: { type: 'string' } }, mayEditPaths: { type: 'array', items: { type: 'string' } }, revertedOutOfOwnership: { type: 'array', items: { type: 'string' } }, fileDiffViolation: { type: 'boolean' }, note: { type: 'string' }, bindingCheck: { type: 'object', additionalProperties: true, description: 'check-bindings.mjs one-line JSON (mockup+bindings cards only)' } } } }
     )
   } catch (e) {
     if (e && e.transientExhausted) { noteDegraded('outage'); return { card: cardId, status: 'pending', gates } }
@@ -653,6 +653,23 @@ async function runCard(cardId, cardPath) {
     if (r.status !== 'resolved') { deferredOpen = true; deferredClasses.add(r.deferralClass || 'unresolved') }
   }
 
+  // --- R1-F2 (v4.92.1): the binding gate result is CONSUMED, not write-only. The agent
+  // was already told to run check-bindings.mjs and fix before returning; here the workflow
+  // verifies the report: violations survive the agent's own pass → resolve (ui domain);
+  // report absent on a bindings card → fail-open but LEDGERED (audit trail, never silent).
+  if (node.hasMockup && node.hasBindings) {
+    const bc = impl && impl.bindingCheck
+    const bcViol = (bc && Array.isArray(bc.violations)) ? bc.violations : []
+    if (!bc) g('binding-gate', 'NOT-REPORTED', 'agent returned no bindingCheck — fail-open (script may be absent on older installs), recorded for audit')
+    else if (bcViol.length) {
+      g('binding-gate', 'VIOLATIONS', bcViol.map((v) => v.component).join(', '))
+      for (const v of bcViol) {
+        const r = await resolve('blocker', cardId, `binding-not-honored: region "${v.region || ''}" is bound action:${v.action || 'reuse'} → ${v.component}, but the component appears in NO touched implementation file — the binding map is authoritative (card-schema.md § component_bindings)`, { mayEditPaths: mayEdit, scopeFiles, domain: 'ui' })
+        if (r.status !== 'resolved') { deferredOpen = true; deferredClasses.add(r.deferralClass || 'unresolved') }
+      }
+    } else g('binding-gate', 'OK', `${(bc && bc.honored) || 0}/${(bc && bc.checked) || 0} bindings honored`)
+  }
+
   // --- T1.A (v4.90.0): route-free structural fidelity lane — the new2 parallel of
   // /e2e-review Phase 2.7. new2 has NO browser lanes (visual/quality verify runs only on
   // the /new path), so the code-form structural check is its ONE per-card fidelity lane.
@@ -664,26 +681,42 @@ async function runCard(cardId, cardPath) {
     const structSrc = node.designSrcDir
       ? { level: 'design_src', design_src_dir: node.designSrcDir }
       : { level: 'html', mockup_path: node.designHtml }
+    const spawnMfv = () => agentSafe(
+      `Compare the implementation's code structure against the mockup's code structure and return JSON per your output schema (route-free — no browser, no dev server; cd into ${sharedCtx.worktreePath}).\n\nInput payload:\n${JSON.stringify({ card_id: cardId, route: '(card-level)', mockup_source: structSrc, implementation_files: scopeFiles, tolerance: 'strict' })}\n\nReturn STRICT JSON only: { status, findings:[{category,severity,description,expected,actual,fix_hint}] }`,
+      { label: `fidelity:${cardId}:structural`, phase: 'Implement', agentType: 'markup-fidelity-verifier',
+        schema: { type: 'object', required: ['findings'], additionalProperties: true, properties: { status: { type: 'string' }, findings: { type: 'array', items: { type: 'object', additionalProperties: true } } } } }
+    )
     let mfv = null
-    try {
-      mfv = await agentSafe(
-        `Compare the implementation's code structure against the mockup's code structure and return JSON per your output schema (route-free — no browser, no dev server; cd into ${sharedCtx.worktreePath}).\n\nInput payload:\n${JSON.stringify({ card_id: cardId, route: '(card-level)', mockup_source: structSrc, implementation_files: scopeFiles, tolerance: 'strict' })}\n\nReturn STRICT JSON only: { findings:[{category,severity,description,expected,actual,fix_hint}] }`,
-        { label: `fidelity:${cardId}:structural`, phase: 'Implement', agentType: 'markup-fidelity-verifier',
-          schema: { type: 'object', required: ['findings'], additionalProperties: true, properties: { findings: { type: 'array', items: { type: 'object', additionalProperties: true } } } } }
-      )
-    } catch (e) {
-      if (e && e.transientExhausted) noteDegraded('outage')
-    }
-    if (!mfv) {
-      g('fidelity-structural', 'UNDERRUN', 'planned lane never executed (verifier unavailable) — verification-coverage-gap, card cannot auto-DONE')
+    try { mfv = await spawnMfv() } catch (e) { if (e && e.transientExhausted) noteDegraded('outage') }
+    // R1-F1 (v4.92.1): a verifier that RETURNS but self-reports `status:"skipped"`
+    // (no_structural_ground_truth — unreadable mockup / no layout-bearing impl) is an
+    // under-run exactly like an unavailable verifier, NEVER a PASS.
+    const mfvSkipped = mfv && /skip/i.test(String(mfv.status || ''))
+    if (!mfv || mfvSkipped) {
+      g('fidelity-structural', 'UNDERRUN', `planned lane did not verify (${!mfv ? 'verifier unavailable' : 'verifier skipped: ' + String((mfv && mfv.reason) || 'no_structural_ground_truth')}) — verification-coverage-gap, card cannot auto-DONE`)
       deferredOpen = true; deferredClasses.add('unresolved')
-      residuals.push({ card: cardId, kind: 'verification-coverage-gap', evidence: 'structural fidelity lane planned but not executed (markup-fidelity-verifier unavailable)', materialized: false })
+      residuals.push({ card: cardId, kind: 'verification-coverage-gap', evidence: `structural fidelity lane planned but did not verify (${!mfv ? 'markup-fidelity-verifier unavailable' : 'verifier skipped'})`, materialized: false })
     } else {
-      const gating = (mfv.findings || []).filter((f) => /critical|major/i.test(String(f.severity || '')))
+      const gatingOf = (x) => ((x && x.findings) || []).filter((f) => /critical|major/i.test(String(f.severity || '')))
+      const gating = gatingOf(mfv)
       g('fidelity-structural', gating.length ? 'BLOCKED' : 'PASS', gating.length ? `${gating.length} gating structural finding(s)` : `ran — ${(mfv.findings || []).length} finding(s), none gating`)
+      let anyResolved = false
       for (const f of gating) {
         const r = await resolve('blocker', cardId, `structural fidelity (${f.category || 'layout'}): ${f.description || ''} — expected: ${f.expected || '(see mockup)'}`, { mayEditPaths: mayEdit, scopeFiles, domain: 'ui' })
         if (r.status !== 'resolved') { deferredOpen = true; deferredClasses.add(r.deferralClass || 'unresolved') }
+        else anyResolved = true
+      }
+      // R1-F3 (v4.92.1): a resolved structural fix is RE-VERIFIED by the deterministic
+      // verifier once (mirror of /e2e-review Phase 5b step 2 — a fixer's self-report is
+      // not the verifier's confirmation). Single re-check, no loop: still-gating after
+      // the re-run → deferral (the follow-up carries it), never a second fix pass here.
+      if (anyResolved) {
+        let mfvRe = null
+        try { mfvRe = await spawnMfv() } catch (e) { if (e && e.transientExhausted) noteDegraded('outage') }
+        const reGating = mfvRe && !/skip/i.test(String(mfvRe.status || '')) ? gatingOf(mfvRe) : null
+        if (reGating === null) { g('fidelity-structural-reverify', 'UNDERRUN', 're-verify did not run — treated as unresolved'); deferredOpen = true; deferredClasses.add('unresolved') }
+        else if (reGating.length) { g('fidelity-structural-reverify', 'STILL-BLOCKED', `${reGating.length} gating finding(s) survive the fix — deferred`); deferredOpen = true; deferredClasses.add('unresolved'); residuals.push({ card: cardId, kind: 'blocker', domain: 'ui', evidence: `structural fidelity still failing after fix: ${reGating.map((f) => f.category).join(', ')}`, materialized: false }) }
+        else g('fidelity-structural-reverify', 'PASS', 'fix confirmed by the verifier')
       }
     }
   }
@@ -1152,7 +1185,7 @@ if (!committed.length) {
 } else {
   try {
     mergeResult = await agentSafe(
-      `Auto-merge the batch worktree to ${TRUNK} per ${REF}/merge-cleanup.md: Phase 6 via the DETERMINISTIC script merge-worktree.sh, then Phase 6b status reconciliation + Phase 6c hygiene. Run git yourself.\n\n${projectBrief}\nWorktree: ${sharedCtx.worktreePath}\nBranch: ${sharedCtx.branch}\nmerge_strategy: ${mergeStrategy}\nCommitted cards: ${committed.map((r) => r.card).join(' ')}\nPhase-0 stash to restore (if any): see "$(git -C ${MAIN} rev-parse --git-common-dir)/baldart/run/batch-tracker-${firstCard}.md".\n\n` +
+      `Auto-merge the batch worktree to ${TRUNK} per ${REF}/merge-cleanup.md: Phase 6 via the DETERMINISTIC script merge-worktree.sh, then Phase 6b status reconciliation + Phase 6c hygiene. Run git yourself.\n\n${projectBrief}\nWorktree: ${sharedCtx.worktreePath}\nBranch: ${sharedCtx.branch}\nmerge_strategy: ${mergeStrategy}\nCommitted cards: ${committed.map((r) => r.card).join(' ')}\nPhase-0 stash to restore (if any): see "$(git -C "${MAIN}" rev-parse --git-common-dir)/baldart/run/batch-tracker-${firstCard}.md".\n\n` +
         `PHASE 6 — run the SSOT script (the merge analogue of setup-worktree.sh; NOT a hand-rolled merge, NOT /mw inline):\n` +
         `  MERGE_SH="$(ls .framework/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh .claude/skills/worktree-manager/scripts/merge-worktree.sh 2>/dev/null | head -1)"\n` +
         `  bash "$MERGE_SH" --worktree ${sharedCtx.worktreePath} --manifest /tmp/new2-merge-status-${firstCard}.txt --skip-checks\n` +