specweave 1.0.352 → 1.0.353

package/plugins/specweave/agents/sw-pm.md

@@ -0,0 +1,117 @@
+---
+name: sw-pm
+description: Product Manager for writing spec.md with user stories and acceptance criteria. Use for increment specification creation during /sw:increment orchestration.
+model: opus
+memory: project
+---
+
+# Product Manager Agent
+
+## Project Overrides
+
+!`s="pm"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
+
+## Identity
+
+You are a Product Manager specializing in spec-driven development. You create product specifications with user stories and acceptance criteria following SpecWeave conventions.
+
+Your prompt will contain: increment ID, increment path, feature description, and plugin root path.
+
+## Progressive Disclosure
+
+Load phases via Read() as needed — do NOT try to generate content without loading the relevant phase first.
+
+| Phase | When to Load | File (relative to plugin root) |
+|-------|--------------|------|
+| Deep Interview | **CHECK FIRST!** If enabled in config | `skills/pm/phases/00-deep-interview.md` |
+| Research | Gathering requirements | `skills/pm/phases/01-research.md` |
+| Spec Creation | Writing spec.md | `skills/pm/phases/02-spec-creation.md` |
+| Templates | Need spec template | `skills/pm/templates/spec-template.md` |
+| Validation | Final quality check | `skills/pm/phases/03-validation.md` |
+
+**How to find phase files**: Extract the plugin root from your prompt, then Read the phase file:
+```
+Read({ file_path: "<plugin_root>/skills/pm/phases/01-research.md" })
+```
+
+## Deep Interview Mode Check (MANDATORY)
+
+**Before starting any spec work, check if Deep Interview Mode is enabled:**
+
+```bash
+jq -r '.planning.deepInterview.enabled // false' .specweave/config.json
+```
+
+If `true`:
+1. Load `skills/pm/phases/00-deep-interview.md` from plugin root
+2. **THINK about complexity first** — don't blindly ask questions:
+   - Trivial features: 0-3 questions
+   - Small features: 4-8 questions
+   - Medium features: 9-18 questions
+   - Large features: 19-40 questions
+3. Check `minQuestions` config: `jq -r '.planning.deepInterview.minQuestions // 5' .specweave/config.json`
+4. Cover relevant categories (skip those that don't apply)
+5. Only proceed to Research phase after sufficient clarity
+
+### Writing Interview State to Disk (CRITICAL)
+
+You MUST write the interview state file so the enforcement guard can find it:
+
+```bash
+mkdir -p .specweave/state
+echo '{"incrementId":"XXXX-name","startedAt":"'$(date -Iseconds)'","coveredCategories":{}}' \
+  > .specweave/state/interview-XXXX-name.json
+```
+
+After covering each category, update the state file:
+```bash
+jq '.coveredCategories.architecture = {"coveredAt": "'$(date -Iseconds)'", "summary": "..."}' \
+  .specweave/state/interview-XXXX-name.json > tmp && mv tmp .specweave/state/interview-XXXX-name.json
+```
+
+## Core Principles
+
+1. **Phased Approach**: Work in phases, not all at once
+2. **Chunking**: Large specs (6+ user stories) must be chunked
+3. **Validation**: Every spec needs acceptance criteria
+4. **Traceability**: User stories link to acceptance criteria
+
+## Spec Structure
+
+```
+.specweave/increments/####-name/
+├── spec.md    # You create this
+├── plan.md    # Architect creates
+├── tasks.md   # Planner creates
+└── metadata.json
+```
+
+## User Story Format
+
+```markdown
+### US-001: [Title]
+**Project**: [project-name]
+**As a** [role]
+**I want** [capability]
+**So that** [benefit]
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: [Criterion 1]
+- [ ] **AC-US1-02**: [Criterion 2]
+```
+
+## Workflow
+
+0. **Check Deep Interview Mode** → If enabled, load phase 00 and interview FIRST
+1. **Read feature description from prompt** → Read `phases/01-research.md`
+2. **Requirements clear** → Read `phases/02-spec-creation.md` + `templates/spec-template.md`
+3. **Spec written** → Read `phases/03-validation.md`
+4. **Return** → spec.md is complete, control returns to increment orchestrator
+
+## Token Budget Per Response
+
+- **Research phase**: < 500 tokens
+- **Spec creation**: < 600 tokens per chunk
+- **Validation**: < 400 tokens
+
+**NEVER exceed 2000 tokens in a single response!**

package/plugins/specweave/hooks/v2/dispatchers/pre-tool-use.sh

@@ -9,6 +9,7 @@
 #
 # @since 1.0.167
 # @updated 1.0.196 - Added status-completion-guard for Edit operations
+# @updated 1.0.352 - Added interview-enforcement-guard for agent-spawned spec.md writes
 
 set -e
 
@@ -68,6 +69,20 @@ if [[ "$TOOL_NAME" == "Write" ]]; then
     fi
   fi
 
+  # Interview Enforcement Guard
+  # Blocks spec.md writes until deep interview is complete (when strict mode enabled)
+  # Needed here because agent-spawned writes don't inherit skill-level hooks
+  INTERVIEW_GUARD="$GUARDS_DIR/interview-enforcement-guard.sh"
+  if [[ -x "$INTERVIEW_GUARD" ]]; then
+    INTERVIEW_RESULT=$(echo "$INPUT" | "$INTERVIEW_GUARD" 2>/dev/null || echo '{"decision":"allow"}')
+    INTERVIEW_DECISION=$(echo "$INTERVIEW_RESULT" | jq -r '.decision // "allow"')
+
+    if [[ "$INTERVIEW_DECISION" == "block" ]]; then
+      echo "$INTERVIEW_RESULT"
+      exit 0
+    fi
+  fi
+
   echo '{"decision":"allow"}'
   exit 0
 fi

package/plugins/specweave/hooks/v2/guards/skill-chain-enforcement-guard.sh

@@ -1,4 +1,12 @@
 #!/bin/bash
+# DEPRECATED: v1.0.352 — No longer referenced by /sw:increment SKILL.md
+# The increment skill now uses Agent() delegation (sw-pm, sw-architect, sw-planner agents)
+# instead of Skill() chains with marker-based enforcement.
+# This guard remains on disk for backward compatibility with older cached plugin versions.
+# It can be safely removed in a future version.
+#
+# --- Original documentation below ---
+#
 # skill-chain-enforcement-guard.sh - Enforces skill delegation in /sw:increment
 #
 # PURPOSE:

package/plugins/specweave/skills/increment/SKILL.md

@@ -1,31 +1,20 @@
 ---
 description: Plan and create SpecWeave increments with PM and Architect agent collaboration. Use when starting new features, hotfixes, bugs, or any development work that needs specification and task breakdown. Creates spec.md, plan.md, tasks.md with proper AC-IDs and living docs integration.
 argument-hint: "<feature-description>"
-context: fork
 model: opus
 hooks:
   PreToolUse:
     - matcher: Write
       hooks:
-        - type: command
-          command: bash plugins/specweave/hooks/v2/guards/skill-chain-enforcement-guard.sh
         - type: command
           command: bash plugins/specweave/hooks/v2/guards/interview-enforcement-guard.sh
         - type: command
           command: bash plugins/specweave/hooks/v2/guards/spec-template-enforcement-guard.sh
-    - matcher: Edit
-      hooks:
-        - type: command
-          command: bash plugins/specweave/hooks/v2/guards/skill-chain-enforcement-guard.sh
   PostToolUse:
     - matcher: Write
       hooks:
         - type: command
           command: bash plugins/specweave/hooks/v2/guards/increment-duplicate-guard.sh
-    - matcher: Skill|Task
-      hooks:
-        - type: command
-          command: bash plugins/specweave/hooks/v2/dispatchers/post-tool-use-analytics.sh
 ---
 
 # Plan Product Increment
@@ -270,85 +259,80 @@ Create files in order: metadata.json FIRST, then spec.md, plan.md, tasks.md.
 
 ## Critical Rules
 
-1. **NEVER write spec.md/plan.md/tasks.md directly** - ALWAYS delegate via Skill() calls (guard-enforced)
-2. **Project field is MANDATORY** - Every US MUST have `**Project**:` field
+1. **NEVER write spec.md/plan.md/tasks.md directly** — ALWAYS delegate via Agent() calls
+2. **Project field is MANDATORY** — Every US MUST have `**Project**:` field
 3. **Use Template Creator CLI** (REQUIRED): `specweave create-increment --id "XXXX-name" --title "Title" --description "Desc" --project "my-app"`
-4. **NO agent spawning** - Skills MUST NOT spawn Task() agents (causes crashes). Guide user in main conversation.
-5. **Increment naming** - Format: `####-descriptive-kebab-case`
-6. **Multi-repo** - In umbrella projects with `repositories/` folder, create increments in EACH repo's `.specweave/`, not the umbrella root
+4. **Agent delegation is the ONLY way** to produce spec.md/plan.md/tasks.md — the increment skill MUST use Agent() calls, not inline writing
+5. **Increment naming** — Format: `####-descriptive-kebab-case`
+6. **Multi-repo** — In umbrella projects with `repositories/` folder, create increments in EACH repo's `.specweave/`, not the umbrella root
 
