forgedock 1.8.1 → 1.8.2

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

@@ -1,15 +1,18 @@
 ---
 description: Pre-implementation architecture planning — traces ALL affected code paths and produces an ordered implementation plan before any code is written
-argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFECTED_FILES]"
+argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE} --files \"<space-separated>\""
+context: fork
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/architect — Multi-Path Implementation Planning
 
-**Invoked by**: `work-on.md` Step 3C.6, between Context Gathering and Implement.
+> **Skill Name Resolution (forked phase)**: `{FORGE_SKILL_PREFIX}` is the namespace this skill itself was invoked under — invoked as `forgedock:work-on:…` → `forgedock:` (nesting `:`); as `work-on:…` → empty (`install.sh`); as `forge-work-on-…` → `forge-` (Codex, nesting `-`); OpenCode → empty with `-` nesting. Confirm the target name in the available-skills list before calling it. A forked phase receives no resolved value from its caller; never guess, and if the target skill is not listed return BLOCKED "skill not found: <name>".
+
+**Invoked by**: `work-on:build` (phase B4), between Context Gathering and Implement, via `Skill()`. Runs in its own forked context: you see only this spec and your args — re-read all other state from GitHub/git.
 **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.
+**Output**: Post `<!-- FORGE:ARCHITECT -->` comment on the issue, then print exactly one `ARCHITECT_RESULT:` block (see Result Block) as your final reply. Every exit path — success, partial, skip, resume-complete, blocked — prints it.
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "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).**
@@ -29,7 +32,7 @@ COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
 ```
 
-**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (A0 through A5), **post the minimal skip marker comment described in "Skip Marker" under Skip Conditions below** (reason: `TRIVIAL complexity band`), then return an empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. The skip marker (ending in `<!-- FORGE:ARCHITECT:COMPLETE -->`) is what makes a legitimate skip observable to the headless engine's marker-only gate, so the issue advances to build instead of being stranded at `needs-human`. <!-- Added: forge#679; skip-marker on skip: forge#2689 -->
+**If COMPLEXITY_BAND: TRIVIAL or INVESTIGATION** → skip all phases (A0 through A5), **post the minimal skip marker comment described in "Skip Marker" under Skip Conditions below** (reason: `TRIVIAL complexity band` or `INVESTIGATION complexity band`), then print `ARCHITECT_RESULT:` with `status: SKIPPED` immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. The skip marker (ending in `<!-- FORGE:ARCHITECT:COMPLETE -->`) is what makes a legitimate skip observable to the headless engine's marker-only gate, so the issue advances to build instead of being stranded at `needs-human`. <!-- Added: forge#679; skip-marker on skip: forge#2689 -->
 
 **If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase A0 below.
 
@@ -50,14 +53,16 @@ Parse from $ARGUMENTS:
 - `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
 - `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--repo-path {REPO_PATH}` — local filesystem path to the worktree (e.g. `/path/to/.claude/worktrees/fix/issue-121`); used by Phase A1 grep commands
-- `--files {AFFECTED_FILES}` — space-separated list of files from investigation report (passed by `build.md` Phase B4)
+- `--files "{AFFECTED_FILES}"` — space-separated list of files from investigation report (quoted as one value; passed by `work-on:build` phase B4; empty triggers the empty-list skip)
+
+**Fail closed**: if `{NUMBER}`, `--repo`, `--gh-flag` or `--repo-path` is missing, print `ARCHITECT_RESULT:` with `status: BLOCKED`, `comment_url:` empty and `blocker: missing arg <name>`, and stop.
 
-Also read from the calling context (in-memory, passed by parent agent):
+You receive no state from the caller. Re-derive everything from GitHub below:
 - `{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):
+Read them from GitHub:
 
 ```bash
 # Read investigation report
@@ -80,7 +85,7 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:ARCHITECT")) | .body'
 ```
 
-- If `<!-- FORGE:ARCHITECT -->` comment exists AND `<!-- FORGE:ARCHITECT:COMPLETE -->` is present in the SAME comment → plan already complete, return existing plan to caller, EXIT.
+- If `<!-- FORGE:ARCHITECT -->` comment exists AND `<!-- FORGE:ARCHITECT:COMPLETE -->` is present in the SAME comment → plan already complete: print `ARCHITECT_RESULT:` with `status: COMPLETE` and the existing comment's `comment_url`, EXIT.
 - If `<!-- FORGE:ARCHITECT -->` comment exists BUT `<!-- FORGE:ARCHITECT:COMPLETE -->` is ABSENT → plan was interrupted, delete the partial comment and restart:
   ```bash
   COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
