Simplify plugin release and repository checks

.github/workflows/ci.yml

@@ -31,30 +31,48 @@ jobs:
         run: |
           test "$(node --version)" = "v24.18.0"
           test "$(npm --version)" = "11.16.0"
+      - name: Select CI scope
+        id: scope
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: node script/ci-scope.mjs "$BASE_SHA" >> "$GITHUB_OUTPUT"
+      - name: Validate catalog metadata
+        if: steps.scope.outputs.catalog_only == 'true' && matrix.node == '22.0.0'
+        run: node script/check-release-compatibility.mjs
+      - name: Verify published catalog selection
+        if: steps.scope.outputs.catalog_only == 'true' && matrix.node == '24.18.0'
+        run: node script/check-catalog.mjs
       - run: npm ci --ignore-scripts
+        if: steps.scope.outputs.catalog_only != 'true'
       - name: Audit dependencies
-        if: matrix.node == '24.18.0'
+        if: steps.scope.outputs.catalog_only != 'true' && matrix.node == '24.18.0'
         run: npm audit
-      - run: sh script/check
       - name: Rehearse release ordering
-        if: matrix.node == '24.18.0'
+        if: steps.scope.outputs.catalog_only != 'true' && matrix.node == '24.18.0'
         run: |
           git fetch --force --no-tags origin \
             "+refs/tags/claude-v*:refs/release-check/tags/claude-v*"
           node script/check-plugin-release-order.mjs --prospective
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: steps.scope.outputs.catalog_only != 'true'
         with:
           repository: firstdraft/cli
           ref: main
           fetch-depth: 0
           path: tmp/firstdraft-cli
           persist-credentials: false
-      - run: git -C tmp/firstdraft-cli merge-base --is-ancestor 660c02e46cdf36ec76dd556de8c96ef67ed3b035 HEAD
-      - run: git -C tmp/firstdraft-cli checkout --detach 660c02e46cdf36ec76dd556de8c96ef67ed3b035
+      - name: Select the pinned CLI
+        if: steps.scope.outputs.catalog_only != 'true'
+        run: |
+          cli_revision="$(node --input-type=module -e 'import { cliRevision } from "./script/cli-contract/config.mjs"; console.log(cliRevision)')"
+          git -C tmp/firstdraft-cli merge-base --is-ancestor "$cli_revision" HEAD
+          git -C tmp/firstdraft-cli checkout --detach "$cli_revision"
+      - run: sh script/check --cli-root tmp/firstdraft-cli
+        if: steps.scope.outputs.catalog_only != 'true'
       - run: node script/check-cli-contract.mjs tmp/firstdraft-cli
-      - run: node script/check-claude-plugin-package.mjs --cli-root tmp/firstdraft-cli
+        if: steps.scope.outputs.catalog_only != 'true'
       - name: Check Codex installation and Skill discovery
-        if: matrix.node == '24.18.0'
+        if: steps.scope.outputs.catalog_only != 'true' && matrix.node == '24.18.0'
         run: |
           npm install --prefix "$RUNNER_TEMP/codex" --ignore-scripts --no-audit --no-fund @openai/codex@0.154.0
           node script/claude-plugin-package.mjs stage "$RUNNER_TEMP/firstdraft" --cli-root tmp/firstdraft-cli

.github/workflows/publish.yml

@@ -114,8 +114,11 @@ jobs:
           fetch-depth: 0
           path: tmp/firstdraft-cli
           persist-credentials: false
-      - run: git -C tmp/firstdraft-cli merge-base --is-ancestor 660c02e46cdf36ec76dd556de8c96ef67ed3b035 HEAD
-      - run: git -C tmp/firstdraft-cli checkout --detach 660c02e46cdf36ec76dd556de8c96ef67ed3b035
+      - name: Select the pinned CLI
+        run: |
+          cli_revision="$(node --input-type=module -e 'import { cliRevision } from "./script/cli-contract/config.mjs"; console.log(cliRevision)')"
+          git -C tmp/firstdraft-cli merge-base --is-ancestor "$cli_revision" HEAD
+          git -C tmp/firstdraft-cli checkout --detach "$cli_revision"
       - run: node script/check-cli-registry-package.mjs --cli-root tmp/firstdraft-cli
       - run: node script/claude-plugin-package.mjs pack "$RUNNER_TEMP/plugin" --cli-root tmp/firstdraft-cli
       - name: Verify publication bytes

