Shadow Forge

The Shadow Forge (RFC-0030) is a many-per-1 mapping of every actively-developed code file in our forge to one or more shadow-documents — each carrying a test or set of criteria the file is checked against, and each referencing a specific spec (an RFC-id / requirement id). Two purposes:

1. Anti-erosion coverage — the shadow-docs are the hidden acceptance tests a degenerate refactor cannot silently factor out (the congruency crankset is the proven instance: held-guarantee floor + shadow gate). 2. Learn the deficits in our specifications — a file with no citable spec, or a criterion with no spec to point at, is a hole in the spec. The catalog surfaces that backlog.

What's here

- rfc/RFC-0030-the-shadow-forge.md — the normative spec (SF-1 … SF-N). - builder/shadow_forge.py — the projector: scans the active source set, maps files → shadow-docs, detects spec citations (graft ids [SP-1] + RFC-NNNN), and emits the index. Canonical copy lives in jazz-forge/forge/shadow_forge.py; this is the shadow-forge's own home. - catalog.json / CATALOG.md — the current file→shadow→spec map, coverage, and the deficit backlog, generated from shadow_index.db. - shadows/ — assertion-sets that live HERE (test/criteria docs mapped to requirements). The congruency shadow-docs live in the congruency repo (tooling/congruencey-tests/*.py); the backup-strategy assertion-set (db_backup.assertions.json, [{req, assertion, …}]) lands here once built.

Rebuild

The index (~/bin/config/forge/shadow_forge/shadow_index.db) is rebuildable — see rebuild.md. It is a derived artifact; this repo is the source-of-truth for the concept + builder + catalog.

Surfaced in congruency

?page=shadowforge reflects the live index (coverage + deficits), read-only.