forgedock 1.0.8 → 1.0.10

package/commands/forgedock-init.md

@@ -1,534 +1,455 @@
 ---
-description: AI-powered forge.yaml config generator — scans codebase, queries GitHub, fills all optional sections interactively
-argument-hint: [--force | --section <name>]
+description: init-enrich skill backend — consumes a ConfigDraft, deeply infers hard sections from codebase + GitHub, returns enriched ConfigDraft with raised confidences
+argument-hint: <ConfigDraft JSON>
 ---
 
-# /forgedock-init — AI-Powered Config Generator
+# /forgedock-init — init-enrich Skill Backend
 
 **Input**: $ARGUMENTS
 
-You complete the `forge.yaml` configuration that `npx forgedock init` started. The CLI generates required sections (project, paths, branches) from auto-detection. Your job is to scan the codebase, query GitHub APIs, ask targeted clarifying questions, and produce a complete `forge.yaml` with every applicable optional section filled.
+You are the **init-enrich skill backend** for ForgeDock's intelligent onboarding pipeline. You consume a `ConfigDraft` JSON object produced by `init-detect`, deeply infer the hard sections (`project_board`, `repos.satellites`, `review`, `verification`) by scanning the codebase and querying GitHub, and return an enriched `ConfigDraft` with the same leaf shape and raised confidences.
+
+**This is a backend, not a wizard.** You MUST NOT ask the user any interactive questions. You MUST NOT write any files. Unknowable items are represented as `low`-confidence TODO-flagged fields — never as blocking prompts.
 
 **Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---
 
-## Argument Parsing
+## ConfigDraft Contract
 
-| Flag | Effect |
-|------|--------|
-| (none) | Fill all optional sections not yet configured |
-| `--force` | Overwrite ALL optional sections without asking |
-| `--section <name>` | Fill only one section: `repos`, `project_board`, `services`, `review`, or `verification` |
+Every leaf in a `ConfigDraft` has the shape:
 
-Parse `$ARGUMENTS` and set:
-```
-FORCE = true if --force present
-TARGET_SECTION = value from --section <name>, or "all"
+```json
+{ "value": "<string>", "confidence": "high|medium|low", "source": "<string>", "why": "<string>" }
 ```
 
-If `--section` was provided, validate the value immediately:
+Confidence levels:
+- `high` — verified from a concrete, unambiguous source
+- `medium` — inferred from available signals; likely correct
+- `low` — guessed default or not found; caller should surface as a `# TODO(forgedock:<field>)` flag
 
-```bash
-ALLOWED_SECTIONS="repos project_board services review verification"
-if [ "$TARGET_SECTION" != "all" ]; then
-  VALID=false
-  for s in $ALLOWED_SECTIONS; do
-    [ "$TARGET_SECTION" = "$s" ] && VALID=true && break
-  done
-  if [ "$VALID" = "false" ]; then
-    echo "Error: '$TARGET_SECTION' is not a valid section name."
-    echo ""
-    echo "Valid sections: repos, project_board, services, review, verification"
-    echo ""
-    echo "Usage: /forgedock-init --section <name>"
-    exit 1
-  fi
-fi
-```
+This skill extends the draft by adding optional section fields. It never removes or downgrades existing fields. Required sections (project, paths, branches) are passed through unchanged.
 
 ---
 
-## Phase 1: Load forge.yaml
+## Phase 0: Parse Input and Extract Identity
 
-### 1A: Locate and read
+### 0A: Parse ConfigDraft from $ARGUMENTS
 
-```bash
-FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"
-if [ ! -f "$FORGE_YAML" ]; then
-  echo "forge.yaml not found in current directory."
-  echo ""
-  echo "Run first:  npx forgedock init"
-  echo ""
-  echo "This generates the required skeleton (project, paths, branches)."
-  echo "Then re-run /forgedock-init to complete the optional sections."
-  exit 1
-fi
-cat "$FORGE_YAML"
+`$ARGUMENTS` contains a ConfigDraft JSON string. Parse it:
+
+```
+DRAFT = JSON.parse($ARGUMENTS)
+```
+
+If `$ARGUMENTS` is empty or not valid JSON, output an error and exit:
+
+```
+Error: /forgedock-init expects a ConfigDraft JSON string as its argument.
+
+Usage:
+  The init-detect module produces the ConfigDraft. Example:
+    node -e "import('./bin/init-detect.mjs').then(m => m.detectConfig()).then(d => console.log(JSON.stringify(d)))"
+
+  Pass the output as the argument to /forgedock-init.
 ```
 
-### 1B: Extract required section values
+### 0B: Extract identity fields
 
-Parse these from the existing file — they are needed for all subsequent queries:
+Extract these from the incoming draft for use in all GitHub queries:
 
 ```
