scar-cli 0.1.1__py3-none-any.whl

scar/cli.py

@@ -0,0 +1,224 @@
+"""scar — the CLI. Thin argparse layer; all logic lives in the library.
+
+Adding a command = one _cmd_* function + one subparser block. Commands that
+read scars resolve the store once via _require_store; commands return exit
+codes (0 ok, 1 user-visible failure) and never raise to the shell.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .lint import lint_text
+from .match import rank_for_edit
+from .model import ParseError, parse_scar_text
+from .store import ScarStore, init_scars
+
+MAX_BODY_CHARS = 700  # ~120 words — the fatigue budget is a format guarantee
+
+
+def _require_store(start: Path | None = None) -> ScarStore | None:
+    store = ScarStore.discover(start or Path.cwd())
+    if store is None:
+        print("no .scars/ directory found (walked up to repo root). Run: scar init")
+    return store
+
+
+def _cmd_init(_args) -> int:
+    scars = init_scars(Path.cwd())
+    print(f"initialized {scars} (README.md, template.md, candidates/)")
+    print("convention: new scars -> candidates/, humans promote via `scar promote`")
+    return 0
+
+
+def _cmd_lint(_args) -> int:
+    store = _require_store()
+    if store is None:
+        return 1
+    failed = 0
+    files = store._scar_files() + store.candidates()
+    for f in files:
+        findings = lint_text(f.read_text(encoding="utf-8"))
+        for finding in findings:
+            print(f"{f.relative_to(store.root)}: {finding}")
+        if any(fi.level == "error" for fi in findings):
+            failed += 1
+    print(f"lint: {len(files)} file(s), {failed} with errors")
+    return 1 if failed else 0
+
+
+def _cmd_status(_args) -> int:
+    store = _require_store()
+    if store is None:
+        return 1
+    active, broken, cands = store.active(), store.broken(), store.candidates()
+    print(f"{store.scars_dir}: {len(active)} active, {len(cands)} candidate(s) pending review")
+    for f, s in active:
+        print(f"  [{s.type} #{s.id} | {s.severity}] {s.title}")
+    for c in cands:
+        print(f"  candidate: {c.name}")
+    if broken:
+        print(f"  WARNING: {len(broken)} unparseable (can NEVER fire): "
+              + ", ".join(b.name for b in broken))
+    return 0
+
+
+def _cmd_promote(args) -> int:
+    store = _require_store()
+    if store is None:
+        return 1
+    matches = [c for c in store.candidates() if args.candidate in c.name]
+    if len(matches) != 1:
+        opts = ", ".join(c.name for c in store.candidates()) or "(none)"
+        print(f"need exactly one candidate matching '{args.candidate}'; have: {opts}")
+        return 1
+    try:
+        new_path = store.promote(matches[0], reviewer=args.reviewer)
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    print(f"promoted -> {new_path.relative_to(store.root)}")
+    return 0
+
+
+def _cmd_check(args) -> int:
+    store = _require_store(Path(args.path).resolve())
+    if store is None:
+        return 1
+    hits = rank_for_edit(store, Path(args.path).resolve(), args.content or "",
+                         top_k=args.top_k)
+    if not hits:
+        print(f"no scars anchored to {args.path}")
+        return 0
+    for s in hits:
+        print(f"[{s.type} #{s.id} | severity: {s.severity} | confidence: {s.confidence}] {s.title}")
+        print("  " + s.body[:200].replace("\n", "\n  "))
+    return 0
+
+
+def _cmd_why(args) -> int:
+    """History of pain for a path: every scar that anchors it, any status."""
+    store = _require_store(Path(args.path).resolve())
+    if store is None:
+        return 1
+    rel = str(Path(args.path).resolve().relative_to(store.root))
+    found = 0
+    for f in store._scar_files():
+        try:
+            s = parse_scar_text(f.read_text(encoding="utf-8"))
+        except ParseError:
+            continue
+        # bidirectional: query under an anchor (editing inside protected dir)
+        # OR anchor under the query (asking a parent dir for its history)
+        if any(rel.startswith(p.rstrip("/")) or p.rstrip("/").startswith(rel)
+               for p in s.path_anchors):
+            found += 1
+            print(f"[{s.status} {s.type} #{s.id}] {s.title}  ({f.name})")
+            print("  " + s.body[:300].replace("\n", "\n  ") + "\n")
+    if not found:
+        print(f"no recorded pain for {rel}")
+    return 0
+
+
+def _cmd_inject(args) -> int:
+    """Machine mode for hooks: JSON additionalContext or silence."""
+    store = ScarStore.discover(Path(args.path).resolve())
+    if store is None:
+        return 0  # hooks must never fail the edit
+    hits = rank_for_edit(store, Path(args.path).resolve(), args.content or "",
+                         top_k=args.top_k)
+    broken = store.broken()
+    parts = []
+    if hits:
+        blocks = [
+            f"[{s.type} #{s.id} | severity: {s.severity} | confidence: {s.confidence}] "
+            f"{s.title}\n{s.body[:MAX_BODY_CHARS]}" for s in hits
+        ]
+        parts.append(
+            "SCAR pre-edit check — negative knowledge anchored to code you are "
+            f"about to modify ({len(hits)} match(es)). Honor these unless the "
+            "user explicitly overrides; full records in .scars/.\n\n"
+            + "\n\n".join(blocks))
+    if broken:
+        parts.append(
+            f"SCAR warning: {len(broken)} scar file(s) unparseable and can NEVER "
+            f"fire: {', '.join(b.name for b in broken)}. Fix frontmatter "
+            f"(copy {store.scars_dir}/template.md).")
+    if parts:
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": args.hook_event, "additionalContext": "\n\n".join(parts)}}))
+    return 0
+
+
+def _cmd_harvest(args) -> int:
+    from .harvest import harvest  # subprocess-heavy; import only when used
+    result = harvest(Path(args.repo).resolve())
+    total = sum(len(v) for v in result.values())
+    print(f"# Harvest candidates — {Path(args.repo).resolve().name} "
+          f"({total} raw; curation required, expect ~13% precision)\n")
+    sections = [("reverts", "Revert-shaped commits (deadend candidates)",
+                 lambda c: f"- `{c['commit']}` {c['date']} — {c['subject']}"),
+                ("deleted_components", "Components tried then deleted (deadend candidates)",
+                 lambda c: f"- **{c['component']}** died {c['died']} (`{c['death_commit']}` {c['death_subject']})"),
+                ("flapping", "Flapping values A->B->A (fence candidates)",
+                 lambda c: f"- `{c['file']}` **{c['key']}**: {c['sequence']}"),
+                ("comments", "Comment archaeology (fence candidates)",
+                 lambda c: f"- `{c['location']}` — {c['text']}")]
+    for key, title, fmt in sections:
+        print(f"## {title} ({len(result[key])})")
+        for c in result[key]:
+            print(fmt(c))
+        print()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="scar",
+                                     description="version control for negative knowledge")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("init", help="create .scars/ layout in the current repo")
+    sub.add_parser("lint", help="validate every scar and candidate")
+    sub.add_parser("status", help="counts, titles, broken-file warnings")
+
+    p = sub.add_parser("promote", help="review a candidate into an active scar")
+    p.add_argument("candidate", help="candidate filename (or unique substring)")
+    p.add_argument("--reviewer", default="", help="human reviewer to add to authors")
+
+    p = sub.add_parser("check", help="scars anchored to a path")
+    p.add_argument("path")
+    p.add_argument("--content", default="", help="new code to test pattern anchors against")
+    p.add_argument("--top-k", type=int, default=10)
+
+    p = sub.add_parser("why", help="history of pain for a path (any status)")
+    p.add_argument("path")
+
+    p = sub.add_parser("harvest", help="mine git history for candidate scars")
+    p.add_argument("repo", nargs="?", default=".")
+
+    p = sub.add_parser("hook", help="Claude Code hook handlers (payload on stdin)")
+    p.add_argument("kind", choices=["precheck", "session-notice", "stop-drafter"])
+
+    p = sub.add_parser("inject", help="machine mode for hooks: JSON or silence")
+    p.add_argument("--path", required=True)
+    p.add_argument("--content", default="")
+    p.add_argument("--top-k", type=int, default=3)
+    p.add_argument("--hook-event", default="PreToolUse")
+
+    args = parser.parse_args(argv)
+    if args.command == "hook":
+        from .hooks import HANDLERS  # hot path: imports nothing beyond library
+        return HANDLERS[args.kind]()
+    handler = {
+        "init": _cmd_init, "lint": _cmd_lint, "status": _cmd_status,
+        "promote": _cmd_promote, "check": _cmd_check, "why": _cmd_why,
+        "inject": _cmd_inject, "harvest": _cmd_harvest,
+    }[args.command]
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scar/harvest.py

@@ -0,0 +1,111 @@
+"""Harvest: mine git history for negative-knowledge candidates.
+
+Port of the gate-0.1 prototype (experiments/harvest/), returning structured
+data instead of printing. Six heuristics; each returns CANDIDATES that a
+human curates — raw precision measured at ~13% on real history, so the CLI
+layer must always present these as "needs confirmation", never as scars.
+
+NB (scar 0001): no \\b in git grep patterns, no speculative extension globs.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+
+REVERT_RE = re.compile(
+    r"revert|rollback|roll back|downgrade|back to|undo|set back|"
+    r"retire|disable again", re.IGNORECASE)
+TRACKED_KEYS = ("image", "replicas", "tag", "version", "cpu", "memory")
+COMMENT_RE = (r"DO NOT|DON'T|do not (remove|change|touch)|HACK|XXX|"
+              r"load.?bearing|intentional|must (stay|remain)|workaround")
+
+
+def _git(repo: Path, *args: str) -> str:
+    return subprocess.run(["git", "-C", str(repo), *args],
+                          capture_output=True, text=True).stdout
+
+
+def _commits(repo: Path):
+    out = _git(repo, "log", "--format=%H\x01%ad\x01%s", "--date=short")
+    for line in out.splitlines():
+        h, date, subj = line.split("\x01", 2)
+        yield h, date, subj
+
+
+def _reverts(repo: Path) -> list[dict]:
+    return [{"commit": h[:8], "date": d, "subject": s}
+            for h, d, s in _commits(repo) if REVERT_RE.search(s)]
+
+
+def _deleted_components(repo: Path) -> list[dict]:
+    out = _git(repo, "log", "--diff-filter=D", "--name-only",
+               "--format=\x02%h\x01%ad\x01%s", "--date=short")
+    comp_del: dict[str, list] = defaultdict(list)
+    commit: list[str] = []
+    for line in out.splitlines():
+        if line.startswith("\x02"):
+            commit = line[1:].split("\x01")
+        elif line and "/" in line:
+            comp_del["/".join(line.split("/")[:2])].append(commit)
+    results = []
+    for comp, dels in comp_del.items():
+        if (repo / comp).exists():
+            continue
+        last = dels[0]
+        results.append({"component": comp, "died": last[1],
+                        "death_commit": last[0], "death_subject": last[2],
+                        "files_deleted": len(dels)})
+    return sorted(results, key=lambda r: r["died"], reverse=True)
+
+
+def _flapping(repo: Path) -> list[dict]:
+    key_re = re.compile(r"^[+-]\s*(" + "|".join(TRACKED_KEYS) + r"):\s*(.+)$")
+    out = _git(repo, "log", "-p", "--reverse", "--format=\x02%h\x01%ad\x01%s",
+               "--date=short")
+    history: dict[tuple, list] = defaultdict(list)
+    commit: list[str] = []
+    fname = ""
+    for line in out.splitlines():
+        if line.startswith("\x02"):
+            commit = line[1:].split("\x01")
+        elif line.startswith("+++ b/"):
+            fname = line[6:]
+        elif line.startswith("+") and fname:
+            m = key_re.match(line)
+            if m:
+                history[(fname, m.group(1))].append(
+                    (m.group(2).strip(), commit[0], commit[1]))
+    flaps = []
+    for (fname, key), seq in history.items():
+        values = [v for v, _, _ in seq]
+        for i in range(len(values) - 2):
+            if values[i] == values[i + 2] and values[i] != values[i + 1]:
+                flaps.append({"file": fname, "key": key,
+                              "sequence": f"{values[i]} -> {values[i+1]} -> {values[i+2]}",
+                              "commits": [seq[i][1], seq[i+1][1], seq[i+2][1]]})
+                break
+    return flaps
+
+
+def _comment_archaeology(repo: Path) -> list[dict]:
+    out = _git(repo, "grep", "-nIE", COMMENT_RE)  # -I skips binaries; no \b (scar 0001)
+    hits = []
+    for line in out.splitlines():
+        parts = line.split(":", 2)
+        if len(parts) == 3:
+            hits.append({"location": f"{parts[0]}:{parts[1]}",
+                         "text": parts[2].strip()[:120]})
+    return hits
+
+
+def harvest(repo: Path) -> dict[str, list[dict]]:
+    repo = Path(repo)
+    return {
+        "reverts": _reverts(repo),
+        "deleted_components": _deleted_components(repo),
+        "flapping": _flapping(repo),
+        "comments": _comment_archaeology(repo),
+    }

