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

scar_cli-0.2.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.2.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.1.1
+Version: 0.2.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -51,7 +51,7 @@ The flip side: agents also solve the historically fatal flaw of every knowledge-
   - 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").
+- 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
 

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

@@ -42,7 +42,7 @@ The flip side: agents also solve the historically fatal flaw of every knowledge-
   - 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").
+- 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
 

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

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

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

@@ -10,6 +10,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+import time
 from pathlib import Path
 
 from .lint import lint_text
@@ -58,8 +59,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,11 +103,29 @@ 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}")
+        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("  " + 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())
@@ -134,7 +161,8 @@ def _cmd_inject(args) -> int:
     parts = []
     if hits:
         blocks = [
-            f"[{s.type} #{s.id} | severity: {s.severity} | confidence: {s.confidence}] "
+            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(
@@ -196,6 +224,14 @@ 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=".")
 
@@ -212,6 +248,9 @@ def main(argv: list[str] | None = None) -> int:
     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,

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

@@ -74,7 +74,8 @@ def precheck() -> int:
     broken = store.broken()
     parts = []
     if hits:
-        blocks = [f"[{s.type} #{s.id} | severity: {s.severity} | confidence: "
+        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 "

{scar_cli-0.1.1 → scar_cli-0.2.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

{scar_cli-0.1.1 → scar_cli-0.2.0}/src/scar/match.py

@@ -36,13 +36,13 @@ def _anchor_strength(scar: Scar, rel_path: str, new_content: str) -> float:
 
 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`."""
+    """Top-k firing scars (active + challenged) relevant to editing `target`."""
     try:
         rel_path = str(Path(target).resolve().relative_to(store.root))
     except ValueError:
         return []
     ranked = []
-    for _, scar in store.active():
+    for _, scar in store.firing():
         strength = _anchor_strength(scar, rel_path, new_content)
         if strength > 0:
             rank = strength * SEVERITY_WEIGHT.get(scar.severity, 2) * scar.confidence

{scar_cli-0.1.1 → scar_cli-0.2.0}/src/scar/store.py

@@ -101,17 +101,25 @@ class ScarStore:
         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]]:
+    def parsed(self) -> list[tuple[Path, Scar]]:
         out = []
         for f in self._scar_files():
             try:
-                scar = parse_scar_text(f.read_text(encoding="utf-8"))
+                out.append((f, parse_scar_text(f.read_text(encoding="utf-8"))))
             except (ParseError, OSError):
                 continue
-            if scar.status == "active":
-                out.append((f, scar))
         return out
 
+    def active(self) -> list[tuple[Path, Scar]]:
+        return [(f, s) for f, s in self.parsed() if s.status == "active"]
+
+    def firing(self) -> list[tuple[Path, Scar]]:
+        """Scars that still inject: active, plus challenged (disputed but
+        not yet resolved by a human — suppressing them would let a mere
+        objection silently delete knowledge)."""
+        return [(f, s) for f, s in self.parsed()
+                if s.status in ("active", "challenged")]
+
     def broken(self) -> list[Path]:
         out = []
         for f in self._scar_files():
@@ -138,6 +146,20 @@ class ScarStore:
                 continue
         return max(ids, default=0) + 1
 
+    def transition(self, scar_id: int, new_status: str, reason: str, date: str) -> Path:
+        """Flip a scar's status in place, appending the reason as an evidence
+        note. The file keeps its name and id — archived/challenged scars stay
+        findable (`scar why`); orphaned != deleted, ever."""
+        for f, s in self.parsed():
+            if s.id == scar_id:
+                if s.status == new_status:
+                    raise ValueError(f"scar #{scar_id} is already {new_status}")
+                s.status = new_status
+                s.evidence.append(f"note: {new_status} {date}: {reason}")
+                f.write_text(s.to_text(), encoding="utf-8")
+                return f
+        raise ValueError(f"no scar with id {scar_id}")
+
     def promote(self, candidate: Path, reviewer: str) -> Path:
         text = candidate.read_text(encoding="utf-8")
         findings = lint_text(text)

scar_cli-0.2.0/tests/test_lifecycle.py

@@ -0,0 +1,137 @@
+"""Lifecycle v0 (#14): challenge, archive, review_after surfacing.
+
+Contract: challenged scars still fire (marked), archived never fire,
+expiry dates surface as warnings — never auto-archive (ADR-4 governance).
+"""
+
+import pytest
+
+from scar.cli import main
+from scar.lint import lint_text
+from scar.match import rank_for_edit
+from scar.store import ScarStore, init_scars
+
+ACTIVE = """\
+---
+id: 1
+type: deadend
+title: Tried X, failed
+severity: high
+confidence: 0.9
+created: 2026-06-10
+authors: ["claude-code"]
+anchors:
+  - path: src/
+evidence:
+  - commit: abc1234
+expires:
+  condition: "X becomes viable"
+  review_after: 2026-01-01
+status: active
+---
+
+Why X failed.
+"""
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    (tmp_path / ".git").mkdir()
+    monkeypatch.chdir(tmp_path)
+    init_scars(tmp_path)
+    (tmp_path / ".scars" / "0001-tried-x.deadend.md").write_text(ACTIVE)
+    return tmp_path
+
+
+def store_of(repo):
+    return ScarStore.discover(repo)
+
+
+# --- store.transition ---
+
+def test_challenge_flips_status_and_records_reason(repo):
+    store = store_of(repo)
+    path = store.transition(1, "challenged", reason="X works since v9", date="2026-06-12")
+    text = path.read_text()
+    assert "status: challenged" in text
+    assert "challenged 2026-06-12: X works since v9" in text
+    # same file, in place — archived/challenged scars keep their identity
+    assert path.name == "0001-tried-x.deadend.md"
+
+
+def test_archive_flips_status_and_records_reason(repo):
+    store = store_of(repo)
+    path = store.transition(1, "archived", reason="condition met", date="2026-06-12")
+    assert "status: archived" in path.read_text()
+
+
+def test_transition_unknown_id_raises(repo):
+    with pytest.raises(ValueError):
+        store_of(repo).transition(99, "archived", reason="r", date="2026-06-12")
+
+
+def test_transition_to_same_status_raises(repo):
+    store = store_of(repo)
+    store.transition(1, "challenged", reason="r", date="2026-06-12")
+    with pytest.raises(ValueError):
+        store.transition(1, "challenged", reason="again", date="2026-06-12")
+
+
+# --- firing semantics ---
+
+def test_challenged_scar_still_fires(repo):
+    store = store_of(repo)
+    store.transition(1, "challenged", reason="r", date="2026-06-12")
+    hits = rank_for_edit(store, repo / "src" / "x.py", "")
+    assert [s.id for s in hits] == [1]
+
+
+def test_archived_scar_never_fires(repo):
+    store = store_of(repo)
+    store.transition(1, "archived", reason="r", date="2026-06-12")
+    assert rank_for_edit(store, repo / "src" / "x.py", "") == []
+
+
+# --- CLI ---
+
+def test_cli_challenge_and_marker_in_check(repo, capsys):
+    assert main(["challenge", "1", "--reason", "X works since v9"]) == 0
+    capsys.readouterr()
+    assert main(["check", str(repo / "src")]) == 0
+    out = capsys.readouterr().out
+    assert "challenged" in out and "#1" in out
+
+
+def test_cli_archive_silences_check(repo, capsys):
+    assert main(["archive", "1", "--reason", "condition met"]) == 0
+    capsys.readouterr()
+    assert main(["check", str(repo / "src")]) == 0
+    assert "no scars anchored" in capsys.readouterr().out
+
+
+def test_cli_challenge_unknown_id_fails(repo, capsys):
+    assert main(["challenge", "7", "--reason", "r"]) == 1
+
+
+# --- review_after surfacing ---
+
+def test_lint_warns_on_past_review_after():
+    findings = lint_text(ACTIVE, today="2026-06-12")
+    assert any("review_after" in f.message and f.level == "warning" for f in findings)
+
+
+def test_lint_silent_on_future_review_after():
+    findings = lint_text(ACTIVE, today="2025-06-12")
+    assert not any("review_after" in f.message for f in findings)
+
+
+def test_lint_silent_on_archived_past_review_after():
+    text = ACTIVE.replace("status: active", "status: archived")
+    findings = lint_text(text, today="2026-06-12")
+    assert not any("review_after" in f.message for f in findings)
+
+
+def test_status_lists_review_due(repo, capsys):
+    assert main(["status"]) == 0
+    out = capsys.readouterr().out
+    assert "review due" in out.lower() and "#1" in out

{scar_cli-0.1.1 → scar_cli-0.2.0}/uv.lock

@@ -79,7 +79,7 @@ wheels = [
 
 [[package]]
 name = "scar-cli"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 
 [package.dev-dependencies]

scar_cli-0.1.1/CHANGELOG.md

@@ -1,8 +0,0 @@
-# Changelog
-
-## [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)