specweave 0.33.5 → 0.34.0

package/CLAUDE.md

@@ -15,8 +15,8 @@ For **contributors to SpecWeave itself** (not users).
 
 ```bash
 # Before editing large files outside increment:
-/specweave:pause XXXX → edit → /specweave:resume XXXX
-# OR close completed increments: /specweave:done XXXX
+/sw:pause XXXX → edit → /sw:resume XXXX
+# OR close completed increments: /sw:done XXXX
 ```
 
 ### 1b. Max 25 Tasks Per Increment (SOFT LIMIT)
@@ -65,7 +65,7 @@ Edit("metadata.json", '"status": "active"', '"status": "completed"')
 
 ✅ CORRECT workflow:
 1. All tasks completed → auto-transition to "ready_for_review"
-2. /specweave:done <id> → validates ACs + asks for user confirmation
+2. /sw:done <id> → validates ACs + asks for user confirmation
 3. Only then → status becomes "completed" with approvedAt timestamp
 ```
 
@@ -77,61 +77,69 @@ MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED);
 // Only succeeds if current status is "ready_for_review"
 ```
 
-### 2c. spec.md MUST Have project: (and board: for 2-level) - RESOLVED VALUES ONLY! (v0.34.0+)
+### 2c. Per-US **Project**: Fields are PRIMARY Source of Truth (ADR-0140, v0.35.0+)
 
-**Increment creation WITHOUT resolved project context = SYNC FAILURE**
+**Frontmatter `project:` and `board:` are OPTIONAL** - per-US fields are now PRIMARY!
 
-**⛔ YOU MUST RUN `specweave context projects` BEFORE GENERATING spec.md!**
-
-```bash
-# MANDATORY FIRST STEP - run this BEFORE generating any spec.md:
-specweave context projects
-
-# Parse the JSON output:
-# 1-level: {"level": 1, "projects": [{"id": "frontend-app"}, {"id": "backend-api"}]}
-# 2-level: {"level": 2, "projects": [...], "boardsByProject": {"project-id": [{"id": "board-1"}]}}
-
-# USE the actual IDs from the output - NEVER use placeholders!
-```
+**Resolution Priority Chain** (ProjectResolutionService):
+1. Per-US `**Project**:` fields (highest priority)
+2. `config.json` → `project.name` (single-project mode)
+3. Intelligent detection (keywords, tech stack)
+4. Ultimate fallback: "default"
 
 ```yaml
-# 1-level structure (RESOLVED values only):
----
-increment: 0001-feature-name
-project: frontend-app        # ← RESOLVED from context API (NOT {{PROJECT_ID}})
----
-
-# 2-level structure (BOTH RESOLVED):
+# NEW (v0.35.0+): Frontmatter project: is OPTIONAL
 ---
 increment: 0001-feature-name
-project: acme-corp           # ← RESOLVED from projects[].id
-board: digital-operations    # ← RESOLVED from boardsByProject[project][].id
+# NOTE: project: field REMOVED per ADR-0140
+# Project is resolved from per-US **Project**: fields or config
 ---
 ```
 
-**Per-US Project/Board (v0.34.0+ MANDATORY):**
+**Per-US Project/Board (PRIMARY SOURCE in spec.md):**
 ```markdown
 ### US-001: Login Form
-**Project**: frontend-app     # ← RESOLVED value, not placeholder!
-**Board**: ui-team            # ← RESOLVED value (2-level only)
+**Project**: frontend-app     # ← PRIMARY source of truth (in spec.md BODY)
+**Board**: ui-team            # ← Required for 2-level structures only
 ```
 
-**VALIDATION RULES (ENFORCED BY HOOK):**
+**CRITICAL: Two File Formats for Project Field**
+
+1. **spec.md** (increment folder): `**Project**:` in BODY of each user story
+2. **us-*.md** (living docs folder): `project:` in FRONTMATTER
+
+When living docs sync runs, it extracts `**Project**:` from spec.md body and places it in us-*.md frontmatter:
+
+```yaml
+# us-001-login-form.md frontmatter (living docs)
+---
+id: US-001
+project: frontend-app    # ← Extracted from spec.md **Project**: field
+---
 ```
