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.
This commit is contained in:
Tom Boucher
2026-04-22 23:03:59 -04:00
committed by GitHub
parent cc17886c51
commit 1a3d953767
13 changed files with 704 additions and 3 deletions

View File

@@ -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') {

View File

@@ -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',

View File

@@ -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

View File

@@ -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,

View File

@@ -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 };

View File

@@ -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,
};

View File

@@ -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

View File

@@ -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.