forgedock 1.0.7 → 1.0.8

package/bin/forgedock.mjs

@@ -13,6 +13,7 @@ import {
 } from "path";
 import {
   mkdir,
+  rm,
   symlink,
   copyFile,
   readlink,
@@ -3653,14 +3654,51 @@ async function docsInit() {
   console.log(`  Files:   ${templateFiles.length} seed files`);
   console.log("");
 
-  await mkdir(targetDir, { recursive: true });
+  // Use resolvedTarget (canonical path) rather than the raw targetDir string.  The
+  // containment check above already resolved symlinks and validated the path; using the
+  // canonical form here closes the TOCTOU window to the narrowest possible interval
+  // and ensures mkdir does not follow a symlink that was NOT present when we checked.
+  //
+  // TOCTOU residual: a narrow window remains between the realpath check and this mkdir
+  // on POSIX systems — a symlink planted at an intermediate path component during that
+  // window could cause mkdir to create directories outside the project boundary.
+  // Full elimination requires O_NOFOLLOW semantics (kernel-level, not available from
+  // Node.js user-space).  We mitigate with a post-create re-validation below (SEC-5).
+  await mkdir(resolvedTarget, { recursive: true });
+
+  // SEC-5: Post-create re-validation — detect symlink planted during the TOCTOU window.
+  // After mkdir succeeds, call realpath() on the now-existing directory to get its
+  // canonical on-disk location.  If that location lies outside the project root a
+  // symlink was planted between the containment check and the mkdir call.  In that case
+  // we remove the directory tree that was created (wherever it landed) and abort.
+  try {
+    const postMkdirReal = await realpath(resolvedTarget);
+    if (postMkdirReal !== realCwd && !postMkdirReal.startsWith(realCwd + sep)) {
+      await rm(postMkdirReal, { recursive: true, force: true }).catch(() => {});
+      console.log(
+        `${RED}Error: devdocs directory escaped the project boundary after creation (TOCTOU).${RESET}`,
+      );
+      console.log(`  Created at: ${postMkdirReal}`);
+      console.log(`  Project:    ${realCwd}`);
+      console.log(
+        `  A symlink was likely planted at an intermediate path component between the`,
+      );
+      console.log(
+        `  containment check and the mkdir call.  The created directory has been removed.`,
+      );
+      process.exit(1);
+    }
+  } catch {
+    // realpath() failure after a successful mkdir is unexpected; proceed — the directory
+    // was created by us and the normal containment check already passed.
+  }
 
   let copied = 0;
   let skipped = 0;
 
   for (const srcFile of templateFiles) {
     const rel = relative(templatesDir, srcFile);
-    const destFile = join(targetDir, rel);
+    const destFile = join(resolvedTarget, rel);
     const destDir = dirname(destFile);
 
     await mkdir(destDir, { recursive: true });

package/commands/autopilot.md

@@ -13,6 +13,12 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 - `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
 - `{BILLING_ENABLED}` ← `billing.enabled` (optional, default `false`) — set to `true` to enable Stripe data collection in the Analytics Snapshot agent
 
+Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
+
+```bash
+BILLING_ENABLED=$(yq '.billing.enabled // false' "$(git rev-parse --show-toplevel)/forge.yaml" 2>/dev/null || echo 'false')
+```
+
 You are an autonomous improvement engine for this project. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
 
 **This is designed to run repeatedly.** Each cycle builds on the last — issues created in cycle N get fixed in cycle N+1. The platform compounds improvements over time.

package/commands/deploy-info.md

@@ -156,9 +156,9 @@ done
 git diff --stat origin/$TARGET..origin/$SOURCE
 
 # Read layout paths from forge.yaml, fall back to AlterLab defaults
-LAYOUT_API=$(yq '.review.layout.api // "services/api"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "services/api")
-LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "services/worker")
-LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "web/src/app")
+LAYOUT_API=$(yq '.review.layout.api // "services/api"' forge.yaml 2>/dev/null || echo "services/api")
+LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' forge.yaml 2>/dev/null || echo "services/worker")
+LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' forge.yaml 2>/dev/null || echo "web/src/app")
 # Derive web root from pages root (strip trailing /src/app or similar suffix if present)
 LAYOUT_WEB=$(echo "$LAYOUT_PAGES" | sed 's|/src/app$||; s|/src$||')
 
@@ -180,7 +180,7 @@ done | sort
 
 ```bash
 # Read migrations path from forge.yaml, fall back to infra/migrations
-LAYOUT_MIGRATIONS=$(yq '.review.layout.migrations // "infra/migrations"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "infra/migrations")
+LAYOUT_MIGRATIONS=$(yq '.review.layout.migrations // "infra/migrations"' forge.yaml 2>/dev/null || echo "infra/migrations")
 
 # Are there new migrations?
 MIGRATIONS=$(git diff --name-only origin/$TARGET..origin/$SOURCE | grep "^${LAYOUT_MIGRATIONS}/" | sort)
@@ -220,18 +220,18 @@ Analyze the deploy payload and flag risks:
 # Check for new env vars that might not be in the configured secrets backend
 NEW_ENV=$(git diff origin/$TARGET..origin/$SOURCE -- '.env.example' | grep "^+" | grep -v "^+++" | grep -v "^#")
 if [ -n "$NEW_ENV" ]; then
-  echo "⚠️ NEW ENVIRONMENT VARIABLES — verify they exist in your secrets backend ({deploy.secrets_backend}):"
+  echo "⚠️ NEW ENVIRONMENT VARIABLES — verify they exist in your secrets backend ({DEPLOY_SECRETS_BACKEND}):"
   echo "$NEW_ENV"
   # Cross-check with SOPS chain (only when deploy.secrets_backend == "sops")
   # If your project uses a different backend, skip this block and verify manually.
-  if [ "{deploy.secrets_backend}" = "sops" ]; then
+  if [ "{DEPLOY_SECRETS_BACKEND}" = "sops" ]; then
     for var in $(echo "$NEW_ENV" | grep -oP '^\+\K[A-Z_]+'); do
       if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
         echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
       fi
     done
   else
-    echo "  ℹ️  SOPS chain check skipped — deploy.secrets_backend is '{deploy.secrets_backend}'. Verify new vars in your configured backend."
+    echo "  ℹ️  SOPS chain check skipped — deploy.secrets_backend is '{DEPLOY_SECRETS_BACKEND}'. Verify new vars in your configured backend."
   fi
 fi
 ```
@@ -249,7 +249,7 @@ Generate a checklist based on what's in the deploy:
 - [ ] All PRs in this deploy have been reviewed
 - [ ] No open `needs-human` issues blocking deploy
 - [ ] {If migrations} Database backup verified
-- [ ] {If new env vars} Secrets backend ({deploy.secrets_backend}) updated with new vars; verify via your configured secrets chain
+- [ ] {If new env vars} Secrets backend ({DEPLOY_SECRETS_BACKEND}) updated with new vars; verify via your configured secrets chain
 - [ ] {If traefik changes} Routing tested locally
 
 ### Deploy Command

package/commands/orchestrate.md

@@ -824,9 +824,9 @@ All tool commands are read from `forge.yaml → verification.commands`; each ste
 
 ```bash
 # Read toolchain commands from forge.yaml
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
-TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 
 # Check if this is a milestone batch with TypeScript changes
 MILESTONE_BRANCH="milestone/{milestone_slug}"

package/commands/review-pr-staging.md

@@ -14,6 +14,22 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 ---
 
+## Config Resolution
+
+Read `forge.yaml` to resolve branch names before running any commands:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+```
+
+All `$DEFAULT_BRANCH` and `$STAGING_BRANCH` references below are populated from `forge.yaml`.
+
+---
+
 ## Evidence-Based Review Protocol (ALL Agents)
 
 ### Diff-First Approach
@@ -70,22 +86,6 @@ Include ALL findings (CONFIRMED, LIKELY, POSSIBLE). One line per finding, sequen
 
 ---
 
-## Config Resolution
-
-Read `forge.yaml` to resolve branch names before running any commands:
-
-```bash
-CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
-GH_FLAG="-R $GH_REPO"
-DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
-STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
-```
-
-All `$DEFAULT_BRANCH` and `$STAGING_BRANCH` references below are populated from `forge.yaml`.
-
----
-
 ## Phase 0A: Open Review-Finding Gate (BLOCKING — runs before scope analysis)
 
 **Purpose**: Prevent deploying commits that have known, unfixed review findings. The review system catches bugs before merging; this gate ensures the merge path acts on that information.
@@ -213,8 +213,8 @@ Create review chunks by priority: Billing/Pricing (CRITICAL) → Security/Auth (
 Read `forge.yaml → verification.commands.python` for project-specific tool commands:
 
 ```bash
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
-PYTHON_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1 | head -30
@@ -234,8 +234,8 @@ fi
 Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
 
 ```bash
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
-TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1
@@ -261,7 +261,7 @@ Build failure is BLOCKING — deploy WILL fail. Typecheck alone misses SSG/prere
 Read `forge.yaml → verification.commands.python.test`:
 
 ```bash
-PYTHON_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$PYTHON_TEST" ]; then
     eval "$PYTHON_TEST" 2>&1 | tail -50

package/commands/review-pr.md

@@ -161,9 +161,9 @@ Read `forge.yaml → verification.commands.python` for project-specific tool com
 
 ```bash
 # Read toolchain commands from forge.yaml
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
-PYTHON_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;s/['\"].*//")
-PYTHON_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_TYPECHECK=$(yq '.verification.commands.python.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 
 # Run format check
 if [ -n "$PYTHON_FORMAT" ]; then
@@ -187,7 +187,7 @@ else
 fi
 
 # Always run compile check on changed Python files (fast, language-universal)
-for f in $(gh pr diff $ARGUMENTS --name-only | grep '\.py$'); do
+gh pr diff $ARGUMENTS --name-only | grep '\.py$' | while IFS= read -r f; do
     python3 -m py_compile "$f" 2>&1
 done
 ```
@@ -197,9 +197,9 @@ done
 Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
 
 ```bash
-TS_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
-TS_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;s/['\"].*//")
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_LINT=$(yq '.verification.commands.typescript.lint // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 
 # Run format check
 if [ -n "$TS_FORMAT" ]; then
@@ -243,7 +243,7 @@ gh pr diff $ARGUMENTS | grep -oE "['\"][A-Za-z0-9+/=]{40,}['\"]" | head -10
 
 ### 2F: SQL Migration Validation (if *.sql changed)
 ```bash
-for sql_file in $(gh pr diff $ARGUMENTS --name-only | grep "\.sql$"); do
+gh pr diff $ARGUMENTS --name-only | grep "\.sql$" | while IFS= read -r sql_file; do
     grep -E "FOR UPDATE" "$sql_file" | grep -qE "(SUM|COUNT|AVG|MIN|MAX)\s*\(" && echo "ERROR: FOR UPDATE with aggregate"
     grep -qE "DROP (TABLE|COLUMN|INDEX)" "$sql_file" && ! grep -qE "IF EXISTS" "$sql_file" && echo "WARNING: DROP without IF EXISTS"
     grep -qE "ALTER TABLE.*ADD COLUMN.*NOT NULL" "$sql_file" && ! grep -qE "DEFAULT" "$sql_file" && echo "WARNING: NOT NULL without DEFAULT"
@@ -263,7 +263,7 @@ Read `forge.yaml → verification.commands.{lang}.test` for the project's test c
 ```bash
 # Check each configured language for a test command
 for lang in python typescript go rust; do
-    TEST_CMD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk "/^    ${lang}:/{f=1;next} f && /^    [^ \t]/{exit} f" | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+    TEST_CMD=$(yq ".verification.commands.${lang}.test // \"\"" forge.yaml 2>/dev/null || echo '')
     if [ -n "$TEST_CMD" ]; then
         echo "=== Running tests (${lang}): ${TEST_CMD} ==="
         eval "$TEST_CMD" 2>&1 | tail -30
@@ -273,8 +273,8 @@ for lang in python typescript go rust; do
 done
 
 # If no test commands were configured, log explicitly
-PYTHON_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
-TS_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
+TS_TEST=$(yq '.verification.commands.typescript.test // ""' forge.yaml 2>/dev/null || echo '')
 if [ -z "$PYTHON_TEST" ] && [ -z "$TS_TEST" ]; then
     echo "SKIPPED — no test commands configured in verification.commands"
 fi
@@ -303,8 +303,8 @@ Read `forge.yaml → verification.commands.typescript.typecheck` and `.build`:
 ```bash
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
 
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
-TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1
@@ -337,10 +337,10 @@ Read `forge.yaml → verification.commands.python.format` and `.build`:
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
 
 # Compile-check all changed Python files (language-universal — no config needed)
-for f in $(echo "$CHANGED_FILES" | grep '\.py$'); do python3 -m py_compile "$f" 2>&1; done
+echo "$CHANGED_FILES" | grep '\.py$' | while IFS= read -r f; do python3 -m py_compile "$f" 2>&1; done
 
 if [ "$REQUIRES_FULL_BUILD" = "true" ]; then
-    PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+    PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
     if [ -n "$PYTHON_FORMAT" ]; then
         eval "$PYTHON_FORMAT" 2>&1
     else
@@ -495,7 +495,7 @@ fi
 # Python scoping hazard check — local imports that shadow module-level names
 # A local `import X` makes X a local variable for the ENTIRE function scope.
 # Any reference to X ABOVE the local import will crash with UnboundLocalError.
-for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
+echo "$CHANGED_FILES" | grep -E '\.py$' | while IFS= read -r f; do
     echo "=== Python Scoping Check: $f ==="
     # Find function-scoped imports (indented import statements)
     grep -nE "^\s+import [a-z]" "$f" 2>/dev/null | while read line; do
@@ -509,7 +509,7 @@ for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
 done
 
 # Config file assumption check (baked into Docker image vs volume-mounted)
-for f in $(echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$"); do
+echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$" | while IFS= read -r f; do
     echo "=== Config File: $f ==="
     grep -n "$(dirname $f)" docker-compose.yml 2>/dev/null || echo "WARNING: Config dir may not be mounted — changes may require --build"
     grep -n "$(dirname $f)" services/*/Dockerfile 2>/dev/null || true

package/commands/rollback.md

@@ -122,7 +122,7 @@ for f in {reverted_python_files}; do
 done
 
 # Python format check (config-driven)
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1 | head -20
 else
@@ -130,7 +130,7 @@ else
 fi
 
 # TypeScript typecheck (config-driven)
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1 | head -20
 else

package/commands/work-on/build/validate.md

@@ -94,7 +94,7 @@ Run after quality gate passes. All tool commands are read from `forge.yaml → v
 ```bash
 cd {WORKTREE_PATH}
 
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
@@ -110,9 +110,9 @@ Failures in `py_compile` are BLOCKING — fix before continuing.
 ```bash
 cd {WORKTREE_PATH}
 
-TS_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
-TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1

package/commands/work-on-monolithic.md

@@ -214,7 +214,24 @@ Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
 All client-side fetch/useSWR/apiFetch must use `/api/...` proxy routes, NEVER `/api/v1/...` directly.
 
 ### 3I: Deployment completeness check (MANDATORY)
-New env vars must be in: `.env.example` + SOPS `prod.enc.yaml` + `decrypt-secrets.sh` ENV_MAPPING + `env_validation.py` (if API).
+Skip if no new env vars introduced.
+
+For each new env var, verify present in ALL required locations:
+
+| Location | Required for |
+|----------|-------------|
+| `.env.example` | All new vars |
+| Secrets backend (see `deploy.secrets_backend`) | Secret vars — skip if backend is `none` or unset |
+| `app/env_validation.py` | API service vars (if project has one) |
+
+**Secrets backend check** *(trigger: `deploy.secrets_backend == "sops"`)*:
+
+If the project uses SOPS, verify the new var is present in all SOPS chain locations:
+- `infra/secrets/prod.enc.yaml` — SOPS-encrypted secret store
+- `infra/decrypt-secrets.sh` ENV_MAPPING — maps SOPS key to env var name
+
+If `deploy.secrets_backend` is absent or not `sops`, skip these checks and log:
+> `SKIP: SOPS chain check — deploy.secrets_backend is not "sops". Configure deploy.secrets_backend in forge.yaml to enable.`
 
 ### 3J: Commit
 Conventional prefix (fix/feat/refactor/docs). Reference #{NUMBER} in the commit message.

package/commands/work-on.md

@@ -753,7 +753,7 @@ All tool commands are read from `forge.yaml → verification.commands`. When a k
 ```bash
 cd {WORKTREE_PATH}
 
-PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
@@ -769,9 +769,9 @@ python -m py_compile {PYTHON_FILES}
 ```bash
 cd {WORKTREE_PATH}
 
-TS_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
-TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
-TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/verify-route-registration.sh

@@ -49,12 +49,25 @@ WARNINGS=0
 
 # --- Next.js Route Handler registration check ---
 while read -r f; do
-    URL_PATH=$(echo "$f" | sed "s|^${FORGE_PAGES_ROOT}||; s|/route\\.ts\$||; s|\\[.*\\]|*|g")
+    # Use shell parameter expansion instead of sed to avoid interpreting FORGE_PAGES_ROOT
+    # as a sed pattern (values containing | or other metacharacters break the substitution).
+    stripped="${f#${FORGE_PAGES_ROOT}/}"
+    stripped="${stripped%/route.ts}"
+    # Replace dynamic segments [param] with * using a loop (no regex needed)
+    URL_PATH=""
+    IFS='/' read -ra SEGMENTS <<< "$stripped"
+    for seg in "${SEGMENTS[@]}"; do
+        case "$seg" in
+            \[*\]) URL_PATH="${URL_PATH}/*" ;;
+            *)     URL_PATH="${URL_PATH}/${seg}" ;;
+        esac
+    done
     ROUTE_SEGMENT=$(echo "$URL_PATH" | sed 's|/api/v1/||; s|/.*||')
 
     # Check if next.config.js has a rewrite that might shadow this route
     if [ -f "$REPO_ROOT/web/next.config.js" ]; then
-        if grep -q "$ROUTE_SEGMENT" "$REPO_ROOT/web/next.config.js" 2>/dev/null; then
+        # Use -F (fixed string) so ROUTE_SEGMENT is not interpreted as a regex pattern
+        if grep -qF "$ROUTE_SEGMENT" "$REPO_ROOT/web/next.config.js" 2>/dev/null; then
             echo "WARNING: Route handler $f ($URL_PATH) — next.config.js references '$ROUTE_SEGMENT', may shadow this route"
             WARNINGS=$((WARNINGS + 1))
         else
@@ -64,12 +77,19 @@ while read -r f; do
 
     # Check if nginx routes this path to Next.js or directly to backend
     if [ -f "$REPO_ROOT/infra/nginx/nginx.conf" ]; then
-        if grep -q "location.*$ROUTE_SEGMENT" "$REPO_ROOT/infra/nginx/nginx.conf" 2>/dev/null; then
+        # Check for location blocks mentioning ROUTE_SEGMENT — use two -F searches to avoid
+        # embedding the variable in a regex: first find lines with "location", then filter
+        # for the literal segment. This avoids ROUTE_SEGMENT being interpreted as a BRE.
+        if grep -F "location" "$REPO_ROOT/infra/nginx/nginx.conf" 2>/dev/null | grep -qF "$ROUTE_SEGMENT"; then
             echo "WARNING: Route handler $f ($URL_PATH) — nginx.conf has a location block for '$ROUTE_SEGMENT', may bypass Next.js"
             WARNINGS=$((WARNINGS + 1))
         fi
     fi
-done < <(echo "$FILES" | grep -E "^${FORGE_PAGES_ROOT}/api/.*route\\.ts$") || true
+done < <(echo "$FILES" | while IFS= read -r line; do
+    case "$line" in
+        "${FORGE_PAGES_ROOT}/api/"*"route.ts") echo "$line" ;;
+    esac
+done) || true
 
 # --- Python API Router registration check ---
 while read -r f; do
@@ -77,7 +97,8 @@ while read -r f; do
     MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
-        if grep -q "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
+        # Use -F (fixed string) so ROUTER_NAME is not interpreted as a regex pattern
+        if grep -qF "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
             echo "OK: API Router '$ROUTER_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
             echo "BLOCKING: API Router '$ROUTER_NAME' ($f) — NOT found in $(basename "$MAIN_PY"). Router will not be reachable."
@@ -95,7 +116,8 @@ while read -r f; do
     MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
-        if grep -q "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
+        # Use -F (fixed string) so MIDDLEWARE_NAME is not interpreted as a regex pattern
+        if grep -qF "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
             echo "OK: Middleware '$MIDDLEWARE_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
             echo "WARNING: Middleware '$MIDDLEWARE_NAME' ($f) — not found in $(basename "$MAIN_PY"). May not be active."
@@ -108,7 +130,8 @@ done < <(echo "$FILES" | grep -E "^${FORGE_API_MIDDLEWARE_DIR}/.*\\.py$") || tru
 while read -r f; do
     MODULE_NAME=$(basename "$f" .py)
 
-    IMPORTERS=$(grep -rl "$MODULE_NAME" "$REPO_ROOT/${FORGE_API_SERVICES_DIR}/" "$REPO_ROOT/${FORGE_WORKER_DIR}/" 2>/dev/null | head -5)
+    # Use -F (fixed string) so MODULE_NAME is not interpreted as a regex pattern
+    IMPORTERS=$(grep -rlF "$MODULE_NAME" "$REPO_ROOT/${FORGE_API_SERVICES_DIR}/" "$REPO_ROOT/${FORGE_WORKER_DIR}/" 2>/dev/null | head -5)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Shared module '$MODULE_NAME' ($f) — imported by services"
     else
@@ -121,7 +144,9 @@ done < <(echo "$FILES" | grep -E "^shared/.*\.py$") || true
 while read -r f; do
     COMPONENT_NAME=$(basename "$f" .tsx)
 
-    IMPORTERS=$(grep -rl "$COMPONENT_NAME" "$REPO_ROOT/${FORGE_PAGES_ROOT}/" "$REPO_ROOT/${FORGE_COMPONENTS_DIR}/" 2>/dev/null | grep -v "$f" | head -3)
+    # Use -F (fixed string) for both the component name search and the self-exclusion
+    # to prevent file paths and component names from being interpreted as regex patterns
+    IMPORTERS=$(grep -rlF "$COMPONENT_NAME" "$REPO_ROOT/${FORGE_PAGES_ROOT}/" "$REPO_ROOT/${FORGE_COMPONENTS_DIR}/" 2>/dev/null | grep -vF "$f" | head -3)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Component '$COMPONENT_NAME' ($f) — imported by other files"
     else

package/scripts/verify-sops-chain.sh

@@ -80,7 +80,9 @@ if [ -n "$NEW_MAPPINGS" ]; then
 
     # For each new mapping, verify the SOPS path structure exists
     # (We can't decrypt SOPS to verify values, but we can check the mapping format is valid)
-    echo "$NEW_MAPPINGS" | while IFS= read -r mapping; do
+    # Use process substitution instead of a pipe so WARNINGS increments persist in the parent shell.
+    # (echo ... | while read creates a subshell — counter changes are lost on subshell exit.)
+    while IFS= read -r mapping; do
         VAR_NAME=$(echo "$mapping" | grep -oE '^"[A-Z_]+"' | tr -d '"')
         SOPS_SECTION=$(echo "$mapping" | grep -oE '\("([a-z_]+)"' | head -1 | tr -d '("')
         SOPS_KEY=$(echo "$mapping" | grep -oE ', "([a-z_]+)"\)' | tr -d ', ")')
@@ -91,7 +93,7 @@ if [ -n "$NEW_MAPPINGS" ]; then
             echo "WARNING: Malformed ENV_MAPPING entry: $mapping"
             WARNINGS=$((WARNINGS + 1))
         fi
-    done
+    done < <(echo "$NEW_MAPPINGS")
 else
     echo "OK: No new ENV_MAPPING entries in diff"
 fi