@cleocode/contracts 2026.5.95 → 2026.5.97

package/dist/scaffold-diagnostics.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Scaffold + diagnostic result contracts.
+ *
+ * Canonical home for the result shapes produced by CLEO's directory/file
+ * scaffolding utilities (`ensure*`) and read-only health-check utilities
+ * (`check*`). Promoted to `@cleocode/contracts` in Phase 0a of the
+ * SG-ARCH-SOLID Saga to eliminate duplicate definitions that previously
+ * lived in `packages/core/src/scaffold.ts`, `injection.ts`, `hooks.ts`,
+ * `schema-management.ts`, and `validation/doctor/checks.ts`.
+ *
+ * Consolidated types:
+ *   - {@link ScaffoldResult} — was defined 3× in core (scaffold/injection/hooks)
+ *   - {@link CheckStatus}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link CheckResult}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link HookCheckResult} — single canonical definition (no prior duplication;
+ *     promoted here to keep all scaffold-diagnostic shapes co-located)
+ *
+ * NOT consolidated (intentional — different domain shape):
+ *   - `CheckResult` in `packages/core/src/schema-management.ts` is a
+ *     `{ ok, installed, bundled, missing, stale }` schema-install report,
+ *     unrelated to diagnostic checks. It retains its local definition and
+ *     will be renamed in a follow-up slice if/when its naming collision
+ *     warrants a separate cleanup task.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+/**
+ * Result of an `ensure*` scaffolding operation.
+ *
+ * All ensure functions in `@cleocode/core` are idempotent — they may
+ * create, repair, or skip the requested resource and report which
+ * action they took.
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/injection.ts`
+ *   - `packages/core/src/hooks.ts`
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface ScaffoldResult {
+    /** What action was taken: created, repaired, or skipped. */
+    action: 'created' | 'repaired' | 'skipped';
+    /** Filesystem path that was operated on. */
+    path: string;
+    /** Human-readable explanation of the result. */
+    details?: string;
+}
+/**
+ * Status of a `check*` diagnostic.
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/validation/doctor/checks.ts`
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export type CheckStatus = 'passed' | 'failed' | 'warning' | 'info';
+/**
+ * Result of a `check*` diagnostic (used by `cleo doctor` and scaffold
+ * health checks).
+ *
+ * Originally defined in:
+ *   - `packages/core/src/scaffold.ts`
+ *   - `packages/core/src/validation/doctor/checks.ts`
+ *
+ * The scaffold.ts and doctor/checks.ts definitions were structurally
+ * identical; this is the consolidated shape with TSDoc preserved.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface CheckResult {
+    /** Unique check identifier (e.g. "cleo_structure", "sqlite_db"). */
+    id: string;
+    /** Category grouping (e.g. "scaffold", "global"). */
+    category: string;
+    /** Diagnostic outcome: passed, failed, warning, or info. */
+    status: CheckStatus;
+    /** Human-readable description of the check result. */
+    message: string;
+    /** Structured metadata about the check (paths, sizes, missing items). */
+    details: Record<string, unknown>;
+    /** Suggested CLI command to fix the issue, or null if passed. */
+    fix: string | null;
+}
+/**
+ * Result of a git-hook installation check.
+ *
+ * Reports whether a managed hook (commit-msg, pre-commit, pre-push) is
+ * installed in `.git/hooks/` and whether the installed copy matches the
+ * source template under `packages/core/templates/git-hooks/`.
+ *
+ * Originally defined in `packages/core/src/hooks.ts`. Promoted here to
+ * co-locate all scaffold-diagnostic shapes.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export interface HookCheckResult {
+    /** Hook name (commit-msg, pre-commit, pre-push). */
+    hook: string;
+    /** Whether the hook is installed at `.git/hooks/<hook>`. */
+    installed: boolean;
+    /** Whether the installed hook bytes match the source template. */
+    current: boolean;
+    /** Absolute path of the source template that should be installed. */
+    sourcePath: string;
+    /** Absolute path where the hook is (or would be) installed. */
+    installedPath: string;
+}
+//# sourceMappingURL=scaffold-diagnostics.d.ts.map

