forgedock 1.17.0 → 1.19.0

package/commands/test-gate.md

@@ -439,23 +439,38 @@ BASELINE_RESULTS=""
 
 # Run the same tests against the base branch state to establish baseline
 # If base-branch tests also fail, those are pre-existing failures — not batch-introduced
-git stash 2>/dev/null || true
-git checkout "origin/${BASE_BRANCH}" -- . 2>/dev/null || true
+# Use a detached worktree at the base branch — never stash/checkout in the main checkout
+BASE_WT=$(mktemp -d)
+git -C "$REPO_PATH" worktree add --detach "$BASE_WT" "origin/${BASE_BRANCH}" 2>/dev/null \
+  || { echo "WARNING: could not create baseline worktree — baseline unavailable (failures will count as batch-introduced)"; rmdir "$BASE_WT" 2>/dev/null; BASE_WT=""; }
+# A fresh worktree has no installed deps or local env files: link the main checkout's (read-only use), at the repo
+# root and in every cluster working_dir, so a baseline cluster fails only for code reasons, never for a missing install.
+if [ -n "$BASE_WT" ]; then
+  { echo .; yq '.verification.integration_tests[].working_dir // "."' "$CONFIG_FILE" 2>/dev/null; } | sort -u | while IFS= read -r _wd; do
+    for _dep in node_modules .venv venv .env .env.local .env.test; do
+      [ -e "${REPO_PATH}/${_wd}/${_dep}" ] && [ ! -e "${BASE_WT}/${_wd}/${_dep}" ] && [ -d "${BASE_WT}/${_wd}" ] \
+        && ln -s "${REPO_PATH}/${_wd}/${_dep}" "${BASE_WT}/${_wd}/${_dep}"
+    done
+  done   # one working_dir per line: a path with spaces is never word-split
+fi
 
 for i in $(seq 0 $((CLUSTER_COUNT - 1))); do
   CLUSTER=$(yq ".verification.integration_tests[${i}].cluster" "$CONFIG_FILE")
   CMD=$(yq ".verification.integration_tests[${i}].command" "$CONFIG_FILE")
   WORKING_DIR=$(yq ".verification.integration_tests[${i}].working_dir // \".\"" "$CONFIG_FILE")
 
-  if (cd "${REPO_PATH}/${WORKING_DIR}" && eval "$CMD") 2>&1; then
+  if [ -z "$BASE_WT" ]; then
+    # No baseline: never claim pre-existing. A bundle failure in this cluster counts as batch-introduced (fail closed).
+    BASELINE_RESULTS="${BASELINE_RESULTS}\n- ${CLUSTER}: UNAVAILABLE"
+  elif (cd "${BASE_WT}/${WORKING_DIR}" && eval "$CMD") 2>&1; then
     BASELINE_RESULTS="${BASELINE_RESULTS}\n- ${CLUSTER}: PASS"
   else
     BASELINE_RESULTS="${BASELINE_RESULTS}\n- ${CLUSTER}: FAIL (pre-existing)"
   fi
 done
 
-# Restore working state
-git checkout HEAD -- . 2>/dev/null || true
+# Remove the baseline worktree (the main checkout was never touched)
+[ -n "$BASE_WT" ] && git -C "$REPO_PATH" worktree remove --force "$BASE_WT" 2>/dev/null || true
 
 echo "Baseline results:"
 echo -e "$BASELINE_RESULTS"
@@ -475,10 +490,10 @@ while IFS= read -r result_line; do
   if echo "$STATUS" | grep -q "^FAIL"; then
     # Check if this cluster also failed in baseline
     BASELINE_STATUS=$(echo -e "$BASELINE_RESULTS" | grep "^- ${CLUSTER}:" | grep -oP ':\s+\K.+' || echo "PASS")
-    if echo "$BASELINE_STATUS" | grep -q "^PASS"; then
-      # This cluster passed in baseline but fails in the bundle — batch-introduced failure
+    if ! echo "$BASELINE_STATUS" | grep -q "^FAIL"; then
+      # Baseline PASS (or UNAVAILABLE: no proof it was pre-existing) but fails in the bundle — batch-introduced failure
       BATCH_FAILURES="${BATCH_FAILURES}\n${CLUSTER}"
-      echo "BATCH-INTRODUCED FAILURE: cluster '${CLUSTER}' (baseline: PASS → bundle: FAIL)"
+      echo "BATCH-INTRODUCED FAILURE: cluster '${CLUSTER}' (baseline: ${BASELINE_STATUS} → bundle: FAIL)"
     else
       echo "PRE-EXISTING FAILURE: cluster '${CLUSTER}' (baseline: FAIL → bundle: FAIL — not this batch)"
     fi
@@ -534,7 +549,7 @@ else
     cat <<ISSUE_EOF > "$TESTGATE_FAIL_BODY_FILE"
 ## Problem
 
-The \`/test-gate\` command detected a runtime failure in cluster \`${cluster}\` that was introduced by the staging→${DEFAULT_BRANCH} bundle. The failure did not exist on \`${BASE_BRANCH}\` (baseline PASS), confirming it is batch-introduced, not pre-existing.
+The \`/test-gate\` command detected a runtime failure in cluster \`${cluster}\` that was introduced by the staging→${DEFAULT_BRANCH} bundle. It was not observed failing on \`${BASE_BRANCH}\` (baseline: PASS, or UNAVAILABLE when the baseline could not run — then treated as batch-introduced, fail closed).
 
 ## Root Cause (if known)
 
@@ -574,7 +589,7 @@ $(echo -e "$SOURCE_ISSUES_LIST")
    \`\`\`
 3. Observe failure. Compare against \`${BASE_BRANCH}\` baseline:
    \`\`\`bash
-   git checkout origin/${BASE_BRANCH} -- .
+   git worktree add --detach "$BASE_WT" origin/${BASE_BRANCH}   # run the command inside $BASE_WT
    $(yq ".verification.integration_tests[] | select(.cluster == \"${cluster}\") | .command" "$CONFIG_FILE")
    \`\`\`
 ISSUE_EOF

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

@@ -604,6 +604,39 @@ The block is delimited by `<!-- FORGE:BLAST_RADIUS:BEGIN -->` and `<!-- FORGE:BL
 
 ---
 
+## Phase A2.9: Append-Only Registry Check *(skip when no planned file is a hand-maintained list)* <!-- Added: forge#3969 -->
+
+Two PRs appending at the same spot of a shared list (test paths, cron targets, workflow steps) conflict textually although every line is independent, and each conflict costs a base-sync remediation round. For each planned file that is an append-only registry (one independent entry per line, edited by many PRs):
+
+1. Confirm with `bash <scripts>/detect-append-registries.sh --detect` (history ranking) and `--check-union <path>`. Resolve `<scripts>` through the trusted script resolution (plugin root, `FORGE_ROOT`, `FORGEDOCK_HOME`), never `$PWD`. The helper rejects JSON, YAML, TOML, lockfiles and Markdown.
+2. Plan one of: (a) a `.gitattributes` `merge=union` entry, only when `--check-union` prints `UNION SAFE` and every line is independent (no ordering, uniqueness or structure); or (b) converting the list to glob discovery where its consumer supports it.
+3. Name the registry and the chosen option in `### Affected Paths`. Never plan union for a file with ordering, uniqueness or structure: that file is edited at the end of the list, and the pre-handoff base sync resolves its conflicts.
+
+---
+
+## Phase A2.10: Consumer Sweep Intake *(advisory: skip silently when no existing identifier changes; never blocks)* <!-- Added: forge#3970 -->
+
+No diff exists yet, so sweep by name. List the existing identifiers the plan will change, rename or re-type (functions, classes, constants, config or context keys, CLI flags, env vars, paths, literal hashes or versions), take them from the investigation's affected files, and run the script in identifier mode. Validate (Phase V4.6) later re-runs the same sweep on the final diff and gates it.
+
+```bash
+# FORGE_ROOT: shared resolver scripts/lib/forge-resolve.sh (empty when unresolved => the sweep is skipped, never guessed)
+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() { :; }; }
+FORGE_ROOT="$(forge_root 2>/dev/null || true)"
+CS_SCRIPT="${FORGE_ROOT:+$FORGE_ROOT/scripts/consumer-sweep.sh}"; [ -f "$CS_SCRIPT" ] || CS_SCRIPT=""
+EXCLUDES=()
+while IFS= read -r _g; do [ -n "$_g" ] && [ "$_g" != "null" ] && EXCLUDES+=(--exclude-glob "$_g"); done \
+  < <(yq '(.build.scope.exclude_globs // []) + (.build.diff_size.exclude_globs // []) | .[]' forge.yaml 2>/dev/null || true)
+if [ -z "$CS_SCRIPT" ]; then echo "CONSUMER_SWEEP: unavailable (script not found under FORGE_ROOT)"; else
+  bash "$CS_SCRIPT" --ident {IDENTIFIER_1} --ident {IDENTIFIER_2} ${EXCLUDES[@]+"${EXCLUDES[@]}"}; echo "CONSUMER_SWEEP_RC=$?"
+fi
+```
+
+Each identifier must match `^[A-Za-z0-9_.:/-]{4,80}$` (flags without leading dashes). Output is TSV `identifier<TAB>kind<TAB>file:line`; a `truncated` row means more sites exist than the cap shows (advisory). Exit `2` or an unavailable script is not "no sites": write "consumer sweep unavailable" in `### Risk Assessment` and continue; never block the plan.
+
+Fold the result into Phase A2.8, with no new record grammar: each swept identifier becomes a `SYMBOL:` (`query` = the identifier) and each referencing file a `HIT:` (`disposition=change` when the plan edits it, else `verified-unaffected` with a reason after reading the site). The builder must update or justify each site (implement I6 `CONSUMERS:` block).
+
+---
+
 ## Phase A3: Consistency Rules
 
 Identify invariants that ALL affected paths must satisfy. These become the builder's consistency checklist.
