.. meta:: :description: FORGE session documentation protocol — the structural enforcement mechanism that makes faithful logging non-optional in every forge session. :keywords: FORGE, llog, protocol, session logging, IGNITE, HEAT, STRIKE, TEMPER, QUENCH, BANK, EMBER, documentation, audit trail, matheology :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and Spirit of Boolean Truth .. _forge-llog-protocol: ********************************************************************* 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. .. list-table:: :header-rows: 1 :widths: 18 12 70 * - 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/``: .. admonition:: 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.