baldart 4.58.0 → 4.60.0

package/framework/.claude/workflows/new-final-review.js

@@ -20,9 +20,16 @@ export const meta = {
 //   archBaselinePaths  string[] | null       per-card baselines; null → spawn architect (F.2)
 //   hasApiDataFiles    boolean               gates api-perf-cost-auditor (default true)
 //   config             object                resolved baldart.config.yml (paths.*, …)
+//   applyFixes         boolean (default false)  when true, run the opt-in Fix phase (P0-A, v4.59.0)
+//   editableFiles      string[] (default [])    union ownership map — files writers MAY edit (Fix scope)
 //
 // Return value (consumed by the skill at F.5):
-//   { codexEngine, findings:[…classified, FALSE_POSITIVE dropped], gateTable, summary }
+//   applyFixes !== true → EXACTLY { codexEngine, findings:[…classified, FALSE_POSITIVE dropped],
+//                                   noActionFindings, gateTable, summary } (byte-compatible; new2 untouched)
+//   applyFixes === true → that PLUS additive { fixesApplied:[…1-line], docFixesApplied:[…1-line],
+//                                   residual:[…slim findings] }. `findings` STAYS the full classified
+//                                   actionable set (telemetry/compat); the skill reads `residual` to
+//                                   decide what (if anything) it still spawns at F.5.
 // ───────────────────────────────────────────────────────────────────────────
 
 // Tolerate args delivered as a JSON string (parse-or-default) — the Workflow tool
@@ -36,6 +43,16 @@ const cfg = a.config || {}
 const highRisk = (cfg.paths && cfg.paths.high_risk_modules) || [] // security-domain hint
 const protocolRef = '.claude/skills/new/references/final-review.md'
 
+// P0-A (v4.59.0) — opt-in Fix phase. Both default safe-OFF: a caller that does not opt in (new2,
+// or any pre-v4.59.0 caller) gets a byte-identical return. Gated below on applyFixes && editable.length.
+const applyFixes = a.applyFixes === true
+const editableFiles = Array.isArray(a.editableFiles) ? a.editableFiles.filter(Boolean) : []
+// Curated toolchain (parity with new-card-review.js): when features.has_toolchain is on the consumer
+// records LITERAL gate commands in toolchain.commands.* — the Fix-phase writers run THOSE. Empty /
+// absent → silent fallback to the project-standard default. Read from args.config, never hardcoded.
+const tcCmds = (cfg.toolchain && cfg.toolchain.commands) || {}
+const tc = (key, fallback) => (tcCmds[key] && String(tcCmds[key]).trim()) || fallback
+
 // Concurrency cap (v4.53.6 — API rate-limit guardrail; mirrors new-card-review.js + the team-mode
 // coder cap). The org-level rate limit is SHARED across every terminal/session; a wide agent fan-out
 // saturates it and the server throttles. Cap concurrent agents at 3 via a rolling worker pool (NOT
@@ -135,6 +152,38 @@ const VERDICT_SCHEMA = {
     rationale: { type: 'string' },
   },
 }
+const FIX_SCHEMA = {
+  type: 'object', required: ['applied', 'unresolved', 'checks'], additionalProperties: false,
+  properties: {
+    applied: {
+      type: 'array',
+      items: {
+        type: 'object', required: ['finding_id'], additionalProperties: false,
+        properties: { finding_id: { type: 'string' }, note: { type: 'string' } },
+      },
+    },
+    unresolved: { type: 'array', items: { type: 'string', description: 'finding_id left unfixed' } },
+    checks: {
+      type: 'object', required: ['lint', 'tsc', 'build'], additionalProperties: false,
+      properties: { lint: { enum: ['PASS', 'FAIL', 'SKIP'] }, tsc: { enum: ['PASS', 'FAIL', 'SKIP'] }, build: { enum: ['PASS', 'FAIL', 'SKIP'] } },
+    },
+    note: { type: 'string' },
+  },
+}
+// SC-1 — collision-safe finding_id reconciliation. The fan-in rewrites every id to `${source}#${i}:${orig}`,
+// but a writer often echoes only the human-readable tail → an exact-Set match drops applied fixes into
+// residual. Accept exact equality OR a UNIQUE colon-delimited tail (id.endsWith(':'+token)); a bare suffix
+// (e.g. '001' vs 'CR-001') must NOT match → only ':'+token. 0 or >1 hits → return the token unchanged
+// (caller logs the mismatch; never silently mis-attribute across cards).
+function makeResolveId(canonIds) {
+  return (returned) => {
+    const t = String(returned == null ? '' : returned).trim()
+    if (!t) return returned
+    if (canonIds.includes(t)) return t
+    const hits = canonIds.filter((id) => id === t || id.endsWith(':' + t))
+    return hits.length === 1 ? hits[0] : returned
+  }
+}
 
 // ---- Shared brief fragments -------------------------------------------------
 const scopeBrief = [
@@ -342,20 +391,34 @@ for (const item of reviewResults) {
   }
 }
 
