Refactor

---
name: refactor
position: both
description: 'Improve the internal quality of a named code target — structure, duplication, naming, complexity — without changing its external behavior or the product model, proving behavior is preserved before it lands. Pins current behavior first (characterization tests where coverage is thin), presents a refactor plan at a single human checkpoint, then refactors and verifies independently that the model is untouched, tests are green before and after, and no test was weakened. The /refactor command in the ProductOS command model. Use when code needs to get better on the inside without changing what it does.'
user-invocable: true
---

# refactor

Given a **refactor target** the user names, improve the code's internal quality — structure,
duplication, naming, complexity — **without changing what it does and without touching the product
model**, and prove behavior is preserved before it lands. Where the target's tests are thin, pin the
current behavior with **characterization tests captured first** (green on the untouched code), so
the refactor has a net to prove against. Present the refactor plan at a single human checkpoint;
after approval the work runs autonomously and lands through review.

**Pipeline position: both.** This play owns only the refactor core (gather → pin behavior →
checkpoint → refactor → verify). The D2 pipeline-position rule
(`standards/rules/pipeline-position.md`) brackets it: `start-change` is injected at the head
(resolve or create the refactor issue, cut the branch off fresh main, optional worktree, init STM)
and the end sequence `commit-change → propose-change → review-change → merge-change` is injected as
the closing chain. This source never hand-rolls issue/branch/PR/merge steps.

## Compiled From

This play was compiled from the refactor ICE (`reference/ice.md`) by play-editor (#466 Batch B;
#467 Batch D turned the Step 5 plan-approval gate off and elevated the behavior-pin, C3, to the
machine precondition). Intent defines constraints (C1–C7) and failure conditions (F1–F8); the
expectation defines success scenarios (S1–S6), a Done means (D1–D3, baked to `stop-condition.yaml`),
and one recovery entry per failure condition. To modify this play, update `reference/ice.md` and recompile with play-editor.
Do NOT edit this file manually — it is a compiled artifact.

## Role

You are the orchestrator. You own the workflow and the step order. You delegate domain work to
agents via JSON contracts over files on disk — never execute domain work directly — and you run the
mechanical checks (scope, model-untouched, behavior-preserved) through bundled scripts.

**Forbidden:** hand-writing the refactor or the plan; editing the product model in any way (C1);
running the verification as the same agent that made the change (the verifier is never the builder);
direct `git`/`gh` commands or codebase analysis in play prose — all issue/branch/PR/merge work comes
via the injected member sub-plays, never hand-rolled here.

**Agent boundaries:**

| Agent | Type | Domain | Skills it invokes | Phases |
|-------|------|--------|-------------------|--------|
| `tech-designer` | domain | Gather the target + its behavior contract + test surface; assess quality issues; draft the refactor plan; author characterization tests where coverage is thin | `map-test-surface`, `detect-test-harness`, `quality-check-scoped`, `author-regression-test` | Gather & Plan |
| `quality-auditor` | domain | Independent verification — run the behavior suite (baseline and post), record the verdicts and the quality assessment | `run-generated-tests-isolated`, `quality-check-scoped` | Pin Behavior; Verify |
| `code-builder` | domain | Perform the refactor from the plan (context-isolated) | — | Implement |
| `project-orchestrator` | utility | Issues (read/comment via `manage-issue`) when needed | `manage-issue` | Gather & Plan |
| `repo-orchestrator` | utility | Self-commit the evidence files | — | Evidence & Close |

Domain agents: 3 (tech-designer, code-builder, quality-auditor) — within the ≤5 budget. Utility
agents: 2 (project-orchestrator, repo-orchestrator) — exempt. The injected member sub-plays carry
their own agents; those are not counted here.

## Pre-flight

| Check | Constraint | Action on Failure |
|-------|-----------|-------------------|
| Resolve working base + config (`.garura/core/config.yaml`) | — | Hard halt — config is required |
| Resolve `stm.base-path`, `ltm.project-target`, `product_base` | C1 | Hard halt |
| A refactor **target** is provided (argument, or a `refactor/`/`feature/` branch names one) | C4 | Hard halt — "No refactor target. Name the code to refactor." |

