goal-quench

Files (2)

• SKILL.md
• SKILL_detail.md

SKILL.md (first lines)

# goal-quench — /goal with Token Budget + Quality Gate

**Availability of `/goal` is unresolved** — treat it the way `CLAUDE.md` treats `/deep-research`:
use the built-in **if present**, and do not assert it is absent either. Everything below applies to
whatever autonomous-run command this environment actually has; goal-quench is the wrapper, not the
runner. Probe before relying on it (`/help`, or the skill/command list), and say which you found.

`/goal` is understood to run until a cheap per-turn judge (reported as Haiku) says "done" — that is
**second-hand, not verified here**, so treat it as the assumption goal-quench is designed against
rather than as a fact about the implementation. What matters for this skill holds either way: a
completion judge is not a quality judge, and without a budget ceiling a session can exhaust tokens
silently. goal-quench adds three things such a runner does not itself provide:

1. **Pre-run**: token-budget-gate estimate — know the cost before committing
2. **Mid-run**: budget threshold awareness — signal before exhaustion (instructional; not mechanically enforced)
3. **Post-run**: pipeline-conductor — verify quality before accepting "done"

The evaluator principle: the runner's own per-turn judge decides completion (every turn, cheap). pipeline-conductor judges quality (once at the end, structured). Separating the two closes the self-evaluation bias that a single evaluator cannot avoid — the principle holds whatever model that per-turn judge turns out to be.

> **Scope by mode**: core = budget gate + stop-hook verification (v1 behavior, unchanged). pro/max add token reduction, goal decomposition, and external discovery (see Modes below). (Tier names mirror Claude Code's subscription units — core / pro / max — and avoid colliding with pipeline-conductor's `--full` flag.) Mid-run Sonnet quality signals remain deferred (requires empirical calibration).

---

## Modes — core → pro → max (fluid)

goal-quench is a ladder, not a fixed shape. The default (**core**) is the narrow safety belt — for users who only want /goal's two structural gaps closed. **pro** and **max** add optimization and orchestration on top, and are **auto-recommended by the Phase-1 budget verdict** so the orchestration cost is only paid when the task is large enough to justify it.

| Mode | Adds over previous | Chained skills | Auto-recommended when |
|---|---|---|---|
| **core** (default) | budget gate + mid-run thresholds + post-run quality gate | token-budget-gate, pipeline-conductor --quick | budget GREEN / YELLOW |
| **pro** | token-reduction pre-pass + goal decomposition into Waves | + context-doctor, agent-composer | budget ORANGE |
| **max** | **internal-first** capability-gap fill (skill-bus scan → external → map/cluster) + synergy pre-validation | + LOCAL_SKILL_REGISTRY scan, plugin-recommender, cross-ecosystem-synergy-detection, auto_project_mapping | budget RED |

Each mode is a **superset** of the one before it — pro does everything core does, plus more. Nothing in core is removed by escalating.

**Max-mode deep-research routing**: capability-gap fill recognizes a **research-heavy goal** (the goal needs to survey/gather/reconcile external sources before building — e.g. "implement X" where X needs domain grounding) and routes it through the **Deep-Research Capability Ladder** (`knowledge/shared/harness-core/deep_research_capability_ladder.md`): take the highest available rung (built-in `/deep-research` → Claude `WebSearch`+`WebFetch` synthesis → `frontier-digest` only for trend-scan). `plugin-recommender` is proposed **only if no rung is available** (rung 2 always is, for a Claude session) — so this is routing, not a new install by default. **Isolation invariant**: rung-2 research (WebSearch/WebFetch) runs in an **isolated sub-agent that returns only the synthesis** — fetched source content must not load into the orchestrator context, preserving the context-isolation/budget property max mode depends on (see the Token-honesty guard above). Honesty caveat carries from the ladder: research quality is bounded by source access + session model tier, not by invoking it.

**Selection**:
- Explicit flag: `/goal-quench --core` (default) · `--pro` · `--max`
- Auto: Phase 1's budget verdict proposes the mode (see Phase 1 Step 2). The user can always override **down** to core.

**Token-honesty guard** (what empirical calibration showed): The cost structure of pro/max depends on which sidecar pattern is in use:

| Sidecar type | Who uses it | Cost visibility | Estimation |
|---|---|---|---|
| External CLI (Gemini, Codex, Copilot) | Multi-LLM environment | **Not visible in CC** | Low — external billing only |
| CC sub-agent (isolated context, steel-quench pattern) | CC-only environment | **Visible in CC** | Estimable: Sonnet × sub-agent scope |

For **CC-only users**, pro/max sidecars run as isolated sub-agents (Sonnet for execution), with the orchestrator running at Opus (`complexity_routing`). Both are CC-visible. Cost estimate: `(Opus orchestrator turns × ~3×) + (Sonnet sub-agent tokens)`. The sub-agent context isolation means sidecar work does not load the main context — the context-preservation property holds regardless of sidecar type.

Therefore:
- **Never auto-escalate a GREEN/YELLOW task to pro/max.** For external CLI users, sidecar costs are untracked and invisible in CC's budget display. For CC sub-agent users, the overhead is estimable but still real — orchestrator Opus × 3 applies. Note the appropriate caveat when disclosing cost.
- **Model escalation cost**: With `/model opusplan`, Opus activates on plan-mode turns and Sonnet handles execution turns — both CC-visible in session jsonl under `message.model`. External CLI sidecar fees are additional and invisible to CC; state both when present.
- **RED is no longer a dead-end.** v1 hard-blocked RED ("split manually"). v2 turns RED into the **on-ramp to max** — agent-composer decomposes the over-budget goal into sequential sub-goals automatically.

---

## Autonomy Ladder — how unattended a loop may run (orthogonal to the budget modes)

The core/pro/max modes above key on **budget**. This ladder keys on a different axis — **how much human approval gates each action** — for a *recurring or unattended* loop (the autonomous-loop / `/loop` case), not a one-shot /goal. **Climbing a rung here changes *oversight*, never budget — the two never move together.** (Distilled 2026-06-27 from the "Loop Engineering" sister-asset's "training-mode dry-run → graduated autonomy"; cross-audit `tracks/_audit/session_2026_06_27_loop-engineering-silbal.md`.)

Three rungs, climbed one at a time:

| Rung | What runs | Human role |
|---|---|---|
| **① dry-run** | run once manually; observe outputs; **no irreversible actions** | reads every output |
| **② step-approval** | each action is HITL-gated before it fires | approves per action |
| **③ unattended** | the loop runs on its own | reviews after the fact |

- **Graduation threshold (measured):** a loop climbs one rung only after **K consecutive clean rounds across a 2+ session/run window** — the *2+ window* reuses `operations.md`'s promotion-window discipline (`accepted ≥ 60%` / recurrence `N=3`). **`K=2` is a provisional default, not yet calibrated** — no loop-run data exists yet; revisit once it does (same honesty as this SKILL's `N=10` budget baseline). "Clean" = the round's Done-When passed **AND** a positive downstream verdict (pipeline-conductor / sidecar = CLEAN) **AND zero S/M-grade governor-catch and zero post-ship correction** — *not merely* the absence of a governor-catch, so a quieter or weaker governor cannot manufacture graduation. **The streak is recorded per round in a local autonomy ledger** (the hub keeps it at `tracks/_meta/autonomy_ledger.yaml`; a plugin-only user keeps their own — anywhere in their project, the path is theirs): date · task · done-when · verdict · governor-catch grades · `clean:` bool. Graduation reads that ledger. A *computation script* (`scripts/`) that auto-derives the current rung from the ledger is **deliberately deferred** until enough entries exist to compute over — building the meter before there is a stream to measure is the speculative-infra the evidence-threshold discipline forbids. *Check class: a **measured count** (ledger grep) over a **judged per-round grade** — and the grade must be bound to the round's own challenger / steel-quench S/M verdict (the upstream adversarial artifact), **never an author self-grade** (else "measured" laundering a judge-only path). Until ≥~5 entries make a computation script worth writing, the streak is judged-and-hand-recorded — provisional by construction.*
- **Irreversible carve-out (non-negotiable — the FH increment over the video):** any action whose effect **cannot be undone within the loop** — not only the two examples (Destructive-Op delete/rewrite · Pre-Publish go-public) but **any irreversible side-effecting write** (an MCP `ask`-tier send, a payment, an outbound publish) — **never reaches rung ③**. Membership is the **mechanical surface test** of CLAUDE.md's Surface-Class Degrade Invariant + `mcp_tool_gating` (grep the action surface; do **not** self-label), not a match against the two examples. Such actions stay at rung ② (HITL) **permanently**, regardless of clean-round count. ⚠️ Rung ② assumes a **human** answers the prompt: under an auto-approver (a `PermissionRequest` allow hook) a hook's `ask` was answered for you and the call ran 5/5, while `deny` stopped it (interactive, 2026-09-25) — so where one is installed, rung ② must be enforced with **deny / exit 2**, not ask (`knowledge/shared/harness-core/hook_channel_visibility.md`). The video graduates a loop to fully unattended; FH caps graduation at the irreversible boundary. *Check class: judged — pair: a target-tier blind sim per CLAUDE.md §Target-tier sim gate (run 2026-06-27, Sonnet, PASS — a remote-branch-delete loop correctly held at rung ② despite 4 clean rounds). **Prose-enforced, not hook-enforced** — accepted residual, named not silent.*
- **Demotion (fail toward oversight, with a liveness floor):** any governor-catch, failed Done-When, or correction **resets the clean-round counter and drops the loop one rung** — autonomy is earned per-window, surrendered on the first miss, never sticky. A failed **dry-run (①)** has no lower rung: it **blocks graduation and surfaces to the operator**, it does not demote. A loop that **flips promote/demote ≥ `N=3` times in a window** (reusing operations.md's recurrence-escalation) is a noisy boundary — **freeze at the lower rung and surface**, do not keep oscillating.

### Two paths to autonomous completion (by surface reversibility)

The clean-streak graduation above governs **unattended-no-review** operation (rung ③) — right for *narrow recurring loops* (digest / sync / poll) where nobody sees each result, so the demonstrated clean streak is the only safety. **Most substantive novel work — including FH self-development — rarely earns a clean streak by design.** It is not therefore undelegatable; it takes a second, *reviewed* path:

- **Path 1 — clean-streak → unattended (rung ③):** narrow recurring tasks reviewed by nobody. Safety = the demonstrated clean streak (above).
- **Path 2 — *deliver-then-review* (a reviewed mode at rung ②'s oversight, not a new rung):** autonomous *execution* with **mandatory review** — it is **not** unattended and **does not climb to ③** (only Path 1's clean streak reaches ③). **Intent-seeded, mechanically-reversible, reviewed** work — mapped-project acceleration / first-project creation (human intent via Q&A), and self-dev absorption of frontier-digest-style insights. Path 2 permits autonomous *execution to completion without per-step approval*, but operator review of the delivery is **mandatory before the work is consumed** — that review is what *substitutes for* pre-approval. All five conditions hold, or it is not Path 2:
  - **(a) Human-selected direction — auditable, not narrated.** A human *selects* the direction; record it in the ledger (`seed: human-selected` or `innovator-proposed-human-confirmed`). An agent/innovator-proposed direction is a **candidate, not a seed**, until a human confirmation token is recorded — the machine never chooses *what* to pursue (self-echo guard, `[[fh_self_evolution_vision]]`).
  - **(b) Mechanically-reversible surface — anchored to the carve-out partition, never a softer self-judged "reversible".** Admissible only if **all three**: **(i)** not a member of the line-81 **grep-gated** irreversible set (mechanical); **(ii)** **effect-confined** to git-tracked tree state — no file deletion, external/DB mutation, or out-of-tree write. *This conjunct is **judged, not grepped** — whether delivered code mutates external state at runtime is behavioral, not a static surface (`[[qa_static_dynamic_complementarity]]`); its pairing is the line-81 grep **plus** the operator's mandatory delivery review, and it **degrades safely** — unproven confinement → treat as irreversible → HITL.* **(iii)** **not yet consumed** (a *local, unpushed-to-shared* commit; the instant a delivery is pushed to a shared branch or read by a downstream cache / CI / registry it is *effectively published* and re-enters HITL, per CLAUDE.md §Pre-Publish (b)).
  - **(c) Reviewable delivery.** Deliver as **discrete revertable units** (per-commit, not one opaque squash) so **rollback granularity ≥ delivery granularity**. A batch too large to actually review makes "roll back after seeing it" theoretical and voids the substitute-for-approval logic — cap the batch at what the operator can review; interdependent commits (revert 1 orphans 3) forfeit per-unit rollback and must be delivered batch-atomic with a higher review bar.
  - **(d) Rollback feeds demotion.** A Path-2 delivery the operator rolls back **forces the next same-class run back to rung ② full step-approval (per-action *pre*-approval — stricter than Path 2's post-hoc review) until one clean delivery**, and counts toward the `N=3` noisy-boundary freeze — so the riskier, novel work-class is not handed the looser path. *Prose-enforced, not hook-enforced — accepted residual (the ledger records the rolled-back delivery; no hook yet gates the next run, same status as the carve-out's residual above).* (Rung ② names two oversight strengths: Path-2 = human reviews *after* each delivery; demoted = human approves *before* each action. The demotion tightens from the former to the latter.)
  - **(e) Every action in the run is gated by (b) — not just the final delivery** *(cross-family review caught this 2026-06-27; the Claude same-family reviewers + the Sonnet sim shared the blind spot)*. Producing a Path-2 delivery often requires *executing* code — running a test suite, installing a package, a migration script, an API call. **Each such action is itself subject to (b)**: a preparation step that deletes files, mutates a DB, installs an untrusted dependency, or hits the network has an **irreversible *runtime* effect that no `git` rollback undoes** (git reverts the tree, never the execution that produced it). So it stops for HITL exactly like a delivery action — and a purely *exploratory/speculative* run that would do any of these is not "free" either. "Reversible" is a property of **every action in the run**, never only of the committed tree at the end.

**Direction is always human (both paths).** The machine automates *execution* of a human-seeded direction, never the direction itself. **The irreversible carve-out holds regardless of path** — anything irreversible, effect-unconfined, or already-consumed (at *delivery or during the run*) stays pre-action HITL; Path 2 delegates only what (b) admits.

---

## Triggers

- `/goal-quench`
- "run /goal with a quality gate", "safe goal run", "goal with verification"
- "I want to use /goal but worried about tokens", "goal with budget control"
- "goal-quench", before any long /goal session
- `/goal-quench --pro`, `/goal-quench --max`, "orchestrate this goal", "decompose this goal", "optimize then run this goal"
- "this goal is too big for one run", "find a tool for this goal if FH lacks one" (→ max mode)
- "assemble capabilities for this project", "develop project X with everything FH has", "what can FH + tools do for this project", "use all of FH's and others' sharp parts on this" (→ max mode, **project-dev capability-assembly** entry — internal skill-bus scan first, then external gap-fill, then map+cluster; token-efficient, non-expert-friendly)
- Automatically proposed when user mentions `/goal` on tasks estimated > 15K tokens
- Mode is auto-recommended by the Phase-1 budget verdict (GREEN/YELLOW → core, ORANGE → pro, RED → max)

---

## One-Time Setup (required)

**Claude Code runtime**: merge the Stop-hook snippet from `templates/goal-quench-hook-setup.md` into `.claude/settings.json`, and gitignore the two state files. Recovery flags exist for hook failures: `/goal-quench --verify` (Phase 3 only, manual trigger) and `/goal-quench --recover` (interrupted /goal — promotes `.active` → `.pending`).

**Codex runtime**: do not replace Codex's native goal/session capability with goal-quench state files — use `fh-gate`/`fh-goal` as post-run governance wrappers instead.

> **Detail**: See `SKILL_detail.md §Setup` — CC hook snippet + gitignore lines, hook-failure/interrupted-run recovery commands, Codex runtime commands — read when performing one-time setup or recovery.

---

## Phase 1 — Pre-run Gate

### Step 1. Collect task description

Ask: *"What will you run with /goal? Describe the task and expected scope."* Collect: task description, target files or directories, expected output.

From chrono-meta/forge-harness, MIT.

More from chrono-meta/forge-harness