specweave 1.0.593 → 2.0.3

package/src/templates/CLAUDE.md.template

@@ -1,182 +1,7 @@
-# {PROJECT_NAME} - SpecWeave Reference
-
-<!-- SECTION:hook-priority required -->
-## Hook Instructions Override Everything
-
-`<system-reminder>` hook output = **BLOCKING PRECONDITIONS**.
-
-| Hook Message | Action |
-|---|---|
-| **"RESTART REQUIRED"** | ALL tools blocked → STOP, wait for restart |
-| **"SKILL FIRST"** | Call shown skill FIRST → chain domain skills → implement |
-
-**"SKILL FIRST" is mandatory** — "simple", "quick", "basic" are NOT opt-out phrases. The ONLY exception: user explicitly says "don't create an increment" or similar. Perceived simplicity never overrides hook instructions.
-
-**Setup actions are NOT implementation** — "connect github", "setup sync", "import issues" → route to the matching setup skill (`sw:sync-setup`, `sw:import`, `sw:progress-sync`), NOT `/sw:increment`.
-<!-- /SECTION -->
-
 <!-- SECTION:header required -->
-**Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
-<!-- /SECTION -->
-
-<!-- SECTION:claude-code-concepts -->
-## Skills & Plugins
-
-**Invoke**: `/skill-name` | auto-trigger by keywords | `Skill({ skill: "name" })`
-**Parallel work**: Append "use subagents" to requests
-
-**Key skills**: `sw:pm`, `sw:architect`, `sw:grill`, `sw:tdd-cycle`
-
-**Skill chaining** — skills are NOT "one and done":
-1. **Planning**: `sw:pm` (specs) → `sw:architect` (design)
-2. **Implementation**: Use `sw:architect` for all domains. Optional domain plugins available via `vskill install` (mobile, marketing, etc.)
-3. **Closure**: `sw:code-reviewer` + `/simplify` + `sw:grill` run automatically via `/sw:done`
-
-**Complexity gate** — before chaining domain skills:
-1. **Tech stack specified?** → Chain ONLY the matching skill. If unspecified, ASK or default to minimal (vanilla JS/HTML, simple Express)
-2. **Complexity triage** → Simple (calculator, todo) = 0 domain plugins. Medium (auth, dashboard) = 1-2. Complex (SaaS) = full chain
-3. **Sanity check** → Would a senior engineer use this tool for this task? If obviously not, don't invoke it
-4. **Never** load all available plugins for a domain — pick ONE per domain based on the actual tech stack
-
-If auto-activation fails, invoke explicitly: `Skill({ skill: "name" })`
-<!-- /SECTION -->
-
-<!-- SECTION:lsp -->
-## LSP (Code Intelligence)
-
-**Native LSP broken in v2.1.0+.** Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
-<!-- /SECTION -->
-
-<!-- SECTION:start -->
-## Getting Started
-
-Your first increment starts at `0001`. Just describe what you want to build:
-
-`/sw:increment "your-feature"`
-<!-- /SECTION -->
-
-<!-- SECTION:autodetect -->
-## Auto-Detection
-
-SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
-
-**Signals** (5+ = auto-route): Project name | Features list (3+) | Tech stack | Timeline/MVP | Problem statement | Business model
-
-**Opt-out phrases**: "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
-
-**Brainstorm routing**: "Just brainstorm first" | "brainstorm" | "ideate" | "what are our options" → routes to `/sw:brainstorm`
-
-**NOT opt-out phrases**: "simple" | "quick" | "basic" | "small" — these still require `/sw:increment`
-
-**Setup/config requests bypass auto-detection** → route directly to the matching skill (e.g., `sw:sync-setup`, `sw:import`)
-<!-- /SECTION -->
-
-<!-- SECTION:metarule required -->
-## Workflow Orchestration
-
-### 1. Plan Mode Default (MANDATORY)
-- **ALWAYS enter plan mode** for ANY non-trivial task (3+ steps or architectural decisions)
-- Call `EnterPlanMode` BEFORE writing specs, plans, or task breakdowns
-- Do NOT start implementation until the plan is reviewed and approved
-- If something goes sideways, **STOP and re-plan** -- do not keep pushing
-- Write detailed specs upfront to reduce ambiguity
-- `/sw:increment` REQUIRES plan mode -- never skip it
-
-### 2. Subagent Strategy (Context Economy)
-- **Protect main context** — the main agent's context window is precious; delegate anything that produces large output
-- **Research via subagents** — when the user provides URLs, links, or references external docs, spawn a subagent to fetch and summarize instead of loading raw content into main context
-- **Codebase exploration** — use Explore subagents for broad searches; only bring concise findings back to main context
-- **One task per subagent** — focused execution produces better results and cleaner summaries
-- **Parallel research** — launch multiple subagents concurrently when investigating independent questions
-- **Summarize, don't relay** — subagent results should be distilled to actionable insights before acting on them in main context
-- Append "use subagents" to requests for safe parallelization
-- In team mode, sub-agents submit plans for team lead review before implementing
-
-### 3. Verification Before Done
-- Never mark a task complete without proving it works
-- Run tests after every task: `npx vitest run` + `npx playwright test`
-- `sw:code-reviewer` writes `code-review-report.json` — CLI blocks closure if critical/high/medium findings remain
-- `/simplify` runs after code-review — catches duplication, readability issues, and inefficiencies via 3 parallel review agents
-- `/sw:grill` writes `grill-report.json` — CLI blocks closure without it
-- `/sw:judge-llm` writes `judge-llm-report.json` — WAIVED if consent denied
-- Ask yourself: **"Would a staff engineer approve this?"**
-
-### 5. Auto-Closure After Implementation (MANDATORY)
-- When `/sw:do` completes all tasks, IMMEDIATELY invoke `/sw:done` — do NOT stop to ask for review
-- The quality gates inside `/sw:done` (code-review, simplify, grill, judge-llm, PM validation) ARE the review — no user confirmation needed
-- `/sw:done` handles: code-review loop, simplify, grill report, judge-llm, PM gates, closure, sync to GitHub/Jira/ADO
-- If a gate fails, the increment stays open automatically — no risk of premature closure
-- If the user disagrees, they can re-open the increment
-- **Anti-pattern**: "All tasks complete. Should I close?" — NEVER ask this. Just close it.
-
-### 4. Think-Before-Act (Dependencies)
-**Satisfy dependencies BEFORE dependent operations.**
-```
-Bad:  node script.js → Error → npm run build
-Good: npm run build → node script.js → Success
-```
-<!-- /SECTION -->
-
-<!-- SECTION:rules required -->
-## Rules
-
-1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
-2. **Update immediately**: `Edit("tasks.md", "[ ] pending", "[x] completed")` + `Edit("spec.md", "[ ] AC-", "[x] AC-")`
-3. **Unique IDs**: Check ALL folders (active, archive, abandoned):
-   ```bash
-   find .specweave/increments -maxdepth 2 -type d -name "[0-9]*" | grep -oE '[0-9]{4}E?' | sort -u | tail -5
-   ```
-4. **Emergency**: "emergency mode" → 1 edit, 50 lines max, no agents
-5. **Initialization guard**: `.specweave/` folders MUST ONLY exist where `specweave init` was run
-6. **Plugin refresh**: Use `specweave refresh-plugins` CLI (not `scripts/refresh-marketplace.sh`)
-7. **Numbered folder collisions**: Before creating `docs/NN-*` folders, CHECK existing prefixes
-8. **Multi-repo**: ALL repos MUST be at `repositories/{org}/{repo-name}/` — NEVER directly under `repositories/`
-<!-- /SECTION -->
-
-<!-- SECTION:workflow required -->
-## Workflow
-
-`/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
+# {PROJECT_NAME}
 
-| Cmd | Action |
-|-----|--------|
-| `/sw:increment` | Plan feature |
-| `/sw:do` | Execute tasks |
-| `/sw:auto` | Autonomous execution |
-| `/sw:auto-status` | Check auto session |
-| `/sw:cancel-auto` | EMERGENCY ONLY manual cancel |
-| `/sw:validate` | Quality check |
-| `/sw:done` | Close |
-| `/sw:progress-sync` | Sync progress to all external tools |
-| `/sw-github:push` | Push progress to GitHub |
-| `/sw:sync-setup` | Connect GitHub/Jira/ADO integration |
-| `/sw:import` | Import issues from external tools |
-
-**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done` | "Ship while sleeping" → `/sw:auto`
-
-**Large-scale changes**: For codebase-wide migrations or bulk refactors, use `/batch` — decomposes work into parallel agents with worktree isolation, each producing its own PR. Example: `/batch migrate from Solid to React`
-<!-- /SECTION -->
-
-<!-- SECTION:save-nested-repos required -->
-## Nested Repos
-
-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`
-<!-- /SECTION -->
-
-<!-- SECTION:reflect -->
-## Skill Memories
-
-SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
-
-**Disable**: Set `"reflect": { "enabled": false }` in `.specweave/config.json`
-<!-- /SECTION -->
-
-<!-- SECTION:context -->
-## Context
-
-**Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
-
-**Load context**: `/sw:docs <topic>` loads relevant living docs into conversation
+SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -184,145 +9,80 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 
 ```
 .specweave/
