forgedock 1.0.7 → 1.0.9

package/docs/superpowers/specs/2026-06-09-intelligent-onboarding-design.md

@@ -0,0 +1,172 @@
+# Intelligent, Idiot-Proof Onboarding — Design Spec
+
+**Date:** 2026-06-09
+**Status:** Approved (design); pending implementation plan
+**Scope:** One milestone, four phases
+
+## Problem
+
+Today's onboarding (`npx forgedock` TUI + `forgedock init` + the `forgedock-init`
+skill) works but asks the first-time user ~12 questions across project / paths /
+branches / optional sections, with little explanation of *why* each is asked or
+*what* a good answer looks like. The deterministic auto-detect is decent, but the
+genuinely hard sections (project board field mapping, satellites, review context,
+verification endpoints) still fall back to manual prompts. There is no per-directory
+control: ForgeDock commands install globally and there is no notion of "activate
+here / stay silent there."
+
+We want onboarding to be **intelligent** (AI fills the config), **idiot-proof**
+(near-zero questions, everything explained), and **scoped** (a Claude Code hook
+that activates ForgeDock only in directories the user has opted into).
+
+## Vision
+
+Open `claude` in any repo → a SessionStart hook resolves the directory's ForgeDock
+state → if managed and active and unconfigured, an AI agent infers the **entire**
+`forge.yaml` from the codebase + GitHub → the user reviews **one annotated screen**
+and presses Enter. No wizard. Per-directory enable/disable means ForgeDock only
+wakes up where wanted.
+
+## Architecture — three pillars
+
+### Pillar A — Autopilot config generation (the "intelligence")
+
+Layered backends behind **one interface** so the experience degrades gracefully
+(the chosen "hybrid" model):
+
+- **`init-detect`** — deterministic, no AI. Refactors today's git / tech-stack /
+  board detection into a pure module that returns a `ConfigDraft` plus a
+  **confidence score per field** (`high` = verified from a concrete source,
+  `medium` = inferred, `low` = guessed default).
+- **`init-enrich`** — AI enrichment. Consumes a `ConfigDraft`, deeply infers the
+  hard sections, and raises confidences. Two interchangeable backends sharing one
+  contract:
+  - **skill backend** — runs inside Claude Code; no API key; uses existing CC auth.
+    *Primary path.*
+  - **api backend** — the CLI calls the Anthropic API directly with a BYO
+    `ANTHROPIC_API_KEY`. *Used when Claude Code is not present.*
+- **`review-render`** — a single annotated review screen. Every field is shown with
+  its **source**, **confidence**, and a plain-language "why this value." Enter to
+  accept all; inline-edit to change any field. **Unknowable items get a sensible
+  default plus an inline `# TODO(forgedock:<field>)` flag in the YAML — never a
+  blocking prompt.**
+
+**Backend selection logic:**
+1. Always run `init-detect` to produce the baseline draft.
+2. If running inside Claude Code → `init-enrich` via **skill** backend.
+3. Else if `ANTHROPIC_API_KEY` present → `init-enrich` via **api** backend.
+4. Else → skip enrichment; render the deterministic baseline (today's quality, but
+   through the new annotated review screen).
+
+### Pillar B — Claude Code hook + per-directory toggle
+
+- **SessionStart hook**, installed into `~/.claude/settings.json` by
+  `forgedock install`. On each CC session it resolves the cwd's state and acts:
+  - **managed + active** → inject ForgeDock context (a `forge.yaml` summary +
+    available commands); if config is missing or stale, offer a one-shot autopilot
+    init.
+  - **managed + opted-out** → completely silent (no output, no context injection).
+  - **unmanaged** → an optional, one-time, suppressible "Enable ForgeDock here?"
+    nudge.
+- **State model** ("marker + global opt-out"):
+  - A directory is **managed** iff it contains `forge.yaml` **or** a lightweight
+    `.forgedock` marker (lets a project signal "ForgeDock-managed" before a full
+    config exists).
+  - A central `~/.claude/forgedock/registry.json` tracks explicit **per-directory
+    opt-out** plus last-seen metadata. Opt-out wins over the marker.
+- **New CLI commands:** `forgedock enable [dir]`, `forgedock disable [dir]`,
+  `forgedock status [dir]`.
+- **Known constraint (explicit, accepted):** Claude Code slash-commands install
+  **globally**, so "disable per dir" means the **hook stays silent and injects
+  nothing** in that directory — it does not physically remove or hide the global
+  commands. This is the achievable and intended semantics.
+
+### Pillar C — Idiot-proofing (cross-cutting)
+
+- **Self-healing `validate`** — on a validation failure, the AI proposes (and, with
+  confirmation, applies) the fix instead of only printing an error.
+- **Actionable preflight** — failures (`gh` missing, not authed, Node too old) show
+  copy-paste fix commands (partially exists today; standardize it).
+- **Escape hatch** — `--manual` / `--verbose` runs the full guided wizard for power
+  users who *want* every prompt.
+
+## Components & interfaces (designed for isolation)
+
+| Unit | Purpose | Depends on | Testable in isolation? |
+|------|---------|-----------|------------------------|
+| `init-detect` | Pure baseline `ConfigDraft` + per-field confidence | git, fs (read-only) | Yes — fixture repos → expected draft |
+| `init-enrich` (skill) | AI enrichment inside CC | CC session, draft contract | Contract test + recorded fixture |
+| `init-enrich` (api) | AI enrichment via Anthropic API | `ANTHROPIC_API_KEY`, draft contract | Contract test against same interface |
+| `review-render` | Annotated review/accept/edit TUI | draft + confidence, tui.mjs | Yes — render snapshot from a draft |
+| `registry` | Resolve dir state; read/write opt-out + markers | fs | Yes — state-resolution matrix |
+| `session-hook` | Thin SessionStart script; emits context JSON | registry | Yes — simulated SessionStart payloads |
+
+**`ConfigDraft` contract** (shared by detect → enrich → render): a structured
+object mirroring `forge.yaml` sections, where each leaf is `{ value, confidence,
+source, why }`. This is the single seam that lets the three enrichment backends and
+the renderer stay decoupled.
+
+## Data flow (autopilot happy path)
+
+```
+open `claude` in repo
+  → SessionStart hook fires
+  → registry resolves: managed (forge.yaml absent) + active
+  → hook suggests autopilot init  (or user runs `forgedock init`)
+  → init-detect            → baseline ConfigDraft + confidences
+  → init-enrich (skill)    → enriched ConfigDraft
+  → review-render          → annotated screen → Enter to accept
+  → write forge.yaml (with any # TODO(forgedock:…) flags)
+  → validate (self-healing on failure)
+```
+
+## Error handling
+
+- **No git remote / detached repo:** `init-detect` lowers confidence, leaves fields
+  as `low`-confidence defaults with TODO flags; never crashes.
+- **`gh` unauthenticated:** GitHub-derived sections (board, satellites) are skipped
+  with a flagged TODO and a copy-paste `gh auth login` hint.
+- **Enrichment backend unavailable / API error:** fall through the backend-selection
+  ladder; worst case is the deterministic baseline through the review screen.
+- **`forge.yaml` already exists:** existing backup-and-overwrite behavior is
+  preserved; review screen shows a diff-style "changed vs current."
+- **Registry file missing/corrupt:** treat as empty opt-out set; the hook fails open
+  to silent (never blocks a CC session).
+
+## Testing strategy
+
+- **`registry`:** unit-test the full state matrix — managed/unmanaged × opted-in/out
+  × `forge.yaml` present/absent.
+- **`init-detect`:** fixture repos (node, python, rust, multi-repo) → expected
+  `ConfigDraft` snapshots.
+- **`session-hook`:** feed simulated SessionStart payloads; assert silent vs
+  context-injecting vs nudge output.
+- **`init-enrich`:** test the `ConfigDraft` contract both backends must satisfy;
+  pin one recorded enrichment fixture for regression.
+- **`review-render`:** snapshot the annotated screen from a known draft.
+
+## Phasing (milestone → issues)
+
+1. **Foundation** — `registry` module + `enable`/`disable`/`status` commands +
+   marker handling. Unblocks the hook.
+2. **Hook** — SessionStart hook install into `settings.json` + context injection +
+   opt-out respect + unmanaged nudge.
+3. **Autopilot brain** — `init-detect` refactor (`ConfigDraft` + confidence) →
+   `init-enrich` skill upgrade → annotated `review-render` screen.
+4. **Resilience** — BYO-key `api` enrichment backend + self-healing `validate` +
+   `--manual` escape hatch.
+
+All four phases ship in **one milestone**.
+
+## Out of scope / non-goals
+
+- Physically hiding global slash-commands per directory (see Pillar B constraint).
+- A standalone web onboarding UI.
+- Multi-user / team-shared registries (registry is per-machine, user-level).
+
+## Open questions
+
+- Exact confidence thresholds that trigger a TODO flag vs a silent default
+  (tune during Phase 3).
+- Whether the unmanaged-directory nudge defaults to on or off (lean: off, opt-in via
+  a global setting) — decide in Phase 2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -33,6 +33,7 @@
   },
   "files": [
     "bin/",
+    "!bin/tests/",
     "commands/",
     "docs/",
     "scripts/",
@@ -40,6 +41,9 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --test \"bin/tests/**/*.test.mjs\""
+  },
   "engines": {
     "node": ">=18"
   }