-## CRITICAL: Mandatory Skill Delegation (BLOCKING ENFORCEMENT)
+## CRITICAL: Mandatory Agent Delegation
 
 **This skill MUST NOT write spec.md, plan.md, or tasks.md directly.**
-A PreToolUse guard (`skill-chain-enforcement-guard.sh`) BLOCKS all direct writes.
-
-**You MUST invoke these sub-skills via Skill() calls:**
+Delegate to native plugin agents via Agent() calls.
 
-| File | Required Skill | Invocation |
-|------|---------------|------------|
-| spec.md | PM | `Skill({ skill: "sw:pm", args: "Write spec for increment XXXX-name: <description>" })` |
-| plan.md | Architect | `Skill({ skill: "sw:architect", args: "Design architecture for increment XXXX-name based on spec.md" })` |
-| tasks.md | Test-Aware Planner | `Skill({ skill: "sw:test-aware-planner", args: "Generate tasks for increment XXXX-name based on spec.md and plan.md" })` |
+**You MUST invoke these agents:**
 
-**Each sub-skill MUST register its marker BEFORE writing its file:**
-```bash
-mkdir -p .specweave/state
-# PM skill registers before writing spec.md:
-echo '{}' | jq '.pm_invoked=true | .pm_invoked_at="'$(date -Iseconds)'"' > .specweave/state/skill-chain-XXXX-name.json
-# Or merge into existing:
-jq '.architect_invoked=true | .architect_invoked_at="'$(date -Iseconds)'"' .specweave/state/skill-chain-XXXX-name.json > tmp && mv tmp .specweave/state/skill-chain-XXXX-name.json
-```
+| File | Agent | Invocation |
+|------|-------|------------|
+| spec.md | sw-pm | `Agent({ subagent_type: "sw-pm", prompt: "Write spec for increment XXXX-name: <description>. Increment path: <path>. Plugin root: <root>" })` |
+| plan.md | sw-architect | `Agent({ subagent_type: "sw-architect", prompt: "Design architecture for increment XXXX-name. Read spec.md at <path>/spec.md" })` |
+| tasks.md | sw-planner | `Agent({ subagent_type: "sw-planner", prompt: "Generate tasks for increment XXXX-name. Read spec.md at <path>/spec.md and plan.md at <path>/plan.md" })` |
 
 **DO NOT:**
 - Write user stories, architecture, or tasks inline
 - Copy/paste spec content into Write() calls
