forgedock 1.0.22 → 1.1.1

package/commands/work-on.md

@@ -835,7 +835,17 @@ esac
 
 <!-- FORGE:PHASE_COMPLETE — Entering Phase 3 (Build). See Universal Phase Dispatcher: sub-phases 3A–3M execute in sequence. No sub-phase completion is terminal. -->
 
-**Skip if**: `<!-- FORGE:BUILDER -->` exists.
+**Skip if**: `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment. <!-- Added: forge#1305 — require completion marker, not mere presence of BUILDER annotation -->
+
+**Partial build detection**: If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → the build was interrupted after implement.md Phase I6 (comment posted) but before validate.md Phase V5 (commit). Delete the partial comment and restart Phase 3 from the top: <!-- Added: forge#1305 -->
+```bash
+PARTIAL_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
+if [ -n "$PARTIAL_ID" ]; then
+  gh api repos/{GH_REPO}/issues/comments/$PARTIAL_ID -X DELETE
+  echo "Deleted partial FORGE:BUILDER comment (no FORGE:BUILDER:COMPLETE) — restarting build"
+fi
+```
 
 **CRITICAL: You MUST execute ALL sub-phases 3A–3M in order. Sub-phases 3C.5 (context) and 3C.6 (architect) are skipped ONLY for TRIVIAL tasks and Investigation tasks — see Phase 3B for classification. For STANDARD and COMPLEX tasks they post mandatory `FORGE:CONTEXT` and `FORGE:ARCHITECT` comments that Phase 3F reads as its primary input. Skipping them without a TRIVIAL/Investigation classification degrades build quality and causes review findings. After each sub-phase, continue to the next — no sub-phase is terminal.**
 
@@ -857,9 +867,9 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 
-# Check if build already completed
+# Check if build already completed (require FORGE:BUILDER:COMPLETE — not just FORGE:BUILDER)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER:COMPLETE")) | .body'
 
 # Check for existing COMPLEXITY_BAND from a prior run (resume path)
 EXISTING_FAST_PATH=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
@@ -1181,6 +1191,14 @@ esac
 **Determine source branch**:
 - Review-finding → parse `**Code branch**: \`{branch}\`` from issue body; branch from `origin/{branch}`
   - **Milestone review-finding hybrid lane** (Code branch matches `milestone/*`): High-risk lane. NEVER use `git merge` to resolve conflicts — use `git rebase` or `git cherry-pick` only. If conflicts can't be resolved without merge, post comment, add `needs-human`, STOP.