-├── increments/####-name/     # metadata.json, spec.md, plan.md, tasks.md
-├── docs/internal/specs/      # Living docs
-└── config.json
+  increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
+  docs/                    ADRs and hand-written docs (read before changing architecture)
+  config.json
 ```
+Only those files (plus optional `plan.md` when Approach outgrows a page, and `scripts/`) live in an increment root; everything else goes in `reports/`. Commit messages start with the increment id: `0042: add login form`.
 
-**Increment root**: ONLY `metadata.json`, `spec.md`, `plan.md`, `tasks.md`
-
-**Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
+`tasks.md` format (the CLI parses it): `### T-01 Title` followed by one line `- AC: AC-01, AC-02 | Files: src/login.ts, src/login.test.ts | Test: npm test -- login`. `ledger.jsonl` is one JSON object per line, append-only: `{"t":"T-01","e":"claim|done|skip|release|block","by":"<tool>@<host>","at":"<ISO>","evidence":"<sha>","note":"<why>"}` (`evidence` required for `done`, `note` required for `skip`, both optional elsewhere).
 <!-- /SECTION -->
 
-<!-- SECTION:taskformat required -->
-## Task Format
-
-```markdown
-### T-001: Title
-**User Story**: US-001 | **Satisfies ACs**: AC-US1-01 | **Status**: [x] completed
-**Test**: Given [X] → When [Y] → Then [Z]
-```
-<!-- /SECTION -->
+<!-- SECTION:loop required -->
+## The loop
 
