principles-disciple 1.72.0 → 1.73.0

package/.planning/codebase/TESTING.md

@@ -1,243 +0,0 @@
-# Testing Patterns
-
-**Analysis Date:** 2026-04-15
-
-## Test Framework
-
-**Runner:** Vitest 4.1.0
-- Config: `vitest.config.ts`
-- Environment: `node`
-- Pool: `threads` (required for `better-sqlite3` native handle cleanup)
-
-**Assertion Library:** Vitest built-in (`expect`)
-
-**Coverage:** `@vitest/coverage-v8`
-- Thresholds: lines 70%, functions 70%, branches 60%, statements 70%
-- Excludes: `tests/**`
-
-**Run Commands:**
-```bash
-npm test              # Run unit tests (fast, parallel)
-npm run test:unit     # Alias for above
-npm run test:integration  # Run integration tests only
-npm run test:coverage # Run with coverage report
-npm run test:all      # Run all tests (unit + integration)
-```
-
-## Test File Organization
-
-**Location:**
-- Tests co-located in `tests/` directory, mirroring `src/` structure
-- `tests/core/`, `tests/commands/`, `tests/hooks/`, `tests/service/`, `tests/utils/`
-- Integration tests in `tests/integration/`
-
-**Naming:**
-- `*.test.ts` suffix for all test files
-- Example: `tests/core/detection-service.test.ts`
-
-**Structure:**
-```
-tests/
-├── commands/     # Command handlers
-├── core/         # Core services and logic
-├── fixtures/     # Shared fixtures
-├── hooks/        # Hook handlers
-├── integration/  # End-to-end tests
-├── scripts/      # Script tests
-└── service/      # Service layer
-```
-
-## Test Structure
-
-**Suite Organization:**
-```typescript
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-describe('DetectionService', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-        // Reset state between tests
-        DetectionService.reset();
-    });
-
-    it('should create a new instance on first get', () => {
-        // Test implementation
-    });
-});
-```
-
-**Patterns:**
-- `beforeEach` for setup, `afterEach` for teardown
-- `vi.clearAllMocks()` between tests (not `vi.resetAllMocks()`)
-- `vi.useFakeTimers()` / `vi.useRealTimers()` for time-sensitive tests
-
-## Mocking
-
-**Framework:** Vitest's `vi.fn()` and `vi.mock()`
-
-**Module Mocking:**
-```typescript
-vi.mock('../../src/core/dictionary-service.js');
-vi.mock('../../src/core/detection-funnel.js');
-
-// Then configure mock implementations
-vi.mocked(DictionaryService.get).mockReturnValue(mockDict as any);
-```
-
-**Built-in Module Mocking:**
-```typescript
-vi.mock('fs');
-vi.mocked(fs.existsSync).mockReturnValue(true);
-vi.mocked(fs.readFileSync).mockImplementation((p) => {
-    if (p.toString() === configPath) return JSON.stringify(mockConfig);
-    return '';
-});
-```
-
-**Mock Reset:**
-- `vi.clearAllMocks()` clears call history but keeps implementations
-- `vi.resetAllMocks()` clears both (use with caution)
-- Reset singleton state: `DetectionService.reset()`, `WorkspaceContext.clearCache()`
-
-**Partial Mocks:**
-```typescript
-vi.mocked(fs.existsSync).mockImplementation((p) => p.toString() === configPath);
-```
-
-## Fixtures and Factories
-
-**Temp Directory Pattern (integration tests):**
-```typescript
-const tempDirs: string[] = [];
-
-function makeWorkspace(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-runtime-summary-'));
-  tempDirs.push(dir);
-  fs.mkdirSync(path.join(dir, '.state', 'sessions'), { recursive: true });
-  return dir;
-}
-
-afterEach(() => {
-  for (const dir of tempDirs.splice(0)) {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-```
-
-**JSON Fixture Writing:**
-```typescript
-function writeJson(filePath: string, value: unknown): void {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), 'utf8');
-}
-```
-
-**Session File Helper:**
-```typescript
-function writeSession(workspace: string, sessionId: string, payload: Record<string, unknown>): void {
-  writeJson(path.join(workspace, '.state', 'sessions', `${sessionId}.json`), {
-    sessionId,
-    ...payload,
-  });
-}
-```
-
-## Integration Tests
-
-**Requirements:**
-- Real SQLite database via `better-sqlite3`
-- Thread pool required (not `vm` pool) due to native handle cleanup issues
-- Explicit file list in `vitest.config.ts` integration array
-
-**Integration Test Files:**
-```typescript
-const integrationTests = [
-  'tests/core/control-ui-db.test.ts',
-  'tests/core/evolution-logger.test.ts',
-  'tests/core/nocturnal-e2e.test.ts',
-  // ...
-];
-```
-
-## Common Patterns
-
-**Async Testing with Fake Timers:**
-```typescript
-beforeEach(() => {
-  vi.useFakeTimers();
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-it('should retry on retryable error', async () => {
-  const fn = vi.fn()
-    .mockRejectedValueOnce(new Error('ETIMEDOUT'))
-    .mockResolvedValue('success');
-
-  const resultPromise = retryAsync(fn, { initialDelayMs: 100 });
-  await vi.advanceTimersByTimeAsync(100);
-  const result = await resultPromise;
-  expect(result).toBe('success');
-});
-```
-
-**Error Testing:**
-```typescript
-it('should throw after max retries exceeded', async () => {
-  vi.useRealTimers();
-  const fn = vi.fn().mockRejectedValue(new Error('ETIMEDOUT'));
-
-  await expect(retryAsync(fn, { maxRetries: 1, initialDelayMs: 1, logger: { warn: vi.fn() } }))
-    .rejects.toThrow('ETIMEDOUT');
-});
-```
-
-**Singleton Reset Pattern:**
-```typescript
-// Many services use singleton pattern requiring reset between tests
-DetectionService.reset();
-WorkspaceContext.clearCache();
-clearSession('live-session');
-```
-
-## Test Naming and Documentation
-
-**Descriptive Test Names:**
-```typescript
-it('should block risk path writes at Seed tier (EP system)', () => { ... });
-it('should return default values if file does not exist', () => { ... });
-```
-
-**Test Comments for Context:**
-```typescript
-// Task 4: Default Values Consistency Tests
-describe('Gate Default Values Consistency', () => {
-  /**
-   * PURPOSE: Prove that gate.ts inline defaults match PROFILE_DEFAULTS.
-   * If gate.ts has inline defaults that differ from normalizeProfile(),
-   * this is a bug - the defaults should come from a single source of truth.
-   */
-});
-```
-
-## Test Isolation
-
-**Environment Variable Injection:**
-```typescript
-// Set env before module load
-process.env.PD_TEST_AGENTS_DIR = TEST_AGENTS_DIR;
-```
-
-**Path Traversal Protection Tests:**
-```typescript
-it('rejects path traversal session IDs', async () => {
-  const result = await extractRecentConversation('../../etc/passwd', 'main');
-  expect(result).toBe('');
-});
-```
-
----
-
-*Testing analysis: 2026-04-15*

