Forge Intelligence

Handbook

Dual wiki: four surfaces in Forge Intelligence

Forge Intelligence uses four distinct dual-wiki patterns. Do not conflate them.

Updated

Glossary

Name Canonical Derived Scope
Handbook pair fi docs/*.md fiw website/*.html Product documentation
Documentation dual-wiki docs/handbook/operator/ docs/handbook/system/ Platform handbook IA (user concepts vs maintainer depth)
Concept dual-wiki LMETA wiki/semantic/ LCDL wiki/execution/ Per intelligence_id overlay parity
Session dual-wiki machine/*.json human/report.md Per execution session

Handbook deploy sync: HANDBOOK-PAIR.md. Documentation dual-wiki requirements: handbook/shared/dual-wiki-requirements.md. Human-Life pack import: HUMAN-LIFE-PACK-V4.md.

Documentation dual-wiki (operator / system)

The published handbook separates what operators need to know from how maintainers implement it.

Operator System
Audience platform users, operators, integrators maintainers, pack authors, implementers
Content problems, outcomes, workflows, limits architecture, contracts, catalogs, ADRs
Form Markdown under docs/handbook/operator/ Markdown under docs/handbook/system/
Truth user-facing concepts (honest limits) technical source of truth for implementation

Layout

docs/handbook/
  operator/           # primary published IA — start here
  system/             # maintainer depth — secondary nav
  shared/             # feature-index, glossary, requirements

Rules

  1. Homepage leads with operator — docs/index.md Start here links operator pages first.
  2. Pair by feature ID — every material capability has FI-<DOMAIN>-<NNN> in feature-index.md.
  3. Do not duplicate deep docs — system pages link to existing ARCHITECTURE.md, maturity pages, concept wiki, vendor packs.
  4. Operator pages exclude backend — no src/ paths, schema dumps, or vendor prompt text as primary content.

Start: handbook/operator/overview.md. Maintainer: handbook/system/README.md.

Session dual-wiki (run/session trace)

Every intelligence session must document itself so a human can audit routing, token spend, and ambiguity outcomes.

Wiki M (machine canonical) Wiki H (human narrative)
Audience tools + evidence attach human steering / auditing
Content session, route trace, token ledger, ambiguity, artifacts story of the session
Form JSON under sessions/<id>/machine/ Markdown at sessions/<id>/human/report.md
Truth source of truth derived from M

Layout of a session

sessions/<session_id>/
  machine/
    session.json          # problem_class, policy_ref, case_id, graph_mode
    route_trace.json      # task graph rungs (task_id, capability_id, outcome)
    token_ledger.json     # planned vs spent per stage
    ambiguity.json        # assessments / escalations
    artifacts.json        # pack outputs / LCDL proof refs
  human/
    report.md             # generated from machine/*.json

Graph execution records each task node as a route_trace rung with capability_id.

Freeze gate (drift protection)

forge_intelligence.wiki.freeze_gate re-derives H from M and compares byte-for-byte against human/report.md.

pip install -e .
PYTHONPATH=src python3 -m forge_intelligence.wiki.freeze_gate sessions/<session_id>

Rules

  1. Never hand-edit human/report.md.
  2. Regenerate after any M change via forge_intelligence.wiki.generate_h.
  3. Attach machine JSON to EvidencePacket / ForgeRun extensions when consumers integrate.

Concept dual-wiki (LMETA / LCDL overlay)

Per Human-Life pack contract, each intelligence_id has paired semantic (LMETA) and execution (LCDL) wiki pages with identity-locked frontmatter (concept_id, semantic_version, capability_ids, invariant_ids).

Semantic (LMETA) Execution (LCDL)
Source seeds bundles/.../wiki_seeds/lmeta/ bundles/.../wiki_seeds/lcdl/
Projected to wiki/semantic/ wiki/execution/
Parity registry registries/overlay_registry.yaml same

Project with:

PYTHONPATH=tools python3 tools/project_concept_wiki.py

Parity is enforced by bundle validate_pack.py against overlay_registry.yaml.

Why generated-from-M (sessions)

  • H is always a faithful projection of what actually happened.
  • Machine records remain queryable for metrics (LLM skip rate, tokens per problem class).
  • One writer, one direction of truth: no reconciliation problem.

Adapted from forge-dark-factory dual-wiki pattern; extended for concept overlays and task graphs.