@@ -435,6 +440,15 @@ Read the 3–5 most relevant files identified. Do NOT read more than 8 files tot
 
 ---
 
+## Phase A1.6: Route-Tree Classification for Shared Components *(conditional — skip if no files under `components/` are affected, except `components/ui/primitives/`)* <!-- Added: forge#381 -->
+
+When a change adds a new hook call or context dependency to a shared component, classify ALL call sites found in A1 by route context:
+1. **Authenticated routes**: Callers under `app/dashboard/`, `app/(authenticated)/`, or any layout that wraps children with an auth provider (e.g., `UserProvider`, `SessionProvider`).
+2. **Public routes**: Callers under `app/(public)/`, `app/playground/`, `app/(marketing)/`, or any layout without the relevant provider.
+3. **If both categories have callers AND the new hook throws when its provider is absent**: add an explicit implementation step to either (a) guard the hook call with a null-context check, (b) make the hook return a safe default when called outside its provider, or (c) remove the hook from the shared component and move it to the authenticated-route-only caller. Document the split in the FORGE:ARCHITECT affected paths table. Do NOT leave a shared component that crashes public routes to be discovered by the FE review agent.
+
+---
+
 ## Phase A2: Trace the Data Flow
 
 From each entry point identified in A1, trace what happens to the data being changed:
@@ -449,10 +463,40 @@ For each step in the flow, check:
 - Is there a validation or coercion that must be updated consistently?
 - Is there a test that covers this path?
 
+**For every field or key read by the changed code, enumerate ALL write paths first** — search across all services for assignments to that field. If multiple code paths write different types to the same field (e.g. dict in the standard path, string in the auth-gated path), the implementation must handle all variants. Do not assume the type you see on the primary code path is the only possible type.
+
 Produce a table of ALL files/functions that must change to maintain consistency.
 
 ---
 
+## Phase A2.1: Runtime UID × Volume Ownership Check *(conditional — skip if no Dockerfile or entrypoint is affected)* <!-- Added: forge#323 -->
+
+When the PR changes the container's runtime user (Dockerfile `USER` directive, `su-exec`, `gosu`, `setuid`), the architect MUST trace the full write-path chain before writing the implementation plan:
+1. **Enumerate volume mounts**: Read all `docker-compose*.yml` files for the affected service. List every named volume and its container mount point (e.g. `storage_shared:/app/storage`). Docker named volumes are created as root-owned by default — any UID change without a corresponding ownership fix will silently break writes.
+2. **Grep for filesystem writes**: Search the affected service's codebase for all filesystem write operations (`mkdir`, `Path.mkdir`, `write_bytes`, `open(`, `os.makedirs`, `shutil.copy`, `shutil.move`). For each write operation, identify the target path.
+3. **Cross-reference**: For each write path that falls under a named volume mount point, add an explicit implementation step to ensure ownership compatibility before the privilege drop — typically `chown -R <user>:<group> <mount_point>` in the entrypoint script before the `exec su-exec` / `exec gosu` call.
+4. **Add to FORGE:ARCHITECT deliverables table**: List the entrypoint or docker-compose change as an explicit deliverable. Do NOT leave volume ownership to be discovered by the builder or reviewer.
+
+---
+
+## Phase A2.2: Gate-Condition Caller Sweep *(conditional — when the fix changes a gate condition that guards a function call or restricts a field)* <!-- Added: forge#383 -->
+
+Before finalizing the affected-paths table, grep for all callers of the gated function across sibling files in the same service directory. For each caller, verify that the gate condition applied at the call site is semantically correct.
+
+```bash
+# Identify the gated function from the issue/contract
+GATED_FUNCTION="{function_being_called_inside_the_gate}"
+SERVICE_DIR=$(dirname {PRIMARY_AFFECTED_FILE})
+# Find all call sites
+grep -rn "$GATED_FUNCTION" "$SERVICE_DIR" --include="*.py" | grep -v "#"
+```
+
+For each call site found: read the surrounding gate condition (±10 lines). If the condition includes fields that do NOT require the gated resource (e.g., `extraction_schema` gated behind an LLM key check when `extraction_schema` is processed without an LLM), add that caller file to the FORGE:ARCHITECT affected-paths table with a note explaining the incorrect gate condition.
+
+**Do NOT** omit sibling callers from the affected-paths table simply because they were not listed in the issue spec. The architect's scope is determined by code correctness, not by the issue spec's file list. A gate-condition bug that exists identically in 3 router files must be fixed in all 3 — even if the issue only named 1.
+
+---
+
 ## Phase A2.5: Pipeline Phase-Dependency Check
 
 **Skip if**: None of the `{AFFECTED_FILES}` are Forge pipeline command files (i.e., no file matches `commands/**/*.md`). When skipped, proceed directly to A3.
