@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/path-audit.test.cjs

@@ -0,0 +1,384 @@
+/**
+ * Path audit test — comprehensive gating test for all file categories.
+ *
+ * This test suite:
+ * 1. GATES on ALL file categories (workflows, templates, agents, references)
+ *    to prevent hardcoded .planning/ path constructions from creeping back in
+ * 2. GATES on library source files (path.join(cwd, '.planning') pattern)
+ * 3. Documents baselines for lib module raw string literals
+ *
+ * Allowlisted files (may legitimately reference .planning/):
+ * - workflows/init-product.md — creates and describes both layouts
+ * - workflows/help.md — user documentation explaining directory structure
+ *
+ * Allowlisted line patterns:
+ * - HTML comments: <!-- .planning/ ... -->
+ * - .gitignore example blocks containing .planning/
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert/strict).
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+// Root of the deliver-great-systems package (two levels up from bin/lib/)
+const DGS_ROOT = path.resolve(__dirname, '..', '..');
+
+// Root of the overall repo (one level above deliver-great-systems/)
+const REPO_ROOT = path.resolve(DGS_ROOT, '..');
+
+/**
+ * Comprehensive pattern: matches ANY .planning/ reference.
+ * Used for the broad gate tests across all file categories.
+ */
+const COMPREHENSIVE_PATTERN = /\.planning\//;
+
+/**
+ * Project-scoped path pattern: matches .planning/ followed by a project-scoped
+ * filename or directory name. These are paths that would be WRONG in a v2
+ * multi-project install because they resolve to the root instead of
+ * .planning/<project>/<path>.
+ */
+const PROJECT_SCOPED_PATTERN = /\.planning\/(?:STATE|ROADMAP|PROJECT(?!S\.md)|REQUIREMENTS|phases|archive|quick|todos|debug|research)/;
+
+/**
+ * Workflow files allowlisted from comprehensive .planning/ scanning.
+ * These files legitimately reference .planning/ for layout documentation.
+ */
+const ALLOWLISTED_WORKFLOW_FILES = [
+  'workflows/init-product.md',  // Creates and describes both layouts
+  'workflows/help.md',          // User documentation explaining directory structure
+];
+
+/**
+ * Reference files allowlisted from comprehensive .planning/ scanning.
+ * These files have legitimate .planning/ references in example content.
+ */
+const ALLOWLISTED_REFERENCE_FILES = [
+  'references/planning-config.md',  // Has .planning/ in .gitignore example block
+];
+
+/**
+ * Product-level paths that are intentionally at .planning/ root and should
+ * NOT be flagged by the audit.
+ */
+const SAFE_PRODUCT_PATHS = [
+  '.planning/config.json',
+  '.planning/PROJECTS.md',
+  '.planning/REPOS.md',
+  '.planning/codebase',
+];
+
+/**
+ * Recursively collect all .md files under a directory.
+ * @param {string} dir - Absolute path to scan
+ * @returns {string[]} Array of absolute file paths
+ */
+function collectMdFiles(dir) {
+  const results = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectMdFiles(fullPath));
+      } else if (entry.name.endsWith('.md')) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+    // Directory may not exist
+  }
+  return results;
+}
+
+/**
+ * Count lines matching the comprehensive .planning/ pattern in a set of files.
+ * Skips allowlisted files and allowlisted line patterns.
+ * @param {string[]} files - Array of absolute file paths
+ * @param {string[]} allowlistFiles - Basenames to skip entirely
+ * @returns {{ count: number, details: Array<{ file: string, line: number, text: string }> }}
+ */
+function countComprehensivePaths(files, allowlistFiles = []) {
+  let count = 0;
+  const details = [];
+
+  for (const filePath of files) {
+    // Skip allowlisted files
+    const relPath = path.relative(DGS_ROOT, filePath);
+    if (allowlistFiles.some(af => relPath === af || relPath.endsWith(af))) {
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Skip HTML comment lines
+      if (line.trimStart().startsWith('<!--')) continue;
+
+      if (COMPREHENSIVE_PATTERN.test(line)) {
+        count++;
+        details.push({
+          file: relPath,
+          line: i + 1,
+          text: line.trim().substring(0, 120),
+        });
+      }
+    }
+  }
+
+  return { count, details };
+}
+
+/**
+ * Count lines matching the project-scoped pattern in a set of files.
+ * Excludes HTML comment lines (starting with <!--).
+ * @param {string[]} files - Array of absolute file paths
+ * @returns {{ count: number, details: Array<{ file: string, line: number, text: string }> }}
+ */
+function countProjectScopedPaths(files) {
+  let count = 0;
+  const details = [];
+
+  for (const filePath of files) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Skip HTML comment lines
+      if (line.trimStart().startsWith('<!--')) continue;
+
+      if (PROJECT_SCOPED_PATTERN.test(line)) {
+        count++;
+        details.push({
+          file: path.relative(DGS_ROOT, filePath),
+          line: i + 1,
+          text: line.trim().substring(0, 120),
+        });
+      }
+    }
+  }
+
+  return { count, details };
+}
+
+/**
+ * Format violations for assertion error messages.
+ */
+function formatViolations(details) {
+  return details.map(d => `  ${d.file}:${d.line}: ${d.text}`).join('\n');
+}
+
+// ─── Comprehensive GATE Tests ───────────────────────────────────────────────
+
+describe('path audit: comprehensive .planning/ reference scanning', () => {
+
+  it('GATE: zero hardcoded .planning/ in workflow files (except allowlisted)', () => {
+    const workflowDir = path.join(DGS_ROOT, 'workflows');
+    const allFiles = collectMdFiles(workflowDir);
+    const { count, details } = countComprehensivePaths(allFiles, ALLOWLISTED_WORKFLOW_FILES);
+
+    if (count > 0) {
+      assert.fail(
+        `Found ${count} hardcoded .planning/ reference(s) in workflow files:\n${formatViolations(details)}\n\n` +
+        'All workflow files (except init-product.md and help.md) must use ${variable} notation.\n' +
+        'Replace .planning/STATE.md with ${state_path}, .planning/ROADMAP.md with ${roadmap_path}, etc.'
+      );
+    }
+
+    assert.equal(count, 0, 'Non-allowlisted workflow files should have zero .planning/ references');
+  });
+
+  it('GATE: zero hardcoded .planning/ in template files', () => {
+    const templateDir = path.join(DGS_ROOT, 'templates');
+    const allFiles = collectMdFiles(templateDir);
+    const { count, details } = countComprehensivePaths(allFiles);
+
+    if (count > 0) {
+      assert.fail(
+        `Found ${count} hardcoded .planning/ reference(s) in template files:\n${formatViolations(details)}\n\n` +
+        'Template files must use relative-from-planning-root paths (e.g., phases/XX-name/ not .planning/phases/XX-name/).\n' +
+        'For @ context references in prompt templates, use ${variable} notation.'
+      );
+    }
+
+    assert.equal(count, 0, 'Template files should have zero .planning/ references');
+  });
+
+  it('GATE: zero hardcoded .planning/ in agent files', () => {
+    const agentDir = path.join(REPO_ROOT, 'agents');
+    const allFiles = collectMdFiles(agentDir);
+    const { count, details } = countComprehensivePaths(allFiles);
+
+    if (count > 0) {
+      // Adjust paths for repo-relative display
+      const repoDetails = details.map(d => ({
+        ...d,
+        file: path.relative(REPO_ROOT, path.join(DGS_ROOT, d.file)),
+      }));
+      assert.fail(
+        `Found ${count} hardcoded .planning/ reference(s) in agent files:\n${formatViolations(repoDetails)}\n\n` +
+        'Agent files must use ${variable} notation resolved by orchestrators at runtime.\n' +
+        'Replace .planning/STATE.md with ${state_path}, .planning/phases/ with ${phase_dir}/, etc.'
+      );
+    }
+
+    assert.equal(count, 0, 'Agent files should have zero .planning/ references');
+  });
+
+  it('GATE: zero hardcoded .planning/ in reference files (except allowlisted)', () => {
+    const refDir = path.join(DGS_ROOT, 'references');
+    const allFiles = collectMdFiles(refDir);
+    const { count, details } = countComprehensivePaths(allFiles, ALLOWLISTED_REFERENCE_FILES);
+
+    if (count > 0) {
+      assert.fail(
+        `Found ${count} hardcoded .planning/ reference(s) in reference files:\n${formatViolations(details)}\n\n` +
+        'Reference files (except planning-config.md) must use ${variable} notation.\n' +
+        'They inherit variable context from parent workflow init output via @ inclusion.'
+      );
+    }
+
+    assert.equal(count, 0, 'Non-allowlisted reference files should have zero .planning/ references');
+  });
+
+  // ─── Library Source Gate Test ────────────────────────────────────────────
+
+  it('GATE: zero hardcoded path.join(cwd, .planning) in library source files', () => {
+    const libDir = path.join(DGS_ROOT, 'bin', 'lib');
+    const files = fs.readdirSync(libDir)
+      .filter(f => f.endsWith('.cjs'))
+      .filter(f => !f.endsWith('.test.cjs'))
+      .filter(f => f !== 'test-helpers.cjs')
+      .filter(f => f !== 'migration.cjs') // v1 migration intentionally uses hardcoded .planning/ paths
+      .map(f => path.join(libDir, f));
+
+    const HARDCODED_PATTERN = /path\.join\(\s*cwd\s*,\s*['"]\.planning['"]/;
+    const violations = [];
+
+    for (const filePath of files) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trimStart().startsWith('//')) continue;
+        if (lines[i].trimStart().startsWith('*')) continue;
+        if (HARDCODED_PATTERN.test(lines[i])) {
+          violations.push(`${path.basename(filePath)}:${i + 1}: ${lines[i].trim()}`);
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      assert.fail(`Found ${violations.length} hardcoded path.join(cwd, '.planning') references:\n${violations.join('\n')}`);
+    }
+  });
+
+  // ─── Allowlist Verification ─────────────────────────────────────────────
+
+  it('allowlisted workflow files exist and are minimal', () => {
+    for (const af of ALLOWLISTED_WORKFLOW_FILES) {
+      const fullPath = path.join(DGS_ROOT, af);
+      assert.ok(fs.existsSync(fullPath), `Allowlisted file should exist: ${af}`);
+    }
+
+    // Allowlist must stay minimal
+    assert.ok(
+      ALLOWLISTED_WORKFLOW_FILES.length <= 2,
+      `Workflow allowlist too large (${ALLOWLISTED_WORKFLOW_FILES.length}). ` +
+      'Only init-product.md and help.md should be allowlisted. Migrate others.'
+    );
+  });
+
+  it('allowlisted reference files exist and are minimal', () => {
+    for (const af of ALLOWLISTED_REFERENCE_FILES) {
+      const fullPath = path.join(DGS_ROOT, af);
+      assert.ok(fs.existsSync(fullPath), `Allowlisted file should exist: ${af}`);
+    }
+
+    // Allowlist must stay minimal
+    assert.ok(
+      ALLOWLISTED_REFERENCE_FILES.length <= 1,
+      `Reference allowlist too large (${ALLOWLISTED_REFERENCE_FILES.length}). ` +
+      'Only planning-config.md should be allowlisted.'
+    );
+  });
+
+  it('known safe paths are excluded from project-scoped audit', () => {
+    for (const safePath of SAFE_PRODUCT_PATHS) {
+      assert.equal(
+        PROJECT_SCOPED_PATTERN.test(safePath),
+        false,
+        safePath + ' should NOT match project-scoped pattern (it is product-level)'
+      );
+    }
+
+    assert.equal(SAFE_PRODUCT_PATHS.length, 4, 'Expected 4 known safe product-level paths');
+  });
+
+  // ─── Documentation Tests ───────────────────────────────────────────────
+
+  it('documents file counts across all categories', () => {
+    const workflowFiles = collectMdFiles(path.join(DGS_ROOT, 'workflows'));
+    const templateFiles = collectMdFiles(path.join(DGS_ROOT, 'templates'));
+    const agentFiles = collectMdFiles(path.join(REPO_ROOT, 'agents'));
+    const refFiles = collectMdFiles(path.join(DGS_ROOT, 'references'));
+
+    console.log(`Workflow files scanned: ${workflowFiles.length} (${ALLOWLISTED_WORKFLOW_FILES.length} allowlisted)`);
+    console.log(`Template files scanned: ${templateFiles.length} (0 allowlisted)`);
+    console.log(`Agent files scanned: ${agentFiles.length} (0 allowlisted)`);
+    console.log(`Reference files scanned: ${refFiles.length} (${ALLOWLISTED_REFERENCE_FILES.length} allowlisted)`);
+    console.log(`Total files gated: ${workflowFiles.length + templateFiles.length + agentFiles.length + refFiles.length}`);
+
+    assert.ok(workflowFiles.length > 0, 'Should find workflow files');
+    assert.ok(templateFiles.length > 0, 'Should find template files');
+    assert.ok(agentFiles.length > 0, 'Should find agent files');
+    assert.ok(refFiles.length > 0, 'Should find reference files');
+  });
+
+  it('documents current hardcoded path count in lib modules (non-test)', () => {
+    const libDir = path.join(DGS_ROOT, 'bin', 'lib');
+    let files;
+    try {
+      files = fs.readdirSync(libDir)
+        .filter(f => f.endsWith('.cjs'))
+        .filter(f => !f.endsWith('.test.cjs'))
+        .filter(f => f !== 'test-helpers.cjs')
+        .map(f => path.join(libDir, f));
+    } catch {
+      files = [];
+    }
+
+    // For lib modules, count raw string literals with .planning/ followed by
+    // project-scoped filenames (not inside path.join calls)
+    let count = 0;
+    const RAW_STRING_PATTERN = /['"`]\.planning\/(?:STATE|ROADMAP|PROJECT|REQUIREMENTS)\.md['"`]/;
+
+    for (const filePath of files) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      for (const line of lines) {
+        // Skip lines that use path.join (these are properly resolved)
+        if (line.includes('path.join')) continue;
+        // Skip comment-only lines
+        if (line.trimStart().startsWith('//')) continue;
+        if (line.trimStart().startsWith('*')) continue;
+
+        if (RAW_STRING_PATTERN.test(line)) {
+          count++;
+        }
+      }
+    }
+
+    console.log('Lib module raw .planning/ string literals: ' + count);
+    console.log('Lib modules scanned: ' + files.length);
+
+    // Documentation test -- always passes, just records the count
+    assert.equal(typeof count, 'number');
+  });
+});

package/deliver-great-systems/bin/lib/paths.cjs

@@ -0,0 +1,144 @@
+/**
+ * paths.cjs — Planning root detection and path constants
+ *
+ * LEAF MODULE: Zero DGS imports. Uses only Node.js built-in fs and path.
+ * This module sits at the bottom of the dependency graph to prevent
+ * circular dependencies with core.cjs and config.cjs.
+ *
+ * Exports:
+ *   getPlanningRoot(cwd) — Returns absolute path to planning root
+ *   getPaths(cwd)        — Returns frozen PATHS object with all standard paths
+ *   initPaths(cwd)       — Alias for getPaths (explicit cache population)
+ *   resetPaths()         — Clears the cwd-keyed cache (for test isolation)
+ *
+ * Detection cascade (getPlanningRoot):
+ *   1. .planning/dgs.config.json or .planning/config.json exists -> .planning/ layout
+ *   2. dgs.config.json at root with planningRoot: '.' -> root layout
+ *   3. dgs.config.json at root without planningRoot: '.' -> .planning/ layout
+ *   4. PROJECT.md at root AND no .planning/ directory -> root layout (auto-detect)
+ *   5. No signals -> .planning/ layout (default)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const _cache = new Map();
+
+/**
+ * The canonical directory name for the projects container.
+ * Single source of truth — all project path construction should reference
+ * this constant instead of using the string literal 'projects'.
+ */
+const PROJECTS_DIR = 'projects';
+
+/**
+ * Detect the planning root directory for the given cwd.
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {string} Absolute path to the planning root
+ */
+function getPlanningRoot(cwd) {
+  const resolved = path.resolve(cwd || process.cwd());
+  const dotPlanning = path.join(resolved, '.planning');
+
+  // Step 1: .planning/ layout — config files inside .planning/
+  if (
+    fs.existsSync(path.join(dotPlanning, 'dgs.config.json')) ||
+    fs.existsSync(path.join(dotPlanning, 'config.json'))
+  ) {
+    return dotPlanning;
+  }
+
+  // Step 2: Root layout — dgs.config.json at repo root
+  const rootConfigPath = path.join(resolved, 'dgs.config.json');
+  if (fs.existsSync(rootConfigPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(rootConfigPath, 'utf-8'));
+      if (config.planningRoot === '.') return resolved;
+    } catch {
+      // Malformed JSON — fall through to next check
+    }
+    // dgs.config.json exists but no planningRoot: '.' or malformed
+    // If malformed, we already fell through the try/catch
+    // If valid but no planningRoot: '.', return .planning/
+    // We need to distinguish: if we got here via catch, we should fall through
+    // If we got here via the normal flow (no planningRoot), return .planning/
+    return dotPlanning;
+  }
+
+  // Step 3: Auto-detect root layout — PROJECT.md at root, no .planning/ dir
+  if (
+    fs.existsSync(path.join(resolved, 'PROJECT.md')) &&
+    !fs.existsSync(dotPlanning)
+  ) {
+    return resolved;
+  }
+
+  // Step 4: Default — .planning/
+  return dotPlanning;
+}
+
+/**
+ * Get the frozen PATHS object for the given cwd.
+ * Results are cached per resolved absolute cwd.
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {Readonly<Object>} Frozen PATHS object with ROOT, PHASES, IDEAS, etc.
+ */
+function getPaths(cwd) {
+  const resolved = path.resolve(cwd || process.cwd());
+  if (_cache.has(resolved)) return _cache.get(resolved);
+
+  const root = getPlanningRoot(resolved);
+  const isRoot = (root === resolved);
+
+  const paths = Object.freeze({
+    ROOT: root,
+    PHASES: path.join(root, 'phases'),
+    IDEAS: path.join(root, 'ideas'),
+    SPECS: path.join(root, 'specs'),
+    JOBS: path.join(root, 'jobs'),
+    DOCS: path.join(root, 'docs'),
+    CODEBASE: path.join(root, 'codebase'),
+    MILESTONES: path.join(root, 'milestones'),
+    CONFIG: path.join(root, 'dgs.config.json'),
+    CONFIG_LEGACY: path.join(root, 'config.json'),
+    QUICK: path.join(root, 'quick'),
+    TODOS: path.join(root, 'todos'),
+    RESEARCH: path.join(root, 'research'),
+    DEBUG: path.join(root, 'debug'),
+    ARCHIVE: path.join(root, 'archive'),
+    PROJECTS: path.join(root, PROJECTS_DIR),
+    LAYOUT: isRoot ? 'root' : 'dotplanning',
+  });
+
+  _cache.set(resolved, paths);
+  return paths;
+}
+
+/**
+ * Populate the cache for the given cwd and return the PATHS object.
+ * Alias for getPaths — provides explicit intent for test setup.
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {Readonly<Object>} Frozen PATHS object
+ */
+function initPaths(cwd) {
+  return getPaths(cwd);
+}
+
+/**
+ * Clear all cached PATHS entries.
+ * Call in afterEach for test isolation between test cases.
+ */
+function resetPaths() {
+  _cache.clear();
+}
+
+module.exports = {
+  getPlanningRoot,
+  getPaths,
+  initPaths,
+  resetPaths,
+  PROJECTS_DIR,
+};