@cleocode/contracts 2026.5.95 → 2026.5.97

package/src/__tests__/provenance.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Structural-equivalence tests for the provenance graph contracts.
+ *
+ * These tests pin the literal shapes of the 16 provenance/release/BRAIN
+ * unions promoted in Phase 0c (T9955) so that accidental narrowing or
+ * widening produces a compile-time failure during `tsc -b` in the CI gate.
+ *
+ * The compile-time assertions use the conditional-equality trick
+ * (`Equals<A, B>`) so any structural drift produces a TS2322 or TS2344 at
+ * build time. The runtime `expect` shape sanity check below is a thin
+ * smoke verification that representative literals satisfy each union — it
+ * does NOT exercise behavior (these are pure type contracts with no
+ * runtime).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  BrainReleaseLinkType,
+  CommitConventionalType,
+  CommitFileChangeType,
+  CommitLinkKind,
+  CommitLinkSource,
+  PrLinkKind,
+  PrLinkSource,
+  PrState,
+  ReleaseArtifactType,
+  ReleaseChangeType,
+  ReleaseChannel,
+  ReleaseClassifiedBy,
+  ReleaseImpact,
+  ReleaseKind,
+  ReleaseScheme,
+  ReleaseStatus,
+} from '../provenance.js';
+
+// ─── Compile-time structural-equality helpers ───────────────────────
+
+/** Resolve to `1` IFF `A` and `B` are mutually assignable; `2` otherwise. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? 1 : 2;
+
+/** Compile-time assert that `T` resolves to `1`. */
+type AssertEquals1<T extends 1> = T;
+
+// ─── PrState pin ────────────────────────────────────────────────────
+
+type _PrStateShape = 'open' | 'closed' | 'merged';
+type _AssertPrStatePinned = AssertEquals1<Equals<PrState, _PrStateShape>>;
+
+// ─── CommitLinkKind pin ─────────────────────────────────────────────
+
+type _CommitLinkKindShape = 'implements' | 'fixes' | 'refactors' | 'tests' | 'docs' | 'reverts';
+type _AssertCommitLinkKindPinned = AssertEquals1<Equals<CommitLinkKind, _CommitLinkKindShape>>;
+
+// ─── ReleaseStatus pin (unified — admits both pipelines) ────────────
+
+type _ReleaseStatusShape =
+  | 'planned'
+  | 'pr-opened'
+  | 'pr-merged'
+  | 'published'
+  | 'reconciled'
+  | 'prepared'
+  | 'committed'
+  | 'tagged'
+  | 'pushed'
+  | 'rolled_back'
+  | 'failed'
+  | 'cancelled';
+type _AssertReleaseStatusPinned = AssertEquals1<Equals<ReleaseStatus, _ReleaseStatusShape>>;
+
+// ─── ReleaseChangeType pin (12-value taxonomy) ──────────────────────
+
+type _ReleaseChangeTypeShape =
+  | 'feature'
+  | 'enhancement'
+  | 'bug'
+  | 'hotfix'
+  | 'security'
+  | 'breaking'
+  | 'refactor'
+  | 'docs'
+  | 'chore'
+  | 'revert'
+  | 'deprecation'
+  | 'infrastructure';
+type _AssertReleaseChangeTypePinned = AssertEquals1<
+  Equals<ReleaseChangeType, _ReleaseChangeTypeShape>
+>;
+
+// ─── ReleaseArtifactType pin ────────────────────────────────────────
+
+type _ReleaseArtifactTypeShape =
+  | 'npm'
+  | 'cargo'
+  | 'docker'
+  | 'pypi'
+  | 'github-release'
+  | 'binary'
+  | 'github-tag';
+type _AssertReleaseArtifactTypePinned = AssertEquals1<
+  Equals<ReleaseArtifactType, _ReleaseArtifactTypeShape>
+>;
+
+// ─── BrainReleaseLinkType pin ───────────────────────────────────────
+
+type _BrainReleaseLinkTypeShape = 'approved-by' | 'documented-in' | 'derived-from' | 'observed-in';
+type _AssertBrainReleaseLinkTypePinned = AssertEquals1<
+  Equals<BrainReleaseLinkType, _BrainReleaseLinkTypeShape>
+>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('provenance contracts', () => {
+  it('PrState union covers exactly the 3 GitHub PR states', () => {
+    const all: PrState[] = ['open', 'closed', 'merged'];
+    expect(all).toHaveLength(3);
+  });
+
+  it('PrLinkSource enumerates all 5 discovery sources', () => {
+    const all: PrLinkSource[] = ['pr-title', 'pr-body', 'branch-name', 'commit-trailer', 'manual'];
+    expect(all).toHaveLength(5);
+  });
+
+  it('PrLinkKind extends CommitLinkKind with the "tracks" addition', () => {
+    const commit: CommitLinkKind = 'implements';
+    const pr: PrLinkKind = commit; // every commit-link-kind is a valid pr-link-kind
+    expect(pr).toBe('implements');
+    const tracks: PrLinkKind = 'tracks';
+    expect(tracks).toBe('tracks');
+  });
+
+  it('CommitConventionalType enumerates the canonical CC prefixes plus "breaking"', () => {
+    const ccs: CommitConventionalType[] = [
+      'feat',
+      'fix',
+      'chore',
+      'docs',
+      'refactor',
+      'test',
+      'build',
+      'ci',
+      'perf',
+      'revert',
+      'breaking',
+    ];
+    expect(ccs).toHaveLength(11);
+    expect(ccs).toContain('breaking');
+  });
+
+  it('CommitLinkSource and CommitLinkKind are independent unions', () => {
+    const src: CommitLinkSource = 'commit-trailer';
+    const kind: CommitLinkKind = 'implements';
+    expect(src).toBe('commit-trailer');
+    expect(kind).toBe('implements');
+  });
+
+  it('CommitFileChangeType matches the git status letter codes', () => {
+    const codes: CommitFileChangeType[] = ['A', 'M', 'D', 'R', 'C'];
+    expect(codes).toHaveLength(5);
+  });
+
+  it('ReleaseScheme enumerates calver/semver/calver-suffix', () => {
+    const schemes: ReleaseScheme[] = ['calver', 'semver', 'calver-suffix'];
+    expect(schemes).toHaveLength(3);
+  });
+
+  it('ReleaseChannel enumerates the provenance-layer channels', () => {
+    const channels: ReleaseChannel[] = ['latest', 'beta', 'dev', 'hotfix'];
+    expect(channels).toHaveLength(4);
+  });
+
+  it('ReleaseKind enumerates regular/hotfix/prerelease', () => {
+    const kinds: ReleaseKind[] = ['regular', 'hotfix', 'prerelease'];
+    expect(kinds).toHaveLength(3);
+  });
+
+  it('ReleaseStatus admits BOTH new-pipeline and legacy-pipeline statuses', () => {
+    const newPipeline: ReleaseStatus[] = [
+      'planned',
+      'pr-opened',
+      'pr-merged',
+      'published',
+      'reconciled',
+    ];
+    const legacyPipeline: ReleaseStatus[] = ['prepared', 'committed', 'tagged', 'pushed'];
+    const terminals: ReleaseStatus[] = ['rolled_back', 'failed', 'cancelled'];
+    expect(newPipeline).toHaveLength(5);
+    expect(legacyPipeline).toHaveLength(4);
+    expect(terminals).toHaveLength(3);
+  });
+
+  it('ReleaseChangeType enumerates the 12 CLEO change types', () => {
+    const types: ReleaseChangeType[] = [
+      'feature',
+      'enhancement',
+      'bug',
+      'hotfix',
+      'security',
+      'breaking',
+      'refactor',
+      'docs',
+      'chore',
+      'revert',
+      'deprecation',
+      'infrastructure',
+    ];
+    expect(types).toHaveLength(12);
+  });
+
+  it('ReleaseImpact enumerates the 4 semver-bump assessments', () => {
+    const impacts: ReleaseImpact[] = ['major', 'minor', 'patch', 'none'];
+    expect(impacts).toHaveLength(4);
+  });
+
+  it('ReleaseClassifiedBy enumerates auto/manual/approved provenance', () => {
+    const provenance: ReleaseClassifiedBy[] = ['auto', 'manual', 'approved'];
+    expect(provenance).toHaveLength(3);
+  });
+
+  it('ReleaseArtifactType enumerates the 7 supported artifact archetypes', () => {
+    const types: ReleaseArtifactType[] = [
+      'npm',
+      'cargo',
+      'docker',
+      'pypi',
+      'github-release',
+      'binary',
+      'github-tag',
+    ];
+    expect(types).toHaveLength(7);
+  });
+
+  it('BrainReleaseLinkType enumerates the 4 BRAIN↔release semantics', () => {
+    const links: BrainReleaseLinkType[] = [
+      'approved-by',
+      'documented-in',
+      'derived-from',
+      'observed-in',
+    ];
+    expect(links).toHaveLength(4);
+  });
+
+  // The five `_Assert…Pinned` aliases above will fail compilation if any
+  // shape drifts. The following references prevent unused-locals
+  // diagnostics from removing them.
+  it('compile-time pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _AssertPrStatePinned,
+      _AssertCommitLinkKindPinned,
+      _AssertReleaseStatusPinned,
+      _AssertReleaseChangeTypePinned,
+      _AssertReleaseArtifactTypePinned,
+      _AssertBrainReleaseLinkTypePinned,
+    ] = [1, 1, 1, 1, 1, 1];
+    expect(pinned).toEqual([1, 1, 1, 1, 1, 1]);
+  });
+});

