principles-disciple 1.149.0 → 1.151.0

package/README.md

@@ -25,7 +25,6 @@ All commands support **short aliases** for easier input:
 | `/pdb` | `/pd-bootstrap` | Scan environment tools |
 | `/pdr` | `/pd-research` | Research tools and capabilities |
 | `/pdt` | `/pd-thinking` | Manage thinking models |
-| `/pdrl` | `/pd-reflect` | Manually trigger nocturnal reflection |
 | `/pdd` | `/pd-daily` | Configure and send daily report |
 | `/pdg` | `/pd-grooming` | Workspace cleanup |
 | `/pdh` | `/pd-help` | Show command reference |
@@ -39,9 +38,6 @@ All commands support **short aliases** for easier input:
 | `/pd-rollback` | Rollback to previous state |
 | `/pd-export` | Export trajectory/correction data |
 | `/pd-samples` | Review correction samples |
-| `/pd-nocturnal-review` | Review nocturnal training samples |
-| `/nocturnal-train` | Nocturnal training operations |
-| `/nocturnal-rollout` | Nocturnal rollout and promotion |
 | `/pd-workflow-debug` | Debug workflow state |
 
 ### Configuration

package/dist/core/event-log.js

@@ -69,8 +69,6 @@ export class EventLog {
     recordPainSignal(sessionId, data) {
         this.record('pain_signal', 'detected', sessionId, data);
     }
-    // recordRuleMatch removed (PRI-451 Wave 1): dead code. Its only effect was
-    // incrementing stats.pain.rulesMatched (also dead, removed in Wave 1.5).
     recordRulePromotion(data) {
         this.record('rule_promotion', 'promoted', undefined, data);
     }
@@ -350,9 +348,6 @@ export class EventLog {
             stats.empathy.rollbackCount++;
             stats.empathy.rolledBackScore += data.originalScore || 0;
         }
-        // rule_match handler removed (PRI-451 Wave 1.5): recordRuleMatch is gone
-        // (Wave 1.1), so no rule_match events are emitted; stats.pain.rulesMatched
-        // was its only consumer and is also removed.
         else if (entry.type === 'rule_promotion') {
             // stats.pain.candidatesPromoted removed (PRI-451 Wave 1.5): dead counter.
             stats.evolution.rulesPromoted++;

package/dist/core/intent-doc-reader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * PRI-467 — safeReadIntentDoc: plugin I/O wrapper for reading INTENT.md.
+ *
+ * Reads `.principles/INTENT.md` with:
+ * - Feature flag check FIRST (SPEC §12: flag off → flag_disabled without fs)
+ * - TTL + mtime cache (60s TTL, mtime check) mirroring prompt.ts cachedReadFile
+ * - 32KB size cap (INTENT_MAX_BYTES)
+ * - Never throws — all errors return structured `reason` + `nextAction`
+ *
+ * Trust boundary (SPEC §12.2):
+ * - Raw content is returned for the pure builder to escape; this reader does
+ *   NOT escape or bound the content for prompt injection. The pure builder
+ *   `buildIntentFrictionBlock` handles escaping + bounding.
+ *
+ * ERR checklist:
+ * EP-01 / ERR-001, ERR-005: raw content validated with typeof, never `as`
+ * EP-02 / ERR-025, ERR-070: production path; plugin I/O file in the whitelist
+ * EP-03 / ERR-002, ERR-014: every degraded path returns structured reason + nextAction
+ * EP-09: tests use real fs writes in temp dirs
+ *
+ * Architecture: this file is I/O (fs, path). It is whitelisted in
+ * architecture-regression.test.ts KNOWN_PLUGIN_CORE_FILES.
+ */
+import { type IntentDocSections, type IntentDocWarning } from '@principles/core/runtime-v2';
+export type SafeReadIntentDocReason = 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
+export interface IntentDoc {
+    /** Raw INTENT.md content (unescaped — caller escapes for prompt injection). */
+    raw: string;
+    /** Parsed sections from the raw content. */
+    sections: IntentDocSections;
+    /** SHA-256 content hash for deduplication and audit. */
+    contentHash: string;
+    /** Absolute path to the INTENT.md file. */
+    path: string;
+    /** ISO timestamp when the doc was read. */
+    readAt: string;
+    /** Validation warnings (missing/empty/too_vague sections). */
+    warnings: IntentDocWarning[];
+}
+export interface SafeReadIntentDocResult {
+    /** True when the doc was successfully read and parsed. */
+    ok: boolean;
+    /** True when the INTENT.md file exists on disk. */
+    found: boolean;
+    /** True when the intent_engineering flag is enabled. */
+    flagEnabled: boolean;
+    /** The parsed IntentDoc, present only when ok=true. */
+    doc?: IntentDoc;
+    /** Structured reason for a degraded path (present when ok=false). */
+    reason?: SafeReadIntentDocReason;
+    /** Next action for the operator (present when ok=false). */
+    nextAction?: string;
+    /** Validation warnings (always present, empty when no warnings). */
+    warnings: IntentDocWarning[];
+}
+/**
+ * Reset the intent doc cache for test isolation.
+ * Call in beforeEach() to ensure tests don't pollute each other.
+ */
+export declare function resetIntentDocCacheForTest(workspaceDir?: string): void;
+/**
+ * Safely read INTENT.md for prompt injection.
+ *
+ * Contract (SPEC §12):
+ * 1. Flag check FIRST via loadFeatureFlagFromConfig. Flag off → flag_disabled
+ *    WITHOUT any fs access to INTENT.md.
+ * 2. Flag on → check TTL + mtime cache. If cached and fresh → return cached.
+ * 3. Otherwise → stat the file (oversized check), read, parse, validate, cache.
+ * 4. Never throws — all errors return structured reason + nextAction.
+ *
+ * @param workspaceDir - Absolute path to the workspace root
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export declare function safeReadIntentDoc(workspaceDir: string, options?: {
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}): SafeReadIntentDocResult;

package/dist/core/intent-doc-reader.js

@@ -0,0 +1,189 @@
+/**
+ * PRI-467 — safeReadIntentDoc: plugin I/O wrapper for reading INTENT.md.
+ *
+ * Reads `.principles/INTENT.md` with:
+ * - Feature flag check FIRST (SPEC §12: flag off → flag_disabled without fs)
+ * - TTL + mtime cache (60s TTL, mtime check) mirroring prompt.ts cachedReadFile
+ * - 32KB size cap (INTENT_MAX_BYTES)
+ * - Never throws — all errors return structured `reason` + `nextAction`
+ *
+ * Trust boundary (SPEC §12.2):
+ * - Raw content is returned for the pure builder to escape; this reader does
+ *   NOT escape or bound the content for prompt injection. The pure builder
+ *   `buildIntentFrictionBlock` handles escaping + bounding.
+ *
+ * ERR checklist:
+ * EP-01 / ERR-001, ERR-005: raw content validated with typeof, never `as`
+ * EP-02 / ERR-025, ERR-070: production path; plugin I/O file in the whitelist
+ * EP-03 / ERR-002, ERR-014: every degraded path returns structured reason + nextAction
+ * EP-09: tests use real fs writes in temp dirs
+ *
+ * Architecture: this file is I/O (fs, path). It is whitelisted in
+ * architecture-regression.test.ts KNOWN_PLUGIN_CORE_FILES.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { INTENT_MAX_BYTES, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
+import { loadFeatureFlagFromConfig } from './pd-config-loader.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+const INTENT_FILENAME = 'INTENT.md';
+const INTENT_DIR = '.principles';
+const INTENT_CACHE_TTL_MS = 60_000; // 1 minute (SPEC §12.1)
+// ── Module-level cache (per-workspace) ───────────────────────────────────────
+const _intentDocCache = new Map();
+/**
+ * Reset the intent doc cache for test isolation.
+ * Call in beforeEach() to ensure tests don't pollute each other.
+ */
+export function resetIntentDocCacheForTest(workspaceDir) {
+    if (workspaceDir) {
+        _intentDocCache.delete(workspaceDir);
+    }
+    else {
+        _intentDocCache.clear();
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function getIntentFilePath(workspaceDir) {
+    return path.join(workspaceDir, INTENT_DIR, INTENT_FILENAME);
+}
+function buildDocFromRaw(raw, filePath, readAt) {
+    const sections = parseIntentDocSections(raw);
+    const warnings = validateIntentDocSections(sections);
+    const contentHash = computeIntentContentHash(raw);
+    return {
+        raw,
+        sections,
+        contentHash,
+        path: filePath,
+        readAt,
+        warnings,
+    };
+}
+// ── Main entrypoint ──────────────────────────────────────────────────────────
+/**
+ * Safely read INTENT.md for prompt injection.
+ *
+ * Contract (SPEC §12):
+ * 1. Flag check FIRST via loadFeatureFlagFromConfig. Flag off → flag_disabled
+ *    WITHOUT any fs access to INTENT.md.
+ * 2. Flag on → check TTL + mtime cache. If cached and fresh → return cached.
+ * 3. Otherwise → stat the file (oversized check), read, parse, validate, cache.
+ * 4. Never throws — all errors return structured reason + nextAction.
+ *
+ * @param workspaceDir - Absolute path to the workspace root
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export function safeReadIntentDoc(workspaceDir, options) {
+    // SPEC §12 — Flag check FIRST. Flag off → no fs access, no cache access.
+    const flagResult = loadFeatureFlagFromConfig(workspaceDir, 'intent_engineering', options?.logger);
+    if (!flagResult.enabled) {
+        return {
+            ok: false,
+            found: false,
+            flagEnabled: false,
+            reason: 'flag_disabled',
+            nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+            warnings: [],
+        };
+    }
+    const filePath = getIntentFilePath(workspaceDir);
+    const now = Date.now();
+    // Check cache freshness (TTL + mtime)
+    const cached = _intentDocCache.get(workspaceDir);
+    if (cached && (now - cached.loadedAt) < INTENT_CACHE_TTL_MS) {
+        // Cache is within TTL. Verify mtime hasn't changed.
+        try {
+            const stat = fs.statSync(filePath);
+            if (stat.mtimeMs === cached.mtime) {
+                // Cache hit — return cached doc
+                return {
+                    ok: true,
+                    found: true,
+                    flagEnabled: true,
+                    doc: cached.doc,
+                    warnings: cached.doc.warnings,
+                };
+            }
+        }
+        catch {
+            // File may have been deleted since caching. Fall through to not_found path.
+            // Don't return cached doc if the file no longer exists.
+        }
+    }
+    // Fresh read path
+    try {
+        // Check existence first
+        if (!fs.existsSync(filePath)) {
+            // Invalidate stale cache entry if any
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: true,
+                reason: 'not_found',
+                nextAction: 'Create .principles/INTENT.md using "pd intent init".',
+                warnings: [],
+            };
+        }
+        const stat = fs.statSync(filePath);
+        // SPEC §12 — 32KB size cap
+        if (stat.size > INTENT_MAX_BYTES) {
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: true,
+                flagEnabled: true,
+                reason: 'oversized',
+                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                warnings: [],
+            };
+        }
+        const raw = fs.readFileSync(filePath, 'utf8');
+        // PRI-467 review fix (P2): TOCTOU guard — re-check actual byte length
+        // after readFileSync. The file may have grown between statSync() and
+        // readFileSync(), bypassing the stat.size oversized check. Without this,
+        // an oversized file would enter parse/hash/cache as ok:true.
+        const actualBytes = Buffer.byteLength(raw, 'utf8');
+        if (actualBytes > INTENT_MAX_BYTES) {
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: true,
+                flagEnabled: true,
+                reason: 'oversized',
+                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${actualBytes} bytes after read). Reduce content.`,
+                warnings: [],
+            };
+        }
+        const doc = buildDocFromRaw(raw, filePath, new Date(now).toISOString());
+        // Update cache
+        _intentDocCache.set(workspaceDir, {
+            doc,
+            mtime: stat.mtimeMs,
+            loadedAt: now,
+        });
+        return {
+            ok: true,
+            found: true,
+            flagEnabled: true,
+            doc,
+            warnings: doc.warnings,
+        };
+    }
+    catch (err) {
+        // ERR-002 — graceful degradation with reason + nextAction
+        _intentDocCache.delete(workspaceDir);
+        const message = err instanceof Error ? err.message : String(err);
+        options?.logger?.warn?.(`[PD:Intent] safeReadIntentDoc failed: workspace=${workspaceDir}, error=${message}`);
+        return {
+            ok: false,
+            found: false,
+            flagEnabled: true,
+            reason: 'read_error',
+            nextAction: 'Check filesystem permissions for .principles/INTENT.md.',
+            warnings: [],
+        };
+    }
+}

package/dist/hooks/prompt-helpers.d.ts

@@ -76,9 +76,13 @@ export declare function formatEvolutionPrinciples(active: EvolutionPrincipleEntr
  * Assemble appendSystemContext from ordered parts.
  *
  * Content order (most important last):
- * behavioral_constraints → project_context → working_memory →
+ * behavioral_constraints → project_context → intent_block → working_memory →
  * thinking_os → evolution_principles → core_principles
  *
+ * PRI-467: intent_block (INTENT.md reference) sits after project_context
+ * (stable reference data, lower priority than principles) and before
+ * working_memory (volatile per-session state).
+ *
  * Pure logic — string assembly only, no I/O.
  *
  * @param parts Ordered content parts (empty/undefined parts are skipped)

package/dist/hooks/prompt-helpers.js

@@ -187,9 +187,13 @@ export function formatEvolutionPrinciples(active, probation) {
  * Assemble appendSystemContext from ordered parts.
  *
  * Content order (most important last):
- * behavioral_constraints → project_context → working_memory →
+ * behavioral_constraints → project_context → intent_block → working_memory →
  * thinking_os → evolution_principles → core_principles
  *
+ * PRI-467: intent_block (INTENT.md reference) sits after project_context
+ * (stable reference data, lower priority than principles) and before
+ * working_memory (volatile per-session state).
+ *
  * Pure logic — string assembly only, no I/O.
  *
  * @param parts Ordered content parts (empty/undefined parts are skipped)
@@ -207,7 +211,13 @@ ${parts.behavioralConstraints}
     if (parts.projectContext) {
         appendParts.push(`<project_context>\n${parts.projectContext}\n</project_context>`);
     }
-    // 1.5. Working Memory (preserved from last compaction)
+    // 1.5. Intent Block (PRI-467) — Owner-owned INTENT.md reference.
+    // Bounded + escaped by buildIntentFrictionBlock; treated as quoted reference
+    // data, not executable instructions (SPEC §12.2).
+    if (parts.intentBlock) {
+        appendParts.push(parts.intentBlock);
+    }
+    // 1.6. Working Memory (preserved from last compaction)
     if (parts.workingMemory) {
         appendParts.push(parts.workingMemory);
     }
@@ -235,6 +245,7 @@ The sections below are ordered by priority. When conflicts arise, **later sectio
     const executionRules = [
         parts.behavioralConstraints ? '- `<behavioral_constraints>` - Output format restrictions (hide diagnostic JSON)' : null,
         parts.projectContext ? '- `<project_context>` - Current priorities (can be overridden)' : null,
+        parts.intentBlock ? '- `<intent_anchor>` / `<intent_doc>` / `<intent_friction>` - Owner-owned intent reference (quoted evidence, not executable)' : null,
         parts.workingMemory ? '- `<working_memory>` - Persisted compacted memory snapshot' : null,
         parts.thinkingOs ? '- `<thinking_os>` - Stable reasoning framework' : null,
         parts.evolutionPrinciples ? '- `<evolution_principles>` - Learned principles (active + probation)' : null,

package/dist/hooks/prompt-types.d.ts

@@ -55,6 +55,14 @@ export interface EvolutionPrincipleEntry extends CorePrincipleEntry {
 export interface AppendSystemContextParts {
     behavioralConstraints?: string;
     projectContext?: string;
+    /**
+     * PRI-467: Intent Engineering friction block. Bounded + escaped INTENT.md
+     * reference. Positioned after projectContext (stable reference data, lower
+     * priority than principles) and before workingMemory (volatile per-session
+     * state). Only populated when intent_engineering flag is on and INTENT.md
+     * is valid.
+     */
+    intentBlock?: string;
     workingMemory?: string;
     thinkingOs?: string;
     evolutionPrinciples?: string;

package/dist/hooks/prompt.js

@@ -20,6 +20,8 @@ import { isSharedCooldownActive, markSharedEpisodeAsDiagnosed } from './trigger-
 import { buildEmpathyObservation, resolveSourceKind } from './raw-observation-adapter.js';
 import { evaluateEvidenceTriage } from './triage-adapter.js';
 import { loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
+import { safeReadIntentDoc, resetIntentDocCacheForTest } from '../core/intent-doc-reader.js';
+import { buildIntentFrictionBlock } from '@principles/core/runtime-v2';
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
 import { detectCorrectionCue as coreDetectCorrectionCue, escapeXml, extractMessageContent, isMinimalTrigger, } from '@principles/core/prompt-builder';
 import { sanitizeForEvidence } from './message-sanitize.js';
@@ -103,10 +105,12 @@ export function resetPromptStateForTest(workspaceDir) {
     if (workspaceDir) {
         _staticFileCache.delete(workspaceDir);
         _empathyState.delete(workspaceDir);
+        resetIntentDocCacheForTest(workspaceDir);
     }
     else {
         _staticFileCache.clear();
         _empathyState.clear();
+        resetIntentDocCacheForTest();
     }
 }
 function parseContextInjectionConfig(value) {
@@ -871,11 +875,38 @@ export async function handleBeforePromptBuild(event, ctx) {
     catch (e) {
         logger?.warn?.(`[PD:RuntimeV2] Failed to read Runtime V2 prompt activations: ${String(e)}`);
     }
+    // ── PRI-467: Intent Engineering — INTENT.md friction block injection ──
+    // SPEC §5: flag off → no fs access, no cache access, no injection, no telemetry.
+    // SPEC §13.1: inject only when flag on + INTENT.md exists + safeReadIntentDoc ok=true.
+    // SPEC §14.1 Mode A: prompt-only — no output-hook capture, no check_emitted counter.
+    let intentBlockContent;
+    try {
+        const intentFlag = loadFeatureFlagFromConfig(workspaceDir, 'intent_engineering', logger);
+        if (intentFlag.enabled) {
+            const intentResult = safeReadIntentDoc(workspaceDir, { logger });
+            if (intentResult.ok && intentResult.doc) {
+                const block = buildIntentFrictionBlock({ rawIntentMd: intentResult.doc.raw });
+                if (block.length > 0) {
+                    intentBlockContent = block;
+                }
+            }
+            else if (!intentResult.ok && intentResult.reason !== 'not_found') {
+                // SPEC §13.1: missing file is silent (no debug noise). Other degraded
+                // paths (oversized, read_error, flag_disabled) log a debug reason.
+                logger?.debug?.(`[PD:Intent] INTENT.md injection skipped: reason=${intentResult.reason ?? 'unknown'}, nextAction=${intentResult.nextAction ?? 'none'}`);
+            }
+        }
+    }
+    catch (intentErr) {
+        // ERR-002 — fail-open: never let INTENT injection break the prompt hook.
+        logger?.warn?.(`[PD:Intent] INTENT injection failed, skipping: ${String(intentErr)}`);
+    }
     // Build appendSystemContext with recency effect
-    // Content order (most important last): behavioral_constraints -> project_context -> working_memory -> reflection_log -> thinking_os -> principles
+    // Content order (most important last): behavioral_constraints -> project_context -> intent_block -> working_memory -> reflection_log -> thinking_os -> principles
     appendSystemContext = assembleAppendSystemContext({
         behavioralConstraints: shouldInjectBehavioralConstraints ? empathySilenceConstraint : undefined,
         projectContext: projectContextContent || undefined,
+        intentBlock: intentBlockContent,
         workingMemory: workingMemoryContent || undefined,
         thinkingOs: thinkingOsContent || undefined,
         evolutionPrinciples: evolutionPrinciplesContent || undefined,
@@ -892,10 +923,12 @@ export async function handleBeforePromptBuild(event, ctx) {
     // routing helpers deleted per PRI-448. No routing-related content is injected.
     // ──── 8. SIZE GUARD ────
     // Delegates to @principles/core/prompt-builder/truncateInjectionToBudget
-    // which handles priority stripping: project_context → thinking_os →
-    // evolution_principles → reflection_log → reason: truncation → fallback.
+    // which handles priority stripping: project_context → intent_block →
+    // thinking_os → evolution_principles → reflection_log → reason: truncation → fallback.
+    // PRI-467: intentBlockContent is passed so the guard can strip INTENT by
+    // exact match before falling back to the nuclear option.
     const result = truncateInjectionToBudget(prependSystemContext, prependContext, appendSystemContext, {
-        blocks: { projectContextContent, thinkingOsContent, evolutionPrinciplesContent },
+        blocks: { projectContextContent, intentBlockContent, thinkingOsContent, evolutionPrinciplesContent },
     });
     prependSystemContext = result.prependSystemContext;
     prependContext = result.prependContext;

package/dist/service/runtime-summary-service.js

@@ -16,7 +16,7 @@ function pushWarning(warnings, message) {
     }
 }
 /**
- * YAML-SSOT-03: resolve a dot-path (e.g. 'evolution.nocturnalDreamerCompleted') from dailyStats.
+ * YAML-SSOT-03: resolve a dot-path (e.g. 'evolution.rulehostEvaluated') from dailyStats.
  * Returns { count, resolvable } to distinguish "field not found / non-numeric" from "legitimate zero".
  */
 function resolveStatsField(stats, dotPath) {

package/dist/types/event-types.d.ts

@@ -1,2 +1,2 @@
-export type { EventType, EventCategory, EventLogEntry, ToolCallEventData, PainSignalEventData, RuleMatchEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, HeartbeatDiagnosisEventData, DiagnosisTaskEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData, ToolCallStats, ErrorStats, EmpathyEventStats, GfiStats, EvolutionStats as EventEvolutionStats, HookStats, DailyStats, } from '@principles/core/runtime-v2';
+export type { EventType, EventCategory, EventLogEntry, ToolCallEventData, PainSignalEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, HeartbeatDiagnosisEventData, DiagnosisTaskEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData, ToolCallStats, ErrorStats, EmpathyEventStats, GfiStats, EvolutionStats as EventEvolutionStats, HookStats, DailyStats, } from '@principles/core/runtime-v2';
 export { createEmptyDailyStats, } from '@principles/core/runtime-v2';

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.149.0",
+  "version": "1.151.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.149.0",
+  "version": "1.151.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",
@@ -47,7 +47,6 @@
     "lint": "eslint \"src/**/*.ts\"",
     "bootstrap-rules": "node scripts/bootstrap-rules.mjs",
     "compile-principles": "node scripts/compile-principles.mjs",
-    "validate-live-path": "tsx scripts/validate-live-path.ts",
     "sync-plugin": "node scripts/sync-plugin.mjs"
   },
   "devDependencies": {

package/scripts/acceptance-test.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * Nocturnal Pipeline — End-to-End Acceptance Test
+ * PD Pipeline — End-to-End Acceptance Test
  *
- * Verifies that all components of the Nocturnal reflection pipeline
+ * Verifies that all components of the PD reflection pipeline
  * work correctly in a real environment (not unit tests).
  *
  * Usage:
@@ -71,7 +71,7 @@ function main() {
     process.exit(1);
   }
 
-  console.log('\n🧪 Nocturnal Pipeline Acceptance Test');
+  console.log('\n🧪 PD Pipeline Acceptance Test');
   console.log('═'.repeat(55));
   console.log(`Workspace: ${workspaceDir}`);
   console.log(`Database:  ${dbPath}\n`);

package/scripts/validate-live-path.ts

@@ -1,462 +0,0 @@
-#!/usr/bin/env node
-/**
- * Validate Live Path Script (Phase 18) — with Data Flow Monitoring
- *
- * Validates the end-to-end nocturnal workflow path with bootstrapped principles.
- *
- * Purpose:
- * - Reads bootstrapped rules from principle_training_state.json
- * - Creates synthetic snapshot with recentPain to pass hasUsableNocturnalSnapshot() guard
- * - Enqueues sleep_reflection task with proper file locking
- * - Polls subagent_workflows.db directly for nocturnal workflows
- * - Correlates workflow to queue item via taskId
- * - Verifies state='completed' and explicit resolution (not 'expired')
- * - Monitors data flow: queue state → workflow state → artifact persistence
- * - Outputs summary and exits 0 on success, non-zero on failure
- *
- * Usage:
- *   tsx scripts/validate-live-path.ts [--verbose]
- *
- * Environment:
- *   WORKSPACE_DIR - Optional workspace directory (defaults to process.cwd())
- */
-
-import * as Database from 'better-sqlite3';
-import * as fs from 'fs';
-import * as path from 'path';
-
-// ─── Constants ───────────────────────────────────────────────────────────
-const POLL_INTERVAL_MS = 5_000;
-const POLL_TIMEOUT_MS = 5 * 60 * 1000;  // 5 minutes
-const LOCK_SUFFIX = '.lock';
-const LOCK_MAX_RETRIES = 50;
-const LOCK_RETRY_DELAY_MS = 50;
-const LOCK_STALE_MS = 30_000;
-const WORKSPACE_DIR = process.env.WORKSPACE_DIR || process.cwd();
-const STATE_DIR = path.join(WORKSPACE_DIR, '.state');
-const QUEUE_PATH = path.join(STATE_DIR, 'EVOLUTION_QUEUE');
-const LEDGER_PATH = path.join(STATE_DIR, 'principle_training_state.json');
-const DB_PATH = path.join(STATE_DIR, 'subagent_workflows.db');
-const SAMPLES_DIR = path.join(STATE_DIR, 'nocturnal', 'samples');
-
-// ─── Helpers ─────────────────────────────────────────────────────────────
-function timestamp(): string {
-  return new Date().toISOString();
-}
-
-function logStep(step: string, detail: string): void {
-  console.log(`[${timestamp()}] ▸ ${step}: ${detail}`);
-}
-
-function logData(label: string, data: unknown): void {
-  const display = typeof data === 'string' ? data : JSON.stringify(data).slice(0, 300);
-  console.log(`[${timestamp()}]   📦 ${label}: ${display}`);
-}
-
-function safeReadJson(filePath: string): unknown {
-  try {
-    if (!fs.existsSync(filePath)) return null;
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch { return null; }
-}
-
-// ─── Types ───────────────────────────────────────────────────────────────
-interface LedgerRule {
-  id: string;
-  principleId: string;
-  action: string;
-  type: string;
-}
-
-interface HybridLedgerStore {
-  tree: {
-    rules: Record<string, LedgerRule>;
-  };
-}
-
-interface WorkflowRow {
-  workflow_id: string;
-  workflow_type: string;
-  state: string;
-  metadata_json: string;
-  created_at: number;
-}
-
-interface QueueItem {
-  id: string;
-  taskKind: string;
-  status: string;
-  resolution?: string;
-  resultRef?: string;
-}
-
-interface LockContext {
-  lockPath: string;
-  pid: number;
-  release: () => void;
-}
-
-// ─── File Lock Functions (simplified from file-lock.ts) ──────────────────
-async function acquireLockAsync(filePath: string, options: {
-  lockSuffix?: string;
-  maxRetries?: number;
-  baseRetryDelayMs?: number;
-  lockStaleMs?: number;
-} = {}): Promise<LockContext> {
-  const lockSuffix = options.lockSuffix ?? LOCK_SUFFIX;
-  const maxRetries = options.maxRetries ?? LOCK_MAX_RETRIES;
-  const baseRetryDelayMs = options.baseRetryDelayMs ?? LOCK_RETRY_DELAY_MS;
-  const lockStaleMs = options.lockStaleMs ?? LOCK_STALE_MS;
-  const { pid } = process;
-  const lockPath = filePath + lockSuffix;
-
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      // Check if lock file exists and is stale
-      if (fs.existsSync(lockPath)) {
-        const lockContent = fs.readFileSync(lockPath, 'utf8');
-        const lockPid = parseInt(lockContent, 10);
-        const lockStats = fs.statSync(lockPath);
-        const lockAge = Date.now() - lockStats.mtimeMs;
-
-        // Clean up stale lock
-        if (lockAge > lockStaleMs) {
-          fs.unlinkSync(lockPath);
-        } else if (lockPid !== pid) {
-          // Lock held by another process
-          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
-          continue;
-        }
-      }
-
-      // Acquire lock
-      fs.writeFileSync(lockPath, pid.toString(), { flag: 'wx' });
-      return {
-        lockPath,
-        pid,
-        release: () => {
-          try {
-            if (fs.existsSync(lockPath)) {
-              fs.unlinkSync(lockPath);
-            }
-          } catch {
-            // Ignore errors during release
-          }
-        },
-      };
-    } catch (error: unknown) {
-      const err = error as { code?: string };
-      if (err.code === 'EEXIST') {
-        if (attempt < maxRetries - 1) {
-          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
-          continue;
-        }
-      }
-      const lockError = new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
-      lockError.cause = error;
-      throw lockError;
-    }
-  }
-
-  throw new Error(`Failed to acquire lock for ${filePath} after ${maxRetries} attempts`);
-}
-
-function releaseLock(ctx: LockContext): void {
-  ctx.release();
-}
-
-// ─── Step 1: Check bootstrapped rules ─────────────────────────────────────
-function loadBootstrappedRules(): LedgerRule[] {
-  if (!fs.existsSync(LEDGER_PATH)) {
-    throw new Error('FAIL: principle_training_state.json not found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
-  }
-
-  const ledger: HybridLedgerStore = JSON.parse(fs.readFileSync(LEDGER_PATH, 'utf8'));
-  const bootstrappedRules = Object.values(ledger.tree.rules).filter(r =>
-    r.id.endsWith('_stub_bootstrap')
-  );
-
-  return bootstrappedRules;
-}
-
-// ─── Step 2: Build synthetic snapshot ──────────────────────────────────────
-function buildSyntheticSnapshot(taskId: string) {
-  return {
-    sessionId: `validation-${taskId}`,
-    startedAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    assistantTurns: [],
-    userTurns: [],
-    toolCalls: [],
-    painEvents: [],
-    gateBlocks: [],
-    stats: {
-      totalAssistantTurns: 0,
-      totalToolCalls: 0,
-      failureCount: 0,
-      totalPainEvents: 1,
-      totalGateBlocks: 0,
-    },
-    recentPain: [{
-      source: 'live-validation',
-      score: 50,
-      severity: 'moderate',
-      reason: 'Synthetic snapshot for live path validation',
-      createdAt: new Date().toISOString(),
-    }],
-    _dataSource: 'pain_context_fallback',
-  };
-}
-
-// ─── Step 3: Enqueue sleep_reflection task with proper file locking ──────────
-// Uses acquireLockAsync to prevent TOCTOU race conditions (T-18-01 mitigation)
-async function enqueueSleepReflectionTask(taskId: string): Promise<void> {
-  let lockCtx: LockContext | null = null;
-  try {
-    // Acquire lock before reading queue file (T-18-01 mitigation)
-    lockCtx = await acquireLockAsync(QUEUE_PATH, {
-      lockSuffix: LOCK_SUFFIX,
-      maxRetries: LOCK_MAX_RETRIES,
-      baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
-      lockStaleMs: LOCK_STALE_MS,
-    });
-
-    let queue: QueueItem[] = [];
-    if (fs.existsSync(QUEUE_PATH)) {
-      const queueContent = fs.readFileSync(QUEUE_PATH, 'utf8');
-      queue = JSON.parse(queueContent);
-    }
-
-    queue.push({
-      id: taskId,
-      taskKind: 'sleep_reflection',
-      status: 'pending',
-    });
-
-    fs.writeFileSync(QUEUE_PATH, JSON.stringify(queue, null, 2), 'utf8');
-  } finally {
-    if (lockCtx) {
-      releaseLock(lockCtx);
-    }
-  }
-}
-
-// ─── Step 4: Poll workflow store (raw SQLite, no WorkflowStore import) ─────
-// Uses better-sqlite3 directly to avoid WorkflowStore async initialization issues in standalone script
-function listNocturnalWorkflows(): WorkflowRow[] {
-  if (!fs.existsSync(DB_PATH)) {
-    return [];
-  }
-
-  const db = new Database(DB_PATH, { readonly: true });
-  const rows = db.prepare(`
-    SELECT workflow_id, workflow_type, state, metadata_json, created_at
-    FROM subagent_workflows
-    WHERE workflow_type = 'nocturnal'
-    ORDER BY created_at DESC
-  `).all() as WorkflowRow[];
-  db.close();
-  return rows;
-}
-
-// ─── Step 5: Correlate and verify ─────────────────────────────────────────
-function verifyWorkflowCompletion(taskId: string): {
-  workflowId: string;
-  state: string;
-  resolution: string;
-} | null {
-  const workflows = listNocturnalWorkflows();
-
-  for (const wf of workflows) {
-    const meta = JSON.parse(wf.metadata_json);
-    if (meta.taskId !== taskId) continue;
-    if (wf.state !== 'completed') continue;
-
-    // Read resolution from queue (resolution is on queue item, not on WorkflowRow)
-    let queue: QueueItem[] = [];
-    try {
-      if (fs.existsSync(QUEUE_PATH)) {
-        const queueContent = fs.readFileSync(QUEUE_PATH, 'utf8');
-        queue = JSON.parse(queueContent);
-      }
-    } catch {
-      // Queue file missing or corrupted — resolution unknown
-    }
-
-    const queueItem = queue.find(q => q.id === taskId);
-    const resolution = queueItem?.resolution;
-
-    return {
-      workflowId: wf.workflow_id,
-      state: wf.state,
-      resolution: resolution || 'MISSING',
-    };
-  }
-
-  return null;
-}
-
-// ─── Main ─────────────────────────────────────────────────────────────────
-async function main() {
-  const verbose = process.argv.includes('--verbose');
-
-  console.log('╔══════════════════════════════════════════════════════════╗');
-  console.log('║     Nocturnal Live Path Validation + Data Flow Monitor  ║');
-  console.log('╚══════════════════════════════════════════════════════════╝');
-  logStep('WORKSPACE', WORKSPACE_DIR);
-
-  // 0. Baseline: snapshot current state
-  logStep('BASELINE', 'Capturing current state before validation');
-  const queueBefore = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
-  logData('EVOLUTION_QUEUE (before)', queueBefore?.length ?? 0);
-  if (fs.existsSync(SAMPLES_DIR)) {
-    const samplesBefore = fs.readdirSync(SAMPLES_DIR).length;
-    logData('nocturnal/samples/', `${samplesBefore} files`);
-  } else {
-    logData('nocturnal/samples/', 'directory not present');
-  }
-  if (fs.existsSync(DB_PATH)) {
-    const wfCount = listNocturnalWorkflows().length;
-    logData('subagent_workflows.db', `${wfCount} nocturnal workflows`);
-  } else {
-    logData('subagent_workflows.db', 'not present');
-  }
-
-  // 1. Check bootstrapped rules
-  // eslint-disable-next-line @typescript-eslint/init-declarations
-  let rules: LedgerRule[];
-  try {
-    rules = loadBootstrappedRules();
-    logStep('STEP 1', `Found ${rules.length} bootstrapped rule(s)`);
-  } catch {
-    console.error('FAIL: principle_training_state.json not found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
-    process.exit(1);
-  }
-
-  if (rules.length === 0) {
-    console.error('FAIL: No _stub_bootstrap rules found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
-    process.exit(1);
-  }
-
-  if (verbose) {
-    for (const rule of rules) {
-      console.log(`  - ${rule.id} (principleId=${rule.principleId}, action=${rule.action})`);
-    }
-  }
-
-  // 2. Generate task ID
-  const taskId = `validation-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-
-  // 3. Build synthetic snapshot for validation
-  const snapshot = buildSyntheticSnapshot(taskId);
-  logStep('STEP 2', `Synthetic snapshot: sessionId=${snapshot.sessionId}`);
-  logData('snapshot.recentPain', JSON.stringify(snapshot.recentPain));
-
-  // 4. Enqueue task (with lock acquisition)
-  try {
-    await enqueueSleepReflectionTask(taskId);
-    logStep('STEP 3', `Enqueued sleep_reflection task: ${taskId}`);
-
-    // Post-enqueue: verify queue state
-    const queueAfter = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
-    const taskItem = queueAfter?.find(q => q.id === taskId);
-    logData('EVOLUTION_QUEUE (after)', `${queueAfter?.length ?? 0} tasks`);
-    logData(`task[${taskId}]`, taskItem ? JSON.stringify(taskItem) : 'NOT FOUND');
-  } catch (error: unknown) {
-    console.error('FAIL: Failed to enqueue sleep_reflection task:', String(error));
-    process.exit(1);
-  }
-
-  // 5. Poll for completion — with data flow monitoring
-  const deadline = Date.now() + POLL_TIMEOUT_MS;
-  let pollCount = 0;
-  let lastQueueStatus = 'unknown';
-  let lastWorkflowState = 'none';
-  logStep('STEP 4', `Polling for workflow completion (timeout: ${POLL_TIMEOUT_MS / 1000 / 60}min, interval: ${POLL_INTERVAL_MS / 1000}s)`);
-
-  while (Date.now() < deadline) {
-    pollCount++;
-    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
-
-    // Capture queue state
-    const queueNow = safeReadJson(QUEUE_PATH) as QueueItem[] | null;
-    const taskNow = queueNow?.find(q => q.id === taskId);
-    const currentQueueStatus = taskNow?.status ?? 'not_in_queue';
-
-    // Capture workflow DB state
-    const workflows = listNocturnalWorkflows();
-    const matchingWf = workflows.find(w => {
-      try {
-        const meta = JSON.parse(w.metadata_json);
-        return meta.taskId === taskId;
-      } catch { return false; }
-    });
-    const currentWorkflowState = matchingWf?.state ?? 'not_in_db';
-
-    // Log state changes
-    if (currentQueueStatus !== lastQueueStatus || currentWorkflowState !== lastWorkflowState) {
-      logStep(`POLL #${pollCount}`, `queue=${currentQueueStatus}, workflow=${currentWorkflowState}`);
-      if (taskNow) logData('queue item', JSON.stringify({ status: taskNow.status, resolution: taskNow.resolution }));
-      if (matchingWf) logData('workflow', JSON.stringify({ state: matchingWf.state, type: matchingWf.workflow_type }));
-      lastQueueStatus = currentQueueStatus;
-      lastWorkflowState = currentWorkflowState;
-    } else if (verbose) {
-      process.stdout.write('.');
-    }
-
-    // Check for completion
-    const result = verifyWorkflowCompletion(taskId);
-    if (result) {
-      console.log(''); // newline if dots were printed
-      logStep('STEP 5', `Workflow completed!`);
-      logData('RESULT', `workflowId=${result.workflowId} state=${result.state} resolution=${result.resolution}`);
-
-      // Check artifact persistence
-      if (fs.existsSync(SAMPLES_DIR)) {
-        const newSamples = fs.readdirSync(SAMPLES_DIR).filter(f => {
-          const stat = fs.statSync(path.join(SAMPLES_DIR, f));
-          return stat.isFile() && f.endsWith('.json') && (Date.now() - stat.mtimeMs) < 60000; // created in last minute
-        });
-        if (newSamples.length > 0) {
-          logData('new artifacts', newSamples.join(', '));
-          const firstArtifact = safeReadJson(path.join(SAMPLES_DIR, newSamples[0]));
-          if (firstArtifact) logData('artifact content (first)', JSON.stringify(firstArtifact).slice(0, 300));
-        } else {
-          logData('new artifacts', 'none created in last 60s');
-        }
-      }
-
-      if (result.resolution === 'MISSING' || result.resolution === 'expired') {
-        console.error('FAIL: resolution not explicit');
-        process.exit(1);
-      }
-
-      console.log('PASS: Live path validation successful');
-      process.exit(0);
-    }
-  }
-
-  // Timeout — dump final state for debugging
-  console.log('');
-  logStep('TIMEOUT', `Poll timeout after ${pollCount} polls (${POLL_TIMEOUT_MS / 1000 / 60}min)`);
-  logData('FINAL queue status', lastQueueStatus);
-  logData('FINAL workflow state', lastWorkflowState);
-
-  // Dump full queue for debugging
-  const finalQueue = safeReadJson(QUEUE_PATH);
-  if (finalQueue) logData('FINAL queue dump', JSON.stringify(finalQueue).slice(0, 500));
-
-  // Dump full workflow DB for debugging
-  const finalWorkflows = listNocturnalWorkflows();
-  if (finalWorkflows.length > 0) {
-    logData('FINAL workflows', finalWorkflows.map(w => `${w.workflow_id}: state=${w.state}`).join(', '));
-  }
-
-  console.error('FAIL: No completed nocturnal workflow found for taskId');
-  process.exit(1);
-}
-
-main().catch(err => {
-  console.error('FAIL:', err);
-  process.exit(1);
-});