@cleocode/contracts 2026.5.96 → 2026.5.97

package/dist/memory/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,+DAKjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;CACxB"}

package/dist/memory/observe.js

@@ -0,0 +1,46 @@
+/**
+ * BRAIN observation-write wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `observeBrain` operation — the unified BRAIN write path that persists
+ * agent observations into `brain_observations`. Companion to the
+ * read-side trio in {@link ./search.ts}, {@link ./timeline.ts}, and
+ * {@link ./fetch.ts}.
+ *
+ * The `BRAIN_OBSERVATION_SOURCE_TYPES` const is co-located here so the
+ * derived `BrainObservationSourceType` union has a single source of truth.
+ * `packages/core/src/store/memory-schema.ts` re-exports the const for
+ * Drizzle's `enum: [...]` column constraint, which requires the runtime
+ * tuple literal.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+// ── BRAIN_OBSERVATION_SOURCE_TYPES + BrainObservationSourceType ─────
+/**
+ * Source-type tuple for `brain_observations.source_type` — how the
+ * observation was created.
+ *
+ * Originally defined in `packages/core/src/store/memory-schema.ts:134`.
+ * Promoted here so the derived {@link BrainObservationSourceType} union
+ * lives alongside its source. `memory-schema.ts` re-exports the const
+ * because Drizzle's `{ enum: ... }` column constraint requires the runtime
+ * tuple literal.
+ *
+ * - `agent`           — produced by a spawned agent at task time.
+ * - `session-debrief` — synthesized at session end by the debrief pipeline.
+ * - `claude-mem`      — imported from a claude-mem migration batch.
+ * - `manual`          — typed directly by the owner via `cleo memory observe`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export const BRAIN_OBSERVATION_SOURCE_TYPES = [
+    'agent',
+    'session-debrief',
+    'claude-mem',
+    'manual',
+];
+//# sourceMappingURL=observe.js.map

package/dist/memory/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,uEAAuE;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,OAAO;IACP,iBAAiB;IACjB,YAAY;IACZ,QAAQ;CACA,CAAC"}

package/dist/memory/search.d.ts

@@ -0,0 +1,137 @@
+/**
+ * BRAIN compact-search wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
+ * per result) so agents can scan a wide candidate set cheaply before drilling
+ * into a specific entry.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
+ * depend on the shape without importing core. Unblocks the
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
+ * (T9834).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 2: {@link ./timeline.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+/**
+ * Single compact hit returned by `searchBrainCompact`.
+ *
+ * Minimal projection of a BRAIN table row designed for cheap scanning —
+ * the full payload is fetched on demand via `fetchBrainEntries` (Layer 3).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainCompactHit {
+    /** Entry identifier (e.g. `D-arch-001`, `P-feat-042`). */
+    id: string;
+    /** Source BRAIN table that produced the hit. */
+    type: 'decision' | 'pattern' | 'learning' | 'observation';
+    /** Display title for the entry. */
+    title: string;
+    /** ISO 8601 creation date. */
+    date: string;
+    /** Legacy relevance score (BM25-only path); omit when `rrfScore` is set. */
+    relevance?: number;
+    /**
+     * RRF-fused score: sum of 1/(rank+60) across all retrieval sources.
+     * Present only when the RRF path is used (`useRRF=true`, default).
+     * Higher = stronger match. Comparable across results in the same query.
+     */
+    rrfScore?: number;
+    /**
+     * BM25-derived score, min-max normalized to [0, 1] across the result set.
+     * 1.0 = best BM25 rank in this query, 0.0 = worst (or not found via FTS).
+     * Present only when the RRF path is used and at least one FTS result exists.
+     */
+    bm25Score?: number;
+    /**
+     * Progressive-disclosure directives for follow-up operations.
+     *
+     * Maps follow-up keys (e.g. `fetch`, `timeline`) to suggested CLI commands.
+     * `Record<string, string>` mirrors the runtime `NextDirectives` alias used
+     * by `@cleocode/core`'s `mvi-helpers`.
+     */
+    _next?: Record<string, string>;
+}
+/**
+ * Parameters for `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactParams {
+    /** Free-text query (FTS5 + optional vector recall). */
+    query: string;
+    /** Maximum number of hits to return (caller-bounded). */
+    limit?: number;
+    /** Restrict the search to a subset of BRAIN tables. */
+    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
+    /** ISO 8601 lower-bound date filter (inclusive). */
+    dateStart?: string;
+    /** ISO 8601 upper-bound date filter (inclusive). */
+    dateEnd?: string;
+    /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
+    agent?: string;
+    /**
+     * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
+     * vector search results for higher recall and better ranking.
+     * When false, fall back to FTS5-only search (faster, no embeddings needed).
+     */
+    useRRF?: boolean;
+    /**
+     * T1085: Peer ID filter for CANT agent memory isolation (PSYCHE Wave 2).
+     *
+     * When provided, search results are scoped to entries where:
+     *   `peer_id = peerId OR peer_id = 'global'`
+     *
+     * When omitted, all entries are returned — backward-compatible behavior.
+     */
+    peerId?: string;
+    /**
+     * T1085: When true (default when peerId is provided), include entries with
+     * `peer_id = 'global'` alongside the peer-specific entries.
+     *
+     * Set to false for strict per-peer isolation (no global pool bleed-through).
+     */
+    includeGlobal?: boolean;
+    /**
+     * T1900: ranking mode.
+     *
+     * - `recency`  — ORDER BY created_at DESC, no BM25/RRF contribution.
+     *                Use for recentObservations / recentLearnings where
+     *                chronological freshness matters more than textual match.
+     * - `lexical`  — FTS5 BM25 only (useRRF=false legacy path).
+     * - `hybrid`   — Reciprocal Rank Fusion (default, useRRF=true path).
+     *
+     * @default 'hybrid'
+     */
+    mode?: 'recency' | 'lexical' | 'hybrid';
+    /**
+     * T1900: ISO 8601 timestamp lower-bound filter (inclusive).
+     *
+     * When provided, only rows with `created_at >= since` are returned.
+     * Applies to all modes including recency. Useful with `mode=hybrid`
+     * (e.g., `since=<30d>`) to limit pattern staleness.
+     *
+     * When omitted, no lower-bound date filter is applied.
+     */
+    since?: string;
+}
+/**
+ * Result envelope returned by `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactResult {
+    /** Ordered compact hits (best match first). */
+    results: BrainCompactHit[];
+    /** Total number of matches before `limit` truncation. */
+    total: number;
+    /** Approximate token cost of the returned payload (~chars/4). */
+    tokensEstimated: number;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/memory/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/memory/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC;IAC1D,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAID;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,CAAC;IACxE,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB"}