package/src/__tests__/scaffold-diagnostics.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Structural-equivalence tests for the scaffold-diagnostics contracts.
+ *
+ * These tests pin the field shapes of {@link ScaffoldResult},
+ * {@link CheckStatus}, {@link CheckResult}, and {@link HookCheckResult}
+ * so accidental narrowing or widening triggers a compile-time failure
+ * during `tsc -b` in the CI gate.
+ *
+ * The compile-time assertions use the conditional-equality trick
+ * (`Equals<A, B>`) so any structural drift produces a TS2322 or TS2344
+ * at build time. The runtime `expect` shape sanity check below is a
+ * thin smoke verification that constructible literals satisfy each
+ * interface — it does NOT exercise behavior (these are pure type
+ * contracts with no runtime).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type {
+  CheckResult,
+  CheckStatus,
+  HookCheckResult,
+  ScaffoldResult,
+} from '../scaffold-diagnostics.js';
+
+// ─── Compile-time structural-equality helpers ───────────────────────
+
+/** Resolve to `1` IFF `A` and `B` are mutually assignable; `2` otherwise. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? 1 : 2;
+
+/** Compile-time assert that `T` resolves to `1`. */
+type AssertEquals1<T extends 1> = T;
+
+// ─── ScaffoldResult shape pin ───────────────────────────────────────
+
+type _ScaffoldResultShape = {
+  action: 'created' | 'repaired' | 'skipped';
+  path: string;
+  details?: string;
+};
+
+type _AssertScaffoldResultPinned = AssertEquals1<Equals<ScaffoldResult, _ScaffoldResultShape>>;
+
+// ─── CheckStatus shape pin ──────────────────────────────────────────
+
+type _CheckStatusShape = 'passed' | 'failed' | 'warning' | 'info';
+
+type _AssertCheckStatusPinned = AssertEquals1<Equals<CheckStatus, _CheckStatusShape>>;
+
+// ─── CheckResult shape pin ──────────────────────────────────────────
+
+type _CheckResultShape = {
+  id: string;
+  category: string;
+  status: CheckStatus;
+  message: string;
+  details: Record<string, unknown>;
+  fix: string | null;
+};
+
+type _AssertCheckResultPinned = AssertEquals1<Equals<CheckResult, _CheckResultShape>>;
+
+// ─── HookCheckResult shape pin ──────────────────────────────────────
+
+type _HookCheckResultShape = {
+  hook: string;
+  installed: boolean;
+  current: boolean;
+  sourcePath: string;
+  installedPath: string;
+};
+
+type _AssertHookCheckResultPinned = AssertEquals1<Equals<HookCheckResult, _HookCheckResultShape>>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('scaffold-diagnostics contracts', () => {
+  it('ScaffoldResult is constructible with the canonical shape', () => {
+    const r: ScaffoldResult = { action: 'created', path: '/tmp/x' };
+    expect(r.action).toBe('created');
+    expect(r.path).toBe('/tmp/x');
+    expect(r.details).toBeUndefined();
+  });
+
+  it('ScaffoldResult accepts the optional details field', () => {
+    const r: ScaffoldResult = {
+      action: 'repaired',
+      path: '/tmp/y',
+      details: 'rewrote stale entry',
+    };
+    expect(r.details).toBe('rewrote stale entry');
+  });
+
+  it('CheckResult is constructible with the canonical shape', () => {
+    const r: CheckResult = {
+      id: 'cleo_structure',
+      category: 'scaffold',
+      status: 'passed',
+      message: 'All subdirs present',
+      details: { missing: [] },
+      fix: null,
+    };
+    expect(r.status).toBe('passed');
+    expect(r.fix).toBeNull();
+  });
+
+  it('CheckStatus union covers exactly the 4 documented values', () => {
+    const statuses: CheckStatus[] = ['passed', 'failed', 'warning', 'info'];
+    expect(statuses).toHaveLength(4);
+  });
+
+  it('HookCheckResult is constructible with the canonical shape', () => {
+    const r: HookCheckResult = {
+      hook: 'pre-commit',
+      installed: true,
+      current: false,
+      sourcePath: '/pkg/templates/git-hooks/pre-commit',
+      installedPath: '/proj/.git/hooks/pre-commit',
+    };
+    expect(r.installed).toBe(true);
+    expect(r.current).toBe(false);
+  });
+
+  // The four `_Assert…Pinned` aliases above will fail compilation if
+  // any shape drifts. The following references prevent unused-locals
+  // diagnostics from removing them.
+  it('compile-time pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _AssertScaffoldResultPinned,
+      _AssertCheckStatusPinned,
+      _AssertCheckResultPinned,
+      _AssertHookCheckResultPinned,
+    ] = [1, 1, 1, 1];
+    expect(pinned).toEqual([1, 1, 1, 1]);
+  });
+});

