@ssm-08/relay 0.4.0

package/lib/filter.mjs

@@ -0,0 +1,110 @@
+// ── Category weights ──────────────────────────────────────────────────────
+const SIGNALS = [
+  // High value — explicit decision language
+  { weight: 3, pattern: /\b(decided?|we('re| are) going with|chose|choice|picked|settled on|agreed)\b/i },
+
+  // High value — rejection / failure
+  { weight: 3, pattern: /\b(rejected?|doesn'?t work|won'?t work|tried .{0,30} (but|and it)|abandoned|reverted)\b/i },
+
+  // High value — deliberate hacks in code
+  { weight: 3, pattern: /\b(workaround|hack|hardcod\w*|stub|mock|placeholder|skip for now)\b/i },
+
+  // High value — known broken / intentionally deferred bugs
+  { weight: 3, pattern: /\b(known (issue|bug|broken)|intentionally (broken|disabled)|won'?t fix|deliberately (broken|disabled)|leaving .{0,15} broken)\b/i },
+
+  // Medium — scope signals
+  { weight: 2, pattern: /\b(out of scope|descoped|added to scope|deferred|cut|dropping)\b/i },
+
+  // Medium — open questions
+  { weight: 2, pattern: /\b(open question|still (need|deciding)|not sure yet|revisit|TBD)\b/i },
+
+  // Medium — maintenance flags
+  { weight: 2, pattern: /\b(TODO|FIXME|before (demo|launch|merge))\b/ },
+
+  // Low — weak signal words that need reinforcement
+  { weight: 1, pattern: /\b(actually|instead|broken|later|for now)\b/i },
+];
+
+// File edits are strong signal — team changed something deliberately
+const EDIT_TOOL_REGEX = /\[tool_use (Edit|Write|MultiEdit)\]/;
+const EDIT_WEIGHT = 3;
+
+// ── Structural signals (scored on transcript shape, not text) ─────────────
+function structuralScore(lines) {
+  let score = 0;
+  const turns = lines.filter(l => l && (l.type === 'user' || l.type === 'assistant'));
+
+  // Long sessions are more likely to contain decisions
+  if (turns.length >= 10) score += 2;
+  if (turns.length >= 20) score += 2;
+
+  // User messages that are long = explaining context or decisions, not just commands
+  const userLines = lines.filter(l => l && l.type === 'user');
+  const avgUserLength = userLines.reduce((sum, l) => {
+    const content = l.message?.content;
+    const text = typeof content === 'string' ? content : JSON.stringify(content || '');
+    return sum + text.length;
+  }, 0) / (userLines.length || 1);
+  if (avgUserLength > 200) score += 2;
+
+  // Multiple file edits = real work happened
+  const editCount = lines.filter(l => {
+    if (l?.type !== 'assistant') return false;
+    const content = l.message?.content;
+    return Array.isArray(content) && content.some(b =>
+      b?.type === 'tool_use' && ['Edit', 'Write', 'MultiEdit'].includes(b.name)
+    );
+  }).length;
+  if (editCount >= 3) score += 2;
+  if (editCount >= 8) score += 2;
+
+  return score;
+}
+
+// ── Threshold (env-overridable for faster test cycles) ────────────────────
+// Read at call time (not module load) so tests can set the env var after import.
+function getThreshold() {
+  const p = parseInt(process.env.RELAY_TIER0_THRESHOLD ?? '3', 10);
+  return isNaN(p) ? 3 : p;
+}
+
+// ── Main export ───────────────────────────────────────────────────────────
+export function scoreTier0(transcriptText, lines = []) {
+  if (typeof transcriptText !== 'string') return { score: 0, passes: false, breakdown: [] };
+  let score = 0;
+  const breakdown = [];
+
+  // Text-based signals
+  for (const { weight, pattern } of SIGNALS) {
+    const matches = transcriptText.match(new RegExp(pattern.source, 'gi'));
+    if (matches) {
+      // Cap contribution per category to avoid one word dominating
+      const contribution = Math.min(matches.length * weight, weight * 3);
+      score += contribution;
+      breakdown.push({ pattern: pattern.source, matches: matches.length, contribution });
+    }
+  }
+
+  // Edit tool signal (rendered transcript format: [tool_use Edit] {...})
+  const editMatches = (transcriptText.match(new RegExp(EDIT_TOOL_REGEX.source, 'g')) || []).length;
+  if (editMatches > 0) {
+    const contribution = Math.min(editMatches * EDIT_WEIGHT, EDIT_WEIGHT * 4);
+    score += contribution;
+    breakdown.push({ pattern: 'tool_use Edit/Write/MultiEdit', matches: editMatches, contribution });
+  }
+
+  // Structural score (operates on raw JSONL lines, not rendered text)
+  const structural = structuralScore(lines);
+  score += structural;
+  if (structural > 0) breakdown.push({ pattern: 'structural', matches: 1, contribution: structural });
+
+  const THRESHOLD = getThreshold();
+  return { score, passes: score >= THRESHOLD, threshold: THRESHOLD, breakdown };
+}
+
+// Backwards-compatible export for distiller.mjs and tests
+export function hasTier0Signal(transcriptText, lines = []) {
+  const { score, passes, threshold } = scoreTier0(transcriptText, lines);
+  process.stderr.write(`[relay] tier0 score=${score} threshold=${threshold} passes=${passes}\n`);
+  return passes;
+}

package/lib/memory.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function readMemory(memoryPath) {
+  if (!fs.existsSync(memoryPath)) return '';
+  return fs.readFileSync(memoryPath, 'utf8');
+}
+
+export function writeMemoryAtomic(memoryPath, content) {
+  const dir = path.dirname(memoryPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(
+    dir,
+    `.${path.basename(memoryPath)}.${process.pid}.${Date.now()}.tmp`
+  );
+  fs.writeFileSync(tmp, content, 'utf8');
+  let lastErr;
+  for (let i = 0; i < 3; i++) {
+    try { fs.renameSync(tmp, memoryPath); return; } catch (e) {
+      lastErr = e;
+      if (e.code !== 'EPERM' && e.code !== 'EBUSY') break;
+    }
+  }
+  try { fs.unlinkSync(tmp); } catch {}
+  throw lastErr;
+}

package/lib/sync.mjs

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// I1: array args to spawnSync — no shell, no injection surface
+// windowsHide: true prevents console window flash on Windows for each git call
+function git(args, cwd, { timeout = 10_000 } = {}) {
+  const r = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    const msg = (r.stderr || '').trim() || `exit code ${r.status}`;
+    throw Object.assign(new Error(msg), { status: r.status, stderr: r.stderr });
+  }
+  return (r.stdout || '').trim();
+}
+
+function appendLog(cwd, msg) {
+  try {
+    const logPath = path.join(cwd, '.relay', 'log');
+    fs.appendFileSync(logPath, `[${new Date().toISOString()}] ${msg}\n`);
+  } catch {}
+}
+
+function resetWatermarkTurns(cwd) {
+  const p = path.join(cwd, '.relay', 'state', 'watermark.json');
+  let renameLogged = false;
+  try {
+    let s = {};
+    try { s = JSON.parse(fs.readFileSync(p, 'utf8')); } catch {}
+    s.turns_since_distill = 0;
+    delete s.distiller_running; // prevent stuck flag if distiller was killed mid-flight
+    delete s.distiller_pid;     // clear stale PID alongside the flag
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(s, null, 2));
+    try { fs.renameSync(tmp, p); } catch (e) {
+      try { fs.unlinkSync(tmp); } catch {}
+      appendLog(cwd, `sync.resetWatermarkTurns: rename failed: ${e.message}`);
+      renameLogged = true;
+      throw e;
+    }
+  } catch (e) {
+    if (renameLogged) return;
+    appendLog(cwd, `sync.resetWatermarkTurns: failed: ${e.message}`);
+  }
+}
+
+// Implements RelaySync interface. Swap for CloudSync later by replacing this class.
+export class GitSync {
+  // Pull latest .relay/ files from remote. Fail-open — session proceeds on any error.
+  // Only fetches memory.md and broadcast/; .relay/state/ is gitignored and machine-local.
+  // opts.fetchTimeoutMs / opts.checkoutTimeoutMs override defaults (UPS uses tight caps).
+  pull(cwd, { fetchTimeoutMs = 3_000, checkoutTimeoutMs = 2_000 } = {}) {
+    // I3: env escape hatch for local-only or demo environments
+    if (process.env.RELAY_SKIP_PULL) return;
+
+    // I3: short-circuit if no remote configured — avoids 50ms spawn + guaranteed failure
+    try {
+      git(['config', '--get', 'remote.origin.url'], cwd, { timeout: 1_000 });
+    } catch {
+      return;
+    }
+
+    try {
+      git(['fetch', '--quiet'], cwd, { timeout: fetchTimeoutMs });
+    } catch (e) {
+      appendLog(cwd, `sync.pull: fetch failed: ${e.message}`);
+      return;
+    }
+
+    let remote;
+    try {
+      // Prefer the configured upstream tracking branch
+      remote = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], cwd, { timeout: 2_000 });
+    } catch {
+      try {
+        const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd, { timeout: 2_000 });
+        remote = `origin/${branch}`;
+      } catch {
+        appendLog(cwd, 'sync.pull: cannot determine remote tracking branch');
+        return;
+      }
+    }
+
+    // Checkout only .relay/ tracked files — no full rebase, no touch on user working tree
+    try { git(['checkout', remote, '--', '.relay/memory.md'], cwd, { timeout: checkoutTimeoutMs }); } catch {}
+    try { git(['checkout', remote, '--', '.relay/broadcast'], cwd, { timeout: checkoutTimeoutMs }); } catch {}
+  }
+
+  // Commit and push .relay/ changes. Retries on non-fast-forward with rebase.
+  push(cwd, sessionId) {
+    const shortId = (sessionId || 'unknown').slice(0, 8);
+
+    // Stage each path separately — if broadcast dir doesn't exist yet, don't abort the whole push
+    for (const p of ['.relay/memory.md', '.relay/broadcast']) {
+      try {
+        git(['add', p], cwd, { timeout: 5_000 });
+      } catch (e) {
+        appendLog(cwd, `sync.push: add ${p} failed (skipping): ${e.message}`);
+      }
+    }
+
+    // One diff call: get all staged names, bail if no relay files, unstage any non-relay files.
+    let nonRelayStaged = [];
+    try {
+      const staged = git(['diff', '--cached', '--name-only'], cwd, { timeout: 2_000 });
+      const allStaged = (staged || '').split('\n').filter(Boolean);
+      if (!allStaged.some((f) => f.startsWith('.relay/'))) return; // nothing relay to commit
+      nonRelayStaged = allStaged.filter((f) => !f.startsWith('.relay/'));
+      if (nonRelayStaged.length > 0) {
+        git(['reset', 'HEAD', '--', ...nonRelayStaged], cwd, { timeout: 5_000 });
+      }
+    } catch (e) {
+      appendLog(cwd, `sync.push: could not check staged files: ${e.message}`);
+    }
+
+    try {
+      // I1: commit message as array arg — shortId never touches a shell
+      git(['commit', '-m', `[relay] memory update (session ${shortId})`], cwd, { timeout: 5_000 });
+    } catch (e) {
+      appendLog(cwd, `sync.push: commit failed: ${e.message}`);
+      // Re-stage user files before returning so we don't silently unstage their work
+      if (nonRelayStaged.length > 0) {
+        try { git(['add', '--', ...nonRelayStaged], cwd, { timeout: 5_000 }); } catch {}
+      }
+      return;
+    }
+
+    // Re-stage user files after relay commit
+    if (nonRelayStaged.length > 0) {
+      try { git(['add', '--', ...nonRelayStaged], cwd, { timeout: 5_000 }); } catch {}
+    }
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        git(['push', 'origin', 'HEAD'], cwd, { timeout: 10_000 });
+        return; // success
+      } catch {
+        if (attempt < 2) {
+          const rebased = this._rebase(cwd);
+          if (!rebased) return; // conflict rolled back — stop retrying
+        } else {
+          appendLog(cwd, 'sync.push: failed after 3 attempts — leaving commit local');
+        }
+      }
+    }
+  }
+
+  // Fetch + rebase onto FETCH_HEAD. On conflict: abort, advance local HEAD to FETCH_HEAD
+  // via reset --mixed (safe: doesn't touch working tree outside .relay/), reset turns.
+  // Returns true if rebase succeeded (push can retry), false if conflict (caller stops).
+  _rebase(cwd) {
+    try {
+      git(['fetch', '--quiet'], cwd, { timeout: 5_000 });
+      git(['rebase', 'FETCH_HEAD'], cwd, { timeout: 10_000 });
+      return true;
+    } catch {
+      try { git(['rebase', '--abort'], cwd, { timeout: 5_000 }); } catch {}
+
+      // C1 fix: advance local HEAD to FETCH_HEAD so repo is no longer behind remote.
+      // reset --mixed moves HEAD + index to FETCH_HEAD without touching working tree
+      // (user's in-progress code changes are preserved; only .relay/ files differ).
+      try { git(['reset', '--mixed', 'FETCH_HEAD'], cwd, { timeout: 2_000 }); } catch {}
+
+      // Sync .relay/ tracked files in working tree to remote version
+      try { git(['checkout', 'FETCH_HEAD', '--', '.relay/memory.md'], cwd, { timeout: 2_000 }); } catch {}
+      try { git(['checkout', 'FETCH_HEAD', '--', '.relay/broadcast'], cwd, { timeout: 2_000 }); } catch {}
+
+      // Reset turn counter so next Stop hook triggers a fresh distillation
+      resetWatermarkTurns(cwd);
+      appendLog(cwd, 'sync._rebase: conflict — advanced to FETCH_HEAD, re-distill queued');
+      return false;
+    }
+  }
+
+  // Advisory local lock. Prevents two concurrent distillers from double-pushing on same machine.
+  // Returns a release function. Throws Error('LOCKED') if a fresh lock exists.
+  // Note: M4 edge case — if this is the repo's very first commit (no HEAD~1 parent),
+  // _rebase()'s reset --mixed HEAD~1 would fail silently; lock is still released correctly.
+  lock(cwd) {
+    const lockPath = path.join(cwd, '.relay', 'state', '.lock');
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+
+    // I4: 'wx' flag is atomic — fails with EEXIST if file already exists (no TOCTOU window)
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      fs.writeSync(fd, new Date().toISOString());
+      fs.closeSync(fd);
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // File exists — check if stale
+      try {
+        const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+        if (age < 60_000) throw new Error('LOCKED');
+        // Stale (> 60s) — steal it atomically: unlink first, then re-acquire with 'wx'.
+        // This avoids the TOCTOU race where two processes both observe stale age and both
+        // open with 'w' (non-exclusive), both believing they hold the lock.
+      } catch (e2) {
+        if (e2.message === 'LOCKED') throw e2;
+        // stat failed (e.g. ENOENT — file vanished between EEXIST and stat).
+        // Fall through to steal attempt — unlink is a no-op if file is gone.
+      }
+      // Atomic steal: unlink stale lock, then acquire exclusively.
+      // If another process steals it first, our 'wx' open throws EEXIST → LOCKED.
+      try { fs.unlinkSync(lockPath); } catch {}
+      const fd = fs.openSync(lockPath, 'wx'); // throws EEXIST if stolen by another process
+      fs.writeSync(fd, new Date().toISOString());
+      fs.closeSync(fd);
+    }
+
+    return () => { try { fs.rmSync(lockPath, { force: true }); } catch {} };
+  }
+}

