Forge Intelligence

Handbook

Dual wiki: three surfaces in Forge Intelligence

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

Updated

Glossary

Name Canonical Derived Scope
Handbook pair fi docs/*.md fiw website/*.html Product documentation
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. Human-Life pack import: HUMAN-LIFE-PACK-V4.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.