scar-cli 0.1.1__tar.gz → 0.3.0__tar.gz

{scar_cli-0.1.1 → scar_cli-0.3.0}/.scars/0003-installer-binds-to-active-venv-scar.landmine.md

@@ -11,7 +11,8 @@ anchors:
   - pattern: "shutil\\.which\\([\"']scar[\"']\\)"
 evidence:
   - note: 2026-06-11 session: user ran `source .venv/bin/activate` then `python3 fabcap/hook/scar-hooks.py install` intending to rebind global hooks to ~/.local/bin/scar; installer reported 'up-to-date' and left all 3 hooks on fabcap/.venv/bin/scar
-status: active
+  - note: archived 2026-06-11: fix shipped in #8 with 4 installer tests guarding regression
+status: archived
 ---
 
 `install()` resolves the scar binary with `shutil.which("scar")` and writes that

{scar_cli-0.1.1 → scar_cli-0.3.0}/.scars/0004-promote-roundtrip-drops-expires-evidence.landmine.md

@@ -11,7 +11,8 @@ anchors:
   - pattern: "_field\(front"
 evidence:
   - note: Observed 2026-06-11 promoting 5 candidates in context-as-program (PR 3 there restores the data by hand). All 5 lost their expires block; one also lost evidence because its note contained escaped quotes.
-status: active
+  - note: archived 2026-06-11: expires.condition met by #10: parser reads nested keys and quote evidence, roundtrip test guards it
+status: archived
 ---
 
 promote() does parse -> mutate -> to_text. Two asymmetries make that lossy.

scar_cli-0.1.1/.scars/candidates/history-rewrite-orphans-commit-evidence.md → scar_cli-0.3.0/.scars/0005-history-rewrite-orphans-commit-evidence.landmine.md

@@ -1,19 +1,20 @@
 ---
+id: 5
 type: landmine
 title: rewriting git history orphans commit-SHA evidence in scars — receipts break in fresh clones
 severity: medium
 confidence: 0.9
 created: 2026-06-11
-authors: ["claude-code"]
+authors: ["claude-code", "Kibukx"]
 anchors:
   - path: .scars/
   - pattern: "push.{0,30}(--force|\\+[a-zA-Z]).{0,40}main|filter-repo|checkout --orphan"
 evidence:
-  - note: "v0.1.0 public release (2026-06-11): fresh-start force-push orphaned 3 commit SHAs cited by scars 0001 and 0002; SHAs still resolve on GitHub by URL but fail in any fresh clone, and GitHub may GC them eventually"
+  - note: v0.1.0 public release (2026-06-11): fresh-start force-push orphaned 3 commit SHAs cited by scars 0001 and 0002; SHAs still resolve on GitHub by URL but fail in any fresh clone, and GitHub may GC them eventually
 expires:
   condition: "evidence schema gains a resolvable form (full URL or archived diff) or lint warns on bare SHAs at promotion"
   review_after: 2027-06-11
-status: candidate
+status: active
 ---
 
 Scars cite commit SHAs as evidence receipts. Those receipts implicitly assume

scar_cli-0.3.0/.scars/candidates/fp-log.txt

@@ -0,0 +1 @@
+2026-06-12 false trigger: meta-session — we tuned the revert-language detector itself, so assistant prose ('revert language', 'reverting' in test fixtures/PR text) matched REVERT_RE; nothing abandoned (tool_errors were expected CLI probes/rejections). First post-tune FP pattern: self-referential sessions about the drafter trip the drafter.

