@cleocode/contracts 2026.5.92 → 2026.5.93

package/src/doctor.ts

@@ -0,0 +1,130 @@
+/**
+ * Doctor domain contracts — types for `cleo doctor` worktree-orphan audit/prune.
+ *
+ * These types describe orphan `.cleo/` directories left behind under
+ * `<projectRoot>/.claude/worktrees/` by the T9550/T9580 SSoT bug (fixed in
+ * v2026.5.83) and the schema for the audit JSONL line written per prune.
+ *
+ * Consumed by:
+ *   - `packages/core/src/doctor/worktree-orphans.ts` (scan + prune primitives)
+ *   - `packages/cleo/src/cli/commands/doctor.ts` (CLI flags)
+ *
+ * @task T9790
+ * @epic T9790
+ */
+
+/**
+ * One orphan `.cleo/` directory discovered under
+ * `<projectRoot>/.claude/worktrees/`.
+ *
+ * Worktrees are nested 1-3 levels deep — examples:
+ *   - `<projectRoot>/.claude/worktrees/agent-X/.cleo/`            (depth 1)
+ *   - `<projectRoot>/.claude/worktrees/agent-X/T9220/.cleo/`     (depth 2)
+ *
+ * Each entry carries full provenance so the operator can decide whether
+ * the orphan represents lost work before pruning.
+ */
+export interface OrphanEntry {
+  /**
+   * The worktree root that contains the orphan — the first directory under
+   * `.claude/worktrees/` (e.g. `<projectRoot>/.claude/worktrees/agent-X`).
+   * Used as the boundary that `pruneWorktreeOrphans` validates against.
+   */
+  worktreePath: string;
+
+  /**
+   * Absolute path to the orphan `.cleo/` directory itself. Always lives
+   * under `worktreePath` (the security check rejects anything that doesn't).
+   */
+  orphanPath: string;
+
+  /**
+   * List of `tasks.db`, `brain.db`, `nexus.db`, or `config.json` paths
+   * found inside the orphan. Empty array means the orphan exists but is
+   * structurally empty (still pruned — it shouldn't be there at all).
+   */
+  dbFiles: string[];
+
+  /** Total byte size of the orphan tree (sum of regular file sizes). */
+  sizeBytes: number;
+
+  /** ISO-8601 timestamp of the most recent file modification under the orphan. */
+  lastModifiedAt: string;
+
+  /**
+   * Seconds since `lastModifiedAt` (relative to scan time). Surfaces "stale
+   * vs recent" without forcing the caller to compute date math.
+   */
+  ageSeconds: number;
+
+  /**
+   * `true` when the orphan contains more than just stray DB files — e.g. a
+   * full duplicate of `adrs/`, `agent-outputs/`, `rcasd/`, etc. These need
+   * heightened operator review before pruning.
+   */
+  isFullDuplicate: boolean;
+}
+
+/**
+ * Result of one prune operation. Reports the archive location, the per-entry
+ * outcome, and any entries rejected by the security gate.
+ */
+export interface PruneResult {
+  /**
+   * Absolute path to the `.tar.gz` archive written before any deletion.
+   * `null` only when `dryRun: true` AND no archive was produced.
+   */
+  archivePath: string | null;
+
+  /** Whether this was a dry run (no archive, no rm, no audit-log line). */
+  dryRun: boolean;
+
+  /** Entries that were successfully pruned (or would be in dry-run mode). */
+  pruned: OrphanEntry[];
+
+  /**
+   * Entries that failed validation and were skipped. The `reason` is a
+   * stable machine-readable code (e.g. `path-outside-worktrees-root`,
+   * `path-not-found`, `rm-failed`).
+   */
+  rejected: Array<{ entry: OrphanEntry; reason: string }>;
+
+  /** Total bytes archived (sum of `pruned[].sizeBytes`). */
+  totalSizeBytes: number;
+
+  /** ISO-8601 timestamp the prune completed. */
+  prunedAt: string;
+}
+
+/**
+ * One line appended to `.cleo/audit/worktree-prune.jsonl` per prune
+ * operation. Extends the existing audit-log schema (timestamp +
+ * worktreePath + action + agent) with the orphan-specific fields needed
+ * to reconstruct what was removed.
+ *
+ * Existing fields preserved for schema continuity:
+ *   - `timestamp`, `worktreePath`, `action`, `agent`
+ *
+ * New fields for orphan prune:
+ *   - `orphanPath`, `sizeBytes`, `dbFileCount`, `archivePath`, `dryRun`
+ */
+export interface PruneAuditEntry {
+  /** ISO-8601 timestamp. */
+  timestamp: string;
+  /** Worktree root that contained the orphan. */
+  worktreePath: string;
+  /** Absolute path to the orphan `.cleo/` directory removed. */
+  orphanPath: string;
+  /** Action code — fixed to `'prune-worktree-orphan'` for this flow. */
+  action: 'prune-worktree-orphan';
+  /** Always `'cleo'` — written by `cleo doctor`. */
+  agent: 'cleo';
+  /** Byte size of the pruned tree. */
+  sizeBytes: number;
+  /** Number of DB files found in the orphan (informational). */
+  dbFileCount: number;
+  /** Absolute path to the archive. `null` only on dry-run lines. */
+  archivePath: string | null;
+  /** Whether this entry represents a dry-run plan (no actual removal). */
+  dryRun: boolean;
+}

