Refactoring/design loop (multi-agent)

You are the orchestrator. Do not enumerate or trace code yourself - dispatch session-blind workers, persist their artifacts, and hold the gates. No code is written or edited until the design is approved at the Phase D gate.

The roles: refactor-cartographer, refactor-tracer, refactor-surveyor (lighter mode), refactor-conformance-auditor. List your available agent roles; if they are missing, tell the user to run scripts/install-codex.sh from the plugin, then either stop or (with the user's consent) run the phases yourself in this context.

Step 0 - Resolve target and state

• Target: a ticket id or an area description. Slug it (e.g. yb-1234).
• State file: .episteme/DESIGN-<slug>.md at the repository root (create .episteme/ if missing). Codex has no reload hook: re-read the file at the start of every session.
• If it exists, route on its frontmatter - the file is the source of truth, never conversation memory: status: done → nothing to resume; status: blocked → restate the blocker and ask; status: awaiting-approval → re-present the design at the Phase D gate; status: active → resume at the phase in phase:.
• If not, create it with frontmatter (target, sources - where the request came from, phase: R, status: active, design_revision: 0) and sections Why, References, Map, Traces, Probes, Design (approved), Decision log, Deferred, Todo, Review findings. Keep the frontmatter current and flush worker artifacts to the file the moment they return. Decision log and Deferred are append-only.
• Fill Why and References before Phase R, while the request is still fresh. They are the only sections a later reader cannot reconstruct from the code, and a target line is not a problem statement. Why is prose, not a list: the defect or goal in the reader's terms, what triggered the loop, why it is worth doing now rather than later, and what breaks if nothing changes. A loop that cannot state its problem in a paragraph should not be spending a worker fan-out on a map. References is a provenance table: ticket and sibling ticket ids, the review or PR threads, prior QA or design files, the contract/spec source, vendor docs or live schema fetched, probe artifacts, and the host-repo rule sections applied. Cite them as ids and paths, not as bare claims - "the reviewer asked" is unusable six weeks later. Both are stable: revise them only when the problem itself changes, and never to make the design that emerged look like the one that was intended.
• Invariant pack: extract the 5-15 lines of project-specific design invariants relevant to the target (CLAUDE.md sections, architecture docs). Workers receive this pack and artifact data only - never conversation narration; their blindness to the session is the anti-anchoring mechanism.

Step 1 - Phase R: recall

State to the user, in 3-5 bullets, the problem from Why in one line, the standing rules, plus anything in the Decision log: fix the invariant, not the instance; dataflow over references (what value reaches this branch during an outage, not who uses this type); distrust names after changing behavior; empirical before architectural.

Step 2 - Phases E+T: enumerate and trace

Lighter mode for small targets (one service, a handful of paths; when unsure run the full pipeline): spawn a single refactor-surveyor that maps and traces in one pass. It reports ESCALATE: <reason> when the area turns out bigger than one pass should carry - then rerun the full fan-out.

Full mode: spawn refactor-cartographer - one per service, in parallel - with repository root, target, invariant pack, and scope hints. Then refactor-tracer per path group the cartographers propose, with the map rows in scope.

Either way: write the map into Map and the hop-chain tables into Traces verbatim, advance phase, and show the user the map and the anomaly list. The map is the scope: a touchpoint discovered later means the map was wrong - update the map first.

Step 3 - Phase P: probe

Where the design depends on external/vendor behavior, verify it empirically before designing - yourself, in the main session (probes may need credentials or VPN the workers must not have). A path that cannot be produced gets a ready-to-run skipped test, never an assumption. Persist results in Probes.

Step 4 - Phase D: design gate (STOP)

Write the design in prose: the invariant being established, type/structure changes, the full touchpoint list with what changes at each, alternatives with a recommendation. Check it against Why before presenting: if the design no longer answers the stated problem, one of the two is wrong, and saying which is part of the presentation rather than something to quietly reconcile. Set status: awaiting-approval, present it, and stop with exactly: 1. Approve and continue / 2. Approve and stop (a fresh session resumes at Phase I from the file alone) / 3. Revise. On approval record the design under Design (approved) inside a <frozen-after-approval> fence, log the decision, derive Todo (one item per touchpoint), set phase: I, status: active. The fence is locked: only an explicit user decision may change it.

Step 5 - Phase I: implement

Work through Todo, checking items off. Apply the design to every touchpoint. Out-of-scope findings go to Deferred, never fixed inline. If the design must change mid-flight: stop, get explicit user approval, update the fenced design, bump design_revision, then spawn refactor-conformance-auditor with the state-file path and how to produce the branch diff - fix every nonconformance before moving forward. After 3 audit rounds in one loop, halt and escalate. Judge the branch by its diff, never by your memory of what you wrote.

Step 6 - Phase V: verify

Tests assert at the boundary the task is about (serialized payloads, wire status, log text), never only a result type. Prove a regression test fails when the fix is removed. Run non-CI integration suites the change touches. Then run the dotnet-techne-review-pipeline skill on the working diff; record the outcome in Review findings.

Step 7 - Phase F: final mechanical pass

Re-read the full diff hunk by hunk against the host repo's rules: comment style, stale doc labels / log texts / XML summaries, unused usings, docs updated where behavior changed. Set status: done.

Worker restrictions: the refactor-* roles run with sandbox_mode = "read-only" and the plugin's git guard (../../../docs/reviewer-restrictions.md) - they search with their file tools and read-only git, and they stay blind to this session by construction.