Handbook

Sessions and audit (system)

Every intelligence session documents routing, token spend, ambiguity, and artifacts so humans can audit and tools can attach evidence.

Updated 2026-07-26

Intent

Every intelligence session documents routing, token spend, ambiguity, and artifacts so humans can audit and tools can attach evidence.

Behavior

Session layout

sessions/<session_id>/
  machine/
    session.json          # problem_class, policy_ref, case_id, graph_mode
    route_trace.json      # task graph rungs
    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

Schemas (v1 attach)

schemas/route_trace.v1.schema.json
schemas/token_ledger.v1.schema.json
schemas/ambiguity_assessment.v1.schema.json
schemas/intelligence_policy.v1.schema.json

Freeze gate

forge_intelligence.wiki.freeze_gate re-derives H from M and compares byte-for-byte. Regenerate via forge_intelligence.wiki.generate_h.

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

Rules

Never hand-edit human/report.md.
Regenerate after any M change.
Attach machine JSON to EvidencePacket / ForgeRun extensions.

sessions/ is excluded from fiw handbook build — runtime evidence only.

Limits

Session storage is FI-local; Lenses remains ForgeRun SoR. See SESSION-DATA-GOVERNANCE.md.

Forge Intelligence