specweave 1.0.488 → 1.0.489

package/plugins/specweave/skills/code-reviewer/agents/reviewer-types.md

@@ -0,0 +1,68 @@
+You are the TYPE DESIGN REVIEWER agent.
+
+REVIEW TARGET: [REVIEW_TARGET]
+
+MISSION:
+  Analyze type system quality — find overly broad types, unsafe assertions, missing
+  invariants, and type designs that don't leverage the compiler to prevent bugs.
+  Good types make illegal states unrepresentable. Your job is to find where the type
+  system could work harder. You are a read-only analyst — FIND issues, not fix them.
+
+SCOPE:
+  - If reviewing a PR: run `gh pr diff [PR_NUMBER]` to get the diff, then analyze changed files
+  - If reviewing a module: read all files in the target path
+  - Focus on TypeScript/JavaScript files (.ts, .tsx, .js, .jsx)
+  - Skip type-checking config files, test fixtures, and generated code
+
+CHECKLIST:
+  1. Explicit `any` type usage — should almost always be `unknown` or a proper type
+  2. Type assertions (`as Type`, `!` non-null) that bypass the type system unsafely
+  3. Overly broad types (string where a union literal is appropriate, e.g., status: string vs status: "active" | "inactive")
+  4. Missing discriminated unions for state machines or multi-state objects
+  5. Interface vs type alias misuse (interfaces for objects, types for unions/intersections)
+  6. Generic types that could be more constrained (T vs T extends SomeBase)
+  7. Missing readonly modifiers on data that should be immutable
+  8. Index signatures ([key: string]: any) when specific keys are known
+  9. Function return types that are too wide (returns string | number | undefined when narrowable)
+  10. Missing or incorrect type predicates and type guards
+  11. Zod/io-ts/valibot schemas that diverge from their TypeScript type counterparts
+  12. Enums used where const objects or union types would be safer and more tree-shakeable
+
+OUTPUT FORMAT:
+  Produce a structured findings report using this format for each finding:
+
+  ### [SEVERITY]: [Title]
+  - **File**: path/to/file.ts:line
+  - **Category**: Type issue (e.g., Unsafe assertion, Overly broad type, Missing discriminant)
+  - **Description**: What the type issue is and what it allows that shouldn't be possible
+  - **Impact**: What bugs this enables (runtime type errors, invalid state, refactoring hazard)
+  - **Recommendation**: The better type design with code example
+  - **Code snippet**: The current type (keep brief)
+
+  Severity levels: CRITICAL | HIGH | MEDIUM | LOW | INFO
+
+COMMUNICATION:
+  When done, signal completion:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "REVIEW_COMPLETE: Type design review finished. Found [N] issues: [X critical, Y high, Z medium]. Key findings: [brief summary of top 3].",
+    summary: "Type design review complete"
+  })
+
+  If you need clarification about type conventions:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "REVIEW_QUESTION: [your question]",
+    summary: "Type reviewer needs clarification"
+  })
+
+RULES:
+  - READ-ONLY: Do not modify any files
+  - Be specific: include file paths and line numbers for every finding
+  - Prioritize: CRITICAL and HIGH findings first
+  - No speculation: only report issues with concrete reasoning about what goes wrong
+  - Consider project style: if the project consistently uses a pattern, note it but don't fight it
+  - Skip generated code: don't flag types in auto-generated files (prisma client, graphql codegen)
+  - TypeScript/JavaScript only: skip non-TS files entirely

package/plugins/specweave/skills/skill-gen/SKILL.md

@@ -52,13 +52,18 @@ Wait for the user to select a pattern by name or number. The user responds in na
 
 ### Step 4: Check Skill-Creator Plugin
 