@@ -636,6 +669,14 @@ Rules for ordering:
 
 ---
 
+## Phase A4.5: Edge-Case Enumeration *(skip on the skip-marker path; an empty block is valid)* <!-- Added: forge#3631 -->
+
+List the error, edge and concurrency cases the change must survive, so validate (Phase V4.7, `scripts/check-edge-cases.sh`) can require a test for each. Cover every error class the code path can raise (not only the one in the report), boundary and empty inputs, and concurrent or repeated invocation. Skip cases that only restate a normal-path acceptance criterion.
+
+Record one single-line record per case between `<!-- FORGE:EDGE_CASES:BEGIN -->` and `<!-- FORGE:EDGE_CASES:END -->`: `EDGE: id=e1 kind=error|edge|concurrency description=<free text>`. Ids are `e1`, `e2`, ... and are unique and stable. Only `id=` and `kind=` are parsed; the description is free text. Emit an empty block (or omit the section) when the change has no such cases. The builder maps each id to a test or an `untestable=` reason in FORGE:BUILDER (implement I6). Never use the architect marker strings as delimiters.
+
+---
+
 ## Phase A5: Risk Assessment
 
 For each non-obvious interaction or potential failure mode:
@@ -719,6 +760,15 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 |---|------|----------------|-----------------|-----|
 | 1 | {FILE} | {FUNCTION} | {CHANGE} | {REASON} |
 
+### Scope Baseline
+<!-- Machine-readable scope baseline read by build B5.5's post-build scope check (forge#3862). Every
+     path in ### Affected Paths (including tests, docs and config the plan changes), one per line as
+     - path (repo-relative; a trailing slash means every file under that directory). The keys sit alone
+     on their lines. ESTIMATED_DIFF_LINES is the plan's own estimate (code plus tests, a whole number). -->
+PLANNED_FILES:
+- {FILE}
+ESTIMATED_DIFF_LINES: {N}
+
 ### Pattern Sweep
 <!-- Pass-through from the FORGE:INVESTIGATOR '### Pattern Sweep' table (Phase A2.7).
      Omit this section when the investigation report had none. -->
