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

{scar_cli-0.4.0 → scar_cli-0.5.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.5.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.5.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.5.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.5.0/.scars/candidates/fp-log.txt

@@ -0,0 +1,3 @@
+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

{scar_cli-0.4.0 → scar_cli-0.5.0}/CHANGELOG.md

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
 License: MIT
 License-File: LICENSE

{scar_cli-0.4.0 → scar_cli-0.5.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.5.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.4.0 → scar_cli-0.5.0}/pyproject.toml

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