godpowers 2.4.2 → 2.5.0

package/lib/gate.js

@@ -0,0 +1,271 @@
+/**
+ * Executable Godpowers tier gates.
+ *
+ * Phase 1 gates are intentionally mechanical. They check expected artifacts on
+ * disk, run the shared artifact linter, and apply narrow tier-specific checks.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const artifactMap = require('./artifact-map');
+const linter = require('./artifact-linter');
+const router = require('./router');
+
+function relToAbs(projectRoot, relPath) {
+  return path.join(projectRoot, relPath);
+}
+
+function makeCheck(id, status, artifact, reason) {
+  return { id, status, artifact, reason };
+}
+
+function makeFinding(id, severity, artifact, reason, extra = {}) {
+  return { id, severity, artifact, reason, ...extra };
+}
+
+function emptySummary() {
+  return {
+    errors: 0,
+    warnings: 0,
+    infos: 0,
+    missing: 0,
+    checkedArtifacts: 0
+  };
+}
+
+function addFindingSummary(summary, severity) {
+  if (severity === 'error') summary.errors++;
+  else if (severity === 'warning') summary.warnings++;
+  else summary.infos++;
+}
+
+function lintArtifact(projectRoot, relPath, opts = {}) {
+  return linter.lintFile(relToAbs(projectRoot, relPath), {
+    projectRoot,
+    today: opts.today
+  });
+}
+
+function checkArtifacts(projectRoot, tier, artifacts, opts, result) {
+  for (const artifact of artifacts) {
+    const exists = fs.existsSync(relToAbs(projectRoot, artifact.path));
+    const artifactResult = {
+      path: artifact.path,
+      required: artifact.required,
+      exists,
+      lint: null
+    };
+    result.artifacts.push(artifactResult);
+
+    if (!exists) {
+      const status = artifact.required ? 'fail' : 'skipped';
+      result.checks.push(makeCheck(
+        `artifact:${tier}:${artifact.path}`,
+        status,
+        artifact.path,
+        artifact.required ? 'Required artifact is missing.' : 'Optional artifact is absent.'
+      ));
+      if (artifact.required) {
+        result.summary.missing++;
+        const finding = makeFinding(
+          `missing-artifact:${tier}:${artifact.path}`,
+          'error',
+          artifact.path,
+          'Required artifact is missing.'
+        );
+        result.findings.push(finding);
+        addFindingSummary(result.summary, finding.severity);
+      }
+      continue;
+    }
+
+    result.checks.push(makeCheck(
+      `artifact:${tier}:${artifact.path}`,
+      'pass',
+      artifact.path,
+      'Artifact exists on disk.'
+    ));
+
+    if (!artifact.lint) continue;
+    const lintResult = lintArtifact(projectRoot, artifact.path, opts);
+    artifactResult.lint = {
+      type: lintResult.type,
+      summary: lintResult.summary
+    };
+    result.summary.checkedArtifacts++;
+    for (const finding of lintResult.findings) {
+      result.findings.push({
+        ...finding,
+        id: `lint:${artifact.path}:${finding.code}:${finding.line}`,
+        artifact: artifact.path,
+        reason: finding.message
+      });
+      addFindingSummary(result.summary, finding.severity);
+    }
+    result.checks.push(makeCheck(
+      `lint:${tier}:${artifact.path}`,
+      lintResult.summary.errors > 0 ? 'fail' : 'pass',
+      artifact.path,
+      lintResult.summary.errors > 0
+        ? `${lintResult.summary.errors} lint error(s) block this gate.`
+        : `${lintResult.summary.warnings} warning(s), ${lintResult.summary.infos} info finding(s).`
+    ));
+  }
+}
+
+function extractPassedCommands(text) {
+  const commands = [];
+  for (const line of text.split(/\r?\n/)) {
+    const backtick = line.match(/`([^`\n]+)`/);
+    const labeled = line.match(/\bcommand\s*:\s*([^;]+?)(?:\s{2,}|\s+status\s*:|\s+result\s*:|$)/i);
+    const command = backtick ? backtick[1].trim() : (labeled ? labeled[1].trim() : null);
+    if (!command) continue;
+    if (/\b(pass|passed|green|success|succeeded|ok)\b/i.test(line)) {
+      commands.push(command);
+    }
+  }
+  return [...new Set(commands)];
+}
+
+function checkBuildEvidence(projectRoot, result) {
+  const relPath = '.godpowers/build/STATE.md';
+  const file = relToAbs(projectRoot, relPath);
+  if (!fs.existsSync(file)) return;
+  const text = fs.readFileSync(file, 'utf8');
+  const passedCommands = extractPassedCommands(text);
+  if (passedCommands.length === 0) {
+    const finding = makeFinding(
+      'build-verification-evidence',
+      'error',
+      relPath,
+      'Build state does not record exact project verification commands that passed.'
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+    result.checks.push(makeCheck(
+      'build-verification-evidence',
+      'fail',
+      relPath,
+      finding.reason
+    ));
+    return;
+  }
+  result.checks.push(makeCheck(
+    'build-verification-evidence',
+    'pass',
+    relPath,
+    `Build state records ${passedCommands.length} passed verification command(s).`
+  ));
+  result.summary.buildVerificationCommands = passedCommands;
+}
+
+function checkHardenCriticals(projectRoot, result) {
+  const relPath = '.godpowers/harden/FINDINGS.md';
+  const file = relToAbs(projectRoot, relPath);
+  if (!fs.existsSync(file)) return;
+  const pass = router.hasNoCriticalFindings(projectRoot);
+  if (!pass) {
+    const finding = makeFinding(
+      'harden-critical-findings',
+      'error',
+      relPath,
+      'Harden findings contain unresolved Critical findings or a blocked launch gate.'
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+  }
+  result.checks.push(makeCheck(
+    'harden-critical-findings',
+    pass ? 'pass' : 'fail',
+    relPath,
+    pass
+      ? 'No unresolved Critical findings or blocked launch gate found.'
+      : 'Unresolved Critical findings or a blocked launch gate block this gate.'
+  ));
+}
+
+function finalize(result) {
+  result.verdict = result.findings.some((finding) => finding.severity === 'error')
+    ? 'fail'
+    : 'pass';
+  return result;
+}
+
+function check(opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot || opts.project || process.cwd());
+  const tier = artifactMap.normalizeTier(opts.tier);
+  const artifacts = artifactMap.artifactsForTier(tier);
+  const result = {
+    tier,
+    verdict: 'fail',
+    project: projectRoot,
+    artifacts: [],
+    checks: [],
+    findings: [],
+    summary: emptySummary()
+  };
+
+  if (!tier || !artifacts) {
+    const supported = artifactMap.tiers().join(', ');
+    const finding = makeFinding(
+      'unknown-tier',
+      'error',
+      null,
+      `Unknown gate tier. Supported tiers: ${supported}.`
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+    result.checks.push(makeCheck('tier-supported', 'fail', null, finding.reason));
+    return finalize(result);
+  }
+
+  checkArtifacts(projectRoot, tier, artifacts, opts, result);
+  if (tier === 'build') checkBuildEvidence(projectRoot, result);
+  if (tier === 'harden') checkHardenCriticals(projectRoot, result);
+  return finalize(result);
+}
+
+async function checkAsync(opts = {}) {
+  return check(opts);
+}
+
+function exitCode(result) {
+  return result.verdict === 'pass' ? 0 : 1;
+}
+
+function render(result) {
+  const lines = [];
+  lines.push(`Godpowers Gate: ${result.tier || 'unknown'}`);
+  lines.push(`Verdict: ${result.verdict}`);
+  lines.push('');
+  lines.push('Artifacts:');
+  for (const artifact of result.artifacts) {
+    const marker = artifact.exists ? '+' : (artifact.required ? 'x' : '-');
+    lines.push(`  ${marker} ${artifact.path}${artifact.required ? '' : ' (optional)'}`);
+  }
+  lines.push('');
+  lines.push('Checks:');
+  for (const checkResult of result.checks) {
+    lines.push(`  ${checkResult.status.toUpperCase()} ${checkResult.id}: ${checkResult.reason}`);
+  }
+  if (result.findings.length > 0) {
+    lines.push('');
+    lines.push('Findings:');
+    for (const finding of result.findings) {
+      const where = finding.artifact ? `${finding.artifact}: ` : '';
+      lines.push(`  ${finding.severity.toUpperCase()} ${finding.id}: ${where}${finding.reason}`);
+    }
+  }
+  lines.push('');
+  lines.push(`Summary: ${result.summary.errors} error(s), ${result.summary.warnings} warning(s), ${result.summary.infos} info finding(s)`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  check,
+  checkAsync,
+  extractPassedCommands,
+  exitCode,
+  render
+};

package/lib/installer-args.js

@@ -8,7 +8,8 @@ const COMMANDS = new Set([
   'automation-status',
   'automation-setup',
   'dogfood',
-  'extension-scaffold'
+  'extension-scaffold',
+  'gate'
 ]);
 
 function parseArgs(argv, cwd = process.cwd()) {
@@ -23,6 +24,7 @@ function parseArgs(argv, cwd = process.cwd()) {
     extensionSkill: null,
     extensionAgent: null,
     extensionWorkflow: null,
+    tier: null,
     runtimes: [],
     global: false,
     local: false,
@@ -46,6 +48,12 @@ function parseArgs(argv, cwd = process.cwd()) {
       case '--brief':
         opts.brief = true;
         break;
+      case '--tier':
+        if (args[i + 1]) {
+          opts.tier = args[i + 1];
+          i++;
+        }
+        break;
       case '--project':
         if (args[i + 1]) {
           opts.project = path.resolve(args[i + 1]);
@@ -93,6 +101,8 @@ function parseArgs(argv, cwd = process.cwd()) {
           opts.extensionAgent = arg.slice('--agent='.length);
         } else if (arg.startsWith('--workflow=')) {
           opts.extensionWorkflow = arg.slice('--workflow='.length);
+        } else if (arg.startsWith('--tier=')) {
+          opts.tier = arg.slice('--tier='.length);
         } else if (arg.startsWith('--profile=')) {
           opts.profile = arg.slice('--profile='.length);
         } else if (arg.startsWith('--') && RUNTIMES[arg.slice(2)]) {

package/lib/route-quality-sync.js

@@ -89,6 +89,17 @@ const STANDARDS_EXEMPT_COMMANDS = new Set([
   '/god-tech-debt'
 ]);
 
+const TIER_GATE_COMMANDS = new Set([
+  '/god-prd',
+  '/god-design',
+  '/god-arch',
+  '/god-roadmap',
+  '/god-stack',
+  '/god-repo',
+  '/god-build',
+  '/god-harden'
+]);
+
 function read(projectRoot, relPath) {
   const file = path.join(projectRoot, relPath);
   if (!fs.existsSync(file)) return '';
@@ -166,6 +177,7 @@ function detect(projectRoot) {
   let typedOutcomeCount = 0;
   let standardsExemptCount = 0;
   let traceEventMissingCount = 0;
+  let gateCommandCount = 0;
 
   for (const routePath of routes) {
     const route = parseRoute(projectRoot, routePath);
@@ -253,6 +265,24 @@ function detect(projectRoot) {
         );
       }
     }
+
+    if (TIER_GATE_COMMANDS.has(command)) {
+      const tierName = command.replace('/god-', '');
+      const expected = `npx godpowers gate --tier=${tierName} --project=.`;
+      const actual = route.standards && route.standards['gate-command'];
+      if (actual === expected) {
+        gateCommandCount++;
+      } else {
+        addCheck(
+          checks,
+          `missing-gate-command-${command.replace(/[^a-z0-9]+/gi, '-')}`,
+          'stale',
+          routePath,
+          `${command} must declare standards.gate-command as ${expected}.`,
+          { spawn: 'god-auditor' }
+        );
+      }
+    }
   }
 
   if (symbolicCount === 0) {
@@ -287,6 +317,14 @@ function detect(projectRoot) {
       : `${traceEventMissingCount} agent-spawning routes are missing required trace events.`,
     { spawn: traceEventMissingCount === 0 ? null : 'god-auditor' }
   );
+  addCheck(
+    checks,
+    'gate-command-policy',
+    checks.some((check) => check.id.startsWith('missing-gate-command-')) ? 'stale' : 'fresh',
+    'routing/',
+    `${gateCommandCount} tier routes declare executable gate commands.`,
+    { spawn: checks.some((check) => check.id.startsWith('missing-gate-command-')) ? 'god-auditor' : null }
+  );
 
   const stale = checks.filter((check) => check.status !== 'fresh');
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "AI-powered development system: 112 slash commands and 40 specialist agents that take a project from raw idea to hardened production. Runs inside Claude Code, Codex, Cursor, Windsurf, Gemini, and 10+ other AI coding tools.",
   "bin": {
     "godpowers": "./bin/install.js"
@@ -23,9 +23,10 @@
     "test:diff": "node scripts/test-artifact-diff.js",
     "test:e2e": "node tests/integration/full-arc.test.js",
     "coverage": "c8 --reporter=text --reporter=lcov node scripts/run-tests.js",
+    "coverage:lib": "c8 --include=lib/**/*.js --check-coverage --lines 90 --reporter=text node scripts/run-tests.js",
     "test:audit": "npm audit --omit=dev && git diff --check && npm run test:surface",
     "pack:check": "node scripts/check-package-contents.js",
