Merge pull request #3607 from gsd-build/feat/3592-test-rewrite-text-existence-checks-into-

test: rewrite alias coverage as behavioral contract

.changeset/eager-foxes-zip.md

@@ -0,0 +1,5 @@
+---
+type: Changed
+pr: 3607
+---
+Rewrite generated alias coverage into behavioral gsd-tools dispatch tests and wire phase mvp-mode through the CJS route.

.github/workflows/test.yml

@@ -16,7 +16,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Static lint: no source-grep tests in the test suite.
+  # Static lint: test-suite and PR-check contracts.
   # Runs once (not per matrix node version) since it is a file-content check.
   lint-tests:
     runs-on: ubuntu-latest
@@ -33,6 +33,9 @@ jobs:
       - name: Lint — command contract (ADR-0002)
         shell: bash
         run: node scripts/lint-command-contract.cjs
+      - name: Lint — PR checks use projectDir
+        shell: bash
+        run: node scripts/lint-pr-check-project-dir.cjs
 
   test:
     runs-on: ${{ matrix.os }}

get-shit-done/bin/lib/core.cjs

@@ -465,6 +465,7 @@ function loadConfig(cwd, options = {}) {
       firecrawl: get('firecrawl') ?? defaults.firecrawl,
       exa_search: get('exa_search') ?? defaults.exa_search,
       tdd_mode: get('tdd_mode', { section: 'workflow', field: 'tdd_mode' }) ?? false,
+      mvp_mode: get('mvp_mode', { section: 'workflow', field: 'mvp_mode' }) ?? false,
       text_mode: get('text_mode', { section: 'workflow', field: 'text_mode' }) ?? defaults.text_mode,
       auto_advance: get('auto_advance', { section: 'workflow', field: 'auto_advance' }) ?? false,
       _auto_chain_active: get('_auto_chain_active', { section: 'workflow', field: '_auto_chain_active' }) ?? false,

get-shit-done/bin/lib/phase-command-router.cjs

@@ -15,6 +15,7 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
     error,
     unknownMessage: (_subcommand, available) => `Unknown phase subcommand. Available: ${available.join(', ')}`,
     handlers: {
+      'mvp-mode': () => phase.cmdPhaseMvpMode(cwd, args.slice(2), raw),
       'next-decimal': () => phase.cmdPhaseNextDecimal(cwd, args[2], raw),
       add: () => {
         let customId = null;

get-shit-done/bin/lib/phase.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, loadConfig, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches } = require('./core.cjs');
+const { escapeRegex, loadConfig, normalizePhaseName, phaseMarkdownRegexSource, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, toPosixPath, output, error, readSubdirectories, phaseTokenMatches, ERROR_REASON } = require('./core.cjs');
 const { platformWriteSync, platformReadSync, platformEnsureDir } = require('./shell-command-projection.cjs');
 const { planningDir, withPlanningLock } = require('./planning-workspace.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
@@ -211,6 +211,65 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
   }
 }
 
+function getRoadmapModeForPhase(cwd, phaseNum) {
+  const roadmapPath = path.join(planningDir(cwd), 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) return null;
+
+  const rawContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const milestoneContent = extractCurrentMilestone(rawContent, cwd);
+  const fullContent = stripShippedMilestones(rawContent);
+  const escapedPhase = phaseMarkdownRegexSource(phaseNum);
+  const phaseHeader = new RegExp(`#{2,4}\\s*Phase\\s+${escapedPhase}\\s*:`, 'i');
+
+  for (const content of [milestoneContent, fullContent]) {
+    const headerMatch = content.match(phaseHeader);
+    if (!headerMatch || headerMatch.index === undefined) continue;
+
+    const sectionStart = headerMatch.index;
+    const rest = content.slice(sectionStart);
+    const nextHeader = rest.slice(headerMatch[0].length).match(/\n#{2,4}\s+Phase\s+\S/i);
+    const sectionEnd = nextHeader ? sectionStart + headerMatch[0].length + nextHeader.index : content.length;
+    const section = content.slice(sectionStart, sectionEnd);
+    const modeMatch = section.match(/\*\*Mode(?::\*\*|\*\*:)\s*([^\n]+)/i);
+    if (modeMatch) return modeMatch[1].trim().toLowerCase();
+  }
+
+  return null;
+}
+
+function cmdPhaseMvpMode(cwd, args, raw) {
+  const phaseNum = args[0];
+  if (!phaseNum) {
+    error('Usage: phase.mvp-mode <phase-number> [--cli-flag]', ERROR_REASON.USAGE);
+  }
+
+  const cliFlagPresent = args.includes('--cli-flag');
+  const roadmapMode = getRoadmapModeForPhase(cwd, phaseNum);
+  const config = loadConfig(cwd);
+  const configMvpMode = Boolean(config.mvp_mode);
+
+  let active = false;
+  let source = 'none';
+  if (cliFlagPresent) {
+    active = true;
+    source = 'cli_flag';
+  } else if (roadmapMode === 'mvp') {
+    active = true;
+    source = 'roadmap';
+  } else if (configMvpMode) {
+    active = true;
+    source = 'config';
+  }
+
+  output({
+    active,
+    source,
+    roadmap_mode: roadmapMode,
+    config_mvp_mode: configMvpMode,
+    cli_flag_present: cliFlagPresent,
+  }, raw);
+}
+
 function cmdFindPhase(cwd, phase, raw) {
   if (!phase) {
     error('phase identifier required');
@@ -1356,6 +1415,7 @@ module.exports = {
   cmdPhasePlanIndex,
   cmdPhaseAdd,
   cmdPhaseAddBatch,
+  cmdPhaseMvpMode,
   cmdPhaseInsert,
   cmdPhaseRemove,
   cmdPhaseComplete,

package.json

@@ -71,6 +71,7 @@
     "lint:descriptions": "node scripts/lint-descriptions.cjs",
     "lint:skill-deps": "node scripts/lint-skill-deps.cjs",
     "lint:tests": "node scripts/lint-no-source-grep.cjs",
+    "lint:pr-checks": "node scripts/lint-pr-check-project-dir.cjs",
     "lint:changeset": "node scripts/changeset/lint.cjs",
     "changeset": "node scripts/changeset/new.cjs",
     "changelog:render": "node scripts/changeset/cli.cjs render",

scripts/lint-pr-check-project-dir.cjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+const DEFAULT_RELATIVE_FILES = [
+  '.github/workflows/test.yml',
+  '.github/workflows/pr-template-format.yml',
+  '.github/workflows/changeset-required.yml',
+  'scripts/lint-no-source-grep.cjs',
+  'scripts/lint-command-contract.cjs',
+  'scripts/lint-skill-deps.cjs',
+  'scripts/lint-descriptions.cjs',
+  'scripts/lint-shell-command-projection-drift.cjs',
+  'scripts/pr-template-policy.cjs',
+  'scripts/changeset/lint.cjs',
+];
+
+function defaultFiles(rootDir = ROOT) {
+  return DEFAULT_RELATIVE_FILES
+    .map((file) => path.join(rootDir, file))
+    .filter((file) => fs.existsSync(file));
+}
+
+function findForbiddenCwd(content, file = '<inline>') {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    const pattern = /\bcwd\b/g;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      findings.push({
+        file,
+        line: index + 1,
+        column: match.index + 1,
+        source: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function checkFiles(files, { rootDir = ROOT } = {}) {
+  const findings = [];
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8');
+    const rel = path.relative(rootDir, file);
+    findings.push(...findForbiddenCwd(content, rel));
+  }
+  return findings;
+}
+
+function formatFindings(findings) {
+  const lines = [
+    `ERROR lint-pr-check-project-dir: ${findings.length} forbidden cwd reference(s) found`,
+    '',
+    'PR checkers must use projectDir for project roots; cwd is forbidden in this layer.',
+    '',
+  ];
+
+  for (const finding of findings) {
+    lines.push(`  ${finding.file}:${finding.line}:${finding.column}`);
+    lines.push(`    ${finding.source}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const files = argv.length > 0 ? argv.map((file) => path.resolve(file)) : defaultFiles();
+  const findings = checkFiles(files);
+
+  if (findings.length === 0) {
+    console.log(`ok lint-pr-check-project-dir: ${files.length} PR check files checked`);
+    return 0;
+  }
+
+  process.stderr.write(formatFindings(findings));
+  return 1;
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  DEFAULT_RELATIVE_FILES,
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+  main,
+};

tests/feat-3251-command-aliases-manifest-coverage.test.cjs

@@ -10,7 +10,11 @@
 
 const { describe, test } = require('node:test');
 const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
 const path = require('path');
+const { spawnSync } = require('node:child_process');
 
 const REPO_ROOT = path.join(__dirname, '..');
 const COMMAND_ALIASES_FILE = path.join(
@@ -20,6 +24,7 @@ const COMMAND_ALIASES_FILE = path.join(
   'lib',
   'command-aliases.generated.cjs',
 );
+const GSD_TOOLS = path.join(REPO_ROOT, 'get-shit-done', 'bin', 'gsd-tools.cjs');
 
 const MISSING_14 = [
   'check.decision-coverage-plan',
@@ -126,3 +131,146 @@ describe('feat-3251: command-aliases.generated.cjs manifest coverage', () => {
     );
   });
 });
+
+function createProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-3251-dispatch-'));
+  fs.mkdirSync(path.join(dir, '.planning', 'phases'), { recursive: true });
+  return dir;
+}
+
+function runGsdTools(args, projectDir) {
+  return spawnSync(process.execPath, [GSD_TOOLS, ...args], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    timeout: 30000,
+    killSignal: 'SIGKILL',
+  });
+}
+
+function snapshotProjectState(projectDir) {
+  const files = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(projectDir, full);
+      if (entry.isDirectory()) walk(full);
+      else {
+        files.push({
+          path: rel,
+          sha256: crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex'),
+        });
+      }
+    }
+  }
+  walk(projectDir);
+  return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+describe('feat-3251: generated aliases dispatch through real gsd-tools behavior', () => {
+  test('phase.mvp-mode spaced alias resolves CLI flag precedence', () => {
+    const projectDir = createProject();
+    try {
+      const result = runGsdTools(['phase', 'mvp-mode', '1', '--cli-flag'], projectDir);
+      assert.equal(result.status, 0, result.stderr);
+
+      const output = JSON.parse(result.stdout);
+      assert.deepEqual(output, {
+        active: true,
+        source: 'cli_flag',
+        roadmap_mode: null,
+        config_mvp_mode: false,
+        cli_flag_present: true,
+      });
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test('phase.mvp-mode spaced alias resolves ROADMAP mode without mutating files', () => {
+    const projectDir = createProject();
+    try {
+      fs.writeFileSync(
+        path.join(projectDir, '.planning', 'ROADMAP.md'),
+        [
+          '# Roadmap',
+          '',
+          '## v1.0.0',
+          '',
+          '### Phase 1: User Auth',
+          '**Goal:** Users can sign in.',
+          '**Mode:** mvp',
+          '',
+        ].join('\n'),
+      );
+      const beforeFiles = snapshotProjectState(projectDir);
+
+      const result = runGsdTools(['phase', 'mvp-mode', '1'], projectDir);
+      assert.equal(result.status, 0, result.stderr);
+
+      const output = JSON.parse(result.stdout);
+      assert.equal(output.active, true);
+      assert.equal(output.source, 'roadmap');
+      assert.equal(output.roadmap_mode, 'mvp');
+      assert.equal(output.config_mvp_mode, false);
+      assert.equal(output.cli_flag_present, false);
+      assert.deepEqual(snapshotProjectState(projectDir), beforeFiles);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test('phase.mvp-mode ROADMAP lookup stops before custom-id next phase', () => {
+    const projectDir = createProject();
+    try {
+      fs.writeFileSync(
+        path.join(projectDir, '.planning', 'ROADMAP.md'),
+        [
+          '# Roadmap',
+          '',
+          '## v1.0.0',
+          '',
+          '### Phase 1: Numeric Phase',
+          '**Goal:** Users can sign in.',
+          '',
+          '### Phase custom-alpha: Custom Phase',
+          '**Goal:** Custom work.',
+          '**Mode:** mvp',
+          '',
+        ].join('\n'),
+      );
+      const beforeFiles = snapshotProjectState(projectDir);
+
+      const result = runGsdTools(['phase', 'mvp-mode', '1'], projectDir);
+      assert.equal(result.status, 0, result.stderr);
+
+      const output = JSON.parse(result.stdout);
+      assert.equal(output.active, false);
+      assert.equal(output.source, 'none');
+      assert.equal(output.roadmap_mode, null);
+      assert.deepEqual(snapshotProjectState(projectDir), beforeFiles);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  test('phase.mvp-mode JSON error is typed and leaves project files untouched', () => {
+    const projectDir = createProject();
+    try {
+      const beforeFiles = snapshotProjectState(projectDir);
+      const result = runGsdTools(['--json-errors', 'phase', 'mvp-mode'], projectDir);
+      assert.notEqual(result.status, 0);
+      assert.equal(result.stdout, '');
+
+      const error = JSON.parse(result.stderr);
+      assert.deepEqual(Object.keys(error).sort(), ['message', 'ok', 'reason']);
+      assert.equal(error.ok, false);
+      assert.equal(error.reason, 'usage');
+      assert.equal(typeof error.message, 'string');
+      assert.equal(/\n\s*at\s/.test(result.stderr), false, 'non-debug failure must not print a stack trace');
+      assert.deepEqual(snapshotProjectState(projectDir), beforeFiles);
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});

tests/lint-pr-check-project-dir.test.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const LINT_SCRIPT = path.join(ROOT, 'scripts', 'lint-pr-check-project-dir.cjs');
+
+const {
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+} = require(LINT_SCRIPT);
+
+function createFixtureDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-pr-check-lint-'));
+}
+
+function runLint(args = []) {
+  return spawnSync(process.execPath, [LINT_SCRIPT, ...args], { encoding: 'utf8' });
+}
+
+describe('lint-pr-check-project-dir', () => {
+  test('flags cwd parameters and shorthand properties', () => {
+    const findings = findForbiddenCwd(
+      [
+        'function runCheck(args, cwd) {',
+        '  return spawnSync(process.execPath, args, { cwd });',
+        '}',
+      ].join('\n'),
+      'fixture.cjs',
+    );
+
+    assert.deepEqual(
+      findings.map((finding) => [finding.line, finding.column]),
+      [
+        [1, 25],
+        [2, 46],
+      ],
+    );
+  });
+
+  test('flags cwd option keys even when the value is projectDir', () => {
+    const findings = findForbiddenCwd(
+      [
+        'function runCheck(args, projectDir) {',
+        '  return spawnSync(process.execPath, args, { cwd: projectDir });',
+        '}',
+      ].join('\n'),
+      'fixture.cjs',
+    );
+
+    assert.deepEqual(findings, [
+      {
+        file: 'fixture.cjs',
+        line: 2,
+        column: 46,
+        source: 'return spawnSync(process.execPath, args, { cwd: projectDir });',
+      },
+    ]);
+  });
+
+  test('allows projectDir project-root naming without cwd references', () => {
+    const findings = findForbiddenCwd(
+      [
+        'function checkProject(args, projectDir) {',
+        '  return runProjectCheck(args, projectDir);',
+        '}',
+      ].join('\n'),
+      'fixture.cjs',
+    );
+
+    assert.deepEqual(findings, []);
+  });
+
+  test('formats diagnostics with file, line, and source', () => {
+    const output = formatFindings([
+      {
+        file: 'scripts/example.cjs',
+        line: 12,
+        column: 7,
+        source: 'const cwd = projectDir;',
+      },
+    ]);
+
+    assert.match(output, /ERROR lint-pr-check-project-dir: 1 forbidden cwd reference/);
+    assert.match(output, /scripts\/example\.cjs:12:7/);
+    assert.match(output, /const cwd = projectDir;/);
+    assert.match(output, /projectDir/);
+  });
+
+  test('checks the real PR-check files without violations', () => {
+    const files = defaultFiles(ROOT);
+    assert.ok(files.length > 0, 'expected default PR-check files');
+    assert.deepEqual(checkFiles(files, { rootDir: ROOT }), []);
+  });
+
+  test('CLI exits non-zero when a passed file contains cwd', () => {
+    const dir = createFixtureDir();
+    try {
+      const file = path.join(dir, 'bad-check.cjs');
+      fs.writeFileSync(file, 'const cwd = process.env.PROJECT_DIR;\n');
+
+      const result = runLint([file]);
+
+      assert.notStrictEqual(result.status, 0);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('script parses without syntax errors', () => {
+    const result = spawnSync(process.execPath, ['--check', LINT_SCRIPT], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  });
+});