+  - **Missing ref fallback**: After parsing, verify the Code branch still exists on remote. If not (e.g., the source PR's head branch was deleted post-merge before a corrected stamp took effect), fall back to `PR_BASE` (the lane default) and note the fallback:
+    ```bash
+    SOURCE_BRANCH="{CODE_BRANCH_FROM_ISSUE_BODY}"
+    if ! git ls-remote --exit-code origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      echo "WARNING: Code branch '$SOURCE_BRANCH' not found on remote — falling back to PR_BASE '$PR_BASE'"
+      SOURCE_BRANCH="$PR_BASE"
+    fi
+    ```
 - Feature lane (has milestone) → branch from `origin/{PR_BASE}` (PR_BASE now set above)
 - Fast lane (no milestone) → branch from `origin/{PR_BASE}` (PR_BASE = `{STAGING_BRANCH}`)
 
@@ -1289,6 +1307,11 @@ if iteration == max_iterations AND not PASS:
 
 All tool commands are read from `forge.yaml → verification.commands`. When a key is absent, the step logs `SKIPPED — not configured in verification.commands` and continues rather than silently passing.
 
+**Track skipped checks** — initialize before any check runs:
+```bash
+VERIFICATION_SKIPPED_CHECKS=""
+```
+
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
@@ -1298,6 +1321,7 @@ if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
     echo "SKIPPED — python.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }python.format"
 fi
 
 # Compile check always runs (no config needed — catches syntax errors)
@@ -1317,6 +1341,7 @@ if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1
 else
     echo "SKIPPED — typescript.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.format"
 fi
 
 if [ -n "$TS_TYPECHECK" ]; then
@@ -1327,6 +1352,7 @@ elif [ -n "$TS_BUILD" ]; then
     TS_EXIT=$?
 else
     echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.typecheck/build"
     TS_EXIT=0
 fi
 ```
@@ -1468,12 +1494,20 @@ Check off completed items, mark phases complete, add PR references.
 
 ### 3M: Post implementation comment
 ```bash
+# Compute verification status from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_STATUS="✅ All configured verification commands passed"
+else
+  VERIFICATION_STATUS="⚠ Verification NOT run: ${VERIFICATION_SKIPPED_CHECKS} — verification.commands not configured for these checks"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 ## Implementation Complete
 
 **Branch**: \`{BRANCH}\`
 **Commits**: {COMMIT_SHA(S)}
 **Files changed**: {COUNT}
+**Verification Status**: ${VERIFICATION_STATUS}
 
 ### Approach
 {what was built, key decisions}
@@ -1887,6 +1921,13 @@ This check is **audit-only** — it annotates the trajectory for visibility. It
 Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table:
 
 ```bash
+# Compute verification row from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_ROW="✅ Ran"
+else
+  VERIFICATION_ROW="⚠ Skipped — verification.commands not configured for: ${VERIFICATION_SKIPPED_CHECKS}"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 ## Pipeline Trajectory — #{NUMBER}
 
@@ -1897,6 +1938,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 | Phase 2: Decomposition | ⏭ Skipped | {reason} |
 | Phase 3: Build | ✅ Complete | Branch: \`{BRANCH}\` |
 | Phase 3G: Quality Gate | ✅ Gate passed | {iterations} iterations |
+| Phase 3H: Verification | ${VERIFICATION_ROW} | |
 | Phase 4–5: Review + PR | {REVIEW_ROW} | PR #{PR_NUMBER} → \`{PR_BASE}\` |
 | Phase 6: Close | ✅ Complete | Issue closed |
 

package/docs/BRAND.md

@@ -6,7 +6,10 @@ Status of reserved and blocked brand handles across platforms.
 
 | Domain | Status |
 |--------|--------|
-| `forgedock.dev` | **Owned** — canonical marketing and App URL |
+| `forgedock.dev` | **Unverified** — live content (2026-07-04) is a third-party product unrelated to ForgeDock; registrar verification pending. Do not use as a public-facing link until resolved. |
+| `forgedock.io` | **Parked** — Porkbun parked page, HTTP-only (HTTPS does not connect). Not controlled by RapierCraft Studios. Do not use as a public-facing link. |
+
+> **Rule**: No public ForgeDock surface (npm homepage, repo description, plugin manifests, docs) may point at a domain until its live content is verified as controlled by RapierCraft Studios.
 
 ## npm
 
@@ -45,7 +48,8 @@ Social handle registration is an operational task. Reserve handles before public
 
 | Platform | Action |
 |----------|--------|
-| Domain | Done |
+| Domain (forgedock.dev) | Unverified — registrar check pending; do not use as live surface |
+| Domain (forgedock.io) | Parked — not controlled by RapierCraft Studios; do not use as live surface |
 | npm | Done |
 | GitHub org slug | Blocked — use variant for App slug |
 | Social handles | Reserve before L1 public launch |

package/docs/CONFIG.md

@@ -12,18 +12,26 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 
 ---
 
-## CLI Flags for `init`
+## CLI Flags
 
-`npx forgedock init` accepts two optional flags that change how configuration is generated:
+`--verbose` and `--fast` apply to both `npx forgedock` (the full install journey) and `npx forgedock init` (config-only regeneration); `--manual` and `--minimal` apply to `init` only:
 
 | 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`). |
