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

{scar_cli-0.2.0 → 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.2.0 → 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.2.0/.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/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.2.0 → scar_cli-0.3.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

scar_cli-0.2.0/README.md → scar_cli-0.3.0/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: scar-cli
+Version: 0.3.0
+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**.
@@ -40,7 +49,7 @@ 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** — 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.
 
@@ -77,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.2.0/PKG-INFO → scar_cli-0.3.0/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: scar-cli
-Version: 0.2.0
-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**.
@@ -49,7 +40,7 @@ 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** — 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.
 
@@ -86,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.2.0 → 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.2.0 → scar_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scar-cli"
-version = "0.2.0"
+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.2.0 → scar_cli-0.3.0}/src/scar/cli.py

@@ -14,12 +14,10 @@ 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())
@@ -103,8 +101,7 @@ def _cmd_check(args) -> int:
         print(f"no scars anchored to {args.path}")
         return 0
     for s in hits:
-        label = f"challenged {s.type}" if s.status == "challenged" else s.type
-        print(f"[{label} #{s.id} | severity: {s.severity} | confidence: {s.confidence}] {s.title}")
+        print(label_line(s))
         print("  " + s.body[:200].replace("\n", "\n  "))
     return 0
 
@@ -132,52 +129,39 @@ def _cmd_why(args) -> int:
     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"[{'challenged ' if s.status == 'challenged' else ''}{s.type} #{s.id} "
-            f"| 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
 
 
@@ -203,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")
@@ -238,13 +236,25 @@ def main(argv: list[str] | None = None) -> int:
     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]()
@@ -255,6 +265,7 @@ def main(argv: list[str] | None = None) -> int:
         "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.2.0 → 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,23 +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"[{'challenged ' if s.status == 'challenged' else ''}{s.type} "
-                  f"#{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.3.0/src/scar/match.py

@@ -0,0 +1,147 @@
+"""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 dataclasses import dataclass
+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
+
+
+@dataclass(frozen=True)
+class ScarMatch:
+    scar: Scar
+    source: Path
+    rank: float
+    anchor_strength: float
+    matched_by: tuple[str, ...]
+    path: str
+
+    def to_dict(self) -> dict:
+        # copy the whole Scar so a future model field can never silently
+        # vanish from MCP responses (guarded by a fields() test)
+        d = dict(self.scar.__dict__)
+        d["anchors"] = {"paths": d.pop("path_anchors"),
+                        "patterns": d.pop("pattern_anchors")}
+        d.update(matched_by=list(self.matched_by),
+                 anchor_strength=self.anchor_strength,
+                 rank=self.rank, path=self.path, source=str(self.source))
+        return d
+
+
+def _anchor_signal(scar: Scar, rel_path: str, new_content: str) -> tuple[float, tuple[str, ...]]:
+    score = 0.0
+    matched: list[str] = []
+    for p in scar.path_anchors:
+        if rel_path.startswith(p.rstrip("/")):
+            score = max(score, 2.0)
+            matched.append("path")
+    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)
+            matched.append("path_pattern")
+        if new_content and rx.search(new_content):
+            score = max(score, 2.5)
+            matched.append("content_pattern")
+    return score, tuple(dict.fromkeys(matched))
+
+
+def _match_target(firing: list, root: Path, rel_path: str,
+                  new_content: str) -> list[ScarMatch]:
+    """Rank one target against an already-loaded firing set (no disk I/O)."""
+    ranked: list[ScarMatch] = []
+    for source, scar in firing:
+        strength, matched_by = _anchor_signal(scar, rel_path, new_content)
+        if strength > 0:
+            rank = strength * SEVERITY_WEIGHT.get(scar.severity, 2) * scar.confidence
+            ranked.append(ScarMatch(scar=scar, source=source.relative_to(root),
+                                    rank=rank, anchor_strength=strength,
+                                    matched_by=matched_by, path=rel_path))
+    ranked.sort(key=lambda m: -m.rank)
+    return ranked
+
+
+def merge_best_matches(match_lists: list[list[ScarMatch]],
+                       top_k: int = DEFAULT_TOP_K) -> list[ScarMatch]:
+    """Dedup matches across targets, keeping each scar's best rank."""
+    best: dict[int | str, ScarMatch] = {}
+    for matches in match_lists:
+        for match in matches:
+            key = match.scar.id if match.scar.id is not None else match.source.as_posix()
+            if key not in best or match.rank > best[key].rank:
+                best[key] = match
+    return sorted(best.values(), key=lambda m: -m.rank)[:top_k]
+
+
+def rank_matches_for_edit(store: ScarStore, target: Path, new_content: str,
+                          top_k: int = DEFAULT_TOP_K) -> list[ScarMatch]:
+    """Top-k firing scar matches relevant to editing `target`."""
+    try:
+        rel_path = str(Path(target).resolve().relative_to(store.root))
+    except ValueError:
+        return []
+    return _match_target(store.firing(), store.root, rel_path, new_content)[:top_k]
+
+
+def rank_matches_for_paths(store: ScarStore, paths: list[str], new_content: str,
+                           top_k: int = DEFAULT_TOP_K) -> list[ScarMatch]:
+    """Best matches across several paths — one store walk, not one per path."""
+    firing = store.firing()
+    lists = []
+    for path in paths:
+        try:
+            rel = str((store.root / str(path)).resolve().relative_to(store.root))
+        except ValueError:
+            continue
+        lists.append(_match_target(firing, store.root, rel, new_content)[:top_k])
+    return merge_best_matches(lists, top_k)
+
+
+def rank_for_edit(store: ScarStore, target: Path, new_content: str,
+                  top_k: int = DEFAULT_TOP_K) -> list[Scar]:
+    """Top-k firing scars (active + challenged) relevant to editing `target`."""
+    return [m.scar for m in rank_matches_for_edit(store, target, new_content, top_k)]
+
+
+def _diff_targets(diff_text: str) -> list[tuple[str, str]]:
+    """Return (path, added_content) pairs from a unified diff."""
+    targets: list[tuple[str, str]] = []
+    current: str | None = None
+    added: list[str] = []
+    for line in diff_text.splitlines():
+        if line.startswith("+++ "):
+            if current:
+                targets.append((current, "\n".join(added)))
+            raw = line[4:].strip()
+            current = raw[2:] if raw.startswith("b/") else raw
+            if current == "/dev/null":
+                current = None
+            added = []
+        elif current and line.startswith("+") and not line.startswith("+++ "):
+            added.append(line[1:])
+    if current:
+        targets.append((current, "\n".join(added)))
+    return targets
+
+
+def rank_matches_for_diff(store: ScarStore, diff_text: str,
+                          top_k: int = DEFAULT_TOP_K) -> list[ScarMatch]:
+    """Top-k firing scar matches across a unified diff (one store walk)."""
+    firing = store.firing()
+    lists = [_match_target(firing, store.root, rel_path, added)[:top_k]
+             for rel_path, added in _diff_targets(diff_text)]
+    return merge_best_matches(lists, top_k)