package/dist/scaffold-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-diagnostics.d.ts","sourceRoot":"","sources":["../src/scaffold-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC3C,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,EAAE,WAAW,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iEAAiE;IACjE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/scaffold-diagnostics.js

@@ -0,0 +1,28 @@
+/**
+ * Scaffold + diagnostic result contracts.
+ *
+ * Canonical home for the result shapes produced by CLEO's directory/file
+ * scaffolding utilities (`ensure*`) and read-only health-check utilities
+ * (`check*`). Promoted to `@cleocode/contracts` in Phase 0a of the
+ * SG-ARCH-SOLID Saga to eliminate duplicate definitions that previously
+ * lived in `packages/core/src/scaffold.ts`, `injection.ts`, `hooks.ts`,
+ * `schema-management.ts`, and `validation/doctor/checks.ts`.
+ *
+ * Consolidated types:
+ *   - {@link ScaffoldResult} — was defined 3× in core (scaffold/injection/hooks)
+ *   - {@link CheckStatus}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link CheckResult}   — was defined 2× in core (scaffold/doctor checks)
+ *   - {@link HookCheckResult} — single canonical definition (no prior duplication;
+ *     promoted here to keep all scaffold-diagnostic shapes co-located)
+ *
+ * NOT consolidated (intentional — different domain shape):
+ *   - `CheckResult` in `packages/core/src/schema-management.ts` is a
+ *     `{ ok, installed, bundled, missing, stale }` schema-install report,
+ *     unrelated to diagnostic checks. It retains its local definition and
+ *     will be renamed in a follow-up slice if/when its naming collision
+ *     warrants a separate cleanup task.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 (Phase 0a)
+ */
+export {};
+//# sourceMappingURL=scaffold-diagnostics.js.map

package/dist/scaffold-diagnostics.js.map

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

package/dist/session.d.ts