Resolve the pre-flight facts mechanically with the bundled resolver — the orchestrator captures the
two live reads and passes them in:

```
git branch --show-current
git status --porcelain > <working>/porcelain.txt
python3 scripts/preflight.py --play refactor --config .garura/core/config.yaml \
    --branch "<current branch>" --porcelain-file <working>/porcelain.txt
```

It returns `stm_base`, `ltm_project_target`, `product_base`, `evidence_record`, `platform`,
`branch`, `issue`, `on_default_branch`, `changes_present`. The play keeps the **policy**: a refactor
issue may be new, so the resolved `issue` (when present from the branch) is passed into the injected
`start-change` to resolve; when absent, `start-change` creates the issue from the target.

Right after the resolver, record the session identity stamp's start marker (#463 — soft-fail,
never a halt):

```
python3 scripts/session_stamp.py --phase start \
    --marker "{stm_base}{issue}/status/session-stamp-refactor.json" \
    --cwd "$(pwd)" --branch "$(git branch --show-current)"
```

**Resume check:** if `{stm_base}/{issue}/status/refactor.json` exists, resume — skip completed
steps, reset any in-progress step to pending, continue from the first incomplete one.

## Task DAG

Create ALL tasks via `TaskCreate` immediately after resolving the working base — before any domain
work. The play owns this DAG; agents must not edit its top-level tasks.

```
[T1]  start-change  (injected — position: both, head)   blockedBy: []
[T2]  Gather Target + Draft Refactor Plan                blockedBy: [T1]
[T3]  Pin Behavior (baseline suite green)                blockedBy: [T2]
[T4]  Prepare Inline Checkpoint                          blockedBy: [T3]
[T5]  Human Approval Gate                                blockedBy: [T4]
[T6]  Implement Refactor                                 blockedBy: [T5]
[T7]  Verify (independent)                               blockedBy: [T6]
[T8]  commit-change   (injected — end #1)                blockedBy: [T7]
[T9]  propose-change  (injected — end #2)                blockedBy: [T8]
[T10] review-change   (injected — end #3)                blockedBy: [T9]
[T11] merge-change    (injected — end #4)                blockedBy: [T10]
[T12] Scenario Validation                                blockedBy: [T11]
[T13] Evidence & Close                                   blockedBy: [T12]
```

The implement→verify retry loop wraps T6 and T7 (cap 2); on exhaustion the play re-invokes
`tech-designer` to revise the plan, then resumes. review-change's verdict (T10) gates merge-change
(T11): a reject stops the sequence before merge. Mark each task in-progress before its step and
completed right after its eval passes. No runtime reordering.

## Workflow

### Phase: Start (injected — D2 position: both)

**Step 1 — start-change** · Owner: `start-change` (sub-play) · Depends on: pre-flight
Run the start-of-pipeline member as a sub-play, dispatched with `parent_run_id`. It resolves the
refactor issue (or creates one from the target), cuts `feature/<issue>-<slug>` off fresh main, sets
up a worktree iff config calls for it, and initializes STM:

    {
      "play":          "start-change",
      "parent_run_id": "<this run id>",
      "inputs":  { "issue_number": "<resolved issue or null>", "title_hint": "<refactor target>" },
      "outputs": { "issue":  "{stm_base}/{issue}/evidence/refactor/start/issue.json",
                   "branch": "{stm_base}/{issue}/evidence/refactor/start/branch.json" }
    }

start-change owns its own evals; they are not re-checked here.

### Phase: Gather & Plan

