Handbook

Dual wiki: machine canonical + generated human narrative

Public diagram of this trace and freeze gate: Bounded execution examples — dual-wiki trace (Blueprints handbook).

Updated

Public diagram of this trace and freeze gate: Bounded execution examples — dual-wiki trace (Blueprints handbook).

Every autonomous run must document itself so a human can back-trace decisions, see the roadmap, and audit what was implemented. The factory keeps two synchronized surfaces, following the workspace's existing dual-wiki / freeze pattern.

Wiki M (machine canonical) Wiki H (human narrative)
Audience the driver + tools a human steering / auditing
Content run, phases, artifacts, proof (structured) the story of the run
Form JSON under runs/<run_id>/machine/ Markdown at runs/<run_id>/human/report.md
Truth source of truth derived from M

Layout of a run

runs/<run_id>/
  machine/
    run.json          # RunRecord: goal, target, level, tier, final status, timestamps
    phases.json       # ordered PhaseRecord list (classify, route, context, plan, ...)
    artifacts.json    # ArtifactRecord list (patch, proof, context pack summary, ...)
    proof.json        # forge-lcdl proof_report_to_dict output
  human/
    report.md         # generated from machine/*.json

Freeze gate (drift protection)

wiki/freeze_gate.py re-derives H from the machine records (render_human(read_run(run_dir))) and compares the result byte-for-byte against human/report.md on disk. Non-zero exit on drift or a missing report. PDCA CHECK step 1 calls freeze_verify before assay and driver status.

Freeze gate checklist (audit a run)

  1. Layout — runs/<run_id>/machine/ contains run.json, phases.json, artifacts.json, and proof.json; runs/<run_id>/human/report.md exists.
  2. Canonical M — machine JSON is the source of truth; H is never edited by hand.
  3. Regenerate — after M changes, re-run the human generator (driver trace phase).
  4. Verify — from repo root: bash PYTHONPATH=src python3 -m forge_dark_factory.wiki.freeze_gate runs/<run_id> Expect stdout: human report matches machine records and exit 0.
  5. Drift hint — on failure, stderr reports DRIFT: with the first differing line (or length mismatch).
  6. Campaign runs — same layout under runs/campaigns/<campaign>/<item>/run-*/; CHECK fails the item if freeze gate fails before assay.

Rule: never hand-edit human/report.md. Change the machine records (or the generator), then regenerate.

Tests: tests/test_freeze_gate.py and wiki writer tests in tests/test_wiki_*.py.

Why generated-from-M

  • H is always a faithful projection of what actually happened.
  • The machine records remain a clean, queryable substrate for later phases (roadmap views, capability-card training, Lenses integration).
  • One writer, one direction of truth: no reconciliation problem.

See src/forge_dark_factory/wiki/.