feat: add STATUS.md as session handoff document

src/cli/init.ts

@@ -36,6 +36,7 @@ const CREATE_IF_MISSING = [
   "cerebrum.md",
   "memory.md",
   "anatomy.md",
+  "STATUS.md",
   "token-ledger.json",
   "buglog.json",
   "cron-manifest.json",
@@ -155,13 +156,15 @@ export async function initCommand(): Promise<void> {
     createdCount++;
   }
 
+  const newlyCreated = new Set<string>();
   for (const file of CREATE_IF_MISSING) {
     const destPath = path.join(wolfDir, file);
     if (fs.existsSync(destPath)) {
       skippedCount++;
     } else {
       writeTemplateFile(actualTemplatesDir, wolfDir, file);
       createdCount++;
+      newlyCreated.add(file);
     }
   }
 
@@ -171,6 +174,11 @@ export async function initCommand(): Promise<void> {
     seedIdentity(wolfDir, projectRoot);
   }
 
+  // --- STATUS.md: substitute {{PROJECT_NAME}} / {{DATE}} when freshly created ---
+  if (newlyCreated.has("STATUS.md")) {
+    seedStatus(wolfDir, projectRoot);
+  }
+
   // --- Token ledger: set created_at only if empty ---
   const ledgerPath = path.join(wolfDir, "token-ledger.json");
   const ledger = readJSON<Record<string, unknown>>(ledgerPath, {});
@@ -324,7 +332,7 @@ function readTemplateContent(filename: string, templatesDir: string): string {
 function getEmbeddedTemplate(filename: string): string {
   const templates: Record<string, string> = {
     "claude-md-snippet.md": `# OpenWolf\n\n@.wolf/OPENWOLF.md\n\nThis project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.`,
-    "claude-rules-openwolf.md": `---\ndescription: OpenWolf protocol enforcement — active on all files\nglobs: **/*\n---\n\n- Check .wolf/anatomy.md before reading any project file\n- Check .wolf/cerebrum.md Do-Not-Repeat list before generating code\n- After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md\n- After receiving a user correction, update .wolf/cerebrum.md immediately (Preferences, Learnings, or Do-Not-Repeat)\n- LEARN from every interaction: if you discover a convention, user preference, or project pattern, add it to .wolf/cerebrum.md. Low threshold — when in doubt, log it.\n- BEFORE fixing any bug or error: read .wolf/buglog.json for known fixes\n- AFTER fixing any bug, error, failed test, failed build, or user-reported problem: ALWAYS log to .wolf/buglog.json with error_message, root_cause, fix, and tags\n- If you edit a file more than twice in a session, that likely indicates a bug — log it to .wolf/buglog.json\n- When the user asks to check/evaluate UI design: run \`openwolf designqc\` to capture screenshots, then read them from .wolf/designqc-captures/\n- When the user asks to change/pick/migrate UI framework: read .wolf/reframe-frameworks.md, ask decision questions, recommend a framework, then execute with the framework's prompt`,
+    "claude-rules-openwolf.md": `---\ndescription: OpenWolf protocol enforcement — active on all files\nglobs: **/*\n---\n\n- Read .wolf/STATUS.md FIRST when resuming a session — it contains current quest, next steps, decisions\n- Update .wolf/STATUS.md (✅ done / 🚀 next quest) when a quest finishes or before suggesting /clear\n- Check .wolf/anatomy.md before reading any project file\n- Check .wolf/cerebrum.md Do-Not-Repeat list before generating code\n- After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md\n- After receiving a user correction, update .wolf/cerebrum.md immediately (Preferences, Learnings, or Do-Not-Repeat)\n- LEARN from every interaction: if you discover a convention, user preference, or project pattern, add it to .wolf/cerebrum.md. Low threshold — when in doubt, log it.\n- BEFORE fixing any bug or error: read .wolf/buglog.json for known fixes\n- AFTER fixing any bug, error, failed test, failed build, or user-reported problem: ALWAYS log to .wolf/buglog.json with error_message, root_cause, fix, and tags\n- If you edit a file more than twice in a session, that likely indicates a bug — log it to .wolf/buglog.json\n- When the user asks to check/evaluate UI design: run \`openwolf designqc\` to capture screenshots, then read them from .wolf/designqc-captures/\n- When the user asks to change/pick/migrate UI framework: read .wolf/reframe-frameworks.md, ask decision questions, recommend a framework, then execute with the framework's prompt`,
   };
   return templates[filename] ?? "";
 }
@@ -336,6 +344,7 @@ function generateTemplate(destPath: string, file: string): void {
     "cerebrum.md": `# Cerebrum\n\n> OpenWolf's learning memory.\n\n## User Preferences\n\n## Key Learnings\n\n## Do-Not-Repeat\n\n## Decision Log\n`,
     "memory.md": `# Memory\n\n> Chronological action log.\n`,
     "anatomy.md": `# anatomy.md\n\n> Project structure index. Pending initial scan.\n`,
+    "STATUS.md": `# STATUS\n\n> Single source of truth for resuming work. Read this FIRST when starting a session.\n> Update at the end of every quest so the next \`/clear\` resumes in 1 read.\n\n---\n\n## ✅ Concluído\n\n- (nothing yet — fill in as quests complete)\n\n---\n\n## 🚀 Próxima fase\n\n**Objetivo:** _<what we're building next>_\n\n### Critérios de aceitação\n1. _<concrete user-visible outcome>_\n\n### Arquivos a criar / editar\n- _<path + purpose>_\n\n### Decisões pendentes\n- _<question to ask before coding>_\n\n---\n\n## 📁 Arquitetura ativa\n\n- **Stack:** _<frameworks>_\n\n---\n\n## 🔧 Comandos úteis\n\n\`\`\`bash\n# add the most-used commands here\n\`\`\`\n`,
     "config.json": JSON.stringify({
       version: 1,
       openwolf: {
@@ -390,6 +399,19 @@ function seedCerebrum(wolfDir: string, projectRoot: string): void {
   writeText(cerebrumPath, cerebrum);
 }
 
+function seedStatus(wolfDir: string, projectRoot: string): void {
+  const statusPath = path.join(wolfDir, "STATUS.md");
+  if (!fs.existsSync(statusPath)) return;
+
+  const projectName = detectProjectName(projectRoot) || path.basename(projectRoot);
+  const date = new Date().toISOString().slice(0, 10);
+
+  let content = readText(statusPath);
+  content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+  content = content.replace(/\{\{DATE\}\}/g, date);
+  writeText(statusPath, content);
+}
+
 function seedIdentity(wolfDir: string, projectRoot: string): void {
   const projectName = detectProjectName(projectRoot);
   if (!projectName) return;

src/hooks/stop.ts

@@ -86,6 +86,9 @@ async function main(): Promise<void> {
   // Check if cerebrum was updated this session (it should be if there were edits)
   checkCerebrumFreshness(wolfDir, session);
 
+  // Check if STATUS.md is stale relative to this session
+  checkStatusFreshness(wolfDir, session);
+
   // Build session entry for ledger
   const reads = Object.entries(session.files_read).map(([file, data]) => ({
     file,
@@ -202,6 +205,37 @@ function checkForMissingBugLogs(wolfDir: string, session: SessionData): void {
   }
 }
 
+/**
+ * Check if STATUS.md is older than the session start AND there was meaningful
+ * code activity (3+ writes outside .wolf/). If so, nudge Claude to update
+ * STATUS.md so the next /clear has fresh handoff context.
+ */
+function checkStatusFreshness(wolfDir: string, session: SessionData): void {
+  const statusPath = path.join(wolfDir, "STATUS.md");
+  const codeWrites = session.files_written.filter(
+    (w) => !w.file.includes("/.wolf/") && !w.file.endsWith(".tmp")
+  );
+
+  try {
+    const stat = fs.statSync(statusPath);
+    const sessionStartMs = session.started ? Date.parse(session.started) : 0;
+    if (!sessionStartMs) return;
+
+    if (codeWrites.length >= 3 && stat.mtimeMs < sessionStartMs) {
+      process.stderr.write(
+        `📌 OpenWolf: STATUS.md not updated this session despite ${codeWrites.length} code writes. Update .wolf/STATUS.md (✅ done / 🚀 next quest) before /clear so next session resumes in 1 read.\n`
+      );
+    }
+  } catch {
+    // STATUS.md doesn't exist — nudge to create it if there were code writes
+    if (codeWrites.length >= 3) {
+      process.stderr.write(
+        `📌 OpenWolf: .wolf/STATUS.md missing. Create it with current quest summary + next steps so /clear stays cheap.\n`
+      );
+    }
+  }
+}
+
 /**
  * Check if cerebrum.md was updated recently. If it hasn't been updated in
  * a while and there was significant activity, emit a gentle reminder.

src/templates/OPENWOLF.md

@@ -2,6 +2,27 @@
 
 You are working in an OpenWolf-managed project. These rules apply every turn.
 
+## STATUS.md — Single Source of Truth (READ FIRST)
+
+`.wolf/STATUS.md` is the **first file** you read when resuming a session. It contains:
+- ✅ What is concluded (current quest finished)
+- 🚀 Next quest (objective, files to create, decisions fixed/pending)
+- 📁 Active architecture (stack, tables, patterns)
+- ⚠️ External pendencies
+- 🔧 Useful commands
+
+**At session start:** read `.wolf/STATUS.md` first. It replaces re-reading memory.md, plans, and code to reconstruct context.
+
+**MANDATORY — keep STATUS.md fresh:**
+1. When the user signals a quest is done ("done", "complete", "ship it", "next phase", "/clear", "wrap up"):
+   - Move just-finished items from `🚀 Próxima fase` → `✅ Concluído`.
+   - Replace `🚀 Próxima fase` with the next planned quest (objective, files, decisions).
+   - Bump "Last updated" date.
+2. After applying a migration, scaffolding a feature, or finishing a multi-file task: update STATUS.md before responding "done".
+3. Before suggesting `/clear` to the user, ensure STATUS.md reflects the current state.
+
+**The bar is HIGH for STATUS.md.** Stale STATUS.md = wasted next session. Always treat it as the handoff document.
+
 ## File Navigation
 
 1. Check `.wolf/anatomy.md` BEFORE reading any file. It has a 2-3 line description and token estimate for every file in the project.
@@ -131,5 +152,6 @@ When the user asks to change, pick, migrate, or "reframe" their project's UI fra
 
 Before ending or when asked to wrap up:
 
-1. Write a session summary to `.wolf/memory.md`.
-2. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`.
+1. **Update `.wolf/STATUS.md`** — move concluded work to ✅, write next quest in 🚀, bump date. This is the most important step for next session efficiency.
+2. Write a session summary to `.wolf/memory.md`.
+3. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`.

src/templates/STATUS.md

@@ -0,0 +1,64 @@
+# STATUS — {{PROJECT_NAME}}
+
+> Single source of truth for resuming work. Read this FIRST when starting a session.
+> Update this file at the end of every quest so the next `/clear` resumes in 1 read.
+> Last updated: {{DATE}}
+
+---
+
+## ✅ Concluído
+
+<!-- Move items here from "🚀 Próxima fase" when finished. Group by area. -->
+
+- (nothing yet — fill in as quests complete)
+
+---
+
+## 🚀 Próxima fase
+
+**Objetivo:** _<what we're building next, in 1 sentence>_
+
+### Critérios de aceitação
+1. _<concrete user-visible outcome>_
+2. _<...>_
+
+### Arquivos a criar / editar
+| Tipo | Arquivo | Conteúdo |
+|---|---|---|
+| novo | `path/to/file.ts` | _what it does_ |
+
+### Decisões fechadas
+- _<choice + reasoning>_
+
+### Decisões pendentes
+- _<question to ask the user before coding>_
+
+---
+
+## 📁 Arquitetura ativa
+
+- **Stack:** _<frameworks, libraries, runtime>_
+- **Tabelas / módulos chave:** _<list>_
+- **Padrões:** _<conventions enforced project-wide>_
+
+---
+
+## ⚠️ Pendências externas (não bloqueia coding)
+
+- _<env vars, secrets, external accounts, manual steps>_
+
+---
+
+## 🔧 Comandos úteis
+
+```bash
+# add the most-used commands here so the next session has them ready
+```
+
+---
+
+## 📚 Referências (leia SE precisar)
+
+- `.wolf/cerebrum.md` — User Preferences + Do-Not-Repeat + Decision Log
+- `.wolf/anatomy.md` — token-efficient file index
+- `.wolf/buglog.json` — known bugs + fixes

src/templates/claude-rules-openwolf.md

@@ -3,6 +3,8 @@ description: OpenWolf protocol enforcement — active on all files
 globs: **/*
 ---
 
+- Read .wolf/STATUS.md FIRST when resuming a session — it contains current quest, next steps, decisions
+- Update .wolf/STATUS.md (✅ done / 🚀 next quest) when a quest finishes or before suggesting /clear
 - Check .wolf/anatomy.md before reading any project file
 - Check .wolf/cerebrum.md Do-Not-Repeat list before generating code
 - After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md