@deftai/directive-content 0.56.2 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.56.2",
+  "version": "0.57.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/, scripts/) the deposit wires. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

package/packs/skills/skills-pack-0.1.json

@@ -168,7 +168,7 @@
     },
     {
       "id": "deft-directive-release",
-      "description": "Cut a v0.X.Y release of the deft framework safely. Use when the user says \"release\", \"cut release\", \"v0.X.Y\", or \"publish release\" -- to walk an 8-phase workflow that pre-flights, runs an end-to-end rehearsal against a temp repo, lands a draft on the real repo, gates on user review, then publishes or rolls back. Re-uses the deft-directive-swarm Phase 6 Step 5 Slack announcement template.",
+      "description": "Cut a v0.X.Y release of the deft framework safely. Use when the user says \"release\", \"cut release\", \"v0.X.Y\", or \"publish release\" -- to walk an 8-phase workflow that pre-flights, runs an end-to-end rehearsal against a temp repo, lands a draft GitHub release (npm ships irrevocably at tag push), optionally QA's draft assets, then publishes the GitHub release or rolls back. Re-uses the deft-directive-swarm Phase 6 Step 5 Slack announcement template.",
       "triggers": [
         "release",
         "cut release",
@@ -177,7 +177,7 @@
       ],
       "path": "skills/deft-directive-release/SKILL.md",
       "version": "0.1",
-      "body": "# Deft Directive Release\n\nStructured 8-phase workflow for cutting a v0.X.Y release of the deft framework. Operationalizes the `task release` / `task release:publish` / `task release:rollback` / `task release:e2e` surface introduced in #716 (safety hardening of #74).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-swarm](../deft-directive-swarm/SKILL.md) Phase 6 Step 5 (Slack announcement template re-used by Phase 8 below) | [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) (user-gate pattern) | [deft-directive-refinement](../deft-directive-refinement/SKILL.md) (conversational phased flow).\n\n## Platform Requirements\n\n! GitHub as the SCM platform; the **GitHub CLI (`gh`)** must be installed and authenticated. The full pipeline plus the rehearsal target (`task release:e2e`) all dispatch through `gh`.\n\n## Branch-Protection Policy Guard\n\n! Before any Phase 1 state mutation, run the skill-level branch-policy guard documented in `scripts/policy.py` / `scripts/preflight_branch.py` (#746 / #747). Releases run on the configured base branch (default `master`), so the operator MUST be on the explicit-opt-in side of the policy before the pipeline starts writing files.\n\n**Preferred path — typed direct-commit policy opt-out (#1553).** For a release session on the default branch, prefer the audited typed flag over the emergency env-var bypass:\n\n```\ntask policy:allow-direct-commits -- --confirm\n```\n\nThis writes `plan.policy.allowDirectCommitsToMaster = true` on `vbrief/PROJECT-DEFINITION.vbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement:\n\n```\ntask policy:enforce-branches\n```\n\n**Branch-guard probe (either path).** Regardless of which opt-out path you chose, confirm the guard passes before Phase 1 mutates state:\n\n```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. This is the canonical surface that surfaces the policy state to the operator before the pipeline starts writing files. The release pipeline's other safety surfaces (the dirty-tree guard, base-branch check, `task ci:local` gate) remain independent of this check.\n\n**Emergency env-var bypass — narrow scope only (#1553).** `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is process-wide: every child process, nested test, and temporary repository spawned from the same shell inherits it. During the v0.43.0 release attempt, wrapping the entire `task release` invocation in this env var let the bypass leak into the Step 5 `task ci:local` preflight, which caused `TestWriteConsumerGitHooks_VendoredCommitBlocked_RealGit` to fail because the vendored test repo allowed a direct `master` commit the test expected the hook to block.\n\n- ! Prefer `task policy:allow-direct-commits -- --confirm` for release sessions instead of exporting `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the whole shell.\n- ⊗ Wrap `task release`, `task ci:local`, or `task check` in `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- the env var is inherited by every subprocess and can produce false preflight failures before any release mutation.\n- ? If the env-var path is unavoidable, scope it to a **single** branch-guard probe only (e.g. `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 task verify:branch`) and do NOT export it for the release session. The release pipeline itself passes the bypass only in scoped subprocess `env=` for its authorised commit/tag/push mutations (#867); operators MUST NOT mirror that pattern at the shell level.\n\nThe release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess `env=` only (`scripts/release.py::_release_subprocess_env`, #867) so the parent shell stays clean. Operator-side env-var exports defeat that isolation.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 `publish`/`rollback`/`defer`) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.\n\n## When to Use\n\n- User says \"release\", \"cut release\", \"v0.X.Y\", \"publish release\", \"ship a release\"\n- The framework's `[Unreleased]` CHANGELOG section is non-empty and the operator wants to cut a tagged release\n- A previous release rehearsal succeeded and the operator is ready for the production cut\n\n## Phase 1 — Pre-flight\n\n! Validate the local + remote state before any irreversible action.\n\n1. ! Verify the operator is on the configured base branch (default `master`) and the working tree is clean\n2. ! Confirm the next version number (`X.Y.Z`) with the user. Major / minor / patch decision flows from the `[Unreleased]` content (breaking change → major; new feature → minor; fix-only → patch)\n3. ! Inspect `[Unreleased]` content vs the proposed version bump. If a breaking change appears in `### Changed` / `### Removed` but only a patch is proposed, surface the mismatch and ask the user to choose\n4. ! Verify `task ci:local` passes locally (or `task check` as the graceful-degradation fallback per `tasks/release.yml` line 9-10). The `task release` script will refuse to proceed otherwise -- but Phase 1 catches it earlier\n5. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder vBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded vBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action\n7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action\n8. ! **Verify the npm credential path is configured before cutting the tag** (#1910, #1909). A `v*` tag now auto-triggers `.github/workflows/npm-publish.yml`, which publishes the four `@deftai/directive*` packages with `npm publish --provenance`. Confirm the publish path can authenticate: either the `NPM_TOKEN` repo secret is present (`gh secret list --repo <owner>/<repo>` shows `NPM_TOKEN`) OR an npm OIDC trusted publisher is configured for the `@deftai/directive*` packages. If neither is in place, WARN loudly that the tag will fire a publish job that fails (red X on the tag, no packages) -- the operator may still proceed for a GitHub-only release, but the npm channel will not land until #1909's credential is provisioned. Cross-reference #1909.\n9. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream\n\n⊗ Skip the version-bump magnitude check -- a patch release that ships breaking changes is the kind of regression that Repair Authority [AXIOM] (#709) is designed to prevent.\n\n⊗ Skip the vBRIEF-lifecycle-sync check (#734); the gate exists because operators consistently forget the manual `task scope:complete` move step. The v0.21.0 cut surfaced 13 stranded vBRIEFs (8 cycle-relevant + 5 historical residue) post-publish as the recurrence record this gate prevents. If `task release` reports `[3/13] Pre-flight vBRIEF lifecycle sync... FAIL (<count> mismatches; run task reconcile:issues -- --apply-lifecycle-fixes to fix)`, the canonical recovery is the apply-mode invocation -- `--allow-vbrief-drift` is reserved for cases where the operator has explicitly reviewed the drift and chosen to defer the lifecycle reconcile to the next refinement pass (e.g. an emergency hot-fix release).\n\n⊗ Skip the tag-availability check (#784); the gate exists because the legacy 12-step pipeline only invoked `git tag` at Step 9, after Steps 1-8 had already mutated state (CHANGELOG promoted, ROADMAP refreshed, dist built, release commit made locally). A duplicate-tag failure at Step 9 stranded the operator with an unpushed wrong-version commit + orphaned `dist/deft-<wrong>.zip` artifact + manual `git reset --hard` recovery (forbidden by AGENTS.md SCM rules without explicit permission). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01. If `task release` reports `[4/13] Pre-flight tag availability... FAIL (<surface> tag v<version> already exists ...)`, the canonical recovery is to choose a different version (the most likely cause is operator typo of a prior release).\n\n⊗ Hand-write a different one-line narrative for each of the three downstream surfaces (CHANGELOG / GitHub release / Slack) -- that drift is exactly the gap the `--summary` flag is designed to close. If the operator insists on per-audience tone, populate the canonical `--summary` ONCE here and document the deviation in the Phase 8 anti-pattern.\n\n## Phase 2 — Dry-run review\n\n! Invoke `task release -- <version> --dry-run --skip-tag --skip-release` and present the plan to the user. If Phase 1 collected an operator summary, also pass `--summary \"<text>\"` so the dry-run preview reflects the canonical narrative the operator just authored.\n\n```\ntask release -- <version> --dry-run --skip-tag --skip-release --summary \"<text>\"\n```\n\nThe dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline step (Step 13 is the post-create verify-isDraft gate added by #724; Step 4 is the tag-availability pre-flight gate added by #784). Step 6 (CHANGELOG promotion) surfaces whether a summary was supplied (truncated to ~60 chars in the preview) so the operator can validate the wording before any file is written. Capture the output and present it to the user, then wait for explicit confirmation before continuing.\n\n! Wait for explicit user confirmation: `yes` / `back` / `quit`.\n- `yes` (or `confirmed` / `approve`) → proceed to Phase 3\n- `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)\n- `quit` → abort the workflow cleanly; no state changes\n\n⊗ Skip the dry-run preview. The dry-run is the operator's last opportunity to catch a bad version number, malformed CHANGELOG, or wrong base branch before the pipeline starts writing files.\n\n## Phase 3 — E2E sanity\n\n! Invoke `task release:e2e` against an auto-created+destroyed temp repo to verify the full pipeline shape works end-to-end before touching the real repo.\n\n```\ntask release:e2e\n```\n\nThe harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and destroys the temp repo in a `try/finally` clause. Cleanup runs even if the rehearsal fails. If `gh repo delete` fails, surface the manual-cleanup hint to the user and continue.\n\n! Treat a non-zero exit from `task release:e2e` as a hard refusal to proceed to Phase 4. Surface the diagnostic and ask whether to debug (return to Phase 1) or abort (`quit`).\n\n? **Skip allowed** when the operator has just run `task release:e2e` successfully against the same branch in the past 30 minutes. Note the prior run timestamp in the user-facing summary.\n\n! **`task release:e2e` now also rehearses the npm publish (#1910).** Unless `--skip-npm` is passed (or `npm` is absent from PATH, which soft-skips), the rehearsal runs `npm publish --dry-run --access public` for all four `@deftai/directive*` packages against the throwaway clone in dependency order (types -> core -> content -> cli), after `pnpm install` + `pnpm -w run build` and a version-alignment pass. This catches a broken `files` allowlist, a version-drift bug, or a dependency-order error BEFORE the real `v*` tag fires the publish workflow -- without touching the real registry. The install+build exceeds the <90s fast budget, so pass `task release:e2e -- --skip-npm` when you only need the GitHub-pipeline shape check.\n\n! **Tag -> npm coupling + version invariant (#1910).** A `v<version>` tag is now a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. A red npm job on a green GitHub release means the npm channel did not ship (see Phase 7).\n\n## Phase 4 — Production draft\n\n! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`). If Phase 1 collected an operator summary, pass `--summary \"<text>\"` so the production cut writes the same blockquote the dry-run previewed.\n\n```\ntask release -- <version> --summary \"<text>\"\n```\n\nPer #716 default-draft hardening, this lands the release as a `--draft` on the real repo. Binaries upload via release.yml CI, but the artifact is NOT yet visible to consumers. The operator-authored summary becomes part of the promoted `CHANGELOG.md [<version>]` section AND the GitHub release body (auto-pickup via `_section_for_version`). The same wording is the canonical source for the Phase 8 Slack `*Summary*:` slot.\n\n! **Maintainer-mode release notes auto-lead with an \"Upgrading from an older version?\" banner (#1413).** When the cut targets the canonical framework repo (`deftai/directive`), `scripts/release.py` Step 12 prepends the banner from the editable template at `.github/release-notes/upgrade-banner.md` to the notes passed to `gh release create` (via `_prepend_upgrade_banner`). The banner points consumers at the canonical `deft-install --yes --upgrade --repo-root . --json` upgrade command and #1411. This is **GitHub-release-body-only** -- it is NEVER injected into `CHANGELOG.md`, so the CHANGELOG section and the release body intentionally differ by this leading block. To change the wording, edit the template file; do not hand-edit the published release body. **Consumer-mode releases (any non-`deftai/directive` repo) are unaffected** -- a downstream project that vendors the release pipeline never inherits deft's upgrade guidance. A missing/unreadable template degrades gracefully (notes ship without the banner; the cut is never blocked).\n\n! **Verify isDraft within 5 seconds; flip immediately if not (#724).** Immediately after `gh release create --draft` returns success, `scripts/release.py` Step 11 polls `gh release view v<version> --json isDraft` up to 5 times at 1-second intervals. If the release exists with `isDraft=false`, the pipeline auto-flips it via `gh release edit v<version> --draft=true` and emits a `WARNING: release landed as public; flipping to draft (defense-in-depth, see #724)` line. This closes the ~90-second public-exposure window observed during the v0.21.0 cut where a manual recovery created a public release before the operator noticed and flipped it. The verify gate is defense in depth even when `--draft` was passed correctly: it catches the case where `gh release create` partially succeeded (release record written, error returned) AND the operator-error variant where an alternate code path sent the release without `--draft`. A release-not-found-within-budget result emits a WARN and does NOT fail the pipeline (release.yml CI may still be processing).\n\n! Wait for `task release` to exit 0 before continuing. A non-zero exit means the pipeline halted partway through; consult Phase 7's `task release:rollback` recovery before retrying.\n\n⊗ Pass `--no-draft` here unless the operator has explicitly opted into direct-publish (e.g. automated security patch). The default-draft contract is the foundation of the safety hardening surface.\n\n⊗ Skip the post-create verify-isDraft gate -- the gate is the only reliable safety net against \"create call exited 0 but the release somehow landed as public\" variants (#724). If `task release` is invoked manually outside the canonical `scripts/release.py` flow, the operator MUST run `gh release view v<version> --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` BEFORE handing off to Phase 5.\n\n## Phase 5 — Draft review gate (user-only authority)\n\n! After `task release` exits 0, present the draft release for user review.\n\n1. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user\n2. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly\n3. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)\n4. ! Wait for explicit user confirmation:\n   - `publish` (or `yes` / `confirmed` / `approve`) → proceed to Phase 6 (Publish branch)\n   - `rollback` → proceed to Phase 6 (Rollback branch)\n   - `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish` or `task release:rollback`. Do NOT auto-merge; do NOT silently wait\n\n⊗ Bypass the user-only authority gate. Even under time pressure or long-context, the release MUST receive an explicit `publish` / `rollback` / `defer` decision from the user. This mirrors the Phase 5→6 gate in `skills/deft-directive-swarm/SKILL.md`.\n\n## Phase 6 — Publish or rollback\n\n! Branch on the user's Phase 5 decision.\n\n### Publish branch (user said `publish`)\n\n```\ntask release:publish -- <version>\n```\n\nThe companion script flips `--draft=false`, then re-reads the release to verify `isDraft == false` actually flipped. State machine:\n- `draft` found → flip to public; verify; exit 0\n- already `published` → exit 0 no-op (idempotent re-runs are safe)\n- `not-found` → exit 1 (cannot publish a missing release)\n- gh-error → exit 1 with diagnostic\n\n! Wait for `task release:publish` to exit 0 before continuing.\n\n### Rollback branch (user said `rollback`)\n\n```\ntask release:rollback -- <version>\n```\n\nThe state-aware unwind detects the post-release state and applies the matching tiered recovery. Time-windowed download-count guard:\n- release age `< 5 min` → threshold = 0 (rollback safe; nobody noticed yet)\n- release age `5-30 min` → threshold = max(`--allow-low-downloads`, 10) (filters bot fetches)\n- release age `> 30 min` → refuse without `--allow-data-loss`\n\nThree escape hatches (escalating warnings):\n- `--allow-low-downloads N` -- accept up to N downloads\n- `--allow-data-loss` -- accept any count (consumer impact)\n- `--force-strict-0` -- require exactly 0 regardless of release age\n\nRace-condition mitigation: `download_count` is double-read with a 5s sleep between reads; rollback only proceeds if both reads agree below threshold.\n\n! When the guard refuses, surface the recommendation to the user: rollback is risky on a released artifact with non-zero downloads. Prefer the **hot-fix path** (cut the next patch with a withdrawal note in `[Unreleased]/Changed` rather than deleting the broken release).\n\n## Phase 7 — Post-publish verification\n\n! Only enter Phase 7 if Phase 6 took the Publish branch (rollback branch ends here with the unwind log).\n\n1. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)\n2. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment \"Closed by release v<version> (squash auto-close did not trigger)\"` (Layer 1, #167)\n3. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n4. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK\n5. ! **Verify the npm publish landed (#1910, #1909).** The `v<version>` tag fired `.github/workflows/npm-publish.yml` in parallel with this skill's pipeline. Confirm the job succeeded (`gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 1` shows the tag run as `completed`/`success`) AND that all four packages published at the new version with provenance: for each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version` (expect it to echo `<version>`) and confirm the provenance attestation on the package's npm page. Surface a missing package or a failed job the same way the closing-keyword / renderer-drift checks above surface failures -- a green GitHub release with a red npm job means the npm channel did NOT ship. (Real-registry verification depends on #1909's credential being provisioned; until then this step verifies the workflow-run status and flags the credential gap.)\n6. ! For any umbrella / staying-OPEN issue (`Refs #N`) referenced in the release notes, run the Layer 3 reopen sweep from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1: any protected issue that auto-closed MUST be reopened with a comment citing #701\n\n⊗ Skip the post-publish verification. The closing-keyword false-positive (Layer 1 / Layer 2 / Layer 3) and the incremental-renderer-drift (#641, #614) are exactly the kind of issues that surface only AFTER a release is public.\n\n## Phase 8 — Slack announcement\n\n! Generate the canonical Slack release announcement and present it to the user for copy-paste, re-using the template from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 5.\n\nThe announcement block MUST include:\n\n```\n:rocket: *deft v<version>* -- <release title>\n\n*Summary*: <one-sentence description of the release scope>\n\n*Key Changes*:\n- <bullet per significant change, 3-5 items max>\n\n*Stats*: 1 release | ~<duration> elapsed | <N> commits since v<previous>\n*Release*: <GitHub release URL>\n```\n\n! Populate version from the freshly-published `gh release view v<version>` output. Populate release title from the CHANGELOG section heading (or the GitHub release title). Summarize key changes from the promoted `[Unreleased]` -> `[<version>]` CHANGELOG section (NOT raw commit messages). Populate stats from `git log v<previous>..v<version> --oneline | wc -l`.\n\n! Populate the `*Summary*:` slot VERBATIM from the operator-authored blockquote at the top of the CHANGELOG `[<version>]` section (the line beginning with `> ` immediately after the `## [<version>] - <date>` heading). The Phase 1 prompt + Phase 4 `--summary` flag exist precisely so this populate step is mechanical -- one canonical narrative authored once at Phase 1, propagated through Phase 4 promotion, and copy-pasted here without re-authoring. If the CHANGELOG section has no blockquote (operator skipped the Phase 1 prompt), generate a one-sentence summary from the `### Added` / `### Changed` bullets and surface to the operator that this is a regenerated narrative (NOT canonical) so they can decide whether to amend the CHANGELOG before publishing.\n\n! Present the block as a code-fenced snippet the user can copy directly. Do NOT post to Slack from inside this skill -- the user owns the actual broadcast.\n\n## Skill Completion\n\n! When Phase 8 completes (or when Phase 5 took the `defer` / `quit` path, or when Phase 6 completed the rollback branch), explicitly confirm skill exit:\n\n```\ndeft-directive-release complete -- exiting skill.\nNext: <one-line guidance>\n```\n\nWhere `<one-line guidance>` is one of:\n- \"release v<version> live -- monitor consumer reports for ~24h before cutting v<next>\"\n- \"release v<version> rolled back -- the underlying defect needs a hot-fix in the next CHANGELOG entry\"\n- \"release deferred -- resume by running `task release:publish -- <version>` (or `task release:rollback -- <version>`) when ready\"\n\n⊗ Exit silently without confirming completion or providing next-step guidance.\n\n## Anti-Patterns\n\n- ⊗ Run `task release` without a Phase 2 dry-run preview -- the dry-run is the only safe place to catch a bad version, malformed CHANGELOG, or wrong base branch\n- ⊗ Skip Phase 3 (e2e rehearsal) on the assumption that \"the dry-run is enough\" -- the e2e harness catches gh-CLI auth issues, repo permission gaps, and pipeline-shape regressions that the dry-run cannot detect\n- ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface\n- ⊗ Auto-publish a draft without the Phase 5 user-only authority gate -- even under time pressure or long-context, the release MUST receive an explicit `publish` / `rollback` / `defer` decision\n- ⊗ Run `task release:rollback` against a release that has > 30 minutes of consumer-driven downloads without first weighing the hot-fix path -- a withdrawal note in the next patch is almost always less disruptive than deleting a public artifact\n- ⊗ Use `--allow-data-loss` without first reading the script docstring's hot-fix-path recommendation -- the flag is an explicit acknowledgment of consumer impact, not a default\n- ⊗ Skip the Phase 7 Layer 3 reopen sweep -- protected umbrellas can auto-close on a release-merge squash even when the release notes use `Refs #N` only\n- ⊗ Post the Phase 8 Slack announcement directly from this skill -- the user owns the broadcast; the skill only generates the template\n- ⊗ Hardcode `master` as the base branch -- delegate to the configured base branch from `task release --base-branch <branch>`\n- ⊗ Skip the post-create verify-isDraft gate (#724) -- a successful `gh release create` exit code does NOT prove the release actually landed in draft state; the 5-second poll-and-flip gate in `scripts/release.py` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `scripts/release.py` MUST run `gh release view --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` before handing off to Phase 5\n- ⊗ Manually rewrite the Phase 8 Slack `*Summary*:` line to deviate from the CHANGELOG `[<version>]` blockquote -- the canonical narrative is authored ONCE at Phase 1 via `--summary` and propagates verbatim across all three audiences (CHANGELOG / GitHub release body / Slack). Per-audience hand-edits create documentation drift that the deterministic `--summary` flow is designed to prevent. If the operator wants Slack-specific tone, fold it into the canonical Phase 1 wording before passing `--summary`, OR amend the CHANGELOG blockquote BEFORE Phase 8 so all three surfaces stay aligned\n- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut\n",
+      "body": "# Deft Directive Release\n\nStructured 8-phase workflow for cutting a v0.X.Y release of the deft framework. Operationalizes the `task release` / `task release:publish` / `task release:rollback` / `task release:e2e` surface introduced in #716 (safety hardening of #74).\n\nLegend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.\n\n**See also**: [deft-directive-swarm](../deft-directive-swarm/SKILL.md) Phase 6 Step 5 (Slack announcement template re-used by Phase 8 below) | [deft-directive-review-cycle](../deft-directive-review-cycle/SKILL.md) (user-gate pattern) | [deft-directive-refinement](../deft-directive-refinement/SKILL.md) (conversational phased flow).\n\n## Platform Requirements\n\n! GitHub as the SCM platform; the **GitHub CLI (`gh`)** must be installed and authenticated. The full pipeline plus the rehearsal target (`task release:e2e`) all dispatch through `gh`.\n\n## Branch-Protection Policy Guard\n\n! Before any Phase 1 state mutation, run the skill-level branch-policy guard documented in `scripts/policy.py` / `scripts/preflight_branch.py` (#746 / #747). Releases run on the configured base branch (default `master`), so the operator MUST be on the explicit-opt-in side of the policy before the pipeline starts writing files.\n\n**Preferred path — typed direct-commit policy opt-out (#1553).** For a release session on the default branch, prefer the audited typed flag over the emergency env-var bypass:\n\n```\ntask policy:allow-direct-commits -- --confirm\n```\n\nThis writes `plan.policy.allowDirectCommitsToMaster = true` on `vbrief/PROJECT-DEFINITION.vbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement:\n\n```\ntask policy:enforce-branches\n```\n\n**Branch-guard probe (either path).** Regardless of which opt-out path you chose, confirm the guard passes before Phase 1 mutates state:\n\n```\nuv run python scripts/preflight_branch.py --project-root . --quiet || exit 1\n```\n\nor invoke `task verify:branch`. This is the canonical surface that surfaces the policy state to the operator before the pipeline starts writing files. The release pipeline's other safety surfaces (the dirty-tree guard, base-branch check, `task ci:local` gate) remain independent of this check.\n\n**Emergency env-var bypass — narrow scope only (#1553).** `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is process-wide: every child process, nested test, and temporary repository spawned from the same shell inherits it. During the v0.43.0 release attempt, wrapping the entire `task release` invocation in this env var let the bypass leak into the Step 5 `task ci:local` preflight, which caused `TestWriteConsumerGitHooks_VendoredCommitBlocked_RealGit` to fail because the vendored test repo allowed a direct `master` commit the test expected the hook to block.\n\n- ! Prefer `task policy:allow-direct-commits -- --confirm` for release sessions instead of exporting `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the whole shell.\n- ⊗ Wrap `task release`, `task ci:local`, or `task check` in `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- the env var is inherited by every subprocess and can produce false preflight failures before any release mutation.\n- ? If the env-var path is unavoidable, scope it to a **single** branch-guard probe only (e.g. `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 task verify:branch`) and do NOT export it for the release session. The release pipeline itself passes the bypass only in scoped subprocess `env=` for its authorised commit/tag/push mutations (#867); operators MUST NOT mirror that pattern at the shell level.\n\nThe release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess `env=` only (`scripts/release.py::_release_subprocess_env`, #867) so the parent shell stays clean. Operator-side env-var exports defeat that isolation.\n\n## Deterministic Questions Contract\n\n! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 optional `defer`/`rollback`/`Discuss` (happy path auto-publishes after draft QA)) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.\n\n## When to Use\n\n- User says \"release\", \"cut release\", \"v0.X.Y\", \"publish release\", \"ship a release\"\n- The framework's `[Unreleased]` CHANGELOG section is non-empty and the operator wants to cut a tagged release\n- A previous release rehearsal succeeded and the operator is ready for the production cut\n\n## Phase 1 — Pre-flight\n\n! Validate the local + remote state before any irreversible action.\n\n1. ! Verify the operator is on the configured base branch (default `master`) and the working tree is clean\n2. ! Confirm the next version number (`X.Y.Z`) with the user. Major / minor / patch decision flows from the `[Unreleased]` content (breaking change → major; new feature → minor; fix-only → patch)\n3. ! Inspect `[Unreleased]` content vs the proposed version bump. If a breaking change appears in `### Changed` / `### Removed` but only a patch is proposed, surface the mismatch and ask the user to choose\n4. ! Verify `task ci:local` passes locally (or `task check` as the graceful-degradation fallback per `tasks/release.yml` line 9-10). The `task release` script will refuse to proceed otherwise -- but Phase 1 catches it earlier\n5. ! Verify `gh auth status` reports authenticated (`task release` will refuse otherwise)\n6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder vBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded vBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action\n7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action\n8. ! **Verify the npm credential path is configured before cutting the tag** (#1910, #1909). A `v*` tag now auto-triggers `.github/workflows/npm-publish.yml`, which publishes the four `@deftai/directive*` packages with `npm publish --provenance`. Confirm the publish path can authenticate: either the `NPM_TOKEN` repo secret is present (`gh secret list --repo <owner>/<repo>` shows `NPM_TOKEN`) OR an npm OIDC trusted publisher is configured for the `@deftai/directive*` packages. If neither is in place, WARN loudly that the tag will fire a publish job that fails (red X on the tag, no packages) -- the operator may still proceed for a GitHub-only release, but the npm channel will not land until #1909's credential is provisioned. Cross-reference #1909.\n9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The operator's explicit `yes` in Phase 2 (dry-run) and the decision to invoke `task release` in Phase 4 are the last human gates before npm goes live. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm.\n10. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream\n\n⊗ Skip the version-bump magnitude check -- a patch release that ships breaking changes is the kind of regression that Repair Authority [AXIOM] (#709) is designed to prevent.\n\n⊗ Skip the vBRIEF-lifecycle-sync check (#734); the gate exists because operators consistently forget the manual `task scope:complete` move step. The v0.21.0 cut surfaced 13 stranded vBRIEFs (8 cycle-relevant + 5 historical residue) post-publish as the recurrence record this gate prevents. If `task release` reports `[3/13] Pre-flight vBRIEF lifecycle sync... FAIL (<count> mismatches; run task reconcile:issues -- --apply-lifecycle-fixes to fix)`, the canonical recovery is the apply-mode invocation -- `--allow-vbrief-drift` is reserved for cases where the operator has explicitly reviewed the drift and chosen to defer the lifecycle reconcile to the next refinement pass (e.g. an emergency hot-fix release).\n\n⊗ Skip the tag-availability check (#784); the gate exists because the legacy 12-step pipeline only invoked `git tag` at Step 9, after Steps 1-8 had already mutated state (CHANGELOG promoted, ROADMAP refreshed, dist built, release commit made locally). A duplicate-tag failure at Step 9 stranded the operator with an unpushed wrong-version commit + orphaned `dist/deft-<wrong>.zip` artifact + manual `git reset --hard` recovery (forbidden by AGENTS.md SCM rules without explicit permission). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01. If `task release` reports `[4/13] Pre-flight tag availability... FAIL (<surface> tag v<version> already exists ...)`, the canonical recovery is to choose a different version (the most likely cause is operator typo of a prior release).\n\n⊗ Hand-write a different one-line narrative for each of the three downstream surfaces (CHANGELOG / GitHub release / Slack) -- that drift is exactly the gap the `--summary` flag is designed to close. If the operator insists on per-audience tone, populate the canonical `--summary` ONCE here and document the deviation in the Phase 8 anti-pattern.\n\n## Phase 2 — Dry-run review\n\n! Invoke `task release -- <version> --dry-run --skip-tag --skip-release` and present the plan to the user. If Phase 1 collected an operator summary, also pass `--summary \"<text>\"` so the dry-run preview reflects the canonical narrative the operator just authored.\n\n```\ntask release -- <version> --dry-run --skip-tag --skip-release --summary \"<text>\"\n```\n\nThe dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline step (Step 13 is the post-create verify-isDraft gate added by #724; Step 4 is the tag-availability pre-flight gate added by #784). Step 6 (CHANGELOG promotion) surfaces whether a summary was supplied (truncated to ~60 chars in the preview) so the operator can validate the wording before any file is written. Capture the output and present it to the user, then wait for explicit confirmation before continuing.\n\n! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) -- this `yes` is the last safe abort before that channel opens.\n- `yes` (or `confirmed` / `approve`) → proceed to Phase 3\n- `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)\n- `quit` → abort the workflow cleanly; no state changes\n\n⊗ Skip the dry-run preview. The dry-run is the operator's last opportunity to catch a bad version number, malformed CHANGELOG, or wrong base branch before the pipeline starts writing files.\n\n## Phase 3 — E2E sanity\n\n! Invoke `task release:e2e` against an auto-created+destroyed temp repo to verify the full pipeline shape works end-to-end before touching the real repo.\n\n```\ntask release:e2e\n```\n\nThe harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and destroys the temp repo in a `try/finally` clause. Cleanup runs even if the rehearsal fails. If `gh repo delete` fails, surface the manual-cleanup hint to the user and continue.\n\n! Treat a non-zero exit from `task release:e2e` as a hard refusal to proceed to Phase 4. Surface the diagnostic and ask whether to debug (return to Phase 1) or abort (`quit`).\n\n? **Skip allowed** when the operator has just run `task release:e2e` successfully against the same branch in the past 30 minutes. Note the prior run timestamp in the user-facing summary.\n\n! **`task release:e2e` now also rehearses the npm publish (#1910).** Unless `--skip-npm` is passed (or `npm` is absent from PATH, which soft-skips), the rehearsal runs `npm publish --dry-run --access public` for all four `@deftai/directive*` packages against the throwaway clone in dependency order (types -> core -> content -> cli), after `pnpm install` + `pnpm -w run build` and a version-alignment pass. This catches a broken `files` allowlist, a version-drift bug, or a dependency-order error BEFORE the real `v*` tag fires the publish workflow -- without touching the real registry. The install+build exceeds the <90s fast budget, so pass `task release:e2e -- --skip-npm` when you only need the GitHub-pipeline shape check.\n\n! **Tag -> npm coupling + irrevocability (#1910, #1972, #2002).** A `v<version>` tag is a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release and is NOT draft-gated. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. **npm publish is irrevocable** (#1972): once the tag fires, packages are live on npm and cannot be unpulled; `task release:rollback` does NOT retract npm (forward-only recovery). A red npm job on a green GitHub release means the npm channel did not ship (verify in Phase 5/7).\n\n## Phase 4 — Production draft\n\n! **Last human gate before npm (#1972, #2002).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms.\n\n! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`). If Phase 1 collected an operator summary, pass `--summary \"<text>\"` so the production cut writes the same blockquote the dry-run previewed.\n\n```\ntask release -- <version> --summary \"<text>\"\n```\n\nPer #716 default-draft hardening, this lands the release as a `--draft` on the real repo. Binaries upload via release.yml CI, but the artifact is NOT yet visible to consumers. The operator-authored summary becomes part of the promoted `CHANGELOG.md [<version>]` section AND the GitHub release body (auto-pickup via `_section_for_version`). The same wording is the canonical source for the Phase 8 Slack `*Summary*:` slot.\n\n! **Maintainer-mode release notes auto-lead with an \"Upgrading from an older version?\" banner (#1413).** When the cut targets the canonical framework repo (`deftai/directive`), `scripts/release.py` Step 12 prepends the banner from the editable template at `.github/release-notes/upgrade-banner.md` to the notes passed to `gh release create` (via `_prepend_upgrade_banner`). The banner points consumers at the canonical `deft-install --yes --upgrade --repo-root . --json` upgrade command and #1411. This is **GitHub-release-body-only** -- it is NEVER injected into `CHANGELOG.md`, so the CHANGELOG section and the release body intentionally differ by this leading block. To change the wording, edit the template file; do not hand-edit the published release body. **Consumer-mode releases (any non-`deftai/directive` repo) are unaffected** -- a downstream project that vendors the release pipeline never inherits deft's upgrade guidance. A missing/unreadable template degrades gracefully (notes ship without the banner; the cut is never blocked).\n\n! **Verify isDraft within 5 seconds; flip immediately if not (#724).** Immediately after `gh release create --draft` returns success, `scripts/release.py` Step 11 polls `gh release view v<version> --json isDraft` up to 5 times at 1-second intervals. If the release exists with `isDraft=false`, the pipeline auto-flips it via `gh release edit v<version> --draft=true` and emits a `WARNING: release landed as public; flipping to draft (defense-in-depth, see #724)` line. This closes the ~90-second public-exposure window observed during the v0.21.0 cut where a manual recovery created a public release before the operator noticed and flipped it. The verify gate is defense in depth even when `--draft` was passed correctly: it catches the case where `gh release create` partially succeeded (release record written, error returned) AND the operator-error variant where an alternate code path sent the release without `--draft`. A release-not-found-within-budget result emits a WARN and does NOT fail the pipeline (release.yml CI may still be processing).\n\n! Wait for `task release` to exit 0 before continuing. A non-zero exit means the pipeline halted partway through; consult Phase 7's `task release:rollback` recovery before retrying.\n\n⊗ Pass `--no-draft` here unless the operator has explicitly opted into direct-publish (e.g. automated security patch). The default-draft contract is the foundation of the safety hardening surface.\n\n⊗ Skip the post-create verify-isDraft gate -- the gate is the only reliable safety net against \"create call exited 0 but the release somehow landed as public\" variants (#724). If `task release` is invoked manually outside the canonical `scripts/release.py` flow, the operator MUST run `gh release view v<version> --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` BEFORE handing off to Phase 5.\n\n## Phase 5 — GitHub draft QA (optional; NOT the npm authority gate)\n\n! After `task release` exits 0, QA the **GitHub draft release** only. npm packages typically **already shipped** when the tag push in Phase 4 fired `.github/workflows/npm-publish.yml` (#1972, #2002). Phase 5 is NOT a \"user-only authority before going live\" gate for the release as a whole -- it is optional draft QA for GitHub assets, notes, and binaries.\n\n1. ! **Verify npm publish status FIRST (in parallel with draft inspection).** Run `gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 5` and confirm the tag run for `v<version>` is `completed`/`success`. If npm failed, surface immediately -- the GitHub draft QA is secondary to a red npm channel.\n2. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user\n3. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly\n4. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)\n\n### Happy path (default when npm succeeded and draft assets look correct)\n\n! When the npm workflow succeeded AND draft assets/notes pass inspection, **auto-proceed to Phase 6 Publish branch** -- run `task release:publish -- <version>` without a redundant human publish prompt (#2002). npm already shipped at tag push; waiting for a separate `publish` confirmation does not protect the npm channel.\n\n? **Operator override:** if the operator wants to hold the GitHub release in draft (e.g. embargo, last-minute notes edit), they MAY say `defer` before auto-publish runs.\n\n### Exception paths (operator-initiated)\n\n- `rollback` → proceed to Phase 6 (Rollback branch). **Reminder:** rollback unwinds the GitHub release only; npm packages already published at tag push are NOT retracted (#1972).\n- `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish -- <version>` or `task release:rollback -- <version>`.\n\n⊗ Treat Phase 5 as the npm publish-authority gate -- npm ships at tag push (Phase 4), not at `task release:publish`. A human `publish` prompt here is redundant when npm already succeeded and only delays flipping the GitHub draft to public.\n⊗ Skip npm workflow verification in Phase 5 and defer it entirely to post-publish Phase 7 -- npm status MUST be checked before or in parallel with the GitHub publish flip.\n\n## Phase 6 — Publish or rollback\n\n! Branch on the Phase 5 outcome. The happy path auto-enters the Publish branch when npm succeeded and draft QA passed (#2002).\n\n### Publish branch (happy path auto-run, or resumed after `defer`)\n\n```\ntask release:publish -- <version>\n```\n\nThe companion script flips `--draft=false`, then re-reads the release to verify `isDraft == false` actually flipped. State machine:\n- `draft` found → flip to public; verify; exit 0\n- already `published` → exit 0 no-op (idempotent re-runs are safe)\n- `not-found` → exit 1 (cannot publish a missing release)\n- gh-error → exit 1 with diagnostic\n\n! Wait for `task release:publish` to exit 0 before continuing. On the happy path this runs immediately after Phase 5 draft QA without a separate human publish prompt.\n\n### Rollback branch (user said `rollback`)\n\n```\ntask release:rollback -- <version>\n```\n\nThe state-aware unwind detects the post-release state and applies the matching tiered recovery. Time-windowed download-count guard:\n- release age `< 5 min` → threshold = 0 (rollback safe; nobody noticed yet)\n- release age `5-30 min` → threshold = max(`--allow-low-downloads`, 10) (filters bot fetches)\n- release age `> 30 min` → refuse without `--allow-data-loss`\n\nThree escape hatches (escalating warnings):\n- `--allow-low-downloads N` -- accept up to N downloads\n- `--allow-data-loss` -- accept any count (consumer impact)\n- `--force-strict-0` -- require exactly 0 regardless of release age\n\nRace-condition mitigation: `download_count` is double-read with a 5s sleep between reads; rollback only proceeds if both reads agree below threshold.\n\n! When the guard refuses, surface the recommendation to the user: rollback is risky on a released artifact with non-zero downloads. Prefer the **hot-fix path** (cut the next patch with a withdrawal note in `[Unreleased]/Changed` rather than deleting the broken release).\n\n! **`task release:rollback` does NOT retract npm (#1972, #2002).** Rollback unwinds GitHub release state (draft/public, tag, assets) only. npm packages published at tag push remain on the registry irrevocably. Recovery is forward-only: deprecate the bad version, move a dist-tag, or ship a patch release.\n\n## Phase 7 — Post-publish verification\n\n! Only enter Phase 7 if Phase 6 took the Publish branch (rollback branch ends here with the unwind log).\n\n1. ! **Re-verify npm publish landed (#1910, #1909, #2002).** Phase 5 checked workflow status before the GitHub publish flip; Phase 7 confirms registry truth AFTER `task release:publish`. For each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version` (expect `<version>`) and confirm provenance on the npm page. A green GitHub release with missing npm packages means consumers cannot `npm i -g @deftai/directive@<version>` -- escalate immediately. (Real-registry verification depends on #1909's credential; until then verify workflow-run status and flag credential gaps.)\n2. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)\n3. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment \"Closed by release v<version> (squash auto-close did not trigger)\"` (Layer 1, #167)\n4. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)\n5. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK\n6. ! For any umbrella / staying-OPEN issue (`Refs #N`) referenced in the release notes, run the Layer 3 reopen sweep from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1: any protected issue that auto-closed MUST be reopened with a comment citing #701\n\n⊗ Skip the post-publish verification. The closing-keyword false-positive (Layer 1 / Layer 2 / Layer 3) and the incremental-renderer-drift (#641, #614) are exactly the kind of issues that surface only AFTER a release is public.\n\n## Phase 8 — Slack announcement\n\n! Generate the canonical Slack release announcement and present it to the user for copy-paste, re-using the template from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 5.\n\nThe announcement block MUST include:\n\n```\n:rocket: *deft v<version>* -- <release title>\n\n*Summary*: <one-sentence description of the release scope>\n\n*Key Changes*:\n- <bullet per significant change, 3-5 items max>\n\n*Stats*: 1 release | ~<duration> elapsed | <N> commits since v<previous>\n*Release*: <GitHub release URL>\n```\n\n! Populate version from the freshly-published `gh release view v<version>` output. Populate release title from the CHANGELOG section heading (or the GitHub release title). Summarize key changes from the promoted `[Unreleased]` -> `[<version>]` CHANGELOG section (NOT raw commit messages). Populate stats from `git log v<previous>..v<version> --oneline | wc -l`.\n\n! Populate the `*Summary*:` slot VERBATIM from the operator-authored blockquote at the top of the CHANGELOG `[<version>]` section (the line beginning with `> ` immediately after the `## [<version>] - <date>` heading). The Phase 1 prompt + Phase 4 `--summary` flag exist precisely so this populate step is mechanical -- one canonical narrative authored once at Phase 1, propagated through Phase 4 promotion, and copy-pasted here without re-authoring. If the CHANGELOG section has no blockquote (operator skipped the Phase 1 prompt), generate a one-sentence summary from the `### Added` / `### Changed` bullets and surface to the operator that this is a regenerated narrative (NOT canonical) so they can decide whether to amend the CHANGELOG before publishing.\n\n! Present the block as a code-fenced snippet the user can copy directly. Do NOT post to Slack from inside this skill -- the user owns the actual broadcast.\n\n## Skill Completion\n\n! When Phase 8 completes (or when Phase 5 took the `defer` / `quit` path, or when Phase 6 completed the rollback branch), explicitly confirm skill exit:\n\n```\ndeft-directive-release complete -- exiting skill.\nNext: <one-line guidance>\n```\n\nWhere `<one-line guidance>` is one of:\n- \"release v<version> live -- monitor consumer reports for ~24h before cutting v<next>\"\n- \"release v<version> rolled back -- the underlying defect needs a hot-fix in the next CHANGELOG entry\"\n- \"release deferred -- resume by running `task release:publish -- <version>` (GitHub only; npm already shipped at tag push) or `task release:rollback -- <version>` (GitHub unwind only; npm is forward-recovery) when ready\"\n\n⊗ Exit silently without confirming completion or providing next-step guidance.\n\n## Anti-Patterns\n\n- ⊗ Run `task release` without a Phase 2 dry-run preview -- the dry-run is the only safe place to catch a bad version, malformed CHANGELOG, or wrong base branch\n- ⊗ Skip Phase 3 (e2e rehearsal) on the assumption that \"the dry-run is enough\" -- the e2e harness catches gh-CLI auth issues, repo permission gaps, and pipeline-shape regressions that the dry-run cannot detect\n- ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface\n- ⊗ Treat Phase 5 as the npm authority gate or require a redundant human `publish` prompt when npm already succeeded -- npm ships at tag push (#1972); Phase 5 is GitHub draft QA only\n- ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)\n- ⊗ Run `task release:rollback` against a release that has > 30 minutes of consumer-driven downloads without first weighing the hot-fix path -- a withdrawal note in the next patch is almost always less disruptive than deleting a public artifact\n- ⊗ Use `--allow-data-loss` without first reading the script docstring's hot-fix-path recommendation -- the flag is an explicit acknowledgment of consumer impact, not a default\n- ⊗ Skip the Phase 7 Layer 3 reopen sweep -- protected umbrellas can auto-close on a release-merge squash even when the release notes use `Refs #N` only\n- ⊗ Post the Phase 8 Slack announcement directly from this skill -- the user owns the broadcast; the skill only generates the template\n- ⊗ Hardcode `master` as the base branch -- delegate to the configured base branch from `task release --base-branch <branch>`\n- ⊗ Skip the post-create verify-isDraft gate (#724) -- a successful `gh release create` exit code does NOT prove the release actually landed in draft state; the 5-second poll-and-flip gate in `scripts/release.py` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `scripts/release.py` MUST run `gh release view --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` before handing off to Phase 5\n- ⊗ Manually rewrite the Phase 8 Slack `*Summary*:` line to deviate from the CHANGELOG `[<version>]` blockquote -- the canonical narrative is authored ONCE at Phase 1 via `--summary` and propagates verbatim across all three audiences (CHANGELOG / GitHub release body / Slack). Per-audience hand-edits create documentation drift that the deterministic `--summary` flow is designed to prevent. If the operator wants Slack-specific tone, fold it into the canonical Phase 1 wording before passing `--summary`, OR amend the CHANGELOG blockquote BEFORE Phase 8 so all three surfaces stay aligned\n- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut\n",
       "frontmatter_extra": null
     },
     {

package/scripts/doctor.py

@@ -131,6 +131,14 @@ VERSION = _resolve_version()
 # UV url constant (the _check_uv_available helper remains in run for other callers)
 UV_INSTALL_URL = "https://docs.astral.sh/uv/"
 
+# Post-freeze npm canonical path (#1997 / #2003 / #1912).
+CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest"
+NPM_PACKAGE_NAME = "@deftai/directive"
+UPGRADING_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md"
+GO_BRIDGE_RELEASES_URL = "https://github.com/deftai/directive/releases"
+NPM_MANAGED_SENTINEL_KEY = "managed_by"
+NPM_MANAGED_SENTINEL_VALUE = "npm"
+
 # --- Install-integrity checks (ported from retired framework_doctor.py #1336) ---
 # Symbols (EXIT_*, run_checks, main, CheckResult, DoctorResult + 4 checks + impl)
 # are inserted below in small batches. Once complete, _run_install_integrity_checks
@@ -765,6 +773,207 @@ def _check_install_path_consistency(project_root: Path, install_root: str | None
     )
 
 
+# ---------------------------------------------------------------------------
+# Legacy-layout + canonical-vendored npm signpost (#1912 / #1997)
+# ---------------------------------------------------------------------------
+
+
+def _gitmodules_references_framework(text: str) -> bool:
+    normalized = text.replace("\r\n", "\n").lower()
+    if "deftai/directive" in normalized:
+        return True
+    return bool(re.search(r"(^|\n)\s*path\s*=\s*\.?deft(/|\s|$)", normalized))
+
+
+def _detect_legacy_layout(project_root: Path) -> tuple[bool, str | None, str, list[str]]:
+    """Mirror packages/core/src/init-deposit/legacy-detect.ts heuristics."""
+    if (project_root / ".deft" / "core").is_dir():
+        return False, None, "", []
+    orphan = project_root / ".deft" / "VERSION"
+    if orphan.is_file():
+        return (
+            True,
+            "orphan-deft-version",
+            "Found an orphan .deft/VERSION manifest with no .deft/core/ directory -- "
+            "this is a pre-.deft/core/ layout the npm CLI does not migrate.",
+            [".deft/VERSION"],
+        )
+    deft_dir = project_root / "deft"
+    deft_markers = [
+        deft_dir / "VERSION",
+        deft_dir / "main.md",
+        deft_dir / "Taskfile.yml",
+    ]
+    deft_is_framework = deft_dir.is_dir() and (
+        any(p.is_file() for p in deft_markers) or (deft_dir / "skills").is_dir()
+    )
+    if deft_is_framework:
+        if (deft_dir / ".git").exists():
+            return (
+                True,
+                "git-clone-or-submodule",
+                "Found a deft/ framework directory backed by its own .git (clone or "
+                "git submodule) -- the npm CLI does not migrate a clone/submodule deposit.",
+                ["deft/", "deft/.git"],
+            )
+        return (
+            True,
+            "legacy-deft-prefixed",
+            "Found a legacy deft/-prefixed framework install -- the canonical layout "
+            "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
+            ["deft/"],
+        )
+    gitmodules = project_root / ".gitmodules"
+    if gitmodules.is_file():
+        text = _read_text_safe(gitmodules)
+        if text is not None and _gitmodules_references_framework(text):
+            return (
+                True,
+                "git-clone-or-submodule",
+                "Found a .gitmodules entry referencing the Deft framework -- a submodule "
+                "deposit the npm CLI does not migrate.",
+                [".gitmodules"],
+            )
+    agents_text = _read_text_safe(project_root / "AGENTS.md")
+    if agents_text is not None:
+        install_root = _parse_install_root_from_agents_md(agents_text)
+        if install_root == "deft":
+            return (
+                True,
+                "legacy-deft-prefixed",
+                "AGENTS.md declares the legacy deft/ install root -- the canonical layout "
+                "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
+                ["AGENTS.md (install root: deft)"],
+            )
+        if (
+            "<!-- deft:managed-section" in agents_text
+            and _extract_managed_section(agents_text) is None
+        ):
+            return (
+                True,
+                "pre-v0.27-sentinel-agents-md",
+                "AGENTS.md carries a pre-v0.27 sentinel-only managed-section (no v2/v3 "
+                "managed-section markers) -- run the Go bridge to migrate before the npm CLI.",
+                ["AGENTS.md (sentinel-only managed-section)"],
+            )
+    return False, None, "", []
+
+
+def _legacy_layout_signpost_line(kind: str | None, detail: str) -> str:
+    return (
+        f"Legacy Deft layout detected ({kind or 'unknown'}): {detail} "
+        "Run the frozen Go bridge installer to migrate to .deft/core/, then use the npm "
+        f"CLI (`npx @deftai/directive update`). See {UPGRADING_DOC_URL} "
+        f"(frozen bridge: {GO_BRIDGE_RELEASES_URL})."
+    )
+
+
+def _check_legacy_layout(project_root: Path) -> CheckResult:
+    legacy, kind, detail, evidence = _detect_legacy_layout(project_root)
+    if not legacy:
+        return CheckResult(
+            name="legacy-layout",
+            status="skip",
+            detail="No legacy Deft layout detected (canonical .deft/core/ or greenfield).",
+            data={"legacy_layout": False},
+        )
+    signpost = _legacy_layout_signpost_line(kind, detail)
+    return CheckResult(
+        name="legacy-layout",
+        status="fail",
+        detail=signpost,
+        data={
+            "legacy_layout": True,
+            "legacy_layout_kind": kind,
+            "evidence": evidence,
+            "upgrading_doc_url": UPGRADING_DOC_URL,
+            "go_bridge_releases_url": GO_BRIDGE_RELEASES_URL,
+        },
+    )
+
+
+def _detect_canonical_vendored_manifest(project_root: Path) -> Path | None:
+    canonical = project_root / ".deft" / "core" / "VERSION"
+    located = _locate_manifest(project_root, ".deft/core")
+    return located if located == canonical else None
+
+
+def _is_npm_managed(manifest: dict) -> bool:
+    return manifest.get(NPM_MANAGED_SENTINEL_KEY) == NPM_MANAGED_SENTINEL_VALUE
+
+
+def _check_canonical_vendored_npm_signpost(project_root: Path) -> CheckResult:
+    manifest_path = _detect_canonical_vendored_manifest(project_root)
+    if manifest_path is None:
+        return CheckResult(
+            name="canonical-vendored-npm-signpost",
+            status="skip",
+            detail="No canonical-vendored .deft/core/ deposit (nothing to signpost).",
+            data={"canonical_vendored": False},
+        )
+    text = _read_text_safe(manifest_path)
+    if text is None:
+        return CheckResult(
+            name="canonical-vendored-npm-signpost",
+            status="skip",
+            detail="Canonical-vendored manifest unreadable.",
+            data={"canonical_vendored": True},
+        )
+    manifest = _parse_manifest(text)
+    if _is_npm_managed(manifest):
+        return CheckResult(
+            name="canonical-vendored-npm-signpost",
+            status="skip",
+            detail="Deposit is already npm-managed (hybrid).",
+            data={"canonical_vendored": True, "npm_managed": True},
+        )
+    detail = (
+        "Canonical-vendored install (.deft/core/) is not yet npm-managed. "
+        "Post-freeze upgrades run via npm: install the engine with "
+        f"`{CANONICAL_UPGRADE_COMMAND}`, then run `directive migrate` "
+        f"to stamp provenance. See {UPGRADING_DOC_URL}."
+    )
+    return CheckResult(
+        name="canonical-vendored-npm-signpost",
+        status="fail",
+        detail=detail,
+        data={
+            "canonical_vendored": True,
+            "npm_managed": False,
+            "manifest_path": str(manifest_path),
+            "sentinel_key": NPM_MANAGED_SENTINEL_KEY,
+            "sentinel_value": NPM_MANAGED_SENTINEL_VALUE,
+            "upgrading_doc_url": UPGRADING_DOC_URL,
+        },
+    )
+
+
+def _run_local_signpost_checks(
+    project_root: Path,
+    *,
+    emit_warn,
+    add_finding,
+) -> None:
+    """Lightweight local signposts on throttle-skip (#1997)."""
+    if _running_inside_deft_repo(project_root):
+        return
+    for check in (
+        _check_legacy_layout(project_root),
+        _check_canonical_vendored_npm_signpost(project_root),
+    ):
+        if check.status == "skip":
+            continue
+        if check.status == "fail":
+            emit_warn(check.detail)
+            add_finding(
+                "warning",
+                check.detail,
+                check=check.name,
+                status=check.status,
+                data=check.data,
+            )
+
+
 # ---------------------------------------------------------------------------
 # Top-level driver (ported) -- provides run_checks for tests + internal use
 # ---------------------------------------------------------------------------
@@ -820,6 +1029,8 @@ def _run_checks_impl(project_root: Path) -> DoctorResult:
         # Still attempt the manifest agreement check (it can run without
         # AGENTS.md for the greenfield case).
         checks.append(_check_manifest_agreement(project_root, None))
+        checks.append(_check_legacy_layout(project_root))
+        checks.append(_check_canonical_vendored_npm_signpost(project_root))
         return DoctorResult(
             project_root=str(project_root),
             install_root=None,
@@ -832,6 +1043,8 @@ def _run_checks_impl(project_root: Path) -> DoctorResult:
     checks.append(_check_skill_paths_resolve(project_root, agents_md_text))
     checks.append(_check_manifest_agreement(project_root, install_root))
     checks.append(_check_install_path_consistency(project_root, install_root))
+    checks.append(_check_legacy_layout(project_root))
+    checks.append(_check_canonical_vendored_npm_signpost(project_root))
 
     return DoctorResult(
         project_root=str(project_root),
@@ -846,7 +1059,10 @@ def _derive_exit_code(checks: list[CheckResult], errors: list[str]) -> int:
     """Three-state exit code from check results + errors."""
     if errors or any(c.status == "error" for c in checks):
         return EXIT_CONFIG_ERROR
-    if any(c.status == "fail" for c in checks):
+    if any(
+        c.status == "fail" and c.name != "canonical-vendored-npm-signpost"
+        for c in checks
+    ):
         return EXIT_DRIFT
     return EXIT_CLEAN
 
@@ -1310,8 +1526,21 @@ def _render_doctor_status_line(decision) -> str:
     )
 
 
-def _emit_doctor_throttle_skip(decision, *, json_mode: bool) -> int:
+def _emit_doctor_throttle_skip(decision, *, json_mode: bool, project_root: Path) -> int:
     """Print the throttle-skip surface and return the gated exit code (#1308)."""
+    signpost_findings: list[dict] = []
+
+    def _add_signpost(severity: str, message: str, **extras: object) -> None:
+        entry: dict = {"severity": severity, "message": message}
+        entry.update(extras)
+        signpost_findings.append(entry)
+
+    _run_local_signpost_checks(
+        project_root,
+        emit_warn=warn if not json_mode else (lambda _m: None),
+        add_finding=_add_signpost,
+    )
+
     hint = (
         "run `deft doctor --full` to re-probe or address findings"
         if decision.dirty
@@ -1327,9 +1556,17 @@ def _emit_doctor_throttle_skip(decision, *, json_mode: bool) -> int:
             "next_eligible_at": _format_iso_z(decision.next_eligible_at),
             "hint": hint,
         }
-        print(json.dumps(payload, sort_keys=True))
+        if signpost_findings:
+            payload["signpost_findings"] = signpost_findings
+        print(json.dumps(payload, sort_keys=True, ensure_ascii=False))
     else:
         print(_render_doctor_status_line(decision))
+        signpost_warnings = sum(1 for f in signpost_findings if f.get("severity") == "warning")
+        if signpost_warnings:
+            warn(
+                f"Signpost advisory: {signpost_warnings} local layout / npm-migration "
+                "note(s) above (throttle-skipped full probe)."
+            )
     return 1 if decision.dirty else 0
 
 
@@ -1404,6 +1641,17 @@ def _run_install_integrity_checks(
         if status == "skip":
             emit_info(f"{name}: skip -- {detail}")
             continue
+        if name in ("legacy-layout", "canonical-vendored-npm-signpost") and status == "fail":
+            emit_warn(f"{name}: {detail}")
+            add_finding(
+                "warning",
+                detail or f"{name} {status}",
+                check=f"install-integrity:{name}",
+                install_check=name,
+                status=status,
+                data=entry.get("data", {}),
+            )
+            continue
         if status == "error":
             emit_error(f"{name}: error -- {detail}")
         else:
@@ -1488,6 +1736,43 @@ def _run_agents_md_freshness_check(
     add_finding("warning", message, check=check_name, status=state)
 
 
+def _parse_semver(version: str) -> tuple[int, ...]:
+    normalized = version.strip().lstrip("vV")
+    parts: list[int] = []
+    for segment in normalized.split("."):
+        try:
+            parts.append(int(segment.split("-")[0]))
+        except ValueError:
+            break
+    return tuple(parts) if parts else (0,)
+
+
+def _semver_less_than(left: str, right: str) -> bool:
+    return _parse_semver(left) < _parse_semver(right)
+
+
+def _npm_view_version() -> tuple[bool, str]:
+    try:
+        proc = subprocess.run(
+            ["npm", "view", NPM_PACKAGE_NAME, "version"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except Exception:  # noqa: BLE001
+        return False, ""
+    version = (proc.stdout or "").strip().splitlines()[0].strip() if proc.stdout else ""
+    return proc.returncode == 0 and bool(version), version
+
+
+def _manifest_version(ref: str, tag: str) -> str:
+    candidate = (tag or ref).strip().replace("refs/tags/", "")
+    normalized = candidate.lstrip("vV")
+    if not re.match(r"^\d+(?:\.\d+)*", normalized):
+        return ""
+    return normalized
+
+
 def _run_payload_staleness_check(
     project_root: Path,
     *,
@@ -1495,17 +1780,8 @@ def _run_payload_staleness_check(
     emit_info,
     add_finding,
 ) -> None:
-    """#1339 (Epic-5): Detect when the installed framework payload is behind its
-    manifest-recorded ref/sha. Reads the canonical <deftDir>/VERSION manifest
-    (single source of truth per #1062), resolves the corresponding remote SHA
-    via git ls-remote, and surfaces the canonical headless upgrade command
-    `deft-install --yes --upgrade --repo-root . --json` (#1409) when the shas
-    diverge. Skips gracefully inside the deft repo or when git / network /
-    manifest unavailable (non-fatal, best-effort).
-    """
+    """#1339 / #2003 / #2004: payload staleness with npm canonical upgrade path."""
     check_name = "payload-staleness"
-    # Self-contained "inside deft repo" probe (avoids dependency on private
-    # _running_inside_deft_repo helper that may be scoped inside cmd_doctor).
     try:
         agents = project_root / "AGENTS.md"
         is_deft = agents.exists() and (
@@ -1516,40 +1792,28 @@ def _run_payload_staleness_check(
             emit_info(f"{check_name}: skip -- running inside deft framework repo")
             add_finding(
                 "skip", "inside framework repo (no install manifest)",
-                check=check_name, status="skip",
+                check=check_name, status="skip", reason="not-applicable",
             )
             return
     except Exception:
         pass
 
-    # Locate a plausible manifest. Prefer the one next to the scripts/doctor.py
-    # we are running from (when invoked via the installed layout); fall back to
-    # common canonical/legacy locations under project_root.
     manifest_path = None
     try:
-        # When doctor.py lives at <deftDir>/scripts/doctor.py the manifest is at <deftDir>/VERSION
         candidate = get_script_dir().parent / "VERSION"
         if candidate.exists():
             manifest_path = candidate
     except Exception:
         pass
     if manifest_path is None:
-        # #1427: probe canonical-first via the shared helper so a
-        # webinstaller-vendored ``.deft/VERSION`` manifest is found too
-        # (the prior list probed only ``.deft/core/VERSION`` and legacy
-        # ``deft/VERSION``).
         manifest_path = _locate_manifest(project_root, None)
     if manifest_path is None:
-        # Legacy bare marker -- not a full manifest, but the last-resort
-        # provenance source for a pre-v0.28 install. Kept out of
-        # ``_locate_manifest`` because that helper returns VERSION-manifest
-        # paths only.
         legacy_marker = project_root / ".deft-version"
         if legacy_marker.exists():
             manifest_path = legacy_marker
     if manifest_path is None or not manifest_path.exists():
         emit_info(f"{check_name}: skip -- no install manifest found (pre-v0.28 or legacy state)")
-        add_finding("skip", "no manifest", check=check_name, status="skip")
+        add_finding("skip", "no manifest", check=check_name, status="skip", reason="not-applicable")
         return
 
     try:
@@ -1557,106 +1821,134 @@ def _run_payload_staleness_check(
         manifest = _parse_install_manifest(text)
     except Exception as exc:  # noqa: BLE001
         emit_info(f"{check_name}: skip -- could not read manifest: {exc}")
-        add_finding("skip", f"manifest unreadable: {exc}", check=check_name, status="skip")
+        add_finding(
+            "skip",
+            f"manifest unreadable: {exc}",
+            check=check_name,
+            status="skip",
+            reason="not-applicable",
+        )
         return
 
     installed_sha = manifest.get("sha", "").strip()
-    # Greptile P1 on #1384: do NOT fall back to "HEAD" when ref/tag are
-    # absent. `git ls-remote origin HEAD` returns the current remote
-    # default-branch tip, which almost certainly differs from the locally
-    # installed sha for development builds without a ref/tag pinned, and
-    # the check would then emit a permanent false-stale warning. Skip
-    # cleanly when the manifest does not declare a ref/tag.
     ref = (manifest.get("ref") or manifest.get("tag") or "").strip()
+    tag = (manifest.get("tag") or "").strip()
     if not installed_sha:
         emit_info(f"{check_name}: skip -- manifest has no sha (incomplete provenance)")
-        add_finding("skip", "no sha in manifest", check=check_name, status="skip")
+        add_finding(
+            "skip",
+            "no sha in manifest",
+            check=check_name,
+            status="skip",
+            reason="not-applicable",
+        )
         return
     if not ref:
         emit_info(
             f"{check_name}: skip -- manifest has no ref or tag (cannot resolve remote sha)"
         )
-        add_finding("skip", "no ref/tag in manifest", check=check_name, status="skip")
+        add_finding(
+            "skip",
+            "no ref/tag in manifest",
+            check=check_name,
+            status="skip",
+            reason="not-applicable",
+        )
         return
 
-    # Resolve current remote SHA for the ref (best effort, may be tag or branch).
-    # Use ls-remote to avoid needing a local fetch or modifying state.
+    deft_dir = manifest_path.parent
+    ls_remote_ok = False
+    remote_sha = ""
     try:
-        # Determine the deft dir from manifest location (parent of VERSION)
-        deft_dir = manifest_path.parent
-        # ls-remote origin <ref> (works for branches and tags)
         proc = subprocess.run(
             ["git", "-C", str(deft_dir), "ls-remote", "origin", ref],
             capture_output=True,
             text=True,
             timeout=15,
         )
-        if proc.returncode != 0:
-            emit_info(f"{check_name}: skip -- git ls-remote failed (no network or no origin)")
-            add_finding("skip", "ls-remote unavailable", check=check_name, status="skip")
-            return
-        # Output is "<sha>\t<refname>"
-        # For annotated tags, ls-remote returns TWO lines:
-        #   <tag-object-sha>	refs/tags/<tag>
-        #   <commit-sha>	refs/tags/<tag>^{}
-        # Prefer the peeled ^{} commit SHA when present (the one that matches
-        # what the installer recorded in the manifest). Fall back to first line.
-        # See Greptile P1 on #1384 (annotated-tag false-positive staleness).
-        remote_sha = ""
-        peeled_sha = ""
-        for line in proc.stdout.splitlines():
-            parts = line.strip().split()
-            if len(parts) >= 2:
-                refname = parts[1]
-                if refname.endswith("^{}"):
-                    peeled_sha = parts[0]
-                elif not remote_sha:
+        ls_remote_ok = proc.returncode == 0
+        if ls_remote_ok:
+            peeled_sha = ""
+            for line in proc.stdout.splitlines():
+                parts = line.strip().split()
+                if len(parts) >= 2:
+                    refname = parts[1]
+                    if refname.endswith("^{}"):
+                        peeled_sha = parts[0]
+                    elif not remote_sha:
+                        remote_sha = parts[0]
+            if peeled_sha:
+                remote_sha = peeled_sha
+            elif not remote_sha:
+                first_line = next((ln for ln in proc.stdout.splitlines() if ln.strip()), "")
+                parts = first_line.strip().split()
+                if parts:
                     remote_sha = parts[0]
-        if peeled_sha:
-            remote_sha = peeled_sha
-        elif not remote_sha:
-            # last-resort: first token of first line
-            first_line = next((ln for ln in proc.stdout.splitlines() if ln.strip()), "")
-            parts = first_line.strip().split()
-            if parts:
-                remote_sha = parts[0]
-        if not remote_sha:
-            emit_info(f"{check_name}: skip -- ls-remote produced no sha")
-            add_finding("skip", "no remote sha", check=check_name, status="skip")
+    except Exception:  # noqa: BLE001
+        ls_remote_ok = False
+
+    if ls_remote_ok and remote_sha:
+        if installed_sha == remote_sha:
+            emit_info(f"{check_name}: current (sha matches remote)")
             return
-    except Exception as exc:  # noqa: BLE001 -- network/git optional
-        emit_info(f"{check_name}: skip -- could not probe remote ({type(exc).__name__})")
-        add_finding("skip", f"remote probe failed: {exc}", check=check_name, status="skip")
+        msg = (
+            f"Framework payload is stale (installed sha {installed_sha[:8]}... "
+            f"behind remote {remote_sha[:8]}... for ref '{ref}'). "
+            f"Recommendation: run `{CANONICAL_UPGRADE_COMMAND}` from any shell with Node ≥ 20."
+        )
+        emit_warn(msg)
+        add_finding(
+            "warning",
+            msg,
+            check=check_name,
+            status="stale",
+            installed_sha=installed_sha,
+            remote_sha=remote_sha,
+            ref=ref,
+            suggestion=CANONICAL_UPGRADE_COMMAND,
+            resolver="git-ls-remote",
+        )
         return
 
-    if installed_sha == remote_sha:
-        # Current
-        emit_info(f"{check_name}: current (sha matches remote)")
+    npm_ok, npm_version = _npm_view_version()
+    installed_version = _manifest_version(ref, tag)
+    if npm_ok and installed_version:
+        if _semver_less_than(installed_version, npm_version):
+            msg = (
+                f"Framework payload is stale (installed v{installed_version} "
+                f"behind npm registry v{npm_version} for ref '{ref}'). "
+                f"Recommendation: run `{CANONICAL_UPGRADE_COMMAND}` from any shell with Node ≥ 20."
+            )
+            emit_warn(msg)
+            add_finding(
+                "warning",
+                msg,
+                check=check_name,
+                status="stale",
+                installed_version=installed_version,
+                remote_version=npm_version,
+                ref=ref,
+                suggestion=CANONICAL_UPGRADE_COMMAND,
+                resolver="npm-view",
+            )
+            return
+        emit_info(f"{check_name}: current (version matches npm registry)")
         return
 
-    # Stale! Emit the EXACT canonical headless upgrade command (#1409) so a
-    # normal consumer can copy-paste one line and end up with a fresh payload
-    # plus updated metadata -- not just the metadata-only `task upgrade` ack.
-    recommended_command = "deft-install --yes --upgrade --repo-root . --json"
-    msg = (
-        f"Framework payload is stale (installed sha {installed_sha[:8]}... "
-        f"behind remote {remote_sha[:8]}... for ref '{ref}'). "
-        f"Recommendation: run the canonical headless upgrader "
-        f"`{recommended_command}` from your project root to pull the latest "
-        f"payload (drop `--json` for human-readable output). On an installer "
-        f"binary predating the headless flags, download the latest deft-install "
-        f"from GitHub Releases first."
+    reason = (
+        "ls-remote produced no sha and npm registry fallback unavailable"
+        if ls_remote_ok
+        else "could not reach remote (git ls-remote / npm view both unavailable)"
     )
-    emit_warn(msg)
+    emit_info(f"{check_name}: skip -- {reason}")
+    unverified_msg = f"payload currency UNVERIFIED — {reason}"
+    emit_warn(unverified_msg)
     add_finding(
         "warning",
-        msg,
+        unverified_msg,
         check=check_name,
-        status="stale",
-        installed_sha=installed_sha,
-        remote_sha=remote_sha,
-        ref=ref,
-        suggestion=recommended_command,
+        status="unverified",
+        reason=reason,
     )
 
 
@@ -1791,7 +2083,9 @@ def cmd_doctor(args: list[str]):
     if not full_mode:
         decision = _evaluate_doctor_throttle(project_root)
         if decision is not None and decision.skip:
-            return _emit_doctor_throttle_skip(decision, json_mode=json_mode)
+            return _emit_doctor_throttle_skip(
+                decision, json_mode=json_mode, project_root=project_root
+            )
 
     # Findings are the single source of truth for the summary, the
     # JSON payload, and the exit code (#1303 review #1 / #4). Replaces
@@ -2132,7 +2426,7 @@ def cmd_doctor(args: list[str]):
             },
             "project_root": str(project_root),
         }
-        print(json.dumps(payload, sort_keys=True))
+        print(json.dumps(payload, sort_keys=True, ensure_ascii=False))
         return exit_code
 
     print()
@@ -2242,7 +2536,7 @@ def main(argv: list[str] | None = None) -> int:
     project_root = Path(args.project_root).resolve()
     result = _run_checks_impl(project_root)
     if args.json:
-        print(json.dumps(result.to_dict(), sort_keys=True))
+        print(json.dumps(result.to_dict(), sort_keys=True, ensure_ascii=False))
     else:
         if not (args.quiet and result.exit_code == EXIT_CLEAN):
             print(_format_text_report(result))

package/skills/deft-directive-release/SKILL.md

@@ -4,9 +4,10 @@ description: >-
   Cut a v0.X.Y release of the deft framework safely. Use when the user says
   "release", "cut release", "v0.X.Y", or "publish release" -- to walk an
   8-phase workflow that pre-flights, runs an end-to-end rehearsal against a
-  temp repo, lands a draft on the real repo, gates on user review, then
-  publishes or rolls back. Re-uses the deft-directive-swarm Phase 6 Step 5
-  Slack announcement template.
+  temp repo, lands a draft GitHub release (npm ships irrevocably at tag push),
+  optionally QA's draft assets, then publishes the GitHub release or rolls
+  back. Re-uses the deft-directive-swarm Phase 6 Step 5 Slack announcement
+  template.
 ---
 <!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
 <!-- Purpose: rendered skill -->
@@ -60,7 +61,7 @@ The release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess
 
 ## Deterministic Questions Contract
 
-! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 `publish`/`rollback`/`defer`) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.
+! Every numbered-menu prompt rendered in this skill (Phase 1 version-bump magnitude check, Phase 2 dry-run review `yes`/`back`/`quit`, Phase 5 optional `defer`/`rollback`/`Discuss` (happy path auto-publishes after draft QA)) MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): the final two numbered options MUST be `Discuss` and `Back`, in that order. Existing `back`/`quit` options remain valid; this contract simply adds `Discuss` as a peer alongside `Back`. The Discuss-pause semantic is documented verbatim in the contract -- implicit resumption is forbidden.
 
 ## When to Use
 
@@ -80,7 +81,8 @@ The release pipeline's Step 9/10/11 git mutations carry the bypass in subprocess
 6. ! **Run `task reconcile:issues -- --apply-lifecycle-fixes` to clear any closed-issue / non-completed-folder vBRIEFs before invoking `task release`** (#734). The release pipeline carries the deterministic gate at Step 3 (`scripts/release.py::check_vbrief_lifecycle_sync`, refuses with `EXIT_VIOLATION` on any Section (c) mismatch), but Phase 1 is the operator's first-line defence -- running the apply-mode flag here is the canonical clean path; `--allow-vbrief-drift` on the pipeline exists only as the explicit-acknowledgment escape hatch (analogous to `--allow-dirty`). The recurrence record is the v0.21.0 cut, which surfaced 13 stranded vBRIEFs (8 cycle-relevant + 5 historical residue) post-publish; the gate now blocks that drift before any irreversible action
 7. ! **Verify the proposed `v<version>` tag is not already in use locally, on origin, or as a published GitHub release** (#784). The release pipeline carries the deterministic gate at Step 4 (`scripts/release.py::check_tag_available`, refuses with `EXIT_VIOLATION` before any state mutation -- CHANGELOG promotion, ROADMAP refresh, build, commit), but Phase 1 is the operator's first-line defence. Quickly probe with `git tag -l v<version>` (local), `git ls-remote --tags origin refs/tags/v<version>` (remote), and `gh release view v<version> --repo <owner>/<repo>` (release-only, where `gh release view` exits 0 only when the release exists). The recurrence record is the v0.22.0 → v0.23.0 release attempt on 2026-05-01: the operator typed `0.22.0` (the prior release from 12 hours earlier) and the legacy pipeline ran 8 steps before failing at `git tag` -- leaving a wrong-version local commit + `dist/deft-0.22.0.zip` orphan + manual `git reset --hard` recovery. The new pre-flight gate blocks that mode before any irreversible action
 8. ! **Verify the npm credential path is configured before cutting the tag** (#1910, #1909). A `v*` tag now auto-triggers `.github/workflows/npm-publish.yml`, which publishes the four `@deftai/directive*` packages with `npm publish --provenance`. Confirm the publish path can authenticate: either the `NPM_TOKEN` repo secret is present (`gh secret list --repo <owner>/<repo>` shows `NPM_TOKEN`) OR an npm OIDC trusted publisher is configured for the `@deftai/directive*` packages. If neither is in place, WARN loudly that the tag will fire a publish job that fails (red X on the tag, no packages) -- the operator may still proceed for a GitHub-only release, but the npm channel will not land until #1909's credential is provisioned. Cross-reference #1909.
-9. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream
+9. ! **Disclose npm irrevocability before any tag push (#1972, #2002).** A `v<version>` tag push is the **real npm publish gate** -- NOT Phase 5 or `task release:publish`. Tag push fires `.github/workflows/npm-publish.yml` in a separate workflow that is NOT draft-gated; npm packages ship immediately and **cannot be retracted** (`npm unpublish` is forbidden). Recovery is forward-only: deprecate, dist-tag, or ship a patch. The operator's explicit `yes` in Phase 2 (dry-run) and the decision to invoke `task release` in Phase 4 are the last human gates before npm goes live. Phase 5 only controls GitHub release visibility (draft → public); it does NOT gate npm.
+10. ~ Ask the operator for an optional one-line release **summary** (recommended 80-160 chars; can be skipped). The summary is the canonical narrative for THIS release across three audiences: (a) injected as a Markdown blockquote at the top of the promoted `CHANGELOG.md [<version>]` section, (b) auto-flowed into the GitHub release body via the existing `_section_for_version` pickup, and (c) populated VERBATIM into the Phase 8 Slack `*Summary*:` slot. Capture the wording once here; do NOT regenerate per-audience downstream
 
 ⊗ Skip the version-bump magnitude check -- a patch release that ships breaking changes is the kind of regression that Repair Authority [AXIOM] (#709) is designed to prevent.
 
@@ -100,7 +102,7 @@ task release -- <version> --dry-run --skip-tag --skip-release --summary "<text>"
 
 The dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline step (Step 13 is the post-create verify-isDraft gate added by #724; Step 4 is the tag-availability pre-flight gate added by #784). Step 6 (CHANGELOG promotion) surfaces whether a summary was supplied (truncated to ~60 chars in the preview) so the operator can validate the wording before any file is written. Capture the output and present it to the user, then wait for explicit confirmation before continuing.
 
-! Wait for explicit user confirmation: `yes` / `back` / `quit`.
+! Wait for explicit user confirmation: `yes` / `back` / `quit`. Remind the operator that Phase 4's tag push will irrevocably publish npm (#1972) -- this `yes` is the last safe abort before that channel opens.
 - `yes` (or `confirmed` / `approve`) → proceed to Phase 3
 - `back` → return to Phase 1 for re-validation (e.g. user wants to amend the version or `[Unreleased]` content)
 - `quit` → abort the workflow cleanly; no state changes
@@ -123,10 +125,12 @@ The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke
 
 ! **`task release:e2e` now also rehearses the npm publish (#1910).** Unless `--skip-npm` is passed (or `npm` is absent from PATH, which soft-skips), the rehearsal runs `npm publish --dry-run --access public` for all four `@deftai/directive*` packages against the throwaway clone in dependency order (types -> core -> content -> cli), after `pnpm install` + `pnpm -w run build` and a version-alignment pass. This catches a broken `files` allowlist, a version-drift bug, or a dependency-order error BEFORE the real `v*` tag fires the publish workflow -- without touching the real registry. The install+build exceeds the <90s fast budget, so pass `task release:e2e -- --skip-npm` when you only need the GitHub-pipeline shape check.
 
-! **Tag -> npm coupling + version invariant (#1910).** A `v<version>` tag is now a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. A red npm job on a green GitHub release means the npm channel did not ship (see Phase 7).
+! **Tag -> npm coupling + irrevocability (#1910, #1972, #2002).** A `v<version>` tag is a TWO-channel action: the GitHub release (this skill's pipeline) AND `.github/workflows/npm-publish.yml`, which runs in a SEPARATE workflow that does NOT block the GitHub release and is NOT draft-gated. The npm workflow derives the published version from the tag (`${GITHUB_REF_NAME#v}`); this skill owns the version chosen in Phase 1. These MUST stay consistent -- the tag you cut IS the npm version that ships; there is no separate npm version bump. **npm publish is irrevocable** (#1972): once the tag fires, packages are live on npm and cannot be unpulled; `task release:rollback` does NOT retract npm (forward-only recovery). A red npm job on a green GitHub release means the npm channel did not ship (verify in Phase 5/7).
 
 ## Phase 4 — Production draft
 
+! **Last human gate before npm (#1972, #2002).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms.
+
 ! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`). If Phase 1 collected an operator summary, pass `--summary "<text>"` so the production cut writes the same blockquote the dry-run previewed.
 
 ```
@@ -145,25 +149,34 @@ Per #716 default-draft hardening, this lands the release as a `--draft` on the r
 
 ⊗ Skip the post-create verify-isDraft gate -- the gate is the only reliable safety net against "create call exited 0 but the release somehow landed as public" variants (#724). If `task release` is invoked manually outside the canonical `scripts/release.py` flow, the operator MUST run `gh release view v<version> --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` BEFORE handing off to Phase 5.
 
-## Phase 5 — Draft review gate (user-only authority)
+## Phase 5 — GitHub draft QA (optional; NOT the npm authority gate)
+
+! After `task release` exits 0, QA the **GitHub draft release** only. npm packages typically **already shipped** when the tag push in Phase 4 fired `.github/workflows/npm-publish.yml` (#1972, #2002). Phase 5 is NOT a "user-only authority before going live" gate for the release as a whole -- it is optional draft QA for GitHub assets, notes, and binaries.
+
+1. ! **Verify npm publish status FIRST (in parallel with draft inspection).** Run `gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 5` and confirm the tag run for `v<version>` is `completed`/`success`. If npm failed, surface immediately -- the GitHub draft QA is secondary to a red npm channel.
+2. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user
+3. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly
+4. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)
+
+### Happy path (default when npm succeeded and draft assets look correct)
 
-! After `task release` exits 0, present the draft release for user review.
+! When the npm workflow succeeded AND draft assets/notes pass inspection, **auto-proceed to Phase 6 Publish branch** -- run `task release:publish -- <version>` without a redundant human publish prompt (#2002). npm already shipped at tag push; waiting for a separate `publish` confirmation does not protect the npm channel.
 
-1. ! Run `gh release view v<version> --json url,name,body,assets,isDraft --repo <owner>/<repo>` and present the output to the user
-2. ! Surface the asset list (size + filename) so the user can verify binaries uploaded correctly
-3. ! Surface the auto-generated release notes (or the CHANGELOG section that was promoted into the release body)
-4. ! Wait for explicit user confirmation:
-   - `publish` (or `yes` / `confirmed` / `approve`) → proceed to Phase 6 (Publish branch)
-   - `rollback` → proceed to Phase 6 (Rollback branch)
-   - `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish` or `task release:rollback`. Do NOT auto-merge; do NOT silently wait
+? **Operator override:** if the operator wants to hold the GitHub release in draft (e.g. embargo, last-minute notes edit), they MAY say `defer` before auto-publish runs.
 
-⊗ Bypass the user-only authority gate. Even under time pressure or long-context, the release MUST receive an explicit `publish` / `rollback` / `defer` decision from the user. This mirrors the Phase 5→6 gate in `skills/deft-directive-swarm/SKILL.md`.
+### Exception paths (operator-initiated)
+
+- `rollback` → proceed to Phase 6 (Rollback branch). **Reminder:** rollback unwinds the GitHub release only; npm packages already published at tag push are NOT retracted (#1972).
+- `defer` → halt and exit. Surface the draft URL so the operator can return later with `task release:publish -- <version>` or `task release:rollback -- <version>`.
+
+⊗ Treat Phase 5 as the npm publish-authority gate -- npm ships at tag push (Phase 4), not at `task release:publish`. A human `publish` prompt here is redundant when npm already succeeded and only delays flipping the GitHub draft to public.
+⊗ Skip npm workflow verification in Phase 5 and defer it entirely to post-publish Phase 7 -- npm status MUST be checked before or in parallel with the GitHub publish flip.
 
 ## Phase 6 — Publish or rollback
 
-! Branch on the user's Phase 5 decision.
+! Branch on the Phase 5 outcome. The happy path auto-enters the Publish branch when npm succeeded and draft QA passed (#2002).
 
-### Publish branch (user said `publish`)
+### Publish branch (happy path auto-run, or resumed after `defer`)
 
 ```
 task release:publish -- <version>
@@ -175,7 +188,7 @@ The companion script flips `--draft=false`, then re-reads the release to verify
 - `not-found` → exit 1 (cannot publish a missing release)
 - gh-error → exit 1 with diagnostic
 
-! Wait for `task release:publish` to exit 0 before continuing.
+! Wait for `task release:publish` to exit 0 before continuing. On the happy path this runs immediately after Phase 5 draft QA without a separate human publish prompt.
 
 ### Rollback branch (user said `rollback`)
 
@@ -197,15 +210,17 @@ Race-condition mitigation: `download_count` is double-read with a 5s sleep betwe
 
 ! When the guard refuses, surface the recommendation to the user: rollback is risky on a released artifact with non-zero downloads. Prefer the **hot-fix path** (cut the next patch with a withdrawal note in `[Unreleased]/Changed` rather than deleting the broken release).
 
+! **`task release:rollback` does NOT retract npm (#1972, #2002).** Rollback unwinds GitHub release state (draft/public, tag, assets) only. npm packages published at tag push remain on the registry irrevocably. Recovery is forward-only: deprecate the bad version, move a dist-tag, or ship a patch release.
+
 ## Phase 7 — Post-publish verification
 
 ! Only enter Phase 7 if Phase 6 took the Publish branch (rollback branch ends here with the unwind log).
 
-1. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)
-2. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment "Closed by release v<version> (squash auto-close did not trigger)"` (Layer 1, #167)
-3. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)
-4. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK
-5. ! **Verify the npm publish landed (#1910, #1909).** The `v<version>` tag fired `.github/workflows/npm-publish.yml` in parallel with this skill's pipeline. Confirm the job succeeded (`gh run list --workflow=npm-publish.yml --repo <owner>/<repo> --limit 1` shows the tag run as `completed`/`success`) AND that all four packages published at the new version with provenance: for each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version` (expect it to echo `<version>`) and confirm the provenance attestation on the package's npm page. Surface a missing package or a failed job the same way the closing-keyword / renderer-drift checks above surface failures -- a green GitHub release with a red npm job means the npm channel did NOT ship. (Real-registry verification depends on #1909's credential being provisioned; until then this step verifies the workflow-run status and flags the credential gap.)
+1. ! **Re-verify npm publish landed (#1910, #1909, #2002).** Phase 5 checked workflow status before the GitHub publish flip; Phase 7 confirms registry truth AFTER `task release:publish`. For each of `@deftai/directive-types`, `@deftai/directive-core`, `@deftai/directive-content`, and `@deftai/directive`, run `npm view <pkg>@<version> version` (expect `<version>`) and confirm provenance on the npm page. A green GitHub release with missing npm packages means consumers cannot `npm i -g @deftai/directive@<version>` -- escalate immediately. (Real-registry verification depends on #1909's credential; until then verify workflow-run status and flag credential gaps.)
+2. ! Verify GitHub auto-closed the discrete-task issue(s) referenced via `Closes #N` in the release notes (mirrors `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2)
+3. ! Run `gh issue view <N> --json state --jq .state` for each closed issue. If any didn't auto-close, manually close with `gh issue close <N> --comment "Closed by release v<version> (squash auto-close did not trigger)"` (Layer 1, #167)
+4. ! Verify ROADMAP.md correctness via `task roadmap:render` (the release pipeline already invoked this; Phase 7 is the second-pass sanity check)
+5. ! Verify binaries are downloadable from the public release URL: `gh release view v<version> --json assets --jq '.assets[].url'` and curl one to confirm 200 OK
 6. ! For any umbrella / staying-OPEN issue (`Refs #N`) referenced in the release notes, run the Layer 3 reopen sweep from `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1: any protected issue that auto-closed MUST be reopened with a comment citing #701
 
 ⊗ Skip the post-publish verification. The closing-keyword false-positive (Layer 1 / Layer 2 / Layer 3) and the incremental-renderer-drift (#641, #614) are exactly the kind of issues that surface only AFTER a release is public.
@@ -246,7 +261,7 @@ Next: <one-line guidance>
 Where `<one-line guidance>` is one of:
 - "release v<version> live -- monitor consumer reports for ~24h before cutting v<next>"
 - "release v<version> rolled back -- the underlying defect needs a hot-fix in the next CHANGELOG entry"
-- "release deferred -- resume by running `task release:publish -- <version>` (or `task release:rollback -- <version>`) when ready"
+- "release deferred -- resume by running `task release:publish -- <version>` (GitHub only; npm already shipped at tag push) or `task release:rollback -- <version>` (GitHub unwind only; npm is forward-recovery) when ready"
 
 ⊗ Exit silently without confirming completion or providing next-step guidance.
 
@@ -255,7 +270,8 @@ Where `<one-line guidance>` is one of:
 - ⊗ Run `task release` without a Phase 2 dry-run preview -- the dry-run is the only safe place to catch a bad version, malformed CHANGELOG, or wrong base branch
 - ⊗ Skip Phase 3 (e2e rehearsal) on the assumption that "the dry-run is enough" -- the e2e harness catches gh-CLI auth issues, repo permission gaps, and pipeline-shape regressions that the dry-run cannot detect
 - ⊗ Pass `--no-draft` to `task release` without explicit operator opt-in -- the default-draft contract is the foundation of the safety hardening surface
-- ⊗ Auto-publish a draft without the Phase 5 user-only authority gate -- even under time pressure or long-context, the release MUST receive an explicit `publish` / `rollback` / `defer` decision
+- ⊗ Treat Phase 5 as the npm authority gate or require a redundant human `publish` prompt when npm already succeeded -- npm ships at tag push (#1972); Phase 5 is GitHub draft QA only
+- ⊗ Expect `task release:rollback` to retract npm packages -- rollback is GitHub-only; npm recovery is forward-only (deprecate / dist-tag / patch)
 - ⊗ Run `task release:rollback` against a release that has > 30 minutes of consumer-driven downloads without first weighing the hot-fix path -- a withdrawal note in the next patch is almost always less disruptive than deleting a public artifact
 - ⊗ Use `--allow-data-loss` without first reading the script docstring's hot-fix-path recommendation -- the flag is an explicit acknowledgment of consumer impact, not a default
 - ⊗ Skip the Phase 7 Layer 3 reopen sweep -- protected umbrellas can auto-close on a release-merge squash even when the release notes use `Refs #N` only