forgedock 1.0.5 → 1.0.7

package/commands/security-audit.md

@@ -7,7 +7,7 @@ argument-hint: [--repo <prefix>] [--phase 1|2|3|4|all] [--dry-run]
 
 **Input**: $ARGUMENTS
 
-You are the security posture auditor. Run a scripted 4-phase checklist against the **current state** of the target repository (not a PR diff). Each check uses bash/grep against repo files. Confirmed findings are posted as GitHub issues in the target repo, labeled `security,audit-finding,P1/P2/P3`.
+You are the security posture auditor. Run a scripted 4-phase checklist against the **current state** of the target repository (not a PR diff). Each check uses bash/grep against repo files. Confirmed findings are posted as GitHub issues in the target repo, labeled `security,audit-finding,priority:P1/priority:P2/priority:P3`.
 
 This command is designed to be run:
 - **Manually** after a pen test engagement
@@ -119,7 +119,7 @@ done
 
 **Confirm**: For each hit, verify the port is NOT a web-facing port (80, 443, 8080, 3000). Ports like 6432 (PgBouncer), 6379 (Redis), 5432 (Postgres), 27017 (MongoDB) bound to `0.0.0.0` are confirmed findings.
 
-**Severity**: P1 if no external firewall documented; P2 otherwise.
+**Severity**: `priority:P1` if no external firewall documented; `priority:P2` otherwise.
 
 **Issue title**: `security: {SERVICE} port {PORT} bound to 0.0.0.0 — exposed beyond localhost`
 
@@ -142,7 +142,7 @@ done
 
 **Confirm**: Check if the Dockerfile is for a long-running service (not a one-shot build image). If service container with no USER → confirmed finding.
 
-**Severity**: P2 (standard finding; exploitability depends on runtime isolation).
+**Severity**: `priority:P2` (standard finding; exploitability depends on runtime isolation).
 
 **Issue title**: `security: {SERVICE} Dockerfile has no USER directive — runs as root`
 
@@ -167,7 +167,7 @@ done
 
 **Manual review**: Check for `POSTGRES_PASSWORD` and `requirepass` in compose environment sections. Flag any service using a blank/trivial password as a documented value.
 
-**Severity**: P3 for dev compose; P1 if the compose file is used in production.
+**Severity**: `priority:P3` for dev compose; `priority:P1` if the compose file is used in production.
 
 **Issue title**: `security: {SERVICE} in {FILE} has no authentication configured`
 
@@ -198,7 +198,7 @@ done
 
 **Confirm**: Verify the flagged step is indeed a security scanner step (not a notification or deploy step). Confirmed if scanner produces failure exit codes that are being swallowed.
 
-**Severity**: P2 (scanner present but findings are silently ignored).
+**Severity**: `priority:P2` (scanner present but findings are silently ignored).
 
 **Issue title**: `security: {SCANNER} step in {WORKFLOW} has continue-on-error: true — findings silently ignored`
 
@@ -219,7 +219,7 @@ done
 
 **Confirm**: Distinguish intentional comments (documentation) from disabled access control rules. Confirmed if the commented line is a functional directive that would restrict access.
 
-**Severity**: P1 if the endpoint is publicly accessible; P2 otherwise.
+**Severity**: `priority:P1` if the endpoint is publicly accessible; `priority:P2` otherwise.
 
 **Issue title**: `security: commented-out access control in {FILE} — {DIRECTIVE} disabled`
 
@@ -242,7 +242,7 @@ done
 
 **Confirm**: Verify the CSP header applies to the production site (not just dev/storybook). Check if a nonce-based approach is already in use (nonce + unsafe-inline is still a finding but lower severity).
 
-**Severity**: P2 (XSS protection materially weakened).
+**Severity**: `priority:P2` (XSS protection materially weakened).
 
 **Issue title**: `security: CSP script-src includes unsafe-inline in {FILE} — XSS protection bypassed`
 