+| `--manual` | `npx forgedock init` only. Skips the annotated review screen and asks plain, one-field-at-a-time prompts instead, pre-filled with the detected values as defaults. |
+| `--minimal` | `npx forgedock init` only. Skips detection enrichment and the review screen entirely, and writes a short `forge.yaml` containing only the three required sections (`project`, `paths`, `branches`) with detected values. |
+| `--verbose` | Shows each field's detection source and confidence rationale on the review screen (e.g. `git remote`, `package.json`, `gh api`), instead of only flagging low-confidence fields. |
+| `--fast` | Skips the animation/motion frames and jumps straight to the static screens. |
 
-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.
+**Environment variables:**
 
-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.
+| Variable | Behavior |
+|----------|----------|
+| `FORGE_NO_MOTION=1` | Same effect as `--fast` — disables animation frames. Color is unaffected. |
+| `NO_COLOR=1` | Disables ANSI color output only. Motion is unaffected (monochrome choreography). |
+| Non-TTY / piped output (or `CI=1`) | Plain sequential log: no color **and** no animation. |
+
+The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can (when an API key is available), and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
 
 ---
 
@@ -686,46 +694,43 @@ Downstream consumers read `field.value` for the raw value and `field.confidence`
 
 ---
 
-## CLAUDE.md Integration
+## SessionStart Hook 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.
+ForgeDock does **not** write anything into your project's `CLAUDE.md` or `AGENTS.md`. Instead, `npx forgedock` registers a `SessionStart` hook in `~/.claude/settings.json` — a small script that runs at the start of every Claude Code session and prints ForgeDock's context straight to that session, without touching any file in your repo.
 
 ### How It Works
 
-Running `npx forgedock init` or `npx forgedock integrate` writes a marker-bounded block into `CLAUDE.md`:
-
-```
-<!-- BEGIN FORGEDOCK -->
-## ForgeDock — Autonomous Development Pipeline
-...command index and conventions...
-<!-- END FORGEDOCK -->
-```
+The hook resolves the current directory's state and reacts accordingly:
 
-The block is **idempotent** — re-running replaces only the managed section and leaves all other `CLAUDE.md` content untouched. If `CLAUDE.md` does not exist, it is created.
+| State | Behavior |
+|-------|----------|
+| `managed-active` (`forge.yaml` present, not opted out) | Prints a summary of `forge.yaml` (project, repo, branches) plus the available pipeline commands |
+| `managed-active`, no `forge.yaml` yet | Suggests running `npx forgedock init` |
+| `managed-optedout` | Completely silent — no output |
+| `unmanaged` | Prints a one-time, suppressible nudge to run `npx forgedock enable` |
 
-If `AGENTS.md` already exists in the project root, the same block is mirrored into it.
+The hook entry is registered idempotently: re-installing (`npx forgedock update`) will not duplicate it, and unrelated hooks or settings in `~/.claude/settings.json` are left untouched. If `settings.json` is malformed, the installer skips writing rather than risk corrupting it.
 
 ### Commands
 
 | Command | Action |
 |---------|--------|
-| `npx forgedock init` | Generates `forge.yaml` **and** injects the CLAUDE.md block |
-| `npx forgedock integrate` | Injects/refreshes the block without modifying `forge.yaml` |
+| `npx forgedock` / `npx forgedock install` | Registers the SessionStart hook (along with installing commands and writing `forge.yaml`) |
+| `npx forgedock update` | Re-registers the hook (relink only — does not touch `forge.yaml`) |
+| `npx forgedock uninstall` | Removes the hook entry from `settings.json` |
 
 ### Opting Out
 
