forgedock 1.0.5 → 1.0.7

package/commands/work-on.md

@@ -747,25 +747,50 @@ if iteration == max_iterations AND not PASS:
 
 ### 3H: Format and verify
 
+All tool commands are read from `forge.yaml → verification.commands`. When a key is absent, the step logs `SKIPPED — not configured in verification.commands` and continues rather than silently passing.
+
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
-black {PYTHON_FILES} && isort {PYTHON_FILES} && python -m py_compile {PYTHON_FILES}
+
+PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+if [ -n "$PYTHON_FORMAT" ]; then
+    eval "$PYTHON_FORMAT" 2>&1
+else
+    echo "SKIPPED — python.format not configured in verification.commands"
+fi
+
+# Compile check always runs (no config needed — catches syntax errors)
+python -m py_compile {PYTHON_FILES}
 ```
 `py_compile` failures are BLOCKING.
 
-**TypeScript (primary repo — has tsconfig.json)**:
+**TypeScript**:
 ```bash
 cd {WORKTREE_PATH}
-prettier --write {TS_FILES} && tsc --noEmit
-```
-`tsc --noEmit` failures are BLOCKING.
 
-**TypeScript (satellite repos)**:
-```bash
-cd {WORKTREE_PATH}
-npm run build && prettier --write {TS_FILES}
+TS_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+
+if [ -n "$TS_FORMAT" ]; then
+    eval "$TS_FORMAT" 2>&1
+else
+    echo "SKIPPED — typescript.format not configured in verification.commands"
+fi
+
+if [ -n "$TS_TYPECHECK" ]; then
+    eval "$TS_TYPECHECK" 2>&1
+    TS_EXIT=$?
+elif [ -n "$TS_BUILD" ]; then
+    eval "$TS_BUILD" 2>&1 | tail -30
+    TS_EXIT=$?
+else
+    echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
+    TS_EXIT=0
+fi
 ```
+Typecheck or build failures are BLOCKING.
 
 ### 3I: Frontend proxy wiring check (MANDATORY)
 
@@ -791,27 +816,44 @@ Advisory only — does not block build. Check for lambda/callable in connect_arg
 
 Skip if no new env vars introduced.
 
+**Config variables used by this phase** (set in `forge.yaml`):
+- `{deploy.secrets_backend}` — secrets delivery method (`sops`, `aws-sm`, `vault`, `ci-env`, `none`). When absent or not `sops`, SOPS-specific checks below are skipped with an explicit log message.
+- `{verification.services[name].container}` — container name for post-deploy verification. Resolved by matching the service name; falls back to `{service}` (bare name) when not configured.
+
 For each new env var, verify present in ALL required locations:
 
 | Location | Required for |
 |----------|-------------|
 | `.env.example` | All new vars |
-| `infra/secrets/prod.enc.yaml` (SOPS) | Production secrets |
-| `infra/decrypt-secrets.sh` ENV_MAPPING | All vars in deploy chain |
-| `app/env_validation.py` | API service vars |
-| `docker-compose.prod.yml` | Vars needing explicit injection |
+| Secrets backend (see `deploy.secrets_backend`) | Secret vars — skip if backend is `none` or unset |
+| `app/env_validation.py` | API service vars (if project has one) |
+| `docker-compose.prod.yml` | Vars needing explicit injection (if project uses Docker Compose) |
 
-Deploy chain: SOPS → `decrypt-secrets.sh` (ENV_MAPPING) → `.env.secrets` → `merge-env-secrets.sh` → `.env.production` → docker-compose `env_file`.
+**Secrets backend check** *(trigger: `deploy.secrets_backend == "sops"`)*:
 
-**Operator-set var classification** *(trigger: new env var is NOT present in `infra/secrets/prod.enc.yaml`)*: <!-- Added: forge#380 -->
+If the project uses SOPS, verify the new var is present in all SOPS chain locations:
+- `infra/secrets/prod.enc.yaml` — SOPS-encrypted secret store
+- `infra/decrypt-secrets.sh` ENV_MAPPING — maps SOPS key to env var name
+- Deploy chain: SOPS → `decrypt-secrets.sh` (ENV_MAPPING) → `.env.secrets` → `merge-env-secrets.sh` → `.env.production` → docker-compose `env_file`
 
-Some env vars are operator-set (non-secret, not sourced from SOPS) — they must be manually added to `.env.production` on the production server. The SOPS deploy chain does not carry them. When a new env var has no entry in `prod.enc.yaml`, classify it as operator-set and add a **HARD BLOCKER** item to the Testing Checklist:
+If `deploy.secrets_backend` is absent or not `sops`, skip these checks and log:
+> `SKIP: SOPS chain check — deploy.secrets_backend is not "sops". Configure deploy.secrets_backend in forge.yaml to enable.`
+
+**Operator-set var classification** *(trigger: new env var is NOT in the configured secrets backend)*: <!-- Added: forge#380 -->
+
+Some env vars are operator-set (non-secret, not sourced from the secrets backend) — they must be manually added to the runtime environment on the production server. When a new env var has no entry in the secrets backend, classify it as operator-set and add a **HARD BLOCKER** item to the Testing Checklist.
+
+Resolve the container name for the verification command:
+1. Look up the service in `forge.yaml → verification.services[]` by name — use the `container` field if present.
+2. If no matching entry, fall back to the bare service name: `{service}` (no suffix).
 
 ```
