godpowers 2.6.0 → 2.7.0

package/agents/god-updater.md

@@ -54,13 +54,13 @@ After feature work, every artifact that was impacted needs to reflect reality.
 - Validate have-nots S-01 through S-05
 
 ### DEPLOY update (if reconciler said "needs-extension")
-- Update deploy/STATE.md
+- Update `.godpowers/state.json` deploy evidence
 - Document new env vars
 - Update CI/CD config notes
 - Have-nots D-01 through D-08
 
 ### OBSERVE update (if reconciler said "needs-slo" or "needs-alert")
-- Update observe/STATE.md
+- Update `.godpowers/state.json` observe evidence
 - Define new SLO with error budget policy
 - Define new alert with runbook reference
 - Have-nots OB-01 through OB-08
@@ -71,7 +71,7 @@ After feature work, every artifact that was impacted needs to reflect reality.
 - Have-nots H-01 through H-11
 
 ### LAUNCH update (if reconciler said "copy-update" or "new-launch")
-- Update launch/STATE.md
+- Update `.godpowers/state.json` launch evidence
 - Update landing copy if user-visible
 - Substitution-test new copy
 
@@ -260,8 +260,8 @@ Updated:
 - arch/ARCH.md: added ADR-007 (auth refactor)
 - arch/adr/007-auth-refactor.md: created
 - roadmap/ROADMAP.md: Milestone 2 marked complete
-- deploy/STATE.md: added STRIPE_WEBHOOK_SECRET env var
-- observe/STATE.md: added SLO for /api/stripe-webhook (99.5%)
+- state.json tier-3.deploy: added STRIPE_WEBHOOK_SECRET env var
+- state.json tier-3.observe: added SLO for /api/stripe-webhook (99.5%)
 - backlog/BACKLOG.md: resolved entry "Stripe webhook handling"
 - todos/TODOS.md: marked "wire stripe events" as done
 - threads/auth-migration.md: appended progress note

package/bin/install.js

