@h4shed/rock-hardened

A public, project-agnostic implementation of the H4shed release contract:

Every PR changes the changelog.
Every changelog change generates release evidence.
Every release can generate a deterministic marketing asset.
Every artifact is traceable to source and version-control metadata.
Human approval remains the publication gate.

hardened-changelogger is designed for teams that want changelog enforcement to become a release-evidence and security-attestation layer, not just a text-file convention.

What it does

• Requires a CHANGELOG.md entry for PRs when used in CI.
• Parses [Unreleased] into structured release groups.
• Supports optional machine-readable release-meta comments.
• Builds a deterministic release manifest with branch, commit, version, source hashes, and selected highlights.
• Produces SHA-256 attestations for the manifest and generated assets.
• Optionally signs attestations with an Ed25519 private key.
• Generates a deterministic HTML release card.
• Optionally captures a 1200×630 PNG via Playwright.
• Ships GitHub Actions and blog frontmatter templates.
• Keeps source truth and human approval separate from automation.

Install

npm install --save-dev @h4shed/rock-hardened

or globally:

npm install -g @h4shed/rock-hardened

Claude Code plugin

The package ships a Claude Code marketplace (h4shed-rock-hardened) and the rock-hardened plugin, which includes a skill describing the CLI. Set it up during install with an opt-in environment variable:

HC_CLAUDE_PLUGIN=1 npm install --save-dev @h4shed/rock-hardened

Use HC_CLAUDE_PLUGIN_SCOPE=project to declare it in the project's Claude settings instead of your user settings. Project scope records the install path on your machine, so teammates should run the setup themselves.

Without the variable, npm only prints a hint. To set up the plugin later, or to preview the commands first:

npx hardened-changelogger claude-plugin install --dry-run
npx hardened-changelogger claude-plugin install [--scope user|project|local]

Setup runs claude plugin marketplace add and claude plugin install rock-hardened@h4shed-rock-hardened, so it needs the Claude Code CLI on your PATH. The plugin loads from the installed package directory. Re-running the setup is safe.

To remove it, run claude plugin marketplace remove h4shed-rock-hardened. Uninstalling the npm package does not remove the Claude registration.

Quick start

npx hardened-changelogger init
npx hardened-changelogger validate
npx hardened-changelogger manifest
npx hardened-changelogger render
npx hardened-changelogger attest

Run everything:

npx hardened-changelogger ci

Changelog contract

## [Unreleased]

### Added

#### Candidate Identity Verification
- Candidates can verify identity by email or supported government ID.
- Recruiters can see verification status without seeing private identity files.

<!-- release-meta
impact: major
audience: candidate,recruiter
marketing: true
category: security
status: shipped
-->

Supported metadata:

• impact: major | normal | minor | internal
• audience: comma-separated roles or audiences
• marketing: true | false
• category: free-form slug such as feature, security, ux, reliability
• status: shipped | preview | coming-soon | internal

Commands

init

Creates:

• release-contract.config.json
• .github/workflows/release-contract.yml if .github exists or can be created
• release-artifacts/ output directory

validate

Checks:

• CHANGELOG.md exists
• [Unreleased] exists
• at least one structured entry exists
• optional --require-changed verifies CHANGELOG.md changed relative to a git base ref
• release-meta blocks are valid
• coming-soon entries stay explicitly marked
• marketing entries contain renderable titles

manifest

Writes:

release-artifacts/release-manifest.json

The manifest includes:

• repository information
• PR number when available
• branch
• commit
• package version
• changelog source path and SHA-256
• release groups
• deterministic highlight ranking
• template and renderer identifiers

render

Writes deterministic HTML:

release-artifacts/release-card.html

If Playwright is installed, use:

npx hardened-changelogger render --png

to also create:

release-artifacts/release-og.png

Default PNG size: 1200×630.

attest

Writes:

release-artifacts/attestation.json

The attestation contains cryptographic hashes for:

• changelog
• release manifest
• release HTML
• release PNG when present

Optional signing:

HC_SIGNING_KEY=./ed25519-private.pem npx hardened-changelogger attest

The signature is Ed25519 over the canonical attestation payload.

sbom

Generates Software Bill of Materials in SPDX 2.3 format:

release-artifacts/sbom.spdx.json
release-artifacts/sbom-metadata.json

The SBOM includes:

• all direct and transitive dependencies
• package metadata and licenses
• dependency graph and relationships
• deterministic format for reproducible builds

Dependencies are extracted from package.json and lock files (package-lock.json or npm-shrinkwrap.json).

provenance

Builds provenance metadata linking build environment to release:

release-artifacts/provenance.json

The provenance captures:

• build timestamp and environment
• GitHub Actions OIDC token claims (when applicable)
• Node.js version and npm registry
• git commit, branch, and repository metadata
• hashes of manifest and SBOM artifacts

Enables verification that a release was built in a specific environment with known dependencies.

verify

Validates all release artifacts:

npx hardened-changelogger verify

Checks:

• ✓ SBOM compliance with SPDX 2.3 specification
• ✓ Provenance integrity and artifact hash consistency
• ✓ Source file hash matches changelog
• ✓ Attestation chain linking all artifacts

Creates:

release-artifacts/attestation-chain.json

ci

Runs complete supply-chain security pipeline:

validate → manifest → render → sbom → provenance → attest → verify

Use --require-changed in pull-request CI.

Configuration

release-contract.config.json

{
  "changelogPath": "CHANGELOG.md",
  "unreleasedHeading": "Unreleased",
  "outputDir": "release-artifacts",
  "siteUrl": "https://example.com",
  "brand": {
    "name": "Acme",
    "tagline": "Release Notes",
    "foreground": "#ffffff",
    "background": "#050505",
    "muted": "#a3a3a3"
  },
  "render": {
    "width": 1200,
    "height": 630,
    "maxHighlights": 4
  },
  "git": {
    "defaultBaseRef": "origin/main"
  }
}

The renderer is intentionally restrained and generic. Projects can replace the HTML renderer while keeping the manifest and attestation contract intact.

GitHub Actions

Copy:

templates/github/release-contract.yml

to:

.github/workflows/release-contract.yml

The workflow blocks PRs that do not include changelog evidence, generates the release evidence bundle, uploads it as an artifact, and exposes the bundle to follow-on publishing steps.

Security model

This package does not claim to prove that a release is safe. It attests that:

1. specific source inputs were used,
2. specific output artifacts were produced,
3. their hashes are recorded,
4. optional signatures bind the attestation to a signing key,
5. the release evidence can be reproduced and audited.

See SECURITY.md and docs/THREAT_MODEL.md.

Artifact Management (v0.7.0+)

Rock-Hardened provides automated PR-scoped artifact uploads with retention policies:

• PR preview artifacts - Automatically uploaded to GitHub Actions with 7-day retention
• Artifact separation - PR artifacts prefixed with pr- for easy identification
• Automatic cleanup - Expires on merge, close, or after 7 days
• GitHub integration - Posts artifact links to PR comments

For details, see ARTIFACT_MANAGEMENT.md.

Supply Chain Security (v0.5.0+)

The toolkit includes comprehensive supply chain security features:

SBOM (Software Bill of Materials)

• SPDX 2.3 format with all dependencies and licenses
• Deterministic, reproducible output
• Automatic dependency extraction from package-lock.json
• Validates SBOM structure and spec compliance

Provenance Tracking

• Captures build environment and version metadata
• GitHub Actions OIDC token claims (CI context)
• Hashes all release artifacts for verification
• Tracks git commit, branch, and repository context

Attestation Chains

• Links SBOM, manifest, and provenance with cryptographic hashes
• Verifiable relationships between all artifacts
• Enables end-to-end supply chain traceability

Verification

• Validates SBOM against SPDX specification
• Verifies provenance matches artifacts
• Checks artifact hash consistency
• Builds complete chain of custody

For detailed information, see SUPPLY_CHAIN_SECURITY.md.

Recommended protected-branch checks

• release-contract / changelog-entry
• release-contract / manifest
• release-contract / image-render
• release-contract / attestation

Publication model

Recommended lifecycle:

PR changelog delta
→ draft release manifest
→ draft release image
→ PR artifact
→ human review
→ merge
→ canonical release manifest
→ canonical marketing image
→ release/blog publication

Do not treat PR preview assets as canonical public release collateral.

Design philosophy

• Evidence before claim.
• Source before summary.
• Reuse before redraw.
• Deterministic render before generative render.
• Human approval before publication.
• Attestation is evidence, not a warranty.

License

MIT.