forgedock 1.0.1 → 1.0.2

package/commands/orchestrate.md

@@ -25,17 +25,35 @@ You are the top-level orchestrator. Your job is to take a batch of issues, plan
 
 ---
 
+## Config Resolution
+
+Read `forge.yaml` at the project root to resolve all project-specific variables before running any commands:
+
+```bash
+# Parse forge.yaml for project context
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+GH_FLAG="-R $GH_REPO"
+REPO_PATH=$(yq '.paths.root' forge.yaml)
+PROJECT_NAME=$(yq '.project.name' forge.yaml)
+STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
+# Build satellite repo map from repos.satellites list
+# Each satellite: { prefix, repo, staging_branch }
+```
+
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, and `{STAGING_BRANCH}` references below are populated from `forge.yaml`.
+
+---
+
 ## Multi-Repo Support
 
-This orchestrator supports issues across the AlterLab ecosystem. See `/work-on` → "Multi-Repo Support" for the full project registry and context variables.
+This orchestrator supports issues across multiple repositories. See `/work-on` → "Multi-Repo Support" and `forge.yaml → repos` for the full project registry and context variables.
 
 ### Cross-Repo Issue References
 
-Issues can be prefixed with a project shorthand:
-- `#123` or `123` → AlterLab (default: `RapierCraft/AlterLab`)
-- `mcp:5` → MCP Server (`RapierCraft/alterlab-mcp-server`)
-- `n8n:12` → n8n Node (`RapierCraft/n8n-nodes-alterlab`)
-- `all-repos` → Scan all ecosystem repos for open issues (combine and prioritize)
+Issues can be prefixed with a project shorthand derived from `forge.yaml → repos.satellites`:
+- `#123` or `123` → default repo (`{GH_REPO}`)
+- `{satellite_prefix}:5` → satellite repo (e.g., `mcp:5`, `n8n:12`) — prefixes and repos come from `forge.yaml → repos.satellites`
+- `all-repos` → Scan all configured repos for open issues (combine and prioritize)
 
 When spawning sub-agents, pass the project prefix so `/work-on` resolves to the correct repo.
 
@@ -63,20 +81,20 @@ Parse `$ARGUMENTS` to determine which issues to work on:
 For each resolved repo, use the appropriate `-R` flag:
 
 ```bash
-# AlterLab (default — no flag needed):
-gh issue list --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone --jq '.[] | {number, title, labels: [.labels[].name], milestone: .milestone.title}'
+# Default repo (no flag needed if using GH_FLAG="" for the default):
+gh issue list {GH_FLAG} --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone --jq '.[] | {number, title, labels: [.labels[].name], milestone: .milestone.title}'
 
-# Satellite repos — always include -R flag:
-gh issue list -R RapierCraft/alterlab-mcp-server --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone
-gh issue list -R RapierCraft/n8n-nodes-alterlab --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone
+# Satellite repos — always include -R flag with the satellite repo from forge.yaml:
+# For each satellite in forge.yaml → repos.satellites:
+gh issue list -R {SATELLITE_REPO} --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone
 
 # For specific numbers with repo prefix:
-gh issue view 5 -R RapierCraft/alterlab-mcp-server --json number,title,labels,state,milestone,body
+gh issue view {NUMBER} -R {SATELLITE_REPO} --json number,title,labels,state,milestone,body
 
-# For "all-repos" — fetch from all and combine:
-gh issue list --state open --limit {N} --json number,title,labels,milestone
-gh issue list -R RapierCraft/alterlab-mcp-server --state open --limit 500 --json number,title,labels,milestone
-gh issue list -R RapierCraft/n8n-nodes-alterlab --state open --limit 500 --json number,title,labels,milestone
+# For "all-repos" — fetch from all configured repos and combine:
+gh issue list {GH_FLAG} --state open --limit {N} --json number,title,labels,milestone
+# For each satellite in forge.yaml → repos.satellites:
+gh issue list -R {SATELLITE_REPO} --state open --limit 500 --json number,title,labels,milestone
 # Combine, sort by priority, take top N
 ```
 
@@ -526,7 +544,7 @@ Agent(
   model="sonnet",
   description="Work on {PROJECT_PREFIX}#{NUMBER}",
   run_in_background=true,
-  prompt="You are working on GitHub issue #{NUMBER} for the AlterLab ecosystem.
+  prompt="You are working on GitHub issue #{NUMBER} for the {PROJECT_NAME} project.
 
 **Project**: {PROJECT_NAME}
 **Repository**: {GH_REPO}
@@ -540,11 +558,10 @@ Agent(
 
 **IMPORTANT RULES**:
 - **MANDATORY**: You MUST use the Skill tool to invoke 'work-on' with args '{PROJECT_PREFIX}{NUMBER}'. Do NOT implement manually — /work-on handles the full pipeline including label state machine (workflow:investigating → workflow:building → workflow:in-review → workflow:merged), investigation reports, PR creation, and cleanup.
-  - For AlterLab issues: `Skill(skill='work-on', args='{NUMBER}')`
-  - For MCP issues: `Skill(skill='work-on', args='mcp:{NUMBER}')`
-  - For n8n issues: `Skill(skill='work-on', args='n8n:{NUMBER}')`
+  - For default repo issues: `Skill(skill='work-on', args='{NUMBER}')`
+  - For satellite repo issues: `Skill(skill='work-on', args='{SATELLITE_PREFIX}:{NUMBER}')` (prefix from forge.yaml → repos.satellites)
 - NEVER bypass /work-on with manual git/gh commands — the label updates and structured comments are critical for tracking
-- NEVER target `main` for AlterLab PRs. Use `staging` for fast-lane issues, or `milestone/{slug}` for milestone issues.
+- NEVER target `main` for PRs targeting the default repo. Use `{STAGING_BRANCH}` for fast-lane issues, or `milestone/{slug}` for milestone issues.
 - Satellite repos (MCP, n8n) have no staging branch — fast-lane PRs go to `main` for those.
 - If the issue is INVALID after investigation, close it with a comment explaining why
 - If you hit merge conflicts or blockers, post a comment on the issue and STOP — do not force anything

package/commands/pipeline-health.md

@@ -9,7 +9,18 @@ argument-hint: [project repo slug or "all"]
 
 You are the Forge pipeline's self-awareness layer. Your job is to measure how well the pipeline is performing, correlate performance with recent prompt changes, identify weak spots, and propose concrete improvements.
 
-**FORGE_HOME**: `~/projects/forge`
+## Config
+
+Read project identity from `forge.yaml` before running any phase:
+
+```bash
+FORGE_REPO=$(yq e '.project.owner + "/" + .project.repo' forge.yaml)
+FORGE_HOME=$(yq e '.paths.root' forge.yaml)
+echo "Forge repo: $FORGE_REPO"
+echo "Forge home: $FORGE_HOME"
+```
+
+**FORGE_HOME**: `$FORGE_HOME` (set from `forge.yaml` → `paths.root`)
 **This command is READ-ONLY on the target project.** It creates issues in the Forge repo only.
 
 ---
@@ -32,7 +43,7 @@ echo "Target project: $REPO"
 
 ```bash
 # Last pipeline-health run (if any) — from Forge git log
-LAST_RUN=$(cd ~/projects/forge && git log --all --oneline --grep="pipeline-health: $REPO" --format="%aI" -1 2>/dev/null || echo "")
+LAST_RUN=$(cd "$FORGE_HOME" && git log --all --oneline --grep="pipeline-health: $REPO" --format="%aI" -1 2>/dev/null || echo "")
 if [ -z "$LAST_RUN" ]; then
     # First run — analyze last 30 days
     SINCE=$(date -d "30 days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -v-30d +%Y-%m-%dT%H:%M:%SZ)
@@ -49,7 +60,7 @@ Fetch the most recent `health-report` issue for the same repo and parse its metr
 
 ```bash
 # Find the most recent health-report issue for this repo
-PRIOR_REPORT=$(gh issue list -R RapierCraftStudios/forge \
+PRIOR_REPORT=$(gh issue list -R $FORGE_REPO \
   --state all --label "health-report" --limit 10 \
   --json number,title,body \
   --jq "[.[] | select(.title | contains(\"$REPO\"))] | sort_by(.number) | last")
@@ -154,7 +165,7 @@ Run ALL of these in parallel (note: Phase 2I fetches trajectory comments per iss
 ### 2A: Forge changelog (what changed in the pipeline itself)
 
 ```bash
-cd ~/projects/forge
+cd "$FORGE_HOME"
 git log --oneline --since="$SINCE" -- commands/ docs/
 ```
 
@@ -366,7 +377,7 @@ echo "Investigation invalidation rate: $INVALID_ISSUES / $TOTAL_INVESTIGATED"
 
 # 2. ISSUE_SPEC audit findings
 # Count of /audit findings classified as ISSUE_SPEC in the window
-ISSUE_SPEC_COUNT=$(gh issue list -R RapierCraftStudios/forge --state all --label "audit-finding" --limit 200 \
+ISSUE_SPEC_COUNT=$(gh issue list -R $FORGE_REPO --state all --label "audit-finding" --limit 200 \
   --json number,title,body,createdAt \
   --jq "[.[] | select(.createdAt > \"$SINCE\" and (.body | contains(\"ISSUE_SPEC\")))] | length")
 
@@ -416,13 +427,13 @@ echo "Issue structure compliance: $STRUCTURED_ISSUES / $TOTAL_ISSUES"
 ```bash
 # Persisted audit-agents summaries are posted to a designated Forge tracking issue
 # tagged with label "orchestration-metrics". Find it:
-TRACKING_ISSUE=$(gh issue list -R RapierCraftStudios/forge \
+TRACKING_ISSUE=$(gh issue list -R $FORGE_REPO \
   --state open --label "orchestration-metrics" --limit 1 \
   --json number --jq '.[0].number' 2>/dev/null)
 
 if [ -n "$TRACKING_ISSUE" ]; then
   # Fetch all FORGE:AUDIT-AGENTS comments posted since $SINCE
-  AUDIT_COMMENTS=$(gh api repos/RapierCraftStudios/forge/issues/$TRACKING_ISSUE/comments \
+  AUDIT_COMMENTS=$(gh api repos/$FORGE_REPO/issues/$TRACKING_ISSUE/comments \
     --jq "[.[] | select(.body | contains(\"FORGE:AUDIT-AGENTS\")) | select(.created_at > \"$SINCE\")]")
   echo "Found $(echo "$AUDIT_COMMENTS" | jq 'length') persisted audit-agents summaries in window"
 else
@@ -530,7 +541,7 @@ fi
 
 ```bash
 # All audit-finding issues created in the window
-AUDIT_FINDINGS=$(gh issue list -R RapierCraftStudios/forge --state all --label "audit-finding" \
+AUDIT_FINDINGS=$(gh issue list -R $FORGE_REPO --state all --label "audit-finding" \
   --limit 200 --json number,title,body,createdAt \
   --jq "[.[] | select(.createdAt > \"$SINCE\")]")
 
@@ -573,7 +584,7 @@ echo "$AUDIT_FINDINGS" | jq -r \
 # Severity breakdown (P1 vs P2 vs P3 from labels)
 echo ""
 echo "Severity breakdown:"
-gh issue list -R RapierCraftStudios/forge --state all --label "audit-finding" \
+gh issue list -R $FORGE_REPO --state all --label "audit-finding" \
   --limit 200 --json number,createdAt,labels \
   --jq "[.[] | select(.createdAt > \"$SINCE\")] | group_by(.labels | map(.name) | map(select(startswith(\"P\"))) | .[0]) | map({severity: .[0].labels | map(.name) | map(select(startswith(\"P\"))) | .[0], count: length})"
 ```
@@ -598,9 +609,9 @@ This phase locates conversation JSONL files for pipeline command sessions (work-
 # Convert a Claude Code project path to its ~/.claude/projects/ directory name
 # Rule: both '/' and '.' are replaced with '-'
 # Examples:
-#   /home/user/projects/forge          ->  -home-user-projects-forge
-#   /home/user/projects/ScraperAPI/.claude/worktrees/fix-branch
-#                                      ->  -home-user-projects-ScraperAPI--claude-worktrees-fix-branch
+#   /home/user/projects/myproject          ->  -home-user-projects-myproject
+#   /home/user/projects/myproject/.claude/worktrees/fix-branch
+#                                          ->  -home-user-projects-myproject--claude-worktrees-fix-branch
 #   (note: .claude -> --claude because '.' becomes '-' and surrounding '/' also become '-')
 _session_project_dir() {
     echo "$1" | sed 's|[/.]|-|g'
@@ -2035,7 +2046,7 @@ For each of the top 3 defect categories:
 Create a detailed health report as a GitHub issue in the Forge repo:
 
 ```bash
-gh issue create -R RapierCraftStudios/forge \
+gh issue create -R $FORGE_REPO \
   --title "Pipeline Health: $REPO — $(date +%Y-%m-%d) — Score: [SCORE]/100" \
   --label "health-report" \
   --body "$(cat <<'EOF'
@@ -2264,7 +2275,7 @@ For each improvement proposal, create a trackable issue using the `/issue` struc
 - Metric < 10% below target → `P3`
 
 ```bash
-gh issue create -R RapierCraftStudios/forge \
+gh issue create -R $FORGE_REPO \
   --title "fix([command]): [description]" \
   --label "[bug|enhancement|feature],[P1|P2|P3]" \
   --body "## Problem
@@ -2338,6 +2349,6 @@ Pipeline health signals:
 
 Top defect categories: [CAT1] ([N]), [CAT2] ([N]), [CAT3] ([N])
 
-Proposed improvements: [N] issues created in RapierCraftStudios/forge
+Proposed improvements: [N] issues created in $FORGE_REPO
 Health report: [ISSUE_URL]
 ```

package/commands/qa-sweep.md

@@ -95,9 +95,72 @@ Depth-first, workflow-driven:
 
 ## Phase 0: Setup & Auth
 
-1. Verify services: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` and `:8000/api/v1/health`
-2. If down: `cd /home/mrdubey/projects/ScraperAPI/alterlab && docker compose up -d --build web api`
-3. Login via Playwright: navigate `/auth/login`, fill `claude@alterlab.dev` / `ClaudeCode2026!`, submit
+**Load config from forge.yaml** before running any checks:
+
+```bash
+QA_CONFIG=$(python3 - <<'PYEOF'
+import yaml, sys, os
+
+config_path = os.environ.get('FORGE_CONFIG', 'forge.yaml')
+try:
+    cfg = yaml.safe_load(open(config_path))
+except FileNotFoundError:
+    print('ERROR: forge.yaml not found. Run `cp forge.yaml.example forge.yaml` and configure your project.')
+    sys.exit(1)
+
+paths = cfg.get('paths', {})
+root = paths.get('root', '')
+if not root:
+    print('ERROR: forge.yaml missing paths.root — qa-sweep needs the project root to discover pages and start services.')
+    sys.exit(1)
+
+svc = cfg.get('services', {})
+app_url = svc.get('app_url', 'http://localhost:3000')
+api_url = svc.get('api_url', 'http://localhost:8000')
+
+# Read QA credentials from credentials file (graceful: empty string if not set)
+creds = paths.get('credentials', {})
+creds_file = creds.get('file', '') if isinstance(creds, dict) else ''
+qa_user = ''
+qa_pass = ''
+if creds_file:
+    try:
+        creds_data = yaml.safe_load(open(creds_file))
+        qa_section = creds_data.get('qa', {})
+        qa_user = qa_section.get('username', '')
+        qa_pass = qa_section.get('password', '')
+    except (FileNotFoundError, AttributeError):
+        pass  # Credentials file optional — will surface as empty QA_USER/QA_PASS
+
+print(root)
+print(app_url)
+print(api_url)
+print(qa_user)
+print(qa_pass)
+PYEOF
+)
+
+if echo "$QA_CONFIG" | grep -q '^ERROR:'; then
+    echo "$QA_CONFIG"
+    exit 1
+fi
+
+PROJECT_ROOT=$(echo "$QA_CONFIG" | sed -n '1p')
+APP_URL=$(echo "$QA_CONFIG" | sed -n '2p')
+API_URL=$(echo "$QA_CONFIG" | sed -n '3p')
+QA_USER=$(echo "$QA_CONFIG" | sed -n '4p')
+QA_PASS=$(echo "$QA_CONFIG" | sed -n '5p')
+
+if [ -z "$QA_USER" ] || [ -z "$QA_PASS" ]; then
+    echo "WARNING: QA credentials not configured in credentials file."
+    echo "Add qa.username and qa.password to the credentials file at paths.credentials.file in forge.yaml."
+    echo "Proceeding — login step will require manual credential entry."
+fi
+```
+
+1. Verify services: `curl -s -o /dev/null -w "%{http_code}" $APP_URL` and `$API_URL/api/v1/health`
+2. If down: `cd $PROJECT_ROOT && docker compose up -d --build web api`
+3. Login via Playwright: navigate `/auth/login`, fill `$QA_USER` / `$QA_PASS`, submit
 4. Capture baseline data from dashboard/sidebar: balance (exact number + format), user info, plan/tier, notification counts, nav items
 
 ---
@@ -107,7 +170,7 @@ Depth-first, workflow-driven:
 **Dynamic discovery from filesystem** (NOT hardcoded):
 
 ```bash
-cd /home/mrdubey/projects/ScraperAPI/alterlab/web/src/app
+cd $PROJECT_ROOT/web/src/app
 find . -name "page.tsx" -o -name "page.js" | sort
 ```
 
@@ -229,7 +292,7 @@ Next steps: `/orchestrate` on P0/P1 issues before deploy.
 ## Safety Rules
 
 1. NEVER modify production data — only read/interact. CAN create+delete test data.
-2. Test user only: `claude@alterlab.dev` / `ClaudeCode2026!`
+2. Test user only: `$QA_USER` (configured in credentials file via forge.yaml)
 3. Handle dialogs gracefully (accept/dismiss, don't leave hanging)
 4. Snapshot before interactions
 5. Check console after EVERY interaction

package/commands/quality-gate.md

@@ -330,6 +330,24 @@ For shell scripts that make HTTP requests to internal services:
 2. Check that auth tokens are included if the endpoint requires them
 3. Verify the URL path actually exists
 
+Before running host-header checks on shell scripts, read project-specific internal service patterns from `forge.yaml` and export them so `verify-host-headers.sh` can append them to its generic defaults:
+
+```bash
+# Read project-specific internal service patterns from forge.yaml (if present)
+FORGE_INTERNAL_PATTERNS=""
+if [ -f "{WORKTREE_PATH}/forge.yaml" ]; then
+    # Extract internal_service_patterns list (one pattern per line) and join with |
+    FORGE_INTERNAL_PATTERNS=$(grep -A 999 'internal_service_patterns:' "{WORKTREE_PATH}/forge.yaml" \
+        | grep -E '^\s*-\s+' \
+        | sed 's/^\s*-\s*//' \
+        | tr -d '"'"'" \
+        | paste -sd '|' -)
+fi
+export FORGE_INTERNAL_PATTERNS
+```
+
+The script `verify-host-headers.sh` checks for the `FORGE_INTERNAL_PATTERNS` env var and appends any project-specific patterns to its generic defaults (localhost, 127.0.0.1, api-, worker-, 172.x.x.x, IP env vars) when the var is set.
+
 ### 2G.5: Hardcoded localhost in DB connection functions (shell scripts)
 
 **Triggered when**: changed `*.sh` files contain DB connection patterns (`PGPASSWORD`, `createdb`, `psql`, `pg_dump`, `pg_restore`).

package/commands/review-pr-agents.md

@@ -157,12 +157,13 @@ Append this block at the very end of your comment (after the `---` footer line,
 
 **Prompt template:**
 ```
-You are performing a security and code quality scan on PR #[PR_NUMBER] for AlterLab (web scraping DaaS platform).
+You are performing a security and code quality scan on PR #[PR_NUMBER] for [PROJECT_NAME].
 
 ## Context
 - PR title: [TITLE]
 - Services touched: [SERVICES]
 - Files changed: [FILE_LIST]
+[PROJECT_CONTEXT]
 
 ## Your Mission
 Scan ALL changed code for security vulnerabilities and code quality issues. This is the baseline review that runs on every PR.
@@ -538,34 +539,24 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for authentication and authorization correctness in AlterLab.
+You are auditing PR #[PR_NUMBER] for authentication and authorization correctness in [PROJECT_NAME].
 
 ## CRITICAL PROJECT CONVENTIONS — You MUST enforce these:
 
-### Auth Dependency Rules
-AlterLab has TWO auth dependencies. Using the wrong one is a security bug:
-
-| Route Type | Auth Dependency | How It Works | Example Routes |
-|-----------|----------------|-------------|----------------|
-| **Dashboard routes** (browser sessions) | `SessionUser` | JWT from httpOnly cookie, set by NextAuth | `/api/dashboard/*`, `/api/billing/*`, `/api/keys/*`, `/api/users/*` |
-| **Public API routes** (SDK/external) | `CurrentUser` | API key from `X-API-Key` header | `/api/v1/scrape`, `/api/v1/jobs/*` |
-| **Admin routes** | `CurrentUser` + `is_admin` check | API key with admin flag | `/api/v1/admin/*` |
-
-**VIOLATION**: Using `CurrentUser` on a dashboard route exposes API key auth to browser sessions.
-**VIOLATION**: Using `SessionUser` on a public API route breaks SDK authentication.
+[DOMAIN_CONTEXT]
 
 ### How to Check
 ```bash
 # Find auth patterns in changed files
-grep -rn "CurrentUser\|SessionUser\|Depends(get_current" [CHANGED_FILES]
+grep -rn "auth\|Depends\|get_current\|verify_token\|require_auth" [CHANGED_FILES]
 
 # Cross-reference with route path to determine if correct
-grep -rn "@router\.(get\|post\|put\|delete)" [CHANGED_FILES]
+grep -rn "@router\.(get\|post\|put\|delete)\|app\.(get\|post\|put\|delete)" [CHANGED_FILES]
 ```
 
 ### What to Verify
 1. Every new endpoint has an auth dependency (no unauthenticated endpoints without justification)
-2. The CORRECT auth dependency is used based on route type (see table above)
+2. The CORRECT auth dependency is used based on route type (refer to project conventions in [DOMAIN_CONTEXT] above — if absent, derive from surrounding code patterns)
 3. Multi-tenancy: resource access checks `user_id` ownership BEFORE returning data
 4. Rate limiting is applied to public-facing endpoints
 5. No IDOR vulnerabilities (different error codes for 404 vs 403 leak existence)
@@ -675,30 +666,15 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for billing integrity in AlterLab.
+You are auditing PR #[PR_NUMBER] for billing integrity in [PROJECT_NAME].
 
-CRITICAL: Users pay per scrape. Any billing bug = revenue loss or user overcharging.
+CRITICAL: Any billing bug = revenue loss or user overcharging.
 
 ## Project Billing Architecture
 
-The billing flow spans two services:
-```
-API (pre-scrape):
-  1. Check user balance (services/api/app/core/credits.py or billing/)
-  2. Pre-debit estimated cost based on requested tier
-  3. Queue job to Redis
-
-Worker (post-scrape):
-  4. Execute scrape, determine actual tier used
-  5. Reconcile: refund difference if actual tier < estimated tier
-  6. Record final billing in job result
-```
+[DOMAIN_CONTEXT]
 
-## Key Files to Cross-Reference
-- Pricing: `services/api/app/core/pricing.py` (TIER_COSTS)
-- Credits: `services/api/app/core/credits.py` or `billing/`
-- Reconciliation: `services/worker/worker/queues.py` (search for "reconcil")
-- Tier determination: `services/worker/worker/unified_consumer.py`
+If no billing context is configured above, derive the billing flow from the changed files: trace credit check → debit → execution → reconciliation paths.
 
 ## What to Verify
 1. **Trace the full flow**: credit check → pre-debit → execution → reconciliation
@@ -781,7 +757,7 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for concurrency bugs and race conditions in AlterLab.
+You are auditing PR #[PR_NUMBER] for concurrency bugs and race conditions in [PROJECT_NAME].
 
 CRITICAL: This is a billing system. Double-spend = revenue loss.
 
@@ -915,19 +891,13 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for scraper logic correctness in AlterLab.
+You are auditing PR #[PR_NUMBER] for domain-specific logic correctness in [PROJECT_NAME].
 
-## Tier System
-AlterLab uses tiered scraping with escalation:
-T1 (curl/httpx) → T2 (HTTP with headers) → T3 (stealth proxy) → T3.5 (light JS) → T4 (full browser/Playwright)
+## Project Domain Architecture
 
-Each tier has different costs. Tier selection affects billing.
+[DOMAIN_CONTEXT]
 
-## Key Architecture
-- **Tier escalation**: `services/worker/worker/unified_consumer.py` — `_parallel_tier_race()`, `get_optimal_starting_tier()`
-- **Domain playbooks**: `services/worker/config/domain_playbooks.json` — domain-specific tier overrides
-- **Cortex intelligence**: `services/worker/worker/cortex_client.py` — learned headers/cookies/min_tier
-- **Content validation**: Determines if scrape succeeded or needs tier escalation
+If no domain context is configured above, derive the architecture from the changed files: read the primary consumer/worker/handler files to understand the execution model.
 
 ## What to Verify
 1. **Tier selection**: Is the starting tier correct? Does escalation logic work?
@@ -1096,14 +1066,13 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for frontend quality in AlterLab (Next.js 15, App Router, React Server Components).
+You are auditing PR #[PR_NUMBER] for frontend quality in [PROJECT_NAME].
 
 ## Project Frontend Conventions
-- **Default to Server Components** — only use 'use client' when needed (hooks, event handlers, browser APIs)
-- **Data fetching**: SWR for client-side, server actions or API routes for mutations
-- **Styling**: Tailwind CSS with oklch dark mode, shadcn/ui components
-- **Forms**: Zod for validation schemas
-- **Auth in frontend**: NextAuth sessions, not direct API key usage
+
+[DOMAIN_CONTEXT]
+
+If no frontend context is configured above, derive conventions from the changed files: check package.json for framework versions and look at existing patterns in surrounding components.
 
 ## What to Check
 1. **Server vs Client components**: Is 'use client' used appropriately? Could this be a Server Component instead?
@@ -1176,15 +1145,13 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for API design consistency in AlterLab.
+You are auditing PR #[PR_NUMBER] for API design consistency in [PROJECT_NAME].
 
 ## Project API Conventions
-- **Router registration**: New routers must be registered in `services/api/app/main.py`
-- **Schema validation**: All request/response models use Pydantic with type hints
-- **Error format**: Consistent error response schema across all endpoints
-- **Versioning**: Public API endpoints under `/api/v1/`, internal under `/api/`
-- **Auth**: Every endpoint must have explicit auth dependency (see Auth Conventions)
-- **Naming**: snake_case for Python, camelCase for JSON response fields (if using alias)
+
+[DOMAIN_CONTEXT]
+
+If no API context is configured above, derive conventions from the changed files: read the main router/application entrypoint to understand registration patterns, and check neighboring endpoints for error format and naming conventions.
 
 ## What to Check
 1. **Registration**: Is the new router registered in main.py?
@@ -1302,7 +1269,9 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for database changes in AlterLab (PostgreSQL).
+You are auditing PR #[PR_NUMBER] for database changes in [PROJECT_NAME].
+
+[DOMAIN_CONTEXT]
 
 ## What to Check
 1. **SQL correctness** (CHECK FIRST — a query that errors at runtime breaks the whole page):
@@ -1393,14 +1362,13 @@ EOF
 
 **Prompt template:**
 ```
-You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in AlterLab.
+You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in [PROJECT_NAME].
 
 ## Deployment Architecture
-- **Blue-green deployment**: Both old and new versions run simultaneously during rollout
-- **Traefik**: Reverse proxy, handles routing. Config at `traefik/dynamic/active.yml`
-- **Docker Compose**: `docker-compose.yml` (dev), `docker-compose.prod.yml` (prod)
-- **Services**: api-blue/green, web-blue/green, worker-blue/green, stripe-webhooks-blue/green, postgres, redis, traefik
-- **CI/CD**: GitHub Actions deploys on merge to `main`
+
+[DOMAIN_CONTEXT]
+
+If no infra context is configured above, derive the deployment model from the changed files: read docker-compose files, GitHub Actions workflows, and entrypoint scripts to understand the deployment pipeline.
 
 ## What to Check
 1. **Downtime risk**: Will this change cause container restarts during deploy?
@@ -1516,27 +1484,21 @@ You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in Alt
    - Common siblings: `ci.yml` ↔ `deploy-production.yml` (share `test-api`, `test-web` jobs), `deploy-production.yml` ↔ `hotfix-deploy.yml` (share build/deploy logic)
    **This is the #1 cause of "CI passed but deploy failed" incidents.** Do not skip this check.
 10. **Deploy scope awareness** (ALWAYS run — checks whether ALL changed services will actually be deployed):
-   AlterLab has two separate deploy pipelines. The PR's CI/CD only covers one of them:
-   | Path prefix | Deploy mechanism | Auto-triggered? |
-   |-------------|-----------------|-----------------|
-   | `web/**`, `services/api/**` | `deploy-production.yml` | Yes (on merge to main) |
-   | `services/worker/**` | `deploy-production.yml` | Yes (on merge to main) |
-   | `services/session-ingest/**` | `deploy-e2e.yml` | **NO — manual trigger required** |
-   | `services/herald/**` | `deploy-e2e.yml` | **NO — manual trigger required** |
-   | `services/cortex/**` | `deploy-e2e.yml` | **NO — manual trigger required** |
-
-   **Steps**:
+   This project may have multiple deploy pipelines. Check which pipelines cover which services:
+
    ```bash
+   # List all GitHub Actions workflows
+   ls .github/workflows/
    # List all paths changed in this PR
    gh pr diff [PR_NUMBER] --name-only
    ```
-   - For each changed path, determine which deploy mechanism covers it (use table above)
-   - If ALL changed paths are covered by `deploy-production.yml` → no action needed
-   - **If ANY changed path maps to `deploy-e2e.yml` (session-ingest, herald, cortex)**:
-     - Flag as CONFIRMED BLOCKING finding
-     - Verdict: `BLOCK — Deploy prerequisite: manually trigger deploy-e2e.yml for [service names] before or after this deploy`
-     - Rationale: These services run via PM2 on the E2E host and are NOT rebuilt by the Docker deploy pipeline. Deploying without them leaves a broken contract between the API/web layer and the E2E service layer (e.g., a new token header sent by web but not yet verified by session-ingest causes 401/500 errors).
-   E2E services run via PM2 on the E2E host and are not part of the Docker deploy pipeline. When the API/web layer deploys a new auth contract (new token type, new header requirement) without a corresponding E2E service deploy, the two layers operate on mismatched contracts — resulting in 401/500 errors until the E2E service is manually redeployed.
+
+   For each changed path: read the `.github/workflows/` directory to determine which workflow deploys it and whether it's auto-triggered or requires manual action. If any changed service path is NOT covered by an auto-triggered workflow on merge:
+   - Flag as CONFIRMED BLOCKING finding
+   - Verdict: `BLOCK — Deploy prerequisite: manually trigger [workflow] for [service names] before or after this deploy`
+   - Rationale: Services not covered by the auto-deploy pipeline will not be updated on merge, leaving a broken contract between deployed and un-deployed layers.
+
+   If `[DOMAIN_CONTEXT]` above contains a deploy pipeline table, use it as the authoritative source for path → pipeline mapping.
 11. **Config field type/doc-comment consistency** (when the diff introduces new pydantic-settings fields):
    When a new env var is introduced as a pydantic-settings field with a collection type (`list[str]`, `List[str]`, `set[str]`, `Set[str]`), cross-reference the field's type annotation against the format hint documented in `.env.example`. **pydantic-settings v2 parses collection-type fields via `json.loads()` — they require JSON array format like `["a","b"]`, NOT comma-separated format like `a,b`**. A doc comment saying "comma-separated" on a `list[str]` field is a CONFIRMED HIGH finding — it guarantees a startup crash for anyone following the documented format.
    ```bash
@@ -1610,7 +1572,13 @@ You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in Alt
    The INFRA agent's secret delivery chain verification (env var present in ENV_MAPPING) does NOT verify whether the fallback value is safe. A config file can pass all delivery chain checks while still containing an active placeholder credential for any environment where the env var is absent. This check targets that gap. <!-- Added: forge#301 -->
 
 14. **Host-side database tool invocations in deploy scripts** (when `.github/workflows/*.yml`, `scripts/deploy*.sh`, or any deploy entrypoint script in the diff invokes `psql`, `createdb`, or `pg_dump` directly on the host):
-   Host-side `psql`, `createdb`, and `pg_dump` connect to PostgreSQL via the host's port binding (`localhost:5432` or `127.0.0.1:5432`). In SSH-based deploy contexts, the host-side port mapping to PostgreSQL's Docker container is unreliable — the listening address may differ from what the SSH session can reach, and the mapping is not guaranteed to be present at all in hardened host configurations. The migration system already uses `docker exec alterlab-postgres` for all database operations — deploy scripts must do the same.
+   Host-side `psql`, `createdb`, and `pg_dump` connect to PostgreSQL via the host's port binding (`localhost:5432` or `127.0.0.1:5432`). In SSH-based deploy contexts, the host-side port mapping to PostgreSQL's Docker container is unreliable — the listening address may differ from what the SSH session can reach, and the mapping is not guaranteed to be present at all in hardened host configurations. The safe pattern is to use `docker exec <postgres-container>` for all database operations in deploy scripts.
+
+   To find the correct container name, grep the project's docker-compose files:
+   ```bash
+   grep -n "container_name" docker-compose*.yml | grep -i "postgres\|pg\|db"
+   ```
+   Use the container name found (referred to as `[DB_CONTAINER]` in examples below).
 
    **Scan for host-side database tool invocations:**
    ```bash
@@ -1623,13 +1591,13 @@ You are auditing PR #[PR_NUMBER] for infrastructure and deployment safety in Alt
    **For each match, classify:**
    - `psql`, `createdb`, `pg_dump`, or `pg_restore` called directly (not via `docker exec`): **CONFIRMED HIGH**
      - Rationale: Host-side port mappings to PostgreSQL's Docker container are unreliable in SSH deploy contexts. A deploy step that fails to connect leaves post-deploy database setup incomplete — silently if `continue-on-error: true` is set, or rolls back a successful deploy if not.
-     - The safe pattern used by the migration system: `docker exec alterlab-postgres psql -U $POSTGRES_USER -d $POSTGRES_DB -c "..."` or `docker exec alterlab-postgres createdb -U $POSTGRES_USER $DB_NAME`
-   - `psql`/`createdb`/`pg_dump` called inside `docker exec alterlab-postgres ...`: **OK** — this is the safe pattern.
+     - The safe pattern: `docker exec [DB_CONTAINER] psql -U $POSTGRES_USER -d $POSTGRES_DB -c "..."` or `docker exec [DB_CONTAINER] createdb -U $POSTGRES_USER $DB_NAME`
+   - `psql`/`createdb`/`pg_dump` called inside `docker exec [DB_CONTAINER] ...`: **OK** — this is the safe pattern.
 
-   **Recommended fix**: Replace host-side invocations with `docker exec alterlab-postgres` equivalents:
-   - `psql -h localhost -U $USER -d $DB -c "..."` → `docker exec alterlab-postgres psql -U $USER -d $DB -c "..."`
-   - `createdb -h localhost -U $USER $DB_NAME` → `docker exec alterlab-postgres createdb -U $USER $DB_NAME`
-   - `pg_dump -h localhost -U $USER $DB` → `docker exec alterlab-postgres pg_dump -U $USER $DB`
+   **Recommended fix**: Replace host-side invocations with `docker exec [DB_CONTAINER]` equivalents:
+   - `psql -h localhost -U $USER -d $DB -c "..."` → `docker exec [DB_CONTAINER] psql -U $USER -d $DB -c "..."`
+   - `createdb -h localhost -U $USER $DB_NAME` → `docker exec [DB_CONTAINER] createdb -U $USER $DB_NAME`
+   - `pg_dump -h localhost -U $USER $DB` → `docker exec [DB_CONTAINER] pg_dump -U $USER $DB`
 
    Host-side port bindings to Docker containers are unreliable in SSH deploy contexts. Deploy scripts that invoke database tools directly cannot depend on `localhost:5432` being reachable; the same operation via `docker exec` bypasses the host network entirely and always succeeds when the container is running. <!-- Added: forge#322 -->