scar_cli-0.3.0/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md
+
+## Project Overview
+
+SCAR records negative knowledge for a repository: failed approaches
+(`deadend`), intentional weirdness (`fence`), and non-obvious coupling
+(`landmine`). Scars live in `.scars/` as Markdown files with mandatory YAML
+frontmatter.
+
+## Agent Contract
+
+- Before editing anchored code, query SCAR with `scar inject --path <path>` or,
+  when you have a diff, `scar inject --diff <unified-diff>`.
+- Honor injected scars unless the user explicitly overrides them.
+- New scars always start in `.scars/candidates/`; never write directly to
+  active `.scars/*.md` files.
+- A human promotes candidates with `scar promote`.
+- Do not silently ignore broken scar files. Run `scar lint` when changing scar
+  format, parsing, promotion, lifecycle, or candidate-writing behavior.
+
+## Agent Integrations
+
+- MCP-capable agents can launch the local server with `scar mcp`.
+- Integration snippets are available with:
+  - `scar agent config codex`
+  - `scar agent config cursor`
+  - `scar agent config opencode`
+  - `scar agent config windsurf`
+- Check local readiness with `scar agent doctor`.
+
+## Development Commands
+
+- Run tests: `uv run pytest`
+- Run focused tests: `uv run pytest tests/test_cli.py tests/test_match.py`
+- Lint scars: `uv run scar lint`
+
+## Repository Rules
+
+- Do not add AI attribution or `Co-Authored-By` lines to commits.
+- Use conventional commit messages.
+- Do not build after changes.
+- Keep runtime dependencies at zero unless there is a strong architectural
+  reason and tests/docs are updated with the tradeoff.

scar_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.3.0](https://github.com/Daily-Nerd/Scar/compare/v0.2.0...v0.3.0) (2026-06-12)
+
+
+### Features
+
+* **agents:** multi-agent scar integration — AGENTS.md, MCP server, agent helpers ([#21](https://github.com/Daily-Nerd/Scar/issues/21)) ([52c817f](https://github.com/Daily-Nerd/Scar/commit/52c817fc963f8f829b70de60b772c1097c6f0334))
+
+## [0.2.0](https://github.com/Daily-Nerd/Scar/compare/v0.1.1...v0.2.0) (2026-06-12)
+
+
+### Features
+
+* **cli:** lifecycle v0 — challenge, archive, review_after surfacing ([#16](https://github.com/Daily-Nerd/Scar/issues/16)) ([0c6fb05](https://github.com/Daily-Nerd/Scar/commit/0c6fb05fbdbb57f8ac9b2a5b558e4cf121c3d5c0)), closes [#14](https://github.com/Daily-Nerd/Scar/issues/14)
+
+
+### Documentation
+
+* **readme:** scar challenge is planned, not shipped — point to lifecycle issue ([8c6b021](https://github.com/Daily-Nerd/Scar/commit/8c6b021c95299cf40bf6c2d978a0421bb9705cb6))
+
+## [0.1.1](https://github.com/Daily-Nerd/Scar/compare/v0.1.0...v0.1.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **hooks:** drafter triggers on revert language only ([#12](https://github.com/Daily-Nerd/Scar/issues/12)) ([547c4bb](https://github.com/Daily-Nerd/Scar/commit/547c4bb21e3521682b6a4046602d6703d88c2cf1)), closes [#11](https://github.com/Daily-Nerd/Scar/issues/11)

{scar_cli-0.1.1 → scar_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.1.1
+Version: 0.3.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -49,9 +49,9 @@ The flip side: agents also solve the historically fatal flaw of every knowledge-
 - 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 mcp` — local MCP server, so MCP-capable agents can query and draft scars
 - `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").
+- Scars are **advisory, never blocking, by default** — and stale knowledge has a lifecycle: `scar challenge <id> --reason` disputes a scar (it still fires, marked as disputed), `scar archive <id> --reason` retires it (never fires again; `scar why` keeps the history), and `scar lint`/`scar status` surface any scar whose `review_after` date has passed. Nothing expires automatically — archiving is a human decision, same governance as promotion.
 
 ## Install
 
@@ -86,6 +86,22 @@ Wiring the Claude Code hook (auto-injects scars before any agent edit):
 scar hook install
 ```
 
+Wiring MCP-capable agents:
+
+```bash
+scar agent doctor
+scar agent config opencode   # or: codex, cursor, windsurf
+```
+
+The MCP server runs as:
+
+```bash
+scar mcp
+```
+
+It exposes `scar_query`, `scar_why`, and `scar_draft`. Drafting writes only to
+`.scars/candidates/`; active enforcement still requires human promotion.
+
 ## 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.

{scar_cli-0.1.1 → scar_cli-0.3.0}/README.md

@@ -40,9 +40,9 @@ The flip side: agents also solve the historically fatal flaw of every knowledge-
 - 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 mcp` — local MCP server, so MCP-capable agents can query and draft scars
 - `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").
+- Scars are **advisory, never blocking, by default** — and stale knowledge has a lifecycle: `scar challenge <id> --reason` disputes a scar (it still fires, marked as disputed), `scar archive <id> --reason` retires it (never fires again; `scar why` keeps the history), and `scar lint`/`scar status` surface any scar whose `review_after` date has passed. Nothing expires automatically — archiving is a human decision, same governance as promotion.
 
 ## Install
 
@@ -77,6 +77,22 @@ Wiring the Claude Code hook (auto-injects scars before any agent edit):
 scar hook install
 ```
 
+Wiring MCP-capable agents:
+
+```bash
+scar agent doctor
+scar agent config opencode   # or: codex, cursor, windsurf
+```
+
+The MCP server runs as:
+
+```bash
+scar mcp
+```
+
+It exposes `scar_query`, `scar_why`, and `scar_draft`. Drafting writes only to
+`.scars/candidates/`; active enforcement still requires human promotion.
+
 ## 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.

{scar_cli-0.1.1 → scar_cli-0.3.0}/SPEC.md

@@ -81,7 +81,10 @@ scar why <path>           # human-readable history of pain for a file/dir
 scar challenge <id>       # open a challenge: contest staleness with evidence
 scar harvest              # mine git history, emit candidate scars to .scars/candidates/
 scar status               # active/orphaned/challenged/expiring counts; repo health
-scar inject --diff <d>    # machine mode: top-k scars for a diff as JSON/markdown (hook backend)
+scar inject --path <p>    # machine mode: top-k scars for one edit as hook JSON
+scar inject --diff <d>    # machine mode: top-k scars for a unified diff as hook JSON
+scar mcp                  # stdio MCP server for MCP-capable agents
+scar agent config <name>  # print setup snippets for supported agent runtimes
 ```
 
 ## 4. Agent integration
@@ -98,7 +101,7 @@ Also `PostToolUse`/stop-hook prompt: *"You appear to have abandoned approach X a
 
 ### 4.2 MCP server
 
-`scar-mcp` exposes: `scar_query(paths|symbols|pattern)`, `scar_why(path)`, `scar_draft(type, title, body, anchors, evidence)` (writes to `candidates/`, never directly to active). Works for any MCP-capable agent — Cursor, Windsurf, custom.
+`scar mcp` exposes: `scar_query(paths|content|diff)`, `scar_why(path)`, `scar_draft(type, title, body, anchors, evidence)` (writes to `candidates/`, never directly to active). Works for any MCP-capable agent — Codex, Cursor, Windsurf, opencode, custom.
 
 ### 4.3 Ranking and the fatigue budget
 

{scar_cli-0.1.1 → scar_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scar-cli"
-version = "0.1.1"
+version = "0.3.0"
 description = "SCAR — version control for negative knowledge (deadends, fences, landmines)"
 readme = "README.md"
 requires-python = ">=3.10"

scar_cli-0.3.0/src/scar/agent.py

@@ -0,0 +1,66 @@
+"""Agent integration helpers."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+_MCP_SERVERS_SNIPPET = """\
+Configure a local MCP server named "scar" with:
+
+{
+  "mcpServers": {
+    "scar": {
+      "command": "scar",
+      "args": ["mcp"]
+    }
+  }
+}
+"""
+
+# target -> setup text; adding a runtime is one entry here, no logic change
+CONFIGS = {
+    "codex": """\
+Codex-compatible setup:
+
+1. Keep AGENTS.md committed at the repository root.
+2. Expose SCAR through MCP with command: scar mcp
+3. For direct shell use, ask the agent to run:
+   scar inject --path <path> --content <new-content>
+   scar inject --diff <unified-diff>
+""",
+    "cursor": _MCP_SERVERS_SNIPPET,
+    "opencode": """\
+Add this to opencode.jsonc:
+
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "scar": {
+      "type": "local",
+      "command": ["scar", "mcp"],
+      "enabled": true
+    }
+  }
+}
+""",
+    "windsurf": "Cascade: " + _MCP_SERVERS_SNIPPET,
+}
+
+TARGETS = tuple(sorted(CONFIGS))
+
+
+def doctor(repo: Path) -> list[str]:
+    root = repo.resolve()
+    findings = []
+    findings.append(f"AGENTS.md: {'present' if (root / 'AGENTS.md').exists() else 'missing'}")
+    findings.append(f".scars/: {'present' if (root / '.scars').is_dir() else 'missing'}")
+    findings.append(f"scar binary: {shutil.which('scar') or 'not found on PATH'}")
+    findings.append("MCP command: scar mcp")
+    return findings
+
+
+def config(target: str) -> str:
+    if target not in CONFIGS:
+        raise ValueError(f"unknown target '{target}' (expected: {', '.join(TARGETS)})")
+    return CONFIGS[target]

{scar_cli-0.1.1 → scar_cli-0.3.0}/src/scar/cli.py

@@ -10,15 +10,14 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+import time
 from pathlib import Path
 
 from .lint import lint_text
-from .match import rank_for_edit
-from .model import ParseError, parse_scar_text
+from .match import rank_for_edit, rank_matches_for_diff, rank_matches_for_edit
+from .render import injection_context, label_line
 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())
@@ -58,8 +57,16 @@ def _cmd_status(_args) -> int:
     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 f, s in store.parsed():
+        if s.status == "challenged":
+            print(f"  [challenged {s.type} #{s.id}] {s.title}")
     for c in cands:
         print(f"  candidate: {c.name}")
+    today = time.strftime("%Y-%m-%d")
+    due = [s for _, s in store.firing() if s.review_after and s.review_after < today]
+    for s in due:
+        print(f"  REVIEW DUE [{s.type} #{s.id}] review_after {s.review_after} — "
+              "re-verify, then update the date or archive")
     if broken:
         print(f"  WARNING: {len(broken)} unparseable (can NEVER fire): "
               + ", ".join(b.name for b in broken))
@@ -94,62 +101,67 @@ def _cmd_check(args) -> int:
         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(label_line(s))
         print("  " + s.body[:200].replace("\n", "\n  "))
     return 0
 
 
+def _cmd_transition(args, new_status: str) -> int:
+    store = _require_store()
+    if store is None:
+        return 1
+    try:
+        path = store.transition(args.id, new_status, reason=args.reason,
+                                date=time.strftime("%Y-%m-%d"))
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    verb = ("still fires, marked as disputed — resolve by archiving or "
+            "re-validating" if new_status == "challenged"
+            else "never fires again; history kept (scar why still shows it)")
+    print(f"{new_status} -> {path.relative_to(store.root)} ({verb})")
+    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:
+    records = store.scars_for_path(rel)
+    for f, s in records:
+        print(f"[{s.status} {s.type} #{s.id}] {s.title}  ({f.name})")
+        print("  " + s.body[:300].replace("\n", "\n  ") + "\n")
+    if not records:
         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())
+    start = Path(args.path).resolve() if args.path else Path.cwd()
+    store = ScarStore.discover(start)
     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:
+    if args.diff:
+        try:
+            diff_text = Path(args.diff).read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError, ValueError):
+            # ValueError covers NUL-byte paths; a hook must never crash on
+            # whatever lands in --diff — fall back to treating it as text
+            diff_text = args.diff
+        matches = rank_matches_for_diff(store, diff_text, top_k=args.top_k)
+    elif args.path:
+        matches = rank_matches_for_edit(store, Path(args.path).resolve(),
+                                        args.content or "", top_k=args.top_k)
+    else:
+        matches = []
+    context = injection_context([m.scar for m in matches], store.broken(),
+                                store.scars_dir)
+    if context:
         print(json.dumps({"hookSpecificOutput": {
-            "hookEventName": args.hook_event, "additionalContext": "\n\n".join(parts)}}))
+            "hookEventName": args.hook_event, "additionalContext": context}}))
     return 0
 
 
@@ -175,6 +187,20 @@ def _cmd_harvest(args) -> int:
     return 0
 
 
+def _cmd_agent(args) -> int:
+    from .agent import config, doctor
+    if args.agent_command == "doctor":
+        for line in doctor(Path.cwd()):
+            print(line)
+        return 0
+    try:
+        print(config(args.target))
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="scar",
                                      description="version control for negative knowledge")
@@ -196,26 +222,50 @@ def main(argv: list[str] | None = None) -> int:
     p = sub.add_parser("why", help="history of pain for a path (any status)")
     p.add_argument("path")
 
+    p = sub.add_parser("challenge", help="dispute a scar (still fires, marked challenged)")
+    p.add_argument("id", type=int)
+    p.add_argument("--reason", required=True, help="why the scar may no longer hold")
+
+    p = sub.add_parser("archive", help="retire a scar (never fires; history kept)")
+    p.add_argument("id", type=int)
+    p.add_argument("--reason", required=True, help="why it is retired (e.g. expiry condition met)")
+
     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"])
 
+    sub.add_parser("mcp", help="run the SCAR MCP stdio server")
+
+    p = sub.add_parser("agent", help="agent integration helpers")
+    agent_sub = p.add_subparsers(dest="agent_command", required=True)
+    agent_sub.add_parser("doctor", help="show local agent integration readiness")
+    cfg = agent_sub.add_parser("config", help="print config for an agent runtime")
+    cfg.add_argument("target", choices=["codex", "cursor", "opencode", "windsurf"])
+
     p = sub.add_parser("inject", help="machine mode for hooks: JSON or silence")
-    p.add_argument("--path", required=True)
+    p.add_argument("--path")
     p.add_argument("--content", default="")
+    p.add_argument("--diff", help="unified diff text, or path to a diff file")
     p.add_argument("--top-k", type=int, default=3)
     p.add_argument("--hook-event", default="PreToolUse")
 
     args = parser.parse_args(argv)
+    if args.command == "mcp":
+        from .mcp import serve
+        return serve()
     if args.command == "hook":
         from .hooks import HANDLERS  # hot path: imports nothing beyond library
         return HANDLERS[args.kind]()
+    if args.command in ("challenge", "archive"):
+        status = {"challenge": "challenged", "archive": "archived"}[args.command]
+        return _cmd_transition(args, status)
     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,
+        "agent": _cmd_agent,
     }[args.command]
     return handler(args)
 

{scar_cli-0.1.1 → scar_cli-0.3.0}/src/scar/hooks.py

@@ -18,10 +18,9 @@ import time
 from pathlib import Path
 
 from .match import rank_for_edit
+from .render import injection_context
 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)|"
@@ -71,22 +70,9 @@ def precheck() -> int:
     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))
+    context = injection_context(hits, store.broken(), store.scars_dir)
+    if context:
+        _emit("PreToolUse", context)
     return 0
 
 

{scar_cli-0.1.1 → scar_cli-0.3.0}/src/scar/lint.py

@@ -6,6 +6,7 @@ contract in .scars/README.md.
 from __future__ import annotations
 
 import re
+import time
 from dataclasses import dataclass
 
 from .model import SEVERITIES, STATUSES, TYPES, ParseError, parse_scar_text
@@ -20,11 +21,12 @@ class Finding:
         return f"{self.level}: {self.message}"
 
 
-def lint_text(text: str) -> list[Finding]:
+def lint_text(text: str, today: str | None = None) -> list[Finding]:
     try:
         scar = parse_scar_text(text)
     except ParseError:
         return [Finding("error", "missing YAML frontmatter — this scar can NEVER fire")]
+    today = today or time.strftime("%Y-%m-%d")
 
     findings = []
     if scar.type not in TYPES:
@@ -44,6 +46,13 @@ def lint_text(text: str) -> list[Finding]:
             findings.append(Finding("error", f"invalid pattern anchor /{pat}/: {exc}"))
     if not scar.evidence:
         findings.append(Finding("warning", "no evidence links — challengeable on sight"))
+    # ISO dates compare correctly as strings; never an error — a human
+    # decides whether to archive (ADR-4), lint only surfaces the due date
+    if (scar.status in ("active", "challenged") and scar.review_after
+            and scar.review_after < today):
+        findings.append(Finding(
+            "warning", f"review_after {scar.review_after} is past — re-verify "
+            "the scar still holds, then update the date or archive it"))
     if not scar.body:
         findings.append(Finding("warning", "empty body — future readers get no why"))
     return findings