v1.57.5.0 feat: cross-session decision memory + gbrain dream-stage call graph

.gitignore

@@ -37,3 +37,6 @@ supabase/.temp/
 
 # Throughput analysis — local-only, regenerate via scripts/garry-output-comparison.ts
 docs/throughput-*.json
+
+# gbrain local source-staging dir (capability checks, source clones) — runtime artifact
+.sources/

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [1.57.5.0] - 2026-06-07
+
+## **Your agent now keeps its decisions, not just its code.**
+## **The durable calls you make, and the "why" behind them, are captured, curated, and resurfaced across sessions, with no daemon to run.**
+
+Every session you and the agent settle real decisions: pick an architecture, cut a scope, choose a tool, reverse an earlier call. Until now that reasoning lived only in a transcript that scrolls away, so the next session re-litigates settled questions or loses the "why." This release adds an institutional decision memory. Durable decisions land in an append-only, event-sourced store, the scope-relevant ones surface automatically at session start, and you can search them any time. It is file-only and works with gbrain off; when gbrain is up you can add semantic recall on top. The planning and ship skills capture their own key calls so the high-value decisions get recorded without anyone remembering to. Separately, `/sync-gbrain` learned to build the cross-reference call graph and to heal a crashed daemon's stale lock instead of wedging every sync.
+
+### The numbers that matter
+
+No speed benchmark here, the win is capability and reliability. These are the real shape of the release (`git diff 1.57.0.0..HEAD`, `bun test`):
+
+| Metric | Value |
+|--------|-------|
+| New commands | 2 (`gstack-decision-log`, `gstack-decision-search`) |
+| Session-start read cost | O(active) bounded snapshot, not a full-history scan |
+| Works with gbrain OFF | Yes, every capture/curate/resurface path is files + bins only |
+| New source | ~2,550 lines across 26 files |
+| New tests | 117 across the decision store + gbrain stages |
+
+Resurfaced decision text is treated as data, not instructions (datamarked at the render boundary), secrets are blocked on write, and `redact` expunges a decision from every read path. The whole loop degrades cleanly: turn gbrain off and you still capture, curate, and resurface.
+
+### What this means for you
+
+Start a session tomorrow and the agent already knows what you settled and why, instead of asking again or quietly reversing it. Log a call with `gstack-decision-log`, reverse one with `--supersede`, pull the relevant history with `gstack-decision-search`. CEO, eng, spec, and ship reviews record their decisions for you. Run `/sync-gbrain` and a crashed autopilot no longer blocks your next sync.
+
+### Itemized changes
+
+#### Added
+- **Cross-session decision memory.** An event-sourced (`decide`/`supersede`/`redact`) store at `~/.gstack/projects/<slug>/decisions.jsonl`. "Active" is computed, never a mutable flag, so the history stays honest and tolerant of dangling references.
+- **`gstack-decision-log`** — capture a durable decision, reverse one (`--supersede <id>`), expunge an accidental secret (`--redact <id>`), or rewrite the log to its active set (`--compact`). Non-interactive, injection-sanitized, blocks HIGH and MEDIUM secrets on write.
+- **`gstack-decision-search`** — read active decisions, scope-filtered to the current branch/issue, with `--recent N`, `--scope`, `--query`, `--all`, `--json`. Add `--semantic` (with `--query`) to append related hits from gbrain memory when it is up; it degrades silently to the reliable file results when gbrain is off.
+- **Session-start resurfacing.** Context Recovery shows the scope-relevant active decisions at the top of a session, from a bounded snapshot so it stays fast as the log grows.
+- **Skill capture.** `/plan-ceo-review`, `/plan-eng-review`, `/spec`, and `/ship` record their structured decisions (accepted scope, architecture verdict, filed spec, version bump) automatically.
+- **A `## Cross-session decision memory` section in CLAUDE.md** documenting when and how to capture and resurface.
+- **`/sync-gbrain` call-graph build (`--dream`).** Builds the symbol cross-reference graph behind a lock-free gate, with an honest outcome guard that reports a degraded no-op as WARN rather than a false success.
+
+#### Changed
+- Decision text that resurfaces into agent context is datamarked (code fences, `---` banners, `<|role|>`/`</system>` tags, chat turn-prefixes, and Unicode line terminators are neutralized) so stored text can never masquerade as instructions.
+- `/sync-gbrain` pin guidance is accurate for current gbrain, and the worktree-scoped `.gbrain-source` pin routes code queries correctly.
+
+#### Fixed
+- `/sync-gbrain` no longer wedges forever on a crashed autopilot daemon's stale lock: it reads the holder pid, confirms liveness, and ignores a dead one (it stays conservative when it cannot tell).
+
+#### For contributors
+- New shared `lib/jsonl-store.ts` (injection-reject + atomic single-line append + tolerant read) backs both the learnings and decision stores, so the sanitization path is audited in one place.
+- `lib/bin-context.ts` shares slug/branch/flag plumbing across the decision bins.
+
 ## [1.57.4.0] - 2026-06-08
 
 ## **The completeness principle is now Boil the Ocean, matching the post it came from.**

