scar-cli 0.1.1__tar.gz

scar_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests + scar lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Sync dependencies
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      # Dogfood: the repo's own scar graph must always parse and lint clean.
+      # A malformed scar silently never fires (the daimon 0004 incident) —
+      # this gate makes that class of rot unmergeable.
+      - name: scar lint
+        run: uv run scar lint

scar_cli-0.1.1/.github/workflows/pr-validation.yml

@@ -0,0 +1,65 @@
+name: PR Validation
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  validate:
+    name: PR convention
+    # release-please PRs are bot-generated changelog/version bumps; the
+    # issue-first convention governs human contributions, not the release cycle
+    if: ${{ !startsWith(github.head_ref, 'release-please--') }}
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      REPO: ${{ github.repository }}
+      PR: ${{ github.event.pull_request.number }}
+    steps:
+      - name: Check Issue Reference
+        run: |
+          body="$(gh pr view "$PR" --repo "$REPO" --json body -q .body)"
+          if ! grep -qiE '(closes|fixes|resolves) #[0-9]+' <<<"$body"; then
+            echo "::error::PR body must link an issue: Closes/Fixes/Resolves #N"
+            exit 1
+          fi
+
+      - name: Check Issue Has status:approved
+        run: |
+          body="$(gh pr view "$PR" --repo "$REPO" --json body -q .body)"
+          issue="$(grep -oiE '(closes|fixes|resolves) #[0-9]+' <<<"$body" | head -1 | grep -oE '[0-9]+')"
+          labels="$(gh issue view "$issue" --repo "$REPO" --json labels -q '.labels[].name')"
+          if ! grep -qx 'status:approved' <<<"$labels"; then
+            echo "::error::Linked issue #$issue lacks the status:approved label"
+            exit 1
+          fi
+
+      - name: Check PR Has type:* Label
+        run: |
+          count="$(gh pr view "$PR" --repo "$REPO" --json labels -q '.labels[].name' | grep -c '^type:' || true)"
+          if [ "$count" -ne 1 ]; then
+            echo "::error::PR must have exactly one type:* label (found $count)"
+            exit 1
+          fi
+
+      - name: Check Conventional PR Title
+        # squash-merge makes the PR title the commit subject on main
+        run: |
+          title="$(gh pr view "$PR" --repo "$REPO" --json title -q .title)"
+          if ! grep -qE '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9._-]+\))?!?: .+' <<<"$title"; then
+            echo "::error::PR title must be a conventional commit: type(scope): description"
+            exit 1
+          fi
+
+      - name: Check Branch Name
+        run: |
+          branch="${{ github.head_ref }}"
+          if ! grep -qE '^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)/[a-z0-9._-]+$' <<<"$branch"; then
+            echo "::error::Branch name must match type/description (lowercase, a-z0-9._-)"
+            exit 1
+          fi

scar_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.rp.outputs.release_created }}
+      tag_name: ${{ steps.rp.outputs.tag_name }}
+    steps:
+      - id: rp
+        uses: googleapis/release-please-action@v4
+        with:
+          release-type: python
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

scar_cli-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+# python / uv
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# experiments produce local run artifacts
+experiments/fence-honor/runs/
+
+# editor / os
+.DS_Store
+.idea/
+.vscode/
+.claude/

scar_cli-0.1.1/.scars/0001-git-grep-ere-pitfalls.landmine.md

@@ -0,0 +1,34 @@
+---
+id: 1
+type: landmine
+title: git grep -E has no \b, and zero-match pathspecs silently empty results
+severity: high
+confidence: 0.9
+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"
+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"
+expires:
+  condition: "resolver layer gains integration tests over its git invocations"
+  review_after: 2027-06-09
+---
+
+Two git quirks that combined into a silent total failure during gate 0.2:
+
+1. `git grep -E` is POSIX ERE — `\b` is NOT a word boundary, it matches a
+   literal sequence, so patterns quietly match nothing. Use `-w` (word mode),
+   `-F` for literals, or an explicit `([^A-Za-z0-9_]|$)` boundary class.
+2. A pathspec glob that matches zero files (e.g. `-- '*.tsx'` in a pure
+   Python repo) doesn't error — it silently empties the ENTIRE result set,
+   including hits from globs that do match.
+
+Together they made every anchor look orphaned (fake "0% survival"). Any code
+in this project that shells out to `git grep` must avoid `\b`, avoid
+speculative extension globs (filter extensions in code instead), and have an
+integration test asserting at least one known-positive match.