package/dist/memory/search.js

@@ -0,0 +1,22 @@
+/**
+ * BRAIN compact-search wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
+ * per result) so agents can scan a wide candidate set cheaply before drilling
+ * into a specific entry.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
+ * depend on the shape without importing core. Unblocks the
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
+ * (T9834).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 2: {@link ./timeline.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+export {};
+//# sourceMappingURL=search.js.map

package/dist/memory/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/memory/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/memory/timeline.d.ts

@@ -0,0 +1,89 @@
+/**
+ * BRAIN timeline wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
+ * around an anchor entry so an agent can reconstruct the surrounding
+ * memory context cheaply.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
+ * continues to re-export it for internal callers.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+/**
+ * Anchor entry around which a timeline is built.
+ *
+ * Carries the entry identifier, its source table (`type`), and the full
+ * payload (`data`) so the caller can render the anchor inline with the
+ * neighbor list without an additional `fetchBrainEntries` round trip.
+ *
+ * Originally defined in `packages/core/src/memory/brain-row-types.ts:46`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainAnchor {
+    /** Entry identifier (e.g. `O-abc123`, `D-arch-001`). */
+    id: string;
+    /** Source BRAIN table (e.g. `observation`, `decision`, `pattern`, `learning`). */
+    type: string;
+    /**
+     * Raw row payload as returned by the underlying SQL query.
+     *
+     * Typed as `unknown` because the shape varies by `type`. Callers narrow
+     * via a discriminated read or pass the value through to a renderer that
+     * already understands every BRAIN table shape.
+     */
+    data: unknown;
+}
+/**
+ * Parameters for `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainParams {
+    /** Anchor entry ID to build the timeline around. */
+    anchor: string;
+    /** Number of chronologically-earlier neighbors to include. */
+    depthBefore?: number;
+    /** Number of chronologically-later neighbors to include. */
+    depthAfter?: number;
+}
+/**
+ * Compact neighbor projection used in timeline results.
+ *
+ * Each neighbor is reduced to an `{id, type, date}` triple so callers can
+ * cheaply scan a large window before drilling into specific entries via
+ * `fetchBrainEntries`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineNeighbor {
+    /** Entry identifier. */
+    id: string;
+    /** Source BRAIN table (e.g. `observation`, `decision`). */
+    type: string;
+    /** ISO 8601 creation date. */
+    date: string;
+}
+/**
+ * Result envelope returned by `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainResult {
+    /** The anchor entry, or `null` when the requested ID does not resolve. */
+    anchor: BrainAnchor | null;
+    /** Chronologically-earlier neighbors, oldest first. */
+    before: TimelineNeighbor[];
+    /** Chronologically-later neighbors, newest last. */
+    after: TimelineNeighbor[];
+}
+//# sourceMappingURL=timeline.d.ts.map