-OWNER     = project.owner
-REPO      = project.repo
-REPO_ROOT = paths.root
+OWNER     = DRAFT.project.owner.value       # GitHub org or username
+REPO      = DRAFT.project.repo.value        # Repository name
+REPO_ROOT = DRAFT.paths.root.value          # Absolute path to repo root
 ```
 
-After extracting these values, validate that OWNER and REPO are non-empty and do not contain placeholder values before proceeding:
+Validate that OWNER and REPO are non-empty and not placeholder values before proceeding with any GitHub queries:
 
-```bash
-if [ -z "$OWNER" ] || [ "$OWNER" = "your-github-org" ]; then
-  echo "Error: project.owner is not set in forge.yaml."
-  echo ""
-  echo "Open forge.yaml and fill in the 'project:' section:"
-  echo "  project:"
-  echo "    owner: \"your-actual-github-org-or-username\""
-  echo ""
-  echo "Then re-run /forgedock-init."
-  exit 1
-fi
+```
+if OWNER is empty or equals "your-github-org":
+  set OWNER = null  # GitHub queries will be skipped
+  note: "project.owner is a placeholder — board and satellite enrichment skipped"
 
-if [ -z "$REPO" ] || [ "$REPO" = "your-repo-name" ]; then
-  echo "Error: project.repo is not set in forge.yaml."
-  echo ""
-  echo "Open forge.yaml and fill in the 'project:' section:"
-  echo "  project:"
-  echo "    repo: \"your-actual-repo-name\""
-  echo ""
-  echo "Then re-run /forgedock-init."
-  exit 1
-fi
+if REPO is empty or equals "your-repo-name":
+  set REPO = null
+  note: "project.repo is a placeholder — satellite enrichment skipped"
 ```
 
-### 1C: Detect already-configured optional sections
+These are non-blocking — an incomplete draft still gets codebase enrichment (review, verification).
 
-For each optional section, check if it has an UNCOMMENTED entry in the file. A commented-out section (all lines starting with `#`) is NOT configured.
+### 0C: Check GitHub auth
 
 ```bash
-# Check which optional sections are already active (uncommented)
-grep -q "^repos:" "$FORGE_YAML" && HAS_REPOS=true || HAS_REPOS=false
-grep -q "^project_board:" "$FORGE_YAML" && HAS_PROJECT_BOARD=true || HAS_PROJECT_BOARD=false
-grep -q "^services:" "$FORGE_YAML" && HAS_SERVICES=true || HAS_SERVICES=false
-grep -q "^review:" "$FORGE_YAML" && HAS_REVIEW=true || HAS_REVIEW=false
-grep -q "^verification:" "$FORGE_YAML" && HAS_VERIFICATION=true || HAS_VERIFICATION=false
+gh auth status 2>&1
 ```
 
-If `FORCE=false` and a section is already active, skip it (unless `--section` targets it explicitly). Tell the user which sections were skipped and why.
+Set `GH_AUTHED = true` if the output does NOT contain "not logged in" or "You are not logged into". Set `GH_AUTHED = false` otherwise.
+
+If `GH_AUTHED = false` or `OWNER = null`: GitHub-dependent enrichment phases (1, 2) will be skipped; their fields will be set to `low` confidence with a TODO. Codebase-only phases (3, 4) still run.
 
 ---
 
-## Phase 2: Codebase Scan
+## Phase 1: Enrich project_board
 
-Run these scans unconditionally — they populate defaults that reduce the number of clarifying questions needed.
+**Skip if**: `GH_AUTHED = false` or `OWNER = null`.
 
-### 2A: Tech stack detection
+### 1A: Discover project boards
 
 ```bash
-# Node.js / TypeScript
-[ -f "$REPO_ROOT/package.json" ] && \
-  cat "$REPO_ROOT/package.json" | grep -E '"name"|"dependencies"|"devDependencies"' | head -30
+gh project list --owner "$OWNER" --format json 2>/dev/null \
+  | jq '[.projects[] | {number: .number, title: .title, id: .id}]'
+```
 
-# Python
-[ -f "$REPO_ROOT/pyproject.toml" ] && grep -E "^\[project\]|^name|^requires-python|^dependencies" "$REPO_ROOT/pyproject.toml" | head -20
-[ -f "$REPO_ROOT/requirements.txt" ] && head -20 "$REPO_ROOT/requirements.txt"
+If the query fails or returns an empty list: skip Phase 1 entirely. Add a `low`-confidence placeholder for the entire `project_board` section (see 1E).
 
-# Rust
-[ -f "$REPO_ROOT/Cargo.toml" ] && grep -E "^\[package\]|^name|^edition|^\[dependencies\]" "$REPO_ROOT/Cargo.toml" | head -20
+If one project is found: select it automatically (high confidence — no ambiguity).
+If multiple projects are found: select the first one (medium confidence — note that the first result may not be the right project board).
 
