# 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.