specweave 0.30.1 → 0.30.3

package/plugins/specweave-ado/commands/specweave-ado-close-workitem.md

@@ -13,40 +13,225 @@ description: Close Azure DevOps work item when increment complete
 
 ## Command Behavior
 
-When user runs this command, invoke `ado-manager` agent to:
+When user runs this command, Claude should:
 
-1. Validate increment is 100% complete (all tasks done)
-2. Generate completion summary
-3. PATCH work item state → Closed
-4. POST final comment with deliverables
-5. Display confirmation
+### 1. Check Permission Gate (MANDATORY FIRST STEP)
+
+**Before ANY ADO API calls**, check if status updates are allowed:
+
+```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;
+
+// Close requires both permissions (write to close, status to change state)
+if (!canUpdateExternal || !canUpdateStatus) {
+  const missing = [];
+  if (!canUpdateExternal) missing.push('canUpdateExternalItems');
+  if (!canUpdateStatus) missing.push('canUpdateStatus');
+
+  console.log(`
+❌ Permission Denied
+
+Closing ADO work items requires these permissions:
+${missing.map(p => `  - sync.settings.${p} = false (required: true)`).join('\n')}
+
+To enable, update .specweave/config.json:
+{
+  "sync": {
+    "settings": {
+      "canUpdateExternalItems": true,
+      "canUpdateStatus": true
+    }
+  }
+}
+`);
+  return;
+}
+```
+
+### 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`);
+  return;
+}
+
+const { organization, project } = profileConfig.config;
+```
+
+### 3. Validate Increment Completion
+
+Before closing, verify the increment is actually complete:
+
+```typescript
+// Check tasks.md for completion
+const tasksPath = `.specweave/increments/${incrementId}/tasks.md`;
+const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+
+const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
+const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
+
+if (completedTasks < totalTasks) {
+  console.log(`
+⚠️ Increment not complete
+
+Tasks: ${completedTasks}/${totalTasks} completed
+Cannot close ADO work item until all tasks are done.
+
+Complete remaining tasks first, then re-run this command.
+`);
+  return;
+}
+```
+
+### 4. Invoke ADO Manager Agent
 
-**Agent Invocation**:
 ```
 Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
 
-Prompt: "Close ADO work item for completed increment 0005-payment-integration.
+Prompt: "Close ADO work item for completed increment {increment-id}.
+
+IMPORTANT:
+- Permission verified: canUpdateExternalItems=true, canUpdateStatus=true
+- Using profile: {profileName} (org: {organization}, project: {project})
 
 Steps:
 1. Validate: All tasks in tasks.md complete
 2. Generate: Completion summary (duration, deliverables)
-3. Load work item ID from increment-metadata.json
-4. PATCH work item: state = Closed
+3. Load work item ID from metadata.json
+4. PATCH work item: state = Closed (using org: {organization}, project: {project})
 5. POST final comment with summary
-6. Display: Closure confirmation"
+6. Display: Closure confirmation with profile used"
+```
+
+### 5. Display Result
+
+```
+✅ Closed ADO Work Item
+
+Work Item: #{workItemId}
+Profile: {profileName}
+  Organization: {organization}
+  Project: {project}
+
+Increment: {increment-id}
+Status: 100% complete ({total}/{total} tasks)
+Duration: {days} days
+
+Summary posted to ADO work item
+URL: https://dev.azure.com/{organization}/{project}/_workitems/edit/{workItemId}
 ```
 
 ---
 
+## Permission Requirements
+
+This command requires **both** permissions:
+
+| Permission | Required | Purpose |
+|------------|----------|---------|
+| canUpdateExternalItems | true | Write to ADO work item |
+| canUpdateStatus | true | Change work item state to Closed |
+
+---
+
 ## Example Output
 
+### Success
+
 ```
+User: /specweave-ado:close-workitem 0005-payment-integration
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: true
+  canUpdateStatus: true
+
+Resolving ADO profile...
+  Using: ado-nova-x-sandbox (from increment)
+  Organization: nova-systems
+  Project: Nova X Sandbox
+
+Validating completion...
+  Tasks: 10/10 complete
+
+Closing work item...
+
 ✅ Closed ADO Epic #12345
 
+Profile: ado-nova-x-sandbox
 Increment: 0005-payment-integration
 Status: 100% complete (10/10 tasks)
 Duration: 3 days
 
 Summary posted to ADO work item
-URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
+URL: https://dev.azure.com/nova-systems/Nova%20X%20Sandbox/_workitems/edit/12345
+```
+
+### Permission Denied
+
+```
+User: /specweave-ado:close-workitem 0005
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: false
+  canUpdateStatus: false
+
+❌ Permission Denied
+
+Closing ADO work items requires:
+  - sync.settings.canUpdateExternalItems = true
+  - sync.settings.canUpdateStatus = true
+
+Update .specweave/config.json to enable these permissions.
+```
+
+### Incomplete Increment
+
+```
+User: /specweave-ado:close-workitem 0005
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: true
+  canUpdateStatus: true
+
+Validating completion...
+
+⚠️ Increment not complete
+
+Tasks: 6/10 completed
+Cannot close ADO work item until all tasks are done.
+
+Complete remaining tasks:
+  - T-007: Add refund functionality
+  - T-008: Implement subscriptions
+  - T-009: Add analytics
+  - T-010: Security audit
 ```
+
+---
+
+## Related
+
+- `/specweave-ado:create-workitem` - Create ADO work item
+- `/specweave-ado:sync` - Sync progress to ADO
+- `/specweave-ado:status` - Check sync status (read-only, always allowed)

package/plugins/specweave-ado/commands/specweave-ado-create-workitem.md

@@ -15,39 +15,163 @@ description: Create Azure DevOps work item from SpecWeave increment
 
 When user runs this command, Claude should:
 
-1. **Validate Prerequisites**:
-   - Check ADO plugin installed
-   - Check AZURE_DEVOPS_PAT environment variable set
-   - Check ADO configured in .specweave/config.json
+### 1. Check Permission Gate (MANDATORY FIRST STEP)
+
+**Before ANY ADO API calls**, check if write operations are allowed:
+
+```typescript
+// Read .specweave/config.json
+const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
+const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
+
+if (!canUpdateExternal) {
+  // STOP HERE - Permission denied
+  console.log(`
+❌ Permission Denied
+
+ADO write operations are disabled.
+Setting: sync.settings.canUpdateExternalItems = false
+
+To enable, update .specweave/config.json:
+{
+  "sync": {
+    "settings": {
+      "canUpdateExternalItems": true
+    }
+  }
+}
+
+Or run: jq '.sync.settings.canUpdateExternalItems = true' .specweave/config.json > tmp && mv tmp .specweave/config.json
+`);
+  return; // DO NOT proceed to create work item
+}
+```
+
+If `canUpdateExternalItems` is `false`, display the error and **STOP**. Do not invoke the ADO Manager agent.
+
+### 2. Resolve ADO Profile
+
+Use the increment's stored profile or fall back to global activeProfile:
+
+```typescript
+// Load increment metadata
+const metadata = JSON.parse(await fs.readFile(
+  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
+));
+
+// Check for increment-specific profile
+let profileName = metadata?.external_sync?.ado?.profile;
+
+// Fall back to global activeProfile
+if (!profileName) {
+  profileName = config?.sync?.activeProfile;
+}
+
+// Get profile config
+const profileConfig = config?.sync?.profiles?.[profileName];
+if (!profileConfig || profileConfig.provider !== 'ado') {
+  console.log(`❌ Profile "${profileName}" not found or not an ADO profile`);
+  return;
+}
+
+const { organization, project } = profileConfig.config;
+```
+
+### 3. Validate Prerequisites
+
+- Check ADO plugin installed
+- Check AZURE_DEVOPS_PAT environment variable set
+- Check ADO profile has organization and project
+
+### 4. Invoke ADO Manager Agent
+
+```
+Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
+
+Prompt: "Create ADO work item for increment {increment-id}.
+
+IMPORTANT: Permission already verified (canUpdateExternalItems=true).
+Use profile: {profileName} (org: {organization}, project: {project})
+
+Steps:
+1. Read .specweave/increments/{increment-id}/spec.md
+2. Extract title and description
+3. Use ADO organization: {organization}, project: {project}
+4. Create work item via ADO REST API
+5. Store work item ID in increment metadata.json
+6. Store profile name in metadata.json external_sync.ado.profile
+7. Display: Work Item ID, URL, and confirmation"
+```
+
+### 5. Display Result
+
+```
+✅ Created ADO Epic
+
+Work Item: #12345
+URL: https://dev.azure.com/{organization}/{project}/_workitems/edit/12345
+Profile: {profileName}
+
+Linked to increment: {increment-id}
+```
 
-2. **Invoke ADO Manager Agent**:
-   ```
-   Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
+---
 
-   Prompt: "Create ADO work item for increment 0005-payment-integration.
+## Permission Denied Output
 
-   Steps:
-   1. Read .specweave/increments/0005-payment-integration/spec.md
-   2. Extract title and description
-   3. Load ADO config from .specweave/config.json
-   4. Create work item via ADO REST API
-   5. Store work item ID in increment-metadata.json
-   6. Display: Work Item ID, URL, and confirmation"
-   ```
+If `canUpdateExternalItems` is false:
 
-3. **Display Result**:
-   ```
-   ✅ Created ADO Epic
+```
+❌ Permission Denied: ADO Write Operations Disabled
 
-   Work Item: #12345
-   URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
+Your configuration prevents creating/updating ADO work items.
 
-   Linked to increment: 0005-payment-integration
-   ```
+Current setting:
+  sync.settings.canUpdateExternalItems = false
+
+To enable ADO writes:
+1. Edit .specweave/config.json
+2. Set sync.settings.canUpdateExternalItems to true
+3. Re-run this command
+
+This setting was configured during 'specweave init'.
+```
 
 ---
 
 ## Example Usage
 
 ```
-User: /specweave-ado:create-workitem 0005
+User: /specweave-ado:create-workitem 0005-payment-integration
+
+# If permission granted:
+Claude: Checking ADO permissions...
+        ✓ canUpdateExternalItems: true
+
+        Resolving ADO profile...
+        ✓ Using profile: ado-nova-x-sandbox (from increment)
+        ✓ Organization: nova-systems
+        ✓ Project: Nova X Sandbox
+
+        Creating work item...
+        [Invokes ADO Manager Agent]
+
+        ✅ Created ADO Epic #12345
+        URL: https://dev.azure.com/nova-systems/Nova%20X%20Sandbox/_workitems/edit/12345
+
+# If permission denied:
+Claude: Checking ADO permissions...
+        ❌ Permission Denied
+
+        sync.settings.canUpdateExternalItems = false
+
+        To enable: Edit .specweave/config.json and set canUpdateExternalItems to true
+```
+
+---
+
+## Related
+
+- `/specweave-ado:sync` - Sync progress to existing work item
+- `/specweave-ado:status` - Check ADO sync status (read-only, always allowed)
+- `/specweave-ado:close-workitem` - Close work item when complete