scar-cli 0.23.0__tar.gz → 0.25.0__tar.gz

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

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

{scar_cli-0.23.0 → scar_cli-0.25.0}/.scars/0001-git-grep-ere-pitfalls.landmine.md

@@ -10,7 +10,7 @@ anchors:
   - path: experiments/anchor-survival/
   - path: src/scar/harvest.py
   - pattern: "git.{0,20}grep"
-violation: "git.{0,60}grep.{0,120}\\b"
+violation: "git[^#\n]{0,60}grep[^#\n]{0,80}[\x22\x27][^\x22\x27#\n]{0,40}\\b"
 evidence:
   - note: "orphaned receipt — pre-v0.1.0 commit 5c63b14 produced a fake 0% anchor-survival run before diagnosis (gate 0.2); resolves at github.com/Daily-Nerd/Scar/commit/5c63b14 until GC, not in fresh clones (rewritten at the v0.1.0 release)"
 expires:

{scar_cli-0.23.0 → scar_cli-0.25.0}/.scars/0005-history-rewrite-orphans-commit-evidence.landmine.md

@@ -8,8 +8,13 @@ created: 2026-06-11
 authors: ["claude-code", "Kibukx"]
 anchors:
   - path: .scars/
+  - command: "git push.*--force"
+  - command: "git rebase"
+  - command: "git filter-repo|git filter-branch"
+  - command: "git commit.*--amend"
 violation: "commit: [0-9a-f]{7,40}"
 evidence:
+  - note: "2026-09-05 anchors: path .scars/ KEPT on purpose. The violation tripwire commit: [0-9a-f]{7,40} only evaluates on files an anchor matched, so dropping it to cut firings would silently disarm the scar. Command anchors added instead, so the history-rewrite half fires on the act rather than on any scar edit"
   - 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"

{scar_cli-0.23.0 → scar_cli-0.25.0}/.scars/0006-yaml-pattern-anchor-over-escaping.landmine.md

@@ -9,8 +9,9 @@ authors: ["claude-code", "kibukx"]
 anchors:
   - path: src/scar/orphan.py
   - path: src/scar/match.py
-  - path: .scars/
+  - pattern: "\n\s*-\s*pattern:"
 evidence:
+  - note: "2026-09-05 anchors: path .scars/ replaced by a pattern matching a scar frontmatter pattern: entry. The directory anchor fired on every scar edit, while the hazard only exists when a pattern anchor is being authored"
   - pr: 40
   - note: scar 1 grep pattern matched only its own body, never experiments/anchor-survival/RESULTS.md
 expires:

{scar_cli-0.23.0 → scar_cli-0.25.0}/.scars/0008-rich-output-nontty-must-bypass-rich.landmine.md

@@ -7,10 +7,10 @@ confidence: 0.9
 created: 2026-06-30
 authors: ["claude-code", "kibukx"]
 anchors:
-  - path: src/scar/cli.py
   - path: src/scar/output.py
-  - pattern: "output\.render\("
+  - pattern: "def plain\(\):"
 evidence:
+  - note: "2026-09-05 anchors: path src/scar/cli.py dropped, it is 3000+ lines and the tty gate is 17 of them. The 18 output.render( call sites only invoke the already-safe dispatcher, so that pattern is replaced by def plain():, which marks the 14 non-tty contract closures this scar actually protects"
   - issue: 78
   - note: 187-test suite asserts plain substrings like '0001-bad.deadend.md' and long anchor paths on main([...]) under capsys
 expires:

{scar_cli-0.23.0 → scar_cli-0.25.0}/.scars/0011-lint-compile-check-lets-redos-anchors-hang-hotpath.landmine.md

@@ -7,11 +7,11 @@ confidence: 0.9
 created: 2026-06-30
 authors: ["claude-code", "Kibukx"]
 anchors:
-  - path: src/scar/lint.py
-  - path: src/scar/match.py
   - pattern: "rx\.search\("
   - pattern: "MAX_ANCHOR_SCAN"
+  - pattern: "_is_redos_prone"
 evidence:
+  - note: "2026-09-05 anchors: both whole-file path anchors dropped, lint.py and match.py serve many concerns beyond ReDoS. _is_redos_prone added so the GATE itself stays anchored, since the body says the gate is the defense and the 64 KiB cap is not"
   - issue: 88
 expires:
   condition: "lint gains full regex-safety analysis OR the matcher runs on a hardened regex engine with a hard timeout"

scar_cli-0.23.0/.scars/candidates/cascade-block-exit-collides-with-argparse.md → scar_cli-0.25.0/.scars/0023-cascade-block-exit-collides-with-argparse.fence.md

