muse-crew 0.14.2 → 0.14.4

package/lib/crew-release.sh

@@ -81,7 +81,8 @@ _validate_workflows() {
   # --- Parse gate (restored 2026-09-18, finding B2) ---
   # The workflow runtime accepts top-level `export`, `return`, and `await`
   # (it wraps scripts in an async function), so neither `node --check` on the
-  # raw .js (vacuous for ESM — exits 0 even on blatant syntax errors) nor a
+  # raw .js (goal confusion: parsed as a module it masks breakage the
+  # async-wrapped loader rejects — a false negative, not a true check) nor a
   # .mjs check (rejects the runtime-legal top-level `return`) is correct.
   # Emulate the runtime instead: strip `export`, wrap the script in an async
   # function, then node --check the result. Tokenizer errors (e.g. an
@@ -210,6 +211,210 @@ _link_dep_node_modules() {
   echo "DEP-NODE-MODULES: $link -> $src"
 }
 
+# ── lib entry gate (blocker 21) ─────────────────────────────────────
+# Every shipped lib entry must actually EXECUTE (JS) — node --check is
+# banned from this gate. The true reason, not the folklore: node --check
+# can check a file under a different PARSE GOAL than the real loader uses
+# (blocker 21: checked as a script, loaded as a module), and V8's
+# preparser skips function bodies — a parse check proves nothing about the
+# loader's path. Real execution is the only check that uses the loader's
+# goal. Parse goal: whether Node reads a .js file as a module
+# (import/export, no top-level return) or as a script — set by the nearest
+# package.json's `type` field (shipped lib/package.json pins
+# {"type":"module"}).
+# What runs how:
+#   lib/*.js  with a first line carrying a node shebang token
+#             (#!/usr/bin/env node, #!/bin/node, env -S variants) →
+#             `node <file> --help` through the $tmp/liblink symlink, which
+#             mirrors production's $CREW_HOME/current path shape (the
+#             ff3fb53 realpath main-guard exists exactly for this shape; the
+#             gate runs through the link so it can tell the broken guard
+#             from the fixed one). shebang⇔CLI contract: exit 0, non-empty
+#             stdout.
+#   lib/*.js  without a shebang → bare `node <file>` through the link
+#             (import-safe module contract: exit 0, no side effects).
+#             Residual, documented: import-safety itself is unchecked — an
+#             import-dirty-but-exit-0 module passes. No cheap mechanism.
+#   lib/*.sh  (except test-*.sh) → `bash -n <file>` — parse-only by
+#             necessity: real .sh execution risks side effects. Test scripts
+#             are exercised by tests/run.sh, not shipped as library entries
+#             (they get a `skipped` evidence row, not silence).
+#   lib/*.py  → `python3 -m py_compile <file>` (bytecode goes to a temp
+#             PYTHONPYCACHEPREFIX, never into the staging dir) — parse-only
+#             by the same necessity.
+# So the headline is honest: the gate EXECUTES every JS entry and
+# PARSE-CHECKS sh/py.
+# Boundary: `--help` short-circuits before argument parsing — the gate
+# proves an entry LOADS, not that its main path behaves. The suite covers
+# behavior. workflows/*.js are not covered by this gate at all; their true
+# gate is the suite's loader emulation (publish-verdict-first.test.js —
+# see root AGENTS.md).
+# Every entry gets one ENTRY-GATE pass/FAIL line and one row in
+# $staging_dir/entry-gate.json {release, node, entries:[{file,kind,verdict,exit,reason}]}.
+# A FAIL reason folds the first 10 stderr lines in, so the row names the
+# actual error instead of a bare exit code.
+# On gate failure cmd_deploy copies entry-gate.json to $CREW_HOME before
+# removing the staging dir, and the rejection names the failing entries —
+# the evidence survives the burn.
+# All verdicts are aggregated (no early stop) so the evidence names every
+# failure. Returns 30 when any entry failed; any other exit is a gate
+# mechanism failure (fail closed — the release is rejected either way).
+_validate_lib_entries() {
+  local dir="$1" release="$2"
+  local tmp base f kind st reason verdict
+  tmp="$(mktemp -d)"
+  local rows="$tmp/rows.jsonl"
+  : > "$rows"
+  local failed=0
+  local node_version
+  node_version="$(node --version 2>/dev/null || echo "node-missing")"
+  # Invoke JS entries through a symlink mirroring production's
+  # $CREW_HOME/current path shape — the ff3fb53 realpath main-guard exists
+  # exactly for that shape, and the gate can only tell the broken guard
+  # from the fixed one when it exercises the symlinked path.
+  local link="$tmp/liblink"
+  if ! ln -s "$dir/lib" "$link" 2>/dev/null || [ ! -L "$link" ]; then
+    echo "ENTRY-GATE FAIL: cannot create lib invocation symlink ($link) — failing closed" >&2
+    return 31
+  fi
+
+  _gate_row() { # file kind verdict exit reason
+    node -e 'console.log(JSON.stringify({file:process.argv[1],kind:process.argv[2],verdict:process.argv[3],exit:+process.argv[4],reason:process.argv[5]}))' \
+      "$1" "$2" "$3" "$4" "$5" >> "$rows"
+  }
+
+  _gate_js() { # $1 = real file path; invoked through $link (the $CREW_HOME/current-shaped symlink)
+    local first
+    first="$(head -n 1 "$1")"
+    local cli=0
+    # Shebang match on a node token: #!/usr/bin/env node, #!/bin/node,
+    # env -S variants all classify as CLI.
+    case "$first" in
+      "#!"*"node"*) cli=1 ;;
+    esac
+    st=0
+    reason="ok"
+    local target="$link/$base"
+    if [ "$cli" = 1 ]; then
+      timeout 30 node "$target" --help >"$tmp/out" 2>"$tmp/err" || st=$?
+      kind="js-cli"
+      if [ "$st" -eq 0 ] && [ ! -s "$tmp/out" ]; then
+        reason="empty-stdout"
+        st=1
+      fi
+    else
+      timeout 30 node "$target" >"$tmp/out" 2>"$tmp/err" || st=$?
+      kind="js-module"
+    fi
+    if [ "$st" -eq 0 ]; then
+      reason="ok"
+    else
+      if grep -q "SyntaxError" "$tmp/err" 2>/dev/null; then
+        reason="syntax-error"
+      elif [ "$reason" != "empty-stdout" ]; then
+        reason="exit=$st"
+      fi
+      # Fold the first 10 stderr lines into the reason: a bare exit code
+      # names nothing, and the staging dir (with $tmp/err) is removed on
+      # failure — the row is the surviving evidence.
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+    fi
+    verdict="pass"
+    [ "$st" -eq 0 ] || { verdict="FAIL"; failed=1; }
+    if [ "$verdict" = "pass" ]; then
+      echo "ENTRY-GATE pass $base ($kind)"
+    else
+      echo "ENTRY-GATE FAIL $base ($kind): $reason" >&2
+    fi
+    _gate_row "$base" "$kind" "$verdict" "$st" "$reason"
+  }
+
+  for f in "$dir"/lib/*.js; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    if ! command -v node >/dev/null 2>&1; then
+      echo "ENTRY-GATE FAIL $base (js): node missing" >&2
+      _gate_row "$base" "js" "FAIL" 127 "node-missing"
+      failed=1
+      continue
+    fi
+    _gate_js "$f"
+  done
+
+  for f in "$dir"/lib/*.sh; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    case "$base" in
+      test-*)
+        # Out of scope for the gate — but never silent: a skipped row, so
+        # "0 rows" is distinguishable from "all skipped".
+        _gate_row "$base" "sh" "skipped" 0 "test scripts are exercised by tests/run.sh, not shipped as library entries"
+        echo "ENTRY-GATE skipped $base (sh)"
+        continue ;;
+    esac
+    st=0
+    bash -n "$f" 2>"$tmp/err" || st=$?
+    reason="ok"; verdict="pass"
+    if [ "$st" -ne 0 ]; then
+      reason="bash-n exit=$st"
+      # Same evidence rule as the JS gate: the row names the actual error.
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+      verdict="FAIL"; failed=1
+      echo "ENTRY-GATE FAIL $base (sh): $reason" >&2
+    else
+      echo "ENTRY-GATE pass $base (sh)"
+    fi
+    _gate_row "$base" "sh" "$verdict" "$st" "$reason"
+  done
+
+  for f in "$dir"/lib/*.py; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f")"
+    st=0
+    if ! command -v python3 >/dev/null 2>&1; then
+      st=127; reason="python3-missing"
+    else
+      # Bytecode goes to a temp prefix — never into the staging dir, or it
+      # would be shipped inside the release.
+      PYTHONPYCACHEPREFIX="$tmp/pyc" python3 -m py_compile "$f" 2>"$tmp/err" || st=$?
+      reason="ok"
+      [ "$st" -eq 0 ] || reason="py-compile exit=$st"
+    fi
+    verdict="pass"
+    if [ "$st" -ne 0 ]; then
+      local errhead
+      errhead="$(head -n 10 "$tmp/err" 2>/dev/null | tr '\n' ';' | cut -c1-500)"
+      [ -n "$errhead" ] && reason="$reason | $errhead"
+      verdict="FAIL"; failed=1
+    fi
+    if [ "$verdict" = "pass" ]; then
+      echo "ENTRY-GATE pass $base (py)"
+    else
+      echo "ENTRY-GATE FAIL $base (py): $reason" >&2
+    fi
+    _gate_row "$base" "py" "$verdict" "$st" "$reason"
+  done
+
+  # Evidence: one row per enumerated entry.
+  node -e '
+    const fs = require("fs");
+    const rows = fs.readFileSync(process.argv[1], "utf8").split("\n").filter(Boolean).map(l => JSON.parse(l));
+    fs.writeFileSync(process.argv[4], JSON.stringify({ release: process.argv[2], node: process.argv[3], entries: rows }, null, 2) + "\n");
+  ' "$rows" "$release" "$node_version" "$dir/entry-gate.json"
+  rm -rf "$tmp"
+
+  if [ "$failed" -ne 0 ]; then
+    echo "ENTRY-GATE: $failed entr(y/ies) failed — release rejected" >&2
+    return 30
+  fi
+  echo "ENTRY-GATE: all lib entries executed cleanly"
+  return 0
+}
+
 # ── deploy ────────────────────────────────────────────────────────────
 # Build, validate, and atomically activate a release from repo HEAD.
 # Single command — no cross-step lock needed.
@@ -302,6 +507,29 @@ cmd_deploy() {
         *)  die "release $hash rejected: workflow validation failed (unexpected exit $_vw_status)" ;;
       esac
     fi
+    # Gate: every shipped lib entry must actually execute (blocker 21).
+    # _validate_lib_entries returns 30 when any entry failed, anything else
+    # on a gate mechanism failure; either way the release is rejected. The
+    # rejection names the failing entries (not just the gate) and points at
+    # the preserved evidence — the evidence is copied to $CREW_HOME before
+    # the staging dir is removed, so it survives the burn.
+    _le_status=0
+    _validate_lib_entries "$staging_dir" "$hash" || _le_status=$?
+    if [ "$_le_status" -ne 0 ]; then
+      # The staging dir (and its entry-gate.json) is about to be removed —
+      # preserve the evidence first, then name the failing entries in the
+      # rejection instead of a bare exit code.
+      local _le_evidence="$CREW_HOME/entry-gate-$hash.json"
+      [ -f "$staging_dir/entry-gate.json" ] && cp "$staging_dir/entry-gate.json" "$_le_evidence"
+      local _le_fails="(no entry rows — gate mechanism failure)"
+      if [ -f "$staging_dir/entry-gate.json" ]; then
+        _le_fails="$(node -e 'const j=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const f=j.entries.filter(e=>e.verdict==="FAIL").map(e=>e.file+" ("+e.kind+")");console.log(f.length?f.join(", "):"(no failing entries — gate mechanism failure)")' "$staging_dir/entry-gate.json" 2>/dev/null)"
+      fi
+      local _le_meaning="gate mechanism failure"
+      [ "$_le_status" = 30 ] && _le_meaning="at least one entry failed"
+      rm -rf "$staging_dir"
+      die "release $hash rejected: lib entry gate failed (exit $_le_status = $_le_meaning) — failing entries: $_le_fails; evidence: $_le_evidence"
+    fi
     # Atomic rename into place
     mv "$staging_dir" "$release_dir"
     echo "INSTALLED: $hash"
@@ -404,6 +632,9 @@ _prune_releases() {
 }
 
 # ── dispatch ──────────────────────────────────────────────────────────
+# Sourced (never executed) by tests/entry-gate.test.js to drive
+# _validate_lib_entries directly — dispatch only when run as the main script.
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
 case "${1:-}" in
   init)     shift; cmd_init "$@" ;;
   deploy)   shift; cmd_deploy "$@" ;;
@@ -412,3 +643,4 @@ case "${1:-}" in
   list)     shift; cmd_list "$@" ;;
   *)        die "usage: crew-release.sh {init|deploy|rollback|current|list} [args...]" ;;
 esac
+fi

package/lib/gitignore.js

@@ -16,8 +16,10 @@
 //   - Never removes, reorders, or reformats existing content.
 //   - Returns { created, appended[], skipped[] }.
 
-const fs = require("fs");
-const path = require("path");
+import fs from "node:fs";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const CREW_GITIGNORE_ENTRIES = [".worktrees/", ".orchestration/user/"];
 
@@ -118,21 +120,37 @@ function describeGitignoreChange(repoPath, entries) {
   };
 }
 
-module.exports = {
+export {
   CREW_GITIGNORE_ENTRIES,
   ensureGitignoreEntries,
   describeGitignoreChange,
 };
 
+const USAGE = "Usage: node lib/gitignore.js --repo <path> [--dry-run]";
+
 // CLI: node lib/gitignore.js --repo <path> [--dry-run]
 // Used by crew-init and by tests. --dry-run prints the diff without writing.
-if (require.main === module) {
+// --help (and the shebang⇔CLI contract): prints usage, exits 0, before
+// required-arg parsing.
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
   const argv = process.argv.slice(2);
+  if (argv.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   const repoIdx = argv.indexOf("--repo");
   const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
   const dryRun = argv.includes("--dry-run");
   if (!repoPath) {
-    console.error("Usage: node lib/gitignore.js --repo <path> [--dry-run]");
+    console.error(USAGE);
     process.exit(2);
   }
   if (dryRun) {

package/lib/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/publish-note-vocabulary.js

@@ -0,0 +1,44 @@
+// Terminal-note vocabulary registry (D7, 2026-09-19). Explicit state, not
+// prose: every `publish: …` note the state machine treats as terminally
+// parked. Readers (scan-publish-unknown in lib/crew-api.js) consult this;
+// writers assert against it (lib/verify-publish.js's terminal() fails loud
+// before emitting a verb that is not in the registry). Add a note here when
+// a new terminal verb is introduced — the scan recognizes it with no other
+// change.
+//
+// This module is the closed-enum pattern's first instance: the audit
+// (room23-design/blanket-call-audit.md §3) lists the other state-carrying
+// string families (the full `publish: <transition>` note shapes, the
+// publish-ledger `outcome` vocabulary, worker-report marker lines) that a
+// later unification pass extends the enum-guard pattern to. The contract
+// for any new family: one registry module, readers consult it, writers
+// assert membership before writing, closed by default and open by edit.
+//
+// ESM, no shebang, no side effects on import (import-safe module — bare
+// `node publish-note-vocabulary.js` exits 0).
+export const TERMINAL_PUBLISH_NOTES = [
+  "publish: ambiguous",
+  "publish: retry-superseded",
+  "publish: retry-refused",
+  "publish: verified",
+  "publish: superseded",
+  // Verification pipeline's terminal content verdict (verify-publish.js).
+  // The task stays parked for human attention; unknown-recovery never
+  // re-enters it. Added 2026-09-19 (Room #23 J1/J3: was mislogged as
+  // unrecognized-publish-note).
+  "publish: verification-failed",
+];
+export const TERMINAL_NOTE_MEANINGS = {
+  "publish: ambiguous": "unknown-recovery terminal: could not prove the drop; parked for human attention",
+  "publish: retry-superseded": "retry protocol terminal: superseded; parked for human attention",
+  "publish: retry-refused": "retry protocol terminal: platform refused the re-issued edit; parked for human attention",
+  "publish: verified": "publish verified and stamped; task re-queued (terminal for the scan)",
+  "publish: superseded": "HEAD moved past the attempt; recovery aborted; parked for human attention",
+  "publish: verification-failed": "verification pipeline's terminal content verdict — parked for human attention",
+};
+export function matchTerminalPublishNote(message) {
+  for (const note of TERMINAL_PUBLISH_NOTES) {
+    if (message.includes(note)) return note; // same substring semantics the scan already uses
+  }
+  return null;
+}

package/lib/publish-npm.sh

@@ -82,7 +82,42 @@ if [ "$PREFLIGHT_CHECK_CODE" -ne 0 ] \
 fi
 # PREFLIGHT-END
 
-# 3. Dry run: markers only, no lock, no deploy, no mutation.
+# PUSH-TARGET-ANCHOR: resolve the push destination before ANY mutation.
+# The destination is the integration target resolved by the lifecycle, not a
+# hardcoded `main` (2026-09-19 REVIEW: the old `git push origin main` was a
+# stale clone of the same hardcoding the integrate fix removed). A detached
+# HEAD pushes as HEAD:<destination>, with the destination resolved explicitly
+# by the lifecycle's push-destination command (2026-09-19 detached-HEAD audit
+# REDO: the old code refused every detached checkout; detached publication
+# is legitimate and must work). Fail here, before the version-bump commit
+# and the registry publish, only when the destination is genuinely
+# unknowable -- never after a side effect you cannot roll back. (The old
+# position of this check -- step 13, after the npm publish -- left a shipped
+# version with a failed phase and a retry loop.)
+# No-origin is checked for BOTH shapes (2026-09-19 critic finding F-A1):
+# step 13 pushes unconditionally, so an attached checkout with no origin
+# would otherwise fail PUBLISH_FAILED=push after the version-bump commit
+# and the registry publish. A version-bump commit with nowhere to record it
+# would ship an npm version with no git provenance, so no-remote fails
+# closed here rather than skipping like the integrate path (F-F6).
+[ -n "${LIFECYCLE:-}" ] || fail "env" "LIFECYCLE is not set -- cannot resolve the push destination before mutation (F-R4)"
+PUSH_TARGET="$(CREW_HOME="${CREW_HOME:-}" CREW_REPO="$REPO_PATH" bash "$LIFECYCLE" integration-target 2>&1)" \
+  || fail "integration-target" "$PUSH_TARGET"
+if ! git -C "$REPO_PATH" remote get-url origin >/dev/null 2>&1; then
+  fail "env" "no origin remote configured: the version-bump commit could not be pushed anywhere -- no version-bump commit was created and nothing was published"
+fi
+PUSH_REFSPEC="$PUSH_TARGET"
+if [ "$PUSH_TARGET" = "HEAD" ]; then
+  PUSH_DEST="$(CREW_HOME="${CREW_HOME:-}" CREW_REPO="$REPO_PATH" bash "$LIFECYCLE" push-destination 2>&1)" \
+    || fail "env" "$PUSH_DEST"
+  PUSH_REFSPEC="HEAD:$PUSH_DEST"
+fi
+# PUSH-TARGET-END
+
+# 3. Dry run: markers only, no lock, no deploy, no mutation. The push
+# preflight above already ran, so even a dry run fails closed on a
+# genuinely unknowable push destination (see case 7 in
+# lib/test-publish-preflight.sh -- F-R9).
 if [ "${DRY_RUN:-0}" = "1" ]; then
   echo "PUBLISH_DRY_RUN=1"
   exit 0
@@ -281,15 +316,9 @@ LOCK_OUT2="$(CREW_HOME="${CREW_HOME:-}" CREW_REPO="$REPO_PATH" bash "${LIFECYCLE
   || fail "lock-refresh" "$LOCK_OUT2"
 
 # 13. Push the version-bump commit (idempotent: no-op if already pushed).
-# The destination is the integration target resolved by the lifecycle, not a
-# hardcoded `main` (2026-09-19 REVIEW: the old `git push origin main` was a
-# stale clone of the same hardcoding the integrate fix removed).
-PUSH_TARGET="$(CREW_HOME="${CREW_HOME:-}" CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" integration-target 2>&1)" \
-  || fail "integration-target" "$PUSH_TARGET"
-if [ "$PUSH_TARGET" = "HEAD" ]; then
-  fail "push" "detached HEAD: publish-npm cannot push a version-bump commit from a detached checkout"
-fi
-PUSH_OUT="$(git -C "$REPO_PATH" push origin "$PUSH_TARGET" 2>&1)" \
+# PUSH_REFSPEC was resolved in the preflight above -- a branch name, or
+# HEAD:<destination> on a detached checkout (never a bare HEAD).
+PUSH_OUT="$(git -C "$REPO_PATH" push origin "$PUSH_REFSPEC" 2>&1)" \
   || fail "push" "$PUSH_OUT"
 echo "PUBLISH_PUSHED=1"
 

package/lib/read-ooda-verdict.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // read-ooda-verdict.js — deterministic cross-checker for the OODA terminal
 // verdict (2026-09-15).
 //
@@ -50,10 +51,9 @@
 // Determinism: no wall-clock reads, no randomness. The script never judges
 // report content — the agent states the reason; the machine enforces its
 // presence and its agreement with the prose verdict.
-"use strict";
 
-const { readFileSync, existsSync } = require("node:fs");
-const { join, resolve } = require("node:path");
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 function fail(code, error) {
   process.stdout.write(JSON.stringify({ ok: false, code: code, error: error }) + "\n");
@@ -72,6 +72,14 @@ function parseArgs(argv) {
 }
 
 function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log(
+      "usage: node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>\n" +
+      "cross-checks the prose VERDICT: line against <phase-dir>/verdict.json"
+    );
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.dir) fail("bad_input", "missing --dir <phase-dir>");
   if (!args.expect) fail("bad_input", "missing --expect <PASS|FAIL>");

package/lib/readback-disk.js

@@ -53,6 +53,15 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+// --help: before required-arg parsing (shebang⇔CLI contract).
+if (process.argv.slice(2).includes("--help")) {
+  console.log(
+    "usage: node readback-disk.js --repo-path <path> --commit <sha> --base <sha> --task-id <uuid> --slug <artifact-slug> [--spaces-root <dir>]\n" +
+    "the deterministic disk read-back SENSOR: emits the machine-readable findings block (FILE:/ADDED:/REMOVED:/END_FILE)"
+  );
+  process.exit(0);
+}
+
 const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 
 function arg(name) {

package/lib/render-html.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // render-html.js — render an HTML evidence layout to PNG via headless Chromium.
 //
 // The reef-qa pattern (2026-09-14): the agent composes evidence as HTML —
@@ -26,11 +27,13 @@
 // The rendered composition is evidence: log it with append-ooda-step.js
 // (--action compose) and READ it — a composition you did not read is not
 // evidence.
-"use strict";
 
-const { existsSync, readFileSync } = require("node:fs");
-const { resolve, dirname } = require("node:path");
-const { pathToFileURL } = require("node:url");
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const cjsRequire = createRequire(import.meta.url);
 
 const DEFAULT_WIDTH = 1200;
 
@@ -54,16 +57,17 @@ function parseArgs(argv) {
 function loadPlaywright() {
   // playwright-core is a declared dependency (package.json), so a normal
   // npm install resolves it from the package's own node_modules.
+  // createRequire keeps the synchronous resolution the CLI relies on.
   try {
-    return require("playwright-core");
+    return cjsRequire("playwright-core");
   } catch (e) { /* fall through */ }
   const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
   if (envDir) {
     try {
-      return require(envDir + "/playwright-core");
+      return cjsRequire(envDir + "/playwright-core");
     } catch (e) { /* fall through */ }
     try {
-      return require(envDir);
+      return cjsRequire(envDir);
     } catch (e) { /* fall through */ }
   }
   fail(3, {
@@ -86,6 +90,12 @@ function findChromium() {
 }
 
 async function main() {
+  // --help: before required-arg parsing (shebang⇔CLI contract).
+  if (process.argv.slice(2).includes("--help")) {
+    console.log("usage: node render-html.js --in <page.html> --out <shot.png> [--width <px>]\n" +
+      "renders a local HTML evidence layout to PNG via headless Chromium");
+    process.exit(0);
+  }
   const args = parseArgs(process.argv.slice(2));
   if (!args.in) fail(2, { ok: false, error: "missing --in <page.html>" });
   if (!args.out) fail(2, { ok: false, error: "missing --out <shot.png>" });

package/lib/repo-orchestration.js

@@ -14,8 +14,10 @@
 // Seeding uses no-clobber semantics: existing project customizations are
 // never overwritten. Idempotent: re-running is a no-op.
 
-const fs = require("fs");
-const path = require("path");
+import fs from "node:fs";
+import path from "node:path";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
@@ -106,19 +108,33 @@ function scaffoldRepoOrchestration(repoPath, crewRepoPath) {
   return result;
 }
 
-module.exports = {
+export {
   scaffoldRepoOrchestration,
 };
 
+const USAGE = "Usage: node lib/repo-orchestration.js --repo <path> --crew-repo <path>";
+
+const isMainModule = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
 // CLI: node lib/repo-orchestration.js --repo <path> --crew-repo <path>
-if (require.main === module) {
+if (isMainModule) {
   const argv = process.argv.slice(2);
+  if (argv.includes("--help")) {
+    console.log(USAGE);
+    process.exit(0);
+  }
   const repoIdx = argv.indexOf("--repo");
   const crewRepoIdx = argv.indexOf("--crew-repo");
   const repoPath = repoIdx >= 0 ? argv[repoIdx + 1] : null;
   const crewRepoPath = crewRepoIdx >= 0 ? argv[crewRepoIdx + 1] : null;
   if (!repoPath || !crewRepoPath) {
-    console.error("Usage: node lib/repo-orchestration.js --repo <path> --crew-repo <path>");
+    console.error(USAGE);
     process.exit(2);
   }
   const r = scaffoldRepoOrchestration(repoPath, crewRepoPath);