release-skill 0.9.10 → 0.9.12

package/bin/rules.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.contracts.rules",
-  "contractsVersion": "1.15.0",
+  "contractsVersion": "1.16.0",
   "budget": {
     "firstVersionMax": 20,
     "absoluteMax": 30,

package/data/hosts/codebuddy/host-descriptor.json

@@ -5,6 +5,11 @@
   "displayName": "CodeBuddy",
   "support": "manual",
   "maturity": "manual",
+  "verification": {
+    "driverId": "codebuddy-print-v1",
+    "authStrategy": "existing-user-state",
+    "credentialMutation": "host-managed"
+  },
   "sourceAliases": [],
   "pathCategories": [],
   "probeCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -78,9 +78,9 @@
     "ajv-formats": "3.0.1",
     "libnpmpublish": "11.2.0",
     "npm-registry-fetch": "18.0.2",
-    "skill-family-contracts": "0.16.0",
-    "skill-family-engineering-kit": "0.16.0",
-    "skill-family-harness-node": "0.16.0",
+    "skill-family-contracts": "0.17.0",
+    "skill-family-engineering-kit": "0.17.0",
+    "skill-family-harness-node": "0.17.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/platform-manifest.json

@@ -2,11 +2,11 @@
   "schemaVersion": "1.0.0",
   "platformId": "release-skill",
   "platformName": "release-skill Plugin Platform",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "logicalRoot": "skills-src/",
   "logicalRootDigest": "aec96745b30289ed48d576fbfc98ecd3aacb834f83394be76d4734d7d0fc0ad4",
   "projectionDigest": "e5117d89c9f965e15a1464cc84f542cb1e75a685f842183d0cfc7a105ace5ceb",
-  "projectionId": "release-skill:platform:0.9.10",
+  "projectionId": "release-skill:platform:0.9.12",
   "manifestRequired": true,
   "projectionSources": {
     "skills-src-root": {

package/references/02-project-config.md

@@ -42,7 +42,7 @@ releaseUnits:               # 发布单元数组，至少 1 个
     version:
       source: <string>      # 版本来源，如 "package.json"
       tagTemplate: <string> # tag 模板，如 "artifact-graph-v{version}"
-    distributions:          # 分发渠道数组
+    distributions:          # 必填；分发渠道数组，也可显式设为 []
       - type: <string>      # "npm" | "claude-plugin" | "codex-plugin"
         package: <string>   # npm 包名（type 为 npm 时必填）
         # 插件渠道（claude-plugin/codex-plugin/kimi-plugin/codebuddy-plugin）
@@ -112,6 +112,12 @@ policy:                     # 可选，安全策略
   forbiddenContentPatterns: [<string>]
 ```
 
+`distributions: []` 表示该发布单元不生成 npm 或插件市场动作，不表示跳过公开发布。
+生产模式的 `prepare` 仍会冻结 GitHub 快照，并生成 `push-snapshot`、`create-tag` 和
+`github-release`。该单元的 `postPublish` 声明保持独立生效，其中 phase 为
+`postVerify` 的 hook 也不受影响。因此纯插件可以先验证公开 GitHub Release，再向中央
+Hub 投递登记提案。
+
 `publicSourceAuthorityReceipt` 只适用于 production prepare。`coordinatorUnitId`
 指定承载该文件的 GitHub Release；`subjectUnitIds` 必须引用现有 release unit，且每个
 unit 恰好声明一个 npm distribution。prepare 等所有 subject tarball 冻结后生成

package/schemas/release-project.schema.json

@@ -155,7 +155,7 @@
           },
           "distributions": {
             "type": "array",
-            "minItems": 1,
+            "description": "Distribution-specific publish and consumer checks. An explicit empty array publishes only the release unit's GitHub snapshot, tag, and GitHub Release; postPublish declarations, including postVerify-phase hooks, remain independent.",
             "items": {
               "type": "object",
               "required": [

package/src/commands/verify.mjs

@@ -64,6 +64,7 @@ import {
   isWorktreeFileClean,
   commitBaselineAdvance,
 } from '../core/baseline-advance.mjs';
+import { updatePreviousPublicBaselines } from '../core/release-metadata.mjs';
 import { loadProjectConfig } from '../core/config.mjs';
 import { assertTransition, PUBLISHED, VERIFIED } from '../core/state-machine.mjs';
 import { clearFrozenMarker } from '../core/frozen-marker.mjs';
@@ -2330,17 +2331,41 @@ export async function verifyRelease(options) {
     // =======================================================================
     let baselineAdvance = null;
     const baselineAdvances = deriveBaselineAdvances(plan);
-    if (baselineAdvances.length > 0) {
+    const hasFirstReleaseBaseline = (plan.units ?? [])
+      .some((unit) => unit?.previousPublicBaseline?.mode === 'none');
+    if (hasFirstReleaseBaseline || baselineAdvances.length > 0) {
       try {
         const configAbs = configPathOpt
           ? (isAbsolute(configPathOpt) ? configPathOpt : join(root, configPathOpt))
           : join(root, '.release-skill/project.yaml');
         const cleanBefore = await isWorktreeFileClean({ root, filePath: configAbs, execFn });
-        const applyResult = await applyBaselineAdvances({
-          configPath: configAbs,
-          advances: baselineAdvances,
-          validateFn: async () => { await loadProjectConfig({ root, configPath: configAbs }); },
-        });
+        // A first-release plan must convert mode=none to a fully bound
+        // baseline. The metadata updater processes the whole plan, so mixed
+        // none+bound plans take this branch exclusively and do not omit or
+        // double-write their already-bound units. Pure bound plans retain
+        // the existing derive/apply path unchanged.
+        let applyResult;
+        if (hasFirstReleaseBaseline) {
+          await loadProjectConfig({ root, configPath: configAbs });
+          const metadataResult = await updatePreviousPublicBaselines({
+            root,
+            planPath,
+            configPath: configAbs,
+            validateFn: async () => { await loadProjectConfig({ root, configPath: configAbs }); },
+          });
+          applyResult = {
+            changed: metadataResult.status === 'UPDATED',
+            updatedUnits: metadataResult.status === 'UPDATED'
+              ? metadataResult.units.map((unit) => unit.id)
+              : [],
+          };
+        } else {
+          applyResult = await applyBaselineAdvances({
+            configPath: configAbs,
+            advances: baselineAdvances,
+            validateFn: async () => { await loadProjectConfig({ root, configPath: configAbs }); },
+          });
+        }
         baselineAdvance = { ...applyResult, committed: false };
         if (applyResult.changed && cleanBefore) {
           const versionLabel = (plan.units ?? [])
@@ -2362,12 +2387,25 @@ export async function verifyRelease(options) {
           committed: baselineAdvance.committed,
         });
       } catch (err) {
-        baselineAdvance = { failed: true, error: err.message };
+        const errorDetails = err instanceof ReleaseError
+          ? err.toJSON().details
+          : undefined;
+        baselineAdvance = {
+          failed: true,
+          error: err.message,
+          ...(errorDetails ? { details: errorDetails } : {}),
+        };
         await evidence.append({
           phase: 'verify',
-          step: 'baseline-advance',
           status: 'failed',
-          error: { code: err.code, message: err.message },
+          error: {
+            code: err.code,
+            message: err.message,
+          },
+          details: {
+            step: 'baseline-advance',
+            ...(errorDetails ? { errorDetails } : {}),
+          },
         });
       }
     }

package/src/core/proposal-document.mjs

@@ -0,0 +1,52 @@
+/**
+ * Pure proposal-document projection shared by runtime transports and frozen
+ * postVerify execution hooks. Keep this module free of package dependencies
+ * so a detached public-tag worktree can load it without node_modules.
+ *
+ * @module core/proposal-document
+ */
+
+import { ReleaseError, GATE_FAILED } from './errors.mjs';
+
+/** Proposal document identity. */
+export const PROPOSAL_SCHEMA_VERSION = 1;
+export const PROPOSAL_KIND = 'release-skill/update-proposal';
+
+/** Proposal file location inside the downstream repository. */
+export function proposalFileName(unitId, version) {
+  if (typeof unitId !== 'string' || unitId.length === 0
+    || typeof version !== 'string' || version.length === 0) {
+    throw new ReleaseError(GATE_FAILED, 'proposal file name requires unitId and version', { unitId, version });
+  }
+  return `incoming/${unitId}-${version}.json`;
+}
+
+/**
+ * Build the deterministic downstream proposal from a post-publish context.
+ * Local materialization paths are intentionally excluded.
+ */
+export function buildProposalDocument(context) {
+  const required = ['unitId', 'version', 'tag', 'commit', 'planDigest', 'runId'];
+  for (const field of required) {
+    if (typeof context?.[field] !== 'string' || context[field].length === 0) {
+      throw new ReleaseError(GATE_FAILED, `proposal document requires context field "${field}"`, { field });
+    }
+  }
+  const { unitId, version, tag, commit, tree, manifestDigest, planDigest, runId, publishedAt, verifyEvidence } = context;
+  return {
+    schemaVersion: PROPOSAL_SCHEMA_VERSION,
+    kind: PROPOSAL_KIND,
+    unitId,
+    version,
+    tag,
+    sha: commit,
+    commit,
+    ...(typeof tree === 'string' && tree.length > 0 ? { tree } : {}),
+    ...(typeof manifestDigest === 'string' && manifestDigest.length > 0 ? { manifestDigest } : {}),
+    planDigest,
+    runId,
+    ...(publishedAt !== undefined ? { publishedAt } : {}),
+    ...(verifyEvidence !== undefined ? { verifyEvidence } : {}),
+    changeSummary: `release ${unitId} ${version} (tag ${tag}, commit ${commit})`,
+  };
+}

package/src/core/proposal-inbox.mjs

@@ -53,12 +53,16 @@ import {
   describeGitRemoteUrlFailure,
   redactUrlCredentialsIfPresent,
 } from './git-url-policy.mjs';
+import { buildProposalDocument, proposalFileName } from './proposal-document.mjs';
 
-const execFileAsync = promisify(execFileCb);
+export {
+  PROPOSAL_SCHEMA_VERSION,
+  PROPOSAL_KIND,
+  buildProposalDocument,
+  proposalFileName,
+} from './proposal-document.mjs';
 
-/** Proposal document identity. */
-export const PROPOSAL_SCHEMA_VERSION = 1;
-export const PROPOSAL_KIND = 'release-skill/update-proposal';
+const execFileAsync = promisify(execFileCb);
 
 const PROBE_TIMEOUT_MS = 30_000;
 const GIT_TIMEOUT_MS = 120_000;
@@ -187,54 +191,6 @@ function parseLsRemote(stdout) {
 // Proposal document (deterministic projection of the §2.3 context)
 // ---------------------------------------------------------------------------
 
-/** Proposal file location inside the downstream repository. */
-export function proposalFileName(unitId, version) {
-  if (typeof unitId !== 'string' || unitId.length === 0
-    || typeof version !== 'string' || version.length === 0) {
-    throw new ReleaseError(GATE_FAILED, 'proposal file name requires unitId and version', { unitId, version });
-  }
-  return `incoming/${unitId}-${version}.json`;
-}
-
-/**
- * Build the proposal document from the §2.3 context projection. Pure and
- * deterministic. Deliberately EXCLUDES payloadDir (a local materialization
- * path has no place in a downstream-facing document), and optional frozen
- * fields are ABSENT rather than null when the plan did not freeze them.
- *
- * Field set suffices to backfill a missing downstream hub entry:
- * unitId/version/tag/sha/commit/tree/manifestDigest/planDigest/runId/
- * publishedAt/verifyEvidence/changeSummary.
- *
- * @param {object} context - The §2.3 context projection.
- * @returns {object} The proposal document.
- */
-export function buildProposalDocument(context) {
-  const required = ['unitId', 'version', 'tag', 'commit', 'planDigest', 'runId'];
-  for (const field of required) {
-    if (typeof context?.[field] !== 'string' || context[field].length === 0) {
-      throw new ReleaseError(GATE_FAILED, `proposal document requires context field "${field}"`, { field });
-    }
-  }
-  const { unitId, version, tag, commit, tree, manifestDigest, planDigest, runId, publishedAt, verifyEvidence } = context;
-  return {
-    schemaVersion: PROPOSAL_SCHEMA_VERSION,
-    kind: PROPOSAL_KIND,
-    unitId,
-    version,
-    tag,
-    sha: commit,
-    commit,
-    ...(typeof tree === 'string' && tree.length > 0 ? { tree } : {}),
-    ...(typeof manifestDigest === 'string' && manifestDigest.length > 0 ? { manifestDigest } : {}),
-    planDigest,
-    runId,
-    ...(publishedAt !== undefined ? { publishedAt } : {}),
-    ...(verifyEvidence !== undefined ? { verifyEvidence } : {}),
-    changeSummary: `release ${unitId} ${version} (tag ${tag}, commit ${commit})`,
-  };
-}
-
 /**
  * Deterministic manual-sync prompt (closure semantics): delivery success plus
  * this prompt in evidence IS the closed loop — downstream consumption is the

package/src/core/release-metadata.mjs

@@ -1,5 +1,5 @@
 import { lstat, readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import YAML from 'yaml';
 import { replaceFileAtomic } from 'skill-family-harness-node';
 
@@ -20,7 +20,20 @@ function assertOid(value, label) {
 export async function updatePreviousPublicBaselines(options = {}) {
   const root = resolve(options.root ?? process.cwd());
   const planPath = resolve(options.planPath ?? '');
-  const configPath = resolve(root, '.release-skill', 'project.yaml');
+  const configPath = isAbsolute(options.configPath ?? '')
+    ? resolve(options.configPath)
+    : resolve(root, options.configPath ?? '.release-skill/project.yaml');
+  const configRelativePath = relative(root, configPath);
+  if (
+    configRelativePath === '..'
+    || configRelativePath.startsWith(`..${sep}`)
+    || isAbsolute(configRelativePath)
+  ) {
+    throw new ReleaseError(CONFIG_INVALID, 'project config must stay within the project root', {
+      root,
+      configPath,
+    });
+  }
   let plan;
   let configRaw;
   let configStat;
@@ -69,6 +82,7 @@ export async function updatePreviousPublicBaselines(options = {}) {
     const old = configUnit.get('previousPublicBaseline', true)?.toJSON?.() ?? {};
     const next = {
       mode: 'bound',
+      ...(typeof old.githubHost === 'string' ? { githubHost: old.githubHost } : {}),
       repo: old.repo ?? unit.publicRepo,
       ref: old.ref ?? `refs/heads/${frozen.branch}`,
       commit: frozen.commit,
@@ -78,6 +92,15 @@ export async function updatePreviousPublicBaselines(options = {}) {
     if (!next.repo || !next.ref) {
       throw new ReleaseError(GATE_FAILED, `unit "${unit.id}" cannot derive its next public baseline identity`);
     }
+    const changed = [
+      'mode',
+      'repo',
+      'ref',
+      'commit',
+      'tree',
+      'manifestDigest',
+    ].some((field) => old[field] !== next[field]);
+    if (!changed) continue;
     configUnit.set('previousPublicBaseline', next);
     updates.push({
       id: unit.id,
@@ -86,16 +109,41 @@ export async function updatePreviousPublicBaselines(options = {}) {
     });
   }
 
+  if (updates.length === 0) {
+    return { status: 'UNCHANGED', configPath, units: [] };
+  }
   const nextRaw = doc.toString();
   if (nextRaw === configRaw) {
     return { status: 'UNCHANGED', configPath, units: updates };
   }
   try {
-    await replaceFileAtomic(root, '.release-skill/project.yaml', nextRaw, {
+    await replaceFileAtomic(root, configRelativePath, nextRaw, {
       mode: configStat.mode & 0o777,
     });
   } catch (error) {
     throw new ReleaseError(CONFIG_INVALID, `cannot update project release metadata: ${error.message}`, error.details);
   }
+  if (typeof options.validateFn === 'function') {
+    try {
+      await options.validateFn(configPath);
+    } catch (error) {
+      try {
+        await replaceFileAtomic(root, configRelativePath, configRaw, {
+          mode: configStat.mode & 0o777,
+        });
+      } catch (restoreError) {
+        throw new ReleaseError(
+          CONFIG_INVALID,
+          `cannot restore project release metadata after validation failed: ${restoreError.message}`,
+          { validationError: error.message, restoreError: restoreError.details },
+        );
+      }
+      throw new ReleaseError(
+        GATE_FAILED,
+        `baseline advance reverted: rewritten config failed validation: ${error.message}`,
+        { configPath, cause: error.message },
+      );
+    }
+  }
   return { status: 'UPDATED', configPath, units: updates };
 }

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.16.0',
-  'skill-family-engineering-kit': '0.16.0',
-  'skill-family-harness-node': '0.16.0',
+  'skill-family-contracts': '0.17.0',
+  'skill-family-engineering-kit': '0.17.0',
+  'skill-family-harness-node': '0.17.0',
 });
 
 export const BINDING_RECORD_PATH = 'bin/foundation-resource-binding.json';

package/src/schemas/engineering-baseline.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.skill-family.example/v1/engineering-baseline.json",
+  "title": "EngineeringBaseline",
+  "description": "Business-neutral identity for an engineering baseline. The contract carries the provider-owned baseline identity, canonical rule lineage references, and the Foundation reference implementation identity; it does not carry rule bodies, effects, equivalence, or exemption semantics.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "provider",
+    "id",
+    "version",
+    "digest",
+    "canonicalRuleRefs",
+    "referenceImplementation"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "skill-family.engineering-baseline" },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider that owns the baseline identity, for example an independent Audit implementation."
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable baseline identifier."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semantic version of the provider-owned baseline identity."
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "SHA-256 digest of the canonical JSON of this document with digest omitted."
+    },
+    "canonicalRuleRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/canonicalRuleRef" },
+      "description": "Sorted, unique references to provider-owned canonical rule lineages. Rule bodies and decisions remain outside this contract."
+    },
+    "referenceImplementation": {
+      "$ref": "#/$defs/referenceImplementation",
+      "description": "Identity of the Foundation reference implementation used by the baseline provider."
+    }
+  },
+  "$defs": {
+    "canonicalRuleRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "revision", "revisionDigest"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "revision": { "type": "integer", "minimum": 1 },
+        "revisionDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "referenceImplementation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["foundationVersion", "profile", "skeletonDigest"],
+      "properties": {
+        "foundationVersion": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+        },
+        "profile": { "type": "string", "minLength": 1 },
+        "skeletonDigest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    }
+  }
+}

package/src/schemas/host-descriptor.schema.json

@@ -25,7 +25,7 @@
       "additionalProperties": false,
       "required": ["driverId", "authStrategy", "credentialMutation"],
       "properties": {
-        "driverId": { "enum": ["kimi-code-print-v1", "workbuddy-codebuddy-print-v1", "claude-code-print-v1", "codex-exec-v1", "qodercli-print-v1"] },
+        "driverId": { "enum": ["kimi-code-print-v1", "workbuddy-codebuddy-print-v1", "codebuddy-print-v1", "claude-code-print-v1", "codex-exec-v1", "qodercli-print-v1"] },
         "authStrategy": { "const": "existing-user-state" },
         "credentialMutation": { "const": "host-managed" }
       }
@@ -80,6 +80,13 @@
         "properties": { "verification": { "type": "object", "properties": { "driverId": { "const": "workbuddy-codebuddy-print-v1" } } } }
       }
     },
+    {
+      "if": { "properties": { "hostId": { "const": "codebuddy" } }, "required": ["hostId"] },
+      "then": {
+        "required": ["verification"],
+        "properties": { "verification": { "type": "object", "properties": { "driverId": { "const": "codebuddy-print-v1" } } } }
+      }
+    },
     {
       "if": { "properties": { "hostId": { "const": "claude" } }, "required": ["hostId"] },
       "then": {
@@ -102,7 +109,7 @@
       }
     },
     {
-      "if": { "properties": { "hostId": { "enum": ["kimi-code", "workbuddy", "claude", "codex", "qoder"] } }, "required": ["hostId"] },
+      "if": { "properties": { "hostId": { "enum": ["kimi-code", "workbuddy", "codebuddy", "claude", "codex", "qoder"] } }, "required": ["hostId"] },
       "else": { "properties": { "verification": false } }
     },
     {