-- [ ] HARD BLOCKER: Add {VAR_NAME} to .env.production on the production server.
-      This var is operator-set (not in SOPS) — it does NOT flow through the automated
-      deploy chain. It must be added manually before or after deploy.
-      Verify with: docker exec {service}-blue env | grep {VAR_NAME}
+- [ ] HARD BLOCKER: Add {VAR_NAME} to the runtime environment on the production server.
+      This var is operator-set — it does NOT flow through the automated secrets chain.
+      It must be added manually before or after deploy.
+      Verify with: docker exec {CONTAINER_NAME} env | grep {VAR_NAME}
+      (CONTAINER_NAME resolved from verification.services[{service}].container in forge.yaml,
+       or bare service name if not configured)
 ```
 
 **`env_file` re-read warning** *(trigger: any new env var added to `.env.production` path)*:
@@ -822,11 +864,13 @@ Add this warning to the Testing Checklist whenever a new env var is introduced (
 
 **Post-deploy in-container verification** *(trigger: any new env var)*:
 
-Add the following to the Testing Checklist so the deployer can confirm delivery after deploy:
+Add the following to the Testing Checklist so the deployer can confirm delivery after deploy.
+
+Resolve `{CONTAINER_NAME}` from `forge.yaml → verification.services[{service}].container`; use `{service}` (bare) if the field is absent.
 
 ```bash
 # Verify env var reached the running container (run post-deploy)