@@ -131,6 +131,43 @@ export interface Session {
     gradeMode?: boolean;
     /** ID of the provider adapter used for this session. @defaultValue undefined */
     providerId?: string | null;
+    /**
+     * Human-readable agent handle for multi-agent isolation (T9975).
+     *
+     * Set via `cleo session start --agent <handle>`. Allows concurrent agent
+     * sessions to be distinguished in `cleo session list --all` and enables
+     * `cleo briefing` env-precedence detection when `CLEO_SESSION_ID` is set.
+     *
+     * @defaultValue undefined
+     */
+    agentHandle?: string | null;
+    /**
+     * Denormalised scope type ("global" | "epic") for fast index queries (T9975).
+     *
+     * Derived from `scope.type` at session creation; cached in the DB column
+     * `scope_kind` to avoid JSON parsing in hot paths.
+     *
+     * @defaultValue undefined
+     */
+    scopeKind?: string | null;
+    /**
+     * Denormalised scope target ID (e.g. "T9964") for epic sessions (T9975).
+     *
+     * Derived from `scope.epicId` / `scope.rootTaskId` at session creation.
+     * NULL for global sessions.
+     *
+     * @defaultValue undefined
+     */
+    scopeId?: string | null;
+    /**
+     * ISO 8601 timestamp of the last mutation on this session (T9975).
+     *
+     * Updated on session start, task focus change, and task completion.
+     * Used by the idle auto-end lifecycle hook and `cleo session list --all`.
+     *
+     * @defaultValue undefined
+     */
+    lastActivity?: string | null;
 }
 /**
  * Result of a session start operation.

package/dist/session.d.ts.map

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

package/dist/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmJH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACL,SAAS,CAAY;IAEtC,YAAY,QAAmB;QAC7B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,iDAAiD;IACjD,MAAM,CAAC,IAAI,CAAC,QAAmB;QAC7B,OAAO,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,2CAA2C;IAC3C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,0BAA0B;IAC1B,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,kDAAkD;IAClD,UAAU;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED,4BAA4B;IAC5B,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,+CAA+C;IAC/C,cAAc,CAAC,GAAG,QAAyB;QACzC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,QAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,mEAAmE;IACnE,WAAW,CAAC,IAAY,EAAE,UAAmB;QAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACjC,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YACzC,IAAI,UAAU,IAAI,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YACnE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,UAAU,CAAC,KAA8B,EAAE,UAAU,GAAG,IAAI;QAC1D,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACvC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,OAAO,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;QACpD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,6CAA6C;IAC7C,UAAU;QACR,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAClD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,4DAA4D;IAC5D,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,gCAAgC;IAChC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwLH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACL,SAAS,CAAY;IAEtC,YAAY,QAAmB;QAC7B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,iDAAiD;IACjD,MAAM,CAAC,IAAI,CAAC,QAAmB;QAC7B,OAAO,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,2CAA2C;IAC3C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,0BAA0B;IAC1B,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,kDAAkD;IAClD,UAAU;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED,4BAA4B;IAC5B,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,+CAA+C;IAC/C,cAAc,CAAC,GAAG,QAAyB;QACzC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,QAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,mEAAmE;IACnE,WAAW,CAAC,IAAY,EAAE,UAAmB;QAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACjC,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YACzC,IAAI,UAAU,IAAI,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YACnE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,UAAU,CAAC,KAA8B,EAAE,UAAU,GAAG,IAAI;QAC1D,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACvC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,OAAO,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;QACpD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,6CAA6C;IAC7C,UAAU;QACR,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAClD,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,4DAA4D;IAC5D,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,gCAAgC;IAChC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC3C,CAAC;CACF"}

package/dist/tasks/archive.d.ts

@@ -51,8 +51,8 @@ import { z } from 'zod';
 export declare const ArchiveReason: z.ZodEnum<{
     cancelled: "cancelled";
     superseded: "superseded";
-    reconciled: "reconciled";
     verified: "verified";
+    reconciled: "reconciled";
     shadowed: "shadowed";
     "completed-unverified": "completed-unverified";
 }>;
@@ -67,8 +67,8 @@ export declare const ArchiveReason: z.ZodEnum<{
 export declare const ArchiveReasonSchema: z.ZodEnum<{
     cancelled: "cancelled";
     superseded: "superseded";
-    reconciled: "reconciled";
     verified: "verified";
+    reconciled: "reconciled";
     shadowed: "shadowed";
     "completed-unverified": "completed-unverified";
 }>;
@@ -93,7 +93,7 @@ export type ArchiveReasonValue = z.infer<typeof ArchiveReason>;
  * Useful when a Drizzle column or a discriminated union needs the raw
  * tuple form (e.g. `text('archive_reason', { enum: ARCHIVE_REASON_VALUES })`).
  */
