release-skill 0.1.9 → 0.2.0

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

@@ -17,6 +17,16 @@ const execFile = promisify(execFileCb);
  * use reserved prefixes; immutable plans and approvals use exact digest-shaped
  * paths so arbitrary files under similarly named directories remain visible.
  *
+ * `kimi-attestations` holds Kimi's closure-protocol lifecycle artifacts:
+ * the manual installation requirement that publish/reconcile itself emits
+ * for a PARTIAL kimi checkpoint, and the human-written attestation that is
+ * the designed closure input (independently bound to planDigest,
+ * payloadDigest, exact version/tag, install path, responsible person, and
+ * expiry). Neither is publishable source or project configuration — they
+ * never enter the frozen snapshot — so excluding them keeps reconcile's own
+ * requirement output and the flow-required attestation from invalidating
+ * the baseline of every subsequent reconcile.
+ *
  * `project.yaml` is intentionally **not** listed — changes to project
  * configuration must always cause a baseline drift.
  */
@@ -27,6 +37,12 @@ const CONTROL_PLANE_PREFIXES = [
   '.release-skill/lock-audit',
   '.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);