-<!-- SECTION:secrets required -->
-## Secrets
+| Step | Command |
+|---|---|
+| Plan a feature (spec.md with ACs + Approach, in plan mode; approved before any code) | `/sw:increment "title"` |
+| Work the tasks (claim → implement → commit → done with evidence) | `/sw:do` (loops `specweave task next` / `claim` / `done --run`) |
+| Verify the whole increment | `specweave verify` |
+| Review before closing (recommended for anything that ships: fresh context, findings cite path:line and are re-verified) | `/sw:review` |
+| Close (needs a green verify or `--reason`) | `/sw:done` |
+| Stop for any reason (context, tokens, switching tools) | `/sw:handoff` |
 
-Before CLI tools, check existing config (`grep -q` only — never display values).
+Start every feature with the increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
 <!-- /SECTION -->
 
-<!-- SECTION:syncing -->
-## External Sync
+<!-- SECTION:verify required -->
+## Verification before "done"
 
-Primary: `/sw:progress-sync`. Individual: `/sw-github:push`, `/sw-github:close`. Mapping: Feature→Milestone | Story→Issue | Task→Checkbox.
+Run the project's build/test/lint (see **Commands**) before reporting any task complete and paste the real output. `specweave task done T-NN --run "<test cmd>"` refuses a failing command. Never skip, weaken, or delete a test to make it pass. Never set `status: completed` by hand; use `/sw:done`.
 <!-- /SECTION -->
 
