musubix3 0.1.20 → 0.1.21

package/.github/plugin/marketplace.json

@@ -3,13 +3,13 @@
   "owner": { "name": "nahisaho" },
   "metadata": {
     "description": "GitHub Copilot CLI specification-driven development skills",
-    "version": "0.1.20"
+    "version": "0.1.21"
   },
   "plugins": [
     {
       "name": "musubix3",
       "source": ".",
-      "version": "0.1.20",
+      "version": "0.1.21",
       "description": "Evidence-driven SDD without duplicating native Copilot capabilities."
     }
   ]

package/.github/skills/sdd-change/SKILL.md

@@ -7,68 +7,51 @@ description: "Use as the MANDATORY first Skill for requests to develop, build, c
  * @implements REQ-SESSION-SCOPED-DEVELOPMENT-001 REQ-SESSION-SCOPED-DEVELOPMENT-002
  * @design DES-SESSION-SCOPED-DEVELOPMENT-001
  */
+/* @id CODE-SDD-CHANGE-OPS-IMPROVEMENTS-001
+ * @implements REQ-SDD-CHANGE-OPS-IMPROVEMENTS-001 REQ-SDD-CHANGE-OPS-IMPROVEMENTS-002 REQ-SDD-CHANGE-OPS-IMPROVEMENTS-003 REQ-SDD-CHANGE-OPS-IMPROVEMENTS-004 REQ-SDD-CHANGE-OPS-IMPROVEMENTS-005 REQ-SDD-CHANGE-OPS-IMPROVEMENTS-006
+ * @design DES-SDD-CHANGE-OPS-IMPROVEMENTS-001 DES-SDD-CHANGE-OPS-IMPROVEMENTS-002 DES-SDD-CHANGE-OPS-IMPROVEMENTS-003
+ */
 Mandatory entrypoint: every new natural-language development request is a new change, even in an existing Copilot session; never reuse prior requirements, approvals, TDD, or change evidence unless the user explicitly names the existing change ID and asks to continue it. never start implementation before validating requirements/design; skip only for verified approved artifacts of that explicitly continued change.
 Never infer approval; show `approval prepare <stage>` and record only its reviewed hash with `approval record <stage> --approver <name> --artifact-sha256 <hash> --confirm`.
-Whenever an AI deliverable is documentation (requirements, design, ADRs, the CHANGE document, or release/quality evidence), run Copilot's native `rubber-duck` review agent on it before that phase's human approval, fixing every issue and re-reviewing until none remain.
+Whenever an AI deliverable is documentation (requirements, design, ADRs, the CHANGE document, or release/quality evidence), run Copilot's native `rubber-duck` review agent on it before that phase's human approval. Run automated validators first, build a quick traceability/self-check matrix, review related requirements/design/ADR artifacts together in one pass when appropriate, scope the request to logic/contradiction/acceptance/consistency issues, pre-state known constraints/decisions, and embed the stop condition in the request itself. Use at most 3 rounds total for one artifact set: round 1 may review the full artifact set, rounds 2-3 must be diff-only, and each round's findings must be fixed in one batch before re-review. If blocking findings remain after round 3, summarize them, ask a human whether to continue with fixes or proceed as-is, and stop instead of looping indefinitely.
 Follow the user's input language. Use native Copilot planning, editing, research, review, security review and subagents.
 Record exactly one final invocation outcome with `npx musubix3 workflow-record sdd-change complete --status <status>`; `change-record` separately proves phases.
-Run `workflow-sanitize <copilot.jsonl> <safe.jsonl>` before review, then
-`workflow-verify <safe.jsonl>`; it validates source-order lifecycles without
-assuming globally monotonic clocks unless `maxEventSkewMs` is explicitly set.
+Run `workflow-sanitize <copilot.jsonl> <safe.jsonl>` before review, then `workflow-verify <safe.jsonl>`; it validates source-order lifecycles without assuming globally monotonic clocks unless `maxEventSkewMs` is explicitly set.
 Baseline-protect transcript byte limits; never truncate/edit to bypass them.
 For strict evidence, bind an expected UUID; GitHub origin needs strict OIDC.
 Never record multiple declarations per invocation; use only the configured CLI.
 For broad work, use short stages: initialize, requirements, requirements approval, design, design approval, real Red, Green, integration, trace/formal, quality, release approval. Report each result before the next prompt.
 For a staged change, run `change-record <CHANGE-ID> <phase> --requirement <REQ-ID...>` after each phase in this exact order: `impact`, `requirements`, `design`, `red`, `implementation`, `green`, `quality`.
 `impact`/`requirements`/`design`/`quality` always use the full requirement ID set; `red`/`implementation`/`green` may instead use a non-empty subset as an independent per-requirement batch for an interleaved Red-Implementation-Green loop; `quality` still needs full cumulative Green coverage.
-List only requirements whose statement/acceptance changes, classify each, and
-document other impacts separately. Each needs fresh Red and Green.
+After Quality, record a new corrective subset Red/Implementation/Green batch and invoke full-set `quality` again; schema v2 retains prior checkpoints in `qualityHistory`, and `change quality-recover` recovers interruptions.
+Refresh errors are `CHANGE_QUALITY_REFRESH_LINEAGE_INVALID`, `CHANGE_QUALITY_REFRESH_GREEN_MISSING`, `CHANGE_QUALITY_REFRESH_NOT_NEEDED`, and `CHANGE_QUALITY_REFRESH_RECOVERY_REQUIRED`; an already-used corrective subset requires a new reviewed staged change.
+List only requirements whose statement/acceptance changes, classify each, and document other impacts separately. Each needs fresh Red and Green.
 The CHANGE document must contain `Requirements:` with exactly those normative IDs.
 Persisted monotonic order, not wall-clock time, proves these phase boundaries.
 ## 1. Classify and inspect / 分類と事前確認
-1. Classify the request as a feature, behavior change, defect correction,
-   refactoring, or documentation-only change. For a new program/feature, create
-   a fresh feature slug and CHANGE artifact; prior session context is not approval.
+1. Classify the request as a feature, behavior change, defect correction, refactoring, or documentation-only change. For a new program/feature, create a fresh feature slug and CHANGE artifact; prior session context is not approval. For documentation-only changes, still run impact/requirements/design/quality evidence and record the reason when TDD is omitted by policy.
 2. Read the constitution and relevant requirements, designs, ADRs, code and tests, but treat prior-session artifacts as historical context unless continuation is explicit.
 3. Run `trace impact`; when code exists run `graph index` and `graph impact`.