@@ -51,6 +51,7 @@ function showHelp() {
   log('Commands:');
   log('  status               Show the Godpowers Dashboard for a project');
   log('  next                 Show the dashboard and recommended next command');
+  log('  state advance        Update one tracked Godpowers state step');
   log('  gate                 Check a tier artifact gate');
   log('  mcp-info             Show read-only MCP companion setup instructions');
   log('  quick-proof          Show a runnable proof from the shipped fixture');
@@ -65,7 +66,9 @@ function showHelp() {
   }
   log('');
   log('Options:');
-  log('  --project=<path>     Project root for status, next, proof, or automation commands');
+  log('  --project=<path>     Project root for status, next, state, proof, or automation commands');
+  log('  --step=<name>        Step for state advance, such as prd or tier-1.prd');
+  log('  --status=<status>    Status for state advance');
   log('  --tier=<name>        Tier for gate: prd, design, arch, roadmap, stack, repo, build, or harden');
   log('  --json               Emit JSON for status, next, proof, or automation commands');
   log('  --brief              Render compact output for status, next, or proof');
@@ -100,6 +103,7 @@ function showHelp() {
   log('Examples:');
   log('  npx godpowers status --project=.');
   log('  npx godpowers next --project=.');
+  log('  npx godpowers state advance --step=prd --status=done --project=.');
   log('  npx godpowers gate --tier=prd --project=.');
   log('  npx godpowers mcp-info --project=.');
   log('  npx godpowers quick-proof --project=.');
@@ -216,6 +220,7 @@ module.exports = {
   runMcpInfoCommand: cliDispatch.runMcpInfoCommand,
   runExtensionScaffoldCommand: cliDispatch.runExtensionScaffoldCommand,
   runGateCommand: cliDispatch.runGateCommand,
+  runStateCommand: cliDispatch.runStateCommand,
   applyDefaultRuntimeSelection,
   runInstall,
   runUninstall,

package/fixtures/gate/build-pass/.godpowers/state.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://godpowers.dev/schema/state.v1.json",
+  "version": "1.0.0",
+  "project": {
+    "name": "build-pass",
+    "started": "2026-06-10T00:00:00.000Z"
+  },
+  "tiers": {
+    "tier-2": {
+      "build": {
+        "status": "done",
+        "updated": "2026-06-10T18:08:00.000Z",
+        "artifact": "build/STATE.md",
+        "verification": {
+          "commands": [
+            {
+              "command": "npm test",
+              "status": "pass",
+              "exitCode": 0,
+              "ranAt": "2026-06-10T18:07:00.000Z"
+            },
+            {
+              "command": "npm run lint",
+              "status": "pass",
+              "exitCode": 0,
+              "ranAt": "2026-06-10T18:07:30.000Z"
+            }
+          ]
+        }
+      }
+    }
+  }
+}

package/lib/README.md

@@ -9,6 +9,8 @@ package-level integrations.
 | Module | Purpose |
 |--------|---------|
 | `state.js` | Read, initialize, validate, and write `.godpowers/state.json`. |
+| `state-views.js` | Generate managed markdown views such as `.godpowers/PROGRESS.md` and Godpowers-owned per-tier `STATE.md` files from `state.json`. |
+| `state-advance.js` | Mutate one tracked state step through locking and generated state view refresh. |
 | `state-lock.js` | Coordinate state writes with a lock file. |
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
 | `frontmatter.js` | Parse shared markdown YAML frontmatter for skills, agents, Pillars, checkpoints, and design specs. |

package/lib/artifact-map.js

@@ -9,7 +9,7 @@ const TIER_ARTIFACTS = {
   design: [
     { path: 'DESIGN.md', required: true, lint: true },
     { path: 'PRODUCT.md', required: false, lint: true },
-    { path: '.godpowers/design/STATE.md', required: true, lint: true }
+    { path: '.godpowers/state.json', required: true, lint: false }
   ],
   arch: [
     { path: '.godpowers/arch/ARCH.md', required: true, lint: true }
@@ -24,13 +24,18 @@ const TIER_ARTIFACTS = {
     { path: '.godpowers/repo/AUDIT.md', required: true, lint: true }
   ],
   build: [
-    { path: '.godpowers/build/STATE.md', required: true, lint: true }
+    { path: '.godpowers/state.json', required: true, lint: false }
   ],
   harden: [
     { path: '.godpowers/harden/FINDINGS.md', required: true, lint: true }
   ]
 };
 
+const TIER_STATE_STEPS = {
+  design: { tierKey: 'tier-1', subStepKey: 'design' },
+  build: { tierKey: 'tier-2', subStepKey: 'build' }
+};
+
 function normalizeTier(tier) {
   if (!tier) return null;
   return String(tier).replace(/^\/?god-/, '').toLowerCase();
@@ -51,10 +56,17 @@ function requiredArtifactsForTier(tier) {
   return artifacts ? artifacts.filter((artifact) => artifact.required) : null;
 }
 
+function stateStepForTier(tier) {
+  const key = normalizeTier(tier);
+  if (!key || !TIER_STATE_STEPS[key]) return null;
+  return { ...TIER_STATE_STEPS[key] };
+}
+
 module.exports = {
   TIER_ARTIFACTS,
   normalizeTier,
   tiers,
   artifactsForTier,
-  requiredArtifactsForTier
+  requiredArtifactsForTier,
+  stateStepForTier
 };

package/lib/cli-dispatch.js

@@ -4,6 +4,7 @@
 
 const gate = require('./gate');
 const identity = require('./package-identity');
+const stateAdvance = require('./state-advance');
 
 const VERSION = identity.PACKAGE_VERSION;
 
@@ -140,9 +141,45 @@ function runGateCommand(opts) {
   }
 }
 
+function runStateCommand(opts) {
+  if (opts.stateAction !== 'advance') {
+    const result = {
+      command: 'state',
+      verdict: 'fail',
+      project: opts.project,
+      step: opts.step || null,
+      status: opts.status || null,
+      previousStatus: null,
+      updated: null,
+      warnings: [],
+      checks: [{ id: 'state-action-required', status: 'fail', artifact: '.godpowers/state.json', reason: 'state requires subcommand advance' }],
+      findings: [{ id: 'state-action-required', severity: 'error', artifact: '.godpowers/state.json', reason: 'state requires subcommand advance' }],
+      summary: { updated: false, state: '.godpowers/state.json', views: ['.godpowers/PROGRESS.md'] }
+    };
+    if (opts.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(stateAdvance.render(result));
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = stateAdvance.advance(opts.project, {
+    step: opts.step,
+    status: opts.status
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(stateAdvance.render(result));
+  }
+  if (stateAdvance.exitCode(result) !== 0) {
+    process.exitCode = 1;
+  }
+}
+
 const COMMAND_RUNNERS = {
   status: runDashboardCommand,
   next: runDashboardCommand,
+  state: runStateCommand,
   'quick-proof': runQuickProofCommand,
   'mcp-info': runMcpInfoCommand,
   'automation-status': runAutomationCommand,
@@ -170,5 +207,6 @@ module.exports = {
   runQuickProofCommand,
   runMcpInfoCommand,
   runExtensionScaffoldCommand,
-  runGateCommand
+  runGateCommand,
+  runStateCommand
 };

package/lib/context-writer.js

@@ -83,13 +83,13 @@ function buildCanonicalContent(state, opts = {}) {
   const scale = (state && (state.scale || (state.project && state.project.scale))) || opts.scale || 'unknown';
   lines.push(`- Project: ${projectName}`);
   lines.push(`- Mode: ${mode}    Scale: ${scale}`);
-  lines.push('- State: `.godpowers/state.json` (machine) and `.godpowers/PROGRESS.md` (human)');
+  lines.push('- State: `.godpowers/state.json` is authority; `.godpowers/PROGRESS.md` is generated for humans');
   lines.push('');
 
   lines.push('### Quarterback rule');
   lines.push('');
-  lines.push('There is exactly one orchestrator: `god-orchestrator`. It owns all writes to');
-  lines.push('`state.json`, `PROGRESS.md`, `intent.yaml`, and `events.jsonl`. Skills like');
+  lines.push('There is exactly one orchestrator: `god-orchestrator`. It owns writes to');
+  lines.push('`state.json`, `intent.yaml`, and `events.jsonl`; `PROGRESS.md` is regenerated from state. Skills like');
   lines.push('`/god`, `/god-next`, `/god-status` read state without writing.');
   lines.push('');
 
@@ -148,7 +148,7 @@ function buildCanonicalContent(state, opts = {}) {
     }
   }
 
-  lines.push('See `.godpowers/PROGRESS.md` for the live tier table.');
+  lines.push('See `.godpowers/state.json` for authority and `.godpowers/PROGRESS.md` for the generated tier table.');
   return lines.join('\n');
 }
 

package/lib/gate.js

@@ -11,6 +11,7 @@ const path = require('path');
 const artifactMap = require('./artifact-map');
 const linter = require('./artifact-linter');
 const router = require('./router');
+const stateStore = require('./state');
 
 function relToAbs(projectRoot, relPath) {
   return path.join(projectRoot, relPath);
@@ -168,12 +169,108 @@ function extractCommandStatuses(text) {
   return entries;
 }
 
-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 failedCommands = extractFailedCommands(text);
+function commandName(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const value = entry.command || entry.cmd || entry.name;
+  return value ? String(value).trim() : null;
+}
+
+function normalizeVerificationStatus(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const raw = entry.status || entry.result || entry.verdict;
+  if (raw) {
+    const text = String(raw).trim().toLowerCase();
+    if (/^(pass|passed|green|success|succeeded|ok)$/.test(text)) return 'pass';
+    if (/^(fail|failed|red|error)$/.test(text)) return 'fail';
+  }
+  if (Number.isInteger(entry.exitCode)) return entry.exitCode === 0 ? 'pass' : 'fail';
+  return null;
+}
+
+function stateVerificationCommands(subStep) {
+  if (!subStep || typeof subStep !== 'object') return [];
+  const verification = subStep.verification && typeof subStep.verification === 'object'
+    ? subStep.verification
+    : {};
+  const commands = verification.commands ||
+    subStep.verificationCommands ||
+    subStep['verification-commands'] ||
+    [];
+  return Array.isArray(commands) ? commands : [];
+}
+
+function commandsWithStatus(subStep, wantedStatus) {
+  const commands = [];
+  for (const entry of stateVerificationCommands(subStep)) {
+    const name = commandName(entry);
+    if (!name) continue;
+    if (normalizeVerificationStatus(entry) !== wantedStatus) continue;
+    if (!commands.includes(name)) commands.push(name);
+  }
+  return commands;
+}
+
+function checkStateStepEvidence(projectRoot, tier, result) {
+  const stepRef = artifactMap.stateStepForTier(tier);
+  if (!stepRef) return null;
+
+  const relPath = '.godpowers/state.json';
+  const currentState = stateStore.read(projectRoot);
+  if (!currentState) {
+    const finding = makeFinding(
+      `state:${tier}:missing`,
+      'error',
+      relPath,
+      `${tier} gate requires structured state evidence in state.json.`
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+    result.checks.push(makeCheck(`state:${tier}:status`, 'fail', relPath, finding.reason));
+    return null;
+  }
+
+  const tierState = currentState.tiers && currentState.tiers[stepRef.tierKey];
+  const subStep = tierState && tierState[stepRef.subStepKey];
+  if (!subStep) {
+    const finding = makeFinding(
+      `state:${tier}:step-missing`,
+      'error',
+      relPath,
+      `state.json does not record ${stepRef.tierKey}.${stepRef.subStepKey}.`
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+    result.checks.push(makeCheck(`state:${tier}:status`, 'fail', relPath, finding.reason));
+    return null;
+  }
+
+  const status = subStep.status || 'pending';
+  const complete = stateStore.isCompleteStatus(status);
+  if (!complete) {
+    const finding = makeFinding(
+      `state:${tier}:incomplete`,
+      'error',
+      relPath,
+      `${stepRef.tierKey}.${stepRef.subStepKey} status is ${status}, expected a complete status.`
+    );
+    result.findings.push(finding);
+    addFindingSummary(result.summary, finding.severity);
+  }
+  result.checks.push(makeCheck(
+    `state:${tier}:status`,
+    complete ? 'pass' : 'fail',
+    relPath,
+    complete
+      ? `${stepRef.tierKey}.${stepRef.subStepKey} records complete status ${status}.`
+      : `${stepRef.tierKey}.${stepRef.subStepKey} must be complete before this gate passes.`
+  ));
+  return subStep;
+}
+
+function checkBuildEvidence(result, buildStep) {
+  const relPath = '.godpowers/state.json';
+  if (!buildStep) return;
+  const failedCommands = commandsWithStatus(buildStep, 'fail');
   if (failedCommands.length > 0) {
     const finding = makeFinding(
       'build-verification-failed-command',
@@ -192,7 +289,7 @@ function checkBuildEvidence(projectRoot, result) {
     result.summary.buildVerificationFailedCommands = failedCommands;
     return;
   }
-  const passedCommands = extractPassedCommands(text);
+  const passedCommands = commandsWithStatus(buildStep, 'pass');
   if (passedCommands.length === 0) {
     const finding = makeFinding(
       'build-verification-evidence',
@@ -214,7 +311,7 @@ function checkBuildEvidence(projectRoot, result) {
     'build-verification-evidence',
     'pass',
     relPath,
-    `Build state records ${passedCommands.length} passed verification command(s).`
+    `state.json records ${passedCommands.length} passed build verification command(s).`
   ));
   result.summary.buildVerificationCommands = passedCommands;
 }
@@ -280,7 +377,8 @@ function check(opts = {}) {
   }
 
   checkArtifacts(projectRoot, tier, artifacts, opts, result);
-  if (tier === 'build') checkBuildEvidence(projectRoot, result);
+  const stateStep = checkStateStepEvidence(projectRoot, tier, result);
+  if (tier === 'build') checkBuildEvidence(result, stateStep);
   if (tier === 'harden') checkHardenCriticals(projectRoot, result);
   return finalize(result);
 }

package/lib/installer-args.js

@@ -4,6 +4,7 @@ const { RUNTIMES } = require('./installer-runtimes');
 const COMMANDS = new Set([
   'status',
   'next',
+  'state',
   'quick-proof',
   'mcp-info',
   'automation-status',
@@ -20,6 +21,9 @@ function parseArgs(argv, cwd = process.cwd()) {
     project: cwd,
     json: false,
     brief: false,
+    stateAction: null,
+    step: null,
+    status: null,
     extensionName: null,
     extensionOutput: cwd,
     extensionSkill: null,
@@ -41,6 +45,10 @@ function parseArgs(argv, cwd = process.cwd()) {
       opts.command = arg;
       continue;
     }
+    if (opts.command === 'state' && !opts.stateAction && !arg.startsWith('-')) {
+      opts.stateAction = arg;
+      continue;
+    }
 
     switch (arg) {
       case '--json':
@@ -55,6 +63,18 @@ function parseArgs(argv, cwd = process.cwd()) {
           i++;
         }
         break;
+      case '--step':
+        if (args[i + 1]) {
+          opts.step = args[i + 1];
+          i++;
+        }
+        break;
+      case '--status':
+        if (args[i + 1]) {
+          opts.status = args[i + 1];
+          i++;
+        }
+        break;
       case '--project':
         if (args[i + 1]) {
           opts.project = path.resolve(args[i + 1]);
@@ -104,6 +124,10 @@ function parseArgs(argv, cwd = process.cwd()) {
           opts.extensionWorkflow = arg.slice('--workflow='.length);
         } else if (arg.startsWith('--tier=')) {
           opts.tier = arg.slice('--tier='.length);
+        } else if (arg.startsWith('--step=')) {
+          opts.step = arg.slice('--step='.length);
+        } else if (arg.startsWith('--status=')) {
+          opts.status = arg.slice('--status='.length);
         } else if (arg.startsWith('--profile=')) {
           opts.profile = arg.slice('--profile='.length);
         } else if (arg.startsWith('--') && RUNTIMES[arg.slice(2)]) {

package/lib/pillars.js

@@ -96,8 +96,7 @@ const ARTIFACT_PILLAR_MAP = [
   { pattern: /(^|\/)stack\/DECISION\.md$/i, pillars: ['stack'] },
   { pattern: /(^|\/)roadmap\/ROADMAP\.md$/i, pillars: ['context', 'quality'] },
   { pattern: /(^|\/)build\/PLAN\.md$/i, pillars: ['quality', 'repo'] },
-  { pattern: /(^|\/)deploy\/STATE\.md$/i, pillars: ['deploy'] },
-  { pattern: /(^|\/)observe\/STATE\.md$/i, pillars: ['observe'] },
+  { pattern: /^\.godpowers\/state\.json$/i, pillars: ['context', 'deploy', 'observe'] },
   { pattern: /(^|\/)harden\/FINDINGS\.md$/i, pillars: ['security', 'auth'] },
   { pattern: /(^|\/)design\/DESIGN\.md$/i, pillars: ['ui'] },
   { pattern: /(^|\/)design\/PRODUCT\.md$/i, pillars: ['context', 'ui'] }
@@ -109,8 +108,7 @@ const GODPOWERS_ARTIFACTS = [
   '.godpowers/stack/DECISION.md',
   '.godpowers/roadmap/ROADMAP.md',
   '.godpowers/build/PLAN.md',
-  '.godpowers/deploy/STATE.md',
-  '.godpowers/observe/STATE.md',
+  '.godpowers/state.json',
   '.godpowers/harden/FINDINGS.md',
   '.godpowers/design/DESIGN.md',
   '.godpowers/design/PRODUCT.md'

package/lib/recipes.js

@@ -112,6 +112,14 @@ function evaluateStateCondition(condition, projectRoot) {
   if (cond.startsWith('file:')) {
     return fs.existsSync(path.join(projectRoot, cond.slice(5).trim()));
   }
+  if (cond.startsWith('state:')) {
+    const m = cond.slice(6).trim().match(/^([\w.-]+)\s*==\s*(.+)$/);
+    if (!m) return true;
+    const [, dottedPath, expected] = m;
+    const s = state.read(projectRoot);
+    const actual = state.valueAtPath(s, dottedPath);
+    return actual === expected.trim() || actual === parseValue(expected.trim());
+  }
   if (cond.startsWith('lifecycle-phase ==')) {
     const expected = cond.split('==')[1].trim();
     const s = state.read(projectRoot);
@@ -131,6 +139,14 @@ function evaluateStateCondition(condition, projectRoot) {
   return true;
 }
 
+function parseValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  if (/^\d+$/.test(value)) return parseInt(value, 10);
+  return value;
+}
+
 /**
  * Suggest top recipes based on current project state alone (no intent text).
  */

package/lib/router.js

@@ -119,11 +119,7 @@ function evaluateCheck(check, projectRoot) {
     if (!match) return false;
     const [, dottedPath, expected] = match;
     const s = state.read(projectRoot);
-    if (!s) return false;
-    const actual = dottedPath.split('.').reduce((acc, k) => {
-      if (!acc || k === '__proto__' || k === 'constructor' || k === 'prototype') return undefined;
-      return acc[k];
-    }, s.tiers || s);
+    const actual = state.valueAtPath(s, dottedPath);
     return actual === expected || actual === parseValue(expected);
   }
 

package/lib/source-sync.js

@@ -131,7 +131,7 @@ function progressLines(projectRoot) {
   lines.push(summarizeArtifact(projectRoot, '.godpowers/arch/ARCH.md', 'Architecture'));
   lines.push(summarizeArtifact(projectRoot, '.godpowers/roadmap/ROADMAP.md', 'Roadmap'));
   lines.push(summarizeArtifact(projectRoot, '.godpowers/stack/DECISION.md', 'Stack'));
-  lines.push(summarizeArtifact(projectRoot, '.godpowers/build/STATE.md', 'Build state'));
+  lines.push(summarizeArtifact(projectRoot, '.godpowers/state.json', 'Godpowers state'));
   lines.push('');
   lines.push('## Return Path');
   lines.push('');