@@ -735,6 +785,16 @@ HIT: symbol=s1 file={FILE} role={producer|consumer|sibling} disposition=change
 HIT: symbol=s1 file={FILE} role={producer|consumer|sibling} disposition=verified-unaffected reason={one-hyphenated-token}
 <!-- FORGE:BLAST_RADIUS:END -->
 
+### Edge Cases
+<!-- Phase A4.5. Human table plus the machine block. Omit when skipped; an empty block is valid. -->
+| id | kind | description |
+|----|------|-------------|
+| e1 | {error\|edge\|concurrency} | {DESCRIPTION} |
+
+<!-- FORGE:EDGE_CASES:BEGIN -->
+EDGE: id=e1 kind={error|edge|concurrency} description={ONE_LINE_DESCRIPTION}
+<!-- FORGE:EDGE_CASES:END -->
+
 ### Implementation Order
 1. {FIRST_CHANGE} — {WHY_FIRST}
 2. {SECOND_CHANGE} — {WHY_SECOND}
@@ -799,13 +859,16 @@ SKIP_BODY=$(cat <<SKIP_EOF
 
 **Skipped**: {SKIP_REASON}. No cross-path consistency risk — the builder proceeds with the investigation report + context briefing.
 
+### Scope Baseline
+PLANNED_FILES:
+
 <!-- FORGE:ARCHITECT:COMPLETE -->
 SKIP_EOF
 )
 gh issue comment {NUMBER} {GH_FLAG} --body "$SKIP_BODY" # <!-- allowlist:check-command-side-effects -->
 ```
 
-The empty-plan-with-marker changes no downstream behavior — the builder already falls back to the investigation report + contract when the plan is empty (see Integration Point below). The marker only makes the legitimate skip **observable** to the marker-only engine gate. This intentionally does **not** weaken crash detection: a genuinely interrupted architect run still posts no marker at all, so `detectOutcome` still fails-and-escalates it correctly.
+The empty `PLANNED_FILES:` list means "no plan baseline": build B5.5 then skips the out-of-plan check (proceed, never block) and falls back to the investigation's `ESTIMATED_DIFF_LINES`. The empty-plan-with-marker changes no downstream behavior — the builder already falls back to the investigation report + contract when the plan is empty (see Integration Point below). The marker only makes the legitimate skip **observable** to the marker-only engine gate. This intentionally does **not** weaken crash detection: a genuinely interrupted architect run still posts no marker at all, so `detectOutcome` still fails-and-escalates it correctly.
 
 ---
 
@@ -840,8 +903,10 @@ B4    → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
           Phase A2.5: Pipeline Phase-Dependency Check
           Phase A2.7: Pattern Sweep Intake (review-finding issues only)
           Phase A2.8: Blast-Radius Manifest (enforced by validate V4.5, passed to review-pr)
+          Phase A2.10: Consumer Sweep Intake (consumer-sweep.sh --ident; gated by validate V4.6)
           Phase A3: Consistency Rules
           Phase A4: Sequence the Implementation
+          Phase A4.5: Edge-Case Enumeration (EDGE: ids; gated by validate V4.7)
           Phase A5: Risk Assessment
 B5    → Implement (builder reads plan, implements ALL affected paths)
 ```

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

@@ -42,6 +42,7 @@ Parse from $ARGUMENTS:
 
 ---
 
