@cleocode/contracts 2026.5.95 → 2026.5.97

package/src/operations/worktree.ts

@@ -159,6 +159,25 @@ export interface CreateWorktreeOptions {
    * @task T1927
    */
   forceReset?: boolean;
+  /**
+   * Sparse-checkout scope pattern (T9807). When set, `createWorktree` runs
+   * `git sparse-checkout init --cone` followed by
+   * `git sparse-checkout set <spawnScope>` after `git worktree add` completes,
+   * limiting the worktree's checked-out tree to paths matching `<spawnScope>`.
+   *
+   * Exposed on `cleo orchestrate spawn` as the `--scope` flag so callers can
+   * request a lean worktree containing only the paths relevant to a task
+   * (e.g. `packages/cleo` to contain a CLI-only fix).
+   *
+   * Cone mode (`--cone`) is used for maximum checkout performance — the scope
+   * string must be a directory prefix, not an arbitrary glob.
+   *
+   * Failures are silently swallowed (best-effort) — the worktree is returned
+   * in full-checkout mode when sparse-checkout setup fails.
+   *
+   * @task T9807
+   */
+  spawnScope?: string;
 }
 
 /**
@@ -247,6 +266,14 @@ export interface DestroyWorktreeOptions {
   force?: boolean;
   /** Declarative hooks to run during destruction lifecycle. */
   hooks?: WorktreeHook[];
+  /**
+   * Free-form reason string appended to the lifecycle audit log (T9805).
+   *
+   * Examples: `'pr-merged'`, `'manual'`, `'idle-timeout'`.
+   *
+   * @default 'manual'
+   */
+  reason?: string;
 }
 
 /**
@@ -332,6 +359,16 @@ export interface PruneWorktreesOptions {
    * @default true
    */
   gitPrune?: boolean;
+  /**
+   * Abandonment-timeout threshold in days (T9805 AC2).
+   *
+   * When set, worktrees whose branch has had no commits for at least this many
+   * days AND which have no open PR associated are eligible for pruning, even
+   * if their task ID is not in a known-stale set.
+   *
+   * @default undefined — disabled; no idle-age check is performed.
+   */
+  idleDays?: number;
 }
 
 /**
@@ -375,6 +412,21 @@ export interface PruneWorktreesResult {
  */
 export type WorktreeStatusCategory = 'active' | 'stale' | 'merged' | 'orphan' | 'locked';
 
+/**
+ * Source classifier for a worktree entry.
+ *
+ * - `cleo-spawn`   — Created by `cleo orchestrate spawn` via the canonical XDG path.
+ * - `claude-agent` — Created by Claude Code Agent `isolation:worktree` dispatch (T9804).
+ * - `manual`       — Created directly via `git worktree add` without CLEO CLI involvement.
+ * - `adopted`      — Registered via `cleo worktree adopt` from an unknown origin.
+ *
+ * The `source` field enables downstream consumers (prune, dashboard, sentient daemon)
+ * to apply different policies per origin without re-querying git.
+ *
+ * @task T9804
+ */
+export type WorktreeSource = 'cleo-spawn' | 'claude-agent' | 'manual' | 'adopted';
+
 /**
  * A single structured worktree entry with full status classification.
  *
@@ -384,6 +436,7 @@ export type WorktreeStatusCategory = 'active' | 'stale' | 'merged' | 'orphan' |
  * sentient daemon) can act on without re-querying git.
  *
  * @task T9546
+ * @task T9804 — added `source` field for multi-source listing
  */
 export interface WorktreeInfo {
   /** Absolute path to the worktree directory. */
@@ -406,6 +459,22 @@ export interface WorktreeInfo {
   owningTaskStatus: string | null;
   /** Mutually-exclusive status category — see {@link WorktreeStatusCategory}. */
   statusCategory: WorktreeStatusCategory;
+  /**
+   * Origin of this worktree entry.
+   *
+   * - `cleo-spawn`   — Canonical XDG worktree created by `cleo orchestrate spawn`.
+   * - `claude-agent` — Created by Claude Code Agent `isolation:worktree` (T9804).
+   * - `manual`       — Created via direct `git worktree add`.
+   * - `adopted`      — Registered via `cleo worktree adopt`.
+   *
+   * For backward-compatibility this field defaults to `cleo-spawn` for entries
+   * that originated from `git worktree list --porcelain` and are NOT present in
+   * the sentinel index.
+   *
+   * @task T9804
+   * @default 'cleo-spawn'
+   */
+  source: WorktreeSource;
 }
 
 /**
@@ -451,6 +520,9 @@ export interface ListWorktreesResult {
 /**
  * Canonical action recorded in `.cleo/audit/worktree-lifecycle.jsonl`.
  *
+ * - `create` — worktree was created via `cleo orchestrate spawn` (T9805).
+ * - `destroy` — worktree was explicitly destroyed (PR-merged cleanup or manual) (T9805).
+ * - `adopt` — an existing worktree directory was attached to a new task ID (T9805).
  * - `prune` — orphaned/merged worktree was removed.
  * - `prune-skip` — orphan was detected but skipped (user said N, or had uncommitted changes).
  * - `force-unlock` — git index.lock removed + `git worktree unlock` ran.
@@ -460,18 +532,26 @@ export interface ListWorktreesResult {
  *                       `--resolve manual`; no automatic merge attempted (T9548).
  * - `complete-conflict` — auto-merge attempted but failed (e.g. rebase/merge conflict);
  *                          worktree was preserved for manual resolution (T9548).
+ * - `adopt` — externally-created worktree (e.g. Claude Code Agent `isolation:worktree`)
+ *             registered in the CLEO SSoT via `cleo worktree adopt` (T9804).
  *
  * @task T9547
  * @task T9548
+ * @task T9804
+ * @task T9805
  */
 export type WorktreeLifecycleAction =
+  | 'create'
+  | 'destroy'
+  | 'adopt'
   | 'prune'
   | 'prune-skip'
   | 'force-unlock'
   | 'complete'
   | 'complete-skip'
   | 'complete-manual'
-  | 'complete-conflict';
+  | 'complete-conflict'
+  | 'adopt';
 
 /**
  * One append-only entry written to `.cleo/audit/worktree-lifecycle.jsonl` by
@@ -629,3 +709,71 @@ export interface ForceUnlockWorktreeResult {
   /** Error message when no worktree could be located or all actions failed. */
   error?: string;
 }
