forgedock 1.1.1 → 1.1.2

package/commands/test-gate.md

@@ -2,6 +2,7 @@
 description: Deterministic deploy-gate — verify a staging→main bundle's acceptance criteria against running code before deploy
 argument-hint: [--prs "<N1 N2 ...>"] [--base <branch>]
 allowed-tools: Task, Bash, Read, Grep, Glob
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -12,7 +13,22 @@ allowed-tools: Task, Bash, Read, Grep, Glob
 
 Verifies a staging→main bundle's acceptance criteria against running code before deploy. Called by `/review-pr-staging` (Phase 6.5) with the bundle PRs, or run standalone when `--prs` is absent (computes the bundle itself). Returns a machine-readable BLOCK / PASS / SKIP verdict for the caller to consume.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**NEVER use plan mode (EnterPlanMode).**
+**NEVER use the Agent tool** — test-gate dispatches test clusters via `Task` only. The Agent tool bypasses the allowed-tools constraint and produces output that cannot be structured into the machine-readable BLOCK / PASS / SKIP verdict.
+
+<!-- FORGE:SPEC_LOADED — test-gate.md loaded and active. Agent is bound by this spec. -->
+
+## Forbidden Tools Self-Check
+
+**Before executing any phase**, verify you are NOT using any of these tools:
+
+| Tool | Status | Reason |
+|------|--------|--------|
+| `Agent` | **FORBIDDEN** | Bypasses allowed-tools constraint; produces unstructured output that cannot be parsed into the machine-readable BLOCK / PASS / SKIP verdict |
+| `EnterPlanMode` | **FORBIDDEN** | Breaks execution context; gate phases must execute, not be planned |
+
+If you find yourself about to call `Agent(...)`, stop and use `Task(...)` instead.
 
 **Posture**: Blocking-with-override at the staging→main boundary (mirrors the Phase 0A open-finding gate in `/review-pr-staging`). Posture is config-driven via `verification.test_gate`.
 

package/commands/validate.md

