aeoptimize 0.6.0 → 0.6.1

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Content-readiness lint with evidence-bounded AI discovery experiments",
-    "version": "0.6.0"
+    "version": "0.6.1"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aeoptimize",
   "description": "Content-readiness lint and evidence-bounded discovery experiments",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "author": {
     "name": "Te-Shu Wang"
   },

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable user-visible changes will be documented here. The project follows Semantic Versioning after the v0.6 evidence baseline is released.
 
+## 0.6.1
+
+### Fixed
+
+- Bound public CLI verification to the downloaded tarball that passed SHA-256 verification.
+- Added an executable clean-worktree release candidate gate and cross-Node package reproducibility check.
+- Exercised the public rule corpus across the HTML parser boundary and strengthened release verifier failure tests.
+
 ## 0.6.0
 
 ### Changed

package/README.md

@@ -64,7 +64,7 @@ node -e "const r=require('./aeoptimize-report.json'); process.exit(r.overall.tot
 The v0.6 GitHub Action is advisory by default. It reports findings without blocking the workflow:
 
 ```yaml
-- uses: cucuwang/aeoptimize@v0.6.0
+- uses: cucuwang/aeoptimize@v0.6.1
   with:
     path: dist
 ```
@@ -72,7 +72,7 @@ The v0.6 GitHub Action is advisory by default. It reports findings without block
 Projects can explicitly choose blocking mode after accepting a baseline:
 
 ```yaml
-- uses: cucuwang/aeoptimize@v0.6.0
+- uses: cucuwang/aeoptimize@v0.6.1
   with:
     path: dist
     fail-on-low-score: 'true'

package/ROADMAP.md

@@ -14,7 +14,7 @@ Release gates:
 - root GitHub Action metadata and an end-to-end sample repository;
 - stable JSON output, changelog, release notes, and rollback instructions.
 
-The release gates are enforced by `src/core/__tests__/release-contract.test.ts`, the versioned corpus in `fixtures/v0.6/`, the copyable sample in `examples/github-action-sample/`, and the release runbook in `docs/release-v0.6.md`.
+The code-level gates are enforced by `npm run release:check`, `src/core/__tests__/release-contract.test.ts`, the versioned corpus in `fixtures/v0.6/`, and the local composite Action contract. CI compares real Node.js 22 and 24 package manifests and hashes. Repository rulesets and the release runbook remain separate maintainer controls.
 
 ## Product validation after v0.6
 

package/dist/cli/index.js

@@ -13,7 +13,7 @@ const program = new Command();
 program
     .name('aeoptimize')
     .description('Deterministic content-readiness lint for websites and documentation')
-    .version('0.6.0');
+    .version('0.6.1');
 // ── scan command ───────────────────────────────────────────────────
 program
     .command('scan <target>')

package/docs/release-v0.6.md

@@ -1,39 +1,33 @@
 # v0.6 release and rollback guide
 
-Version 0.6.0 establishes the evidence-bounded scoring, packaging, and GitHub Action contracts. It is not released until npm, the Git tag, and the GitHub Release are each created and read back independently.
+Version 0.6.1 hardens the v0.6 evidence-bounded scoring, packaging, and GitHub Action contracts. It is not released until npm, the Git tag, and the GitHub Release are each created and read back independently.
 
 ## Release acceptance
 
-Before publication, verify all of the following from the intended release commit:
+Before publication, run `npm ci` and `npm run release:check` from the intended release commit. The candidate gate verifies all of the following:
 
-1. `npm ci`, `npm run check`, `npm audit --audit-level=high`, and `bash action/test-contract.sh` pass.
+1. `npm run check`, `npm audit --audit-level=high`, and `bash action/test-contract.sh` pass.
 2. The public v0.6 rule corpus covers the positive, negative, and false-positive boundary for every scored rule.
-3. `npm pack` is reproducible, its SHA-256 is recorded, and a clean consumer can invoke `aeoptimize`, `aeo`, and `aeo-cli`.
+3. An actual `npm pack` candidate contains the required public files, its SHA-256 is recorded, and a clean consumer can invoke `aeoptimize`, `aeo`, and `aeo-cli` from that exact tarball.
 4. CI succeeds on Node.js 22 and 24 for the release commit.
 5. The JSON automation contract and Action sample tests pass.
 6. The npm account is verified immediately before publishing.
 
+CI runs the same candidate gate on Node.js 22 and 24 and compares version, filename, SHA-256, file count, and unpacked size. `prepublishOnly` invokes the candidate gate again and refuses a dirty worktree by default.
+
 Publishing, tagging, creating a GitHub Release, changing npm dist-tags, and deprecating a version are separate external mutations and require separate maintainer authorization.
 
 ## Release notes
 
-### Evidence-bounded readiness scoring
-
-- Reframe the score as deterministic content readiness rather than a prediction of ranking or AI citation.
-- Treat FAQ structure and `llms.txt` as optional, zero-point signals.
-- Remove exact-one-H1 and fixed meta-description-length assumptions.
-- Flag unsourced quantitative claims instead of rewarding more numbers.
-- Publish a versioned fixture corpus with positive, negative, and false-positive boundaries for every scored rule.
-
-### Reproducible automation
+### Artifact-bound release verification
 
-- Support maintained Node.js 22 and 24 lines.
-- Keep `aeoptimize`, `aeo`, and `aeo-cli` in the packed npm manifest.
-- Add an advisory-by-default GitHub Action with explicit blocking mode and stable JSON outputs.
-- Add a copyable end-to-end Action sample and release-time contract checks.
-- Refresh dependencies and require zero high or critical audit findings at release time.
+- Build the candidate from a clean worktree and install all three CLI aliases from the exact tarball whose SHA-256 is recorded.
+- Require byte-identical candidate manifests from Node.js 22 and 24 before the release can proceed.
+- Bind the public verifier's CLI smoke checks to the downloaded, hash-verified npm tarball.
+- Fail closed when a CLI alias, tag target, repository identity, or GitHub Release state does not match.
+- Exercise every v0.6 rule fixture through the real HTML parser boundary.
 
-No ranking, traffic, indexing, rich-result, AI Overview, or citation outcome is claimed by this release.
+No scoring rule, rule weight, JSON field, Action input, or Action output changes in this patch. No ranking, traffic, indexing, rich-result, AI Overview, or citation outcome is claimed by this release.
 
 ## Publication readback
 
@@ -41,16 +35,16 @@ After an authorized npm publication:
 
 ```bash
 npm view aeoptimize version dist-tags --json
