release-skill 0.1.1 → 0.1.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.1",
+      "version": "0.1.4",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,10 +1,10 @@
 {
   "name": "release-skill",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
   },
   "license": "MIT",
-  "skills": "./skills/"
+  "skills": "./adapters/claude/skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "release-skill",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
   },
   "license": "MIT",
-  "skills": "./skills/",
+  "skills": "./adapters/codex/skills/",
   "interface": {
     "displayName": "Release Skill",
     "shortDescription": "Safe preparation and frozen GitHub/npm publishing",
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.1.",
+      "Prepare a release plan for version 0.1.4.",
       "Help me understand the release workflow."
     ]
   }

package/CHANGELOG.md

@@ -3,6 +3,95 @@
 All notable changes to the `release-skill` plugin will be documented in this
 file. The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.1.4] - 2026-07-19
+
+### Added
+
+- **Docs version hard gate**: the English and Chinese README and INSTALL each
+  carry a machine-readable `release-skill:release-version` marker that must
+  equal the `package.json` version, and the CHANGELOG must carry a formal
+  heading for the current version. Any drift fails closed in
+  `pnpm test:release` before prepare. A release freezes only the current
+  truth: human docs are never auto-refreshed and must be updated, reviewed,
+  and approved first.
+- **Auditable frozen commit timestamps**: production `prepare` samples the
+  plan freeze time once, validates it before any Git write, and binds it to
+  `GIT_AUTHOR_DATE`/`GIT_COMMITTER_DATE` and each unit's
+  `frozenSnapshot.commitTimestamp` (schema-required); plans missing the field
+  are rejected instead of silently rebuilt.
+
+### Fixed
+
+- **Self-contained installed CLI smoke**: the v0.1.3 self-release selected
+  `help --json`, which correctly treats Git as a required environment
+  dependency, while npm smoke intentionally exposes only the Node runtime.
+  The CLI now supports `--version --json`, and self-release verification uses
+  that dependency-free entry to bind the installed CLI name and exact version
+  without widening the isolated process `PATH`.
+- Added a real subprocess regression that runs the installed-style version
+  entry with the Node-only `PATH` and proves an unrelated injected path is not
+  inherited.
+
+## [0.1.3] - 2026-07-19
+
+> `0.1.2` was an internal release candidate and was never published to npm or
+> GitHub Releases. Its fixes are included here; `0.1.3` is the next public
+> release after `0.1.1`.
+
+### Added
+
+- **Create-once first-use setup**: `release-skill setup` performs deterministic,
+  read-only discovery of packages, plugin manifests, Git remotes, legacy
+  `public-release.json`, public-file hints, and project quality scripts. It
+  reports `NEEDS_INPUT` or `LOCAL_ONLY_DETECTED` honestly and writes only an
+  absent `.release-skill/project.yaml` after answers and the exact
+  `setupDigest` are confirmed.
+- **Discoverable `release-setup` skill**: Claude and Codex adapters now guide
+  users through candidate review, explicit gate selection, fact-drift handling,
+  and the safe handoff to `release-assess` without regenerating human content.
+- **Project verification gates**: `snapshot-verify` runs selected commands in a
+  disposable writable copy of the frozen public snapshot;
+  `consumer-verify` runs after an exact isolated npm/Claude/Codex installation.
+  Gate definitions, exact execution-input digests, and bounded output digests
+  are frozen into plan/run evidence.
+- **Identity-bound create-once setup**: the final facts/answers digest and
+  config bytes are bound immediately before a directory-handle-relative,
+  no-follow create. v0.1.3 ships a digest-registered `darwin-arm64` prebuild;
+  unsupported platforms fail closed instead of using pathname writes.
+- **Explicit production branch strategies**: projects can create an immutable
+  release branch, fast-forward an existing branch from an exact bound baseline,
+  or initialize an absent standard branch and make a separately approved,
+  observable, reconcilable default-branch change.
+
+### Changed
+
+- Existing `public-release.json` snapshot commands are surfaced only as
+  migration candidates. Discovery never grants execution authority; gate and
+  legacy-hook side effects still require separate explicit acknowledgements.
+- Compatibility configurations for artifact-graph, flow-architect, loop-agent,
+  and agent-method-registry now bind real tag/channel/baseline semantics and
+  project-owned verification behavior. glaf4-test is represented as local-only
+  instead of receiving an invented remote channel.
+- README and installation guidance now begin with safe setup, explain the three
+  branch strategies, and distinguish pre-freeze hooks from frozen-snapshot and
+  installed-consumer gates.
+
+### Fixed
+
+- **GitHub CLI Release-missing plain text compatibility**: `gh release view`
+  returns plain text `release not found` when the target release does not
+  exist; the previous implementation only recognized an HTTP 404 exit code.
+  The adapter now maps that specific plain text to a missing-release
+  decision without misclassifying `repository not found` or permission
+  errors as a target release absence.
+- **Plugin consumer install verification transport semantics**: frozen
+  snapshots are sealed as read-only, but Git and plugin installation
+  transport restores owner write permission on extraction. Verification
+  now normalizes ordinary write permission from transport semantics and
+  continues to strictly verify path, type, content, size, and executable
+  intent. The frozen source digest is still compared against the plan and
+  must not be back-filled from observed results.
+
 ## [0.1.1] - 2026-07-18
 
 ### Fixed

