gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.725028083

package/README.md

@@ -27,38 +27,46 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.81
+## What's New in v2.82
 
-### Worktree Safety & Projection
+### State Reconciliation & Drift Detection (ADR-017)
 
-- **Worktree safety is now fail-closed** — write/edit operations enforce the worktree-isolation contract before touching project files. If GSD cannot prove the active worktree is healthy, rooted correctly, and attached to the intended milestone, it stops instead of guessing.
-- **Custom-engine bypasses are explicit** — custom workflow units can opt out of worktree safety checks only through the dedicated path for that runtime. That keeps normal auto-mode writes protected while avoiding false failures for engines that do not use the same worktree lifecycle.
-- **Lifecycle and projection are split into dedicated modules** — worktree entry, exit, root projection, and merge finalization now flow through clearer boundaries. This makes it easier to reason about when state is copied into a milestone worktree, when it is projected back to the project root, and which module owns each step.
-- **Milestone merge closeout is harder to wedge** — stale leases, orphaned preflight stashes, branch-mode drift, reused branches, and wrong-branch merges are detected or recovered more reliably. If GSD finds completed work stranded in a milestone branch or preflight stash, startup and closeout paths now have better recovery hooks.
-- **Projection bypasses were closed** — post-unit and phase flows now route through the Worktree State Projection path instead of ad hoc file movement. That keeps database state, milestone artifacts, and root projections aligned during long-running auto-mode sessions.
+- **Unified drift-detection framework** — a new state-reconciliation layer replaces ad-hoc recovery checks. Each drift kind (stale worker, unregistered milestone, roadmap divergence, missing completion timestamp, merge-state, stale render) is owned by a focused detector + idempotent repair handler registered in a single registry, with a cap=2 retry contract that ensures repair-then-retry settles cleanly.
+- **Stale session locks no longer block resume** — when a `/gsd auto` process is SIGKILL'd, sleep-killed, or otherwise crashes, the `auto.lock` file is left behind with a dead PID. Previously you had to wait out a 30-minute stale window before `/gsd` would resume. The new `stale-worker` drift handler verifies the PID is alive and clears orphaned locks proactively on startup.
+- **Unregistered milestones get imported automatically** — if you scaffold a milestone directory (with `ROADMAP.md`/`CONTEXT.md`/`SUMMARY.md`) but never re-imported, dispatch couldn't see it. The `unregistered-milestone` handler now imports those rows idempotently before dispatch.
+- **ROADMAP and DB stay in sync** — divergence between `ROADMAP.md` (parsed slice sequence + `depends` declarations) and the corresponding DB slice rows is detected per-milestone and reconciled via importer upserts plus an explicit `syncSliceDependencies` pass.
+- **Missing completion timestamps backfill from disk** — entities marked complete in the DB but with a null `completed_at` are now backfilled from `SUMMARY.md` mtime, deterministically and idempotently. Tasks are checked independently of their parent slice status (a bug in the first cut nested task iteration behind slice completion).
+- **Parallel spawns reconcile before fanning out** — `/gsd parallel start` and slice-parallel-dispatch now run reconciliation at the parent before spawning auto-loop workers, so workers don't independently race on shared drift. Gate failures surface a typed exit reason (`slice-parallel-reconciliation-failed`) and a user-visible message instead of a confused hang.
 
-### Memory, Context & Token Control
+### Worktree Lifecycle Refactor (ADR-016 — final phases)
 