-To prevent ForgeDock from managing the block, remove the `<!-- BEGIN FORGEDOCK -->` / `<!-- END FORGEDOCK -->` markers from `CLAUDE.md`. Without the markers, subsequent runs will append a new block rather than replacing one — so if you want to opt out permanently, delete or omit the markers **and** do not run `integrate` again.
-
-Alternatively, keep the markers but edit the content between them freely — ForgeDock will replace that section on the next run, so any manual edits inside the markers will be overwritten.
-
-### Re-generating
-
-The command index inside the block is auto-generated from the `description:` frontmatter in each `commands/*.md` file. To refresh it after a ForgeDock update:
+Per-directory, independent of the global hook registration. Each command acts on the current working directory — run it inside the project directory:
 
 ```bash
-npx forgedock integrate
+npx forgedock disable  # the current directory goes silent (managed-optedout)
+npx forgedock enable   # re-activate the current directory
+npx forgedock status   # show the current directory's resolved state
 ```
 
+See [Per-Directory State Registry](#per-directory-state-registry) below for how opt-out state is tracked.
+
 ---
 
 ## Per-Directory State Registry
@@ -788,22 +793,22 @@ If you downgrade to a build older than PR #467 **and** your project is accessed
 - The one-time "Enable ForgeDock here?" nudge may reappear once.
 - No data is lost. No crash. Fail-open behaviour holds throughout.
 
-**Recovery**: after downgrading, re-apply your opt-out with the older build:
+**Recovery**: after downgrading, re-apply your opt-out with the older build (run inside the project directory):
 
 ```bash
-npx forgedock disable [dir]
+npx forgedock disable
 ```
 
 This re-writes the entry under the key form the older build expects.
 
 ### Managing Opt-Out State
 
-Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set:
+Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set. Each command acts on the current working directory by default — run it inside the project directory, or pass an explicit path:
 
 ```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
+npx forgedock enable [dir]   # Remove a directory from the opt-out set (default: cwd)
+npx forgedock disable [dir]  # Add a directory to the opt-out set (default: cwd)
+npx forgedock status [dir]   # Show a directory's resolved state (default: cwd)
 ```
 
 ---

package/docs/site/.vitepress/config.mjs

@@ -0,0 +1,85 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'ForgeDock',
+  description: 'Autonomous AI development pipeline that uses GitHub as a structured knowledge graph for Claude Code agents.',
+  lang: 'en-US',
+
+  // Deploy to GitHub Pages at /
+  base: '/',
+
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#7C3AED' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:site_name', content: 'ForgeDock' }],
+  ],
+
+  themeConfig: {
+    logo: 'https://avatars.githubusercontent.com/in/3731547?s=40',
+    siteTitle: 'ForgeDock',
+
+    nav: [
+      { text: 'Quick Start', link: '/getting-started' },
+      { text: 'Commands', link: '/command-reference' },
+      { text: 'Annotations', link: '/annotations-explained' },
+      {
+        text: 'GitHub',
+        link: 'https://github.com/RapierCraftStudios/ForgeDock',
+      },
+    ],
+
+    sidebar: [
+      {
+        text: 'Get Started',
+        items: [
+          { text: 'Quick Start', link: '/getting-started' },
+          { text: 'How It Works', link: '/how-it-works' },
+          { text: 'Troubleshooting', link: '/troubleshooting' },
+        ],
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'Command Reference', link: '/command-reference' },
+          { text: 'Command Learning Path', link: '/command-learning-path' },
+          { text: 'FORGE Annotation Protocol', link: '/forge-annotation-protocol' },
+          { text: 'Annotations Explained', link: '/annotations-explained' },
+        ],
+      },
+      {
+        text: 'Guides',
+        items: [
+          { text: 'ForgeDock vs. Manual Workflows', link: '/vs-manual-workflows' },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/RapierCraftStudios/ForgeDock' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/forgedock' },
+    ],
+
+    footer: {
+      message: 'Released under the AGPL-3.0 License.',
+      copyright: 'Copyright © 2024–2026 RapierCraft Studios',
+    },
+
+    editLink: {
+      pattern: 'https://github.com/RapierCraftStudios/ForgeDock/edit/main/docs/site/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    search: {
+      provider: 'local',
+    },
+
+    outline: {
+      level: [2, 3],
+    },
+  },
+
+  markdown: {
+    lineNumbers: false,
+  },
+})