package/dist/memory/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/memory/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,oDAAoD;IACpD,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B"}

package/dist/memory/timeline.js

@@ -0,0 +1,22 @@
+/**
+ * BRAIN timeline wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
+ * around an anchor entry so an agent can reconstruct the surrounding
+ * memory context cheaply.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
+ * continues to re-export it for internal callers.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+export {};
+//# sourceMappingURL=timeline.js.map

package/dist/memory/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/memory/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/operations/focus.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Focus Domain Operations — single-envelope task orientation.
+ *
+ * `cleo focus <id>` aggregates 8 separate orientation calls into one
+ * wire-format envelope covering identity, scope, members, blockers,
+ * the next parallel-safe wave, attached docs, recent git activity, and
+ * scope-filtered brain context.
+ *
+ * Token budget: ≤ 1 500 tokens for a typical task orientation request.
+ *
+ * @task T9973
+ * @epic T9964 E-ORIENT-V2
+ */
+import type { MemoryCompactHit } from './memory.js';
+/**
+ * Parameters for `focus.show`.
+ *
+ * @task T9973
+ */
+export interface FocusShowParams {
+    /** Task, Epic, or Saga ID to orient on (e.g. `T9973`, `T9831`). Required. */
+    id: string;
+}
+/**
+ * Minimal identity block surfaced for the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusIdentity {
+    /** Task / Epic / Saga identifier. */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Entity tier — `'task'`, `'epic'`, or `'saga'`. */
+    type: string;
+    /** Current lifecycle status. */
+    status: string;
+    /** Parent task / Epic identifier, if any. */
+    parentId?: string | null;
+}
+/**
+ * Scope hierarchy resolved from the focused entity's ancestry.
+ *
+ * @task T9973
+ */
+export interface FocusScope {
+    /** Saga ID, when the entity belongs to a Saga. */
+    sagaId?: string;
+    /** Epic ID when the entity is a task or the focused entity itself is an Epic. */
+    epicId?: string;
+    /** Task ID when the focused entity is a task. */
+    taskId?: string;
+}
+/**
+ * One member Epic of a Saga, with a rollup status.
+ *
+ * Populated only when `focus.show` is called on a Saga ID.
+ *
+ * @task T9973
+ */
+export interface FocusSagaMember {
+    /** Epic task identifier. */
+    epicId: string;
+    /** Rollup status for the Epic (e.g. `'active'`, `'done'`). */
+    status: string;
+    /** Epic title. */
+    title: string;
+}
+/**
+ * One task blocking the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusBlocker {
+    /** ID of the task that is blocking. */
+    id: string;
+    /** Title of the blocking task. */
+    title: string;
+    /** Human-readable reason the dependency is unresolved. */
+    reason: string;
+}
+/**
+ * One ready task from the next parallel-safe wave of the parent Epic.
+ *
+ * @task T9973
+ */
+export interface FocusReadyTask {
+    /** Task identifier. */
+    id: string;
+    /** Task title. */
+    title: string;
+    /** Engine-rolled priority. */
+    priority: string;
+    /** Dependency IDs (already satisfied for ready tasks). */
+    depends: string[];
+}
+/**
+ * One doc attachment linked to the focused entity.
+ *
+ * @task T9973
+ */
+export interface FocusAttachedDoc {
+    /** Attachment identifier (att_* or UUID). */
+    attachmentId: string;
+    /** Human-friendly slug, when assigned. */
+    slug?: string;
+    /** Taxonomy classification, when assigned. */
+    type?: string;
+    /** Storage kind (e.g. `'local-file'`, `'url'`, `'blob'`). */
+    kind: string;
+}
+/**
+ * One recent git commit mentioning the focused task ID.
+ *
+ * @task T9973
+ */
+export interface FocusRecentCommit {
+    /** Full 40-character commit SHA. */
+    commitSha: string;
+    /** Commit subject line (first line of the commit message). */
+    message: string;
+    /** ISO 8601 author date. */
+    date: string;
+}
+/**
+ * Brain context scoped to the focused entity (≤ 3 entries per category).
+ *
+ * @task T9973
+ */
+export interface FocusBrainContext {
+    /** Recent observations relevant to the focused entity. */
+    observations: MemoryCompactHit[];
+    /** Learnings relevant to the focused entity. */
+    learnings: MemoryCompactHit[];
+    /** Decisions relevant to the focused entity. */
+    decisions: MemoryCompactHit[];
+}
+/**
+ * Result of `focus.show` — the single-envelope task orientation response.
+ *
+ * All fields except `identity` and `scope` are omitted when the
+ * underlying data source returns nothing (empty arrays, unavailable stores,
+ * git not in repo). Consumers MUST handle optional fields gracefully.
+ *
+ * Token budget: ≤ 1 500 tokens for typical task orientation.
+ *
+ * @task T9973
+ * @epic T9964
+ */
+export interface FocusShowResult {
+    /** Core identity of the focused entity. */
+    identity: FocusIdentity;
+    /** Scope hierarchy (saga → epic → task) derived from ancestry. */
+    scope: FocusScope;
+    /**
+     * Saga member Epics with rollup statuses.
+     * Populated only when `id` resolves to a Saga (`label='saga'`).
+     */
+    members?: FocusSagaMember[];
+    /**
+     * Tasks that are blocking the focused entity.
+     * Empty array when the entity is not blocked.
+     */
+    blockers: FocusBlocker[];
+    /**
+     * Next parallel-safe wave of tasks from the parent Epic.
+     * Omitted when the entity has no parent Epic or the ready-set is empty.
+     */
+    readyWave?: FocusReadyTask[];
+    /**
+     * Docs attached to the focused task/epic.
+     * Omitted when the docs store is unavailable or no attachments exist.
+     */
+    attachedDocs?: FocusAttachedDoc[];
+    /**
+     * Up to 5 most-recent git commits mentioning the focused task ID.
+     * Omitted when git is unavailable or no matching commits are found.
+     */
+    recentActivity?: FocusRecentCommit[];
+    /**
+     * Scope-filtered brain context — up to 3 entries per category.
+     * Omitted when the BRAIN store is unavailable.
+     */
+    brainContext?: FocusBrainContext;
+    /** Estimated token weight of this envelope. */
+    tokensEstimated: number;
+}
+/**
+ * Typed operation record for the focus domain.
+ *
+ * Maps each operation name to its `[Params, Result]` tuple for compile-time
+ * narrowing in the dispatch layer.
+ *
+ * @task T9973
+ */
+export type FocusOps = {
+    readonly show: readonly [FocusShowParams, FocusShowResult];
+};
+//# sourceMappingURL=focus.d.ts.map

