forgedock 1.0.0

package/commands/work-on/review.md

@@ -0,0 +1,245 @@
+---
+description: Review subcommand — push branch, create PR, invoke /review-pr with --auto-merge
+argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]
+---
+
+# work-on/review — Review & PR Creation Subcommand
+
+**Input**: $ARGUMENTS
+
+**Invoked by**: `work-on.md` Phase 4–5, after `build/validate.md` returns `GATE_PASSED: true`.
+**Output**: Push branch, create PR, invoke /review-pr --auto-merge, 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. `RapierCraftStudios/forge`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree
+- `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`)
+- `--base {PR_BASE}` — PR target branch (e.g. `milestone/modular-pipeline-architecture` or `staging`)
+
+---
+
+## Phase R0: Load State from GitHub (MANDATORY)
+
+Re-read current state before doing anything:
+
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
+
+# Get builder comment (for branch + commit info)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body'
+
+# Check if PR already exists for this branch
+gh pr list {GH_FLAG} --head {BRANCH} --json number,state,url 2>/dev/null
+```
+
+**Resume check**:
+- If PR already exists AND is OPEN → skip to Phase R3 (invoke /review-pr)
+- If PR already exists AND is MERGED → return `REVIEW_RESULT: status: ALREADY_MERGED`
+- If no `<!-- FORGE:BUILDER -->` or `<!-- ALTERLAB:BUILDER -->` comment exists → EXIT with `REVIEW_RESULT: status: BLOCKED`, blocker: "FORGE:BUILDER comment not found — implement phase may not have completed"
+
+---
+
+## Phase R1: Pre-Push Ancestry Guard
+
+Before pushing, verify the branch contains no merge commits from branches outside the PR base ancestry. This is the final defense against milestone-code-onto-staging contamination.
+
+```bash
+cd {WORKTREE_PATH}
+# Skip if PR_BASE does not exist on origin yet (new branch — no contamination possible)
+if git ls-remote --exit-code origin {PR_BASE} >/dev/null 2>&1; then
+  MERGE_COMMITS=$(git log --merges {BRANCH} ^origin/{PR_BASE} 2>/dev/null)
+  if [ -n "$MERGE_COMMITS" ]; then
+    echo "PRE-PUSH ANCESTRY GUARD FAILED: merge commits from outside {PR_BASE} detected"
+    gh issue comment {NUMBER} {GH_FLAG} --body "## Pre-Push Ancestry Guard Failed
+
+Branch \`{BRANCH}\` contains merge commits from branches outside the PR base (\`{PR_BASE}\`). Pushing this branch risks contaminating \`{PR_BASE}\` with unapproved code (e.g. milestone code leaking onto staging).
+
+**Detected merge commits**:
+\`\`\`
+${MERGE_COMMITS}
+\`\`\`
+
+Do NOT push this branch. Human review required to identify the source of the merge commits and clean the branch history (e.g. via \`git rebase\` to replay only the intended commits onto \`origin/{PR_BASE}\`).
+
+<!-- FORGE:PUSH_BLOCKED -->"
+    gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+    # Return REVIEW_RESULT: status: BLOCKED — do not push
+    exit 1
+  fi
+fi
+```
+
+## Phase R1: Push Branch
+
+```bash
+cd {WORKTREE_PATH}
+git push origin {BRANCH}
+```
+
+If push fails, retry with `--force-with-lease`:
+```bash
+git push origin {BRANCH} --force-with-lease
+```
+
+If still fails:
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "## Push Failed
+
+Branch \`{BRANCH}\` could not be pushed to origin.
+
+**Error**: {ERROR_OUTPUT}
+
+This may indicate a merge conflict or remote rejection. Human review required.
+
+<!-- FORGE:PUSH_FAILED -->"
+
+gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+```
+Return `REVIEW_RESULT: status: BLOCKED`, blocker: "git push failed".
+
+---
+
+## Phase R2: Create PR
+
+### R2A: Determine PR title
+
+Derive from issue title:
+- `fix(...):`  → `Fix: {description}`
+- `feat(...):`  → `Feat: {description}`
+- `refactor(...):`  → `Refactor: {description}`
+- `docs(...):`  → `Docs: {description}`
+- fallback: use issue title as-is
+
+### R2B: Create PR
+
+```bash
+gh pr create {GH_FLAG} \
+  --base {PR_BASE} \
+  --head {BRANCH} \
+  --title "{PR_TITLE}" \
+  --body "## Summary
+
+{BRIEF_DESCRIPTION_FROM_ISSUE_BODY}
+
+## Changes
+
+{BULLETED_LIST_OF_KEY_CHANGES_FROM_BUILDER_COMMENT}
+
+## Testing
+
+{TESTING_CHECKLIST_FROM_BUILDER_COMMENT}
+
+---
+
+Closes #{NUMBER}
+
+**Implementation branch**: \`{BRANCH}\`
+**Base**: \`{PR_BASE}\`"
+```
+
+**Note**: `Closes #{NUMBER}` documents intent but does NOT auto-close for non-default-branch PRs. The close subcommand handles explicit closure after merge.
+
+If PR creation fails because a PR already exists for this branch:
+```bash
+gh pr list {GH_FLAG} --head {BRANCH} --json number,url --jq '.[0]'
+```
+Use the existing PR number and continue.
+
+### R2C: Update labels
+
+```bash
+gh issue edit {NUMBER} {GH_FLAG} \
+  --add-label "workflow:in-review" \
+  --remove-label "workflow:building"
+```
+
+---
+
+## Phase R3: Invoke /review-pr with --auto-merge
+
+Re-read the PR number (from creation or from resume check):
+
+```bash
+PR_NUMBER=$(gh pr list {GH_FLAG} --head {BRANCH} --json number --jq '.[0].number')
+```
+
+Post a progress comment before delegating:
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "## Submitting for Review
+
+PR #${PR_NUMBER} created targeting \`{PR_BASE}\`. Invoking /review-pr with --auto-merge.
+
+Review will: analyze changes → spawn domain agents → post findings → merge → close issue → clean up worktree.
+
+<!-- FORGE:REVIEW_STARTED -->"
+```
+
+Invoke the review command:
+
+```
+Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
+```
+
+/review-pr handles: full domain-agent review → post findings as separate issues (non-blocking) → merge the PR → close the issue → clean up worktree.
+
+---
+
+## Phase R4: Verify Review Outcome
+
+After /review-pr returns, verify the outcome:
+
+```bash
+# Check PR state
+gh pr view {PR_NUMBER} {GH_FLAG} --json state,mergedAt --jq '{state: .state, mergedAt: .mergedAt}'
+
+# Check issue state
+gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
+```
+
+**Cases**:
+- PR MERGED (issue OPEN or CLOSED) → `REVIEW_RESULT: status: COMPLETE` — do NOT close the issue or add labels here; the router will route to `work-on:close` which handles issue closure, label updates, project board, trajectory log, and worktree cleanup.
+- PR NOT MERGED → attempt manual merge:
+  ```bash
+  gh pr merge {PR_NUMBER} {GH_FLAG} --merge --auto
+  ```
+  If merge fails: post comment, add `needs-human`, return `REVIEW_RESULT: status: BLOCKED`
+
+---
+
+## Output
+
+Output this structured block — the routing loop in `work-on.md` will read this result, re-evaluate state, and continue to the next phase. This subcommand is complete; control returns to the router's loop iteration.
+
+```
+REVIEW_RESULT:
+  status: COMPLETE | ALREADY_MERGED | BLOCKED
+  pr_number: {PR_NUMBER}
+  pr_url: {PR_URL}
+  merged_to: {PR_BASE}
+  blocker: {description if status=BLOCKED}
+```
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Phases 4–5** — after validate returns `GATE_PASSED: true`, before close:
+
+```
+3F.5 → Validate (by build/validate.md) — gate passed
+4    → [THIS MODULE] Push + PR creation + /review-pr invocation + merge verification
+5    → Close (by close.md) — trajectory, parent tracker, summary
+```
+
+/review-pr is invoked within this module (not by the router). The router waits for REVIEW_RESULT before invoking close.md.

package/commands/work-on-monolithic.md

@@ -0,0 +1,298 @@
+---
+description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
+argument-hint: [issue number]
+---
+
+# /work-on-monolithic — Full Issue Pipeline (Single Prompt)
+
+**Input**: $ARGUMENTS
+
+Orchestrator for the full issue lifecycle: investigate → build → review → merge → close. GitHub issues are the persistent context layer — read existing comments before starting, write structured reports back, use `workflow:*` labels to track state.
+
+**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**NEVER use plan mode (EnterPlanMode).**
+
+### Compaction Resilience
+
+1. Write state to GitHub after EVERY significant step
+2. Re-read GitHub state at the START of each phase (don't rely on in-memory context)
+3. After compaction: re-read issue (body + comments + labels) to reconstruct state
+4. Key principle: A NEW session running this command should pick up where the last left off by reading GitHub state alone
+
+---
+
+## Pipeline Rules
+
+- **NEVER merge to main.** PRs target `staging` (fast lane) or `milestone/{slug}` (feature lane).
+- **`Closes #N` does not auto-close for non-default-branch PRs.** You MUST explicitly `gh issue close`.
+- **Review findings are NOT merge blockers.** They become separate issues.
+
+---
+
+## Multi-Repo Support
+
+| Input | Resolves To |
+|-------|-------------|
+| `123` / `#123` | AlterLab (default): `RapierCraftStudios/AlterLab` |
+| `mcp:5` | MCP Server: `RapierCraftStudios/alterlab-mcp-server` |
+| `n8n:12` | n8n Node: `RapierCraftStudios/n8n-nodes-alterlab` |
+
+**Context Variables** (set after resolving project):
+
+| Variable | AlterLab | MCP | n8n |
+|----------|----------|-----|-----|
+| `GH_REPO` | `RapierCraftStudios/AlterLab` | `RapierCraftStudios/alterlab-mcp-server` | `RapierCraftStudios/n8n-nodes-alterlab` |
+| `REPO_PATH` | `/home/mrdubey/projects/ScraperAPI/alterlab` | `/home/mrdubey/projects/ScraperAPI/alterlab-mcp-server` | `/home/mrdubey/projects/ScraperAPI/n8n-nodes-alterlab` |
+| `STAGING_BRANCH` | `staging` | `main` | `main` |
+| `GH_FLAG` | _(empty)_ | `-R RapierCraftStudios/alterlab-mcp-server` | `-R RapierCraftStudios/n8n-nodes-alterlab` |
+
+Satellite repos (MCP, n8n) have no staging — fast-lane PRs go to `main`.
+
+---
+
+## Phase 0: Resolve Issue & Load Context
+
+### 0A: Parse input
+Extract project prefix and issue number.
+
+### 0B: Load issue + existing context
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments,milestone
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, author: .user.login, body: .body}'
+```
+
+**Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`), parent tracker status.
+
+**Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder + no PR → Phase 4. Builder + PR open → Phase 5. PR merged + issue open → close issue.
+
+**Classify lane**: Milestone → feature lane (`milestone/{slug}`). No milestone → fast lane (`staging`).
+
+**Source branch for review-findings**: Parse `**Code branch**: \`{branch}\`` from body. Branch from there, not main.
+
+### 0C: Sync to Project board
+Add issue to project, set Status=In Progress, Lane, Component, Priority, Workflow=Investigating.
+
+---
+
+## Phase 1: Investigation
+
+**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->`.
+
+### 1A: Set label
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:investigating"
+gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review" 2>/dev/null || true
+```
+
+### 1B: Investigate the issue
+
+Mission: Validate whether the issue is real. Assume description is wrong until proven otherwise.
+
+**Domain file hints** (start search here):
+
+| Domain | Key files |
+|--------|-----------|
+| BILLING | `routers/billing.py`, `core/pricing.py`, `services/credit_service.py` |
+| SCRAPING | `unified_consumer.py`, `queues.py`, `domain_playbooks.json` |
+| AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
+| DATABASE | `infra/migrations/`, `models/`, `db/` |
+| FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
+| CORTEX | `cortex_client.py`, `routers/cortex.py` |
+| INFRA | `.github/workflows/`, `docker-compose.yml`, `infra/traefik/` |
+
+**Steps**: Check right branch → read domain files → verify claims → git blame → determine root cause → identify affected files → validate proposed fixes against full system stack.
+
+**Fix-Approach Validation**: If issue proposes a fix, don't adopt it as spec. Trace through target system's middleware, auth, routing.
+
+**Domain Context Discovery** (narrow scope, max 5 files):
+```bash
+git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u
+```
+
+**Output format**: Verdict (CONFIRMED/PARTIAL/INVALID), Confidence, Severity, Task Type, What Was Claimed, What We Found, Root Cause, Affected Files, Evidence, Recommendation.
+
+### 1C: Post investigation comment
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
+<!-- INVESTIGATION:COMPLETE -->
+## Investigation Report
+{report}"
+```
+
+### 1D: Update labels
+CONFIRMED/PARTIAL → add `workflow:ready-to-build`, continue to Phase 3.
+INVALID → close issue, add `workflow:invalid`, STOP.
+
+---
+
+## Phase 3: Build
+
+**Skip if**: `<!-- FORGE:BUILDER -->` exists.
+
+### 3A: Re-read state from GitHub (MANDATORY)
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json body,labels
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
+```
+
+### 3B: Classify task type
+
+| Signal | Type | Approach |
+|--------|------|----------|
+| UI/UX, feature + web/ files | UI/UX | `frontend-design` skill |
+| Feature + services/ | Backend Feature | Implement directly |
+| Feature + both | Full-Stack | Backend first, then frontend-design |
+| Bug + web/ | Frontend Fix | Direct |
+| Bug + services/ | Backend Fix | Direct |
+| Refactor/docs | Maintenance | Direct |
+
+### 3C: Builder Contract (MANDATORY)
+Post `<!-- FORGE:CONTRACT -->` comment with: task type, proposed approach, deliverables table (file/change/why), acceptance criteria, quality considerations.
+
+### 3C.5: Context Gathering (max 2 minutes)
+
+Surface institutional memory before writing code. For each affected file:
+```bash
+# Recent agent work on these files
+git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u | head -5
+# Check for review findings on same files
+for ISSUE_NUM in {related_issue_numbers}; do
+  gh api repos/{GH_REPO}/issues/${ISSUE_NUM}/comments --jq '.[] | select(.body | contains("FORGE:")) | .body' 2>/dev/null | head -20
+done
+```
+
+Post `<!-- FORGE:CONTEXT -->` comment with findings (or skip if no relevant history).
+
+### 3C.6: Architecture Plan
+
+For multi-file changes, trace ALL affected code paths before writing code:
+- Map the call chain: entry point → middleware → handler → service → model → response
+- Identify every file that needs to change
+- Order implementation steps to avoid broken intermediate states
+
+Post `<!-- FORGE:ARCHITECT -->` comment with the implementation plan.
+
+For single-file or trivial changes, skip this step.
+
+### 3D: Set building label
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:building" --remove-label "workflow:ready-to-build,workflow:investigating"
+```
+
+### 3E: Create worktree
+Branch slug from title (lowercase, hyphenated, max 40 chars). Prefix: `fix/` (bugs) or `feat/` (features).
+- Review-finding → branch from `origin/{SOURCE_BRANCH}`
+- Fast lane → branch from `origin/{STAGING_BRANCH}`
+- Feature lane → branch from `origin/milestone/{slug}`
+
+```bash
+cd {REPO_PATH}
+git fetch origin
+BRANCH="fix/{slug}-{NUMBER}"
+git worktree add /home/mrdubey/projects/ScraperAPI/{WT_PREFIX}-worktrees/{BRANCH} -b {BRANCH} origin/{PR_BASE}
+```
+
+### 3F: Implement
+Route by task type. Read the investigation report and contract. Implement the fix/feature.
+
+### 3F.5: Quality Gate
+Invoke quality-gate on changed files:
+```
+Skill(skill="quality-gate", args="{changed_files} --worktree {WORKTREE_PATH}")
+```
+Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
+
+### 3G: Format and verify
+- Python: `black` + `isort` + `py_compile`
+- TypeScript (AlterLab): `prettier --write` + `tsc --noEmit` (BLOCKING if fails)
+- TypeScript (satellite): `npm run build` + `prettier --write`
+
+### 3H: Frontend proxy wiring check (MANDATORY)
+All client-side fetch/useSWR/apiFetch must use `/api/...` proxy routes, NEVER `/api/v1/...` directly.
+
+### 3I: Deployment completeness check (MANDATORY)
+New env vars must be in: `.env.example` + SOPS `prod.enc.yaml` + `decrypt-secrets.sh` ENV_MAPPING + `env_validation.py` (if API).
+
+### 3J: Commit
+Conventional prefix (fix/feat/refactor/docs). Reference #{NUMBER} in the commit message.
+
+### 3K: Post implementation comment
+Post `<!-- FORGE:BUILDER -->` with: branch, commit, files changed, approach, changes list, testing checklist.
+
+---
+
+## Phase 4: PR Creation
+
+### 4A: Push branch
+```bash
+cd {WORKTREE_PATH} && git push -u origin {BRANCH}
+```
+If fails: try `--force-with-lease`. If still fails: post comment, add `needs-human`, STOP.
+
+### 4B: Determine PR target
+No milestone → `staging`. Has milestone → `milestone/{slug}`. NEVER `main`.
+
+### 4C: Create PR
+```bash
+gh pr create {GH_FLAG} --base {PR_BASE} --title "{Fix|Feat}: {description} (#{NUMBER})" --body "..."
+```
+Include `Closes #{NUMBER}`.
+
+### 4D: Update labels
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:in-review" --remove-label "workflow:building"
+```
+
+---
+
+## Phase 5: Auto-Review
+
+### 5A: Re-read state from GitHub (MANDATORY)
+### 5B: Invoke /review-pr with --auto-merge
+```
+Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
+```
+
+### 5C: Verify merge and close (recovery)
+- PR MERGED + issue CLOSED → proceed to Phase 6/7
+- PR MERGED + issue OPEN → close issue manually
+- PR NOT MERGED → `gh pr merge --merge {GH_FLAG}`, close issue. If merge fails → post comment, add `needs-human`, STOP.
+
+### 5D: Project board update (Workflow=Merged, Status=Done)
+
+### 5E: Final issue body update
+Check off remaining items.
+
+---
+
+## Phase 6: Parent Tracker Update (Sub-Issues Only)
+
+**Skip if**: Not a sub-issue.
+
+Check off this sub-issue in parent body. If ALL sub-issues closed → close parent with `workflow:merged`.
+
+---
+
+## Phase 7: Summary & Trajectory
+
+### 7A: Report
+```
+## Done: #{NUMBER} — {TITLE}
+- Investigation: {verdict} ({confidence})
+- Lane: {FAST/FEATURE}
+- Fix: {branch} → PR #{PR_NUMBER} → merged to `{PR_BASE}`
+- Files changed: {count}
+```
+
+### 7B: Trajectory Log (MANDATORY)
+Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table, decisions, anomalies.
+
+---
+
+## Error Handling
+
+- Worktree exists: reuse or clean up
+- PR creation fails: check if branch pushed, if PR already exists
+- Merge conflicts: report to user, do NOT auto-resolve
+- gh CLI fails: check `gh auth status`
+- Label missing: create it