principles-disciple 1.16.0 → 1.18.0

package/src/core/evolution-types.ts

@@ -12,15 +12,15 @@
 
  
 export enum EvolutionTier {
-  // eslint-disable-next-line no-unused-vars -- Reason: enum members are used via EvolutionTier.Seed syntax - bare names unused but required for enum structure
+   
   Seed = 1,      // 起步：150行 + 3文件 + 子智能体（现代 AI 能力已足够强）
-  // eslint-disable-next-line no-unused-vars -- Reason: enum members are used via EvolutionTier.Sprout syntax - bare names unused but required for enum structure
+   
   Sprout = 2,    // 成长：300行 + 5文件
-  // eslint-disable-next-line no-unused-vars -- Reason: enum members are used via EvolutionTier.Sapling syntax - bare names unused but required for enum structure
+   
   Sapling = 3,   // 独当：500行 + 10文件 + 风险路径
-  // eslint-disable-next-line no-unused-vars -- Reason: enum members are used via EvolutionTier.Tree syntax - bare names unused but required for enum structure
+   
   Tree = 4,      // 专家：1000行 + 20文件
-  // eslint-disable-next-line no-unused-vars -- Reason: enum members are used via EvolutionTier.Forest syntax - bare names unused but required for enum structure
+   
   Forest = 5     // 大师：完全自主
 }
 

package/src/core/external-training-contract.ts