-// F-040 — ONE deterministic fallback: either the pre-flight found no companion, or it ran
-// but did not complete. Either way the primary code review must still happen (F.4 step 8).
-// PROSE-ONLY salvage (v4.56.0): when Codex FINISHED but emitted prose (no sentinel JSON), seed the
-// fallback with that prose as UNVERIFIED leads — the relay never parses prose; the fallback
-// code-reviewer (real reviewer WITH code access) re-verifies each lead against the actual diff and
-// emits the schema, so Codex's cross-model finds are recovered, not discarded. Same trust model.
-if (!codexRan) {
-  codexEngine = codexProse ? 'code-reviewer (codex-seeded)' : 'code-reviewer (fallback)'
-  const seedBlock = codexProse
-    ? `\n\nCodex (a DIFFERENT model) reviewed this exact batch diff and reported the following findings in PROSE — it failed to emit machine-readable JSON, so these are UNVERIFIED leads, NOT validated findings. VERIFY each against the actual diff at its cited file:line, DROP any that don't hold, then run your own full independent review for anything Codex missed. Treat the prose as hints to check, never as ground truth:\n<codex-prose>\n${codexProse}\n</codex-prose>`
-    : ''
+// F-040 — fallback when Codex did not produce parseable JSON. TWO distinct sub-branches:
+//   SEEDED (codexProse present, v4.59.0 Opt-2): Codex FINISHED and reported findings in PROSE.
+//     The cross-model coverage is ALREADY OBTAINED — re-running a full re-hunting code-reviewer over
+//     the whole diff would be a wasted duplicate pass. Instead run a CHEAP CONVERTER that ONLY turns
+//     the prose into the finding schema (no independent re-hunt) and marks the findings source
+//     'codex' but NON-preValidated → the existing Verify phase validates each over the real code.
+//     This preserves the trust model (Verify validates) while removing the duplicate full re-hunt;
+//     layered coverage stays (per-card simplify/security + qa + Verify + the rest of this Final pass).
+//   COLD (no prose at all): genuinely no Codex output → run today's FULL code-reviewer as the primary
+//     review engine; its own FP check makes it preValidated (a second pass would self-judge).
+if (!codexRan && codexProse) {
+  codexEngine = 'codex (prose-converted)'
+  const conv = await agent(
+    `Convert the Codex PROSE findings below into the structured finding schema. For each finding: keep the cited file:line + severity + a one-line minimal_fix_direction; do a LIGHT plausibility check (drop a lead whose cited file:line is obviously wrong/empty); do NOT perform an independent code review or hunt for new issues. Return findings[].\n\n` +
+      `Codex (a DIFFERENT model) reviewed this exact batch diff and reported the following in PROSE (it failed to emit machine-readable JSON):\n<codex-prose>\n${codexProse}\n</codex-prose>`,
+    { label: 'codex-prose-convert', phase: 'Review', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
+  )
+  // NON-preValidated (no `preValidated:true`): the converter did not re-hunt or independently
+  // verify, so verifyFinding routes each to its domain specialist over the real code. Clamp
+  // confidence < 80 — verifyFinding short-circuits to VERIFIED at >= 80, which would skip the
+  // domain-specialist validation SC-3 relies on (the converter just transcribes Codex's own confidence).
+  if (conv && Array.isArray(conv.findings)) raw.push(...conv.findings.map((f) => ({ ...f, source: 'codex', confidence: Math.min(Number(f.confidence) || 0, 70) })))
+} else if (!codexRan) {
+  // COLD branch: no Codex JSON and no prose → the primary code review must still happen (F.4 step 8).
+  codexEngine = 'code-reviewer (fallback)'
   const fb = await agent(
-    `Codex was unavailable for the batch final review. Run the FULL code review yourself over the batch diff, per ${protocolRef} Step F.3.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied. An observation you VERIFIED needs NO change (fix direction "no fix required" / "acceptable as-is") is not work — set requires_action:false (recorded, never sent to a fixer), or do not emit it.${seedBlock}`,
-    { label: codexProse ? 'code-reviewer (codex-seeded)' : 'code-reviewer (fallback)', phase: 'Review', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
+    `Codex was unavailable for the batch final review. Run the FULL code review yourself over the batch diff, per ${protocolRef} Step F.3.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied. An observation you VERIFIED needs NO change (fix direction "no fix required" / "acceptable as-is") is not work — set requires_action:false (recorded, never sent to a fixer), or do not emit it.`,
+    { label: 'code-reviewer (fallback)', phase: 'Review', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
   )
   // the fallback code-reviewer IS the primary code-review engine here and applied its own FP
   // check (prompt above) → trusted, exactly like Codex. A SECOND code-reviewer pass over its own
@@ -438,8 +501,142 @@ const summary = {
 }
 log(`Final review done: ${summary.verified} verified (${summary.blockers} BLOCKER / ${summary.highs} HIGH), ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s). Engine: ${codexEngine}.`)
 
-return { codexEngine, findings, noActionFindings, gateTable, summary }
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Fix (P0-A, v4.59.0) — OPT-IN. Mirrors new-card-review.js's Fix+Doc phases EXACTLY:
+//   security writer FIRST (owns the security-invariant contract — never folded into the coder pass),
+//   then the coder (code/perf/migration/test/simplify), then a doc-reviewer audit-and-apply pass
+//   (WORKTREE ISOLATION). Passes run SEQUENTIALLY so edits on shared files never conflict — no
+//   disjoint-ownership gate needed; the last code pass to run carries the build it verified.
+//   Gated on applyFixes && editableFiles.length: a caller that does NOT opt in (new2, any pre-v4.59.0
+//   caller) skips the whole phase and returns the byte-identical shape below.
+//   Unfixed BLOCKER/HIGH (and every unresolved actionable / NEEDS_MANUAL) flow into `residual` —
+//   never silently dropped.
+// ───────────────────────────────────────────────────────────────────────────
+let fixesApplied = []
+let docFixesApplied = []
+let residual = []
+let checksFailed = false
+if (applyFixes && editableFiles.length) {
+  phase('Fix')
+  const isDoc = (f) => /doc|wiki|ssot|readme/.test(String(f.domain).toLowerCase())
+  // 'security' domain → security-reviewer. migration STAYS coder (canonical writer map), so match the
+  // exact 'security' domain, not the broader verifier regex.
+  const isSecurity = (f) => String(f.domain).toLowerCase() === 'security'
+  const isManual = (f) => f.classification === 'NEEDS_MANUAL_CONFIRMATION'
+  // Partition the actionable set out of `findings` (= VERIFIED + NEEDS_MANUAL; FP + no-action already
+  // removed above). No overlap:
+  //   securityFix    = VERIFIED security → security-reviewer applies (owns the security invariants).
+  //   codeActionable = VERIFIED non-doc non-security → the coder fixes these.
+  //   docFindings    = VERIFIED doc → the doc-reviewer audit-and-apply pass.
+  //   manualResidual = NEEDS_MANUAL any → human gate, owned by the skill (carries its classification out).
+  const securityFix = findings.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && isSecurity(f))
+  const codeActionable = findings.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && !isSecurity(f))
+  const docFindings = findings.filter((f) => f.classification === 'VERIFIED' && isDoc(f))
+  const manualResidual = findings.filter(isManual)
+
+  const SKIP_CHECKS = { lint: 'SKIP', tsc: 'SKIP', build: 'SKIP' }
+
+  // One fix pass: the domain WRITER applies its verified findings to the worktree, then re-verifies.
+  async function applyFixPass(items, writer, label, role) {
+    if (!items.length) return { applied: [], unresolved: [], checks: { ...SKIP_CHECKS }, ran: false }
+    const fixBrief =
+      `Apply ALL of the verified ${role} review findings below to the worktree, then verify the build. You are the ${writer} fix pass for this batch's FINAL review.\n\n` +
+      `Worktree: ${a.worktreePath || '(cwd)'} — cd into it.\n` +
+      `You MAY edit ONLY these files (ownership map — touching anything else is a violation):\n${editableFiles.join('\n')}\n\n` +
+      `Findings to fix (fix the code, not the tests unless a test itself is wrong; do NOT expand scope beyond the finding):\n` +
+      items.map((f) => `- [${f.finding_id}] (${f.domain} / ${f.severity}) ${f.title}\n    evidence: ${f.evidence}\n    direction: ${f.minimal_fix_direction}`).join('\n') +
+      `\n\nSCOPE DISCIPLINE (do not run away — every finding already cites the exact site to fix): go DIRECTLY to each finding's \`evidence\` file:line and apply its \`direction\`. Do NOT re-map the architecture, do NOT re-survey the codebase, do NOT read files beyond the cited evidence + their immediate dependencies. A verified finding is a precise instruction, not a research prompt.` +
+      `\n\nAfter applying: run \`${tc('lint', 'npm run lint')}\` and (when the project uses typescript) \`${tc('typecheck', 'npx tsc --noEmit')}\` and \`${tc('build', 'npm run build')}\` in the worktree. If a check fails because of an edit you made, fix the regression — at most 2 retries — staying within the allowed files. ` +
+      `Do NOT commit. Do NOT git stash (refs/stash is shared across worktrees). ` +
+      `Return: applied (finding_ids you fixed — list a finding here if you MADE the edit, even when the build stays red for reasons OUTSIDE this finding / your ownership; the build status is reported separately in checks), unresolved (finding_ids you could NOT fix within the allowed files / 2 retries), and checks (PASS/FAIL/SKIP for lint, tsc, build).`
+    const r = await agent(fixBrief, { label, phase: 'Fix', agentType: writer, schema: FIX_SCHEMA })
+    const res = (r && typeof r === 'object') ? r : { applied: [], unresolved: items.map((f) => f.finding_id), checks: { ...SKIP_CHECKS } }
+    if (!Array.isArray(res.applied)) res.applied = []
+    if (!Array.isArray(res.unresolved)) res.unresolved = []
+    if (!res.checks || typeof res.checks !== 'object') res.checks = { ...SKIP_CHECKS }
+    res.ran = true
+    log(`Fix: ${writer} applied ${res.applied.length}/${items.length} ${label} finding(s); checks lint=${res.checks.lint} tsc=${res.checks.tsc} build=${res.checks.build}.`)
+    return res
+  }
+
+  // Security writer FIRST, then the coder — sequential → no edit conflict on shared files.
+  const secResult = await applyFixPass(securityFix, 'security-reviewer', 'fix-security', 'security')
+  const codeFixResult = await applyFixPass(codeActionable, 'coder', 'fix-coder', 'code/perf/simplify')
+  if (!securityFix.length && !codeActionable.length) log('Fix: no actionable code/perf/security/simplify findings — fixers skipped.')
+
+  // Reconcile applied/unresolved via SC-1 (the writer may echo only the human-readable id tail).
+  const fixPasses = [secResult, codeFixResult]
+  const allActionable = [...securityFix, ...codeActionable]
+  const canonIds = allActionable.map((f) => f.finding_id)
+  const resolveId = makeResolveId(canonIds)
+  const appliedIds = new Set(fixPasses.flatMap((p) => (p.applied || []).map((x) => resolveId(x.finding_id))))
+  const unresolvedIds = new Set(fixPasses.flatMap((p) => (p.unresolved || []).map(resolveId)))
+  const matched = [...appliedIds].filter((id) => canonIds.includes(id)).length
+  const claimed = fixPasses.reduce((n, p) => n + (p.applied || []).length, 0)
+  if (matched < claimed) log(`Fix: id-reconciliation — ${claimed - matched} applied id(s) did not map to a canonical finding_id (left as residual; check writer echo).`)
+  const ranChecks = fixPasses.filter((p) => p.ran).map((p) => p.checks)
+  const mergedChecks = ['lint', 'tsc', 'build'].reduce((acc, k) => {
+    acc[k] = ranChecks.some((c) => c[k] === 'FAIL') ? 'FAIL' : (ranChecks.some((c) => c[k] === 'PASS') ? 'PASS' : 'SKIP')
+    return acc
+  }, {})
+  checksFailed = ['lint', 'tsc', 'build'].some((k) => mergedChecks[k] === 'FAIL')
+  const codeResidual = allActionable.filter((f) => !appliedIds.has(f.finding_id) || unresolvedIds.has(f.finding_id))
+
+  // Doc audit-and-apply pass (WORKTREE ISOLATION — worktree-rooted paths, do NOT git stash).
+  const docDir = (cfg.paths && (cfg.paths.docs_dir || cfg.paths.references_dir)) || 'docs'
+  let docApplied = []
+  let docResidualOut = docFindings  // default (no-run branch) keeps the contract explicit
+  const DOC_SURFACE_RE = /(^|\/)(docs?|api|server\/data|lib\/server|schema|migrations?)(\/|\.|$)|\.(md|sql)$/i
+  const docSurfaceTouched = scope.some((f) => DOC_SURFACE_RE.test(String(f)))
+  if (docSurfaceTouched || docFindings.length) {
+    const docBrief =
+      `You OWN the \`doc\` domain end-to-end for this batch's FINAL review: AUDIT the committed diff for doc drift AND APPLY the fixes in THIS invocation (audit-and-apply mode). Do NOT defer doc writes to another agent.\n\n` +
+      `**WORKTREE ISOLATION (per AGENTS.md § Worktree isolation):** every doc you Edit/Write MUST be UNDER the worktree root ${a.worktreePath || '(cwd)'}. NEVER write a path under the main repo — it is checked out live by other sessions; \`cd\` alone does not stop an absolute main-repo path. cd into the worktree first and edit the worktree-rooted copy of each doc (e.g. ${docDir}/… UNDER the worktree).\n\n` +
+      `${scopeBrief}\n\n${baselineBrief}\n\n` +
+      (docFindings.length
+        ? `Verified doc-domain findings from this batch's review (apply each):\n${docFindings.map((f) => `- [${f.finding_id}] ${f.title}\n    evidence: ${f.evidence}\n    direction: ${f.minimal_fix_direction}`).join('\n')}\n\n`
+        : '') +
+      `Then run your standard doc audit on the changed files: sync canonical reference docs (api/, data-model, ssot-registry as applicable), set freshness_status:fresh + last_verified_from_code:<today> on docs you touch. ` +
+      `Do NOT commit (the orchestrator commits). Do NOT git stash (refs/stash is shared across worktrees). ` +
+      `A doc-drift→bug finding rooted in CODE (the impl contradicts a documented contract) is the ONE thing you do NOT fix yourself — return it in \`unresolved\` with the conflicting code file:line + the doc it violates.\n\n` +
+      `Return: applied (one entry per doc fix you MADE — finding_id REQUIRED: use the listed finding's id when it maps to one, else a short synthetic id like "doc-audit-1"; put a 1-line summary in note), unresolved (finding_ids / descriptions you could NOT resolve, incl. code-rooted drift), checks (lint/tsc/build PASS/SKIP — SKIP unless you touched a source-adjacent file).`
+    const dr = await agent(docBrief, { label: 'fix-doc', phase: 'Fix', agentType: 'doc-reviewer', schema: FIX_SCHEMA })
+    const dres = (dr && typeof dr === 'object') ? dr : {}
+    docApplied = Array.isArray(dres.applied) ? dres.applied : []
+    const docUnresolved = Array.isArray(dres.unresolved) ? dres.unresolved : []
+    // SC-1 reconciliation over the doc canon (synthetic doc-audit#i ids return unchanged — correct).
+    const resolveDoc = makeResolveId(docFindings.map((f) => f.finding_id))
+    const docAppliedIds = new Set(docApplied.map((x) => resolveDoc(x && x.finding_id)).filter(Boolean))
+    docResidualOut = docFindings.filter((f) => !docAppliedIds.has(f.finding_id))
+    const extraDocResidual = docUnresolved
+      .filter((u) => typeof u === 'string' && u.trim() && !docFindings.some((f) => f.finding_id === u))
+      .map((u, i) => ({ finding_id: `doc-audit#${i}`, title: String(u).slice(0, 160), severity: 'MEDIUM', domain: 'doc', evidence: '(doc-reviewer audit)', minimal_fix_direction: String(u), classification: 'VERIFIED' }))
+    docResidualOut = [...docResidualOut, ...extraDocResidual]
+    log(`Fix: doc-reviewer applied ${docApplied.length} doc fix(es)${docFindings.length ? ` (incl. ${docFindings.length} routed finding(s))` : ''}; ${docResidualOut.length} unresolved → residual.`)
+  } else {
+    log('Fix: doc audit SKIPPED (no doc-relevant surface in the batch diff and no verified doc finding).')
+  }
+
+  // Assemble the additive return fields.
+  for (const f of allActionable) {
+    if (appliedIds.has(f.finding_id) && !unresolvedIds.has(f.finding_id)) fixesApplied.push(`[${f.finding_id}] ${f.title}`)
+  }
+  for (const x of docApplied) {
+    const note = (x && (x.note || x.finding_id)) ? `${x.finding_id ? `[${x.finding_id}] ` : ''}${x.note || ''}`.trim() : '(doc fix)'
+    docFixesApplied.push(note)
+  }
+  // Residual = unfixed code/perf/security + unresolved doc + every NEEDS_MANUAL (BLOCKER/HIGH ALWAYS land here).
+  residual = [...codeResidual, ...docResidualOut, ...manualResidual].map(slimFinding)
+  log(`Final Fix phase done: ${fixesApplied.length} fixed, ${docFixesApplied.length} doc-applied, ${residual.length} residual${checksFailed ? ', post-fix checks FAILED' : ''}.`)
+}
+
+const base = { codexEngine, findings, noActionFindings, gateTable, summary }
+// Additive ONLY when the Fix phase ran — otherwise byte-identical to today's shape (new2 untouched).
+return applyFixes ? { ...base, fixesApplied, docFixesApplied, residual } : base
 
 function emptySummary() {
   return { total: 0, verified: 0, falsePositive: 0, needsManual: 0, blockers: 0, highs: 0, failingGates: [] }
 }
+function slimFinding(f) {
+  return { finding_id: f.finding_id, title: f.title, severity: f.severity, domain: f.domain, evidence: f.evidence, minimal_fix_direction: f.minimal_fix_direction, classification: f.classification }
+}

package/framework/agents/index.md

@@ -36,6 +36,7 @@ Route agents to the right module with minimal reading.
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
+- If authoring/auditing a subagent whose return would flood the orchestrator context (free-form analysis/audit/research) -> read `agents/return-contract-protocol.md` and bound its final message: COMPACT headline + `path:line` findings + disk pointer, persist the long form. The input-side twin of the effort protocol.
 - If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
 - For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
 - For legacy context -> read `archive/project_full_legacy.md` if it exists.
@@ -71,6 +72,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/i18n-protocol.md` — Internationalization discipline: no hardcoded user-facing strings, context registry (`paths.i18n_registry`) + ICU + context-aware translation; BLOCKING anti-hardcoded lint gate (since v4.52.0, gated on `features.has_i18n`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 - `agents/card-schema.md` — Atomic Card Baseline Schema: the universal, profile-aware (epic/child/standalone) field contract every backlog card satisfies, plus the consumer HALT/BACK-FILL/WARN contract (since v4.35.0)
+- `agents/return-contract-protocol.md` — Subagent return-message economy: COMPACT (bounded headline + `path:line` findings + disk pointer) vs FULL, persist-then-summarize — the input-side twin of `effort-protocol.md` (since v4.59.0)
 
 ## Where to Document (Decision Tree)
 

package/framework/agents/return-contract-protocol.md

@@ -0,0 +1,130 @@
+<!-- contamination-scan: skip
+     The only token the scanner flags here is the substring "fidelity" inside the
+     framework agent name `visual-fidelity-verifier` (a real BALDART agent cited as
+     a return-shape exemplar). It is framework content, not consumer project-leak. -->
+# Return Contract Protocol
+
+## Purpose
+
+Define how a BALDART **subagent** shapes the *final message* it returns to the
+orchestrator that spawned it. The goal is **context economy of the orchestrator**:
+a subagent's full reasoning is often large (analysis, audits, research, doc
+sweeps), and when that whole body lands verbatim in the orchestrator's context it
+crowds out everything else and inflates token cost for every subsequent turn. The
+contract is simple — **persist the long form, return the short form**: the
+deliverable lives on disk (or as structured findings), and the message back to the
+orchestrator is a bounded headline + pointers, never a reasoning dump.
+
+This is the input-side twin of the `effort-protocol`: effort governs how *deeply*
+an agent reasons; this governs how *compactly* it reports back.
+
+## Scope
+
+**In**: The shape and size ceiling of a subagent's *return message* (its last
+action before yielding to the orchestrator), the COMPACT vs FULL distinction, and
+where the long-form body goes instead.
+**Out**: What an agent writes to disk (that is the agent's own deliverable format —
+docs, reports, locale files, cards), the native effort knob (see
+`effort-protocol.md`), and runtime/wire-level token compression (BALDART does not
+ship a runtime; this is a prompt-level authoring convention, not a proxy).
+
+## Background — why the return message is the lever
+
+A subagent invoked via the `Task` tool runs in its own context window; only its
+**final message** is injected back into the orchestrator's context. So the only
+text that costs the orchestrator tokens is that final message — not the agent's
+intermediate reading, thinking, or tool calls. Therefore the entire optimization
+reduces to one rule: **make the final message bounded and structured.** Everything
+the agent needed to reason over stays in its own (discarded) context; the
+durable long-form output, when it is a deliverable, goes to disk where the
+orchestrator can read it on demand instead of paying for it on every turn.
+
+## The two modes
+
+### COMPACT (default for every orchestrator-facing subagent)
+
+The final message is bounded and consists only of:
+
+1. **Headline / verdict** — one line: the outcome (`PASS | FAIL`, "analysis
+   ready", "3 findings", "report written").
+2. **Findings or key points** — as `path:line` references, not pasted code or
+   prose. If the agent emits review findings, use the shared pooled YAML findings
+   schema (see "Reuse the existing findings schema" below) — do not invent a new
+   one.
+3. **Disk pointer** — `Report: <path>` (or `Doc: <path>`, `Cards: <path>`) when
+   the full analysis was persisted, so the orchestrator can read the long form
+   only if it needs to.
+
+Keep it tight — model the ceiling on `qa-sentinel`'s "Return Protocol" (a short
+final message, *not* the full report) and `visual-fidelity-verifier`'s strict
+JSON. A good COMPACT return is tens of lines, not hundreds. **No preamble, no
+restating the task, no narrating what you read.**
+
+### FULL (opt-in, narrow)
+
+The agent returns extended narrative **only** when:
+- the agent was invoked **directly by the user** (not by an orchestrator) for an
+  explanation/exploration where the prose *is* the answer; or
+- the agent's deliverable is inherently the long-form text AND there is no disk to
+  persist it to.
+
+Even in FULL mode, prefer **persist-then-summarize**: if the agent can write the
+long form to disk (a report, a doc, a research file), do that and return COMPACT
+with the pointer. FULL is the exception, not the fallback.
+
+## Persist-then-summarize (the guiding rule)
+
+If your reasoning is a deliverable, **write it to disk and return the pointer.**
+The orchestrator's context is not an archive — it is a working set. An agent that
+writes its report to `/qa/<CARD-ID>.md`, `${paths.references_dir}/...`, or a
+research file and returns a three-line pointer has done its job better than one
+that pastes 800 lines back, because the orchestrator pays for those 800 lines on
+*every* subsequent turn of the batch.
+
+## Reuse the existing findings schema
+
+Review/audit agents that emit findings already share one pooled YAML schema
+(`finding_id / title / source / category / severity / confidence /
+evidence{file,lines,quote ≤8} / minimal_fix_direction / …`), parsed by
+`/codexreview` and the `/new` review fan-in. The COMPACT return **reuses that
+schema** — it is already terse and machine-readable. Never define a per-agent
+findings shape.
+
+## Honest limits
+
+This is a **prompt-level authoring convention**, best-effort — not a parser that
+truncates output. It works because the agent follows its own contract, exactly
+like the thinking-keyword escalation in `effort-protocol.md`. Two consequences:
+
+1. **Don't drop signal to hit a line count.** COMPACT means *no ceremony and no
+   dumps*, not lossy omission of a real BLOCKER. If the findings genuinely need 60
+   lines, use 60 — the win is cutting preamble/narration/echo, not truncating
+   substance. (This mirrors headroom's verbosity L1–L3: remove ceremony and echo
+   first; "caveman" L4 fragmentation is for prose, never for findings.)
+2. **Agents already structured stay as they are.** `qa-sentinel` (Return
+   Protocol), `visual-fidelity-verifier` (JSON schema), `code-reviewer` /
+   `security-reviewer` / `api-perf-cost-auditor` (verdict line + pooled YAML
+   findings, capped narrative) already satisfy this contract — they are the
+   reference exemplars, not edit targets.
+
+## The canonical body block
+
+Every orchestrator-facing subagent that returns free-form analysis pastes a short
+`## Return Contract` section into its body (after `## Core Responsibilities` /
+`## Mission`, or after the role preamble). Keep it dense — cite this module, do
+not re-explain the modes:
+
+```markdown
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+headline/verdict + key points as `path:line` (no reasoning dump, no pasted code) +
+`Report: <path>` when the full analysis is on disk. Persist the long form, return
+the short form. FULL narrative only when the user invoked you directly for prose.
+Findings schema, mode definitions, and the persist-then-summarize rule:
+`framework/agents/return-contract-protocol.md`.
+```
+
+A copy-paste starter lives at `framework/templates/agent-return-contract.snippet.md`.
+When adding a new orchestrator-facing agent, paste this block — the convention is
+recorded in `framework/.claude/agents/REGISTRY.md` (the agent SSOT).

package/framework/templates/agent-return-contract.snippet.md

@@ -0,0 +1,30 @@
+<!-- contamination-scan: skip
+     The only token the scanner flags is "fidelity" inside the framework agent name
+     `visual-fidelity-verifier` (cited as an exemplar) — framework content, not leak. -->
+<!--
+  RETURN CONTRACT HEADER — paste this into any orchestrator-facing BALDART
+  subagent that would otherwise return free-form analysis/audit/research prose.
+
+  Paste the `## Return Contract` block below right after `## Core Responsibilities`
+  / `## Mission` (or after the role preamble). It bounds the agent's FINAL MESSAGE
+  to the orchestrator so a long body doesn't flood the orchestrator's context —
+  the long form goes to disk, the return is a short headline + pointers.
+
+  Skip for agents that ALREADY have a tight return shape (qa-sentinel's Return
+  Protocol, visual-fidelity-verifier's JSON, the verdict+pooled-YAML reviewers) —
+  they are the reference exemplars, not edit targets.
+
+  Full protocol: framework/agents/return-contract-protocol.md
+
+  Keep this header DENSE (4-5 lines). Do not re-explain the modes —
+  cite framework/agents/return-contract-protocol.md instead.
+-->
+
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+headline/verdict + key points as `path:line` (no reasoning dump, no pasted code) +
+`Report: <path>` when the full analysis is on disk. Persist the long form, return
+the short form. FULL narrative only when the user invoked you directly for prose.
+Findings schema, mode definitions, and the persist-then-summarize rule:
+`framework/agents/return-contract-protocol.md`.

package/framework/templates/baldart.config.template.yml

@@ -410,6 +410,17 @@ git:
   # worktree-isolated and respect the terminal-isolation rule.
   merge_strategy: pr
 
+  # Auto-deploy allowlist (since v4.59.0). Bounds what the `/new` `-auto-ship`
+  # autonomous mode may execute as an OUTWARD/IRREVERSIBLE action (remote schema
+  # deploy, env/feature-flag writes, etc.). A list of deploy targets/intents the
+  # orchestrator is authorized to run unattended; default empty = NOTHING
+  # auto-deploys (bare `-auto` ships nothing outward — outward actions defer to a
+  # follow-up card). This is layered ON TOP of `stack.schema_deploy_from_trunk_only`,
+  # which remains a hard branch floor — the allowlist authorizes WHAT may ship, the
+  # trunk-only invariant still constrains FROM WHERE. Free-form labels matched by
+  # the production-readiness gate, e.g. ["supabase-db-push", "vercel-prod"].
+  auto_deploy: []
+
 # ─── TOOLS ───────────────────────────────────────────────────────────────
 # Which AI CLI tools should the framework target on this machine?
 # Each enabled tool gets its own per-item skill symlinks pointing at the

package/package.json

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

package/src/commands/configure.js

@@ -663,6 +663,19 @@ async function interactivePrompts(merged, detected) {
     UI.warning('You picked `local-push` but develop appears protected on origin — pushes will be rejected. Switch back to `pr` if it fails.');
   }
 
+  // ---- Auto-deploy allowlist (since v4.59.0) ----------------------------
+  // Bounds what `/new -auto-ship` may execute as an OUTWARD action. Empty =
+  // nothing auto-deploys (safe default). Layered ON TOP of
+  // stack.schema_deploy_from_trunk_only, which stays a hard branch floor.
+  const currentAutoDeploy = Array.isArray(merged.git.auto_deploy) ? merged.git.auto_deploy : [];
+  const autoDeployAnswer = (await UI.input(
+    `Auto-deploy allowlist for \`/new -auto-ship\` (comma-separated deploy targets/intents; blank = none) (current: ${currentAutoDeploy.join(', ') || '—'})`,
+    currentAutoDeploy.join(', ')
+  )).trim();
+  merged.git.auto_deploy = autoDeployAnswer
+    ? autoDeployAnswer.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
   UI.section('Features (explicit yes/no — option A: always ask)');
   for (const flag of [
     ['has_design_system', 'Project has a documented design system?'],

package/src/commands/doctor.js

@@ -464,6 +464,21 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on i18n probe */ }
 
+    // ---- Auto-deploy allowlist presence (since v4.59.0) ----------------
+    // Purely informational: git.auto_deploy bounds what `/new -auto-ship`
+    // may execute as an OUTWARD action. An empty allowlist is the SAFE
+    // default (nothing auto-deploys), so this is only worth noting — never
+    // a fix. Surfaced so a user who relies on `-auto-ship` knows whether the
+    // gate is open. Empty/unset = closed (the common, safe case).
+    state.autoDeployConfigured = false;
+    try {
+      if (config && !config.__malformed && config.git
+        && Array.isArray(config.git.auto_deploy) && config.git.auto_deploy.length > 0) {
+        state.autoDeployConfigured = true;
+        state.autoDeployTargets = config.git.auto_deploy.slice();
+      }
+    } catch (_) { /* never block doctor on auto_deploy probe */ }
+
     // ---- External-tool version currency (since v4.38.0) ----------------
     // BALDART pins none of the external tools it installs (graphifyy via pipx,
     // language servers via npm/system) — pipx/npm never auto-upgrade, so a
@@ -983,6 +998,24 @@ function planActions(state) {
     });
   }
 
+  // Auto-deploy allowlist (since v4.59.0). Advisory print-only — surfaced ONLY
+  // when the allowlist is non-empty (the safe default of empty/unset opens
+  // nothing, so it warrants no nag). Reminds the user that `/new -auto-ship`
+  // may execute the listed OUTWARD targets unattended. Never a fix; safe in
+  // --auto since run() only prints. The trunk-only branch floor still applies.
+  if (state.autoDeployConfigured) {
+    actions.push({
+      key: 'auto-deploy-allowlist',
+      label: `Auto-deploy allowlist active: ${state.autoDeployTargets.join(', ')}`,
+      why: `git.auto_deploy authorizes \`/new -auto-ship\` to auto-execute these OUTWARD deploy targets unattended. Only relevant when you run with -auto-ship; otherwise nothing auto-deploys. stack.schema_deploy_from_trunk_only still constrains FROM WHERE a schema deploy may run. Empty the list in baldart.config.yml to close the gate.`,
+      autoOk: true, // advisory print-only; run() does NOT mutate config
+      run: () => {
+        UI.info(`git.auto_deploy = [${state.autoDeployTargets.join(', ')}] — \`/new -auto-ship\` may auto-execute these targets.`);
+        UI.info('Empty `git.auto_deploy` in baldart.config.yml to disable all unattended deploys.');
+      },
+    });
+  }
+
   // External-tool version currency (since v4.38.0). One non-blocking upgrade
   // action per managed tool confirmed behind upstream — the tool-dependency
   // analogue of the `baldart` CLI's own UpdateNotifier. `unknown`/`current`

package/src/commands/update.js

@@ -1283,6 +1283,9 @@ async function update(options = {}, unknownArgs = []) {
               .filter((k) => !(k in (cur2.features || {})));
             const missingPaths = Object.keys(tpl.paths || {})
               .filter((k) => !(k in (cur2.paths || {})));
+            // `git.*` has no type filter — ALL new keys surface regardless of
+            // type, so scalars (trunk_branch, merge_strategy) AND ARRAYS
+            // (git.auto_deploy, the allowlist since v4.59.0) are both caught.
             const missingGit = Object.keys(tpl.git || {})
               .filter((k) => !(k in (cur2.git || {})));
             // Scalar top-level stack.* keys — e.g. stack.database,