ecoportal-api 0.10.16 → 0.10.17

data/.ai-assistance/scripts/distill_procedural.py

@@ -0,0 +1,602 @@
+#!/usr/bin/env python3
+"""
+distill_procedural.py -- Procedural-memory DISTILL stage.
+
+Standard: standards/workflows/procedural-memory.md ("Distill" + D1 lifecycle).
+
+Mines the machine-local Observe stream (.ai-assistance/local/observe-<ISO-week>.jsonl --
+the dedicated stream observe_session.py writes; NOT the kpi/usage heartbeat stream) into
+`procedural` memory entries, and runs the D1 lifecycle over existing entries: confidence
+re-evaluation, retirement (confidence floor / staleness), forced RETIRE/CONFIRM markers, and
+archive-with-tombstone + cool-off so a retired routine cannot silently reappear.
+
+SCHEDULING: this is a deterministic, zero-LLM, machine-local pass -- safe on a clock. The
+standard OliveTin action "epai: Procedural distill (daily)" runs it daily (see
+templates/olivetin/config.yaml.template); a plain cron line works identically:
+  15 6 * * *  python <repo>/templates/ai-assistance/scripts/distill_procedural.py --cwd <repo> --apply
+It never spawns a claude session (standards/tooling/self-spawning-automation.md), never
+commits, and is no-op-safe: with nothing to do it prints one "0 records distilled" line
+and exits 0.
+
+BACKFILL (--backfill-from-feedback): one-shot verification seeding per the 2026-07-20
+inventory. Reads hand-written `type: feedback` records from --memory-dir and writes
+`type: procedural` PROPOSALS to --output-dir (never into the live memory dir); a human
+reviews and moves approved proposals into memory. This gives the Act/surface stage a
+known-present positive signal (feedback-verify-actuators-against-positive-signal).
+
+The DETERMINISTIC lifecycle (confidence arithmetic, retirement, archival, tombstones) lives
+here in full. The pattern MINER here is a conservative v1 co-occurrence heuristic (event B
+reliably follows event A within a session); the richer semantic mining -- and the
+reasoning-trait / blind-spot subtypes -- are performed by the `procedural-memory` skill (an
+LLM task) over the same evidence log. Because the evidence layer is stable, either miner can
+be re-run over the existing archive without re-collecting data.
+
+CONSENT: refuses to read the log unless the developer opted in (procedural-observe.enabled
+marker or PROCEDURAL_OBSERVE=1), mirroring the Observe hook.
+
+SAFE BY DEFAULT: dry-run (prints the plan, writes nothing). Pass --apply to write.
+
+Provisional constants (tunable in the reviewed phase; see the standard):
+  INITIAL_CONFIDENCE=0.6  CONF_UP=+0.1  CONF_DOWN=-0.2  FLOOR=0.3
+  STALENESS_DAYS=90  COOLOFF_DAYS=30  MIN_CONSISTENCY=0.8  MIN_OCCURRENCES=3
+"""
+import argparse
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone, date
+
+INITIAL_CONFIDENCE = 0.6
+CONF_UP = 0.1
+CONF_DOWN = 0.2
+FLOOR = 0.3
+STALENESS_DAYS = 90
+COOLOFF_DAYS = 30
+MIN_CONSISTENCY = 0.8
+MIN_OCCURRENCES = 3
+
+_FIELD = {
+    "trigger": re.compile(r"(?im)^\*\*Trigger:\*\*\s*(.+?)\s*$"),
+    "action": re.compile(r"(?im)^\*\*Inferred action:\*\*\s*(.+?)\s*$"),
+    "confidence": re.compile(r"(?im)^\*\*Confidence:\*\*\s*([0-9.]+)"),
+    "first": re.compile(r"(?im)^\*\*First-observed:\*\*\s*([0-9]{4}-[0-9]{2}-[0-9]{2})"),
+    "last": re.compile(r"(?im)^\*\*Last-observed:\*\*\s*([0-9]{4}-[0-9]{2}-[0-9]{2})"),
+    "subtype": re.compile(r"(?im)^\*\*Subtype:\*\*\s*(\w[\w-]*)"),
+    "evkey": re.compile(r"(?im)^\*\*Evidence-key:\*\*\s*(\S+)"),
+}
+_RETIRE = re.compile(r"<!--\s*RETIRE:\s*(.+?)\s*-->")
+_CONFIRM = re.compile(r"<!--\s*CONFIRM:\s*(.+?)\s*-->")
+
+
+def _today(override=None):
+    if override:
+        return date.fromisoformat(override)
+    return datetime.now(timezone.utc).date()
+
+
+def _consent(local_dir):
+    if os.environ.get("PROCEDURAL_OBSERVE", "").lower() in ("1", "true", "yes"):
+        return True
+    return os.path.exists(os.path.join(local_dir, "procedural-observe.enabled"))
+
+
+def _project_slug(cwd):
+    # Mirror Claude Code's project-dir slug: path with : \ / replaced by -.
+    ab = os.path.abspath(cwd)
+    return ab.replace(":", "-").replace("\\", "-").replace("/", "-")
+
+
+# --- evidence: mine candidate routines from the observe stream ----------------
+
+def _read_events(evidence_dir):
+    """Return {session_id: [event_key, ...]} ordered by timestamp. Event key = component/action.
+    Reads ONLY the dedicated observe-*.jsonl stream -- the kpi/usage-*.jsonl heartbeat stream
+    is deliberately not evidence (it buried the behavioral signal; 2026-07-20 inventory)."""
+    sessions = {}
+    if not os.path.isdir(evidence_dir):
+        return sessions
+    rows = []
+    for fn in sorted(os.listdir(evidence_dir)):
+        if not (fn.startswith("observe-") and fn.endswith(".jsonl")):
+            continue
+        try:
+            with open(os.path.join(evidence_dir, fn), encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        r = json.loads(line)
+                    except ValueError:
+                        continue
+                    comp = r.get("component", "")
+                    act = r.get("action", "")
+                    if not comp or act == "session-summary":
+                        continue  # aggregate rows carry no sequence signal
+                    rows.append((r.get("session_id", ""), r.get("ts", ""), f"{comp}/{act}"))
+        except OSError:
+            continue
+    rows.sort(key=lambda t: (t[0], t[1]))
+    for sid, _ts, ev in rows:
+        sessions.setdefault(sid, []).append(ev)
+    return sessions
+
+
+def _mine_pairs(sessions):
+    """Co-occurrence: for each event A, consistency = P(next distinct event is B).
+    Returns {(A,B): {"count":n,"opportunities":m,"consistency":r}} for pairs meeting thresholds."""
+    opp = {}   # A -> count of A occurrences that had a following event
+    pair = {}  # (A,B) -> count
+    for evs in sessions.values():
+        for i in range(len(evs) - 1):
+            a, b = evs[i], evs[i + 1]
+            if a == b:
+                continue
+            opp[a] = opp.get(a, 0) + 1
+            pair[(a, b)] = pair.get((a, b), 0) + 1
+    out = {}
+    for (a, b), n in pair.items():
+        m = opp.get(a, 0)
+        r = (n / m) if m else 0.0
+        if n >= MIN_OCCURRENCES and r >= MIN_CONSISTENCY:
+            out[(a, b)] = {"count": n, "opportunities": m, "consistency": round(r, 3)}
+    return out
+
+
+def _pair_occurrences(sessions):
+    """Return dict A -> (fired, followed_by_any) is not enough; we need per-entry re-eval.
+    Provide: for an evidence-key 'A>>B', did A fire in window, and did B follow A?"""
+    opp = {}
+    pair = {}
+    for evs in sessions.values():
+        for i in range(len(evs) - 1):
+            a, b = evs[i], evs[i + 1]
+            if a == b:
+                continue
+            opp[a] = opp.get(a, 0) + 1
+            pair[(a, b)] = pair.get((a, b), 0) + 1
+    return opp, pair
+
+
+# --- existing entries ---------------------------------------------------------
+
+def _split_frontmatter(text):
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            return text[3:end].strip(), text[end + 4:].lstrip("\n")
+    return "", text
+
+
+def _is_procedural(front):
+    return re.search(r"(?im)^\s*type:\s*procedural\b", front) is not None
+
+
+def _parse_entry(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+    except OSError:
+        return None
+    front, body = _split_frontmatter(text)
+    if not _is_procedural(front):
+        return None
+    nm = re.search(r"(?im)^\s*name:\s*(.+?)\s*$", front)
+    e = {"path": path, "text": text, "front": front, "body": body,
+         "name": nm.group(1).strip() if nm else os.path.basename(path)[:-3]}
+    for k, rx in _FIELD.items():
+        m = rx.search(body)
+        e[k] = m.group(1).strip() if m else None
+    e["confidence"] = float(e["confidence"]) if e["confidence"] else INITIAL_CONFIDENCE
+    e["subtype"] = e["subtype"] or "routine"
+    return e
+
+
+def _set_field(body, label, value):
+    rx = re.compile(r"(?im)^(\*\*" + re.escape(label) + r":\*\*\s*).+?$")
+    repl = r"\g<1>" + value.replace("\\", "\\\\")
+    if rx.search(body):
+        return rx.sub(lambda m: m.group(1) + value, body, count=1)
+    return body.rstrip() + f"\n**{label}:** {value}\n"
+
+
+# --- main ---------------------------------------------------------------------
+
+def run(memory_dir, evidence_dir, worklog, apply, today):
+    plan = {"retired": [], "confirmed": [], "up": [], "down": [], "new": [], "skipped_cooloff": []}
+    tombstone_path = os.path.join(memory_dir, "retired", "tombstones.json")
+    tombstones = {}
+    if os.path.exists(tombstone_path):
+        try:
+            tombstones = {t["evkey"]: t for t in json.load(open(tombstone_path, encoding="utf-8"))}
+        except (OSError, ValueError, KeyError):
+            tombstones = {}
+
+    # Forced markers from worklog + memory files.
+    marker_text = ""
+    if worklog and os.path.exists(worklog):
+        try:
+            marker_text += open(worklog, encoding="utf-8").read()
+        except OSError:
+            pass
+    entries = []
+    if os.path.isdir(memory_dir):
+        for fn in sorted(os.listdir(memory_dir)):
+            if fn.endswith(".md") and fn != "MEMORY.md":
+                e = _parse_entry(os.path.join(memory_dir, fn))
+                if e:
+                    entries.append(e)
+                    marker_text += e["text"]
+    force_retire = {m.strip().lower() for m in _RETIRE.findall(marker_text)}
+    force_confirm = {m.strip().lower() for m in _CONFIRM.findall(marker_text)}
+
+    sessions = _read_events(evidence_dir)
+    opp, pair = _pair_occurrences(sessions)
+    tstr = today.isoformat()
+
+    existing_keys = set()
+    for e in entries:
+        nm = (e["name"] or "").lower()
+        evkey = e.get("evkey")
+        if evkey:
+            existing_keys.add(evkey)
+        retire = False
+        reason = None
+
+        # 1) forced markers (honoured before arithmetic)
+        if nm in force_retire:
+            retire, reason = True, "forced"
+        elif nm in force_confirm:
+            e["confidence"] = 1.0
+            e["last"] = tstr
+            plan["confirmed"].append(e["name"])
+
+        # 2) confidence re-evaluation from evidence (only if we can map the trigger)
+        if not retire and evkey and ">>" in evkey and nm not in force_confirm:
+            a, b = evkey.split(">>", 1)
+            if opp.get(a, 0) > 0:  # trigger fired in window
+                if pair.get((a, b), 0) > 0:  # action followed
+                    e["confidence"] = min(1.0, e["confidence"] + CONF_UP)
+                    e["last"] = tstr
+                    plan["up"].append(e["name"])
+                else:  # trigger fired but action did NOT follow
+                    e["confidence"] = max(0.0, e["confidence"] - CONF_DOWN)
+                    plan["down"].append(e["name"])
+            # trigger did not fire -> unchanged, no last-observed refresh
+
+        # 3) retirement (confidence floor / staleness). A CONFIRM'd entry is rescued: it is
+        #    exempt from retirement in the same pass (its conf is 1.0 and last is refreshed
+        #    above, but guard explicitly so the intent survives future reordering).
+        if not retire and nm not in force_confirm:
+            if e["confidence"] < FLOOR:
+                retire, reason = True, "confidence floor"
+            elif e.get("last"):
+                try:
+                    age = (today - date.fromisoformat(e["last"])).days
+                    if age > STALENESS_DAYS:
+                        retire, reason = True, "staleness"
+                except ValueError:
+                    pass
+
+        if retire:
+            plan["retired"].append({"name": e["name"], "reason": reason, "evkey": evkey})
+            if apply:
+                _do_retire(e, memory_dir, reason, tstr, tombstones)
+        elif apply:
+            _write_back(e)
+
+    # 4) mine new candidate routines (skip cool-off + already-present)
+    mined = _mine_pairs(sessions)
+    for (a, b), stats in sorted(mined.items()):
+        evkey = f"{a}>>{b}"
+        if evkey in existing_keys:
+            continue
+        ts = tombstones.get(evkey)
+        if ts:
+            try:
+                if (today - date.fromisoformat(ts["retired"])).days <= COOLOFF_DAYS:
+                    plan["skipped_cooloff"].append(evkey)
+                    continue
+            except (ValueError, KeyError):
+                pass
+        plan["new"].append({"evkey": evkey, **stats})
+        if apply:
+            _write_new(memory_dir, a, b, stats, tstr)
+
+    # Write tombstones only when there is (or was) something to record -- a scheduled
+    # no-op run must leave zero filesystem traces (the 2026-07-21 no-op-commit lesson).
+    if apply and (tombstones or os.path.exists(tombstone_path)):
+        os.makedirs(os.path.dirname(tombstone_path), exist_ok=True)
+        _atomic_write(tombstone_path, json.dumps(list(tombstones.values()), indent=2))
+    return plan
+
+
+def _atomic_write(path, text):
+    """Write text to path atomically (temp file in the same dir + os.replace), so an
+    interrupted scheduled run can never truncate/corrupt a state file (MEMORY.md,
+    tombstones.json, a memory entry). Best-effort: swallows OSError like the callers did."""
+    d = os.path.dirname(path) or "."
+    tmp = None
+    try:
+        fd, tmp = tempfile.mkstemp(dir=d, prefix=".distill-", suffix=".tmp")
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        os.replace(tmp, path)
+    except OSError:
+        if tmp and os.path.exists(tmp):
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+
+
+def _write_back(e):
+    body = e["body"]
+    body = _set_field(body, "Confidence", f"{e['confidence']:.2f}")
+    if e.get("last"):
+        body = _set_field(body, "Last-observed", e["last"])
+    _atomic_write(e["path"], "---\n" + e["front"] + "\n---\n\n" + body.lstrip("\n"))
+
+
+def _do_retire(e, memory_dir, reason, tstr, tombstones):
+    retired_dir = os.path.join(memory_dir, "retired")
+    os.makedirs(retired_dir, exist_ok=True)
+    note = f"\n<!-- RETIRED {tstr}: {reason} -->\n"
+    fname = os.path.basename(e["path"])
+    _atomic_write(os.path.join(retired_dir, fname), e["text"].rstrip() + note)
+    try:
+        os.remove(e["path"])
+    except OSError:
+        pass
+    if e.get("evkey"):
+        tombstones[e["evkey"]] = {"evkey": e["evkey"], "name": e["name"],
+                                  "retired": tstr, "reason": reason}
+    # Remove the entry's line from MEMORY.md if present. Match the exact filename in the link,
+    # or the name as a whole token -- a bare substring test would also delete a similarly-named
+    # entry (retiring "routine-foo" must NOT drop "routine-foo-bar").
+    mem_index = os.path.join(memory_dir, "MEMORY.md")
+    if os.path.exists(mem_index):
+        try:
+            lines = open(mem_index, encoding="utf-8").read().splitlines()
+            name_re = re.compile(r"(?<![\w-])" + re.escape(e["name"]) + r"(?![\w-])")
+            kept = [ln for ln in lines if fname not in ln and not name_re.search(ln)]
+            _atomic_write(mem_index, "\n".join(kept) + "\n")
+        except OSError:
+            pass
+
+
+def _slug(a, b):
+    s = re.sub(r"[^a-z0-9]+", "-", f"{a}-to-{b}".lower()).strip("-")
+    full = "routine-" + s
+    if len(full) > 60:
+        # Preserve uniqueness when truncating, else two long distinct pairs could collide
+        # on the first 60 chars and the second would be silently skipped.
+        import hashlib
+        return full[:55] + "-" + hashlib.sha256(full.encode("utf-8")).hexdigest()[:4]
+    return full
+
+
+def _write_new(memory_dir, a, b, stats, tstr):
+    name = _slug(a, b)
+    path = os.path.join(memory_dir, name + ".md")
+    if os.path.exists(path):
+        return
+    entry = (
+        "---\n"
+        f"name: {name}\n"
+        f"description: \"Distilled routine: after {a}, {b} reliably follows.\"\n"
+        "metadata:\n"
+        "  type: procedural\n"
+        "---\n\n"
+        f"## {a} -> {b}\n\n"
+        f"**Subtype:** routine\n"
+        f"**Trigger:** event `{a}` occurs\n"
+        f"**Inferred action:** `{b}` follows\n"
+        f"**Confidence:** {INITIAL_CONFIDENCE:.2f}\n"
+        f"**First-observed:** {tstr}\n"
+        f"**Last-observed:** {tstr}\n"
+        f"**Evidence-key:** {a}>>{b}\n\n"
+        f"Observed {stats['count']} times in {stats['opportunities']} opportunities "
+        f"(consistency {stats['consistency']}). Distilled by distill_procedural.py; "
+        f"probationary until re-confirmed. This is an INFERENCE, not an asserted fact.\n"
+    )
+    _atomic_write(path, entry)
+
+
+# --- backfill: seed procedural PROPOSALS from hand-written feedback records ----
+
+BACKFILL_LIMIT = 5
+BACKFILL_CONFIDENCE = 0.6
+
+_HOWTO = re.compile(r"(?is)\*\*How to apply:\*\*\s*(.+?)(?:\n\s*\n|\Z)")
+_DESC = re.compile(r"(?im)^description:\s*(.+?)\s*$")
+_ISO_DATE = re.compile(r"\b(20[0-9]{2}-[0-9]{2}-[0-9]{2})\b")
+_WHEN_SPLIT = re.compile(r"(?is)^when\s+(.+?)[,:]\s+(.+)$")
+
+
+def _is_feedback(front):
+    return re.search(r"(?im)^\s*type:\s*feedback\b", front) is not None
+
+
+def _squash(text, limit=240):
+    text = re.sub(r"\s+", " ", text).strip()
+    if len(text) > limit:
+        text = text[:limit].rsplit(" ", 1)[0].rstrip(",;") + " ..."
+    return text
+
+
+def _unquote(s):
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ("\"", "'"):
+        s = s[1:-1]
+    return s.replace('\\"', '"')
+
+
+def _backfill_candidates(memory_dir):
+    """Deterministic scan: every `type: feedback` record carrying a **How to apply:**
+    line is behavior-shaped enough to propose a routine from. Sorted by filename."""
+    out = []
+    if not os.path.isdir(memory_dir):
+        return out
+    for fn in sorted(os.listdir(memory_dir)):
+        if not fn.endswith(".md") or fn == "MEMORY.md":
+            continue
+        try:
+            text = open(os.path.join(memory_dir, fn), encoding="utf-8").read()
+        except OSError:
+            continue
+        front, body = _split_frontmatter(text)
+        if not _is_feedback(front):
+            continue
+        how = _HOWTO.search(body)
+        if not how:
+            continue
+        dm = _DESC.search(front)
+        desc = _squash(_unquote(dm.group(1))) if dm else ""
+        how_text = _squash(how.group(1), limit=400)
+        wm = _WHEN_SPLIT.match(how_text)
+        if wm:
+            # bare clause, no "when " prefix: the Act stage renders "when {trigger}"
+            trigger = _squash(wm.group(1))
+            action = _squash(wm.group(2))
+        else:
+            trigger = desc or _squash(fn[:-3].replace("-", " ").replace("_", " "))
+            if trigger.lower().startswith("when "):
+                trigger = trigger[5:]
+            action = how_text
+        dates = sorted(_ISO_DATE.findall(body))
+        stem = fn[:-3]
+        for pre in ("feedback-", "feedback_"):
+            if stem.startswith(pre):
+                stem = stem[len(pre):]
+                break
+        out.append({
+            "src": fn,
+            "name": "procedural-" + stem,
+            "title": stem.replace("-", " ").replace("_", " "),
+            "trigger": trigger,
+            "action": action,
+            "first": dates[0] if dates else None,
+        })
+    return out
+
+
+def _write_proposal(output_dir, cand, tstr):
+    path = os.path.join(output_dir, cand["name"] + ".md")
+    if os.path.exists(path):
+        return path, False
+    first = cand["first"] or tstr
+    entry = (
+        "---\n"
+        f"name: {cand['name']}\n"
+        f"description: \"PROPOSAL backfilled from {cand['src']} -- human review required "
+        "before adoption into live memory.\"\n"
+        "metadata:\n"
+        "  type: procedural\n"
+        "  source: backfill-from-feedback\n"
+        "---\n\n"
+        f"## {cand['title']}\n\n"
+        "**Subtype:** routine\n"
+        f"**Trigger:** {cand['trigger']}\n"
+        f"**Inferred action:** {cand['action']}\n"
+        f"**Confidence:** {BACKFILL_CONFIDENCE:.2f}\n"
+        f"**First-observed:** {first}\n"
+        f"**Last-observed:** {tstr}\n"
+        f"**Evidence-key:** feedback:{cand['src']}\n\n"
+        f"Backfilled from the hand-written feedback record `{cand['src']}` by "
+        "distill_procedural.py --backfill-from-feedback (verification seed, 2026-07-20 "
+        "inventory fix 3). This is an INFERENCE PROPOSAL, not an asserted fact: a human "
+        "moves it into the live memory dir (and indexes it in MEMORY.md) to adopt it, "
+        "or deletes it to reject it.\n"
+    )
+    _atomic_write(path, entry)
+    return path, True
+
+
+def backfill_from_feedback(memory_dir, output_dir, today, limit=BACKFILL_LIMIT):
+    """Read feedback records from memory_dir; write procedural PROPOSALS to output_dir.
+    NEVER writes into memory_dir. Idempotent: an existing proposal file is left alone."""
+    mem = os.path.abspath(memory_dir)
+    out = os.path.abspath(output_dir)
+    if out == mem or (out + os.sep).startswith(mem + os.sep):
+        raise ValueError("--output-dir must not be (or live inside) the memory dir "
+                         "(proposals are staged for human review, never written into live memory)")
+    cands = _backfill_candidates(memory_dir)[:max(0, limit)]
+    written, skipped = [], []
+    if cands:
+        os.makedirs(output_dir, exist_ok=True)
+    tstr = today.isoformat()
+    for c in cands:
+        path, wrote = _write_proposal(output_dir, c, tstr)
+        (written if wrote else skipped).append((c["name"], path))
+    return written, skipped
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Procedural-memory distill pass (D1 lifecycle + v1 miner).")
+    ap.add_argument("--cwd", default=os.getcwd())
+    ap.add_argument("--memory-dir", help="override the project memory dir (testing / backfill input)")
+    ap.add_argument("--evidence-dir", "--usage-dir", dest="evidence_dir",
+                    help="override the observe-stream dir (default: .ai-assistance/local)")
+    ap.add_argument("--worklog", help="worklog path to scan for RETIRE/CONFIRM markers")
+    ap.add_argument("--today", help="ISO date override (testing)")
+    ap.add_argument("--apply", action="store_true", help="write changes (default: dry-run)")
+    ap.add_argument("--backfill-from-feedback", action="store_true",
+                    help="propose procedural records from `type: feedback` records; requires "
+                         "--memory-dir (input) and --output-dir (staging; never live memory)")
+    ap.add_argument("--output-dir", help="backfill only: where proposals are written")
+    ap.add_argument("--limit", type=int, default=BACKFILL_LIMIT,
+                    help=f"backfill only: max proposals to write (default {BACKFILL_LIMIT})")
+    a = ap.parse_args(argv)
+
+    if a.backfill_from_feedback:
+        if not a.memory_dir or not a.output_dir:
+            print("[distill] --backfill-from-feedback requires --memory-dir (input) and "
+                  "--output-dir (proposal staging dir)")
+            return 2
+        try:
+            written, skipped = backfill_from_feedback(
+                a.memory_dir, a.output_dir, _today(a.today), a.limit)
+        except ValueError as e:
+            print(f"[distill] {e}")
+            return 2
+        for name, path in written:
+            print(f"[distill] proposal written: {name} -> {path}")
+        for name, _path in skipped:
+            print(f"[distill] proposal skipped (exists): {name}")
+        print(f"[distill] backfill: {len(written)} proposal(s) written, {len(skipped)} skipped "
+              "-- review and move approved ones into the live memory dir yourself.")
+        return 0
+
+    local_dir = os.path.join(a.cwd, ".ai-assistance", "local")
+    evidence_dir = a.evidence_dir or local_dir
+    if not a.memory_dir and not _consent(local_dir):
+        print("[distill] observe consent not set (no procedural-observe.enabled / "
+              "PROCEDURAL_OBSERVE) -- 0 records distilled (refusing to read the observe stream).")
+        return 0
+    memory_dir = a.memory_dir or os.path.join(
+        os.path.expanduser("~"), ".claude", "projects", _project_slug(a.cwd), "memory")
+    worklog = a.worklog or os.path.join(a.cwd, "docs", "worklog.md")
+
+    plan = run(memory_dir, evidence_dir, a.worklog and worklog, a.apply, _today(a.today))
+    mode = "APPLIED" if a.apply else "DRY-RUN"
+    total = sum(len(v) for v in plan.values())
+    if total == 0:
+        # No-op-safe scheduled run: exactly one clear line, zero writes, exit 0.
+        print(f"[distill] {mode} -- 0 records distilled (memory={memory_dir})")
+        return 0
+    print(f"[distill] {mode} -- memory={memory_dir}")
+    for k in ("new", "up", "down", "confirmed", "retired", "skipped_cooloff"):
+        v = plan[k]
+        if not v:
+            continue
+        print(f"  {k:16} {len(v)}")
+        for item in v:
+            print(f"    - {item}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

data/.ai-assistance/scripts/log-mcp-access.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# log-mcp-access.sh -- PostToolUse hook (matcher: mcp__.*) that DETERMINISTICALLY
+# records every MCP tool call to the local access-audit ledger. Deterministic capture
+# slice of standards/security/access-audit-ledger.md (v0 local store).
+#
+# Standard: standards/security/access-audit-ledger.md ("Record schema" -- fields marked
+# CAPTURED are exactly what this script writes; nothing else).
+#
+# Wired in .claude/settings.json (this repo) and templates/claude-settings/settings.json.*:
+#   "PostToolUse": [{ "matcher": "mcp__.*",
+#       "hooks": [{ "type": "command",
+#                   "command": "bash .ai-assistance/scripts/log-mcp-access.sh 2>/dev/null || true" }] }]
+#
+# Reads:  stdin -- the PostToolUse JSON (tool_name, tool_input, tool_response, session_id, cwd)
+# Writes: .ai-assistance/local/audit/access-<YYYY-WNN>.jsonl (one appended line)
+#
+# NOTE: uses `python -c`-equivalent invocation of a sibling .py file (NOT a heredoc) so the
+# hook's stdin -- the PostToolUse JSON -- reaches python unaltered.
+# Fails OPEN and SILENT on any error: an audit logger must never wedge, slow, or deny a
+# tool call. Always exits 0 with no stdout.
+PY=python3
+command -v python3 >/dev/null 2>&1 || PY=python
+"$PY" "$(dirname "$0")/log_mcp_access.py" 2>/dev/null || true
+exit 0