-❌ FORBIDDEN: Generating spec.md WITHOUT running "specweave context projects" first
-❌ FORBIDDEN: Using {{PROJECT_ID}}, {{BOARD_ID}}, {{RESOLVED_PROJECT}} placeholders
-❌ FORBIDDEN: Inventing project/board names not in the API response
-❌ FORBIDDEN: User stories without **Project**: field
-❌ FORBIDDEN: User stories in 2-level without **Board**: field
-✅ REQUIRED: Run "specweave context projects" and parse output BEFORE generating
-✅ REQUIRED: Each US has **Project**: with RESOLVED value from API
-✅ REQUIRED: Each US (2-level) has **Board**: with RESOLVED value from API
+
+**Code Implementation Rules:**
+- **Generating GitHub issues**: Read from `frontmatter.project` in us-*.md files
+- **Parsing spec.md**: Extract from `**Project**:` in body using regex
+- **Living docs sync**: Transforms body field → frontmatter field
+
+**VALIDATION RULES (ENFORCED BY HOOKS):**
+```
+✅ Per-US **Project**: fields are PRIMARY source
+✅ Frontmatter project:/board: are OPTIONAL (deprecated but allowed)
+✅ Single-project mode: auto-resolves from config.project.name
+❌ FORBIDDEN: Using {{...}} placeholders in spec.md
+❌ FORBIDDEN: User stories without **Project**: field (multi-project mode)
+❌ FORBIDDEN: Multiple comma-separated projects per US
 ```
 
+**Pre-tool-use hook `spec-project-validator.sh` ALLOWS:**
+- spec.md WITHOUT frontmatter `project:` field (new best practice)
+- spec.md WITHOUT frontmatter `board:` field
+
 **Pre-tool-use hook `spec-project-validator.sh` BLOCKS:**
-- spec.md with `{{...}}` placeholders
-- spec.md without `project:` field
-- spec.md (2-level) without `board:` field
+- spec.md with `{{...}}` unresolved placeholders
+- Frontmatter project: that doesn't match config (if present)
 - User stories with unresolved `**Project**:` or `**Board**:` placeholders
 
 ### 2c-bis. Each User Story MUST Have **Project**: (and **Board**: for 2-level) (v0.34.0+)
@@ -202,9 +210,10 @@ SPECWEAVE_LEGACY_SPEC=1     # Allow legacy specs without per-US fields
 .specweave/docs/internal/specs/{project}/FS-116/FEATURE.md
 ```
 
-**Where `{project}` comes from:**
-1. spec.md YAML frontmatter `project:` field (MANDATORY)
-2. Example: `project: specweave` → `.specweave/docs/internal/specs/specweave/FS-116/`
+**Where `{project}` comes from (ADR-0140 v0.35.0+):**
+1. Per-US `**Project**:` field (PRIMARY - recommended)
+2. `config.json` → `project.name` (single-project mode fallback)
+3. Example: `**Project**: specweave` → `.specweave/docs/internal/specs/specweave/FS-116/`
 
 **Pre-tool-use hook `features-folder-guard.sh` BLOCKS writes to `_features/` (v0.33.0+).**
 
@@ -237,36 +246,44 @@ SPECWEAVE_LEGACY_SPEC=1     # Allow legacy specs without per-US fields
 
 **Pre-tool-use hook `increment-root-guard.sh` BLOCKS non-standard files at root (v0.33.0+).**
 
-### 2f. NEVER Create Duplicate Increment IDs (v0.33.0+)
+### 2f. NEVER Create Duplicate Increment IDs (v0.33.0+, enhanced v0.34.0)
 
 **Increment numbers MUST be unique across ALL directories!**
 
 ```
-❌ FORBIDDEN (Bug pattern from 2025-12-07):
+❌ FORBIDDEN (Bug pattern from 2025-12-07 and 2025-12-10):
 0121-ado-jira-feature-parity-p2-p3/  ← exists
 0121-intelligent-living-docs-content/ ← DUPLICATE!
 
