specweave 0.30.12 → 0.30.14

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

@@ -0,0 +1,361 @@
+---
+name: specweave-ado:push
+description: Push local changes to Azure DevOps (like git push). Supports increment, project, or full living docs sync.
+---
+
+# ADO Push Command
+
+**Usage**: `/specweave-ado:push [target] [options]`
+
+**Purpose**: Push local changes to Azure DevOps (like `git push`)
+
+---
+
+## Quick Start
+
+```bash
+# Push current/active increment (simple mode)
+/specweave-ado:push
+
+# Push specific increment
+/specweave-ado:push 0005
+
+# Push ALL local changes to ADO (living docs sync)
+/specweave-ado:push --all
+
+# Push specific project/board
+/specweave-ado:push --project clinical-insights
+
+# Push specific feature hierarchy
+/specweave-ado:push --feature FS-042
+```
+
+---
+
+## Sync Modes
+
+### Mode 1: Increment Sync (Default)
+Pushes task progress from ONE increment to its linked work item.
+
+### Mode 2: Living Docs Sync (--all)
+Pushes ALL local spec changes to corresponding ADO items:
+- Scans `.specweave/docs/internal/specs/` for modified specs
+- Updates status, progress, comments on linked ADO items
+- Respects multi-project folder structure
+
+### Mode 3: Project-Scoped Sync (--project)
+Pushes changes only within a specific project folder.
+
+### Mode 4: Feature Hierarchy Sync (--feature)
+Pushes a feature and all its child user stories.
+
+---
+
+## What Gets Pushed
+
+| Field | Source |
+|-------|--------|
+| **Progress** | Calculated from tasks.md (X/Y tasks, Z%) |
+| **Comment** | Auto-generated with completed tasks list |
+| **Completion %** | Updated on work item custom field |
+| **State** | Updated if threshold crossed (e.g., 100% -> Resolved) |
+
+---
+
+## Command Behavior
+
+When user runs this command:
+
+### 1. Check Permission Gate (MANDATORY)
+
+```typescript
+const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
+const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
+
+if (!canUpdateExternal) {
+  console.log(`
+Permission Denied: ADO writes disabled
+
+Current: sync.settings.canUpdateExternalItems = false
+
+To enable writes, update .specweave/config.json:
+  "sync": { "settings": { "canUpdateExternalItems": true } }
+
+Or use read-only mode:
+  /specweave-ado:pull ${incrementId}
+`);
+  return;
+}
+```
+
+### 2. Resolve Increment & Profile
+
+```typescript
+const incrementId = args.incrementId || await findActiveIncrement();
+
+const metadata = JSON.parse(await fs.readFile(
+  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
+));
+
+const adoWorkItemId = metadata?.external_sync?.ado?.workItemId;
+if (!adoWorkItemId) {
+  console.log(`Not linked to ADO. Run: /specweave-ado:create ${incrementId}`);
+  return;
+}
+
+const profileName = metadata?.external_sync?.ado?.profile
+  || config?.sync?.defaultProfile;
+```
+
+### 3. Calculate Progress
+
+```typescript
+const tasksContent = await fs.readFile(
+  `.specweave/increments/${incrementId}/tasks.md`, 'utf-8'
+);
+
+const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
+const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
+const percentage = Math.round((completedTasks / totalTasks) * 100);
+
+// Find recently completed tasks (for comment)
+const recentlyCompleted = parseRecentlyCompletedTasks(tasksContent);
+```
+
+### 4. Invoke Push Sync
+
+```
+Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
+
+Prompt: "Push progress to ADO for increment {increment-id}.
+
+DIRECTION: to-ado
+PERMISSION: canUpdateExternalItems = true (verified)
+
+Profile: {profileName}
+Work Item: #{workItemId}
+
+Progress: {completedTasks}/{totalTasks} ({percentage}%)
+Recently completed: {recentlyCompleted}
+
+Steps:
+1. Format progress comment with task list
+2. POST comment to ADO work item
+3. PATCH work item completion field
+4. Update state if threshold crossed:
+   - 100% completed -> Resolved (if canUpdateStatus)
+5. Update sync timestamp in metadata
+6. Display push summary"
+```
+
+### 5. Display Result
+
+```
+Pushed to ADO
+
+Work Item: #12345
+Profile: ado-my-project
+
+Progress: 6/10 tasks (60%)
+
+Comment posted:
+  "Progress Update: 60% complete
+
+   Recently completed:
+   - T-005: Add payment validation
+   - T-006: Implement refund flow"
+
+Fields updated:
+  Completion: 60%
+
+URL: https://dev.azure.com/org/project/_workitems/edit/12345
+```
+
+---
+
+## Permission Requirements
+
+| Permission | Required | Purpose |
+|------------|----------|---------|
+| `canUpdateExternalItems` | **true** | Write to ADO |
+| `canUpdateStatus` | optional | Change work item state |
+
+If `canUpdateStatus` is false, progress is posted but state unchanged.
+
+---
+
+## Examples
+
+### Example 1: Simple Push
+
+```
+User: /specweave-ado:push
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: true
+
+Pushing to ADO...
+  Increment: 0005-payment-integration
+  Work Item: #12345
+
+Pushed to ADO
+
+Progress: 8/10 tasks (80%)
+Comment posted with 2 recently completed tasks
+
+Push complete!
+```
+
+### Example 2: Permission Denied
+
+```
+User: /specweave-ado:push 0005
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: false
+
+Permission Denied
+
+To enable ADO writes:
+1. Edit .specweave/config.json
+2. Set sync.settings.canUpdateExternalItems = true
+
+Or use read-only: /specweave-ado:pull 0005
+```
+
+### Example 3: 100% Complete
+
+```
+User: /specweave-ado:push 0005
+
+Claude:
+Pushing to ADO...
+
+Progress: 10/10 tasks (100%)
+
+Comment posted:
+  "Progress Update: 100% complete - All tasks done!"
+
+State updated:
+  Active -> Resolved (canUpdateStatus = true)
+
+Ready to close: /specweave-ado:close 0005
+```
+
+---
+
+## Sync Brief (MANDATORY OUTPUT)
+
+**After EVERY push operation, display a compact summary:**
+
+### Brief Format (Single Increment)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+│  Profile:   ado-techcorp                                │
+├─────────────────────────────────────────────────────────┤
+│  PROGRESS                                               │
+│    Tasks: 8/10 (80%)  ████████░░                        │
+│    ↑ Comment posted: "Progress: 80% complete"           │
+│    ↑ Completion field: 60% → 80%                        │
+├─────────────────────────────────────────────────────────┤
+│  RECENTLY COMPLETED                                     │
+│    ✓ T-007: Add payment validation                      │
+│    ✓ T-008: Implement refund flow                       │
+├─────────────────────────────────────────────────────────┤
+│  Last sync: 2025-12-04 10:32:15 (just now)              │
+│  URL: https://dev.azure.com/.../12345                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (Multi-Project --all)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Pushed: 12 specs across 3 projects                     │
+│  Comments posted: 12                                    │
+│  Status transitions: 3                                  │
+│  Duration: 5.1s                                         │
+├─────────────────────────────────────────────────────────┤
+│  BY PROJECT                                             │
+│    techcorp/clinical-insights/   5 pushed               │
+│    techcorp/ai-platform/         4 pushed               │
+│    infrastructure/core/          3 pushed               │
+├─────────────────────────────────────────────────────────┤
+│  CHANGES PUSHED                                         │
+│    ↑ Progress comments: 12                              │
+│    ↑ Completion updates: 8                              │
+│    ↑ Status transitions: 3                              │
+│      • FS-042/us-001: Active → Resolved (100%)          │
+│      • FS-043/us-005: Active → Resolved (100%)          │
+│      • FS-050/us-010: New → Active (started)            │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (100% Complete - Ready to Close)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+├─────────────────────────────────────────────────────────┤
+│  PROGRESS                                               │
+│    Tasks: 10/10 (100%)  ██████████  COMPLETE!           │
+│    ↑ Comment: "All tasks complete!"                     │
+│    ↑ Status: Active → Resolved                          │
+├─────────────────────────────────────────────────────────┤
+│  🎉 INCREMENT READY TO CLOSE                            │
+│     Run: /specweave-ado:close 0005                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (Permission Denied)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH BLOCKED                                     ✗ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Permission: canUpdateExternalItems = false             │
+├─────────────────────────────────────────────────────────┤
+│  TO ENABLE:                                             │
+│    Edit .specweave/config.json:                         │
+│    sync.settings.canUpdateExternalItems = true          │
+│                                                         │
+│  OR USE READ-ONLY:                                      │
+│    /specweave-ado:pull 0005                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Symbols Reference
+
+| Symbol | Meaning |
+|--------|---------|
+| `✓` | Success |
+| `⚠` | Warning (partial success) |
+| `✗` | Error/Failed |
+| `↓` | Pulled from external (incoming) |
+| `↑` | Pushed to external (outgoing) |
+| `+` | Added (new items) |
+| `−` | Removed |
+| `~` | Modified |
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO |
+| `/specweave-ado:sync` | Two-way sync (pull + push) |
+| `/specweave-ado:status` | Check sync status |
+| `/specweave-ado:close` | Close completed work item |

