godpowers 3.13.0 → 3.13.2

package/lib/pillars.js

@@ -114,6 +114,13 @@ const GODPOWERS_ARTIFACTS = [
   '.godpowers/design/PRODUCT.md'
 ];
 
+// ===========================================================================
+// Pillar model: parse pillar files, detect installed pillars, compute the
+// per-task load set, and construct/initialize pillar files. Shared with the
+// artifact-sync workflow below (init/ensurePillar/pillarStub/detect are also
+// part of the public API).
+// ===========================================================================
+
 function stripQuotes(value) {
   return String(value).trim().replace(/^['"]|['"]$/g, '');
 }
@@ -401,6 +408,12 @@ function writeFenced(filePath, begin, end, content) {
   fs.writeFileSync(filePath, next);
 }
 
+// ===========================================================================
+// Artifact-sync workflow: turn Godpowers artifacts (PRD/ARCH/...) into durable
+// pillar signals and write them into the routed pillar files. Builds on the
+// model above (init/ensurePillar/pillarStub/detect/buildProtocolContent).
+// ===========================================================================
+
 function artifactToPillars(artifactPath) {
   const normalized = artifactPath.replace(/\\/g, '/');
   const pillars = [];

package/lib/planning-systems.js

@@ -11,6 +11,7 @@ const path = require('path');
 const crypto = require('crypto');
 
 const state = require('./state');
+const { exists } = require('./sync-fs');
 
 const MAX_FILE_BYTES = 80 * 1024;
 const MAX_SYSTEM_FILES = 80;
@@ -95,18 +96,10 @@ function rel(projectRoot, absPath) {
   return path.relative(projectRoot, absPath).split(path.sep).join('/');
 }
 
-function exists(projectRoot, relPath) {
-  return fs.existsSync(path.join(projectRoot, relPath));
-}
-
 function ensureDir(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
 
-function sha(input) {
-  return crypto.createHash('sha256').update(input).digest('hex');
-}
-
 function hashFiles(projectRoot, files) {
   const h = crypto.createHash('sha256');
   for (const file of files.map((f) => f.path).sort()) {
@@ -476,7 +469,6 @@ module.exports = {
   _private: {
     classifyFile,
     extractSignals,
-    filesForKinds,
-    sha
+    filesForKinds
   }
 };

package/lib/recipe-coverage-sync.js

@@ -9,6 +9,10 @@ const fs = require('fs');
 const path = require('path');
 
 const recipes = require('./recipes');
+const { read, write } = require('./sync-fs');
+const { makeAddCheck } = require('./sync-check');
+
+const addCheck = makeAddCheck('recipe-coverage');
 
 const LOG_PATH = '.godpowers/surface/RECIPE-COVERAGE-SYNC.md';
 
@@ -40,29 +44,6 @@ const REQUIRED_COVERAGE = [
   }
 ];
 
-function read(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
-function write(projectRoot, relPath, content) {
-  const file = path.join(projectRoot, relPath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content);
-}
-
-function addCheck(checks, id, status, relPath, message, opts = {}) {
-  checks.push({
-    area: 'recipe-coverage',
-    id,
-    status,
-    path: relPath,
-    message,
-    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
-    spawn: opts.spawn || null
-  });
-}
 
 function recipePath(projectRoot, name) {
   const rel = `routing/recipes/${name}.yaml`;

package/lib/release-surface-sync.js

@@ -9,6 +9,11 @@
 const fs = require('fs');
 const path = require('path');
 
+const { read, write, readJson } = require('./sync-fs');
+const { makeAddCheck } = require('./sync-check');
+
+const addCheck = makeAddCheck('release-surface');
+
 const LOG_PATH = '.godpowers/surface/RELEASE-SURFACE-SYNC.md';
 
 const REQUIRED_PACKAGE_GUARDS = [
@@ -37,26 +42,6 @@ const REQUIRED_RELEASE_TESTS = [
   'scripts/test-install-smoke.js'
 ];
 
-function read(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
-function write(projectRoot, relPath, content) {
-  const file = path.join(projectRoot, relPath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content);
-}
-
-function readJson(projectRoot, relPath) {
-  try {
-    return JSON.parse(read(projectRoot, relPath));
-  } catch (err) {
-    return null;
-  }
-}
-
 function releaseGateText(projectRoot, pkg) {
   return [
     JSON.stringify((pkg && pkg.scripts) || {}),
@@ -64,18 +49,6 @@ function releaseGateText(projectRoot, pkg) {
   ].join('\n');
 }
 
-function addCheck(checks, id, status, relPath, message, opts = {}) {
-  checks.push({
-    area: 'release-surface',
-    id,
-    status,
-    path: relPath,
-    message,
-    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
-    spawn: opts.spawn || null
-  });
-}
-
 function detect(projectRoot) {
   const checks = [];
   const pkg = readJson(projectRoot, 'package.json') || {};

package/lib/repo-doc-sync.js

@@ -10,25 +10,10 @@ const path = require('path');
 const crypto = require('crypto');
 
 const pillars = require('./pillars');
+const { read, write, exists } = require('./sync-fs');
 
 const LOG_PATH = '.godpowers/docs/REPO-DOC-SYNC.md';
 
-function read(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
-function write(projectRoot, relPath, text) {
-  const file = path.join(projectRoot, relPath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, text);
-}
-
-function exists(projectRoot, relPath) {
-  return fs.existsSync(path.join(projectRoot, relPath));
-}
-
 function countFiles(projectRoot, dir, pattern) {
   const full = path.join(projectRoot, dir);
   if (!fs.existsSync(full)) return 0;

package/lib/repo-surface-sync.js

@@ -11,6 +11,8 @@ const fs = require('fs');
 const path = require('path');
 
 const { parseSimpleYaml } = require('./intent');
+const { read, write, exists, readJson } = require('./sync-fs');
+const { addCheck, listFiles } = require('./sync-check');
 const extensions = require('./extensions');
 const repoDocSync = require('./repo-doc-sync');
 const routeQualitySync = require('./route-quality-sync');
@@ -51,43 +53,6 @@ const REQUIRED_PACKAGE_CHECKS = [
   'routing/god-export-otel.yaml'
 ];
 
-function rel(projectRoot, absPath) {
-  return path.relative(projectRoot, absPath).split(path.sep).join('/');
-}
-
-function exists(projectRoot, relPath) {
-  return fs.existsSync(path.join(projectRoot, relPath));
-}
-
-function read(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
-function write(projectRoot, relPath, content) {
-  const file = path.join(projectRoot, relPath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content);
-}
-
-function listFiles(projectRoot, relDir, pattern) {
-  const dir = path.join(projectRoot, relDir);
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir)
-    .filter((name) => pattern.test(name))
-    .sort()
-    .map((name) => `${relDir}/${name}`.replace(/\\/g, '/'));
-}
-
-function readJson(projectRoot, relPath) {
-  try {
-    return JSON.parse(read(projectRoot, relPath));
-  } catch (err) {
-    return null;
-  }
-}
-
 function releaseGateText(projectRoot, pkg) {
   return [
     JSON.stringify((pkg && pkg.scripts) || {}),
@@ -104,19 +69,6 @@ function commandForSkill(skillPath) {
   return `/${path.basename(skillPath, '.md')}`;
 }
 
-function addCheck(checks, area, id, status, relPath, message, opts = {}) {
-  checks.push({
-    area,
-    id,
-    status,
-    path: relPath,
-    message,
-    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
-    safeFix: opts.safeFix === true,
-    spawn: opts.spawn || null
-  });
-}
-
 function routingChecks(projectRoot) {
   const checks = [];
   const skills = listFiles(projectRoot, 'skills', /^god.*\.md$/);
@@ -508,15 +460,12 @@ function releasePolicyChecks(projectRoot) {
     checks,
     'release',
     'release-checklist-surface-sync',
-    read(projectRoot, 'docs/RELEASE-CHECKLIST.md').includes('repo-surface-sync'),
+    read(projectRoot, 'docs/RELEASE-CHECKLIST.md').includes('repo-surface-sync') ? 'fresh' : 'stale',
     'docs/RELEASE-CHECKLIST.md',
     'Release checklist references repo-surface-sync readiness.',
     { spawn: 'god-docs-writer' }
   );
-  return checks.map((check) => ({
-    ...check,
-    status: check.status === true ? 'fresh' : (check.status === false ? 'stale' : check.status)
-  }));
+  return checks;
 }
 
 function detect(projectRoot) {

package/lib/requirements.js

@@ -32,9 +32,12 @@ const path = require('path');
 const linkage = require('./linkage');
 const state = require('./state');
 const atomic = require('./atomic-write');
+const textUtil = require('./text-util');
+const artifactMap = require('./artifact-map');
+const { readTextOrNull: readText } = require('./sync-fs');
 
-const PRD_PATH = '.godpowers/prd/PRD.md';
-const ROADMAP_PATH = '.godpowers/roadmap/ROADMAP.md';
+const PRD_PATH = artifactMap.requiredArtifactsForTier('prd')[0].path;
+const ROADMAP_PATH = artifactMap.requiredArtifactsForTier('roadmap')[0].path;
 const LEDGER_PATH = '.godpowers/REQUIREMENTS.md';
 
 const PRIORITIES = ['MUST', 'SHOULD', 'COULD'];
@@ -43,26 +46,12 @@ const REQ_ID_RE_G = /\bP-(MUST|SHOULD|COULD)-\d+\b/g;
 const MILESTONE_ID_RE = /\bM-[\w-]+\b/;
 const LABEL_RE = /\[(?:DECISION|HYPOTHESIS|OPEN QUESTION)\]/g;
 
-function readText(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return null;
-  try {
-    return fs.readFileSync(file, 'utf8');
-  } catch (e) {
-    return null;
-  }
-}
-
 function pad2(n) {
   return String(n).padStart(2, '0');
 }
 
 function slugify(text) {
-  return String(text)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 40) || 'increment';
+  return textUtil.slugify(text, 'increment');
 }
 
 // ============================================================================

package/lib/reverse-sync.js

@@ -318,23 +318,29 @@ function run(projectRoot, opts = {}) {
   // write the file when the PRD actually declares requirements, to avoid
   // littering pre-PRD projects with an empty ledger.
   let requirementsSummary = null;
+  let requirementsError = null;
   if (opts.runRequirements !== false) {
     try {
       const derived = requirements.derive(projectRoot);
       if (derived.hasRequirements) {
-        requirements.writeLedger(projectRoot, derived);
         const currentState = state.read(projectRoot);
         requirementsSummary = requirements.summarizeForState(
           derived,
           currentState && currentState.deliverables
         );
+        // Write state.json first, then the ledger, so a state-write failure
+        // cannot leave a REQUIREMENTS.md ledger that state.json never references.
         if (currentState) {
           currentState.deliverables = requirementsSummary;
           state.write(projectRoot, currentState);
         }
+        requirements.writeLedger(projectRoot, derived);
       }
     } catch (e) {
+      // ERR-001: surface the failure instead of swallowing it, so the caller can
+      // tell a genuine requirements-step error apart from "no requirements".
       requirementsSummary = null;
+      requirementsError = e.message;
     }
   }
 
@@ -346,7 +352,8 @@ function run(projectRoot, opts = {}) {
     footers,
     sourceSyncResult,
     reviewItems,
-    requirements: requirementsSummary
+    requirements: requirementsSummary,
+    requirementsError
   };
 }
 

package/lib/route-quality-sync.js

@@ -10,6 +10,10 @@ const fs = require('fs');
 const path = require('path');
 
 const { parseSimpleYaml } = require('./intent');
+const { read, write } = require('./sync-fs');
+const { makeAddCheck, listFiles } = require('./sync-check');
+
+const addCheck = makeAddCheck('route-quality');
 
 const LOG_PATH = '.godpowers/surface/ROUTE-QUALITY-SYNC.md';
 const CONTEXTUAL_NEXT_VALUES = new Set([
@@ -100,27 +104,6 @@ const TIER_GATE_COMMANDS = new Set([
   '/god-harden'
 ]);
 
-function read(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
-function write(projectRoot, relPath, content) {
-  const file = path.join(projectRoot, relPath);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content);
-}
-
-function listFiles(projectRoot, relDir, pattern) {
-  const dir = path.join(projectRoot, relDir);
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir)
-    .filter((name) => pattern.test(name))
-    .sort()
-    .map((name) => `${relDir}/${name}`.replace(/\\/g, '/'));
-}
-
 function arr(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -133,18 +116,6 @@ function parseRoute(projectRoot, routePath) {
   }
 }
 
-function addCheck(checks, id, status, relPath, message, opts = {}) {
-  checks.push({
-    area: 'route-quality',
-    id,
-    status,
-    path: relPath,
-    message,
-    severity: opts.severity || (status === 'fresh' ? 'info' : 'warning'),
-    spawn: opts.spawn || null
-  });
-}
-
 function spawnTokens(route) {
   const execution = route.execution || {};
   return normalizeSpawnList([

package/lib/source-sync.js

@@ -30,10 +30,6 @@ const SYSTEM_TARGETS = {
   }
 };
 
-function rel(projectRoot, absPath) {
-  return path.relative(projectRoot, absPath).split(path.sep).join('/');
-}
-
 function sha(input) {
   return `sha256:${crypto.createHash('sha256').update(input).digest('hex')}`;
 }

package/lib/state.js

@@ -53,10 +53,26 @@ const SUBSTEP_LABELS = {
  * @property {number} ordinal One-based step position.
  */
 
+// Canonical project-relative location of the state file. Other modules that
+// need to name state.json (gates, dispatch findings, audits) import this rather
+// than re-typing the literal (ARC-002).
+const STATE_FILE = '.godpowers/state.json';
+
 function statePath(projectRoot) {
   return path.join(projectRoot, '.godpowers', 'state.json');
 }
 
+// A typed error so callers (e.g. the CLI dispatcher) can detect corrupt state
+// by `err.code === 'CORRUPT_STATE'` instead of matching the message prose.
+function corruptStateError(file, cause) {
+  const err = new Error(
+    `Corrupt state file at ${file}: ${cause.message}. ` +
+    `Fix the JSON or remove the file to let Godpowers reinitialize it.`
+  );
+  err.code = 'CORRUPT_STATE';
+  return err;
+}
+
 function tierNumber(tierKey) {
   const match = String(tierKey).match(/^tier-(\d+)$/);
   return match ? Number(match[1]) : Number.MAX_SAFE_INTEGER;
@@ -88,10 +104,7 @@ function read(projectRoot) {
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(
-      `Corrupt state file at ${file}: ${e.message}. ` +
-      `Fix the JSON or remove the file to let Godpowers reinitialize it.`
-    );
+    throw corruptStateError(file, e);
   }
 }
 
@@ -144,10 +157,7 @@ async function readAsync(projectRoot) {
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(
-      `Corrupt state file at ${file}: ${e.message}. ` +
-      `Fix the JSON or remove the file to let Godpowers reinitialize it.`
-    );
+    throw corruptStateError(file, e);
   }
 }
 
@@ -421,6 +431,7 @@ module.exports = {
   updateSubStepAsync,
   hashFile,
   detectDrift,
+  STATE_FILE,
   statePath,
   isInitialized,
   isInitializedState,

package/lib/sync-check.js

@@ -0,0 +1,56 @@
+/**
+ * Shared check-builder and file-lister for the lib/*-sync.js family (ARC-001).
+ *
+ * The aggregator (repo-surface-sync) passes a per-call `area` and may mark a
+ * check `safeFix`, so it uses the full `addCheck`. The single-area sync modules
+ * (recipe-coverage, release-surface, route-quality) bind their area once via
+ * `makeAddCheck(area)`; their records intentionally omit `safeFix` (none of
+ * their checks are auto-fixable), matching the original per-module builders.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function severityFor(status, opts) {
+  return opts.severity || (status === 'fresh' ? 'info' : 'warning');
+}
+
+// Full form: caller supplies `area`; records include the `safeFix` flag.
+function addCheck(checks, area, id, status, relPath, message, opts = {}) {
+  checks.push({
+    area,
+    id,
+    status,
+    path: relPath,
+    message,
+    severity: severityFor(status, opts),
+    safeFix: opts.safeFix === true,
+    spawn: opts.spawn || null
+  });
+}
+
+// Area-bound form for single-area modules; records omit `safeFix`.
+function makeAddCheck(area) {
+  return function (checks, id, status, relPath, message, opts = {}) {
+    checks.push({
+      area,
+      id,
+      status,
+      path: relPath,
+      message,
+      severity: severityFor(status, opts),
+      spawn: opts.spawn || null
+    });
+  };
+}
+
+function listFiles(projectRoot, relDir, pattern) {
+  const dir = path.join(projectRoot, relDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => pattern.test(name))
+    .sort()
+    .map((name) => `${relDir}/${name}`.replace(/\\/g, '/'));
+}
+
+module.exports = { addCheck, makeAddCheck, listFiles };

package/lib/sync-fs.js

@@ -0,0 +1,49 @@
+/**
+ * Shared filesystem helpers for the lib/*-sync.js family.
+ *
+ * Every sync module used to redefine its own byte-identical read/write/exists/
+ * readJson against a project root (ARC-001). They now share these so a change
+ * to path handling or read semantics lives in one place. Module-specific log
+ * writers (appendLog) stay per-module because their headers and formats differ.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function read(projectRoot, relPath) {
+  const file = path.join(projectRoot, relPath);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8');
+}
+
+function write(projectRoot, relPath, content) {
+  const file = path.join(projectRoot, relPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function exists(projectRoot, relPath) {
+  return fs.existsSync(path.join(projectRoot, relPath));
+}
+
+function readJson(projectRoot, relPath) {
+  try {
+    return JSON.parse(read(projectRoot, relPath));
+  } catch (err) {
+    return null;
+  }
+}
+
+// Like read(), but returns null (not '') when the file is missing or unreadable,
+// for callers that distinguish "absent" from "empty".
+function readTextOrNull(projectRoot, relPath) {
+  const file = path.join(projectRoot, relPath);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return null;
+  }
+}
+
+module.exports = { read, write, exists, readJson, readTextOrNull };

package/lib/text-util.js

@@ -0,0 +1,19 @@
+/**
+ * Small shared string helpers (QUAL-002).
+ *
+ * slugify is the canonical home for the "lowercase, collapse non-alphanumerics
+ * to '-', strip edge '-', truncate to 40 chars" contract. lib/evidence.js keeps
+ * its own copy on purpose: that module is vendored from the upstream engine and
+ * its helpers are provenance-tracked, so it must not import first-party code.
+ */
+
+function slugify(text, fallback = '') {
+  const slug = String(text == null ? '' : text)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return slug || fallback;
+}
+
+module.exports = { slugify };

package/lib/workflow-helper-groups.js

@@ -6,6 +6,10 @@
  */
 
 const HELPER_GROUPS = {
+  'context-bootstrap': [
+    'pillars-detect',
+    'pillars-init'
+  ],
   'standard-closeout': [
     'repo-doc-sync',
     'repo-surface-sync',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "3.13.0",
+  "version": "3.13.2",
   "description": "AI-powered development system: 120 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"
@@ -24,11 +24,11 @@
     "test:e2e": "node tests/integration/full-arc.test.js",
     "test:mcp": "npm --workspace @godpowers/mcp test",
     "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",
+    "coverage:lib": "c8 --include=lib/**/*.js --check-coverage --lines 90 --branches 75 --reporter=text --reporter=json-summary 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",
     "pack:mcp:check": "npm --workspace @godpowers/mcp run pack:check",
-    "release:check": "npm run coverage:lib && npm run test:audit && npm run pack:check && npm run pack:mcp:check",
+    "release:check": "npm run coverage:lib && node scripts/check-per-file-coverage.js && npm run test:audit && npm run pack:check && npm run pack:mcp:check",
     "lint": "node scripts/static-check.js"
   },
   "workspaces": [

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

@@ -115,6 +115,13 @@ This converts existing Godpowers artifacts into managed source references in
 the relevant pillar files, so old projects are Pillar-ized as part of being
 Godpower-ized.
 
+In the greenfield `full-arc` workflow this start-of-arc step is surfaced as the
+tier-0 `context` job, whose `context-bootstrap` helper group expands to
+`pillars-detect` (`lib/pillars.detect`) and `pillars-init` (`lib/pillars.init`).
+The job uses `god-orchestrator` as a local runtime call, not a `god-context-writer`
+spawn, so it changes nothing about the behavior described above; it only makes the
+init visible in `/god-mode --plan` alongside the closeout `pillars-sync-plan`.
+
 Before each major command, compute the task-specific Pillars load set with
 `lib/pillars.computeLoadSet(projectRoot, taskText)`. Load `agents/context.md`
 and `agents/repo.md` first, then the routed primary pillars and their direct