release-skill 0.6.2 → 0.6.3

package/adapters/workbuddy/schemas/.render-manifest.json

@@ -21,17 +21,21 @@
       "digest": "b7e14522a5aba818cab191545f23d2323be0e4c80566e9d3e4da576103a00490",
       "bytes": 2390
     },
+    "postpublish-approval-record.schema.json": {
+      "digest": "e365c9e9f5aa189ca6788e68dbedfa718aa120f2c197534417c21e019b9a29a4",
+      "bytes": 1744
+    },
     "release-plan.schema.json": {
-      "digest": "5e988a5301b89b3d3260154ffae12669af0e4d6ec7f9db8c44df21037ea0eaf6",
-      "bytes": 46948
+      "digest": "517ac9b1d92d2bf348497ee0e79c9e474a4c60e6ed8ba77830948716d143dfa2",
+      "bytes": 49369
     },
     "release-project.schema.json": {
-      "digest": "546e05845cd83a3b1db0a54036f9555081420337e9df961d783d2d2630800ef7",
-      "bytes": 41898
+      "digest": "d38649d1dc9b1dbc643f4e2c98fd18d111090e9ce221c9c61fa50245f6c4c232",
+      "bytes": 45715
     },
     "release-run.schema.json": {
-      "digest": "6dd239c59f7045df11d13d6ba2027610d3c55c27a6af5bc87676b0eaad9600fd",
-      "bytes": 17663
+      "digest": "a605db801d6994d657049431ad453233974bd10610b7b447b196136bb0692866",
+      "bytes": 17847
     }
   }
 }

package/adapters/workbuddy/schemas/postpublish-approval-record.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://release-skill.dev/schemas/postpublish-approval-record/v1",
+  "title": "PostPublish Hook Approval Record",
+  "description": "Schema for checkpoint-level approval of a requiresApproval postPublish hook (v0.6.3 R1, design §2.7 ruling 2). Binds the approval to (planDigest, hookId); the plan-level approval-record schema is untouched. runId is audit-only and never participates in binding or validation semantics.",
+  "type": "object",
+  "required": [
+    "planDigest",
+    "hookId",
+    "actor",
+    "approvedAt",
+    "expiresAt"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "planDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the frozen release plan whose postPublish hooks block this approval binds to"
+    },
+    "hookId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "id of the requiresApproval postPublish hook being approved (must be declared in the frozen plan)"
+    },
+    "actor": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identity of the approver"
+    },
+    "approvedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when approval was granted"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when approval expires (max 24h after approvedAt; 5-minute clock skew tolerated at validation)"
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Audit-only identifier of the distribute run present when approval was granted; never a binding"
+    }
+  }
+}

package/adapters/workbuddy/schemas/release-plan.schema.json

@@ -1307,7 +1307,6 @@
       "description": "冻结的发布后分发块：声明本身 + tag/tagCommit/unitId/payloadSource 绑定。整体参与 plan digest（planVersion 2 记录层剥离不包含该块），任何配置变更都会改变 planDigest。tagCommit 仅在 prepare 能冻结 create-tag 预期 commit 时存在（production 资产）；缺省时 distribute fail-closed。",
       "required": [
         "materialize",
-        "targets",
         "commitIdentity",
         "tag",
         "unitId",
@@ -1325,6 +1324,13 @@
             "$ref": "#/definitions/planPostPublishTarget"
           }
         },
+        "hooks": {
+          "type": "array",
+          "description": "冻结的发布后钩子声明（v0.6.3 R1）；随整块参与 plan digest",
+          "items": {
+            "$ref": "#/definitions/planPostPublishHook"
+          }
+        },
         "commitIdentity": {
           "type": "object",
           "required": [
@@ -1373,6 +1379,64 @@
         }
       }
     },