-- **Memory relevance improved** — artifacts now carry integrity fingerprints, memories track last-hit time, and relevance scoring uses time decay. Recent, repeatedly useful memories can rank higher, while stale or superseded context is less likely to crowd out the current task.
-- **Artifact integrity is easier to preserve** — content hashes are retained through worktree reconciliation, so GSD can detect whether projected artifacts still match the state it expects. This supports safer recovery and reduces accidental drift between root and worktree state.
-- **Fallback memory search is safer** — when FTS5 is unavailable, LIKE-based fallback scans are capped and surfaced with warnings instead of silently becoming expensive. Memory ranking also guards against invalid decay settings producing unusable scores.
-- **Provider tools are scoped per request** — tool availability is narrowed at request time, with provider-boundary token audit support. The model sees the tools relevant to the current provider and task instead of carrying broad tool definitions through every request.
-- **Prompt and workflow context got leaner** — repeated workflow context is capped, prompt templates use portable paths, and many high-volume workflow prompts were compacted. The goal is less repeated instruction text in long sessions without removing the guardrails that keep planning, execution, and closeout on track.
-- **Token accounting is more accurate** — session tokens are reported separately from context in VS Code, the token encoder warms at startup, and provider-boundary audit hooks make it easier to understand where request size is coming from.
+- **Phase 2 complete** — the worktree-manager module finished absorbing fs primitives, git-CLI primitives, worktree-manager helpers, cache/preferences/paths, and the final `gitServiceFactory`. Lifecycle verbs are now first-class: `adoptOrphanWorktree`, `adoptSessionRoot`, `resumeFromPausedSession`, and `restoreToProjectRoot` are explicit entry points, and the stop-path routes through `restoreToProjectRoot` instead of ad-hoc cleanup. `mergeMilestoneStandalone` was extracted and `mergeMilestoneToMain` was privatized.
+- **Phase 3 closes strict-closure residuals** — dead defensive `s.basePath = s.originalBasePath` fallbacks were removed from both auto.ts stop-path catch blocks (the verb assigns `basePath` before any throwable work, so the fallback was unreachable). The public `WorktreeLifecycleDeps` interface dropped 15 `@deprecated` optional fields; the active dep bag is now three fields (`gitServiceFactory`, `worktreeProjection`, `mergeMilestoneToMain`). Test fixtures move to a dedicated `WorktreeLifecycleTestOverrides` type.
+
+### Auto-Mode Reliability
+
+- **`complete-slice` closeout is read-only** — the closeout prompt is no longer allowed to write project files, removing a class of races where closeout edits could fight with the next slice's setup. Write-gate planning and prompt contracts were updated to enforce this.
+- **Verification retries back off properly** — a new `verification-retry-policy.ts` adds bounded exponential backoff and runs stuck detection between attempts, so transient verification failures (slow tools, flaky LLM calls) no longer spin in tight retry loops.
+- **Auto-loop exit paths are journaled end-to-end** — post-unit finalize stops, all unit-end iteration exits, and the run-unit failsafe now journal cleanly. Auto-timeout recovery journaling completes its handoff record. The run-unit failsafe also defers when a recovery is already in flight to avoid double-firing.
+- **Ghost completions and stale telemetry are guarded** — auto-mode no longer stops on ghost completions before a milestone stop has actually fired, and unmerged-exit telemetry is gated on active worktrees so closed sessions don't generate noise.
+- **Session-switch hygiene** — completed-content aborts that fire while the session is switching are ignored instead of being misclassified as user aborts. Auto-commit skips `.gitignore`d task key files so the working tree stays clean across slices.
 
 ### TUI & Operator Experience
 
-- **Compact tool output is more useful** — compact cards show tool targets and low-signal tool output can roll up by phase.
-- **Terminal UI refreshed** — chat/tool cards align with the terminal design, adaptive refresher layouts landed, and the welcome/header lifecycle is more stable.
-- **Auto-mode stays anchored** — bottom anchoring, direct tool execution rollups, and lifecycle hook shutdown behavior were tightened.
+- **Operations console redesign** — the auto-mode dashboard, notification overlay, parallel-monitor overlay, health widget, header renderer, and welcome screen were all rebuilt against a new shared `render-kit`. The result is a more consistent visual language across overlays, with refreshed reference designs (`docs/dev/tui-recommended-design.html`, `tui-render-options.html`) and expanded test coverage for the new components.
+- **Milestone completion rollup** — at the boundary between milestones, auto-mode now renders a `CompletionDashboardSnapshot` summarizing success criteria results, definition-of-done results, requirement outcomes, deviations, follow-ups, key decisions, key files, lessons learned, total cost, total tokens, cache hit rate, and slice progress. You no longer have to scroll back through the transcript to see what a milestone actually delivered.
 
