create-principles-disciple 1.94.0 → 1.95.0

package/console/dist/server/models/IntentPageModel.d.ts

@@ -0,0 +1,18 @@
+import { type IntentDocWarning } from '@principles/core/runtime-v2';
+export interface IntentPageResult {
+    ok: boolean;
+    found: boolean;
+    flagEnabled: boolean;
+    warnings: IntentDocWarning[];
+    path?: string;
+    contentHash?: string;
+    lastEditedAt?: string;
+    sections?: Record<string, string>;
+    reason?: string;
+    nextAction?: string;
+}
+export declare class IntentPageModel {
+    private readonly workspaceDir;
+    constructor(workspaceDir: string);
+    getSummary(flagEnabled: boolean): Promise<IntentPageResult>;
+}

package/console/dist/server/models/IntentPageModel.js

@@ -0,0 +1,90 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { INTENT_MAX_BYTES, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
+const INTENT_FILENAME = 'INTENT.md';
+const INTENT_DIR = '.principles';
+export class IntentPageModel {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    async getSummary(flagEnabled) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: false,
+                warnings: [],
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+            };
+        }
+        const filePath = path.join(this.workspaceDir, INTENT_DIR, INTENT_FILENAME);
+        try {
+            if (!fs.existsSync(filePath)) {
+                return {
+                    ok: false,
+                    found: false,
+                    flagEnabled: true,
+                    warnings: [],
+                    reason: 'not_found',
+                    nextAction: 'Create .principles/INTENT.md using "pd intent init".',
+                };
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.size > INTENT_MAX_BYTES) {
+                return {
+                    ok: false,
+                    found: true,
+                    flagEnabled: true,
+                    warnings: [],
+                    reason: 'oversized',
+                    nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                };
+            }
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const sections = parseIntentDocSections(raw);
+            const warnings = validateIntentDocSections(sections);
+            const contentHash = computeIntentContentHash(raw);
+            const sectionRecord = {};
+            if (sections.why !== undefined) {
+                sectionRecord.why = sections.why;
+            }
+            if (sections.desiredOutcome !== undefined) {
+                sectionRecord.desiredOutcome = sections.desiredOutcome;
+            }
+            if (sections.nonNegotiables !== undefined) {
+                sectionRecord.nonNegotiables = sections.nonNegotiables;
+            }
+            if (sections.stopEscalation !== undefined) {
+                sectionRecord.stopEscalation = sections.stopEscalation;
+            }
+            if (sections.currentStrategicFocus !== undefined) {
+                sectionRecord.currentStrategicFocus = sections.currentStrategicFocus;
+            }
+            return {
+                ok: true,
+                found: true,
+                flagEnabled: true,
+                warnings,
+                path: filePath,
+                contentHash,
+                lastEditedAt: stat.mtime.toISOString(),
+                sections: sectionRecord,
+            };
+        }
+        catch (err) {
+            // Runtime Contract Rule #9: log underlying error for observability
+            // while preserving the never-throws contract.
+            console.error('[IntentPageModel] failed to read INTENT.md:', err);
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: true,
+                warnings: [],
+                reason: 'read_error',
+                nextAction: 'Check filesystem permissions for .principles/INTENT.md.',
+            };
+        }
+    }
+}

package/console/dist/server/models/PrinciplesConsoleModel.d.ts

@@ -77,4 +77,6 @@ export declare class PrinciplesConsoleModel {
     private loadLedger;
     listPrinciples(filter?: PrincipleFilter, decidedPrincipleIds?: Set<string>): Promise<PrinciplesListOutput>;
     getPrincipleDetail(principleId: string): Promise<PrincipleDetailOutput | null>;
+    archivePrinciple(principleId: string): Promise<boolean>;
+    unarchivePrinciple(principleId: string): Promise<boolean>;
 }

package/console/dist/server/models/PrinciplesConsoleModel.js

@@ -1,6 +1,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { classifyPrinciples, filterOwnerActionable } from './PrincipleClassifier.js';
+import { updatePrinciple } from '@principles/core/principle-tree-ledger';
 const VALID_STATUSES = ['candidate', 'active', 'archived', 'deprecated', 'probation'];
 const VALID_PRIORITIES = ['P0', 'P1', 'P2'];
 const VALID_SCOPES = ['general', 'domain'];
