forgedock 1.0.0 → 1.0.2

package/commands/review-pr.md

@@ -4,7 +4,7 @@ argument-hint: [PR number, URL, "open", or "staging" for feature→main review]
 allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
 ---
 
-# AlterLab PR Review — Orchestrator
+# PR Review — Orchestrator
 
 **Input**: $ARGUMENTS
 
@@ -20,8 +20,10 @@ This is the **orchestrator**. It routes to the right review mode, runs automated
 
 | File | What | How to invoke |
 |------|------|---------------|
-| `/home/mrdubey/.claude/commands/review-pr-agents.md` | Agent prompt templates (9 agents + protocols) | `Read` tool during Phase 3C |
-| `/home/mrdubey/.claude/commands/review-pr-staging.md` | Full staging→main review pipeline | `Skill("review-pr-staging", ...)` during Phase 0 |
+| `$FORGE_HOME/commands/review-pr-agents.md` | Agent prompt templates (9 agents + protocols) | `Read` tool during Phase 3C |
+| `$FORGE_HOME/commands/review-pr-staging.md` | Full staging→main review pipeline | `Skill("review-pr-staging", ...)` during Phase 0 |
+
+`$FORGE_HOME` defaults to `~/.claude` (the directory where `npx forgedock` symlinks commands). Override by setting `FORGE_HOME` in your environment.
 
 **Invocation flow:**
 ```
@@ -38,7 +40,7 @@ This is the **orchestrator**. It routes to the right review mode, runs automated
 If `$ARGUMENTS` contains `--auto-merge`, this review was invoked from `/work-on` and must merge the PR after approval. Parse:
 
 ```
