release-skill 0.6.2 → 0.7.0

package/bin/license-texts/Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/license-texts/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} {{COPYRIGHT_HOLDER}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/registry.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.contracts.registry",
-  "contractsVersion": "1.5.0",
+  "contractsVersion": "1.7.0",
   "note": "Protocol-name and schema-$id registry. Registration mechanically rejects duplicate protocol name/version (SFC1004) and duplicate $id (SFC1003). This file is the single registration surface; adding an entry is a contracts change.",
   "protocols": [
     {
@@ -27,6 +27,13 @@
       "status": "stable",
       "file": "src/schemas/profile-descriptor.schema.json"
     },
+    {
+      "$id": "https://contracts.skill-family.example/v1/project-profile.json",
+      "object": "project-profile",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/project-profile.schema.json"
+    },
     {
       "$id": "https://contracts.skill-family.example/v1/managed-file-lock.json",
       "object": "managed-file-lock",
@@ -166,6 +173,62 @@
       "dialect": "2020-12",
       "status": "stable",
       "file": "src/schemas/structured-scan-policy.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/timeout-policy.json",
+      "object": "timeout-policy",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/timeout-policy.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/watchdog-termination-envelope.json",
+      "object": "watchdog-termination-envelope",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/watchdog-termination-envelope.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/public-boundary-declaration.json",
+      "object": "public-boundary-declaration",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/public-boundary-declaration.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/platform-difference-registry.json",
+      "object": "platform-difference-registry",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/platform-difference-registry.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/observation-scope.json",
+      "object": "observation-scope",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/observation-scope.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/profile-adoption-declaration.json",
+      "object": "profile-adoption-declaration",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/profile-adoption-declaration.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/audit-baseline-pin.json",
+      "object": "audit-baseline-pin",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/audit-baseline-pin.schema.json"
+    },
+    {
+      "$id": "https://contracts.skill-family.example/v1/token-estimate-record.json",
+      "object": "token-estimate-record",
+      "dialect": "2020-12",
+      "status": "stable",
+      "file": "src/schemas/token-estimate-record.schema.json"
     }
   ],
   "dialects": {

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,19 +1394,55 @@ 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
   
-Usage: release-skill distribute --plan <path> --run <path> [options]
+Usage: release-skill distribute --plan <path> --run <path> --approval <path> [options]
 
 Options:
   --root     Project root directory (default: cwd)
   --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)
+  --approval Path to the approval record (required)
+  --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:
@@ -1282,15 +1453,17 @@ Description:
       console.log(JSON.stringify({
         command: 'distribute',
         description: 'Distributes frozen artifacts to post-publish targets (git mirror + marketplace) after PUBLISHED',
-        usage: 'release-skill distribute --plan <path> --run <path> [options]',
+        usage: 'release-skill distribute --plan <path> --run <path> --approval <path> [options]',
         options: {
           '--root': 'Project root directory (default: cwd)',
           '--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)',
+          '--approval': 'Path to the approval record (required)',
+          '--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);
@@ -1298,8 +1471,8 @@ Description:
     process.exit(0);
   }
 
-  if (!planPath || !runPath) {
-    const msg = 'distribute requires --plan <path> and --run <path>';
+  if (!planPath || !runPath || !approvalPath) {
+    const msg = 'distribute requires --plan <path>, --run <path>, and --approval <path>';
     if (hasJson) {
       console.log(JSON.stringify({ error: 'MISSING_PARAMETERS', message: msg, exitCode: 1 }));
     } else {
@@ -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) {