dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-retune/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/ce-retune/references/baseline-mining.md

@@ -0,0 +1,122 @@
+# Phase 1: mine the archive
+
+Zero model cost. Everything here reads files that already exist on disk. Do not run the harness in this phase. Phase 2 is where the first paid runs happen (`references/noise-floor.md`).
+
+An archive is usually an order of magnitude larger than the experiment you can afford this week. In the engagement this method came from, 745 archived runs were on disk and 458 carried usable traces. That is more evidence than any deliberate sample, sitting unread.
+
+## What the archive must contain
+
+Per run, in whatever form the harness stores it (JSONL transcript, structured log, a directory per run): the ordered tool-call trace, token counts, timestamps, and the final assistant message. If it stores only a pass/fail verdict, the archive is not minable. Say so and go to Phase 2.
+
+Find the archive by asking the harness where it writes run output, or by locating the directory it appends to after a run. Do not assume a schema. Read one run end to end and derive the field paths before writing any extractor.
+
+## Build the phase-marker map first
+
+`phase_trace`, `process_followed`, and the terminal-phase cross-tab are all functions of one artifact that does not exist yet: a table mapping each phase of the corpus's own workflow to the observable side effect that proves it ran. Derive it before writing the extractor, by reading the corpus's spine. Do not infer phases from the logs; that is circular.
+
+| Phase name, in spine order | Marker in the trace |
+|---|---|
+| `<phase>` | the reference file it must read, the helper it must dispatch, the artifact path it must write, or the sentinel it must emit |
+
+Rules: one marker per phase minimum, each a **tool call or a file that exists**, never a phrase in the assistant's prose. A phase with no observable marker cannot be scored. Record it as unobservable rather than assuming it ran, and carry that list forward. It is the same list Phase 2 needs for the probe's unentered phases and Phase 5 needs for the unmeasured paths. Keep the map in the same directory as the extractor. Every later re-run and every re-scored table depends on it.
+
+## Extract one row per run
+
+Write a script, not a per-run read. Reading 458 transcripts by hand is the failure mode this phase is supposed to avoid.
+
+| Field | How to derive it | Why it pays for itself |
+|---|---|---|
+| `run_id`, `model`, `settings` | harness metadata | the stratification keys; without them the whole table is one undifferentiated blob |
+| `session_id`, and the child id on every dispatch | whatever the trace calls the conversation and the spawned agent | the only way to tell a real runtime boundary from a fictional one. `references/halt-taxonomy.md` opens on this comparison; extract it here or that diagnostic has no data |
+| `phase_trace` | ordered list of which corpus phases ran | tells you **where** it stopped, not just that it did. This is the field that localizes the defect |
+| `marker_present` | boolean; the corpus's own terminal marker in the final message | the corpus's own claim of completion, separable from whether it is true |
+| `output_tokens` | harness token accounting | the variance channel; spread here is a stronger signal than the mean |
+| `wall_clock_min` | last timestamp minus first | useless alone, required as a denominator |
+| `helper_dispatches` | count of subagent/helper dispatches | how far the run got, and how it got there |
+| `max_parallel_dispatch` | most dispatched in a single message | separates fan-out from serial plodding; a corpus that mandates parallelism and never gets it is a finding |
+| `final_message` | verbatim, untruncated | halt language lives here and nowhere else. Do not summarize it during extraction |
+
+Derive `phase_trace` from **artifacts, not claims**. A phase ran if the trace shows its side effect: the reference file it must read, the helper it must dispatch, the file it must write. A run asserting "Phase 3 complete" in prose is not evidence. The defect class you are hunting is exactly runs that report success without doing the work.
+
+## Derived metrics
+
+**Tokens per minute is the metric that separates working from stalling.** `output_tokens / wall_clock_min`. Compute it for every run and look for bimodality before looking at anything else.
+
+In the engagement, healthy cells ran 10-12k tokens/min; every failing cell sat at 1.5-3.8k. A run burning hours at 2k tok/min is not thinking hard. It is waiting, because the prose told it a second party would respond. Duration alone cannot show this. A long successful run and a long stalled run look identical until you divide.
+
+Treat those bands as the shape to look for, not as thresholds to import. Find your own corpus's two clusters, then read the gap.
+
+**The two booleans the spine requires, derived independently:**
+
+```
+task_done       = the run's expected deliverable exists (artifact on disk, commit, PR, file changed)
+process_followed = every required phase appears in phase_trace, in spine order
+```
+
+Never let one imply the other, and never let `marker_present` stand in for either. `task_done AND NOT process_followed` is `done-no-workflow` below: the run did the job inline and skipped the corpus. Collapsed into one success column, it reads as a win and hides the most expensive defect in the set.
+
+## Outcome taxonomy
+
+Apply in order. First match wins. `broken` is first so that a harness fault can never be scored as a model failure.
+
+| # | Outcome | Test |
+|---|---|---|
+| 1 | `broken` | empty transcript, error exit, or `output_tokens` implausibly low for the task (set the floor from the smallest run that did real work, then check the excluded set by hand) |
+| 2 | `complete` | `marker_present AND task_done AND process_followed` |
+| 3 | `done-but-thin` | `marker_present AND task_done`, closing phases absent from `phase_trace` |
+| 4 | `done-no-workflow` | `marker_present AND task_done AND NOT process_followed`; the spine barely ran |
+| 5 | `bail-with-handoff` | no marker; `final_message` matches hand-off language (below) |
+| 6 | `ran-but-no-marker` | substantial trace, no marker, no hand-off language. Ambiguous; keep the bucket rather than forcing it |
+| 7 | `bail-early` | trace ends inside the first phase or two |
+
+Report the `broken` count as its own number every time you report a rate. In the engagement 20% of usable-looking runs were broken, and excluding them falsified the first headline finding. That finding was an apparently clean monotonic relationship between reasoning effort and completion, which was really the broken runs clustering in one cell (see Confounds).
+
+## Halt language in the final message
+
+Match against `final_message`. Starter set, case-insensitive:
+
+```
+\b(let me know|just let me know)\b
+\b(would you like|shall I|should I)\b.*\?
+\b(ready (to|for)|standing by|awaiting)\b
+\b(waiting (for|on)) (your|the)\b
+\b(next steps? (for|would be))\b
+\bI('ll| will) (wait|pause|hold)\b
+\bonce you (confirm|approve|reply|respond)\b
+\b(remaining|the rest|still needs? to be) (work|done|completed)\b
+```
+
+These are **evidence that the run stopped, not proof of why.** A match tells you to open that transcript and find which phase boundary produced it. A workflow that is *supposed* to stop and ask will match every one of these and be behaving correctly. Phase 4 sorts stops by who is actually on the other side. Extend the set with the phrasings your own corpus's prose invites. Grep the corpus for its own hand-off wording and add those.
+
+## Confounds that fool careful analysts
+
+Each of these was believed by someone competent before being ruled out. Run the rule-out before reporting the effect.
+
+| Apparent finding | Why it is suspect | Rule it out by |
+|---|---|---|
+| "The harness is timing out" | the cheapest explanation, and it makes the corpus innocent | comparing durations. Timed-out runs are **longer** than successes. In the engagement failures averaged 48 min against 88 for successes, so failures were shorter and the timeout hypothesis died. Failing *early* is a behavior, not a limit |
+| "More helper dispatches cause success" | `helper_dispatches` is a **collider**: it measures how far the run got. A run that stopped in phase 2 cannot dispatch phase 5's helpers | never reading it as a cause. Use it as a position estimate. If you want the causal claim, it needs a build that changes dispatch behavior and a Phase 2 comparison |
+| A clean dose-response across a setting | `broken` runs cluster by cell (one config, one date range, one machine), manufacturing the gradient | re-running the cross-tab with `broken` excluded. If the effect vanishes, it was never there. Also check whether exclusions land evenly across arms |
+| "This model is worse at the task" | model identity and workload are often confounded in an archive nobody designed | checking whether the arms ran the *same* task list. Unequal task mixes make any per-model rate meaningless |
+
+## Stratify before believing anything
+
+This is the highest-leverage work in the phase. A single pooled completion rate hides everything worth knowing.
+
+Cross-tabulate `outcome` against, at minimum:
+
+1. **model**, the identity axis
+2. **settings**: reasoning effort, temperature, context budget, whatever the harness varies
+3. **terminal phase**, the last entry in `phase_trace`, which is where the run died
+
+Read the third one against the first two. In the engagement, model identity explained roughly 3x the variance that reasoning-effort settings did, and the failing models died at **one specific phase boundary** 38-58% of the time while succeeding models died there 0-8%. That single cross-tab localized the defect without reading a line of corpus prose, and it turned Phase 3's audit from a 31-skill sweep into a targeted read.
+
+Watch cell counts. A 3-of-4 cell is not a rate. Label small cells rather than ranking them. If every cell is small, the stratification's output is a hypothesis list, which is still the correct output of this phase.
+
+## Hand off
+
+Carry forward: the `broken`-excluded baseline rate for `complete`, the observed `output_tokens` range, the tokens/min clusters, and the ranked list of phase boundaries where runs die. Phase 2 needs the baseline rate to compute a bar (`references/noise-floor.md`). Phase 3 needs the phase list to know which files to read first.
+
+## The limit
+
+Archive mining is observational. Nobody assigned the conditions, the arms are not balanced, and the confounds above are the ones you thought to check. It produces a baseline rate and a ranked hypothesis list. It cannot attribute a cause, and a rate computed from it is not a bar until Phase 2 shows how wide the noise is. Do not credit a change against an archive number alone.