-### Reliability, Tests & CI
+See the full [Changelog](./CHANGELOG.md) for the complete v2.82 entry and prior releases.
 
-- **Auto-mode recovery tightened** — crash recovery, session handoff, stale milestone completion replay, stale leases, and complete-project restart loops were all hardened.
-- **E2E coverage expanded** — real-process MCP, fake LLM, native ABI, schema migration, Docker runtime, Windows runner, and multi-iteration loop coverage landed.
-- **CI is faster and less noisy** — merge/build gates were simplified, expensive PR jobs are gated, and merge-conflict PRs skip heavy jobs.
+<details>
+<summary>v2.81 highlights</summary>
 
-See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior releases.
+- **Worktree safety is fail-closed** — write/edit operations enforce the worktree-isolation contract; lifecycle and projection split into dedicated modules; milestone merge closeout is harder to wedge.
+- **Memory, context, and token control** — artifact integrity fingerprints, time-decay memory ranking, safer FTS5 fallback, request-time tool scoping, leaner workflow prompts, and more accurate session/context token accounting.
+- **TUI polish** — compact tool output with targets, refreshed chat/tool cards, adaptive refresher layouts, stable welcome/header lifecycle, and bottom-anchored auto-mode rendering.
+- **Reliability, tests, and CI** — auto-mode recovery and session handoff hardened, broad E2E coverage expansion (real-process MCP, fake LLM, native ABI, Docker, Windows), and a faster, less-noisy CI gate setup.
+
+</details>
 
 <details>
 <summary>v2.80 highlights</summary>
@@ -108,7 +116,7 @@ See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior
 
 - **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
 - **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
-- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; decisions and KNOWLEDGE patterns/lessons are memory-backed projections after the cutover
 - **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
 - **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
 - **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
@@ -330,6 +338,8 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
 
 **Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
+When progressive planning is enabled, the first slice is fully planned up front while later slices may appear in `M###-ROADMAP.md` with a `` `[sketch]` `` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs `refine-slice` just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.
+
 ### `/gsd auto` — The Main Event
 
 This is what makes GSD different. Run it, walk away, come back to built software.
@@ -340,7 +350,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 
 Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
 
-The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+The database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns/lessons are `pattern`/`gotcha` memories. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+
+`KNOWLEDGE.md` is hybrid: rules remain file-canonical, while patterns and lessons are stored in the `memories` table and rendered back into `KNOWLEDGE.md` on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.
 
 **What happens under the hood:**
 
@@ -534,13 +546,13 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 | `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
 | `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
-| `DECISIONS.md`     | Append-only register of architectural decisions                 |
-| `KNOWLEDGE.md`     | Cross-session rules, patterns, and lessons learned              |
+| `DECISIONS.md`     | Projected register of memory-backed architectural decisions     |
+| `KNOWLEDGE.md`     | Hybrid knowledge projection: manual Rules plus memory-backed Patterns/Lessons |
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
 | `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
 | `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
 | `STATE.md`         | Quick-glance dashboard rendered from the database                |
-| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
+| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies, and `` `[sketch]` `` badges for slices awaiting `refine-slice` |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
 | `S01-PLAN.md`      | Slice task decomposition with must-haves                        |
@@ -577,6 +589,12 @@ Every task has must-haves — mechanically checkable outcomes:
 
 The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).
 
