forgedock 1.0.7 → 1.0.9

package/commands/orchestrate.md

@@ -824,9 +824,9 @@ All tool commands are read from `forge.yaml → verification.commands`; each ste
 
 ```bash
 # Read toolchain commands from forge.yaml
-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/['\"].*//")
-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/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 
 # Check if this is a milestone batch with TypeScript changes
 MILESTONE_BRANCH="milestone/{milestone_slug}"

package/commands/review-pr-staging.md

@@ -14,6 +14,22 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 ---
 
+## Config Resolution
+
+Read `forge.yaml` to resolve branch names before running any commands:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+```
+
+All `$DEFAULT_BRANCH` and `$STAGING_BRANCH` references below are populated from `forge.yaml`.
+
+---
+
 ## Evidence-Based Review Protocol (ALL Agents)
 
 ### Diff-First Approach
@@ -70,22 +86,6 @@ Include ALL findings (CONFIRMED, LIKELY, POSSIBLE). One line per finding, sequen
 
 ---
 
-## Config Resolution
-
-Read `forge.yaml` to resolve branch names before running any commands:
-
-```bash
-CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
-GH_FLAG="-R $GH_REPO"
-DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
-STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
-```
-
-All `$DEFAULT_BRANCH` and `$STAGING_BRANCH` references below are populated from `forge.yaml`.
-
----
-
 ## Phase 0A: Open Review-Finding Gate (BLOCKING — runs before scope analysis)
 
 **Purpose**: Prevent deploying commits that have known, unfixed review findings. The review system catches bugs before merging; this gate ensures the merge path acts on that information.