package/.planning/phases/01-basic-visualization/01-GAP-CLOSURE-VERIFICATION.md

@@ -1,113 +0,0 @@
----
-phase: "01-basic-visualization"
-plan: "01-GAP-CLOSURE"
-verified: 2026-04-17T15:30:00Z
-status: passed
-score: "4/4 must-haves verified"
-overrides_applied: 0
-re_verification: false
-gaps: []
-deferred: []
-human_verification: []
-requirement_mismatch:
-  note: "Requirement IDs provided (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization) - a different domain. Requirement coverage cannot be established for IDs that do not belong to this phase."
----
-
-# Phase 01-basic-visualization: GAP-CLOSURE Verification Report
-
-**Phase Goal:** Close verification gaps from Phase 01 by implementing missing i18n fixes for LineChart component and coverage trend empty state.
-**Verified:** 2026-04-17T15:30:00Z
-**Status:** passed
-**Re-verification:** No — initial verification
-
-## Goal Achievement
-
-### Observable Truths
-
-| #   | Truth | Status | Evidence |
-| --- | ----- | ------ | -------- |
-| 1   | LineChart interface has emptyText prop for i18n | VERIFIED | `emptyText?: string;` at line 864 in charts.tsx |
-| 2   | LineChart renders emptyText prop instead of hardcoded '暂无数据' | VERIFIED | Conditional render at lines 878-885: `if (!emptyText) return null;` then `{emptyText}` |
-| 3   | Coverage trend section shows EmptyState when no data | VERIFIED | Ternary at line 259: `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
-| 4   | All LineChart usages pass emptyText prop | VERIFIED | Lines 272, 454, 521 all have `emptyText={t('common.noData')}` |
-
-**Score:** 4/4 truths verified
-
-### Deferred Items
-
-None
-
-### Required Artifacts
-
-| Artifact | Expected | Status | Details |
-| -------- | -------- | ------ | ------- |
-| `charts.tsx:864` | `emptyText?: string` in LineChartProps | VERIFIED | Prop exists at correct line |
-| `charts.tsx:876` | Default value `emptyText = ''` | VERIFIED | Default empty string assigned |
-| `charts.tsx:878-885` | Conditional render using emptyText | VERIFIED | Returns null if no emptyText, renders div with {emptyText} otherwise |
-| `ThinkingModelsPage.tsx:259` | Ternary operator for coverage trend | VERIFIED | `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
-| `ThinkingModelsPage.tsx:272` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
-| `ThinkingModelsPage.tsx:454` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
-| `ThinkingModelsPage.tsx:521` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
-
-### Key Link Verification
-
-| From | To | Via | Status | Details |
-| ---- | --- | --- | ------ | ------- |
-| LineChart | i18n system | emptyText prop | WIRED | emptyText prop accepts i18n string and renders it |
-| Coverage trend | EmptyState | ternary operator | WIRED | Ternary correctly switches between LineChart and EmptyState |
-| ThinkingModelsPage | common.noData | t() function | WIRED | All LineChart usages pass i18n key |
-| EmptyState | i18n keys | t() function | WIRED | `t('thinkingModels.emptyCoverageTrend')` and `t('thinkingModels.emptyCoverageTrendDesc')` used |
-
-### Data-Flow Trace (Level 4)
-
-| Artifact | Data Variable | Source | Produces Real Data | Status |
-| -------- | ------------- | ------ | ------------------ | ------ |
-| LineChart emptyText | emptyText prop | Parent component via t('common.noData') | N/A | STATIC — i18n key is static, not dynamic |
-
-### Behavioral Spot-Checks
-
-| Behavior | Command | Result | Status |
-| -------- | ------- | ------ | ------ |
-| emptyText in interface | `grep -n "emptyText?: string" charts.tsx` | `864:  emptyText?: string;` | PASS |
-| No hardcoded Chinese | `grep -n "暂无数据" charts.tsx` | No matches | PASS |
-| Ternary for coverage | `grep -n "coverageTrend.length.*?" ThinkingModelsPage.tsx` | `259: {data.coverageTrend.length >= 1 ?` | PASS |
-| EmptyState for coverage | `grep -n "EmptyState" ThinkingModelsPage.tsx \| head -3` | Lines 276-279 with i18n keys | PASS |
-| All LineChart have emptyText | `grep -B5 -A10 "<LineChart" ThinkingModelsPage.tsx \| grep -c "emptyText"` | 3 | PASS |
-
-### Requirements Coverage
-
-**IMPORTANT - Requirement Mismatch Found:**
-
-| Requirement | Source | Description | Status | Evidence |
-| ----------- | ------ | ----------- | ------ | -------- |
-| SDK-CORE-03 | User-provided | Implement universal PainSignal interface logic | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-ADP-07 | User-provided | Implement Coding domain adapter | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-ADP-08 | User-provided | Implement second domain adapter | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-TEST-02 | User-provided | Implement full Adapter conformance test suite | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-TEST-03 | User-provided | Execute and publish performance benchmarks | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-MGMT-01 | User-provided | Package SDK as @principles/core npm package | N/A | Does not belong to 01-basic-visualization phase |
-| SDK-MGMT-02 | User-provided | Establish Semver versioning and migration guides | N/A | Does not belong to 01-basic-visualization phase |
-| VIZ-04 | GAP-CLOSURE-PLAN | Empty state optimization | VERIFIED | All 4 must_haves from GAP-CLOSURE-PLAN verified |
-
-**The 7 requirement IDs provided are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. They do not map to the 01-basic-visualization phase. The phase's actual scope is VIZ-04 (Empty state optimization), which has been verified through must_haves.**
-
-### Anti-Patterns Found
-
-| File | Line | Pattern | Severity | Impact |
-| ---- | ---- | ------- | -------- | ------ |
-| None | - | No anti-patterns detected | - | - |
-
-### Human Verification Required
-
-None required — all truths verifiable via static analysis.
-
-### Gaps Summary
-
-**None.** All 4 must_haves verified. Phase goal achieved.
-
-**Notable finding:** The requirement IDs provided by user (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization for visualization) - a different scope. Requirement coverage cannot be established for IDs that do not belong to this phase.
-
----
-
-_Verified: 2026-04-17T15:30:00Z_
-_Verifier: Claude (gsd-verifier)_

