@cleocode/core 2026.4.9 → 2026.4.12

package/src/output.ts

@@ -4,22 +4,28 @@
  * LAFS (LLM-Agent-First Schema) ensures all CLI output is
  * machine-parseable JSON by default, with optional human-readable modes.
  *
- * All envelopes are now full LAFS-compliant with $schema and _meta.
- * The backward-compatible shape (success + data, no _meta) has been removed.
+ * All envelopes use the canonical CLI envelope shape:
+ *   { success, data?, error?, meta, page? }
+ *
+ * This replaces the three legacy shapes:
+ *   {ok, r, _m}            (minimal MVI — removed)
+ *   {$schema, _meta, success, result}  (full LAFS — now uses meta/data)
+ *   {success, result}      (observe command — now uses data)
  *
  * Types are re-exported from the canonical source in src/types/lafs.ts.
  *
  * @epic T4663
  * @task T4672
+ * @task T338 (ADR-039 envelope unification)
  */
 
 import { randomUUID } from 'node:crypto';
 import type { LafsEnvelope, LafsError, LafsSuccess } from '@cleocode/contracts';
-import type { LAFSMeta, LAFSPage, Warning } from '@cleocode/lafs';
+import type { CliEnvelope, CliEnvelopeError, CliMeta, LAFSPage, Warning } from '@cleocode/lafs';
 import { CleoError } from './errors.js';
 import { getCurrentSessionId } from './sessions/context-alert.js';
 
-export type { LafsEnvelope, LafsError, LafsSuccess };
+export type { CliEnvelope, CliEnvelopeError, CliMeta, LafsEnvelope, LafsError, LafsSuccess };
 
 /**
  * Accumulated warnings for the current request.
@@ -70,47 +76,57 @@ export interface FormatOptions {
 }
 
 /**
- * Create a LAFS-conformant _meta object for CLI envelopes.
+ * Create a canonical `CliMeta` object for CLI envelopes.
+ *
  * Includes sessionId (T4702) and warnings (T4669) when present.
+ * Drains the pending warnings queue so they are included in the current envelope.
+ *
+ * @param operation - Dot-delimited operation identifier (e.g. `"tasks.show"`).
+ * @param duration_ms - Wall-clock duration in milliseconds. Defaults to 0.
+ * @returns A fully populated {@link CliMeta} object.
  *
  * @task T4700
  * @task T4702
+ * @task T338
  * @epic T4663
  */