README.md

@@ -9,9 +9,9 @@ actually receives.
 Source candidate `0.4.0` requires CLI `0.4.0`, Service API `0.4`, and Foundation Plan `0.20`. It preserves the planning
 workspace under `.firstdraft/design/` and defaults to current-folder local output. Use explicit `--github` for server
 Publication. Its identities belong in
-[release compatibility](release/compatibility.json); it is unpublished.
-The public catalog remains on plugin `0.2.5`. Only `create-full-stack-app` is packaged; the UI Skill auditions remain
-deferred source.
+[release compatibility](release/compatibility.json). The [public catalog](.claude-plugin/marketplace.json) owns the
+installed version; source compatibility does not establish publication. Only `create-full-stack-app` is packaged;
+the UI Skill auditions remain deferred source.
 
 Trying First Draft as a tester? Start with the
 [local development guide](https://gist.github.com/raghubetina/3d424a97a1eaa6de8c406e67f32a237e). Start in an empty
@@ -49,8 +49,8 @@ Historical pins and release chronology in the evidence archive are receipts, not
 
 ## Using Codex
 
-The catalog manifest selects shared plugin `0.2.5`, which includes the compatible CLI and discovers it in either
-agent. Drawing Board supplies its own project wrapper and installed CLI. The
+The [catalog manifest](.claude-plugin/marketplace.json) selects the shared plugin, which includes the compatible CLI
+and discovers it in either agent. Drawing Board supplies its own project wrapper and installed CLI. The
 [release evidence](evidence/2026-09-15-account-authoring-0.2.5.md) distinguishes package checks from public catalog
 installation. A fresh authenticated student Codespace journey remains unproved.
 
@@ -116,8 +116,7 @@ of Compilation, builds, or CI. A registry page example does not change the Rails
 
 ## Development
 
-Use Node.js 22 or newer and a real, non-shallow Git checkout. Checks inspect the repository index, historical
-evidence objects, and the complete Skill tree.
+Use Node.js 22 or newer and a Git checkout. Checks inspect the repository index and complete Skill tree.
 
 ~~~sh
 npm ci --ignore-scripts
@@ -133,8 +132,9 @@ The check covers:
 - deterministic plugin packaging with a stub CLI; and
 - release compatibility.
 
-CI separately checks the exact pinned CLI contract and candidate package digest. The release runbook owns the
-commands for reproducing that check against a local exact CLI checkout.
+CI checks consumer commands against the exact pinned CLI and verifies the candidate package digest. CLI-owned tests
+cover the complete Publication protocol matrix; Skills retains representative recovery cases, compatible fixtures,
+and packaged-executable integration. The release runbook owns the commands for reproducing these checks.
 
 Preview the plugin directly from a checkout:
 
@@ -152,8 +152,7 @@ node script/check-packaged-claude-plugin-install.mjs --claude /absolute/path/to/
 
 These install checks use temporary client state, discover every Skill through the real client, compare all Skill
 files with the candidate, and exercise the bundled CLI without a global `firstdraft`. They need no agent login or
-First Draft service. The old `check-claude-plugin-install.mjs` is a retired historical recording path, not the
-assembled-package check. Behavioral cases remain shared across clients; [the eval guide](evals/README.md) describes
+First Draft service. Behavioral cases remain shared across clients; [the eval guide](evals/README.md) describes
 the separate agent-session checks.
 
 If the installed GitHub CLI supports Skill preview:

RELEASING.md

@@ -9,8 +9,8 @@ longer part of an ordinary release. Coordinate the service, CLI, and Skills thro
 [`release/compatibility.json`](release/compatibility.json) owns the candidate version, compatible CLI/API/Plan
 identities, and deterministic package SHA-256. The current source candidate is
 `@firstdraft.com/claude-code@0.4.0` with CLI `0.4.0`, API `>= 0.4.0`, `< 0.5.0`, and Plan `sketch/0.20`.
-It is unpublished. The [marketplace manifest](.claude-plugin/marketplace.json) still selects the published plugin
-`0.2.5`; keep it there until the intended new version is actually published. Source compatibility is not public
+The [marketplace manifest](.claude-plugin/marketplace.json) independently selects a published plugin version;
+retain its selection until the intended new version is actually published. Source compatibility is not public
 catalog selection. Query npm when releasing rather than treating a dated distribution snapshot as current.
 
 Use an ordinary pre-1.0 minor bump for a breaking compatibility change and a patch bump for a compatible change.
@@ -28,7 +28,8 @@ The real GitHub `npm` environment protection still applies; do not bypass it or
 ## 1. Use the checks already completed
 
 1. Resolve the candidate commits for the service, CLI, and Skills. Confirm the Skills commit is on `main`, and the
-   CLI pin and compatibility metadata match the intended release.
+   CLI pin and compatibility metadata match the intended release. `script/cli-contract/config.mjs` owns the exact
+   CLI revision and runtime digest; workflows read that configuration rather than copying its values.
 2. Reuse successful hosted CI for the exact release commit. CI already runs repository tests, the pinned CLI
    contract, deterministic package checks, and Codex discovery. Do not rerun that suite, dependency audit, both
    client installations, or behavioral evaluation sessions merely because the release is about to publish.
@@ -40,9 +41,8 @@ For development or a failed check, the relevant reproduction commands are:
 
 ```sh
 npm ci --ignore-scripts
-sh script/check
+sh script/check --cli-root /path/to/exact/cli
 node script/check-cli-contract.mjs /path/to/exact/cli
-node script/check-claude-plugin-package.mjs --cli-root /path/to/exact/cli
 ```
 
 These are troubleshooting and pre-merge commands, not a second post-merge release checklist.
@@ -92,7 +92,8 @@ A public package verification is a read-only reconciliation, not another live ap
 ## 4. Select the published version in the catalog
 
 Update `.claude-plugin/marketplace.json` to the exact published version. Keep its version and npm source version
-aligned, run normal PR checks, and merge under the already authorized release scope. Never point the live catalog
+aligned and merge under the already authorized release scope. A version-selection-only change uses the catalog
+metadata and published-version checks; any other change runs the full CI matrix. Never point the live catalog
 at an unpublished candidate. Catalog CI validates this small change; do not add a second product smoke.
 
 A normal package release does not require installing both Claude and Codex again after the catalog merge. Verify a
@@ -111,6 +112,6 @@ start again without reconciliation. A validated retained Compilation ID permits
 `plan compile --github`, the documented unchanged-byte, same-singleton Publication replay remains available after
 the prior invocation exits; it never applies to an ambiguous Plan push or direct Compilation start.
 
-The [npm-default repair workflow](docs/npm-promotion.md) remains available for explicitly requested repairs of
-already-published versions. It is not part of the ordinary release. Record new release observations in
-[`evidence/`](evidence/README.md) without rewriting historical receipts.
+Use the short [npm-default repair procedure](docs/npm-promotion.md) for an approved change to an already-published
+version. It uses standard npm dist-tags, without a separate promotion workflow or credential probe. Record new
+release observations in [`evidence/`](evidence/README.md) without rewriting historical receipts.

docs/README.md

@@ -10,7 +10,7 @@ historical observations intentionally have different owners.
 | What package is the source candidate compatible with? | [`release/compatibility.json`](../release/compatibility.json) |
 | What does the shared Claude/Codex catalog select? | [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) |
 | What is the current release procedure? | [`RELEASING.md`](../RELEASING.md) |
-| How do I repair an existing npm default? | [npm promotion](npm-promotion.md) |
+| How do I repair an existing npm default? | [npm default repair](npm-promotion.md) |
 | What does the agent execute? | [`SKILL.md`](../skills/create-full-stack-app/SKILL.md) |
 | How does an agent extend or review generated UI? | The app's `UI.md`; [deferred Skill status](../README.md#ui-continuation) |
 | What is exact Plan syntax? | [JSON Schema](../skills/create-full-stack-app/references/foundation-plan-0.20.schema.json) |