-Example: "3126 --auto-merge --issue 3124 --base staging --gh-flag -R RapierCraft/AlterLab --worktree /path/to/worktree"
+Example: "3126 --auto-merge --issue 3124 --base staging --gh-flag -R $GH_REPO --worktree /path/to/worktree"
 ```
 
 Extract: `PR_NUMBER`, `AUTO_MERGE=true`, `MERGE_ISSUE`, `MERGE_BASE`, `MERGE_GH_FLAG`, `MERGE_WORKTREE` (optional — the absolute path to the git worktree to clean up after merge)
@@ -292,12 +294,12 @@ Map each changed file to its activation requirements:
 | `web/src/app/**/*-client.tsx`, `web/src/components/**/*.tsx`, `web/src/lib/*.ts` (Client-side code with `fetch()`/`useSWR()`) | Client requests go through Next.js proxy (`/api/...`), never directly to FastAPI (`/api/v1/...`) | Grep changed `.tsx`/`.ts` files (excluding `route.ts` proxy handlers) for `fetch("/api/v1/` or `` `/api/v1/ `` in template literals or `useSWR.*"/api/v1/`. Any match is a **CONFIRMED BLOCKING** integration bug — direct calls bypass session auth (admin proxy JWT, session-to-bearer conversion) and fail locally (no nginx). |
 | `.github/workflows/*.yml` (Workflow with test/build jobs) | Sibling workflows with same-named jobs stay in sync | For each job name in the changed workflow, check if the same job name exists in sibling workflows (`ci.yml` ↔ `deploy-production.yml` ↔ `hotfix-deploy.yml`). Compare env vars, PYTHONPATH, working-directory, and run commands for meaningful drift. |
 | `docker-compose*.yml` changes to `postgres` or `redis` service (`command:`, `image:`, `volumes:`, `environment:`) | Stateful container will NOT be recreated during deploy, OR restart is safe | **Auto-escalate to HIGH risk.** Changing `command:` args, `image:` tag, or `volumes:` forces container recreation on `docker-compose up`. For stateful services (postgres, redis), verify: (1) `stop_grace_period` is set and sufficient (≥30s for PG); (2) `full_page_writes = on` in PG config (protects against partial page writes on crash); (3) `fsync = on` (ensures write durability); (4) No long-running transactions will be interrupted. If container recreation is unavoidable, recommend scheduling during a maintenance window — NOT as a side effect of a routine deploy. **This check prevents the class of incident documented in issue #146**: a PG `command:` arg change triggered container restart under active load, corrupting btree indexes. |
-| `docker-compose*.yml` changes `entrypoint:` or `command:` to reference a script (`.sh` file) | Env vars used inside the entrypoint script are available inside the container at runtime | **Run `verify-env-vars.sh`** which detects shell `${VAR}` references in entrypoint scripts and cross-checks against the service's `environment:` section. Docker Compose `${VAR}` in YAML `command:` is parsed at Compose load time (host-side) — the var doesn't need to be in the container. But `${VAR}` inside an entrypoint `.sh` script runs at container runtime — it MUST be injected via `environment:` or `env_file:`. **This check prevents the class of incident documented in RapierCraftStudios/forge#185**: Redis migrated from `command: --requirepass ${REDIS_PASSWORD}` (Compose interpolation) to `entrypoint.sh` (container runtime) without adding `environment: REDIS_PASSWORD`, causing a restart loop on deploy. |
+| `docker-compose*.yml` changes `entrypoint:` or `command:` to reference a script (`.sh` file) | Env vars used inside the entrypoint script are available inside the container at runtime | **Run `verify-env-vars.sh`** which detects shell `${VAR}` references in entrypoint scripts and cross-checks against the service's `environment:` section. Docker Compose `${VAR}` in YAML `command:` is parsed at Compose load time (host-side) — the var doesn't need to be in the container. But `${VAR}` inside an entrypoint `.sh` script runs at container runtime — it MUST be injected via `environment:` or `env_file:`. **This check prevents the class of incident where a service migrates from `command:` args (Compose interpolation) to an entrypoint script (container runtime) without adding the env var to `environment:`, causing a restart loop on deploy.** <!-- Added: forge#185 --> |
 | **ANY staging→main PR** (regardless of files changed) | `ci.yml` and `deploy-production.yml` test jobs are in sync | **ALWAYS runs for staging→main PRs.** Pre-existing drift is invisible until deploy. Deep-diff shared jobs (test-api, test-web): compare PYTHONPATH values, dependency install steps, and step names. A missing PYTHONPATH or install step in deploy is CONFIRMED BLOCKING — CI passes but deploy fails (PR #11356 incident). |
 
 ### Step 2.5B: Run Verification
 
-For each changed file, execute the relevant checks using the standalone verification scripts in `~/projects/forge/scripts/`. These scripts can also be run independently outside the review context (e.g., from `/quality-gate` or `/work-on` builder steps).
+For each changed file, execute the relevant checks using the standalone verification scripts in `$FORGE_HOME/scripts/`. These scripts can also be run independently outside the review context (e.g., from `/quality-gate` or `/work-on` builder steps).
 
 ```bash
 CHANGED_FILES=$(gh pr diff $ARGUMENTS --name-only)
@@ -315,19 +317,29 @@ gh pr diff $ARGUMENTS > "$DIFF_TMP"
 
 # 1. Route/router/middleware/shared-module/component registration
 echo "=== Running: verify-route-registration.sh ==="
-~/projects/forge/scripts/verify-route-registration.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+$FORGE_HOME/scripts/verify-route-registration.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
 # 2. Environment variable wiring (checks .env.example, docker-compose, env_validation, SOPS mapping)
 echo "=== Running: verify-env-vars.sh ==="
-~/projects/forge/scripts/verify-env-vars.sh "$DIFF_TMP" "$REPO_ROOT" || true
+$FORGE_HOME/scripts/verify-env-vars.sh "$DIFF_TMP" "$REPO_ROOT" || true
 
 # 3. Host headers in shell scripts + client-side proxy bypass check
+# Read project-specific internal service patterns from forge.yaml (if present)
+FORGE_INTERNAL_PATTERNS=""
+if [ -f "$REPO_ROOT/forge.yaml" ]; then
+    FORGE_INTERNAL_PATTERNS=$(grep -A 999 'internal_service_patterns:' "$REPO_ROOT/forge.yaml" \
+        | grep -E '^\s*-\s+' \
+        | sed 's/^\s*-\s*//' \
+        | tr -d '"'"'" \
+        | paste -sd '|' -)
+fi
+export FORGE_INTERNAL_PATTERNS
 echo "=== Running: verify-host-headers.sh ==="
-~/projects/forge/scripts/verify-host-headers.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+$FORGE_HOME/scripts/verify-host-headers.sh "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
 # 4. SOPS deploy chain (ENV_MAPPING consistency, deploy path drift, hotfix sync)
 echo "=== Running: verify-sops-chain.sh ==="
