specweave 0.30.0 → 0.30.2

package/plugins/specweave-ado/commands/specweave-ado-sync.md

@@ -16,9 +16,9 @@ description: Two-way sync between SpecWeave increment and Azure DevOps work item
 ## Options
 
 - `--direction <mode>`: Sync direction (default: `two-way`)
-  - `two-way`: SpecWeave ↔ ADO (default - recommended)
-  - `to-ado`: SpecWeave → ADO only (push progress)
-  - `from-ado`: ADO → SpecWeave only (pull updates)
+  - `two-way`: SpecWeave <-> ADO (default - recommended)
+  - `to-ado`: SpecWeave -> ADO only (push progress)
+  - `from-ado`: ADO -> SpecWeave only (pull updates)
 
 ## Examples
 
@@ -37,112 +37,205 @@ description: Two-way sync between SpecWeave increment and Azure DevOps work item
 
 ## Command Behavior
 
-When user runs this command, invoke `ado-manager` agent to perform two-way sync:
-
-### Phase 1: Pull FROM ADO (default behavior)
-1. Fetch work item state from ADO API
-2. Detect changes in ADO:
-   - State changes (New → Active → Resolved → Closed)
-   - Priority changes
-   - Iteration/sprint changes
-   - Comments from team members
-   - Field updates
-3. Apply ADO changes to SpecWeave increment:
-   - Update increment status to match ADO state
-   - Update priority in metadata
-   - Import team comments to increment notes
-   - Update iteration tracking
-
-### Phase 2: Push TO ADO (default behavior)
-1. Read tasks.md from increment
-2. Calculate completion percentage
-3. Identify recently completed tasks
-4. Format progress update comment
-5. POST comment to ADO work item
-6. Update work item state if needed (New → Active → Resolved)
-7. Update custom fields (completion %, current task, etc.)
-
-**Agent Invocation**:
+When user runs this command, Claude should:
+
+### 1. Check Permission Gate (MANDATORY FIRST STEP)
+
+**Before ANY ADO write operations**, check permissions:
+
+```typescript
+// Read .specweave/config.json
+const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
+const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
+const canUpdateStatus = config?.sync?.settings?.canUpdateStatus ?? false;
+
+// Permission check based on direction
+if (direction === 'to-ado' || direction === 'two-way') {
+  if (!canUpdateExternal) {
+    console.log(`
+❌ Permission Denied: ADO Write Operations Disabled
+
+Cannot push changes to ADO (sync.settings.canUpdateExternalItems = false).
+
+Options:
+1. Enable writes: Set canUpdateExternalItems to true in config.json
+2. Pull-only mode: /specweave-ado:sync ${incrementId} --direction from-ado
+`);
+    return;
+  }
+}
+```
+
+For `--direction from-ado` (pull-only), permission check is skipped as it's read-only.
+
+### 2. Resolve ADO Profile
+
+Use the increment's stored profile or fall back to global activeProfile:
+
+```typescript
+// Load increment metadata
+const metadataPath = `.specweave/increments/${incrementId}/metadata.json`;
+const metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+
+// Priority: increment profile > global activeProfile
+let profileName = metadata?.external_sync?.ado?.profile;
+if (!profileName) {
+  profileName = config?.sync?.activeProfile;
+}
+
+// Validate profile exists
+const profileConfig = config?.sync?.profiles?.[profileName];
+if (!profileConfig || profileConfig.provider !== 'ado') {
+  console.log(`❌ ADO profile "${profileName}" not found`);
+  console.log('Available ADO profiles:', Object.entries(config?.sync?.profiles || {})
+    .filter(([_, p]) => p.provider === 'ado')
+    .map(([name]) => name)
+    .join(', '));
+  return;
+}
+
+const { organization, project } = profileConfig.config;
+console.log(`Using ADO profile: ${profileName}`);
+console.log(`  Organization: ${organization}`);
+console.log(`  Project: ${project}`);
+```
+
+### 3. Invoke ADO Manager Agent
+
 ```
 Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
 
-Prompt: "Two-way sync for increment 0005-payment-integration with ADO.
+Prompt: "{direction} sync for increment {increment-id} with ADO.
+
+IMPORTANT:
+- Permission verified: canUpdateExternalItems={canUpdateExternal}
+- Using profile: {profileName} (org: {organization}, project: {project})
 
 Phase 1 - Pull FROM ADO:
-1. Fetch work item #12345 from ADO API
+1. Fetch work item #{workItemId} from ADO API
 2. Detect changes: state, priority, iteration, comments
 3. Apply ADO changes to increment metadata
 4. Import team comments to increment notes
 
-Phase 2 - Push TO ADO:
-1. Read .specweave/increments/0005/tasks.md
+Phase 2 - Push TO ADO (if direction allows):
+1. Read .specweave/increments/{increment-id}/tasks.md
 2. Calculate: X/Y tasks complete (Z%)
 3. Identify: Recently completed tasks
 4. Format comment with progress update
-5. Load work item ID from increment-metadata.json
-6. POST comment to ADO API
+5. Load work item ID from metadata.json
+6. POST comment to ADO API using org: {organization}, project: {project}
 7. Update work item state/fields
 
-Display: Two-way sync summary"
+Display: Sync summary with profile used"
+```
+
+### 4. Display Result
+
+```
+Sync Summary for increment {increment-id}
+
+Profile: {profileName}
+  Organization: {organization}
+  Project: {project}
+
+Direction: {direction}
+
+FROM ADO:
+  State: Active -> Resolved
+  Priority: 2 -> 1
+  Comments: 3 new
+
+TO ADO:
+  Progress: 60% (6/10 tasks)
+  Posted comment #98765
+
+Work Item: https://dev.azure.com/{organization}/{project}/_workitems/edit/{workItemId}
 ```
 
 ---
 
