generated from coulomb/repo-seed
137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
# 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.
|