@@ -1,22 +1,24 @@
 ---
-id: 0
+id: 23
 type: fence
 title: Cascade's block code is 2, and so is argparse's error code — never exit 2 directly from cascade-hook
 severity: high
 confidence: 0.9
 created: 2026-08-04
 authors: ["claude-code"]
+promoted_by: Kibukx
+promoted_by_source: explicit
 anchors:
   - path: src/scar/cascade.py
   - path: src/scar/installer.py
   - pattern: "cascade-hook"
 evidence:
   - issue: 197
-  - note: ".windsurf/hooks.json is committed and workspace-level, so a teammate on an older scar-cli runs whatever command string we wrote"
+  - note: .windsurf/hooks.json is committed and workspace-level, so a teammate on an older scar-cli runs whatever command string we wrote
 expires:
   condition: "Cascade gains a non-blocking context channel (an additionalContext equivalent), so blocking is no longer the injection path at all"
   review_after: 2027-02-04
-status: candidate
+status: active
 ---
 
 `scar cascade-hook` signals "block this action" with sentinel exit code 20,

scar_cli-0.25.0/.scars/0024-host-detection-must-not-read-the-process-home.deadend.md

@@ -0,0 +1,42 @@
+---
+id: 24
+type: deadend
+title: Host detection must take home from installer.CLAUDE_DIR, never Path.home() — a bare call passes locally and fails every other machine
+severity: high
+confidence: 0.9
+created: 2026-09-07
+authors: ["claude-code"]
+promoted_by: Kibukx
+promoted_by_source: explicit
+anchors:
+  - pattern: "detect_hosts\("
+  - symbol: src/scar/cli.py::_detect
+evidence:
+  - issue: 318
+  - note: 2026-09-07, during the multi-host skill install work: the skill-install refusal resolved home with Path.home(). Under HOME=empty the suite went 1031 passed / 2 FAILED, both PRE-EXISTING tests, printing 'claude not detected on this machine, nothing written'. Fixed by reusing _detect(). Branch SHAs deliberately omitted: scar #5 fired on the amend that wrote this, and squash-merge would orphan them.
+expires:
+  condition: "detect_hosts takes home from one injected seam no caller can bypass"
+  review_after: 2027-03-08
+status: active
+---
+
+`Path.home()` in a detection path looks obviously right and is a trap. Tests
+patch `installer.CLAUDE_DIR`, not the environment, and `_detect()` derives
+home from `installer.CLAUDE_DIR.parent`. A bare call reads the author's real
+home, finds their real `~/.claude`, and passes. On any machine without one,
+every CI runner included, detection returns nothing and the caller refuses.
+
+The failure is invisible where it is introduced: the suite was fully green on
+the authoring machine, and the tests that finally failed were pre-existing
+ones nobody had touched. Use `_detect(kind)`, or `installer.CLAUDE_DIR.parent`
+exactly as `_detect` does. Never add a second answer to where home is.
+
+Two anchors on purpose. `cli.py` is 143 KiB and its first `detect_hosts(` sits
+at byte ~123,000, past the 64 KiB `MAX_ANCHOR_SCAN` bound, so the pattern is
+blind to the very file the defect landed in. The `symbol:` anchor covers it,
+at the cost of needing `scar-cli[symbols]`. Lint reports neither gap: the
+pattern matches `hosts.py`, so the scar reads live while blind where it counts.
+
+Not armed. The obvious tripwire is `Path\.home\(\)`, but `cli.py` carries that
+string in a warning comment and `installer.py` uses it correctly for module
+constants, so it would fire on prose and on correct code.

scar_cli-0.23.0/.scars/candidates/one-plugin-hook-manifest-two-hosts-two-root-variables.md → scar_cli-0.25.0/.scars/0025-one-plugin-hook-manifest-two-hosts-two-root-variables.landmine.md

@@ -1,11 +1,13 @@
 ---
-id: 0
+id: 25
 type: landmine
 title: A plugin hook manifest is read by every host that installs the plugin, and hosts expand different root variables
 severity: high
 confidence: 0.9
 created: 2026-09-03
 authors: ["claude-code"]
+promoted_by: Kibukx
+promoted_by_source: explicit
 anchors:
   - path: plugin/
   - path: src/scar/installer.py
@@ -16,7 +18,7 @@ evidence:
 expires:
   condition: "the plugin format gains per-host scoping for hook files"
   review_after: 2026-12-01
-status: candidate
+status: active
 ---
 
 Claude Code merges plugin.json hooks with hooks/hooks.json and defines only

scar_cli-0.25.0/.scars/0026-path-anchor-breadth-drives-the-review-due-threshold.landmine.md