-<!-- SECTION:testing -->
-## Testing Pipeline (MANDATORY)
+<!-- SECTION:parallel required -->
+## Working in parallel (any tool, any account)
 
-**Testing is a pipeline step, not an afterthought.**
+1. One worktree per agent, named after the agent: `git worktree add ../NNNN-<agent> -b inc/NNNN-<agent>` (e.g. `../0042-claude -b inc/0042-claude`) or `claude --worktree NNNN-<agent>`. The branch name must contain the increment id.
+2. Claim before editing: `specweave task claim T-NN` (or `specweave task next`). Edit only that task's **Files**; need another file → claim its task or add a task. A claim older than 2h with no `done` is stale and may be re-claimed.
+3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
+4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."`, never ticked.
+5. When you stop: `specweave task release --all-mine` then `/sw:handoff`.
 
-### During Design (`/sw:increment`)
-- `/sw:increment` generates tasks.md with BDD test plans (Given/When/Then) for every AC via the sw-planner agent
-- Every task MUST have a `**Test Plan**:` block before implementation begins
-- E2E test scenarios MUST be specified for user-facing features
-
-### During Implementation (`/sw:do`)
-- TDD cycle: `/sw:tdd-red` → `/sw:tdd-green` → `/sw:tdd-refactor`
-- Run tests after EVERY task: `npx vitest run` (unit) + `npx playwright test` (E2E when applicable)
-- Never mark a task `[x]` until its tests pass
-
-### Before Closing (`/sw:done`)
-- `sw:code-reviewer` writes `code-review-report.json` — blocks closure if critical/high/medium findings remain (fix loop, max 3 iterations)
-- `/simplify` runs after code-review passes — cleans up code before grill
-- `/sw:grill` writes `grill-report.json` — CLI blocks closure without it
-- `/sw:judge-llm` writes `judge-llm-report.json` — WAIVED if consent denied
-- `/sw:validate` — 130+ rule checks
-- E2E: `npx playwright test` (blocking gate)
-
-### Test Stack
-- Unit/Integration: Vitest (`.test.ts`), ESM mocking with `vi.hoisted()` + `vi.mock()`
-- E2E: Playwright CLI (`npx playwright test`)
-- Coverage targets: unit 95%, integration 90%, e2e 100% of AC scenarios
+Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
 <!-- /SECTION -->
 
-<!-- SECTION:tdd -->
-## TDD
+<!-- SECTION:conventions required -->
+## Conventions
 
-When `testing.defaultTestMode: "TDD"` in config.json: RED→GREEN→REFACTOR. Use `/sw:tdd-cycle`. Enforcement via `testing.tddEnforcement` (strict|warn|off).
+- Secrets: confirm a key is present without printing its value (`grep -q NAME .env` or `Select-String -Quiet NAME .env`); never commit `.env*`.
+- Prefer deleting code over adapting it; change only what the task needs.
+- Check `.specweave/docs/` ADRs before architectural changes; record new decisions in spec.md **Approach** or an ADR. When a new increment replaces an old one, create it with `--supersedes NNNN` instead of leaving the old one open.
 <!-- /SECTION -->
 
-<!-- SECTION:api -->
-<!-- API: Enable `apiDocs` in config.json. Commands: /sw:api-docs -->
+<!-- SECTION:umbrella when="umbrella" -->
+- Umbrella projects only: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
 <!-- /SECTION -->
 