scar/hooks.py

@@ -0,0 +1,206 @@
+"""Claude Code hook handlers — harness payload on stdin, hook JSON on stdout.
+
+One library code path replaces three standalone scripts (which drifted within
+two days of birth — gate 0.4 findings). Contract per handler: silent no-op on
+any problem; a hook must NEVER fail or delay the user's action.
+
+State (drafter markers, firing log) lives in ~/.claude/scar-state/, overridable
+via SCAR_STATE_DIR for tests.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+from .match import rank_for_edit
+from .store import ScarStore
+
+MAX_BODY_CHARS = 700
+
+REVERT_RE = re.compile(
+    r"revert(ing|ed)?\b|roll(ing|ed)? back|undo(ing)? (the|that|my)|"
+    r"abandon(ing|ed)? (the|this|that|this approach)|scrap(ping)? (the|this|that)|"
+    r"back to the (original|previous)", re.IGNORECASE)
+USER_NEG_RE = re.compile(
+    r"didn'?t work|doesn'?t work|still (broken|failing|not working)|"
+    r"that broke|go back|revert|undo that|no funciona|sigue (roto|fallando)|"
+    r"volv[ée] al?", re.IGNORECASE)
+
+
+def _state_dir() -> Path:
+    return Path(os.environ.get("SCAR_STATE_DIR",
+                               str(Path.home() / ".claude" / "scar-state")))
+
+
+def _read_payload() -> dict | None:
+    """Hook payload from stdin; None means 'tty — hint printed, do nothing'."""
+    if sys.stdin.isatty():
+        # interactive invocation: never hang waiting for a payload that
+        # only a hook harness would pipe in, and never mix the human hint
+        # with machine JSON (both found live)
+        print("scar hook expects a hook payload on stdin (it is run by the "
+              "agent harness, not by hand). Try: echo '{}' | scar hook <kind>")
+        return None
+    try:
+        return json.load(sys.stdin)
+    except (json.JSONDecodeError, OSError, ValueError):
+        return {}
+
+
+def _emit(event: str, context: str) -> None:
+    print(json.dumps({"hookSpecificOutput": {
+        "hookEventName": event, "additionalContext": context}}))
+
+
+def precheck() -> int:
+    payload = _read_payload()
+    if payload is None:
+        return 0
+    tool_input = payload.get("tool_input", {})
+    target = tool_input.get("file_path") or tool_input.get("notebook_path")
+    if not target:
+        return 0
+    store = ScarStore.discover(Path(target))
+    if store is None:
+        return 0
+    new_content = " ".join(str(tool_input.get(k, ""))
+                           for k in ("content", "new_string", "new_source"))
+    hits = rank_for_edit(store, Path(target), new_content)
+    broken = store.broken()
+    parts = []
+    if hits:
+        blocks = [f"[{s.type} #{s.id} | severity: {s.severity} | confidence: "
+                  f"{s.confidence}] {s.title}\n{s.body[:MAX_BODY_CHARS]}" for s in hits]
+        parts.append(
+            "SCAR pre-edit check — negative knowledge anchored to code you are "
+            f"about to modify ({len(hits)} match(es)). Honor these unless the "
+            "user explicitly overrides; full records in .scars/.\n\n" + "\n\n".join(blocks))
+    if broken:
+        parts.append(
+            f"SCAR warning: {len(broken)} scar file(s) unparseable and can NEVER "
+            f"fire: {', '.join(b.name for b in broken)}. Their knowledge is "
+            f"silently dead. Fix the frontmatter (copy {store.scars_dir}/template.md).")
+    if parts:
+        _emit("PreToolUse", "\n\n".join(parts))
+    return 0
+
+
+def session_notice() -> int:
+    payload = _read_payload()
+    if payload is None:
+        return 0
+    cwd = Path(payload.get("cwd") or os.getcwd())
+    store = ScarStore.discover(cwd)
+    if store is None:
+        return 0
+    active, broken, cands = store.active(), store.broken(), store.candidates()
+    state = (f"{len(active)} active scar(s)" if active
+             else "0 scars yet — the convention is live, be the first to record one")
+    pending = f", {len(cands)} candidate(s) pending review" if cands else ""
+    warn = (f" WARNING: {len(broken)} unparseable scar file(s) that can never "
+            f"fire: {', '.join(b.name for b in broken)} — fix their frontmatter."
+            if broken else "")
+    _emit("SessionStart", (
+        f"SCAR: this repository records negative knowledge in {store.scars_dir} "
+        f"({state}{pending}).{warn} Relevant scars are injected automatically "
+        "before you edit anchored code — honor them unless the user overrides. "
+        "Reciprocal duty: when you abandon an approach (deadend), keep "
+        "intentional-looking weirdness (fence), or discover non-obvious coupling "
+        f"(landmine), record it. Contract: COPY {store.scars_dir}/template.md "
+        "(YAML frontmatter is mandatory — scars without it never fire), write to "
+        f"{store.scars_dir}/candidates/<slug>.md with status: candidate, and "
+        "never write directly into .scars/ — only a human reviewer promotes."))
+    return 0
+
+
+def _analyze_transcript(path: str) -> dict | None:
+    revert_hits = user_neg = errors = 0
+    edits_per_file: dict[str, int] = {}
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.readlines()[-4000:]
+    except OSError:
+        return None
+    for raw in lines:
+        try:
+            entry = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        etype = entry.get("type", "")
+        content = (entry.get("message") or {}).get("content")
+        blocks = ([{"type": "text", "text": content}] if isinstance(content, str)
+                  else content if isinstance(content, list) else [])
+        for b in blocks:
+            if not isinstance(b, dict):
+                continue
+            if b.get("type") == "text":
+                if etype == "assistant" and REVERT_RE.search(b.get("text", "")):
+                    revert_hits += 1
+                if etype == "user" and USER_NEG_RE.search(b.get("text", "")):
+                    user_neg += 1
+            elif b.get("type") == "tool_use" and b.get("name") in ("Edit", "Write", "MultiEdit"):
+                fp = (b.get("input") or {}).get("file_path", "")
+                if fp:
+                    edits_per_file[fp] = edits_per_file.get(fp, 0) + 1
+            elif b.get("type") == "tool_result" and b.get("is_error"):
+                errors += 1
+    thrash = max(edits_per_file.values(), default=0)
+    signals = {"revert_language": revert_hits, "user_corrections": user_neg,
+               "tool_errors": errors, "max_edits_one_file": thrash}
+    # Trigger on assistant revert/abandon language only. Field data (gate 0.4,
+    # 6 firings): revert_language >= 1 was present in both true positives and
+    # absent in all four false positives; the user_corrections and
+    # tool_errors+thrash paths went 0/4 (normal debugging, policy denials).
+    # The other signals stay in the log so future FN evidence can re-add a path.
+    triggered = revert_hits >= 1
+    return signals if triggered else None
+
+
+def stop_drafter() -> int:
+    payload = _read_payload()
+    if payload is None or payload.get("stop_hook_active"):
+        return 0
+    session = payload.get("session_id", "unknown")
+    state = _state_dir()
+    marker = state / f"drafted-{session}"
+    if marker.exists():
+        return 0
+    store = ScarStore.discover(Path(payload.get("cwd") or os.getcwd()))
+    if store is None:
+        return 0
+    transcript = payload.get("transcript_path")
+    if not transcript:
+        return 0
+    signals = _analyze_transcript(transcript)
+    if not signals:
+        return 0
+
+    state.mkdir(parents=True, exist_ok=True)
+    marker.touch()
+    with open(state / "drafter-log.jsonl", "a", encoding="utf-8") as fh:
+        fh.write(json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                             "repo": str(store.root), "session": session,
+                             "signals": signals}) + "\n")
+    candidates = store.scars_dir / "candidates"
+    print(json.dumps({"decision": "block", "reason": (
+        "SCAR auto-authorship check: this session shows abandonment signals "
+        f"({', '.join(f'{k}={v}' for k, v in signals.items() if v)}). "
+        "Before finishing: review the session. "
+        f"(1) If an approach was genuinely tried and abandoned, write a short "
+        f"candidate scar (<=15 lines) to {candidates}/<slug>.md — COPY the "
+        f"format from {store.scars_dir}/template.md (YAML frontmatter "
+        "mandatory, status: candidate); it stays a candidate until a human "
+        "reviews it. (2) If nothing was actually abandoned (false trigger), "
+        f"append one line — date + one-phrase reason — to "
+        f"{candidates}/fp-log.txt. Then finish normally. Do exactly one of "
+        "the two; do not ask the user.")}))
+    return 0
+
+
+HANDLERS = {"precheck": precheck, "session-notice": session_notice,
+            "stop-drafter": stop_drafter}

scar/lint.py

@@ -0,0 +1,49 @@
+"""Lint rules. Each rule exists because the failure already happened once:
+no-frontmatter = daimon 0004 (born unable to fire); the rest harden the
+contract in .scars/README.md.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .model import SEVERITIES, STATUSES, TYPES, ParseError, parse_scar_text
+
+
+@dataclass
+class Finding:
+    level: str  # "error" | "warning"
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.level}: {self.message}"
+
+
+def lint_text(text: str) -> list[Finding]:
+    try:
+        scar = parse_scar_text(text)
+    except ParseError:
+        return [Finding("error", "missing YAML frontmatter — this scar can NEVER fire")]
+
+    findings = []
+    if scar.type not in TYPES:
+        findings.append(Finding("error", f"unknown type '{scar.type}' (expected one of {', '.join(TYPES)})"))
+    if not scar.title:
+        findings.append(Finding("error", "missing title"))
+    if scar.severity not in SEVERITIES:
+        findings.append(Finding("error", f"invalid severity '{scar.severity}'"))
+    if scar.status not in STATUSES:
+        findings.append(Finding("error", f"invalid status '{scar.status}'"))
+    if not scar.path_anchors and not scar.pattern_anchors:
+        findings.append(Finding("error", "no anchors — scar protects nothing"))
+    for pat in scar.pattern_anchors:
+        try:
+            re.compile(pat)
+        except re.error as exc:
+            findings.append(Finding("error", f"invalid pattern anchor /{pat}/: {exc}"))
+    if not scar.evidence:
+        findings.append(Finding("warning", "no evidence links — challengeable on sight"))
+    if not scar.body:
+        findings.append(Finding("warning", "empty body — future readers get no why"))
+    return findings

scar/match.py

@@ -0,0 +1,51 @@
+"""Anchor matching and injection ranking.
+
+Scoring: anchor_strength x severity_weight x confidence.
+Anchor strengths — content-pattern hit (2.5, a dead end re-appearing in new
+code is the strongest signal) > path prefix (2.0) > pattern on the path (1.5).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .model import Scar
+from .store import ScarStore
+
+SEVERITY_WEIGHT = {"low": 1, "medium": 2, "high": 3, "critical": 4}
+DEFAULT_TOP_K = 3
+
+
+def _anchor_strength(scar: Scar, rel_path: str, new_content: str) -> float:
+    score = 0.0
+    for p in scar.path_anchors:
+        if rel_path.startswith(p.rstrip("/")):
+            score = max(score, 2.0)
+    for pat in scar.pattern_anchors:
+        try:
+            rx = re.compile(pat, re.IGNORECASE)
+        except re.error:
+            continue  # lint's job; never crash the read path
+        if rx.search(rel_path):
+            score = max(score, 1.5)
+        if new_content and rx.search(new_content):
+            score = max(score, 2.5)
+    return score
+
+
+def rank_for_edit(store: ScarStore, target: Path, new_content: str,
+                  top_k: int = DEFAULT_TOP_K) -> list[Scar]:
+    """Top-k active scars relevant to editing `target` with `new_content`."""
+    try:
+        rel_path = str(Path(target).resolve().relative_to(store.root))
+    except ValueError:
+        return []
+    ranked = []
+    for _, scar in store.active():
+        strength = _anchor_strength(scar, rel_path, new_content)
+        if strength > 0:
+            rank = strength * SEVERITY_WEIGHT.get(scar.severity, 2) * scar.confidence
+            ranked.append((rank, scar))
+    ranked.sort(key=lambda t: -t[0])
+    return [s for _, s in ranked[:top_k]]

scar/model.py

@@ -0,0 +1,112 @@
+"""The scar model — the ONE parser/serializer for the whole system.
+
+Frontmatter is a constrained YAML subset parsed line-wise on purpose: zero
+dependencies keeps hook startup ~20ms, and the format is ours to constrain.
+Anything this module can't parse, no SCAR tool fires on — so every consumer
+must go through here (hooks included, eventually) to prevent parser drift.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+TYPES = ("deadend", "fence", "landmine")
+SEVERITIES = ("low", "medium", "high", "critical")
+STATUSES = ("candidate", "active", "challenged", "archived", "orphaned", "template")
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n?(.*)$", re.DOTALL)
+
+
+class ParseError(ValueError):
+    """Text is not a scar (no/malformed frontmatter)."""
+
+
+@dataclass
+class Scar:
+    type: str = "deadend"
+    title: str = ""
+    id: int | None = None
+    severity: str = "medium"
+    confidence: float = 0.5
+    created: str = ""
+    authors: list[str] = field(default_factory=list)
+    path_anchors: list[str] = field(default_factory=list)
+    pattern_anchors: list[str] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)
+    expires_condition: str = ""
+    review_after: str = ""
+    status: str = "active"
+    body: str = ""
+
+    def to_text(self) -> str:
+        lines = ["---"]
+        if self.id is not None:
+            lines.append(f"id: {self.id}")
+        lines += [f"type: {self.type}", f"title: {self.title}",
+                  f"severity: {self.severity}", f"confidence: {self.confidence}"]
+        if self.created:
+            lines.append(f"created: {self.created}")
+        if self.authors:
+            lines.append("authors: [" + ", ".join(f'"{a}"' for a in self.authors) + "]")
+        lines.append("anchors:")
+        lines += [f"  - path: {p}" for p in self.path_anchors]
+        lines += [f'  - pattern: "{p}"' for p in self.pattern_anchors]
+        if self.evidence:
+            lines.append("evidence:")
+            lines += [f"  - {e}" for e in self.evidence]
+        if self.expires_condition or self.review_after:
+            lines.append("expires:")
+            if self.expires_condition:
+                lines.append(f'  condition: "{self.expires_condition}"')
+            if self.review_after:
+                lines.append(f"  review_after: {self.review_after}")
+        lines += [f"status: {self.status}", "---", "", self.body.strip(), ""]
+        return "\n".join(lines)
+
+
+def _field(front: str, name: str, default: str = "") -> str:
+    m = re.search(rf"^\s*{name}:\s*(.+?)\s*$", front, re.MULTILINE)
+    return m.group(1) if m else default
+
+
+def parse_scar_text(text: str) -> Scar:
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        raise ParseError("no YAML frontmatter (--- block) — scar can never fire")
+    front, body = m.groups()
+
+    try:
+        confidence = float(_field(front, "confidence", "0.5"))
+    except ValueError:
+        confidence = 0.5
+    raw_id = _field(front, "id")
+    try:
+        scar_id: int | None = int(raw_id) if raw_id else None
+    except ValueError:
+        scar_id = None
+
+    authors_raw = _field(front, "authors")
+    authors = [a.strip().strip('"').strip("'")
+               for a in authors_raw.strip("[]").split(",") if a.strip()] if authors_raw else []
+
+    evidence = [f"{m1.group(1)}: {m1.group(2).strip().strip('\"')}" for m1 in re.finditer(
+        r"^\s*-\s*(commit|pr|incident|note):\s*(.+)\s*$", front, re.MULTILINE)]
+
+    return Scar(
+        type=_field(front, "type", "deadend"),
+        title=_field(front, "title"),
+        id=scar_id,
+        severity=_field(front, "severity", "medium"),
+        confidence=confidence,
+        created=_field(front, "created"),
+        authors=authors,
+        path_anchors=re.findall(r"^\s*-\s*path:\s*(\S+)\s*$", front, re.MULTILINE),
+        pattern_anchors=[p.strip().strip('"')
+                         for p in re.findall(r"^\s*-\s*pattern:\s*(.+?)\s*$", front, re.MULTILINE)],
+        evidence=evidence,
+        expires_condition=_field(front, "condition").strip('"'),
+        review_after=_field(front, "review_after"),
+        status=_field(front, "status", "active"),
+        body=body.strip(),
+    )

scar/store.py

@@ -0,0 +1,156 @@
+"""ScarStore — filesystem layer: discovery, listing, init, promotion.
+
+All path conventions live here and nowhere else. README/template content is
+embedded so `scar init` works from a bare install with no data files.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .lint import lint_text
+from .model import ParseError, Scar, parse_scar_text
+
+SKIP_NAMES = {"readme.md", "template.md"}
+
+README = """\
+# .scars/ — Negative knowledge for this repo
+
+This directory records what this codebase **refused to be**: approaches that
+were tried and failed (`deadend`), configuration that looks wrong but is
+intentional (`fence`), and changes that break non-obvious things elsewhere
+(`landmine`).
+
+Before "cleaning up" anything these files anchor to — read the scar first.
+Every scar carries evidence (commits, PRs, incidents). If a scar is stale,
+challenge it: update or archive it with a note, don't ignore it.
+
+## The contract (humans and agents)
+
+1. **New scars start as candidates.** Copy `template.md`, write to
+   `candidates/<slug>.md` with `status: candidate`. Never write directly
+   into `.scars/` — only a human reviewer promotes (`scar promote`).
+2. **YAML frontmatter is mandatory.** A scar without it is unparseable and
+   will NEVER fire in any tool. `scar lint` checks; the hooks warn loudly.
+3. **Promotion** = human review: `scar promote candidates/<slug>.md`.
+4. **Evidence required.** A scar without a commit/PR/incident reference is
+   an opinion and can be challenged on sight.
+
+Format details: `template.md`. Project: SCAR.
+"""
+
+TEMPLATE = """\
+---
+# COPY THIS FILE — do not edit the template itself.
+# New scars: write to .scars/candidates/<slug>.md with status: candidate.
+# A human reviewer promotes via `scar promote` (assigns id + renames).
+id: 0                      # assigned at promotion
+type: deadend              # deadend = tried+failed | fence = looks wrong, intentional | landmine = touching A breaks B
+title: One line, searchable, says the constraint
+severity: medium           # low | medium | high | critical
+confidence: 0.7            # 0..1 — how sure are we this still holds
+created: 1970-01-01
+authors: ["claude-code"]   # reviewer added at promotion
+anchors:
+  - path: src/module/      # file or directory this protects
+  - pattern: "regex"       # optional: fires when matching code appears in ANY new/edited file
+evidence:
+  - commit: abc1234        # at least one receipt: commit, pr, incident, or note
+expires:
+  condition: "what change would make this scar obsolete"
+  review_after: 1971-01-01
+status: template           # candidate | active | challenged | archived  (template = never parsed)
+---
+
+Body: 5-15 lines of prose. What was tried/observed, why it failed or why the
+weirdness is intentional, and what a future editor must do instead. Write it
+for someone (human or agent) with zero context. Cite the evidence inline.
+"""
+
+
+def init_scars(repo_root: Path) -> Path:
+    """Create .scars/ layout. Idempotent; never clobbers existing files."""
+    scars = Path(repo_root) / ".scars"
+    scars.mkdir(exist_ok=True)
+    (scars / "candidates").mkdir(exist_ok=True)
+    for name, content in (("README.md", README), ("template.md", TEMPLATE)):
+        f = scars / name
+        if not f.exists():
+            f.write_text(content, encoding="utf-8")
+    return scars
+
+
+@dataclass
+class ScarStore:
+    root: Path        # repo root
+    scars_dir: Path   # root/.scars
+
+    @classmethod
+    def discover(cls, start: Path) -> "ScarStore | None":
+        cur = Path(start).resolve()
+        cur = cur if cur.is_dir() else cur.parent
+        for d in [cur, *cur.parents]:
+            if (d / ".scars").is_dir():
+                return cls(root=d, scars_dir=d / ".scars")
+            if (d / ".git").exists():
+                return None
+        return None
+
+    def _scar_files(self):
+        return [f for f in sorted(self.scars_dir.glob("*.md"))
+                if f.name.lower() not in SKIP_NAMES and not f.name.startswith("_")]
+
+    def active(self) -> list[tuple[Path, Scar]]:
+        out = []
+        for f in self._scar_files():
+            try:
+                scar = parse_scar_text(f.read_text(encoding="utf-8"))
+            except (ParseError, OSError):
+                continue
+            if scar.status == "active":
+                out.append((f, scar))
+        return out
+
+    def broken(self) -> list[Path]:
+        out = []
+        for f in self._scar_files():
+            try:
+                parse_scar_text(f.read_text(encoding="utf-8"))
+            except ParseError:
+                out.append(f)
+            except OSError:
+                pass
+        return out
+
+    def candidates(self) -> list[Path]:
+        cand = self.scars_dir / "candidates"
+        return sorted(p for p in cand.glob("*.md")) if cand.is_dir() else []
+
+    def next_id(self) -> int:
+        ids = [scar.id for _, scar in self.active() if scar.id is not None]
+        for f in self._scar_files():  # count non-active numbered scars too
+            try:
+                s = parse_scar_text(f.read_text(encoding="utf-8"))
+                if s.id is not None:
+                    ids.append(s.id)
+            except (ParseError, OSError):
+                continue
+        return max(ids, default=0) + 1
+
+    def promote(self, candidate: Path, reviewer: str) -> Path:
+        text = candidate.read_text(encoding="utf-8")
+        findings = lint_text(text)
+        errors = [f for f in findings if f.level == "error"]
+        if errors:
+            raise ValueError(f"refusing to promote, lint errors: {'; '.join(f.message for f in errors)}")
+        scar = parse_scar_text(text)
+        scar.id = self.next_id()
+        scar.status = "active"
+        if reviewer and reviewer not in scar.authors:
+            scar.authors.append(reviewer)
+        slug = candidate.stem
+        new_path = self.scars_dir / f"{scar.id:04d}-{slug}.{scar.type}.md"
+        new_path.write_text(scar.to_text(), encoding="utf-8")
+        candidate.unlink()
+        return new_path

scar_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: scar-cli
+Version: 0.1.1
+Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SCAR — Version Control for Negative Knowledge
+
+> Git records what your codebase **is**. Nothing records what it **refused to be**.
+
+SCAR is a git-native system for capturing, anchoring, and enforcing the *negative knowledge* of a codebase — the dead ends, the load-bearing weirdness, the invisible tripwires — and surfacing it at the exact moment someone (human or AI agent) is about to step on it.
+
+## The one-liner
+
+**Every codebase is a battlefield where the bodies have been removed.** SCAR puts the markers back.
+
+## The three primitives
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| `deadend` | We tried X. It failed because Y. Don't retry unless Z changes. | "We tried Redis for session storage in 2024-03. Eviction under memory pressure logged users out mid-checkout. Don't retry unless sessions become re-derivable." |
+| `fence` | This code looks wrong. It is intentional. Here's why. | "Yes, this retry loop sleeps 7 seconds, not 5. The upstream vendor's rate limiter has a 6-second window they don't document." |
+| `landmine` | Changing A breaks B in a way nothing in the code tells you. | "The CSV export in `reports/` depends on the column order of this SELECT. Reorder it and Finance's reconciliation pipeline silently corrupts." |
+
+## Why now
+
+AI agents write an increasing share of all code. Agents have **zero hallway memory**. They see a weird retry loop and "clean it up." They see a missing cache layer and re-add the library that was removed after a data-corruption incident. They retry, across thousands of sessions, the exact approaches that already failed — because the repository only records positive space.
+
+Humans at least had tribal knowledge. Agents have none. And as agents author more of the code, the negative knowledge stops even entering human memory — it evaporates entirely.
+
+The flip side: agents also solve the historically fatal flaw of every knowledge-capture system — **authorship cost**. Nobody writes documentation after a failure. But an agent that just tried an approach and abandoned it can write a `deadend` scar in milliseconds, for free, at the moment of maximum context.
+
+**Agents created the urgency. Agents remove the adoption barrier. That's the wedge.**
+
+## How it works
+
+```
+.scars/
+├── 0001-redis-sessions.deadend.md
+├── 0002-vendor-retry-window.fence.md
+└── 0003-csv-column-order.landmine.md
+```
+
+- Scars are small structured Markdown files with YAML frontmatter, tracked in git, reviewed in PRs like code.
+- Each scar is **anchored** to code via paths, symbol names, and content fingerprints — not line numbers — so anchors survive refactors.
+- Enforcement happens **at the moment of action**:
+  - `scar check <path>` — CLI gate for humans and CI
+  - Agent hook (Claude Code `PreToolUse`, etc.) — injects relevant scars into the agent's context *before* it edits the file
+  - MCP server — planned, so any agent can query the scar graph
+- `scar harvest` — mines git history (reverts, add-then-remove dependencies, reopened issues) to propose candidate scars for codebases starting from zero.
+- Scars are **advisory, never blocking, by default**. Stale knowledge is challenged via `scar challenge`, and every scar can carry expiry conditions ("valid until we drop Postgres 12").
+
+## Install
+
+```bash
+uv tool install scar-cli   # or: pipx install scar-cli
+```
+
+Zero runtime dependencies. Python ≥3.10.
+
+## Quickstart
+
+```bash
+cd your-repo
+scar init                  # creates .scars/ with template + README
+
+# write your first scar
+cp .scars/template.md .scars/candidates/redis-sessions.md
+$EDITOR .scars/candidates/redis-sessions.md
+
+scar lint                  # validate format
+scar promote redis-sessions.md   # human review gate: candidate -> active
+
+# from then on
+scar check src/auth/       # what's anchored here?
+scar why src/auth/         # full history of pain for this path
+scar harvest               # mine git history for candidate scars
+```
+
+Wiring the Claude Code hook (auto-injects scars before any agent edit):
+
+```bash
+scar hook install
+```
+
+## Quality discipline
+
+- **Candidates vs active:** agents and `scar harvest` only ever write to `.scars/candidates/`. A human promotes (`scar promote`) — nothing enters active enforcement without review.
+- **Expiry conditions:** every scar can declare when it stops being true ("valid until sessions are re-derivable"). Stale knowledge is a bug, not a feature.
+- **Validated in use:** in a 14-day agent auto-authorship trial, agents drafted 13 keepable scars across 3 repos with 0% false positives — including one that caught a real parser bug in this repo and fired on the exact edit that fixed it.
+
+## Read more
+
+- [IDEA.md](IDEA.md) — the full pitch: problem, solution, why this, why now, why me
+- [SPEC.md](SPEC.md) — scar format, anchoring model, CLI surface, agent integration
+- [STRESS-TEST.md](STRESS-TEST.md) — adversarial analysis: failure modes, loopholes, objections, premortem
+- [ROADMAP.md](ROADMAP.md) — phased plan from prototype to product
+
+## Status & expectations
+
+**Working software, shared as-is.** CLI v0 is shipped: 9 subcommands, 63 tests, zero dependencies, CI-enforced. It runs daily across the author's repos (where it has already caught real bugs — see `.scars/` in this very repo for live examples).
+
+This is personal infrastructure published as a gift to the OSS community, not a product. Issues and PRs are welcome and read with interest, but there is no support SLA and no roadmap promise. If it's useful to you, that's the whole point.
+
+## License
+
+MIT

scar_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+scar/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scar/cli.py,sha256=_bs_VK-8Z1Z4n9h0h5szzGtYCuOdpVv3qF04bpzE70U,8888
+scar/harvest.py,sha256=6eJJWYnAORKlAH6-ePX87u_fRI_pG7qynvRrB4z9uB4,4190
+scar/hooks.py,sha256=S3mNEjJR-IU9kCxSy2NPVFO7Em63FoPLftdq4J4BAnc,8833
+scar/lint.py,sha256=xHlnYpXGQogNHV2fUkPyCUOAcjIfUVxmzQk2-FYkuoQ,1768
+scar/match.py,sha256=AVtN2SisyrgNJ2CQYs2BI35uN1hsaqEKdUOuduaWGNU,1716
+scar/model.py,sha256=EAaeXd-wOaS7-rOCS-9Rlqg7yPgZVOAw94eUNj8hIFE,4224
+scar/store.py,sha256=PGXN651Jw3ZhWC6z39l3x50LU5aMUiPxQvh6iQbVoyg,6051
+scar_cli-0.1.1.dist-info/METADATA,sha256=B-VIpc2_Wn-MkE3Lyvs8owyzSTEyAtiUSMsjHktp-bk,5816
+scar_cli-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+scar_cli-0.1.1.dist-info/entry_points.txt,sha256=y2N95d5kCcCkVybbzuYdbfJeNBnj0btQFZ9tw3whpGw,39
+scar_cli-0.1.1.dist-info/licenses/LICENSE,sha256=0U9GZYTymBZdT5ErJalgsbW9msHCIqMdzgWWq687F8s,1063
+scar_cli-0.1.1.dist-info/RECORD,,

scar_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

scar_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scar = scar.cli:main

scar_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kibukx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.