specweave 0.22.13 → 0.23.0

package/.claude-plugin/README.md

@@ -101,7 +101,7 @@ SpecWeave's marketplace.json follows Claude's official schema format. Here's the
   "plugins": [
     {
       "name": "specweave-github",
-      "description": "GitHub integration - bidirectional sync",
+      "description": "GitHub integration - full sync (all permissions)",
       "source": "../plugins/specweave-github",
       "category": "productivity",
       "version": "1.0.0",
@@ -173,7 +173,7 @@ SpecWeave's marketplace.json follows Claude's official schema format. Here's the
 - `status` - Show GitHub sync status
 
 **Skills**:
-- `github-sync` - Bidirectional sync
+- `github-sync` - Full sync (all permissions)
 - `github-issue-tracker` - Task-level tracking
 
 **Agents**:

package/CLAUDE.md

@@ -10,77 +10,114 @@ For **contributors to SpecWeave itself** (not users).
 
 ## 🚨 CRITICAL SAFETY RULES
 
-### 1. Dual-Mode Development Setup (MANDATORY for Contributors)
+### 1. Local Development Setup
 
-**Context**: SpecWeave contributors need TWO modes:
-1. **Development Mode**: Local repo symlink (for iterating on SpecWeave itself)
-2. **NPM Testing Mode**: Global npm installation (for testing end-user experience)
+**SpecWeave uses Claude Code's GitHub marketplace** for plugin management. This is the **cross-platform, simple approach** that works on macOS, Linux, and Windows.
 
-#### Development Mode (Default for Contributors)
+#### Quick Start (Recommended - All Platforms)
 
-**Problem**: Claude Code executes hooks from `~/.claude/plugins/marketplaces/specweave/`. If this is a **directory** (not symlink), hooks fail with "No such file or directory".
-
-**Quick Setup**:
 ```bash
-# Switch to development mode (creates symlink)
-bash scripts/dev-mode.sh
+# 1. Clone and install
+git clone https://github.com/YOUR_USERNAME/specweave.git
+cd specweave
+npm install
 
-# Verify symlink:
-ls -ld ~/.claude/plugins/marketplaces/specweave
-# Must show: lrwxr-xr-x ... -> /path/to/repo (SYMLINK, not drwxr-xr-x)
+# 2. Build TypeScript
+npm run rebuild
+
+# 3. That's it! Claude Code auto-installs from GitHub marketplace
+# Hooks execute from: ~/.claude/plugins/marketplaces/specweave/
 ```
 
-**Manual Setup** (if scripts fail):
+#### Development Workflow
+
+**How it works**: Claude Code automatically pulls your latest code from GitHub every 5-10 seconds.
+
 ```bash
-# Verify symlink exists:
-ls -ld ~/.claude/plugins/marketplaces/specweave
+# 1. Make changes in local repo
+vim src/core/task-parser.ts
 
-# If directory or missing, fix it:
-rm -rf ~/.claude/plugins/marketplaces/specweave
-ln -s "$(pwd)" ~/.claude/plugins/marketplaces/specweave
+# 2. Build TypeScript changes
+npm run rebuild
 
-# Verify:
-bash .specweave/increments/0043-spec-md-desync-fix/scripts/verify-dev-setup.sh
+# 3. Test locally
+npm test
+
+# 4. Commit and push to your branch
+git add . && git commit -m "feat: new feature"
+git push origin develop
+
+# 5. Wait 5-10 seconds → Claude Code auto-updates marketplace
+
+# 6. Test in Claude Code
+/specweave:increment "test feature"
+# Your latest hooks now execute automatically!
 ```
 
-**Without symlink**: Hooks fail, status line broken, living docs don't sync.
-**Protection**: Pre-commit hook verifies symlink before each commit.
+**For hook-only changes** (no TypeScript build needed):
+```bash
+vim plugins/specweave/hooks/post-task-completion.sh
+git add . && git commit -m "fix: improve hook logic"
+git push origin develop
+# Wait 5-10 seconds → hooks updated!
+```
 
-#### NPM Testing Mode (For End-User Testing)
+**Key Benefits**:
+- ✅ **Cross-platform** (works on Windows, no admin privileges needed)
+- ✅ **Simple** (standard git workflow, no scripts)
+- ✅ **Reliable** (Claude Code manages updates, no symlink race conditions)
+- ✅ **Team-friendly** (everyone gets updates automatically)
 
-**When to use**: Testing the npm-installed version as end-users would experience it.
+#### Testing Unpushed Changes (Advanced)
 
-**Setup**:
+**Option 1: Temporary Branch** (Recommended)
 ```bash
-# 1. Install global npm package (if not already)
-npm install -g specweave
+# Create throwaway test branch
+git checkout -b temp-test-$(date +%s)
+git add . && git commit -m "temp: testing unpushed changes"
+git push origin temp-test-1234567890
 
-# 2. Switch to npm mode (removes symlink)
-bash scripts/npm-mode.sh
+# Claude Code pulls from your test branch (5-10 seconds)
+# Test your changes...
 
-# 3. Test as end-user
-specweave init test-project
-cd test-project
-# ... test commands ...
+# Clean up when done
+git push origin --delete temp-test-1234567890
+git checkout develop && git branch -D temp-test-1234567890
+```
 
-# 4. Switch back to dev mode when done
-cd /path/to/specweave/repo
-bash scripts/dev-mode.sh
+**Option 2: Fork-Based Development**
+```bash
+# One-time: Point Claude Code to your fork
+claude plugin marketplace remove specweave
+claude plugin marketplace add github:YOUR_USERNAME/specweave
+
+# Now push to your fork's branch
+git push origin develop
+# Claude Code pulls from YOUR fork, not upstream
 ```
 
-**Key Differences**:
-| Aspect | Development Mode | NPM Testing Mode |
-|--------|------------------|------------------|
-| Symlink | ✅ Points to local repo | ❌ Removed |
-| Changes | ⚡ Instant (after rebuild) | 📦 Requires npm publish |
-| Use Case | Contributing to SpecWeave | Testing end-user experience |
-| Hooks | Use local `plugins/` | Use npm `node_modules/specweave/plugins/` |
+**Option 3: Symlink Mode** (Advanced, Unix-Only)
+If you need **instant updates** without pushing (e.g., rapid hook iteration):
+- See: `.specweave/docs/internal/advanced/symlink-dev-mode.md`
+- ⚠️ **Warning**: Only works on macOS/Linux, not Windows
+- ⚠️ Requires bash scripts, registry manipulation, ongoing maintenance
+
+#### NPM Testing Mode (End-User Experience)
+
+To test the published npm package as end-users experience it:
 
-**Quick Toggle**:
 ```bash
-# Switch modes anytime:
-./scripts/dev-mode.sh   # → Development (symlink)
-./scripts/npm-mode.sh   # → NPM testing (global install)
+# 1. Install global npm package
+npm install -g specweave
+
+# 2. Test in fresh directory
+cd /tmp && mkdir test-project && cd test-project
+specweave init .
+# ... test end-user workflows ...
+
+# 3. Resume development
+cd /path/to/specweave/repo
+# Claude Code automatically switches back to marketplace mode
 ```
 
 ### 2. NEVER Pollute Increment Folders
@@ -222,6 +259,61 @@ grep -c "^- \[x\] \*\*AC-" spec.md
 
 **Incident Reference**: 2025-11-19 - Increment 0044 was incorrectly closed with tasks.md showing `[ ] pending` while internal TODO showed "completed". This violated SpecWeave's core principle. See `.specweave/increments/0044-integration-testing-status-hooks/reports/INCIDENT-SOURCE-OF-TRUTH-VIOLATION.md` for full post-mortem.
 
+### 7a. Status Line Synchronization (AUTOMATIC & ENFORCED!)
+
+**CRITICAL**: Status line MUST ALWAYS reflect current task completion status.
+
+**How It Works** (Automatic):
+1. Every TodoWrite call → `post-task-completion.sh` hook fires
+2. Hook calls `update-status-line.sh` → cache updates
+3. Status line displays updated progress immediately
+
+**The ONLY Way to Complete Tasks**:
+```
+ALWAYS use TodoWrite when working on increment tasks!
+- TodoWrite triggers hooks automatically
+- Hooks update status line cache
+- Status line stays synchronized
+```
+
+**❌ NEVER Complete Tasks Without TodoWrite**:
+```typescript
+// ❌ WRONG: Direct Edit without TodoWrite
+Edit("tasks.md", "**Status**: [ ] pending", "**Status**: [x] completed");
+// Status line will NOT update! Hook never fires!
+
+// ✅ CORRECT: TodoWrite triggers automatic update
+TodoWrite([{task: "T-001", status: "in_progress"}]);
+// ... do the work ...
+TodoWrite([{task: "T-001", status: "completed"}]);
+Edit("tasks.md", "**Status**: [ ] pending", "**Status**: [x] completed");
+// Hook fires → status line updates automatically!
+```
+
+**Validation Commands**:
+```bash
+# Check if status line is in sync
+/specweave:validate-status
+
+# Manual update (emergency only)
+bash plugins/specweave/hooks/lib/update-status-line.sh
+
+# Validate all increments
+npx tsx src/core/status-line-validator.ts
+```
+
+**Detection & Recovery**:
+- Pre-commit hook validates sync (blocks commit if desync detected)
+- `/specweave:done` validates before closing (blocks if desync)
+- Automatic tests verify hook fires correctly
+
+**Why This Matters**:
+- Status line is visible to user at ALL times
+- Stale status = broken trust
+- Hooks ensure atomic updates (task complete → status updates together)
+
+**Incident Reference**: 2025-11-20 - Status line showed 21/52 tasks when actually 26/52 were complete (10% desync). Root cause: Tasks marked complete without using TodoWrite, so hooks never fired. Added validation layer and tests to prevent future occurrences.
+
 ### 8. NEVER Use `console.*` in Production Code
 
 **Rule**: ALL `src/` code MUST use logger abstraction, NEVER `console.log/error/warn`.
@@ -320,7 +412,71 @@ export async function myCommand(options: CommandOptions = {}) {
 
 **Note**: Most standards are enforced by ESLint/Prettier. This list focuses on SpecWeave-specific rules and patterns that can't be auto-fixed by linters.
 
-### 10. Task Format with US-Task Linkage (v0.23.0+)
+### 10. GitHub Issue Format Policy (v0.24.0+)
+
+**CRITICAL**: ALL GitHub issues MUST use User Story-level format.
+
+**ONLY Correct Format**:
+```
+[FS-XXX][US-YYY] User Story Title
+```
+
+**Examples**:
+- ✅ `[FS-043][US-001] Status Line Shows Correct Active Increment`
+- ✅ `[FS-047][US-002] AC-Task Mapping`
+
+**Incorrect Formats** (NEVER use):
+- ❌ `[FS-047]` (Feature-only, missing US-ID)
+- ❌ `[SP-US-006]` (SP prefix, missing Feature ID)
+- ❌ `[SP-FS-047-specweave]` (SP prefix, project name)
+- ❌ `[INC-0047]` (Increment-only)
+
+**How to Create Issues**:
+```bash
+# CORRECT way (creates [FS-XXX][US-YYY] issues)
+node -e "
+const { GitHubFeatureSync } = require('./dist/plugins/specweave-github/lib/github-feature-sync.js');
+const { GitHubClientV2 } = require('./dist/plugins/specweave-github/lib/github-client-v2.js');
+
+const client = GitHubClientV2.fromRepo('anton-abyzov', 'specweave');
+const sync = new GitHubFeatureSync(client, '.specweave/docs/internal/specs', process.cwd());
+sync.syncFeatureToGitHub('FS-047').then(console.log).catch(console.error);
+"
+
+# WRONG way (deprecated, creates [FS-XXX] issues)
+/specweave:increment "feature"  # ← This no longer creates GitHub issues
+```
+
+**Why This Matters**:
+- **Features** are tracked via GitHub **Milestones** (not Issues)
+- **User Stories** are tracked via GitHub **Issues**
+- **Tasks** are tracked as **checkboxes** in User Story issue body
+
+**Architecture**:
+```
+Feature (FS-047)
+  ↓ GitHub Milestone #13
+  ├─ User Story (US-001) → GitHub Issue #638: [FS-047][US-001] Title
+  ├─ User Story (US-002) → GitHub Issue #639: [FS-047][US-002] Title
+  └─ User Story (US-003) → GitHub Issue #640: [FS-047][US-003] Title
+```
+
+**Deprecated Mechanisms**:
+- ❌ `post-increment-planning.sh` hook (disabled by default)
+- ❌ `update-epic-github-issue.sh` script (deprecated)
+- ❌ `generate-epic-issue-body.ts` script (deprecated)
+
+These created Feature-only issues with format `[FS-XXX]` which is INCORRECT.
+
+**Hooks Disabled**:
+- Increment-level GitHub sync in `post-increment-planning.sh` (disabled unless `SPECWEAVE_ENABLE_INCREMENT_GITHUB_SYNC=true`)
+- Epic sync in `post-task-completion.sh` (disabled unless `SPECWEAVE_ENABLE_EPIC_SYNC=true`)
+
+**See Also**:
+- `.specweave/increments/0047-us-task-linkage/reports/GITHUB-TITLE-FORMAT-FIX-PLAN.md`
+- `plugins/specweave-github/lib/user-story-issue-builder.ts:94`
+
+### 11. Task Format with US-Task Linkage (v0.23.0+)
 
 **CRITICAL**: ALL tasks MUST include User Story linkage fields for proper traceability.
 
@@ -397,6 +553,115 @@ When task marked completed in tasks.md:
 - Proposal: `.specweave/increments/0046-console-elimination/reports/US-TASK-LINKAGE-PROPOSAL.md`
 - Living Docs: `.specweave/docs/public/guides/bidirectional-linking.md`
 
+### 12. ADR Naming Convention (CRITICAL!)
+
+**Architecture Decision Records (ADRs) MUST follow strict naming convention**:
+
+**Correct Format**:
+- **Filename**: `XXXX-decision-title.md` (4-digit number, kebab-case, NO `adr-` prefix)
+- **Header**: `# ADR-XXXX: Decision Title` (includes `ADR-` prefix for document clarity)
+- **Location**: `.specweave/docs/internal/architecture/adr/`
+
+**Examples**:
+```
+✅ CORRECT:
+  Filename: 0007-github-first-task-sync.md
+  Header:   # ADR-0007: GitHub-First Task-Level Synchronization
+
+✅ CORRECT:
+  Filename: 0032-universal-hierarchy-mapping.md
+  Header:   # ADR-0032: Universal Hierarchy Mapping
+
+❌ WRONG:
+  Filename: adr-0007-github-first-task-sync.md  (NO adr- prefix!)
+  Reason:   Redundant (already in /adr/ directory)
+
+❌ WRONG:
+  Filename: ADR-0007-github-first-task-sync.md  (uppercase)
+  Reason:   Filenames must be lowercase
+
+❌ WRONG:
+  Filename: 007-github-first-task-sync.md  (3-digit)
+  Reason:   MUST be 4-digit (0001-9999)
+```
+
+**Why This Matters**:
+- **Consistency**: All ADRs follow same pattern (sortable, predictable)
+- **Clarity**: File location indicates type (in `/adr/` directory)
+- **Tooling**: Scripts expect 4-digit format for auto-numbering
+- **Cross-references**: Links use `adr/XXXX-name.md` format
+
+**Enforcement**:
+- Architect agent validates format before creating ADRs
+- Pre-commit hook checks for `adr-XXXX-*.md` pattern and rejects
+- `/specweave:validate` command verifies ADR naming
+
+**Common Mistakes**:
+1. Adding `adr-` prefix to filename (copying from header)
+2. Using 3-digit numbers instead of 4-digit (001 vs 0001)
+3. Uppercase filenames (ADR-0007 vs 0007)
+4. Missing kebab-case (spaces or underscores instead of hyphens)
+
+**Auto-Numbering**:
+To find next available ADR number (handles duplicates correctly):
+```bash
+ls .specweave/docs/internal/architecture/adr/*.md | \
+  grep -E '/[0-9]{4}-' | \
+  sed 's/.*\/\([0-9][0-9][0-9][0-9]\)-.*/\1/' | \
+  sort -u | \
+  tail -1 | \
+  awk '{printf "Next ADR: %04d\n", $1 + 1}'
+# Output: Next ADR: 0049
+# (Extracts unique numbers only, finds max, adds 1)
+```
+
+### 13. Archiving Logic Anti-Patterns (CRITICAL!)
+
+**NEVER use string search or substring matching for structured data matching**
+
+#### Anti-Pattern #1: String Search for Frontmatter Fields
+
+```typescript
+// ❌ WRONG: Matches ANYWHERE in file (false positives!)
+const content = await fs.readFile('spec.md', 'utf-8');
+if (content.includes('FS-039')) {
+  // This matches:
+  // - feature_id: FS-039 ✓ (correct)
+  // - "See FS-039 for details" ✗ (FALSE POSITIVE!)
+  // - [Related](FS-039) ✗ (FALSE POSITIVE!)
+}
+
+// ✅ CORRECT: Parse frontmatter explicitly
+const featureIdMatch = content.match(/^feature_id:\s*["']?([^"'\n]+)["']?$/m);
+if (featureIdMatch && featureIdMatch[1].trim() === 'FS-039') {
+  // Only matches actual frontmatter field
+}
+```
+
+#### Anti-Pattern #2: Substring Matching for IDs
+
+```typescript
+// ❌ WRONG: Substring matching (false positives!)
+const isArchived = archivedList.some(item => item.includes(searchId));
+// "0039-ultra-smart-v2".includes("0039-ultra-smart") → TRUE (WRONG!)
+
+// ✅ CORRECT: Exact equality
+const isArchived = archivedList.some(item => item === searchId);
+```
+
+**Why This Matters**:
+- **Incident 2025-11-20**: String search caused 11 features to be incorrectly archived
+- Features that merely REFERENCED another feature appeared to BELONG to it
+- Substring matching confused similar IDs as identical
+
+**Prevention**:
+1. Always parse structured data (YAML frontmatter, JSON) explicitly
+2. Use exact equality (`===`) for ID matching, never `.includes()`
+3. Add comprehensive logging to show matching decisions
+4. Test with edge cases: references, links, partial matches
+
+**See Also**: `.specweave/increments/0047-us-task-linkage/reports/CRITICAL-ARCHIVING-BUGS-FIX.md`
+
 ---
 
 ## Project Structure
@@ -418,6 +683,123 @@ plugins/                # Claude Code components (skills, agents, commands, hook
 
 ---
 
+## Plugin Hook Registration (CRITICAL!)
+
+**When**: Adding or modifying hooks that respond to Claude Code tool events
+
+**Hook Schema Rules** (v0.22.14+):
+1. ✅ **ONLY use valid Claude Code hook events** (e.g., PostToolUse, PreToolUse, SessionStart)
+2. ❌ **NEVER use custom hook names** (e.g., "TodoWrite") as hook events
+3. ✅ **Use matchers** to filter which tool calls trigger the hook
+
+### Valid Claude Code Hook Events
+
+Claude Code supports **only these 10 hook events**:
+- `PostToolUse` - After a tool completes (use this for TodoWrite, Write, Edit, etc.)
+- `PreToolUse` - Before a tool executes
+- `PermissionRequest` - When permission dialogs appear
+- `Notification` - When notifications are sent
+- `UserPromptSubmit` - When users submit prompts
+- `Stop` - When the main agent finishes
+- `SubagentStop` - When subagents finish
+- `PreCompact` - Before compaction operations
+- `SessionStart` - At session initialization
+- `SessionEnd` - When sessions terminate
+
+### Correct Hook Registration Format
+
+**File**: `plugins/*/. claude-plugin/plugin.json`
+
+```json
+{
+  "name": "specweave",
+  "version": "0.22.14",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Schema Breakdown**:
+| Field | Type | Purpose |
+|-------|------|---------|
+| `PostToolUse` | array | Hook event (one of 10 valid events above) |
+| `matcher` | string | Tool name pattern (e.g., "TodoWrite", "Write\|Edit") |
+| `type` | string | Always "command" for shell scripts |
+| `command` | string | Script path (use `${CLAUDE_PLUGIN_ROOT}` for plugin directory) |
+| `timeout` | number | Seconds before timeout (default: 30) |
+
+### Common Mistakes (v0.22.13 Bug)
+
+❌ **WRONG** (Invalid hook event):
+```json
+{
+  "hooks": {
+    "TodoWrite": {
+      "post": "./hooks/post-task-completion.sh"
+    }
+  }
+}
+```
+**Error**: `"TodoWrite"` is not a valid Claude Code hook event
+
+✅ **CORRECT** (Use PostToolUse with matcher):
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [{"type": "command", "command": "..."}]
+      }
+    ]
+  }
+}
+```
+
+### Testing Hook Registration
+
+```bash
+# 1. Update plugin.json with correct schema
+vim plugins/specweave/.claude-plugin/plugin.json
+
+# 2. Commit and push
+git add plugins/specweave/.claude-plugin/plugin.json
+git commit -m "fix: correct hook registration schema"
+git push origin develop
+
+# 3. Wait 5-10 seconds for marketplace auto-update
+
+# 4. Force refresh marketplace (if needed)
+cd ~/.claude/plugins/marketplaces
+rm -rf specweave
+git clone https://github.com/YOUR_USERNAME/specweave.git
+
+# 5. Restart Claude Code
+
+# 6. Verify no plugin loading errors
+# Should NOT see: "hooks: Invalid input" error
+```
+
+### Documentation References
+
+- **Claude Code Plugin Hooks**: https://code.claude.com/docs/en/hooks.md
+- **Hooks Reference**: https://code.claude.com/docs/en/hooks-reference.md
+- **Fix History**: See CHANGELOG.md v0.22.14 for the hook schema bug fix
+
+---
+
 ## Development Workflow
 
 ### Core Commands
@@ -477,10 +859,23 @@ claude plugin marketplace update specweave
 
 ```bash
 npm run rebuild    # Clean + build (use this during development)
-npm run build      # Compile TypeScript
+npm run build      # Compile TypeScript + copy hook dependencies
 npm run clean      # Remove dist/
 ```
 
+**Build Architecture**:
+1. `tsc` compiles `src/**/*.ts` → `dist/src/**/*.js`
+2. `copy:locales` copies translation files
+3. `copy:plugins` compiles plugin TypeScript with esbuild
+4. `copy:hook-deps` **NEW**: Copies hook dependencies to vendor/
+
+**Hook Dependencies** (NEW in v0.22.15):
+- Problem: Hooks imported from `../../../../dist/src/...` (failed in marketplace)
+- Solution: Copy compiled files to `plugins/*/lib/vendor/`
+- Hooks now import from `../vendor/...` (self-contained)
+- Script: `scripts/copy-hook-dependencies.js`
+- Auto-detect deps: `scripts/find-hook-dependencies.js`
+
 **Critical**: Always import with `.js` extensions:
 ```typescript
 // ✅ CORRECT
@@ -613,7 +1008,7 @@ vim .specweave/docs/public/guides/user-guide.md
 **Commands not working**: Verify plugin installed, restart Claude Code
 **Tests failing**: Run `npm run rebuild`, check test output
 **Root folder polluted**: Move files to `.specweave/increments/####/reports/`
-**Hooks failing**: Verify symlink (see "Symlink Setup" above)
+**Hooks failing**: Ensure changes are pushed to GitHub (Claude Code auto-updates marketplace every 5-10s). For symlink mode, see `.specweave/docs/internal/advanced/symlink-dev-mode.md`
 
 ---
 
@@ -644,7 +1039,7 @@ vim .specweave/docs/public/guides/user-guide.md
 - Tests: `tests/` (unit, integration, E2E)
 
 **Remember**:
-1. Symlink setup is MANDATORY for contributors
+1. Push changes to GitHub → Claude Code auto-updates marketplace (5-10s)
 2. Keep root clean (use increment folders)
 3. Test before committing
 4. Never delete .specweave/ directories

package/README.md

@@ -137,7 +137,30 @@ You → Manual → Write docs ❌ (4 hours/week wasted)
 
 **Total waste**: 9 hours/week = $35K/year per developer
 
-### The SpecWeave Solution: Bidirectional AI Integration
+### The SpecWeave Solution: AI with Three-Permission Sync
+
+**Control EXACTLY what Claude updates with three simple questions**:
+
+```mermaid
+graph TB
+    A[👤 You + Claude] -->|"Plan feature:\n/specweave:increment"| B{Q1: Can Claude CREATE\nand UPDATE work items\nit created?}
+    B -->|"✅ Yes"| C[📝 Create GitHub Issue #142]
+    B -->|"❌ No"| D[💻 Local Mode Only]
+
+    E[✅ Task Complete] -->|"Update content?"| F{Q2: Can Claude UPDATE\nwork items created\nexternally?}
+    F -->|"✅ Yes"| G[📤 Update PM-Created Issues]
+    F -->|"❌ No"| H[📋 Living Docs Only]
+
+    I[🔔 Issue Closed] -->|"Sync status?"| J{Q3: Can Claude UPDATE\nstatus of work items?}
+    J -->|"✅ Yes"| K[✅ Sync Status]
+    J -->|"❌ No"| L[👤 Manual Management]
+
+    style B fill:#339af0,stroke:#1971c2,stroke-width:3px,color:#fff
+    style F fill:#51cf66,stroke:#2f9e44,stroke-width:3px,color:#fff
+    style J fill:#ff8c42,stroke:#e8590c,stroke-width:3px,color:#fff
+```
+
+**Answer 3 questions during `specweave init`, Claude handles everything else**:
 
 ```
 You → Claude → EVERYTHING (automatic!)
@@ -146,20 +169,20 @@ You → Claude → EVERYTHING (automatic!)
 
 Claude creates:
 ✅ Spec.md (user stories, acceptance criteria)
-✅ JIRA Epic + 5 Stories (auto-created in your JIRA!)
-✅ GitHub Issue #142 (auto-created in your repo!)
+✅ JIRA Epic + 5 Stories (auto-created if Q1=Yes)
+✅ GitHub Issue #142 (auto-created if Q1=Yes)
 ✅ Tasks with embedded tests (BDD format)
 
 /specweave:do
 
 Claude implements Task 1:
 ✅ Code (AuthService.ts, tests, 92% coverage)
-✅ JIRA Story → "Done" (updated automatically!)
-✅ GitHub checkbox → ✓ (updated automatically!)
+✅ JIRA Story → "Done" (if Q2=Yes, updated automatically!)
+✅ GitHub checkbox → ✓ (if Q2=Yes, updated automatically!)
 ✅ Docs synced (ADRs, architecture, runbooks)
 ```
 
-**Your team/client/manager sees updates in real-time. You never touched JIRA.**
+**Your team/client/manager sees updates in real-time. Zero manual work.**
 
 ### What This Means in Practice
 
@@ -187,9 +210,9 @@ Claude implements Task 1:
 
 | Platform | Status | Capabilities |
 |----------|--------|--------------|
-| **GitHub Issues** | ✅ Production | Bidirectional sync, task tracking, auto-close, multi-repo |
-| **JIRA** | ✅ Production | Epic/Story sync, status updates, comments, unlimited projects |
-| **Azure DevOps** | ✅ Production | Work items, hierarchy, area paths, team-based organization |
+| **GitHub Issues** | ✅ Production | Three-permission sync, task tracking, auto-close, multi-repo |
+| **JIRA** | ✅ Production | Three-permission sync, Epic/Story sync, status updates, comments |
+| **Azure DevOps** | ✅ Production | Three-permission sync, Work items, hierarchy, area paths |
 | **Linear** | 🔄 Coming Q1 2026 | Full integration planned |
 | **Asana** | 🔄 Coming Q2 2026 | Full integration planned |
 
@@ -326,7 +349,7 @@ specweave init .
 
 ### Production Features
 
-- 🤖 **AI-Native Enterprise Sync** - Claude updates JIRA/GitHub/ADO automatically (bidirectional!)
+- 🤖 **AI-Native Enterprise Sync** - Claude updates JIRA/GitHub/ADO automatically (three-permission control)
 - 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
 - 🧪 **Test-Aware Planning** - Embedded tests in BDD format (Given/When/Then)
 - 🎯 **Disciplined Progress** - Can't start increment N+1 until N is DONE

package/dist/plugins/specweave-github/lib/ThreeLayerSyncManager.d.ts

@@ -1,5 +1,5 @@
 /**
- * Three-Layer Bidirectional Sync Manager
+ * Three-Layer Full Sync Manager (All Permissions Enabled)
  *
  * Handles synchronization across three layers:
  * - Layer 1: GitHub Issue (stakeholder UI)