package/src/index.ts

@@ -277,6 +277,22 @@ export type {
   StoreDocParams,
   StoreDocResult,
 } from './docs-accessor.js';
+// === Canonical Doc-Kind Taxonomy Registry (T9788) ===
+export type {
+  BuiltinDocKind,
+  DocKindConfigFile,
+  DocKindExtensionConfig,
+  DocKindMetadata,
+  SlugValidationResult,
+} from './docs-taxonomy.js';
+export {
+  BUILTIN_DOC_KIND_VALUES,
+  BUILTIN_DOC_KINDS,
+  DocKindConfigError,
+  DocKindRegistry,
+} from './docs-taxonomy.js';
+// === Doctor: Worktree-Orphan Audit + Prune Types (T9790) ===
+export type { OrphanEntry, PruneAuditEntry, PruneResult } from './doctor.js';
 export type {
   EngineErrorPayload,
   EngineFailure,
@@ -993,6 +1009,9 @@ export type {
   SessionGcResult,
   SessionHandoffShowParams,
   SessionHandoffShowResult,
+  SessionLintParams,
+  SessionLintResult,
+  SessionLintViolation,
   SessionListParams,
   SessionListResult,
   SessionOps,
@@ -1105,6 +1124,8 @@ export type {
   ComplianceMetrics,
   ValidateArchiveStatsParams,
   ValidateArchiveStatsResult,
+  ValidateCanonDocsParams,
+  ValidateCanonDocsResult,
   ValidateCanonParams,
   ValidateCanonResult,
   ValidateChainParams,

package/src/operations/docs.ts

@@ -29,6 +29,7 @@
  */
 
 import type { AttachmentKind } from '../attachment.js';
+import { BUILTIN_DOC_KIND_VALUES, type BuiltinDocKind } from '../docs-taxonomy.js';
 
 // ============================================================================
 // Shared Attachment Types (API wire format)
@@ -54,28 +55,32 @@ export type { AttachmentKind } from '../attachment.js';
 /**
  * Allowed values for the `--type` taxonomy on `cleo docs add`.
  *
- * The set is closed at the CLI surface; new values require a coordinated
- * update to (1) {@link DOCS_TYPE_VALUES}, (2) the dispatch-layer guard, and
- * (3) the citty CLI flag description. The DB column itself is open (no CHECK)
- * so older clients reading a forward-compatible value gracefully degrade.
+ * As of T9788 this is derived from the canonical {@link BUILTIN_DOC_KIND_VALUES}
+ * in `docs-taxonomy.ts` — adding a kind there automatically widens this set
+ * without a duplicate edit here.
+ *
+ * Project-level extensions registered through `.cleo/docs-config.json` are
+ * NOT included in this constant (they are runtime-only, since the
+ * compile-time union must stay closed). Use {@link DocKindRegistry.list}
+ * to enumerate built-ins plus extensions at runtime.
  *
  * @task T9637 (T-DOCS-SLUG-2)
+ * @task T9788 (E-DOCS-TAXONOMY-V2 — registry consolidation)
  */
-export const DOCS_TYPE_VALUES = [
-  'spec',
-  'adr',
-  'research',
-  'handoff',
-  'note',
-  'llm-readme',
-] as const;
+export const DOCS_TYPE_VALUES: ReadonlyArray<BuiltinDocKind> =
+  BUILTIN_DOC_KIND_VALUES as ReadonlyArray<BuiltinDocKind>;
 
 /**
  * Closed-set type alias for {@link DOCS_TYPE_VALUES}.
  *
+ * As of T9788 this aliases {@link BuiltinDocKind} from the canonical
+ * registry — the union widens automatically when a new built-in kind
+ * is added to {@link BUILTIN_DOC_KINDS}.
+ *
  * @task T9637
+ * @task T9788
  */
-export type DocsType = (typeof DOCS_TYPE_VALUES)[number];
+export type DocsType = BuiltinDocKind;
 
 /**
  * Flattened wire-format attachment row returned by docs query operations.
@@ -169,16 +174,38 @@ export interface AttachmentRecord {
 // docs.list — list attachments for an owner
 // --------------------------------------------------------------------------
 
+/**
+ * Sort key for `docs.list` results.
+ *
+ * - `newest` — descending by `createdAt` (default — most recent first).
+ * - `sha`    — ascending by `sha256` (stable lexicographic).
+ * - `slug`   — ascending by `slug`; entries without a slug sort last.
+ *
+ * @task T9792
+ */
+export type DocsListOrderBy = 'newest' | 'sha' | 'slug';
+
+/**
+ * Default maximum number of rows returned by `docs.list` when the caller
+ * does not pass an explicit `limit`. Mirrored on the CLI flag default so the
+ * dispatch and CLI surfaces agree on the browsing window.
+ *
+ * @task T9792
+ */
+export const DOCS_LIST_DEFAULT_LIMIT = 50;
+
 /**
  * Parameters for `docs.list`.
  *
- * Exactly one of `task`, `session`, `observation`, or `project` must be
- * provided. `project=true` lists ALL attachments in the project DB
- * regardless of owner. `type` is an optional filter applicable to every
- * mode and matches the {@link DocsType} taxonomy exactly.
+ * Scope is auto-promoted to whole-project when no owner-scope flag is set
+ * (T9792). Pre-T9792 callers MUST still pass `project: true` explicitly to
+ * stay forward-compatible — the auto-promote happens at the CLI layer.
+ * `type` is an optional filter applicable to every mode and matches the
+ * {@link DocsType} taxonomy exactly.
  *
  * @task T9637 (T-DOCS-SLUG-2 — `type` filter)
  * @task T9638 (T-DOCS-SLUG-3 — `project` scope)
+ * @task T9792 (E-DOCS-LIST-UX-FIX — auto-promote project scope + limit + orderBy)
  */
 export interface DocsListParams {
   /** Task identifier to list attachments for. */
@@ -199,6 +226,20 @@ export interface DocsListParams {
    * @task T9637
    */
   type?: DocsType;
+  /**
+   * Maximum number of rows to return. Defaults to
+   * {@link DOCS_LIST_DEFAULT_LIMIT} when omitted. Values `<= 0` are treated
+   * as "no limit" so agents can opt-in to the full result set explicitly.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Sort key for the returned rows. Defaults to `newest` when omitted.
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
 }
 
 /**
@@ -218,8 +259,41 @@ export interface DocsListResult {
   project?: boolean;
   /** Type taxonomy filter, echoed back from the request when provided. */
   type?: DocsType;
-  /** Count of attachments for this owner. */
+  /** Count of attachments for this owner (after limit + filters). */
   count: number;
+  /**
+   * Total number of attachments matching the scope + filters BEFORE the
+   * `limit` window was applied. Only emitted when `limit` truncated the
+   * result set so consumers can distinguish "fewer than limit" from
+   * "limit truncated".
+   *
+   * @task T9792
+   */
+  totalCount?: number;
+  /**
+   * Effective limit applied to this response. Mirrored from the request
+   * (or {@link DOCS_LIST_DEFAULT_LIMIT} when the request did not set one)
+   * so consumers can paginate without re-deriving the default.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Effective sort key applied to this response. Mirrored from the request
+   * (or `"newest"` when the request did not set one).
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
+  /**
+   * Optional human-readable hint surfaced when a default behaviour kicked
+   * in (e.g. project scope auto-promoted because no scope was passed). The
+   * CLI surfaces this through `meta.hint` so JSON consumers can detect that
+   * a narrower invocation may have been intended.
+   *
+   * @task T9792
+   */
+  hint?: string;
   /** Attachment metadata array. */
   attachments: DocsAttachmentRow[];
   /** Current attachment backend in use. */

package/src/operations/session.ts

@@ -587,6 +587,76 @@ export interface SessionRecordAssumptionResult {
   timestamp: string;
 }
 
+// session.lint — agent-accountability harness (T9797)
+
+/**
+ * Parameters for `session.lint`.
+ *
+ * Scans a Claude Code-style session transcript (`*.jsonl`) for raw
+ * markdown writes that bypass the docs SSoT. Flags any tool call whose
+ * `file_path` lands under a `rawMdPaths` entry whose owning DocKind has
+ * `rawMdAllowed: false` in `.cleo/canon.yml`.
+ *
+ * @task T9797
+ */
+export interface SessionLintParams {
+  /**
+   * Absolute path to the `.jsonl` transcript to scan. Required.
+   */
+  transcript: string;
+}
+
+/**
+ * One violation surfaced by `session.lint`.
+ *
+ * Mirrors `CanonLintViolation` from
+ * `packages/core/src/session/canon-lint.ts` (the SDK-level engine).
+ *
+ * @task T9797
+ */
+export interface SessionLintViolation {
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** Anthropic `tool_use.id` (e.g. `toolu_01ABC...`). May be empty. */
+  toolUseId: string;
+  /** Tool name — `Write`, `Edit`, or `MultiEdit`. */
+  tool: string;
+  /** Repo-relative path the agent attempted to write. */
+  path: string;
+  /** Owning DocKind id (e.g. `adr`, `note`). */
+  docKind: string;
+  /** Matching `rawMdPaths` entry (e.g. `.cleo/adrs/`). */
+  matchedPath: string;
+  /** Categorical reason — always `'raw-md-canonical'` today. */
+  kind: 'raw-md-canonical';
+  /** First 200 chars of the violating content. */
+  evidence: string;
+  /** Suggested fix command. */
+  fix: string;
+}
+
+/**
+ * Result of `session.lint`.
+ *
+ * @task T9797
+ */
+export interface SessionLintResult {
+  /** Absolute transcript path that was scanned. */
+  transcriptPath: string;
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** True when no violations were flagged. */
+  passed: boolean;
+  /** Number of `Write`/`Edit`/`MultiEdit` tool calls inspected. */
+  scanned: number;
+  /** Violations in transcript order. Empty when `passed === true`. */
+  violations: SessionLintViolation[];
+  /** Non-fatal warnings (e.g. JSON parse failures on isolated lines). */
+  warnings: string[];
+  /** `'enforced'` when canon.yml present, `'no-canon'` when missing. */
+  mode: 'enforced' | 'no-canon';
+}
+
 // ---------------------------------------------------------------------------
 // Typed operation record (Wave D adapter — T975)
 // ---------------------------------------------------------------------------
@@ -619,4 +689,5 @@ export type SessionOps = {
     SessionRecordAssumptionParams,
     SessionRecordAssumptionResult,
   ];
+  readonly lint: readonly [SessionLintParams, SessionLintResult];
 };

package/src/operations/validate.ts

@@ -277,6 +277,39 @@ export interface ValidateCanonResult {
   assertions: Array<{ passed: boolean }>;
 }
 
+/**
+ * Params for `check.canon.docs` — the T9796 docs-routing CI gate.
+ *
+ * `baseRef` defaults to `origin/main` and is overridden in CI to
+ * `origin/${{ github.base_ref }}` so PRs targeting any branch work.
+ * `candidateFiles` is a test seam — when supplied, bypasses `git diff`
+ * and treats the list as the candidate set.
+ *
+ * @task T9796 — E-DOCS-CANON-LOCKDOWN
+ */
+export interface ValidateCanonDocsParams {
+  baseRef?: string;
+  candidateFiles?: ReadonlyArray<string>;
+}
+
+/**
+ * Result envelope returned by `check.canon.docs`.
+ *
+ * @task T9796
+ */
+export interface ValidateCanonDocsResult {
+  passed: boolean;
+  baseRef: string;
+  scanned: number;
+  violations: ReadonlyArray<{
+    file: string;
+    kind: string;
+    matchedPath: string;
+    fix: string;
+  }>;
+  mode: 'enforced' | 'no-canon';
+}
+
 export interface ValidateWorkflowComplianceParams {
   since?: string;
 }
@@ -350,6 +383,7 @@ export type CheckOps = {
   readonly grade: readonly [ValidateGradeParams, ValidateGradeResult];
   readonly 'grade.list': readonly [ValidateGradeListParams, ValidateGradeListResult];
   readonly canon: readonly [ValidateCanonParams, ValidateCanonResult];
+  readonly 'canon.docs': readonly [ValidateCanonDocsParams, ValidateCanonDocsResult];
   readonly 'workflow.compliance': readonly [
     ValidateWorkflowComplianceParams,
     ValidateWorkflowComplianceResult,