@@ -471,7 +515,7 @@ For each affected `commands/*.md` file, identify what it produces that other pha
 
 1. **Comment markers** — HTML comment markers the phase writes to GitHub (e.g., `<!-- FORGE:ARCHITECT -->`, `<!-- FORGE:ARCHITECT:COMPLETE -->`). Search for `<!-- FORGE:` patterns in the affected file.
 2. **Structured output blocks** — named result blocks returned to the caller (e.g., `BUILD_RESULT:`, `VALIDATE_RESULT:`, `IMPLEMENT_RESULT:`). Search for lines ending in `:` that start a return block.
-3. **Skill() invocation signatures** — parameters the file passes when invoking subcommands (e.g., `Skill("work-on:build:architect", args="... --files ...")`). Search for `Skill(` calls.
+3. **Skill() invocation signatures** — parameters the file passes when invoking subcommands (e.g., `Skill("{FORGE_SKILL_PREFIX}work-on:build:architect", args="... --files ...")`). Search for `Skill(` calls.
 4. **Label state machine transitions** — `gh issue edit ... --add-label ... --remove-label ...` calls that define which label is set at the end of this phase.
 
 **P2: Find downstream phases that consume these artefacts**
@@ -668,12 +712,13 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 
 ## Skip Conditions
 
-Skip the planning work (Phases A0–A5) and return an empty plan to caller — **but always post the Skip Marker below first** — if:
+Skip the planning work (Phases A0–A5) and print `ARCHITECT_RESULT:` with `status: SKIPPED` — **but always post the Skip Marker below first** — if:
 - **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
 - Issue creates only **new files** with no callers to find (e.g. a new command file with no existing integration point yet)
 - Issue is a 1-file config or docs edit with no code logic
 - Issue title starts with "docs:" or "chore:"
 - `{AFFECTED_FILES}` is empty
+- **COMPLEXITY_BAND: INVESTIGATION** — investigation tasks produce issues, not code
 
 When skipped, the builder proceeds with investigation report + context briefing only (see Integration Point below — the builder falls back gracefully on an empty plan).
 
@@ -681,7 +726,7 @@ When skipped, the builder proceeds with investigation report + context briefing
 
 **Do not post nothing.** The headless engine gate (`bin/engine/phases.mjs` → `architect.detectOutcome`) treats a **missing** `FORGE:ARCHITECT:COMPLETE` sentinel as a phase **failure**, retries to `maxAttempts` (3), then strands the issue at `needs-human`. It reads GitHub comment markers only — it cannot see this subcommand's in-process "empty plan" return value. So a skip that posts no marker is indistinguishable from a crashed architect run and deterministically strands **every** `chore:`/`docs:`/trivial issue.
 