+
+// ---------------------------------------------------------------------------
+// Adopt operation (T9804 — Claude Code Agent isolation:worktree bridge)
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for {@link adoptWorktree} — the SDK primitive behind
+ * `cleo worktree adopt <path>`.
+ *
+ * @task T9804
+ */
+export interface AdoptWorktreeOpts {
+  /**
+   * Absolute path to the worktree directory to adopt.
+   *
+   * Typically a path under `.claude/worktrees/<sessionId>/` for Claude Code
+   * Agent `isolation:worktree` spawns, but any valid worktree path is accepted.
+   */
+  worktreePath: string;
+  /**
+   * Absolute path to the project root. Used to resolve the sentinel index
+   * and the audit-log file.
+   *
+   * @default process.cwd()
+   */
+  projectRoot?: string;
+  /**
+   * Source classification for this worktree.
+   *
+   * @default 'claude-agent'
+   */
+  source?: WorktreeSource;
+  /**
+   * Task ID to associate with this worktree. When not supplied the function
+   * attempts to extract it from the branch name following the `task/T####`
+   * convention, then falls back to null.
+   */
+  taskId?: string | null;
+  /** Override actor name written to the audit log and sentinel index. */
+  actor?: string;
+  /** Optional override for the audit-log file path (testing). */
+  auditLogPath?: string;
+  /** Optional override for the sentinel index path (testing). */
+  sentinelIndexPath?: string;
+}
+
+/**
+ * Result of a successful `cleo worktree adopt` operation.
+ *
+ * @task T9804
+ */
+export interface AdoptWorktreeResult {
+  /** Absolute path of the adopted worktree. */
+  path: string;
+  /** Branch name extracted from the worktree `.git` gitlink. */
+  branch: string;
+  /** Task ID associated with the worktree (null if not determinable). */
+  taskId: string | null;
+  /** Source classification applied to this entry. */
+  source: WorktreeSource;
+  /**
+   * Whether this was a new adoption (`true`) or an idempotent re-adopt
+   * of an already-registered worktree (`false`).
+   */
+  isNew: boolean;
+  /** ISO-8601 timestamp when the sentinel entry was written. */
+  adoptedAt: string;
+}

package/src/provenance.ts

