4a1ed2531f
* test(#3242): failing-first suite for the codex posture health-check Specifies ADR-2313 D6 before the implementation exists, so the tests bind to the contract rather than to whatever the code happens to do. RED is established by construction, not by a remote run: checkCodexModelPosture and POSTURE_REASON are absent from the compiled lib today, so every row fails on the missing export. A remote checkpoint here would prove only that the function is missing, which is already known — so the run is deliberately deferred to the combined green checkpoint rather than spent proving a tautology. That makes the NEGATIVE PROOFS the rows that carry real signal. Every positive row passes even for a naive implementation that greps /model\s*=/ over the whole file. Six rows fail it: light-tier service_tier/model_verbosity decoupling (#774), hand-added keys, a commented pin, the model_verbosity key-prefix collision, the runtime no-op ordering, and the headline case — a literal `model = "sonnet"` inside the developer_instructions ''' block, which the emitter fills with agent prompts that discuss models constantly. Row 14's fixture was verified to discriminate before being written: a whole-file scan matches it and a header-slice scan does not. Without that check the test would pass trivially and prove nothing, which is the vacuous-test failure this epic has already hit repeatedly. Adversarial TOML fixtures are hand-authored against the real Codex shape rather than generated by generateCodexAgentToml, per #2371 — a fixture from the writer can only confirm what the writer already believed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(#3242): validate codex .toml model posture, not just presence Implements ADR-2313 D6. checkCodexModelPosture is a new sibling export, not a branch inside checkAgentsInstalled — that function carries 33 upstream dependents, cyclomatic 25, and sits in two traced process flows, so it is deliberately left untouched. It imports isAnthropicFlavoredModel from model-catalog, a genuine leaf. That is what Phase 1's constant move bought: agent-install-check is documented as pure read/verify and imports only leaves, so reaching the rule through model-resolver would have dragged config-loader into it. Reads liberally, judges strictly, and never guesses. Tolerates comments, key order, whitespace, CRLF, and a BOM; anchors on full key names so model_verbosity does not satisfy a `model` probe; treats extra hand-added keys as none of its business, since the check is a predicate on the two fields the posture owns rather than a whitelist over the document. An unreadable file becomes a named violation and the loop keeps going. The scan covers only the header slice — the lines before the developer_instructions ''' marker. The emitter writes agent prompts into that block and GSD's prompts discuss models constantly, so a whole-file scan reports violations for prose. This is the highest-risk defect in the phase and the reason its fixture was verified to discriminate before being written. The non-codex short-circuit runs before any filesystem call, so a stray .toml under another runtime is never inspected. Wired through cmdValidateAgents as an additive codex_posture key, so a violating install is visible from a command a user actually runs rather than only from a library nothing calls. Also fixes a test defect found while implementing: .gitattributes forces `* text=auto eol=lf` repo-wide, so the committed CRLF fixture was normalized to LF in the index — `git ls-files --eol` reported `i/lf w/crlf`, the working copy being stale pre-normalization bytes. The CRLF row was asserting against a file that could not survive a fresh clone. CRLF is now derived at runtime, which puts it under the test's control rather than git's, instead of adding a .gitattributes exception that fights a deliberate repo-wide policy and that anyone could re-normalize. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(#3242): document the codex posture check where a user will look Three quadrants, filed by where the reader actually arrives. How-to (recover-and-troubleshoot.md, under Install and update problems) is titled by the SYMPTOM — "If Codex agents fail to spawn with a 400 about an unsupported model" — and opens with the verbatim error string. Someone hitting this does not know the words "posture" or "ADR-2313"; they have a 400 in their terminal and will search for that. Reference (COMMANDS.md) had no `validate agents` entry at all, though sibling gsd-tools subcommands are documented. Adding user-visible output to an undocumented command and then linking to it from the new how-to would have left a dangling reference. The entry carries the violation-reason table, since the frozen POSTURE_REASON enum is the machine-readable contract a reader needs rather than the prose. Both surfaces state that presence and posture are separate verdicts — a missing agent lands in `missing`, never as a posture violation. That is a deliberate design decision and would otherwise be invisible to someone watching one command emit both. Explanation stays in ADR-2313, which already covers D6 and the liberal-parse/strict-judge boundary. Pointing at it beats duplicating it into COMMANDS.md and creating two copies to drift. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3242): close two false negatives in the posture scan Both found by an isolated reviewer and reproduced before fixing. Both made the check report clean when it was not — the worst direction for this function, since the how-to tells users an empty violations list means the install is posture-clean. A quoted TOML key was never matched. `"model" = "sonnet"` is legal TOML, but the key pattern required a bare identifier, so the pin was silently invisible. Bare, "double" and 'single' quoted forms now normalize to the same key name. The block marker was found by unanchored whole-content search and used to truncate the header. A `description` value merely containing the literal text `developer_instructions = '''` truncated the scan before a real pin, and a user who hand-reordered `model` to sit after the block — still legal TOML — was never scanned at all. Fixed by changing the strategy rather than the regex: find the block's range, anchored at line start, and scan every line OUTSIDE it. That covers both failures and is strictly more correct than truncation, while still never reading prompt prose. An unterminated block excludes the rest of the file, which fails toward a false positive — the safe direction, since misreading prose as a pin wastes a user's time while the alternative hides a real one. Also corrects two overclaims of mine. The how-to named "v1.11", a version that does not exist — package.json is 1.10.0 and unreleased — so it now describes the boundary by behavior and links the ADR. And the test matrix asserted that a naive whole-file scan "fails exactly rows 12,13,14,15,16,25"; the reviewer computed that rows 12, 13, 15 and 16 produce the correct result against that baseline too. They guard real but *different* mistakes, and the matrix now says which one each catches instead of attributing them all to the header-slice defect. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#3242): skip symlinked agent files instead of following them Security review finding. The scan listed entries with readdirSync and read them with readFileSync, which follows symlinks — so a symlink in the agents directory pointing anywhere would have its contents read, and any line matching the model pattern echoed into cmdValidateAgents' output through the `value` field. A read-and-echo primitive on an arbitrary path. It needs write access to the agents directory, so it crosses no new trust boundary today. Fixed anyway, for two reasons. This repo already does it correctly next door: cmdEffortSync filters with lstatSync().isFile() and the comment "Skip symlinks — only write regular files to avoid clobbering symlink targets." Being inconsistent with a sibling in the same subsystem IS the defect. And Phase 3 (#3243) extends that same cmdEffortSync to WRITE these files. Establishing symlink-following as the house pattern for Codex .toml handling here would hand Phase 3 a worse starting point while it writes rather than reads. Skipped silently rather than reported, matching the sibling: a symlinked agent file is a structural install choice, which checkAgentsInstalled owns, not a model-content posture defect. An lstat that itself throws excludes the file rather than crashing the scan. That does narrow the guarantee slightly, so the how-to now says an empty list means every REGULAR .toml is clean, and tells anyone symlinking their configs to check the targets by hand. Claiming a clean bill of health over files the check declined to open would be the same kind of false confidence the two false negatives above produced. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#3242): backfill changeset pr number (#3290) --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2748 lines
111 KiB
TypeScript
2748 lines
111 KiB
TypeScript
/**
|
|
* Verify — Verification suite, consistency, and health validation
|
|
*
|
|
* ADR-457 build-at-publish: the hand-written bin/lib/verify.cjs collapsed to
|
|
* a TypeScript source of truth, compiled by tsc to a gitignored .cjs at the
|
|
* same require() path. Behaviour preserved byte-for-behaviour; only types are added.
|
|
*/
|
|
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import os from 'node:os';
|
|
import { phaseVariants, buildRoadmapPhaseVariants, buildNotStartedPhaseVariants } from './validate.cjs';
|
|
import { realClock } from './clock.cjs';
|
|
import { phaseDirNameRe, PHASE_TOKEN_FROM_DIR_RE, MILESTONE_ARCHIVE_DIR_RE, textEncodingError } from './validate.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
|
|
import planningWorkspace = require('./planning-workspace.cjs');
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
|
|
import frontmatterMod = require('./frontmatter.cjs');
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- state.cjs is an export= CommonJS module
|
|
import stateMod = require('./state.cjs');
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-profiles.cjs is an export= CommonJS module
|
|
import modelProfilesMod = require('./model-profiles.cjs');
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
|
|
import planScanMod = require('./plan-scan.cjs');
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
|
|
import coreUtilsMod = require('./core-utils.cjs');
|
|
const { findOrphanSummaries, findUnsummarizedPlans } = coreUtilsMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
|
|
import planningScopeMod = require('./planning-scope.cjs');
|
|
const { SCOPE } = planningScopeMod;
|
|
import { execGit, platformReadSync as safeReadFile, platformWriteSync, posixNormalize } from './shell-command-projection.cjs';
|
|
import { PACKAGE_NAME } from './package-identity.cjs';
|
|
import { formatGsdSlash, resolveRuntime } from './runtime-slash.cjs';
|
|
import { detectSchemaFiles, checkSchemaDrift } from './schema-detect.cjs';
|
|
import { isCanonicalPlanningFile } from './artifacts.cjs';
|
|
import { extractTaggedBlocks } from './markdown-sectionizer.cjs';
|
|
import { VALID_PROFILES, VALID_TIERS, VALID_PHASE_TYPES } from './model-catalog.cjs';
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- agent-install-check.cjs is an export= CommonJS module
|
|
import agentInstallCheck = require('./agent-install-check.cjs');
|
|
const { checkAgentsInstalled, checkCodexModelPosture } = agentInstallCheck;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import ioMod = require('./io.cjs');
|
|
const { output, error } = ioMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import configLoaderMod = require('./config-loader.cjs');
|
|
const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import phaseIdMod = require('./phase-id.cjs');
|
|
const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE, PHASE_NUMBER_TOKEN_SOURCE, extractPhaseToken, comparePhaseNum } = phaseIdMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import phaseLocatorMod = require('./phase-locator.cjs');
|
|
const { findPhaseInternal } = phaseLocatorMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import roadmapParserMod = require('./roadmap-parser.cjs');
|
|
const { getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone } = roadmapParserMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
import worktreeSafetyMod = require('./worktree-safety.cjs');
|
|
const { inspectWorktreeHealth } = worktreeSafetyMod;
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- commands.cjs is an export= CommonJS module
|
|
import commandsMod = require('./commands.cjs');
|
|
const { determinePhaseStatus } = commandsMod;
|
|
|
|
const { planningDir, planningRoot } = planningWorkspace;
|
|
const { extractFrontmatter, parseMustHavesBlock } = frontmatterMod;
|
|
const { writeStateMd } = stateMod;
|
|
const { MODEL_PROFILES } = modelProfilesMod;
|
|
|
|
// Unused but imported for structural parity
|
|
void stripShippedMilestones;
|
|
void detectSchemaFiles;
|
|
|
|
interface SummaryVerification {
|
|
passed: boolean;
|
|
checks: {
|
|
summary_exists: boolean;
|
|
files_created: { checked: number; found: number; missing: string[] };
|
|
commits_exist: boolean;
|
|
self_check: string;
|
|
};
|
|
errors: string[];
|
|
}
|
|
|
|
/**
|
|
* Pure core of `verify-summary` (#2572).
|
|
*
|
|
* Same artifact↔git checks the CLI verb has always run, lifted out of the
|
|
* `output()` wrapper so other verbs can consume the structured
|
|
* `{ passed, checks, errors }` contract directly instead of shelling out and
|
|
* re-parsing JSON. `cmdVerifySummary` is now a thin adapter over this.
|
|
*
|
|
* Never throws and never writes to stdout: a missing SUMMARY, a non-repo, or an
|
|
* unresolvable commit all come back as structured `false`/`missing` values.
|
|
*
|
|
* Caveat for callers surfacing `commits_exist`: the hash pattern is a loose
|
|
* `\b[0-9a-f]{7,40}\b`, so any hex-shaped token in the prose counts as a
|
|
* candidate. That is cheap as an advisory signal and unacceptable as a gate.
|
|
*
|
|
* @param checkFileCount How many extracted candidates to probe. Defaults to 2 —
|
|
* the value the CLI verb has always used. Pass `Infinity` to probe every
|
|
* candidate (see `cmdPhaseComplete`, which reports on all of them).
|
|
* @param opts.checkCommits When `false`, the `git cat-file` probes are skipped
|
|
* entirely and `commits_exist` comes back `false` meaning *not checked*.
|
|
* Callers that do not surface `commits_exist` should pass `false` so this
|
|
* stays a pure-filesystem check with no subprocess cost.
|
|
*/
|
|
function verifySummaryCore(
|
|
cwd: string,
|
|
summaryPath: string,
|
|
checkFileCount?: number,
|
|
opts?: { checkCommits?: boolean },
|
|
): SummaryVerification {
|
|
const fullPath = path.join(cwd, summaryPath);
|
|
const checkCount = checkFileCount || 2;
|
|
const checkCommits = opts?.checkCommits !== false;
|
|
|
|
if (!fs.existsSync(fullPath)) {
|
|
return {
|
|
passed: false,
|
|
checks: {
|
|
summary_exists: false,
|
|
files_created: { checked: 0, found: 0, missing: [] },
|
|
commits_exist: false,
|
|
self_check: 'not_found',
|
|
},
|
|
errors: ['SUMMARY.md not found'],
|
|
};
|
|
}
|
|
|
|
const content = fs.readFileSync(fullPath, 'utf-8');
|
|
const errors: string[] = [];
|
|
|
|
const projectRoot = path.resolve(cwd);
|
|
|
|
/**
|
|
* Is `candidate` plausibly a repo-relative file this check should probe?
|
|
*
|
|
* Deliberately narrowing. This is an ADVISORY, so the two error directions are
|
|
* not symmetric: a false positive tells a user their healthy project is
|
|
* missing a file that was never claimed, while a false negative just means one
|
|
* reference goes unprobed. Every rejection below is a noise class confirmed on
|
|
* #2685; when in doubt, skip rather than warn.
|
|
*/
|
|
const isProbableProjectFile = (candidate: string): boolean => {
|
|
// Only repo-relative paths — a bare filename is too ambiguous to locate.
|
|
if (!candidate.includes('/')) return false;
|
|
// URLs, protocol-relative links, and any other scheme.
|
|
if (candidate.startsWith('http') || candidate.startsWith('//')) return false;
|
|
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate)) return false;
|
|
// Globs name a set, not a file: `src/**/*.cts` is never "missing".
|
|
if (/[*?]/.test(candidate)) return false;
|
|
// Bare hostnames (`docs.example.com/guide.html`). A repo-relative path's
|
|
// first segment is a directory name, which in practice contains a dot only
|
|
// when it is a dotfile directory (`.github/`, `.changeset/`, `.planning/`)
|
|
// — i.e. the dot is at index 0. A dot anywhere later marks a hostname.
|
|
const firstSegment = candidate.split('/')[0] || '';
|
|
if (firstSegment.indexOf('.') > 0) return false;
|
|
// Containment guard: a `../`-bearing reference must not turn this advisory
|
|
// into a filesystem existence probe outside the project.
|
|
const resolved = path.resolve(projectRoot, candidate);
|
|
if (resolved !== projectRoot && !resolved.startsWith(projectRoot + path.sep)) return false;
|
|
return true;
|
|
};
|
|
|
|
// Pattern 2 excludes `[` and `]` from its path class (#2685 Blocker 1). All
|
|
// three SUMMARY templates prescribe a YAML flow sequence for `key-files`:
|
|
//
|
|
// key-files:
|
|
// created: [src/auth/login.ts, src/auth/session.ts]
|
|
//
|
|
// and the label matches `(?:Created|Modified|…):` case-insensitively. Without
|
|
// the bracket exclusion the class captures the literal `[` as part of the
|
|
// first path, yielding `[src/auth/login.ts` — a candidate that can never exist
|
|
// on disk. That fired on healthy projects built from GSD's own shipped
|
|
// template. The exclusion also stops a markdown list in the body from
|
|
// reintroducing the same artifact.
|
|
//
|
|
// Stripping frontmatter first was the other remedy offered on #2685. It is a
|
|
// verified no-op on top of this exclusion — measured identical extraction
|
|
// across all three shipped templates — because the exclusion already makes a
|
|
// flow-sequence line contribute nothing. Consequence worth naming: the
|
|
// `key-files` block, the most authoritative statement of what a phase created,
|
|
// is still not read. Recovering it needs a real frontmatter parse, which is
|
|
// deliberately left as a follow-up rather than smuggled in here.
|
|
const mentionedFiles = new Set<string>();
|
|
// #2844: Pattern 1 matches any backticked path-like token. A SUMMARY body is
|
|
// predominantly about what the phase DID, so a backticked path in prose ("Built
|
|
// `src/kept.ts`", a `- \`src/x.ts\`` list item) is a legitimate claim (#2685
|
|
// pins this). The false-positive class #2844 fixes is a path mentioned as a
|
|
// FUTURE/CONDITIONAL deliverable — "next phase will add `shared/types.ts`",
|
|
// "planned", "would", "to be created" — which is NOT a claim about this phase.
|
|
// Exclude those lines rather than requiring an explicit claim verb (which would
|
|
// drop the legitimate "Built …" / list-item forms #2685 protects).
|
|
const isFutureMention = (line: string): boolean =>
|
|
/\b(?:will(?:\s+(?:add|create|build|land))?(?:[^.])?|(?:next|later|future)\s+phase|planned?|would\s+(?:be|add|create|build)|to\s+be\s+(?:added|created|built)|eventually|not\s+yet)\b/i.test(line);
|
|
const patterns = [
|
|
/`([^`]+\.[a-zA-Z]+)`/g,
|
|
/(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`[\]]+\.[a-zA-Z]+)`?/gi,
|
|
];
|
|
|
|
for (const pattern of patterns) {
|
|
let m: RegExpExecArray | null;
|
|
while ((m = pattern.exec(content)) !== null) {
|
|
const filePath = m[1];
|
|
if (!filePath || !isProbableProjectFile(filePath)) continue;
|
|
// #2844: skip a backticked path on a future/conditional line — it names a
|
|
// deliverable this phase did NOT produce, so probing it is a false positive.
|
|
const lineStart = content.lastIndexOf('\n', m.index) + 1;
|
|
const lineEnd = content.indexOf('\n', m.index);
|
|
const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
|
|
if (isFutureMention(line)) continue;
|
|
mentionedFiles.add(filePath);
|
|
}
|
|
}
|
|
|
|
const filesToCheck = Array.from(mentionedFiles).slice(0, checkCount);
|
|
const missing: string[] = [];
|
|
for (const file of filesToCheck) {
|
|
if (!fs.existsSync(path.resolve(projectRoot, file))) {
|
|
missing.push(file);
|
|
}
|
|
}
|
|
|
|
const commitHashPattern = /\b[0-9a-f]{7,40}\b/g;
|
|
const hashes = checkCommits ? content.match(commitHashPattern) || [] : [];
|
|
let commitsExist = false;
|
|
if (hashes.length > 0) {
|
|
for (const hash of hashes.slice(0, 3)) {
|
|
const result = execGit(['cat-file', '-t', hash], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (result.exitCode === 0 && result.stdout.trim() === 'commit') {
|
|
commitsExist = true;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
let selfCheck = 'not_found';
|
|
const selfCheckPattern = /##\s*(?:Self[- ]?Check|Verification|Quality Check)/i;
|
|
if (selfCheckPattern.test(content)) {
|
|
const passPattern = /(?:all\s+)?(?:pass|✓|✅|complete|succeeded)/i;
|
|
const failPattern = /(?:fail|✗|❌|incomplete|blocked)/i;
|
|
const checkSection = content.slice(content.search(selfCheckPattern));
|
|
if (failPattern.test(checkSection)) {
|
|
selfCheck = 'failed';
|
|
} else if (passPattern.test(checkSection)) {
|
|
selfCheck = 'passed';
|
|
}
|
|
}
|
|
|
|
if (missing.length > 0) errors.push('Missing files: ' + missing.join(', '));
|
|
if (!commitsExist && hashes.length > 0)
|
|
errors.push('Referenced commit hashes not found in git history');
|
|
if (selfCheck === 'failed') errors.push('Self-check section indicates failure');
|
|
|
|
const checks = {
|
|
summary_exists: true,
|
|
files_created: { checked: filesToCheck.length, found: filesToCheck.length - missing.length, missing },
|
|
commits_exist: commitsExist,
|
|
self_check: selfCheck,
|
|
};
|
|
|
|
const passed = missing.length === 0 && selfCheck !== 'failed';
|
|
return { passed, checks, errors };
|
|
}
|
|
|
|
/** CLI adapter over verifySummaryCore — arg guard + output shaping only. */
|
|
function cmdVerifySummary(
|
|
cwd: string,
|
|
summaryPath: string,
|
|
checkFileCount: number | undefined,
|
|
raw: boolean,
|
|
): void {
|
|
if (!summaryPath) {
|
|
error('summary-path required');
|
|
}
|
|
const result = verifySummaryCore(cwd, summaryPath, checkFileCount);
|
|
output(result, raw, result.passed ? 'passed' : 'failed');
|
|
}
|
|
|
|
/**
|
|
* Issue #429 — negative-grep comment-text echo gate.
|
|
* A literal that an acceptance criterion negative-greps for (grep -c 'LIT' file == 0)
|
|
* must not also appear verbatim inside an <action> body, or the executor's commit-time
|
|
* verify gate fails on the comment echo rather than a real regression. Conservative:
|
|
* errors only on a confidently-extracted QUOTED literal; ambiguous (bareword) → warning.
|
|
*/
|
|
function scanNegativeGrepCommentEcho(content: string): { errors: string[]; warnings: string[] } {
|
|
const errors: string[] = [];
|
|
const warnings: string[] = [];
|
|
// Normalize newlines; join backslash line-continuations so a verify command wrapped
|
|
// across lines (grep ... \ <newline> == 0) is still seen as one segment.
|
|
const text = (content || '')
|
|
.replace(/\r\n/g, '\n')
|
|
.replace(/\r/g, '\n')
|
|
.replace(/\\\n/g, ' ');
|
|
|
|
// 1. Allowlisted literals: <!-- planner-discipline-allow: LIT -->
|
|
const allow = new Set<string>();
|
|
const allowRe = /<!--\s*planner-discipline-allow:\s*(.+?)\s*-->/g;
|
|
let am: RegExpExecArray | null;
|
|
while ((am = allowRe.exec(text)) !== null) allow.add(am[1]);
|
|
|
|
// Zero-equality comparison (the negative grep). The required leading whitespace
|
|
// before the operator distinguishes a shell comparison (`[ $c == 0 ]`, `... == 0`,
|
|
// always spaced) from an assignment (`VAR=0`, never spaced) and naturally excludes
|
|
// `>= 0`, `<= 0`, `!= 0`, `!== 0`, `=== 0`.
|
|
const zeroCmp = (s: string): boolean =>
|
|
/\s==?\s*0\b/.test(s) || /-eq\s+0\b/.test(s) || /\bequals\s+0\b/.test(s);
|
|
|
|
// A grep invocation using a count flag (-c / -cF / -Fc / --count), capturing the
|
|
// search pattern (first quoted token, else first bareword) after a run of options.
|
|
// The options run lets `grep -c -F 'LIT'`, `grep -F -c 'LIT'`, `grep -c -e 'LIT'`
|
|
// and `grep --count 'LIT'` all resolve to the LIT pattern.
|
|
const countGrepRe =
|
|
/grep((?:\s+-{1,2}[A-Za-z][A-Za-z-]*)+)\s+(?:'([^']*)'|"([^"]*)"|([^\s'"|>&;]+))/g;
|
|
const optsHaveCount = (opts: string): boolean =>
|
|
/(?:^|\s)-[A-Za-z]*c[A-Za-z]*(?=\s|$)/.test(opts) || /--count\b/.test(opts);
|
|
// `grep -cv 'pat' == 0` counts NON-matching lines, so == 0 there asserts "all lines
|
|
// match" — a POSITIVE gate, not our negative gate. Skip inverted greps.
|
|
const optsHaveInvert = (opts: string): boolean =>
|
|
/(?:^|\s)-[A-Za-z]*v[A-Za-z]*(?=\s|$)/.test(opts) || /--invert-match\b/.test(opts);
|
|
// Bareword sanity: a real grep target, not a stray operator/number/flag.
|
|
const plausibleBare = (s: string): boolean => /[A-Za-z0-9_]/.test(s) && !/^[-=!<>0-9]+$/.test(s);
|
|
|
|
// 2. <action> text to scan, with negative-grep COMMAND SPANS removed (only the
|
|
// command, not the whole line) so a pasted verify command does not self-flag
|
|
// while a prose echo on the same line is still caught.
|
|
const cmdSpanRe =
|
|
/grep(?:\s+-{1,2}[A-Za-z][A-Za-z-]*)+\s+(?:'[^']*'|"[^"]*"|[^\s'"|>&;]+)[^\n]*?(?:==|-eq|=)\s*0\b/g;
|
|
// Security scan: must see the FULL text up to the first </action> — including a
|
|
// malformed inner <action> — so a grep-echo-0 trick cannot hide behind a
|
|
// deliberately-unclosed tag. Use a bounded to-first-close scan (ReDoS-safe via
|
|
// the {0,20000} cap, #2128), NOT the stop-at-next-open extractTaggedBlocks seam
|
|
// (which would drop the span before an unterminated inner <action>).
|
|
const actionZones: string[] = [];
|
|
const actionRe = /<action>([\s\S]{0,20000}?)<\/action>/g;
|
|
let acm: RegExpExecArray | null;
|
|
while ((acm = actionRe.exec(text)) !== null) actionZones.push(acm[1]);
|
|
const scannableActionText = actionZones.map((zone) => zone.replace(cmdSpanRe, ' ')).join('\n');
|
|
|
|
// 3. Per shell SEGMENT (split lines on && / ||) extract count-grep literals and
|
|
// check echoes. Per-segment splitting keeps a positive gate (`== 1`) from
|
|
// poisoning a negative gate (`== 0`) sharing the same physical line.
|
|
const seenErr = new Set<string>();
|
|
const seenWarn = new Set<string>();
|
|
const segments = text.split('\n').flatMap((line) => line.split(/\s*(?:&&|\|\|)\s*/));
|
|
for (const seg of segments) {
|
|
if (!/grep(?:\s+-{1,2}[A-Za-z])/.test(seg) || !zeroCmp(seg)) continue;
|
|
countGrepRe.lastIndex = 0;
|
|
const quotedLits: string[] = [];
|
|
const bareLits: string[] = [];
|
|
let m: RegExpExecArray | null;
|
|
while ((m = countGrepRe.exec(seg)) !== null) {
|
|
if (!optsHaveCount(m[1]) || optsHaveInvert(m[1])) continue; // need count, not invert (-cv is positive)
|
|
if (m[2] !== undefined) quotedLits.push(m[2]);
|
|
else if (m[3] !== undefined) quotedLits.push(m[3]);
|
|
else if (m[4] !== undefined && plausibleBare(m[4])) bareLits.push(m[4]);
|
|
}
|
|
for (const quoted of quotedLits) {
|
|
if (!quoted || allow.has(quoted) || seenErr.has(quoted)) continue;
|
|
if (scannableActionText.includes(quoted)) {
|
|
seenErr.add(quoted);
|
|
errors.push(
|
|
`Plan body contains forbidden literal "${quoted}" in an <action> block, but an acceptance criterion negative-greps for it (grep -c ... == 0). Rephrase the literal by concept, remove it from the plan body, or add <!-- planner-discipline-allow: ${quoted} --> if it must legitimately appear.`,
|
|
);
|
|
}
|
|
}
|
|
if (quotedLits.length === 0) {
|
|
for (const bare of bareLits) {
|
|
if (allow.has(bare) || seenWarn.has(bare)) continue;
|
|
if (scannableActionText.includes(bare)) {
|
|
seenWarn.add(bare);
|
|
warnings.push(
|
|
`Possible comment-text echo (#429): negative-grep target "${bare}" is unquoted so its literal could not be extracted unambiguously, but it appears in an <action> block. Quote the grep literal and add an allowlist marker if the echo is intended, or rephrase by concept.`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return { errors, warnings };
|
|
}
|
|
|
|
/**
|
|
* Issue #968 — file-wide negative-grep sibling conflict detector.
|
|
* A file-wide negative grep gate (! grep -Eq 'PAT' FILE or grep -c 'PAT' FILE == 0)
|
|
* bans a construct across the WHOLE file. When a sibling task in the same plan
|
|
* legitimately requires the same construct in the same file, the two gates are
|
|
* mutually unsatisfiable. This is a WARN-only check (never changes valid:false).
|
|
*/
|
|
function scanFileWideNegativeGateConflict(content: string): { warnings: string[]; valid: true } {
|
|
const warnings: string[] = [];
|
|
|
|
// Normalize newlines; join backslash line-continuations (same as #429).
|
|
const text = (content || '')
|
|
.replace(/\r\n/g, '\n')
|
|
.replace(/\r/g, '\n')
|
|
.replace(/\\\n/g, ' ');
|
|
|
|
// Allowlisted patterns: <!-- planner-region-allow: PAT -->
|
|
const allow = new Set<string>();
|
|
const allowRe = /<!--\s*planner-region-allow:\s*(.+?)\s*-->/g;
|
|
let am: RegExpExecArray | null;
|
|
while ((am = allowRe.exec(text)) !== null) allow.add(am[1]);
|
|
|
|
// Helper predicates (reused from #429 style).
|
|
// Zero-equality comparison: spaced == 0 or -eq 0.
|
|
const zeroCmp = (s: string): boolean =>
|
|
/\s==?\s*0\b/.test(s) || /-eq\s+0\b/.test(s) || /\bequals\s+0\b/.test(s);
|
|
|
|
// grep options include -c / --count
|
|
const optsHaveCount = (opts: string): boolean =>
|
|
/(?:^|\s)-[A-Za-z]*c[A-Za-z]*(?=\s|$)/.test(opts) || /--count\b/.test(opts);
|
|
|
|
// grep options include -v / --invert-match (inverted count is NOT a negative gate)
|
|
const optsHaveInvert = (opts: string): boolean =>
|
|
/(?:^|\s)-[A-Za-z]*v[A-Za-z]*(?=\s|$)/.test(opts) || /--invert-match\b/.test(opts);
|
|
|
|
// A bareword that is a plausible grep pattern (not a stray flag/number).
|
|
const plausibleBare = (s: string): boolean => /[A-Za-z0-9_]/.test(s) && !/^[-=!<>0-9]+$/.test(s);
|
|
|
|
// Regex to extract grep arguments: opts run then PAT (quoted or bare).
|
|
const grepArgRe =
|
|
/grep((?:\s+-{1,2}[A-Za-z][A-Za-z-]*)+)\s+(?:'([^']*)'|"([^"]*)"|([^\s'"|>&;$()\[\]]+))/g;
|
|
|
|
// FIX 1 (ReDoS): Linear-time "does reqText satisfy the grep pattern" — no RegExp execution.
|
|
// Never calls new RegExp, so no catastrophic backtracking is possible.
|
|
//
|
|
// Handles literal patterns and `.`/`.*/`.+`/`\s`-style wildcard gaps and `^`/`$` anchors.
|
|
// Patterns using character classes (`[…]`), alternation (`a|b`), or other regex constructs
|
|
// fall back to a conservative literal-substring check, so the detector may NOT warn on those
|
|
// (false-negative is the safe direction for a warn-only advisory).
|
|
const patternRequiredIn = (pat: string, reqText: string): boolean => {
|
|
const hay = (reqText || '').slice(0, 8000); // bound the haystack
|
|
if (!pat) return false;
|
|
// Strip ERE anchors — position constraints don't change whether the construct is required.
|
|
pat = pat.replace(/^\^/, '').replace(/\$$/, '');
|
|
if (!pat) return false;
|
|
// Pure literal (no regex metacharacters): direct substring.
|
|
if (!/[.*+?^${}()|[\]\\]/.test(pat)) return hay.includes(pat);
|
|
const SENT = ' ';
|
|
// Replace simple wildcard gaps (\s* \w+ .* .+ .? bare .) with a sentinel.
|
|
let work = pat
|
|
.replace(/\\[sSwWdD][*+?]?/g, SENT)
|
|
.replace(/\.[*+?]/g, SENT)
|
|
.replace(/\./g, SENT);
|
|
work = work.replace(/\\(.)/g, '$1'); // de-escape \( \. etc → literal char
|
|
const joined = work.split(SENT).join('');
|
|
// Unhandled regex constructs remain → safe literal-substring fallback on the raw pattern.
|
|
if (/[*+?^${}()|[\]]/.test(joined)) return hay.includes(pat);
|
|
const frags = work.split(SENT).filter(Boolean);
|
|
if (!frags.length) return false; // all-wildcard pattern → no meaningful requirement
|
|
let pos = 0;
|
|
for (const f of frags) {
|
|
const idx = hay.indexOf(f, pos);
|
|
if (idx === -1) return false;
|
|
pos = idx + f.length;
|
|
}
|
|
return true;
|
|
};
|
|
|
|
// FIX 2 (file basename over-match): exact normalized match; basename fallback ONLY for
|
|
// unqualified gate files (no path separator).
|
|
const normPath = (p: string): string => p.replace(/^\.\//, '').trim();
|
|
|
|
// File-wide discriminator: a token AFTER PAT that looks like a path.
|
|
// Paths have /, a file extension, or match a known task <files> entry.
|
|
// Globs (containing *) are excluded (unresolvable — no warn).
|
|
const looksLikePath = (token: string): boolean =>
|
|
!token.includes('*') &&
|
|
(token.includes('/') || /\.[a-zA-Z]{1,6}$/.test(token));
|
|
|
|
// FIX 5 (hasLeadingNot): collapse to one command-boundary-anchored regex.
|
|
// Negation at a command boundary: start of segment, or after ; & | ( newline / then / do.
|
|
|
|
// FIX 4 (isRegionScoped tightened): return true ONLY when grep is downstream of a
|
|
// sed line-range or awk range producer. Other pipe sources (cat, tac, etc.) are file-wide.
|
|
const isRegionScoped = (seg: string): boolean => {
|
|
if (!seg.includes('|')) return false;
|
|
const before = seg.slice(0, seg.lastIndexOf('|'));
|
|
// sed -n line/range extraction, e.g. sed -n '12,40p' FILE or sed -n '/a/,/b/p' FILE
|
|
if (/\bsed\s+-n\b/.test(before)) return true;
|
|
// awk range pattern, e.g. awk '/start/,/end/' FILE
|
|
if (/\bawk\b[^|]*\/[^/]*\/\s*,\s*\/[^/]*\//.test(before)) return true;
|
|
return false;
|
|
};
|
|
|
|
// Parse all <task> blocks.
|
|
interface TaskInfo {
|
|
name: string;
|
|
files: string[]; // entries from <files>
|
|
gateText: string; // <verify>+<automated>+<acceptance_criteria> text
|
|
reqText: string; // <action>+<acceptance_criteria> text (requirement side)
|
|
}
|
|
const tasks: TaskInfo[] = [];
|
|
for (const tc of extractTaggedBlocks(text, 'task', true)) {
|
|
// Extract task name.
|
|
const namem = extractTaggedBlocks(tc, 'name');
|
|
const name = namem.length ? namem[0].trim() : 'unnamed';
|
|
// Extract <files> entries.
|
|
const filesArr = extractTaggedBlocks(tc, 'files');
|
|
const filesText = filesArr.length ? filesArr[0] : '';
|
|
const files = filesText.split(/[,\s]+/).map(s => s.trim()).filter(Boolean);
|
|
// Gate text: <verify>/<automated>/<acceptance_criteria>.
|
|
const gateFragments: string[] = [];
|
|
for (const tag of ['verify', 'automated', 'acceptance_criteria']) gateFragments.push(...extractTaggedBlocks(tc, tag));
|
|
// Requirement text: <action>/<acceptance_criteria>.
|
|
const reqFragments: string[] = [];
|
|
for (const tag of ['action', 'acceptance_criteria']) reqFragments.push(...extractTaggedBlocks(tc, tag));
|
|
// Strip XML tags from gate text so segments containing embedded
|
|
// XML closing tags (e.g. <automated>cmd</automated> nested inside <verify>)
|
|
// don't bleed into the file-path token extraction.
|
|
const rawGateText = gateFragments.join('\n');
|
|
const gateText = rawGateText.replace(/<[^>]+>/g, ' ');
|
|
tasks.push({
|
|
name,
|
|
files,
|
|
gateText,
|
|
reqText: reqFragments.join('\n'),
|
|
});
|
|
}
|
|
|
|
if (tasks.length < 2) return { warnings, valid: true };
|
|
|
|
// FIX 3 (extensionless known files): build a normalized set of ALL tasks' <files> entries
|
|
// so that extensionless filenames like Dockerfile are also recognized as valid file tokens.
|
|
const knownFiles = new Set<string>();
|
|
for (const t of tasks) {
|
|
for (const f of t.files) knownFiles.add(normPath(f));
|
|
}
|
|
|
|
// Extended looksLikePath: accepts known <files> entries even without an extension.
|
|
const isFileLike = (token: string): boolean => {
|
|
if (token.includes('*')) return false; // exclude globs
|
|
if (looksLikePath(token)) return true;
|
|
return knownFiles.has(normPath(token));
|
|
};
|
|
|
|
// Dedup key: (taskAIdx, taskBIdx, pat, file)
|
|
const seen = new Set<string>();
|
|
|
|
// For each task A, scan gate text for file-wide negative grep bans.
|
|
for (let ai = 0; ai < tasks.length; ai++) {
|
|
const taskA = tasks[ai];
|
|
|
|
// Split gate text into shell segments (split on && / || within lines).
|
|
const segments = taskA.gateText.split('\n').flatMap(line =>
|
|
line.split(/\s*(?:&&|\|\|)\s*/),
|
|
);
|
|
|
|
for (const seg of segments) {
|
|
if (!/grep/.test(seg)) continue;
|
|
|
|
// FIX 5: Negation at a command boundary: start of segment, or after ; & | ( newline / then / do.
|
|
// Also handles ! negating an entire pipeline (e.g. ! cat FILE | grep ...).
|
|
const hasLeadingNot =
|
|
// Direct ! grep: negation immediately before grep keyword
|
|
/(?:^|[\n;&|(]|\bthen\b|\bdo\b)\s*!\s*grep/.test(seg) ||
|
|
// Pipeline negation: ! at command boundary, grep appears in pipeline after |
|
|
(/(?:^|[\n;&|(]|\bthen\b|\bdo\b)\s*!\s*\w/.test(seg) && /\|\s*grep\b/.test(seg));
|
|
|
|
const hasCountZero = zeroCmp(seg);
|
|
|
|
// Extract grep invocation and check for count.
|
|
grepArgRe.lastIndex = 0;
|
|
let pat: string | null = null;
|
|
let file: string | null = null;
|
|
let isBan = false;
|
|
|
|
// FIX 4 helper: given a segment and the grep match end position, find the
|
|
// file argument. First try the token immediately after PAT; if none qualifies,
|
|
// try a cat/tac producer or < FILE redirect from the full segment.
|
|
const resolveFileArg = (segment: string, afterPatStr: string): string | null => {
|
|
// Primary: token immediately after PAT in the grep command
|
|
const fileM = afterPatStr.match(/^\s+([^\s'"|>&;$()\[\]]+)/);
|
|
const rawFile = fileM ? fileM[1] : null;
|
|
if (rawFile && isFileLike(rawFile)) return rawFile;
|
|
// FIX 4: For NON-region segments, also look for cat/tac producer or < FILE redirect
|
|
const catM = segment.match(/\b(?:cat|tac)\s+([^\s'"|>&;()]+)/);
|
|
if (catM && isFileLike(catM[1])) return catM[1];
|
|
const redirM = segment.match(/<\s*([^\s'"|>&;()]+)/);
|
|
if (redirM && isFileLike(redirM[1])) return redirM[1];
|
|
return null;
|
|
};
|
|
|
|
// If leading !, it might be a count or a direct !grep
|
|
if (hasLeadingNot && !hasCountZero) {
|
|
// Direct ! grep PAT FILE form: grep opts PAT FILE
|
|
// Extract PAT and FILE from the grep invocation
|
|
grepArgRe.lastIndex = 0;
|
|
let gm: RegExpExecArray | null;
|
|
while ((gm = grepArgRe.exec(seg)) !== null) {
|
|
const opts = gm[1];
|
|
if (optsHaveInvert(opts)) continue; // -v form: not a ban
|
|
// PAT
|
|
const rawPat = gm[2] !== undefined ? gm[2] :
|
|
gm[3] !== undefined ? gm[3] :
|
|
gm[4] !== undefined && plausibleBare(gm[4]) ? gm[4] : null;
|
|
if (!rawPat) continue;
|
|
// FILE: next non-option token after PAT (or cat/tac/redirect in segment)
|
|
const afterPat = seg.slice((gm.index || 0) + gm[0].length);
|
|
const rawFile = resolveFileArg(seg, afterPat);
|
|
if (rawFile) {
|
|
pat = rawPat;
|
|
file = rawFile;
|
|
isBan = true;
|
|
}
|
|
}
|
|
}
|
|
|
|
if (!isBan && hasCountZero) {
|
|
// count grep form: grep -c PAT FILE == 0 or [ $(grep -c PAT FILE) -eq 0 ]
|
|
grepArgRe.lastIndex = 0;
|
|
let gm: RegExpExecArray | null;
|
|
while ((gm = grepArgRe.exec(seg)) !== null) {
|
|
const opts = gm[1];
|
|
if (!optsHaveCount(opts) || optsHaveInvert(opts)) continue;
|
|
const rawPat = gm[2] !== undefined ? gm[2] :
|
|
gm[3] !== undefined ? gm[3] :
|
|
gm[4] !== undefined && plausibleBare(gm[4]) ? gm[4] : null;
|
|
if (!rawPat) continue;
|
|
const afterPat = seg.slice((gm.index || 0) + gm[0].length);
|
|
const rawFile = resolveFileArg(seg, afterPat);
|
|
if (rawFile) {
|
|
pat = rawPat;
|
|
file = rawFile;
|
|
isBan = true;
|
|
}
|
|
}
|
|
}
|
|
|
|
if (!isBan || !pat || !file) continue;
|
|
if (allow.has(pat)) continue;
|
|
// Skip if region-scoped (grep downstream of a sed/awk pipe — region extracted)
|
|
if (isRegionScoped(seg)) continue;
|
|
|
|
// For each other task B: check if B's <files> includes FILE AND B's reqText contains PAT
|
|
for (let bi = 0; bi < tasks.length; bi++) {
|
|
if (bi === ai) continue;
|
|
const taskB = tasks[bi];
|
|
|
|
// FIX 2: Exact normalized match; basename fallback ONLY for unqualified gate files.
|
|
const gateFile = normPath(file);
|
|
const bMatchesFile = taskB.files.some((bf) => {
|
|
const nbf = normPath(bf);
|
|
if (nbf === gateFile) return true;
|
|
// basename fallback only when the gate file is an unqualified bare filename (no dir separator)
|
|
if (!gateFile.includes('/') && path.basename(nbf) === gateFile) return true;
|
|
return false;
|
|
});
|
|
if (!bMatchesFile) continue;
|
|
|
|
// FIX 1: Use linear-time patternRequiredIn instead of new RegExp (ReDoS-safe).
|
|
const bRequiresPat = patternRequiredIn(pat, taskB.reqText);
|
|
if (!bRequiresPat) continue;
|
|
|
|
const dedupeKey = `${ai}:${bi}:${pat}:${file}`;
|
|
if (seen.has(dedupeKey)) continue;
|
|
seen.add(dedupeKey);
|
|
|
|
warnings.push(
|
|
`Region-scope conflict (#968): task "${taskA.name}" negative-greps "${pat}" file-wide on ${file}, ` +
|
|
`but sibling task "${taskB.name}" requires it in the same file. ` +
|
|
`A file-wide ban is unsatisfiable when a sibling needs the construct elsewhere — ` +
|
|
`region-scope task "${taskA.name}"'s gate (sed -n/awk range then grep) or use an AST/test check. ` +
|
|
`See planner-antipatterns.md "Region-Scoped Negative Gates", or add ` +
|
|
`<!-- planner-region-allow: ${pat} --> if intentional.`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
// This detector is warn-only: it never sets valid=false.
|
|
return { warnings, valid: true as const };
|
|
}
|
|
|
|
// ─── Plan-task structure validation (#2444) ──────────────────────────────────
|
|
|
|
/**
|
|
* Per-task structural information extracted from a PLAN.md `<tasks>` block.
|
|
* Captures the task's `type` attribute (so `checkpoint:*` tasks validate
|
|
* against their type-specific canonical field set per
|
|
* `gsd-core/references/checkpoints.md`) plus presence flags for every tag the
|
|
* validator cares about. Pure data — no I/O.
|
|
*/
|
|
interface PlanTaskInfo {
|
|
name: string;
|
|
/** Lowercased `type` attribute value, or '' when the opening tag has no type. */
|
|
type: string;
|
|
hasName: boolean;
|
|
// auto-task fields
|
|
hasFiles: boolean;
|
|
hasAction: boolean;
|
|
hasVerify: boolean;
|
|
hasDone: boolean;
|
|
// checkpoint:human-verify fields
|
|
hasWhatBuilt: boolean;
|
|
hasHowToVerify: boolean;
|
|
// checkpoint:decision fields
|
|
hasDecision: boolean;
|
|
hasOptions: boolean;
|
|
// checkpoint:human-action fields
|
|
hasInstructions: boolean;
|
|
hasVerification: boolean;
|
|
// cross-checkpoint common
|
|
hasResumeSignal: boolean;
|
|
}
|
|
|
|
/**
|
|
* Single pass over `<task ...>…</task>` blocks. The body pattern is
|
|
* ReDoS-safe stop-at-next-open (mirrors `taggedBlockPattern` in
|
|
* markdown-sectionizer.cts): bounded attributes (`[^>]{0,1000}`) and a body
|
|
* boundary that terminates at the NEXT `<task[\s>]` opening, so a document
|
|
* full of unclosed `<task>` openings scans linearly. Captures both the
|
|
* attribute string (group 1, so the `type=` selector is not lost the way it is
|
|
* with `extractTaggedBlocks`) and the body (group 2).
|
|
*/
|
|
const PLAN_TASK_BLOCK_RE = /<task(\s[^>]{0,1000})?>((?:(?!<task[\s>])[\s\S])*?)<\/task>/g;
|
|
|
|
/**
|
|
* Extract one `PlanTaskInfo` per `<task …>…</task>` block in `content`.
|
|
*
|
|
* Why a dedicated regex instead of `extractTaggedBlocks('task', true)`:
|
|
* `extractTaggedBlocks` discards the opening tag, so the task's `type=`
|
|
* attribute (which selects the validation branch) is lost. This helper
|
|
* captures both the attribute string and the body in one pass, then reuses
|
|
* `extractTaggedBlocks` on the body for sub-element extraction.
|
|
*/
|
|
function extractPlanTaskInfos(content: string): PlanTaskInfo[] {
|
|
const infos: PlanTaskInfo[] = [];
|
|
if (typeof content !== 'string' || content.length === 0) return infos;
|
|
|
|
PLAN_TASK_BLOCK_RE.lastIndex = 0;
|
|
let match: RegExpExecArray | null;
|
|
while ((match = PLAN_TASK_BLOCK_RE.exec(content)) !== null) {
|
|
const attrs = match[1] ?? '';
|
|
const body = match[2] ?? '';
|
|
|
|
const typeMatch = attrs.match(/\btype\s*=\s*["']?([\w:-]+)/i);
|
|
const type = typeMatch ? typeMatch[1].toLowerCase() : '';
|
|
|
|
const nameArr = extractTaggedBlocks(body, 'name');
|
|
const hasName = nameArr.length > 0;
|
|
const name = hasName ? nameArr[0].trim() : '';
|
|
|
|
infos.push({
|
|
name,
|
|
type,
|
|
hasName,
|
|
hasFiles: /<files>/.test(body),
|
|
hasAction: /<action>/.test(body),
|
|
hasVerify: /<verify>/.test(body),
|
|
hasDone: /<done>/.test(body),
|
|
hasWhatBuilt: /<what-built>/.test(body),
|
|
hasHowToVerify: /<how-to-verify>/.test(body),
|
|
hasDecision: /<decision>/.test(body),
|
|
hasOptions: /<options>/.test(body),
|
|
hasInstructions: /<instructions>/.test(body),
|
|
hasVerification: /<verification>/.test(body),
|
|
hasResumeSignal: /<resume-signal>/.test(body),
|
|
});
|
|
|
|
// Guard against zero-length matches looping forever.
|
|
if (match.index === PLAN_TASK_BLOCK_RE.lastIndex) {
|
|
PLAN_TASK_BLOCK_RE.lastIndex++;
|
|
}
|
|
}
|
|
return infos;
|
|
}
|
|
|
|
function isCheckpointType(type: string): boolean {
|
|
return type.startsWith('checkpoint:');
|
|
}
|
|
|
|
/**
|
|
* Validate one plan task's structure against its type-specific canonical field
|
|
* set (per `gsd-core/references/checkpoints.md`):
|
|
* - `checkpoint:human-verify` requires `<what-built>` / `<how-to-verify>` /
|
|
* `<resume-signal>` (the "checkpoint triple").
|
|
* - `checkpoint:decision` requires `<decision>` / `<options>` /
|
|
* `<resume-signal>`.
|
|
* - `checkpoint:human-action` requires `<action>` / `<instructions>` /
|
|
* `<verification>` / `<resume-signal>`.
|
|
* - Unknown `checkpoint:*` subtypes require only the universal
|
|
* `<resume-signal>` (forward-compat — newer checkpoint types registered
|
|
* in the reference don't need a verifier change to pass structure
|
|
* validation).
|
|
* - All other types (`auto`, `tracer`, `manual`, bare `<task>`, …) keep the
|
|
* historical `<action>` / `<verify>` / `<done>` / `<files>` requirements.
|
|
*/
|
|
function validatePlanTaskStructure(task: PlanTaskInfo): { errors: string[]; warnings: string[] } {
|
|
const errors: string[] = [];
|
|
const warnings: string[] = [];
|
|
const taskName = task.hasName ? task.name : 'unnamed';
|
|
|
|
if (!task.hasName) {
|
|
errors.push('Task missing <name> element');
|
|
}
|
|
|
|
if (isCheckpointType(task.type)) {
|
|
if (!task.hasResumeSignal) {
|
|
errors.push(`Task '${taskName}' missing <resume-signal>`);
|
|
}
|
|
switch (task.type) {
|
|
case 'checkpoint:human-verify':
|
|
if (!task.hasWhatBuilt) errors.push(`Task '${taskName}' missing <what-built>`);
|
|
if (!task.hasHowToVerify) errors.push(`Task '${taskName}' missing <how-to-verify>`);
|
|
break;
|
|
case 'checkpoint:decision':
|
|
if (!task.hasDecision) errors.push(`Task '${taskName}' missing <decision>`);
|
|
if (!task.hasOptions) errors.push(`Task '${taskName}' missing <options>`);
|
|
break;
|
|
case 'checkpoint:human-action':
|
|
if (!task.hasAction) errors.push(`Task '${taskName}' missing <action>`);
|
|
if (!task.hasInstructions) errors.push(`Task '${taskName}' missing <instructions>`);
|
|
if (!task.hasVerification) errors.push(`Task '${taskName}' missing <verification>`);
|
|
break;
|
|
default:
|
|
// Unknown checkpoint:* subtype: <resume-signal> is the only universal
|
|
// requirement (forward-compat).
|
|
break;
|
|
}
|
|
} else {
|
|
if (!task.hasAction) errors.push(`Task '${taskName}' missing <action>`);
|
|
if (!task.hasVerify) warnings.push(`Task '${taskName}' missing <verify>`);
|
|
if (!task.hasDone) warnings.push(`Task '${taskName}' missing <done>`);
|
|
if (!task.hasFiles) warnings.push(`Task '${taskName}' missing <files>`);
|
|
}
|
|
|
|
return { errors, warnings };
|
|
}
|
|
|
|
function cmdVerifyPlanStructure(cwd: string, filePath: string, raw: boolean): void {
|
|
if (!filePath) {
|
|
error('file path required');
|
|
}
|
|
if (filePath.includes('\0')) { error('file path contains null bytes'); }
|
|
const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
|
|
const content = safeReadFile(fullPath);
|
|
if (!content) {
|
|
output({ error: 'File not found', path: filePath }, raw);
|
|
return;
|
|
}
|
|
|
|
// #2701: fail loud on NUL/binary corruption before structure checks. A
|
|
// structurally intact-but-NUL-corrupted plan otherwise passes as valid and is
|
|
// silently skipped by recursive/binary-skipping searchers downstream.
|
|
const encErr = textEncodingError(content, filePath);
|
|
if (encErr) {
|
|
output({ valid: false, errors: [encErr] }, raw);
|
|
return;
|
|
}
|
|
|
|
const fm = extractFrontmatter(content, fullPath);
|
|
const errors: string[] = [];
|
|
const warnings: string[] = [];
|
|
|
|
const required = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
|
|
for (const field of required) {
|
|
if (fm[field] === undefined) errors.push(`Missing required frontmatter field: ${field}`);
|
|
}
|
|
|
|
const extractedTasks = extractPlanTaskInfos(content);
|
|
const tasks: Record<string, unknown>[] = [];
|
|
for (const task of extractedTasks) {
|
|
const verdict = validatePlanTaskStructure(task);
|
|
errors.push(...verdict.errors);
|
|
warnings.push(...verdict.warnings);
|
|
tasks.push({
|
|
name: task.hasName ? task.name : 'unnamed',
|
|
type: task.type,
|
|
hasFiles: task.hasFiles,
|
|
hasAction: task.hasAction,
|
|
hasVerify: task.hasVerify,
|
|
hasDone: task.hasDone,
|
|
});
|
|
}
|
|
|
|
if (tasks.length === 0) warnings.push('No <task> elements found');
|
|
|
|
if (
|
|
fm['wave'] &&
|
|
parseInt(fm['wave'] as string) > 1 &&
|
|
(!fm['depends_on'] ||
|
|
(Array.isArray(fm['depends_on']) && (fm['depends_on'] as unknown[]).length === 0))
|
|
) {
|
|
warnings.push('Wave > 1 but depends_on is empty');
|
|
}
|
|
|
|
const hasCheckpoints = /<task\s+type=["']?checkpoint/.test(content);
|
|
// eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
|
|
if (hasCheckpoints && fm['autonomous'] !== 'false' && String(fm['autonomous']) !== 'false') {
|
|
errors.push('Has checkpoint tasks but autonomous is not false');
|
|
}
|
|
|
|
// #1951: a decision rated one-way is supposed to be confirmed before it is
|
|
// walked through. Warn (never error — <reversibility> stays additive) when a
|
|
// one-way rating has no checkpoint:decision anywhere ahead of it in the plan,
|
|
// which is the planner emitting the rating but skipping the gate.
|
|
const decisionCheckpointOffsets: number[] = [];
|
|
for (const m of content.matchAll(/<task\s+type=["']?checkpoint:decision/g)) {
|
|
if (m.index !== undefined) decisionCheckpointOffsets.push(m.index);
|
|
}
|
|
for (const m of content.matchAll(/<reversibility\s[^>]*rating=["']?one-way/g)) {
|
|
const at = m.index;
|
|
if (at === undefined) continue;
|
|
if (!decisionCheckpointOffsets.some((offset) => offset < at)) {
|
|
warnings.push(
|
|
'Task rated <reversibility rating="one-way"> has no preceding checkpoint:decision — '
|
|
+ 'a one-way door must be confirmed before the agent walks through it',
|
|
);
|
|
}
|
|
}
|
|
|
|
const echoScan = scanNegativeGrepCommentEcho(content);
|
|
errors.push(...echoScan.errors);
|
|
warnings.push(...echoScan.warnings);
|
|
|
|
const conflictScan = scanFileWideNegativeGateConflict(content);
|
|
warnings.push(...conflictScan.warnings);
|
|
|
|
output(
|
|
{
|
|
valid: errors.length === 0,
|
|
errors,
|
|
warnings,
|
|
task_count: tasks.length,
|
|
tasks,
|
|
frontmatter_fields: Object.keys(fm),
|
|
},
|
|
raw,
|
|
errors.length === 0 ? 'valid' : 'invalid',
|
|
);
|
|
}
|
|
|
|
function cmdVerifyPhaseCompleteness(cwd: string, phase: string, raw: boolean): void {
|
|
if (!phase) {
|
|
error('phase required');
|
|
}
|
|
const phaseInfoRaw = findPhaseInternal(cwd, phase);
|
|
if (!phaseInfoRaw || !(phaseInfoRaw as unknown as Record<string, unknown>)['found']) {
|
|
output({ error: 'Phase not found', phase }, raw);
|
|
return;
|
|
}
|
|
const phaseInfo = phaseInfoRaw as unknown as Record<string, unknown>;
|
|
|
|
const errors: string[] = [];
|
|
const warnings: string[] = [];
|
|
const phaseDir = path.join(cwd, phaseInfo['directory'] as string);
|
|
|
|
// #3183 (lint-plan-count-drift / ADR-3180 Decision 2): source plans/
|
|
// summaries and their pairing from the single owner (scanPhasePlans +
|
|
// findUnsummarizedPlans/findOrphanSummaries) instead of a bespoke
|
|
// root-only `-PLAN.md`/`-SUMMARY.md` filter and exact-suffix-stem
|
|
// Set-diff. The prior pairing missed bare PLAN.md/SUMMARY.md, nested
|
|
// (#3139 layout) plans, and any of the canonical pairing's other
|
|
// recognized naming forms — producing false "Plans without summaries" /
|
|
// "Summaries without plans" for names it could not recognize as paired
|
|
// (the same failure class #1988/#2648 fixed for the owner's own callers).
|
|
const scan = planScanMod.scanPhasePlans(phaseDir);
|
|
if (scan.scope === SCOPE.UNREADABLE) {
|
|
output({ error: 'Cannot read phase directory' }, raw);
|
|
return;
|
|
}
|
|
const { planFiles, summaryFiles } = scan;
|
|
|
|
const incompletePlans = findUnsummarizedPlans(planFiles, summaryFiles);
|
|
if (incompletePlans.length > 0) {
|
|
errors.push(`Plans without summaries: ${incompletePlans.join(', ')}`);
|
|
}
|
|
|
|
const orphanSummaries = findOrphanSummaries(planFiles, summaryFiles);
|
|
if (orphanSummaries.length > 0) {
|
|
warnings.push(`Summaries without plans: ${orphanSummaries.join(', ')}`);
|
|
}
|
|
|
|
output(
|
|
{
|
|
complete: errors.length === 0,
|
|
phase: phaseInfo['phase_number'],
|
|
plan_count: planFiles.length,
|
|
summary_count: summaryFiles.length,
|
|
incomplete_plans: incompletePlans,
|
|
orphan_summaries: orphanSummaries,
|
|
errors,
|
|
warnings,
|
|
},
|
|
raw,
|
|
errors.length === 0 ? 'complete' : 'incomplete',
|
|
);
|
|
}
|
|
|
|
function cmdVerifyReferences(cwd: string, filePath: string, raw: boolean): void {
|
|
if (!filePath) {
|
|
error('file path required');
|
|
}
|
|
const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
|
|
const content = safeReadFile(fullPath);
|
|
if (!content) {
|
|
output({ error: 'File not found', path: filePath }, raw);
|
|
return;
|
|
}
|
|
|
|
const found: string[] = [];
|
|
const missing: string[] = [];
|
|
|
|
const atRefs = content.match(/@([^\s\n,)]+\/[^\s\n,)]+)/g) || [];
|
|
for (const ref of atRefs) {
|
|
const cleanRef = ref.slice(1);
|
|
const resolved = cleanRef.startsWith('~/')
|
|
? path.join(process.env['HOME'] || '', cleanRef.slice(2))
|
|
: path.join(cwd, cleanRef);
|
|
if (fs.existsSync(resolved)) {
|
|
found.push(cleanRef);
|
|
} else {
|
|
missing.push(cleanRef);
|
|
}
|
|
}
|
|
|
|
const backtickRefs = content.match(/`([^`]+\/[^`]+\.[a-zA-Z]{1,10})`/g) || [];
|
|
for (const ref of backtickRefs) {
|
|
const cleanRef = ref.slice(1, -1);
|
|
if (cleanRef.startsWith('http') || cleanRef.includes('${') || cleanRef.includes('{{')) continue;
|
|
if (found.includes(cleanRef) || missing.includes(cleanRef)) continue;
|
|
const resolved = path.join(cwd, cleanRef);
|
|
if (fs.existsSync(resolved)) {
|
|
found.push(cleanRef);
|
|
} else {
|
|
missing.push(cleanRef);
|
|
}
|
|
}
|
|
|
|
output(
|
|
{
|
|
valid: missing.length === 0,
|
|
found: found.length,
|
|
missing,
|
|
total: found.length + missing.length,
|
|
},
|
|
raw,
|
|
missing.length === 0 ? 'valid' : 'invalid',
|
|
);
|
|
}
|
|
|
|
function cmdVerifyCommits(cwd: string, hashes: string[], raw: boolean): void {
|
|
if (!hashes || hashes.length === 0) {
|
|
error('At least one commit hash required');
|
|
}
|
|
|
|
const valid: string[] = [];
|
|
const invalid: string[] = [];
|
|
for (const hash of hashes) {
|
|
const result = execGit(['cat-file', '-t', hash], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (result.exitCode === 0 && result.stdout.trim() === 'commit') {
|
|
valid.push(hash);
|
|
} else {
|
|
invalid.push(hash);
|
|
}
|
|
}
|
|
|
|
output(
|
|
{
|
|
all_valid: invalid.length === 0,
|
|
valid,
|
|
invalid,
|
|
total: hashes.length,
|
|
},
|
|
raw,
|
|
invalid.length === 0 ? 'valid' : 'invalid',
|
|
);
|
|
}
|
|
|
|
function cmdVerifyArtifacts(cwd: string, planFilePath: string, raw: boolean): void {
|
|
if (!planFilePath) {
|
|
error('plan file path required');
|
|
}
|
|
const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
|
|
const content = safeReadFile(fullPath);
|
|
if (!content) {
|
|
output({ error: 'File not found', path: planFilePath }, raw);
|
|
return;
|
|
}
|
|
|
|
const artifacts = parseMustHavesBlock(content, 'artifacts') as Record<string, unknown>[];
|
|
if (artifacts.length === 0) {
|
|
output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
|
|
return;
|
|
}
|
|
|
|
const results: Record<string, unknown>[] = [];
|
|
for (const artifact of artifacts) {
|
|
if (typeof artifact === 'string') continue;
|
|
const artPath = artifact['path'] as string | undefined;
|
|
if (!artPath) continue;
|
|
|
|
const artFullPath = path.join(cwd, artPath);
|
|
const exists = fs.existsSync(artFullPath);
|
|
const check: Record<string, unknown> = { path: artPath, exists, issues: [], passed: false };
|
|
|
|
if (exists) {
|
|
const fileContent = safeReadFile(artFullPath) || '';
|
|
const lineCount = fileContent.split('\n').length;
|
|
|
|
if (artifact['min_lines'] && lineCount < (artifact['min_lines'] as number)) {
|
|
(check['issues'] as string[]).push(`Only ${lineCount} lines, need ${artifact['min_lines'] as number}`);
|
|
}
|
|
if (artifact['contains'] && !fileContent.includes(artifact['contains'] as string)) {
|
|
(check['issues'] as string[]).push(`Missing pattern: ${artifact['contains'] as string}`);
|
|
}
|
|
if (artifact['exports']) {
|
|
const exports = Array.isArray(artifact['exports'])
|
|
? artifact['exports']
|
|
: [artifact['exports']];
|
|
for (const exp of exports) {
|
|
if (!fileContent.includes(exp as string)) (check['issues'] as string[]).push(`Missing export: ${exp as string}`);
|
|
}
|
|
}
|
|
check['passed'] = (check['issues'] as string[]).length === 0;
|
|
} else {
|
|
(check['issues'] as string[]).push('File not found');
|
|
}
|
|
|
|
results.push(check);
|
|
}
|
|
|
|
const passed = results.filter((r) => r['passed']).length;
|
|
output(
|
|
{
|
|
all_passed: passed === results.length,
|
|
passed,
|
|
total: results.length,
|
|
artifacts: results,
|
|
},
|
|
raw,
|
|
passed === results.length ? 'valid' : 'invalid',
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns a Set of file paths (relative to cwd) that are promised by plans in
|
|
* the same phase directory at a wave number >= minWave.
|
|
*
|
|
* Used by cmdVerifyKeyLinks to avoid hard-failing a missing `from:` file that
|
|
* is a planned future artifact (fix #1202).
|
|
*/
|
|
function collectPromisedFilesAtOrAfterWave(phaseDir: string, minWave: number): Set<string> {
|
|
const promised = new Set<string>();
|
|
const { planFiles } = planScanMod.scanPhasePlans(phaseDir);
|
|
for (const planFile of planFiles) {
|
|
const planFullPath = path.join(phaseDir, planFile);
|
|
const planContent = safeReadFile(planFullPath);
|
|
if (!planContent) continue;
|
|
const fm = extractFrontmatter(planContent, planFullPath);
|
|
const waveRaw = fm['wave'];
|
|
const wave = typeof waveRaw === 'string' ? parseInt(waveRaw, 10) : (typeof waveRaw === 'number' ? waveRaw : NaN);
|
|
if (isNaN(wave) || wave < minWave) continue;
|
|
const filesModified = fm['files_modified'];
|
|
if (!filesModified) continue;
|
|
const files: unknown[] = Array.isArray(filesModified)
|
|
? filesModified
|
|
: (typeof filesModified === 'string' ? [filesModified] : []);
|
|
for (const f of files) {
|
|
if (typeof f === 'string' && f.trim()) promised.add(f.trim());
|
|
}
|
|
}
|
|
return promised;
|
|
}
|
|
|
|
function cmdVerifyKeyLinks(cwd: string, planFilePath: string, raw: boolean): void {
|
|
if (!planFilePath) {
|
|
error('plan file path required');
|
|
}
|
|
const fullPath = path.isAbsolute(planFilePath) ? planFilePath : path.join(cwd, planFilePath);
|
|
const content = safeReadFile(fullPath);
|
|
if (!content) {
|
|
output({ error: 'File not found', path: planFilePath }, raw);
|
|
return;
|
|
}
|
|
|
|
const keyLinks = parseMustHavesBlock(content, 'key_links') as Record<string, unknown>[];
|
|
if (keyLinks.length === 0) {
|
|
output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
|
|
return;
|
|
}
|
|
|
|
// Derive the current plan's wave number and phase directory for wave-aware
|
|
// missing-file handling (fix #1202).
|
|
const currentFm = extractFrontmatter(content, fullPath);
|
|
const currentWaveRaw = currentFm['wave'];
|
|
const currentWave = typeof currentWaveRaw === 'string'
|
|
? parseInt(currentWaveRaw, 10)
|
|
: (typeof currentWaveRaw === 'number' ? currentWaveRaw : 1);
|
|
const phaseDir = path.dirname(fullPath);
|
|
|
|
// Collect files promised by plans at wave >= currentWave (lazy: computed once
|
|
// the first time a missing source is encountered).
|
|
let promisedFiles: Set<string> | null = null;
|
|
function getPromisedFiles(): Set<string> {
|
|
if (promisedFiles === null) {
|
|
promisedFiles = collectPromisedFilesAtOrAfterWave(phaseDir, isNaN(currentWave) ? 1 : currentWave);
|
|
}
|
|
return promisedFiles;
|
|
}
|
|
|
|
const results: Record<string, unknown>[] = [];
|
|
let pendingCount = 0;
|
|
for (const link of keyLinks) {
|
|
if (typeof link === 'string') continue;
|
|
const check: Record<string, unknown> = {
|
|
from: link['from'],
|
|
to: link['to'],
|
|
via: link['via'] || '',
|
|
verified: false,
|
|
detail: '',
|
|
};
|
|
|
|
const fromPath = (link['from'] as string) || '';
|
|
const sourceContent = safeReadFile(path.join(cwd, fromPath));
|
|
if (!sourceContent) {
|
|
// Check if the missing file is promised by a plan at the same or later wave.
|
|
const promised = getPromisedFiles();
|
|
const isPromised = fromPath.trim() !== '' && promised.has(fromPath.trim());
|
|
if (isPromised) {
|
|
check['pending'] = true;
|
|
check['detail'] = 'Source file not yet created — declared in files_modified of a same-or-later-wave plan';
|
|
pendingCount++;
|
|
} else {
|
|
check['detail'] = 'Source file not found (from: must be a relative file path; describe components/endpoints in via:)';
|
|
}
|
|
} else if (link['pattern']) {
|
|
try {
|
|
const regex = new RegExp(link['pattern'] as string);
|
|
if (regex.test(sourceContent)) {
|
|
check['verified'] = true;
|
|
check['detail'] = 'Pattern found in source';
|
|
} else {
|
|
const targetContent = safeReadFile(path.join(cwd, (link['to'] as string) || ''));
|
|
if (targetContent && regex.test(targetContent)) {
|
|
check['verified'] = true;
|
|
check['detail'] = 'Pattern found in target';
|
|
} else {
|
|
check['detail'] = `Pattern "${link['pattern'] as string}" not found in source or target`;
|
|
}
|
|
}
|
|
} catch {
|
|
check['detail'] = `Invalid regex pattern: ${link['pattern'] as string}`;
|
|
}
|
|
} else {
|
|
if (sourceContent.includes((link['to'] as string) || '')) {
|
|
check['verified'] = true;
|
|
check['detail'] = 'Target referenced in source';
|
|
} else {
|
|
check['detail'] = 'Target not referenced in source';
|
|
}
|
|
}
|
|
|
|
results.push(check);
|
|
}
|
|
|
|
const verified = results.filter((r) => r['verified']).length;
|
|
// A pending link (from: file promised by a same-or-later-wave plan) is not a
|
|
// hard failure — it should not count against the all_verified gate (#1202).
|
|
const hardFailed = results.filter((r) => !r['verified'] && !r['pending']).length;
|
|
const allVerified = hardFailed === 0;
|
|
output(
|
|
{
|
|
all_verified: allVerified,
|
|
verified,
|
|
pending: pendingCount,
|
|
total: results.length,
|
|
links: results,
|
|
},
|
|
raw,
|
|
allVerified ? 'valid' : 'invalid',
|
|
);
|
|
}
|
|
|
|
function listMilestoneArchiveDirs(planBase: string): string[] {
|
|
const milestonesDir = path.join(planBase, 'milestones');
|
|
try {
|
|
return fs
|
|
.readdirSync(milestonesDir, { withFileTypes: true })
|
|
.filter((e) => e.isDirectory() && MILESTONE_ARCHIVE_DIR_RE.test(e.name))
|
|
.map((e) => path.join(milestonesDir, e.name))
|
|
.sort((a, b) =>
|
|
path.basename(a).localeCompare(path.basename(b), undefined, { numeric: true }),
|
|
);
|
|
} catch (err) {
|
|
// #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
|
|
// (no milestones/ dir yet) keeps the long-standing [] contract that
|
|
// collectPhaseRoots / forEachArchivedPhaseToken depend on for "no archives";
|
|
// every other error (EACCES, EIO, …) must propagate — otherwise an unreadable
|
|
// milestones/ dir is silently reported as "no archives" and active-milestone
|
|
// resolution / archived-phase filtering misbehaves.
|
|
if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
|
|
throw err;
|
|
}
|
|
}
|
|
|
|
function forEachArchivedPhaseToken(planBase: string, onPhase: (token: string) => void): void {
|
|
for (const archiveDir of listMilestoneArchiveDirs(planBase)) {
|
|
try {
|
|
const entries = fs.readdirSync(archiveDir, { withFileTypes: true });
|
|
for (const e of entries) {
|
|
if (!e.isDirectory()) continue;
|
|
const m = e.name.match(PHASE_TOKEN_FROM_DIR_RE);
|
|
if (m) onPhase(m[1]);
|
|
}
|
|
} catch {
|
|
/* archive dir absent/unreadable */
|
|
}
|
|
}
|
|
}
|
|
|
|
function getActiveMilestoneArchiveDir(planBase: string): string | null {
|
|
const archiveDirs = listMilestoneArchiveDirs(planBase);
|
|
if (archiveDirs.length === 0) return null;
|
|
|
|
try {
|
|
const statePath = path.join(planBase, 'STATE.md');
|
|
if (fs.existsSync(statePath)) {
|
|
const state = fs.readFileSync(statePath, 'utf-8');
|
|
const m = state.match(
|
|
/^\s*(?:\*\*)?milestone(?:\*\*)?:\s*\*{0,2}\s*([^\s*\r\n#][^\s\r\n#]*)/mi,
|
|
);
|
|
if (m && m[1]) {
|
|
const milestone = m[1].trim();
|
|
const candidate = path.join(planBase, 'milestones', `${milestone}-phases`);
|
|
return archiveDirs.includes(candidate) ? candidate : null;
|
|
}
|
|
}
|
|
} catch {
|
|
/* intentionally empty — fall through to version-sort below */
|
|
}
|
|
|
|
return archiveDirs[archiveDirs.length - 1];
|
|
}
|
|
|
|
function collectPhaseRoots(planBase: string): string[] {
|
|
const roots: string[] = [];
|
|
const flatPhasesDir = path.join(planBase, 'phases');
|
|
if (fs.existsSync(flatPhasesDir)) roots.push(flatPhasesDir);
|
|
const activeArchive = getActiveMilestoneArchiveDir(planBase);
|
|
if (activeArchive) roots.push(activeArchive);
|
|
return roots;
|
|
}
|
|
|
|
function collectDiskPhases(planBase: string): Set<string> {
|
|
const diskPhases = new Set<string>();
|
|
const phaseRoots = collectPhaseRoots(planBase);
|
|
const scanDir = (dir: string) => {
|
|
try {
|
|
const entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
for (const e of entries) {
|
|
if (e.isDirectory()) {
|
|
const m = e.name.match(PHASE_TOKEN_FROM_DIR_RE);
|
|
if (m) diskPhases.add(m[1]);
|
|
}
|
|
}
|
|
} catch {
|
|
/* dir absent */
|
|
}
|
|
};
|
|
|
|
for (const root of phaseRoots) scanDir(root);
|
|
|
|
return diskPhases;
|
|
}
|
|
|
|
interface MilestoneMismatch {
|
|
phaseId: string;
|
|
foundInMilestone: string;
|
|
expectedMilestone: string;
|
|
}
|
|
|
|
function checkMilestonePrefixMismatches(
|
|
roadmapContent: string,
|
|
{ getMilestoneFromPhaseId }: { getMilestoneFromPhaseId: (id: string) => string | null },
|
|
): MilestoneMismatch[] {
|
|
const mismatches: MilestoneMismatch[] = [];
|
|
const sections: { version: string; start: number; end: number }[] = [];
|
|
const sectionRx = /^#{1,3}\s+(?:\[[^\]]{1,200}\]\s*)?.*v(\d+\.\d+)/gim;
|
|
let m: RegExpExecArray | null;
|
|
while ((m = sectionRx.exec(roadmapContent)) !== null) {
|
|
if (sections.length > 0) sections[sections.length - 1].end = m.index;
|
|
sections.push({ version: `v${m[1]}`, start: m.index, end: roadmapContent.length });
|
|
}
|
|
for (const section of sections) {
|
|
const content = roadmapContent.slice(section.start, section.end);
|
|
// #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
|
|
const phaseRx = /#{2,4}\s*(?:\[[^\]]{1,200}\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/gi;
|
|
let pm: RegExpExecArray | null;
|
|
while ((pm = phaseRx.exec(content)) !== null) {
|
|
const phaseId = pm[1];
|
|
const expectedMilestone = getMilestoneFromPhaseId(phaseId);
|
|
if (expectedMilestone !== null && expectedMilestone !== section.version) {
|
|
mismatches.push({
|
|
phaseId,
|
|
foundInMilestone: section.version,
|
|
expectedMilestone,
|
|
});
|
|
}
|
|
}
|
|
}
|
|
return mismatches;
|
|
}
|
|
|
|
interface IssueEntry {
|
|
code: string;
|
|
message: string;
|
|
fix: string;
|
|
repairable: boolean;
|
|
}
|
|
|
|
function cmdValidateConsistency(cwd: string, raw: boolean): void {
|
|
const planBase = planningDir(cwd);
|
|
const roadmapPath = path.join(planBase, 'ROADMAP.md');
|
|
const errors: string[] = [];
|
|
const warnings: string[] = [];
|
|
|
|
if (!fs.existsSync(roadmapPath)) {
|
|
errors.push('ROADMAP.md not found');
|
|
output({ passed: false, errors, warnings }, raw, 'failed');
|
|
return;
|
|
}
|
|
|
|
const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8');
|
|
const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd);
|
|
|
|
const { roadmapPhases } = buildRoadmapPhaseVariants(roadmapContent);
|
|
const { roadmapPhaseVariants: fullRoadmapPhaseVariants } = buildRoadmapPhaseVariants(roadmapContentRaw);
|
|
|
|
const diskPhases = collectDiskPhases(planBase);
|
|
|
|
for (const p of roadmapPhases) {
|
|
if (!diskPhases.has(p) && !diskPhases.has(normalizePhaseName(p))) {
|
|
warnings.push(`Phase ${p} in ROADMAP.md but no directory on disk`);
|
|
}
|
|
}
|
|
|
|
for (const p of diskPhases) {
|
|
const variants = phaseVariants(p);
|
|
if (![...variants].some((v) => fullRoadmapPhaseVariants.has(v))) {
|
|
warnings.push(`Phase ${p} exists on disk but not in ROADMAP.md`);
|
|
}
|
|
}
|
|
|
|
const config = loadConfig(cwd);
|
|
if (config.phase_naming !== 'custom') {
|
|
const integerPhases = [...diskPhases]
|
|
.filter((p) => !p.includes('.'))
|
|
.map((p) => parseInt(p, 10))
|
|
.sort((a, b) => a - b);
|
|
|
|
for (let i = 1; i < integerPhases.length; i++) {
|
|
if (integerPhases[i] !== integerPhases[i - 1] + 1) {
|
|
warnings.push(`Gap in phase numbering: ${integerPhases[i - 1]} → ${integerPhases[i]}`);
|
|
}
|
|
}
|
|
}
|
|
|
|
const phaseRoots = collectPhaseRoots(planBase);
|
|
for (const phaseRoot of phaseRoots) {
|
|
try {
|
|
const entries = fs.readdirSync(phaseRoot, { withFileTypes: true });
|
|
const dirs = entries
|
|
.filter((e) => e.isDirectory())
|
|
.map((e) => e.name)
|
|
.sort();
|
|
|
|
for (const dir of dirs) {
|
|
const phasePath = path.join(phaseRoot, dir);
|
|
const phaseLabel = posixNormalize(path.relative(planBase, phasePath));
|
|
|
|
// #3183: this loop mixes two DIFFERENT questions — split explicitly
|
|
// rather than migrating it as one blind swap-in.
|
|
|
|
// QUESTION 1 — physical numbering-gap detection: wants EVERY plan
|
|
// file that physically exists, superseded or not (a retired plan
|
|
// still occupied a number in the sequence), root+nested. Uses the
|
|
// single owner's allPlanFiles rather than a root-only readdirSync
|
|
// filter. The strict `-NN-PLAN.md` suffix regex below already
|
|
// ignores any entry (nested, loose-named, bare PLAN.md) that isn't
|
|
// in the root canonical numbered form, so widening the input set is
|
|
// a pure visibility fix with no change to which files feed a number.
|
|
//
|
|
// One scan serves both questions below: `allPlanFiles` answers
|
|
// Question 1 (numbering-gap), `planFiles`/`summaryFiles` answer
|
|
// Question 2 (pairing) a few lines down.
|
|
const { allPlanFiles, planFiles, summaryFiles } = planScanMod.scanPhasePlans(phasePath);
|
|
|
|
// Root-canonical numbered plans only (`<phase>-NN-PLAN.md`) — the
|
|
// shape the numbering-gap sequence check operates on. Matched via
|
|
// the numbering regex itself rather than a separate suffix filter,
|
|
// so this stays a single derivation from the owner's output, not a
|
|
// second independent re-derivation of its filename grammar.
|
|
const numberedPlans = allPlanFiles
|
|
.map((p) => {
|
|
const pm = p.match(/-(\d{2})-PLAN\.md$/);
|
|
return pm ? { file: p, num: parseInt(pm[1], 10) } : null;
|
|
})
|
|
.filter((e): e is { file: string; num: number } => e !== null)
|
|
.sort((a, b) => a.num - b.num);
|
|
// numberedPlans (and planNums below) answers Question 1 ONLY — the
|
|
// numbering-gap sequence check. It is a strict `-NN-PLAN.md` subset
|
|
// and must NOT be reused as a general "all live plans" set: a plan
|
|
// whose filename isn't in that canonical 2-digit form (a 3-digit
|
|
// continuation, a bare PLAN.md, etc.) is silently absent from it.
|
|
const planNums = numberedPlans.map((e) => e.num);
|
|
|
|
for (let i = 1; i < planNums.length; i++) {
|
|
if (planNums[i] !== planNums[i - 1] + 1) {
|
|
warnings.push(
|
|
`Gap in plan numbering in ${phaseLabel}: plan ${planNums[i - 1]} → ${planNums[i]}`,
|
|
);
|
|
}
|
|
}
|
|
|
|
// QUESTION 2 — plan↔summary pairing: "does this summary have a
|
|
// matching LIVE plan" wants the single owner's superseded-excluded
|
|
// planFiles and the canonical summaryCandidates-based pairing
|
|
// (findOrphanSummaries) instead of an exact-suffix Set-diff, which
|
|
// produced false "orphan summary" warnings for legacy/nested naming
|
|
// forms it could not recognize as paired.
|
|
const orphanSummaries = findOrphanSummaries(planFiles, summaryFiles);
|
|
for (const orphan of orphanSummaries) {
|
|
warnings.push(`Summary ${orphan} in ${phaseLabel} has no matching PLAN.md`);
|
|
}
|
|
|
|
// QUESTION 3 — wave-frontmatter presence: "does every LIVE plan
|
|
// declare a wave" wants the same live (superseded-excluded) set as
|
|
// Question 2's pairing check — planFiles, NOT numberedPlans/Question
|
|
// 1's strict 2-digit subset. A superseded plan legitimately carries
|
|
// no wave, and a live plan whose filename isn't in canonical 2-digit
|
|
// form (a 3-digit continuation, a bare PLAN.md, etc.) must still be
|
|
// checked here even though it is invisible to the numbering-gap scan.
|
|
for (const plan of planFiles) {
|
|
const planFilePath = path.join(phasePath, plan);
|
|
const content = fs.readFileSync(planFilePath, 'utf-8');
|
|
const fmData = extractFrontmatter(content, planFilePath);
|
|
if (!fmData['wave']) {
|
|
warnings.push(`${phaseLabel}/${plan}: missing 'wave' in frontmatter`);
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* intentionally empty */
|
|
}
|
|
}
|
|
|
|
const passed = errors.length === 0;
|
|
output({ passed, errors, warnings, warning_count: warnings.length }, raw, passed ? 'passed' : 'failed');
|
|
}
|
|
|
|
function cmdValidateHealth(
|
|
cwd: string,
|
|
options: Record<string, unknown>,
|
|
raw: boolean,
|
|
): Record<string, unknown> | undefined {
|
|
const resolved = path.resolve(cwd);
|
|
if (resolved === os.homedir()) {
|
|
output(
|
|
{
|
|
status: 'error',
|
|
errors: [
|
|
{
|
|
code: 'E010',
|
|
message: `CWD is home directory (${resolved}) — health check would read the wrong .planning/ directory. Run from your project root instead.`,
|
|
fix: 'cd into your project directory and retry',
|
|
},
|
|
],
|
|
warnings: [],
|
|
info: [{ code: 'I010', message: `Resolved CWD: ${resolved}` }],
|
|
repairable_count: 0,
|
|
},
|
|
raw,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// rootBase always resolves to .planning/ (shared root — PROJECT.md, config.json live here)
|
|
// wsBase resolves to .planning/workstreams/<ws>/ when GSD_WORKSTREAM is set (STATE.md, ROADMAP.md, phases/)
|
|
const rootBase = planningRoot(cwd);
|
|
const wsBase = planningDir(cwd);
|
|
// planBase is kept as an alias for wsBase for all the internal helpers (collectDiskPhases, etc.)
|
|
// that are already parameterised on the workstream-aware path.
|
|
const planBase = wsBase;
|
|
const projectPath = path.join(rootBase, 'PROJECT.md');
|
|
const roadmapPath = path.join(wsBase, 'ROADMAP.md');
|
|
const statePath = path.join(wsBase, 'STATE.md');
|
|
const configPath = path.join(rootBase, 'config.json');
|
|
const phasesDir = path.join(wsBase, 'phases');
|
|
const _slashRuntime = resolveRuntime(cwd);
|
|
const slash = (name: string) => formatGsdSlash(name, _slashRuntime) as string;
|
|
|
|
const errors: IssueEntry[] = [];
|
|
const warnings: IssueEntry[] = [];
|
|
const info: IssueEntry[] = [];
|
|
const repairs: string[] = [];
|
|
|
|
const addIssue = (
|
|
severity: 'error' | 'warning' | 'info',
|
|
code: string,
|
|
message: string,
|
|
fix: string,
|
|
repairable = false,
|
|
) => {
|
|
const issue: IssueEntry = { code, message, fix, repairable };
|
|
if (severity === 'error') errors.push(issue);
|
|
else if (severity === 'warning') warnings.push(issue);
|
|
else info.push(issue);
|
|
};
|
|
|
|
if (!fs.existsSync(rootBase)) {
|
|
addIssue('error', 'E001', '.planning/ directory not found', `Run ${slash('new-project')} to initialize`);
|
|
output({ status: 'broken', errors, warnings, info, repairable_count: 0 }, raw);
|
|
return;
|
|
}
|
|
|
|
if (!fs.existsSync(projectPath)) {
|
|
addIssue('error', 'E002', 'PROJECT.md not found', `Run ${slash('new-project')} to create`);
|
|
} else {
|
|
const content = fs.readFileSync(projectPath, 'utf-8');
|
|
const requiredSections = ['## What This Is', '## Core Value', '## Requirements'];
|
|
for (const section of requiredSections) {
|
|
if (!content.includes(section)) {
|
|
addIssue('warning', 'W001', `PROJECT.md missing section: ${section}`, 'Add section manually');
|
|
}
|
|
}
|
|
}
|
|
|
|
if (!fs.existsSync(roadmapPath)) {
|
|
addIssue('error', 'E003', 'ROADMAP.md not found', `Run ${slash('new-milestone')} to create roadmap`);
|
|
}
|
|
|
|
if (!fs.existsSync(statePath)) {
|
|
addIssue(
|
|
'error',
|
|
'E004',
|
|
'STATE.md not found',
|
|
`Run ${slash('health')} --repair to regenerate`,
|
|
true,
|
|
);
|
|
repairs.push('regenerateState');
|
|
} else {
|
|
const stateContent = fs.readFileSync(statePath, 'utf-8');
|
|
const phaseRefs = [
|
|
...stateContent.matchAll(new RegExp(`[Pp]hase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'g')),
|
|
].map(
|
|
(m) => m[1],
|
|
);
|
|
const validPhases = collectDiskPhases(planBase);
|
|
try {
|
|
if (fs.existsSync(roadmapPath)) {
|
|
const roadmapRaw = fs.readFileSync(roadmapPath, 'utf-8');
|
|
const all = [
|
|
...roadmapRaw.matchAll(new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'gi')),
|
|
];
|
|
for (const m of all) validPhases.add(m[1]);
|
|
}
|
|
} catch {
|
|
/* intentionally empty */
|
|
}
|
|
forEachArchivedPhaseToken(planBase, (token) => validPhases.add(token));
|
|
const normalizedValid = new Set<string>();
|
|
for (const p of validPhases) {
|
|
normalizedValid.add(p);
|
|
const dotIdx = p.indexOf('.');
|
|
const head = dotIdx === -1 ? p : p.slice(0, dotIdx);
|
|
const tail = dotIdx === -1 ? '' : p.slice(dotIdx);
|
|
if (/^\d+$/.test(head)) {
|
|
normalizedValid.add(head.padStart(2, '0') + tail);
|
|
}
|
|
}
|
|
for (const ref of phaseRefs) {
|
|
const dotIdx = ref.indexOf('.');
|
|
const head = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
|
|
const tail = dotIdx === -1 ? '' : ref.slice(dotIdx);
|
|
const padded = /^\d+$/.test(head) ? head.padStart(2, '0') + tail : ref;
|
|
if (!normalizedValid.has(ref) && !normalizedValid.has(padded)) {
|
|
if (normalizedValid.size > 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W002',
|
|
`STATE.md references phase ${ref}, but only phases ${[...validPhases].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })).join(', ')} are declared`,
|
|
`Review STATE.md manually before changing it; ${slash('health')} --repair will not overwrite an existing STATE.md for phase mismatches`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
if (!fs.existsSync(configPath)) {
|
|
addIssue(
|
|
'warning',
|
|
'W003',
|
|
'config.json not found',
|
|
`Run ${slash('health')} --repair to create with defaults`,
|
|
true,
|
|
);
|
|
repairs.push('createConfig');
|
|
} else {
|
|
try {
|
|
const rawCfg = fs.readFileSync(configPath, 'utf-8');
|
|
const parsed = JSON.parse(rawCfg) as Record<string, unknown>;
|
|
if (parsed['model_profile'] && !VALID_PROFILES.includes(parsed['model_profile'] as string)) {
|
|
addIssue(
|
|
'warning',
|
|
'W004',
|
|
`config.json: invalid model_profile "${parsed['model_profile'] as string}"`,
|
|
`Valid values: ${VALID_PROFILES.join(', ')}`,
|
|
);
|
|
}
|
|
const configModels = parsed['models'];
|
|
if (configModels && typeof configModels === 'object' && !Array.isArray(configModels)) {
|
|
for (const [phaseType, tierValue] of Object.entries(configModels as Record<string, unknown>)) {
|
|
if (!VALID_PHASE_TYPES.has(phaseType)) {
|
|
addIssue(
|
|
'warning',
|
|
'W022',
|
|
`config.json: models has an unknown phase type "${phaseType}" which will be ignored`,
|
|
`Valid phase types: ${[...VALID_PHASE_TYPES].join(', ')}`,
|
|
);
|
|
} else if (typeof tierValue !== 'string' || !VALID_TIERS.has(tierValue)) {
|
|
addIssue(
|
|
'warning',
|
|
'W022',
|
|
`config.json: models.${phaseType} has an invalid tier value ${JSON.stringify(tierValue)} which will be ignored`,
|
|
`Valid tiers: ${[...VALID_TIERS].join(', ')}`,
|
|
);
|
|
}
|
|
}
|
|
} else if (configModels !== undefined && configModels !== null) {
|
|
addIssue(
|
|
'warning',
|
|
'W022',
|
|
`config.json: models is set to ${JSON.stringify(configModels)}, but must be an object mapping phase types to tiers — this value will be ignored`,
|
|
`Set models to an object like {"planning": "sonnet"}, or remove the key to use profile defaults`,
|
|
);
|
|
}
|
|
} catch (err) {
|
|
addIssue(
|
|
'error',
|
|
'E005',
|
|
`config.json: JSON parse error - ${err instanceof Error ? err.message : String(err)}`,
|
|
`Run ${slash('health')} --repair to reset to defaults`,
|
|
true,
|
|
);
|
|
repairs.push('resetConfig');
|
|
}
|
|
}
|
|
|
|
if (fs.existsSync(configPath)) {
|
|
try {
|
|
const configRaw = fs.readFileSync(configPath, 'utf-8');
|
|
const configParsed = JSON.parse(configRaw) as Record<string, unknown>;
|
|
const workflow = configParsed['workflow'] as Record<string, unknown> | undefined;
|
|
if (workflow && workflow['nyquist_validation'] === undefined) {
|
|
addIssue(
|
|
'warning',
|
|
'W008',
|
|
'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)',
|
|
`Run ${slash('health')} --repair to add key`,
|
|
true,
|
|
);
|
|
if (!repairs.includes('addNyquistKey')) repairs.push('addNyquistKey');
|
|
}
|
|
if (workflow && workflow['ai_integration_phase'] === undefined) {
|
|
addIssue(
|
|
'warning',
|
|
'W016',
|
|
`config.json: workflow.ai_integration_phase absent (defaults to enabled — run ${slash('ai-integration-phase')} before planning AI system phases)`,
|
|
`Run ${slash('health')} --repair to add key`,
|
|
true,
|
|
);
|
|
if (!repairs.includes('addAiIntegrationPhaseKey')) repairs.push('addAiIntegrationPhaseKey');
|
|
}
|
|
} catch {
|
|
/* intentionally empty */
|
|
}
|
|
}
|
|
|
|
let phaseDirEntries: fs.Dirent[] = [];
|
|
const phaseDirFiles = new Map<string, string[]>();
|
|
// #3183: companion map of the single owner's scan per phase dir
|
|
// (root+nested, superseded-excluded plan/summary sets + canonical
|
|
// pairing), computed alongside the raw readdirSync listing above. The
|
|
// W023 duplicate-dir describer and the I001 unsummarized-plan detector
|
|
// below use THIS map for plan/summary counts and pairing; phaseDirFiles
|
|
// stays raw for the RESEARCH/VALIDATION and phase-dir-naming checks that
|
|
// are not plan-count questions.
|
|
const phaseDirScans = new Map<string, ReturnType<typeof planScanMod.scanPhasePlans>>();
|
|
try {
|
|
phaseDirEntries = fs
|
|
.readdirSync(phasesDir, { withFileTypes: true })
|
|
.filter((e) => e.isDirectory());
|
|
for (const e of phaseDirEntries) {
|
|
try {
|
|
phaseDirFiles.set(e.name, fs.readdirSync(path.join(phasesDir, e.name)));
|
|
} catch {
|
|
phaseDirFiles.set(e.name, []);
|
|
}
|
|
phaseDirScans.set(e.name, planScanMod.scanPhasePlans(path.join(phasesDir, e.name)));
|
|
}
|
|
} catch {
|
|
/* intentionally empty */
|
|
}
|
|
|
|
for (const e of phaseDirEntries) {
|
|
if (!e.name.match(phaseDirNameRe)) {
|
|
addIssue(
|
|
'warning',
|
|
'W005',
|
|
`Phase directory "${e.name}" doesn't follow NN-name format`,
|
|
'Rename to match pattern (e.g., 01-setup)',
|
|
);
|
|
}
|
|
}
|
|
|
|
// W023 (#2408): detect two or more real on-disk phase directories that
|
|
// normalize to the same phase key (e.g. `05-real/` + `05-real-stray/`).
|
|
// The collision silently breaks /gsd-stats status accuracy (now folded by
|
|
// precedence — see commands.cts foldPhaseStatus) and forces an operator
|
|
// decision. Wording is neutral — never guesses which directory is "real".
|
|
{
|
|
const groups = new Map<string, string[]>();
|
|
for (const e of phaseDirEntries) {
|
|
// extractPhaseToken never returns empty — for unparseable dir names it
|
|
// falls back to the dir name itself. Two distinct unparseable names
|
|
// therefore normalize to distinct keys and cannot false-positive here;
|
|
// only dirs whose tokens collapse to the same key (e.g. `05-real` and
|
|
// `05-real-stray` → token `05`) produce a collision group.
|
|
const token = extractPhaseToken(e.name);
|
|
const key = normalizePhaseName(token);
|
|
const list = groups.get(key);
|
|
if (list) list.push(e.name);
|
|
else groups.set(key, [e.name]);
|
|
}
|
|
for (const [key, dirs] of groups) {
|
|
if (dirs.length < 2) continue;
|
|
// Compute each dir's status independently so the warning is informative.
|
|
// Sort by phase id for stable output regardless of readdir order; tie-
|
|
// break on the dir name itself so two dirs sharing the same phase token
|
|
// (the collision case itself) still sort deterministically (V8's stable
|
|
// sort would otherwise fall back to non-portable fs.readdirSync order).
|
|
const described = dirs
|
|
.slice()
|
|
.sort((a, b) => comparePhaseNum(a, b) || String(a).localeCompare(String(b)))
|
|
.map((d) => {
|
|
// #3183: canonical plan/summary counts (root+nested,
|
|
// superseded-excluded, canonical pairing) from the single owner.
|
|
const scan = phaseDirScans.get(d);
|
|
const plans = scan ? scan.planCount : 0;
|
|
const summaries = scan ? scan.summaryCount : 0;
|
|
const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, d), 'Not Started');
|
|
return `${d} (${status})`;
|
|
})
|
|
.join(', ');
|
|
addIssue(
|
|
'warning',
|
|
'W023',
|
|
`Phase directories collide on normalized key "${key}": ${described}`,
|
|
'Inspect each directory; rename or remove the duplicate so only one directory maps to this phase key',
|
|
);
|
|
}
|
|
}
|
|
|
|
// I001 (#3183): this IS findUnsummarizedPlans's exact question — routed
|
|
// through the single owner's scan (root+nested, superseded-excluded plan
|
|
// set) and the canonical summaryCandidates-based pairing, instead of a
|
|
// bespoke canonicalPlanStem reimplementation. Fixes: a superseded plan is
|
|
// no longer permanently flagged "may be in progress" (false noise
|
|
// forever), and nested (#3139 layout) plans are no longer invisible.
|
|
for (const e of phaseDirEntries) {
|
|
const scan = phaseDirScans.get(e.name);
|
|
const planFiles = scan ? scan.planFiles : [];
|
|
const summaryFiles = scan ? scan.summaryFiles : [];
|
|
for (const plan of findUnsummarizedPlans(planFiles, summaryFiles)) {
|
|
addIssue('info', 'I001', `${e.name}/${plan} has no SUMMARY.md`, 'May be in progress');
|
|
}
|
|
}
|
|
|
|
for (const e of phaseDirEntries) {
|
|
const phaseFiles = phaseDirFiles.get(e.name) || [];
|
|
const hasResearch = phaseFiles.some((f) => f.endsWith('-RESEARCH.md'));
|
|
const hasValidation = phaseFiles.some((f) => f.endsWith('-VALIDATION.md'));
|
|
if (hasResearch && !hasValidation) {
|
|
const researchFile = phaseFiles.find((f) => f.endsWith('-RESEARCH.md'));
|
|
try {
|
|
const researchContent = fs.readFileSync(
|
|
path.join(phasesDir, e.name, researchFile!),
|
|
'utf-8',
|
|
);
|
|
if (researchContent.includes('## Validation Architecture')) {
|
|
addIssue(
|
|
'warning',
|
|
'W009',
|
|
`Phase ${e.name}: has Validation Architecture in RESEARCH.md but no VALIDATION.md`,
|
|
`Re-run ${slash('plan-phase')} with --research to regenerate`,
|
|
);
|
|
}
|
|
} catch {
|
|
/* intentionally empty */
|
|
}
|
|
}
|
|
}
|
|
|
|
try {
|
|
const agentStatus = checkAgentsInstalled(_slashRuntime, cwd);
|
|
if (!agentStatus.agents_installed) {
|
|
if ((agentStatus.installed_agents).length === 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W010',
|
|
`No GSD agents found in ${agentStatus.agents_dir} — Task(subagent_type="gsd-*") will fall back to general-purpose`,
|
|
`Run the GSD installer: npx ${PACKAGE_NAME}@latest`,
|
|
);
|
|
} else if ((agentStatus.incomplete_agents).length > 0 && (agentStatus.missing_agents).length === 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W010',
|
|
`Incomplete agent installs (missing generated file): ${(agentStatus.incomplete_agents).join(', ')} — affected workflows may fall back to general-purpose`,
|
|
`Re-run the GSD installer to complete the install: npx ${PACKAGE_NAME}@latest`,
|
|
);
|
|
} else if ((agentStatus.incomplete_agents).length > 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W010',
|
|
`Missing ${(agentStatus.missing_agents).length} GSD agents: ${(agentStatus.missing_agents).join(', ')}; incomplete agent installs (missing generated file): ${(agentStatus.incomplete_agents).join(', ')} — affected workflows will fall back to general-purpose`,
|
|
`Run the GSD installer: npx ${PACKAGE_NAME}@latest`,
|
|
);
|
|
} else {
|
|
addIssue(
|
|
'warning',
|
|
'W010',
|
|
`Missing ${(agentStatus.missing_agents).length} GSD agents: ${(agentStatus.missing_agents).join(', ')} — affected workflows will fall back to general-purpose`,
|
|
`Run the GSD installer: npx ${PACKAGE_NAME}@latest`,
|
|
);
|
|
}
|
|
}
|
|
} catch {
|
|
/* intentionally empty — agent check is non-blocking */
|
|
}
|
|
|
|
if (fs.existsSync(roadmapPath)) {
|
|
const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8');
|
|
const roadmapContent = extractCurrentMilestone(roadmapContentRaw, cwd);
|
|
|
|
const { roadmapPhases } = buildRoadmapPhaseVariants(roadmapContent);
|
|
const { roadmapPhaseVariants: fullRoadmapPhaseVariants } =
|
|
buildRoadmapPhaseVariants(roadmapContentRaw);
|
|
|
|
const diskPhases = collectDiskPhases(planBase);
|
|
forEachArchivedPhaseToken(planBase, (token) => diskPhases.add(token));
|
|
|
|
const activeDiskPhases = collectDiskPhases(planBase);
|
|
|
|
const notStartedPhases = buildNotStartedPhaseVariants(roadmapContent);
|
|
|
|
for (const p of roadmapPhases) {
|
|
const variants = phaseVariants(p);
|
|
const existsOnDisk = [...variants].some((v) => diskPhases.has(v));
|
|
if (!existsOnDisk) {
|
|
const isNotStarted = [...variants].some((v) => notStartedPhases.has(v));
|
|
if (isNotStarted) continue;
|
|
addIssue(
|
|
'warning',
|
|
'W006',
|
|
`Phase ${p} in ROADMAP.md but no directory on disk`,
|
|
'Create phase directory or remove from roadmap',
|
|
);
|
|
}
|
|
}
|
|
|
|
for (const p of activeDiskPhases) {
|
|
const variants = phaseVariants(p);
|
|
if (![...variants].some((v) => fullRoadmapPhaseVariants.has(v))) {
|
|
addIssue(
|
|
'warning',
|
|
'W007',
|
|
`Phase ${p} exists on disk but not in ROADMAP.md`,
|
|
'Add to roadmap or remove directory',
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
if (fs.existsSync(statePath) && fs.existsSync(roadmapPath)) {
|
|
try {
|
|
const stateContent = fs.readFileSync(statePath, 'utf-8');
|
|
const roadmapContentFull = fs.readFileSync(roadmapPath, 'utf-8');
|
|
|
|
const currentPhaseMatch =
|
|
stateContent.match(/\*\*Current Phase:\*\*\s*(\S+)/i) ||
|
|
stateContent.match(/Current Phase:\s*(\S+)/i);
|
|
if (currentPhaseMatch) {
|
|
const statePhase = currentPhaseMatch[1].replace(/^0+/, '');
|
|
const phaseCheckboxRe = new RegExp(
|
|
`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`,
|
|
'i',
|
|
);
|
|
if (phaseCheckboxRe.test(roadmapContentFull)) {
|
|
const stateStatus = stateContent.match(/\*\*Status:\*\*\s*(.+)/i);
|
|
const statusVal = stateStatus ? stateStatus[1].trim().toLowerCase() : '';
|
|
if (statusVal !== 'complete' && statusVal !== 'done') {
|
|
addIssue(
|
|
'warning',
|
|
'W011',
|
|
`STATE.md says current phase is ${statePhase} (status: ${statusVal || 'unknown'}) but ROADMAP.md shows it as [x] complete — state files may be out of sync`,
|
|
`Run ${slash('progress')} to re-derive current position, or manually update STATE.md`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* intentionally empty — cross-validation is advisory */
|
|
}
|
|
}
|
|
|
|
if (fs.existsSync(configPath)) {
|
|
try {
|
|
const configRaw = fs.readFileSync(configPath, 'utf-8');
|
|
const configParsed = JSON.parse(configRaw) as Record<string, unknown>;
|
|
|
|
const validStrategies = ['none', 'phase', 'milestone'];
|
|
if (
|
|
configParsed['branching_strategy'] &&
|
|
!validStrategies.includes(configParsed['branching_strategy'] as string)
|
|
) {
|
|
addIssue(
|
|
'warning',
|
|
'W012',
|
|
`config.json: invalid branching_strategy "${configParsed['branching_strategy'] as string}"`,
|
|
`Valid values: ${validStrategies.join(', ')}`,
|
|
);
|
|
}
|
|
|
|
if (configParsed['context_window'] !== undefined) {
|
|
const cw = configParsed['context_window'];
|
|
if (typeof cw !== 'number' || cw <= 0 || !Number.isInteger(cw)) {
|
|
addIssue(
|
|
'warning',
|
|
'W013',
|
|
`config.json: context_window should be a positive integer, got "${cw as string}"`,
|
|
'Set to 200000 (default) or 1000000 (for 1M models)',
|
|
);
|
|
}
|
|
}
|
|
|
|
if (
|
|
configParsed['phase_branch_template'] &&
|
|
!(configParsed['phase_branch_template'] as string).includes('{phase}')
|
|
) {
|
|
addIssue(
|
|
'warning',
|
|
'W014',
|
|
'config.json: phase_branch_template missing {phase} placeholder',
|
|
'Template must include {phase} for phase number substitution',
|
|
);
|
|
}
|
|
if (
|
|
configParsed['milestone_branch_template'] &&
|
|
!(configParsed['milestone_branch_template'] as string).includes('{milestone}')
|
|
) {
|
|
addIssue(
|
|
'warning',
|
|
'W015',
|
|
'config.json: milestone_branch_template missing {milestone} placeholder',
|
|
'Template must include {milestone} for version substitution',
|
|
);
|
|
}
|
|
} catch {
|
|
/* parse error already caught in Check 5 */
|
|
}
|
|
}
|
|
|
|
try {
|
|
const worktreeHealth = (inspectWorktreeHealth as unknown as (
|
|
cwd: string,
|
|
opts: { staleAfterMs: number },
|
|
deps: { execGit: unknown; existsSync: unknown; statSync: unknown },
|
|
) => Record<string, unknown>)(
|
|
cwd,
|
|
{ staleAfterMs: 60 * 60 * 1000 },
|
|
{ execGit, existsSync: fs.existsSync, statSync: fs.statSync },
|
|
);
|
|
if (!(worktreeHealth['ok'] as boolean)) {
|
|
if (worktreeHealth['reason'] === 'git_timed_out') {
|
|
addIssue(
|
|
'warning',
|
|
'W020',
|
|
'Worktree health check degraded: git worktree list timed out after 10s — orphan/stale worktrees could not be inspected',
|
|
'Run: git worktree list --porcelain to diagnose; check for .git/index.lock or a hung git process',
|
|
);
|
|
}
|
|
if (worktreeHealth['reason'] === 'git_list_failed') {
|
|
addIssue(
|
|
'warning',
|
|
'W020',
|
|
'Worktree health check degraded: git worktree list failed — orphan/stale worktrees could not be inspected',
|
|
'Run: git worktree list --porcelain to diagnose; check git repository state and permissions',
|
|
);
|
|
}
|
|
} else {
|
|
for (const finding of worktreeHealth['findings'] as Record<string, unknown>[]) {
|
|
if (finding['kind'] === 'orphan') {
|
|
addIssue(
|
|
'warning',
|
|
'W017',
|
|
`Orphan git worktree: ${finding['path'] as string} (path no longer exists on disk)`,
|
|
'Run: git worktree prune',
|
|
);
|
|
continue;
|
|
}
|
|
|
|
if (finding['kind'] === 'stale') {
|
|
// Do not flag the active session's worktree — removing it would be harmful.
|
|
const worktreePath = finding['path'] as string;
|
|
const activeCwd = process.cwd();
|
|
const normalizedWorktree = path.resolve(worktreePath);
|
|
const normalizedCwd = path.resolve(activeCwd);
|
|
// Skip if the worktree IS the cwd or is an ancestor of it.
|
|
const isActiveWorktree =
|
|
normalizedCwd === normalizedWorktree ||
|
|
normalizedCwd.startsWith(normalizedWorktree + path.sep);
|
|
if (isActiveWorktree) continue;
|
|
addIssue(
|
|
'warning',
|
|
'W017',
|
|
`Stale git worktree: ${worktreePath} (last modified ${finding['ageMinutes'] as number} minutes ago)`,
|
|
`Run: git worktree remove ${worktreePath} --force`,
|
|
);
|
|
continue;
|
|
}
|
|
|
|
// #3050/#3057 (B5): a 'unverified' finding means existsSync confirmed
|
|
// the worktree is present but statSync threw, so orphan/stale status
|
|
// could not be determined for THIS entry — it must not be silently
|
|
// dropped (that would be the exact fail-open the row exists to close).
|
|
if (finding['kind'] === 'unverified') {
|
|
addIssue(
|
|
'warning',
|
|
'W020',
|
|
`Worktree health check degraded: could not stat ${finding['path'] as string} — presence/staleness could not be verified`,
|
|
'Check filesystem permissions on the worktree path, or investigate why statSync failed for it',
|
|
);
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* git worktree not available or not a git repo — skip silently */
|
|
}
|
|
|
|
try {
|
|
const phaseConvention = (() => {
|
|
if (!fs.existsSync(configPath)) return null;
|
|
try {
|
|
const configRaw = fs.readFileSync(configPath, 'utf-8');
|
|
const configParsed = JSON.parse(configRaw) as Record<string, unknown>;
|
|
return (configParsed['phase_id_convention'] as string | undefined) || null;
|
|
} catch {
|
|
return null;
|
|
}
|
|
})();
|
|
if (phaseConvention === 'milestone-prefixed') {
|
|
if (fs.existsSync(roadmapPath)) {
|
|
const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
|
|
const mismatches = checkMilestonePrefixMismatches(roadmapContent, {
|
|
getMilestoneFromPhaseId: getMilestoneFromPhaseId,
|
|
});
|
|
for (const mm of mismatches) {
|
|
addIssue(
|
|
'warning',
|
|
'W021',
|
|
`Phase ${mm.phaseId}: integer prefix implies ${mm.expectedMilestone} but listed under ${mm.foundInMilestone}`,
|
|
'Run `gsd-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default)',
|
|
);
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* W021 check is advisory — skip on error */
|
|
}
|
|
|
|
const milestonesPath = path.join(rootBase, 'MILESTONES.md');
|
|
const milestonesArchiveDir = path.join(rootBase, 'milestones');
|
|
const missingFromRegistry: string[] = [];
|
|
try {
|
|
if (fs.existsSync(milestonesArchiveDir)) {
|
|
const archiveFiles = fs.readdirSync(milestonesArchiveDir);
|
|
const archivedVersions = archiveFiles
|
|
.map((f) => f.match(/^(v\d+\.\d+(?:\.\d+)?)-ROADMAP\.md$/))
|
|
.filter(Boolean)
|
|
.map((m) => m![1]);
|
|
|
|
if (archivedVersions.length > 0) {
|
|
const registryContent = fs.existsSync(milestonesPath)
|
|
? fs.readFileSync(milestonesPath, 'utf-8')
|
|
: '';
|
|
for (const ver of archivedVersions) {
|
|
if (!registryContent.includes(`## ${ver}`)) {
|
|
missingFromRegistry.push(ver);
|
|
}
|
|
}
|
|
if (missingFromRegistry.length > 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W018',
|
|
`MILESTONES.md missing ${missingFromRegistry.length} archived milestone(s): ${missingFromRegistry.join(', ')}`,
|
|
`Run ${slash('health')} --backfill to synthesize missing entries from archive snapshots`,
|
|
true,
|
|
);
|
|
repairs.push('backfillMilestones');
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* intentionally empty — milestone sync check is advisory */
|
|
}
|
|
|
|
try {
|
|
const entries = fs.readdirSync(rootBase, { withFileTypes: true });
|
|
for (const entry of entries) {
|
|
if (!entry.isFile()) continue;
|
|
if (!entry.name.endsWith('.md')) continue;
|
|
if (!isCanonicalPlanningFile(entry.name)) {
|
|
addIssue(
|
|
'warning',
|
|
'W019',
|
|
`Unrecognized .planning/ file: ${entry.name} — not a canonical GSD artifact`,
|
|
'Move to .planning/milestones/ archive subdir or delete if stale. See templates/README.md for the canonical artifact list.',
|
|
false,
|
|
);
|
|
}
|
|
}
|
|
} catch {
|
|
/* artifact check is advisory — skip on error */
|
|
}
|
|
|
|
try {
|
|
if (fs.existsSync(statePath) && fs.existsSync(roadmapPath)) {
|
|
const stateRaw = fs.readFileSync(statePath, 'utf-8');
|
|
const statusMatch = stateRaw.match(/^status:\s*(.+)/im);
|
|
const stateStatus = statusMatch ? statusMatch[1].trim().toLowerCase() : '';
|
|
const isMarkedComplete = /milestone complete|archived/.test(stateStatus);
|
|
if (isMarkedComplete) {
|
|
const roadmapRaw = fs.readFileSync(roadmapPath, 'utf-8');
|
|
const scopedContent = extractCurrentMilestone(roadmapRaw, cwd);
|
|
// #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
|
|
const phasePattern = new RegExp(`#{2,4}\\s*Phase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
|
|
const unstarted: string[] = [];
|
|
let pm: RegExpExecArray | null;
|
|
// Non-hoisted: load-order matters (circular dep guard)
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
|
|
const planningWorkspace2 = require('./planning-workspace.cjs') as typeof planningWorkspace;
|
|
const phasesDir2 = planningWorkspace2.planningPaths(cwd).phases;
|
|
const phaseDirNames2 = (() => {
|
|
try {
|
|
return fs
|
|
.readdirSync(phasesDir2, { withFileTypes: true })
|
|
.filter((e) => e.isDirectory())
|
|
.map((e) => e.name);
|
|
} catch {
|
|
return [];
|
|
}
|
|
})();
|
|
while ((pm = phasePattern.exec(scopedContent)) !== null) {
|
|
const phaseNum = pm[1];
|
|
const normalizedPh = normalizePhaseName(phaseNum);
|
|
const hasDirectory = phaseDirNames2.some((d) => phaseTokenMatches(d, normalizedPh));
|
|
if (!hasDirectory) {
|
|
unstarted.push(phaseNum);
|
|
}
|
|
}
|
|
if (unstarted.length > 0) {
|
|
addIssue(
|
|
'warning',
|
|
'W021',
|
|
`STATE says milestone complete but ROADMAP lists ${unstarted.length} unstarted phase(s) (e.g. Phase ${unstarted[0]})`,
|
|
'Run validate consistency or re-run complete-milestone after verifying all phases are done',
|
|
);
|
|
}
|
|
}
|
|
}
|
|
} catch {
|
|
/* W021 check is advisory — skip on error */
|
|
}
|
|
|
|
// ─── Perform repairs if requested ─────────────────────────────────────────
|
|
const repairActions: Record<string, unknown>[] = [];
|
|
if (options['repair'] && repairs.length > 0) {
|
|
for (const repair of repairs) {
|
|
try {
|
|
switch (repair) {
|
|
case 'createConfig':
|
|
case 'resetConfig': {
|
|
const defaults = {
|
|
model_profile: CONFIG_DEFAULTS.model_profile,
|
|
commit_docs: CONFIG_DEFAULTS.commit_docs,
|
|
search_gitignored: CONFIG_DEFAULTS.search_gitignored,
|
|
branching_strategy: CONFIG_DEFAULTS.branching_strategy,
|
|
phase_branch_template: CONFIG_DEFAULTS.phase_branch_template,
|
|
milestone_branch_template: CONFIG_DEFAULTS.milestone_branch_template,
|
|
quick_branch_template: CONFIG_DEFAULTS.quick_branch_template,
|
|
workflow: {
|
|
research: CONFIG_DEFAULTS.research,
|
|
plan_check: CONFIG_DEFAULTS.plan_checker,
|
|
verifier: CONFIG_DEFAULTS.verifier,
|
|
nyquist_validation: CONFIG_DEFAULTS.nyquist_validation,
|
|
},
|
|
parallelization: CONFIG_DEFAULTS.parallelization,
|
|
brave_search: CONFIG_DEFAULTS.brave_search,
|
|
};
|
|
platformWriteSync(configPath, JSON.stringify(defaults, null, 2));
|
|
repairActions.push({ action: repair, success: true, path: 'config.json' });
|
|
break;
|
|
}
|
|
case 'regenerateState': {
|
|
if (fs.existsSync(statePath)) {
|
|
const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
|
|
const backupPath = `${statePath}.bak-${timestamp}`;
|
|
fs.copyFileSync(statePath, backupPath);
|
|
repairActions.push({ action: 'backupState', success: true, path: backupPath });
|
|
}
|
|
const milestone = getMilestoneInfo(cwd).value;
|
|
const projectRef = path
|
|
.relative(cwd, path.join(rootBase, 'PROJECT.md'))
|
|
.split(path.sep)
|
|
.join('/');
|
|
let stateContent = `# Session State\n\n`;
|
|
stateContent += `## Project Reference\n\n`;
|
|
stateContent += `See: ${projectRef}\n\n`;
|
|
stateContent += `## Position\n\n`;
|
|
stateContent += `**Milestone:** ${milestone?.version ?? ''} ${milestone?.name ?? ''}\n`;
|
|
stateContent += `**Current phase:** (determining...)\n`;
|
|
stateContent += `**Status:** Resuming\n\n`;
|
|
stateContent += `## Session Log\n\n`;
|
|
stateContent += `- ${realClock.localToday()}: STATE.md regenerated by ${slash('health')} --repair\n`;
|
|
writeStateMd(statePath, stateContent, cwd);
|
|
repairActions.push({ action: repair, success: true, path: 'STATE.md' });
|
|
break;
|
|
}
|
|
case 'addNyquistKey': {
|
|
if (fs.existsSync(configPath)) {
|
|
try {
|
|
const configRaw = fs.readFileSync(configPath, 'utf-8');
|
|
const configParsed = JSON.parse(configRaw) as Record<string, unknown>;
|
|
if (!configParsed['workflow']) configParsed['workflow'] = {};
|
|
const wf = configParsed['workflow'] as Record<string, unknown>;
|
|
if (wf['nyquist_validation'] === undefined) {
|
|
wf['nyquist_validation'] = true;
|
|
platformWriteSync(configPath, JSON.stringify(configParsed, null, 2));
|
|
}
|
|
repairActions.push({ action: repair, success: true, path: 'config.json' });
|
|
} catch (err) {
|
|
repairActions.push({
|
|
action: repair,
|
|
success: false,
|
|
error: err instanceof Error ? err.message : String(err),
|
|
});
|
|
}
|
|
}
|
|
break;
|
|
}
|
|
case 'addAiIntegrationPhaseKey': {
|
|
if (fs.existsSync(configPath)) {
|
|
try {
|
|
const configRaw = fs.readFileSync(configPath, 'utf-8');
|
|
const configParsed = JSON.parse(configRaw) as Record<string, unknown>;
|
|
if (!configParsed['workflow']) configParsed['workflow'] = {};
|
|
const wf = configParsed['workflow'] as Record<string, unknown>;
|
|
if (wf['ai_integration_phase'] === undefined) {
|
|
wf['ai_integration_phase'] = true;
|
|
platformWriteSync(configPath, JSON.stringify(configParsed, null, 2));
|
|
}
|
|
repairActions.push({ action: repair, success: true, path: 'config.json' });
|
|
} catch (err) {
|
|
repairActions.push({
|
|
action: repair,
|
|
success: false,
|
|
error: err instanceof Error ? err.message : String(err),
|
|
});
|
|
}
|
|
}
|
|
break;
|
|
}
|
|
case 'backfillMilestones': {
|
|
if (!options['backfill'] && !options['repair']) break;
|
|
const today = realClock.localToday();
|
|
let backfilled = 0;
|
|
for (const ver of missingFromRegistry) {
|
|
try {
|
|
const snapshotPath = path.join(milestonesArchiveDir, `${ver}-ROADMAP.md`);
|
|
const snapshot = safeReadFile(snapshotPath);
|
|
const titleMatch = snapshot && snapshot.match(/^#\s+(.+)$/m);
|
|
const milestoneName = titleMatch
|
|
? titleMatch[1].replace(/^Milestone\s+/i, '').replace(/^v[\d.]+\s*/, '').trim()
|
|
: ver;
|
|
const entry =
|
|
`## ${ver}${milestoneName && milestoneName !== ver ? ` ${milestoneName}` : ''} (Backfilled: ${today})\n\n**Note:** Synthesized from archive snapshot by \`${slash('health')} --backfill\`. Original completion date unknown.\n\n---\n\n`;
|
|
const milestonesContent = fs.existsSync(milestonesPath)
|
|
? fs.readFileSync(milestonesPath, 'utf-8')
|
|
: '';
|
|
if (!milestonesContent.trim()) {
|
|
platformWriteSync(milestonesPath, `# Milestones\n\n${entry}`);
|
|
} else {
|
|
const headerMatch = milestonesContent.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
|
|
if (headerMatch) {
|
|
const header = headerMatch[1];
|
|
const rest = milestonesContent.slice(header.length);
|
|
platformWriteSync(milestonesPath, header + entry + rest);
|
|
} else {
|
|
platformWriteSync(milestonesPath, entry + milestonesContent);
|
|
}
|
|
}
|
|
backfilled++;
|
|
} catch {
|
|
/* intentionally empty — partial backfill is acceptable */
|
|
}
|
|
}
|
|
repairActions.push({
|
|
action: repair,
|
|
success: true,
|
|
detail: `Backfilled ${backfilled} milestone(s) into MILESTONES.md`,
|
|
});
|
|
break;
|
|
}
|
|
}
|
|
} catch (err) {
|
|
repairActions.push({
|
|
action: repair,
|
|
success: false,
|
|
error: err instanceof Error ? err.message : String(err),
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
let status: string;
|
|
if (errors.length > 0) {
|
|
status = 'broken';
|
|
} else if (warnings.length > 0) {
|
|
status = 'degraded';
|
|
} else {
|
|
status = 'healthy';
|
|
}
|
|
|
|
const repairableCount =
|
|
errors.filter((e) => e.repairable).length + warnings.filter((w) => w.repairable).length;
|
|
|
|
const result: Record<string, unknown> = {
|
|
status,
|
|
errors,
|
|
warnings,
|
|
info,
|
|
repairable_count: repairableCount,
|
|
repairs_performed: repairActions.length > 0 ? repairActions : undefined,
|
|
};
|
|
output(result, raw);
|
|
return result;
|
|
}
|
|
|
|
function cmdValidateAgents(cwd: string, raw: boolean): void {
|
|
const runtime = resolveRuntime(cwd);
|
|
const agentStatus = checkAgentsInstalled(runtime, cwd);
|
|
const expected = Object.keys(MODEL_PROFILES);
|
|
// #3242 ADR-2313 D6 — additive: validates posture (never an Anthropic-flavored
|
|
// model or an orphaned reasoning-effort pin in a Codex agent .toml), not just
|
|
// presence. checkAgentsInstalled above is untouched.
|
|
const codexPosture = checkCodexModelPosture(runtime, cwd);
|
|
|
|
output(
|
|
{
|
|
agents_dir: agentStatus.agents_dir,
|
|
agents_found: agentStatus.agents_installed,
|
|
installed: agentStatus.installed_agents,
|
|
missing: agentStatus.missing_agents,
|
|
incomplete: agentStatus.incomplete_agents,
|
|
expected,
|
|
codex_posture: codexPosture,
|
|
},
|
|
raw,
|
|
);
|
|
}
|
|
|
|
function cmdVerifySchemaDrift(
|
|
cwd: string,
|
|
phaseArg: string,
|
|
skipFlag: boolean | undefined,
|
|
raw: boolean,
|
|
): void {
|
|
if (!phaseArg) {
|
|
error('Usage: verify schema-drift <phase> [--skip]');
|
|
return;
|
|
}
|
|
|
|
const pDir = planningDir(cwd);
|
|
const phasesDir = path.join(pDir, 'phases');
|
|
if (!fs.existsSync(phasesDir)) {
|
|
output({ block: false, drift_detected: false, blocking: false, message: 'No phases directory' }, raw);
|
|
return;
|
|
}
|
|
|
|
// Resolve the phase directory with the canonical phase-token matcher
|
|
// (phase-id.cjs), not a naive substring test. A bare `.includes(phaseArg)`
|
|
// lets a non-existent phase silently match a different phase whose directory
|
|
// name merely contains the requested token (e.g. "1" matching "11-expansion"),
|
|
// making the drift gate inspect the wrong phase. This mirrors find-phase /
|
|
// verify phase-completeness, which both use phaseTokenMatches. (#1571)
|
|
let phaseDir: string | null = null;
|
|
const normalizedPhase = normalizePhaseName(phaseArg);
|
|
const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
|
|
for (const entry of entries) {
|
|
if (entry.isDirectory() && phaseTokenMatches(entry.name, normalizedPhase)) {
|
|
phaseDir = path.join(phasesDir, entry.name);
|
|
break;
|
|
}
|
|
}
|
|
|
|
if (!phaseDir) {
|
|
const exact = path.join(phasesDir, phaseArg);
|
|
if (fs.existsSync(exact)) phaseDir = exact;
|
|
}
|
|
|
|
if (!phaseDir) {
|
|
output(
|
|
{ block: false, drift_detected: false, blocking: false, message: `Phase directory not found: ${phaseArg}` },
|
|
raw,
|
|
);
|
|
return;
|
|
}
|
|
|
|
// #3183: canonical LIVE plan/summary sets (root+nested,
|
|
// status: superseded EXCLUDED) from the single owner, rather than a
|
|
// root-only readdirSync filter — a superseded plan's claimed
|
|
// files_modified is no longer treated as an expected drift target, and
|
|
// nested (#3139 layout) plans/summaries are no longer invisible to the
|
|
// drift check.
|
|
const { planFiles, summaryFiles } = planScanMod.scanPhasePlans(phaseDir);
|
|
|
|
const allFiles: string[] = [];
|
|
for (const pf of planFiles) {
|
|
const content = fs.readFileSync(path.join(phaseDir, pf), 'utf-8');
|
|
const fmMatch = content.match(/files_modified:\s*\[([^\]]{0,8000})\]/);
|
|
if (fmMatch) {
|
|
const files = fmMatch[1].split(',').map((f) => f.trim()).filter(Boolean);
|
|
allFiles.push(...files);
|
|
}
|
|
}
|
|
|
|
let executionLog = '';
|
|
for (const sf of summaryFiles) {
|
|
executionLog += fs.readFileSync(path.join(phaseDir, sf), 'utf-8') + '\n';
|
|
}
|
|
|
|
const gitLog = execGit(['log', '--oneline', '--all', '-50'], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (gitLog.exitCode === 0) {
|
|
executionLog += '\n' + gitLog.stdout;
|
|
}
|
|
|
|
const result = checkSchemaDrift(allFiles, executionLog, { skipCheck: !!skipFlag }) as unknown as Record<string, unknown>;
|
|
|
|
const isSkipped = !!result['skipped'];
|
|
output(
|
|
{
|
|
// Uniform gate contract: `block` = true means "this gate's bad condition is met".
|
|
// When skipCheck is true (GSD_SKIP_SCHEMA_CHECK=true), the gate is bypassed —
|
|
// block must be false regardless of whether drift was detected.
|
|
// drift_detected and blocking are kept for compatibility.
|
|
block: isSkipped ? false : !!result['driftDetected'],
|
|
drift_detected: result['driftDetected'],
|
|
blocking: result['blocking'],
|
|
schema_files: result['schemaFiles'],
|
|
orms: result['orms'],
|
|
unpushed_orms: result['unpushedOrms'],
|
|
message: result['message'],
|
|
skipped: isSkipped,
|
|
},
|
|
raw,
|
|
);
|
|
}
|
|
|
|
function cmdVerifyCodebaseDrift(cwd: string, raw: boolean): void {
|
|
// Non-hoisted: load-order matters for circular dep guard
|
|
// eslint-disable-next-line @typescript-eslint/no-require-imports -- drift.cjs is an export= CommonJS module
|
|
const drift = require('./drift.cjs') as Record<string, unknown>;
|
|
|
|
const emit = (payload: unknown) => output(payload, raw);
|
|
|
|
try {
|
|
const codebaseDir = path.join(planningDir(cwd), 'codebase');
|
|
const structurePath = path.join(codebaseDir, 'STRUCTURE.md');
|
|
if (!fs.existsSync(structurePath)) {
|
|
emit({
|
|
// Uniform gate contract: block = action_required (false when skipped).
|
|
block: false,
|
|
skipped: true,
|
|
reason: 'no-structure-md',
|
|
action_required: false,
|
|
directive: 'none',
|
|
elements: [],
|
|
});
|
|
return;
|
|
}
|
|
|
|
let structureMd: string;
|
|
try {
|
|
structureMd = fs.readFileSync(structurePath, 'utf-8');
|
|
} catch (err) {
|
|
emit({
|
|
block: false,
|
|
skipped: true,
|
|
reason: 'cannot-read-structure-md: ' + (err instanceof Error ? err.message : String(err)),
|
|
action_required: false,
|
|
directive: 'none',
|
|
elements: [],
|
|
});
|
|
return;
|
|
}
|
|
|
|
const lastMapped = (drift['readMappedCommit'] as (p: string) => string | null)(structurePath);
|
|
|
|
const revProbe = execGit(['rev-parse', 'HEAD'], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (revProbe.exitCode !== 0) {
|
|
emit({
|
|
block: false,
|
|
skipped: true,
|
|
reason: 'not-a-git-repo',
|
|
action_required: false,
|
|
directive: 'none',
|
|
elements: [],
|
|
});
|
|
return;
|
|
}
|
|
|
|
const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
|
|
let base = lastMapped;
|
|
if (!base) {
|
|
base = EMPTY_TREE;
|
|
} else {
|
|
const verify = execGit(['cat-file', '-t', base], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (verify.exitCode !== 0) base = EMPTY_TREE;
|
|
}
|
|
|
|
const diff = execGit(['diff', '--name-status', base, 'HEAD'], { cwd }) as unknown as { exitCode: number; stdout: string };
|
|
if (diff.exitCode !== 0) {
|
|
emit({
|
|
block: false,
|
|
skipped: true,
|
|
reason: 'git-diff-failed',
|
|
action_required: false,
|
|
directive: 'none',
|
|
elements: [],
|
|
});
|
|
return;
|
|
}
|
|
|
|
const added: string[] = [];
|
|
const modified: string[] = [];
|
|
const deleted: string[] = [];
|
|
for (const line of diff.stdout.split(/\r?\n/)) {
|
|
if (!line.trim()) continue;
|
|
const m = line.match(/^([A-Z])\d*\t(.+?)(?:\t(.+))?$/);
|
|
if (!m) continue;
|
|
const status = m[1];
|
|
const file = m[3] || m[2];
|
|
if (status === 'A' || status === 'R' || status === 'C') added.push(file);
|
|
else if (status === 'M') modified.push(file);
|
|
else if (status === 'D') deleted.push(file);
|
|
}
|
|
|
|
// loadConfig() returns a flattened object — there is no nested `workflow`
|
|
// key. Read the raw config.json directly to access workflow-scoped keys,
|
|
// matching the pattern used in check-command-router.cts:readWorkflowConfig.
|
|
let wf: Record<string, unknown> | undefined;
|
|
try {
|
|
const rawCfg = JSON.parse(
|
|
fs.readFileSync(path.join(planningDir(cwd), 'config.json'), 'utf-8'),
|
|
) as Record<string, unknown>;
|
|
wf = rawCfg['workflow'] as Record<string, unknown> | undefined;
|
|
} catch {
|
|
wf = undefined;
|
|
}
|
|
const threshold =
|
|
Number.isInteger(wf?.drift_threshold) && (wf?.drift_threshold as number) >= 1
|
|
? (wf?.drift_threshold as number)
|
|
: 3;
|
|
const action = wf?.drift_action === 'auto-remap' ? 'auto-remap' : 'warn';
|
|
|
|
const driftResult = (drift['detectDrift'] as (opts: unknown) => Record<string, unknown>)({
|
|
addedFiles: added,
|
|
modifiedFiles: modified,
|
|
deletedFiles: deleted,
|
|
structureMd,
|
|
threshold,
|
|
action,
|
|
runtime: resolveRuntime(cwd),
|
|
});
|
|
|
|
const actionRequired = !!driftResult['actionRequired'];
|
|
emit({
|
|
// Uniform gate contract: block = action_required.
|
|
block: actionRequired,
|
|
skipped: !!driftResult['skipped'],
|
|
reason: driftResult['reason'] || null,
|
|
action_required: actionRequired,
|
|
directive: driftResult['directive'],
|
|
spawn_mapper: !!driftResult['spawnMapper'],
|
|
affected_paths: driftResult['affectedPaths'] || [],
|
|
elements: driftResult['elements'] || [],
|
|
threshold,
|
|
action,
|
|
last_mapped_commit: lastMapped,
|
|
message: driftResult['message'] || '',
|
|
});
|
|
} catch (err) {
|
|
emit({
|
|
block: false,
|
|
skipped: true,
|
|
reason: 'exception: ' + (err && err instanceof Error ? err.message : String(err)),
|
|
action_required: false,
|
|
directive: 'none',
|
|
elements: [],
|
|
});
|
|
}
|
|
}
|
|
|
|
export = {
|
|
scanNegativeGrepCommentEcho,
|
|
scanFileWideNegativeGateConflict,
|
|
cmdVerifySummary,
|
|
verifySummaryCore,
|
|
cmdVerifyPlanStructure,
|
|
cmdVerifyPhaseCompleteness,
|
|
cmdVerifyReferences,
|
|
cmdVerifyCommits,
|
|
cmdVerifyArtifacts,
|
|
cmdVerifyKeyLinks,
|
|
cmdValidateConsistency,
|
|
cmdValidateHealth,
|
|
cmdValidateAgents,
|
|
cmdVerifySchemaDrift,
|
|
cmdVerifyCodebaseDrift,
|
|
// Test seam (#1883): listMilestoneArchiveDirs is private and exercised through
|
|
// the validate command, which runs in a subprocess — an fs monkeypatch in the
|
|
// test process cannot reach it. Exposed under a leading underscore so the
|
|
// permission-error path can be unit-tested directly (no chmod 0o000).
|
|
_listMilestoneArchiveDirs: listMilestoneArchiveDirs,
|
|
};
|