principles-disciple 1.71.0 → 1.73.0

package/.planning/codebase/CONCERNS.md

@@ -1,145 +0,0 @@
-# Codebase Concerns
-
-**Analysis Date:** 2026-04-15
-
-## Tech Debt
-
-**Large Monolithic Files:**
-- Issue: `evolution-worker.ts` is 2689 lines, `nocturnal-trinity.ts` is 2429 lines. These exceed reasonable single-file thresholds and make debugging/profiling difficult.
-- Files: `src/service/evolution-worker.ts`, `src/core/nocturnal-trinity.ts`
-- Impact: Hard to trace bugs, no granular profiling, high risk of regression on modification
-- Fix approach: Break into smaller focused modules (e.g., queue-processor.ts, workflow-watchdog.ts, sleep-cycle.ts)
-
-**Type Safety Workarounds:**
-- Issue: Extensive use of `as any`, `as unknown`, and double casts (`as unknown as`) throughout the codebase
-- Files: `src/hooks/prompt.ts`, `src/hooks/subagent.ts`, `src/service/evolution-worker.ts`, `src/commands/promote-impl.ts`, `src/commands/rollback.ts`, `src/commands/pain.ts`
-- Impact: Type errors are silenced rather than fixed, runtime type mismatches can go undetected
-- Fix approach: Define proper shared type interfaces, use discriminated unions
-
-**Busy-Wait Retry Loops:**
-- Issue: `src/utils/io.ts` uses busy-wait spin loops (`while (Date.now() < end)`) for Windows file lock retries
-- Files: `src/utils/io.ts` (lines 32-33)
-- Impact: Consumes CPU while waiting; fails to yield to event loop
-- Fix approach: Use `setTimeout` delay or `fs.promises` with proper async retry
-
-**Unhandled Promise Rejections:**
-- Issue: Comments in `evolution-worker.ts` (line 182) reference unhandled rejections leaving workflows in limbo. Pattern of catch blocks that re-throw or log but don't always propagate.
-- Files: `src/service/evolution-worker.ts`
-- Impact: Workflows stuck in inconsistent state, silent failures
-- Fix approach: Ensure all async operations have proper error handlers; use `process.on('unhandledRejection')` logging
-
-**TODO Comments Not Addressed:**
-- Issue: One active TODO in `src/hooks/bash-risk.ts:18` — "Extract types from gate.ts related to bash risk analysis"
-- Files: `src/hooks/bash-risk.ts`
-
-## Known Bugs
-
-**Stale Active Workflows (#185):**
-- Symptoms: Workflows marked 'active' but subagent never responds, blocking queue processing
-- Files: `src/service/evolution-worker.ts` (runWorkflowWatchdog)
-- Trigger: Subagent crash or network failure during workflow execution
-- Workaround: Watchdog marks them as 'terminal_error' after 2x TTL
-
-**Orphaned Sessions (#188):**
-- Symptoms: Child session cleanup fails when subagent runtime unavailable
-- Files: `src/service/evolution-worker.ts` (cleanup path)
-- Trigger: Gateway-safe fallback fails
-- Workaround: Manual cleanup required
-
-**Sleep Reflection Timeout Recovery (#214, #219):**
-- Symptoms: `sleep_reflection` tasks stuck in 'in_progress' after worker crash
-- Files: `src/service/evolution-worker.ts` (lines 1122-1198)
-- Trigger: Worker crashes after claiming task but before writing result
-- Fix: Timeout recovery logic reclaims stuck tasks after `task_timeout_ms`
-
-## Security Considerations
-
-**Credential Detection in Logs:**
-- Risk: Sensitive data (passwords, tokens, api_keys) may leak into event logs or trajectory data
-- Files: `src/hooks/trajectory-collector.ts`, `src/core/nocturnal-arbiter.ts`, `src/core/nocturnal-compliance.ts`
-- Current mitigation: `SENSITIVE_KEY_PATTERN` regex filters known patterns
-- Recommendations: Extend pattern to cover more formats; add redaction before any async write
-
-**Gateway Token Auth:**
-- Risk: HTTP route in `principles-console-route.ts` uses Bearer token auth
-- Files: `src/http/principles-console-route.ts`
-- Current mitigation: Token comparison with configured value
-- Recommendations: Use constant-time comparison to prevent timing attacks
-
-**No eval() or Dynamic Code Execution:**
-- Status: Clean — no `eval()`, `new Function()`, or `dangerouslySetInnerHTML` found in codebase
-
-## Performance Bottlenecks
-
-**Session Persistence Timer Per Session:**
-- Problem: `session-tracker.ts` creates a `setTimeout` per session for delayed persistence writes
-- Files: `src/core/session-tracker.ts`
-- Cause: Timer per workspace/session scales poorly with many concurrent sessions
-- Improvement path: Use a single periodic sweep for all dirty sessions
-
-**Event Log Buffer Flush:**
-- Problem: 20-event buffer or 30-second flush interval — events can be lost on crash
-- Files: `src/core/event-log.ts`
-- Cause: Trade-off between I/O frequency and durability
-- Improvement path: Flush immediately on critical events (hook failures, errors)
-
-**Evolution Queue File Read on Every Cycle:**
-- Problem: `evolution-worker.ts` reads and parses the entire queue JSON file on each heartbeat
-- Files: `src/service/evolution-worker.ts` (queue loading at lines 1085-1110)
-- Cause: Full file read/parse despite incremental changes
-- Improvement path: Use SQLite or incremental updates
-
-**Focus History Compression Timestamp:**
-- Problem: `focus-history.ts` writes `Date.now().toString()` on every compression
-- Files: `src/core/focus-history.ts` (line 962)
-- Impact: File modified on every compress even if content unchanged
-
-## Fragile Areas
-
-**Workflow Store Queue Migration:**
-- Files: `src/service/evolution-worker.ts` (migrateQueueToV2), `src/service/subagent-workflow/workflow-store.ts`
-- Why fragile: Legacy queue format detection via type guards, migration happens on every cycle
-- Safe modification: Add version field, run migrations once at startup not per cycle
-
-**JSON.parse Without Try-Catch on Queue Items:**
-- Files: `src/service/evolution-worker.ts` (line 1148: `JSON.parse(failureEvent.payload_json)`)
-- Why fragile: Payload may be malformed, parse throws and is caught broadly
-- Safe modification: Validate JSON structure before parse
-
-**Nocturnal Trinity Runtime Adapter:**
-- Files: `src/core/nocturnal-trinity.ts` (TrinityRuntimeAdapter)
-- Why fragile: Uses `api.runtime.agent.runEmbeddedPiAgent()` which has specific requirements (provider/model must be explicit)
-- Safe modification: Ensure all trinity calls pass explicit provider/model
-
-## Dependencies at Risk
-
-**better-sqlite3 (^12.9.0):**
-- Risk: Native module requiring platform-specific rebuilds; may break on Node.js major version upgrades
-- Impact: Database operations fail, session/trajectory storage breaks
-- Migration plan: Consider `sql.js` (pure JS) or `node:sqlite` (built-in) for portability
-
-**@sinclair/typebox (^0.34.48):**
-- Risk: Used for runtime schema validation; newer versions may change behavior
-- Impact: Validation mismatches could allow invalid data through
-
-## Test Coverage Gaps
-
-**Untested Service Layer:**
-- What's not tested: `evolution-worker.ts` (2689 lines), `nocturnal-service.ts` (1584 lines)
-- Files: `src/service/evolution-worker.ts`, `src/service/nocturnal-service.ts`
-- Risk: High — service layer contains critical business logic
-- Priority: High
-
-**Untested Workflow Managers:**
-- What's not tested: `empathy-observer-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `correction-observer-workflow-manager.ts`
-- Files: `src/service/subagent-workflow/`
-- Risk: Workflow spawning and result handling is untested
-
-**No Integration Tests for Queue Processing:**
-- What's not tested: Queue enqueue/dequeue cycle, migration path, error recovery
-- Files: `src/service/evolution-worker.ts` (queue operations)
-- Risk: Queue corruption or migration bugs go undetected
-
----
-
-*Concerns audit: 2026-04-15*

package/.planning/codebase/CONVENTIONS.md

@@ -1,148 +0,0 @@
-# Coding Conventions
-
-**Analysis Date:** 2026-04-15
-
-## Naming Patterns
-
-**Files:**
-- PascalCase for modules: `detection-service.ts`, `risk-calculator.ts`
-- kebab-case for utilities with multiple exports: `retry.ts`, `hashing.ts`
-- `.test.ts` suffix for test files co-located in `tests/` directory
-
-**Directories:**
-- Flat structure under `src/`: `commands/`, `core/`, `hooks/`, `service/`, `utils/`
-- Tests mirror source structure in `tests/` parallel directory
-
-**Functions:**
-- camelCase: `normalizePath`, `handleBeforeToolCall`, `computeDynamicTimeout`
-- Verb prefixes for actions: `handle*`, `compute*`, `extract*`, `serialize*`
-- Getter-style for services: `DetectionService.get()`, `WorkspaceContext.fromHookContext()`
-
-**Types & Interfaces:**
-- PascalCase: `DeepReflectionSettings`, `PainSettings`, `GfiGateSettings`
-- Suffix for type variants: `*Types`, `*Contract`, `*Schema`
-- Barrel exports via `index.ts` in each directory
-
-## Code Style
-
-**Formatting:**
-- ESLint with `@typescript-eslint` plugin
-- No Prettier config detected (not enforced)
-- 2-space indentation
-- No trailing semicolons in ESLint config (but not explicitly disabled)
-
-**Key ESLint Rules:**
-```javascript
-'no-empty': 'error',
-'no-console': 'warn',
-'@typescript-eslint/no-explicit-any': 'warn',
-'@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-'@typescript-eslint/no-non-null-assertion': 'warn',
-```
-
-**Linting (test files relaxed):**
-```javascript
-'@typescript-eslint/no-explicit-any': 'off',
-'no-empty': 'warn',
-'no-console': 'off',
-```
-
-**Import Organization:**
-1. Node.js built-ins (`path`, `fs`, `os`)
-2. External packages (`vitest`, `better-sqlite3`)
-3. Internal modules (`../../src/core/...`, `./hooks/...`)
-4. Type-only imports use `import type` syntax
-
-**Path Aliases:**
-- No `paths` aliasing in `tsconfig.json`
-- Relative imports with `.js` extension for ESM compatibility: `from '../../src/utils/io.js'`
-
-## Error Handling
-
-**Patterns:**
-- Return `undefined` for "not found" / "allowed" cases (not exceptions)
-- Throw typed errors from `src/config/errors.ts`
-- Result objects with `allowed: boolean` for gate checks
-- Log warnings via `plugin-logger.ts` for non-critical failures
-
-**Example - Gate pattern:**
-```typescript
-// Return block result, not exceptions
-export function handleBeforeToolCall(event, ctx): BlockResult | undefined {
-  if (someCondition) {
-    return { block: true, blockReason: '...' };
-  }
-  return undefined; // Allowed
-}
-```
-
-**SQLite errors:**
-- Use `better-sqlite3` with synchronous API
-- Wrap in try/catch for migration failures
-
-## Logging
-
-**Framework:** `src/utils/plugin-logger.ts`
-
-**Patterns:**
-- Structured logging with levels: `warn`, `error`, `info`, `debug`
-- Context passed as object: `logger.warn({ context: 'Gate' }, 'message')`
-- No `console.log` in production paths (warn-only via ESLint)
-
-## Comments
-
-**When to Comment:**
-- Complex cross-platform logic (Windows EPERM handling in `atomicWriteFileSync`)
-- Magic numbers explained: `const RENAME_MAX_RETRIES = 3`
-- Task markers in tests: `// Task 4: Default Values Consistency Tests`
-
-**JSDoc:**
-- Used in config files and public APIs
-- Not enforced on internal functions
-
-## Function Design
-
-**Size:**
-- Prefer small, focused functions
-- Complex modules split into helpers (e.g., `rule-host-helpers.ts`)
-
-**Parameters:**
-- Max 3-4 parameters before grouping into options object
-- Destructure for clarity: `function ({ workspaceDir, stateDir })`
-
-**Return Values:**
-- Explicit return types in public APIs
-- `undefined` for "not applicable" vs `null` for "intentionally empty"
-
-## Module Design
-
-**Exports:**
-- Named exports preferred over default exports
-- Barrel `index.ts` files aggregate directory exports
-- Factory functions for singleton services: `DetectionService.get(dir)`
-
-**Service Pattern:**
-```typescript
-// Singleton pattern for stateful services
-class DetectionService {
-  private static instances = new Map<string, DetectionFunnel>();
-  
-  static get(stateDir: string): DetectionFunnel {
-    if (!instances.has(stateDir)) {
-      instances.set(stateDir, new DetectionFunnel(...));
-    }
-    return instances.get(stateDir);
-  }
-  
-  static reset(): void { instances.clear(); }
-}
-```
-
-**Static Analysis:**
-- Vitest used for unit tests
-- ESM modules with `.js` extension in imports
-- `"type": "module"` in `package.json`
-
----
-
-*Convention analysis: 2026-04-15*

package/.planning/codebase/INTEGRATIONS.md

@@ -1,81 +0,0 @@
-# External Integrations
-
-**Analysis Date:** 2026-04-15
-
-## APIs & External Services
-
-**Plugin Framework:**
-- OpenClaw - Host application
-  - SDK/Client: `@openclaw/plugin-kit` (peer dependency, bundled as external)
-  - Communication: Plugin hook events (`before_prompt_build`, `before_tool_call`, `after_tool_call`, `llm_output`, `subagent_spawning`, `subagent_ended`, `before_reset`, `before_compaction`, `after_compaction`)
-  - Registration: Commands, tools, HTTP routes, background services
-
-## Data Storage
-
-**Databases:**
-- SQLite (better-sqlite3 12.9.0)
-  - Connection: File-based at `.state/trajectory.db`
-  - Schema managed via migration runner in `src/core/schema/migrations/`
-  - Migrations: 4 migrations (001-init-trajectory, 002-init-central, 003-init-workflow, 004-add-thinking-and-gfi)
-
-**File Storage:**
-- Local filesystem (workspace-relative paths)
-- Templates copied to workspace on init (`templates/` directory)
-- State persisted to `.state/` directory
-- Pain samples stored in `memory/pain/`
-
-**Caching:**
-- None detected (in-memory caching only)
-
-## Authentication & Identity
-
-**Auth Provider:**
-- OpenClaw native (session-based)
-  - Implementation: Session key extraction via `extractAgentIdFromSessionKey()` in `src/utils/session-key.ts`
-  - Agent identification via `agentId` from OpenClaw context
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- Plugin logger (`src/utils/plugin-logger.ts`)
-- System logger (`src/core/system-logger.ts`)
-- Hook execution recording via `WorkspaceContext.eventLog.recordHookExecution()`
-
-**Logs:**
-- File-based logs: `.state/memory/logs/SYSTEM.log`
-- Console output for errors during build/dev
-
-## CI/CD & Deployment
-
-**Hosting:**
-- OpenClaw plugin ecosystem
-- Published as npm package `principles-disciple`
-
-**CI Pipeline:**
-- Not detected (no GitHub Actions or similar)
-
-## Environment Configuration
-
-**Required env vars:**
-- None required (configuration via OpenClaw plugin config API)
-
-**Secrets location:**
-- OpenClaw plugin configuration (not file-based)
-
-## Webhooks & Callbacks
-
-**Incoming (via OpenClaw hooks):**
-- `before_prompt_build` - Prompt building stage
-- `before_tool_call` - Security gate before tool execution
-- `after_tool_call` - Pain/trust tracking after tool execution
-- `llm_output` - LLM response analysis
-- `subagent_spawning` - Subagent lifecycle
-- `subagent_ended` - Subagent completion
-- `before_reset` / `before_compaction` / `after_compaction` - Workspace lifecycle
-
-**Outgoing:**
-- HTTP routes registered via `api.registerHttpRoute()` in `src/http/principles-console-route.ts`
-
----
-
-*Integration audit: 2026-04-15*

package/.planning/codebase/STACK.md

@@ -1,87 +0,0 @@
-# Technology Stack
-
-**Analysis Date:** 2026-04-15
-
-## Languages
-
-**Primary:**
-- TypeScript 6.0.2 - Core plugin development
-- JSX/TSX - UI components
-
-**Secondary:**
-- JavaScript (ES2022) - Build scripts and configuration
-
-## Runtime
-
-**Environment:**
-- Node.js 20 (build target via esbuild)
-
-**Package Manager:**
-- pnpm 9.x
-- Lockfile: `pnpm-lock.yaml` (present)
-
-## Frameworks
-
-**Core:**
-- OpenClaw Plugin SDK (peer dependency) - Plugin architecture framework
-- React 19.2.0 - UI layer
-- React Router 7.9.4 - UI routing
-
-**Database:**
-- better-sqlite3 12.9.0 - Local SQLite database for trajectory and state persistence
-
-**UI Components:**
-- lucide-react 1.7.0 - Icon library
-
-**Build:**
-- esbuild 0.28.0 - Bundling plugin code
-- TypeScript 6.0.2 - Type checking and compilation
-
-**Testing:**
-- Vitest 4.1.0 - Test runner
-- @vitest/coverage-v8 4.1.0 - Coverage reporting
-- jsdom 29.0.1 - DOM environment for React testing
-- @testing-library/react 16.3.0 - React component testing
-
-**Linting:**
-- ESLint 10.1.0 - Code linting
-- @typescript-eslint packages 8.58.0 - TypeScript ESLint support
-
-## Key Dependencies
-
-**Critical:**
-- `@sinclair/typebox` 0.34.48 - JSON schema type generation
-- `micromatch` 4.0.8 - Glob pattern matching for file paths
-
-**Database:**
-- `@types/better-sqlite3` 7.6.13 - TypeScript types for SQLite
-
-**HTTP/WebSocket:**
-- `ws` 8.18.0 - WebSocket support
-- `@types/ws` 8.5.13 - TypeScript types for WebSocket
-
-## Configuration
-
-**Environment:**
-- Plugin configuration via `openclaw.plugin.json`
-- Workspace-level settings in `.state/pain_settings.json`
-- No `.env` files (configuration is code-driven)
-
-**Build:**
-- `tsconfig.json` - TypeScript configuration (target: ES2022, module: ESNext)
-- `esbuild.config.js` - Bundle configuration
-- `vitest.config.ts` - Test configuration with layered projects (unit/integration)
-
-## Platform Requirements
-
-**Development:**
-- Node.js 20+
-- pnpm 9+
-
-**Production:**
-- OpenClaw >=2026.4.4 (peer dependency)
-- Node.js 20 runtime
-
----
-
-*Stack analysis: 2026-04-15*

package/.planning/codebase/STRUCTURE.md

@@ -1,193 +0,0 @@
-# Codebase Structure
-
-**Analysis Date:** 2026-04-15
-
-## Directory Layout
-
-```
-openclaw-plugin/
-├── src/                    # Main source code
-│   ├── commands/           # Slash command implementations
-│   ├── config/            # Configuration defaults and errors
-│   ├── constants/          # Shared constants
-│   ├── core/               # Core business logic
-│   │   ├── hygiene/        # Hygiene tracking
-│   │   ├── principle-internalization/  # Principle lifecycle
-│   │   └── schema/         # Database schema and migrations
-│   ├── hooks/              # OpenClaw hook handlers
-│   ├── http/               # HTTP route handlers
-│   ├── i18n/               # Internationalization
-│   ├── service/            # Background services
-│   │   └── subagent-workflow/  # Workflow managers
-│   ├── tools/              # Plugin tools
-│   ├── types/              # TypeScript type definitions
-│   └── utils/              # Utility functions
-├── ui/                     # React UI
-│   └── src/
-│       ├── components/     # React components
-│       ├── context/        # React contexts
-│       ├── hooks/          # React hooks
-│       └── pages/          # Page components
-├── tests/                  # Test suite
-│   ├── commands/           # Command tests
-│   ├── core/               # Core module tests
-│   ├── fixtures/           # Test fixtures
-│   ├── hooks/              # Hook tests
-│   ├── integration/        # Integration tests
-│   ├── service/            # Service tests
-│   └── utils/              # Utility tests
-├── templates/               # Workspace templates
-│   ├── langs/              # Language-specific templates
-│   └── workspace/           # Workspace structure templates
-├── dist/                   # Build output
-├── scripts/                # Build scripts
-├── .state/                 # Runtime state (gitignored)
-└── .tmp/                   # Temporary files (gitignored)
-```
-
-## Directory Purposes
-
-**src/commands/:**
-- Purpose: Slash command implementations
-- Contains: 20+ command handlers (strategy, focus, pain, rollback, nocturnal-review, nocturnal-train, etc.)
-- Key files: `strategy.ts`, `focus.ts`, `nocturnal-train.ts`, `nocturnal-rollout.ts`
-
-**src/core/:**
-- Purpose: Core business logic (evolution, trajectory, pain, training, rules)
-- Contains: 70+ core modules including `evolution-engine.ts`, `trajectory.ts`, `nocturnal-trinity.ts`, `pain.ts`, `principle-tree-ledger.ts`
-- Key files: `evolution-engine.ts`, `nocturnal-trinity.ts`, `rule-host.ts`
-
-**src/hooks/:**
-- Purpose: OpenClaw hook handlers for intercepting agent behavior
-- Contains: `prompt.ts`, `gate.ts`, `pain.ts`, `llm.ts`, `lifecycle.ts`, `subagent.ts`, `trajectory-collector.ts`
-- Key files: `gate.ts` (security), `prompt.ts` (context injection)
-
-**src/service/:**
-- Purpose: Background worker services
-- Contains: `evolution-worker.ts` (main worker), `nocturnal-service.ts`, `trajectory-service.ts`, `central-database.ts`
-- Key files: `evolution-worker.ts` (144KB, main async processor)
-
-**src/service/subagent-workflow/:**
-- Purpose: Workflow orchestration for complex subagent operations
-- Contains: `nocturnal-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `empathy-observer-workflow-manager.ts`
-- Key files: `workflow-manager-base.ts`, `dynamic-timeout.ts`
-
-**src/utils/:**
-- Purpose: Shared utility functions
-- Contains: `io.ts` (atomic writes), `plugin-logger.ts`, `retry.ts`, `hashing.ts`, `file-lock.ts`
-- Key files: `io.ts` (critical for safe file operations)
-
-**src/schema/:**
-- Purpose: SQLite database schema and migrations
-- Contains: `schema-definitions.ts`, `migration-runner.ts`, `migrations/*.ts`
-- Migrations: 4 migrations (001-004)
-
-**ui/src/:**
-- Purpose: React-based plugin UI
-- Contains: Pages (Overview, Evolution, Feedback, GateMonitor), components (Shell, ProtectedRoute)
-- Key files: `App.tsx`, `pages/EvolutionPage.tsx`, `pages/FeedbackPage.tsx`
-
-## Key File Locations
-
-**Entry Points:**
-- `src/index.ts`: Plugin entry point, registers all hooks/commands/tools
-
-**Configuration:**
-- `src/core/config.ts`: PainSettings defaults
-- `src/core/paths.ts`: Directory and file path constants (PD_DIRS, PD_FILES)
-- `openclaw.plugin.json`: Plugin manifest
-
-**Core Logic:**
-- `src/core/evolution-engine.ts`: Evolution processing (18KB)
-- `src/core/nocturnal-trinity.ts`: Nocturnal training orchestration (87KB - largest file)
-- `src/core/trajectory.ts`: Trajectory tracking (64KB)
-- `src/core/principle-tree-ledger.ts`: Principle lifecycle management (22KB)
-- `src/core/rule-host.ts`: Sandboxed rule execution (7KB)
-
-**Service Layer:**
-- `src/service/evolution-worker.ts`: Background evolution worker (144KB - largest file)
-- `src/service/nocturnal-service.ts`: Nocturnal training service (59KB)
-- `src/service/nocturnal-runtime.ts`: Runtime for nocturnal operations (24KB)
-
-**Testing:**
-- `tests/`: Test suite with unit and integration layers
-- `vitest.config.ts`: Test configuration with unit/integration project separation
-
-## Naming Conventions
-
-**Files:**
-- TypeScript: `kebab-case.ts` or `camelCase.ts` depending on module type
-- Commands: `kebab-case.ts` (e.g., `nocturnal-review.ts`)
-- Core modules: `camelCase.ts` (e.g., `evolutionEngine.ts`)
-- React components: `PascalCase.tsx`
-
-**Directories:**
-- kebab-case: `subagent-workflow`, `principle-internalization`
-
-**Types:**
-- Interfaces: `PascalCase` (e.g., `PainSettings`, `EvolutionContext`)
-- Type aliases: `PascalCase`
-- Enums: `PascalCase`
-
-## Where to Add New Code
-
-**New Command:**
-- Primary code: `src/commands/<name>.ts`
-- Handler registration: `src/index.ts` in `registerCommandWithAlias()` or `api.registerCommand()`
-- Tests: `tests/commands/<name>.test.ts`
-
-**New Hook Handler:**
-- Implementation: `src/hooks/<name>.ts`
-- Registration: `src/index.ts` in `api.on('<hook_name>', ...)` call
-- Tests: `tests/hooks/<name>.test.ts`
-
-**New Core Service:**
-- Implementation: `src/core/<name>.ts` or `src/service/<name>.ts`
-- Registration: `src/index.ts` in `api.registerService()`
-- Tests: `tests/core/<name>.test.ts` or `tests/service/<name>.test.ts`
-
-**New Workflow Manager:**
-- Implementation: `src/service/subagent-workflow/<name>-workflow-manager.ts`
-- Base class: `src/service/subagent-workflow/workflow-manager-base.ts`
-- Tests: `tests/service/subagent-workflow/<name>.test.ts`
-
-**New Database Migration:**
-- Implementation: `src/core/schema/migrations/<number>-<description>.ts`
-- Registration: `src/core/schema/migrations/index.ts`
-- Tests: Integration test in `tests/core/control-ui-db.test.ts`
-
-**New Utility:**
-- Shared: `src/utils/<name>.ts`
-- Tests: `tests/utils/<name>.test.ts`
-
-## Special Directories
-
-**.state/:**
-- Purpose: Runtime state (per workspace)
-- Generated: Yes (created at runtime)
-- Committed: No (gitignored)
-
-**.tmp/:**
-- Purpose: Temporary files during build/dev
-- Generated: Yes
-- Committed: No (gitignored)
-
-**dist/:**
-- Purpose: Build output
-- Generated: Yes (by `npm run build`)
-- Committed: Yes (in some branches)
-
-**templates/:**
-- Purpose: Workspace template files copied on init
-- Generated: No
-- Committed: Yes
-- Contains: Language-specific templates (en, zh), workspace structure
-
-**node_modules/:**
-- Purpose: Dependencies
-- Generated: Yes (by pnpm install)
-- Committed: No
-
----
-
-*Structure analysis: 2026-04-15*