@cleocode/core 2026.4.11 → 2026.4.13

package/src/errors.ts

@@ -77,6 +77,23 @@ function exitCodeToLafsCode(code: ExitCode): string {
   return `E_${category}_${name}`;
 }
 
+/**
+ * Structured field-level details for constraint-violation errors.
+ * Surfaces in the LAFS envelope so agents can recover programmatically.
+ *
+ * @task T341
+ */
+export interface CleoErrorDetails {
+  /** The specific field that failed validation. */
+  field: string;
+  /** The expected value or constraint (e.g. max length, valid enum members). */
+  expected?: unknown;
+  /** The actual value that was provided. */
+  actual?: unknown;
+  /** Additional context keys. */
+  [key: string]: unknown;
+}
+
 /**
  * Structured error class for CLEO operations.
  * Carries an exit code, human-readable message, and optional fix suggestions.
@@ -87,6 +104,8 @@ export class CleoError extends Error {
   readonly code: ExitCode;
   readonly fix?: string;
   readonly alternatives?: Array<{ action: string; command: string }>;
+  /** Field-level details for constraint-violation errors. @task T341 */
+  readonly details?: CleoErrorDetails;
 
   constructor(
     code: ExitCode,
@@ -94,6 +113,7 @@ export class CleoError extends Error {
     options?: {
       fix?: string;
       alternatives?: Array<{ action: string; command: string }>;
+      details?: CleoErrorDetails;
       cause?: unknown;
     },
   ) {
@@ -102,6 +122,7 @@ export class CleoError extends Error {
     this.code = code;
     this.fix = options?.fix;
     this.alternatives = options?.alternatives;
+    this.details = options?.details;
   }
 
   /**
@@ -121,6 +142,7 @@ export class CleoError extends Error {
         name: getExitCodeName(this.code),
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { fieldDetails: this.details }),
       },
     };
   }
@@ -145,6 +167,7 @@ export class CleoError extends Error {
         recoverable: isRecoverableCode(this.code),
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { fieldDetails: this.details }),
       },
     };
   }
@@ -159,6 +182,7 @@ export class CleoError extends Error {
         message: this.message,
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { details: this.details }),
       },
     };
   }

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.ts

@@ -59,7 +59,6 @@ function makeConfig(
     autoCapture?: boolean;
     captureWork?: boolean;
     captureFiles?: boolean;
-    captureMcp?: boolean;
     autoRefresh?: boolean;
   } = {},
 ): Awaited<ReturnType<typeof configModule.loadConfig>> {
@@ -68,7 +67,6 @@ function makeConfig(
       autoCapture: overrides.autoCapture ?? true,
       captureWork: overrides.captureWork ?? false,
       captureFiles: overrides.captureFiles ?? false,
-      captureMcp: overrides.captureMcp ?? false,
       memoryBridge: { autoRefresh: overrides.autoRefresh ?? false },
       embedding: { enabled: false, provider: 'local' },
       summarization: { enabled: false },
@@ -564,9 +562,8 @@ describe('hook automation E2E', () => {
       );
     });
 
-    it('work-capture and mcp-hooks register on same event but use different config keys', async () => {
-      // work-capture is keyed on captureWork; mcp-hooks keyed on captureMcp
-      // When both are disabled (default), neither fires
+    it('work-capture does not fire when captureWork is disabled (default)', async () => {
+      // When captureWork is disabled (default), work-capture does not fire
       await handleWorkPromptSubmit(PROJECT_ROOT, {
         timestamp: TIMESTAMP,
         gateway: 'mutate',

package/src/init.ts

@@ -11,8 +11,7 @@
  *   4. Sequence counter (SQLite schema_meta)
  *   5. Project info (.cleo/project-info.json)
  *   6. CAAMP injection into agent instruction files (AGENTS.md hub pattern)
- *   7. (removed — was MCP server installation)
- *   8. Agent definition installation (cleo-subagent)
+ *   7. Agent definition installation (cleo-subagent)
  *   9. Core skill installation via CAAMP
  *  10. NEXUS project registration
  *  11. Project type detection (--detect)

package/src/internal.ts

@@ -410,6 +410,9 @@ export { listStickies, purgeSticky } from './sticky/index.js';
 export type { CreateStickyParams, ListStickiesParams, StickyNote } from './sticky/types.js';
 // Store
 export { createBackup, listBackups, restoreFromBackup } from './store/backup.js';
+// Backup portability — bundle packer (T311 / T347)
+export type { PackBundleInput, PackBundleResult } from './store/backup-pack.js';
+export { packBundle } from './store/backup-pack.js';
 export { getBrainDb, getBrainNativeDb } from './store/brain-sqlite.js';
 export type { LegacyCleanupResult, StrayNexusCleanupResult } from './store/cleanup-legacy.js';
 export {
@@ -422,17 +425,35 @@ export {
   isCleoGitInitialized,
 } from './store/git-checkpoint.js';
 export { computeChecksum, readJson } from './store/json.js';
+export type { MigrationResult } from './store/migrate-signaldock-to-conduit.js';
+export {
+  migrateSignaldockToConduit,
+  needsSignaldockToConduitMigration,
+} from './store/migrate-signaldock-to-conduit.js';
 export { createSession, getActiveSession } from './store/session-store.js';
 export {
+  _resetGlobalSignaldockDb_TESTING_ONLY,
+  checkGlobalSignaldockDbHealth,
   checkSignaldockDbHealth,
+  ensureGlobalSignaldockDb,
   ensureSignaldockDb,
+  GLOBAL_SIGNALDOCK_DB_FILENAME,
+  GLOBAL_SIGNALDOCK_SCHEMA_VERSION,
+  getGlobalSignaldockDbPath,
+  getGlobalSignaldockNativeDb,
   getSignaldockDbPath,
   SIGNALDOCK_SCHEMA_VERSION,
 } from './store/signaldock-sqlite.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
-export type { BackupScope, GlobalBackupEntry } from './store/sqlite-backup.js';
+export type {
+  BackupScope,
+  GlobalBackupEntry,
+  GlobalSaltBackupEntry,
+} from './store/sqlite-backup.js';
 export {
+  backupGlobalSalt,
   listBrainBackups,
+  listGlobalSaltBackups,
   listGlobalSqliteBackups,
   listSqliteBackups,
   listSqliteBackupsAll,
@@ -589,6 +610,7 @@ export type {
 export {
   buildCommanderArgs,
   buildCommanderOptionString,
+  buildDispatchInputSchema,
   buildMcpInputSchema,
   camelToKebab,
   validateRequiredParamsDef,
@@ -681,11 +703,51 @@ export { readSnapshot } from './snapshot/index.js';
 export { addSticky } from './sticky/create.js';
 export { getSticky } from './sticky/index.js';
 
+// Store — backup crypto (T363)
+export { decryptBundle, encryptBundle, isEncryptedBundle } from './store/backup-crypto.js';
+
 // Store (additional)
 export { resolveProjectRoot } from './store/file-utils.js';
 export { TASK_PRIORITIES } from './store/tasks-schema.js';
 // System (additional)
 export type { MigrateResult } from './system/index.js';
+
+// ---------------------------------------------------------------------------
+// T311 Backup portability — unpack + verify + A/B restore (T350, T352, T354, T357)
+// ---------------------------------------------------------------------------
+
+// Unpack + verify (T350)
+export type {
+  SchemaCompatWarning as BundleSchemaCompatWarning,
+  UnpackBundleInput,
+  UnpackBundleResult,
+} from './store/backup-unpack.js';
+export { BundleError, cleanupStaging, unpackBundle } from './store/backup-unpack.js';
+// Dry-run JSON file generators (T352)
+export type { RegeneratedFile } from './store/regenerators.js';
+export {
+  regenerateAllJson,
+  regenerateConfigJson,
+  regenerateProjectContextJson,
+  regenerateProjectInfoJson,
+} from './store/regenerators.js';
+// Conflict report formatter (T357)
+export type {
+  BuildConflictReportInput,
+  ReauthWarning,
+  SchemaCompatWarning as RestoreSchemaCompatWarning,
+} from './store/restore-conflict-report.js';
+export { buildConflictReport, writeConflictReport } from './store/restore-conflict-report.js';
+// A/B regenerate-and-compare engine (T354)
+export type {
+  FieldCategory,
+  FieldClassification,
+  FilenameForRestore,
+  JsonRestoreReport,
+  RegenerateAndCompareInput,
+  Resolution,
+} from './store/restore-json-merge.js';
+export { regenerateAndCompare, regenerateAndCompareAll } from './store/restore-json-merge.js';
 // Tasks (additional — stats)
 export { coreTaskStats } from './tasks/task-ops.js';
 
@@ -847,6 +909,30 @@ export { createSqliteDataAccessor } from './store/sqlite-data-accessor.js';
 // Validation — doctor checks (used by cleo init tests)
 export { checkRootGitignore } from './validation/doctor/checks.js';
 
+// ---------------------------------------------------------------------------
+// T310 startup sequence exports (required by cli/index.ts T360 wire-up)
+// ---------------------------------------------------------------------------
+
+// Conduit DB lifecycle — ensureConduitDb is called at every CLI startup (step 3)
+export type { ProjectAgentRef } from './store/conduit-sqlite.js';
+export {
+  CONDUIT_DB_FILENAME,
+  CONDUIT_SCHEMA_VERSION,
+  checkConduitDbHealth,
+  ensureConduitDb,
+  getConduitDbPath,
+  getConduitNativeDb,
+} from './store/conduit-sqlite.js';
+
+// Global-salt lifecycle — validateGlobalSalt and getGlobalSalt used at startup (step 5)
+export {
+  GLOBAL_SALT_FILENAME,
+  GLOBAL_SALT_SIZE,
+  getGlobalSalt,
+  getGlobalSaltPath,
+  validateGlobalSalt,
+} from './store/global-salt.js';
+
 // ---------------------------------------------------------------------------
 // Agent Registry + Conduit (T170 Unification)
 // ---------------------------------------------------------------------------
@@ -855,4 +941,12 @@ export { ConduitClient } from './conduit/conduit-client.js';
 export { createConduit } from './conduit/factory.js';
 export { HttpTransport } from './conduit/http-transport.js';
 export { decrypt, encrypt } from './crypto/credentials.js';
-export { AgentRegistryAccessor } from './store/agent-registry-accessor.js';
+export {
+  AgentRegistryAccessor,
+  attachAgentToProject,
+  createProjectAgent,
+  detachAgentFromProject,
+  getProjectAgentRef,
+  listAgentsForProject,
+  lookupAgent,
+} from './store/agent-registry-accessor.js';

package/src/lifecycle/cant/lifecycle-rcasd.cant

@@ -0,0 +1,133 @@
+---
+kind: lifecycle
+version: 1.0.0
+title: "RCASD-IVTR+C Pipeline Stages"
+status: active
+---
+
+# RCASD-IVTR+C Pipeline Stage Definitions
+#
+# Canonical pipeline stages in execution order.
+# Source of truth: packages/core/src/lifecycle/stages.ts
+#
+# Stages: research, consensus, architecture_decision, specification,
+#   decomposition, implementation, validation, testing, release
+#
+# Cross-cutting stage: contribution (not part of pipeline execution order,
+#   tracked for attribution and provenance recording)
+#
+# Stage 1: Research
+#   order: 1
+#   category: planning
+#   description: Information gathering, exploration, and knowledge acquisition
+#   skippable: false
+#   defaultTimeoutHours: 48
+#   requiredGates: prerequisites-met
+#   expectedArtifacts: research-report, findings-document
+#
+# Stage 2: Consensus
+#   order: 2
+#   category: decision
+#   description: Multi-agent decision making and validation of research findings
+#   skippable: true
+#   defaultTimeoutHours: 24
+#   requiredGates: research-complete, agreement-reached
+#   expectedArtifacts: consensus-record, decision-log
+#
+# Stage 3: Architecture Decision
+#   order: 3
+#   category: decision
+#   description: Architecture Decision Records - documenting significant technical decisions
+#   skippable: true
+#   defaultTimeoutHours: 24
+#   requiredGates: decisions-documented, review-completed
+#   expectedArtifacts: adr-document
+#
+# Stage 4: Specification
+#   order: 4
+#   category: planning
+#   description: Specification writing - RFC-style documentation of requirements and design
+#   skippable: false
+#   defaultTimeoutHours: 72
+#   requiredGates: spec-complete, spec-reviewed
+#   expectedArtifacts: spec-document, api-spec, design-doc
+#
+# Stage 5: Decomposition
+#   order: 5
+#   category: planning
+#   description: Task breakdown - splitting work into atomic, executable tasks
+#   skippable: false
+#   defaultTimeoutHours: 24
+#   requiredGates: tasks-created, dependencies-mapped
+#   expectedArtifacts: task-breakdown, dependency-graph
+#
+# Stage 6: Implementation
+#   order: 6
+#   category: execution
+#   description: Implementation - writing code and building features
+#   skippable: false
+#   defaultTimeoutHours: none
+#   requiredGates: code-complete, lint-passing
+#   expectedArtifacts: source-code, implementation-notes
+#
+# Stage 7: Validation
+#   order: 7
+#   category: validation
+#   description: Verification - static analysis, type checking, and quality gates
+#   skippable: false
+#   defaultTimeoutHours: 12
+#   requiredGates: static-analysis-pass, type-check-pass
+#   expectedArtifacts: verification-report
+#
+# Stage 8: Testing
+#   order: 8
+#   category: validation
+#   description: Testing - running test suites and ensuring coverage
+#   skippable: false
+#   defaultTimeoutHours: 24
+#   requiredGates: tests-pass, coverage-met
+#   expectedArtifacts: test-results, coverage-report
+#
+# Stage 9: Release
+#   order: 9
+#   category: delivery
+#   description: Release - versioning, publishing, and deployment
+#   skippable: true
+#   defaultTimeoutHours: 4
+#   requiredGates: version-bumped, changelog-updated, artifacts-published
+#   expectedArtifacts: version-tag, release-notes, published-package
+#
+# Stage Categories:
+#   planning: research, specification, decomposition
+#   decision: consensus, architecture_decision
+#   execution: implementation
+#   validation: validation, testing
+#   delivery: release
+#
+# Prerequisites:
+#   research: (none)
+#   consensus: research
+#   architecture_decision: research, consensus
+#   specification: research, consensus, architecture_decision
+#   decomposition: research, specification
+#   implementation: research, specification, decomposition
+#   validation: implementation
+#   testing: implementation, validation
+#   release: implementation, validation, testing
+#
+# Transition Rules:
+#   Forward progressions (always allowed):
+#     research -> consensus -> architecture_decision -> specification
+#     specification -> decomposition -> implementation -> validation
+#     validation -> testing -> release
+#   Skip patterns (allowed with force):
+#     research -> specification (skipping consensus + architecture_decision)
+#     specification -> implementation (skipping decomposition)
+#   Backward transitions (allowed with force, for rework):
+#     implementation -> specification (rework required)
+#     testing -> implementation (fix test failures)
+#   Disallowed:
+#     release -> any (pipeline completed)
+#
+# Stage Status Values:
+#   not_started, in_progress, completed, skipped, blocked, failed

package/src/memory/__tests__/engine-compat.test.ts

@@ -37,7 +37,7 @@ const SAMPLE_ENTRIES = [
     date: '2026-01-15',
     status: 'completed',
     agent_type: 'research',
-    topics: ['mcp', 'engine'],
+    topics: ['async-ops', 'engine'],
     key_findings: ['finding1', 'finding2', 'finding3'],
     actionable: true,
     linked_tasks: ['T001'],
@@ -186,7 +186,7 @@ describe('Pipeline Manifest SQLite (moved from memory domain)', () => {
 
     it('should search by topic', async () => {
       await seedEntries();
-      const result = await pipelineManifestFind('mcp', {}, testRoot);
+      const result = await pipelineManifestFind('async-ops', {}, testRoot);
       expect(result.success).toBe(true);
       expect((result.data as any).total).toBeGreaterThan(0);
     });

package/src/memory/__tests__/pipeline-manifest-sqlite.test.ts

@@ -45,8 +45,8 @@ const ENTRY_A: ExtendedManifestEntry = {
   date: '2026-01-15',
   status: 'completed',
   agent_type: 'research',
-  topics: ['mcp', 'engine'],
-  key_findings: ['This library is deprecated', 'MCP supports structured output'],
+  topics: ['async-ops', 'engine'],
+  key_findings: ['This library is deprecated', 'System supports structured output'],
   actionable: true,
   linked_tasks: ['T001'],
   needs_followup: [],
@@ -464,9 +464,9 @@ describe('pipeline-manifest-sqlite', () => {
 
     it('should filter by topic param', async () => {
       await seedEntries(testRoot, [ENTRY_A, ENTRY_C]);
-      const result = await pipelineManifestContradictions(testRoot, { topic: 'mcp' });
+      const result = await pipelineManifestContradictions(testRoot, { topic: 'async-ops' });
       expect(result.success).toBe(true);
-      // ENTRY_C doesn't have 'mcp' topic, so no contradictions on that topic
+      // ENTRY_C doesn't have 'async-ops' topic, so no contradictions on that topic
       expect((result.data as any).contradictions.length).toBe(0);
     });
   });

package/src/observability/__tests__/index.test.ts

@@ -43,7 +43,7 @@ describe('queryLogs', () => {
         pid: 1,
         hostname: 'h',
         msg: 'Start',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'WARN',
@@ -273,7 +273,7 @@ describe('getLogSummary', () => {
         pid: 1,
         hostname: 'h',
         msg: 'a',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'INFO',
@@ -281,7 +281,7 @@ describe('getLogSummary', () => {
         pid: 2,
         hostname: 'h',
         msg: 'b',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'WARN',
@@ -305,7 +305,7 @@ describe('getLogSummary', () => {
     const summary = getLogSummary({ scope: 'project' }, tmpDir);
     expect(summary.totalEntries).toBe(4);
     expect(summary.byLevel).toEqual({ INFO: 2, WARN: 1, ERROR: 1 });
-    expect(summary.bySubsystem).toEqual({ mcp: 2, engine: 2 });
+    expect(summary.bySubsystem).toEqual({ engine: 4 });
     expect(summary.dateRange).not.toBeNull();
     expect(summary.dateRange!.earliest).toBe('2026-02-28T10:00:00Z');
     expect(summary.dateRange!.latest).toBe('2026-02-28T10:03:00Z');

package/src/observability/__tests__/log-filter.test.ts

@@ -73,7 +73,7 @@ describe('matchesFilter', () => {
   it('filters by subsystem', () => {
     const entry = makeEntry({ subsystem: 'engine' });
     expect(matchesFilter(entry, { subsystem: 'engine' })).toBe(true);
-    expect(matchesFilter(entry, { subsystem: 'mcp' })).toBe(false);
+    expect(matchesFilter(entry, { subsystem: 'dispatch' })).toBe(false);
   });
 
   it('filters by code', () => {
@@ -105,7 +105,7 @@ describe('matchesFilter', () => {
   it('applies AND logic for multiple criteria', () => {
     const entry = makeEntry({ level: 'ERROR', subsystem: 'engine', code: 'E_NOT_FOUND' });
     expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'engine' })).toBe(true);
-    expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'mcp' })).toBe(false);
+    expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'dispatch' })).toBe(false);
     expect(matchesFilter(entry, { level: 'WARN', subsystem: 'engine' })).toBe(false);
   });
 
@@ -119,10 +119,10 @@ describe('matchesFilter', () => {
 
 describe('filterEntries', () => {
   const entries = [
-    makeEntry({ level: 'INFO', msg: 'Starting server', subsystem: 'mcp' }),
+    makeEntry({ level: 'INFO', msg: 'Starting server', subsystem: 'dispatch' }),
     makeEntry({ level: 'WARN', msg: 'Task not found', subsystem: 'engine', code: 'E_NOT_FOUND' }),
     makeEntry({ level: 'ERROR', msg: 'Database locked', subsystem: 'engine', exitCode: 3 }),
-    makeEntry({ level: 'INFO', msg: 'Server stopped', subsystem: 'mcp' }),
+    makeEntry({ level: 'INFO', msg: 'Server stopped', subsystem: 'dispatch' }),
   ];
 
   it('returns all entries for empty filter', () => {