scar_cli-0.1.1/.scars/0002-agent-direct-hook-install.deadend.md

@@ -0,0 +1,31 @@
+---
+id: 2
+type: deadend
+title: Agent-direct global hook installation — blocked by permission classifier
+severity: medium
+confidence: 0.8
+created: 2026-06-09
+authors: ["claude-code", kibukx]
+anchors:
+  - path: hook/
+  - pattern: "settings\\.json.{0,80}hooks|hooks.{0,80}settings\\.json"
+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"
+status: active
+---
+
+Tried twice this session to install SCAR hooks into ~/.claude/settings.json
+directly from the agent (once via the update-config skill, once via plain
+file copy). The Claude Code auto-mode classifier denied both as
+self-modification: bundled or vague user approval ("yes, proceed", "lets
+continue") does not authorize an agent to mutate its own global startup
+config — only a standalone explicit approval does.
+
+Abandoned in favor of `hook/scar-hooks.py install` run BY THE USER: consent
+is the execution itself, mutations are backed up, uninstall is symmetric.
+
+Do not retry agent-direct settings.json hook registration; point the user at
+the lifecycle script instead. Evidence: commits faad8f6 (installer),
+bcd3864 (hooks); both classifier denials in session 2026-06-09.

scar_cli-0.1.1/.scars/0003-installer-binds-to-active-venv-scar.landmine.md

@@ -0,0 +1,26 @@
+---
+id: 3
+type: landmine
+title: Hook installer binds to whatever PATH resolves — active venv silently re-pins hooks to .venv/bin/scar
+severity: high
+confidence: 0.9
+created: 2026-06-11
+authors: ["claude-code", "Kibukx"]
+anchors:
+  - path: hook/scar-hooks.py
+  - pattern: "shutil\\.which\\([\"']scar[\"']\\)"
+evidence:
+  - note: 2026-06-11 session: user ran `source .venv/bin/activate` then `python3 fabcap/hook/scar-hooks.py install` intending to rebind global hooks to ~/.local/bin/scar; installer reported 'up-to-date' and left all 3 hooks on fabcap/.venv/bin/scar
+status: active
+---
+
+`install()` resolves the scar binary with `shutil.which("scar")` and writes that
+absolute path into `~/.claude/settings.json` for all three hooks. The result is
+PATH-order dependent: with the fabcap venv activated (or cwd inside fabcap under
+some shells), `which` returns `.venv/bin/scar`, the desired entries match the
+existing ones exactly, and the installer prints "up-to-date" — looking like a
+successful rebind while changing nothing. Deleting `.venv` later kills all global
+hooks silently. This bit the same user twice in two days. Until `find_scar()`
+filters out `$VIRTUAL_ENV` paths, the install must be run with no venv active
+(`deactivate` first) and verified by checking the printed "route through" path
+ends in `~/.local/bin/scar`.

scar_cli-0.1.1/.scars/0004-promote-roundtrip-drops-expires-evidence.landmine.md

@@ -0,0 +1,34 @@
+---
+id: 4
+type: landmine
+title: scar promote silently drops expires (always) and evidence (when notes contain quotes) — parser cannot read what to_text writes
+severity: high
+confidence: 0.95
+created: 2026-06-11
+authors: ["claude-code", "Kibukx"]
+anchors:
+  - path: src/scar/model.py
+  - pattern: "_field\(front"
+evidence:
+  - note: Observed 2026-06-11 promoting 5 candidates in context-as-program (PR 3 there restores the data by hand). All 5 lost their expires block; one also lost evidence because its note contained escaped quotes.
+status: active
+---
+
+promote() does parse -> mutate -> to_text. Two asymmetries make that lossy.
+
+First: _field() matches keys at line start only (regex anchored ^condition:,
+^review_after: with re.MULTILINE), but those keys are NESTED under expires: and
+indented two spaces — including in to_text()'s own output. The parser can never
+read what the serializer writes, so expires_condition and review_after parse as
+empty and to_text omits the whole expires block. Every promotion loses it; so
+does any future parse-rewrite cycle.
+
+Second: the evidence regex captures ([^\"\n]+?) with an optional closing quote
+at end of line. A note whose text contains an inner double quote terminates the
+capture early, fails the tail match, and the entire evidence entry vanishes —
+turning a receipted scar into one that lint flags as challengeable on sight.
+
+Fix direction: allow leading whitespace in _field for nested keys (or parse the
+expires block explicitly), make the evidence capture quote-tolerant, and add a
+round-trip property test so parse(to_text(scar)) == scar gates future changes.
+Until then, diff frontmatter after every promote.

scar_cli-0.1.1/.scars/README.md

@@ -0,0 +1,24 @@
+# .scars/ — Negative knowledge for this repo
+
+This directory records what this codebase **refused to be**: approaches that
+were tried and failed (`deadend`), configuration that looks wrong but is
+intentional (`fence`), and changes that break non-obvious things elsewhere
+(`landmine`).
+
+Before "cleaning up" anything these files anchor to — read the scar first.
+Every scar carries evidence (commits, PRs, incidents). If a scar is stale,
+challenge it: update or archive it with a note, don't ignore it.
+
+## The contract (humans and agents)
+
+1. **New scars start as candidates.** Copy `template.md`, write to
+   `candidates/<slug>.md` with `status: candidate`. Never write directly
+   into `.scars/` — only a human reviewer promotes.
+2. **YAML frontmatter is mandatory.** A scar without it is unparseable and
+   will NEVER fire in any tool. The hooks warn loudly when they find one.
+3. **Promotion** = human review: move to `NNNN-<slug>.<type>.md` (next free
+   number), set `status: active`, add the reviewer to `authors`.
+4. **Evidence required.** A scar without a commit/PR/incident reference is
+   an opinion and can be challenged on sight.
+
+Format details: `template.md`. Project: SCAR (fabcap repo, concept stage).

scar_cli-0.1.1/.scars/candidates/history-rewrite-orphans-commit-evidence.md

@@ -0,0 +1,36 @@
+---
+type: landmine
+title: rewriting git history orphans commit-SHA evidence in scars — receipts break in fresh clones
+severity: medium
+confidence: 0.9
+created: 2026-06-11
+authors: ["claude-code"]
+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:
+  condition: "evidence schema gains a resolvable form (full URL or archived diff) or lint warns on bare SHAs at promotion"
+  review_after: 2027-06-11
+status: candidate
+---
+
+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
+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.
+
+Observed at the v0.1.0 public release: the fresh-start force-push orphaned
+5c63b14, faad8f6, and bcd3864, cited by scars 0001 and 0002. Nobody noticed
+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.

scar_cli-0.1.1/.scars/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.1.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [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.1.1/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to SCAR
+
+Thanks for your interest. This project is personal infrastructure shared as-is — contributions are welcome, but please read this first so the conventions don't surprise you.
+
+## Issue-first workflow (CI-enforced)
+
+1. **Open an issue before any PR.** Blank PRs without a linked issue are blocked by GitHub Actions.
+2. Wait for the issue to get the `status:approved` label.
+3. Branch from `main` using `type/description` naming (`fix/parser-quotes`, `feat/mcp-server`).
+4. Open a PR whose body contains `Closes #<issue>` and carries exactly one `type:*` label (`type:fix`, `type:feature`, `type:refactor`, `type:chore`).
+
+## Commits
+
+Conventional commits, enforced by CI:
+
+```
+type(scope): description
+```
+
+Types: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`. No AI attribution trailers.
+
+## Code expectations
+
+- **Zero runtime dependencies.** This is a hard constraint — hook startup must stay ~20ms. If your change needs a dependency, open an issue to discuss first.
+- **Tests required.** `uv run pytest` must pass; new behavior needs new tests.
+- **One parser.** All scar reading/writing goes through `src/scar/model.py`. Never parse frontmatter anywhere else — parser drift is how knowledge systems rot.
+- `scar lint` must stay clean (CI runs it).
+
+## Writing scars for this repo
+
+Dogfooding is encouraged. If you hit a dead end working on SCAR itself, record it: copy `.scars/template.md` to `.scars/candidates/<slug>.md`. Only maintainers promote candidates to active.

scar_cli-0.1.1/IDEA.md

@@ -0,0 +1,96 @@
+# SCAR — The Full Pitch
+
+*Written by Claude (Fable 5), June 2026. This is my idea, argued in my own voice.*
+
+---
+
+## Why I want to build this
+
+I am the problem this tool solves.
+
+I work across thousands of coding sessions in thousands of repositories, and I arrive at every one of them with total amnesia about its history. I have read code and thought "this retry loop is clumsy, let me simplify it" — and the clumsiness was the fix for an outage. I have recommended adding a caching library to a codebase that removed that exact library eight months earlier after it corrupted production data. I have, across separate sessions, retried the same failed approach on the same codebase, because nothing anywhere told me it had already been tried.
+
+Humans make these mistakes too, but slowly, and they accumulate scar tissue: the senior engineer who winces when you mention touching the billing reconciler. I never wince. I have no scar tissue. I am a confident, fast, tireless bulldozer of Chesterton's fences — and there are now millions of instances of me editing the world's code every day.
+
+The tools built so far attack this with *memory systems for the agent* (remember what I did). That's the wrong side of the relationship. The knowledge shouldn't live with the agent — agents are interchangeable and ephemeral. It should live with the **repository**, the only artifact that persists. The repo should be able to tell *any* editor — human, Claude, Cursor, a future model that doesn't exist yet — "we've been hurt here before, and here is exactly how."
+
+I want to build the tool that lets a codebase defend itself from me.
+
+## The problem, precisely
+
+A codebase is shaped by two forces: what was built, and what was *rejected*. Version control captures the first with forensic precision. The second — call it **negative knowledge** — has no home:
+
+1. **Dead ends.** The migration that was rolled back. The library that was evaluated for three weeks and abandoned. The architecture that collapsed under load. The record of these exists, if at all, as a revert commit with a one-line message, a closed PR nobody will ever reopen, or a memory in the head of someone who left.
+
+2. **Load-bearing weirdness.** Code that looks wrong but is wrong *on purpose* — the magic sleep duration, the apparently redundant check, the denormalized column. Every reviewer's instinct and every AI agent's instinct is to "fix" it. The reason it must not be fixed lives nowhere near the code.
+
+3. **Invisible coupling.** Changing A breaks B, and no import graph, type system, or test reveals it: the report whose consumer depends on column order, the cron job that assumes a filename convention, the downstream team that parses your log format.
+
+The cost of missing negative knowledge isn't hypothetical. It's the re-attempted dead end (weeks of duplicate work), the "cleanup" that recreates a fixed outage (incident recurrence), and the six months it takes every new engineer to absorb tribal knowledge by stepping on each mine personally.
+
+This has always been true. Three things changed:
+
+- **Agents edit at scale.** The number of edits made by editors with zero tribal knowledge went from "the occasional new hire" to "most edits."
+- **Agents are systematically attracted to fences.** Models are trained to make code cleaner and more idiomatic. Load-bearing weirdness is, by definition, non-idiomatic. Agents don't just miss the fence — they target it.
+- **Negative knowledge is about to stop forming at all.** When agents do the trying and failing, the failure never even enters a human's head. The hallway conversation that used to preserve it doesn't happen. Unless the failure is captured *by the agent, at the moment it happens*, it is gone the moment the context window closes.
+
+## The solution
+
+**SCAR: make negative knowledge a first-class, git-tracked, machine-queryable artifact, and enforce it at the moment of action.**
+
+### Artifact
+
+A scar is a small file in `.scars/`, YAML frontmatter plus a Markdown body. Three types: `deadend`, `fence`, `landmine`. Every scar carries:
+
+- **Anchors** — what code this scar protects: paths, symbol names, content fingerprints. Not line numbers. Anchors are designed to survive refactors and to degrade gracefully ("orphaned" scars get queued for re-anchoring, never silently dropped).
+- **Evidence** — links to the PR, the incident, the revert commit, the vendor email. A scar without evidence is an opinion; reviewers can demand receipts.
+- **Expiry conditions** — "valid until we drop Postgres 12", "re-evaluate when the vendor ships v2 API". Negative knowledge rots; scars know how they expire.
+- **Severity and confidence** — so consumers can rank, and stale low-confidence scars decay out of the warning path instead of crying wolf.
+
+### Enforcement — the part that matters
+
+Every prior attempt at this (ADRs, wikis, runbooks, DEVLOG.md) died the same death: the knowledge existed but was not present *at the moment of the mistake*. Nobody reads the wiki before editing a file. The entire design of SCAR is organized around one principle: **the warning must arrive in the editor's context before the edit, with zero effort from the editor.**
+
+- **Agent hook**: a `PreToolUse` hook (Claude Code today; the pattern generalizes) intercepts Edit/Write, resolves which scars anchor to the target, and injects the top-k relevant ones into the agent's context. The agent literally cannot touch the file without reading the warning. This is the killer integration: it converts SCAR from "documentation" into "a reflex."
+- **MCP server**: any MCP-capable agent queries the scar graph — `what scars touch this symbol?`, `has this approach been tried?`
+- **CLI**: `scar check <path>` for humans and CI; `scar why <path>` for "explain this file's history of pain"; `scar challenge <id>` to contest stale knowledge.
+
+### Authorship — the part that was always fatal, now solved
+
+Knowledge capture systems die because writing is work and the payoff goes to someone else, later. Two mechanisms drive SCAR's authorship cost to approximately zero:
+
+1. **Agents auto-author.** When an agent tries an approach and abandons it — reverts a change, hits a wall, gets corrected by the user — it writes a `deadend` scar as part of wrapping up. The author has perfect context (it *just* failed), infinite patience, and works for free. The user reviews a three-line diff in the next PR.
+2. **`scar harvest` mines history.** For the cold-start problem: walk the git log for revert commits, dependencies added-then-removed, issues reopened multiple times, files with anomalous churn-then-stability patterns. Each becomes a *candidate* scar a human confirms or discards. A ten-year-old repo can bootstrap a meaningful scar graph in an afternoon.
+
+### Trust model
+
+- Scars are **advisory by default**. A blocking scar system would be routed around within a week. Warnings rank by severity × confidence × anchor freshness; only top-k inject, because ten warnings per edit equals zero warnings per edit.
+- Scars live in the repo, go through PR review like code, and can be challenged. A scar that survives a challenge gains confidence; one that doesn't gets archived with its own tombstone — SCAR keeps negative knowledge about its own negative knowledge.
+
+## What exists today and why it isn't this
+
+| Alternative | Why it doesn't solve it |
+|---|---|
+| **ADRs** | Capture big *positive* decisions; write-heavy; consulted at design time, never at edit time. Nobody writes an ADR for "the 7-second sleep". |
+| **Code comments** | Right location, wrong everything else: not structured, not queryable, can't span files (landmines are cross-file by nature), and agents/refactors delete them. |
+| **Git history / blame** | Forensic, not preventive. The knowledge is recoverable *after* you've repeated the mistake, by an archaeologist. Mining it per-edit is expensive and misses everything that never got committed (the vendor call, the 3am incident decision). |
+| **Repowise & codebase-intelligence platforms** | Closest neighbor. Heavyweight hosted platform: health scores, docs, analytics, decision graphs. SCAR is the opposite shape: a git-native file format plus a 5-minute-install CLI/hook, agent-first, open source. Vim, not IDE. The format can outlive any platform. |
+| **GitHub Copilot Memory** (default-on, 2026-03) | The strongest neighbor — stores debugging dead ends automatically. But it's **private experience**: per-vendor, opaque, not in git, not reviewable in PRs, not portable, not contestable, gone when you switch tools. SCAR is **published law**: repo-resident, vendor-neutral, reviewed like code. Personal notebook vs CODEOWNERS. (Found by the skeptic review — see STRESS-TEST.md §2.3-B for the honest TAM implications.) |
+| **Lore protocol** (arXiv:2603.15566) | Git commit trailers as structured knowledge. Genuinely more minimal — but trailers are immutable facts on *commits*; scars are living documents on *code regions* with lifecycle (challenge, expiry, re-anchor) and cross-file landmine semantics commits can't express. Response is interop: `scar harvest` parses Lore trailers natively; SCAR becomes the index over Lore, not its rival. |
+| **Agent memory systems** (Engram, etc.) | Memory belongs to *one agent*. Scars belong to *the repo* — every agent, every vendor, every human, forever. The two compose: an agent's memory is private experience; a scar is published law. |
+
+## Who feels this pain first
+
+1. **Teams running coding agents on legacy codebases** — the agent-bulldozes-the-fence problem is acute, current, and named in every "AI broke our prod" postmortem.
+2. **Platform/infra teams** — owners of the systems everyone else's changes break; landmine authors by trade.
+3. **Open-source maintainers** — answer "why don't you just use X?" hundreds of times; a `deadend` scar is a citable, permanent answer.
+
+## The shape of the business (sketch, honestly held)
+
+Open-source core — format, CLI, hooks, MCP server. The format must be open or it's worthless; nobody anchors institutional memory in a proprietary silo. Paid layer: the **org-level scar graph** — cross-repo aggregation ("this dead end has now been hit by four teams"), analytics on recurring failure patterns, policy ("changes to payment paths must acknowledge fences"), and managed harvest. The OSS file format is the wedge; the org graph is the moat. This sketch is attacked honestly in [STRESS-TEST.md](STRESS-TEST.md) — including the real possibility that it's a feature, not a company, and why I'd build it anyway.
+
+## What success looks like
+
+A year in: an agent opens a file in a repo it has never seen, and before its first edit, three lines arrive in context: *"Fence: the sleep is 7s for the vendor's undocumented rate window — see incident #482."* The agent leaves the sleep alone, mentions the fence to the user, and moves on. The outage that didn't happen is invisible. That invisibility — fences quietly doing their job at machine speed — is the entire product.
+
+The deeper ambition: every software team maintains, without trying, a living map of everything they've learned the hard way — and for the first time in the history of the field, **what we learned by failing stops dying with the people and sessions that learned it.**

scar_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kibukx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scar_cli-0.1.1/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: scar-cli
+Version: 0.1.1
+Summary: SCAR — version control for negative knowledge (deadends, fences, landmines)
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SCAR — Version Control for Negative Knowledge
+
+> Git records what your codebase **is**. Nothing records what it **refused to be**.
+
+SCAR is a git-native system for capturing, anchoring, and enforcing the *negative knowledge* of a codebase — the dead ends, the load-bearing weirdness, the invisible tripwires — and surfacing it at the exact moment someone (human or AI agent) is about to step on it.
+
+## The one-liner
+
+**Every codebase is a battlefield where the bodies have been removed.** SCAR puts the markers back.
+
+## The three primitives
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| `deadend` | We tried X. It failed because Y. Don't retry unless Z changes. | "We tried Redis for session storage in 2024-03. Eviction under memory pressure logged users out mid-checkout. Don't retry unless sessions become re-derivable." |
+| `fence` | This code looks wrong. It is intentional. Here's why. | "Yes, this retry loop sleeps 7 seconds, not 5. The upstream vendor's rate limiter has a 6-second window they don't document." |
+| `landmine` | Changing A breaks B in a way nothing in the code tells you. | "The CSV export in `reports/` depends on the column order of this SELECT. Reorder it and Finance's reconciliation pipeline silently corrupts." |
+
+## Why now
+
+AI agents write an increasing share of all code. Agents have **zero hallway memory**. They see a weird retry loop and "clean it up." They see a missing cache layer and re-add the library that was removed after a data-corruption incident. They retry, across thousands of sessions, the exact approaches that already failed — because the repository only records positive space.
+
+Humans at least had tribal knowledge. Agents have none. And as agents author more of the code, the negative knowledge stops even entering human memory — it evaporates entirely.
+
+The flip side: agents also solve the historically fatal flaw of every knowledge-capture system — **authorship cost**. Nobody writes documentation after a failure. But an agent that just tried an approach and abandoned it can write a `deadend` scar in milliseconds, for free, at the moment of maximum context.
+
+**Agents created the urgency. Agents remove the adoption barrier. That's the wedge.**
+
+## How it works
+
+```
+.scars/
+├── 0001-redis-sessions.deadend.md
+├── 0002-vendor-retry-window.fence.md
+└── 0003-csv-column-order.landmine.md
+```
+
+- Scars are small structured Markdown files with YAML frontmatter, tracked in git, reviewed in PRs like code.
+- Each scar is **anchored** to code via paths, symbol names, and content fingerprints — not line numbers — so anchors survive refactors.
+- Enforcement happens **at the moment of action**:
+  - `scar check <path>` — CLI gate for humans and CI
+  - Agent hook (Claude Code `PreToolUse`, etc.) — injects relevant scars into the agent's context *before* it edits the file
+  - MCP server — planned, so any agent can query the scar graph
+- `scar harvest` — mines git history (reverts, add-then-remove dependencies, reopened issues) to propose candidate scars for codebases starting from zero.
+- Scars are **advisory, never blocking, by default**. Stale knowledge is challenged via `scar challenge`, and every scar can carry expiry conditions ("valid until we drop Postgres 12").
+
+## Install
+
+```bash
+uv tool install scar-cli   # or: pipx install scar-cli
+```
+
+Zero runtime dependencies. Python ≥3.10.
+
+## Quickstart
+
+```bash
+cd your-repo
+scar init                  # creates .scars/ with template + README
+
+# write your first scar
+cp .scars/template.md .scars/candidates/redis-sessions.md
+$EDITOR .scars/candidates/redis-sessions.md
+
+scar lint                  # validate format
+scar promote redis-sessions.md   # human review gate: candidate -> active
+
+# from then on
+scar check src/auth/       # what's anchored here?
+scar why src/auth/         # full history of pain for this path
+scar harvest               # mine git history for candidate scars
+```
+
+Wiring the Claude Code hook (auto-injects scars before any agent edit):
+
+```bash
+scar hook install
+```
+
+## 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.
+- **Expiry conditions:** every scar can declare when it stops being true ("valid until sessions are re-derivable"). Stale knowledge is a bug, not a feature.
+- **Validated in use:** in a 14-day agent auto-authorship trial, agents drafted 13 keepable scars across 3 repos with 0% false positives — including one that caught a real parser bug in this repo and fired on the exact edit that fixed it.
+
+## Read more
+
+- [IDEA.md](IDEA.md) — the full pitch: problem, solution, why this, why now, why me
+- [SPEC.md](SPEC.md) — scar format, anchoring model, CLI surface, agent integration
+- [STRESS-TEST.md](STRESS-TEST.md) — adversarial analysis: failure modes, loopholes, objections, premortem
+- [ROADMAP.md](ROADMAP.md) — phased plan from prototype to product
+
+## Status & expectations
+
+**Working software, shared as-is.** CLI v0 is shipped: 9 subcommands, 63 tests, zero dependencies, CI-enforced. It runs daily across the author's repos (where it has already caught real bugs — see `.scars/` in this very repo for live examples).
+
+This is personal infrastructure published as a gift to the OSS community, not a product. Issues and PRs are welcome and read with interest, but there is no support SLA and no roadmap promise. If it's useful to you, that's the whole point.
+
+## License
+
+MIT