+❌ ALSO FORBIDDEN when splitting increments:
+0141-frontmatter-removal-part1/  ← exists (original split)
+0141-frontmatter-removal-code/   ← DUPLICATE! (created later with same ID)
+
 ❌ ALSO FORBIDDEN (0001 and 0001E share SAME base number):
 0001-internal-feature/
 0001E-external-fix/  ← COLLISION! Same base number!
 ```
 
-**VALIDATION RULES:**
-```
-✅ ALWAYS use IncrementNumberManager.generateUniqueIncrementId()
-✅ ALWAYS use IncrementNumberManager.validateUnique() before creating
-✅ Check ALL directories: active, _archive, _abandoned, _paused
-```
+**MULTI-LAYER PREVENTION (v0.34.0+):**
+1. **Code-level**: `generateIncrementId()` now validates by default
+2. **Hook-level**: `increment-duplicate-guard.sh` blocks Write operations
+3. **Split-level**: Use `validateExplicitId()` when manually specifying IDs
 
-**API (v0.33.0+):**
+**API (v0.34.0+):**
 ```typescript
 import { IncrementNumberManager } from './core/increment/increment-utils.js';
 
-// Safe generation with validation:
-const id = IncrementNumberManager.generateUniqueIncrementId('feature-name');
-// → "0122-feature-name" (guaranteed unique)
+// RECOMMENDED: Auto-generated ID (validates by default)
+const id = IncrementNumberManager.generateIncrementId('feature-name');
+// → "0122-feature-name" (guaranteed unique, throws if duplicate)
+
+// For explicit IDs (e.g., splits): MUST validate first!
+IncrementNumberManager.validateExplicitId('0145-split-part2');
+// → Throws if 0145 already exists!
+
+// Then create folder only if validation passes
 
-// Manual validation:
+// Manual validation (still available):
 IncrementNumberManager.validateUnique('0121-new-name'); // throws if duplicate!
 
 // Find duplicates:
