docHub

FVS Pact lookup chain

The lookup procedure for finding any FVS Pact rule, fragment, or constitutional artifact.

TL;DR

When you need to know "what does FVS say about X?" — the lookup chain has 6 steps. Use the index, don't re-derive.

The 6-step lookup chain

  1. pact/pipeline/codex/codex-overlays/alignment/overlay-question-index.md — Topic-Lookup Overlay (trace.atlas.topic-lookup.001). Start here for "what does FVS say about topic X?"
  2. pact/governance/dna/question-index.md — topic → file path. Falls back from the Topic-Lookup Overlay.
  3. pact/governance/dna/fragment-registry.md — fragment_id → file path. Use when you have a fragment_id.
  4. pact/governance/dna/constitutional-index.md — master map of constitutional artifacts. The "where is everything" index.
  5. pact/scripts/pact-search.sh "<query>" — full pact grep. Use when the indexes don't have what you need.
  6. Read the specific file — once you have a path, read the file. Don't re-derive the rule from the file path; read the file.

User-facing trigger phrases

Any of these routes to the same lookup:

If the operator says any of these, follow the chain. Don't ask "which topic?" — the chain is itself the answer.

What to do when a topic is NOT in pact

If after step 5 the topic is not found:

  1. Say "I don't see this in pact" — don't fabricate a rule
  2. Ask the operator: "Should I add a new fragment for this?"
  3. If yes, write a new fragment to the appropriate file (e.g., pact/platform/<area>/<topic>.md) and add it to the fragment-registry
  4. If no, surface that the topic is ungoverned and the operator should decide

Cross-references in docHub

docHub's dev face mirrors the lookup chain at _meta/contracts/pact.json (planned). For now, this file is the human-readable version of the contract.

When a docHub decision (D-NNN) cites a pact fragment, the citation format is:

**Pact ref — `<fragment_id>`** ([path](github-url))
> <quoted rule text>
**Relation to this decision:** <how the rule applies>

This format is required for any D-NNN that touches FVS doctrine.

Related

← back to Dev docs