package/docs/COMMAND_REFERENCE.md

@@ -1,76 +0,0 @@
-# Principles Disciple Command Reference
-
-> 当前版本重点：EP (Evolution Points) 系统已接替 trust score 成为唯一门控机制。  
-> `rollback` 只回滚 `user_empathy` slice，`/pd-evolution-status` 读的是运行时 summary。
-
----
-
-## 核心命令
-
-| 命令 | 用途 | 当前口径 |
-|---|---|---|
-| `/pd-evolution-status` | 查看控制面与进化面的当前状态 | 读取 `RuntimeSummaryService` 的 canonical state |
-| `/pd-status empathy` | 查看情绪/共情事件统计 | 用于观察 `user_empathy` 与 `system_infer` 事件是否稳定落日志 |
-| `/pd-rollback last` | 回滚最近一次情绪惩罚 | 只回滚 `user_empathy` 对应的 GFI slice |
-| `/pd-evolve` | 执行进化任务 | 属于学习面，通过 EP 积累提升权限 |
-| `/pd-help` | 显示帮助 | |
-
----
-
-## `/pd-evolution-status`
-
-### 它现在显示什么
-
-- `EP Tier`: 当前 EP 等级 (Seed → Sprout → Sapling → Tree → Forest)
-- `Session GFI`: 当前会话 GFI 与峰值
-- `GFI Sources`: 当前 summary 能解释出来的 friction 来源
-- `Pain Flag`: pain flag 是否激活
-- `Gate Events`: 最近的 block / bypass
-- `Queue / Directive`: evolution queue 与 directive 的当前状态
-
-### 重要说明
-
-- 这是当前控制面的权威读模型入口。
-- 它优先读取 canonical `.state`，并尽量合并 live session / buffered events。
-- 如果数据不完整，会显示 `partial` 或 warning，而不是静默显示 `0`。
-
----
-
-## `/pd-rollback`
-
-### 当前行为
-
-- `/pd-rollback last`
-- `/pd-rollback <event-id>`
-
-回滚的是最近一次或指定的 `user_empathy` 事件。
-
-### 重要变化
-
-- 现在只回滚 `user_empathy` 对应的 GFI slice
-- 不再把整段 session GFI 一起清空
-- 如果事件不存在或来源不匹配，不会误伤其他 friction
-
----
-
-## EP 等级说明
-
-| 等级 | EP 要求 | 权限 |
-|---|---|---|
-| Seed | 0 | 只读 + 基础文档 |
-| Sprout | 50 | 单文件编辑 |
-| Sapling | 200 | 多文件 + 测试 + 子智能体 |
-| Tree | 500 | 重构 + 风险路径 |
-| Forest | 1000 | 无限制 |
-
----
-
-## 观察窗口建议
-
-在进入 `Phase 3 capability shadow` 之前，优先每天检查：
-
-1. `user_empathy` / `system_infer` 是否稳定进入 `events.jsonl`
-2. rollback 是否只影响 empathy slice
-3. `evolution_queue.json`、`evolution_directive.json` 与 status 是否一致
-4. summary 是否仍然需要 `partial` 警告才能解释当前状态
-5. EP 积累是否正常驱动等级提升