-export declare const ARCHIVE_REASON_VALUES: ("cancelled" | "superseded" | "reconciled" | "verified" | "shadowed" | "completed-unverified")[];
+export declare const ARCHIVE_REASON_VALUES: ("cancelled" | "superseded" | "verified" | "reconciled" | "shadowed" | "completed-unverified")[];
 /**
  * The single tombstone value within {@link ArchiveReason}.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.95",
+  "version": "2026.5.97",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,30 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./provenance": {
+      "types": "./dist/provenance.d.ts",
+      "import": "./dist/provenance.js"
+    },
+    "./provenance.js": {
+      "types": "./dist/provenance.d.ts",
+      "import": "./dist/provenance.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "import": "./dist/jobs.js"
+    },
+    "./jobs.js": {
+      "types": "./dist/jobs.d.ts",
+      "import": "./dist/jobs.js"
+    },
+    "./enums": {
+      "types": "./dist/enums.d.ts",
+      "import": "./dist/enums.js"
+    },
+    "./enums.js": {
+      "types": "./dist/enums.d.ts",
+      "import": "./dist/enums.js"
+    },
     "./nexus-contract-ops": {
       "types": "./dist/nexus-contract-ops.d.ts",
       "import": "./dist/nexus-contract-ops.js"
@@ -50,6 +74,14 @@
       "types": "./dist/nexus-tasks-bridge-ops.d.ts",
       "import": "./dist/nexus-tasks-bridge-ops.js"
     },
+    "./dispatch/*": {
+      "types": "./dist/dispatch/*.d.ts",
+      "import": "./dist/dispatch/*.js"
+    },
+    "./dispatch/*.js": {
+      "types": "./dist/dispatch/*.d.ts",
+      "import": "./dist/dispatch/*.js"
+    },
     "./operations/*": {
       "types": "./dist/operations/*.d.ts",
       "import": "./dist/operations/*.js"
@@ -73,6 +105,14 @@
     "./memory/*.js": {
       "types": "./dist/memory/*.d.ts",
       "import": "./dist/memory/*.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
     }
   },
   "engines": {
@@ -98,7 +138,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.95"
+    "@cleocode/lafs": "2026.5.97"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/emit-schemas.mjs",

package/src/__tests__/enums.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Structural-equivalence + value-set tests for the task-axis enum
+ * constants promoted in Phase 0c (T9955).
+ *
+ * These tests pin the runtime value sets of the 6 `as const` arrays
+ * (`TASK_KINDS`, `TASK_SCOPES`, `TASK_SEVERITIES`, `TASK_SIZES`,
+ * `ARCHIVE_REASONS`, `TASK_RELATION_TYPES`) so that:
+ *   - The Drizzle row-type narrowing in `tasks-schema.ts` stays byte-identical.
+ *   - The DB CHECK constraints they back keep their canonical value list.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ARCHIVE_REASONS,
+  TASK_KINDS,
+  TASK_RELATION_TYPES,
+  TASK_SCOPES,
+  TASK_SEVERITIES,
+  TASK_SIZES,
+} from '../enums.js';
+
+// ─── Compile-time readonly-tuple guarantees ─────────────────────────
+
+/**
+ * Compile-time assertion that `T` is a readonly tuple (not a mutable
+ * `string[]`). Drizzle's `text({ enum })` narrowing depends on the
+ * literal tuple shape, so accidental widening MUST fail at build time.
+ */
+type _AssertReadonlyTuple<T extends readonly string[]> = T;
+
+type _PinTaskKinds = _AssertReadonlyTuple<typeof TASK_KINDS>;
+type _PinTaskScopes = _AssertReadonlyTuple<typeof TASK_SCOPES>;
+type _PinTaskSeverities = _AssertReadonlyTuple<typeof TASK_SEVERITIES>;
+type _PinTaskSizes = _AssertReadonlyTuple<typeof TASK_SIZES>;
+type _PinArchiveReasons = _AssertReadonlyTuple<typeof ARCHIVE_REASONS>;
+type _PinTaskRelationTypes = _AssertReadonlyTuple<typeof TASK_RELATION_TYPES>;
+
+// ─── Runtime value-set assertions ───────────────────────────────────
+
+describe('task-axis enum constants', () => {
+  it('TASK_KINDS holds the 6 canonical task kinds', () => {
+    expect(TASK_KINDS).toEqual(['work', 'research', 'experiment', 'bug', 'spike', 'release']);
+  });
+
+  it('TASK_SCOPES holds project / feature / unit (in canonical order)', () => {
+    expect(TASK_SCOPES).toEqual(['project', 'feature', 'unit']);
+  });
+
+  it('TASK_SEVERITIES holds P0 through P3 in increasing severity order', () => {
+    expect(TASK_SEVERITIES).toEqual(['P0', 'P1', 'P2', 'P3']);
+  });
+
+  it('TASK_SIZES holds small / medium / large (CLEO avoids time estimates)', () => {
+    expect(TASK_SIZES).toEqual(['small', 'medium', 'large']);
+  });
+
+  it('ARCHIVE_REASONS holds exactly the 6 truth-grade closure reasons', () => {
+    expect(ARCHIVE_REASONS).toEqual([
+      'verified',
+      'reconciled',
+      'superseded',
+      'shadowed',
+      'cancelled',
+      'completed-unverified',
+    ]);
+  });
+
+  it('TASK_RELATION_TYPES includes "groups" (ADR-073 Saga membership)', () => {
+    expect(TASK_RELATION_TYPES).toContain('groups');
+    expect(TASK_RELATION_TYPES).toEqual([
+      'related',
+      'blocks',
+      'duplicates',
+      'absorbs',
+      'fixes',
+      'extends',
+      'supersedes',
+      'groups',
+    ]);
+  });
+
+  it('All enum arrays are non-empty readonly tuples', () => {
+    expect(TASK_KINDS.length).toBeGreaterThan(0);
+    expect(TASK_SCOPES.length).toBeGreaterThan(0);
+    expect(TASK_SEVERITIES.length).toBeGreaterThan(0);
+    expect(TASK_SIZES.length).toBeGreaterThan(0);
+    expect(ARCHIVE_REASONS.length).toBeGreaterThan(0);
+    expect(TASK_RELATION_TYPES.length).toBeGreaterThan(0);
+  });
+
+  // The six `_Pin…` aliases above will fail compilation if any const
+  // array is accidentally widened to `string[]`. The reference below
+  // prevents unused-locals diagnostics from removing them.
+  it('compile-time readonly-tuple pins are wired (no-op at runtime)', () => {
+    const pinned: [
+      _PinTaskKinds,
+      _PinTaskScopes,
+      _PinTaskSeverities,
+      _PinTaskSizes,
+      _PinArchiveReasons,
+      _PinTaskRelationTypes,
+    ] = [
+      TASK_KINDS,
+      TASK_SCOPES,
+      TASK_SEVERITIES,
+      TASK_SIZES,
+      ARCHIVE_REASONS,
+      TASK_RELATION_TYPES,
+    ];
+    expect(pinned).toHaveLength(6);
+  });
+});

