principles-disciple 1.11.0 → 1.13.0

package/src/core/migration.ts

@@ -1,7 +1,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
-import { PD_DIRS, PD_FILES, resolvePdPath } from './paths.js';
+import type { PD_FILES} from './paths.js';
+import { resolvePdPath } from './paths.js';
 
 /**
  * Handles migration of Principles Disciple files from legacy directories
@@ -13,11 +14,10 @@ export function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir:
         const legacyStateDir = path.join(workspaceDir, 'memory', '.state');
         
         // Comprehensive migration map covering ALL legacy locations
-        const migrationMap: Array<{ legacy: string; newKey: keyof typeof PD_FILES }> = [
+        const migrationMap: { legacy: string; newKey: keyof typeof PD_FILES }[] = [
             // From docs/
             { legacy: path.join(legacyDocsDir, 'PRINCIPLES.md'), newKey: 'PRINCIPLES' },
             { legacy: path.join(legacyDocsDir, 'THINKING_OS.md'), newKey: 'THINKING_OS' },
-            { legacy: path.join(legacyDocsDir, '00-kernel.md'), newKey: 'KERNEL' },
             { legacy: path.join(legacyDocsDir, 'DECISION_POLICY.json'), newKey: 'DECISION_POLICY' },
             { legacy: path.join(legacyDocsDir, 'PLAN.md'), newKey: 'PLAN' },
             { legacy: path.join(legacyDocsDir, 'evolution_queue.json'), newKey: 'EVOLUTION_QUEUE' },

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

@@ -228,7 +228,7 @@ function readRegistry(stateDir: string): ModelDeploymentRegistry {
     return registry;
   } catch (err) {
     if (err instanceof SyntaxError || err instanceof Error) {
-      throw new Error(`Failed to read deployment registry from "${registryPath}": ${err.message}`);
+      throw new Error(`Failed to read deployment registry from "${registryPath}": ${err.message}`, { cause: err });
     }
     throw err;
   }
@@ -249,9 +249,10 @@ 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
+  fn: (_registry: ModelDeploymentRegistry) => T
 ): T {
   const registryPath = getRegistryPath(stateDir);
   return withLock(registryPath, () => {
@@ -348,6 +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,
@@ -451,7 +453,7 @@ export function listDeployments(
   }
 ): Deployment[] {
   const registry = readRegistry(stateDir);
-  let deployments = registry.deployments;
+  let {deployments} = registry;
 
   if (filter?.workerProfile) {
     deployments = deployments.filter((d) => d.workerProfile === filter.workerProfile);
@@ -711,7 +713,7 @@ export function getDeploymentRegistryStats(
   profilesWithRoutingEnabled: number;
 } {
   const registry = readRegistry(stateDir);
-  const deployments = registry.deployments;
+  const {deployments} = registry;
 
   return {
     totalDeployments: deployments.length,

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

@@ -249,7 +249,8 @@ function writeRegistry(stateDir: string, registry: ModelTrainingRegistry): void
  */
 function withRegistryLock<T>(
   stateDir: string,
-  fn: (registry: ModelTrainingRegistry) => T
+  // eslint-disable-next-line no-unused-vars -- parameter type annotation requires name
+  fn: (_: ModelTrainingRegistry) => T
 ): T {
   const registryPath = getRegistryPath(stateDir);
   return withLock(registryPath, () => {
@@ -320,6 +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,
@@ -498,7 +500,7 @@ export function listCheckpoints(
   }
 ): Checkpoint[] {
   const registry = readRegistry(stateDir);
-  let checkpoints = registry.checkpoints;
+  let {checkpoints} = registry;
 
   if (filter?.trainRunId) {
     checkpoints = checkpoints.filter((c) => c.trainRunId === filter.trainRunId);
@@ -795,7 +797,7 @@ export function getTrainingRegistryStats(
   const registry = readRegistry(stateDir);
 
   const runs = registry.trainingRuns;
-  const checkpoints = registry.checkpoints;
+  const {checkpoints} = registry;
   const evals = registry.evalSummaries;
 
   return {

package/src/core/nocturnal-arbiter.ts

@@ -22,8 +22,6 @@
  * - No LLM involvement — all checks are algorithmic
  */
 
-import type { NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -218,7 +216,7 @@ export function validateDreamerOutput(output: unknown): TrinityStageValidationRe
     });
 
     // Check for duplicate candidateIndices
-    const indices = (obj.candidates as Array<Record<string, unknown>>)
+    const indices = (obj.candidates as Record<string, unknown>[])
       .map((c) => c.candidateIndex)
       .filter((i) => typeof i === 'number');
     const uniqueIndices = new Set(indices);
@@ -287,7 +285,7 @@ export function validatePhilosopherOutput(output: unknown): TrinityStageValidati
     });
 
     // Check ranks are unique and sequential (1, 2, 3...)
-    const ranks = (obj.judgments as Array<Record<string, unknown>>)
+    const ranks = (obj.judgments as Record<string, unknown>[])
       .map((j) => j.rank)
       .filter((r) => typeof r === 'number')
       .sort((a, b) => a - b);
@@ -495,7 +493,7 @@ export function validateArtifact(
   }
 
   // Rule 3: Required string fields must be present and non-empty
-  const requiredFields: Array<{ key: keyof RawReflectionArtifact; label: string }> = [
+  const requiredFields: { key: keyof RawReflectionArtifact; label: string }[] = [
     { key: 'artifactId', label: 'artifactId' },
     { key: 'sessionId', label: 'sessionId' },
     { key: 'principleId', label: 'principleId' },
@@ -522,7 +520,7 @@ export function validateArtifact(
 
   // Rule 4: Cross-validate principleId
   if (options.expectedPrincipleId !== undefined) {
-    const principleId = obj.principleId;
+    const {principleId} = obj;
     if (!isNonEmptyString(principleId)) {
       failures.push({ reason: 'principleId is required but missing', field: 'principleId' });
     } else if (String(principleId) !== options.expectedPrincipleId) {
@@ -535,7 +533,7 @@ export function validateArtifact(
 
   // Rule 5: Cross-validate sessionId
   if (options.expectedSessionId !== undefined) {
-    const sessionId = obj.sessionId;
+    const {sessionId} = obj;
     if (!isNonEmptyString(sessionId)) {
       failures.push({ reason: 'sessionId is required but missing', field: 'sessionId' });
     } else if (String(sessionId) !== options.expectedSessionId) {
@@ -547,7 +545,7 @@ export function validateArtifact(
   }
 
   // Rule 6: Check for placeholder values in text fields
-  const textFields: Array<keyof RawReflectionArtifact> = [
+  const textFields: (keyof RawReflectionArtifact)[] = [
     'badDecision',
     'betterDecision',
     'rationale',
@@ -569,14 +567,14 @@ export function validateArtifact(
   }
 
   // Rule 7: Check sourceSnapshotRef if present
-  const sourceSnapshotRef = obj.sourceSnapshotRef;
+  const {sourceSnapshotRef} = obj;
   if (sourceSnapshotRef !== undefined && !isNonEmptyString(sourceSnapshotRef)) {
     failures.push({ reason: 'Field "sourceSnapshotRef" must be a non-empty string if present', field: 'sourceSnapshotRef' });
   }
 
   // Rule 8: badDecision should not be identical to betterDecision
-  const badDecision = obj.badDecision;
-  const betterDecision = obj.betterDecision;
+  const {badDecision} = obj;
+  const {betterDecision} = obj;
   if (isNonEmptyString(badDecision) && isNonEmptyString(betterDecision)) {
     if (String(badDecision).trim() === String(betterDecision).trim()) {
       failures.push({
@@ -587,7 +585,7 @@ export function validateArtifact(
   }
 
   // Rule 9: Rationale should not be too short (needs explanation)
-  const rationale = obj.rationale;
+  const {rationale} = obj;
   if (isNonEmptyString(rationale) && String(rationale).trim().length < 20) {
     failures.push({
       reason: 'rationale is too short — must provide meaningful explanation',
@@ -596,7 +594,7 @@ export function validateArtifact(
   }
 
   // Rule 10: Validate optional reflection quality metrics (if present)
-  const thinkingModelDelta = obj.thinkingModelDelta;
+  const {thinkingModelDelta} = obj;
   if (thinkingModelDelta !== undefined && typeof thinkingModelDelta !== 'number') {
     failures.push({
       reason: 'thinkingModelDelta must be a number if present',
@@ -609,7 +607,7 @@ export function validateArtifact(
     });
   }
 
-  const planningRatioGain = obj.planningRatioGain;
+  const {planningRatioGain} = obj;
   if (planningRatioGain !== undefined && typeof planningRatioGain !== 'number') {
     failures.push({
       reason: 'planningRatioGain must be a number if present',
@@ -691,6 +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-artifact-lineage.ts

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveNocturnalDir } from './nocturnal-paths.js';
+import { withLock } from '../utils/file-lock.js';
+
+export type ArtifactKind = 'behavioral-sample' | 'rule-implementation-candidate';
+
+export interface ArtifactLineageRecord {
+  artifactKind: ArtifactKind;
+  artifactId: string;
+  principleId: string;
+  ruleId: string | null;
+  sessionId: string;
+  sourceSnapshotRef: string;
+  sourcePainIds: string[];
+  sourceGateBlockIds: string[];
+  storagePath: string;
+  implementationId: string | null;
+  createdAt: string;
+}
+
+export interface CandidateArtifactLineageInput {
+  artifactId: string;
+  principleId: string;
+  ruleId: string;
+  sessionId: string;
+  sourceSnapshotRef: string;
+  sourcePainIds: string[];
+  sourceGateBlockIds: string[];
+  storagePath: string;
+  implementationId: string;
+  createdAt?: string;
+}
+
+function getLineageRegistryPath(workspaceDir: string): string {
+  return path.join(resolveNocturnalDir(workspaceDir, 'ROOT'), 'artifact-lineage.json');
+}
+
+function readArtifactLineageRegistry(workspaceDir: string): ArtifactLineageRecord[] {
+  const registryPath = getLineageRegistryPath(workspaceDir);
+  if (!fs.existsSync(registryPath)) {
+    return [];
+  }
+
+  try {
+    const content = fs.readFileSync(registryPath, 'utf-8');
+    return JSON.parse(content) as ArtifactLineageRecord[];
+  } catch {
+    return [];
+  }
+}
+
+function writeArtifactLineageRegistry(
+  workspaceDir: string,
+  records: ArtifactLineageRecord[]
+): void {
+  const registryPath = getLineageRegistryPath(workspaceDir);
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+  const tmpPath = `${registryPath}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(records, null, 2), 'utf-8');
+  fs.renameSync(tmpPath, registryPath);
+}
+
+export function appendArtifactLineageRecord(
+  workspaceDir: string,
+  record: ArtifactLineageRecord
+): ArtifactLineageRecord {
+  const registryPath = getLineageRegistryPath(workspaceDir);
+
+  return withLock(registryPath, () => {
+    const records = readArtifactLineageRegistry(workspaceDir);
+    const nextRecord: ArtifactLineageRecord = {
+      ...record,
+      sourcePainIds: [...record.sourcePainIds],
+      sourceGateBlockIds: [...record.sourceGateBlockIds],
+      storagePath: path.normalize(record.storagePath),
+    };
+    records.push(nextRecord);
+    writeArtifactLineageRegistry(workspaceDir, records);
+    return nextRecord;
+  });
+}
+
+export function listArtifactLineageRecords(
+  workspaceDir: string,
+  artifactKind?: ArtifactKind
+): ArtifactLineageRecord[] {
+  const records = readArtifactLineageRegistry(workspaceDir);
+  const filtered =
+    artifactKind === undefined
+      ? records
+      : records.filter((record) => record.artifactKind === artifactKind);
+
+  return filtered.sort(
+    (left, right) =>
+      new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime()
+  );
+}
+
+export function appendCandidateArtifactLineageRecord(
+  workspaceDir: string,
+  input: CandidateArtifactLineageInput
+): ArtifactLineageRecord {
+  return appendArtifactLineageRecord(workspaceDir, {
+    artifactKind: 'rule-implementation-candidate',
+    artifactId: input.artifactId,
+    principleId: input.principleId,
+    ruleId: input.ruleId,
+    sessionId: input.sessionId,
+    sourceSnapshotRef: input.sourceSnapshotRef,
+    sourcePainIds: input.sourcePainIds,
+    sourceGateBlockIds: input.sourceGateBlockIds,
+    storagePath: input.storagePath,
+    implementationId: input.implementationId,
+    createdAt: input.createdAt ?? new Date().toISOString(),
+  });
+}

package/src/core/nocturnal-artificer.ts

@@ -0,0 +1,257 @@
+import type { NocturnalSessionSnapshot } from './nocturnal-trajectory-extractor.js';
+import {
+  getPrincipleSubtree,
+  listImplementationsForRule,
+  listRuleImplementationsByState,
+} from './principle-tree-ledger.js';
+import type { LedgerRule } from './principle-tree-ledger.js';
+
+export type ArtificerArtifactKind = 'rule-implementation-candidate';
+
+export interface ArtificerLineageMetadata {
+  artifactKind: ArtificerArtifactKind;
+  sourceSnapshotRef: string;
+  sourcePainIds: string[];
+  sourceGateBlockIds: string[];
+}
+
+export interface ArtificerInput {
+  principleId: string;
+  ruleId: string;
+  snapshot: NocturnalSessionSnapshot;
+  scribeArtifact: {
+    sessionId: string;
+    badDecision: string;
+    betterDecision: string;
+    rationale: string;
+    sourceSnapshotRef: string;
+  };
+  lineage: ArtificerLineageMetadata;
+}
+
+export interface ArtificerOutput {
+  ruleId: string;
+  implementationType: 'code';
+  candidateSource: string;
+  helperUsage: string[];
+  expectedDecision: 'allow' | 'block' | 'requireApproval';
+  rationale: string;
+  lineage: ArtificerLineageMetadata;
+}
+
+export interface ArtificerTargetRuleScore {
+  ruleId: string;
+  score: number;
+  matchedSignals: string[];
+}
+
+export type ArtificerTargetRuleResolution =
+  | {
+      status: 'selected';
+      ruleId: string;
+      reason: 'single-rule' | 'evidence-winner';
+      scores: ArtificerTargetRuleScore[];
+    }
+  | {
+      status: 'skip';
+      reason:
+        | 'principle-not-found'
+        | 'no-rules'
+        | 'ambiguous-target-rule'
+        | 'no-deterministic-signal';
+      scores: ArtificerTargetRuleScore[];
+    };
+
+export interface TrinityArtificerContext {
+  principleId: string;
+  resolution: ArtificerTargetRuleResolution;
+  eligible: boolean;
+}
+
+function tokenize(value: string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+
+  return value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 3);
+}
+
+function countMatches(tokens: string[], haystacks: string[]): number {
+  return tokens.reduce((total, token) => {
+    if (haystacks.some((haystack) => haystack.includes(token))) {
+      return total + 1;
+    }
+    return total;
+  }, 0);
+}
+
+function scoreRule(
+  stateDir: string,
+  rule: LedgerRule,
+  snapshot: NocturnalSessionSnapshot
+): ArtificerTargetRuleScore {
+  const toolNames = snapshot.toolCalls.map((toolCall) => toolCall.toolName.toLowerCase());
+  const painReasons = snapshot.painEvents
+    .map((painEvent) => painEvent.reason?.toLowerCase())
+    .filter((reason): reason is string => typeof reason === 'string' && reason.length > 0);
+  const gateReasons = snapshot.gateBlocks.map((gateBlock) => gateBlock.reason.toLowerCase());
+  const ruleTokens = [
+    ...tokenize(rule.name),
+    ...tokenize(rule.description),
+    ...tokenize(rule.triggerCondition),
+    ...tokenize(rule.action),
+  ];
+
+  const gateMatches = countMatches(ruleTokens, gateReasons);
+  const painMatches = countMatches(ruleTokens, painReasons);
+  const toolMatches = countMatches(ruleTokens, toolNames);
+  const candidateImplCount = listRuleImplementationsByState(stateDir, rule.id, 'candidate').length;
+  const totalImplCount = listImplementationsForRule(stateDir, rule.id).length;
+  const implementationSignal = Math.max(totalImplCount - candidateImplCount, 0);
+  const score = gateMatches * 1000 + painMatches * 100 + toolMatches * 10 + implementationSignal;
+  const matchedSignals: string[] = [];
+
+  if (gateMatches > 0) {
+    matchedSignals.push(`gate:${gateMatches}`);
+  }
+  if (painMatches > 0) {
+    matchedSignals.push(`pain:${painMatches}`);
+  }
+  if (toolMatches > 0) {
+    matchedSignals.push(`tool:${toolMatches}`);
+  }
+  if (implementationSignal > 0) {
+    matchedSignals.push(`impl:${implementationSignal}`);
+  }
+
+  return {
+    ruleId: rule.id,
+    score,
+    matchedSignals,
+  };
+}
+
+export function resolveArtificerTargetRule(
+  stateDir: string,
+  principleId: string,
+  snapshot: NocturnalSessionSnapshot
+): ArtificerTargetRuleResolution {
+  const subtree = getPrincipleSubtree(stateDir, principleId);
+  if (!subtree) {
+    return {
+      status: 'skip',
+      reason: 'principle-not-found',
+      scores: [],
+    };
+  }
+
+  const eligibleRules = subtree.rules
+    .map((entry) => entry.rule)
+    .filter((rule) => rule.status !== 'retired');
+
+  if (eligibleRules.length === 0) {
+    return {
+      status: 'skip',
+      reason: 'no-rules',
+      scores: [],
+    };
+  }
+
+  if (eligibleRules.length === 1) {
+    return {
+      status: 'selected',
+      ruleId: eligibleRules[0].id,
+      reason: 'single-rule',
+      scores: [
+        {
+          ruleId: eligibleRules[0].id,
+          score: 1,
+          matchedSignals: ['single-rule'],
+        },
+      ],
+    };
+  }
+
+  const scores = eligibleRules.map((rule) => scoreRule(stateDir, rule, snapshot));
+  const sorted = [...scores].sort((left, right) => {
+    if (right.score !== left.score) {
+      return right.score - left.score;
+    }
+    return left.ruleId.localeCompare(right.ruleId);
+  });
+  const [winner, runnerUp] = sorted;
+
+  if (!winner || winner.score === 0) {
+    return {
+      status: 'skip',
+      reason: 'no-deterministic-signal',
+      scores: sorted,
+    };
+  }
+
+  if (runnerUp && runnerUp.score === winner.score) {
+    return {
+      status: 'skip',
+      reason: 'ambiguous-target-rule',
+      scores: sorted,
+    };
+  }
+
+  return {
+    status: 'selected',
+    ruleId: winner.ruleId,
+    reason: 'evidence-winner',
+    scores: sorted,
+  };
+}
+
+export function shouldRunArtificer(
+  snapshot: NocturnalSessionSnapshot,
+  resolution: ArtificerTargetRuleResolution,
+  minimumSignalCount = 2
+): boolean {
+  if (resolution.status !== 'selected') {
+    return false;
+  }
+
+  const signalCount =
+    snapshot.stats.totalPainEvents +
+    snapshot.stats.totalGateBlocks +
+    snapshot.stats.failureCount;
+
+  return signalCount >= minimumSignalCount;
+}
+
+export function parseArtificerOutput(payload: string): ArtificerOutput | null {
+  try {
+    const parsed = JSON.parse(payload) as Partial<ArtificerOutput>;
+    if (
+      typeof parsed.ruleId !== 'string' ||
+      typeof parsed.candidateSource !== 'string' ||
+      !Array.isArray(parsed.helperUsage) ||
+      typeof parsed.expectedDecision !== 'string' ||
+      typeof parsed.rationale !== 'string' ||
+      !parsed.lineage
+    ) {
+      return null;
+    }
+
+    return {
+      ruleId: parsed.ruleId,
+      implementationType: 'code',
+      candidateSource: parsed.candidateSource,
+      helperUsage: parsed.helperUsage.filter(
+        (value): value is string => typeof value === 'string'
+      ),
+      expectedDecision: parsed.expectedDecision,
+      rationale: parsed.rationale,
+      lineage: parsed.lineage,
+    };
+  } catch {
+    return null;
+  }
+}

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

@@ -158,7 +158,7 @@ export function scoreCandidate(
   let boundedness = 0.5;
   // Specific: mentions specific targets (files, tools, etc.)
   const betterDecisionStr = candidate.betterDecision ?? '';
-  const hasSpecificTarget = /[a-zA-Z0-9_\-]+\.(ts|js|json|md|yml|yaml|sh|py|go|rs)/.test(betterDecisionStr);
+  const hasSpecificTarget = /[a-zA-Z0-9_.]+\.(ts|js|json|md|yml|yaml|sh|py|go|rs)/.test(betterDecisionStr);
   if (hasSpecificTarget) boundedness += 0.2;
   // Not too generic
   const genericPatterns = [
@@ -241,6 +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[],
@@ -327,6 +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[],
@@ -376,7 +378,7 @@ export function runTournament(
   }
 
   // Winner is rank 1
-  const winner = eligible[0];
+  const [winner] = eligible;
 
   trace.push({
     step: 'Winner Selected',