-<!-- SECTION:limits -->
-## Limits
-
-**Max 1500 lines/file** — extract before adding
-<!-- /SECTION -->
-
-<!-- SECTION:troubleshooting required -->
+<!-- SECTION:troubleshooting -->
 ## Troubleshooting
 
 | Issue | Fix |
-|-------|-----|
-| Skills missing | Restart Claude Code |
-| Plugins outdated | `specweave refresh-plugins` |
-| Out of sync | `/sw:sync-progress` |
-| Session stuck | `rm -f .specweave/state/*.lock` + restart |
-| npm E401 on update | `npm i -g specweave --registry https://registry.npmjs.org --userconfig /dev/null` |
-<!-- /SECTION -->
-
-<!-- SECTION:lazyloading -->
-## Plugin Auto-Loading
-
-Plugins load automatically. Manual: `specweave refresh-plugins` or `claude plugin install <name>@specweave`. Disable: `export SPECWEAVE_DISABLE_AUTO_LOAD=1`
-<!-- /SECTION -->
-
-<!-- SECTION:principles -->
-## Principles
-
-1. **Spec-first**: `/sw:increment` before coding — mandatory for ALL implementation requests, no exceptions unless user explicitly opts out
-2. **Docs = truth**: Specs guide implementation
-3. **Simplicity First**: Minimal code, minimal impact
-4. **No Laziness**: Root causes, senior standards
-5. **DRY**: Don't Repeat Yourself — flag and eliminate repetitions aggressively
-6. **Plan Review**: Review the plan thoroughly before making any code changes
-7. **Test before ship**: Tests pass at every step — unit after each task, E2E before close, no exceptions
-<!-- /SECTION -->
-
-<!-- SECTION:linking -->
-## Bidirectional Linking
-
-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)
-<!-- /SECTION -->
-
-<!-- SECTION:mcp -->
-## External Services
-
-CLI tools first (`gh`, `wrangler`, `supabase`) → MCP for complex integrations.
-<!-- /SECTION -->
-
-<!-- SECTION:auto -->
-## Auto Mode
-
-`/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency)
-
-Pattern: IMPLEMENT → TEST → FAIL? → FIX → PASS → NEXT. STOP & ASK if spec conflicts or ambiguity.
+|---|---|
+| Skills or hooks missing | `specweave doctor`, then `/reload-plugins` (restart if still missing) |
+| Instructions out of date after upgrade | `specweave update` |
+| Unsure who owns a task | `specweave task list` |
 <!-- /SECTION -->
 
-<!-- SECTION:docs -->
-## Docs
+## Commands
 
-[verified-skill.com](https://verified-skill.com)
-<!-- /SECTION -->
+| Action | Command |
+|---|---|
+| Build | `{{BUILD_CMD}}` |
+| Test | `{{TEST_CMD}}` |
+| Lint | `{{LINT_CMD}}` |
 
-<!-- SECTION:non-claude -->
-## Using SpecWeave with Other AI Tools
+If a cell still says TODO, fill it in from `package.json`/`Makefile` and commit; `specweave verify` runs these rows.
 
-See **AGENTS.md** for Cursor, Copilot, Windsurf, Aider instructions.
+## Project notes
 
-**Command format note**: This file uses `/sw:do` (Claude Code slash-command format). AGENTS.md uses `sw:do` (tool-agnostic format). Both refer to the same commands.
-<!-- /SECTION -->
+(architecture map, things agents get wrong here, recurring mistakes — keep it short)

package/src/templates/README.md.template

@@ -1,156 +1,26 @@
 # {{PROJECT_NAME}}
 
-**A SpecWeave project** - where specifications drive development.
+A [SpecWeave](https://verified-skill.com) project: work happens in increments under `.specweave/increments/NNNN-slug/`, each with a `spec.md` (Problem, acceptance criteria, Approach), a `tasks.md`, and an append-only `ledger.jsonl` that records who claimed and finished what.
 
-## Quick Start
+## Working on this project
 
-Your project is initialized! Now describe what you want to build.
+| Step | Command |
+|---|---|
+| Plan a feature | `specweave create-increment "title"` (Claude Code: `/sw:increment`) |
+| Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → `specweave task done T-NN --run "<test cmd>"` |
+| Verify | `specweave verify` |
+| Close | `specweave complete NNNN` |
+| Stop / hand off | `specweave handoff` |
 
-### Next Steps
+Agent instructions live in `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex, OpenCode, Cursor, Gemini, Aider). Both files keep a short managed block; the **Commands** table and **Project notes** at the bottom are yours to edit.
 
