@chrono-meta/fh-gate 1.0.3 → 1.2.0

package/plugins/fh-commons/skills/deliberation/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: deliberation
+description: Multi-perspective synthesis structure — Innovator (propose) → Devil-Advocate (challenge) → Mediator (synthesize) 3-layer execution. Outputs conditional verdicts without binary win/loss. Activates on "deliberation", "battle this out", "weigh the pros and cons", "review from multiple angles", "which side is right?". Optional deep-insight persona jurors for domain-specific views. Designed for design decisions, skill proposals, and architectural choices.
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Agent"]
+model: opus
+origin: fh-meta
+---
+
+# deliberation — The Forge Skill
+
+Innovator (propose) → Devil (challenge) → Mediator (synthesize) 3-layer core structure.
+The goal is not to pick a winner — it is to **extract salvageable fragments from the losing argument and produce a conditional verdict**.
+Even those who struggle to challenge assumptions can use this structure as a rope to reach better decisions.
+
+> **Role distinction from sim-conductor and steel-quench**
+> - sim-conductor: **validates** quality and consistency of a completed asset
+> - steel-quench: **adversarially stress-tests** a near-complete artifact (post-build defect surfacing)
+> - deliberation: perspective clash during the **design decision process** → synthesis (upstream of both)
+
+---
+
+## Triggers
+
+- `/deliberation`
+- "battle this out", "make them argue", "clash and synthesize"
+- "review this decision from multiple angles"
+- When agent-composer Step 4-b proposes `Wave next-D` automatically
+
+### Natural Language Triggers (for general users — activates without internal vocabulary)
+
+Also activates when design decisions or perspective clashes are expressed in natural language:
+
+| Example phrase | Intent |
+|---|---|
+| "I'm not sure whether to do this or not" | Decision uncertainty → multi-perspective synthesis |
+| "It seems like opinions are divided" | Perspective clash → synthesis layer needed |
+| "Help me decide which side is right" | Conditional synthesis, not simple winner selection |
+| "Someone will probably object to this" | Request for devil's advocate perspective |
+| "Is it okay to keep going in this direction?" | Re-validation of design decision |
+| "Review this from multiple angles" | Multi-perspective synthesis → 3-layer default |
+| "Analyze this from all sides" | Multi-perspective synthesis → 3-layer default |
+| "Weigh the pros and cons" | Perspective clash → devil + innovator engaged |
+| "Analyze the strengths and weaknesses" | Pro/con structure → Innovator (pros) + Devil (cons) |
+| "Help me make a decision" | Decision support → conditional verdict generation |
+| "pros and cons", "pros cons" | Comparative analysis → synthesis layer needed |
+
+---
+
+## Step 0. Receive Topic + Select Layer
+
+If no input is provided, ask:
+```
+Please provide the deliberation topic.
+  - Topic: What are you trying to decide or design?
+  - Layer: [3-layer default (recommended)] / [5-layer — includes jury]
+  - Jury focus (if 5-layer selected): user experience / technical feasibility / business & policy
+```
+
+**Default: 3-layer** (Innovator → Devil → Mediator). Use 5-layer only when a jury is needed.
+
+**Execution log (workers_approved pattern)**:
+Upon completing Step 0, include the following in the output:
+```
+[DELIBERATION START] Topic: {topic} | Layer: {layer} | {timestamp}
+  → WORKER_CALL: Innovator (isolated instance)
+  → WORKER_CALL: Devil-Advocate (isolated instance)
+  → WORKER_CALL: Mediator (isolated instance — Cost of Consensus prevention)
+```
+
+Jury auto-selection criteria:
+| Topic nature | Recommended jury personas |
+|---|---|
+| New user experience related | `newcomer` + `power-user` |
+| Technical implementation feasibility | `persona-be` + `persona-fe` |
+| Business viability / policy / legal | `persona-pm` + `persona-business` |
+| General design decisions | No jury (3-layer is sufficient) |
+
+---
+
+## Step 1. Innovator Layer — Propose
+
+Invoke `deep-insight:persona-innovator`.
+
+> **Fallback (if deep-insight is not installed)**: Claude Code performs the Innovator role inline. Same instruction template and output format apply. The deliberation pipeline is guaranteed to work without deep-insight installed.
+
+> **No isolation (intentional)**: The Innovator is a proposal generator — it does not evaluate its own output, so Agent tool isolation is not needed. Cost of Consensus applies only to the Mediator, which **evaluates** its own generated content (arXiv 2605.00914). Only the Mediator (Step 3) is isolated via the Agent tool.
+
+Instruction template (meta-prompt-builder structure):
+```
+Goal: Generate the most creative and scalable proposals for {topic}
+Context: Current harness state + list of relevant assets
+Constraints: No duplication of existing assets / must not violate simplification guard
+Done When: 1~3 concrete proposals + 1-line rationale per proposal
+Brief limit: Total Context passed to Agent must be kept under 1200 characters
+```
+
+Output format:
+```
+[Innovator]
+  Proposal 1: {content} — Rationale: {1 line}
+  Proposal 2: {content} — Rationale: {1 line}
+  (optional) Proposal 3: {content} — Rationale: {1 line}
+```
+
+---
+
+## Step 2. Devil-Advocate Layer — Challenge
+
+Invoke `deep-insight:persona-devil-advocate`. Takes Step 1 output as input.
+
+> **Fallback (if deep-insight is not installed)**: `fh-commons:quench-challenger` (includes Devil DNA) or Claude Code performs the Devil-Advocate role inline. Same output format. Instance isolation is not required, same as Step 1.
+
+Instruction template:
+```
+Goal: Generate the sharpest single rebuttal for each of the {N} Innovator proposals
+Context: Innovator output + harness simplification guard + known failure patterns
+Constraints: No emotional rebuttals / no baseless negation / must include a hint toward improvement
+Done When: 1 rebuttal per proposal + 1-line core risk + 1-line acknowledgment of valid parts
+Brief limit: Total Context passed to Agent must be kept under 1200 characters
+```
+
+Output format:
+```
+[Devil-Advocate]
+  Proposal 1 rebuttal: {content}
+    Risk: {1 line}
+    Acknowledgment: {1 line}  ← this line is the Mediator's raw material
+  Proposal 2 rebuttal: ...
+```
+
+> **Acknowledgment line is mandatory**: The Devil must explicitly state "this part is valid" — synthesis is impossible without it.
+> A rebuttal with no acknowledgment is automatically flagged as `[WARN: unsynthesizable rebuttal]`.
+
+---
+
+## Step 3. Mediator Layer — Synthesize (Core)
+
+**[Isolation Principle — Cost of Consensus Response]**
+The Mediator invokes a separate instance via the `Agent` tool.
+When the same instance evaluates its own generated content, confirmation bias occurs (demonstrated in arXiv 2605.00914).
+Physical separation from the Innovator/Devil generation context is required for unbiased synthesis.
+
+> **What isolation means**: Blocks Self-Evaluation Bias — the tendency for an instance to favor its own output.
+> The Mediator reads the Innovator and Devil outputs, but does not share the **reasoning process that generated** those outputs.
+> Independence of the reasoning path — not mere information sharing — is the key to resolving Cost of Consensus.
+
+Agent invocation instruction (includes Context Card):
+```
+Goal: Synthesize Innovator and Devil-Advocate outputs into a conditional verdict
+Context: {full Step 1 output} + {full Step 2 output}
+Constraints: No simple selection of the winning argument / must extract fragments from the losing argument / no hedge language ("balance both sides") / output under 1200 characters
+Done When: All 5 sections output — Adopt / Alert absorption / Verdict / Conditions / Discard
+```
+
+**Synthesis formula**:
+```
+Core value of the Innovator proposal
+  + Valid alerts from Devil's rebuttal (extracted from the acknowledgment line)
+  → Conditional verdict: "{proposal} OK, provided {condition} is mandatory"
+```
+
+**What the Mediator must not do**:
+- Simply select the winning argument as-is (simple verdict = deliberation failure)
+- Discard the losing argument (fragment extraction is mandatory)
+- Use hedge expressions like "we should consider both sides in a balanced way"
+
+Output format:
+```
+[Mediator — Synthesis Verdict]
+  Adopt: Core of {Innovator Proposal N} — {value, 1 line}
+  Alert absorption: "{acknowledgment line}" from {Devil rebuttal} → converted to condition {X}
+  ─────────────────────────────────────────
+  Verdict: Proceed with {proposal} — OK
+  Conditions: {1~3 required conditions}
+  Discard: {fully rejected parts — with rationale}
+```
+
+---
+
+## Step 4 (Optional). Jury Layer — Domain Perspectives
+
+Runs only when 5-layer is selected. **Parallel** dispatch of 2~3 selected deep-insight personas via the `Agent` tool.
+
+> **Fallback (if deep-insight is not installed)**: dispatch the jury from real fh-meta agents instead — `persona-innovator` and `hub-persona-auditor` (and `fh-commons:quench-challenger` for an adversarial juror). Same parallel-Agent dispatch, juror cap, and output format apply. The 5-layer jury is guaranteed to run without deep-insight installed — mirroring the Step 1/Step 2 fallbacks.
+
+Juror count limit: **maximum 3**. If 4 or more are selected, output `[WARN: jury overload — noise risk]` and defer to the user.
+
+Instruction per juror:
+```
+Goal: Review the Mediator's synthesis verdict from the perspective of {persona}
+Context: Full output from Steps 1~3
+Constraints: Do not overturn the already-synthesized verdict / only propose additional conditions
+Done When: Agree / partial agreement / disagree + 1 line of additional conditions or risk
+```
+
+Output format:
+```
+[Jury: {persona name}]
+  Verdict: Agree / Partial agreement / Disagree
+  Opinion: {1~2 lines}
+  Additional condition: {1 line if applicable}
+```
+
+---
+
+## Step 5 (Optional). Mediator Final Synthesis
+
+Incorporates jury opinions to refine the Step 3 verdict.
+
+```
+[Final Verdict]
+  Based on: Step 3 synthesis verdict
+  Jury input: {N agreed / N partial / N disagreed}
+  Added conditions: {additional conditions from jury}
+  Final conclusion: {1~2 lines}
+```
+
+---
+
+## Automatic WARN Detection Patterns
+
+| Situation | WARN content |
+|---|---|
+| Devil rebuttal has no "acknowledgment" line | `[WARN: unsynthesizable rebuttal — Mediator lacks raw material]` |
+| Mediator adopts only one side's argument | `[WARN: simple verdict, not synthesis — deliberation failure]` |
+| Innovator and Devil share the same premise | `[WARN: no real clash — recommend redefining the topic]` |
+| 4 or more jurors selected | `[WARN: jury overload — reduce to 3 or fewer?]` |
+| Done When contains vague expressions | `[WARN: Done When is unmeasurable — share meta-prompt-builder WARN criteria]` |
+
+---
+
+## agent-composer Integration — Wave next-D
+
+Add the following condition to the agent-composer Step 4-b state transition gate:
+
+```
+| ⑤ Design decision clash or judgment that "a battle is needed" | Wave next-D | deliberation (S) |
+```
+
+`Wave next-D` activation criteria:
+- M/S/R results contain "2 or more mutually conflicting proposals"
+- User utterance includes "which side is right?", "they conflict", "both seem valid"
+- agent-composer cannot synthesize the fan-in results and is about to defer the decision to the user
+
+---
+
+## Design Principle — Why This Skill Exists
+
+It is a **rope** for those who have not yet dared to challenge.
+
+Thinking alone traps you in a single perspective. Only the courageous construct counterarguments themselves.
+deliberation provides that counterargument as structure — even those afraid of conflict can start a battle, because the Mediator will synthesize it for them.
+
+The Mediator's conditional verdict creates a safe entry point: "this is okay if you do it this way."
+The jury fills the domain blind spots that no single person can see on their own.
+
+**What the forge creates is not a winner — it is a new alloy.**
+
+---
+
+## Done When
+
+```
+All Steps 0~3 completed (Steps 4~5 added if 5-layer selected)
++ [Mediator — Synthesis Verdict] output present (Adopt / Alert absorption / Verdict / Conditions / Discard)
++ User's final decision confirmed (deliberation output must never be auto-executed)
+```
+
+**→ When invoked from agent-composer Wave next-D: synthesis verdict is the fan-in input for Wave continuation** — return the Mediator verdict + Conditions to agent-composer so the conflict is marked resolved in the fan-in result set. After this, agent-composer re-runs Step 4-b state transition evaluation with the conflict cleared; subsequent Waves (next-M / next-E / end) proceed based on the updated result.
+
+## Simplification Guard
+
+- Simple information queries → deliberation is unnecessary. Respond directly.
+- Cases where the answer is already clear → route to sim-conductor (validation) or harness-doctor (diagnosis).
+- If resolvable without a jury, 3-layer default is sufficient.
+- deliberation output always completes with the user's final decision. Auto-execution is prohibited.
+
+---
+
+## Related Skills
+
+| Situation | Related skill |
+|---|---|
+| Auto-triggered on design decision clash (Wave next-D) | `fh-meta:agent-composer` Step 4-b |
+| Validate quality and consistency of a completed asset | `fh-meta:sim-conductor` |
+| Validate skill candidates after deliberation | `fh-meta:harness-doctor` |
+| Implementation convergence loop after a decision | `fh-commons:convergence-loop` |

