Phanes v3.4.1

Patch release, one theme: a "good enough" threshold for every Opus-run role. It answers a field report from a downstream Phanes-managed project. Measured over three consecutive plan steps there, agent dispatches went 8, 13, 17; Critic passes 1, 3, 4; prose produced about 2,450, 3,700 and 7,760 lines; the plan's scope estimate was missed by 3.2x and then 9.5x; and the same "still owed elsewhere" list appeared verbatim in all three session summaries. The reviewers were catching real bugs, so review presence is not the problem. The problem is that the architect, the Critic, the security auditor and the Orchestrator each had a duty to observe and record, and none of them had a rule for when an observation creates no further work. Obligations accrued faster than steps discharged them, and by the third step the chain was producing four lines of review prose per line of code.

Five thresholds close that, each placed where the generated agents are told to restate it. Nothing about chain composition, review presence, the two mandatory verdicts, the security pass's cardinality or the self-fix bounds moves.

Added

• Acceptance criteria are checks, not counts. The architect/designer protocol now states that every acceptance criterion is satisfied by a named test or by a structural check that ignores comments, string literals, docs and test fixtures, and that token-count criteria (X appears exactly N times, no file mentions Y) are forbidden: comments and tests legitimately contain the token, the criterion is unsatisfiable as written, and the chain spends a Critic pass proving that instead of reviewing code. The Critic's protocol gains the matching rule: an unsatisfiable criterion is a plan defect routed to the planning-class agent in one line, never proven at length. Ten of the report's recorded "AC wordings owed correction" items were this class.
• The Reflect loop is bounded at two, then a whole-file rewrite. A step gets at most two Reflect passes by its original producer. A third fix_required is a recycle trigger: the producer is retired and a fresh one rewrites the affected files whole from the current on-disk state and the Critic's findings, reviewed once more, after which the step fails. Rework is always a whole-artifact rewrite, never a delta applied on top of an earlier delta, because a producer patching its own patch without reloading the file is how each loop injected the defect the next pass found (two of the report's three steps had fix-introduced bugs found on pass two and three). Stated in §II, in the Orchestrator's duty (5), in the recycle triggers, in the Failure paragraph and in the orchestrator's self-carrying list.
• Severity ladder and stopping rule for the security pass. Findings are graded CRIT, HIGH, MED, LOW or INFO. Only CRIT, HIGH and MED can return fix_required or create work anywhere; LOW and INFO stay in the report file and are never rehomed to another step, never become a plan amendment, a follow-up step, an invariant elsewhere or a session-summary obligation, and are not re-raised by a later pass. A finding whose preconditions cannot be named as reachable in this codebase is INFO at most. Every security report closes with No further findings at or above MED. or the list of those that remain; a report without that line is returned as incomplete. Stated in §III rule 13, the security specialization's protocol and the Security Review Gate.
• Review reports are files. The Critic writes its Actionable Audit Report to reports/reviews/<date>_<step-id>_critic.md (the security specialization to _security.md, later passes appending a dated section) and returns only the path, the two verdicts and the finding IDs with severities. reports/ is outside the stamped trees by design, so the write needs no phanes new-file and trips no stamp guard.
• Batch SS shape and carry-over rule. A batch session summary is verdicts and pointers, never transcripts: per step the two verdicts, the report paths, the MED-or-above finding IDs with one line each, the applied-diff summary and the Reflect count; then the mandatory record lines; then open items. Soft cap 150 lines; past 200 means a report body was pasted in, and it moves to reports/reviews/. An open item carried across two batches is either scheduled as a plan step (the primary is told in register_lines.blockers) or dropped with a one-line reason, never copied a third time.
• Scope halt at 4x. The architect's batch_recommendation gains a scope_ratio field: the designed scope over the scope the plan step states, in the plan's own unit, n/a where the plan states none. A ratio of 4 or more is a plan defect, not a bigger step: the Orchestrator takes the existing failure path for that step (verdict: fail, failed_step set, blocker scope: design is <R>x the plan's stated scope, split the step) and the primary returns it to planning. Below 4 the existing renegotiation handles it. No receipt schema change.

Changed

• The Critic's tools: grant. It carried a scoped Edit (existing files only, "never Write, never new-file creation"), while §IV had always listed reports/ as the Critic's output directory. Generated agents resolved the contradiction by denying all file creation, so every verdict landed in the session summary, which is why the report's summaries ran 365 to 484 lines. The grant now carries the scoped Edit for the self-fix duty plus Write for reports/reviews/ only (the report file and the handoff digest; never a source, test or documentation file, never phanes new-file). The self-fix bound "never new files" is stated to concern the reviewed tree.
• The Batch sizing: record line gains halted: scope <R>x as a disposition and a trailing scope ratio <R | n/a> field, in both places it is specified.
• Deliberately unchanged. Chain composition at every tier, review presence, the two mandatory Critic verdicts per step, the security pass serial and single-shot after Critic pass, the self-fix bounds (trivial class, soft cap 10, hard cap 20), the batch cap 1 to 3, the receipt JSON schema, the four renegotiation clamps. The report's sixth proposal, a burn-down batch for the frozen "still owed" list, is a downstream project action, not a spec change; the carry-over rule above is what keeps such a list from freezing again.

Installed project impact:

• Affected: .claude/agents/<projectSlug>-orchestrator.md (Reflect cap and recycle trigger, scope halt, SS shape and carry-over rule, the extended sizing line), the Critic agent file (report file duty, Write grant scoped to reports/reviews/, unsatisfiable-criteria rule), the security-review agent file where the roster carries one (severity ladder, stopping line), the architect/designer agent file (acceptance-criteria rule, scope_ratio in batch_recommendation), .phanes/config.json (phanesVersion), all template stamps (phanes-template v3.4.1, fetched pinned to the v3.4.1 tag).
• Breaking: none at the file level. Behaviorally, a LOW or INFO security finding no longer creates a follow-up anywhere, a third fix_required on a step now retires the producer instead of resuming it, and a 4x scope miss now fails the step for re-planning instead of being recorded; an installation left at v3.4.0 keeps the old behavior. Existing plans whose acceptance criteria are token counts are flagged for a one-time architect rewrite by the upgrade, not edited by it.
• Verify: .phanes/config.json contains "phanesVersion": "3.4.1"; the Critic agent file names reports/reviews/ and carries Write in its tools:; the orchestrator agent file states the two-pass Reflect cap, the scope_ratio halt and the 150-line SS cap; the security agent file (where present) carries the five severity grades and the closing line No further findings at or above MED.; the architect agent file forbids token-count criteria and its batch_recommendation schema carries scope_ratio.

Phanes v3.4.0

About this release

Everything below is the accumulated change since v3.3, which is where most installs are sitting. Items marked (v3.3.1) shipped in that patch release; everything else is new in v3.4. If you are already on v3.3.1, read past those markers.

v3.4 also absorbs an entire version that was never published. v3.3.2 was finished on a branch and never tagged, merged, or pushed, so nobody ever ran it and the public history goes v3.3.1 straight to v3.4.0. Its whole content is folded in here.

Two themes. First, Phanes stopped doing its own paperwork by hand. Setting up a project used to mean thirty to fifty tool calls of pure procedure, slightly different every time. Ten new commands do that work now, and re-running /phanes measures what actually moved instead of rebuilding everything. Second, batches finally behave like batches: a group of plan steps runs as one job, instead of quietly spawning the entire review chain again for every single step.

One scope limit, stated plainly: the ten new commands are Windows only in this release. macOS and Linux keep the manual flow they already had, unchanged and fully supported. Nothing is taken away there; it simply does not gain the automation yet.

---

Added

Automation of the setup itself (Windows)

• Eight bootstrap commands covering setup and the update sweep: preflight (the whole pre-flight check in one call), install-templates (fetch, verify, install, merge hooks without clobbering yours, record provenance), scaffold (documentation and test trees, merge never overwrite), ledger (append, status, close, reset for run progress), manifest-write (recompute file hashes instead of doing it by hand), census-diff (stop re-asking what it already knows), update-preflight (the change sensor described under Changed), and hook-verify (reports the hook table and repairs nothing, because repair is a write to your own settings).
• repo-manifest, a source inventory pairing each tracked file with a one-line summary plus the content hash from when that summary was written, so it can report what is new, what changed underneath its summary, and what is gone. Summaries are written lazily by whichever agent just read the file. A large "new" count is never a work order to bulk-read your repository.
• batch-apply, many exact-match edits applied in one call instead of one tool call per change. Undo is a saved copy rather than git, so it needs no clean tree, no tracked files, and no repository at all. A file's byte-order mark and line-ending convention are never changed as a side effect.
• A SessionStart hook, hook-ledger-status, on by default. Silence is the healthy signal: it prints nothing at all unless a previous run died mid-flight, in which case you find out at the start of the next session rather than halfway through it.

Safety and hygiene

• Stale-customization detection. The manifest now records the hash of the template a file came from, separately from the hash of the file on disk. Those answer different questions: one is "did someone edit this", the other is "has upstream moved on since they did". Your customizations are still never overwritten; you simply get one advisory line when the thing you worked around has since been fixed upstream. Motivated by a real project found sitting on workarounds for five bugs that had been fixed the following day.
• A doc_discipline config block: index_exclusions for documentation subtrees you want skipped, and frozen_classes for trees exempt from the size ceiling.
• Two phanes new-file guards (breaking, see below): an unknown module name is refused, and a docs target resolving outside your documentation root is refused.

How plan steps get executed

• Grouped batch execution (v3.3.1). A batch can run as one chain over all its steps instead of one chain per step: one producer turn, one review turn, one apply turn. Three small steps used to cost six spawned turns and now cost two. The verifier runs once at batch close rather than once per step, which is better verification for less spend, not weaker.
• Grouped batching, composed for cohesion (v3.4 rebuilds the above). A batch now runs as one chain over its steps, full stop, which is what a batch was always for. Batches are composed to keep related work together rather than padded out to a step count, so a batch closes at a module boundary instead of absorbing an unrelated step.
• Per-step verdicts and per-step attribution. Even when steps run as one job, the reviewer returns a separate pass/fail verdict for each step, and every individual change is tagged with the step that asked for it, so a failure still names the exact step. This is what makes grouping a scheduling change rather than a review change.
• Producer autonomy on small edits. An agent may decide for itself that an in-scope edit is small enough to just make and report afterwards, instead of a permission round-trip. Size caps are unchanged and every self-edit must still be disclosed.

Changed

• The update run senses before it regenerates. Re-running /phanes now takes one of three branches. Quiet (nothing moved, worktree clean) verifies instead of rebuilding. Delta rebuilds only what the measured changes implicate, naming the sensor that triggered each one. Blind (no git history to measure against) runs the full pass exactly as before, because not knowing is not the same as nothing having changed. This is what makes a habitual re-run cheap enough to actually be habitual.
• An interrupted run now offers a choice. Instead of silently resuming, it reports which phase it died in and asks: resume (still the default) or start fresh, which archives the old record so stale state cannot resurface. A new "unreadable" state asks rather than guessing in either direction.
• File overlap now groups a batch instead of splitting it. The v3.3.1 rule sent a batch back to one full chain per step whenever its steps touched the same files, which split exactly the case where sharing loaded context saves the most. One agent authoring both steps writes one coherent result instead. Splitting a batch now needs a real reason: a step that genuinely needs an earlier step's output already written to disk. Ambiguity now resolves to grouped rather than to split.
• Security review now covers the whole batch. When any step in a batch touches security, one review pass reads the batch's entire change set rather than only the flagged steps, with a separate verdict per step. A security regression usually surfaces in the ordinary-looking step editing the same file, and the reviewer is already holding the batch.
• Rework covers the affected cluster. When part of a batch fails review, the fix and the re-review now cover the failing steps plus anything sharing a file with them, rather than the failing steps alone.
• Model and effort roster flattened. Every agent runs at one fixed effort level, high, set once when you launch the session. Model is the only remaining variation: Sonnet 5 for the roster, Opus 5 for the plan-authoring chain and the security reviewer.
• Model guidance now splits by run type (documentation only, nothing installed changes). /phanes and /phanesupgrade want Opus 5, or Fable 5 if you can afford it; everyday workflow execution stays on Sonnet 5, with Opus 5 as the paid upgrade and Fable 5 for pre-planning. Both prompts now say so at their own top, so a run launched on a lighter session can tell you rather than proceed quietly.
• Phase 5 records the git ref it finished at, which is the substrate the next run's change sensor measures against.
• Not changed, deliberately: preserve-never-overwrite, the propose then review then apply invariant, the always-succeed contract for advisory scripts, and the rule that every judgment call stays with the session rather than moving into a script. Nothing in this release auto-merges a customization.

Removed

• xhigh reasoning effort is retired. There is no hotter setting to reach for. Any project still launching at --effort xhigh should relaunch at --effort high.
• The per-agent effort-delivery bridge is deleted, along with the effort and effort_class frontmatter fields it read. Model is delivered natively by frontmatter; effort is delivered by the session. The removed machinery is preserved verbatim in the repository rather than lost, in case it is ever needed again.
• The elevation mechanism is gone, though its four trigger conditions survive as a record-only obligation, so the tuning signal outlives the spending mechanism it used to feed.
• The tier-based batch gate is gone (replaced). A step's tier no longer decides whether its batch groups, and the old three-condition gate from v3.3.1 (tier, security, file overlap) is replaced by a single condition.
• The "no shared interaction surface" affirmation required of the security reviewer is dropped. Under the new grouping rule the changes in a batch often do share a surface, deliberately, and reviewing that surface is the assignment rather than certifying its absence.

Fixed

Twenty-odd defects across the script library. They are grouped by class rather than one per script, because that is the shape they had: nearly every one was a single mistake replicated across sibling scripts.

• Line counting undercounted on both platforms, by two different mechanisms. On Windows every blank line counted as zero, so a 525-line file with 199 blank lines measured 326 and hid a real ceiling breach. On macOS and Linux a file without a trailing newline was undercounted by one.
• Character counting disagreed with the ceiling it enforces. One emoji cost 4 against the budget on one platform and 2 on the other. Both now count Unicode code points, so any character costs exactly 1 everywhere.
• **Byt...

v3.3.1

Patch release, one correction to plan-batch economics. v3.3 gave the Orchestrator a dial for how many steps a batch covers, and left a second one missing: whether those steps' chains run once per step or once for the whole batch. Three small steps run per-step pay a producer turn, a Critic turn, and an Executor turn three times over for work amounting to a few dozen lines, and the review depth those repeats buy is real at T3 and largely ceremony at T1. Agent Persistence had already deleted the respawn tax on the repeats; this release deletes the repeats. No gate is removed at any tier.

Added

• Grouped Batch Execution. A batch may now run as ONE chain over all of its steps instead of one chain per step: one producer turn, one Critic turn, one Executor turn. A grouped batch of 3 T1 steps runs 2 spawned turns instead of 6; a grouped batch of 3 T2 steps runs 4 instead of 12. close-verifier runs once at batch close on T2 structural work, one phanes regen-registry and one phanes api-diff rather than one pair per step, which is better verification for less spend rather than a weaker one. The designated visual verifier likewise runs once, over the union of the batch's declared viewports and screens.
• The grouping gate, decided by the Orchestrator at triage. A batch groups only when all three hold: every step is T1 or T2 (any T3 step forces per-step); no step is security-triggering (those fire elevation trigger (a) and the Security Review Gate is one pass per step by design, so they earn isolated attention); and the steps' working sets do not overlap, no step editing a file another step in the batch edits and no step consuming another's output. Per-step stays the default, grouping is the exception the gate has to earn, and ambiguity resolves to per-step. The overlap test is judgment rather than arithmetic: the Orchestrator already holds every step body, since tier triage cannot be performed without reading them, and T1 is itself defined by a scope test of the same kind. A step whose scope cannot be bounded is not groupable.
• Per-step Critic verdicts. In grouped mode the two mandatory verdicts are returned once per step, keyed by step id, and a single undifferentiated pair spanning several steps is fix_required on arrival, the same treatment a missing verdict already got. This is what carries the per-step review guarantee through grouping, and it is the clause that makes grouping a scheduling change rather than a review change.
• Per-step Executor checkpointing. In grouped mode the Executor applies the batch's approved diffs in plan order with a checkpoint per step, and on failure stops at the failing step, leaves the already-applied steps applied, and names that step id. failed_step in the receipt therefore stays exact, and §III rule 12's failure handling needs nothing new.
• Reflect over the failing subset. On a mixed verdict the producer is resumed ONCE with the findings for every failing step and the Critic ONCE to re-review that subset only. Steps that passed stay applied and are not re-reviewed: the non-overlap gate is precisely what makes that safe, since a fix to one step cannot reach a sibling's files. The grouped rework counts as one loop against the bounded Reflect cap, never one per failing step.
• Mandatory mode record. Every batch session summary now carries Batch mode: grouped | per-step (<gate condition that failed>), steps <ids>, chain turns <N>. whether the batch grouped or not. A mode decision leaving no trace is indistinguishable from the mechanism not working, the same reason the sizing and effort lines are mandatory.

Changed

• Batch renegotiation gains a fifth clamp. An adopted growth is clamped when the batch is running grouped and the absorbed step fails the grouping gate. A batch is never part grouped and part per-step.
• Deliberately unchanged. The batch cap stays 1 to 3 steps, grouping never earns a wider batch. No tier's chain composition changes, no gate is skipped at any tier, review presence stays universal, and the batch receipt schema is untouched.

Installed project impact:

• Affected: .claude/agents/<projectSlug>-orchestrator.md (restates the grouping gate, the fifth renegotiation clamp, the two agent contracts, subset Reflect, and the mandatory batch-mode line), the Critic agent file (per-step verdict duty for grouped assignments), the Executor agent file (ordered per-step checkpoint duty), documentation/session-summaries/* (batch SS gains the Batch mode: line), .phanes/scripts/*, .claude/template/* and .phanes/config.json (re-stamped to 3.3.1)
• Breaking: none. No schema change, no frontmatter change, no chain recomposition. An installation left at v3.3 behaves exactly as it did, since per-step is the default and grouping only ever engages where the gate passes.
• Verify: .phanes/config.json contains "phanesVersion": "3.3.1"; the orchestrator agent file mentions the grouping gate's three conditions, the ambiguity-resolves-to-per-step rule, and the Batch mode: session-summary line; the Critic agent file states that grouped assignments return verdicts per step keyed by step id; the Executor agent file states that grouped assignments are applied in plan order with a checkpoint per step; .claude/template/agent-definition.md and .claude/template/report.md each carry the phanes-template v3.3.1 <name> stamp within their first two lines

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...

Phanes v3.2.1

A small update that aligns Phanes with the new Claude Opus 5 model.

The Model & Effort rubric now names Opus 5 in place of Opus 4.8 at all three Opus-tier assignments: every Critic at high (xhigh for security-critical or money-critical review), the Orchestrator role at high, and the architect/designer, Synthesizer/Arbiter, high-ambiguity planning and security or monetary design work at xhigh. The use cases behind those assignments have not moved, only the model generation they name, so nothing about how Phanes routes work has changed.

Also in this release:

• The README "How to use" section now recommends launching the session at high reasoning effort (claude --effort high, or CLAUDE_CODE_EFFORT_LEVEL=high), with xhigh for design-heavy runs. Effort is set once at launch and governs the primary session and every sub-agent it spawns.
• The workflow diagram now shows the branch it was missing: a single task, or a plan of 4 or fewer steps, is triaged and run directly, while a plan of 5 or more steps is handed to the ephemeral Orchestrator that batches 1 to 3 consecutive steps and returns a session summary and a short receipt.
• New guidance that the setup performs best when you write a multi-step, phase-grouped plan first and then let the run work through it.
• The script template library is re-stamped to v3.2.1 so the version-pinned fetch path stays in lockstep. Script contents are unchanged.

Upgrading: nothing breaks. An installed v3.2 project keeps working as is and can pick this up whenever convenient by running /phanes, or /phanesupgrade if you prefer the checklist route.

Phanes v3.2

Two operating-discipline fixes and one architecture addition.

Added

• Pinned Directives block: a top-anchored, delete-protected, namespaced block generated as the first content of the project root CLAUDE.md, regenerated every run, crop-exempt but budget-counted. Seeds the per-agent effort trigger and the procedure-precedence rule onto the always-loaded surface.
• Procedure precedence + supersession annotation: current phanes.md and workflow YAML outrank session-summary narrative on any operating-procedure conflict; update runs annotate superseded procedure statements in place, additive only.
• The Orchestrator role: plan runs of 5+ steps execute through an ephemeral per-batch orchestrator agent (1 to 3 self-sized consecutive steps, bounded JSON receipts, one batch session summary), keeping the primary session slim enough to run long multi-phase plans without compaction. Short or explicitly narrowed runs behave exactly as v3.1.

Changed

• The Orchestrator name now refers exclusively to the new role; the agent-spawning grant widens to include it as the sole non-scout exception.
• register-check additionally measures the Pinned Directives block; template library re-stamped to v3.2.
• PhanesUpgrade v2.1 with four new verification items, including workflow currency.

See Changelog.md for the full entry and the installed-project impact block.

Phanes v3.0.1

Patch over v3.0.

Fixed

• Effort-control rubric corrected. Effort frontmatter is honored on no native in-session spawn path (anthropics/claude-code #43083, open; #64033 and #65598 closed as duplicates of it). The only working lever is session-level effort set at launch with --effort or CLAUDE_CODE_EFFORT_LEVEL, never /effort or /model mid-run, since both leak to the global settings file (#57618, #49076).

Added

• Per-Agent Effort Delivery, a temporary CLI-spawn bridge. The session launches at the orchestrator's peak need (high by default, xhigh for design-heavy runs). To lift a heavy archetype above the baseline, the orchestrator spawns it as its own process, claude --bg "<prompt>" --agent <name> --effort <level> --permission-mode <mode>, monitored with claude agents --json and collected with claude logs <id>. Upward only. The subsection is removed when #43083 ships.

Changed

• Template library re-stamped to v3.0.1 with no script change, so the fetch-time version check matches the prompt stamp.

Phanes v3.0

v3.0 (2026-07-20)

Major version. It adds a consent layer over capability discovery, renames the close-time verifier to match its real duties, makes the CLI reachable from any shell, and re-grounds the model rubric on a tier-first policy with forward-compatible effort control. All changes are to phanes.md and the template library; deployed projects adopt them on their next update run.

Added

• Capability Census & Consent Gate (Phase 0). The installed-capability pre-flight is now a census that additionally probes each MCP server's auth/health, and a mandate may exist only for a capability the census verified reachable, closing the failure mode where a "use semble first" mandate coexisted with an unauthenticated semble for a whole session. On a setup run it asks one per-item AskUserQuestion (multiSelect) listing every detected capability by name: the Phanes-standard set (context7, deepwiki, serena, semble, frontend-design) pre-selected and marked recommended, every other detected capability listed unchecked by its detected name only. The selection persists to .phanes/config.json (capabilities.selection[]). Update runs re-census and diff: no change is silent, a delta asks only about the delta, a removed-but-mandated capability has its mandates stripped and recorded. Non-interactive runs default to the standard set and never block.
• Cross-shell CLI entry point (cli.js). A small Node launcher installed on every platform; agents invoke node .phanes/scripts/cli.js <cmd>, which resolves identically in PowerShell, cmd, and Git Bash and forwards to the platform dispatcher. This fixes the failure where a bare phanes was "command not found" in a sub-agent shell. A generated project cannot know which of the three shells Claude Code will use on Windows, and each rejects a different platform launcher. phanes <cmd> stays shorthand in the document; the invocation is stated once and carried in the agent template.
• effort: frontmatter in the generated agent template. Forward-compatible: honored on CLI dispatch, ignored on the in-session Task-tool spawn path until anthropics/claude-code #43083 lands (thinking directives remain the in-session depth lever). Omitted for haiku, which exposes no effort dial.
• mcpServers: per-agent allowlist in the agent template, gated by the consent selection and Phase 3 matching. When an agent is granted more than ~3 non-standard capabilities, their usage rules move into one generated capability-map skill (progressive disclosure) instead of bloating the always-loaded persona.
• No Inline Secrets (§III). Agents never inline a connection string, key, or token on a command line; command lines are logged verbatim by transcripts, OTel, and console captures, and credentials are read instead from the environment or a gitignored file. Carried in the operating-protocol template.
• Companion Tool Detection. The census recognizes a /metis command; when present, update runs invoke the Metis session-audit companion (harvest, ledger verification, adherence audit) and consume its report. No hard dependency in either direction.

Changed

• api-monitor renamed to close-verifier across the chain rules, archetype table, roster requirement, tier tables, and report template, with a rewritten duty list reflecting its real role: the independent close-time verifier that re-derives the API baseline, independently re-runs the build/typecheck (never trusting a producer's self-report), reconciles applied-vs-approved, and observes the hot-file budget. Its independence from the architect/designer is now a stated non-merge invariant. Deployed projects keep the old agent name until their next update run regenerates the roster.
• Model & Effort rubric re-grounded, re-stamped 2026-07-20. Selection is tier-first, effort-second: a stronger model at moderate effort beats a weaker model at its ceiling, and past ~4 to 8 agent steps does so for fewer tokens. The anti-pattern is recorded explicitly: maxing effort on a smaller model is not a substitute for a tier bump.
• Living-document budget discipline generalized. The register's demote-on-close rule now extends to any living document carrying a running log/status/amendment section: closed entries collapse to one-line pointers in the same change set, running lists are capped, doc-check flags growth. A Single-Writer corollary keeps close-time summaries with the agent that already holds the content, rather than paying to re-inject context into a fresh writer.
• T1/MCP boundary clarified. A task whose verification inherently requires a service MCP (querying live external state) is not a T1; it promotes to T2, removing the contradiction of a T1-labelled agent making heavy MCP calls.
• Template library re-stamped to v3.0 (manifest version, sanity stamp, every template stamp, CHECKLIST), and cli.js registered in the manifest, so the fetch-time version check stays satisfied.

Phanes v2.6.1

v2.6.1 (2026-07-17)

Fixed

• Update runs reconcile an existing script library instead of overwriting it. v2.6's "acquire, do not author" step (Phase 2.5 Step 4) was written for a fresh install: an absent script library is filled from tested templates. On an update run a working library already exists, and it is not always a stale copy of the shipped templates. It may have been generated in the project's own language by an earlier version, kept as a recorded per project edit, or deliberately rewritten with a project specific safety behavior. Fetching over such a library traded a known good, project shaped set of scripts for a generic one and replaced the phanes dispatcher with a different runtime, orphaning the scripts it routes to. Step 4 now branches on .phanes/config.json and the files on disk: an absent library is fetched, a library already in the shipped runtime is re-fetched so upstream fixes propagate, and a library authored in another runtime or carrying a project specific guard is preserved and verified against the in document specifications rather than replaced. A real update run hit exactly this: a project with a script library authored in its own language, and a guard on its registry regeneration, would have had that library swapped for generic shell templates. The reconcile path makes preservation the defined behavior instead of a hand judged exception.

Added

• templates.source gains a "preserved" value. .phanes/config.json now records "preserved" alongside "fetched" and "generated", so an update run that keeps a project shaped library instead of fetching over it stays legible to later runs, and swapping a preserved library for the shipped templates becomes an explicit user decision rather than a silent side effect.

Changed

• Template library re-stamped to v2.6.1 with no change to script behavior, so the manifest version, the sanity stamp, and every template stamp stay equal to the prompt stamp, as the acquire step's version check requires.

Phanes v2.6

v2.6 (2026-07-17)

Added

• Script template library, fetched instead of regenerated. The ten scripts that do not depend on the project's language (new-file, loc-check, doc-check, register-check, doc-index, module-list, list-apis, the phanes dispatcher, and the two hooks hook-stamp-guard and hook-size-check) now ship as tested reference implementations under templates/ in the distribution repository, in both a Windows variant (.ps1 plus a .cmd shim) and a POSIX shell variant. Phase 2.5 Step 4 fetches them pinned to the run's own version tag, sanity checks every file, installs them into .phanes/scripts/, and works through a shipped CHECKLIST.md. A bug fixed once in a template is fixed for every future install, which removes the largest source of variance between installs.
• No path substitution. The fetched scripts take no per project editing. Each one finds the project by walking up from the working directory to .phanes/config.json and uses only paths relative to that root, so there is nothing to adapt and nothing to get wrong. Project values (module list, comment syntax, documentation root, stamped trees) are read from config.json at run time; the size numbers stay baked constants. config.json gains commentSyntax, docRoot, stampedTrees, and a templates provenance block that records the version installed and whether it was fetched or generated.
• Graceful fallback, no new dependency. If the fetch fails (offline, rate limited, tag missing) or the manifest version does not match the running prompt, the install generates the scripts from the Step 4 specifications exactly as earlier versions did, and records the failure. Those specifications stay in phanes.md in full: they are both the contract the shipped templates are audited against and the offline definition. regen-registry and api-diff stay generated per project, since their extractors are specific to each language.

Fixed

• Enforcement hooks no longer block when run by hand. Both hooks read the tool-call JSON from stdin, which the harness always pipes in. Invoked directly in a terminal with nothing piped, they used to wait on that read until interrupted; they now detect a terminal on stdin and exit 0 immediately, so a manual run can never leave an interpreter waiting.
• Hook commands can no longer be anchored at the wrong project. A real install wrote its Step 4b hook commands as an absolute path into the Phanes repository instead of the target project, so the enforcement hooks policed the wrong tree and never fired where they were meant to. Step 4b now binds hook commands to their project relative form, copied verbatim, and adds a mechanical read back of the merged .claude/settings.json: every Phanes hook command must contain .phanes/scripts/ and must not contain a drive letter or a leading slash. Update runs rewrite any absolutized hook command back to its relative form and report the repair. The template scripts make the failure structurally impossible on the fetch path, since they carry no absolute paths at all.