scar-cli 0.20.0__tar.gz → 0.22.0__tar.gz

scar_cli-0.22.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,112 @@
+name: Bug report
+description: Something broke — anchoring, hooks, injection, CLI, lint, or stats
+title: "fix: "
+labels: ["bug", "type:fix"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Scar is entirely local — no service, no accounts, no telemetry. That means
+        nothing about your setup reaches us unless you paste it, and the diagnostics
+        below answer most questions in one round-trip.
+
+        **A maintainer must add `status:approved` to this issue before a PR can be
+        opened against it.** CI enforces that, so please wait for the label rather
+        than opening a PR alongside the report.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you did and what broke. Quote error text exactly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. scar init
+        2. scar hook install
+        3. edit a file matching an anchor
+        4. ...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Agent runtime
+      description: Where Scar was running when this happened.
+      options:
+        - Claude Code
+        - Codex
+        - Cursor
+        - opencode
+        - Windsurf / Cascade
+        - An MCP client (scar mcp)
+        - No agent — scar CLI directly
+        - Other (say which in "What happened")
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How is scar installed?
+      description: Matters more than it looks — a local editable install never upgrades.
+      options:
+        - uv tool install
+        - pipx
+        - pip
+        - editable / from source
+        - don't know
+    validations:
+      required: false
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics
+      description: |
+        Paste the output of these. All local; nothing is transmitted by running them.
+
+            scar --version
+            scar status
+            scar hook status
+            scar lint
+
+        If the symbol/tree-sitter extra is involved, add whether you installed
+        `scar-cli[symbols]` — `--force` reinstalls have been known to drop extras.
+      render: text
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: |
+        ### ⚠️ Before you paste anything else
+
+        **Do not paste `scar stats --all-repos` or the raw firing log.** Both are
+        machine-global: they name **every repository on your machine**, including
+        private ones. Plain `scar stats` is scoped to the current repo and is safe.
+
+        If a machine-global number is genuinely relevant, redact the repo names and
+        keep only the counts.
+
+  - type: textarea
+    id: stats
+    attributes:
+      label: "`scar stats` (optional)"
+      description: Current repo only. Useful for injection, retrieval or firing-log bugs.
+      render: text
+    validations:
+      required: false

scar_cli-0.22.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,18 @@
+# Blank issues are disabled: the two templates cover the cases that become
+# work, and anything else is a question, which belongs in Discussions.
+#
+# This is only safe BECAUSE Discussions is enabled (turned on 2026-08-29). If
+# Discussions is ever turned off again, flip this back to true — otherwise
+# someone with a plain "is this the intended behavior?" has no route in at all.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/Daily-Nerd/Scar/discussions
+    about: "Not sure it's a bug? Asking how something is meant to work? Start here — questions get answered faster than they do in issues."
+  - name: Documentation
+    url: https://daily-nerd.github.io/Scar/
+    about: Quickstart, concepts, agent setup, and the methodology behind the measurements.
+  - name: Agent-readable docs (llms.txt)
+    url: https://daily-nerd.github.io/Scar/llms.txt
+    about: If you are an AI agent reading this, start here rather than scraping the site.

scar_cli-0.22.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,70 @@
+name: Feature request
+description: A capability Scar should have, or a pain it should remove
+title: "feat: "
+labels: ["enhancement", "type:feature"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **A maintainer must add `status:approved` to this issue before a PR can be
+        opened against it.** CI enforces that, so please let the idea get a verdict
+        before writing code against it.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: |
+        The pain, as concretely as you can. What happens today that shouldn't, or
+        can't happen that should? Prefer a real case you hit over a hypothetical.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How it would work from your side — commands, flags, output, behavior. Rough is fine.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Workarounds you use today, or other shapes this could take.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Anchoring and matching (path, pattern, symbol, fingerprint, command)
+        - Hooks and agent integration
+        - CLI surface and output
+        - Harvest and authoring
+        - Lint, orphan detection, lifecycle
+        - Measurement — firing log, stats, compliance
+        - Docs and website
+        - Packaging and install
+        - Other / not sure
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        ### Before you write it up
+
+        Two things this project is deliberate about, worth knowing so a proposal
+        does not get bounced for a reason that isn't obvious:
+
+        - **Machine-readable output is a contract.** The `--json` payloads are
+          documented in `SPEC.md` §9. Adding keys is fine; removing or retyping a
+          documented key is breaking.
+        - **Numbers are refused rather than flattered.** Where a metric's
+          denominator is absent, Scar reports `null` instead of a number the data
+          cannot support. Proposals that would report a confident number from thin
+          evidence tend to get pushed back on for that reason alone.

scar_cli-0.22.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,70 @@
+Closes #
+
+<!--
+CI gates this PR (.github/workflows/pr-validation.yml). All of these are checked
+BEFORE review, so getting them right up front saves a round-trip:
+
+1. The body links an issue: `Closes #N` / `Fixes #N` / `Resolves #N`.
+   "Refs #N" does NOT satisfy this check — the regex only accepts those three
+   verbs. If a PR is one stage of a multi-PR issue and you don't want merging it
+   to close the issue, say so in the body and reopen the issue after merge.
+
+2. That linked issue carries the `status:approved` label. A maintainer adds it.
+   If it isn't there yet, the check fails — wait for approval rather than
+   opening the PR early.
+
+3. Exactly ONE `type:*` label on the PR. Note the names, they are not the same
+   as the conventional-commit types:
+       type:feature   type:fix   type:docs   type:refactor   type:chore
+   ("type:feat" does not exist and will not apply.)
+
+4. Conventional title: `type(scope): description`. Squash-merge makes this the
+   commit subject on main, so release-please reads THIS, not your local commit
+   messages. A breaking change needs the `!` in the title (`feat!:`,
+   `fix(scope)!:`) — a local commit footer does not survive the squash.
+
+5. Branch name matches `type/description`, lowercase, `[a-z0-9._-]` only:
+       feat fix chore docs style refactor perf test build ci revert
+   Pick it from the KIND of change, not the content area — `research/foo` fails.
+   A PR's head branch cannot be retargeted, so a wrong name means closing and
+   reopening the PR. Worse, renaming a branch mid-flight can resurrect the old
+   ref. Get the name right before the first push.
+
+Two exemptions, both automatic:
+  - Scars-only PRs (every changed file under `.scars/`) skip gates 1 and 2 —
+    human sign-off already happened at `scar promote`. Gates 3-5 still apply.
+  - release-please branches skip the whole job.
+
+Seeing NO checks at all, rather than failing ones? That is not a broken
+workflow. Pull requests from forks and from bots wait on a maintainer to
+approve the Actions run, and until someone clicks, zero check-runs is the
+expected state. Nothing on your side to fix — say so in a comment if it sits.
+-->
+
+## What
+
+## Why
+
+## Tests
+
+<!--
+What you ran and what it proves. New behavior needs a test that failed before
+the change.
+
+Run before pushing — CI runs all three:
+
+    uv run pytest
+    uv run scar lint          # a gate pytest does NOT cover: dead anchors, rot, ReDoS
+    uv run ruff check src/scar tests
+
+If you touched a `--json` payload, re-read `SPEC.md` §9 first. Those keys are a
+published contract: adding is fine, removing or retyping a documented key is
+breaking, and `tests/test_json_contract.py` will tell you which.
+-->
+
+## Checklist
+
+- [ ] Linked issue above has `status:approved`
+- [ ] Exactly one `type:*` label applied
+- [ ] `uv run pytest`, `uv run scar lint` and `ruff` pass locally
+- [ ] If an approach was tried and abandoned here, a candidate scar was written to `.scars/candidates/`

{scar_cli-0.20.0 → scar_cli-0.22.0}/.github/workflows/ci.yml

@@ -39,15 +39,46 @@ jobs:
       # fixture (tests/conftest.py) fails loudly here instead of silently
       # writing into a real ~/.claude/scar-state firing log. 92 of 105 records
       # were once pytest artifacts — see website/docs/methodology.md (#228).
+      # Coverage is collected across BOTH legs and combined (--cov-append),
+      # not just the richer one: the no-symbols run is the only place the
+      # "symbols unavailable" fallbacks execute, so measuring the extras run
+      # alone would report those branches as dead when they are the default
+      # install's real path. One .coverage file, written here, appended below,
+      # rendered to XML at the end.
       - name: Run tests
         run: |
           mkdir -p "$RUNNER_TEMP/fake-home"
-          HOME="$RUNNER_TEMP/fake-home" uv run pytest -q
+          HOME="$RUNNER_TEMP/fake-home" uv run pytest -q \
+            --cov=scar --cov-report= --junitxml=junit-core.xml
 
       - name: Run tests (with symbols extra)
         run: |
           mkdir -p "$RUNNER_TEMP/fake-home"
-          HOME="$RUNNER_TEMP/fake-home" uv run --extra symbols pytest -q
+          HOME="$RUNNER_TEMP/fake-home" uv run --extra symbols pytest -q \
+            --cov=scar --cov-append --cov-report=xml --junitxml=junit-symbols.xml
+
+      # Reporting only — no coverage threshold gates the build, and
+      # fail_ci_if_error stays false so a missing or rotated CODECOV_TOKEN
+      # degrades to "no coverage comment" rather than a red build on a PR
+      # that changed nothing about the tests (#273).
+      - name: Upload test results to Codecov
+        if: ${{ matrix.python-version == '3.13' && !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./junit-core.xml,./junit-symbols.xml
+          flags: py${{ matrix.python-version }}
+          fail_ci_if_error: false
+
+      - name: Upload coverage to Codecov
+        if: ${{ matrix.python-version == '3.13' && !cancelled() }}
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: Daily-Nerd/Scar
+          files: ./coverage.xml
+          flags: py${{ matrix.python-version }}
+          fail_ci_if_error: false
 
       # Dogfood: the repo's own scar graph must always parse and lint clean.
       # A malformed scar silently never fires (the daimon 0004 incident) —

{scar_cli-0.20.0 → scar_cli-0.22.0}/.gitignore

@@ -18,3 +18,8 @@ experiments/fence-honor/runs/
 .claude/
 
 .scars/candidates/fp-log.txt
+
+# Coverage artifacts (#273) — written by pytest-cov in CI and locally.
+.coverage
+coverage.xml
+junit-*.xml

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

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

scar_cli-0.22.0/.scars/0018-cli-subparsers-register-through-_add-wrapper.landmine.md

@@ -0,0 +1,35 @@
+---
+id: 18
+type: landmine
+title: cli.py subparsers register via _add(), not add_parser — and a test's drift gate parses that exact call shape
+severity: medium
+confidence: 0.8
+created: 2026-08-29
+authors: ["claude-code", "Kibukx"]
+anchors:
+  - path: src/scar/cli.py
+  - path: tests/test_json_contract.py
+  - pattern: "_add\(\s*sub,"
+evidence:
+  - pr: 257
+  - issue: 255
+  - issue: 259
+expires:
+  condition: "subcommand registration stops going through a wrapper, or the drift gate stops parsing source text"
+  review_after: 2027-08-29
+status: active
+---
+
+Every subcommand is registered through the local `_add()` wrapper (which wires
+RichHelpFormatter), so `add_parser` appears only twice in cli.py — inside that
+helper's own definition. Grepping for `add_parser` to enumerate the CLI surface
+returns nothing useful and reads as "no subcommands here". Search for
+`_add(sub, "name"` instead.
+
+The coupling: `tests/test_json_contract.py::test_spec_documents_every_json_subcommand`
+parses cli.py as TEXT with that regex to prove SPEC §9.3 documents every
+`--json` command. Renaming `_add`, changing its argument order, or building
+parsers in a loop makes the regex match nothing — the test then compares an
+empty set against a populated SPEC table and fails with a confusing message
+that points at the spec rather than at the refactor. If you change the
+registration shape, update that helper in the same commit (PR #257).

scar_cli-0.20.0/.scars/candidates/token-in-scar-body-cannot-prove-hook-delivery.md → scar_cli-0.22.0/.scars/0019-token-in-scar-body-cannot-prove-hook-delivery.deadend.md

@@ -1,19 +1,14 @@
 ---
-id: 0
+id: 19
 type: deadend
 title: A token in a scar body cannot prove hook delivery — the agent can just read the file
 severity: high
 confidence: 0.95
 created: 2026-08-28
-authors: ["claude-code"]
+authors: ["claude-code", "Kibukx"]
 anchors:
   - path: src/scar/codex.py
   - path: src/scar/hooks.py
-  # No pattern anchor on purpose: the candidate phrasings ("verification
-  # token", "delivery proof") matched nothing but this file, and "A/B" alone
-  # is too loose to earn one. Path anchors are the honest fire condition —
-  # this hazard applies whenever someone edits a hook adapter and wants to
-  # prove it works. See scar #35 on ghost patterns that only self-match.
 evidence:
   - pr: 244
   - pr: 247
@@ -21,7 +16,7 @@ evidence:
 expires:
   condition: "a delivery check exists that observes hook execution directly (firing-log row or marker) rather than model output"
   review_after: 2027-02-28
-status: candidate
+status: active
 ---
 
 Putting a private token in an active scar's body and looking for it in the

scar_cli-0.22.0/.scars/candidates/one-directional-health-check-leaves-flattering-direction-unwatched.md

@@ -0,0 +1,42 @@
+---
+id: 0
+type: landmine
+title: A health check that watches one direction of pipeline failure leaves the flattering direction unwatched
+severity: high
+confidence: 0.9
+created: 2026-08-30
+authors: ["claude-code"]
+anchors:
+  - path: src/scar/cli.py
+  - path: src/scar/hooks.py
+  - pattern: "instrument_disconnected|posttool_silent|verdict_observed"
+evidence:
+  - issue: 277
+  - issue: 237
+expires:
+  condition: "the pipeline stops having two independently-installable halves"
+status: candidate
+---
+
+The precheck and posttool hooks install separately and fail separately. #237
+added a guard for one of those failures: violations recorded with zero precheck
+rows means the precheck half is dead. That guard was correct and it shipped
+after a real four-week outage.
+
+Nobody wrote the mirror, and the mirror was the dangerous one. Posttool used to
+`return 0` before logging anything when it found no violation, so a clean edit
+left no trace. That made a dead posttool hook produce zero violations against a
+full firing count, which is byte-identical to perfect compliance. The guarded
+direction was the one that made the numbers look bad. The unguarded direction
+was the one that made them look good, and it stayed unguarded for months.
+
+Two rules follow, and both are load-bearing. First, when a pipeline has halves
+that fail independently, a health check for one half is not a health check.
+Ask which failure the existing guard CANNOT see, and assume it is the flattering
+one until proven otherwise. Second, absence of a record is only evidence when
+the writer emits a record in the negative case too. Posttool now logs on the
+clean path whenever a violation was possible, and that is the only reason
+`verdicts_unresolved` can mean anything.
+
+Do not "simplify" posttool by restoring the early return on no-violation. It
+looks like dead work and it is the entire mechanism.

scar_cli-0.22.0/.scars/candidates/posttool-fix-in-hooks-does-not-reach-codex-or-cascade.md

@@ -0,0 +1,36 @@
+---
+id: 0
+type: landmine
+title: A posttool change in hooks.py does not reach codex.py or cascade.py, which carry their own copy of the same logic
+severity: high
+confidence: 0.8
+created: 2026-09-02
+authors: ["claude-code"]
+anchors:
+  - path: src/scar/hooks.py
+  - path: src/scar/codex.py
+  - path: src/scar/cascade.py
+violation: "if not violations:"
+evidence:
+  - issue: 277
+  - issue: 293
+  - pr: 297
+expires:
+  condition: "the three posttool paths share one implementation, or the adapters delegate to hooks.posttool"
+  review_after: 2026-12-01
+status: candidate
+---
+
+The posttool verdict logic exists three times: `hooks.posttool` for Claude
+Code, `codex.posttool` for Codex, and `cascade.post_write_code` for Windsurf.
+They are copies, not callers. #277 fixed the flattering-direction blind spot
+(a clean edit must still write a verdict row, or a dead hook reads as perfect
+compliance) in hooks.py only. The adapters kept the pre-#277 early return, so
+on Codex one clean armed edit trips the "broken install" warning on a healthy
+install (#293). The #277 test suite asserted the Codex row SHAPE and never
+exercised the Codex clean path, so green CI proved nothing about the copies.
+
+When you change what a posttool writes, reads, or skips in hooks.py, open
+codex.py and cascade.py in the same PR and make the same change, or make them
+delegate. A bare `if not violations: return` in an adapter is the exact shape
+that reintroduces the blind spot, which is why it is the tripwire here.

{scar_cli-0.20.0/src/scar/skills/scar-authoring/assets → scar_cli-0.22.0/.scars}/template.md

@@ -10,7 +10,7 @@ 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
+authors: ["claude-code"]   # who DRAFTED it; the promoting human goes in promoted_by, written by promote
 anchors:
   - path: src/module/      # file or directory this protects
   - pattern: "regex"       # optional: fires when matching code appears in ANY new/edited file

{scar_cli-0.20.0 → scar_cli-0.22.0}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [0.22.0](https://github.com/Daily-Nerd/Scar/compare/v0.21.0...v0.22.0) (2026-09-03)
+
+
+### Features
+
+* **lint:** escalate a chronically-firing scar into an explicit review flag ([#276](https://github.com/Daily-Nerd/Scar/issues/276)) ([e26884b](https://github.com/Daily-Nerd/Scar/commit/e26884b0b01938420c137673e1c9e01eb4c6dc63))
+* **promote:** record whether promoted_by was typed or read from git config ([#298](https://github.com/Daily-Nerd/Scar/issues/298)) ([bcdc4d7](https://github.com/Daily-Nerd/Scar/commit/bcdc4d7b6d82c5d1b9b38365648f23ed45050064))
+* **reanchor:** record an applied rewrite as an evidence note on the scar ([#299](https://github.com/Daily-Nerd/Scar/issues/299)) ([2aa1d12](https://github.com/Daily-Nerd/Scar/commit/2aa1d12230e7c8b379dcd967a780e0c2cf4a3b2e))
+* **stats:** record blocking capability on the firing row ([#281](https://github.com/Daily-Nerd/Scar/issues/281)) ([a341b48](https://github.com/Daily-Nerd/Scar/commit/a341b48eb365bd8522175570f72b767af1b50c37))
+* **stats:** record context size on the firing row ([#283](https://github.com/Daily-Nerd/Scar/issues/283)) ([99ba9c3](https://github.com/Daily-Nerd/Scar/commit/99ba9c3e8e63aa64ed2c925cba4b4a59895139e0))
+* **stats:** record the match census before top_k truncates it ([#289](https://github.com/Daily-Nerd/Scar/issues/289)) ([715e42c](https://github.com/Daily-Nerd/Scar/commit/715e42c4f73f512b80854f6d68152c5108256246))
+
+
+### Bug Fixes
+
+* **hooks:** Codex and Windsurf posttool record a clean verdict too ([#297](https://github.com/Daily-Nerd/Scar/issues/297)) ([823af3c](https://github.com/Daily-Nerd/Scar/commit/823af3c8e463d6ee89990de0f0fe8606e5dde86f)), closes [#293](https://github.com/Daily-Nerd/Scar/issues/293)
+* **promote:** record who vouched in its own field, not inside authors ([#290](https://github.com/Daily-Nerd/Scar/issues/290)) ([d1e649a](https://github.com/Daily-Nerd/Scar/commit/d1e649a03ef7a76349da48f7772ee4755c332009)), closes [#287](https://github.com/Daily-Nerd/Scar/issues/287)
+* **stats:** make a dead posttool hook distinguishable from compliance ([#280](https://github.com/Daily-Nerd/Scar/issues/280)) ([13f0b6a](https://github.com/Daily-Nerd/Scar/commit/13f0b6ae255dfb1e89f0f61296f4f25d5890acda))
+* **stats:** record why a scar was demoted, not just that it was ([#288](https://github.com/Daily-Nerd/Scar/issues/288)) ([d6dafba](https://github.com/Daily-Nerd/Scar/commit/d6dafbab8ed389815e28535fdc929cd906f657ef)), closes [#284](https://github.com/Daily-Nerd/Scar/issues/284)
+* **stats:** stop counting a command firing as an observed edit ([#300](https://github.com/Daily-Nerd/Scar/issues/300)) ([7abeeed](https://github.com/Daily-Nerd/Scar/commit/7abeeedba8b43634c6d4ccfafbf7eac7fd173269)), closes [#294](https://github.com/Daily-Nerd/Scar/issues/294)
+
+
+### Documentation
+
+* **format:** update the stale veritrail link to vitni ([#269](https://github.com/Daily-Nerd/Scar/issues/269)) ([a842449](https://github.com/Daily-Nerd/Scar/commit/a842449ca0d2eb2fde9310dcef244c299316a84f)), closes [#268](https://github.com/Daily-Nerd/Scar/issues/268)
+* **stats:** state that the armed-window number needs git archaeology ([#291](https://github.com/Daily-Nerd/Scar/issues/291)) ([4097081](https://github.com/Daily-Nerd/Scar/commit/4097081b40fa56bcb255dbda8bdf03f8ac0ab203)), closes [#285](https://github.com/Daily-Nerd/Scar/issues/285)
+
+## [0.21.0](https://github.com/Daily-Nerd/Scar/compare/v0.20.0...v0.21.0) (2026-08-29)
+
+
+### Features
+
+* **stats:** add --since/--until so a window is a first-class operation ([#263](https://github.com/Daily-Nerd/Scar/issues/263)) ([f1b262b](https://github.com/Daily-Nerd/Scar/commit/f1b262b600394d206022ce7f129a168f518254e1)), closes [#258](https://github.com/Daily-Nerd/Scar/issues/258)
+* **stats:** record which fired scars were violation-armed ([#267](https://github.com/Daily-Nerd/Scar/issues/267)) ([206d6af](https://github.com/Daily-Nerd/Scar/commit/206d6afff0094b72ec01ff004a274442738617d0)), closes [#266](https://github.com/Daily-Nerd/Scar/issues/266)
+
+
+### Bug Fixes
+
+* **codex:** let the duplicate-channel warning be silenced ([#253](https://github.com/Daily-Nerd/Scar/issues/253)) ([e060656](https://github.com/Daily-Nerd/Scar/commit/e06065631f9fd3054d7d86d1a528d464a15af432)), closes [#252](https://github.com/Daily-Nerd/Scar/issues/252)
+* **match:** scan whole file bodies for pattern liveness ([#262](https://github.com/Daily-Nerd/Scar/issues/262)) ([fe177ca](https://github.com/Daily-Nerd/Scar/commit/fe177ca55bd05dc69a9a486b89bb8dca0e24e514)), closes [#259](https://github.com/Daily-Nerd/Scar/issues/259)
+* **stats:** report the applied window in the --all-repos payload ([#265](https://github.com/Daily-Nerd/Scar/issues/265)) ([b0e8c1f](https://github.com/Daily-Nerd/Scar/commit/b0e8c1f4a138b2c8847acdd1e7ba8c09269a4069)), closes [#264](https://github.com/Daily-Nerd/Scar/issues/264)
+
+
+### Documentation
+
+* **spec:** publish a stability contract for the nine --json payloads ([#257](https://github.com/Daily-Nerd/Scar/issues/257)) ([c3e5c1b](https://github.com/Daily-Nerd/Scar/commit/c3e5c1b94060fc551aaece7ad98085464b9603d7)), closes [#255](https://github.com/Daily-Nerd/Scar/issues/255)
+
 ## [0.20.0](https://github.com/Daily-Nerd/Scar/compare/v0.19.0...v0.20.0) (2026-08-28)
 
 

{scar_cli-0.20.0 → scar_cli-0.22.0}/PKG-INFO

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

{scar_cli-0.20.0 → scar_cli-0.22.0}/SCAR-FORMAT.md

@@ -41,11 +41,14 @@ is deliberate: consumers in hook hot-paths parse with zero dependencies.
 | `severity` | yes | `low` \| `medium` \| `high` \| `critical` | ranking input |
 | `confidence` | yes | float 0..1 | static authored ranking weight; dynamic decay deferred (SPEC §5, issue #95) |
 | `created` | yes | ISO date | |
-| `authors` | yes | inline list | agents as `"claude-code"` etc.; reviewer appended at promotion |
+| `authors` | yes | inline list | who drafted it: agents as `"claude-code"` etc. The reviewer is no longer appended here |
+| `promoted_by` | active scars | string | the human who promoted it. Written only by `scar promote`, which overwrites anything a candidate carried. Empty on scars promoted before the field existed, and never inferred from `authors` |
+| `promoted_by_source` | optional | `explicit` \| `git-config` | whether `promoted_by` came from `--reviewer` or from `git config user.name`. Written only alongside `promoted_by`, never on its own. Absent on scars promoted before the field existed |
 | `anchors` | yes, ≥1 | list of `- path:`, `- pattern:`, `- symbol:`, and/or `- command:` | §4 |
 | `evidence` | recommended | list of `- commit:`/`- pr:`/`- issue:`/`- incident:`/`- note:`/`- url:` | absent ⇒ challengeable on sight; `issue:`/`url:` are durable forms that survive squash-merge |
 | `expires.condition` | recommended | quoted string | what change obsoletes this scar |
 | `expires.review_after` | recommended | ISO date | forces periodic freshness contact |
+| `expires.review_after_firings` | optional | non-negative integer | forces a review once the scar has fired this many times since its last revision; absent ⇒ per-type default (`landmine` 10, `fence` 15, `deadend` disabled), `0` ⇒ never escalate |
 | `status` | yes | `candidate` \| `active` \| `challenged` \| `archived` \| `orphaned` \| `template` | lifecycle §5 |
 | `receipt_id` | reserved | string ref | **reserved — not yet parsed.** Optional pointer to a cryptographic provenance receipt; see note below. |
 
@@ -54,7 +57,7 @@ trust model is social by design (git history, `authors`, evidence-by-reference);
 that is sufficient within one repo or org. It does **not** carry across orgs that
 share no git history — the future cross-org / org-graph layer where "this dead end
 hit N teams" must be attributable. `receipt_id` reserves the slot for a signed,
-content-addressed receipt (e.g. [veritrail](https://github.com/Daily-Nerd/veritrail))
+content-addressed receipt (e.g. [vitni](https://github.com/Daily-Nerd/vitni))
 bound to an authorship (`scar_draft`) or promotion event. No tool emits, requires,
 or validates it today, and the line-wise parser ignores it like any unknown key —
 so existing scars are unaffected. It will not become required in v0.x.