specweave 1.0.255 → 1.0.257

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.254" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.256" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
 
 <!-- SW:SECTION:hook-priority version="1.0.171" -->
 ## ⛔ Hook Instructions Override Everything
@@ -11,7 +11,7 @@
 | **"SKILL FIRST"** | Call shown skill FIRST → chain domain skills → implement |
 <!-- SW:END:hook-priority -->
 
-<!-- SW:SECTION:header version="1.0.254" -->
+<!-- SW:SECTION:header version="1.0.256" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
@@ -31,24 +31,15 @@
 If auto-activation fails, invoke explicitly: `Skill({ skill: "name" })`
 <!-- SW:END:claude-code-concepts -->
 
-## Automatic Enforcement
-
-| Mechanism | Enforcement |
-|---|---|
-| `task-ac-sync` | Task completion → auto-updates spec.md ACs |
-| `tdd-enforcement` | Blocks GREEN if RED not done (strict mode) |
-| `grill` | Runs as first `/sw:done` step; blockers halt close |
-| `living-specs` | Updates docs on increment done/reopened/archived |
-
 <!-- SW:SECTION:skill-chaining version="1.0.179" -->
 <!-- Consolidated into Skills & Plugins section above -->
 <!-- SW:END:skill-chaining -->
 
-## LSP (Code Intelligence)
+## LSP
 
-**Native LSP broken in v2.1.0+.** Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
+Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
 
-<!-- SW:SECTION:start version="1.0.254" -->
+<!-- SW:SECTION:start version="1.0.256" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -58,7 +49,7 @@ If auto-activation fails, invoke explicitly: `Skill({ skill: "name" })`
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.254" -->
+<!-- SW:SECTION:autodetect version="1.0.256" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -68,7 +59,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.254" -->
+<!-- SW:SECTION:metarule version="1.0.256" -->
 ## Workflow Orchestration
 
 ### 1. Plan Mode Default
@@ -95,7 +86,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.254" -->
+<!-- SW:SECTION:rules version="1.0.256" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
@@ -116,7 +107,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
    Discover org from config: `repository.organization` → `sync.profiles` → `umbrella.childRepos` → filesystem
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.254" -->
+<!-- SW:SECTION:workflow version="1.0.256" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -142,7 +133,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 Before git operations, scan: `for d in repositories packages services apps libs workspace; do [ -d "$d" ] && find "$d" -maxdepth 2 -name ".git" -type d; done`
 <!-- SW:END:save-nested-repos -->
 
-<!-- SW:SECTION:reflect version="1.0.254" -->
+<!-- SW:SECTION:reflect version="1.0.256" -->
 ## Skill Memories
 
 SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
@@ -163,7 +154,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 - Prefer leaderboard-style reporting for analysis
 - Auto mode: Stop hook creates implicit loops via block/approve pattern
 
-<!-- SW:SECTION:context version="1.0.254" -->
+<!-- SW:SECTION:context version="1.0.256" -->
 ## Context
 
 **Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
@@ -171,7 +162,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Load context**: `/sw:docs <topic>` loads relevant living docs into conversation
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:structure version="1.0.254" -->
+<!-- SW:SECTION:structure version="1.0.256" -->
 ## Structure
 
 ```
@@ -186,7 +177,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.254" -->
+<!-- SW:SECTION:taskformat version="1.0.256" -->
 ## Task Format
 
 ```markdown
@@ -196,163 +187,53 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.254" -->
-## Secrets Check
+<!-- SW:SECTION:secrets version="1.0.257" -->
+## Secrets
 
-**BEFORE CLI tools**: Check existing config first!
-```bash
-# Check if credentials EXIST (never display values!)
-grep -qE "(GITHUB_TOKEN|GH_TOKEN|JIRA_|AZURE_DEVOPS_|ADO_)" .env 2>/dev/null && echo "Credentials found in .env"
-cat .specweave/config.json | grep -A5 '"sync"'
-gh auth status
-```
-
-**SECURITY**: NEVER use `grep TOKEN .env` without `-q` flag - it exposes credentials in terminal!
+Check credentials exist before CLI tools (`grep -q`, never display values). NEVER `grep TOKEN .env` without `-q`.
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.254" -->
-## External Sync (GitHub/JIRA/ADO)
-
-**Primary command**: `/sw:progress-sync` — syncs tasks.md → spec.md → living docs → external tools (auto-creates missing issues)
-
-**Individual commands**:
-| Command | Action |
-|---------|--------|
-| `/sw-github:create {id}` | Create GitHub issue for increment |
-| `/sw-github:push {id}` | Push task progress to GitHub issue |
-| `/sw-github:close {id}` | Close GitHub issue |
-| `/sw-github:status {id}` | Check sync status |
-| `/sw:sync-specs` | Sync living docs locally |
+<!-- SW:SECTION:syncing version="1.0.257" -->
+## External Sync
 
