From 0ea43b7bdd840218738fe659948f32757caa96eb Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 16:41:08 +0900 Subject: [PATCH 1/9] docs(retrospect): document memory frontmatter taxonomy schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이슈 #942: 세션 메모리 frontmatter의 taxonomy 필드(node_type, type, originSessionId, hookable, hookKeywords, hookEvents, modified) 정규 위치를 stage4-execution.md의 기존 SoT 절에 명시. metadata: 중첩은 memory-hint 훅 파서(hooks/advisory-nudge/memory-hint/impl.py)의 정규식이 위치와 무관하게 매치하므로 런타임 오작동과 무관하며, 유일한 근거는 엔트리 간 일관성임을 문서에 그대로 기록. momentum: 필드는 별도 훅(momentum-rule-retrieval-gate)이 소비하는 독립 opt-in 메커니즘이라 taxonomy 블록 밖(top-level)에 유지하기로 확정 — 기존 3개 엔트리 전부 top-level인 자체 컨벤션과도 일치. cycle 17의 발견이 이슈 없이 cycle 18로 이월된 경위(.omc/state/ retrospect-hygiene-cursor.json 확인: gh issue create 미실행, cursor cycle_note로만 존재)도 같은 절에 기록. Confidence: high Not-tested: markdownlint-cli2 not installed locally — relies on CI advisory step; content correctness verified by re-reading rendered section --- .../retrospect/references/stage4-execution.md | 42 ++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/skills/retrospect/references/stage4-execution.md b/skills/retrospect/references/stage4-execution.md index a8f56179..644861b7 100644 --- a/skills/retrospect/references/stage4-execution.md +++ b/skills/retrospect/references/stage4-execution.md @@ -30,18 +30,46 @@ For each approved action: In addition to standard fields (`name`, `description`, `type`), every new memory MUST evaluate whether to include the `memory-hint` opt-in fields — `hookable` and `hookKeywords`. The full field spec (parser semantics, matching rules, fail-open contract) lives in `hooks/advisory-nudge/memory-hint/spec.md`; this section defines the authoring-time decision. The parser ignores `type` entirely and reads `hookable` / `hookKeywords` / `hookEvents` regardless of nesting depth (the regexes are indentation-tolerant), so place `type:` per your host's memory convention — this repo's on-disk memories nest taxonomy fields under `metadata:`. Only the opt-in fields' spelling and single-line list form matter for the hook. + **Canonical schema (issue #942).** The taxonomy block below is the full + field set this repo's memories converge on. Nesting these fields under + `metadata:` (vs. leaving them top-level) has **no runtime effect** — + `hooks/advisory-nudge/memory-hint/impl.py`'s regexes match either + position — so the *only* reason to enforce nesting is cross-entry + consistency: a reader (human or a future retrospect scan) should not have + to check two positions per field. `scripts/check-memory-frontmatter.py` + lints this shape and is wired into CI (see its docstring for what it does + and does not catch). + ```yaml --- name: my-memory description: Short rule statement metadata: # this repo nests taxonomy fields here + node_type: memory # fixed literal; present on nearly all existing entries type: feedback + originSessionId: # session the memory was authored in hookable: true # opt into PreToolUse surface hookKeywords: [keyword1, keyword2] # flat single-line list, whole-token (case-sensitive) hookEvents: [Bash, Edit] # optional; default [Bash] when omitted + modified: # optional; set on later edits + momentum: [merge] # opt-in, top-level — NOT a taxonomy field, see below --- ``` + **`momentum:` stays top-level — a deliberate exclusion, not a residual gap.** + `momentum` is a *different* opt-in mechanism (consumed by + `hooks/advisory-nudge/momentum-rule-retrieval-gate/impl.py`'s + `MOMENTUM_RE`, not by the memory-hint hook's `hookKeywords`/`hookEvents`) + with its own independent hook consumer — it answers "surface this memory + at a high-momentum action point" rather than "what kind of memory is + this", so it does not belong in the `metadata:` taxonomy block + conceptually. Practically: every existing `momentum:` entry (3/3, as of + issue #942's scan) is already top-level, so nesting it would be swimming + against its own 100%-consistent convention rather than fixing drift. + `scripts/check-memory-frontmatter.py` deliberately excludes `momentum` + from the fields it checks — this is the schema decision that exclusion + encodes, not an oversight. + **Category-based default (apply unless rationale documented):** | Category | `hookable` default | Rationale | @@ -58,9 +86,21 @@ For each approved action: - Whole-token, case-sensitive matching only (per `hooks/advisory-nudge/memory-hint/spec.md`). List multiple casings explicitly if needed (`[Edit, edit]`). - 1–4 keywords typical; >5 raises false-positive risk linearly. - **Avoid generic English words** (`add`, `run`, `test`, `update`) — they fire on unrelated commands and erode the hint signal. - - **`hookKeywords` must be a flat single-line list** (`[a, b]`). Multi-line YAML-block form (`- item` on separate lines) and scalar form (`hookKeywords: foo`) are silently skipped — the entire memory is then dropped (not indexed at all) and the hint never fires. Verify the list is single-line before committing. + - **`hookKeywords` must be a flat single-line list** (`[a, b]`). Multi-line YAML-block form (`- item` on separate lines) and scalar form (`hookKeywords: foo`) are silently skipped — the entire memory is then dropped (not indexed at all) and the hint never fires. Verify the list is single-line before committing. **This is not hypothetical** — issue #942's full-corpus scan found two `hookable: true` entries (`feedback_hook_flag_file_heredoc_timing.md`, `feedback_merge_ask_ci_comments_precheck.md`) shipped in the block-list form, so their hints had never fired despite `hookable: true` reading as "on". `scripts/check-memory-frontmatter.py` now catches this shape. - When the memory targets a non-Bash event, add `hookEvents:` to opt in — the memory-hint hook (`hooks/advisory-nudge/memory-hint/impl.py`) supports `[Bash, Edit, Write, NotebookEdit, AskUserQuestion]` (default `[Bash]` when omitted). Unsupported tool names in the list are dropped; if every listed event is unsupported the parser keeps the `[Bash]` default. + **Why cycle 17's finding recurred instead of closing (issue #942):** the + Stage 1.5 hygiene cursor (`.omc/state/retrospect-hygiene-cursor.json`, + gitignored local state) shows cycle 17 recorded the schema-drift family as + a carried `cycle_note` string only — no `gh issue create` action ran, so + the finding had nowhere to be closed *against*. It sat in the cursor's + carry-forward note, silently grew from 2 files to 4 across cycle + 17→18, and only became an issue (#942) once cycle 18 explicitly promoted + it. The gap this exposes: a carried `cycle_note` has no re-verification + path of its own (no CI, no lint, no issue to close) — `scripts/check-memory-frontmatter.py` + in CI is the structural fix, so the *next* drift of this family fails a + build instead of aging quietly in cursor state. + **⚠️ MANDATORY: Duplicate check before creating any memory file:** **Precondition:** This check applies ONLY when the finding's action type is `memory` (new pattern). If Stage 2 already marked `repeat=true` and escalated to issue/hook/global `~/.claude/CLAUDE.md` draft, skip this check — the escalation ladder takes precedence over merge. From 2360d14f1e2878dff87ee71fb2f0ebc50f2e7545 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 16:43:42 +0900 Subject: [PATCH 2/9] feat(scripts): add memory frontmatter lint script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이슈 #942. check-memory-frontmatter.py는 hooks/_lib/_memory_dir.py의 resolve_memory_dir()을 재사용해 memory-hint 훅과 동일한 경로 해석 순서(PRAXIS_MEMORY_DIR → CLAUDE_CONFIG_DIR → linked-worktree fallback)를 따른다. 검출 대상: taxonomy 필드의 top-level 배치, 필드 중복, 그리고 hookKeywords/hookEvents의 multi-line block form(memory-hint 파서가 묵살하고 해당 메모리 전체를 hint 인덱스에서 제외시키는 기능 결함). 메모리 디렉터리가 없으면(CI 등) SKIPPED을 출력하고 exit 0 — 단 PRAXIS_TESTS_STRICT=1일 때는 exit 1로 전환해 run-tests.sh의 기존 skip-is-not-pass 컨벤션(#917)을 그대로 따른다. tests/test_check_memory_frontmatter.py 11개 케이스: 정규화된 엔트리 clean, top-level 배치 검출, 중복 필드 검출, hookKeywords block/scalar form 검출, momentum 필드는 taxonomy 대상에서 제외됨을 확인, 그리고 디렉터리 부재 시 skip(strict 포함) 동작. Confidence: high Not-tested: markdownlint on the new files (tool not installed locally); ruff check ran clean --- scripts/check-memory-frontmatter.py | 181 ++++++++++++++++++++ tests/test_check_memory_frontmatter.py | 220 +++++++++++++++++++++++++ 2 files changed, 401 insertions(+) create mode 100755 scripts/check-memory-frontmatter.py create mode 100644 tests/test_check_memory_frontmatter.py diff --git a/scripts/check-memory-frontmatter.py b/scripts/check-memory-frontmatter.py new file mode 100755 index 00000000..065fe275 --- /dev/null +++ b/scripts/check-memory-frontmatter.py @@ -0,0 +1,181 @@ +#!/usr/bin/env python3 +"""Lint session-memory frontmatter for taxonomy-field schema drift (issue #942). + +Background: this repo's on-disk session memories +(`$CLAUDE_CONFIG_DIR/projects//memory/*.md`) nest taxonomy fields +(`type`, `originSessionId`, `hookable`, `hookKeywords`, `hookEvents`, +`modified`, `node_type`) under a `metadata:` block by convention — see +`skills/retrospect/references/stage4-execution.md`. Nesting has NO runtime +effect on `hooks/advisory-nudge/memory-hint/impl.py` (its regexes match +either position); the only reason to enforce it is cross-entry consistency, +so a reader never has to check two positions per field. + +Two retrospect cycles (17 -> 18) flagged the same drift family without it +ever becoming a re-checkable artifact — the finding lived only in a carried +`cycle_note` string in `.omc/state/retrospect-hygiene-cursor.json`, which has +no CI and no issue to close against. This script is the structural fix: it +runs the same check every time instead of relying on a future retrospect +scan to notice again. + +Checks (one entry = one `*.md` file in the memory dir, `MEMORY.md` excluded): + 1. no taxonomy field at the top level of the frontmatter — each must live + under `metadata:` + 2. no taxonomy field duplicated (top-level + nested, or nested twice) + 3. `hookKeywords:` / `hookEvents:`, when present, use the single-line + bracket form (`[a, b]`). The multi-line YAML-block form (`hookKeywords:` + followed by `- item` lines) is a FUNCTIONAL bug, not just a style + drift: `hooks/advisory-nudge/memory-hint/impl.py`'s KEYWORDS_RE/EVENTS_RE + read the rest of the `key:` line only, find no `[`, and silently reject + the whole memory — `hookable: true` then never fires. Two entries in the + corpus shipped this way (issue #942 scan): the hint had been dark since + they were authored. + +Resolution: reuses `hooks/_lib/_memory_dir.py::resolve_memory_dir()`, so this +follows `PRAXIS_MEMORY_DIR` / `CLAUDE_CONFIG_DIR` exactly like the memory-hint +hook does — no separate path convention to drift from that one. + +Exit codes: 0 clean (or skipped, unless PRAXIS_TESTS_STRICT=1), 1 on any +violation (or on a skip under PRAXIS_TESTS_STRICT=1, matching the +skip-is-not-pass convention `scripts/run-tests.sh` already uses, #917). + +CI reality: the memory directory is a local, gitignored, per-user store and +does not exist in CI at all — so in CI this script always prints SKIPPED and +exits 0. It has enforcement value locally (a contributor normalizing memory +frontmatter) and as a component this repo's own tests exercise directly +(`tests/test_check_memory_frontmatter.py`, via `PRAXIS_MEMORY_DIR`). Wiring +it into `scripts/run-tests.sh` is a follow-up, deliberately not done here — +that file is shared with concurrently in-flight PRs. +""" +from __future__ import annotations + +import os +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO_ROOT / "hooks" / "_lib")) +from _memory_dir import resolve_memory_dir # type: ignore[import-not-found] # noqa: E402 + +FENCE_RE = re.compile(r"^---\s*$", re.MULTILINE) +KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$") + +# Fields this repo's convention requires nested under `metadata:`. +TAXONOMY_FIELDS = ( + "node_type", + "type", + "originSessionId", + "hookable", + "hookKeywords", + "hookEvents", + "modified", +) +# Fields that must use single-line `[a, b]` form — the memory-hint parser +# rejects any other shape outright (see module docstring, check 3). +BRACKET_FIELDS = ("hookKeywords", "hookEvents") + + +def frontmatter_block(raw: str) -> str | None: + """Return the text between the first two `---` fences, or None.""" + matches = list(FENCE_RE.finditer(raw)) + if len(matches) < 2: + return None + return raw[matches[0].end() : matches[1].start()] + + +def _indented_lines(block: str) -> list[tuple[int, str]]: + out = [] + for line in block.splitlines(): + if not line.strip(): + continue + indent = len(line) - len(line.lstrip(" ")) + out.append((indent, line.strip())) + return out + + +def check_file(path: Path) -> list[str]: + """Return a list of human-readable violations for one memory file.""" + raw = path.read_text(encoding="utf-8") + block = frontmatter_block(raw) + if block is None: + return ["missing `---`-fenced frontmatter block"] + + errors: list[str] = [] + # field -> list of (nested: bool, raw_value: str) + occurrences: dict[str, list[tuple[bool, str]]] = {} + in_metadata = False + + for indent, line in _indented_lines(block): + m = KEY_RE.match(line) + if not m: + continue # e.g. a `- item` list line, or free-text + key, value = m.group(1), m.group(2) + if indent == 0: + if key == "metadata": + in_metadata = True + continue + in_metadata = False + nested = in_metadata and indent > 0 + if key in TAXONOMY_FIELDS: + occurrences.setdefault(key, []).append((nested, value)) + + for field, occs in occurrences.items(): + if len(occs) > 1: + errors.append(f"`{field}` appears {len(occs)} times — must appear exactly once, nested under `metadata:`") + for nested, value in occs: + if not nested: + errors.append(f"`{field}` is at the top level — must nest under `metadata:`") + if field in BRACKET_FIELDS: + for _nested, value in occs: + value = value.strip() + if not value: + errors.append( + f"`{field}:` has no inline value (multi-line YAML-block `- item` form) — " + "the memory-hint parser rejects this shape and silently drops the entire " + "memory from the hint index; use single-line `[a, b]` form" + ) + elif not value.startswith("["): + errors.append( + f"`{field}: {value}` is scalar form, not `[a, b]` — the memory-hint parser " + "rejects this shape and silently drops the entire memory from the hint index" + ) + + return errors + + +def iter_memory_files(memory_dir: str) -> list[Path]: + return sorted(p for p in Path(memory_dir).glob("*.md") if p.name != "MEMORY.md") + + +def main() -> int: + strict = os.environ.get("PRAXIS_TESTS_STRICT", "0") == "1" + + memory_dir = resolve_memory_dir() + if not memory_dir: + print("SKIPPED: memory-frontmatter-lint (memory directory not found — expected in CI / a fresh checkout)") + return 1 if strict else 0 + + files = iter_memory_files(memory_dir) + if not files: + print(f"SKIPPED: memory-frontmatter-lint (no memory entries under {memory_dir})") + return 1 if strict else 0 + + total_errors = 0 + for path in files: + errors = check_file(path) + if errors: + total_errors += len(errors) + print(f"FAIL: {path.name}") + for err in errors: + print(f" - {err}") + + if total_errors: + print(f"\n{total_errors} frontmatter schema violation(s) across {len(files)} memory entries in {memory_dir}") + return 1 + + print(f"OK: {len(files)} memory entries in {memory_dir} — frontmatter schema clean") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_check_memory_frontmatter.py b/tests/test_check_memory_frontmatter.py new file mode 100644 index 00000000..62214d94 --- /dev/null +++ b/tests/test_check_memory_frontmatter.py @@ -0,0 +1,220 @@ +"""Tests for scripts/check-memory-frontmatter.py (issue #942). + +Covers the three shapes the script's docstring commits to: + - taxonomy fields at the top level (not nested under `metadata:`) fail + - a field duplicated across top-level + `metadata:` (or nested twice) fails + - `hookKeywords:` / `hookEvents:` in multi-line YAML-block or scalar form + fail — this is the functional-bug case, not just a style drift + - a normalized entry passes + - directory resolution honors `PRAXIS_MEMORY_DIR` and skips (rather than + erroring) when the directory is absent, matching resolve_memory_dir()'s + own contract +""" +from __future__ import annotations + +import importlib.util +import io +from contextlib import redirect_stdout +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent + +_spec = importlib.util.spec_from_file_location( + "check_memory_frontmatter", REPO_ROOT / "scripts" / "check-memory-frontmatter.py" +) +assert _spec and _spec.loader +check = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(check) + + +# --------------------------------------------------------------------------- +# check_file — pure frontmatter checker +# --------------------------------------------------------------------------- + +def _write(tmp_path: Path, name: str, content: str) -> Path: + p = tmp_path / name + p.write_text(content, encoding="utf-8") + return p + + +def test_normalized_entry_is_clean(tmp_path): + p = _write( + tmp_path, + "feedback_good.md", + """--- +name: good +description: test +metadata: + node_type: memory + type: feedback + hookable: true + hookKeywords: [foo, bar] + originSessionId: abc-123 +--- +body +""", + ) + assert check.check_file(p) == [] + + +def test_top_level_taxonomy_field_flagged(tmp_path): + p = _write( + tmp_path, + "feedback_bad.md", + """--- +name: bad +description: test +type: feedback +originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("`type`" in e and "top level" in e for e in errors), errors + assert any("`originSessionId`" in e and "top level" in e for e in errors), errors + + +def test_duplicate_field_top_level_and_metadata_flagged(tmp_path): + p = _write( + tmp_path, + "feedback_bad_dup.md", + """--- +name: bad-dup +description: test +type: feedback +metadata: + type: feedback + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("`type`" in e and "2 times" in e for e in errors), errors + + +def test_hookkeywords_block_form_flagged_as_functional_bug(tmp_path): + p = _write( + tmp_path, + "feedback_bad_blockform.md", + """--- +name: bad-blockform +description: test +metadata: + type: feedback + hookable: true + hookKeywords: + - foo + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("multi-line YAML-block" in e for e in errors), errors + + +def test_hookkeywords_scalar_form_flagged(tmp_path): + p = _write( + tmp_path, + "feedback_bad_scalar.md", + """--- +name: bad-scalar +description: test +metadata: + type: feedback + hookable: true + hookKeywords: kubectl + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("scalar form" in e for e in errors), errors + + +def test_missing_frontmatter_fence_flagged(tmp_path): + p = _write(tmp_path, "feedback_no_fence.md", "just prose, no frontmatter\n") + errors = check.check_file(p) + assert any("frontmatter" in e for e in errors), errors + + +def test_momentum_field_is_not_taxonomy(tmp_path): + # `momentum:` is a real top-level field in several existing entries and + # is deliberately out of scope — it must never be flagged. + p = _write( + tmp_path, + "feedback_momentum.md", + """--- +name: has-momentum +description: test +metadata: + type: feedback + originSessionId: abc-123 +momentum: [merge] +--- +body +""", + ) + assert check.check_file(p) == [] + + +# --------------------------------------------------------------------------- +# main() — directory resolution + skip contract +# --------------------------------------------------------------------------- + +def test_main_skips_when_directory_absent(tmp_path, monkeypatch): + monkeypatch.setenv("PRAXIS_MEMORY_DIR", str(tmp_path / "does-not-exist")) + monkeypatch.delenv("PRAXIS_TESTS_STRICT", raising=False) + out = io.StringIO() + with redirect_stdout(out): + rc = check.main() + assert rc == 0 + assert "SKIPPED" in out.getvalue() + + +def test_main_skip_is_failure_under_strict(tmp_path, monkeypatch): + monkeypatch.setenv("PRAXIS_MEMORY_DIR", str(tmp_path / "does-not-exist")) + monkeypatch.setenv("PRAXIS_TESTS_STRICT", "1") + out = io.StringIO() + with redirect_stdout(out): + rc = check.main() + assert rc == 1 + assert "SKIPPED" in out.getvalue() + + +def test_main_fails_on_drifted_entry(tmp_path, monkeypatch): + _write( + tmp_path, + "feedback_bad.md", + """--- +name: bad +description: test +type: feedback +originSessionId: abc-123 +--- +body +""", + ) + monkeypatch.setenv("PRAXIS_MEMORY_DIR", str(tmp_path)) + monkeypatch.delenv("PRAXIS_TESTS_STRICT", raising=False) + out = io.StringIO() + with redirect_stdout(out): + rc = check.main() + assert rc == 1 + assert "FAIL: feedback_bad.md" in out.getvalue() + + +def test_main_ignores_memory_md_index_file(tmp_path, monkeypatch): + # MEMORY.md is the index, not a memory entry — it has no frontmatter + # contract and must never be linted. + _write(tmp_path, "MEMORY.md", "- [foo](foo.md) — bar\n") + monkeypatch.setenv("PRAXIS_MEMORY_DIR", str(tmp_path)) + monkeypatch.delenv("PRAXIS_TESTS_STRICT", raising=False) + out = io.StringIO() + with redirect_stdout(out): + rc = check.main() + assert rc == 0 + assert "SKIPPED" in out.getvalue() # no *.md entries besides MEMORY.md From 1e876c1f44e3a4bbd5aff85dad4375e3dbc82498 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 16:43:53 +0900 Subject: [PATCH 3/9] ci: wire memory frontmatter lint into test job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이슈 #942 작업목록의 'CI 연결'. scripts/run-tests.sh는 병렬 진행 중인 다른 PR들과의 공유 파일이라 수정하지 않고(팀 합의), test job에 독립 스텝으로 python3 scripts/check-memory-frontmatter.py를 추가했다. 메모리 디렉터리는 로컬·per-user·gitignored 저장소라 CI 러너에는 존재하지 않는다 — 이 스텝은 CI에서 항상 SKIPPED을 출력하고 exit 0으로 통과한다. 체커 자체의 회귀 커버리지는 pytest tests/(run-tests.sh 1단계, 이 CI job에서 이미 실행됨)가 담당한다. run-tests.sh로의 편입은 후속 작업으로 남긴다. Confidence: high Not-tested: this ci.yml step always SKIPs on this runner (memory dir absent in CI by design) — actual CI green/red for this step has not been observed on a real GitHub Actions run yet, only reasoned from resolve_memory_dir()'s contract and local reproduction --- .github/workflows/ci.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bf58c4fb..d8204d08 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -109,6 +109,18 @@ jobs: - run: bash scripts/run-tests.sh env: PRAXIS_TESTS_STRICT: "1" + # Standalone step (issue #942), not folded into run-tests.sh: the memory + # dir it lints is a local, gitignored, per-user store + # ($CLAUDE_CONFIG_DIR/projects//memory/) that does not exist on + # this runner, so the script always prints SKIPPED here and exits 0 — + # its real enforcement runs on a contributor's machine, and unit + # coverage for the checker itself lives in + # tests/test_check_memory_frontmatter.py (already run by the pytest + # step above via `python3 -m pytest tests/` inside run-tests.sh). This + # step exists so the script's own CLI entrypoint — resolve_memory_dir(), + # the skip path, PRAXIS_TESTS_STRICT — gets exercised on every push, + # not just under pytest. + - run: python3 scripts/check-memory-frontmatter.py link-check: runs-on: ubuntu-latest From 2a0869b7bce1ce699938467c388b302e8bb2525a Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 16:50:46 +0900 Subject: [PATCH 4/9] docs(retrospect): mark node_type optional, not required MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이슈 #942 리뷰 지적: SoT 문서는 node_type을 '거의 모든 엔트리에 존재'로 서술해 사실상 필수처럼 읽혔지만, lint 스크립트는 부재를 드리프트로 잡지 않아 문서와 도구가 서로 다른 스키마를 말하고 있었다. grep -rn node_type로 이 레포의 모든 훅·스크립트를 확인한 결과 이 필드를 읽는 소비자가 전혀 없다 — type/hookable/hookKeywords/hookEvents와 달리 런타임에서 아무 의미가 없다. 따라서 (B) 선택: node_type을 선택 필드로 명시하고, 있으면 유지하되 없는 엔트리에 채워 넣지 않는다. lint 스크립트 docstring에도 동일하게 명시하고, 부재가 플래그되지 않음을 확인하는 테스트를 추가했다. Confidence: high Not-tested: markdownlint on the updated doc section (tool availability confirmed only after CI run) --- scripts/check-memory-frontmatter.py | 5 +++++ .../retrospect/references/stage4-execution.md | 13 ++++++++++++- tests/test_check_memory_frontmatter.py | 19 +++++++++++++++++++ 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/scripts/check-memory-frontmatter.py b/scripts/check-memory-frontmatter.py index 065fe275..325f1c81 100755 --- a/scripts/check-memory-frontmatter.py +++ b/scripts/check-memory-frontmatter.py @@ -10,6 +10,11 @@ either position); the only reason to enforce it is cross-entry consistency, so a reader never has to check two positions per field. +`node_type` is included in the taxonomy set for *position* checking (if +present, it must be nested and not duplicated, same as any other taxonomy +field) but is never required to be present — no hook in this repo reads it +(grep-verified). A memory missing `node_type` entirely is not drift. + Two retrospect cycles (17 -> 18) flagged the same drift family without it ever becoming a re-checkable artifact — the finding lived only in a carried `cycle_note` string in `.omc/state/retrospect-hygiene-cursor.json`, which has diff --git a/skills/retrospect/references/stage4-execution.md b/skills/retrospect/references/stage4-execution.md index 644861b7..98df89f6 100644 --- a/skills/retrospect/references/stage4-execution.md +++ b/skills/retrospect/references/stage4-execution.md @@ -45,7 +45,7 @@ For each approved action: name: my-memory description: Short rule statement metadata: # this repo nests taxonomy fields here - node_type: memory # fixed literal; present on nearly all existing entries + node_type: memory # optional; no hook reads it (grep-verified, issue #942) — carry it when present, don't backfill it when absent type: feedback originSessionId: # session the memory was authored in hookable: true # opt into PreToolUse surface @@ -70,6 +70,17 @@ For each approved action: from the fields it checks — this is the schema decision that exclusion encodes, not an oversight. + **`node_type: memory` is optional, not required.** `grep -rn node_type` + across every hook and script in this repo (issue #942) finds no + consumer at all — unlike `type`/`hookable`/`hookKeywords`/`hookEvents`, + nothing reads it. It is present on most existing entries (a fixed literal + from an earlier authoring convention) but its absence is inert: two + entries lack it entirely and `scripts/check-memory-frontmatter.py` + reports them clean, correctly, because there is nothing to enforce. + When authoring or normalizing a memory, carry `node_type: memory` if + it's already there — don't add it to a file that lacks it, and don't + treat its absence as drift. + **Category-based default (apply unless rationale documented):** | Category | `hookable` default | Rationale | diff --git a/tests/test_check_memory_frontmatter.py b/tests/test_check_memory_frontmatter.py index 62214d94..d5bbef35 100644 --- a/tests/test_check_memory_frontmatter.py +++ b/tests/test_check_memory_frontmatter.py @@ -161,6 +161,25 @@ def test_momentum_field_is_not_taxonomy(tmp_path): assert check.check_file(p) == [] +def test_missing_node_type_is_not_flagged(tmp_path): + # node_type has no consumer (grep-verified, issue #942) — its absence is + # optional, not drift. Two real entries in the corpus lack it entirely. + p = _write( + tmp_path, + "feedback_no_node_type.md", + """--- +name: no-node-type +description: test +metadata: + type: feedback + originSessionId: abc-123 +--- +body +""", + ) + assert check.check_file(p) == [] + + # --------------------------------------------------------------------------- # main() — directory resolution + skip contract # --------------------------------------------------------------------------- From 49dff44440af9b399b2d7029a2d4c0003081cf17 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 17:50:17 +0900 Subject: [PATCH 5/9] build(ci): wire memory frontmatter lint into run-tests.sh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이슈 #942의 근본 원인(재검증 경로 부재)을 해소한다. check-plugin-manifests.py / check-hook-token-invariants.py 두 sibling(repo-internal custom invariant script)이 모두 run-tests.sh 전용이고 독립 ci.yml job이 없다는 컨벤션을 확인 후 같은 패턴을 따른다. - run-tests.sh: step 5로 삽입, ruff/shellcheck/markdownlint를 6-8로 재번호 - PRAXIS_TESTS_STRICT는 이 호출에만 전달하지 않는다: 메모리 디렉터리는 CI/신규 체크아웃에 구조적으로 항상 부재하므로, strict 모드를 그대로 흘려보내면 CI가 영구적으로 실패한다. 실제 드리프트 탐지(exit 1)만 FAILED로 집계한다 - ci.yml test job의 독립 실행 스텝(python3 scripts/check-memory-frontmatter.py) 제거 — run-tests.sh 내부 호출과 중복 실행이었다 - 스코프 노트 (5-7)→(6-8) 오기 정정 Confidence: high Not-tested: GitHub Actions에서 이 변경이 실제로 그린인지는 push 후 CI 결과로만 확인 가능 (로컬은 shellcheck+bash -n+pytest로 검증) --- .github/workflows/ci.yml | 12 ----------- scripts/run-tests.sh | 45 +++++++++++++++++++++++++++++++++------- 2 files changed, 37 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d8204d08..bf58c4fb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -109,18 +109,6 @@ jobs: - run: bash scripts/run-tests.sh env: PRAXIS_TESTS_STRICT: "1" - # Standalone step (issue #942), not folded into run-tests.sh: the memory - # dir it lints is a local, gitignored, per-user store - # ($CLAUDE_CONFIG_DIR/projects//memory/) that does not exist on - # this runner, so the script always prints SKIPPED here and exits 0 — - # its real enforcement runs on a contributor's machine, and unit - # coverage for the checker itself lives in - # tests/test_check_memory_frontmatter.py (already run by the pytest - # step above via `python3 -m pytest tests/` inside run-tests.sh). This - # step exists so the script's own CLI entrypoint — resolve_memory_dir(), - # the skip path, PRAXIS_TESTS_STRICT — gets exercised on every push, - # not just under pytest. - - run: python3 scripts/check-memory-frontmatter.py link-check: runs-on: ubuntu-latest diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh index f64b9ebe..025b923c 100755 --- a/scripts/run-tests.sh +++ b/scripts/run-tests.sh @@ -6,15 +6,24 @@ # 2. shell — shell tests at tests/hooks/*/test_*.sh and tests/test_*.sh # 3. manifest — scripts/check-plugin-manifests.py # 4. invariants — scripts/check-hook-token-invariants.py -# 5. ruff — static Python lint (mirrors the ci.yml `ruff` job) -# 6. shellcheck — static shell lint (mirrors the ci.yml `shellcheck` job) -# 7. markdownlint — advisory markdown lint (mirrors the ci.yml `markdownlint` job) +# 5. memory-frontmatter — scripts/check-memory-frontmatter.py +# 6. ruff — static Python lint (mirrors the ci.yml `ruff` job) +# 7. shellcheck — static shell lint (mirrors the ci.yml `shellcheck` job) +# 8. markdownlint — advisory markdown lint (mirrors the ci.yml `markdownlint` job) # -# Steps 5-7 mirror CI jobs that used to have no local equivalent, so a change +# Steps 6-8 mirror CI jobs that used to have no local equivalent, so a change # could pass here and still be flagged on the PR (issue #866). Each skips with # an explicit SKIPPED line when its tool is absent, so a contributor without # the toolchain is not blocked — CI remains authoritative either way. # +# Step 5 is a different repo-internal script, same family as steps 3-4 (no +# external toolchain — nothing to install), but it has its own legitimate skip +# condition: the memory directory it lints is a local, gitignored, per-user +# store that does not exist in CI or a fresh checkout at all (issue #942). It +# prints its own SKIPPED line and exit code, honoring PRAXIS_TESTS_STRICT the +# same way steps 6-8 do — no skip_step() wiring needed here, so a nonzero exit +# is treated as FAILED like steps 3-4, not routed through the tool-skip path. +# # A skip is not a pass (#917). The SKIPPED line used to scroll past and the run # still ended on a bare "ALL TESTS PASSED", which read as full coverage: PR #912 # shipped 15 markdownlint violations that way, and PR #864 had shipped 23 for the @@ -123,7 +132,24 @@ if ! python3 ./scripts/check-hook-token-invariants.py; then fi # --------------------------------------------------------------------------- -# 5. Ruff (mirrors ci.yml `ruff` job — blocking there, blocking here) +# 5. Memory frontmatter lint (schema-drift guard, issue #942) +# --------------------------------------------------------------------------- +echo "" +echo "=== memory frontmatter lint ===" +# PRAXIS_TESTS_STRICT is deliberately NOT propagated to this one call: unlike +# steps 6-8 (a tool a contributor could install), the memory dir this checks +# is a local, gitignored, per-user store that structurally never exists in +# CI or a fresh checkout — treating its absence as a strict-mode failure +# would fail every CI run forever, not flag a fixable gap. A SKIPPED here is +# always benign; only actual detected drift (exit 1 with violations listed) +# fails this step. The script's own PRAXIS_TESTS_STRICT support still works +# for direct standalone invocation (see its tests / docstring). +if ! env -u PRAXIS_TESTS_STRICT python3 ./scripts/check-memory-frontmatter.py; then + FAILED=1 +fi + +# --------------------------------------------------------------------------- +# 6. Ruff (mirrors ci.yml `ruff` job — blocking there, blocking here) # --------------------------------------------------------------------------- echo "" echo "=== ruff ===" @@ -142,7 +168,7 @@ elif ! "${RUFF[@]}" check .; then fi # --------------------------------------------------------------------------- -# 6. Shellcheck (mirrors ci.yml `shellcheck` job — same find/severity) +# 7. Shellcheck (mirrors ci.yml `shellcheck` job — same find/severity) # --------------------------------------------------------------------------- echo "" echo "=== shellcheck ===" @@ -157,7 +183,7 @@ else fi # --------------------------------------------------------------------------- -# 7. Markdownlint (mirrors ci.yml `markdownlint` job) +# 8. Markdownlint (mirrors ci.yml `markdownlint` job) # # CI runs this with filter_mode:added and never fails the check, so the repo's # existing backlog stays untouched. The advisory half is mirrored exactly — a @@ -221,7 +247,10 @@ if [[ $FAILED -ne 0 ]]; then exit 1 fi -# Scope note: this counts the three tool steps this script owns (5-7). Gates +# Scope note: this counts the three tool steps this script owns (6-8). Step 5 +# has its own SKIPPED line but is deliberately excluded from this tally (see +# its PRAXIS_TESTS_STRICT note above) — it is never a missing-toolchain skip. +# Gates # that a sub-suite skips internally — e.g. the Darwin-only gate in # tests/test_codex_broker_reaper.sh — announce themselves in their own summary # and are not aggregated here; conflating them would make a portable-by-design From 09f6f620260d07d7a621acb57be59aa55a41ba8b Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 17:57:02 +0900 Subject: [PATCH 6/9] fix(scripts): distinguish structural memory-dir absence from a fixable skip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit team-lead 리뷰: CI에서 이 스텝은 매 런 SKIPPED를 출력하는데, 메모리 디렉터리는 CI에 구조적으로 항상 부재하므로 이 SKIPPED는 절대 해소되지 않는다. run-tests.sh 자신이 #917에서 지키려는 신호(SKIPPED = 고칠 수 있는 갭)를 이 상시 SKIPPED가 갉는다 — 이슈 #942 자체가 고발하는 '신호가 노이즈에 묻혀 안 읽힌다' 실패와 같은 계열. - check-memory-frontmatter.py: 두 skip 지점(디렉터리 부재/빈 디렉터리) 출력을 'SKIPPED:' → 'N/A:'로 변경. exit-code 시맨틱(strict 시 1, 아니면 0)은 유지 — 라벨만 분리, 동작은 불변 - 관련 docstring · run-tests.sh 헤더 코멘트 3곳 · step 5 인라인 코멘트 · 하단 scope note를 N/A 어휘로 정합화 (헤더 코멘트가 실제 env -u 구현과 모순되던 부분도 함께 정정) - tests/test_check_memory_frontmatter.py: 3개 assertion을 'N/A' 매칭으로 갱신 실측: PRAXIS_MEMORY_DIR=/nonexistent → 'N/A: ... EXIT=0'. 실제 디렉터리(48건) → 'OK: 48 memory entries ... clean EXIT=0'. Confidence: high Not-tested: none — 라벨 변경만이라 로컬 pytest(585 passed)·shellcheck·bash -n·실측 2-시나리오로 전부 커버됨 --- scripts/check-memory-frontmatter.py | 27 ++++++++++++-------- scripts/run-tests.sh | 35 ++++++++++++++++---------- tests/test_check_memory_frontmatter.py | 8 +++--- 3 files changed, 43 insertions(+), 27 deletions(-) diff --git a/scripts/check-memory-frontmatter.py b/scripts/check-memory-frontmatter.py index 325f1c81..1704afc9 100755 --- a/scripts/check-memory-frontmatter.py +++ b/scripts/check-memory-frontmatter.py @@ -39,17 +39,24 @@ follows `PRAXIS_MEMORY_DIR` / `CLAUDE_CONFIG_DIR` exactly like the memory-hint hook does — no separate path convention to drift from that one. -Exit codes: 0 clean (or skipped, unless PRAXIS_TESTS_STRICT=1), 1 on any -violation (or on a skip under PRAXIS_TESTS_STRICT=1, matching the -skip-is-not-pass convention `scripts/run-tests.sh` already uses, #917). +Exit codes: 0 clean (or N/A, unless PRAXIS_TESTS_STRICT=1), 1 on any +violation (or on N/A under PRAXIS_TESTS_STRICT=1, for standalone invocation). CI reality: the memory directory is a local, gitignored, per-user store and -does not exist in CI at all — so in CI this script always prints SKIPPED and -exits 0. It has enforcement value locally (a contributor normalizing memory +does not exist in CI at all — so in CI this script always prints N/A and +exits 0 (`scripts/run-tests.sh` strips PRAXIS_TESTS_STRICT for this one call, +so N/A can never fail the CI job either). This label is deliberately NOT +"SKIPPED": `scripts/run-tests.sh`'s header explains why a skip is not a pass +(#917) — a SKIPPED line names a *fixable* gap (install the tool) that a +strict rerun can close. This condition can never close; the directory is +structurally absent in CI by design, forever. Printing it as SKIPPED would +plant a permanently-unresolvable entry in exactly the noise this repo already +learned (via #917) drowns out the *actionable* skips — the same signal-loss +failure mode issue #942 itself was opened to stop recurring. N/A keeps it +readable as "nothing to check here", not "something you could fix but +didn't". It has enforcement value locally (a contributor normalizing memory frontmatter) and as a component this repo's own tests exercise directly -(`tests/test_check_memory_frontmatter.py`, via `PRAXIS_MEMORY_DIR`). Wiring -it into `scripts/run-tests.sh` is a follow-up, deliberately not done here — -that file is shared with concurrently in-flight PRs. +(`tests/test_check_memory_frontmatter.py`, via `PRAXIS_MEMORY_DIR`). """ from __future__ import annotations @@ -157,12 +164,12 @@ def main() -> int: memory_dir = resolve_memory_dir() if not memory_dir: - print("SKIPPED: memory-frontmatter-lint (memory directory not found — expected in CI / a fresh checkout)") + print("N/A: memory-frontmatter-lint (memory directory not found — expected in CI / a fresh checkout, not a fixable gap, see issue #942)") return 1 if strict else 0 files = iter_memory_files(memory_dir) if not files: - print(f"SKIPPED: memory-frontmatter-lint (no memory entries under {memory_dir})") + print(f"N/A: memory-frontmatter-lint (no memory entries under {memory_dir})") return 1 if strict else 0 total_errors = 0 diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh index 025b923c..657f1679 100755 --- a/scripts/run-tests.sh +++ b/scripts/run-tests.sh @@ -17,12 +17,17 @@ # the toolchain is not blocked — CI remains authoritative either way. # # Step 5 is a different repo-internal script, same family as steps 3-4 (no -# external toolchain — nothing to install), but it has its own legitimate skip -# condition: the memory directory it lints is a local, gitignored, per-user -# store that does not exist in CI or a fresh checkout at all (issue #942). It -# prints its own SKIPPED line and exit code, honoring PRAXIS_TESTS_STRICT the -# same way steps 6-8 do — no skip_step() wiring needed here, so a nonzero exit -# is treated as FAILED like steps 3-4, not routed through the tool-skip path. +# external toolchain — nothing to install), but its skip condition is not +# like steps 6-8's: the memory directory it lints is a local, gitignored, +# per-user store that is structurally absent in CI or a fresh checkout, +# always, forever (issue #942) — not a "toolchain not installed" gap a +# contributor can close. It prints "N/A", never "SKIPPED", to keep that +# distinction visible in the log (see its own docstring / #917 below), and +# this call strips PRAXIS_TESTS_STRICT (`env -u`, not passed through like +# steps 6-8) so that permanent N/A can never fail the job. Real drift +# (nonzero exit with violations listed) still counts as FAILED, same as +# steps 3-4 — this is not routed through the SKIPPED_TOOLS/skip_step() path +# at all. # # A skip is not a pass (#917). The SKIPPED line used to scroll past and the run # still ended on a bare "ALL TESTS PASSED", which read as full coverage: PR #912 @@ -140,10 +145,15 @@ echo "=== memory frontmatter lint ===" # steps 6-8 (a tool a contributor could install), the memory dir this checks # is a local, gitignored, per-user store that structurally never exists in # CI or a fresh checkout — treating its absence as a strict-mode failure -# would fail every CI run forever, not flag a fixable gap. A SKIPPED here is -# always benign; only actual detected drift (exit 1 with violations listed) -# fails this step. The script's own PRAXIS_TESTS_STRICT support still works -# for direct standalone invocation (see its tests / docstring). +# would fail every CI run forever, not flag a fixable gap. The script prints +# "N/A", not "SKIPPED", for exactly this reason: #917 exists because a +# scrolling SKIPPED line lost its signal value once contributors stopped +# reading it, and a condition that can never be fixed would sit there as +# permanent unresolvable noise if it wore the same "SKIPPED" label as steps +# 6-8's genuinely-fixable tool-absence skips. An N/A here is always benign; +# only actual detected drift (exit 1 with violations listed) fails this step. +# The script's own PRAXIS_TESTS_STRICT support still works for direct +# standalone invocation (see its tests / docstring). if ! env -u PRAXIS_TESTS_STRICT python3 ./scripts/check-memory-frontmatter.py; then FAILED=1 fi @@ -248,9 +258,8 @@ if [[ $FAILED -ne 0 ]]; then fi # Scope note: this counts the three tool steps this script owns (6-8). Step 5 -# has its own SKIPPED line but is deliberately excluded from this tally (see -# its PRAXIS_TESTS_STRICT note above) — it is never a missing-toolchain skip. -# Gates +# has its own N/A line (deliberately not "SKIPPED") and is excluded from this +# tally on purpose — it is never a missing-toolchain skip. Gates # that a sub-suite skips internally — e.g. the Darwin-only gate in # tests/test_codex_broker_reaper.sh — announce themselves in their own summary # and are not aggregated here; conflating them would make a portable-by-design diff --git a/tests/test_check_memory_frontmatter.py b/tests/test_check_memory_frontmatter.py index d5bbef35..c202dc5a 100644 --- a/tests/test_check_memory_frontmatter.py +++ b/tests/test_check_memory_frontmatter.py @@ -181,7 +181,7 @@ def test_missing_node_type_is_not_flagged(tmp_path): # --------------------------------------------------------------------------- -# main() — directory resolution + skip contract +# main() — directory resolution + N/A contract # --------------------------------------------------------------------------- def test_main_skips_when_directory_absent(tmp_path, monkeypatch): @@ -191,7 +191,7 @@ def test_main_skips_when_directory_absent(tmp_path, monkeypatch): with redirect_stdout(out): rc = check.main() assert rc == 0 - assert "SKIPPED" in out.getvalue() + assert "N/A" in out.getvalue() def test_main_skip_is_failure_under_strict(tmp_path, monkeypatch): @@ -201,7 +201,7 @@ def test_main_skip_is_failure_under_strict(tmp_path, monkeypatch): with redirect_stdout(out): rc = check.main() assert rc == 1 - assert "SKIPPED" in out.getvalue() + assert "N/A" in out.getvalue() def test_main_fails_on_drifted_entry(tmp_path, monkeypatch): @@ -236,4 +236,4 @@ def test_main_ignores_memory_md_index_file(tmp_path, monkeypatch): with redirect_stdout(out): rc = check.main() assert rc == 0 - assert "SKIPPED" in out.getvalue() # no *.md entries besides MEMORY.md + assert "N/A" in out.getvalue() # no *.md entries besides MEMORY.md From 6a9b905d5db2b026ab3e17a4307be2afa6874075 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 21:52:26 +0900 Subject: [PATCH 7/9] fix(scripts): flag hookable memories missing hookKeywords entirely MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex-review-wrap F1 (praxis:codex-review-wrap 비대화형 검증, team-lead 적용 승인). lint이 존재하는 이유 자체의 구멍이었다 — hookKeywords가 이 lint에 '존재하는 필드로서' 잘못된 형태(block/scalar)일 때만 검출됐고, 필드 자체가 아예 없거나 빈 리스트(hookKeywords: [])인 경우는 통과했다. 하지만 memory-hint 런타임 (hooks/advisory-nudge/memory-hint/impl.py:117-139)은 이 두 경우 모두 keywords_match 부재 또는 inner 빈 문자열에서 즉시 None을 반환해 메모리 전체를 hint 인덱스에서 조용히 제외한다 — lint가 막으려던 가장 직접적인 silent-dark 형태를 놓치고 있었다. - HOOKABLE_TRUTHY_VALUES 상수 추가 — memory-hint/impl.py:60의 TRUTHY_VALUES를 그대로 미러링(같은 정규화: strip/lower/quote-strip) - hookable truthy + hookKeywords 필드 자체 부재 → 신규 위반 추가 - hookKeywords: [] (빈 bracket) → 신규 위반 추가 (hookEvents는 폴백이라 대상 아님) - docstring check 4 추가, 회귀 테스트 4건(양성 2 + 경계 2: hookable false는 미대상, hookEvents 빈 리스트는 미대상) 회귀 오라클: git archive cf48a71로 픽스 이전 트리를 추출해 신규 테스트 파일만 얹어 재실행 — 신규 케이스만 정확히 깨지고 기존 케이스는 전부 그린임을 확인. Confidence: high Premise-Verified: hooks/advisory-nudge/memory-hint/impl.py:117-139 직접 판독 — keywords_match 없으면 line 119 return None, inner 빈 문자열이면 line 132 return None. 둘 다 memory 전체 드롭 확인 Not-tested: 실제 memory-hint 훅에 이 두 형태(누락/빈 리스트)를 실전 발화시켜 재확인하지 않음 — 코드 판독+회귀 테스트만 --- scripts/check-memory-frontmatter.py | 45 +++++++++++++ tests/test_check_memory_frontmatter.py | 92 ++++++++++++++++++++++++++ 2 files changed, 137 insertions(+) diff --git a/scripts/check-memory-frontmatter.py b/scripts/check-memory-frontmatter.py index 1704afc9..ebe2e773 100755 --- a/scripts/check-memory-frontmatter.py +++ b/scripts/check-memory-frontmatter.py @@ -34,6 +34,21 @@ the whole memory — `hookable: true` then never fires. Two entries in the corpus shipped this way (issue #942 scan): the hint had been dark since they were authored. + 4. `hookable: true` with `hookKeywords` missing entirely, or present as an + empty list (`hookKeywords: []`), is the same silent-drop failure as + check 3's block/scalar form — `impl.py:117-139` returns `None` (no + memory, no hint, ever) the moment `hookKeywords:` has no match or its + bracket content is empty. This check was added in a later revision of + this script (issue #942 F1, caught by an independent codex-review pass + after the first revision shipped without it): the original release only + inspected a field that IS present, so a memory missing `hookKeywords` + outright passed as clean while being just as dark as the block-form + case check 3 catches. + +Note on `hookEvents:` specifically: an empty list (`hookEvents: []`) is NOT +flagged the same way — `impl.py:150-169` falls back to the `[Bash]` default +when the bracket content is empty or unparseable, so the memory still gets +indexed. Resolution: reuses `hooks/_lib/_memory_dir.py::resolve_memory_dir()`, so this follows `PRAXIS_MEMORY_DIR` / `CLAUDE_CONFIG_DIR` exactly like the memory-hint @@ -86,6 +101,11 @@ # rejects any other shape outright (see module docstring, check 3). BRACKET_FIELDS = ("hookKeywords", "hookEvents") +# Mirrors hooks/advisory-nudge/memory-hint/impl.py:60 exactly (TRUTHY_VALUES) — +# the runtime's own truthy set for `hookable:`, after the same normalization +# (strip, lowercase, strip quotes) that impl.py:108-113 applies. +HOOKABLE_TRUTHY_VALUES = {"true", "yes"} + def frontmatter_block(raw: str) -> str | None: """Return the text between the first two `---` fences, or None.""" @@ -151,6 +171,31 @@ def check_file(path: Path) -> list[str]: f"`{field}: {value}` is scalar form, not `[a, b]` — the memory-hint parser " "rejects this shape and silently drops the entire memory from the hint index" ) + elif field == "hookKeywords": + close_idx = value.find("]") + inner = value[1:close_idx].strip() if close_idx != -1 else value[1:] + if not inner: + errors.append( + f"`{field}: {value}` is an empty list — the memory-hint parser treats " + "an empty hookKeywords the same as absent and silently drops the entire " + "memory from the hint index (issue #942 F1)" + ) + + # F1 (issue #942): `hookable: true` with `hookKeywords` entirely absent is + # the most direct silent-dark shape and was previously invisible to this + # lint — the BRACKET_FIELDS loop above only inspects a field that IS + # present. hooks/advisory-nudge/memory-hint/impl.py:117-119 returns None + # (drops the memory from the hint index) the moment `hookKeywords:` has no + # match in the frontmatter block at all. + hookable_truthy = False + if "hookable" in occurrences: + _, hookable_value = occurrences["hookable"][0] + hookable_truthy = hookable_value.strip().strip("\"'").lower() in HOOKABLE_TRUTHY_VALUES + if hookable_truthy and "hookKeywords" not in occurrences: + errors.append( + "`hookable: true` but `hookKeywords` is missing — the memory-hint parser requires " + "it and silently drops the entire memory from the hint index when absent (issue #942 F1)" + ) return errors diff --git a/tests/test_check_memory_frontmatter.py b/tests/test_check_memory_frontmatter.py index c202dc5a..13d5a9bd 100644 --- a/tests/test_check_memory_frontmatter.py +++ b/tests/test_check_memory_frontmatter.py @@ -135,6 +135,98 @@ def test_hookkeywords_scalar_form_flagged(tmp_path): assert any("scalar form" in e for e in errors), errors +def test_hookable_true_missing_hookkeywords_flagged(tmp_path): + # F1 (issue #942, codex-review pass after the original release): a field + # that is entirely ABSENT from the frontmatter was previously invisible + # to this checker — only present-but-malformed forms were caught. The + # memory-hint parser (impl.py:117-119) drops the memory outright when + # `hookable: true` and `hookKeywords:` has no match at all. + p = _write( + tmp_path, + "feedback_bad_missing_keywords.md", + """--- +name: bad-missing-keywords +description: test +metadata: + type: feedback + hookable: true + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("hookable: true" in e and "hookKeywords" in e and "missing" in e for e in errors), errors + + +def test_hookable_false_missing_hookkeywords_not_flagged(tmp_path): + # The F1 check is conditional on hookable being truthy — a non-hookable + # memory has no hint-index behavior to protect, so omitting hookKeywords + # entirely is normal, not drift. + p = _write( + tmp_path, + "feedback_not_hookable.md", + """--- +name: not-hookable +description: test +metadata: + type: feedback + originSessionId: abc-123 +--- +body +""", + ) + assert check.check_file(p) == [] + + +def test_hookkeywords_empty_bracket_flagged(tmp_path): + # F1: `hookKeywords: []` starts with `[` so the pre-F1 check accepted it + # as clean bracket form, but the runtime parser (impl.py:130-139) reads + # an empty inner list and returns None — same silent drop as the missing + # case above. + p = _write( + tmp_path, + "feedback_bad_empty_keywords.md", + """--- +name: bad-empty-keywords +description: test +metadata: + type: feedback + hookable: true + hookKeywords: [] + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + assert any("hookKeywords" in e and "empty list" in e for e in errors), errors + + +def test_hookevents_empty_bracket_not_flagged(tmp_path): + # Asymmetric with hookKeywords (F1 scope note): an empty hookEvents list + # falls back to the `[Bash]` default at runtime (impl.py:150-169) rather + # than dropping the memory, so it is not a drift the way an empty + # hookKeywords is. + p = _write( + tmp_path, + "feedback_empty_events.md", + """--- +name: empty-events +description: test +metadata: + type: feedback + hookable: true + hookKeywords: [foo] + hookEvents: [] + originSessionId: abc-123 +--- +body +""", + ) + assert check.check_file(p) == [] + + def test_missing_frontmatter_fence_flagged(tmp_path): p = _write(tmp_path, "feedback_no_fence.md", "just prose, no frontmatter\n") errors = check.check_file(p) From 77ea5c2e20e38915c034061c3044c611c5b4eaf5 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 21:55:36 +0900 Subject: [PATCH 8/9] fix(scripts): correct hookEvents error message to match runtime fallback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex-review-wrap F2 (praxis:codex-review-wrap 비대화형 검증, team-lead 적용 승인). hookKeywords/hookEvents block-form·scalar-form 오류 메시지가 하나의 공유 문자열('전체 메모리가 hint 인덱스에서 제외된다')을 썼는데, hookKeywords에는 참이지만 hookEvents에는 거짓이다. 런타임(memory-hint/impl.py:150-169)은 hookEvents가 malformed일 때 메모리를 드롭하지 않고 기본 이벤트([Bash])로 폴백할 뿐이다 — 실패 모드가 다른데 메시지가 같았다. - 필드별 consequence 분기 추가 (hookKeywords: 전체 드롭 / hookEvents: Bash 폴백, 의도한 non-Bash 이벤트만 소실) - docstring에 hookEvents 폴백 동작 근거 명시 - 회귀 테스트 1건 — hookEvents block-form 메시지가 'falls back to the default'를 담고 'drops the entire memory'를 담지 않는지 확인 회귀 오라클: F1 커밋과 동일하게 이 커밋 이전 트리(F1까지만 적용된 상태) 대상 새 테스트만 실행하면 이 케이스만 깨지는 것을 별도로 확인. Confidence: high Premise-Verified: hooks/advisory-nudge/memory-hint/impl.py:150-169 직접 판독 — events_raw가 '['로 시작 안 하거나 inner가 비면 if 블록을 건너뛰어 events는 DEFAULT_EVENTS(Bash)로 남음, return None 없음. hookKeywords의 return None과 다른 경로임을 확인 Not-tested: 실제 memory-hint 훅에 non-Bash hookEvents block-form을 흘려 stderr에 Bash로 매칭되는지까지는 재현하지 않음 — 코드 판독+메시지 텍스트 회귀 테스트만 --- scripts/check-memory-frontmatter.py | 26 +++++++++++++++++++---- tests/test_check_memory_frontmatter.py | 29 ++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 4 deletions(-) diff --git a/scripts/check-memory-frontmatter.py b/scripts/check-memory-frontmatter.py index ebe2e773..724e60fb 100755 --- a/scripts/check-memory-frontmatter.py +++ b/scripts/check-memory-frontmatter.py @@ -48,7 +48,10 @@ Note on `hookEvents:` specifically: an empty list (`hookEvents: []`) is NOT flagged the same way — `impl.py:150-169` falls back to the `[Bash]` default when the bracket content is empty or unparseable, so the memory still gets -indexed. +indexed (see check 3's own error text distinguishing the two fields' failure +modes — this was also caught in the F1/F2 codex-review pass: prior to that, +`check_file()`'s error message for `hookEvents` incorrectly claimed the same +"entire memory dropped" consequence hookKeywords has). Resolution: reuses `hooks/_lib/_memory_dir.py::resolve_memory_dir()`, so this follows `PRAXIS_MEMORY_DIR` / `CLAUDE_CONFIG_DIR` exactly like the memory-hint @@ -158,18 +161,33 @@ def check_file(path: Path) -> list[str]: if not nested: errors.append(f"`{field}` is at the top level — must nest under `metadata:`") if field in BRACKET_FIELDS: + # hookKeywords and hookEvents fail differently at runtime (F2, + # issue #942, caught by an independent codex-review pass): a + # malformed hookKeywords drops the WHOLE memory (impl.py:117-139 + # returns None outright), but a malformed hookEvents just falls + # back to the `[Bash]` default (impl.py:150-169) — the memory + # still gets indexed, only the intended non-Bash event is lost. + # An earlier revision of this script used one shared "entire + # memory dropped" message for both fields; that was accurate for + # hookKeywords and wrong for hookEvents. + consequence = ( + "silently drops the entire memory from the hint index" + if field == "hookKeywords" + else "silently falls back to the default `[Bash]` event — the memory " + "still gets indexed, but the intended non-Bash event is lost" + ) for _nested, value in occs: value = value.strip() if not value: errors.append( f"`{field}:` has no inline value (multi-line YAML-block `- item` form) — " - "the memory-hint parser rejects this shape and silently drops the entire " - "memory from the hint index; use single-line `[a, b]` form" + f"the memory-hint parser rejects this shape and {consequence}; " + "use single-line `[a, b]` form" ) elif not value.startswith("["): errors.append( f"`{field}: {value}` is scalar form, not `[a, b]` — the memory-hint parser " - "rejects this shape and silently drops the entire memory from the hint index" + f"rejects this shape and {consequence}" ) elif field == "hookKeywords": close_idx = value.find("]") diff --git a/tests/test_check_memory_frontmatter.py b/tests/test_check_memory_frontmatter.py index 13d5a9bd..e1b80386 100644 --- a/tests/test_check_memory_frontmatter.py +++ b/tests/test_check_memory_frontmatter.py @@ -227,6 +227,35 @@ def test_hookevents_empty_bracket_not_flagged(tmp_path): assert check.check_file(p) == [] +def test_hookevents_block_form_message_says_fallback_not_drop(tmp_path): + # F2 (issue #942, same codex-review pass): the shared error message used + # to claim "the entire memory is dropped" for both hookKeywords and + # hookEvents malformed shapes. For hookEvents that is false — impl.py + # falls back to the default [Bash] event and still indexes the memory. + p = _write( + tmp_path, + "feedback_bad_events_blockform.md", + """--- +name: bad-events-blockform +description: test +metadata: + type: feedback + hookable: true + hookKeywords: [foo] + hookEvents: + - Edit + originSessionId: abc-123 +--- +body +""", + ) + errors = check.check_file(p) + matching = [e for e in errors if e.startswith("`hookEvents:`")] + assert matching, errors + assert "falls back to the default" in matching[0], matching + assert "drops the entire memory" not in matching[0], matching + + def test_missing_frontmatter_fence_flagged(tmp_path): p = _write(tmp_path, "feedback_no_fence.md", "just prose, no frontmatter\n") errors = check.check_file(p) From e3aac9d5e57561fde95971afc6e9d5f51bfa8e45 Mon Sep 17 00:00:00 2001 From: Seunggwan Song Date: Wed, 12 Aug 2026 21:58:37 +0900 Subject: [PATCH 9/9] docs(retrospect): correct false claim about CI catching memory drift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex-review-wrap F3 (praxis:codex-review-wrap 비대화형 검증, team-lead 적용 승인). 이 PR이 이번 rev 이전에 스스로 써넣은 문장이 거짓이었다: scripts/check-memory-frontmatter.py in CI is the structural fix, so the next drift of this family fails a build instead of aging quietly in cursor state. 메모리 디렉터리는 gitignored per-user 저장소라 CI에 구조적으로 부재하고, run-tests.sh의 env -u PRAXIS_TESTS_STRICT 호출은 이 조건에서 항상 N/A/exit 0을 반환한다 — build를 실패시킬 수 있는 경로가 없다. 이 세션에서 직접 설계한 env -u 처리와 정확히 모순되는 문장이었다. 문장을 CI가 이 lint로 무엇을 할 수 있는지 정확히 서술하도록 교체했다 — '구조적 수정'이 아니라 '로컬 run-tests.sh 실행 또는 직접 실행 시에만 잡힌다, CI에서는 구조적으로 N/A'. 재검증 경로가 완전하지 않다는 한계를 명시했다. 문서 전용 수정이라 회귀 테스트 대상 아님(team-lead 확인). Confidence: high Premise-Verified: gh run view --repo devseunggwan/praxis --job 94063407506 --log (commit cf48a71, 이 세션에서 이미 수집) — step 5가 'N/A: memory-frontmatter-lint ...' 출력 후 FAILED 미집계, ALL TESTS PASSED로 종료. CI가 이 스텝으로 드리프트를 build 실패시킬 수 없음을 실제 CI 런 로그로 확인 Not-tested: none — 문서 서술의 정정 대상 자체가 이미 이 세션의 CI 로그 오라클로 검증된 사실 --- skills/retrospect/references/stage4-execution.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/skills/retrospect/references/stage4-execution.md b/skills/retrospect/references/stage4-execution.md index 98df89f6..21758a38 100644 --- a/skills/retrospect/references/stage4-execution.md +++ b/skills/retrospect/references/stage4-execution.md @@ -109,8 +109,14 @@ For each approved action: 17→18, and only became an issue (#942) once cycle 18 explicitly promoted it. The gap this exposes: a carried `cycle_note` has no re-verification path of its own (no CI, no lint, no issue to close) — `scripts/check-memory-frontmatter.py` - in CI is the structural fix, so the *next* drift of this family fails a - build instead of aging quietly in cursor state. + is the structural fix, but only on a contributor's own machine: the + memory directory it lints is a local, gitignored, per-user store that is + structurally absent in CI, so `scripts/run-tests.sh`'s call to it always + prints `N/A` and exits 0 there (verified — F3, issue #942 codex-review + pass). **CI cannot catch the next drift of this family; only a local + `run-tests.sh` run, or a contributor running the script directly, + catches it.** That re-verification path is therefore still incomplete — + it exists, but is opt-in rather than structurally enforced on every push. **⚠️ MANDATORY: Duplicate check before creating any memory file:**