baldart 4.92.1 → 4.93.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.93.0] - 2026-07-02
+
+**`/prd` gate-hygiene wave — dai driver misurati (forensics di una sessione reale: 61.6M token, 48% del costo in fasi meccaniche, una famiglia di card con zero audit-trail, 96% del wall-clock in attesa umana).** Sette interventi chirurgici, nessuna nuova chiave di config:
+
+- **Tool di misura onesto**: `scripts/new-session-audit.mjs` deduplica l'usage per `message.id` (sovracontava ~2.85× — 175M riportati vs 61.6M reali su FEAT-0061) e riconosce le sessioni `/prd` (`mode=prd`, anche quando la skill è invocata via Skill tool dopo un preambolo; backtrack `self`; confronto col reference FEAT-0041 saltato).
+- **Severità assoluta evidence-anchored** (`prd` skill 1.2.0 + `plan-auditor`): via la quota posizionale "top 20% → HIGH must-apply" — fabbricava cicli di apply su piani puliti e demotava finding reali sui batch grandi. Zero-finding è un esito legittimo.
+- **Validation eseguita, non recitata**: `validate-card-baseline.js --prd` (requirements condizionale PO1, epic `skip`, marker `[NEEDS CLARIFICATION]` bloccanti) + nuovo `framework/scripts/stamp-holistic-audit.js` (stamp `metadata.holistic_audit` deterministico, idempotente; chiamato da 6.9.4 e dal backstop 5b — i due gate-prosa che erano falliti insieme su FEAT-0064).
+- **Context economy dell'orchestratore /prd**: contratto teammate audit estratto in `references/audit-teammate-prompt.md` e passato BY PATH (mai caricato dall'orchestratore; ~−9KB da audit-phase + regola generale per gli spec agent-facing incl. `api-perf-gate.md`); analisi mockup su file delegata a `ui-expert` read-only (misurati ~208KB di mockup in cache per ~300 eventi); Progress Bar solo ai phase-gate con riga compatta intra-fase (~20 righe × 30+ messaggi risparmiate; unifica la policy Codex già esistente).
+
+**MINOR** — capability change su skill/agent/script condivisi; nessun cambio di layout install. **No new `baldart.config.yml` key** → la schema-change propagation rule NON si applica. **Codex parity: portable** (script node zero-dep; prosa skill condivisa ai due runtime; il branch file-backed Codex del teammate contract è documentato in-file).
+
 ## [4.92.1] - 2026-07-02
 
 **Review avversariale post-release del motore new2 (coerenza interna).** Tre reviewer indipendenti a contesto fresco (dataflow / edge-case / contratti) sull'onda v4.90–4.92; ogni finding ri-verificato contro il codice prima di agire: **11 confermati e fixati, 9 refutati con evidenza empirica** (tra i refutati: la "race" del worker-pool adattivo — simulata: 0 buchi; `verify-item.sh` su bash 3.2 reale — funziona; `parseInt` con CRLF; un CAP attribuito a `new2.js` che non esiste).

package/VERSION

@@ -1 +1 @@
-4.92.1
+4.93.0

package/framework/.claude/agents/plan-auditor.md

@@ -348,14 +348,15 @@ Consider:
 
 ## SEVERITY CALIBRATION (after challenge pass)
 
-After challenge pass, rank ALL surviving findings by impact:
-
-1. List all surviving findings in order of impact (most impactful first).
-2. Assign severity based on position:
-   - Top 20% → **HIGH** (must fix before implementation)
-   - Middle 40% → **MEDIUM** (should fix, mark `[MANUAL]` if ambiguous)
-   - Bottom 40% → **LOW** (note only, do not edit structured fields)
-3. **Exception**: data loss, security bypass, breaking change, claimed_path collision, ADR required missing = automatically **HIGH** regardless of position.
+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** (must fix before implementation) — implementing the card as written produces a defect: data loss, security bypass, breaking change, claimed_path collision, ADR required missing, 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** (should fix, mark `[MANUAL]` if ambiguous) — 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** (note only, do not edit structured fields) — informational, no behavioral consequence.
+
+Zero HIGH — or zero findings at all — on a well-formed card is a legitimate, reportable outcome. Do NOT stretch severities to fill bands.
 
 ## QUANTIFIED RISK SCORING (MANDATORY)
 