@@ -261,9 +261,9 @@ for f in $HEADER_FILES; do
 done
 ```
 
-**Confirm**: Check if the header is set in a response (not just read). If set in outbound responses → confirmed finding. Internal-only APIs (not publicly routed) are P3; public APIs are P2.
+**Confirm**: Check if the header is set in a response (not just read). If set in outbound responses → confirmed finding. Internal-only APIs (not publicly routed) are `priority:P3`; public APIs are `priority:P2`.
 
-**Severity**: P2 for public APIs; P3 for internal.
+**Severity**: `priority:P2` for public APIs; `priority:P3` for internal.
 
 **Issue title**: `security: {HEADER} response header leaks deployment/version information`
 
@@ -291,7 +291,7 @@ grep -rn '@router.get\("/health"\|@app.route("/health"\|@router.get\("/metrics"\
 
 **Confirm**: Manually verify the route has no authentication dependency. Check if it's behind a network-level gate (traefik middleware, nginx ACL). Confirmed if publicly routable and returns system state.
 
-**Severity**: P2 (information disclosure enables targeted attacks).
+**Severity**: `priority:P2` (information disclosure enables targeted attacks).
 
 **Issue title**: `security: unauthenticated {ROUTE} endpoint exposes system state`
 
@@ -326,7 +326,7 @@ grep -rn "new Map\(\)" "$REPO_PATH/web" --include="*.ts" --include="*.tsx" --inc
 
 **Confirm**: Verify the rate limiter is not backed by Redis, a database, or a distributed cache. Confirmed if per-process store with no TTL-based external backend.
 
-**Severity**: P2 (rate limit bypass possible in scaled deployments).
+**Severity**: `priority:P2` (rate limit bypass possible in scaled deployments).
 
 **Issue title**: `security: in-memory rate limiter in {FILE} has no cross-replica enforcement`
 
@@ -363,9 +363,9 @@ grep -rn "document\.cookie\s*=\|res\.cookie(" "$REPO_PATH/web" --include="*.ts"
   done
 ```
 
-**Confirm**: Verify the cookie stores user-controlled data or authentication state. Internal-only cookies (debug flags, feature flags with no sensitive data) are P3. Auth/session cookies without flags are P1.
+**Confirm**: Verify the cookie stores user-controlled data or authentication state. Internal-only cookies (debug flags, feature flags with no sensitive data) are `priority:P3`. Auth/session cookies without flags are `priority:P1`.
 
-**Severity**: P1 for auth/session tokens; P2 for user-controlled data; P3 for non-sensitive cookies.
+**Severity**: `priority:P1` for auth/session tokens; `priority:P2` for user-controlled data; `priority:P3` for non-sensitive cookies.
 
 **Issue title**: `security: {COOKIE_NAME} cookie missing {FLAGS} — vulnerable to XSS/CSRF/MITM`
 
@@ -395,7 +395,7 @@ grep -rn '||\s*["'"'"'][a-zA-Z0-9]\{4,\}["'"'"']\|default.*password\|default.*se
 
 **Confirm**: Verify the fallback value is a real credential (not a placeholder like `""` or `"REPLACE_ME"` which would fail explicitly). Confirmed if a non-trivial value would silently succeed authentication.
 
-**Severity**: P1 if the credential protects a production service; P2 otherwise.
+**Severity**: `priority:P1` if the credential protects a production service; `priority:P2` otherwise.
 
 **Issue title**: `security: credential placeholder fallback in {FILE} — {VAR} defaults to hardcoded value`
 
@@ -445,7 +445,7 @@ done
 
 **Confirm**: Verify the event type appears in a handler dispatch (not just a comment). Confirmed if the event would change user entitlements or financial state but has no handler.
 
-**Severity**: P1 for events that affect billing state (subscription.deleted, payment_failed, dispute); P2 for informational events.
+**Severity**: `priority:P1` for events that affect billing state (subscription.deleted, payment_failed, dispute); `priority:P2` for informational events.
 
 **Issue title**: `security: Stripe event {EVENT_TYPE} not handled in {FILE} — financial state may diverge`
 
@@ -466,7 +466,7 @@ grep -rn "pre_reserve\|prereserve\|reserve_credits\|MAX_COST\|max_cost\|PRE_RESE
 
 **Manual review required**: Compare the pre-reserve amount against the maximum operation cost for the highest-tier model. If pre-reserve < max possible cost, users can overdraw.
 