-function createCliMeta(
-  operation: string,
-  mvi: import('@cleocode/lafs').MVILevel = 'minimal',
-): LAFSMeta {
+function createCliMeta(operation: string, duration_ms = 0): CliMeta {
   const warnings = drainWarnings();
-  const meta: LAFSMeta = {
-    specVersion: '1.2.3',
-    schemaVersion: '2026.2.1',
-    timestamp: new Date().toISOString(),
+  const meta: CliMeta = {
     operation,
     requestId: randomUUID(),
-    transport: 'cli',
-    strict: true,
-    mvi,
-    contextVersion: 1,
-    ...(warnings && { warnings }),
+    duration_ms,
+    timestamp: new Date().toISOString(),
   };
   const sessionId = getCurrentSessionId();
   if (sessionId) {
-    meta.sessionId = sessionId;
+    meta['sessionId'] = sessionId;
+  }
+  if (warnings && warnings.length > 0) {
+    meta['warnings'] = warnings;
   }
   return meta;
 }
 
 /**
- * Format a successful result as a full LAFS-conformant envelope.
+ * Format a successful result as a canonical CLI envelope.
+ *
+ * Produces the unified `CliEnvelope<T>` shape: `{success, data, meta, page?}`.
+ * This replaces all three legacy shapes (minimal `{ok,r,_m}`, full `{$schema,_meta,result}`,
+ * and observe `{success,result}`) with a single canonical format (ADR-039).
+ *
+ * The `mvi` option in `FormatOptions` is accepted for backward compatibility but
+ * no longer affects the envelope shape — the canonical shape is always emitted.
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
- * Supports optional page (T4668) and _extensions (T4670).
+ * @param data - The operation result payload.
+ * @param message - Optional success message (attached to `meta.message`).
+ * @param operationOrOpts - Operation name string or `FormatOptions` object.
+ * @returns JSON-serialized `CliEnvelope<T>`.
  *
  * @task T4672
  * @task T4668
  * @task T4670
+ * @task T338
  * @epic T4663
  */
 export function formatSuccess<T>(
@@ -121,71 +137,53 @@ export function formatSuccess<T>(
   const opts: FormatOptions =
     typeof operationOrOpts === 'string' ? { operation: operationOrOpts } : (operationOrOpts ?? {});
 
-  // Determine MVI level: default is 'minimal' (agent-optimized).
-  // Only --human flag or explicit mvi='full'/'standard' overrides.
-  const mviLevel = opts.mvi ?? 'minimal';
+  const meta = createCliMeta(opts.operation ?? 'cli.output');
 
-  const meta = createCliMeta(opts.operation ?? 'cli.output', mviLevel);
-  const fullEnvelope: Record<string, unknown> = {
-    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
-    _meta: meta,
-    success: true as const,
-    result: data as Record<string, unknown> | Record<string, unknown>[] | null,
-    ...(message && { message }),
+  const envelope: CliEnvelope<T> = {
+    success: true,
+    data,
+    meta: message ? { ...meta, message } : meta,
     ...(opts.page && { page: opts.page }),
-    ...(opts.extensions &&
-      Object.keys(opts.extensions).length > 0 && { _extensions: opts.extensions }),
   };
 
-  // For 'full' level, skip projection — return the complete envelope as-is.
-  // This is the backward-compatible path used by --human and conformance tests.
-  if (mviLevel === 'full') {
-    return JSON.stringify(fullEnvelope);
-  }
-
-  // Apply MVI projection — strips envelope to the declared level.
-  // 'minimal': { success, result, _meta: { requestId, contextVersion } }
-  // 'standard': + $schema, timestamp, operation, mvi
-  if (mviLevel === 'minimal') {
-    // Inline minimal projection — avoids dynamic import overhead.
-    // Matches projectMetaMinimal() from @cleocode/lafs/mviProjection.ts
-    const minimalMeta: Record<string, unknown> = {
-      op: meta.operation,
-      rid: meta.requestId,
-    };
-    if (meta.sessionId) minimalMeta.sid = meta.sessionId;
-    if (meta.warnings?.length) minimalMeta.w = meta.warnings;
-
-    const minimal: Record<string, unknown> = {
-      ok: true,
-      r: data,
-      _m: minimalMeta,
-    };
-    if (message) minimal.msg = message;
-    if (opts.page) minimal.p = opts.page;
-    return JSON.stringify(minimal);
-  }
-
-  // 'standard' level — use the full envelope structure (current behavior)
-  return JSON.stringify(fullEnvelope);
+  return JSON.stringify(envelope);
 }
 
 /**
- * Format an error as a full LAFS-conformant envelope.
+ * Format an error as a canonical CLI error envelope.
+ *
+ * Produces `{success: false, error: CliEnvelopeError, meta: CliMeta}`.
+ * Every error envelope now always includes `meta` (ADR-039).
+ * When operation is omitted, defaults to `'cli.output'`.
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
+ * @param error - The `CleoError` to format.
+ * @param operation - Optional dot-delimited operation identifier.
+ * @returns JSON-serialized error `CliEnvelope`.
  *
  * @task T4672
+ * @task T338
  * @epic T4663
  */
 export function formatError(error: CleoError, operation?: string): string {
-  const envelope = {
-    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
-    _meta: createCliMeta(operation ?? 'cli.output'),
-    success: false as const,
-    result: null,
-    error: error.toLAFSError(),
+  const lafsError = error.toLAFSError();
+  const errorObj: CliEnvelopeError = {
+    code: lafsError.code,
+    message: lafsError.message,
+    details: lafsError.details,
+  };
+  if ('category' in lafsError && lafsError.category) {
+    (errorObj as Record<string, unknown>)['category'] = lafsError.category;
+  }
+  if ('retryable' in lafsError) {
+    (errorObj as Record<string, unknown>)['retryable'] = lafsError.retryable;
+  }
+  if ('agentAction' in lafsError && lafsError.agentAction) {
+    (errorObj as Record<string, unknown>)['agentAction'] = lafsError.agentAction;
+  }
+  const envelope: CliEnvelope<null> = {
+    success: false,
+    error: errorObj,
+    meta: createCliMeta(operation ?? 'cli.output'),
   };
   return JSON.stringify(envelope);
 }

package/src/paths.ts

@@ -1,8 +1,14 @@
 /**
  * XDG-compliant path resolution for CLEO V2.
  *
+ * Global data directory is resolved via env-paths (XDG on Linux, platform
+ * conventions on macOS and Windows):
+ *   Linux:   ~/.local/share/cleo
+ *   macOS:   ~/Library/Application Support/cleo
+ *   Windows: %LOCALAPPDATA%\cleo
+ *
  * Environment variables:
- *   CLEO_HOME   - Global installation directory (default: ~/.cleo)
+ *   CLEO_HOME   - Override global installation directory
  *   CLEO_DIR    - Project data directory (default: .cleo)
  *
  * @epic T4454
@@ -12,6 +18,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from './errors.js';
 import { getPlatformPaths } from './system/platform-paths.js';
 
 /**
@@ -160,31 +168,100 @@ export function getCleoDirAbsolute(cwd?: string): string {
 }
 
 /**
- * Get the project root from the CLEO directory.
- * Respects CLEO_ROOT env var, then derives from CLEO_DIR.
- * If CLEO_DIR is ".cleo", the project root is its parent.
+ * Get the project root by walking ancestor directories for `.cleo/` or `.git/`.
+ *
+ * Stops at the **first** ancestor directory that contains either sentinel
+ * directory and never drifts past it — even when multiple nested projects
+ * exist above the starting directory.
+ *
+ * Resolution order:
+ *   1. `CLEO_ROOT` env var — bypasses walk entirely (CI / test override)
+ *   2. `CLEO_DIR` env var (absolute path only) — derives project root from dirname
+ *   3. Walk ancestors from `cwd` (or `process.cwd()`) toward filesystem root:
+ *      - `.cleo/` found → return that directory (project root)
+ *      - `.git/` found (without `.cleo/` sibling) → throw `E_NOT_INITIALIZED`
+ *   4. Filesystem root reached without either → throw `E_NO_PROJECT`
  *
- * @param cwd - Optional working directory hint
- * @returns Absolute path to the project root
+ * @param cwd - Optional starting directory; defaults to `process.cwd()`
+ * @returns Absolute path to the project root directory (parent of `.cleo/`)
+ * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_NOT_INITIALIZED`) when a
+ *   `.git/` is found but no `.cleo/` is present at that level.
+ * @throws {CleoError} `ExitCode.NOT_FOUND` (`E_NO_PROJECT`) when neither
+ *   sentinel is found in any ancestor.
  *
  * @remarks
- * Resolution order: CLEO_ROOT env var (if no cwd), parent of the resolved
- * .cleo directory (if it ends with /.cleo), or the cwd/process.cwd() fallback.
+ * `CLEO_ROOT` is an absolute-path escape hatch for environments where the
+ * working directory is unrelated to the project (CI tmpdirs, monorepo scripts,
+ * test harnesses). When set it is returned as-is without scanning ancestors.
+ *
+ * `CLEO_DIR` set to an absolute path (e.g. `/project/.cleo`) also bypasses
+ * the walk: the project root is derived as its `dirname`. This preserves
+ * backward compatibility for test harnesses that use `CLEO_DIR` to pin the
+ * project root.
+ *
+ * NEVER auto-creates `.cleo/`. Project initialisation is an explicit opt-in
+ * via `cleo init`.
  *
  * @example
  * ```typescript
- * const root = getProjectRoot(); // "/home/user/projects/myapp"
+ * // Running from packages/core inside the monorepo:
+ * const root = getProjectRoot(); // "/mnt/projects/cleocode"
  * ```
  */
 export function getProjectRoot(cwd?: string): string {
-  if (!cwd && process.env['CLEO_ROOT']) {
+  // 1. Honour CLEO_ROOT env var — bypass walk entirely
+  if (process.env['CLEO_ROOT']) {
     return process.env['CLEO_ROOT'];
   }
-  const cleoDirAbs = getCleoDirAbsolute(cwd);
-  if (cleoDirAbs.endsWith('/.cleo') || cleoDirAbs.endsWith('\\.cleo')) {
-    return dirname(cleoDirAbs);
+
+  // 2. If CLEO_DIR is an absolute path, derive the project root from it.
+  //    This preserves backward compatibility for test harnesses that set
+  //    CLEO_DIR=/some/absolute/path/.cleo to pin the project root.
+  const cleoDirEnv = process.env['CLEO_DIR'];
+  if (cleoDirEnv && isAbsolutePath(cleoDirEnv)) {
+    if (cleoDirEnv.endsWith('/.cleo') || cleoDirEnv.endsWith('\\.cleo')) {
+      return dirname(cleoDirEnv);
+    }
+    return cleoDirEnv;
   }
-  return cwd ?? process.cwd();
+
+  const start = resolve(cwd ?? process.cwd());
+  let current = start;
+
+  // 2. Walk ancestors toward filesystem root
+  while (true) {
+    const cleoDir = join(current, '.cleo');
+    const gitDir = join(current, '.git');
+
+    if (existsSync(cleoDir)) {
+      // .cleo/ found — this is the project root
+      return current;
+    }
+
+    if (existsSync(gitDir)) {
+      // .git/ found but no .cleo/ sibling — not initialised
+      throw new CleoError(ExitCode.CONFIG_ERROR, `Run cleo init at ${current}`, {
+        fix: `cd ${current} && cleo init`,
+      });
+    }
+
+    // Move up one level
+    const parent = dirname(current);
+    if (parent === current) {
+      // Reached filesystem root without finding either sentinel
+      break;
+    }
+    current = parent;
+  }
+
+  // 3. No sentinel found in any ancestor
+  throw new CleoError(
+    ExitCode.NOT_FOUND,
+    'Not inside a CLEO project. Run cleo init or cd to an existing project',
+    {
+      fix: 'cleo init',
+    },
+  );
 }
 
 /**

package/src/scaffold.ts

@@ -77,18 +77,35 @@ export const REQUIRED_CLEO_SUBDIRS = [
   'adrs',
 ] as const;
 
-/** Embedded fallback for .cleo/.gitignore content (deny-by-default). */
+/**
+ * Embedded fallback for .cleo/.gitignore content (deny-by-default).
+ *
+ * Must stay in sync with `packages/core/templates/cleo-gitignore`. The
+ * template file is the source of truth; this constant is only used when
+ * the template file cannot be located at runtime (bundled binary edge
+ * cases, air-gapped installs, etc.).
+ *
+ * ADR-013 §9 (2026-04-07, T5158): config.json / project-info.json are
+ * NOT re-included here. Runtime state files (tasks.db, brain.db,
+ * config.json, project-info.json) are protected by explicit deny rules
+ * so that nested-.gitignore allow rules cannot unignore them at the
+ * project repository level.
+ */
 export const CLEO_GITIGNORE_FALLBACK = `# .cleo/.gitignore — Deny-by-default for CLEO project data
 # Ignore everything, then explicitly allow only tracked files.
+#
+# ADR-013 §9 (2026-04-07, T5158): config.json + project-info.json are
+# runtime snapshots regenerated by \`cleo init\`, not tracked in git.
+# Recovery for all four runtime files (tasks.db, brain.db, config.json,
+# project-info.json) is provided by \`cleo backup add\` snapshots under
+# .cleo/backups/. See .cleo/adrs/ADR-013 for the full recovery story.
 
 # Step 1: Ignore everything
 *
 
 # Allow list
 !.gitignore
-!config.json
 !project-context.json
-!project-info.json
 !setup-otel.sh
 !DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
 !adrs/
@@ -103,6 +120,8 @@ export const CLEO_GITIGNORE_FALLBACK = `# .cleo/.gitignore — Deny-by-default f
 *.db-shm
 *.db-wal
 *.db-journal
+config.json
+project-info.json
 log.json
 bypass-log.json
 qa-log.json

package/src/sessions/__tests__/session-grade.integration.test.ts

@@ -160,7 +160,7 @@ function sloppySession(): AuditEntry[] {
       params: { title: 'Do something', description: 'Duplicate' },
       result: { success: true, exitCode: 0, duration: 20 },
     }),
-    // No session.end, no help calls, no MCP gateway
+    // No session.end, no help calls, no query gateway usage
   ];
 }
 

package/src/sessions/__tests__/session-grade.test.ts

@@ -657,7 +657,7 @@ describe('gradeSession', () => {
         }),
       ]);
 
-      const result = await gradeSession('s5-mcp', tempDir);
+      const result = await gradeSession('s5-query', tempDir);
 
       expect(result.dimensions.disclosureUse.score).toBe(10);
       expect(result.dimensions.disclosureUse.evidence).toEqual(
@@ -698,7 +698,7 @@ describe('gradeSession', () => {
         entry({ domain: 'tasks', operation: 'find', timestamp: ts(0) }),
       ]);
 
-      const result = await gradeSession('s5-nomcp', tempDir);
+      const result = await gradeSession('s5-noqueries', tempDir);
 
       expect(result.flags).toContain(
         'No query gateway calls (use query operations for programmatic access)',

package/src/skills/__tests__/dynamic-skill-generator.test.ts

@@ -9,7 +9,6 @@ import {
 const cliProvider: ProviderContext = {
   providerId: 'claude-code',
   providerName: 'Claude Code',
-  supportsMcp: false,
   supportsHooks: true,
   supportsSpawn: true,
   instructionFilePattern: 'CLAUDE.md',
@@ -18,7 +17,6 @@ const cliProvider: ProviderContext = {
 const limitedProvider: ProviderContext = {
   providerId: 'cursor',
   providerName: 'Cursor',
-  supportsMcp: false,
   supportsHooks: false,
   supportsSpawn: false,
   instructionFilePattern: '.cursor/rules/*.mdc',

package/src/skills/dynamic-skill-generator.ts

@@ -16,8 +16,6 @@ import { getPreferredChannel } from './routing-table.js';
 export interface ProviderContext {
   providerId: string;
   providerName: string;
-  /** Always false. CLI dispatch only. */
-  supportsMcp: boolean;
   supportsHooks: boolean;
   supportsSpawn: boolean;
   instructionFilePattern?: string;