+    "planPostPublishHook": {
+      "type": "object",
+      "description": "冻结的发布后钩子声明项（v0.6.3 R1）：preset 与 command 运行时互斥；phase 缺省 distribute；blocksVerified 缺省 true 且仅 preset 可声明 false",
+      "required": [
+        "id"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "preset": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "distribute",
+            "postVerify"
+          ]
+        },
+        "config": {
+          "type": "object"
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true
+        },
+        "requiresApproval": {
+          "type": "boolean"
+        },
+        "blocksVerified": {
+          "type": "boolean"
+        }
+      }
+    },
     "planPostPublishMaterialize": {
       "type": "object",
       "required": [

package/adapters/workbuddy/schemas/release-project.schema.json

@@ -889,7 +889,6 @@
       "description": "发布后分发声明：materialize 钩子从冻结 tag 工作树物化载荷，targets 将载荷镜像或渲染市场索引推送到独立 git 远端。分发在 publish 之后由 distribute 命令执行，时序契约禁止读取工作区状态。",
       "required": [
         "materialize",
-        "targets",
         "commitIdentity"
       ],
       "additionalProperties": false,
@@ -904,6 +903,13 @@
             "$ref": "#/definitions/postPublishTarget"
           }
         },
+        "hooks": {
+          "type": "array",
+          "description": "发布后钩子声明（v0.6.3 R1）：每项为命名 preset（+config）或自定义 command 钩子（executable+参数数组，禁止 shell 字符串）。schema 层只校验形状；preset 与 command 互斥、preset 注册表归属等语义在运行时 fail-closed 校验（POSTPUBLISH_HOOK_INVALID）",
+          "items": {
+            "$ref": "#/definitions/postPublishHook"
+          }
+        },
         "commitIdentity": {
           "type": "object",
           "description": "分发仓库提交者身份（bot 身份），通过 git -c user.name/-c user.email 注入，绝不读取或修改全局 git 配置",
@@ -936,6 +942,72 @@
         }
       }
     },
+    "postPublishHook": {
+      "type": "object",
+      "description": "发布后钩子声明项：preset（命名预设 + config）与 command（自定义命令）在运行时互斥校验；phase 缺省为 distribute（VERIFIED 之前执行），postVerify 在 verify 通过后作为独立 run 执行（R3）；blocksVerified 缺省 true，仅 preset 可声明 false",
+      "required": [
+        "id"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "preset": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "description": "预设注册表中的预设名（R2 起）；R1 无注册表，任何 preset 引用在运行时 fail-closed"
+        },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "executable+参数数组（禁止 shell 字符串）；在冻结 tag 工作树中执行"
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "distribute",
+            "postVerify"
+          ],
+          "description": "执行阶段；缺省 distribute"
+        },
+        "config": {
+          "type": "object",
+          "description": "preset 钩子的配置对象；语义由预设注册表校验（R2 起）"
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$",
+          "description": "command 钩子执行目录（相对冻结 tag 工作树）；preset 钩子禁止声明（运行时 fail-closed）"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true,
+          "description": "允许透传给钩子进程的环境变量白名单；TOKEN/SECRET 等敏感子串在 schema 层即被拒绝"
+        },
+        "requiresApproval": {
+          "type": "boolean",
+          "description": "执行前需要 checkpoint 级批准（绑定 planDigest + hookId）；public-write preset 缺省 true"
+        },
+        "blocksVerified": {
+          "type": "boolean",
+          "description": "失败时是否阻断 VERIFIED；缺省 true；仅 preset 可声明 false（运行时 fail-closed 校验）"
+        }
+      }
+    },
     "postPublishMaterialize": {
       "type": "object",
       "description": "载荷物化钩子：executable+参数数组（禁止 shell 字符串），stdout 中 outputMarker 行之后为载荷目录路径；可选 requireReport 对 stdout 首个 JSON 对象做字段断言",

package/adapters/workbuddy/schemas/release-run.schema.json

@@ -43,7 +43,8 @@
         "PARTIAL",
         "BLOCKED",
         "DISTRIBUTING",
-        "DISTRIBUTED"
+        "DISTRIBUTED",
+        "NEEDS_INPUT"
       ],
       "description": "Current status of the run"
     },
@@ -55,7 +56,8 @@
         "publish",
         "reconcile",
         "verify",
-        "distribute"
+        "distribute",
+        "postverify"
       ],
       "description": "The command that initiated this run"
     },
@@ -133,7 +135,8 @@
               "codebuddy-marketplace-install",
               "set-default-branch",
               "distribute-probe",
-              "distribute-mirror"
+              "distribute-mirror",
+              "postpublish-hook"
             ],
             "description": "Type of external action"
           },
@@ -149,9 +152,10 @@
               "PASSED_AUTOMATIC",
               "PASSED_MANUAL",
               "NOT_REQUIRED_UNCHANGED",
-              "NO_CHANGE"
+              "NO_CHANGE",
+              "AWAITING_APPROVAL"
             ],
-            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push)"
+            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push; AWAITING_APPROVAL = requiresApproval postPublish hook 尚无 checkpoint 批准，v0.6.3 R1)"
           },
           "preObserve": {
             "type": "string",
@@ -621,7 +625,8 @@
             "enum": [
               "reconcile",
               "verify",
-              "distribute"
+              "distribute",
+              "postverify"
             ]
           }
         },

package/bin/release-skill-cli.mjs

@@ -237,7 +237,8 @@ Commands:
   publish    Publish frozen GitHub/npm artifacts after approval
   reconcile  Resume PARTIAL state from evidence; conflicts require a human
   verify     Fresh remote and consumer verification; only this reaches VERIFIED
-  ship       Resume one durable prepare -> approve -> publish -> verify flow
+  ship       Resume one durable prepare -> approve -> publish -> verify flow; completes a parked
+             postVerify hook once its checkpoint approval is provided (--hook-approval)
   attest     Legacy only: record a Kimi/CodeBuddy result for an old frozen plan
   hooks      Run declared development hooks and populate reusable receipts
   artifacts  Artifact status, inspect, update/apply, resolution, and diagnostics
@@ -249,7 +250,8 @@ Commands:
 Options:
   --root <path>    Project root directory (default: cwd)
   --plan <path>    Path to the release plan file
-  --run <path>     Path to the release run file (required for reconcile/verify)
+  --run <path>     Path to the release run file, or a run directory whose release-run.json
+                   is resolved automatically (required for reconcile/verify)
   --approval <path> Path to the approval record
   --production     Prepare immutable Git/npm production artifacts
   --output <path>  Override prepare/approve output path (non-production only)
@@ -264,6 +266,12 @@ Options:
   --answers <path> Human-reviewed setup answers JSON
   --write          Create an absent project.yaml during setup; never overwrites
   --confirm-setup <digest> Confirm exact setup facts and answers before create
+  --discover-downstream Read-only discovery of downstream candidates (git remotes, marketplace/docs
+                   clues, artifact-graph.config.yaml, foundation profile). Never writes
+  --propose-hooks  Produce postPublish hook declaration drafts; with --write and exact --confirm-setup,
+                   performs an append-only hooks edit of an existing config (create-once is untouched)
+  --select-hooks <ids> Comma-separated proposal ids to adopt (propose-hooks mode)
+  --foundation-profile <path> Explicit foundation postPublish profile JSON (proposal input only; never auto-applied)
   --unit <id>      Release unit whose declared release documents are refreshed (docs refresh)
   --confirm-refresh <sha256:...> Confirm the exact dry-run refreshDigest before any document write
   --ack-local-document-write Acknowledge the explicit local release-document write (docs refresh --write)
@@ -274,6 +282,7 @@ Options:
   --install-path <path> Actual managed plugin path when closure verification requires it
   --install-channel <desktop|cli> CodeBuddy installation channel when required
   --approve         Approve the ship plan (boolean; plan digest is auto-resolved)
+  --hook-approval <path> Checkpoint approval for a requiresApproval postPublish hook (ship/distribute; repeatable)
   --state <path>    Override the durable ship state file
   --no-hook-cache  Force every prepare hook to run in full; neither read nor write the hook cache
   --json           Output results as JSON