-npm view aeoptimize@0.6.0 version gitHead repository homepage bugs dist --json
-consumer_root=$(mktemp -d "${TMPDIR:-/tmp}/aeoptimize-v0.6-consumer.XXXXXX")
-npm install --prefix "$consumer_root" aeoptimize@0.6.0
+npm view aeoptimize@0.6.1 version gitHead repository homepage bugs dist --json
+consumer_root=$(mktemp -d "${TMPDIR:-/tmp}/aeoptimize-v0.6.1-consumer.XXXXXX")
+npm install --prefix "$consumer_root" aeoptimize@0.6.1
 "$consumer_root/node_modules/.bin/aeoptimize" --version
 "$consumer_root/node_modules/.bin/aeo" --version
 "$consumer_root/node_modules/.bin/aeo-cli" --version
 rm -rf -- "$consumer_root"
 ```
 
-After separately authorized tag and GitHub Release creation, verify that `v0.6.0` points to the tested release commit and that the Release is published rather than draft or prerelease.
+After separately authorized tag and GitHub Release creation, verify that `v0.6.1` points to the tested release commit and that the Release is published rather than draft or prerelease.
 
 The fail-closed public verifier checks npm `latest`, the exact version, public repository identity, the downloaded tarball SHA-256, all three installed CLI aliases, the tag target, and the published GitHub Release. The tarball hash is the required artifact-identity gate. If npm exposes `gitHead`, it must match the expected release commit; absence is reported as informational because npm's publish contract guarantees tarball integrity but does not guarantee that metadata field.
 
@@ -62,11 +56,11 @@ bash scripts/verify-release-v0.6.sh <verified-release-commit> <verified-package-
 
 An npm dist-tag rollback changes what `npm install aeoptimize` selects; it does not remove exact-version installs. Never silently move an existing Git tag to different code.
 
-If npm 0.6.0 is unsuitable before a corrective release is available, request separate authorization for each mutation, then:
+If npm 0.6.1 is unsuitable before a corrective release is available, request separate authorization for each mutation, then:
 
 ```bash