package/scripts/verify-route-registration.sh

@@ -49,27 +49,53 @@ WARNINGS=0
 
 # --- Next.js Route Handler registration check ---
 while read -r f; do
-    URL_PATH=$(echo "$f" | sed "s|^${FORGE_PAGES_ROOT}||; s|/route\\.ts\$||; s|\\[.*\\]|*|g")
+    # Use shell parameter expansion instead of sed to avoid interpreting FORGE_PAGES_ROOT
+    # as a sed pattern (values containing | or other metacharacters break the substitution).
+    stripped="${f#${FORGE_PAGES_ROOT}/}"
+    stripped="${stripped%/route.ts}"
+    # Replace dynamic segments [param] with * using a loop (no regex needed)
+    URL_PATH=""
+    IFS='/' read -ra SEGMENTS <<< "$stripped"
+    for seg in "${SEGMENTS[@]}"; do
+        case "$seg" in
+            \[*\]) URL_PATH="${URL_PATH}/*" ;;
+            *)     URL_PATH="${URL_PATH}/${seg}" ;;
+        esac
+    done
     ROUTE_SEGMENT=$(echo "$URL_PATH" | sed 's|/api/v1/||; s|/.*||')
 
-    # Check if next.config.js has a rewrite that might shadow this route
-    if [ -f "$REPO_ROOT/web/next.config.js" ]; then
-        if grep -q "$ROUTE_SEGMENT" "$REPO_ROOT/web/next.config.js" 2>/dev/null; then
-            echo "WARNING: Route handler $f ($URL_PATH) — next.config.js references '$ROUTE_SEGMENT', may shadow this route"
-            WARNINGS=$((WARNINGS + 1))
-        else
-            echo "OK: Route handler $f ($URL_PATH) — no shadowing rewrites found in next.config.js"
+    # Guard: skip shadow checks when ROUTE_SEGMENT is empty (e.g. /api/ root handlers).
+    # An empty ROUTE_SEGMENT causes grep -qF "" to match every line — false-positive WARNINGs.
+    if [ -z "$ROUTE_SEGMENT" ]; then
+        echo "OK: Route handler $f ($URL_PATH) — root handler, no segment to match, skipping shadow checks"
+    else
+        # Check if next.config.js has a rewrite that might shadow this route
+        if [ -f "$REPO_ROOT/web/next.config.js" ]; then
+            # Use -F (fixed string) so ROUTE_SEGMENT is not interpreted as a regex pattern
+            if grep -qF "$ROUTE_SEGMENT" "$REPO_ROOT/web/next.config.js" 2>/dev/null; then
+                echo "WARNING: Route handler $f ($URL_PATH) — next.config.js references '$ROUTE_SEGMENT', may shadow this route"
+                WARNINGS=$((WARNINGS + 1))
+            else
+                echo "OK: Route handler $f ($URL_PATH) — no shadowing rewrites found in next.config.js"
+            fi
         fi
-    fi
 
-    # Check if nginx routes this path to Next.js or directly to backend
-    if [ -f "$REPO_ROOT/infra/nginx/nginx.conf" ]; then
-        if grep -q "location.*$ROUTE_SEGMENT" "$REPO_ROOT/infra/nginx/nginx.conf" 2>/dev/null; then
-            echo "WARNING: Route handler $f ($URL_PATH) — nginx.conf has a location block for '$ROUTE_SEGMENT', may bypass Next.js"
-            WARNINGS=$((WARNINGS + 1))
+        # Check if nginx routes this path to Next.js or directly to backend
+        if [ -f "$REPO_ROOT/infra/nginx/nginx.conf" ]; then
+            # Check for location blocks mentioning ROUTE_SEGMENT — use two -F searches to avoid
+            # embedding the variable in a regex: first find lines with "location", then filter
+            # for the literal segment. This avoids ROUTE_SEGMENT being interpreted as a BRE.
+            if grep -F "location" "$REPO_ROOT/infra/nginx/nginx.conf" 2>/dev/null | grep -qF "$ROUTE_SEGMENT"; then
+                echo "WARNING: Route handler $f ($URL_PATH) — nginx.conf has a location block for '$ROUTE_SEGMENT', may bypass Next.js"
+                WARNINGS=$((WARNINGS + 1))
+            fi
         fi
     fi