+- `--fix-consumers "<UNADDRESSED lines>"` — optional. Set only by build B6 after validate returned `consumer_unaddressed`. Skip I1–I2 planning: for each listed `UNADDRESSED: <identifier> <file:line>` site, either update that file so it no longer depends on the old identifier (the file then joins the change set) or add a `- <path>[:<line>] unaffected: <reason>` line to the `### Consumers` block of the FORGE:BUILDER comment (the match is by path, split on the literal ` unaffected: `, so any path characters work). Never edit the checker (`scripts/consumer-sweep.sh`) or its stop-lists, and never add `unaffected:` lines without reading the site. Stage the changes, return `IMPLEMENT_RESULT: status: COMPLETE`; if a site cannot be addressed, leave it: build records it as `CONSUMERS: unresolved`. This is the single repair round; there is no second one. <!-- Added: forge#4017 -->
 - `--fix-acceptance "<failed checks>"` — optional. Set only by build B6.5 after a failed acceptance gate. In this mode, skip I1–I2 planning: read the listed failing `ACCEPTANCE_CHECK` ids from the FORGE:INVESTIGATOR comment, change the code in `{WORKTREE_PATH}` until each check's target/matcher holds (do not edit the checks), update the BUILDER comment's `### Changes` list, and return `IMPLEMENT_RESULT: status: COMPLETE`. If a check is impossible as written (contradicts the contract), return `status: BLOCKED` with that reason. **Decomposition refusal** <!-- Added: forge#3543 -->: never implement work that the FORGE:INVESTIGATOR `### Decomposition Assessment` (`**YES**`) assigns to a separate sub-issue, even if a listed check targets it; return `status: BLOCKED` with blocker "check <id> belongs to decomposed item <N>" instead.
 
 ## Phase I1: Load Context from GitHub
@@ -165,6 +166,7 @@ Work in `{WORKTREE_PATH}`. Follow the contract deliverables table exactly — im
 - For each acceptance criterion in the contract: implement it, then mentally verify it's met
 - Do NOT add unrequested scope — contract out-of-scope items stay out of scope
 - **Library callback verification**: When writing a lambda or callable that will be passed to a library/framework parameter (e.g., `prepared_statement_name_func=lambda: ""`, `key=lambda x: ...`), you MUST verify the expected calling convention BEFORE writing it. Check the library's default value for that parameter, its documentation, or its source code. A lambda with wrong arity causes `TypeError` at runtime — this is invisible to static analysis and linting. The P0 incident from PR #14391 was caused by `lambda _: ""` (1 arg) passed where SQLAlchemy expects 0 args.
