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.
• Byte-order marks on write, at four call sites. Every generated file is now written without one.
• Encoding on read. A header-detection read omitted its UTF-8 flag, garbling non-ASCII documentation headers in the generated index while leaving the source file untouched.
• Case-insensitivity, in two forms. phanes new-file CORE ... was refused on one platform and silently accepted on the other. Separately, a variable-name collision crashed the index script outright on the first documentation folder over 100 files.
• Unguarded JSON parsing across the Windows library. A stray trailing comma in your config produced a raw stack trace and locked the project out of its only sanctioned file-creation path. Every consumer now guards the parse, and each degrades honestly rather than uniformly.
• "Cannot read" was reported as "absent" or as a clean zero at several sites, including an unreadable file reporting 0 chars [OK]. Each site now names the file and keeps going instead of abandoning the rest of the tree.
• loc-check exited with an error outside a git repository, breaking the library's own contract that advisory scripts never fail the caller.
• The two platforms disagreed on a malformed config. macOS and Linux could not tell an unreadable config from an unset key, so the module guard silently turned itself off. A per-key detector now refuses when a key the script actually reads is present but unreadable.
• new-file wrote outside the repository and reported success, on both platforms. Only the docs branch had a containment guard; source and tests had none, so a path with .. in it created a real file next to your repository and exited clean. A root gate now runs first on every target.
• docRoot was honored inconsistently. One script never read the key its siblings had honored since v2.6, so a docs file landed at the repository root. A trailing slash in the value separately leaked into derived paths.
• Index rotation sorted by filename rather than modification time on macOS and Linux, contradicting both the spec and its own header comment.
• Excluded documentation trees were only half-excluded, still flagged as missing an index and still linked to index files the exclusion guarantees can never exist.
• Cross-platform message and path parity, closing the last cosmetic divergences between the two platforms.

---

Upgrading

Already running an older Phanes? Do not just re-run /phanes. Install PhanesUpgrade.md as /phanesupgrade and run that instead. It works on a dedicated branch behind an evidence-verified checklist, preserves everything your project has accumulated, and leaves the merge to you. Run it on Opus 5, since it performs file surgery on knowledge your project cannot re-earn if it is lost.

Two breaking changes, both intentional: phanes new-file now refuses an unknown module name (only when your config actually lists modules) and refuses a docs target that resolves outside your documentation root. PhanesUpgrade.md covers both.

Full technical detail, defect by defect, is in Changelog.md.