Sigil: Inventory

Default layout:

.arcanum/inventory/
  README.md
  schema.md
  index.md
  index.json
  log.md
  tags.md
  indexes/
  raw/
  wiki/
  entries/
  queries/
  lint/

1. Run scripts/sync-runtime.sh --check --target <inventory-root> --json.
2. Review exact missing, drifted, and extra_managed paths.
3. Apply only when requested with scripts/sync-runtime.sh --apply --target <inventory-root> --json.
4. Re-run check and require a clean managed set.
5. Prove consumer-owned entries, queries, raw material, receipts, indexes, local schema, tags, and logs remain byte-identical.

The managed set is declared by runtime-manifest.json. Never broaden it from the target repository contents, and never treat runtime synchronization as permission to rewrite consumer knowledge state.

• contradictions between pages,
• stale claims superseded by newer sources,
• orphan pages with no incoming or outgoing links,
• important concepts mentioned but lacking pages,
• missing cross-references,
• untagged pages,
• invalid frontmatter when frontmatter is enabled,
• raw sources not yet inventoried,
• generated pages without source coverage,
• log entries that do not match the configured heading pattern,
• missing, stale, or unparsable index.json,
• failed projection conformance between configured sources, index.json, exact derived maps, index.md, and enabled projections,
• machine index rows that lack source path, projection source, freshness, validation boundary, or residue fields when required by the local schema,
• CSV projections that do not declare their index.json source or are treated as authoritative,
• evidence-cards missing source_refs,
• evidence-cards with unknown controlled vocabulary values,
• EvidenceSets with unknown controlled vocabulary values,
• EvidenceSets that reference missing evidence-card IDs,
• EvidenceSets that duplicate evidence-card source excerpts or summaries,
• full evidence-cards missing trace,
• terminal promotion status with promotion_owner: none,
• relation candidates missing a non-authority notice,
• unresolved residue that should be surfaced in lookup or validation output.

The machine index must be JSON, parse with jq, and preserve enough structure for downstream sigils to filter without reparsing Markdown. Repositories may add CSV projections for spreadsheets or shell pipelines, but CSV projections are secondary read models whose source must be index.json.

Minimum index.json shape:

{
  "schema_version": "inventory.index.v0.1",
  "inventory_root": ".arcanum/inventory",
  "generated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "human_index": "index.md",
  "entries": [
    {
      "id": "stable-entry-id",
      "path": "entries/example.md",
      "kind": "page | entry | query | lint | raw-manifest | evidence-card-bundle | evidence-set-bundle",
      "type": "concept",
      "title": "Entry title",
      "summary": "Short reusable summary.",
      "tags": ["inventory"],
      "sources": ["source/path.md#selector"],
      "updated": "YYYY-MM-DD",
      "status": "candidate",
      "confidence": "high | medium | low",
      "selectors": [],
      "evidence_card_ids": [],
      "evidence_set_ids": [],
      "residue": []
    }
  ],
  "indexes": {
    "by_id": {},
    "by_type": {},
    "by_tag": {},
    "by_source": {},
    "by_status": {},
    "by_evidence_card": {},
    "by_evidence_set": {}
  },
  "projections": [
    {
      "path": "projections/index.csv",
      "metadata": "projections/index.meta.json",
      "format": "csv",
      "source": "index.json",
      "purpose": "flat table export",
      "freshness": "generated-from-current-index",
      "enabled": true
    }
  ],
  "validation": {
    "parseable": true,
    "source_coverage": "complete | partial | unknown",
    "validation_boundary": "inventory-read-model-only",
    "projection_conformance": {
      "schema_version": "inventory.projection-conformance.config.v1",
      "governed_sources": [
        {"root": "entries", "patterns": ["**/*.md"]}
      ],
      "human_indexed_prefixes": ["entries/"],
      "uncontrolled_tags": "warn"
    }
  }
}