-    "release:check": "npm test && npm run test:audit && npm run pack:check",
+    "release:check": "npm run coverage:lib && npm run test:audit && npm run pack:check",
     "lint": "node scripts/static-check.js"
   },
   "keywords": [

package/references/orchestration/GOD-MODE-RUNBOOK.md

@@ -124,6 +124,25 @@ quality drift before declaring complete.
 ### --skip-hygiene
 Default. Skip the hygiene pass. Use when iterating quickly.
 
+## Tier transition gates
+
+After each tier skill returns, run the matching executable gate before starting
+the downstream tier:
+
+```bash
+npx godpowers gate --tier=prd --project=.
+npx godpowers gate --tier=design --project=.
+npx godpowers gate --tier=arch --project=.
+npx godpowers gate --tier=roadmap --project=.
+npx godpowers gate --tier=stack --project=.
+npx godpowers gate --tier=repo --project=.
+npx godpowers gate --tier=build --project=.
+npx godpowers gate --tier=harden --project=.
+```
+
+Run the design gate only when the project requires design. A non-zero gate exit
+pauses the project run for repair and blocks downstream tier dispatch.
+
 ## Mandatory final sync
 
 Regardless of flags, `/god-mode` always runs `/god-sync` before declaring

package/references/orchestration/GOD-NEXT-RUNBOOK.md

@@ -0,0 +1,32 @@
+# God Next Runbook
+
+This reference owns the detailed process notes for `/god-next`. The skill file stays a concise dispatch contract.
+
+## Invocation modes
+
+1. Post-completion routing reads `routing/<just-completed>.yaml`, applies success-path and conditional-next rules, runs any configured standards gate, and announces the next command.
+2. Pre-flight routing reads `routing/<target>.yaml`, evaluates prerequisites, and offers auto-completable prerequisites before the target command runs.
+3. Standalone routing reads disk state, uses `lib/router.js` for structural next steps, then uses recipes when the project is already in steady state.
+4. Intent-based routing uses `lib/recipes.js` for fuzzy text, ranked recipes, and state-aware command sequences.
+
+## Data sources
+
+Use runtime routing YAML, recipes, `lib/command-families.js`, `lib/router.js`, `lib/dashboard.js`, state.json, PROGRESS.md, CHECKPOINT.md, and completed artifacts.
+
+Read `.godpowers/prep/INITIAL-FINDINGS.md` and `.godpowers/prep/IMPORTED-CONTEXT.md` when present. Treat them as preparation context only.
+
+## Route detail
+
+When the suggestion is based on state.json, show a three-line path ahead: current state, next command, and the following gate if known.
+
+When prerequisites are missing, name the missing prerequisite, the auto-completable command when available, and the exact decision needed from the user.
+
+When a standards gate fails, show the failures, suggest `/god-redo` with feedback or `/god-skip` with a reason, and do not auto-progress.
+
+## Edge cases
+
+State drift routes to `/god-repair`. Safe sync blockers route to `/god-reconcile Release Truth And Safe Sync` before deploy, observe, harden, launch, broad migration, or resume work.
+
+Unresolved Critical harden findings block launch in default mode and under `--yolo`.
+
+In steady state, use the work-family ladders before raw route order so feature, hotfix, refactor, docs, dependency, audit, hygiene, and preflight intents resolve to the narrowest useful command.