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

scar_cli-0.6.0/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "scar",
+  "owner": { "name": "Daily-Nerd" },
+  "plugins": [
+    {
+      "name": "scar",
+      "source": "./plugin",
+      "description": "Read and author negative-knowledge scars: auto-injected scars before edits, plus the scar-authoring skill."
+    }
+  ]
+}

{scar_cli-0.4.0 → scar_cli-0.6.0}/.scars/0001-git-grep-ere-pitfalls.landmine.md

@@ -8,12 +8,10 @@ created: 2026-06-09
 authors: ["claude-code", kibukx]
 anchors:
   - path: experiments/anchor-survival/
-  - path: hook/scar-precheck.py
-  - pattern: "git.{0,20}grep.{0,40}\\\\b"
+  - path: src/scar/harvest.py
+  - pattern: "git.{0,20}grep"
 evidence:
-  - commit: 5c63b14
-  - note: "produced a fake 0% anchor-survival run before diagnosis (gate 0.2)"
-  - note: "history rewritten at v0.1.0 public release; pre-release SHAs resolve on GitHub by URL but not in fresh clones"
+  - 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:
   condition: "resolver layer gains integration tests over its git invocations"
   review_after: 2027-06-09

{scar_cli-0.4.0 → scar_cli-0.6.0}/.scars/0002-agent-direct-hook-install.deadend.md

@@ -8,11 +8,11 @@ created: 2026-06-09
 authors: ["claude-code", kibukx]
 anchors:
   - path: hook/
-  - pattern: "settings\\.json.{0,80}hooks|hooks.{0,80}settings\\.json"
+  - path: src/scar/installer.py
 evidence:
-  - commit: faad8f6
-  - commit: bcd3864
-  - note: "history rewritten at v0.1.0 public release; pre-release SHAs resolve on GitHub by URL but not in fresh clones"
+  - note: "orphaned receipt — pre-v0.1.0 installer commit faad8f6 at github.com/Daily-Nerd/Scar/commit/faad8f6 (unreachable in fresh clones)"
+  - note: "orphaned receipt — pre-v0.1.0 hooks commit bcd3864 at github.com/Daily-Nerd/Scar/commit/bcd3864 (unreachable in fresh clones)"
+  - note: "both SHAs orphaned by the fresh-start force-push at the v0.1.0 public release; resolve on GitHub by URL until GC, not in fresh clones"
 status: active
 ---
 

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

@@ -8,7 +8,6 @@ created: 2026-06-11
 authors: ["claude-code", "Kibukx"]
 anchors:
   - path: .scars/
-  - pattern: "push.{0,30}(--force|\\+[a-zA-Z]).{0,40}main|filter-repo|checkout --orphan"
 evidence:
   - note: v0.1.0 public release (2026-06-11): fresh-start force-push orphaned 3 commit SHAs cited by scars 0001 and 0002; SHAs still resolve on GitHub by URL but fail in any fresh clone, and GitHub may GC them eventually
 expires:
@@ -19,7 +18,7 @@ status: active
 
 Scars cite commit SHAs as evidence receipts. Those receipts implicitly assume
 the SHA stays reachable in the repo's history forever. Any history rewrite —
-fresh-start orphan branch, force-push, filter-repo scrub — silently breaks
+fresh-start orphan branch, force-push, filter-repo scrub, or a routine squash-/rebase-merge — silently breaks
 that assumption: the scar still lints clean and still fires (anchors are
 paths/patterns, not commits), but `git show <sha>` fails in every fresh clone,
 so the receipt is unverifiable exactly where strangers would check it.
@@ -29,9 +28,15 @@ Observed at the v0.1.0 public release: the fresh-start force-push orphaned
 until after the push because nothing in the toolchain connects "history
 operation" to "evidence integrity."
 