package/src/dispatch/identity.ts

@@ -0,0 +1,109 @@
+/**
+ * Dispatch identity contracts.
+ *
+ * Canonical home for the three primitive identity types every dispatch
+ * operation is keyed on:
+ *
+ *   - {@link Gateway}          — CQRS read vs write classification
+ *   - {@link Tier}             — progressive-disclosure tier (0/1/2)
+ *   - {@link CanonicalDomain}  — the closed set of dispatch domains
+ *
+ * Promoted to `@cleocode/contracts` in Phase 0b of the SG-ARCH-SOLID
+ * Saga (T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954) alongside
+ * {@link OperationDef} / {@link Resolution}. Originally defined in
+ * `packages/cleo/src/dispatch/types.ts` (lines 16, 27, 58, 86). The
+ * `packages/cleo` definition is now a re-export shim — every consumer
+ * continues to compile unchanged.
+ *
+ * `CANONICAL_DOMAINS` remains the runtime SSoT — adding/removing a
+ * domain still requires editing the array here exactly as before.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+
+// ── Gateway ──────────────────────────────────────────────────────────
+
+/**
+ * CQRS gateway: read-only queries vs state-modifying mutations.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:16`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type Gateway = 'query' | 'mutate';
+
+// ── Tier ─────────────────────────────────────────────────────────────
+
+/**
+ * Progressive disclosure tier.
+ *
+ * - `0` — tasks + session (~80% of agents)
+ * - `1` — + memory + check (~15% of agents)
+ * - `2` — + pipeline + orchestrate + tools + admin + nexus (~5%)
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:27`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type Tier = 0 | 1 | 2;
+
+// ── CanonicalDomain ──────────────────────────────────────────────────
+
+/**
+ * The closed set of dispatch canonical-domain names.
+ *
+ * T964: `conduit` promoted to first-class domain (supersedes ADR-042 Decision 1).
+ * CONDUIT is agent-to-agent messaging and is semantically disjoint from
+ * ORCHESTRATE (wave planning + spawn-prompt generation). The original
+ * "exactly 10 canonical domains" invariant that justified folding CONDUIT
+ * under ORCHESTRATE has been broken multiple times (intelligence, diagnostics,
+ * docs, playbook); promoting CONDUIT aligns registry with wire-format, CLI,
+ * and core module structure at zero behavior cost.
+ *
+ * T1726: `sentient` and `release` promoted to first-class domains. Both were
+ * reachable via the CLI and had registered DomainHandlers but were absent from
+ * CANONICAL_DOMAINS, making them invisible to SDK consumers via OPERATIONS.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/types.ts:58`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export const CANONICAL_DOMAINS = [
+  'tasks',
+  'session',
+  'memory',
+  'check',
+  'pipeline',
+  'orchestrate',
+  'tools',
+  'admin',
+  'nexus',
+  'sticky',
+  'intelligence',
+  'diagnostics',
+  'docs',
+  'playbook',
+  'conduit',
+  'sentient',
+  'release',
+  'llm',
+  // T9528: provenance-graph maintenance verbs (backfill, verify, repair).
+  'provenance',
+  // T9536: `cleo upgrade workflows` — re-render release-pipeline workflow
+  // templates + 3-way merge with `.workflow-overrides.yml`.
+  'upgrade',
+  // T9546/T9547: 'cleo worktree list/prune/force-unlock' — worktree lifecycle.
+  'worktree',
+  // T9973: 'cleo focus <id>' — single-envelope task orientation (8 calls → 1).
+  'focus',
+] as const;
+
+/**
+ * One of the canonical dispatch domain names.
+ *
+ * Derived as a string-literal union from {@link CANONICAL_DOMAINS} so
+ * adding/removing a domain in the array automatically updates the type.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export type CanonicalDomain = (typeof CANONICAL_DOMAINS)[number];

package/src/dispatch/operation-def.ts

@@ -0,0 +1,102 @@
+/**
+ * Dispatch operation-def contracts.
+ *
+ * Canonical home for the {@link OperationDef} and {@link Resolution}
+ * interfaces that describe a single dispatchable CQRS operation and the
+ * result of resolving one from the operation registry.
+ *
+ * Promoted to `@cleocode/contracts` in Phase 0b of the SG-ARCH-SOLID Saga
+ * (T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954). Originally defined in
+ * `packages/cleo/src/dispatch/registry.ts` (lines 14-41 / 43-53). The
+ * `packages/cleo` definition is now a re-export shim — every consumer of
+ * `OperationDef` / `Resolution` continues to compile unchanged.
+ *
+ * This promotion unblocks E-CLI-BOUNDARY (T9833) — the registry data
+ * relocation can now move {@link OPERATIONS} into `@cleocode/contracts`
+ * (or split it without changing the type's canonical home) without
+ * crossing a circular dependency.
+ *
+ * NOT promoted (intentional — different concern):
+ *   - `OPERATIONS: OperationDef[]` — the registry data itself remains in
+ *     `packages/cleo/src/dispatch/registry.ts` and is the subject of the
+ *     follow-up E-CLI-BOUNDARY epic.
+ *   - The helper functions (`resolve`, `validateRequiredParams`,
+ *     `getByDomain`, `getByGateway`, `getByTier`, `getActiveDomains`,
+ *     `getCounts`, `deriveGatewayMatrix`, `getGatewayDomains`) — they
+ *     operate on the data and remain colocated with it.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+
+import type { ParamDef } from '../operations/params.js';
+import type { CanonicalDomain, Gateway, Tier } from './identity.js';
+
+// Re-export the upstream identity types so consumers can pull every
+// dispatch-related shape from a single subpath without having to know
+// which leaf file each type lives in.
+export type { CanonicalDomain, Gateway, ParamDef, Tier };
+
+// ── OperationDef ─────────────────────────────────────────────────────
+
+/**
+ * Definition of a single dispatchable operation.
+ *
+ * Each entry in the operation registry (currently in
+ * `packages/cleo/src/dispatch/registry.ts`'s `OPERATIONS` array)
+ * conforms to this interface. The dispatcher uses these definitions to
+ * (1) route a {@link CanonicalDomain} + operation-name + {@link Gateway}
+ * triple to its handler, (2) validate that all required parameters are
+ * present, and (3) emit dispatch-validation telemetry.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/registry.ts:14-41`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export interface OperationDef {
+  /** The CQRS gateway ('query' or 'mutate'). */
+  gateway: Gateway;
+  /** The canonical domain this operation belongs to. */
+  domain: CanonicalDomain;
+  /** The specific operation name (e.g. 'show', 'skill.list'). */
+  operation: string;
+  /** Brief description of what the operation does. */
+  description: string;
+  /** Agent progressive-disclosure tier (0=basic, 1=memory/check, 2=full). */
+  tier: Tier;
+  /** Whether the operation is safe to retry. */
+  idempotent: boolean;
+  /** Whether this operation requires an active session. */
+  sessionRequired: boolean;
+  /** List of parameter keys that MUST be present in the request. */
+  requiredParams: string[];
+  /**
+   * Fully-described parameter list. Replaces `requiredParams` when populated.
+   * Empty array = "no declared params" (not "no params accepted").
+   * Optional during T4897 migration — defaults to [] when absent.
+   * @see T4897 for progressive migration
+   */
+  params?: ParamDef[];
+}
+
+// ── Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Resolution output for a dispatch request.
+ *
+ * Returned by the `resolve(gateway, domain, operation)` helper in the
+ * operation registry. Bundles the resolved {@link OperationDef} with the
+ * already-typed `domain` + `operation` strings so downstream consumers
+ * don't have to re-narrow them.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/registry.ts:43-53`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export interface Resolution {
+  /** The canonical domain. */
+  domain: CanonicalDomain;
+  /** The operation name. */
+  operation: string;
+  /** The definition of the matched operation. */
+  def: OperationDef;
+}