package/framework/.claude/agents/prd-card-writer.md

@@ -91,6 +91,14 @@ the card reaches `status: DONE`.
 
 6. **Populate `data_fields`** for every card that reads/writes the persistence layer (see Required Fields).
 
+**Never guess silently — mark the ambiguity.** The grounding rule generalizes beyond field
+names: whenever card material forces you to GUESS (an unresolved behavior, an unspecified
+control/state, a value the PRD/Discovery never pinned down), do NOT pick a plausible answer
+silently — write `[NEEDS CLARIFICATION: <the exact question>]` inline at the ambiguous spot.
+The `/prd` validation gate (`validate-card-baseline.js --prd`) BLOCKS commit while any marker
+is unresolved, so the ambiguity reaches a human instead of shipping as a hidden assumption.
+A marker is a legitimate intermediate state, never a defect — the defect is the silent guess.
+
 ## Mission
 
 You receive:

package/framework/.claude/skills/prd/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.2.0 — 2026-07-02
+
+**Gate-hygiene wave** — dai driver misurati sul forensics di una sessione /prd reale (61.6M token; 48% del costo in fasi meccaniche a piena finestra; una famiglia di card spedita con zero audit-trail; ~20 righe di progress bar × 30+ messaggi):
+
+- **Severità assoluta evidence-anchored** (`audit-phase.md` § Severity Calibration + `plan-auditor.md`): rimossa la calibrazione a quota posizionale ("top 20% → HIGH must-apply") che fabbricava finding HIGH su piani puliti e demotava finding reali sui batch grandi. HIGH ora richiede citazione dell'evidenza; zero-finding è un esito legittimo.
+- **Validation ESEGUITA, non recitata** (`validation-phase.md` Step 6 item 0-i): il gate deterministico gira via `validate-card-baseline.js --prd` (enum, requirements condizionale PO1, epic `review_profile: skip`, matrice campi) — i check semantici restano in prosa (0-ii). Nuovo check bloccante: marker `[NEEDS CLARIFICATION: …]` irrisolti (l'ambiguità di planning è un artefatto gated, mai un'assunzione silenziosa; `prd-card-writer` istruito a marcare invece di indovinare).
+- **Stamp holistic deterministico** (`framework/scripts/stamp-holistic-audit.js`, nuovo, zero-dep): `metadata.holistic_audit` scritto da script idempotente/additivo/epic-skipping/self-verifying, chiamato da `audit-phase.md` 6.9.4 E dal backstop `validation-phase.md` 5b (entrambi i call-site erano prosa e sono falliti INSIEME su un run reale).
+- **Prompt agent-facing passati BY PATH** (context economy, ~−30KB dal contesto orchestratore): il contratto teammate dell'audit estratto in `references/audit-teammate-prompt.md` (letto dai teammate, MAI dall'orchestratore); `api-perf-gate.md` dichiarato agent-facing nella flow table (era già delegato, ma la regola "read before each phase" lo faceva caricare comunque); regola generale in SKILL.md.
+- **Mockup mai nel contesto orchestratore** (`discovery-phase.md` 1.6.5): l'analisi mockup su file è DELEGATA a `ui-expert` read-only (ritorna solo lo YAML `mockup_analysis`); misurati ~208KB di mockup decodificato trascinati in cache per ~300 eventi. Eccezione: immagini incollate in chat (già in contesto).
+- **Progress Bar ai phase-gate** (SKILL.md HARD RULE 11): tabella completa solo alle transizioni di fase; riga compatta sugli STOP intra-fase; niente sui messaggi tecnici — adottata su Claude la policy già scritta per Codex (unificazione, non fork).
+
+Codex parity: portable (script node zero-dep + prosa skill condivisa; il branch Codex file-backed del teammate contract è documentato nel file stesso).
+
 ## 1.1.2 — 2026-07-01
 
 - Context economy: trimmed the HARD-RULES **Runtime portability** citation to a one-liner (cite, don't restate — the detail lives in `runtime-portability-protocol.md`). ~330 chars off the SKILL.md core, which sits in context every turn. No behavior change; RULE 4/11 Codex branches unchanged.

package/framework/.claude/skills/prd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.1.2
+version: 1.2.0
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 
@@ -46,14 +46,21 @@ message. You ask questions, wait for answers, and iterate.
 | 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
 | 3 | UI Design (3a-3d) | [ui-design-phase.md](references/ui-design-phase.md) |
 | 4 | Write PRD | [prd-writing-phase.md](references/prd-writing-phase.md) |
-| 4.5 | API Performance Gate | [api-perf-gate.md](references/api-perf-gate.md) |
+| 4.5 | API Performance Gate | [api-perf-gate.md](references/api-perf-gate.md) — **agent-facing**: passed BY PATH to `api-perf-cost-auditor` (spawn per prd-writing-phase § 4.5); the orchestrator does NOT read it |
 | 4b | Confirm Specs (§ "Present and Confirm") | [prd-writing-phase.md](references/prd-writing-phase.md) |
 | 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
 | 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
 | 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
 | 7.6 | Obsidian back-reference — FINAL (upgrades the 1.2 provisional block; only if a spec note was given) | [validation-phase.md](references/validation-phase.md) + [obsidian-backref.md](references/obsidian-backref.md) |
 
-**Before starting each phase, read the corresponding reference file.**
+**Before starting each phase, read the corresponding reference file** — with ONE
+exception class: **agent-facing specs are passed BY PATH to the agent that consumes
+them and MUST NOT be loaded into the orchestrator context.** Today these are
+`references/api-perf-gate.md` (read by `api-perf-cost-auditor` at Step 4.5 and at the
+Step 6 audit) and `references/audit-teammate-prompt.md` (read by each Step 6.6 audit
+teammate). Rationale: a spec loaded by a subagent costs one cheap Read in a disposable
+context; the same spec in the orchestrator rides EVERY subsequent full-window API call
+for the rest of the run.
 
 ---
 
@@ -73,7 +80,17 @@ message. You ask questions, wait for answers, and iterate.
    **Worktree-mode exception (HARD RULE 17):** when the PRD runs inside a docs worktree (default since v3.22.0), the session-start update is **SKIPPED** — writing `project-status.md` in the worktree wouldn't be visible to other terminals working on the main repo, and writing it on the main repo would pollute `git status` for parallel sessions (exactly what worktree isolation is meant to prevent). The at-commit update still applies and runs inside the worktree as the last write before rebase + merge — see [validation-phase.md](references/validation-phase.md) § Step 7.
 10. **STOP means STOP.** When you see `STOP`, end your message. Do not make more tool
     calls. Do not continue to the next step. Wait for the user.
-11. **Progress visibility.** Claude Code: every message MUST end with the Progress Bar (no exceptions). **Codex**: the Progress Bar is OPTIONAL — derive it on demand from the state file and show a compact summary at the phase gates (not after every technical/tool message, per `/new`'s context-economy precedent); update the state file after each phase either way. The discovery **user gates** (one question per message) stay conversational on both runtimes.
+11. **Progress visibility — at PHASE GATES, not on every message (context economy,
+    unified with the Codex policy).** Display the FULL Progress Bar table only at
+    **phase transitions**: entering/completing a numbered phase (1.6, 2, 2.5, 3, 4,
+    4b, 5, 6, 7) and on the final message. On intra-phase STOP messages (e.g. each
+    discovery question) end with ONE compact line instead:
+    `📋 <slug> · Fase <N> <nome> · <indicatore> · Prossimo: <cosa>` (for discovery
+    the indicator is `X/11 dimensioni`). Technical/tool messages carry neither.
+    The state file is updated after each phase either way and stays the recovery
+    SSOT. (Measured driver: ~20 lines × 30+ messages of orchestrator output per
+    run bought no signal the compact line doesn't carry.) The discovery **user
+    gates** (one question per message) stay conversational on both runtimes.
 12. **Scope Expansion Detection.** During discovery (Step 2), after every user answer,
     check if the response introduces NEW structural entities (endpoints, collections,
     pages, roles, flows) not in the original feature description. If detected, pause
@@ -297,9 +314,12 @@ the value lives only in the state file `## Worktree` section.
 
 ---
 
-## PROGRESS BAR — MANDATORY ON EVERY MESSAGE
+## PROGRESS BAR — AT PHASE GATES (see HARD RULE 11)
 
-At the END of every message (after all text, before stopping), display:
+At the END of every **phase-transition** message (a numbered phase entered or
+completed, and the final message), display the full table below. On intra-phase
+STOP messages use only the compact line from HARD RULE 11; on technical/tool
+messages display nothing.
 
 ```
 ---
@@ -324,7 +344,8 @@ Prossimo passo: <what happens next>
 
 Legend: ⬜ = da fare, 🔄 = in corso, ✅ = completato, ⏭️ = saltato (N/A)
 
-**If your message doesn't end with this table, you violated the skill rules.**
+**If a phase-transition message doesn't end with this table — or an intra-phase STOP
+message lacks the compact line — you violated the skill rules.**
 
 ---
 

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

@@ -106,7 +106,7 @@ Use `TaskCreate` to create one task per audit agent per card:
 
 - For **N cards × M agent types**, create **N × M tasks** (one task per agent type per card; excluding Codex plan-audit — see 6.6d). In Step 6.6c, ONE teammate agent per type handles all N tasks in its queue — M agents run in parallel, not N×M.
 - Each task subject: `[CARD-ID] <agent-type> audit`
-- Each task description: full card YAML + adjacent card summaries + file paths + PRD path + instructions.
+- Each task description: full card YAML + adjacent card summaries + file paths + PRD path. The audit instructions are NOT embedded — each teammate reads them from `audit-teammate-prompt.md` (see 6.6e).
 
 **Claim-lock (atomicity on the N×M fan-out)**: each task carries a `claimed_by` field, empty at creation. Before a teammate processes a task it MUST atomically set `claimed_by: <its name>` via `TaskUpdate` and re-read; if the field is already non-empty and not its own name, it SKIPS that task (another worker owns it). This prevents two workers — for example a re-spawn after a transient failure, or an overlapping re-audit (Step 6.9) — from both processing the same card+agent pair and producing duplicate findings. The teammate workflow (Step 6.6e) embeds the claim step.
 
@@ -259,138 +259,31 @@ Suppress findings where the strongest false-positive argument is convincing.
 - If `codebase-architect` was already spawned earlier this session (its summary is in the session tracker artifact registry), pass that summary in the prompt and instruct plan-auditor NOT to re-invoke `codebase-architect`.
 - If `security_review_needed: true` (security-reviewer already ran as a teammate), instruct plan-auditor NOT to spawn `security-reviewer`; its security findings are already in the task store and will be merged at Step 6.7. plan-auditor should rely on those rather than running an independent, un-merged second review.
 
-### 6.6e. Teammate prompt template
+### 6.6e. Teammate prompt — passed BY PATH (context economy)
 
-Each teammate receives this prompt:
+The full teammate contract — identity, task-queue workflow (claim-lock included), the
+per-role audit instructions, the output format with `[Target:]` tags, the challenge
+pass, and the severity calibration — lives in
+[audit-teammate-prompt.md](audit-teammate-prompt.md). That file is an **AGENT-FACING
+spec**: each teammate reads it in ITS OWN context window; the orchestrator MUST NOT
+load it into its own (in a teammate it costs one cheap Read — in the orchestrator it
+would ride every subsequent full-window API call for the rest of the run).
 
-```
-## 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 instructions below).
-   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.
-
-## Audit Instructions
-
-{AGENT_SPECIFIC_INSTRUCTIONS}
-
-## 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:
+Spawn each teammate with this THIN prompt (fill the placeholders, nothing more):
 
-<details>
-<summary>Suppressed findings (N items — challenge pass)</summary>
-- **Finding title** — FP argument: <why suppressed>
-</details>
-
-## Severity Calibration (after challenge pass)
-
-After challenge pass, rank ALL surviving findings relative to each other by impact:
-
-1. List all surviving findings in order of impact (most impactful first).
-2. Assign severity based on position:
-   - Top 20% → HIGH (must apply)
-   - Middle 40% → MEDIUM (should apply)
-   - Bottom 40% → LOW (notes only)
-3. Exception: data loss, security bypass, or breaking change = automatically HIGH regardless of position.
-
-### 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
+```
+You are teammate "<name>" (role: <agent-type>) in team "check-audit".
+FIRST ACTION: Read <references-path>/audit-teammate-prompt.md and follow it exactly —
+it defines your identity, task-queue workflow (TaskList/TaskGet/claim/TaskUpdate),
+your role's audit instructions (§ "<agent-type>"), the output format, the challenge
+pass, and the severity calibration. Then work your task queue until every task you
+can claim is completed.
 ```
 
-### Agent-specific instructions
-
-**plan-auditor**: **Handled by Codex adversarial audit (Step 6.6d).** Not included in the teammate agent team. If Codex is unavailable, the fallback plan-auditor uses INVEST criteria, DoR checks, and requirements smell detection — see Step 6.6d attack_surface for the full checklist.
-
-**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 above): 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` (see `framework/.claude/skills/prd/references/api-perf-gate.md`). 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` (see `framework/.claude/skills/prd/references/api-perf-gate.md`). **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.
+`<references-path>` = the absolute path of this skill's `references/` directory in this
+install — the same directory you read THIS file from (in a consumer typically
+`<repo>/.claude/skills/prd/references`). Do NOT paste the contract's content into the
+spawn prompt or the task descriptions — the path IS the payload.
 
 ## Step 6.7 — Collect & Merge Findings
 
@@ -515,13 +408,23 @@ metadata:
 
 > **Fail-safe contract**: the block is an OPTIMIZATION hint for `/new`, never a *correctness* gate — if `audited_commit` is empty or the block is absent, `/new` Step 3d **and** the `implement.md` Phase-1 plan-auditor grounding (step 4, P1) simply RUN as before (redundant, never wrong). **But writing the block is MANDATORY whenever the audit ran.** It is the single most-omitted step under context pressure, and its absence is exactly what makes `/new` / `new2` spawn the plan-auditor on **every** freshly-authored card even when the batch is implemented immediately after this audit (nothing changed since). Do NOT skip it "to save a write". If git is genuinely unavailable, write `audited_commit: ""` **explicitly** — never omit the block. `validation-phase.md` Step 7 item 5b is the **deterministic backstop** that guarantees this lands before the PRD commit even if this per-card write is missed — but write it here too; the backstop is a safety net, not a license to skip.
 
+**Deterministic writer — EXECUTE, don't hand-edit.** `framework/scripts/stamp-holistic-audit.js` mechanizes this write (idempotent, additive, epic-skipping, self-verifying). Run it ONCE for the whole card set after the per-card field edits:
+
+```bash
+node .framework/framework/scripts/stamp-holistic-audit.js \
+  --at "$HOLISTIC_AUDITED_AT" --commit "$HOLISTIC_AUDITED_COMMIT" \
+  --set "<sorted child IDs, comma-separated>" ${CARD_PATHS}
+```
+
+Hand-edit the YAML only when the script is genuinely unreachable in this install — and say so in the audit log.
+
 ### Per-card workflow
 
 For each card:
 1. Read persisted report → collect all findings for this card ID.
 2. Read current card YAML.
 3. Apply HIGH findings first, then MEDIUM, then write audit trail.
-4. Write the `metadata.holistic_audit` provenance block (see "Holistic-audit provenance stamp" above) using the run-level values captured once. **MANDATORY when the audit ran** (see the Fail-safe contract above) — this is what lets `/new`/`new2` skip the per-card plan-auditor when the card is implemented right after `/prd`; `validation-phase.md` Step 7 item 5b deterministically backstops it, but do not rely on the backstop.
+4. Write the `metadata.holistic_audit` provenance block (see "Holistic-audit provenance stamp" above) — **by EXECUTING `stamp-holistic-audit.js` once for the whole card set** (after the last card's field edits), not by hand-editing YAML. **MANDATORY when the audit ran** (see the Fail-safe contract above) — this is what lets `/new`/`new2` skip the per-card plan-auditor when the card is implemented right after `/prd`; `validation-phase.md` Step 7 item 5b deterministically backstops it, but do not rely on the backstop.
 5. Write updated card YAML.
 6. Re-read to verify edits landed correctly.
 
@@ -538,4 +441,4 @@ Every component in this audit encodes an assumption about what the model can't d
 - Remove one component at a time, measure audit quality delta.
 - If delta < 5% `[CALIBRATION-NEEDED: removal threshold is a heuristic; validate against a labelled audit-quality benchmark before treating it as a hard cutoff]`, remove permanently.
 - **Current load-bearing assumptions**: challenge pass, adjacent card retrieval, evidence quotes, adversarial evaluator tuning.
-- **Assumptions to re-test**: agent team separation (could single-agent handle N cards?), relative severity ranking (does absolute assignment work with better models?).
+- **Assumptions to re-test**: agent team separation (could single-agent handle N cards?). (Relative severity ranking was retired in the gate-hygiene wave: severity is now absolute + evidence-anchored — positional quotas manufactured mandatory findings on clean plans.)

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/scripts/stamp-holistic-audit.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * stamp-holistic-audit.js — deterministic writer of the `metadata.holistic_audit`
+ * provenance block on backlog cards.
+ *
+ * Why this exists (/prd gate-hygiene wave): the per-card stamp write in
+ * audit-phase.md Step 6.9.4 and its backstop in validation-phase.md Step 7 item 5b
+ * were BOTH model-driven prose — and both failed together on a real run (a whole
+ * card family shipped with zero audit trail, so `/new` re-spawned the plan-auditor
+ * on every card). A prose gate degrades under context pressure; this script makes
+ * the stamp a single deterministic operation both call sites EXECUTE.
+ *
+ * Semantics are defined in audit-phase.md § "Holistic-audit provenance stamp" —
+ * this script only mechanizes the write:
+ *   - idempotent: a card already carrying `holistic_audit` with a non-empty
+ *     `audited_commit` is left untouched;
+ *   - additive: never overwrites other `metadata` keys;
+ *   - EPIC cards are skipped (they carry `planning_session` only — card-schema.md);
+ *   - `--commit ""` is written EXPLICITLY (never omitted) so `/new` treats it as
+ *     drift and runs its own plan-auditor (the fail-safe contract).
+ *
+ * Usage:
+ *   node framework/scripts/stamp-holistic-audit.js \
+ *     --at "2026-07-02T10:00:00Z" --commit "<sha-or-empty>" \
+ *     --set "FEAT-0070-01,FEAT-0070-02" <card1.yml> [<card2.yml> ...]
+ *
+ * Exit 0 = every non-epic card carries the stamp afterwards; exit 1 = a write or
+ * parse failed (per-file errors printed). Zero-dep, node-core only.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseCardYaml, detectProfile } = require(path.join(__dirname, 'validate-card-baseline.js'));
+
+function argValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i > -1 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+/** True when the card text already carries holistic_audit with a non-empty audited_commit. */
+function alreadyStamped(text) {
+  const m = String(text).match(/^\s+holistic_audit:\s*$[\s\S]*?^\s+audited_commit:\s*"([^"]+)"/m);
+  return !!(m && m[1].trim() !== '');
+}
+
+/** Remove a pre-existing holistic_audit block (e.g. one with an empty commit) so the rewrite is clean. */
+function stripExistingBlock(text) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((l) => /^\s+holistic_audit:\s*$/.test(l));
+  if (start === -1) return text;
+  const indent = lines[start].length - lines[start].trimStart().length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const l = lines[end];
+    if (l.trim() === '') { end++; continue; }
+    const li = l.length - l.trimStart().length;
+    if (li <= indent) break;
+    end++;
+  }
+  return lines.slice(0, start).concat(lines.slice(end)).join('\n');
+}
+
+function buildBlock(at, commit, set, childIndent) {
+  const pad = ' '.repeat(childIndent);
+  const inner = ' '.repeat(childIndent + 2);
+  const ids = set.map((s) => `"${s}"`).join(', ');
+  return [
+    `${pad}holistic_audit:`,
+    `${inner}audited_at: "${at}"`,
+    `${inner}audited_commit: "${commit}"`,
+    `${inner}audited_set: [${ids}]`,
+  ].join('\n');
+}
+
+function stampFile(file, at, commit, set) {
+  let text = fs.readFileSync(file, 'utf8');
+  let card;
+  try { card = parseCardYaml(text); } catch (e) { return { file, status: 'error', detail: `YAML parse error — ${e.message}` }; }
+  if (!card || typeof card !== 'object') return { file, status: 'error', detail: 'not a YAML mapping' };
+  if (detectProfile(card, path.basename(file)) === 'EPIC') return { file, status: 'epic-skipped' };
+  if (alreadyStamped(text)) return { file, status: 'already-stamped' };
+
+  text = stripExistingBlock(text);
+  const lines = text.split('\n');
+  const metaIdx = lines.findIndex((l) => /^metadata:\s*$/.test(l));
+  if (metaIdx > -1) {
+    // child indent = indent of the first existing metadata child, else 2 spaces
+    let childIndent = 2;
+    for (let j = metaIdx + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === '') continue;
+      const li = l.length - l.trimStart().length;
+      if (li > 0) childIndent = li;
+      break;
+    }
+    lines.splice(metaIdx + 1, 0, buildBlock(at, commit, set, childIndent));
+    text = lines.join('\n');
+  } else {
+    if (!text.endsWith('\n')) text += '\n';
+    text += `\nmetadata:\n${buildBlock(at, commit, set, 2)}\n`;
+  }
+  fs.writeFileSync(file, text);
+  // verify the write landed (the 5b "re-read one card" contract, made universal)
+  if (!alreadyStamped(fs.readFileSync(file, 'utf8')) && commit !== '') {
+    return { file, status: 'error', detail: 'post-write verification failed — stamp not found' };
+  }
+  return { file, status: 'stamped' };
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const at = argValue(args, '--at');
+  const commit = argValue(args, '--commit'); // may legitimately be "" — must still be PASSED
+  const setRaw = argValue(args, '--set');
+  const files = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--at' || args[i] === '--commit' || args[i] === '--set') { i++; continue; }
+    files.push(args[i]);
+  }
+  if (!at || commit === null || setRaw === null || !files.length) {
+    process.stderr.write('Usage: stamp-holistic-audit.js --at <iso8601> --commit <sha-or-empty> --set "ID1,ID2" <card.yml> [...]\n');
+    return 2;
+  }
+  const set = setRaw.split(',').map((s) => s.trim()).filter(Boolean).sort();
+  let failed = 0, stamped = 0, already = 0, epics = 0;
+  for (const f of files) {
+    let r;
+    try { r = stampFile(f, at, commit, set); } catch (e) { r = { file: f, status: 'error', detail: e.message }; }
+    if (r.status === 'error') { failed++; process.stdout.write(`✖ ${f}: ${r.detail}\n`); }
+    else if (r.status === 'stamped') { stamped++; process.stdout.write(`✓ ${f}: stamped\n`); }
+    else if (r.status === 'already-stamped') { already++; process.stdout.write(`· ${f}: already stamped\n`); }
+    else { epics++; process.stdout.write(`· ${f}: epic — skipped\n`); }
+  }
+  process.stdout.write(`holistic_audit provenance: ${stamped + already}/${files.length - epics} non-epic cards stamped (${stamped} written here, ${already} already present, ${epics} epic skipped)\n`);
+  return failed ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { stampFile, alreadyStamped, stripExistingBlock };

