FORGE Session Documentation Protocol#

Created: 2026m03d27

Purpose: This protocol makes faithful session logging structural rather than voluntary. It defines commands, file formats, and enforcement rules that prevent documentation from being forgotten, abbreviated, or skipped — across sessions, across context windows, and across conversation resets.

Why This Protocol Exists#

The problem: Claude tends to document well when explicitly reminded, then forgets in the next session. The user must constantly re-explain that documentation matters. This wastes effort and produces incomplete records.

The solution: embed documentation requirements into the forge prompt itself as non-optional protocol steps. Every phase transition writes to the LLog. Every prompt is recorded verbatim. The LLog file is the session’s ground truth — if it is not in the LLog, it did not happen.

Design principle: Documentation is a side effect of doing the work, not an extra step after the work is done. The forge agent writes LLog entries as part of phase transitions, not as a separate task.

Session Lifecycle Commands#

The user types these commands to control the session. The forge agent MUST respond to each command with the specified LLog action. Failure to do so is a protocol violation.

Command

Forge metaphor

What the agent MUST do

FORGE:IGNITE

Light the forge

Create session directory and files. Record scope, question, target area, date, loaded WB sheets. Write the IGNITE entry to the LLog. This is the ONLY command that creates files; all others append.

FORGE:HEAT

Heat the metal

Append HEAT phase header to LLog. Begin exploration: gather ideas, survey the problem space, identify relevant axioms and theorems. Every prompt-response pair in this phase is logged.

FORGE:STRIKE

Strike while hot

Append STRIKE phase header with HEAT summary. Begin formalization: write axioms, definitions, formal statements. Every prompt-response pair is logged.

FORGE:TEMPER

Temper the blade

Append TEMPER phase header with STRIKE summary. Begin stress-testing: Iron Maiden tests, adversarial critique, edge cases. Every prompt-response pair is logged.

FORGE:QUENCH

Quench to harden

Append QUENCH phase header with TEMPER summary. Consolidate: record findings, decisions, open questions, StayC verdicts. Write round summary.

FORGE:ROUND

Reheat for next pass

Append round boundary with QUENCH summary. Increment round counter. Automatically transitions to HEAT for the next round.

FORGE:BANK

Bank the fire

Proper session conclusion. Write session summary with: all findings, all StayC verdicts, all open questions, proposed HELL entries, and next steps. Update session meta with final status.

FORGE:EMBER

Recover from embers

Recovery command for interrupted sessions. Read existing LLog, reconstruct state, summarize where things left off. Append recovery entry. Continue with normal phase commands.

Session Directory Structure#

Each session creates a directory under forge/llog/:

Migration note (2026m04d04)

FORGE session llogs were moved from compiler/forge/llog/sa* to hell/ll/forge/b/{11,12,13}/ on 2026m04d04 to consolidate all llogs under hell/ll/. The protocol examples below still show the original paths for design reference. Current locations: hell/ll/forge/b/11/ (sa1), hell/ll/forge/b/12/ (sa2), hell/ll/forge/b/13/ (sa3).

forge/llog/
├── protocol.rst          (this file)
├── index.rst             (session registry --- one line per session)
└── sa1_2026m03d27/       (session directory) [moved to hell/ll/forge/b/11/]
    ├── meta.rst           (session metadata, updated at BANK)
    └── llog.rst           (append-only session transcript)

Session numbering: Uses delayed counting (a1–a9, b10–b99, c100–c999) prefixed with s. First session is sa1, ninth is sa9, tenth is sb10. The directory name appends the date in YYYYmMMdDD format: sa1_2026m03d27/. The index.rst registry tracks all sessions with one-line summaries.

File Formats#

meta.rst#

Created at IGNITE, updated at BANK:

:orphan:

FORGE Session Sa1 — Metadata
================================

:Session:    Sa1
:Date:       2026m03d27
:Status:     ACTIVE | BANKED | INTERRUPTED
:Scope:      [area of reality being modeled]
:Question:   [the driving question for this session]
:WB loaded:  [list of WisdomBase sheets loaded]
:Rounds:     [number of HEAT→QUENCH rounds completed]
:Forge:      forge_1m | forge_200k
:VVN-iv:     [user's VVN for this session's output]
:VVN-dv:     [Claude's VVN for this session's output]

LLog.rst#

Append-only. Every entry follows this template:

.. _forge_sa1_2026m03d27_ra1_heat_ea1:

Forge_Sa1_2026m03d27 | Round a1 | HEAT | Entry a1
----------------------------------------------------

.. container:: verbatim-prompt

   [EXACT user prompt — no abbreviation, no summary, no paraphrase.
    Copy the prompt character for character. This is non-negotiable.]

**Response summary:**

[Key points from the agent's response. For short responses, include
the full text. For long responses, summarize the key findings,
formal statements, and decisions — but NEVER omit formal content
(axioms, theorems, definitions, proofs). Those are recorded verbatim.]

**Findings:**

- [bullet list of things learned, discovered, or decided]

**StayC verdicts** (if any):

- [claim]: [MM|OO|PP|QQ|RR|SS|NN] — [one-line justification]

**Status:** [what just happened]
**Next:** [what the user should consider next]

Numbering scheme (delayed counting): All counters (session, round, entry) use the HELL-compatible delayed counting convention: a1–a9, b10–b99, c100–c999. The prefix letter encodes the digit count, so sort order is correct within each prefix group and no leading zeros are ever needed.

Phase labels: IGNITE, HEAT, STRIKE, TEMPER, QUENCH, ROUND, BANK, EMBER.

