create-principles-disciple 1.104.0 → 1.104.2

package/plugin/dist/core/hygiene/tracker.js

@@ -1,110 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { createEmptyHygieneStats } from '../../types/hygiene-types.js';
-import { atomicWriteFileSync } from '../../utils/io.js';
-/**
- * HygieneTracker - Tracks agent behavior regarding workspace organization and persistence.
- */
-export class HygieneTracker {
-    statsFile;
-    currentStats;
-    logger;
-    constructor(stateDir, logger) {
-        this.statsFile = path.join(stateDir, 'hygiene-stats.json');
-        this.logger = logger;
-        // Ensure state directory exists
-        if (!fs.existsSync(stateDir)) {
-            try {
-                fs.mkdirSync(stateDir, { recursive: true });
-            }
-            catch (e) {
-                this.logger?.error(`[PD] Failed to create state directory ${stateDir}: ${String(e)}`);
-            }
-        }
-        this.currentStats = this.loadStats();
-    }
-    loadStats() {
-        const today = new Date().toISOString().split('T')[0] ?? '';
-        if (fs.existsSync(this.statsFile)) {
-            try {
-                const content = fs.readFileSync(this.statsFile, 'utf-8');
-                if (content.trim()) {
-                    const allStats = JSON.parse(content);
-                    if (allStats[today]) {
-                        return allStats[today];
-                    }
-                }
-            }
-            catch (e) {
-                this.logger?.error(`[PD] Failed to load/parse hygiene-stats.json: ${String(e)}`);
-                // If file is corrupted, we might want to back it up and start fresh
-                try {
-                    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 -- Reason: catch parameter intentionally unused - error handling only
-                }
-                catch (_renameErr) {
-                    // Empty - corrupted stats backup is non-fatal
-                }
-            }
-        }
-        return createEmptyHygieneStats(today);
-    }
-    saveStats() {
-        let allStats = {};
-        // Check if we need to rotate date (reset currentStats if date changed)
-        const today = new Date().toISOString().split('T')[0] ?? '';
-        if (this.currentStats.date !== today) {
-            this.currentStats = createEmptyHygieneStats(today);
-        }
-        if (fs.existsSync(this.statsFile)) {
-            try {
-                const content = fs.readFileSync(this.statsFile, 'utf-8');
-                if (content.trim()) {
-                    allStats = JSON.parse(content);
-                }
-            }
-            catch (e) {
-                this.logger?.error(`[PD] Failed to parse hygiene-stats.json for saving: ${String(e)}`);
-            }
-        }
-        allStats[this.currentStats.date] = this.currentStats;
-        try {
-            // Use a temporary file for atomic write if possible, or simple write
-            atomicWriteFileSync(this.statsFile, JSON.stringify(allStats, null, 2));
-        }
-        catch (e) {
-            this.logger?.error(`[PD] Failed to write hygiene-stats.json: ${String(e)}`);
-        }
-    }
-    /**
-     * Records a persistence action (writing to memory or plan).
-     */
-    recordPersistence(action) {
-        this.currentStats.persistenceCount++;
-        this.currentStats.lastPersistenceTime = action.ts;
-        this.currentStats.totalCharsPersisted += action.contentLength;
-        const fileName = path.basename(action.path);
-        this.currentStats.persistenceByFile[fileName] = (this.currentStats.persistenceByFile[fileName] || 0) + 1;
-        this.saveStats();
-        this.logger?.info(`[PD] Hygiene: Persisted state to ${fileName} (${action.contentLength} chars)`);
-    }
-    /**
-     * Records a grooming action (cleaning up the workspace).
-     */
-    recordGrooming() {
-        this.currentStats.groomingExecutedCount++;
-        this.currentStats.lastGroomingTime = new Date().toISOString();
-        this.saveStats();
-        this.logger?.info(`[PD] Hygiene: Workspace grooming executed.`);
-    }
-    getStats() {
-        // Check for date change on every get
-        const today = new Date().toISOString().split('T')[0] ?? '';
-        if (this.currentStats.date !== today) {
-            this.currentStats = createEmptyHygieneStats(today);
-        }
-        return this.currentStats;
-    }
-}

package/plugin/dist/core/init.js

@@ -1,254 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { PD_DIRS } from './paths.js';
-import { loadStore, setPrincipleState } from './principle-training-state.js';
-import { addPrincipleToLedger } from './principle-tree-ledger.js';
-import { atomicWriteFileSync } from '../utils/io.js';
-import { createDefaultKeywordStore, saveKeywordStore } from './empathy-keyword-matcher.js';
-import { CORE_PRINCIPLES } from '@principles/core/runtime-v2';
-/**
- * Default PROFILE.json content
- * Note: contextInjection is migrated to .pd/config.yaml — not initialized here.
- */
-const DEFAULT_PROFILE = {
-    name: "Principles Disciple Agent",
-    version: "1.0.0",
-};
-const CORE_GUIDANCE_VERSION = 'pd-core-guidance-v2';
-const CORE_GUIDANCE_FILES = new Set(['AGENTS.md', 'TOOLS.md']);
-function getCoreGuidanceVersionMarker() {
-    return `pd-core-guidance-version: ${CORE_GUIDANCE_VERSION}`;
-}
-function hasOutdatedCoreGuidance(file, content) {
-    if (!CORE_GUIDANCE_FILES.has(file))
-        return false;
-    if (content.includes(getCoreGuidanceVersionMarker()))
-        return false;
-    if (content.includes('pd_spawn_agent'))
-        return true;
-    if (!content.includes('subagents'))
-        return true;
-    if (!content.includes('sessions_spawn'))
-        return true;
-    return false;
-}
-/**
- * Ensures that the workspace has the necessary template files for Principles Disciple.
- * This function flattens 'core' templates to the root so OpenClaw can find them.
- */
-export function ensureWorkspaceTemplates(api, workspaceDir, language = 'en') {
-    try {
-        const __filename = fileURLToPath(import.meta.url);
-        const __dirname = path.dirname(__filename);
-        // 1. Copy common workspace templates (e.g., docs/*)
-        const commonTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'workspace');
-        if (fs.existsSync(commonTemplatesDir)) {
-            api.logger.info(`[PD] Syncing workspace templates: ${workspaceDir}...`);
-            copyRecursiveSync(commonTemplatesDir, workspaceDir, api);
-        }
-        // 2. Copy language-specific core templates (AGENTS.md, SOUL.md, etc.)
-        // CRITICAL: These MUST be at the root of the workspace for OpenClaw to recognize them.
-        let coreTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'core');
-        if (!fs.existsSync(coreTemplatesDir)) {
-            coreTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', 'zh', 'core');
-        }
-        if (fs.existsSync(coreTemplatesDir)) {
-            api.logger.info(`[PD] Flattening ${language} core templates to workspace root...`);
-            // We copy contents of 'core' directory directly to workspaceDir root
-            const coreFiles = fs.readdirSync(coreTemplatesDir);
-            for (const file of coreFiles) {
-                const srcPath = path.join(coreTemplatesDir, file);
-                const destPath = path.join(workspaceDir, file);
-                // If it's a core file and we want to ensure latest templates are used
-                // but don't want to destroy user custom data, we check if we should overwrite.
-                // For now, we only copy if missing to be safe, but log it.
-                if (!fs.existsSync(destPath)) {
-                    fs.copyFileSync(srcPath, destPath);
-                    api.logger.info(`[PD] Initialized core file: ${file}`);
-                }
-                else if (CORE_GUIDANCE_FILES.has(file)) {
-                    const existingContent = fs.readFileSync(destPath, 'utf8');
-                    if (hasOutdatedCoreGuidance(file, existingContent)) {
-                        api.logger.warn(`[PD] Outdated core guidance detected in ${file}. Review the latest template guidance for peer sessions, subagents, and sessions_spawn routing.`);
-                    }
-                }
-            }
-        }
-        // 3. Copy pain memory seed files
-        const painTemplatesDir = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'pain');
-        const painDestDir = path.join(workspaceDir, PD_DIRS.PAIN_SAMPLES);
-        if (fs.existsSync(painTemplatesDir)) {
-            if (!fs.existsSync(painDestDir)) {
-                fs.mkdirSync(painDestDir, { recursive: true });
-            }
-            copyRecursiveSync(painTemplatesDir, painDestDir, api);
-        }
-        // 4. Initialize PROFILE.json with project identity metadata
-        const principlesDir = path.join(workspaceDir, PD_DIRS.IDENTITY);
-        const profilePath = path.join(principlesDir, 'PROFILE.json');
-        if (!fs.existsSync(profilePath)) {
-            // Ensure .principles directory exists
-            if (!fs.existsSync(principlesDir)) {
-                fs.mkdirSync(principlesDir, { recursive: true });
-            }
-            atomicWriteFileSync(profilePath, JSON.stringify(DEFAULT_PROFILE, null, 2));
-            api.logger.info(`[PD] Initialized PROFILE.json with identity metadata (contextInjection migrated to .pd/config.yaml)`);
-        }
-    }
-    catch (err) {
-        api.logger.error(`[PD] Failed to initialize workspace templates: ${String(err)}`);
-    }
-}
-/**
- * Standard recursive copy that preserves directory structure.
- * Special handling: maps 'okr' directory to 'memory/okr' for runtime compatibility.
- */
-function copyRecursiveSync(srcDir, destDir, api) {
-    const items = fs.readdirSync(srcDir);
-    for (const item of items) {
-        const srcPath = path.join(srcDir, item);
-        // Special mapping: okr -> memory/okr (runtime path expects memory/okr/)
-        const destItemName = item === 'okr' ? path.join('memory', 'okr') : item;
-        const destPath = path.join(destDir, destItemName);
-        const stat = fs.statSync(srcPath);
-        if (stat.isDirectory()) {
-            if (!fs.existsSync(destPath)) {
-                fs.mkdirSync(destPath, { recursive: true });
-            }
-            copyRecursiveSync(srcPath, destPath, api);
-        }
-        else {
-            if (!fs.existsSync(destPath)) {
-                // Ensure parent directory exists
-                const destParent = path.dirname(destPath);
-                if (!fs.existsSync(destParent)) {
-                    fs.mkdirSync(destParent, { recursive: true });
-                }
-                fs.copyFileSync(srcPath, destPath);
-                api.logger.info(`[PD] Copied: ${destItemName}`);
-            }
-        }
-    }
-}
-/**
- * Core thinking model definitions (T-01 through T-10).
- * Derived from the Core Principle Registry — the single source of truth.
- */
-export const CORE_THINKING_MODELS = CORE_PRINCIPLES.map(p => ({
-    id: p.id,
-    name: p.name,
-    description: p.statement,
-}));
-/**
- * Initialize core thinking models into the training store if it's empty.
- * This ensures every workspace has evaluable principles for nocturnal reflection.
- *
- * @param stateDir - State directory path
- * @param logger - Plugin logger
- * @returns true if initialization was performed, false if already had principles
- */
-export function ensureCorePrinciples(stateDir, logger) {
-    try {
-        const store = loadStore(stateDir);
-        const existingIds = Object.keys(store).filter(k => k !== '_tree');
-        // If already has principles, skip initialization
-        if (existingIds.length > 0) {
-            return false;
-        }
-        logger.info(`[PD] Initializing core thinking models (${CORE_THINKING_MODELS.length} principles) into training store`);
-        for (const model of CORE_THINKING_MODELS) {
-            const state = {
-                principleId: model.id,
-                evaluability: 'deterministic',
-                applicableOpportunityCount: 0,
-                observedViolationCount: 0,
-                complianceRate: 0,
-                violationTrend: 0,
-                generatedSampleCount: 0,
-                approvedSampleCount: 0,
-                includedTrainRunIds: [],
-                deployedCheckpointIds: [],
-                internalizationStatus: 'needs_training',
-            };
-            setPrincipleState(stateDir, state);
-            // Also write to Ledger Tree so bootstrapRules() can find them
-            const now = new Date().toISOString();
-            const ledgerPrinciple = {
-                id: model.id,
-                version: 1,
-                text: model.description,
-                coreAxiomId: model.id,
-                triggerPattern: '',
-                action: '',
-                status: 'active',
-                priority: 'P1',
-                scope: 'general',
-                evaluability: 'deterministic',
-                valueScore: 0,
-                adherenceRate: 0,
-                painPreventedCount: 0,
-                derivedFromPainIds: [],
-                ruleIds: [],
-                conflictsWithPrincipleIds: [],
-                createdAt: now,
-                updatedAt: now,
-                suggestedRules: [],
-            };
-            addPrincipleToLedger(stateDir, ledgerPrinciple);
-        }
-        const firstId = CORE_THINKING_MODELS[0]?.id ?? 'T-01';
-        const lastId = CORE_THINKING_MODELS[CORE_THINKING_MODELS.length - 1]?.id ?? 'T-10';
-        logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: ${firstId} through ${lastId}`);
-        return true;
-    }
-    catch (err) {
-        logger.error(`[PD] Failed to initialize core principles: ${String(err)}`);
-        return false;
-    }
-}
-/**
- * Ensures that the state directory has the necessary files (like pain_dictionary.json).
- */
-export function ensureStateTemplates(ctx, stateDir, language = 'en') {
-    try {
-        const __filename = fileURLToPath(import.meta.url);
-        const __dirname = path.dirname(__filename);
-        if (!fs.existsSync(stateDir)) {
-            fs.mkdirSync(stateDir, { recursive: true });
-        }
-        // 1. Copy common state files
-        const commonFiles = ['pain_settings.json'];
-        for (const filename of commonFiles) {
-            const templatePath = path.resolve(__dirname, '..', '..', 'templates', filename);
-            const destPath = path.join(stateDir, filename);
-            if (!fs.existsSync(destPath) && fs.existsSync(templatePath)) {
-                fs.copyFileSync(templatePath, destPath);
-                ctx.logger.info(`[PD] Initialized ${filename} in stateDir: ${destPath}`);
-            }
-        }
-        // 2. Copy language-specific dictionary
-        let dictTemplate = path.resolve(__dirname, '..', '..', 'templates', 'langs', language, 'pain_dictionary.json');
-        if (!fs.existsSync(dictTemplate)) {
-            dictTemplate = path.resolve(__dirname, '..', '..', 'templates', 'langs', 'en', 'pain_dictionary.json');
-        }
-        const dictDest = path.join(stateDir, 'pain_dictionary.json');
-        if (!fs.existsSync(dictDest) && fs.existsSync(dictTemplate)) {
-            fs.copyFileSync(dictTemplate, dictDest);
-            ctx.logger.info(`[PD] Initialized pain dictionary in stateDir: ${dictDest} (Lang: ${language})`);
-        }
-        // 3. Initialize empathy keyword store for new users
-        // loadKeywordStore() creates the file if missing, but we call it explicitly
-        // here so the file exists before any agent/workflow tries to read it
-        const empathyFile = path.join(stateDir, 'empathy_keywords.json');
-        if (!fs.existsSync(empathyFile)) {
-            const lang = language === 'zh' || language === 'en' ? language : 'en';
-            const store = createDefaultKeywordStore(lang);
-            saveKeywordStore(stateDir, store);
-            ctx.logger.info(`[PD] Initialized empathy keyword store in stateDir: ${empathyFile}`);
-        }
-    }
-    catch (err) {
-        ctx.logger.error(`[PD] Failed to initialize state templates: ${String(err)}`);
-    }
-}

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

@@ -1,76 +0,0 @@
-/**
- * PRI-468 — Plugin adapter implementing the core `IntentDocReader` port.
- *
- * Bridges the plugin-owned `safeReadIntentDoc()` I/O function to the
- * core-owned `IntentDocReader` interface so Stage A (in core) can read
- * INTENT.md without core performing any filesystem I/O.
- *
- * This adapter only MAPS types — it adds no new I/O, no new flag checks,
- * and no new telemetry. The underlying `safeReadIntentDoc()` already
- * performs the flag-first check (SPEC §12), TTL+mtime cache, and size cap.
- *
- * ERR checklist:
- *   EP-01 / ERR-001: never `as` — field-by-field mapping with typeof checks
- *   EP-02 / ERR-025: plugin I/O file, whitelisted in architecture-regression
- *   EP-03 / ERR-002: every degraded path flows through with reason + nextAction
- *
- * Architecture: this file is I/O (delegates to fs-reading safeReadIntentDoc).
- * It will be added to KNOWN_PLUGIN_CORE_FILES in architecture-regression.test.ts.
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { safeReadIntentDoc } from './intent-doc-reader.js';
-import { getIntentFilename, } from '@principles/core/runtime-v2';
-const INTENT_DIR = '.principles';
-/**
- * Detect which language's INTENT file exists on disk.
- * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
- *
- * This lets hooks avoid hardcoding a single language — the Owner may have
- * created either INTENT.zh-CN.md or INTENT.en.md.
- */
-export function resolveIntentLang(workspaceDir) {
-    const zhPath = path.join(workspaceDir, INTENT_DIR, getIntentFilename('zh-CN'));
-    if (fs.existsSync(zhPath))
-        return 'zh-CN';
-    const enPath = path.join(workspaceDir, INTENT_DIR, getIntentFilename('en'));
-    if (fs.existsSync(enPath))
-        return 'en';
-    return 'zh-CN';
-}
-/**
- * Create an IntentDocReader bound to a specific workspace and language.
- *
- * The returned reader is stateless beyond the (workspace, lang) binding — each
- * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
- * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
- */
-export function createIntentDocReader(workspaceDir, lang) {
-    return {
-        readIntentDoc() {
-            const result = safeReadIntentDoc(workspaceDir, lang);
-            if (result.ok && result.doc) {
-                const doc = result.doc;
-                const reference = {
-                    raw: typeof doc.raw === 'string' ? doc.raw : '',
-                    contentHash: typeof doc.contentHash === 'string' ? doc.contentHash : '',
-                    path: typeof doc.path === 'string' ? doc.path : '',
-                };
-                return {
-                    ok: true,
-                    found: true,
-                    flagEnabled: true,
-                    doc: reference,
-                };
-            }
-            // Degraded path — preserve structured reason + nextAction (EP-03 / ERR-002)
-            return {
-                ok: false,
-                found: result.found,
-                flagEnabled: result.flagEnabled,
-                reason: result.reason,
-                nextAction: result.nextAction,
-            };
-        },
-    };
-}

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

@@ -1,210 +0,0 @@
-/**
- * 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, getIntentFilename, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
-import { loadFeatureFlagFromConfig } from './pd-config-loader.js';
-// ── Constants ────────────────────────────────────────────────────────────────
-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.
- *
- * - No args: clear the whole cache.
- * - workspaceDir only: delete all entries for that workspace (any lang).
- *   Keys are formatted as `${workspaceDir}:${lang}`, so we match by prefix.
- * - workspaceDir + lang: delete the single `${workspaceDir}:${lang}` entry.
- *
- * Note: prompt.ts resetPromptStateForTest passes workspaceDir only — the
- * previous signature treated it as a literal cache key, which never matched
- * the `${workspaceDir}:${lang}` format and silently left entries behind.
- */
-export function resetIntentDocCacheForTest(workspaceDir, lang) {
-    if (workspaceDir === undefined) {
-        _intentDocCache.clear();
-        return;
-    }
-    if (lang !== undefined) {
-        _intentDocCache.delete(`${workspaceDir}:${lang}`);
-        return;
-    }
-    // workspaceDir only — clear all langs for this workspace by prefix.
-    const prefix = `${workspaceDir}:`;
-    for (const key of _intentDocCache.keys()) {
-        if (key.startsWith(prefix)) {
-            _intentDocCache.delete(key);
-        }
-    }
-}
-// ── Helpers ──────────────────────────────────────────────────────────────────
-function getIntentFilePath(workspaceDir, lang) {
-    return path.join(workspaceDir, INTENT_DIR, getIntentFilename(lang));
-}
-function getCacheKey(workspaceDir, lang) {
-    return `${workspaceDir}:${lang}`;
-}
-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 lang - Mandatory language code ('zh-CN' | 'en'); selects INTENT.${lang}.md
- * @param options - Optional logger for debug-level diagnostics
- * @returns SafeReadIntentDocResult (never throws)
- */
-export function safeReadIntentDoc(workspaceDir, lang, 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 ${getIntentFilename(lang)}.`,
-            warnings: [],
-        };
-    }
-    const cacheKey = getCacheKey(workspaceDir, lang);
-    const filePath = getIntentFilePath(workspaceDir, lang);
-    const now = Date.now();
-    // Check cache freshness (TTL + mtime)
-    const cached = _intentDocCache.get(cacheKey);
-    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(cacheKey);
-            return {
-                ok: false,
-                found: false,
-                flagEnabled: true,
-                reason: 'not_found',
-                nextAction: `Create .principles/${getIntentFilename(lang)} using "pd intent init".`,
-                warnings: [],
-            };
-        }
-        const stat = fs.statSync(filePath);
-        // SPEC §12 — 32KB size cap
-        if (stat.size > INTENT_MAX_BYTES) {
-            _intentDocCache.delete(cacheKey);
-            return {
-                ok: false,
-                found: true,
-                flagEnabled: true,
-                reason: 'oversized',
-                nextAction: `${getIntentFilename(lang)} 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(cacheKey);
-            return {
-                ok: false,
-                found: true,
-                flagEnabled: true,
-                reason: 'oversized',
-                nextAction: `${getIntentFilename(lang)} 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(cacheKey, {
-            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(cacheKey);
-        const message = err instanceof Error ? err.message : String(err);
-        options?.logger?.warn?.(`[PD:Intent] safeReadIntentDoc failed: workspace=${workspaceDir}, lang=${lang}, error=${message}`);
-        return {
-            ok: false,
-            found: false,
-            flagEnabled: true,
-            reason: 'read_error',
-            nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
-            warnings: [],
-        };
-    }
-}