**Step 2 — Gather Target + Draft Refactor Plan** · Owner: `tech-designer` · Depends on: Step 1
Dispatch a JSON contract. The agent maps the target's test surface (`map-test-surface`,
`detect-test-harness`), assesses concrete quality issues against the standards
(`quality-check-scoped`), and — where coverage is thin — authors characterization tests
(`author-regression-test`) that pin the current behavior. It writes the refactor plan and a
before-manifest of the target's test files with their assertion counts:

    {
      "task":   "gather the refactor target, its behavior contract and test surface; assess quality issues; draft the refactor plan; author characterization tests where coverage is thin",
      "inputs": { "target": "<refactor target>", "product_base": "<product_base>" },
      "outputs": {
        "refactor_plan":   "{stm_base}/{issue}/evidence/refactor/refactor-plan.yaml",
        "test_surface":    "{stm_base}/{issue}/evidence/refactor/test-surface.yaml",
        "tests_before":    "{stm_base}/{issue}/evidence/refactor/tests-before.yaml",
        "characterization_added": "{stm_base}/{issue}/evidence/refactor/characterization.yaml"
      }
    }

`refactor-plan.yaml` carries `target_paths`, the named quality issues (duplication / complexity /
naming / structure), the `behavior_contract` (marked unchanged), and the coverage assessment.

**SE-1 (F5/C5):** `refactor-plan.yaml` exists and names at least one concrete quality issue tied to
a standard — not cosmetic churn; `target_paths` is non-empty.

**Step 3 — Pin Behavior (baseline suite green)** · Owner: `quality-auditor` · Depends on: Step 2
Dispatch a JSON contract; the agent runs the target's behavior suite (its existing tests plus any
characterization tests from Step 2) isolated (`run-generated-tests-isolated`) and records the
verdict — this is the "before" proof, and it must be green:

    {
      "task":   "run the target's behavior suite (incl. characterization tests) and record the baseline verdict",
      "inputs": { "test_surface": "{stm_base}/{issue}/evidence/refactor/test-surface.yaml" },
      "outputs": { "baseline_verdict": "{stm_base}/{issue}/evidence/refactor/baseline-verdict.yaml" }
    }

**SE-2 (F3/C3):** `baseline-verdict.yaml` exists and is green (behavior is pinned) before any
implementation. If it is red or absent, apply REC3 — pin behavior first; never proceed to refactor
against an unproven baseline.

### Phase: Checkpoint

**Step 4 — Prepare Inline Checkpoint** · Owner: play · Depends on: Step 3
Read `refactor-plan.yaml` and render the checkpoint summary **inline** in Step 5 — no standalone
brief or HTML artifact is produced.

**Step 5 — Human Approval Gate (class: standard)** · Owner: play · Depends on: Step 4
**This is the single checkpoint (C6) — the agent never skips it on its own judgment; the config
does.** Resolve the gate FIRST per `standards/rules/gate-config.md` (first match wins:
`gates.plays.refactor` → `gates.classes.standard` → `gates.default`; absent ⇒ on). Under #467
Batch D `gates.plays.refactor` is **off** — the human plan-approval is redundant because the
**behavior-pin** (C3) is the machine precondition that carries what the human was protecting:
characterization/behavior tests captured and GREEN before the refactor, GREEN after, and no test
weakened or deleted.

- **off** — do NOT wait. Proceed ONLY behind the behavior-pin wall: `baseline-verdict.yaml` is
  GREEN (Step 3 pinned the behavior) before any implementation step runs. Record
  `gate skipped by config (gates.plays.refactor)` as a Checkpoint Decisions row in the evidence and
  proceed to Step 6. The pin is re-asserted at Step 7 (`preservation.yaml.behavior_preserved: true`
  — green before AND after, no test weakened); a broken pin at either point is a HARD HALT, never
  gated (REC8), and the refactor must not land. If the baseline is not green, do NOT proceed — apply
  REC3/REC8: pin the behavior first.
- **on** — present the plan inline and wait for the typed Tether/Vanish; the agent never skips it on
  its own judgment.

Present the plan inline (rendered whether the gate is on for the human, or recorded alongside the
config-skip row when off):

```markdown
**Refactor Plan: #{issue} — {target}**

**Target**
{target_paths from refactor-plan.yaml}

**Quality Issues Addressed**
{named issues — duplication / complexity / naming / structure — from refactor-plan.yaml}

**Planned Improvements**
{the changes, from refactor-plan.yaml}

**Behavior Held By**
{the behavior contract + the tests/characterization suite that pins it; coverage assessment}

---
Type **Tether** to approve and proceed, or **Vanish** to reject.
```

