release-skill 0.9.0 → 0.9.1

package/src/commands/ship.mjs

@@ -2,6 +2,7 @@ import { readFile, lstat, mkdir } from 'node:fs/promises';
 import { basename, dirname, resolve } from 'node:path';
 import { publishFileOrReplace } from 'skill-family-harness-node';
 
+import { MAX_APPROVAL_MS } from '../core/approval.mjs';
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
 import {
   effectiveHookRequiresApproval,
@@ -88,6 +89,7 @@ async function defaultDependencies() {
     postVerifyRelease: postverifyModule.postVerifyRelease,
     preflightGitTransports: transportModule.preflightGitTransports,
     updatePreviousPublicBaselines: metadataModule.updatePreviousPublicBaselines,
+    readMaxApprovalMs: () => MAX_APPROVAL_MS,
   };
 }
 
@@ -116,34 +118,135 @@ function publicState(state) {
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
     ...(state.postRelease ? { postRelease: state.postRelease } : {}),
-    verificationGateAuthorizationIncludedInPlanApproval: true,
-    postVerifyMetadataUpdateIncludedInPlanApproval: true,
+    externalActionsIncludedInPlanApproval: true,
+    verificationGatesIncludedInPlanApproval: true,
+    postPublishCheckpointApprovalsIncludedInPlanApproval: false,
   };
 }
 
+const HOUR_MS = 60 * 60 * 1000;
+
+const ACTION_TARGET_FIELDS = Object.freeze({
+  'push-commit': Object.freeze(['remote', 'branch']),
+  'push-snapshot': Object.freeze(['repo', 'branch', 'branchStrategy', 'commit']),
+  'create-tag': Object.freeze(['repo', 'tag', 'commit']),
+  'npm-publish': Object.freeze(['package', 'version', 'registry', 'tag', 'access', 'provenance']),
+  'github-release': Object.freeze(['repo', 'tag', 'name', 'commit']),
+  'claude-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'codex-marketplace-install': Object.freeze(['consumer', 'plugin', 'marketplace', 'repo', 'ref', 'version', 'entrySkill']),
+  'kimi-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'codebuddy-marketplace-install': Object.freeze(['consumer', 'plugin', 'repo', 'ref', 'version', 'entrySkill']),
+  'set-default-branch': Object.freeze(['repo', 'oldBranch', 'newBranch', 'expectedNewBranchCommit']),
+});
+
+function deriveApprovalWindowHours(maxApprovalMs) {
+  if (
+    !Number.isSafeInteger(maxApprovalMs)
+    || maxApprovalMs <= 0
+    || maxApprovalMs % HOUR_MS !== 0
+  ) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      'core approval window must be a positive whole number of hours',
+      { maxApprovalMs },
+    );
+  }
+  return maxApprovalMs / HOUR_MS;
+}
+
+function projectActionTarget(action) {
+  const parameters = action?.parameters ?? {};
+  return Object.fromEntries(
+    (ACTION_TARGET_FIELDS[action?.type] ?? [])
+      .filter((field) => parameters[field] !== undefined)
+      .map((field) => [field, parameters[field]]),
+  );
+}
+
 /**
  * Build a human-readable approval summary from the frozen plan.
- * Lists each unit's version and every external action's id/type/unitId.
- * Returns an empty summary when the plan file is not yet available (e.g., in tests).
+ * Lists every publish target and every checkpoint approval separately. All
+ * fields are mechanically projected from the frozen plan; unreadable plans
+ * fail closed instead of producing an empty or partial summary.
  *
  * @param {string} planPath - Path to the frozen release plan.
  * @returns {Promise<object>} The approval summary.
  */