-~/projects/forge/scripts/verify-sops-chain.sh "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+$FORGE_HOME/scripts/verify-sops-chain.sh "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
 # Cleanup temp files
 rm -f "$CHANGED_FILES_TMP" "$DIFF_TMP"
@@ -488,14 +500,37 @@ echo "$FILES" | grep -cE "^sdk/|openapi.*\.json$|openapi-versions/" && echo "  S
 
 **>>> INVOCATION: Read the agent catalog file:**
 ```
-Read the file: /home/mrdubey/.claude/commands/review-pr-agents.md
+Read the file: $FORGE_HOME/commands/review-pr-agents.md
 ```
 
+(`$FORGE_HOME` defaults to `~/.claude`)
+
+**>>> LOAD CONFIG: Read forge.yaml for project context:**
+```bash
+# Read review config from forge.yaml (if present in project root)
+FORGE_YAML="${REPO_ROOT}/forge.yaml"
+PROJECT_NAME=$(yq '.project.name' "$FORGE_YAML" 2>/dev/null || echo "this project")
+PROJECT_CONTEXT=$(yq '.review.context' "$FORGE_YAML" 2>/dev/null || echo "")
+TECH_STACK=$(yq '.review.tech_stack' "$FORGE_YAML" 2>/dev/null || echo "")
+# Domain-specific context (keyed by agent name)
+DOMAIN_CONTEXT_AUTH=$(yq '.review.domains.auth' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_BILLING=$(yq '.review.domains.billing' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_INFRA=$(yq '.review.domains.infra' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_DATABASE=$(yq '.review.domains.database' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_FRONTEND=$(yq '.review.domains.frontend' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_SECURITY=$(yq '.review.domains.security' "$FORGE_YAML" 2>/dev/null || echo "")
+DOMAIN_CONTEXT_API=$(yq '.review.domains.api' "$FORGE_YAML" 2>/dev/null || echo "")
+```
+
+If `forge.yaml` is absent or a field is empty/null, agents fall back to generic checks (no project-specific context injected — agents still function correctly, just without project conventions).
+
 This file contains the Evidence-Based Review Protocol, Structured Findings Protocol, and all 9 agent prompt templates. For each selected agent:
 1. Extract its template from the catalog
 2. Substitute: `[PR_NUMBER]`, `[REVIEW_SHA]`, `[REVIEW_SHA_SHORT]`, `[TITLE]`, relevant files list
-3. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
-4. Launch via `Task` tool with the resolved model (default `"sonnet"`, fallback `"opus"` if rate-limited)
+3. Substitute: `[PROJECT_NAME]` → `$PROJECT_NAME`, `[PROJECT_CONTEXT]` → `$PROJECT_CONTEXT`, `[TECH_STACK]` → `$TECH_STACK`
+4. Substitute per-agent domain context: `[DOMAIN_CONTEXT]` → the agent's matching key from `forge.yaml → review.domains` (e.g., `$DOMAIN_CONTEXT_AUTH` for the auth agent, `$DOMAIN_CONTEXT_BILLING` for the billing agent)
+5. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
+6. Launch via `Task` tool with the resolved model (default `"sonnet"`, fallback `"opus"` if rate-limited)
 
 **CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple Task tool calls. Each agent posts findings directly to the PR via `gh pr comment`.
 
