release-skill 0.1.10 → 0.2.1

package/src/commands/verify.mjs

@@ -120,7 +120,10 @@ function matchesSubset(actual, expected) {
  * - When smokeBin is configured: the specified bin is resolved, validated
  *   against path-escape/symlink/non-regular-file guards, and executed with
  *   smokeArgs; output is validated against smokeExpectedJson (recursive
- *   subset match) when present.
+ *   subset match) when present. The expected `version` field is injected at
+ *   runtime from the unit's resolved targetVersion and overrides any
+ *   config-declared value, so the version check never depends on a
+ *   hand-written config version (T2.1 §4.3).
  * - When smokeBin is not configured: install + name/version check passes
  *   immediately; runBin is never called; result records
  *   cliSmoke: "not-configured".
@@ -162,7 +165,15 @@ export async function runSmokeTest(plan, root, options = {}) {
             unitId: unit.id,
             smokeBin: dist.smokeBin,
             smokeArgs: dist.smokeArgs ?? [],
-            smokeExpectedJson: dist.smokeExpectedJson,
+            // The expected `version` is always the unit's resolved
+            // targetVersion (whose source is version.source → package.json),
+            // injected at runtime. A config-declared smokeExpectedJson.version
+            // is redundant and overridden. This keeps the version check strong
+            // without hand-writing the version into project config, so a
+            // version bump never churns configDigest (T2.1 §4.3).
+            smokeExpectedJson: dist.smokeExpectedJson
+              ? { ...dist.smokeExpectedJson, version: unit.targetVersion }
+              : dist.smokeExpectedJson,
           });
         }
       }

package/src/core/approval.mjs

@@ -4,13 +4,21 @@
  * Centralises the safety gates that an approval record must pass before
  * any external write actions can proceed:
  * - planDigest matches the computed plan digest
- * - baseline.gitTreeHash matches the plan baseline
+ * - baseline.gitTreeHash matches the plan baseline (v1 plans only)
  * - targetVersion matches the plan's first unit target version
  * - approvedActions exactly equals plan external action ids (no superset, no subset)
  * - approval has not expired
  * - approval duration does not exceed 24 hours
  * - approvedAt is not in the future (beyond 5-minute clock skew tolerance)
  *
+ * The planVersion fork (design: t1-2-digest-decoupling.md §4.3) is
+ * centralized here: for planVersion 2 plans the baseline is record-layer
+ * data -- gitTreeHash/workspaceDigest equality and the production workspace
+ * digest algorithm double-check are NOT invalidation conditions (artifact
+ * integrity is sealed by the frozen-artifact re-verification at publish).
+ * Version, action-list, planDigest, and time-window bindings are preserved
+ * for every plan version. v1 plans keep the full legacy path untouched.
+ *
  * @module core/approval
  */
 
