forge-cc 0.1.5 → 0.1.7

package/dist/worktree/state-merge.js

@@ -0,0 +1,162 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync } from "../utils/platform.js";
+// ---------------------------------------------------------------------------
+// mergeSessionState
+// ---------------------------------------------------------------------------
+/**
+ * Merge state from a completed worktree session back to the main repo.
+ *
+ * - STATE.md: updates the milestone row with completion status and the
+ *   Last Session date.
+ * - ROADMAP.md: marks the milestone row as complete with the given date.
+ *
+ * Uses synchronous I/O throughout — consistent with all other worktree modules.
+ *
+ * @param mainRepoDir - Absolute path to the main repository
+ * @param worktreeDir - Absolute path to the completed worktree
+ * @param milestoneNumber - The milestone that was completed
+ * @param completionDate - Date string (YYYY-MM-DD) for the completion
+ */
+export function mergeSessionState(mainRepoDir, worktreeDir, milestoneNumber, completionDate) {
+    const warnings = [];
+    let stateUpdated = false;
+    let roadmapUpdated = false;
+    const completionStatus = `Complete (${completionDate})`;
+    // --- Check that the worktree has planning files --------------------------
+    const worktreeStatePath = join(worktreeDir, ".planning", "STATE.md");
+    const worktreeRoadmapPath = join(worktreeDir, ".planning", "ROADMAP.md");
+    if (!existsSync(worktreeStatePath)) {
+        warnings.push(`Worktree STATE.md not found at ${worktreeStatePath} — skipping state merge`);
+    }
+    if (!existsSync(worktreeRoadmapPath)) {
+        warnings.push(`Worktree ROADMAP.md not found at ${worktreeRoadmapPath} — skipping roadmap merge`);
+    }
+    // --- Update main repo STATE.md ------------------------------------------
+    const mainStatePath = join(mainRepoDir, ".planning", "STATE.md");
+    if (existsSync(mainStatePath)) {
+        const milestoneUpdated = updateStateMilestoneRow(mainStatePath, milestoneNumber, completionStatus);
+        if (milestoneUpdated) {
+            stateUpdated = true;
+        }
+        else {
+            warnings.push(`Milestone ${milestoneNumber} row not found in main repo STATE.md — no state update performed`);
+        }
+    }
+    else {
+        warnings.push(`Main repo STATE.md not found at ${mainStatePath} — cannot update state`);
+    }
+    // --- Update main repo ROADMAP.md ----------------------------------------
+    const mainRoadmapPath = join(mainRepoDir, ".planning", "ROADMAP.md");
+    if (existsSync(mainRoadmapPath)) {
+        const milestoneUpdated = updateRoadmapMilestoneStatus(mainRoadmapPath, milestoneNumber, completionStatus);
+        if (milestoneUpdated) {
+            roadmapUpdated = true;
+        }
+        else {
+            warnings.push(`Milestone ${milestoneNumber} row not found in main repo ROADMAP.md — no roadmap update performed`);
+        }
+    }
+    else {
+        warnings.push(`Main repo ROADMAP.md not found at ${mainRoadmapPath} — cannot update roadmap`);
+    }
+    return { stateUpdated, roadmapUpdated, warnings };
+}
+// ---------------------------------------------------------------------------
+// updateRoadmapMilestoneStatus
+// ---------------------------------------------------------------------------
+/**
+ * Update a specific milestone row in a ROADMAP.md file.
+ * Uses structured line-by-line parsing (not regex replace) to safely
+ * update the status column of the milestone's table row.
+ *
+ * @param roadmapPath - Absolute path to ROADMAP.md
+ * @param milestoneNumber - Which milestone to update
+ * @param newStatus - New status string (e.g., "Complete (2026-02-15)")
+ * @returns true if the milestone was found and updated
+ */
+export function updateRoadmapMilestoneStatus(roadmapPath, milestoneNumber, newStatus) {
+    const content = readFileSync(roadmapPath, "utf-8");
+    const lines = content.split("\n");
+    let found = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Match table rows: | <number> | <name> | <status> |
+        // Cells are separated by |. Split and check the first data cell.
+        if (!line.trimStart().startsWith("|"))
+            continue;
+        const cells = line.split("|");
+        // A valid table row split by | produces: ["", " cell1 ", " cell2 ", " cell3 ", ""]
+        // We need at least 4 separators (5 segments) for a 3-column table row.
+        if (cells.length < 5)
+            continue;
+        const firstCell = cells[1].trim();
+        const parsedNumber = parseInt(firstCell, 10);
+        if (isNaN(parsedNumber) || parsedNumber !== milestoneNumber)
+            continue;
+        // Check if this is already completed — if so, last completer wins with warning.
+        const currentStatus = cells[3].trim();
+        const alreadyComplete = currentStatus.toLowerCase().startsWith("complete");
+        // Update the status cell (index 3), preserving cell padding.
+        cells[3] = ` ${newStatus} `;
+        lines[i] = cells.join("|");
+        found = true;
+        if (alreadyComplete) {
+            // Last completer wins — overwrite is intentional but callers may
+            // want to know. We still return true since the update was applied.
+        }
+        break;
+    }
+    if (found) {
+        atomicWriteFileSync(roadmapPath, lines.join("\n"));
+    }
+    return found;
+}
+// ---------------------------------------------------------------------------
+// updateStateMilestoneRow
+// ---------------------------------------------------------------------------
+/**
+ * Update the milestone progress table in STATE.md.
+ * Reads the current STATE.md, finds the milestone row, updates its status.
+ * Also updates the `**Last Session:**` date if present.
+ * Preserves all other content.
+ *
+ * @param statePath - Absolute path to STATE.md
+ * @param milestoneNumber - Which milestone to update
+ * @param newStatus - New status string
+ * @returns true if the milestone was found and updated
+ */
+export function updateStateMilestoneRow(statePath, milestoneNumber, newStatus) {
+    const content = readFileSync(statePath, "utf-8");
+    const lines = content.split("\n");
+    let milestoneFound = false;
+    // Extract the date from the status string for Last Session update.
+    // Status format is typically "Complete (YYYY-MM-DD)".
+    const dateMatch = newStatus.match(/\((\d{4}-\d{2}-\d{2})\)/);
+    const completionDate = dateMatch ? dateMatch[1] : null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // --- Update milestone table row ----------------------------------------
+        if (line.trimStart().startsWith("|")) {
+            const cells = line.split("|");
+            if (cells.length >= 5) {
+                const firstCell = cells[1].trim();
+                const parsedNumber = parseInt(firstCell, 10);
+                if (!isNaN(parsedNumber) && parsedNumber === milestoneNumber) {
+                    cells[3] = ` ${newStatus} `;
+                    lines[i] = cells.join("|");
+                    milestoneFound = true;
+                }
+            }
+        }
+        // --- Update Last Session date ------------------------------------------
+        if (completionDate && line.match(/\*\*Last Session:\*\*/)) {
+            lines[i] = line.replace(/(\*\*Last Session:\*\*\s*)\S+/, `$1${completionDate}`);
+        }
+    }
+    if (milestoneFound) {
+        atomicWriteFileSync(statePath, lines.join("\n"));
+    }
+    return milestoneFound;
+}
+//# sourceMappingURL=state-merge.js.map