-**Mapping**: Feature → Milestone | Story → Issue | Task → Checkbox
-
-**Auto-configured**: Sync enabled by default during `specweave init` when a tracker is selected.
-
-**After task completion**: Run `/sw:progress-sync` or `/sw-github:push` to sync changes to external tools.
+Primary: `/sw:progress-sync`. Individual: `/sw-github:push`, `/sw-github:close`. Mapping: Feature→Milestone | Story→Issue | Task→Checkbox.
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:testing version="1.0.254" -->
+<!-- SW:SECTION:testing version="1.0.257" -->
 ## Testing
 
-BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
-
-```typescript
-// ESM mocking: vi.hoisted() + vi.mock() (Vitest 4.x+)
-const { mockFn } = vi.hoisted(() => ({ mockFn: vi.fn() }));
-vi.mock('./module', () => ({ func: mockFn }));
-```
-
-### Browser Automation Mode
-
-**Default**: `@playwright/cli` if installed (98% token reduction vs MCP)
-**Fallback**: Playwright MCP plugin (rich DOM introspection)
-**Config**: `testing.playwright.preferCli: true|false` in `.specweave/config.json`
-**Install CLI**: `npm install -g @playwright/cli@latest`
+BDD in tasks.md | Unit >80% | `.test.ts` (Vitest) | ESM mocking: `vi.hoisted()` + `vi.mock()`
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:tdd version="1.0.254" -->
-## TDD Mode (Test-Driven Development)
-
-**When `testing.defaultTestMode: "TDD"` is configured**, follow RED-GREEN-REFACTOR discipline:
-
-### TDD Workflow (MANDATORY when configured)
-
-```
-1. RED:     Write FAILING test first → verify it fails
-2. GREEN:   Write MINIMAL code to pass → no extra features
-3. REFACTOR: Improve code quality → keep tests green
-```
-
-### Check TDD Mode Before Implementation
-
-```bash
-# Check if TDD mode is enabled
-jq -r '.testing.defaultTestMode' .specweave/config.json
-# Returns: "TDD" | "test-first" | "test-after"
-```
-
-### TDD Commands
-
-| Command | Phase | Purpose |
-|---------|-------|---------|
-| `/sw:tdd-red` | RED | Write failing tests |
-| `/sw:tdd-green` | GREEN | Minimal implementation |
-| `/sw:tdd-refactor` | REFACTOR | Code quality improvement |
-| `/sw:tdd-cycle` | ALL | Full orchestrated workflow |
-
-### Enforcement Levels
-
-Set `testing.tddEnforcement` in config.json:
+<!-- SW:SECTION:tdd version="1.0.257" -->
+## TDD
 
-| Level | Behavior |
-|-------|----------|
-| `strict` | **BLOCKS** task completion if RED not done before GREEN |
-| `warn` | Shows warning but allows continuation (default) |
-| `off` | No enforcement |
-
-### TDD Task Format
-
-When TDD is enabled, tasks include phase markers:
-
-```markdown
-### T-001: [RED] Write auth service tests
-**Depends On**: None
-**Status**: [ ] pending
-
-### T-002: [GREEN] Implement auth service
-**Depends On**: T-001
-**Status**: [ ] pending
-
-### T-003: [REFACTOR] Extract token utilities
-**Depends On**: T-002
-**Status**: [ ] pending
-```
-
-**Rule**: Complete dependencies BEFORE dependent tasks (RED before GREEN).
+When `testing.defaultTestMode: "TDD"` in config.json: RED→GREEN→REFACTOR. Use `/sw:tdd-cycle`. Enforcement via `testing.tddEnforcement` (strict|warn|off). Tasks use `[RED]`/`[GREEN]`/`[REFACTOR]` markers with dependencies.
 <!-- SW:END:tdd -->
 
-<!-- SW:SECTION:api version="1.0.254" -->
-## API Development (OpenAPI-First)
-
-**For API projects only.** Commands: `/sw:api-docs --all` | `--openapi` | `--postman` | `--validate`
-
-Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
+<!-- SW:SECTION:api version="1.0.257" -->
+<!-- API docs: use /sw:api-docs when apiDocs.enabled in config -->
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.254" -->
+<!-- SW:SECTION:limits version="1.0.256" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.254" -->
+<!-- SW:SECTION:troubleshooting version="1.0.257" -->
 ## Troubleshooting
 
