plainmarker 0.49.0__tar.gz

plainmarker-0.49.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodny Fernandez
+
+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.

plainmarker-0.49.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: plainmarker
+Version: 0.49.0
+Summary: A fail-closed, fully-local, no-account in-loop verifier for AI-written code: deterministic checks the instant your agent writes, and it never claims 'safe'.
+Author: Rodny Fernandez
+License: MIT
+Keywords: security,secret-scanning,ai-code,claude-code,in-loop,verification,ground-truth
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Requires-Dist: pathspec>=0.12
+Requires-Dist: cryptography>=49.0.0
+Dynamic: license-file
+
+# plainmarker
+
+**A fail-closed second opinion on the code your AI agent just wrote — deterministic, in-loop checks that need no model and no account and never send your code off your machine.**
+
+plainmarker is an in-loop verifier for developers running AI coding agents (Claude Code, Cursor, Codex).
+The moment the agent edits a file, plainmarker reads what the code, tests, and scans *actually do*, not
+what the agent claims, and tells you in plain language what's dangerous right now: a hardcoded secret,
+a `curl | sh` install hook. These are **deterministic checks** — detect-secrets, a
+vendored offline Semgrep ruleset, and a shell-command auditor — not the writer agent's say-so, so they
+can't just agree with it, and they run entirely on your machine. (`plainmarker check` additionally screens
+your dependencies against the OSV advisory database, sending package names — never your code. plainmarker's
+deeper, opt-in `plainmarker audit` adds an independent reviewer on a *different* AI model family and discloses
+what it sends; the in-loop seatbelt runs no model.) It never calls your code
+"safe" — only which checks passed, and that this is not a guarantee — and when a check can't finish, it
+says so (fail-closed) instead of pretending all-clear. It also remembers *why* each decision was made
+and re-checks it every session, so trust compounds instead of resetting.
+
+You don't have to read the diff to know what your agent just did to your project.
+
+> **Status: in-loop wedge, v0.49.0.** The in-loop `plainmarker seatbelt` + an actionable verdict + a
+> one-line install are the current focus. Running the target's tests in a sandbox and the agent-facing
+> API are deferred to later milestones (see `docs/ROADMAP.md`).
+
+## The one rule
+
+**Ground truth only.** plainmarker never reports what the AI *says* it did. It reports
+what the code, the tests, the scans, and the live system *actually are*. It never
+claims a project is "safe," only which specific checks passed, and that this is not a
+guarantee.
+
+## Privacy
+
+Local-capable, and **honest about egress.** The independent Auditor uses a cloud model by
+default, so whenever it runs — and when onboarding writes its plain-English summary — plainmarker tells
+you, in plain language, that your code or project facts left your machine. Turn on `local_only` with
+a local Auditor model and nothing leaves your computer. No telemetry, ever.
+
+### Choosing the Auditor model
+
+Three ready-to-use Auditor configs ship under `keeper_core/templates/keeper/` — point at one with
+`plainmarker audit <path> --config <file>`:
+
+- **Default — NVIDIA-served DeepSeek** (no config file needed): a capable cloud model; set `NVIDIA_API_KEY`.
+- **Free — OpenRouter** (`config.openrouter-free.yaml`): run the Auditor at no cost on a free,
+  different-family model; set `OPENROUTER_API_KEY`. Egress is disclosed like any cloud model. ⚠️ Free models
+  may **log/train on inputs**, so **if you are not 100% sure your project is free of private/customer data,
+  use the local option below instead.** They are also **rate-limited**: a throttle shows up honestly as
+  "could not determine" (never a fake pass), so a first run that says "the reviewer did not run" is usually a
+  rate-limit — run `plainmarker doctor` for the exact reason, then retry / switch model / go local.
+- **Local / private — Ollama** (`config.local-ollama.yaml`): zero egress, unlimited; `local_only: true`
+  refuses any remote endpoint. Best for private code, and the only option with a benchmarked model
+  (`qwen2.5-coder:7b`, validated in DECISIONS D-022).
+
+## Architecture (Core + adapters)
+
+- **`keeper_core/`** — the standalone engine. All real logic. Knows nothing about
+  Claude Code and runs on its own.
+- **`adapters/`** — thin wrappers that let a host use Core. The Claude Code plugin is
+  the first; a standalone CLI/service and others follow. Adapters contain no logic of
+  their own.
+
+See `docs/ARCHITECTURE.md` for the full plain-language map of the parts, and
+`docs/INDEX.md` for where everything lives.
+
+## Install
+
+```
+uvx plainmarker check .
+```
+
+That's the whole install: [`uvx`](https://docs.astral.sh/uv/) fetches a compatible Python and runs
+`plainmarker` — no clone, no global setup. For a command that stays around, `uv tool install plainmarker`
+(or `pipx install plainmarker`), then just `plainmarker <command>`.
+
+**For the in-loop catch** — run `plainmarker seatbelt .` right after an agent edits and it tells you
+what's dangerous *now* plus a paste-ready fix to hand back to the agent. Firing it *automatically* the
+moment your agent writes a file means adding a Claude Code PostToolUse hook that calls `plainmarker
+seatbelt` yourself — that wiring is manual today (a packaged hook is on the roadmap, see
+`docs/ROADMAP.md`), and `plainmarker` never edits your `~/.claude` config for you. That hook only fires
+in repos you opt into the watch with `mkdir -p .keeper && touch .keeper/.watch`.
+
+**For the opt-in `plainmarker audit`** (the independent, different-family model reviewer) add one API key
+for the Auditor model — read from an environment variable, never stored in the repo (see *Choosing the
+Auditor model* above).
+
+## What you can do today
+
+Point `plainmarker` at any project (each writes its receipts under that project's `.keeper/` folder):
+
+| Command | What it does |
+|---|---|
+| `plainmarker doctor` | check your setup and that the two models are reachable |
+| `plainmarker onboard <path>` | map a project (files, stack, dependencies, risk areas) + a plain summary |
+| `plainmarker seatbelt <path>` | **in-loop:** after your agent edits a file, what's dangerous NOW + a paste-ready fix to hand back to the agent |
+| `plainmarker check <path>` | what changed since plainmarker last looked, what's dangerous now, and what it did NOT check |
+| `plainmarker baseline <path>` | read-only hard checks: exposed secrets, vulnerable dependencies, code-vulnerability patterns |
+| `plainmarker audit <path>` | the independent different-family reviewer over ground truth (facts vs concerns) |
+| `plainmarker interrogate <path>` | a few plain questions; flags where the code disagrees with your intent |
+| `plainmarker report <path>` | one plain-language report: what's true, broken, unsure, and to decide |
+| `plainmarker calibrate` | prove it catches planted flaws and passes clean projects (and see its blind spots) |
+
+plainmarker never claims a project is "safe" — only which specific checks passed, and that this is not a
+guarantee.
+
+## Exit codes (for CI, pre-commit, and agent hooks)
+
+A script can gate on plainmarker's exit code. There are two shapes, both fail-closed in the way that matters:
+**a real danger never exits `0`.**
+
+| Code | Meaning |
+|---|---|
+| `0` | Nothing to act on (see per-verb note below). |
+| `1` | **STOP** — something needs a human. |
+| `2` | Usage error (bad arguments; standard argparse). Not a security signal. |
+
+- **`plainmarker seatbelt`** and **`plainmarker baseline`** are **fail-closed gates**: exit `0` only when nothing
+  dangerous was found **and** every check actually ran. A danger, *or* a check that could not finish
+  (timeout / offline / missing tool), *or* a crash → `1`. There is deliberately **no exit code meaning
+  "could not determine"** — doubt collapses to `1`, never `0`, so a hook can treat any non-zero as
+  "don't trust this yet." (`baseline` is strict: with no network for the dependency check it returns
+  `1`.)
+- **`plainmarker check`** is the change **narrator**: it exits `1` only when a real danger is present *right
+  now*, and `0` otherwise. A gracefully-undetermined (`unknown`) check — a scanner that timed out or
+  is offline — is disclosed in the report text and in `--json` as `fail_closed` / `could_not_check`,
+  **not** in the exit code (a check that outright *crashes* still exits `1`). If you want
+  fail-closed-on-unknown gating from `check`, read `--json` `fail_closed`, not the exit code (or gate
+  with `seatbelt`).
+- **`plainmarker audit`** additionally needs the Auditor model reachable.
+
+## License
+
+[MIT](./LICENSE).

plainmarker-0.49.0/README.md

@@ -0,0 +1,132 @@
+# plainmarker
+
+**A fail-closed second opinion on the code your AI agent just wrote — deterministic, in-loop checks that need no model and no account and never send your code off your machine.**
+
+plainmarker is an in-loop verifier for developers running AI coding agents (Claude Code, Cursor, Codex).
+The moment the agent edits a file, plainmarker reads what the code, tests, and scans *actually do*, not
+what the agent claims, and tells you in plain language what's dangerous right now: a hardcoded secret,
+a `curl | sh` install hook. These are **deterministic checks** — detect-secrets, a
+vendored offline Semgrep ruleset, and a shell-command auditor — not the writer agent's say-so, so they
+can't just agree with it, and they run entirely on your machine. (`plainmarker check` additionally screens
+your dependencies against the OSV advisory database, sending package names — never your code. plainmarker's
+deeper, opt-in `plainmarker audit` adds an independent reviewer on a *different* AI model family and discloses
+what it sends; the in-loop seatbelt runs no model.) It never calls your code
+"safe" — only which checks passed, and that this is not a guarantee — and when a check can't finish, it
+says so (fail-closed) instead of pretending all-clear. It also remembers *why* each decision was made
+and re-checks it every session, so trust compounds instead of resetting.
+
+You don't have to read the diff to know what your agent just did to your project.
+
+> **Status: in-loop wedge, v0.49.0.** The in-loop `plainmarker seatbelt` + an actionable verdict + a
+> one-line install are the current focus. Running the target's tests in a sandbox and the agent-facing
+> API are deferred to later milestones (see `docs/ROADMAP.md`).
+
+## The one rule
+
+**Ground truth only.** plainmarker never reports what the AI *says* it did. It reports
+what the code, the tests, the scans, and the live system *actually are*. It never
+claims a project is "safe," only which specific checks passed, and that this is not a
+guarantee.
+
+## Privacy
+
+Local-capable, and **honest about egress.** The independent Auditor uses a cloud model by
+default, so whenever it runs — and when onboarding writes its plain-English summary — plainmarker tells
+you, in plain language, that your code or project facts left your machine. Turn on `local_only` with
+a local Auditor model and nothing leaves your computer. No telemetry, ever.
+
+### Choosing the Auditor model
+
+Three ready-to-use Auditor configs ship under `keeper_core/templates/keeper/` — point at one with
+`plainmarker audit <path> --config <file>`:
+
+- **Default — NVIDIA-served DeepSeek** (no config file needed): a capable cloud model; set `NVIDIA_API_KEY`.
+- **Free — OpenRouter** (`config.openrouter-free.yaml`): run the Auditor at no cost on a free,
+  different-family model; set `OPENROUTER_API_KEY`. Egress is disclosed like any cloud model. ⚠️ Free models
+  may **log/train on inputs**, so **if you are not 100% sure your project is free of private/customer data,
+  use the local option below instead.** They are also **rate-limited**: a throttle shows up honestly as
+  "could not determine" (never a fake pass), so a first run that says "the reviewer did not run" is usually a
+  rate-limit — run `plainmarker doctor` for the exact reason, then retry / switch model / go local.
+- **Local / private — Ollama** (`config.local-ollama.yaml`): zero egress, unlimited; `local_only: true`
+  refuses any remote endpoint. Best for private code, and the only option with a benchmarked model
+  (`qwen2.5-coder:7b`, validated in DECISIONS D-022).
+
+## Architecture (Core + adapters)
+
+- **`keeper_core/`** — the standalone engine. All real logic. Knows nothing about
+  Claude Code and runs on its own.
+- **`adapters/`** — thin wrappers that let a host use Core. The Claude Code plugin is
+  the first; a standalone CLI/service and others follow. Adapters contain no logic of
+  their own.
+
+See `docs/ARCHITECTURE.md` for the full plain-language map of the parts, and
+`docs/INDEX.md` for where everything lives.
+
+## Install
+
+```
+uvx plainmarker check .
+```
+
+That's the whole install: [`uvx`](https://docs.astral.sh/uv/) fetches a compatible Python and runs
+`plainmarker` — no clone, no global setup. For a command that stays around, `uv tool install plainmarker`
+(or `pipx install plainmarker`), then just `plainmarker <command>`.
+
+**For the in-loop catch** — run `plainmarker seatbelt .` right after an agent edits and it tells you
+what's dangerous *now* plus a paste-ready fix to hand back to the agent. Firing it *automatically* the
+moment your agent writes a file means adding a Claude Code PostToolUse hook that calls `plainmarker
+seatbelt` yourself — that wiring is manual today (a packaged hook is on the roadmap, see
+`docs/ROADMAP.md`), and `plainmarker` never edits your `~/.claude` config for you. That hook only fires
+in repos you opt into the watch with `mkdir -p .keeper && touch .keeper/.watch`.
+
+**For the opt-in `plainmarker audit`** (the independent, different-family model reviewer) add one API key
+for the Auditor model — read from an environment variable, never stored in the repo (see *Choosing the
+Auditor model* above).
+
+## What you can do today
+
+Point `plainmarker` at any project (each writes its receipts under that project's `.keeper/` folder):
+
+| Command | What it does |
+|---|---|
+| `plainmarker doctor` | check your setup and that the two models are reachable |
+| `plainmarker onboard <path>` | map a project (files, stack, dependencies, risk areas) + a plain summary |
+| `plainmarker seatbelt <path>` | **in-loop:** after your agent edits a file, what's dangerous NOW + a paste-ready fix to hand back to the agent |
+| `plainmarker check <path>` | what changed since plainmarker last looked, what's dangerous now, and what it did NOT check |
+| `plainmarker baseline <path>` | read-only hard checks: exposed secrets, vulnerable dependencies, code-vulnerability patterns |
+| `plainmarker audit <path>` | the independent different-family reviewer over ground truth (facts vs concerns) |
+| `plainmarker interrogate <path>` | a few plain questions; flags where the code disagrees with your intent |
+| `plainmarker report <path>` | one plain-language report: what's true, broken, unsure, and to decide |
+| `plainmarker calibrate` | prove it catches planted flaws and passes clean projects (and see its blind spots) |
+
+plainmarker never claims a project is "safe" — only which specific checks passed, and that this is not a
+guarantee.
+
+## Exit codes (for CI, pre-commit, and agent hooks)
+
+A script can gate on plainmarker's exit code. There are two shapes, both fail-closed in the way that matters:
+**a real danger never exits `0`.**
+
+| Code | Meaning |
+|---|---|
+| `0` | Nothing to act on (see per-verb note below). |
+| `1` | **STOP** — something needs a human. |
+| `2` | Usage error (bad arguments; standard argparse). Not a security signal. |
+
+- **`plainmarker seatbelt`** and **`plainmarker baseline`** are **fail-closed gates**: exit `0` only when nothing
+  dangerous was found **and** every check actually ran. A danger, *or* a check that could not finish
+  (timeout / offline / missing tool), *or* a crash → `1`. There is deliberately **no exit code meaning
+  "could not determine"** — doubt collapses to `1`, never `0`, so a hook can treat any non-zero as
+  "don't trust this yet." (`baseline` is strict: with no network for the dependency check it returns
+  `1`.)
+- **`plainmarker check`** is the change **narrator**: it exits `1` only when a real danger is present *right
+  now*, and `0` otherwise. A gracefully-undetermined (`unknown`) check — a scanner that timed out or
+  is offline — is disclosed in the report text and in `--json` as `fail_closed` / `could_not_check`,
+  **not** in the exit code (a check that outright *crashes* still exits `1`). If you want
+  fail-closed-on-unknown gating from `check`, read `--json` `fail_closed`, not the exit code (or gate
+  with `seatbelt`).
+- **`plainmarker audit`** additionally needs the Auditor model reachable.
+
+## License
+
+[MIT](./LICENSE).

plainmarker-0.49.0/keeper_core/__init__.py

@@ -0,0 +1,12 @@
+"""plainmarker Core — the standalone engine.
+
+All of plainmarker's real logic lives here. This package assumes NOTHING about Claude
+Code (or any other host) and is designed to run on its own. Host-specific surfaces
+(the Claude Code plugin, a future standalone CLI service, etc.) live under
+``adapters/`` and only call into this package.
+
+Milestone 0, Step 1: this is the skeleton. The feature modules described in
+``docs/ARCHITECTURE.md`` are added one per later build-kit step.
+"""
+
+__version__ = "0.49.0"

plainmarker-0.49.0/keeper_core/__main__.py

@@ -0,0 +1,11 @@
+"""Run plainmarker Core as a module: ``python -m keeper_core ...``.
+
+This is the invocation path the Claude Code plugin's MCP server will use later
+(Step 5): it launches Core as a subprocess instead of importing it, so the plugin
+never has to carry a copy of Core's logic.
+"""
+
+from keeper_core.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plainmarker-0.49.0/keeper_core/accept_baseline.py

@@ -0,0 +1,327 @@
+"""Accept-baseline (D-079) + per-finding acknowledge (D-082): the OWNER's noise filter for `plainmarker check`.
+
+`plainmarker accept <path>` records the current findings' content-bound IDs to `.keeper/accepted.json`;
+`plainmarker check` then headlines only NEW findings (IDs not in the store) and quietly counts the accepted
+ones. `plainmarker accept <path> --only <selector> --reason "..."` acknowledges ONE finding and records WHY,
+so `plainmarker check` keeps just that one quiet and shows the reason (the decision is remembered) until the
+code at that spot changes — the content-bound id then changes and the finding re-surfaces on its own.
+
+NOT A SECURITY BOUNDARY. `plainmarker check` is the ADVISORY narrator and is fully silenceable by an agent
+with file-write (this store, `.keeperignore`, or editing `.keeper/`). The SIGNED GATE (`plainmarker baseline`
+/`sign`/`audit`) IGNORES this store and reports everything — it is the only trust boundary. Therefore this
+module is imported ONLY by the keeper-check path; `baseline.py`/`auditor.py`/`witness_store.py` MUST NOT
+import it (enforced mechanically by tests/test_accept_baseline.py::test_gate_modules_do_not_import_accept).
+
+Content-bound IDs (a rotated secret / changed source line gets a new id and re-surfaces) are an
+honest-user RE-REVIEW aid, NOT an adversary defense.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+_STORE = "accepted.json"
+_SCHEMA = 2                                   # 1 = {schema,recorded,accepted}; 2 adds {reasons:{id:{...}}}
+
+# Only these two checks are acceptable in v1. Shell HARD findings (download-and-run / exfil) are
+# deliberately NEVER acceptable, and shell has no receipt + a 20-cap, so it is excluded entirely.
+_ACCEPTABLE = ("secrets", "code_vulnerabilities")
+
+# A selector is FILE:LINE[:TAG]. The file part has NO colon (receipt paths are relative posix paths), so
+# the first ':' ends the file and the optional TAG (a detect-secrets type / semgrep rule) may itself
+# contain ':'. Resolution is fail-CLOSED at the call site (exactly one id, or acknowledge nothing).
+_SELECTOR_RE = re.compile(r"^(?P<file>[^:]+):(?P<line>\d+)(?::(?P<tag>.+))?$")
+
+
+def _accept_path(project_path) -> Path:
+    return Path(project_path) / ".keeper" / _STORE
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).date().isoformat()
+
+
+def _clean_reason(s) -> str:
+    """Neutralize a stored reason for display: drop control chars / newlines / ANSI (an agent-writable
+    store must not be able to inject plainmarker-looking lines into the report) and cap the length. Applied
+    BOTH when storing (fresh) and when loading (a forged store), so neither path can forge output."""
+    return "".join(ch for ch in str(s) if ch.isprintable()).strip()[:200]
+
+
+def _line_at(path: Path, line) -> str:
+    """The stripped source line at 1-based `line`, or "" if unreadable/out of range (fail-safe)."""
+    if not isinstance(line, int) or line < 1:
+        return ""
+    try:
+        with path.open(encoding="utf-8", errors="replace") as fh:
+            for i, text in enumerate(fh, 1):
+                if i == line:
+                    return text.strip()
+    except OSError:
+        return ""
+    return ""
+
+
+def _secret_rows(receipt: dict) -> list[dict]:
+    # ONE row per REAL (placeholder-demoted) finding, joined to raw.results for the unsalted hashed_secret
+    # — so a placeholder never mints an id and a rotated value re-surfaces. This is the single source of
+    # truth for secret ids (finding_ids derives from it).
+    raw = ((receipt.get("raw") or {}).get("results")) or {}
+    rows: list[dict] = []
+    consumed: dict[str, set[int]] = {}        # file -> raw indices already mapped, so N distinct secrets on the
+    for f in receipt.get("findings") or []:   # SAME (line,type) map to N distinct hashes (not all to the first)
+        file, line, typ = f.get("file"), f.get("line"), f.get("type")
+        used = consumed.setdefault(file, set())
+        hashed = None
+        for i, entry in enumerate(raw.get(file, [])):
+            if i in used or entry.get("line_number") != line or entry.get("type") != typ:
+                continue
+            used.add(i)
+            hashed = entry.get("hashed_secret")
+            break
+        rid = (f"secrets\0{file}\0{hashed}" if hashed     # fallback so a finding never VANISHES from the count
+               else f"secrets\0{file}\0L{line}\0{typ}")
+        rows.append({"id": rid, "file": file, "line": line, "type": typ,
+                     "content_bound": hashed is not None})    # fallback id is line+type bound (NOT acknowledgeable)
+    return rows
+
+
+def _sast_rows(receipt: dict, root: Path) -> list[dict]:
+    # ID off (file, rule, hash-of-source-line-CONTENT) — NOT the line number — so a line shift keeps the
+    # acceptance but an in-place edit at that location re-surfaces it for re-review.
+    rows: list[dict] = []
+    for f in receipt.get("findings") or []:
+        file, rule, line = f.get("file"), f.get("rule"), f.get("line")
+        content_bound = bool(file) and rule is not None
+        if not content_bound:                 # malformed (never from real semgrep) -> fallback so none vanishes
+            rid = f"code_vulnerabilities\0{file or '?'}\0{rule}\0L{line}"
+        else:
+            line_text = _line_at(root / file, line)
+            digest = hashlib.sha256(line_text.encode("utf-8", "replace")).hexdigest()
+            rid = f"code_vulnerabilities\0{file}\0{rule}\0{digest}"
+            if not line_text:                 # unreadable/empty line -> sha256("") is NOT value-binding -> refuse
+                content_bound = False
+        rows.append({"id": rid, "file": file, "rule": rule, "line": line, "content_bound": content_bound})
+    return rows
+
+
+def finding_rows(check_result, root) -> list[dict]:
+    """Per-finding rows for a fail CheckResult (secrets + code_vulnerabilities only): each is
+    {id, file, line, type|rule}. Same fail-closed contract as finding_ids (a non-fail / unknown /
+    receiptless / non-acceptable check yields [])."""
+    if (not check_result or check_result.status != "fail"
+            or check_result.check not in _ACCEPTABLE or not check_result.receipt_path):
+        return []
+    try:
+        receipt = json.loads(Path(check_result.receipt_path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return []
+    return _secret_rows(receipt) if check_result.check == "secrets" else _sast_rows(receipt, Path(root))
+
+
+def finding_ids(check_result, root) -> set[str]:
+    """Content-bound IDs for a fail CheckResult's findings (secrets + code_vulnerabilities only).
+
+    A non-fail / unknown / receiptless check yields an EMPTY set, so it can never be marked "all
+    accepted". Derives from finding_rows so the id logic has one home."""
+    return {r["id"] for r in finding_rows(check_result, root)}
+
+
+def finding_label(row: dict) -> str:
+    """The human-readable label for one finding row: FILE:LINE (TAG). SANITIZED — a receipt file path or
+    type string can carry a newline / ANSI (an adversarial agent can name a file `evil\\nkeeper ...`), so
+    this is the single chokepoint that neutralizes label injection into the report (the twin of the reason
+    sanitizer). Every render site routes a finding's display through here."""
+    tag = row.get("type") or row.get("rule")
+    return _clean_reason(f"{row.get('file')}:{row.get('line')}" + (f" ({tag})" if tag else ""))
+
+
+def resolve_selector(rows: list[dict], selector: str) -> set[str]:
+    """The set of finding ids a FILE:LINE[:TAG] selector matches. The CALLER fail-CLOSES on len != 1 —
+    a 0/ambiguous match must acknowledge nothing, never the wrong finding or all of them."""
+    m = _SELECTOR_RE.match((selector or "").strip())
+    if not m:
+        return set()
+    file, line, tag = m.group("file"), int(m.group("line")), m.group("tag")
+    out: set[str] = set()
+    for r in rows:
+        if r.get("file") != file or r.get("line") != line:
+            continue
+        if tag is not None and (r.get("type") or r.get("rule")) != tag:
+            continue
+        out.add(r["id"])
+    return out
+
+
+def load_store(project_path) -> dict:
+    """The full accept store, sanitized + fail-OPEN. Returns {schema, recorded, accepted:list,
+    reasons:{id:{reason,recorded}}}; any problem (missing/malformed/forged) degrades to an empty store
+    so a broken store never HIDES a finding. Schema-1 stores (no `reasons`) load as reasons={}."""
+    empty = {"schema": _SCHEMA, "recorded": "", "accepted": [], "reasons": {}}
+    try:
+        obj = json.loads(_accept_path(project_path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return empty
+    if not isinstance(obj, dict):
+        return empty
+    accepted = [x for x in (obj.get("accepted") or []) if isinstance(x, str)]
+    reasons: dict = {}
+    src = obj.get("reasons")
+    if isinstance(src, dict):
+        for k, v in src.items():
+            if isinstance(k, str) and isinstance(v, dict) and isinstance(v.get("reason"), str):
+                rec = v.get("recorded")
+                reasons[k] = {"reason": _clean_reason(v["reason"]),       # forged store can't inject output
+                              "recorded": _clean_reason(rec) if isinstance(rec, str) else ""}
+    recorded = obj.get("recorded")
+    return {"schema": _SCHEMA, "recorded": recorded if isinstance(recorded, str) else "",
+            "accepted": accepted, "reasons": reasons}
+
+
+def save_store(project_path, store: dict) -> Path:
+    """Write the store as schema-2, deterministically. GC: a reason is kept ONLY if its id is still in
+    `accepted` (so an orphaned reason — its finding rotated/edited away — never lingers)."""
+    accepted = sorted(set(store.get("accepted", [])))
+    keep = set(accepted)
+    reasons = {k: v for k, v in (store.get("reasons") or {}).items() if k in keep}
+    p = _accept_path(project_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps({"schema": _SCHEMA, "recorded": store.get("recorded", ""),
+                             "accepted": accepted, "reasons": reasons}, indent=2) + "\n", encoding="utf-8")
+    return p
+
+
+def load_accepted(project_path) -> set[str]:
+    """The accepted-finding IDs, or an EMPTY set on any problem (fail-OPEN). Unchanged API."""
+    return set(load_store(project_path)["accepted"])
+
+
+def load_reasons(project_path) -> dict:
+    """{id: {reason, recorded}} for findings the owner acknowledged with a reason. Fail-open ({})."""
+    return load_store(project_path)["reasons"]
+
+
+def save_accepted(project_path, ids, recorded: str = "") -> Path:
+    """Record `ids` as the accepted set, MERGING into the existing store so a per-finding reason is never
+    clobbered (a surviving id keeps its reason; a vanished id's reason is GC'd by save_store)."""
+    store = load_store(project_path)
+    store["accepted"] = sorted(set(ids))
+    store["recorded"] = recorded
+    return save_store(project_path, store)
+
+
+def _scan_rows(path: Path) -> tuple[list[dict], list[str]]:
+    """Scan secrets + sast with the SAME exclude set as plainmarker check (.keeperignore) and return
+    (all finding rows, names of checks that could not be scanned)."""
+    from keeper_core.checks import sast_check, secrets_check
+    from keeper_core.onboarding.builtin_provider import project_excludes
+    evidence = path / ".keeper" / "evidence"
+    excludes = project_excludes(path)           # MUST match plainmarker check's scan set, else the baseline
+    rows: list[dict] = []                       # records findings `plainmarker check` never sees (mismatch)
+    unscanned: list[str] = []
+    for check in (secrets_check, sast_check):
+        r = check(path, evidence, excludes)
+        if r.status == "unknown":               # a timed-out / unavailable scanner accepted NOTHING — say so
+            unscanned.append(r.check)
+        rows.extend(finding_rows(r, path))
+    return rows, unscanned
+
+
+def _acknowledge_one(path: Path, rows: list[dict], selector: str, reason: str,
+                     recorded: str, as_json: bool) -> int:
+    """Acknowledge exactly ONE finding (fail-CLOSED): refuse on no reason, no match, or an ambiguous
+    selector. Records the reason and echoes what was acknowledged (informed consent)."""
+    if not reason.strip():
+        print("--only needs --reason \"why this is OK\" — the reason is recorded and shown on later "
+              "`plainmarker check`. Nothing acknowledged.")
+        return 1
+    matches = resolve_selector(rows, selector)
+    if len(matches) != 1:
+        if not matches:
+            print(f"No current finding matches {selector!r}. Run `plainmarker check` to see the exact "
+                  "FILE:LINE to use. Nothing acknowledged.")
+        else:
+            cands = sorted({finding_label(r) for r in rows if r["id"] in matches})
+            if len(cands) == 1:                       # N indistinguishable findings at one spot (same type)
+                print(f"{selector!r} matches {len(matches)} findings at the same spot ({cands[0]}) that "
+                      "cannot be told apart by selector — fix them, or use `plainmarker accept` to accept all "
+                      "current findings. Nothing acknowledged.")
+            else:
+                print(f"{selector!r} matches {len(matches)} findings — add the type/rule to pick one "
+                      f"(e.g. {cands[0]!r}). Candidates:")
+                for c in cands:
+                    print(f"  - {c}")
+                print("Nothing acknowledged.")
+        return 1
+    rid = next(iter(matches))
+    backing = [r for r in rows if r["id"] == rid]
+    if len(backing) > 1:                              # one content-bound id can back N byte-identical lines
+        others = sorted({finding_label(r) for r in backing if finding_label(r) != selector})
+        print(f"{selector!r} has the same content as {len(backing) - 1} other finding(s) "
+              f"({', '.join(others) or 'elsewhere'}), so acknowledging it would silence those too — and a "
+              "future identical line would inherit your reason. Fix them, or use `plainmarker accept` to accept "
+              "all. Nothing acknowledged.")
+        return 1
+    row = backing[0]
+    if not row.get("content_bound", True):           # a fallback (line+type) id would hide a ROTATED value
+        print(f"plainmarker could not fingerprint the content of {finding_label(row)}, so it can't safely "
+              "remember this one — a changed value would silently ride the acknowledgement. Fix it instead. "
+              "Nothing acknowledged.")
+        return 1
+    reason = _clean_reason(reason)
+    store = load_store(path)
+    store["accepted"] = sorted(set(store["accepted"]) | {rid})
+    store["reasons"][rid] = {"reason": reason, "recorded": recorded or _today()}
+    save_store(path, store)
+    if as_json:
+        print(json.dumps({"acknowledged": finding_label(row), "reason": reason}, indent=2))
+        return 0
+    print(f"Acknowledged {finding_label(row)} — \"{reason}\".")
+    print("Future `plainmarker check` keeps this one quiet (and shows your reason) until the code at that spot "
+          "changes. A noise filter, NOT a safety guarantee — `plainmarker baseline` still reports it.")
+    return 0
+
+
+def run_accept_cli(project_path: str, recorded: str = "", as_json: bool = False,
+                   only: str | None = None, reason: str = "") -> int:
+    """`plainmarker accept <path>`: re-scan (secrets + code-vulns, local) and record the findings as reviewed,
+    printing exactly what is accepted (informed consent). With `--only <selector> --reason "..."`,
+    acknowledge a SINGLE finding and record why (fail-closed on an ambiguous/absent selector)."""
+    path = Path(project_path).expanduser().resolve()
+    if not path.is_dir():
+        print(f"Not a folder: {path}")
+        return 1
+    from keeper_core.baseline import _protect_keeper_dir
+    _protect_keeper_dir(path)
+    rows, unscanned = _scan_rows(path)
+
+    if only is not None:
+        return _acknowledge_one(path, rows, only, reason, recorded, as_json)
+
+    ids = {r["id"] for r in rows}
+    # A check that could NOT be scanned this run (timed out / unavailable) must not silently wipe its prior
+    # acknowledgements + reasons — preserve them (ids are "<check>\0...") so a transient scanner failure
+    # never destroys the owner's recorded decisions. (Disclosed below.)
+    preserved: set[str] = set()
+    if unscanned:
+        pref = tuple(f"{c}\0" for c in unscanned)
+        preserved = {i for i in load_store(path)["accepted"] if i.startswith(pref)}
+    by_check = {"secrets": sum(1 for i in ids if i.startswith("secrets\0")),
+                "code_vulnerabilities": sum(1 for i in ids if i.startswith("code_vulnerabilities\0"))}
+    save_accepted(path, ids | preserved, recorded)   # MERGE: preserves reasons for surviving ids; GCs the rest
+    if as_json:
+        print(json.dumps({"accepted": len(ids), "by_check": by_check, "unscanned": unscanned,
+                          "preserved_unscanned": len(preserved)}, indent=2))
+        return 0
+    parts = ", ".join(f"{n} {'secret' if c == 'secrets' else 'code-vuln'}(s)"
+                      for c, n in by_check.items() if n)
+    print(f"Accepted {len(ids)} finding(s)" + (f" ({parts})" if parts else "") + ".")
+    for c in unscanned:
+        print(f"⚠ {c}: could not scan (timed out / unavailable) — kept your earlier acknowledgements for it.")
+    print("Future `plainmarker check` will flag only NEW findings. This is a noise filter, NOT a safety "
+          "guarantee — `plainmarker baseline` always scans everything.")
+    return 0