@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/086-template-component-deduplication/README.md

@@ -1,146 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - refactoring
-  - templates
-  - maintenance
-priority: high
-created_at: '2025-11-17T01:27:01.679Z'
-updated_at: '2025-11-17T01:40:10.673Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T01:27:44.713Z'
-  - status: complete
-    at: '2025-11-17T01:40:10.673Z'
-completed_at: '2025-11-17T01:40:10.673Z'
-completed: '2025-11-17'
----
-
-# template-component-deduplication
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17 · **Tags**: refactoring, templates, maintenance
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-### Problem
-Template component files in `packages/cli/templates/_shared/agents-components/` contain significant code redundancy. When updating shared content (like status tracking requirements), we must edit multiple files with duplicate content, creating maintenance burden and risk of inconsistency.
-
-**Example redundancy patterns:**
-- `core-rules-base.md` and `core-rules-enterprise.md` both have "Never use nested code blocks" rule
-- `discovery-commands-{minimal,standard,enterprise}.md` share common intro text and progressive command additions
-- `essential-commands-{minimal,standard,enterprise}.md` have massive overlap (15→28→38 lines with shared sections)
-
-### Why Now
-We just improved status update instructions in AGENTS.md and had to update the same content in multiple files. This highlighted the maintenance problem and showed we need a DRY solution before making more updates.
-
-### Success Criteria
-- Shared content exists in exactly ONE file
-- Pattern-specific differences in separate addition files
-- Build system composes components automatically
-- Future updates to shared content require editing only one file
-- Generated AGENTS.md files remain functionally identical
-
-## Design
-
-### Refactoring Strategy
-
-Apply composition pattern (already proven for quality-standards):
-
-**1. Extract Shared Components**
-- Create base files with only truly common content
-- Name pattern: `{section}-shared.md`
-
-**2. Create Pattern-Specific Additions**
-- Files with only differences per pattern
-- Name pattern: `{section}-{pattern}-additions.md`
-
-**3. Use Array Composition in Config**
-```json
-"essentialCommands": [
-  "essential-commands-shared.md",
-  "essential-commands-standard-additions.md"
-]
-```
-
-### Files to Refactor
-
-**Priority 1: Essential Commands** (highest redundancy)
-- Shared: Header, Discovery, Viewing, Working basics, closing line
-- Minimal: Only basic commands
-- Standard: + Project Overview, Token Management, more detail
-- Enterprise: + Enterprise-specific commands
-
-**Priority 2: Discovery Commands** (progressive additions)
-- Shared: Intro text + base commands (stats, board, list, search)
-- Standard additions: + deps
-- Enterprise additions: + gantt
-
-**Priority 3: Core Rules** (one shared line)
-- Shared: "Never use nested code blocks" rule
-- Base additions: Base-specific rules
-- Enterprise additions: Enterprise-specific rules
-
-## Plan
-
-### Phase 1: Essential Commands Refactoring ✅ COMPLETE
-- [x] Analyze redundancy in essential-commands files
-- [x] Create `essential-commands-shared.md` with common content
-- [x] Create `essential-commands-minimal-additions.md`
-- [x] Create `essential-commands-standard-additions.md`
-- [x] Create `essential-commands-enterprise-additions.md`
-- [x] Update configs to use arrays
-- [x] Rebuild and verify output
-- [x] Delete old files
-
-### Phase 2: Discovery Commands Refactoring ✅ COMPLETE
-- [x] Create `discovery-commands-shared.md`
-- [x] Create pattern-specific addition files
-- [x] Update build script if needed (support for discoveryCommands array)
-- [x] Update configs
-- [x] Rebuild and verify
-- [x] Delete old files
-
-### Phase 3: Core Rules Refactoring ✅ COMPLETE
-- [x] Create `core-rules-shared.md`
-- [x] Create pattern-specific addition files
-- [x] Update configs
-- [x] Rebuild and verify
-- [x] Delete old files
-
-### Phase 4: Audit Other Components
-- [ ] Review remaining component files for redundancy
-- [ ] Document any other refactoring opportunities
-
-## Test
-
-- [ ] All three AGENTS.md templates generate successfully
-- [ ] Generated files are functionally identical to pre-refactor versions (diff check)
-- [ ] Build script supports arrays for all relevant config fields
-- [ ] No broken references to old component files
-- [ ] Token counts remain similar (no content lost)
-- [ ] Update status tracking instruction as test - should only require 1 file edit
-
-## Notes
-
-### Already Completed (Quality Standards)
-We successfully refactored quality-standards using this same approach:
-- Created `quality-standards-shared.md` (common standards)
-- Created `quality-standards-{minimal,enterprise}-additions.md`
-- Created `status-update-triggers.md` (extracted from workflow files)
-- Deleted `quality-standards-base.md` and `quality-standards-enterprise.md`
-
-This serves as the proven pattern for the remaining refactorings.
-
-### Build Script Enhancements
-Already supports:
-- `string | string[]` for workflow and qualityStandards
-- `readComponents()` function for composition
-
-May need to extend support to:
-- `discoveryCommands` (currently only string)
-- `coreRules` (currently only string)
-- `essentialCommands` (currently optional string)