package/docs/COMMAND_REFERENCE_EN.md

@@ -1,79 +0,0 @@
-# Principles Disciple Command Reference (English)
-
-> Current state: EP (Evolution Points) system is the primary growth system, fully operational and enabled by default.
-
----
-
-## Core Commands
-
-| Command | Purpose |
-|---|---|
-| `/pd-evolution-status` | View EP tier, GFI, pain flag, and gate events |
-| `/pd-status empathy` | Inspect empathy/frustration event statistics |
-| `/pd-rollback last` | Roll back the latest empathy penalty |
-| `/pd-evolve` | Run an evolution task |
-| `/pd-evolution-points` | View current EP balance and tier |
-
----
-
-## `/pd-evolution-status`
-
-### What it shows
-
-- `EP Tier`: Current evolution tier (Seed → Sprout → Sapling → Tree → Forest)
-- `Session GFI`: Current session GFI and peak
-- `GFI Sources`: Currently attributable friction sources
-- `Pain Flag`: Whether a pain flag is active
-- `Gate Events`: Recent block / bypass counts
-- `Queue / Directive`: Evolution queue and directive state
-
-### Important notes
-
-- This is the main operator entry point into the control plane.
-- It reads canonical `.state` and tries to merge live session state and buffered events when available.
-- When data is incomplete, it surfaces `partial` or warnings instead of silently printing `0`.
-
----
-
-## `/pd-rollback`
-
-### Current behavior
-
-- `/pd-rollback last`
-- `/pd-rollback <event-id>`
-
-It rolls back the latest or specified `user_empathy` event.
-
-### Important notes
-
-- It subtracts only the `user_empathy` GFI slice
-- It no longer wipes the whole session GFI
-- If the event is missing or the source does not match, unrelated friction remains untouched
-
----
-
-## EP Tier System
-
-| Tier | EP Required | Max Lines/Write |
-|------|-------------|-----------------|
-| Seed | 0 | 150 |
-| Sprout | 50 | 300 |
-| Sapling | 200 | 500 |
-| Tree | 500 | 1000 |
-| Forest | 1000 | Unlimited |
-
-EP is earned through successful task completion and problem resolution.
-
----
-
-## Observation Window Checklist
-
-Before entering new capability phases, check daily:
-
-1. EP tier and queue are functioning correctly
-2. `user_empathy` and `system_infer` appear in `events.jsonl`
-3. rollback affects only the empathy slice
-4. `evolution_queue.json`, `evolution_directive.json`, and status stay aligned
-5. summary warnings still accurately explain partial data quality
-
-(End of file - total 84 lines)

package/scripts/build-web.mjs

@@ -1,46 +0,0 @@
-import { build } from "esbuild";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
-
-const isProduction = process.argv.includes("--production");
-const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const outDir = path.join(rootDir, "dist", "web");
-const assetsDir = path.join(outDir, "assets");
-
-mkdirSync(assetsDir, { recursive: true });
-
-await build({
-  entryPoints: [path.join(rootDir, "ui", "src", "main.tsx")],
-  bundle: true,
-  format: "esm",
-  platform: "browser",
-  target: ["es2022"],
-  outfile: path.join(assetsDir, "app.js"),
-  sourcemap: isProduction ? false : "inline",
-  minify: isProduction,
-  jsx: "automatic",
-  loader: {
-    ".css": "css",
-  },
-  define: {
-    "process.env.NODE_ENV": JSON.stringify(isProduction ? "production" : "development"),
-  },
-});
-
-const html = `<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Principles Console</title>
-    <link rel="stylesheet" href="/plugins/principles/assets/app.css" />
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/plugins/principles/assets/app.js"></script>
-  </body>
-</html>
-`;
-
-writeFileSync(path.join(outDir, "index.html"), html, "utf8");