feat: add unified post-planning gap checker (closes #2493) (#2610)

* feat: add unified post-planning gap checker (closes #2493) Adds a unified post-planning gap checker as Step 13e of plan-phase.md. After all plans are generated and committed, scans REQUIREMENTS.md and CONTEXT.md <decisions> against every PLAN.md in the phase directory and emits a single Source | Item | Status table. Why - The existing Requirements Coverage Gate (§13) blocks/re-plans on REQ gaps but emits two separate per-source signals. Issue #2493 asks for one unified report after planning so that requirements AND discuss-phase decisions slipping through are surfaced in one place before execution starts. What - New workflow.post_planning_gaps boolean config key, default true, added to VALID_CONFIG_KEYS, CONFIG_DEFAULTS, hardcoded.workflow, and cmdConfigSet (boolean validation). - New get-shit-done/bin/lib/decisions.cjs — shared parser for CONTEXT.md <decisions> blocks (D-NN entries). Designed for reuse by the related #2492 plan/verify decision gates. - New get-shit-done/bin/lib/gap-checker.cjs — parses REQUIREMENTS.md (checkbox + traceability table forms), reads CONTEXT.md decisions, walks PHASE_DIR/*-PLAN.md, runs word-boundary coverage detection (REQ-1 must not match REQ-10), formats a sorted report. - New gsd-tools gap-analysis CLI command wired through gsd-tools.cjs. - workflows/plan-phase.md gains §13e between §13d (commit plans) and §14 (Present Final Status). Existing §13 gate preserved — §13e is additive and non-blocking. - sdk/prompts/workflows/plan-phase.md gets an equivalent post_planning_gaps step for headless mode. - Docs: CONFIGURATION.md, references/planning-config.md, INVENTORY.md, INVENTORY-MANIFEST.json all updated. Tests - tests/post-planning-gaps-2493.test.cjs: 30 test cases covering step insertion position, decisions parser, gap detector behavior (covered/not-covered, false-positive guard, missing-file resilience, malformed-input resilience, gate on/off, deterministic natural sort), and full config integration. - Full suite: 5234 / 5234 pass. Design decisions - Numbered §13e (sub-step), not §14 — §14 already exists (Present Final Status); inserting before it preserves downstream auto-advance step numbers. - Existing §13 gate kept, not replaced — §13 blocks/re-plans on REQ gaps; §13e is the unified post-hoc report. Per spec: "default behavior MUST be backward compatible." - Word-boundary ID matching avoids REQ-1 matching REQ-10 and avoids brittle semantic/substring matching. - Shared decisions.cjs parser so #2492 can reuse the same regex. - Natural-sort keys (REQ-02 before REQ-10) for deterministic output. - Boolean validation in cmdConfigSet rejects non-boolean values matches the precedent set by drift_threshold/drift_action. Closes #2493 * fix(#2493): expose post_planning_gaps in loadConfig() + sync schema example Address CodeRabbit review on PR #2610: - core.cjs loadConfig(): return post_planning_gaps from both the config.json branch and the global ~/.gsd/defaults.json fallback so callers can rely on config.post_planning_gaps regardless of whether the key is present (comment 3127977404, Major). - docs/CONFIGURATION.md: add workflow.post_planning_gaps to the Full Schema JSON example so copy/paste users see the new toggle alongside security_block_on (comment 3127977392, Minor). - tests/post-planning-gaps-2493.test.cjs: regression coverage for loadConfig() — default true when key absent, honors explicit true/false from workflow.post_planning_gaps.
2026-04-25 17:25:23 +02:00 · 2026-04-22 23:03:59 -04:00
parent cc17886c51
commit 1a3d953767
13 changed files with 704 additions and 3 deletions
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -52,7 +52,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new
    "cross_ai_timeout": 300,
    "security_enforcement": true,
    "security_asvs_level": 1,
-    "security_block_on": "high"
+    "security_block_on": "high",
+    "post_planning_gaps": true
  },
  "hooks": {
    "context_warnings": true,
@@ -193,6 +194,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin
 | `workflow.plan_bounce` | boolean | `false` | Run external validation script against generated plans. When enabled, the plan-phase orchestrator pipes each PLAN.md through the script specified by `plan_bounce_script` and blocks on non-zero exit. Added in v1.36 |
 | `workflow.plan_bounce_script` | string | (none) | Path to the external script invoked for plan bounce validation. Receives the PLAN.md path as its first argument. Required when `plan_bounce` is `true`. Added in v1.36 |
 | `workflow.plan_bounce_passes` | number | `2` | Number of sequential bounce passes to run. Each pass feeds the previous pass's output back into the validator. Higher values increase rigor at the cost of latency. Added in v1.36 |
+| `workflow.post_planning_gaps` | boolean | `true` | Unified post-planning gap report (#2493). After all plans are generated and committed, scans REQUIREMENTS.md and CONTEXT.md `<decisions>` against every PLAN.md in the phase directory, then prints one `Source \| Item \| Status` table. Word-boundary matching (REQ-1 vs REQ-10) and natural sort (REQ-02 before REQ-10). Non-blocking — informational report only. Set to `false` to skip Step 13e of plan-phase. |
 | `workflow.plan_chunked` | boolean | `false` | Enable chunked planning mode. When `true` (or when `--chunked` flag is passed to `/gsd-plan-phase`), the orchestrator splits the single long-lived planner Task into a short outline Task followed by N short per-plan Tasks (~3-5 min each). Each plan is committed individually for crash resilience. If a Task hangs and the terminal is force-killed, rerunning with `--chunked` resumes from the last completed plan. Particularly useful on Windows where long-lived Tasks may hang on stdio. Added in v1.38 |
 | `workflow.code_review_command` | string | (none) | Shell command for external code review integration in `/gsd-ship`. Receives changed file paths via stdin. Non-zero exit blocks the ship workflow. Added in v1.36 |
 | `workflow.tdd_mode` | boolean | `false` | Enable TDD pipeline as a first-class execution mode. When `true`, the planner aggressively applies `type: tdd` to eligible tasks (business logic, APIs, validations, algorithms) and the executor enforces RED/GREEN/REFACTOR gate sequence. An end-of-phase collaborative review checkpoint verifies gate compliance. Added in v1.36 |
--- a/docs/INVENTORY-MANIFEST.json
+++ b/docs/INVENTORY-MANIFEST.json
@@ -1,5 +1,5 @@
 {
-  "generated": "2026-04-22",
+  "generated": "2026-04-23",
  "families": {
    "agents": [
      "gsd-advisor-researcher",
@@ -268,9 +268,11 @@
      "config-schema.cjs",
      "config.cjs",
      "core.cjs",
+      "decisions.cjs",
      "docs.cjs",
      "drift.cjs",
      "frontmatter.cjs",
+      "gap-checker.cjs",
      "graphify.cjs",
      "gsd2-import.cjs",
      "init.cjs",
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -359,7 +359,7 @@ The `gsd-planner` agent is decomposed into a core agent plus reference modules t

 ---

-## CLI Modules (28 shipped)
+## CLI Modules (30 shipped)

 Full listing: `get-shit-done/bin/lib/*.cjs`.

@@ -371,9 +371,11 @@ Full listing: `get-shit-done/bin/lib/*.cjs`.
 | `config-schema.cjs` | Single source of truth for `VALID_CONFIG_KEYS` and dynamic key patterns; imported by both the validator and the config-schema-docs parity test |
 | `config.cjs` | `config.json` read/write, section initialization; imports validator from `config-schema.cjs` |
 | `core.cjs` | Error handling, output formatting, shared utilities, runtime fallbacks |
+| `decisions.cjs` | Shared parser for CONTEXT.md `<decisions>` blocks (D-NN entries); used by `gap-checker.cjs` and intended for #2492 plan/verify decision gates |
 | `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection |
 | `drift.cjs` | Post-execute codebase structural drift detector (#2003): classifies file changes into new-dir/barrel/migration/route categories and round-trips `last_mapped_commit` frontmatter |
 | `frontmatter.cjs` | YAML frontmatter CRUD operations |
+| `gap-checker.cjs` | Post-planning gap analysis (#2493): unified REQUIREMENTS.md + CONTEXT.md decisions vs PLAN.md coverage report (`gsd-tools gap-analysis`) |
 | `graphify.cjs` | Knowledge-graph build/query/status/diff for `/gsd-graphify` |
 | `gsd2-import.cjs` | External-plan ingest for `/gsd-from-gsd2` |
 | `init.cjs` | Compound context loading for each workflow type |
--- a/get-shit-done/bin/gsd-tools.cjs
+++ b/get-shit-done/bin/gsd-tools.cjs
@@ -188,6 +188,7 @@ 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');
+const gapChecker = require('./lib/gap-checker.cjs');

 // ─── Arg parsing helpers ──────────────────────────────────────────────────────

@@ -712,6 +713,13 @@ async function runCommand(command, args, cwd, raw, defaultValue) {
      break;
    }

+    case 'gap-analysis': {
+      // Post-planning gap checker (#2493) — unified REQUIREMENTS.md +
+      // CONTEXT.md <decisions> coverage report against PLAN.md files.
+      gapChecker.cmdGapAnalysis(cwd, args.slice(1), raw);
+      break;
+    }
+
    case 'phase': {
      const subcommand = args[1];
      if (subcommand === 'next-decimal') {
--- a/get-shit-done/bin/lib/config-schema.cjs
+++ b/get-shit-done/bin/lib/config-schema.cjs
@@ -34,6 +34,7 @@ const VALID_CONFIG_KEYS = new Set([
  'workflow.plan_bounce_script',
  'workflow.plan_bounce_passes',
  'workflow.plan_chunked',
+  'workflow.post_planning_gaps',
  'workflow.security_enforcement',
  'workflow.security_asvs_level',
  'workflow.security_block_on',
--- a/get-shit-done/bin/lib/config.cjs
+++ b/get-shit-done/bin/lib/config.cjs
@@ -120,6 +120,7 @@ function buildNewProjectConfig(userChoices) {
      plan_bounce_script: null,
      plan_bounce_passes: 2,
      auto_prune_state: false,
+      post_planning_gaps: CONFIG_DEFAULTS.post_planning_gaps,
      security_enforcement: CONFIG_DEFAULTS.security_enforcement,
      security_asvs_level: CONFIG_DEFAULTS.security_asvs_level,
      security_block_on: CONFIG_DEFAULTS.security_block_on,
@@ -345,6 +346,13 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
    }
  }

+  // Post-planning gap checker (#2493)
+  if (keyPath === 'workflow.post_planning_gaps') {
+    if (typeof parsedValue !== 'boolean') {
+      error(`Invalid workflow.post_planning_gaps '${value}'. Must be a boolean (true or false).`);
+    }
+  }
+
  const setConfigValueResult = setConfigValue(cwd, keyPath, parsedValue);

  // Mask secrets in both JSON and text output. The plaintext is written
--- a/get-shit-done/bin/lib/core.cjs
+++ b/get-shit-done/bin/lib/core.cjs
@@ -266,6 +266,7 @@ const CONFIG_DEFAULTS = {
  security_enforcement: true, // workflow.security_enforcement — threat-model-anchored security verification via /gsd:secure-phase
  security_asvs_level: 1, // workflow.security_asvs_level — OWASP ASVS verification level (1=opportunistic, 2=standard, 3=comprehensive)
  security_block_on: 'high', // workflow.security_block_on — minimum severity that blocks phase advancement ('high' | 'medium' | 'low')
+  post_planning_gaps: true, // workflow.post_planning_gaps — unified post-planning gap report (#2493): scan REQUIREMENTS.md + CONTEXT.md decisions vs all PLAN.md files
 };

 function loadConfig(cwd) {
@@ -381,6 +382,7 @@ function loadConfig(cwd) {
      plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker,
      verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
      nyquist_validation: get('nyquist_validation', { section: 'workflow', field: 'nyquist_validation' }) ?? defaults.nyquist_validation,
+      post_planning_gaps: get('post_planning_gaps', { section: 'workflow', field: 'post_planning_gaps' }) ?? defaults.post_planning_gaps,
      parallelization,
      brave_search: get('brave_search') ?? defaults.brave_search,
      firecrawl: get('firecrawl') ?? defaults.firecrawl,
@@ -434,6 +436,9 @@ function loadConfig(cwd) {
        plan_checker: globalDefaults.plan_checker ?? defaults.plan_checker,
        verifier: globalDefaults.verifier ?? defaults.verifier,
        nyquist_validation: globalDefaults.nyquist_validation ?? defaults.nyquist_validation,
+        post_planning_gaps: globalDefaults.post_planning_gaps
+          ?? globalDefaults.workflow?.post_planning_gaps
+          ?? defaults.post_planning_gaps,
        parallelization: globalDefaults.parallelization ?? defaults.parallelization,
        text_mode: globalDefaults.text_mode ?? defaults.text_mode,
        resolve_model_ids: globalDefaults.resolve_model_ids ?? defaults.resolve_model_ids,
--- a/get-shit-done/bin/lib/decisions.cjs
+++ b/get-shit-done/bin/lib/decisions.cjs
@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Shared parser for CONTEXT.md `<decisions>` blocks.
+ *
+ * Used by:
+ *   - gap-checker.cjs (#2493 post-planning gap analysis)
+ *   - intended for #2492 (plan-phase decision gate, verify-phase decision validator)
+ *
+ * Format produced by discuss-phase.md:
+ *
+ *   <decisions>
+ *   ## Implementation Decisions
+ *
+ *   ### Category
+ *   - **D-01:** Decision text
+ *   - **D-02:** Another decision
+ *   </decisions>
+ *
+ * D-IDs outside the <decisions> block are ignored. Missing block returns [].
+ */
+
+/**
+ * Parse the <decisions> section of a CONTEXT.md string.
+ *
+ * @param {string|null|undefined} contextMd - File contents, may be empty/missing.
+ * @returns {Array<{id: string, text: string}>}
+ */
+function parseDecisions(contextMd) {
+  if (!contextMd || typeof contextMd !== 'string') return [];
+  const blockMatch = contextMd.match(/<decisions>([\s\S]*?)<\/decisions>/);
+  if (!blockMatch) return [];
+  const block = blockMatch[1];
+
+  const decisionRe = /^\s*-\s*\*\*(D-[A-Za-z0-9_-]+):\*\*\s*(.+?)\s*$/gm;
+  const out = [];
+  const seen = new Set();
+  let m;
+  while ((m = decisionRe.exec(block)) !== null) {
+    const id = m[1];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, text: m[2] });
+  }
+  return out;
+}
+
+module.exports = { parseDecisions };
--- a/get-shit-done/bin/lib/gap-checker.cjs
+++ b/get-shit-done/bin/lib/gap-checker.cjs
@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Post-planning gap analysis (#2493).
+ *
+ * Reads REQUIREMENTS.md (planning-root) and CONTEXT.md (per-phase) and compares
+ * each REQ-ID and D-ID against the concatenated text of all PLAN.md files in
+ * the phase directory. Emits a unified `Source | Item | Status` report.
+ *
+ * Gated on workflow.post_planning_gaps (default true). When false, returns
+ * { enabled: false } and does not scan.
+ *
+ * Coverage detection uses word-boundary regex matching to avoid false positives
+ * (REQ-1 must not match REQ-10).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { planningPaths, planningDir, escapeRegex, output, error } = require('./core.cjs');
+const { parseDecisions } = require('./decisions.cjs');
+
+/**
+ * Parse REQ-IDs from REQUIREMENTS.md content.
+ *
+ * Supports both checkbox (`- [ ] **REQ-NN** ...`) and traceability table
+ * (`| REQ-NN | ... |`) formats.
+ */
+function parseRequirements(reqMd) {
+  if (!reqMd || typeof reqMd !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+
+  const checkboxRe = /^\s*-\s*\[[x ]\]\s*\*\*(REQ-[A-Za-z0-9_-]+)\*\*\s*(.*)$/gm;
+  let cm = checkboxRe.exec(reqMd);
+  while (cm !== null) {
+    const id = cm[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push({ id, text: (cm[2] || '').trim() });
+    }
+    cm = checkboxRe.exec(reqMd);
+  }
+
+  const tableRe = /\|\s*(REQ-[A-Za-z0-9_-]+)\s*\|/g;
+  let tm = tableRe.exec(reqMd);
+  while (tm !== null) {
+    const id = tm[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push({ id, text: '' });
+    }
+    tm = tableRe.exec(reqMd);
+  }
+
+  return out;
+}
+
+function detectCoverage(items, planText) {
+  return items.map(it => {
+    const re = new RegExp('\\b' + escapeRegex(it.id) + '\\b');
+    return {
+      source: it.source,
+      item: it.id,
+      status: re.test(planText) ? 'Covered' : 'Not covered',
+    };
+  });
+}
+
+function naturalKey(s) {
+  return String(s).replace(/(\d+)/g, (_, n) => n.padStart(8, '0'));
+}
+
+function sortRows(rows) {
+  const sourceOrder = { 'REQUIREMENTS.md': 0, 'CONTEXT.md': 1 };
+  return rows.slice().sort((a, b) => {
+    const so = (sourceOrder[a.source] ?? 99) - (sourceOrder[b.source] ?? 99);
+    if (so !== 0) return so;
+    return naturalKey(a.item).localeCompare(naturalKey(b.item));
+  });
+}
+
+function formatGapTable(rows) {
+  if (rows.length === 0) {
+    return '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n';
+  }
+  const header = '| Source | Item | Status |\n|--------|------|--------|';
+  const body = rows.map(r => {
+    const tick = r.status === 'Covered' ? '\u2713 Covered' : '\u2717 Not covered';
+    return `| ${r.source} | ${r.item} | ${tick} |`;
+  }).join('\n');
+  return `## Post-Planning Gap Analysis\n\n${header}\n${body}\n`;
+}
+
+function readGate(cwd) {
+  const cfgPath = path.join(planningDir(cwd), 'config.json');
+  try {
+    const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    if (raw && raw.workflow && typeof raw.workflow.post_planning_gaps === 'boolean') {
+      return raw.workflow.post_planning_gaps;
+    }
+  } catch { /* fall through */ }
+  return true;
+}
+
+function runGapAnalysis(cwd, phaseDir) {
+  if (!readGate(cwd)) {
+    return {
+      enabled: false,
+      rows: [],
+      table: '',
+      summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
+      counts: { total: 0, covered: 0, uncovered: 0 },
+    };
+  }
+
+  const absPhaseDir = path.isAbsolute(phaseDir) ? phaseDir : path.join(cwd, phaseDir);
+
+  const reqPath = planningPaths(cwd).requirements;
+  const reqMd = fs.existsSync(reqPath) ? fs.readFileSync(reqPath, 'utf-8') : '';
+  const reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
+
+  const ctxPath = path.join(absPhaseDir, 'CONTEXT.md');
+  const ctxMd = fs.existsSync(ctxPath) ? fs.readFileSync(ctxPath, 'utf-8') : '';
+  const dItems = parseDecisions(ctxMd).map(d => ({ ...d, source: 'CONTEXT.md' }));
+
+  const items = [...reqItems, ...dItems];
+
+  let planText = '';
+  try {
+    if (fs.existsSync(absPhaseDir)) {
+      const files = fs.readdirSync(absPhaseDir).filter(f => /-PLAN\.md$/.test(f));
+      planText = files.map(f => {
+        try { return fs.readFileSync(path.join(absPhaseDir, f), 'utf-8'); }
+        catch { return ''; }
+      }).join('\n');
+    }
+  } catch { /* unreadable */ }
+
+  if (items.length === 0) {
+    return {
+      enabled: true,
+      rows: [],
+      table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
+      summary: 'no requirements or decisions to check',
+      counts: { total: 0, covered: 0, uncovered: 0 },
+    };
+  }
+
+  const rows = sortRows(detectCoverage(items, planText));
+  const uncovered = rows.filter(r => r.status === 'Not covered').length;
+  const covered = rows.length - uncovered;
+
+  const summary = uncovered === 0
+    ? `\u2713 All ${rows.length} items covered by plans`
+    : `\u26A0 ${uncovered} of ${rows.length} items not covered by any plan`;
+
+  return {
+    enabled: true,
+    rows,
+    table: formatGapTable(rows) + '\n' + summary + '\n',
+    summary,
+    counts: { total: rows.length, covered, uncovered },
+  };
+}
+
+function cmdGapAnalysis(cwd, args, raw) {
+  const idx = args.indexOf('--phase-dir');
+  if (idx === -1 || !args[idx + 1]) {
+    error('Usage: gap-analysis --phase-dir <path-to-phase-directory>');
+  }
+  const phaseDir = args[idx + 1];
+  const result = runGapAnalysis(cwd, phaseDir);
+  output(result, raw, result.table || result.summary);
+}
+
+module.exports = {
+  parseRequirements,
+  detectCoverage,
+  formatGapTable,
+  sortRows,
+  runGapAnalysis,
+  cmdGapAnalysis,
+};
--- a/get-shit-done/references/planning-config.md
+++ b/get-shit-done/references/planning-config.md
@@ -268,6 +268,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/gsd:secure-phase`. When `false`, security checks are skipped entirely |
 | `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive |
 | `workflow.security_block_on` | string | `"high"` | `"high"`, `"medium"`, `"low"` | Minimum severity that blocks phase advancement |
+| `workflow.post_planning_gaps` | boolean | `true` | `true`, `false` | Post-planning gap report (#2493). After plans are generated, scans REQUIREMENTS.md and CONTEXT.md `<decisions>` against all PLAN.md files and emits a unified `Source \| Item \| Status` table. Non-blocking. Set to `false` to skip Step 13e of plan-phase. _Alias:_ `post_planning_gaps` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.post_planning_gaps` is the canonical namespaced form. |

 ### Git Fields

--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -1344,6 +1344,53 @@ gsd-sdk query commit "docs(${PADDED_PHASE}): create phase plan" --files "${PHASE

 This commits all PLAN.md files for the phase plus the updated STATE.md and ROADMAP.md to version-control the planning artifacts. Skip this step if `commit_docs` is false.

+## 13e. Post-Planning Gap Analysis
+
+After all plans are generated, committed, and the Requirements Coverage Gate (§13)
+has run, emit a single unified gap report covering both REQUIREMENTS.md and the
+CONTEXT.md `<decisions>` section. This is a **proactive, post-hoc report** — it
+does not block phase advancement and does not re-plan. It exists so that any
+requirement or decision that slipped through the per-plan checks is surfaced in
+one place before execution begins.
+
+**Skip if:** `workflow.post_planning_gaps` is `false`. Default is `true`.
+
+```bash
+POST_PLANNING_GAPS=$(gsd-sdk query config-get workflow.post_planning_gaps --default true 2>/dev/null || echo true)
+if [ "$POST_PLANNING_GAPS" = "true" ]; then
+  gsd-tools gap-analysis --phase-dir "${PHASE_DIR}"
+fi
+```
+
+(`gsd-tools gap-analysis` reads `.planning/REQUIREMENTS.md`, `${PHASE_DIR}/CONTEXT.md`,
+and `${PHASE_DIR}/*-PLAN.md`, then prints a markdown table with one row per
+REQ-ID and D-ID. Word-boundary matching prevents `REQ-1` from being mistaken for
+`REQ-10`.)
+
+**Output format (deterministic; sorted REQUIREMENTS.md → CONTEXT.md, then natural
+sort within source):**
+
+```
+## Post-Planning Gap Analysis
+
+| Source | Item | Status |
+|--------|------|--------|
+| REQUIREMENTS.md | REQ-01 | ✓ Covered |
+| REQUIREMENTS.md | REQ-02 | ✗ Not covered |
+| CONTEXT.md | D-01 | ✓ Covered |
+| CONTEXT.md | D-02 | ✗ Not covered |
+
+⚠ N items not covered by any plan
+```
+
+**Skip-gracefully behavior:**
+- REQUIREMENTS.md missing → CONTEXT-only report.
+- CONTEXT.md missing → REQUIREMENTS-only report.
+- Both missing or `<decisions>` block missing → "No requirements or decisions to check" line, no error.
+
+This step is non-blocking. If items are reported as not covered, the user may
+re-run `/gsd:plan-phase --gaps` to add plans, or proceed to execute-phase as-is.
+
 ## 14. Present Final Status

 Route to `<offer_next>` OR `auto_advance` depending on flags/config.
--- a/sdk/prompts/workflows/plan-phase.md
+++ b/sdk/prompts/workflows/plan-phase.md
@@ -73,6 +73,14 @@ After plans pass the checker (or checker is skipped), verify all phase requireme
 3. If gaps found: log as warning, continue (headless mode does not block for coverage gaps)
 </step>

+<step name="post_planning_gaps">
+Unified post-planning gap report (#2493). Gated on `workflow.post_planning_gaps`
+(default true). When enabled, scan REQUIREMENTS.md and CONTEXT.md `<decisions>`
+against all generated PLAN.md files, then emit one `Source | Item | Status` table.
+Skip-gracefully on missing sources. Non-blocking — headless mode reports gaps
+via the event stream and continues.
+</step>
+
 </process>

 <success_criteria>
--- a/tests/post-planning-gaps-2493.test.cjs
+++ b/tests/post-planning-gaps-2493.test.cjs
@@ -0,0 +1,386 @@
+/**
+ * Issue #2493: Add unified post-planning gap checker for requirements and context
+ *
+ * Verifies:
+ *   1. Step 13e (Post-Planning Gap Analysis) is inserted into plan-phase.md after
+ *      Step 13d and before Step 14, gated on workflow.post_planning_gaps.
+ *   2. Headless plan-phase variant has an equivalent post_planning_gaps step.
+ *   3. The decision parser extracts D-NN entries from CONTEXT.md <decisions> blocks.
+ *   4. The gap detector identifies covered vs not-covered items, avoiding
+ *      false-positive ID collisions (REQ-1 vs REQ-10).
+ *   5. The gap-analysis CLI:
+ *        - Returns enabled:false when workflow.post_planning_gaps is false.
+ *        - Returns rows + table when enabled, sorting deterministically.
+ *        - Skips gracefully when REQUIREMENTS.md or CONTEXT.md is missing/malformed.
+ *   6. config-set workflow.post_planning_gaps:
+ *        - Accepts true/false.
+ *        - Rejects non-boolean values.
+ *   7. config-ensure-section materializes workflow.post_planning_gaps default true.
+ *   8. config-schema lists workflow.post_planning_gaps in VALID_CONFIG_KEYS and
+ *      core CONFIG_DEFAULTS includes it.
+ *   9. The existing Requirements Coverage Gate (Step 13) is still present
+ *      (no regression — §13e adds, does not replace).
+ */
+
+const { describe, test, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const PLAN_PHASE_PATH = path.join(REPO_ROOT, 'get-shit-done', 'workflows', 'plan-phase.md');
+const PLAN_PHASE_SDK_PATH = path.join(REPO_ROOT, 'sdk', 'prompts', 'workflows', 'plan-phase.md');
+
+// ─── Workflow file structure ──────────────────────────────────────────────────
+
+describe('plan-phase.md Step 13e insertion (#2493)', () => {
+  test('plan-phase.md exists', () => {
+    assert.ok(fs.existsSync(PLAN_PHASE_PATH));
+  });
+
+  test('Step 13e (Post-Planning Gap Analysis) heading is present', () => {
+    const content = fs.readFileSync(PLAN_PHASE_PATH, 'utf-8');
+    assert.match(content, /## 13e\.\s*Post-Planning Gap Analysis/);
+  });
+
+  test('Step 13e appears between Step 13d and Step 14', () => {
+    const content = fs.readFileSync(PLAN_PHASE_PATH, 'utf-8');
+    const i13d = content.indexOf('## 13d.');
+    const i13e = content.indexOf('## 13e.');
+    const i14 = content.indexOf('## 14.');
+    assert.ok(i13d !== -1, '## 13d. must exist');
+    assert.ok(i13e !== -1, '## 13e. must exist');
+    assert.ok(i14 !== -1, '## 14. must exist');
+    assert.ok(i13d < i13e && i13e < i14,
+      `Step 13e must be between 13d and 14 (got 13d=${i13d}, 13e=${i13e}, 14=${i14})`);
+  });
+
+  test('Step 13e references workflow.post_planning_gaps gate', () => {
+    const content = fs.readFileSync(PLAN_PHASE_PATH, 'utf-8');
+    const i13e = content.indexOf('## 13e.');
+    const i14 = content.indexOf('## 14.');
+    const stepBody = content.slice(i13e, i14);
+    assert.match(stepBody, /workflow\.post_planning_gaps/);
+  });
+
+  test('Step 13e invokes gap-analysis via gsd-tools', () => {
+    const content = fs.readFileSync(PLAN_PHASE_PATH, 'utf-8');
+    const i13e = content.indexOf('## 13e.');
+    const i14 = content.indexOf('## 14.');
+    const stepBody = content.slice(i13e, i14);
+    assert.match(stepBody, /gap-analysis/);
+  });
+
+  test('Existing Requirements Coverage Gate (§13) is still present (no regression)', () => {
+    const content = fs.readFileSync(PLAN_PHASE_PATH, 'utf-8');
+    assert.match(content, /## 13\.\s*Requirements Coverage Gate/);
+  });
+
+  test('Headless plan-phase variant has post_planning_gaps step', () => {
+    const content = fs.readFileSync(PLAN_PHASE_SDK_PATH, 'utf-8');
+    assert.match(content, /post_planning_gaps/);
+  });
+});
+
+// ─── Decisions parser ────────────────────────────────────────────────────────
+
+describe('decisions.cjs parser (shared with #2492)', () => {
+  const { parseDecisions } = require('../get-shit-done/bin/lib/decisions.cjs');
+
+  test('extracts D-NN entries from a <decisions> block', () => {
+    const md = `
+<decisions>
+## Implementation Decisions
+
+### Auth
+- **D-01:** Use OAuth 2.0 with PKCE
+- **D-02:** Session storage in Redis
+
+### Storage
+- **D-03:** Postgres 15 with pgvector
+</decisions>
+`;
+    const ds = parseDecisions(md);
+    assert.deepStrictEqual(ds.map(d => d.id), ['D-01', 'D-02', 'D-03']);
+    assert.strictEqual(ds[0].text, 'Use OAuth 2.0 with PKCE');
+  });
+
+  test('returns [] when no <decisions> block is present', () => {
+    assert.deepStrictEqual(parseDecisions('# Just a header\nno decisions here'), []);
+  });
+
+  test('returns [] for empty / null / undefined input', () => {
+    assert.deepStrictEqual(parseDecisions(''), []);
+    assert.deepStrictEqual(parseDecisions(null), []);
+    assert.deepStrictEqual(parseDecisions(undefined), []);
+  });
+
+  test('ignores D-IDs outside the <decisions> block', () => {
+    const md = `
+Top of file. - **D-99:** Not a real decision (outside block).
+<decisions>
+- **D-01:** Real decision
+</decisions>
+After the block. - **D-77:** Also not real.
+`;
+    const ds = parseDecisions(md);
+    assert.deepStrictEqual(ds.map(d => d.id), ['D-01']);
+  });
+});
+
+// ─── Gap analysis CLI ────────────────────────────────────────────────────────
+
+describe('gap-analysis CLI (#2493)', () => {
+  let tmpDir;
+  let phaseDir;
+
+  function writeRequirements(ids) {
+    const lines = ids.map((id, i) => `- [ ] **${id}** Requirement ${i + 1} description`);
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'REQUIREMENTS.md'),
+      `# Requirements\n\n${lines.join('\n')}\n`);
+  }
+
+  function writeContext(decisions) {
+    const dLines = decisions.map(d => `- **${d.id}:** ${d.text}`).join('\n');
+    fs.writeFileSync(path.join(phaseDir, 'CONTEXT.md'),
+      `# Phase Context\n\n<decisions>\n## Implementation Decisions\n\n${dLines}\n</decisions>\n`);
+  }
+
+  function writePlan(name, body) {
+    fs.writeFileSync(path.join(phaseDir, `${name}-PLAN.md`), body);
+  }
+
+  function ensureConfig() {
+    const r = runGsdTools('config-ensure-section', tmpDir);
+    assert.ok(r.success, `config-ensure-section failed: ${r.error}`);
+  }
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+    phaseDir = path.join(tmpDir, '.planning', 'phases', '01-test');
+    fs.mkdirSync(phaseDir, { recursive: true });
+    ensureConfig();
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('marks REQ-01 as covered when a plan body mentions REQ-01', () => {
+    writeRequirements(['REQ-01']);
+    writePlan('01', '# Plan 1\n\nImplements REQ-01.\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success, `gap-analysis failed: ${r.error}`);
+    const out = JSON.parse(r.output);
+    const row = out.rows.find(x => x.item === 'REQ-01');
+    assert.ok(row, 'REQ-01 row missing');
+    assert.strictEqual(row.status, 'Covered');
+  });
+
+  test('marks REQ-99 as not covered when no plan mentions it', () => {
+    writeRequirements(['REQ-99']);
+    writePlan('01', '# Plan 1\n\nImplements something unrelated.\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    const row = out.rows.find(x => x.item === 'REQ-99');
+    assert.strictEqual(row.status, 'Not covered');
+  });
+
+  test('marks D-01 covered when plan mentions D-01', () => {
+    writeContext([{ id: 'D-01', text: 'Use OAuth 2.0' }]);
+    writePlan('01', '# Plan\n\nImplements D-01 (OAuth).\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    const row = out.rows.find(x => x.item === 'D-01');
+    assert.ok(row);
+    assert.strictEqual(row.source, 'CONTEXT.md');
+    assert.strictEqual(row.status, 'Covered');
+  });
+
+  test('marks D-99 not covered when no plan mentions it', () => {
+    writeContext([{ id: 'D-99', text: 'Bit offsets in +OFFSET:BIT format' }]);
+    writePlan('01', '# Plan\n\nUnrelated work.\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    const row = out.rows.find(x => x.item === 'D-99');
+    assert.strictEqual(row.status, 'Not covered');
+  });
+
+  test('REQ-1 in plan does not falsely mark REQ-10 as covered (word-boundary)', () => {
+    writeRequirements(['REQ-1', 'REQ-10']);
+    writePlan('01', '# Plan\n\nMentions REQ-1 only.\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    const row1 = out.rows.find(x => x.item === 'REQ-1');
+    const row10 = out.rows.find(x => x.item === 'REQ-10');
+    assert.strictEqual(row1.status, 'Covered');
+    assert.strictEqual(row10.status, 'Not covered',
+      'REQ-10 must not be marked covered by a substring match against REQ-1');
+  });
+
+  test('table output contains documented columns', () => {
+    writeRequirements(['REQ-01']);
+    writePlan('01', '# Plan\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    assert.match(out.table, /\| Source \| Item \| Status \|/);
+    assert.match(out.table, /\|--------\|------\|--------\|/);
+    assert.match(out.table, /## Post-Planning Gap Analysis/);
+  });
+
+  test('rows sort REQ-02 before REQ-10 (natural sort, deterministic)', () => {
+    writeRequirements(['REQ-10', 'REQ-02', 'REQ-01']);
+    writePlan('01', '# Plan\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    const reqRows = out.rows.filter(x => x.source === 'REQUIREMENTS.md').map(x => x.item);
+    assert.deepStrictEqual(reqRows, ['REQ-01', 'REQ-02', 'REQ-10']);
+  });
+
+  test('REQUIREMENTS.md missing → CONTEXT-only run still works', () => {
+    writeContext([{ id: 'D-01', text: 'foo' }]);
+    writePlan('01', '# Plan mentioning D-01\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success, r.error);
+    const out = JSON.parse(r.output);
+    assert.strictEqual(out.rows.length, 1);
+    assert.strictEqual(out.rows[0].source, 'CONTEXT.md');
+  });
+
+  test('CONTEXT.md missing → REQ-only run still works', () => {
+    writeRequirements(['REQ-01']);
+    writePlan('01', '# Plan REQ-01\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success, r.error);
+    const out = JSON.parse(r.output);
+    assert.strictEqual(out.rows.length, 1);
+    assert.strictEqual(out.rows[0].source, 'REQUIREMENTS.md');
+  });
+
+  test('both REQUIREMENTS.md and CONTEXT.md missing → no error, empty rows', () => {
+    writePlan('01', '# Plan\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success, r.error);
+    const out = JSON.parse(r.output);
+    assert.deepStrictEqual(out.rows, []);
+    assert.match(out.summary, /no requirements or decisions/i);
+  });
+
+  test('malformed CONTEXT.md (no <decisions> block) treated as zero decisions', () => {
+    fs.writeFileSync(path.join(phaseDir, 'CONTEXT.md'), '# Just plain prose, no decisions block.\n');
+    writeRequirements(['REQ-01']);
+    writePlan('01', '# Plan REQ-01\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success, r.error);
+    const out = JSON.parse(r.output);
+    assert.strictEqual(out.rows.length, 1);
+    assert.strictEqual(out.rows[0].source, 'REQUIREMENTS.md');
+  });
+
+  test('gate flag false → enabled:false, no scanning', () => {
+    runGsdTools(['config-set', 'workflow.post_planning_gaps', 'false'], tmpDir);
+    writeRequirements(['REQ-01']);
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    assert.strictEqual(out.enabled, false);
+    assert.deepStrictEqual(out.rows, []);
+  });
+
+  test('gate flag true (default) → enabled:true, rows present', () => {
+    writeRequirements(['REQ-01']);
+    writePlan('01', '# Plan REQ-01\n');
+    const r = runGsdTools(['gap-analysis', '--phase-dir', phaseDir], tmpDir);
+    assert.ok(r.success);
+    const out = JSON.parse(r.output);
+    assert.strictEqual(out.enabled, true);
+    assert.ok(out.rows.length >= 1);
+  });
+});
+
+// ─── Config integration ──────────────────────────────────────────────────────
+
+describe('workflow.post_planning_gaps config (#2493)', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = createTempProject(); });
+  afterEach(() => { cleanup(tmpDir); });
+
+  test('VALID_CONFIG_KEYS contains workflow.post_planning_gaps', () => {
+    const { VALID_CONFIG_KEYS } = require('../get-shit-done/bin/lib/config-schema.cjs');
+    assert.ok(VALID_CONFIG_KEYS.has('workflow.post_planning_gaps'));
+  });
+
+  test('CONFIG_DEFAULTS contains post_planning_gaps default true', () => {
+    // CONFIG_DEFAULTS is exported from core.cjs
+    const { CONFIG_DEFAULTS } = require('../get-shit-done/bin/lib/core.cjs');
+    assert.strictEqual(CONFIG_DEFAULTS.post_planning_gaps, true);
+  });
+
+  test('config-ensure-section materializes workflow.post_planning_gaps:true', () => {
+    runGsdTools('config-ensure-section', tmpDir);
+    const config = JSON.parse(fs.readFileSync(path.join(tmpDir, '.planning', 'config.json'), 'utf-8'));
+    assert.strictEqual(config.workflow.post_planning_gaps, true);
+  });
+
+  test('config-set workflow.post_planning_gaps true → persisted as boolean', () => {
+    runGsdTools('config-ensure-section', tmpDir);
+    const r = runGsdTools(['config-set', 'workflow.post_planning_gaps', 'true'], tmpDir);
+    assert.ok(r.success, r.error);
+    const config = JSON.parse(fs.readFileSync(path.join(tmpDir, '.planning', 'config.json'), 'utf-8'));
+    assert.strictEqual(config.workflow.post_planning_gaps, true);
+  });
+
+  test('config-set workflow.post_planning_gaps false → persisted as boolean', () => {
+    runGsdTools('config-ensure-section', tmpDir);
+    const r = runGsdTools(['config-set', 'workflow.post_planning_gaps', 'false'], tmpDir);
+    assert.ok(r.success, r.error);
+    const config = JSON.parse(fs.readFileSync(path.join(tmpDir, '.planning', 'config.json'), 'utf-8'));
+    assert.strictEqual(config.workflow.post_planning_gaps, false);
+  });
+
+  test('config-set workflow.post_planning_gaps yes → rejected', () => {
+    runGsdTools('config-ensure-section', tmpDir);
+    const r = runGsdTools(['config-set', 'workflow.post_planning_gaps', 'yes'], tmpDir);
+    assert.ok(!r.success, 'non-boolean value must be rejected');
+    assert.match(r.error || r.output, /boolean|true|false/i);
+  });
+
+  // CodeRabbit PR #2610 (comment 3127977404): loadConfig() must surface post_planning_gaps
+  // in its return so callers can read config.post_planning_gaps regardless of whether
+  // config.json exists, has the workflow section, or sets the flat key.
+  test('loadConfig() returns post_planning_gaps default true when key absent', () => {
+    const { loadConfig } = require('../get-shit-done/bin/lib/core.cjs');
+    runGsdTools('config-ensure-section', tmpDir);
+    // Remove the key to simulate older configs that pre-date the toggle
+    const cfgPath = path.join(tmpDir, '.planning', 'config.json');
+    const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    delete raw.workflow.post_planning_gaps;
+    fs.writeFileSync(cfgPath, JSON.stringify(raw, null, 2));
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.post_planning_gaps, true);
+  });
+
+  test('loadConfig() returns post_planning_gaps:false when workflow.post_planning_gaps=false', () => {
+    const { loadConfig } = require('../get-shit-done/bin/lib/core.cjs');
+    runGsdTools('config-ensure-section', tmpDir);
+    runGsdTools(['config-set', 'workflow.post_planning_gaps', 'false'], tmpDir);
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.post_planning_gaps, false);
+  });
+
+  test('loadConfig() returns post_planning_gaps:true when workflow.post_planning_gaps=true', () => {
+    const { loadConfig } = require('../get-shit-done/bin/lib/core.cjs');
+    runGsdTools('config-ensure-section', tmpDir);
+    runGsdTools(['config-set', 'workflow.post_planning_gaps', 'true'], tmpDir);
+    const config = loadConfig(tmpDir);
+    assert.strictEqual(config.post_planning_gaps, true);
+  });
+});