@@ -92,7 +93,8 @@ function readLedgerFromFile(filePath) {
             tree: parseTree(treeRaw),
         };
     }
-    catch {
+    catch (e) {
+        console.warn('PrinciplesConsoleModel: failed to parse principle_training_state.json, returning empty tree:', e);
         return { trainingStore: {}, tree: createEmptyTree() };
     }
 }
@@ -244,4 +246,38 @@ export class PrinciplesConsoleModel {
         };
         return { principle };
     }
+    async archivePrinciple(principleId) {
+        try {
+            const stateDir = path.join(this.workspaceDir, '.state');
+            updatePrinciple(stateDir, principleId, {
+                status: 'archived',
+                updatedAt: new Date().toISOString(),
+            });
+            // Clear cache to force reload
+            this.cachedLedger = null;
+            this.cacheTimestamp = 0;
+            return true;
+        }
+        catch (e) {
+            console.error(`Failed to archive principle ${principleId}:`, e);
+            return false;
+        }
+    }
+    async unarchivePrinciple(principleId) {
+        try {
+            const stateDir = path.join(this.workspaceDir, '.state');
+            updatePrinciple(stateDir, principleId, {
+                status: 'active',
+                updatedAt: new Date().toISOString(),
+            });
+            // Clear cache to force reload
+            this.cachedLedger = null;
+            this.cacheTimestamp = 0;
+            return true;
+        }
+        catch (e) {
+            console.error(`Failed to unarchive principle ${principleId}:`, e);
+            return false;
+        }
+    }
 }

package/console/dist/server/models/WorkspaceService.d.ts

@@ -1,35 +1,7 @@
 import type { WorkspaceConfigStore } from '../config/WorkspaceConfigStore.js';
 import type { SyncResult } from '../types/index.js';
-export interface CentralOverviewOutput {
-    generatedAt: string;
-    workspaceCount: number;
-    workspaces: {
-        name: string;
-        path: string;
-        status: 'healthy' | 'degraded' | 'error';
-        gfi: number;
-        principleCount: number;
-    }[];
-}
-export interface CentralHealthOutput {
-    generatedAt: string;
-    overallStatus: 'healthy' | 'degraded' | 'error';
-    workspaces: {
-        name: string;
-        status: 'healthy' | 'degraded' | 'error';
-        gfi: number;
-        activePrinciples: number;
-        pendingTasks: number;
-    }[];
-}
 export declare class WorkspaceService {
     private readonly configStore;
-    private readonly models;
     constructor(configStore: WorkspaceConfigStore);
-    getCentralOverview(): Promise<CentralOverviewOutput>;
-    getCentralHealth(): Promise<CentralHealthOutput>;
     syncWorkspace(name: string): Promise<SyncResult>;
-    dispose(): void;
-    private disposeWorkspace;
-    private getModels;
 }

package/console/dist/server/models/WorkspaceService.js

@@ -1,97 +1,13 @@
-import { OperatorHealthReadModel, PainChainReadModel, PruningReadModel, RuntimeStateManager, } from '@principles/core/runtime-v2';
-const noop = () => { };
 export class WorkspaceService {
     configStore;
-    models = new Map();
     constructor(configStore) {
         this.configStore = configStore;
     }
-    async getCentralOverview() {
-        const workspaces = this.configStore.getWorkspaces().filter(w => w.config?.enabled !== false);
-        const results = [];
-        for (const ws of workspaces) {
-            try {
-                const models = this.getModels(ws);
-                const [snapshot, pruningSummary] = await Promise.all([
-                    models.operatorHealth.getSnapshot(),
-                    Promise.resolve(models.pruning.getHealthSummary()),
-                ]);
-                const { byStatus } = pruningSummary;
-                results.push({
-                    name: ws.name,
-                    path: ws.path,
-                    status: snapshot.overallStatus === 'healthy' ? 'healthy' : snapshot.overallStatus === 'degraded' ? 'degraded' : 'error',
-                    gfi: snapshot.gfi.active?.currentGfi ?? 0,
-                    principleCount: (byStatus.active ?? 0) + (byStatus.candidate ?? 0),
-                });
-            }
-            catch {
-                results.push({
-                    name: ws.name,
-                    path: ws.path,
-                    status: 'error',
-                    gfi: -1,
-                    principleCount: 0,
-                });
-            }
-        }
-        return {
-            generatedAt: new Date().toISOString(),
-            workspaceCount: workspaces.length,
-            workspaces: results,
-        };
-    }
-    async getCentralHealth() {
-        const workspaces = this.configStore.getWorkspaces().filter(w => w.config?.enabled !== false);
-        const results = [];
-        let overallStatus = 'healthy';
-        for (const ws of workspaces) {
-            try {
-                const models = this.getModels(ws);
-                const [snapshot, pruningSummary, pendingTasks] = await Promise.all([
-                    models.operatorHealth.getSnapshot(),
-                    Promise.resolve(models.pruning.getHealthSummary()),
-                    models.runtime.listTasks({ status: 'pending', limit: 100 }),
-                ]);
-                const { byStatus } = pruningSummary;
-                const wsStatus = snapshot.overallStatus === 'healthy' ? 'healthy' : snapshot.overallStatus === 'degraded' ? 'degraded' : 'error';
-                if (wsStatus === 'error') {
-                    overallStatus = 'error';
-                }
-                else if (wsStatus !== 'healthy' && overallStatus === 'healthy') {
-                    overallStatus = 'degraded';
-                }
-                results.push({
-                    name: ws.name,
-                    status: wsStatus,
-                    gfi: snapshot.gfi.active?.currentGfi ?? 0,
-                    activePrinciples: (byStatus.active ?? 0) + (byStatus.candidate ?? 0),
-                    pendingTasks: pendingTasks.length,
-                });
-            }
-            catch {
-                overallStatus = 'error';
-                results.push({
-                    name: ws.name,
-                    status: 'error',
-                    gfi: -1,
-                    activePrinciples: 0,
-                    pendingTasks: 0,
-                });
-            }
-        }
-        return {
-            generatedAt: new Date().toISOString(),
-            overallStatus,
-            workspaces: results,
-        };
-    }
     async syncWorkspace(name) {
         const entry = this.configStore.getWorkspace(name);
         if (!entry) {
             throw new Error(`Workspace "${name}" not found`);
         }
-        this.disposeWorkspace(name);
         this.configStore.updateSyncTime(name);
         return {
             success: true,
@@ -99,35 +15,4 @@ export class WorkspaceService {
             items: {},
         };
     }
-    dispose() {
-        for (const name of this.models.keys()) {
-            this.disposeWorkspace(name);
-        }
-        this.models.clear();
-    }
-    disposeWorkspace(name) {
-        const existing = this.models.get(name);
-        if (existing) {
-            existing.operatorHealth.close().catch(noop);
-            existing.painChain.close().catch(noop);
-            existing.runtime.close().catch(noop);
-            this.models.delete(name);
-        }
-    }
-    getModels(entry) {
-        let existing = this.models.get(entry.name);
-        if (!existing) {
-            const runtime = new RuntimeStateManager({ workspaceDir: entry.path });
-            const painChain = new PainChainReadModel({ workspaceDir: entry.path, stateManager: runtime });
-            const pruning = new PruningReadModel({ workspaceDir: entry.path });
-            const operatorHealth = new OperatorHealthReadModel({
-                workspaceDir: entry.path,
-                painChainReadModel: painChain,
-                pruningReadModel: pruning,
-            });
-            existing = { operatorHealth, painChain, pruning, runtime };
-            this.models.set(entry.name, existing);
-        }
-        return existing;
-    }
 }

package/console/dist/server/routes/config.js

@@ -21,7 +21,7 @@
  * - ERR-045: ANY-segment redaction for sensitive keys
  */
 import { sendSuccess, sendError, sendNotFound, sendMethodNotAllowed, sendBadRequest } from '../utils/response.js';
-import { getConfigSummary, getConfigCatalog, updateAgentBinding, updateDefaultRuntime, checkReadiness, getPrinciplesOutputLanguage, updatePrinciplesOutputLanguage, } from '../config/pd-config-store.js';
+import { getConfigSummary, getConfigCatalog, updateAgentBinding, updateDefaultRuntime, checkReadiness, getPrinciplesOutputLanguage, updatePrinciplesOutputLanguage, updateFeatureFlag, } from '../config/pd-config-store.js';
 // ── Constants ────────────────────────────────────────────────────────────────
 const MAX_BODY_SIZE = 1024 * 64; // 64 KB — generous for config binding updates
 // ── Request Body Reader ──────────────────────────────────────────────────────
@@ -49,6 +49,10 @@ function safeParseBody(text) {
         return null;
     }
 }
+/** Type guard: is `value` a plain Record<string, unknown>? (ERR-001) */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 // ── Route Handler ────────────────────────────────────────────────────────────
 export async function handleConfigRoute(req, res, ctx) {
     const { workspaceDir, subPath } = ctx;
@@ -170,6 +174,56 @@ export async function handleConfigRoute(req, res, ctx) {
         });
         return;
     }
+    // PATCH /features/:featureName — spec 2026-06-27 §13.4
+    // Toggles a registered feature flag's `enabled` field in .pd/config.yaml.
+    const featureFlagMatch = /^\/features\/([^/]+)$/.exec(subPath);
+    if (featureFlagMatch) {
+        if (method !== 'PATCH') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        let featureName;
+        try {
+            featureName = decodeURIComponent(featureFlagMatch[1] ?? '');
+        }
+        catch {
+            sendBadRequest(res, 'Invalid feature name encoding');
+            return;
+        }
+        let bodyText;
+        try {
+            bodyText = await readBody(req);
+        }
+        catch {
+            sendBadRequest(res, 'Request body exceeds maximum allowed size');
+            return;
+        }
+        const body = safeParseBody(bodyText);
+        if (body === null) {
+            sendBadRequest(res, 'Invalid JSON body');
+            return;
+        }
+        // Validate body shape: { enabled: boolean } (ERR-001: no `as` bypass)
+        if (!isObject(body)) {
+            sendBadRequest(res, 'Body must be a JSON object with an enabled field');
+            return;
+        }
+        if (!Object.hasOwn(body, 'enabled')) {
+            sendBadRequest(res, 'Missing required field: enabled');
+            return;
+        }
+        if (typeof body.enabled !== 'boolean') {
+            sendBadRequest(res, 'enabled must be a boolean');
+            return;
+        }
+        const result = updateFeatureFlag(workspaceDir, featureName, body.enabled);
+        if (!result.ok) {
+            sendError(res, result.statusCode, result.error, result.message);
+            return;
+        }
+        sendSuccess(res, { feature: result.feature, enabled: result.enabled });
+        return;
+    }
     // GET/PATCH /principles/output-language — PRI-332 P1-1
     if (subPath === '/principles/output-language') {
         if (method === 'GET') {

package/console/dist/server/routes/intent-decisions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * IntentDecisions route — HTTP surface for IntentDecisionRecord (PRI-470, SPEC §21.7).
+ *
+ * Endpoints (all gated by the `intent_engineering` feature flag):
+ * - POST   /api/v1/intent-decisions                       → create (201) or idempotent replay (200)
+ * - GET    /api/v1/intent-decisions?painId=…              → list by painId
+ * - GET    /api/v1/intent-decisions?taskId=…              → list by taskId
+ * - GET    /api/v1/intent-decisions/summary               → tallied summary (MUST precede /:id)
+ * - GET    /api/v1/intent-decisions/:id                   → single record
+ * - POST   /api/v1/intent-decisions/:id/follow-up         → dispatch governed follow-up (PRI-471)
+ *
+ * PRI-471 follow-up types (SPEC §22.1.4):
+ * - link_candidate         — record which existing principle candidate the Owner
+ *                            chose to link. Does NOT create a candidate.
+ * - guide_rulehost         — returns the CLI guidance for promoting to RuleHost.
+ *                            Does NOT create a rule or approval directly.
+ * - generate_patch_proposal — generates a read-only Intent Patch Proposal and
+ *                            records its id on the decision. Does NOT modify
+ *                            `.principles/INTENT.md`.
+ *
+ * Runtime Contract rules applied:
+ * - Rule 1: parsed JSON body treated as `unknown` (ERR-001)
+ * - Rule 2: enum fields validated via core type guards, never `as` (ERR-001/ERR-005)
+ * - Rule 3: required fields fail loud → 400 with reason (ERR-009/ERR-010)
+ * - Rule 5: `Object.hasOwn()` for untrusted object keys (ERR-013)
+ * - Rule 9: every degraded path carries reason + nextAction (ERR-002)
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare function handleIntentDecisionsRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string, subPath: string): Promise<void>;
+/**
+ * Dispose hook for graceful shutdown — clears the per-workspace model cache.
+ */
+export declare function disposeIntentDecisionModels(): void;