Skip to main content
Two failure modes this layer exists to kill: partial work (code changes without the artifacts that depend on it) and session amnesia (the next session re-assumes what this one knew). Instructions raise the probability of correct behavior; deterministic hooks guarantee a floor.

​
Session anchoring

On SessionStart (src/session.js), Forge records HEAD once per session, prunes week-old session artifacts, and injects a fresh orientation:

Learned lessons

Cortex lessons mined from past corrections — stored in (and read from) the .forge ledger, the sole memory store.

The anchored goal

The stated goal, so drift can be measured against it.

The handoff snapshot

The bounded .forge/state.md the last session wrote.

Recent commits + changes

Recent commits and uncommitted changes — evidence, not priors.
A fresh session orients on evidence, not priors.

​
The completion gate

The only Stop-path guard that may answer is completion-gate.sh (src/gate.js). It runs synchronously; the lesson-mining cortex.sh stop stays detached and can never block. The changed set is session-scoped: files from commits whose committer time is at or after session start, plus working-tree changes minus the dirt snapshotted at SessionStart — so pre-existing edits, branch switches, and git pulls are never pinned on the agent.
If code moved with no doc or state artifact following, the gate blocks once with a repair checklist as the reason. Every other case allows, and every internal error allows (fail-open). FORGE_STOPGATE=0 disables it.
For sessions that changed code, the gate also requires test evidence — either a test file in the session’s diff or a fresh passing forge verify against the current changes. A forge handoff snapshot alone no longer clears the code-change branch of the gate. The repair checklist points at the tools that finish the work:

​
Handoff and decisions

Two stores keep knowledge across sessions: Both refuse secrets at write. state.md is re-injected each session start; decisions.md is read before re-deciding anything a past session settled.

​
The diff-driven docs sweep

forge docs sync answers the diff-shaped question: changed identifiers (paths, definitions, and called symbols, from added and removed lines) swept against every doc artifact → UPDATED / STALE (with file:line hits) / VERIFIED-UNAFFECTED, with the reason recorded. It is a pure reporter; the completion gate provides the teeth.
recall and cortex are file-and-prompt memory only — not weight-level learning. Consolidation is a summarizer that can hallucinate, so it stays advisory, human-reviewable, and secret-free.