@@ -0,0 +1,335 @@
+/**
+ * Provenance graph union types.
+ *
+ * Canonical home for the 16 string-literal union types that describe edges
+ * and FSM states in the CLEO provenance graph (commits, pull requests,
+ * releases, release artifacts, and BRAIN↔release links). Promoted from
+ * `packages/core/src/store/tasks-schema.ts` in Phase 0c of the
+ * SG-ARCH-SOLID Saga so that downstream packages can import these unions
+ * without pulling in the Drizzle schema runtime.
+ *
+ * The const arrays that back each union (`PR_STATES`, `COMMIT_LINK_KINDS`,
+ * `RELEASE_STATUSES`, …) remain in `tasks-schema.ts` because Drizzle's
+ * `text({ enum: ... })` column declaration narrows the runtime row type
+ * directly from those `as const` literals. `tasks-schema.ts` re-exports
+ * each union from this module to preserve the existing public surface for
+ * every `import * as schema from '../store/tasks-schema.js'` consumer.
+ *
+ * @see SPEC-T9345 §3 — provenance graph table definitions
+ * @see ADR-073 — task hierarchy charter (release provenance scope)
+ *
+ * Consolidated unions:
+ *   - {@link PrState}                   — pull-request lifecycle state
+ *   - {@link PrLinkSource}              — how a PR↔task link was discovered
+ *   - {@link PrLinkKind}                — semantic PR↔task relationship
+ *   - {@link CommitConventionalType}    — Conventional Commits prefix
+ *   - {@link CommitLinkKind}            — semantic commit↔task relationship
+ *   - {@link CommitLinkSource}          — how a commit↔task link was discovered
+ *   - {@link CommitFileChangeType}      — git status letter (A/M/D/R/C)
+ *   - {@link ReleaseScheme}             — versioning scheme
+ *   - {@link ReleaseChannel}            — npm dist-tag channel
+ *   - {@link ReleaseKind}               — release packaging type
+ *   - {@link ReleaseStatus}             — unified release FSM state
+ *   - {@link ReleaseChangeType}         — 12-value change taxonomy
+ *   - {@link ReleaseImpact}             — semver impact level
+ *   - {@link ReleaseClassifiedBy}       — change-classification provenance
+ *   - {@link ReleaseArtifactType}       — artifact archetype
+ *   - {@link BrainReleaseLinkType}      — BRAIN↔release link semantics
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+// ── Pull-request unions (T9507) ─────────────────────────────────────────
+
+/**
+ * State of a pull request.
+ *
+ * Mirrors the GitHub PR state machine:
+ *   - `open`   — PR is open and not yet merged
+ *   - `closed` — PR was closed without merging
+ *   - `merged` — PR was merged into the target branch
+ *
+ * @task T9507
+ */
+export type PrState = 'open' | 'closed' | 'merged';
+
+/**
+ * How a PR↔task link was discovered.
+ *
+ *   - `pr-title`       — task ID matched in the PR title
+ *   - `pr-body`        — task ID matched in the PR body markdown
+ *   - `branch-name`    — parsed from the branch name (e.g. `feat/T9507-...`)
+ *   - `commit-trailer` — extracted from a git trailer in a PR commit
+ *   - `manual`         — explicitly linked via `cleo provenance link`
+ *
+ * @task T9507
+ */
+export type PrLinkSource = 'pr-title' | 'pr-body' | 'branch-name' | 'commit-trailer' | 'manual';
+
+/**
+ * Semantic classification of a PR↔task relationship.
+ *
+ * Extends {@link CommitLinkKind} with `'tracks'` for PRs that observe a
+ * task without directly implementing, fixing, or documenting it.
+ *
+ *   - `implements` — the PR directly implements the task's acceptance criteria
+ *   - `fixes`      — the PR fixes a bug or regression in the task's work
+ *   - `refactors`  — the PR restructures code introduced by the task
+ *   - `tests`      — the PR adds or updates tests for the task
+ *   - `docs`       — the PR updates documentation for the task
+ *   - `reverts`    — the PR reverts work introduced by the task
+ *   - `tracks`     — the PR is related to but does not directly implement the task
+ *
+ * @task T9507
+ */
+export type PrLinkKind =
+  | 'implements'
+  | 'fixes'
+  | 'refactors'
+  | 'tests'
+  | 'docs'
+  | 'reverts'
+  | 'tracks';
+
+// ── Commit unions (T9506) ───────────────────────────────────────────────
+
+/**
+ * Conventional Commits prefix parsed from a commit subject.
+ *
+ * Adds `'breaking'` to the canonical CC set to flag BREAKING CHANGE
+ * footers. The DB column is nullable — a commit that does not follow
+ * Conventional Commits format stores NULL rather than one of these values.
+ *
+ * @task T9506
+ */
+export type CommitConventionalType =
+  | 'feat'
+  | 'fix'
+  | 'chore'
+  | 'docs'
+  | 'refactor'
+  | 'test'
+  | 'build'
+  | 'ci'
+  | 'perf'
+  | 'revert'
+  | 'breaking';
+
+/**
+ * Semantic classification of a commit↔task relationship.
+ *
+ *   - `implements` — the commit directly implements the task's acceptance criteria
+ *   - `fixes`      — the commit fixes a bug or regression in the task's work
+ *   - `refactors`  — the commit restructures code introduced by the task
+ *   - `tests`      — the commit adds or updates tests for the task
+ *   - `docs`       — the commit updates documentation for the task
+ *   - `reverts`    — the commit reverts work introduced by the task
+ *
+ * @task T9506
+ */
+export type CommitLinkKind = 'implements' | 'fixes' | 'refactors' | 'tests' | 'docs' | 'reverts';
+
+/**
+ * How a commit↔task link was discovered.
+ *
+ *   - `commit-trailer` — extracted from a `T####:` or `Task-Id:` git trailer
+ *   - `commit-subject` — matched `T####` regex in the commit subject line
+ *   - `pr-title`       — matched task ID in the PR title
+ *   - `pr-body`        — matched task ID in the PR body markdown
+ *   - `branch-name`    — parsed from the branch name (e.g., `feat/T9506-...`)
+ *   - `manual`         — explicitly linked via `cleo provenance link`
+ *
+ * @task T9506
+ */
+export type CommitLinkSource =
+  | 'commit-trailer'
+  | 'commit-subject'
+  | 'pr-title'
+  | 'pr-body'
+  | 'branch-name'
+  | 'manual';
+
+/**
+ * Per-file change type from a git diff (status letter codes).
+ *
+ *   - `A` — added
+ *   - `M` — modified
+ *   - `D` — deleted
+ *   - `R` — renamed
+ *   - `C` — copied
+ *
+ * @task T9506
+ */
+export type CommitFileChangeType = 'A' | 'M' | 'D' | 'R' | 'C';
+
+// ── Release unions (T9508) ──────────────────────────────────────────────
+
+/**
+ * Versioning scheme for a release.
+ *
+ *   - `calver`        — YYYY.MM.patch (e.g. 2026.5.74) — CLEO default
+ *   - `semver`        — MAJOR.MINOR.PATCH (e.g. 1.2.3)
+ *   - `calver-suffix` — YYYY.MM.patch.N suffix hotfix (e.g. 2026.5.74.2)
+ *
+ * @task T9508
+ * @remarks
+ * The values here MUST stay aligned with `RELEASE_SCHEMES` in
+ * `tasks-schema.ts`; that const array drives the Drizzle row type. A
+ * compile-time structural assertion in
+ * `packages/contracts/src/__tests__/provenance.test.ts` pins both sides.
+ */
+export type ReleaseScheme = 'calver' | 'semver' | 'calver-suffix';
+
+/**
+ * Release channel — controls which npm dist-tag (or equivalent) the
+ * artifact is published under.
+ *
+ *   - `latest` — current stable
+ *   - `beta`   — pre-release tested in production-adjacent environments
+ *   - `dev`    — internal development snapshots
+ *   - `hotfix` — emergency patch outside the regular cadence
+ *
+ * @task T9508
+ * @remarks
+ * Distinct from the `ReleaseChannel` exported by
+ * `@cleocode/contracts/release/channel` (which carries the npm-level
+ * `latest|beta|alpha` set) and from the `ReleaseChannel` in
+ * `@cleocode/contracts/release/plan` (which carries the release-plan
+ * `latest|beta|alpha|rc` set). Top-level `@cleocode/contracts` re-exports
+ * this union under a disambiguating alias.
+ */
+export type ReleaseChannel = 'latest' | 'beta' | 'dev' | 'hotfix';
+
+/**
+ * Release packaging kind, orthogonal to individual change types within
+ * the release.
+ *
+ *   - `regular`    — standard scheduled release
+ *   - `hotfix`     — emergency patch outside regular cadence
+ *   - `prerelease` — alpha/beta/rc release for early adopters
+ *
+ * @task T9508
+ */
+export type ReleaseKind = 'regular' | 'hotfix' | 'prerelease';
+
+/**
+ * Unified release FSM state (admits values from BOTH the new T9492
+ * pipeline and the legacy T5580 pipeline; the status value itself
+ * discriminates which pipeline owns the row).
+ *
+ * **New T9492 pipeline** — SPEC-T9345 §10.1 FSM:
+ *   `planned → pr-opened → pr-merged → published → reconciled`
+ *
+ * **Legacy T5580 pipeline** — pre-T9492 12-step flow:
+ *   `prepared → committed → tagged → pushed`
+ *
+ * **Shared terminal states**:
+ *   `rolled_back | failed | cancelled`
+ *
+ * State transitions per R-302 MUST be monotonic within each lifecycle;
+ * illegal transitions return `E_INVALID_STATE` and MUST NOT mutate any row.
+ *
+ * @task T9508
+ * @task T9686 (unification — legacy + new statuses on one column)
+ * @see SPEC-T9345 §10.1
+ */
+export type ReleaseStatus =
+  | 'planned'
+  | 'pr-opened'
+  | 'pr-merged'
+  | 'published'
+  | 'reconciled'
+  | 'prepared'
+  | 'committed'
+  | 'tagged'
+  | 'pushed'
+  | 'rolled_back'
+  | 'failed'
+  | 'cancelled';
+
+/**
+ * 12-value CLEO release change taxonomy (Option B from
+ * provenance-graph-design.md §2.2).
+ *
+ * Lives at the release-changes level (not on `tasks.kind`) so that:
+ *   - A single task can produce multiple change rows across releases.
+ *   - Hotfix classification is a release-packaging decision, not a task property.
+ *   - Auto-classification is agent-writable without touching OWNER-WRITE-ONLY fields.
+ *
+ * @task T9508
+ * @see SPEC-T9345 §2.2
+ */
+export type ReleaseChangeType =
+  | 'feature'
+  | 'enhancement'
+  | 'bug'
+  | 'hotfix'
+  | 'security'
+  | 'breaking'
+  | 'refactor'
+  | 'docs'
+  | 'chore'
+  | 'revert'
+  | 'deprecation'
+  | 'infrastructure';
+
+/**
+ * Impact level for a release change, mapped to semver bump assessment.
+ *
+ *   - `major` — breaking change (MAJOR bump)
+ *   - `minor` — new feature (MINOR bump)
+ *   - `patch` — bug fix / chore (PATCH bump)
+ *   - `none`  — cosmetic / docs / trivial (no version bump warranted alone)
+ *
+ * @task T9508
+ */
+export type ReleaseImpact = 'major' | 'minor' | 'patch' | 'none';
+
+/**
+ * Provenance of a release-change classification.
+ *
+ *   - `auto`     — derived by the classification engine from CC prefix + heuristics
+ *   - `manual`   — owner overrode the auto classification via `cleo release classify`
+ *   - `approved` — owner approved an agent-proposed classification
+ *
+ * @task T9508
+ */
+export type ReleaseClassifiedBy = 'auto' | 'manual' | 'approved';
+
+// ── Release artifact + BRAIN-link unions (T9509) ─────────────────────────
+
+/**
+ * Release artifact archetype.
+ *
+ *   - `npm`            — npm package published to a registry
+ *   - `cargo`          — Rust crate published to crates.io
+ *   - `docker`         — Container image pushed to an OCI registry
+ *   - `pypi`           — Python package published to pypi.org
+ *   - `github-release` — GitHub Releases asset attached to a git tag
+ *   - `binary`         — Generic compiled binary distributed via direct URL
+ *   - `github-tag`     — Lightweight git tag (no attached assets)
+ *
+ * @task T9509
+ * @see SPEC-T9345 §3.9
+ */
+export type ReleaseArtifactType =
+  | 'npm'
+  | 'cargo'
+  | 'docker'
+  | 'pypi'
+  | 'github-release'
+  | 'binary'
+  | 'github-tag';
+
+/**
+ * Semantic relationship between a BRAIN entry and a release.
+ *
+ *   - `approved-by`    — A BRAIN decision approved a change that shipped in this release.
+ *   - `documented-in`  — This release is where the BRAIN entry was first formally documented.
+ *   - `derived-from`   — The release's failure or outcome produced this BRAIN learning/pattern.
+ *   - `observed-in`    — A BRAIN observation was made about this release (e.g. performance note).
+ *
+ * @task T9509
+ * @see SPEC-T9345 §8.1
+ */
+export type BrainReleaseLinkType = 'approved-by' | 'documented-in' | 'derived-from' | 'observed-in';

package/src/scaffold-diagnostics.ts

@@ -0,0 +1,119 @@
+/**
+ * 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)
+ */
+
+// ── ScaffoldResult ────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── CheckStatus + CheckResult ─────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── HookCheckResult ───────────────────────────────────────────────────
+
+/**
+ * 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;
+}