-1. **Open your AI assistant** (Claude Code, Cursor, Windsurf, or any AI-powered IDE)
-
-2. **Use SpecWeave commands** to start building:
-
-```
-# Plan a new feature
-sw:increment "user authentication with JWT"
-
-# Execute the implementation
-sw:do
-
-# Check progress
-sw:progress
-
-# Close when done
-sw:done 0001
-```
-
-> **Invocation varies by tool**: Claude Code uses `/sw:do`, Cursor/Copilot users type `sw:do` or describe the action. See AGENTS.md for details.
-
-3. **Or describe your project** in natural language (works with command workflows):
-
-```
-"Build a real estate listing platform with search, images, and admin dashboard"
-"Create a task management API with authentication"
-"Build an e-commerce platform with Stripe payments"
-```
-
-4. **SpecWeave will automatically**:
-   - Detect your tech stack (or ask you to choose)
-   - Use the right agents and skills (all pre-installed)
-   - Create strategic documentation
-   - Generate specifications (spec.md, plan.md, tasks.md)
-   - Guide implementation
-   - Generate tests
-
-That's it! All components ready - just use `sw:increment` to start!
-
----
-
-## Project Structure
-
-```
-{{PROJECT_NAME}}/
-├── .specweave/             # SpecWeave framework
-│   ├── config.json         # Project configuration
-│   ├── increments/         # Features (created via sw:increment)
-│   │   └── 0001-feature/
-│   │       ├── spec.md     # WHAT & WHY
-│   │       ├── plan.md     # HOW
-│   │       ├── tasks.md    # Implementation steps
-│   │       └── reports/    # Analysis reports
-│   └── docs/               # Strategic documentation
-│       ├── internal/       # Internal docs (strategy, architecture)
-│       └── public/         # Published docs
-├── CLAUDE.md               # Instructions for AI assistant
-└── README.md               # This file
-```
-
----
-
-## What is SpecWeave?
-
-SpecWeave is a specification-first development framework where:
-- **Specifications are the source of truth** (code follows specs, not reverse)
-- **Commands drive workflow** (`sw:increment` → `sw:do` → `sw:done`)
-- **AI agents work autonomously** (PM, Architect, Security, QA, DevOps)
-- **Works with ANY tech stack** (TypeScript, Python, Go, Rust, Java, .NET, etc.)
-- **Works with multiple AI assistants** (Claude Code, Cursor, Windsurf, etc.)
-
----
-
-## Core Workflow
+## Structure
 
 ```
-sw:increment "feature" → sw:do → sw:progress → sw:done → repeat
+.specweave/
+  increments/NNNN-slug/   spec.md · tasks.md · ledger.jsonl · handoff.md · reports/
+  docs/                    ADRs and hand-written docs
+  config.json
 ```
 
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `sw:increment "feature"` | Plan new increment | Starting new feature |
-| `sw:do` | Execute tasks | Ready to implement |
-| `sw:progress` | Check status | Want to see progress |
-| `sw:validate 0001` | Validate quality | Before completion |
-| `sw:done 0001` | Close increment | Feature finished |
-| `sw:team-lead "feature"` | Parallel agents | Complex multi-domain features |
-| `sw:progress-sync` | Sync to external tools | Export to GitHub/JIRA/ADO |
-
-For complex features spanning frontend, backend, and database — `sw:team-lead` splits work across parallel agents for faster delivery. [Learn more](https://verified-skill.com/docs/guides/agent-teams-and-swarms).
-
-See `CLAUDE.md` for complete workflow guide.
-
----
-
-## File Organization
-
-**Keep project root clean!** All AI-generated files go into increment folders:
-
-```
-CORRECT:
-.specweave/increments/0001-auth/
-├── reports/analysis.md
-└── logs/execution.log
-
-WRONG:
-project-root/
-├── execution.log
-└── analysis.md
-```
-
----
-
-## AI Assistant Compatibility
-
-SpecWeave works with:
-- **Claude Code** (recommended) - Full command support with auto-activation
-- **Cursor** - Commands via composer
-- **Windsurf** - Cascade mode compatible
-- **Any AI IDE** - Supports commands via prompts or native integrations
-
-**Setup**: See `CLAUDE.md` for AI assistant instructions.
-
----
-
-## Learn More
-
-- **Documentation**: https://verified-skill.com
-- **GitHub**: https://github.com/anton-abyzov/specweave
-- **Quick Reference**: See `CLAUDE.md` in your project
-
----
-
-## Ready to Build?
-
-**Start with your first feature**:
-```bash
-sw:increment "describe your feature here"
-```
-
-Or just describe what you want to build, and SpecWeave will guide you through the process!
-
----
-
-**Documentation Philosophy**: {{DOCUMENTATION_APPROACH}}
-
-**Tech Stack**: Auto-detected from project files (package.json, requirements.txt, etc.)
+Docs: https://verified-skill.com · Source: https://github.com/anton-abyzov/specweave

package/src/templates/git-hooks/pre-commit.template

@@ -2,7 +2,7 @@
 #
 # SpecWeave Pre-Commit Hook (User Projects)
 # Generated by: specweave init
-# Version: 1.0.0
+# Version: 2.0.0
 #
 # This hook enforces SpecWeave best practices to prevent common mistakes.
 # Checks run automatically on every commit to maintain code quality.
@@ -33,17 +33,9 @@ VALIDATION_FAILED=0
 echo "1️⃣  Checking for root folder pollution..."
 
 # Allowed root markdown files (standard project docs)
-ALLOWED_FILES=(
-  "README.md"
-  "CLAUDE.md"
-  "AGENTS.md"
-  "CHANGELOG.md"
-  "LICENSE.md"
-  "CODE_OF_CONDUCT.md"
-  "SECURITY.md"
-  "IMPLEMENTATION-SUMMARY.md"
-  "IMPLEMENTATION-COMPLETE.md"
-)
+# Space-separated, not a bash array: /bin/sh is dash on Debian/Ubuntu and
+# `ALLOWED_FILES=(...)` is a syntax error there, which aborts the whole hook.
+ALLOWED_FILES="README.md CLAUDE.md AGENTS.md CHANGELOG.md LICENSE.md CODE_OF_CONDUCT.md SECURITY.md IMPLEMENTATION-SUMMARY.md IMPLEMENTATION-COMPLETE.md"
 
 # Get staged markdown and log files in root (not in subdirectories)
 STAGED_ROOT_FILES=$(git diff --cached --name-only --diff-filter=AM | grep -E '^[^/]*\.(md|log)$' || true)
@@ -54,7 +46,7 @@ if [ -n "$STAGED_ROOT_FILES" ]; then
   for file in $STAGED_ROOT_FILES; do
     # Check if file is in allowed list
     is_allowed=0
-    for allowed in "${ALLOWED_FILES[@]}"; do
+    for allowed in $ALLOWED_FILES; do
       if [ "$file" = "$allowed" ]; then
         is_allowed=1
         break
@@ -90,7 +82,7 @@ if [ -n "$STAGED_ROOT_FILES" ]; then
     echo "   mkdir -p .specweave/increments/\$CURRENT/reports/"
     for file in $STAGED_ROOT_FILES; do
       is_allowed=0
-      for allowed in "${ALLOWED_FILES[@]}"; do
+      for allowed in $ALLOWED_FILES; do
         if [ "$file" = "$allowed" ]; then
           is_allowed=1
           break
@@ -104,7 +96,7 @@ if [ -n "$STAGED_ROOT_FILES" ]; then
     echo "   # Unstage old location, stage new location"
     for file in $STAGED_ROOT_FILES; do
       is_allowed=0
-      for allowed in "${ALLOWED_FILES[@]}"; do
+      for allowed in $ALLOWED_FILES; do
         if [ "$file" = "$allowed" ]; then
           is_allowed=1
           break
@@ -129,7 +121,10 @@ echo ""
 # ============================================================================
 # CHECK 2: Increment Folder Cleanliness
 # ============================================================================
-# Ensures increment folders stay organized (ONLY 4 files at root)
+# Ensures increment folders stay organized (only the canonical 2.0 artifacts at root)
+
+# Generated from INCREMENT_ROOT_FILES (src/core/increment/increment-artifacts.ts)
+ALLOWED_INCREMENT_ROOT_FILES="{{ALLOWED_INCREMENT_ROOT_FILES}}"
 
 echo "2️⃣  Checking increment folder cleanliness..."
 
@@ -150,8 +145,11 @@ if [ -n "$STAGED_INCREMENT_FILES" ]; then
       if ! echo "$relative_path" | grep -q '/'; then
         # File is at increment root - check if it's allowed
         filename=$(basename "$relative_path")
-        case "$filename" in
-          metadata.json|spec.md|plan.md|tasks.md)
+        # Membership test on the pipe-delimited allow-list. (A `case` pattern
+        # cannot come from a variable: `|` is syntax, not data, so `case $f in
+        # $LIST)` would compare against the literal string.)
+        case "|$ALLOWED_INCREMENT_ROOT_FILES|" in
+          *"|$filename|"*)
             # Allowed files
             ;;
           *)
