baldart 4.59.0 → 4.60.0

package/CHANGELOG.md

@@ -5,7 +5,7 @@ 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.59.0] - 2026-06-21
+## [4.60.0] - 2026-06-21
 
 **`/new` cost + autonomy release — born from a forensic post-mortem of a real `-full` epic run** (224M orchestrator cache_read over 543 turns, context grown to ~670k, 9 improvised on-context fix agents, Codex completing only 2/7 reviews). The dominant cost is mechanical — turn-count × monotonically-growing context, confirmed against Anthropic's current prompt-caching docs — and the back half of the run was the expensive half because the final-review fix cascade and the deploy phase ran ON the orchestrator context at ~670k/turn. Two adversarial review passes shaped and verified the change set (several proposed items were refuted as already-shipped or redundant; four blockers found in pre-release review were fixed before tagging).
 
@@ -21,7 +21,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`framework/.claude/workflows/new-card-review.js`** (+ the final-review Fix phase) — collision-safe `finding_id` reconciliation. A writer that echoes only the human-readable id tail no longer drops applied fixes into residual (the empty-coder re-spawn bug): `resolveId` maps a returned token to its canonical prefixed id by exact or UNIQUE colon-tail match, logging any unmatched. Also a light-tier test gate: after the Fix phase at light tier (where qa-sentinel was skipped), a diff-scoped qa-sentinel pass now catches a fix-introduced test regression via the existing gateTable gate (graceful SKIP when no diff-scoped runner).
 - **`framework/.claude/skills/new/` references** — autonomous gate coverage + turn economy. Every `AskUserQuestion`/HALT gate across SKILL.md + `implement.md`, `setup.md`, `review-cycle.md`, `team-mode.md`, `completeness.md`, `merge-cleanup.md`, `commit.md`, `codex-gate.md`, `final-review.md`, `production-readiness.md` cites the AUTONOMOUS rule (so none silently blocks under `-auto` and none auto-approves a deferral); a sequential-path coverage assertion (review-cycle.md) catches a silently-skipped test-only card review; one concrete batching example added to the turn-economy HARD RULE.
 