+## Permission Check Matrix
+
+| Direction | canUpdateExternalItems | Result |
+|-----------|------------------------|--------|
+| from-ado | any | Allowed (read-only) |
+| to-ado | false | Denied |
+| to-ado | true | Allowed |
+| two-way | false | Denied |
+| two-way | true | Allowed |
+
+---
+
+## Profile Resolution
+
+The command resolves the ADO profile in this order:
+
+1. **Increment profile** (metadata.json -> external_sync.ado.profile)
+2. **Global profile** (config.json -> sync.activeProfile)
+
+This allows:
+- Different increments to sync to different ADO projects
+- No manual `activeProfile` switching needed
+- Automatic project targeting
+
+---
+
 ## Example Output
 
 ### Two-way Sync (Default)
 
 ```
-🔄 Two-way sync for increment 0005...
+User: /specweave-ado:sync 0005-payment-integration
 
-✓ Azure DevOps work item: #12345
-✓ Sync direction: Two-way (push & pull)
+Claude:
+Checking permissions...
+  canUpdateExternalItems: true
 
-Detecting changes (both directions)...
+Resolving ADO profile...
+  Using: ado-nova-x-sandbox (from increment)
+  Organization: nova-systems
+  Project: Nova X Sandbox
+
+Syncing...
 
 FROM ADO:
-✓ Work item state changed: Active → Resolved
-✓ Iteration updated: Sprint 23 → Sprint 24
-✓ Priority changed: 2 → 1
-✓ 3 new comments from team
-
-FROM SpecWeave:
-✓ 2 new tasks completed (T-005, T-006)
-✓ Progress: 40% → 60% (6/10 tasks)
-✓ Current task: T-007
-
-Syncing TO ADO...
-✓ Posted progress comment (ID: 98765)
-✓ Updated completion: 60%
-✓ Updated current task field: T-007
-
-Syncing FROM ADO...
-✓ Updated increment status: active → completed
-✓ Updated priority: P2 → P1
-✓ Updated iteration tracking: Sprint 24
-✓ Imported 3 team comments to increment notes
-
-✅ Bidirectional Sync Complete!
-
-   SpecWeave ↔ ADO synchronized
-   • Pushed: Progress (60%), 2 task updates
-   • Pulled: State (Resolved), priority (P1), iteration, 3 comments
-
-ADO Work Item: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
-Last synced: just now
-Next sync: Automatic (hook-based) or manual when ready
+  State changed: Active -> Resolved
+  Iteration updated: Sprint 23 -> Sprint 24
+  Priority changed: 2 -> 1
+  3 new comments from team
+
+TO ADO:
+  Progress: 60% complete (6/10 tasks)
+  Posted comment (ID: 98765)
+  Updated completion field: 60%
+
+Sync Complete!
+Profile: ado-nova-x-sandbox
+Work Item: https://dev.azure.com/nova-systems/Nova%20X%20Sandbox/_workitems/edit/12345
 ```
 