package/.next/standalone/packages/ui/dist/standalone/specs/087-cli-ui-command/README.md

@@ -1,421 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - cli
-  - web
-  - dx
-  - integration
-priority: medium
-created_at: '2025-11-17T01:31:21.397Z'
-related:
-  - 035-live-specs-showcase
-  - 081-web-app-ux-redesign
-  - 082-web-realtime-sync-architecture
-updated_at: '2025-11-17T06:12:03.020Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T01:59:34.354Z'
-  - status: complete
-    at: '2025-11-17T06:12:03.020Z'
-completed_at: '2025-11-17T02:00:24.131Z'
-completed: '2025-11-17'
----
-
-# CLI UI Command: `lean-spec ui`
-
-> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-17 · **Tags**: cli, web, dx, integration
-
-**Project**: lean-spec  
-**Team**: Core Development  
-**Related**: Spec 035 (live-specs-showcase), Spec 081 (web-app-ux-redesign), Spec 082 (web-realtime-sync-architecture)
-
-## Current Status
-
-**Phase 1: CLI Command (Monorepo Mode)** - ✅ **COMPLETE**
-- Basic `lean-spec ui` command implemented with all options
-- Monorepo detection working (checks for `packages/web`)
-- Package manager auto-detection (pnpm/yarn/npm)
-- Port validation (1-65535 range)
-- Robust error handling and graceful shutdown
-- Unit tests passing
-- Code review feedback addressed
-
-### Implementation Approach
-
-**Phase 1: CLI command (packages/cli/src/commands/ui.ts)**
-- `startUi` validates ports, resolves specs via explicit flag, `.lean-spec/config.json`, YAML configs, or common folder heuristics.
-- `detectPackageManager()` centralizes pnpm/yarn/npm detection using user agents + lockfiles so both dev and production code paths invoke the right tool.
-- `runLocalWeb()` now sets `SPECS_MODE=filesystem`, inherits the detected package manager (`pnpm run dev`, `yarn run dev`, etc.), auto-opens the browser, and tears down cleanly on `SIGINT`.
-
-**Phase 2: Published runner (`runPublishedUI`)**
-- Outside the monorepo we construct the proper command (`pnpm dlx --prefer-offline @leanspec/ui ...`, `yarn dlx ...`, or `npx --yes ...`) and stream stdio straight through so the packaged UI owns the console experience.
-- Dry runs show the exact delegation command for both monorepo and external cases, enabling smoke tests without starting servers.
-
-**@leanspec/ui package (packages/ui/)**
-- Next.js config now emits `output: 'standalone'`, producing `/.next/standalone/packages/web/server.js` plus the necessary node_modules snapshot.
-- `scripts/prepare-dist.mjs`
-  - Ensures a fresh web build exists (running `pnpm --filter @leanspec/web build` on demand).
-  - Copies `.next/standalone`, `.next/static`, `public/`, and `BUILD_ID` into `packages/ui/dist/`, handling the nested `packages/web` path automatically.
-- `bin/ui.js`
-  - Resolves specs via flag/config/heuristics, validates ports, and exposes `--port`, `--specs`, `--no-open`, and `--dry-run` flags.
-  - Runs `node dist/standalone/packages/web/server.js` with `SPECS_MODE=filesystem`, opens the browser after launch, and surfaces troubleshooting hints when the build is missing.
-
-**Release automation**
-- `.github/workflows/publish-ui.yml` installs dependencies, runs `pnpm --filter @leanspec/ui build`, and publishes the package with provenance whenever a `ui-v*` tag is pushed or the workflow is dispatched.
-  
-**Phase 2: Standalone UI Package (packages/ui/)**
-
-Create new package `@leanspec/ui`:
-
-```json
-{
-  "name": "@leanspec/ui",
-  "version": "0.3.0",
-  "description": "Web UI for LeanSpec - visual spec management",
-  "bin": {
-    "leanspec-ui": "./bin/ui.js"
-  },
-  "dependencies": {
-    "@leanspec/core": "workspace:*",
-    "next": "16.0.1",
-    "react": "19.2.0",
-    "react-dom": "19.2.0"
-    // ... other web dependencies
-  },
-  "scripts": {
-    "build": "next build",
-    "start": "node bin/ui.js"
-  }
-}
-```
-
-**Standalone UI Wrapper (packages/ui/bin/ui.js):**
-
-```javascript
-#!/usr/bin/env node
-import { spawn } from 'child_process';
-import { resolve } from 'path';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const nextDir = join(__dirname, '..');
-
-// Parse CLI args
-const args = process.argv.slice(2);
-const specsDir = args[args.indexOf('--specs') + 1] || './specs';
-const port = args[args.indexOf('--port') + 1] || '3000';
-const noOpen = args.includes('--no-open');
-
-// Set environment variables
-process.env.SPECS_DIR = resolve(process.cwd(), specsDir);
-process.env.PORT = port;
-process.env.SPECS_MODE = 'filesystem'; // Force filesystem mode
-
-// Start Next.js server
-const child = spawn('next', ['start'], {
-  cwd: nextDir,
-  stdio: 'inherit',
-  env: process.env
-});
-
-// Open browser
-if (!noOpen) {
-  setTimeout(async () => {
-    const open = (await import('open')).default;
-    await open(`http://localhost:${port}`);
-  }, 2000);
-}
-
-process.on('SIGINT', () => {
-  child.kill();
-  process.exit(0);
-});
-```
-
-### Package Publishing Strategy
-
-**Option 1: Separate @leanspec/ui package** (Recommended)
-- **Pros**: Clean separation, can be used standalone, smaller CLI package
-- **Cons**: One more package to maintain
-- **Use case**: External projects using `npx lean-spec ui`
-
-**Option 2: Bundle in @leanspec/web**
-- **Pros**: Reuse existing package
-- **Cons**: Web package is currently private, larger dependency
-- **Use case**: Make `@leanspec/web` public with CLI wrapper
-
-**Option 3: Bundle in lean-spec CLI**
-- **Pros**: Single package install
-- **Cons**: CLI becomes massive (Next.js + React = ~50MB)
-- **Use case**: All-in-one installation
-
-**Recommendation: Option 1** - Create `@leanspec/ui` as a thin wrapper around `@leanspec/web` that:
-- Shares code with `@leanspec/web` (monorepo symlinks)
-- Has its own bin/ui.js entry point
-- Can be published separately
-- CLI delegates to it via `npx @leanspec/ui`
-
-### Auto-Detection Logic
-
-```typescript
-function detectSpecsDirectory(): string | null {
-  const candidates = [
-    './specs',
-    './spec',
-    './docs/specs',
-    './docs/spec',
-    './.lean-spec/specs'
-  ];
-  
-  for (const candidate of candidates) {
-    if (existsSync(resolve(process.cwd(), candidate))) {
-      return candidate;
-    }
-  }
-  
-  // Check for leanspec.yaml config
-  const configPath = resolve(process.cwd(), 'leanspec.yaml');
-  if (existsSync(configPath)) {
-    const config = yaml.load(readFileSync(configPath, 'utf-8'));
-    return config.specsDirectory || null;
-  }
-  
-  return null;
-}
-```
-
-### Integration with Spec 082 Architecture
-
-The web UI will use the **filesystem mode** (spec 082) for local projects:
-
-- Direct reads from `specs/` directory (no database required)
-- In-memory caching with 60s TTL
-- Realtime updates (changes appear within 60s)
-- No manual seeding or sync required
-
-**Environment Configuration:**
-```bash
-# Automatically set by lean-spec ui command
-SPECS_MODE=filesystem
-SPECS_DIR=/absolute/path/to/project/specs
-PORT=3000
-```
-
-## Plan
-
-### Phase 1: CLI Command (Week 1)
-
-**Day 1-2: Basic Command Implementation** - ✅ **COMPLETE**
-- [x] Create `packages/cli/src/commands/ui.ts`
-- [x] Implement command registration in registry
-- [x] Add monorepo detection logic (check for `packages/web`)
-- [x] Implement `runLocalWeb()` for dev mode
-- [x] Add port, specs-dir, and no-open options
-- [x] Add `--dry-run` flag for testing
-- [x] Test in LeanSpec monorepo
-- [x] Add port validation (1-65535)
-- [x] Auto-detect package manager (pnpm/yarn/npm)
-- [x] Fix race conditions and event listener leaks
-- [x] Comprehensive error handling
-
-**Day 3: External Package Delegation** - ✅ **COMPLETE**
-- [x] Implement `runPublishedUI()` that spawns pnpm/yarn/npm runners for `@leanspec/ui`
-- [x] Add specs directory auto-detection (config + heuristics)
-- [x] Add error handling for missing specs / missing build artifacts
-- [x] Add graceful shutdown (SIGINT handling)
-- [x] Test with and without local monorepo context (dry-run)
-
-### Phase 2: Standalone UI Package (Week 2) - ✅ **COMPLETE**
-
-**Day 4-5: Package Structure**
-- [x] Create `packages/ui/` directory
-- [x] Build wrapper + dist copier sourced from `packages/web`
-- [x] Create `bin/ui.js` wrapper script
-- [x] Update package.json with bin entry point + publish config
-- [x] Configure build scripts (`scripts/prepare-dist.mjs` + `prepublishOnly`)
-- [x] Add README with usage + troubleshooting instructions
-
-**Day 6-7: Standalone Build**
-- [x] Configure Next.js for standalone builds (`output: 'standalone'`)
-- [x] Test production build works and copies nested workspace paths
-- [x] Verify bundle completeness via `node packages/ui/bin/ui.js --dry-run`
-- [x] Add CLI arg parsing (--specs, --port, --no-open, --dry-run)
-- [x] Browser auto-open + graceful shutdown
-
-**Day 8: Integration Testing**
-- [x] Test `lean-spec ui` in monorepo (dev mode, dry-run)
-- [x] Test external invocation (`node ... ui --specs ... --dry-run`)
-- [x] Validate missing specs messaging + port validation
-- [ ] Full manual verification of realtime filesystem cache (tracked for follow-up release)
-
-### Phase 3: Documentation & Polish (Week 3)
-
-**Day 9-10: Documentation**
-- [x] Update CLI help text with `ui` command + specs override example
-- [x] Add examples to main README (Quick Start step 4)
-- [x] Create @leanspec/ui README with usage + env docs
-- [x] Document environment variables in the package README
-- [x] Add troubleshooting guide for the published package
-
-**Day 11-12: Publishing Preparation**
-- [x] Version bump coordination (`@leanspec/ui@0.3.0`)
-- [x] Update CHANGELOG.md
-- [ ] Test npm publish dry-run (handled during release freeze)
-- [x] Verify package.json metadata + files list
-- [ ] Test installation from npm registry (will happen after first publish)
-
-**Day 13: Release**
-- [ ] Publish `@leanspec/ui` to npm (next release tag `ui-v0.3.0`)
-- [ ] Publish updated `lean-spec` CLI to npm (bundled with release cadence)
-- [ ] Create GitHub release with notes
-- [ ] Announce feature in docs/social once npm publish is live
-
-## Test
-
-### Functional Testing
-
-**CLI Command:**
-- [x] `lean-spec ui` works in LeanSpec monorepo (dev mode dry-run)
-- [x] `lean-spec ui` works in external projects (delegates via pnpm/yarn/npm dry-run)
-- [x] `--specs` option overrides auto-detection
-- [x] `--port` option changes port correctly
-- [x] `--no-open` prevents browser from opening
-- [x] `--dry-run` shows what would run without executing
-- [x] Error message when specs directory not found
-- [x] Graceful shutdown on Ctrl+C
-- [x] Port validation (1-65535 range)
-- [x] Package manager detection (pnpm/yarn/npm)
-
-**Standalone UI Package:**
-- [ ] `npx @leanspec/ui` launches web UI (will verify after first publish)
-- [x] Dry-run confirms env vars (SPECS_MODE/SPECS_DIR) and command construction
-- [x] Works with custom `--specs` directory via CLI flag
-- [x] Browser auto-open + graceful shutdown logic implemented
-- [ ] Filesystem mode async cache + live reload acceptance (tracked via spec 082 instrumentation)
-- [ ] Cache updates work (realtime within 60s)
-
-**Integration:**
-- [x] CLI delegates to standalone package when outside the monorepo (dry-run verification)
-- [x] Monorepo dev mode takes precedence over published package
-- [ ] Both modes can run simultaneously (different ports)
-- [x] Process cleanup works (SIGINT propagated to child processes)
-
-### Performance Testing
-
-- [ ] Startup time <5s (cold start)
-- [ ] Startup time <2s (warm cache)
-- [ ] Memory usage reasonable (<200MB)
-- [ ] No memory leaks during extended runs
-
-### Compatibility Testing
-
-- [ ] Works on macOS
-- [ ] Works on Linux
-- [ ] Works on Windows (WSL)
-- [ ] Works with Node 20+
-- [ ] Works with npm, pnpm, yarn
-- [ ] Works when installed globally vs locally
-
-### User Experience Testing
-
-- [ ] Clear startup messages
-- [ ] Helpful error messages
-- [ ] Browser opens to correct page
-- [ ] UI loads specs correctly
-- [ ] Changes to specs appear within 60s
-- [ ] Shutdown is clean (no errors)
-
-## Notes
-
-### Design Decisions
-
-**Why separate @leanspec/ui package?**
-- **Clean separation**: CLI stays lightweight, UI is separate concern
-- **Standalone use**: Users can run `npx @leanspec/ui` directly
-- **Smaller CLI**: Don't bloat CLI with Next.js/React dependencies
-- **Easier maintenance**: UI can version independently
-
-**Why not bundle UI in CLI?**
-- **Size**: Next.js + React = ~50MB, too large for CLI
-- **Dependencies**: React, Next.js not needed for CLI users who never use UI
-- **Complexity**: Build process more complicated
-- **Performance**: Slower CLI startup if bundled
-
-**Why detect monorepo mode?**
-- **Dev experience**: LeanSpec contributors shouldn't need published package
-- **Faster iteration**: Local changes immediately available
-- **Flexibility**: Can test unreleased UI changes
-
-**Why filesystem mode (spec 082)?**
-- **No setup**: Works immediately, no database required
-- **Realtime**: Changes appear within 60s (cache TTL)
-- **Simple**: Single source of truth (specs/ directory)
-- **Fast**: <100ms reads from filesystem
-
-### Package Size Comparison
-
-| Package | Compressed | Unpacked | Dependencies |
-|---------|-----------|----------|--------------|
-| `lean-spec` CLI | ~500KB | ~2MB | 20 packages |
-| `@leanspec/ui` | ~5MB | ~25MB | Next.js, React, UI libs |
-| **Combined** | ~5.5MB | ~27MB | Separate installs |
-
-**If bundled in CLI**: ~50MB unpacked (not acceptable)
-
-### Alternative Approaches Considered
-
-**1. Embedded Server in CLI**
-- Pros: Single package
-- Cons: Massive size, complex build, slow startup
-- **Rejected**: Too complex, violates Unix philosophy
-
-**2. Static HTML Export**
-- Pros: No server needed, tiny package
-- Cons: No realtime updates, limited interactivity
-- **Rejected**: Defeats purpose of web UI
-
-**3. Electron App**
-- Pros: Native feel, auto-updates
-- Cons: Even larger (100MB+), more maintenance
-- **Rejected**: Overkill for this use case
-
-**4. Browser Extension**
-- Pros: Integrated in browser
-- Cons: Limited filesystem access, requires extension install
-- **Rejected**: Adds friction to workflow
-
-### Open Questions
-
-- [ ] Should we support watching for file changes (instant reload) beyond the filesystem cache window? (Deferred to a future spec once we feel pain)
-- [ ] Should we add `lean-spec ui export/share` flows for static hosting or temporary sharing?
-- [ ] Should we bundle a version checker (warn if CLI/UI versions are out of sync)? (Candidate for the docs polish phase)
-
-### Related Work
-
-- **Spec 035**: Live Specs Showcase - Web app foundation
-- **Spec 081**: Web App UX Redesign - UI improvements
-- **Spec 082**: Web Realtime Sync Architecture - Filesystem mode enables this
-
-### Future Enhancements
-
-**v0.4+:**
-- [ ] `lean-spec ui export` - Static HTML export
-- [ ] `lean-spec ui share` - Temporary public URL (via ngrok/tunneling)
-- [ ] `lean-spec ui --watch` - Instant reload on file changes
-- [ ] Desktop app wrapper (Tauri/Electron)
-- [ ] VSCode webview integration (spec 017)
-- [ ] Multi-project mode (switch between projects in UI)
-
-### Dependencies
-
-**This spec depends on:**
-- Spec 082 (filesystem mode) - Must be complete for realtime updates
-- Spec 081 (UX redesign) - UI should be polished before exposing via CLI
-
-**This spec enables:**
-- Better DX for visual learners
-- Easier onboarding (show, don't tell)
-- Spec 017 (VSCode extension) - Can embed UI in webview
-- External adoption - Easy way to explore LeanSpec

package/.next/standalone/packages/ui/dist/standalone/specs/088-core-concepts-terminology-only/README.md

@@ -1,106 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T02:09:38.041Z'
-updated_at: '2025-11-17T09:14:30.117Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T02:10:38.350Z'
-  - status: complete
-    at: '2025-11-17T02:10:43.845Z'
-  - status: planned
-    at: '2025-11-17T02:58:35.396Z'
-  - status: complete
-    at: '2025-11-17T09:14:30.117Z'
-completed_at: '2025-11-17T02:10:43.845Z'
-completed: '2025-11-17'
----
-
-# Core Concepts: Real SDD Terminology Only
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Users report that the current "Core Concepts" section in docs-site contains philosophy and principles rather than actual terminology definitions. This creates confusion for newcomers trying to understand SDD basics.
-
-**Problem**: Current Core Concepts mixes:
-- Philosophical principles (first principles, progressive disclosure)
-- Process guidance (workflow, decision-making)
-- Actual SDD terminology (specs, tokens, context)
-
-**Goal**: Restructure Core Concepts to be a **glossary of essential SDD terms** only:
-- **Spec**: What is a specification in SDD context
-- **Context**: What context means (human + AI working memory)
-- **Tokens**: Why tokens matter for AI + human cognition
-- **Agent**: AI agents in SDD workflow
-- **Status**: Spec lifecycle states
-- **Dependencies**: Relationship between specs
-- Other concrete terms users encounter when using LeanSpec
-
-**Non-Goals**: 
-- Philosophy content → move to "Philosophy & Principles" section
-- Workflow guidance → move to tutorials/guides
-- Decision frameworks → keep in methodology docs
-
-## Design
-
-**Restructure Core Concepts as a terminology glossary with definitions only.**
-
-Each concept entry should:
-1. **Definition**: What it is (1-2 sentences)
-2. **Why it matters**: Practical importance for SDD
-3. **Example**: Concrete example from LeanSpec usage
-4. **Related**: Links to deeper explanations
-
-**Priority order for inclusion**:
-1. Terms users encounter in first 5 minutes (spec, status, tokens)
-2. Terms in CLI/UI (tags, priority, dependencies)
-3. SDD methodology terms (context, agent, signal-to-noise)
-4. Advanced concepts (progressive disclosure, templates)
-
-**Content reorganization**:
-- Philosophy → New "Philosophy & Principles" section
-- Workflow → Move to step-by-step tutorials (spec 089)
-- Decision frameworks → Keep in "Methodology" docs
-
-**Term structure template**:
-```markdown
-### [Term Name]
-
-**Definition**: [One sentence explanation]
-
-**Why it matters**: [Practical importance in SDD workflow]
-
-**Example**: 
-[Concrete example from LeanSpec usage]
-
-**See also**: [Links to related concepts or deeper docs]
-```
-
-## Plan
-
-- [ ] Audit current Core Concepts docs - identify what's philosophy vs terminology
-- [ ] Create list of essential SDD terms users encounter
-- [ ] Write clean definitions for each term (using template)
-- [ ] Create new "Philosophy & Principles" section in docs
-- [ ] Move philosophical content to new section
-- [ ] Update navigation/sidebar in docs-site
-- [ ] Verify all cross-references still work
-
-## Test
-
-- [ ] New user can find definition of any term they encounter in first use
-- [ ] Each term has clear, concise definition (no philosophy/principles mixed in)
-- [ ] Examples are concrete and actionable
-- [ ] Philosophy content successfully moved to separate section
-- [ ] All internal doc links still work after reorganization
-
-## Notes
-
-<!-- Optional: Research findings, alternatives considered, open questions -->