-4. Separate confirmed intent, assumptions and open questions. When material context is missing, ask exactly one highest-priority question, wait, then repeat; never batch questions or finalize requirements, design or code while blockers remain.
+4. In long-lived or parallel worktrees, periodically run `git fetch`, inspect both `git log origin/main..HEAD` and `git log HEAD..origin/main` (or an equivalent symmetric divergence check), refresh against `origin/main` before release time, and rebase onto `origin/main` especially around other in-flight changes merging to `main`, so evidence/hash-chain conflicts are corrected early instead of at release time.
+5. Separate confirmed intent, assumptions and open questions. When material context is missing, ask exactly one highest-priority question, wait, then repeat; never batch questions or finalize requirements, design or code while blockers remain.
 ## 2. Update specifications first / 仕様を先に更新
-1. For new or changed observable behavior, add or revise EARS requirements and
-   measurable acceptance criteria before implementation. Preserve stable IDs
-   when meaning remains the same; create new IDs when obligations are distinct.
-2. For a bug where implementation violates an existing requirement, keep that
-   requirement and record that no specification change is needed. Never rewrite
-   a requirement merely to make incorrect behavior appear compliant.
-3. Run requirements and constitution validation; stop on invalid artifacts
-   instead of continuing with unapproved assumptions.
-4. Run a `rubber-duck` review (Copilot's native review agent) of `requirements.md`, fixing every issue and re-reviewing until none remain, then stop for explicit current `requirements` approval before design. An edit to `requirements.md` re-opens approval and requires re-review.
-5. Update design responsibilities/interfaces/constraints/links and ADRs, run design validation, then run the same rubber-duck review/fix loop on `design.md`/ADRs before stopping for explicit current `design` approval before Red/implementation. An edit re-opens approval and requires re-review.
+1. For new or changed observable behavior, add or revise EARS requirements and measurable acceptance criteria before implementation. Preserve stable IDs when meaning remains the same; create new IDs when obligations are distinct.
+2. For a bug where implementation violates an existing requirement, keep that requirement and record that no specification change is needed. Never rewrite a requirement merely to make incorrect behavior appear compliant.
+3. Run requirements and constitution validation; stop on invalid artifacts instead of continuing with unapproved assumptions.
+4. Before `requirements` approval, run a bounded `rubber-duck` review of `requirements.md`: validate first, build a REQ↔acceptance self-check matrix, include related design/ADR context in the same review when cross-document consistency matters, scope the prompt to logic/contradiction/acceptance/consistency issues (not style), pre-state known constraints/decisions, state the round number and "stop after round 3 and summarize unresolved findings" condition in the request itself, fix all findings from a round in one batch, and use only diff-only follow-up reviews for rounds 2-3. After round 3, stop for a human continue-vs-proceed decision instead of auto-retrying. An edit to `requirements.md` re-opens approval and requires this bounded review loop again.
+5. Update design responsibilities/interfaces/constraints/links and ADRs, run design validation, then apply the same bounded rubber-duck protocol to `design.md`/ADRs before explicit current `design` approval: validate first, build a REQ↔DES↔ADR traceability/self-check table, review related artifacts together when appropriate, scope the prompt to logic/contradiction/acceptance/consistency issues, pre-state known constraints/decisions, batch-fix each round, embed the capped stop condition in the request, use one full-artifact pass plus diff-only rounds 2-3, and stop after round 3 for human decision if blocking findings remain. An edit re-opens approval and requires the bounded review loop again.
 ## 3. Implement and prove coverage / 実装と網羅性
-1. For observable behavior changes and defect fixes, write the smallest meaningful
-   test first. Include its `TEST-*` ID in the test name/output and link it to the
-   requirement with `@verifies`. Configure the command's `tddArgs` with
-   `{testId}` or `{testPath}` so only that test is selected. Configure
-   `tddReport` and make the runner write a fresh `musubix-json` result containing
-   exactly the target test with `failed` or `passed` status, or select a built-in
-   test adapter. For deterministic performance requirements, use a passing
-   instrumented `operations` report with command/report/run/exit provenance;
-   native adapters cannot emit app counters, and elapsed time is insufficient.
-2. Run `npx musubix3 tdd red <TEST-ID> --requirement <REQ-ID> --command <name>`.
+1. For observable behavior changes and defect fixes, write the smallest meaningful test first. Include its `TEST-*` ID in the test name/output and link it to the requirement with `@verifies`. Configure the command's `tddArgs` with `{testId}` or `{testPath}` so only that test is selected. Configure `tddReport` and make the runner write a fresh `musubix-json` result containing exactly the target test with `failed` or `passed` status, or select a built-in test adapter. For deterministic performance requirements, use a passing instrumented `operations` report with command/report/run/exit provenance; native adapters cannot emit app counters, and elapsed time is insufficient.
+2. **Strict order checklist for every requirement batch (never reorder or batch ahead):** `tdd red` → `change-record red` → implementation edit → `change-record implementation` → `tdd green` → `change-record green`. Treat this as the highest-priority ordering safeguard in the skill. Do not run `tdd green` before `change-record implementation`. Never batch `tdd green` calls ahead of `change-record implementation`.
+3. Run `npx musubix3 tdd red <TEST-ID> --requirement <REQ-ID> --command <name>`.
    Do not edit implementation code until this records the expected failing test.
-3. Implement the smallest complete change, preserving the test, then run
-   `tdd green` with the same IDs and command. Refactor only after Green and record
-   `tdd refactor` after the refactored code passes.
-4. Maintain unique IDs and trace annotations in authoritative files; never add
-   proxies for coverage. Links locate evidence, not proof.
-5. Run focused tests, then configured typecheck, build and complete test commands.
-Documentation/prototypes may omit TDD only when policy allows; record the reason.
+4. Implement the smallest complete change, preserving the test, then run `tdd green` with the same IDs and command. Refactor only after Green and record `tdd refactor` after the refactored code passes.
+5. Maintain unique IDs and trace annotations in authoritative files; never add proxies for coverage. Links locate evidence, not proof.
+6. Run focused tests, then configured typecheck, build and complete test commands.
+Documentation/prototypes may omit TDD only when policy allows; record the reason in the CHANGE document and quality evidence instead of inventing retroactive or proxy TDD cycles.
 ## 4. Rebuild evidence and finish / 根拠更新と完了
 1. Run `trace build`, `trace check --strict`, `graph index`, and `graph gate`.
-2. Run `formal check` when changed requirements fit its documented abstraction;
-   use strict `Formal:` JSON for explicit conditional, numeric, temporal or
-   transition semantics; report unsupported prose rather than claiming proof.
-   A required `formal` check enforces modeled fraction and configured solver.
-3. Run `gate --changed --json` and `status --json`. Repair failures, dangling links and stale evidence; never weaken requirements or policy to obtain green. If `workflow` fails, run `workflow-verify` compatible mode against this session's live transcript, then `workflow waiver record-all` (bulk, all-or-nothing) for remaining declaration-scoped diagnostics (it cannot clear `WORKFLOW_INVOCATION_UNVERIFIED`), then rerun gate/status.
-4. Treat the first otherwise-passing gate as the release candidate. Run a `rubber-duck` review of the release/quality evidence summary and the CHANGE document; fix every reported issue and re-review until zero issues remain. Before any release operation, prepare/show its exact hash, ask one human approve/reject question and wait; record only that hash, then rerun gate/status.
-5. Complete only when required checks pass and `status.gate.ready` is true;
-   otherwise report blockers. One-phase work must state downstream work.
+2. Run `formal check` when changed requirements fit its documented abstraction; use strict `Formal:` JSON for explicit conditional, numeric, temporal or transition semantics; report unsupported prose rather than claiming proof. A required `formal` check enforces modeled fraction and configured solver.
+3. Use `gate --changed --json` plus `status --json` for intermediate confidence during iterative work. Repair failures, dangling links and stale evidence; never weaken requirements or policy to obtain green. If `workflow` fails, run `workflow-verify` compatible mode against this session's live transcript, then `workflow waiver record-all` (bulk, all-or-nothing) for remaining declaration-scoped diagnostics (it cannot clear `WORKFLOW_INVOCATION_UNVERIFIED`), then rerun the changed-scope gate/status.
+4. Treat the first otherwise-passing `gate --changed --json` run as the release-candidate checkpoint. Confirm the `CHANGELOG.md` entry was added before release approval. Confirm the `CHANGELOG.md` entry was added before the change is treated as release-ready. Confirm the `CHANGELOG.md` entry was added in the quality checklist. Then run a bounded `rubber-duck` review of the release/quality evidence summary and the CHANGE document using the same 3-round cap: validators first, full-artifact round 1, diff-only rounds 2-3, explicit stop condition in the request, batch-fix each round, and human escalation if blocking findings remain after round 3. Reserve the full `gate --json` for final release-candidate confirmation only. After the changed-scope release-candidate check passes, run the full `gate --json` once as the final confirmation before any release approval step. Before any release operation, prepare/show its exact hash, ask one human approve/reject question and wait; record only that hash, then rerun gate/status.
+5. Complete only when required checks pass and `status.gate.ready` is true; otherwise report blockers. One-phase work must state downstream work.

package/CHANGELOG.md

@@ -1,7 +1,95 @@
 # Changelog
 
+## 0.1.21 - 2026-10-07
+
+- Remove the development-only `sprintf-js` advisory chain using the single
+  reviewed `js-yaml: "^5.4.3"` override. Pin that exact override and npm-generated
+  root metadata, reject graph/evidence drift offline, retain a full zero-finding
+  audit bound to the current lockfile, and verify YAML/native Jest/package
+  compatibility without changing production dependencies or the package version
+  (CHANGE-0052).
+
+- Add a `--diff-only` option to `approval prepare <requirements|design|release>`
+  that additionally reports a `changedFiles` array: only the artifact paths
+  whose content differs from that same stage's (and domain's, when
+  applicable) last recorded approval, or every current path tagged
+  `diffOnlyBaseline: "none"` when no prior approval exists yet. The full,
+  unfiltered `artifactSha256` and `artifacts` manifest used by
+  `approval record` are computed identically with or without the flag, so the
+  cryptographic integrity guarantee is never weakened — `--diff-only` only
+  makes the already-required full review easier to perform by letting a human
+  reviewer see at a glance which files are new since their own last approval,
+  instead of manually diffing against `origin/main` for every requirements/
+  design/release approval request (#68).
+- Reject `tdd red`/`tdd green` with a new `CHANGE_RECORD_PHASE_PRECONDITION`
+  error, before any TDD evidence is appended, when the requirement's staged
+  change has not yet recorded the `design` phase (for `red`) or the `red`/
+  `implementation` phases (for `green`) in the correct order; the error names
+  the exact `change-record <id> <phase> --requirement <id>` command to run
+  first (or, when no staged change references the requirement at all, that a
+  staged change must record `design` first). This is a fail-fast,
+  complementary guard alongside the existing post-hoc `hasValidTddCycle`
+  validation — not a replacement for it — so an out-of-order `tdd green`
+  (one recorded before its requirement's `change-record red`/
+  `implementation` phases) can never corrupt the append-only, hash-chained
+  TDD evidence log in the first place, eliminating the manual hash-chain
+  recovery this exact scenario required during CHANGE-0047/Issue #55 (#67).
+- Exclude a fixed, source-hardcoded scratch-file naming convention
+  (untracked files at or beneath `.musubix/scratch/`, and untracked files
+  whose basename matches `*.scratch.<ext>`) from the untracked candidates
+  that `approval prepare release`'s manifest hashes, so an operator's own
+  scratch/debug inspection output written into the worktree no longer
+  silently changes the release-manifest hash on every inspection. The
+  exclusion is applied only as a final post-filter on the untracked
+  candidate set, after (never before) the existing nested-workspace and
+  generated-directory structural exclusion scan runs against the complete,
+  unfiltered candidate set, and it never removes a tracked file by name, so
+  the cryptographic integrity guarantee that every tracked artifact is
+  always included is preserved (#66).
+- Add `assertWaiverStaleSeverityFix` to the `pack:check` release-packaging
+  verification script so the packaged `change-waiver.js`'s `CHANGE_WAIVER_STALE`
+  severity-downgrade behavior (already present in source since CHANGE-0028/0029)
+  is also verified against the actually built and packaged distribution before
+  release, preventing a regression in the published package from silently
+  reintroducing the "waiver stale deadlock" (a stale waiver for a diagnostic
+  whose root cause has since been fixed cannot be re-recorded and has no way
+  to be cleared) that Issue #55 describes (#55).
+- Exclude validly archived TDD cycles from the Red-phase order window that
+  `validateChangeEvidence`'s `CHANGE_ORDER_MIGRATION_REQUIRED` diagnostic
+  uses, mirroring the existing exclusion already applied to validly voided
+  cycles, so a dangling cycle correctly rejected by `tdd red`'s
+  forced-failure check and cleaned up with `tdd archive` can never be
+  selected as a requirement's "current" cycle or falsely trigger the
+  diagnostic (#64).
+- Tighten the bundled `sdd-change` operational guidance for documentation and
+  review work: it now makes the Red → change-record Red → implementation →
+  change-record implementation → Green → change-record Green ordering
+  checklist explicit, adds symmetric `origin/main` freshness checks for
+  long-lived parallel worktrees, caps rubber-duck review loops at three
+  rounds with diff-only follow-up reviews and explicit stop conditions,
+  requires confirming the `CHANGELOG.md` entry during quality review, and
+  distinguishes iterative `gate --changed --json` runs from the single final
+  full `gate --json` confirmation (#61).
+- Keep `CHANGE_RECORD_MISSING` waivers stable when the operator appends the
+  waiver's own final `## Debt Remediation Approval` note to the staged
+  `CHANGE-*.md` document, while keeping the stale check fail-closed for
+  mismatched approval metadata, extra content, non-final sections, or any
+  substantive edit outside that tightly structured carve-out (#58).
+
 ## 0.1.20 - 2026-09-22
 
+- Add `CHANGE_PHASE_ORDER` as a thirteenth waivable code (`WAIVABLE_CODES`),
+  with `phase:<name>` detail scoping for the two change-level transitions
+  (`requirements`, `design`) and `batch:<name>:<batchKey>` detail scoping for
+  the four per-batch transitions (`red`, `implementation`, `green`,
+  `quality`). This provides a documented, human-approved safety net for a
+  corrective Red/Implementation/Green batch recorded after Quality that has
+  not yet been resolved by a Quality re-recording (#56).
+- Add repeatable Quality checkpoints after complete post-Quality corrective
+  batches. Schema version 2 retains ordinal Quality history, validation and
+  evidence merge pair every checkpoint deterministically, and
+  `change quality-recover` recovers the dedicated atomic `order.json` /
+  `changes.json` refresh transaction (#36).
 - Add `evidence merge` for append-only consolidation of `order.json`,
   `tdd.json`, `changes.json`, and `change-waivers.json` from another project
   root, with dry-run planning, crash-safe journaling, deterministic conflict

package/README-ja.md

@@ -1,6 +1,6 @@
 # musubix3
 
-**最新リリース v0.1.20 · GitHub Copilot CLI 専用 · Node.js ≥20 · TypeScript · MIT**
+**最新リリース v0.1.21 · GitHub Copilot CLI 専用 · Node.js ≥20 · TypeScript · MIT**
 
 [English](README.md)
 
@@ -339,7 +339,7 @@ npx musubix3 tdd green TEST-EXAMPLE-002 --requirement REQ-EXAMPLE-002 --command
 | `constitution validate [file]` | 版・原則・測定可能な規則の定義検査 |
 | `design validate <file>` | 必須項目・要求ID・既存ADRの参照検査 |
 | `design c4 <file>` | 明示的なコンポーネントと依存から Mermaid 図 |
-| `approval prepare <requirements\|design\|release>` | 人間が確認する決定的manifestとhashを表示 |
+| `approval prepare <requirements\|design\|release> [--diff-only]` | 人間が確認する決定的manifestとhashを表示。`--diff-only`はそのステージの直近の記録済み承認からハッシュが変化したファイルパスのみを`changedFiles`として追加表示（未承認なら`diffOnlyBaseline: "none"`で現在の全ファイルを表示）。`artifactSha256`/`artifacts`自体は変化しない |
 | `approval record <stage> --approver <name> --artifact-sha256 <hash> --confirm` | 確認済みhashが現在も一致するときだけ承認を記録 |
 | `approval validate` | 各承認をapproved・missing・staleとして表示し、検証結果から承認を推測しない |
 | `trace build` | リポジトリ全体のグラフと機能別コピーを生成 |
@@ -373,6 +373,7 @@ npx musubix3 tdd green TEST-EXAMPLE-002 --requirement REQ-EXAMPLE-002 --command
 | `attestation payload --provider <name> --run-id <id> --key-id <id> [--public-key-file <pem>] [--github-oidc-token-file <jwt>]` | 外部署名用の正規化CI payloadを出力 |
 | `attestation verify` | 静的鍵またはGitHub OIDC認可済みEd25519 provenanceを検証 |
 | `change-record <CHANGE-ID> <phase> --requirement <REQ-ID...>` | 段階的変更の成果物・TDD指紋を順序付きで記録。複数batchが同じrequirementを含む場合、検証はRedの`order`が最新のbatchを使用し、後発batchが未完了でも古い完了済み証跡へ暗黙にフォールバックしない |
+| `change quality-recover [--json]` | 中断したQuality refreshの2ファイルtransactionを復旧する。Quality後に新しい完全なcorrective batchがある場合、full-set Qualityを再記録すると以前のcheckpointをschema version 2の`qualityHistory`へ保持する。不完全・不要なrefreshは安定した`CHANGE_QUALITY_REFRESH_*`エラーで拒否する |
 | `config lint` | `args`が存在しないrepository相対パスを参照する設定済みコマンドを報告 |
 | `config scaffold` | 検出したGo/Rust/Maven/Python/Nodeツールチェーン向けのnative test-command候補を`.musubix/config.json`へ書き込まずに提案 |
 | `gate [--changed] [--feature <name>]` | 検証・実コマンドを集約し品質根拠を保存。`--feature`は requirements/design/trace/tdd/change-history/change-completeness の検査を1機能へ限定する診断用途で、repository全体のgateの代替ではない |
@@ -389,6 +390,12 @@ fileへ書込み・flushした後、排他的hard linkで公開するため、ca
 空または部分的な状態で見えることはありません。このatomic publicationを
 提供できないfilesystemでは`EVIDENCE_WRITER_LOCK_ACQUIRE_FAILED`となり、
 非atomicなfallbackは行いません。
+staging fileの同期とatomic publicationまたは検証済みreleaseが成功した後、
+Windows の directory synchronization が EPERM、EINVAL、ENOTSUP
+のいずれかを返す場合に限り、そのdirectory entryのdurability操作を未対応
+capabilityとして扱います。file同期、publication、metadata、unlink、
+open/close、その他のerror、およびWindows以外のplatformはfail-closedの
+ままです。
 
 status、approval prepare/validate、trace/graph inspection、knowledge query、
 TDD validate、attestation payload/verify、merge dry-runなどのcoordinated
@@ -403,7 +410,8 @@ musubix3外からproject fileを直接変更するprogramはcoordination対象
 自動復旧は現在Linux限定で、hostname、boot identity、PID namespaceが一致し、
 owner PIDが確実に存在しない場合だけ削除します。live、PID再利用、別host、
 不正・変更済みmetadata、未対応platform、判定不能なlockは正確なpathと確認手順を
-表示して保持し、force modeはありません。canonical lockと
+表示して保持し、force modeはありません。必要なidentity probeを提供できないため、
+Windows と macOS の自動復旧は inspection-only です。canonical lockと
 `.writer-lock.<transactionId>.json` staging fileはGitおよび生成入力から除外
 されます。関連processが存在しないことを確認した後に限り、残存staging fileを
 正確なpath指定で削除できます。
@@ -665,11 +673,31 @@ evidence/reportのpath（`tddReport`/`testReport`/`mutationReport`、
 なります。承認fileはstage、approver、`approvedAt`、artifactごとのSHA-256、決定的
 manifest SHA-256を保持します。release記録はcache済みquality evidenceを信頼せずgateを
 再計算し、承認以外の必須checkがすべてpassした場合だけ成功します。
+`approval prepare <stage> --diff-only`は、同じ決定的manifestから計算した
+`changedFiles`（そのstageの直近の*記録済み*承認とハッシュが異なるartifact pathのみ。
+ライブな`git diff`ではない）を追加表示します。`artifactSha256`と`artifacts`自体は
+常に従来通り返り、整合性検証は一切弱まりません。`diffOnlyBaseline`は、直近の承認と
+比較できた場合は`"approved"`、そのstageが一度も承認されたことがない場合は`"none"`
+（現在の全pathを表示）になります。`--domain`指定時はそのdomainの直近承認に限定して
+比較します。直近の承認fileが存在してもschema検証に失敗する場合、`approval validate`
+と同じ`Invalid <stage> approval evidence.`エラーで即座に失敗し、壊れた証拠を
+「未承認」として黙って扱うことはありません。`--diff-only`なしの非JSON出力は従来通り
+変化せず、`--diff-only`かつ`--json`なしの場合のconsole要約は全artifact一覧ではなく
+変更pathのみと簡潔なbaseline注記を表示します。
 approver文字列は明示的なlocal証拠であり、認証済みidentityではありません。
 独立identityが必要なrepositoryではprotected review、CODEOWNERS、CI/OIDCも併用します。
 local承認証拠は明示的な意思を記録しますが、承認者の暗号学的な本人確認ではありません。
 release権限はrepository review、CODEOWNERS/branch protection、またはCI/OIDC attestationで
 保護してください。
+`approval prepare release`のmanifestは、固定でsourceに埋め込まれたscratch file命名規則を
+untracked candidateから除外します：`.musubix/scratch/`配下のuntracked path、および
+basenameが`*.scratch.<ext>`に一致するuntracked file（例：`debug.scratch.json`）です。
+確認用のscratch/debug出力はこの命名規則で書くことで、確認のたびにrelease manifestの
+hashが変化することを防げます。この除外はconfigurableな設定ではなく固定・version管理
+された一覧です：untracked candidateにのみ適用され（同名のtracked fileは引き続き含まれ
+ます）、manifestの最終出力に対する後段filterとしてのみ適用され、構造的なnested
+workspace/生成directory除外のscanより前には適用されません。そのため、実際のtracked
+変更を隠すために範囲を広げることはできません。
 `tdd.redPreflightCommands`にはformatter等のplain command名を指定でき、
 Redのtest fingerprintを取得する前に成功が必須です。
 通常ファイルの`pyvenv.cfg`を含む`.venv`と`venv`に加え、生成された
@@ -943,6 +971,14 @@ CLI検証を呼び出す前に削除します。短命JWTは署名済みattestat
 - Core CIはNode 22をLinux、Windows、macOSで実行し、LinuxではNode 20と
   Node 24の互換性も追加確認します。native adapterとformal solverの統合は、
   固定toolchainを使ってLinuxで実行します。
+- **GitHub-hosted runner ポリシー:** portability matrix は意図的に
+  `ubuntu-latest`、`windows-latest`、`macos-latest` を使用し、それ以外の
+  CI job、Release workflow、npm publish workflow は `ubuntu-latest` を
+  使用します。これらは固定 image ではなく GitHub-hosted の floating label
+  です。選択される hosted runner image が変更された場合は、toolchain 導入、
+  typecheck、build、test、package check、release preparation、provenance、
+  publication control を再検証します。Action 自体の Node.js 24 runtime は、
+  package が検証する Node.js 20/22/24 とは別のものです。
   Windowsの実行ラッパーとprocess tree停止にはplatform固有の差があります。
   ESLintは追加せず、strict TypeScript と既存テストで検証します。
 
@@ -958,6 +994,48 @@ npm run pack:check
 npm run pack:smoke
 ```
 
+### 依存関係auditポリシー
+
+導入時またはrelease preparationで依存関係advisoryが報告された場合は、
+すべてのseverityと開発時依存を含むroot workspaceの
+`npm run audit:report`（`npm audit --json`）を実行します。advisory ID、すべての依存経路、
+production/build/testへの到達可能性、maintained fixの有無、remediation判断、
+残存リスクまたはmonitoring義務を記録します。開発時依存または現在到達不能で
+あることはexposureを下げますが、maintained fixが存在する場合のremediation
+にはなりません。記録したclean resultはその時点の証拠であり、将来のauditも
+cleanであることの証明として扱いません。
+`.github/workflows/dependency-audit.yml`は週次および手動dispatchでfull reportを
+再実行します。失敗したrunはrelease前にreviewし、remediationしてください。
+
+レビュー済みの依存例外は root `overrides` の
+`{"js-yaml":"^5.4.3"}` だけです（CHANGE-0052）。オフライン検査は異なる値・
+追加override・`sprintf-js` 再混入を拒否し、保存audit証拠は現在lockfileの
+bytesに一致させます。Vitestへの一般的なoverride許可や開発時脆弱性の容認ではありません。
+
+ビルド前に、機械管理されるすべてのリリース version を同期します。
+
+```sh
+npm run --silent release:version -- 1.2.3
+npm run --silent release:version -- --check 1.2.3
+# 同等の直接実行:
+node scripts/release-version.mjs 1.2.3
+node scripts/release-version.mjs --check 1.2.3
+```
+
+npm entrypoint では stdout をJSON reportだけにするため `--silent` を指定します。
+tag の `v` prefix と build metadata を含まない SemVer を指定します。
+リリース順序は version 同期、`CHANGELOG.md` の内容レビュー、`npm run build`、
+package 検査、明示的な release 承認、commit、一致する `v<version>` tag、
+最後に準備処理です。
+強制されるリリース順序は、最終リリースメタデータと `CHANGELOG.md`、
+検証とビルド、明示的な release 承認、commit と変更されていない `v<version>` tag の作成、
+最後に `release:prepare` です。承認後にcommit済みの
+release入力を変更した場合は、新しいtagを準備する前に検証と release 承認をやり直す必要があります。
+`release:prepare` は出力ディレクトリを変更する前に、すべての同期対象、
+tag が指すcommit、および承認済みtag manifestを検証します。Release workflowを
+手動実行する場合はworkflowのref selectorで対象tagを選び、同じtagを
+`release_tag`へ入力します。
+
 `packages/domain` は純粋な検証、`packages/analysis` は根拠・コンパイラ・
 ファイルシステム、`packages/cli` はコマンドと配置を担当します。
 ビルド出力は `dist/packages/**`。npm パッケージには隠しSkills、プラグイン定義、
@@ -979,6 +1057,28 @@ secretも利用できます。npm publishがpendingまたは失敗してもGitHu
 workflow refとして選び、同じ値を`release_tag`へ指定します。tagがOIDCに束縛された
 `GITHUB_SHA`を指していなければworkflowは拒否します。
 
+npm publishはstableな`vMAJOR.MINOR.PATCH` tagだけを受け付けます。保護された
+2つのGitHub Actions publish経路は、そのtagをcheckoutし、non-draftのGitHub
+Releaseを新しい空ディレクトリへdownloadしてから、共通validatorを通してnpm
+provenance publishを実行します。validatorはhistorical assetや追加assetを拒否し、
+SHA256SUMSの厳密な形式、tarball内の`musubix3` package version、全local fileと
+現在のuploaded GitHub Release asset digestの一致を検証します。`release:prepare`
+の直接出力には後段のstrict CI attestationがないためpublishできません。
+
+local operatorは同じreleaseを検証できますが、provenance publishはできません。
+
+```bash
+gh auth status
+mkdir release-assets-verify
+gh release download v1.2.3 --repo nahisaho/musubix3 --dir release-assets-verify
+npm run --silent release:publish -- --verify-only --tag v1.2.3 \
+  --repository nahisaho/musubix3 --directory release-assets-verify
+```
+
+release asset出力に`digest`と`state`を含むGitHub CLIを使用してください。
+provenance publishは保護された`npm-publish` GitHub Actions environmentだけで
+実行されます。
+
 release attestationは、ephemeral Ed25519公開鍵をcustom audienceへ束縛した
 GitHub Actions OIDC tokenを使用します。署名対象にはrepository、Git commit、
 run ID、workflow/ref identity、workspace snapshot、存在するmusubix evidence headが

package/README.md

@@ -1,6 +1,6 @@
 # musubix3
 
-**Latest release v0.1.20 · GitHub Copilot CLI only · Node.js ≥20 · TypeScript · MIT**
+**Latest release v0.1.21 · GitHub Copilot CLI only · Node.js ≥20 · TypeScript · MIT**
 
 [日本語](README-ja.md)
 
@@ -389,7 +389,7 @@ validation/gate or requested solver failure, **2** usage, I/O or malformed confi
 | `design validate <file>` | Fields, global requirement IDs, existing ADR references |
 | `design scaffold <slug>` | Create `.musubix/features/<slug>/design.md` from a fixed placeholder template; never overwrites an existing file, and does not require a pre-existing `requirements.md` |
 | `design c4 <file>` | Mermaid component/dependency diagram from explicit fields |
-| `approval prepare <requirements\|design\|release>` | Display the exact deterministic manifest and hash for human review |
+| `approval prepare <requirements\|design\|release> [--diff-only]` | Display the exact deterministic manifest and hash for human review; `--diff-only` additionally reports `changedFiles` (only paths whose content differs from the last recorded approval for that stage; all current paths with `diffOnlyBaseline: "none"` when no prior approval exists) without altering `artifactSha256`/`artifacts` |
 | `approval record <stage> --approver <name> --artifact-sha256 <hash> --confirm` | Record approval only if the reviewed hash is still current |
 | `approval validate` | Report each approval as approved, missing, or stale; never infer approval from validation |
 | `trace build` | Generate global trace snapshot and feature copies |
@@ -413,7 +413,8 @@ validation/gate or requested solver failure, **2** usage, I/O or malformed confi
 | `mutation validate` | Revalidate requirement-scoped schema-v1 killed-mutant evidence |
 | `mutation identity <REQ-ID> <TEST-ID> <sourcePath> <operator> <line> <column>` | Print the deterministic `MUT-*` identity a mutation report must declare |
 | `tdd validate` | Validate persisted Red/Green/Refactor order, fingerprints, durations, and hash-chain evidence |
-| `tdd red\|green\|refactor <TEST-ID> --requirement <REQ-ID> --command <name>` | Execute and record a verified TDD phase. Recording the project's **first** `tdd` cycle (any `red` call while `.musubix/evidence/tdd.json` has zero cycles) makes `gate`'s `tdd` check required **project-wide**, for every mandatory requirement, not just the ones touched by the current change; each uncovered requirement then surfaces as `TDD_REQUIREMENT_UNCOVERED`. `approval record release` always runs the full (non-`--changed`) gate, so it is blocked by any resulting `TDD_REQUIREMENT_UNCOVERED` diagnostics. `tdd migrate` cannot be used to bulk-onboard previously-uncovered requirements: it only re-fingerprints a requirement that already has a valid Green cycle. `tdd red` prints/returns a `TDD_ADOPTION_PROJECT_WIDE` warning (in a `warnings` array, separate from `diagnostics`) the moment this first cycle is persisted, listing every other still-uncovered mandatory requirement. |
+| `tdd red\|green\|refactor <TEST-ID> --requirement <REQ-ID> --command <name>` | Execute and record a verified TDD phase. Recording the project's **first** `tdd` cycle (any `red` call while `.musubix/evidence/tdd.json` has zero cycles) activates `gate`'s `tdd` coverage evaluation **project-wide**, for every mandatory requirement, not just the ones touched by the current change; each uncovered requirement then surfaces as `TDD_REQUIREMENT_UNCOVERED`. If `tdd` was not already required for another configured reason, that same first cycle is also what makes the check required. `approval record release` always runs the full (non-`--changed`) gate, so it is blocked by any resulting `TDD_REQUIREMENT_UNCOVERED` diagnostics. `tdd migrate` cannot be used to bulk-onboard previously-uncovered requirements: it only reuses already-covered valid Green-backed evidence. `tdd red` prints/returns a `TDD_ADOPTION_PROJECT_WIDE` warning (in a `warnings` array, separate from `diagnostics`) the moment this first cycle is persisted, listing every other still-uncovered mandatory requirement. |
+| `tdd migrate <test-id>` / `tdd migrate <old-id> <new-id>` | Relink already-covered evidence without fabricating a fresh Red/Green cycle. `tdd migrate <test-id>` preserves the existing fingerprint-migration mode for a single covered test whose current declaration still matches the stored evidence under the superseded fingerprinting algorithm. `tdd migrate <old-id> <new-id>` relinks a pure identifier rename when the current authoritative `new-id` declaration differs from `old-id` only in its `@id` annotation and adapter-matched test identity string, the non-test `sourceFingerprint` is unchanged, and the renamed test remains the sole authoritative declaration at the same test path. |
 | `workflow-record <skill> <phase> --status <status>` | Record a compact self-reported workflow declaration |
 | `workflow waiver record <code> --skill <skill> --phase <phase> --recorded-at <timestamp> [--index <n>] --approver <name> --reason <text> --confirm` | Record an audited, bounded downgrade of one declaration-scoped workflow reconciliation diagnostic (`WORKFLOW_SKILL_NOT_INVOKED`, `WORKFLOW_INVOCATION_ORDER`, `WORKFLOW_INVOCATION_INCOMPLETE`, `WORKFLOW_INVOCATION_FAILED`, or `WORKFLOW_INVOCATION_REUSED`) to a non-blocking waived status; a paired `WORKFLOW_BINDING_MISSING` diagnostic sharing the same declaration scope is downgraded together with it. It cannot waive `WORKFLOW_INVOCATION_UNVERIFIED`, which only `workflow-verify` having actually run this session can resolve |
 | `workflow waiver record-all --approver <name> --reason <text> --confirm` | Bulk variant of `workflow waiver record`: waives every currently-outstanding waivable declaration-scoped diagnostic across the whole reconciliation report in one all-or-nothing call, instead of one `record` invocation per diagnostic. Rejects (recording nothing) if any bulk waiver precondition fails first — malformed waiver evidence, an invalid waiver chain, a blank `--approver`/`--reason`, or a `WORKFLOW_INVOCATION_UNVERIFIED` diagnostic (which `workflow-verify` must resolve first; no per-declaration or bulk waiver can substitute for `workflow-verify` never having run). Each waived declaration-scoped diagnostic's paired `WORKFLOW_BINDING_MISSING` is downgraded together with it, identically to the existing single-record command. With zero remaining candidates (already waived, or none present) it succeeds idempotently and records nothing |
@@ -423,6 +424,7 @@ validation/gate or requested solver failure, **2** usage, I/O or malformed confi
 | `attestation payload --provider <name> --run-id <id> --key-id <id> [--public-key-file <pem>] [--github-oidc-token-file <jwt>]` | Emit canonical unsigned CI payload for external signing |
 | `attestation verify` | Verify static-key or GitHub OIDC-authorized Ed25519 provenance |
 | `change-record <CHANGE-ID> <phase> --requirement <REQ-ID...> [--allow-unchanged] [--dry-run]` | Record ordered artifact/TDD fingerprints for a staged change. `impact`/`requirements`/`design`/`quality` require the change's full requirement ID set; `red`/`implementation`/`green` also accept a proper non-empty subset, recorded as an independent per-requirement batch, so a multi-requirement change can be completed with an interleaved per-requirement Red-Implementation-Green loop instead of one global batch. When multiple batches contain the same requirement, validation uses the batch with the latest Red `order`; a later incomplete batch supersedes older evidence and must be completed rather than silently falling back. Rejects with a non-zero exit and a stable `*_UNCHANGED_AT_RECORD` diagnostic (leaving `changes.json`/`order.json` untouched) when a phase's fingerprint is byte-identical to the immediately preceding phase's, since that mistake is otherwise only caught much later by `trace check --strict`/`gate`, at which point the append-only evidence store makes it unfixable. `--allow-unchanged` bypasses this check for the `requirements` phase only (the one case `sdd-change` documents as legitimate: a defect fix that intentionally leaves its requirement unchanged) and persists a durable marker so later validation does not re-flag it. `--dry-run` previews the exact success/rejection outcome, including every existing check, without persisting anything. Each recorded phase/batch stores both `order` (the verified, `gate`-checked logical append sequence from `order.json` — the only field guaranteed correct and monotonic per change) and `recordedAt` (an independently captured wall-clock timestamp with no ordering guarantee relative to `order`); `gate` reports a non-blocking `CHANGE_RECORDEDAT_OUT_OF_ORDER` warning when a change's `recordedAt` values disagree with its `order` sequence |
+| `change quality-recover [--json]` | Recover an interrupted atomic Quality refresh. A repeated full-set Quality after a newer complete corrective batch retains earlier checkpoints in schema-version-2 `qualityHistory`; incomplete/current or unnecessary refreshes fail with stable `CHANGE_QUALITY_REFRESH_*` errors. |
 | `config lint` | Report configured commands whose `args` reference repository-relative paths that do not exist |
 | `config scaffold` | Propose native test-command entries for detected Go/Rust/Maven/Python/Node toolchains without writing `.musubix/config.json` |
 | `gate [--changed] [--feature <name>]` | Fresh full checks plus actual configured commands; persist evidence. `--feature` scopes requirements/design/trace/tdd/change-history/change-completeness checks to one feature as a diagnostic view; never a substitute for the repository-wide gate |
@@ -438,6 +440,12 @@ Complete owner metadata is staged, flushed, and published with a same-directory
 exclusive hard link, so the canonical lock is never visible as empty or partial.
 Filesystems that cannot provide this atomic publication fail with
 `EVIDENCE_WRITER_LOCK_ACQUIRE_FAILED`; there is no non-atomic fallback.
+When Windows directory synchronization rejects EPERM, EINVAL, or ENOTSUP after
+successful staging-file synchronization and atomic publication or verified
+release, musubix3 treats only that directory-entry durability operation as an
+unsupported capability. File synchronization, publication, metadata, unlink,
+open/close, every other error, and every non-Windows platform remain
+fail-closed.
 
 Coordinated readers such as status, approval preparation/validation, trace and
 graph inspection, knowledge queries, TDD validation, attestation payload/verify,
@@ -454,6 +462,7 @@ recovery is currently Linux-only and requires matching hostname, boot identity,
 PID namespace, and a demonstrably absent owner PID. Live, PID-reused,
 cross-host, malformed, changed, unsupported, or indeterminate locks are left
 untouched with the exact path and inspection guidance. There is no force mode.
+Because the required identity probes are unavailable, automatic recovery remains inspection-only on Windows and macOS.
 The canonical lock and `.writer-lock.<transactionId>.json` staging files are
 ignored and excluded from generated inputs. After confirming no related process
 is active, an abandoned staging file may be removed by its exact path.
@@ -712,12 +721,39 @@ SHA-256. Run `approval prepare` before review and pass that exact hash to
 `approval record`; an intervening change is rejected and later changes become
 stale. Release recording recomputes the gate and requires every required
 non-approval check to pass rather than trusting cached quality evidence.
+`approval prepare <stage> --diff-only` additionally reports `changedFiles`:
+only the artifact paths whose content differs from that stage's last
+*recorded* approval (not a live `git diff`), computed from the same
+deterministic manifest used for `artifactSha256` — the full hash and
+`artifacts` map are always still returned unchanged, so integrity verification
+is never weakened. `diffOnlyBaseline` is `"approved"` when compared against a
+prior recorded approval, or `"none"` (with every current path listed) when
+this stage has never been approved before. With `--domain`, the comparison is
+scoped to that domain's prior approval, matching normal domain-scoped approval
+semantics. If the last recorded approval file for that stage exists but fails
+schema validation, `approval prepare --diff-only` fails fast with the same
+`Invalid <stage> approval evidence.` error `approval validate` reports,
+rather than silently treating corrupted evidence as "no prior approval".
+Without `--diff-only`, non-JSON output is unchanged; with `--diff-only` and no
+`--json`, the console summary prints only the changed paths and a short
+baseline note instead of the full artifact listing.
 The approver string is explicit local evidence, not authenticated identity;
 repositories that require independent identity must also use protected review,
 CODEOWNERS, or CI/OIDC controls.
 Local approval evidence records explicit intent but does not cryptographically
 authenticate the approver; protect release authorization with repository review,
 CODEOWNERS/branch protection, or CI/OIDC attestation.
+`approval prepare release`'s manifest excludes a fixed, source-hardcoded
+scratch-file convention from its untracked candidates: any untracked path at
+or beneath `.musubix/scratch/`, and any untracked file whose basename matches
+`*.scratch.<ext>` (for example `debug.scratch.json`). Write ad hoc
+inspection/debug output using this convention so it never changes the
+release-manifest hash on repeated inspection. This exclusion is a fixed,
+version-controlled list, not a configurable setting: it applies only to
+untracked candidates (a tracked file named this way is still included), and
+only as a final filter on the manifest's output, never before the structural
+nested-workspace/generated-directory exclusion scan, so it cannot be widened
+to quietly hide a real tracked change.
 Use `tdd.redPreflightCommands` to reference plain configured formatter commands;
 they must pass before Red captures the authoritative test fingerprint.
 Conventional `.venv` and `venv` Python environments containing a regular
@@ -1133,6 +1169,14 @@ transcript/session fields into the Ed25519 signature.
 - Core CI covers Node 22 on Linux, Windows, and macOS, with additional Node 20
   and Node 24 Linux compatibility checks. Native adapters and formal solvers run
   once on Linux with pinned toolchains.
+- **GitHub-hosted runner policy:** the portability matrix intentionally uses
+  `ubuntu-latest`, `windows-latest`, and `macos-latest`; every other CI job and
+  the Release and npm publication workflows use `ubuntu-latest`. These are
+  floating GitHub-hosted labels, not pinned images. When the selected hosted
+  runner image changes, revalidate toolchain installation, typecheck, build,
+  tests, package checks, release preparation, provenance, and publication
+  controls. The actions' Node.js 24 implementation runtime is independent of
+  the Node.js 20/22/24 versions tested for this package.
   No formatting/lint framework is bundled; strict TypeScript and tests are used.
 
 ## Development and release checks
@@ -1147,6 +1191,49 @@ npm run pack:check
 npm run pack:smoke
 ```
 
+### Dependency audit policy
+
+When installation or release preparation reports a dependency advisory, run
+root-workspace `npm run audit:report` (`npm audit --json`) with all severities and development
+dependencies included. Record the advisory ID, every dependency path,
+production/build/test reachability, maintained fix availability, remediation
+decision, and residual risk or monitoring obligation. Development-only or
+currently unreachable code lowers exposure but is not remediation when a
+maintained fix is available. A recorded clean result is time-bound and must not
+be treated as proof that future audits remain clean.
+`.github/workflows/dependency-audit.yml` repeats the full report weekly and on
+manual dispatch; review and remediate any failing run before release.
+
+The reviewed dependency exception is exactly `{"js-yaml":"^5.4.3"}` in root
+`overrides` (CHANGE-0052). The offline remediation checker rejects different or
+additional overrides and reintroduced `sprintf-js`; retained audit evidence
+must match the current lockfile bytes. This is not general permission to override
+Vitest packages or to accept development-only vulnerabilities.
+
+Synchronize every mechanically managed release-version surface before building:
+
+```sh
+npm run --silent release:version -- 1.2.3
+npm run --silent release:version -- --check 1.2.3
+# Equivalent direct entrypoints:
+node scripts/release-version.mjs 1.2.3
+node scripts/release-version.mjs --check 1.2.3
+```
+
+Use `--silent` with the npm entrypoint so stdout contains only its JSON report.
+Supply a bare SemVer version, without the tag's `v` prefix or build metadata.
+The release order is version synchronization, authored `CHANGELOG.md` review,
+`npm run build`, package validation, explicit release approval, commit, and the
+matching `v<version>` tag before preparation.
+The enforced release order is final release metadata and `CHANGELOG.md`,
+validation and build, explicit release approval, commit and create the unchanged `v<version>` tag,
+then `release:prepare`. Any committed release-input change
+after approval requires renewed validation and release approval before a new tag
+is prepared. `release:prepare` validates every synchronized surface, the tag
+commit, and the approved tagged manifest before changing its output directory.
+For a manual Release workflow dispatch, select the target tag in the workflow
+ref selector and enter that identical tag as `release_tag`.
+
 Workspaces: `packages/domain` (pure validators), `packages/analysis` (evidence,
 compiler and filesystem services), `packages/cli` (thin command/installation layer).
 One build emits `dist/packages/**`. Published contents explicitly include hidden
@@ -1171,6 +1258,29 @@ For manual dispatch, select the release tag as the workflow ref and provide the
 same value as `release_tag`; the workflow rejects tags that do not point to the
 OIDC-bound `GITHUB_SHA`.
 
+npm publishing accepts stable `vMAJOR.MINOR.PATCH` tags only. Both protected
+GitHub Actions publish paths check out that tag, download its non-draft GitHub
+Release into a new empty directory, and use the shared validator before npm
+provenance publishing. The validator rejects historical or additional assets,
+verifies the exact SHA256SUMS syntax and embedded `musubix3` package version,
+and requires every local file digest to match the current uploaded GitHub
+Release asset digest. Direct `release:prepare` output is not publishable because
+the strict CI attestation is added later.
+
+Local operators can verify, but cannot provenance-publish, the same release:
+
+```bash
+gh auth status
+mkdir release-assets-verify
+gh release download v1.2.3 --repo nahisaho/musubix3 --dir release-assets-verify
+npm run --silent release:publish -- --verify-only --tag v1.2.3 \
+  --repository nahisaho/musubix3 --directory release-assets-verify
+```
+
+Use a GitHub CLI version whose release asset output includes `digest` and
+`state`. Provenance-enabled publishing remains restricted to the protected
+`npm-publish` GitHub Actions environment.
+
 The release attestation uses a real GitHub Actions OIDC token whose custom
 audience binds an ephemeral Ed25519 public key. Its signature covers repository,
 Git commit, run ID, workflow/ref identity, current workspace snapshot, and any