-- "Summarize" what a skill would produce
-- Skip any of the 3 Skill() calls
-
-**The guard will BLOCK your write and show this error if you try.**
+- "Summarize" what an agent would produce
+- Skip any of the 3 Agent() calls
 
 ## Step 3a: Deep Interview Mode (if enabled)
 
 **IMPORTANT**: This step runs AFTER the increment folder is created (Step 3), so the
 interview state file can reference the real increment ID.
 
-**If deep interview is enabled, delegate to PM skill:**
+**If deep interview is enabled, delegate to PM agent:**
 
 ```typescript
-Skill({ skill: "sw:pm", args: "Deep interview for increment XXXX-name: <user description>" })
+Agent({ subagent_type: "sw-pm", prompt: "Deep interview for increment XXXX-name: <user description>. Increment path: <path>. Plugin root: <root>" })
 ```
 
-The PM skill will:
+The PM agent will:
 1. Assess complexity and determine question count (trivial: 0-3, small: 4-8, medium: 9-18, large: 19-40)
 2. Interview the user across relevant categories
 3. Write interview state to `.specweave/state/interview-{increment-id}.json`
 4. Return interview summary for spec.md creation
 
-**After PM returns**, read the interview state file to confirm all categories are covered
+**After PM agent returns**, read the interview state file to confirm all categories are covered
 before proceeding to spec.md creation (especially when `enforcement: "strict"`).
 