-npm dist-tag add aeoptimize@0.5.3 latest
-npm deprecate aeoptimize@0.6.0 "Use 0.5.3 until the corrective release is available."
+npm dist-tag add aeoptimize@0.6.0 latest
+npm deprecate aeoptimize@0.6.1 "Use 0.6.0 until the corrective release is available."
 ```
 
-Mark the GitHub Release with the same warning. Preserve the `v0.6.0` tag as evidence of what was published, fix forward in 0.6.1, rerun the complete release acceptance suite, and only then move npm `latest` to the corrective version.
+Mark the GitHub Release with the same warning. Preserve the `v0.6.1` tag as evidence of what was published, fix forward in 0.6.2, rerun the complete release acceptance suite, and only then move npm `latest` to the corrective version.

package/examples/github-action-sample/.github/workflows/aeoptimize.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: cucuwang/aeoptimize@v0.6.0
+      - uses: cucuwang/aeoptimize@v0.6.1
         with:
           path: site
           fail-on-low-score: 'false'

package/examples/github-action-sample/README.md

@@ -6,4 +6,4 @@ This directory is a copyable end-to-end sample for the v0.6 Action contract.
 - `site/index.html` is a deterministic public input.
 - The Action is advisory by default. The sample does not block a pull request on an unreviewed score threshold.
 
-The workflow becomes reproducible only after both `aeoptimize@0.6.0` exists on npm and the immutable `v0.6.0` Git tag points to the matching release commit. Until both artifacts exist, use the local CLI or the release-candidate package during controlled verification.
+The workflow becomes reproducible only after both `aeoptimize@0.6.1` exists on npm and the immutable `v0.6.1` Git tag points to the matching release commit. Until both artifacts exist, use the local CLI or the release-candidate package during controlled verification.

package/fixtures/v0.6/rule-corpus.ts

@@ -126,14 +126,26 @@ export const ruleFixtureCorpus: Record<string, RuleFixtureSet> = {
     negative: {
       purpose: 'A majority of dangling pronoun or transition openings triggers a review finding.',
       document: {
-        paragraphs: ['This is important.', 'They require context.', 'However, it varies.', 'The release is versioned.', 'The report is public.'],
+        paragraphs: [
+          'This is important for the release.',
+          'They require additional context.',
+          'However, it varies by project.',
+          'The release is versioned for users.',
+          'The report is publicly available.',
+        ],
       },
       expected: { score: 3, issues: 1, suggestions: 1 },
     },
     boundary: {
       purpose: 'Exactly twenty percent dangling openings is the non-penalized ratio boundary.',
       document: {
-        paragraphs: ['This needs context.', 'The package is versioned.', 'The Action is advisory.', 'The report is stable.', 'The fixture is public.'],
+        paragraphs: [
+          'This needs context for the reader.',
+          'The package is explicitly versioned.',
+          'The Action is advisory by default.',
+          'The report remains stable for automation.',
+          'The fixture is publicly reviewable.',
+        ],
       },
       expected: { score: 8, issues: 0, suggestions: 1 },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeoptimize",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Deterministic content-readiness lint for static websites and documentation",
   "type": "module",
   "main": "./dist/core/index.js",
@@ -20,6 +20,7 @@
     "agents/",
     "fixtures/",
     "examples/github-action-sample/",
+    "scripts/verify-release-candidate.sh",
     "scripts/verify-release-v0.6.sh",
     ".claude-plugin/",
     "docs/methodology.md",
@@ -34,10 +35,11 @@
   "scripts": {
     "build": "tsc",
     "check": "npm test && npm run build",
+    "release:check": "bash scripts/verify-release-candidate.sh",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run check"
+    "prepublishOnly": "npm run release:check"
   },
   "keywords": [
     "aeo",

package/scripts/verify-release-candidate.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd)
+cd "$REPO_ROOT"
+
+for command_name in git jq mktemp node npm; do
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    echo "missing required command: $command_name" >&2
+    exit 2
+  fi
+done
+
+if [ "${ALLOW_DIRTY_RELEASE_CHECK:-0}" != "1" ] && [ -n "$(git status --porcelain)" ]; then
+  echo "release candidate must be built from a clean worktree" >&2
+  exit 1
+fi
+
+VERIFY_BASE=${TMPDIR:-/tmp}
+VERIFY_BASE=${VERIFY_BASE%/}
+VERIFY_ROOT=$(mktemp -d "$VERIFY_BASE/aeoptimize-release-candidate.XXXXXX")
+PACK_ROOT="$VERIFY_ROOT/pack"
+CONSUMER_ROOT="$VERIFY_ROOT/consumer"
+PACK_JSON="$VERIFY_ROOT/pack.json"
+
+cleanup() {
+  case "$VERIFY_ROOT" in
+    "$VERIFY_BASE"/aeoptimize-release-candidate.*)
+      rm -rf -- "$VERIFY_ROOT"
+      ;;
+    *)
+      echo "Refusing to remove unexpected verification path: $VERIFY_ROOT" >&2
+      ;;
+  esac
+}
+
+trap cleanup EXIT
+mkdir -p "$PACK_ROOT"
+
+npm run check
+bash action/test-contract.sh
+npm --cache "$VERIFY_ROOT/npm-cache" audit --audit-level=high
+npm_config_dry_run=false npm --cache "$VERIFY_ROOT/npm-cache" \
+  pack --json --pack-destination "$PACK_ROOT" > "$PACK_JSON"
+
+PACKAGE_FILENAME=$(jq -er '.[0].filename' "$PACK_JSON")
+PACKAGE_VERSION=$(jq -er '.[0].version' "$PACK_JSON")
+PACKAGE_FILE_COUNT=$(jq -er '.[0].files | length' "$PACK_JSON")
+PACKAGE_UNPACKED_SIZE=$(jq -er '.[0].unpackedSize' "$PACK_JSON")
+PACKAGE_TARBALL="$PACK_ROOT/$PACKAGE_FILENAME"
+PACKAGE_SHA256=$(node -e "const crypto=require('node:crypto');const fs=require('node:fs');console.log(crypto.createHash('sha256').update(fs.readFileSync(process.argv[1])).digest('hex'))" "$PACKAGE_TARBALL")
+
+jq -e '
+  (.[0].files | map(.path) | index("dist/cli/index.js")) != null and
+  (.[0].files | map(.path) | index("fixtures/v0.6/rule-corpus.ts")) != null and
+  (.[0].files | map(.path) | index("examples/github-action-sample/.github/workflows/aeoptimize.yml")) != null and
+  (.[0].files | map(.path) | index("scripts/verify-release-candidate.sh")) != null and
+  (.[0].files | map(.path) | index("scripts/verify-release-v0.6.sh")) != null
+' "$PACK_JSON" >/dev/null
+
+npm_config_dry_run=false npm --cache "$VERIFY_ROOT/npm-cache" install \
+  --ignore-scripts --no-audit --no-fund \
+  --prefix "$CONSUMER_ROOT" "$PACKAGE_TARBALL" >/dev/null
+
+for binary in aeoptimize aeo aeo-cli; do
+  BINARY_VERSION=$("$CONSUMER_ROOT/node_modules/.bin/$binary" --version)
+  if [ "$BINARY_VERSION" != "$PACKAGE_VERSION" ]; then
+    echo "$binary returned $BINARY_VERSION; expected $PACKAGE_VERSION" >&2
+    exit 1
+  fi
+done
+
+MANIFEST=$(jq -n \
+  --arg version "$PACKAGE_VERSION" \
+  --arg filename "$PACKAGE_FILENAME" \
+  --arg sha256 "$PACKAGE_SHA256" \
+  --argjson fileCount "$PACKAGE_FILE_COUNT" \
+  --argjson unpackedSize "$PACKAGE_UNPACKED_SIZE" \
+  '{version: $version, filename: $filename, sha256: $sha256, fileCount: $fileCount, unpackedSize: $unpackedSize}')
+
+if [ -n "${RELEASE_MANIFEST_OUT:-}" ]; then
+  printf '%s\n' "$MANIFEST" > "$RELEASE_MANIFEST_OUT"
+fi
+
+printf '%s\n' "$MANIFEST"
+echo "Release candidate checks passed."

package/scripts/verify-release-v0.6.sh

@@ -2,14 +2,22 @@
 set -u
 
 PACKAGE_NAME=aeoptimize
-EXPECTED_VERSION=0.6.0
-EXPECTED_TAG=v0.6.0
 REPOSITORY=cucuwang/aeoptimize
 EXPECTED_COMMIT=${1:-}
 EXPECTED_PACKAGE_SHA256=${2:-}
 EXPECTED_REPOSITORY_URL=git+https://github.com/cucuwang/aeoptimize.git
 EXPECTED_HOMEPAGE=https://github.com/cucuwang/aeoptimize
 EXPECTED_BUGS_URL=https://github.com/cucuwang/aeoptimize/issues
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+PACKAGE_JSON="$SCRIPT_DIR/../package.json"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "missing required command: node" >&2
+  exit 2
+fi
+
+EXPECTED_VERSION=$(node -e "const fs=require('node:fs');const packageJson=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.stdout.write(packageJson.version)" "$PACKAGE_JSON")
+EXPECTED_TAG="v$EXPECTED_VERSION"
 
 if [ -z "$EXPECTED_COMMIT" ] || [ -z "$EXPECTED_PACKAGE_SHA256" ]; then
   echo "usage: $0 <expected-release-commit> <expected-package-sha256>" >&2
@@ -26,7 +34,7 @@ if ! [[ "$EXPECTED_PACKAGE_SHA256" =~ ^[0-9a-f]{64}$ ]]; then
   exit 2
 fi
 
-for command_name in awk curl jq npm git mktemp node; do
+for command_name in awk curl jq npm git mktemp; do
   if ! command -v "$command_name" >/dev/null 2>&1; then
     echo "missing required command: $command_name" >&2
     exit 2
@@ -119,7 +127,7 @@ if curl -fsS "https://registry.npmjs.org/$PACKAGE_NAME" > "$REGISTRY_JSON"; then
 
     if npm --cache "$VERIFY_ROOT/npm-cache" install \
       --ignore-scripts --no-audit --no-fund \
-      --prefix "$CONSUMER_ROOT" "$PACKAGE_NAME@$EXPECTED_VERSION" >/dev/null; then
+      --prefix "$CONSUMER_ROOT" "$PACKAGE_TARBALL" >/dev/null; then
       for binary in aeoptimize aeo aeo-cli; do
         binary_version=$("$CONSUMER_ROOT/node_modules/.bin/$binary" --version 2>/dev/null || true)
         if [ "$binary_version" = "$EXPECTED_VERSION" ]; then
@@ -129,7 +137,7 @@ if curl -fsS "https://registry.npmjs.org/$PACKAGE_NAME" > "$REGISTRY_JSON"; then
         fi
       done
     else
-      fail "clean consumer installation failed for $PACKAGE_NAME@$EXPECTED_VERSION"
+      fail "clean consumer installation failed for the verified package tarball"
     fi
   else
     fail "npm does not contain exact version $EXPECTED_VERSION"