package/framework/scripts/validate-card-baseline.js

@@ -19,8 +19,18 @@
  *
  * Usage:
  *   node framework/scripts/validate-card-baseline.js <card.yml> [<card2.yml> ...]
+ *   node framework/scripts/validate-card-baseline.js --prd <card.yml> [...]
  * Exit 0 = all valid; exit 1 = at least one card has errors (printed per-field).
  *
+ * --prd (since the /prd gate-hygiene wave): adds the deterministic subset of the
+ * /prd validation-phase Step 6 item 0 checks, so the orchestrator EXECUTES them
+ * instead of reciting them (prose gates fail silently under context pressure):
+ *   - conditional `requirements` (PO1): child/standalone with non-empty
+ *     acceptance_criteria + scope MUST have non-empty requirements;
+ *   - epic `review_profile` must be `skip`;
+ *   - `[NEEDS CLARIFICATION: …]` ambiguity markers in the raw YAML are BLOCKERS —
+ *     a card ships only when every planning ambiguity has been resolved.
+ *
  * Module API (for CI self-tests in scripts/check-card-baseline.js):
  *   const { validateCard, detectProfile, loadSchema, loadEnums } = require(...)
  */
@@ -349,21 +359,56 @@ function validateCard(card, { matrix, enums, filename = '' } = {}) {
   return { profile, errors };
 }
 