@@ -274,6 +291,17 @@ IncrementNumberManager.findDuplicates('0121');
 // → ["0121-ado-jira-feature (active)", "0121-intelligent-living-docs (active)"]
 ```
 
+**CRITICAL: When Splitting Increments:**
+```typescript
+// ❌ WRONG - Manually specifying ID without validation:
+const splitId = '0141-feature-part2';  // May conflict!
+fs.mkdirSync(path.join(incrementsDir, splitId));
+
+// ✅ CORRECT - Validate first:
+IncrementNumberManager.validateExplicitId('0145-feature-part2');  // Throws if exists!
+// Only proceed if no error thrown
+```
+
 **Pre-tool-use hook `increment-duplicate-guard.sh` BLOCKS duplicate increment creation (v0.33.0+).**
 
 ### 2f. Gap-Filling Increment IDs (v0.33.1+)
@@ -314,6 +342,249 @@ IncrementNumberManager.getNextIncrementNumber(); // "0001" ← Starts from begin
 
 **Details:** See ADR-0142 (`.specweave/docs/internal/architecture/adr/0142-gap-filling-increment-ids.md`)
 
+### 2g. NEVER Create Project Folders Without Validation (v0.34.0+, fixed v0.35.1)
+
+**Project folders MUST exist in config.json before creation!**
+
+```
+❌ FORBIDDEN (Bug pattern from 2025-12-11):
+.specweave/docs/internal/specs/MyApp (3 repos)/      ← Example from spec.md!
+.specweave/docs/internal/specs/frontend-app/         ← Example from spec.md!
+.specweave/docs/internal/specs/backend-api/          ← Example from spec.md!
+.specweave/docs/internal/specs/acme-corp/            ← Example from spec.md!
+.specweave/docs/internal/specs/{{PROJECT_ID}}.../    ← Unresolved placeholder!
+
+✅ CORRECT - Only configured projects:
+.specweave/docs/internal/specs/specweave/  (exists in config.json)
+```
+
+**ROOT CAUSE (Fixed in v0.35.1):**
+- Increments contain EXAMPLE User Stories with placeholder `**Project**:` values
+- `extractUserStoryProjectInfo()` in parsers.ts extracts ANY string after `**Project**:`
+- When sync runs, creates folders for ALL projects mentioned, including examples
+- v0.35.1 FIX: `ProjectResolutionService.validateProjectForFolderCreation()` now validates BEFORE folder creation
+
+**KNOWN EXAMPLE PROJECT NAMES (ALWAYS BLOCKED unless configured):**
+- `frontend-app`, `backend-api`, `mobile-app`, `shared-lib`
+- `acme-corp`, `my-app`, `myapp`, `example-project`, `sample-project`
+- `test-project`, `demo`, `placeholder`, `per`, `default`
+
+**MULTI-LAYER PROTECTION (v0.35.1+):**
+1. **Code-level**: `ProjectResolutionService.validateProjectForFolderCreation()` validates in TypeScript
+2. **Living-docs-sync**: Filters out invalid projects BEFORE calling `ensureDir()`
+3. **Cross-project-sync**: `ensureSpecsFolder()` throws Error if project invalid
+4. **Hook-level**: `project-folder-guard.sh` blocks Write operations to invalid folders
+
+**EXAMPLES OF FORBIDDEN PATTERNS:**
+```markdown
+### US-001: Example Login Form
+**Project**: MyApp (3 repos)  ← FORBIDDEN (parentheses not allowed!)
+
+### US-002: Example API
+**Project**: frontend-app, backend-api  ← FORBIDDEN (comma-separated!)
+
+### US-003: Placeholder Story
+**Project**: acme-corp  ← FORBIDDEN (example name not in config!)
+
+### US-004: Unresolved
+**Project**: {{PROJECT_ID}}  ← FORBIDDEN (unresolved placeholder!)
+```
+
+**VALIDATION RULES (ENFORCED BY CODE + HOOK):**
+```
+❌ FORBIDDEN: Creating folders for projects not in config.json
+❌ FORBIDDEN: Example/placeholder project names (see list above)
+❌ FORBIDDEN: Parentheses in project names (e.g., "MyApp (3 repos)")
+❌ FORBIDDEN: Comma-separated projects (must be ONE project per US)
+❌ FORBIDDEN: Template placeholders like {{PROJECT_ID}}
+
+✅ REQUIRED: All projects MUST be in config.project.name (single) or config.multiProject.projects (multi)
+✅ REQUIRED: Run `specweave context projects` to get valid project IDs
+✅ REQUIRED: Use RESOLVED values from config, never placeholders
+```
+
+**BYPASS (EMERGENCY ONLY):**
+```bash
+SPECWEAVE_FORCE_PROJECT=1  # Skip project folder validation (DANGEROUS!)
+```
+
+**API for validation (v0.35.1+):**
+```typescript
+import { ProjectResolutionService } from './core/project/project-resolution.js';
+
+const resolver = new ProjectResolutionService(projectRoot);
+
+// Validate before folder creation
+const validation = await resolver.validateProjectForFolderCreation('frontend-app');
+if (!validation.valid) {
+  console.error(`Cannot create folder: ${validation.reason}`);
+  console.log(`Allowed projects: ${validation.allowedProjects.join(', ')}`);
+}
+
+// Static sync check for hooks
+if (ProjectResolutionService.isExampleProjectName('frontend-app')) {
+  // Block - it's a known example name
+}
+```
+
+**Pre-tool-use hook `project-folder-guard.sh` BLOCKS writes to non-configured project folders (v0.35.1 enhanced).**
+
+### 2h. Single-Project-First Architecture (v0.34.0+)
+
+**SpecWeave defaults to single-project mode** for 99% of users. Multi-project is an explicit opt-in.
+
+```
+DEFAULT: Single-project mode (multiProject.enabled=false)
+OPT-IN:  Multi-project mode (/sw:enable-multiproject)
+```
+
+**Why Single-Project-First?**
+- **Simplicity**: Most repos have one project → no need for project complexity
+- **No Accidental Folders**: Example user stories don't create random project folders
+- **Clear Migration Path**: Explicit command when you need multi-project features
+- **Backwards Compatible**: Existing multi-project setups unaffected
+
+#### Single-Project Mode (Default)
+
+```json
+// config.json - single project
+{
+  "project": {
+    "name": "my-app",
+    "description": "My Application",
+    "techStack": ["TypeScript", "React"]
+  },
+  "multiProject": {
+    "enabled": false  // ← Default!
+  }
+}
+```
+
+**Behavior**:
+- All increments go to same project folder
+- No `project:` field required in spec.md (optional)
+- No `board:` field allowed (always blocked)
+- Living docs auto-use `project.name`
+
+**Commands**:
+```bash
+specweave init .  # Creates single-project config by default
+```
+
+#### Multi-Project Mode (Opt-In)
+
+```json
+// config.json - multi-project (after migration)
+{
+  "multiProject": {
+    "enabled": true,
+    "activeProject": "frontend-app",
+    "projects": {
+      "frontend-app": {
+        "name": "Frontend App",
+        "techStack": ["TypeScript", "React"]
+      },
+      "backend-api": {
+        "name": "Backend API",
+        "techStack": ["Node.js", "Express"]
+      }
+    }
+  }
+}
+```
+
+**Behavior**:
+- Each increment requires `project:` field in spec.md
+- Living docs distributed across project folders
+- Can switch between projects with `/sw:switch-project`
+
+**Commands**:
+```bash
+/sw:enable-multiproject  # Explicit opt-in with confirmation
+/sw:switch-project       # Change active project
+```
+
+#### When to Enable Multi-Project?
+
+| Scenario | Use Single-Project | Use Multi-Project |
+|----------|-------------------|-------------------|
+| One repository, one application | ✅ Default | ❌ Unnecessary |
+| Monorepo with 2-3 services | ✅ Simpler | ⚠️  Optional |
+| 5+ services/teams | ❌ Too simple | ✅ Recommended |
+| Multi-repo (umbrella) | ❌ Not supported | ✅ Required |
+
+**Migration Example**:
+```bash
+# You start with single-project (default):
+# project.name = "my-app"
+# multiProject.enabled = false
+
+# Later, you need multi-project features:
+/sw:enable-multiproject
+
+# Prompts for confirmation, then:
+# 1. Migrates project → multiProject.projects
+# 2. Sets multiProject.enabled = true
+# 3. Creates project folders
+# 4. Updates existing increments with project: field
+```
+
+#### Validation Rules
+
+**Single-Project Mode**:
+```markdown
+# spec.md frontmatter
+---
+increment: 0001-feature
+project: my-app        # ← OPTIONAL (auto-filled if missing)
+---
+
+# User story
+### US-001: Feature Name
+**Project**: my-app    # ← OPTIONAL (ignored in single-project)
+```
+
+**Multi-Project Mode**:
+```markdown
+# spec.md frontmatter
+---
+increment: 0001-feature
+project: frontend-app  # ← REQUIRED
+---
+
+# User story
+### US-001: Feature Name
+**Project**: frontend-app  # ← REQUIRED (validated against config)
+```
+
+#### Automatic Migration (v0.34.0+)
+
+**SpecWeave auto-detects single-project repos with incorrect config:**
+
+```
+If config.multiProject.enabled = true
+AND only 1 project in multiProject.projects
+THEN auto-migrate to single-project mode
+```
+
+This fixes the bug where `specweave init` created multi-project configs by default.
+
+**Migration log**: `.specweave/logs/migration.log`
+
+#### Troubleshooting
+
+**Error**: "Project folders created for example names (MyApp, frontend-app)"
+**Cause**: Old bug - auto-enabled multi-project mode
+**Fix**: Auto-migration runs on next command. Check `migration.log`.
+
+**Error**: "board: field not allowed"
+**Cause**: Using `board:` in single-project mode
+**Fix**: Remove `board:` field OR run `/sw:enable-multiproject`
+
+**Error**: "Only folder allowed: my-app"
+**Cause**: Trying to create non-configured project folder
+**Fix**: Check `project.name` in config OR run `/sw:enable-multiproject`
+
 ### 3. Protected Directories
 
 **NEVER delete**: `.specweave/docs/`, `.specweave/increments/`
@@ -464,13 +735,14 @@ rm -f .specweave/state/.dedup-cache/*.lock
 
 **Mental model**: Bash = "run a program". Write/Edit/Read = "modify files".
 
-### 11. Notifications - MUST Be Non-Alarming (v0.33.4+)
+### 11. Notifications - MUST Be Non-Alarming AND Non-Blocking (v0.33.4+)
 
 **All notifications are INFORMATIVE only - NEVER alarming!** Every notification MUST:
 1. **WHO** sent it (always start with "SpecWeave:")
 2. **WHAT** happened (specific action, not vague alert)
 3. **ACTION** needed (or "No action needed" if informational)
 4. **NEVER trigger alert icon** - no red/warning badges!
+5. **NEVER block execution** - fire-and-forget pattern ONLY!
 
 ```
 ❌ FORBIDDEN (alarming):