@@ -89,7 +97,19 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  if (!approval.planDigest || !approval.baseline?.gitTreeHash || !approval.expiresAt) {
+  // planVersion fork (centralized here; see module header): v2 plans treat
+  // the baseline as optional record-layer data.
+  const planV2 = plan?.planVersion === 2;
+
+  if (planV2) {
+    if (!approval.planDigest || !approval.expiresAt) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'approval record missing required fields: planDigest or expiresAt',
+        { approval },
+      );
+    }
+  } else if (!approval.planDigest || !approval.baseline?.gitTreeHash || !approval.expiresAt) {
     throw new ReleaseError(
       GATE_FAILED,
       'approval record missing required fields: planDigest, baseline.gitTreeHash, or expiresAt',
@@ -97,35 +117,37 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  if (plan.production?.mode === 'github-npm-v1') {
-    if (plan.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `production plan workspace digest algorithm is missing or obsolete; expected ${WORKSPACE_DIGEST_ALGORITHM}`,
-        { expected: WORKSPACE_DIGEST_ALGORITHM, actual: plan.baseline?.workspaceDigestAlgorithm ?? null },
-      );
+  if (!planV2) {
+    if (plan.production?.mode === 'github-npm-v1') {
+      if (plan.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `production plan workspace digest algorithm is missing or obsolete; expected ${WORKSPACE_DIGEST_ALGORITHM}`,
+          { expected: WORKSPACE_DIGEST_ALGORITHM, actual: plan.baseline?.workspaceDigestAlgorithm ?? null },
+        );
+      }
+      if (approval.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `production approval workspace digest algorithm is missing or obsolete; expected ${WORKSPACE_DIGEST_ALGORITHM}`,
+          { expected: WORKSPACE_DIGEST_ALGORITHM, actual: approval.baseline?.workspaceDigestAlgorithm ?? null },
+        );
+      }
     }
-    if (approval.baseline?.workspaceDigestAlgorithm !== WORKSPACE_DIGEST_ALGORITHM) {
+    if (
+      plan.baseline?.workspaceDigestAlgorithm &&
+      approval.baseline?.workspaceDigestAlgorithm !== plan.baseline.workspaceDigestAlgorithm
+    ) {
       throw new ReleaseError(
         GATE_FAILED,
-        `production approval workspace digest algorithm is missing or obsolete; expected ${WORKSPACE_DIGEST_ALGORITHM}`,
-        { expected: WORKSPACE_DIGEST_ALGORITHM, actual: approval.baseline?.workspaceDigestAlgorithm ?? null },
+        'approval workspace digest algorithm does not match the frozen plan',
+        {
+          planAlgorithm: plan.baseline.workspaceDigestAlgorithm,
+          approvalAlgorithm: approval.baseline?.workspaceDigestAlgorithm ?? null,
+        },
       );
     }
   }
-  if (
-    plan.baseline?.workspaceDigestAlgorithm &&
-    approval.baseline?.workspaceDigestAlgorithm !== plan.baseline.workspaceDigestAlgorithm
-  ) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      'approval workspace digest algorithm does not match the frozen plan',
-      {
-        planAlgorithm: plan.baseline.workspaceDigestAlgorithm,
-        approvalAlgorithm: approval.baseline?.workspaceDigestAlgorithm ?? null,
-      },
-    );
-  }
 
   // --- planDigest match ---
   const actualDigest = computePlanDigest(plan);
@@ -137,30 +159,35 @@ export function validateApproval(plan, approval, options = {}) {
     );
   }
 
-  // --- baseline.gitTreeHash match ---
-  if (approval.baseline.gitTreeHash !== plan.baseline?.gitTreeHash) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `approval baseline mismatch: approval says ${approval.baseline.gitTreeHash}, plan says ${plan.baseline?.gitTreeHash}`,
-      { approvalTreeHash: approval.baseline.gitTreeHash, planTreeHash: plan.baseline?.gitTreeHash },
-    );
-  }
-
-  // --- baseline.workspaceDigest match ---
-  if (plan.baseline?.workspaceDigest) {
-    if (!approval.baseline?.workspaceDigest) {
+  // --- baseline equality checks (v1 plans only) ---
+  // For planVersion 2 plans the baseline is record-layer data: it stays in
+  // the plan/approval files for audit but is not an invalidation condition.
+  if (!planV2) {
+    // --- baseline.gitTreeHash match ---
+    if (approval.baseline.gitTreeHash !== plan.baseline?.gitTreeHash) {
       throw new ReleaseError(
         GATE_FAILED,
-        'approval record missing baseline.workspaceDigest (plan has workspaceDigest)',
-        { planWorkspaceDigest: plan.baseline.workspaceDigest },
+        `approval baseline mismatch: approval says ${approval.baseline.gitTreeHash}, plan says ${plan.baseline?.gitTreeHash}`,
+        { approvalTreeHash: approval.baseline.gitTreeHash, planTreeHash: plan.baseline?.gitTreeHash },
       );
     }
-    if (approval.baseline.workspaceDigest !== plan.baseline.workspaceDigest) {
-      throw new ReleaseError(
-        GATE_FAILED,
-        `approval workspaceDigest mismatch: approval says ${approval.baseline.workspaceDigest}, plan says ${plan.baseline.workspaceDigest}`,
-        { approvalWorkspaceDigest: approval.baseline.workspaceDigest, planWorkspaceDigest: plan.baseline.workspaceDigest },
-      );
+
+    // --- baseline.workspaceDigest match ---
+    if (plan.baseline?.workspaceDigest) {
+      if (!approval.baseline?.workspaceDigest) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          'approval record missing baseline.workspaceDigest (plan has workspaceDigest)',
+          { planWorkspaceDigest: plan.baseline.workspaceDigest },
+        );
+      }
+      if (approval.baseline.workspaceDigest !== plan.baseline.workspaceDigest) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `approval workspaceDigest mismatch: approval says ${approval.baseline.workspaceDigest}, plan says ${plan.baseline.workspaceDigest}`,
+          { approvalWorkspaceDigest: approval.baseline.workspaceDigest, planWorkspaceDigest: plan.baseline.workspaceDigest },
+        );
+      }
     }
   }
 

