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

scar_cli-0.6.1/.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.5.0 → scar_cli-0.6.1}/.github/workflows/release.yml

@@ -19,7 +19,10 @@ jobs:
       - id: rp
         uses: googleapis/release-please-action@v4
         with:
-          release-type: python
+          # config-file + manifest replace the inline release-type so extra-files
+          # can keep plugin/plugin.json's version in lock-step with pyproject (#62).
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
 
   publish:
     needs: release-please

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

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

scar_cli-0.6.1/.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.5.0 → scar_cli-0.6.1}/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.5.0 → scar_cli-0.6.1}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.6.1](https://github.com/Daily-Nerd/Scar/compare/v0.6.0...v0.6.1) (2026-06-26)
+
+
+### Bug Fixes
+
+* **plugin:** sync plugin.json + uv.lock to 0.6.0 + drift guard ([#63](https://github.com/Daily-Nerd/Scar/issues/63)) ([fe21ed6](https://github.com/Daily-Nerd/Scar/commit/fe21ed6046ea4cabc8abd2ca681e85d02991be6a))
+
+## [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scar-cli
-Version: 0.5.0
+Version: 0.6.1
 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.5.0 → scar_cli-0.6.1}/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.6.1/plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "scar",
+  "version": "0.6.1",
+  "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.1/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.1/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.5.0 → scar_cli-0.6.1}/pyproject.toml

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

scar_cli-0.6.1/release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    }
+  }
+}

{scar_cli-0.5.0 → scar_cli-0.6.1}/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")

{scar_cli-0.5.0 → scar_cli-0.6.1}/src/scar/cli.py

@@ -480,11 +480,14 @@ def _cmd_harvest(args) -> int:
 
 
 def _cmd_agent(args) -> int:
-    from .agent import config, doctor
+    from .agent import config, doctor, skill
     if args.agent_command == "doctor":
         for line in doctor(Path.cwd()):
             print(line)
         return 0
+    if args.agent_command == "skill":
+        print(skill())
+        return 0
     try:
         print(config(args.target))
     except ValueError as exc:
@@ -502,6 +505,15 @@ def _cmd_hook_lifecycle(args) -> int:
     return status()
 
 
+def _cmd_skill_lifecycle(args) -> int:
+    from .installer import skill_install, skill_status, skill_uninstall
+    if args.kind == "install":
+        return skill_install(dry=args.dry_run)
+    if args.kind == "uninstall":
+        return skill_uninstall(dry=args.dry_run)
+    return skill_status()
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="scar",
                                      description="version control for negative knowledge")
@@ -562,6 +574,11 @@ def main(argv: list[str] | None = None) -> int:
     p.add_argument("--dry-run", action="store_true",
                    help="show lifecycle changes without writing settings")
 
+    p = sub.add_parser("skill", help="install, remove, or inspect the scar-authoring skill")
+    p.add_argument("kind", choices=["install", "uninstall", "status"])
+    p.add_argument("--dry-run", action="store_true",
+                   help="show changes without writing to ~/.claude/skills")
+
     sub.add_parser("mcp", help="run the SCAR MCP stdio server")
 
     p = sub.add_parser("agent", help="agent integration helpers")
@@ -569,6 +586,7 @@ def main(argv: list[str] | None = None) -> int:
     agent_sub.add_parser("doctor", help="show local agent integration readiness")
     cfg = agent_sub.add_parser("config", help="print config for an agent runtime")
     cfg.add_argument("target", choices=["codex", "cursor", "opencode", "windsurf"])
+    agent_sub.add_parser("skill", help="print the scar-authoring skill body")
 
     p = sub.add_parser("inject", help="machine mode for hooks: JSON or silence")
     p.add_argument("--path")
@@ -586,6 +604,8 @@ def main(argv: list[str] | None = None) -> int:
             return _cmd_hook_lifecycle(args)
         from .hooks import HANDLERS  # hot path: imports nothing beyond library
         return HANDLERS[args.kind]()
