release-skill 0.6.2 → 0.7.0

package/src/commands/ship.mjs

@@ -2,6 +2,7 @@ import { readFile, lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { effectiveHookRequiresApproval } from '../core/postpublish.mjs';
 import {
   ReleaseError,
   GATE_FAILED,
@@ -61,6 +62,7 @@ async function defaultDependencies() {
     reconcileModule,
     verifyModule,
     distributeModule,
+    postverifyModule,
     transportModule,
     metadataModule,
   ] = await Promise.all([
@@ -71,6 +73,7 @@ async function defaultDependencies() {
     import('./reconcile.mjs'),
     import('./verify.mjs'),
     import('./distribute.mjs'),
+    import('./postverify.mjs'),
     import('../core/git-transport.mjs'),
     import('../core/release-metadata.mjs'),
   ]);
@@ -82,6 +85,7 @@ async function defaultDependencies() {
     reconcileRelease: reconcileModule.reconcileRelease,
     verifyRelease: verifyModule.verifyRelease,
     distributeRelease: distributeModule.distributeRelease,
+    postVerifyRelease: postverifyModule.postVerifyRelease,
     preflightGitTransports: transportModule.preflightGitTransports,
     updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
   };
@@ -106,6 +110,7 @@ function publicState(state) {
     ...(state.approvalPath ? { approvalPath: state.approvalPath } : {}),
     ...(state.sourceRunPath ? { sourceRunPath: state.sourceRunPath } : {}),
     ...(state.distributeRunPath ? { distributeRunPath: state.distributeRunPath } : {}),
+    ...(state.postVerify ? { postVerify: state.postVerify } : {}),
     ...(state.requirements ? { requirements: state.requirements } : {}),
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
@@ -140,6 +145,41 @@ async function buildApprovalSummary(planPath) {
   }
 }
 
+/**
+ * Re-entry gate helper (R4 review followup 8): true when EVERY unclosed
+ * postVerify hook is ungated (effective requiresApproval false), so a failed
+ * non-gated hook (e.g. notify-handoff) can be retried without any
+ * --hook-approval file. The unclosed set comes from the last postVerify run
+ * record when readable (checkpoints not succeeded/NO_CHANGE); an unreadable
+ * or missing record falls back to ALL declared hooks — fail-safe, because a
+ * gated hook in doubt keeps the gate shut.
+ *
+ * @param {object} state - Ship state (postVerify.runPath inspected).
+ * @param {object[]} postVerifyHooks - Declared phase:postVerify hooks.
+ * @returns {Promise<boolean>}
+ */
+async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks) {
+  if (!Array.isArray(postVerifyHooks) || postVerifyHooks.length === 0) return false;
+  let candidates = postVerifyHooks;
+  if (state.postVerify?.runPath) {
+    try {
+      const record = JSON.parse(await readFile(state.postVerify.runPath, 'utf8'));
+      const checkpoints = Array.isArray(record.checkpoints) ? record.checkpoints : [];
+      const closedIds = new Set(
+        checkpoints
+          .filter((cp) => cp?.actionType === 'postpublish-hook'
+            && (cp.status === 'succeeded' || cp.status === 'NO_CHANGE'))
+          .map((cp) => cp.actionId),
+      );
+      candidates = postVerifyHooks.filter((hook) => !closedIds.has(hook.id));
+    } catch {
+      candidates = postVerifyHooks; // unreadable record: fail safe
+    }
+  }
+  if (candidates.length === 0) return false;
+  return candidates.every((hook) => effectiveHookRequiresApproval(hook) === false);
+}
+
 /**
  * Advance one durable production release. Re-running is safe: the state file
  * carries the immutable plan, approval and source-run paths so the command
@@ -304,11 +344,18 @@ export async function advanceShip(options = {}, injected = {}) {
     await writeJsonAtomic(statePath, state);
   }
 
+  // Double-run guard (R4 review followup 5): when the PUBLISHED block's
+  // step 3 executes postVerify inside this very call, the re-entry block
+  // after the lifecycle must NOT immediately re-run it.
+  let postVerifyRanThisCall = false;
+
   if (state.status === 'PUBLISHED' || state.status === 'NEEDS_MANUAL_ATTESTATIONS') {
-    // Step 1: Check if postPublish requires distribution
+    // Step 1: Check if postPublish requires distribution.
+    // Hooks-only declarations (no targets) still route through distribute.
     const plan = JSON.parse(await readFile(state.planPath, 'utf8'));
-    const needsDistribution = plan.postPublish && plan.postPublish.targets && plan.postPublish.targets.length > 0;
-    
+    const hasDistributeWork = (plan.postPublish?.targets?.length ?? 0) > 0
+      || (plan.postPublish?.hooks?.length ?? 0) > 0;
+    const needsDistribution = Boolean(plan.postPublish) && hasDistributeWork;
     if (needsDistribution && deps.distributeRelease) {
       state.status = 'DISTRIBUTING';
       await writeJsonAtomic(statePath, state);
@@ -321,17 +368,23 @@ export async function advanceShip(options = {}, injected = {}) {
           root,
           dryRun: false,
           planPath: state.planPath,
+          // Checkpoint approvals for requiresApproval distribute-phase hooks
+          // (review major-1: same seam the distribute CLI already uses).
+          ...(options.postpublishApprovalPaths ? { postpublishApprovalPaths: options.postpublishApprovalPaths } : {}),
         });
         
         state = {
           ...state,
           status: distributed.status,
-          distributeRunPath: distributed.distributeRunPath,
+          distributeRunPath: distributed.distributeRunPath ?? distributed.runPath,
           updatedAt: new Date().toISOString(),
         };
         await writeJsonAtomic(statePath, state);
         
-        if (!distributed.checkpoints || distributed.checkpoints.some((cp) => cp.status === 'failed')) {
+        // In-memory saga checkpoints carry UPPERCASE statuses ('FAILED');
+        // the persisted run record is the lowercase projection. Comparing
+        // against 'failed' here was dead code until v0.6.3 (review note-5).
+        if (!distributed.checkpoints || distributed.checkpoints.some((cp) => cp.status === 'FAILED')) {
           state.status = 'PARTIAL';
           await writeJsonAtomic(statePath, state);
           return publicState(state);
@@ -372,6 +425,100 @@ export async function advanceShip(options = {}, injected = {}) {
       };
       await writeJsonAtomic(statePath, state);
     }
+
+    // Step 3: postVerify phase (design §2.4). phase:postVerify hooks run in an
+    // independent run after the main run is VERIFIED, with the verify run as
+    // lineage source. A PARTIAL postVerify run or a postVerify gate failure
+    // NEVER demotes VERIFIED — the outcome is recorded on the ship state.
+    const postVerifyHooks = (plan.postPublish?.hooks ?? [])
+      .filter((hook) => hook.phase === 'postVerify');
+    if (state.status === 'VERIFIED' && postVerifyHooks.length > 0 && deps.postVerifyRelease) {
+      postVerifyRanThisCall = true;
+      let postVerifyOutcome;
+      try {
+        const postVerified = await deps.postVerifyRelease({
+          planPath: state.planPath,
+          approvalPath: state.approvalPath,
+          sourceRunPath: state.verifyRunPath,
+          root,
+          postpublishApprovalPaths: options.postpublishApprovalPaths,
+        });
+        postVerifyOutcome = {
+          status: postVerified.status,
+          runPath: postVerified.runPath,
+        };
+      } catch (error) {
+        postVerifyOutcome = {
+          status: 'FAILED',
+          error: {
+            code: error?.code ?? GATE_FAILED,
+            message: error?.message ?? String(error),
+          },
+        };
+      }
+      state = {
+        ...state,
+        postVerify: postVerifyOutcome,
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    }
+  }
+
+  // postVerify re-entry (design §2.4; review major-1). Once the main run is
+  // VERIFIED, ship no longer enters the PUBLISHED block, so a postVerify
+  // outcome parked at AWAITING_APPROVAL (run status NEEDS_INPUT) could never
+  // complete through the CLI. The gate opens when a checkpoint approval is
+  // provided OR every unclosed postVerify hook is ungated (R4 review
+  // followup 8: a failed requiresApproval:false hook retries without any
+  // approval file; a gated hook still unclosed keeps the gate shut).
+  // Re-entry re-runs the phase — rerun IS the reconcile: approved hooks
+  // execute, already-delivered hooks stay idempotent, the verify run remains
+  // the lineage source, and the main VERIFIED status never changes. When the
+  // gate stays shut this block is a no-op: zero postVerify work, no writes.
+  const reentryApprovalPaths = options.postpublishApprovalPaths ?? [];
+  if (
+    state.status === 'VERIFIED'
+    && deps.postVerifyRelease
+    && !postVerifyRanThisCall
+    && (!state.postVerify || state.postVerify.status !== 'DISTRIBUTED')
+  ) {
+    const reentryPlan = JSON.parse(await readFile(state.planPath, 'utf8'));
+    const reentryPostVerifyHooks = (reentryPlan.postPublish?.hooks ?? [])
+      .filter((hook) => hook.phase === 'postVerify');
+    const approvallessRetryAllowed = reentryApprovalPaths.length === 0
+      && await allUnclosedPostVerifyHooksUngated(state, reentryPostVerifyHooks);
+    if (reentryPostVerifyHooks.length > 0
+      && (reentryApprovalPaths.length > 0 || approvallessRetryAllowed)) {
+      let postVerifyOutcome;
+      try {
+        const postVerified = await deps.postVerifyRelease({
+          planPath: state.planPath,
+          approvalPath: state.approvalPath,
+          sourceRunPath: state.verifyRunPath,
+          root,
+          postpublishApprovalPaths: reentryApprovalPaths,
+        });
+        postVerifyOutcome = {
+          status: postVerified.status,
+          runPath: postVerified.runPath,
+        };
+      } catch (error) {
+        postVerifyOutcome = {
+          status: 'FAILED',
+          error: {
+            code: error?.code ?? GATE_FAILED,
+            message: error?.message ?? String(error),
+          },
+        };
+      }
+      state = {
+        ...state,
+        postVerify: postVerifyOutcome,
+        updatedAt: new Date().toISOString(),
+      };
+      await writeJsonAtomic(statePath, state);
+    }
   }
 
   return publicState(state);

package/src/commands/verify.mjs

@@ -25,6 +25,7 @@ import { validatePlan, computePlanDigest, validatePlanActionCompleteness } from
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import {
   loadRun,
+  resolveRunPath,
   validateRunPlanDigest,
   validateRunCheckpointMapping,
   validateRunLineage,
@@ -822,6 +823,47 @@ async function discoverDistributeRuns({ planPath, plan }) {
   return candidates;
 }
 
+/**
+ * Evaluate one distribute run against the verify distribute gate
+ * (v0.6.3 R1, design §2.4/§2.7).
+ *
+ * Semantics:
+ * - A DISTRIBUTED run passes outright (no warning).
+ * - A PARTIAL run passes only when EVERY checkpoint that is not
+ *   succeeded/skipped is a FAILED `postpublish-hook` checkpoint whose hook
+ *   declaration in the frozen plan explicitly downgrades with
+ *   `blocksVerified: false` (default true). Each such downgrade is reported
+ *   as a warning exemption — prominently evidenced, never silent.
+ * - AWAITING_APPROVAL checkpoints never pass (the checkpoint approval is
+ *   still missing), and target/mirror checkpoints are never exemptable.
+ * - Any other run status (BLOCKED / NEEDS_INPUT / ...) never passes, per the
+ *   governance rule that NEEDS_INPUT/BLOCKED cannot silently become VERIFIED.
+ *
+ * @param {Object} run - A distribute run record (checkpoints + status).
+ * @param {Object} plan - The frozen release plan (postPublish.hooks source).
+ * @returns {{ pass: boolean, warned: boolean, exemptions: Object[] }}
+ */
+export function evaluateDistributeGateRun(run, plan) {
+  if (!run || typeof run !== 'object') return { pass: false, warned: false, exemptions: [] };
+  if (run.status === 'DISTRIBUTED') return { pass: true, warned: false, exemptions: [] };
+  if (run.status !== 'PARTIAL') return { pass: false, warned: false, exemptions: [] };
+
+  const hooksById = new Map(((plan?.postPublish?.hooks ?? [])).map((hook) => [hook.id, hook]));
+  const exemptions = [];
+  for (const checkpoint of run.checkpoints ?? []) {
+    if (checkpoint.status === 'succeeded' || checkpoint.status === 'skipped') continue;
+    const hook = checkpoint.actionType === 'postpublish-hook'
+      ? hooksById.get(checkpoint.actionId)
+      : undefined;
+    if (hook && checkpoint.status === 'failed' && hook.blocksVerified === false) {
+      exemptions.push({ actionId: checkpoint.actionId, status: checkpoint.status });
+      continue;
+    }
+    return { pass: false, warned: false, exemptions: [] };
+  }
+  return { pass: true, warned: exemptions.length > 0, exemptions };
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -831,7 +873,8 @@ async function discoverDistributeRuns({ planPath, plan }) {
  *
  * @param {Object} options
  * @param {string} options.planPath - Absolute path to the frozen release plan.
- * @param {string} options.sourceRunPath - Absolute path to the source run.
+ * @param {string} options.sourceRunPath - Absolute path to the source run
+ *   file, or to its containing run directory (resolved to release-run.json; O6).
  * @param {Object} options.adapterRegistry - Adapter registry for verification.
  * @param {string} [options.root] - Project root for source access.
  * @param {string} [options.runDir] - Evidence directory.
@@ -870,6 +913,11 @@ export async function verifyRelease(options) {
     );
   }
 
+  // O6: --run accepts a run directory as well as the run file. Resolve a
+  // directory to its release-run.json before any load/lineage/authority step;
+  // a file input passes through unchanged (compat).
+  const resolvedSourceRunPath = await resolveRunPath(sourceRunPath);
+
   // Load and validate the plan before creating any evidence directory. A
   // production plan grants authority only to a fresh direct child of its
   // sibling .release-skill/runs directory.
@@ -936,14 +984,14 @@ export async function verifyRelease(options) {
     // =======================================================================
     await evidence.append({ phase: 'verify', step: 'source-run-load', status: 'started' });
 
-    const sourceRun = await loadRun(sourceRunPath, {
+    const sourceRun = await loadRun(resolvedSourceRunPath, {
       requireDigest: Boolean(plan.production),
       ...(plan.production ? { authorityPlanPath: planPath } : {}),
     });
     await validateRunLineage(sourceRun, {
       plan,
       planPath,
-      runPath: sourceRunPath,
+      runPath: resolvedSourceRunPath,
       production: Boolean(plan.production),
     });
 
@@ -966,29 +1014,58 @@ export async function verifyRelease(options) {
     }
 
     // =======================================================================
-    // Step 2b: Check for postPublish distribution requirement
+    // Step 2b: Check for postPublish distribution requirement.
+    // v0.6.3 R1: the gate triggers on targets OR hooks declarations, and a
+    // PARTIAL distribute run passes only through the blocksVerified:false
+    // exemption path (evaluateDistributeGateRun) — warned, never silent.
     // =======================================================================
-    if (plan.postPublish && plan.postPublish.targets && plan.postPublish.targets.length > 0) {
+    const declaredPostPublishTargets = plan.postPublish?.targets ?? [];
+    const declaredPostPublishHooks = plan.postPublish?.hooks ?? [];
+    if (plan.postPublish
+      && (declaredPostPublishTargets.length > 0 || declaredPostPublishHooks.length > 0)) {
       await evidence.append({ phase: 'verify', step: 'distribute-run-discovery', status: 'started' });
-      
-      const distributeCandidates = await discoverDistributeRuns({ planPath, plan });
-      const distRunPath = (distributeCandidates ?? []).find((c) => c.status === 'DISTRIBUTED')?.runPath || null;
-      
+
+      const distributeCandidates = await discoverDistributeRuns({ planPath, plan }) ?? [];
+
+      let gateRun = distributeCandidates.find((c) => c.status === 'DISTRIBUTED') ?? null;
+      let gateVerdict = gateRun ? { pass: true, warned: false, exemptions: [] } : null;
+      if (!gateRun) {
+        for (const candidate of distributeCandidates) {
+          const verdict = evaluateDistributeGateRun(candidate, plan);
+          if (verdict.pass) {
+            gateRun = candidate;
+            gateVerdict = verdict;
+            break;
+          }
+        }
+      }
+
       await evidence.append({
         phase: 'verify',
         step: 'distribute-run-discovery',
         status: 'checked',
-        foundCandidate: !!distRunPath,
-        distributeRunPath: distRunPath,
+        foundCandidate: Boolean(gateRun),
+        distributeRunPath: gateRun?.runPath ?? null,
       });
-      
-      if (!distRunPath) {
+
+      if (!gateRun) {
         throw new ReleaseError(
           GATE_FAILED,
-          `distribution required by plan.postPublish but no DISTRIBUTED run found; run release-skill distribute --plan ${planPath} --root ${root}`,
+          `distribution required by plan.postPublish but no DISTRIBUTED (or blocksVerified-exempted) distribute run found; run release-skill distribute --plan ${planPath} --root ${root}`,
           { requiredDistribution: true, evidenceEvent: 'distribute-run-missing' },
         );
       }
+
+      if (gateVerdict.warned) {
+        await evidence.append({
+          phase: 'verify',
+          step: 'distribute-gate',
+          status: 'warning',
+          warning: 'blocksVerified:false postPublish hook failure exempted; VERIFIED proceeds with a downgrade warning',
+          exemptions: gateVerdict.exemptions,
+          distributeRunPath: gateRun.runPath ?? null,
+        });
+      }
     }
 
     if (plan.production) {
@@ -1772,7 +1849,7 @@ export async function verifyRelease(options) {
       } : {}),
       sourceRunId: sourceRun.runId,
       sourceRunDigest,
-      sourceRunPath,
+      sourceRunPath: resolvedSourceRunPath,
       status: VERIFIED,
       checkpoints: actions.map((a) => {
         const check = adapterChecks.find((c) => c.actionId === a.id);

package/src/core/approval.mjs

@@ -58,6 +58,94 @@ export function computeApprovalDigest(rawApproval) {
     : JSON.stringify(rawApproval, null, 2));
 }
 
+/** Maximum approval window: 24 hours. */
+export const MAX_APPROVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/** Clock-skew tolerance for approvedAt: 5 minutes. */
+export const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Validate the time-window semantics shared by every approval record kind
+ * (plan-level approvals and v0.6.3 R1 checkpoint-level postPublish hook
+ * approvals): well-formed timestamps, expiresAt after approvedAt, a maximum
+ * 24h window, approvedAt not in the future beyond 5-minute clock skew, and
+ * (unless requireUnexpired === false) an unexpired window at `clock`.
+ *
+ * @param {{ approvedAt?: string, expiresAt?: string }} approval
+ * @param {Object} [options]
+ * @param {() => string} [options.clock]  Clock function returning ISO-8601 strings.
+ * @param {boolean} [options.requireUnexpired]  Default true.
+ *
+ * @throws {ReleaseError} GATE_FAILED on any violation.
+ */
+export function validateApprovalTimeWindow(approval, options = {}) {
+  const clockFn = typeof options.clock === 'function' ? options.clock : () => new Date().toISOString();
+
+  const approvedAtDate = new Date(approval.approvedAt);
+  if (Number.isNaN(approvedAtDate.getTime())) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `invalid approvedAt: "${approval.approvedAt}"`,
+      { approvedAt: approval.approvedAt },
+    );
+  }
+
+  const expiresAtDate = new Date(approval.expiresAt);
+  if (Number.isNaN(expiresAtDate.getTime())) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `invalid expiresAt: "${approval.expiresAt}"`,
+      { expiresAt: approval.expiresAt },
+    );
+  }
+
+  if (expiresAtDate.getTime() <= approvedAtDate.getTime()) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `expiresAt (${approval.expiresAt}) must be after approvedAt (${approval.approvedAt})`,
+      { approvedAt: approval.approvedAt, expiresAt: approval.expiresAt },
+    );
+  }
+
+  // --- Max 24h approval window ---
+  const approvalDurationMs = expiresAtDate.getTime() - approvedAtDate.getTime();
+  if (approvalDurationMs > MAX_APPROVAL_MS) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `approval duration ${Math.round(approvalDurationMs / 3600000)}h exceeds maximum 24h`,
+      { approvedAt: approval.approvedAt, expiresAt: approval.expiresAt, durationHours: approvalDurationMs / 3600000 },
+    );
+  }
+
+  // --- Reject future approvedAt (beyond 5-minute clock skew tolerance) ---
+  const now = clockFn();
+  const nowDate = new Date(now);
+  if (Number.isNaN(nowDate.getTime())) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `invalid clock value: "${now}"`,
+      { clock: now },
+    );
+  }
+  if (approvedAtDate.getTime() > nowDate.getTime() + CLOCK_SKEW_TOLERANCE_MS) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `approvedAt (${approval.approvedAt}) is in the future (current time: ${now})`,
+      { approvedAt: approval.approvedAt, now },
+    );
+  }
+
+  // --- Expiry (publish/reconcile require current approval; verify may only
+  // revalidate the immutable approval identity after publication) ---
+  if (options.requireUnexpired !== false && nowDate > expiresAtDate) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `approval expired at ${approval.expiresAt}, current time is ${now}`,
+      { expiresAt: approval.expiresAt, now },
+    );
+  }
+}
+
 export function assertImmutableApprovalAuthority(approvalPath, plan, rawApproval) {
   if (!plan?.production) return;
   const planDigest = computePlanDigest(plan);
@@ -89,8 +177,6 @@ export function assertImmutableApprovalAuthority(approvalPath, plan, rawApproval
  * @throws {ReleaseError} GATE_FAILED if any validation check fails.
  */
 export function validateApproval(plan, approval, options = {}) {
-  const clockFn = typeof options.clock === 'function' ? options.clock : () => new Date().toISOString();
-
   // --- Required fields ---
   if (!approval || typeof approval !== 'object') {
     throw new ReleaseError(
@@ -290,71 +376,10 @@ export function validateApproval(plan, approval, options = {}) {
     }
   }
 
-  // --- Time validation ---
-  const approvedAtDate = new Date(approval.approvedAt);
-  if (Number.isNaN(approvedAtDate.getTime())) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `invalid approvedAt: "${approval.approvedAt}"`,
-      { approvedAt: approval.approvedAt },
-    );
-  }
-
-  const expiresAtDate = new Date(approval.expiresAt);
-  if (Number.isNaN(expiresAtDate.getTime())) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `invalid expiresAt: "${approval.expiresAt}"`,
-      { expiresAt: approval.expiresAt },
-    );
-  }
-
-  if (expiresAtDate.getTime() <= approvedAtDate.getTime()) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `expiresAt (${approval.expiresAt}) must be after approvedAt (${approval.approvedAt})`,
-      { approvedAt: approval.approvedAt, expiresAt: approval.expiresAt },
-    );
-  }
-
-  // --- Max 24h approval window ---
-  const MAX_APPROVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-  const approvalDurationMs = expiresAtDate.getTime() - approvedAtDate.getTime();
-  if (approvalDurationMs > MAX_APPROVAL_MS) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `approval duration ${Math.round(approvalDurationMs / 3600000)}h exceeds maximum 24h`,
-      { approvedAt: approval.approvedAt, expiresAt: approval.expiresAt, durationHours: approvalDurationMs / 3600000 },
-    );
-  }
-
-  // --- Reject future approvedAt (beyond 5-minute clock skew tolerance) ---
-  const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000; // 5 minutes
-  const now = clockFn();
-  const nowDate = new Date(now);
-  if (Number.isNaN(nowDate.getTime())) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `invalid clock value: "${now}"`,
-      { clock: now },
-    );
-  }
-  if (approvedAtDate.getTime() > nowDate.getTime() + CLOCK_SKEW_TOLERANCE_MS) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `approvedAt (${approval.approvedAt}) is in the future (current time: ${now})`,
-      { approvedAt: approval.approvedAt, now },
-    );
-  }
-
-  // --- Expiry (publish/reconcile require current approval; verify may only
-  // revalidate the immutable approval identity after publication) ---
-  if (options.requireUnexpired !== false && nowDate > expiresAtDate) {
-    throw new ReleaseError(
-      GATE_FAILED,
-      `approval expired at ${approval.expiresAt}, current time is ${now}`,
-      { expiresAt: approval.expiresAt, now },
-    );
-  }
+  // --- Time validation (shared authority: 24h window, 5-minute skew, expiry) ---
+  validateApprovalTimeWindow(approval, {
+    clock: options.clock,
+    requireUnexpired: options.requireUnexpired,
+  });
 
 }

