@haposoft/cafekit 0.16.6 → 0.18.0

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

@@ -1,104 +0,0 @@
-# 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.

package/src/claude/skills/loop/references/metric-and-guard-contract.md

@@ -1,76 +0,0 @@
-# Metric and Guard contract
-
-Freeze this contract before mutation. If any field changes, stop for drift; do
-not silently recompute the baseline under new rules.
-
-## Required Metric fields
-
-- `argv`: nonempty trusted argv vector; no shell string.
-- `cwd`: canonical detached worktree root, fixed by Loop.
-- `unit`: one nonempty unit label.
-- `direction`: exactly `higher` or `lower`.
-- `sample_count`: integer at least 3, identical for baseline and candidates.
-- `timeout_ms`: positive integer per sample.
-- `minimum_delta`: finite nonnegative number in the declared unit.
-- `numeric_format`: exactly IEEE-754 binary64, roundTiesToEven after every
-  operation, with negative zero normalized to positive zero.
-- `environment`: fixed allowlisted names and redacted non-secret values; no
-  inherited credential or mutable random/time seed unless explicitly frozen.
-
-Each successful sample must emit exactly one trimmed UTF-8 line matching
-`^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$`. Reject empty,
-multi-line, multi-value, `NaN`, `Infinity`, unit-suffixed, nonzero exit, signaled,
-or timed-out output. Parse to a finite number without locale-dependent separators.
-Reject a decimal with a nonzero significand when binary64 parsing underflows it
-to zero.
-
-## Fixed calculation
-
-For each sample set:
-
-1. Sort binary64 values and calculate the median. For an even count with central
-   values `lower <= upper`, use `lower + (upper - lower) / 2` when both have the
-   same sign (zero may join either sign); otherwise use
-   `lower / 2 + upper / 2`. Apply binary64 roundTiesToEven after every operation
-   and normalize negative zero to positive zero.
-2. Calculate noise as the maximum absolute distance from that median.
-3. For `higher`, improvement is `candidate_median - best_median`; for `lower`,
-   improvement is `best_median - candidate_median`.
-4. Calculate `required_delta = max(minimum_delta, best_noise + candidate_noise)`.
-5. Accept only when `improvement > required_delta` and Guard passes on the exact
-   candidate bytes. Equality is not an improvement.
-
-After every operation, require median, noise, improvement, and required delta to
-remain finite. A parsed nonzero value that became zero, an overflow, or a
-non-finite derived value blocks the baseline or rejects the candidate; never
-store it as current best. A rounded zero produced by subtraction is handled
-conservatively as no improvement, never as a win.
-
-The initial current best is the pinned baseline. Keep the accepted candidate's
-median and noise as the next current best. Never compare a candidate against an
-older, more favorable baseline or select one sample from a noisy set.
-
-## Guard independence
-
-For code mutation, Guard is mandatory, fixed before baseline, and distinct from
-Metric. It must validate correctness beyond the optimized outcome—for example a
-relevant real test command, typecheck, or invariant checker. A second invocation
-of Metric, a threshold over the same output, or an oracle the loop may edit is
-not an independent Guard.
-
-Run Guard after Metric on the identical candidate fingerprint. Guard passes only
-with its predeclared literal exit/oracle and zero required skips; `NO_TESTS`,
-warning-only, partial, flaky-history waiver, or changed Guard bytes do not pass.
-Metric and Guard may create disposable caches only at exact predeclared paths.
-Snapshot the complete detached-worktree tracked/untracked state around each
-oracle, subtract only that fixed cache allowlist, and treat every other byte,
-mode, type, or path mutation—including outside Scope—as drift.
-
-## Reproducibility and drift
-
-Record tool versions, immutable Metric/Guard/test/benchmark/dataset digests,
-fixed inputs/data digest, relevant configuration digest,
-base OID, scoped byte manifest digest, and environment fingerprint. Stop when any
-of them changes. Report variance and raw sample values; do not hide outliers or
-retry only bad samples. A failed sample rejects the candidate rather than being
-dropped from aggregation.

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

