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

{scar_cli-0.2.0 → scar_cli-0.4.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.4.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.4.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.4.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.4.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## [0.4.0](https://github.com/Daily-Nerd/Scar/compare/v0.3.0...v0.4.0) (2026-06-12)
+
+
+### Features
+
+* **format:** reserve optional receipt_id field ([#29](https://github.com/Daily-Nerd/Scar/issues/29)) ([47ce933](https://github.com/Daily-Nerd/Scar/commit/47ce933cde02fa1155d0474e98101804cb7b1a80))
+
+
+### Bug Fixes
+
+* **hooks:** expose lifecycle commands ([#31](https://github.com/Daily-Nerd/Scar/issues/31)) ([dba2c0d](https://github.com/Daily-Nerd/Scar/commit/dba2c0d1c1bd8a0f73880bfab0ff17187eec2fb9)), closes [#30](https://github.com/Daily-Nerd/Scar/issues/30)
+
+
+### Documentation
+
+* **roadmap:** truth pass — gates resolved, Phase 1 shipped, Phase 2 in progress ([#26](https://github.com/Daily-Nerd/Scar/issues/26)) ([7701a97](https://github.com/Daily-Nerd/Scar/commit/7701a97610f470e7726e7f5fc86932a5101eb255))
+
+## [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.2.0 → scar_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -49,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.
 
@@ -84,8 +84,33 @@ Wiring the Claude Code hook (auto-injects scars before any agent edit):
 
 ```bash
 scar hook install
+scar hook status
 ```
 
+Hooks are advisory and are installed only by this explicit user command. To
+stop all automatic injection and drafting while keeping the repository's
+`.scars/` records:
+
+```bash
+scar hook uninstall
+```
+
+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.4.0}/README.md

@@ -40,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.
 
@@ -75,8 +75,33 @@ Wiring the Claude Code hook (auto-injects scars before any agent edit):
 
 ```bash
 scar hook install
+scar hook status
 ```
 
+Hooks are advisory and are installed only by this explicit user command. To
+stop all automatic injection and drafting while keeping the repository's
+`.scars/` records:
+
+```bash
+scar hook uninstall
+```
+
+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.4.0/ROADMAP.md

@@ -0,0 +1,48 @@
+# SCAR — Roadmap
+
+Restructured after the adversarial review (see [STRESS-TEST.md](STRESS-TEST.md)): **validation before construction**. Every phase had a kill gate decided in advance. Phase 0 and Phase 1 are complete; Phase 2 is in progress. Strategy note (2026-06-11): SCAR is published as **OSS-as-gift** — personal infrastructure shared openly, no product promises. Product work only happens if organic stranger traction appears; that decision retired gate 0.5.
+
+## Phase 0 — Kill-gate experiments ✅ complete
+
+| # | Experiment | Gate (pass/kill) | Result |
+|---|-----------|------------------|--------|
+| 0.1 | Prototype `scar harvest` (reverts, add-then-remove deps, reopened issues, comment archaeology); run on 5 real aging repos | ≥1 "I'd forgotten that" reaction per repo from someone who knows it; harvest precision subjectively >50% | ✅ **PASSED 2026-06-09** on a 7-year-old personal infra repo — owner had forgotten a service-placement deadend the harvest resurfaced; 12/12 curated candidates correct. Raw precision 13% → ranking layer remains a requirement (Phase 2). |
+| 0.2 | Prototype anchors (tree-sitter symbols + content fingerprints); replay real historical refactor commits against them | ≥80% anchor survival across rename + file-split refactors | ✅ **PASSED 2026-06-09** — 94.8% single-commit, 88.0% at 200-commit zero-maintenance horizon; naive path+line baseline 0.0% ([results](experiments/anchor-survival/RESULTS.md)) |
+| 0.3 | **Fence honor test**: hand-write fences on a real repo, wire a PreToolUse hook, A/B agent sessions hook-on vs hook-off on tasks that tempt fence-bulldozing | Hook measurably reduces fence violations without degrading task completion | ✅ **PASSED 2026-06-09** — 6/6 control violations vs 0/6 treatment ([results](experiments/fence-honor/RESULTS.md)) |
+| 0.4 | Auto-authorship trial: 2 weeks of normal agent-assisted work with the stop-hook drafting `deadend` candidates | ≥5 human-kept scars; false-positive rate <15% (skeptic's bar, adopted) | ✅ **PASSED 2026-06-11**, closed day 3 of 14 — 13 keepable agent-authored scars across 3 repos, 0% rejected. One agent-authored scar caught a real parser bug and fired on the exact edit that fixed it. Drafter *trigger* precision was tuned separately (revert-language-only) after 3 of 6 firings proved false. |
+| 0.5 | Survey 50 Claude Code / Cursor users re: Copilot Memory | Meaningful segment says no + wants repo-resident, reviewable knowledge | ⛔ **RETIRED 2026-06-11** — the OSS-as-gift decision removed the product hypothesis this gate validated. If stranger traction ever reopens the product question, this survey reopens with it. |
+| 0.6 | Implement Lore trailers on the same repo as 0.3; compare agent behavior vs scar injection | SCAR injection outperforms history-walk over trailers on latency and compliance | ⏸ **Deprioritized** — no longer gating anything; optional research. |
+
+## Phase 1 — Format + CLI (OSS) ✅ shipped
+
+Public at [github.com/Daily-Nerd/Scar](https://github.com/Daily-Nerd/Scar), `scar-cli` on PyPI. Honest deltas from the original plan:
+
+- ✅ `SCAR-FORMAT.md` v0.1 published; one parser/serializer (`model.py`), one renderer (`render.py`)
+- ✅ CLI: `init, lint, status, promote, check, why, challenge, archive, harvest, hook, mcp, agent, inject` — lifecycle commands (`challenge`/`archive`, expiry review surfacing) shipped beyond the original plan
+- ✅ Claude Code plugin: PreToolUse injection + stop-hook candidate drafting, both field-validated (gates 0.3, 0.4)
+- ⚠️ **Python, not Go/Rust** — zero-dependency stdlib hits the goal the compiled binary was chasing (~20ms hook startup, trivial install via `uv tool install scar-cli`); a rewrite is not planned unless profiling says otherwise
+- ❌ No `add` command — copy `template.md` + `scar promote` covers authoring; revisit only on user friction
+- ❌ Lore trailer ingestion in `harvest` — moved to Phase 2, optional
+- ✅ Dogfooding: 6 repos, including this one (the repo's own scars caught its own release-process bug)
+
+## Phase 2 — Ecosystem 🔄 in progress
+
+- ✅ **MCP server** (`scar_query`, `scar_why`, `scar_draft`) — shipped v0.3.0, dependency-free stdio, drafts gated to candidates/. First non-Claude agent (Codex) arrived and contributed the implementation — the deferral condition resolving itself.
+- ✅ Multi-agent surface: committed `AGENTS.md`, `scar inject --diff`, `scar agent doctor/config` for Codex, Cursor, Windsurf, opencode (v0.3.0)
+- 🔶 CI surface: expiry warnings shipped (`lint`/`status`, v0.2.0); **orphan detection is the next milestone** — content-fingerprint drift → `orphaned` status, loud in CI (principle 3 is not yet enforced by code)
+- ⬜ Harvest ranking layer (gate 0.1 verdict: required — raw precision 13% without it)
+- ⬜ Re-anchoring agent workflow: orphaned scar + orphaning diff → proposed new anchors as a PR
+- ⬜ Editor surfaces (VS Code gutter marks, LSP code lens) — fences visible to humans, not only agents
+- ⬜ Lint warning on evidence commit SHAs unreachable from HEAD (scar #5's expiry condition)
+
+## Phase 3 — The org graph ⏸ parked by design
+
+The commercial hypothesis (cross-repo aggregation, recurrence analytics, policy, managed harvest) is **parked under the OSS-as-gift decision**, not killed: it reopens only on organic adoption signal — external repos with active scars, inbound interest from strangers. "SCAR remains a free standard" was declared in advance as an acceptable ending, and it is the current operating assumption.
+
+## Non-negotiable principles carried from the stress test
+
+1. Advisory by default, forever. Blocking is opt-in, per-scar-severity, in CI only.
+2. Max 3 scars / ~120 words each injected per edit. The fatigue budget is a format-level guarantee, not a tuning knob (enforced in `render.py`).
+3. Rot must be loud. No scar ever disappears silently; orphaning is a visible state. *(Lifecycle transitions enforce this for human decisions; orphan detection — the code-drift half — is Phase 2's next milestone.)*
+4. Assume zero ongoing human maintenance; design for graceful visible decay.
+5. The format stays open and vendor-neutral even if a company forms. Platform absorption of the format = success, not failure.

{scar_cli-0.2.0 → scar_cli-0.4.0}/SCAR-FORMAT.md

@@ -47,6 +47,17 @@ is deliberate: consumers in hook hot-paths parse with zero dependencies.
 | `expires.condition` | recommended | quoted string | what change obsoletes this scar |
 | `expires.review_after` | recommended | ISO date | forces periodic freshness contact |
 | `status` | yes | `candidate` \| `active` \| `challenged` \| `archived` \| `orphaned` \| `template` | lifecycle §5 |
+| `receipt_id` | reserved | string ref | **reserved — not yet parsed.** Optional pointer to a cryptographic provenance receipt; see note below. |
+
+`receipt_id` is a forward-compatibility reservation, not a live field. Scar's
+trust model is social by design (git history, `authors`, evidence-by-reference);
+that is sufficient within one repo or org. It does **not** carry across orgs that
+share no git history — the future cross-org / org-graph layer where "this dead end
+hit N teams" must be attributable. `receipt_id` reserves the slot for a signed,
+content-addressed receipt (e.g. [veritrail](https://github.com/Daily-Nerd/veritrail))
+bound to an authorship (`scar_draft`) or promotion event. No tool emits, requires,
+or validates it today, and the line-wise parser ignores it like any unknown key —
+so existing scars are unaffected. It will not become required in v0.x.
 
 Body: prose after the frontmatter, 5–15 lines. What happened, why, what a
 future editor must do instead — written for a reader with zero context.

{scar_cli-0.2.0 → scar_cli-0.4.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.4.0/hook/scar-hooks.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Backward-compatible wrapper for the packaged hook lifecycle commands."""
+
+import sys
+
+from scar.installer import find_scar, install, status, uninstall
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    dry = "--dry-run" in args
+    cmd = next((a for a in args if not a.startswith("-")), "status")
+    sys.exit({"install": lambda: install(dry=dry),
+              "uninstall": lambda: uninstall(dry=dry),
+              "status": status}.get(cmd, status)())

{scar_cli-0.2.0 → scar_cli-0.4.0}/pyproject.toml

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

scar_cli-0.4.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.4.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,29 @@ 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 _cmd_hook_lifecycle(args) -> int:
+    from .installer import install, status, uninstall
+    if args.kind == "install":
+        return install(dry=args.dry_run)
+    if args.kind == "uninstall":
+        return uninstall(dry=args.dry_run)
+    return status()
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="scar",
                                      description="version control for negative knowledge")
@@ -235,17 +242,34 @@ def main(argv: list[str] | None = None) -> int:
     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("hook", help="install, remove, inspect, or run Claude Code hooks")
+    p.add_argument("kind", choices=["install", "uninstall", "status",
+                                    "precheck", "session-notice", "stop-drafter"])
+    p.add_argument("--dry-run", action="store_true",
+                   help="show lifecycle changes without writing settings")
+
+    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":
+        if args.kind in ("install", "uninstall", "status"):
+            return _cmd_hook_lifecycle(args)
         from .hooks import HANDLERS  # hot path: imports nothing beyond library
         return HANDLERS[args.kind]()
     if args.command in ("challenge", "archive"):
@@ -255,6 +279,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.4.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