@@ -711,10 +746,17 @@ Labels: `review-finding` + `needs-validation` + priority (`P1` CONFIRMED, `P2` L
 **Add to project board:**
 ```bash
 for FINDING_NUM in {numbers}; do
-  ITEM_ID=$(gh project item-add 1 --owner RapierCraft --url "https://github.com/RapierCraft/AlterLab/issues/${FINDING_NUM}" --format json --jq '.id' 2>/dev/null)
+  # GH_REPO and board IDs are read from forge.yaml → project_board section
+  # OWNER = forge.yaml → project_board.owner (or project.owner)
+  # PROJECT_NUMBER = forge.yaml → project_board.project_number
+  # PROJECT_ID = forge.yaml → project_board.project_id
+  # STATUS_FIELD_ID = forge.yaml → project_board.field_ids.status
+  # LANE_FIELD_ID = forge.yaml → project_board.field_ids.lane
+  # REVIEW_FINDING_OPTION_ID = forge.yaml → project_board.option_ids.status.in_review
+  ITEM_ID=$(gh project item-add ${PROJECT_NUMBER} --owner ${OWNER} --url "https://github.com/${GH_REPO}/issues/${FINDING_NUM}" --format json --jq '.id' 2>/dev/null)
   [ -n "$ITEM_ID" ] && {
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id f75ad846 2>/dev/null || true
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF98 --single-select-option-id 62864af4 2>/dev/null || true
+    [ -n "$STATUS_FIELD_ID" ] && gh project item-edit --project-id ${PROJECT_ID} --id "$ITEM_ID" --field-id ${STATUS_FIELD_ID} --single-select-option-id ${REVIEW_FINDING_OPTION_ID} 2>/dev/null || true
+    [ -n "$LANE_FIELD_ID" ] && gh project item-edit --project-id ${PROJECT_ID} --id "$ITEM_ID" --field-id ${LANE_FIELD_ID} --single-select-option-id ${LANE_OPTION_ID} 2>/dev/null || true
   }
 done
 ```

package/commands/rollback.md

@@ -7,6 +7,9 @@ argument-hint: [PR number to revert, or "last" for most recent deploy]
 
 **Input**: $ARGUMENTS
 
+**Config variables used by this command** (set in `forge.yaml`):
+- `{REPO_PATH}` ← `paths.root` — project repository root
+
 You are the pipeline's emergency rollback system. When a shipped feature or fix causes production issues, this command creates a revert PR and fast-tracks it through the pipeline.
 
 **Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`.
@@ -75,11 +78,11 @@ Which approach? (Reply or press enter for option 1)
 ### Step 2A: Create a revert branch
 
 ```bash
-cd /home/mrdubey/projects/ScraperAPI/alterlab
+cd {REPO_PATH}
 git fetch origin main
-git worktree add ../alterlab-revert-pr-{PR_NUMBER} -b revert/pr-{PR_NUMBER} origin/main
+git worktree add ../revert-pr-{PR_NUMBER} -b revert/pr-{PR_NUMBER} origin/main
 
-cd ../alterlab-revert-pr-{PR_NUMBER}
+cd ../revert-pr-{PR_NUMBER}
 ```
 
 ### Step 2B: Execute the revert
@@ -230,8 +233,8 @@ BODY_EOF
 ### Step 4C: Clean up worktree
 
 ```bash
-cd /home/mrdubey/projects/ScraperAPI/alterlab
-git worktree remove ../alterlab-revert-pr-{PR_NUMBER}
+cd {REPO_PATH}
+git worktree remove ../revert-pr-{PR_NUMBER}
 git branch -D revert/pr-{PR_NUMBER} 2>/dev/null || true
 ```
 

package/commands/security-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Periodic security posture audit — runs a scripted 4-phase checklist against repo files (not diffs), creates GitHub issues for confirmed findings
-argument-hint: [--repo alterlab|mcp|n8n] [--phase 1|2|3|4|all] [--dry-run]
+argument-hint: [--repo <prefix>] [--phase 1|2|3|4|all] [--dry-run]
 ---
 
 # /security-audit — Periodic Security Posture Audit
@@ -21,22 +21,70 @@ This is NOT a PR review — it does not approve or block. It creates issues for
 
 ---
 
+## Config Preamble
+
+Before executing any phase, read `forge.yaml` to resolve project references:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+if [ -f "$CONFIG_FILE" ]; then
+  GH_OWNER=$(yq '.project.owner' "$CONFIG_FILE")
+  GH_REPO_NAME=$(yq '.project.repo' "$CONFIG_FILE")
+  GH_REPO="${GH_OWNER}/${GH_REPO_NAME}"
+  GH_FLAG="-R $GH_REPO"
+  REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+  # FORGE_REPO: the self-pipeline repo where security audit summary comments are posted.
+  # Set project.forge_repo in forge.yaml if your pipeline repo differs from GH_REPO.
+  FORGE_REPO=$(yq '.project.forge_repo // ""' "$CONFIG_FILE")
+  [ -z "$FORGE_REPO" ] && FORGE_REPO="$GH_REPO"
+  # BILLING_ENABLED: controls whether Phase 4 (Financial Integrity) runs.
+  # Set billing.enabled: true in forge.yaml if your project uses Stripe billing.
+  BILLING_ENABLED=$(yq '.billing.enabled // "false"' "$CONFIG_FILE")
+else
+  echo "WARNING: forge.yaml not found — commands will use placeholder values"
+  echo "Run: cp forge.yaml.example forge.yaml  and fill in your project details"
+  GH_REPO="your-org/your-repo"
+  GH_FLAG="-R $GH_REPO"
+  REPO_PATH="./"
+  FORGE_REPO="$GH_REPO"
+  BILLING_ENABLED="false"
+fi
+```
+
+---
+
 ## Multi-Repo Support
 
-| Input Pattern | Target Repo | GH_REPO | REPO_PATH |
-|---------------|-------------|---------|-----------|
-| `--repo alterlab` or default | AlterLab | `RapierCraft/AlterLab` | `/home/user/projects/alterlab` |
-| `--repo mcp` | MCP Server | `RapierCraft/alterlab-mcp-server` | `/home/user/projects/alterlab-mcp-server` |
-| `--repo n8n` | n8n Node | `RapierCraft/n8n-nodes-alterlab` | `/home/user/projects/n8n-nodes-alterlab` |
+If your project spans multiple repositories, define them in the `repos.satellites` section of `forge.yaml`. The `--repo <prefix>` argument selects a satellite by its `prefix` field.
 
 Parse `$ARGUMENTS` for:
-- **`--repo <name>`**: target repo (default: `alterlab`)
+- **`--repo <prefix>`**: target repo prefix (default: primary repo from `project.owner/project.repo`)
 - **`--phase <N|all>`**: run only a specific phase, or all (default: `all`)
 - **`--dry-run`**: print findings but do NOT create GitHub issues
 
-Set context variables from the table above. If `REPO_PATH` is not found locally, clone from GitHub:
+Set context variables from config:
+
 ```bash
-gh repo clone {GH_REPO} {REPO_PATH} -- --depth=1 2>/dev/null || true
+REPO_PREFIX=$(echo "$ARGUMENTS" | grep -oP '(?<=--repo )\S+' || true)
+
+if [ -n "$REPO_PREFIX" ]; then
+  # Look up satellite repo by prefix in forge.yaml
+  SATELLITE_REPO=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .repo" "$CONFIG_FILE" 2>/dev/null)
+  if [ -n "$SATELLITE_REPO" ] && [ "$SATELLITE_REPO" != "null" ]; then
+    GH_REPO="$SATELLITE_REPO"
+    GH_FLAG="-R $GH_REPO"
+    REPO_PATH=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .local_path" "$CONFIG_FILE" 2>/dev/null || echo "$REPO_PATH")
+    # Also read billing flag for satellite if set
+    BILLING_ENABLED=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .billing_enabled // \"false\"" "$CONFIG_FILE" 2>/dev/null || echo "false")
+  else
+    echo "WARNING: --repo prefix '$REPO_PREFIX' not found in forge.yaml repos.satellites — using default repo"
+  fi
+fi
+
+# If REPO_PATH is not found locally, clone from GitHub
+if [ ! -d "$REPO_PATH" ]; then
+  gh repo clone {GH_REPO} {REPO_PATH} -- --depth=1 2>/dev/null || true
+fi
 ```
 
 ---
@@ -353,9 +401,17 @@ grep -rn '||\s*["'"'"'][a-zA-Z0-9]\{4,\}["'"'"']\|default.*password\|default.*se
 
 ---
 
-## Phase 4: Financial Integrity (AlterLab-specific)
+## Phase 4: Financial Integrity
 
-*Skip this phase for non-AlterLab repos (MCP, n8n). These checks are specific to AlterLab's billing architecture.*
+*Skip this phase if `billing.enabled` is not set to `true` in `forge.yaml`. These checks require Stripe webhook integration and a billing architecture in your project.*
+
+```bash
+if [ "$BILLING_ENABLED" != "true" ]; then
+  echo "Phase 4 skipped — billing.enabled is not true in forge.yaml"
+  echo "To enable: add 'billing:\n  enabled: true' to forge.yaml"
+  # Skip to Phase 5
+fi
+```
 
 ### 4A: Stripe Webhook Handler Coverage
 
@@ -491,7 +547,7 @@ ISSUE_EOF
 If this command was invoked from within a `/work-on` context or with an issue reference:
 
 ```bash
-gh issue comment "{CALLER_ISSUE}" -R RapierCraftStudios/forge --body "$(cat <<'COMMENT_EOF'
+gh issue comment "{CALLER_ISSUE}" -R {FORGE_REPO} --body "$(cat <<'COMMENT_EOF'
 <!-- FORGE:SECURITY_AUDIT -->
 ## Security Audit Complete