-On **every** skip branch above, post exactly this minimal comment (substitute the concrete `{SKIP_REASON}`, e.g. `chore:/docs: title`, `TRIVIAL complexity band`, `new files only — no callers`, or `AFFECTED_FILES empty`) **before** returning the empty plan:
+On **every** skip branch above, post exactly this minimal comment (substitute the concrete `{SKIP_REASON}`, e.g. `chore:/docs: title`, `TRIVIAL complexity band`, `new files only — no callers`, or `AFFECTED_FILES empty`) **before** printing `ARCHITECT_RESULT:`:
 
 ```bash
 # The skip marker is mandatory and un-gated by design — posting it IS the point
@@ -704,22 +749,39 @@ The empty-plan-with-marker changes no downstream behavior — the builder alread
 
 ---
 
-## Integration Point in work-on.md
+## Result Block (MANDATORY on every path)
+
+Your final reply MUST end with exactly one block, printed after the plan, partial, or skip-marker comment has been posted. `work-on:build` reads only this block.
+
+```
+ARCHITECT_RESULT:
+  status: COMPLETE | PARTIAL | SKIPPED | BLOCKED
+  comment_url: {URL of the FORGE:ARCHITECT comment, or empty}
+  blocker: {description if status=BLOCKED, else empty}
+```
+
+- `COMPLETE` — plan posted with `FORGE:ARCHITECT:COMPLETE` (also the result when the Resume Check finds a complete plan).
+- `PARTIAL` — budget exceeded; `FORGE:ARCHITECT:PARTIAL` posted.
+- `SKIPPED` — a skip condition applied and the Skip Marker was posted (give its URL).
+- `BLOCKED` — conflicting constraints that cannot be resolved, or a missing required arg. Post a comment describing the conflict and add `needs-human` (guard with `DRY_RUN`) before printing the block.
+
+---
+
+## Integration Point
 
-This module runs at **Step 3C.6** — after Context Gathering, before Implement:
+This module runs as build phase B4 — after Context Gathering, before Implement:
 
 ```
-3C    → Builder Contract posted
-3C.5  → Context Gathering (FORGE:CONTEXT comment)
-3C.6  → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
+B3    → Context Gathering (FORGE:CONTEXT comment)
+B4    → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
           Phase A0: Read Custom Instructions and Project Conventions (highest precedence)
-          Phase A1: Read Entry Points
-          Phase A2: Trace the Data Flow
+          Phase A1: Read Entry Points (A1.5 Prior Decision Injection, A1.6 Route-Tree Classification)
+          Phase A2: Trace the Data Flow (A2.1 Runtime UID x Volume Ownership, A2.2 Gate-Condition Caller Sweep)
           Phase A2.5: Pipeline Phase-Dependency Check
           Phase A3: Consistency Rules
           Phase A4: Sequence the Implementation
           Phase A5: Risk Assessment
-3F    → Implement (builder reads plan, implements ALL affected paths)
+B5    → Implement (builder reads plan, implements ALL affected paths)
 ```
 
 The builder agent reads the `<!-- FORGE:ARCHITECT -->` comment as its **primary input** before writing any code. The raw issue body is secondary context. If the architect step was skipped, the builder falls back to investigation report + contract.

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

@@ -1,15 +1,16 @@
 ---
 description: Pre-implementation context gathering — surfaces historical findings, bug patterns, and related code paths before the builder writes any code
-argument-hint: "[issue number] [affected_files...] [--functions function_names...]"
+argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE} --files \"<space-separated>\" [--functions \"<names>\"]"
+context: fork
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/context — Pre-Implementation Context Gathering
 
-**Invoked by**: `work-on.md` Step 3C.5, between Builder Contract and Implement.
+**Invoked by**: `work-on:build` (phase B3), between Builder Contract and Architect, via `Skill()`. Runs in its own forked context: you see only this spec and your args — re-read all other state from GitHub/git.
 **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.
+**Output**: Post `<!-- FORGE:CONTEXT -->` comment on the issue, then print exactly one `CONTEXT_RESULT:` block (see Result Block) as your final reply. Every exit path — success, partial, skip, failure — prints it.
 
 <!-- FORGE:SPEC_LOADED — work-on/build/context.md loaded and active. Agent is bound by this spec. -->
 
@@ -26,7 +27,7 @@ COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
 ```
 
-**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (C-1 through C4), post NO comment, return empty briefing to caller immediately. Do not query GitHub, do not read files. This is not an error — trivial single-file changes have no institutional memory to surface. <!-- Added: forge#679 -->
+**If COMPLEXITY_BAND: TRIVIAL or INVESTIGATION** → skip all phases (C-1 through C4), post NO comment, print `CONTEXT_RESULT:` with `status: SKIPPED` and `comment_url:` empty immediately. Do not query GitHub, do not read files. This is not an error — trivial single-file changes (and investigation tasks, which produce issues rather than code) have no institutional memory to surface. <!-- Added: forge#679 -->
 
 **If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase C-1 below.
 
