forgedock 1.0.0

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

@@ -0,0 +1,280 @@
+---
+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]
+---
+
+# work-on/build/implement — Implementation Subcommand
+
+**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.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{NUMBER}` — issue number (required)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree (set by caller)
+- `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`)
+
+---
+
+## Phase I1: Load Context from GitHub
+
+Read the full context chain before writing a single line of code:
+
+```bash
+# Issue body and labels
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels
+
+# Architect plan (primary implementation guide — read BEFORE writing any code)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:ARCHITECT")) | .body'
+
+# Investigation report
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
+
+# Builder contract
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTRACT")) | .body'
+
+# Context briefing (if present)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTEXT")) | .body'
+```
+
+**Resume check**: If `<!-- FORGE:BUILDER -->` comment already exists, the implementation is done — EXIT and return `IMPLEMENT_RESULT: status: ALREADY_DONE` to caller.
+
+**Primary guide**: If `<!-- FORGE:ARCHITECT -->` is present, it is the **primary implementation input**. Follow its ordered implementation list exactly — it defines which files change, in what order, and what consistency checks must pass. The investigation report and contract are secondary context.
+
+**Fallback**: If `<!-- FORGE:ARCHITECT -->` is absent (architect step was skipped), proceed with investigation report + contract as the sole implementation guide.
+
+Extract from architect plan (when present):
+- Ordered implementation list (sequence of file changes to make)
+- All affected paths (every file that must change for consistency)
+- Consistency checks (invariants the builder must verify before committing)
+- Risk assessment (HIGH/MEDIUM/LOW risks to watch for)
+
+Extract from investigation report:
+- Affected files list
+- Root cause
+- Recommendation
+
+Extract from contract:
+- Task type (Bug Fix / Feature / Refactor / Maintenance / UI/UX / Full-Stack)
+- Deliverables table (file, change, why)
+- Acceptance criteria
+
+---
+
+## Phase I2: Route by Task Type
+
+| Task Type | Approach |
+|-----------|----------|
+| Bug Fix | Implement fix directly in worktree |
+| Feature (backend only) | Implement directly |
+| Feature (UI/UX) | Invoke `frontend-design` skill + visual verification |
+| Full-Stack | Backend first, then invoke `frontend-design` skill for UI |
+| 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`. Use `gh issue create {GH_FLAG}` with a fully-structured body. Post a deliverables comment listing the created issues, close the original issue, return `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE`.
+
+---
+
+## Phase I3: Implement
+
+Work in `{WORKTREE_PATH}`. Follow the contract deliverables table exactly — implement each file change listed, in the order that resolves dependencies first.
+
+**Implementation rules**:
+- Read the current file before modifying it — never assume its state
+- Read related files identified in the context briefing before touching the changed code
+- 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.
+- **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
+
+**Worktree working directory**:
+```bash
+cd {WORKTREE_PATH}
+# all file reads, writes, and git operations happen here
+```
+
+---
+
+## Phase I3.5: Env/Config Completeness Check
+
+**Run this BEFORE Phase I4.** This phase is read-only — it scans the working changes for INFRA-class gaps that would otherwise surface as review findings. Do NOT run `git add` or `git commit` here.
+
+**Trigger**: Run this phase whenever the diff introduces env vars, touches infra/deploy configs, or adds literal IP addresses.
+
+### Check 1 — New env var documentation sync
+
+Scan changed files for newly introduced env var references:
+
+```bash
+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+)" \
+  | sed "s/os\.getenv\(['\"]//; s/process\.env\.//" \
+  | sort -u)
+
+if [ -n "$NEW_ENV_VARS" ]; then
+    for var in $NEW_ENV_VARS; do
+        grep -q "$var" .env.example 2>/dev/null \
+            || echo "MISSING: $var not in .env.example — add it before staging"
+        [ -f ENV_VARS.md ] \
+            && { grep -q "$var" ENV_VARS.md \
+                || echo "MISSING: $var not in ENV_VARS.md — add it before staging"; }
+        [ -f env_validation.py ] \
+            && { grep -q "$var" env_validation.py \
+                || echo "MISSING: $var not in env_validation.py — add it before staging"; }
+    done
+fi
+```
+
+**If any MISSING line is printed**: add the var to the missing location before proceeding to Phase I4. If the file doesn't exist in this repo (e.g. `ENV_VARS.md` is an AlterLab file, not a Forge file), skip that check silently.
+
+### Check 2 — Deploy/infra restart risk
+
+```bash
+cd {WORKTREE_PATH}
+INFRA_FILES=$(echo "{CHANGED_FILES}" | tr ' ' '\n' \
+  | grep -E "docker-compose.*\.yml|deploy/|infra/")
+
+if [ -n "$INFRA_FILES" ]; then
+    echo "INFRA CHANGE DETECTED in: $INFRA_FILES"
+    # Check for restart-inducing changes
+    RESTART_LINES=$(while IFS= read -r f; do grep -n "" "$f"; done <<< "$INFRA_FILES" \
+      | grep -E "^\+.*(image:|resources:|mem_limit|cpus:|restart:|depends_on:)" \
+      | grep -v "^---" || true)
+    if [ -n "$RESTART_LINES" ]; then
+        echo "RESTART RISK: the following lines may force container restarts on next deploy:"
+        echo "$RESTART_LINES"
+        echo "ACTION: annotate your commit message with [restart: <service_name>]"
+    fi
+fi
+```
+
+**If RESTART RISK is printed**: annotate the commit message (in Phase V5) with `[restart: <service>]` so operators know to plan downtime.
+
+### Check 3 — Hardcoded IPs and credentials
+
+```bash
+cd {WORKTREE_PATH}
+# Scan for bare IPv4 literals not inside env var lookups
+grep -rnE "\b([0-9]{1,3}\.){3}[0-9]{1,3}\b" {CHANGED_FILES} 2>/dev/null \
+  | grep -vE "os\.getenv|process\.env|\.env\.example|example|placeholder|test|mock|localhost|127\.0\.0\.1|0\.0\.0\.0" \
+  && echo "HARDCODED IP: replace with a config reference (env var or config file) before staging"
+
+# Scan for credential-like assignments with literal values
+grep -rnE "(api_key|secret|password|token|credential)\s*=\s*(f?['\"]|\`)[^{'\"\`]" {CHANGED_FILES} 2>/dev/null \
+  | grep -vE "os\.getenv|process\.env|example|placeholder|test|mock" \
+  && echo "HARDCODED CREDENTIAL: replace with env var before staging"
+```
+
+**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.
+
+---
+
+## Phase I4: Stage Changes
+
+**Precondition**: Do NOT commit yet — the validate subcommand (validate.md) runs AFTER implement and will make the commit in Phase V5 after the gate passes. Commit will happen in validate.md Phase V5 after the gate passes.
+
+Migration collision check (if applicable):
+```bash
+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.
+
+Stage the changed files:
+```bash
+cd {WORKTREE_PATH}
+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`.
+
+---
+
+## Phase I5: Update Issue Body
+
+Check off each acceptance criterion that has been implemented:
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body'
+# Edit the body: check off completed items, add PR reference if known
+gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
+```
+
+---
+
+## Phase I6: Post FORGE:BUILDER Comment
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
+## Implementation Complete
+
+**Branch**: \`{BRANCH}\`
+**Commits**: {COMMIT_SHA(S)}
+**Files changed**: {COUNT}
+
+### Approach
+{One paragraph: what was built, key decisions, why this approach over alternatives}
+
+### Changes
+{Bulleted list of each file changed and what was done}
+
+### Acceptance Criteria Status
+{Checklist of each criterion from the contract, marked ✅ or ❌}
+
+### Testing Checklist
+- [ ] {Test scenario 1}
+- [ ] {Test scenario 2}
+- [ ] {Test scenario 3}
+
+<!-- FORGE:BUILDER:COMPLETE -->"
+```
+
+---
+
+## Output
+
+The subcommand writes its results to GitHub (FORGE:BUILDER comment). Return structured output to the caller:
+
+```
+IMPLEMENT_RESULT:
+  status: COMPLETE | ALREADY_DONE | INVESTIGATION_COMPLETE | BLOCKED
+  branch: {BRANCH}
+  commits: [{SHA}, ...]
+  files_changed: [{file}, ...]
+  comment_url: {url of FORGE:BUILDER comment}
+  blocker: {description if status=BLOCKED}
+```
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Step 3F** — after worktree creation and context gathering, 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
+```
+
+The validate subcommand reads the staged diff produced by this module, runs the gate, and commits only after the gate passes.

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

@@ -0,0 +1,292 @@
+---
+description: Validation agent — quality gate loop, format/verify, proxy check, deploy check
+argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]
+---
+
+# work-on/build/validate — Validation Subcommand
+
+**Input**: $ARGUMENTS
+
+**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"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{NUMBER}` — issue number (required)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree
+- `--files {CHANGED_FILES}` — space-separated list of changed files (from implement result)
+
+---
+
+## Skip Conditions
+
+Skip all phases (return `GATE_PASSED: true` immediately) if:
+- Only 1 file was changed AND it is a config or docs file with no code logic (e.g. `.md`, `.yml` with no scripts, `.env.example`)
+
+In all other cases, the gate MUST run.
+
+---
+
+## Phase V1: Quality Gate Loop
+
+**Loop protocol** — the gate MUST pass or exhaust iterations before returning:
+
+```
+iteration = 0
+max_iterations = 3
+
+while iteration < max_iterations:
+    iteration += 1
+    Run quality-gate agent on CHANGED_FILES
+    if result == "QUALITY GATE: PASS":
+        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:
+    GATE_PASSED = false
+    → post comment (see V1-FAIL below)
+    → add label needs-human
+    → return GATE_PASSED: false to caller, STOP
+```
+
+**Quality gate invocation**:
+```
+Skill("quality-gate", args="{CHANGED_FILES} --worktree {WORKTREE_PATH}")
+```
+
+**Rules**:
+- 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
+
+**V1-FAIL comment** (post when gate never passes):
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "## Quality Gate Failed After 3 Iterations
+
+Quality gate findings persist after 3 fix passes. Flagging for human review.
+
+**Files**: {CHANGED_FILES}
+**Final findings**: {SUMMARY_OF_REMAINING_FINDINGS}
+
+Needs human review before proceeding to commit.
+
+<!-- FORGE:GATE_FAILED -->"
+```
+
+---
+
+## Phase V2: Format and Verify
+
+Run after quality gate passes. Format checks are per-language:
+
+**Python**:
+```bash
+cd {WORKTREE_PATH}
+black {PYTHON_FILES}
+isort {PYTHON_FILES}
+python -m py_compile {PYTHON_FILES}
+```
+Failures in `py_compile` are BLOCKING — fix before continuing.
+
+**TypeScript (AlterLab)**:
+```bash
+cd {WORKTREE_PATH}
+prettier --write {TS_FILES}
+tsc --noEmit
+```
+`tsc --noEmit` failures are BLOCKING — fix type errors before continuing.
+
+**TypeScript (satellite repos — MCP, n8n)**:
+```bash
+cd {WORKTREE_PATH}
+npm run build
+prettier --write {TS_FILES}
+```
+
+**Shell scripts**: Verify service interactions — read target middleware files, document what was verified in V4 summary.
+
+**Markdown / config files**: No format step required.
+
+If no files match a language category, skip that language's step.
+
+---
+
+## Phase V3: Frontend Proxy Wiring Check
+
+**Skip if**: No TypeScript/TSX files were changed.
+
+Scan all changed client-side files for direct backend calls that bypass the Next.js proxy:
+
+```bash
+grep -n "api/v1" {CHANGED_TS_FILES}
+grep -n "localhost:" {CHANGED_TS_FILES}
+grep -n "127.0.0.1" {CHANGED_TS_FILES}
+```
+
+**Rule**: All client-side `fetch`, `useSWR`, `apiFetch`, and `axios` calls MUST use `/api/...` proxy routes. Direct calls to `/api/v1/...` or hardcoded host:port are BLOCKING.
+
+If violations found:
+1. Fix them in `{WORKTREE_PATH}`
+2. Document fixes in V4 summary
+
+---
+
+## Phase V3.5: Database Configuration Change Advisory
+
+**Skip if**: No changed Python files contain database engine/session/pool configuration patterns.
+
+When changed files touch database engine configuration, flag for manual connectivity verification. Configuration bugs in `create_async_engine`, `connect_args`, or session factories are invisible to static analysis but cause immediate runtime failures.
+
+```bash
+cd {WORKTREE_PATH}
+DB_CONFIG_FILES=""
+for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+    grep -qE "create_async_engine|AsyncSession|connect_args|pool_size|prepared_statement|engine_from_config|sessionmaker" "$f" 2>/dev/null && \
+        DB_CONFIG_FILES="$DB_CONFIG_FILES $f"
+done
+
+if [ -n "$DB_CONFIG_FILES" ]; then
+    echo "DB CONFIG CHANGE DETECTED in:$DB_CONFIG_FILES"
+    echo "ACTION: Verify database connectivity after deploy — changes to engine config, connect_args, or session factories can cause silent runtime failures."
+    echo "RECOMMENDED: Run a minimal connectivity test (e.g., SELECT 1) through the modified session/engine path."
+
+    # Check for lambda/callable in connect_args — the exact bug class from PR #14391
+    for f in $DB_CONFIG_FILES; do
+        grep -nE "lambda.*:.*['\"]|=lambda" "$f" 2>/dev/null | grep -iE "connect_args|prepared_statement|pool|engine" && \
+            echo "WARNING: Lambda/callable in database configuration in $f — verify callback signature matches library's expected calling convention"
+    done
+fi
+```
+
+**This is advisory only** — it does not block the build. The output is included in the V5 summary to alert reviewers and deployers. This check exists because PR #14391 passed `lambda _: ""` to `prepared_statement_name_func` (which expects 0 args), breaking all worker billing. Static analysis cannot catch arity mismatches in library callbacks — the flag ensures a human verifies connectivity.
+
+---
+
+## Phase V4: Deployment Completeness Check
+
+**Skip if**: No new environment variables were introduced in the changed files.
+
+Detect new env vars:
+```bash
+cd {WORKTREE_PATH}
+git diff HEAD~1 -- {CHANGED_FILES} | grep -oP '(?<=os\.environ\[")[^"]+|(?<=os\.getenv\()["\']?[A-Z_]+' | sort -u
+# Also check TypeScript:
+git diff HEAD~1 -- {CHANGED_FILES} | grep -oP 'process\.env\.\K[A-Z_]+' | sort -u
+```
+
+For each new env var found, verify it is present in ALL required locations:
+
+| Location | Required for |
+|----------|-------------|
+| `.env.example` | All new vars |
+| `infra/secrets/prod.enc.yaml` (SOPS) | Production secrets |
+| `infra/decrypt-secrets.sh` ENV_MAPPING | All vars in deploy chain |
+| `app/env_validation.py` | API service vars |
+| `docker-compose.prod.yml` | Vars needing explicit injection |
+
+**Deploy chain**: SOPS → `decrypt-secrets.sh` (ENV_MAPPING) → `.env.secrets` → `merge-env-secrets.sh` → `.env.production` → docker-compose `env_file`.
+
+If any required location is missing the var:
+1. Add it to the missing location in `{WORKTREE_PATH}`
+2. Document the addition in V4 summary
+3. These additions are NOT new commits — they should be staged and committed together with any other pending fixes, or as a separate commit if clean
+
+---
+
+## Phase V5: Commit (always — after GATE_PASSED=true)
+
+After the gate passes, commit all staged changes in a single commit. This includes:
+- The implementation changes staged by `implement.md` Phase I4
+- Any format, proxy, or deploy fixes applied by phases V2–V4
+
+```bash
+cd {WORKTREE_PATH}
+git add -u
+git commit -m "fix({SCOPE}): {description} (#NUMBER)"
+```
+
+Where `{SCOPE}` is the command or module scope from the contract (e.g. `work-on`, `quality-gate`), and `{description}` summarises the implementation. Use the commit convention from the contract:
+- Bug Fix → `fix(`
+- Feature → `feat(`
+- Refactor → `refactor(`
+
+This is the **only** commit for this build cycle. It replaces the old `git commit` that was previously in `implement.md` Phase I4. Do NOT create a separate commit for validation fixes — they are absorbed into this single commit.
+
+### V5 Post-Commit Ancestry Audit (MANDATORY)
+
+After committing, run the ancestry audit to detect merge commits from unrelated branches before the branch is pushed:
+
+```bash
+cd {WORKTREE_PATH}
+MERGE_COMMITS=$(git log --merges HEAD ^origin/{PR_BASE} 2>/dev/null)
+if [ -n "$MERGE_COMMITS" ]; then
+  echo "ANCESTRY AUDIT FAILED: merge commits from unrelated branches detected on this branch:"
+  echo "$MERGE_COMMITS"
+  # Block push — do NOT proceed to review.md R1
+  gh issue comment {NUMBER} {GH_FLAG} --body "## Ancestry Audit Failed
+
+Branch \`{BRANCH}\` contains merge commits from branches outside the PR base (\`{PR_BASE}\`). This is a staging contamination risk — these commits may carry code from milestone branches that has not been approved for \`{PR_BASE}\`.
+
+**Detected merge commits**:
+\`\`\`
+${MERGE_COMMITS}
+\`\`\`
+
+Human review required before this branch can be pushed.
+
+<!-- FORGE:ANCESTRY_FAILED -->"
+  gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+  # Return GATE_PASSED: false — do not push
+  exit 1
+fi
+```
+
+If `origin/{PR_BASE}` does not exist yet (new branch), skip this check — no contamination is possible from a non-existent base. Detect with:
+```bash
+git ls-remote --exit-code origin {PR_BASE} >/dev/null 2>&1 || echo "PR_BASE not on origin — skipping ancestry audit"
+```
+
+---
+
+## Output
+
+Return structured output to the caller:
+
+```
+VALIDATE_RESULT:
+  gate_passed: true | false
+  quality_gate_iterations: {COUNT}
+  format_issues_fixed: {COUNT}
+  proxy_violations_fixed: {COUNT}
+  deploy_completeness_fixes: [{VAR_NAME: location_added}, ...]
+  commits_added: [{SHA}, ...]  # from V5 if any
+  blocker: {description if gate_passed=false}
+```
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Step 3F.5** — after implement, before commit (3J) and PR creation (Phase 4):
+
+```
+3F  → Implement (by implement.md) — code written, staged (not committed)
+3F.5 → [THIS MODULE] Validate — gate loop, format, proxy, deploy checks
+3G  → (covered by Phase V2 above)
+3H  → (covered by Phase V3 above)
+3I  → (covered by Phase V4 above)
+3J  → V5 commit happens here after GATE_PASSED=true (single commit for implementation + any fixes)
+```
+
+If `VALIDATE_RESULT: gate_passed: false`, the router adds `needs-human` label and stops — no PR is created.