scar-cli 0.26.0__tar.gz → 0.27.0__tar.gz

scar_cli-0.27.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.27.0"
+}

{scar_cli-0.26.0 → scar_cli-0.27.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.27.0](https://github.com/Daily-Nerd/Scar/compare/v0.26.0...v0.27.0) (2026-11-06)
+
+
+### Features
+
+* **lint:** rolling review queue from scar lint (--review-queue) ([#357](https://github.com/Daily-Nerd/Scar/issues/357)) ([8136513](https://github.com/Daily-Nerd/Scar/commit/8136513ef1c7cbba2ac2d7e1b4f0b68baf6544c0))
+
 ## [0.26.0](https://github.com/Daily-Nerd/Scar/compare/v0.25.1...v0.26.0) (2026-11-06)
 
 

{scar_cli-0.26.0 → scar_cli-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scar-cli
-Version: 0.26.0
+Version: 0.27.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -126,6 +126,11 @@ CI without pre-commit:
 `@main` always tracks the latest commit; releases are tagged `vX.Y.Z` via
 release-please, so pin a tag for reproducible CI.
 
+`scar lint --review-queue` prints a markdown checklist of scars that need a human
+(orphans, partial rot, symbol drift, unreachable evidence, passed `review_after`),
+empty when there are none. The docs have a scheduled-workflow recipe that keeps
+one rolling issue in sync with it: see [CI](https://daily-nerd.github.io/Scar/docs/agents#review-queue).
+
 ## 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.26.0 → scar_cli-0.27.0}/README.md

@@ -111,6 +111,11 @@ CI without pre-commit:
 `@main` always tracks the latest commit; releases are tagged `vX.Y.Z` via
 release-please, so pin a tag for reproducible CI.
 
+`scar lint --review-queue` prints a markdown checklist of scars that need a human
+(orphans, partial rot, symbol drift, unreachable evidence, passed `review_after`),
+empty when there are none. The docs have a scheduled-workflow recipe that keeps
+one rolling issue in sync with it: see [CI](https://daily-nerd.github.io/Scar/docs/agents#review-queue).
+
 ## 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.26.0 → scar_cli-0.27.0}/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "scar",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "SCAR — version control for negative knowledge (deadends, fences, landmines)",
   "hooks": {
     "PreToolUse": [

{scar_cli-0.26.0 → scar_cli-0.27.0}/pyproject.toml

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

{scar_cli-0.26.0 → scar_cli-0.27.0}/src/scar/cli.py

@@ -546,6 +546,74 @@ def _firing_reviews(store):
         return []
 
 
+def _review_due(store) -> list[Scar]:
+    """Firing scars whose review_after date has passed. The one definition
+    shared by `status` and `lint` so the two JSON surfaces cannot disagree."""
+    today = time.strftime("%Y-%m-%d")
+    return [s for _f, s in store.firing() if s.review_after and s.review_after < today]
+
+
+def _review_due_json(due: list[Scar]) -> list[dict]:
+    return [{"type": s.type, "id": s.id, "review_after": s.review_after} for s in due]
+
+
+def _review_queue_markdown(store, data: dict) -> str:
+    """Markdown checklist of scars a human should look at, built from the SAME
+    dict `lint --json` emits (#354). One row per scar, states merged. Only
+    CI-usable signals: the firing log is machine-local and empty on a fresh
+    checkout, so firing_review and never_fired are deliberately absent.
+
+    Only the id, title, a path and fixed state wording are printed. The
+    `reason` strings in `data` embed anchor text and violation hints, so they
+    are never used here, and the body and evidence are never read."""
+    by_id: dict[int, tuple[Path, Scar]] = {}
+    for f, s in store.parsed():
+        if s.id is not None:
+            by_id.setdefault(s.id, (f, s))
+
+    states: dict[int, list[str]] = {}
+    cmds: dict[int, list[str]] = {}
+
+    def add(scar_id: int, state: str, cmd: str) -> None:
+        if state not in states.setdefault(scar_id, []):
+            states[scar_id].append(state)
+        if cmd not in cmds.setdefault(scar_id, []):
+            cmds[scar_id].append(cmd)
+
+    for o in data["orphans"]:
+        add(o["scar_id"], "orphan (all anchors dead)", "`scar reanchor`")
+    for pr in data["partial_rot"]:
+        add(pr["scar_id"], "partial rot (dead anchor among live ones)", "`scar reanchor`")
+    for d in data["symbol_drift"]:
+        add(d["scar_id"], "symbol drift", "`scar why <path>`")
+    for ue in data["unreachable_evidence"]:
+        add(ue["scar_id"], "evidence commit unreachable", "`scar why <path>`")
+    for r in data["revivals"]:
+        add(r["scar_id"], "archived but revives_if matches again", "`scar why <path>`")
+    for rd in data["review_due"]:
+        add(rd["id"], f"review_after {rd['review_after']} passed",
+            f"`scar archive {rd['id']} --reason \"...\"` or bump review_after")
+
+    if not states:
+        return ""
+    lines = []
+    for scar_id in sorted(states):
+        found = by_id.get(scar_id)
+        if found:
+            f, s = found
+            where = s.path_anchors[0] if s.path_anchors else f.name
+            title = s.title
+        else:
+            where, title = "unknown file", "(scar not found)"
+        cmd = "; ".join(cmds[scar_id]).replace("<path>", where)
+        lines.append(f"- [ ] #{scar_id} {title} ({where}): "
+                     f"{'; '.join(states[scar_id])}. Suggested: {cmd}")
+    lines.append("")
+    lines.append("Firing-log signals (firing review, never fired) are not included: "
+                 "the firing log is machine-local and empty in CI.")
+    return "\n".join(lines) + "\n"
+
+
 def _cmd_lint(args) -> int:
     store = _require_store()
     if store is None:
@@ -733,6 +801,7 @@ def _cmd_lint(args) -> int:
     # revised. Advisory like every other lifecycle signal here — only the
     # opt-in --fail-firing-review turns it into an exit code.
     reviews = _firing_reviews(store)
+    review_due = _review_due(store)
 
     # evidence reachability (#43, scar #5): commit-SHA receipts that no longer
     # resolve from HEAD. None = shallow clone, reachability indeterminate → skip.
@@ -762,6 +831,7 @@ def _cmd_lint(args) -> int:
         "unreachable_evidence": [{"scar_id": ue.scar_id, "sha": ue.sha, "reason": ue.reason}
                                  for ue in unreachable],
         "failed": failed,
+        "review_due": _review_due_json(review_due),
     }
 
     def plain():
@@ -809,8 +879,13 @@ def _cmd_lint(args) -> int:
               f"{len(unreachable)} unreachable-evidence, "
               f"{len(reviews)} firing-review")
 
-    output.render(data=data, json_flag=getattr(args, "json", False),
-                  tty=lambda: _lint_rich(data), plain=plain)
+    if getattr(args, "review_queue", False):
+        # Machine path: plain markdown, never rich, and empty stdout when the
+        # queue is empty so a workflow can close its issue on `-s queue.md`.
+        sys.stdout.write(_review_queue_markdown(store, data))
+    else:
+        output.render(data=data, json_flag=getattr(args, "json", False),
+                      tty=lambda: _lint_rich(data), plain=plain)
 
     if failed:
         return 1
@@ -829,8 +904,7 @@ def _cmd_status(args) -> int:
         return 1
     active, broken, cands = store.active(), store.broken(), store.candidates()
     challenged = [(f, s) for f, s in store.parsed() if s.status == "challenged"]
-    today = time.strftime("%Y-%m-%d")
-    due = [s for _, s in store.firing() if s.review_after and s.review_after < today]
+    due = _review_due(store)
 
     # Orphans: detected (firing scars whose anchors all died — not yet persisted)
     # and persisted (already flipped to status: orphaned, invisible until now).
@@ -849,7 +923,7 @@ def _cmd_status(args) -> int:
                    for _f, s in active],
         "challenged": [{"type": s.type, "id": s.id, "title": s.title} for _f, s in challenged],
         "candidates": [c.name for c in cands],
-        "review_due": [{"type": s.type, "id": s.id, "review_after": s.review_after} for s in due],
+        "review_due": _review_due_json(due),
         # Count-based review trigger (#274), kept SEPARATE from review_due:
         # one is a date passing, the other is accumulated firings, and a
         # consumer that merges them cannot tell which obligation it is looking
@@ -3116,7 +3190,11 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--fail-firing-review", action="store_true",
                    help="exit non-zero when any scar has crossed its "
                         "review_after_firings threshold")
-    p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    fmt = p.add_mutually_exclusive_group()
+    fmt.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    fmt.add_argument("--review-queue", action="store_true",
+                     help="print a markdown checklist of scars needing a human "
+                          "(CI-usable signals only); empty output when none")
     p = _add(sub, "status", _cmd_status, help="counts, titles, broken-file warnings")
     p.add_argument("--json", action="store_true", help="emit machine-readable JSON")
 

{scar_cli-0.26.0 → scar_cli-0.27.0}/tests/test_docs.py

@@ -36,3 +36,15 @@ def test_agents_doc_documents_native_codex_hooks_and_trust():
     assert "Bash" in text and "apply_patch" in text
     assert "/hooks" in text
     assert "silently" in text
+
+
+def test_agents_doc_documents_review_queue_recipe():
+    """#354: the rolling review issue is a documented recipe over
+    `scar lint --review-queue`, not a subcommand."""
+    text = (ROOT / "website" / "docs" / "agents.md").read_text(encoding="utf-8")
+    assert "### Review queue" in text
+    assert "scar lint --review-queue" in text
+    assert "scar-review-queue" in text
+    assert "issues: write" in text
+    assert "fetch-depth: 0" in text
+    assert "\u2014" not in text.split("### Review queue")[1].split("## Machine-readable")[0]

{scar_cli-0.26.0 → scar_cli-0.27.0}/tests/test_json_contract.py

@@ -36,7 +36,8 @@ ROOT = Path(__file__).resolve().parent.parent
 GUARANTEED: dict[str, set[str]] = {
     "lint": {"files", "findings", "failed", "orphans", "partial_rot",
              "symbol_drift", "revivals", "reverse_hints",
-             "unreachable_evidence", "shallow_clone", "symbols_unchecked"},
+             "unreachable_evidence", "shallow_clone", "symbols_unchecked",
+             "review_due"},
     "status": {"scars_dir", "active", "challenged", "candidates", "review_due",
                "orphan_detected", "orphaned", "partial_rot", "broken", "counts"},
     "check": {"paths", "scars"},

scar_cli-0.27.0/tests/test_review_queue.py

@@ -0,0 +1,173 @@
+"""Review queue (#354): lint --json carries review_due, and
+`lint --review-queue` renders the CI-usable review signals as markdown."""
+import json
+import subprocess
+
+from scar.cli import main
+from scar.store import init_scars
+
+SCAR = """\
+---
+id: {id}
+type: landmine
+title: {title}
+severity: medium
+confidence: 0.8
+created: 2026-06-10
+authors: ["claude-code"]
+anchors:
+{anchors}
+evidence:
+  - commit: abc1234
+{extra}status: active
+---
+
+{body}
+"""
+
+
+def _write(root, name, *, id, title, anchors, extra="", body="Plain body."):
+    text = SCAR.format(id=id, title=title, anchors="\n".join(
+        f"  - path: {a}" for a in anchors), extra=extra, body=body)
+    (root / ".scars" / name).write_text(text)
+
+
+def _repo(tmp_path, monkeypatch):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.email", "t@t.t"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "t"], cwd=tmp_path, check=True)
+    init_scars(tmp_path)
+    (tmp_path / "src" / "live").mkdir(parents=True)
+    (tmp_path / "src" / "live" / "mod.py").write_text("x = 1\n")
+    monkeypatch.chdir(tmp_path)
+
+
+def _commit(root):
+    """Commit, then point every scar's evidence at that real commit so the
+    fixtures are not accidentally flagged as unreachable-evidence."""
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-q", "-m", "init"], cwd=root, check=True)
+    sha = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, check=True,
+                         capture_output=True, text=True).stdout.strip()
+    for f in (root / ".scars").glob("0*.md"):
+        f.write_text(f.read_text().replace("abc1234", sha))
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-q", "-m", "evidence"], cwd=root, check=True)
+
+
+def _due_and_rot(tmp_path, monkeypatch):
+    _repo(tmp_path, monkeypatch)
+    _write(tmp_path, "0001-due.landmine.md", id=1, title="Due scar",
+           anchors=["src/live/"], extra="review_after: 2020-01-01\n")
+    _write(tmp_path, "0002-rot.landmine.md", id=2, title="Rotted scar",
+           anchors=["src/live/", "src/gone/"], body="SECRET-BODY-TEXT")
+    _commit(tmp_path)
+
+
+def test_lint_json_review_due_matches_status(tmp_path, monkeypatch, capsys):
+    _due_and_rot(tmp_path, monkeypatch)
+    main(["lint", "--json"])
+    lint_due = json.loads(capsys.readouterr().out)["review_due"]
+    main(["status", "--json"])
+    status_due = json.loads(capsys.readouterr().out)["review_due"]
+    assert lint_due == status_due
+    assert [d["id"] for d in lint_due] == [1]
+    assert lint_due[0]["review_after"] == "2020-01-01"
+
+
+def test_lint_json_review_due_empty_list_when_none(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    main(["lint", "--json"])
+    assert json.loads(capsys.readouterr().out)["review_due"] == []
+
+
+# --- lint --review-queue ---
+
+def _queue(capsys, *extra):
+    rc = main(["lint", "--review-queue", *extra])
+    return rc, capsys.readouterr().out
+
+
+def test_review_queue_empty_store_prints_nothing(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    rc, out = _queue(capsys)
+    assert rc == 0
+    assert out == ""
+
+
+def test_review_queue_one_row_per_flagged_scar(tmp_path, monkeypatch, capsys):
+    _due_and_rot(tmp_path, monkeypatch)
+    rc, out = _queue(capsys)
+    assert rc == 0
+    rows = [ln for ln in out.splitlines() if ln.startswith("- [ ] ")]
+    assert len(rows) == 2
+    due = next(r for r in rows if "#1 " in r)
+    rot = next(r for r in rows if "#2 " in r)
+    assert "Due scar" in due and "src/live/" in due
+    assert "review_after 2020-01-01" in due
+    assert "Suggested:" in due and "scar archive 1" in due
+    assert "Rotted scar" in rot and "partial rot" in rot
+    assert "Suggested: `scar reanchor`" in rot
+
+
+def test_review_queue_merges_states_into_one_row(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _write(tmp_path, "0003-both.landmine.md", id=3, title="Both",
+           anchors=["src/live/", "src/gone/"], extra="review_after: 2020-01-01\n")
+    _commit(tmp_path)
+    _, out = _queue(capsys)
+    rows = [ln for ln in out.splitlines() if "#3 " in ln]
+    assert len(rows) == 1
+    assert "partial rot" in rows[0] and "review_after 2020-01-01" in rows[0]
+
+
+def test_review_queue_never_prints_body_or_violation(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _write(tmp_path, "0004-v.landmine.md", id=4, title="Violating",
+           anchors=["src/live/", "src/gone/"],
+           extra="violation: 'LEAKY_REGEX_\\d+'\n",
+           body="SECRET-BODY-TEXT")
+    _commit(tmp_path)
+    _, out = _queue(capsys)
+    assert "#4" in out
+    assert "SECRET-BODY-TEXT" not in out
+    assert "LEAKY_REGEX" not in out
+    assert "evidence" not in out.lower()
+
+
+def test_review_queue_excludes_firing_log_signals(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _write(tmp_path, "0005-n.landmine.md", id=5, title="Healthy",
+           anchors=["src/live/"], extra="review_after_firings: 1\n")
+    _commit(tmp_path)
+    _, out = _queue(capsys)
+    assert out == ""
+
+
+def test_review_queue_notes_firing_log_exclusion_when_non_empty(tmp_path, monkeypatch, capsys):
+    _due_and_rot(tmp_path, monkeypatch)
+    _, out = _queue(capsys)
+    last = out.rstrip("\n").splitlines()[-1]
+    assert "firing" in last.lower()
+
+
+def test_review_queue_plain_even_on_tty(tmp_path, monkeypatch, capsys):
+    from scar import output
+    _due_and_rot(tmp_path, monkeypatch)
+    monkeypatch.setattr(output, "is_tty", lambda: True)
+    _, out = _queue(capsys)
+    assert "\x1b[" not in out
+    assert "- [ ] #1 " in out
+
+
+def test_review_queue_does_not_change_exit_codes(tmp_path, monkeypatch, capsys):
+    _due_and_rot(tmp_path, monkeypatch)
+    rc, _ = _queue(capsys, "--fail-partial-rot")
+    assert rc == 1
+    assert main(["lint", "--fail-partial-rot"]) == 1
+
+
+def test_review_queue_has_no_em_dash(tmp_path, monkeypatch, capsys):
+    _due_and_rot(tmp_path, monkeypatch)
+    _, out = _queue(capsys)
+    assert "\u2014" not in out

{scar_cli-0.26.0 → scar_cli-0.27.0}/uv.lock

@@ -297,7 +297,7 @@ wheels = [
 
 [[package]]
 name = "scar-cli"
-version = "0.26.0"
+version = "0.27.0"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },

{scar_cli-0.26.0 → scar_cli-0.27.0}/website/docs/agents.md

@@ -183,6 +183,60 @@ scar lint                                     # format, dead tripwires, overdue
 
 Advisory by default everywhere; CI opts into strictness explicitly.
 
+### Review queue
+
+Orphans, partial rot, symbol drift, unreachable evidence, revivals and passed `review_after` dates all end in a red job or a terminal warning that nobody owns. `scar lint --review-queue` turns them into one markdown checklist, one row per scar, and a scheduled workflow keeps a single rolling issue in sync with it:
+
+```bash
+scar lint --review-queue
+# - [ ] #7 One anchor alive, one rotted (src/live/): partial rot (dead anchor among live ones). Suggested: `scar reanchor`
+```
+
+The output is plain text with no scar bodies, evidence or violation patterns: only id, title, path, state and a suggested command. When nothing needs review it prints nothing and exits 0. Exit codes follow the usual gates (`--fail-orphans` and friends), the flag only changes what is printed. The firing-log signals (firing review, never fired) are left out on purpose: that log lives on each developer's machine and is empty on a CI checkout.
+
+```yaml
+# .github/workflows/scar-review-queue.yml
+name: Scar review queue
+on:
+  schedule:
+    - cron: '0 7 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  queue:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # evidence-reachability checks need full history
+      - uses: astral-sh/setup-uv@v5
+      - name: Build the queue
+        run: uvx --from scar-cli scar lint --review-queue > queue.md
+      - name: Sync the rolling issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          label=scar-review-queue
+          gh label create "$label" --color BFD4F2 --description "Rolling Scar review queue" 2>/dev/null || true
+          number=$(gh issue list --label "$label" --state all --limit 1 --json number --jq '.[0].number // empty')
+          if [ -s queue.md ]; then
+            if [ -z "$number" ]; then
+              gh issue create --title "Scar review queue" --label "$label" --body-file queue.md
+            else
+              gh issue edit "$number" --body-file queue.md
+              gh issue reopen "$number" 2>/dev/null || true
+            fi
+          elif [ -n "$number" ]; then
+            gh issue close "$number" --comment "Review queue is empty." 2>/dev/null || true
+          fi
+```
+
+The issue is rewritten from scar's output on every run, never duplicated, closed when the queue is empty and reopened when it is not. Its visibility follows the repository's: on a public repo the titles and file paths in the checklist are public too.
+
 ## Machine-readable docs
 
 Agents reading these docs programmatically: fetch [`/llms.txt`](pathname:///Scar/llms.txt) for a plain-text index of every page with stable URLs, plus the changelog.

scar_cli-0.26.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.26.0"
-}