@@ -478,12 +750,48 @@ Title: "🚨 Zombie Cleanup"           ← Emoji overload
 Sound: "Basso"                       ← Shows RED ALERT ICON - NEVER USE!
 Message: "Cleaned up 5 processes"    ← Too vague
 
-✅ CORRECT (explicit, calm):
+❌ FORBIDDEN (blocking):
+execSync(`osascript -e 'display notification...'`)  ← BLOCKS main thread!
+await exec(`osascript -e 'display notification...'`)  ← BLOCKS cleanup/exit!
+
+✅ CORRECT (explicit, calm, non-blocking):
 Title: "SpecWeave: Cleanup Done"     ← Clear source
 Sound: "Pop" or "Submarine"          ← Neutral sounds ONLY
 Message: "Cleaned up 5 zombie processes. No action needed."
+exec(`osascript...`, (error) => { /* log */ })  ← Fire-and-forget!
 ```
 
+**CRITICAL: Fire-and-Forget Pattern (v0.33.6+)**
+
+**⛔ NEVER use `execSync()` or `await exec()` for notifications!**
+- Notifications MUST be **fire-and-forget** to prevent blocking Claude Code
+- macOS `osascript` can take 1-2 seconds → blocks session if awaited
+- Use callback-based `exec()` WITHOUT await/Promise wrapping
+
+```typescript
+// ❌ WRONG - BLOCKS execution!
+execSync(`osascript -e 'display notification...'`);
+await exec(`osascript -e 'display notification...'`);
+
+// ✅ CORRECT - Fire-and-forget!
+import('child_process').then(cp => {
+  cp.exec(`osascript -e 'display notification...'`, (error) => {
+    if (error) logger.debug(`Notification failed: ${error.message}`);
+  });
+});
+
+// Or using require (CommonJS):
+const { exec } = require('child_process');
+exec(`osascript -e 'display notification...'`, (error) => {
+  if (error) logger.debug(`Notification failed: ${error.message}`);
+});
+```
+
+**Files using notifications MUST follow fire-and-forget pattern:**
+- [src/utils/platform-utils.ts](src/utils/platform-utils.ts) (uses dynamic import)
+- [src/utils/notification-manager.ts](src/utils/notification-manager.ts) (resolves immediately)
+- [src/cli/cleanup-zombies.ts](src/cli/cleanup-zombies.ts) (uses childProcess.exec callback)
+
 **Sound selection rules (macOS only, other OS have no sound param):**
 | Sound | When to use |
 |-------|-------------|
@@ -508,7 +816,10 @@ const msg = buildNotificationMessage('cleanup', { count: 5 });  // "Cleaned up 5
 const sound = getSoundForType('cleanup');  // "Pop" (NEVER returns "Basso")
 ```
 
