godpowers 3.11.0 → 3.13.1

package/hooks/pre-tool-use.sh

@@ -1,52 +1,64 @@
 #!/usr/bin/env bash
-# Godpowers PreToolUse Safety Hook
-# Runs before destructive tool calls in a Godpowers project.
-# Warns on: rm -rf, git reset --hard, force push to main, deleting .godpowers/,
-# and irreversible public release actions.
+# Godpowers PreToolUse advisory hook (best-effort, NOT a security boundary).
+#
+# Warns before some common destructive command spellings when run inside a
+# Godpowers project: deleting .godpowers/, git reset --hard, force push,
+# npm publish, gh release create. It matches command text heuristically after
+# normalizing whitespace, so it tolerates spacing and short-flag variants
+# (rm -fr, -r -f, ./ prefix, trailing slash, push -f). It is still deliberately
+# conservative and is easily bypassed by uncommon spellings, quoting, aliases,
+# or a child process that does the deletion. Treat it as a typo guard that buys
+# a confirmation prompt, not as a guarantee. See SECURITY.md.
 
 set -euo pipefail
 
-TOOL_NAME="${CLAUDE_TOOL_NAME:-}"
 TOOL_INPUT="${CLAUDE_TOOL_INPUT:-}"
 
 if [ ! -d ".godpowers" ]; then
   exit 0
 fi
 
-# Pattern matches that should warn
-case "$TOOL_INPUT" in
-  *"rm -rf .godpowers"*)
-    echo "WARNING: About to delete the .godpowers/ directory."
-    echo "This destroys all PROGRESS, PRD, ARCH, ROADMAP, and other artifacts."
-    echo "If this is intentional, confirm in chat before proceeding."
-    exit 1
-    ;;
-  *"git reset --hard"*)
-    echo "WARNING: git reset --hard discards uncommitted work."
-    echo "If you have artifacts not yet committed, they will be lost."
-    echo "Consider git stash first."
-    exit 1
-    ;;
-  *"git push --force"*)
-    echo "WARNING: Force pushing. If pushing to main/master, this can"
-    echo "destroy collaborators' work."
-    exit 1
-    ;;
-  *"npm publish"*)
-    echo "WARNING: npm publish is a public release action."
-    echo "Confirm release checklist, repo-doc-sync, repo-surface-sync,"
-    echo "release-surface-sync, package contents, and installer smoke first."
-    exit 1
-    ;;
-  *"gh release create"*)
-    echo "WARNING: gh release create publishes public release notes."
-    echo "Confirm README, badges, CHANGELOG, RELEASE, package, tag, and npm version agree."
-    exit 1
-    ;;
-  *"rm -rf node_modules"*)
-    # Allowed: this is just cache
-    exit 0
-    ;;
-esac
+# Collapse tabs and runs of spaces so spacing variants normalize to one form.
+norm="$(printf '%s' "$TOOL_INPUT" | tr '\t' ' ' | tr -s ' ')"
+
+matches() {
+  printf '%s' "$norm" | grep -Eq -- "$1"
+}
+
+# rm targeting .godpowers (optional ./ or / prefix, optional trailing slash)
+# that carries a recursive flag in any spelling: -rf, -fr, -r -f, -R, --recursive.
+if matches 'rm( +-[a-zA-Z]+)* +\.?/?\.godpowers(/|$| )' && matches ' -[a-zA-Z]*[rR]|--recursive'; then
+  echo "WARNING: About to delete the .godpowers/ directory."
+  echo "This destroys all PROGRESS, PRD, ARCH, ROADMAP, and other artifacts."
+  echo "If this is intentional, confirm in chat before proceeding."
+  exit 1
+fi
+
+if matches 'git +reset +--hard'; then
+  echo "WARNING: git reset --hard discards uncommitted work."
+  echo "If you have artifacts not yet committed, they will be lost."
+  echo "Consider git stash first."
+  exit 1
+fi
+
+# git push with a force flag: --force, --force-with-lease, or a standalone -f.
+if matches 'git +push +' && matches '(--force(-with-lease)?| -f( |$))'; then
+  echo "WARNING: Force pushing. If pushing to main/master, this can"
+  echo "destroy collaborators' work."
+  exit 1
+fi
+
+if matches 'npm +publish'; then
+  echo "WARNING: npm publish is a public release action."
+  echo "Confirm release checklist, repo-doc-sync, repo-surface-sync,"
+  echo "release-surface-sync, package contents, and installer smoke first."
+  exit 1
+fi
+
+if matches 'gh +release +create'; then
+  echo "WARNING: gh release create publishes public release notes."
+  echo "Confirm README, badges, CHANGELOG, RELEASE, package, tag, and npm version agree."
+  exit 1
+fi
 
 exit 0

