the-custodian/docs/changes/2026-11-01-scanner-json-digest/native-r3/PLAN.md

Missing-fragment repair and sealed JSON rollout, revision 3

Proposal SYNC-SCANNER-JSON-DIGEST-20261101, revision 3. Original revisions 1 and 2 and the failed revision-2 execution remain preserved. No revision-3 native action has run.

Verified reason for revision

The founder's read-only condition report examined 171 repositories. The only rejected condition was a missing hooks/pre-receive.d/10-custodian-secret-scan at /data/git/gitea-repositories/coulomb/markitect-main.git. Node/deployment/pod identity, readiness, old hook template and installed-artifact guards had already passed. Revision 2 stopped before staging or mutation. Its failure receipt SHA256 is 35e4ba1b09065ec765762d4238235cb02286c42e19baad0f0ae505167c44a500.

This is an actual missing receiver fragment. The inventory guard correctly refused it. The repair adds the existing policy at this one exact path, rather than accepting an uncovered repository. The report does not establish why the fragment was missing, or retroactively establish admission of existing history.

Exact action

The founder runs the reviewed /tmp/forge-scanner-recover-and-rollout.sh launcher. It selects the attended admin context and supplies this packet's SHA256 acknowledgement. The agent does not access that kubeconfig. A fresh outer receipt is created exclusively at /tmp/forge-scanner-recovery-r3-receipt.json; an existing receipt refuses execution.

1. Verify every revision-3 sealed file and the unchanged revision-2 packet SHA256 d22b1f555af96c203b7d68efd25e80815ce18ca4e3bf0dd3ab96b6f699d50237. Check all six owner-source preimages, candidate binary, exact failed receipt and absence of its archive destination. Recheck original node/deployment/pod UID, old guard/template and installed artifacts. Unknown identity/guard/template/source drift refuses.
2. Snapshot active hook hashes, modes and ownership for all 171 repositories. Permit exactly the declared fragment absence at markitect-main, with its dispatcher and parent directories present and non-symlinked. Every other scanner fragment must match the old policy bytes/custody. Another gap, changed scope, unsafe path or symlink refuses before installation.
3. Copy markitect-main's real dispatcher into a private disposable tmpfs receive fixture and run the original old-policy receive probe. Require clean acceptance, intermediate synthetic-private-key rejection, quarantine discard, unavailable-scanner refusal, clean recovery and cleanup. This does not write to any hosted repository. Recheck the complete hook snapshot immediately before installation.
4. Install only the missing fragment, using the exact old hook bytes from the verified public ConfigMap. Expected hook SHA256: d1df801be39f2cd4ac2a9e71bbd1341ccd2723d236c9c265853b289cc6df221f; it calls the old 20261027-b735d052a49f adapter and unchanged pinned Gitleaks. Create a private sibling temporary file, verify bytes/owner, set uid/gid 1000 and mode 0755, then use a no-replace atomic hard link at the exact target. Refuse an existing or concurrently created target; never overwrite generated dispatchers or other hooks. Remove only the owned temporary inode. No Git ref, object or deployment change in this phase.
5. Run the original strict inventory across all 171 repositories. Verify 171 known old-policy fragments; the repaired fragment has the expected hash/mode/uid/gid, and every other active hook and its metadata exactly equals the pre-repair snapshot. Record repair-verified in the outer receipt.
6. Preserve the original failed receipt under the exact non-overwriting archive /tmp/forge-scanner-rollout-r2-failed-receipt.json, verify its bytes, then remove only its verified old pathname so a fresh embedded execution receipt can be created. The durable Git copy is also retained. An unknown, changed or pre-existing archive refuses; do not rerun an uncertain attempt.
7. Continue the sealed revision-2 JSON correction using its unchanged implementation, artifact/source/config digests, mandatory server dry-run/diff, guarded deployment patch, old/new artifact guards, hook migration, pre/post probes and rollback. A revision-3 wrapper supplies operation labels and fixed safe failure categories; it prints no raw Kubernetes objects/errors. The embedded implementation receipt remains at /tmp/forge-scanner-rollout-receipt.json, binds both packet digests, and identifies revision 2 as implementation and revision 3 as execution envelope. The outer receipt binds the full newly approved action.
8. After verified native activation, the agent applies the same six exact reviewed owner-source changes with the original source_followthrough.py and publishes them through normal hooks. Review both ../native-r2/scanner-source-changes.json and ../native-r2/apps-source.patch. The original source helper's exact packet acknowledgement is covered by this combined revision-3 review; it does not grant independent authority. Normal held-publication retries and remaining finding adjudication then continue under CUST-WP-0083.

Recovery and evidence

Repair failure stops before JSON activation. The original dispatcher, other hooks, failed receipt and reviewed packet are preserved. A successfully installed scanner fragment remains installed even if later verification fails; unknown concurrent drift is retained for founder review. No automatic recovery removes the restored protection.

If JSON activation fails, the original revision-2 controller attempts its guarded rollback to old artifacts, old deployment guard/template and known old hook bytes across all repositories, including the repaired repository. It retains the coverage repair. A failed/unverified rollback requires founder recovery; automatic recovery is not guaranteed. The original failed revision-2 attempt is not replaced by a success or counted as a fresh trial.

The paired source/receiver candidate and original rollout retain their existing real-scanner proof (12 local tests, full receiver suite, 13 filesystem/probe cases and 5 controller tests). Revision 3 adds seven controller tests and six actual filesystem cases: correct installation, existing target refusal, dangling and ancestor symlink refusal, bad-payload cleanup, and the full 171-repository inventory/install/verification round trip. Controller tests cover extra gaps/scope drift, unchanged protected hooks, archived failure preservation and repair retention on JSON failure. These local tests do not claim live execution or native creation/resynchronization acceptance.

Installing a fragment applies the declared receive policy on subsequent invocations; it does not retroactively scan existing reachable objects, prove why adoption missed this repository, or establish every Forgejo write/new-repository lifecycle. Those limits remain explicit in forge-owned coverage guidance and CUST-WP-0083's class-level followup. No wider scanner exception is added: UUIDs, fingerprints and prose findings remain separate adjudication work.

Cost and risk

No new service/image, resource increase or infrastructure commitment. Incremental infrastructure cost: EUR 0; founder time and marginal existing compute remain unpriced. Estimate 20–35 attended minutes including the extra repair probe and snapshot. Repair itself needs no Forgejo restart. The JSON phase retains the expected 1–3 minute Recreate interruption and up to 180 seconds readiness wait for rollback, plus bounded probes/commands; this is not an availability guarantee.

Illustrative recovery effort remains one hour/EUR 100 at EUR 100/hour. Complete security and recovery loss cannot be defensibly bounded in EUR and requires explicit founder judgement. The filename/digest exception has the limitations documented in revision 2. This preparation grants no autopilot authority, numerical risk limit, signed approval or promotion credit.

Revision 3 requires exact founder review because it adds a native fragment repair and receipt-preserving recovery envelope to the previously reviewed action. Governing instruction: docs/agent-autonomy-decision.md, "Approval is bound to the reviewed proposal revision; changing that revision requires review again."