package/dist/worktree/state-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-merge.js","sourceRoot":"","sources":["../../src/worktree/state-merge.ts"],"names":[],"mappings":"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"}

package/hooks/pre-commit-verify.js

@@ -35,8 +35,9 @@ function checkPreCommit(hookData) {
   const projectDir = process.cwd();
 
   // Check 1: Wrong branch protection
+  let branch = "unknown";
   try {
-    const branch = execSync("git branch --show-current", {
+    branch = execSync("git branch --show-current", {
       encoding: "utf-8",
     }).trim();
     if (branch === "main" || branch === "master") {
@@ -49,8 +50,13 @@ function checkPreCommit(hookData) {
     // Can't determine branch — allow
   }
 
-  // Check 2: Verify cache exists
-  const cachePath = join(projectDir, ".forge", "last-verify.json");
+  // Check 2: Verify cache exists — per-branch first, fall back to legacy path
+  const slug = branch.replace(/\//g, "-").toLowerCase();
+  const perBranchCachePath = join(projectDir, ".forge", "verify-cache", `${slug}.json`);
+  const legacyCachePath = join(projectDir, ".forge", "last-verify.json");
+  const cachePath = existsSync(perBranchCachePath)
+    ? perBranchCachePath
+    : legacyCachePath;
   if (!existsSync(cachePath)) {
     return {
       decision: "block",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-cc",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Pre-PR verification harness for Claude Code agents — gate runner + CLI + MCP server",
   "type": "module",
   "license": "MIT",

package/skills/forge-go.md

@@ -38,6 +38,8 @@ If all milestones are complete:
 
 If `--auto` was passed as an argument, set mode to auto and skip the prompt.
 
+If `--single` was passed as an argument, set mode to single and skip the prompt.
+
 Otherwise: **your very next tool call MUST be AskUserQuestion.** No file reads, no git commands, no exploration — ask the user first. Use exactly these parameters:
 
 - question: "How should this project be executed?"
@@ -65,6 +67,12 @@ Verify the execution environment is ready:
 
    > You have uncommitted changes. Commit or stash them before running /forge:go.
 
+5. **Milestone size:** Count waves and agents in the milestone. If >3 waves or >6 total agents, warn:
+
+   > Warning: This milestone has {N} waves and {M} agents. Large milestones risk context overflow. Consider splitting before execution.
+
+   This is a pre-flight warning, not a hard abort — the user can choose to proceed. But the warning should be prominent so they can split the milestone first if needed.
+
 Print the pre-flight summary:
 
 ```
@@ -78,6 +86,21 @@ Print the pre-flight summary:
 Ready to execute Milestone 4.
 ```
 
+### Step 2.5 — Session Isolation (Automatic)
+
+The execution engine automatically creates a git worktree for isolated execution. This happens transparently — you don't need to manage it manually.
+
+**What happens behind the scenes:**
+1. A worktree is created at `../.forge-wt/<repo>/<session-id>/` based on the feature branch
+2. A session is registered in `.forge/sessions.json`
+3. All wave execution happens inside the worktree directory
+4. After completion, changes are merged back to the feature branch
+5. The worktree and session are cleaned up
+
+**Why:** Multiple users or terminals can run `/forge:go` simultaneously without corrupting each other's work. Each session gets an isolated copy of the codebase.
+
+**If worktree creation fails:** The engine falls back to running in the main working directory (original behavior). A warning is printed but execution continues.
+
 ### Step 3 — Execute Waves
 
 Parse the milestone section from the PRD. Each milestone contains waves with agent definitions:
@@ -261,7 +284,7 @@ After milestone completion, determine the next action:
 - Verification: PASSED
 - Branch: {branch} (pushed)
 
-**Next:** Run `/clear` to reset context, then `/forge:go` for Milestone {N+1}: {Next Milestone Name}.
+**Next:** Run `/clear` then `/forge:go` for Milestone {N+1}, or exit and run `npx forge run` to auto-chain all remaining milestones.
 ```
 
 #### If this IS the last milestone:
@@ -303,27 +326,46 @@ The PR is ready for review.
 
 ### Auto Mode
 
-When the user selects "Auto (all milestones)" in Step 1.5 or invokes with `--auto` (e.g., `/forge:go --auto`), chain all remaining milestones with context resets between each.
+When the user selects "Auto (all milestones)" in Step 1 Part B or invokes with `--auto` (e.g., `/forge:go --auto`):
+
+Print the following instructions and then **stop** (do not execute a milestone):
 
-After each milestone completes (Step 5-7):
+```
+## Auto Mode — Fresh Context Execution
 
-1. Print the completion summary for the milestone.
-2. Print instructions for the context reset:
+Auto mode runs each milestone in a fresh Claude session for maximum quality.
 
-   ```
-   ## Context Reset for Milestone {N+1}
+**To start:** Exit this Claude session (Ctrl+C), then run in your terminal:
 
-   Milestone {N} is complete and committed. Starting fresh context for the next milestone.
+    npx forge run
 
-   To continue autonomously, start a new session and run:
-   > /forge:go --auto
+**What happens:**
+- Each milestone gets a fresh Claude session (no context rot)
+- Output streams inline to your terminal
+- Stops on completion, failure, or stall
+- Resume after failure: fix the issue, run `npx forge run` again
 
-   The new session will read STATE.md (just updated) and pick up at Milestone {N+1}.
-   ```
+**Requires:** claude CLI on PATH, --dangerously-skip-permissions (automatic)
+```
+
+**IMPORTANT:** Auto mode does NOT execute milestones in the current session. It redirects the user to `npx forge run`, which handles spawning fresh Claude sessions per milestone via the Ralph Loop pattern.
 
-**IMPORTANT:** Auto mode does NOT continue in the same context window. Each milestone gets a fresh context (the Ralph Loop pattern). The `--auto` flag simply means "after completing this milestone, print the instructions for continuing" rather than "execute everything in one session."
+### Parallel Milestones (dependsOn)
+
+When milestones specify `dependsOn` fields in the PRD, the scheduler can identify which milestones are independent and run them in parallel:
+
+- Milestones with no `dependsOn` (or `dependsOn: []`) can run in the first wave
+- Milestones that depend on completed milestones become ready as dependencies finish
+- The scheduler builds a DAG and groups milestones into execution waves
+
+Example PRD milestone with dependencies:
+```
+### Milestone 3: Integration Layer
+**dependsOn:** 1, 2
+**Goal:** Combine components from M1 and M2...
+```
 
-This prevents context rot — each milestone starts with clean context reading CLAUDE.md + STATE.md + current milestone section only (~20% of context window).
+If no `dependsOn` fields are present, milestones execute sequentially (backward compatible).
 
 ### Step 9 — Linear Issue Start (On Milestone Begin)
 
@@ -347,3 +389,4 @@ If Linear is not configured, skip silently.
   > Milestone {N} has no wave definitions. Update the PRD with agent assignments before running /forge:go.
 - **Already on correct milestone:** If STATE.md's current milestone matches the target, proceed normally (this is the expected case).
 - **Linear auth fails:** Warn but continue execution. Linear sync is not blocking.
+- **Worktree conflict:** If the worktree directory already exists (e.g., from a crashed session), the engine attempts `npx forge cleanup` first. If that fails, it falls back to main directory execution.

package/skills/forge-setup.md

@@ -93,7 +93,32 @@ Check if `~/.claude/CLAUDE.md` exists:
 - **If it does not exist:** Create it using `globalClaudeMdTemplate()` from the templates.
 - **If it exists:** Leave it alone. Do not overwrite the user's global config.
 
-### Step 6 — Install Hooks
+### Step 6 — Install Skills
+
+Copy all forge skills to `~/.claude/commands/forge/` so they're discoverable via `/forge:*`:
+
+```bash
+mkdir -p ~/.claude/commands/forge
+```
+
+Find the installed forge-cc package and copy skill files, stripping the `forge-` prefix:
+
+```bash
+SKILLS_DIR="$(dirname "$(which forge)")/../lib/node_modules/forge-cc/skills"
+# Fallback: check local node_modules
+if [ ! -d "$SKILLS_DIR" ]; then
+  SKILLS_DIR="node_modules/forge-cc/skills"
+fi
+
+for f in "$SKILLS_DIR"/forge-*.md; do
+  name=$(basename "$f" | sed 's/^forge-//')
+  cp "$f" ~/.claude/commands/forge/"$name"
+done
+```
+
+Print: "Installed forge skills to ~/.claude/commands/forge/"
+
+### Step 7 — Install Hooks
 
 Check if the user has a `.claude/settings.json` or `.claude/settings.local.json` in the project:
 
@@ -126,7 +151,7 @@ If a settings file already exists, inform the user:
 > Settings file already exists. To add the version-check hook manually, add this to your hooks config:
 > `"command": "node node_modules/forge-cc/hooks/version-check.js"`
 
-### Step 7 — Summary
+### Step 8 — Summary
 
 Print a summary of everything that was created or updated:
 
@@ -138,6 +163,7 @@ Print a summary of everything that was created or updated:
 **Gates:** {comma-separated list}
 
 ### Files Created/Updated
+- ~/.claude/commands/forge/*.md ✓ (skills)
 - .forge.json ✓
 - CLAUDE.md ✓
 - .planning/STATE.md ✓

package/skills/forge-spec.md

@@ -83,12 +83,31 @@ Conduct an adaptive interview using the interview engine logic from `src/spec/in
 4. **Scope** — what's out, sacred files, boundaries
 5. **Milestones** — phasing, dependencies, delivery chunks
 
+**Milestone Sizing Constraint (Hard Rule):**
+
+Each milestone MUST be completable in one main agent context window. If a milestone requires more than ~4 agents across 2-3 waves, split it. This is non-negotiable — large milestones cause context overflow and execution failures. When interviewing about milestones, actively recommend splitting any milestone that looks too large.
+
+**Milestone Dependencies (dependsOn):**
+
+During the milestones phase of the interview, ask about milestone dependencies using AskUserQuestion. For each milestone after the first, ask:
+
+- question: "Does Milestone {N} depend on any previous milestones?"
+- options:
+  - "No dependencies — can start immediately"
+  - "Depends on Milestone {N-1} (sequential)"
+  - "Depends on specific milestones (I'll specify)"
+
+If milestones have explicit dependencies, include `**dependsOn:** 1, 2` in the milestone section of the PRD. If no dependencies are specified, omit the field (backward compatible — treated as sequential).
+
+Independent milestones enable parallel execution via `/forge:go`, which creates separate worktrees for each parallel milestone.
+
 **Interview Rules:**
 
-- **Lead with recommendations.** Every question includes context from the codebase scan. Never ask a blank "what do you want to build?" question.
-- **Ask 1-3 questions per round.** Present them as a numbered list. The user can answer all at once or pick which to answer.
-- **Follow interesting threads.** If the user mentions migration, breaking changes, multiple user types, or external integrations, follow up with targeted questions.
-- **Show progress.** After each answer round, show a compact status:
+- **NEVER present questions as numbered text — always use AskUserQuestion with 2-4 options per question.** Every interview question MUST be delivered via Claude Code's AskUserQuestion tool with structured multiple-choice options. Do not print numbered lists of questions for the user to answer in free text.
+- **Lead with recommendations.** Every question includes context from the codebase scan as the question text. Never ask a blank "what do you want to build?" question.
+- **Ask 1 question at a time via AskUserQuestion.** Each question gets its own AskUserQuestion call with 2-4 predefined options derived from codebase scan context and common patterns. Always include a final option like "Other (I'll describe)" to allow the user to provide a custom answer.
+- **Follow interesting threads.** If the user's selection mentions migration, breaking changes, multiple user types, or external integrations, follow up with targeted AskUserQuestion calls.
+- **Show progress.** After each answer round, show a compact status as text output:
 
 ```
 Progress: [##---] Problem & Goals (2/2) | User Stories (0/2) | Technical (0/1) | Scope (0/1) | Milestones (0/1)
@@ -101,22 +120,35 @@ Progress: [##---] Problem & Goals (2/2) | User Stories (0/2) | Technical (0/1) |
 - **Stop when complete.** When all sections have enough info (Problem 2+, Users 2+, Technical 1+, Scope 1+, Milestones 1+), move to Step 4. Don't drag the interview out.
 - **Allow early exit.** If the user says "that's enough", "skip", or "generate it", respect that and move to Step 4 with what you have.
 
-**Question Format:**
+**Question Format (AskUserQuestion):**
+
+Each interview question MUST use AskUserQuestion. Build the question text from codebase scan context and the section being asked about. Provide 2-4 options that reflect likely answers based on the scan results, plus a free-text escape hatch. Example:
 
 ```
-### Round N
+AskUserQuestion:
+  question: "[Section] Context from scan or previous answers. Question text here?"
+  options:
+    - "Option A — a likely answer based on scan findings"
+    - "Option B — another plausible direction"
+    - "Option C — a third possibility (if applicable)"
+    - "Other (I'll describe)"
+```
+
+If the user selects "Other (I'll describe)", prompt them for a free-text answer using a follow-up AskUserQuestion or accept their typed response.
 
-Based on your codebase scan, I have some questions:
+**Do NOT do this (anti-pattern):**
 
-1. **[Section]** Context from scan or previous answers.
-   Question text here?
+```
+### Round N
 
-2. **[Section]** Context observation.
-   Question text here?
+1. **[Section]** Question text?
+2. **[Section]** Question text?
 
-> Answer by number (e.g., "1. My answer to first question. 2. Second answer") or answer all at once.
+> Answer by number...
 ```
 
+This numbered-text format is explicitly prohibited. Always use AskUserQuestion.
+
 ### Step 4 — Generate PRD
 
 Using all gathered interview answers and codebase scan results, generate the final PRD. Use the generator module at `src/spec/generator.ts`:
@@ -154,9 +186,13 @@ The PRD should follow this structure:
 - [ ] Issue title — brief description
 
 ### Milestone 2: {Name}
+**dependsOn:** 1
+**Goal:** {What this delivers}
 ...
 ```
 
+**Milestone sizing check:** Before finalizing, review each milestone against the sizing constraint. Every milestone MUST fit in one agent context window (~4 agents across 2-3 waves max). If any milestone exceeds this, split it into smaller milestones before writing the final PRD. Set `maxContextWindowFit: true` on all milestones — if you cannot make a milestone fit, flag it as `maxContextWindowFit: false` and warn the user.
+
 Write the final PRD to `.planning/prds/{project-slug}.md`. Tell the user:
 
 > Final PRD written to `.planning/prds/{slug}.md`.
@@ -234,13 +270,15 @@ After sync, print the handoff prompt:
 PRD: `.planning/prds/{slug}.md`
 Linear: {project URL}
 
-**Next step:** Run `/forge:go` to start executing Milestone 1. The execution engine will:
+**Next step:** Run `/forge:go` for one milestone at a time, or exit and run `npx forge run` to execute all milestones autonomously. The execution engine will:
 - Read the PRD and milestone plan
 - Spawn agent teams for each issue
 - Verify each change with forge-mcp gates
 - Open PRs and transition issues automatically
 ```
 
+**Note:** `/forge:go` now uses git worktrees for session isolation. Multiple users can run `/forge:go` on different milestones simultaneously without conflicts.
+
 ## Edge Cases
 
 - **No Linear connection:** Warn the user. Still generate the PRD locally — skip the Linear sync steps.

package/skills/forge-update.md

@@ -48,7 +48,27 @@ Verify the update succeeded:
 npm list -g forge-cc --json 2>/dev/null | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');const j=JSON.parse(d);console.log(j.dependencies?.['forge-cc']?.version||'failed')"
 ```
 
-### Step 4 — Post-Update Check
+### Step 4 — Re-sync Skills
+
+After updating, copy the latest skills to `~/.claude/commands/forge/`:
+
+```bash
+mkdir -p ~/.claude/commands/forge
+
+SKILLS_DIR="$(dirname "$(which forge)")/../lib/node_modules/forge-cc/skills"
+if [ ! -d "$SKILLS_DIR" ]; then
+  SKILLS_DIR="node_modules/forge-cc/skills"
+fi
+
+for f in "$SKILLS_DIR"/forge-*.md; do
+  name=$(basename "$f" | sed 's/^forge-//')
+  cp "$f" ~/.claude/commands/forge/"$name"
+done
+```
+
+Print: "Synced skills to ~/.claude/commands/forge/"
+
+### Step 5 — Post-Update Check
 
 After updating, check if the current project's forge files need refreshing: