principles-disciple 1.31.0 → 1.33.0

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.31.0",
+  "version": "1.33.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.31.0",
+  "version": "1.33.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/core/correction-cue-learner.ts

@@ -0,0 +1,203 @@
+/**
+ * Correction Cue Learner
+ *
+ * Persistent, learnable keyword store for correction cue detection.
+ * Replaces the hardcoded cue list in detectCorrectionCue() with a
+ * crash-safe JSON store that can grow over time.
+ *
+ * Persistence contract:
+ *   - Atomic write: temp-file-then-rename (T-38-02)
+ *   - Cache invalidated after every write (D-05)
+ *   - 200-term hard cap enforced before any write (T-38-01)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  CorrectionKeyword,
+  CorrectionKeywordStore,
+  CorrectionMatchResult,
+  CORRECTION_SEED_KEYWORDS,
+  MAX_CORRECTION_KEYWORDS,
+} from './correction-types.js';
+
+const KEYWORD_STORE_FILE = 'correction_keywords.json';
+
+// =========================================================================
+// Module-level cache (D-04, D-05)
+// =========================================================================
+
+/**
+ * Invalidated on every successful save so the next load re-reads from disk.
+ * Set to null intentionally — never assume disk and memory are in sync after a write.
+ */
+let _correctionCueCache: CorrectionKeywordStore | null = null;
+
+/**
+ * Resets the module-level cache (for testing only).
+ * @internal
+ */
+export function _resetCorrectionCueCache(): void {
+  _correctionCueCache = null;
+}
+
+// =========================================================================
+// Default store factory
+// =========================================================================
+
+/**
+ * Creates a fresh store populated with the 16 seed keywords (D-08, D-09).
+ * addedAt is stamped with the current ISO timestamp.
+ */
+function createDefaultStore(): CorrectionKeywordStore {
+  const now = new Date().toISOString();
+  const keywords: CorrectionKeyword[] = CORRECTION_SEED_KEYWORDS.map((k) => ({
+    ...k,
+    source: 'seed' as const,
+    addedAt: now,
+  }));
+  return { keywords, version: 1, lastOptimizedAt: now };
+}
+
+// =========================================================================
+// Load / save
+// =========================================================================
+
+/**
+ * Loads the keyword store from disk.
+ * On first run (file absent) or parse failure, creates and persists the default store.
+ */
+export function loadCorrectionKeywordStore(stateDir: string): CorrectionKeywordStore {
+  if (_correctionCueCache) return _correctionCueCache;
+
+  const filePath = path.join(stateDir, KEYWORD_STORE_FILE);
+
+  if (fs.existsSync(filePath)) {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      _correctionCueCache = JSON.parse(raw) as CorrectionKeywordStore;
+      return _correctionCueCache;
+    } catch {
+      // Parse failure — fall through to default
+    }
+  }
+
+  // File absent or corrupt: seed the store and persist it (D-01)
+  const defaultStore = createDefaultStore();
+  saveCorrectionKeywordStore(stateDir, defaultStore);
+  _correctionCueCache = defaultStore;
+  return _correctionCueCache;
+}
+
+/**
+ * Atomically saves the keyword store to disk (D-03, T-38-02).
+ * Uses temp-file-then-rename to ensure the file is always valid JSON or
+ * the previous valid state if a crash occurs mid-write.
+ * MUST invalidate the cache after the rename (D-05).
+ */
+export function saveCorrectionKeywordStore(
+  stateDir: string,
+  store: CorrectionKeywordStore
+): void {
+  const filePath = path.join(stateDir, KEYWORD_STORE_FILE);
+  const tmpPath = filePath + '.tmp';
+
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(tmpPath, JSON.stringify(store, null, 2), 'utf-8');
+  fs.renameSync(tmpPath, filePath);
+
+  // Invalidate cache so the next read re-loads from disk (D-05)
+  _correctionCueCache = null;
+}
+
+// =========================================================================
+// Singleton state
+// =========================================================================
+
+let _instance: CorrectionCueLearner | null = null;
+let _lastStateDir: string | null = null;
+
+/** Resets singleton state (for testing only). @internal */
+export function _resetCorrectionCueLearnerInstance(): void {
+  _instance = null;
+  _lastStateDir = null;
+}
+
+// =========================================================================
+// CorrectionCueLearner class
+// =========================================================================
+
+export class CorrectionCueLearner {
+  private store: CorrectionKeywordStore;
+  private stateDir: string;
+
+  constructor(stateDir: string) {
+    this.stateDir = stateDir;
+    this.store = loadCorrectionKeywordStore(stateDir);
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Checks whether text contains a correction cue (D-11).
+   * Normalisation is equivalent to the original detectCorrectionCue():
+   *   trim → lowercase → strip punctuation
+   * Returns the first matched term only (first-match semantics).
+   */
+  match(text: string): CorrectionMatchResult {
+    const normalized = text
+      .trim()
+      .toLowerCase()
+      .replace(/[.,!?;:，。！？；：]/g, '');
+
+    for (const keyword of this.store.keywords) {
+      if (normalized.includes(keyword.term.toLowerCase())) {
+        return { matched: true, matchedTerms: [keyword.term], score: keyword.weight, confidence: 0.9 };
+      }
+    }
+
+    return { matched: false, matchedTerms: [], score: 0.0, confidence: 0.0 };
+  }
+
+  /**
+   * Adds a new keyword to the store and immediately flushes (D-06, D-07).
+   * Throws if the 200-term limit would be exceeded.
+   */
+  add(keyword: Omit<CorrectionKeyword, 'addedAt'>): void {
+    if (this.store.keywords.length >= MAX_CORRECTION_KEYWORDS) {
+      throw new Error('Correction keyword store limit reached (200 terms)');
+    }
+
+    const entry: CorrectionKeyword = {
+      ...keyword,
+      addedAt: new Date().toISOString(),
+    };
+
+    this.store.keywords.push(entry);
+    this.flush();
+  }
+
+  /** Returns a reference to the in-memory store. */
+  getStore(): CorrectionKeywordStore {
+    return this.store;
+  }
+
+  /** Persists the current in-memory store to disk atomically. */
+  flush(): void {
+    saveCorrectionKeywordStore(this.stateDir, this.store);
+  }
+
+  // ── Singleton factory ───────────────────────────────────────────────────
+
+  /**
+   * Returns the shared CorrectionCueLearner instance for a given stateDir.
+   * Re-creates the instance if stateDir changes (e.g. workspace switch).
+   */
+  static get(stateDir: string): CorrectionCueLearner {
+    if (!_instance || _lastStateDir !== stateDir) {
+      _instance = new CorrectionCueLearner(stateDir);
+      _lastStateDir = stateDir;
+    }
+    return _instance;
+  }
+}

package/src/core/correction-types.ts

@@ -0,0 +1,88 @@
+/**
+ * Correction Cue Keyword Types
+ *
+ * Types for the dynamic correction cue detection system.
+ * Replaces the previous hardcoded cue list in detectCorrectionCue()
+ * with a persistent, learnable keyword store.
+ */
+
+// =========================================================================
+// Keyword Store
+// =========================================================================
+
+export interface CorrectionKeyword {
+  /** The keyword term to match against normalized user text */
+  term: string;
+  /** Contribution weight (0-1) */
+  weight: number;
+  /** How this keyword was introduced */
+  source: 'seed' | 'llm' | 'user';
+  /** ISO 8601 timestamp of when this keyword was added */
+  addedAt: string;
+  /** Total times this keyword has matched (default: 0) */
+  hitCount?: number;
+  /** Confirmed correct matches (default: 0) */
+  truePositiveCount?: number;
+  /** Confirmed incorrect matches (default: 0) */
+  falsePositiveCount?: number;
+  /** Last time this keyword matched (ISO timestamp) */
+  lastHitAt?: string;
+}
+
+export interface CorrectionKeywordStore {
+  /** All correction keywords */
+  keywords: CorrectionKeyword[];
+  /** Schema version */
+  version: number;
+  /** Last time keyword optimization was performed (ISO timestamp) */
+  lastOptimizedAt: string;
+}
+
+// =========================================================================
+// Match Result
+// =========================================================================
+
+export interface CorrectionMatchResult {
+  /** Whether any keyword matched */
+  matched: boolean;
+  /** The first matched term (empty array when no match) */
+  matchedTerms: string[];
+  /** Weighted score (0-1) based on keyword weight and accuracy */
+  score: number;
+  /** Confidence in the match result (0-1) */
+  confidence: number;
+}
+
+// =========================================================================
+// Seed Keywords (16 terms — sourced from detectCorrectionCue)
+// =========================================================================
+
+/** Maximum number of keywords the store may hold (D-06). */
+export const MAX_CORRECTION_KEYWORDS = 200;
+
+/**
+ * Preset seed keywords for correction cue detection.
+ * Mirrors the hardcoded list in detectCorrectionCue() exactly (D-08).
+ * addedAt is intentionally empty here — it is filled in at runtime by
+ * createDefaultStore() when the store is first persisted to disk.
+ */
+export const CORRECTION_SEED_KEYWORDS: CorrectionKeyword[] = [
+  // Chinese (8)
+  { term: '不是这个', weight: 0.6, source: 'seed', addedAt: '' },
+  { term: '不对', weight: 0.5, source: 'seed', addedAt: '' },
+  { term: '错了', weight: 0.5, source: 'seed', addedAt: '' },
+  { term: '搞错了', weight: 0.7, source: 'seed', addedAt: '' },
+  { term: '理解错了', weight: 0.7, source: 'seed', addedAt: '' },
+  { term: '你理解错了', weight: 0.8, source: 'seed', addedAt: '' },
+  { term: '重新来', weight: 0.6, source: 'seed', addedAt: '' },
+  { term: '再试一次', weight: 0.4, source: 'seed', addedAt: '' },
+  // English (8)
+  { term: 'you are wrong', weight: 0.7, source: 'seed', addedAt: '' },
+  { term: 'wrong file', weight: 0.6, source: 'seed', addedAt: '' },
+  { term: 'not this', weight: 0.4, source: 'seed', addedAt: '' },
+  { term: 'redo', weight: 0.6, source: 'seed', addedAt: '' },
+  { term: 'try again', weight: 0.4, source: 'seed', addedAt: '' },
+  { term: 'again', weight: 0.3, source: 'seed', addedAt: '' },
+  { term: 'please redo', weight: 0.6, source: 'seed', addedAt: '' },
+  { term: 'please try again', weight: 0.5, source: 'seed', addedAt: '' },
+];

package/src/core/init.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
 import { PD_DIRS } from './paths.js';
 import { defaultContextConfig } from '../types.js';
+import { loadStore, setPrincipleState, type PrincipleTrainingState } from './principle-training-state.js';
 
 /**
  * Default PROFILE.json content
@@ -143,6 +144,72 @@ function copyRecursiveSync(srcDir: string, destDir: string, api: OpenClawPluginA
     }
 }
 
+/**
+ * Core thinking model definitions (T-01 through T-10).
+ * These are the built-in cognitive patterns that every workspace should have.
+ */
+const CORE_THINKING_MODELS: Array<{
+  id: string;
+  name: string;
+  description: string;
+}> = [
+  { id: 'T-01', name: 'Survey Before Acting', description: 'Understand the structure first before making changes.' },
+  { id: 'T-02', name: 'Respect Constraints', description: 'Trust files, not your context window. Write conclusions to files.' },
+  { id: 'T-03', name: 'Evidence Over Assumption', description: 'Use logs, code, and outputs before inferring causes.' },
+  { id: 'T-04', name: 'Reversible First', description: 'Prefer changes that are safe to roll back when risk is high.' },
+  { id: 'T-05', name: 'Safety Rails', description: 'Call out guardrails, prohibitions, and failure-prevention constraints.' },
+  { id: 'T-06', name: 'Simplicity First', description: 'Prefer the smallest understandable solution over over-engineering.' },
+  { id: 'T-07', name: 'Minimal Change Surface', description: 'Limit the blast radius and touch only what is necessary.' },
+  { id: 'T-08', name: 'Pain As Signal', description: 'Treat failures and friction as clues to step back and rethink.' },
+  { id: 'T-09', name: 'Divide And Conquer', description: 'Split the task into smaller phases before execution.' },
+  { id: 'T-10', name: 'Memory Externalization', description: 'Write intermediate conclusions to files for persistence.' },
+];
+
+/**
+ * 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: string, logger: PluginLogger): boolean {
+  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: PrincipleTrainingState = {
+        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);
+    }
+
+    logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: T-01 through T-10`);
+    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).
  */

package/src/service/correction-observer-types.ts

@@ -0,0 +1,58 @@
+/**
+ * Correction Observer Workflow - Type Definitions
+ *
+ * Types for the correction observer LLM optimization workflow.
+ * This workflow dispatches an LLM subagent to analyze keyword performance
+ * and recommend ADD/UPDATE/REMOVE actions for the correction keyword store.
+ */
+
+import type { SubagentWorkflowSpec, WorkflowPersistContext, WorkflowResultContext } from './subagent-workflow/types.js';
+
+/**
+ * Input passed to the correction observer subagent.
+ */
+export interface CorrectionObserverPayload {
+  /** Parent session that triggered the optimization */
+  parentSessionId: string;
+  /** Workspace directory */
+  workspaceDir: string;
+  /** Current keyword store summary for context */
+  keywordStoreSummary: {
+    totalKeywords: number;
+    terms: Array<{
+      term: string;
+      weight: number;
+      hitCount: number;
+      truePositiveCount: number;
+      falsePositiveCount: number;
+    }>;
+  };
+  /** Recent user messages for pattern analysis */
+  recentMessages: string[];
+}
+
+/**
+ * Result from the correction observer subagent.
+ */
+export interface CorrectionObserverResult {
+  /** Whether any changes were made */
+  updated: boolean;
+  /** The optimization decisions returned by the LLM */
+  updates: Record<string, {
+    action: 'add' | 'update' | 'remove';
+    weight?: number;
+    falsePositiveRate?: number;
+    reasoning: string;
+  }>;
+  /** Human-readable summary */
+  summary: string;
+}
+
+/**
+ * Workflow spec for the correction observer optimization workflow.
+ */
+export interface CorrectionObserverWorkflowSpec extends SubagentWorkflowSpec<CorrectionObserverResult> {
+  workflowType: 'correction_observer';
+  payload: CorrectionObserverPayload;
+  result?: CorrectionObserverResult;
+}

package/src/service/correction-observer-workflow-manager.ts

@@ -0,0 +1,218 @@
+/**
+ * CorrectionObserverWorkflowManager
+ *
+ * Workflow manager that dispatches an LLM subagent to optimize correction
+ * keywords based on recent match performance data and user feedback.
+ *
+ * Follows the established WorkflowManagerBase pattern from EmpathyObserverWorkflowManager.
+ */
+
+import type { PluginLogger } from '../openclaw-sdk.js';
+import type {
+    SubagentWorkflowSpec,
+    WorkflowMetadata,
+    WorkflowResultContext,
+    WorkflowPersistContext,
+    WorkflowHandle,
+} from './subagent-workflow/types.js';
+import type { RuntimeDirectDriver } from './subagent-workflow/runtime-direct-driver.js';
+import { WorkflowManagerBase } from './subagent-workflow/workflow-manager-base.js';
+import { isSubagentRuntimeAvailable } from '../utils/subagent-probe.js';
+import type {
+    CorrectionObserverPayload,
+    CorrectionObserverResult,
+    CorrectionObserverWorkflowSpec,
+} from './correction-observer-types.js';
+
+const WORKFLOW_SESSION_PREFIX = 'agent:main:subagent:workflow-correction-';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+// ── Options ─────────────────────────────────────────────────────────────────
+
+export interface CorrectionObserverWorkflowOptions {
+    workspaceDir: string;
+    logger: PluginLogger;
+    subagent: RuntimeDirectDriver['subagent'];
+    /** Pass api.runtime.agent.session to enable heartbeat-safe cleanup (#188) */
+    agentSession?: RuntimeDirectDriver['agentSession'];
+}
+
+// ── Helper Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Extract raw assistant text from messages or assistantTexts array.
+ */
+function extractAssistantTextForSpec(messages: unknown[], assistantTexts?: string[]): string {
+    if (assistantTexts && assistantTexts.length > 0) {
+        return assistantTexts[assistantTexts.length - 1] || '';
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i] as { role?: string; content?: unknown };
+        if (msg?.role !== 'assistant') continue;
+        if (typeof msg.content === 'string') return msg.content;
+        if (Array.isArray(msg.content)) {
+            const txt = msg.content
+                .filter((part: unknown) => part && typeof part === 'object' && (part as { type?: string }).type === 'text' && typeof (part as { text?: unknown }).text === 'string')
+                .map((part: unknown) => (part as { text: string }).text)
+                .join('\n');
+            if (txt) return txt;
+        }
+    }
+    return '';
+}
+
+/**
+ * Parse correction observer JSON payload from raw text.
+ */
+function parseCorrectionObserverPayload(rawText: string): CorrectionObserverResult | null {
+    if (!rawText?.trim()) return null;
+    try {
+        return JSON.parse(rawText.trim()) as CorrectionObserverResult;
+    } catch {
+        const match = /\{[\s\S]*\}/.exec(rawText);
+        if (!match) return null;
+        try {
+            return JSON.parse(match[0]) as CorrectionObserverResult;
+        } catch {
+            return null;
+        }
+    }
+}
+
+// ── Workflow Spec ─────────────────────────────────────────────────────────────
+
+export const correctionObserverWorkflowSpec: SubagentWorkflowSpec<CorrectionObserverResult> = {
+    workflowType: 'correction_observer',
+    transport: 'runtime_direct',
+    timeoutMs: 30_000,
+    ttlMs: 300_000,
+    shouldDeleteSessionAfterFinalize: true,
+
+    buildPrompt(taskInput: unknown, _metadata: WorkflowMetadata): string {
+        const payload = taskInput as CorrectionObserverPayload;
+        const { keywordStoreSummary, recentMessages } = payload;
+
+        const termsList = keywordStoreSummary.terms
+            .map(t => `  - term="${t.term}", weight=${t.weight}, hits=${t.hitCount}, TP=${t.truePositiveCount}, FP=${t.falsePositiveCount}`)
+            .join('\n');
+
+        const messages = recentMessages.length > 0
+            ? recentMessages.map(m => `  - ${JSON.stringify(m)}`).join('\n')
+            : '  (none)';
+
+        return [
+            'You are a correction keyword optimizer.',
+            '',
+            '## TASK',
+            'Analyze the current correction keyword store and recent user messages.',
+            'Recommend ADD/UPDATE/REMOVE actions to improve correction cue accuracy.',
+            '',
+            '## Current Keyword Store (' + keywordStoreSummary.totalKeywords + ' terms):',
+            termsList,
+            '',
+            '## Recent User Messages (' + recentMessages.length + ' messages):',
+            messages,
+            '',
+            '## Rules:',
+            '- ADD: If a correction pattern is detected in messages but not in store',
+            '- UPDATE: If a term\'s weight should change based on TP/FP ratio',
+            '- REMOVE: If a term has 0 hits after many uses AND high false positive rate (>0.3)',
+            '- Keep reasoning concise (max 100 chars)',
+            '- Weight range: 0.1-0.9',
+            '',
+            'Return strict JSON (no markdown):',
+            '{"updated": boolean, "updates": {...}, "summary": string}',
+        ].join('\n');
+    },
+
+    async parseResult(ctx: WorkflowResultContext): Promise<CorrectionObserverResult | null> {
+        const rawText = extractAssistantTextForSpec(ctx.messages, ctx.assistantTexts);
+        return parseCorrectionObserverPayload(rawText);
+    },
+
+    async persistResult(_ctx: WorkflowPersistContext<CorrectionObserverResult>): Promise<void> {
+        // Result persistence is handled by the caller (evolution-worker.ts)
+        // which reads the result and applies keyword store updates.
+        // This spec handles only the LLM dispatch and result parsing.
+    },
+
+    shouldFinalizeOnWaitStatus(status: 'ok' | 'error' | 'timeout'): boolean {
+        return status === 'ok';
+    },
+};
+
+// ── Manager Class ─────────────────────────────────────────────────────────────
+
+export class CorrectionObserverWorkflowManager extends WorkflowManagerBase {
+    constructor(opts: CorrectionObserverWorkflowOptions) {
+        super({
+            workspaceDir: opts.workspaceDir,
+            logger: opts.logger,
+            subagent: opts.subagent,
+            agentSession: opts.agentSession,
+            workflowType: 'correction_observer',
+            sessionPrefix: WORKFLOW_SESSION_PREFIX,
+            defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+            defaultTtlMs: DEFAULT_TTL_MS,
+        });
+    }
+
+    async startWorkflow<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        }
+    ): Promise<WorkflowHandle> {
+        // Surface degrade: skip boot sessions
+        if (options.parentSessionId.startsWith('boot-')) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: boot session`);
+            throw new Error(`CorrectionObserverWorkflowManager: cannot start workflow for boot session`);
+        }
+
+        // Surface degrade: check subagent runtime availability
+        if (!isSubagentRuntimeAvailable(this.driver.getSubagent())) {
+            this.logger.info(`[PD:CorrectionObserver] Skipping workflow: subagent runtime unavailable`);
+            throw new Error(`CorrectionObserverWorkflowManager: subagent runtime unavailable`);
+        }
+
+        if (spec.transport !== 'runtime_direct') {
+            throw new Error(`CorrectionObserverWorkflowManager only supports runtime_direct transport`);
+        }
+
+        return super.startWorkflow(spec, options);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    protected override createWorkflowMetadata<TResult>(
+        spec: SubagentWorkflowSpec<TResult>,
+        options: {
+            parentSessionId: string;
+            workspaceDir?: string;
+            taskInput: unknown;
+            metadata?: Record<string, unknown>;
+        },
+        now: number
+    ): WorkflowMetadata {
+        return {
+            parentSessionId: options.parentSessionId,
+            workspaceDir: options.workspaceDir,
+            taskInput: options.taskInput,
+            startedAt: now,
+            workflowType: spec.workflowType,
+            ...options.metadata,
+        };
+    }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+export function createCorrectionObserverWorkflowManager(
+    opts: CorrectionObserverWorkflowOptions
+): CorrectionObserverWorkflowManager {
+    return new CorrectionObserverWorkflowManager(opts);
+}