godpowers 3.13.1 → 3.13.2

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.13.2] - 2026-06-17
+
+Maintenance release that drives a third self-audit (`codeaudit.md`) to zero: one
+Medium and twelve Low findings across de-duplication, error handling, security
+hardening, the test gate, and docs. No public command/agent/workflow/recipe
+surface change (counts stay 120 / 40 / 13 / 44); lib module count 90 -> 91.
+
+### Changed
+- **Shared sync check-builder (ARC-001):** the four `*-sync` modules no longer
+  copy-paste `addCheck`/`listFiles`; they share `lib/sync-check.js` (full
+  `addCheck` for the aggregator, area-bound `makeAddCheck` for the rest).
+- **Per-file coverage floor (TEST-001):** `coverage:lib` now emits a json-summary
+  and `scripts/check-per-file-coverage.js` (in `release:check`) fails any lib
+  module below 70% lines (excluding the two environment-bound browser drivers),
+  so a single file can no longer rot while the aggregate stays green.
+- **De-duplication and cleanup (QUAL-001/002/003):** removed dead helpers
+  (two unused `rel()`, an unused `sha`), added `sync-fs.readTextOrNull` adopted by
+  `requirements.js` (which now sources PRD/ROADMAP paths from `artifact-map`), and
+  fixed a boolean/string status wart in `repo-surface-sync`.
+- **Pillars delineation (ARC-002):** `pillars.js` now has section dividers
+  separating the model and artifact-sync halves (a full split was deferred; the
+  halves share construction functions that are public API).
+
+### Fixed
+- **Reverse-sync error visibility (ERR-001):** the requirements step now writes
+  state before the ledger and surfaces a caught error as `requirementsError`
+  instead of silently nulling it.
+
+### Security
+- **MCP module-name guard (SEC-001):** `requireRuntime` rejects any name that is
+  not a plain lib basename (defense-in-depth).
+- **YAML recursion cap (SEC-002):** `intent.cleanArrays` caps recursion depth so a
+  pathologically deep file cannot overflow the stack.
+
+### Performance
+- **have-nots regex (PERF-001):** `findPositions` compiles its regex once instead
+  of per line. The whole-ledger read in `evidence.readJsonl` is documented as
+  bounded/acceptable with an opt-in prune noted for the future (PERF-002).
+
+### Docs
+- **Absolute README doc links (DOC-001):** `docs/` is deliberately excluded from
+  the package, so the README's `docs/*` links are now absolute GitHub URLs that
+  resolve on the npm page and in the tarball.
+
 ## [3.13.1] - 2026-06-16
 
 Maintenance release that drives a full self-audit (`codeaudit.md`) to zero: one

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.13.1-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.13.2-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -12,30 +12,33 @@ idea to hardened production. It runs as **slash commands inside your AI coding
 tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
-Want the short proof first? Start with [Quick Proof](docs/quick-proof.md) to
+Want the short proof first? Start with [Quick Proof](https://github.com/aihxp/godpowers/blob/main/docs/quick-proof.md) to
 run `npx godpowers quick-proof --project=. --brief`, see outcome metrics, pick
 a starter command set, and understand runtime expectations before reading the
-full reference. The [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
+full reference. The [First 10 Minute Proof Case Study](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/first-10-minute-proof.md)
 shows the same evidence as a before-and-after adoption story. External
-CLI-verifiable canaries now cover [sindresorhus/is](docs/case-studies/sindresorhus-is-adoption-canary.md),
-[expressjs/cors](docs/case-studies/expressjs-cors-adoption-canary.md), and
-[tinyhttp/tinyhttp](docs/case-studies/tinyhttp-adoption-canary.md), with host
+CLI-verifiable canaries now cover [sindresorhus/is](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/sindresorhus-is-adoption-canary.md),
+[expressjs/cors](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/expressjs-cors-adoption-canary.md), and
+[tinyhttp/tinyhttp](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/tinyhttp-adoption-canary.md), with host
 slash-command gaps called out rather than hidden.
-Host-run proof studies now cover [slugify-cli](docs/case-studies/run-a.md),
-[Countdown](docs/case-studies/run-b.md), and
-[react-github-readme-button](docs/case-studies/run-c.md), including one
+Host-run proof studies now cover [slugify-cli](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-a.md),
+[Countdown](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-b.md), and
+[react-github-readme-button](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/run-c.md), including one
 blocked harden run recorded as evidence instead of hidden as success.
 
 Godpowers makes AI coding accountable: every serious run should leave disk
 state, artifacts, validation gates, host guarantees, and a next action. Code is
 only one output. The project memory and proof trail matter too.
 
-Version 3.13.1 is a maintenance release that drives a full self-audit to zero:
-the runtime ledger no longer loses verification records under concurrent writes,
-the `outcome check` verifier and the pre-tool-use hook are hardened, the
-`*-sync` modules share one filesystem helper, the argument parser is table-driven,
-branch coverage is now gated, and the architecture map is kept in lockstep by a
-machine guard. Version 3.13.0 makes the default greenfield arc (`/god-mode`) miss
+Version 3.13.2 is a maintenance release that drives a third self-audit to zero:
+the `*-sync` modules now share one check-builder, the coverage gate enforces a
+per-file floor, the corrupt-state error is typed, dead helpers are removed, and
+the MCP module loader and YAML parser gain defense-in-depth guards. Version
+3.13.1 drove a full self-audit to zero: the runtime ledger no longer loses
+verification records under concurrent writes, the `outcome check` verifier and
+the pre-tool-use hook are hardened, the `*-sync` modules share one filesystem
+helper, the argument parser is table-driven, and branch coverage is gated.
+Version 3.13.0 makes the default greenfield arc (`/god-mode`) miss
 less. The one-shot `full-arc` workflow now runs a whole-codebase code audit after the
 build (so it catches what the per-slice reviews missed in AI-generated code) and
 a documentation pass after harden (so the shipped product has docs verified
@@ -183,7 +186,7 @@ instead of pretending a background agent ran.
 | Other install targets | Skills and agent contracts install, while host-native spawning depends on the tool. |
 | Degraded hosts | Godpowers must report local-only or simulated agent behavior instead of hiding the limitation. |
 
-See [Host capabilities](docs/host-capabilities.md) for the detailed guarantee
+See [Host capabilities](https://github.com/aihxp/godpowers/blob/main/docs/host-capabilities.md) for the detailed guarantee
 model.
 
 ## Usage
@@ -334,17 +337,17 @@ dependency to the main `godpowers` package:
 
 ```bash
 npx godpowers mcp-info --project=.
-npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp serve --project=.
+npx -y -p godpowers@3.13.2 -p @godpowers/mcp@3.13.2 godpowers-mcp serve --project=.
 ```
 
 The companion exposes `status`, `next`, `gate_check`, `lint_artifact`, and
 `trace_requirement`. Host registration is opt-in:
 
 ```bash
-npx -y -p godpowers@3.13.1 -p @godpowers/mcp@3.13.1 godpowers-mcp setup --host=codex --project=. --write
+npx -y -p godpowers@3.13.2 -p @godpowers/mcp@3.13.2 godpowers-mcp setup --host=codex --project=. --write
 ```
 
-See [MCP Companion](docs/mcp.md) for package boundaries and setup details.
+See [MCP Companion](https://github.com/aihxp/godpowers/blob/main/docs/mcp.md) for package boundaries and setup details.
 
 ### Slash Commands
 
@@ -618,16 +621,16 @@ Pi. T3 Code inherits from the underlying agent (Codex / Claude / OpenCode).
 
 ## Full reference
 
-- [Getting Started](docs/getting-started.md)
-- [Quick Proof](docs/quick-proof.md)
-- [First 10 Minute Proof Case Study](docs/case-studies/first-10-minute-proof.md)
-- [Concepts](docs/concepts.md)
-- [Command reference (all 120 skills + 40 agents)](docs/reference.md)
-- [Feature awareness](docs/feature-awareness.md)
-- [Adoption Canary](docs/adoption-canary.md)
-- [Repository documentation sync](docs/repo-doc-sync.md)
-- [Repository surface sync](docs/repo-surface-sync.md)
-- [Roadmap](docs/ROADMAP.md)
+- [Getting Started](https://github.com/aihxp/godpowers/blob/main/docs/getting-started.md)
+- [Quick Proof](https://github.com/aihxp/godpowers/blob/main/docs/quick-proof.md)
+- [First 10 Minute Proof Case Study](https://github.com/aihxp/godpowers/blob/main/docs/case-studies/first-10-minute-proof.md)
+- [Concepts](https://github.com/aihxp/godpowers/blob/main/docs/concepts.md)
+- [Command reference (all 120 skills + 40 agents)](https://github.com/aihxp/godpowers/blob/main/docs/reference.md)
+- [Feature awareness](https://github.com/aihxp/godpowers/blob/main/docs/feature-awareness.md)
+- [Adoption Canary](https://github.com/aihxp/godpowers/blob/main/docs/adoption-canary.md)
+- [Repository documentation sync](https://github.com/aihxp/godpowers/blob/main/docs/repo-doc-sync.md)
+- [Repository surface sync](https://github.com/aihxp/godpowers/blob/main/docs/repo-surface-sync.md)
+- [Roadmap](https://github.com/aihxp/godpowers/blob/main/docs/ROADMAP.md)
 - [Release Notes](RELEASE.md)
 - [Changelog](CHANGELOG.md)
 - [Inspiration](INSPIRATION.md)

package/RELEASE.md

@@ -1,41 +1,40 @@
-# Godpowers 3.13.1 Release
+# Godpowers 3.13.2 Release
 
 > Status: Prepared
-> Date: 2026-06-16
+> Date: 2026-06-17
 
-[DECISION] Godpowers 3.13.1 is a maintenance release that drives a full self-audit (`codeaudit.md`, codeauditor-grade, nine weighted dimensions) to zero. It fixes one High finding plus the Medium and Low findings across runtime correctness, security hardening, the test gate, documentation, and de-duplication.
-[DECISION] No new skill, agent, workflow, or recipe surface is added or removed. Surface counts are unchanged from 3.13.0: 120 slash commands, 40 specialist agents, 13 workflows, 44 recipes.
-[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and keeps the full 3.1.0-3.13.0 surface (fusion + codeauditor-grade audit + remediation loop + audited/documented greenfield arc).
+[DECISION] Godpowers 3.13.2 is a maintenance release that drives a third self-audit (`codeaudit.md`, codeauditor-grade, nine weighted dimensions) to zero. It fixes one Medium finding and twelve Low findings across de-duplication, error handling, security hardening, the test gate, and documentation.
+[DECISION] No new skill, agent, workflow, or recipe surface is added or removed. Surface counts are unchanged from 3.13.1: 120 slash commands, 40 specialist agents, 13 workflows, 44 recipes. The lib module count rises from 90 to 91 (`lib/sync-check.js`).
+[DECISION] This release keeps `core` as the omitted installer profile, keeps `--profile=full` as the complete compatibility surface, and keeps the full 3.1.0-3.13.1 surface.
 
 ## What's in this release
 
-- [DECISION] Runtime correctness: `lib/evidence.js` `appendJsonlAtomic` now appends with `fs.appendFileSync` (O_APPEND) instead of a read-modify-write, so concurrent `verify`/`outcome check` processes no longer lose ledger records and the append is no longer O(n) (ERR-001). A `maxBuffer` overflow is surfaced distinctly instead of as a plain failure (ERR-003).
-- [DECISION] Security hardening: the pre-tool-use hook is reframed as a best-effort advisory typo guard and matches more destructive-command variants (SEC-001); `outcome check` announces a disk-sourced verifier before running it (SEC-002); the `LEDGER-LOG.md` command echo masks obvious secret shapes and `SECURITY.md` documents the ledger and Codex-sandbox trust boundaries (SEC-003, SEC-004); `SECURITY.md` replaces the non-existent `npm install --verify` with `npm audit signatures` (DOC-002).
-- [DECISION] Test gate: `coverage:lib` now enforces `--branches 75` (TEST-001); a new `scripts/test-runtime-audit.js` raises `lib/runtime-audit.js` line coverage from 68.8% to 77.8% (TEST-002); `scripts/test-router.js` no longer shares cumulative state across tests and cleans up its temp dirs (TEST-003); new `scripts/test-hooks.js`, `scripts/test-cli-log.js`, and `scripts/test-text-util.js` cover the new code.
-- [DECISION] De-duplication: the five `*-sync` modules share `lib/sync-fs.js`; the ANSI logger moves to `lib/cli-log.js` and `slugify` to `lib/text-util.js`; `installer-args.parseArgs` is now table-driven (ARC-001, QUAL-001, QUAL-002).
-- [DECISION] Documentation: `ARCHITECTURE-MAP.md` counts are regenerated and now machine-guarded by `scripts/test-doc-surface-counts.js`; `state.STATE_FILE` is the canonical state-file constant and `artifact-map.js`'s scope is documented accurately (DOC-001, DOC-003, ARC-002).
-- [DECISION] Re-audit follow-ups: a fresh self-audit confirmed no regressions and closed the residual gaps it found - `installer-core.js` imports the shared logger (QUAL-003); `dashboard.js`/`planning-systems.js` consume `sync-fs` (ARC-003); the `lib/README` module catalog is complete and now guarded by a completeness check (DOC-004); the ledger-append comment is corrected (DOC-005); the corrupt-state error is typed rather than message-matched (ERR-004); and the hook tests assert each warning's text (TEST-005).
+- [DECISION] De-duplication (ARC-001, QUAL-001/002/003): the four `*-sync` modules share `lib/sync-check.js` (`addCheck`/`makeAddCheck`/`listFiles`) instead of copy-pasting them; removed dead helpers (two unused `rel()`, an unused `sha`); added `sync-fs.readTextOrNull` adopted by `requirements.js`, which now sources PRD/ROADMAP paths from `artifact-map`; fixed a boolean/string status wart in `repo-surface-sync`.
+- [DECISION] Test gate (TEST-001, TEST-002): `coverage:lib` now emits a json-summary and `scripts/check-per-file-coverage.js` (in `release:check`) fails any lib module below 70% lines, excluding the two environment-bound browser drivers, so a single file can no longer rot while the aggregate stays green; the `run()`/`appendLog()` write path of the three sync siblings is now tested for the no-banned-dash invariant.
+- [DECISION] Error handling (ERR-001): reverse-sync writes state before the ledger and surfaces a caught error as `requirementsError` instead of silently nulling it.
+- [DECISION] Security hardening (SEC-001, SEC-002): the MCP `requireRuntime` rejects any module name that is not a plain lib basename; `intent.cleanArrays` caps recursion depth so a pathologically deep YAML cannot overflow the stack.
+- [DECISION] Performance and docs (PERF-001/002, DOC-001, ARC-002): `have-nots` `findPositions` compiles its regex once per call; the bounded whole-ledger read is documented with an opt-in prune noted; the README's `docs/*` links are now absolute GitHub URLs (docs are deliberately excluded from the package); and `pillars.js` is delineated into its model and artifact-sync halves (a full split was deferred because the halves share public-API construction functions).
 
 ## Changes
 
-- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.13.1 version.
-- [DECISION] New runtime modules `lib/sync-fs.js`, `lib/cli-log.js`, and `lib/text-util.js` (lib module count 87 -> 90). No public command/agent/workflow/recipe surface change.
-- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, and the architecture map now reflect 3.13.1. The SECURITY supported-version table already carries the `3.13.x` row.
+- [DECISION] `package.json`, `package-lock.json`, and `packages/mcp/package.json` now publish the 3.13.2 version.
+- [DECISION] New runtime module `lib/sync-check.js` (lib module count 90 -> 91). No public command/agent/workflow/recipe surface change.
+- [DECISION] CHANGELOG, RELEASE notes, README, roadmap, reference, architecture, and the architecture map now reflect 3.13.2. The SECURITY supported-version table already carries the `3.13.x` row.
 
 ## Validation
 
 - [DECISION] `npm test` passed all command groups.
-- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor and the new 75 percent branch floor for `lib/**/*.js`.
+- [DECISION] `npm run release:check` passed `coverage:lib` above the 90 percent line floor and the 75 percent branch floor, and the new per-file floor (>= 70 percent lines across 88 lib modules).
 - [DECISION] `npm run release:check` passed `npm audit --omit=dev` with 0 vulnerabilities and `git diff --check`.
-- [DECISION] `npm run release:check` passed public surface docs for version 3.13.1 with 120 skills, 40 agents, 13 workflows, and 44 recipes.
+- [DECISION] `npm run release:check` passed public surface docs for version 3.13.2 with 120 skills, 40 agents, 13 workflows, and 44 recipes.
 - [DECISION] `npm run release:check` passed root and `@godpowers/mcp` package contents.
 
 ## Upgrade
 
-- [DECISION] Use `npm install -g godpowers@3.13.1` or `npx godpowers@3.13.1`.
-- [DECISION] No migration is required. Existing projects are unaffected; the changes are internal correctness, security, test-gate, and maintainability fixes with no surface change.
+- [DECISION] Use `npm install -g godpowers@3.13.2` or `npx godpowers@3.13.2`.
+- [DECISION] No migration is required. The changes are internal de-duplication, error-visibility, security, test-gate, and documentation improvements with no surface change.
 
 ## Notes
 
-- [DECISION] The publish targets are npm `godpowers@3.13.1`, npm `@godpowers/mcp@3.13.1`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.13.1`.
+- [DECISION] The publish targets are npm `godpowers@3.13.2`, npm `@godpowers/mcp@3.13.2`, and GitHub release `https://github.com/aihxp/godpowers/releases/tag/v3.13.2`.
 - [DECISION] The tag-triggered GitHub publish workflow remains the preferred npm path because it publishes with provenance. This release has not been tagged or published to npm yet.

package/lib/README.md

@@ -29,6 +29,7 @@ package-level integrations.
 | `atomic-write.js` | Write load-bearing files through temp-file validation and atomic rename. |
 | `fs-async.js` | Promise-based file read/write helpers for non-blocking runtime paths. |
 | `sync-fs.js` | Shared project-relative read/write/exists/readJson helpers for the `*-sync` modules. |
+| `sync-check.js` | Shared check-builder (`addCheck`/`makeAddCheck`) and file-lister for the `*-sync` modules. |
 
 ## Events and observability
 

package/lib/evidence.js

@@ -195,6 +195,10 @@ function appendJsonlAtomic(file, record) {
   return file;
 }
 
+// Reads the whole ledger into memory. This is bounded and acceptable for a CLI:
+// each record caps its stdout/stderr tails (TAIL_CHARS) so growth is slow, and
+// every consumer reads it once per command, never in a loop. If a long-lived
+// project's ledger ever grows large, add an opt-in prune/size cap here (PERF-002).
 function readJsonl(file) {
   let raw;
   try {

package/lib/have-nots-validator.js

@@ -53,9 +53,13 @@ const LABEL_TAGS = ['DECISION', 'HYPOTHESIS', 'OPEN QUESTION', 'OPEN-QUESTION'];
 function findPositions(content, regex) {
   const positions = [];
   const lines = content.split('\n');
+  // Compile once and reuse across lines (PERF-001); reset lastIndex per line so
+  // matching is identical to a fresh per-line regex.
+  const flags = regex.flags.includes('g') ? regex.flags : regex.flags + 'g';
+  const localRegex = new RegExp(regex.source, flags);
   for (let i = 0; i < lines.length; i++) {
+    localRegex.lastIndex = 0;
     let match;
-    const localRegex = new RegExp(regex.source, regex.flags.includes('g') ? regex.flags : regex.flags + 'g');
     while ((match = localRegex.exec(lines[i])) !== null) {
       positions.push({ line: i + 1, column: match.index + 1, matched: match[0] });
     }

package/lib/intent.js

@@ -332,15 +332,20 @@ function splitInlineArray(text) {
   return parts;
 }
 
-function cleanArrays(obj) {
-  if (Array.isArray(obj)) return obj.map(cleanArrays);
+// Far beyond any legitimate config nesting; caps recursion so a hostile,
+// thousands-deep YAML file cannot overflow the stack (SEC-002).
+const MAX_CLEAN_DEPTH = 200;
+
+function cleanArrays(obj, depth = 0) {
+  if (depth > MAX_CLEAN_DEPTH) return obj;
+  if (Array.isArray(obj)) return obj.map((v) => cleanArrays(v, depth + 1));
   if (obj && typeof obj === 'object') {
     // Detect array container (legacy or new)
-    if (obj.__items__) return obj.__items__.map(cleanArrays);
+    if (obj.__items__) return obj.__items__.map((v) => cleanArrays(v, depth + 1));
     if (obj.__pending_array__) return obj.__pending_array__;
     const cleaned = {};
     for (const [k, v] of Object.entries(obj)) {
-      cleaned[k] = cleanArrays(v);
+      cleaned[k] = cleanArrays(v, depth + 1);
     }
     return cleaned;
   }

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

@@ -100,10 +100,6 @@ 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()) {
@@ -473,7 +469,6 @@ module.exports = {
   _private: {
     classifyFile,
     extractSignals,
-    filesForKinds,
-    sha
+    filesForKinds
   }
 };

package/lib/recipe-coverage-sync.js

@@ -10,6 +10,9 @@ 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';
 
@@ -42,18 +45,6 @@ const REQUIRED_COVERAGE = [
 ];
 
 
-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`;
   return fs.existsSync(path.join(projectRoot, rel)) ? rel : 'routing/recipes/';

package/lib/release-surface-sync.js

@@ -10,6 +10,9 @@ 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';
 
@@ -46,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-surface-sync.js

@@ -12,6 +12,7 @@ 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');
@@ -52,19 +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 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 releaseGateText(projectRoot, pkg) {
   return [
     JSON.stringify((pkg && pkg.scripts) || {}),
@@ -81,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$/);
@@ -485,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

@@ -33,9 +33,11 @@ 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'];
@@ -44,16 +46,6 @@ 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');
 }

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

@@ -11,6 +11,9 @@ 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([
@@ -101,15 +104,6 @@ const TIER_GATE_COMMANDS = new Set([
   '/god-harden'
 ]);
 
-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 : [];
 }
@@ -122,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/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

@@ -34,4 +34,16 @@ function readJson(projectRoot, relPath) {
   }
 }
 
-module.exports = { read, write, exists, readJson };
+// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "3.13.1",
+  "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 --branches 75 --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": [