-| Issue | Fix |
-|-------|-----|
-| Skills/commands missing | Restart Claude Code |
-| Plugins outdated | `specweave refresh-marketplace` |
-| Out of sync | `/sw:sync-tasks` |
-| Duplicate IDs | `/sw:fix-duplicates` |
-| Edits blocked | Add `"additionalDirectories":["repositories"]` to `.claude/settings.json` |
-| Session stuck | Kill + `rm -f .specweave/state/*.lock` + restart |
+Skills missing → restart Claude Code | Plugins outdated → `specweave refresh-marketplace` | Stuck → `rm -f .specweave/state/*.lock` + restart
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:lazyloading version="1.0.254" -->
-## Plugin Auto-Loading
-
-Plugins load automatically based on project type and keywords. Manual install if needed:
-
-```bash
-claude plugin install sw-frontend@specweave  # Install plugin
-claude plugin list                           # Check installed
-export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
-```
+<!-- SW:SECTION:lazyloading version="1.0.257" -->
+## Plugins
 
-**Token savings**: Core ~3-5K tokens vs all plugins ~60K+
+Auto-loaded by project type. Manual: `claude plugin install sw-frontend@specweave`. Disable: `SPECWEAVE_DISABLE_AUTO_LOAD=1`.
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.254" -->
+<!-- SW:SECTION:principles version="1.0.256" -->
 ## Principles
 
 ### SpecWeave Principles
@@ -368,7 +249,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 - **Demand Elegance**: For non-trivial changes, pause and ask "is there a more elegant way?" - but skip this for simple, obvious fixes (don't over-engineer).
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.254" -->
+<!-- SW:SECTION:linking version="1.0.256" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -376,46 +257,19 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.254" -->
+<!-- SW:SECTION:mcp version="1.0.257" -->
 ## External Services
 
-**Priority**: CLI tools first (simpler) → MCP for complex integrations
-
-**CLI tools** (check auth first):
-```bash
-gh auth status          # GitHub
-wrangler whoami         # Cloudflare
-supabase status         # Supabase
-```
-
-**MCP servers** (for richer integrations):
-```bash
-claude mcp add --transport http github https://api.github.com/mcp
-claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres
-/mcp                    # Check status in Claude Code
-```
-
-MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
+CLI tools first (`gh`, `wrangler`, `supabase`) → MCP for complex integrations.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:auto version="1.0.254" -->
+<!-- SW:SECTION:auto version="1.0.257" -->
 ## Auto Mode
 
-**Commands**: `/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency only)
-
-**Pattern**: IMPLEMENT → TEST → FAIL? → FIX → PASS → NEXT
-
-**TDD in Auto Mode**: If `testing.defaultTestMode: "TDD"` is configured:
-- Use `/sw:auto --tdd` for strict enforcement (ALL tests must pass)
-- Auto mode reads config and displays TDD banner
-- Follow RED → GREEN → REFACTOR order for task triplets
-
-**Pragmatic completion**: MUST (MVP, security, data integrity) | SHOULD (edge cases) | CAN SKIP (conflicts - ask user)
-
-**STOP & ASK** if: Spec conflicts | Task unnecessary | Requirement ambiguous
+`/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency). Pattern: IMPLEMENT→TEST→FIX→NEXT. STOP & ASK if spec conflicts or ambiguous requirements.
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.254" -->
+<!-- SW:SECTION:docs version="1.0.256" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com)
@@ -423,26 +277,6 @@ MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 
 ---
 
-# SpecWeave Contributor Guide
+# Contributor Guide
 
-**Full guide**: [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md)
-
-| Rule | Detail |
-|---|---|
-| Completion | `/sw:done` only (NEVER edit metadata.json) |
-| Protected dirs | NEVER delete `.specweave/docs/`, `.specweave/increments/` |
-| Token budget | ~80k/increment, max 25 tasks, max 1500 lines/file |
-| Marketplace | Contributors: `scripts/refresh-marketplace.sh` \| Users: `specweave refresh-marketplace` |
-| No `name:` in frontmatter | Strips plugin prefix (`/sw:grill` → `/grill`) |
-| Plugin naming | CLI: `sw-*` \| Filesystem: `specweave-*` |
-| Imports | ALWAYS `.js` extensions |
-| Tests | `.test.ts`, `vi.fn()`, `os.tmpdir()` |
-| Logger | `logger` over `console.*` |
-
-```bash
-npm run rebuild                    # Clean + build
-npm test                           # All tests
-
-# Stuck: pkill -f "cat.*EOF" ; pkill -9 -f "bash.*specweave" ; rm -f .specweave/state/*.lock
-# Debug: SPECWEAVE_DEBUG_HOOKS=1 | SPECWEAVE_DISABLE_HOOKS=1
-```
+See [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md). Key: `.js` imports | `.test.ts` (Vitest) | `logger` over `console.*` | No `name:` in frontmatter | `npm run rebuild` + `npm test`