+### Project Knowledge
+
+`.gsd/KNOWLEDGE.md` remains the human-readable register for durable project knowledge, but the memory store is now authoritative for generated Patterns and Lessons. On startup, GSD backfills existing `## Patterns` and `## Lessons Learned` rows into `gsd.db` memories, then rewrites `KNOWLEDGE.md` as a hybrid projection: the manual `## Rules` section is preserved from the file, while Patterns and Lessons are rendered from the backfilled memory rows.
+
+Keep hand-authored operating rules in `## Rules` or add them with `/gsd knowledge rule`. Patterns and Lessons that agents discover are retrieved through the memory system for prompts and projected back into `KNOWLEDGE.md` for review, reports, and git history.
+
 ### Dashboard
 
 `Ctrl+Alt+G` or `/gsd status` opens a real-time overlay showing:
@@ -821,7 +839,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. `KNOWLEDGE.md` keeps rules file-canonical and projects patterns/lessons from `memories` at session start. No in-memory state survives across sessions.
 
 ---
 

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-cec78fe13fe69412
+5c6d4acc2e1d8c2b

package/dist/resources/extensions/browser-tools/tools/screenshot.js

@@ -5,6 +5,7 @@ export function registerScreenshotTools(pi, deps) {
         name: "browser_screenshot",
         label: "Browser Screenshot",
         description: "Take a screenshot of the current browser page and return it as an inline image. Uses JPEG for viewport/fullpage (smaller, configurable quality) and PNG for element crops (preserves transparency). Optionally crop to a specific element by CSS selector.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             fullPage: Type.Optional(Type.Boolean({ description: "Capture the full scrollable page (default: false)" })),
             selector: Type.Optional(Type.String({

package/dist/resources/extensions/browser-tools/tools/zoom.js

@@ -9,6 +9,7 @@ export function registerZoomTools(pi, deps) {
         description: "Capture and optionally upscale a specific rectangular region of the page for detailed inspection. " +
             "Useful for dense UIs where full-page screenshots have text too small to read. " +
             "Returns the region as an inline image, same as browser_screenshot.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             x: Type.Number({ description: "Left coordinate of the region in CSS pixels." }),
             y: Type.Number({ description: "Top coordinate of the region in CSS pixels." }),

package/dist/resources/extensions/gsd/auto/phases.js

@@ -1656,6 +1656,15 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             return { action: "break", reason: "session-timeout" };
         }
+        if (unitResult.errorContext?.isTransient &&
+            errorCategory === "aborted") {
+            ctx.ui.notify(`Unit ${unitType} ${unitId} was aborted by the user. Pausing auto-mode (recoverable).`, "warning");
+            debugLog("autoLoop", { phase: "unit-aborted-transient-pause", unitType, unitId, category: errorCategory });
+            await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "unit-aborted-pause" };
+        }
         // All other cancelled states (structural errors, non-transient failures): hard stop
         if (s.currentUnit) {
             await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -728,12 +728,20 @@ export async function inlineDecisionsFromDb(base, milestoneId, scope, level) {
     try {
         const { isDbAvailable } = await import("./gsd-db.js");
         if (isDbAvailable()) {
-            const { queryDecisions, formatDecisionsForPrompt } = await import("./context-store.js");
+            // ADR-013 Phase 6 cutover (Stage 1): read decisions from the `memories`
+            // table. Both `queryDecisions` (legacy) and `queryDecisionsFromMemories`
+            // return identical Decision[] for active rows once Phase 5 dual-write is
+            // caught up. Switching the read here lets the destructive Phase 6 step
+            // (#5755) retire the legacy `decisions` table without changing prompt
+            // contents. Projection regen (`DECISIONS.md`) still sources from the
+            // legacy table — that switch lands separately to handle superseded
+            // history cleanly.
+            const { queryDecisionsFromMemories, formatDecisionsForPrompt } = await import("./context-store.js");
             // First query: try with both milestoneId and scope (if scope provided)
-            let decisions = queryDecisions({ milestoneId, scope });
+            let decisions = queryDecisionsFromMemories({ milestoneId, scope });
             // Cascade: if empty AND scope was provided, retry without scope
             if (decisions.length === 0 && scope) {
-                decisions = queryDecisions({ milestoneId });
+                decisions = queryDecisionsFromMemories({ milestoneId });
             }
             if (decisions.length > 0) {
                 // Use compact format for non-full levels to save ~35% tokens

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -355,6 +355,9 @@ async function writeContextModeCompactionSnapshot(basePath) {
     }
 }
 export function registerHooks(pi, ecosystemHandlers) {
+    // ADR-005 Phase 3b: surface pi-ai ProviderSwitchReport via audit, notification, and counter.
+    // Idempotent — only the first registerHooks call installs.
+    void import("../provider-switch-observer.js").then((m) => m.installProviderSwitchObserver());
     pi.on("session_start", async (_event, ctx) => {
         const basePath = contextBasePath(ctx);
         initSessionNotifications(ctx);
@@ -411,6 +414,8 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         await loadToolApiKeysForSession();
         if (!isAutoActive()) {
+            ctx.ui.setWidget("gsd-progress", undefined);
+            ctx.ui.setWidget("gsd-outcome", undefined);
             const { initHealthWidget } = await import("../health-widget.js");
             initHealthWidget(ctx);
         }

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -10,6 +10,7 @@ import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffect
 import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
@@ -116,19 +117,19 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
     }
+    const ctxProjectRoot = ctx.projectRoot;
+    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+        ? ctxProjectRoot
+        : process.cwd();
     let preferenceBlock = "";
     if (loadedPreferences) {
-        const cwd = process.cwd();
+        const cwd = basePath;
         const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
         preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
         if (report.warnings.length > 0) {
             ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
         }
     }
-    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
-    if (globalSizeKb > 4) {
-        ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
-    }
     // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
     // and best-effort — first run absorbs the existing decisions table into
     // the memory store; subsequent runs are a single sentinel SELECT.
@@ -136,12 +137,47 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
         const written = backfillDecisionsToMemories();
         if (written > 0) {
-            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
+            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store.`, "info");
         }
     }
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
+    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
+    // re-render the hybrid projection (manual Rules + projected Patterns +
+    // projected Lessons). Both are idempotent and best-effort — failures here
+    // can't block agent startup.
+    try {
+        const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
+        const writtenK = backfillKnowledgeToMemories(basePath);
+        if (writtenK > 0) {
+            ctx.ui.notify(`GSD: backfilled ${writtenK} KNOWLEDGE.md row${writtenK === 1 ? "" : "s"} into the memory store.`, "info");
+        }
+    }
+    catch (e) {
+        logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${e.message}`);
+    }
+    try {
+        const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
+        renderKnowledgeProjection(basePath);
+    }
+    catch (e) {
+        logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${e.message}`);
+    }
+    // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
+    // yet in the memories table. Read-only; never throws. Runs after the two
+    // backfills above so the gap report reflects post-backfill state.
+    try {
+        const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
+        reportConsolidationGaps(basePath);
+    }
+    catch (e) {
+        logWarning("bootstrap", `memory consolidation scan failed: ${e.message}`);
+    }
+    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
+    if (globalSizeKb > 4) {
+        ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
+    }
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -320,7 +356,9 @@ export async function loadMemoryBlock(userPrompt, opts = {}) {
     }
 }
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
-    // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
+    // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project,
+    //    user-maintained. NOT migrated to memories (which are project-scoped),
+    //    so the full file is injected unchanged.
     let globalKnowledge = "";
     let globalSizeKb = 0;
     const globalKnowledgePath = join(gsdHomeDir, "agent", "KNOWLEDGE.md");
@@ -336,14 +374,19 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
             logWarning("bootstrap", `global knowledge file read failed: ${e.message}`);
         }
     }
-    // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
+    // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific.
+    //    ADR-013 Stage 2b: Patterns and Lessons are projected from the
+    //    memories table and already reach the LLM via loadMemoryBlock. Inject
+    //    only the intro prose + `## Rules` section here to avoid duplicating
+    //    Patterns/Lessons content in the prompt. Rules stay manual per
+    //    ADR-013 line 39 and have no memory equivalent.
     let projectKnowledge = "";
     const knowledgePath = resolveGsdRootFile(cwd, "KNOWLEDGE");
     if (existsSync(knowledgePath)) {
         try {
-            const content = readFileSync(knowledgePath, "utf-8").trim();
-            if (content)
-                projectKnowledge = content;
+            const raw = readFileSync(knowledgePath, "utf-8").trim();
+            if (raw)
+                projectKnowledge = extractIntroAndRules(raw).trim();
         }
         catch (e) {
             logWarning("bootstrap", `project knowledge file read failed: ${e.message}`);
@@ -361,7 +404,7 @@ export function loadKnowledgeBlock(gsdHomeDir, cwd) {
     }
     const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
     return {
-        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
+        block: `\n\n[KNOWLEDGE — Rules from KNOWLEDGE.md (Patterns and Lessons reach the LLM via the memory block)]\n\n${body}`,
         globalSizeKb,
     };
 }

package/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -90,7 +90,7 @@ export function showHelp(ctx, args = "") {
         "  /gsd unpark [id]    Reactivate a parked milestone",
         "",
         "PROJECT KNOWLEDGE",
-        "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+        "  /gsd knowledge <type> <text>   Add a rule to KNOWLEDGE.md or capture a pattern/lesson to memories",
         "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
         "",
         "SHIPPING & BACKLOG",

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -303,8 +303,21 @@ export async function handleKnowledge(args, ctx) {
     const scope = state.activeMilestone?.id
         ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
         : "global";
-    await appendKnowledge(basePath, type, entryText, scope);
-    ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
+    // ADR-013 Stage 2c: Patterns and Lessons land in the memories table; the
+    // next session-start projection render emits them back into KNOWLEDGE.md.
+    // Rules stay file-canonical per ADR-013 line 39 — Rules are not migrated.
+    if (type === "rule") {
+        await appendKnowledge(basePath, type, entryText, scope);
+        ctx.ui.notify(`Added rule to KNOWLEDGE.md: "${entryText}"`, "success");
+        return;
+    }
+    const { captureKnowledgeEntry } = await import("./knowledge-capture.js");
+    const { id, written } = captureKnowledgeEntry(basePath, type, entryText, scope);
+    if (!written) {
+        ctx.ui.notify(`Could not persist ${type} — see logs for details.`, "error");
+        return;
+    }
+    ctx.ui.notify(`Captured ${type} ${id} to memories; KNOWLEDGE.md will render it on next session start.`, "success");
 }
 export async function handleRunHook(args, ctx, pi) {
     const parts = args.trim().split(/\s+/);

package/dist/resources/extensions/gsd/context-store.js

@@ -47,6 +47,118 @@ export function queryDecisions(opts) {
         return [];
     }
 }
+/**
+ * Internal: shared core for the two memory-sourced decision queries. Reads
+ * memory rows tagged with `sourceDecisionId` and reconstructs `Decision[]`
+ * from their `structured_fields` JSON.
+ *
+ * @param includeSuperseded — when false, drops rows whose
+ *   `structured_fields.superseded_by` is non-null. The supersedes-chain is
+ *   captured by the backfill (`memory-backfill.ts`) and kept in sync by
+ *   the backfill's drift auto-heal pass.
+ */
+function readDecisionsFromMemories(opts, includeSuperseded) {
+    if (!isDbAvailable())
+        return [];
+    const adapter = _getAdapter();
+    if (!adapter)
+        return [];
+    try {
+        const clauses = [
+            "category = 'architecture'",
+            "structured_fields LIKE '%\"sourceDecisionId\":\"%'",
+        ];
+        const params = {};
+        if (opts?.milestoneId) {
+            // when_context is a free-text JSON value; substring match preserves the
+            // semantics of `when_context LIKE '%milestoneId%'` on the legacy table.
+            clauses.push("json_extract(structured_fields, '$.when_context') LIKE :milestone_pattern");
+            params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+        }
+        if (opts?.scope) {
+            // Stage 1 used `json_extract` in main (post-merge); preserve that
+            // style here. Exact equality on the JSON value avoids the prefix
+            // collision risk LIKE patterns had (scope=M001 vs scope=M001-S01).
+            clauses.push("json_extract(structured_fields, '$.scope') = :scope");
+            params[':scope'] = opts.scope;
+        }
+        const sql = `SELECT seq, structured_fields FROM memories WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+        const rows = adapter.prepare(sql).all(params);
+        const decisions = [];
+        for (const row of rows) {
+            const seq = row['seq'];
+            const sfRaw = row['structured_fields'];
+            if (!sfRaw)
+                continue;
+            let sf;
+            try {
+                sf = JSON.parse(sfRaw);
+            }
+            catch {
+                continue;
+            }
+            const sourceId = sf['sourceDecisionId'];
+            if (typeof sourceId !== 'string' || sourceId.length === 0)
+                continue;
+            // Decision-level superseded status lives in structured_fields.superseded_by
+            // (written by mirrorDecisionToMemory / memory-backfill.ts). The top-level
+            // memories.superseded_by column is intentionally never set for decision mirrors,
+            // so active-only filtering must be done here in the JS loop.
+            const supersededBy = typeof sf['superseded_by'] === 'string' ? sf['superseded_by'] : null;
+            if (!includeSuperseded && supersededBy)
+                continue;
+            decisions.push({
+                seq,
+                id: sourceId,
+                when_context: typeof sf['when_context'] === 'string' ? sf['when_context'] : '',
+                scope: typeof sf['scope'] === 'string' ? sf['scope'] : '',
+                decision: typeof sf['decision'] === 'string' ? sf['decision'] : '',
+                choice: typeof sf['choice'] === 'string' ? sf['choice'] : '',
+                rationale: typeof sf['rationale'] === 'string' ? sf['rationale'] : '',
+                revisable: typeof sf['revisable'] === 'string' ? sf['revisable'] : '',
+                made_by: (typeof sf['made_by'] === 'string' ? sf['made_by'] : 'agent'),
+                superseded_by: supersededBy,
+            });
+        }
+        return decisions;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * ADR-013 Phase 6 cutover (Stage 1): read **active** decisions from the
+ * `memories` table instead of the legacy `decisions` table. Returns the
+ * same `Decision[]` shape as `queryDecisions` so downstream formatters
+ * work unchanged.
+ *
+ * Filter semantics match `queryDecisions` exactly:
+ * - active only (skips rows where `structured_fields.superseded_by` is set)
+ * - `milestoneId`: substring match on `structured_fields.when_context`
+ * - `scope`: exact match on `structured_fields.scope`
+ *
+ * Used by the prompt-inline path (`inlineDecisionsFromDb` in
+ * `auto-prompts.ts`). For the projection regen (which renders superseded
+ * rows too), see `getAllDecisionsFromMemories`.
+ */
+export function queryDecisionsFromMemories(opts) {
+    return readDecisionsFromMemories(opts, /* includeSuperseded */ false);
+}
+/**
+ * ADR-013 Phase 6 cutover (Stage 2a): read **all** decisions (active +
+ * superseded) from the `memories` table. Used by the DECISIONS.md
+ * projection regen in `saveDecisionToDb`, which must render the full
+ * supersedes-chain for the canonical register format.
+ *
+ * Equivalent to `SELECT * FROM decisions ORDER BY seq` over the legacy
+ * table — but sourced from memories so the legacy table can be retired
+ * in Stage 3. Includes `superseded_by` reconstructed from
+ * `structured_fields.superseded_by` (populated by the backfill's drift
+ * auto-heal pass).
+ */
+export function getAllDecisionsFromMemories() {
+    return readDecisionsFromMemories(undefined, /* includeSuperseded */ true);
+}
 /**
  * Query active (non-superseded) requirements with optional filters.
  * - milestoneId: combined with sliceId for precise filtering (e.g. %M005/S01%)