package/plugins/specweave-ado/commands/{specweave-ado-status.md → status.md}

@@ -51,3 +51,15 @@ Sync Enabled: ✅
 
 Next Sync: Automatic on task completion
 ```
+
+---
+
+## Related
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO |
+| `/specweave-ado:push` | Push progress to ADO |
+| `/specweave-ado:sync` | Two-way sync |
+| `/specweave-ado:create` | Create ADO work item |
+| `/specweave-ado:close` | Close work item |

package/plugins/specweave-ado/commands/{specweave-ado-sync.md → sync.md}

@@ -234,8 +234,69 @@ Options:
 
 ---
 
+## Simpler Alternatives
+
+For most use cases, use the git-style commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO (read-only) |
+| `/specweave-ado:push` | Push progress to ADO |
+
+Use `/specweave-ado:sync` when you need explicit two-way sync with options.
+
+---
+
+## Sync Brief (MANDATORY OUTPUT)
+
+**After EVERY sync operation, display a compact two-way summary:**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  SYNC COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+│  Profile:   ado-techcorp                                │
+│  Direction: two-way (pull + push)                       │
+├─────────────────────────────────────────────────────────┤
+│  PULLED (from ADO)                              ↓       │
+│    ↓ Status:    Active → Resolved  (external wins)      │
+│    ↓ Priority:  P2 → P1                                 │
+│    + Comments:  2 new imported                          │
+├─────────────────────────────────────────────────────────┤
+│  PUSHED (to ADO)                                ↑       │
+│    Tasks: 8/10 (80%)  ████████░░                        │
+│    ↑ Comment posted: "Progress: 80% complete"           │
+│    ↑ Completion: 60% → 80%                              │
+├─────────────────────────────────────────────────────────┤
+│  CONFLICTS RESOLVED: 1                                  │
+│    Status: local "in-progress" vs ADO "Resolved"        │
+│    Winner: ADO (external tool always wins)              │
+├─────────────────────────────────────────────────────────┤
+│  Last sync: 2025-12-04 10:32:15 (just now)              │
+│  URL: https://dev.azure.com/.../12345                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Symbols Reference
+
+| Symbol | Meaning |
+|--------|---------|
+| `✓` | Success |
+| `⚠` | Warning |
+| `✗` | Failed |
+| `↓` | Pulled (incoming) |
+| `↑` | Pushed (outgoing) |
+
+---
+
 ## 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
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull from ADO (git-style) |
+| `/specweave-ado:push` | Push to ADO (git-style) |
+| `/specweave-ado:create` | Create new ADO work item |
+| `/specweave-ado:status` | Check sync status |
+| `/specweave-ado:close` | Close work item when complete |

package/plugins/specweave-ado/hooks/README.md

@@ -193,7 +193,7 @@ Core hook (330 lines)      ADO plugin hook (150 lines)
 
 - **Core Plugin Hooks**: `plugins/specweave/hooks/README.md`
 - **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
-- **ADO Sync Command**: `plugins/specweave-ado/commands/specweave-ado-sync.md`
+- **ADO Sync Command**: `plugins/specweave-ado/commands/sync.md`
 
 ---
 

package/plugins/specweave-docs/commands/build.md

@@ -0,0 +1,158 @@
+---
+name: specweave-docs:build
+description: Build static documentation site for deployment. Supports both public and internal docs. Outputs production-ready HTML/CSS/JS.
+---
+
+# Documentation Build Command
+
+Build production-ready static documentation site for deployment to any static host.
+
+## Usage
+
+```bash
+# Build INTERNAL docs (SpecWeave living documentation) - DEFAULT
+/specweave-docs:build
+
+# Build PUBLIC docs (end-user documentation)
+/specweave-docs:build --public
+```
+
+## Two Build Targets
+
+| Site | Output Directory | NPM Script |
+|------|------------------|------------|
+| **Internal** | `docs-site/build-internal/` | `docs:internal:build` |
+| **Public** | `docs-site/build/` | `docs:build` |
+
+## Your Task
+
+Execute the appropriate npm script based on user flags:
+
+```bash
+# Check if user wants public docs
+PUBLIC_FLAG="${1:-}"
+
+cd /path/to/project
+
+if [ "$PUBLIC_FLAG" = "--public" ]; then
+  echo "Building PUBLIC documentation..."
+  echo "Output: docs-site/build/"
+  echo ""
+  npm run docs:build
+  echo ""
+  echo "Build complete! Output: docs-site/build/"
+else
+  echo "Building INTERNAL documentation..."
+  echo "Output: docs-site/build-internal/"
+  echo ""
+  npm run docs:internal:build
+  echo ""
+  echo "Build complete! Output: docs-site/build-internal/"
+fi
+```
+
+## Output Structure
+
+```
+docs-site/build-internal/
+├── index.html              <- Landing page
+├── strategy/
+├── specs/
+├── architecture/
+│   └── adr/
+├── delivery/
+├── operations/
+├── governance/
+├── assets/
+│   ├── css/styles.[hash].css
+│   └── js/runtime.[hash].js
+└── sitemap.xml
+```
+
+## Deployment Options
+
+### 1. Preview Locally
+
+```bash
+# Internal docs
+cd docs-site && npm run serve:internal
+
+# Public docs
+cd docs-site && npm run serve
+```
+
+### 2. Netlify
+
+```bash
+cd docs-site
+npx netlify deploy --dir=build-internal --prod
+```
+
+### 3. Vercel
+
+```bash
+cd docs-site
+npx vercel --prod
+```
+
+### 4. GitHub Pages
+
+```bash
+# Copy build to docs folder (GitHub Pages expects /docs)
+cp -r docs-site/build-internal/* docs/
+git add docs/
+git commit -m "docs: update documentation site"
+git push
+```
+
+### 5. Static Server
+
+```bash
+npx serve docs-site/build-internal/
+```
+
+## Build vs Preview
+
+| Aspect | Preview | Build |
+|--------|---------|-------|
+| **Purpose** | Development | Production |
+| **Speed** | Instant | 10-30 seconds |
+| **Output** | Dev server | Static files |
+| **Hot Reload** | Yes | No |
+| **Optimization** | No | Yes (minified) |
+| **Use Case** | Writing docs | Deployment |
+
+## First-Time Setup
+
+If dependencies not installed:
+
+```bash
+npm run docs:install
+```
+
+## Troubleshooting
+
+### Build fails with broken links
+```bash
+# Preview first to find errors
+npm run docs:internal
+# Fix broken links, then build
+npm run docs:internal:build
+```
+
+### Out of memory
+```bash
+# Increase Node memory
+NODE_OPTIONS="--max-old-space-size=4096" npm run docs:internal:build
+```
+
+### Cache issues
+```bash
+cd docs-site && npm run clear && npm run build:internal
+```
+
+## See Also
+
+- `/specweave-docs:preview` - Preview docs locally with hot reload
+- `/specweave-docs:organize` - Organize large folders with themed indexes
+- `/specweave-docs:health` - Documentation health report

package/plugins/specweave-docs/commands/{docs-generate.md → generate.md}

@@ -1,11 +1,16 @@
-# Docs Generate - Generate Documentation from Code
+---
+name: specweave-docs:generate
+description: Generate documentation from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications.
+---
+
+# Generate Documentation from Code
 
 Generate documentation automatically from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications. Creates comprehensive API docs, type references, and usage examples.
 
 ## Usage
 
 ```
-/specweave-docs:docs-generate <source-type> <path> [options]
+/specweave-docs:generate <source-type> <path> [options]
 ```
 
 ## Source Types
@@ -402,9 +407,9 @@ cat ./docs/api/index.md ./docs/specs/index.md > ./docs/complete-reference.md
 
 ## Related Commands
 
-- `/specweave-docs:docs-init` - Initialize Docusaurus documentation site
-- `/specweave-docs-preview:preview` - Preview generated documentation
-- `/specweave-docs-preview:build` - Build static site from generated docs
+- `/specweave-docs:init` - Initialize Docusaurus documentation site
+- `/specweave-docs:preview` - Preview generated documentation
+- `/specweave-docs:build` - Build static site from generated docs
 
 ## Requirements