@@ -1,94 +0,0 @@
----
-name: cf:route
-description: "Route ambiguous, multi-step, multi-domain, or risk-elevated work through the shortest valid chain of installed CafeKit skills and agents."
-user-invocable: true
-when_to_use: "Use when no single obvious installed skill covers the request; skip for an explicitly named skill, one clear low-risk intent, or a direct factual answer."
-category: utilities
-keywords: [routing, workflow, orchestration, delegation, risk]
-argument-hint: "<task>"
-metadata:
-  author: haposoft
-  version: "1.0.0"
----
-# Route — proportional native routing
-
-Choose the shortest valid path through capabilities that are installed now.
-Route is a decision layer: it classifies, composes, and hands off; each selected
-skill or agent still owns its domain contract and evidence.
-
-## 1. Proportional gate
-
-Apply these exits before discovery, classification, or delegation:
-
-1. **Explicit installed skill:** when the user names a valid installed skill,
-   invoke that skill directly. Do not reclassify it or add routing ceremony.
-2. **One obvious intent:** when exactly one installed skill clearly covers a
-   low-risk request, use it directly without constructing a chain.
-3. **Direct factual conversation:** answer a factual question directly, or use
-   the installed evidence-answering skill when repository or current evidence is
-   needed. Do not create a route chain or spawn agents merely to answer it.
-4. Continue in Route only for ambiguity, multiple dependent steps, multiple
-   domains, elevated/high risk, or no obvious installed capability.
-
-An explicitly named capability that is absent, invalid, duplicate, ambiguous,
-or retired is not an installed route. Name the gap; do not invent a substitute
-with broader authority.
-
-## 2. Classify material work
-
-Load `references/task-taxonomy.md`. Record exactly one class based on the final
-deliverable, then record size (`trivial | standard | epic`), the highest-link
-risk (`low | elevated | high`), and the number of material domains. Never
-average risk down across links.
-
-Use the runtime's live installed skill and agent catalogs. Never synthesize a
-skill, agent, command, or optional bundle from examples in these instructions.
-If inventory is unavailable, use only capabilities the runtime visibly exposes;
-otherwise name the capability gap and keep the path inline where safe.
-
-## 3. Compose the shortest valid chain
-
-Load `references/chaining-patterns.md` only when two or more links are required.
-Start from `understand -> decide -> execute -> verify -> deliver`, remove every
-link whose output is already evidenced, and add a link only when a modifier
-requires it. Every retained link has an entry condition, an observable exit
-artifact, and exactly one owner.
-
-Prefer the user-named skill, then the narrowest domain skill, then a generic
-workflow skill. One intent has one primary skill. Supporting skills may produce
-inputs for it but may not compete for ownership.
-
-## 4. Agents and risk gates
-
-Load `references/agent-timing.md` only when delegation may materially improve
-fresh context, specialization, tool isolation, or safe parallel work. Discover
-agents from the current runtime; if the preferred agent is missing, continue
-inline when safe or return the named gap. Never synthesize an unavailable agent.
-
-- `low`: the owning link's normal proof is sufficient.
-- `elevated`: add explicit verification appropriate to the changed surface.
-- `high`: require independent review and user confirmation before advancing
-  past the high-risk gate. When an irreversible or external action is present,
-  obtain that confirmation immediately before the action.
-
-## 5. Authority is monotonic
-
-The route may narrow user authority but never expand it. Read-only stays
-read-only; diagnosis does not authorize repair; implementation does not
-authorize commit, push, deploy, publish, or release; local work does not
-authorize an external action. Stop before any mutation or delivery link that
-the user did not already authorize and state what authority is missing.
-
-## 6. Return and handoff
-
-Return a compact route record before the first material handoff:
-
-```text
-Route: <class> | size=<trivial|standard|epic> | risk=<low|elevated|high> | domains=<n>
-Chain: <owner: entry -> exit> [-> ...]
-Gates: <authority, verification, confirmation, or named gap>
-```
-
-Do not claim that source text or installed projection proves live-model
-adherence. That behavior remains `[UNPROVEN]` until a separate host run observes
-it.

package/src/claude/skills/route/references/agent-timing.md