-docker exec {service}-blue env | grep {VAR_NAME}
+docker exec {CONTAINER_NAME} env | grep {VAR_NAME}
 # Expected: {VAR_NAME}={value}
 # If blank: container was not recreated — run: docker compose up --no-deps --force-recreate {service}
 ```
@@ -1100,4 +1144,4 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 - 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: `gh label create "{name}" --color {hex} -R {GH_REPO}`
+- Label missing: run `npx forgedock labels setup` (from the project directory, or pass `--repo owner/repo`) to idempotently bootstrap all ForgeDock-managed labels with canonical colors and descriptions. Alternatively: `gh label create "{name}" --color {hex} --description "Managed by ForgeDock." --force -R {GH_REPO}`

package/docs/CONFIG.md

@@ -23,6 +23,7 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 | [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
 | [`services`](#services-optional) | No | External service URLs and IDs |
 | [`review`](#review-optional) | No | Context injected into review agents |
+| [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
 
@@ -305,6 +306,39 @@ review:
 
 ---
 
+## `devdocs` (OPTIONAL)
+
+Path configuration for the devdocs knowledge tree. Pipeline agents (work-on, review-pr, etc.) read these files as **authoritative project knowledge** before acting.
+
+Run `npx forgedock docs init` to scaffold the tree from ForgeDock's seed templates into the configured path.
+
+```yaml
+devdocs:
+  path: "devdocs"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | string (relative path) | No | Path to the devdocs tree, relative to project root. Default: `devdocs`. |
+
+**Commands that use this section**: `docs init`, `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
+
+### Migration from `review.context`
+
+If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file after running `npx forgedock docs init`:
+
+| `review.context` content | Target devdocs file |
+|--------------------------|---------------------|
+| Architecture decisions | `devdocs/project/architecture.md` |
+| Tech stack details | `devdocs/project/stack.md` |
+| Coding conventions | `devdocs/project/conventions.md` |
+| Project terminology | `devdocs/project/glossary.md` |
+| ForgeDock usage notes | `devdocs/agent/using-forgedock.md` |
+
+Agents read devdocs files as binding source-of-truth, so they receive richer context than the single `review.context` string.
+
+---
+
 ## `verification` (OPTIONAL)
 
 Service health-check patterns for the quality gate and validate commands.
@@ -382,6 +416,47 @@ billing:
 
 ---
 
+## Label Bootstrap
+
+ForgeDock manages a canonical set of GitHub labels for use across all pipeline commands. Labels cover workflow state, priority, review findings, audit findings, and category classification.
+
+### Bootstrap command
+
+```bash
+# Create/update all ForgeDock-managed labels on the repo defined in forge.yaml:
+npx forgedock labels setup
+
+# Or target a specific repo explicitly:
+npx forgedock labels setup --repo owner/repo
+```
+
+Running this command is idempotent — it creates labels that don't exist and updates the color/description of labels that do. Safe to re-run at any time.
+
+**When to run it**: Once after `npx forgedock install`, or whenever a pipeline command fails with "label not found". The command bootstraps every label the pipeline relies on.
+
+### Canonical label set
+
+The full manifest lives in [`bin/labels.json`](../bin/labels.json) in the ForgeDock package. Each label has a fixed hex color and a description attributing it to ForgeDock.
+
+| Family | Labels |
+|--------|--------|
+| Priority | `priority:P0` `priority:P1` `priority:P2` `priority:P3` |
+| Workflow | `workflow:investigating` `workflow:ready-to-build` `workflow:building` `workflow:in-review` `workflow:merged` `workflow:decomposed` `workflow:invalid` |
+| Pipeline | `needs-human` `review-finding` `needs-validation` `validated` `false-positive` `staging-review` `audit-finding` `orchestration-metrics` `health-report` |
+| Category | `bug` `enhancement` `feature` `refactor` `dead-code` `improvement` `documentation` `qa` `security` `performance` |
+
+### Colors
+
+Colors are grouped by semantic meaning:
+- **Critical/error** (`#B60205`): `priority:P0`, `security`
+- **High/warning-red** (`#D93F0B`): `priority:P1`, `review-finding`, `audit-finding`
+- **Medium/yellow** (`#FBCA04`): `priority:P2`, `needs-validation`
+- **Low/green** (`#C2E0C6`, `#0E8A16`): `priority:P3`, `workflow:merged`, `validated`
+- **Blue pipeline** (`#1D76DB`, `#0075CA`, `#0052CC`): active workflow states
+- **Neutral** (`#CCCCCC`, `#E4E669`): terminal/dismissal states
+
+---
+
 ## Config Reading Conventions
 
 ForgeDock commands use two accepted patterns for reading `forge.yaml`:
@@ -393,6 +468,48 @@ Do **not** mix the two patterns for the same block of variables (e.g., `yq` with
 
 ---
 
+## CLAUDE.md Integration
+
+ForgeDock can inject a managed usage block into your project's `CLAUDE.md` so every Claude Code session opened in the repo automatically knows that ForgeDock drives development here and which commands to use.
+
+### How It Works
+
+Running `npx forgedock init` or `npx forgedock integrate` writes a marker-bounded block into `CLAUDE.md`:
+
+```
+<!-- BEGIN FORGEDOCK -->
+## ForgeDock — Autonomous Development Pipeline
+...command index and conventions...
+<!-- END FORGEDOCK -->
+```
+
+The block is **idempotent** — re-running replaces only the managed section and leaves all other `CLAUDE.md` content untouched. If `CLAUDE.md` does not exist, it is created.
+
+If `AGENTS.md` already exists in the project root, the same block is mirrored into it.
+
+### Commands
+
+| Command | Action |
+|---------|--------|
+| `npx forgedock init` | Generates `forge.yaml` **and** injects the CLAUDE.md block |
+| `npx forgedock integrate` | Injects/refreshes the block without modifying `forge.yaml` |
+
+### Opting Out
+
+To prevent ForgeDock from managing the block, remove the `<!-- BEGIN FORGEDOCK -->` / `<!-- END FORGEDOCK -->` markers from `CLAUDE.md`. Without the markers, subsequent runs will append a new block rather than replacing one — so if you want to opt out permanently, delete or omit the markers **and** do not run `integrate` again.
+
+Alternatively, keep the markers but edit the content between them freely — ForgeDock will replace that section on the next run, so any manual edits inside the markers will be overwritten.
+
+### Re-generating
+
+The command index inside the block is auto-generated from the `description:` frontmatter in each `commands/*.md` file. To refresh it after a ForgeDock update:
+
+```bash
+npx forgedock integrate
+```
+
+---
+
 ## Complete Example
 
 See [`forge.yaml.example`](../forge.yaml.example) at the repository root for a fully annotated example covering all sections.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -36,6 +36,7 @@
     "commands/",
     "docs/",
     "scripts/",
+    "templates/",
     "LICENSE",
     "README.md"
   ],