-### One-Way Sync (to-ado)
+### Permission Denied
 
 ```
-✅ Pushed to ADO Work Item #12345
+User: /specweave-ado:sync 0005 --direction to-ado
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: false
 
-Progress: 60% complete (6/10 tasks)
+Permission Denied: ADO Write Operations Disabled
 
-Recently Completed:
-- T-005: Add payment tests
-- T-006: Update documentation
+Cannot push changes to ADO.
 
-URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
+Options:
+1. Enable writes: Set sync.settings.canUpdateExternalItems = true
+2. Pull-only: /specweave-ado:sync 0005 --direction from-ado
 ```
+
+---
+
+## Related
+
+- `/specweave-ado:create-workitem` - Create new ADO work item
+- `/specweave-ado:status` - Check sync status (read-only, always allowed)
+- `/specweave-ado:close-workitem` - Close work item when complete

package/plugins/specweave-ado/lib/ado-permission-gate.js

@@ -0,0 +1,127 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+const DEFAULT_SYNC_SETTINGS = {
+  canUpsertInternalItems: false,
+  canUpdateExternalItems: false,
+  canUpdateStatus: false
+};
+class AdoPermissionGate {
+  constructor(settings, configPath) {
+    this.settings = settings;
+    this.configPath = configPath;
+  }
+  /**
+   * Check if write operations (create/update work items) are allowed
+   *
+   * Requires: canUpdateExternalItems = true
+   */
+  checkWritePermission() {
+    if (this.settings.canUpdateExternalItems) {
+      return {
+        allowed: true,
+        reason: "Write operations permitted (canUpdateExternalItems=true)"
+      };
+    }
+    return {
+      allowed: false,
+      reason: "Permission denied: External tool updates are disabled.",
+      suggestedAction: `Enable sync.settings.canUpdateExternalItems in ${this.configPath}`,
+      settingPath: "sync.settings.canUpdateExternalItems"
+    };
+  }
+  /**
+   * Check if status updates are allowed
+   *
+   * Requires: canUpdateStatus = true
+   */
+  checkStatusPermission() {
+    if (this.settings.canUpdateStatus) {
+      return {
+        allowed: true,
+        reason: "Status updates permitted (canUpdateStatus=true)"
+      };
+    }
+    return {
+      allowed: false,
+      reason: "Permission denied: Status updates are disabled.",
+      suggestedAction: `Enable sync.settings.canUpdateStatus in ${this.configPath}`,
+      settingPath: "sync.settings.canUpdateStatus"
+    };
+  }
+  /**
+   * Check if internal item creation is allowed
+   *
+   * Requires: canUpsertInternalItems = true
+   */
+  checkCreateInternalPermission() {
+    if (this.settings.canUpsertInternalItems) {
+      return {
+        allowed: true,
+        reason: "Internal item creation permitted (canUpsertInternalItems=true)"
+      };
+    }
+    return {
+      allowed: false,
+      reason: "Permission denied: Creating internal items is disabled.",
+      suggestedAction: `Enable sync.settings.canUpsertInternalItems in ${this.configPath}`,
+      settingPath: "sync.settings.canUpsertInternalItems"
+    };
+  }
+  /**
+   * Get current settings
+   */
+  getSettings() {
+    return { ...this.settings };
+  }
+  /**
+   * Get human-readable permission summary
+   */
+  getPermissionSummary() {
+    const parts = [];
+    if (this.settings.canUpdateExternalItems) {
+      parts.push("create/update ADO items");
+    }
+    if (this.settings.canUpdateStatus) {
+      parts.push("update status");
+    }
+    if (this.settings.canUpsertInternalItems) {
+      parts.push("create internal items");
+    }
+    if (parts.length === 0) {
+      return "All ADO write operations disabled (read-only mode)";
+    }
+    return `Allowed: ${parts.join(", ")}`;
+  }
+}
+async function createAdoPermissionGate(projectRoot = process.cwd()) {
+  const configPath = path.join(projectRoot, ".specweave", "config.json");
+  try {
+    const content = await fs.readFile(configPath, "utf-8");
+    const config = JSON.parse(content);
+    const settings = {
+      canUpsertInternalItems: config?.sync?.settings?.canUpsertInternalItems ?? false,
+      canUpdateExternalItems: config?.sync?.settings?.canUpdateExternalItems ?? false,
+      canUpdateStatus: config?.sync?.settings?.canUpdateStatus ?? false
+    };
+    return new AdoPermissionGate(settings, configPath);
+  } catch {
+    return new AdoPermissionGate(DEFAULT_SYNC_SETTINGS, configPath);
+  }
+}
+async function canWriteToAdo(projectRoot = process.cwd()) {
+  const gate = await createAdoPermissionGate(projectRoot);
+  return gate.checkWritePermission();
+}
+async function canUpdateAdoStatus(projectRoot = process.cwd()) {
+  const gate = await createAdoPermissionGate(projectRoot);
+  return gate.checkStatusPermission();
+}
+var ado_permission_gate_default = AdoPermissionGate;
+export {
+  AdoPermissionGate,
+  DEFAULT_SYNC_SETTINGS,
+  canUpdateAdoStatus,
+  canWriteToAdo,
+  createAdoPermissionGate,
+  ado_permission_gate_default as default
+};

