Implement operational discovery rescan loops

docs/operational-rescan-loops.md

@@ -0,0 +1,136 @@
+# Operational Rescan Loops
+
+`registry scan-manifest` is the operational entry point for repeated repo
+reality scans. It can run safely as a dry-run, keep local baselines, reconcile
+against registry-stored discovery snapshots, write a run report, and optionally
+ingest or accept reviewed discovery output.
+
+## Local Cache
+
+By default, manifest scans use a local runtime directory beside the manifest:
+
+```text
+.fabric-discovery/
+  snapshots/
+    <repo-slug>-<profile>.discovery.json
+  reports/
+    <timestamp>-<profile>.rescan-report.json
+  rescan.lock
+```
+
+This directory is ignored by git. It is operator/runtime state, not source. Use
+`--cache-dir` to place it elsewhere, `--output-dir` and `--previous-dir` for
+explicit snapshot locations, or `--no-cache` when a run should only write
+explicit outputs.
+
+## Standard Dry-Run
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --repo-slug railiance-fabric \
+  --dry-run
+```
+
+The first run is a baseline. Later runs use the cached snapshot directory by
+default and report `unchanged`, `changed`, or `review_required` per repo.
+
+## Registry-Backed Rescan
+
+Use the registry as the durable previous source:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --repo-slug railiance-fabric \
+  --previous-from-registry \
+  --dry-run
+```
+
+When `--ingest` is enabled, unchanged snapshots are skipped by default to avoid
+registry churn. Use `--ingest-unchanged` only when a full audit trail of every
+run is required.
+
+## Reports
+
+Every cached scan writes a `FabricDiscoveryRescanReport`. The schema is
+`schemas/rescan-run-report.schema.yaml`. Reports include:
+
+- manifest, registry URL, profile, cache paths, and scanner version
+- selected repos and LLM budget policy
+- previous snapshot source/id/path per repo
+- candidate counts, diff counts, review artifacts, connector runs, and errors
+- discovery snapshot ids and accepted graph snapshot ids when registry writes
+  occur
+
+Use `--report-output` for a specific path. Use `--json` to print the same report
+shape to stdout.
+
+## Acceptance Policy
+
+`--accept` requires `--ingest`. The default `--accept-policy safe` only projects
+candidates with `review_state: accepted` and blocks projection when the scan has
+conflicts, tombstones, or low-confidence LLM artifacts. Use
+`--accept-policy explicit` only for deliberate manual overrides, such as
+selected keys or non-default review states.
+
+## Automation Mode
+
+For cron or automation, use:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --previous-from-registry \
+  --dry-run \
+  --exit-code-mode operational
+```
+
+Operational exit codes:
+
+- `0`: no changes and no review/failure
+- `2`: baseline or changed repo reality detected
+- `3`: review required
+- `4`: one or more repo failures
+- `5`: rescan lock already exists
+
+The command creates a lock file under the cache directory by default. Use
+`--lock-file` for an explicit lock path or `--no-lock` when an outer scheduler
+already provides overlap protection.
+
+## Rescan Status
+
+The registry exposes latest discovery health in `/status` and per-repo
+inventory. The CLI view is:
+
+```bash
+railiance-fabric registry rescan-status --review-only
+```
+
+Use `--stale-after-hours <n>` to show snapshots older than an operational
+freshness window.
+
+## First Rollout
+
+The first controlled loop should stay small:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --repo-slug repo-scoping \
+  --repo-slug llm-connect \
+  --repo-slug railiance-fabric \
+  --previous-from-registry \
+  --dry-run
+```
+
+If the report shows clean baselines or expected changes, rerun with `--ingest`
+to store the baseline discovery snapshots. Broader all-local-repo rollout
+should wait until the small loop is repeatable and the review queue is readable.
+
+Initial implementation rollout on 2026-05-20:
+
+- Registry-backed previous lookup correctly reported per-repo failures while
+  the local registry service on `127.0.0.1:8765` was offline.
+- Local-cache dry-run completed for `repo-scoping`, `llm-connect`, and
+  `railiance-fabric`.
+- Result: 3 scanned, 2 baseline, 1 changed, 7 conflicted, 1 review required,
+  0 errors.
+- Follow-up: review `repo-scoping` conflicts before accepting or ingesting a
+  broad baseline.

docs/repo-reality-scanner.md

@@ -258,6 +258,10 @@ After review, rerun with `--ingest` to store the snapshots. Add `--accept` only
 when candidates marked `review_state: accepted` should be projected into the
 registry graph.
 
+For repeated operational loops, including default cache paths, registry-backed
+previous snapshots, run reports, exit codes, and rescan health views, see
+`docs/operational-rescan-loops.md`.
+
 ## Scan Profiles And Review Workflow
 
 The initial profile is `deterministic`, which means repo-local extraction plus