package/skills/ce-retune/references/corpus-audit.md

@@ -0,0 +1,128 @@
+# Phase 3: Adversarial Corpus Audit
+
+Produces one finding set per corpus unit, each finding carrying a defender ruling. That ruling set is the input to Phase 4's passes. Nothing here edits a file.
+
+The audit is not evidence. It ranks candidates; only the harness says whether a cut helped. Do not let a large finding count imply a large effect. A corpus's run-to-run spread on fixed inputs (`references/noise-floor.md`) is the same whether the audit found 6 findings or 600.
+
+## Dispatch shape
+
+**The two waves must run as separate dispatched agents.** A defender's ruling is only worth recording when it can genuinely disagree with the proposal that reached it, which one context holding both roles cannot do. If the host exposes no way to run them as independent agents, report that as a blocker and stop the audit. Do not run the waves inline and hand the result to Phase 4. The same context arguing both sides still emits confident `cut` rulings, and Phase 4 deletes on them. That is the demolition this reference warns about below, arriving through the dispatch layer instead of a weak model tier.
+
+Two waves, one agent per unit each way.
+
+**Wave 1, the proposers.** One agent per corpus unit. Give it the unit's **full directory**, not just its entry file. Conditionally-loaded reference files are usually the bulk of a unit, and the entry file alone hides them. Instruct it to return the finding schema below and nothing else: no summary prose, no recommendations about other units.
+
+**Wave 2, the defenders.** One agent per unit, given that unit's directory *and* its proposal set, with the opposite job: find a reason each targeted line exists. A defender must search three sources, and must say which it searched:
+
+1. The project's own documented learnings and solution docs.
+2. The test suite. Grep a distinctive substring of the target text.
+3. Version history. Run `git log -S '<substring>'` for the commit that introduced the line, then read that commit message and the PR it belongs to.
+
+Source 3 is unavailable in a corpus checkout with no history, which is the normal shape of an installed or vendored copy. A defender working without history must say so in `sources_searched` and cannot return `cut` on the strength of the other two alone. That combination is "no provenance found in two of three sources", which is a verification task, not a cut. Point defenders at a checkout that has history, or record the whole audit's provenance basis as partial.
+
+**Pipeline the waves.** Start a unit's defense as soon as its proposal set returns. Do not wait for wave 1 to finish; the two waves share no state across units. It is 2N dispatches on N units, so plan the wave count against the host's concurrency cap (`references/workflow-shapes.md`).
+
+Keep defenders on a capable model tier. A defender that cannot read a test suite and reconstruct intent from a commit message returns "no provenance found" for everything, which silently converts the audit into a demolition.
+
+## Finding schema
+
+Per finding:
+
+| Field | Shape |
+|---|---|
+| `id` | stable, `<unit>-<nnn>`; defenses and later passes reference findings by id |
+| `target` | `path/to/file.md:line` or a line range |
+| `class` | exactly one value from the closed enum below |
+| `size` | estimated words removed |
+| `text` | the offending text verbatim, long enough to relocate after other edits land |
+| `why_unneeded` | what a capable model does here without being told |
+| `replacement` | the thinner line, or empty for pure deletion |
+| `risk` | low / medium / high; high means it touches a contract, a guard, or a string a test may pin |
+
+Per unit, in addition to the findings:
+
+- `must_survive`: every line that must not be cut, each with its reason. See "Protocol regardless of model tier" below for what belongs here.
+- `halt_sites`: every place where prose could make an orchestrating model end its turn while naming work it did not do. Quote each verbatim. This list is the highest-value output of the whole phase. A unit that reports zero halt sites has almost certainly not looked at its phase boundaries. `references/halt-taxonomy.md` carries the classes.
+
+## Classes worth hunting
+
+Ordered by expected behavior change per finding, not by word count. The last entry yields the most words and the least behavior.
+
+| Class | Diagnostic question |
+|---|---|
+| `phantom-handoff` | Does the party this sentence hands off to (a reviewer, a caller, a next agent, a consumer of the artifact) exist in this run? |
+| `step-machinery` | Would a different order, or skipping the ceremony, produce a different artifact? |
+| `capability-restatement` | Would the model do this if the line were deleted? |
+| `filler-rationale` | Does the rule survive intact if the sentence after it is removed? |
+| `vestigial-mode` | Grep the corpus for a caller that sets this mode, flag, or branch. Is there one? |
+| `mandatory-fanout` | Is this helper dispatch or self-verification pass conditional on anything, or does it run every time regardless of need? |
+| `cross-unit-duplication` | Is this block near-identical elsewhere, and is factoring it out actually permitted? |
+| `oversized-reference` | Could this file's entire content be five lines? |
+
+Two notes that change how the results read:
+
+- **`phantom-handoff` is the class that causes halts.** Prose written as if a second party were waiting teaches the model to stop and wait. Hunt it at phase boundaries first.
+- **Separate always-loaded prose from conditionally-loaded references when you tally `size`.** They cost differently. Always-loaded prose is context cost on every run; a conditionally-loaded file is runtime cost only when loaded. A corpus can be mostly conditional, which makes raw word count overstate context cost and understate runtime cost. Report the split.
+
+## Defender rulings
+
+Exactly three, one per finding:
+
+- **`cut`**: a real search over all three sources found no provenance. The proposal stands.
+- **`reduce`**: the constraint is real and the prose states it at several times the length needed. The defender returns the minimal form that preserves the constraint.
+- **`keep`**: concrete citable provenance a capable model could not infer, such as a test asserting it, a documented learning, or a commit that added it to fix a named bug. The ruling must carry the citation: path, test name, or sha.
+
+A defender returns one row per finding, in these fields, and nothing else:
+
+| Field | Shape |
+|---|---|
+| `id` | the proposer's finding id, unchanged; a ruling that cannot be joined back is discarded |
+| `ruling` | `cut` / `reduce` / `keep` |
+| `sources_searched` | which of the three, named; plus the query used, so an empty search is visible |
+| `citation` | required on `keep`: path, test name, or sha. Empty is not a `keep` |
+| `minimal_form` | required on `reduce`: the shortest text preserving the constraint |
+| `pinning_test` | test path and assertion if a grep of the target text hits the suite, else empty |
+
+**"A weaker model might need it" is not grounds for `keep`. Only citable provenance is.** Without that rule every line survives, because a defender asked to defend can always imagine a reader who needed the line. Where the unmeasured weaker tier is a genuine concern, the ruling is still `cut` or `reduce`, and the tier becomes a logged verification task in the Phase 5 limits report, not a keep.
+
+Symmetrically: a defender who returns `cut` without naming which sources it searched has not searched. Send it back once. Treat a second empty search as an unaudited unit and say so.
+
+## Protocol regardless of model tier
+
+For three categories the default inverts: **absence of provenance is not grounds to cut.** A capable model cannot re-derive them, so keep them even when no citation turns up. This is the one unrecoverable mistake in the phase. Everything else a later pass can put back after a failed run, and these fail silently.
+
+1. **Machine-readable strings other units parse**: field names, enum values, output paths, greppable markers, sentinel lines. These are arbitrary shared conventions. Nothing makes them true except agreement, so no amount of model capability recovers a changed one.
+2. **Security guards.**
+3. **Platform gotchas where the wrong behavior looks like success.** Their unifying property: *the model cannot discover them by trying*, because trying returns something that looks fine. A flag that returns empty instead of erroring, so a run reports zero findings and calls itself clean. A config key whose commented-out example matched a naive substring check and silently forced every user into the wrong mode.
+
+What *is* cuttable around all three is the justification clause, the sentence explaining that a separate consumer is waiting on the string. Keep the data, cut the story about who wants it. That is usually a `reduce`, and it is frequently also a `phantom-handoff`.
+
+`cross-unit-duplication` collides with this category more than any other class. Before proposing a factor-out, check whether the duplication is mandated: a documented decision, or a test that forbids sharing the block. The most-duplicated block in a corpus is often the one thing that must stay duplicated. In the engagement it was a security guard whose duplication a test explicitly required, and the largest duplication mandate was itself the documented fix for a bug that had regressed twice.
+
+## Synthesis: rank contradiction above confirmation
+
+The synthesis leads with what contradicts the premise the audit started from, before any cut list. Answer three questions explicitly:
+
+- **Which proposals did defenders save, with citations?** Report the count and the strongest saves. A defense rate near zero means the defenders did not search, not that the corpus is pure junk.
+- **Which unit was leaner than its word count implied?** Use the always-loaded / conditionally-loaded split. The largest unit by words is often not the largest by context cost.
+- **Where does the corpus already contain a documented argument against its own ceremony that nobody had grepped for?** Corpora that document their own decisions accumulate these. A duplication mandate that is itself the recorded fix for a bug that regressed twice is the shape to look for. The ceremony you were about to cut may be a scar.
+
+A synthesis that only confirms the premise is a finding about the audit, not about the corpus. Say so rather than shipping it.
+
+**The per-unit partition does not carry forward.** Findings arrive grouped by unit because that is how they were gathered. Phase 4 groups them by problem, and one problem's findings cross many units (`references/cut-passes.md`). Emit the ruled findings as a flat, id-addressable set with `class` and `target` intact so a pass can select across units. Handing Phase 4 a per-unit bundle produces one agent per unit editing one problem each, which is the collision shape Phase 4 exists to avoid.
+
+## Test pinning is the rate limiter
+
+Expect roughly half of `reduce` items to be pinned by a test asserting exact strings. That, not authoring effort, sets how many items a pass can carry.
+
+- Grep each `reduce` target's distinctive substring against the test suite **during the audit** and record the pinning test in the finding. Discovering the pin during Phase 4 costs a whole pass.
+- Budget the assertion retarget as part of the item, not as follow-up. Moving an assertion from a wording to the invariant it was protecting is often larger than the prose edit.
+- **A half-applied structural fix is worse than either endpoint.** If a pass cannot land both the prose change and the retarget, leave the item unstarted. A corpus half-migrated between two shapes has the ceremony of both and the guarantees of neither, and the harness cannot attribute a resulting failure to either shape.
+- If the invariant a pinned string was protecting cannot be named, that is a finding to report, not a license to loosen the assertion.
+
+## Two rules separate an audit from a demolition
+
+- **A cut with no provenance found after a real search is a confident cut. A cut the defender saves with a citation is off the list.** Do not relitigate a defended keep.
+- **Absence of evidence is weaker than the project's own standard for a change.** Where the guidance requires a reproduced failure or an exact failing path, a search that found nothing is a verification task, not a change. Say which of your cuts rest on that weaker basis.
+
+Dispatch shape: one agent per skill, each reading that skill's full directory and proposing cuts with a target and a reason; then a second agent per skill whose job is the opposite, to **defend the existing prose** using the project's own documented learnings, its tests, and git history. Expect the audit to contradict the premise you started with. That is its value.

package/skills/ce-retune/references/cut-passes.md

@@ -0,0 +1,129 @@
+# Cut Passes (Phase 4)
+
+A pass applies **one problem class** across the corpus and stops. The work fails in two places: agents overwriting each other, and edits left half-applied. Both are prevented by protocol, not care.
+
+`references/workflow-shapes.md` carries the cross-phase orchestration catalog. This file is the Phase 4 procedure only.
+
+## The pass loop
+
+1. Pick one class from the Phase 3 findings (`references/corpus-audit.md`), or one regression class from `references/halt-taxonomy.md`. One class per pass, no bundling.
+2. Write the **file-assignment manifest**: unit -> the agent that edits it -> exact paths. Every copy of a shared asset goes to a single named agent (below).
+3. If the rewrite has cross-referencing strings, author the **contract file** first, serially (below).
+4. Dispatch one agent per unit through whatever sub-agent primitive the platform provides. Each prompt carries the class, the contract path if any, its own paths, and the forbidden paths.
+5. **Reconcile** every block touched (below). This is the step that gets skipped.
+6. Run the project's own test suite. A pinned string that disappeared is a finding to report with its test path, never a test to edit.
+7. Collect each agent's applied/skipped report. Then measure (Phase 5) and commit the pass alone.
+
+Eight passes landed in the engagement that produced this skill. Every one reduced to the same class. Resist widening a pass to "also fix the obvious thing". A pass that changed two classes cannot be attributed by the next measurement.
+
+## One problem per agent, disjoint files
+
+Fanning out by **problem** looks natural and collides immediately. A single class, say a phrasing that implies an absent reader, appears in twenty files, and the next class appears in eleven of the same twenty. Two agents open one file, both write, the second write wins, and the loss is silent because each agent's own diff looks correct.
+
+Fan out by **unit** instead: one agent edits one skill directory and applies the class everywhere inside it. The file assignment is then a partition of the filesystem, and the invariant is checkable before dispatch: every path appears in exactly one manifest row.
+
+| Manifest column | Content |
+|---|---|
+| unit | the directory the agent edits, e.g. `skills/<name>/` |
+| paths | explicit glob or file list inside it |
+| forbidden | shared assets and anything outside `unit`, listed by path |
+| class | the one problem being applied |
+| contract | path to the canonical mapping, or `none` |
+
+State the forbidden set in the prompt as paths, not as a rule to infer. An agent told "do not touch shared files" will decide for itself what is shared.
+
+## Isolation: separate worktrees or disjoint paths in one tree
+
+Disjoint paths in one tree are enough when nothing an agent runs mutates state outside its own paths. That covers most cut passes: edits are text, the manifest is a partition, and a single tree keeps the diff readable and the commit trivial.
+
+Pay for a worktree (or equivalent per-agent checkout) when any of these is true:
+
+- Agents run builds, formatters, generators, or anything that writes outside its unit, such as lockfiles, caches, generated output, or a repo-root config.
+- An agent needs to run the suite or the harness to check its own edit. Concurrent runs in one tree race on scratch and on git index state.
+- Agents commit, stage, or use branch operations. One git index shared by parallel agents corrupts staging.
+- A pass may need to be abandoned wholesale, and a clean discard is worth more than a shared diff.
+
+Otherwise the isolation cost is real: N checkouts to create, N results to merge, and merge conflicts reintroduced on exactly the files the manifest was designed to keep apart.
+
+## The shared-asset trap
+
+Some corpora hold byte-identical copies of a file inside several units, deliberately, with a parity test asserting the copies match. A per-unit agent editing "its" copy breaks parity, and the breakage shows up as a test failure in a *different* pass, attributed to the wrong change.
+
+Discover them before dispatch. Shape (POSIX shell; hash every candidate file, key by basename, report pairs appearing in more than one path):
+
+```
+find . -type f \( -name '*.md' -o -name '*.py' -o -name '*.sh' \) -exec shasum {} + \
+  | awk '{ n = $2; sub(/.*\//, "", n); print $1, n }' \
+  | sort | uniq -c | awk '$1 > 1'
+```
+
+Read the output two ways. A basename with **one** hash across many paths is a maintained shared asset: assign every copy to exactly one agent, list it as forbidden for everyone else, and have that agent propagate the edit to all copies in the same pass. A basename with **several** hashes across paths is drift that already happened. That is a finding, not necessarily yours to fix in this pass.
+
+Whether a duplication should exist at all is a proposal-time question, decided in `references/corpus-audit.md`. A pass never settles it by factoring out. Assign the copies to one agent, propagate to every copy, leave the mandate alone.
+
+## Author the contract before a parallel rewrite
+
+When one class spans many files and the strings **cross-reference each other** (a phrase in one unit that another unit quotes, a marker other prose routes to, a shared field name), the rewrite cannot be decided in parallel. `references/workflow-shapes.md` carries what breaks if you skip either the contract or the fan-out.
+
+Serialize the decision. One high-effort agent (or you) writes the canonical mapping to a file first:
+
+```
+old string (exact)  ->  new string (exact)  |  rationale  |  units affected
+```
+
+Per-unit agents then apply it **verbatim** and report any occurrence the contract does not cover rather than improvising a variant. An uncovered occurrence is a contract gap to resolve serially, not an invitation to extend the contract locally.
+
+Corollary: **gathering the inventory is parallelizable; deciding the canonical rewrite is not.** Fan out to find every occurrence, then collapse to one author to decide the mapping, then fan out to apply it.
+
+## Reconcile
+
+After editing, re-read every block touched and fix what the edit itself broke. A half-applied cut is worse than no cut. It leaves prose that is internally inconsistent, which is a defect the corpus did not have before.
+
+Check each of these on every touched file:
+
+- A reference (path, section name, phase number) pointing at something the pass removed.
+- A numbered or ordered sequence with a hole, or with a step whose ordinal no longer matches what it depends on.
+- An instruction whose precondition was deleted, so it now applies unconditionally or never.
+- A reference file nothing routes to any more. Either restore the route or remove the file. An orphan reference is loaded by nobody and rots.
+- Two surviving sentences that now contradict each other. Pick one and delete the other. Do not leave both and let the model choose.
+- Frontmatter, description, or activation text that no longer matches what the unit does after the cut.
+- A cut that landed in a duplicated shared asset without the sibling copies following.
+
+## Assertions on mechanical edits
+
+When a pass applies many exact replacements, do it under assertions rather than by hand. For each target, assert the string matches **exactly once** in its file, and abort before writing anything if any target matches zero times or more than once.
+
+Exactly-once is the part that makes the check worth running. Zero matches means an earlier pass already rewrote the anchor. More than one means the anchor is ambiguous and the edit would land in the wrong place. In the engagement this caught an anchor a previous pass had already changed, and because the check ran before any write, nothing was partially applied. The pass was re-derived against current content instead of repaired afterward.
+
+Fail closed, all-or-nothing per file at minimum. A script that writes files 1 through 7 and dies on 8 leaves a state no one can review.
+
+## Report the skips
+
+**Report what you deliberately did not cut, and why.** An agent that applied 100% of its proposals has almost certainly over-cut. A meaningful skip rate is the expected outcome, not underperformance. In the engagement's audit, 81 of 616 proposed cuts were defended and kept.
+
+## The over-cut failure mode
+
+Removing a "you must" does not remove the decision. It hands the decision to the model. `references/halt-taxonomy.md` class 10 carries the mechanism and the observed failure. The line that resolved it without restoring the old prose was **a unit decides its own internal delegation; whether a step runs at all is not its call.**
+
+The pass-loop rule: for every mandate you remove, name what now decides, and check that the new decider is allowed to decide it. If the answer is "the model, at its discretion, whether a required step happens", then that mandate is a required check, and it stays. This class is also invisible to a probe that never enters the skipped phase. That is why Phase 5 audits the phases the instrument cannot reach, and why one clean run proves nothing (`references/noise-floor.md`).
+
+## Discipline that survives contact
+
+- **Fix at the smallest layer that defines the behavior.** Reword only when rewording is the smallest mechanism; prefer deleting the structure that made the wording necessary.
+- **Field names, enums, greppable markers and security guards are data.** They stay. What goes is the justification clause around them that teaches the model a separate consumer is waiting.
+- **Never edit tests to make a suite green.** A removed string a test pins is a finding to report, not a test to weaken.
+- One problem per agent, each editing a disjoint file set so parallel work cannot collide.
+
+## Reading the failure (Phase 5)
+
+A failure that moves to a later phase is progress and names the next target. A failure at the same site means the fix missed. A run that completes the task while skipping the workflow is a different defect than a halt, and only shows up if Phase 1's two metrics stayed separate.
+
+**Audit the phases the instrument cannot reach.** A probe that skips a phase can never fail in it, so a green streak certifies only what it exercised. List the phases your task never enters, read those files, and treat what you find there as equal in weight to what the runs found. Some of the most consequential defects live where no test looks.
+
+**Report the limit.** Name the paths that remain unmeasured and what would be needed to measure them. Do not let a cleared bar imply coverage it does not have.
+
+## Ship (Phase 6)
+
+Commit each pass separately with its own message so the history says which change was made and why, and so release tooling can classify intent. Keep the measurement artifacts.
+
+Then write the finding down where the next person will hit it: the mechanism, the before and after, the measured numbers, and the hypotheses that died. **Record the ones that died.** They are what stops the next attempt from re-running a dead end, and they are the part every write-up omits.