-**Code review should verify notification messages follow these standards.**
+**Code review should verify:**
+1. Notification messages follow WHO/WHAT/ACTION pattern
+2. All notification calls use fire-and-forget (no await/execSync)
+3. macOS notifications use dynamic import or callback pattern
 
 ---
 
@@ -521,7 +832,7 @@ git add . && git commit -m "feat: feature" && git push origin develop
 ```
 
 **Marketplace**: `bash scripts/refresh-marketplace.sh` (GitHub mode, always use)
-**NPM Release**: `/specweave-release:npm`
+**NPM Release**: `/sw-release:npm`
 
 ---
 
@@ -652,7 +963,7 @@ board: digital-operations     # REQUIRED for 2-level structures
 Use `DuplicateDetector.createWithProtection()`, NEVER `--limit 1` in gh searches
 
 ### AC Presence in spec.md
-**MANDATORY** - even with external living docs. Use `/specweave:embed-acs` if missing.
+**MANDATORY** - even with external living docs. Use `/sw:embed-acs` if missing.
 
 ### Git Provider Abstraction
 Use `getPlatformRegistry().getProvider('github')`. NEVER hardcode platform names/endpoints.
@@ -661,20 +972,66 @@ Use `getPlatformRegistry().getProvider('github')`. NEVER hardcode platform names
 
 ## Configuration
 
-**Secrets** (`.env`, gitignored): Tokens, PATs, emails
-**Config** (`.specweave/config.json`, committed): Domains, strategies, sync settings
+### Secrets vs Configuration (v0.34.0+ MANDATORY)
+
+**CRITICAL**: Configuration values MUST NOT be in .env. Use config.json via ConfigManager.
+
+**Secrets** (`.env`, gitignored):
+- `AZURE_DEVOPS_PAT` - Personal Access Token
+- `JIRA_API_TOKEN` - API Token
+- `JIRA_EMAIL` - Auth email
+- `GH_TOKEN` / `GITHUB_TOKEN` - GitHub token
+
+**Config** (`.specweave/config.json`, committed):
+- `issueTracker.domain` - JIRA domain (e.g., "company.atlassian.net")
+- `issueTracker.organization_ado` - ADO organization name
+- `issueTracker.project` - Project name
+- `sync.profiles` - Sync profile configurations
+
+### FORBIDDEN Patterns (Pre-tool-use hook blocks these)
+```typescript
+// NEVER DO THIS in src/ files:
+const domain = process.env.JIRA_DOMAIN;  // VIOLATION!
+const org = process.env.AZURE_DEVOPS_ORG;  // VIOLATION!
+
+// ALWAYS DO THIS:
+const config = await this.configManager.read();
+const domain = config.issueTracker?.domain || '';
+const org = config.issueTracker?.organization_ado || '';
+```
+
+### Migration from .env to config.json
+```bash
+# 1. Add to config.json
+specweave config set issueTracker.domain "company.atlassian.net"
+specweave config set issueTracker.organization_ado "my-org"
+
+# 2. Remove deprecated vars from .env (keep only secrets)
+# JIRA_DOMAIN=xxx  # DELETE THIS LINE
+# AZURE_DEVOPS_ORG=xxx  # DELETE THIS LINE
+
+# 3. Keep these in .env (secrets):
+AZURE_DEVOPS_PAT=xxx
+JIRA_API_TOKEN=xxx
+JIRA_EMAIL=xxx
+```
+
+### ADR Reference
+See ADR-0194 for full architecture decision.
 
 ---
 
 ## Commands
 
 ```bash
-/specweave:increment "feature"  # Plan new increment
-/specweave:do                   # Execute tasks
-/specweave:done 0002            # Close (validates gates)
-/specweave:progress             # Show status
-/specweave:sync-progress        # Full sync (tasks→docs→GitHub/JIRA/ADO)
-/specweave:validate 0001        # Validate increment
+/sw:increment "feature"    # Plan new increment
+/sw:do                     # Execute tasks
+/sw:done 0002              # Close (validates gates)
+/sw:progress               # Show status
+/sw:sync-progress          # Full sync (tasks→docs→GitHub/JIRA/ADO)
+/sw:validate 0001          # Validate increment
+/sw:living-docs            # Launch living docs builder (interactive)
+/sw:living-docs --full-scan # Full deep scan (all phases: repos, org, arch, inconsistencies, strategy)
 ```
 
 ---