-async function buildApprovalSummary(planPath) {
+async function buildApprovalSummary(planPath, maxApprovalMs = MAX_APPROVAL_MS) {
   try {
     const plan = JSON.parse(await readFile(planPath, 'utf8'));
-    const units = (plan.units ?? []).map((unit) => ({
-      id: unit.id,
-      targetVersion: unit.targetVersion ?? unit.version,
-    }));
+    const approvalWindowHours = deriveApprovalWindowHours(maxApprovalMs);
     const actions = (plan.externalActions ?? []).map((action) => ({
       id: action.id,
       type: action.type,
       unitId: action.unitId,
+      target: projectActionTarget(action),
     }));
-    return { units, actions };
-  } catch {
-    return { units: [], actions: [] };
+    const units = (plan.units ?? []).map((unit) => {
+      const targetVersion = unit.targetVersion ?? unit.version;
+      const githubRelease = (plan.externalActions ?? [])
+        .find((action) => action.unitId === unit.id && action.type === 'github-release');
+      return {
+        id: unit.id,
+        targetVersion,
+        publicRepo: unit.publicRepo,
+        branch: unit.frozenSnapshot?.branch
+          ?? unit.productionConfig?.branchTemplate
+            ?.replaceAll('{tag}', unit.tagTemplate?.replace('{version}', targetVersion) ?? '')
+            .replaceAll('{version}', targetVersion)
+            .replaceAll('{unit}', unit.id),
+        branchStrategy: unit.frozenSnapshot?.branchStrategy ?? unit.productionConfig?.branchStrategy,
+        tag: unit.tagTemplate?.replace('{version}', targetVersion),
+        npm: (unit.distributions ?? [])
+          .filter((distribution) => distribution.type === 'npm')
+          .map((distribution) => ({
+            package: distribution.package,
+            version: targetVersion,
+            registry: distribution.registry,
+            distTag: distribution.tag,
+            access: distribution.access,
+            provenance: distribution.provenance,
+          })),
+        ...(githubRelease ? {
+          githubRelease: {
+            repo: githubRelease.parameters?.repo ?? githubRelease.parameters?.publicRepo,
+            tag: githubRelease.parameters?.tag,
+            name: githubRelease.parameters?.name,
+          },
+        } : {}),
+      };
+    });
+    const postPublishCheckpointApprovals = normalizePostPublishView(plan)
+      .flatMap((declaration) => (declaration.hooks ?? [])
+        .filter((hook) => effectiveHookRequiresApproval(hook))
+        .map((hook) => ({
+          unitId: declaration.unitId,
+          hookId: hook.id,
+          actionId: postPublishActionId({
+            planVersion: plan.planVersion,
+            unitId: declaration.unitId,
+            localId: hook.id,
+          }),
+          phase: hook.phase ?? 'distribute',
+          ...(hook.preset !== undefined ? { preset: hook.preset } : {}),
+          ...(hook.config?.delivery !== undefined ? { delivery: hook.config.delivery } : {}),
+          requiresApproval: true,
+          includedInPlanApproval: false,
+          approvalWindowHours,
+          binding: { planDigest: plan.digest, hookId: hook.id },
+        })));
+    return {
+      units,
+      actions,
+      waivers: Array.isArray(plan.waivers) ? plan.waivers : [],
+      postPublishCheckpointApprovals,
+    };
+  } catch (error) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `cannot build ship approval summary from frozen plan: ${error.message}`,
+      { planPath },
+    );
   }
 }
 