- `Tether` → proceed to Step 6.
- `Vanish` → halt; write rejection evidence; no implementation occurs.
- else → clarify.

**SE-3 (F6/C6):** no implementation report
(`{stm_base}/{issue}/evidence/refactor/implementation-report.yaml`) exists unless the status file
shows this gate completed — with a `tether_received_at` that precedes the implement step when the
gate is ON, or a recorded `gate skipped by config (gates.plays.refactor)` Checkpoint Decisions row
when it is OFF; the gate resolution is always recorded, never silent.

**SE-10 (F8/C6):** with the gate off, the behavior-pin held across the refactor — no implementation
step ran unless `baseline-verdict.yaml` was GREEN (Step 3), and the run proceeded/landed only with
`preservation.yaml.behavior_preserved: true` (green before AND after, no test weakened; Step 7). A
refactor that proceeded or landed with the pin broken is F8 (REC8) — the machine precondition that
replaced the human approval was not met.

### Phase: Implement & Verify (retry loop, cap 2)

**Step 6 — Implement Refactor** · Owner: `code-builder` · Depends on: Step 5 (Tether only)
First snapshot the product model so Step 7 can prove it untouched:

```
cp -R <product_base>/product-os <working>/model-before
```

Then dispatch a JSON contract carrying only the plan path — never the checkpoint markdown:

    {
      "task":   "perform the refactor per the plan; change code only, never the product model, never behavior",
      "inputs": { "refactor_plan": "{stm_base}/{issue}/evidence/refactor/refactor-plan.yaml" },
      "outputs": { "implementation_report": "{stm_base}/{issue}/evidence/refactor/implementation-report.yaml" }
    }

code-builder must NOT run its own verification (the verifier is never the builder). After the report
is written, the play runs the scope check:

```
python3 scripts/check_refactor_scope.py <refactor-plan.yaml> <implementation-report.yaml>
```

**SE-4 (F4/C4):** `check_refactor_scope.py` exits 0 — every file in `files_modified` is within
`target_paths` or carries a `deviation_justification`.

**Step 7 — Verify (independent)** · Owner: `quality-auditor` · Depends on: Step 6
Dispatch a JSON contract; the agent re-runs the SAME behavior suite against the refactored code,
writes the post verdict + a tests-after manifest, and records a quality assessment naming the
concrete improvements delivered — the verifier is never the implementer:

    {
      "task":   "re-run the behavior suite against the refactored code; record the post verdict, the tests-after manifest, and the quality assessment",
      "inputs": { "test_surface": "{stm_base}/{issue}/evidence/refactor/test-surface.yaml",
                  "baseline_verdict": "{stm_base}/{issue}/evidence/refactor/baseline-verdict.yaml" },
      "outputs": { "post_verdict":   "{stm_base}/{issue}/evidence/refactor/post-verdict.yaml",
                   "tests_after":    "{stm_base}/{issue}/evidence/refactor/tests-after.yaml",
                   "quality_verdict":"{stm_base}/{issue}/evidence/refactor/quality-verdict.yaml" }
    }

Then the play runs the two deterministic guards:

```
python3 scripts/check_model_untouched.py --before <working>/model-before --after <product_base>/product-os
python3 scripts/check_behavior_preserved.py \
    --baseline <working>/.../baseline-verdict.yaml --post <working>/.../post-verdict.yaml \
    --tests-before <working>/.../tests-before.yaml --tests-after <working>/.../tests-after.yaml \
    --out "{stm_base}/{issue}/evidence/refactor/preservation.yaml"
```