+    if args.command == "skill":
+        return _cmd_skill_lifecycle(args)
     if args.command in ("challenge", "archive"):
         status = {"challenge": "challenged", "archive": "archived"}[args.command]
         return _cmd_transition(args, status)

{scar_cli-0.5.0 → scar_cli-0.6.1}/src/scar/harvest.py

@@ -326,6 +326,31 @@ _SECTION_TYPES = {
 }
 
 
+def _candidate_path(signal_type: str, c: dict) -> str:
+    """Repo-relative path a candidate points at ('' if it has none, e.g. reverts)."""
+    if signal_type == "comment":
+        return c.get("location", "").split(":", 1)[0]
+    if signal_type == "deleted_component":
+        return c.get("component", "")
+    if signal_type == "flapping":
+        return c.get("file", "")
+    return ""
+
+
+def _in_scars(path: str) -> bool:
+    """True if a candidate path lives under the repo's own .scars/ tree.
+
+    Harvest must not re-surface a repo's own negative knowledge as a fresh
+    candidate. Comment-archaeology is the loud case — scar bodies quote the very
+    DO-NOT/load-bearing/intentional prose the grep hunts for, so every promoted
+    scar self-matches (same self-ref class as #35). Excluded uniformly (#55).
+
+    Matches `.scars` as any path segment, not just the root — nested scar trees
+    (e.g. an experiment fixture's own .scars/) are the same self-ref noise.
+    """
+    return ".scars" in path.split("/")
+
+
 def _annotate_and_sort(candidates: list[dict], signal_type: str,
                        now_months: int | None = None) -> list[dict]:
     """Add 'score' and 'id' fields to each candidate, then sort by score desc."""
@@ -345,6 +370,14 @@ def harvest(repo: Path) -> dict[str, list[dict]]:
         "flapping": _flapping(repo),
         "comments": _comment_archaeology(repo),
     }
+    # Drop a repo's own .scars/ tree — self-ref noise, never a fresh candidate
+    # (#55). Filtered in code, not via a git grep pathspec (landmine #1: a
+    # zero-match pathspec silently empties the whole result set).
+    raw = {
+        section: [c for c in candidates
+                  if not _in_scars(_candidate_path(_SECTION_TYPES[section], c))]
+        for section, candidates in raw.items()
+    }
     return {
         section: _annotate_and_sort(candidates, _SECTION_TYPES[section], now_months)
         for section, candidates in raw.items()

{scar_cli-0.5.0 → scar_cli-0.6.1}/src/scar/installer.py

@@ -16,6 +16,8 @@ from pathlib import Path
 CLAUDE_DIR = Path.home() / ".claude"
 HOOKS_DIR = CLAUDE_DIR / "hooks"
 SETTINGS = CLAUDE_DIR / "settings.json"
+SKILLS_DIR = CLAUDE_DIR / "skills"
+SKILL_NAME = "scar-authoring"
 
 LEGACY_SCRIPTS = ("scar-precheck.py", "scar-session-notice.py", "scar-stop-drafter.py")
 OURS_RE = re.compile(r"(scar[^ ]*) hook (precheck|session-notice|stop-drafter)"
@@ -152,3 +154,44 @@ def status() -> int:
                  else "installed" if ours else "not installed")
         print(f"{spec['kind']:16} {spec['event']:13} {state}")
     return 0
+
+
+def _skill_source() -> Path:
+    from importlib.resources import files
+    return Path(str(files("scar").joinpath("skills") / SKILL_NAME))
+
+
+def skill_install(dry: bool = False) -> int:
+    src = _skill_source()
+    if not src.is_dir():
+        print(f"skill source not found: {src}")
+        return 1
+    dest = SKILLS_DIR / SKILL_NAME
+    print(f"[skill] install {SKILL_NAME} -> {dest}")
+    if dry:
+        print("install: done (dry-run, nothing written)")
+        return 0
+    SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+    print("install: done.")
+    return 0
+
+
+def skill_uninstall(dry: bool = False) -> int:
+    dest = SKILLS_DIR / SKILL_NAME
+    if not dest.exists():
+        print(f"[skill] {SKILL_NAME}: not installed")
+        return 0
+    print(f"[skill] remove {dest}")
+    if not dry:
+        shutil.rmtree(dest)
+    print("uninstall: done" + (" (dry-run, nothing written)" if dry else "."))
+    return 0
+
+
+def skill_status() -> int:
+    dest = SKILLS_DIR / SKILL_NAME
+    print(f"skill {SKILL_NAME}: {'installed' if dest.exists() else 'not installed'} ({dest})")
+    return 0

{scar_cli-0.5.0 → scar_cli-0.6.1}/src/scar/mcp.py

@@ -173,7 +173,14 @@ TOOLS = [
     },
     {
         "name": "scar_draft",
-        "description": "Write a candidate scar to .scars/candidates/ for human promotion.",
+        "description": (
+            "Write a candidate scar to .scars/candidates/ for human promotion. "
+            "Use for negative knowledge: deadend (tried+failed), fence (looks "
+            "wrong but intentional), or landmine (touching A breaks B). Prefer a "
+            "path: anchor — pattern: regexes over-escape in YAML and silently "
+            "self-match. Writes only to candidates/ and lints before writing; a "
+            "human promotes. See the scar-authoring skill (scar agent skill)."
+        ),
         "inputSchema": {
             "type": "object",
             "required": ["type", "title", "anchors", "body"],

scar_cli-0.6.1/src/scar/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.1/src/scar/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.5.0 → scar_cli-0.6.1}/tests/test_cli.py

@@ -649,3 +649,11 @@ def test_harvest_label_date_is_monkeypatchable(harvest_repo, tmp_path, monkeypat
     main(["harvest", str(harvest_repo), "--label", cid, "keep"])
     rec = json.loads(labels.read_text(encoding="utf-8").splitlines()[0])
     assert rec["date"] == "1999-12-31"
+
+
+def test_agent_skill_prints_body_with_three_types(repo, capsys):
+    assert main(["agent", "skill"]) == 0
+    out = capsys.readouterr().out
+    assert "name: scar-authoring" in out
+    for kind in ("deadend", "fence", "landmine"):
+        assert kind in out

scar_cli-0.6.1/tests/test_docs.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def test_agents_md_documents_authoring_skill_access():
+    text = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+    assert "scar agent skill" in text
+    assert "scar-authoring" in text
+
+
+def test_readme_documents_plugin_and_cli_install():
+    text = (ROOT / "README.md").read_text(encoding="utf-8")
+    assert "scar skill install" in text

{scar_cli-0.5.0 → scar_cli-0.6.1}/tests/test_harvest.py

@@ -65,6 +65,46 @@ def test_clean_repo_yields_empty_sections(tmp_path):
     assert result["reverts"] == [] and result["deleted_components"] == []
 
 
+def test_excludes_scars_dir_from_candidates(tmp_path):
+    """Scar #55: harvest must not surface candidates pointing into .scars/.
+
+    Comment-archaeology greps DO-NOT/load-bearing/intentional prose, and a
+    repo's own scar bodies are full of exactly that. Without an exclusion every
+    promoted scar self-matches and reads as a fresh candidate (same self-ref
+    class as #35). .scars/** must produce zero candidates across all detectors.
+    """
+    git(tmp_path.parent, "init", "-q", "-b", "main", str(tmp_path))
+    git(tmp_path, "config", "user.email", "t@t")
+    git(tmp_path, "config", "user.name", "t")
+    # real code comment — SHOULD still be harvested
+    (tmp_path / "app.py").write_text(
+        "# DO NOT remove this init — load-bearing\nx = 1\n")
+    # promoted scar bodies full of trigger prose — must NOT be harvested,
+    # at the repo root AND nested (e.g. a fixture's own .scars/ tree).
+    body = ("---\ntype: deadend\n---\n"
+            "This is intentional. DO NOT remove; load-bearing workaround.\n")
+    root_scars = tmp_path / ".scars"
+    root_scars.mkdir()
+    (root_scars / "0001-x.deadend.md").write_text(body)
+    nested_scars = tmp_path / "experiments" / "fixture" / ".scars"
+    nested_scars.mkdir(parents=True)
+    (nested_scars / "0001-y.fence.md").write_text(body)
+    git(tmp_path, "add", "-A")
+    git(tmp_path, "commit", "-qm", "feat: code + scars")
+
+    result = harvest(tmp_path)
+    locations = [c["location"] for c in result["comments"]]
+    assert any(loc.startswith("app.py") for loc in locations), \
+        "real code comment should still be harvested"
+    all_paths = (
+        locations
+        + [c["component"] for c in result["deleted_components"]]
+        + [c["file"] for c in result["flapping"]]
+    )
+    assert not any(".scars" in p.split("/") for p in all_paths), \
+        "no candidate may point into any .scars/ tree (self-ref noise, #55)"
+
+
 # ---------------------------------------------------------------------------
 # Ranking / scoring tests
 # ---------------------------------------------------------------------------

{scar_cli-0.5.0 → scar_cli-0.6.1}/tests/test_installer.py

@@ -102,3 +102,36 @@ def test_cli_hook_status_reports_each_hook(isolated_settings, capsys):
     assert "session-notice" in out
     assert "stop-drafter" in out
     assert out.count("not installed") == 3
+
+
+def test_skill_install_dry_run_reports_target_without_writing(tmp_path, monkeypatch):
+    monkeypatch.setattr(installer, "CLAUDE_DIR", tmp_path / ".claude")
+    monkeypatch.setattr(installer, "SKILLS_DIR", tmp_path / ".claude" / "skills")
+    rc = main(["skill", "install", "--dry-run"])
+    assert rc == 0
+    assert not (tmp_path / ".claude" / "skills" / "scar-authoring").exists()
+
+
+def test_skill_install_copies_skill_then_uninstall_removes_it(tmp_path, monkeypatch):
+    monkeypatch.setattr(installer, "CLAUDE_DIR", tmp_path / ".claude")
+    monkeypatch.setattr(installer, "SKILLS_DIR", tmp_path / ".claude" / "skills")
+    assert main(["skill", "install"]) == 0
+    dest = tmp_path / ".claude" / "skills" / "scar-authoring" / "SKILL.md"
+    assert dest.exists() and "scar-authoring" in dest.read_text()
+    assert main(["skill", "uninstall"]) == 0
+    assert not dest.parent.exists()
+
+
+def test_skill_reinstall_over_existing_removes_stale_files(tmp_path, monkeypatch):
+    # Reinstall must rmtree the existing dir before copy: a stale file left from
+    # a prior install must NOT survive a second install. Guards against a refactor
+    # to copytree(dirs_exist_ok=True), which would leave orphaned files behind.
+    monkeypatch.setattr(installer, "CLAUDE_DIR", tmp_path / ".claude")
+    monkeypatch.setattr(installer, "SKILLS_DIR", tmp_path / ".claude" / "skills")
+    assert main(["skill", "install"]) == 0
+    dest = tmp_path / ".claude" / "skills" / "scar-authoring"
+    stale = dest / "STALE-LEFTOVER.txt"
+    stale.write_text("orphan from a previous layout", encoding="utf-8")
+    assert main(["skill", "install"]) == 0
+    assert not stale.exists()
+    assert (dest / "SKILL.md").exists()

{scar_cli-0.5.0 → scar_cli-0.6.1}/tests/test_mcp.py

@@ -90,3 +90,14 @@ def test_scar_draft_writes_candidate_only(tmp_path):
     assert data["status"] == "candidate"
     assert data["candidate"].startswith(".scars/candidates/")
     assert not list((tmp_path / ".scars").glob("*.deadend.md"))
+
+
+from scar.mcp import TOOLS
+
+
+def test_scar_draft_description_carries_authoring_digest():
+    draft = next(t for t in TOOLS if t["name"] == "scar_draft")
+    desc = draft["description"]
+    for kind in ("deadend", "fence", "landmine"):
+        assert kind in desc
+    assert "candidate" in desc

scar_cli-0.6.1/tests/test_plugin.py

@@ -0,0 +1,57 @@
+"""Claude Code plugin manifest validity + skill mirror drift guard."""
+
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def test_plugin_version_matches_pyproject():
+    # plugin.json carries its own version; release-please bumps only pyproject,
+    # so the two silently drift unless guarded. Regex (not tomllib) keeps this
+    # stdlib-only and Python 3.10-safe.
+    pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    match = re.search(r'(?m)^version\s*=\s*"([^"]+)"', pyproject)
+    assert match, "version not found in pyproject.toml"
+    py_version = match.group(1)
+    plugin = json.loads((ROOT / "plugin" / "plugin.json").read_text(encoding="utf-8"))
+    assert plugin["version"] == py_version, (
+        f"plugin.json version {plugin['version']!r} != pyproject {py_version!r}")
+
+
+def test_plugin_manifest_is_valid_and_declares_three_hook_events():
+    manifest = json.loads((ROOT / "plugin" / "plugin.json").read_text())
+    assert manifest["name"] == "scar"
+    assert set(manifest["hooks"]) == {"PreToolUse", "SessionStart", "Stop"}
+
+
+def test_marketplace_manifest_lists_the_plugin():
+    market = json.loads((ROOT / ".claude-plugin" / "marketplace.json").read_text())
+    names = [p["name"] for p in market["plugins"]]
+    assert "scar" in names
+
+
+def test_plugin_skill_mirror_is_byte_identical_to_canonical():
+    canonical = (ROOT / "src" / "scar" / "skills" / "scar-authoring" / "SKILL.md").read_bytes()
+    mirror = (ROOT / "plugin" / "skills" / "scar-authoring" / "SKILL.md").read_bytes()
+    assert mirror == canonical
+    can_tmpl = (ROOT / "src" / "scar" / "skills" / "scar-authoring" / "assets" / "template.md").read_bytes()
+    mir_tmpl = (ROOT / "plugin" / "skills" / "scar-authoring" / "assets" / "template.md").read_bytes()
+    assert mir_tmpl == can_tmpl
+
+
+def test_plugin_hooks_use_bare_path_resolved_scar_command():
+    manifest = json.loads((ROOT / "plugin" / "plugin.json").read_text())
+    expected = {
+        "PreToolUse": "scar hook precheck",
+        "SessionStart": "scar hook session-notice",
+        "Stop": "scar hook stop-drafter",
+    }
+    for event, command in expected.items():
+        commands = [h["command"]
+                    for group in manifest["hooks"][event]
+                    for h in group["hooks"]]
+        assert command in commands, f"{event} must use bare '{command}'"
+        for c in commands:
+            assert not c.startswith("/"), f"{event} command must be PATH-resolved, not absolute: {c}"

scar_cli-0.6.1/tests/test_skill.py

@@ -0,0 +1,36 @@
+"""The packaged scar-authoring skill: canonical content + drift guards."""
+
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+SKILL = ROOT / "src" / "scar" / "skills" / "scar-authoring"
+
+
+def _frontmatter(text: str) -> dict:
+    assert text.startswith("---\n"), "SKILL.md must open with YAML frontmatter"
+    end = text.index("\n---", 4)
+    block = text[4:end]
+    fields = {}
+    for line in block.splitlines():
+        if line and not line[0].isspace() and ":" in line:
+            key = line.split(":", 1)[0].strip()
+            fields[key] = True
+    return fields
+
+
+def test_skill_frontmatter_has_name_and_description():
+    text = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+    fields = _frontmatter(text)
+    assert "name" in fields and "description" in fields
+
+
+def test_skill_covers_all_three_types():
+    text = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+    for kind in ("deadend", "fence", "landmine"):
+        assert kind in text
+
+
+def test_bundled_template_is_byte_identical_to_dot_scars():
+    canonical = (ROOT / ".scars" / "template.md").read_bytes()
+    bundled = (SKILL / "assets" / "template.md").read_bytes()
+    assert bundled == canonical

{scar_cli-0.5.0 → scar_cli-0.6.1}/uv.lock

@@ -79,7 +79,7 @@ wheels = [
 
 [[package]]
 name = "scar-cli"
-version = "0.4.0"
+version = "0.6.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

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

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