-# Ruby
-[ -f "$REPO_ROOT/Gemfile" ] && head -15 "$REPO_ROOT/Gemfile"
+Record:
+```
+PROJECT_NUMBER = first (or only) project number
+PROJECT_TITLE  = project title
+PROJECT_ID     = project id (the PVT_... node ID)
+```
 
-# Go
-[ -f "$REPO_ROOT/go.mod" ] && head -10 "$REPO_ROOT/go.mod"
+### 1B: Fetch field definitions
+
+```bash
+gh project field-list "$PROJECT_NUMBER" --owner "$OWNER" --format json 2>/dev/null \
+  | jq '[.fields[] | {name: .name, id: .id, type: .type, options: (.options // [])}]'
 ```
 
-Build `TECH_STACK` description from findings (e.g., "Next.js 15, FastAPI, PostgreSQL").
+If the query fails: skip Phase 1, emit low-confidence placeholder.
 
-### 2B: Project context
+### 1C: Map fields to ForgeDock slots
 
-```bash
-# CLAUDE.md — primary context source
-[ -f "$REPO_ROOT/CLAUDE.md" ] && cat "$REPO_ROOT/CLAUDE.md"
+For each of the five ForgeDock field slots, search the field list case-insensitively:
 
-# README.md — fallback
-[ -f "$REPO_ROOT/README.md" ] && head -60 "$REPO_ROOT/README.md"
-```
+| ForgeDock slot | Primary match | Fallback match |
+|----------------|---------------|----------------|
+| `status` | "Status" | "State" |
+| `lane` | "Lane" | "Track", "Type" |
+| `component` | "Component" | "Area", "Team" |
+| `priority` | "Priority" | "Severity" |
+| `workflow` | "Workflow" | "Stage", "Phase" |
 
-Extract a 2–4 sentence project description for `review.context`.
+For each slot:
+- If a field is found: confidence = `high`, source = `gh project field-list`, why = `Field named "<name>" (id: <id>) found in project "<PROJECT_TITLE>"`
+- If no field matches: confidence = `low`, value = `""`, why = `No field matching "<slot>" found in project "<PROJECT_TITLE>"; add a field with this name and re-run /forgedock-init`
 
-### 2C: Docker / service names
+### 1D: Map option IDs
 
-```bash
-# Container name prefixes for verification section
-ls "$REPO_ROOT"/docker-compose*.yml 2>/dev/null
-for f in "$REPO_ROOT"/docker-compose*.yml; do
-  [ -f "$f" ] || continue
-  grep -E "^\s+container_name:|^\s+image:" "$f" | head -20
-done
-```
+For each single-select field that was successfully mapped, extract its option IDs.
 
-Extract container name prefixes (e.g., `acme-`, `my-app-`) for `verification.internal_service_patterns` and `verification.services`.
+For each of the required option slots, match case-insensitively:
 
-### 2D: Branch topology
+**status options**: "Todo" / "To Do" → `todo`; "In Progress" / "In-Progress" → `in_progress`; "Done" / "Complete" → `done`
 
-```bash
-# Staging branch detection
-git -C "$REPO_ROOT" branch -r | grep -E "staging|develop|dev" | head -5
+**lane options**: "Fast" / "Fast Lane" → `fast`; "Feature" / "Feature Lane" → `feature`; "Sync" → `sync`
 
-# CI/CD target branches
-grep -rh "branches:" "$REPO_ROOT/.github/workflows/"*.yml 2>/dev/null | head -20
-```
+**priority options**: "P0" / "Critical" → `p0`; "P1" / "High" → `p1`; "P2" / "Medium" → `p2`; "P3" / "Low" → `p3`
 
-Use to confirm or suggest `branches.staging`.
+**workflow options**: "Investigating" → `investigating`; "Building" → `building`; "In Review" / "In-Review" → `in_review`; "Merged" / "Complete" → `merged`
 
-### 2E: API health endpoint hints
+For each option:
+- If matched: confidence = `high`, source = `gh project field-list (options)`, why = `Option "<name>" (id: <id>) found in field "<field_name>"`
+- If not matched: confidence = `low`, value = `""`, why = `No option matching "<slot>" found in field "<field_name>"; add the option or set this value manually`
 