package/scripts/verify-route-registration.sh

@@ -5,6 +5,18 @@
 #   changed_files_file: path to a file listing changed files (one per line)
 #   repo_root: path to the repository root
 #
+# Layout path overrides (env vars — override defaults for non-AlterLab layouts):
+#   FORGE_PAGES_ROOT          Root of Next.js App Router pages dir (default: web/src/app)
+#   FORGE_API_ROUTERS_DIR     Dir containing FastAPI router .py files (default: services/api/app/routers)
+#   FORGE_API_MAIN            Path to API app entrypoint, relative to repo root (default: services/api/app/main.py)
+#   FORGE_API_MIDDLEWARE_DIR  Dir containing API middleware .py files (default: services/api/app/middleware)
+#   FORGE_API_SERVICES_DIR    Root of the backend API service dir (default: services/api)
+#   FORGE_WORKER_DIR          Root of the background worker service dir (default: services/worker)
+#   FORGE_COMPONENTS_DIR      Root of shared frontend component library (default: web/src/components)
+#
+# Set these from forge.yaml review.layout fields before invoking, e.g.:
+#   export FORGE_PAGES_ROOT=$(yq '.review.layout.pages // "web/src/app"' forge.yaml)
+#
 # Output: Structured findings (one per line, prefixed with severity)
 #   BLOCKING: <message>  — must fix before merge
 #   WARNING:  <message>  — likely issue, verify manually
@@ -23,12 +35,21 @@ else
     FILES=$(cat "$CHANGED_FILES")
 fi
 
+# Layout path configuration — read from env vars, fall back to AlterLab defaults
+FORGE_PAGES_ROOT="${FORGE_PAGES_ROOT:-web/src/app}"
+FORGE_API_ROUTERS_DIR="${FORGE_API_ROUTERS_DIR:-services/api/app/routers}"
+FORGE_API_MAIN="${FORGE_API_MAIN:-services/api/app/main.py}"
+FORGE_API_MIDDLEWARE_DIR="${FORGE_API_MIDDLEWARE_DIR:-services/api/app/middleware}"
+FORGE_API_SERVICES_DIR="${FORGE_API_SERVICES_DIR:-services/api}"
+FORGE_WORKER_DIR="${FORGE_WORKER_DIR:-services/worker}"
+FORGE_COMPONENTS_DIR="${FORGE_COMPONENTS_DIR:-web/src/components}"
+
 BLOCKING=0
 WARNINGS=0
 
 # --- Next.js Route Handler registration check ---
 while read -r f; do
-    URL_PATH=$(echo "$f" | sed 's|^web/src/app||; s|/route\.ts$||; s|\[.*\]|*|g')
+    URL_PATH=$(echo "$f" | sed "s|^${FORGE_PAGES_ROOT}||; s|/route\\.ts\$||; s|\\[.*\\]|*|g")
     ROUTE_SEGMENT=$(echo "$URL_PATH" | sed 's|/api/v1/||; s|/.*||')
 
     # Check if next.config.js has a rewrite that might shadow this route
@@ -48,50 +69,50 @@ while read -r f; do
             WARNINGS=$((WARNINGS + 1))
         fi
     fi
-done < <(echo "$FILES" | grep -E "^web/src/app/api/.*route\.ts$") || true
+done < <(echo "$FILES" | grep -E "^${FORGE_PAGES_ROOT}/api/.*route\\.ts$") || true
 
 # --- Python API Router registration check ---
 while read -r f; do
     ROUTER_NAME=$(basename "$f" .py)
-    MAIN_PY="$REPO_ROOT/services/api/app/main.py"
+    MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
         if grep -q "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
-            echo "OK: API Router '$ROUTER_NAME' ($f) — registered in main.py"
+            echo "OK: API Router '$ROUTER_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
-            echo "BLOCKING: API Router '$ROUTER_NAME' ($f) — NOT found in main.py. Router will not be reachable."
+            echo "BLOCKING: API Router '$ROUTER_NAME' ($f) — NOT found in $(basename "$MAIN_PY"). Router will not be reachable."
             BLOCKING=$((BLOCKING + 1))
         fi
     else