@@ -47,8 +48,10 @@ Parse from `$ARGUMENTS`:
 - `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
 - `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--repo-path {REPO_PATH}` — local filesystem path to the worktree (e.g. `/path/to/.claude/worktrees/fix/issue-121`); used by Phase C3 grep commands
-- `{AFFECTED_FILES}` — space-separated file paths (positional, after `{NUMBER}`, before any `--functions` flag)
-- `--functions {FUNCTION_NAMES}` — space-separated function/class names extracted from the Builder Contract deliverables table (optional)
+- `--files "{AFFECTED_FILES}"` — space-separated file paths (quoted as one value; an empty value is allowed and triggers the empty-list skip)
+- `--functions "{FUNCTION_NAMES}"` — space-separated function/class names extracted from the Builder Contract deliverables table (optional)
+
+**Fail closed**: if `{NUMBER}`, `--repo`, `--gh-flag` or `--repo-path` is missing, print `CONTEXT_RESULT:` with `status: SKIPPED` and `comment_url:` empty plus a one-line `note: missing arg <name>` and stop (context is advisory — a missing arg must never block the build, but it must be visible).
 
 **Graceful skip for empty FUNCTION_NAMES**: If `--functions` is absent or `{FUNCTION_NAMES}` is empty, Phase C3 produces zero for-loop iterations and is effectively skipped — no error, no output for that phase. This is expected behavior when the contract does not name specific functions.
 
@@ -674,6 +677,12 @@ If `GIST_SUMMARIES` is non-empty, it will be included in the `### Prior Investig
 
 ---
 
+## Batch Execution of C1–C4 (MANDATORY) <!-- Added: forge#1826 -->
+
+C1, C2 (including the direct commit-body read and the pickaxe pass), C3, and C4 below are mutually independent — none consumes another's output. Issue ALL of their underlying `gh`/`git`/`grep` calls as a single batch of parallel tool calls in one message, not as four sequential steps. This is the same rule as the "independent tool calls → same message" convention used elsewhere in the pipeline; it turns a ~4x serial round-trip chain (each `gh api` call is 0.5-2s) into one wall-clock round-trip. The per-file loop inside C1 and the per-function loop inside C3 are themselves independent across iterations — include every iteration's call in the same batch rather than looping turn-by-turn. Total budget is still 20s per query / 2 min overall; batching only removes serialization, it does not change the timeout.
+
+---
+
 ## Phase C1: Past Review Findings on These Files
 
 **Primary path — Forge Ledger** (O(1) local index lookup, zero API calls): <!-- Added: forge#1732 -->
@@ -922,36 +931,70 @@ gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 - Each `gh issue list` call: timeout after 20s, skip if exceeded
 - Each `gh pr list` call: timeout after 20s, skip if exceeded
 - Each `grep -r` call: timeout after 10s, skip if exceeded