-**Severity**: P2 (financial loss; users can consume credits they don't have).
+**Severity**: `priority:P2` (financial loss; users can consume credits they don't have).
 
 **Issue title**: `security: pre-reservation credit cap {AMOUNT} is below maximum operation cost {MAX_COST}`
 
@@ -483,8 +483,8 @@ After all phases complete, produce a summary table:
 
 | # | Phase | Finding | File | Severity | Status |
 |---|-------|---------|------|----------|--------|
-| 1 | 1A | Port binding | docker-compose.prod.yml:12 | P1 | CONFIRMED |
-| 2 | 1B | No USER directive | services/worker/Dockerfile | P2 | CONFIRMED |
+| 1 | 1A | Port binding | docker-compose.prod.yml:12 | priority:P1 | CONFIRMED |
+| 2 | 1B | No USER directive | services/worker/Dockerfile | priority:P2 | CONFIRMED |
 ...
 ```
 
@@ -492,12 +492,14 @@ If `--dry-run` was passed, print the table and STOP. Do not create issues.
 
 ### 5B: Ensure labels exist in target repo
 
-Before creating any issues, ensure all required labels exist:
+Before creating any issues, ensure all required labels exist. Colors match the canonical ForgeDock label manifest (`bin/labels.json`). Run `npx forgedock labels setup` to bootstrap all managed labels at once.
 
 ```bash
-for label in "security" "audit-finding" "P1" "P2" "P3"; do
-  gh label create "$label" --color "d73a4a" --force -R "{GH_REPO}" 2>/dev/null || true
-done
+gh label create "security" --color "B60205" --description "Security vulnerability or hardening. Managed by ForgeDock." --force -R "{GH_REPO}" 2>/dev/null || true
+gh label create "audit-finding" --color "D93F0B" --description "Security or compliance defect found during audit. Managed by ForgeDock." --force -R "{GH_REPO}" 2>/dev/null || true
+gh label create "priority:P1" --color "D93F0B" --description "High priority — major feature broken, no workaround. Managed by ForgeDock." --force -R "{GH_REPO}" 2>/dev/null || true
+gh label create "priority:P2" --color "FBCA04" --description "Medium priority — impaired functionality, workaround exists. Managed by ForgeDock." --force -R "{GH_REPO}" 2>/dev/null || true
+gh label create "priority:P3" --color "C2E0C6" --description "Low priority — minor issue or polish. Managed by ForgeDock." --force -R "{GH_REPO}" 2>/dev/null || true
 ```
 
 ### 5C: Create GitHub issues for CONFIRMED findings
@@ -559,9 +561,9 @@ gh issue comment "{CALLER_ISSUE}" -R {FORGE_REPO} --body "$(cat <<'COMMENT_EOF'
 
 | Severity | Count |
 |----------|-------|
-| P1 | {P1_COUNT} |
-| P2 | {P2_COUNT} |
-| P3 | {P3_COUNT} |
+| priority:P1 | {P1_COUNT} |
+| priority:P2 | {P2_COUNT} |
+| priority:P3 | {P3_COUNT} |
 
 ### Issues Created
 

package/commands/sync-ecosystem.md

@@ -217,7 +217,7 @@ Create issues in the affected repos:
 # For satellite repos (separate GitHub repos):
 gh issue create -R {TARGET_REPO} \
   --title "feat(sync): {description of what API change needs to be reflected}" \
-  --label "feature,P2" \
+  --label "feature,priority:P2" \
   --body "$(cat <<'BODY_EOF'
 ## Problem
 
@@ -254,7 +254,7 @@ BODY_EOF
 # For monorepo issues (SDKs, packages inside a single repo):
 gh issue create \
   --title "feat(sync): {description of what API change needs to be reflected}" \
-  --label "feature,P2" \
+  --label "feature,priority:P2" \
   --body "$(cat <<'BODY_EOF'
 ## Problem
 

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

@@ -65,6 +65,134 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 
 ---
 
+## Phase A0: Read Custom Instructions and Project Conventions
+
+Read project-resident authoritative docs **before** any code path tracing. `project/custom-instructions.md` has the highest precedence of all knowledge sources — its directives are BINDING and override agent defaults, training knowledge, and all other context. Other applicable `project/*.md` files provide authoritative project conventions the architect must enforce.
+
+**Time budget**: 30 seconds. If exceeded, log a skip note and continue to Phase A1.
+
+**Skip if**: `{REPO_PATH}` is not set, devdocs path does not exist, or path contains no markdown files.
+
+### Step 0: Resolve devdocs path
+
+Read `forge.yaml → devdocs.path` from the project root. Default to `devdocs` if the key is absent or unreadable.
+
+```bash
+DEVDOCS_PATH=""
+
+FORGE_YAML_PATH="{REPO_PATH}/forge.yaml"
+
+if [ -f "$FORGE_YAML_PATH" ]; then
+  DEVDOCS_REL=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
+    | grep '^\s*path:' \
+    | head -1 \
+    | sed 's/.*path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+fi
+
+DEVDOCS_REL="${DEVDOCS_REL:-devdocs}"
+DEVDOCS_PATH="{REPO_PATH}/${DEVDOCS_REL}"
+
+if [ ! -d "$DEVDOCS_PATH" ]; then
+  echo "Devdocs path '${DEVDOCS_PATH}' does not exist — skipping Phase A0 (no blocking)"
+  DEVDOCS_PATH=""
+fi
+```
+
+> **Note**: `devdocs/` must be tracked in git for the worktree to contain it. If the project gitignores `devdocs/`, the path will not exist in the worktree and this phase silently skips — this is by design. Run `git check-ignore -v devdocs/` to confirm tracking status.
+
+### Step 1: Priority read — custom instructions (HIGHEST PRECEDENCE)
+
+Always read `project/custom-instructions.md` first if it exists. Directives in this file are BINDING — they override everything else.
+
+```bash
+CUSTOM_INSTRUCTIONS=""
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  CUSTOM_INSTRUCTIONS_FILE="${DEVDOCS_PATH}/project/custom-instructions.md"
+  if [ -f "$CUSTOM_INSTRUCTIONS_FILE" ]; then
+    TOTAL_LINES=$(wc -l < "$CUSTOM_INSTRUCTIONS_FILE" 2>/dev/null || echo 0)
+    if [ "$TOTAL_LINES" -gt 200 ]; then
+      CUSTOM_INSTRUCTIONS=$(head -200 "$CUSTOM_INSTRUCTIONS_FILE")
+      CUSTOM_INSTRUCTIONS="${CUSTOM_INSTRUCTIONS}
+
+_[Truncated at 200 lines — ${TOTAL_LINES} total. Read full file for complete directives.]_"
+    else
+      CUSTOM_INSTRUCTIONS=$(cat "$CUSTOM_INSTRUCTIONS_FILE")
+    fi
+  fi
+fi
+```
+
+### Step 2: Secondary reads — other applicable project files
+
+Read all other `*.md` files under `DEVDOCS_PATH` where `applies_to` contains `work-on`. Skip `project/custom-instructions.md` (already read). Sort by authority (`required` first).
+
+```bash
+PROJECT_CONVENTIONS=""
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  APPLICABLE_FILES=""
+
+  while IFS= read -r -d '' mdfile; do
+    # Skip custom-instructions — already read as priority
+    [ "$mdfile" = "${DEVDOCS_PATH}/project/custom-instructions.md" ] && continue
+
+    FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$mdfile" 2>/dev/null)
+
+    if echo "$FRONTMATTER" | grep -q 'applies_to:.*work-on'; then
+      AUTHORITY=$(echo "$FRONTMATTER" | grep 'authority:' | head -1 | sed 's/.*authority:\s*//' | tr -d ' ')
+      case "$AUTHORITY" in
+        required)    SORT_KEY="1" ;;
+        recommended) SORT_KEY="2" ;;
+        *)           SORT_KEY="3" ;;
+      esac
+      APPLICABLE_FILES="${APPLICABLE_FILES}${SORT_KEY}|${mdfile}\n"
+    fi
+  done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
+
+  APPLICABLE_FILES=$(printf "$APPLICABLE_FILES" | sort | cut -d'|' -f2-)
+
+  while IFS= read -r mdfile; do
+    [ -z "$mdfile" ] && continue
+    TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
+    if [ "$TOTAL_LINES" -gt 200 ]; then
+      FILE_CONTENT=$(head -200 "$mdfile")
+      TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total.]_"
+    else
+      FILE_CONTENT=$(cat "$mdfile")
+      TRUNCATION_NOTE=""
+    fi
+
+    REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
+    PROJECT_CONVENTIONS="${PROJECT_CONVENTIONS}
+
+#### \`${REL_PATH}\`
+${FILE_CONTENT}
+${TRUNCATION_NOTE}"
+  done <<< "$APPLICABLE_FILES"
+fi
+```
+
+### Step 3: Precedence rules to enforce
+
+When `CUSTOM_INSTRUCTIONS` or `PROJECT_CONVENTIONS` is non-empty, the architect MUST apply them throughout the plan. The precedence order is:
+
+```
+project/custom-instructions.md  ← HIGHEST PRIORITY (binding directives)
+    ↑
+other project/*.md              ← Authoritative project conventions
+agent/*.md                      ← ForgeDock/GitHub usage instructions
+agent memory                    ← Recalled knowledge
+agent defaults                  ← Built-in behaviors
+    ↓ LOWEST PRIORITY
+```
+
+`CUSTOM_INSTRUCTIONS` and `PROJECT_CONVENTIONS` are used in the `### Custom Instructions (HIGHEST PRECEDENCE)` and `### Project Conventions` sections of the FORGE:ARCHITECT output. If both are empty (devdocs path absent), these sections are replaced with skip notes.
+
+---
+
 ## Phase A1: Read Entry Points
 
 Identify every entry point that initiates the affected logic. Start from the files named in the investigation report.
@@ -226,6 +354,20 @@ Post the following as a GitHub comment on `{NUMBER}`:
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 ## Implementation Plan for #{NUMBER}
 
+### Custom Instructions (HIGHEST PRECEDENCE)
+<!-- Binding directives from project/custom-instructions.md (Phase A0).
+     These override agent defaults, training knowledge, and all other context.
+     Builder MUST follow these exactly — violations are elevated to HIGH severity in review.
+     If devdocs path was absent or file not found: 'No custom-instructions.md found at
+     {DEVDOCS_PATH}/project/custom-instructions.md — skipping. Run `npx forgedock docs init`.' -->
+{CUSTOM_INSTRUCTIONS}
+
+### Project Conventions
+<!-- Authoritative project knowledge from project/*.md and agent/*.md files
+     with applies_to: work-on (Phase A0). Read these before finalizing the plan.
+     If devdocs path was absent or no applicable files found: 'No applicable devdocs found.' -->
+{PROJECT_CONVENTIONS}
+
 ### Affected Paths (ALL must be updated)
 | # | File | Function/Class | Change Required | Why |
 |---|------|----------------|-----------------|-----|
@@ -259,9 +401,10 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 
 ## Timing Rules
 
-- Each file read: skip if the file exceeds 500 lines and only the first 100 lines are needed for structure
+- Phase A0 devdocs read: 30s total budget (path resolution + file enumeration + content reads); skip if exceeded
+- Each file read (A1): skip if the file exceeds 500 lines and only the first 100 lines are needed for structure
 - Each `grep -r` call: timeout after 10s, skip if exceeded
-- Total wall time budget: **3 minutes**. If budget exceeded, post partial results with `<!-- FORGE:ARCHITECT:PARTIAL -->` marker instead of `COMPLETE`.
+- Total wall time budget: **3 minutes** (A0 through A5 combined). If budget exceeded, post partial results with `<!-- FORGE:ARCHITECT:PARTIAL -->` marker instead of `COMPLETE`.
 
 ---
 
@@ -285,7 +428,16 @@ This module runs at **Step 3C.6** — after Context Gathering, before Implement:
 3C    → Builder Contract posted
 3C.5  → Context Gathering (FORGE:CONTEXT comment)
 3C.6  → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
+          Phase A0: Read Custom Instructions and Project Conventions (highest precedence)
+          Phase A1: Read Entry Points
+          Phase A2: Trace the Data Flow
+          Phase A2.5: Pipeline Phase-Dependency Check
+          Phase A3: Consistency Rules
+          Phase A4: Sequence the Implementation
+          Phase A5: Risk Assessment
 3F    → Implement (builder reads plan, implements ALL affected paths)
 ```
 
 The builder agent reads the `<!-- FORGE:ARCHITECT -->` comment as its **primary input** before writing any code. The raw issue body is secondary context. If the architect step was skipped, the builder falls back to investigation report + contract.
+
+**Devdocs precedence** (Phase A0): `project/custom-instructions.md` has ABSOLUTE priority over all other context. The architect's plan must reflect any directives in that file — if custom instructions mandate a specific pattern, the implementation order and approach MUST follow it, even if the architect's general reasoning suggests an alternative. <!-- Added: forge#259 -->

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

@@ -33,6 +33,117 @@ Parse from `$ARGUMENTS`:
 
 ---
 
+## Phase C-1: Authoritative Devdocs
+
+Read project-resident authoritative docs **before** any institutional-memory queries. Devdocs contain binding project knowledge (conventions, architecture, custom instructions) that must inform the builder's mental model from the start.
+
+**Time budget**: 30 seconds. If exceeded, log a skip note and continue to Phase C0.
+
+**Skip if**: `{REPO_PATH}` is not set, devdocs path does not exist, or path contains no markdown files.
+
+### Step 0: Resolve devdocs path
+
+Read `forge.yaml → devdocs.path` from the project root. Default to `devdocs` if the key is absent or unreadable.
+
+```bash
+DEVDOCS_PATH=""
+
+# Read forge.yaml directly from repo root (REPO_PATH points to the project root — no directory walk)
+FORGE_YAML_PATH="{REPO_PATH}/forge.yaml"
+
+if [ -f "$FORGE_YAML_PATH" ]; then
+  # Extract devdocs.path key (simple grep — value is on the same or next line under "devdocs:")
+  DEVDOCS_REL=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
+    | grep '^\s*path:' \
+    | head -1 \
+    | sed 's/.*path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+fi
+
+# Default to "devdocs" if not found
+DEVDOCS_REL="${DEVDOCS_REL:-devdocs}"
+DEVDOCS_PATH="{REPO_PATH}/${DEVDOCS_REL}"
+
+if [ ! -d "$DEVDOCS_PATH" ]; then
+  echo "Devdocs path '${DEVDOCS_PATH}' does not exist — skipping Phase C-1 (no blocking)"
+  DEVDOCS_PATH=""
+fi
+```
+
+> **Note**: `devdocs/` must be tracked in git for the worktree to contain it. If the project gitignores `devdocs/`, the path will not exist in the worktree and this phase silently skips — this is by design. Run `git check-ignore -v devdocs/` to confirm tracking status.
+
+### Step 1: Enumerate and filter applicable files
+
+Find all `.md` files under `DEVDOCS_PATH`, parse YAML frontmatter, keep those with `work-on` in `applies_to`. Sort by authority (`required` first, then `recommended`, then `reference`).
+
+```bash
+DEVDOCS_APPLICABLE=""  # list of paths that apply
+
+if [ -n "$DEVDOCS_PATH" ]; then
+  # Find all markdown files recursively
+  while IFS= read -r -d '' mdfile; do
+    # Extract frontmatter block (between first two --- markers)
+    FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$mdfile" 2>/dev/null)
+
+    # Check if applies_to contains work-on
+    if echo "$FRONTMATTER" | grep -q 'applies_to:.*work-on'; then
+      AUTHORITY=$(echo "$FRONTMATTER" | grep 'authority:' | head -1 | sed 's/.*authority:\s*//' | tr -d ' ')
+      # Prepend sort key: 1=required, 2=recommended, 3=reference, 4=other
+      case "$AUTHORITY" in
+        required)    SORT_KEY="1" ;;
+        recommended) SORT_KEY="2" ;;
+        reference)   SORT_KEY="3" ;;
+        *)           SORT_KEY="4" ;;
+      esac
+      DEVDOCS_APPLICABLE="${DEVDOCS_APPLICABLE}${SORT_KEY}|${mdfile}\n"
+    fi
+  done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
+
+  # Sort by authority key and extract paths
+  DEVDOCS_APPLICABLE=$(printf "$DEVDOCS_APPLICABLE" | sort | cut -d'|' -f2-)
+fi
+
+if [ -z "$DEVDOCS_APPLICABLE" ]; then
+  echo "No devdocs files with 'applies_to: work-on' found — skipping Phase C-1 content read"
+fi
+```
+
+### Step 2: Read content of applicable files
+
+For each applicable file: read its content (max 200 lines; truncate with note if longer). Accumulate for output.
+
+```bash
+DEVDOCS_CONTENT=""
+
+while IFS= read -r mdfile; do
+  [ -z "$mdfile" ] && continue
+  TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
+  if [ "$TOTAL_LINES" -gt 200 ]; then
+    FILE_CONTENT=$(head -200 "$mdfile")
+    TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total. Read full file for complete context.]_"
+  else
+    FILE_CONTENT=$(cat "$mdfile")
+    TRUNCATION_NOTE=""
+  fi
+
+  # Relative path for display
+  REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
+
+  DEVDOCS_CONTENT="${DEVDOCS_CONTENT}
+
+#### \`${REL_PATH}\`
+${FILE_CONTENT}
+${TRUNCATION_NOTE}"
+done <<< "$DEVDOCS_APPLICABLE"
+```
+
+### Step 3: Store for output
+
+`DEVDOCS_CONTENT` is used in the `### Authoritative Devdocs` section of the FORGE:CONTEXT comment output. If empty (path absent or no applicable files), the section is replaced with a skip note.
+
+---
+
 ## Phase C0: Prior Investigation Findings (from Gists)
 
 Scan the issue body for `<!-- FORGE:PRIOR_GIST: {url} -->` annotations embedded by the decompose or orchestrate phases (GIST-02). Also check for `<!-- FORGE:MILESTONE_INDEX: {url} -->` annotations — these reference a milestone-level index Gist (GIST-04) that aggregates all investigation Gist URLs for a milestone into a single reference. Both annotation types reference Knowledge Gists created during upstream investigation (GIST-01) and contain structured findings — verdict, root cause, recommendation, affected files — that the builder needs before writing code.
