leerness 1.36.187 → 1.36.188

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.36.188 — 2026-09-08
+
+- Add read-only state stores diagnostics for decision, lesson and role status, bounded reads and explicit fallback provenance; preserve metadata-only state inspect and existing mutation behavior.
+
 ## 1.36.187 — 2026-09-05
 
 - feat(state): add read-only runtime compatibility diagnosis and observed-layout write guards; keep legacy storage without migration or activation

package/README.ko.md

@@ -90,6 +90,8 @@ leerness verify-claim T-0001 --require-evidence
 ```
 
 - `optimism-check` · `verify-claim` — evidence의 도메인 주장(API·DB·결제·이메일·큐·캐시·알림·스토리지 등 10종)을 실제 소스 호출과 대조. **JavaScript뿐 아니라 Python·Ruby·Go·C#·Java·PHP·Rust 구현도 인식**합니다(1.13).
+
+`verify-claim`의 통과는 적용된 증거 검사 통과이며 요구사항의 의미적 정확성 보장이 아닙니다. 단건 `--json`의 `evidenceLevel: "executed"`에는 실패한 실행도 포함되고 `semanticVerified`는 항상 `false`입니다. `--run-tests`를 지정해도 명령이 없거나 차단되면 실행을 건너뜁니다. `ok`·`reasons`·`run.skipped`·`run.allPassed`를 함께 확인하세요. [검증 결과 해석 및 실행 예제](docs/verification-evidence.md)를 참고하세요.
 - `lazy detect` — 증거 없는 done, 빈 handoff, 테스트 미실행, 미추적 TODO를 탐지.
 - 정직한 완료는 통과하고 가짜 완료만 exit 1로 차단 — `gate` 또는 CI에 그대로 연결됩니다.
 

package/README.md

@@ -39,9 +39,9 @@ npx leerness task update T-0002 --status done --evidence "payment.js implemented
 npx leerness verify-claim T-0002   # exit 1 — payment.js does not exist. Claim rejected.
 ```
 
-Now actually write `payment.js`, then run the **same** `verify-claim T-0002` → it exits 0. That is the whole idea: **"done" must match reality.**
+Now write the implementation and record evidence, then run the **same** `verify-claim T-0002` again. A successful check means the applicable evidence checks passed; creating a file alone does not prove that the payment API works.
 
-> Tip: if your evidence claims a specific test count (e.g. "5 tests passed"), leerness counts the test functions actually present and rejects a claim that exceeds them — so claim only what's true. That default is a static count of test declarations, not proof they pass; add `--run-tests --test-cmd "<your test cmd>"` to verify they actually pass by running them.
+> Tip: test counts are static declaration-pattern heuristics, not execution or coverage proof. Add `--run-tests --test-cmd "<your trusted test command>" --json` to check the selected command's exit status and supported reporter output. `evidenceLevel: "executed"` includes failed runs; inspect `ok`, `reasons`, and `run` together. `semanticVerified` remains `false`. See [verification evidence and runnable examples](docs/verification-evidence.md) for skipped runs, unparsed output, and reporting limits.
 
 > Want a smaller footprint? `leerness init . --minimal` installs only the core memory + verification files instead of the full set.
 
@@ -166,7 +166,7 @@ MIT
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.36.187 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.36.188 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -220,7 +220,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.36.187는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **98개 도구**를 노출:
+Leerness v1.36.188는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **98개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -241,7 +241,7 @@ Leerness v1.36.187는 stdio JSON-RPC MCP server를 내장합니다 — Claude Co
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) 회귀 테스트 갱신 → 4) 전체 e2e 스위트 통과 → 5) npm publish + git tag → 6) main push → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **v1.9.x → 1.36.187 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
+현재 누적: **v1.9.x → 1.36.188 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
 
 ### 성능 가이드
 
@@ -279,5 +279,5 @@ leerness release pack --close --auto-main-push
 - `.leerness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
 - `.leerness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
 
-Last synced by Leerness v1.36.187: 2026-09-06
+Last synced by Leerness v1.36.188: 2026-09-08
 <!-- leerness:project-readme:end -->

package/bin/leerness.js

@@ -50,7 +50,7 @@ const {
   migrateLegacyWorkspace,
 } = require('../lib/workspace-dir');
 
-const VERSION = '1.36.187';
+const VERSION = '1.36.188';
 
 // MCP lifecycle 주소 표식은 현재 CLI 호출 한 번에만 유효하다. CLI bootstrap에서 즉시 env에서
 // 떼어 두어 `--no-record`/hook처럼 presence 기록 함수에 도달하지 않는 경로도 후속 child에 유출하지 않는다.
