forgedock 1.20.0 → 1.21.0

package/bin/runner.mjs

@@ -671,6 +671,23 @@ export function isClaudeCliAvailable(
 // gated on the cached `claude --version` probe, never on help-text scraping.
 const CLI_MIN_VERSION_MODEL_FLAG = [1, 0, 0];
 const CLI_MIN_VERSION_MAX_TURNS_FLAG = [1, 0, 0];
+// forge#4065: minimal phase sessions. Conservative floor: the oldest version
+// known to accept `--strict-mcp-config`, `--mcp-config` and
+// `--disable-slash-commands` together. Unparseable/older => flags omitted.
+const CLI_MIN_VERSION_MINIMAL_SESSION = [2, 1, 296];
+
+// Phase commands whose spec never invokes `Skill(...)`; only these run with
+// `--disable-slash-commands` (spec-coverage test enforces the invariant).
+export const SKILL_FREE_PHASE_COMMANDS = Object.freeze(["work-on/investigate", "work-on/close"]);
+
+// Engine phase commands (mirrors PHASES in bin/engine/phases.mjs; a test enforces it). Only these
+// get the minimal-session group: other `forgedock run` commands (qa-sweep, analytics, geo-audit,
+// autopilot) may need the operator's MCP servers and skills.
+export const ENGINE_PHASE_COMMANDS = Object.freeze([
+  "work-on/investigate", "work-on/decompose", "work-on/build", "work-on/review", "work-on/remediate", "work-on/close",
+]);
+
+const MINIMAL_SESSION_MCP_CONFIG = '{"mcpServers":{}}';
 
 /**
  * Extract a `major.minor.patch` version from probe output (the text after the
@@ -702,7 +719,7 @@ function versionAtLeast(version, min) {
  *
  * @param {string} [cwd]
  * @param {object} [opts] - Forwarded to `isClaudeCliAvailable()` (test seams).
- * @returns {{model: boolean, maxTurns: boolean}}
+ * @returns {{model: boolean, maxTurns: boolean, strictMcp: boolean, disableSlash: boolean}}
  */
 export function getClaudeCliCapabilities(cwd = process.cwd(), opts = {}) {
   isClaudeCliAvailable(cwd, opts);
@@ -710,9 +727,53 @@ export function getClaudeCliCapabilities(cwd = process.cwd(), opts = {}) {
   return {
     model: versionAtLeast(version, CLI_MIN_VERSION_MODEL_FLAG),
     maxTurns: versionAtLeast(version, CLI_MIN_VERSION_MAX_TURNS_FLAG),
+    strictMcp: versionAtLeast(version, CLI_MIN_VERSION_MINIMAL_SESSION),
+    disableSlash: versionAtLeast(version, CLI_MIN_VERSION_MINIMAL_SESSION),
   };
 }
 
+/**
+ * Build the minimal-session argv group (forge#4065): no operator MCP servers
+ * and, for Skill-free phases only, no slash-command/skill listing. Operator
+ * settings are deliberately NOT skipped (the CLI setting-sources flag is not passed) so
+ * ForgeDock's user-scope PreToolUse/SubagentStop hooks keep running.
+ * Non-engine commands, `FORGEDOCK_FULL_SESSION=1` (exactly) or an unsupported CLI yield `[]`.
+ *
+ * @param {string} commandName
+ * @param {{strictMcp: boolean, disableSlash: boolean}} caps
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+export function buildMinimalSessionFlags(commandName, caps, env = process.env) {
+  if (env?.FORGEDOCK_FULL_SESSION === "1" || !caps) return [];
+  const name = String(commandName ?? "").trim().replace(/^\/+/, "").replace(/\.md$/i, "");
+  if (!ENGINE_PHASE_COMMANDS.includes(name)) return [];
+  const flags = [];
+  if (caps.strictMcp) flags.push("--strict-mcp-config", "--mcp-config", MINIMAL_SESSION_MCP_CONFIG);
+  if (caps.disableSlash && SKILL_FREE_PHASE_COMMANDS.includes(name)) flags.push("--disable-slash-commands");
+  return flags;
+}
+
+/**
+ * Lean-path (#4081) minimal session flags: reuses the #4065 capability probe. Every phase is Skill-free, so slash
+ * commands are off too; user-scope settings and hooks still load. Unsupported CLI or FORGEDOCK_FULL_SESSION=1 yields [].
+ */
+export function buildLeanSessionFlags(caps, env = process.env) {
+  // Same group as the Skill-free engine phases (no MCP, no slash commands). Operator settings stay loaded so the
+  // user-scope safety hooks keep running, exactly like #4077.
+  return buildMinimalSessionFlags("work-on/investigate", caps, env);
+}
+
+/**
+ * Read-only reviewer tools (#4081): only Read, Grep and Glob. Uses `--tools` where the capability probe says the
+ * CLI is recent enough, else denies the mutating tools with `--disallowedTools`.
+ */
+export function buildReadOnlyToolFlags(caps) {
+  return caps?.strictMcp
+    ? ["--tools", "Read,Grep,Glob"]
+    : ["--disallowedTools", "Bash", "Edit", "Write", "MultiEdit", "NotebookEdit"];
+}
+
 /**
  * Return the exact absolute `claude` executable path that
  * `isClaudeCliAvailable()` validated for `cwd` (issue #2741), ensuring the
@@ -1443,6 +1504,9 @@ export function runCliBackend({
   model = null,
   maxTurns = null,
   leaseHolder = null,
+  sessionFlags = [],
+  // #4081: extra argv (e.g. ["--resume", id]) appended verbatim, never dropped by FORGEDOCK_FULL_SESSION.
+  extraArgs = [],
 }) {
   // forge#3589: opt-in flags, validated again here as defence in depth. Callers
   // (runCommand) are responsible for the version gate. Unset -> argv unchanged.
@@ -1451,6 +1515,12 @@ export function runCliBackend({
   const optionalFlags = [
     ...(modelFlag ? ["--model", modelFlag] : []),
     ...(maxTurnsFlag ? ["--max-turns", String(maxTurnsFlag)] : []),
+    // forge#4065: minimal-session group, built by buildMinimalSessionFlags().
+    // Re-checked here so FORGEDOCK_FULL_SESSION=1 always wins.
+    ...(process.env.FORGEDOCK_FULL_SESSION === "1" || !Array.isArray(sessionFlags)
+      ? []
+      : sessionFlags.map(String)),
+    ...(Array.isArray(extraArgs) ? extraArgs.map(String) : []),
   ];
   const rawTimeout = parseInt(process.env.FORGEDOCK_CLI_TIMEOUT_MS, 10);
   const configuredTimeout = resolveConfiguredCliTimeout(cwd);
@@ -1738,6 +1808,7 @@ export function runCliBackend({
     // bin/batch-runner.mjs's `tokenCost()` (`input + output`).
     const stdoutTrimmed = stdout.trim();
     let parsedResult = null;
+    let sessionId = null;
     let usage = null;
     let turns = null;
     // forge#3696: envelope cost/duration per attempt (null when absent or non-finite).
@@ -1750,6 +1821,7 @@ export function runCliBackend({
         if (Number.isFinite(parsed.total_cost_usd)) costUsd = parsed.total_cost_usd;
         if (Number.isFinite(parsed.duration_ms)) durationMs = parsed.duration_ms;
         parsedResult = typeof parsed.result === "string" ? parsed.result : null;
+        if (typeof parsed.session_id === "string" && parsed.session_id) sessionId = parsed.session_id;
         if (parsed.usage && typeof parsed.usage === "object") {
           usage = {
             input_tokens: toFiniteUsageNumber(parsed.usage.input_tokens),
@@ -1835,6 +1907,7 @@ export function runCliBackend({
       turns,
       costUsd,
       durationMs,
+      sessionId,
       backend: "cli",
       // forge#3521: the phase's final reply (the CLI envelope's `.result`), so
       // callers can read its structured `*_RESULT` block. Additive; "" when absent.
@@ -2715,10 +2788,13 @@ export async function runCommand(opts = {}) {
       : null;
     let cliModel = commandSettings.model ?? runLevelModel;
     let cliMaxTurns = commandSettings.maxTurns;
-    if (resolvedBin && (cliModel || cliMaxTurns)) {
+    // forge#4065: minimal phase session flags, computed per call (never cached).
+    let sessionFlags = [];
+    if (resolvedBin) {
       const caps = getClaudeCliCapabilities(cwd);
       if (cliModel && !caps.model) cliModel = null;
       if (cliMaxTurns && !caps.maxTurns) cliMaxTurns = null;
+      sessionFlags = buildMinimalSessionFlags(commandName, caps);
     }
     if (!resolvedBin && backend === "auto") {
       resolvedBackend = "api";
@@ -2741,6 +2817,7 @@ export async function runCommand(opts = {}) {
           model: cliModel,
           maxTurns: cliMaxTurns,
           leaseHolder,
+          sessionFlags,
         },
       });
     }

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

@@ -842,11 +842,18 @@ DEGRADED_CHECKS="${DEGRADED_CHECKS:-}"
 GATE_STATUS=$([ "$GATE_PASSED" != "true" ] && echo FAIL || { [ -n "$DEGRADED_CHECKS" ] && echo DEGRADED || echo PASS; })
 # Bind the PASS to what was actually gated: the staged tree is exactly the tree the V5 commit will have.
 # scripts/verify-phase-trail.sh --head-tree (work-on/review.md R1.5) rejects a PASS recorded for a different tree. <!-- Added: forge#3149 -->
-git -C {WORKTREE_PATH} add -u   # same staging as the commit below; valid only because V2-V4 are done
-GATE_TREE=$(git -C {WORKTREE_PATH} write-tree)
-# Marker-only re-gate (invoked by work-on/review.md after a base sync or a stale re-review): HEAD is already committed and
-# the index is clean, so the gated tree is HEAD's tree. Use it instead of write-tree, and post the marker only (no V5 Step 2 commit).
-[ "${REGATE_MERGED_HEAD:-}" = "1" ] && GATE_TREE=$(git -C {WORKTREE_PATH} rev-parse 'HEAD^{tree}')
+if [ "${REGATE_MERGED_HEAD:-}" = "1" ]; then
+  # Marker-only re-gate (invoked by work-on/review.md after a base sync or a stale re-review): HEAD is already committed, so the
+  # gated tree must be HEAD's tree. Never stage here: require a clean worktree so no uncommitted fix sits outside the marked tree.
+  if [ -n "$(git -C {WORKTREE_PATH} status --porcelain --untracked-files=no)" ]; then
+    echo "QUALITY_GATE: marker-only re-gate needs a clean worktree (uncommitted tracked changes) - commit the fix, re-run the scoped V1 gate on the committed head, then re-run this step; not posting a marker" >&2
+    exit 1
+  fi
+  GATE_TREE=$(git -C {WORKTREE_PATH} rev-parse 'HEAD^{tree}')
+else
+  git -C {WORKTREE_PATH} add -u   # same staging as the commit below; valid only because V2-V4 are done
+  GATE_TREE=$(git -C {WORKTREE_PATH} write-tree)
+fi
 [ -n "$GATE_TREE" ] || { echo "QUALITY_GATE: tree unresolved - not posting a marker" >&2; exit 1; }
 QG_BODY="<!-- FORGE:QUALITY_GATE -->
 ## Quality Gate Result
@@ -860,7 +867,7 @@ QG_BODY="<!-- FORGE:QUALITY_GATE -->
 gh issue comment {NUMBER} {GH_FLAG} --body "$QG_BODY" # allowlist:check-command-side-effects
 ```
 
-**Marker-only re-gate mode** <!-- Added: forge#3983 -->: when `work-on/review.md` re-gates a merged head (Pre-Handoff Base Sync or stale re-review), it runs the scoped V1 gate on the committed head first, then sets `REGATE_MERGED_HEAD=1` and runs only this Step 1 with the real `GATE_RESULT` (FAIL stays FAIL). Steps 2-4 are skipped: there is nothing staged and no commit to make.
+**Marker-only re-gate mode** <!-- Added: forge#3983 -->: when `work-on/review.md` re-gates a merged head (Pre-Handoff Base Sync or stale re-review), it runs the scoped V1 gate on the committed head first, then sets `REGATE_MERGED_HEAD=1` and runs only this Step 1 with the real `GATE_RESULT` (FAIL stays FAIL). Steps 2-4 are skipped: there is nothing staged and no commit to make. **Precondition**: a clean worktree (no uncommitted tracked changes, untracked files ignored); a dirty tracked file or staged change exits 1 with no marker, so a fix made after a FAIL must be committed and the scoped V1 gate re-run on the committed head before this step is re-run, keeping the gated tree equal to the marked `HEAD^{tree}`.
 
 ### V5 Step 2: Commit
 

package/commands/work-on/review.md

@@ -205,7 +205,7 @@ On conflict, resolve every file, keep both sides' intent, `git add`, `git commit
 **Re-gate the merged head** <!-- Added: forge#3983 -->: the `FORGE:QUALITY_GATE` PASS is bound to `HEAD^{tree}` (R1.5 `--head-tree`), so a merge that changes the tree invalidates it. After the merge and any conflict resolution, compare `PRE_SYNC_TREE` with the current `HEAD^{tree}` (fail closed if either cannot be resolved):
 
 - Unchanged: do nothing; never re-gate.
-- Changed: run the scoped quality gate on the merged head here (`work-on/build/validate` V1 loop over the PR's changed files), then post the marker via validate.md V5 Step 1 "Marker-only re-gate mode" (`**Tree**` = merged `HEAD^{tree}`, `**Commands run**` = what ran). Post the real result: on FAIL, fix and re-run within the validate bounds, else add `needs-human` and return `REVIEW_RESULT: status: BLOCKED`, blocker "post-sync quality gate failed"; never post PASS without a run.
+- Changed: run the scoped quality gate on the merged head here (`work-on/build/validate` V1 loop over the PR's changed files), then post the marker via validate.md V5 Step 1 "Marker-only re-gate mode" (`**Tree**` = merged `HEAD^{tree}`, `**Commands run**` = what ran). Post the real result: on FAIL, fix, commit the fix (marker-only mode requires a clean worktree so the re-gated tree is the committed `HEAD^{tree}`), and re-run within the validate bounds, else add `needs-human` and return `REVIEW_RESULT: status: BLOCKED`, blocker "post-sync quality gate failed"; never post PASS without a run.
 
 ## Phase R1: Pre-Push Ancestry Guard
 

package/docs/CONFIG.md

@@ -481,6 +481,7 @@ engine:
 | `<key>_model` | string | No | Model alias (`sonnet`, `opus`, `haiku`) or full model id passed as `--model`. Invalid values are ignored. |
 | `<key>_max_turns` | integer | No | Positive integer passed as `--max-turns`. Invalid values are ignored. |
 
+| `path` | string | No | `full` (default), `lean` or `auto`. The lean path (#4081, `bin/lean/`) runs validate, architect and implement in one warm builder session, deterministic gates, one independent reviewer and a no-model merge; `auto` uses it unless the risk tier is high and the diff is large. The `--path` flag overrides. `lean_reviewer_model` sets the reviewer model (default `claude-sonnet-5-5`); the builder uses `--model` or the CLI default. |
 | `ci_pending_max_minutes` | integer | No | Minutes the engine waits for CI when the review phase ends BLOCKED with "checks still pending", or the remediate phase holds at its M7 re-gate on "CI pending" (the merge gate's wait window ended while CI was still running). Default: 90. Invalid values are ignored. This key is flat like the others but is not part of the `<key>_model` / `<key>_max_turns` pattern. |
 
 **CI still pending**: the engine polls `scripts/wait-ci-green.sh` (no model calls) one read per poll on a 60 s, 2 min, 4 min, 5 min (cap) backoff with +/-20% jitter, while the lease keeps renewing, then re-dispatches the phase that was waiting, review or remediate (idempotent at an unchanged head: review re-runs the merge gate and merges; remediate resumes at its M7 re-gate). Before each poll it reads `gh api rate_limit` (not itself rate-limited) and, below 10% of the REST budget, sleeps until the window resets instead of polling; a rate-limited or transient (5xx, network) poll is retried and never re-dispatches the phase. Red CI takes the normal ci-gate path. When the budget is exhausted the run ends `needs-human` with outcome code `review.ci_pending_timeout`; `--retry` resumes. Each wait emits a `ci_pending_wait` telemetry event (`docs/TELEMETRY.md`) with the minutes waited, polls made and rate-limit sleeps.
@@ -493,6 +494,8 @@ engine:
 
 **Per-run scratch dir** (`tmp_root`): every engine child runs with `TMPDIR` and `CLAUDE_CODE_TMPDIR` set to `<tmp_root>/<repo-key>/<issue>` so venvs and Claude session data stay off a size-limited `/tmp`. `engine.tmp_root` is an absolute or `~`-prefixed path; default `~/.forge/tmp`. The `<repo-key>` is the checkout's directory name plus 8 hex characters of a hash of its real path, so the same issue number in two repos never shares a dir; the dir is created `0700` and an existing symlink or dir owned by another user is not used (the child keeps the inherited tmp). Old `<tmp_root>/<issue>` dirs from earlier versions are not migrated. When `tmp_root` is unset and the operator already exported `TMPDIR` or `CLAUDE_CODE_TMPDIR`, that choice is respected and never cleaned. The dir is removed on a terminal outcome and kept on `engine-error` so `--retry` resumes. A disk-full/quota failure (EDQUOT, ENOSPC, errno -28/-122) ends a retryable `engine-error` (outcome code `infra.disk_quota`), never `needs-human`.
 
+**Minimal phase sessions** (forge#4065): on a supported CLI (`claude --version` >= 2.1.296, probed once and cached like the flags above) every engine phase (`work-on/*`) runs with `--strict-mcp-config --mcp-config '{"mcpServers":{}}'`, so operator MCP servers and connectors are not loaded. Phases whose spec never calls `Skill(...)` (`work-on/investigate`, `work-on/close`) also get `--disable-slash-commands`; skill-using phases keep skills. Operator settings are intentionally not skipped (no `--setting-sources`), because ForgeDock's user-scope PreToolUse/SubagentStop hooks must keep running. Set `FORGEDOCK_FULL_SESSION=1` to restore the previous full session (no flags). Other `forgedock run` commands (qa-sweep, analytics, geo-audit, autopilot) keep the full session because they may need MCP servers. An old or unparseable CLI version also omits the flags.
+
 **Commands that use this section**: CLI backend (`runCommand` in `bin/runner.mjs`)
 
 ---

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,12 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Lean path engine (#4081)
+
+`forgedock run-issue N --lane L --path lean|full|auto` (or `engine.path` in forge.yaml; default `full`) runs validate, architect and implement in one warm, minimal builder session, then deterministic gates (a test-file change unless docs-only, ci-local), one independent Sonnet reviewer (plus a security reviewer for auth, crypto, secret, permission, migration, payment or workflow paths), then PR, remote CI wait, merge and close with no model. Gate failures and blocking findings (CRITICAL/HIGH, or CONFIRMED MEDIUM introduced) resume the same builder session with `--resume`, at most 2 rounds each, then `needs-human`; a blocking round is followed by one delta re-review. Non-blocking findings are listed in `FORGE:REVIEW` and never filed. Each stage posts `FORGE:VALIDATE`, `FORGE:PLAN`, `FORGE:IMPLEMENT`, `FORGE:REVIEW`, `FORGE:CLOSE`; telemetry is one `phase_attempt` per stage plus `run_terminal`. `auto` goes lean unless the risk tier is high and the diff is large, in which case it falls back to `full`. Slow CI is polled with backoff and ends `ci-pending` (resumable), never `needs-human`. See docs/CONFIG.md (`engine.path`).
+
+Action: none; the default path is unchanged.
+
 ## v1.19.1: build-time self-review, ci-local under concurrency, review roster gates
 
 - **Build-time self-review (B5.6, #3971).** After implement, the risk-tier review roster's domain agents review the staged diff, and the builder fixes CONFIRMED/LIKELY findings at MEDIUM or above in one repair round before validate. Small or docs-only diffs skip. Each build that runs it spends extra reviewer tokens, which the official review should save back through fewer findings and remediation rounds. Off switch: `FORGE_SELFREVIEW=off`. Wait budget: `SELFREVIEW_WAIT_SECS` (default 600, max 1800). Telemetry: `build_selfreview`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -48,7 +48,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bash scripts/with-run-tmpdir.sh node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"bin/stats/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
+    "test": "bash scripts/with-run-tmpdir.sh node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"bin/stats/**/*.test.mjs\" \"bin/lean/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
     "test:sh": "bash scripts/run-shell-tests.sh",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",