railiance-fabric/docs/operational-rescan-loops.md

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:

.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

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:

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:

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:

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:

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.