aeoptimize 0.6.0 → 0.6.2

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.2"
   },
   "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.2",
   "author": {
     "name": "Te-Shu Wang"
   },

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable user-visible changes will be documented here. The project follows Semantic Versioning after the v0.6 evidence baseline is released.
 
+## 0.6.2
+
+### Fixed
+
+- Added a fail-closed publish source gate that requires `HEAD` to match the fetched `origin/main` commit before npm publication.
+- Prepared a corrective release after npm 0.6.1 exposed the pre-squash PR commit as `gitHead`; the verified package contents were correct, but the release provenance did not match the merged commit.
+- Kept scoring rules, output contracts, and runtime behavior unchanged.
+
+## 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.2
   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.2
   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.2');
 // ── scan command ───────────────────────────────────────────────────
 program
     .command('scan <target>')

package/docs/release-v0.6.md

@@ -1,39 +1,34 @@
 # 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.2 is the provenance-corrective release for the v0.6 evidence-bounded scoring, packaging, and GitHub Action contracts. npm 0.6.1 contained the verified candidate bytes but exposed the pre-squash PR commit as `gitHead`, so no v0.6.1 Git tag or GitHub Release was created. Version 0.6.2 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.
+6. The npm account is verified immediately before publishing, and the publish source gate confirms that `HEAD` is the exact fetched `origin/main` commit.
+
+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, refuses a dirty worktree, and refuses publication unless `HEAD` matches `origin/main` exactly. Run `git fetch origin main` immediately before the authorized publish so the remote-tracking ref is current.
 
 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.
+- Fail closed before publication when the checked-out commit differs from the fetched `origin/main` commit.
+- 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 +36,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.2 version gitHead repository homepage bugs dist --json
+consumer_root=$(mktemp -d "${TMPDIR:-/tmp}/aeoptimize-v0.6.2-consumer.XXXXXX")
+npm install --prefix "$consumer_root" aeoptimize@0.6.2
 "$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.2` 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 +57,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.2 is unsuitable, request separate authorization for each mutation and restore `latest` to the last fully released version rather than the provenance-mismatched 0.6.1 artifact:
 
 ```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.2 "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. Never create or retarget `v0.6.1` merely to mask its npm `gitHead` mismatch. Preserve immutable versions as evidence, fix forward in 0.6.3, 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.2
         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.2` exists on npm and the immutable `v0.6.2` 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.2",
   "description": "Deterministic content-readiness lint for static websites and documentation",
   "type": "module",
   "main": "./dist/core/index.js",
@@ -20,6 +20,8 @@
     "agents/",
     "fixtures/",
     "examples/github-action-sample/",
+    "scripts/verify-release-candidate.sh",
+    "scripts/verify-publish-source.sh",
     "scripts/verify-release-v0.6.sh",
     ".claude-plugin/",
     "docs/methodology.md",
@@ -34,10 +36,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 && bash scripts/verify-publish-source.sh"
   },
   "keywords": [
     "aeo",

package/scripts/verify-publish-source.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -u
+
+if ! command -v git >/dev/null 2>&1; then
+  echo "missing required command: git" >&2
+  exit 2
+fi
+
+if ! head_commit=$(git rev-parse --verify HEAD 2>/dev/null); then
+  echo "publish source gate: HEAD is unavailable" >&2
+  exit 1
+fi
+
+if ! main_commit=$(git rev-parse --verify refs/remotes/origin/main 2>/dev/null); then
+  echo "publish source gate: origin/main is unavailable; run git fetch origin main" >&2
+  exit 1
+fi
+
+if [ "$head_commit" != "$main_commit" ]; then
+  echo "publish source gate: HEAD is $head_commit; expected origin/main $main_commit" >&2
+  echo "fetch origin/main and publish from its exact commit" >&2
+  exit 1
+fi
+
+echo "Publish source gate passed: HEAD matches origin/main at $head_commit."

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"