package/src/core/baseline.mjs

@@ -38,6 +38,11 @@ const CONTROL_PLANE_PREFIXES = [
   '.release-skill/runs',
   '.release-skill/transactions',
   '.release-skill/kimi-attestations',
+  // T3.2 incremental hook cache: a pure local optimisation written by prepare.
+  // Excluding it keeps cache records from destabilising workspaceDigest on
+  // every prepare (and hook-cache.mjs also skips this prefix when fingerprinting
+  // inputs, so records never hash themselves).
+  '.release-skill/cache',
 ];
 const RESERVED_CONTROL_PREFIXES = [
   ...CONTROL_PLANE_PREFIXES,

package/src/core/checkpoints.mjs

@@ -0,0 +1,143 @@
+/**
+ * Shared checkpoint ordering and dependency-tier constants for the publish
+ * and reconcile sagas.
+ *
+ * These were previously duplicated byte-for-byte in `commands/publish.mjs`
+ * and `commands/reconcile.mjs` (the reconcile copy carried a `Must match
+ * publish.mjs` comment). They live here as the single source of truth so the
+ * two commands cannot drift apart (T3.1 §4.7).
+ *
+ * The tier table is a HARD-CODED dependency layering. It is never derived at
+ * runtime (no topological sort, no dynamic inference): every dependency it
+ * encodes is backed by concrete code evidence (see t3-1-parallel-checkpoints.md
+ * §3). Action types absent from every tier fail closed; they are never
+ * silently appended to the last tier.
+ *
+ * @module core/checkpoints
+ */
+
+/**
+ * Checkpoint order for the publish/reconcile sagas.
+ *
+ * Used to sort a plan's external actions into a deterministic execution
+ * order. Action types not present here sort to the end (index 999), matching
+ * the legacy inline comparator in publish.mjs.
+ */
+export const CHECKPOINT_ORDER = [
+  'push-commit',
+  'push-snapshot',
+  'set-default-branch',
+  'create-tag',
+  'npm-publish',
+  'github-release',
+  'claude-marketplace-install',
+  'codex-marketplace-install',
+  'kimi-marketplace-install',
+];
+
+/**
+ * Map plan action type to adapter ActionType.
+ *
+ * Plan uses `push-commit`, `push-snapshot`, `create-tag`, `npm-publish`,
+ * `github-release`. The adapter contract uses `git-push`, `git-tag`,
+ * `npm-publish`, `github-release`.
+ */
+export const ADAPTER_ACTION_TYPE_MAP = {
+  'push-commit': 'git-push',
+  'push-snapshot': 'push-snapshot',
+  'set-default-branch': 'set-default-branch',
+  'create-tag': 'git-tag',
+  'npm-publish': 'npm-publish',
+  'github-release': 'github-release',
+  'claude-marketplace-install': 'claude-marketplace-install',
+  'codex-marketplace-install': 'codex-marketplace-install',
+  'kimi-marketplace-install': 'kimi-marketplace-install',
+};
+
+/**
+ * Hard-coded dependency tiers for parallel checkpoint execution (T3.1 §4.1).
+ *
+ * Tiers execute strictly serially (a whole tier completes before the next
+ * begins); the actions within a tier are independent and run concurrently.
+ * Each entry's dependency is backed by code evidence:
+ * - Tier 1 `set-default-branch` / `create-tag` depend on Tier 0
+ *   `push-snapshot` (the frozen commit must exist on the remote before a tag
+ *   or branch tip can point at it). `npm-publish` has no git dependency and is
+ *   placed in Tier 1 only for conservative scheduling.
+ * - Tier 2 `github-release` and the claude/codex marketplace installs depend
+ *   on Tier 1 `create-tag` (release `--verify-tag`; install ref is the tag).
+ * - Tier 3 `kimi-marketplace-install` depends on Tier 2 `github-release`
+ *   (its install URL points at the Release page).
+ *
+ * Action types not listed in any tier are unknown to the scheduler and fail
+ * closed (see groupActionsByTier); they are never silently scheduled.
+ */
+export const TIER_TABLE = [
+  ['push-commit', 'push-snapshot'],                                              // Tier 0
+  ['set-default-branch', 'create-tag', 'npm-publish'],                          // Tier 1
+  ['github-release', 'claude-marketplace-install', 'codex-marketplace-install'], // Tier 2
+  ['kimi-marketplace-install'],                                                 // Tier 3
+];
+
+/** Fast reverse lookup: action type -> tier index (-1 when unknown). */
+const TIER_OF = new Map();
+TIER_TABLE.forEach((tierTypes, tierIndex) => {
+  for (const type of tierTypes) {
+    TIER_OF.set(type, tierIndex);
+  }
+});
+
+/**
+ * Return the tier index for an action type, or -1 if the type is not present
+ * in any tier (i.e. unknown to the scheduler and must fail closed).
+ *
+ * @param {string} actionType - The plan action type.
+ * @returns {number} Tier index (0-based) or -1.
+ */
+export function tierOfActionType(actionType) {
+  return TIER_OF.has(actionType) ? TIER_OF.get(actionType) : -1;
+}
+
+/**
+ * Sort external actions by CHECKPOINT_ORDER.
+ *
+ * Action types not in CHECKPOINT_ORDER sort to the end (index 999), matching
+ * the legacy inline comparator. Returns a new array; the input is not mutated.
+ *
+ * @param {Object[]} actions - External actions (each has a `type`).
+ * @returns {Object[]} A new sorted array.
+ */
+export function sortActionsByCheckpointOrder(actions) {
+  return (actions ?? []).slice().sort((a, b) => {
+    const ai = CHECKPOINT_ORDER.indexOf(a.type);
+    const bi = CHECKPOINT_ORDER.indexOf(b.type);
+    return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
+  });
+}
+
+/**
+ * Group an ordered list of external actions into dependency tiers.
+ *
+ * Actions are bucketed by TIER_TABLE; within a tier the input order is
+ * preserved (callers pass CHECKPOINT_ORDER-sorted actions). Actions whose type
+ * is absent from every tier are collected in `unknown` so the caller can fail
+ * closed instead of silently scheduling an unrecognized external write.
+ *
+ * @param {Object[]} orderedActions - CHECKPOINT_ORDER-sorted external actions.
+ * @returns {{ tiers: Object[][], unknown: Object[] }}
+ *   `tiers[i]` is the array of actions in tier i (possibly empty);
+ *   `unknown` holds actions whose type is not in any tier.
+ */
+export function groupActionsByTier(orderedActions) {
+  const tiers = TIER_TABLE.map(() => []);
+  const unknown = [];
+  for (const action of orderedActions ?? []) {
+    const tierIndex = tierOfActionType(action.type);
+    if (tierIndex === -1) {
+      unknown.push(action);
+    } else {
+      tiers[tierIndex].push(action);
+    }
+  }
+  return { tiers, unknown };
+}

package/src/core/evidence.mjs

@@ -95,12 +95,22 @@ export function createEvidenceWriter({ runDir, command, clock }) {
   const evidencePath = `${runDir}/evidence.jsonl`;
   const summaryPath = `${runDir}/summary.json`;
 
-  let sequence = 0;
+  // Sequences start at 1, matching schemas/evidence-event.schema.json
+  // (`sequence.minimum: 1`). The historical implementation started at 0; that
+  // was an implementation/schema drift, corrected here (T3.1 §4.4).
+  let sequence = 1;
   let handle = null;
+  // Mutex chain serializing every append. T3.1 runs same-tier checkpoints
+  // concurrently, so multiple `append` calls can be in flight at once; even
+  // under JS single-threading their awaits would interleave and could tear a
+  // line. Chaining each append behind the previous one guarantees a complete
+  // line is written before the next event starts.
+  let appendChain = Promise.resolve();
 
   /**
    * Lazily open the evidence file for appending.
    * Creates the run directory if it does not exist.
+   * Must only be called from inside the serialized append chain.
    */
   async function ensureHandle() {
     if (handle === null) {
@@ -115,16 +125,23 @@ export function createEvidenceWriter({ runDir, command, clock }) {
    * The event is enriched with automatic metadata:
    * - `schemaVersion`: always 1
    * - `runId`: extracted from the run directory name
-   * - `sequence`: auto-incrementing integer starting at 0
+   * - `sequence`: auto-incrementing integer starting at 1
    * - `timestamp`: ISO-8601 string from the clock
    * - `command`: the command passed at creation time
    *
    * The entire event object is redacted before writing.
    *
+   * Ordering semantics (T3.1 §4.4): `sequence` is guaranteed monotonic but is
+   * NOT guaranteed to match real-world completion order. Same-tier checkpoints
+   * run concurrently, so their events are serialized in whichever order reaches
+   * the mutex first. Callers that need layer context attach it as `details.tier`
+   * (no top-level field is added; the evidence schema is `additionalProperties:
+   * false` at the top level).
+   *
    * @param {Object} event - The event data. Must include `phase` and `status`;
    *   may include `error` and any other fields.
    */
-  async function append(event) {
+  async function appendOnce(event) {
     await ensureHandle();
 
     const enriched = {
@@ -144,6 +161,14 @@ export function createEvidenceWriter({ runDir, command, clock }) {
     await handle.write(`${line}\n`, null, 'utf8');
   }
 
+  function append(event) {
+    const result = appendChain.then(() => appendOnce(event));
+    // Keep the chain alive even if one append rejects; the caller still
+    // receives that rejection through `result`.
+    appendChain = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
   /**
    * Write the final summary file and close the evidence stream.
    *
@@ -152,6 +177,8 @@ export function createEvidenceWriter({ runDir, command, clock }) {
    * @param {Object} summary - The run summary object.
    */
   async function finish(summary) {
+    // Drain any in-flight appends before closing the handle.
+    await appendChain;
     await ensureHandle();
 
     const redacted = redact(summary);

package/src/core/hook-cache.mjs

@@ -0,0 +1,254 @@
+/**
+ * Incremental hook result cache (T3.2).
+ *
+ * A hook that opts in with `cacheable: true` and a `cacheInputs` glob list is
+ * keyed by the fingerprint of its full configuration plus the content of every
+ * file its inputs match. When the key is unchanged and the last run succeeded,
+ * prepare replays the cached outcome instead of re-executing the hook.
+ *
+ * Safety contract (see t3-2-incremental-hooks.md §4.8):
+ * - Failures are never cached. Only an `exitCode === 0` result is written; a
+ *   non-zero exit or HOOK_TIMEOUT leaves no record, so the next run re-executes.
+ * - The cache only ever skips execution. It runs AFTER the hook authorization
+ *   gate and never bypasses any GATE; hook order and failure semantics are
+ *   untouched.
+ * - Fail-closed inputs: if any declared `cacheInputs` glob matches no file, the
+ *   input set is considered a declaration error and caching aborts with
+ *   GATE_FAILED before the hook runs (no execution, no cache).
+ * - Default zero change: a hook without `cacheable: true` never touches the
+ *   cache directory at all.
+ *
+ * The cache is a pure local optimisation under `.release-skill/cache` (a
+ * registered control-plane prefix, excluded from workspaceDigest and
+ * .gitignore). Deleting it is equivalent to a cold miss for every hook.
+ *
+ * @module hook-cache
+ */
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson, sha256Hex } from './digest.mjs';
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+/** Control-plane location of hook cache records: `.release-skill/cache/hooks`. */
+const CACHE_BASE = ['.release-skill', 'cache', 'hooks'];
+
+/** Bounded tail length stored per stream (matches prepare's evidence tails). */
+const TAIL_LENGTH = 4000;
+
+/**
+ * Directory names never walked when enumerating hook inputs. `.git` and
+ * `node_modules` are VCS/dependency internals; `.release-skill` is the control
+ * plane and MUST stay excluded so cache records never fingerprint themselves
+ * (which would destabilise every subsequent key).
+ */
+const SKIPPED_DIRS = new Set(['.git', 'node_modules', '.release-skill']);
+
+/**
+ * Translate a `cacheInputs` glob into an anchored RegExp.
+ *
+ * Supported syntax (sufficient for input declarations):
+ * - `**`  matches any run of characters, including `/` (crosses directories)
+ * - `*`   matches any run of characters except `/`
+ * - `?`   matches a single character except `/`
+ * - every other character matches literally (regex metacharacters escaped)
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegExp(glob) {
+  let source = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        source += '.*';
+        i += 2;
+      } else {
+        source += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      source += '[^/]';
+      i += 1;
+    } else {
+      source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+      i += 1;
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * Recursively list every regular file under `root` as a `/`-separated relative
+ * path, skipping VCS/dependency/control-plane directories and symlinks (inputs
+ * are real files; symlink handling stays deterministic by not following them).
+ *
+ * @param {string} root - Absolute project root.
+ * @returns {Promise<string[]>} Sorted relative paths.
+ */
+async function listInputFiles(root) {
+  const out = [];
+
+  async function walk(dirAbs, dirRel) {
+    let entries;
+    try {
+      entries = await readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return; // Unreadable directory: treat as no inputs there.
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIPPED_DIRS.has(entry.name)) continue;
+        const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+        await walk(join(dirAbs, entry.name), rel);
+      } else if (entry.isFile()) {
+        out.push(dirRel ? `${dirRel}/${entry.name}` : entry.name);
+      }
+    }
+  }
+
+  await walk(root, '');
+  out.sort();
+  return out;
+}
+
+/**
+ * Compute the cache key for a cacheable hook.
+ *
+ * `cacheKey = sha256( canonicalJSON(hook config) + canonicalJSON(sorted matched
+ * files [{ path, sha256(content) }]) )`
+ *
+ * The full hook configuration (command/cwd/timeoutMs/envAllowlist/cacheInputs/
+ * cacheable) is part of the key, so any config change switches the key. Matched
+ * files are sorted by path before hashing for determinism.
+ *
+ * @param {Object} hook - A hook descriptor with a non-empty `cacheInputs`.
+ * @param {string} root - Absolute project root.
+ * @returns {Promise<{ cacheKey: string, matchedFiles: string[] }>}
+ * @throws {ReleaseError} GATE_FAILED when any declared glob matches no file.
+ */
+export async function computeHookCacheKey(hook, root) {
+  const globs = Array.isArray(hook.cacheInputs) ? hook.cacheInputs : [];
+  const matchers = globs.map((glob) => ({ glob, re: globToRegExp(glob) }));
+
+  const allFiles = await listInputFiles(root);
+  const matched = [];
+  const hitPerGlob = matchers.map(() => false);
+  for (const relPath of allFiles) {
+    let hit = false;
+    for (let i = 0; i < matchers.length; i += 1) {
+      if (matchers[i].re.test(relPath)) {
+        hitPerGlob[i] = true;
+        hit = true;
+      }
+    }
+    if (hit) matched.push(relPath);
+  }
+
+  // Fail-closed: a glob that matches nothing is a declaration error (a typo or
+  // a missing input). Refuse to cache rather than risk a false hit.
+  for (let i = 0; i < matchers.length; i += 1) {
+    if (!hitPerGlob[i]) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `hook cacheInputs glob "${matchers[i].glob}" matched no files; refusing to cache`,
+        { glob: matchers[i].glob },
+      );
+    }
+  }
+
+  matched.sort();
+  const fileEntries = [];
+  for (const relPath of matched) {
+    const content = await readFile(join(root, relPath));
+    fileEntries.push({ path: relPath, sha256: sha256Hex(content) });
+  }
+
+  const cacheKey = sha256Hex(canonicalJson(hook) + canonicalJson(fileEntries));
+  return { cacheKey, matchedFiles: matched };
+}
+
+/**
+ * Resolve the cache directory for a named hook.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @returns {string} Absolute path to `.release-skill/cache/hooks/<hookName>`.
+ */
+export function hookCacheDir(root, hookName) {
+  return join(root, ...CACHE_BASE, hookName);
+}
+
+/**
+ * Resolve the cache record path for a hook + key.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @returns {string} Absolute path to the `<cacheKey>.json` record.
+ */
+export function hookCachePath(root, hookName, cacheKey) {
+  return join(hookCacheDir(root, hookName), `${cacheKey}.json`);
+}
+
+/**
+ * Read a cached hook result. Returns the record only when it exists, its key
+ * matches, and it recorded a successful (`exitCode === 0`) run; anything else
+ * (missing, corrupt, or non-zero) is a miss.
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @returns {Promise<Object | null>}
+ */
+export async function readHookCache(root, hookName, cacheKey) {
+  try {
+    const raw = await readFile(hookCachePath(root, hookName, cacheKey), 'utf8');
+    const record = JSON.parse(raw);
+    if (record && record.cacheKey === cacheKey && record.exitCode === 0) {
+      return record;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a successful hook result to the cache. Never throws: a write failure
+ * returns `{ ok: false, error }` so the caller can record a warning without
+ * aborting prepare (the cache is an optimisation, not a gate).
+ *
+ * @param {string} root
+ * @param {string} hookName
+ * @param {string} cacheKey
+ * @param {Object} result
+ * @param {number} result.exitCode - Must be 0; non-zero results are not cached.
+ * @param {string} [result.stdoutTail] - Already truncated to TAIL_LENGTH.
+ * @param {string} [result.stderrTail] - Already truncated to TAIL_LENGTH.
+ * @param {string} [result.createdAt] - ISO timestamp (defaults to now).
+ * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ */
+export async function writeHookCache(root, hookName, cacheKey, result) {
+  // Defence in depth: a failure must never be persisted, even if a caller
+  // mistakenly passes a non-zero exit code.
+  if (!result || result.exitCode !== 0) {
+    return { ok: false, error: 'refusing to cache a non-zero exit result' };
+  }
+  try {
+    await mkdir(hookCacheDir(root, hookName), { recursive: true });
+    const record = {
+      cacheKey,
+      exitCode: 0,
+      stdoutTail: String(result.stdoutTail ?? '').slice(-TAIL_LENGTH),
+      stderrTail: String(result.stderrTail ?? '').slice(-TAIL_LENGTH),
+      createdAt: result.createdAt ?? new Date().toISOString(),
+    };
+    await writeFile(hookCachePath(root, hookName, cacheKey), `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}