@@ -278,6 +389,14 @@ Post the following as a GitHub comment on `{NUMBER}`:
 gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 ## Implementation Context for #{NUMBER}
 
+### Authoritative Devdocs
+<!-- Project-resident authoritative knowledge read from devdocs/ (Phase C-1).
+     These files have the highest precedence — they override agent defaults and memory.
+     custom-instructions.md directives are BINDING and MUST be followed exactly.
+     If devdocs path was absent or no files matched applies_to: work-on — write:
+     'No devdocs found at {DEVDOCS_PATH} — skipping. Run `npx forgedock docs init` to scaffold.' -->
+{DEVDOCS_CONTENT}
+
 ### Prior Investigation Findings
 <!-- Summarized Knowledge Gist content from upstream investigations (Phase C0).
      If no FORGE:PRIOR_GIST annotations were found in the issue body: omit this section entirely.
@@ -317,11 +436,12 @@ gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 
 ## Timing Rules
 
+- Phase C-1 devdocs read: 30s total budget (file enumeration + content reads combined); skip if exceeded
 - Phase C0 `gh gist view` calls: timeout after 15s each, 30s total budget for all Gist fetches
 - Each `gh issue list` call: timeout after 20s, skip if exceeded
 - Each `gh pr list` call: timeout after 20s, skip if exceeded
 - Each `grep -r` call: timeout after 10s, skip if exceeded
-- Total wall time budget: **2 minutes** (C0 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
+- Total wall time budget: **2 minutes** (C-1 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
 
 ---
 
@@ -339,11 +459,19 @@ Skip this entire step (post nothing, return empty briefing) if:
 This module runs at **Step 3C.5** — after Builder Contract is posted, before Implement:
 
 ```
-3C  → Builder Contract posted
+3C   → Builder Contract posted
 3C.5 → [THIS MODULE] Context gathering (max 2 min)
-3F  → Implement (builder now has context briefing)
+         Phase C-1: Authoritative Devdocs (project-resident knowledge — highest precedence)
+         Phase C0:  Prior Investigation Findings (from Gists)
+         Phase C1:  Past Review Findings on These Files
+         Phase C2:  Past Bugs in the Same Module
+         Phase C3:  Related Code Paths
+         Phase C4:  Successful Similar Implementations
+3F   → Implement (builder now has context briefing)
 ```
 
 The builder agent reads the `<!-- FORGE:CONTEXT -->` comment before writing any code. If the context step was skipped, the builder proceeds with investigation report + contract only.
 
+**Devdocs precedence** (Phase C-1): Content from `project/custom-instructions.md` has the HIGHEST precedence of all context sources. Directives there override agent defaults, training knowledge, and all other devdocs. Other `project/*.md` and `agent/*.md` files with `applies_to: work-on` provide authoritative project conventions and ForgeDock usage guidance. <!-- Added: forge#259 -->
+
 When prior investigation Gists are available (Phase C0), the `### Prior Investigation Findings` section gives the builder cross-issue context — root causes, recommendations, and affected files from upstream investigations — without requiring manual Gist lookups. When a milestone-level index Gist exists (GIST-04), Phase C0 can resolve the index to discover all investigation Gists for the milestone from a single URL — providing full milestone-wide context automatically. <!-- Updated: forge#341 -->

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

@@ -88,31 +88,50 @@ Needs human review before proceeding to commit.
 
 ## Phase V2: Format and Verify
 
-Run after quality gate passes. Format checks are per-language:
+Run after quality gate passes. All tool commands are read from `forge.yaml → verification.commands`; each step logs `SKIPPED — not configured` when the corresponding key is absent rather than silently passing:
 
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
-black {PYTHON_FILES}
-isort {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 for Python files (no config needed — catches syntax errors)
 python -m py_compile {PYTHON_FILES}
 ```
 Failures in `py_compile` are BLOCKING — fix before continuing.
 
-**TypeScript (tsc)**:
+**TypeScript**:
 ```bash
 cd {WORKTREE_PATH}
-prettier --write {TS_FILES}
-tsc --noEmit
-```
-`tsc --noEmit` failures are BLOCKING — fix type errors before continuing.
 
-**TypeScript (satellite repos — MCP, n8n)**:
-```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 — fix type errors before continuing.
 
 **Shell scripts**: Verify service interactions — read target middleware files, document what was verified in V4 summary.
 

package/commands/work-on/decompose.md

@@ -40,6 +40,8 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 - If FORGE:INVESTIGATOR comment is absent → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "No investigation report found — run investigate first"
 - If investigation report has no Decomposition Assessment section, OR the assessment does not list any sub-issues → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "Investigation report has no decomposition plan — re-run investigate with explicit decomposition scope"
 
+> **Shared Scoping Convention**: This investigation gate (blocks without a `FORGE:INVESTIGATOR` comment) is the **reference pattern** for investigation-gated issue creation across the pipeline. `milestone.md` Step 4 and `orchestrate.md` MUST apply the same principle: read code and identify all affected call sites BEFORE writing any issue body. Sub-issue bodies created in Phase D3 MUST use the Pipeline Issue Template defined in `issue.md` Phase 3D — that template is the single canonical standard for all automated issue creation. <!-- Added: forge#293 -->
+
 Extract from investigation report:
 - Decomposition Assessment section: list of proposed sub-issues with titles and dependencies
 - Milestone (from issue metadata)

package/commands/work-on-monolithic.md

@@ -89,16 +89,20 @@ Mission: Validate whether the issue is real. Assume description is wrong until p
 
 **Domain file hints** (start search here):
 
-| Domain | Key files |
-|--------|-----------|
-| BILLING | `routers/billing.py`, `core/pricing.py`, `services/credit_service.py` |
-| SCRAPING | `unified_consumer.py`, `queues.py`, `domain_playbooks.json` |
+Configure domain-to-file mappings for your project in `forge.yaml → review.key_paths`. The table below shows the standard layout — override any entry that doesn't match your codebase:
+
+| Domain | Default key files (override via forge.yaml) |
+|--------|---------------------------------------------|
+| BILLING | `routers/billing.py`, `core/pricing.py`, `services/payment_service.py` |
+| WORKER | `worker/main.py`, `worker/queues.py`, `worker/tasks.py` |
 | AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
 | DATABASE | `infra/migrations/`, `models/`, `db/` |
 | FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
-| CORTEX | `cortex_client.py`, `routers/cortex.py` |
+| AI | `services/ai_client.py`, `routers/ai.py` |
 | INFRA | `.github/workflows/`, `docker-compose.yml`, `infra/traefik/` |
 
+If `forge.yaml → review.key_paths` is present, use those mappings instead of the defaults above.
+
 **Steps**: Check right branch → read domain files → verify claims → git blame → determine root cause → identify affected files → validate proposed fixes against full system stack.
 
 **Fix-Approach Validation**: If issue proposes a fix, don't adopt it as spec. Trace through target system's middleware, auth, routing.