@@ -159,11 +157,8 @@ if [ -n "$STAGED_INCREMENT_FILES" ]; then
             if [ $POLLUTION_FOUND -eq 0 ]; then
               echo "${RED}   ❌ Increment folder pollution detected!${NC}"
               echo ""
-              echo "   ${YELLOW}ONLY 4 files allowed at increment root:${NC}"
-              echo "   - metadata.json (required)"
-              echo "   - spec.md (required)"
-              echo "   - plan.md (optional)"
-              echo "   - tasks.md (required)"
+              echo "   ${YELLOW}Only these files are allowed at an increment root:${NC}"
+              echo "   ${YELLOW}   $(echo "$ALLOWED_INCREMENT_ROOT_FILES" | tr '|' ' ')${NC}"
               echo ""
               echo "   ${RED}Files in wrong location:${NC}"
               POLLUTION_FOUND=1
@@ -203,9 +198,10 @@ echo "3️⃣  Checking for duplicate increment IDs..."
 
 if [ -d ".specweave/increments" ]; then
   # Get all increment IDs across ALL directories (including _archive, _paused, etc.)
-  ALL_IDS=$(find .specweave/increments -maxdepth 2 -type d | \
-    grep -oE '/[0-9]{4}-' | \
-    sed 's|/||g' | sed 's|-||g' | \
+  # -name filters on the directory's OWN basename, so `0001-slug/reports`
+  # (depth 2) is NOT counted as a second `0001` while `_archive/0002-slug` is.
+  ALL_IDS=$(find .specweave/increments -maxdepth 2 -type d -name '[0-9][0-9][0-9][0-9]-*' | \
+    sed 's|.*/||' | cut -c1-4 | \
     sort)
 
   # Check for duplicates