baldart 4.92.1 → 4.94.0

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: e2e-review
 effort: medium
-version: 1.2.1
+version: 1.3.0
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via
@@ -140,8 +140,9 @@ system constraints into a machine-readable verification plan.
      route, SvelteKit `routes/...` → route). If the framework is unknown,
      ask the user.
    - For each changed component under `${paths.components_primitives}`,
-     identify the routes that import it via the `codebase-architect` agent
-     (fallback to grep when LSP is unavailable).
+     identify the routes that import it via the `codebase-architect` agent —
+     pass `PROFILE=impact` (reverse-dependency lookup per
+     `agents/analysis-profiles.md`; fallback to grep when LSP is unavailable).
 3. **Synthesize verification plan** as Gherkin scenarios. Format:
 
    ```gherkin
@@ -260,7 +261,8 @@ If no mockup image is available BUT `features.has_design_system: true`:
   specs (cascade detailed in
   [`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md)).
 - Identify which primitives the route uses via the `codebase-architect`
-  agent (or grep on imports under `${paths.components_primitives}`).
+  agent with `PROFILE=impact` (or grep on imports under
+  `${paths.components_primitives}`).
 - Record `mockup_source.level = "compliance-only"` and the list of components
   in scope.
 

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

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.4.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: `implement.md` Phase 1 step 3 now passes a deterministic `PROFILE=` token to the `codebase-architect` spawn — `ui` when the card has a non-empty `links.design`/`links.design_src` (the same mockup bit as step 6a), else `feature`. Contract SSOT: `framework/agents/analysis-profiles.md`; guarded by the `check-new-parity.mjs` tripwire.
+
 ## 1.3.0 — 2026-07-02
 
 - **Hot-file economy (T2.A)**: il briefing "Codebase Context" passa il baseline

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 1.3.0
+version: 1.4.0
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and

package/framework/.claude/skills/new/references/final-review.md

@@ -211,7 +211,8 @@ that is a **gate violation**: log it as
      Log `f.2-arch: reused N per-card baselines (no re-spawn)` in the tracker. This avoids the N+1
      architect invocations the per-card persistence was designed to prevent.
    - **Any missing** (a card was added late, or a baseline was purged) → invoke **codebase-architect**
-     ONCE over the batch scope to map existing architecture, critical patterns, and high-risk code
+     ONCE over the batch scope — pass `PROFILE=baseline OUTPUT=terse` (`agents/analysis-profiles.md`) —
+     to map existing architecture, critical patterns, and high-risk code
      paths for regression. Persist its output to `/tmp/arch-baseline-batch-<FIRST-CARD-ID>.md` and set
      `${ARCH_BASELINE_PATHS}` to that single path. Log `f.2-arch: re-spawned (missing baselines: <list>)`. Do NOT spawn
      the architect more than once for the batch — it is the single grounding context for all

package/framework/.claude/skills/new/references/implement.md

@@ -10,7 +10,7 @@
    - If `DONE` (or the user chose "proceed anyway") → continue.
 2b. **Claim** — only now set the card status to `IN_PROGRESS` (in the backlog YAML / tracker) and assign yourself. This is a state write, not a visibility emission — do not also spend a TaskUpdate / Progress-Bar turn (§ "State surface — the tracker only").
 2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
-3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.) **Pass `OUTPUT=terse` in the architect prompt (since v4.49.0)** — this is grounding for the coder/reviewer, not an explanation, so the architect returns its structured contract (reuse table + canonical evidence + `path:line — symbol` rows + `totals:`) without narrative prose. The verbatim baseline persisted at step 5b keeps all the substance a lean `/codexreview` needs (paths, signatures, patterns, high-risk paths) while staying small in the orchestrator's context and on disk. **Baseline content contract (MANDATORY — since v4.56.0):** the architect prompt is grounding INPUT only — pass the card scope, `files_likely_touched`, and the question to map. NEVER put line-level fix directives ("remove lines 90-91", "Fix: use X"), the words "implement/fix/apply", or acceptance-criteria framed as a task into the architect prompt. The architect produces a read-only MAP (file/symbol locations, patterns, type signatures, integration points, high-risk paths); it does NOT implement and has no `Task`/Agent tool to delegate (see `codebase-architect.md` § Role boundary). The coder is a separate spawn the orchestrator owns.
+3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.) **Pass `OUTPUT=terse` in the architect prompt (since v4.49.0)** — this is grounding for the coder/reviewer, not an explanation, so the architect returns its structured contract (reuse table + canonical evidence + `path:line — symbol` rows + `totals:`) without narrative prose. **Pass the analysis profile too (since v4.94.0)**: `PROFILE=ui` when the card has a non-empty `links.design` OR `links.design_src` (the same mockup bit that drives step 6a), else `PROFILE=feature` — contract and per-profile scoping in `agents/analysis-profiles.md` (its § 3 caller routing table is normative). The profile is deterministic from the card YAML; never leave the architect to infer it. The verbatim baseline persisted at step 5b keeps all the substance a lean `/codexreview` needs (paths, signatures, patterns, high-risk paths) while staying small in the orchestrator's context and on disk. **Baseline content contract (MANDATORY — since v4.56.0):** the architect prompt is grounding INPUT only — pass the card scope, `files_likely_touched`, and the question to map. NEVER put line-level fix directives ("remove lines 90-91", "Fix: use X"), the words "implement/fix/apply", or acceptance-criteria framed as a task into the architect prompt. The architect produces a read-only MAP (file/symbol locations, patterns, type signatures, integration points, high-risk paths); it does NOT implement and has no `Task`/Agent tool to delegate (see `codebase-architect.md` § Role boundary). The coder is a separate spawn the orchestrator owns.
 3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.
 4. **Plan-auditor grounding check** — but first, a **provenance skip (since v4.7.0 — mirror of Step 3d)**: the `/prd` Step 6.6 holistic audit already ran a per-card grounding pass when the card was authored. Re-grounding here is only worth a plan-auditor spawn if something changed since. **This skip is the NORMAL path for a card implemented right after `/prd`, not an occasional optimization** — `/prd` now guarantees the `metadata.holistic_audit` stamp lands on every audited card (deterministic backstop at `validation-phase.md` Step 7 item 5b, since the v4.88.2 provenance-reliability fix), so P1 below holds whenever the batch is freshly authored. Skip the plan-auditor when **BOTH** hold:
    - **P1 — provenance present**: the card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, `audited_set`.

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

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: the B7 per-card architect spawn in `new2.js` passes `PROFILE=${hasMockup ? 'ui' : 'feature'}` (deterministic from the pre-flight cardGraph bit) mirroring `/new` implement.md step 3; the SSOT is `framework/agents/analysis-profiles.md`. Tripwire rule added to `check-new-parity.mjs`.
+
 ## 1.2.1 — 2026-07-02
 
 Review avversariale post-release (3 lenti indipendenti, finding verificati):

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.2.1
+version: 1.3.0
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background

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

@@ -2,6 +2,23 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.0 — 2026-07-02
+
+- **Analysis-profile contract (framework v4.94.0)**: the discovery-loop targeted architect question now passes `PROFILE=discovery`, and the Step 2 ISA scan passes `PROFILE=impact` (structural tier primary) — per `framework/agents/analysis-profiles.md`. Prompt semantics otherwise unchanged.
+
+## 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.3.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