@caddis/cli 0.2.5 → 0.3.0

package/bundles/antigravity-plugin/scripts/claudster_migrate_rules.py

@@ -0,0 +1,300 @@
+"""claudster_migrate_rules — migrate a repo's rules hierarchy to AGENTS.md-canonical + CLAUDE.md shims.
+
+`AGENTS.md` is the canonical rules file every agent reads (Claude Code, Codex CLI, Antigravity); each
+`CLAUDE.md` becomes a thin `@AGENTS.md` import shim. This tool migrates an existing repo — root pair +
+every subfolder `CLAUDE.md` — to that layout, safely and idempotently.
+
+Behavior (per target repo):
+  • ROOT: CLAUDE.md's (fuller, possibly enriched) content becomes the canonical AGENTS.md, re-headed
+    agent-neutrally; CLAUDE.md becomes the shim. An existing AGENTS.md that is the old caddis mirror
+    (a subset of CLAUDE.md) is replaced. If the existing AGENTS.md carries content CLAUDE.md LACKS
+    (project enrichments on both sides), it is a CONFLICT — the root pair is skipped and reported
+    (exit 1); a human resolves the few by hand-merge, then re-runs to confirm.
+  • SUBFOLDERS: each <dir>/CLAUDE.md is `git mv`'d to <dir>/AGENTS.md (content verbatim) + a <dir>/CLAUDE.md shim.
+  • Idempotent (a re-run is a no-op); refuses a dirty tree (unless --allow-dirty); `--dry-run` is the
+    default (`--apply` executes); `git mv` when tracked; never touches archived `done/`-style files.
+  • --check (fork detector): flags any CLAUDE.md that is NOT a shim beside an AGENTS.md (drifted shim),
+    and any bare CLAUDE.md with no sibling AGENTS.md (a hand-created fork). Exit 1 on findings.
+
+Usage:
+    python scripts/claudster_migrate_rules.py [target]              # dry-run (default)
+    python scripts/claudster_migrate_rules.py [target] --apply      # execute
+    python scripts/claudster_migrate_rules.py [target] --check      # fork detector (gate)
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# Reuse the harness templates + folder shim so the migration output matches what the generator emits.
+try:
+    from setup_project_ai import HARNESS_DIR, SUBFOLDER_SHIM, render as _render
+except Exception:  # pragma: no cover — standalone fallback if setup_project_ai isn't importable
+    HARNESS_DIR = None
+    SUBFOLDER_SHIM = ("# Folder conventions — canonical in AGENTS.md (imported below; Claude Code inlines it)\n"
+                      "@AGENTS.md\n")
+
+    def _render(text, mapping):  # type: ignore
+        for k, v in mapping.items():
+            text = text.replace("{{" + k + "}}", v)
+        return text
+
+# Directories we never migrate into (vendored/generated + archived rules).
+SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".mypy_cache", ".ruff_cache",
+             ".pytest_cache", "dist", "build", ".tanstack", "done", "archive", "archived"}
+
+# Section headings whose bodies are pure template boilerplate — their wording differs between the old
+# root.md.tmpl and agents.md.tmpl, so they are excluded from the divergence check (only PROJECT content
+# is compared). "What this project is" is intentionally NOT here — its content IS compared.
+_BOILERPLATE_HEADING_KEYS = (
+    "the laws", "the harness", "development harness", "context discipline", "conventions",
+    "where things live", "doc discipline", "resuming a session", "resources", "why subagents",
+)
+
+_CANONICAL_PREAMBLE = (
+    "> **This is the canonical rules file.** Every coding agent reads it — Claude Code (via the one-line\n"
+    "> `@AGENTS.md` import in `CLAUDE.md`), OpenAI Codex CLI, and Antigravity (`agy`). `CLAUDE.md` is a\n"
+    "> thin `@AGENTS.md` import shim; keep durable project rules HERE, never in the shim."
+)
+
+
+# ── git helpers ──────────────────────────────────────────────────────────────
+def _git(target: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=str(target), capture_output=True, text=True)
+
+
+def _in_git_repo(target: Path) -> bool:
+    r = _git(target, "rev-parse", "--is-inside-work-tree")
+    return r.returncode == 0 and r.stdout.strip() == "true"
+
+
+def _is_dirty(target: Path) -> bool:
+    return bool(_git(target, "status", "--porcelain").stdout.strip())
+
+
+def _is_tracked(target: Path, rel: str) -> bool:
+    return bool(_git(target, "ls-files", "--error-unmatch", rel).returncode == 0)
+
+
+# ── content helpers ──────────────────────────────────────────────────────────
+def is_shim(text: str) -> bool:
+    """A CLAUDE.md is a shim iff it carries a bare `@AGENTS.md` import line."""
+    return any(ln.strip() == "@AGENTS.md" for ln in text.splitlines())
+
+
+def _project_name(claude_text: str, target: Path) -> str:
+    for ln in claude_text.splitlines():
+        if ln.startswith("# "):
+            title = ln[2:].strip()
+            # "<name> — Project Memory (root)" -> "<name>"
+            for sep in (" — ", " - ", " –– "):
+                if sep in title:
+                    return title.split(sep, 1)[0].strip()
+            return title
+    return target.name
+
+
+def _meaningful(text: str) -> set[str]:
+    """Normalized set of content lines (md markers/whitespace stripped), for subset comparison."""
+    out: set[str] = set()
+    for ln in text.splitlines():
+        s = ln.strip().lstrip("#>-*").strip()
+        # drop an ordered-list prefix like "1. "
+        while s[:1].isdigit():
+            s = s[1:]
+        s = s.lstrip(". ").strip()
+        if len(s) >= 8:
+            out.add(s.lower())
+    return out
+
+
+def _checkable_lines(agents_text: str) -> set[str]:
+    """AGENTS.md's PROJECT content — meaningful lines from non-boilerplate-heading sections (and the
+    preamble is dropped). Compared against CLAUDE.md to detect divergence."""
+    lines = agents_text.splitlines()
+    # find section spans by "## " headings
+    heads = [i for i, l in enumerate(lines) if l.startswith("## ")]
+    out: set[str] = set()
+    for k, start in enumerate(heads):
+        heading = lines[start][3:].strip().lower()
+        if any(key in heading for key in _BOILERPLATE_HEADING_KEYS):
+            continue
+        end = heads[k + 1] if k + 1 < len(heads) else len(lines)
+        out |= _meaningful("\n".join(lines[start:end]))
+    return out
+
+
+def root_conflict(claude_text: str, agents_text: str) -> list[str]:
+    """Return AGENTS.md project lines that CLAUDE.md lacks (the enrichment residue). Non-empty => the
+    two files diverged and must not be auto-merged."""
+    residue = _checkable_lines(agents_text) - _meaningful(claude_text)
+    return sorted(residue)
+
+
+def reheaded_agents(claude_text: str, name: str) -> str:
+    """Canonical AGENTS.md from CLAUDE.md content: replace the shim/mirror preamble (everything before
+    the first `## ` heading) with a canonical header + preamble; keep the body (enrichments) verbatim."""
+    lines = claude_text.splitlines()
+    idx = next((i for i, l in enumerate(lines) if l.startswith("## ")), None)
+    body = "\n".join(lines[idx:]) if idx is not None else claude_text
+    header = f"# {name} — Project Memory (canonical rules)\n\n{_CANONICAL_PREAMBLE}\n\n"
+    text = header + body
+    return text if text.endswith("\n") else text + "\n"
+
+
+def root_shim(name: str) -> str:
+    """The root CLAUDE.md shim — the harness root.md.tmpl rendered (reused, so no drift)."""
+    if HARNESS_DIR is not None:
+        tmpl = HARNESS_DIR / "claude-md" / "root.md.tmpl"
+        if tmpl.is_file():
+            return _render(tmpl.read_text(encoding="utf-8"), {"PROJECT_NAME": name})
+    return (f"# {name} — Project Memory\n\n@AGENTS.md\n\n"
+            "> **Canonical rules live in `AGENTS.md`** (imported above — Claude Code inlines it). This\n"
+            "> shim adds only Claude-native conveniences; durable rules go in `AGENTS.md`.\n")
+
+
+# ── migration steps ──────────────────────────────────────────────────────────
+def _write(target: Path, rel: str, content: str, apply: bool, report: list[str], verb: str):
+    report.append(f"{verb}: {rel}")
+    if apply:
+        dest = target / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+
+
+def _move(target: Path, src_rel: str, dst_rel: str, apply: bool, report: list[str]):
+    report.append(f"move: {src_rel} -> {dst_rel}")
+    if not apply:
+        return
+    if _is_tracked(target, src_rel):
+        r = _git(target, "mv", src_rel, dst_rel)
+        if r.returncode == 0:
+            return
+    # untracked (or git mv failed): plain rename
+    (target / dst_rel).parent.mkdir(parents=True, exist_ok=True)
+    os.replace(target / src_rel, target / dst_rel)
+
+
+def migrate_root(target: Path, apply: bool, report: list[str]) -> int:
+    """Migrate the root pair. Returns 1 on conflict (root skipped), else 0."""
+    claude = target / "CLAUDE.md"
+    agents = target / "AGENTS.md"
+    if not claude.exists() and not agents.exists():
+        report.append("root: no CLAUDE.md/AGENTS.md — nothing to migrate")
+        return 0
+    claude_text = claude.read_text(encoding="utf-8") if claude.exists() else ""
+    if claude.exists() and is_shim(claude_text) and agents.exists():
+        report.append("root: already migrated (CLAUDE.md is a shim) — no-op")
+        return 0
+    if not claude.exists():
+        report.append("root: AGENTS.md present, no CLAUDE.md — leaving as-is (already canonical or hand-authored)")
+        return 0
+    name = _project_name(claude_text, target)
+    if agents.exists():
+        conflict = root_conflict(claude_text, agents.read_text(encoding="utf-8"))
+        if conflict:
+            report.append("root: CONFLICT — AGENTS.md carries content CLAUDE.md lacks; skipping root pair. "
+                          "Hand-merge into CLAUDE.md, then re-run. Divergent line(s): "
+                          + "; ".join(conflict[:5]) + (" …" if len(conflict) > 5 else ""))
+            return 1
+    # safe: CLAUDE.md content -> canonical AGENTS.md; CLAUDE.md -> shim
+    _write(target, "AGENTS.md", reheaded_agents(claude_text, name), apply, report,
+           "rewrite (canonical)" if agents.exists() else "create (canonical)")
+    _write(target, "CLAUDE.md", root_shim(name), apply, report, "shim")
+    return 0
+
+
+def _iter_subfolder_claude(target: Path):
+    for dirpath, dirnames, filenames in os.walk(target):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        d = Path(dirpath)
+        if d == target:
+            continue  # root handled separately
+        if "CLAUDE.md" in filenames:
+            yield d
+
+
+def migrate_subfolders(target: Path, apply: bool, report: list[str]) -> None:
+    for d in _iter_subfolder_claude(target):
+        rel = d.relative_to(target).as_posix()
+        claude_text = (d / "CLAUDE.md").read_text(encoding="utf-8")
+        if is_shim(claude_text) and (d / "AGENTS.md").exists():
+            report.append(f"{rel}/: already migrated — no-op")
+            continue
+        if (d / "AGENTS.md").exists():
+            report.append(f"{rel}/: CONFLICT — both AGENTS.md and a non-shim CLAUDE.md present; skipped")
+            continue
+        _move(target, f"{rel}/CLAUDE.md", f"{rel}/AGENTS.md", apply, report)
+        _write(target, f"{rel}/CLAUDE.md", SUBFOLDER_SHIM, apply, report, "shim")
+
+
+def check_forks(target: Path) -> list[str]:
+    """Fork detector: non-shim CLAUDE.md beside an AGENTS.md, or a bare CLAUDE.md with no sibling AGENTS.md."""
+    findings: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(target):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        if "CLAUDE.md" not in filenames:
+            continue
+        d = Path(dirpath)
+        rel = (d / "CLAUDE.md").relative_to(target).as_posix()
+        text = (d / "CLAUDE.md").read_text(encoding="utf-8", errors="replace")
+        if "AGENTS.md" in filenames:
+            if not is_shim(text):
+                findings.append(f"{rel}: CLAUDE.md is not a shim but a sibling AGENTS.md exists (drifted shim)")
+        else:
+            findings.append(f"{rel}: CLAUDE.md has no sibling AGENTS.md (hand-created fork — run /caddis:add-rules semantics)")
+    return findings
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+def main(argv: list[str] | None = None) -> int:
+    for _stream in (sys.stdout, sys.stderr):  # Windows cp1252 can't encode em-dashes in our messages
+        if hasattr(_stream, "reconfigure"):
+            _stream.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description="Migrate a repo to AGENTS.md-canonical rules + CLAUDE.md shims.")
+    ap.add_argument("target", nargs="?", default=".", type=Path)
+    ap.add_argument("--apply", action="store_true", help="Execute (default is --dry-run).")
+    ap.add_argument("--allow-dirty", action="store_true", help="Proceed even if the working tree is dirty.")
+    ap.add_argument("--check", action="store_true", help="Fork detector only (gate mode); exit 1 on findings.")
+    args = ap.parse_args(argv)
+
+    target = args.target.resolve()
+    if not target.is_dir():
+        print(f"ERROR: target not a directory: {target}", file=sys.stderr)
+        return 2
+
+    if args.check:
+        findings = check_forks(target)
+        for f in findings:
+            print(f"  fork: {f}")
+        if findings:
+            print(f"\n{len(findings)} rules-file fork(s) found.")
+            return 1
+        print("No rules-file forks — CLAUDE.md shims are clean.")
+        return 0
+
+    apply = args.apply
+    if not _in_git_repo(target):
+        print(f"ERROR: {target} is not a git repository (rules migration uses git mv).", file=sys.stderr)
+        return 2
+    if apply and _is_dirty(target) and not args.allow_dirty:
+        print("ERROR: working tree is dirty — commit/stash first, or pass --allow-dirty.", file=sys.stderr)
+        return 2
+
+    print(f"=== caddis-migrate-rules -> {target} {'(APPLY)' if apply else '(dry-run)'}")
+    report: list[str] = []
+    rc = migrate_root(target, apply, report)
+    migrate_subfolders(target, apply, report)
+    for line in report:
+        print(f"   {line}")
+    if not apply:
+        print("\n(dry-run — no files changed; pass --apply to execute)")
+    print(f"\nresult: {'CONFLICT (root skipped)' if rc else 'ok'}")
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/dream_capture.py

@@ -0,0 +1,249 @@
+"""Deterministic Dream Memory capture from a Stop transcript (fann Phase 5b).
+
+Pure, filesystem-free extraction of *high-confidence* fact candidates from a parsed transcript,
+plus privacy redaction. The hook (``session_end.py``) does the I/O — read the transcript, call
+:func:`extract_facts`, then consolidate via ``dream_memory`` and rewrite the store. Keeping the
+logic here (dicts in → dicts out) makes it unit-testable without a tree, mirroring the engine.
+
+Two kinds are captured (the only ones inferable *without an LLM* — the rich kinds come from the
+knowledge-transfer agent in 5d):
+  • **failure-mode** — a ``Bash`` tool call whose result is an error (``is_error``). One candidate
+    per distinct command per session; cross-session recurrence is what reinforces it.
+  • **workflow-success** — a *build/test* command that succeeded after the same command failed
+    earlier in the same session (the red→green signal).
+
+PRIVACY (hard constraint, see the design doc): a fact must be safe to print at SessionStart and
+(eventually) to commit. So we (1) **skip entirely** any command that touches a secret file
+(``.env``, ``**/secrets/**``, ``*.pem``/``*.key``, credential files — guard.py's secret sense),
+and (2) **redact** inline secrets (``KEY=…``, ``--token …``, ``Bearer …``, URLs with credentials,
+known token shapes, long high-entropy blobs) from both the command head and the error line. The
+dedup key derives from the *redacted* command, so a token can never leak into the store's key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from dream_memory import make_fact, normalize_key  # sibling module in scripts/
+
+# --------------------------------------------------------------------------- #
+# Limits — keep the store lean and a single Stop's append bounded.
+# --------------------------------------------------------------------------- #
+MAX_FACTS_PER_RUN = 15      # cap candidates emitted from one transcript
+_HEAD_LEN = 80              # command head kept (we store heads, not full args)
+_ERR_LEN = 120             # first error line kept
+_SUMMARY_LEN = 200          # final clamp on a summary
+
+
+# --------------------------------------------------------------------------- #
+# Privacy — redaction + secret-path skip. Mirrors guard.py's secret sense but
+# operates on inline text (value-level scrubbing), not just file-path classing.
+# --------------------------------------------------------------------------- #
+_URL_CRED = re.compile(r"(\w[\w+.\-]*://)[^/\s:@]+:[^/\s@]+@")
+_SENSITIVE_KEY = re.compile(
+    r"\b([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD|CREDENTIAL|CREDENTIALS|AUTH|APIKEY|PRIVATE)[A-Za-z0-9_]*)"
+    r"(\s*[=:]\s*)(\"[^\"]*\"|'[^']*'|\S+)",
+    re.I,
+)
+_SENSITIVE_FLAG = re.compile(
+    r"(--?(?:password|passwd|pwd|token|secret|api[-_]?key|access[-_]?key|auth)\b)(\s+|=)(\"[^\"]*\"|'[^']*'|\S+)",
+    re.I,
+)
+# MySQL/MariaDB attached-password flag: `-pVALUE` glued to the flag (no separator).
+# Scoped to mysql-family commands so `cp -pr`, `mkdir -p`, `docker -p 8080:80`,
+# `ssh -p22` are never touched. Value may be quoted (`-p"my pass"`).
+_MYSQL_PW = re.compile(
+    r"(\b(?:mysql|mysqldump|mariadb|mysqladmin)\b[^\n]*?\s-p)(\"[^\"]*\"|'[^']*'|\S+)",
+    re.I,
+)
+# curl basic-auth: `-u user:pass` / `--user user:pass` (value may be glued to -u).
+# Scoped to curl so `python -u`, `sort -u`, `docker run -u 1000:1000` survive.
+_CURL_USERPASS = re.compile(
+    r"(\bcurl\b[^\n]*?\s(?:--user|-u)\s*)(\"[^\"]*\"|'[^']*'|\S+)",
+    re.I,
+)
+# AWS credential keys given WHITESPACE-separated (e.g. `aws configure set
+# aws_secret_access_key <k>`); the `=`/`:` form is already caught by _SENSITIVE_KEY.
+_AWS_CRED = re.compile(
+    r"\b(aws_secret_access_key|aws_access_key_id|aws_session_token)\b"
+    r"(\s+|\s*[=:]\s*)(\"[^\"]*\"|'[^']*'|\S+)",
+    re.I,
+)
+_AUTH_HEADER = re.compile(r"\b(authorization|x-api-key)\b(\s*:\s*|\s+)(?:bearer\s+)?\S+", re.I)
+_BEARER = re.compile(r"\bbearer\s+[A-Za-z0-9._\-]+", re.I)
+_TOKEN_PREFIX = re.compile(
+    r"\b(?:gh[posru]_[A-Za-z0-9]{6,}|sk-[A-Za-z0-9]{6,}|xox[baprs]-[A-Za-z0-9-]{6,}|AKIA[0-9A-Z]{12,})"
+)
+# Long high-entropy blob (a letter AND a digit, ≥40 chars). Excludes '/' so file paths survive.
+_LONG_TOKEN = re.compile(r"\b(?=[A-Za-z0-9+=_\-]*[A-Za-z])(?=[A-Za-z0-9+=_\-]*[0-9])[A-Za-z0-9+=_\-]{40,}\b")
+
+_SECRET_PATH = re.compile(
+    r"(?:^|[\s=:'\"/\\])\.env(?:\.|$|[\s'\"/\\])"
+    r"|[/\\]\.?secrets?[/\\]"
+    r"|\b(?:id_rsa|id_dsa|id_ecdsa|id_ed25519|credentials|\.npmrc|\.pypirc|\.netrc|\.pgpass|\.htpasswd)\b"
+    r"|\.(?:pem|key|p12|pfx|keystore|jks)\b",
+    re.I,
+)
+
+
+def redact(text: str) -> str:
+    """Scrub inline secrets from ``text`` so it's safe to store, surface, and commit.
+
+    Order matters: credentialed URLs first, then whole-value header/bearer forms (these must run
+    before the generic ``KEY=…`` rule, else "Authorization" matches as a key and only eats the
+    word "Bearer", leaking the token), then explicit ``KEY=…`` / ``--token …`` assignments, then
+    known token prefixes, then a catch-all for long high-entropy blobs. Conservative on file paths
+    (the blob rule excludes ``/``) so an error line stays useful.
+    """
+    if not text:
+        return ""
+    t = str(text)
+    t = _URL_CRED.sub(r"\1***:***@", t)
+    t = _AUTH_HEADER.sub(r"\1: ***", t)
+    t = _BEARER.sub("bearer ***", t)
+    t = _SENSITIVE_KEY.sub(r"\1=***", t)
+    t = _AWS_CRED.sub(r"\1 ***", t)
+    t = _SENSITIVE_FLAG.sub(r"\1 ***", t)
+    t = _CURL_USERPASS.sub(r"\1***", t)
+    t = _MYSQL_PW.sub(r"\1***", t)
+    t = _TOKEN_PREFIX.sub("***", t)
+    t = _LONG_TOKEN.sub("***", t)
+    return t
+
+
+def touches_secret(command: str) -> bool:
+    """True if ``command`` references a secret file/path — such a fact is never stored at all."""
+    return bool(_SECRET_PATH.search(command or ""))
+
+
+# --------------------------------------------------------------------------- #
+# Text shaping
+# --------------------------------------------------------------------------- #
+def command_head(command: str, max_len: int = _HEAD_LEN) -> str:
+    """Whitespace-collapsed, length-capped command head — we store heads, not full arg lists."""
+    c = " ".join((command or "").split())
+    return c[:max_len].rstrip()
+
+
+def command_fp(command: str) -> str:
+    """Stable dedup fingerprint of the FULL command (whitespace-collapsed, lowercased), hashed so two
+    distinct commands that share a truncated 80-char head don't merge into one inflated fact. Kept
+    separate from the display head on purpose. Pass the ALREADY-REDACTED command so no secret is hashed."""
+    norm = " ".join((command or "").split()).lower()
+    return hashlib.sha1(norm.encode("utf-8")).hexdigest()[:16]
+
+
+def first_error_line(output: str, max_len: int = _ERR_LEN) -> str:
+    """First non-empty line of tool output, length-capped — the error's gist, not the whole dump."""
+    for line in (output or "").splitlines():
+        s = line.strip()
+        if s:
+            return s[:max_len]
+    return ""
+
+
+# Commands whose non-zero exit is routine control flow / a search miss — not a durable lesson.
+_NOISE_FIRST_TOKEN = frozenset({
+    "grep", "rg", "test", "[", "find", "ls", "cat", "which", "type", "head", "tail", "diff",
+})
+
+# Build/test commands — only these qualify for the red→green workflow-success signal.
+_BUILD_TEST = re.compile(
+    r"\b(?:pytest|tox|nox|unittest|jest|vitest|mocha|"
+    r"npm\s+(?:run\s+\S+|test|ci)|yarn\s+\S+|pnpm\s+\S+|"
+    r"vite(?:\s+build)?|tsc\b|go\s+(?:test|build)|cargo\s+(?:test|build)|"
+    r"make\b|gradle\b|mvn\b|dotnet\s+(?:test|build)|rspec|phpunit)\b",
+    re.I,
+)
+
+
+def _is_noise_failure(command: str) -> bool:
+    toks = (command or "").strip().split()
+    return bool(toks) and toks[0] in _NOISE_FIRST_TOKEN
+
+
+# --------------------------------------------------------------------------- #
+# Transcript walking
+# --------------------------------------------------------------------------- #
+def _content_blocks(record: dict) -> list[dict]:
+    """The list of content blocks in a transcript record (handles the nested ``message`` shape)."""
+    if not isinstance(record, dict):
+        return []
+    msg = record.get("message") if isinstance(record.get("message"), dict) else record
+    content = msg.get("content") if isinstance(msg, dict) else None
+    if isinstance(content, list):
+        return [b for b in content if isinstance(b, dict)]
+    return []
+
+
+def _result_text(block: dict) -> str:
+    """Flatten a tool_result's content (string or list-of-{text}) to plain text."""
+    c = block.get("content")
+    if isinstance(c, str):
+        return c
+    if isinstance(c, list):
+        parts = [item["text"] for item in c if isinstance(item, dict) and isinstance(item.get("text"), str)]
+        return "\n".join(parts)
+    return ""
+
+
+def extract_facts(records: list[dict], observed_at: str) -> list[dict]:
+    """Mine deterministic fact candidates from parsed transcript ``records`` (in order).
+
+    Returns at most :data:`MAX_FACTS_PER_RUN` ``make_fact`` dicts. Pure: no I/O, no mutation of
+    inputs. Secret-touching commands are skipped wholesale; all stored text is redacted.
+    """
+    # Pass 1: map Bash tool_use id → command.
+    uses: dict[str, str] = {}
+    for rec in records:
+        for b in _content_blocks(rec):
+            if b.get("type") == "tool_use" and b.get("name") == "Bash":
+                tid = b.get("id")
+                inp = b.get("input") if isinstance(b.get("input"), dict) else {}
+                cmd = inp.get("command")
+                if tid and isinstance(cmd, str) and cmd.strip():
+                    uses[tid] = cmd
+
+    # Pass 2: walk results in order — failures first feed the red→green check for later successes.
+    facts: list[dict] = []
+    failed_keys: set[str] = set()
+    emitted: set[str] = set()
+
+    for rec in records:
+        for b in _content_blocks(rec):
+            if b.get("type") != "tool_result":
+                continue
+            cmd = uses.get(b.get("tool_use_id"))
+            if not cmd or touches_secret(cmd):
+                continue  # unknown tool, or a secret-touching command we refuse to record
+
+            red = redact(cmd)
+            head = command_head(red)
+            key = normalize_key(head)
+            if not key:
+                continue
+            fp = command_fp(red)  # full-command dedup identity (the display key stays the 80-char head)
+
+            if bool(b.get("is_error")):
+                if _is_noise_failure(cmd):
+                    continue
+                failed_keys.add(fp)
+                if fp in emitted:
+                    continue  # one failure candidate per distinct command per session
+                emitted.add(fp)
+                errline = redact(first_error_line(_result_text(b)))
+                summary = (f"`{head}` failed: {errline}" if errline else f"`{head}` failed")[:_SUMMARY_LEN]
+                facts.append(make_fact("failure-mode", key, summary, observed_at, source="auto", fp=fp))
+            else:
+                # Success → only a fact if a build/test command recovered from an earlier failure.
+                ok_key = "ok:" + fp
+                if _BUILD_TEST.search(cmd) and fp in failed_keys and ok_key not in emitted:
+                    emitted.add(ok_key)
+                    summary = (f"`{head}` passes now — was failing earlier this session")[:_SUMMARY_LEN]
+                    facts.append(make_fact("workflow-success", key, summary, observed_at, source="auto", fp=fp))
+
+            if len(facts) >= MAX_FACTS_PER_RUN:
+                return facts
+
+    return facts