@@ -893,7 +893,7 @@ function _errorUiLang(root, command) {
   const parsed = nonFlagArgs();
   const resolvedCommand = command || parsed[0];
   if (resolvedCommand === 'mode' && has('--json')) return 'ko';
-  if (resolvedCommand === 'state' && ['inspect', 'compatibility'].includes(parsed[1])) return _inspectionUiLang();
+  if (resolvedCommand === 'state' && ['inspect', 'compatibility', 'stores'].includes(parsed[1])) return _inspectionUiLang();
   return _uiLang(resolvedCommand === 'mode' ? _modeRoot(parsed, root) : root);
 }
 function _inspectionUiLang() {
@@ -11563,6 +11563,7 @@ function commandsCmd(root) {
       { cmd: 'state show|start|record|verify|handoff', desc: '.leerness/ JSON 상태 substrate (에이전트 간 인수인계 표준) — 1.9.278', descEn: '.leerness/ JSON state substrate (cross-agent handoff standard) — 1.9.278' },
       { cmd: 'state inspect [path] [--json]', desc: '5-scope 현재/제안 경로와 기존 상태 목록 — 읽기 전용, 이동·활성화 없음', descEn: 'five-scope current/proposed paths and legacy inventory — read-only, no migration or activation' },
       { cmd: 'state compatibility [path] [--json]', desc: '관측한 runtime layout의 쓰기 호환성 — 읽기 전용, 이동·활성화 없음', descEn: 'observed runtime-layout write compatibility — read-only, no migration or activation' },
+      { cmd: 'state stores [path] [--json]', desc: '결정·교훈·역할 저장소 상태와 fallback — 읽기 전용, 본문 비노출', descEn: 'decision, lesson and role store status and fallback — read-only, no payload output' },
       { cmd: 'adapter <tool>|list [--dry-run]', desc: '도구별 지침/.mcp.json 선택 생성 (claude/cursor/codex/goose/...) — 1.9.280', descEn: 'generate per-tool instructions/.mcp.json selectively (claude/cursor/codex/goose/...) — 1.9.280' },
       { cmd: 'ci init [path] [--force]', desc: 'PR 마다 leerness gate 실행하는 GitHub Actions 워크플로 생성 (.github/workflows/leerness-gate.yml) — 1.9.444', descEn: 'create a GitHub Actions workflow that runs leerness gate on every PR (.github/workflows/leerness-gate.yml) — 1.9.444' },
       { cmd: 'export|prompt --target <agent>', desc: 'adapter 별칭 — 도구별 지침/계약 파일 생성 (claude/cursor/codex/agents-md/...) — 1.9.448', descEn: 'adapter alias — generate per-tool instruction/contract files (claude/cursor/codex/agents-md/...) — 1.9.448' },
@@ -12257,7 +12258,7 @@ const _OBSERVATION_ONLY_SUBCOMMANDS = new Map([
   ['lease', new Set(['list', 'check'])],
   ['roles', new Set(['validate'])],
   ['role', new Set(['validate'])],
-  ['state', new Set(['inspect', 'compatibility'])],
+  ['state', new Set(['inspect', 'compatibility', 'stores'])],
 ]);
 function _cliMutationClass(args, cmd) {
   if (cmd === 'mcp') return 'observation-only'; // server startup must not mutate its incidental cwd
@@ -15709,6 +15710,7 @@ const _STRICT_COMMAND_FLAGS = {
   'roles validate': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles validate [--path .] [--json]' },
   'state inspect': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'state inspect [path] [--path <path>] [--json]' },
   'state compatibility': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'state compatibility [path] [--path <path>] [--json]' },
+  'state stores': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'state stores [path] [--path <path>] [--json]' },
   'roles set': { allowed: ['--provider', '--to', '--model', '--model-family', '--policy', '--fallback-policy', '--candidate', '--candidate-family', '--remove-candidate', '--clear-candidates', '--persona', '--force'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles set <role> --provider <id> [--model <id>] [--policy strict|balanced|continuity]' },
   'roles unset': { allowed: [], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles unset <role> [--path .] [--json]' },
   'roles suggest': { allowed: ['--apply'], globals: [..._COMMON_COMMAND_FLAGS, '--json'], usage: 'roles suggest [--apply] [--path .] [--json]' },
@@ -15790,7 +15792,7 @@ function _validateRolesCommandShape(cmd, args) {
 }
 
 function _validateCommandFlags(cmd, args) {
-  if (cmd === 'state' && ['inspect', 'compatibility'].includes(args[1])) {
+  if (cmd === 'state' && ['inspect', 'compatibility', 'stores'].includes(args[1])) {
     if (!_rejectDuplicateValueFlags(['--path'])) return false;
     if (args.length > 3) {
       failJson(has('--json'), 'too_many_arguments', `Usage: state ${args[1]} [path] [--path <path>] [--json]`);
@@ -15809,7 +15811,7 @@ function _validateCommandFlags(cmd, args) {
   if (cmd === 'intent' && args[1] === 'expand') route = 'intent expand';
   if (cmd === 'lease') route = `lease ${args[1] == null ? 'list' : args[1]}`;
   if (roleSub) route = `roles ${roleSub === 'remove' || roleSub === 'rm' ? 'unset' : roleSub}`;
-  if (cmd === 'state' && ['inspect', 'compatibility'].includes(args[1])) route = `state ${args[1]}`;
+  if (cmd === 'state' && ['inspect', 'compatibility', 'stores'].includes(args[1])) route = `state ${args[1]}`;
   const cfg = _STRICT_COMMAND_FLAGS[route];
   if (!cfg) return true;
   return _rejectUnknownFlags(cfg.allowed, cfg.usage, { globals: cfg.globals });
@@ -29077,6 +29079,18 @@ function stateCompatibilityCmd(root) {
   return report;
 }
 
+function stateStoresCmd(root) {
+  try {
+    const { inspectStores, formatStoreDiagnostics } = require('../lib/store-diagnostics');
+    const report = inspectStores(root);
+    log(has('--json') ? JSON.stringify(report, null, 2) : formatStoreDiagnostics(report));
+    if (!report.ok) process.exitCode = 1;
+    return report;
+  } catch {
+    return failJson(has('--json'), 'store_diagnostics_failed', 'Store diagnostics could not be completed; no files were changed.');
+  }
+}
+
 // leerness state <show|start|record|verify|handoff>
 // 1.9.292 (UR-0031): get_project_context — 외부 에이전트 온보딩용 단일 집약 컨텍스트.
 //   1콜로 현재 작업/미답 요청/최근 결정/활성 룰/next-actions/memory/프로젝트 의도를 구조화 회수.
@@ -31986,6 +32000,7 @@ STATUS & DIAGNOSTICS
   status [path]                   Install status (files present)
   state inspect [path] [--json]   Read-only five-scope paths/inventory; no migration or runtime activation
   state compatibility [path] [--json]   Read-only observed-layout write admission; no activation
+  state stores [path] [--json]   Read-only decision/lesson/role diagnostics; no payload output
   health [path] | doctor [--json]   health: project state · doctor: CLI install/environment (no path arg)
   verify [path]                   Required-file verification
   which [--json]                  Resolve current binary/version (npm cache conflicts)
@@ -32069,6 +32084,7 @@ function help() {
   leerness lease acquire|release|list|check [file|lease-id] [--session KEY] [--ttl SEC] [--json]  # exact-file opt-in 협업 lease
   leerness state inspect [path] [--json]   # 5-scope 경로/목록 읽기 전용 진단 — 이동·활성화 없음
   leerness state compatibility [path] [--json]   # 관측 layout 쓰기 호환성 읽기 전용 진단 — 활성화 없음
+  leerness state stores [path] [--json]   # 결정/교훈/역할 상태·fallback 진단 — 읽기 전용, 본문 비노출
   leerness retro [path] [--days 7] [--all-apps] [--include p1,p2] [--json]  # 회고 (1.9.13~1.9.16)
   leerness insights [path] [--all-apps] [--include p1,p2] [--json]         # 누적 통계 (1.9.13~1.9.16)
   leerness brainstorm "<주제>" [--all-apps] [--include p1,p2] [--json]    # 브레인스토밍 (1.9.13~1.9.16)
@@ -32115,6 +32131,10 @@ async function main(runtimeEntered = false) {
     const explicit = arg('--path', null);
     return stateCompatibilityCmd(explicit !== null ? explicit : args[2] === undefined ? process.cwd() : args[2]);
   }
+  if (cmd === 'state' && args[1] === 'stores') {
+    const explicit = arg('--path', null);
+    return stateStoresCmd(explicit !== null ? explicit : args[2] === undefined ? process.cwd() : args[2]);
+  }
   const runtimeRoot = _runtimeProjectRoot(args, cmd);
   if (!runtimeEntered && runtimeRoot && !_mustRemainReadOnly(args, cmd)) {
     return withRuntimeWrites(runtimeRoot, () => main(true));
@@ -33296,7 +33316,7 @@ async function main(runtimeEntered = false) {
 
 const skillCatalog = (() => {
   const args = nonFlagArgs();
-  if (require.main === module && args[0] === 'state' && ['inspect', 'compatibility'].includes(args[1])) {
+  if (require.main === module && args[0] === 'state' && ['inspect', 'compatibility', 'stores'].includes(args[1])) {
     return _withBuiltinSource(BUILTIN_CATALOG);
   }
   return _loadSkillCatalog();

package/docs/state-paths-api.md

@@ -4,6 +4,11 @@ Available in v1.36.186. T-0174 / P-0020 is an additive inspection-only foundatio
 It does not move data or activate a new backend. The complete staged design is in
 [State scopes and migration](state-scopes.md).
 
+This API inventories path metadata, not payload validity. A successful inspection
+does not imply that the stores contain valid JSON or domain records. See the
+[store observation boundaries and staged contract](store-observation-contract.md)
+for existing validator differences, and the [separate store diagnostic candidate](store-diagnostics-api.md).
+
 ## CLI
 
 ```sh

package/docs/store-diagnostics-api.md

@@ -0,0 +1,67 @@
+# Store diagnostics API v1
+
+Implementation candidate for T-0192 / P-0022. Publication is tracked separately.
+
+```sh
+leerness state stores ./project --json
+leerness state stores --path ./project
+```
+
+This separate command reads only decisions, lessons and roles in the selected
+workspace. `state inspect` remains metadata-only. Explicit `--path` takes precedence
+over the optional positional directory. Duplicate paths, extra positional arguments
+and unsupported write flags fail before ordinary startup bookkeeping.
+
+`inspectStores(root, options)` is exported by `lib/store-diagnostics.js`; options
+are passed to the existing `resolveStatePaths` resolver. It resolves the selected
+workspace, not all worktrees or every native runtime authority. A legacy workspace
+is diagnosed in place without migration. No provider or model call is made.
+
+## Result
+
+The single JSON document has schema `leerness.store-diagnostics/v1`, `ok`,
+`readOnly:true`, `writesPerformed:false`, `workspace`, `warnings`, and three `stores`.
+Each row identifies the fixed filename and contains:
+
+- `canonical.status`: `valid`, `missing`, `invalid_json`, `invalid_shape`,
+  `unreadable`, `unsupported`, or `unknown`.
+- `reasonCode` and actual `bytesRead` inside `canonical`; no original text or parse
+  error excerpt is included. `syntaxValid`, `shapeValid`, `itemsValid` are tri-state.
+- `effectiveSource`: source selected by this diagnostic (`canonical`,
+  `legacy_markdown`, `none`), not an authorization to write or switch runtime authority.
+- `fallback`: whether the diagnostic attempted/used bounded Markdown parsing, its
+  status and (when attempted) read metadata. It does not execute the legacy loader.
+- `itemCount`: parsed array/Markdown count or validated role count, otherwise null.
+
+Missing optional data is allowed. An invalid canonical file keeps `ok:false` even
+when Markdown is available. CLI exit is 0 only when `ok:true`; failed discovery
+returns a generic `store_diagnostics_failed` envelope and exit 1. For each memory
+store, fallback is attempted only on missing, syntax-error or non-array JSON.
+Unreadable, unsupported and changing sources do not trigger fallback. This is
+deliberately stricter than the existing resilient memory loader, which is unchanged.
+
+Memory JSON validates array shape only: `itemsValid:null` even for an empty array.
+This is not full item validation or a semantic-health certificate. Roles reuse the
+pure legacy role schema and extended role-definition validator. Markdown uses the
+existing pure parsers; readable text with no matching entries can yield count zero.
+
+## Read and scope limits
+
+Each file is limited to 1 MiB; the reader consumes at most limit+1 bytes to detect
+growth/overflow. Size checks alone are not relied on. It uses strict UTF-8 and
+rejects observed linked/non-regular/multiply-linked files and linked workspace
+parents. File/parent identity and file metadata are compared around the read;
+observed changes fail rather than certify an unstable snapshot. These checks are
+not a portable filesystem transaction, writer lease or guarantee against every
+hostile concurrent filesystem action.
+
+Only selected known files are covered, with no recursive scan, automatic repair,
+archive append, usage write, presence update or migration. The diagnostic performs
+no content writes; ordinary filesystem access-time effects are not a content/mtime
+immutability guarantee. Existing mutation commands and their late save guards are
+unchanged. See [the broader observation contract](store-observation-contract.md).
+
+Run `npm run test:store-diagnostics` for the focused functional checks. This suite
+also runs through `test:state-scopes`, hence through the existing fast/full gates.
+Its ordinary fixtures test schema/fallback/size/encoding/privacy and CLI zero-write
+behavior; it is not an adversarial filesystem or OS-permission coverage claim.

package/docs/store-observation-contract.md

@@ -0,0 +1,94 @@
+# Store observation: current boundaries and staged changes
+
+T-0187-B / T-0191. Source baseline: product code at `70b2a124`; the later
+`7694fb8` commit changes verification documentation only. This is a bounded
+inventory and implementation contract, not a claim that the proposed API exists.
+
+Update: the T-0192 implementation candidate adds a separate `state stores` command.
+See [its exact API and remaining limits](store-diagnostics-api.md). The baseline
+table below describes pre-existing behavior; mutation admission and migration B
+remain unimplemented follow-ups.
+
+## Current behavior
+
+| Surface | What it observes | Missing / invalid / unreadable behavior | Boundary |
+| --- | --- | --- | --- |
+| `state inspect` / `inspectLegacyInventory` | Known paths, file kinds, sizes and times | `absent`, `unreadable`, or blocked parent metadata | Does not read payloads; `ok:true` does not validate store contents |
+| `findCorruptedStateJson` used by check/health/audit | Nonempty, readable, top-level `.leerness/*.json` syntax | Missing or unreadable directory returns no findings; unreadable/blank files are skipped | No recursive scan or schema validation; no findings is not proof every store was checked |
+| `readRoleStore` / `roles validate` | Role file boundaries, size checks before and after a whole-file read, strict UTF-8, JSON and role schema | Missing is explicit; malformed JSON, invalid shape and unreadable state are rejected separately | The read itself has no byte cap; this role schema does not apply to other stores |
+| `_loadDecisions`, `_loadLessons` | JSON array, otherwise Markdown fallback | Missing, malformed JSON, non-array JSON and caught JSON read errors can all fall back | Returned array does not identify the chosen source or canonical error; items are not fully schema-validated |
+| `_assertStoreParsable` | Existing JSON syntax at a save boundary | Parse/read failure becomes `E_STORE_CORRUPT`; valid JSON with wrong shape passes | A late save guard is not a multi-file transaction |
+| `state compatibility` | Fixed runtime layout descriptor and admission conditions | Missing compatible legacy layout differs from unsupported/unreadable conditions via `reasonCode` | Compatibility-only; no payload migration, runtime activation or memory validation |
+
+Sources: [inventory](../lib/state-inventory.js), [inspection](../lib/state-inspect.js),
+[integrity](../lib/state-integrity.js), [roles](../lib/role-store.js),
+[runtime layout](../lib/runtime-layout.js), and the `_loadDecisions`, `_loadLessons`,
+`_assertStoreParsable`, `lessonDropCmd`, `decisionDropCmd`, `memoryRestoreCmd`
+functions in [the CLI](../bin/leerness.js). Function names are navigation anchors,
+not a promise that these internal functions are public exports.
+
+### Legacy memory needs separate read and write contracts
+
+- A readable JSON array wins over Markdown, even if individual items are unsuitable.
+- A non-array JSON document is parseable but is not a valid memory array; the loader
+  falls back while the syntax-only save guard permits it.
+- Blank JSON falls back on read and fails the save guard, yet the integrity scan skips it.
+- JSON read exceptions are caught by the loader; Markdown read exceptions are not.
+  `existsSync` false is not a positively observed `ENOENT` reason.
+- Add/save can exit on deduplication before reaching the save guard. A successful
+  no-op therefore does not certify the canonical file.
+- Drop appends to the archive before the final save guard. Restore appends to active
+  Markdown before the final save guard. Refusing the canonical save does not undo
+  those earlier writes. JSON then Markdown saves are sequential, not transactional.
+
+The ordering and fallback statements above are source observations, not destructive
+tests against user data. Do not activate migration B assuming zero mutation on failure.
+
+## Proposed observation contract — not implemented
+
+Keep `state inspect` metadata-only. Add a separately requested, read-only store
+diagnostic surface in a later implementation; do not silently add payload reads to
+the existing command. Start with decisions, lessons and roles, not arbitrary files.
+
+Each domain adapter should describe these independent facts:
+
+| Axis | Proposed values / rule |
+| --- | --- |
+| Canonical observation | `missing`, `valid`, `invalid_json`, `invalid_shape`, `unreadable`, `unsupported`, `unknown`; preserve the native domain reason code |
+| Effective source | `canonical`, `legacy_markdown`, `none`; no silent switch of authority |
+| Fallback | Explicit attempted/used state and reason; fallback availability does not make canonical data valid |
+| Validation | Separate syntax, schema and item validation; unperformed checks are unknown, not true |
+| Coverage | Enumerated stores, skipped stores and reason, bytes/limits; no “all healthy” from an empty findings list |
+| Write effects | Zero for the diagnostic itself; not a promise about separate mutation commands |
+
+These labels are design vocabulary, not existing wire fields. Public output should
+contain paths/allowlisted codes and bounded metadata, not memory text, parse-error
+excerpts, credentials, prompts or provider output. Missing optional data is not a
+failure; inability to determine its state must not become success. Preserve existing
+read fallback until an explicit compatibility change is implemented and tested.
+
+Reuse domain validators and scope resolution. Avoid a universal schema or recursive
+payload scan. A role-validator error must remain an error; an array-only legacy
+memory read must not be advertised as complete item validation. Before parsing,
+require bounded regular-file reads, appropriate link/identity checks and strict
+decoding. Reuse pure domain schema validation on bounded input; do not assume the
+current `readRoleStore` whole-file read enforces a physical read cap during growth.
+A diagnostic snapshot is not a writer lease or a durable authority.
+
+## Implementation order and acceptance gates
+
+1. **Observability:** separate read-only diagnostics, preserving existing metadata-only
+   behavior. Check valid/absent/blank/syntax/shape/read-error/oversize inputs and
+   effective-source provenance; assert original bytes, file set and mtimes unchanged.
+2. **Memory mutation admission:** validate the canonical source inside the operation's
+   lock and before archive, projection, log or canonical writes. Retest add, dedup,
+   drop and restore. Handle concurrent replacement and failed later writes explicitly;
+   an early check alone does not create a transaction.
+3. **Migration B:** reuse the validated source-selection contract. Refuse uncertain
+   canonical authority, retain originals and evidence, and prove rollback and legacy
+   writer admission. Only then advance runtime activation.
+
+Characterization checks of today's skip behavior document a gap; they are not an
+acceptance requirement to preserve that gap forever. New diagnostics require new
+tests for explicit unknown/error reporting. Existing role/runtime guards must not
+be weakened, and a source inventory is not a complete writer audit.

package/docs/verification-evidence.md

@@ -0,0 +1,67 @@
+# Verification evidence: what a passing check means
+
+This guide describes the existing single-task `verify-claim --json` contract. It does not introduce a new verifier or change exit codes. 한국어 요약은 아래에 있습니다.
+
+## Read the result, not just the label
+
+| Field | Meaning | Not a guarantee of |
+| --- | --- | --- |
+| `ok`, `reasons` | Overall result of the applicable claim checks | Correct requirements, complete coverage, production readiness |
+| `semanticVerified: false` | Semantic correctness is not established by this verifier | A hidden semantic review having passed |
+| `evidenceLevel: "static"` | No non-skipped test-run result was collected | Tests passing; absence of every other kind of execution |
+| `evidenceLevel: "executed"` | A non-skipped test-run result was collected, including failed runs | A successful run |
+| `run.skipped` | The selected test execution was skipped; inspect `reason` | A test failure or success |
+| `run.allPassed` | Exit status was zero and, if parsed, the reporter's passed/total counts agree | Meaningful tests, sufficient coverage, or any particular number when `parsed` is null |
+| `verdict.testCountMatch: null` | No applicable count comparison was made | A passing count comparison |
+
+Without `--run-tests`, `run` is absent. With it, command selection is `--test-cmd`, then `.leerness/leerness-config.json`'s `testCommand`, then an available non-placeholder `npm test`, otherwise skip. A blocked command also skips. A skipped run stays `static` and does not itself add `tests-failed`; other checks can still fail.
+
+An executed failure stays `executed` and contributes `tests-failed`. An exit-zero command with output the parser cannot recognize can have `parsed: null` and `allPassed: true`. Report that as successful command execution with unknown parsed test count, not “all requirements tested.” Only run commands from a workspace you trust: `--run-tests` executes project code.
+
+These two boundary fields are present in the single-task JSON result, not promised for each `--all` aggregate entry. Static source checks count recognized declaration patterns; they do not run tests or establish coverage. Git checks compare working changes, not a reviewer's approval of a particular commit.
+
+## A small executable example
+
+Use a disposable directory outside your real project, initialize it with `leerness init . --minimal --yes`, and create these two files. The example assumes Node.js and an installed `leerness` CLI.
+
+`sum.cjs`:
+
+```js
+module.exports = (a, b) => a + b;
+```
+
+`sum.test.cjs`:
+
+```js
+const assert = require('node:assert/strict');
+const sum = require('./sum.cjs');
+assert.equal(sum(2, 3), 5);
+console.log('1/1 passed');
+```
+
+Register a task and substitute its actual printed ID for `T-0001` below. Record only what you actually ran; the first check deliberately makes no passing-test claim.
+
+```sh
+leerness task add "Implement integer addition"
+leerness task update T-0001 --status done --evidence "Files: sum.cjs, sum.test.cjs"
+leerness verify-claim T-0001 --json
+leerness verify-claim T-0001 --run-tests --test-cmd "node sum.test.cjs" --json
+```
+
+The first result is `static`, with no `run`. The second is `executed`; for the supplied assertion, expect `run.exitCode: 0`, `run.allPassed: true`, and parsed count 1/1. Both retain `semanticVerified: false`. These are expected observations in the isolated example, not universal pass promises for an existing project's other evidence checks.
+
+Now change the expected value from `5` to `6` in the disposable test and rerun the second command. The assertion fails: expect a nonzero CLI exit, `ok: false`, `executed`, and `tests-failed`. Restore `5` and rerun before recording success. Do not use a command that merely prints a pass count as proof of test quality.
+
+## Keep an auditable handoff
+
+Alongside the claim, record the project/worktree and commit tested, exact command, exit status, parsed count or “unavailable,” log location, and known exclusions. Keep failed and skipped attempts distinct from subsequent success. Review should identify the exact commit reviewed. These are reporting practices, not fields automatically guaranteed by every existing command.
+
+For a sibling repository, run its tests there. Do not pretend its paths are relative to the current repository. A local evidence document can reference the external commit and logs, but verifying that document's existence does not rerun or validate the sibling implementation.
+
+## 한국어 요약
+
+- `ok`는 적용된 검사 결과이고 `executed`는 실행 여부의 분류입니다. 실패도 `executed`입니다.
+- 미실행은 `run.skipped`와 사유를 확인합니다. `null`은 미측정/비적용이지 통과가 아닙니다.
+- 종료 코드가 0이어도 `parsed: null`이면 테스트 개수는 미확인입니다. 요구사항 충족이나 테스트 품질을 증명하지 않습니다.
+- 위 예제는 실제 assertion 성공/실패를 비교합니다. 정적 검사와 실행 결과를 섞지 말고 명령·종료 코드·검증한 commit·미검증 범위를 함께 기록합니다.
+- `semanticVerified`는 계속 `false`이며, 이 가이드는 현재 계약을 설명할 뿐 새 의미론 검증이나 migration 활성화를 구현하지 않습니다.

package/lib/store-diagnostic-read.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { TextDecoder } = require('util');
+const MAX_BYTES = 1024 * 1024;
+const NAMES = new Set(['decisions.json', 'lessons.json', 'agent-roles.json', 'decisions.md', 'lessons.md']);
+const identity = (a, b) => a.dev === b.dev && a.ino === b.ino && a.mode === b.mode;
+const snapshot = (a, b) => identity(a, b) && a.size === b.size
+  && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && a.nlink === b.nlink;
+const regular = stat => stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1n;
+
+// 고정된 최상위 파일만 읽는다. 반환 text는 내부용이며 공개 보고서에 복사하지 않는다.
+const readStoreFile = (workspace, name) => {
+  let fd = null;
+  let bytesRead = 0;
+  const fail = (status, reasonCode) => ({ status, reasonCode, bytesRead });
+  if (!NAMES.has(name)) return fail('unsupported', 'store_not_supported');
+  const file = path.join(workspace, name);
+  try {
+    let parent;
+    try { parent = fs.lstatSync(workspace, { bigint: true }); }
+    catch (error) { return fail(error.code === 'ENOENT' ? 'missing' : 'unreadable', 'workspace_unavailable'); }
+    if (parent.isSymbolicLink() || !parent.isDirectory()) return fail('unsupported', 'workspace_type');
+    const parentStable = () => {
+      const now = fs.lstatSync(workspace, { bigint: true });
+      return now.isDirectory() && !now.isSymbolicLink() && identity(parent, now);
+    };
+    let before;
+    try { before = fs.lstatSync(file, { bigint: true }); }
+    catch (error) {
+      if (!parentStable()) return fail('unknown', 'workspace_changed');
+      return fail(error.code === 'ENOENT' ? 'missing' : 'unreadable', error.code === 'ENOENT' ? 'file_missing' : 'stat_failed');
+    }
+    if (!regular(before)) return fail('unsupported', 'file_type_or_links');
+    if (before.size > BigInt(MAX_BYTES)) return fail('unsupported', 'size_limit');
+    const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0) | (fs.constants.O_NONBLOCK || 0);
+    fd = fs.openSync(file, flags);
+    const opened = fs.fstatSync(fd, { bigint: true });
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!parentStable() || !regular(opened) || !regular(current)
+      || !snapshot(before, opened) || !snapshot(opened, current)) return fail('unknown', 'changed_before_read');
+    // 크기 검사와 별개로 실제 I/O를 limit+1 바이트에서 중단한다.
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    while (bytesRead < buffer.length) {
+      const n = fs.readSync(fd, buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (n === 0) break;
+      bytesRead += n;
+    }
+    if (bytesRead > MAX_BYTES) return fail('unsupported', 'size_limit');
+    const after = fs.fstatSync(fd, { bigint: true });
+    const afterPath = fs.lstatSync(file, { bigint: true });
+    if (!parentStable() || !regular(afterPath) || !snapshot(opened, after)
+      || !snapshot(after, afterPath) || BigInt(bytesRead) !== after.size) return fail('unknown', 'changed_during_read');
+    let text;
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, bytesRead)); }
+    catch { return fail('unsupported', 'invalid_utf8'); }
+    return { status: 'valid', reasonCode: 'read_ok', bytesRead, text };
+  } catch {
+    return fail('unreadable', 'read_failed');
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+  }
+};
+
+module.exports = { readStoreFile, MAX_BYTES };

package/lib/store-diagnostics.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const { resolveStatePaths } = require('./state-paths');
+const { readStoreFile, MAX_BYTES } = require('./store-diagnostic-read');
+const { validateLegacyRoleStore } = require('./role-agent-schema');
+const { validateRoleDefinitionShape } = require('./role-fallback');
+const { _decisionsFromMd, _parseLessonEntries } = require('./pure-utils');
+
+const observeCanonical = (workspace, name, file) => {
+  const read = readStoreFile(workspace, file);
+  const result = { status: read.status, reasonCode: read.reasonCode, bytesRead: read.bytesRead,
+    syntaxValid: null, shapeValid: null, itemsValid: null };
+  if (read.status !== 'valid') return { canonical: result, count: null };
+  let document;
+  try { document = JSON.parse(read.text); result.syntaxValid = true; }
+  catch {
+    return { canonical: { ...result, status: 'invalid_json', reasonCode: 'json_syntax', syntaxValid: false }, count: null };
+  }
+  if (name !== 'roles') {
+    const valid = Array.isArray(document);
+    return { canonical: { ...result, shapeValid: valid,
+      status: valid ? 'valid' : 'invalid_shape', reasonCode: valid ? 'array_valid_items_unchecked' : 'array_required' },
+    count: valid ? document.length : null };
+  }
+  const shape = validateLegacyRoleStore(document);
+  const extended = shape.ok && Object.entries(document.roles).every(([role, value]) =>
+    validateRoleDefinitionShape(role, value, { allowLegacyProviderIds: true }).ok);
+  return { canonical: { ...result, shapeValid: shape.ok, itemsValid: shape.ok ? extended : null,
+    status: shape.ok && extended ? 'valid' : 'invalid_shape', reasonCode: shape.ok && extended ? 'role_schema_valid' : 'role_schema_invalid' },
+  count: shape.ok && extended ? Object.keys(document.roles).length : null };
+};
+
+const observeStore = (workspace, name, file) => {
+  const { canonical, count } = observeCanonical(workspace, name, file);
+  const row = { name, file, canonical, effectiveSource: canonical.status === 'valid' ? 'canonical' : 'none',
+    itemCount: count, fallback: { attempted: false, used: false, status: 'not_attempted' } };
+  if (name === 'roles' || !['missing', 'invalid_json', 'invalid_shape'].includes(canonical.status)) return row;
+  const fallback = readStoreFile(workspace, `${name}.md`);
+  row.fallback = { attempted: true, used: false, status: fallback.status,
+    reasonCode: fallback.reasonCode, bytesRead: fallback.bytesRead };
+  if (fallback.status !== 'valid') return row;
+  try {
+    const entries = (name === 'decisions' ? _decisionsFromMd : _parseLessonEntries)(fallback.text);
+    row.itemCount = entries.length;
+    row.effectiveSource = 'legacy_markdown';
+    row.fallback.used = true;
+  } catch {
+    row.fallback.status = 'unknown';
+    row.fallback.reasonCode = 'markdown_parse_failed';
+  }
+  return row;
+};
+
+const inspectStores = (root, options = {}) => {
+  const resolved = resolveStatePaths(root, options);
+  const workspace = resolved.workspace.selectedPath;
+  const stores = [['decisions', 'decisions.json'], ['lessons', 'lessons.json'], ['roles', 'agent-roles.json']]
+    .map(([name, file]) => observeStore(workspace, name, file));
+  const ok = stores.every(row => ['valid', 'missing'].includes(row.canonical.status)
+    && ['not_attempted', 'valid', 'missing'].includes(row.fallback.status));
+  return { schema: 'leerness.store-diagnostics/v1', schemaVersion: 1, ok,
+    projectRoot: resolved.projectRoot, workspace, readOnly: true, writesPerformed: false,
+    runtimeActivated: false, migrationAvailable: false, maxBytesPerFile: MAX_BYTES,
+    coverage: { stores: stores.length, recursive: false, memoryItemsValidated: false },
+    warnings: resolved.warnings, stores };
+};
+
+const formatStoreDiagnostics = report => [
+  'Leerness store diagnostics (read-only; no migration)',
+  ...report.stores.map(row => `${row.name}: ${row.canonical.status} (${row.canonical.reasonCode}); source=${row.effectiveSource}; fallback=${row.fallback.status}`),
+  'Memory arrays are not item/schema validation. A diagnostic is not writer admission.',
+].join('\n');
+
+module.exports = { inspectStores, formatStoreDiagnostics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.36.187",
+  "version": "1.36.188",
   "description": "The AI-coding operations layer that makes \"done\" require evidence — persistent memory, evidence-gated completion checks, and clean handoffs for any AI agent (Claude Code, Codex, Cursor). State lives as plain files in your repo. CLI + MCP, 0 runtime dependencies.",
   "keywords": [
     "leerness",
@@ -70,7 +70,8 @@
     "test:role-agent-schema": "node ./scripts/role-agent-schema-probe.js",
     "test:role-store-loader": "node ./scripts/role-store-loader-probe.js",
     "test:role-fallback": "node ./scripts/role-fallback-probe.js",
-    "test:state-scopes": "node ./scripts/workspace-selection-probe.js && node ./scripts/state-scopes-probe.js && node ./scripts/state-inspect-cli-probe.js",
+    "test:store-diagnostics": "node ./scripts/store-diagnostic-probe.js",
+    "test:state-scopes": "node ./scripts/workspace-selection-probe.js && node ./scripts/state-scopes-probe.js && node ./scripts/state-inspect-cli-probe.js && npm run test:store-diagnostics",
     "test:runtime-compatibility": "node ./scripts/runtime-layout-probe.js && node ./scripts/runtime-admission-probe.js && node ./scripts/runtime-write-probe.js && node ./scripts/runtime-repl-probe.js && node ./scripts/runtime-git-write-probe.js && node ./scripts/runtime-replacement-probe.js && node ./scripts/encoding-selftest-probe.js && node ./scripts/selftest-cleanup-probe.js"
   },
   "publishConfig": {

package/scripts/command-flags-probe.js

@@ -72,7 +72,7 @@ const catalog = run(['commands', '--json']);
 const catalogJson = json(catalog);
 const catalogRows = catalogJson?.categories ? Object.values(catalogJson.categories).flat() : [];
 check('commands --json returns the machine-readable catalog',
-  catalog.status === 0 && catalogJson?.totalCommands === 102 && catalogJson?.categories && !catalog.stderr,
+  catalog.status === 0 && catalogJson?.totalCommands === 103 && catalogJson?.categories && !catalog.stderr,
   catalog);
 check('commands totalCommands equals the category sum',
   catalogJson?.totalCommands === catalogRows.length,
@@ -80,7 +80,8 @@ check('commands totalCommands equals the category sum',
 check('commands catalog includes verify-code, contract verify, and exact-file lease',
   catalogRows.some(row => /^verify-code\b/.test(row.cmd))
     && catalogRows.some(row => /^contract verify\b/.test(row.cmd))
-    && catalogRows.some(row => /^lease acquire\|release\|list\|check\b/.test(row.cmd)),
+    && catalogRows.some(row => /^lease acquire\|release\|list\|check\b/.test(row.cmd))
+    && catalogRows.some(row => /^state stores\b/.test(row.cmd)),
   catalog);
 
 const englishCatalog = run(['commands', '--language', 'en', '--json']);

package/scripts/store-diagnostic-probe.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+'use strict';
+
+// Functional contract checks using only disposable, locally owned fixtures.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const cp = require('child_process');
+const vm = require('vm');
+const { inspectStores } = require('../lib/store-diagnostics');
+const { _shouldDrop } = require('../lib/git');
+const CLI = path.resolve(__dirname, '../bin/leerness.js');
+const tempRoot = fs.realpathSync.native(os.tmpdir());
+const fixture = fs.mkdtempSync(path.join(tempRoot, 'leerness-store-diagnostic-'));
+const fixtureIdentity = fs.realpathSync.native(fixture);
+const LIMIT = 1024 * 1024;
+const PRIVATE = 'synthetic-private-fixture-content';
+let passed = 0;
+
+function check(label, action) {
+  action();
+  passed++;
+  console.log(`PASS ${label}`);
+}
+
+function project(name, files = {}) {
+  const root = path.join(fixture, name);
+  fs.mkdirSync(path.join(root, '.leerness'), { recursive: true });
+  for (const [file, content] of Object.entries(files)) {
+    fs.writeFileSync(path.join(root, '.leerness', file), content);
+  }
+  return root;
+}
+
+function snapshot(root) {
+  const rows = {};
+  function visit(file, relative) {
+    const stat = fs.lstatSync(file);
+    const row = { mtimeMs: stat.mtimeMs, kind: stat.isDirectory() ? 'dir' : 'file' };
+    if (stat.isFile()) row.sha256 = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    rows[relative] = row;
+    if (stat.isDirectory()) for (const name of fs.readdirSync(file).sort()) visit(path.join(file, name), `${relative}/${name}`);
+  }
+  visit(root, '.');
+  return rows;
+}
+
+function inspect(root) {
+  const before = snapshot(fixture);
+  const result = inspectStores(root);
+  assert.strictEqual(result.schema, 'leerness.store-diagnostics/v1');
+  assert.strictEqual(result.readOnly, true);
+  assert.strictEqual(result.writesPerformed, false);
+  assert.strictEqual(typeof result.ok, 'boolean');
+  assert.deepStrictEqual(result.stores.map(row => row.name).sort(), ['decisions', 'lessons', 'roles']);
+  assert.deepStrictEqual(snapshot(fixture), before, 'inspection must preserve file set, hashes and mtimes');
+  assert(!JSON.stringify(result).includes(PRIVATE), 'raw fixture content must not appear in diagnostics');
+  return result;
+}
+
+function row(report, name) { return report.stores.find(store => store.name === name); }
+const legacy = {
+  'decisions.md': `# Decisions\n\n### 2026-09-08 — Fixture\n- Decision: ${PRIVATE}\n- Reason: test\n`,
+  'lessons.md': `# Lessons\n\n### 2026-09-08\n- Lesson: ${PRIVATE}\n- Tag: fixture\n`,
+};
+
+try {
+  function fakeRead(mode) {
+    const workspace = path.join(fixture, 'in-memory-workspace');
+    const regular = { dev: 1n, ino: 2n, mode: 1n, size: 2n, nlink: 1n,
+      mtimeNs: 1n, ctimeNs: 1n, isFile: () => true, isSymbolicLink: () => false };
+    const parent = { dev: 1n, ino: 1n, mode: 2n, isDirectory: () => true, isSymbolicLink: () => false };
+    const metrics = { requested: 0, consumed: 0, closes: 0 };
+    const fakeFs = {
+      constants: fs.constants,
+      lstatSync: file => file === workspace ? parent : regular,
+      openSync: () => 9,
+      fstatSync: () => regular,
+      readSync(fd, buffer, offset, length) {
+        assert.strictEqual(fd, 9);
+        metrics.requested += length;
+        assert(metrics.requested <= LIMIT + 1, 'actual I/O requests must remain bounded');
+        if (mode === 'denied') throw Object.assign(new Error('synthetic read failure'), { code: 'EACCES' });
+        buffer.fill(0x20, offset, offset + length);
+        metrics.consumed += length;
+        return length;
+      },
+      closeSync(fd) { assert.strictEqual(fd, 9); metrics.closes++; },
+    };
+    const module = { exports: {} };
+    vm.runInNewContext(fs.readFileSync(path.resolve(__dirname, '../lib/store-diagnostic-read.js'), 'utf8'), {
+      module, Buffer, require: name => name === 'fs' ? fakeFs : require(name),
+    }, { filename: 'store-diagnostic-read.js', timeout: 2000 });
+    assert.strictEqual(module.exports.MAX_BYTES, LIMIT);
+    return { result: module.exports.readStoreFile(workspace, 'decisions.json'), metrics };
+  }
+  check('in-memory continuous reader stops at the actual byte limit despite small metadata', () => {
+    const { result, metrics } = fakeRead('continuous');
+    assert.strictEqual(result.status, 'unsupported');
+    assert.strictEqual(result.reasonCode, 'size_limit');
+    assert.strictEqual(result.bytesRead, LIMIT + 1);
+    assert.strictEqual(metrics.requested, LIMIT + 1);
+    assert.strictEqual(metrics.consumed, LIMIT + 1);
+    assert.strictEqual(metrics.closes, 1);
+  });
+  check('in-memory read failure is unreadable and closes its descriptor once', () => {
+    const { result, metrics } = fakeRead('denied');
+    assert.strictEqual(result.status, 'unreadable');
+    assert.strictEqual(result.reasonCode, 'read_failed');
+    assert.strictEqual(result.bytesRead, 0);
+    assert.strictEqual(metrics.consumed, 0);
+    assert.strictEqual(metrics.closes, 1);
+  });
+  check('absent optional stores are missing, not invented empty canonical arrays', () => {
+    const report = inspect(project('absent'));
+    assert.strictEqual(report.ok, true);
+    for (const store of report.stores) {
+      assert.strictEqual(store.canonical.status, 'missing');
+      assert.strictEqual(store.effectiveSource, 'none');
+      assert.strictEqual(store.itemCount, null);
+    }
+  });
+  const valid = project('valid target 한글', {
+    'decisions.json': JSON.stringify([{ title: PRIVATE }]),
+    'lessons.json': '[]',
+    'agent-roles.json': JSON.stringify({ schemaVersion: 1, roles: { implementer: { provider: 'codex', model: 'fixture-model' } } }),
+    ...legacy,
+  });
+  check('valid canonical stores take precedence without reading fallback', () => {
+    const report = inspect(valid);
+    assert.strictEqual(report.ok, true);
+    for (const store of report.stores) {
+      assert.strictEqual(store.canonical.status, 'valid');
+      assert.strictEqual(store.canonical.syntaxValid, true);
+      assert.strictEqual(store.canonical.shapeValid, true);
+      assert.strictEqual(store.effectiveSource, 'canonical');
+      assert.strictEqual(store.fallback.attempted, false);
+      assert.strictEqual(store.fallback.used, false);
+      assert(store.canonical.bytesRead > 0);
+    }
+    assert.strictEqual(row(report, 'decisions').itemCount, 1);
+    assert.strictEqual(row(report, 'lessons').itemCount, 0);
+    assert.strictEqual(row(report, 'roles').itemCount, 1);
+    assert.strictEqual(row(report, 'decisions').canonical.itemsValid, null);
+    assert.strictEqual(row(report, 'lessons').canonical.itemsValid, null);
+    assert.strictEqual(row(report, 'roles').canonical.itemsValid, true);
+  });
+  check('memory array shape acceptance does not claim item validation', () => {
+    const report = inspect(project('array shape only', { 'decisions.json': '[null,1,"fixture"]' }));
+    assert.strictEqual(report.ok, true);
+    assert.strictEqual(row(report, 'decisions').canonical.itemsValid, null);
+    assert.strictEqual(row(report, 'decisions').itemCount, 3);
+  });
+  for (const [label, content, status, fallbackAllowed] of [
+    ['invalid JSON', '{', 'invalid_json', true],
+    ['object shape', '{}', 'invalid_shape', true],
+    ['blank', '   \n', 'invalid_json', true],
+    ['oversize', ' '.repeat(LIMIT + 100), 'unsupported', false],
+    ['invalid UTF8', Buffer.from([0xc3, 0x28]), 'unsupported', false],
+  ]) {
+    check(`${label}: explicit canonical failure remains visible with legacy files present`, () => {
+      const report = inspect(project(label, { 'decisions.json': content, 'lessons.json': content, ...legacy }));
+      assert.strictEqual(report.ok, false);
+      for (const name of ['decisions', 'lessons']) {
+        const store = row(report, name);
+        assert.strictEqual(store.canonical.status, status);
+        assert.strictEqual(typeof store.canonical.reasonCode, 'string');
+        assert(store.canonical.bytesRead <= LIMIT + 1);
+        assert.strictEqual(store.fallback.attempted, fallbackAllowed);
+        assert.strictEqual(store.fallback.used, fallbackAllowed);
+        assert.strictEqual(store.effectiveSource, fallbackAllowed ? 'legacy_markdown' : 'none');
+        assert.strictEqual(store.itemCount, fallbackAllowed ? 1 : null);
+      }
+    });
+  }
+  check('missing canonical files can report legacy counts without backfill', () => {
+    const report = inspect(project('legacy only', legacy));
+    assert.strictEqual(report.ok, true);
+    for (const name of ['decisions', 'lessons']) {
+      const store = row(report, name);
+      assert.strictEqual(store.canonical.status, 'missing');
+      assert.strictEqual(store.fallback.status, 'valid');
+      assert.strictEqual(store.fallback.used, true);
+      assert.strictEqual(store.itemCount, 1);
+    }
+  });
+  check('invalid role definitions are not accepted as valid assignments', () => {
+    const report = inspect(project('invalid roles', { 'agent-roles.json': JSON.stringify({ schemaVersion: 1, roles: { reviewer: { provider: 42 } } }) }));
+    assert.strictEqual(report.ok, false);
+    const store = row(report, 'roles');
+    assert.strictEqual(store.canonical.status, 'invalid_shape');
+    assert.strictEqual(store.canonical.syntaxValid, true);
+    assert.strictEqual(store.fallback.attempted, false);
+    assert.strictEqual(store.effectiveSource, 'none');
+    assert.strictEqual(store.itemCount, null);
+  });
+  check('invalid role schema versions remain explicit failures', () => {
+    const report = inspect(project('role schema', { 'agent-roles.json': '{"schemaVersion":999,"roles":{}}' }));
+    assert.strictEqual(report.ok, false);
+    assert.strictEqual(row(report, 'roles').canonical.status, 'invalid_shape');
+  });
+
+  const cwd = project('unrelated cwd', { 'current-state.md': 'Keep user state.\n', 'manifest.json': '{"language":"ko"}' });
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (/^(LEERNESS_|GIT_CONFIG_|NODE_OPTIONS)/i.test(key) || _shouldDrop(key)) delete env[key];
+  env.LEERNESS_LANG = 'en';
+  function cli(target, extra = []) {
+    return cp.spawnSync(process.execPath, [CLI, 'state', 'stores', target, ...extra, '--json'], { cwd, env, encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 });
+  }
+  check('real CLI from unrelated cwd preserves target and cwd file sets, hashes and mtimes', () => {
+    const before = snapshot(fixture);
+    const result = cli(valid);
+    assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+    assert.strictEqual(result.stderr, '');
+    const report = JSON.parse(result.stdout);
+    assert.strictEqual(report.schema, 'leerness.store-diagnostics/v1');
+    assert.strictEqual(report.ok, true);
+    assert.strictEqual(report.readOnly, true);
+    assert.strictEqual(report.writesPerformed, false);
+    assert.strictEqual(row(report, 'decisions').itemCount, 1);
+    assert(!result.stdout.includes(PRIVATE));
+    assert.deepStrictEqual(snapshot(fixture), before);
+  });
+  check('real CLI failed diagnostic keeps canonical failure despite successful fallback and writes nothing', () => {
+    const target = project('cli invalid', { 'decisions.json': '{', ...legacy });
+    const before = snapshot(fixture);
+    const result = cli(target);
+    assert.strictEqual(result.status, 1, result.stderr || result.stdout);
+    assert.strictEqual(result.stderr, '');
+    const report = JSON.parse(result.stdout);
+    assert.strictEqual(report.ok, false);
+    assert.strictEqual(row(report, 'decisions').canonical.status, 'invalid_json');
+    assert.strictEqual(row(report, 'decisions').fallback.used, true);
+    assert(!result.stdout.includes(PRIVATE));
+    assert.deepStrictEqual(snapshot(fixture), before);
+  });
+  for (const [label, args] of [
+    ['mutation flag', ['--apply']],
+    ['extra positional path', [cwd]],
+    ['duplicate explicit path', ['--path', valid, '--path', cwd]],
+  ]) {
+    check(`real CLI rejects ${label} without writes`, () => {
+      const before = snapshot(fixture);
+      const result = cli(valid, args);
+      assert.strictEqual(result.status, 1, result.stderr || result.stdout);
+      assert.strictEqual(result.stderr, '');
+      assert.strictEqual(JSON.parse(result.stdout).ok, false);
+      assert.deepStrictEqual(snapshot(fixture), before);
+    });
+  }
+  check('explicit --path overrides an unrelated positional root without writes', () => {
+    const before = snapshot(fixture);
+    const result = cli(cwd, ['--path', valid]);
+    assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+    assert.strictEqual(result.stderr, '');
+    const report = JSON.parse(result.stdout);
+    assert.strictEqual(report.ok, true);
+    assert.strictEqual(report.projectRoot, fs.realpathSync.native(valid));
+    assert.strictEqual(row(report, 'decisions').itemCount, 1);
+    assert.deepStrictEqual(snapshot(fixture), before);
+  });
+  console.log(`store-diagnostic probe: ${passed}/${passed} PASS`);
+} finally {
+  // Resolve and check the exact allocated directory before recursive removal.
+  const resolved = fs.realpathSync.native(fixture);
+  assert.strictEqual(resolved, fixtureIdentity);
+  assert.strictEqual(path.dirname(resolved), tempRoot);
+  assert(path.basename(resolved).startsWith('leerness-store-diagnostic-'));
+  fs.rmSync(resolved, { recursive: true, force: true });
+}