@opengsd/gsd-core 1.5.0-rc.2 → 1.5.0-rc.4

package/commands/gsd/mempalace-capture.md

@@ -0,0 +1,71 @@
+---
+name: gsd:mempalace-capture
+description: "File a phase artifact into MemPalace; mirror decision facts into its temporal KG"
+argument-hint: "[CONTEXT.md|PLAN.md|SUMMARY.md]"
+allowed-tools:
+  - Read
+  - Bash
+requires: [config]
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+GSD > MEMPALACE CAPTURE
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Config Gate
+
+Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
+
+1. Read `.planning/config.json` with the Read tool.
+2. If the file does not exist, or `config.mempalace` is absent, or `config.mempalace.enabled !== true`, or `config.mempalace.capture_artifacts !== true`: display the disabled message and **STOP**.
+3. Otherwise proceed to Step 2.
+
+**Disabled message:**
+
+```
+GSD > MEMPALACE CAPTURE
+
+MemPalace capture is disabled (mempalace.enabled / mempalace.capture_artifacts).
+Nothing was filed; the loop proceeds normally.
+```
+
+This step is `onError: skip` at `discuss:post` / `plan:post` / `verify:post` -- capture never fails a phase.
+
+## Step 2 -- Resolve target
+
+1. **Artifact.** Take the artifact from `$ARGUMENTS`. If absent, infer from the loop point: `discuss:post` → `CONTEXT.md`, `plan:post` → `PLAN.md`, `verify:post` → `SUMMARY.md`.
+2. **Room.** Map artifact → room:
+   - `CONTEXT.md` → `decisions`
+   - `PLAN.md` → `planning`
+   - `SUMMARY.md` → `milestones`
+   (Confirmed problem→fix pairs go to `problems` — see the `capture-problems` fragment used at `execute:wave:post`.)
+3. **Wing.** `config.mempalace.wing` if non-empty, else `config.project_code`, else the repo directory name.
+4. **Mode / transport.** Read `config.mempalace.memory_mode`. Prefer MCP (`mempalace_*`) when your MemPalace MCP server is registered and your runtime permits those tools; otherwise use the `mempalace` CLI (covered by this skill's `Bash` allow-tool), as in `mempalace-recall`.
+
+## Step 3 -- File verbatim (idempotent)
+
+On any error or timeout, stop and let the phase continue -- capture is best-effort.
+
+1. **Dedup first.** Interactive: `mempalace_check_duplicate` on the artifact's deterministic drawer id. Headless: rely on `mempalace mine`'s content-hash idempotency.
+2. **Add the drawer (verbatim).** File the exact artifact text into `room: <room>` of `wing: <wing>` with provenance (`source_file`, phase id). Interactive: `mempalace_add_drawer`. Headless: `mempalace mine <path> --wing <wing> --room <room>`.
+3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Only `augment` is currently wired, so these are an *additive* mirror of `.planning/graphs/`. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
+4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
+
+## Step 4 -- Report
+
+Print a one-line summary: `Filed <artifact> → <wing>/<room> (<n> KG facts)` or `MemPalace unavailable — capture skipped`.
+
+## Anti-Patterns
+
+1. DO NOT let any MemPalace error fail the step -- capture is `onError: skip`.
+2. DO NOT write lossy summaries -- store the verbatim artifact text (AAAK compression is a separate, optional index).
+3. DO NOT prune or delete drawers here -- pruning (`sync --apply`) is the curator agent's job at `ship:post`, wing-scoped only.
+4. DO NOT skip the config gate or the dedup check.

package/commands/gsd/mempalace-recall.md

@@ -0,0 +1,102 @@
+---
+name: gsd:mempalace-recall
+description: "Recall decisions, patterns, and surprises from MemPalace before planning"
+argument-hint: "[phase-slug]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+requires: [config]
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
+
+## Step 0 -- Banner
+
+**Before ANY tool calls**, display this banner:
+
+```
+GSD > MEMPALACE RECALL
+```
+
+Then proceed to Step 1.
+
+## Step 1 -- Config Gate
+
+Check whether the MemPalace capability is enabled by reading `.planning/config.json` directly with the Read tool.
+
+**DO NOT use `gsd-tools config get-value`** -- it hard-exits on missing keys.
+
+1. Read `.planning/config.json` with the Read tool.
+2. If the file does not exist: write the "unavailable" stub (Step 4) and **STOP**.
+3. Parse the JSON. Proceed to Step 2 only if `config.mempalace && config.mempalace.enabled === true` **and** `config.mempalace.recall_on_plan !== false`. Otherwise display the disabled message and **STOP** (`recall_on_plan: false` turns plan-time recall off while leaving the rest of the capability enabled).
+
+**Disabled message:**
+
+```
+GSD > MEMPALACE RECALL
+
+MemPalace memory is disabled. To activate:
+
+  node <runtime-home>/gsd-core/bin/gsd-tools.cjs config-set mempalace.enabled true
+
+Recall is opt-in; the loop proceeds normally without it.
+```
+
+This step is `onError: skip` at `plan:pre` -- recall never blocks planning.
+
+## Step 2 -- Resolve wing, mode, and transport
+
+1. **Wing.** Use `config.mempalace.wing` if non-empty; otherwise derive from `config.project_code`; otherwise fall back to the repository directory name.
+2. **Mode.** Read `config.mempalace.memory_mode` (`augment` | `kg_backend` | `replace`, default `augment`). Only `augment` is wired today, so recall always treats the palace as additive; `kg_backend`/`replace` are forward-declared and behave as `augment`.
+3. **Transport.** Prefer the **MCP tools** (`mempalace_*`) in interactive runs *when your MemPalace MCP server is registered and your runtime permits those tools*. Otherwise — headless/cron/autonomous runs, or runtimes that don't grant the MemPalace MCP tools — use the **CLI** (`mempalace wake-up`, `mempalace search`), which this skill's `Bash` allow-tool always covers. If neither is reachable, go to Step 4.
+4. **Topic.** Read the phase `CONTEXT.md` (the consumed artifact). Derive a short search query from its title, goal, and key decisions.
+
+## Step 3 -- Retrieve (read-only)
+
+All calls in this step are side-effect-free. On any error or timeout, stop retrieving and write whatever was gathered (or the stub) -- never raise.
+
+1. **Wake up** (cheap, ~600--900 tokens):
+   - Interactive: read the wing identity/summary, then `mempalace_search`.
+   - Headless: `mempalace wake-up --wing <wing>`.
+2. **Targeted search:**
+   - Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
+   - Headless: `mempalace search "<topic>" --wing <wing>`.
+3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Only `augment` is currently wired, so the palace KG *supplements* GSD's native `.planning/graphs/` — do not treat it as the sole source. (`kg_backend`/`replace` are forward-declared and behave as `augment` today.)
+4. **Dedup** the returned drawers/facts; keep the top results.
+
+## Step 4 -- Write MEMORY-RECALL.md
+
+Write `MEMORY-RECALL.md` in the current phase directory. The planner consumes it.
+
+When recall succeeded, structure it as:
+
+```markdown
+# Memory Recall (MemPalace)
+
+_Wing: <wing> · Mode: <mode> · Transport: <mcp|cli>_
+
+## Prior decisions
+- <decision> — <provenance: drawer id / kg fact, valid_from>
+
+## Patterns
+- <pattern> — <provenance>
+
+## Surprises / gotchas
+- <surprise> — <provenance>
+```
+
+When MemPalace is unreachable, write the stub and continue:
+
+```markdown
+# Memory Recall (MemPalace)
+
+_MemPalace unavailable at recall time — proceeding without recalled memory._
+```
+
+## Anti-Patterns
+
+1. DO NOT let any MemPalace error fail the step -- recall is `onError: skip`.
+2. DO NOT write to the palace from this skill -- recall is read-only; capture is a separate skill.
+3. DO NOT paste raw search output into the file -- distil to decisions/patterns/surprises with provenance.
+4. DO NOT skip the config gate.

package/commands/gsd/ns-context.md

@@ -1,11 +1,11 @@
 ---
 name: gsd-context
-description: "codebase intelligence | map graphify docs learnings"
+description: "codebase intel | map graphify docs learnings mempalace"
 argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [map-codebase, graphify, docs-update, extract-learnings]
+requires: [map-codebase, graphify, docs-update, extract-learnings, mempalace-recall, mempalace-capture]
 ---
 
 Route to the appropriate codebase-intelligence skill based on the user's intent.
@@ -19,5 +19,7 @@ Route to the appropriate codebase-intelligence skill based on the user's intent.
 | Generate a knowledge graph | gsd-graphify |
 | Update project documentation | gsd-docs-update |
 | Extract learnings from a completed phase | gsd-extract-learnings |
+| Recall prior decisions and patterns before planning | gsd-mempalace-recall |
+| File a phase artifact into MemPalace | gsd-mempalace-capture |
 
 Invoke the matched skill directly using the Skill tool.

package/commands/gsd/progress.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:progress
 description: Check progress, advance workflow, or dispatch freeform intent — the unified GSD situational command
-argument-hint: "[--forensic | --next | --do \"task description\"]"
+argument-hint: "[--forensic | --next [--auto] [--converge] | --do \"task description\"]"
 effort: low
 allowed-tools:
   - Read
@@ -25,6 +25,7 @@ Three modes:
 <flags>
 - **--next**: Detect current project state and automatically invoke the next logical GSD workflow step. Scans all prior phases for incomplete work before routing. `--next --force` bypasses safety gates.
 - **--next --auto**: Like `--next`, but after the determined step completes, automatically re-invokes `/gsd:progress --next --auto` to continue chaining steps until completion or a blocking decision. Enables hands-free plan→execute→verify→complete progression.
+- **--next --converge**: When the next action is planning (Route 3), route it through the plan-review **convergence** loop instead of the standard planner. Requires `workflow.plan_review_convergence=true` (enable with `gsd config-set workflow.plan_review_convergence true`). `--cross-ai` is an alias. Reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`) and `--max-cycles N` are forwarded to the convergence loop.
 - **--do "..."**: Smart dispatcher — match freeform intent to the best GSD command using routing rules, confirm the match, then hand off.
 - **--forensic**: Run 6-check integrity audit after the standard progress report.
 - **(no flag)**: Standard progress check + intelligent routing (Routes A through F).

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-core",
-  "version": "1.5.0-rc.2",
+  "version": "1.5.0-rc.4",
   "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/gsd-core/bin/gsd-tools.cjs

@@ -58,6 +58,18 @@
  *     [--name <name>]
  *     [--archive-phases]               Move phase dirs to milestones/vX.Y-phases/
  *
+ * User Story Validation:
+ *   user-story validate --story "..."  Validate "As a / I want to / so that" format
+ *                                      Returns JSON { valid, errors[], slots: {role,capability,outcome} | null }
+ *                                      --pick valid  Emit bare boolean (for workflow boolean checks)
+ *
+ * Drift Guard (ADR-22):
+ *   drift-guard authority                Resolve effective source-grounding authority
+ *                                        (reads plan_review.source_grounding_authority + intel.enabled from config)
+ *   drift-guard severity --status <S>    Classify a symbol verdict into { severity, hardBlock }
+ *     [--authority <A>]                  Status: VERIFIED|MISSING|AMBIGUOUS|UNCHECKABLE
+ *                                        Authority: grep|intel|treesitter|lsp|scip (default: config-resolved)
+ *
  * Validation:
  *   validate consistency               Check phase numbering, disk/roadmap sync
  *   validate health [--repair]         Check .planning/ integrity, optionally repair
@@ -201,8 +213,6 @@ const milestone = require('./lib/milestone.cjs');
 const commands = require('./lib/commands.cjs');
 const init = require('./lib/init.cjs');
 const frontmatter = require('./lib/frontmatter.cjs');
-const profilePipeline = require('./lib/profile-pipeline.cjs');
-const profileOutput = require('./lib/profile-output.cjs');
 const workstream = require('./lib/workstream.cjs');
 const docs = require('./lib/docs.cjs');
 const learnings = require('./lib/learnings.cjs');
@@ -214,6 +224,7 @@ const verification = require('./lib/verification.cjs');
 const { routeInitCommand } = require('./lib/init-command-router.cjs');
 const loopResolver = require('./lib/loop-resolver.cjs');
 const capabilityState = require('./lib/capability-state.cjs');
+const capabilityWriter = require('./lib/capability-writer.cjs');
 const { routePhaseCommand } = require('./lib/phase-command-router.cjs');
 const { routePhasesCommand } = require('./lib/phases-command-router.cjs');
 const { routeValidateCommand } = require('./lib/validate-command-router.cjs');
@@ -222,6 +233,8 @@ const { routeAgentCommand } = require('./lib/agent-command-router.cjs');
 const { routeCheckCommand } = require('./lib/check-command-router.cjs');
 const { routeTaskCommand } = require('./lib/task-command-router.cjs');
 const { parseNamedArgs, parseMultiwordArg } = require('./lib/command-arg-projection.cjs');
+const { cmdGitBaseBranch } = require('./lib/git-base-branch.cjs');
+const { getEffectiveAuthority, classifyDriftSeverity } = require('./lib/plan-drift-guard.cjs');
 
 // ─── Bridge collapsed (Phase 4) ────────────────────────────────────────────────
 // Non-family commands now run through their CJS handlers directly. Keep the
@@ -505,12 +518,12 @@ async function main() {
   const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
     'Commands: agent, agent-skills, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, ' +
     'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
-    'current-timestamp, detect-custom-files, docs-init, effort, extract-messages, find-phase, ' +
+    'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
-    'capability, classify-confidence, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
+    'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
-    'task, template, validate, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
+    'task, template, user-story, validate, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
     '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
@@ -559,6 +572,7 @@ async function main() {
     'verify-summary', 'template', 'frontmatter', 'detect-custom-files',
     'worktree', 'prompt-budget',
     'research-store', 'research-plan', 'package-legitimacy', 'classify-confidence',
+    'user-story', // pure string validation — no .planning/ access needed
   ]);
   if (!SKIP_ROOT_RESOLUTION.has(command)) {
     cwd = findProjectRoot(cwd);
@@ -1236,7 +1250,39 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       // loop render-hooks <point>
       const loopSubcommand = args[1];
       if (loopSubcommand === 'render-hooks') {
-        loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {});
+        let loopConfigDir = null;
+        const configDirEqArg = args.find(arg => arg.startsWith('--config-dir='));
+        const configDirIdx = args.indexOf('--config-dir');
+        if (configDirEqArg) {
+          const value = configDirEqArg.slice('--config-dir='.length).trim();
+          if (!value) error('Missing value for --config-dir', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          loopConfigDir = value;
+        } else if (configDirIdx !== -1) {
+          const value = args[configDirIdx + 1];
+          if (!value || value.startsWith('--')) {
+            error('Missing value for --config-dir', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          }
+          loopConfigDir = value;
+        }
+        // --active-cap <capId>: parse and validate before delegating
+        let loopActiveCap = undefined;
+        const activeCapEqArg = args.find(arg => arg.startsWith('--active-cap='));
+        const activeCapIdx = args.indexOf('--active-cap');
+        if (activeCapEqArg) {
+          const value = activeCapEqArg.slice('--active-cap='.length).trim();
+          if (!value) error('Missing value for --active-cap (e.g. --active-cap tdd)', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          loopActiveCap = value;
+        } else if (activeCapIdx !== -1) {
+          const value = args[activeCapIdx + 1];
+          if (!value || value.startsWith('--')) {
+            error('Missing value for --active-cap (e.g. --active-cap tdd)', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          }
+          loopActiveCap = value;
+        }
+        loopResolver.cmdLoopRenderHooks(cwd, args[2], raw, {
+          configDir: loopConfigDir ? path.resolve(loopConfigDir) : undefined,
+          activeCap: loopActiveCap,
+        });
       } else {
         error(
           `Unknown loop subcommand: ${loopSubcommand}. Available: render-hooks`,
@@ -1267,9 +1313,85 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         }
         const resolvedConfigDir = configDir ? path.resolve(configDir) : null;
         capabilityState.cmdCapabilityState(cwd, resolvedConfigDir, raw, {});
+      } else if (capSubcommand === 'set') {
+        // capability set <id> [--on|--off|--enable|--disable] [--gate <key>=<bool>]... [--config-dir <dir>] [--runtime <r>] [--scope <s>]
+        const capId = args[2];
+        if (!capId || capId.startsWith('--')) {
+          error('Missing capability id for: capability set <id>', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+        }
+        // Parse --config-dir
+        const setConfigDirIdx = args.indexOf('--config-dir');
+        let setConfigDir = null;
+        if (setConfigDirIdx !== -1) {
+          const setConfigDirVal = args[setConfigDirIdx + 1];
+          if (!setConfigDirVal || setConfigDirVal.startsWith('--')) {
+            error('Missing value for --config-dir', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          }
+          setConfigDir = setConfigDirVal;
+        }
+        const resolvedSetConfigDir = setConfigDir ? path.resolve(setConfigDir) : null;
+        // Parse --on/--enable and --off/--disable (mutually exclusive)
+        const hasOn = args.includes('--on') || args.includes('--enable');
+        const hasOff = args.includes('--off') || args.includes('--disable');
+        if (hasOn && hasOff) {
+          error('Conflicting flags: --on/--enable and --off/--disable cannot both be present', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+        }
+        let setEnabled;
+        if (hasOn) {
+          setEnabled = true;
+        } else if (hasOff) {
+          setEnabled = false;
+        }
+        // Parse --gate <key>=<bool> (repeatable)
+        const setGates = {};
+        for (let gi = 0; gi < args.length; gi++) {
+          if (args[gi] === '--gate') {
+            const gateVal = args[gi + 1];
+            if (!gateVal || gateVal.startsWith('--')) {
+              error('Missing value for --gate (expected <key>=<true|false>)', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+            }
+            const eqIdx = gateVal.indexOf('=');
+            if (eqIdx === -1) {
+              error(`Malformed --gate value "${gateVal}": expected <key>=<true|false>`, core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+            }
+            const gateKey = gateVal.slice(0, eqIdx);
+            const gateBoolStr = gateVal.slice(eqIdx + 1);
+            if (gateBoolStr !== 'true' && gateBoolStr !== 'false') {
+              error(`Malformed --gate value "${gateVal}": bool must be true or false`, core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+            }
+            setGates[gateKey] = gateBoolStr === 'true';
+            gi++; // skip consumed value
+          }
+        }
+        // Parse --runtime and --scope (validate that values are present and not flags)
+        const runtimeIdx = args.indexOf('--runtime');
+        let setRuntime;
+        if (runtimeIdx !== -1) {
+          const runtimeVal = args[runtimeIdx + 1];
+          if (!runtimeVal || runtimeVal.startsWith('--')) {
+            error('Missing value for --runtime', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          }
+          setRuntime = runtimeVal;
+        }
+        const scopeIdx = args.indexOf('--scope');
+        let setScope;
+        if (scopeIdx !== -1) {
+          const scopeVal = args[scopeIdx + 1];
+          if (!scopeVal || scopeVal.startsWith('--')) {
+            error('Missing value for --scope', core.ERROR_REASON ? core.ERROR_REASON.USAGE : undefined);
+          }
+          setScope = scopeVal;
+        }
+        capabilityWriter.cmdCapabilitySet(
+          cwd,
+          resolvedSetConfigDir,
+          capId,
+          { enabled: setEnabled, gates: Object.keys(setGates).length > 0 ? setGates : undefined, runtime: setRuntime, scope: setScope },
+          raw,
+        );
       } else {
         error(
-          `Unknown capability subcommand: ${capSubcommand}. Available: state`,
+          `Unknown capability subcommand: ${capSubcommand}. Available: state, set`,
           core.ERROR_REASON ? core.ERROR_REASON.SDK_UNKNOWN_COMMAND : undefined,
         );
       }
@@ -1305,94 +1427,6 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
-    // ─── Profiling Pipeline ────────────────────────────────────────────────
-
-    case 'scan-sessions': {
-      const pathIdx = args.indexOf('--path');
-      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
-      const verboseFlag = args.includes('--verbose');
-      const jsonFlag = args.includes('--json');
-      await profilePipeline.cmdScanSessions(sessionsPath, { verbose: verboseFlag, json: jsonFlag }, raw);
-      break;
-    }
-
-    case 'extract-messages': {
-      const sessionIdx = args.indexOf('--session');
-      const sessionId = sessionIdx !== -1 ? args[sessionIdx + 1] : null;
-      const limitIdx = args.indexOf('--limit');
-      const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : null;
-      const pathIdx = args.indexOf('--path');
-      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
-      const projectArg = args[1];
-      if (!projectArg || projectArg.startsWith('--')) {
-        error('Usage: gsd-tools extract-messages <project> [--session <id>] [--limit N] [--path <dir>]\nRun scan-sessions first to see available projects.', ERROR_REASON.USAGE);
-      }
-      await profilePipeline.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath);
-      break;
-    }
-
-    case 'profile-sample': {
-      const pathIdx = args.indexOf('--path');
-      const sessionsPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
-      const limitIdx = args.indexOf('--limit');
-      const limit = limitIdx !== -1 ? parseInt(args[limitIdx + 1], 10) : 150;
-      const maxPerIdx = args.indexOf('--max-per-project');
-      const maxPerProject = maxPerIdx !== -1 ? parseInt(args[maxPerIdx + 1], 10) : null;
-      const maxCharsIdx = args.indexOf('--max-chars');
-      const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
-      await profilePipeline.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw);
-      break;
-    }
-
-    // ─── Profile Output ──────────────────────────────────────────────────
-
-    case 'write-profile': {
-      const inputIdx = args.indexOf('--input');
-      const inputPath = inputIdx !== -1 ? args[inputIdx + 1] : null;
-      if (!inputPath) error('--input <analysis-json-path> is required', ERROR_REASON.USAGE);
-      const outputIdx = args.indexOf('--output');
-      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
-      profileOutput.cmdWriteProfile(cwd, { input: inputPath, output: outputPath }, raw);
-      break;
-    }
-
-    case 'profile-questionnaire': {
-      const answersIdx = args.indexOf('--answers');
-      const answers = answersIdx !== -1 ? args[answersIdx + 1] : null;
-      profileOutput.cmdProfileQuestionnaire({ answers }, raw);
-      break;
-    }
-
-    case 'generate-dev-preferences': {
-      const analysisIdx = args.indexOf('--analysis');
-      const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
-      const outputIdx = args.indexOf('--output');
-      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
-      const stackIdx = args.indexOf('--stack');
-      const stack = stackIdx !== -1 ? args[stackIdx + 1] : null;
-      profileOutput.cmdGenerateDevPreferences(cwd, { analysis: analysisPath, output: outputPath, stack }, raw);
-      break;
-    }
-
-    case 'generate-claude-profile': {
-      const analysisIdx = args.indexOf('--analysis');
-      const analysisPath = analysisIdx !== -1 ? args[analysisIdx + 1] : null;
-      const outputIdx = args.indexOf('--output');
-      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
-      const globalFlag = args.includes('--global');
-      profileOutput.cmdGenerateClaudeProfile(cwd, { analysis: analysisPath, output: outputPath, global: globalFlag }, raw);
-      break;
-    }
-
-    case 'generate-claude-md': {
-      const outputIdx = args.indexOf('--output');
-      const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : null;
-      const autoFlag = args.includes('--auto');
-      const forceFlag = args.includes('--force');
-      profileOutput.cmdGenerateClaudeMd(cwd, { output: outputPath, auto: autoFlag, force: forceFlag }, raw);
-      break;
-    }
-
     case 'workstream': {
       const subcommand = args[1];
       if (subcommand === 'create') {
@@ -1984,6 +2018,154 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    // ─── User Story Validation (bug #1145) ────────────────────────────────────
+    //
+    // Invocation shapes (from mvp-phase.md and verify-work.md):
+    //   gsd_run query user-story.validate --story "$USER_STORY"
+    //   gsd_run query user-story.validate --story "$PHASE_GOAL" --pick valid
+    //
+    // Returns JSON: { valid: boolean, errors: string[], slots: { role, capability, outcome } | null }
+    //   - valid: true only when the story fully matches the canonical format
+    //   - errors: per-slot diagnostic strings (empty on success)
+    //   - slots: extracted role/capability/outcome on success; null on failure
+    //
+    // Canonical format (user-story-template.md):
+    //   "As a [user role], I want to [capability], so that [outcome]."
+    //   Each slot must be non-empty and contain non-whitespace content.
+    //
+    // No .planning/ access needed — pure string validation.
+
+    // #1146: single base-branch resolver for all forking workflows.
+    // Workflows call `gsd_run query git.base-branch` (dotted form normalised to
+    // command='git', args=['git','base-branch']).
+    case 'git': {
+      const subcommand = args[1];
+      if (subcommand !== 'base-branch') {
+        error(
+          `Unknown git subcommand: ${subcommand || '(none)'}. Available: base-branch`,
+          ERROR_REASON.SDK_UNKNOWN_COMMAND,
+        );
+        break;
+      }
+      cmdGitBaseBranch(cwd, args.slice(2));
+      break;
+    }
+
+    case 'user-story': {
+      const subcommand = args[1];
+      if (subcommand !== 'validate') {
+        error(`Unknown user-story subcommand: ${subcommand || '(none)'}. Available: validate`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        break;
+      }
+
+      const storyIdx = args.indexOf('--story');
+      const story = (storyIdx !== -1 && args[storyIdx + 1] && !args[storyIdx + 1].startsWith('--'))
+        ? args[storyIdx + 1]
+        : '';
+
+      // Canonical extraction regex — requires non-whitespace content in each slot
+      // (\S.*? ensures the slot isn't whitespace-only).
+      // Named groups: role / capability / outcome.
+      const USER_STORY_RE = /^As a (\S.*?), I want to (\S.*?), so that (\S.*?)\.$/;
+
+      const errors = [];
+      const trimmed = story.trim();
+      let slots = null;
+
+      if (!trimmed) {
+        errors.push('Story is empty. Required format: "As a [role], I want to [capability], so that [outcome]."');
+      } else {
+        // Per-clause guards produce targeted, actionable error messages before
+        // attempting the full regex. Guards are ordered: role → capability → outcome → period.
+        if (!/^As a \S/i.test(trimmed)) {
+          errors.push('Story must start with "As a [user role]," (role must be non-empty).');
+        }
+        if (!/, I want to \S/i.test(trimmed)) {
+          errors.push('Story must include ", I want to [capability]," (capability must be non-empty).');
+        }
+        if (!/, so that \S/i.test(trimmed)) {
+          errors.push('Story must include ", so that [outcome]." (outcome must be non-empty).');
+        }
+        if (!trimmed.endsWith('.')) {
+          errors.push('Story must end with a period (.).');
+        }
+        // Full-regex check only when per-clause guards all passed — avoids
+        // redundant "format mismatch" noise on top of specific error messages.
+        if (errors.length === 0) {
+          const m = USER_STORY_RE.exec(trimmed);
+          if (!m) {
+            errors.push('Story does not match the canonical format: "As a [role], I want to [capability], so that [outcome]."');
+          } else {
+            slots = { role: m[1], capability: m[2], outcome: m[3] };
+          }
+        }
+      }
+
+      core.output({ valid: errors.length === 0, errors, slots }, raw);
+      break;
+    }
+
+    case 'drift-guard': {
+      // ADR-22: deterministic authority resolution + severity classification.
+      // Subcommands:
+      //   drift-guard authority                          → effective authority string
+      //   drift-guard severity --status <S> [--authority <A>]  → {severity, hardBlock}
+      const subcommand = args[1];
+
+      // Read config.json directly for both plan_review.source_grounding_authority
+      // and intel.enabled. Neither key is in the config-loader.cjs whitelist that
+      // core.loadConfig() returns; plan_review is only in config.cjs's private
+      // buildConfig(), and intel is a federated capability config key.
+      let configuredAuthority = 'grep';
+      let intelEnabled = false;
+      try {
+        const { planningDir } = require('./lib/planning-workspace.cjs');
+        const cfgPath = require('path').join(planningDir(cwd), 'config.json');
+        if (require('fs').existsSync(cfgPath)) {
+          const rawCfg = JSON.parse(require('fs').readFileSync(cfgPath, 'utf-8'));
+          if (rawCfg && rawCfg.plan_review && rawCfg.plan_review.source_grounding_authority) {
+            configuredAuthority = String(rawCfg.plan_review.source_grounding_authority);
+          }
+          if (rawCfg && rawCfg.intel && rawCfg.intel.enabled === true) {
+            intelEnabled = true;
+          }
+        }
+      } catch {
+        // not fatal — defaults apply
+      }
+
+      const effectiveAuthority = getEffectiveAuthority(configuredAuthority, intelEnabled);
+
+      if (subcommand === 'authority') {
+        // Pass rawValue as 3rd arg so --raw returns unquoted string (not JSON)
+        core.output(effectiveAuthority, raw, effectiveAuthority);
+        break;
+      }
+
+      if (subcommand === 'severity') {
+        const statusIdx = args.indexOf('--status');
+        const statusVal = statusIdx !== -1 ? args[statusIdx + 1] : undefined;
+        if (!statusVal || statusVal.startsWith('--')) {
+          error('drift-guard severity requires --status <VERIFIED|MISSING|AMBIGUOUS|UNCHECKABLE>', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+          break;
+        }
+        const authIdx = args.indexOf('--authority');
+        const authVal = authIdx !== -1 ? args[authIdx + 1] : undefined;
+        const authorityForClassify = (authVal && !authVal.startsWith('--'))
+          ? authVal
+          : effectiveAuthority;
+        const result = classifyDriftSeverity({ status: statusVal, authority: authorityForClassify });
+        core.output(result, raw);
+        break;
+      }
+
+      error(
+        `Unknown drift-guard subcommand: ${subcommand || '(none)'}. Available: authority, severity`,
+        ERROR_REASON.SDK_UNKNOWN_COMMAND,
+      );
+      break;
+    }
+
     default: {
       // ADR-959: try capability-registry dispatch before emitting the unknown-command error.
       // An unmigrated command still hits its hardcoded `case` above — untouched.