@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

package/src/claude/skills/hotfix/references/review-cycle.md

@@ -4,16 +4,16 @@ How to handle code review results after a fix is implemented. Ensures quality wi
 
 ## Default Review Handling
 
-The agent reviews its own fix using `hapo:code-review` and decides automatically. Every review returns exactly one verdict: `PASS | FAIL | BLOCKED`.
+The agent reviews its own fix using `cf:code-review` and applies the verdict. Every review returns exactly one verdict from the shared surface: `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`. The definition of `PASS` defers to `cf:code-review`; Fix never redefines it with local severity thresholds.
 
 ```
 attempt = 0
 LOOP:
-  1. Trigger hapo:code-review → receives: verdict and severity-classified findings
+  1. Trigger cf:code-review → receives: verdict and severity-classified findings
 
   2. Evaluate:
-     IF verdict == PASS (no Critical, no High, at most one Medium):
-       → ACCEPT. Log: "✓ Review PASS — auto-approved"
+     IF verdict == PASS:
+       → ACCEPT. Log: "✓ Review PASS"
        → Proceed to Step 6 (Finalize)
 
      ELSE IF verdict == BLOCKED:
@@ -21,29 +21,33 @@ LOOP:
        → Present the blocker and required execution proof, permission, environment,
          or user-owned decision to the user.
 
-     ELSE IF verdict == FAIL AND attempt < 3:
-       → AUTO-REMEDIATE the reported findings
+     ELSE IF (verdict == FAIL OR verdict == PASS_WITH_WARNINGS) AND attempt < 3:
+       → REMEDIATE the reported findings (or pause for the user when the
+         Required User Pause conditions below apply)
        → Re-run verification (typecheck + lint + test)
        → attempt += 1
        → GOTO LOOP
 
-     ELSE IF verdict == FAIL AND attempt >= 3:
+     ELSE IF attempt >= 3:
        → HALT. Present findings to user:
-         "3 auto-fix cycles exhausted. [N] blocking findings remain."
-         Options: "Fix manually" | "Approve with known issues" | "Abort"
+         "3 auto-fix cycles exhausted. [N] findings remain."
+         Options: "Revise scope and re-review" | "Stop incomplete" | "Abort"
 ```
 
-`BLOCKED` is terminal for this review cycle. Only `FAIL` may enter remediation retry; never retry a blocked review unchanged.
+`BLOCKED` is terminal for this review cycle. Only `FAIL` and `PASS_WITH_WARNINGS` enter remediation retry; neither verdict can enter
+finalization through user approval. If the user changes scope or accepts a
+different contract, update the review target and obtain a fresh literal `PASS`.
+A blocked review is never retried unchanged.
 
 ## Required User Pause
 
 When the fix touches production-critical code, changes public contracts, introduces a behavior change, or the user explicitly requests review control:
 
-1. Run `hapo:code-review` → collect verdict + severity findings
+1. Run `cf:code-review` → collect verdict + severity findings
 2. Present a structured summary to user:
    ```
    ┌──────────────────────────────────┐
-   │ Review Verdict: [PASS | FAIL | BLOCKED] │
+   │ Review Verdict: [verdict]        │
    ├──────────────────────────────────┤
    │ Critical: [list or "none"]       │
    │ High: [list or "none"]           │
@@ -53,9 +57,11 @@ When the fix touches production-critical code, changes public contracts, introdu
    ```
 3. Ask user for direction:
    - If verdict is `BLOCKED` → resolve the blocker; do not retry this review cycle unchanged.
-   - If verdict is `FAIL` with Critical or High findings → "Fix blocking findings" | "Fix all" | "Approve anyway" | "Abort"
-   - If verdict is `FAIL` with only Medium/Low findings → "Approve" | "Address findings" | "Abort"
-4. Execute user's choice. Max 3 remediation cycles for `FAIL`; `BLOCKED` never enters this retry limit.
+   - If verdict is `FAIL` with Critical or High findings → "Fix blocking findings" | "Fix all" | "Revise scope" | "Abort"
+   - If verdict is `FAIL` or `PASS_WITH_WARNINGS` with only Medium/Low findings → "Address findings" | "Revise scope" | "Stop incomplete"
+4. Execute the user's remediation or scope decision, then re-run verification
+   and review. Max 3 remediation cycles for `FAIL` and `PASS_WITH_WARNINGS`;
+   only a fresh literal `PASS` enters finalization. `BLOCKED` never enters this retry limit.
 
 ## When To Pause vs Continue
 

package/src/claude/skills/hotfix/references/workflow-specialized.md

@@ -1,6 +1,9 @@
 # Specialized Workflows
 
-Targeted procedures for common bug categories. Use these as supplements to the main 6-step process (they don't replace it).
+Targeted procedures for common bug categories. Load only the matching section
+after the main workflow has scouted the affected area. Each overlay adds a
+category-specific baseline and completion proof; it never replaces diagnosis,
+the bounded repair frame, or the side-effect gate.
 
 ---
 
@@ -8,14 +11,20 @@ Targeted procedures for common bug categories. Use these as supplements to the m
 
 When GitHub Actions or CI/CD is failing:
 
-1. **Identify the failing job:** `gh run list --status failure -L 5`
-2. **Pull the failure log:** `gh run view <ID> --log-failed`
+1. **Baseline:** identify the exact failing workflow, job, step, commit, runner,
+   and attempt. Preserve the failing command and log excerpt.
+2. **Inspect safely:** use the project-native CI surface; for GitHub Actions,
+   `gh run list --status failure -L 5` and `gh run view <ID> --log-failed` are
+   examples, not permission to rerun, cancel, or mutate remote state.
 3. **Common traps:**
    - Environment setup step failed silently (DB container didn't start, npm ci cache corrupted)
    - Secrets/env vars missing in the CI environment
    - Version mismatch between local Node/Python and CI runner
    - Flaky tests (passes locally, fails on CI) — check for timezone, file ordering, or race conditions
-4. **Fix pattern:** Reproduce locally first. Never push blind fixes to CI.
+4. **Proof:** reproduce locally when parity is available, run the affected job
+   command, and verify workflow/config syntax. A local pass is not CI proof; if
+   a remote rerun is not authorized, report it as unverified. Never push blind
+   fixes to CI.
 
 ---
 
@@ -23,11 +32,15 @@ When GitHub Actions or CI/CD is failing:
 
 When unit/integration/e2e tests are failing:
 
-1. **Isolate:** Run the failing test alone: `npx jest --testPathPattern=<file> --verbose`
-2. **Check for pollution:** Does it pass alone but fail in suite? → Test order dependency or shared state leaking
-3. **Check for staleness:** Did the implementation change but the test assertions were not updated?
-4. **Snapshot drift:** If snapshot tests fail, review the diff carefully — is it an intentional change or a regression?
-5. **Flaky async:** Replace arbitrary sleeps with condition-based waits: wait for observable state, DOM condition, network completion, queue drain, or explicit event instead of fixed timeouts.
+1. **Baseline:** record runner, exact failing command, test name, seed/shard,
+   environment, and assertion output. Use the repository's runner rather than
+   assuming Jest.
+2. **Isolate:** run the smallest native selector that preserves the failure.
+3. **Check for pollution:** Does it pass alone but fail in suite? → Test order dependency or shared state leaking.
+4. **Check for staleness:** Did implementation behavior intentionally change, or is the assertion exposing a regression? Never weaken the assertion merely to turn the suite green.
+5. **Snapshot drift:** Review the semantic diff; regenerate only when the changed output is accepted behavior.
+6. **Flaky async:** Replace arbitrary sleeps with condition-based waits for observable state, DOM condition, network completion, queue drain, or an explicit event.
+7. **Proof:** show fail-before/pass-after for the regression selector, then run the owning suite and any shared-state/order-sensitive suite.
 
 ---
 
@@ -35,13 +48,17 @@ When unit/integration/e2e tests are failing:
 
 When `tsc` is throwing type errors:
 
-1. **Never** suppress with `any`, `@ts-ignore`, or `as unknown as X` — these are band-aids that rot
-2. **Trace the type chain:** Where was the type originally defined? Follow the generic flow
-3. **Common roots:**
+1. **Baseline:** record the exact compiler command, diagnostic code, source
+   location, and affected type relationship.
+2. **Never** suppress with `any`, `@ts-ignore`, or `as unknown as X` unless the
+   public contract itself explicitly requires an unsafe boundary and the risk is called out.
+3. **Trace the type chain:** Where was the type originally defined? Follow the generic flow.
+4. **Common roots:**
    - Library update changed return types → check CHANGELOG/migration guide
    - Missing null check → add proper narrowing
    - Generic type inference failure → provide explicit type argument
-4. **Fix pattern:** Fix the type definition at the source, not at the consumption point
+5. **Fix pattern:** Fix the owned contract at its source. Do not "fix all" unrelated pre-existing diagnostics outside the blast radius.
+6. **Proof:** rerun the exact failing compiler command plus tests covering runtime narrowing or serialization behavior affected by the type change.
 
 ---
 
@@ -49,10 +66,17 @@ When `tsc` is throwing type errors:
 
 When the interface is broken, misaligned, or not rendering:
 
-1. **Capture visual evidence:** Use `pushd skills/chrome-devtools/scripts && node screenshot.js --url <url> && popd`
-2. **Check ARIA structure:** `pushd skills/chrome-devtools/scripts && node aria-snapshot.js --url <url> && popd` — reveals hidden overlays, z-index battles
-3. **Check console errors:** `pushd skills/chrome-devtools/scripts && node console.js --url <url> && popd` — catches JS crashes preventing render
-4. **Run frontend verification:** collect screenshot, console, network, accessibility, responsive, and interaction evidence before/after the fix.
+1. **Baseline:** capture the failing route, viewport, theme, browser/runtime,
+   interaction sequence, screenshot, console, and relevant network state with
+   the available project/browser tooling.
+2. **Inspect structure:** compare DOM/ARIA and computed layout at the failing
+   element; visual similarity alone does not prove interaction behavior.
+3. **Trace runtime state:** preserve console errors, hydration warnings, failed
+   requests, and state transitions that explain the symptom.
+4. **Proof:** repeat the exact interaction and compare before/after at the
+   failing viewport, then test affected responsive states, keyboard/accessibility
+   behavior, console, and network. If the host cannot perform visual interaction,
+   report it as unverified instead of inferring a pass from static code.
 5. **Common traps:**
    - CSS specificity wars (use browser DevTools or ARIA snapshot to verify computed styles)
    - Hydration mismatch in SSR frameworks (server HTML differs from client render)
@@ -65,10 +89,18 @@ When the interface is broken, misaligned, or not rendering:
 
 When investigating production or server-side log errors:
 
-1. **Pull wide context:** `tail -n 200 <logfile>` — don't just look at the last error line
-2. **Timestamp correlation:** Cross-reference error timestamps across multiple log sources (app, DB, reverse proxy)
-3. **Pattern recognition:** Is it a single occurrence or repeated? Use `grep -c` to count
-4. **Common traps:**
+1. **Baseline:** preserve the source, environment, time range, timezone,
+   request/trace/job ID, exact error, and surrounding events. Do not expose
+   secrets or personal data in reports.
+2. **Correlate:** normalize timestamps and cross-reference relevant app, DB,
+   proxy, queue, or provider logs. Ordering is evidence, not automatic causation.
+3. **Measure:** establish frequency, first/last occurrence, affected cohort, and
+   whether the error is isolated or load-dependent using the available native tools.
+4. **Proof:** replay a safe deterministic trigger when possible, confirm the
+   expected state transition and absence of the same correlated error, then
+   verify metrics/alerts or report live recurrence as unverified when observation
+   time is insufficient.
+5. **Common traps:**
    - Silent exception swallowing upstream (the real error was caught and logged as a warning 50 lines earlier)
    - Database connection pool exhaustion (errors appear random but correlate with connection count)
    - Memory leaks (errors start appearing after extended uptime, not immediately)

package/src/claude/skills/inspect/SKILL.md

@@ -1,21 +1,24 @@
 ---
-name: hapo:inspect
-description: "Fast codebase discovery using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal Explore agents."
+name: cf:scout
+description: "Fast scoped codebase discovery using local search first and user-permitted Explore delegation only for broad independent scopes. Use for file discovery, task context, entrypoints, call paths, and blast radius."
 user-invocable: true
-when_to_use: "Invoke for fast parallel codebase discovery and file location."
+when_to_use: "Invoke for fast scoped codebase discovery and file location."
 category: discovery
-keywords: [discovery, search, explore, context]
+keywords: [scout, inspect, discovery, search, context]
 argument-hint: "[search-target]"
 metadata:
   author: haposoft
   version: "2.1.0"
 ---
-# Inspect
+# Scout
 
-Fast, token-efficient codebase discovery using parallel agents to find files needed for tasks.
+Fast, token-efficient codebase discovery that uses focused local search by default
+and delegates only when parallel scouting has a concrete benefit.
 
 ## Arguments
-- Default: Inspect using built-in Explore subagents in parallel (`./references/internal-inspection.md`)
+- Default: Scout the named target with local `rg` and targeted reads. For a
+  genuinely broad scope, use the conditional delegation route in
+  `./references/internal-inspection.md`.
 
 ## When to Use
 
@@ -30,24 +33,29 @@ Before scanning:
 2. Apply the built-in no-scan lists below.
 3. Prefer file-type or glob hints whenever possible.
 
-**When scope is too broad:** use a **2-phase approach** — lightweight Structure Scout first, then parallel agents on real sub-scopes.
+**When scope is too broad:** use a **2-phase approach** — lightweight structure
+mapping first, then parallel agents only when the Delegation Gate is open.
 
-### Phase 1 — Structure Scout (Single Agent, Run First)
+### Phase 1 — Structure Map
 
-Spawn **one scout** to map top-level layout before dividing work:
+Map the top-level layout in the main agent. A single Explore agent may do this
+only when the Delegation Gate below is already open:
 1. List immediate children of the scope root (dirs + key config; monorepo markers)
 2. Rough file count per discovered directory
 3. Return a division plan of 1–10 logical sub-scopes (path/glob, est. files, focus)
 
-Wait for Scout before Phase 2.
+Complete the structure map before Phase 2.
 
-### Phase 2 — Parallel Explore Agents (Based on Scout Results)
+### Phase 2 — Conditional Parallel Explore
 
-1. Follow Scout's plan; merge scopes < 10 files; split scopes > 100 files
-2. Spawn parallel Explore agents, one per sub-scope
-3. Aggregate into the Inspect Report; offer deeper follow-up on specific areas
+1. Follow the structure map; merge scopes < 10 files; split scopes > 100 files
+2. If the Delegation Gate is open, spawn Explore agents on distinct sub-scopes;
+   otherwise scout the sub-scopes sequentially in the main agent
+3. Aggregate into the Scout Report; offer deeper follow-up on specific areas
 
-**Fallback to AskUserQuestion:** if Scout is ambiguous (flat layout, < 3 areas), offer 2–4 concrete scopes from findings, then re-invoke with the chosen scope.
+**Fallback to AskUserQuestion:** if the structure map still leaves multiple
+plausible targets and the choice would materially change the scan, offer 2–4
+concrete scopes from findings, then continue with the selected scope.
 
 ## Built-in No-Scan Guidance
 
@@ -63,50 +71,51 @@ Wait for Scout before Phase 2.
 
 ### 1. Analyze Task
 - Parse search targets; identify directories, patterns, file types
-- Determine SCALE of subagents
+- Estimate scan size and whether the work divides into independent scopes
 
-**SCALE Calculation:**
-```
-SCALE = ceil(estimated_files_to_scan / 50)
-```
+### 2. Choose The Smallest Route
 
-- Min SCALE = 1; Max SCALE = 10
-- SCALE 1-2: focused (< 100 files)
-- SCALE 3-5: medium
-- SCALE 6-10: large (internal Explore agents)
+| Condition | Route |
+|---|---|
+| Named files/directories or focused scope (about 50 files or fewer) | Main-agent `rg` plus targeted reads; do not delegate |
+| Medium scope that still fits one coherent search | Main-agent scouting; narrow before considering delegation |
+| Broad scope with two or more independent areas | Structure map, then evaluate the Delegation Gate |
 
-### 2. Divide and Conquer
-- Split into logical segments; assign distinct directories/patterns; no overlap
+Do not use the file estimate alone to justify agents. A focused 100-file search
+may still be cheaper locally; a smaller cross-system search may justify two
+independent scopes.
 
-### 3. Register Inspect Tasks
-- **Skip if:** Agent count ≤ 2
-- `TaskList` first; if none, `TaskCreate` per agent with scope metadata
-- See `./references/internal-inspection.md` for patterns
+### 3. Delegation Gate
 
-### 4. Choose Mode
+Delegate only when all are true:
 
-| Condition | Mode |
-|---|---|
-| Always | Internal Explore agents |
+- The user explicitly requested or permitted subagents, delegation, or parallel work.
+- The active runtime exposes an Explore/delegation capability.
+- At least two non-overlapping scopes have useful independent work.
 
-Load: **Internal** `./references/internal-inspection.md`.
+If any condition is false, continue in the main agent with scoped `rg`, file
+listing, and targeted reads. Do not ask for delegation merely to complete an
+ordinary focused scout.
 
-### 5. Spawn Parallel Agents
+### 4. Divide And Scout
 
-Dispatch native Explore agents with breadth medium/very-thorough + the Scope Gate above. Details: `./references/internal-inspection.md`.
+For local scouting, search the shortlisted scopes sequentially and stop when the
+question is answered. For delegated scouting, load
+`./references/internal-inspection.md`, split by logical boundaries, and ensure
+no overlap.
 
-- `TaskUpdate` each task to `in_progress` before spawn
-- Prompt each subagent with exact directories/files; each has < 200K context
-- Agent count follows resources + file volume; each returns a summary to the main agent
+- Skip task registration for two or fewer agents.
+- For three or more agents, use the live task/plan surface when available.
+- Prompt each agent with exact directories/files and a read-only boundary.
 
-### 6. Collect Results
+### 5. Collect Results
 - Timeout: 3 minutes per agent (skip non-responders; log in report)
-- `TaskUpdate` completed tasks; aggregate; list unresolved questions at end
+- Update live task/plan state when one was used; aggregate; list unresolved questions at end
 
 ## Report Format
 
 ```markdown
-# Inspect Report
+# Scout Report
 
 ## Relevant Files
 - `path/to/file.ts` - Brief description
@@ -121,7 +130,7 @@ Dispatch native Explore agents with breadth medium/very-thorough + the Scope Gat
 
 ## Rules
 
-- Keep scope narrow. Do not use `hapo:inspect` as a runtime policy engine.
+- Keep scope narrow. Do not use `cf:scout` as a runtime policy engine.
 - Prefer listing files first, then reading only the shortlisted files.
 - Never encourage scanning ignored/generated/sensitive areas from the no-scan list.
 - Keep reports concise and actionable.
@@ -130,4 +139,4 @@ Dispatch native Explore agents with breadth medium/very-thorough + the Scope Gat
 
 ## References
 
-- `./references/internal-inspection.md` - Using Explore subagents
+- `./references/internal-inspection.md` - Conditional Explore delegation

package/src/claude/skills/inspect/references/internal-inspection.md

@@ -1,6 +1,19 @@
-# Internal Discovery with Explore Subagents
+# Conditional Discovery with Explore Subagents
 
-Dispatch native Explore agents with breadth medium/very-thorough + the Scope Gate in `SKILL.md`. Use when SCALE ≥ 6 or external tools are unavailable.
+Use native Explore agents only after the `SKILL.md` Delegation Gate passes.
+Focused discovery stays in the main agent even when Explore is available.
+
+## Delegation Preconditions
+
+All are required:
+
+1. The user explicitly requested or permitted delegation or parallel agents.
+2. The active runtime exposes an Explore/delegation capability.
+3. The structure map identifies at least two distinct, non-overlapping scopes
+   with useful independent work.
+
+If any precondition fails, use scoped `rg`, file listing, and targeted reads in
+the main agent. Do not request extra authority for an ordinary focused scout.
 
 ## Agent Tool Configuration
 
@@ -26,7 +39,9 @@ Report format:
 
 ## Spawning Strategy
 
-Split by logical dirs (`src/`, `lib/`, `tests/`, `config/`, `api/`, `types/`). Spawn all in one call; distinct scopes; no overlap.
+Split by logical dirs (`src/`, `lib/`, `tests/`, `config/`, `api/`, `types/`).
+Spawn agents concurrently only when the runtime supports it; keep scopes
+distinct and non-overlapping.
 
 **Example** (auth): A1 `src/auth/, middleware/`; A2 `api/, routes/`; A3 `tests/`; A4 `lib/, utils/`; A5 `config/`; A6 `types/`.
 
@@ -37,7 +52,9 @@ Split by logical dirs (`src/`, `lib/`, `tests/`, `config/`, `api/`, `types/`). S
 | ≤ 2    | No (overhead) |
 | ≥ 3    | Yes |
 
-`TaskList` → reuse or `TaskCreate` per agent (`agentType: Explore`, scope, scale, agentIndex, totalAgents, toolMode: internal). Lifecycle: pending → in_progress before spawn → completed on return (timeout: keep in_progress + error metadata).
+Use the live task or plan surface when available. Record scope and ownership
+before spawn, then completion or timeout after collection. Do not create task
+state solely for one or two short probes.
 
 ## Timeout, Aggregation, Reading
 
@@ -51,4 +68,3 @@ Start from concrete directories (not repo root); prefer scoped globs; skip `NO_S
 ## Output Contract
 
 Return: file paths, brief description per file, notable relationships/patterns, unresolved questions.
-

package/src/claude/skills/loop/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: cf:loop
+description: "Run an explicit, bounded optimization loop against a numeric metric while a separate correctness guard protects the result."
+user-invocable: true
+when_to_use: "Use only when the user explicitly requests measurable iterative optimization and supplies a safe Metric and Guard contract."
+category: utilities
+keywords: [loop, optimization, benchmark, metric, experiment]
+argument-hint: "<goal>"
+metadata:
+  author: haposoft
+  version: "1.0.0"
+---
+# Loop — bounded metric optimization
+
+Loop is explicit-only. Never auto-route ordinary implementation, debugging, or
+research into Loop. It optimizes one numeric outcome under a separate correctness
+Guard; it does not guarantee improvement or replace Test/Review.
+
+Live-agent adherence to this written contract is `[UNPROVEN]` without a host run.
+The safety boundary is cooperative: commands must already be trusted by the user
+or repository. No instruction-only workflow can contain a malicious executable
+without an OS sandbox.
+
+## 1. Preflight before mutation
+
+Load `references/metric-and-guard-contract.md` and freeze every field before any
+worktree, process, patch, or file mutation:
+
+- Goal and canonical repository root.
+- Scope: contained regular tracked text paths; symlink, untracked, binary, and
+  submodule policy. Default is reject each unsupported kind.
+- Pinned base OID plus primary tracked/untracked status. Reject dirty in-scope
+  state; record but never import or clean out-of-scope dirt.
+- Metric argv, unit, `higher|lower`, sample count, IEEE-754 binary64 numeric and
+  rounding policy, fixed aggregation/noise rule, minimum delta, timeout, and
+  reproducible baseline environment.
+- Distinct immutable Guard argv and timeout for code mutation. Metric and Guard
+  may not be the same command or validate the same sole outcome.
+- Frozen positive iteration and wall-clock budgets; explicit success,
+  no-improvement, drift, failure, timeout, and cancellation stops.
+- Unique run identity, exact disposable root, ownership marker, upfront cleanup
+  consent, handoff mode/destination, retention, and cleanup owner.
+
+Missing, ambiguous, unsafe, or non-reproducible input returns `BLOCKED` without
+mutation. A subjective score, a metric that can be edited by the loop, or code
+mutation without a distinct Guard is ineligible.
+
+## 2. Establish isolation and baseline
+
+Load `references/bounded-loop-protocol.md`. Create a never-reused canonical temp
+root and ownership marker, then add a detached Git worktree at the pinned OID.
+Do not create a branch or commit. Necessary common-Git-dir worktree metadata is
+the only allowed primary-repository metadata effect; primary worktree bytes,
+index, branch, and refs remain untouched.
+
+Screen each trusted command as an argv vector and run it with `cwd` fixed to the
+canonical detached root. The executable is a separately approved external
+realpath; only path-valued target arguments must resolve inside the detached
+root. Never use `eval`, `sh -c`, `bash -c`, `zsh -c`,
+`cmd /c`, PowerShell `-Command`, inline interpreter code, Git `-C`, `--git-dir`,
+`--work-tree`, destructive Git operations, path traversal, or an absolute target
+outside the detached root. Use a minimal fixed environment and redact secrets.
+
+Capture the complete detached-worktree tracked/untracked manifest before and
+after every Metric and Guard run, subtracting only an exact immutable cache
+allowlist frozen at preflight. Any other oracle mutation is drift. Establish
+baseline samples on pinned bytes before allowing a candidate.
+
+## 3. Iterate one attributable change
+
+For every iteration:
+
+1. Create a fresh unique detached worktree from pinned base and apply only the
+   accepted-best patch, if one exists. Never restore in place.
+2. Make exactly one bounded hypothesis change inside Scope. Multiple unrelated
+   changes are forbidden. Reject unexpected,
+   untracked, binary, symlink, submodule, or out-of-scope bytes.
+3. Fingerprint candidate bytes, run Metric samples, fingerprint again, then run
+   Guard on those identical bytes and fingerprint once more.
+4. Reject on nonzero exit, timeout, malformed/non-finite/multi-value output,
+   oracle mutation, Guard failure, or any source/environment/contract drift.
+5. Accept only when Guard passes and improvement over current best is strictly
+   greater than both the frozen minimum delta and calculated noise threshold.
+   Record the candidate as a base-bound accepted-best patch; otherwise discard
+   only that iteration's owned disposable environment.
+
+Do not edit Metric, Guard, tests, benchmarks, datasets, budgets, or thresholds
+to win; their frozen digests are revalidated before every candidate.
+Stop at the first budget, cancellation, drift, ownership, cleanup, or repeated
+no-improvement condition named in preflight.
+
+## 4. Failure and process ownership
+
+Launch every command in an isolated process group on POSIX or Job Object on
+Windows. If the runtime cannot terminate the whole process tree, refuse to run.
+On timeout/cancel, terminate, escalate to kill, reap, and verify quiescence before
+cleanup. Never reuse a timed-out path. If descendants, path ownership, or cleanup
+is uncertain, retain exact residue and return `BLOCKED`; never use
+`git reset --hard`, `git clean`, broad deletion, or unrelated recovery.
+
+## 5. Handoff
+
+Return baseline, best value/noise, the exact keep formula, accepted/rejected
+iteration ledger, Guard evidence, stop reason, remaining limits, and live-proof
+status. A successful handoff is a redacted tracked-text patch bound to base OID,
+complete scoped file manifest, and lowercase SHA-256. Reject secret-bearing,
+untracked, binary, incomplete, or stale output unless a separately approved
+bundle contract exists.
+
+Use only the preflight-selected handoff mode: inline ephemeral patch, or an exact
+user-approved path outside the primary worktree with retention and cleanup owner.
+Never apply, commit, push, merge, cherry-pick, deploy, publish, or write an
+artifact into the primary worktree implicitly. The user reviews and explicitly
+authorizes any later application through the normal Develop/Test/Review flow.

package/src/claude/skills/loop/references/bounded-loop-protocol.md

@@ -0,0 +1,104 @@
+# Bounded Loop protocol
+
+This is a cooperative instruction contract, not a sandbox or a production
+runtime. Live-agent adherence remains `[UNPROVEN]` until separately observed.
+
+## Run identity and filesystem boundary
+
+1. Resolve the repository root and pinned base OID without changing checkout.
+2. Capture primary tracked and untracked status. Reject any dirty path that is
+   inside Scope; never import, stash, clean, or overwrite primary dirt.
+3. Create a unique temp directory using the platform's secure temp API. Resolve
+   its lexical and canonical path, require it outside the repository, and refuse
+   a symlink, pre-existing reused run path, broad root, or ownership ambiguity.
+4. Write an ownership marker containing a random run ID, base OID, canonical
+   root, and creation time. Acquire one exclusive run lock; contention blocks.
+5. With upfront consent for this exact path, use `git worktree add --detach`
+   against the pinned OID. Do not use `-b`, create refs, or commit.
+
+Every later path must be a lexical and canonical descendant of the owned root.
+Reject `..`, symlink traversal, mount redirection, absolute external targets,
+submodules, and paths that changed identity after validation.
+
+## Command trust and screening
+
+Commands are supplied or already owned by the trusted repository/user. Record
+the separately trusted/allowlisted executable realpath (which may be outside the
+worktree), argv, fixed cwd, timeout, output limit, and allowlisted
+environment before execution. Do not pass secrets; redact credentials, tokens,
+cookies, authorization headers, PII, and secret-looking patch lines from reports.
+
+Refuse general shell evaluation, inline code flags, Git external targeting
+(`-C`, `--git-dir`, `--work-tree`), destructive Git (`reset --hard`, `clean`,
+branch/ref deletion), recursive deletion, privilege escalation, deploy/publish,
+and any path-valued target argument that resolves outside the detached root,
+including response/config/output targets. Do not apply the target-path rule to
+the separately approved executable itself. A trusted script file may run through
+its declared interpreter, but inline `-c`, `-e`, `--eval`, and equivalent dynamic
+code are forbidden.
+
+This screening reduces mistakes; it cannot contain arbitrary side effects from
+a malicious or compromised executable. If that threat is material, return
+`BLOCKED` and require an OS sandbox outside this skill's scope.
+
+## Iteration lifecycle
+
+- Revalidate base OID, primary status, contract digests, lock, ownership marker,
+  and canonical roots before every iteration.
+- Build a new never-reused detached worktree from pinned base plus the current
+  accepted-best tracked-text patch. Do not repair a rejected candidate in place.
+- Capture a complete Scope manifest of path, type, mode, size, and SHA-256 before
+  mutation; lstat paths and reject symlink/type/identity changes.
+- Permit one hypothesis patch. Its post-change manifest must be contained in
+  Scope and attributable to that hypothesis.
+- Capture the complete detached-worktree tracked/untracked fingerprint around
+  every Metric and Guard command. Subtract only exact immutable cache paths
+  frozen at preflight; every other oracle-created file or byte/mode/type/path
+  change, inside or outside Scope, rejects the candidate as drift.
+- Record command exit/signal/timeout, bounded redacted output, raw finite samples,
+  median/noise, Guard verdict, patch digest, and keep/discard reason.
+
+Parallel iterations are forbidden: one run, one lock, one candidate at a time.
+An external source/base/contract change stops the run; it never triggers an
+automatic rebase, new baseline, threshold change, or wider Scope.
+
+## Process-tree timeout and cancellation
+
+Spawn a new process group on POSIX or Job Object on Windows. On timeout or user
+cancellation, stop scheduling, terminate the whole tree, wait the frozen grace
+period, escalate to kill, reap, and verify no owned descendant remains. The run
+path is permanently retired after timeout.
+
+If the platform cannot own/observe descendants, termination fails, a process
+survives, or quiescence cannot be proven, do not clean. Preserve the exact path,
+PID/process evidence, and ownership marker; return `BLOCKED` for operator action.
+
+## Cleanup and recovery
+
+Clean only a canonical path whose run ID, lock, marker, base OID, and inode/path
+identity still match the run and whose process tree is quiescent. Release the
+detached worktree through Git, then remove only that exact temp root using the
+pre-approved cleanup action. Never broaden a glob or follow a symlink.
+
+No `git reset --hard`, `git clean`, force checkout, stash, branch deletion,
+primary-index edit, or unrelated recovery is permitted. Cleanup uncertainty is
+a retained residue plus `BLOCKED`, not a reason to become more destructive.
+
+## Patch handoff
+
+Default handoff supports tracked regular UTF-8 text files only. Generate a
+reviewable unified patch against the pinned base, then bind:
+
+- `base_oid`;
+- sorted complete Scope manifest before/after with file SHA-256;
+- patch byte length and lowercase SHA-256;
+- Metric/Guard contract digests and evidence;
+- accepted/rejected iteration ledger and stop reason;
+- secret/redaction scan result;
+- mode: inline ephemeral, or exact approved external path;
+- creation time, retention/expiry, cleanup owner, and application authority.
+
+Reject missing/untracked/binary/symlink/submodule/secret-bearing/incomplete or
+stale patch bytes. Never store the artifact in the primary worktree implicitly.
+Never apply or commit it. A later authorized workflow revalidates base, patch,
+tests, review, and current repository state before application.