@@ -0,0 +1,39 @@
+---
+id: 26
+type: landmine
+title: A whole-file or whole-directory path anchor makes the review-due threshold report anchor breadth, not code hazard
+severity: medium
+confidence: 0.8
+created: 2026-09-04
+authors: ["claude-code"]
+promoted_by: Kibukx
+promoted_by_source: explicit
+anchors:
+  - path: SCAR-FORMAT.md
+  - pattern: "review_after_firings"
+evidence:
+  - issue: 312
+  - note: triage of all five over-threshold scars in this repo on 2026-09-04: four were over-anchored, one was a real code fix
+expires:
+  condition: "lint reports what share of a scar's firings touched the hazard, so the review-due warning can distinguish breadth from recurrence"
+  review_after: 2027-03-04
+status: active
+---
+
+`scar lint` warns past `review_after_firings` that either the guarded code
+merits the fix or the scar merits revision. Read literally that sends you to
+the code first. It is usually the anchor.
+
+A `path:` anchor is a repo-relative PREFIX, so it fires on every edit beneath
+it. Scar #8 guards a 17-line tty branch inside a 52-line module but anchored
+the whole 3,090-line `src/scar/cli.py`; roughly nine of every ten of its 47
+firings touched nothing related. Scar #5 guards against history rewrites and
+anchored all of `.scars/`, so it fired on 22 routine promotions and zero
+force-pushes, which is zero of its actual trigger events.
+
+A firing count therefore measures anchor breadth first and hazard recurrence
+second, and the two are not separable from the log. Before reading a
+review-due warning as evidence that code needs fixing, check what share of the
+firings touched the hazard at all. Then narrow the anchor to the smallest file
+holding the branching, or switch to a `command:` anchor when the trigger is an
+action rather than a file (#312 is the one case here that really was the code).

{scar_cli-0.23.0 → scar_cli-0.25.0}/AGENTS.md

@@ -26,8 +26,11 @@ The full authoring contract — qualification criteria, the candidates-only writ
 path, mandatory YAML frontmatter, and the regex over-escaping trap — is packaged
 as the `scar-authoring` skill.
 
-- **Claude Code:** install the plugin (recommended) or `scar skill install` to
-  drop the skill into `~/.claude/skills/`. It auto-loads on trigger.
+- **Claude Code, Codex, Cursor, opencode, Windsurf:** `scar skill install`
+  detects which of those hosts are on the machine and writes the skill to each
+  one's native skills directory. On Claude Code the plugin is the recommended
+  route and carries the same skill. The per-host destination table is in
+  [website/docs/agents.md](website/docs/agents.md).
 - **MCP agents (Cursor/Windsurf/opencode):** the `scar_draft` tool enforces the
   candidates-only path and lints before writing; its description carries the
   digest.

{scar_cli-0.23.0 → scar_cli-0.25.0}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.25.0](https://github.com/Daily-Nerd/Scar/compare/v0.24.0...v0.25.0) (2026-10-06)
+
+
+### Features
+
+* **firing-log:** record which anchor kinds matched each scar ([#335](https://github.com/Daily-Nerd/Scar/issues/335)) ([#339](https://github.com/Daily-Nerd/Scar/issues/339)) ([aa6b719](https://github.com/Daily-Nerd/Scar/commit/aa6b719089d504fce045052598e8d93ef1832fd7))
+* **lint:** warn on a violation that cannot arm, dead candidate anchors, and broad patterns ([#325](https://github.com/Daily-Nerd/Scar/issues/325)) ([#328](https://github.com/Daily-Nerd/Scar/issues/328)) ([b3b3224](https://github.com/Daily-Nerd/Scar/commit/b3b3224c31a6b29f9d253290dd0e7bf99e1e7e56))
+* **render:** header names the pre-cap total when the cap cut scars ([#322](https://github.com/Daily-Nerd/Scar/issues/322)) ([fc3754b](https://github.com/Daily-Nerd/Scar/commit/fc3754beef137d1d51bf0079d8172765a0277c73))
+* **sweep:** run every armed violation over the whole tree and report live hits ([#326](https://github.com/Daily-Nerd/Scar/issues/326)) ([#329](https://github.com/Daily-Nerd/Scar/issues/329)) ([ecbd159](https://github.com/Daily-Nerd/Scar/commit/ecbd1597db6536d801a05c80a69fa1bd3e945ccc))
+
+
+### Bug Fixes
+
+* **lint:** report duplicate scar ids, and stop the matcher dropping one ([#327](https://github.com/Daily-Nerd/Scar/issues/327)) ([210f4c7](https://github.com/Daily-Nerd/Scar/commit/210f4c77197fa603d8659f9717ef8350277fc6f8))
+* **match:** symbol anchor is a content signal only when the edit mentions the symbol ([#338](https://github.com/Daily-Nerd/Scar/issues/338)) ([0a1aac6](https://github.com/Daily-Nerd/Scar/commit/0a1aac63c8118fb3701c56fd6a9c03de08fe3581))
+* **orphan:** count symbol anchors in orphan detection and report one that no longer resolves ([#337](https://github.com/Daily-Nerd/Scar/issues/337)) ([#342](https://github.com/Daily-Nerd/Scar/issues/342)) ([321f9de](https://github.com/Daily-Nerd/Scar/commit/321f9de04f18630d6354ee6cd204b0dba67f0bda))
+
+
+### Documentation
+
+* **anchors:** say path anchors are prefixes, and teach the skill when to use symbol anchors ([#340](https://github.com/Daily-Nerd/Scar/issues/340)) ([7babb9f](https://github.com/Daily-Nerd/Scar/commit/7babb9face9116f9dfa5884a14cefdeb6b9bee90))
+
+## [0.24.0](https://github.com/Daily-Nerd/Scar/compare/v0.23.0...v0.24.0) (2026-09-08)
+
+
+### Features
+
+* **firing-log:** one shared validated reader for the firing log ([#313](https://github.com/Daily-Nerd/Scar/issues/313)) ([d316922](https://github.com/Daily-Nerd/Scar/commit/d31692205715e63380b8ac104643de4ceac0338d))
+* **skill:** install the authoring skill to every detected host ([#320](https://github.com/Daily-Nerd/Scar/issues/320)) ([1d9c985](https://github.com/Daily-Nerd/Scar/commit/1d9c985e3e5815ba67d222defa86d549886c7e94))
+
+
+### Bug Fixes
+
+* **promote:** record whether a promotion happened at a terminal ([#315](https://github.com/Daily-Nerd/Scar/issues/315)) ([f28e8eb](https://github.com/Daily-Nerd/Scar/commit/f28e8eb90a5fb3161aa40565dbfb218d1b9b4160)), closes [#308](https://github.com/Daily-Nerd/Scar/issues/308)
+
 ## [0.23.0](https://github.com/Daily-Nerd/Scar/compare/v0.22.0...v0.23.0) (2026-09-03)
 
 

{scar_cli-0.23.0 → scar_cli-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scar-cli
-Version: 0.23.0
+Version: 0.25.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -80,6 +80,8 @@ scar skill install               # same detection for the scar-authoring skill
 scar hook status                 # every host with the channel that serves it (settings, plugin, none)
 ```
 
+`scar skill install` writes the scar-authoring skill to a native path for Claude Code, Codex, Cursor, opencode, or Windsurf. Claude Code is the one confirmed to load it, and the rest are written per vendor documentation but unverified: see the [per-host table](https://daily-nerd.github.io/Scar/agents#where-scar-skill-install-writes) for which is which.
+
 Claude Code users: the marketplace **plugin** ships the hooks and the scar-authoring skill together. `scar hook install` and `scar skill install` see the plugin and skip Claude unless you pass `--runtime claude --force`. Re-run `scar skill install` after upgrading a manual install; the installed skill is a static copy.
 
 Codex users: run `scar hook install --runtime codex`, then open `/hooks` in Codex to review and trust the entries. The hooks push matching scars before `Bash` and `apply_patch` calls and report post-patch `violation:` tripwires without blocking. The plugin no longer carries Codex hook definitions; the installer is the one path.

{scar_cli-0.23.0 → scar_cli-0.25.0}/README.md

@@ -65,6 +65,8 @@ scar skill install               # same detection for the scar-authoring skill
 scar hook status                 # every host with the channel that serves it (settings, plugin, none)
 ```
 
+`scar skill install` writes the scar-authoring skill to a native path for Claude Code, Codex, Cursor, opencode, or Windsurf. Claude Code is the one confirmed to load it, and the rest are written per vendor documentation but unverified: see the [per-host table](https://daily-nerd.github.io/Scar/agents#where-scar-skill-install-writes) for which is which.
+
 Claude Code users: the marketplace **plugin** ships the hooks and the scar-authoring skill together. `scar hook install` and `scar skill install` see the plugin and skip Claude unless you pass `--runtime claude --force`. Re-run `scar skill install` after upgrading a manual install; the installed skill is a static copy.
 
 Codex users: run `scar hook install --runtime codex`, then open `/hooks` in Codex to review and trust the entries. The hooks push matching scars before `Bash` and `apply_patch` calls and report post-patch `violation:` tripwires without blocking. The plugin no longer carries Codex hook definitions; the installer is the one path.

{scar_cli-0.23.0 → scar_cli-0.25.0}/SCAR-FORMAT.md

@@ -43,7 +43,7 @@ is deliberate: consumers in hook hot-paths parse with zero dependencies.
 | `created` | yes | ISO date | |
 | `authors` | yes | inline list | who drafted it: agents as `"claude-code"` etc. The reviewer is no longer appended here |
 | `promoted_by` | active scars | string | the human who promoted it. Written only by `scar promote`, which overwrites anything a candidate carried. Empty on scars promoted before the field existed, and never inferred from `authors` |
-| `promoted_by_source` | optional | `explicit` \| `git-config` | whether `promoted_by` came from `--reviewer` or from `git config user.name`. Written only alongside `promoted_by`, never on its own. Absent on scars promoted before the field existed |
+| `promoted_by_source` | optional | `explicit` \| `git-config-interactive` \| `git-config` | how strongly `promoted_by` is evidenced. `explicit` = a name was typed with `--reviewer`. `git-config-interactive` = no name typed, but `promote` ran at a terminal, so a person was there. `git-config` = no name typed and no terminal recorded, which is the unattended shape `lint` warns on. Written only alongside `promoted_by`, never on its own. Absent on scars promoted before the field existed, and plain `git-config` on scars promoted before interactivity was recorded, so neither absence proves an agent did it |
 | `anchors` | yes, ≥1 | list of `- path:`, `- pattern:`, `- symbol:`, and/or `- command:` | §4 |
 | `evidence` | recommended | list of `- commit:`/`- pr:`/`- issue:`/`- incident:`/`- note:`/`- url:` | absent ⇒ challengeable on sight; `issue:`/`url:` are durable forms that survive squash-merge |
 | `expires.condition` | recommended | quoted string | what change obsoletes this scar |

{scar_cli-0.23.0 → scar_cli-0.25.0}/SPEC.md

@@ -59,6 +59,8 @@ Do not reintroduce Redis (or any evicting store) for sessions unless sessions
 become stateless/re-derivable. Postgres-backed sessions are intentional.
 ```
 
+An `id` identifies one scar. `scar lint` reports an id carried by more than one numbered scar file as an error on each of them (two branches that each promote a candidate both take the next number), naming the other files and the next free id. It does not renumber: firing-log rows and evidence notes already reference the number, so which scar keeps it is a human call. Candidates are not checked: promotion assigns their id, and they never fire.
+
 ### Type semantics
 
 - **`deadend`** — protects against *re-attempting an approach*. Primary anchor is often a `pattern` (the approach reappearing anywhere), not a location.
@@ -71,18 +73,20 @@ The hard technical problem. Line numbers are dead on arrival; file paths die on
 
 Four anchor classes, used in combination:
 
-1. **Path anchors** — file or directory globs. Cheap, survive content change, die on rename (mitigated by git rename tracking during re-anchor).
+1. **Path anchors** — file or directory prefixes. A directory with a trailing slash or a file path both work; wildcards are not expanded. Cheap, survive content change, die on rename (mitigated by git rename tracking during re-anchor).
 2. **Symbol anchors** — function/class/method names resolved via tree-sitter. Survive moves within and across files in the same repo. Primary anchor class for fences.
+   For orphan detection (#337) a symbol anchor is live while its definition resolves: `path::name` in that file, a bare name in any tracked file the `[symbols]` extra can parse. Without the extra it cannot be checked, so it holds the scar alive the way a command anchor does, and `scar lint` prints one `symbols-unchecked` hint per run.
 3. **Pattern anchors** — regex/AST patterns over *new* code (diff-scoped, not whole-repo). The only anchor class that can catch a dead end being re-attempted in a brand-new file. Powers `deadend` enforcement.
 4. **Command anchors** (#175) — regexes over a *shell command about to execute* (`PreToolUse:Bash` and `scar inject --command`). The only anchor class with a firing surface for run-a-command mistakes — knowledge like "bare `uv sync` strips extras" has no edit to anchor to. Never matched against paths or content (structurally immune to self-match/partial-rot) and exempt from content liveness; `review_after` is the freshness mechanism.
 
-Plus a **content fingerprint** (normalized-token hash of the protected region) used not for matching but for *drift detection*: fingerprint drift is an advisory warning surfaced by `scar orphan` and `scar lint`. The `orphaned` transition itself is driven by the location anchors — a scar orphans when all of its path/pattern anchors go dead — and surfaces in `scar status` and CI as "this knowledge has come loose — re-anchor or archive." Orphaned ≠ deleted, ever.
+Plus a **content fingerprint** (normalized-token hash of the protected region) used not for matching but for *drift detection*: fingerprint drift is an advisory warning surfaced by `scar orphan` and `scar lint`. The `orphaned` transition itself is driven by the location anchors (a scar orphans when all of its path/pattern/symbol anchors go dead) and surfaces in `scar status` and CI as "this knowledge has come loose: re-anchor or archive." Orphaned ≠ deleted, ever.
 
 ## 3. CLI surface (v0)
 
 ```
 scar init                 # create .scars/ with a seeded example candidate; installs nothing (hooks are explicit: scar hook install)
 scar check <path|diff>    # scars relevant to a path or staged diff; exit code for CI
+scar sweep                # run every armed violation over the whole tree; read-only, exit 0 unless --exit-code
 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/
@@ -117,7 +121,7 @@ Also `PostToolUse`/stop-hook prompt: *"You appear to have abandoned approach X a
 
 ### 4.3 Ranking and the fatigue budget
 
-Hard rule: **max 3 scars injected per edit, max ~120 words each.** A scar system that warns constantly is a scar system that gets uninstalled. Ranking: `severity_weight × confidence × anchor_specificity`, sorted descending (`confidence` is the static authored weight — see §5). Everything else is reachable via `scar why` but not pushed.
+Hard rule: **max 3 scars injected per edit, max ~120 words each.** A scar system that warns constantly is a scar system that gets uninstalled. Ranking: `severity_weight × confidence × anchor_specificity`, sorted descending (`confidence` is the static authored weight, see §5). Everything else is reachable via `scar why` but not pushed. The cut is never silent (#321): when more scars matched than the cap allows, the injection header reads `3 of 5 matched shown` (the count is distinct scars, taken before the cut). With no census the header makes no claim about a total, and when nothing was cut it is unchanged.
 
 ## 5. Lifecycle
 
@@ -167,8 +171,8 @@ All harvest output is `candidates/`, never active. Precision over recall: a harv
 
 ## 9. Machine-readable output contract
 
-Nine subcommands accept `--json`: `lint`, `status`, `check`, `why`, `stats`,
-`gc`, `orphan`, `reanchor`, `draft-check`. Two more are machine-mode by
+Ten subcommands accept `--json`: `lint`, `status`, `check`, `sweep`, `why`,
+`stats`, `gc`, `orphan`, `reanchor`, `draft-check`. Two more are machine-mode by
 design: `scar inject` (hook JSON or silence) and `scar brief --compact`.
 
 Everything in this section is a **promise to external consumers**. It exists
@@ -221,9 +225,10 @@ Top-level keys, and the keys of each object inside the listed arrays.
 
 | Command | Guaranteed top-level | Array item keys |
 |---|---|---|
-| `lint` | `files` int, `findings` array, `failed` int, `orphans`, `partial_rot`, `symbol_drift`, `revivals`, `reverse_hints`, `unreachable_evidence` arrays, `shallow_clone` bool | `findings[]`: `file`, `level`, `message` |
+| `lint` | `files` int, `findings` array, `failed` int, `orphans`, `partial_rot`, `symbol_drift`, `revivals`, `reverse_hints`, `unreachable_evidence` arrays, `symbols_unchecked` array of int, `shallow_clone` bool | `findings[]`: `file`, `level`, `message` |
 | `status` | `scars_dir` str, `active`, `challenged`, `candidates`, `review_due`, `orphan_detected`, `orphaned`, `partial_rot`, `broken` arrays, `counts` object | `active[]`: `id`, `type`, `severity`, `title`. `candidates[]` are strings. `counts`: `active`, `candidates`, `orphan_detected`, `orphaned`, `partial_rot`, `broken` |
 | `check` | `paths` array of str, `scars` array | `scars[]`: `id`, `type`, `severity`, `confidence`, `status`, `title`, `body` |
+| `sweep` | `files` int (tracked files swept), `skipped` int (tracked files with no readable content: oversized or binary), `scars` int (scars armed on at least one swept file), `hits` array | `hits[]`: `id` int, `type`, `severity`, `title`, `source` (scar file, repo-relative), `path`, `line` int (1-based), `excerpt` |
 | `why` | `path` str, `records` array | `records[]`: `id`, `type`, `status`, `title`, `file`, `body` |
 | `stats` | `repo` str, `total_firings` int, `per_scar` array, `most_fired` int, `last_fired` str, `never_fired` array of int, `demotions` int, `demotions_path_only` int, `demotions_cooldown` int, `demotions_reason_unknown` int, `census_known` int, `census_unknown` int, `cofires_per_edit` float **or null**, `edits_multi_fire` int, `path_only_ratio` float **or null**, `edits_observed` int, `injection_rate` float **or null**, `retrieval_misses` int **or null**, `instrument_disconnected` bool, `posttool_silent` bool, `last_fired_age_days` int, `armed_firings` int, `armed_unknown` int, `verdicts_expected` int, `verdicts_observed` int, `verdicts_unresolved` int, `verdicts_unplaceable` int, `firings_block_capable` int, `firings_advisory` int, `firings_block_unknown` int, `all_firings_advisory` bool, `firings_context_known` int, `firings_context_unknown` int, `command_firings` int, `firings_kind_unknown` int, `advisories` array. `window` object **only when `--since`/`--until` is given** | `per_scar[]`: `id`, `count`, `violations`. `window`: `since`, `until`, `excluded_undated` |
 | `gc` | `removed_markers` int, `dropped_firings` int, `dry_run` bool, `candidates` array, `fp_log` object | `candidates[]`: `name`, `age_days`. `fp_log`: `present`, `size`, `lines` |
@@ -373,8 +378,8 @@ CI, and never emits JSON.
 A scar rendered as a one-liner was demoted for one of two reasons, and they are
 opposite evidence. A **path-only** demotion means the anchor proved the file
 was in scope and nothing in the edit matched: a near miss. A **cooldown**
-demotion means the edit content matched (a pattern hit, a symbol resolved, a
-command matched) and the full body was withheld only because it had been shown
+demotion means the edit content matched (a pattern hit, a symbol the edit
+names, a command matched) and the full body was withheld only because it had been shown
 in the last four hours: a hit we chose not to repeat.
 
 `demoted_ids` lists both in one field. `demotion_reasons` records which is
@@ -402,9 +407,18 @@ never recoverable from the log.
 
 `matched` records what `_match_target` returned before `_select_top` truncated
 it: `{"total": n, "content": c, "path_only": p}` with `content + path_only ==
-total`. `content` matched the edit itself (a pattern hit, a symbol resolved, a
-command matched). `path_only` matched nothing but the file's location. The
-split is the same one the fatigue budget uses to tier, counted before it cuts.
+total`. `content` matched the edit itself (a pattern hit, a symbol the edit
+names, a command matched). `path_only` matched nothing but the file's location.
+The split is the same one the fatigue budget uses to tier, counted before it
+cuts.
+
+A symbol anchor yields one of two `matched_by` kinds. `symbol` means the file
+on disk defines the symbol and the edited text names it as a whole word (the
+innermost name, so `src/a.py::Store.save` looks for `save`); it is a content
+signal. `symbol_file` means the file defines the symbol but the edited text
+never names it; it counts as `path_only`, like a path anchor. The hook sees the
+new text without line numbers, so a name mention is the strongest proof
+available that the edit touched the symbol.
 
 The key is written by every shipped writer (edit, command, Codex, Cascade). It
 is **omitted** by a writer that did not count, never zeroed: zeros would claim
@@ -458,6 +472,18 @@ denominators changed.
 hook recorded **anything**, so command rows and kind-unknown rows answer it
 just as well as edit rows do.
 
+`matched_by` on a firing row says which anchor kinds matched each scar that
+fired, keyed by the scar id as a string, kinds in rank order:
+`{"24": ["path", "symbol"], "1": ["content_pattern"]}`. `scar_ids` says that a
+scar fired and `matched` is a census for the whole edit; neither says what a
+given scar matched on. The kinds are opaque strings copied from the matcher, so
+a new anchor kind appears here without a format change.
+
+Every scar that fired has a non-empty list. The key is **omitted**, never
+emptied, when a writer has no match objects in hand, and a MISSING `matched_by`
+means the row predates the field, never "no kinds". Readers must not treat its
+absence as a value.
+
 ### 9.4 Enforcement
 
 `tests/test_json_contract.py` asserts every guaranteed key above against live
@@ -468,3 +494,5 @@ ones that reach `main` wrong.
 ### 9.10 Install detection
 
 `scar hook install` and `scar skill install` without `--runtime` detect hosts (claude, codex, windsurf, cursor, opencode) by config directory or binary on PATH, and resolve for each the channel that already serves it: `settings` (Scar's own entries in the host's hook file), `plugin` (the scar marketplace plugin installed and not disabled), or `none`. windsurf is repo-scoped: its hooks file is written into the working repo, so the binary on PATH counts only when that repo is inside a git repository. On a terminal, one question per present, wirable, unserved host, default no. Without a terminal, exactly one such host is installed; zero or several means the commands are printed and nothing is written. Zero detected hosts says so, rather than naming the plugin. `--all` wires every such host. `--runtime claude` on a Claude Code already served by the plugin refuses unless `--force`. `--all` and `--force` apply to `install` only, and `--force` applies to `--runtime claude` only. A missing or unreadable plugin registry never counts as `plugin`.
+
+Two rules differ for the skill kind. windsurf is not repo-scoped there: its global skills live under home (`~/.codeium/windsurf/skills`), so the binary on PATH counts on its own, with no git-repo guard. And `scar skill install --runtime <host>` refuses, exit 1, when detection does not find that host on the machine, rather than creating a skill directory nothing reads. Every destination resolves through the same home the detection pass used, and the Codex destination honours `$CODEX_HOME`, so a reported success always names a directory the detected host actually reads.

{scar_cli-0.23.0 → scar_cli-0.25.0}/plugin/plugin.json

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

{scar_cli-0.23.0/src/scar → scar_cli-0.25.0/plugin}/skills/scar-authoring/SKILL.md

@@ -96,6 +96,9 @@ self-match).
 
 - `path:` = repo-relative prefix (file or directory). `pattern:` =
   case-insensitive regex over path + new content.
+- `symbol:` = `path::name` or a bare name. Use it for code likely to move or be
+  renamed: it follows the definition, not the path. Needs the `[symbols]` extra
+  (`uv tool install "scar-cli[symbols]"`), Python, TypeScript and JavaScript.
 - Severity: `low | medium | high | critical`.
 - Injection is capped at ~3 scars / ~700 chars each — write tight: 5–15 lines,
   evidence cited inline.

{scar_cli-0.23.0 → scar_cli-0.25.0}/pyproject.toml

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

{scar_cli-0.23.0 → scar_cli-0.25.0}/src/scar/cascade.py

@@ -38,12 +38,13 @@ from .hooks import (
     _extract_edit_content,
     _log_firing,
     _log_violation_firing,
+    _matched_by_of,
     _read_payload,
     _state_dir,
 )
 from .match import (MatchCensus, armed_scar_ids, find_violations,
                     has_content_signal, rank_and_census_for_edit)
-from .render import compact_block, rule_line
+from .render import compact_block, cut_total, rule_line
 from .store import ScarStore
 
 # NOT 2, which is what Cascade reads as "block". argparse also exits 2 on an
@@ -120,16 +121,19 @@ def _remember_fired(keys: list[str]) -> bool:
     return True
 
 
-def _block_text(scars: list) -> str:
+def _block_text(scars: list, matched_total: int | None = None) -> str:
     """What the agent reads on the bounced action. Compact tier only — this
     renders as an error in the Cascade UI, and the agent needs the constraint,
-    not the essay."""
+    not the essay. When the fatigue cap cut matches, the closing line says so
+    in a clause (#321); no census, or one that shows no cut, changes nothing."""
+    cut = cut_total(len(scars), matched_total)
+    shown = "" if cut is None else f"{len(scars)} of {cut} matched shown. "
     return (
         f"SCAR blocked this action once — {len(scars)} scar(s) record why it "
         "went wrong before. Read them, then retry: the identical action goes "
         "through, informed.\n\n"
         + compact_block(scars)
-        + "\n\nFull records in .scars/ (`scar why <path>`).")
+        + f"\n\n{shown}Full records in .scars/ (`scar why <path>`).")
 
 
 def _partition(matches: list, fired: dict[str, float], trajectory: str,
@@ -173,7 +177,10 @@ def _respond(store: ScarStore, trajectory: str, target: str,
     if not to_block:
         return 0
     scars = [m.scar for m in to_block]
-    print(_block_text(scars), file=sys.stderr)
+    # Only a cap cut counts: matches the partition above sent to stdout instead
+    # of the block were not cut, so the census must exceed the whole list.
+    capped = census.total if census and census.total > len(matches) else None
+    print(_block_text(scars, capped), file=sys.stderr)
     # Firing log parity (#106) records what the AGENT saw, and here only a
     # block reaches it — a stdout line went to the human. So the surface-only
     # matches are NOT logged, and in particular not as `demoted_ids`: that
@@ -184,7 +191,8 @@ def _respond(store: ScarStore, trajectory: str, target: str,
     # refuse the action. Surface-only matches never reach the log at all
     # (see the comment above), so every windsurf row is block-capable.
     _log_firing(store, target, scars, runtime=RUNTIME, block_capable=True,
-                matched=census, anchor_kind=anchor_kind)
+                matched=census, anchor_kind=anchor_kind,
+                matched_by=_matched_by_of(to_block))
     return BLOCK_EXIT