@@ -467,6 +476,59 @@ if (command === 'setup') {
     ? args[confirmationIdx + 1]
     : undefined;
   const write = args.includes('--write');
+
+  // R5 — downstream discovery + postPublish hook proposal (guided config) and
+  // the independent incremental-proposal mode for existing projects. These
+  // modes are read-only until --write + exact --confirm-setup, and the write is
+  // an append-only hooks edit; they never touch the create-once setup path.
+  const discoverDownstreamMode = args.includes('--discover-downstream');
+  const proposeHooksMode = args.includes('--propose-hooks');
+  if (discoverDownstreamMode || proposeHooksMode) {
+    const flagValue = (flag) => {
+      const idx = args.indexOf(flag);
+      return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+    };
+    const foundationProfilePath = flagValue('--foundation-profile');
+    const unitId = flagValue('--unit');
+    const selectRaw = flagValue('--select-hooks');
+    const selectedHookIds = selectRaw
+      ? selectRaw.split(',').map((item) => item.trim()).filter(Boolean)
+      : undefined;
+    try {
+      const setupModule = await import('../src/commands/setup.mjs');
+      const report = discoverDownstreamMode
+        ? await setupModule.discoverDownstream({ root, foundationProfilePath })
+        : await setupModule.proposePostPublishHooks({
+          root, write, confirmSetup, selectedHookIds, foundationProfilePath, unitId,
+        });
+      if (hasJson) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        console.log(`Status: ${report.status ?? report.mode}`);
+        if (report.setupDigest) console.log(`Setup digest: ${report.setupDigest}`);
+        if (report.hookProposals) {
+          console.log(`Hook proposals: ${report.hookProposals.map((p) => p.id).join(', ') || '(none)'}`);
+        }
+        if (report.configPath) console.log(`Config: ${report.configPath}`);
+        if (report.next) console.log(`Next: ${report.next}`);
+      }
+      const okStatuses = ['HOOKS_PROPOSAL_READY', 'HOOKS_APPENDED', 'HOOKS_NO_CHANGE', 'postpublish-discovery'];
+      process.exit(okStatuses.includes(report.status ?? report.mode) ? 0 : 2);
+    } catch (err) {
+      if (hasJson) {
+        console.log(JSON.stringify({
+          error: err.code ?? 'UNKNOWN_ERROR',
+          message: err.message,
+          details: err.details ?? {},
+          exitCode: err.exitCode ?? 1,
+        }));
+      } else {
+        console.error(`Error: ${err.message}`);
+      }
+      process.exit(err.exitCode ?? 1);
+    }
+  }
+
   try {
     const { setupProject } = await import('../src/commands/setup.mjs');
     const report = await setupProject({ root, answersPath, write, confirmSetup });
@@ -575,6 +637,16 @@ if (command === 'ship') {
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
   };
   const root = resolve(value('--root') ?? process.cwd());
+  // Repeatable --hook-approval <path>: checkpoint approvals for
+  // requiresApproval postPublish hooks (same convention as distribute;
+  // review major-1 — without this the ship flow can never complete a
+  // parked AWAITING_APPROVAL postVerify hook).
+  const postpublishApprovalPaths = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--hook-approval' && args[i + 1]) {
+      postpublishApprovalPaths.push(resolve(args[i + 1]));
+    }
+  }
   try {
     const [
       { advanceShip },
@@ -582,6 +654,7 @@ if (command === 'ship') {
       { createNpmAdapter },
       { createPluginMarketplaceAdapter },
       { createPushSnapshotAdapter },
+      { createDistributeGitAdapter },
       { createAdapterRegistry },
     ] = await Promise.all([
       import('../src/commands/ship.mjs'),
@@ -589,13 +662,17 @@ if (command === 'ship') {
       import('../src/adapters/npm.mjs'),
       import('../src/adapters/plugin-marketplace.mjs'),
       import('../src/adapters/push-snapshot.mjs'),
+      import('../src/adapters/distribute-git.mjs'),
       import('../src/adapters/contract.mjs'),
     ]);
+    // v0.6.3 R1: ship auto-routes into the distribute saga; the registry must
+    // carry the distribute-git adapter or that production path fails closed.
     const adapterRegistry = createAdapterRegistry([
       createGitGithubAdapter(),
       createNpmAdapter(),
       createPluginMarketplaceAdapter(),
       createPushSnapshotAdapter(),
+      createDistributeGitAdapter(),
     ]);
     const result = await advanceShip({
       root,
@@ -605,15 +682,27 @@ if (command === 'ship') {
       planApprovalDigest: value('--approve-plan'),
       actor: value('--actor'),
       adapterRegistry,
+      ...(postpublishApprovalPaths.length > 0 ? { postpublishApprovalPaths } : {}),
     });
     if (hasJson) {
       console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(`Ship status: ${result.status}`);
       console.log(`State: ${result.statePath}`);
+      for (const warning of result.warnings ?? []) {
+        console.log(`Warning [${warning.code}] ${warning.message}`);
+      }
       if (result.planDigest && result.status === 'NEEDS_PLAN_APPROVAL') {
         console.log(`Approve plan: ship --approve --actor <person>`);
       }
+      if (result.postVerify) {
+        console.log(`PostVerify: ${result.postVerify.status}${result.postVerify.runPath ? ` (run: ${result.postVerify.runPath})` : ''}`);
+        if (['NEEDS_INPUT', 'PARTIAL', 'BLOCKED', 'FAILED'].includes(result.postVerify.status)) {
+          console.log('PostVerify incomplete: re-run release-skill ship to retry non-gated hooks (no approval needed for them).');
+          console.log('For requiresApproval hooks, mint a checkpoint approval (release-skill approve --plan <plan> --hook <hookId> --actor <person>)');
+          console.log('then re-run: release-skill ship --root <root> --hook-approval <approval-record>');
+        }
+      }
       for (const followUp of result.manualFollowUps ?? []) {
         console.log(`Manual follow-up [${followUp.platform}] ${followUp.plugin}: not verified by system`);
       }
@@ -757,6 +846,7 @@ if (command === 'prepare') {
           unitId: action.unitId,
         })),
         warnings: result.warnings,
+        nextSteps: result.nextSteps ?? [],
       }, null, 2));
     } else {
       for (const warning of result.warnings) {
@@ -765,6 +855,9 @@ if (command === 'prepare') {
       console.log(`Plan frozen at: ${result.planPath}`);
       console.log(`Plan digest: ${result.planDigest}`);
       console.log(`Evidence: ${result.evidenceDir}`);
+      for (const step of result.nextSteps ?? []) {
+        console.log(`Next [${step.code}] ${step.message}`);
+      }
       if (plan.workflowKind && plan.workflowKind !== 'full') {
         console.log(`Workflow: ${plan.workflowKind}`);
       }
@@ -804,6 +897,10 @@ if (command === 'approve') {
   const actor = actorIdx !== -1 && args[actorIdx + 1] ? args[actorIdx + 1] : undefined;
   const outputIdx = args.indexOf('--output');
   const outputPath = outputIdx !== -1 && args[outputIdx + 1] ? resolve(args[outputIdx + 1]) : undefined;
+  const hookIdx = args.indexOf('--hook');
+  const hookId = hookIdx !== -1 && args[hookIdx + 1] ? args[hookIdx + 1] : undefined;
+  const runIdIdx = args.indexOf('--run-id');
+  const runId = runIdIdx !== -1 && args[runIdIdx + 1] ? args[runIdIdx + 1] : undefined;
 
   if (!planPath || !actor) {
     const msg = 'approve requires --plan <path> and --actor <name>';
@@ -815,6 +912,44 @@ if (command === 'approve') {
     process.exit(1);
   }
 
+  // --- Checkpoint-level postPublish hook approval (v0.6.3 R1, review N-6) ---
+  if (hookId) {
+    try {
+      const { approvePostPublishHook } = await import('../src/commands/approve.mjs');
+      const record = await approvePostPublishHook({
+        planPath: resolve(planPath),
+        hookId,
+        actor,
+        ...(runId ? { runId } : {}),
+      });
+      if (hasJson) {
+        console.log(JSON.stringify(record, null, 2));
+      } else {
+        console.log(`Checkpoint approval for postPublish hook "${record.hookId}" by ${record.actor}`);
+        console.log(`Approval record: ${record.approvalPath}`);
+        console.log(`Approved at: ${record.approvedAt}`);
+        console.log(`Expires at: ${record.expiresAt}`);
+        console.log('Approved hook (normalized entry summary):');
+        const summary = record.hookSummary ?? {};
+        for (const [key, value] of Object.entries(summary)) {
+          console.log(`  ${key}: ${typeof value === 'object' ? JSON.stringify(value) : value}`);
+        }
+      }
+      process.exit(0);
+    } catch (err) {
+      if (hasJson) {
+        console.log(JSON.stringify({
+          error: err.code ?? 'UNKNOWN_ERROR',
+          message: err.message,
+          exitCode: err.exitCode ?? 1,
+        }));
+      } else {
+        console.error(`Error: ${err.message}`);
+      }
+      process.exit(err.exitCode ?? 1);
+    }
+  }
+
   try {
     const { approvePlan } = await import('../src/commands/approve.mjs');
     const { computePlanDigest } = await import('../src/core/plan.mjs');
@@ -1259,7 +1394,41 @@ if (command === 'distribute') {
   const approvalPath = value('--approval');
   const runPath = value('--run');
   const dryRun = args.includes('--dry-run');
+  // Repeatable --hook-approval <path>: checkpoint approvals for
+  // requiresApproval postPublish hooks (v0.6.3 R1).
+  const postpublishApprovalPaths = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--hook-approval' && args[i + 1]) {
+      postpublishApprovalPaths.push(resolve(args[i + 1]));
+    }
+  }
   
+  // R2: enumerate the postPublish preset registry (ships with the bundle).
+  // Read-only; needs no --plan/--run, so it short-circuits parameter checks.
+  if (args.includes('--list-presets')) {
+    const { listPostPublishPresets } = await import('../src/core/presets.mjs');
+    const presets = listPostPublishPresets();
+    if (hasJson) {
+      console.log(JSON.stringify({ command: 'distribute', presets }, null, 2));
+    } else {
+      console.log('postPublish presets:');
+      for (const preset of presets) {
+        const status = preset.implemented ? 'implemented' : 'reserved (behavior lands in a later release)';
+        console.log(`  ${preset.name}`);
+        console.log(`    description: ${preset.description}`);
+        console.log(`    requiresApproval default: ${preset.defaultRequiresApproval}`);
+        if (preset.requiresApprovalNote) {
+          console.log(`    requiresApproval note: ${preset.requiresApprovalNote}`);
+        }
+        if (preset.targetsFormOnly) {
+          console.log('    declaration form: targets-form only (declare under postPublish.targets, not postPublish.hooks)');
+        }
+        console.log(`    write-downstream: ${preset.writeDownstream}; target optional: ${preset.targetOptional}; status: ${status}`);
+      }
+    }
+    process.exit(0);
+  }
+
   // Handle --help explicitly
   if (args.includes('--help')) {
     const helpText = `Distribute command: Distributes frozen artifacts to post-publish targets
@@ -1271,7 +1440,9 @@ Options:
   --plan     Path to the release plan file (required)
   --run      Path to the release run file (required)
   --approval Path to the approval record (optional but recommended)
+  --hook-approval <path>  Checkpoint approval for a requiresApproval postPublish hook (repeatable)
   --dry-run  Preview distribution steps without executing (default: false)
+  --list-presets  Enumerate the postPublish preset registry (no plan/run needed)
 
 Description:
   After PUBLISHED state, distributes to configured postPublish targets:
@@ -1288,9 +1459,11 @@ Description:
           '--plan': 'Path to the release plan file (required)',
           '--run': 'Path to the release run file (required)',
           '--approval': 'Path to the approval record (optional but recommended)',
+          '--hook-approval': 'Checkpoint approval for a requiresApproval postPublish hook (repeatable)',
           '--dry-run': 'Preview distribution steps without executing (default: false)',
+          '--list-presets': 'Enumerate the postPublish preset registry (no plan/run needed)',
         },
-        description: 'After PUBLISHED state, distributes to configured postPublish targets: git mirrors + marketplace index updates. Requires plan.postPublish config. Reconciles PARTIAL runs.',
+        details: 'After PUBLISHED state, distributes to configured postPublish targets: git mirrors + marketplace index updates. Requires plan.postPublish config. Reconciles PARTIAL runs.',
       }, null, 2));
     } else {
       console.log(helpText);
@@ -1314,13 +1487,17 @@ Description:
     const { createNpmAdapter } = await import('../src/adapters/npm.mjs');
     const { createPluginMarketplaceAdapter } = await import('../src/adapters/plugin-marketplace.mjs');
     const { createPushSnapshotAdapter } = await import('../src/adapters/push-snapshot.mjs');
+    const { createDistributeGitAdapter } = await import('../src/adapters/distribute-git.mjs');
     const { createAdapterRegistry } = await import('../src/adapters/contract.mjs');
 
+    // v0.6.3 R1: the distribute saga executes through the distribute-git
+    // adapter; without this registration the production path fails closed.
     const registry = createAdapterRegistry([
       createGitGithubAdapter(),
       createNpmAdapter(),
       createPluginMarketplaceAdapter(),
       createPushSnapshotAdapter(),
+      createDistributeGitAdapter(),
     ]);
 
     const result = await distributeRelease({
@@ -1330,6 +1507,7 @@ Description:
       root,
       dryRun,
       planPath,
+      ...(postpublishApprovalPaths.length > 0 ? { postpublishApprovalPaths } : {}),
     });
 
     if (hasJson) {