package/src/doctor.ts

@@ -5,12 +5,19 @@
  * `<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.
  *
+ * Also contains the comprehensive worktree audit types (T9808) covering:
+ *   - Orphan `.cleo/` dirs inside ANY git worktree (not just .claude/worktrees/)
+ *   - Worktrees outside the canonical XDG location
+ *   - Rogue `.cleo/worktrees/` DIRECTORY (council D009 — only .json sentinel allowed)
+ *
  * Consumed by:
  *   - `packages/core/src/doctor/worktree-orphans.ts` (scan + prune primitives)
  *   - `packages/cleo/src/cli/commands/doctor.ts` (CLI flags)
  *
  * @task T9790
+ * @task T9808
  * @epic T9790
+ * @epic T9808
  */
 
 /**
@@ -96,6 +103,61 @@ export interface PruneResult {
   prunedAt: string;
 }
 
+// ============================================================================
+// Comprehensive Worktree Audit (T9808 — council D009)
+// ============================================================================
+
+/**
+ * Anomaly kinds surfaced by {@link auditWorktreeOrphansComprehensive}.
+ *
+ * - `orphan-cleo-dir`: a `.cleo/` directory found inside a git worktree path
+ *   (any worktree, not just those under `.claude/worktrees/`)
+ * - `non-canonical-location`: a worktree exists outside the canonical XDG
+ *   path (`~/.local/share/cleo/worktrees/<projectHash>/<taskId>/`)
+ * - `rogue-worktrees-directory`: `.cleo/worktrees/` exists as a DIRECTORY
+ *   (council D009: only a `.json` sentinel file is permitted there)
+ */
+export type WorktreeAnomalyKind =
+  | 'orphan-cleo-dir'
+  | 'non-canonical-location'
+  | 'rogue-worktrees-directory';
+
+/**
+ * One anomaly surfaced by the comprehensive worktree audit.
+ */
+export interface WorktreeAnomaly {
+  /** Machine-readable anomaly type. */
+  kind: WorktreeAnomalyKind;
+  /**
+   * Absolute path of the affected location.
+   * - For `orphan-cleo-dir`: path to the offending `.cleo/` directory.
+   * - For `non-canonical-location`: path to the non-canonical worktree root.
+   * - For `rogue-worktrees-directory`: path to the `.cleo/worktrees/` directory.
+   */
+  path: string;
+  /** Human-readable description including suggested remediation. */
+  description: string;
+  /**
+   * The git worktree path that triggered this anomaly (from `git worktree list`),
+   * or `null` for anomalies not tied to a specific worktree entry.
+   */
+  worktreePath: string | null;
+}
+
+/**
+ * Result returned by {@link auditWorktreeOrphansComprehensive}.
+ */
+export interface ComprehensiveAuditResult {
+  /** Absolute path to the project root that was audited. */
+  projectRoot: string;
+  /** Canonical XDG worktrees root for this project (expected location). */
+  canonicalWorktreesRoot: string;
+  /** All anomalies detected. Sorted by `kind` then `path`. */
+  anomalies: WorktreeAnomaly[];
+  /** Total anomaly count. Non-zero triggers exit code 2. */
+  count: number;
+}
+
 /**
  * One line appended to `.cleo/audit/worktree-prune.jsonl` per prune
  * operation. Extends the existing audit-log schema (timestamp +