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.

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.
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.