@@ -213,8 +213,8 @@ Create review chunks by priority: Billing/Pricing (CRITICAL) → Security/Auth (
 Read `forge.yaml → verification.commands.python` for project-specific tool commands:
 
 ```bash
-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/['\"].*//")
-PYTHON_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1 | head -30
@@ -234,8 +234,8 @@ fi
 Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
 
 ```bash
-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/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1
@@ -261,7 +261,7 @@ Build failure is BLOCKING — deploy WILL fail. Typecheck alone misses SSG/prere
 Read `forge.yaml → verification.commands.python.test`:
 
 ```bash
-PYTHON_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$PYTHON_TEST" ]; then
     eval "$PYTHON_TEST" 2>&1 | tail -50

package/commands/review-pr.md

@@ -161,9 +161,9 @@ Read `forge.yaml → verification.commands.python` for project-specific tool com
 
 ```bash
 # Read toolchain commands from forge.yaml
-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/['\"].*//")
-PYTHON_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;s/['\"].*//")
-PYTHON_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_LINT=$(yq '.verification.commands.python.lint // ""' forge.yaml 2>/dev/null || echo '')
+PYTHON_TYPECHECK=$(yq '.verification.commands.python.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 
 # Run format check
 if [ -n "$PYTHON_FORMAT" ]; then
@@ -187,7 +187,7 @@ else
 fi
 
 # Always run compile check on changed Python files (fast, language-universal)
-for f in $(gh pr diff $ARGUMENTS --name-only | grep '\.py$'); do
+gh pr diff $ARGUMENTS --name-only | grep '\.py$' | while IFS= read -r f; do
     python3 -m py_compile "$f" 2>&1
 done
 ```
@@ -197,9 +197,9 @@ done
 Read `forge.yaml → verification.commands.typescript` for project-specific tool commands:
 
 ```bash
-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_LINT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'lint:' | head -1 | sed "s/.*lint: *['\"]//;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_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_LINT=$(yq '.verification.commands.typescript.lint // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 
 # Run format check
 if [ -n "$TS_FORMAT" ]; then
@@ -243,7 +243,7 @@ gh pr diff $ARGUMENTS | grep -oE "['\"][A-Za-z0-9+/=]{40,}['\"]" | head -10
 
 ### 2F: SQL Migration Validation (if *.sql changed)
 ```bash
-for sql_file in $(gh pr diff $ARGUMENTS --name-only | grep "\.sql$"); do
+gh pr diff $ARGUMENTS --name-only | grep "\.sql$" | while IFS= read -r sql_file; do
     grep -E "FOR UPDATE" "$sql_file" | grep -qE "(SUM|COUNT|AVG|MIN|MAX)\s*\(" && echo "ERROR: FOR UPDATE with aggregate"
     grep -qE "DROP (TABLE|COLUMN|INDEX)" "$sql_file" && ! grep -qE "IF EXISTS" "$sql_file" && echo "WARNING: DROP without IF EXISTS"
     grep -qE "ALTER TABLE.*ADD COLUMN.*NOT NULL" "$sql_file" && ! grep -qE "DEFAULT" "$sql_file" && echo "WARNING: NOT NULL without DEFAULT"
@@ -263,7 +263,7 @@ Read `forge.yaml → verification.commands.{lang}.test` for the project's test c
 ```bash
 # Check each configured language for a test command
 for lang in python typescript go rust; do
-    TEST_CMD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk "/^    ${lang}:/{f=1;next} f && /^    [^ \t]/{exit} f" | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+    TEST_CMD=$(yq ".verification.commands.${lang}.test // \"\"" forge.yaml 2>/dev/null || echo '')
     if [ -n "$TEST_CMD" ]; then
         echo "=== Running tests (${lang}): ${TEST_CMD} ==="
         eval "$TEST_CMD" 2>&1 | tail -30
@@ -273,8 +273,8 @@ for lang in python typescript go rust; do
 done
 
 # If no test commands were configured, log explicitly
-PYTHON_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
-TS_TEST=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'test:' | head -1 | sed "s/.*test: *['\"]//;s/['\"].*//")
+PYTHON_TEST=$(yq '.verification.commands.python.test // ""' forge.yaml 2>/dev/null || echo '')
+TS_TEST=$(yq '.verification.commands.typescript.test // ""' forge.yaml 2>/dev/null || echo '')
 if [ -z "$PYTHON_TEST" ] && [ -z "$TS_TEST" ]; then
     echo "SKIPPED — no test commands configured in verification.commands"
 fi
@@ -303,8 +303,8 @@ Read `forge.yaml → verification.commands.typescript.typecheck` and `.build`:
 ```bash
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
 
-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/['\"].*//")
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1
@@ -337,10 +337,10 @@ Read `forge.yaml → verification.commands.python.format` and `.build`:
 gh pr checkout $ARGUMENTS --detach 2>/dev/null
 
 # Compile-check all changed Python files (language-universal — no config needed)
-for f in $(echo "$CHANGED_FILES" | grep '\.py$'); do python3 -m py_compile "$f" 2>&1; done
+echo "$CHANGED_FILES" | grep '\.py$' | while IFS= read -r f; do python3 -m py_compile "$f" 2>&1; done
 
 if [ "$REQUIRES_FULL_BUILD" = "true" ]; then
-    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/['\"].*//")
+    PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
     if [ -n "$PYTHON_FORMAT" ]; then
         eval "$PYTHON_FORMAT" 2>&1
     else
@@ -495,7 +495,7 @@ fi
 # Python scoping hazard check — local imports that shadow module-level names
 # A local `import X` makes X a local variable for the ENTIRE function scope.
 # Any reference to X ABOVE the local import will crash with UnboundLocalError.
-for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
+echo "$CHANGED_FILES" | grep -E '\.py$' | while IFS= read -r f; do
     echo "=== Python Scoping Check: $f ==="
     # Find function-scoped imports (indented import statements)
     grep -nE "^\s+import [a-z]" "$f" 2>/dev/null | while read line; do
@@ -509,7 +509,7 @@ for f in $(echo "$CHANGED_FILES" | grep -E '\.py$'); do
 done
 
 # Config file assumption check (baked into Docker image vs volume-mounted)
-for f in $(echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$"); do
+echo "$CHANGED_FILES" | grep -E "config/.*\.(json|yaml|yml)$" | while IFS= read -r f; do
     echo "=== Config File: $f ==="
     grep -n "$(dirname $f)" docker-compose.yml 2>/dev/null || echo "WARNING: Config dir may not be mounted — changes may require --build"
     grep -n "$(dirname $f)" services/*/Dockerfile 2>/dev/null || true

package/commands/rollback.md

@@ -122,7 +122,7 @@ for f in {reverted_python_files}; do
 done
 
 # Python format check (config-driven)
-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/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1 | head -20
 else
@@ -130,7 +130,7 @@ else
 fi
 
 # TypeScript typecheck (config-driven)
-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_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$TS_TYPECHECK" ]; then
     eval "$TS_TYPECHECK" 2>&1 | head -20
 else

package/commands/work-on/build/validate.md

@@ -94,7 +94,7 @@ Run after quality gate passes. All tool commands are read from `forge.yaml → v
 ```bash
 cd {WORKTREE_PATH}
 
-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/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
@@ -110,9 +110,9 @@ Failures in `py_compile` are BLOCKING — fix before continuing.
 ```bash
 cd {WORKTREE_PATH}
 
-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/['\"].*//")
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1

package/commands/work-on-monolithic.md

@@ -214,7 +214,24 @@ Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
 All client-side fetch/useSWR/apiFetch must use `/api/...` proxy routes, NEVER `/api/v1/...` directly.
 
 ### 3I: Deployment completeness check (MANDATORY)
-New env vars must be in: `.env.example` + SOPS `prod.enc.yaml` + `decrypt-secrets.sh` ENV_MAPPING + `env_validation.py` (if API).
+Skip if no new env vars introduced.
+
+For each new env var, verify present in ALL required locations:
+
+| Location | Required for |
+|----------|-------------|
+| `.env.example` | All new vars |
+| 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) |
+
+**Secrets backend check** *(trigger: `deploy.secrets_backend == "sops"`)*:
+
+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
+
+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.`
 
 ### 3J: Commit
 Conventional prefix (fix/feat/refactor/docs). Reference #{NUMBER} in the commit message.

package/commands/work-on.md

@@ -753,7 +753,7 @@ All tool commands are read from `forge.yaml → verification.commands`. When a k
 ```bash
 cd {WORKTREE_PATH}
 
-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/['\"].*//")
+PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
@@ -769,9 +769,9 @@ python -m py_compile {PYTHON_FILES}
 ```bash
 cd {WORKTREE_PATH}
 
-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/['\"].*//")
+TS_FORMAT=$(yq '.verification.commands.typescript.format // ""' forge.yaml 2>/dev/null || echo '')
+TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml 2>/dev/null || echo '')
+TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1

package/docs/CONFIG.md

@@ -12,6 +12,21 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 
 ---
 
+## CLI Flags for `init`
+
+`npx forgedock init` accepts two optional flags that change how configuration is generated:
+
+| Flag | Behavior |
+|------|----------|
+| `--manual` | Skips AI autopilot enrichment entirely. Presents the annotated review screen with detection baseline values only (no AI-enriched suggestions). Detection still runs to provide defaults — you review and edit the raw inferred values on the same single-screen interface. |
+| `--verbose` | Surfaces each field's detection source and confidence rationale during the init flow. Helpful for understanding where ForgeDock inferred values from (e.g. `git remote`, `package.json`, `gh api`). |
+
+The two flags can be combined: `npx forgedock init --manual --verbose` shows the annotated review screen with detection baseline values and field provenance at each entry.
+
+The default (`npx forgedock init` with no flags) remains the zero-question autopilot: AI enrichment fills in everything it can, and you review the result on a single annotated screen.
+
+---
+
 ## Schema Overview
 
 | Section | Required | Purpose |
@@ -468,6 +483,96 @@ Do **not** mix the two patterns for the same block of variables (e.g., `yq` with
 
 ---
 
+## ConfigDraft Contract
+
+`ConfigDraft` is the shared data structure emitted by `bin/init-detect.mjs` and consumed by the AI enrichment backends (`init-enrich`) and the annotated review renderer (`review-render`). It mirrors the required sections of `forge.yaml` at a per-field granularity, adding provenance and confidence metadata.
+
+### Field shape
+
+Every leaf value in a `ConfigDraft` is a **ConfigField** object:
+
+```ts
+{
+  value:      string,            // The detected or inferred value
+  confidence: "high" | "medium" | "low",  // How certain the detection was
+  source:     string,            // Human-readable label for where the value came from
+  why:        string,            // Plain-language explanation of why this value was chosen
+}
+```
+
+**Confidence levels:**
+
+| Level | Meaning |
+|-------|---------|
+| `"high"` | Verified from a concrete, unambiguous source (e.g., parsed from the git remote URL) |
+| `"medium"` | Inferred from available signals; likely correct but not guaranteed (e.g., current branch name, name derived from repo slug) |
+| `"low"` | Guessed default — no supporting evidence was found (e.g., no git remote, not a git repo) |
+
+### ConfigDraft shape
+
+```js
+{
+  project: {
+    owner: ConfigField,   // GitHub org or username
+    repo:  ConfigField,   // Repository name (without owner prefix)
+    name:  ConfigField,   // Human-readable project name
+  },
+  paths: {
+    root:         ConfigField,  // Absolute path to the project root
+    worktreeBase: ConfigField,  // Absolute path to the git worktree base dir
+  },
+  branches: {
+    default: ConfigField,  // Default branch (e.g. "main")
+    staging: ConfigField,  // Staging branch for fast-lane PRs
+  },
+  meta: {
+    remoteDetected: boolean,  // true iff a parseable git remote URL was found
+  },
+}
+```
+
+### Example output (high-confidence repo)
+
+```js
+{
+  project: {
+    owner: { value: "acme-org",    confidence: "high",   source: "git remote origin (SSH)",   why: "Parsed from SSH remote URL: git@github.com:acme-org/acme-platform.git" },
+    repo:  { value: "acme-platform", confidence: "high",   source: "git remote origin (SSH)",   why: "Parsed from SSH remote URL: git@github.com:acme-org/acme-platform.git" },
+    name:  { value: "Acme Platform", confidence: "medium", source: "derived from repo slug",     why: "Title-cased version of repo name 'acme-platform' (split on hyphens/underscores)" },
+  },
+  paths: {
+    root:         { value: "/home/user/acme",                      confidence: "high", source: "process.cwd()", why: "Absolute path passed to detectConfig — the project root" },
+    worktreeBase: { value: "/home/user/acme/.claude/worktrees",    confidence: "high", source: "derived from root", why: "Convention: {root}/.claude/worktrees" },
+  },
+  branches: {
+    default: { value: "main",    confidence: "high",   source: "git symbolic-ref refs/remotes/origin/HEAD", why: "Remote HEAD points to main" },
+    staging: { value: "staging", confidence: "high",   source: "git branch -r",                             why: "Found 'origin/staging' in the remote branch listing" },
+  },
+  meta: { remoteDetected: true },
+}
+```
+
+### Producing a ConfigDraft
+
+```js
+import { detectConfig } from "./bin/init-detect.mjs";
+
+const draft = await detectConfig(process.cwd());
+// draft.project.owner.value  → "acme-org"
+// draft.project.owner.confidence  → "high"
+```
+
+`detectConfig(cwd)` is the sole public API. It never throws — every error path produces a `low`-confidence default.
+
+### Consuming a ConfigDraft
+
+Downstream consumers read `field.value` for the raw value and `field.confidence` to decide how to handle it:
+
+- **`init-enrich`** (AI enrichment): passes `low`- and `medium`-confidence fields to the AI backend to raise their confidence; leaves `high`-confidence fields untouched.
+- **`review-render`** (TUI review screen): shows each field with its source and why; highlights `low`-confidence fields with a `# TODO(forgedock:<field>)` annotation in the generated YAML.
+
+---
+
 ## 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.
@@ -510,6 +615,68 @@ npx forgedock integrate
 
 ---
 
+## Per-Directory State Registry
+
+ForgeDock tracks per-directory opt-out state in a central registry file on the local machine.
+
+### Registry File Location
+
+```
+~/.claude/forgedock/registry.json
+```
+
+The directory (`~/.claude/forgedock/`) is created automatically on first use with mode `0700`. The file is never committed to version control — it is per-user, per-machine state.
+
+### Registry Schema
+
+```json
+{
+  "version": 1,
+  "optedOut": {
+    "/absolute/path/to/project": { "at": "2026-06-09T12:00:00.000Z" }
+  },
+  "nudgeSeen": {
+    "/absolute/path/to/project": { "at": "2026-06-09T12:00:00.000Z" }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | number | Schema version — currently `1` |
+| `optedOut` | object | Map of absolute directory paths to opt-out metadata |
+| `optedOut[path].at` | string | ISO-8601 timestamp of when the opt-out was recorded |
+| `nudgeSeen` | object | Map of absolute directory paths where the one-time "Enable ForgeDock here?" nudge has already been shown |
+| `nudgeSeen[path].at` | string | ISO-8601 timestamp of when the nudge was shown for this directory |
+
+### State Resolution
+
+The `registry` module resolves one of three states for any directory:
+
+| State | Meaning |
+|-------|---------|
+| `managed-active` | Directory contains `forge.yaml` or `.forgedock` and is **not** opted out — ForgeDock is active here |
+| `managed-optedout` | Directory has a managed marker but the user has explicitly opted out — ForgeDock stays silent |
+| `unmanaged` | No `forge.yaml` or `.forgedock` marker found — ForgeDock has no presence here |
+
+**Opt-out wins over managed**: if a directory contains `forge.yaml` but its path is listed in `optedOut`, the state is `managed-optedout`.
+
+### Failure Behaviour
+
+A missing or corrupt `registry.json` is treated as an empty opt-out set. The registry always fails open — it never throws and never blocks a Claude Code session.
+
+### Managing Opt-Out State
+
+Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set:
+
+```bash
+npx forgedock enable [dir]   # Remove directory from opt-out set (default: cwd)
+npx forgedock disable [dir]  # Add directory to opt-out set (default: cwd)
+npx forgedock status [dir]   # Show resolved state for a directory
+```
+
+---
+
 ## Complete Example
 
 See [`forge.yaml.example`](../forge.yaml.example) at the repository root for a fully annotated example covering all sections.