@@ -197,9 +300,11 @@ async function allUnclosedPostVerifyHooksUngated(state, postVerifyHooks, planVer
  * resumes instead of reconstructing authority from terminal/chat output.
  *
  * New flow (v0.4+): ship directly runs configured hooks and verification gates
- * without a separate hook authorization step. The only human gate is plan
- * approval. Kimi/CodeBuddy installations are non-blocking manual follow-up
- * tasks when the plan declares humanConsumersStrategy: 'manualFollowUps'.
+ * without a separate hook authorization step. Plan approval is the only
+ * normal release-level gate. A postPublish hook whose effective
+ * requiresApproval is true still needs its independent checkpoint approval.
+ * Kimi/CodeBuddy installations are non-blocking manual follow-up tasks when
+ * the plan declares humanConsumersStrategy: 'manualFollowUps'.
  */
 export async function advanceShip(options = {}, injected = {}) {
   const root = resolve(options.root ?? process.cwd());
@@ -268,7 +373,10 @@ export async function advanceShip(options = {}, injected = {}) {
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }
-    const approvalSummary = await buildApprovalSummary(prepared.planPath);
+    const maxApprovalMs = typeof deps.readMaxApprovalMs === 'function'
+      ? await deps.readMaxApprovalMs()
+      : MAX_APPROVAL_MS;
+    const approvalSummary = await buildApprovalSummary(prepared.planPath, maxApprovalMs);
     state = {
       ...state,
       status: 'NEEDS_PLAN_APPROVAL',

package/src/core/derived-artifact-gates.mjs

@@ -5,17 +5,20 @@
  * In the 0.6.1 cycle two prepares burned the full ~80s test hook before
  * surfacing drift that a sub-second check could have caught: adapter trees
  * out of sync with skills-src/, and self-bootstrap fact pins still bound to
- * the previous version. This module promotes those two exact checks to
- * prepare's earliest stage, alongside the bundle freshness gate:
+ * the previous version. This module promotes those checks and the platform
+ * manifest freshness check to prepare's earliest stage, alongside the bundle
+ * freshness gate:
  *
  * - adapter gate: runs `scripts/build-adapters.mjs --check` (drift list,
  *   exit 1 on drift — the same supported check the scripts surface offers);
+ * - platform manifest gate: runs
+ *   `scripts/generate-platform-manifest.mjs --check`;
  * - fact-pin gate: runs the version fact pins of
  *   `test/release-docs-self-bootstrap.test.mjs` — exactly its hermetic
  *   section 1 (`[self-bootstrap 1*]`: byte-level version assertions plus the
  *   in-process read-only planner), scoped via `--test-name-pattern`.
  *
- * Both promote the CANONICAL check logic — the gate and the full pipeline
+ * All three promote the CANONICAL check logic — the gates and the full pipeline
  * can never disagree about what "in sync" means. The facts gate is scoped to
  * the suite's hermetic fact-pin section deliberately: the suite's remaining
  * sections shell out to npm/git and drive fixture prepares, which would make
@@ -88,6 +91,15 @@ const GATES = Object.freeze({
       'Rebuild the existing adapters with: node scripts/build-adapters.mjs --apply ' +
       `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
   }),
+  'platform-manifest': Object.freeze({
+    artifact: 'platform-manifest',
+    marker: join('scripts', 'generate-platform-manifest.mjs'),
+    argv: (pkgRoot) => [join(pkgRoot, 'scripts', 'generate-platform-manifest.mjs'), '--check'],
+    timeoutMs: 120000,
+    remediation:
+      'Regenerate the platform manifest with: node scripts/generate-platform-manifest.mjs ' +
+      `(or run the one-click derived-artifact sync from the workspace root: ${DERIVED_SYNC_COMMAND}).`,
+  }),
   'self-bootstrap-facts': Object.freeze({
     artifact: 'self-bootstrap-facts',
     marker: join('test', 'release-docs-self-bootstrap.test.mjs'),
@@ -118,7 +130,7 @@ async function isFile(path) {
 /**
  * Run one derived-artifact check (pure decision, never throws).
  *
- * @param {'adapters' | 'self-bootstrap-facts'} kind - Gate to run.
+ * @param {'adapters' | 'platform-manifest' | 'self-bootstrap-facts'} kind - Gate to run.
  * @param {string} pkgRoot - Absolute package root of the running checkout.
  * @param {object} [options]
  * @param {Function} [options.execFileFn] - execFile seam (tests).
@@ -202,6 +214,11 @@ export function checkAdapterFreshness(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('adapters', pkgRoot, options);
 }
 
+/** Platform manifest freshness decision (generate-platform-manifest --check). */
+export function checkPlatformManifestFreshness(pkgRoot, options = {}) {
+  return checkDerivedArtifactGate('platform-manifest', pkgRoot, options);
+}
+
 /** Self-bootstrap fact-pin decision (single-file test). */
 export function checkSelfBootstrapFacts(pkgRoot, options = {}) {
   return checkDerivedArtifactGate('self-bootstrap-facts', pkgRoot, options);
@@ -215,7 +232,9 @@ async function assertGate(kind, pkgRoot, options = {}) {
   const gate = GATES[kind];
   const subject = kind === 'adapters'
     ? 'adapters/ is out of sync with its sources (build-adapters --check reported drift)'
-    : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
+    : kind === 'platform-manifest'
+      ? 'platform-manifest.json is out of sync with the current package tree (generate-platform-manifest --check reported drift)'
+      : 'the release-docs-self-bootstrap fact pins are stale (the hermetic fact-pin check failed)';
   throw new ReleaseError(
     DERIVED_ARTIFACT_STALE,
     `${subject}. ${DERIVED_ARTIFACT_PREGATE_NOTE} ${gate.remediation}`,
@@ -243,6 +262,14 @@ export function assertAdapterFreshness(pkgRoot, options = {}) {
   return assertGate('adapters', pkgRoot, options);
 }
 
+/**
+ * Fail-closed platform manifest pre-gate used by prepare's earliest stage.
+ * Not-applicable layouts return quietly; drift throws DERIVED_ARTIFACT_STALE.
+ */
+export function assertPlatformManifestFreshness(pkgRoot, options = {}) {
+  return assertGate('platform-manifest', pkgRoot, options);
+}
+
 /**
  * Fail-closed self-bootstrap fact-pin pre-gate used by prepare's earliest
  * stage. Not-applicable layouts return quietly; drift throws

package/src/producers/foundation-resource-projection.mjs

@@ -55,9 +55,9 @@ import { digestBytes, publishFileOrReplace, readFileStrict, withTemporaryWorkspa
 import { canonicalJson } from '../core/digest.mjs';
 
 export const FOUNDATION_PACKAGES = Object.freeze({
-  'skill-family-contracts': '0.13.0',
-  'skill-family-engineering-kit': '0.13.0',
-  'skill-family-harness-node': '0.13.0',
+  'skill-family-contracts': '0.14.0',
+  'skill-family-engineering-kit': '0.14.0',
+  'skill-family-harness-node': '0.14.0',
 });
 
 export const BINDING_RECORD_PATH = 'bin/foundation-resource-binding.json';
@@ -295,6 +295,19 @@ export async function computeFoundationProjection({ pkgRoot, bundleContent }) {
             continue;
           }
         }
+        // Foundation 0.14 keeps this example behind a capability-selection
+        // branch that esbuild removes from the release-skill bundle. The
+        // source scanner still sees the directory URL in the marked module,
+        // so admit this one exact directory only when its path survives in
+        // the built bundle.
+        if (
+          pkg === 'skill-family-engineering-kit'
+          && toPosix(relative(packages[pkg].root, sourceDir)) === 'data/examples/minimal-plugin-payload'
+          && !bundleContent.includes('data/examples/minimal-plugin-payload')
+        ) {
+          scopeOf(targetPosix);
+          continue;
+        }
         const files = await walkTree(sourceDir, `${pkg} directory read "${rel}"`);
         const members = [];
         for (const file of files) {

package/src/schemas/migration-manifest.schema.json

@@ -13,6 +13,138 @@
     "kind": {
       "const": "skill-family.migration-manifest"
     },
+    "capabilityUseContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "locale"],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["contracts", "harness", "engineering-kit", "profile", "all"]
+        },
+        "locale": {
+          "type": "string",
+          "enum": ["en", "zh-CN"]
+        }
+      }
+    },
+    "capabilityUses": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 200,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["useId", "problemStatement", "constraints", "retainedGuarantees"],
+        "properties": {
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "problemStatement": {
+            "allOf": [
+              { "$ref": "#/$defs/trimmedCapabilityUseText" },
+              { "type": "string", "maxLength": 1000 }
+            ]
+          },
+          "constraints": {
+            "type": "array",
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 500 }
+              ]
+            }
+          },
+          "retainedGuarantees": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 500 }
+              ]
+            }
+          },
+            "catalogFilters": {
+            "type": "array",
+            "maxItems": 20,
+            "uniqueItems": true,
+            "items": {
+              "allOf": [
+                { "$ref": "#/$defs/trimmedCapabilityUseText" },
+                { "type": "string", "maxLength": 200 }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "capabilityDecisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["useId", "disposition", "reason"],
+        "properties": {
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "disposition": {
+            "type": "string",
+            "enum": ["direct-adoption", "compatibility-layer", "keep-business", "foundation-gap"]
+          },
+          "targetCapability": {
+            "type": "string",
+            "pattern": "^foundation\\.[a-z0-9\\-]+(\\.[a-z0-9\\-]+)+$"
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["disposition"],
+              "properties": {
+                "disposition": {
+                  "enum": ["direct-adoption", "compatibility-layer"]
+                }
+              }
+            },
+            "then": {
+              "required": ["targetCapability"],
+              "properties": { "targetCapability": { "type": "string" } }
+            }
+          },
+          {
+            "if": {
+              "required": ["disposition"],
+              "properties": {
+                "disposition": {
+                  "enum": ["keep-business", "foundation-gap"]
+                }
+              }
+            },
+            "then": {
+              "not": {
+                "required": ["targetCapability"],
+                "properties": { "targetCapability": { "type": "string" } }
+              }
+            }
+          }
+        ]
+      }
+    },
     "manifestVersion": {
       "type": "integer",
       "minimum": 1,
@@ -31,11 +163,34 @@
             "description": "Relative POSIX path of one legacy implementation. Shape only: absolute paths, traversal, UNC/drive forms and symlink escapes are rejected by harness containment at assessment time, fail-closed."
           },
           "replacedBy": {
-            "type": "string",
-            "minLength": 1,
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ],
             "description": "The replacement facility (tool/command/module) that supersedes this legacy entry. An empty replacement is never a valid exit claim."
+          },
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "recoveryRef": {
+            "type": "string",
+            "minLength": 1
           }
-        }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["replacedBy"],
+              "properties": { "replacedBy": { "type": "null" } }
+            },
+            "then": {
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        ]
       }
     },
     "legacyReferences": {
@@ -57,11 +212,30 @@
             "description": "Exact literal text that must be absent from the file. No regex; byte-exact UTF-8 match."
           },
           "replacedBy": {
-            "type": "string",
-            "minLength": 1,
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ],
             "description": "The replacement facility that supersedes this old reference. Empty is never valid."
+          },
+          "useId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "maxLength": 80
           }
-        }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["replacedBy"],
+              "properties": { "replacedBy": { "type": "null" } }
+            },
+            "then": {
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        ]
       }
     },
     "exceptions": {
@@ -144,5 +318,95 @@
         }
       }
     }
-  }
+  },
+  "$defs": {
+    "trimmedCapabilityUseText": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)(?![\\s\\S]*\\u0000)[\\s\\S]+$"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["capabilityUses"],
+        "properties": { "capabilityUses": { "type": "array" } }
+      },
+      "then": {
+        "required": ["capabilityUseContext"],
+        "properties": { "capabilityUseContext": { "type": "object" } }
+      },
+      "else": {
+        "not": {
+          "anyOf": [
+            {
+              "required": ["capabilityUseContext"],
+              "properties": { "capabilityUseContext": { "type": "object" } }
+            },
+            {
+              "required": ["capabilityDecisions"],
+              "properties": { "capabilityDecisions": { "type": "array" } }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["capabilityDecisions"],
+        "properties": { "capabilityDecisions": { "type": "array" } }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["legacyInfra"],
+        "properties": {
+          "legacyInfra": {
+            "type": "array",
+            "contains": {
+              "type": "object",
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["legacyReferences"],
+        "properties": {
+          "legacyReferences": {
+            "type": "array",
+            "contains": {
+              "type": "object",
+              "required": ["useId"],
+              "properties": { "useId": { "type": "string" } }
+            }
+          }
+        }
+      },
+      "then": {
+        "required": ["capabilityUses", "capabilityUseContext"],
+        "properties": {
+          "capabilityUses": { "type": "array" },
+          "capabilityUseContext": { "type": "object" }
+        }
+      }
+    }
+  ]
 }

package/src/schemas/profile-adoption-declaration.schema.json

@@ -54,6 +54,14 @@
             "stability": { "enum": ["stable", "candidate-only"] }
           }
         },
+        "capabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^foundation\\.[a-z0-9\\-]+(?:\\.[a-z0-9\\-]+)+$"
+          }
+        },
         "foundation_pin": {
           "type": "object",
           "additionalProperties": false,