package/docs/site/getting-started.md

@@ -71,24 +71,31 @@ ForgeDock Doctor — Installation Health Check
   All checks passed. ForgeDock installation is healthy.
 ```
 
-It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI. The `forge.yaml` and GitHub-label checks will fully pass once you finish Step 2 below — re-run `doctor` any time your setup feels off.
+It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI.
 
 > Prefer a quick spot-check? `ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`.
 
 ---
 
-## Step 2: Configure Your Repository
+## Step 2: Your Config Is Already There
 
-ForgeDock reads a single `forge.yaml` in your project root. **Start minimal** — only the `project`, `paths`, and `branches` sections are required. Everything else is optional and falls back to sensible defaults; add sections as you need them.
-
-The fastest way to get a working config is the `--minimal` flag, which scans your repo and writes just the required sections with detected values:
+`npx forgedock` in Step 1 ran the full install journey — including repo detection and a reviewed `forge.yaml` — so there's no separate config step to run. If you need to redo detection later (moved the repo, renamed a branch), or want a leaner config with just the required sections, re-run:
 
 ```bash
 cd /path/to/your/project
 npx forgedock init --minimal
 ```
 
-This produces a short, readable `forge.yaml` like the one below — this is essentially ForgeDock's own real-world config:
+**Optional: enrich the config.** Once `forge.yaml` exists, open Claude Code in your project directory and run `/forgedock-init` to fill in the optional sections that plain detection can't infer:
+
+- Project board connection (GitHub Projects v2)
+- Satellite repo routing (multi-repo setups)
+- Review context (tech stack, known pitfalls)
+- Service URLs for health checks
+
+`/forgedock-init` completes an existing `forge.yaml` — it won't create one from scratch.
+
+**Minimal `forge.yaml` example:**
 
 ```yaml
 project:
@@ -110,7 +117,7 @@ That's the whole config. Run `npx forgedock doctor` to confirm it's valid.
 
 > **The three required sections are `project`, `paths`, and `branches`** — `npx forgedock init --minimal` auto-detects `paths` for you (so worktrees land in the right place) and you rarely need to touch it. Everything else (project board, review context, verification commands, multi-repo routing) is optional and falls back to sensible defaults. Browse [`forge.yaml.example`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/forge.yaml.example) and [`docs/CONFIG.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/CONFIG.md) when you're ready to customize.
 
-**Prefer guided, AI-powered setup?** Open Claude Code in your project directory and run `/forgedock-init` instead — it scans your repo and fills in the optional sections (repo owner/name, worktree path, branch strategy, project board) for you. Plain `npx forgedock init` (no flag) generates the full annotated template with every optional section commented out.
+**Prefer guided, AI-powered setup?** Open Claude Code in your project directory and run `/forgedock-init` instead — it scans your repo and fills in the optional sections (repo owner/name, worktree path, branch strategy, project board) for you.
 
 ---
 
@@ -200,7 +207,7 @@ The symlink wasn't created. Re-run `npx forgedock` and check `ls ~/.claude/comma
 
 **`forge.yaml` not found**
 
-Run `/forgedock-init` in your project directory inside Claude Code, or copy `forge.yaml.example` from the ForgeDock repo and edit it.
+Run `npx forgedock init` in your project directory to generate it, or copy `forge.yaml.example` from the ForgeDock repo and edit it. Once it exists, `/forgedock-init` inside Claude Code can fill in the optional sections.
 
 **`gh` auth errors**
 

package/docs/site/index.md

@@ -37,7 +37,7 @@ No more coordinating between agent sessions. No more lost context. No more start
 
 - [GitHub Repository](https://github.com/RapierCraftStudios/ForgeDock)
 - [npm Package](https://www.npmjs.com/package/forgedock)
-- [Configuration Reference](../CONFIG.md)
+- [Configuration Reference](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/CONFIG.md)
 - [Report an Issue](https://github.com/RapierCraftStudios/ForgeDock/issues/new)
 
 ---