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

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

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

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.27.1](https://github.com/Daily-Nerd/Scar/compare/v0.27.0...v0.27.1) (2026-11-07)
+
+
+### Bug Fixes
+
+* **lint:** list scars with lint errors in the review queue and sync before failing ([#360](https://github.com/Daily-Nerd/Scar/issues/360)) ([cc23232](https://github.com/Daily-Nerd/Scar/commit/cc23232194e1e1b7daa319a5b73a35e4eba8c801))
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scar-cli
-Version: 0.26.0
+Version: 0.27.1
 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.1}/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.1}/plugin/plugin.json

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "scar-cli"
-version = "0.26.0"
+version = "0.27.1"
 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.1}/src/scar/cli.py

@@ -546,6 +546,94 @@ 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 and not data["failed_files"]:
+        return ""
+    lines = []
+    # Files with lint errors (unparseable, or parseable but failing an error
+    # rule such as duplicate ids) come first and are keyed by relative path (a
+    # broken file may have no usable id or title). Only
+    # the path and fixed wording are printed, never lint messages or the body.
+    for rel in sorted(data["failed_files"]):
+        lines.append(f"- [ ] `{rel}`: file has lint errors. "
+                     "Suggested: run `scar lint` locally and fix them")
+    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}")
+    tail = ["", "Firing-log signals (firing review, never fired) are not included: "
+                "the firing log is machine-local and empty in CI."]
+    # GitHub rejects issue bodies over 65536 characters. Scar owns the cap so
+    # no consumer has to: drop trailing rows and say how many were omitted.
+    def omit_line(n: int) -> list[str]:
+        return [f"... {n} more row(s) omitted to fit GitHub's issue body limit. "
+                "Run `scar lint` locally for the full list."] if n else []
+
+    kept = len(lines)
+    while kept and len("\n".join(
+            lines[:kept] + omit_line(len(lines) - kept) + tail)) + 1 > _QUEUE_BODY_LIMIT:
+        kept -= 1
+    return "\n".join(lines[:kept] + omit_line(len(lines) - kept) + tail) + "\n"
+
+
+# Under GitHub's 65536-character issue body cap, with headroom.
+_QUEUE_BODY_LIMIT = 65000
+
+
 def _cmd_lint(args) -> int:
     store = _require_store()
     if store is None:
@@ -733,6 +821,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 +851,8 @@ def _cmd_lint(args) -> int:
         "unreachable_evidence": [{"scar_id": ue.scar_id, "sha": ue.sha, "reason": ue.reason}
                                  for ue in unreachable],
         "failed": failed,
+        "failed_files": sorted(failed_files),
+        "review_due": _review_due_json(review_due),
     }
 
     def plain():
@@ -809,8 +900,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 +925,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 +944,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 +3211,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.1}/tests/test_docs.py

@@ -36,3 +36,21 @@ 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
+    # #359: the sync must not be skipped by lint's exit code, and failures of
+    # the gh calls must not be swallowed.
+    recipe = text.split("### Review queue")[1].split("## Machine-readable")[0]
+    assert "set +e" in recipe and "status=$?" in recipe
+    assert "2>/dev/null" not in recipe and "|| true" not in recipe
+    assert "lint errors" in recipe
+    assert "\u2014" not in text.split("### Review queue")[1].split("## Machine-readable")[0]

{scar_cli-0.26.0 → scar_cli-0.27.1}/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.1/tests/test_review_queue.py