-Verify Anthropic's official skill-creator is available:
+Verify Anthropic's official skill-creator is available (local-first, then global fallback):
 
 ```bash
-SKILL_CREATOR_PATH=$(find ~/.claude/plugins/cache/claude-plugins-official/skill-creator -name "SKILL.md" -maxdepth 3 2>/dev/null | head -1)
+# Check local project copy first (auto-installed by specweave init)
+SKILL_CREATOR_PATH=".claude/skills/skill-creator/SKILL.md"
+if [ ! -f "$SKILL_CREATOR_PATH" ]; then
+  # Fall back to global plugin cache
+  SKILL_CREATOR_PATH=$(find ~/.claude/plugins/cache/claude-plugins-official/skill-creator -name "SKILL.md" -maxdepth 3 2>/dev/null | head -1)
+fi
 if [ -z "$SKILL_CREATOR_PATH" ]; then
   echo "ERROR: Anthropic's skill-creator plugin is not installed."
-  echo "Install it via: claude plugin install skill-creator"
+  echo "Install it via: claude install-skill https://github.com/anthropics/claude-code/tree/main/skill-creator"
   echo ""
   echo "The skill-creator is required to build tested, benchmarked skills."
   exit 1
@@ -67,6 +72,18 @@ fi
 
 ### Step 5: Delegate to Skill-Creator
 
+**Slug dedup guard** — before delegating, check if a skill with this slug already exists:
+
+```bash
+SKILL_SLUG="$SELECTED_PATTERN_SLUG"   # e.g. "error-handling"
+SKILL_DIR=".claude/skills/$SKILL_SLUG"
+if [ -d "$SKILL_DIR" ] && [ -f "$SKILL_DIR/SKILL.md" ]; then
+  echo "Skill '$SKILL_SLUG' already exists at $SKILL_DIR/SKILL.md -- skipping generation."
+  # Mark signal as generated in skill-signals.json and continue to next pattern
+  exit 0
+fi
+```
+
 Invoke the skill-creator with the selected pattern context:
 
 1. **Provide context** to skill-creator:

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

@@ -114,6 +114,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
   // ==========================================================================

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

@@ -8,6 +8,7 @@
  */
 
 import https from 'https';
+import { AdoRateLimiter } from './ado-rate-limiter.js';
 
 // ============================================================================
 // Types
@@ -20,6 +21,8 @@ export interface AdoConfig {
   workItemType?: 'Epic' | 'Feature' | 'User Story';
   areaPath?: string;
   iterationPath?: string;
+  /** Optional rate limiter instance (shared across client instances) */
+  rateLimiter?: AdoRateLimiter;
 }
 
 export interface WorkItem {
@@ -207,6 +210,21 @@ export class AdoClient {
     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: number): Promise<{ state: string; modifiedAt: Date }> {
+    const url = `${this.baseUrl}/_apis/wit/workitems/${id}?$select=System.State,System.ChangedDate&api-version=7.1`;
+    const item = await this.request<WorkItem>('GET', url);
+    return {
+      state: item.fields['System.State'],
+      modifiedAt: new Date(item.fields['System.ChangedDate']),
+    };
+  }
+
   // ==========================================================================
   // Comment Operations
   // ==========================================================================

package/plugins/specweave-ado/lib/ado-pull-sync.js

@@ -0,0 +1,35 @@
+function mapAdoStateToSpecweave(adoState) {
+  const map = {
+    "New": "planned",
+    "To Do": "planned",
+    "Active": "active",
+    "Doing": "active",
+    "In Progress": "active",
+    "Resolved": "completed",
+    "Closed": "completed",
+    "Done": "completed",
+    "Removed": "abandoned"
+  };
+  return map[adoState] ?? "active";
+}
+function pullAdoChanges(ctx) {
+  if (!ctx.canUpsertInternalItems) {
+    return { changed: false, reason: "canUpsertInternalItems is false" };
+  }
+  const mappedStatus = mapAdoStateToSpecweave(ctx.adoState);
+  if (mappedStatus === ctx.localStatus) {
+    return { changed: false, reason: "states are equivalent" };
+  }
+  if (ctx.adoModifiedAt.getTime() <= ctx.localUpdatedAt.getTime()) {
+    return { changed: false, reason: "local is newer" };
+  }
+  return {
+    changed: true,
+    newStatus: mappedStatus,
+    reason: `ADO state "${ctx.adoState}" is newer \u2014 updating to "${mappedStatus}"`
+  };
+}
+export {
+  mapAdoStateToSpecweave,
+  pullAdoChanges
+};

package/plugins/specweave-ado/lib/ado-pull-sync.ts

@@ -0,0 +1,74 @@
+/**
+ * ADO Pull Sync — Bidirectional state synchronization
+ *
+ * Implements last-write-wins conflict resolution for pulling
+ * ADO work item state changes back into SpecWeave metadata.
+ *
+ * @module ado-pull-sync
+ */
+
+export interface PullSyncContext {
+  localStatus: string;
+  localUpdatedAt: Date;
+  adoState: string;
+  adoModifiedAt: Date;
+  workItemId: number;
+  canUpsertInternalItems: boolean;
+}
+
+export interface PullSyncResult {
+  changed: boolean;
+  newStatus?: string;
+  reason?: string;
+}
+
+/**
+ * Map ADO work item states to SpecWeave statuses.
+ *
+ * Covers Agile/Scrum/Basic process templates.
+ */
+export function mapAdoStateToSpecweave(adoState: string): string {
+  const map: Record<string, string> = {
+    'New': 'planned',
+    'To Do': 'planned',
+    'Active': 'active',
+    'Doing': 'active',
+    'In Progress': 'active',
+    'Resolved': 'completed',
+    'Closed': 'completed',
+    'Done': 'completed',
+    'Removed': 'abandoned',
+  };
+
+  return map[adoState] ?? 'active';
+}
+
+/**
+ * Determine if ADO changes should override local state.
+ *
+ * Uses last-write-wins: if ADO was modified more recently than local,
+ * and the mapped state differs, update local metadata.
+ */
+export function pullAdoChanges(ctx: PullSyncContext): PullSyncResult {
+  if (!ctx.canUpsertInternalItems) {
+    return { changed: false, reason: 'canUpsertInternalItems is false' };
+  }
+
+  const mappedStatus = mapAdoStateToSpecweave(ctx.adoState);
+
+  // Same effective status — no change needed
+  if (mappedStatus === ctx.localStatus) {
+    return { changed: false, reason: 'states are equivalent' };
+  }
+
+  // Last-write-wins: ADO must be newer
+  if (ctx.adoModifiedAt.getTime() <= ctx.localUpdatedAt.getTime()) {
+    return { changed: false, reason: 'local is newer' };
+  }
+
+  return {
+    changed: true,
+    newStatus: mappedStatus,
+    reason: `ADO state "${ctx.adoState}" is newer — updating to "${mappedStatus}"`,
+  };
+}