package/plugins/fh-commons/skills/mcp-circuit-breaker/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: mcp-circuit-breaker
+description: Detects MCP tool failure patterns and trips a circuit breaker to stop cascading retries. Proposes fallback alternatives and resets when the tool recovers. Triggers on "MCP failing", "tool keeps erroring", "circuit-breaker", repeated tool call failures.
+user-invocable: true
+allowed-tools: ["Read", "Bash", "Write"]
+model: sonnet
+complexity_routing:
+  base: sonnet
+  high: opus
+  escalate_when:
+    - multi_server_failure
+    - unknown_mcp_server
+---
+
+# mcp-circuit-breaker — MCP Tool Failure Guard
+
+MCP tools can fail silently or return partial results, leading to cascading retry loops that waste tokens and degrade session quality. This skill detects failure patterns, trips a circuit breaker to halt retries, proposes alternatives, and resets when the tool recovers.
+
+> **Scope distinction**
+> - Claude Code native retry: low-level transport retries (transparent, fast)
+> - mcp-circuit-breaker: **session-level guard** — detects repeated semantic failures, intervenes before token waste compounds
+
+---
+
+## Triggers
+
+- `/mcp-circuit-breaker`
+- "MCP failing", "MCP keeps erroring", "tool isn't working", "circuit-breaker"
+- "same error keeps happening", "tool call looping", "MCP timeout"
+- Automatic: when the same MCP tool name appears in 3+ consecutive failed calls within a session
+
+---
+
+## Circuit States
+
+```
+CLOSED   → Normal operation (tool calls pass through)
+OPEN     → Circuit tripped (calls blocked, alternatives proposed)
+HALF-OPEN → Recovery probe (1 test call allowed, resets if success)
+```
+
+Default thresholds:
+- **Trip threshold**: 3 consecutive failures of the same tool
+- **Half-open probe**: after 60s cooldown (or explicit user command)
+- **Reset**: 1 successful call in HALF-OPEN state → back to CLOSED
+
+---
+
+## Execution Steps
+
+### Step 1. Detect Failure Pattern
+
+Identify the failing tool and failure mode:
+
+```bash
+# Check MCP server config
+cat .claude/settings.json 2>/dev/null | grep -A5 '"mcpServers"' || echo "No MCP config found"
+```
+
+Classify failure type:
+
+| Type | Symptom | Likely Cause |
+|---|---|---|
+| `TIMEOUT` | Tool call hangs >30s | Server overload / network |
+| `AUTH` | 401 / 403 response | Credentials expired or missing |
+| `NOT_FOUND` | 404 / tool not available | Server down / tool removed |
+| `MALFORMED` | Parse error on response | Schema mismatch / API change |
+| `RATE_LIMIT` | 429 / quota exceeded | Too many calls |
+
+If failure type cannot be determined: classify as `UNKNOWN`.
+
+---
+
+### Step 2. Trip Decision
+
+Count consecutive failures of the identified tool in the current session context.
+
+| Count | Action |
+|---|---|
+| 1 | Log warning. Continue — *"MCP tool {name} failed once. Monitoring."* |
+| 2 | Escalate warning. Suggest checking server status. |
+| 3+ | **TRIP CIRCUIT** → output circuit open notice, block further calls to this tool |
+
+Circuit open notice format:
+```
+⚡ CIRCUIT OPEN — {tool-name}
+Failure type: {TYPE}  |  Consecutive failures: {N}
+Further calls to this tool are blocked until circuit resets.
+```
+
+---
+
+### Step 3. Log Circuit State
+
+Write state to session-local file (in-memory is insufficient — logs survive /clear):
+
+```bash
+mkdir -p .claude/mcp_circuit/
+# Append to circuit log
+```
+
+Log entry format:
+```yaml
+- tool: {tool-name}
+  state: OPEN
+  failure_type: {TYPE}
+  failure_count: {N}
+  tripped_at: {ISO-8601}
+  reset_at: null
+```
+
+---
+
+### Step 4. Propose Alternatives
+
+Present 3 fallback options ranked by effort:
+
+| Priority | Alternative | When to Use |
+|---|---|---|
+| **1 — Substitute tool** | Use a different MCP tool or built-in tool that covers the same task | Tool-specific failure (NOT_FOUND, AUTH) |
+| **2 — Degrade gracefully** | Skip the MCP step, note the gap, continue with available information | TIMEOUT / RATE_LIMIT |
+| **3 — Pause and retry** | Wait for server recovery (HALF-OPEN probe after cooldown) | Transient failure (TIMEOUT, RATE_LIMIT) |
+
+Output format:
+```
+## Fallback Options for {tool-name}
+
+Option 1 — Substitute: Use {alternative-tool} instead
+  → Command: [specific invocation]
+  → Gap: [what's different vs. original tool]
+
+Option 2 — Degrade: Skip this step, continue without {capability}
+  → Impact: [what is missing from the output]
+
+Option 3 — Retry after cooldown (60s)
+  → Run: /mcp-circuit-breaker reset {tool-name}
+```
+
+---
+
+### Step 5. Recovery Probe (HALF-OPEN)
+
+When user requests reset or after cooldown:
+
+```
+Sending HALF-OPEN probe to {tool-name}...
+```
+
+- 1 minimal test call is allowed through
+- If success: circuit → CLOSED, log updated
+- If fail: circuit remains OPEN, cooldown resets
+
+Reset log entry:
+```yaml
+  state: CLOSED
+  reset_at: {ISO-8601}
+  reset_method: probe_success | user_forced
+```
+
+---
+
+### Step 6. Report
+
+At session end or on demand:
+
+```
+## MCP Circuit Breaker Report
+
+| Tool | State | Failures | Tripped | Reset |
+|---|---|---|---|---|
+| {tool} | OPEN | 4 | 14:23 | — |
+| {tool} | CLOSED | 1 | 14:10 | 14:15 (probe) |
+
+Recommendations:
+- {tool}: AUTH failure → refresh credentials in .claude/settings.json
+```
+
+---
+
+## Done When
+
+- Failure pattern classified (type + count)
+- Circuit state logged (OPEN / HALF-OPEN / CLOSED)
+- At least 3 fallback alternatives proposed when circuit is OPEN
+- Recovery probe offered with reset path
+
+---
+
+## Chains
+
+**Upstream** (can trigger this skill):
+- Automatically activates on 3+ consecutive MCP failures during any task
+
+**Downstream** (after circuit open):
+- No mandatory chain — fallback options are presented, user decides
+- Optional: `context-doctor` if MCP failure is due to large context degrading tool calls

