bigpowers 2.90.2 → 2.91.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.91.1](https://github.com/danielvm-git/bigpowers/compare/v2.91.0...v2.91.1) (2026-11-03)
+
+
+### Bug Fixes
+
+* **hooks:** give each guard fixture row its own branch context ([#196](https://github.com/danielvm-git/bigpowers/issues/196)) ([5d379df](https://github.com/danielvm-git/bigpowers/commit/5d379df5dc1d9f139636a3f361ee35a1a1ceedd0))
+* **hooks:** judge git argv instead of command substrings in guard-git ([#194](https://github.com/danielvm-git/bigpowers/issues/194)) ([9532372](https://github.com/danielvm-git/bigpowers/commit/95323721c0257964b572d9e0a37834b34955944f)), closes [#184](https://github.com/danielvm-git/bigpowers/issues/184)
+
+# [2.91.0](https://github.com/danielvm-git/bigpowers/compare/v2.90.2...v2.91.0) (2026-11-03)
+
+
+### Features
+
+* **hooks:** enforce mechanical gates for red-commit, artifacts, and adversarial mutation (e86) ([#191](https://github.com/danielvm-git/bigpowers/issues/191)) ([7a1b090](https://github.com/danielvm-git/bigpowers/commit/7a1b0907aa20962ee71e825c4996aa80c213be3f))
+
 ## [2.90.2](https://github.com/danielvm-git/bigpowers/compare/v2.90.1...v2.90.2) (2026-11-03)
 
 

package/extensions/omp-hooks.ts

@@ -18,15 +18,152 @@ import { fileURLToPath } from "node:url";
 // only truly foreign entries (e.g. a stray node_modules symlink) need exclusion.
 const EXCLUDED_DIRS = new Set([".git", "node_modules"]);
 
-const DANGEROUS_PATTERNS = [
-  /git\s+reset\s+--hard/,
-  /git\s+clean\s+-f/,
-  /git\s+branch\s+-D/,
-  /git\s+checkout\s+\./,
-  /git\s+restore\s+\./,
-  /push\s+--force/,
-  /push\s+-f(?:\s|$)/,
-];
+// ---------------------------------------------------------------------------
+// Git argv normalization (BUG-2026-11-03-guard-git-flag-normalize, #184).
+//
+// Literal substring patterns cannot see a global flag in front of the
+// subcommand (`git -C repo reset --hard`), a flag between the subcommand and the
+// destructive option (`git reset -q --hard`), or an alternative spelling of the
+// same act (`git checkout -- .`, `git branch --delete --force`). Tokenize the
+// command, drop the global options, then judge (subcommand, arguments).
+//
+// scripts/lib/git-argv.py is the same rule table in Python for the shell hooks;
+// scripts/test-guard-git-normalize.sh fails if the two disagree on any fixture.
+// ---------------------------------------------------------------------------
+
+/** Quote-aware split; a quoting error degrades to whitespace splitting, never to eval. */
+export function tokenizeArgs(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let hasToken = false;
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch as '"' | "'";
+      hasToken = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (hasToken) {
+        tokens.push(current);
+        current = "";
+        hasToken = false;
+      }
+      continue;
+    }
+    current += ch;
+    hasToken = true;
+  }
+  if (hasToken) tokens.push(current);
+  return tokens;
+}
+
+// Global options that consume the next token as their value.
+const GIT_VALUE_FLAGS = new Set([
+  "-C", "-c", "--exec-path", "--git-dir", "--work-tree", "--namespace",
+  "--super-prefix", "--config-env",
+]);
+
+// Global options that stand alone.
+const GIT_BARE_FLAGS = new Set([
+  "-p", "--paginate", "--no-pager", "--bare", "--no-replace-objects",
+  "--literal-pathspecs", "--glob-pathspecs", "--icase-pathspecs",
+  "--no-optional-locks", "--version", "--help",
+]);
+
+const SEPARATORS = new Set([";", "&&", "||", "|", "&", "(", ")", "\n"]);
+
+function shortFlagHas(args: string[], letter: string): boolean {
+  return args.some((a) => a.startsWith("-") && !a.startsWith("--") && a.slice(1).includes(letter));
+}
+
+/** Block reason for one normalized git invocation, or null. Mirror git-argv.py. */
+export function classifyGitInvocation(sub: string, args: string[]): string | null {
+  if (sub === "reset" && args.includes("--hard")) return "git reset --hard discards uncommitted work";
+  if (sub === "clean" && (shortFlagHas(args, "f") || args.includes("--force"))) {
+    return "git clean -f deletes untracked files";
+  }
+  if (sub === "branch") {
+    const forced =
+      args.includes("-D") ||
+      (args.includes("--delete") && (args.includes("--force") || shortFlagHas(args, "f")));
+    if (forced) return "git branch -D deletes an unmerged branch";
+  }
+  if (sub === "checkout") {
+    if (args.includes("-f") || args.includes("--force")) return "git checkout -f discards local changes";
+    if (args.includes(".")) return "git checkout . discards local changes";
+  }
+  if (sub === "restore" && (args.includes("--worktree") || args.includes("."))) {
+    return "git restore discards local changes";
+  }
+  if (sub === "push") {
+    const leased = args.some((a) => a === "--force-with-lease" || a.startsWith("--force-with-lease="));
+    const forced =
+      args.includes("-f") ||
+      args.includes("--force") ||
+      args.some((a) => a.startsWith("+") && !a.startsWith("++"));
+    if (forced && !leased) return "force push rewrites remote history";
+  }
+  return null;
+}
+
+/** Every (subcommand, args) pair in a command, with global options stripped. */
+export function gitInvocations(tokens: string[]): Array<{ sub: string; args: string[] }> {
+  const found: Array<{ sub: string; args: string[] }> = [];
+  let i = 0;
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (token.split("/").pop() !== "git") {
+      i += 1;
+      continue;
+    }
+    let j = i + 1;
+    while (j < tokens.length) {
+      const opt = tokens[j];
+      if (SEPARATORS.has(opt)) break;
+      const name = opt.split("=")[0];
+      if (GIT_VALUE_FLAGS.has(name)) {
+        j += opt.includes("=") ? 1 : 2;
+        continue;
+      }
+      if (GIT_BARE_FLAGS.has(name) || (opt.startsWith("-") && !opt.startsWith("--") && opt.length > 1)) {
+        j += 1;
+        continue;
+      }
+      break;
+    }
+    if (j >= tokens.length || SEPARATORS.has(tokens[j])) {
+      i = j + 1;
+      continue;
+    }
+    const sub = tokens[j];
+    const args: string[] = [];
+    let k = j + 1;
+    while (k < tokens.length && !SEPARATORS.has(tokens[k])) {
+      args.push(tokens[k]);
+      k += 1;
+    }
+    found.push({ sub, args });
+    i = k;
+  }
+  return found;
+}
+
+/** The normalized verdict for a whole shell command: a reason to block, or null. */
+export function dangerousGitCommand(command: string): string | null {
+  for (const { sub, args } of gitInvocations(tokenizeArgs(command))) {
+    const reason = classifyGitInvocation(sub, args);
+    if (reason) return reason;
+  }
+  return null;
+}
+
 
 // Conventional Commits specifies `type(scope)!:`, but many repositories write
 // `type!(scope):`. Accept both; the leading type is what matters.
@@ -224,6 +361,46 @@ function currentBranch(cwd: string): string {
   }
 }
 
+/** Everything the tool_call handler decides, as a pure function (testable). */
+export function evaluateBashCall(
+  command: string,
+  opts: {
+    landMode: boolean;
+    hasRepo: boolean;
+    branchFor: (upTo: number) => string | undefined;
+  },
+): string | null {
+  const gitReason = dangerousGitCommand(command);
+  if (gitReason) return `BLOCKED: ${gitReason}. Use a safer approach or ask the user.`;
+
+  if (!opts.hasRepo) return null;
+
+  const pushBranch = opts.branchFor(command.length) ?? "unknown";
+  if (/git\s+push/.test(command) && !opts.landMode && protectedPushTarget(command, pushBranch)) {
+    return "BLOCKED: Direct push to protected branch. Use kickoff-branch + release-branch.";
+  }
+
+  if (/git\s+commit/.test(command)) {
+    const commitBranches = [...command.matchAll(/\bgit\s+commit\b/g)].map(
+      (m) => opts.branchFor(m.index ?? 0) ?? "unknown",
+    );
+    const hit = commitBranches.find((b) => (PROTECTED_BRANCHES as readonly string[]).includes(b));
+    if (hit) {
+      return `BLOCKED: Direct commits to '${hit}' are forbidden. Use a feature branch.`;
+    }
+    const msg = extractCommitMessage(command);
+    if (msg) {
+      if (!CONVENTIONAL_RE.test(msg)) {
+        return `BLOCKED: Commit subject '${msg.split("\n")[0]}' must follow Conventional Commits: <type>(<scope>): <subject>.`;
+      }
+      if (msg.split("\n")[0].length > 72) {
+        return "BLOCKED: Commit subject line must be \u226472 characters.";
+      }
+    }
+  }
+  return null;
+}
+
 function protectedPushTarget(command: string, branch: string): boolean {
   if (PROTECTED_BRANCH_RE.test(command)) return true;
   const trimmed = command.trim();
@@ -414,55 +591,17 @@ export default function bigpowers(pi: ExtensionAPI) {
     const { command } = event.input as { command?: string };
     if (!command) return;
 
-    for (const pat of DANGEROUS_PATTERNS) {
-      if (pat.test(command)) {
-        return {
-          block: true,
-          reason: `BLOCKED: '${command}' matches dangerous pattern '${pat}'.`,
-        };
-      }
-    }
-
     const sessionRoot = process.cwd();
-    if (!inGitRepo(sessionRoot)) return;
-    const pushBranch = currentBranch(commandGitCwd(command, command.length, sessionRoot));
-
-    if (/git\s+push/.test(command) && protectedPushTarget(command, pushBranch)) {
-      return {
-        block: true,
-        reason:
-          "BLOCKED: Direct push to protected branch. Use kickoff-branch + release-branch.",
-      };
-    }
-
-    if (/git\s+commit/.test(command)) {
-      const commitBranches = [...command.matchAll(/\bgit\s+commit\b/g)].map((m) =>
-        currentBranch(commandGitCwd(command, m.index ?? 0, sessionRoot)),
-      );
-      const hit = commitBranches.find((b) =>
-        (PROTECTED_BRANCHES as readonly string[]).includes(b),
-      );
-      if (hit) {
-        return {
-          block: true,
-          reason: `BLOCKED: Direct commits to '${hit}' are forbidden. Use a feature branch.`,
-        };
-      }
-      const msg = extractCommitMessage(command);
-      if (msg) {
-        if (!CONVENTIONAL_RE.test(msg)) {
-          return {
-            block: true,
-            reason: `BLOCKED: Commit subject '${msg.split("\n")[0]}' must follow Conventional Commits: <type>(<scope>): <subject>.`,
-          };
-        }
-        if (msg.split("\n")[0].length > 72) {
-          return {
-            block: true,
-            reason: "BLOCKED: Commit subject line must be ≤72 characters.",
-          };
-        }
-      }
-    }
+    const verdict = evaluateBashCall(command, {
+      landMode: process.env.GIT_BIGPOWERS_LAND === "1",
+      // `undefined` means "there is no repo here"; the guard then only judges
+      // the argv rules, which need no branch.
+      branchFor: (upTo: number) =>
+        inGitRepo(sessionRoot)
+          ? currentBranch(commandGitCwd(command, upTo, sessionRoot))
+          : undefined,
+      hasRepo: inGitRepo(sessionRoot),
+    });
+    if (verdict) return { block: true, reason: verdict };
   });
 }

package/hooks/pre/bash.sh

@@ -11,7 +11,8 @@ INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty' 2>/dev/null || true)
 [ -z "$COMMAND" ] && exit 0
 
-DANGEROUS_PATTERNS=(
+# Last-resort literals, used only when the normalizer is unreachable.
+LEGACY_DANGEROUS=(
   "git reset --hard"
   "git clean -f"
   "git branch -D"
@@ -19,18 +20,64 @@ DANGEROUS_PATTERNS=(
   "push -f"
 )
 PROTECTED_BRANCHES=("main" "master")
+COMMIT_MSG_RE='-m[[:space:]]+"([^"]+)"'
 CONVENTIONAL_RE='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?:[[:space:]].+'
 
-for p in "${DANGEROUS_PATTERNS[@]}"; do
-  if echo "$COMMAND" | grep -qE "$p"; then
-    printf '{"decision":"block","reason":"BLOCKED: dangerous pattern %q"}\n' "$p"
-    exit 0
+# --- Normalized git argv (BUG-2026-11-03-guard-git-flag-normalize, #184) ------
+# Literal substring matching cannot see a global flag in front of the subcommand
+# or a flag between the subcommand and the destructive option: the destructive
+# tokens are all still there, only their position changed. The rules live in
+# scripts/lib/git-argv.py and are mirrored in extensions/omp-hooks.ts;
+# scripts/test-guard-git-normalize.sh fails if the two disagree on any fixture.
+SELF_PATH="${BASH_SOURCE[0]}"
+# Only pay for realpath when the hook actually is a symlink (installed copies).
+# This hook runs on every tool call, so a spawn per invocation is real latency.
+if [ -L "$SELF_PATH" ] && command -v python3 >/dev/null 2>&1; then
+  SELF_PATH="$(python3 -c 'import os,sys;print(os.path.realpath(sys.argv[1]))' "$SELF_PATH" 2>/dev/null || echo "$SELF_PATH")"
+fi
+GUARD_ROOT="$(cd "$(dirname "$SELF_PATH")/.." 2>/dev/null && pwd -P || true)"
+GIT_ARGV="$GUARD_ROOT/scripts/lib/git-argv.py"
+
+# classify_git_argv <command>: echoes "block: <reason>" or nothing.
+# Fast path: a command with no "git" token cannot contain a git invocation, so
+# the helper (a python start) is skipped. Falls back to the legacy literal
+# patterns when the helper is unreachable (hook symlinked outside the package).
+classify_git_argv() {
+  local cmd="$1" out=""
+  case "$cmd" in
+    *git*) ;;
+    *) return 0 ;;
+  esac
+  if command -v python3 >/dev/null 2>&1 && [ -f "$GIT_ARGV" ]; then
+    out="$(python3 "$GIT_ARGV" --command "$cmd" 2>/dev/null || true)"
+    case "$out" in
+      block:*) printf '%s' "$out"; return 0 ;;
+      *) return 0 ;;
+    esac
   fi
-done
+  return 0
+}
+
+GIT_VERDICT="$(classify_git_argv "$COMMAND")"
+if [ -n "$GIT_VERDICT" ]; then
+  printf '{"decision":"block","reason":"BLOCKED: %s"}\n' "${GIT_VERDICT#block: }"
+  exit 0
+fi
+if [ ! -f "$GIT_ARGV" ]; then
+  for p in "${LEGACY_DANGEROUS[@]}"; do
+    if echo "$COMMAND" | grep -qE "$p"; then
+      printf '{"decision":"block","reason":"BLOCKED: dangerous pattern %q"}\n' "$p"
+      exit 0
+    fi
+  done
+fi
 
 if [[ "$COMMAND" =~ git[[:space:]]+commit ]]; then
   MSG=""