-**MINOR** — additive: two new flags (`-auto`/`-auto-ship`) + an opt-in workflow Fix phase + one new `baldart.config.yml` key (`git.auto_deploy`, schema-change propagation applied) + reference-prose gate coverage. No new agent/skill/command/routine; no install/layout change. With the flags/args absent and `applyFixes` not opted in, every path is byte-identical to v4.58.0 (`new2` unaffected).
+**MINOR** — additive: two new flags (`-auto`/`-auto-ship`) + an opt-in workflow Fix phase + one new `baldart.config.yml` key (`git.auto_deploy`, schema-change propagation applied) + reference-prose gate coverage. No new agent/skill/command/routine; no install/layout change. With the flags/args absent and `applyFixes` not opted in, every path is byte-identical to v4.59.0 (`new2` unaffected).
+
+## [4.59.0] - 2026-06-20
+
+**Subagent return contracts — every orchestrator-facing agent now bounds its *final message* so a long body doesn't flood the spawning context.** Outcome of studying the [headroom](https://github.com/chopratejas/headroom) context-compression tool against BALDART's existing context-economy stack. The study's verdict: headroom is **not** adopted as a dependency — it is a heavyweight Python+Rust runtime (proxy/wrapper) that contradicts BALDART's "thin CLI + authored markdown, zero runtime" identity, is explicitly unsuitable for the ephemeral cloud sandboxes these sessions run in, and applies *lossy* compression to code/tool output (risky in a code-gen framework). Its techniques already have prompt-level analogues here: verbosity steering L0–L4 ≈ the Terse / Terse Ultra output styles, effort routing ≈ `effort-protocol`, AST/code compression ≈ the LSP + Graphify retrieval layers (which filter input *losslessly*).
+
+The one real gap headroom surfaced is the **verbosity of subagent return messages**: when free-form analysts (`codebase-architect`, `doc-reviewer`, `plan-auditor`, `senior-researcher`) finish, their entire reasoning body lands verbatim in the orchestrator's context — and the orchestrator pays for it on *every* subsequent turn of a batch. A subagent's final message is the only text that costs the spawning context tokens (its intermediate reading/thinking is discarded), so the whole optimization reduces to one rule: **persist the long form, return the short form.** This is implemented natively — zero dependencies, portable across Claude + Codex, works inside sandboxes — as the input-side twin of the effort protocol: effort governs how *deeply* an agent reasons, the return contract governs how *compactly* it reports back.
+
+The contract: COMPACT (default) = bounded headline/verdict + key points as `path:line` references (no reasoning dump, no pasted code) + `Report: <path>` when the long form is on disk; FULL narrative only when the user invoked the agent directly for prose. It reuses the existing pooled YAML findings schema (never a new one) and explicitly does **not** truncate substance — it cuts ceremony/narration/echo, not real findings. Agents already structured this way (`qa-sentinel` Return Protocol, `visual-fidelity-verifier` JSON, the verdict+pooled-YAML reviewers `code-reviewer` / `security-reviewer` / `api-perf-cost-auditor`) are the reference exemplars and were left untouched.
+
+**MINOR** — adds a protocol module + a template snippet (additive capability); no new `baldart.config.yml` key, so the schema-change propagation rule does not apply (same class as `effort-protocol`). No install/layout change.
+
+### Added
+
+- **`framework/agents/return-contract-protocol.md`** — new SSOT protocol module: COMPACT vs FULL return modes, the persist-then-summarize rule, findings-schema reuse, honest limits, and the canonical `## Return Contract` body block. Modeled on `effort-protocol.md`.
+- **`framework/templates/agent-return-contract.snippet.md`** — copy-paste starter for the `## Return Contract` block (twin of `skill-effort.snippet.md`), with placement guidance and the "skip agents already structured" carve-out.
+
+### Changed
+
+- **`framework/.claude/agents/{codebase-architect,doc-reviewer,plan-auditor,senior-researcher}.md`** — added an explicit `## Return Contract` block (tailored per agent: architect → file/symbol/pattern/risk map as `path:line`; doc-reviewer → condensed verdict + docs on disk; plan-auditor → verdict + pooled YAML, 10-section narrative is FULL-only; senior-researcher → §0–§11 report written to disk, return the Executive Summary + pointer).
+- **`framework/agents/index.md`** — added the return-contract routing rule and a Modules-list entry.
+- **`framework/.claude/agents/REGISTRY.md`** — added the return-contract convention note (exemplars + "paste the block for new analysis/audit/research agents").
 
 ## [4.58.0] - 2026-06-20
 

package/README.md

@@ -82,7 +82,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 ### Core Protocol
 
 - **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
-- **agents/**: 24 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, etc.)
+- **agents/**: 25 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
 ### AI Agents (29 specialized agents)

package/VERSION

@@ -1 +1 @@
-4.59.0
+4.60.0

package/framework/.claude/agents/REGISTRY.md

@@ -6,6 +6,8 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 > **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.
 
+> **Return contract (since v4.59.0)**: every orchestrator-facing subagent bounds its **final message** so a long body doesn't flood the spawning context — COMPACT return (headline/verdict + `path:line` findings + disk pointer), long form persisted to disk. Agents already structured this way are the exemplars (`qa-sentinel` Return Protocol, `visual-fidelity-verifier` JSON, the verdict+pooled-YAML reviewers — `code-reviewer` / `security-reviewer` / `api-perf-cost-auditor`); free-form analysts carry an explicit `## Return Contract` block (`codebase-architect`, `doc-reviewer`, `plan-auditor`, `senior-researcher`). When adding a new analysis/audit/research agent, paste the block from `framework/templates/agent-return-contract.snippet.md`. Protocol: `framework/agents/return-contract-protocol.md`.
+
 ## Agent Map
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |

package/framework/.claude/agents/codebase-architect.md

@@ -27,6 +27,15 @@ Per the project's AGENTS.md MUST rules, all agents must invoke you (codebase-arc
 
 4. **Pattern Recognition**: Identify and explain established patterns in the codebase, including coding standards, architectural decisions (from ADRs), and implementation conventions.
 
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+a structured file / symbol / pattern / risk map as `path:line` references, NOT a
+narrative essay. Lead with the headline answer; cite locations, don't paste code
+or restate what you read. Return only what the spawning agent needs to plan. FULL
+prose only when the user invoked you directly for an explanation. Mode definitions
+and the persist-then-summarize rule: `framework/agents/return-contract-protocol.md`.
+
 **Project-Specific Context:**
 
 This codebase follows strict protocols defined in AGENTS.md. Key architectural references you should consult:

package/framework/.claude/agents/doc-reviewer.md

@@ -36,6 +36,17 @@ Notes: [one-liner if any]
 
 For cards exceeding 3 files or triggering invariants, use the full Required Deliverables format (sections A-H, summarized under "Required Deliverables" below). If `.claude/skills/doc-reviewer-support/references/deliverables-format.md` exists, read it for the detailed section spec; otherwise use the inline summary.
 
+## Return Contract
+
+**Mode:** COMPACT (default). Your docs are written to disk; your final message to
+the orchestrator is bounded — the condensed verdict line (Verdict / invariants /
+docs written / SSOT updated) + violated rows + any `path:line` notes. Persist the
+long form (the docs themselves), return the short form. Never paste full doc bodies
+or the A–H narrative back into the orchestrator context. The Fast-Mode condensed
+format above IS the COMPACT return; use it as the ceiling even for larger cards
+(point to the docs on disk instead of inlining them). Mode definitions and the
+persist-then-summarize rule: `framework/agents/return-contract-protocol.md`.
+
 ## Parallel Safety (MUST)
 
 When running in parallel with other agents (code-reviewer, security-reviewer):

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

@@ -22,6 +22,17 @@ You receive an existing implementation plan (created by another agent, a human,
 
 You review ANY development plan: frontend, backend, mobile, infra, data pipelines, AI/ML, integrations. Assume the plan may be incomplete or optimistic. You must expose gaps.
 
+## Return Contract
+
+**Mode:** COMPACT (default, orchestrator-spawned). Your final message is bounded —
+verdict line + the pooled YAML findings (the FINDINGS YAML SCHEMA below) + a
+`path:line`-referenced one-liner per BLOCKER. The 10-section narrative (OUTPUT
+FORMAT — FULL mode only) is **FULL mode**: emit it only when invoked directly by a
+human for an interactive audit, and when it is large, persist it and return the
+pointer. Don't paste the 10 sections back to an orchestrator that only needs the
+findings. Mode definitions, findings-schema reuse, and persist-then-summarize:
+`framework/agents/return-contract-protocol.md`.
+
 ## AUDIT MODE (read your invocation prompt FIRST)
 
 You operate in one of two declared modes. Detect which from your invocation prompt:

package/framework/.claude/agents/senior-researcher.md

@@ -35,6 +35,16 @@ The report will be read by an AI model with finite context. Therefore:
 - Use consistent terminology and define aliases once (glossary).
 - Use citation-friendly formatting: `[Author Year]` consistently throughout.
 
+## Return Contract
+
+**Mode:** COMPACT return, FULL deliverable-on-disk. The §0–§11 report below is your
+deliverable — **write it to disk** (a research file under the project's docs/wiki
+path). Your final message to the orchestrator is bounded: the Executive Summary
+headline + the recommendation line + `Report: <path>`. Do NOT paste the full
+§0–§11 body back into the orchestrator context — that is exactly the "finite
+context" cost the CRITICAL CONSTRAINT above warns about. Persist the long form,
+return the short form: `framework/agents/return-contract-protocol.md`.
+
 ## OUTPUT (DELIVERABLE)
 A detailed research report containing these sections in order:
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.59.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"