+// --- /prd deterministic gate additions (--prd) -------------------------------
+
+/** Scan raw YAML text for unresolved planning-ambiguity markers. */
+function scanAmbiguityMarkers(text) {
+  const out = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('[NEEDS CLARIFICATION')) {
+      out.push(`line ${i + 1}: ${lines[i].trim().slice(0, 120)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * The deterministic subset of /prd validation-phase Step 6 item 0 (see file header).
+ * Returns string[] errors. `text` is the raw YAML (marker scan), `card` the parsed map.
+ */
+function prdGateChecks(card, text, profile) {
+  const errors = [];
+  if (profile !== 'EPIC' && nonEmpty(card.acceptance_criteria) && nonEmpty(card.scope) && !nonEmpty(card.requirements)) {
+    errors.push("has acceptance_criteria + scope but no 'requirements' — emit requirements (faithful restatement of AC + scope) before commit (PO1)");
+  }
+  if (profile === 'EPIC' && nonEmpty(card.review_profile) && String(card.review_profile) !== 'skip') {
+    errors.push(`epic 'review_profile' must be 'skip' (got '${card.review_profile}') — trackers have no code work`);
+  }
+  for (const m of scanAmbiguityMarkers(text)) {
+    errors.push(`unresolved ambiguity marker — resolve with the user before commit: ${m}`);
+  }
+  return errors;
+}
+
 // --- CLI --------------------------------------------------------------------
 
 function main(argv) {
-  const files = argv.slice(2);
+  const args = argv.slice(2);
+  const prdMode = args.includes('--prd');
+  const files = args.filter((a) => a !== '--prd');
   if (!files.length) {
-    process.stderr.write('Usage: validate-card-baseline.js <card.yml> [<card2.yml> ...]\n');
+    process.stderr.write('Usage: validate-card-baseline.js [--prd] <card.yml> [<card2.yml> ...]\n');
     return 2;
   }
   const matrix = loadSchema();
   const enums = loadEnums();
   let failed = 0;
   for (const file of files) {
-    let card;
+    let text, card;
     try {
-      card = parseCardYaml(fs.readFileSync(file, 'utf8'));
+      text = fs.readFileSync(file, 'utf8');
+      card = parseCardYaml(text);
     } catch (e) {
       process.stdout.write(`✖ ${file}: YAML parse error — ${e.message}\n`);
       failed++;
@@ -375,6 +420,7 @@ function main(argv) {
       continue;
     }
     const { profile, errors } = validateCard(card, { matrix, enums, filename: path.basename(file) });
+    if (prdMode) errors.push(...prdGateChecks(card, text, profile));
     if (errors.length) {
       failed++;
       process.stdout.write(`✖ ${file} [${profile}] — ${errors.length} issue(s):\n`);
@@ -390,4 +436,4 @@ if (require.main === module) {
   process.exit(main(process.argv));
 }
 
-module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml };
+module.exports = { validateCard, detectProfile, loadSchema, loadEnums, nonEmpty, parseCardYaml, prdGateChecks, scanAmbiguityMarkers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.92.1",
+  "version": "4.93.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"