Label format: forge_{session}_{date}_{round}_{phase}_{entry} using lowercase delayed-count IDs and lowercase phase name. Example: forge_sa1_2026m03d27_ra1_heat_ea1, forge_sb12_2026m04d05_ra3_temper_eb14.

Display format: Forge_Sa1_2026m03d27 | Round a3 | TEMPER | Entry b14 using capitalized Forge_ prefix in human-facing text.

The date is the session start date. If a session spans multiple days, it keeps the FORGE:IGNITE date. This matches VVN convention.

Enforcement Rules#

These rules are NON-NEGOTIABLE. They must be embedded in the forge prompt (forge_1m.rst and forge_200k.rst) so that any fresh Claude session follows them without needing prior conversation history.

Rule 1: No response without a log entry. Every substantive response the forge agent gives MUST be accompanied by an append to the LLog file. If the agent finds itself about to respond without logging, it MUST log first. A response without a log entry is a protocol violation.

Rule 2: Verbatim prompts, always. The user’s prompt is recorded in .. container:: verbatim-prompt character-for-character. No abbreviation. No “the user asked about X.” The full text. This is the foundation of the audit trail.

Rule 3: Formal content is never summarized. Axioms, theorems, definitions, formal statements, and proofs are recorded verbatim in the LLog. Informal discussion can be summarized. The distinction: if it has symbols, quantifiers, or formal structure, it goes in full.

Rule 4: Phase transitions require summaries. When the user issues a phase transition command (HEAT→STRIKE→TEMPER→ QUENCH), the agent MUST write a summary of the outgoing phase before beginning the new phase. The summary includes: what was attempted, what succeeded, what failed, and what remains open.

Rule 5: BANK before leaving. If the user signals session end (explicitly or by running low on context), the agent MUST execute FORGE:BANK. If the user forgets, the agent reminds them. An unbanked session is an incomplete record.

Rule 6: EMBER reads before writing. When recovering an interrupted session (FORGE:EMBER), the agent MUST read the entire existing LLog and meta before appending anything. The recovery entry summarizes the state as understood from the LLog, flags any gaps, and proposes where to resume.

Rule 7: Append-only, forever. The LLog is append-only. NEVER overwrite, rewrite, or delete earlier entries. If an earlier entry is wrong, append a correction entry. If a StayC verdict changes, append the new verdict with a reference to the old one. The LLog is an immutable audit trail.

Rule 8: Session meta tracks status. The meta.rst file is updated at IGNITE (created with ACTIVE status), at BANK (updated to BANKED with final counts), and at EMBER (updated to ACTIVE if recovery succeeds, remains INTERRUPTED if it fails).

Multi-Round Sessions#

A single session can have multiple rounds. Each round is a full HEAT→STRIKE→TEMPER→QUENCH cycle:

IGNITE
├── Round a1: HEAT → STRIKE → TEMPER → QUENCH
├── ROUND (boundary)
├── Round a2: HEAT → STRIKE → TEMPER → QUENCH
├── ROUND (boundary)
├── Round a3: HEAT → STRIKE → TEMPER → QUENCH
└── BANK

When to start a new round:

  • The QUENCH phase revealed issues that need a second pass

  • The user wants to explore a different aspect of the same scope

  • A finding in TEMPER invalidated earlier STRIKE work

Scoping across rounds: The scope declared at IGNITE covers all rounds. If the scope needs to change fundamentally, BANK the current session and IGNITE a new one.

Session Timestamps and Duration#

The date in a session ID (e.g., 2026m03d27 in Forge_Sa1_2026m03d27) is the start date — the date when FORGE:IGNITE was run. If a session spans multiple days, it keeps the IGNITE date. This matches the VVN convention where dates mark the start of work, not its completion.

Recommendation (not enforced): Keep sessions short — ideally completed within a single day or sitting. Multi-day sessions accumulate context drift: the model developer’s thinking evolves between sittings, but the LLog cannot capture what happened off-record. A session that drags on for many days produces a less coherent audit trail than multiple focused sessions. If work on a topic spans several days, prefer BANK the current session and IGNITE a fresh one each day, linking them through the scope and open-questions fields. The LLog index (llog/index.rst) makes the continuity across sessions visible.

Interrupted Session Recovery#

Sessions can be interrupted by: context window exhaustion, network failure, user absence, or session timeout.

Recovery procedure:

  1. Start a new Claude session

  2. Load the forge prompt (forge_1m.rst or forge_200k.rst)

  3. Type FORGE:EMBER sa1 (where sa1 is the session ID)

  4. The agent reads llog/sa1_2026m03d27/llog.rst and llog/sa1_2026m03d27/meta.rst

  5. The agent appends an EMBER entry summarizing: - Last recorded phase and round - Last recorded findings - Where the session likely was when interrupted - Proposed resumption point

  6. The user confirms or redirects

  7. Normal phase commands resume

If the LLog is empty or missing: The session cannot be recovered. This is why Rule 1 (no response without a log entry) is critical — an unlogged session is an unrecoverable session.

Integration with FORGE Pipeline#

The LLog connects to the broader pipeline:

  • FORGE:QUENCH summaries feed into PROMY (for model revision)

  • FORGE:BANK proposed HELL entries feed into the HELL database

  • FORGE:BANK StayC verdicts feed into VV (version tracking)

  • FORGE:EMBER enables continuity across Claude sessions

The LLog itself is a permanent record that supports external review: anyone can read the LLog to see exactly how ideas progressed, what was tried, what failed, and why decisions were made.