package/plugins/specweave-ado/lib/ado-permission-gate.ts

@@ -0,0 +1,231 @@
+/**
+ * ADO Permission Gate
+ *
+ * Validates that sync permissions are enabled before allowing ADO write operations.
+ * This ensures manual ADO commands respect the same permission settings as the
+ * sync-coordinator.
+ *
+ * Usage:
+ * ```typescript
+ * const gate = await createAdoPermissionGate();
+ * const result = gate.checkWritePermission();
+ * if (!result.allowed) {
+ *   console.log(result.reason);
+ *   return;
+ * }
+ * ```
+ *
+ * @module ado-permission-gate
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+  /**
+   * Whether the operation is allowed
+   */
+  allowed: boolean;
+
+  /**
+   * Human-readable reason for the decision
+   */
+  reason: string;
+
+  /**
+   * Suggested action if permission denied
+   */
+  suggestedAction?: string;
+
+  /**
+   * Which setting controls this permission
+   */
+  settingPath?: string;
+}
+
+/**
+ * Sync settings from config.json
+ */
+export interface SyncSettings {
+  canUpsertInternalItems: boolean;
+  canUpdateExternalItems: boolean;
+  canUpdateStatus: boolean;
+}
+
+/**
+ * Default settings (all disabled for safety)
+ */
+export const DEFAULT_SYNC_SETTINGS: SyncSettings = {
+  canUpsertInternalItems: false,
+  canUpdateExternalItems: false,
+  canUpdateStatus: false,
+};
+
+/**
+ * ADO Permission Gate
+ *
+ * Checks permission settings before allowing ADO write operations.
+ */
+export class AdoPermissionGate {
+  private settings: SyncSettings;
+  private configPath: string;
+
+  constructor(settings: SyncSettings, configPath: string) {
+    this.settings = settings;
+    this.configPath = configPath;
+  }
+
+  /**
+   * Check if write operations (create/update work items) are allowed
+   *
+   * Requires: canUpdateExternalItems = true
+   */
+  checkWritePermission(): PermissionCheckResult {
+    if (this.settings.canUpdateExternalItems) {
+      return {
+        allowed: true,
+        reason: 'Write operations permitted (canUpdateExternalItems=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: External tool updates are disabled.',
+      suggestedAction: `Enable sync.settings.canUpdateExternalItems in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpdateExternalItems',
+    };
+  }
+
+  /**
+   * Check if status updates are allowed
+   *
+   * Requires: canUpdateStatus = true
+   */
+  checkStatusPermission(): PermissionCheckResult {
+    if (this.settings.canUpdateStatus) {
+      return {
+        allowed: true,
+        reason: 'Status updates permitted (canUpdateStatus=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: Status updates are disabled.',
+      suggestedAction: `Enable sync.settings.canUpdateStatus in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpdateStatus',
+    };
+  }
+
+  /**
+   * Check if internal item creation is allowed
+   *
+   * Requires: canUpsertInternalItems = true
+   */
+  checkCreateInternalPermission(): PermissionCheckResult {
+    if (this.settings.canUpsertInternalItems) {
+      return {
+        allowed: true,
+        reason: 'Internal item creation permitted (canUpsertInternalItems=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: Creating internal items is disabled.',
+      suggestedAction: `Enable sync.settings.canUpsertInternalItems in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpsertInternalItems',
+    };
+  }
+
+  /**
+   * Get current settings
+   */
+  getSettings(): SyncSettings {
+    return { ...this.settings };
+  }
+
+  /**
+   * Get human-readable permission summary
+   */
+  getPermissionSummary(): string {
+    const parts: string[] = [];
+
+    if (this.settings.canUpdateExternalItems) {
+      parts.push('create/update ADO items');
+    }
+    if (this.settings.canUpdateStatus) {
+      parts.push('update status');
+    }
+    if (this.settings.canUpsertInternalItems) {
+      parts.push('create internal items');
+    }
+
+    if (parts.length === 0) {
+      return 'All ADO write operations disabled (read-only mode)';
+    }
+
+    return `Allowed: ${parts.join(', ')}`;
+  }
+}
+
+/**
+ * Create an AdoPermissionGate from config.json
+ *
+ * @param projectRoot - Project root directory (defaults to cwd)
+ * @returns AdoPermissionGate instance
+ */
+export async function createAdoPermissionGate(
+  projectRoot: string = process.cwd()
+): Promise<AdoPermissionGate> {
+  const configPath = path.join(projectRoot, '.specweave', 'config.json');
+
+  try {
+    const content = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(content);
+
+    const settings: SyncSettings = {
+      canUpsertInternalItems: config?.sync?.settings?.canUpsertInternalItems ?? false,
+      canUpdateExternalItems: config?.sync?.settings?.canUpdateExternalItems ?? false,
+      canUpdateStatus: config?.sync?.settings?.canUpdateStatus ?? false,
+    };
+
+    return new AdoPermissionGate(settings, configPath);
+  } catch {
+    // Return gate with default (disabled) settings if config not found
+    return new AdoPermissionGate(DEFAULT_SYNC_SETTINGS, configPath);
+  }
+}
+
+/**
+ * Quick check: Are ADO write operations allowed?
+ *
+ * Convenience function for simple permission checks.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Permission check result
+ */
+export async function canWriteToAdo(
+  projectRoot: string = process.cwd()
+): Promise<PermissionCheckResult> {
+  const gate = await createAdoPermissionGate(projectRoot);
+  return gate.checkWritePermission();
+}
+
+/**
+ * Quick check: Are ADO status updates allowed?
+ *
+ * @param projectRoot - Project root directory
+ * @returns Permission check result
+ */
+export async function canUpdateAdoStatus(
+  projectRoot: string = process.cwd()
+): Promise<PermissionCheckResult> {
+  const gate = await createAdoPermissionGate(projectRoot);
+  return gate.checkStatusPermission();
+}
+
+export default AdoPermissionGate;