package/INSTALL.md

@@ -1,5 +1,8 @@
 # Installation Guide
 
+[简体中文](INSTALL.zh-CN.md)
+
+<!-- release-skill:release-version: 0.1.4 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -7,9 +10,10 @@
 
 ## Install from npm (recommended)
 
-This repository is currently preparing the v0.1.1 release. Use the npm path
-only after `npm view release-skill version` returns `0.1.1` (or newer). Before
-that publication is verified, use the source checkout instructions below.
+A public version is complete only after its immutable production plan has been
+approved, published, and reached `VERIFIED`. For a newer source checkout, use
+the npm path only after `npm view release-skill version` returns that exact
+version; before then, use the source checkout instructions below.
 
 ```bash
 npm install -g release-skill
@@ -61,7 +65,124 @@ instructions above; do not mix the two entry paths in one run.
 "${CLI[@]}" help
 ```
 
-To check if your project is ready for release governance:
+If `.release-skill/project.yaml` is absent, keep the full read-only report in a
+temporary file and inspect only its deterministic `compactSummary`:
+
+```bash
+PROJECT=/path/to/your/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"
+
+"${CLI[@]}" 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"
+```
+
+The summary is a review view, not authorization; `setupDigest` binds the full
+facts, candidates, and answers. If `proposalConflicts` is non-empty, a human
+must correct the conflicting repository/mapping authority and rerun setup.
+Do not guess. With no conflicts, mechanically extract the proposal:
+
+```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"
+"${CLI[@]}" 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"
+```
+
+After one explicit human confirmation of the bound summary and exact digest,
+create once with that confirmed digest literal. The result must be
+`CONFIG_CREATED`; a second setup must be `ALREADY_CONFIGURED`, then run assess.
+
+```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"
+"${CLI[@]}" setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <confirmed-setupDigest> --json > "$CREATED_REPORT"
+"${CLI[@]}" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+"${CLI[@]}" 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"
+```
+
+Indirect interpreter/package-manager scripts are `SIDE_EFFECTS_UNPROVEN` and
+remain unselected. Register a project-specific hook/gate only through a reviewed
+incremental edit: edit `projectConfig.hooks`, or edit `verificationGates` and
+add the same id to `selectedGateIds`, then rerun the bound dry-run. Human files use `mode: preserve`; explicit cross-unit shared
+sources use `sourceScope: workspace`.
+
+### Advanced schema reference—not the first-run path
+
+The following wrapper documents the schema. Do not hand-write it during normal
+setup; use the mechanically extracted `recommendedAnswers`.
+
+```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 wrapper is reference data only. Normal setup uses the machine proposal;
+`mode: none` is valid only when no public version exists. When a reviewed gate
+is added incrementally, its id must exactly match `selectedGateIds`, and a
+snapshot gate plus its dependencies must be present in `publicFiles`. See the
+[README setup section](README.md#first-use-deterministic-setup-without-loading-the-full-report).
+
+An existing config is never regenerated or overwritten. A project with no
+discoverable GitHub/npm channel reports `LOCAL_ONLY_DETECTED` rather than
+claiming production readiness.
+
+The automatic create-once write uses the digest-registered `darwin-arm64`
+native prebuild shipped in v0.1.3. Other platforms fail closed with
+`SAFE_WRITE_UNAVAILABLE`; keep the dry-run report and create the reviewed file
+manually instead of enabling an unsafe pathname fallback.
+
+After the config exists, check release readiness:
 
 ```bash
 "${CLI[@]}" assess --root /path/to/your/project --offline --json