-        echo "WARNING: Cannot verify router registration — main.py not found at $MAIN_PY"
+        echo "WARNING: Cannot verify router registration — API main not found at $MAIN_PY"
         WARNINGS=$((WARNINGS + 1))
     fi
-done < <(echo "$FILES" | grep -E "^services/api/app/routers/.*\.py$") || true
+done < <(echo "$FILES" | grep -E "^${FORGE_API_ROUTERS_DIR}/.*\\.py$") || true
 
 # --- Python Middleware registration check ---
 while read -r f; do
     MIDDLEWARE_NAME=$(basename "$f" .py)
-    MAIN_PY="$REPO_ROOT/services/api/app/main.py"
+    MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
         if grep -q "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
-            echo "OK: Middleware '$MIDDLEWARE_NAME' ($f) — registered in main.py"
+            echo "OK: Middleware '$MIDDLEWARE_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
-            echo "WARNING: Middleware '$MIDDLEWARE_NAME' ($f) — not found in main.py. May not be active."
+            echo "WARNING: Middleware '$MIDDLEWARE_NAME' ($f) — not found in $(basename "$MAIN_PY"). May not be active."
             WARNINGS=$((WARNINGS + 1))
         fi
     fi
-done < <(echo "$FILES" | grep -E "^services/api/app/middleware/.*\.py$") || true
+done < <(echo "$FILES" | grep -E "^${FORGE_API_MIDDLEWARE_DIR}/.*\\.py$") || true
 
 # --- Shared module import check ---
 while read -r f; do
     MODULE_NAME=$(basename "$f" .py)
 
-    IMPORTERS=$(grep -rl "$MODULE_NAME" "$REPO_ROOT/services/api/" "$REPO_ROOT/services/worker/" 2>/dev/null | head -5)
+    IMPORTERS=$(grep -rl "$MODULE_NAME" "$REPO_ROOT/${FORGE_API_SERVICES_DIR}/" "$REPO_ROOT/${FORGE_WORKER_DIR}/" 2>/dev/null | head -5)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Shared module '$MODULE_NAME' ($f) — imported by services"
     else
-        echo "WARNING: Shared module '$MODULE_NAME' ($f) — no imports found in services/api/ or services/worker/"
+        echo "WARNING: Shared module '$MODULE_NAME' ($f) — no imports found in ${FORGE_API_SERVICES_DIR}/ or ${FORGE_WORKER_DIR}/"
         WARNINGS=$((WARNINGS + 1))
     fi
 done < <(echo "$FILES" | grep -E "^shared/.*\.py$") || true
@@ -100,14 +121,14 @@ done < <(echo "$FILES" | grep -E "^shared/.*\.py$") || true
 while read -r f; do
     COMPONENT_NAME=$(basename "$f" .tsx)
 
-    IMPORTERS=$(grep -rl "$COMPONENT_NAME" "$REPO_ROOT/web/src/app/" "$REPO_ROOT/web/src/components/" 2>/dev/null | grep -v "$f" | head -3)
+    IMPORTERS=$(grep -rl "$COMPONENT_NAME" "$REPO_ROOT/${FORGE_PAGES_ROOT}/" "$REPO_ROOT/${FORGE_COMPONENTS_DIR}/" 2>/dev/null | grep -v "$f" | head -3)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Component '$COMPONENT_NAME' ($f) — imported by other files"
     else
         echo "WARNING: Component '$COMPONENT_NAME' ($f) — no imports found. May be unused or new."
         WARNINGS=$((WARNINGS + 1))
     fi
-done < <(echo "$FILES" | grep -E "^web/src/components/.*\.tsx$") || true
+done < <(echo "$FILES" | grep -E "^${FORGE_COMPONENTS_DIR}/.*\\.tsx$") || true
 
 # --- Exit code ---
 if [ "$BLOCKING" -gt 0 ]; then

package/scripts/verify-sops-chain.sh

@@ -24,6 +24,24 @@ DIFF_INPUT="${1:--}"
 CHANGED_FILES_INPUT="${2:--}"
 REPO_ROOT="${3:-.}"
 