-```bash
-# Look for health route definitions
-grep -rn "health\|/ping\|/status" "$REPO_ROOT" --include="*.py" --include="*.ts" --include="*.go" -l 2>/dev/null | head -10
-grep -rn "healthcheck\|health_endpoint\|HEALTH_URL" "$REPO_ROOT" --include="*.yml" --include="*.yaml" -l 2>/dev/null | head -5
+### 1E: Build project_board enrichment
+
+Assemble the enriched `project_board` section of the draft. If Phase 1 was skipped entirely:
+
+```json
+"project_board": {
+  "owner":          { "value": "", "confidence": "low", "source": "skipped", "why": "GitHub auth unavailable or project.owner is a placeholder; run gh auth login then re-run /forgedock-init" },
+  "project_number": { "value": "", "confidence": "low", "source": "skipped", "why": "GitHub auth unavailable; project board not queried" },
+  "project_id":     { "value": "", "confidence": "low", "source": "skipped", "why": "GitHub auth unavailable; obtain via: gh project list --owner <owner> --format json | jq '.projects[] | .id' (value must start with PVT_)" },
+  "field_ids":      { ... all slots at low confidence ... },
+  "option_ids":     { ... all option slots at low confidence ... }
+}
 ```
 
+**Important**: `project_board.project_id` must be a GitHub Projects v2 node ID with the `PVT_` prefix (e.g. `PVT_kwHOxxxxxxxxxxxxxxxx`). When emitting this field at high confidence, always include a note in `why` reminding the caller of this format requirement.
+
 ---
 
-## Phase 3: GitHub Queries
+## Phase 2: Enrich repos.satellites
 
-Run these to gather live IDs. Failures are non-blocking — skip the section if the query fails.
+**Skip if**: `GH_AUTHED = false` or `OWNER = null` or `REPO = null`.
 
-### 3A: Check GitHub auth
+### 2A: List sibling repos
 
 ```bash
-gh auth status 2>&1
+gh repo list "$OWNER" --limit 50 --json name,description,primaryLanguage 2>/dev/null \
+  | jq '[.[] | select(.name != "'"$REPO"'") | {name: .name, description: (.description // ""), language: (.primaryLanguage.name // "")}]'
 ```
 
-If not authenticated, skip all GitHub queries and note which sections will need manual completion.
+If the query fails or returns empty: skip Phase 2, emit low-confidence placeholder.
 
-### 3B: Project board discovery
+### 2B: Infer satellite candidates
 
-```bash
-# List projects owned by this org/user
-gh project list --owner "$OWNER" --format json 2>/dev/null \
-  | jq '.projects[] | {number: .number, title: .title, id: .id}'
-```
+For each sibling repo, apply heuristics to determine if it looks like a ForgeDock satellite (i.e., a repo the user might want to route issues to with a short prefix):
 
-If projects found: ask the user which one ForgeDock should use (or `none`). Record:
-- `PROJECT_NUMBER`
-- `PROJECT_ID` (the `PVT_...` node ID)
+**Include as a satellite candidate if any of these match**:
+- Name ends with `-sdk`, `-api`, `-mcp`, `-cli`, `-server`, `-worker`, `-plugin`
+- Name contains `sdk`, `client`, `plugin`, `extension`, `lib`
+- Description mentions "companion", "client for", "SDK for", "plugin for", "server for"
 
-### 3C: Project board field IDs
+**Exclude**:
+- Names that are clearly personal/fork repos (contain the word "fork", start with the owner name exactly)
+- Repos with zero description and language = null (likely empty/template repos)
 
-```bash
-# Only run if PROJECT_NUMBER is set
-gh project field-list "$PROJECT_NUMBER" --owner "$OWNER" --format json 2>/dev/null \
-  | jq '.fields[] | {name: .name, id: .id, type: .type}'
-```
+For each candidate, derive a prefix:
+- Strip the `$OWNER-` prefix from the name if present (e.g. `acme-mcp-server` → `mcp-server`)
+- Take the first word before any `-` (e.g. `mcp-server` → `mcp`)
+- If the prefix conflicts with another candidate, use the first two words
 
-Map field names to their IDs:
-- Look for fields named `Status`, `Lane`, `Component`, `Priority`, `Workflow` (case-insensitive)
-- Record their `PVTSSF_...` IDs
+### 2C: Build repos enrichment
 
-```bash
-# Get option IDs for single-select fields
-gh project field-list "$PROJECT_NUMBER" --owner "$OWNER" --format json 2>/dev/null \
-  | jq '.fields[] | select(.type == "SINGLE_SELECT") | {name: .name, options: [.options[] | {name: .name, id: .id}]}'
-```
+For each satellite candidate:
 
-Map option names to IDs for `status` (Todo/In Progress/Done), `lane` (Fast/Feature/Sync), `priority` (P0/P1/P2/P3), `workflow` (Investigating/Building/In Review/Merged).
+```json
+{
+  "prefix":    { "value": "<derived-prefix>", "confidence": "medium", "source": "gh repo list + name heuristic", "why": "Repo '<name>' looks like a satellite (name pattern: <pattern>); verify prefix is correct" },
+  "repo":      { "value": "<owner>/<name>",  "confidence": "high",   "source": "gh repo list", "why": "Repo exists under owner <owner>" },
+  "staging_branch": { "value": "main", "confidence": "low", "source": "default", "why": "Could not verify staging branch without reading satellite repo; defaulting to 'main'" }
+}
+```
 
-### 3D: Satellite repo discovery
+If no candidates found:
 
-```bash
-# List all repos under this owner
-gh repo list "$OWNER" --limit 50 --json name,description,url 2>/dev/null \
-  | jq '.[] | select(.name != "'"$REPO"'") | {name: .name, description: .description}'
+```json
+"repos": {
+  "satellites": [],
+  "_enrichment_note": { "value": "none", "confidence": "low", "source": "gh repo list", "why": "No repos under <owner> matched satellite heuristics; if satellites exist, add them manually to forge.yaml" }
+}
 ```
 