CLAUDE.md

@@ -905,6 +905,31 @@ Key routing rules:
 - Save progress → invoke /context-save
 - Resume context → invoke /context-restore
 
+## Cross-session decision memory
+
+Durable decisions and their rationale are captured in an append-only, event-sourced
+store at `~/.gstack/projects/<slug>/decisions.jsonl` so neither you nor the user
+re-litigates a settled call or loses the "why" across sessions. This is the reliable,
+file-only path: it works with gbrain OFF. (gbrain semantic recall is an optional
+enhancement layered on top, never a dependency.)
+
+- **Resurface** active decisions before re-deciding: `bin/gstack-decision-search`
+  (`--recent N`, `--scope repo|branch|issue`, `--query KW`, `--all`, `--json`).
+  Add `--semantic` (with `--query`) to append related hits from gbrain memory when
+  it's up; it degrades silently to the reliable file results when gbrain is off.
+  Session start already surfaces scope-relevant active decisions via Context Recovery.
+  If a decision is listed, treat it as settled with its rationale; if you're about to
+  reverse it, say so explicitly.
+- **Capture** a DURABLE decision when you or the user make one:
+  `bin/gstack-decision-log '{"decision":"...","rationale":"...","scope":"repo|branch|issue","source":"user|skill|agent","confidence":1-10}'`.
+  Reverse a prior call with `--supersede <id>`; expunge an accidental secret with
+  `--redact <id>`; rewrite the log to the active set with `--compact`. Non-interactive
+  (never prompts), injection-sanitized, and HIGH-secret-blocking on write.
+- **Durable means:** architecture choice, scope cut, tool/vendor choice, or a reversal
+  of a prior call. NOT a turn-level edit, a phrasing tweak, or anything trivially
+  re-derivable. Capture is curated at the source — log durable decisions only, or the
+  store becomes noise.
+
 ## GBrain Search Guidance (configured by /sync-gbrain)
 <!-- gstack-gbrain-search-guidance:start -->
 

VERSION

@@ -1 +1 @@
-1.57.4.0
+1.57.5.0

autoplan/SKILL.md

@@ -599,12 +599,19 @@ if [ -d "$_PROJ" ]; then
   fi
   _LATEST_CP=$(find "$_PROJ/checkpoints" -name "*.md" -type f 2>/dev/null | xargs ls -t 2>/dev/null | head -1)
   [ -n "$_LATEST_CP" ] && echo "LATEST_CHECKPOINT: $_LATEST_CP"
