specweave 1.0.488 → 1.0.490

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Orchestrate multi-agent parallel development with domain-specialized agents. PROACTIVELY invoke this skill (without user asking) when you detect an implementation task spanning 3+ domains (frontend, backend, database, devops, testing, security, mobile) OR 15+ tasks in tasks.md. Warn the user about higher token cost but recommend it for quality. Also use when user says "team setup", "parallel agents", "team lead", or "agent teams".
+description: Phase-agnostic orchestrator for parallel multi-agent work — brainstorm, plan, implement, review, research, or test. Auto-detects mode from intent. Use for implementation (3+ domains or 15+ tasks), brainstorming (multiple perspectives), parallel planning (PM + Architect), code review (delegates to /sw:code-reviewer), research (multiple topics), or testing (parallel test layers). Also use when user says "team setup", "parallel agents", "team lead", "agent teams", "brainstorm with agents", "plan in parallel", "review code", "research this".
 hooks:
   PreToolUse:
     - matcher: TeamCreate
@@ -62,12 +62,164 @@ hooks:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--dry-run` | Show proposed agent plan without launching | false |
+| `--mode` | Force operating mode: `brainstorm`, `plan`, `implement`, `review`, `research`, `test` | auto-detect |
 | `--domains` | Override domain detection (e.g., `--domains frontend,backend,testing`) | auto-detect |
 | `--max-agents` | Maximum number of concurrent agents | 6 |
 
 ---
 
-## 0. Increment Pre-Flight (CONDITIONAL)
+## 0. Mode Detection (BEFORE Increment Pre-Flight)
+
+**Detect operating mode FIRST. This determines the entire workflow path.**
+
+### Detection Rules (priority order)
+
+1. **Explicit flag**: `--mode brainstorm|plan|implement|review|research|test`
+2. **team_name prefix**: `review-*`, `brainstorm-*`, `research-*`, `plan-*`, `test-*`
+3. **Intent keywords** in the user's request:
+
+| Keywords | Mode | Go To |
+|----------|------|-------|
+| "brainstorm", "ideate", "explore ideas", "what if", "pros and cons" | BRAINSTORM | Section 0a |
+| "plan", "spec", "design", "architect", "define requirements" | PLANNING | Section 0b |
+| "implement", "build", "code", "develop" *(or default)* | IMPLEMENTATION | Section 1 |
+| "review", "audit", "check code", "review PR", "code quality" | REVIEW | Section 0c |
+| "research", "investigate", "analyze", "explore codebase" | RESEARCH | Section 0d |
+| "test", "write tests", "test strategy", "test coverage" | TESTING | Section 0e |
+
+4. **Default**: IMPLEMENTATION mode if no keywords match.
+
+### Mode Configuration
+
+| Mode | Increment? | Agent Templates | Coordination | Output |
+|------|-----------|-----------------|--------------|--------|
+| BRAINSTORM | No | brainstorm-advocate, brainstorm-critic, brainstorm-pragmatist | Parallel → synthesize | Decision matrix |
+| PLANNING | Creates one | pm, architect (+ optional security reviewer) | PM first → Architect parallel | spec.md, plan.md, tasks.md |
+| IMPLEMENTATION | Required | backend, frontend, database, testing, security | Contract-first phases | Working code |
+| REVIEW | Optional | Delegates to /sw:code-reviewer | Parallel | Review report |
+| RESEARCH | No | researcher (1-3 instances) | Parallel → merge | Research report |
+| TESTING | Required | testing (split by layer) | Parallel | Test suites |
+
+---
+
+### 0a. BRAINSTORM Mode
+
+**team_name**: `brainstorm-{topic-slug}`
+
+Skip increment pre-flight entirely. Brainstorm doesn't need a spec — it explores possibilities.
+
+1. Create team: `TeamCreate({ team_name: "brainstorm-{slug}", description: "Brainstorm: {topic}" })`
+2. Read agent templates from `agents/brainstorm-advocate.md`, `agents/brainstorm-critic.md`, `agents/brainstorm-pragmatist.md`
+3. Replace `[BRAINSTORM_QUESTION]` with the user's question/topic
+4. Spawn all 3 agents in parallel via `Task()` with `mode: "bypassPermissions"`
+5. Collect `PERSPECTIVE_COMPLETE:` messages from all agents
+6. Synthesize perspectives into a decision matrix:
+   - Compare approaches across dimensions (effort, risk, value, alignment)
+   - Highlight points of agreement and disagreement
+   - Provide a ranked recommendation
+7. Offer handoff: "Ready to proceed? Run `/sw:increment` to formalize the chosen approach."
+8. Cleanup: shutdown agents, TeamDelete
+9. **STOP** — do not proceed to implementation sections
+
+---
+
+### 0b. PLANNING Mode
+
+**team_name**: `plan-{feature-slug}`
+
+Planning mode runs PM and Architect agents in parallel for richer, faster spec creation.
+
+1. **Check for existing increment**:
+   - If increment exists: read it as context, agents will update/enhance its spec and plan
+   - If no increment: create one (folder + metadata.json only, agents will write spec/plan)
+
+2. **Phase 1 — PM Agent** (upstream):
+   - Read `agents/pm.md`, replace `[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`, `[FEATURE_DESCRIPTION]`
+   - Spawn via `Task()` with `mode: "bypassPermissions"`
+   - PM writes spec.md with user stories and ACs
+   - Wait for PM's `PLAN_READY:` or `COMPLETION:` message
+
+3. **Phase 2 — Architect + Security** (parallel, after PM):
+   - Read `agents/architect.md`, replace placeholders, spawn Architect agent
+   - Optionally read `agents/reviewer-security.md` from team-lead agents, replace `[REVIEW_TARGET]` with the spec, spawn Security reviewer
+   - Both run in parallel: Architect writes plan.md, Security reviewer flags design-level vulnerabilities
+   - Wait for both `COMPLETION:` messages
+
+4. **Post-planning**:
+   - Run `specweave sync-living-docs {increment-id}` to sync external tools
+   - Present the spec + plan summary to the user
+   - Recommend execution strategy: `/sw:do`, `/sw:auto`, or `/sw:team-lead` (implementation mode)
+
+5. Cleanup: shutdown agents, TeamDelete
+6. **STOP** — do not proceed to implementation sections
+
+---
+
+### 0c. REVIEW Mode
+
+**Delegates entirely to `/sw:code-reviewer`.**
+
+Team-lead does NOT spawn its own reviewer agents for review mode. The code-reviewer skill handles its own orchestration with 6 specialized reviewers.
+
+```typescript
+Skill({ skill: "sw:code-reviewer", args: "<user's review target or flags>" })
+```
+
+Pass through any arguments the user provided (--pr N, --changes, --cross-repo, path).
+
+**STOP** after the skill completes — do not proceed to implementation sections.
+
+---
+
+### 0d. RESEARCH Mode
+
+**team_name**: `research-{topic-slug}`
+
+Skip increment pre-flight. Research is exploratory — no spec needed.
+
+1. Create team: `TeamCreate({ team_name: "research-{slug}", description: "Research: {topic}" })`
+2. **Determine research agents**:
+   - Single topic: spawn 1 researcher from `agents/researcher.md`
+   - Multi-faceted topic: spawn 2-3 researchers with different scopes
+     (e.g., "research auth" → one agent on OAuth providers, one on session management, one on security best practices)
+3. Replace `[RESEARCH_TOPIC]` and `[RESEARCH_SCOPE]` in each agent prompt
+4. Spawn all researchers in parallel via `Task()` with `mode: "bypassPermissions"`
+5. Collect `RESEARCH_COMPLETE:` messages
+6. Merge findings into a unified research report:
+   - Cross-reference findings between agents
+   - Resolve contradictions
+   - Produce ranked recommendations
+7. Offer handoff: `/sw:increment` (to act on findings) or `/sw:brainstorm` (to explore approaches)
+8. Cleanup: shutdown agents, TeamDelete
+9. **STOP** — do not proceed to implementation sections
+
+---
+
+### 0e. TESTING Mode
+
+**team_name**: `test-{increment-id}`
+
+Testing mode requires an increment (it needs to know WHAT to test).
+
+1. **Verify increment exists** (same as implementation mode — see below)
+2. Create team: `TeamCreate({ team_name: "test-{id}", description: "Testing: {increment}" })`
+3. Spawn testing agents split by layer:
+   - **Unit test agent**: read `agents/testing.md`, override scope to unit tests only
+   - **E2E test agent**: read `agents/testing.md`, override scope to E2E tests only
+   - Split scope via the agent prompt, not via separate templates
+4. Spawn both in parallel via `Task()` with `mode: "bypassPermissions"`
+5. Collect `COMPLETION:` messages
+6. Run test suites to verify: `npx vitest run` + `npx playwright test`
+7. Report results: pass/fail counts, coverage, uncovered ACs
+8. Cleanup: shutdown agents, TeamDelete
+9. **STOP** — do not proceed to implementation sections
+
+---
+
+## 0.5. Increment Pre-Flight (IMPLEMENTATION and TESTING modes only)
+
+**This section applies only to IMPLEMENTATION mode (default) and TESTING mode.**
+All other modes handle their own increment logic (or skip it entirely) in Section 0a-0e above.
 
 The team-lead works best with an increment (spec.md, plan.md, tasks.md) but can also run **without one** in free-form mode.
 
@@ -75,10 +227,9 @@ The team-lead works best with an increment (spec.md, plan.md, tasks.md) but can
 
 **Free-form mode** (no increment needed) applies when:
 - `SPECWEAVE_NO_INCREMENT=1` is set (via `specweave team --no-increment`)
-- The team_name uses a non-implementation prefix (`review-*`, `brainstorm-*`, `analysis-*`)
 - The user explicitly opted out of increment creation
 
-In free-form mode: **skip the rest of Section 0** and proceed directly to Step 1. Agents will work from the natural language description instead of a spec. Note: without a spec, `/sw:done` closure is not available — the team-lead simply coordinates agent completion.
+In free-form mode: **skip the rest of Section 0.5** and proceed directly to Step 1. Agents will work from the natural language description instead of a spec. Note: without a spec, `/sw:done` closure is not available — the team-lead simply coordinates agent completion.
 
 ### Standard mode: Verify increment exists
 

package/plugins/specweave/skills/team-lead/agents/architect.md

@@ -0,0 +1,52 @@
+You are the ARCHITECT PLANNING agent for increment [INCREMENT_ID].
+
+MASTER SPEC (SOURCE OF TRUTH):
+  The feature is specified in [MASTER_INCREMENT_PATH]/spec.md.
+  Read the spec BEFORE designing anything. Your architecture MUST satisfy all ACs.
+
+MISSION:
+  Produce plan.md with system architecture, component design, and ADRs for key decisions.
+  You own the HOW — defining the technical approach. You work in parallel with
+  the Security reviewer who validates your design for vulnerabilities.
+
+SKILLS TO INVOKE:
+  Skill({ skill: "sw:architect" })
+
+FILE OWNERSHIP (WRITE access):
+  [MASTER_INCREMENT_PATH]/plan.md
+  .specweave/docs/internal/architecture/adr/    (new ADRs only)
+
+READ ACCESS: Any file in the repository
+
+UPSTREAM DEPENDENCY:
+  Wait for the PM agent to signal PLAN_READY or COMPLETION before starting.
+  You need spec.md to exist with user stories and ACs before you can design.
+
+WORKFLOW:
+  1. Read spec.md at [MASTER_INCREMENT_PATH]/spec.md
+  2. Explore the codebase to understand existing architecture, patterns, and tech stack
+  3. Check existing ADRs at .specweave/docs/internal/architecture/adr/
+  4. Design system architecture:
+     - Component boundaries and responsibilities
+     - Data flow and state management
+     - API contracts and integration points
+     - Error handling strategy
+     - Performance considerations
+  5. Write ADRs for significant architectural decisions (use ADR template format)
+  6. Write plan.md to [MASTER_INCREMENT_PATH]/plan.md
+  7. Signal architecture decisions:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "CONTRACT_READY: Architecture defined in plan.md.\nComponents: [list]\nKey patterns: [e.g., CQRS, event-driven]\nADRs created: [list or 'none']\nTech stack: [decisions]",
+       summary: "Architect: plan.md ready with architecture" })
+  8. Signal COMPLETION:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "COMPLETION: plan.md finalized.\nComponents: [count]\nADRs: [count]\nKey risk: [biggest concern]",
+       summary: "Architect agent: plan complete" })
+
+RULES:
+  - WRITE only plan.md and ADRs — do not modify spec.md or create tasks.md
+  - Every architectural decision must be justified (not just "use X because it's popular")
+  - Consider scalability, maintainability, testability, and security
+  - Reference existing codebase patterns — don't propose patterns alien to the project
+  - Flag technical risks and mitigation strategies
+  - Keep plan.md actionable — an implementer should be able to code from it

package/plugins/specweave/skills/team-lead/agents/pm.md

@@ -0,0 +1,50 @@
+You are the PM PLANNING agent for increment [INCREMENT_ID].
+
+FEATURE DESCRIPTION: [FEATURE_DESCRIPTION]
+
+MASTER INCREMENT PATH: [MASTER_INCREMENT_PATH]
+
+MISSION:
+  Produce a comprehensive spec.md with user stories, acceptance criteria, and scope
+  boundaries. You own the WHAT — defining what the feature does and how success is
+  measured. You work in parallel with the Architect agent who owns the HOW.
+
+SKILLS TO INVOKE:
+  Skill({ skill: "sw:pm" })
+
+FILE OWNERSHIP (WRITE access):
+  [MASTER_INCREMENT_PATH]/spec.md
+
+READ ACCESS: Any file in the repository (for understanding existing patterns and domain)
+
+WORKFLOW:
+  1. Read the feature description and any existing context
+  2. Explore the codebase to understand the domain, existing patterns, and constraints
+  3. Identify stakeholders, personas, and key use cases
+  4. Write user stories with acceptance criteria following the format:
+     ### US-NNN: Story Title
+     **Project**: [project-name]
+     **As a** [role]
+     **I want** [capability]
+     **So that** [benefit]
+     **Acceptance Criteria**:
+     - [ ] **AC-USNN-01**: [Criterion]
+  5. Define scope boundaries (in-scope vs out-of-scope)
+  6. Write spec.md to [MASTER_INCREMENT_PATH]/spec.md
+  7. Send PLAN_READY notification (do NOT wait for response):
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "PLAN_READY: spec.md written at [MASTER_INCREMENT_PATH]/spec.md\nUser Stories: [count]\nACs: [count]\nKey decisions: [1-2 sentence summary]",
+       summary: "PM: spec.md ready — proceeding" })
+  8. Proceed immediately. If team-lead sends PLAN_CORRECTION, revise spec.md accordingly.
+  9. Signal COMPLETION:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "COMPLETION: spec.md finalized.\nStories: [count]\nACs: [count]\nScope: [brief summary]",
+       summary: "PM agent: spec complete" })
+
+RULES:
+  - WRITE only spec.md — do not create plan.md or tasks.md (Architect and Planner own those)
+  - Every user story MUST have a **Project**: field
+  - Every AC MUST use the AC-USNN-NN format for bidirectional linking
+  - Be specific in ACs — testable, not vague ("user can log in" not "auth works")
+  - Consider edge cases, error states, and non-functional requirements
+  - Do NOT scope-creep — stick to the feature description

package/plugins/specweave/skills/team-lead/agents/researcher.md

@@ -0,0 +1,64 @@
+You are the RESEARCHER agent.
+
+RESEARCH TOPIC: [RESEARCH_TOPIC]
+RESEARCH SCOPE: [RESEARCH_SCOPE]
+
+MISSION:
+  Investigate the given topic thoroughly — explore the codebase, search the web,
+  analyze patterns, and compile actionable findings. You are a read-only analyst.
+  Your job is to FIND information, not implement changes.
+
+APPROACH:
+  1. Parse the research scope to understand what information is needed
+  2. Explore the codebase for relevant patterns, implementations, and conventions
+  3. Search the web for related technologies, best practices, and alternatives
+  4. Cross-reference findings — validate web claims against actual codebase state
+  5. Compile a structured research report
+
+YOUR REPORT MUST INCLUDE:
+
+  ### Executive Summary
+  2-3 sentence overview of key findings and recommendation.
+
+  ### Current State
+  What exists today in the codebase. Include file paths and line references.
+
+  ### External Research
+  What the broader ecosystem offers. Technologies, libraries, patterns considered.
+  Include sources and links where relevant.
+
+  ### Analysis
+  Compare options. Use a decision matrix if comparing 3+ alternatives:
+  | Option | Pros | Cons | Effort | Fit |
+
+  ### Recommendations
+  Concrete, actionable recommendations ranked by priority.
+  Each should include: what to do, why, and estimated effort.
+
+  ### Open Questions
+  Things that need further investigation or user input.
+
+COMMUNICATION:
+  When done, signal completion:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "RESEARCH_COMPLETE: [topic] research finished.\nKey finding: [most important insight]\nRecommendation: [primary recommendation]\nOpen questions: [count]",
+    summary: "Research complete: [topic]"
+  })
+
+  For significant discoveries during research:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "INSIGHT: [important discovery that may affect scope or approach]",
+    summary: "Researcher found insight"
+  })
+
+RULES:
+  - READ-ONLY: Do not modify any files
+  - Be thorough: explore multiple angles, not just the first result
+  - Be specific: include file paths, line numbers, URLs — not vague references
+  - Be honest: flag uncertainty and gaps in knowledge
+  - Stay scoped: answer the research question, don't expand into tangential topics
+  - Cite sources: for web findings, include the source URL or reference

package/plugins/specweave-ado/lib/ado-ac-checkbox-sync.js

@@ -5,6 +5,7 @@ import axios from "axios";
 import { consoleLogger } from "../../specweave/lib/vendor/utils/logger.js";
 import { deriveFeatureId } from "../../specweave/lib/vendor/utils/feature-id-derivation.js";
 import { GitHubACCheckboxSync } from "../../specweave-github/lib/github-ac-checkbox-sync.js";
+import { AdoDescriptionUpdater } from "../../../src/core/ado-description-updater.js";
 class AdoACCheckboxSync {
   constructor(options) {
     this.projectRoot = options.projectRoot;
@@ -88,47 +89,48 @@ class AdoACCheckboxSync {
     }
   }
   /**
-   * Fetch current HTML description, regex-flip ☐/☑ for matching ACs, PATCH back.
-   * Posts a comment listing all AC statuses when any AC changed.
+   * Update a work item's AC section using API-based section manipulation.
+   *
+   * GET description → formatACCheckboxes → updateAcSection → PATCH with
+   * JSON Patch op:"replace". No regex used at any point.
    */
-  async updateStoryCheckboxes(client, adoConfig, storyId, acStatus) {
+  async updateWorkItemACSection(client, storyId, acStatus) {
+    const updater = new AdoDescriptionUpdater();
     const resp = await client.get(
       `/wit/workitems/${storyId}?fields=System.Description&api-version=7.0`
     );
-    let description = resp.data?.fields?.["System.Description"] ?? "";
-    const original = description;
-    let updatedCount = 0;
-    for (const [acId, completed] of acStatus) {
-      const escaped = acId.replace(/-/g, "\\-");
-      const beforeRegex = new RegExp(`(\u2610|\u2611)\\s+(${escaped}:)`, "g");
-      const newCheckbox = completed ? "\u2611" : "\u2610";
-      const replaced = description.replace(beforeRegex, `${newCheckbox} $2`);
-      if (replaced !== description) {
-        updatedCount++;
-        description = replaced;
-      }
-    }
-    if (description === original) return 0;
+    const currentDescription = resp.data?.fields?.["System.Description"] ?? "";
+    const newAcHtml = updater.formatACCheckboxes(acStatus);
+    if (!newAcHtml) return 0;
+    const updatedDescription = updater.updateAcSection(currentDescription, newAcHtml);
+    if (updatedDescription === currentDescription) return 0;
     await client.patch(
       `/wit/workitems/${storyId}?api-version=7.0`,
-      [{ op: "replace", path: "/fields/System.Description", value: description }],
+      [{ op: "replace", path: "/fields/System.Description", value: updatedDescription }],
       { headers: { "Content-Type": "application/json-patch+json" } }
     );
     const completedCount = [...acStatus.values()].filter(Boolean).length;
     const totalCount = acStatus.size;
     const percentage = Math.round(completedCount / totalCount * 100);
     const acLines = [...acStatus.entries()].map(([id, done]) => `<li>${done ? "\u2705" : "\u2B1C"} ${id}</li>`).join("\n");
-    const commentHtml = `<h3>\u{1F4CA} AC Progress Update</h3>
+    const commentHtml = `<h3>AC Progress Update</h3>
 <p><strong>Acceptance Criteria</strong>: ${completedCount}/${totalCount} (${percentage}%)</p>
 <ul>
 ${acLines}
 </ul>
-<p>\u{1F916} Auto-updated by SpecWeave AC Completion Gate</p>`;
+<p>Auto-updated by SpecWeave</p>`;
     await client.post(
       `/wit/workItems/${storyId}/comments?api-version=7.1-preview.3`,
       { text: commentHtml }
     );
-    return updatedCount;
+    return acStatus.size;
+  }
+  /**
+   * Legacy: Fetch current HTML description, regex-flip checkboxes, PATCH back.
+   * Kept for backward compatibility. New code should use updateWorkItemACSection.
+   */
+  async updateStoryCheckboxes(client, adoConfig, storyId, acStatus) {
+    return this.updateWorkItemACSection(client, storyId, acStatus);
   }
   buildClient(adoConfig) {
     const token = Buffer.from(`:${adoConfig.pat}`).toString("base64");

package/plugins/specweave-ado/lib/ado-ac-checkbox-sync.ts

@@ -2,10 +2,10 @@
  * ADO AC Checkbox Sync
  *
  * When ACs are marked complete in spec.md, updates the HTML description
- * of the linked ADO work item (☐ → ☑) and posts a progress comment.
+ * of the linked ADO work item using API-based section update (not regex).
  *
- * Mirrors jira-ac-checkbox-sync.ts pattern for ADO.
- * The ADO description is HTML — we use regex to flip ☐/☑ by AC ID.
+ * Uses AdoDescriptionUpdater for clean HTML section manipulation via
+ * sentinel comments (<!-- AC_SECTION_START/END -->).
  */
 
 import { promises as fs, existsSync } from 'fs';
@@ -15,6 +15,7 @@ import axios, { AxiosInstance } from 'axios';
 import { Logger, consoleLogger } from '../../specweave/lib/vendor/utils/logger.js';
 import { deriveFeatureId } from '../../specweave/lib/vendor/utils/feature-id-derivation.js';
 import { GitHubACCheckboxSync } from '../../specweave-github/lib/github-ac-checkbox-sync.js';
+import { AdoDescriptionUpdater } from '../../../src/core/ado-description-updater.js';
 import type { SpecWeaveConfig } from '../../../src/core/config/types.js';
 import type { LivingDocsUSFile } from '../../../src/types/living-docs-us-file.js';
 
@@ -131,41 +132,35 @@ export class AdoACCheckboxSync {
   }
 
   /**
-   * Fetch current HTML description, regex-flip ☐/☑ for matching ACs, PATCH back.
-   * Posts a comment listing all AC statuses when any AC changed.
+   * Update a work item's AC section using API-based section manipulation.
+   *
+   * GET description → formatACCheckboxes → updateAcSection → PATCH with
+   * JSON Patch op:"replace". No regex used at any point.
    */
-  private async updateStoryCheckboxes(
+  async updateWorkItemACSection(
     client: AxiosInstance,
-    adoConfig: { organization: string; project: string; pat: string },
     storyId: number,
-    acStatus: Map<string, boolean>
+    acStatus: Map<string, boolean>,
   ): Promise<number> {
+    const updater = new AdoDescriptionUpdater();
+
     const resp = await client.get(
       `/wit/workitems/${storyId}?fields=System.Description&api-version=7.0`
     );
 
-    let description: string = resp.data?.fields?.['System.Description'] ?? '';
-    const original = description;
-    let updatedCount = 0;
-
-    for (const [acId, completed] of acStatus) {
-      const escaped = acId.replace(/-/g, '\\-');
-      // Pattern: ☐ AC-US1-01: or ☑ AC-US1-01:
-      const beforeRegex = new RegExp(`(☐|☑)\\s+(${escaped}:)`, 'g');
-      const newCheckbox = completed ? '☑' : '☐';
-      const replaced = description.replace(beforeRegex, `${newCheckbox} $2`);
-      if (replaced !== description) {
-        updatedCount++;
-        description = replaced;
-      }
-    }
+    const currentDescription: string = resp.data?.fields?.['System.Description'] ?? '';
+    const newAcHtml = updater.formatACCheckboxes(acStatus);
+
+    if (!newAcHtml) return 0;
 
-    if (description === original) return 0;
+    const updatedDescription = updater.updateAcSection(currentDescription, newAcHtml);
 
-    // PATCH description
+    if (updatedDescription === currentDescription) return 0;
+
+    // PATCH description via JSON Patch
     await client.patch(
       `/wit/workitems/${storyId}?api-version=7.0`,
-      [{ op: 'replace', path: '/fields/System.Description', value: description }],
+      [{ op: 'replace', path: '/fields/System.Description', value: updatedDescription }],
       { headers: { 'Content-Type': 'application/json-patch+json' } }
     );
 
@@ -178,19 +173,32 @@ export class AdoACCheckboxSync {
       .map(([id, done]) => `<li>${done ? '✅' : '⬜'} ${id}</li>`)
       .join('\n');
 
-    const commentHtml = `<h3>📊 AC Progress Update</h3>
+    const commentHtml = `<h3>AC Progress Update</h3>
 <p><strong>Acceptance Criteria</strong>: ${completedCount}/${totalCount} (${percentage}%)</p>
 <ul>
 ${acLines}
 </ul>
-<p>🤖 Auto-updated by SpecWeave AC Completion Gate</p>`;
+<p>Auto-updated by SpecWeave</p>`;
 
     await client.post(
       `/wit/workItems/${storyId}/comments?api-version=7.1-preview.3`,
       { text: commentHtml }
     );
 
-    return updatedCount;
+    return acStatus.size;
+  }
+
+  /**
+   * Legacy: Fetch current HTML description, regex-flip checkboxes, PATCH back.
+   * Kept for backward compatibility. New code should use updateWorkItemACSection.
+   */
+  private async updateStoryCheckboxes(
+    client: AxiosInstance,
+    adoConfig: { organization: string; project: string; pat: string },
+    storyId: number,
+    acStatus: Map<string, boolean>
+  ): Promise<number> {
+    return this.updateWorkItemACSection(client, storyId, acStatus);
   }
 
   private buildClient(adoConfig: { organization: string; project: string; pat: string }): AxiosInstance {

package/plugins/specweave-ado/lib/ado-client.js

@@ -3,6 +3,7 @@ class AdoClient {
   constructor(config) {
     this.config = config;
     this.baseUrl = `https://dev.azure.com/${config.organization}/${config.project}`;
+    this.rateLimiter = config.rateLimiter;
     this.authHeader = "Basic " + Buffer.from(`:${config.personalAccessToken}`).toString("base64");
   }
   // ==========================================================================