-Present the list and ask: "Do any of these serve as satellite repos that you'd route issues to with a prefix (e.g., `mcp:5`)?"
-
 ---
 
-## Phase 4: Interactive Clarification
+## Phase 3: Enrich review
 
-Ask only about items NOT already determined by Phases 2–3. Keep questions grouped by section. Use `read` or present multiple-choice.
+**Always runs** — does not require GitHub auth.
 
-### 4A: repos section
+### 3A: Detect tech stack
 
-Only ask if satellite repos were found in 3D:
+For each supported ecosystem, check for its manifest file under `$REPO_ROOT`:
 
+**Node.js / TypeScript**:
+```bash
+if [ -f "$REPO_ROOT/package.json" ]; then
+  # Extract name, framework dependencies
+  cat "$REPO_ROOT/package.json" | jq '{
+    name: .name,
+    deps: ((.dependencies // {}) + (.devDependencies // {})) | keys | map(select(
+      test("next|react|vue|nuxt|svelte|express|fastify|hono|nest|koa|astro|remix|gatsby|vite|esbuild|rollup|webpack|prisma|drizzle|sequelize|typeorm|mongoose")
+    ))
+  }'
+fi
 ```
-The following repos were found under {OWNER}:
-  - {repo_name}: {description}
-  (...)
 
-Do any of these serve as satellite repos for ForgeDock routing?
-If yes, enter a prefix:repo mapping (e.g., "mcp:acme-mcp-server"), or "none":
+**Python**:
+```bash
+[ -f "$REPO_ROOT/pyproject.toml" ] && grep -E "^(name|requires-python)" "$REPO_ROOT/pyproject.toml" | head -5
+[ -f "$REPO_ROOT/pyproject.toml" ] && grep -E "fastapi|django|flask|starlette|sqlalchemy|pydantic|alembic|celery|aiohttp" "$REPO_ROOT/pyproject.toml" | head -10
+[ -f "$REPO_ROOT/requirements.txt" ] && grep -iE "fastapi|django|flask|starlette|sqlalchemy|pydantic|alembic|celery|aiohttp" "$REPO_ROOT/requirements.txt" | head -10
 ```
 
-### 4B: project_board section
+**Rust**:
+```bash
+[ -f "$REPO_ROOT/Cargo.toml" ] && grep -E "^name|axum|actix|rocket|tokio|serde|sqlx" "$REPO_ROOT/Cargo.toml" | head -10
+```
 
-If project board found in 3B but field mapping is ambiguous:
+**Go**:
+```bash
+[ -f "$REPO_ROOT/go.mod" ] && head -10 "$REPO_ROOT/go.mod"
+```
 
+**Ruby**:
+```bash
+[ -f "$REPO_ROOT/Gemfile" ] && grep -E "rails|sinatra|roda|hanami|sidekiq" "$REPO_ROOT/Gemfile" | head -5
 ```
