feat(security): add content-silent staged secret scanner

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a12d13-27f2-7163-b8c0-f682af02772c

docs/secret-detection.md

@@ -0,0 +1,82 @@
+# Repository secret detection
+
+Repo Manager provides a control adapter to an external scanner. Credential
+custody, incident response and authorization remain with their existing owners.
+The adapter is initially source tooling; it does not install or activate hooks.
+Work: RMGR-WP-0021, coordinated by Custodian CUST-WP-0080 G07.
+
+## Scan the proposed index
+
+```bash
+rmgr secret-scan --path /path/to/repo --binary /reviewed/path/to/gitleaks
+```
+
+The supported executable is Gitleaks 8.30.1 Linux x64, SHA256
+`88f91962aa2f93ac6ab281d553b9e125f5197bbbce38f9f2437f7299c32e5509`.
+Install/admit it separately; this command never downloads or executes an
+unverified replacement. The reviewed test archive and checksum came from the
+[official release](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1).
+Checksum comparison alone is not a detached signature verification or fleet
+installation receipt. Other platforms/versions need an explicitly reviewed pin.
+
+The JSON result contains a fixed status, counts and affected Git blob IDs. It
+contains no findings, paths, matched lines or credential values. Raw scanner
+stdout/stderr are discarded even on errors; no findings report is written.
+Inspect blocked content only in an approved private review environment. Never
+paste it into chat, State Hub, issue bodies or CI logs.
+
+| Exit | Result | Required caller behavior |
+| --- | --- | --- |
+| 0 | `clean` | No detection in the declared changed staged blobs |
+| 1 | `blocked` | Reject the proposed commit and privately review the indicated objects |
+| 2 | `unverified` | Reject; fix missing tool, unreadable index, limits or other verification failure |
+
+`clean` is not a statement about working-tree files, existing HEAD/history, other
+branches, remote refs, logs, artifacts, production credentials or complete absence
+of secrets. An empty staged change scans zero objects and says nothing about
+history. The scanner uses the upstream default detection rules; heuristic false
+negatives and false positives remain possible.
+
+## Input and configuration boundaries
+
+The adapter scans complete changed staged blobs, including an initial commit,
+renames and partial staging. It honors Git's explicit alternate index (including
+`git commit --only` behavior), ignores Git replacement objects and refuses index
+changes observed during scanning. Symlink text is scanned without reading the
+external target. Changed gitlinks, conflicts and unreadable entries are refused.
+
+A reviewed configuration extending the scanner's built-in defaults is supplied
+from an isolated temporary directory. Repository `.gitleaks.toml`, ignore files,
+inline `gitleaks:allow` comments and ambient scanner environment do not suppress
+this check. There is no implicit baseline or exception switch. False positives
+need a reviewed follow-up mechanism with exact scope and real approval; do not
+silently add broad path exclusions.
+
+The current resource bounds are 500 distinct blobs, 8 MiB per blob and 64 MiB in
+total; exceeding a bound refuses instead of skipping. Individual Git and scanner
+calls have timeouts. The executable is hash-checked and invoked through its open
+file descriptor. These measures are not isolation from a hostile same-UID writer,
+a malicious Git installation, hook bypass or a process with repository authority.
+
+## Enforcement and response acceptance
+
+Before activating a hook, preserve the existing generated-commit and assistant
+provenance checks; validate exact repository coverage, executable availability,
+clean commits, synthetic detections and scanner failures. Do not replace the
+shared hook or change global `core.hooksPath` merely to run this command.
+
+Local pre-commit can be bypassed. Forge/CI enforcement must independently check
+all introduced objects/commits, including merge/base-history cases and unavailable
+scanner failures. Required checks and writers able to alter enforcement need
+separate admission. An actual finding needs owner classification and a governed
+revocation/rotation path; source removal or rejection of one commit does not
+revoke credentials that were already exposed. CUST-WP-0073-T05's existing founder
+deferral is not overridden by this adapter.
+
+## Tests
+
+Set `RMGR_TEST_GITLEAKS` to the exact reviewed test executable when running
+`pytest tests/test_secret_scan.py`. Tests use disposable repositories and keys,
+verify commit refusal and preserved index semantics, and never contact a forge
+or issuer. Without the test executable, scanner-dependent tests explicitly skip;
+those skips are not acceptance evidence.