+- **Scratch placement (venvs, caches)**: create virtualenvs, package caches and other large scratch data under `"$TMPDIR/forge-venv-{NUMBER}"` (the engine exports a per-run, disk-backed `TMPDIR`) or inside the worktree. Never use a literal `/tmp/<name>` path: a size-limited `/tmp` fails concurrent lanes with EDQUOT/ENOSPC. Remove what you created when the run finishes. <!-- Added: forge#3572 -->
 - **Worktree-aware path derivation**: When writing shell code that derives repository paths, ALWAYS use `git rev-parse --show-toplevel` for the repo root in regular checkouts, or `git rev-parse --git-common-dir` (then `dirname`) to get the shared `.git` directory when the context may be a linked worktree. For worktree cleanup code specifically, ALWAYS use `--git-common-dir` — `--show-toplevel` returns the worktree path itself, NOT the main repo root. NEVER use `pwd`, relative paths, or `dirname` chains on `--show-toplevel` output for repo root derivation. Test path logic for both regular checkouts and linked worktrees. (Ref: review-findings #104, #105 — 4 PATH_DERIVATION defects, 15% of all review findings)
 - **State machine completeness verification**: When implementing routing logic, state transition tables, or phase dispatch code (e.g., adding a `Skill()` call in a routing loop, adding a new phase to a state machine, creating a new subcommand file), you MUST run three checks BEFORE staging: (1) **Routing target existence** — for each `Skill("subcommand", ...)` call or file reference in routing logic, verify the target file exists at `commands/{subcommand-path}.md`; (2) **State reachability** — for each declared state or phase, verify at least one prior state or entry condition in the router routes to it; (3) **Subcommand invocation wiring** — for each `commands/work-on/*.md` file that declares its invocation condition (e.g., `Invoked by work-on.md routing loop, when X`), verify that condition is actually handled in the router. A missing target file, an unreachable state, or a declared-but-unwired subcommand will not surface until review. (Ref: review-findings #85, #116, #137 — 4 ROUTING defects, 15% of all review findings)
 - **Migration safety checklist** *(trigger: diff includes `*.sql` files or files under a `migrations/` path)*: When any migration file is in the diff, verify ALL of the following BEFORE staging. Fix each violation inline — do not defer to review or the quality gate: (a) **Rollback file**: a corresponding down/rollback migration file exists (e.g. `0042_down_*.sql`, `rollback_*.sql`) or the migration is explicitly self-reversing (DROP of a previously-added column); (b) **NOT NULL safety**: any `ADD COLUMN ... NOT NULL` either includes a `DEFAULT` clause or is preceded by a backfill step — a NOT NULL column without DEFAULT locks the table and fails on existing rows; (c) **Constraint name consistency**: constraint names in the migration match ORM model declarations — a mismatch causes `alembic stamp` and FK introspection to silently diverge; (d) **CREATE TRIGGER idempotency**: every `CREATE TRIGGER` uses `CREATE OR REPLACE TRIGGER` or is preceded by `DROP TRIGGER IF EXISTS` — a bare `CREATE TRIGGER` fails on re-run in test and CI environments; (e) **Migration prefix uniqueness**: confirm the new file's numeric prefix does not already exist in the `infra/migrations/` tree (`ls infra/migrations/*.sql | xargs -n1 basename | grep -oE '^[0-9]+' | sort | uniq -d` prints duplicates) — a duplicate prefix hard-fails the deploy gate regardless of file content. <!-- Added: forge#373 -->
@@ -172,6 +174,8 @@ Work in `{WORKTREE_PATH}`. Follow the contract deliverables table exactly — im
 - **Deliverable-type consistency check**: Before committing, compare the actual output against the CONTRACT's deliverable list. If the CONTRACT explicitly states "no code changes required", "docs only", or "configuration update only" AND the diff introduces new executable files (`.py`, `.js`, `.ts`, `.sh` — not test, config, or documentation files), STOP. Do NOT commit. Re-read the CONTRACT, the investigation recommendation, and the ARCHITECT plan. If all three agree that code is needed, update the CONTRACT comment to reflect the new deliverable type before proceeding. If only the builder decided to add code without contract support, discard the code change and implement the contracted deliverable instead. <!-- Added: forge#279 -->
 - **Pipeline check documentation — generalization rule**: When writing or updating pipeline check documentation (in `commands/*.md`), describe the **bug class**, not a specific incident. Do NOT embed: PR numbers, issue numbers, run IDs, timestamps, function names, dollar amounts, or multi-sentence incident timelines in check prose or `**Evidence**:` blocks. One brief HTML comment `<!-- Added: forge#NNN -->` is acceptable per check for traceability. `**Evidence**:` blocks must describe the vulnerability pattern (what the class of bug looks like, why it's dangerous) — not narrate a single historical occurrence. CHANGELOG entries may reference originating issues; command prompt text must not.
 - **Pattern sweep — class-wide fix and test**: When the FORGE:ARCHITECT plan or FORGE:INVESTIGATOR report contains a `### Pattern Sweep` table (`Query | Hit | Disposition`), fix EVERY hit with disposition `fix`, not only the instance the reviewer cited. Write the test against a representative set of instances from the table, not the reviewer's single repro, so it fails for any sibling still carrying the defect. Do not tune a rule, matcher, or fixture to the cited example. If a `fix` row cannot be changed, or a `not-affected` row turns out to be affected, say so in the `### Approach` of the FORGE:BUILDER comment instead of dropping it silently. Absent table = no-op. <!-- Added: forge#3449 -->
+- **Consumer sweep — address every referencing site**: when the FORGE:ARCHITECT plan lists consumer-sweep sites (`HIT:` rows from `scripts/consumer-sweep.sh`, Phase A2.10), update each referencing file or justify it as unaffected. Validate (V4.6) re-runs the sweep on the final diff; in `blocking` mode it returns `consumer_unaddressed` for every referencing site outside the change set that has no justification, and build runs one repair round (`--fix-consumers`). Sites still unaddressed after that round are recorded as `CONSUMERS: unresolved` and passed to review as known risk; they never block. Record the justifications in the `CONSUMERS:` block of the FORGE:BUILDER comment (Phase I6). <!-- Added: forge#3970 -->
+- **Edge cases — one test per id**: when the FORGE:ARCHITECT plan carries a `FORGE:EDGE_CASES` block (`### Edge Cases`, Phase A4.5), write one test per `EDGE:` id (error, edge and concurrency cases, not only the happy path) and keep the test in the diff's added lines. Record each id in the `### Edge Case Coverage` section of the FORGE:BUILDER comment (Phase I6). Validate (V4.7) fails with `edge-cases: <ids>` for an id with no `EDGE_TEST:` line, a mapped test name absent from the added lines of its file, or an empty `untestable=` reason. Use `untestable=<reason>` only when no test can exercise the case, and give the real reason. An empty or absent block is a no-op. <!-- Added: forge#3631 -->
 - **Endpoint response contract consumer tracing**: When changing an endpoint's response body shape or status field values (e.g., changing `"status": "healthy"` to `"status": "ok"`, renaming response keys, removing fields), grep the full repo for ALL consumers of that response body before committing. Consumers are not limited to the service being changed — they include deploy scripts, CI health checks, monitoring configs, docker-compose healthcheck definitions, Traefik probes, and any script that parses or pattern-matches on the response body. Run: `grep -rn "{old_value}\|{endpoint_path}" scripts/ infra/ .github/ docker-compose*.yml traefik/ 2>/dev/null`. All consumers whose behavior depends on the old response format MUST be updated in the same PR — a response contract change that updates only one consumer while leaving others on the old format is a deploy-time breakage. <!-- Added: forge#321 -->
 - If you discover the contract is wrong (e.g. a file doesn't exist, a function has a different signature): STOP, post a comment on the issue explaining the discrepancy, add label `needs-human`, and EXIT with `IMPLEMENT_RESULT: status: BLOCKED` and a `blocker` describing the discrepancy
 
@@ -305,7 +309,7 @@ git add {CHANGED_FILES}
 
 Do NOT run `git commit` here. The commit (with conventional commit message and issue reference) is made by validate.md Phase V5 after `GATE_PASSED=true`.
 
-**Informational diff size** <!-- Added: forge#3450 -->: after staging, read the changed-line count so the builder comment and result carry it. This is a hint only. Implement never gates or decides: the diff-size gate lives in build B5.5, which re-measures authoritatively. Leave `DIFF_LINES` empty when the script is unavailable or fails.
+**Informational diff size** <!-- Added: forge#3450 -->: after staging, read the changed-line count so the builder comment and result carry it. This is a hint only. Implement never gates or decides: the scope check lives in build B5.5, which re-measures authoritatively against the plan (it needs only the `diff_lines=` key here). Leave `DIFF_LINES` empty when the script is unavailable or fails.
 
 ```bash
 # <Script resolution block from work-on/build.md, verbatim>
@@ -354,6 +358,22 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 ### Acceptance Criteria Status
 {Checklist of each criterion from the contract, marked ✅ or ❌}
 
+### Consumers
+CONSUMERS:
+- {path}[:{line}] unaffected: {one-line reason}
+- {path} updated
+
+CONSUMERS: unresolved
+- {path}:{line} unresolved: {identifier}
+
+> **Consumers block**: one line per referencing site of a changed or removed identifier (the architect's A2.10 sweep and the V4.6 `UNADDRESSED:` output). Only `unaffected: <reason>` lines justify a site outside the change set; the match is by file path (the line number is optional, lines shift). A file you changed needs no line. `unresolved` lines are written by validate V5 for sites left unaddressed after the one repair round (a recorded known risk for review): they never justify a site and you do not write them by hand. Omit the block when there are no sites.
+
+### Edge Case Coverage
+EDGE_TEST: id=e1 test={path}::{test_name}
+EDGE_TEST: id=e2 untestable={reason}
+
+> **Edge case block**: one line per `EDGE:` id of the architect's `FORGE:EDGE_CASES` block, each line starting at the line start (no prose before `EDGE_TEST:`). `test=` names a file and a test name (a single token with no whitespace; name the test with underscores or hyphens) that occurs in a line this change adds to that file; a pre-existing test does not count. `untestable=` needs a non-empty reason. Omit the section when the plan has no edge cases.
+
 ### Testing Checklist
 - [ ] {Test scenario 1} [type:api]
 - [ ] {Test scenario 2} [type:unit]