@@ -1,6 +1,7 @@
 ---
 description: Independently verify if a reported issue is actually a problem before making code changes.
 argument-hint: [issue description or #number]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -11,7 +12,7 @@ argument-hint: [issue description or #number]
 
 Verify whether a reported issue is real before anyone writes code. This command exists for reports that come from outside the pipeline — user complaints, DevOps alerts, monitoring triggers, gut feelings. It is the checkpoint before creating a GitHub issue.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 **Output**: A verdict (CONFIRMED / NOT A PROBLEM / NEEDS MORE DATA) with evidence.
 

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

@@ -11,6 +11,11 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFE
 **Time budget**: Max 3 minutes. Skip any file read that times out.
 **Output**: Post `<!-- FORGE:ARCHITECT -->` comment on the issue, then return structured plan to caller.
 
+**Agent model policy**: `model: "sonnet"`, `effort: xhigh` (deep tier — full code-path tracing, multi-file architecture planning). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` only on Claude Code >= 2.1.154.
+**NEVER use plan mode (EnterPlanMode).**
+
+<!-- FORGE:SPEC_LOADED — work-on/build/architect.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## COMPLEXITY_BAND Guard (check BEFORE all phases)
@@ -50,6 +55,7 @@ Parse from $ARGUMENTS:
 Also read from the calling context (in-memory, passed by parent agent):
 - `{INVESTIGATION_REPORT}` — full text of FORGE:INVESTIGATOR comment
 - `{CONTEXT_BRIEFING}` — full text of FORGE:CONTEXT comment (empty string if context step was skipped)
+- `{MEMORY_PRIORS}` — structured prior run blocks emitted by investigate Phase 0.5 (empty string if no priors found or investigate predates memory). When non-empty, treat each `[MEMORY PRIOR]` block as a high-confidence prior: if any prior's affected files overlap with the current plan's affected files, explicitly note the prior's root cause and key lesson in the FORGE:ARCHITECT comment's **Prior Run Priors** section (add this section after **Context Briefing** when priors exist). <!-- Added: forge#1316 -->
 
 If any of these are not passed directly, read them from GitHub (fallback/recovery path):
 
@@ -316,6 +322,28 @@ agent defaults                  ← Built-in behaviors
 
 Identify every entry point that initiates the affected logic. Start from the files named in the investigation report.
 
+### A1.0: Code Index Query (run FIRST — deterministic, one tool call)
+
+If `scripts/code-index.sh` exists under `{REPO_PATH}`, query the pre-built index before any grep. The index provides caller lists and import graphs without re-scanning the repo:
+
+```bash
+# Ensure index is current (cache-hit on unchanged HEAD — instant if already built)
+bash {REPO_PATH}/scripts/code-index.sh --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Get callers of the primary function under change
+bash {REPO_PATH}/scripts/code-index.sh query --callers {PRIMARY_FUNCTION} --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Get all files that import the affected module
+bash {REPO_PATH}/scripts/code-index.sh query --importers {AFFECTED_FILE} --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Get all files in the same domain as affected files (for sibling path detection)
+bash {REPO_PATH}/scripts/code-index.sh query --domain {DOMAIN} --repo-path {REPO_PATH} 2>/dev/null || true
+```
+
+Use index results to populate the caller list and sibling candidates below. If the index returns results, **skip the grep fallback** — do not re-scan what the index already answered. If the index is absent or returns nothing, fall back to grep.
+
+### A1.1: Grep fallback (only when index absent or returned no results)
+
 For each affected file, read it and identify:
 1. The primary function/method being changed
 2. All callers of that function (grep for usages)

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

@@ -11,6 +11,8 @@ argument-hint: [issue number] [affected_files...] [--functions function_names...
 **Time budget**: Max 2 minutes of queries. Skip any query that times out.
 **Output**: Post `<!-- FORGE:CONTEXT -->` comment on the issue, then return structured briefing to caller.
 
+<!-- FORGE:SPEC_LOADED — work-on/build/context.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## COMPLEXITY_BAND Guard (check BEFORE all phases)

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

@@ -12,9 +12,11 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 **Invoked by**: `work-on.md` Step 3F, after worktree is created and context is gathered.
 **Output**: Write code, commit(s), post `<!-- FORGE:BUILDER -->` comment, return result to caller.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
+<!-- FORGE:SPEC_LOADED — work-on/build/implement.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Inputs

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

@@ -12,9 +12,11 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 **Invoked by**: `work-on.md` Step 3F.5, after `implement.md` has written and staged code (not committed).
 **Output**: Return `GATE_PASSED: true/false` to caller. On failure after max iterations, post comment and set `needs-human`.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
+<!-- FORGE:SPEC_LOADED — work-on/build/validate.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Inputs
@@ -52,10 +54,22 @@ while iteration < max_iterations:
         GATE_PASSED = true
         break
     else:
-        Fix each HIGH and MEDIUM finding in the code at {WORKTREE_PATH}
-        (Do NOT commit yet — fixes are staged for the next gate run)
-
-if iteration == max_iterations AND result != PASS:
+        # Separate quarantined test findings from real blocker findings.
+        # quality-gate Step 2R classifies each failing test as PRE_BROKEN, FLAKY, or REAL.
+        # TEST-QUARANTINE findings (LOW) are advisory — do not fix, do not count as gate failures.
+        # TEST-REAL findings (HIGH) and all other HIGH/MEDIUM findings must be fixed.
+        quarantine_findings = findings where severity == LOW and code starts with "TEST-QUARANTINE"
+        blocker_findings    = findings where code != "TEST-QUARANTINE"
+
+        if blocker_findings is empty:
+            # All remaining findings are quarantined tests — gate passes from the builder's perspective.
+            GATE_PASSED = true
+            break
+        else:
+            Fix each HIGH and MEDIUM finding in blocker_findings at {WORKTREE_PATH}
+            (Do NOT commit yet — fixes are staged for the next gate run)
+
+if iteration == max_iterations AND result != PASS AND blocker_findings not empty:
     GATE_PASSED = false
     → post comment (see V1-FAIL below)
     → add label needs-human
@@ -71,6 +85,7 @@ Skill("quality-gate", args="{CHANGED_FILES} --worktree {WORKTREE_PATH}")
 - Re-run after EVERY fix pass — never trust that fixes resolved findings without verification
 - Each iteration re-scans ALL changed files — fixes can introduce new issues
 - Only HIGH and MEDIUM findings must be fixed; LOW findings are advisory only
+- `TEST-QUARANTINE | LOW` findings (pre-broken or flaky tests classified by Step 2R) do **not** require fixing and do **not** count toward gate failure — include them in the V5 commit comment for reviewer visibility
 
 **V1-FAIL comment** (post when gate never passes):
 ```bash
@@ -305,9 +320,13 @@ BUILDER_COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
 
 if [ -n "$BUILDER_COMMENT_ID" ]; then
-  # Fetch current body and append the completion marker
+  # Fetch current body and append the completion marker plus best-effort cost signal
   CURRENT_BODY=$(gh api repos/{GH_REPO}/issues/comments/$BUILDER_COMMENT_ID --jq '.body')
-  UPDATED_BODY="${CURRENT_BODY}
+  # Best-effort cost append: only include if session telemetry provides a value; never block
+  PHASE_COST_LINE=""
+  [ -n "${PHASE_COST_USD:-}" ] && PHASE_COST_LINE="
+cost_usd: ${PHASE_COST_USD}"
+  UPDATED_BODY="${CURRENT_BODY}${PHASE_COST_LINE}
 
 <!-- FORGE:BUILDER:COMPLETE -->"
   gh api repos/{GH_REPO}/issues/comments/$BUILDER_COMMENT_ID \

package/commands/work-on/build.md

@@ -10,12 +10,30 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BA
 **Input**: $ARGUMENTS
 
 **Invoked by**: `work-on.md` Phase 3 — entered when the issue carries label `workflow:ready-to-build` or `workflow:building` (see Universal Phase Dispatcher in work-on.md).
-**Output**: Create worktree, post contract, sequence build subcommands, return result to work-on.md.
+**Output**: Create worktree, post contract, run build phases, return result to work-on.md.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
-**CRITICAL: You MUST execute ALL phases B0–B6 in order. After each Skill() call returns, you MUST continue to the next phase. Phases B3 (context) and B4 (architect) are skipped ONLY when COMPLEXITY_BAND: TRIVIAL (read from FORGE:FAST_PATH comment in Phase B0). For STANDARD and COMPLEX tasks they are NOT optional — skipping them degrades build quality.**
+**CRITICAL: You MUST execute ALL phases B0–B6 in order. Phases B3 (context) and B4 (architect) are skipped ONLY when COMPLEXITY_BAND: TRIVIAL (read from FORGE:FAST_PATH comment in Phase B0). For STANDARD and COMPLEX tasks they are NOT optional — skipping them degrades build quality.**
+
+### Canonical Build Path (STANDARD/fast-lane) <!-- Added: forge#1276 -->
+
+**Default execution model: inline.** For STANDARD and fast-lane issues, phases B3 (context gathering) and B4 (architecture planning) run **inline in the current context window** — not as separate `Skill()` sub-agent spawns. B5 (implement) and B6 (validate) also run inline.
+
+`Skill()` invocations for context/architect sub-phases are only permitted when the Spawn-Decision Table (work-on.md `##Spawn-Decision Policy`) explicitly applies — specifically Row (c) (parent context near overflow: ≥20 Skill invocations or ≥10 files already changed before the build sub-phase). For most issues, the Skill() forms shown in B3 and B4 below are **reference documentation** describing the sub-phase contract, not mandatory sub-agent invocations.
+
+**Build topology summary**:
+
+| Path | When | Phases |
+|------|------|--------|
+| **STANDARD/fast-lane (default)** | All issues not matching exceptions below | B0 → B1 → B2 → B2.5 → [B3] → [B4] → B5 → B6 — all inline |
+| **Spawn exception (Row c)** | ≥20 Skill invocations OR ≥10 files changed before build | Spawn B3/B4 as fresh sub-agents via `Skill()` |
+| **TRIVIAL fast-path** | COMPLEXITY_BAND: TRIVIAL | Skip B3 and B4 entirely |
+
+This resolves the three-topology conflict: `work-on.md` Phase 3 (inline 3A–3M), `work-on/build.md` (this file), and `work-on-monolithic.md` ([BENCHMARK]) all describe the **same canonical inline path**. `work-on/build.md` adds worktree lifecycle management (B1) and the FORGE:CONTRACT handoff (B2) that the monolithic variant omits for brevity. The `Skill()` forms in B3/B4 below document the sub-phase contract and serve as the exception path only. <!-- Added: forge#1276 -->
+
+<!-- FORGE:SPEC_LOADED — work-on/build.md loaded and active. Agent is bound by this spec. -->
 
 ---
 
@@ -27,6 +45,8 @@ Parse from $ARGUMENTS:
 - `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--base {PR_BASE}` — PR target branch (e.g. `milestone/modular-pipeline-architecture` or `staging`)
 
+**Phase notation**: This file uses **B0–B6** for its own phases. The calling orchestrator (`work-on.md`) uses **3A–3M** for its sub-phases. Mapping: work-on.md Phase 3A = B0 (load state), Phase 3B = complexity classification (posts `FORGE:FAST_PATH` before invoking build), Phase 3C onward maps to B1+ in this file. When cross-references mention "Phase 3B", they refer to work-on.md's Phase 3B, not a phase in this file. <!-- Added: forge#1380 -->
+
 ---
 
 ## Phase B0: Load State from GitHub (MANDATORY)
@@ -64,7 +84,7 @@ Extract from investigation report:
 - Recommendation
 - Task type (Bug Fix / Feature / Refactor / Maintenance / UI/UX / Full-Stack)
 
-**Read COMPLEXITY_BAND** (from FORGE:FAST_PATH comment posted by Phase 3B):
+**Read COMPLEXITY_BAND** (from `FORGE:FAST_PATH` comment posted by Phase 3B of `work-on.md` — the complexity classification step that runs before invoking this file): <!-- Fixed: forge#1380 -->
 ```bash
 COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:FAST_PATH")) | .body' 2>/dev/null \
@@ -192,44 +212,46 @@ If `FUNCTION_NAMES` is non-empty, it will be passed via `--functions` to the con
 
 ## Phase B3: Context Gathering (MANDATORY for STANDARD/COMPLEX — skip for TRIVIAL)
 
-**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — do not invoke the context subcommand. Proceed directly to Phase B4.
+**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — skip this phase entirely. Proceed directly to Phase B4.
 
-**For STANDARD and COMPLEX tasks**: Always invoke. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
+**For STANDARD and COMPLEX tasks**: Always run. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
 
-Invoke the context subcommand to surface historical review findings and bug patterns:
+**Execution model**: Run **inline** (see Canonical Build Path above). Read the `commands/work-on/build/context.md` spec and execute its steps directly in this context window. Only spawn a Skill() sub-agent when the Spawn-Decision Table Row (c) applies (≥20 prior Skill invocations or ≥10 files already changed). <!-- Added: forge#1276 -->
 
-```
-Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} {AFFECTED_FILES} --functions {FUNCTION_NAMES}")
-```
-
-If `FUNCTION_NAMES` is empty, omit the `--functions` flag entirely:
+Surface historical review findings and bug patterns for the affected files. The full step-by-step logic is defined in `commands/work-on/build/context.md`. Key steps: search closed issues with `review-finding` label on the affected files; check git log for past bug patterns; synthesize a `FORGE:CONTEXT` annotation and post it as a GitHub comment.
 
+**Spawn exception** (only when Row (c) applies):
 ```
-Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} {AFFECTED_FILES}")
+Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} {AFFECTED_FILES} --functions {FUNCTION_NAMES}")
 ```
+If `FUNCTION_NAMES` is empty, omit `--functions`. The Skill() form above is the exception path — not the default. <!-- Added: forge#1276 -->
 
-**After subcommand returns**:
-- Returns structured context briefing (or indicates no relevant history) → continue to B4
-- If subcommand times out or errors → log warning, continue to B4 with empty context (non-blocking)
+**After context gathering**:
+- Structured context briefing produced (or no relevant history found) → continue to B4
+- Context gathering timed out or errored → log warning, continue to B4 with empty context (non-blocking)
 # MUST CONTINUE to Phase B4 — context result is intermediate, NOT terminal.
 
 ---
 
 ## Phase B4: Architecture Planning (MANDATORY for STANDARD/COMPLEX — skip for TRIVIAL)
 
-**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — do not invoke the architect subcommand. Proceed directly to Phase B5.
+**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — skip this phase entirely. Proceed directly to Phase B5.
 
-**For STANDARD and COMPLEX tasks**: Always invoke. Even a 1-file STANDARD fix benefits from cross-path consistency checks. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
+**For STANDARD and COMPLEX tasks**: Always run. Even a 1-file STANDARD fix benefits from cross-path consistency checks. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
 
-Invoke the architect subcommand to trace all affected code paths and produce an ordered implementation plan:
+**Execution model**: Run **inline** (see Canonical Build Path above). Read the `commands/work-on/build/architect.md` spec and execute its steps directly in this context window. Only spawn a Skill() sub-agent when the Spawn-Decision Table Row (c) applies. <!-- Added: forge#1276 -->
 
+Trace all affected code paths and produce an ordered implementation plan. The full step-by-step logic is defined in `commands/work-on/build/architect.md`. Key steps: map all callers and importers of changed functions; check consistency rules across paths; post a `FORGE:ARCHITECT` annotation with the ordered plan and a risk table.
+
+**Spawn exception** (only when Row (c) applies):
 ```
 Skill("work-on:build:architect", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} --files {AFFECTED_FILES}")
 ```
+The Skill() form above is the exception path — not the default. <!-- Added: forge#1276 -->
 
-**After subcommand returns**:
+**After architecture planning**:
 - Returns ordered implementation plan → continue to B5
-- If subcommand returns BLOCKED → post comment, add `needs-human`, return `BUILD_RESULT: status: BLOCKED`
+- BLOCKED (conflicting constraints that cannot be resolved inline) → post comment, add `needs-human`, return `BUILD_RESULT: status: BLOCKED`
 # MUST CONTINUE to Phase B5 — architect result is intermediate, NOT terminal.
 
 ---
@@ -262,9 +284,126 @@ Skill("work-on:build:validate", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FL
 Where `{CHANGED_FILES}` is the space-separated list of files changed by the implement subcommand (read from `IMPLEMENT_RESULT` or from the `<!-- FORGE:BUILDER -->` comment).
 
 **After subcommand returns**:
-- `VALIDATE_RESULT: gate_passed: true` → write checkpoint, then return `BUILD_RESULT: status: COMPLETE`
+- `VALIDATE_RESULT: gate_passed: true` → continue to Phase B6.5 (acceptance gate)
 - `VALIDATE_RESULT: gate_passed: false` → subcommand has already posted comment and added `needs-human` label; return `BUILD_RESULT: status: BLOCKED`
 
+---
+
+## Phase B6.5: Acceptance Gate (MANDATORY — cannot be silently skipped) <!-- Added: forge#1315 -->
+
+**Goal**: Execute the machine-checkable acceptance spec emitted by investigate Phase 1C and block merge if any check fails. This is a hard gate — not advisory.
+
+**Read acceptance spec from FORGE:INVESTIGATOR comment**:
+
+```bash
+ACCEPTANCE_CHECKS=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' \
+  | grep "^ACCEPTANCE_CHECK:" )
+```
+
+**If `ACCEPTANCE_CHECKS` is empty** (investigation predates this feature or comment was deleted): post a warning comment and **block** — do not silently pass:
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ACCEPTANCE_GATE -->
+## Acceptance Gate — No Spec Found
+
+No \`ACCEPTANCE_CHECK:\` lines found in the FORGE:INVESTIGATOR comment. This may mean:
+- The investigation was run before acceptance spec emission was added (re-run investigate to generate the spec), or
+- The investigator comment was deleted.
+
+**Gate result: BLOCKED** — re-run \`/work-on:investigate {NUMBER}\` to regenerate the acceptance spec, then retry the build.
+
+<!-- FORGE:ACCEPTANCE_GATE:BLOCKED -->"
+gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+```
+Return `BUILD_RESULT: status: BLOCKED`, blocker: "No acceptance spec — re-run investigate to emit ACCEPTANCE_CHECK lines".
+
+**If all checks are `type=skipped`**: post a pass comment noting human review is required, then continue to the checkpoint (non-blocking — skip was deliberate):
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ACCEPTANCE_GATE -->
+## Acceptance Gate — Skipped (No Machine-Checkable Criteria)
+
+The acceptance spec contains only a skip sentinel (\`type=skipped\`). No automated checks were run. Human review is required before merge.
+
+<!-- FORGE:ACCEPTANCE_GATE:PASSED -->"
+```
+
+**Otherwise — execute each check**:
+
+```bash
+GATE_PASS=true
+FAILED_CHECKS=""
+
+while IFS= read -r check_line; do
+  ID=$(echo "$check_line"    | sed -n 's/.*id=\([^ ]*\).*/\1/p')
+  TYPE=$(echo "$check_line"  | sed -n 's/.*type=\([^ ]*\).*/\1/p')
+  TARGET=$(echo "$check_line"| sed -n 's/.*target=\([^ ]*\).*/\1/p')
+  MATCHER=$(echo "$check_line"| sed -n 's/.*matcher=\([^ ]*\).*/\1/p')
+  DESC=$(echo "$check_line"  | sed -n 's/.*description=\(.*\)/\1/p')
+
+  [ "$TYPE" = "skipped" ] && continue
+
+  RESULT="PASS"
+  DETAIL=""
+
+  case "$TYPE" in
+    exists)
+      [ -e "$TARGET" ] || { RESULT="FAIL"; DETAIL="path not found: $TARGET"; }
+      ;;
+    contains)
+      grep -qE "$MATCHER" "$TARGET" 2>/dev/null || { RESULT="FAIL"; DETAIL="'$MATCHER' not found in $TARGET"; }
+      ;;
+    command|behavior)
+      if [ "$MATCHER" = "exit_0" ]; then
+        eval "$TARGET" >/dev/null 2>&1 || { RESULT="FAIL"; DETAIL="command exited non-zero: $TARGET"; }
+      else
+        OUTPUT=$(eval "$TARGET" 2>&1)
+        echo "$OUTPUT" | grep -qE "$MATCHER" || { RESULT="FAIL"; DETAIL="output did not match '$MATCHER'. Got: $(echo "$OUTPUT" | head -3)"; }
+      fi
+      ;;
+    *)
+      RESULT="FAIL"; DETAIL="unknown check type: $TYPE"
+      ;;
+  esac
+
+  if [ "$RESULT" = "FAIL" ]; then
+    GATE_PASS=false
+    FAILED_CHECKS="${FAILED_CHECKS}\n- **$ID** ($DESC): $DETAIL"
+  fi
+done <<< "$ACCEPTANCE_CHECKS"
+```
+
+**Post gate result comment**:
+
+```bash
+if [ "$GATE_PASS" = "true" ]; then
+  gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ACCEPTANCE_GATE -->
+## Acceptance Gate — PASSED
+
+All machine-checkable acceptance criteria verified against real behavior.
+
+<!-- FORGE:ACCEPTANCE_GATE:PASSED -->"
+else
+  gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ACCEPTANCE_GATE -->
+## Acceptance Gate — FAILED
+
+The following acceptance checks did not pass:
+
+$(echo -e "$FAILED_CHECKS")
+
+Merge is blocked. Fix the failing criteria and re-run the validate phase.
+
+<!-- FORGE:ACCEPTANCE_GATE:FAILED -->"
+  gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+  # Return BLOCKED — merge gate failed
+fi
+```
+
+If `GATE_PASS = false`: return `BUILD_RESULT: status: BLOCKED`, blocker: "Acceptance gate failed — see FORGE:ACCEPTANCE_GATE comment".
+
+If `GATE_PASS = true`: continue to write the phase checkpoint below.
+
 **When gate_passed is true — write machine-readable phase checkpoint before returning (MANDATORY)**:
 ```bash
 CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -295,8 +434,8 @@ BUILD_RESULT:
 This module runs during **Phase 3** of the work-on.md pipeline (label: `workflow:ready-to-build` or `workflow:building`). The full sequence is defined by the Universal Phase Dispatcher in work-on.md:
 
 ```
-Phase 3 (Build)   → [THIS MODULE] worktree + contract + context + architect + implement + validate
-                  → posts FORGE:BUILDER comment, writes FORGE:CHECKPOINT next_phase=REVIEW
+Phase 3 (Build)   → [THIS MODULE] worktree + contract + context + architect + implement + validate + acceptance-gate
+                  → posts FORGE:BUILDER comment + FORGE:ACCEPTANCE_GATE comment, writes FORGE:CHECKPOINT next_phase=REVIEW
 Phase 4 (PR)      → work-on:review — push branch, create PR, set workflow:in-review
 Phase 5 (Review)  → work-on:review — invoke /review-pr --auto-merge
 Phase 6 (Close)   → work-on:close — trajectory + parent tracker + summary + worktree cleanup

package/commands/work-on/close.md

@@ -12,9 +12,11 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMB
 **Invoked by**: `work-on.md` Phase 6–7, after `review.md` returns `REVIEW_RESULT: status: COMPLETE`.
 **Output**: Update project board, close issue, update parent tracker, post trajectory log. Return final summary.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical tier — label transitions, annotation posting, board updates). Fallback: `model: "sonnet"` if rate-limited. Feature gate: pass `effort` only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
