7bb366e836
* test(#4130): failing-first regressions for --context flag + parseDecisions hardening Block A (flag): check decision-coverage-plan --context <path> must route identically to the positional form; flag wins over positional context; valueless --context falls through to the #2770 fail-closed caller error; verify keeps its positional surface (flag is plan-only). RED on base: the flag token lands in the args[2] phase slot (false uncovered) or the args[3] context slot (silent CONTEXT.md-missing skip). Block B (hardening): regex-lattice asserts pin the atomic-ID wrapper (?=(X))\1 and the em-dash first-separator narrowing [^*—–]*[—–] plus the no-adjacent-overlap property; a differential property compares the module against a frozen copy of the pre-hardening grammars (reference validated against the base build: 60k generated lines, 0 mismatches); 40k cliff shapes assert correct outcomes with no wall-time asserts (repo rule). A12: partitionPredicateArgs keeps one parser behind parsePredicateFlags. * fix(#4130): --context flag for check decision-coverage-plan + quadratic-backtracking hardening in parseDecisions (A) check decision-coverage-plan --context <path> — sibling convention (check predicate, #2008): --flag value pairs parsed by the new shared partitionPredicateArgs (parsePredicateFlags reimplemented as its flags half — one parser, cannot diverge), the flag winning over a same-purpose positional, positionals kept (no sibling deprecates them; the plan-phase workflow caller passes positionals), valueless --context falls through to the #2770 fail-closed caller error. Repair of the routing accident where --context landed in the args[2] phase slot (false uncovered) or the literal token in the args[3] context slot (silent green skip). (B) parseDecisions regex seam hardened, byte-identical on all legal inputs: the three bullet grammars consume the ID atomically via the (?=(X))\1 lookahead emulation (kills the tail/[^:*]* O(n^2) re-split, ~1.1s @ 40k), and the em-dash first separator narrows [^*]*[—–] to [^*—–]*[—–] (kills the dash-position O(n^2) retry, ~1.7s @ 40k). Group indices unchanged (handlers untouched). Pinned by regex-lattice tests, a differential fast-check property vs the frozen pre-hardening grammars, and 40k cliff/legal-shape outcome tests (no wall-time asserts per repo rule — no deterministic engine step counter exists in Node). * docs+test(#4130): document --context invocation; harden lattice test tooling - docs/CONFIGURATION.md Decision Coverage Gates: new 'Invoking the plan gate directly' block documenting both the positional and --context forms, flag precedence, and the valueless-flag fail-closed semantics (same place the gate's behavior is documented; sibling check predicate documents its flags the same way). - Two changeset fragments per the maintainer brief (Added: flag; Fixed: hardening), PR numbers to be backfilled. - tests/decisions.test.cjs review fixes: readRegExpTemplate template escaping (bare ')' SyntaxError), range-aware lattice checker with backreference skip and template unescape, honest A1 contract, lint escape warning. * fix(#4130): valueless --context fails closed per #2770; A8 isolates flag-vs-positional context Suite-caught fixes from the first verify run: - cmdDecisionCoveragePlan now refuses a flag-shaped token as the positional context path: a bare valueless --context stays a positional (sibling parser semantics, unchanged) but reading it as a PATH would turn a caller mistake into a silent 'CONTEXT.md missing' green skip — exactly what #2770's fail-closed law forbids. Now falls through to the missing-context-argument error, as documented. - A8 test compares decoy-positional+flag against flag-with-phase (phase held constant) so the row isolates WHICH context was read; the old form compared against a no-phase invocation that could never match. * chore(#4130): backfill PR number in changeset fragments (PR #4374) --------- Co-authored-by: sim <sim@local>
1905 lines
79 KiB
TypeScript
1905 lines
79 KiB
TypeScript
/**
|
|
* Check subcommand router — auto-mode, decision-coverage-plan, decision-coverage-verify.
|
|
*
|
|
* ADR-457 build-at-publish: the hand-written bin/lib/check-command-router.cjs collapsed
|
|
* to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
|
|
* from the prior hand-written .cjs; only strict types are added.
|
|
*/
|
|
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { execFileSync } from 'node:child_process';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import io = require('./io.cjs');
|
|
const { output, error, ERROR_REASON } = io;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import planningWorkspaceMod = require('./planning-workspace.cjs');
|
|
const { planningDir } = planningWorkspaceMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import phaseLocatorMod = require('./phase-locator.cjs');
|
|
const { findPhaseInternal } = phaseLocatorMod;
|
|
import { extractDecisions } from './decisions.cjs';
|
|
import type { Decision } from './decisions.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import frontmatterMod = require('./frontmatter.cjs');
|
|
const { extractFrontmatter } = frontmatterMod;
|
|
import { stripFencedCode, collectSections } from './markdown-sectionizer.cjs';
|
|
import { validatePath } from './security.cjs';
|
|
import { checkUiPresence } from './ui-safety-gate.cjs';
|
|
import { hasStaticFrontendEvidence } from './ui-frontend-evidence.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import verifyModule = require('./verify.cjs');
|
|
const { cmdVerifySchemaDrift, cmdVerifyCodebaseDrift, cmdVerifyContextDrift } = verifyModule;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import roadmapModule = require('./roadmap.cjs');
|
|
const { getRoadmapPhaseWithFallback } = roadmapModule;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import gapCheckerModule = require('./gap-checker.cjs');
|
|
const { runGapAnalysis } = gapCheckerModule;
|
|
import { routeProhibitionEnforcement } from './prohibition-enforcement.cjs';
|
|
import { classifyRedEvidence, buildRedEvidenceRecord } from './tdd-red-evidence.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import gatePredicateEval = require('./gate-predicate-evaluator.cjs');
|
|
const { evaluatePredicate } = gatePredicateEval;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import apiCoverageMod = require('./api-coverage.cjs');
|
|
const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
|
|
import { execTool, platformReadSync, posixNormalize } from './shell-command-projection.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import planScanMod = require('./plan-scan.cjs');
|
|
const { scanPhasePlans } = planScanMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import planningScopeMod = require('./planning-scope.cjs');
|
|
const { SCOPE } = planningScopeMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import verifyCommandGroundingMod = require('./verify-command-grounding.cjs');
|
|
const { probePhaseVerifyCommands, probePhaseFailingDirections } = verifyCommandGroundingMod;
|
|
|
|
// ─── Helpers ──────────────────────────────────────────────────────────────────
|
|
|
|
function normalizePhrase(text: unknown): string {
|
|
// eslint-disable-next-line @typescript-eslint/no-base-to-string
|
|
return String(text || '')
|
|
.toLowerCase()
|
|
.replace(/[^a-z0-9\s]/g, ' ')
|
|
.replace(/\s+/g, ' ')
|
|
.trim();
|
|
}
|
|
|
|
const SOFT_PHRASE_MIN_WORDS = 6;
|
|
|
|
function softPhrase(text: unknown): string {
|
|
const words = normalizePhrase(text).split(' ').filter(Boolean);
|
|
if (words.length < SOFT_PHRASE_MIN_WORDS) return '';
|
|
return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
|
|
}
|
|
|
|
function decisionMentioned(haystack: string | null | undefined, decision: Decision): boolean {
|
|
if (!haystack) return false;
|
|
if (new RegExp(`\\b${decision.id}\\b`).test(haystack)) return true;
|
|
const phrase = softPhrase(decision.text);
|
|
return phrase ? normalizePhrase(haystack).includes(phrase) : false;
|
|
}
|
|
|
|
function readIfExists(filePath: string): string {
|
|
try {
|
|
return fs.readFileSync(filePath, 'utf-8');
|
|
} catch {
|
|
return '';
|
|
}
|
|
}
|
|
|
|
function resolvePath(inputPath: string, projectDir: string): string {
|
|
return path.isAbsolute(inputPath) ? inputPath : path.join(projectDir, inputPath);
|
|
}
|
|
|
|
interface WorkflowConfig {
|
|
auto_advance?: boolean;
|
|
_auto_chain_active?: boolean;
|
|
context_coverage_gate?: boolean | string;
|
|
}
|
|
|
|
function readWorkflowConfig(projectDir: string): WorkflowConfig {
|
|
const configPath = path.join(projectDir, '.planning', 'config.json');
|
|
try {
|
|
const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
|
|
const wf = (parsed['workflow'] as Record<string, unknown> | undefined) || {};
|
|
return {
|
|
...wf,
|
|
auto_advance: (wf['auto_advance'] ?? parsed['auto_advance']) as boolean | undefined,
|
|
_auto_chain_active: (wf['_auto_chain_active'] ?? parsed['_auto_chain_active']) as boolean | undefined,
|
|
context_coverage_gate: (wf['context_coverage_gate'] ?? parsed['context_coverage_gate']) as boolean | string | undefined,
|
|
};
|
|
} catch {
|
|
return {};
|
|
}
|
|
}
|
|
|
|
function cmdAutoMode(projectDir: string, raw: boolean): void {
|
|
const workflow = readWorkflowConfig(projectDir);
|
|
const autoAdvance = Boolean(workflow.auto_advance ?? false);
|
|
const autoChainActive = Boolean(workflow._auto_chain_active ?? false);
|
|
let source = 'none';
|
|
if (autoChainActive && autoAdvance) source = 'both';
|
|
else if (autoChainActive) source = 'auto_chain';
|
|
else if (autoAdvance) source = 'auto_advance';
|
|
|
|
output({
|
|
active: autoChainActive || autoAdvance,
|
|
source,
|
|
auto_chain_active: autoChainActive,
|
|
auto_advance: autoAdvance,
|
|
}, raw, undefined);
|
|
}
|
|
|
|
function gateEnabled(projectDir: string): boolean {
|
|
const value = readWorkflowConfig(projectDir).context_coverage_gate;
|
|
if (typeof value === 'boolean') return value;
|
|
if (typeof value === 'string') {
|
|
const lower = value.toLowerCase();
|
|
if (lower === 'false' || lower === 'true') return lower !== 'false';
|
|
}
|
|
return true;
|
|
}
|
|
|
|
function loadPlanContents(phaseDir: string): string[] {
|
|
if (!fs.existsSync(phaseDir)) return [];
|
|
// #3183 (lint-plan-count-drift): source live plan files from the single
|
|
// owner (scanPhasePlans) instead of a local `-PLAN.md` readdirSync filter
|
|
// — picks up bare PLAN.md and nested plans/, and excludes plans marked
|
|
// `status: superseded`, which the prior root-only exact-suffix filter did
|
|
// neither for.
|
|
return scanPhasePlans(phaseDir).planFiles
|
|
.map((entry) => readIfExists(path.join(phaseDir, entry)));
|
|
}
|
|
|
|
const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
|
|
// #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
|
|
// is meaningful. `<objective>`/`<tasks>`/`<task>`/`<action>` are the historical core. The
|
|
// planner is also explicitly told (plan-phase.md) to cite decisions in `<read_first>`,
|
|
// `<behavior>`, `<verify>`, `<acceptance_criteria>`, and `<done>` — those are now scanned too,
|
|
// so the gate no longer reports a false coverage gap when a decision is cited in any of them.
|
|
//
|
|
// Implementation: per-tag matching, NOT a single wide alternation. A single alternation
|
|
// like `<(?:a|b|c)>...<\/(?:a|b|c)>` halts the outer tag's body capture at any inner tag
|
|
// in the set, dropping any citation in the outer tag's prefix prose — e.g.
|
|
// `<action>per D-05 <verify>npm test</verify></action>` would lose D-05 because `<verify>`
|
|
// halts the `<action>` body before the citation. Per-tag matching avoids this: each tag's
|
|
// body terminates only at its OWN closing tag, so `<verify>` inside `<action>` is absorbed
|
|
// into `<action>`'s body (D-05 caught) AND `<verify>` is matched separately on its own pass.
|
|
// Each per-tag regex keeps the ReDoS-safe negative-lookahead tempering (#2128).
|
|
const XML_DECISION_TAG_NAMES = ['objective', 'tasks', 'task', 'action', 'read_first', 'behavior', 'verify', 'acceptance_criteria', 'done'] as const;
|
|
|
|
function buildXmlDecisionTagRegex(tagName: string): RegExp {
|
|
// Per-tag: body tempering stops only at the SAME tag's reopening or closing — other
|
|
// scanned tags pass through as text into this body. Non-greedy `*?` to first close.
|
|
return new RegExp(
|
|
`<${tagName}(?:\\s[^>]{0,1000})?>((?:(?!<${tagName}[\\s>])[\\s\\S])*?)<\\/${tagName}>`,
|
|
'gi',
|
|
);
|
|
}
|
|
|
|
function stripCommentsAndFences(text: string): string {
|
|
// HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
|
|
// Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
|
|
// so downstream tags are preserved (unlike a `(?:-->|$)` fallback, which would
|
|
// wipe to EOF and fail-close the decision-coverage gate).
|
|
const htmlStripped = text.replace(/<!--(?:(?!<!--)[\s\S])*?-->/g, ' ');
|
|
// Fenced-code stripping: delegate to the canonical CommonMark-correct seam.
|
|
// replaces the prior independent regex copy (```` ``` ``` ```` + `~~~ ~~~`).
|
|
return stripFencedCode(htmlStripped).text;
|
|
}
|
|
|
|
function extractYamlBlock(frontmatter: string, key: string): string {
|
|
const match = frontmatter.match(new RegExp(`^${key}\\s*:(.*)$`, 'm'));
|
|
if (!match) return '';
|
|
const startIdx = (match.index || 0) + match[0].length;
|
|
const rest = frontmatter.slice(startIdx + 1).split(/\r?\n/);
|
|
const block = [match[1] || ''];
|
|
for (const line of rest) {
|
|
if (line === '' || /^\s/.test(line)) block.push(line);
|
|
else break;
|
|
}
|
|
return block.join('\n');
|
|
}
|
|
|
|
function extractXmlTagBodies(text: string): string {
|
|
const parts: string[] = [];
|
|
for (const tagName of XML_DECISION_TAG_NAMES) {
|
|
const re = buildXmlDecisionTagRegex(tagName);
|
|
for (const match of text.matchAll(re)) {
|
|
if (match[1]) parts.push(match[1]);
|
|
}
|
|
}
|
|
return parts.join('\n');
|
|
}
|
|
|
|
function extractPlanDesignatedSections(planContent: string | null | undefined): string {
|
|
if (!planContent) return '';
|
|
const cleaned = stripCommentsAndFences(planContent);
|
|
const fmMatch = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
|
|
const frontmatter = fmMatch ? fmMatch[1] : '';
|
|
const body = fmMatch ? fmMatch[2] : cleaned;
|
|
|
|
const parts: string[] = [];
|
|
for (const key of ['must_haves', 'truths', 'objective']) {
|
|
const block = extractYamlBlock(frontmatter, key);
|
|
if (block) parts.push(block);
|
|
}
|
|
|
|
// Replace hand-rolled split(/\r?\n/) + heading walk with the seam's collectSections.
|
|
// stopPredicate fires on EVERY heading (collectSections needs to start a section at
|
|
// each heading), then we filter to designated ones — same semantics as the prior
|
|
// inDesignated flag: emit the heading line + body only when DESIGNATED_HEADINGS_RE matches.
|
|
const sections = collectSections(body, () => true);
|
|
const bodyParts: string[] = [];
|
|
for (const section of sections) {
|
|
const headingLine = '#'.repeat(section.heading.level) + ' ' + section.heading.text;
|
|
if (DESIGNATED_HEADINGS_RE.test(headingLine)) {
|
|
bodyParts.push(headingLine);
|
|
if (section.body) bodyParts.push(section.body);
|
|
}
|
|
}
|
|
parts.push(bodyParts.join('\n'));
|
|
parts.push(extractXmlTagBodies(cleaned));
|
|
return parts.join('\n\n');
|
|
}
|
|
|
|
interface UncoveredItem {
|
|
id: string;
|
|
text: string;
|
|
category: string;
|
|
}
|
|
|
|
function buildPlanMessage(uncovered: UncoveredItem[]): string {
|
|
if (uncovered.length === 0) return 'All trackable CONTEXT.md decisions are covered by plans.';
|
|
return [
|
|
'## Decision Coverage Gap',
|
|
'',
|
|
`${uncovered.length} CONTEXT.md decision(s) are not covered by any plan:`,
|
|
'',
|
|
...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
|
|
'',
|
|
'Resolve by citing `D-NN:` in any of the scanned plan surfaces: front-matter',
|
|
'`must_haves`/`truths`/`objective`, a `## must_haves`/`truths`/`tasks`/`objective`',
|
|
'heading, or an `<objective>`/`<tasks>`/`<task>`/`<action>`/`<read_first>`/`<behavior>`/`<verify>`/`<acceptance_criteria>`/`<done>`',
|
|
'tag body. Other locations (prose outside those headings, comments, other XML tags) are not scanned.',
|
|
'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
|
|
].join('\n');
|
|
}
|
|
|
|
function buildVerifyMessage(notHonored: UncoveredItem[]): string {
|
|
if (notHonored.length === 0) return 'All trackable CONTEXT.md decisions are honored by shipped artifacts.';
|
|
return [
|
|
'### Decision Coverage (warning)',
|
|
'',
|
|
`${notHonored.length} decision(s) not found in shipped artifacts:`,
|
|
'',
|
|
...notHonored.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
|
|
'',
|
|
'This is a soft warning - verification status is unchanged.',
|
|
].join('\n');
|
|
}
|
|
|
|
function loadDecisionExtraction(contextPath: string): { trackable: Decision[]; outcome: 'parsed' | 'none-present' | 'could-not-parse' } {
|
|
const extraction = extractDecisions(readIfExists(contextPath));
|
|
return {
|
|
trackable: extraction.decisions.filter((d) => d.trackable),
|
|
outcome: extraction.outcome,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* `check decision-coverage-plan` — blocking plan-phase decision-coverage gate
|
|
* (#2492, #1365 fail-loud, #2770 empty-arg fail-closed).
|
|
*
|
|
* Invocation (the context path may be supplied EITHER way; #4130 follow-up):
|
|
* gsd_run check decision-coverage-plan <phase-dir> <context-path> (positional, the workflow caller's form)
|
|
* gsd_run check decision-coverage-plan --context <path> [<phase-dir>]
|
|
*
|
|
* `--context <path>` follows the sibling flag convention (`check predicate`,
|
|
* #2008): `--flag value` pairs parsed by the shared partitionPredicateArgs
|
|
* pass, the flag WINNING over a same-purpose positional when both appear,
|
|
* and a valueless `--context` counting as no context at all (it falls
|
|
* through to the #2770 caller-error branch, not to the "CONTEXT.md missing"
|
|
* green skip). The positional form keeps working unchanged — no sibling
|
|
* check verb deprecates positionals and the plan-phase workflow passes them.
|
|
*/
|
|
function cmdDecisionCoveragePlan(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0]='check', args[1]=subcommand — partition the REST so flag tokens
|
|
// and their values never land in a positional slot.
|
|
const { flags, positionals } = partitionPredicateArgs(args.slice(2));
|
|
const phaseDir = positionals[0] ? resolvePath(positionals[0], projectDir) : '';
|
|
// A VALUELESS `--context` stays a bare token in the positionals (sibling
|
|
// parser semantics); it must not then be read as the context PATH — a
|
|
// `--`-prefixed "path" is a caller mistake, and #2770's law says a missing
|
|
// context argument fails CLOSED, never a silent "CONTEXT.md missing" green
|
|
// skip. So only a non-flag positional may serve as the context.
|
|
const positionalContext = positionals[1] && !positionals[1].startsWith('--') ? positionals[1] : '';
|
|
const contextArg = flags['context'] ?? positionalContext ?? '';
|
|
const contextPath = contextArg ? resolvePath(contextArg, projectDir) : '';
|
|
|
|
if (!gateEnabled(projectDir)) {
|
|
output({ passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
|
|
return;
|
|
}
|
|
// #2770: an EMPTY/MISSING contextPath argument is a CALLER ERROR (the workflow
|
|
// forgot to pass the path — e.g. a shell variable lost between Bash blocks), not
|
|
// evidence the phase has no CONTEXT.md. Fail closed (mirrors #1365 fail-loud) so a
|
|
// blocking gate cannot silently certify success on a caller mistake.
|
|
if (!contextArg || contextArg === '') {
|
|
output({ passed: false, skipped: false, reason: 'missing context path argument', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate called without a context path argument — the caller (e.g. the plan-phase workflow) must pass the CONTEXT.md path. An empty argument is a caller error, not evidence there is nothing to check (#2770).' }, raw, undefined);
|
|
return;
|
|
}
|
|
// A REAL path whose file genuinely does not exist is the LEGITIMATE green skip.
|
|
if (!fs.existsSync(contextPath)) {
|
|
output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
const { trackable: decisions, outcome } = loadDecisionExtraction(contextPath);
|
|
|
|
// #1365 fail-loud gate: any could-not-parse outcome must NOT silently pass —
|
|
// even when some decisions were extracted (e.g. D-01 valid but D-02 malformed).
|
|
// A parse-miss on ANY bullet means the gate cannot certify full coverage.
|
|
// Fire independent of decisions.length so a partial-parse still blocks.
|
|
if (outcome === 'could-not-parse') {
|
|
const partialParse = decisions.length > 0;
|
|
output({
|
|
passed: false,
|
|
skipped: false,
|
|
reason: 'could-not-parse',
|
|
total: decisions.length,
|
|
covered: 0,
|
|
uncovered: [],
|
|
message: partialParse
|
|
? 'Decision coverage gate: decisions could not be fully parsed — one or more ' +
|
|
'`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
|
|
'prefix that is not a digit run, e.g. `D4x-01`). Fix the bullet format so all decisions ' +
|
|
'can be read before re-running the gate.'
|
|
: 'Decision coverage gate: could not parse decisions — possible format mismatch. ' +
|
|
'The CONTEXT.md appears to be decision-shaped (has a <decisions> block, a decisions heading, ' +
|
|
'or D- tokens) but no decision bullets could be extracted. Check the formatting of the decisions ' +
|
|
'block and ensure bullets follow the `- **D-NN:** text`, `- **D4-NN:** text` (phase-prefixed), ' +
|
|
'or `- **D-NN — title** body` form. An ID grammar the parser does not support (e.g. `DEC-01`) ' +
|
|
'also lands here.',
|
|
}, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
if (decisions.length === 0) {
|
|
output({ passed: true, skipped: true, reason: 'no trackable decisions', total: 0, covered: 0, uncovered: [], message: 'No trackable decisions in CONTEXT.md.' }, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
const sections = loadPlanContents(phaseDir).map(extractPlanDesignatedSections);
|
|
const uncovered: UncoveredItem[] = [];
|
|
let covered = 0;
|
|
for (const decision of decisions) {
|
|
if (sections.some((section) => decisionMentioned(section, decision))) covered++;
|
|
else uncovered.push({ id: decision.id, text: decision.text, category: decision.category });
|
|
}
|
|
|
|
output({
|
|
passed: uncovered.length === 0,
|
|
skipped: false,
|
|
total: decisions.length,
|
|
covered,
|
|
uncovered,
|
|
message: buildPlanMessage(uncovered),
|
|
}, raw, undefined);
|
|
}
|
|
|
|
function recentCommitMessages(projectDir: string): string {
|
|
try {
|
|
return execFileSync('git', ['log', '-n', '200', '--pretty=%s%n%b'], {
|
|
cwd: projectDir,
|
|
encoding: 'utf-8',
|
|
maxBuffer: 4 * 1024 * 1024,
|
|
windowsHide: true,
|
|
timeout: 15_000,
|
|
});
|
|
} catch {
|
|
return '';
|
|
}
|
|
}
|
|
|
|
function isInsideRoot(candidatePath: string, rootDir: string): boolean {
|
|
const root = path.resolve(rootDir);
|
|
const target = path.resolve(root, candidatePath);
|
|
return target === root || target.startsWith(`${root}${path.sep}`);
|
|
}
|
|
|
|
function readModifiedFilesContent(projectDir: string, summaries: string[]): string {
|
|
const out: string[] = [];
|
|
let total = 0;
|
|
for (const summary of summaries) {
|
|
if (!summary) continue;
|
|
for (const blockMatch of summary.matchAll(/files_modified:\s*\n((?:[ \t]*-\s+.+\n?)+)/g)) {
|
|
const files = [...(blockMatch[1] || '').matchAll(/-\s+(.+)/g)]
|
|
.map((match) => match[1].trim().replace(/^["']|["']$/g, ''));
|
|
for (const file of files) {
|
|
if (total >= 50) break;
|
|
if (!file || !isInsideRoot(file, projectDir)) continue;
|
|
const raw = readIfExists(resolvePath(file, projectDir));
|
|
out.push(raw.length > 256 * 1024 ? raw.slice(0, 256 * 1024) : raw);
|
|
total++;
|
|
}
|
|
if (total >= 50) break;
|
|
}
|
|
if (total >= 50) break;
|
|
}
|
|
return out.join('\n\n');
|
|
}
|
|
|
|
function cmdDecisionCoverageVerify(projectDir: string, args: string[], raw: boolean): void {
|
|
const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
|
|
const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
|
|
|
|
if (!gateEnabled(projectDir)) {
|
|
output({ skipped: true, blocking: false, reason: 'workflow.context_coverage_gate is false', total: 0, honored: 0, not_honored: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
|
|
return;
|
|
}
|
|
if (!contextPath || !fs.existsSync(contextPath)) {
|
|
output({ skipped: true, blocking: false, reason: 'CONTEXT.md missing', total: 0, honored: 0, not_honored: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
const { trackable: decisions, outcome: decisionOutcome } = loadDecisionExtraction(contextPath);
|
|
|
|
// Mirror could-not-parse surface for verify (non-blocking advisory WARN).
|
|
// Fire independent of decisions.length — a parse-miss on any bullet must surface,
|
|
// even when some decisions were partially extracted (#1365 fix-parity with plan gate).
|
|
if (decisionOutcome === 'could-not-parse') {
|
|
const partialParse = decisions.length > 0;
|
|
output({
|
|
skipped: false,
|
|
blocking: false,
|
|
reason: 'could-not-parse',
|
|
total: decisions.length,
|
|
honored: 0,
|
|
not_honored: [],
|
|
message: partialParse
|
|
? 'Decision coverage verify (warning): decisions could not be fully parsed — one or more ' +
|
|
'`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
|
|
'prefix that is not a digit run). Fix the bullet format in the CONTEXT.md decisions block.'
|
|
: 'Decision coverage verify (warning): could not parse decisions — possible format mismatch. ' +
|
|
'Check the formatting of the CONTEXT.md decisions block (accepted forms: `- **D-NN:** text`, ' +
|
|
'`- **D4-NN:** text` (phase-prefixed), `- **D-NN — title** body`).',
|
|
}, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
if (decisions.length === 0) {
|
|
output({ skipped: true, blocking: false, reason: 'no trackable decisions', total: 0, honored: 0, not_honored: [], message: 'No trackable decisions in CONTEXT.md.' }, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
const planContents = loadPlanContents(phaseDir);
|
|
// #3183 (lint-plan-count-drift): same single-owner sourcing as
|
|
// loadPlanContents above — scanPhasePlans's summaryFiles instead of a
|
|
// local `-SUMMARY.md` readdirSync filter.
|
|
const summaryParts = fs.existsSync(phaseDir)
|
|
? scanPhasePlans(phaseDir).summaryFiles.map((entry) => readIfExists(path.join(phaseDir, entry)))
|
|
: [];
|
|
const haystack = [
|
|
planContents.join('\n\n'),
|
|
summaryParts.join('\n\n'),
|
|
readModifiedFilesContent(projectDir, summaryParts),
|
|
recentCommitMessages(projectDir),
|
|
].join('\n\n');
|
|
|
|
const notHonored: UncoveredItem[] = [];
|
|
let honored = 0;
|
|
for (const decision of decisions) {
|
|
if (decisionMentioned(haystack, decision)) honored++;
|
|
else notHonored.push({ id: decision.id, text: decision.text, category: decision.category });
|
|
}
|
|
|
|
output({
|
|
skipped: false,
|
|
blocking: false,
|
|
total: decisions.length,
|
|
honored,
|
|
not_honored: notHonored,
|
|
message: buildVerifyMessage(notHonored),
|
|
}, raw, undefined);
|
|
}
|
|
|
|
// ─── ui-plan-gate ─────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* ui-plan-gate: given a phase number, checks whether the phase has frontend
|
|
* indicators and whether a *-UI-SPEC.md already exists in the phase directory.
|
|
*
|
|
* Returns JSON: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine }
|
|
* block = frontend && hasFrontendEvidence && !hasUiSpec (#3312: gate fires when
|
|
* UI work is detected AND the repo has static frontend evidence but no spec exists)
|
|
*
|
|
* Invocable as: gsd_run check ui-plan-gate <phase>
|
|
*
|
|
* Uses checkUiPresence from ui-safety-gate.cjs — does NOT reimplement frontend detection.
|
|
* Uses getRoadmapPhaseWithFallback + findPhaseInternal from leaf modules for phase data.
|
|
*/
|
|
function findUiSpecInDir(phaseDir: string): string {
|
|
if (!phaseDir || !fs.existsSync(phaseDir)) return '';
|
|
try {
|
|
const files = fs.readdirSync(phaseDir);
|
|
const found = files.find((f) => /-UI-SPEC\.md$/.test(f));
|
|
return found ? path.join(phaseDir, found) : '';
|
|
} catch {
|
|
return '';
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Pure logic for ui-plan-gate — exposed for direct behavioral testing.
|
|
*
|
|
* Given a projectDir and phase number:
|
|
* (a) Reads the phase section from ROADMAP.md via getRoadmapPhaseWithFallback —
|
|
* same two-pass lookup (current milestone → full roadmap) as `roadmap.get-phase`
|
|
* (cmdRoadmapGetPhase). Cross-milestone / older frontend phases resolve correctly.
|
|
* If ROADMAP.md is missing, phaseSection is '' (ROADMAP.md not present = project
|
|
* has no roadmap = cannot be frontend). If the phase truly can't be found after
|
|
* both passes, phaseSection is '' and phaseLookupFailed is set so callers can
|
|
* surface the miss — we do NOT silently degrade to frontend:false if the roadmap
|
|
* exists but the phase header is absent.
|
|
* (b) Runs checkUiPresence (frontend detection) — no reimplementation.
|
|
* (c) Resolves the phase directory via findPhaseInternal (phase-locator.cjs); checks for *-UI-SPEC.md.
|
|
*
|
|
* Returns: { frontend, hasFrontendEvidence, hasUiSpec, block, uiSpecPath, matchedToken, matchedLine, phaseLookupFailed }
|
|
* block = frontend && hasFrontendEvidence && !hasUiSpec (#3312)
|
|
* phaseLookupFailed = ROADMAP.md present but phase header not found (surfaced for
|
|
* onError:halt gates so a missing phase doesn't silently bypass)
|
|
*
|
|
* #3312 — structural corroboration: `frontend` is a vocabulary signal only. A
|
|
* hyphen is a word boundary, so a phase naming the repo `dashboard-financeiro`
|
|
* matches the token `dashboard` exactly like the real compound `micro-frontend`
|
|
* (the boundary rule of #3718 is intentional and untouched). The gate therefore
|
|
* blocks only when the token match is corroborated by static frontend evidence
|
|
* in the repo tree (hasStaticFrontendEvidence: package.json UI-framework dep or
|
|
* a component-framework file). This mirrors the sibling post-wave gate
|
|
* computeUiSafetyGate, which requires `hasUiFiles` (git diff) before blocking.
|
|
* matchedToken/matchedLine surface what tripped the sniffer so an operator can
|
|
* judge the flag in one second instead of reaching for --skip-ui.
|
|
*/
|
|
function computeUiPlanGate(projectDir: string, phase: string): {
|
|
frontend: boolean;
|
|
hasFrontendEvidence: boolean;
|
|
hasUiSpec: boolean;
|
|
block: boolean;
|
|
uiSpecPath: string | null;
|
|
matchedToken: string | null;
|
|
matchedLine: string | null;
|
|
phaseLookupFailed?: boolean;
|
|
} {
|
|
// (a) Read the phase section text using the same two-pass lookup as roadmap.get-phase.
|
|
// getRoadmapPhaseWithFallback: current-milestone first, then stripShippedMilestones
|
|
// fallback — mirrors cmdRoadmapGetPhase exactly.
|
|
let phaseSection = '';
|
|
let phaseLookupFailed: boolean | undefined;
|
|
try {
|
|
const section = getRoadmapPhaseWithFallback(projectDir, phase);
|
|
if (section === null) {
|
|
// Distinguish: ROADMAP.md missing (no-roadmap project) vs phase not found in ROADMAP.
|
|
// planningDir(cwd) resolves the .planning/ root for workstream-aware paths.
|
|
const planDir: string = planningDir(projectDir);
|
|
const roadmapPath = path.join(planDir, 'ROADMAP.md');
|
|
if (fs.existsSync(roadmapPath)) {
|
|
// ROADMAP.md exists but phase was not found → surface the miss
|
|
phaseLookupFailed = true;
|
|
}
|
|
// phaseSection stays ''
|
|
} else {
|
|
phaseSection = section;
|
|
}
|
|
} catch { /* roadmap read failure → treat as empty (non-frontend) */ }
|
|
|
|
// (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
|
|
const presenceResult = checkUiPresence(phaseSection);
|
|
const frontend = presenceResult.hasUI;
|
|
|
|
// (b') #3312 — static structural corroboration. Only probed when the sniffer
|
|
// matched (evidence is irrelevant otherwise); failures degrade to false.
|
|
const hasFrontendEvidence = frontend ? hasStaticFrontendEvidence(projectDir) : false;
|
|
|
|
// (c) Resolve phase directory via findPhaseInternal and check for *-UI-SPEC.md
|
|
let phaseDir = '';
|
|
try {
|
|
const result = findPhaseInternal(projectDir, phase);
|
|
if (result && typeof result === 'object') {
|
|
// findPhaseInternal returns { directory: '<relative-posix-path>', ... }
|
|
// directory is relative to cwd — resolve it to absolute.
|
|
const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
|
|
if (relDir) {
|
|
phaseDir = path.resolve(projectDir, relDir);
|
|
}
|
|
} else if (typeof result === 'string') {
|
|
phaseDir = result;
|
|
}
|
|
} catch { /* phase dir lookup failure → hasUiSpec=false */ }
|
|
|
|
const uiSpecPath = findUiSpecInDir(phaseDir);
|
|
const hasUiSpec = uiSpecPath !== '';
|
|
|
|
// block = frontend phase with structural frontend evidence and no UI-SPEC (#3312)
|
|
const block = frontend && hasFrontendEvidence && !hasUiSpec;
|
|
|
|
const result: {
|
|
frontend: boolean;
|
|
hasFrontendEvidence: boolean;
|
|
hasUiSpec: boolean;
|
|
block: boolean;
|
|
uiSpecPath: string | null;
|
|
matchedToken: string | null;
|
|
matchedLine: string | null;
|
|
phaseLookupFailed?: boolean;
|
|
} = {
|
|
frontend, hasFrontendEvidence, hasUiSpec, block,
|
|
uiSpecPath: hasUiSpec ? uiSpecPath : null,
|
|
matchedToken: presenceResult.matchedToken,
|
|
matchedLine: presenceResult.matchedLine,
|
|
};
|
|
if (phaseLookupFailed) result.phaseLookupFailed = true;
|
|
return result;
|
|
}
|
|
|
|
function cmdUiPlanGate(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'ui-plan-gate', args[2] = phase
|
|
const phase = args[2] || '';
|
|
if (!phase) {
|
|
error('ui-plan-gate requires a phase argument: check ui-plan-gate <phase>', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
output(computeUiPlanGate(projectDir, phase), raw, undefined);
|
|
}
|
|
|
|
// ─── ui-safety-gate ───────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* ui-safety-gate: post-wave check that verifies UI-changed files conform to
|
|
* the active UI-SPEC for the phase. Called after each wave by execute:wave:post.
|
|
*
|
|
* Returns JSON: { frontend: boolean, hasUiFiles: boolean, hasUiSpec: boolean, block: boolean, message?: string }
|
|
* block = frontend && hasUiFiles && !hasUiSpec
|
|
*
|
|
* Args: check ui-safety-gate <phase>
|
|
* Invocable as: gsd_run check ui-safety-gate <phase>
|
|
* or gsd_run check ui.safety-gate <phase> (dots normalized to hyphens)
|
|
*
|
|
* Uses checkUiPresence from ui-safety-gate.cjs — does NOT reimplement frontend detection.
|
|
* Checks whether any files changed in recent git history match frontend file patterns.
|
|
* Also checks whether a *-UI-SPEC.md exists in the phase directory (same as ui-plan-gate).
|
|
*
|
|
* Limitation: uses git diff HEAD~1..HEAD which covers only the last commit; in a
|
|
* multi-plan wave the wave-start commit would be more accurate but is not yet stored
|
|
* in the wave manifest. This is tracked as a known limitation.
|
|
*/
|
|
const UI_FILE_EXTENSIONS_RE = /\.(tsx|jsx|css|scss|sass|less|vue|svelte|html)$/i;
|
|
const UI_PATH_PATTERNS_RE = /\/(components|pages|views|screens|layouts|ui|frontend)\//i;
|
|
|
|
/**
|
|
* Pure logic for ui-safety-gate — exposed for direct behavioral testing.
|
|
*
|
|
* Given a projectDir and phase number:
|
|
* (a) Reads the phase section from ROADMAP.md via getRoadmapPhaseWithFallback —
|
|
* same lookup as computeUiPlanGate — to determine if this is a frontend phase.
|
|
* (b) Runs checkUiPresence (frontend detection) — no reimplementation.
|
|
* (c) Checks git diff HEAD~1..HEAD for UI file changes in the current worktree.
|
|
* (d) Resolves the phase directory via findPhaseInternal (phase-locator.cjs); checks for *-UI-SPEC.md.
|
|
*
|
|
* Returns: { frontend, hasUiFiles, hasUiSpec, block, message?, phaseLookupFailed? }
|
|
* block = frontend && hasUiFiles && !hasUiSpec
|
|
* phaseLookupFailed = ROADMAP.md present but phase header not found
|
|
*/
|
|
function computeUiSafetyGate(projectDir: string, phase: string): {
|
|
frontend: boolean;
|
|
hasUiFiles: boolean;
|
|
hasUiSpec: boolean;
|
|
block: boolean;
|
|
message?: string;
|
|
phaseLookupFailed?: boolean;
|
|
} {
|
|
// (a) Read the phase section text (same two-pass lookup as computeUiPlanGate)
|
|
let phaseSection = '';
|
|
let phaseLookupFailed: boolean | undefined;
|
|
try {
|
|
const section = getRoadmapPhaseWithFallback(projectDir, phase);
|
|
if (section === null) {
|
|
const planDir: string = planningDir(projectDir);
|
|
const roadmapPath = path.join(planDir, 'ROADMAP.md');
|
|
if (fs.existsSync(roadmapPath)) {
|
|
phaseLookupFailed = true;
|
|
}
|
|
} else {
|
|
phaseSection = section;
|
|
}
|
|
} catch { /* roadmap read failure → treat as empty (non-frontend) */ }
|
|
|
|
// (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
|
|
const presenceResult = checkUiPresence(phaseSection);
|
|
const frontend = presenceResult.hasUI;
|
|
|
|
// (c) Check whether any UI files were changed in recent git commits
|
|
// Uses git diff HEAD~1..HEAD to detect frontend file changes since last commit.
|
|
// Known limitation: multi-plan waves may need the wave-start commit for full coverage.
|
|
let hasUiFiles = false;
|
|
try {
|
|
const changed = execFileSync('git', ['diff', '--name-only', 'HEAD~1', 'HEAD'], {
|
|
cwd: projectDir,
|
|
encoding: 'utf-8',
|
|
maxBuffer: 2 * 1024 * 1024,
|
|
windowsHide: true,
|
|
timeout: 10_000,
|
|
});
|
|
hasUiFiles = changed.split('\n').some((f) =>
|
|
f.trim() && (UI_FILE_EXTENSIONS_RE.test(f) || UI_PATH_PATTERNS_RE.test(f)),
|
|
);
|
|
} catch { /* git unavailable or no prior commit — treat as no UI files changed */ }
|
|
|
|
// (d) Resolve phase directory and check for *-UI-SPEC.md (same as computeUiPlanGate)
|
|
let phaseDir = '';
|
|
try {
|
|
const result = findPhaseInternal(projectDir, phase);
|
|
if (result && typeof result === 'object') {
|
|
const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
|
|
if (relDir) {
|
|
phaseDir = path.resolve(projectDir, relDir);
|
|
}
|
|
} else if (typeof result === 'string') {
|
|
phaseDir = result;
|
|
}
|
|
} catch { /* phase dir lookup failure → hasUiSpec=false */ }
|
|
|
|
const uiSpecPath = findUiSpecInDir(phaseDir);
|
|
const hasUiSpec = uiSpecPath !== '';
|
|
|
|
// block only when: this is a frontend phase AND UI files were changed AND no UI-SPEC exists
|
|
const block = frontend && hasUiFiles && !hasUiSpec;
|
|
|
|
const result: {
|
|
frontend: boolean;
|
|
hasUiFiles: boolean;
|
|
hasUiSpec: boolean;
|
|
block: boolean;
|
|
message?: string;
|
|
phaseLookupFailed?: boolean;
|
|
} = { frontend, hasUiFiles, hasUiSpec, block };
|
|
|
|
if (block) {
|
|
result.message = `UI files changed in this wave but no UI-SPEC.md exists for Phase ${phase}. ` +
|
|
`Run /gsd:ui-phase ${phase} to generate the design contract before continuing.`;
|
|
}
|
|
if (phaseLookupFailed) result.phaseLookupFailed = true;
|
|
return result;
|
|
}
|
|
|
|
function cmdUiSafetyGate(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'ui-safety-gate', args[2] = phase
|
|
const phase = args[2] || '';
|
|
if (!phase) {
|
|
error('ui-safety-gate requires a phase argument: check ui-safety-gate <phase>', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
output(computeUiSafetyGate(projectDir, phase), raw, undefined);
|
|
}
|
|
|
|
// ─── tdd-review-checkpoint ────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* tdd-review-checkpoint: end-of-phase advisory check that scans type:tdd plans
|
|
* for RED/GREEN/REFACTOR gate-sequence compliance and surfaces a review table.
|
|
*
|
|
* Logic from gsd-core/references/tdd.md <end_of_phase_review> and
|
|
* execute-phase.md <step name="tdd_review_checkpoint"> (now removed).
|
|
*
|
|
* Returns JSON:
|
|
* { passed: true, tddPlans: N, violations: N, table: string, rows: PlanRow[] }
|
|
* where passed is always true (advisory gate — never blocks).
|
|
*
|
|
* Args: check tdd.review-checkpoint <phase>
|
|
* Phase can be a number or phase-dir path; if not resolvable the check
|
|
* returns passed:true with tddPlans:0 (no plans to review).
|
|
*/
|
|
interface TddPlanRow {
|
|
planId: string;
|
|
red: boolean;
|
|
green: boolean;
|
|
refactor: boolean;
|
|
status: 'Pass' | 'FAIL';
|
|
missing: string[];
|
|
}
|
|
|
|
function cmdTddReviewCheckpoint(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'tdd-review-checkpoint' (normalized), args[2] = phase
|
|
const phase = args[2] || '';
|
|
if (!phase) {
|
|
error('tdd.review-checkpoint requires a phase argument: check tdd.review-checkpoint <phase>', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
|
|
// Resolve phase directory
|
|
let phaseDir = '';
|
|
try {
|
|
const result = findPhaseInternal(projectDir, phase);
|
|
if (result && typeof result === 'object') {
|
|
const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
|
|
if (relDir) phaseDir = path.resolve(projectDir, relDir);
|
|
} else if (typeof result === 'string') {
|
|
phaseDir = result;
|
|
}
|
|
} catch { /* phase dir lookup failure */ }
|
|
|
|
// Find all PLAN.md files with type: tdd in frontmatter
|
|
const tddPlanFiles: string[] = [];
|
|
if (phaseDir) {
|
|
try {
|
|
// #3183: canonical plan set (root+nested, superseded-excluded) from the
|
|
// single owner, rather than a root-only hand-rolled readdirSync filter.
|
|
const files = scanPhasePlans(phaseDir).planFiles;
|
|
for (const file of files) {
|
|
const planPath = path.join(phaseDir, file);
|
|
const content = readIfExists(planPath);
|
|
// Check frontmatter for type: tdd
|
|
// CRLF-tolerant: a PLAN.md written with Windows line endings (---\r\n...---)
|
|
// must still match. The same CRLF-tolerant form is already used at line 205
|
|
// (extractPlanDesignatedSections); this is the same canonical pattern, applied
|
|
// here for the tdd-classification path. Fixes #2449.
|
|
const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
|
if (frontmatterMatch) {
|
|
const fm = frontmatterMatch[1];
|
|
if (/^type:\s*tdd\s*$/m.test(fm)) {
|
|
tddPlanFiles.push(planPath);
|
|
}
|
|
}
|
|
}
|
|
} catch { /* directory read failure */ }
|
|
}
|
|
|
|
if (tddPlanFiles.length === 0) {
|
|
const result = {
|
|
// Uniform gate contract: block = violations > 0 (advisory; never truly blocks).
|
|
block: false,
|
|
passed: true,
|
|
tddPlans: 0,
|
|
violations: 0,
|
|
table: '',
|
|
rows: [] as TddPlanRow[],
|
|
message: `No type:tdd plans found in phase ${phase}. TDD review skipped.`,
|
|
};
|
|
// Pass undefined as rawValue so --raw emits JSON (not plain text).
|
|
// The human-readable report is carried in `result.message` for the
|
|
// dispatch's advisory branch to surface.
|
|
output(result, raw, undefined);
|
|
return;
|
|
}
|
|
|
|
// For each TDD plan, extract the plan ID (padded plan number) and check git log
|
|
const rows: TddPlanRow[] = [];
|
|
for (const planPath of tddPlanFiles) {
|
|
// Extract plan ID from filename (e.g. "01-02-PLAN.md" → "01-02", or "03-PLAN.md" → "03")
|
|
const basename = path.basename(planPath, '-PLAN.md');
|
|
// planId for commit grep: phase-plan format, e.g. "01-02"
|
|
const planId = basename;
|
|
|
|
// Check for RED gate commit: test({planId}):
|
|
let red = false;
|
|
let green = false;
|
|
let refactor = false;
|
|
try {
|
|
const redCommit = execFileSync(
|
|
'git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'],
|
|
{ cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 },
|
|
);
|
|
red = redCommit.trim().length > 0;
|
|
} catch { /* git unavailable or no match */ }
|
|
|
|
try {
|
|
const greenCommit = execFileSync(
|
|
'git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'],
|
|
{ cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 },
|
|
);
|
|
green = greenCommit.trim().length > 0;
|
|
} catch { /* git unavailable or no match */ }
|
|
|
|
try {
|
|
const refactorCommit = execFileSync(
|
|
'git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'],
|
|
{ cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true, timeout: 10_000 },
|
|
);
|
|
refactor = refactorCommit.trim().length > 0;
|
|
} catch { /* git unavailable or no match */ }
|
|
|
|
const missing: string[] = [];
|
|
if (!red) missing.push('RED');
|
|
if (!green) missing.push('GREEN');
|
|
const status: 'Pass' | 'FAIL' = missing.length === 0 ? 'Pass' : 'FAIL';
|
|
|
|
rows.push({ planId, red, green, refactor, status, missing });
|
|
}
|
|
|
|
const violations = rows.filter(r => r.status === 'FAIL').length;
|
|
|
|
// Build review table
|
|
const tableHeader = '| Plan | RED | GREEN | REFACTOR | Status |';
|
|
const tableDivider = '|------|-----|-------|----------|--------|';
|
|
const tableRows = rows.map(r =>
|
|
`| ${r.planId.padEnd(4)} | ${r.red ? ' ✓ ' : ' ✗ '} | ${r.green ? ' ✓ ' : ' ✗ '} | ${r.refactor ? ' ✓ ' : ' — '} | ${r.status.padEnd(6)} |`,
|
|
);
|
|
|
|
let table = [
|
|
`### TDD REVIEW — Phase ${phase}`,
|
|
'',
|
|
`TDD Plans: ${tddPlanFiles.length} | Gate violations: ${violations}`,
|
|
'',
|
|
tableHeader,
|
|
tableDivider,
|
|
...tableRows,
|
|
].join('\n');
|
|
|
|
if (violations > 0) {
|
|
table += '\n\n⚠ Gate violations are advisory — review before advancing.';
|
|
for (const r of rows.filter(row => row.status === 'FAIL')) {
|
|
table += `\n Plan ${r.planId} missing: ${r.missing.join(', ')} gate commit(s).`;
|
|
table += `\n Expected commit pattern: test(${r.planId}): ... → feat(${r.planId}): ...`;
|
|
}
|
|
}
|
|
|
|
const result = {
|
|
// Uniform gate contract: block = violations > 0.
|
|
// This gate is advisory (blocking: false in capability.json) so block:true
|
|
// only surfaces as a warning, never halts. Kept here so the host-loop
|
|
// dispatch can read a single consistent `block` field.
|
|
block: violations > 0,
|
|
passed: true,
|
|
tddPlans: tddPlanFiles.length,
|
|
violations,
|
|
table,
|
|
rows,
|
|
// Human-readable report in `message` so the dispatch's advisory branch
|
|
// can surface it. --raw emits JSON (rawValue=undefined), not plain text.
|
|
message: table,
|
|
};
|
|
// Pass undefined as rawValue so --raw emits JSON (not the raw table text).
|
|
// The review table is carried in `result.message` and `result.table` so
|
|
// the host-loop dispatch's advisory branch can surface it.
|
|
output(result, raw, undefined);
|
|
}
|
|
|
|
// ─── tdd-red-evidence (#3770) ──────────────────────────────────────────────────
|
|
|
|
/**
|
|
* tdd-red-evidence: validates a persisted RED-phase test-run record for a
|
|
* `type: tdd` plan (#3770). Only an INTENTIONAL failure of the target test
|
|
* (verdict RED_EVIDENCE_OK) may authorize GREEN; zero-test discovery, fixture/
|
|
* load crashes, nonzero exits without a failing test, unrelated failures, and
|
|
* unexpected greens are INVALID_RED and block GREEN.
|
|
*
|
|
* The record is the JSON the executor persists after running the RED command:
|
|
* { command, exitCode, output, targetTest, targetFile?, expected?, actual? }
|
|
* Fail-closed: a missing/unreadable/unparseable record is INVALID_RED
|
|
* (reason unreadable_record), never a pass.
|
|
*
|
|
* Args: check tdd-red-evidence <record.json>
|
|
*/
|
|
function cmdTddRedEvidence(_projectDir: string, args: string[], raw: boolean): void {
|
|
const recordPath = typeof args[2] === 'string' ? args[2] : '';
|
|
if (!recordPath) {
|
|
error('tdd-red-evidence requires a record path: check tdd-red-evidence <record.json>', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
const resolved = path.resolve(recordPath);
|
|
const text = readIfExists(resolved);
|
|
const input = ((): Record<string, unknown> | null => {
|
|
if (!text) return null;
|
|
try {
|
|
return (JSON.parse(text) ?? {}) as Record<string, unknown>;
|
|
} catch {
|
|
return null;
|
|
}
|
|
})();
|
|
if (!input) {
|
|
output(
|
|
{
|
|
passed: false,
|
|
block: true,
|
|
verdict: 'INVALID_RED',
|
|
reason: 'unreadable_record',
|
|
record: resolved,
|
|
readError: text ? `record is not valid JSON: ${resolved}` : `record not found or unreadable: ${resolved}`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
const evidenceInput = {
|
|
command: input['command'],
|
|
exitCode: input['exitCode'],
|
|
output: input['output'],
|
|
targetTest: input['targetTest'],
|
|
targetFile: input['targetFile'],
|
|
expected: input['expected'],
|
|
actual: input['actual'],
|
|
};
|
|
const result = classifyRedEvidence(evidenceInput);
|
|
const record = buildRedEvidenceRecord(evidenceInput, result);
|
|
output(
|
|
{
|
|
// Uniform gate contract: block = !passed. INVALID_RED blocks GREEN.
|
|
passed: result.verdict === 'RED_EVIDENCE_OK',
|
|
block: result.verdict !== 'RED_EVIDENCE_OK',
|
|
verdict: result.verdict,
|
|
reason: result.reason,
|
|
evidence: result.evidence,
|
|
record,
|
|
message:
|
|
result.verdict === 'RED_EVIDENCE_OK'
|
|
? `RED evidence verified: target test "${result.evidence.target_test}" failed as expected (exit ${result.evidence.exit_code}). GREEN authorized.`
|
|
: `INVALID_RED (${result.reason}): GREEN blocked. Fix the RED phase — only an intentional failure of target test "${result.evidence.target_test}" authorizes production edits.`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Resolve a phase argument to an absolute phase directory, or '' when it
|
|
* cannot be resolved. Shared by every `check` arm that probes a phase's
|
|
* PLAN.md files, so the two never drift (DEFECT.GENERATIVE-FIX-DIVERGENCE).
|
|
* Never throws — the callers emit a degraded JSON payload instead, because
|
|
* a consumer must be able to tell "nothing to report" from "could not look".
|
|
*/
|
|
function resolvePhaseDirOrEmpty(projectDir: string, phase: string): string {
|
|
try {
|
|
const result = findPhaseInternal(projectDir, phase);
|
|
if (result && typeof result === 'object') {
|
|
// findPhaseInternal returns { directory: '<relative-posix-path>', ... }
|
|
// directory is relative to cwd — resolve it to absolute.
|
|
const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
|
|
if (relDir) {
|
|
return path.resolve(projectDir, relDir);
|
|
}
|
|
} else if (typeof result === 'string') {
|
|
return result;
|
|
}
|
|
} catch { /* phase dir lookup failure → caller emits degraded payload */ }
|
|
return '';
|
|
}
|
|
|
|
// ─── verify-command-paths (#2401) ──────────────────────────────────────────────
|
|
|
|
/**
|
|
* verify-command-paths: probes every `<automated>` verify command declared in a
|
|
* phase's `-PLAN.md` files against the filesystem WITHOUT executing anything —
|
|
* see verify-command-grounding.cjs for the recognizer contract.
|
|
*
|
|
* Args: check verify-command-paths <phase>
|
|
* Invocable as: gsd_run check verify-command-paths <phase>
|
|
*
|
|
* When the phase cannot be resolved to a directory, this emits a non-throwing
|
|
* degraded JSON payload (status/commands/counts all zeroed, `readError`
|
|
* populated) rather than calling `error()` — the plan-checker parses this
|
|
* result and must be able to distinguish "nothing to report" from "could not
|
|
* look", which a non-zero exit / thrown error would collapse.
|
|
*/
|
|
function cmdVerifyCommandPaths(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'verify-command-paths', args[2] = phase
|
|
const phase = args[2] || '';
|
|
if (!phase) {
|
|
output(
|
|
{
|
|
status: 'unresolvable',
|
|
commands: [],
|
|
counts: { blocker: 0, warning: 0, total: 0 },
|
|
readError: 'verify-command-paths requires a phase argument: check verify-command-paths <phase>',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
|
|
|
|
if (!phaseDir) {
|
|
output(
|
|
{
|
|
status: 'unresolvable',
|
|
commands: [],
|
|
counts: { blocker: 0, warning: 0, total: 0 },
|
|
readError: `could not resolve phase directory for phase ${phase}`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const probed = probePhaseVerifyCommands({ phaseDir, projectRoot: projectDir });
|
|
output(probed, raw, undefined);
|
|
}
|
|
|
|
// ─── verify-failure-directions (#3172) ─────────────────────────────────────────
|
|
|
|
/**
|
|
* verify-failure-directions: probes every `<automated>` verify command
|
|
* declared in a phase's `-PLAN.md` files for a stated `<fails_when>` failing
|
|
* direction — see verify-command-grounding.cjs for the recognizer contract.
|
|
*
|
|
* Args: check verify-failure-directions <phase>
|
|
* Invocable as: gsd_run check verify-failure-directions <phase>
|
|
*
|
|
* When the phase cannot be resolved to a directory, this emits a non-throwing
|
|
* degraded JSON payload (status/commands/counts all zeroed, `readError`
|
|
* populated) rather than calling `error()` — the plan-checker parses this
|
|
* result and must be able to distinguish "nothing to report" from "could not
|
|
* look", which a non-zero exit / thrown error would collapse.
|
|
*/
|
|
function cmdVerifyFailureDirections(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'verify-failure-directions', args[2] = phase
|
|
const phase = args[2] || '';
|
|
if (!phase) {
|
|
output(
|
|
{
|
|
status: 'unresolvable',
|
|
commands: [],
|
|
counts: { blocker: 0, warning: 0, total: 0 },
|
|
readError: 'verify-failure-directions requires a phase argument: check verify-failure-directions <phase>',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const phaseDir = resolvePhaseDirOrEmpty(projectDir, phase);
|
|
|
|
if (!phaseDir) {
|
|
output(
|
|
{
|
|
status: 'unresolvable',
|
|
commands: [],
|
|
counts: { blocker: 0, warning: 0, total: 0 },
|
|
readError: `could not resolve phase directory for phase ${phase}`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const result = probePhaseFailingDirections({ phaseDir });
|
|
output(result, raw, undefined);
|
|
}
|
|
|
|
// ─── gap-analysis-plan-post ───────────────────────────────────────────────────
|
|
|
|
/**
|
|
* gap-analysis-plan-post: non-blocking advisory check that runs the post-planning
|
|
* gap analysis after all PLAN.md files are generated for a phase.
|
|
*
|
|
* Cross-references every REQ-ID and D-ID from REQUIREMENTS.md and CONTEXT.md
|
|
* against the concatenated text of all *-PLAN.md files, emitting a coverage table.
|
|
*
|
|
* This gate is always advisory (passed: true) — it never blocks phase advancement.
|
|
*
|
|
* Args: check gap-analysis.plan-post <phase-dir> [phase-req-ids]
|
|
* Invocable as: gsd_run check gap-analysis.plan-post <phase-dir> [phase-req-ids]
|
|
*/
|
|
function cmdGapAnalysisPlanPost(projectDir: string, args: string[], raw: boolean): void {
|
|
// args[0] = 'check', args[1] = 'gap-analysis-plan-post' (normalized), args[2] = phaseDir, args[3] = phaseReqIds
|
|
const phaseDir = args[2] || '';
|
|
if (!phaseDir) {
|
|
error('gap-analysis.plan-post requires a phase-dir argument: check gap-analysis.plan-post <phase-dir> [phase-req-ids]', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
const phaseReqIds = args[3] ?? undefined;
|
|
const result = runGapAnalysis(projectDir, phaseDir, { phaseReqIds });
|
|
// Uniform gate contract: block = false (gap-analysis is always advisory, never blocks).
|
|
// `message` carries the human-readable gap analysis report so the dispatch's
|
|
// advisory branch can surface it. --raw emits JSON (rawValue=undefined), not
|
|
// plain markdown text.
|
|
output(
|
|
{
|
|
block: false,
|
|
passed: true,
|
|
enabled: result.enabled,
|
|
table: result.table,
|
|
summary: result.summary,
|
|
counts: result.counts,
|
|
// Human-readable report in `message` for the host-loop advisory branch.
|
|
message: result.table || result.summary || '',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
}
|
|
|
|
interface RouteCheckCommandOptions {
|
|
args: string[];
|
|
cwd: string;
|
|
raw: boolean;
|
|
}
|
|
|
|
// ─── predicate (generic gate-predicate evaluator, #2008) ──────────────────────
|
|
|
|
/**
|
|
* Production subprocess binding for the gate-predicate evaluator. Wraps the
|
|
* bounded `execTool` seam (shell-command-projection) as a `runBoundedShell`
|
|
* the pure evaluator consumes. `sh -c` runs the interpolated command; the
|
|
* subprocess inherits the process env and is killed (SIGTERM) on timeout.
|
|
*
|
|
* `timedOut` is derived from the kill signal: spawnSync sets `signal: 'SIGTERM'`
|
|
* when the `timeout` fires, distinct from a normal non-zero exit code. A command
|
|
* that self-terminates with SIGTERM is indistinguishable at this seam and is
|
|
* reported as a timeout — either way the gate blocks (non-zero), so the outcome
|
|
* is fail-closed and correct. See ADR-2008.
|
|
*/
|
|
function buildPredicateDeps() {
|
|
return {
|
|
runBoundedShell(opts: { command: string; cwd: string; timeoutMs: number }): {
|
|
exitCode: number | null;
|
|
stdout: string;
|
|
stderr: string;
|
|
signal: NodeJS.Signals | null;
|
|
timedOut: boolean;
|
|
} {
|
|
const r = execTool('sh', ['-c', opts.command], { cwd: opts.cwd, timeout: opts.timeoutMs });
|
|
return {
|
|
exitCode: r.exitCode,
|
|
stdout: r.stdout,
|
|
stderr: r.stderr,
|
|
signal: r.signal,
|
|
timedOut: r.timedOut,
|
|
};
|
|
},
|
|
findPhaseArtifact(phaseDir: string, artifactSuffix: string): string | null {
|
|
if (!fs.existsSync(phaseDir)) return null;
|
|
if (
|
|
artifactSuffix === '.' ||
|
|
artifactSuffix === '..' ||
|
|
artifactSuffix.includes('\0') ||
|
|
path.basename(artifactSuffix) !== artifactSuffix ||
|
|
path.win32.basename(artifactSuffix) !== artifactSuffix
|
|
) {
|
|
return null;
|
|
}
|
|
const directPath = validatePath(artifactSuffix, phaseDir);
|
|
if (directPath.safe && fs.existsSync(directPath.resolved) && fs.statSync(directPath.resolved).isFile()) {
|
|
return directPath.resolved;
|
|
}
|
|
const planningPath = validatePath(path.join('.planning', artifactSuffix), phaseDir);
|
|
if (planningPath.safe && fs.existsSync(planningPath.resolved) && fs.statSync(planningPath.resolved).isFile()) {
|
|
return planningPath.resolved;
|
|
}
|
|
try {
|
|
const files = fs.readdirSync(phaseDir);
|
|
for (const f of files) {
|
|
if (f.endsWith('-' + artifactSuffix) || f === artifactSuffix) {
|
|
const candidate = validatePath(f, phaseDir);
|
|
if (candidate.safe && fs.statSync(candidate.resolved).isFile()) return candidate.resolved;
|
|
}
|
|
}
|
|
} catch { /* ignore */ }
|
|
return null;
|
|
},
|
|
readFrontmatter(filePath: string): Record<string, unknown> {
|
|
const content = platformReadSync(filePath);
|
|
if (content === null) throw new Error(`predicate artifact disappeared before it could be read: ${filePath}`);
|
|
const parsed = extractFrontmatter(content, filePath) as Record<string, unknown>;
|
|
return parsed;
|
|
}
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Split an args array into `--flag value` pairs and the leftover positional
|
|
* tokens, in ONE pass, with the semantics `check predicate` established
|
|
* (#2008): a `--flag` followed by a non-`--` token consumes it as the value
|
|
* (last write wins); a `--flag` with no value stays a bare token and moves to
|
|
* the positionals; everything else is positional. `parsePredicateFlags` is
|
|
* the flags half of this same pass — there is exactly one parser, so the
|
|
* flag-taking check verbs cannot drift apart (#4130 follow-up: `check
|
|
* decision-coverage-plan --context <path>` shares it).
|
|
*/
|
|
function partitionPredicateArgs(args: string[]): { flags: Record<string, string>; positionals: string[] } {
|
|
const flags: Record<string, string> = {};
|
|
const positionals: string[] = [];
|
|
for (let i = 0; i < args.length; i++) {
|
|
const a = args[i];
|
|
if (typeof a !== 'string') continue;
|
|
if (!a.startsWith('--')) {
|
|
positionals.push(a);
|
|
continue;
|
|
}
|
|
const key = a.slice(2);
|
|
const next = args[i + 1];
|
|
if (key.length > 0 && typeof next === 'string' && !next.startsWith('--')) {
|
|
flags[key] = next;
|
|
i++;
|
|
} else {
|
|
positionals.push(a);
|
|
}
|
|
}
|
|
return { flags, positionals };
|
|
}
|
|
|
|
/** Parse `--flag value` pairs from an args array into a map (last write wins). */
|
|
function parsePredicateFlags(args: string[]): Record<string, string> {
|
|
return partitionPredicateArgs(args).flags;
|
|
}
|
|
|
|
/**
|
|
* `check predicate` — generic evaluator for capability gate `check.predicate`
|
|
* blocks (#2008). The workflow gate-dispatch invokes this for any gate whose
|
|
* `check` carries a `predicate` (instead of a `query`); the predicate object is
|
|
* passed as `--predicate '<json>'`. Emits the standard `{ block, message,
|
|
* details? }` gate contract on success. A malformed predicate / unknown kind
|
|
* THROWS inside the evaluator and is mapped here to `error()` (non-zero exit),
|
|
* which the workflow's two-step gate contract treats as a step-1 command failure
|
|
* routed per the gate's `onError`.
|
|
*
|
|
* Invocation:
|
|
* gsd_run check predicate --predicate '<json>' \
|
|
* [--phase-dir <dir>] [--phase-number <n>] [--phase-req-ids <ids>] --raw
|
|
*
|
|
* The subprocess runs at the runtime project root (the `cwd` passed to this
|
|
* router), inheriting the process env. Interpolation placeholders
|
|
* ${PHASE_NUMBER}/${PHASE_DIR}/${PHASE_REQ_IDS} are substituted from the flags.
|
|
*/
|
|
function cmdCheckPredicate(projectDir: string, args: string[], raw: boolean): void {
|
|
const flags = parsePredicateFlags(args);
|
|
const predicateJson = flags['predicate'];
|
|
if (!predicateJson) {
|
|
error('predicate requires --predicate <json> (the gate hook check.predicate object)', ERROR_REASON.SDK_MISSING_ARG);
|
|
return;
|
|
}
|
|
let predicate: unknown;
|
|
try {
|
|
predicate = JSON.parse(predicateJson);
|
|
} catch {
|
|
error('predicate --predicate value must be valid JSON', ERROR_REASON.USAGE);
|
|
return;
|
|
}
|
|
const ctx = {
|
|
cwd: projectDir,
|
|
phaseNumber: flags['phase-number'],
|
|
phaseDir: flags['phase-dir'],
|
|
phaseReqIds: flags['phase-req-ids'],
|
|
};
|
|
let result;
|
|
try {
|
|
result = evaluatePredicate(predicate, ctx, buildPredicateDeps());
|
|
} catch (e) {
|
|
error(`gate predicate evaluation failed: ${(e as Error).message}`, ERROR_REASON.USAGE);
|
|
return;
|
|
}
|
|
output(result, raw, undefined);
|
|
}
|
|
|
|
// ─── api-coverage-verify-pre ──────────────────────────────────────────────────
|
|
|
|
/**
|
|
* api-coverage.verify-pre: BLOCKING seal-time gate for the ai-integration
|
|
* capability (#1562). Enforces "Full API Coverage by Default — Opt Out, Never
|
|
* Opt In." A phase that integrates an external API/SDK/service may not seal
|
|
* until a COVERAGE.md matrix enumerates the surface and every non-integrated
|
|
* capability is an explicit, reasoned opt-out.
|
|
*
|
|
* Contract (two touch points composed into one check):
|
|
* 1. If COVERAGE.md exists in the phase dir → validate it (acceptance #2).
|
|
* Block on any validation error (empty matrix, OPT-OUT without reason,
|
|
* duplicate/empty capability).
|
|
* 2. If COVERAGE.md is absent → run detectApiIntegration over the phase scope
|
|
* (PLAN.md body, then ROADMAP phase section as fallback). If a strong
|
|
* external-API-integration signal is detected → BLOCK ("integration
|
|
* detected without coverage matrix"). If no signal → PASS (treat as a
|
|
* non-API phase; acceptance #4 — low false positives).
|
|
*
|
|
* The detector is the FALLBACK for the "nobody decided / forgot the matrix"
|
|
* case; the primary path is the plan:pre contribution prompting COVERAGE.md.
|
|
*
|
|
* Args: check api-coverage.verify-pre <phase-dir>
|
|
* Emits the uniform gate contract: { block, passed, message, ...details }.
|
|
*/
|
|
function cmdApiCoverageVerifyPre(projectDir: string, args: string[], raw: boolean): void {
|
|
const phaseArg = typeof args[2] === 'string' ? args[2] : '';
|
|
if (!phaseArg) {
|
|
error(
|
|
'api-coverage.verify-pre requires a phase argument: check api-coverage.verify-pre <phase-dir-or-token>',
|
|
ERROR_REASON.SDK_MISSING_ARG,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const pDir = planningDir(projectDir);
|
|
const phasesRoot = path.join(pDir, 'phases');
|
|
|
|
// SECURITY (path traversal): the phase argument is taken ONLY as a phase
|
|
// token — its basename — and resolved by findPhaseInternal strictly under
|
|
// .planning/phases/ (or a milestone archive). The raw arg is never used as a
|
|
// path, so `..`, absolute paths, and arbitrary directories cannot reach a
|
|
// file read. Mirrors cmdVerifySchemaDrift's token-match approach.
|
|
let token = posixNormalize(phaseArg).split('/').filter(Boolean).pop() || '';
|
|
// A token like ".." or "." carries no phase identity → unresolvable.
|
|
if (token === '.' || token === '..') token = '';
|
|
|
|
// Not a GSD project (no phases tree at all) → fail-open: nothing to gate.
|
|
if (!fs.existsSync(phasesRoot)) {
|
|
output(
|
|
{
|
|
block: false,
|
|
passed: true,
|
|
coverage_present: false,
|
|
detected: false,
|
|
message: 'api-coverage: no .planning/phases directory; gate skipped (not a GSD project layout)',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// Resolve the phase dir under the contained phases root.
|
|
let resolvedDir: string | null = null;
|
|
let phaseNumber = '';
|
|
if (token) {
|
|
const found = findPhaseInternal(projectDir, token);
|
|
if (found && found.directory) {
|
|
resolvedDir = found.directory;
|
|
phaseNumber = found.phase_number || '';
|
|
}
|
|
}
|
|
|
|
if (!resolvedDir) {
|
|
// The phases tree EXISTS but THIS phase could not be resolved. For a
|
|
// BLOCKING gate, fail-closed: a missing phase dir must not silently bypass
|
|
// the coverage requirement. (Distinguished from "no .planning at all"
|
|
// above, which is a genuine non-GSD-project → pass.)
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
detected: false,
|
|
phase_lookup_failed: true,
|
|
message:
|
|
`api-coverage: could not resolve phase "${phaseArg}" under .planning/phases/. ` +
|
|
'Resolve the phase directory (or produce COVERAGE.md) before sealing.',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// Defense-in-depth: the resolved dir must be inside the phases root (or a
|
|
// milestone archive under .planning/milestones).
|
|
const milestonesRoot = path.join(pDir, 'milestones');
|
|
if (!isInsideRoot(resolvedDir, phasesRoot) && !isInsideRoot(resolvedDir, milestonesRoot)) {
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
detected: false,
|
|
message: 'api-coverage: resolved phase dir escapes .planning/ — refusing to evaluate',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// (1) locate COVERAGE.md — prefer the exact name, then a single *-COVERAGE.md.
|
|
let coverageFile = '';
|
|
let suffixed: string[] = [];
|
|
try {
|
|
const entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
|
|
const files = entries.filter((e) => e.isFile()).map((e) => e.name);
|
|
const exact = files.find((f) => /^COVERAGE\.md$/i.test(f));
|
|
if (exact) {
|
|
coverageFile = exact;
|
|
} else {
|
|
suffixed = files.filter((f) => /-COVERAGE\.md$/i.test(f)).sort();
|
|
if (suffixed.length === 1) coverageFile = suffixed[0];
|
|
}
|
|
} catch {
|
|
// readdir failure → treat as no matrix readable; fall through to detection.
|
|
}
|
|
|
|
if (coverageFile) {
|
|
let matrixText: string;
|
|
try {
|
|
matrixText = fs.readFileSync(path.join(resolvedDir, coverageFile), 'utf8');
|
|
} catch {
|
|
// COVERAGE.md exists but is unreadable (EACCES/EIO/encoding). Fail-closed
|
|
// with a useful message rather than a raw throw.
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: true,
|
|
message: `api-coverage: COVERAGE.md exists but is unreadable — fix file permissions/encoding before sealing`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
const v = validateCoverageMatrix(matrixText);
|
|
if (v.valid) {
|
|
if (v.none_declared) {
|
|
// The declaration is the human override for the detector — it PASSES
|
|
// even when detection fires (that is acceptance #5's point: the
|
|
// detector is fallible and the declaration is the reasoned overrule).
|
|
// But a contradiction must be VISIBLE, not silent: re-run detection
|
|
// over the phase scope and surface any signals it still finds
|
|
// (#2365 review S-1).
|
|
const declScope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
|
|
const declDetection = detectApiIntegration(declScope.text);
|
|
const declSignals = declDetection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
|
|
// The declaration legitimately wins even over a read error (it is the
|
|
// human overrule), but if scope was incomplete we say so — the contract
|
|
// is that contradictions stay visible, not silent (#2365 review).
|
|
const baseMsg = declDetection.detected
|
|
? `api-coverage: COVERAGE.md declares no external API integration, overriding ${declSignals.length} detected signal(s) — confirm the declaration is accurate`
|
|
: 'api-coverage: COVERAGE.md declares no external API integration — matrix not required';
|
|
output(
|
|
{
|
|
block: false,
|
|
passed: true,
|
|
coverage_present: true,
|
|
matrix: coverageFile,
|
|
counts: v.counts,
|
|
none_declared: true,
|
|
detected: declDetection.detected,
|
|
...(declDetection.detected ? { signals: declSignals } : {}),
|
|
...(declScope.readError ? { scope_read_error: declScope.readError } : {}),
|
|
message: declScope.readError
|
|
? `${baseMsg} (note: phase scope was incompletely read — ${declScope.readError})`
|
|
: baseMsg,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
output(
|
|
{
|
|
block: false,
|
|
passed: true,
|
|
coverage_present: true,
|
|
matrix: coverageFile,
|
|
counts: v.counts,
|
|
message: `api-coverage: matrix present (${v.counts.surface} capabilities, ${v.counts.optout} opt-out)`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
// Fixed-template message (no raw cell content echoed into the LLM-facing
|
|
// message). The structured `errors` array is safe (row-indexed, no cell
|
|
// values) and travels as data for tooling that wants detail.
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: true,
|
|
matrix: coverageFile,
|
|
error_count: v.errors.length,
|
|
errors: v.errors,
|
|
message: `api-coverage: COVERAGE.md has ${v.errors.length} problem(s) — fix the matrix (every capability INTEGRATE or OPT-OUT with a reason) before sealing`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
if (suffixed.length > 1) {
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
message: `api-coverage: multiple *-COVERAGE.md files found (${suffixed.length}) — consolidate into one COVERAGE.md before sealing`,
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// (2) no matrix — detect whether this phase integrates an external API.
|
|
const scope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
|
|
if (scope.readError) {
|
|
// Fail-closed: an unreadable plan could be the one describing the
|
|
// integration, so we cannot certify "no integration" — block and surface it.
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
detected: false,
|
|
message:
|
|
`api-coverage: could not read the phase scope (${scope.readError}); ` +
|
|
'refusing to certify no external-API integration from incomplete scope. ' +
|
|
'Fix the unreadable plan file, or add a COVERAGE.md declaration.',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
// An EMPTY scope is not a negative verdict. This gate's neighbouring arms
|
|
// already fail closed (unresolvable phase → block; unreadable plan → block),
|
|
// but a phase with no plan body AND no roadmap section fell through to
|
|
// detection over zero bytes and CERTIFIED "no external-API integration" —
|
|
// clearing a blocking seal gate on a probe that examined nothing
|
|
// (ADR-3889 failure class (c), #3909). The discriminator is BYTES EXAMINED,
|
|
// never SIGNALS FOUND: a phase with real plans and no API vocabulary still
|
|
// reaches the pass below unchanged.
|
|
if (scope.text.trim() === '') {
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
detected: false,
|
|
scope_unavailable: true,
|
|
message:
|
|
'api-coverage: the phase scope is empty — no plan body and no roadmap section were ' +
|
|
'found, so nothing was examined. Refusing to certify no external-API integration ' +
|
|
'from an unestablished scope. Add the phase plan, or add a COVERAGE.md declaration.',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
const detection = detectApiIntegration(scope.text);
|
|
if (detection.detected) {
|
|
// Surface only verb/noun (typed, bounded) — NOT raw prose snippets — so the
|
|
// gate output cannot relay injected PLAN.md instructions to the orchestrator.
|
|
const signals = detection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
|
|
output(
|
|
{
|
|
block: true,
|
|
passed: false,
|
|
coverage_present: false,
|
|
detected: true,
|
|
signals,
|
|
message:
|
|
'api-coverage: external-API integration detected without a coverage matrix. ' +
|
|
'Produce COVERAGE.md enumerating the API surface (every capability INTEGRATE or ' +
|
|
'OPT-OUT with a reason) before sealing. Full coverage is the default.',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
return;
|
|
}
|
|
|
|
output(
|
|
{
|
|
block: false,
|
|
passed: true,
|
|
coverage_present: false,
|
|
detected: false,
|
|
message: 'api-coverage: no external-API integration detected; coverage matrix not required',
|
|
},
|
|
raw,
|
|
undefined,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Read the phase-scope text used for API-integration detection. Uses the
|
|
* resolved plan files (PLAN.md bodies — the planner's own words about what the
|
|
* phase does) and, as a fallback, ONLY THIS PHASE'S ROADMAP section (not the
|
|
* whole roadmap, which would cross-contaminate sibling phases). Strips nothing
|
|
* here — detectApiIntegration strips fenced code itself.
|
|
*/
|
|
interface PhaseScopeRead {
|
|
text: string;
|
|
/** Non-null when a plan file EXISTED but could not be read. The gate must not
|
|
* conclude "no external API integration" from provably incomplete scope — an
|
|
* unreadable plan could be the one describing the integration (#2365 review:
|
|
* the blocking consumer silently passed partially-read scope). A missing plan
|
|
* directory is NOT a read error (a phase may legitimately have no plans yet). */
|
|
readError: string | null;
|
|
}
|
|
|
|
/** A filesystem error that is NOT "does not exist" — i.e. a real read failure
|
|
* (EACCES/EIO/…) the gate must not swallow. `ENOENT` is a legitimate "not
|
|
* there yet" and is treated as absence, not error. */
|
|
function isRealReadFailure(err: unknown): boolean {
|
|
const code = (err as NodeJS.ErrnoException | undefined)?.code;
|
|
return err != null && code !== 'ENOENT';
|
|
}
|
|
|
|
function readPhaseScope(projectDir: string, phaseDir: string, phaseNumber: string): PhaseScopeRead {
|
|
const chunks: string[] = [];
|
|
let readError: string | null = null;
|
|
// A MISSING phase directory is fine (no plans yet → fall through to the
|
|
// roadmap). Checked up front (rather than via a readdirSync catch) because
|
|
// #3183 (lint-plan-count-drift) now sources the plan-file list from the
|
|
// single owner (scanPhasePlans) instead of a local `-PLAN\.md$` readdirSync
|
|
// filter — picks up bare PLAN.md and nested plans/, and excludes
|
|
// superseded plans, none of which the prior root-only exact-suffix filter
|
|
// did.
|
|
if (fs.existsSync(phaseDir)) {
|
|
const scan = scanPhasePlans(phaseDir);
|
|
if (scan.scope === SCOPE.UNREADABLE) {
|
|
// Directory exists but scanPhasePlans's own readdirSync(phaseDir) call
|
|
// failed (EACCES/EIO race) — a real read failure the gate must not
|
|
// silently pass (#2365 review), mirroring the prior isRealReadFailure
|
|
// branch below for the readdirSync-throws case.
|
|
return {
|
|
text: '',
|
|
readError: 'could not read the phase directory: scanPhasePlans reported scope UNREADABLE',
|
|
};
|
|
}
|
|
const plans = [...scan.planFiles].sort();
|
|
for (const p of plans) {
|
|
try {
|
|
chunks.push(fs.readFileSync(path.join(phaseDir, p), 'utf8'));
|
|
} catch (err) {
|
|
// A plan file that exists but cannot be read — record it and keep
|
|
// reading the rest so the message names the first failure.
|
|
if (!readError) {
|
|
readError = `could not read ${p}: ${err instanceof Error ? err.message : String(err)}`;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
if (readError) return { text: chunks.join('\n\n'), readError };
|
|
if (chunks.join('').trim().length > 0) return { text: chunks.join('\n\n'), readError: null };
|
|
|
|
// Fallback: ONLY this phase's ROADMAP section (not the whole file, which
|
|
// would pollute detection with sibling-phase prose). A MISSING roadmap/section
|
|
// is non-fatal; a roadmap that exists but cannot be read is a real failure.
|
|
if (phaseNumber) {
|
|
try {
|
|
const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
|
|
if (section) return { text: section, readError: null };
|
|
} catch (err) {
|
|
if (isRealReadFailure(err)) {
|
|
return {
|
|
text: '',
|
|
readError: `could not read the roadmap fallback: ${err instanceof Error ? err.message : String(err)}`,
|
|
};
|
|
}
|
|
}
|
|
}
|
|
return { text: '', readError: null };
|
|
}
|
|
|
|
function routeCheckCommand({ args, cwd, raw }: RouteCheckCommandOptions): void {
|
|
// Normalize dots to hyphens in the subcommand so both forms are accepted.
|
|
// This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
|
|
// directly runnable as `gsd_run check ui.plan-gate` — the dot is normalized to
|
|
// `ui-plan-gate` before routing. The generic gate-dispatch in §5.6 reads
|
|
// `check.query` from the active gate hook and runs `gsd_run check ${hook.check.query}`,
|
|
// so the declared query must be dispatchable exactly as declared.
|
|
const rawSubcommand = args[1];
|
|
const subcommand = typeof rawSubcommand === 'string' ? rawSubcommand.replace(/\./g, '-') : rawSubcommand;
|
|
if (subcommand === 'auto-mode') {
|
|
cmdAutoMode(cwd, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'decision-coverage-plan') {
|
|
cmdDecisionCoveragePlan(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'decision-coverage-verify') {
|
|
cmdDecisionCoverageVerify(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'ui-plan-gate') {
|
|
cmdUiPlanGate(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'gap-analysis-plan-post') {
|
|
cmdGapAnalysisPlanPost(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'verify-command-paths') {
|
|
// Deterministic filesystem probe for <automated> verify commands (#2401) —
|
|
// never executes anything; see verify-command-grounding.cjs.
|
|
cmdVerifyCommandPaths(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'verify-failure-directions') {
|
|
// Presence probe for a stated <fails_when> per <automated> command
|
|
// (#3172) — never executes anything; see verify-command-grounding.cjs.
|
|
cmdVerifyFailureDirections(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'api-coverage-verify-pre') {
|
|
// ai-integration capability blocking gate at verify:pre (#1562). Dot-to-
|
|
// hyphen normalization means query "api-coverage.verify-pre" routes here.
|
|
cmdApiCoverageVerifyPre(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'tdd-review-checkpoint') {
|
|
cmdTddReviewCheckpoint(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'tdd-red-evidence') {
|
|
// #3770: intentional-RED evidence gate — only a target-test failure may
|
|
// authorize GREEN. Validates the persisted record; never executes anything.
|
|
cmdTddRedEvidence(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'ui-safety-gate') {
|
|
cmdUiSafetyGate(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'verify-schema-drift') {
|
|
// Delegates to verify.schema-drift — drift capability gate at execute:wave:post (blocking).
|
|
// Dot-to-hyphen normalization means query "verify.schema-drift" routes here.
|
|
// Honor GSD_SKIP_SCHEMA_CHECK=true to bypass the gate (preserves the original inline gate behavior).
|
|
const phaseArg = typeof args[2] === 'string' ? args[2] : '';
|
|
const skipSchemaCheck = process.env['GSD_SKIP_SCHEMA_CHECK'] === 'true';
|
|
cmdVerifySchemaDrift(cwd, phaseArg, skipSchemaCheck, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'verify-codebase-drift') {
|
|
// Delegates to verify.codebase-drift — drift capability gate at execute:wave:post (non-blocking).
|
|
// Dot-to-hyphen normalization means query "verify.codebase-drift" routes here.
|
|
cmdVerifyCodebaseDrift(cwd, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'verify-context-drift') {
|
|
// Delegates to verify.context-drift — drift capability gate at plan:pre (non-blocking).
|
|
// Dot-to-hyphen normalization means query "verify.context-drift" routes here.
|
|
const phaseArg = typeof args[2] === 'string' ? args[2] : '';
|
|
cmdVerifyContextDrift(cwd, phaseArg, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'predicate') {
|
|
// Generic gate-predicate evaluator (#2008). The workflow gate-dispatch calls
|
|
// this for any gate whose `check` carries a `predicate` (instead of a `query`),
|
|
// passing the predicate object as --predicate '<json>'. NOTE: unlike the
|
|
// `check.query` subcommands above (which take positional phase args), this
|
|
// subcommand is flag-driven. `decision-coverage-plan` above now ALSO accepts
|
|
// `--context <path>` (its positionals still work) — both share
|
|
// partitionPredicateArgs, the one flag parser.
|
|
cmdCheckPredicate(cwd, args, raw);
|
|
return;
|
|
}
|
|
if (subcommand === 'prohibition-enforcement') {
|
|
// The deterministic test-tier prohibition PRODUCER/gate (#1259, ADR-550 D5d). Locates the
|
|
// wired mechanical check (node-test or lint-rule), confirms fail-first, runs it, builds
|
|
// enforcementEvidence, and emits the dispositionForProhibition verdict. Invocable as
|
|
// `gsd_run check prohibition-enforcement <request.json>`.
|
|
routeProhibitionEnforcement(args, raw);
|
|
return;
|
|
}
|
|
error('Unknown check subcommand. Available: api-coverage-verify-pre, auto-mode, decision-coverage-plan, decision-coverage-verify, gap-analysis-plan-post, predicate, prohibition-enforcement, tdd-red-evidence, tdd-review-checkpoint, ui-plan-gate, ui-safety-gate, verify-command-paths, verify-failure-directions, verify-schema-drift, verify-codebase-drift, verify-context-drift', ERROR_REASON.SDK_UNKNOWN_COMMAND);
|
|
}
|
|
|
|
export = {
|
|
routeCheckCommand,
|
|
decisionMentioned,
|
|
extractPlanDesignatedSections,
|
|
computeUiPlanGate,
|
|
computeUiSafetyGate,
|
|
cmdGapAnalysisPlanPost,
|
|
cmdVerifyCommandPaths,
|
|
cmdVerifyFailureDirections,
|
|
cmdTddReviewCheckpoint,
|
|
cmdTddRedEvidence,
|
|
cmdCheckPredicate,
|
|
buildPredicateDeps,
|
|
parsePredicateFlags,
|
|
partitionPredicateArgs,
|
|
// Fail-closed phase-scope reader for the api-coverage gate — exported for
|
|
// in-process failure-injection tests (#2365 review).
|
|
readPhaseScope,
|
|
};
|