forgedock 1.26.0 → 1.27.0

package/bin/engine/outcome-codes.mjs

@@ -36,9 +36,11 @@ export const OUTCOME_CODES = Object.freeze({
   BASE_CONFLICT: "base.conflict",
   RATE_LIMITED: "rate_limited",
   HOST_BUSY: "host.busy",
+  GH_UNAVAILABLE: "gh.unavailable", // forge#4157: `gh` unreachable after retries during the --repo identity check; run deferred, nothing posted
   MERGE_TRANSIENT: "merge.transient",
   PUSH_TRANSIENT: "push.transient",
   CLI_IDLE: "cli.idle",
+  RUN_INTERRUPTED: "run.interrupted", // forge#4179: SIGTERM/SIGINT on a core run; teardown ran from the ledger, lane requeued
   PATH_SWITCH_CONFLICT: "path.switch_conflict",
   ENGINE_ERROR: "engine.error",
   INFRA_DISK_QUOTA: "infra.disk_quota",
@@ -74,6 +76,7 @@ export const OUTCOME_CODES = Object.freeze({
   CONFORMANCE_UNJUSTIFIED_DEFERRAL: "conformance.unjustified_deferral",
   CONFORMANCE_PRESERVE_VIOLATED: "conformance.preserve_violated",
   CONFORMANCE_REGRESSION: "conformance.regression",
+  STRUCTURE_UNDECLARED_EDGE: "structure.undeclared_edge", // forge#4159: a workspace package.json edge the contract does not name
   FOLLOWUP_UNAVAILABLE: "followup.unavailable",
   MERGE_HEAD_MISMATCH: "merge.head_mismatch",
   // Non-failure terminals, so a RUN_TERMINAL for a healthy run is not counted as a gap.

package/bin/engine/phases.mjs

@@ -349,12 +349,48 @@ export async function openDependency(issue, io) {
       return { unreadable: true, detail: `dependency #${dep} of issue ${issue} could not be read: ${e?.message || e}` };
     }
     const st = typeof d?.state === "string" ? d.state.toLowerCase() : "";
-    if (st === "open") open.push(dep);
+    if (st === "open") {
+      // #4153: an open decomposed parent is a tracker; the edge resolves to its sub-issues (satisfied when all close).
+      const subs = isDecomposedRecord(d) ? await decomposedSubissues(dep, io) : null;
+      if (!subs) { open.push(dep); continue; }
+      for (const s of subs) {
+        let sr;
+        try { sr = await readIssueRecord(s, io); } catch (e) {
+          return { unreadable: true, detail: `sub-issue #${s} of decomposed dependency #${dep} could not be read: ${e?.message || e}` };
+        }
+        const ss = typeof sr?.state === "string" ? sr.state.toLowerCase() : "";
+        if (ss === "open") open.push(s);
+        else if (ss !== "closed") return { unreadable: true, detail: `sub-issue #${s} of decomposed dependency #${dep} has no readable state` };
+      }
+    }
     else if (st !== "closed") return { unreadable: true, detail: `dependency #${dep} of issue ${issue} has no readable state` };
   }
-  return open.length ? { open } : null;
+  return open.length ? { open: [...new Set(open)].filter((n) => n !== Number(issue)) } : null;
 }
 
+/**
+ * #4153: sub-issues of a decomposed parent, from the `- #N` lines of its newest trusted `<!-- FORGE:DECOMPOSED -->`
+ * comment (lean `- #N title` and decompose.md `- #N: title`). `null` when there is none, it lists no issue, it was
+ * revoked, or the trail is unreadable: the caller then keeps the parent as the dependency (fail closed).
+ */
+export async function decomposedSubissues(issue, io) {
+  let comments;
+  try { comments = (await issueMarkers(issue, io)).comments; } catch { return null; }
+  const head = /^\s*<!--\s*FORGE:DECOMPOSED\s*-->/;
+  const revoked = /^\s*<!--\s*FORGE:DECOMPOSED:REVOKED(?![A-Za-z0-9_])/;
+  let rec = null;
+  for (let i = comments.length - 1; i >= 0; i--) {
+    if (revoked.test(comments[i])) return null;
+    if (head.test(comments[i])) { rec = comments[i]; break; }
+  }
+  if (!rec) return null;
+  const subs = [...new Set([...rec.matchAll(/^[ \t]*[-*][ \t]+#(\d+)\b/gm)].map((m) => Number(m[1])))].filter((n) => Number.isSafeInteger(n) && n > 0 && n !== Number(issue));
+  return subs.length ? subs : null;
+}
+
+/** True when a REST/`gh --json` issue record carries the `workflow:decomposed` label. */
+export const isDecomposedRecord = (rec) => (rec?.labels ?? []).some((l) => (l?.name ?? l) === "workflow:decomposed");
+
 /**
  * Decompose loop guard (mirrors decompose.md Guard 1; forge#3676). Returns a
  * short reason string when the issue must NOT be routed to decompose, else null:

package/bin/engine/telemetry-seam.mjs

@@ -5,6 +5,7 @@
  * seam onto FORGE:TELEMETRY events so `forgedock stats` can rebuild Cost, Time and outcome codes from GitHub alone:
  *   PHASE_ATTEMPT_USAGE -> `phase_attempt` (attempt, model, turns, duration_ms, cost_usd, *_tokens)
  *   RUN_TERMINAL        -> `run_terminal`  (reason, code, wall_ms)
+ *   STRUCTURE_DELTA     -> `structure_delta` (edges_added/removed, import_files_added/removed, boundary_changed/loosened 0|1; forge#4159)
  * Other records are ignored. The returned function NEVER throws and honours FORGE_TELEMETRY=off. Telemetry values
  * are scalars (the emitter stringifies objects), so the `usage` object is flattened here; absent values are omitted.
  */
@@ -37,6 +38,11 @@ export function mapRecord(rec, wallMs) {
   if (rec.event === "RUN_TERMINAL") {
     return { event: "run_terminal", phase: null, payload: compact({ reason: rec.reason, code: rec.code, wall_ms: wallMs }) };
   }
+  if (rec.event === "STRUCTURE_DELTA") {
+    const bit = (v) => (typeof v === "boolean" ? Number(v) : v);
+    return { event: "structure_delta", phase: rec.phase ?? "implement", payload: compact({ edges_added: rec.edges_added, edges_removed: rec.edges_removed,
+      import_files_added: rec.import_files_added, import_files_removed: rec.import_files_removed, boundary_changed: bit(rec.boundary_changed), boundary_loosened: bit(rec.boundary_loosened) }) };
+  }
   if (rec.event === "CI_PENDING_WAIT") {
     return { event: "ci_pending_wait", phase: rec.phase ?? "review", payload: compact({ pr: rec.pr, minutes_waited: rec.minutes_waited, result: rec.result, polls: rec.polls, rate_limit_sleeps: rec.rate_limit_sleeps }) };
   }

package/bin/engine/telemetry-seam.test.mjs

@@ -37,6 +37,10 @@ describe("engine telemetry seam", () => {
     assert.deepEqual(calls[0][1], { reason: "needs-human", code: "review.escalated", wall_ms: 60000 });
     assert.equal(calls[0][2].phase, undefined);
   });
+  it("maps STRUCTURE_DELTA (forge#4159) to structure_delta with scalar counts and 0/1 flags", () => {
+    const m = mapRecord({ event: "STRUCTURE_DELTA", issue: 7, edges_added: 1, edges_removed: 0, import_files_added: 8, import_files_removed: 2, boundary_changed: true, boundary_loosened: false }, 10);
+    assert.deepEqual(m, { event: "structure_delta", phase: "implement", payload: { edges_added: 1, edges_removed: 0, import_files_added: 8, import_files_removed: 2, boundary_changed: 1, boundary_loosened: 0 } });
+  });
   it("null usage yields a record with no token fields", () => {
     assert.deepEqual(mapRecord({ event: "PHASE_ATTEMPT_USAGE", phase: "build", attempt: 1, usage: null, duration_ms: 5 }).payload, { attempt: 1, duration_ms: 5 });
   });

package/bin/engine-cli.mjs

@@ -17,7 +17,9 @@ import { assertOpenCodeNativeRuntime } from "./runner.mjs";
 import { parseForgeYaml } from "./forge-utils.mjs";
 import { makeEmitTelemetry } from "./engine/telemetry-seam.mjs";
 import { readBranches, resolveLane, isDefaultLane } from "./lean/lane.mjs";
+import { parseVerify } from "./lean/verify.mjs";
 import { writeAtomic as writeResultAtomic } from "./lean/batch.mjs";
+import { OUTCOME_CODES } from "./engine/outcome-codes.mjs";
 
 /**
  * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
@@ -147,6 +149,16 @@ export function readMergeWait(cwd = process.cwd()) {
     return ["required", "all", "none"].includes(v) ? v : undefined;
   } catch { return undefined; }
 }
+/**
+ * forge.yaml `verify:` section (#4167, block style: `verify:` then `  mode: ci`, `  workflow: verify.yml`, `  paths_input`,
+ * `  skip_paths` comma-separated, `  max_rounds`) for the core path; undefined when the section is absent or unreadable.
+ */
+export function readVerify(cwd = process.cwd()) {
+  try {
+    const sec = parseForgeYaml(readFileSync(join(cwd, "forge.yaml"), "utf8"))?.verify;
+    return sec && typeof sec === "object" ? parseVerify(sec) : undefined;
+  } catch { return undefined; }
+}
 export const ENGINE_PATHS = ["core", "full", "lean", "auto"];
 
 export function runDir() { return join(homedir(), ".forge", "runs"); }
@@ -256,21 +268,36 @@ export function formatTerminalDiagnostics(dir, issue) {
   return lines.join("\n");
 }
 
+// forge#4157: backoff between `gh repo view` attempts. Under host load one call can exceed makeIo's exec timeout.
+export const REPO_VIEW_BACKOFF_MS = [2000, 4000];
+// forge#4157: how long an orchestrate lane waits before rerunning after `gh` stayed unreachable.
+export const GH_UNAVAILABLE_RETRY_S = 60;
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
 /**
  * Resolves the repo `gh` would target by default (i.e. resolved from the cwd
  * git remote), via `gh repo view`. Used to validate an explicit `--repo` flag
- * against the ambient context — see `assertRepoMatchesCwd`.
+ * against the ambient context — see `assertRepoMatchesCwd`. A failed call is
+ * retried with backoff (forge#4157: it is usually a transient timeout under load).
  * @param {{gh: Function}} io
- * @returns {Promise<string|null>} "owner/repo", or null if it can't be determined
+ * @param {{sleep?: (ms:number)=>Promise<void>, detail?: boolean}} [opts] - `detail: true` returns
+ *   `{repo, failed}` so a caller can tell "every attempt errored" from an answer.
+ * @returns {Promise<string|null|{repo:string|null, failed:boolean}>} "owner/repo", or null if it can't be determined
  */
-async function resolveDefaultRepo(io) {
-  try {
-    const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
-    const repo = String(out).trim();
-    return repo || null;
-  } catch {
-    return null;
+async function resolveDefaultRepo(io, { sleep = realSleep, detail = false } = {}) {
+  let failed = false;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const out = await io.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]);
+      const repo = String(out).trim() || null;
+      return detail ? { repo, failed: false } : repo;
+    } catch {
+      failed = true;
+      if (attempt >= REPO_VIEW_BACKOFF_MS.length) break;
+      await sleep(REPO_VIEW_BACKOFF_MS[attempt]);
+    }
   }
+  return detail ? { repo: null, failed } : null;
 }
 
 /**
@@ -298,16 +325,20 @@ export async function assertLaneNotDefault(io, lane, repo = null, cwd = process.
  * default, refuse to run at all rather than silently mixing repos.
  * @param {{gh: Function}} io
  * @param {string|null} repo
+ * @param {{sleep?: Function}} [opts] - backoff seam for the `gh repo view` retries
  * @returns {Promise<void>}
  */
-async function assertRepoMatchesCwd(io, repo) {
+async function assertRepoMatchesCwd(io, repo, { sleep } = {}) {
   if (!repo) return;
-  const defaultRepo = await resolveDefaultRepo(io);
+  const { repo: defaultRepo, failed } = await resolveDefaultRepo(io, { sleep, detail: true });
   if (defaultRepo === null) {
-    throw new Error(
+    const err = new Error(
       `--repo ${repo} was given, but the current repo could not be determined (\`gh repo view\` failed) to ` +
       `verify it matches. Refusing to run cross-repo without verification.`
     );
+    // forge#4157: `gh` kept failing after retries; transient, so run-issue defers instead of erroring.
+    if (failed) err.code = OUTCOME_CODES.GH_UNAVAILABLE;
+    throw err;
   }
   if (defaultRepo !== repo) {
     throw new Error(
@@ -495,7 +526,17 @@ export async function runFromCli(argv, deps = {}) {
   // The full path takes the lane as given (its spec runs classify-lane), so it must be explicit; no default.
   if (enginePath === "full" && !lane) throw new Error("--lane is required with --path full: staging or milestone/<slug>. No default to prevent accidental production targeting.");
   const io = deps.io ?? makeIo();
-  await assertRepoMatchesCwd(io, repo);
+  const resultFile = flag(argv, "--result-file");
+  const report = (r) => { if (resultFile) (deps.writeAtomic ?? writeResultAtomic)(resultFile, JSON.stringify(r) + "\n"); return r; };
+  try {
+    await assertRepoMatchesCwd(io, repo, { sleep: deps.sleep });
+  } catch (e) {
+    if (e?.code !== OUTCOME_CODES.GH_UNAVAILABLE) throw e;
+    // forge#4157: a scheduling fact, not an engine error; the batch requeues it and the breaker never sees it.
+    const res = report({ terminalReason: "deferred", code: OUTCOME_CODES.GH_UNAVAILABLE, detail: e.message, retryInSeconds: GH_UNAVAILABLE_RETRY_S });
+    console.log(`issue #${issue} → deferred (${res.detail})`);
+    return res;
+  }
   await assertLaneNotDefault(io, lane, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
   const agentId = `cli_${sanitizeLeaseHost(hostname())}_${process.pid}`;
@@ -529,14 +570,31 @@ export async function runFromCli(argv, deps = {}) {
     const { runCore } = deps.leanModule ?? (await import("./lean/lean.mjs"));
     const leanIo = deps.leanIo ?? (await import("./lean/effects.mjs")).makeLeanIo({ repo: leanRepo });
     // #4121: a batch lane reports its result through --result-file (written atomically, also for a thrown run).
-    const resultFile = flag(argv, "--result-file");
-    const report = (r) => { if (resultFile) (deps.writeAtomic ?? writeResultAtomic)(resultFile, JSON.stringify(r) + "\n"); return r; };
+    // #4179: SIGTERM/SIGINT run the lane's teardown (ledger, checkpoint, worktree, lease), report deferred run.interrupted, exit 128+signo.
+    let teardown = null, interrupted = false;
+    const on = deps.processOn ?? ((s, f) => process.on(s, f)), off = deps.processOff ?? ((s, f) => process.removeListener(s, f));
+    const exit = deps.exit ?? ((c) => process.exit(c));
+    const SIGNO = { SIGINT: 2, SIGTERM: 15 };
+    const handlers = Object.fromEntries(Object.keys(SIGNO).map((sig) => [sig, async () => {
+      if (interrupted) return;
+      interrupted = true;
+      let r = null;
+      try { r = teardown ? await teardown(sig) : null; } catch { r = null; }
+      try { report({ ...(r ?? {}), terminalReason: "deferred", code: OUTCOME_CODES.RUN_INTERRUPTED, detail: r?.detail ?? `interrupted by ${sig}` }); } catch { /* exit anyway */ }
+      console.log(`issue #${issue} → deferred (interrupted by ${sig})`);
+      exit(128 + SIGNO[sig]);
+    }]));
+    for (const [sig, f] of Object.entries(handlers)) on(sig, f);
+    const env = deps.env ?? process.env;
     let lres;
     try {
       lres = await runCore({ issue, repo: leanRepo, ...(lane ? { lane } : {}), laneOverride, branches: readBranches(), cwd: process.cwd(), dir, io: leanIo, path: enginePath, onProgress,
+      onTeardown: (fn) => { teardown = fn; }, ...(env.FORGEDOCK_BATCH_ID ? { batchId: env.FORGEDOCK_BATCH_ID } : {}),
       emitTelemetry: deps.emitTelemetry ?? makeEmitTelemetry({ repo: leanRepo }),
-      admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
-    } catch (e) { report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
+      admission: readAdmission(), ...readCoreLimits(), ...(readMergeWait() ? { mergeWait: readMergeWait() } : {}), ...(readConformanceMode() ? { conformance: readConformanceMode() } : {}), ...(readVerify() ? { verify: readVerify() } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model") ? { reviewerModel: readLeanSetting("reviewer_model") } : {}) });
+    } catch (e) { if (!interrupted) report({ terminalReason: "engine-error", detail: String(e?.message ?? e).slice(0, 500) }); throw e; }
+    finally { if (!interrupted) for (const [sig, f] of Object.entries(handlers)) off(sig, f); }
+    if (interrupted) return lres; // the signal handler reported and exits
     report(lres);
     if (lres.code === "host.busy") { console.log(`issue #${issue} → deferred (${lres.detail})`); return lres; }
     if (lres.terminalReason === "lane-refused") { console.log(`issue #${issue} → lane-refused ${lres.code} (${lres.detail})`); return lres; }
@@ -629,7 +687,7 @@ export async function resumeStalledFromCli(argv, deps = {}) {
   const repo   = flag(argv, "--repo");
 
   const io = deps.io ?? makeIo();
-  await assertRepoMatchesCwd(io, repo);
+  await assertRepoMatchesCwd(io, repo, { sleep: deps.sleep });
   await assertLaneNotDefault(io, lane, repo);
   const dispatch = deps.dispatch ?? runFromCli;
   const projector = makeProjector(io);
@@ -786,8 +844,8 @@ export async function orchestrateFromCli(argv, deps = {}) {
   if (deps.leanModule) {
     const { runCore } = deps.leanModule;
     const emitTelemetry = deps.emitTelemetry ?? makeEmitTelemetry({ repo });
-    lanes = { adopt: null, runOne: (n, ln) => runCore({ issue: n, repo, lane: ln, laneOverride, branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry,
-      admission: readAdmission(cwd), ...readCoreLimits(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}) }) };
+    lanes = { adopt: null, runOne: (n, ln) => runCore({ issue: n, repo, lane: ln, laneOverride, branches, cwd, dir, io: leanIo, agentId: `orch_${process.pid}_${n}`, emitTelemetry, batchId: batch.id,
+      admission: readAdmission(cwd), ...readCoreLimits(cwd), ...(readMergeWait(cwd) ? { mergeWait: readMergeWait(cwd) } : {}), ...(readConformanceMode(cwd) ? { conformance: readConformanceMode(cwd) } : {}), ...(readVerify(cwd) ? { verify: readVerify(cwd) } : {}), ...(model ? { builderModel: model } : {}), ...(readLeanSetting("reviewer_model", cwd) ? { reviewerModel: readLeanSetting("reviewer_model", cwd) } : {}) }) };
   } else {
     lanes = batchMod.detachedLanes({ batch, cwd, script: deps.laneScript ?? fileURLToPath(new URL("./forgedock.mjs", import.meta.url)), bin: deps.laneBin, pollMs: deps.pollMs,
       laneArgs: (n, ln) => ["--repo", repo, ...(ln ? ["--lane", ln] : []), ...(laneOverride ? ["--lane-override"] : []), ...(model ? ["--model", model] : [])] });

package/bin/engine.mjs

@@ -13,6 +13,7 @@ import { pickPhase, TERMINAL_REASONS, issueSnapshot, hasInvestigationExit, postC
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { VALID_BACKENDS, resolveRunTmpRoot, runTmpDir } from "./runner.mjs";
+import { resolveClaudeConfigDir } from "./journey.mjs";
 import { OUTCOME_CODES, UNCLASSIFIED, normalizeCode, codeForRunnerError, codeForTerminalReason, isDiskQuotaError, isDiskQuotaText, isTransientSpawnError } from "./engine/outcome-codes.mjs";
 
 // Exported (forge#2175) so bin/engine-cli.mjs can render "failed N/M attempts"
@@ -82,7 +83,10 @@ export function ciRateLimitSleepMs(rl, nowMs, rand = Math.random) {
  */
 export function backendIdentity({ backend, env = process.env } = {}) {
   const sha = (s) => createHash("sha256").update(String(s)).digest("hex");
-  const cfg = env.CLAUDE_CONFIG_DIR || `${homedir()}/.claude`;
+  // Shared resolver (forge#4173). The fallback keeps its legacy
+  // `${homedir()}/.claude` spelling so identities recorded before the shared
+  // resolver existed still match on Windows (path.join would use "\\").
+  const cfg = env.CLAUDE_CONFIG_DIR ? resolveClaudeConfigDir(env) : `${homedir()}/.claude`;
   const key = env.ANTHROPIC_API_KEY
     ? scryptSync(String(env.ANTHROPIC_API_KEY), "forgedock-backend-identity", 16).toString("hex") : "";
   return sha(JSON.stringify([backend ?? "auto", cfg, key])).slice(0, 16);

package/bin/forgedock.mjs

@@ -34,6 +34,8 @@ import {
   writeInstallReceipt,
   persistHome,
   PIPELINE_SCRIPTS,
+  resolveClaudeConfigDir,
+  setupAfterRead,
 } from "./journey.mjs";
 import {
   deriveWorkflowLabels,
@@ -176,7 +178,14 @@ const HOME = process.env.HOME || process.env.USERPROFILE || homedir();
 // existing invocations, but it is now a no-op — global is the only supported
 // install location.
 
-const GLOBAL_CLAUDE_DIR = join(HOME, ".claude");
+//
+// The directory itself honours CLAUDE_CONFIG_DIR (forge#4173): Claude Code
+// reads commands/settings from there when it is set, so install, doctor,
+// status and uninstall all resolve it through the one shared helper the
+// journey installer uses — never a hard-coded ~/.claude.
+const GLOBAL_CLAUDE_DIR = resolveClaudeConfigDir(process.env, HOME);
+/** Display form of GLOBAL_CLAUDE_DIR for user-facing messages. */
+const CLAUDE_DIR_LABEL = GLOBAL_CLAUDE_DIR === join(HOME, ".claude") ? "~/.claude" : GLOBAL_CLAUDE_DIR;
 
 /**
  * Resolve the install target directories for the current invocation.
@@ -242,7 +251,7 @@ const restArgs = cmdIdx === -1 ? [] : rawArgs.slice(cmdIdx + 1).filter((a) => a
  * Path to the user-level Claude Code settings file.
  * This is where the SessionStart hook entry is written/removed.
  */
-const CLAUDE_SETTINGS_PATH = join(HOME, ".claude", "settings.json");
+const CLAUDE_SETTINGS_PATH = join(GLOBAL_CLAUDE_DIR, "settings.json");
 
 /**
  * Check whether a hook command string refers to the ForgeDock SessionStart hook.
@@ -1004,6 +1013,11 @@ async function statusScreen(c) {
  * otherwise falls back to the Anthropic API when ANTHROPIC_API_KEY is set,
  * otherwise skips enrichment.
  *
+ * Repository setup (forge#4173): after detection, interactive runs with no
+ * GitHub remote, no commits, or no `staging` branch are offered repo
+ * creation, an initial push of `main`, and `staging` creation — see
+ * journey.mjs setupRepo(). Non-TTY runs are unchanged.
+ *
  * Env:
  *   FORGEDOCK_INIT_BACKEND   Override ("cli"|"api"|"none"|"auto"; default
  *                            "auto") — pins the enrichment backend instead of
@@ -1042,7 +1056,7 @@ async function initFlow(c) {
     // Staging semantics preserved (#1148): detection → minimal template with
     // only the three required sections. No review screen — this is the
     // power-user escape hatch for a ~20-line forge.yaml.
-    const { draft, description } = await read(c);
+    const { draft, description } = await setupAfterRead(c, await read(c));
     // Hard-fail on unresolved identity placeholders when overwriting an
     // existing config (forge#1850 spec item 4) — never destroy a working
     // forge.yaml in favor of one that can't address a repo.
@@ -1071,7 +1085,7 @@ async function initFlow(c) {
 
   if (flags.includes("--manual")) {
     // Manual escape hatch: plain prompts, detection values as defaults.
-    const { draft, description } = await read(c);
+    const { draft, description } = await setupAfterRead(c, await read(c));
     const v = {
       owner: await input("GitHub owner", draft.project.owner.value),
       repo: await input("Repository", draft.project.repo.value),
@@ -1097,7 +1111,7 @@ async function initFlow(c) {
     await maybeOfferDemo(c);
     return 0;
   }
-  const { draft, description } = await read(c);
+  const { draft, description } = await setupAfterRead(c, await read(c));
   const reviewed = await review(c, draft, description);
   celebrate(c, reviewed);
   if (!reviewed.aborted) await maybeOfferDemo(c);
@@ -1110,7 +1124,7 @@ async function uninstall() {
   console.log("");
 
   const { targetDir, scriptsTargetDir, manifestPath } = detectInstallPaths();
-  console.log(`  Mode: global (~/.claude)`);
+  console.log(`  Mode: global (${CLAUDE_DIR_LABEL})`);
   console.log(`  ${dim(getLogoTagline("uninstall"))}`);
   console.log("");
 
@@ -1244,19 +1258,19 @@ async function uninstall() {
 
   // Remove the SessionStart hook from ~/.claude/settings.json via the
   // hardened settings-hook module (never writes through malformed JSON).
-  const settingsJsonPath = join(HOME, ".claude", "settings.json");
+  const settingsJsonPath = CLAUDE_SETTINGS_PATH;
   const { status: hookRemoveResult } = removeSessionStartHook(settingsJsonPath);
   if (hookRemoveResult === "removed") {
     console.log(
-      `  ${GREEN}✔${RESET}  Removed SessionStart hook from ${CYAN}~/.claude/settings.json${RESET}`,
+      `  ${GREEN}✔${RESET}  Removed SessionStart hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`,
     );
   } else if (hookRemoveResult === "absent") {
     console.log(
-      `  ✔  SessionStart hook already absent from ~/.claude/settings.json`,
+      `  ✔  SessionStart hook already absent from ${CLAUDE_DIR_LABEL}/settings.json`,
     );
   } else {
     console.log(
-      `  ${YELLOW}⚠${RESET}  Could not update ~/.claude/settings.json — remove the hook manually.`,
+      `  ${YELLOW}⚠${RESET}  Could not update ${CLAUDE_DIR_LABEL}/settings.json — remove the hook manually.`,
     );
   }
 
@@ -1264,19 +1278,19 @@ async function uninstall() {
   // engine adapter, and SubagentStop annotation verifier.
   const { status: preToolUseRemoveResult } = removePreToolUseHook(settingsJsonPath);
   if (preToolUseRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed PreToolUse enforcement hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed PreToolUse enforcement hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   } else if (preToolUseRemoveResult !== "absent") {
-    console.log(`  ${YELLOW}⚠${RESET}  Could not remove PreToolUse hook — check ${CYAN}~/.claude/settings.json${RESET} manually.`);
+    console.log(`  ${YELLOW}⚠${RESET}  Could not remove PreToolUse hook — check ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET} manually.`);
   }
   const { status: subagentStopRemoveResult } = removeSubagentStopHook(settingsJsonPath);
   if (subagentStopRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   }
   const { status: subagentStopEnforceRemoveResult } = removeSubagentStopEnforceHook(settingsJsonPath);
   if (subagentStopEnforceRemoveResult === "removed") {
-    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop enforcement hook from ${CYAN}~/.claude/settings.json${RESET}`);
+    console.log(`  ${GREEN}✔${RESET}  Removed SubagentStop enforcement hook from ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET}`);
   } else if (subagentStopEnforceRemoveResult !== "absent") {
-    console.log(`  ${YELLOW}⚠${RESET}  Could not remove SubagentStop enforcement hook — check ${CYAN}~/.claude/settings.json${RESET} manually.`);
+    console.log(`  ${YELLOW}⚠${RESET}  Could not remove SubagentStop enforcement hook — check ${CYAN}${CLAUDE_DIR_LABEL}/settings.json${RESET} manually.`);
   }
   console.log("");
 
@@ -2111,6 +2125,44 @@ function resolveLabelsRepo(subArgs) {
   return null;
 }
 
+/** Fixed colors for well-known domain labels (forge#4174); anything else gets DOMAIN_LABEL_DEFAULT_COLOR. */
+const DOMAIN_LABEL_COLORS = {
+  frontend: "1D76DB",
+  backend: "0E8A16",
+  infra: "5319E7",
+  design: "D4C5F9",
+  "legal-gated": "B60205",
+};
+const DOMAIN_LABEL_DEFAULT_COLOR = "EDEDED";
+
+/**
+ * Parse a `--domain a,b,c` value into domain-label entries (forge#4174).
+ * Names are trimmed and deduped (first occurrence wins). An empty name, a name
+ * over 50 characters (GitHub's label-name limit), or a missing value is an
+ * error — the caller exits before any gh call.
+ *
+ * @param {string|undefined} raw - the value after --domain
+ * @returns {{ labels?: Array<{name: string, color: string, description: string}>, error?: string }}
+ */
+function buildDomainLabels(raw) {
+  if (raw === undefined || raw.startsWith("--")) return { error: "--domain needs a comma-separated list, e.g. --domain frontend,backend" };
+  const seen = new Set();
+  const labels = [];
+  for (const part of raw.split(",")) {
+    const name = part.trim();
+    if (!name) return { error: `--domain contains an empty label name: "${raw}"` };
+    if (name.length > 50) return { error: `--domain label name exceeds 50 characters: "${name}"` };
+    if (seen.has(name)) continue;
+    seen.add(name);
+    labels.push({
+      name,
+      color: DOMAIN_LABEL_COLORS[name] ?? DOMAIN_LABEL_DEFAULT_COLOR,
+      description: `Domain: ${name}. Managed by ForgeDock.`,
+    });
+  }
+  return { labels };
+}
+
 /**
  * Idempotently create or update all ForgeDock-managed labels on a GitHub repo.
  *
@@ -2122,10 +2174,15 @@ function resolveLabelsRepo(subArgs) {
  * --force makes the call idempotent: it creates the label if absent, or updates
  * its color and description if it already exists. Safe to re-run at any time.
  *
+ * Optional per-repo domain labels (forge#4174) are appended after the
+ * manifest — see buildDomainLabels(). They are never part of bin/labels.json,
+ * so doctor's required-label check ignores them.
+ *
  * @param {string} repo - "owner/repo" string
+ * @param {Array<{name: string, color: string, description: string}>} [domainLabels]
  * @returns {{ created: number, failed: string[] }}
  */
-async function labelsSetup(repo) {
+async function labelsSetup(repo, domainLabels = []) {
   const manifestPath = join(__dirname, "labels.json");
 
   if (!existsSync(manifestPath)) {
@@ -2141,6 +2198,8 @@ async function labelsSetup(repo) {
     console.log(`${RED}Failed to parse labels.json: ${err.message}${RESET}`);
     process.exit(1);
   }
+  const manifestNames = new Set(labels.map((l) => l.name));
+  labels = labels.concat(domainLabels.filter((l) => !manifestNames.has(l.name)));
 
   console.log("");
   console.log(`${BOLD}ForgeDock Label Bootstrap${RESET}`);
@@ -2210,7 +2269,7 @@ async function labelsSetup(repo) {
  *   2.  gh CLI installed and authenticated
  *   3.  git configured (user.name + user.email)
  *   4.  forge.yaml exists and has required keys
- *   5.  SessionStart hook registered in ~/.claude/settings.json
+ *   5.  SessionStart hook registered in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR)
  *   6.  CLAUDE.md legacy managed block (cwd) — informational only; the
  *       journey install never injects one, session context comes from the
  *       SessionStart hook
@@ -2247,7 +2306,7 @@ async function doctor(fix = false) {
   console.log(
     isGitCloneInstall
       ? `  Mode: git clone at ${CYAN}${FORGE_HOME}${RESET}`
-      : `  Mode: global (~/.claude)`,
+      : `  Mode: global (${CLAUDE_DIR_LABEL})`,
   );
   console.log(`  Source: ${formatSourceIdentity(sourceBranch)}`);
   console.log("");
@@ -2301,7 +2360,7 @@ async function doctor(fix = false) {
     console.log(`  ${CYAN}↻${RESET}  ${BOLD}${label}${RESET}${suffix}`);
   }
 
-  const settingsPath = join(HOME, ".claude", "settings.json");
+  const settingsPath = CLAUDE_SETTINGS_PATH;
 
   /**
    * Detect whether the registered SessionStart hook entry (if any) points at
@@ -2671,17 +2730,17 @@ async function doctor(fix = false) {
     }
 
     if (hookReg.error) {
-      fail("SessionStart hook", `Cannot read ~/.claude/settings.json: ${hookReg.error}. Run: npx forgedock install`);
+      fail("SessionStart hook", `Cannot read ${CLAUDE_DIR_LABEL}/settings.json: ${hookReg.error}. Run: npx forgedock install`);
     } else if (hookReg.ok) {
       if (fix && hookRegWasBroken) {
-        fixed("SessionStart hook", "registered in ~/.claude/settings.json (repaired)");
+        fixed("SessionStart hook", `registered in ${CLAUDE_DIR_LABEL}/settings.json (repaired)`);
       } else {
-        pass("SessionStart hook", "registered in ~/.claude/settings.json");
+        pass("SessionStart hook", `registered in ${CLAUDE_DIR_LABEL}/settings.json`);
       }
     } else {
       fail(
         "SessionStart hook",
-        "Run: npx forgedock doctor --fix  (or: npx forgedock install)  (writes hook entry to ~/.claude/settings.json)",
+        `Run: npx forgedock doctor --fix  (or: npx forgedock install)  (writes hook entry to ${CLAUDE_DIR_LABEL}/settings.json)`,
       );
     }
   }
@@ -3007,7 +3066,7 @@ async function doctor(fix = false) {
   // server presence is orthogonal to the core ForgeDock install — but missing
   // it causes /qa-sweep to silently fail mid-sweep.
   {
-    const mcpServersPath = join(HOME, ".claude", "mcp_servers.json");
+    const mcpServersPath = join(GLOBAL_CLAUDE_DIR, "mcp_servers.json");
     let playwrightFound = false;
     let fileReadable = false;
     let hasMcpServers = false;
@@ -3040,12 +3099,12 @@ async function doctor(fix = false) {
     if (!fileReadable) {
       warn(
         "Playwright MCP",
-        "No MCP servers file found (~/.claude/mcp_servers.json). Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+        `No MCP servers file found (${CLAUDE_DIR_LABEL}/mcp_servers.json). Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest`,
       );
     } else if (!hasMcpServers) {
       warn(
         "Playwright MCP",
-        "MCP servers file found (~/.claude/mcp_servers.json) but it has no 'mcpServers' key. Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest",
+        `MCP servers file found (${CLAUDE_DIR_LABEL}/mcp_servers.json) but it has no 'mcpServers' key. Register Playwright MCP to enable /qa-sweep: claude mcp add playwright npx @playwright/mcp@latest`,
       );
     } else if (playwrightFound) {
       pass("Playwright MCP", "registered in Claude Code MCP servers");
@@ -3214,7 +3273,7 @@ function help() {
     ["npx forgedock gc", "Prune stale per-run scratch dirs under ~/.forge/tmp/runs (older than 6h, owner dead)"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
-    ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
+    ["npx forgedock labels [setup] [--repo owner/repo] [--domain a,b,c]", "Bootstrap ForgeDock-managed labels on a GitHub repo, plus optional per-repo domain labels (idempotent)"],
     ["npx forgedock config migrate [dir]", "Backfill missing optional sections into an existing forge.yaml (idempotent)"],
     ["npx forgedock watch [--repo owner/repo]", "Live per-agent orchestration view (Ctrl+C to exit)"],
     ["npx forgedock report [--days 30] [--md] [--json]", "30-day pipeline impact receipts for your repo"],
@@ -4048,19 +4107,24 @@ switch (command) {
     const subcommand = positional[1];
     if (!subcommand || subcommand === "setup" || subcommand.startsWith("--")) {
       const repo = resolveLabelsRepo(restArgs);
-      if (!repo) {
+      const domainIdx = restArgs.indexOf("--domain");
+      const domain = domainIdx === -1 ? { labels: [] } : buildDomainLabels(restArgs[domainIdx + 1]);
+      if (domain.error) {
+        console.log(`${RED}${domain.error}${RESET}`);
+        exitCode = 1;
+      } else if (!repo) {
         console.log(
           `${RED}No repository specified.${RESET}\n` +
             `  Pass ${cyan("--repo owner/repo")} or run from a directory with ${cyan("forge.yaml")}.`,
         );
         exitCode = 1;
       } else {
-        await labelsSetup(repo);
+        await labelsSetup(repo, domain.labels);
       }
     } else {
       console.log(`${RED}Unknown labels subcommand: ${subcommand}${RESET}`);
       console.log(
-        `Usage: ${CYAN}npx forgedock labels [setup] [--repo owner/repo]${RESET}`,
+        `Usage: ${CYAN}npx forgedock labels [setup] [--repo owner/repo] [--domain a,b,c]${RESET}`,
       );
       exitCode = 1;
     }