specweave 1.0.265 → 1.0.266

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.264" sections="header,lsp,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.265" sections="header,lsp,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.264" -->
+<!-- SW:SECTION:header version="1.0.265" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
@@ -39,13 +39,13 @@ If auto-activation fails, invoke explicitly: `Skill({ skill: "name" })`
 
 Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
 
-<!-- SW:SECTION:lsp version="1.0.264" -->
+<!-- SW:SECTION:lsp version="1.0.265" -->
 ## LSP (Code Intelligence)
 
 **Native LSP broken in v2.1.0+.** Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
 <!-- SW:END:lsp -->
 
-<!-- SW:SECTION:start version="1.0.264" -->
+<!-- SW:SECTION:start version="1.0.265" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -55,7 +55,7 @@ Use: `specweave lsp refs|def|hover src/file.ts SymbolName`
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.264" -->
+<!-- SW:SECTION:autodetect version="1.0.265" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -65,7 +65,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.264" -->
+<!-- SW:SECTION:metarule version="1.0.265" -->
 ## Workflow Orchestration
 
 ### 1. Plan Mode Default
@@ -92,7 +92,7 @@ Good: npm run build → node script.js → Success
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.264" -->
+<!-- SW:SECTION:rules version="1.0.265" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
@@ -108,7 +108,7 @@ Good: npm run build → node script.js → Success
 8. **Multi-repo**: ALL repos MUST be at `repositories/{org}/{repo-name}/` — NEVER directly under `repositories/`
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.264" -->
+<!-- SW:SECTION:workflow version="1.0.265" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -148,7 +148,7 @@ Skills auto-recommend based on this matrix. In non-auto mode: ask user. In auto
 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.264" -->
+<!-- SW:SECTION:reflect version="1.0.265" -->
 ## Skill Memories
 
 SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
@@ -170,7 +170,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 - Auto mode: Stop hook creates implicit loops via block/approve pattern
 - **Team-lead for complex work**: After plan generation, ALWAYS assess complexity (task count + domain count). For 3+ domains or 15+ tasks, proactively recommend /sw:team-lead with token cost warning. In auto mode, auto-invoke team-lead for 3+ domains.
 
-<!-- SW:SECTION:context version="1.0.264" -->
+<!-- SW:SECTION:context version="1.0.265" -->
 ## Context
 
 **Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
@@ -178,7 +178,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.264" -->
+<!-- SW:SECTION:structure version="1.0.265" -->
 ## Structure
 
 ```
@@ -193,7 +193,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.264" -->
+<!-- SW:SECTION:taskformat version="1.0.265" -->
 ## Task Format
 
 ```markdown
@@ -203,41 +203,41 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.264" -->
+<!-- SW:SECTION:secrets version="1.0.265" -->
 ## Secrets
 
 Before CLI tools, check existing config (`grep -q` only — never display values).
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.264" -->
+<!-- SW:SECTION:syncing version="1.0.265" -->
 ## External Sync
 
 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.264" -->
+<!-- SW:SECTION:testing version="1.0.265" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest) | ESM mocking: `vi.hoisted()` + `vi.mock()`
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:tdd version="1.0.264" -->
+<!-- SW:SECTION:tdd version="1.0.265" -->
 ## TDD
 
 When `testing.defaultTestMode: "TDD"` in config.json: RED→GREEN→REFACTOR. Use `/sw:tdd-cycle`. Enforcement via `testing.tddEnforcement` (strict|warn|off).
 <!-- SW:END:tdd -->
 
-<!-- SW:SECTION:api version="1.0.264" -->
+<!-- SW:SECTION:api version="1.0.265" -->
 <!-- API: Enable `apiDocs` in config.json. Commands: /sw:api-docs -->
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.264" -->
+<!-- SW:SECTION:limits version="1.0.265" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.264" -->
+<!-- SW:SECTION:troubleshooting version="1.0.265" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -248,13 +248,13 @@ When `testing.defaultTestMode: "TDD"` in config.json: RED→GREEN→REFACTOR. Us
 | Session stuck | `rm -f .specweave/state/*.lock` + restart |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:lazyloading version="1.0.264" -->
+<!-- SW:SECTION:lazyloading version="1.0.265" -->
 ## Plugin Auto-Loading
 
 Plugins load automatically. Manual: `claude plugin install sw-frontend@specweave`. Disable: `export SPECWEAVE_DISABLE_AUTO_LOAD=1`
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.264" -->
+<!-- SW:SECTION:principles version="1.0.265" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -263,7 +263,7 @@ Plugins load automatically. Manual: `claude plugin install sw-frontend@specweave
 4. **No Laziness**: Root causes, senior standards
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.264" -->
+<!-- SW:SECTION:linking version="1.0.265" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -271,13 +271,13 @@ 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.264" -->
+<!-- SW:SECTION:mcp version="1.0.265" -->
 ## External Services
 
 CLI tools first (`gh`, `wrangler`, `supabase`) → MCP for complex integrations.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:auto version="1.0.264" -->
+<!-- SW:SECTION:auto version="1.0.265" -->
 ## Auto Mode
 
 `/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency)