package/src/__tests__/jobs.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Structural-equivalence tests for the background-job contracts.
+ *
+ * Pins the literal shape of {@link BackgroundJobStatus} promoted in
+ * Phase 0c (T9955) so accidental narrowing or widening triggers a
+ * compile-time failure during `tsc -b` in the CI gate.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { BackgroundJobStatus } from '../jobs.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;
+
+// ─── BackgroundJobStatus shape pin ──────────────────────────────────
+
+type _BackgroundJobStatusShape =
+  | 'pending'
+  | 'running'
+  | 'complete'
+  | 'failed'
+  | 'cancelled'
+  | 'orphaned';
+
+type _AssertBackgroundJobStatusPinned = AssertEquals1<
+  Equals<BackgroundJobStatus, _BackgroundJobStatusShape>
+>;
+
+// ─── Runtime constructibility smoke ─────────────────────────────────
+
+describe('jobs contracts', () => {
+  it('BackgroundJobStatus enumerates the 6 documented lifecycle states', () => {
+    const all: BackgroundJobStatus[] = [
+      'pending',
+      'running',
+      'complete',
+      'failed',
+      'cancelled',
+      'orphaned',
+    ];
+    expect(all).toHaveLength(6);
+  });
+
+  it('BackgroundJobStatus distinguishes terminal from in-flight states', () => {
+    const terminal: BackgroundJobStatus[] = ['complete', 'failed', 'cancelled', 'orphaned'];
+    const inFlight: BackgroundJobStatus[] = ['pending', 'running'];
+    expect(terminal).toHaveLength(4);
+    expect(inFlight).toHaveLength(2);
+  });
+
+  it('Every BackgroundJobStatus is a non-empty string literal', () => {
+    const statuses: BackgroundJobStatus[] = [
+      'pending',
+      'running',
+      'complete',
+      'failed',
+      'cancelled',
+      'orphaned',
+    ];
+    for (const s of statuses) {
+      expect(s.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('compile-time pin is wired (no-op at runtime)', () => {
+    const pinned: _AssertBackgroundJobStatusPinned = 1;
+    expect(pinned).toBe(1);
+  });
+});