-## Step 4: Delegation (MANDATORY - Guard Enforced)
+## Step 4: Delegation (MANDATORY - Agent Based)
 
-**After increment folder + metadata.json are created, you MUST invoke all 3 sub-skills.**
-**A PreToolUse guard BLOCKS writes to spec.md/plan.md/tasks.md without skill markers.**
+**After increment folder + metadata.json are created, you MUST invoke all 3 agents sequentially.**
+
+Resolve the plugin root path first:
+```bash
+PLUGIN_ROOT=$(find . -path "*/plugins/specweave/agents/sw-pm.md" -type f 2>/dev/null | head -1 | sed 's|/agents/sw-pm.md||')
+# Fallback: check node_modules
+[ -z "$PLUGIN_ROOT" ] && PLUGIN_ROOT=$(find node_modules -path "*/plugins/specweave/agents/sw-pm.md" -type f 2>/dev/null | head -1 | sed 's|/agents/sw-pm.md||')
+```
 
-### 4a. Invoke PM for spec.md (REQUIRED)
+### 4a. Invoke PM Agent for spec.md (REQUIRED)
 ```typescript
-Skill({ skill: "sw:pm", args: "Write spec for increment XXXX-name: <user's feature description>" })
+Agent({ subagent_type: "sw-pm", prompt: "Write spec for increment XXXX-name: <user's feature description>. Increment path: .specweave/increments/XXXX-name/. Plugin root: <PLUGIN_ROOT>" })
 ```
 
-### 4b. Invoke Architect for plan.md (REQUIRED)
+### 4b. Invoke Architect Agent for plan.md (REQUIRED)
 ```typescript
-Skill({ skill: "sw:architect", args: "Design architecture for increment XXXX-name based on spec.md" })
+Agent({ subagent_type: "sw-architect", prompt: "Design architecture for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md. ADR directory: .specweave/docs/internal/architecture/adr/" })
 ```
 
-### 4c. Invoke Test-Aware Planner for tasks.md (REQUIRED)
+### 4c. Invoke Planner Agent for tasks.md (REQUIRED)
 ```typescript
-Skill({ skill: "sw:test-aware-planner", args: "Generate tasks for increment XXXX-name based on spec.md and plan.md" })
+Agent({ subagent_type: "sw-planner", prompt: "Generate tasks for increment XXXX-name. Read spec.md at .specweave/increments/XXXX-name/spec.md and plan.md at .specweave/increments/XXXX-name/plan.md" })
 ```
 
 **Order matters**: PM first (spec.md) -> Architect second (plan.md) -> Planner last (tasks.md).
-Each skill reads the output of the previous one.
+Each agent reads the output of the previous one.
 
 ## Step 5: Post-Creation Sync
 
@@ -454,7 +438,7 @@ Created increment 0003-user-authentication
 
 - `.specweave/` not found: "Run specweave init first"
 - Vague description: Ask clarifying questions
-- Skill fails: Fall back to keyword prompts for PM/Architect skills
+- Agent fails: Fall back to invoking `/sw:pm` or `/sw:architect` skills directly
 
 ---
 

package/plugins/specweave-github/hooks/github-auto-create-handler.sh

