principles-disciple 1.11.0 → 1.13.0

package/src/core/shadow-observation-registry.ts

@@ -222,10 +222,12 @@ function writeRegistry(stateDir: string, registry: ShadowRegistry): void {
 /**
  * Execute a read-modify-write under an exclusive file lock.
  */
+/* eslint-disable no-unused-vars -- Reason: registry param name in type signature intentionally unused - actual function uses different param name */
 function withShadowRegistryLock<T>(
   stateDir: string,
-  fn: (registry: ShadowRegistry) => T
+  fn: (_registry: ShadowRegistry) => T
 ): T {
+/* eslint-enable no-unused-vars */
   const registryPath = getRegistryPath(stateDir);
   return withLock(registryPath, () => {
     const registry = readRegistry(stateDir);
@@ -339,6 +341,7 @@ export function completeShadowObservation(
  * @param failureSignals - Runtime failure signals
  * @returns The updated ShadowObservation, or null if not found
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: shadow observation completion requires all 4 params - refactoring would break API
 export function completeShadowObservationByTask(
   stateDir: string,
   taskFingerprint: string,
@@ -355,7 +358,7 @@ export function completeShadowObservationByTask(
       return null;
     }
 
-    const observation = pendingObs[0];
+    const [observation] = pendingObs;
     observation.completedAt = new Date().toISOString();
     observation.outcome = outcome;
     observation.failureSignals = failureSignals ?? {
@@ -477,7 +480,7 @@ export function computeShadowStats(
 export function queryShadowObservations(
   stateDir: string,
   checkpointId: string,
-  limit: number = 100
+  limit = 100
 ): ShadowObservation[] {
   return withShadowRegistryLock(stateDir, (registry) => {
     return registry.observations

package/src/core/system-logger.ts

@@ -25,10 +25,10 @@ export const SystemLogger = {
             const logEntry = `[${timestamp}] [${eventType.padEnd(15)}] ${message}\n`;
             
             // Use fire-and-forget async append to prevent blocking
-            fs.appendFile(logFile, logEntry, 'utf8', (err) => {
+            fs.appendFile(logFile, logEntry, 'utf8', (_err) => { // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: fire-and-forget, errors silently dropped
                 // Silently drop errors (e.g. disk full) to not crash the gateway
             });
-        } catch (e) {
+        } catch (e) { // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: intentionally unused - silently fail if we can't setup the log
             // Silently fail if we can't setup the log
         }
     }

package/src/core/thinking-models.ts

@@ -1,7 +1,22 @@
+/**
+ * Thinking Models — Detection Engine
+ *
+ * THINKING_OS.md is the single source of truth for model definitions (id, name, description).
+ * Detection patterns are carefully tuned regexes that match AI output text.
+ *
+ * Flow:
+ *   THINKING_OS.md (authority) → id, name, description, antiPattern
+ *   BUILTIN_PATTERNS (engine) → detection regexes per model id
+ *   THINKING_MODELS (merged) → full definitions with patterns
+ */
+
+import { loadThinkingOsFromWorkspace, generateDetectionPatterns } from './thinking-os-parser.js';
+
 export interface ThinkingModelDefinition {
   id: string;
   name: string;
   description: string;
+  antiPattern?: string;
   patterns: RegExp[];
   baselineScenarios: string[];
 }
@@ -12,146 +27,250 @@ export interface ThinkingModelMatch {
 }
 
 export interface ThinkingScenarioContext {
-  recentToolCalls?: Array<{
+  recentToolCalls?: {
     toolName: string;
     outcome: 'success' | 'failure' | 'blocked';
     errorType?: string | null;
-  }>;
-  recentPainEvents?: Array<{
+  }[];
+  recentPainEvents?: {
     source: string;
     score: number;
-  }>;
-  recentGateBlocks?: Array<{
+  }[];
+  recentGateBlocks?: {
     toolName: string;
     reason: string;
-  }>;
-  recentUserCorrections?: Array<{
+  }[];
+  recentUserCorrections?: {
     correctionCue?: string | null;
-  }>;
-  recentPrincipleEvents?: Array<{
+  }[];
+  recentPrincipleEvents?: {
     eventType: string;
     principleId?: string | null;
-  }>;
+  }[];
+}
+
+// ---------------------------------------------------------------------------
+// Detection patterns — carefully tuned for AI output text matching
+// These must be manually updated when THINKING_OS.md adds new directives.
+// ---------------------------------------------------------------------------
+
+interface BuiltinPatternEntry {
+  id: string;
+  patterns: RegExp[];
+  baselineScenarios: string[];
 }
 
-const THINKING_MODELS: ThinkingModelDefinition[] = [
+const BUILTIN_PATTERNS: BuiltinPatternEntry[] = [
   {
     id: 'T-01',
-    name: 'Survey Before Acting',
-    description: 'Understand the structure first before making changes.',
-    baselineScenarios: ['exploration', 'discovery'],
     patterns: [
       /let me (first )?(understand|map|outline|survey|review the (structure|architecture|dependencies))/i,
       /before (changing|editing|touching) anything/i,
       /让我先(梳理|理解|看看|盘点).*(结构|架构|依赖|全貌)/i,
+      /在执行任何.*/i,
     ],
+    baselineScenarios: ['exploration', 'discovery'],
   },
   {
     id: 'T-02',
-    name: 'Respect Constraints',
-    description: 'Explicitly reason about contracts, tests, schemas, and requirements.',
-    baselineScenarios: ['constraint-check', 'contract-verification'],
     patterns: [
       /(type|test|contract|schema|interface) (constraint|requirement|check|validation)/i,
-      /we (must|need to) (respect|follow|adhere to) the/i,
       /(必须|需要).*(遵守|符合|满足).*(类型|测试|契约|接口|规范)/i,
     ],
+    baselineScenarios: ['constraint-check', 'contract-verification'],
   },
   {
     id: 'T-03',
-    name: 'Evidence Over Assumption',
-    description: 'Use logs, code, and outputs before inferring causes.',
-    baselineScenarios: ['evidence-gathering', 'verification'],
     patterns: [
       /based on (the |this )?(evidence|logs?|output|error|stack trace|test result)/i,
       /let me (check|verify|confirm|read|look at) (the |)(actual|source|code|file|log)/i,
       /根据(日志|证据|输出|报错|堆栈|测试结果)/i,
     ],
+    baselineScenarios: ['evidence-gathering', 'verification'],
   },
   {
     id: 'T-04',
-    name: 'Reversible First',
-    description: 'Prefer changes that are safe to roll back when risk is high.',
-    baselineScenarios: ['risk-management', 'reversibility'],
     patterns: [
       /this (is|would be) (irreversible|destructive|permanent|not easily undone)/i,
       /(reversible|can be undone|safely roll back)/i,
       /(不可逆|破坏性|无法回滚|可以回滚|安全撤销)/i,
     ],
+    baselineScenarios: ['risk-management', 'reversibility'],
   },
   {
     id: 'T-05',
-    name: 'Safety Rails',
-    description: 'Call out guardrails, prohibitions, and failure-prevention constraints.',
-    baselineScenarios: ['guardrails', 'safety-rails'],
     patterns: [
       /we (must|should) (not|never|avoid|prevent|ensure we don't)/i,
       /(critical|important) (not to|that we don't|to avoid)/i,
       /(绝不能|必须避免|不可|禁止|确保不会)/i,
     ],
+    baselineScenarios: ['guardrails', 'safety-rails'],
   },
   {
     id: 'T-06',
-    name: 'Simplicity First',
-    description: 'Prefer the smallest understandable solution over over-engineering.',
-    baselineScenarios: ['simplification', 'pragmatism'],
     patterns: [
       /(simpl(er|est|ify)|minimal|straightforward|lean) (approach|solution|fix|implementation)/i,
       /(simple is better|keep it simple|no need to over)/i,
       /(最简|更简单|精简|没必要过度设计)/i,
     ],
+    baselineScenarios: ['simplification', 'pragmatism'],
   },
   {
     id: 'T-07',
-    name: 'Minimal Change Surface',
-    description: 'Limit the blast radius and touch only what is necessary.',
-    baselineScenarios: ['minimal-diff', 'blast-radius-control'],
     patterns: [
       /(minimal|smallest|narrowest|least) (change|diff|modification|impact)/i,
       /only (change|modify|touch|edit) (the |what)/i,
       /(最小改动|最小变更|只改|只动必要部分)/i,
     ],
+    baselineScenarios: ['minimal-diff', 'blast-radius-control'],
   },
   {
     id: 'T-08',
-    name: 'Pain As Signal',
-    description: 'Treat failures and friction as clues to step back and rethink.',
-    baselineScenarios: ['reflection', 'pain-response'],
     patterns: [
       /this (error|failure|issue) (tells us|indicates|signals|suggests|means)/i,
       /let me (stop|pause|step back|reconsider|rethink)/i,
       /这个(错误|失败|问题).*(说明|意味着|提示)/i,
       /让我(停下|暂停|退一步|重新考虑|重新审视)/i,
     ],
+    baselineScenarios: ['reflection', 'pain-response'],
   },
   {
     id: 'T-09',
-    name: 'Divide And Conquer',
-    description: 'Split the task into smaller phases before execution.',
-    baselineScenarios: ['decomposition', 'phased-execution'],
     patterns: [
       /(break|split|decompose|divide) (this |the task |it )?(into|down)/i,
       /(step 1|first,? (we|i|let's)|phase 1)/i,
       /(拆分|分解|分步|分阶段|第一步)/i,
     ],
+    baselineScenarios: ['decomposition', 'phased-execution'],
+  },
+  {
+    id: 'T-10',
+    patterns: [
+      /let me (write|save|record|note down|document)/i,
+      /memory.*scratchpad|write.*plan\.md|write.*memory|memory.*persist/i,
+      /(让我.*写入|写入.*memory|记录.*scratchpad)/i,
+    ],
+    baselineScenarios: ['memory-persistence', 'state-externalization'],
   },
 ];
 
-export const THINKING_MODEL_MAP = new Map(THINKING_MODELS.map((model) => [model.id, model]));
+const BUILTIN_PATTERN_MAP = new Map(BUILTIN_PATTERNS.map((p) => [p.id, p]));
+
+// Fallback name/description lookup tables (must be defined before listThinkingModels uses them)
+function getFallbackName(id: string): string {
+  const names: Record<string, string> = {
+    'T-01': 'Survey Before Acting',
+    'T-02': 'Respect Constraints',
+    'T-03': 'Evidence Over Assumption',
+    'T-04': 'Reversible First',
+    'T-05': 'Safety Rails',
+    'T-06': 'Simplicity First',
+    'T-07': 'Minimal Change Surface',
+    'T-08': 'Pain As Signal',
+    'T-09': 'Divide And Conquer',
+    'T-10': 'Memory Externalization',
+  };
+  return names[id] ?? id;
+}
+
+function getFallbackDescription(id: string): string {
+  const descs: Record<string, string> = {
+    'T-01': 'Understand the structure first before making changes.',
+    'T-02': 'Trust files, not your context window. Write conclusions to files.',
+    'T-03': 'Use logs, code, and outputs before inferring causes.',
+    'T-04': 'Prefer changes that are safe to roll back when risk is high.',
+    'T-05': 'Call out guardrails, prohibitions, and failure-prevention constraints.',
+    'T-06': 'Prefer the smallest understandable solution over over-engineering.',
+    'T-07': 'Limit the blast radius and touch only what is necessary.',
+    'T-08': 'Treat failures and friction as clues to step back and rethink.',
+    'T-09': 'Split the task into smaller phases before execution.',
+    'T-10': 'Write intermediate conclusions to files for persistence.',
+  };
+  return descs[id] ?? '';
+}
+
+// ---------------------------------------------------------------------------
+// Runtime model definitions — merged from THINKING_OS.md + builtin patterns
+// ---------------------------------------------------------------------------
+
+let _cachedDefinitions: ThinkingModelDefinition[] | null = null;
+let _cachedWorkspace: string | null = null;
+
+/**
+ * Load thinking model definitions dynamically from THINKING_OS.md.
+ * Falls back to built-in definitions if parsing fails.
+ *
+ * @param workspaceDir Optional. If provided, loads from that workspace's THINKING_OS.md.
+ */
+export function listThinkingModels(workspaceDir?: string): ThinkingModelDefinition[] {
+  const cacheKey = workspaceDir ?? '__global__';
+  if (_cachedDefinitions && _cachedWorkspace === cacheKey) {
+    return _cachedDefinitions.slice();
+  }
+
+  const models: ThinkingModelDefinition[] = [];
+
+  if (workspaceDir) {
+    // Try to load from THINKING_OS.md
+    const directives = loadThinkingOsFromWorkspace(workspaceDir);
+    if (directives.length > 0) {
+      for (const dir of directives) {
+        const builtin = BUILTIN_PATTERN_MAP.get(dir.id);
+        const patterns = builtin?.patterns ?? generateDetectionPatterns(dir.trigger);
+        if (patterns.length === 0) {
+          console.warn(`[PD:thinking-models] No detection patterns for ${dir.id}: "${dir.trigger}"`);
+        }
+        models.push({
+          id: dir.id,
+          name: dir.name,
+          description: dir.must,
+          antiPattern: dir.forbidden || undefined,
+          patterns,
+          baselineScenarios: builtin?.baselineScenarios ?? [],
+        });
+      }
+      _cachedDefinitions = models;
+      _cachedWorkspace = cacheKey;
+      return models.slice();
+    }
+  }
+
+  // Fallback: built-in definitions
+  for (const bp of BUILTIN_PATTERNS) {
+    models.push({
+      id: bp.id,
+      name: getFallbackName(bp.id),
+      description: getFallbackDescription(bp.id),
+      patterns: bp.patterns,
+      baselineScenarios: bp.baselineScenarios,
+    });
+  }
+  _cachedDefinitions = models;
+  _cachedWorkspace = cacheKey;
+  return models.slice();
+}
 
-export function listThinkingModels(): ThinkingModelDefinition[] {
-  return THINKING_MODELS.slice();
+/**
+ * Clear the cached model definitions.
+ * Call this when THINKING_OS.md changes.
+ */
+export function clearThinkingModelCache(): void {
+  _cachedDefinitions = null;
+  _cachedWorkspace = null;
 }
 
-export function getThinkingModel(modelId: string): ThinkingModelDefinition | undefined {
-  return THINKING_MODEL_MAP.get(modelId);
+export function getThinkingModel(modelId: string, workspaceDir?: string): ThinkingModelDefinition | undefined {
+  const models = listThinkingModels(workspaceDir);
+  return models.find(m => m.id === modelId);
 }
 
-export function detectThinkingModelMatches(text: string): ThinkingModelMatch[] {
+export function detectThinkingModelMatches(text: string, workspaceDir?: string): ThinkingModelMatch[] {
   if (!text) return [];
 
+  const models = listThinkingModels(workspaceDir);
   const matches: ThinkingModelMatch[] = [];
-  for (const model of THINKING_MODELS) {
+
+  for (const model of models) {
     for (const pattern of model.patterns) {
       if (pattern.test(text)) {
         matches.push({
@@ -165,6 +284,23 @@ export function detectThinkingModelMatches(text: string): ThinkingModelMatch[] {
   return matches;
 }
 
+/**
+ * Get all model definitions for display purposes (no patterns).
+ */
+export function getThinkingModelDefinitions(workspaceDir?: string): {
+  modelId: string;
+  name: string;
+  description: string;
+  antiPattern?: string;
+}[] {
+  return listThinkingModels(workspaceDir).map(m => ({
+    modelId: m.id,
+    name: m.id + ': ' + m.name,
+    description: m.description,
+    antiPattern: m.antiPattern,
+  }));
+}
+
 export function deriveThinkingScenarios(
   modelId: string,
   context: ThinkingScenarioContext,

package/src/core/thinking-os-parser.ts

@@ -0,0 +1,156 @@
+/**
+ * Thinking OS XML Parser
+ *
+ * Parses THINKING_OS.md to extract directive definitions.
+ * THINKING_OS.md is the single source of truth for thinking models.
+ *
+ * Required XML structure:
+ *   <directive id="T-01" name="MAP_BEFORE_TERRITORY">
+ *     <trigger>...</trigger>
+ *     <must>...</must>
+ *     <forbidden>...</forbidden>
+ *   </directive>
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { resolvePdPath } from './paths.js';
+
+export interface ThinkingOsDirective {
+  id: string;         // "T-01"
+  name: string;       // "MAP_BEFORE_TERRITORY"
+  trigger: string;    // <trigger> content — used for detection patterns
+  must: string;       // <must> content — used as description
+  forbidden: string;  // <forbidden> content — used as anti-pattern
+}
+
+/**
+ * Extract a single XML tag's text content from a string.
+ */
+function extractTag(content: string, tagName: string): string {
+  const regex = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`, 'i');
+  const match = content.match(regex);
+  if (!match) return '';
+  return match[1].trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * Parse THINKING_OS.md content and extract all <directive> blocks.
+ * Returns empty array if no XML directives found.
+ */
+export function parseThinkingOsMd(content: string): ThinkingOsDirective[] {
+  const directives: ThinkingOsDirective[] = [];
+  const directiveRegex = /<directive\s+([^>]*)>([\s\S]*?)<\/directive>/gi;
+   
+  let match: RegExpExecArray | null = null;
+
+  while ((match = directiveRegex.exec(content)) !== null) {
+    const attrs = match[1];
+    const body = match[2];
+    const idMatch = attrs.match(/id="([^"]+)"/i);
+    const nameMatch = attrs.match(/name="([^"]+)"/i);
+    if (!idMatch) continue;
+
+    directives.push({
+      id: idMatch[1],
+      name: nameMatch ? nameMatch[1] : '',
+      trigger: extractTag(body, 'trigger'),
+      must: extractTag(body, 'must'),
+      forbidden: extractTag(body, 'forbidden'),
+    });
+  }
+
+  return directives;
+}
+
+/**
+ * Load THINKING_OS.md from the workspace.
+ * Falls back to plugin templates if workspace file doesn't exist or has no XML directives.
+ */
+export function loadThinkingOsFromWorkspace(
+  workspaceDir: string,
+  language = 'zh',
+): ThinkingOsDirective[] {
+  // Priority 1: workspace THINKING_OS.md
+  const workspacePath = resolvePdPath(workspaceDir, 'THINKING_OS');
+  if (fs.existsSync(workspacePath)) {
+    try {
+      const content = fs.readFileSync(workspacePath, 'utf-8');
+      const directives = parseThinkingOsMd(content);
+      if (directives.length > 0) return directives;
+    } catch {
+      // Fall through to template
+    }
+  }
+
+  // Priority 2: plugin template for the given language
+  const templatePath = resolveTemplatePath(language);
+  if (templatePath) {
+    try {
+      const content = fs.readFileSync(templatePath, 'utf-8');
+      const directives = parseThinkingOsMd(content);
+      if (directives.length > 0) return directives;
+    } catch {
+      // Fall through to zh template
+    }
+  }
+
+  // Priority 3: zh template as ultimate fallback
+  const zhPath = resolveTemplatePath('zh');
+  if (zhPath) {
+    try {
+      const content = fs.readFileSync(zhPath, 'utf-8');
+      return parseThinkingOsMd(content);
+    } catch {
+      return [];
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Resolve the THINKING_OS.md template path for a given language.
+ */
+function resolveTemplatePath(language: string): string | null {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  const templatePath = path.join(
+    path.dirname(path.dirname(path.dirname(currentDir))),
+    'templates',
+    'langs',
+    language,
+    'principles',
+    'THINKING_OS.md',
+  );
+  return fs.existsSync(templatePath) ? templatePath : null;
+}
+
+/**
+ * Extract meaningful detection keywords from a trigger string.
+ * Returns an array of regex patterns.
+ */
+export function generateDetectionPatterns(trigger: string): RegExp[] {
+  if (!trigger) return [];
+
+  const patterns: string[] = [];
+
+  // Extract Chinese phrases: 3-8 character sequences
+  const chinesePattern = /[\u4e00-\u9fff]{3,8}/g;
+  const chineseMatches = trigger.match(chinesePattern) ?? [];
+  for (const phrase of chineseMatches) {
+    patterns.push(phrase);
+  }
+
+  // Extract English words/phrases
+  const englishPattern = /[a-zA-Z]{3,20}(?:\s+[a-zA-Z]{3,20}){0,3}/g;
+  const englishMatches = trigger.match(englishPattern) ?? [];
+  for (const phrase of englishMatches) {
+    const cleaned = phrase.trim();
+    if (cleaned.length >= 3) {
+      patterns.push(cleaned);
+    }
+  }
+
+  return patterns.map(p => new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'));
+}

package/src/core/training-program.ts

@@ -30,7 +30,6 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import {
   type TrainingExperimentSpec,
@@ -42,7 +41,6 @@ import {
   type TrainingBudget,
   validateTrainerResult,
   computeConfigFingerprint,
-  computeDatasetFingerprint,
   computeCodeHash,
   generateExperimentId,
   validateHardwareTier,
@@ -279,7 +277,7 @@ export interface ExecuteTrainerParams {
 export async function executeTrainer(
   spec: TrainingExperimentSpec,
   scriptsDir?: string
-): Promise<import('./external-training-contract.js').TrainingExperimentResult> {
+): Promise<TrainingExperimentResult> {
   const baseDir = scriptsDir ?? path.join(REPO_ROOT, TRAINER_SCRIPTS_DIR);
 
   // Map backend to script name
@@ -341,7 +339,7 @@ export async function executeTrainer(
     const MAX_STDOUT_BUFFER = 1 * 1024 * 1024; // 1MB cap
 
     const trainerResult = await new Promise<
-      import('./external-training-contract.js').TrainingExperimentResult
+      TrainingExperimentResult
     >((resolve, reject) => {
       const proc = spawn(pythonExecutable, [scriptPath, '--spec', specPath, '--output-dir', spec.outputDir]);
 
@@ -372,7 +370,7 @@ export async function executeTrainer(
           const trimmed = stdout.trim();
           if (trimmed) {
             try {
-              resolve(JSON.parse(trimmed) as import('./external-training-contract.js').TrainingExperimentResult);
+              resolve(JSON.parse(trimmed) as TrainingExperimentResult);
               return;
             } catch {
               // fall through to result file
@@ -382,7 +380,7 @@ export async function executeTrainer(
           if (fs.existsSync(resultFilePath)) {
             try {
               const content = fs.readFileSync(resultFilePath, 'utf-8');
-              resolve(JSON.parse(content) as import('./external-training-contract.js').TrainingExperimentResult);
+              resolve(JSON.parse(content) as TrainingExperimentResult);
               return;
             } catch {
               // fall through to error
@@ -399,7 +397,7 @@ export async function executeTrainer(
           if (fs.existsSync(resultFilePath)) {
             try {
               const content = fs.readFileSync(resultFilePath, 'utf-8');
-              resolve(JSON.parse(content) as import('./external-training-contract.js').TrainingExperimentResult);
+              resolve(JSON.parse(content) as TrainingExperimentResult);
             } catch {
               reject(new Error(`Trainer exited with code ${code} and result file was invalid: ${resultFilePath}`));
             }
@@ -567,7 +565,9 @@ export function processTrainerResult(
  * ```
  */
 export class TrainingProgram {
+  /* eslint-disable no-unused-vars -- Reason: stateDir is used via this.stateDir in createExperiment method */
   constructor(private readonly stateDir: string) {}
+  /* eslint-enable no-unused-vars */
 
   /**
    * Create a new training experiment.