+<!-- FORGE:SPEC_LOADED — work-on/close.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Inputs
@@ -183,9 +185,11 @@ ISSUE_STATE=$(gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state')
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:PHASE:COMPLETE -->
 Phase complete. PR #{PR_NUMBER} merged to \`{PR_BASE}\`. ${REMAINING_AFTER} phase item(s) remain — leaving issue open for next pipeline iteration."
 
-# Update labels to reflect phase complete (not yet fully merged)
+# Update labels to reflect phase complete — remove current-phase labels and set next-phase label
+# so the router has a signal for which phase comes next (fixes: issue #1381)
 gh issue edit {NUMBER} {GH_FLAG} \
-  --remove-label "workflow:in-review,workflow:building,workflow:investigating" 2>/dev/null || true
+  --remove-label "workflow:in-review,workflow:building,workflow:investigating" \
+  --add-label "workflow:investigating" 2>/dev/null || true
 
 # EXIT — do not close, do not post trajectory, do not run C3–C6
 # Return CLOSE_RESULT: status: PHASE_COMPLETE to caller
@@ -444,6 +448,129 @@ Where:
 
 ---
 
+## Phase C5.2: Memory Index Update <!-- Added: forge#1316 -->
+
+**Goal**: Append this run's learnings to the per-repo memory index so future `investigate` runs can retrieve relevant priors. This is the write side of the compounding intelligence loop.
+
+**This phase is non-blocking** — if Gist creation or update fails, log the reason and continue to Phase C5.5. Never stall close for memory.
+
+**Skip if**: Terminal state is `INVALID` (nothing useful to learn from an invalid issue) OR `<!-- FORGE:TRAJECTORY -->` was already posted AND `<!-- FORGE:MEMORY_INDEXED -->` comment exists on the issue (idempotency guard).
+
+### Step 1: Compose memory entry
+
+Extract key fields from the pipeline:
+
+```bash
+ROOT_CAUSE=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' \
+  | sed -n '/### Root Cause/{n;p;q}' | head -1 | cut -c1-120)
+
+AFFECTED_FILES_BRIEF=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' \
+  | sed -n '/### Affected Files/{n;p;q}' | head -1 | cut -c1-120)
+
+DOMAIN_TAGS=$(gh issue view {NUMBER} {GH_FLAG} --json labels \
+  --jq '[.labels[].name | select(test("^(auth|billing|database|security|payments|gdpr|perf|ui|api|config)"))] | join(",")' 2>/dev/null || echo "")
+
+MEMORY_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+MEMORY_ENTRY="MEMORY_ENTRY: issue={NUMBER} title=\"{TITLE}\" domain=\"${DOMAIN_TAGS}\" root_cause=\"${ROOT_CAUSE}\" outcome=\"${CARD_STATUS}\" files=\"${AFFECTED_FILES_BRIEF}\" lesson=\"${ROOT_CAUSE}\" timestamp=${MEMORY_TIMESTAMP}"
+```
+
+### Step 2: Find or create the memory index Gist
+
+```bash
+MEMORY_INDEX_ID=$(gh gist list --limit 100 \
+  --jq '.[] | select(.description | contains("FORGE:MEMORY_INDEX: {GH_REPO}")) | .id' 2>/dev/null | head -1)
+
+if [ -z "$MEMORY_INDEX_ID" ]; then
+  # First run — create the index Gist
+  TMPFILE=$(mktemp --suffix=.md)
+  cat > "$TMPFILE" <<GIST_EOF
+# ForgeDock Memory Index — {GH_REPO}
+<!-- FORGE:MEMORY_INDEX: {GH_REPO} -->
+Generated by ForgeDock close phase. Each line is a prior pipeline run.
+
+${MEMORY_ENTRY}
+GIST_EOF
+  # Memory gists MUST be secret — never pass --public here (forge#1587).
+  # The entry content below embeds real issue titles, root causes, and file
+  # paths; for a private consumer repo, --public would publish that content
+  # to a world-readable Gist. `gh gist create` is secret by default, so
+  # simply omitting --public is sufficient — the read side (investigate.md
+  # Phase 0.5, via `gh gist view`/`gh gist list`) works unchanged against
+  # secret gists for the authenticated owner.
+  MEMORY_INDEX_URL=$(gh gist create "$TMPFILE" \
+    --desc "FORGE:MEMORY_INDEX: {GH_REPO} — per-codebase learning index" \
+    2>/dev/null | head -1)
+  MEMORY_INDEX_ID=$(echo "$MEMORY_INDEX_URL" | sed 's|.*/||')
+  rm -f "$TMPFILE"
+  echo "[MEMORY] Created memory index Gist: ${MEMORY_INDEX_URL}"
+else
+  # Append to existing index
+  EXISTING_CONTENT=$(gh gist view "$MEMORY_INDEX_ID" 2>/dev/null)
+  UPDATED_CONTENT="${EXISTING_CONTENT}
+${MEMORY_ENTRY}"
+  INDEX_FILENAME=$(gh api gists/${MEMORY_INDEX_ID} --jq '.files | keys[0]' 2>/dev/null)
+  INDEX_FILENAME="${INDEX_FILENAME:-memory_index.md}"
+  TMPFILE=$(mktemp --suffix=.md)
+  echo "$UPDATED_CONTENT" > "$TMPFILE"
+  gh gist edit "$MEMORY_INDEX_ID" -f "$INDEX_FILENAME" "$TMPFILE" 2>/dev/null
+  EDIT_EXIT=$?
+  rm -f "$TMPFILE"
+  MEMORY_INDEX_URL="https://gist.github.com/${MEMORY_INDEX_ID}"
+  if [ $EDIT_EXIT -eq 0 ]; then
+    echo "[MEMORY] Appended to memory index: ${MEMORY_INDEX_URL}"
+  else
+    echo "WARNING: Failed to update memory index — run will not be persisted"
+    MEMORY_INDEX_URL=""
+  fi
+fi
+```
+
+### Migration: replacing an existing public memory-index Gist
+
+GitHub does not support flipping a Gist's visibility from public to secret in place. If you find an existing `FORGE:MEMORY_INDEX: {GH_REPO}` Gist that is **public** (check with `gh api gists/${MEMORY_INDEX_ID} --jq '.public'`), replace it:
+
+```bash
+# The gist ID here is the same one found by the FORGE:MEMORY_INDEX search above.
+OLD_PUBLIC_GIST_ID="$MEMORY_INDEX_ID"
+
+# 1. Save the existing content so no learnings are lost — and verify the save
+#    succeeded BEFORE deleting anything.
+gh gist view "$OLD_PUBLIC_GIST_ID" > /tmp/memory_index_migrate.md
+if [ ! -s /tmp/memory_index_migrate.md ]; then
+  echo "ABORT: failed to save gist content — not deleting the public gist." >&2
+  exit 1
+fi
+
+# 2. Delete the public gist (removes the world-readable copy)
+gh gist delete "$OLD_PUBLIC_GIST_ID" --yes
+
+# 3. Recreate it secret (no --public) with the same description tag so the
+#    next close/investigate run finds it via the FORGE:MEMORY_INDEX search
+gh gist create /tmp/memory_index_migrate.md \
+  --desc "FORGE:MEMORY_INDEX: {GH_REPO} — per-codebase learning index"
+```
+
+This is a one-time manual step per affected repo — Phase C5.2 itself only ever creates the index once (Step 2's `if [ -z "$MEMORY_INDEX_ID" ]` branch) and appends afterward, so a stale public gist is never auto-recreated secret on its own.
+
+### Step 3: Post audit annotation on the issue
+
+```bash
+if [ -n "$MEMORY_INDEX_URL" ]; then
+  gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:MEMORY_INDEXED -->
+This run has been indexed in the per-repo memory: ${MEMORY_INDEX_URL}
+
+Future \`investigate\` runs on \`{GH_REPO}\` will retrieve this entry as a prior when working on related issues.
+
+<!-- FORGE:MEMORY_INDEXED:COMPLETE -->"
+  echo "[MEMORY] Indexed issue #{NUMBER} into memory at: ${MEMORY_INDEX_URL}"
+fi
+```
+
+---
+
 ## Phase C5.5: Graph Decision Record (MANDATORY when PR exists)
 
 **Skip if**: `{PR_NUMBER}` is empty OR `<!-- FORGE:DECISION_RECORD -->` already posted on the PR.

package/commands/work-on/decompose.md

@@ -12,7 +12,7 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
 **Invoked by**: `work-on.md` routing loop, when `INVESTIGATE_RESULT.decompose = YES`.
 **Output**: Create sub-issues, update parent tracker, post `<!-- FORGE:DECOMPOSED -->` comment, set labels. STOP — each sub-issue runs its own /work-on.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---
@@ -108,6 +108,24 @@ For each sub-issue, prepare:
 
 For each sub-issue (in dependency order):
 
+**Before creating each sub-issue, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+
+```bash
+SUB_TITLE="{fix|feat|refactor}: {SUB_ISSUE_TITLE}"
+DEDUP_RESULT=$(scripts/issue-dedup.sh "$SUB_TITLE" {GH_FLAG} 2>&1)
+DEDUP_EXIT=$?
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "DEDUP: Sub-issue near-duplicate detected — $DEDUP_RESULT"
+  echo "Skipping creation. Comment on the existing issue instead."
+  # Do NOT call gh issue create for this sub-issue
+elif [ "$DEDUP_EXIT" -eq 2 ]; then
+  echo "DEDUP: Usage error — $DEDUP_RESULT"
+  # Do NOT call gh issue create for this sub-issue — fix the invocation and retry
+fi
+```
+
+Only call `gh issue create` when the dedup script exits 0 (no match):
+
 ```bash
 gh issue create {GH_FLAG} \
   --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \