forgedock 1.0.5 → 1.0.7

package/bin/labels.json

@@ -0,0 +1,152 @@
+[
+  {
+    "name": "priority:P0",
+    "color": "B60205",
+    "description": "Critical priority — production broken, data loss, security breach. Managed by ForgeDock."
+  },
+  {
+    "name": "priority:P1",
+    "color": "D93F0B",
+    "description": "High priority — major feature broken, no workaround. Managed by ForgeDock."
+  },
+  {
+    "name": "priority:P2",
+    "color": "FBCA04",
+    "description": "Medium priority — impaired functionality, workaround exists. Managed by ForgeDock."
+  },
+  {
+    "name": "priority:P3",
+    "color": "C2E0C6",
+    "description": "Low priority — minor issue or polish. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:investigating",
+    "color": "1D76DB",
+    "description": "Pipeline: investigation phase in progress. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:ready-to-build",
+    "color": "0075CA",
+    "description": "Pipeline: investigation complete, ready for build. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:building",
+    "color": "0052CC",
+    "description": "Pipeline: implementation in progress. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:in-review",
+    "color": "5319E7",
+    "description": "Pipeline: PR created, under review. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:merged",
+    "color": "0E8A16",
+    "description": "Pipeline: PR merged, issue closed. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:decomposed",
+    "color": "BFD4F2",
+    "description": "Pipeline: decomposed into sub-issues. Managed by ForgeDock."
+  },
+  {
+    "name": "workflow:invalid",
+    "color": "CCCCCC",
+    "description": "Pipeline: issue closed as invalid after investigation. Managed by ForgeDock."
+  },
+  {
+    "name": "needs-human",
+    "color": "E4E669",
+    "description": "Pipeline stalled — requires human intervention. Managed by ForgeDock."
+  },
+  {
+    "name": "review-finding",
+    "color": "D93F0B",
+    "description": "Defect or improvement found during automated PR review. Managed by ForgeDock."
+  },
+  {
+    "name": "needs-validation",
+    "color": "FBCA04",
+    "description": "Review finding awaiting human validation. Managed by ForgeDock."
+  },
+  {
+    "name": "validated",
+    "color": "0E8A16",
+    "description": "Review finding confirmed as a real issue. Managed by ForgeDock."
+  },
+  {
+    "name": "false-positive",
+    "color": "CCCCCC",
+    "description": "Review finding dismissed as a false positive. Managed by ForgeDock."
+  },
+  {
+    "name": "staging-review",
+    "color": "1D76DB",
+    "description": "Finding from a staging branch review before deploy to main. Managed by ForgeDock."
+  },
+  {
+    "name": "audit-finding",
+    "color": "D93F0B",
+    "description": "Security or compliance defect found during audit. Managed by ForgeDock."
+  },
+  {
+    "name": "orchestration-metrics",
+    "color": "5319E7",
+    "description": "Running log of persisted audit-agents efficiency summaries. Managed by ForgeDock."
+  },
+  {
+    "name": "health-report",
+    "color": "1D76DB",
+    "description": "Pipeline health report issue. Managed by ForgeDock."
+  },
+  {
+    "name": "bug",
+    "color": "D73A4A",
+    "description": "Something isn't working. Managed by ForgeDock."
+  },
+  {
+    "name": "enhancement",
+    "color": "A2EEEF",
+    "description": "New feature or request. Managed by ForgeDock."
+  },
+  {
+    "name": "feature",
+    "color": "0075CA",
+    "description": "New feature implementation. Managed by ForgeDock."
+  },
+  {
+    "name": "refactor",
+    "color": "FEF2C0",
+    "description": "Code restructuring without behavior change. Managed by ForgeDock."
+  },
+  {
+    "name": "dead-code",
+    "color": "E4E669",
+    "description": "Unused code to be removed. Managed by ForgeDock."
+  },
+  {
+    "name": "improvement",
+    "color": "C5DEF5",
+    "description": "Non-bug improvement to existing functionality. Managed by ForgeDock."
+  },
+  {
+    "name": "documentation",
+    "color": "0075CA",
+    "description": "Documentation addition or update. Managed by ForgeDock."
+  },
+  {
+    "name": "qa",
+    "color": "E99695",
+    "description": "Quality assurance or testing issue. Managed by ForgeDock."
+  },
+  {
+    "name": "security",
+    "color": "B60205",
+    "description": "Security vulnerability or hardening. Managed by ForgeDock."
+  },
+  {
+    "name": "performance",
+    "color": "F9D0C4",
+    "description": "Performance optimization or regression. Managed by ForgeDock."
+  }
+]

package/commands/audit-agents.md

@@ -343,9 +343,11 @@ This step posts a structured `<!-- FORGE:AUDIT-AGENTS -->` summary comment to th
 **Step 4E.1 — Locate or create the tracking issue**:
 
 ```bash
-# Ensure the label exists before using it (gh issue create fails with GraphQL error if label is absent)
+# Ensure the label exists before using it (gh issue create fails with GraphQL error if label is absent).
+# Color and description match the canonical ForgeDock label manifest (bin/labels.json).
+# Run `npx forgedock labels setup` to bootstrap all managed labels at once.
 gh label create "orchestration-metrics" -R {FORGE_REPO} \
-  --color "5319E7" --description "Running log of persisted audit-agents efficiency summaries" \
+  --color "5319E7" --description "Running log of persisted audit-agents efficiency summaries. Managed by ForgeDock." \
   --force 2>/dev/null || true
 
 TRACKING_ISSUE=$(gh issue list -R {FORGE_REPO} \

package/commands/autopilot.md

@@ -11,6 +11,7 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 - `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
 - `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
 - `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
+- `{BILLING_ENABLED}` ← `billing.enabled` (optional, default `false`) — set to `true` to enable Stripe data collection in the Analytics Snapshot agent
 
 You are an autonomous improvement engine for this project. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
 
@@ -51,25 +52,31 @@ DRY_RUN = true if --dry-run present
 ```bash
 echo "=== Autopilot Cycle: $(date -u +%Y-%m-%dT%H:%M:%SZ) ==="
 
+# Portable ISO-8601 date arithmetic using python3 (works on Windows, macOS, Linux).
+# Replaces GNU-only `date -u -d 'N days ago'` which fails on Windows and macOS.
+DATE_3D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=3)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+DATE_7D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=7)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+DATE_1D_AGO=$(python3 -c "from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) - timedelta(days=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+
 # Recent closed issues (last 3 days) — what was fixed recently?
 gh issue list --state closed --json number,title,labels,closedAt \
-  --jq '[.[] | select(.closedAt > "'$(date -u -d '3 days ago' +%Y-%m-%dT%H:%M:%SZ)'")] | length' 2>/dev/null || echo "0"
+  --jq '[.[] | select(.closedAt > "'"$DATE_3D_AGO"'")] | length' 2>/dev/null || echo "0"
 
 # Open issue count by priority
-gh issue list --state open --label P0 --json number --jq 'length'
-gh issue list --state open --label P1 --json number --jq 'length'
-gh issue list --state open --label P2 --json number --jq 'length'
+gh issue list --state open --label "priority:P0" --json number --jq 'length'
+gh issue list --state open --label "priority:P1" --json number --jq 'length'
+gh issue list --state open --label "priority:P2" --json number --jq 'length'
 
 # Stale issues (open, no workflow label, older than 7 days)
 gh issue list --state open --limit 200 --json number,title,labels,createdAt \
   --jq '[.[] | select(
     (.labels | map(.name) | any(startswith("workflow:")) | not) and
-    (.createdAt < "'$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)'")
+    (.createdAt < "'"$DATE_7D_AGO"'")
   )] | length'
 
 # Failed CI runs in last 24h
 gh run list --limit 30 --json conclusion,createdAt \
-  --jq '[.[] | select(.conclusion == "failure" and .createdAt > "'$(date -u -d '1 day ago' +%Y-%m-%dT%H:%M:%SZ)'")] | length'
+  --jq '[.[] | select(.conclusion == "failure" and .createdAt > "'"$DATE_1D_AGO"'")] | length'
 ```
 
 Store these as `BASELINE` metrics for the cycle report.
@@ -77,7 +84,7 @@ Store these as `BASELINE` metrics for the cycle report.
 ### 0B: Check for open P0s
 
 ```bash
-gh issue list --state open --label P0 --json number,title --jq '.[] | "#\(.number) \(.title)"'
+gh issue list --state open --label "priority:P0" --json number,title --jq '.[] | "#\(.number) \(.title)"'
 ```
 
 If any P0 issues exist:
@@ -140,8 +147,9 @@ Analyze GitHub issue backlog:
 Quick analytics pulse — just the key metrics, not a full audit:
 1. Read credentials from {CREDENTIALS_FILE} (set via paths.credentials.file in forge.yaml)
 2. GSC: mcp__gsc__search_analytics for last 7 days — total clicks, impressions, avg position
-3. Stripe: mcp__stripe__retrieve_balance — current balance
-4. Return: clicks trend (up/down), any revenue, notable changes
+3. Stripe (only if {BILLING_ENABLED} is true): mcp__stripe__retrieve_balance — current balance.
+   Skip this step entirely if {BILLING_ENABLED} is false — do NOT call any Stripe MCP tools.
+4. Return: clicks trend (up/down), revenue (or "N/A — billing.enabled: false" if skipped), notable changes
 ```
 
 ### 1B: Collect results
@@ -291,7 +299,7 @@ Print a structured report:
 
 ### Analytics Pulse
 - Clicks (7d): {N} ({trend})
-- Revenue: ${N}
+- Revenue: ${N} (or "N/A — billing.enabled: false" if Stripe step was skipped)
 
 ### Actions Taken
 - Issues created: {count} ({list with numbers})
@@ -334,7 +342,7 @@ Pick the top `FIX_LIMIT` issues by this priority:
 ```bash
 # Get candidates
 gh issue list --state open --label "bug" --limit 50 --json number,title,labels,createdAt \
-  --jq 'sort_by(.labels | map(select(.name | startswith("P"))) | .[0].name) | .[:{FIX_LIMIT}] | .[] | "#\(.number) \(.title)"'
+  --jq 'sort_by(.labels | map(select(.name | startswith("priority:P"))) | .[0].name) | .[:{FIX_LIMIT}] | .[] | "#\(.number) \(.title)"'
 ```
 
 ### 4B: Present fix plan to user

package/commands/cleanup.md

@@ -25,11 +25,16 @@ GH_FLAG="-R $GH_REPO"
 REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
 STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
 PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
-PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' "$CONFIG_FILE")
-PROJECT_ID=$(yq '.project_board.project_id' "$CONFIG_FILE")
+PROJECT_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+PROJECT_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+# Project board field and option IDs — empty string when project_board section is absent
+STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_FIELD_ID=$(yq '.project_board.field_ids.workflow // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+STATUS_DONE_OPTION_ID=$(yq '.project_board.option_ids.status.done // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_MERGED_OPTION_ID=$(yq '.project_board.option_ids.workflow.merged // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, `{PROJECT_ID}`, `{STATUS_FIELD_ID}`, `{WORKFLOW_FIELD_ID}`, `{STATUS_DONE_OPTION_ID}`, and `{WORKFLOW_MERGED_OPTION_ID}` references below are populated from `forge.yaml`.
 
 ---
 
@@ -222,19 +227,29 @@ fi
 
 ## Phase 5: Sync Project Board (if `board` or `all`)
 
-For closed issues that are on the Project board but have stale fields:
+**Skip if `project_board` is not configured** — check resolved vars before proceeding:
 
 ```bash
-gh project item-list {PROJECT_NUMBER} --owner {PROJECT_BOARD_OWNER} --format json --limit 200
-```
+if [ -z "$PROJECT_BOARD_OWNER" ] || [ -z "$PROJECT_ID" ] || [ -z "$PROJECT_NUMBER" ]; then
+  echo "INFO: project_board not configured in forge.yaml — skipping board sync"
+else
+  # Board sync: mark closed issues as Done/Merged on the project board
 
-For each item where `content.state == "CLOSED"` but `status != "Done"` or `workflow` is not a terminal state:
+  # List all board items
+  ITEMS=$(gh project item-list "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --format json --limit 200)
 
-```bash
-gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" \
-  --field-id {PROJECT_BOARD_STATUS_FIELD_ID} --single-select-option-id {PROJECT_BOARD_STATUS_DONE_ID} 2>/dev/null || true  # Status=Done
-gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" \
-  --field-id {PROJECT_BOARD_WORKFLOW_FIELD_ID} --single-select-option-id {PROJECT_BOARD_WORKFLOW_MERGED_ID} 2>/dev/null || true  # Workflow=Merged
+  # For each item where content.state == "CLOSED" but status != "Done" or workflow is not terminal:
+  echo "$ITEMS" | jq -r '.items[] | select(.content.state == "CLOSED") | .id' | while read -r ITEM_ID; do
+    if [ -n "$STATUS_FIELD_ID" ] && [ -n "$STATUS_DONE_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$STATUS_FIELD_ID" --single-select-option-id "$STATUS_DONE_OPTION_ID" 2>/dev/null || true  # Status=Done
+    fi
+    if [ -n "$WORKFLOW_FIELD_ID" ] && [ -n "$WORKFLOW_MERGED_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$WORKFLOW_FIELD_ID" --single-select-option-id "$WORKFLOW_MERGED_OPTION_ID" 2>/dev/null || true  # Workflow=Merged
+    fi
+  done
+fi
 ```
 
 ---

package/commands/deploy-info.md

@@ -10,6 +10,8 @@ argument-hint: [staging | milestone/{slug} | compare {branch}]
 **Config variables used by this command** (set in `forge.yaml`):
 - `{REPO_PATH}` ← `paths.root` — project repository root
 - `{HEALTH_ENDPOINT}` ← `services.health_endpoint` (optional) — URL used in post-deploy health check
+- `{DEPLOY_WORKFLOW}` ← `deploy.workflow` (optional) — GitHub Actions workflow filename to trigger a deploy (e.g., `hotfix-deploy.yml`). When absent or empty, workflow-trigger steps are omitted.
+- `{DEPLOY_SECRETS_BACKEND}` ← `deploy.secrets_backend` (optional) — secrets delivery method (`sops`, `aws-sm`, `vault`, `ci-env`, `none`). Controls whether secret-chain checks run.
 
 You are the pipeline's deploy awareness layer. Before the user merges staging → main (triggering CI/CD deployment), this command shows exactly what's going out: which PRs, which issues, what changed, and what risks exist.
 
@@ -153,13 +155,20 @@ done
 # Full file diff summary
 git diff --stat origin/$TARGET..origin/$SOURCE
 
+# Read layout paths from forge.yaml, fall back to AlterLab defaults
+LAYOUT_API=$(yq '.review.layout.api // "services/api"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "services/api")
+LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "services/worker")
+LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "web/src/app")
+# Derive web root from pages root (strip trailing /src/app or similar suffix if present)
+LAYOUT_WEB=$(echo "$LAYOUT_PAGES" | sed 's|/src/app$||; s|/src$||')
+
 # Categorize by service
 echo "=== By Service ==="
 git diff --name-only origin/$TARGET..origin/$SOURCE | sort | while read f; do
   case "$f" in
-    services/api/*) echo "API: $f" ;;
-    services/worker/*) echo "WORKER: $f" ;;
-    web/*) echo "WEB: $f" ;;
+    ${LAYOUT_API}/*) echo "API: $f" ;;
+    ${LAYOUT_WORKER}/*) echo "WORKER: $f" ;;
+    ${LAYOUT_WEB}/*) echo "WEB: $f" ;;
     shared/*) echo "SHARED: $f" ;;
     infra/*) echo "INFRA: $f" ;;
     *) echo "OTHER: $f" ;;
@@ -170,8 +179,11 @@ done | sort
 ### Step 2E: Migration check
 
 ```bash
+# Read migrations path from forge.yaml, fall back to infra/migrations
+LAYOUT_MIGRATIONS=$(yq '.review.layout.migrations // "infra/migrations"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "infra/migrations")
+
 # Are there new migrations?
-MIGRATIONS=$(git diff --name-only origin/$TARGET..origin/$SOURCE | grep "^infra/migrations/" | sort)
+MIGRATIONS=$(git diff --name-only origin/$TARGET..origin/$SOURCE | grep "^${LAYOUT_MIGRATIONS}/" | sort)
 if [ -n "$MIGRATIONS" ]; then
   echo "⚠️ DATABASE MIGRATIONS INCLUDED:"
   echo "$MIGRATIONS"
@@ -195,7 +207,7 @@ Analyze the deploy payload and flag risks:
 |--------|-----------|--------|
 | Database migrations present | MEDIUM | Verify migrations are reversible |
 | `shared/` changes | LOW | Restart-only deploy possible (no rebuild) |
-| `.env.example` changes | HIGH | Verify SOPS + decrypt-secrets has new vars |
+| `.env.example` changes | HIGH | Verify secrets backend has new vars (see `deploy.secrets_backend`) |
 | `docker-compose.prod.yml` changes | HIGH | Review infrastructure changes carefully |
 | `infra/traefik/` changes | HIGH | Routing changes — test before full deploy |
 | 10+ PRs in one deploy | MEDIUM | Consider deploying in smaller batches |
@@ -205,17 +217,22 @@ Analyze the deploy payload and flag risks:
 ### Automated Checks
 
 ```bash
-# Check for new env vars that might not be in SOPS
+# Check for new env vars that might not be in the configured secrets backend
 NEW_ENV=$(git diff origin/$TARGET..origin/$SOURCE -- '.env.example' | grep "^+" | grep -v "^+++" | grep -v "^#")
 if [ -n "$NEW_ENV" ]; then
-  echo "⚠️ NEW ENVIRONMENT VARIABLES — verify they exist in SOPS:"
+  echo "⚠️ NEW ENVIRONMENT VARIABLES — verify they exist in your secrets backend ({deploy.secrets_backend}):"
   echo "$NEW_ENV"
-  # Cross-check with decrypt-secrets.sh
-  for var in $(echo "$NEW_ENV" | grep -oP '^\+\K[A-Z_]+'); do
-    if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
-      echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
-    fi
-  done
+  # Cross-check with SOPS chain (only when deploy.secrets_backend == "sops")
+  # If your project uses a different backend, skip this block and verify manually.
+  if [ "{deploy.secrets_backend}" = "sops" ]; then
+    for var in $(echo "$NEW_ENV" | grep -oP '^\+\K[A-Z_]+'); do
+      if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
+        echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      fi
+    done
+  else
+    echo "  ℹ️  SOPS chain check skipped — deploy.secrets_backend is '{deploy.secrets_backend}'. Verify new vars in your configured backend."
+  fi
 fi
 ```
 
@@ -232,7 +249,7 @@ Generate a checklist based on what's in the deploy:
 - [ ] All PRs in this deploy have been reviewed
 - [ ] No open `needs-human` issues blocking deploy
 - [ ] {If migrations} Database backup verified
-- [ ] {If new env vars} SOPS secrets updated and decrypt-secrets.sh has mapping
+- [ ] {If new env vars} Secrets backend ({deploy.secrets_backend}) updated with new vars; verify via your configured secrets chain
 - [ ] {If traefik changes} Routing tested locally
 
 ### Deploy Command
@@ -240,8 +257,9 @@ Generate a checklist based on what's in the deploy:
 # Standard deploy (merge staging → main via GitHub web UI)
 # CI/CD auto-triggers on push to main
 
-# Or manual trigger for specific services:
-gh workflow run hotfix-deploy.yml --ref main -f services={affected_services} -f reason="Deploy: {summary}"
+# Or manual trigger for specific services (requires deploy.workflow set in forge.yaml):
+gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services}={affected_services} -f {deploy.workflow_inputs.reason}="Deploy: {summary}"
+# If deploy.workflow is not configured, deploy via the GitHub web UI or your CI/CD provider.
 ```
 
 ### Post-Deploy
@@ -292,5 +310,6 @@ gh workflow run hotfix-deploy.yml --ref main -f services={affected_services} -f
 ---
 
 **Ready to deploy?** Merge staging → main via GitHub web UI, or run:
-`gh workflow run hotfix-deploy.yml --ref staging -f services={services} -f reason="Batch deploy"`
+`gh workflow run {deploy.workflow} --ref staging -f {deploy.workflow_inputs.services}={services} -f {deploy.workflow_inputs.reason}="Batch deploy"`
+*(requires `deploy.workflow` set in `forge.yaml`; omit this line if not configured)*
 ```

package/commands/incident-response.md

@@ -9,6 +9,7 @@ argument-hint: [issue number | "active" | "postmortem {issue}"]
 
 **Config variables used by this command** (set in `forge.yaml`):
 - `{REPO_PATH}` ← `paths.root` — project repository root
+- `{DEPLOY_WORKFLOW}` ← `deploy.workflow` (optional) — GitHub Actions workflow filename for hotfix deploys (e.g., `hotfix-deploy.yml`). When absent or empty, workflow-trigger and workflow-monitor steps are omitted.
 
 You are the pipeline's incident response coordinator. When production goes down or a critical bug surfaces, this command orchestrates the response: validates the hotfix before deploy, reconstructs the incident timeline, and produces a post-incident analysis.
 
@@ -39,7 +40,7 @@ You are the pipeline's incident response coordinator. When production goes down
 gh issue view {NUMBER} --json number,title,body,labels,state,comments,assignees,createdAt
 
 # If "active" — find most recent open P0
-gh issue list --state open --label "P0" --limit 5 --json number,title,createdAt,labels \
+gh issue list --state open --label "priority:P0" --limit 5 --json number,title,createdAt,labels \
   --jq 'sort_by(.createdAt) | reverse | .[0]'
 ```
 
@@ -55,8 +56,9 @@ Parse the issue to understand:
 gh pr list --state merged --base main --json number,title,mergedAt \
   --jq '[.[] | select(.mergedAt > (now - 86400 | todate))] | .[] | "\(.number) | \(.title) | \(.mergedAt)"'
 
-# Check recent hotfix deploys
-gh run list --workflow=hotfix-deploy.yml --limit 5 --json databaseId,status,conclusion,createdAt,displayTitle
+# Check recent hotfix deploys (requires deploy.workflow set in forge.yaml)
+# Skip this check if deploy.workflow is not configured.
+gh run list --workflow={deploy.workflow} --limit 5 --json databaseId,status,conclusion,createdAt,displayTitle
 ```
 
 #### Step 1C: Post incident acknowledgment
@@ -119,9 +121,10 @@ Your job:
    - Does it remove functionality other code depends on?
    - Are there syntax errors?
    - Does it change DB schema without a migration?
-4. Run compile checks:
-   - Python: python -m py_compile on changed .py files
-   - TypeScript: npx tsc --noEmit (if web/ files changed)
+4. Run compile checks (read forge.yaml → verification.commands for tool commands):
+   - Python: always run python -m py_compile on changed .py files (no config needed)
+   - Python format/lint: run verification.commands.python.format and .lint if configured; log "SKIPPED — not configured in verification.commands" if absent
+   - TypeScript: run verification.commands.typescript.typecheck if configured; log "SKIPPED — not configured in verification.commands" if absent
 5. Check if the fix is scoped tightly (minimal changes for the incident)
 
 Output:
@@ -143,10 +146,11 @@ gh issue comment {NUMBER} --body "$(cat <<'EOF'
 **Confidence**: {level}
 
 {If safe}:
-**Ready for deploy.** Run:
+**Ready for deploy.** Run (requires `deploy.workflow` set in `forge.yaml`):
 ```
-gh workflow run hotfix-deploy.yml --ref {FIX_BRANCH} -f services={affected_services} -f reason="P0: {TITLE}"
+gh workflow run {deploy.workflow} --ref {FIX_BRANCH} -f {deploy.workflow_inputs.services}={affected_services} -f {deploy.workflow_inputs.reason}="P0: {TITLE}"
 ```
+*(If `deploy.workflow` is not configured, merge the fix branch via the GitHub web UI or your CI/CD provider.)*
 
 {If not safe}:
 **Concerns found:**
@@ -164,8 +168,9 @@ EOF
 #### Step 3A: Watch the deploy workflow
 
 ```bash
-# Find the most recent hotfix-deploy run
-RUN_ID=$(gh run list --workflow=hotfix-deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')
+# Find the most recent deploy run (requires deploy.workflow set in forge.yaml)
+# Skip if deploy.workflow is not configured.
+RUN_ID=$(gh run list --workflow={deploy.workflow} --limit 1 --json databaseId --jq '.[0].databaseId')
 
 # Check status
 gh run view $RUN_ID --json status,conclusion,jobs

package/commands/issue.md

@@ -28,7 +28,7 @@ The user's input (`$ARGUMENTS`) can be:
 |-----------|---------|
 | Free-text description | "the billing page crashes when credits hit zero" |
 | URL to error/log | "https://sentry.io/..." or a pasted stack trace |
-| Reference to code | "the scraper queue leaks memory in unified_consumer.py" |
+| Reference to code | "the background worker leaks memory in task_processor.py" |
 | Feature request | "add a dark mode toggle to the dashboard settings page" |
 | Multi-repo prefix | "mcp: add list_schemas tool" or "n8n: fix credential refresh" |
 | Audit/investigation | "investigate why deploy times doubled this week" |
@@ -161,8 +161,8 @@ Format: `{prefix}: {concise description}`
 Rules:
 - **Max 80 characters**
 - Use conventional commit prefixes: `fix:`, `feat:`, `refactor:`, `investigate:`, `docs:`
-- Be specific — "fix: billing page crash" is bad, "fix: credit_service division by zero when user credits reach 0" is good
-- Include the component/domain if it helps: `fix(scraper): queue leak in unified_consumer heartbeat loop`
+- Be specific — "fix: billing page crash" is bad, "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" is good
+- Include the component/domain if it helps: `fix(worker): queue leak in task_processor heartbeat loop`
 - Never use vague words: "improve", "update", "change", "handle" without specifics
 
 ### 3B: Compose the body
@@ -258,6 +258,8 @@ Files/areas to examine:
 
 ### 3D: Pipeline Issue Template (machine-callable reference)
 
+> **Canonical Standard**: This template is the single source of truth for all automated issue creation in the ForgeDock pipeline. `milestone.md`, `orchestrate.md`, and `work-on/decompose.md` MUST use this template structure when creating issues programmatically. A shared convention is only useful if all create-paths enforce it — divergent inline templates in each command file cause acceptance-criteria drift and coverage gaps. See `work-on/decompose.md` Phase D0 for the investigation-gate pattern that enforces this standard at decomposition time. <!-- Added: forge#293 -->
+
 When pipeline agents create issues programmatically (not via user input), use this canonical template. All automated `gh issue create` calls across Forge commands MUST include these mandatory sections. Domain-specific sections are additive — preserve them, but wrap them with this structure.
 
 ```markdown
@@ -488,10 +490,10 @@ Create all {N} issues? (yes / adjust #N / cancel)
 | Bad Issue | Why It Fails | Good Version |
 |-----------|-------------|-------------|
 | "Fix docker mount" | Which compose file? Which mount? | "fix: `.gemini` volume mount in docker-compose.prod.yml missing rw flag" |
-| "Update billing" | What about billing? What's broken? | "fix: credit_service.deduct() raises DivisionByZero when user.credits == 0" |
-| "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in scraping routers" |
+| "Update billing" | What about billing? What's broken? | "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" |
+| "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in job processing routers" |
 | No affected files listed | Investigator guesses wrong files | List every file with what needs to change |
-| "Handle edge case" | Which edge case? In what function? | "fix: unified_consumer.process_job() silently drops jobs when queue.length > MAX_BATCH" |
+| "Handle edge case" | Which edge case? In what function? | "fix: task_processor.process_job() silently drops jobs when queue.length > MAX_BATCH" |
 | Missing override files | Fix is incomplete, deploy fails | Include docker-compose.prod.yml, .env.example, etc. |
 | P0 for a typo fix | Wastes priority signaling | Use P3 for cosmetic issues |