musubix3 0.1.19 → 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.19"
+    "version": "0.1.21"
   },
   "plugins": [
     {
       "name": "musubix3",
       "source": ".",
-      "version": "0.1.19",
+      "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,5 +1,131 @@
 # 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
+  handling, and explicit recovery for interrupted merges.
+- Add project-wide evidence writer serialization with atomic lock publication,
+  coordinated readers, reentrant same-process ownership, and deterministic
+  multi-process contention handling. Stale-lock recovery validates Linux
+  process identity and lock inode metadata before removal; unsupported
+  platforms fail closed and require operator-reviewed manual removal using the
+  reported lock path and owner metadata. On Linux, operators can use
+  `evidence unlock --recover` for validated stale-lock removal (#28).
+- Protect direct analysis APIs and CLI writer paths, including adapter reports,
+  trace/cache outputs, approvals, workflow evidence, TDD evidence, and evidence
+  merge/recovery. Dry-run and exempt command modes remain explicitly classified,
+  and merge coordination checks the destination before the incoming project
+  (#28).
+- Add deterministic regression coverage for release-time inode replacement,
+  stale-lock recovery, destination-first merge conflicts, CLI classification,
+  exempt commands, graph cache protection, and direct adapter API access (#28).
+- Existing projects should rerun `musubix3 init` to add the writer-lock file
+  and its staging-file pattern to `.gitignore`.
+
+- Fix requirement-batch validation selecting stale legacy full-set evidence
+  when later scoped Red/Implementation/Green evidence exists. Validation,
+  completeness, order-migration checks, and waiver condition re-derivation now
+  use the applicable batch with the latest Red order; later incomplete batches
+  remain fail-closed instead of falling back (#27).
+
+- Fix strict workflow verification for resumed Copilot CLI conversations.
+  A single-session transcript may now contain one or more routine
+  `session.shutdown` / `session.resume` episodes before its final routine
+  shutdown. Invalid or unmatched lifecycle transitions, mixed `result` and
+  shutdown formats, abnormal shutdowns, multiple session identities, and
+  non-final terminal state still fail closed. `workflow-sanitize` retains the
+  resume boundaries required for strict re-verification (#26).
+
 ## 0.1.19 - 2026-09-14
 
 Bug fix: change completeness now recognizes every requirement listed in a

package/README-ja.md

@@ -1,6 +1,6 @@
 # musubix3
 
-**最新リリース v0.1.17 · 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` | リポジトリ全体のグラフと機能別コピーを生成 |
@@ -357,6 +357,9 @@ npx musubix3 tdd green TEST-EXAMPLE-002 --requirement REQ-EXAMPLE-002 --command
 | `formal check <file> [--solver auto\|none\|z3\|lean]` | 明示的なBoolean・条件・数値・時間・状態遷移モデルを検査 |
 | `model-correspondence validate` | Formal JSON→生成trace→正本passing testの証拠を再検証 |
 | `evidence refresh [--changed]` | 同じfail-closed gate pipelineで派生証拠を再生成 |
+| `evidence unlock --recover` | 同一hostでowner processが確実に終了したevidence writer lockだけを復旧する。live、別host、不正metadata、PID再利用、未対応platform、判定不能なownerは変更せず拒否する |
+| `evidence merge --incoming <directory> [--dry-run]` | 現在rootの有効なorder/TDD/change/waiver履歴へ、別projectの有効な履歴を統合する。base recordを先に保持し、完全重複をdedupeし、payload競合・chronology逆転・Quality後のbatch追加は書込みなしで拒否する。dry-runも同じ計画・検証を行い、incoming directoryは変更しない |
+| `evidence merge --recover` | journalから中断したevidence mergeを復旧する。prepared transactionはrollback、committed transactionは検証してroll-forwardする。`EVIDENCE_MERGE_RECOVERY_UNSAFE`の場合は`.musubix/evidence`をバックアップし、信頼できるsourceから`order.json`、`tdd.json`、`changes.json`、`change-waivers.json`を復元または検証し、merge journal/tempを隔離してから再検証する |
 | `mutation validate` | 要求scopeのschema-v1 killed-mutant証拠を再検証 |
 | `mutation identity <REQ-ID> <TEST-ID> <sourcePath> <operator> <line> <column>` | mutation reportが宣言すべき決定的な`MUT-*`識別子を出力 |
 | `tdd validate` | 保存済みRed/Green/Refactorの順序、指紋、実行時間、hash-chainを検証 |
@@ -369,12 +372,80 @@ npx musubix3 tdd green TEST-EXAMPLE-002 --requirement REQ-EXAMPLE-002 --command
 | `attestation oidc-audience --key-id <id> [--public-key-file <pem>]` | 署名鍵を許可するGitHub custom audienceを導出 |
 | `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指紋を順序付きで記録 |
+| `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の代替ではない |
 | `status` | 成果物数と準備状況・陳腐化を表示 |
 
+### Evidence writer coordination
+
+証拠または生成済みproject stateを変更するcommandは、
+`<realpath(project-root)>/.musubix/evidence/.writer-lock.json` の単一の
+fail-fast lockを使用します。対象はinit/upgradeの書込み、gate/evidence
+refresh、TDD/change/workflow/approval記録、trace/graph/knowledge/formal生成、
+evidence merge/recoveryです。完全なowner metadataを同一directoryのstaging
+fileへ書込み・flushした後、排他的hard linkで公開するため、canonical lockが
+空または部分的な状態で見えることはありません。この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
+readerは、無関係なownerが存在すると`EVIDENCE_WRITER_LOCKED`で即時失敗し、
+待機もread lease保持もしません。同じowner async context内のnested analysis
+operationはlockを再利用しますが、child processとworker threadはcontextを
+継承しません。したがって設定commandが同じrootへmusubix3 writer/readerを
+再帰実行するとfail-fastになるため、そのcommand chainを修正してください。
+musubix3外からproject fileを直接変更するprogramはcoordination対象外です。
+
+異常終了でlockが残った場合は`evidence unlock --recover`を実行します。
+自動復旧は現在Linux限定で、hostname、boot identity、PID namespaceが一致し、
+owner PIDが確実に存在しない場合だけ削除します。live、PID再利用、別host、
+不正・変更済みmetadata、未対応platform、判定不能なlockは正確なpathと確認手順を
+表示して保持し、force modeはありません。必要なidentity probeを提供できないため、
+Windows と macOS の自動復旧は inspection-only です。canonical lockと
+`.writer-lock.<transactionId>.json` staging fileはGitおよび生成入力から除外
+されます。関連processが存在しないことを確認した後に限り、残存staging fileを
+正確なpath指定で削除できます。
+
+writer-lock checkはmerge journal checkより先に実行されます。abandoned writer
+lockとpending merge journalが両方ある場合は、先に
+`evidence unlock --recover`、次に`evidence merge --recover`を実行します。
+unlock recoveryはmerge journalを読み書きしません。
+
+### Evidence history の統合
+
+`evidence merge` は両方のrootに個別に有効な`order.json`、`tdd.json`、
+`changes.json`があることを前提とし、`change-waivers.json`は省略できます。
+incomingのreal pathは現在rootと分離され、read-onlyのままです。現在worktree
+には新しく導入するincoming change documentが必要です。duplicate比較では、
+再構築対象のsequence/order/hash-link fieldだけを除外してJSONをcanonical化します。
+結果はbase historyを先に、incomingの相対順序を後に保持するため、論理orderが
+正しくてもwall-clockの`recordedAt` warningは残り得ます。base Qualityより後に
+incoming RedまたはImplementation batchがある場合は、Quality記録前にhistoryを
+統合し、統合後のhistoryに対してQualityを再記録してください。
+
+`--dry-run`は書込みなしで同じconflict、candidate、stale waiver、
+supersession解析を行います。統合によりwaiver snapshotがstaleかつinactiveに
+なったり、より後のauthoritative waiverが選択されたりするため、該当waiverを
+明示的に再承認し、通常の`gate`と`status`を再実行してください。統合対象は
+`order.json`、`tdd.json`、`changes.json`、`change-waivers.json`だけです。
+workflow、approval、quality、formal、mutation、correspondence、performance、
+attestation、native test-report evidenceは既存の再生成またはconflict解決手順を
+使用します。`EVIDENCE_MERGE_CANDIDATE_INVALID`は基礎となるfile/entity診断を
+すべて報告します。中断後は`--recover`を使い、
+`EVIDENCE_MERGE_RECOVERY_UNSAFE`の場合は`.musubix/evidence`をバックアップし、
+信頼できるsourceから4 targetを復元または検証し、merge journal/tempを隔離して
+structural validationを再実行してください。
+
 `--changed` は Git の staged/unstaged/untracked/rename/delete を収集し、
 変更・影響を表示します。**安全のため全検査と全設定コマンドを再実行**します。
 未実施検査を推測で成功扱いする差分最適化はありません。常駐プロセスもありません。
@@ -602,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`に加え、生成された
@@ -752,10 +843,13 @@ review evidenceへ入れる前に`workflow-sanitize`で必要最小限へ変換
 重複workflow eventではなく`change-record`に記録します。
 `"workflow":{"mode":"strict"}`または`--strict`では、全非空行のJSON、
 event timestamp、tool start/completionの1対1整合性、最後に1件だけ存在する
-正常終了terminal eventを追加検査します。対応形式は`exitCode: 0`の`result`、
+正常終了terminal stateを追加検査します。対応形式は`exitCode: 0`の`result`、
 または一意なsession UUIDと、末尾の
 `session.shutdown(data.shutdownType="routine")`を持つ現行Copilot CLI形式です。
-terminal形式の混在、複数session、異常shutdown、末尾以外のterminal eventは
+shutdown形式では、各中間routine shutdownの直後に`session.resume`がある場合、
+1回以上のshutdown/resumeを含む再開sessionも受理し、`workflow-sanitize`は
+検証に必要なlifecycle境界を保持します。terminal形式の混在、対応しない
+shutdown/resume、複数session、異常shutdown、末尾以外のterminal stateは
 fail closedで拒否します。terminal `sessionId`、exit code、
 event数、terminal時刻、raw source hash、canonical transcript hashを保存します。
 `workflow.expectedSessionId`または`--session-id`でcaller申告sessionの置換を拒否します。
@@ -877,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 と既存テストで検証します。
 
@@ -892,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、プラグイン定義、
@@ -913,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が