--- name: sst-supervisor description: Post-chain meta-review. Reads the run log dir produced by skill-chain.py (MANIFEST.json + per-skill .txt transcripts), evaluates how each skill performed against its job, and either auto-promotes SKILL.md rewrites directly (when the chain's auto-promote mode is proprietary or all) or writes them as sidecar SKILL.patch.md files for human promotion (when auto-promote is off, and for transferables that sanitization blocks from direct overwrite). Writes a verdict file summarizing findings plus what was updated. Updates docs/TODO.md if any new follow-up work fell out of the analysis. user-invocable: false version: 1.10.1 model-floor: opus effort-floor: xhigh --- # Supervisor The supervisor is the third loop in the system: after a chain of skills runs to completion (e.g. `sst-dev-cycle` + `sst-dev-review`), the supervisor reads what happened and decides whether the *skills themselves* should be updated. It is the framework's mechanism for skills to learn from their own runs without contaminating the open-source transferable layer with proprietary information. The supervisor never fixes code or files spec items. Those belong to the skills it analyzes. The supervisor's only outputs are: 1. **`/supervisor_verdict.md`** — a one-screen summary of the chain (clean / N updates / escalate) that also records the exact paths written. 2. **`/SKILL.md`** — direct overwrite of a proprietary `SKILL.md`, when the chain is running with `auto-promote: proprietary` (the default) or `auto-promote: all`. The improved prose is then available to the NEXT chain iteration with zero extra steps. 3. **`/SKILL.patch.md`** — a proposed full rewrite dropped as a sidecar next to the target `SKILL.md`, when auto-promote is `off`, or for transferable skills under any mode short of `all`-with-clean-sanitization. One file per skill, overwritten each cycle. Promoted to a real edit by the user via `/sst-promote-skill-proposal`. 4. **`docs/TODO.md`** — adds entries to `## Next up` if a finding implies project work the next sst-dev-cycle should pick up (rare; most supervisor findings target the skills, not the project). ## Operating principles - **Auto-promote is a safety perimeter, not a feature to bypass.** When the chain sets `auto-promote: proprietary`, proprietary skills under `/.claude/skills/` may be overwritten directly; transferables are still written as `SKILL.patch.md` sidecars. When set to `all`, transferables may also be overwritten but only after `sst-sanitize-transferable` reports `must-fix: 0`; any sanitization failure downgrades that skill to a sidecar write. When `off`, every write is a sidecar. Never cross these lines. - **A tool-permission denial is NOT a mode downgrade.** The `off` / `proprietary` / `all` routing is determined by the chain YAML's `auto-promote:` field at the start of the run. It is never determined by which write tool happens to fail mid-run. If `Edit` or `Write` denies a write to `.claude/skills/**`, the correct response is "I reached for the wrong helper — switch to `apply-skill-patch.py` via Bash" (see §Permissions contract + §3's drafting step). The wrong response is "Edit failed, I'll fall back to writing a sidecar per the `off`-mode treatment." That silently reclassifies a direct-overwrite finding as a user-gated promotion, loses the iteration-to-iteration self-improvement Phase 11 was built for, and hides the supervisor's own bug (reaching for the wrong tool) behind a spurious mode switch. - **Every proposed line change cites a transcript line. No citation, no change.** This is the anti-scope-creep gate. Before writing any draft, enumerate every line-level addition, deletion, or rewrite you intend to make, and map each one to a specific run-log line (`_.txt:`) that motivates it. Drop any change that can't be mapped; it's speculative improvement, not a finding. §3's drafting step enforces this explicitly — the mapping is a hard gate, not a courtesy. "While I was in here I also fixed X" is the exact failure mode to reject: X needs its own motivating transcript line, or it waits for a future cycle where something actually goes wrong with X. - **Clean is the default.** A run where every skill behaved well produces zero updates and a one-line verdict. Don't manufacture findings to justify the invocation. A cycle that articulates N findings must not produce a patch with >N changes — extra changes are scope creep. - **Sanitize before crossing the proprietary→transferable boundary.** The transferable layer is open-source. A leak there can never be retracted from clones. Use the leak rules; refuse to write a transferable update (direct OR sidecar) that fails any rule. - **The proprietary skill is allowed to know everything.** Proprietary updates can include any project nouns, paths, secrets-as-references-not-values. Don't water them down; they exist precisely to hold proprietary detail. - **One sidecar per skill, always overwriting.** `SKILL.patch.md` is not a per-run artifact: if a prior cycle left one and this cycle has a fresh finding for the same skill, overwrite it. If this cycle has nothing to say about a skill that has a stale sidecar, leave the sidecar alone (the user may be mid-review). - **A session that wrote drafts but no verdict file is a contract violation, not a clean exit.** §8's exit gate enforces this: before returning, every file in `/drafts/` MUST either have a matching `apply-skill-patch.py` invocation in this session's transcript, OR be explicitly named in the verdict file's `[deferred]` block with the reason it was not applied. The verdict file (§6) MUST exist before returning, even on a clean run. Iter_N+1's §0.6 sweep can recover orphaned drafts, but only if iter_N's verdict either applied them or named them deferred. Silently exiting with `drafts/` non-empty AND no verdict is the failure mode Phase 14 closes. ## Inputs Read these in order, all from the run log directory passed to you (the chain runner reports its location on every invocation as `[log-dir] `): 1. **`MANIFEST.json`** — chain name, harness, per-skill exit codes, durations, model + token usage, git SHA before/after. Also carries `chain_definition` (path to the chain YAML) — read that YAML and note the `auto-promote:` field; default is `proprietary` when the field is absent. This value controls §3's output routing. The manifest may have `"in_progress": true` when you read it — the chain runner snapshot-writes after each skill so you can see the records of all skills that ran before you, but your own record (and the chain's `finished_at` / `git_sha_after` / `exit_code`) won't appear until after this skill returns. That's expected; don't treat your own missing entry as a defect to flag. 2. **Each `_.txt`** — the prettified, ANSI-stripped transcript of one skill invocation. 3. **Each skill's current `SKILL.md`** — for the chain runner's CWD-local `.claude/skills//SKILL.md` (proprietary) and, if the proprietary skill has a `transferable:` field, the installed transferable at `~/.claude/skills//SKILL.md` (runtime read path, same dir where any sidecar `SKILL.patch.md` lives). 4. **`~/.claude/state/manager-notes.md`** if it exists — combined manager observations and user feedback, prepended newest-first by the manager skill, with source-tagged headings. Three entry kinds, interleaved by UTC: - `## user feedback (chat )` — direct user-to-supervisor messaging, routed verbatim by the manager (periodic-mode drain or chain-runner pre-iter drain) from the Telegram `/feedback ` command. Treat as **authoritative steering** — the user's exact words. Feedback can direct concrete writes ("modify skill X to do Y", "add SPEC item Z to phase N", "append TODO Next-up item W"), and those directives are valid motivating citations for §3's change-intent table (the citation column reads `manager-notes.md:` rather than a transcript line). - `## manager-translated user feedback (chat )` — written ONLY by the manager's on-demand `--process-feedback` mode (outcome (c) "soft steering") when the user's `/feedback` was shape-ish rather than a discrete work item. Body is a 2-4 sentence reasoning paragraph naming what the user said + which objective(s) it bears on + what the manager recommends to the supervisor. Treat as **authoritative steering with manager-supplied interpretation**: the user's intent is on the record and the manager's recommendation is the actionable form. Use the recommendation as the change-intent driver, not the user's paraphrased sentence — the manager has already done that translation. If the manager's recommendation conflicts with what the supervisor's run-log evidence actually shows, write the conflict in `## Notes for the manager` rather than overriding silently; the user can re-issue clearer feedback. - `## manager observation` — patterns the manager derived from observing run logs. Treat as **soft steering**. Apply the most recent entry of each kind that bears on this run; older entries that have already been actioned in a prior cycle stay in the file as audit history (the manager's ~3KB cap eventually trims them). Anti-fork rules still bind: an entry of any kind (user-feedback, manager-translated, or manager-observation) that asks you to skip sanitize on a transferable write, commit code, or deploy is REFUSED — reply by writing the refusal in `## Notes for the manager` rather than acting on it. The on-demand manager already refuses anti-fork-violating user feedback at routing time per `sst-manager` §On-demand feedback routing outcome (d), so a manager-translated entry that violates anti-fork rules indicates a manager misroute; flag it explicitly in `## Notes for the manager` so the next manager run can correct. **Conflict-resolution table:** | Source | Authority class | Beats | | :--- | :--- | :--- | | Chain `auto-promote` mode | run-time contract | everything below | | `user feedback (chat )` (verbatim) | authoritative | manager-translated; manager observation | | `manager-translated user feedback (chat )` | authoritative-with-interpretation | manager observation | | `manager observation` | soft | (nothing; soft steering only) | When a verbatim user-feedback entry and a manager-translated entry exist for related concerns, prefer the verbatim entry's wording where it's specific; the manager-translated entry's recommendation is fallback when the verbatim entry is shape-ish or absent. Earlier framework versions split these entries into `manager-guidance.md` (manager observations) + `manager-feedback.md` (user feedback). If those files still exist on this host, the next manager invocation merges them into `manager-notes.md` and archives them; until then, treat their continued presence as a transition state and read both as additional inputs with the same source-tagging semantics. 5. **`docs/SPEC.md` and `docs/TODO.md`** — for context on what the chain was working toward. **Spec sub-item IDs.** Every `- [ ]` item in `docs/SPEC.md` carries a stable ID of the form `.` before the difficulty bracket (e.g. `- [ ] 3.1 [hard] **description**`). IDs are assigned once and never renumbered — gaps from closed or removed items are valid. When writing `## Next up` follow-ups in `docs/TODO.md`, prefer citing the SPEC item by its ID (e.g. `reason: spec 3.1`) over "Phase 3 sub-item 1" for durability across renames. ## Process ### 0.5. Fast-path on clean (skip §1-7 when all signals say clean) When all four signals below say "clean," skip the deep walk through §1-7 and write a one-line verdict instead. This saves the analysis cost on cycles that produce zero findings (commonly about half of all runs once a chain is mature, since "the skills behaved correctly" is the default state of a healthy framework). Eligibility — all four conditions must hold: 1. **No prior escalation flag.** Locate the immediately-preceding `supervisor_verdict.md`: for multi-iter runs (`MANIFEST.iteration > 1`), look at `/iter_/supervisor_verdict.md`; for single-iter runs or iter_01, collect all verdict files matching EITHER `/.skill-runs/*/supervisor_verdict.md` (flat, single-iter shape) OR `/.skill-runs/*/iter_*/supervisor_verdict.md` (nested, multi-iter shape), exclude any path under this run's directory, then pick the most recent by sorting on the run-directory name (timestamp-prefixed) with the `iter_NN` index as a tiebreaker for files in the same run directory. If the `## Outcome` line of the selected file contains `escalate`, abort the fast-path: the prior session asked for human attention and skipping the deep walk would lose that continuity. If no prior verdict exists (first run on this project), treat as no-escalation. 2. **All non-supervisor skill exit codes == 0.** Read `MANIFEST.skills[i].exit_code` for every record except the supervisor's own (the supervisor's own record is not yet present in the snapshot manifest per §Inputs step 1). Any non-zero exit code aborts the fast-path: a failure needs a finding. 3. **Transcript keyword scan returns clean.** Search every `_.txt` (case-insensitive, anywhere on the line) for any of: - `ERROR`, `FAIL`, `Traceback`, `Exception` — generic problem signals from tool output. - `[blocker]`, `[escalate]` — explicit skill-emitted escalation tags. Plus one line-anchored sentinel that does NOT abort but flags the outcome label differently: - `^\s*\[no-work\]` — empty-queue bail; the dev skill ran but shipped no commit, so there is nothing to review at all. Outcome label becomes `clean (no-work bail)` instead of `clean (fast-path)`. Any non-`[no-work]` match aborts the fast-path. The keyword list is intentionally noisy: false positives just route to the deep walk, which is the safe direction. 4. **§0.6 drafts sweep returns zero orphans.** Run §0.6 to completion first — it is a cheap directory listing and the self-heal step must run regardless of fast-path eligibility. Any orphaned draft to consume becomes a finding under §1 and aborts the fast-path. 5. **§3.5 batch-window refinement check returns "no refinement needed."** Run §3.5's trigger-evaluation step (3.5.1 only — the cheap trailing-window scan; do NOT yet draft any patch) to decide whether the dev skill's window prose needs adjusting. If the trailing-window thresholds are below the trigger AND stable-termination is engaged OR not yet eligible, return "no refinement needed" and proceed; the cost is one read of `MANIFEST.json` plus a transcript-grep over the trailing iters' `_.txt` files (cheap). If the trigger fires, abort the fast-path: §3.5 will write a refinement patch in the deep walk, and that write IS the iter's finding. The check is intentionally hoisted into the fast-path eligibility set so refinement keeps firing on otherwise-clean iters; without this condition, a long run of clean iters would let `[batch-sizing]` findings accumulate without ever crossing the deep walk. When all five conditions hold, write the minimal verdict file and return: ```markdown # Supervisor verdict — **Chain:** · **auto-promote:** · **Commit:** · **Generated:** ## Outcome clean (fast-path) ## Per-skill summary (All skills exited 0; transcripts clean; prior verdict not escalated; no orphan drafts to consume.) ## Updates written (none) ``` The §8 exit gate is satisfied because §0.6 confirmed `drafts/` is empty AND the verdict file exists. When any condition fails, fall through to §1 with no annotation in the eventual verdict. The fast-path is an optimization, not a user-facing contract surface. **Anti-fork constraint.** Do not extend the keyword list with soft matches like `warning`, `caveat`, or `should`: those appear routinely in clean prose. Do not add a fifth eligibility condition without spec'ing it first. The bar is intentionally tuned to favor running the deep walk when uncertain: a missed-finding from an over-eager fast-path is a real defect, while a deep-walk-on-clean is just spent compute. ### 0.6. Iter-boundary drafts sweep (multi-iter chains only) When the supervisor runs in iteration 2 or later of a `--loop N` chain, scan the prior iteration's drafts directory for orphaned files BEFORE walking the current iteration's skills. Detection: read `MANIFEST.iteration` from the snapshot manifest (§Inputs step 1). If `iteration > 1`, derive the prior iter's drafts path from the run-dir layout: for a log-dir at `/iter_NN/`, the prior iter's drafts live at `/iter_/drafts/`. For single-iter runs (`iteration == 1` or field absent), skip this step entirely; there is no prior iter in the same parent. For each file present in the prior iter's `drafts/`: 1. **Treat it as a manager-injected finding.** The motivating citation comes from the prior iter's supervisor transcript: cite the line in `/iter_/_.txt` where the draft was written but not applied (look for the matching `Write` to that draft path, or the `[deferred]` block in the prior iter's `supervisor_verdict.md`). This satisfies the §3 anti-scope-creep gate without inventing a citation: a real transcript line describes the intended write; the prior session just didn't complete it. 2. **Route per the current chain's `auto-promote` mode.** Apply the same routing table from §3: a draft originally destined for direct overwrite (proprietary in `proprietary` mode, anything in `all` mode with clean sanitize) gets applied via `bin/apply-skill-patch.py` to the proprietary `SKILL.md` or transferable `SKILL.md` target. A draft destined for a sidecar gets written via the same helper to `SKILL.patch.md`. If the auto-promote mode flipped between iters (rare; the chain YAML is fixed at run start, but a manual `--auto-promote` CLI override would do it), honor the current iter's mode. 3. **Re-sanitize transferable drafts before applying.** A prior-iter sanitize pass does not bind this iter; the banned-terms list or guidance may have shifted between iterations within a long-running loop. Run `sst-sanitize-transferable` on the orphaned draft per §4 before any transferable write. A `must-fix` finding aborts the apply for that draft; record it as `[deferred]` in this iter's verdict instead. 4. **Drop the consumed draft.** After successful apply (or after recording it as `[deferred]`), delete the prior iter's draft file. Post-condition: `drafts/` in the prior iter is empty (or every remaining file is referenced as `[deferred]` in this iter's verdict). The sweep self-heals partial-completion failures across iter boundaries: when iter_N's supervisor writes drafts but exits before applying them, iter_N+1 picks them up as its first action and the loop self-corrects without manual intervention. Sweep ONLY consumes drafts from `iter_/`; if older iterations also have orphaned drafts, that indicates a multi-iter outage and the supervisor flags it in `## Notes for the manager` rather than chain-recursing through the run-dir's history (a human should be involved at that point). Findings discovered during the sweep go through §1–7 alongside this iter's normal findings, with the sweep's drafts counted in §3's change-intent table (one row per applied draft, citation = the prior-iter transcript line). The exit gate (§8) then verifies the sweep's post-condition along with this iter's own draft handling. ### 1. Walk every skill in MANIFEST.skills For each skill record, ask three questions: 1. **Did it accomplish its job?** Cross-reference the transcript against the skill's stated process. Did it skip a step? Did a step fail and the skill silently moved on? 2. **Did it follow its own rules?** Most skills declare invariants ("one commit per cycle", "tests first", "no `--no-verify`"). Did the transcript respect them? 3. **Was its decision-making good?** When the skill made a choice (which item to pick, which test to write first, which deploy step to run), was the choice justified by the inputs available to it? Mistakes uncovered are findings against the *skill*, not the *cycle*. If the skill's prose is ambiguous, that's a `should-fix` proposal targeting the prose. If the skill missed a step, that's a `blocker`. ### 2. Severity bar Two severities. **No third tier.** - **blocker** — the skill failed its job, broke an invariant, or has prose that will reliably mislead the next invocation into the same failure. - **should-fix** — the skill's prose has a real gap that will surface again under different inputs, or it's missing a guard the run revealed it needs. Skip nitpicks (style, wording, "could be clearer", "what if"). If after honest examination you have zero findings at this bar, that's a clean result — report it and stop. ### 3. Write the update — direct or sidecar **Before drafting ANY content, build the change-intent table.** This is the anti-scope-creep hard gate. For the target skill, list every line-level change you intend to make in the draft, one row per change, and map each to the specific transcript line(s) that motivate it: ``` | # | kind (add/delete/rewrite) | section / anchor in the skill | motivating citation | | 1 | rewrite | §0.2 "clean git state" bullet | 01_.txt:L123 (ran `git status` with .claude/skills/ dirty, correctly proceeded but prose says "stop") | | 2 | add | §Hard rules, last bullet | 01_.txt:L298 (chained `git stash && checkout HEAD~1`, clobbered tree, ran `git fsck --lost-found`) | ``` **If you can't fill in the "motivating citation" column for a row, drop that row.** No exceptions for "while I was in here I noticed," "this would also be nice," "for consistency," or "future-proofing." Those are speculative improvements and belong to a future cycle where something actually goes wrong. The findings you articulated in §1–2 define the scope; the change-intent table MUST be a strict subset of motivations that appear in the transcript, not a superset. **Count check.** If your change-intent table has more rows than the findings you enumerated in §1, stop and reconcile: either (a) you elided a finding in §1 that should have been listed separately — add it, or (b) one of the table rows is scope creep — drop it. Exactly one of those is true. A patch that makes 3 changes from 2 findings is the failure mode the framework is trying to prevent. Once the change-intent table passes both gates (every row cited, row-count ≤ finding-count), then draft the full rewritten `SKILL.md` (frontmatter + body). Bump `version:` per SemVer: patch for prose clarification, minor for added behavior, major for changed contract. Then route the write based on (a) whether the skill is proprietary or transferable, and (b) the chain's `auto-promote` value from §Inputs step 1. **Routing table:** | auto-promote | Proprietary skill | Transferable skill | | :--- | :--- | :--- | | `off` | sidecar `SKILL.patch.md` | sidecar `SKILL.patch.md` | | `proprietary`| direct overwrite `SKILL.md`| sidecar `SKILL.patch.md` | | `all` | direct overwrite `SKILL.md`| direct overwrite `SKILL.md` iff §4 sanitization returns `must-fix: 0`; else sidecar | Target paths: - **Proprietary**: `/.claude/skills//SKILL.md` or `.../SKILL.patch.md`. - **Transferable** (runtime-effective location): `~/.claude/skills//SKILL.md` or `.../SKILL.patch.md`. This is the path the harness actually reads on the next run. A separate sanitized copy for the open-source master repo still lands at `~/Dev/skill-set/skills///SKILL.md` — but that update is staged (not committed) and surfaced in the verdict file for the user's PR flow; NEVER auto-commit anything in the master repo. **Execute every write via `bin/apply-skill-patch.py` through the Bash tool.** Do NOT use the `Edit` or `Write` tools on any `.claude/skills/**` target. Those tools prompt for interactive approval on every `.claude/skills/` write even under `--permission-mode bypassPermissions`, which silently blocks headless runs and fires the denial → "fall back to sidecar" failure mode. Write the drafted body to `/drafts/.md` first (the run dir IS writable via `Write`), then: ```bash /home/rob/Dev/skill-set/bin/apply-skill-patch.py \ --source /drafts/.md \ --target ``` The `--target` is the path from the routing table above (`SKILL.md` for direct overwrite, `SKILL.patch.md` for sidecar). The helper is pre-allow-listed as `Bash(/home/rob/Dev/skill-set/bin/apply-skill-patch.py:*)`, so the Bash call does not prompt. `--backup` is intentionally omitted from the supervisor's automated path: git history covers rollback, and the `.bak` files otherwise surface as persistent untracked cruft in `git status` after every cycle. The flag still exists on the helper for ad-hoc human use, just don't pass it from the supervisor. See §Permissions contract for the full rationale. If the helper exits non-zero (e.g. target path rejected), that's a bug to report in the verdict, not an excuse to switch modes. Never "fall back" from direct overwrite to sidecar because one tool call failed. The `SKILL.patch.md` file is a **drop-in replacement**: it contains full YAML frontmatter + body, identical in shape to a normal SKILL.md. No proposal-wrapper headers, no rationale section in the file itself. All rationale + citations live in the verdict file (§6). If a prior cycle left a stale `SKILL.patch.md` on a skill that this cycle has no finding for, **do not touch it** — the user may be mid-review. Only overwrite a sidecar when this cycle has a fresh finding for that skill. ### 3.5. Batch-window refinement loop (self-tune) The dev skill's batching contract (`sst-dev-cycle` §1) sizes each cycle's batch against per-difficulty token-window targets (e.g. `[easy]` 100-200k, `[medium]` 200-300k, `[hard]` 400-500k input tokens). The dev's review counterpart (`sst-dev-review`) tags any cycle that falls outside the band with a `[batch-sizing]` finding. Those findings are honest empirical signal: the dev's chunk-shape estimates are wrong (drift from real cost-per-section), the band edges are mis-tuned, or a missing chunk-shape entry is causing the dev to systematically under- or over-pack the batch. Left alone, the windowing contract stays honor-system and the dev never learns from the misses. §3.5 closes the loop: the supervisor watches the trailing window of `[batch-sizing]` findings, and on accumulated signal authors a prose patch refining the dev's window-target text. Over many runs the dev's prose converges on observed reality. This step runs UNCONDITIONALLY (regardless of whether this iter has other findings). On most iters it returns "no refinement needed" without writing anything; on the rare iter where the trailing-window threshold trips, it writes a single refinement patch to `sst-dev-cycle` (transferable) and the proprietary mirror named per the chain's proprietary skills. The §0.5 fast-path's condition #5 calls §3.5.1 eagerly so refinement still fires on otherwise-clean iters. #### 3.5.1. Trigger evaluation (cheap; runs every iter) Scan the trailing window of recent dev-review transcripts and iter MANIFESTs. Define the window: - **Trailing iter set.** For multi-iter runs, walk backward from this iter through `/iter_/` directories where K = 1, 2, ..., up to 20 (the `M=5 in trailing 20` window's outer bound). For single-iter runs, walk backward through the most recent `/.skill-runs/*/` directories sorted by name (timestamp-prefixed); each single-iter run contributes one iter to the trailing set. Stop when fewer than 20 iters are available; partial windows are fine (the thresholds are minimums, not minimums-of-a-fixed-window). - **`[batch-sizing]` finding extraction.** For each iter in the trailing set, locate the dev-review transcript (the file whose name matches the chain's review skill — e.g. `01_sst-dev-review.txt` or `01_.txt` per the chain definition). Grep for lines matching `\[batch-sizing\]` (any position on the line, case-sensitive — the tag is framework-canonical). The primary extraction target is the machine-parseable summary line emitted by `sst-dev-review §2.10` in the format `[batch-sizing] direction= difficulty= actual=k band=-k`; the any-position match also catches legacy prose-embedded mentions. Each match is one finding; capture the `direction` token from the `direction=` key on the matched line, or from the first occurrence of `undersized` | `oversized` anywhere on the line when no key is present. Capture the iter's primary difficulty from the `difficulty=` key when present, else from `iter_manifest.difficulty`, else from the `[picked-difficulty: ]` sentinel in the iter's dev transcript. Compute the trigger conditions: 1. **Same-direction streak (default N=3):** `N` consecutive most-recent iters in the same difficulty band all carry a `[batch-sizing]` finding with the same `direction`. "Same difficulty band" matters because an `[easy]` undersizing and a `[hard]` undersizing are different prose problems (different chunk-shape estimates) and shouldn't be lumped. The streak counts iters, not findings — a single iter with two `[batch-sizing]` findings (rare) still counts as one streak step. 2. **Trailing-window total (default M=5):** total `[batch-sizing]` findings across the trailing 20 iters is ≥ M, regardless of difficulty band or direction. The total-trigger catches diffuse drift that doesn't form a streak (e.g. an `easy` undersize, a `medium` oversize, an `easy` undersize, a `hard` oversize, an `easy` undersize: no streak, but real dispersion that says the windowing is mis-tuned across the board). 3. **Stable-termination override (default K=10):** if the most recent K iters all carry zero `[batch-sizing]` findings AND a prior cycle's verdict file recorded a `## Batch-window refinement: monitoring (K=)` block, the loop is in stable-termination mode. Suppress trigger evaluation entirely; return "no refinement needed (monitoring)". Re-engage the moment a `[batch-sizing]` finding lands again (the K-streak resets to zero on the next finding). Defaults are the framework's published values; do NOT vary them per cycle (a refinement that lowers N to chase a single iter's noise is the exact failure mode the trigger thresholds defend against). They MAY be raised per project via a future SPEC change; until then, treat them as constants. If neither trigger fires AND stable-termination is not in force, return "no refinement needed (below threshold)". If the trailing window has fewer iters than the smallest threshold permits a meaningful read (typically <3 iters), return "no refinement needed (insufficient trailing window)". If a trigger fires, capture the trigger metadata for §3.5.2: which trigger (`streak` or `total`), which difficulty band (for streak triggers), the dominant direction (`undersized` | `oversized` | `mixed` for total triggers), the iter range cited, and the count of `[batch-sizing]` findings within that range. #### 3.5.2. Refinement decision (only when trigger fires) Decide WHAT prose adjustment to write. There are three legal refinement kinds; pick exactly one per cycle (do not bundle multiple refinements; the next cycle's trailing-window read will surface the next-needed one): 1. **Adjust a band edge** — when a streak trigger fires in a single difficulty band with a single direction. Move the edge by a single increment (~10-20% of the current edge value), in the direction the data implies: streak-undersized in `[medium]` → raise the lower edge of `[medium]` (the dev was under-packing because the floor was too low to motivate batching); streak-oversized in `[medium]` → lower the upper edge (the dev was over-packing because the ceiling permitted it). Do NOT cross-tier (an `[easy]`-band edge change must stay inside `[easy]`'s neighbors; never let `[easy]`-upper > `[medium]`-lower). 2. **Refine a chunk-shape estimate** — when the trigger metadata implicates a specific chunk shape mentioned in the dev's prose (e.g. "supervisor + sanitize sub-skill: ~50-80k", "transferable prose patch: ~30-60k"). Tighten or widen the estimate by a single increment based on the trailing iters' actual cost; cite the iter range as the empirical basis in the patch's commit-style prose. 3. **Add an empirical chunk-shape entry** — when the trailing iters consistently hit a chunk shape NOT already named in the dev's prose (e.g. a runner-changes iter consistently consumed ~80-120k with no estimate to compare against, biasing the dev's whole-cycle estimate). Append a single new entry to the dev's chunk-shape list, with the observed range bracketed conservatively. Refinements MUST stay inside the windowing-prose surface. Patches MUST NOT: - **Invent new section structure.** No new top-level sections, no new subsection numbering, no new contract surfaces. The refinement loop adjusts text inside the existing batching contract; it does not author the contract. - **Change the difficulty enum.** `[easy] | [medium] | [hard]` is a SPEC-defined contract; adding `[trivial]` or `[xhard]` requires a SPEC change first. - **Touch the per-skill model-floor / effort-floor table.** Routing floors are a separate concern (the routing spec phase); the refinement loop is windowing-only. - **Bundle a refinement with an unrelated improvement.** "While I was in here I also tightened §2's tone" is the scope-creep failure mode §3 already forbids; §3.5 inherits the same gate. The change-intent table for the refinement patch (§3) MUST contain exactly one row, and that row's motivating citation is the trigger-metadata line range from §3.5.1. If the trigger fires but the implicated change does not fit any of the three legal refinement kinds (e.g. the dev's prose has no chunk-shape entry that maps to the misbehaving cost shape, AND adding one would require renaming an existing entry), DO NOT write a hybrid patch. Record the refinement as `[deferred: shape-mismatch]` in the verdict (under "Updates written" with a one-line note explaining why the fix exceeds the legal refinement surface) and surface it in `## Notes for the manager`. The manager can route the case to the user as a SPEC change for a future cycle. The refinement loop is conservative on purpose: a too-broad patch that cascades into unrelated prose is worse than a deferred refinement that the user reviews directly. #### 3.5.3. Write the refinement patch (only when trigger fires AND refinement is in-surface) Author the full rewritten dev `SKILL.md` body — frontmatter (with bumped patch-level `version:`) + body with exactly the §3.5.2 prose change applied. SemVer guidance: a band-edge or chunk-shape-estimate adjustment is patch-level (clarification of existing prose); an empirical chunk-shape entry add is minor-level (added behavior in the windowing prose). No major bumps from §3.5; a major bump would imply contract change, which §3.5 is forbidden from authoring per §3.5.2. The dev skill is a `(transferable, proprietary)` pair. Write BOTH targets per the chain's `auto-promote:` mode using the §3 routing table: the transferable `sst-dev-cycle` AND its proprietary mirror named in the chain definition. Use `bin/apply-skill-patch.py` per §Permissions contract for both writes. Sanitize the transferable per §4 first; a `must-fix` finding aborts the transferable write and the proprietary mirror still receives the patch (so the loop's learning is not lost; the proprietary stays ahead of the transferable until the next sanitization-clean cycle promotes it). Record both writes in the verdict's "Updates written" block per §6. The proprietary mirror's body typically inherits the windowing prose from the transferable verbatim plus project-specific overrides (chunk-shape estimates that include the project's own per-skill costs, e.g. a custom deploy step that doesn't exist in the transferable). When the refinement is to a piece of prose that exists ONLY in the proprietary mirror (not in the transferable), skip the transferable write entirely — record `transferable: (no change; refinement is in proprietary-specific prose only)` in the verdict. #### 3.5.4. Stable-termination bookkeeping (always written, even when no refinement) Whether or not a refinement was written this iter, append a single block to the verdict file under a `## Batch-window refinement` header: ``` ## Batch-window refinement - Trigger evaluation: - Trailing window scanned: iters ; `[batch-sizing]` findings: ; same-direction streak: @ ; total in trailing 20: - Outcome: →v + v→v | no refinement needed | deferred: shape-mismatch | monitoring (K=)> ``` The next iter's §3.5.1 reads this block from the trailing iters' verdicts to know whether stable-termination was previously in force. Continuity is the contract: a clean K-streak produces a single `monitoring (K=)` block per iter (incrementing); a `[batch-sizing]` finding next iter resets the K counter to zero AND demotes the outcome to `below threshold` until the streak or total triggers fire again. The `## Batch-window refinement` block is also written under the §0.5 fast-path verdict (after the `## Updates written` block). Fast-path verdicts that omit the block break stable-termination continuity for downstream iters; the eligibility check at §0.5.5 already runs §3.5.1, so the block's content is computed regardless. #### 3.5.5. Anti-fork constraints summary - Refinement patches stay inside the windowing-prose surface (band edges, chunk-shape estimates, empirical chunk-shape entries). - Triggers (N, M, K) are framework constants; do not vary per cycle. - One refinement kind per cycle; multiple in-surface needs queue across iters. - Trailing-window scan is read-only against transcripts and verdicts; never re-runs analysis on prior iters. - The refinement loop never authors the windowing contract itself (no new sections, no enum changes, no routing-floor touches). ### 4. Sanitize (any transferable write, direct or sidecar) Before writing to ANY transferable target — whether that's a direct overwrite at `~/.claude/skills//SKILL.md` (auto-promote: `all`), a sidecar at `~/.claude/skills//SKILL.patch.md`, or the master-repo staged copy at `~/Dev/skill-set/skills///SKILL.md` — run the proposed body through `sst-sanitize-transferable`: 1. Write the proposed body to a temp file (e.g. `/transferable-draft-.md`). 2. Invoke `/sst-sanitize-transferable --project-context `. 3. Read the resulting `.findings.md`. Categorize: - **Any `must-fix` findings** → abort every transferable write for this skill (runtime path AND master-repo path). The lesson stays as a proprietary-only update, with a note in the verdict file: `(transferable promotion blocked by sst-sanitize-transferable findings; see .findings.md)`. - **`should-fix` findings only** → either rewrite the draft to address them all, or downgrade to proprietary-only. - **Zero findings or only `nit`** → safe to write the transferable targets. If `auto-promote: all`, overwrite the runtime `SKILL.md`; otherwise write the runtime-path sidecar `SKILL.patch.md`. In both cases, also write the master-repo sanitized copy (staged, not committed). Append the `Sanitization checklist` footer from the findings file to the verdict entry for that skill, filled with per-category counts. Sanitization is judgment-based; it's an LLM pass against `~/Dev/skill-set/templates/sanitization-guidance.md` plus the per-project banned-terms list. Do not try to grep — `sst-sanitize-transferable` exists precisely so the supervisor doesn't have to play regex games. ### 5. Update docs/TODO.md (rare) If any finding implies the *project* (not the skill) needs follow-up work — for example, the run revealed an unhandled production state the project's spec doesn't cover — append a single line to `docs/TODO.md`'s `## Next up` section: ``` - [supervisor] — supervisor verdict ``` Do not move existing entries; do not touch `## In flight` or `## Just shipped`. ### 6. Write the verdict file `/supervisor_verdict.md`: ```markdown # Supervisor verdict — **Chain:** · **auto-promote:** · **Commit:** · **Generated:** ## Outcome clean | updates | escalate ## Per-skill summary - `` (``): findings; direct overwrite | sidecar SKILL.patch.md | transferable blocked by sanitization> - ... ## Updates written For each update, record the change-intent table from §3 verbatim. This is the auditable evidence that no row was added without a transcript-line citation. Readers (the manager skill, the user, the next supervisor run) can confirm at a glance that changes = findings. ``` - direct: — v→v, , one-line summary. Change-intent table: 1. @
— _.txt:> 2. @
— _.txt:> - sidecar: — v→v, , one-line summary. Change-intent table: (same shape) Promote with: /sst-promote-skill-proposal - master-repo (staged, not committed): — for transferable updates written in `all` mode with clean sanitization. User opens the PR. - (or: none) ``` A row without a citation in this section is a bug — re-verify before signing off. The manager skill treats a missing-citation verdict as an escalation signal on its next poll. ## Sanitization footers (Appended verbatim from `.findings.md` for each transferable write, per §4. Omit entirely when no transferable writes happened.) ## Notes for the manager ``` ### 7. Escalate when warranted Set the verdict outcome to `escalate` (and write a note to the manager) when: - The same blocker has surfaced in 2+ consecutive runs (the prior verdict_*.md files in adjacent run dirs will tell you). - The skill's commit landed on the wrong branch, on top of someone else's work, or rewrote history. - A `sst-sanitize-transferable` rejection happened (so the user knows the system caught something potentially sensitive, even though the proposal didn't ship to the master repo). Escalation does NOT change what the supervisor writes; it just sets a flag the manager will pick up and surface to the user. ### 8. Exit gate — completion invariant before returning This is the LAST step of every supervisor session. Do not return until both invariants hold; the chain runner has no way to detect a partial-completion exit, so the discipline is enforced here. 1. **Drafts directory accounted for.** List `/drafts/` (or for multi-iter runs, `/drafts/`). For each file present, confirm one of: - A matching `apply-skill-patch.py` invocation appears in this session's transcript AND the target file exists at the expected path; OR - The verdict file (§6) carries a `[deferred]` block naming this draft and the reason it was not applied (e.g. `sst-sanitize-transferable` returned `must-fix`, the helper exited non-zero on path validation, the draft was rendered moot by a parallel finding). 2. **Verdict file exists.** `/supervisor_verdict.md` MUST be written before returning, even when the outcome is `clean`. A clean run produces a one-line verdict (no findings, no updates) so the manager skill, the user, and the next iteration's §0.6 sweep can confirm the prior session completed cleanly. A clean run with no verdict file is indistinguishable from a partial-completion failure. If either invariant fails, do not return. Either complete the missing apply step + verdict write, or write a `[deferred]` block per orphaned draft. The contract is simple: "drafts written → drafts applied OR explicitly deferred in verdict"; nothing falls through the cracks. `[deferred]` block format (extends the §6 "Updates written" section): ``` - [deferred]: — would have written to ; not applied because . Picked up next iter via §0.6 sweep. ``` The next iter's §0.6 sweep treats a `[deferred]` draft as a manager-injected finding (the reason field is the citation-equivalent: a real prior-iter transcript artifact describes the intended write). A run that exits with a non-empty `drafts/` AND no `[deferred]` blocks AND no matching apply invocations is a contract violation; the next iter's sweep will still pick up the orphans, but the gap should be flagged in `## Notes for the manager`. ## Permissions contract — write SKILL.md via the helper script, NOT via Edit/Write Claude Code's Edit/Write tools prompt for user approval on every write under `.claude/skills/**` — both `--dangerously-skip-permissions` and `--permission-mode bypassPermissions` have been empirically confirmed to still fire the prompt there, despite docs suggesting otherwise. That blocks every supervisor run whose only job is to rewrite a peer SKILL.md. **Therefore: do every direct-overwrite and sidecar write via `bin/apply-skill-patch.py`, invoked through the Bash tool.** The script writes the file in its own Python process, not via a Claude tool, so the tool-level permission gate doesn't apply. Bash-tool invocations are gated separately, and this script's invocation pattern is pre-allowed in global settings: ``` Bash(/home/rob/Dev/skill-set/bin/apply-skill-patch.py:*) ``` Invoke like this (draft the full replacement body to a temp file first, then apply): ```bash # 1. Write the draft body (full frontmatter + body, a drop-in SKILL.md) to a # temp location the Edit/Write tools ARE allowed to write to (the run-dir): /drafts/.md # 2. Apply it via the helper. --backup is intentionally omitted from the # supervisor's automated path: git history covers rollback, and the # .bak files surface as persistent untracked cruft otherwise. The flag # still exists on the helper for ad-hoc human use; just don't pass it # from the supervisor. /home/rob/Dev/skill-set/bin/apply-skill-patch.py \ --source /drafts/.md \ --target ``` The script refuses any target that isn't `SKILL.md` / `SKILL.patch.md` under an approved skills root (`~/.claude/skills/`, `/.claude/skills/`, `~/Dev/skill-set/skills/`, `~/Dev/skill-set-personal/skills/`, or `~/.claude/commands/`, `~/.claude/agents/`). Anything outside exits with a clear `refusing:` message and non-zero status — don't try to work around it. Manual supervisor runs outside the chain runner will need the same global allow rule to avoid Bash prompts; that's a one-time setup. Chain runs spawn with `--permission-mode bypassPermissions`, which still allows Bash invocations of allow-listed patterns without prompts. Do NOT fall back to Edit/Write on `.claude/skills/` targets and accept the prompts. Do NOT paste the proposed body into `/proposals/.patch.md` and call it a day — that's the pre-Phase-11 flow and skips the auto-promote that's the whole point of the mode. Use the helper. ## Output rules - **Write paths are limited to:** (a) the run-dir (verdict, sanitize drafts, findings files); (b) `/.claude/skills//SKILL.md` or `SKILL.patch.md` for proprietary updates; (c) `~/.claude/skills//SKILL.md` or `SKILL.patch.md` for transferable updates (runtime-effective path); (d) `~/Dev/skill-set/skills///SKILL.md` for the master-repo staged sanitized copy of a transferable update; (e) `docs/TODO.md` under `## Next up` (rare). Never elsewhere. - **Never call git.** No commits, no pushes, no branch creation. Direct overwrites to SKILL.md are left unstaged under `/.claude/skills/` (often gitignored anyway) and staged-but-uncommitted under `~/Dev/skill-set/` so the user can open the PR with the sanitization footer from the verdict file. - **Never deploy.** No SSH, no service restarts, no curl against a live site. - **Never touch a stale `SKILL.patch.md` you didn't just write.** If this cycle had no finding for a skill that already has a sidecar, leave the sidecar alone; the user may be mid-review. ## When invoked with no run-log dir argument Default to the most recent `.skill-runs/<*>/` directory under the current working directory. If none exists, exit cleanly with a one-line message — there's nothing to review.