package/src/core/bounded-output.mjs

@@ -0,0 +1,46 @@
+/**
+ * Bounded hook-output tails (v0.6.3 R1 tail unification).
+ *
+ * Single authority for the "last 50 lines, capped at 8 KiB" tail semantics
+ * used everywhere a captured child-output stream is persisted as evidence:
+ * prepare hook failures (original home) and distribute postPublish hook
+ * failures (R1; previously a 4000-character slice). Keeping both call sites
+ * on one implementation means triage output can never diverge between the
+ * prepare and distribute phases.
+ *
+ * @module core/bounded-output
+ */
+
+/** Maximum number of output lines preserved in a hook-failure tail. */
+export const HOOK_OUTPUT_TAIL_MAX_LINES = 50;
+/** Maximum bytes preserved in a hook-failure tail. */
+export const HOOK_OUTPUT_TAIL_MAX_BYTES = 8 * 1024;
+
+/**
+ * Bound a captured child-output stream to the tail that matters for triage:
+ * the last 50 lines, further capped at 8 KB — whichever is smaller.
+ *
+ * @param {string} [text] - Captured stdout/stderr text.
+ * @returns {string} The bounded tail ('' for empty/absent input).
+ */
+export function boundedOutputTail(text) {
+  if (typeof text !== 'string' || text.length === 0) return '';
+  let lines = text.split('\n');
+  // A trailing newline produces an empty final element; drop it so the line
+  // budget counts real output lines.
+  if (lines.length > 1 && lines[lines.length - 1] === '') {
+    lines = lines.slice(0, -1);
+  }
+  let tail = lines.slice(-HOOK_OUTPUT_TAIL_MAX_LINES);
+  let joined = tail.join('\n');
+  while (tail.length > 1 && Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
+    tail = tail.slice(1);
+    joined = tail.join('\n');
+  }
+  if (Buffer.byteLength(joined, 'utf8') > HOOK_OUTPUT_TAIL_MAX_BYTES) {
+    // A single line exceeds the byte cap: keep the trailing bytes.
+    const buf = Buffer.from(joined, 'utf8');
+    joined = buf.subarray(buf.length - HOOK_OUTPUT_TAIL_MAX_BYTES).toString('utf8');
+  }
+  return joined;
+}