@@ -1,46 +0,0 @@
-# Agent timing
-
-Delegation is optional acceleration, not a mandatory stage. Keep work inline
-when it is small, tightly coupled, dependent on shared evolving context, or no
-installed specialist offers a material advantage.
-
-Delegate only when at least one trigger is evidenced:
-
-- a specialist needs fresh isolated context;
-- a distinct tool or runtime boundary must be owned separately;
-- two or more scopes are genuinely independent and can run in parallel;
-- an independent reviewer or tester is required by risk.
-
-Discover the current runtime's installed agent catalog before delegation. Use
-Claude-native agent types in Claude Code and Codex-native agents/subagents in
-Codex. If the preferred agent is absent, do the work inline when safe or name
-the gap and stop; never synthesize a role or pretend delegation occurred.
-
-## Delegation brief
-
-Every delegated link receives exactly these seven fields:
-
-1. **Outcome** — observable result.
-2. **Scope** — owned files, systems, or questions.
-3. **Inputs** — current evidence and prerequisite artifacts.
-4. **Constraints** — safety, compatibility, authority, and non-goals.
-5. **Acceptance** — proof required for completion.
-6. **Handoff** — expected returned artifact and destination.
-7. **Status vocabulary** — `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`.
-
-Parallel delegates require disjoint write ownership and no hidden dependency.
-The controller reconciles their outputs and remains responsible for route state;
-an agent never gains commit, push, deploy, publish, release, or other mutation
-authority from delegation alone.
-
-## Status handling
-
-- `DONE`: validate the exit artifact, then advance.
-- `DONE_WITH_CONCERNS`: resolve correctness or scope concerns before advancing;
-  record observational concerns without inventing failure.
-- `BLOCKED`: change evidence, owner, scope, or dependency before retrying.
-- `NEEDS_CONTEXT`: supply the missing bounded context before retrying.
-
-Never blindly retry `BLOCKED` or `NEEDS_CONTEXT`. A retry without a material
-change preserves the same normalized cause and therefore the same route failure
-key.

package/src/claude/skills/route/references/chaining-patterns.md

@@ -1,53 +0,0 @@
-# Chaining patterns
-
-Use a chain only when one link's output is required by another. The default
-skeleton is:
-
-```text
-understand -> decide -> execute -> verify -> deliver
-```
-
-## Link contract
-
-Every retained link must state:
-
-- **Entry:** the evidence or artifact required to start.
-- **Exit:** one observable artifact or decision passed forward.
-- **Owner:** exactly one installed skill, installed agent, or the controller.
-
-Pass only the exit artifact plus the target, constraints, authority, acceptance,
-and unresolved gaps needed by the next owner. For one or two short links, chat
-context is enough. For longer or interruption-prone work, use an already
-authorized repository artifact; routing never grants permission to create one.
-
-## Collapse and insertion
-
-Remove a link when its exit is already current and evidenced. An explicit valid
-skill or one obvious low-risk intent normally collapses to one link. Do not keep
-Scout, Brainstorm, Research, Specs, Test, Review, Git, or delivery merely for
-ceremony.
-
-Insert a link only for a real modifier:
-
-- unresolved repository shape -> discovery;
-- unresolved material choice -> decision;
-- implementation or repair -> execution;
-- elevated risk or changed behavior -> verification;
-- high risk -> independent review and confirmation;
-- commit, push, deploy, publish, or release -> delivery, only with matching
-  user authority.
-
-## Failure detours and stop
-
-On a failed link, preserve its valid exit evidence, normalize the root cause,
-and choose one bounded detour that can change that cause. Track the failure key
-as `(link, owner, normalized cause)` within the current chain.
-
-Two failures with the same failure key stop the chain and return `BLOCKED` with
-the evidence and missing decision or capability. Different normalized causes do
-not share a key and must not stop early merely because the link name matches.
-This route-level stop does not replace a separate orchestrator's authoritative
-task-retry budget.
-
-No detour may add authority. In particular, review cannot imply push,
-diagnosis cannot imply repair, and build cannot imply deploy.

package/src/claude/skills/route/references/task-taxonomy.md

@@ -1,48 +0,0 @@
-# Task taxonomy
-
-Classify by the final deliverable the user expects, not by the first verb, file
-type, or tool mentioned. Choose exactly one class; use domains as modifiers.
-
-| Class | Final deliverable |
-|---|---|
-| `answer` | Evidence-backed explanation or factual response |
-| `discover` | Located files, call path, inventory, or blast-radius map |
-| `decide` | Chosen product, architecture, or technical direction |
-| `specify` | Approved bounded plan and executable task packet |
-| `change` | Working implementation or content change |
-| `diagnose` | Root cause and verification-ready repair plan |
-| `repair` | Cause-aligned fix plus regression proof |
-| `verify` | Test or review verdict with owned evidence |
-| `deliver` | Authorized commit, push, deploy, publish, or release result |
-
-When a request contains several verbs, classify by its terminal observable
-result. For example, “research options and implement the winner” is `change`,
-while research is a decision link. “Inspect this failure and tell me why” is
-`diagnose`, not `repair`.
-
-## Size
-
-- `trivial`: one clear reversible outcome, normally one owner and one link.
-- `standard`: multiple dependent links or a bounded cross-file/domain change.
-- `epic`: three or more independently deliverable subsystems; split them into
-  bounded routes instead of creating one oversized chain.
-
-## Risk
-
-Risk is the maximum risk of any retained link, never an average:
-
-- `low`: local, reversible, no material compatibility or data boundary.
-- `elevated`: shared contract, integration, migration, sensitive data, or a
-  meaningful regression surface.
-- `high`: security boundary, irreversible data/action, production delivery,
-  public compatibility, or large blast radius.
-
-## Domains and ambiguity
-
-Count only material domains that need distinct evidence or ownership. A file
-extension alone is not a domain. Ambiguity adds an understand or decide link
-only when unresolved information can change the final deliverable, authority,
-or verification; otherwise choose the shortest valid direct path.
-
-Modifiers constrain a route. They never grant mutation, external-action,
-commit, push, deploy, publish, or release authority.

package/src/codex/hooks/completion-authority-check.cjs

@@ -1,67 +0,0 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const STATE = require('./completion-authority-state.cjs');
-const { checkFeatureReceipt, checkReceiptDetails } = require('./lib/spec-receipt.cjs');
-const RESOLVER = require('./lib/spec-utils.cjs');
-
-const installedScripts = path.join(__dirname, '..', 'scripts');
-const scripts = fs.existsSync(path.join(installedScripts, 'spec-final-state.cjs'))
-  ? installedScripts
-  : path.resolve(__dirname, '..', '..', 'claude', 'scripts');
-
-function runtimeModule(root, name) {
-  const target = path.join(root, name);
-  const stat = fs.lstatSync(target);
-  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`runtime dependency must be a regular non-symlink file: ${name}`);
-  const canonicalRoot = fs.realpathSync(root);
-  const canonical = fs.realpathSync(target);
-  const relative = path.relative(canonicalRoot, canonical);
-  if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`runtime dependency escaped scripts root: ${name}`);
-  return require(canonical);
-}
-
-const FINAL_STATE = runtimeModule(scripts, 'spec-final-state.cjs');
-
-function explicitTarget(payload) {
-  for (const key of ['featureName', 'feature', 'explicitFeature']) {
-    if (Object.prototype.hasOwnProperty.call(payload, key)) return { explicitFeature: payload[key] };
-  }
-  for (const key of ['specPath', 'spec_path', 'featurePath']) {
-    if (Object.prototype.hasOwnProperty.call(payload, key)) return { explicitPath: payload[key] };
-  }
-  return null;
-}
-
-function resolveCandidate({ projectRoot, runtime, payload }) {
-  const target = explicitTarget(payload);
-  if (target) return RESOLVER.resolveActiveSpec({ projectRoot, runtime, ...target });
-  // Delegate so both runtimes answer the same question; the count below stays only as a
-  // fallback for an installed resolver older than this wrapper.
-  const shared = RESOLVER.resolvePersistedSpec({ projectRoot, runtime });
-  if (shared !== null) return shared;
-  const candidates = RESOLVER.findAllSpecCandidates(projectRoot, runtime);
-  if (candidates.length > 1) return { error: 'multiple_persisted', candidates: candidates.map((candidate) => candidate.featureName) };
-  return candidates[0] || null;
-}
-
-function dependencies(overrides = {}) {
-  if (!overrides.grounder) runtimeModule(scripts, 'spec-semantic-model.cjs');
-  const grounder = overrides.grounder || runtimeModule(scripts, 'spec-ground.cjs');
-  return {
-    validator: overrides.validator || runtimeModule(scripts, 'validate-spec-output.cjs'),
-    grounder,
-    semanticAuthority: overrides.semanticAuthority || require('./semantic-review-authority.cjs'),
-  };
-}
-
-module.exports = FINAL_STATE.createAuthority({
-  state: STATE,
-  resolveCandidate,
-  dependencies,
-  receipts: {
-    task: (featureDir, taskPath, task, context) => checkReceiptDetails(featureDir, taskPath, task, context),
-    feature: (featureDir, context) => checkFeatureReceipt(featureDir, context),
-  },
-});