package/plugins/fh-commons/skills/token-budget-gate/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: token-budget-gate
+description: Estimates token cost before a multi-step task and outputs a Green/Yellow/Red gate verdict. Tracks actual vs. estimated after completion for calibration. Triggers on "token budget", "how much will this cost", "will this be expensive", "estimate tokens", before long multi-agent tasks.
+user-invocable: true
+allowed-tools: ["Read", "Bash"]
+model: sonnet
+complexity_routing:
+  base: sonnet
+  high: opus
+  escalate_when:
+    - multi_project_scope
+    - unknown_task_type
+---
+
+# token-budget-gate — Pre-Task Token Cost Gate
+
+Multi-step and multi-agent tasks can silently consume large token budgets. This skill estimates cost before execution, outputs a gate verdict, and calibrates estimates against actual usage after completion — preventing surprise overruns without blocking legitimate work.
+
+> **FH context**: FH default execution tier is `standard` (~15K tokens). This skill gates against accidental `full` (~30K) or `max` (~60K+) consumption on tasks that could be handled lighter.
+
+---
+
+## Triggers
+
+- `/token-budget-gate`
+- "token budget", "token cost", "how expensive", "will this use a lot of tokens"
+- "estimate tokens", "token estimate before we start"
+- Before invoking: `agent-composer`, `sim-conductor`, `steel-quench` (max-tier skills)
+- Automatically proposed when task description contains: multi-agent, parallel dispatch, full suite, all files, entire codebase
+
+---
+
+## Gate Thresholds (defaults — user-configurable)
+
+| Signal | Verdict | Action |
+|---|---|---|
+| Estimated < 10K tokens | 🟢 **GREEN** | Proceed without comment |
+| 10K–30K tokens | 🟡 **YELLOW** | Proceed with notice — suggest lighter approach if one exists |
+| 30K–60K tokens | 🟠 **ORANGE** | Confirm before proceeding — present scope reduction options |
+| > 60K tokens | 🔴 **RED** | Block + require explicit approval — present mandatory reduction |
+
+Custom threshold: user can set `TOKEN_BUDGET_MAX=N` in conversation or `.claude/settings.json`.
+
+---
+
+## Execution Steps
+
+### Step 1. Parse Task Description
+
+Extract task dimensions:
+
+| Dimension | Low (×1) | Medium (×2) | High (×4) |
+|---|---|---|---|
+| **File scope** | 1–3 files | 4–10 files | 11+ files / whole codebase |
+| **Agent count** | 0 (inline) | 1–2 agents | 3+ agents / parallel |
+| **Step depth** | 1–3 steps | 4–8 steps | 9+ steps |
+| **Iteration** | None | 1 round | 2+ rounds (wave/loop) |
+| **Output size** | Short answer | Medium doc | Full report / deck |
+
+---
+
+### Step 2. Estimate Token Cost
+
+Base estimates per task type:
+
+| Task Type | Base Estimate | Notes |
+|---|---|---|
+| Single file edit | 2K | Read + edit + verify |
+| Code review (1 PR) | 5K | Diff + analysis + comments |
+| Skill creation (1 SKILL.md) | 8K | Design + write + CATALOG update |
+| Agent dispatch (1 agent) | 10K | Context card + agent overhead |
+| Parallel dispatch (3 agents) | 25K | 3× agent + orchestration |
+| sim-conductor full run | 30K | All 5 simulation axes |
+| steel-quench 4-wave | 50K | All waves + prescriptions |
+| Full harvest-loop cycle | 40K | 8-step pipeline + PRs |
+
+Apply dimension multipliers from Step 1 to the base estimate.
+
+**Final formula:**
+```
+Estimated = base × file_multiplier × agent_multiplier × iteration_multiplier
+```
+
+Round to nearest 1K.
+
+---
+
+### Step 3. Output Gate Verdict
+
+```
+## Token Budget Gate
+
+Task: {one-line task description}
+Estimated cost: ~{N}K tokens
+Threshold: {user max or default}
+
+Verdict: 🟡 YELLOW — within budget but consider lighter approach
+
+Breakdown:
+  Base (skill creation): 8K
+  × 2 agents: ×2 = 16K
+  × 1 iteration: ×1 = 16K
+  Total: ~16K
+
+Lighter alternative:
+  → Inline (no agent dispatch): ~8K (-50%)
+  → Single agent, not parallel: ~12K (-25%)
+
+Proceed? (y to continue / n to adjust scope)
+```
+
+For 🟢 GREEN: output one line only — *"Token estimate: ~{N}K — GREEN, proceeding."*
+
+---
+
+### Step 4. Proceed / Adjust
+
+- **GREEN / YELLOW + user confirms**: proceed, note start marker
+- **ORANGE**: present scope reduction table, wait for user selection
+- **RED**: present mandatory reduction — do not proceed until user explicitly approves
+
+Scope reduction options table (ORANGE/RED):
+
+| Option | Reduction | Trade-off |
+|---|---|---|
+| Drop parallel → sequential | -30% | Slower, same quality |
+| Reduce agent count (3→1) | -50% | Less parallelism |
+| Narrow file scope | -40% | Shallower coverage |
+| Use lighter skill variant | -60% | Fewer waves/probes |
+| Split into 2 sessions | -50%/session | No quality loss |
+
+---
+
+### Step 5. Post-Task Calibration (optional)
+
+After task completion, if user says "how much did that cost" or "calibrate":
+
+```
+## Calibration
+
+Estimated: ~16K tokens
+Actual: ~{actual}K tokens
+Error: {+/-N}%
+
+Calibration note saved → improves next estimate for this task type.
+```
+
+Write calibration data:
+```bash
+mkdir -p .claude/token_calibration/
+# Append: task_type, estimated, actual, date
+```
+
+Calibration data improves future estimates for the same task type (no model training — local record only).
+
+---
+
+## Done When
+
+- Gate verdict output (GREEN/YELLOW/ORANGE/RED) with estimated cost breakdown
+- For ORANGE/RED: scope reduction options presented and user decision recorded
+- Calibration offered after task completion (optional, not mandatory)
+
+---
+
+## Chains
+
+**Upstream** (proposed before these skills):
+- → `agent-composer` (multi-agent orchestration)
+- → `sim-conductor` (5-axis simulation)
+- → `steel-quench` (4-wave adversarial review)
+- → `harvest-loop` (8-step pipeline)
+
+**Downstream**:
+- No mandatory chain — gate verdict is the output; task execution follows user decision