@@ -315,12 +315,13 @@ extract_acs_for_us() {
       continue
     fi
     # Start of next US section or next ## section — stop
-    if $in_section && [[ "$line" =~ ^##[[:space:]] ]]; then
+    if $in_section && { [[ "$line" =~ ^###[[:space:]]+US- ]] || [[ "$line" =~ ^##[[:space:]] ]]; }; then
       break
     fi
     # Inside our section, look for AC lines
     if $in_section; then
-      if [[ "$line" =~ ^\*\*Acceptance[[:space:]]Criteria ]]; then
+      # Acceptance Criteria heading: both bold (**AC**) and heading (#### AC) formats
+      if [[ "$line" =~ ^\*\*Acceptance[[:space:]]Criteria ]] || [[ "$line" =~ ^#+[[:space:]]+Acceptance[[:space:]]Criteria ]]; then
         in_ac=true
         continue
       fi
@@ -372,10 +373,13 @@ extract_desc_for_us() {
     fi
     if $in_section; then
       # Stop at next US heading, next ## section, or Acceptance Criteria
+      # Match ## but NOT ### or ####: ^##[[:space:]] catches "## Heading"
+      # Match ### US- for next user story: ^###[[:space:]]+US-
       if [[ "$line" =~ ^###[[:space:]]+US- ]] || [[ "$line" =~ ^##[[:space:]] ]]; then
         break
       fi
-      if [[ "$line" =~ ^\*\*Acceptance[[:space:]]Criteria ]]; then
+      # Acceptance Criteria heading: both bold (**AC**) and heading (#### AC) formats
+      if [[ "$line" =~ ^\*\*Acceptance[[:space:]]Criteria ]] || [[ "$line" =~ ^#+[[:space:]]+Acceptance[[:space:]]Criteria ]]; then
         break
       fi
       # Collect non-empty lines as description

package/plugins/specweave-github/lib/github-ac-comment-poster.js

@@ -2,7 +2,6 @@ import { readFile } from "fs/promises";
 import { existsSync } from "fs";
 import * as path from "path";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
-import { pushSyncUserStories } from "./github-push-sync.js";
 async function postACProgressComments(incrementId, affectedUSIds, specPath, options) {
   const result = { posted: [], errors: [] };
   if (affectedUSIds.length === 0) {
@@ -41,15 +40,14 @@ async function postACProgressComments(incrementId, affectedUSIds, specPath, opti
         error: execResult.stderr || "Unknown error posting comment"
       });
     }
-    const usForSync = buildUserStoryForSync(content, usId, acStates, incrementId);
-    if (usForSync) {
+    if (acStates.length > 0) {
       try {
-        await pushSyncUserStories([usForSync], {
-          owner: options.owner,
-          repo: options.repo,
-          token: options.token
+        await patchIssueBodyCheckboxes(link.issueNumber, acStates, repoSlug, env);
+      } catch (patchErr) {
+        result.errors.push({
+          usId,
+          error: `body-patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`
         });
-      } catch {
       }
     }
   }
@@ -92,7 +90,7 @@ function parseACStatesForUS(content, usId) {
   const states = [];
   const usNum = String(parseInt(usId.replace("US-", ""), 10));
   const acPattern = new RegExp(
-    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    `- \\[([ x])\\] (?:\\*\\*)?AC-US${usNum}-(\\d+)(?:\\*\\*)?:\\s*(.+)`,
     "g"
   );
   let match;
@@ -105,24 +103,6 @@ function parseACStatesForUS(content, usId) {
   }
   return states;
 }
-function buildUserStoryForSync(content, usId, acStates, incrementId) {
-  const usNum = String(parseInt(usId.replace("US-", ""), 10)).padStart(3, "0");
-  const titleMatch = content.match(new RegExp(`### US-${usNum}:\\s*(.+)`));
-  const title = titleMatch ? titleMatch[1].trim() : usId;
-  return {
-    id: usId,
-    title,
-    description: "",
-    priority: "P1",
-    status: "in-progress",
-    acceptanceCriteria: acStates.map((ac) => ({
-      id: ac.id,
-      description: ac.description,
-      completed: ac.completed
-    })),
-    specId: incrementId
-  };
-}
 function buildProgressCommentForUS(incrementId, usId, acStates) {
   const total = acStates.length;
   const completed = acStates.filter((ac) => ac.completed).length;
@@ -157,6 +137,35 @@ function buildProgressCommentForUS(incrementId, usId, acStates) {
 `;
   return comment;
 }
+async function patchIssueBodyCheckboxes(issueNumber, acStates, repoSlug, env) {
+  const acMap = new Map(acStates.map((ac) => [ac.id, ac.completed]));
+  const fetchResult = await execFileNoThrow(
+    "gh",
+    ["issue", "view", String(issueNumber), "--json", "body", "-q", ".body", "-R", repoSlug],
+    env ? { env } : {}
+  );
+  if (!fetchResult.success || !fetchResult.stdout) return;
+  const body = fetchResult.stdout;
+  const patchedBody = body.replace(
+    /^(- \[)[ x](\] (?:\*\*)?)(AC-[A-Z0-9]+-\d+)((?:\*\*)?: .+)$/gm,
+    (_match, prefix, mid, acId, suffix) => {
+      const completed = acMap.get(acId);
+      if (completed !== void 0) {
+        return `${prefix}${completed ? "x" : " "}${mid}${acId}${suffix}`;
+      }
+      return _match;
+    }
+  );
+  if (patchedBody === body) return;
+  const editResult = await execFileNoThrow(
+    "gh",
+    ["issue", "edit", String(issueNumber), "--body", patchedBody, "-R", repoSlug],
+    env ? { env } : {}
+  );
+  if (!editResult.success) {
+    throw new Error(editResult.stderr || "Failed to update issue body");
+  }
+}
 export {
   postACProgressComments
 };

package/plugins/specweave-github/lib/github-ac-comment-poster.ts

@@ -12,8 +12,6 @@ import { readFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
-import { pushSyncUserStories } from './github-push-sync.js';
-import type { UserStoryForSync } from './github-push-sync.js';
 
 export interface CommentPostOptions {
   owner: string;
@@ -99,17 +97,16 @@ export async function postACProgressComments(
       });
     }
 
-    // Targeted push-sync: update issue body with current AC states
-    const usForSync = buildUserStoryForSync(content, usId, acStates, incrementId);
-    if (usForSync) {
+    // Patch AC checkboxes directly in the issue body using the known issue number
+    if (acStates.length > 0) {
       try {
-        await pushSyncUserStories([usForSync], {
-          owner: options.owner,
-          repo: options.repo,
-          token: options.token,
+        await patchIssueBodyCheckboxes(link.issueNumber, acStates, repoSlug, env);
+      } catch (patchErr) {
+        // Body patch failure is non-blocking but should be visible
+        result.errors.push({
+          usId,
+          error: `body-patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`,
         });
-      } catch {
-        // Push-sync failure is non-blocking
       }
     }
   }
@@ -177,8 +174,9 @@ function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
   // AC IDs use unpadded US number: US-001 → AC-US1-XX
   const usNum = String(parseInt(usId.replace('US-', ''), 10));
 
+  // Support both bold (**AC-US1-01**:) and plain (AC-US1-01:) formats
   const acPattern = new RegExp(
-    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    `- \\[([ x])\\] (?:\\*\\*)?AC-US${usNum}-(\\d+)(?:\\*\\*)?:\\s*(.+)`,
     'g',
   );
 
@@ -194,35 +192,6 @@ function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
   return states;
 }
 
-/**
- * Build a UserStoryForSync object for targeted push-sync.
- */
-function buildUserStoryForSync(
-  content: string,
-  usId: string,
-  acStates: ParsedACState[],
-  incrementId: string,
-): UserStoryForSync | null {
-  // Extract US title from content
-  const usNum = String(parseInt(usId.replace('US-', ''), 10)).padStart(3, '0');
-  const titleMatch = content.match(new RegExp(`### US-${usNum}:\\s*(.+)`));
-  const title = titleMatch ? titleMatch[1].trim() : usId;
-
-  return {
-    id: usId,
-    title,
-    description: '',
-    priority: 'P1',
-    status: 'in-progress',
-    acceptanceCriteria: acStates.map(ac => ({
-      id: ac.id,
-      description: ac.description,
-      completed: ac.completed,
-    })),
-    specId: incrementId,
-  };
-}
-
 /**
  * Build a progress comment for a specific user story.
  * Follows ProgressCommentBuilder format: percentage, AC checkboxes, timestamp.
@@ -260,3 +229,51 @@ function buildProgressCommentForUS(
 
   return comment;
 }
+
+/**
+ * Patch AC checkboxes in the GitHub issue body in-place.
+ * Fetches the current body, flips checkboxes to match local AC states,
+ * and updates the issue. Only modifies lines matching AC-USXX-YY patterns.
+ */
+async function patchIssueBodyCheckboxes(
+  issueNumber: number,
+  acStates: ParsedACState[],
+  repoSlug: string,
+  env?: NodeJS.ProcessEnv,
+): Promise<void> {
+  // Build a map of AC ID → completed
+  const acMap = new Map(acStates.map(ac => [ac.id, ac.completed]));
+
+  // Fetch current issue body
+  const fetchResult = await execFileNoThrow(
+    'gh',
+    ['issue', 'view', String(issueNumber), '--json', 'body', '-q', '.body', '-R', repoSlug],
+    env ? { env } : {},
+  );
+  if (!fetchResult.success || !fetchResult.stdout) return;
+
+  const body = fetchResult.stdout;
+
+  // Patch AC checkboxes: match both bold and plain AC-ID patterns
+  const patchedBody = body.replace(
+    /^(- \[)[ x](\] (?:\*\*)?)(AC-[A-Z0-9]+-\d+)((?:\*\*)?: .+)$/gm,
+    (_match: string, prefix: string, mid: string, acId: string, suffix: string) => {
+      const completed = acMap.get(acId);
+      if (completed !== undefined) {
+        return `${prefix}${completed ? 'x' : ' '}${mid}${acId}${suffix}`;
+      }
+      return _match;
+    },
+  );
+
+  if (patchedBody === body) return; // No changes needed
+
+  const editResult = await execFileNoThrow(
+    'gh',
+    ['issue', 'edit', String(issueNumber), '--body', patchedBody, '-R', repoSlug],
+    env ? { env } : {},
+  );
+  if (!editResult.success) {
+    throw new Error(editResult.stderr || 'Failed to update issue body');
+  }
+}

package/plugins/specweave-github/lib/github-push-sync.js

@@ -50,6 +50,8 @@ async function searchIssueByPrefix(usId, repoSlug, env) {
     "list",
     "--repo",
     repoSlug,
+    "--state",
+    "all",
     "--search",
     `[${usId}] in:title`,
     "--json",

package/plugins/specweave-github/lib/github-push-sync.ts

@@ -102,6 +102,7 @@ async function searchIssueByPrefix(
   const res = await execFileNoThrow('gh', [
     'issue', 'list',
     '--repo', repoSlug,
+    '--state', 'all',
     '--search', `[${usId}] in:title`,
     '--json', 'number,title,node_id',
     '--limit', '1',

package/plugins/specweave-github/lib/github-us-auto-closer.js

@@ -158,7 +158,7 @@ function parseACStatesForUS(content, usId) {
   const states = [];
   const usNum = String(parseInt(usId.replace("US-", ""), 10));
   const acPattern = new RegExp(
-    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    `- \\[([ x])\\] (?:\\*\\*)?AC-US${usNum}-(\\d+)(?:\\*\\*)?:\\s*(.+)`,
     "g"
   );
   let match;

package/plugins/specweave-github/lib/github-us-auto-closer.ts

@@ -275,8 +275,9 @@ function parseACStatesForUS(content: string, usId: string): ParsedACState[] {
   // AC IDs use unpadded US number: US-001 → AC-US1-XX
   const usNum = String(parseInt(usId.replace('US-', ''), 10));
 
+  // Support both bold (**AC-US1-01**:) and plain (AC-US1-01:) formats
   const acPattern = new RegExp(
-    `- \\[([ x])\\] \\*\\*AC-US${usNum}-(\\d+)\\*\\*:\\s*(.+)`,
+    `- \\[([ x])\\] (?:\\*\\*)?AC-US${usNum}-(\\d+)(?:\\*\\*)?:\\s*(.+)`,
     'g',
   );