forgedock 1.0.8 → 1.0.9

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.

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.8",
+  "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

@@ -64,25 +64,31 @@ while read -r f; do
     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
-        # 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"
+    # 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
-        # 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))
+        # 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" | while IFS= read -r line; do