+# --- Secrets backend guard ---
+# This script only applies when the project uses SOPS as its secrets backend.
+# Read the configured backend from the FORGE_SECRETS_BACKEND env var (set by the
+# calling pipeline) or fall back to parsing forge.yaml in the repo root.
+#
+# If the backend is not "sops" (or is unset), exit 0 with a skip message.
+# This is a clean no-op — not a false-pass — so callers can distinguish
+# "SOPS configured and passed" from "SOPS not in use on this project".
+_SECRETS_BACKEND="${FORGE_SECRETS_BACKEND:-}"
+if [ -z "$_SECRETS_BACKEND" ] && [ -f "$REPO_ROOT/forge.yaml" ]; then
+    _SECRETS_BACKEND=$(grep -E '^\s*secrets_backend:' "$REPO_ROOT/forge.yaml" \
+        | head -1 | sed 's/.*secrets_backend:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
+fi
+if [ "$_SECRETS_BACKEND" != "sops" ]; then
+    echo "SKIP: verify-sops-chain — secrets_backend is '${_SECRETS_BACKEND:-none}' (not sops). Configure deploy.secrets_backend: sops in forge.yaml to enable SOPS chain verification."
+    exit 0
+fi
+
 if [ "$DIFF_INPUT" = "-" ]; then
     DIFF_CONTENT=$(cat)
 else

package/templates/devdocs/README.md

@@ -0,0 +1,96 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, issue, orchestrate, quality-gate]
+---
+
+# DevDocs — Authoritative Knowledge Base
+
+This directory contains the authoritative knowledge base for your project. Pipeline agents (ForgeDock commands) read these files as **binding source-of-truth** before acting — not as suggestions.
+
+---
+
+## Purpose
+
+DevDocs bridge the gap between what agents know by default and what your project requires. They answer:
+
+- How do we use ForgeDock in this project? (`agent/using-forgedock.md`)
+- How do we use GitHub in this project? (`agent/using-github.md`)
+- What templates do we use? (`templates/`)
+- What is this project's tech stack, architecture, and conventions? (`project/`)
+
+---
+
+## Directory Structure
+
+```
+devdocs/
+  README.md                     ← you are here
+  agent/
+    using-forgedock.md          ← ForgeDock pipeline how-to (all phases, lanes, commands)
+    using-github.md             ← GitHub CLI, branch naming, labels, commit discipline
+  templates/
+    issue.md                    ← reusable issue body template
+    pull-request.md             ← reusable PR body template
+    commit-convention.md        ← conventional commit reference
+    review-finding.md           ← review-finding issue template
+  project/
+    custom-instructions.md      ← user binding directives (HIGHEST precedence)
+    stack.md                    ← tech stack description
+    architecture.md             ← system and domain overview
+    conventions.md              ← coding standards and patterns
+    glossary.md                 ← domain terms and definitions
+```
+
+---
+
+## Precedence Rules
+
+When a conflict arises between different knowledge sources, agents follow this priority order:
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 (highest) | `project/custom-instructions.md` | Explicit user-authored directives. Always wins. |
+| 2 | Other `project/*.md` files | Authoritative project context (stack, architecture, conventions) |
+| 3 | `agent/*.md` files | Authoritative ForgeDock/GitHub usage instructions |
+| 4 | `templates/*.md` files | Standard templates (lower authority than instructions) |
+| 5 | Agent memory | Recalled knowledge from past sessions |
+| 6 (lowest) | Agent defaults | Built-in behaviors when no other source applies |
+
+**Rule**: When `custom-instructions.md` says X, agents do X — even if their training or memory says otherwise.
+
+---
+
+## Authority Levels
+
+Each file declares an `authority` field in its frontmatter:
+
+| Authority | Meaning |
+|-----------|---------|
+| `required` | Agent MUST read this file before acting in its domain |
+| `recommended` | Agent SHOULD read this file; improves output quality |
+| `reference` | Agent MAY consult this file; informational only |
+
+---
+
+## How Agents Use DevDocs
+
+1. **Before investigating**: Read `agent/using-forgedock.md` and `project/custom-instructions.md`
+2. **Before building**: Read `agent/using-github.md`, relevant `project/*.md`, applicable `templates/*.md`
+3. **Before reviewing**: Read `project/conventions.md`, `project/stack.md`
+4. **Always**: Treat `project/custom-instructions.md` as the final authority
+
+---
+
+## Regeneration
+
+If this directory was scaffolded by `npx forgedock docs init`, re-running that command will add any new template files introduced in newer ForgeDock versions. It will **not** overwrite files you have edited (idempotent).
+
+---
+
+## Maintenance Notes
+
+- Edit `project/*.md` files to reflect your project's actual stack, architecture, and conventions
+- Edit `project/custom-instructions.md` to add binding directives for your project
+- Do NOT edit `agent/*.md` unless you want to override ForgeDock's default behavior for this project
+- `templates/*.md` files can be customized; changes affect what pipeline agents use as templates