@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/memory-flush/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: memory-flush
+owner: baseline
+description: Review the auto-extracted candidates in `.claude/memory/_pending.md` and commit keepers to the canonical memory files (`landmarks.md`, `libraries.md`, `decisions.md`, `landmines.md`, `conventions.md`, `pending-questions.md`). Invoke at session start when the SessionStart hook reports pending candidates, or any time `_pending.md` has accumulated entries you want to curate. Reset the pending body after flushing.
+---
+
+# memory-flush — curate auto-extracted memory candidates
+
+The `memory_stop.sh` hook appends candidates to `.claude/memory/_pending.md` after every turn. This skill reviews them in main context (where conversation richness is preserved), commits the keepers to the right canonical file with proper metadata, and resets the pending body.
+
+The hook is a passive collector. **You are the curator.** Discard noise, promote signal, deduplicate against existing canonical entries.
+
+# Inputs
+
+- `.claude/memory/_pending.md` — the pending body. Each block looks like:
+  ```
+  ## CANDIDATE: <key> → <target-file>.md
+  - field: value
+  - field: value
+  ```
+- The six canonical files at `.claude/memory/<name>.md`. Read each before deciding where a candidate lands and whether it duplicates existing content.
+
+# Method
+
+## Step 0 — Canonical sweep (closure semantics)
+
+Before reviewing `_pending.md`, sweep the six canonical files for closed entries and stale entries. The `sweep.py` helper at `.claude/skills/memory-flush/sweep.py` is the deterministic actuator; this SOP composes the three modes.
+
+### Step 0a — Auto-close structured closure fields
+
+Invoke:
+
+```
+python3 .claude/skills/memory-flush/sweep.py --mode auto-close --memory-dir .claude/memory
+```
+
+Behavior:
+
+- For each entry on `pending-questions.md`: if `- resolved-at: <ISO>` is present and valid, delete the entry block.
+- For each entry on the other five canonical files: if `- superseded-at: <ISO>` is present and valid, delete the entry block.
+- Per-file invariant violations (`resolved-at:` on a non-pending file, `superseded-at:` on `pending-questions.md`) are flagged in the report and the block is **kept**.
+- Malformed ISO dates are flagged and the block is **kept**.
+
+Report shape: `{"closed": N, "malformed": [...], "invariant_violation": [...]}`. Surface counts in the Step 6 report.
+
+### Step 0b — Surface prose closure phrases
+
+Invoke (one reply per surfaced entry, piped from stdin):
+
+```
+python3 .claude/skills/memory-flush/sweep.py --mode prose-scan --memory-dir .claude/memory
+```
+
+For each entry without a structured closure field, the helper scans the body against three anchored, case-insensitive regexes (R1 `Resolution path taken|by|date`, R2 `Superseded by|at|on`, R3 `Resolved by|on|at`). On a match the helper reads one line from stdin and applies the reply: `y` deletes the block, `n` keeps and does-not-resurface-this-run, `skip` keeps and defers for next-run reconsideration.
+
+You drive this step interactively: ask the user `Close <key> from <file>? (y / n / skip)` for each entry the helper surfaces, then feed the answers to the helper one per line.
+
+### Step 0c — Stale sweep
+
+Only run when `memory_session_start.sh` reported stale > 0 this session, or the user asks. Invoke:
+
+```
+python3 .claude/skills/memory-flush/sweep.py --mode stale-sweep --memory-dir .claude/memory
+```
+
+The helper re-derives the stale set using the same predicate as the hook (verified-at ≥ 30 commits behind HEAD in git, or last-touched ≥ 30 days in non-git). For each stale entry, prompt the user `Stale: <key> in <file>. re-verify / delete / mark-closed / skip?` and feed the reply. `re-verify` restamps `verified-at:` + `last-touched:` to today; `delete` removes the block; `mark-closed` inserts the register-correct closure field (`resolved-at:` on pending-questions, `superseded-at:` elsewhere) and leaves the block in place so Step 0a auto-closes it next run; `skip` keeps it and resurfaces next session.
+
+After Step 0 completes, proceed to Step 1.
+
+## Step 1 — Read everything
+
+Read `_pending.md` in full. Then read the canonical file each candidate targets (don't read all six; read only what's referenced in pending). For each canonical file you'll write to, check the existing entries' stable keys.
+
+## Step 2 — Decide per candidate
+
+For each `## CANDIDATE:` block, decide one of:
+
+- **Promote.** The candidate is signal. Build the canonical entry shape (see `.claude/memory/README.md`) and append to the right file. If the candidate's stable key already exists in the canonical file → **replace** that entry; do not duplicate.
+- **Discard.** The candidate is noise (touched-once file with no clear role; a context7 query that resolved nothing useful; a path under generated/vendored code). No canonical write.
+- **Defer.** Useful but you don't have enough context to write a clean entry. Move the candidate verbatim to `pending-questions.md` as a `Q-NNN` entry phrased as "Should X be a landmark?" so the next session can decide. The pending body still gets reset at the end.
+
+## Step 3 — Verify before promoting
+
+Per the project memory contract: every entry on the canonical files must have a `verified-at:` field. Verify the candidate's claim before writing:
+
+- **Landmark candidate** → confirm the file exists at the named path (Read tool). If the candidate has no line number, find the relevant symbol and add `:line` to the key. If the file is missing, **discard**.
+- **Library candidate** → confirm the version against the project's lockfile (or its stack equivalent). If lockfile absent or version mismatched, mark `verified-at: unverified` and add a caveat instead of a SHA.
+- **Decision / landmine / convention candidate** → confirm the cited file/line still exists; if not, surface and discard.
+
+Stamp `verified-at: <short HEAD SHA>` on every promoted entry. If the project isn't a git repo or HEAD isn't reachable, use `verified-at: HEAD` (the SessionStart hook treats `HEAD` as fresh).
+
+## Step 4 — Write canonical entries
+
+For each promoted candidate:
+
+1. Read the target canonical file's body.
+2. If a stable-key match exists → use Edit to replace that block in place.
+3. If no match → use Edit to insert the new entry at the bottom of the body (above any trailing blank lines).
+4. After each write, re-read the file and confirm the new/updated entry is present and well-formed.
+
+Apply the canonical entry shape (from `.claude/memory/README.md`):
+
+```markdown
+## <stable key>
+
+- <field>: <value>
+- ...
+- verified-at: <short SHA>
+- last-touched: <ISO date YYYY-MM-DD>
+- caveat: <optional>
+```
+
+## Step 5 — Reset the pending body
+
+After all promotion/discard/defer decisions are written, **rewrite `_pending.md`** to the empty skeleton:
+
+```markdown
+---
+owners: [memory_stop.sh writes; /memory-flush clears]
+category: auto-extracted candidates awaiting curation
+verifies-against: none
+---
+
+# Pending memory candidates
+
+Auto-extracted by `memory_stop.sh` at end of each turn. Run `/memory-flush` to review and commit keepers to the canonical files.
+
+**Content of this file is gitignored.** The file itself (with this header) is committed; everything below the `---` separator below is per-session and not staged.
+
+---
+```
+
+Use `Write` to overwrite the file (not `Edit`, since you're truncating).
+
+## Step 6 — Report
+
+Tell the user what happened:
+
+```
+memory-flush — <date>
+
+Closed (P):
+- <key> → <file> (auto-close | confirmed)
+- ...
+
+Stale handled (Q):
+- <key> → <file> (re-verified | deleted | marked-closed | skipped)
+- ...
+
+Promoted (N):
+- <key> → <file> (new | replaced)
+- ...
+
+Discarded (M):
+- <key> — <reason>
+- ...
+
+Deferred (K) → pending-questions.md:
+- Q-NNN: <question>
+- ...
+
+Pending body reset.
+```
+
+# Constraints
+
+- **Never write directly from `_pending.md` to canonical without verification.** The whole point of the curation step is to add the verified-at stamp. Auto-promotion would defeat self-healing.
+- **Never duplicate entries.** Stable-key match → replace, don't append a second copy.
+- **Never grow a canonical file past its `size-cap`** (default 500 lines). If a write would exceed, prune the oldest unverified entries in the same write — and surface what you pruned in the report.
+- **The pending body is gitignored content, but the file itself is committed.** Always reset to the skeleton (don't delete the file).
+- **Do not write to `_pending.md` outside this skill.** The hook owns appends; this skill owns clears.
+- **Do not write to `.claude/memory/README.md`.** It's documentation, not a memory file.

package/obj/template/.claude/skills/memory-flush/sweep.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Deterministic Step 0 helper for /memory-flush.
+
+Scans canonical memory files for closure fields and prose closure signals,
+applies the matching action (auto-close / surface-and-confirm / stale-sweep),
+and emits a JSON action report. Invoked by SKILL.md Step 0 and exercised by
+the fixture tests at .claude/skills/memory-flush/tests/run.sh.
+
+CLI:
+  --mode {auto-close, prose-scan, stale-sweep}
+  --memory-dir <path>
+
+For interactive modes (prose-scan, stale-sweep), one reply per surfaced entry
+is read from stdin. Empty stdin / EOF defaults to "keep".
+"""
+from __future__ import annotations
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import date, datetime
+from pathlib import Path
+
+# --- constants (Foundation) ---------------------------------------------------
+
+CANONICAL_FILES = [
+    'landmarks', 'libraries', 'decisions',
+    'landmines', 'conventions', 'pending-questions',
+]
+PENDING_FILE = 'pending-questions'
+
+STALE_COMMITS = 30
+STALE_DAYS = 30
+
+ISO_DATE_RE = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+
+PROSE_PATTERNS = [
+    re.compile(r'^(\s*-\s*)?\*\*?Resolution\s+(path\s+taken|by|date)\b', re.I | re.M),
+    re.compile(r'^Superseded\s+(by|at|on)\b', re.I | re.M),
+    re.compile(r'^Resolved\s+(by|on|at)\b', re.I | re.M),
+]
+
+# --- Foundation: filesystem + entry parsing -----------------------------------
+
+def file_path(memdir: Path, name: str) -> Path:
+    return memdir / f'{name}.md'
+
+def read_file(memdir: Path, name: str) -> str:
+    p = file_path(memdir, name)
+    return p.read_text(encoding='utf-8', errors='replace') if p.is_file() else ''
+
+def write_file(memdir: Path, name: str, text: str) -> None:
+    file_path(memdir, name).write_text(text, encoding='utf-8')
+
+def split_entries(text: str):
+    """Return [(key, block_text)] for each `## ` heading + body in the file."""
+    body = text.split('---', 2)[-1] if text.startswith('---') else text
+    parts = re.split(r'(?m)^(##\s+\S.*)$', body)
+    entries = []
+    for i in range(1, len(parts), 2):
+        heading = parts[i]
+        tail = parts[i + 1] if i + 1 < len(parts) else ''
+        key = heading[2:].strip().split()[0] if heading[2:].strip() else ''
+        entries.append((key, heading + tail))
+    return entries
+
+def read_field(block: str, name: str):
+    pat = re.compile(rf'^\s*-\s*{re.escape(name)}\s*:\s*(.+?)\s*$', re.M | re.I)
+    m = pat.search(block)
+    return m.group(1) if m else None
+
+def has_field(block: str, name: str) -> bool:
+    return read_field(block, name) is not None
+
+def valid_iso(s) -> bool:
+    if not s or not ISO_DATE_RE.match(s):
+        return False
+    try:
+        datetime.strptime(s, '%Y-%m-%d')
+        return True
+    except ValueError:
+        return False
+
+def delete_block(text: str, block: str) -> str:
+    idx = text.find(block)
+    if idx < 0:
+        return text
+    before = text[:idx].rstrip('\n')
+    after = text[idx + len(block):].lstrip('\n')
+    if before and after:
+        return before + '\n\n' + after
+    if before:
+        return before + '\n'
+    return after
+
+def update_field(block: str, name: str, value: str) -> str:
+    pat = re.compile(rf'(^\s*-\s*{re.escape(name)}\s*:\s*).+$', re.M | re.I)
+    if pat.search(block):
+        return pat.sub(lambda m: f'{m.group(1)}{value}', block, count=1)
+    return _append_field(block, name, value)
+
+def _append_field(block: str, name: str, value: str) -> str:
+    lines = block.rstrip('\n').split('\n')
+    insert_at = len(lines)
+    for i in range(len(lines) - 1, -1, -1):
+        if lines[i].strip().startswith('-'):
+            insert_at = i + 1
+            break
+    lines.insert(insert_at, f'- {name}: {value}')
+    return '\n'.join(lines) + '\n'
+
+# --- Foundation: git + dates --------------------------------------------------
+
+def head_sha(root: Path) -> str:
+    try:
+        return subprocess.check_output(
+            ['git', '-C', str(root), 'rev-parse', '--short', 'HEAD'],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+    except Exception:
+        return ''
+
+def commit_distance(root: Path, stamp: str):
+    try:
+        d = subprocess.check_output(
+            ['git', '-C', str(root), 'rev-list', '--count', f'{stamp}..HEAD'],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+        return int(d) if d.isdigit() else None
+    except Exception:
+        return None
+
+def days_since(iso: str):
+    try:
+        d = datetime.strptime(iso, '%Y-%m-%d').date()
+        return (date.today() - d).days
+    except Exception:
+        return None
+
+# --- Domain: closure semantics ------------------------------------------------
+
+def closure_field_for(name: str) -> str:
+    return 'resolved-at' if name == PENDING_FILE else 'superseded-at'
+
+def invariant_field_for(name: str) -> str:
+    return 'superseded-at' if name == PENDING_FILE else 'resolved-at'
+
+def is_closed(block: str, name: str) -> bool:
+    return has_field(block, closure_field_for(name))
+
+def prose_matches(block: str) -> bool:
+    return any(p.search(block) for p in PROSE_PATTERNS)
+
+def is_stale(block: str, name: str, head: str, root: Path) -> bool:
+    if is_closed(block, name):
+        return False
+    stamp = read_field(block, 'verified-at')
+    if head and stamp and stamp != 'HEAD':
+        dist = commit_distance(root, stamp)
+        return dist is None or dist >= STALE_COMMITS
+    if not head:
+        touched = read_field(block, 'last-touched')
+        days = days_since(touched) if touched else None
+        return days is not None and days >= STALE_DAYS
+    return False
+
+# --- Domain: per-mode sweepers ------------------------------------------------
+
+def mode_auto_close(memdir: Path) -> dict:
+    report = {'closed': 0, 'malformed': [], 'invariant_violation': []}
+    for name in CANONICAL_FILES:
+        text = read_file(memdir, name)
+        if not text:
+            continue
+        valid = closure_field_for(name)
+        wrong = invariant_field_for(name)
+        new_text = text
+        for key, block in split_entries(text):
+            if has_field(block, wrong):
+                report['invariant_violation'].append(
+                    {'file': f'{name}.md', 'key': key, 'field': wrong}
+                )
+                continue
+            value = read_field(block, valid)
+            if value is None:
+                continue
+            if valid_iso(value):
+                new_text = delete_block(new_text, block)
+                report['closed'] += 1
+            else:
+                report['malformed'].append(
+                    {'file': f'{name}.md', 'key': key, 'value': value}
+                )
+        if new_text != text:
+            write_file(memdir, name, new_text)
+    return report
+
+def _next_reply() -> str:
+    line = sys.stdin.readline()
+    return line.strip().lower() if line else ''
+
+def mode_prose_scan(memdir: Path) -> dict:
+    report = {'surfaced': 0, 'closed_by_confirm': 0, 'kept': 0, 'deferred': 0}
+    for name in CANONICAL_FILES:
+        text = read_file(memdir, name)
+        if not text:
+            continue
+        new_text = text
+        for key, block in split_entries(text):
+            if is_closed(block, name):
+                continue
+            if not prose_matches(block):
+                continue
+            report['surfaced'] += 1
+            reply = _next_reply()
+            if reply == 'y':
+                new_text = delete_block(new_text, block)
+                report['closed_by_confirm'] += 1
+            elif reply == 'skip':
+                report['deferred'] += 1
+            else:
+                report['kept'] += 1
+        if new_text != text:
+            write_file(memdir, name, new_text)
+    return report
+
+def mode_stale_sweep(memdir: Path) -> dict:
+    report = {'reverified': 0, 'deleted': 0, 'mark_closed': 0, 'kept': 0}
+    root = memdir.parent.parent
+    head = head_sha(root)
+    today = date.today().isoformat()
+    for name in CANONICAL_FILES:
+        text = read_file(memdir, name)
+        if not text:
+            continue
+        new_text = text
+        for key, block in split_entries(text):
+            if not is_stale(block, name, head, root):
+                continue
+            reply = _next_reply()
+            new_text = _apply_stale_action(new_text, block, name, reply, head, today, report)
+        if new_text != text:
+            write_file(memdir, name, new_text)
+    return report
+
+def _apply_stale_action(text, block, name, reply, head, today, report):
+    if reply == 're-verify':
+        updated = update_field(block, 'verified-at', head or 'HEAD')
+        updated = update_field(updated, 'last-touched', today)
+        report['reverified'] += 1
+        return text.replace(block, updated)
+    if reply == 'delete':
+        report['deleted'] += 1
+        return delete_block(text, block)
+    if reply == 'mark-closed':
+        field = closure_field_for(name)
+        updated = update_field(block, field, today)
+        report['mark_closed'] += 1
+        return text.replace(block, updated)
+    report['kept'] += 1
+    return text
+
+# --- Orchestration ------------------------------------------------------------
+
+MODE_DISPATCH = {
+    'auto-close': mode_auto_close,
+    'prose-scan': mode_prose_scan,
+    'stale-sweep': mode_stale_sweep,
+}
+
+def parse_args(argv):
+    p = argparse.ArgumentParser(description='Memory Step 0 sweep helper')
+    p.add_argument('--mode', required=True, choices=list(MODE_DISPATCH))
+    p.add_argument('--memory-dir', required=True)
+    return p.parse_args(argv)
+
+def main(argv) -> int:
+    args = parse_args(argv)
+    memdir = Path(args.memory_dir).resolve()
+    report = MODE_DISPATCH[args.mode](memdir)
+    print(json.dumps(report))
+    return 0
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))