-Before any history rewrite in a repo with scars: grep `.scars/` for
-`commit:` evidence and either (a) amend those scars with a note explaining the
-rewrite, (b) replace bare SHAs with full GitHub commit URLs (survive as
-unreachable objects, at GC's mercy), or (c) inline the relevant diff/fact into
-a note so the scar is self-contained. Longer term: `scar lint` could warn
-when a cited SHA is unreachable from HEAD.
+The everyday trigger is the merge strategy itself: this repo squash-merges, so a
+feature-branch commit — exactly the SHA you cite while drafting a scar mid-PR —
+is orphaned the moment that PR lands. Rebase-merge does the same; only a true
+merge-commit preserves branch SHAs. So PREFER `pr:`/`issue:` evidence (it
+resolves on GitHub regardless of merge strategy) or a SHA already on the default
+branch, and avoid citing transient feature-branch SHAs at all.
+
+Before any deliberate history rewrite: grep `.scars/` for `commit:` evidence and
+either (a) amend with a note explaining the rewrite, (b) replace bare SHAs with
+full GitHub commit URLs (at GC's mercy), or (c) inline the fact so the scar is
+self-contained. `scar lint` now warns when a cited SHA is unreachable from HEAD
+(#43) — but it fires after the fact; the durable fix is not citing branch SHAs.

scar_cli-0.6.0/.scars/0006-yaml-pattern-anchor-over-escaping.landmine.md

@@ -0,0 +1,41 @@
+---
+id: 6
+type: landmine
+title: Pattern anchors over-escape through YAML double-quotes and silently only self-match
+severity: medium
+confidence: 0.9
+created: 2026-06-13
+authors: ["claude-code", "kibukx"]
+anchors:
+  - path: src/scar/orphan.py
+  - path: src/scar/match.py
+  - path: .scars/
+evidence:
+  - pr: 40
+  - note: scar 1 grep pattern matched only its own body, never experiments/anchor-survival/RESULTS.md
+expires:
+  condition: "pattern anchors are authored through a validated path (e.g. scar draft) that escapes regex correctly, OR lint rejects a pattern whose only pre-exclusion match is the scar's own file"
+  review_after: 2027-06-13
+status: active
+---
+
+A regex written in a scar's `pattern:` field passes through YAML double-quoted
+string parsing before it ever reaches the matcher. Backslashes collapse: what
+you type as a four-backslash word boundary in the file becomes a regex needing
+*literal* backslashes, not a word boundary. The intended code almost never
+contains literal backslashes, so the pattern matches nothing real.
+
+The trap is that it still reads as LIVE. Pattern anchors are matched against ALL
+tracked content, including the scar's own `.scars/` body, and the body quotes
+the pattern verbatim, so the scar keeps itself alive by self-reference. Orphan
+detection sees a live anchor and stays quiet. The protection is dead; the gauge
+says green. On this repo, scars 1 and 5 were pure ghosts (own-body only) and
+scar 2 matched zero files at all, none visible until self-referential exclusion
+was added in PR #40 (`_pattern_anchor_live(..., exclude_path=self_path)`).
+
+What a future editor must do: when adding a `pattern:` anchor, verify it matches
+the REAL code with `scar lint` (it must NOT appear under partial-rot), not just
+that the scar parses. Prefer a `path:` anchor when the target is a file or dir;
+path anchors do not go through regex escaping and cannot self-match. If you must
+use a regex with escapes, test it against tracked content excluding the scar's
+own file before trusting it.

scar_cli-0.6.0/.scars/candidates/fp-log.txt

@@ -0,0 +1,6 @@
+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.
+2026-06-13 false trigger: tool_errors were external API hiccups (pypistats rate-limit/404, bq schema field); no code approach tried-and-abandoned this session (design-only work)
+2026-06-12 false trigger: orphan-detection impl — 'revert' is feature-domain ('revert case' reverse hint = anchors-live-again) + a planned AC#1 refactor swapping batch-1 copied anchor logic for a shared match.py primitive; replacement was design-mandated, not a deadend discovered by failure
+2026-06-13 — false trigger: signals from iterative re-anchoring + a caught staging bug (fixed #51) + gh CLI flakiness; all genuine lessons already captured as scars #5/#6 and issues #50
+2026-06-13 false trigger: harvest-labeling session — 'revert/reverted/abandoned' prose describes ANOTHER repo's history (homelab-apps reverts judged as scar candidates), not an approach abandoned here; tool_errors were a wc-on-wrong-path + benign exit-1 during label recording. Curation work trips the drafter like meta-sessions do (FP #1).
+2026-06-24 false trigger: #54 scorer investigation — 'revert' is feature-domain (the revert heuristic) + 'user_corrections'/'wrong' is me correcting the ISSUE BODY's mechanism claim (flapping base vs uncapped osc bonus), not abandoning a tried code approach. Read-only mapping + scope question; no code written, nothing deadended. Same self-ref class as FP #1/#5: sessions reasoning about the scorer trip the scorer.

{scar_cli-0.4.0 → scar_cli-0.6.0}/AGENTS.md

@@ -18,6 +18,23 @@ frontmatter.
 - Do not silently ignore broken scar files. Run `scar lint` when changing scar
   format, parsing, promotion, lifecycle, or candidate-writing behavior.
 
+## Authoring scars
+
+When you abandon an approach (deadend), keep intentional-looking weirdness
+(fence), or discover non-obvious coupling (landmine), record it as a scar.
+The full authoring contract — qualification criteria, the candidates-only write
+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.
+- **MCP agents (Cursor/Windsurf/opencode):** the `scar_draft` tool enforces the
+  candidates-only path and lints before writing; its description carries the
+  digest.
+- **Any runtime / manual:** run `scar agent skill` to print the full skill body
+  and load it into context. The canonical file is
+  `src/scar/skills/scar-authoring/SKILL.md`.
+
 ## Agent Integrations
 
 - MCP-capable agents can launch the local server with `scar mcp`.

scar_cli-0.6.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+## [0.6.0](https://github.com/Daily-Nerd/Scar/compare/v0.5.0...v0.6.0) (2026-06-26)
+
+
+### Features
+
+* **agent:** Packaged scar-authoring skill + Claude Code plugin ([#32](https://github.com/Daily-Nerd/Scar/issues/32)) ([#58](https://github.com/Daily-Nerd/Scar/issues/58)) ([b1eaca7](https://github.com/Daily-Nerd/Scar/commit/b1eaca7f702d86a4e5429c8c085c1537f5505d0d))
+
+
+### Bug Fixes
+
+* **harvest:** exclude .scars/ tree from candidates (self-ref noise) ([#56](https://github.com/Daily-Nerd/Scar/issues/56)) ([29c2d61](https://github.com/Daily-Nerd/Scar/commit/29c2d6116e23a748df8455170c311023c6578c5c)), closes [#55](https://github.com/Daily-Nerd/Scar/issues/55)
+
+## [0.5.0](https://github.com/Daily-Nerd/Scar/compare/v0.4.0...v0.5.0) (2026-06-13)
+
+
+### Features
+
+* **harvest:** precision@N reporting CLI — close the measurement loop ([#53](https://github.com/Daily-Nerd/Scar/issues/53)) ([100bd1d](https://github.com/Daily-Nerd/Scar/commit/100bd1d46bbac981a3629b74c237fc0584f5ce05))
+* **harvest:** ranking layer — heuristic scorer + label-capture instrument ([#39](https://github.com/Daily-Nerd/Scar/issues/39)) ([7369f73](https://github.com/Daily-Nerd/Scar/commit/7369f738d3fe356a0290cbf05f0654a48587ee9f))
+* **lifecycle:** lint warns on evidence commit SHAs unreachable from HEAD ([#44](https://github.com/Daily-Nerd/Scar/issues/44)) ([714357e](https://github.com/Daily-Nerd/Scar/commit/714357e9b6366ec67d71d086cf62d8dafbcae976))
+* **lifecycle:** orphan detection — resolution failure, loud in CI ([#34](https://github.com/Daily-Nerd/Scar/issues/34)) ([421a12a](https://github.com/Daily-Nerd/Scar/commit/421a12aae25cc46f6aa40593a6274bb755d4b81b))
+* **lifecycle:** partial-anchor rot — surface dead anchors on firing scars ([#40](https://github.com/Daily-Nerd/Scar/issues/40)) ([85fd57e](https://github.com/Daily-Nerd/Scar/commit/85fd57e397055576bd754c3d606417274d6a9d5c))
+
+
+### Bug Fixes
+
+* **scars:** drop [#6](https://github.com/Daily-Nerd/Scar/issues/6) orphaned receipt, broaden scar [#5](https://github.com/Daily-Nerd/Scar/issues/5) for squash-merge ([#51](https://github.com/Daily-Nerd/Scar/issues/51)) ([4c63ac5](https://github.com/Daily-Nerd/Scar/commit/4c63ac50c648d8ec47190c6045987a276c9fb9bf))
+* **scars:** re-anchor 3 ghost pattern anchors to real code ([#42](https://github.com/Daily-Nerd/Scar/issues/42)) ([00a2fcb](https://github.com/Daily-Nerd/Scar/commit/00a2fcb5c41c165f260019ec95bc636b18d17491))
+* **scars:** replace 3 orphaned bare commit-SHA receipts with self-contained notes ([#46](https://github.com/Daily-Nerd/Scar/issues/46)) ([a224619](https://github.com/Daily-Nerd/Scar/commit/a224619f47387cce401039bf9ddbb93cb3841641))
+
+## [0.4.0](https://github.com/Daily-Nerd/Scar/compare/v0.3.0...v0.4.0) (2026-06-12)
+
+
+### Features
+
+* **format:** reserve optional receipt_id field ([#29](https://github.com/Daily-Nerd/Scar/issues/29)) ([47ce933](https://github.com/Daily-Nerd/Scar/commit/47ce933cde02fa1155d0474e98101804cb7b1a80))
+
+
+### Bug Fixes
+
+* **hooks:** expose lifecycle commands ([#31](https://github.com/Daily-Nerd/Scar/issues/31)) ([dba2c0d](https://github.com/Daily-Nerd/Scar/commit/dba2c0d1c1bd8a0f73880bfab0ff17187eec2fb9)), closes [#30](https://github.com/Daily-Nerd/Scar/issues/30)
+
+
+### Documentation
+
+* **roadmap:** truth pass — gates resolved, Phase 1 shipped, Phase 2 in progress ([#26](https://github.com/Daily-Nerd/Scar/issues/26)) ([7701a97](https://github.com/Daily-Nerd/Scar/commit/7701a97610f470e7726e7f5fc86932a5101eb255))
+
+## [0.3.0](https://github.com/Daily-Nerd/Scar/compare/v0.2.0...v0.3.0) (2026-06-12)
+
+
+### Features
+
+* **agents:** multi-agent scar integration — AGENTS.md, MCP server, agent helpers ([#21](https://github.com/Daily-Nerd/Scar/issues/21)) ([52c817f](https://github.com/Daily-Nerd/Scar/commit/52c817fc963f8f829b70de60b772c1097c6f0334))
+
+## [0.2.0](https://github.com/Daily-Nerd/Scar/compare/v0.1.1...v0.2.0) (2026-06-12)
+
+
+### Features
+
+* **cli:** lifecycle v0 — challenge, archive, review_after surfacing ([#16](https://github.com/Daily-Nerd/Scar/issues/16)) ([0c6fb05](https://github.com/Daily-Nerd/Scar/commit/0c6fb05fbdbb57f8ac9b2a5b558e4cf121c3d5c0)), closes [#14](https://github.com/Daily-Nerd/Scar/issues/14)
+
+
+### Documentation
+
+* **readme:** scar challenge is planned, not shipped — point to lifecycle issue ([8c6b021](https://github.com/Daily-Nerd/Scar/commit/8c6b021c95299cf40bf6c2d978a0421bb9705cb6))
+
+## [0.1.1](https://github.com/Daily-Nerd/Scar/compare/v0.1.0...v0.1.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **hooks:** drafter triggers on revert language only ([#12](https://github.com/Daily-Nerd/Scar/issues/12)) ([547c4bb](https://github.com/Daily-Nerd/Scar/commit/547c4bb21e3521682b6a4046602d6703d88c2cf1)), closes [#11](https://github.com/Daily-Nerd/Scar/issues/11)

{scar_cli-0.4.0 → scar_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE
@@ -95,6 +95,16 @@ stop all automatic injection and drafting while keeping the repository's
 scar hook uninstall
 ```
 
+**Recommended (Claude Code): install the plugin** so the hooks *and* the
+scar-authoring skill arrive together via the marketplace.
+
+**Fallback / non-marketplace:** `scar hook install` registers the hooks, and
+`scar skill install` drops the authoring skill into `~/.claude/skills/`. Both are
+explicit — you run them, nothing is installed as a side effect.
+
+Non-Claude agents: `scar agent skill` prints the authoring skill for any runtime;
+MCP agents get the digest via the `scar_draft` tool description.
+
 Wiring MCP-capable agents:
 
 ```bash

{scar_cli-0.4.0 → scar_cli-0.6.0}/README.md

@@ -86,6 +86,16 @@ stop all automatic injection and drafting while keeping the repository's
 scar hook uninstall
 ```
 
+**Recommended (Claude Code): install the plugin** so the hooks *and* the
+scar-authoring skill arrive together via the marketplace.
+
+**Fallback / non-marketplace:** `scar hook install` registers the hooks, and
+`scar skill install` drops the authoring skill into `~/.claude/skills/`. Both are
+explicit — you run them, nothing is installed as a side effect.
+
+Non-Claude agents: `scar agent skill` prints the authoring skill for any runtime;
+MCP agents get the digest via the `scar_draft` tool description.
+
 Wiring MCP-capable agents:
 
 ```bash

{scar_cli-0.4.0 → scar_cli-0.6.0}/ROADMAP.md

@@ -29,11 +29,11 @@ Public at [github.com/Daily-Nerd/Scar](https://github.com/Daily-Nerd/Scar), `sca
 
 - ✅ **MCP server** (`scar_query`, `scar_why`, `scar_draft`) — shipped v0.3.0, dependency-free stdio, drafts gated to candidates/. First non-Claude agent (Codex) arrived and contributed the implementation — the deferral condition resolving itself.
 - ✅ Multi-agent surface: committed `AGENTS.md`, `scar inject --diff`, `scar agent doctor/config` for Codex, Cursor, Windsurf, opencode (v0.3.0)
-- 🔶 CI surface: expiry warnings shipped (`lint`/`status`, v0.2.0); **orphan detection is the next milestone** — content-fingerprint drift → `orphaned` status, loud in CI (principle 3 is not yet enforced by code)
-- ⬜ Harvest ranking layer (gate 0.1 verdict: required — raw precision 13% without it)
-- ⬜ Re-anchoring agent workflow: orphaned scar + orphaning diff → proposed new anchors as a PR
+- ✅ CI surface: expiry warnings (`lint`/`status`, v0.2.0); orphan detection — all-anchors-dead firing scars → `orphaned`, loud in CI (#34); partial-rot advisory — firing scars with ≥1 dead anchor among live ones, named in `lint`/`status`/`orphan` (#35). Principle 3 now enforced by code for both total and partial rot.
+- ✅ Harvest ranking layer — heuristic weighted scorer + label-capture instrument, zero-dep, deterministic (#39). Weights remain intuition until real-repo labels calibrate precision.
+- ⬜ Re-anchoring agent workflow: orphaned/partially-rotted scar + orphaning diff → proposed new anchors as a PR
 - ⬜ Editor surfaces (VS Code gutter marks, LSP code lens) — fences visible to humans, not only agents
-- ⬜ Lint warning on evidence commit SHAs unreachable from HEAD (scar #5's expiry condition)
+- ✅ Lint warning on evidence commit SHAs unreachable from HEAD (#43) — scar #5's expiry condition, now enforced; advisory in `lint`, skipped on shallow clones
 
 ## Phase 3 — The org graph ⏸ parked by design
 

scar_cli-0.6.0/experiments/harvest/PROTOCOL.md

@@ -0,0 +1,76 @@
+# Experiment: Harvest Ranking + Label Instrument (Issue #38)
+
+**Question.** Can a cheap, explainable heuristic score RANK harvested candidates so the human curator reads the real scars first — without normalizing away the precision signal carried by candidate type?
+
+**Why it matters.** Raw harvest precision sits at ~13% on real history. If a curator must read every candidate in arbitrary order, the tool costs more attention than it saves. Ranking earns its place only if the top-N is denser in real scars than the tail. This experiment builds the *instrument* (labels + precision@N) so that claim becomes measurable instead of asserted.
+
+## What the ranker does
+
+Each candidate gets a deterministic `score` (see `src/scar/harvest.py`). The score is a sum of calibration priors — base weight per signal type plus small bonuses (PR/issue ref on reverts, files-deleted threshold, oscillation count, comment specificity, recency). All weights are **priors, unvalidated until labels exist**; this experiment is how they get validated.
+
+**Cross-section ranking uses RAW score, no normalization** (`scar harvest --top-k N`). The per-type base constants order `comment < flapping < deleted_component < revert`. That ordering is an intentional precision prior: signal *type* predicts precision, so a revert outranks a grep hit by design. Normalizing scores across types would erase exactly the signal we want to exploit. If the labels later show the ordering is wrong, fix the base constants — do not add normalization.
+
+## Label JSONL format
+
+Path: `experiments/harvest/labels.jsonl` (committed — instrument/data, like the anchor-survival replay). Written one line at a time by:
+
+```
+scar harvest <repo> --label <id> keep|discard [--note "..."]
+```
+
+Each line is one JSON object:
+
+| Field   | Type   | Meaning |
+|---------|--------|---------|
+| `id`    | string | the candidate's stable id (see below) |
+| `label` | string | **exactly** `"keep"` or `"discard"` — nothing else is accepted |
+| `note`  | string | free-text rationale (may be empty) |
+| `date`  | string | `YYYY-MM-DD`, from `time.strftime` (monkeypatchable in tests) |
+| `repo`  | string | the harvested repo's name (provenance) |
+
+**Only `keep`/`discard` are valid.** The CLI rejects any other label value with a non-zero exit and writes nothing. This is load-bearing: `precision_at_n` reads `label == "keep"` and counts everything labeled as the denominator — a third value (`"maybe"`, `"skip"`) would silently corrupt precision by inflating the denominator without ever counting toward the numerator.
+
+**Id validation.** `--label` runs `harvest(repo)` for the target repo, collects every candidate id, and **rejects an id not in that set** (mirrors `scar orphan --apply` rejecting an unknown `--id`). You cannot label a candidate that the current harvest does not produce.
+
+## Candidate-id stability rule
+
+`harvest.candidate_id(signal_type, candidate)` = first 10 hex of `sha1(signal_type + identifying-fields)`. The id is a hash of the **identifying fields only — NOT the score, NOT the id itself**, so the same candidate gets the same id across runs and a re-scored candidate keeps its label.
+
+Identifying fields per type:
+
+| Type                | Hashed fields |
+|---------------------|---------------|
+| `revert`            | `commit` |
+| `deleted_component` | `component` |
+| `flapping`          | `file` + `key` |
+| `comment`           | `location` + `text[:40]` |
+
+**Comment ids use `text[:40]`** — the first 40 characters of the comment text. Keep those 40 chars stable: editing the tail of a long comment preserves the id; editing the start changes it (and orphans any prior label). This deliberately tolerates the 120-char display truncation in `_comment_archaeology` without making the id depend on it.
+
+## Precision@N
+
+`harvest.precision_at_n(ranked, labels, n)`:
+- `ranked` — candidates pre-sorted by score descending (caller's responsibility; `scar harvest --top-k` produces this order).
+- `labels` — a `{id: "keep"|"discard"}` dict built from the JSONL (group by id; last write wins if a candidate was labeled twice).
+- Take the first `n`. Among them, consider **only** candidates whose id is in `labels`. Return the fraction of that labeled subset where `label == "keep"`.
+
+**Contract: unlabeled candidates in the top-N are excluded from BOTH numerator and denominator.** They neither help nor hurt the score — precision@N measures "of the ones we judged in the top-N, how many were real". If no candidate in the top-N is labeled, the result is `0.0` (not NaN, not an error).
+
+## Method (to run once labels accrue)
+
+1. Harvest a real repo; curate the top-N by hand, recording `keep`/`discard` via `--label`.
+2. Build `{id: label}` from `labels.jsonl`.
+3. Compute `precision_at_n` at several N (e.g. 5, 10, 20) and compare against the ~13% raw base rate.
+4. Compare per-type precision to validate (or refute) the base-constant ordering.
+
+## Pre-registered claim
+
+- **Ranking earns its place** if precision@N for small N is materially above the ~13% raw base rate — i.e. the top of the ranked list is denser in real scars than the unranked pool.
+- If precision@N ≈ base rate at every N, the score adds no signal and the constants need rework (or the heuristic is the wrong instrument).
+
+## Limitations (declared)
+
+1. Weights are hand-set priors, not fit to data — this instrument exists to replace the guess with a measurement, but until ~50 labels accrue the ranking is an assertion.
+2. Single-curator labels carry that curator's bias; `keep`/`discard` is a coarse binary over what is really a confidence gradient.
+3. `precision_at_n` ignores recall — a candidate the harvester never surfaced cannot be labeled, so a missed real scar is invisible here.
+4. Recency scoring reads the wall clock at harvest time; the same candidate scored months apart can shift rank (id stays stable, so labels still attach correctly).

scar_cli-0.6.0/plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "scar",
+  "version": "0.5.0",
+  "description": "SCAR — version control for negative knowledge (deadends, fences, landmines)",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "scar hook precheck", "timeout": 10 }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "scar hook session-notice", "timeout": 10 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "scar hook stop-drafter", "timeout": 15 }
+        ]
+      }
+    ]
+  }
+}

scar_cli-0.6.0/plugin/skills/scar-authoring/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: scar-authoring
+description: >
+  Author negative-knowledge scars (deadend/fence/landmine) for a repo's .scars/
+  directory — qualification criteria, the candidates-only write path, and the
+  mandatory-frontmatter / regex-escaping traps that silently break scars.
+  Trigger: when you abandon an approach after trying it, when you keep code that
+  looks wrong on purpose, or when you discover that changing one thing breaks
+  another non-obviously — and you want to record it so the next agent does not
+  repeat the pain.
+license: MIT
+metadata:
+  author: Daily-Nerd
+  version: "1.0"
+---
+
+# Authoring Scars
+
+A scar records *negative knowledge*: a thing that was tried and failed, code
+that looks wrong but is intentional, or a non-obvious coupling. Scars fire
+automatically — the next editor sees the relevant scar injected before they
+touch anchored code. Your job here is to write a good one.
+
+## When to Use
+
+- You **abandoned an approach** after trying it → `deadend`
+- You **kept code that looks wrong on purpose** → `fence`
+- You **found that changing A breaks B non-obviously** → `landmine`
+
+Not a scar: routine debugging that eventually succeeded. If you tried something,
+it worked, and you moved on — there is nothing to record.
+
+## The Three Types
+
+**`deadend` — tried and failed.** Protects against re-attempting a dead path.
+Primary anchor is usually `pattern` (the shape of the failed approach).
+*Example (scar #2):* an agent tried to install Claude Code hooks by writing
+`~/.claude/settings.json` directly; the permission classifier denies it. Anchor
+`path: src/scar/installer.py`; body says the *user* must run `scar hook install`.
+
+**`fence` — looks wrong, is intentional.** Protects existing code from a
+"cleanup" that would break it. Primary anchor is `path`.
+*Example (scar #3):* the installer deliberately ignores an active virtualenv so
+hooks bind to a stable `scar` on PATH, not a venv shim that disappears. Anchor
+`path: src/scar/installer.py`; body says "do not 'simplify' this to plain
+`shutil.which`."
+
+**`landmine` — touching A breaks B.** Anchor the trigger site; the body names
+the blast radius. *Example (scar #6):* a regex in a scar's `pattern:` field is
+double-quoted YAML, so `\b` collapses and the anchor silently self-matches only
+its own `.scars/` body — the protection is dead but the gauge reads green.
+
+## The Write Contract (non-negotiable)
+
+1. COPY `.scars/template.md` (or this skill's `assets/template.md`) — do not
+   edit the template itself.
+2. Write to `.scars/candidates/<slug>.md` with `status: candidate`.
+3. **Never** write into `.scars/*.md` directly. A human promotes via
+   `scar promote`.
+4. If an MCP server is wired, prefer the `scar_draft` tool — it enforces the
+   path and runs lint before writing.
+
+## Mandatory Frontmatter
+
+A file without `---`-fenced YAML frontmatter is **not a scar at all** — it never
+fires. Minimum valid block: `type`, `title`, `severity`, `confidence`,
+`created`, `authors`, at least one `anchors` entry, and `status: candidate`.
+
+## Anti-Over-Escape (the #1 silent failure)
+
+Prefer a `path:` anchor — it cannot self-match and needs no escaping. If you
+must use a `pattern:` regex: backslashes in double-quoted YAML collapse (`\b`
+dies), and the pattern is matched against all tracked content **including the
+scar's own body**, so a broken pattern keeps itself alive by self-reference.
+Run `scar lint` and confirm the scar does NOT appear under partial-rot
+(self-match only).
+
+Wrong: `pattern: "\\bwiden\\b"`  →  Right: `path: src/widen/` (no escaping, no
+self-match).
+
+## Anchors, Severity, Size
+
+- `path:` = repo-relative prefix (file or directory). `pattern:` =
+  case-insensitive regex over path + new content.
+- Severity: `low | medium | high | critical`.
+- Injection is capped at ~3 scars / ~700 chars each — write tight: 5–15 lines,
+  evidence cited inline.
+
+## Verify Before Finishing
+
+- `scar lint` must pass.
+- At least one `evidence` receipt (commit / pr / incident / note) — without it
+  the scar is challengeable on sight.

scar_cli-0.6.0/plugin/skills/scar-authoring/assets/template.md

@@ -0,0 +1,25 @@
+---
+# COPY THIS FILE — do not edit the template itself.
+# New scars: write to .scars/candidates/<slug>.md with status: candidate.
+# A human reviewer promotes to .scars/NNNN-<slug>.<type>.md with status: active.
+id: 0                      # assigned at promotion (next free NNNN)
+type: deadend              # deadend = tried+failed | fence = looks wrong, intentional | landmine = touching A breaks B
+title: One line, searchable, says the constraint
+severity: medium           # low | medium | high | critical
+confidence: 0.7            # 0..1 — how sure are we this still holds
+created: 1970-01-01
+authors: ["claude-code"]   # add the human reviewer at promotion
+anchors:
+  - path: src/module/      # file or directory this protects
+  - pattern: "regex"       # optional: fires when matching code appears in ANY new/edited file
+evidence:
+  - commit: abc1234        # at least one receipt: commit, pr, incident, or note
+expires:
+  condition: "what change would make this scar obsolete"
+  review_after: 1971-01-01 # force a freshness look even if condition never triggers
+status: template           # candidate | active | challenged | archived  (template = never parsed)
+---
+
+Body: 5-15 lines of prose. What was tried/observed, why it failed or why the
+weirdness is intentional, and what a future editor must do instead. Write it
+for someone (human or agent) with zero context. Cite the evidence inline.

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

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

{scar_cli-0.4.0 → scar_cli-0.6.0}/src/scar/agent.py

@@ -64,3 +64,10 @@ def config(target: str) -> str:
     if target not in CONFIGS:
         raise ValueError(f"unknown target '{target}' (expected: {', '.join(TARGETS)})")
     return CONFIGS[target]
+
+
+def skill() -> str:
+    """Return the full scar-authoring SKILL.md body (packaged, runtime-neutral)."""
+    from importlib.resources import files
+    resource = files("scar").joinpath("skills/scar-authoring/SKILL.md")
+    return resource.read_text(encoding="utf-8")