package/lib/README.md

@@ -28,6 +28,7 @@ package-level integrations.
 | `cost-tracker.js` | Track token and cost estimates from event streams. |
 | `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. |
 
 ## Events and observability
 
@@ -38,12 +39,17 @@ package-level integrations.
 | `otel-exporter.js` | Export Godpowers events in an OpenTelemetry-shaped format. |
 | `runtime-audit.js` | Audit runtime health and expected project state. |
 | `runtime-test.js` | Provide runtime checks used by package tests. |
+| `evidence.js` | Enforced producer of executed/attested verification records, the state.json rollup, gate events, reflections, memory, lessons, and outcome loops. |
+| `evidence-import.js` | Import an existing `.mythify/` ledger into `.godpowers/ledger/`. |
+| `work-report.js` | Render the verification play-by-play from the evidence ledger. |
+| `adoption-metrics.js` | Derive adoption and outcome metrics from event streams. |
 
 ## Routing and execution
 
 | Module | Purpose |
 |--------|---------|
 | `router.js` | Resolve user intent to skills, agents, recipes, and workflows. |
+| `quarterback.js` | Entry router that classifies a prompt into a play and refuses new work when the project is on red. |
 | `command-families.js` | Define UX command families, status views, decision ladders, and trigger precedence helpers. |
 | `recipes.js` | Load and validate routing recipes. |
 | `workflow-parser.js` | Parse workflow YAML into executable steps. |
@@ -59,7 +65,7 @@ package-level integrations.
 
 | Module | Purpose |
 |--------|---------|
-| `artifact-map.js` | Centralize canonical artifact paths for dashboards, gates, and helpers. |
+| `artifact-map.js` | Tier gate artifact map: the per-tier required artifacts and state steps used by dashboards, gates, and doc-count checks. (Module-local paths stay in their owning module; `state.json` is named via `state.STATE_FILE`.) |
 | `artifact-linter.js` | Check artifacts for required labels, evidence, and domain precision. |
 | `artifact-diff.js` | Compare artifact changes for review and release workflows. |
 | `gate.js` | Run executable artifact gates for Phase 1 tier completion checks. |
@@ -98,6 +104,7 @@ package-level integrations.
 | `drift-detector.js` | Detect context drift between artifacts and implementation. |
 | `impact.js` | Summarize expected impact of proposed changes. |
 | `linkage.js` | Connect artifacts, stories, and implementation files. |
+| `requirements.js` | Track which PRD requirements are done, in progress, or untouched from disk evidence. |
 | `multi-repo-detector.js` | Detect multi-repository workspaces. |
 | `reverse-sync.js` | Reflect implementation changes back into artifacts. |
 | `review-required.js` | Decide when review gates should block progress. |
@@ -111,6 +118,9 @@ package-level integrations.
 | `installer-files.js` | File-copy helpers shared by the installer and its tests. |
 | `installer-args.js` | Parse `bin/install.js` arguments and subcommands. |
 | `cli-dispatch.js` | Dispatch local CLI helper commands such as status, quick-proof, gate, dogfood, and extension-scaffold. |
+| `cli-log.js` | Shared ANSI console logger (log/success/warn/error) for the binary and CLI dispatch. |
+| `text-util.js` | Small shared string helpers (the canonical `slugify`). |
+| `mcp-info.js` | Render read-only MCP companion setup instructions for `npx godpowers mcp-info`. |
 | `install-profiles.js` | Select smaller role-specific slash-command install surfaces. |
 | `surface-profile.js` | Preview and apply runtime command surface profile switches after install. |
 | `installer-runtimes.js` | Map supported runtimes to their config directories. |

package/lib/artifact-map.js

@@ -1,5 +1,11 @@
 /**
  * Shared tier artifact map for dashboard, gates, and documentation checks.
+ *
+ * Scope: this owns the per-tier *gate artifacts* (which files a tier requires
+ * and the state step it maps to). It is not a flat registry of every
+ * `.godpowers/...` path: module-local artifacts (a sync module's log file, the
+ * evidence ledger) live in their owning module, and `state.json` is named via
+ * `state.STATE_FILE`.
  */
 
 const TIER_ARTIFACTS = {

package/lib/cli-dispatch.js

@@ -5,25 +5,10 @@
 const gate = require('./gate');
 const identity = require('./package-identity');
 const stateAdvance = require('./state-advance');
+const { log, success, warn, error } = require('./cli-log');
 
 const VERSION = identity.PACKAGE_VERSION;
 
-function log(msg) {
-  console.log(`  ${msg}`);
-}
-
-function success(msg) {
-  console.log(`  \x1b[32m+\x1b[0m ${msg}`);
-}
-
-function warn(msg) {
-  console.log(`  \x1b[33m!\x1b[0m ${msg}`);
-}
-
-function error(msg) {
-  console.error(`  \x1b[31mx\x1b[0m ${msg}`);
-}
-
 function runAutomationCommand(opts) {
   const automation = require('./automation-providers');
   const result = opts.command === 'automation-setup'
@@ -501,7 +486,20 @@ function runOutcomeCommand(opts) {
       projectRoot
     });
   } else if (action === 'check') {
-    payload = evidence.outcome.check(opts.outcomeSlug, { projectRoot });
+    payload = evidence.outcome.check(opts.outcomeSlug, {
+      projectRoot,
+      // SEC-002: announce the disk-sourced verifier before it runs, so running
+      // `outcome check` inside an untrusted cloned repo cannot silently execute
+      // a planted command. Goes to stderr so it never corrupts --json on stdout.
+      notice: ({ verifier, source }) => {
+        const rel = relLedger({ project: projectRoot }, source) || source;
+        process.stderr.write(
+          `  notice: outcome '${opts.outcomeSlug}' runs a verifier loaded from ${rel}\n` +
+          `          command: ${verifier}\n` +
+          `          (.godpowers/ledger/ carries executable state; only run 'outcome check' in repos you trust)\n`
+        );
+      }
+    });
   } else if (action === 'stop') {
     payload = evidence.outcome.stop(opts.outcomeSlug, opts.reason || undefined, { projectRoot });
   } else {
@@ -626,11 +624,22 @@ const COMMAND_RUNNERS = {
 
 function runCommand(opts) {
   const runner = COMMAND_RUNNERS[opts.command];
-  if (runner) {
+  if (!runner) return false;
+  try {
     runner(opts);
-    return true;
+  } catch (err) {
+    // ERR-002: a corrupt state.json throws from state.read(). Surface the
+    // helpful message as a clean one-liner with a non-zero exit instead of a
+    // raw stack trace. Match the typed error code (ERR-004), not the message
+    // prose. Re-throw anything else so genuine bugs still surface.
+    if (err && err.code === 'CORRUPT_STATE') {
+      error(err.message);
+      process.exitCode = 1;
+    } else {
+      throw err;
+    }
   }
-  return false;
+  return true;
 }
 
 module.exports = {

package/lib/cli-log.js

@@ -0,0 +1,24 @@
+/**
+ * Shared ANSI console logger for the installer binary and CLI dispatch (QUAL-002).
+ *
+ * bin/install.js and lib/cli-dispatch.js previously defined these four helpers
+ * verbatim. They now share one copy so the prefix/colour convention lives once.
+ */
+
+function log(msg) {
+  console.log(`  ${msg}`);
+}
+
+function success(msg) {
+  console.log(`  \x1b[32m+\x1b[0m ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`  \x1b[33m!\x1b[0m ${msg}`);
+}
+
+function error(msg) {
+  console.error(`  \x1b[31mx\x1b[0m ${msg}`);
+}
+
+module.exports = { log, success, warn, error };

package/lib/dashboard.js

@@ -17,6 +17,7 @@ const repoDocSync = require('./repo-doc-sync');
 const repoSurfaceSync = require('./repo-surface-sync');
 const hostCapabilities = require('./host-capabilities');
 const artifactMap = require('./artifact-map');
+const { read: readText, exists } = require('./sync-fs');
 
 const GOD_DIR = '.godpowers';
 const PRD_PATH = artifactMap.requiredArtifactsForTier('prd')[0].path;
@@ -25,16 +26,6 @@ const CHECKPOINT_PATH = '.godpowers/CHECKPOINT.md';
 const SYNC_LOG_PATH = '.godpowers/SYNC-LOG.md';
 const REVIEW_PATH = '.godpowers/REVIEW-REQUIRED.md';
 
-function exists(projectRoot, relPath) {
-  return fs.existsSync(path.join(projectRoot, relPath));
-}
-
-function readText(projectRoot, relPath) {
-  const file = path.join(projectRoot, relPath);
-  if (!fs.existsSync(file)) return '';
-  return fs.readFileSync(file, 'utf8');
-}
-
 function mtimeMs(projectRoot, relPath) {
   const file = path.join(projectRoot, relPath);
   if (!fs.existsSync(file)) return null;

package/lib/evidence.js

@@ -10,8 +10,9 @@
  * Adaptations from the upstream Node engine (see .provenance.json):
  *   - Mythify's plan/step context becomes Godpowers' arc/substep context.
  *   - The .mythify/ state dir becomes .godpowers/ledger/.
- *   - The jsonl append goes through lib/atomic-write.js (temp + rename) so a
- *     torn record is never visible.
+ *   - The jsonl append uses O_APPEND (fs.appendFileSync) so concurrent writers
+ *     never clobber each other's records; a torn line from an interleaved large
+ *     write is tolerated by the reader, which skips unparseable records.
  *
  * What this adds on top of the upstream engine (the Godpowers integration):
  *   1. .godpowers/ledger/verifications.jsonl: append-only, Mythify-shape record,
@@ -61,6 +62,9 @@ const events = require('./events');
 const TAIL_CHARS = 4000;
 const DEFAULT_TIMEOUT_SECONDS = 300;
 const DIAGNOSTICS_LIMIT = 1000;
+// Cap on captured stdout/stderr per verify command. Exceeding it makes
+// spawnSync raise ENOBUFS and truncate output, so the verdict is unreliable.
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 
 // Substeps whose close gate requires an executed, verified:true record (the
 // runtime/executable-gated tiers). Other substeps (planning, repo, observe,
@@ -161,19 +165,33 @@ function slugify(text) {
     .slice(0, 40);
 }
 
+// SEC-003: mask obvious secret shapes before echoing a command into the
+// human-readable LEDGER-LOG.md. The durable verifications.jsonl record keeps the
+// exact command (it is the audit source of truth); this only protects the log
+// echo. Output tails can still carry secrets, so SECURITY.md documents that
+// .godpowers/ledger/ may capture sensitive output.
+function redactSecrets(text) {
+  return String(text == null ? '' : text)
+    .replace(/\bgh[pousr]_[A-Za-z0-9]{16,}\b/g, 'gh*_***REDACTED***')
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, 'sk-***REDACTED***')
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, 'AKIA***REDACTED***')
+    .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, 'xox*-***REDACTED***')
+    .replace(/(--?(?:token|password|passwd|secret|api[-_]?key)[=\s])\S+/gi, '$1***REDACTED***');
+}
+
 // ---------------------------------------------------------------------------
-// Ledger append (atomic, via lib/atomic-write.js) and tolerant read
+// Ledger append (O_APPEND) and tolerant read
 // ---------------------------------------------------------------------------
 
 function appendJsonlAtomic(file, record) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  let existing = '';
-  try {
-    existing = fs.readFileSync(file, 'utf8');
-  } catch (_) {
-    existing = '';
-  }
-  atomic.writeFileAtomic(file, existing + JSON.stringify(record) + '\n');
+  // O_APPEND: each record is written at EOF in a single positioned write, so
+  // two concurrent writers never overwrite each other's record. The previous
+  // read-concat-rewrite was last-writer-wins (it lost records under concurrent
+  // invocation) and rewrote the whole file on every append (O(n) per record).
+  // A torn line from an interleaved oversized write is tolerated by readJsonl,
+  // which skips unparseable records. Mirrors the append in lib/events.js.
+  fs.appendFileSync(file, JSON.stringify(record) + '\n');
   return file;
 }
 
@@ -255,18 +273,27 @@ function runCommand(command, timeoutSeconds) {
     shell: true,
     encoding: 'utf8',
     timeout: Math.round(timeoutSeconds * 1000),
-    maxBuffer: 16 * 1024 * 1024
+    maxBuffer: MAX_OUTPUT_BYTES
   });
   const durationSeconds = Number(process.hrtime.bigint() - startedAt) / 1e9;
   let stdoutTail = tail(run.stdout);
   let stderrTail = tail(run.stderr);
   const timedOut = Boolean(run.error && run.error.code === 'ETIMEDOUT');
+  const bufferOverflow = Boolean(run.error && run.error.code === 'ENOBUFS');
   let exitCode;
   let verified;
   if (timedOut) {
     exitCode = -1;
     verified = false;
     stderrTail = stderrTail + (stderrTail ? '\n' : '') + `(timed out after ${timeoutSeconds} seconds)`;
+  } else if (bufferOverflow) {
+    // Output exceeded the capture buffer: spawnSync truncated stdout/stderr, so
+    // we cannot trust the exit status. Surface this distinctly rather than
+    // folding it into a plain command failure.
+    exitCode = -1;
+    verified = false;
+    stderrTail = stderrTail + (stderrTail ? '\n' : '') +
+      `(output exceeded ${Math.round(MAX_OUTPUT_BYTES / (1024 * 1024))} MB buffer; output truncated and verdict unreliable)`;
   } else if (typeof run.status === 'number') {
     exitCode = run.status;
     verified = exitCode === 0;
@@ -280,7 +307,7 @@ function runCommand(command, timeoutSeconds) {
         : 'command did not produce an exit code';
     stderrTail = stderrTail + (stderrTail ? '\n' : '') + `(${reason})`;
   }
-  return { exitCode, verified, durationSeconds, stdoutTail, stderrTail, timedOut };
+  return { exitCode, verified, durationSeconds, stdoutTail, stderrTail, timedOut, bufferOverflow };
 }
 
 // ---------------------------------------------------------------------------
@@ -449,7 +476,7 @@ function verify(command, opts = {}) {
   appendRecord(projectRoot, record);
   appendLog(
     projectRoot,
-    `verify ${record.verified ? 'PASS' : 'FAIL'} substep=${context.substep || '-'} exit=${record.exit_code} cmd=\`${command}\``
+    `verify ${record.verified ? 'PASS' : 'FAIL'} substep=${context.substep || '-'} exit=${record.exit_code} cmd=\`${redactSecrets(command)}\``
   );
 
   const rollup = rollUp(projectRoot, opts.substep, record);
@@ -818,6 +845,15 @@ function outcomeCheck(name, opts = {}) {
   if (goal.status !== 'active') return { ran: false, reason: `outcome-${goal.status}`, goal };
   if (!goal.verifier) return { ran: false, reason: 'no-verifier', goal };
 
+  // SEC-002: the verifier is a shell command read from goal.json on disk, not
+  // from a live flag, so `outcome check` in a cloned untrusted repo would
+  // otherwise execute a planted command silently. Surface what is about to run
+  // and where it came from before executing. The notice is informational; the
+  // CLI passes one that prints to stderr.
+  if (typeof opts.notice === 'function') {
+    opts.notice({ verifier: goal.verifier, source: outcomeGoalPath(projectRoot, slug) });
+  }
+
   const result = verify(goal.verifier, {
     substep: goal.substep || undefined,
     claim: goal.title,
@@ -901,6 +937,7 @@ module.exports = {
   DEFAULT_TIMEOUT_SECONDS,
   // Internals exposed for tests and the re-sync script.
   _runCommand: runCommand,
+  _redactSecrets: redactSecrets,
   _toStateCommand: toStateCommand,
   _substepContext: substepContext,
   _rollUp: rollUp,

package/lib/gate.js

@@ -215,7 +215,7 @@ function checkStateStepEvidence(projectRoot, tier, result) {
   const stepRef = artifactMap.stateStepForTier(tier);
   if (!stepRef) return null;
 
-  const relPath = '.godpowers/state.json';
+  const relPath = stateStore.STATE_FILE;
   const currentState = stateStore.read(projectRoot);
   if (!currentState) {
     const finding = makeFinding(
@@ -275,7 +275,7 @@ function checkStateStepEvidence(projectRoot, tier, result) {
 // tier-prefixed so the build tier keeps its existing `build-verification-*`
 // contract while harden gains `harden-verification-*`.
 function checkExecutedEvidence(result, step, tier) {
-  const relPath = '.godpowers/state.json';
+  const relPath = stateStore.STATE_FILE;
   if (!step) return;
   const label = tier.charAt(0).toUpperCase() + tier.slice(1);
   const failedCommands = commandsWithStatus(step, 'fail');