-Found project board: "{TITLE}" (#{PROJECT_NUMBER})
 
-Field mapping (press Enter to accept detected name, or type correct field name):
-  Status field   → detected: "{DETECTED}" (ID: {ID})
-  Lane field     → detected: "{DETECTED}" (ID: {ID})
-  ...
+**Docker / infrastructure**:
+```bash
+ls "$REPO_ROOT"/docker-compose*.yml 2>/dev/null | head -5
+[ -f "$REPO_ROOT/Dockerfile" ] && head -5 "$REPO_ROOT/Dockerfile"
 ```
 
-### 4C: services section
+Build a concise `TECH_STACK` string from the detected components, e.g. "Next.js 15, FastAPI, PostgreSQL 16, Docker". If multiple ecosystems are detected, list all. If nothing is detected, set `TECH_STACK = ""`.
 
-```
-Does your project use any of the following analytics/monitoring services?
-  [1] Umami (self-hosted)
-  [2] Microsoft Clarity
-  [3] Google Analytics 4
-  [4] None / Skip this section
+**Confidence**:
+- One or more manifest files found → `medium` (detected from deps but not verified running)
+- Nothing detected → `low`
 
-Enter numbers separated by commas (e.g., "1,3"), or "4" to skip:
-```
+### 3B: Extract project context
 
-If any selected, ask for the specific IDs/URLs required by each.
+```bash
+# Primary: CLAUDE.md
+if [ -f "$REPO_ROOT/CLAUDE.md" ]; then
+  cat "$REPO_ROOT/CLAUDE.md"
+fi
 
-```
-Do you have an API URL for health checks? (e.g., https://api.myproject.io)
-Enter URL or press Enter to skip:
+# Fallback: README.md (first 80 lines)
+if [ ! -f "$REPO_ROOT/CLAUDE.md" ] && [ -f "$REPO_ROOT/README.md" ]; then
+  head -80 "$REPO_ROOT/README.md"
+fi
 ```
 
-### 4D: review section
+From the content, synthesize a 2–4 sentence `REVIEW_CONTEXT` that captures:
+- What the project does
+- Its architecture (if mentioned)
+- Any deploy or infrastructure notes relevant to a code reviewer
+- Known conventions or pitfalls (if mentioned)
 
-```
-Detected tech stack: {TECH_STACK}
+If neither CLAUDE.md nor README.md exists: `REVIEW_CONTEXT = ""` at low confidence.
 
-Is this accurate? Add/edit if needed, or press Enter to accept:
-```
+**Confidence**:
+- Synthesized from CLAUDE.md → `high`
+- Synthesized from README.md → `medium`
+- No source found → `low`
 
-```
-Any additional context for code reviewers? (unusual conventions, deploy setup, known pitfalls)
-Press Enter to skip, or describe briefly:
+### 3C: Build review enrichment
+
+```json
+"review": {
+  "tech_stack": { "value": "<TECH_STACK>", "confidence": "<high|medium|low>", "source": "<manifest files found>", "why": "<what was detected>" },
+  "context":    { "value": "<REVIEW_CONTEXT>", "confidence": "<high|medium|low>", "source": "<CLAUDE.md|README.md|none>", "why": "<synthesis note>" }
+}
 ```
 
-### 4E: verification section
+---
 
-```
-Detected potential health endpoint path: {DETECTED_PATH}
-Full health URL (e.g., https://api.myproject.io/health), or press Enter to skip:
+## Phase 4: Enrich verification
+
+**Always runs** — does not require GitHub auth.
+
+### 4A: Detect health endpoint
+
+```bash
+# Search for health route definitions in server code
+grep -rn "health\|/ping\|/status" "$REPO_ROOT" \
+  --include="*.py" --include="*.ts" --include="*.tsx" --include="*.go" --include="*.rs" --include="*.rb" \
+  -l 2>/dev/null | head -10
+
+# Look for healthcheck patterns in compose/config files
+grep -rn "healthcheck\|HEALTH_URL\|health_endpoint\|/health" \
+  "$REPO_ROOT" --include="*.yml" --include="*.yaml" --include="*.env*" \
+  -l 2>/dev/null | head -5
 ```
 
+From the results, infer the most likely health endpoint path:
+- If a route like `GET /health` or `GET /ping` is found → use that path
+- If a docker-compose healthcheck URL is found → extract the host:port+path
+- If docker-compose has a `services.api` block → infer `http://localhost:<port>/health`
+
+If an endpoint can be inferred:
+```json
+{ "value": "https://api.<detected-or-inferred-host>/<path>", "confidence": "medium", "source": "<file where found>", "why": "Health route found at <file>:<line>" }
 ```
-Detected container name prefixes: {PREFIXES}
-Are these correct? Add/edit prefixes, or press Enter to accept:
+
+If no endpoint found:
+```json
+{ "value": "", "confidence": "low", "source": "codebase scan", "why": "No health route detected; set this to the URL of your API's health endpoint" }
 ```
 
----
+### 4B: Detect container names and service patterns
 
-## Phase 5: Write forge.yaml
-
-### 5A: Preserve required sections
-
-Read the current `forge.yaml` content. Extract the complete `project:`, `paths:`, and `branches:` blocks verbatim — they must not change.
-
-### 5B: Build optional section YAML
-
-For each optional section the user confirmed:
-
-**repos** (if satellites confirmed):
-```yaml
-repos:
-  default:
-    repo: "{OWNER}/{REPO}"
-    staging_branch: "{branches.staging}"
-  satellites:
-    - prefix: "{PREFIX}"
-      repo: "{OWNER}/{SATELLITE_REPO}"
-      staging_branch: "main"
-      local_path: "{REPO_ROOT}/../{SATELLITE_REPO}"
-```
-
-**project_board** (if board and field IDs found):
-```yaml
-project_board:
-  owner: "{OWNER}"
-  project_number: {PROJECT_NUMBER}
-  project_id: "{PROJECT_ID}"  # Must be a PVT_... node ID — obtain via: gh project list --owner <owner> --format json | jq '.projects[] | .id'
-  field_ids:
-    status: "{STATUS_FIELD_ID}"
-    lane: "{LANE_FIELD_ID}"
-    component: "{COMPONENT_FIELD_ID}"
-    priority: "{PRIORITY_FIELD_ID}"
-    workflow: "{WORKFLOW_FIELD_ID}"
-  option_ids:
-    status:
-      todo: "{TODO_OPTION_ID}"
-      in_progress: "{IN_PROGRESS_OPTION_ID}"
-      done: "{DONE_OPTION_ID}"
-    lane:
-      fast: "{FAST_OPTION_ID}"
-      feature: "{FEATURE_OPTION_ID}"
-    priority:
-      p0: "{P0_OPTION_ID}"
-      p1: "{P1_OPTION_ID}"
-      p2: "{P2_OPTION_ID}"
-      p3: "{P3_OPTION_ID}"
-    workflow:
-      investigating: "{INVESTIGATING_OPTION_ID}"
-      building: "{BUILDING_OPTION_ID}"
-      in_review: "{IN_REVIEW_OPTION_ID}"
-      merged: "{MERGED_OPTION_ID}"
-```
-
-**services** (if analytics/monitoring confirmed):
-```yaml
-services:
-  domain: "{ROOT_DOMAIN}"
-  api_url: "{API_URL}"
-  analytics:
-    # Only include subsections the user confirmed
-    umami:         # if selected
-      url: "{UMAMI_URL}"
-      website_id: "{UMAMI_WEBSITE_ID}"
-    clarity:       # if selected
-      project_id: "{CLARITY_PROJECT_ID}"
-    ga4:           # if selected
-      property_id: "{GA4_PROPERTY_ID}"
-```
-
-**review** (if tech stack or context provided):
-```yaml
-review:
-  tech_stack: "{TECH_STACK}"
-  context: |
-    {PROJECT_CONTEXT}
-```
-
-**verification** (if health endpoint or containers found):
-```yaml
-verification:
-  health_endpoint: "{HEALTH_ENDPOINT}"
-  health_patterns:
-    - '"status": "ok"'
-  internal_service_patterns:
-    - "{SERVICE_PREFIX}"
-```
-
-### 5C: Overwrite protection
-
-For each optional section that is ALREADY ACTIVE in forge.yaml (detected in Phase 1C):
-
-If `FORCE=false`:
-```
-forge.yaml already has an active {section}: section.
-Overwrite it with newly detected values? [y/N]
-```
-
-If user says N: keep existing content for that section.
-
-### 5D: Write the file
-
-Backup the existing file:
 ```bash
-cp "$FORGE_YAML" "${FORGE_YAML}.bak"
-echo "Backed up: forge.yaml → forge.yaml.bak"
+for f in "$REPO_ROOT"/docker-compose*.yml; do
+  [ -f "$f" ] || continue
+  grep -E "^\s+container_name:" "$f" | head -20
+done
 ```
 
-Write the complete new file: required sections (preserved verbatim) + active optional sections (newly generated) + inactive optional sections (left as commented-out blocks matching forge.yaml.example structure).
+Extract the common prefix from all container names (e.g., `acme-api`, `acme-worker` → prefix `acme-`).
 
-Print a summary of what was written:
+If container names are found:
+```json
+{ "value": "<prefix>", "confidence": "high", "source": "docker-compose.yml container_name entries", "why": "Containers named: <list>" }
 ```
-forge.yaml updated:
 
-  Required sections (preserved):
-    ✓ project
-    ✓ paths
-    ✓ branches
+If no docker-compose files found or no container_name entries:
+```json
+{ "value": "", "confidence": "low", "source": "codebase scan", "why": "No docker-compose container_name entries found; add your service name prefix here (e.g., 'acme-')" }
+```
 
-  Optional sections (filled):
-    ✓ repos          — 2 satellite(s) configured
-    ✓ project_board  — field IDs from project "Acme Board" (#1)
-    ✗ services       — skipped (no analytics services)
-    ✓ review         — tech stack + context
-    ✓ verification   — health endpoint configured
+### 4C: Build verification enrichment
 
-  Optional sections (skipped — still commented out):
-    - services
+```json
+"verification": {
+  "health_endpoint": { "value": "...", "confidence": "...", "source": "...", "why": "..." },
+  "health_patterns": [
+    { "value": "\"status\": \"ok\"", "confidence": "low", "source": "default", "why": "Standard ForgeDock health pattern; update if your API uses a different response shape" }
+  ],
+  "internal_service_patterns": [
+    { "value": "<prefix>", "confidence": "...", "source": "...", "why": "..." }
+  ]
+}
 ```
 
 ---
 
-## Phase 6: Validation
+## Phase 5: Assemble and Return Enriched ConfigDraft
 
-### 6A: Repo access
+### 5A: Merge enrichments into the draft
 
-```bash
-gh repo view "${OWNER}/${REPO}" --json name,url 2>/dev/null \
-  || echo "WARNING: Cannot access ${OWNER}/${REPO} — check project.owner and project.repo"
-```
+Start from the incoming `DRAFT`. Merge the enriched sections:
+- `DRAFT.project_board` = Phase 1 output (or low-confidence placeholder)
+- `DRAFT.repos` = Phase 2 output (or low-confidence placeholder)
+- `DRAFT.review` = Phase 3 output
+- `DRAFT.verification` = Phase 4 output
 
-### 6B: Path existence
+Never modify `DRAFT.project`, `DRAFT.paths`, `DRAFT.branches`, or `DRAFT.meta` — pass them through unchanged.
 
-```bash
-[ -d "$(grep 'root:' "$FORGE_YAML" | head -1 | awk '{print $2}' | tr -d '"')" ] \
-  && echo "✓ paths.root exists" \
-  || echo "WARNING: paths.root does not exist on this machine"
+### 5B: Add enrichment metadata
+
+Append to `DRAFT.meta`:
+
+```json
+{
+  "enriched": true,
+  "enrichment_backend": "skill",
+  "enriched_at": "<ISO 8601 timestamp>",
+  "enrichment_notes": ["<any skipped phases and reasons>"]
+}
 ```
 
-### 6C: Project board ID resolution
+### 5C: Return the enriched ConfigDraft
 
-`project_board.project_id` must be a GitHub Projects v2 node ID with the `PVT_` prefix (e.g. `PVT_kwHOxxxxxxxxxxxxxxxx`). This value is returned by `gh project list --owner <owner> --format json | jq '.projects[] | .id'`. A manually-edited `forge.yaml` with an incorrect value (e.g. a project number instead of a node ID) will produce a confusing GraphQL error — the format check below catches this before attempting the API call.
+Output the complete enriched ConfigDraft as a JSON blob on stdout. This is the skill's return value — the caller (CLI orchestrator or review-render) reads it from the output.
 
-```bash
-# Only run if project_board section was written
-if grep -q "^project_board:" "$FORGE_YAML"; then
-  PROJECT_ID=$(grep "project_id:" "$FORGE_YAML" | head -1 | awk '{print $2}' | tr -d '"')
-  # Validate PVT_ prefix before GraphQL call — any other format will produce a confusing API error
-  if [[ "$PROJECT_ID" != PVT_* ]]; then
-    echo "ERROR: project_board.project_id must start with 'PVT_' (got: '$PROJECT_ID')"
-    echo "  Expected format: PVT_kwHOxxxxxxxxxxxxxxxx"
-    echo "  Obtain the correct value with: gh project list --owner ${OWNER} --format json | jq '.projects[] | .id'"
-  else
-    gh api graphql -f query='query { node(id: "'"$PROJECT_ID"'") { id __typename } }' 2>/dev/null \
-      | jq -e '.data.node.id' > /dev/null \
-      && echo "✓ project_board.project_id resolves" \
-      || echo "WARNING: project_board.project_id may be invalid — verify with: gh project list --owner ${OWNER}"
-  fi
-fi
+```
+<ENRICHED_DRAFT_JSON>
 ```
 
-### 6D: Satellite repo access
+**Output format requirements**:
+- Single JSON object, pretty-printed (2-space indent)
+- All sections present (project, paths, branches, project_board, repos, review, verification, meta)
+- Every leaf is `{ value, confidence, source, why }` — no raw strings
+- No trailing prose after the JSON blob
 
-```bash
-# Only run if repos.satellites section was written
-if grep -q "^repos:" "$FORGE_YAML"; then
-  # Extract satellite repo names and verify each is accessible
-  grep -A 20 "^repos:" "$FORGE_YAML" | grep "repo:" | tail -n +2 | while read -r line; do
-    SAT_REPO=$(echo "$line" | awk '{print $2}' | tr -d '"')
-    gh repo view "$SAT_REPO" --json name 2>/dev/null \
-      && echo "✓ satellite repo ${SAT_REPO} accessible" \
-      || echo "WARNING: satellite repo ${SAT_REPO} not accessible — check prefix and repo name"
-  done
-fi
-```
+---
+
+## Enrichment Summary (informational)
 
-### 6E: Final report
+After the JSON output, print a human-readable enrichment summary for the operator's benefit. This is NOT part of the machine-readable output — it is separated by a `---` divider:
 
 ```
-forge.yaml is ready.
+---
+## Enrichment Summary
 
-Validation results:
-  {validation output from 6A–6D}
+Sections enriched:
+  project_board  — <high|medium|low: brief note>
+  repos          — <N satellite candidates found | skipped>
+  review         — tech_stack=<value>, context from <source>
+  verification   — health_endpoint=<value | not found>, <N> container patterns
 
-Next steps:
-  1. If forge.yaml contains sensitive paths (credentials file, local paths):
-       echo "forge.yaml" >> .gitignore
-  2. Test the pipeline:
-       /work-on next
-  3. If any WARNING appeared above, edit forge.yaml to fix the flagged values.
-  4. Backup file: forge.yaml.bak (delete when satisfied)
+Skipped:
+  <phase> — <reason>
 
-ForgeDock commands now use your project's config from forge.yaml.
+Low-confidence fields (will appear as TODO flags in forge.yaml):
+  <list of field paths with low confidence and their why>
 ```