package/dist/operations/focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../src/operations/focus.ts"],"names":[],"mappings":"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"}

package/dist/operations/focus.js

@@ -0,0 +1,15 @@
+/**
+ * Focus Domain Operations — single-envelope task orientation.
+ *
+ * `cleo focus <id>` aggregates 8 separate orientation calls into one
+ * wire-format envelope covering identity, scope, members, blockers,
+ * the next parallel-safe wave, attached docs, recent git activity, and
+ * scope-filtered brain context.
+ *
+ * Token budget: ≤ 1 500 tokens for a typical task orientation request.
+ *
+ * @task T9973
+ * @epic T9964 E-ORIENT-V2
+ */
+export {};
+//# sourceMappingURL=focus.js.map

package/dist/operations/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../../src/operations/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/operations/index.d.ts

@@ -9,6 +9,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './dialectic.js';
 export * from './docs.js';
+export * from './focus.js';
 export * from './intelligence.js';
 export * from './issues.js';
 export * from './lifecycle.js';

package/dist/operations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/dist/operations/index.js

@@ -9,6 +9,7 @@ export * from './brain.js';
 export * from './conduit.js';
 export * from './dialectic.js';
 export * from './docs.js';
+export * from './focus.js';
 export * from './intelligence.js';
 export * from './issues.js';
 export * from './lifecycle.js';

package/dist/operations/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}