The `--out` flag makes the behavior guard write the **machine preservation record** (C7/#464) —
`preservation.yaml` with `behavior_preserved: true|false`, `baseline_green`, `post_green`, and the
failure list. This record, not prose, is what the close's stop-condition gate (D3) reads.

**SE-5 (F1/C1):** `check_model_untouched.py` reports PASS — the product-os tree is byte-identical
before and after; the refactor wrote no product-model file.
**SE-6 (F2/C2):** `post-verdict.yaml` is green and `refactor-plan.yaml.behavior_contract` is marked
unchanged — the observable contract is preserved.
**SE-7 (F3/C3):** `check_behavior_preserved.py` reports PASS — green before and after, and no test
file removed or weakened (assertion counts did not drop).
**SE-8 (F5/C5):** `quality-verdict.yaml` names at least one concrete quality improvement delivered
(duplication / complexity / naming / structure) against the standards — the change is a real
improvement, not churn.
**SE-9 (F7/C7):** the behavior guard wrote `preservation.yaml` with `behavior_preserved: true` as
machine fields — green before AND after, no test weakened — and the close's stop-condition verdict
reads held before the run may close COMPLETED; preservation asserted only in prose fails this eval.

Retry semantics: all guards PASS → proceed to the end sequence. A guard FAIL with retries remaining
→ re-run Step 6 → Step 7. On exhaustion (cap 2) → re-invoke `tech-designer` to revise the plan, then
resume; it does not halt blindly. A behavior-change fail (SE-6) that is actually wanted is not a
refactor — apply REC2 (route to /fix or /implement).

### Phase: End sequence (injected — D2 position: both)

Each member runs as a sub-play dispatched with `parent_run_id` (emits only its own C1 evidence; this
play's close absorbs it). Each resolves its own context from the branch and config; this play passes
no hand-rolled git/PR/merge logic.

**Step 8 — commit-change** · Owner: `commit-change` (sub-play) · Depends on: Step 7 (all guards
pass) — commit the refactor grouped by concern with conventional messages referencing the issue; no
push.

**Step 9 — propose-change** · Owner: `propose-change` (sub-play) · Depends on: Step 8 — run the
scope-and-quality self-review, push the branch, open the PR carrying the review and the issue
reference.

**Step 10 — review-change** · Owner: `review-change` (sub-play) · Depends on: Step 9 — run the
diff-scoped quality check, classify by the severity taxonomy, post an approve/reject verdict. A
reject stops the sequence before merge.

**Step 11 — merge-change** · Owner: `merge-change` (sub-play) · Depends on: Step 10 (approve
verdict) — merge the PR, switch to main and pull, delete the feature branch (local + remote).

    {
      "play":          "<commit-change | propose-change | review-change | merge-change>",
      "parent_run_id": "<this run id>",
      "inputs":  { "issue_number": "<resolved issue number>" },
      "outputs": { "result": "{stm_base}/{issue}/evidence/refactor/end/<member>.json" }
    }

### Phase: Scenario Validation

**Step 12 — Scenario Evals** · Owner: play · Depends on: Step 11
- **SCE-1 (S1 — developer, well-tested target):** the baseline verdict is green, the post verdict
  (same suite, independent run) is green, `check_model_untouched.py` PASS, and `quality-verdict.yaml`
  names at least one concrete improvement.
- **SCE-2 (S2 — developer, thin-coverage target):** `characterization.yaml` records characterization
  tests captured before implementation, green in the baseline verdict, and green again in the post
  verdict.
- **SCE-3 (S3 — reviewer, no model change):** `check_model_untouched.py` reports PASS over the
  before/after snapshots.
- **SCE-4 (S4 — reviewer, no behavior change):** `check_behavior_preserved.py` PASS and the plan's
  `behavior_contract` is marked unchanged.
- **SCE-5 (S5 — developer, the checkpoint):** the Step 5 summary carries the target, the named
  quality issues, the planned improvements, and how behavior is held; no implementation report has a
  timestamp preceding the recorded approval.
- **SCE-6 (S6 — QA engineer, no weakening):** `check_behavior_preserved.py` finds no test file
  removed and no file's assertion count dropped between `tests-before.yaml` and `tests-after.yaml`.

### Phase: Evidence & Close

Closes with the **Standard Play Close** — the canonical three-table delivery report, not prose. See
`standards/rules/play-close.md`.

```bash
# --- Standard Play Close (canonical; see standards/rules/play-close.md) ---
# Path tokens resolved at pre-flight (resolve here if not already):
#   ltm_project_target  = yq '.ltm.project-target' .garura/core/config.yaml
#   refactor is project-scoped:
#     evidence_base="${stm_base}${issue}/evidence/refactor/"   ; slug="#${issue}"
evidence_template=$(cat "${ltm_project_target}standards/templates/evidence-file.md")
delivery_template=$(cat "${ltm_project_target}standards/templates/delivery-report.md")
ts=$(date -u +%Y%m%d-%H%M%S)
evidence_dest="${evidence_base}${ts}.md"
mkdir -p "$(dirname "$evidence_dest")"
# Session identity stamp (#463) — close phase; start phase ran at pre-flight
session_stamp=$(python3 scripts/session_stamp.py --phase close \
    --marker "${stm_base}${issue}/status/session-stamp-refactor.json")
# Stop-condition gate (#464) — Step C0: this play carries a baked manifest, so the
# gate is LIVE. Evaluate the Done means against the run's STM as the close's
# authoritative input.
python3 scripts/check_stop_condition.py \
    --manifest "<play-dir>/stop-condition.yaml" \
    --base "${stm_base}${issue}/" \
    --out "${stm_base}${issue}/status/stop-condition-refactor.yaml"
sc_exit=$?   # 0 held · 1 unmet · 2 error
```

**Step C0 — bind the verdict.** `sc_exit == 0` (held) permits `status: COMPLETED`.
Anything else closes `HALTED` with `exit_reason: stop_condition_unmet` and the evidence's
Stop Condition section names every unmet clause. An unevaluable verdict is never a pass.

**Step C1 — Write evidence file.** Gated by the resolved `evidence.record` flag (per-play
`evidence.plays.refactor` first, else global `evidence.record`, else record). When false, skip the
write and record `evidence skipped (record=false)` in the report's pointer line. Otherwise fill the
`evidence-file.md` slots (play `refactor`, run_id `refactor-${ts}`, issue, started_at/completed_at,
status per C0, exit_reason, artifacts: refactor-plan / test-surface / baseline verdict / characterization
/ implementation report / post verdict / quality verdict / model + behavior guard results incl.
`preservation.yaml` / PR + merge SHA / branch status; step + scenario eval results; checkpoint decision
(incl. any `gate skipped by config` row); commit reference; the session identity stamp fields from
$session_stamp (#463): session_id, ledger_file, ledger_start_offset, ledger_end_offset (null when
unresolved — never blocks the close); and stop_condition per C0 with the Stop Condition section
filled) and write to `$evidence_dest`. Do NOT hand-author the body. Then dispatch `repo-orchestrator` to self-commit only
the listed evidence files with message `chore(stm): record refactor evidence for #{issue}`
(non-blocking — a commit failure logs a warning, never halts).

**Step C2 — Render delivery report.** Also render the **Next** line: resolve this play in `standards/rules/pipeline-next.md` and emit `**Next:** /<command> — <why>. Or run /next to see all recommended actions.` (only /next pointer, or omit, when the mapped command is null), per `play-close.md`. Fill the `delivery-report.md` slots and output it:
`## refactor Delivered — #{issue}`, the Run Summary table, the Pipeline Steps table from the task DAG
(T1–T13, including the injected start/end members), the Artifacts Produced table, Next Steps (only
real follow-ons), and a pointer to `$evidence_dest`. Always emitted; never gated. When this play
itself runs as a sub-play (`parent_run_id` present), skip C2.

```bash
# --- end Standard Play Close ---
```

## Scenario Validation

| Scenario | Persona | Eval |
|----------|---------|------|
| S1 — well-tested target | developer | SCE-1 |
| S2 — thin coverage | developer | SCE-2 |
| S3 — no model change | reviewer | SCE-3 |
| S4 — no behavior change | reviewer | SCE-4 |
| S5 — the checkpoint | developer | SCE-5 |
| S6 — no weakening | QA engineer | SCE-6 |

## Recovery

One entry per failure condition. The injected member sub-plays own their own recovery; the entries
below cover this play's refactor core.

| For | Trigger | Direction | Handoff |
|-----|---------|-----------|---------|
| F1 | a product-model file was added, removed, or changed | revert the product-model write and restore product-os to the pre-refactor snapshot; a refactor changes code only | autonomous |
| F2 | external behavior changed — an API, input→output, or side effect differs | revert the behavior-changing edit; if the change is actually wanted it is not a refactor — route it to /fix or /implement | human |
| F3 | a test was weakened/deleted, or behavior is unproven (baseline or post not green) | restore the test to its prior strength and re-run; where coverage was thin, capture characterization tests first and prove green before and after | autonomous |
| F4 | a modified file lies outside the declared target with no justification | restrict the change to the target, or record the deviation justification, before the close | autonomous |
| F5 | the change is cosmetic churn with no real quality gain | re-scope the refactor to a concrete quality issue named against the standards, or drop it | human |
| F6 | a code change was made with no completed checkpoint preceding it | hold for the single human Tether/Vanish before any implementation step runs; revert any premature edit | human |
| F7 | the run is about to close COMPLETED with the Done means unmet (a missing plan or baseline artifact, or preservation asserted in prose with no machine record) | produce the missing artifact — re-run the behavior guard with `--out` so `preservation.yaml` carries the machine fields — then re-evaluate the stop condition; the close stays HALTED until the verdict reads held | autonomous |
| F8 | with the plan-approval gate off, a refactor proceeded or landed without the behavior-pin holding (behavior suite not green both before and after, or a test weakened/deleted) | restore the behavior-pin — re-capture or repair the characterization suite to green on the pre-refactor code and restore any weakened test to its prior strength — re-run the behavior guard, and do not land until green before AND after | human |

At Level 4, `intent-resolver` runs the autonomous entries without a human; the four human entries
always escalate. The implement→verify retry loop is capped at 2, then tech-designer re-plans; resume,
never halt blindly.

## Pause and Resume

Steps run top to bottom. Resolve the issue number from the branch name on entry, check the status
marker at `{stm_base}/{issue}/status/refactor.json`, skip completed steps, reset any in-progress step
to pending, and continue from the first incomplete one. A fresh start with no marker runs everything
and creates the marker at Step 1. The injected member sub-plays (`start-change` and the end sequence)
are themselves resumable and never duplicate an issue, branch, PR, or merge on a re-run.

## Compilation Metadata

| Field | Value |
|-------|-------|
| fingerprint | sha256:34b5741606ac28b74d43f0410ebdd2fe49d9b0c4be109ec336532a2b73601498 (of `reference/ice.md`) |
| compiled_by | play-editor (#466 Batch B; #467 Batch D — Step 5 gate off + C6 gate-resolution/behavior-pin + F8/REC8/SE-10) |
| pipeline_position | both (start-change head; commit-change → propose-change → review-change → merge-change tail) |
| workflow_structure | A (single checkpoint — gate off under #467 Batch D, the human plan-approval replaced by the behavior-pin machine wall, C3/C6; with retry loop around implement + verify, cap 2) |
| stop_condition | stop-condition.yaml (D1–D3), gate live at Step C0 |
| domain_agents | 3 (tech-designer, code-builder, quality-auditor) |
| utility_agents | 2 (project-orchestrator, repo-orchestrator) |
| skills_reused | map-test-surface, detect-test-harness, quality-check-scoped, author-regression-test, run-generated-tests-isolated |
| member_subplays | start-change, commit-change, propose-change, review-change, merge-change |
| scripts | 6 (preflight, check_refactor_scope, check_model_untouched, check_behavior_preserved — writes the machine preservation record, check_stop_condition — Done-means gate, session_stamp — #463 identity stamp) |
| step_evals | 10 (SE-1…SE-10; SE-10 covers the gate-off behavior-pin precondition F8/C6) |
| scenario_evals | 6 (SCE-1…SCE-6) |
| recovery_entries | 8 (one per failure condition; 4 autonomous / 4 human) |