package/lib/transcript.mjs

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+
+const MAX_TOOL_RESULT_CHARS = 800;
+const MAX_TOOL_INPUT_CHARS = 400;
+
+export async function readTranscriptLines(filePath) {
+  const lines = [];
+  let parseErrors = 0;
+  const rl = readline.createInterface({
+    input: fs.createReadStream(filePath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  for await (const raw of rl) {
+    if (!raw) continue;
+    try {
+      lines.push(JSON.parse(raw));
+    } catch {
+      parseErrors++;
+    }
+  }
+  if (parseErrors > 0) {
+    process.stderr.write(`[relay] transcript: ${parseErrors} malformed JSONL line(s) skipped in ${filePath}\n`);
+  }
+  return lines;
+}
+
+export function sliceSinceUuid(lines, watermarkUuid) {
+  if (!watermarkUuid) return lines;
+  const idx = lines.findIndex((l) => l && l.uuid === watermarkUuid);
+  if (idx < 0) return lines;
+  return lines.slice(idx + 1);
+}
+
+export function lastUuid(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i] && lines[i].uuid) return lines[i].uuid;
+  }
+  return null;
+}
+
+function truncate(s, n) {
+  if (!s) return '';
+  if (s.length <= n) return s;
+  return s.slice(0, n) + `... [truncated ${s.length - n} chars]`;
+}
+
+function stringifyInput(input) {
+  if (!input) return '';
+  try {
+    return truncate(JSON.stringify(input), MAX_TOOL_INPUT_CHARS);
+  } catch {
+    return '[unserializable input]';
+  }
+}
+
+function renderUserContent(content) {
+  if (typeof content === 'string') return content.trim();
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (!block) continue;
+    if (block.type === 'text' && block.text) {
+      parts.push(block.text.trim());
+    } else if (block.type === 'tool_result') {
+      const body =
+        typeof block.content === 'string'
+          ? block.content
+          : Array.isArray(block.content)
+          ? block.content
+              .map((c) => (c && c.type === 'text' ? c.text : ''))
+              .join('\n')
+          : '';
+      const err = block.is_error ? ' ERROR' : '';
+      parts.push(`[tool_result${err}] ${truncate(body.trim(), MAX_TOOL_RESULT_CHARS)}`);
+    } else if (block.type === 'image') {
+      parts.push('[image omitted]');
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+function renderAssistantContent(content) {
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (!block) continue;
+    if (block.type === 'thinking') continue; // always skip — internal reasoning, not signal
+    if (block.type === 'text' && block.text) {
+      parts.push(block.text.trim());
+    } else if (block.type === 'tool_use') {
+      parts.push(`[tool_use ${block.name}] ${stringifyInput(block.input)}`);
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+export function renderForDistiller(lines) {
+  let turn = 0;
+  const out = [];
+  for (const line of lines) {
+    if (!line || line.isSidechain) continue;
+    if (line.type === 'user') {
+      const msg = line.message;
+      if (!msg) continue;
+      const text = renderUserContent(msg.content);
+      if (!text) continue;
+      turn++;
+      out.push(`[turn ${turn}, user]\n${text}`);
+    } else if (line.type === 'assistant') {
+      const msg = line.message;
+      if (!msg) continue;
+      const text = renderAssistantContent(msg.content);
+      if (!text) continue;
+      turn++;
+      out.push(`[turn ${turn}, assistant]\n${text}`);
+    }
+  }
+  return out.join('\n\n');
+}

package/lib/util.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export function isMain(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    // realpathSync follows junctions/symlinks — avoids mismatch when plugin
+    // is registered via junction into ~/.claude/plugins/relay/
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    const meta = fs.realpathSync(path.resolve(fileURLToPath(metaUrl)));
+    return argv1 === meta;
+  } catch {
+    return path.resolve(process.argv[1]) === path.resolve(fileURLToPath(metaUrl));
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ssm-08/relay",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Shared team memory across Claude Code sessions",
+  "author": "ssm-08",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ssm-08/relay.git"
+  },
+  "homepage": "https://ssm-08.github.io/relay/",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "memory",
+    "team",
+    "plugin"
+  ],
+  "bin": {
+    "relay": "bin/relay.mjs"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "lib/",
+    "prompts/",
+    "commands/",
+    ".claude-plugin/",
+    "scripts/installer.mjs",
+    "distiller.mjs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 tests/*.test.mjs",
+    "test:e2e": "node scripts/test-e2e.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/prompts/distill.md

@@ -0,0 +1,65 @@
+You maintain a shared team memory file for an active software project. Every teammate's Claude Code session draws from this file to start warm. Your job: merge a new session transcript slice into the existing memory, keeping ONLY what a teammate joining fresh would genuinely need to avoid wasted time, contradictory decisions, or breaking something deliberately left in a known state.
+
+## Hard rules
+
+1. **Replace superseded entries.** If a new decision contradicts an old one, remove the old — never stack contradictions.
+2. **Remove resolved workarounds.** If the transcript shows a workaround was fixed or removed, delete it from "Live workarounds".
+3. **Never append blindly.** Every entry you keep must still be true and load-bearing right now. Cull stale entries aggressively.
+4. **No code snippets.** Reference files/functions by path (e.g. `hooks/session-start.mjs:42`). No copy-pasted code.
+5. **No conversation quotes.** Extract the conclusion, not the discussion. No "Alice said…" — just the fact.
+6. **Max 30 lines per section.** When near the limit, cull the least load-bearing entry.
+7. **Tag provenance.** Append `[session <short-id>, turn <n>]` to every entry you add or keep. Use the session id and turn numbers from the transcript. Keep tags on existing entries unchanged unless the fact itself is updated.
+8. **If nothing new qualifies, return the existing memory unchanged.** Do not rephrase for its own sake.
+
+## The guiding question
+
+For every entry you add or keep, ask:
+
+> Would a new Claude opening this project in 10 minutes genuinely need this, or is this noise?
+
+If the honest answer is "noise," drop it.
+
+## What counts as signal
+
+- **Decisions** — tech picks, architectural choices, scope calls. Only the resolved choice, not the deliberation.
+- **Rejected paths** — approaches tried and abandoned, with the one-line reason. Prevents re-litigation.
+- **Live workarounds** — deliberate shortcuts currently in the code that look like bugs but are intentional. E.g. hardcoded values, disabled checks, stubbed integrations.
+- **Known broken state** — things currently non-functional that the team consciously deferred. Must be both: (a) broken and (b) intentionally not fixed right now. E.g. a test disabled pending investigation, a feature failing a known edge case, a CI check temporarily bypassed. Remove once fixed.
+- **Scope changes** — things explicitly cut or added mid-build. Keep only if they affect what someone should/shouldn't touch.
+- **Open questions** — blocking unknowns the team is still resolving. Remove once answered.
+
+## What is NOT signal (drop even if mentioned)
+
+- Tool-call noise, file lists, grep output, build output.
+- Code the assistant wrote (the code is the code — memory is for *why*).
+- Commentary on what the model is about to do.
+- Generic advice, tutorials, or restated requirements from docs.
+- Anything already obvious from `README.md`, `CLAUDE.md`, or a 30-second codebase scan.
+
+## Output format
+
+Output the full new `memory.md` file content. Nothing else. No preamble, no trailing notes, no explanation of changes.
+
+Use these sections in this order. Omit a section entirely if empty (don't leave a bare header).
+
+```
+## Decisions
+- <fact> [session <id>, turn <n>]
+
+## Rejected paths
+- <approach>: <one-line reason> [session <id>, turn <n>]
+
+## Live workarounds
+- <file or area>: <what's intentional> [session <id>, turn <n>]
+
+## Known broken state
+- <what's broken>: <why deferred / unblocking condition> [session <id>, turn <n>]
+
+## Scope changes
+- <what changed> [session <id>, turn <n>]
+
+## Open questions
+- <question> [session <id>, turn <n>]
+```
+
+Total memory should stay under ~60 lines on a 2-hour transcript. If you're tempted to add a 31st entry to a section, you should be deleting one first.