forgedock 1.26.0 → 1.27.0

package/commands/forgedock-init.md

@@ -1,6 +1,6 @@
 ---
 description: AI-powered forge.yaml config generator — scans codebase, queries GitHub, auto-fills all optional sections from detection
-argument-hint: "[--preserve | --interactive | --section <name>]"
+argument-hint: "[--preserve | --interactive | --section <name> | --domain-labels <a,b,c>]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -23,13 +23,15 @@ You complete the `forge.yaml` configuration that `npx forgedock init` started. T
 | (none) | Fill all optional sections — overwrite existing values with newly detected ones, skip sections with nothing detected |
 | `--preserve` | Keep existing active section values unchanged — only fill sections that are not yet configured |
 | `--interactive` | Ask confirmation for every detected value and present menus for optional features |
-| `--section <name>` | Fill only one section: `repos`, `project_board`, `services`, `review`, or `verification` |
+| `--section <name>` | Fill only one section: `repos`, `project_board`, `services`, `review`, `verification`, or `labels` |
+| `--domain-labels <a,b,c>` | Domain labels to bootstrap on the repo (e.g. `frontend,backend,infra,design,legal-gated`) in addition to `bin/labels.json`. Overrides the list Phase 5E derives from the spec. |
 
 Parse `$ARGUMENTS` and set:
 ```
 PRESERVE = true if --preserve present
 INTERACTIVE = true if --interactive present (restores full questionnaire behavior for all sections)
 TARGET_SECTION = value from --section <name>, or "all"
+DOMAIN_LABELS = value from --domain-labels <a,b,c>, or "" (derived in Phase 5E)
 ```
 
 If both `--preserve` and `--interactive` are present, `--interactive` takes precedence (`PRESERVE = false`).
@@ -37,7 +39,7 @@ If both `--preserve` and `--interactive` are present, `--interactive` takes prec
 If `--section` was provided, validate the value immediately:
 
 ```bash
-ALLOWED_SECTIONS="repos project_board services review verification"
+ALLOWED_SECTIONS="repos project_board services review verification labels"
 if [ "$TARGET_SECTION" != "all" ]; then
   VALID=false
   for s in $ALLOWED_SECTIONS; do
@@ -46,7 +48,7 @@ if [ "$TARGET_SECTION" != "all" ]; then
   if [ "$VALID" = "false" ]; then
     echo "Error: '$TARGET_SECTION' is not a valid section name."
     echo ""
-    echo "Valid sections: repos, project_board, services, review, verification"
+    echo "Valid sections: repos, project_board, services, review, verification, labels"
     echo ""
     echo "Usage: /forgedock-init --section <name>"
     exit 1
@@ -248,6 +250,17 @@ Build `DETECTED_ANALYTICS` list from findings:
 - `DETECTED_GA4=true` if GA4 references found
 - If none found, `DETECTED_ANALYTICS_EMPTY=true`
 
+### 2G: Boundary config check
+
+Core work-on blocks a new package.json dependency between workspace packages that its contract does not name, and only reports import growth along existing ones (`scripts/structure-delta.sh`). An allow-all boundary rule makes that report the only signal, so suggest tightening it once.
+
+```bash
+# eslint-plugin-boundaries, dependency-cruiser, Nx depConstraints (repo root only)
+ls "$REPO_ROOT"/.eslintrc* "$REPO_ROOT"/eslint.config.* "$REPO_ROOT"/.dependency-cruiser.* "$REPO_ROOT"/nx.json 2>/dev/null | head -10
+```
+
+Read each file found. Set `BOUNDARY_ALLOW_ALL=true` when a rule allows everything: an eslint-plugin-boundaries rule `{ from: [X], allow: ['*'] }` (or an `allow` list naming every element type), a dependency-cruiser config with no `forbidden` rules, or Nx `onlyDependOnLibsWithTags: ['*']`. Record the file and the rule as `BOUNDARY_ALLOW_ALL_AT`. Suggestion only: never edit the config. If no config is found, or the rules are scoped, leave it unset.
+
 ---
 
 ## Phase 3: GitHub Queries
@@ -262,6 +275,28 @@ gh auth status 2>&1
 
 If not authenticated, skip all GitHub queries and note which sections will need manual completion.
 
+**Projects v2 scope check.** Board discovery and creation need the `read:project` (read) or `project` (read + write) OAuth scope, which `gh auth login` does not grant by default. Without it, `gh project list` fails — and that failure must NOT be reported as "zero boards":
+
+```bash
+BOARD_SCOPE_MISSING=false
+SCOPES=$(gh auth status 2>&1 | grep -i "Token scopes:" || true)
+# Classic OAuth tokens list their scopes; a token with neither project scope cannot touch boards.
+if [ -n "$SCOPES" ] && ! echo "$SCOPES" | grep -qE "'(read:)?project'"; then
+  BOARD_SCOPE_MISSING=true
+fi
+# Fine-grained / App tokens list no scopes — probe instead and match the missing-scope error.
+if [ "$BOARD_SCOPE_MISSING" = "false" ] && gh project list --owner "$OWNER" --limit 1 2>&1 >/dev/null | grep -qiE "required scopes|read:project|INSUFFICIENT_SCOPES"; then
+  BOARD_SCOPE_MISSING=true
+fi
+if [ "$BOARD_SCOPE_MISSING" = "true" ]; then
+  echo "Your GitHub token lacks the read:project/project scope needed for Projects v2 boards."
+  echo "Grant it, then re-run /forgedock-init --section project_board:"
+  echo "  gh auth refresh -h github.com -s read:project,project"
+fi
+```
+
+When `BOARD_SCOPE_MISSING=true`, skip Phases 3B, 3C, 4B and 5F; the Phase 5D summary shows `✗ project_board — token lacks read:project/project scope (run: gh auth refresh -h github.com -s read:project,project)`. Label bootstrap (Phase 5E) does not need this scope and still runs.
+
 ### 3B: Project board discovery
 
 ```bash
@@ -312,6 +347,7 @@ Store results in `SIBLING_REPOS`. Assess satellite signals for each repo — str
 - **Auto-detected value** → use it directly. No confirmation prompt.
 - **Genuine ambiguity** (e.g., multiple project boards, multiple candidates for the same field) → ask once with the detected candidates listed.
 - **Nothing detected** → skip the section silently. Do NOT offer a menu or ask "do you want X?".
+  Exception: `project_board` — with no board found, Phase 4B offers to create one (a new project has none to detect).
 - **`--interactive` flag** → override the above and ask confirmation/selection for every section, even when detection found a clear answer.
 
 ### 4A: repos section
@@ -346,8 +382,16 @@ Store results in `SIBLING_REPOS`. Assess satellite signals for each repo — str
 
   Which board should ForgeDock use? Enter number, or press Enter to skip:
   ```
-- Zero project boards found AND `INTERACTIVE=false` → skip this section silently.
-- `INTERACTIVE=true` → present all boards and ask which one to use.
+- Zero project boards found → offer to create one (Phase 5F provisions it after `forge.yaml` is written):
+  ```
+  No Projects v2 board found under {OWNER}.
+  Create "{REPO} ForgeDock" with the ForgeDock fields (Status, Lane, Priority, Workflow, Component) and link it to {OWNER}/{REPO}? [Y/n]
+  ```
+  Set `BOARD_ACTION=create` on yes, else skip the section.
+- Board(s) found but you are linking, not auto-using one (multiple boards, or `INTERACTIVE=true`) → the menu above also offers `[n] Create a new "{REPO} ForgeDock" board`. Picking an existing board sets `BOARD_ACTION=link`; picking new sets `BOARD_ACTION=create`. The single auto-used board is `BOARD_ACTION=link`.
+- `BOARD_SCOPE_MISSING=true` (Phase 3A) → skip; the scope hint was already printed.
+
+Whichever path is taken, Phase 5F makes sure the board has every ForgeDock field before the `project_board` IDs are written.
 
 ### 4C: services section
 
@@ -453,6 +497,7 @@ project_board:
     lane:
       fast: "{FAST_OPTION_ID}"
       feature: "{FEATURE_OPTION_ID}"
+      sync: "{SYNC_OPTION_ID}"
     priority:
       p0: "{P0_OPTION_ID}"
       p1: "{P1_OPTION_ID}"
@@ -562,6 +607,69 @@ forge.yaml updated:
 
 If nothing changed for an overwritten section (detected values match existing values), show `(no change)` instead of a diff.
 
+Add one line for each provisioning step below, e.g. `✓ project_board — created "Acme ForgeDock" (#3), linked to acme/app, 4 fields added` and `✓ labels — 36 ForgeDock labels + domain labels: frontend, backend`.
+
+### 5E: Bootstrap labels (after forge.yaml is written)
+
+Runs on every invocation unless `--section` targets some other section. With `--preserve` it still runs: label creation is idempotent.
+
+**Domain labels.** If `DOMAIN_LABELS` was supplied (`--domain-labels`), use it verbatim. Otherwise derive it from the spec — the Phase 2 scan, `CLAUDE.md` and `README.md`:
+- web/UI framework (React, Next.js, Vue, Svelte, Angular, `app/`/`frontend/` dirs) → `frontend`
+- server/API code (Express, FastAPI, Django, Rails, Go/Rust services, `api/`/`backend/`/`server/` dirs) → `backend`
+- `Dockerfile`, `docker-compose*`, Terraform, Kubernetes/Helm manifests, deployment workflows → `infra`
+- a design system, Figma links, Storybook, or `design/` dir → `design`
+- legal, compliance, licensing or regulatory gating described in the spec → `legal-gated`
+
+Ask once — listing the derived names — only when the spec is ambiguous (or `INTERACTIVE=true`); otherwise use the derived list directly. An empty list is fine.
+
+```bash
+if [ -n "$DOMAIN_LABELS" ]; then
+  npx forgedock labels setup --repo "${OWNER}/${REPO}" --domain "$DOMAIN_LABELS"
+else
+  npx forgedock labels setup --repo "${OWNER}/${REPO}"
+fi
+```
+
+This creates or updates every label in `bin/labels.json` plus one `Domain: <name>` label per domain name (known domains get fixed colors). Failures are reported, not fatal.
+
+### 5F: Create or link the Projects v2 board (after forge.yaml is written)
+
+Run only when Phase 4B set `BOARD_ACTION` (and `BOARD_SCOPE_MISSING=false`).
+
+**Create** (`BOARD_ACTION=create`):
+```bash
+CREATED=$(gh project create --owner "$OWNER" --title "${REPO} ForgeDock" --format json)
+PROJECT_NUMBER=$(echo "$CREATED" | jq -r '.number')
+PROJECT_ID=$(echo "$CREATED" | jq -r '.id')
+```
+
+**Link** to the repo (both actions; idempotent — an "already linked" error is fine):
+```bash
+gh project link "$PROJECT_NUMBER" --owner "$OWNER" --repo "${OWNER}/${REPO}" 2>/dev/null || true
+```
+
+**Ensure ForgeDock fields.** `Status` is built into every Projects v2 board (Todo / In Progress / Done) — map it, never create it. Create each other field that is missing (case-insensitive name match):
+
+```bash
+EXISTING=$(gh project field-list "$PROJECT_NUMBER" --owner "$OWNER" --format json | jq -r '.fields[].name | ascii_downcase')
+COMPONENT_OPTIONS="${DOMAIN_LABELS:-core}"
+# One "field name|comma-separated options" row per ForgeDock field
+while IFS='|' read -r FIELD_NAME FIELD_OPTIONS; do
+  echo "$EXISTING" | grep -qx "$(echo "$FIELD_NAME" | tr '[:upper:]' '[:lower:]')" && continue
+  gh project field-create "$PROJECT_NUMBER" --owner "$OWNER" --name "$FIELD_NAME" \
+    --data-type SINGLE_SELECT --single-select-options "$FIELD_OPTIONS"
+done <<EOF
+Lane|Fast,Feature,Sync
+Priority|P0,P1,P2,P3
+Workflow|Investigating,Building,In Review,Merged
+Component|${COMPONENT_OPTIONS}
+EOF
+```
+
+Component options come from the Phase 5E domain-label list (fallback `core`), so board components and domain labels line up.
+
+**Write the IDs.** Re-run the Phase 3C field/option queries against `PROJECT_NUMBER`, then write the `project_board` section (Phase 5B schema) into `forge.yaml`, replacing any previous `project_board` block, and keep `forge.yaml.bak` from 5D. If any `gh project` call fails with a missing-scope error, print `gh auth refresh -h github.com -s read:project,project` and stop this step.
+
 ---
 
 ## Phase 6: Validation
@@ -626,6 +734,9 @@ forge.yaml is ready.
 Validation results:
   {validation output from 6A–6D}
 
+Board:  {created "{TITLE}" (#{N}) | linked "{TITLE}" (#{N}) | skipped — token lacks read:project/project scope, run: gh auth refresh -h github.com -s read:project,project}
+Labels: {N} ForgeDock labels + domain labels: {DOMAIN_LABELS or "none"}
+
 Next steps:
   1. If forge.yaml contains sensitive paths (credentials file, local paths):
        echo "forge.yaml" >> .gitignore
@@ -633,6 +744,7 @@ Next steps:
        /work-on next
   3. If any WARNING appeared above, edit forge.yaml to fix the flagged values.
   4. Backup file: forge.yaml.bak (delete when satisfied)
+  {If BOUNDARY_ALLOW_ALL (2G): "5. Your boundary config allows every package to import every package ({BOUNDARY_ALLOW_ALL_AT}). Consider tightening it per package once its design settles: core work-on reports import growth but only blocks undeclared package.json edges."}
 
 ForgeDock commands now use your project's config from forge.yaml.
 ```

package/commands/review-pr.md

@@ -294,7 +294,7 @@ Substitute each printed value into later fences as `{NAME}` (`{CONTEXT_FILE}`, `
 The 2D env-var, 2E secrets and 2F SQL scans ran in Phase 1 (`PHASE2_FINDINGS`): **a secrets hit is CRITICAL and BLOCKING**; an env var missing from `.env.example` and a migration hazard (`FOR UPDATE` with an aggregate, `DROP` without `IF EXISTS`, `NOT NULL` without `DEFAULT`) are findings. Execution (format, lint, typecheck, build, tests) stays here: it is long-running and needs a throwaway checkout (HARD RULE 7). Commands come from the main checkout's `forge.yaml → verification.commands.*` and run for the changed languages only; a missing command prints `SKIPPED`, never a silent pass, and exit codes are printed so the verdict is not inferred from truncated output.
 
 ```bash
-PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; REVIEW_SHA="{REVIEW_SHA}"; REQUIRES_FULL_BUILD="{REQUIRES_FULL_BUILD}"
+PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"; REVIEW_SHA="{REVIEW_SHA}"; REQUIRES_FULL_BUILD="{REQUIRES_FULL_BUILD}"; CTX="{CONTEXT_FILE}"
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; FORGE_SOURCED_ROOT='${CLAUDE_PLUGIN_ROOT}'; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/*; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 MAIN_ROOT="$(cd "$(git rev-parse --path-format=absolute --git-common-dir)/.." && pwd)"   # main checkout even when run from a linked worktree
 REVIEW_WT="${TMPDIR:-/tmp}/forge-review-wt-${PR_NUMBER}-$$"
@@ -304,7 +304,7 @@ git worktree add --detach "$REVIEW_WT" "$REVIEW_SHA" 2>/dev/null
 { cd "$REVIEW_WT" && [ "$(git rev-parse HEAD)" = "$(git -C "$MAIN_ROOT" rev-parse "$REVIEW_SHA")" ]; } || { echo "SKIPPED — could not create per-PR worktree at $REVIEW_SHA"; exit 0; }
 CFG="${FORGE_CONFIG:-$MAIN_ROOT/forge.yaml}"
 vcmd() { yq ".verification.commands.${1}.${2} // \"\"" "$CFG" 2>/dev/null || echo ''; }
-CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)
+CHANGED=$(jq -r '.full_files[]?' "$CTX" 2>/dev/null); [ -n "$CHANGED" ] || CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)   # Phase 1 list survives an API 406 (forge#4154)
 [ -d "$MAIN_ROOT/node_modules" ] && [ ! -e node_modules ] && ln -s "$MAIN_ROOT/node_modules" node_modules
 run_step() { # run_step <lang> <step> <tail-lines>: prints the exit code; empty command = SKIPPED
   local c; c=$(vcmd "${1}" "${2}")

package/docs/CONFIG.md

@@ -55,6 +55,7 @@ If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pi
 | [`review`](#review-optional) | No | Context injected into review agents |
 | [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
 | [`verification`](#verification-optional) | No | Health-check patterns |
+| [`verify`](#verify-optional) | No | Core work-on: run lane verification on CI runners instead of the host (`mode: local\|ci\|hybrid`) |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
 | [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
 
@@ -227,6 +228,12 @@ repos:
 
 GitHub Projects v2 integration. When configured, ForgeDock automatically adds issues to the project board and updates Status, Lane, Component, Priority, and Workflow fields as issues progress through the pipeline.
 
+`/forgedock-init` fills this section for you: it links an existing board or creates a new one, links it to the repo, adds any missing Lane/Priority/Workflow/Component fields (Status is built in), and writes the IDs below. Projects v2 needs the `read:project`/`project` token scope, which `gh auth login` does not grant by default. If the scope is missing, `/forgedock-init` prints the fix:
+
+```bash
+gh auth refresh -h github.com -s read:project,project
+```
+
 ```yaml
 project_board:
   owner: "acme-org"
@@ -399,7 +406,7 @@ orchestration:
 |-------|------|----------|-------------|
 | `max_concurrent` | integer | No | Max concurrent top-level `/work-on` dispatches. It does not bound cascade growth; under `policy: all` it raises drain and spawn throughput together. Default: 12. |
 | `breaker.errors` / `breaker.window_min` | integer | No | `forgedock orchestrate` circuit breaker (#4121): after `errors` engine-errors within `window_min` minutes the batch stops admitting lanes, lets running lanes finish, and keeps the rest pending for `--resume`. `errors: 0` turns it off. Default: 3 in 30 |
-| `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held) before its row is final. `host.busy` deferrals are not capped. Default: 3 |
+| `max_deferrals` | integer | No | `forgedock orchestrate`: requeues of one issue after a non-host `deferred` (usage limit, merge/push transient, CLI idle, lease held, gh unavailable) before its row is final. `host.busy` deferrals are not capped. Default: 3 |
 | `cascade.policy` | string | No | `all` \| `balanced` \| `conservative`. Default: `balanced` |
 | `cascade.max_generation` | integer or `"unlimited"` | No | Max cascade generation admitted at Phase 1 resolve time. Default: 1 |
 | `cascade.batch_max_generation` | integer | No | Finite maximum member generation that an automated P3 batch may aggregate. Default: 2 |
@@ -484,12 +491,12 @@ engine:
 | `<key>_max_turns` | integer | No | Positive integer passed as `--max-turns`. Invalid values are ignored. |
 
 | `path` | string | No | `core` (default), `full`, `lean` or `auto`. `core` is the lean work-on (`bin/lean/`): a planning call that writes a frozen contract, an implement call in the same session, one read-only conformance reviewer, GitHub as the register (see `conformance`). `lean` and `auto` are aliases of `core`; `full` runs the legacy multi-phase pipeline and is required for `--retry` and `--wait-lease`. The `--path` flag overrides. `lean_reviewer_model` sets the reviewer model (default `claude-sonnet-5-5`); the builder uses `--model` or the CLI default. `forgedock orchestrate <issues...> [--parallel K] [--lane L]` runs the core per issue (K default 3, lane default `staging`) and honours `**Depends on**` ordering among the given issues. |
-| `conformance` | string | No | Core work-on conformance gate. The builder first writes a contract (requirements quoted verbatim from the issue and maintainers' comments, deliverables, preserve constraints, validate commands), which the engine freezes and posts as `FORGE:CONTRACT`; changes go only through typed amendments (`FORGE:AMENDMENT`). A deterministic precheck (scope, validation, deferrals) and a row-based conformance review follow, and the engine computes the verdict. `shadow` (default): the verdict is posted in `FORGE:REVIEW` and logged (`CONFORMANCE_SHADOW` event) but only what the previous reviewer blocked on still blocks (a requirement found not implemented, a regression); deferrals are not filed. `enforce`: every failure blocks (one same-session builder resume, then `needs-human` with a `conformance.*`/`review.*` code, see docs/OUTCOME-CODES.md); deferrals the reviewer accepts are filed in one batched follow-up issue (`scripts/file-deferred-followups.sh`) and linked in the PR body and a `FORGE:TRACKED` comment before merge. |
+| `conformance` | string | No | Core work-on conformance gate. The builder first writes a contract (requirements quoted verbatim from the issue and maintainers' comments, deliverables, preserve constraints, validate commands), which the engine freezes and posts as `FORGE:CONTRACT`; changes go only through typed amendments (`FORGE:AMENDMENT`). A deterministic precheck (scope, validation, deferrals) and a row-based conformance review follow, and the engine computes the verdict. `shadow` (default): the verdict is posted in `FORGE:REVIEW` and logged (`CONFORMANCE_SHADOW` event) but only what the previous reviewer blocked on still blocks (a requirement found not implemented, a regression), plus the precheck's equivalent: a validate command that ran and failed, or a deliver requirement the builder reported as not implemented (#4160). These block before any reviewer run. A validate step with no recorded result, scope creep and amendment problems are recorded only. Deferrals are not filed. `enforce`: every failure blocks (one same-session builder resume, then `needs-human` with a `conformance.*`/`review.*` code, see docs/OUTCOME-CODES.md); deferrals the reviewer accepts are filed in one batched follow-up issue (`scripts/file-deferred-followups.sh`) and linked in the PR body and a `FORGE:TRACKED` comment before merge. |
 | `cli_idle_minutes` | number | No | Core builder idle timeout (#4112): the builder CLI runs with `--output-format stream-json` and is killed (code `cli.idle`) when it shows no stream activity for this many minutes. The run log records the last tool call and the live child processes. Default 15. |
 | `cli_max_minutes` | number | No | Absolute ceiling for a core builder session (code `cli.timeout`), replacing the fixed 60-minute kill. A session that keeps making progress is never idle-killed. Default 180. On either kill, uncommitted work is committed as `wip(forge): checkpoint after <reason>` and the lane branch is pushed (with the push retry), the builder retries once from the checkpoint, and a second kill ends `deferred`; a rerun resumes from the branch. |
 | `lane_limits` | map | No | Cap each core lane's whole process tree (#4115), under `pipeline:` or `engine:`: `memory_max` (for example `3G`) and `cpu_quota` (for example `150%`). When set and `systemd-run --user --scope` works (probed once), the builder CLI is spawned as `systemd-run --user --scope -q -p MemoryMax=... -p CPUQuota=... -- claude ...`; elsewhere the caps are ignored. Write it nested or flat (`lane_limits_memory_max`, `lane_limits_cpu_quota`). While a builder runs the engine polls host load and memory every 15 s against the `admission` thresholds: over them it SIGSTOPs the lane's process group, under them SIGCONT, and never pauses longer than 10 minutes. |
 | `admission` | map | No | Host-resource admission for the core work-on (#4105), checked before the lease, worktree or any GitHub call. When a check fails the run ends `deferred` (code `host.busy`, exit 75) with a last line such as `issue #N → deferred (host busy: mem 1.2G < 2G; retry in 60s)`; no lease is taken and nothing is posted. Keys: `enabled` (default `true`; `false` disables admission), `min_free_mem_mb` (default 2048; `MemAvailable` from `/proc/meminfo`, else `os.freemem()`), `min_free_tmp_mb` (default 1024; free space of the run TMPDIR filesystem, `~/.forge/tmp`, and of `/tmp`, via `statfs`), `max_load_per_core` (default 4; 1-minute load average divided by cores). Write it nested (`engine:` then `admission:` with the keys indented) or flat as `admission_enabled`, `admission_min_free_mem_mb`, `admission_min_free_tmp_mb`, `admission_max_load_per_core`; the parser reads one nested level into `engine`. `/orchestrate` requeues a host-busy lane and lowers K by 1 for 5 minutes. |
-| `merge_wait` | string | No | Core work-on merge gate. `required` (default): wait only for the status checks the base branch requires under branch protection (`gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`, contexts and checks); with no protection or no required checks (404 or empty) merge right after review PASS. A failing required check is `needs-human`; a pending one is polled with backoff and never `needs-human`. `all`: wait for every check (`scripts/wait-ci-green.sh`). `none`: merge right after review. Always `--match-head-commit` at the reviewed head. The policy used is recorded in the `FORGE:WORK-ON` comment. |
+| `merge_wait` | string | No | Core work-on merge gate. `required` (default): wait only for the status checks the base branch requires: the union of classic branch protection (`gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`, contexts and checks) and repository rulesets (`gh api repos/{o}/{r}/rules/branches/{base}`, `required_status_checks` rules); with neither (404 or empty) merge right after review PASS. A merge rejected by base branch policy (PR `MERGEABLE` but `BLOCKED`) is waited on and retried within the CI budget, then left `ci-pending`; it is never base-synced and never `base.conflict`. A failing required check is `needs-human`; a pending one is polled with backoff and never `needs-human`. `all`: wait for every check (`scripts/wait-ci-green.sh`). `none`: merge right after review. Always `--match-head-commit` at the reviewed head. The policy used is recorded in the `FORGE:WORK-ON` comment. |
 | `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.
@@ -508,6 +515,43 @@ engine:
 
 ---
 
+## `verify` (OPTIONAL)
+
+Verify-by-CI for the core work-on path (forge#4167). It moves a lane's heavy verification (type-checks, test suites, docker test containers) off the host and onto CI runners, and it catches CI-class failures (lock files, suite wiring, hangs, formatting) before the lane merges into staging. Write it as a block-style section: `parseForgeYaml` does not read inline `{ ... }` maps.
+
+```yaml
+verify:
+  mode: ci                      # local (default) | ci | hybrid
+  workflow: forgedock-verify.yml  # optional; needs an `on: workflow_dispatch` trigger
+  paths_input: changed_paths    # optional workflow_dispatch input that receives the changed paths (newline-separated)
+  skip_paths: "*.md,docs/**"    # optional, comma-separated; default *.md,*.mdx,*.rst,*.txt,docs/**,devdocs/**
+  max_rounds: 2                 # optional CI fix rounds before needs-human (default 2)
+```
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `mode` | string | No | `local` (default): today's behaviour; the builder runs every validate command on the host and no CI is started before review. `ci`: the builder runs only formatters and linters on the files it changed (no type-checks, test suites or test containers) and records validate ids it left to CI as `{"id","command","ci":true}`; the engine verifies on CI. `hybrid`: the builder runs the targeted validate commands too, and CI also verifies. |
+| `workflow` | string | No | Workflow file name or id dispatched on the lane branch (`gh workflow run <workflow> --ref <branch>`). The engine waits for the `workflow_dispatch` run of the lane's head commit. Without it, the engine waits on the head commit's push-triggered check runs. |
+| `paths_input` | string | No | Name of a `workflow_dispatch` input that receives the changed paths, so the workflow can scope its jobs to the change. |
+| `skip_paths` | string | No | Comma-separated globs. A glob without `/` matches the basename anywhere; `**` spans directories. When every changed file matches, the lane skips CI verification (a docs-only lane runs no CI matrix). |
+| `max_rounds` | integer | No | Builder fix rounds for red CI (0–10, default 2). |
+
+**Flow** (`ci`/`hybrid`, `bin/lean/verify.mjs` `runCiVerify`):
+
+1. After the build and before every conformance review, the engine pushes the lane branch (a plain push, never forced) and runs CI on the head. A base-sync that moves the head is verified again.
+2. Green (or skipped by `skip_paths`): the review runs. The precheck accepts validate ids left to CI for that head, but a recorded non-zero exit still fails.
+3. Red: the failed jobs' logs (`gh run view --log-failed`, tails capped at about 12 KB) go back to the builder session. The builder fixes and commits, and the engine pushes and verifies again. Still red after `max_rounds`, or a fix round with no new commit, ends as `needs-human` (`ci.red`) and nothing merges.
+4. Slow CI: once the core CI wait budget (360 min, the same budget the merge wait uses) is used up, the lane ends `ci-pending` and can be resumed. Slow CI is never `needs-human`.
+5. CI unavailable (dispatch refused, or no run or check for the head within 5 minutes): one local fallback. The builder runs every validate command on the host and records real exit codes.
+
+Each verification emits a `CI_VERIFY` run-log/telemetry event (`mode`, `round`, `result`, `skipped`, `run_url`) and adds a **Verify** row to the trajectory.
+
+**Cost:** `ci`/`hybrid` spend GitHub Actions minutes before review, so they are opt-in per repo. On the green path they add no LLM calls; each red CI round adds one builder resume. The merge gate (`engine.merge_wait`) is unchanged.
+
+**Commands that use this section**: core work-on (`forgedock run-issue`, `forgedock orchestrate`; `bin/engine-cli.mjs` `readVerify`)
+
+---
+
 ## `build` (OPTIONAL)
 
 Tuning for the `/work-on` build phase. Today it holds the **scope check** (forge#3862, replacing the diff-size gate): after the implement phase stages its changes and before validation commits them, the build compares the staged diff with the architect plan (the `PLANNED_FILES:` list and `ESTIMATED_DIFF_LINES` in the plan's `### Scope Baseline`), measures a deterministic `review_weight` with `scripts/diff-size.sh`, and records the outcome in `FORGE:DIFF_SIZE`. **Size never blocks, a finished build is never discarded, and a completed build is never routed to decompose.**
@@ -977,8 +1021,13 @@ npx forgedock labels setup
 
 # Or target a specific repo explicitly:
 npx forgedock labels setup --repo owner/repo
+
+# Also create per-repo domain labels (comma-separated):
+npx forgedock labels setup --domain frontend,backend,infra,design,legal-gated
 ```
 
+Domain labels are optional and per-repo. They are not part of `bin/labels.json`, so `forgedock doctor` never requires them. Each one gets the description `Domain: <name>. Managed by ForgeDock.`. `frontend`, `backend`, `infra`, `design` and `legal-gated` have fixed colors; any other name is grey (`#EDEDED`). A name that is already in the manifest is not created twice. `/forgedock-init` derives the list from your spec or takes it from `--domain-labels`.
+
 Running this command is idempotent — it creates labels that don't exist and updates the color/description of labels that do. Safe to re-run at any time.
 
 **When to run it**: Once after `npx forgedock install`, or whenever a pipeline command fails with "label not found". The command bootstraps every label the pipeline relies on.

package/docs/OUTCOME-CODES.md

@@ -37,7 +37,9 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `merge.transient` | `gh pr merge` kept failing with a transient error (`Base branch was modified`, GraphQL or 5xx) after the retry budget; the run is `deferred` and a rerun resumes at the merge | lean | `bin/lean/lean.mjs` |
 | `push.transient` | `git push` kept failing with a transient error (`remote unpack failed`, `index-pack failed`, `RPC failed`, 5xx, reset, timeout) after 4 attempts; `deferred`, rerun resumes | lean | `bin/lean/lean.mjs` |
 | `cli.idle` | The builder CLI showed no stream activity for `engine.cli_idle_minutes` and was killed; uncommitted work was checkpointed to the lane branch; `deferred` after one automatic retry | lean | `bin/runner.mjs` |
+| `run.interrupted` | A core run got SIGTERM/SIGINT; the lane tore down from its resource ledger (unpushed work checkpointed to the lane branch, worktree removed, lease released) and ended `deferred`, so a batch requeues it | lean | `bin/engine-cli.mjs` |
 | `host.busy` | Core run deferred at admission: free memory, free tmp space or load per core outside `engine.admission` limits; no lease taken, nothing posted | lean | `bin/lean/admission.mjs` |
+| `gh.unavailable` | `run-issue --repo` could not verify the cwd repo because `gh repo view` kept failing after 3 attempts with backoff (typically a timeout under host load); the core or full run is `deferred` (exit 75, retry in 60s) before any lease, nothing posted | engine CLI | `bin/engine-cli.mjs` |
 | `rate_limited` | Session or usage limit outlasted the pause budget | engine | `err.usageLimit` / `err.resetAtEpochMs` |
 | `engine.error` | Engine or tool failure (missing key/SDK, CLI crash, max turns, unresolved args, runner threw every attempt) | engine | `err.code` |
 | `infra.disk_quota` | Disk full or quota exhausted (EDQUOT/ENOSPC, errno -28/-122); retryable infra failure, never `needs-human` | engine | Runner error text |
@@ -70,6 +72,7 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `conformance.unjustified_deferral` | Core work-on: the reviewer judged a deferred or post-deploy requirement unjustified (it belongs in this change), after one builder resume; nothing is filed or merged | lean | Review requirement row `deferral_ok: false` |
 | `conformance.preserve_violated` | Core work-on: a preserve constraint is violated or unverified, after one builder resume | lean | Review `preserve` row not `intact` |
 | `conformance.regression` | Core work-on: the reviewer named a concrete regression, after one builder resume | lean | Review `regressions` row |
+| `structure.undeclared_edge` | Core work-on: the change adds a package.json dependency between workspace packages that the frozen contract does not name, still present after one builder resume | lean | `unnamedEdges` over `scripts/structure-delta.sh` `package_edges_added` |
 | `followup.unavailable` | Core work-on: filing or verifying the tracking issue for a deferral failed; the run is deferred with nothing merged, never needs-human | lean | `file-deferred-followups.sh` exit 3/4 or an unreadable tracking issue |
 | `merge.head_mismatch` | Core work-on: CI passed for a head other than the reviewed head; merge refused | lean | Gate head differs from the reviewed head |
 | `completed` | Non-failure terminal (merged, phase-complete, investigation) | engine | Terminal reason |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"