Optional indexes under indexes/*.json may specialize selector, link, backlink, tag, traceability, query-pattern, gap/risk, or projection lookup. They must declare their source index and remain Inventory read models, not Ontology Vault relations or Definitions Governance authority.

scripts/validate-index-json.sh is the lookup-readiness gate. Its projection conformance stage enumerates configured source roots, proves one-to-one source path and stable machine ID bindings, checks every indexed path, rebuilds all required maps in memory for exact comparison, compares human path/type columns where represented, and validates every enabled projection. Each enabled projection needs a JSON metadata file whose source_sha256 equals the current index.json, whose source_generated_at equals the current machine-index timestamp, and whose projection_sha256 equals the projection artifact. Uncontrolled historical tags are warnings unless a separately governed closed vocabulary says otherwise.

Required authoring behavior:

• every material claim points to source_refs or is explicitly marked as inference, synthesis, or open question,
• trace records field-level extraction or assignment decisions for full cards,
• residue preserves schema or instance ambiguity instead of hiding it,
• promotion_owner records who owns terminal promotion decisions,
• downstream packets include non-authority language and do not imply ontology or definition promotion,
• governed_ref appears only after the downstream owner creates a real governed artifact.

Required authoring behavior:

• reference evidence-card IDs instead of copying card content,
• include card_refs with inclusion reasons,
• include excluded_card_refs with boundary reasons,
• include index_terms for shell plus jq lookup,
• include handoff_target, synthesis_note, and residue,
• keep status candidate-level unless a later explicit promotion decision exists,
• do not imply ontology, definition, ledger, or Context Builder authority.

• source,
• entity,
• concept,
• architecture-layer,
• implementation-pattern,
• decision,
• capability,
• workflow,
• interface,
• dependency-rule,
• test-pattern,
• observability-signal,
• question,
• contradiction,
• synthesis.

Repositories may add custom entry types in schema.md when they define required fields, evidence rules, tag rules, and update behavior.

• machine index entry ID when available,
• inventory page path,
• evidence-card ID when available,
• selector or heading,
• summary,
• tags,
• confidence,
• source references,
• task obligation fit,
• excluded matches when useful,
• unresolved gaps.

For architecture-pattern-inventory, inventory output should support entries for:

• architecture layers,
• implementation patterns,
• dependency rules,
• test patterns,
• observability signals,
• relationship notes.

Inventory owns evidence-cards, indexes, lint findings, and handoff projections. Ontology Vault owns governed meaning, relations, confidence, and promotion. Definitions Governance owns canonical definitions. Evidence-card handoff packets are non-authority read models until a downstream owner accepts them.

• mode,
• install decisions,
• source count,
• entries created,
• entries updated,
• contradictions found,
• lint gaps,
• validation result,
• downstream sigil lookups,
• filed query syntheses.

• preserve raw source immutability,
• create or respect a local schema,
• maintain index.md, index.json, and log.md,
• tag generated pages consistently,
• link generated knowledge to source evidence,
• expose a parseable machine index before claiming lookup readiness,
• flag contradictions instead of hiding them,
• expose lookup results that other sigils can consume,
• avoid creating a competing system when a repository already has a usable wiki or inventory.

• editing raw sources during ingest,
• making generated pages the sole authority for source facts,
• leaving index.md as the only machine lookup surface after install or sync,
• treating CSV projections as authoritative when index.json is missing or stale,
• dumping source summaries without updating related pages,
• creating tags ad hoc without recording them,
• answering queries from raw files while ignoring the inventory,
• overwriting contradictions instead of recording them,
• installing a new package when existing repository conventions can be adapted,
• letting inventory maintenance replace human source curation.

## Inventory Result

- Mode: install | ingest | lookup | query | lint | validate | backfill | sync
- Repository: <path>
- Inventory root: <path>
- Files changed: <paths or none>
- Sources processed: <count>
- Entries created: <count>
- Entries updated: <count>
- Index updated: yes | no
- Machine index updated: yes | no | not applicable
- Log updated: yes | no
- Contradictions flagged: <count>
- Lint gaps: <count>
- Validation: pass | fail | not run
- Downstream lookup output: <summary or none>
- Next action: <action>