v3.3

v3.3 (2026-07-26)

Minor version. Four corrections to the orchestration economics, one shared root: stop paying fixed costs where a per-step judgment is cheaper and better informed. The batch-size estimate is corrected by the agent that just did the design (batch renegotiation); worker agents persist and are resumed within a batch instead of respawned (agent persistence); the Critic may fix trivia itself within audited bounds (bounded self-fix); and effort becomes relative, a medium baseline with discretionary one-rung elevation where a step earns it (relative effort). Plus the hot-file trim target, the prompt-template fetch that moves the agent and report templates out of the prompt's own body, and the retirement of PhanesUpgrade's independent version line.

Added

• Batch Renegotiation. The Orchestrator's opening batch estimate is formed from the plan's step list as structure, before any design exists, so it is a guess by the least-informed party. The architect/designer that plans the batch's first step finishes holding a far better picture of true scale, and now has a channel to say so. It appends batch_recommendation (steps, reason) to its report; the Orchestrator adopts it by default and overrides only when one of four clamps fires: the batch would exceed 3 steps, growth would cross a phase boundary, a CLI bridge spawn is still in flight, or its own context is already heavy. The Orchestrator may not decline on the merits, since it holds strictly less information about step complexity than the agent that just did the design.
• The look-ahead block. To recommend growth the planner needs to know what it would absorb, so the Orchestrator now attaches to that agent's spawn prompt the current batch size and step ids plus the ids and one-line descriptions of the next up to 2 pending steps in the same phase. Ids and one-liners only, never step bodies. Roughly 100 to 200 tokens, which is the entire marginal input cost of the mechanism.
• Mandatory sizing record. Every batch session summary now carries one line reporting the estimate, what actually executed, and the recommendation or clamp behind it. A recommendation that leaves no trace is indistinguishable from the mechanism not working, and this line is the only way the heuristic can ever be tuned.
• Agent Persistence. Worker agents (Critic, architect/planner, Executor, Patch-Author) persist for the life of a batch and are RESUMED rather than respawned: the Reflect loop resumes the original producer, a later review resumes the Critic that gave the earlier verdicts. Each avoided respawn saves a measured entry tax of roughly 80,000 tokens, and continuity is the qualitative win: the reviewer that flagged a defect verifies its fix instead of re-litigating from zero. Scoped hard: nothing survives batch close, scouts and haiku agents never persist, the Orchestrator stays ephemeral. Guards: universal re-read-on-resume (no agent ever acts on remembered file state), a resume match rule (same agent, effort satisfiable), and recycle-before-bloat (bridge handles retire past 400,000 cumulative tokens, in-session handles after 6 resumes; the Orchestrator sends a retire notice, the agent finishes its task, writes a handoff digest of at most 40 lines, and stops).
• Bounded Critic self-fix. The Critic may apply fixes from its own review directly, bounded five ways: trivial class only (typos, comments, imports, metadata, lint-level corrections, never logic or interfaces), soft cap 10 changed lines with a hard cap of 20, a mechanical check run before reporting, the full diff attached to the report, and the Orchestrator always informed. Its tools: gains a scoped Edit grant (existing files only) to carry the duty. Anything larger takes the normal Reflect path, which persistence has made cheap.
• Security Review Gate (serial, single-shot). A security-review agent and the Code Critic were being composed as concurrent perspectives on the same artifact, so every review was paid twice, and every Reflect loop re-paid the pair, both at the elevated effort a security-critical step attracts. The gate corrects the topology rather than the price: where the roster carries a security-review specialization and the step triggers it (authentication, credentials, secrets, permissions, a trust-boundary input path, cryptography, money), it runs exactly once per step, after the Code Critic returns pass, never beside it. A fix_required from the Critic never reaches it, so the security pass fires once no matter how many Reflect loops ran, and it always reviews a stable artifact rather than one about to be rewritten. Disagreement resolves in place: findings inside the bounded self-fix limits (the Critic's trivial class plus single-site local security corrections, same soft cap 10 / hard cap 20, mechanical check, diff attached, Orchestrator informed) it applies itself, and that fix is terminal, no Critic re-review, since a dedicated re-review of a 10-line mechanical fix costs more than the risk it retires. Findings above the bounds return fix_required and the security reviewer's involvement in that step ends there: the Reflect loop resumes the original producer (the planner, where the finding is a design defect), the Code Critic verifies the rework against the written findings, and the chain closes on that verdict. The security reviewer is never re-dispatched or resumed within the same step for any reason, so a security-triggering step costs exactly one security pass no matter how the review lands. Its report is therefore the whole handover, and its protocol requires findings written for a Critic who did not attend the review: exact file:line, the concrete failure, the acceptance condition that closes it. close-verifier's applied-vs-approved reconciliation learns that an attached post-Critic security diff is approved-with-attached-diff, not drift; an unattached one still is.
• semble gains an enumeration trigger, and the grant follows duty rather than archetype. A live run logged Read x154 and Grep x20 with zero semble calls, including an exhaustive construction-site enumeration, which is the workload the grant exists for. Two causes, both fixed. The rubric stated one trigger, location ("you do not know which files matter"), so an agent that knew exactly what it was hunting correctly concluded the rule did not apply; enumeration ("you need EVERY instance across the repo") is now a named second trigger, called out as the one agents miss, since knowing what you seek feels like knowing where it is, and it is precisely where a Grep sweep costs most, fanning out across the tree with every hit then Read in full. Grep is demoted to confirming or completing a candidate set the index produced, never to building one. Separately, the Validator archetype was absent from the scout-eligible list and therefore from the semble grant list, so an auditor filed as a Validator never received the tool its whole job needs: Validator is now scout-eligible, Integrator is explicitly excluded (it consolidates already-digested findings and never sweeps raw material), and "analysis-heavy" is defined by duty, not by archetype label, any specialization that sweeps the repo for every instance of something MUST receive semble whatever archetype it was filed under.
• Elevation becomes consider-decline-record. In the same run the elevation budget of 2 went entirely unused while two named triggers were live (a security-critical step and a Reflect loop that failed four times), and the session summary was indistinguishable from a run where nothing triggered. Root cause is an asymmetry, not a judgment error: elevation was MAY, it is delivered by CLI bridge spawn and therefore always looks locally expensive (measured entry tax ~82,000 tokens), and declining left no record at all, so the path of least resistance was free and invisible. The rule is now MUST consider, MAY decline, MUST record: the spend stays discretionary, but every trigger that fires is written to the batch SS effort line with its disposition, elevated, declined: <reason>, or refused: budget. The line's format changes accordingly and triggers 0 fired becomes a distinct, meaningful claim. Trigger (c) additionally obliges the Orchestrator to carry per-step Reflect-loop counts into the decision, a repeatedly failing loop being the clearest signal in the set.
• Hot-file trim target. The register and project CLAUDE.md budget line gains a third number: soft limit 35,000, crop trigger 40,000, trim target 20,000. The Cropping Operation now completes only at or below the target, best effort, protected classes untouched (🛑 entries, the Pinned Directives block, the active project's current-step lines). The point is hysteresis: a register cropped to just under the trigger re-crops within days.
• Relative effort. The recommended launch baseline drops to medium, and agent frontmatter stops carrying absolute levels: effort: becomes effort_class: baseline | elevated, resolved by the Orchestrator at dispatch against the declared session baseline (medium resolves baseline to medium and elevated to high; high to high and xhigh; xhigh is the ceiling). Every shipped archetype is baseline; elevation is purely discretionary, per step, +1 only, hard budget 2 per batch, on a named trigger (security or money, cross-module or high ambiguity, a failed Reflect loop, a batch recommendation reporting the step larger than estimated), and every firing is recorded in the batch SS effort line.
• Prompt-template fetch. The Sub-Agent Definition Template and the Blank Report Template move out of phanes.md's body and into the version-pinned template library (templates/prompts/, new manifest group promptTemplates), fetched by the Step 4 acquire pass on every platform and installed to .claude/template/agent-definition.md and .claude/template/report.md under the same sanity-stamp rule as the scripts. phanes.md keeps a compact Template Contract per template, the audit reference the fetched file is checked against and the fallback recipe when no fetch is possible, the same dual role the script specifications already play, so an offline install still produces complete agents and reports, with template-exact wording restored by the next successful fetch. The exact JSON emission block is retained verbatim in the contract because chains parse it. Update runs overwrite an installed prompt template only while its sha256 still matches the run manifest; a mismatch is a user customization and is preserved, the Reconcile principle applied to prompts. Net effect: roughly 8,000 characters off the prompt body that loads on every /phanes invocation, and one tested wording for every install instead of a fresh paraphrase per run.
• Resumable effort bridge. The CLI bridge's command form moves from --bg to a detached print-mode process (claude -p ... --output-format json), because --bg and -p are mutually exclusive and headless resume requires -p. Bridge spawns now capture session_id and resume via claude --resume <sid> -p ... --effort <level>, with --effort re-passed on every resume (silently dropped otherwise, anthropics/claude-code #66005). The entry tax falls from once per invocation to once per elevated agent per batch, and the per-invocation usage block in the JSON result is what implements the 400k recycle ceiling.

Changed

• Scope guarantees held deliberately unchanged. The planner designs only its own step; it does not pre-design the steps it recommends absorbing, and it must not modify the plan file it was given (the plan is an input, not a workspace). Absorbed steps run their own chains with their own planners and their own Critic, so the per-step review guarantee is untouched. Renegotiation fires once per batch, at the first planning point; later surprises stay covered by the existing early close-out right. Where a bare T1 chain carries no planning-class agent, no look-ahead block is sent, no recommendation is returned, and the opening estimate stands.
• The batch receipt is byte-identical to v3.2. The slim session does not need to know how the number was reached, so the sizing record lives in the session summary rather than in context the primary session pays for and never reads.
• §III workflow rules gain a rule 13 (security review is serial and single-shot); the former rule 13, the spawn-grant exception, renumbers to 14. No other rule numbers move, and nothing cross-references the renumbered rule.
• §III rule 14 carve-out. The spawn-grant rule forbids routing to the orchestrator; it now states explicitly that a worker returning data inside its own report to the Orchestrator that spawned it is neither routing nor invocation, so nobody later reads batch_recommendation as a violation and removes it.
• PhanesUpgrade now carries the Phanes version (v3.3); its independent v2.x line is retired. One framework, one number: any change to the setup moves the whole release, PhanesUpgrade included, and it is re-stamped on every release whether its own content changed or not. Its verification list grows items for the renegotiation, persistence, and effort-resolution protocols, and it gains a migration that rewrites installed effort: frontmatter to effort_class: baseline (every absolute value maps to baseline, including xhigh; a definition left with an absolute value is one the orchestrator can no longer resolve).

Installed project impact:

• Affected: EVERY Phanes-prefixed .claude/agents/*.md (frontmatter migration: effort: becomes effort_class: baseline), .claude/agents/<projectSlug>-orchestrator.md (restates the renegotiation, persistence, and effort-resolution protocols; tools: gains the agent-continuation affordance), .claude/agents/<architect|designer>.md (emit duty plus plan-file prohibition), the Critic agent file (self-fix bounds, scoped Edit grant), any security-review agent file (serial single-shot gate, widened self-fix class, terminal-fix rule), the project CLAUDE.md workflow rules (new rule 13, renumbered rule 14, amended terminal-gate order in rule 5), .claude/workflows/* carrying a security reviewer (recomposed serial, never parallel with the Critic), CLAUDE.local.md and the project CLAUDE.md budget lines (trim target), documentation/session-summaries/* (batch SS gains the sizing, persistence, and effort lines; the effort line now carries a disposition per fired trigger), any Validator or auditor agent file (semble grant plus the enumeration trigger in its MCP Usage Rubric, scout eligibility), .phanes/scripts/* and .phanes/config.json (re-stamped), .claude/template/agent-definition.md (new fetched artifact) and .claude/template/report.md (source moves to the fetched template library)
• Breaking: no schema breaks (the receipt is byte-identical to v3.2), but TWO behavioural changes an upgrading user should know: the recommended launch effort drops from high to medium, and Critics and architects run cooler by default than v3.2.1 (baseline instead of pinned high/xhigh), lifted per step only when a named trigger fires. Founder-accepted trade against their own performance testing. /phanesupgrade rewrites agent frontmatter in place.
• Verify: .phanes/config.json contains "phanesVersion": "3.3"; the orchestrator agent file mentions the look-ahead block, the four clamps, the resume match rule, and the resolution table; the architect agent file mentions batch_recommendation; the Critic agent file mentions the five self-fix bounds; any security-review agent file states it runs only after the Code Critic returns pass, exactly once per step with no re-dispatch or resume within that step, and that its bounded self-fix is terminal; no workflow in .claude/workflows/ places a security reviewer in the same parallel stage as the Critic; every auditor or Validator agent file lists semble and states the enumeration trigger; the orchestrator agent file states MUST consider / MAY decline / MUST record and the disposition-per-fired-trigger effort line; grep "effort:" .claude/agents/<projectSlug>-*.md returns nothing; .claude/template/agent-definition.md and .claude/template/report.md each carry the phanes-template v3.3 <name> stamp within their first two lines

---