-  if [[ "$COMMAND" =~ -m[[:space:]]+"([^"]+)" ]]; then MSG="${BASH_REMATCH[1]}"; fi
+  # Parentheses inside [[ =~ ]] must come from a variable, not the literal
+  # pattern: bash parses `([^"]+)` as a syntax error (pre-existing since #118,
+  # so this fallback hook never ran; BUG-2026-11-03-guard-git-flag-normalize).
+  if [[ "$COMMAND" =~ $COMMIT_MSG_RE ]]; then MSG="${BASH_REMATCH[1]}"; fi
   if [ -n "$MSG" ] && [[ ! "$MSG" =~ $CONVENTIONAL_RE ]]; then
     echo '{"decision":"block","reason":"BLOCKED: Conventional Commits required"}'
     exit 0

package/hooks/pre-tool-use.sh

@@ -11,16 +11,13 @@ set -euo pipefail
 
 # Configuration
 PROTECTED_BRANCHES=("main" "master")
-DANGEROUS_PATTERNS=(
+# Last-resort literals, used only when the normalizer is unreachable.
+LEGACY_DANGEROUS=(
   "git reset --hard"
-  "git clean -fd"
   "git clean -f"
   "git branch -D"
-  "git checkout \\."
-  "git restore \\."
   "push --force"
   "push -f"
-  "reset --hard"
 )
 CONVENTIONAL_COMMITS_REGEX='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:[[:space:]].+'
 LAND_MODE="${GIT_BIGPOWERS_LAND:-}"
@@ -29,6 +26,41 @@ LAND_MODE="${GIT_BIGPOWERS_LAND:-}"
 # GIT_GUARDRAILS_MODE: claude (default) | cursor | gemini
 MODE="${GIT_GUARDRAILS_MODE:-claude}"
 
+# --- Normalized git argv (BUG-2026-11-03-guard-git-flag-normalize, #184) ------
+# Literal substring matching cannot see a global flag in front of the subcommand
+# or a flag between the subcommand and the destructive option: the destructive
+# tokens are all still there, only their position changed. The rules live in
+# scripts/lib/git-argv.py and are mirrored in extensions/omp-hooks.ts;
+# scripts/test-guard-git-normalize.sh fails if the two disagree on any fixture.
+SELF_PATH="${BASH_SOURCE[0]}"
+# Only pay for realpath when the hook actually is a symlink (installed copies).
+# This hook runs on every tool call, so a spawn per invocation is real latency.
+if [ -L "$SELF_PATH" ] && command -v python3 >/dev/null 2>&1; then
+  SELF_PATH="$(python3 -c 'import os,sys;print(os.path.realpath(sys.argv[1]))' "$SELF_PATH" 2>/dev/null || echo "$SELF_PATH")"
+fi
+GUARD_ROOT="$(cd "$(dirname "$SELF_PATH")/.." 2>/dev/null && pwd -P || true)"
+GIT_ARGV="$GUARD_ROOT/scripts/lib/git-argv.py"
+
+# classify_git_argv <command>: echoes "block: <reason>" or nothing.
+# Fast path: a command with no "git" token cannot contain a git invocation, so
+# the helper (a python start) is skipped. Falls back to the legacy literal
+# patterns when the helper is unreachable (hook symlinked outside the package).
+classify_git_argv() {
+  local cmd="$1" out=""
+  case "$cmd" in
+    *git*) ;;
+    *) return 0 ;;
+  esac
+  if command -v python3 >/dev/null 2>&1 && [ -f "$GIT_ARGV" ]; then
+    out="$(python3 "$GIT_ARGV" --command "$cmd" 2>/dev/null || true)"
+    case "$out" in
+      block:*) printf '%s' "$out"; return 0 ;;
+      *) return 0 ;;
+    esac
+  fi
+  return 0
+}
+
 deny() {
   local reason="$1"
   if [ "$MODE" = "gemini" ]; then
@@ -42,20 +74,48 @@ deny() {
 # Read input from stdin
 INPUT=$(cat)
 
-# Extract command using jq (standard in bigpowers)
+# Extract command and file path using jq (standard in bigpowers)
 COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .tool_input.file_path // .path // .tool_input.path // .target_file // .tool_input.target_file // empty')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool // .name // .tool_name // empty')
+
+# 0. Check file editing rules
+if [ -n "$FILE_PATH" ]; then
+  # e86s01: Generated paths are blocked at edit time
+  if [[ "$FILE_PATH" =~ ^\.cursor/rules/ ]] || [[ "$FILE_PATH" =~ ^\.gemini/extensions/ ]] || [[ "$FILE_PATH" =~ ^\.windsurf/ ]]; then
+    deny "BLOCKED: Generated file '$FILE_PATH' cannot be edited directly. Edit the source SKILL.md instead and run bash scripts/sync-skills.sh."
+  fi
+
+  # e86s02: Tests are locked during fix_bug flow after RED commit
+  if [[ "$FILE_PATH" =~ (^|/)test/ ]] || [[ "$FILE_PATH" =~ (^|/)tests/ ]] || [[ "$FILE_PATH" =~ \.test\.[^/]+$ ]] || [[ "$FILE_PATH" =~ _test\.[^/]+$ ]] || [[ "$FILE_PATH" =~ (^|/)test_[^/]+$ ]]; then
+    if [ -f specs/state.yaml ] && grep -qE "active_flow:[[:space:]]*fix_bug" specs/state.yaml 2>/dev/null; then
+      if git rev-parse --git-dir >/dev/null 2>&1; then
+        recent_log=$(git log -n 5 --format=%s 2>/dev/null || true)
+        if echo "$recent_log" | grep -qE '^test(\(.+\))?:'; then
+          deny "BLOCKED: Test files ($FILE_PATH) are locked during fix_bug after the RED commit. Write the fix in production code (src/), not in tests."
+        fi
+      fi
+    fi
+  fi
+fi
 
 if [ -z "$COMMAND" ]; then
   [ "$MODE" = "gemini" ] && echo '{"decision":"allow"}'
   exit 0
 fi
 
-# 1. Check for dangerous patterns (git push is NOT blanket-blocked)
-for p in "${DANGEROUS_PATTERNS[@]}"; do
-  if echo "$COMMAND" | grep -qE "$p"; then
-    deny "BLOCKED: '$COMMAND' matches dangerous pattern '$p'. Use a safer approach or ask the user."
-  fi
-done
+# 1. Normalized git argv (git push is NOT blanket-blocked)
+GIT_VERDICT="$(classify_git_argv "$COMMAND")"
+if [ -n "$GIT_VERDICT" ]; then
+  deny "BLOCKED: ${GIT_VERDICT#block: }. Use a safer approach or ask the user."
+fi
+if [ ! -f "$GIT_ARGV" ]; then
+  for p in "${LEGACY_DANGEROUS[@]}"; do
+    if echo "$COMMAND" | grep -qE "$p"; then
+      deny "BLOCKED: '$COMMAND' matches dangerous pattern '$p'. Use a safer approach or ask the user."
+    fi
+  done
+fi
 
 # 2. Check for git commit / git push
 if [[ "$COMMAND" =~ git[[:space:]]+commit ]] || [[ "$COMMAND" =~ git[[:space:]]+push ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.90.2",
+  "version": "2.91.1",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {
@@ -68,6 +68,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@ctxo/lang-typescript": "^0.11.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",

package/scripts/convert-legado.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # convert-legado.sh — RELEASE-PLAN.md + SCOPE.md → YAML layout (one-time migration helper)
+# bp-manual-utility: legacy MD spec converter (pre-e44 migration)
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 SPECS="$REPO_ROOT/specs"

package/scripts/lib/assert-epic-gate.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# story: e86 / GH #182
+# Mechanical audit-code pass gate before commit / release.
+set -euo pipefail
+
+STAGE="${1:-commit}"
+
+AUDIT_PASSED=false
+
+# Check specs/AUDIT_LATEST.md
+if [[ -f specs/AUDIT_LATEST.md ]]; then
+  if grep -qiE "VERDICT:[[:space:]]*PASS|RESULT:[[:space:]]*PASS" specs/AUDIT_LATEST.md; then
+    AUDIT_PASSED=true
+  fi
+fi
+
+# Check specs/execution-status.yaml
+if [[ "$AUDIT_PASSED" == "false" ]] && [[ -f specs/execution-status.yaml ]]; then
+  if grep -qE "audit_passed:[[:space:]]*true" specs/execution-status.yaml 2>/dev/null; then
+    AUDIT_PASSED=true
+  fi
+fi
+
+if [[ "$AUDIT_PASSED" == "false" ]]; then
+  echo "ERROR [$STAGE]: audit-code check is missing or did not pass (Issue #182)." >&2
+  echo "Remediation: Run audit-code and ensure all checks pass before advancing to $STAGE." >&2
+  echo "If audit fails, loop back to develop-tdd to address findings." >&2
+  exit 1
+fi
+
+echo "PASS [$STAGE]: audit-code verified."
+exit 0

package/scripts/lib/assert-planning-artifacts.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# story: e86 / GH #183
+# Mechanical artifact existence assertion for run-planning workflow steps.
+set -euo pipefail
+
+STEP="${1:-}"
+
+if [[ -z "$STEP" ]]; then
+  echo "Usage: bash scripts/lib/assert-planning-artifacts.sh <step_name>" >&2
+  exit 1
+fi
+
+case "$STEP" in
+  survey-context)
+    if [[ ! -f specs/tech-architecture/tech-stack.md ]] && [[ ! -f specs/state.yaml ]]; then
+      echo "ERROR [survey-context]: Neither specs/tech-architecture/tech-stack.md nor specs/state.yaml exists." >&2
+      exit 1
+    fi
+    ;;
+
+  scope-work)
+    if [[ ! -f specs/product/SCOPE_LATEST.yaml ]] || [[ ! -s specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [scope-work]: specs/product/SCOPE_LATEST.yaml is missing or empty." >&2
+      exit 1
+    fi
+    ;;
+
+  research-first)
+    # Research can record in specs/product/PRIOR_ART.md or directly in specs/
+    if [[ ! -f specs/product/PRIOR_ART.md ]] && [[ ! -f specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [research-first]: Neither specs/product/PRIOR_ART.md nor specs/product/SCOPE_LATEST.yaml found." >&2
+      exit 1
+    fi
+    ;;
+
+  elaborate-spec)
+    if [[ ! -f specs/planning-context.yaml ]] && [[ ! -f specs/product/SCOPE_LATEST.yaml ]]; then
+      echo "ERROR [elaborate-spec]: specs/planning-context.yaml is missing." >&2
+      exit 1
+    fi
+    ;;
+
+  plan-release)
+    if [[ ! -f specs/release-plan.yaml ]] || [[ ! -s specs/release-plan.yaml ]]; then
+      echo "ERROR [plan-release]: specs/release-plan.yaml is missing or empty." >&2
+      exit 1
+    fi
+    ;;
+
+  slice-tasks)
+    # Assert at least one task file exists in specs/epics/
+    if ! find specs/epics -name "*-tasks.yaml" 2>/dev/null | grep -q .; then
+      echo "ERROR [slice-tasks]: No tasks files (*-tasks.yaml) found in specs/epics/." >&2
+      exit 1
+    fi
+    ;;
+
+  *)
+    echo "WARNING: Unknown step '$STEP' — skipping artifact assertion" >&2
+    exit 0
+    ;;
+esac
+
+echo "PASS: Planning artifacts asserted for step '$STEP'."
+exit 0