release-skill 0.1.1 → 0.1.4

package/README.md

@@ -1,7 +1,8 @@
 # release-skill
 
-[简体中文](README.zh-CN.md)
+[简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
+<!-- release-skill:release-version: 0.1.4 -->
 Release preparation for Claude Code and Codex, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -10,28 +11,29 @@ reviewed artifacts first and publishes those same artifacts later; it does not
 regenerate a README or re-pack the live workspace at the last step.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** read-only `assess`, offline `prepare`, frozen Git
-> branch/tag, GitHub Release, npm tarball, and Claude/Codex marketplace consumer
-> installation verification have passed a local production-equivalent protocol
-> sandbox using the real release-skill CLI and frozen artifacts, local bare Git
-> remotes, and protocol fakes for `gh`, `npm`, Claude, and Codex. Separate
-> isolated local probes have exercised the installed Claude/Codex CLIs; no real
-> marketplace or production API was contacted. The tests do not provide
-> OS-level network isolation. We
-> have not run a real production canary for you; treat the first real release as
-> a monitored canary. Real APIs, auth, permissions, rate limits, and eventual
-> consistency are outside this sandbox claim. `prepare --online` observes previous
-> public baselines (bound mode) and fails closed on drift; remote uniqueness checks
-> are deferred to publish global preflight.
+> **Current boundary:** v0.1.4 is the current release. v0.1.1 completed a real production release
+> to GitHub and npm — the first production-verified milestone — followed by
+> exact npm installation and Claude/Codex consumer installation verification
+> from the frozen Git ref; "current release" and "first production-verified
+> milestone" are two distinct facts and must not be conflated. The same
+> workflow also has a local production-equivalent protocol suite using the
+> real release-skill CLI and frozen artifacts, local bare Git remotes, and
+> protocol fakes for `gh`, `npm`, Claude, and Codex. The suite does not
+> provide OS-level network isolation, and it does not prove that another
+> project's credentials, permissions, rate limits, or eventual-consistency
+> behavior will match this release. Treat each project's first production run
+> as a monitored canary. `prepare --online` observes bound previous-public
+> baselines and fails closed on drift; remote uniqueness checks run during
+> publish global preflight.
 
 <!-- release-skill:capability:safe-first-command -->
-> **v0.1.1 release candidate:** until `npm view release-skill version` returns
-> `0.1.1`, use the source-checkout command below; do not assume the npm command
-> already exists.
+> **Production path verified since the v0.1.1 milestone; v0.1.4 is the current
+> release.** The npm-installed CLI is the supported user entry. Source checkout
+> is the development/contributor fallback.
 >
 > **Start here:**
-> - published package: `release-skill help`
-> - current release candidate: `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help`
+> - npm install: `npm install -g release-skill` → `release-skill help`
+> - source checkout: `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help`
 
 <!-- release-skill:maturity:v0.1-boundary -->
 <!-- release-skill:maturity:boundary -->
@@ -58,6 +60,13 @@ slogans, examples, prose, formatting, and later human edits.
   intervention; the tool does not force or overwrite them.
 - Only files listed in `publicFiles` are copied. Add translated READMEs, images,
   demos, and linked documents explicitly when they belong in the release.
+- A release freezes only the current truth: `prepare` never refreshes or
+  rewrites human docs. Maintainers update README, INSTALL, and CHANGELOG first
+  — including the machine-readable `release-skill:release-version` markers,
+  which must equal the `package.json` version, and the formal CHANGELOG
+  heading for the current version — then prepare, review, and approve. A
+  pre-release gate fails closed when any doc version marker or the CHANGELOG
+  current-version entry drifts.
 
 This is the preservation contract: **copy current truth, freeze reviewed
 truth, and never rewrite human truth.**
@@ -70,12 +79,7 @@ truth, and never rewrite human truth.**
 - Git 2.30+
 - A target Git repository with at least one commit
 
-> **v0.1.1 release candidate:** before the production release completes, the
-> npm registry may return 404. Use the source-checkout path below for review.
-> After `npm view release-skill version` returns `0.1.1`, the npm-installed CLI
-> is the supported user entry and the source checkout is a development fallback.
-
-**Install from npm (supported after v0.1.1 publication):**
+**Install from npm (recommended):**
 
 ```bash
 npm install -g release-skill
@@ -93,7 +97,7 @@ npx release-skill help
 release-skill help
 ```
 
-**Development install (from source checkout):**
+**Development install (contributor fallback, from source checkout):**
 
 Set the checkout location and install dependencies:
 
@@ -105,8 +109,6 @@ npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
 
 Then use the CLI via `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs"`.
 
-Create `.release-skill/project.yaml` in the target project:
-
 First keep local plans, approvals, and frozen artifacts out of Git:
 
 ```gitignore
@@ -114,7 +116,194 @@ First keep local plans, approvals, and frozen artifacts out of Git:
 !.release-skill/project.yaml
 ```
 
-Then create the configuration. npm visibility must be explicit:
+### First use: deterministic setup without loading the full report
+
+Setup is read-only by default. Keep its potentially large report in temporary
+files; show the user or Agent only the deterministic `compactSummary` review
+view. The summary does not replace authorization: `setupDigest` still binds the
+complete facts, candidates, and answers.
+
+```bash
+PROJECT=/absolute/path/to/my-project
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+
+release-skill setup --root "$PROJECT" --json > "$REPORT" || test "$?" -eq 2
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
+```
+
+`NEEDS_INPUT` and `LOCAL_ONLY_DETECTED` intentionally exit with code 2. If
+`proposalConflicts` is non-empty—including `PUBLIC_REPO_AUTHORITY_CONFLICT` or
+a public-file mapping conflict—stop and let a human correct the conflicting
+repository or mapping authority, then rerun setup. Do not guess a winner.
+
+With no conflicts, copy the machine proposal mechanically. The Agent must not
+rewrite or transcribe it:
+
+```bash
+SETUP_SESSION='/session-directory-absolute-path-printed-above'
+PROJECT='/project-absolute-path-printed-above'
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+
+release-skill setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+Review that bound summary and exact digest once. After explicit human
+confirmation, use the confirmed digest literal to create the configuration:
+
+```bash
+SETUP_SESSION=<session-directory-absolute-path-printed-above>
+PROJECT=<project-absolute-path-printed-above>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+release-skill setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <confirmed-setupDigest> --json > "$CREATED_REPORT"
+release-skill setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+release-skill assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"||!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){process.exit(2)}process.stdout.write(JSON.stringify({created:c.status,postSetup:p.status,assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingCodes:(a.gaps??[]).filter(g=>g.severity==="error").map(g=>g.code)}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+The write must return `CONFIG_CREATED`; the next setup must return
+`ALREADY_CONFIGURED`. Existing configuration is never regenerated—make only
+reviewed incremental edits. Discovered interpreter/package-manager scripts are
+`SIDE_EFFECTS_UNPROVEN` and are not selected automatically. Add a project-specific
+hook or gate only after human review: edit `projectConfig.hooks`, or edit
+`verificationGates` and add the same id to `selectedGateIds`, then rerun the
+bound dry-run. Keep human files at `mode: preserve`, and
+use `sourceScope: workspace` only for explicit cross-unit shared sources.
+
+#### Advanced schema reference—not the first-use path
+
+The wrapper below illustrates the schema only. Do not hand-write it during the
+normal setup path; mechanically extract `recommendedAnswers` as shown above.
+
+```json
+{
+  "projectConfig": {
+    "apiVersion": "release-skill/v1",
+    "kind": "ReleaseProject",
+    "project": { "name": "my-project", "defaultBranch": "main" },
+    "releaseUnits": [{
+      "id": "my-project",
+      "source": ".",
+      "publicRepo": "owner/my-project",
+      "version": { "source": "package.json", "tagTemplate": "v{version}" },
+      "distributions": [{
+        "type": "npm",
+        "package": "my-project",
+        "access": "public",
+        "provenance": false,
+        "tag": "latest",
+        "registry": "https://registry.npmjs.org",
+        "publisher": "my-npm-username"
+      }],
+      "publicFiles": [
+        { "from": "README.md", "to": "README.md", "mode": "preserve" },
+        { "from": "package.json", "to": "package.json", "mode": "preserve" }
+      ],
+      "requiredPublicFiles": ["README.md", "package.json"],
+      "previousPublicBaseline": { "mode": "none" },
+      "production": {
+        "branchTemplate": "release/{tag}",
+        "branchStrategy": "create-release-branch"
+      }
+    }]
+  },
+  "selectedGateIds": []
+}
+```
+
+This is a schema reference, not an onboarding template. Normal setup must use
+the machine proposal. `mode: none` is valid only when no public version exists.
+
+The following reference shows the exact relationship between a manually
+reviewed gate and `selectedGateIds`. Apply that relationship only as an
+incremental edit to the extracted machine proposal:
+
+```json
+{
+  "projectConfig": {
+    "apiVersion": "release-skill/v1",
+    "kind": "ReleaseProject",
+    "project": { "name": "my-project", "defaultBranch": "main" },
+    "releaseUnits": [{
+      "id": "my-project",
+      "source": ".",
+      "publicRepo": "owner/my-project",
+      "version": { "source": "package.json", "tagTemplate": "v{version}" },
+      "distributions": [{
+        "type": "npm",
+        "package": "my-project",
+        "access": "public",
+        "provenance": false,
+        "tag": "latest",
+        "registry": "https://registry.npmjs.org",
+        "publisher": "my-npm-username"
+      }],
+      "publicFiles": [
+        { "from": "package.json", "to": "package.json", "mode": "preserve" }
+      ],
+      "requiredPublicFiles": ["package.json"],
+      "previousPublicBaseline": { "mode": "none" },
+      "production": {
+        "branchTemplate": "release/{tag}",
+        "branchStrategy": "create-release-branch"
+      }
+    }],
+    "verificationGates": [{
+      "id": "my-project-script-test",
+      "phase": "snapshot-verify",
+      "scope": { "unit": "my-project" },
+      "command": ["node", "-e", "const p=require('./package.json');if(!p.name)process.exit(1)"],
+      "cwd": ".",
+      "timeoutMs": 30000,
+      "envAllowlist": []
+    }]
+  },
+  "selectedGateIds": ["my-project-script-test"]
+}
+```
+
+The id must be copied from the current `gateCandidates`; do not invent one.
+The example command is self-contained in the public snapshot. A project script
+is valid only when the script and every dependency it needs are included in
+`publicFiles`; a snapshot gate cannot see the parent workspace's tests,
+development dependencies, or `node_modules` unless they are explicitly public.
+
+```bash
+release-skill setup --root /absolute/path/to/my-project \
+  --answers /absolute/path/to/setup-answers.json --json
+release-skill setup --root /absolute/path/to/my-project \
+  --answers /absolute/path/to/setup-answers.json \
+  --write --confirm-setup <setupDigest> --json
+```
+
+Setup atomically creates only an absent `.release-skill/project.yaml`.
+That create-once step uses the digest-registered `darwin-arm64` native
+prebuild shipped in v0.1.3; unsupported platforms fail closed with
+`SAFE_WRITE_UNAVAILABLE` instead of falling back to path-based writes.
+`ALREADY_CONFIGURED`/`CONFIG_EXISTS` means the existing file remains
+human-owned and must be edited incrementally. README, slogans, CHANGELOG, and
+business scripts are never generated or overwritten. A project with no remote
+channel reports `LOCAL_ONLY_DETECTED` instead of inventing production support.
+
+The following is a minimal human-authored configuration. npm visibility,
+public-file boundaries, and remote targets must be explicit:
 
 ```yaml
 apiVersion: release-skill/v1
@@ -162,6 +351,7 @@ releaseUnits:
         #   status: READY
     production:
       branchTemplate: release/{tag}
+      branchStrategy: create-release-branch
       releaseTitleTemplate: "{unit} {version}"
       releaseNotes: "Human-maintained release notes"
 ```
@@ -192,6 +382,58 @@ After `merge` or `adopt`, rebind `previousPublicBaseline` to the accepted
 immutable `repo`/`ref`/`commit`, then run a new `prepare --online --production`,
 review, and approval.
 
+Choose a branch strategy that matches the real repository:
+
+- `create-release-branch` creates an absent immutable release branch and stops
+  if the name already exists.
+- `advance-existing-branch` creates a single-parent commit on the exact
+  `previousPublicBaseline` commit and permits only an ordinary fast-forward
+  push; concurrent drift requires human intervention.
+- `initialize-default-branch` creates an absent standard branch under control.
+  Only explicit `setAsDefaultBranch` and `expectedCurrentDefaultBranch` values
+  add a separately approved, observed, and reconcilable default-branch action.
+
+Minimal configurations for the three strategies are:
+
+```yaml
+# New immutable release branch; the target must not exist.
+previousPublicBaseline: { mode: none } # only for a true first public release
+production:
+  branchTemplate: release/{tag}
+  branchStrategy: create-release-branch
+```
+
+```yaml
+# Advance main; the bound ref must be exactly the target branch.
+previousPublicBaseline:
+  mode: bound
+  repo: owner/my-project
+  ref: refs/heads/main
+  commit: 0123456789abcdef0123456789abcdef01234567
+production:
+  branchTemplate: main
+  branchStrategy: advance-existing-branch
+```
+
+```yaml
+# One-time creation of an absent main and an explicit default-branch switch.
+previousPublicBaseline:
+  mode: bound
+  repo: owner/my-project
+  ref: refs/heads/old-public-branch
+  commit: 0123456789abcdef0123456789abcdef01234567
+production:
+  branchTemplate: main
+  branchStrategy: initialize-default-branch
+  setAsDefaultBranch: true
+  expectedCurrentDefaultBranch: old-public-branch
+```
+
+The latter two require `prepare --online --production`. If the observed branch,
+commit, target absence, or current default branch differs, stop and update the
+human-owned source/config only after reviewing the real remote state; never
+force-push or weaken the baseline.
+
 This is a mechanics-only local example, not a complete npm publication map.
 Before a real release, enumerate every public runtime file, executable, type
 declaration, image, and linked document. In a monorepo, set `source` to a path
@@ -206,48 +448,71 @@ causes baseline validation to stop.
 
 ### Main workflow
 
-Run these steps in order. Steps 1–3 are safe default (read-only or local-only);
-steps 4–8 are production publishing with explicit human gates.
+Run these steps in order. Steps 1–4 are safe default (read-only or local-only);
+steps 5–9 are production publishing with explicit human gates.
 
 ```bash
-# Current v0.1.1 release candidate:
-CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
+# npm-installed CLI (recommended):
+CLI=(release-skill)
 PROJECT=/absolute/path/to/my-project
-# After npm view reports 0.1.1 and the package is installed:
-# CLI=(release-skill)
+ACTOR=your-name
+# Development fallback (source checkout):
+# CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
 ```
 
-The source-checkout entry remains the candidate default until npm publication is
-verified; after that, the installed npm entry is the supported user default.
+The npm-installed CLI is the supported user entry after v0.1.1 production
+publication. The source checkout remains the development/contributor fallback.
 
 1. **Environment check:**
    ```bash
    "${CLI[@]}" help
    ```
-2. **Readiness assessment (read-only):**
+2. **First-use setup (only when config is absent; read-only):**
+   ```bash
+   "${CLI[@]}" setup --root "$PROJECT" --json
+   ```
+   Follow the mechanical `compactSummary` and `recommendedAnswers` path above;
+   confirm the bound `setupDigest` once, and skip this step when configuration exists.
+3. **Readiness assessment (read-only):**
    ```bash
    "${CLI[@]}" assess --root "$PROJECT" --offline --json
    ```
-3. **Local snapshot and plan freeze:**
+4. **Local snapshot and plan freeze:**
    ```bash
-   "${CLI[@]}" prepare --root "$PROJECT" --offline --json
+   "${CLI[@]}" prepare --root "$PROJECT" --offline \
+     --acknowledge-hook-side-effects \
+     --acknowledge-gate-side-effects --json
    ```
-4. **Human review:** inspect the returned `planPath`, `externalActions`,
+   Omit an acknowledgement only when that project config has no corresponding
+   hook or snapshot gate. Never grant either acknowledgement before reviewing
+   the configured executable, arguments, working directory, and side effects.
+5. **Human review:** inspect the returned `planPath`, `externalActions`,
    `units[].targetVersion`, and `planDigest`. Each unit's snapshot is under
-   `<evidenceDir>/snapshots/<unit-id>/`. The command writes only local release
-   data under `.release-skill/`.
-5. **Production plan freeze:**
+   `<evidenceDir>/snapshots/<unit-id>/`. The release-skill pipeline writes its
+   own data under `.release-skill/`; acknowledged project hooks and gates are
+   unsandboxed processes and may write elsewhere or access the network.
+6. **Production plan freeze:**
    ```bash
-   "${CLI[@]}" prepare --root "$PROJECT" --online --production --json
+   PRODUCTION_JSON=$("${CLI[@]}" prepare --root "$PROJECT" --online --production \
+     --acknowledge-hook-side-effects \
+     --acknowledge-gate-side-effects --json)
+   printf '%s\n' "$PRODUCTION_JSON" | jq .
+   PLAN_PATH=$(printf '%s\n' "$PRODUCTION_JSON" | jq -r '.planPath')
+   PLAN_DIGEST=$(printf '%s\n' "$PRODUCTION_JSON" | jq -r '.planDigest')
    ```
+   As above, omit only acknowledgements that are not required by the project
+   config, and review every configured process before granting them.
    Review the new plan's externalActions, npm policy, branch/tag, and frozen
    digests. `prepare --json` returns the immutable production authority as
    `<project>/.release-skill/plans/<planDigest>.json`; always carry that returned
    `planPath` forward. `.release-skill/release-plan.json` is only a mutable
    convenience alias and must not be passed to production approve/publish/reconcile.
-6. **Approval:**
+7. **Approval:**
    ```bash
-   "${CLI[@]}" approve --plan <planPath> --digest <planDigest> --actor <name> --json
+   APPROVAL_JSON=$("${CLI[@]}" approve --plan "$PLAN_PATH" \
+     --digest "$PLAN_DIGEST" --actor "$ACTOR" --json)
+   printf '%s\n' "$APPROVAL_JSON" | jq .
+   APPROVAL_PATH=$(printf '%s\n' "$APPROVAL_JSON" | jq -r '.approvalPath')
    ```
    Returns the immutable production authority as `approvalPath` at
    `<project>/.release-skill/approvals/<planDigest>/<approvalDigest>.json`.
@@ -257,18 +522,28 @@ verified; after that, the installed npm entry is the supported user default.
    hours; a PARTIAL recovery may create a new approval for the same plan while
    preserving every earlier approval byte-for-byte. Use the returned
    `approvalPath` and `expiresAt` as authority.
-7. **Publish (remote writes start here):**
+8. **Publish (remote writes start here):**
    ```bash
-   "${CLI[@]}" publish --root "$PROJECT" \
-     --plan <planPath> --approval <approvalPath> \
-     --confirm-production <planDigest> --json
+   PUBLISH_JSON=$("${CLI[@]}" publish --root "$PROJECT" \
+     --plan "$PLAN_PATH" --approval "$APPROVAL_PATH" \
+     --confirm-production "$PLAN_DIGEST" --json)
+   printf '%s\n' "$PUBLISH_JSON" | jq .
+   PUBLISH_RUN_PATH=$(printf '%s\n' "$PUBLISH_JSON" | jq -r '.runPath')
    ```
    Save the returned `runPath`. `PUBLISHED` is **not** the terminal state.
-8. **Verify (consumer install check):**
+9. **Verify (consumer install check):**
    ```bash
    "${CLI[@]}" verify --root "$PROJECT" \
-     --plan <planPath> --run <publishRunPath> --json
+     --plan "$PLAN_PATH" --run "$PUBLISH_RUN_PATH" \
+     --acknowledge-gate-side-effects --json
    ```
+   Omit the acknowledgement only when the plan has neither consumer gates nor
+   a configured npm `smokeBin`. Both execute installed project code without an
+   OS or network sandbox.
+
+The handoff example requires `jq`. Without it, copy the same four returned JSON
+fields exactly; do not pass the angle-bracket labels shown elsewhere as shell
+syntax.
 
 Production prepare seals a standalone Git commit/tree for every public snapshot
 and creates a fixed tarball for every npm unit. Publish globally preflights all
@@ -411,17 +686,24 @@ Instead, use `reconcile` to inspect actual remote state, skip already-consistent
 steps, and safely retry incomplete actions:
 
 ```bash
-"${CLI[@]}" reconcile --root "$PROJECT" \
-  --run <publishRunPath> \
-  --plan <planPath> \
-  --approval <approvalPath> \
-  --confirm-production <planDigest> \
-  --json
+RECONCILE_JSON=$("${CLI[@]}" reconcile --root "$PROJECT" \
+  --run "$PUBLISH_RUN_PATH" \
+  --plan "$PLAN_PATH" \
+  --approval "$APPROVAL_PATH" \
+  --confirm-production "$PLAN_DIGEST" --json)
+printf '%s\n' "$RECONCILE_JSON" | jq .
+RECONCILE_RUN_PATH=$(printf '%s\n' "$RECONCILE_JSON" | jq -r '.runPath')
 # Save reconcile's new runPath, then perform the fresh install verification.
 "${CLI[@]}" verify --root "$PROJECT" \
-  --plan <planPath> --run <reconcileRunPath> --json
+  --plan "$PLAN_PATH" --run "$RECONCILE_RUN_PATH" \
+  --acknowledge-gate-side-effects --json
 ```
 
+Omit the verify acknowledgement only when the frozen plan has neither consumer
+gates nor an npm `smokeBin`. The variables above are the exact values captured
+by the main flow; if approval expired during recovery, create a fresh approval
+for the same immutable plan and replace `APPROVAL_PATH` before reconcile.
+
 `reconcile` queries the actual remote state (Git refs, npm version, GitHub
 Release, marketplace install), skips any step whose evidence already matches
 the frozen plan, and retries only safe and incomplete steps. Remote conflicts
@@ -435,6 +717,10 @@ Successful reconcile returns `PUBLISHED`, not `VERIFIED`; only the fresh
 - validates project configuration and release units;
 - reports readiness without changing the project during `assess`;
 - copies configured public files into an isolated snapshot;
+- discovers first-use candidates read-only and creates a config only once after
+  exact `setupDigest` confirmation;
+- runs human-selected project gates in frozen-snapshot copies and exact
+  consumer installation roots;
 - checks required files, path safety, exact bytes/modes, and obvious leaks;
 - records Git/workspace identity and freezes a digest-bound release plan;
 - binds approval to the plan digest, expiry, and explicit action allowlist;
@@ -447,6 +733,52 @@ Successful reconcile returns `PUBLISHED`, not `VERIFIED`; only the fresh
 - stops subsequent checkpoints on failure and writes a separate run record
   without mutating the frozen plan or undoing successful remote actions.
 
+## Project-specific verification: hooks and gates
+
+`hooks.docs/build/test/typecheck/lint` run before the snapshot is frozen. Use
+them only for work that genuinely needs the parent workspace or generates
+source files. They can modify files or access the network, so prepare requires
+`--acknowledge-hook-side-effects`.
+
+`verificationGates` are the controlled extension point for release calibration:
+
+```yaml
+verificationGates:
+  - id: package-contract
+    phase: snapshot-verify
+    scope: { unit: my-project }
+    command:
+      - node
+      - -e
+      - "const p=require('./package.json'); if (!p.name) process.exit(1)"
+    cwd: .
+    timeoutMs: 120000
+    envAllowlist: [CI]
+  - id: installed-help
+    phase: consumer-verify
+    scope: { unit: my-project, distribution: npm }
+    command: [node, scripts/check-installed-help.mjs]
+    cwd: .
+    timeoutMs: 30000
+    envAllowlist: []
+    expectedJson: { status: READY }
+```
+
+The snapshot example is deliberately self-contained and reads only a mapped
+public file. Any replacement script and every dependency it needs must exist
+in the frozen public snapshot. The consumer script must likewise be present in
+the exact installed distribution; gates cannot borrow tests, development
+dependencies, or `node_modules` from the parent workspace.
+
+`snapshot-verify` runs in a disposable writable copy of the frozen public
+snapshot. `consumer-verify` runs from an exact isolated npm/Claude/Codex install
+root. Both use executable arrays instead of shell strings; definitions and
+results enter digest-bound evidence, and prepare/verify require
+`--acknowledge-gate-side-effects`. Gates are still project processes without a
+network sandbox, so release-skill cannot promise that they will not write files
+or access the network. Push, tag, default-branch changes, GitHub Releases, and
+npm publish may never be hooks/gates; they remain controlled plan actions.
+
 ## What it does not do yet
 
 <!-- release-skill:capability:unsupported-scope -->
@@ -455,17 +787,22 @@ Successful reconcile returns `PUBLISHED`, not `VERIFIED`; only the fresh
 - no claim that a real production canary has run for marketplace verification;
 - `prepare --online` observes previous public baselines (bound mode) and defers
   remote uniqueness checks to publish global preflight;
-- no force push, overwrite of branches/tags/releases, or npm unpublish;
+- no overwrite of branches/tags/releases or npm unpublish; create-only refs use
+  `--force-with-lease=<ref>:` solely as an atomic compare-and-set assertion that
+  the ref is absent, while existing branches use an ordinary non-force push;
 - no promise of Windows or broad multi-platform native write support;
 - no hidden commit, push, tag, release, or package publication.
 
 ### Write Safety
 
-`assess` is read-only unless an explicit report output is requested. `prepare`
+`setup` is read-only by default and may create a config only once after exact
+digest confirmation. `assess` is read-only unless an explicit report output is requested. `prepare`
 writes local files under `.release-skill/`; it does not write project source
 files or remote services. If hooks are configured, they are arbitrary local
 processes and require `--acknowledge-hook-side-effects`; hooks may have their
-own filesystem or network side effects. `publish` is the production write entry
+own filesystem or network side effects. Gates are also project processes and
+require `--acknowledge-gate-side-effects`; they may have the same side effects.
+`publish` is the production write entry
 and requires both approval and the current plan digest. Omit hooks and use local
 sandbox targets for the smallest safe rehearsal.
 
@@ -473,12 +810,18 @@ sandbox targets for the smallest safe rehearsal.
 
 | Result | What to do |
 |---|---|
+| `NEEDS_INPUT` | Complete setup's repository, tag, channel, baseline, and gate decisions. |
+| `LOCAL_ONLY_DETECTED` | Establish a remote channel or keep only a local configuration design; do not claim production readiness. |
+| `SETUP_DIGEST_MISMATCH` | Facts or answers changed; rerun dry-run, review, and confirm the new digest. |
+| `CONFIG_EXISTS` | Setup never overwrites the existing config; assess it and edit incrementally. |
+| `SAFE_WRITE_UNAVAILABLE` | Automatic create-once setup is unsupported on this platform; keep the dry-run report and create the reviewed config manually without overwriting an existing file. |
 | `CONFIG_INVALID` | Correct `.release-skill/project.yaml`, then rerun `assess`. |
 | `PUBLIC_FILE_MISSING` | Add or correct the configured public file. |
 | `FORBIDDEN_CONTENT_DETECTED` | Remove the leaked/private content, then prepare again. |
 | `SNAPSHOT_FIDELITY_FAILED` | Inspect the source/snapshot path and rerun `prepare`. |
 | `BASELINE_CHANGED` | Keep the human edit, then prepare, review, and approve again. |
-| `GATE_FAILED` | Inspect frozen artifacts, auth, remote uniqueness, and digest confirmation. |
+| `GATE_FAILED` during `prepare` | Fix the snapshot gate or frozen public artifact, then run a new `prepare`; the failed plan cannot be approved. |
+| `GATE_FAILED` during `verify` | If the consumer environment failed, repair it and rerun `verify` from the same `PUBLISHED` run. If the published artifact is defective, release a new patch version; never overwrite it. |
 | `PARTIAL` | Do not restart or delete remote state; review the returned `runPath` and run `reconcile` (see above). |
 | `PUBLISHED` | Run `verify --plan <planPath> --run <publishRunPath>`; this is not terminal success. |
 | `VERIFIED` | Remote state, exact npm install, and configured plugin consumer installs all matched the frozen plan. |
@@ -486,15 +829,16 @@ sandbox targets for the smallest safe rehearsal.
 ## Skills
 
 - `release-help`: environment check and next-step guidance.
+- `release-setup`: read-only discovery, human calibration, and create-once first-use configuration.
 - `release-assess`: read-only release readiness report.
 - `release-prepare`: local snapshot and reviewable release plan.
 - `release-publish`: approved, digest-confirmed frozen GitHub+npm publishing.
 - `release-reconcile`: evidence-based PARTIAL recovery with human intervention on conflicts.
 - `release-verify`: post-publish verification; only `VERIFIED` is the happy end.
 
-Conflicts still default to human intervention. Before v0.1.1 is published, use
-the source CLI shown above; after registry verification, the supported user
-entry is the npm-installed `release-skill` CLI.
+Conflicts still default to human intervention. The npm-installed `release-skill`
+CLI is the supported user entry after v0.1.1 production publication; source
+checkout remains the development/contributor fallback.
 
 ## License