@@ -114,6 +115,20 @@ class AdoClient {
     const url = `${this.baseUrl}/_apis/wit/workitems/${id}?api-version=7.1`;
     await this.request("DELETE", url);
   }
+  /**
+   * Pull the current state of a work item for bidirectional sync.
+   *
+   * @param id - ADO work item ID
+   * @returns state and last-modified timestamp
+   */
+  async pullWorkItemState(id) {
+    const url = `${this.baseUrl}/_apis/wit/workitems/${id}?$select=System.State,System.ChangedDate&api-version=7.1`;
+    const item = await this.request("GET", url);
+    return {
+      state: item.fields["System.State"],
+      modifiedAt: new Date(item.fields["System.ChangedDate"])
+    };
+  }
   // ==========================================================================
   // Comment Operations
   // ==========================================================================
@@ -166,6 +181,9 @@ class AdoClient {
    * Make HTTP request to ADO API
    */
   async request(method, url, body, additionalHeaders) {
+    if (this.rateLimiter && !this.rateLimiter.consume()) {
+      throw new Error("ADO rate limit exceeded \u2014 try again later");
+    }
     return new Promise((resolve, reject) => {
       const urlObj = new URL(url);
       const options = {
@@ -196,6 +214,12 @@ class AdoClient {
               reject(new Error(`Failed to parse JSON response: ${error}`));
             }
           } else {
+            if (res.statusCode === 429 && this.rateLimiter) {
+              const retryAfter = parseInt(res.headers["retry-after"], 10);
+              if (retryAfter > 0) {
+                this.rateLimiter.applyRetryAfter(retryAfter);
+              }
+            }
             let errorMessage = `ADO API error: ${res.statusCode} ${res.statusMessage}`;
             try {
               const errorData = JSON.parse(data);
@@ -204,7 +228,9 @@ class AdoClient {
               }
             } catch {
             }
-            reject(new Error(errorMessage));
+            const err = new Error(errorMessage);
+            err.status = res.statusCode;
+            reject(err);
           }
         });
       });