@@ -285,7 +285,7 @@ CLI tools first (`gh`, `wrangler`, `supabase`) → MCP for complex integrations.
 Pattern: IMPLEMENT → TEST → FAIL? → FIX → PASS → NEXT. STOP & ASK if spec conflicts or ambiguity.
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.264" -->
+<!-- SW:SECTION:docs version="1.0.265" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com)

package/bin/specweave.js

@@ -870,7 +870,8 @@ const docsCmd = program
 docsCmd
   .command('preview')
   .description('Start documentation preview server with hot reload')
-  .option('-p, --port <number>', 'Port number (default: auto-find 3000-3010)')
+  .option('-p, --port <number>', 'Port number (default: 3015 internal, 3016 public)')
+  .option('-s, --scope <scope>', 'Documentation scope: internal or public (default: internal)')
   .option('-f, --force', 'Force reinstall Docusaurus')
   .option('--no-browser', 'Do not open browser automatically')
   .option('--no-validate', 'Skip pre-flight validation')
@@ -883,12 +884,14 @@ docsCmd
       noBrowser: !options.browser,
       validate: options.validate,
       autoFix: options.autoFix,
+      scope: options.scope || 'internal',
     });
   });
 
 docsCmd
   .command('build')
   .description('Build static documentation site for deployment')
+  .option('-s, --scope <scope>', 'Documentation scope: internal or public (default: internal)')
   .option('--no-validate', 'Skip pre-build validation')
   .option('--no-auto-fix', 'Do not auto-fix validation issues')
   .option('-o, --output <path>', 'Output directory')
@@ -898,17 +901,43 @@ docsCmd
       validate: options.validate,
       autoFix: options.autoFix,
       output: options.output,
+      scope: options.scope || 'internal',
     });
   });
 
 docsCmd
   .command('validate')
   .description('Validate documentation without starting server')
+  .option('-s, --scope <scope>', 'Documentation scope: internal or public (default: internal)')
   .option('--auto-fix', 'Auto-fix common issues')
   .option('-v, --verbose', 'Show all issues (not just errors)')
   .action(async (options) => {
     const { docsValidateCommand } = await import('../dist/src/cli/commands/docs.js');
-    await docsValidateCommand(options);
+    await docsValidateCommand({
+      autoFix: options.autoFix,
+      verbose: options.verbose,
+      scope: options.scope || 'internal',
+    });
+  });
+
+docsCmd
+  .command('public')
+  .description('Preview public documentation (shorthand for preview --scope public)')
+  .option('-p, --port <number>', 'Port number (default: 3016)')
+  .option('-f, --force', 'Force reinstall Docusaurus')
+  .option('--no-browser', 'Do not open browser automatically')
+  .option('--no-validate', 'Skip pre-flight validation')
+  .option('--no-auto-fix', 'Do not auto-fix validation issues')
+  .action(async (options) => {
+    const { docsPreviewCommand } = await import('../dist/src/cli/commands/docs.js');
+    await docsPreviewCommand({
+      port: options.port ? parseInt(options.port, 10) : undefined,
+      force: options.force,
+      noBrowser: !options.browser,
+      validate: options.validate,
+      autoFix: options.autoFix,
+      scope: 'public',
+    });
   });
 
 docsCmd
@@ -927,10 +956,10 @@ docsCmd
     await docsStatusCommand();
   });
 
-// Default action for 'specweave docs' without subcommand
+// Default action for 'specweave docs' without subcommand — launches internal preview
 docsCmd.action(async () => {
-  const { docsStatusCommand } = await import('../dist/src/cli/commands/docs.js');
-  await docsStatusCommand();
+  const { docsPreviewCommand } = await import('../dist/src/cli/commands/docs.js');
+  await docsPreviewCommand({ scope: 'internal' });
 });
 
 // Context command - Get project/board context for increment planning
@@ -1166,12 +1195,12 @@ program.on('--help', () => {
   console.log('  $ specweave context projects                # Get available projects as JSON');
   console.log('  $ specweave context boards --project myapp  # Get boards for a project');
   console.log('  $ specweave context select                  # Interactive project/board selection');
-  console.log('  $ specweave docs                            # Show docs status and help');
-  console.log('  $ specweave docs preview                    # Start docs server with hot reload');
-  console.log('  $ specweave docs preview --port 3015        # Start on specific port');
-  console.log('  $ specweave docs build                      # Build static site for deployment');
+  console.log('  $ specweave docs                            # Preview internal docs (port 3015)');
+  console.log('  $ specweave docs public                     # Preview public docs (port 3016)');
+  console.log('  $ specweave docs build                      # Build internal site');
+  console.log('  $ specweave docs build --scope public       # Build public site');
   console.log('  $ specweave docs validate                   # Check for docs errors');
-  console.log('  $ specweave docs validate --auto-fix        # Fix common issues automatically');
+  console.log('  $ specweave docs status                     # Show docs status');
   console.log('  $ specweave docs kill                       # Stop all docs servers');
   console.log('  $ specweave set-sync-target 0008            # Set sync target for increment');
   console.log('  $ specweave set-sync-target 0008 -v         # Show resolution path');