-- Total wall time budget: **2 minutes** (C-1 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
+- Total wall time budget: **2 minutes** (C-1 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`, and report `status: PARTIAL` in `CONTEXT_RESULT:`.
+- C1–C4 are issued as one parallel batch (see Batch Execution above) — the 2-minute budget is wall time for the batch, not per step.
 
 ---
 
 ## Skip Conditions
 
-Skip this entire step (post nothing, return empty briefing) if:
-- **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
+Skip the context gathering (print `CONTEXT_RESULT:` with `status: SKIPPED`) if:
+- **COMPLEXITY_BAND: TRIVIAL or INVESTIGATION** — checked via FORGE:FAST_PATH comment at entry (see guard above); post NO comment <!-- Primary skip path: forge#679 -->
 - Issue is a 1-file config or docs edit with no code logic
 - The affected files have zero git history (new files being created)
 - `{AFFECTED_FILES}` is empty (investigation produced no file list)
 
+**Minimal marker on every non-TRIVIAL skip (forge#3123)**: for STANDARD/COMPLEX the phase-trail gate (`scripts/verify-phase-trail.sh`) requires a `FORGE:CONTEXT` marker, so a skip must still post an empty marker comment (idempotent: skip if a `FORGE:CONTEXT` comment already exists), otherwise a re-run can never satisfy the gate:
+
+```bash
+EXISTING_CONTEXT=$(gh api "repos/{GH_REPO}/issues/{NUMBER}/comments" --paginate \
+  --jq '[.[] | select(.body | contains("<!-- FORGE:CONTEXT -->"))] | length' \
+  | awk '{s+=$1} END {print s+0}')
+if [ "${DRY_RUN:-false}" = "true" ]; then
+  echo "[DRY_RUN] would post minimal FORGE:CONTEXT marker on #{NUMBER}"
+elif [ "$EXISTING_CONTEXT" -eq 0 ]; then
+  gh issue comment "{NUMBER}" -R "{GH_REPO}" --body "<!-- FORGE:CONTEXT -->
+## Implementation Context for #{NUMBER}
+
+Context gathering skipped: {REASON — config/docs-only edit | new files, no git history | empty affected-file list}. No institutional memory to surface.
+
+<!-- FORGE:CONTEXT:COMPLETE -->"
+fi
+```
+
+---
+
+## Result Block (MANDATORY on every path)
+
+Your final reply MUST end with exactly one block, printed after any marker comment has been posted. `work-on:build` reads only this block.
+
+```
+CONTEXT_RESULT:
+  status: COMPLETE | PARTIAL | SKIPPED
+  comment_url: {URL of the FORGE:CONTEXT comment, or empty when no comment was posted}
+```
+
+- `COMPLETE` — full `FORGE:CONTEXT:COMPLETE` comment posted.
+- `PARTIAL` — budget exceeded or a source errored; `FORGE:CONTEXT:PARTIAL` posted.
+- `SKIPPED` — any skip condition (TRIVIAL/INVESTIGATION band: no comment; other skips: minimal marker comment, give its URL if you posted or found one).
+- An error, timeout or missing arg is never a reason to omit the block and never blocks the build.
+
 ---
 
-## Integration Point in work-on.md
+## Integration Point
 
-This module runs at **Step 3C.5** — after Builder Contract is posted, before Implement:
+This module runs as build phase B3 — after the Builder Contract is posted, before Architect:
 
 ```
-3C   → Builder Contract posted
-3C.5 → [THIS MODULE] Context gathering (max 2 min)
+B2   → Builder Contract posted
+B3   → [THIS MODULE] Context gathering (max 2 min)
          Phase C-1:  Authoritative Devdocs (project-resident knowledge — highest precedence)
          Phase C-0.5: Active Peer Claims Reader (conditional — orchestration only)
          Phase C0.5: Danger-Zone Rule Cards (fixed 400-token slot — forge#1744)
          Phase C0:  Prior Investigation Findings (from Gists)
-         Phase C1:  Past Review Findings on These Files
-         Phase C2:  Past Bugs in the Same Module
-         Phase C3:  Related Code Paths
-         Phase C4:  Successful Similar Implementations
-3F   → Implement (builder now has context briefing)
+         Phases C1–C4: batched in parallel (Past Review Findings, Past Bugs, Related Code Paths, Similar Implementations)
+B4   → Architect
+B5   → Implement (builder now has context briefing)
 ```
 
 The builder agent reads the `<!-- FORGE:CONTEXT -->` comment before writing any code. If the context step was skipped, the builder proceeds with investigation report + contract only.

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

@@ -1,16 +1,21 @@
 ---
 description: Implementation agent — writes code, makes commits, posts builder comment
-argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH]"
+argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --worktree {WORKTREE} --branch {BRANCH} --base {PR_BASE} [--fix-acceptance \"<failed checks>\"]"
+context: fork
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/implement — Implementation Subcommand
 
+> **Skill Name Resolution (forked phase)**: `{FORGE_SKILL_PREFIX}` is the namespace this skill itself was invoked under — invoked as `forgedock:work-on:…` → `forgedock:` (nesting `:`); as `work-on:…` → empty (`install.sh`); as `forge-work-on-…` → `forge-` (Codex, nesting `-`); OpenCode → empty with `-` nesting. Confirm the target name in the available-skills list before calling it. A forked phase receives no resolved value from its caller; never guess, and if the target skill is not listed return BLOCKED "skill not found: <name>".
+
 **Input**: $ARGUMENTS
 
-**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.
+**Invoked by**: `work-on:build`, after the worktree is created and context is gathered. This skill runs in an isolated forked context: it sees only this text and its args, so it re-reads all other state from GitHub/git.
+**Output**: Write code, stage changes, post `<!-- FORGE:BUILDER -->` comment, and end with exactly one `IMPLEMENT_RESULT:` block as the final reply.
+
+**Result-on-every-exit rule**: every exit path — success, `ALREADY_DONE`, `INVESTIGATION_COMPLETE`, every guard, every failure — MUST print the `IMPLEMENT_RESULT:` block (see Output) as the final reply. Never exit with a bare `exit 1` or free text. Failures use `status: BLOCKED` with a `blocker` line.
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "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).**
@@ -25,11 +30,18 @@ Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
 - `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
 - `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
-- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree (set by caller)
-- `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`)
+- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree (required)
+- `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`) (required)
+- `--base {PR_BASE}` — PR base branch name without the `origin/` prefix (required; computed by the router and passed down; used by the cross-lane import guard and migration collision check)
+
+**Fail closed**: if `{NUMBER}`, `--repo`, `--worktree`, `--branch`, or `--base` is missing or empty, or `{WORKTREE_PATH}` is not an existing directory, print `IMPLEMENT_RESULT:` with `status: BLOCKED` and `blocker: missing or invalid arg: <name>` and STOP. `{GH_FLAG}` defaults to `-R {GH_REPO}` when absent.
+
+**Derived values**: `{CHANGED_FILES}` (used below) is the space-separated list of files you changed in the worktree — derive it with `git -C {WORKTREE_PATH} diff --name-only HEAD` plus any untracked files from `git -C {WORKTREE_PATH} ls-files --others --exclude-standard`. `{GH_REPO}` and `{GH_FLAG}` as parsed above.
 
 ---
 
+- `--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.
+
 ## Phase I1: Load Context from GitHub
 
 Read the full context chain before writing a single line of code:
@@ -56,7 +68,7 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 ```
 
 **Resume check**:
-- If `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment → implementation is done — EXIT and return `IMPLEMENT_RESULT: status: ALREADY_DONE` to caller.
+- If `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment → implementation is done — EXIT and print `IMPLEMENT_RESULT: status: ALREADY_DONE` as the final reply.
 - If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → implementation was interrupted after the comment was posted but before the commit (validate.md V5). Delete the partial comment and restart from Phase I2:
   ```bash
   PARTIAL_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
@@ -102,7 +114,7 @@ Extract from contract:
 | Refactor / Maintenance | Implement directly following contract deliverables |
 | Investigation | Spawn research agents, create GitHub issues for findings, skip to I5 |
 
-**Investigation task special case**: Research deeply, create GitHub issues for each finding using the Pipeline Issue Template (see `commands/issue.md` § "Pipeline Issue Template"). Each issue MUST include `## Problem`, `## Affected Files`, and `## Acceptance Criteria`. Create each issue via the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") — `Skill(skill="issue", args="--title \"...\" --body-file <path> --label ...")` — instead of calling the raw issue-creation command directly; this gets dedup and body validation for free. Post a deliverables comment listing the created issues, close the original issue, return `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE`.
+**Investigation task special case**: Research deeply, create GitHub issues for each finding using the Pipeline Issue Template (see `commands/issue.md` § "Pipeline Issue Template"). Each issue MUST include `## Problem`, `## Affected Files`, and `## Acceptance Criteria`. Create each issue via the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") — `Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"...\" --body-file <path> --label ...")` — instead of calling the raw issue-creation command directly; this gets dedup and body validation for free. Post a deliverables comment listing the created issues, close the original issue, and print `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE` as the final reply (the build skill passes this up and the router skips review). <!-- Added: forge#2090 -->
 
 ---
 
@@ -118,8 +130,12 @@ Work in `{WORKTREE_PATH}`. Follow the contract deliverables table exactly — im
 - **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.
 - **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 | grep -oP '^\d+' | sort | uniq -d` prints duplicates) — a duplicate prefix hard-fails the deploy gate regardless of file content. <!-- Added: forge#373 -->
-- 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
+- **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 -->
+- **Cross-lane import guard**: Before adding any `import` or `from X import Y` statement for a service-internal module (`app.*`), verify the module exists on the PR's base branch (`{PR_BASE}`) — NOT just on your local disk or a milestone branch. Run `git show origin/{PR_BASE}:{module_path}.py` (replacing dots with slashes) to confirm. If the module only exists on a milestone branch, do NOT import it — find an alternative implementation or make the import conditional with a `try/except ImportError` fallback. A milestone-only import on a fast-lane PR will crash production on every request with `ModuleNotFoundError`. <!-- Added: forge#277 -->
+- **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.
+- **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
 
 **Worktree working directory**:
 ```bash
@@ -143,7 +159,7 @@ Scan changed files for newly introduced env var references:
 cd {WORKTREE_PATH}
 # Collect all env var names referenced in changed files
 NEW_ENV_VARS=$(grep -rnE "os\.getenv\(|process\.env\." {CHANGED_FILES} 2>/dev/null \
-  | grep -oP "(os\.getenv\(['\"]|process\.env\.)(\w+)" \
+  | grep -oE "(os\.getenv\(['\"]|process\.env\.)[A-Za-z0-9_]+" \
   | sed "s/os\.getenv\(['\"]//; s/process\.env\.//" \
   | sort -u)
 
@@ -203,6 +219,33 @@ grep -rnE "(api_key|secret|password|token|credential)\s*=\s*(f?['\"]|\`)[^{'\"\`
 
 **If HARDCODED IP or HARDCODED CREDENTIAL is printed**: replace the literal value with a config reference before proceeding to Phase I4. This is a hard blocker — do not stage hardcoded secrets or IPs.
 
+### Check 4 — SDK/API Literal sync advisory
+
+**Trigger**: the diff contains `Literal[` in a schema file.
+
+```bash
+# Detect Literal type changes in API schema files
+cd {WORKTREE_PATH}
+LITERAL_CHANGES=$(git diff HEAD -- | grep -E '^\+.*Literal\[' | grep -v '^\+\+\+')
+if [ -n "$LITERAL_CHANGES" ]; then
+    echo "SDK SYNC ADVISORY: Literal type changed in schema."
+    echo "Changed Literal lines:"
+    echo "$LITERAL_CHANGES"
+    echo ""
+    echo "ACTION REQUIRED — verify SDK method/type lists match new API schema:"
+    echo "  - sdk/python/*/client.py: check _valid_methods or equivalent list"
+    echo "  - sdk/node/src/index.ts: check JSDoc @param Literal type annotation"
+    echo "  - web/public/openapi*.json: check enum arrays for affected field"
+    echo "  - web/public/openapi-versions/*.json: check all versioned specs"
+    echo ""
+    echo "Inconsistency example: API schema narrows Literal['GET','POST','PUT','PATCH','DELETE']"
+    echo "to Literal['GET','POST'] but SDK JSDoc still lists all 5 methods — API returns 422"
+    echo "for callers following SDK docs. This produces silent user-facing failures."
+fi
+```
+
+This advisory is informational — it does NOT block the commit. But the implementer MUST check each listed file and add to the implementation scope if any SDK/spec file still documents the removed/changed Literal values. If SDK files need changes, add them to the current PR rather than leaving the inconsistency for review to catch.
+
 ---
 
 ## Phase I4: Stage Changes
@@ -214,7 +257,7 @@ Migration collision check (if applicable):
 git fetch origin
 git log --oneline origin/{PR_BASE}..HEAD -- {MIGRATION_PATHS}
 ```
-If a collision is detected, post a comment and add `needs-human` label before staging.
+If a collision is detected, post a comment, add `needs-human` label before staging, and EXIT with `IMPLEMENT_RESULT: status: BLOCKED` (`blocker: migration collision`).
 
 Stage the changed files:
 ```bash
@@ -272,7 +315,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 
 ## Output
 
-The subcommand writes its results to GitHub (FORGE:BUILDER comment). Return structured output to the caller:
+The subcommand writes its results to GitHub (FORGE:BUILDER comment). The final reply is exactly one `IMPLEMENT_RESULT:` block — on every exit path (use `status: BLOCKED` + `blocker` for failures; fields not applicable may be empty):
 
 ```
 IMPLEMENT_RESULT:
@@ -286,15 +329,16 @@ IMPLEMENT_RESULT:
 
 ---
 
-## Integration Point in work-on.md
+## Integration Point
 
-This module runs at **Step 3F** — after worktree creation and context gathering, before validate:
+This module is invoked by `work-on:build` after the worktree exists and context/architect are posted, and before validate:
 
 ```
-3E  → Worktree created (by router)
-3C.5 → Context gathered (by context.md)
-3F  → [THIS MODULE] Implement — code written, staged (not committed)
-3F.5 → Validate (by validate.md) — gate loop runs; V5 commit happens here after GATE_PASSED=true
+build (worktree + contract)
+  → context   (work-on:build:context)
+  → architect (work-on:build:architect)
+  → [THIS MODULE] implement — Phases I1–I6: code written, staged (not committed), FORGE:BUILDER posted
+  → validate  (work-on:build:validate) — gate loop; the single commit happens in validate Phase V5 after the gate passes
 ```
 
 The validate subcommand reads the staged diff produced by this module, runs the gate, and commits only after the gate passes.