release-skill 0.1.1

package/.agents/plugins/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "release-skill",
+  "interface": {
+    "displayName": "Release Skill",
+    "shortDescription": "Safe preparation and frozen GitHub/npm production publishing",
+    "category": "DevOps"
+  },
+  "plugins": [
+    {
+      "name": "release-skill",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "DevOps",
+      "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "release-skill",
+  "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
+  "owner": {
+    "name": "mzdbxqh",
+    "url": "https://github.com/mzdbxqh"
+  },
+  "plugins": [
+    {
+      "name": "release-skill",
+      "source": "./",
+      "version": "0.1.1",
+      "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "release-skill",
+  "version": "0.1.1",
+  "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
+  "author": {
+    "name": "release-skill contributors"
+  },
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Release Skill",
+    "shortDescription": "Safe preparation and frozen GitHub/npm publishing",
+    "longDescription": "Prepares byte-faithful public snapshots without rewriting project source files and publishes approved frozen GitHub/npm artifacts. Full happy end verification confirms consumer installation from frozen Git ref.",
+    "developerName": "release-skill",
+    "category": "DevOps",
+    "capabilities": [
+      "Write",
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Assess this project for release readiness.",
+      "Prepare a release plan for version 0.1.1.",
+      "Help me understand the release workflow."
+    ]
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+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.1] - 2026-07-18
+
+### Fixed
+
+- **Stable npm byte handoff on macOS and Linux**: production publishing no
+  longer passes `/dev/fd/*` or a mutable named path to npm. The adapter opens
+  the frozen tarball with `O_NOFOLLOW`, verifies file identity, SHA-256,
+  SHA-512 SRI, and embedded package name/version, then gives the same in-memory
+  `Buffer` to `libnpmpublish`.
+- **Registry and publisher authority**: plans freeze an explicit HTTPS npm
+  registry and publisher. Preflight, token-specific `whoami`, publish,
+  observation, and consumer install all use that registry; bearer credentials
+  are sent with `forceAuth` and never fall back to ambient identity.
+- **Pre-write tarball identity gate**: prepare and publish global preflight
+  reject a tarball whose manifest name/version or independently computed
+  integrity differs from the frozen unit and distribution, before any Git or
+  npm external action executes.
+- **Digest-addressed plan and approval history**: production commands consume
+  `plans/<planDigest>.json` and
+  `approvals/<planDigest>/<approvalDigest>.json`. Renewing an expired approval
+  preserves prior approval bytes, so a long-lived PARTIAL recovery remains
+  auditable without reusing expired authority.
+- **Reconcile succeeded checkpoint fail-closed**: when re-observing a
+  succeeded checkpoint, if the remote returns empty/error/uncertain state,
+  reconcile now fails closed with REMOTE_CONFLICT instead of adding to the
+  retry list. This prevents blind re-execution of already-succeeded actions.
+- **Production README blocking findings**: missing required markers and
+  readability requirements (install command, minimal example, failure
+  diagnosis) in production prepare are now blocking findings (GATE_FAILED),
+  not warnings.
+
+## [0.1.0] - 2026-07-15
+
+### Added
+
+- **release-help** skill: discoverable entry point with environment checks,
+  capability overview, minimal examples, read-only diagnosis, dry-run
+  guidance, and failure triage.
+- **release-assess** skill: read-only project topology identification and
+  gap evaluation for documentation, configuration, supply chain, and
+  release workflow.
+- **release-prepare** skill: gate execution and release plan freezing
+  without any external writes.
+- **release-publish** skill: external release checkpoint execution from
+  an approved, non-expired release plan.
+- **release-reconcile** skill: remote state querying, partial success
+  handling, safe retries, and post-publish verification.
+- Deterministic release state machine:
+  DISCOVERED -> ASSESSED -> PREPARED -> APPROVED -> PUBLISHING -> PUBLISHED -> VERIFIED.
+- Exception states: NEEDS_INPUT, BLOCKED, PARTIAL.
+- Adapter layer for Git/GitHub, npm, Claude Code marketplace, and Codex
+  marketplace.
+- Project declaration via `.release-skill/project.yaml` configuration.
+- Hook execution model with executable/argument arrays, relative cwd,
+  timeout, and environment allowlist.
+- Structured evidence output in JSON/JSONL format with per-step
+  checkpointing.
+- Read-only assess and prepare phases; publish requires explicit approval
+  bound to a frozen release plan digest.
+- 24-hour approval expiry with automatic invalidation on plan, tree hash,
+  target version, or remote conflict changes.
+- Reconcile with idempotent skip of already-consistent steps and safe
+  retry of incomplete actions.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education,
+socio-economic status, nationality, personal appearance, race, caste, color,
+religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action
+in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, and will communicate reasons
+for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public
+spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at the
+project's GitHub repository.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity

package/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to release-skill
+
+Thank you for your interest in contributing to release-skill.
+
+## Getting Started
+
+1. Fork and clone the repository.
+2. Install dependencies: `pnpm install`.
+3. Run tests: `pnpm test`.
+4. Run syntax validation: `pnpm build`.
+
+## Project Structure
+
+- `skills-src/` - Skill definition source files (SKILL.md for each skill).
+- `src/core/` - Deterministic release kernel (baseline, errors, evidence, hooks).
+- `src/adapters/` - Registry adapters (Git/GitHub, npm, plugin marketplace).
+- `bin/` - CLI entry point.
+- `schemas/` - JSON Schema definitions for configuration and plans.
+- `references/` - Rendered reference documentation.
+- `test/` - Test suite.
+
+## Development Guidelines
+
+- All code uses ESM (`.mjs` extension) on Node.js 22+.
+- All `.mjs` files must pass `node --check` (syntax validation).
+- Hooks must use executable/argument arrays, not shell strings.
+- Never include absolute paths like `/Users/...` in code or documentation.
+- Test your changes before submitting a pull request.
+
+## Pull Request Process
+
+1. Create a feature branch from `main`.
+2. Make your changes and ensure all tests pass.
+3. Write clear commit messages describing what changed and why.
+4. Open a pull request with a description of the change and any related
+   issue numbers.
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Reporting Issues
+
+For non-security issues, please open a GitHub issue with:
+
+- A clear description of the problem.
+- Steps to reproduce.
+- Expected vs. actual behavior.
+- Your environment (Node.js version, OS).

package/INSTALL.md

@@ -0,0 +1,182 @@
+# Installation Guide
+
+## Prerequisites
+
+- Node.js 22.0.0 or later
+- Git 2.30+
+
+## 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.
+
+```bash
+npm install -g release-skill
+CLI=(release-skill)
+```
+
+Or run directly without installing:
+
+```bash
+npx release-skill help
+```
+
+Verify:
+
+```bash
+release-skill --version
+release-skill help
+```
+
+You should see the version number and the list of available commands.
+
+## Development Install (Local Checkout)
+
+For development or when working from source:
+
+```bash
+export RELEASE_SKILL_HOME=/absolute/path/to/release-skill
+cd "$RELEASE_SKILL_HOME"
+npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
+```
+
+Then use the CLI via:
+
+```bash
+CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
+"${CLI[@]}" help
+```
+
+After `npm view release-skill version` confirms the supported version is
+published and installed, the equivalent npm entry is `CLI=(release-skill)`.
+
+## First Run
+
+The safest first command is always `help`. It runs entirely locally and
+performs no writes. Use the `CLI` array selected by the npm or source-checkout
+instructions above; do not mix the two entry paths in one run.
+
+```bash
+"${CLI[@]}" help
+```
+
+To check if your project is ready for release governance:
+
+```bash
+"${CLI[@]}" assess --root /path/to/your/project --offline --json
+```
+
+This command is read-only. It examines your project structure, configuration,
+documentation, and supply chain, then outputs a gap report. Without an explicit
+`--output`, `assess` writes no report file and never runs project hooks.
+
+`prepare` is different: it writes release artifacts under the target project's
+`.release-skill/` directory and may run configured hooks. Hooks are unsandboxed
+arbitrary processes. They may write outside the project, access credentials,
+use the network, or perform remote writes. Review the displayed executable,
+arguments, and working directory before granting
+`--acknowledge-hook-side-effects`.
+
+For a Git repository, keep the human-owned project configuration while ignoring
+generated authority and evidence:
+
+```gitignore
+.release-skill/*
+!.release-skill/project.yaml
+```
+
+## Project Configuration
+
+Create `.release-skill/project.yaml` in your project root. Here is a minimal
+example for a single-package project:
+
+```yaml
+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
+      - from: LICENSE
+        to: LICENSE
+        mode: preserve
+    requiredPublicFiles: [README.md, package.json, LICENSE]
+    previousPublicBaseline:
+      mode: none # only after confirming that no previous public version exists
+```
+
+### Advanced: hooks (optional)
+
+Hooks are optional and run arbitrary local processes. They require explicit
+`--acknowledge-hook-side-effects` authorization when used with `prepare`.
+
+```yaml
+hooks:
+  build:
+    command: [npm, run, build]
+  test:
+    command: [npm, test]
+```
+
+See the [full README](README.md) for hook parameter constraints and safety
+requirements.
+
+## Protect Human-Owned Content
+
+README text, slogans, examples, layout, and other manually curated source files
+remain authoritative. release-skill snapshots them according to each
+`publicFiles` mapping; it does not regenerate or overwrite the source README.
+After any manual edit, run `prepare` again and approve the new immutable plan.
+Never edit a frozen snapshot or reuse an old approval to make later steps pass.
+
+When an existing public copy has drifted, choose explicitly:
+
+- **merge** — compare the actual remote content, merge accepted changes back
+  into the human-owned source, then bind `previousPublicBaseline` to that exact
+  immutable `repo`/`ref`/`commit` and prepare again;
+- **adopt** — accept the remote copy as the new source of truth, first bring it
+  into the human-owned source, then update the same immutable baseline binding
+  and prepare again;
+- **reject** — stop and investigate. Do not switch to `mode: none` to bypass a
+  drift or uniqueness check.
+
+## Next Steps
+
+- Read the [full README](README.md) for the complete workflow guide.
+- 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
+  a release plan.
+- Before production, configure every unit's `previousPublicBaseline`. Use
+  `mode: bound` with the exact `repo`, `ref`, and `commit` for an existing
+  public version, then run `"${CLI[@]}" prepare --root <your-project> --online --production`.
+  The default observer proves only the ref-to-commit mapping; remote content is
+  not downloaded. Target branch/tag/Release/npm uniqueness is checked by the
+  publish global preflight before any execute.
+- For production commands, use only the immutable `planPath` returned by
+  `prepare --json` and immutable `approvalPath` returned by `approve --json`.
+  Mutable latest aliases are for convenience and are not production authority.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 release-skill contributors
+
+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/NOTICE

@@ -0,0 +1,25 @@
+# Notice
+
+release-skill is an open-source project released under the MIT License.
+
+## Third-Party Dependencies
+
+This project is built on Node.js and the npm ecosystem. See `package.json`
+for the full list of dependencies.
+
+## Acknowledgments
+
+The release governance patterns in this project draw on ideas from the
+following open-source projects:
+
+- [changesets/changesets](https://github.com/changesets/changesets) -
+  Change intent records and prepare/publish separation
+- [googleapis/release-please](https://github.com/googleapis/release-please) -
+  Reviewable release plans
+- [semantic-release/semantic-release](https://github.com/semantic-release/semantic-release) -
+  Idempotent publishing concepts
+- [vercel-labs/skills](https://github.com/vercel-labs/skills) -
+  Explicit triggers, provenance, and post-publish releases
+
+No code from these projects is copied or redistributed. Only design
+inspiration is acknowledged.