-done < <(echo "$FILES" | grep -E "^${FORGE_PAGES_ROOT}/api/.*route\\.ts$") || true
+done < <(echo "$FILES" | while IFS= read -r line; do
+    case "$line" in
+        "${FORGE_PAGES_ROOT}/api/"*"route.ts") echo "$line" ;;
+    esac
+done) || true
 
 # --- Python API Router registration check ---
 while read -r f; do
@@ -77,7 +103,8 @@ while read -r f; do
     MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
-        if grep -q "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
+        # Use -F (fixed string) so ROUTER_NAME is not interpreted as a regex pattern
+        if grep -qF "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
             echo "OK: API Router '$ROUTER_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
             echo "BLOCKING: API Router '$ROUTER_NAME' ($f) — NOT found in $(basename "$MAIN_PY"). Router will not be reachable."
@@ -95,7 +122,8 @@ while read -r f; do
     MAIN_PY="$REPO_ROOT/${FORGE_API_MAIN}"
 
     if [ -f "$MAIN_PY" ]; then
-        if grep -q "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
+        # Use -F (fixed string) so MIDDLEWARE_NAME is not interpreted as a regex pattern
+        if grep -qF "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
             echo "OK: Middleware '$MIDDLEWARE_NAME' ($f) — registered in $(basename "$MAIN_PY")"
         else
             echo "WARNING: Middleware '$MIDDLEWARE_NAME' ($f) — not found in $(basename "$MAIN_PY"). May not be active."
@@ -108,7 +136,8 @@ done < <(echo "$FILES" | grep -E "^${FORGE_API_MIDDLEWARE_DIR}/.*\\.py$") || tru
 while read -r f; do
     MODULE_NAME=$(basename "$f" .py)
 
-    IMPORTERS=$(grep -rl "$MODULE_NAME" "$REPO_ROOT/${FORGE_API_SERVICES_DIR}/" "$REPO_ROOT/${FORGE_WORKER_DIR}/" 2>/dev/null | head -5)
+    # Use -F (fixed string) so MODULE_NAME is not interpreted as a regex pattern
+    IMPORTERS=$(grep -rlF "$MODULE_NAME" "$REPO_ROOT/${FORGE_API_SERVICES_DIR}/" "$REPO_ROOT/${FORGE_WORKER_DIR}/" 2>/dev/null | head -5)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Shared module '$MODULE_NAME' ($f) — imported by services"
     else
@@ -121,7 +150,9 @@ done < <(echo "$FILES" | grep -E "^shared/.*\.py$") || true
 while read -r f; do
     COMPONENT_NAME=$(basename "$f" .tsx)
 
-    IMPORTERS=$(grep -rl "$COMPONENT_NAME" "$REPO_ROOT/${FORGE_PAGES_ROOT}/" "$REPO_ROOT/${FORGE_COMPONENTS_DIR}/" 2>/dev/null | grep -v "$f" | head -3)
+    # Use -F (fixed string) for both the component name search and the self-exclusion
+    # to prevent file paths and component names from being interpreted as regex patterns
+    IMPORTERS=$(grep -rlF "$COMPONENT_NAME" "$REPO_ROOT/${FORGE_PAGES_ROOT}/" "$REPO_ROOT/${FORGE_COMPONENTS_DIR}/" 2>/dev/null | grep -vF "$f" | head -3)
     if [ -n "$IMPORTERS" ]; then
         echo "OK: Component '$COMPONENT_NAME' ($f) — imported by other files"
     else

package/scripts/verify-sops-chain.sh

@@ -80,7 +80,9 @@ if [ -n "$NEW_MAPPINGS" ]; then
 
     # For each new mapping, verify the SOPS path structure exists
     # (We can't decrypt SOPS to verify values, but we can check the mapping format is valid)
-    echo "$NEW_MAPPINGS" | while IFS= read -r mapping; do
+    # Use process substitution instead of a pipe so WARNINGS increments persist in the parent shell.
+    # (echo ... | while read creates a subshell — counter changes are lost on subshell exit.)
+    while IFS= read -r mapping; do
         VAR_NAME=$(echo "$mapping" | grep -oE '^"[A-Z_]+"' | tr -d '"')
         SOPS_SECTION=$(echo "$mapping" | grep -oE '\("([a-z_]+)"' | head -1 | tr -d '("')
         SOPS_KEY=$(echo "$mapping" | grep -oE ', "([a-z_]+)"\)' | tr -d ', ")')
@@ -91,7 +93,7 @@ if [ -n "$NEW_MAPPINGS" ]; then
             echo "WARNING: Malformed ENV_MAPPING entry: $mapping"
             WARNINGS=$((WARNINGS + 1))
         fi
-    done
+    done < <(echo "$NEW_MAPPINGS")
 else
     echo "OK: No new ENV_MAPPING entries in diff"
 fi