+  if [ -f "$_PROJ/decisions.active.json" ]; then
+    echo "--- ACTIVE DECISIONS (recent, scope-relevant) ---"
+    ~/.claude/skills/gstack/bin/gstack-decision-search --recent 5 2>/dev/null
+    echo "--- END DECISIONS ---"
+  fi
   echo "--- END ARTIFACTS ---"
 fi
 ```
 
 If artifacts are listed, read the newest useful one. If `LAST_SESSION` or `LATEST_CHECKPOINT` appears, give a 2-sentence welcome back summary. If `RECENT_PATTERN` clearly implies a next skill, suggest it once.
 
+**Cross-session decisions.** If `ACTIVE DECISIONS` are listed, treat them as prior settled calls with their rationale — do not silently re-litigate them; if you're about to reverse one, say so explicitly. Reach for `~/.claude/skills/gstack/bin/gstack-decision-search` whenever a question touches a past decision ("what did we decide / why / did we try"). When you or the user make a DURABLE decision (architecture, scope, tool/vendor choice, or a reversal) — NOT a turn-level or trivial choice — log it with `~/.claude/skills/gstack/bin/gstack-decision-log` (`--supersede <id>` for a reversal). Reliable and local; gbrain not required.
+
 ## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
 
 Applies to AskUserQuestion, user replies, and findings. AskUserQuestion Format is structure; this is prose quality.

bin/gstack-decision-log

@@ -0,0 +1,89 @@
+#!/usr/bin/env bun
+/**
+ * gstack-decision-log — append a durable decision (or supersede/redact/compact it).
+ *
+ * Usage:
+ *   gstack-decision-log '{"decision":"...","rationale":"...","scope":"repo","source":"user"}'
+ *   gstack-decision-log --supersede <decision-id>
+ *   gstack-decision-log --redact <decision-id>
+ *   gstack-decision-log --compact
+ *
+ * Event-sourced (lib/gstack-decision): every call appends an event and refreshes the
+ * bounded active snapshot. NON-INTERACTIVE — never prompts (agents/skills call this;
+ * a prompt would hang them). Validation + injection + HIGH-secret rejection happen in
+ * validateDecide; a rejected decision exits 1 with a message, nothing persisted.
+ */
+
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { spawnSync } from "child_process";
+import {
+  decisionPaths,
+  validateDecide,
+  makeRefEvent,
+  appendEvent,
+  rebuildSnapshot,
+  compact,
+  type DecisionEvent,
+} from "../lib/gstack-decision";
+import { resolveSlug, gitBranch, flagValue } from "../lib/bin-context";
+
+const HERE = import.meta.dir;
+
+const args = process.argv.slice(2);
+const slug = resolveSlug(`${HERE}/gstack-slug`);
+const paths = decisionPaths(slug);
+mkdirSync(dirname(paths.log), { recursive: true });
+
+function enqueue(): void {
+  // Fire-and-forget cross-machine sync (no-op when artifacts_sync is off).
+  spawnSync(`${HERE}/gstack-brain-enqueue`, [`projects/${slug}/decisions.jsonl`], { stdio: "ignore" });
+}
+
+if (args.includes("--compact")) {
+  const r = compact(paths);
+  if (r.skipped) {
+    console.log("compact skipped: a concurrent write/compact is in progress; log left intact — re-run");
+    process.exit(0);
+  }
+  console.log(`compacted: ${r.activeCount} active, ${r.archivedCount} archived, ${r.expungedCount} expunged`);
+  enqueue();
+  process.exit(0);
+}
+
+const supersedeId = flagValue(args, "--supersede");
+const redactId = flagValue(args, "--redact");
+if (supersedeId || redactId) {
+  const kind = supersedeId ? "supersede" : "redact";
+  const targetId = (supersedeId || redactId) as string;
+  appendEvent(paths, makeRefEvent(kind, targetId, { source: "agent" }));
+  rebuildSnapshot(paths);
+  enqueue();
+  console.log(`${kind}: ${targetId}`);
+  process.exit(0);
+}
+
+const jsonArg = args.find((a) => !a.startsWith("--"));
+if (!jsonArg) {
+  process.stderr.write(
+    "gstack-decision-log: provide a JSON decision, or --supersede/--redact <id>, or --compact\n",
+  );
+  process.exit(1);
+}
+let obj: Partial<DecisionEvent>;
+try {
+  obj = JSON.parse(jsonArg);
+} catch {
+  process.stderr.write("gstack-decision-log: invalid JSON\n");
+  process.exit(1);
+}
+if (obj.scope === "branch" && !obj.branch) obj.branch = gitBranch();
+const res = validateDecide(obj);
+if (!res.ok) {
+  process.stderr.write(`gstack-decision-log: ${res.error}\n`);
+  process.exit(1);
+}
+appendEvent(paths, res.event);
+rebuildSnapshot(paths);
+enqueue();
+console.log(res.event.id);

bin/gstack-decision-search

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * gstack-decision-search — read active decisions (the curated "what did we decide" view).
+ *
+ * Usage:
+ *   gstack-decision-search [--query KW] [--scope repo|branch|issue]
+ *                          [--branch B] [--issue I] [--recent N] [--all] [--json]
+ *                          [--semantic]
+ *
+ * Reads the BOUNDED active snapshot (decisions.active.json) — O(active), not a full
+ * history scan — and rebuilds it from the event log if missing. Scope-filtered to the
+ * current branch/issue context (recency != relevance). NON-INTERACTIVE. `--all` shows
+ * superseded decisions too (from the full log). Exit 0 silently when there are none.
+ *
+ * `--semantic` (with `--query`) appends an OPTIONAL "related from memory" block from
+ * gbrain semantic recall. It is a pure enhancement: when gbrain is off/unconfigured/
+ * empty it degrades silently to the reliable file results above. The reliable path
+ * never loads gbrain code (the semantic module is imported lazily only here).
+ */
+
+import { existsSync } from "fs";
+import {
+  decisionPaths,
+  readSnapshot,
+  rebuildSnapshot,
+  readEvents,
+  filterByScope,
+  datamark,
+  type ActiveDecision,
+} from "../lib/gstack-decision";
+import { resolveSlug, gitBranch, flagValue } from "../lib/bin-context";
+
+const HERE = import.meta.dir;
+const args = process.argv.slice(2);
+
+const slug = resolveSlug(`${HERE}/gstack-slug`);
+const paths = decisionPaths(slug);
+const queryRaw = flagValue(args, "--query");
+const query = queryRaw?.toLowerCase();
+const scope = flagValue(args, "--scope");
+const branch = flagValue(args, "--branch") ?? gitBranch();
+const issue = flagValue(args, "--issue");
+const recentRaw = flagValue(args, "--recent");
+const recent = recentRaw ? parseInt(recentRaw, 10) : undefined;
+const showAll = args.includes("--all");
+const asJson = args.includes("--json");
+const semantic = args.includes("--semantic");
+
+let rows: ActiveDecision[];
+if (showAll) {
+  // --all includes SUPERSEDED decisions (history), but NEVER redacted ones — a redact
+  // is an expunge, so it must remove the text from every read path, not just active.
+  const events = readEvents(paths);
+  const redacted = new Set(
+    events.filter((e) => e.kind === "redact" && e.supersedes).map((e) => e.supersedes as string),
+  );
+  rows = events.filter((e): e is ActiveDecision => e.kind === "decide" && !redacted.has(e.id));
+} else {
+  rows = readSnapshot(paths);
+  // Rebuild only when a snapshot is absent but a log exists (don't write a snapshot
+  // into a nonexistent store on an empty read — just return nothing).
+  if (!rows.length && existsSync(paths.log)) rows = rebuildSnapshot(paths);
+}
+
+rows = filterByScope(rows, { branch, issue });
+if (scope) rows = rows.filter((d) => d.scope === scope);
+if (query) {
+  rows = rows.filter((d) =>
+    [d.decision, d.rationale, d.alternatives_considered]
+      .filter((s): s is string => typeof s === "string")
+      .some((s) => s.toLowerCase().includes(query)),
+  );
+}
+rows.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0)); // newest first
+if (recent && recent > 0) rows = rows.slice(0, recent);
+
+if (asJson) {
+  // --json stays reliable-only (semantic recall is a human-facing supplement).
+  console.log(JSON.stringify(rows));
+  process.exit(0);
+}
+
+for (const d of rows) {
+  // Datamark all stored free-text (decision, rationale, branch/issue) — it lands in
+  // agent context via Context Recovery, so treat it as DATA, not instructions.
+  const branchTag = d.branch ? `:${datamark(d.branch)}` : "";
+  const issueTag = d.issue ? `:${datamark(d.issue)}` : "";
+  const scopeTag = d.scope === "repo" ? "" : ` [${d.scope}${branchTag}${issueTag}]`;
+  console.log(`- ${datamark(d.decision ?? "")}${scopeTag} (${d.source}, ${d.date.slice(0, 10)})`);
+  if (d.rationale) console.log(`  why: ${datamark(d.rationale)}`);
+}
+
+// OPTIONAL gbrain enhancement. Lazy import so the reliable path above never loads
+// gbrain code. Degrades silently: null (gbrain off) or [] (nothing found) leaves the
+// reliable results above as the answer.
+if (semantic && queryRaw) {
+  const { semanticRecall } = await import("../lib/gstack-decision-semantic");
+  const hits = semanticRecall(queryRaw);
+  if (hits && hits.length) {
+    console.log("\nRelated from memory (gbrain semantic recall):");
+    for (const h of hits) {
+      // gbrain hits are EXTERNAL corpus content — datamark slug + snippet too so they
+      // can't spoof role markers / fences when printed into agent context.
+      const snip = datamark(h.snippet.length > 100 ? `${h.snippet.slice(0, 100)}…` : h.snippet);
+      console.log(`  [${h.score.toFixed(2)}] ${datamark(h.slug)}: ${snip}`);
+    }
+  }
+}