@@ -139,12 +260,100 @@ hooks:
   build:
     command: [npm, run, build]
   test:
-    command: [npm, test]
+    command:
+      - node
+      - -e
+      - "const p=require('./package.json'); if (!p.name) process.exit(1)"
 ```
 
 See the [full README](README.md) for hook parameter constraints and safety
 requirements.
 
+### Advanced: verification gates (optional)
+
+Use a `snapshot-verify` gate for checks that should run against a disposable
+writable copy of the frozen public snapshot. Use `consumer-verify` for commands
+that must run from an exact isolated npm/Claude/Codex installation root. Gate
+commands are executable arrays, not shell strings, and must declare unit,
+distribution when applicable, cwd, timeout, and environment allowlist.
+
+```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: 30000
+    envAllowlist: []
+```
+
+This self-contained example reads only a mapped public file. A replacement
+script and every dependency it needs must exist in the frozen public snapshot;
+the gate cannot borrow tests, development dependencies, or `node_modules` from
+the parent workspace.
+
+Prepare and verify require `--acknowledge-gate-side-effects` whenever their
+planned phase contains gates. Hooks and gates are project processes without a
+network sandbox; release-skill limits their inputs and evidence but cannot
+guarantee that a custom command will not modify files or access the network.
+Never register Git push, tag, default-branch changes, GitHub Releases, or npm
+publish as a hook/gate; those are controlled plan actions.
+
+### Production branch strategy
+
+Every production unit selects one explicit strategy:
+
+- `create-release-branch` creates an absent immutable release branch;
+- `advance-existing-branch` fast-forwards an existing branch from the exact
+  bound public baseline using an ordinary non-force push;
+- `initialize-default-branch` creates an absent standard branch and may add an
+  explicit default-branch action only when `setAsDefaultBranch` and
+  `expectedCurrentDefaultBranch` are both reviewed.
+
+Remote drift, a non-fast-forward update, or an unexpected default branch stops
+for human intervention. No strategy overwrites remote history. Create-only refs
+use `--force-with-lease=<ref>:` solely as an atomic absence assertion; advancing
+an existing branch uses an ordinary non-force push.
+
+```yaml
+# create-release-branch: target must be absent
+previousPublicBaseline: { mode: none } # true first public release only
+production:
+  branchTemplate: release/{tag}
+  branchStrategy: create-release-branch
+```
+
+```yaml
+# advance-existing-branch: ref must exactly equal refs/heads/<target>
+previousPublicBaseline:
+  mode: bound
+  repo: owner/my-project
+  ref: refs/heads/main
+  commit: 0123456789abcdef0123456789abcdef01234567
+production:
+  branchTemplate: main
+  branchStrategy: advance-existing-branch
+```
+
+```yaml
+# initialize-default-branch: main must be absent; current default must match
+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 last two strategies require online production prepare. Any mismatch stops
+for review; update the human-owned config only after inspecting real remote
+state, and never force-push or weaken the baseline.
+
 ## Protect Human-Owned Content
 
 README text, slogans, examples, layout, and other manually curated source files
@@ -167,6 +376,8 @@ When an existing public copy has drifted, choose explicitly:
 ## Next Steps
 
 - Read the [full README](README.md) for the complete workflow guide.
+- Run `"${CLI[@]}" setup --root <your-project> --json` when the project has no
+  configuration; keep its default dry-run behavior until human decisions are complete.
 - Run `"${CLI[@]}" assess --root <your-project> --offline` to evaluate your project's release readiness.
 - Run `"${CLI[@]}" prepare --root <your-project> --offline` (release-skill pipeline writes
   locally only; user-configured hooks may perform remote operations) to generate