@@ -0,0 +1,243 @@
+"""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
+
+
+def _broken(root, name="0009-broken.landmine.md", marker="BROKEN-BODY-TEXT"):
+    # No frontmatter terminator and no required fields: lint_text errors.
+    (root / ".scars" / name).write_text(f"---\nid: 9\ntitle: {marker}\n\n{marker}\n")
+
+
+def test_review_queue_lists_broken_file_and_still_exits_1(tmp_path, monkeypatch, capsys):
+    """#359: a file with lint errors must be in the queue."""
+    _due_and_rot(tmp_path, monkeypatch)
+    _broken(tmp_path)
+    rc, out = _queue(capsys)
+    assert rc == 1
+    assert "- [ ] `.scars/0009-broken.landmine.md`: file has lint errors." in out
+    assert "scar lint" in out
+
+
+def test_review_queue_only_broken_file_is_non_empty(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _broken(tmp_path)
+    rc, out = _queue(capsys)
+    assert rc == 1
+    assert out.strip() != ""
+    assert len([r for r in out.splitlines() if r.startswith("- [ ]")]) == 1
+
+
+def test_review_queue_broken_row_never_leaks_body_or_message(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _broken(tmp_path)
+    data_rc = main(["lint", "--json"])
+    msgs = [f["message"] for f in json.loads(capsys.readouterr().out)["findings"]]
+    assert data_rc == 1 and msgs
+    _, out = _queue(capsys)
+    assert "BROKEN-BODY-TEXT" not in out
+    for m in msgs:
+        assert m not in out
+
+
+def test_review_queue_broken_rows_are_sorted_by_path(tmp_path, monkeypatch, capsys):
+    _repo(tmp_path, monkeypatch)
+    _broken(tmp_path, "0012-b.landmine.md")
+    _broken(tmp_path, "0010-a.landmine.md")
+    _, out = _queue(capsys)
+    rows = [r for r in out.splitlines() if r.startswith("- [ ]")]
+    assert "0010-a" in rows[0] and "0012-b" in rows[1]
+
+
+def test_review_queue_truncates_to_issue_body_limit(tmp_path, monkeypatch, capsys):
+    """GitHub rejects issue bodies over 65536 characters (#359)."""
+    _repo(tmp_path, monkeypatch)
+    for i in range(1200):
+        _broken(tmp_path, f"{3000 + i}-{'x' * 40}.landmine.md")
+    rc, out = _queue(capsys)
+    assert rc == 1
+    assert len(out) <= 65536
+    assert "more row(s) omitted" in out
+    assert out.count("- [ ]") < 1200
+
+
+def test_review_queue_lists_duplicate_id_scars_that_parse(tmp_path, monkeypatch, capsys):
+    """Duplicate ids parse fine (and can fire) but are lint errors: both get rows."""
+    _repo(tmp_path, monkeypatch)
+    _write(tmp_path, "0001-a.landmine.md", id=1, title="A", anchors=["src/live/"])
+    _write(tmp_path, "0002-b.landmine.md", id=1, title="B", anchors=["src/live/"])
+    _commit(tmp_path)
+    rc, out = _queue(capsys)
+    assert rc == 1
+    assert "`.scars/0001-a.landmine.md`: file has lint errors." in out
+    assert "`.scars/0002-b.landmine.md`: file has lint errors." in out
+    assert "duplicate id" not in out

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

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

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

@@ -183,6 +183,71 @@ 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. Scar files with lint errors are listed too, by path, with no lint message text. Exit codes are unchanged: lint still exits 1 when any file has an error, and `--fail-orphans` and friends still apply. The output is capped below GitHub's issue body limit, with a final line saying how many rows were omitted. 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
+        # Keep lint's exit code, but let the next step run first: each run
+        # step is bash -e, so a bare failure would skip the issue sync.
+        run: |
+          set +e
+          uvx --from scar-cli scar lint --review-queue > queue.md
+          echo "status=$?" >> "$GITHUB_ENV"
+          exit 0
+      - 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" --force
+          issue=$(gh issue list --label "$label" --state all --limit 1 --json number,state)
+          number=$(jq -r '.[0].number // empty' <<<"$issue")
+          state=$(jq -r '.[0].state // empty' <<<"$issue")
+          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
+              if [ "$state" = "CLOSED" ]; then gh issue reopen "$number"; fi
+            fi
+          elif [ -n "$number" ] && [ "$state" = "OPEN" ]; then
+            gh issue close "$number" --comment "Review queue is empty."
+          fi
+      - name: Fail the job if lint failed
+        if: env.status != '0'
+        run: exit 1
+```
+
+The queue step records lint's exit code instead of failing, the issue is synced, and the last step fails the job when lint did, so CI stays red and the issue stays current. 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"
-}