@@ -403,7 +403,7 @@ export function computeConfigFingerprint(config: Partial<TrainingHyperparameters
  * If the file cannot be read, falls back to path+count hash (legacy behavior).
  */
 export function computeDatasetFingerprint(exportPath: string, sampleCount: number): string {
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch has fallback return
+   
   let contentHash: string;
   try {
     const content = fs.readFileSync(exportPath, 'utf-8');

package/src/core/focus-history.ts

@@ -428,7 +428,7 @@ export function extractWorkingMemory(
             toolUse.name === 'write_file' || toolUse.name === 'create_file' ? 'created' : 'modified';
           
           // 尝试从文本中提取描述
-          // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+           
           const description = extractDescription(text, filePath);
           
           snapshot.artifacts.push({
@@ -443,20 +443,20 @@ export function extractWorkingMemory(
     if (!text) continue;
 
     // 从文本中提取文件操作（备用方式）
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+     
     extractFileArtifacts(text, snapshot.artifacts, workspaceDir);
 
     // 提取问题
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+     
     extractProblems(text, snapshot.activeProblems);
 
     // 提取下一步
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+     
     extractNextActions(text, snapshot.nextActions);
   }
 
   // 去重和限制数量
-  // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+   
   snapshot.artifacts = deduplicateArtifacts(snapshot.artifacts).slice(-MAX_ARTIFACTS);
   snapshot.activeProblems = snapshot.activeProblems.slice(-MAX_PROBLEMS);
   snapshot.nextActions = snapshot.nextActions.slice(-MAX_NEXT_ACTIONS);
@@ -476,7 +476,7 @@ function extractFileArtifacts(
   // 格式: file_path: "/path/to/file" 或 absolute_path: "/path/to/file"
   const filePathRegex = /(?:file_path|absolute_path)["']?\s*[:=]\s*["']([^"']+\.(ts|js|json|md|yaml|yml|py|sh|mjs|cjs))["']/gi;
 
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in while loop condition before use
+   
   let match;
   while ((match = filePathRegex.exec(text)) !== null) {
     const [, filePath] = match;
@@ -506,7 +506,7 @@ function extractFileArtifacts(
     }
 
     // 尝试提取描述（从附近的文本）
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+     
     const description = extractDescription(text, filePath);
 
     artifacts.push({
@@ -539,7 +539,7 @@ function extractFileArtifacts(
       continue;
     }
 
-    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+     
     const description = extractDescription(text, filePath);
 
     artifacts.push({
@@ -587,7 +587,7 @@ function extractProblems(
 ): void {
   // 问题模式（匹配问题描述）
   const problemPattern = /(?:问题|problem|error|错误|失败|failed)[:：]\s*([^\n]{5,100})/gi;
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in while loop condition before use
+   
   let match;
   while ((match = problemPattern.exec(text)) !== null) {
     const content = match[1].trim();
@@ -630,7 +630,7 @@ function extractNextActions(text: string, actions: string[]): void {
   ];
 
   for (const pattern of patterns) {
-    // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in while loop condition before use
+     
     let match;
     while ((match = pattern.exec(text)) !== null) {
       const action = match[1].trim();
@@ -689,7 +689,7 @@ export function parseWorkingMemorySection(content: string): WorkingMemorySnapsho
   // 解析文件记录表格
   // | 文件路径 | 操作 | 描述 |
   const tableRegex = /\|\s*`?([^`|\n]+)`?\s*\|\s*(created|modified|deleted)\s*\|\s*([^|\n]*)\s*\|/gi;
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in while loop condition before use
+   
   let match;
   while ((match = tableRegex.exec(wmContent)) !== null) {
     snapshot.artifacts.push({
@@ -728,7 +728,7 @@ export function mergeWorkingMemory(content: string, snapshot: WorkingMemorySnaps
   const wmIndex = content.indexOf(WORKING_MEMORY_SECTION);
 
   // 生成 Working Memory 章节
-  // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
+   
   const wmSection = generateWorkingMemorySection(snapshot);
   
   if (wmIndex === -1) {
@@ -1405,9 +1405,9 @@ export function recoverFromTemplate(
 export function safeReadCurrentFocus(
   focusPath: string,
   extensionRoot: string,
-  /* eslint-disable no-unused-vars -- Reason: type-only callback parameter names in function type */
+   
   logger?: { warn?: (msg: string) => void; info?: (msg: string) => void }
-  /* eslint-enable no-unused-vars */
+   
 ): {
   content: string;
   recovered: boolean;

package/src/core/hygiene/tracker.ts

@@ -46,7 +46,7 @@ export class HygieneTracker {
           const backupPath = `${this.statsFile}.bak`;
           fs.renameSync(this.statsFile, backupPath);
           this.logger?.warn(`[PD] Corrupted hygiene stats backed up to ${backupPath}`);
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: catch parameter intentionally unused - error handling only
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reason: catch parameter intentionally unused - error handling only
         } catch (_renameErr) {
           // Empty - corrupted stats backup is non-fatal
         }

package/src/core/init.ts

@@ -43,7 +43,7 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
         const commonTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'workspace');
         if (fs.existsSync(commonTemplatesDir)) {
             api.logger.info(`[PD] Syncing workspace templates: ${workspaceDir}...`);
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: copyRecursiveSync is defined later in this file, called here for organizational reasons
+             
             copyRecursiveSync(commonTemplatesDir, workspaceDir, api);
         }
 
@@ -85,7 +85,7 @@ export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: s
             if (!fs.existsSync(painDestDir)) {
                 fs.mkdirSync(painDestDir, { recursive: true });
             }
-            // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: copyRecursiveSync is defined later in this file, called here for organizational reasons
+             
             copyRecursiveSync(painTemplatesDir, painDestDir, api);
         }
 

package/src/core/model-deployment-registry.ts

@@ -249,7 +249,7 @@ function writeRegistry(stateDir: string, registry: ModelDeploymentRegistry): voi
 /**
  * Execute a read-modify-write under an exclusive file lock.
  */
-/* eslint-disable no-unused-vars -- Reason: _registry is a type signature parameter */
+ 
 function withDeploymentRegistryLock<T>(
   stateDir: string,
   fn: (_registry: ModelDeploymentRegistry) => T
@@ -349,7 +349,7 @@ export function assertPromotionGatePassed(stateDir: string, checkpointId: string
  * @throws Error if checkpoint is not found or not deployable
  * @throws Error if checkpoint's targetModelFamily violates profile constraints
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: checkpoint binding requires state + profile + checkpoint - refactoring would break API
+ 
 export function bindCheckpointToWorkerProfile(
   stateDir: string,
   workerProfile: WorkerProfile,

package/src/core/model-training-registry.ts

@@ -249,7 +249,7 @@ function writeRegistry(stateDir: string, registry: ModelTrainingRegistry): void
  */
 function withRegistryLock<T>(
   stateDir: string,
-  // eslint-disable-next-line no-unused-vars -- parameter type annotation requires name
+   
   fn: (_: ModelTrainingRegistry) => T
 ): T {
   const registryPath = getRegistryPath(stateDir);
@@ -321,7 +321,7 @@ export function registerTrainingRun(
  *
  * @throws Error if run not found or transition is invalid
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: status update requires state + runId + status - refactoring would break API
+ 
 export function updateTrainingRunStatus(
   stateDir: string,
   trainRunId: string,

package/src/core/nocturnal-arbiter.ts

@@ -689,7 +689,7 @@ export function parseAndValidateArtifact(
   options: ArbiterOptions = {}
 ): ArbiterResult {
   // Step 1: Parse JSON
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned in try block immediately after declaration
+   
   let parsed: unknown;
   try {
     parsed = JSON.parse(jsonString);

package/src/core/nocturnal-artificer.ts

@@ -220,8 +220,8 @@ export function shouldRunArtificer(
 
   const signalCount =
     snapshot.stats.totalPainEvents +
-    snapshot.stats.totalGateBlocks +
-    snapshot.stats.failureCount;
+    (snapshot.stats.totalGateBlocks ?? 0) +
+    (snapshot.stats.failureCount ?? 0);
 
   return signalCount >= minimumSignalCount;
 }

package/src/core/nocturnal-candidate-scoring.ts

@@ -241,7 +241,7 @@ export function checkThresholds(
  * @param weights - Scoring weights
  * @returns All scored and ranked candidates
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: candidate ranking requires candidates + judgments + thresholds + weights - refactoring would break API
+ 
 export function rankCandidates(
   candidates: DreamerCandidate[],
   judgments: PhilosopherJudgment[],
@@ -328,7 +328,7 @@ export function rankCandidates(
  * @param weights - Scoring weights
  * @returns Tournament result with winner
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: tournament requires candidates + judgments + thresholds + weights - refactoring would break API
+ 
 export function runTournament(
   candidates: DreamerCandidate[],
   judgments: PhilosopherJudgment[],

package/src/core/nocturnal-compliance.ts

@@ -239,7 +239,7 @@ export function detectOpportunity(principleId: string, session: SessionEvents):
   }
 
   // T-xx principles — specific deterministic detection
-  /* eslint-disable @typescript-eslint/no-use-before-define -- Reason: Mutual recursion between helper functions - reordering would break logical grouping */
+   
   switch (principleId) {
     case 'T-01':
       return detectT01Opportunity(session);
@@ -537,7 +537,7 @@ export function detectViolation(principleId: string, session: SessionEvents): Vi
   }
 
   // T-xx principles — specific deterministic detection
-  /* eslint-disable @typescript-eslint/no-use-before-define -- Reason: Mutual recursion between helper functions - reordering would break logical grouping */
+   
   switch (principleId) {
     case 'T-01':
       return detectT01Violation(session);
@@ -558,6 +558,7 @@ export function detectViolation(principleId: string, session: SessionEvents): Vi
     case 'T-09':
       return detectT09Violation(session);
     default:
+      console.warn(`[PD:Compliance] Unknown principle ID: ${principleId} — treating as no violation. Check for typos (P-001 vs P_001).`);
       return { violated: false, reason: `Unknown principle: ${principleId}` };
   }
 }
@@ -986,7 +987,7 @@ function computeViolationTrend(
 /**
  * Builds a human-readable explanation for the compliance result.
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: explanation builder requires all context parameters - refactoring would break API
+ 
 function buildExplanation(
   principleId: string,
   applicableOpportunityCount: number,

package/src/core/nocturnal-dataset.ts

@@ -259,7 +259,7 @@ function writeRegistry(workspaceDir: string, records: NocturnalDatasetRecord[]):
  * Execute a read-modify-write on the registry under an exclusive lock.
  * This prevents concurrent writers from racing on the same file.
  */
-/* eslint-disable no-unused-vars -- Reason: _records is a type signature parameter, unused by design in function type definition */
+ 
 function withRegistryLock<T>(workspaceDir: string, fn: (_records: NocturnalDatasetRecord[]) => T): T {
   const registryPath = getRegistryPath(workspaceDir);
   return withLock(registryPath, () => {
@@ -283,7 +283,7 @@ function withRegistryLock<T>(workspaceDir: string, fn: (_records: NocturnalDatas
  * @param classification - Optional replay classification
  * @returns RegisterSampleResult
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: sample registration requires workspace + artifact + path + family - refactoring would break API
+ 
 export function registerSample(
   workspaceDir: string,
   artifact: NocturnalArtifact,
@@ -425,7 +425,7 @@ const VALID_TRANSITIONS: Record<NocturnalReviewStatus, NocturnalReviewStatus[]>
  * @returns Updated record, or null if not found
  * @throws Error if transition is invalid
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: status update requires workspace + fingerprint + status - refactoring would break API
+ 
 export function updateReviewStatus(
   workspaceDir: string,
   sampleFingerprint: string,

package/src/core/nocturnal-export.ts

@@ -136,7 +136,7 @@ function computeDatasetFingerprint(sampleFingerprints: string[]): string {
  * Serialize a single dataset record + artifact to ORPO JSONL line.
  * Caller guarantees record.targetModelFamily is non-null.
  */
-// eslint-disable-next-line @typescript-eslint/max-params -- Reason: serialization requires record + artifact + export info - refactoring would break internal API
+ 
 function serializeORPOSample(
   record: NocturnalDatasetRecord,
   artifact: ReturnType<typeof readDatasetArtifact>,
@@ -183,7 +183,7 @@ function serializeORPOSample(
 export function exportORPOSamples(
   workspaceDir: string,
   targetModelFamily?: string | null,
-  _options: Record<string, never> = {} // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: options parameter intentionally unused
+  _options: Record<string, never> = {}  
 ): ExportResult {
   const exportId = crypto.randomUUID();
   const now = new Date().toISOString();
@@ -195,7 +195,7 @@ export function exportORPOSamples(
     reviewStatus: 'approved_for_training',
   });
 
-  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
+   
   let eligibleRecords: typeof allApprovedRecords;
 
   if (targetModelFamily !== undefined && targetModelFamily !== null) {
@@ -244,7 +244,7 @@ export function exportORPOSamples(
     }
 
     // Read artifact (throws on error — distinguishes read failure from missing artifact)
-    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch continues to next iteration
+     
     let artifact;
     try {
       artifact = readDatasetArtifact(workspaceDir, record.sampleFingerprint);

package/src/core/nocturnal-rule-implementation-validator.ts

@@ -201,7 +201,7 @@ export function validateRuleImplementationCandidate(
   try {
     const moduleExports = loadRuleImplementationModule(normalizedSource, 'nocturnal-candidate.js') as {
       meta?: unknown;
-      /* eslint-disable no-unused-vars -- Reason: type signature parameters, unused by design in function type definition */
+       
       evaluate?: (_input: RuleHostInput, _helpers: RuleHostHelpers) => unknown;
     };
 

package/src/core/nocturnal-snapshot-contract.ts

@@ -0,0 +1,112 @@
+import type { NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
+
+export interface NocturnalSnapshotContractResult {
+  status: 'valid' | 'invalid';
+  reasons: string[];
+  snapshot?: NocturnalSessionSnapshot;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNumberOrNull(value: unknown): value is number | null {
+  return value === null || (typeof value === 'number' && Number.isFinite(value));
+}
+
+export function validateNocturnalSnapshotIngress(
+  value: unknown
+): NocturnalSnapshotContractResult {
+  const reasons: string[] = [];
+
+  if (!isObjectRecord(value)) {
+    return { status: 'invalid', reasons: ['snapshot must be an object'] };
+  }
+
+  if (!isNonEmptyString(value.sessionId)) {
+    reasons.push('snapshot.sessionId must be a non-empty string');
+  }
+
+  if (!isNonEmptyString(value.startedAt)) {
+    reasons.push('snapshot.startedAt must be a non-empty string');
+  }
+
+  if (!isNonEmptyString(value.updatedAt)) {
+    reasons.push('snapshot.updatedAt must be a non-empty string');
+  }
+
+  const arrayFields = [
+    'assistantTurns',
+    'userTurns',
+    'toolCalls',
+    'painEvents',
+    'gateBlocks',
+  ] as const;
+  for (const field of arrayFields) {
+    if (!Array.isArray(value[field])) {
+      reasons.push(`snapshot.${field} must be an array`);
+    }
+  }
+
+  const stats = value.stats;
+  if (!isObjectRecord(stats)) {
+    reasons.push('snapshot.stats must be an object');
+  } else {
+    if (!isNumberOrNull(stats.totalAssistantTurns)) {
+      reasons.push('snapshot.stats.totalAssistantTurns must be a number or null');
+    }
+    if (!isNumberOrNull(stats.totalToolCalls)) {
+      reasons.push('snapshot.stats.totalToolCalls must be a number or null');
+    }
+    if (typeof stats.totalPainEvents !== 'number' || !Number.isFinite(stats.totalPainEvents)) {
+      reasons.push('snapshot.stats.totalPainEvents must be a finite number');
+    }
+    if (!isNumberOrNull(stats.totalGateBlocks)) {
+      reasons.push('snapshot.stats.totalGateBlocks must be a number or null');
+    }
+    if (!isNumberOrNull(stats.failureCount)) {
+      reasons.push('snapshot.stats.failureCount must be a number or null');
+    }
+  }
+
+  const isFallback = value._dataSource === 'pain_context_fallback';
+  if (value._dataSource !== undefined && !isFallback) {
+    reasons.push('snapshot._dataSource must be omitted or pain_context_fallback');
+  }
+
+  if (isFallback && isObjectRecord(stats) && Array.isArray(value.painEvents)) {
+    const hasPainSignal = value.painEvents.length > 0 || ((stats.totalPainEvents as number) > 0);
+    if (!hasPainSignal) {
+      reasons.push('fallback snapshot must contain at least one pain signal');
+    }
+  }
+
+  if (!isFallback && isObjectRecord(stats)) {
+    if (stats.totalAssistantTurns === null) {
+      reasons.push('non-fallback snapshot.stats.totalAssistantTurns must be a number');
+    }
+    if (stats.totalToolCalls === null) {
+      reasons.push('non-fallback snapshot.stats.totalToolCalls must be a number');
+    }
+    if (stats.totalGateBlocks === null) {
+      reasons.push('non-fallback snapshot.stats.totalGateBlocks must be a number');
+    }
+    if (stats.failureCount === null) {
+      reasons.push('non-fallback snapshot.stats.failureCount must be a number');
+    }
+  }
+
+  if (reasons.length > 0) {
+    return { status: 'invalid', reasons };
+  }
+
+  return {
+    status: 'valid',
+    reasons: [],
+    snapshot: value as unknown as NocturnalSessionSnapshot,
+  };
+}

package/src/core/nocturnal-trajectory-extractor.ts

@@ -116,13 +116,15 @@ export interface NocturnalSessionSnapshot {
   gateBlocks: NocturnalGateBlock[];
   /**
    * Summary statistics for quick triage.
+   * When _dataSource is 'pain_context_fallback', these fields are null
+   * to distinguish "no data" from "data is zero".
    */
   stats: {
-    totalAssistantTurns: number;
-    totalToolCalls: number;
+    totalAssistantTurns: number | null;
+    totalToolCalls: number | null;
     totalPainEvents: number;
-    totalGateBlocks: number;
-    failureCount: number;
+    totalGateBlocks: number | null;
+    failureCount: number | null;
   };
   /**
    * #219: Marker for data source to identify fallback/partial stats.
@@ -364,7 +366,7 @@ export class NocturnalTrajectoryExtractor {
  *   const sessions = extractor.listRecentNocturnalCandidateSessions({ limit: 10 });
  *   const snapshot = extractor.getNocturnalSessionSnapshot(sessionId);
  */
-/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: _stateDir parameter kept for API compatibility but unused in implementation */
+ 
 export function createNocturnalTrajectoryExtractor(
   workspaceDir: string,
   _stateDir?: string