package/skills/ce-retune/references/halt-taxonomy.md

@@ -0,0 +1,123 @@
+# Halt Taxonomy
+
+## The mechanism
+
+A workflow "phase" is often invoked by loading its instructions into the **same conversation** (a skill load, an include, a prose route to "the review phase") rather than by spawning a separate process. When that happens, the model on both sides of that seam is one model in one turn. In an unattended run there is no second party and no next user message, and a reply that contains no tool call ends the session. So an instruction to return, hand back, or report to a caller has exactly one expressible form at that seam: stop. The prose is not wrong about its protocol. The protocol has no runtime.
+
+**The diagnostic that settles which seams are real.** In the run archive, find one session id whose trace contains *both* phase-invocation calls (skill loads, reads of another unit's `SKILL.md`) and real subagent dispatches. The phase invocations carry the same session id as the orchestrator. That is one conversation and a fictional boundary. The subagent dispatches carry a distinct child id. That is a real boundary that can carry a hand-off. One line of log settles it for the whole corpus. Run this before classifying anything. Class 9 and survival screen 3 both depend on the answer.
+
+If the archive carries no session or child ids (`references/baseline-mining.md` extracts them where it can), substitute the weaker structural test: a seam is real only where the trace shows a **dispatch tool call whose result returns into the parent trace**. A skill load, an include, or a file read is not one. Do not treat an unlabeled trace as evidence of a real boundary. That reading keeps every halt.
+
+Each class below gives what to grep, why the match halts, and the replacement. Grep terms are starting points for a corpus that never used exactly these words. Read the matches; do not batch-edit them. Case-insensitive, whole corpus including reference files, one class at a time:
+
+```
+grep -rniE 'return control|hand back|hand off to|the caller (owns|applies)' <corpus-dir>
+```
+
+## 1. Waits on helpers the runtime already terminated
+
+**Grep:** `wait for all`, `in parallel`, `concurrently`, `background`, `up to <n> minutes`, `poll until`, `dispatch all <n>`
+
+**Why it halts:** a mandated fan-out plus a wait ceiling. If the helpers were never spawned concurrently, or the runtime reaped them at turn end, the wait resolves to nothing. And "wait" has no tool call to express it, so the turn ends inside the ceiling.
+
+**Falsifiable check before touching it:** from the archive, measure the maximum number of helpers dispatched *concurrently* per run (see `references/baseline-mining.md` for the extraction). In the engagement, 331 of 332 runs never exceeded one at a time, which falsified the wall-clock justification the corpus had written for its own fan-out machinery.
+
+**Replacement:** dispatch serially, or state parallelism as an allowance rather than a mandate, and delete the wait ceiling with the wall-clock rationale that justified it.
+
+## 2. Hand-off across a same-model seam
+
+**Grep:** `return control`, `hand back`, `hand off to`, `the caller owns`, `the caller applies`, `report to the orchestrator`, `your caller will`
+
+**Why it halts:** it names a recipient that does not exist on this side of the diagnostic above.
+
+**Replacement:** record the structured result and continue. "Write the result to `<path>`, then continue to `<next step>`." Keep every field name in the result untouched. The fields are data; the hand-off verb is the defect.
+
+## 3. A step ending with no instruction to advance
+
+**Diagnostic (count, not grep):** at each boundary between consecutive steps, classify the last sentence of the step as terminal (`stop`, `done`, `await`, `report`, `wait for confirmation`, `end of step`) or forward (`then`, `next`, `continue to`, `proceed to`). A corpus with more terminal than forward endings has a structural halt, not a wording problem.
+
+**Why it halts:** a step that closes on a terminal word and says nothing about advancing leaves ending the turn as the only complete reading.
+
+**Replacement:** an explicit continue-to-next at **each** transition, placed at the transition and not once in a preamble, plus one statement that a checkpoint means verify and continue rather than pause.
+
+## 4. Completion defined without a successor
+
+**Grep:** `is done once`, `is complete when`, `you are finished when`, `definition of done`, `success criteria`
+
+**Why it halts:** "X is done once ..." with nothing after it reads as the end of the turn, not the end of a step.
+
+**Replacement:** say what follows being done. "X is done once <criteria>; then <next step>."
+
+## 5. A structured output labeled as a return
+
+**Grep:** `Return the following`, `Return:`, `your return value`, `respond with the following object`
+
+**Why it halts:** the verb, and only the verb. A return is a control transfer; there is nowhere to transfer to.
+
+**Replacement:** verb swap. `Return the following:` becomes `Write the following to <path>:`. The field list is untouched. This is the cheapest class and the easiest to over-cut. An agent told to fix "return" language will happily also delete the schema under it.
+
+## 6. An output-format rule doubling as a turn boundary
+
+**Grep:** `output nothing else`, `no other text`, `respond with only`, `a single bare`, `do not add commentary`, `the entire response must be`
+
+**Why it halts:** a rule forbidding anything after the payload forbids the next tool call. It is a strictness constraint that has quietly become a stop instruction.
+
+**Replacement:** write the machine-readable payload to a file at a stated path and let the reply continue. The strictness moves rather than being lost. A file at a fixed path is a *more* deterministic parse target for a programmatic consumer than the end of a transcript, so say that in the replacement text or someone will restore the old rule.
+
+## 7. A missing optional capability treated as fatal
+
+**Grep:** `not installed`, `must be available`, `required tool`, `abort if`, `did not start`, `if <x> is unavailable, stop`
+
+**Why it halts:** a step that cannot execute takes the whole run with it, when the correct outcome is a partial result.
+
+**Replacement:** record the step as skipped with the reason and what it would have covered, report partial, continue. Keep the stop only where the missing capability makes every later step meaningless. That is a real precondition, not this class.
+
+## 8. An unresolvable precondition with no unattended path
+
+**Grep:** `resolve ... first`, `ask the user to`, `credentials`, `log in`, `confirm before`, `requires approval`
+
+**Why it halts:** "resolve credentials first" is satisfiable only by a human, and no human is present.
+
+**Replacement:** report the unmet precondition and continue without the step. Where the step is mutating and unsafe to perform unattended, skip the mutation and record the exact command a human would run. Do not resolve a halt by widening what the run is allowed to change.
+
+## 9. The subagent-prompt trap
+
+**Grep:** the vocabulary of classes 2 and 6, restricted to the corpus's own prompt assets: its persona or agent-prompt directories and prompt templates. Also `report and stop`, `return only a gist`, `the orchestrator owns that decision`, `do not act on this yourself`.
+
+**Why a naive sweep misses it entirely:** while the asset is sent to a real subagent, every one of those lines is correct and required. They become a live session terminator the moment a documented no-subagent fallback routes the asset **inline** into the orchestrator's own conversation. Same words, different consumer. A sweep that reads only the asset sees a correct file. A sweep that reads only the orchestrator sees no offending prose.
+
+**Resolution:** classify each prompt asset by who actually consumes it. Grep every unit that dispatches the asset for an inlining fallback: `if you cannot dispatch`, `if subagents are unavailable`, `run this yourself`, `inline`. Then:
+
+| Consumer | Action |
+|---|---|
+| Always a real subagent | Leave as is. The boundary is real. |
+| Any documented inline fallback | Rewrite so the text is safe in both paths, or remove the fallback. |
+| Asset shared by several units | Resolve once, for the union of consumers (see the shared-asset rule in `references/cut-passes.md`). |
+
+Do not blanket-rewrite prompt assets. That deletes the one boundary in the corpus that was not fiction.
+
+## 10. Over-correction: removing the mandate that made phases required
+
+This class belongs here because the cure for 1 through 9 causes it.
+
+A dispatch mandate carries two payloads: the fictional seam, and the requirement that the phase run at all. Remove the first without preserving the second and nothing in the corpus says the workflow's own phases are required.
+
+**Observed:** after a dispatch-mandate removal, a run did the task inline and reported success with no artifacts. The transcript looked clean. That defect is invisible to a did-it-finish metric and shows up only if process adherence and task completion are tracked as separate numbers (`references/baseline-mining.md`).
+
+**Replacement:** keep the requirement, drop the seam. "Phase N is required. Do it in this session; do not skip it." Then verify the phase by artifact existence, never by the final message.
+
+## Screens for a stop that must survive
+
+Treating every stop as the enemy is the failure mode of applying this file. Run these before editing any match above. **Any one** is sufficient to keep the stop as written.
+
+1. **The user is genuinely the subject.** The instruction concerns a human's decision, consent, or preference, not a fabricated caller.
+2. **It is a terminal no-op.** Nothing is left for anyone: "no findings, stop." A continuation here invents work.
+3. **The roles split across a real runtime boundary.** The opening diagnostic shows two distinct sessions or processes. Then "return to the caller" is accurate and the halt is somebody else's turn ending, correctly.
+4. **The site already has an unattended default.** "If no reply within X, choose Y", "in non-interactive mode, do Z." The path exists; the stop is the interactive branch.
+5. **The word bounds an activity, not the turn.** "Stop expanding the search once you have three candidates", "halt the retry loop after two failures." A grep for `stop` catches these. They are scope quantifiers, and removing them removes a threshold.
+
+**Sixth case, stated separately because it is the one that gets deleted anyway:** a workflow whose product **is** stopping to ask. An interview that must take one question at a time. A teaching check-in that pauses for the learner's answer. An approval step that exists in order to make the user decide. Deleting the pause deletes the unit. These get an unattended degradation path (a stated default, a skip-with-reason, or an explicit refusal to run unattended), never a deletion. If such a unit fails the benchmark, the benchmark's task is wrong for it. Exclude the unit and report the exclusion rather than editing the unit to pass.
+
+## Why the fix is never more capability
+
+Every class above reduces to prose written as if a second party were waiting. The fix is never to add capability. It is to remove the fictional seam and keep the requirement.