forgedock 1.0.6 → 1.0.8

package/bin/forgedock.mjs

@@ -2,9 +2,18 @@
 
 import os from "os";
 import { fileURLToPath } from "url";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "path";
 import {
   mkdir,
+  rm,
   symlink,
   copyFile,
   readlink,
@@ -2211,7 +2220,9 @@ async function _buildForgeDockBlock() {
     if (!description) continue;
 
     // Derive display name: relative path from COMMANDS_DIR, remove .md extension
-    const rel = relative(COMMANDS_DIR, file).replace(/\\/g, "/").replace(/\.md$/, "");
+    const rel = relative(COMMANDS_DIR, file)
+      .replace(/\\/g, "/")
+      .replace(/\.md$/, "");
     commands.push({ name: rel, description });
   }
 
@@ -2274,28 +2285,51 @@ function _injectManagedBlock(filePath, blockContent, createIfMissing) {
 
   let existing = readFileSync(filePath, "utf-8");
 
-  if (existing.includes(CLAUDE_BLOCK_BEGIN) && existing.includes(CLAUDE_BLOCK_END)) {
-    // Both markers present — replace existing block in place
-    const escaped_begin = CLAUDE_BLOCK_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (
+    existing.includes(CLAUDE_BLOCK_BEGIN) &&
+    existing.includes(CLAUDE_BLOCK_END)
+  ) {
+    // Both markers present — replace existing block in place.
+    // Guard: if markers are reversed (END before BEGIN) the regex finds no
+    // forward-spanning match; fall through to the repair path instead of
+    // writing the file unchanged and returning a false 'updated'. <!-- Added: forge#291 -->
+    const escaped_begin = CLAUDE_BLOCK_BEGIN.replace(
+      /[.*+?^${}()|[\]\\]/g,
+      "\\$&",
+    );
     const escaped_end = CLAUDE_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const blockRegex = new RegExp(
       `${escaped_begin}[\\s\\S]*?${escaped_end}`,
       "g",
     );
-    existing = existing.replace(blockRegex, managed);
-    writeFileSync(filePath, existing, "utf-8");
-    return "updated";
-  }
-
-  if (existing.includes(CLAUDE_BLOCK_BEGIN)) {
+    const replaced = existing.replace(blockRegex, managed);
+    if (replaced !== existing) {
+      writeFileSync(filePath, replaced, "utf-8");
+      return "updated";
+    }
+    // Regex found no match (e.g. reversed markers) — strip both orphaned
+    // markers below and fall through to the append path to repair the file.
+    existing = existing
+      .replace(CLAUDE_BLOCK_BEGIN, "")
+      .replace(CLAUDE_BLOCK_END, "")
+      .trimEnd();
+  } else if (existing.includes(CLAUDE_BLOCK_BEGIN)) {
     // BEGIN present but END missing — file is truncated or malformed.
     // Strip the orphaned marker and everything after it, then fall through
     // to the append path below so the complete block is written correctly.
-    existing = existing.slice(0, existing.indexOf(CLAUDE_BLOCK_BEGIN)).trimEnd();
+    existing = existing
+      .slice(0, existing.indexOf(CLAUDE_BLOCK_BEGIN))
+      .trimEnd();
+  } else if (existing.includes(CLAUDE_BLOCK_END)) {
+    // END present but BEGIN missing — orphaned END marker left by a previous
+    // failed write. Strip it and fall through to append the complete block.
+    // <!-- Added: forge#291 -->
+    existing = existing.replace(CLAUDE_BLOCK_END, "").trimEnd();
   }
 
   // Append block to existing content, separated by a blank line
-  const separator = existing.length === 0 || existing.endsWith("\n") ? "\n" : "\n\n";
+  const separator =
+    existing.length === 0 || existing.endsWith("\n") ? "\n" : "\n\n";
   writeFileSync(filePath, `${existing}${separator}${managed}\n`, "utf-8");
   return "updated";
 }
@@ -2324,9 +2358,13 @@ async function injectClaudeMd(cwd) {
 
   const claudeResult = _injectManagedBlock(claudePath, blockContent, true);
   if (claudeResult === "created") {
-    console.log(`  ${GREEN}✔${RESET}  CLAUDE.md created with ForgeDock integration block`);
+    console.log(
+      `  ${GREEN}✔${RESET}  CLAUDE.md created with ForgeDock integration block`,
+    );
   } else {
-    console.log(`  ${GREEN}✔${RESET}  CLAUDE.md updated — ForgeDock block refreshed`);
+    console.log(
+      `  ${GREEN}✔${RESET}  CLAUDE.md updated — ForgeDock block refreshed`,
+    );
   }
 
   if (existsSync(agentsPath)) {
@@ -3421,9 +3459,7 @@ async function labelsSetup(repo) {
   const manifestPath = join(__dirname, "labels.json");
 
   if (!existsSync(manifestPath)) {
-    console.log(
-      `${RED}Label manifest not found: ${manifestPath}${RESET}`,
-    );
+    console.log(`${RED}Label manifest not found: ${manifestPath}${RESET}`);
     process.exit(1);
   }
 
@@ -3543,21 +3579,54 @@ async function docsInit() {
 
   // Security: assert targetDir is confined to the project directory.
   // Prevents path traversal via ../.. sequences, absolute paths, and symlinks in devdocs.path.
-  // Use realpath() to dereference symlinks — resolve() does not follow them, so a symlink
-  // pre-placed inside the project (e.g. devdocs -> /etc) would bypass a resolve()-only check.
-  // Fall back to resolve() when targetDir does not yet exist (no symlink to dereference).
+  //
+  // Two hardening steps beyond the initial check:
+  //
+  // 1. realpath(cwd) — on Windows, process.cwd() may return a directory-junction path while
+  //    realpath() returns the canonical target.  Comparing a canonical resolvedTarget against
+  //    a non-canonical cwd would false-reject valid paths (BUG-3).
+  //
+  // 2. Walk-up-to-existing-ancestor resolution on ENOENT — when the target path does not yet
+  //    exist, falling back to lexical resolve() fails to follow intermediate symlinks.  A
+  //    symlink planted at "sub/" pointing outside the project would not be dereferenced, so
+  //    the lexical result would appear inside the project and the containment check would
+  //    pass, allowing mkdir() to write through the symlink (SEC-1).  Calling realpath() only
+  //    one level up ("parent-first") still fails when the parent also does not exist (e.g.,
+  //    devdocs.path = "sub/mid/leaf" where "sub" is a symlink but "sub/mid" is absent) —
+  //    realpath("sub/mid") follows sub then ENOENT-s on mid, and the lexical fallback does
+  //    not dereference sub (SEC-2).  Instead, walk up the directory hierarchy until finding
+  //    an ancestor that exists, realpath() it to dereference any symlinks at that level, then
+  //    reattach all collected suffix segments.
+  const realCwd = await realpath(cwd).catch(() => resolve(cwd));
   let resolvedTarget;
   try {
     resolvedTarget = await realpath(targetDir);
   } catch {
+    // targetDir does not exist — walk up the hierarchy to the nearest existing ancestor,
+    // dereference it via realpath() to follow any intermediate symlinks, then reattach the
+    // collected suffix segments.  Initialise resolvedTarget to the lexical path as a
+    // last-resort sentinel (overwritten by the loop on the first successful realpath call).
+    const trailSegments = [basename(targetDir)];
+    let ancestor = dirname(targetDir);
     resolvedTarget = resolve(targetDir);
+    while (true) {
+      const parent = dirname(ancestor);
+      if (parent === ancestor) break; // reached filesystem root — keep lexical sentinel
+      try {
+        resolvedTarget = join(await realpath(ancestor), ...trailSegments);
+        break;
+      } catch {
+        trailSegments.unshift(basename(ancestor));
+        ancestor = parent;
+      }
+    }
   }
-  if (resolvedTarget !== cwd && !resolvedTarget.startsWith(cwd + sep)) {
+  if (resolvedTarget !== realCwd && !resolvedTarget.startsWith(realCwd + sep)) {
     console.log(
       `${RED}Error: devdocs.path must be inside the project directory.${RESET}`,
     );
     console.log(`  Resolved: ${resolvedTarget}`);
-    console.log(`  Project:  ${cwd}`);
+    console.log(`  Project:  ${realCwd}`);
     console.log(
       `  Fix: set ${CYAN}devdocs.path${RESET} to a relative path inside your project (e.g. "devdocs" or "docs/knowledge").`,
     );
@@ -3568,12 +3637,8 @@ async function docsInit() {
   const templatesDir = join(FORGE_HOME, "templates", "devdocs");
 
   if (!existsSync(templatesDir)) {
-    console.log(
-      `${RED}DevDocs templates not found: ${templatesDir}${RESET}`,
-    );
-    console.log(
-      `  This usually means ForgeDock is not installed correctly.`,
-    );
+    console.log(`${RED}DevDocs templates not found: ${templatesDir}${RESET}`);
+    console.log(`  This usually means ForgeDock is not installed correctly.`);
     console.log(
       `  Try: ${CYAN}npm install -g forgedock${RESET} or ${CYAN}npx forgedock@latest docs init${RESET}`,
     );
@@ -3589,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 });
@@ -4083,7 +4185,11 @@ if (!command) {
       break;
     case "labels": {
       const subcommand = args[1];
-      if (!subcommand || subcommand === "setup" || subcommand.startsWith("--")) {
+      if (
+        !subcommand ||
+        subcommand === "setup" ||
+        subcommand.startsWith("--")
+      ) {
         const subArgs = args.slice(1);
         const repo = resolveLabelsRepo(subArgs);
         if (!repo) {
@@ -4112,9 +4218,7 @@ if (!command) {
         await docsInit();
       } else {
         console.log(`${RED}Unknown docs subcommand: ${docsSubcommand}${RESET}`);
-        console.log(
-          `Usage: ${CYAN}npx forgedock docs init${RESET}`,
-        );
+        console.log(`Usage: ${CYAN}npx forgedock docs init${RESET}`);
         process.exit(1);
       }
       break;

package/commands/autopilot.md

@@ -11,6 +11,13 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 - `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
 - `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
 - `{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.
 
@@ -51,9 +58,15 @@ DRY_RUN = true if --dry-run present
 ```bash
 echo "=== Autopilot Cycle: $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="
 
+# Portable ISO-8601 date arithmetic using python3 (works on Windows, macOS, Linux).
+# Replaces GNU-only `date -u -d 'N days ago'` which fails on Windows and macOS.
+DATE_3D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=3)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+DATE_7D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=7)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+DATE_1D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+
 # Recent closed issues (last 3 days) — what was fixed recently?
 gh issue list --state closed --json number,title,labels,closedAt \
-  --jq '[.[] | select(.closedAt > "'$(date -u -d '3 days ago' +%Y-%m-%dT%H:%M:%SZ)'")] | length' 2>/dev/null || echo "0"
+  --jq '[.[] | select(.closedAt > "'"$DATE_3D_AGO"'")] | length' 2>/dev/null || echo "0"
 
 # Open issue count by priority
 gh issue list --state open --label "priority:P0" --json number --jq 'length'
@@ -64,12 +77,12 @@ gh issue list --state open --label "priority:P2" --json number --jq 'length'
 gh issue list --state open --limit 200 --json number,title,labels,createdAt \
   --jq '[.[] | select(
     (.labels | map(.name) | any(startswith("workflow:")) | not) and
-    (.createdAt < "'$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)'")
+    (.createdAt < "'"$DATE_7D_AGO"'")
   )] | length'
 
 # Failed CI runs in last 24h
 gh run list --limit 30 --json conclusion,createdAt \
-  --jq '[.[] | select(.conclusion == "failure" and .createdAt > "'$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)'")] | length'
+  --jq '[.[] | select(.conclusion == "failure" and .createdAt > "'"$DATE_1D_AGO"'")] | length'
 ```
 
 Store these as `BASELINE` metrics for the cycle report.
@@ -140,8 +153,9 @@ Analyze GitHub issue backlog:
 Quick analytics pulse — just the key metrics, not a full audit:
 1. Read credentials from {CREDENTIALS_FILE} (set via paths.credentials.file in forge.yaml)
 2. GSC: mcp__gsc__search_analytics for last 7 days — total clicks, impressions, avg position
-3. Stripe: mcp__stripe__retrieve_balance — current balance
-4. Return: clicks trend (up/down), any revenue, notable changes
+3. Stripe (only if {BILLING_ENABLED} is true): mcp__stripe__retrieve_balance — current balance.
+   Skip this step entirely if {BILLING_ENABLED} is false — do NOT call any Stripe MCP tools.
+4. Return: clicks trend (up/down), revenue (or "N/A — billing.enabled: false" if skipped), notable changes
 ```
 
 ### 1B: Collect results
@@ -291,7 +305,7 @@ Print a structured report:
 
 ### Analytics Pulse
 - Clicks (7d): {N} ({trend})
-- Revenue: ${N}
+- Revenue: ${N} (or "N/A — billing.enabled: false" if Stripe step was skipped)
 
 ### Actions Taken
 - Issues created: {count} ({list with numbers})

package/commands/cleanup.md

@@ -25,11 +25,16 @@ GH_FLAG="-R $GH_REPO"
 REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
 STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
 PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
-PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' "$CONFIG_FILE")
-PROJECT_ID=$(yq '.project_board.project_id' "$CONFIG_FILE")
+PROJECT_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+PROJECT_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+# Project board field and option IDs — empty string when project_board section is absent
+STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_FIELD_ID=$(yq '.project_board.field_ids.workflow // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+STATUS_DONE_OPTION_ID=$(yq '.project_board.option_ids.status.done // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_MERGED_OPTION_ID=$(yq '.project_board.option_ids.workflow.merged // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, `{PROJECT_ID}`, `{STATUS_FIELD_ID}`, `{WORKFLOW_FIELD_ID}`, `{STATUS_DONE_OPTION_ID}`, and `{WORKFLOW_MERGED_OPTION_ID}` references below are populated from `forge.yaml`.
 
 ---
 
@@ -222,19 +227,29 @@ fi
 
 ## Phase 5: Sync Project Board (if `board` or `all`)
 
-For closed issues that are on the Project board but have stale fields:
+**Skip if `project_board` is not configured** — check resolved vars before proceeding:
 
 ```bash
-gh project item-list {PROJECT_NUMBER} --owner {PROJECT_BOARD_OWNER} --format json --limit 200
-```
+if [ -z "$PROJECT_BOARD_OWNER" ] || [ -z "$PROJECT_ID" ] || [ -z "$PROJECT_NUMBER" ]; then
+  echo "INFO: project_board not configured in forge.yaml — skipping board sync"
+else
+  # Board sync: mark closed issues as Done/Merged on the project board
 
-For each item where `content.state == "CLOSED"` but `status != "Done"` or `workflow` is not a terminal state:
+  # List all board items
+  ITEMS=$(gh project item-list "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --format json --limit 200)
 
-```bash
-gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" \
-  --field-id {PROJECT_BOARD_STATUS_FIELD_ID} --single-select-option-id {PROJECT_BOARD_STATUS_DONE_ID} 2>/dev/null || true  # Status=Done
-gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" \
-  --field-id {PROJECT_BOARD_WORKFLOW_FIELD_ID} --single-select-option-id {PROJECT_BOARD_WORKFLOW_MERGED_ID} 2>/dev/null || true  # Workflow=Merged
+  # For each item where content.state == "CLOSED" but status != "Done" or workflow is not terminal:
+  echo "$ITEMS" | jq -r '.items[] | select(.content.state == "CLOSED") | .id' | while read -r ITEM_ID; do
+    if [ -n "$STATUS_FIELD_ID" ] && [ -n "$STATUS_DONE_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$STATUS_FIELD_ID" --single-select-option-id "$STATUS_DONE_OPTION_ID" 2>/dev/null || true  # Status=Done
+    fi
+    if [ -n "$WORKFLOW_FIELD_ID" ] && [ -n "$WORKFLOW_MERGED_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$WORKFLOW_FIELD_ID" --single-select-option-id "$WORKFLOW_MERGED_OPTION_ID" 2>/dev/null || true  # Workflow=Merged
+    fi
+  done
+fi
 ```
 
 ---

package/commands/deploy-info.md

@@ -10,6 +10,8 @@ argument-hint: [staging | milestone/{slug} | compare {branch}]
 **Config variables used by this command** (set in `forge.yaml`):
 - `{REPO_PATH}` ← `paths.root` — project repository root
 - `{HEALTH_ENDPOINT}` ← `services.health_endpoint` (optional) — URL used in post-deploy health check
+- `{DEPLOY_WORKFLOW}` ← `deploy.workflow` (optional) — GitHub Actions workflow filename to trigger a deploy (e.g., `hotfix-deploy.yml`). When absent or empty, workflow-trigger steps are omitted.
+- `{DEPLOY_SECRETS_BACKEND}` ← `deploy.secrets_backend` (optional) — secrets delivery method (`sops`, `aws-sm`, `vault`, `ci-env`, `none`). Controls whether secret-chain checks run.
 
 You are the pipeline's deploy awareness layer. Before the user merges staging → main (triggering CI/CD deployment), this command shows exactly what's going out: which PRs, which issues, what changed, and what risks exist.
 
@@ -153,13 +155,20 @@ done
 # Full file diff summary
 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"' 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$||')
+
 # Categorize by service
 echo "=== By Service ==="
 git diff --name-only origin/$TARGET..origin/$SOURCE | sort | while read f; do
   case "$f" in
-    services/api/*) echo "API: $f" ;;
-    services/worker/*) echo "WORKER: $f" ;;
-    web/*) echo "WEB: $f" ;;
+    ${LAYOUT_API}/*) echo "API: $f" ;;
+    ${LAYOUT_WORKER}/*) echo "WORKER: $f" ;;
+    ${LAYOUT_WEB}/*) echo "WEB: $f" ;;
     shared/*) echo "SHARED: $f" ;;
     infra/*) echo "INFRA: $f" ;;
     *) echo "OTHER: $f" ;;
@@ -170,8 +179,11 @@ done | sort
 ### Step 2E: Migration check
 
 ```bash
+# Read migrations path from forge.yaml, fall back to 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 "^infra/migrations/" | sort)
+MIGRATIONS=$(git diff --name-only origin/$TARGET..origin/$SOURCE | grep "^${LAYOUT_MIGRATIONS}/" | sort)
 if [ -n "$MIGRATIONS" ]; then
   echo "⚠️ DATABASE MIGRATIONS INCLUDED:"
   echo "$MIGRATIONS"
@@ -195,7 +207,7 @@ Analyze the deploy payload and flag risks:
 |--------|-----------|--------|
 | Database migrations present | MEDIUM | Verify migrations are reversible |
 | `shared/` changes | LOW | Restart-only deploy possible (no rebuild) |
-| `.env.example` changes | HIGH | Verify SOPS + decrypt-secrets has new vars |
+| `.env.example` changes | HIGH | Verify secrets backend has new vars (see `deploy.secrets_backend`) |
 | `docker-compose.prod.yml` changes | HIGH | Review infrastructure changes carefully |
 | `infra/traefik/` changes | HIGH | Routing changes — test before full deploy |
 | 10+ PRs in one deploy | MEDIUM | Consider deploying in smaller batches |
@@ -205,17 +217,22 @@ Analyze the deploy payload and flag risks:
 ### Automated Checks
 
 ```bash
-# Check for new env vars that might not be in SOPS
+# 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 SOPS:"
+  echo "⚠️ NEW ENVIRONMENT VARIABLES — verify they exist in your secrets backend ({DEPLOY_SECRETS_BACKEND}):"
   echo "$NEW_ENV"
-  # Cross-check with decrypt-secrets.sh
-  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
+  # 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
+    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."
+  fi
 fi
 ```
 
@@ -232,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} SOPS secrets updated and decrypt-secrets.sh has mapping
+- [ ] {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
@@ -240,8 +257,9 @@ Generate a checklist based on what's in the deploy:
 # Standard deploy (merge staging → main via GitHub web UI)
 # CI/CD auto-triggers on push to main
 
-# Or manual trigger for specific services:
-gh workflow run hotfix-deploy.yml --ref main -f services={affected_services} -f reason="Deploy: {summary}"
+# Or manual trigger for specific services (requires deploy.workflow set in forge.yaml):
+gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services}={affected_services} -f {deploy.workflow_inputs.reason}="Deploy: {summary}"
+# If deploy.workflow is not configured, deploy via the GitHub web UI or your CI/CD provider.
 ```
 
 ### Post-Deploy
@@ -292,5 +310,6 @@ gh workflow run hotfix-deploy.yml --ref main -f services={affected_services} -f
 ---
 
 **Ready to deploy?** Merge staging → main via GitHub web UI, or run:
-`gh workflow run hotfix-deploy.yml --ref staging -f services={services} -f reason="Batch deploy"`
+`gh workflow run {deploy.workflow} --ref staging -f {deploy.workflow_inputs.services}={services} -f {deploy.workflow_inputs.reason}="Batch deploy"`
+*(requires `deploy.workflow` set in `forge.yaml`; omit this line if not configured)*
 ```

package/commands/incident-response.md

@@ -9,6 +9,7 @@ argument-hint: [issue number | "active" | "postmortem {issue}"]
 
 **Config variables used by this command** (set in `forge.yaml`):
 - `{REPO_PATH}` ← `paths.root` — project repository root
+- `{DEPLOY_WORKFLOW}` ← `deploy.workflow` (optional) — GitHub Actions workflow filename for hotfix deploys (e.g., `hotfix-deploy.yml`). When absent or empty, workflow-trigger and workflow-monitor steps are omitted.
 
 You are the pipeline's incident response coordinator. When production goes down or a critical bug surfaces, this command orchestrates the response: validates the hotfix before deploy, reconstructs the incident timeline, and produces a post-incident analysis.
 
@@ -55,8 +56,9 @@ Parse the issue to understand:
 gh pr list --state merged --base main --json number,title,mergedAt \
   --jq '[.[] | select(.mergedAt > (now - 86400 | todate))] | .[] | "\(.number) | \(.title) | \(.mergedAt)"'
 
-# Check recent hotfix deploys
-gh run list --workflow=hotfix-deploy.yml --limit 5 --json databaseId,status,conclusion,createdAt,displayTitle
+# Check recent hotfix deploys (requires deploy.workflow set in forge.yaml)
+# Skip this check if deploy.workflow is not configured.
+gh run list --workflow={deploy.workflow} --limit 5 --json databaseId,status,conclusion,createdAt,displayTitle
 ```
 
 #### Step 1C: Post incident acknowledgment
@@ -119,9 +121,10 @@ Your job:
    - Does it remove functionality other code depends on?
    - Are there syntax errors?
    - Does it change DB schema without a migration?
-4. Run compile checks:
-   - Python: python -m py_compile on changed .py files
-   - TypeScript: npx tsc --noEmit (if web/ files changed)
+4. Run compile checks (read forge.yaml → verification.commands for tool commands):
+   - Python: always run python -m py_compile on changed .py files (no config needed)
+   - Python format/lint: run verification.commands.python.format and .lint if configured; log "SKIPPED — not configured in verification.commands" if absent
+   - TypeScript: run verification.commands.typescript.typecheck if configured; log "SKIPPED — not configured in verification.commands" if absent
 5. Check if the fix is scoped tightly (minimal changes for the incident)
 
 Output:
@@ -143,10 +146,11 @@ gh issue comment {NUMBER} --body "$(cat <<'EOF'
 **Confidence**: {level}
 
 {If safe}:
-**Ready for deploy.** Run:
+**Ready for deploy.** Run (requires `deploy.workflow` set in `forge.yaml`):
 ```
-gh workflow run hotfix-deploy.yml --ref {FIX_BRANCH} -f services={affected_services} -f reason="P0: {TITLE}"
+gh workflow run {deploy.workflow} --ref {FIX_BRANCH} -f {deploy.workflow_inputs.services}={affected_services} -f {deploy.workflow_inputs.reason}="P0: {TITLE}"
 ```
+*(If `deploy.workflow` is not configured, merge the fix branch via the GitHub web UI or your CI/CD provider.)*
 
 {If not safe}:
 **Concerns found:**
@@ -164,8 +168,9 @@ EOF
 #### Step 3A: Watch the deploy workflow
 
 ```bash
-# Find the most recent hotfix-deploy run
-RUN_ID=$(gh run list --workflow=hotfix-deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+# Find the most recent deploy run (requires deploy.workflow set in forge.yaml)
+# Skip if deploy.workflow is not configured.
+RUN_ID=$(gh run list --workflow={deploy.workflow} --limit 1 --json databaseId --jq '.[0].databaseId')
 
 # Check status
 gh run view $RUN_ID --json status,conclusion,jobs

package/commands/issue.md

@@ -28,7 +28,7 @@ The user's input (`$ARGUMENTS`) can be:
 |-----------|---------|
 | Free-text description | "the billing page crashes when credits hit zero" |
 | URL to error/log | "https://sentry.io/..." or a pasted stack trace |
-| Reference to code | "the scraper queue leaks memory in unified_consumer.py" |
+| Reference to code | "the background worker leaks memory in task_processor.py" |
 | Feature request | "add a dark mode toggle to the dashboard settings page" |
 | Multi-repo prefix | "mcp: add list_schemas tool" or "n8n: fix credential refresh" |
 | Audit/investigation | "investigate why deploy times doubled this week" |
@@ -161,8 +161,8 @@ Format: `{prefix}: {concise description}`
 Rules:
 - **Max 80 characters**
 - Use conventional commit prefixes: `fix:`, `feat:`, `refactor:`, `investigate:`, `docs:`
-- Be specific — "fix: billing page crash" is bad, "fix: credit_service division by zero when user credits reach 0" is good
-- Include the component/domain if it helps: `fix(scraper): queue leak in unified_consumer heartbeat loop`
+- Be specific — "fix: billing page crash" is bad, "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" is good
+- Include the component/domain if it helps: `fix(worker): queue leak in task_processor heartbeat loop`
 - Never use vague words: "improve", "update", "change", "handle" without specifics
 
 ### 3B: Compose the body
@@ -258,6 +258,8 @@ Files/areas to examine:
 
 ### 3D: Pipeline Issue Template (machine-callable reference)
 
+> **Canonical Standard**: This template is the single source of truth for all automated issue creation in the ForgeDock pipeline. `milestone.md`, `orchestrate.md`, and `work-on/decompose.md` MUST use this template structure when creating issues programmatically. A shared convention is only useful if all create-paths enforce it — divergent inline templates in each command file cause acceptance-criteria drift and coverage gaps. See `work-on/decompose.md` Phase D0 for the investigation-gate pattern that enforces this standard at decomposition time. <!-- Added: forge#293 -->
+
 When pipeline agents create issues programmatically (not via user input), use this canonical template. All automated `gh issue create` calls across Forge commands MUST include these mandatory sections. Domain-specific sections are additive — preserve them, but wrap them with this structure.
 
 ```markdown
@@ -488,10 +490,10 @@ Create all {N} issues? (yes / adjust #N / cancel)
 | Bad Issue | Why It Fails | Good Version |
 |-----------|-------------|-------------|
 | "Fix docker mount" | Which compose file? Which mount? | "fix: `.gemini` volume mount in docker-compose.prod.yml missing rw flag" |
-| "Update billing" | What about billing? What's broken? | "fix: credit_service.deduct() raises DivisionByZero when user.credits == 0" |
-| "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in scraping routers" |
+| "Update billing" | What about billing? What's broken? | "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" |
+| "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in job processing routers" |
 | No affected files listed | Investigator guesses wrong files | List every file with what needs to change |
-| "Handle edge case" | Which edge case? In what function? | "fix: unified_consumer.process_job() silently drops jobs when queue.length > MAX_BATCH" |
+| "Handle edge case" | Which edge case? In what function? | "fix: task_processor.process_job() silently drops jobs when queue.length > MAX_BATCH" |
 | Missing override files | Fix is incomplete, deploy fails | Include docker-compose.prod.yml, .env.example, etc. |
 | P0 for a typo fix | Wastes priority signaling | Use P3 for cosmetic issues |