@lemoncode/lemony 0.1.0 → 0.1.1-alpha.1

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execFile } from "node:child_process";
 import { access, appendFile, chmod, lstat, mkdir, open, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
-import { delimiter, dirname, join, sep } from "node:path";
+import { delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { argv, cwd, env, exit, stderr, stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
@@ -10,89 +10,21 @@ import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
 import { constants } from "node:fs";
 //#region src/events/append.ts
-/**
-* Append one JSON line to `eventsPath`, creating parent dirs and the file as
-* needed.
-*
-* **Concurrency.** A single `write(2)` to an `O_APPEND`-opened file is atomic
-* up to `PIPE_BUF` (4096 bytes on macOS/Linux) — every event in the seven-type
-* catalog stays well under that. `fs.appendFile` opens with `O_APPEND` and
-* issues one write, so two concurrent emitters (a hook + the Orchestrator's
-* `task_done` emit, say) can interleave whole lines but never tear a single
-* one and never lose an event. This matches the `O_APPEND` option called out
-* as safe in `catalog/schemas/tier2-events.md`.
-*/
 const appendEvent = async (eventsPath, event) => {
 	await mkdir(dirname(eventsPath), { recursive: true });
 	await appendFile(eventsPath, `${JSON.stringify(event)}\n`);
 };
 //#endregion
 //#region src/config/config.constant.ts
-/**
-* Constants and enumerations for `harness.config.yml` (decision #53). The Zod
-* schema (`config.schema.ts`) is built from these; keeping the literal sets here
-* lets non-schema code (the installer, the bash defaults guard) reference the
-* same source of truth without importing Zod.
-*/
 const HARNESS_CONFIG_FILENAME = "harness.config.yml";
-/**
-* Keys retired from the schema but **tolerated on read** so an existing install's
-* config doesn't fail-closed when the CLI is upgraded past the removal (ADR 0015).
-* The reader strips these before `.strict()` validation (so an honest typo still
-* fails loud), and the writer deletes them on the next config write (so the dead
-* line disappears the first time any verb rewrites the file). `profile` was the
-* coarse skill tier (#39/#50), removed when profiles collapsed to a single
-* capability-gated skill set.
-*/
-const DEPRECATED_CONFIG_KEYS = ["profile"];
-/** Committed JSON Schema the IDE reads via the `$schema` header (decision #53e/B1.5). */
+const DEPRECATED_CONFIG_KEYS = ["profile", "agents"];
 const HARNESS_CONFIG_SCHEMA_FILENAME = "harness.config.schema.json";
-/**
-* Sentinel value the installer writes to `task_storage.repo` when it cannot
-* resolve a real slug (no git origin remote, no `--task-storage-repo` flag,
-* non-TTY install) so the file is well-formed. Every downstream consumer treats
-* this literal as "unset" — `emit` refuses to stamp it onto telemetry events.
-*/
 const TASK_STORAGE_REPO_PLACEHOLDER = "OWNER/REPO";
-/** AI-coding harnesses this build can target (#53j). Only `claude-code` is operative. */
 const TARGETS = ["claude-code"];
-/** Task-storage backends (#53a). Only `github` in Sprint 0; adapters are a Fase 1+ pattern. */
 const TASK_STORAGE_TYPES = ["github"];
-/**
-* `task_storage.repo` shape (#53a): `owner/name` — two non-empty, slash-free
-* segments. Permissive on the characters GitHub allows (letters, digits, `-`,
-* `_`, `.`); strict on the shape so a hand-edited slug can't be a bare flag (e.g.
-* `--foo`) that a downstream `gh --repo <slug>` would misread. The `OWNER/REPO`
-* placeholder matches and is rejected separately by the emit/sync guards.
-*/
 const TASK_STORAGE_REPO_PATTERN = /^[^\s/]+\/[^\s/]+$/;
-/**
-* Agent slugs valid in the `agents` array (#53h). `orchestrator` is the hat and
-* is required; `ui-designer` is a catalog slot, inactive by default (decision #11).
-*/
-const AGENTS = [
-	"orchestrator",
-	"spec-author",
-	"implementer",
-	"reviewer",
-	"architect",
-	"ui-designer"
-];
-/** The hat — must always be present in the `agents` array (#53h). */
-const REQUIRED_AGENT = "orchestrator";
-/**
-* `vendor_version` format (#53i): an exact semver with an optional prerelease
-* tag (`alpha`/`beta`/`rc`). Registry-existence is checked in P7 (B1.3), not here.
-*/
 const VENDOR_VERSION_REGEX = /^\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$/;
-/** A copy-pasteable `vendor_version` for the did-you-mean error message. */
 const VENDOR_VERSION_EXAMPLE = "0.1.0-alpha.0";
-/**
-* Canonical defaults for the optional `paths.*` keys (#53g, B1.1-fu). Declared
-* once here in TS; the bash `playbook-scan.sh` keeps its own literals for the
-* two keys it reads, and a guard test (`paths-defaults.spec.ts`) asserts the two
-* stay equal so the duplication can never silently drift.
-*/
 const PATHS_DEFAULTS = {
 	state: ".claude/state",
 	skills: ".claude/skills",
@@ -102,13 +34,6 @@ const PATHS_DEFAULTS = {
 };
 //#endregion
 //#region src/config/config-error.ts
-/**
-* Turn a `ZodError` from validating `harness.config.yml` into a human-readable,
-* actionable message (decision B1.2). A developer edits this YAML by hand, so an
-* unknown key gets a did-you-mean suggestion (the nearest valid sibling key) and
-* a malformed `vendor_version` gets the expected format plus a concrete example,
-* instead of the raw Zod dump.
-*/
 const formatConfigError = (schema, error) => {
 	return error.issues.flatMap((issue) => formatIssue(schema, issue)).join("\n");
 };
@@ -128,16 +53,8 @@ const formatIssue = (schema, issue) => {
 	if (issue.code === "invalid_value") return [`${where} must be one of: ${issue.values.map((v) => JSON.stringify(v)).join(", ")}.`];
 	return [`${where}: ${issue.message}`];
 };
-/** A `vendor_version` issue (top-level scalar) gets the example appended. */
 const isVendorVersion = (path) => path.length === 1 && path[0] === "vendor_version";
-/** Human label for an issue path: the dotted key, or `(root)` for the top object. */
 const pathLabel = (path) => path.length === 0 ? "(root)" : path.map(String).join(".");
-/**
-* The valid keys of the object at `path`, read from the schema itself so the
-* suggestion set never drifts from the schema. Walks the shape, unwrapping the
-* `default()`/`optional()` wrappers that sit between an object and its `shape`.
-* Returns null when the path doesn't resolve to an object (no suggestions then).
-*/
 const validKeysAt = (schema, path) => {
 	let shape = shapeOf(schema);
 	for (const segment of path) {
@@ -152,12 +69,6 @@ const shapeOf = (schema) => {
 	while (current?.def?.innerType) current = current.def.innerType;
 	return current?.shape;
 };
-/**
-* The candidate closest to `key` by Levenshtein distance, or null when even the
-* closest is too far to be a plausible typo (distance over half the candidate's
-* length). Keeps "extra" from suggesting an unrelated key while still catching
-* "targett" → "target".
-*/
 const nearestKey = (key, candidates) => {
 	let best = null;
 	let bestDistance = Infinity;
@@ -185,19 +96,6 @@ const levenshtein = (a, b) => {
 };
 //#endregion
 //#region src/config/config.schema.ts
-/**
-* The `harness.config.yml` schema (decision #53, B1). `.strict()` is recursive —
-* top level, `task_storage`, and `paths` all reject unknown keys so a typo'd key
-* fails loudly instead of silently disabling the override it was meant to set
-* (e.g. the awk hooks reading `paths.playbooks`). Optional `paths.*` keys carry
-* their canonical defaults, so `readHarnessConfig` returns the fully resolved
-* config (defaults applied) and `HarnessConfig` = `z.infer` of this schema is the
-* single source of truth for the config's shape.
-*
-* Models the keys the template ships (#53 a/g–k) plus `rollback` (b), which lands
-* in P7/S2 with the feature that reads it. `session_close` (c) blocks land with the
-* session hook, and `metrics` (d) stays a template comment until Fase 1+.
-*/
 const pathsSchema = z.object({
 	state: z.string().default(PATHS_DEFAULTS.state),
 	skills: z.string().default(PATHS_DEFAULTS.skills),
@@ -209,45 +107,20 @@ const taskStorageSchema = z.object({
 	type: z.enum(TASK_STORAGE_TYPES),
 	repo: z.string().regex(TASK_STORAGE_REPO_PATTERN)
 }).strict();
-/**
-* The `rollback` block (#53b/#48). Only `keep_snapshots`: how many pre-update
-* snapshot bundles `rollback` rotation retains — a positive integer or the
-* `"unlimited"` sentinel (never rotate). Default `3` (#53b). The block is optional
-* and `.prefault({})` so an old config (pre-P7) without it still validates and
-* resolves to the default — the config writer never injects new keys (D4).
-*/
 const rollbackSchema = z.object({ keep_snapshots: z.union([z.int().positive(), z.literal("unlimited")]).default(3) }).strict().prefault({});
-/**
-* The `telemetry` block (#229). v1 exposes only `enabled` — the committed,
-* team-wide off-switch over the on-by-default floor. `anonymous` is the only tier
-* (hardcoded in the send path), so there is **no `tier` key**: `tier` + the
-* `project` tier land together in a later version, and a committed `tier:` today is
-* a loud `.strict()` error, not an inert no-op. `enabled` defaults `true` and the
-* block is `.prefault({})` so an old config without it resolves to the floor
-* (consent precedence + fail-safe live in `src/telemetry/consent.ts`).
-*/
 const telemetrySchema = z.object({ enabled: z.boolean().default(true) }).strict().prefault({});
+const designTokensSchema = z.object({ scan_extensions: z.array(z.string()).default([]) }).strict().prefault({});
 const harnessConfigSchema = z.object({
 	vendor_version: z.string().regex(VENDOR_VERSION_REGEX),
 	target: z.enum(TARGETS),
 	task_storage: taskStorageSchema,
-	agents: z.array(z.enum(AGENTS)).refine((agents) => agents.includes(REQUIRED_AGENT), { error: `agents must include "${REQUIRED_AGENT}" (the orchestrator is the hat).` }),
 	paths: pathsSchema,
 	rollback: rollbackSchema,
-	telemetry: telemetrySchema
+	telemetry: telemetrySchema,
+	design_tokens: designTokensSchema
 }).strict();
 //#endregion
 //#region src/config/config.ts
-/**
-* Read and validate `harness.config.yml` at the repo root. Re-parsed on every
-* read (no caching) so a hand edit applies immediately — the file is small and a
-* stale cache between CLI calls would surprise a developer editing it by hand.
-*
-* Validation is the Zod schema (the single source of truth, decision B1): the
-* returned config is the **fully resolved** object with `paths.*` defaults
-* applied. A schema failure is rendered through `formatConfigError` so the CLI
-* surfaces a did-you-mean / expected-format message instead of a raw Zod dump.
-*/
 const readHarnessConfig = async (repoRoot) => {
 	const configPath = join(repoRoot, HARNESS_CONFIG_FILENAME);
 	let raw;
@@ -272,17 +145,11 @@ const readHarnessConfig = async (repoRoot) => {
 };
 //#endregion
 //#region src/config/compare-version.ts
-/** Prerelease tags in ascending semver precedence (alpha < beta < rc < release). */
 const PRERELEASE_RANK = {
 	alpha: 0,
 	beta: 1,
 	rc: 2
 };
-/**
-* Capturing form of `VENDOR_VERSION_REGEX` (config.constant): the same bounded
-* format `MAJOR.MINOR.PATCH[-(alpha|beta|rc).N]`, but with groups so we can read
-* the parts out. A non-match is the validity gate (parse → null).
-*/
 const VERSION_PARTS = /^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.(\d+))?$/;
 const parse$1 = (raw) => {
 	const m = VERSION_PARTS.exec(raw);
@@ -305,17 +172,6 @@ const parse$1 = (raw) => {
 		}
 	};
 };
-/**
-* Compare two `vendor_version` strings by semver precedence (#172): returns -1/0/1
-* for a<b / a==b / a>b, or `null` when either side is not a valid `vendor_version`
-* (callers degrade gracefully — neutral message, no guard — rather than guess a
-* direction from an unparseable string).
-*
-* The format is the bounded subset `MAJOR.MINOR.PATCH[-(alpha|beta|rc).N]`, so a full
-* semver dependency is overkill: core numbers compare numerically, a release (no
-* prerelease) outranks any prerelease of the same core, and among prereleases the tag
-* (alpha<beta<rc) then the numeric `.N` decide.
-*/
 const compareVendorVersion = (a, b) => {
 	const pa = parse$1(a);
 	const pb = parse$1(b);
@@ -334,57 +190,18 @@ const compareVendorVersion = (a, b) => {
 };
 //#endregion
 //#region src/config/write-config.ts
-/**
-* Apply value bumps to a `harness.config.yml` source string via the `yaml`
-* Document API (decision D4): `parseDocument` keeps the document's comments and
-* formatting as a CST, `doc.set` rewrites only the touched scalar, and `toString`
-* re-emits everything else byte-for-byte. This is why `update` can edit the config
-* without yq and without flattening the template's rich comments.
-*
-* **Value-bumps only** — a key absent from the document is skipped, never injected.
-* New optional keys are covered by the Zod schema's `.default()`/`.prefault()`, so
-* an old config without them still validates; the writer never adds structure.
-*
-* On every write it also deletes any `DEPRECATED_CONFIG_KEYS` present (ADR 0015) —
-* so a config still carrying a retired key (e.g. `profile`) is cleaned up the first
-* time any verb rewrites it, pairing with the reader's read-time tolerance.
-*/
 const setConfigValues = (rawYaml, updates) => {
 	const doc = parseDocument(rawYaml);
 	for (const [key, value] of Object.entries(updates)) if (doc.has(key)) doc.set(key, value);
 	for (const key of DEPRECATED_CONFIG_KEYS) if (doc.has(key)) doc.delete(key);
 	return doc.toString();
 };
-/**
-* Read `harness.config.yml` at the repo root, apply the value bumps, and write it
-* back. The on-disk counterpart of `setConfigValues` — `update` calls it to bump
-* `vendor_version` after a merge (and, en passant, to drop any retired key).
-*/
 const writeConfigValues = async (repoRoot, updates) => {
 	const configPath = join(repoRoot, HARNESS_CONFIG_FILENAME);
 	await writeFile(configPath, setConfigValues(await readFile(configPath, "utf8"), updates));
 };
 //#endregion
 //#region src/config/pointer.schema.ts
-/**
-* Canonical contract for the per-dev pointer frontmatter (`current-<user>.md`)
-* — decision B4.1. Single source of truth for the keys the lifecycle hooks
-* (`init.sh`, `session-close.sh`) WRITE and the `status` command READS. Lives
-* beside the other bash↔TS contract guard (`paths-defaults.spec.ts`).
-*
-* The fail-closed boot path stays bash-only (no node dependency, #54/#41), so
-* this schema can't be imported there. Instead `pointer.schema.spec.ts` reads
-* the hook source and asserts the bash writers/readers stay in lock-step with
-* these keys — the convergence guard that lets the read logic live in one place
-* without coupling the boot path to the CLI.
-*
-* Every scalar is lenient (absent | null | string | number | boolean): the
-* hooks emit YAML `null`, empty strings, and quoted/unquoted scalars
-* interchangeably, and a partial or hand-edited pointer must still parse — a
-* single stray scalar (e.g. a numeric `active_task`) degrades that one field,
-* it must not blank the whole pointer. `normalize` (status.ts) collapses the
-* "unset" variants to `null` and stringifies the rest.
-*/
 const pointerScalar = z.union([
 	z.string(),
 	z.number(),
@@ -400,14 +217,6 @@ const pointerFrontmatterSchema = z.object({
 Object.keys(pointerFrontmatterSchema.shape);
 //#endregion
 //#region src/events/envelope.ts
-/**
-* Build the on-wire envelope every event line carries (see
-* `catalog/schemas/tier2-events.md`). Stamps `ts` in UTC ISO 8601 with the literal
-* `Z` suffix — `Date#toISOString` is already that format. Skips `task_id` when the
-* caller didn't provide one so the line stays sparse and the Zod schema for
-* task-less events (`session_closed`, `l3_bypass`) accepts it without a
-* placeholder.
-*/
 const buildEnvelope = (input) => {
 	const ts = (input.now ?? /* @__PURE__ */ new Date()).toISOString();
 	const envelope = {
@@ -422,15 +231,6 @@ const buildEnvelope = (input) => {
 };
 //#endregion
 //#region src/events/events.model.ts
-/**
-* Tier 2 event types declared in `catalog/schemas/tier2-events.md`.
-*
-* Five emit in P5; `bug_post_merge` (P8) and `l3_bypass` (P6) are reserved so the
-* file is forward-compatible from `0.1.0-alpha.0` — readers dispatch on `type` and
-* skip unknown values. `followup_captured` (#112, `/spinoff`) is the eighth — emitted
-* when a non-blocking defect is parked mid-task as a stub. `step_completed` (#176)
-* is the ninth — emitted at each resolved human checkpoint in step-by-step mode.
-*/
 const EVENT_TYPES = [
 	"session_closed",
 	"spec_created",
@@ -442,7 +242,6 @@ const EVENT_TYPES = [
 	"followup_captured",
 	"step_completed"
 ];
-/** Reason codes accepted by `session_closed` — Claude Code SessionEnd values plus `manual` for `/pause`. */
 const SESSION_CLOSE_REASONS = [
 	"clear",
 	"resume",
@@ -452,38 +251,23 @@ const SESSION_CLOSE_REASONS = [
 	"other",
 	"manual"
 ];
-/** Task-fit dial value, recorded on `task_done` (decisions #57–#61). */
 const TASK_LEVELS = [
 	"L1",
 	"L2",
 	"L3"
 ];
-/** Bug severity, recorded on `bug_post_merge` (P8 meta-test). */
 const BUG_SEVERITIES = [
 	"low",
 	"medium",
 	"high",
 	"critical"
 ];
-/**
-* Implementation mode chosen at the L1 approval gate (#176), recorded on
-* `task_done`. Absent on L2 — the mode question only exists where `tasks.md` does.
-*/
 const IMPLEMENTATION_MODES = ["all_at_once", "step_by_step"];
-/** Human checkpoint outcome, recorded on `step_completed` (#176). */
 const CHECKPOINT_RESULTS = [
 	"ok",
 	"changes",
 	"ok_downgrade"
 ];
-/**
-* What kind of component a friction event is attributed to (#217). Optional on
-* `review_rejected` and `step_completed` — `attributed_name` (free string) names
-* the specific component. Free string by design this phase (measure-then-decide):
-* the emitting prompts list the roster and omit when unsure; the aggregation
-* script reports coverage and flags unknown names rather than the CLI enforcing a
-* registry.
-*/
 const ATTRIBUTION_KINDS = [
 	"agent",
 	"skill",
@@ -492,12 +276,6 @@ const ATTRIBUTION_KINDS = [
 //#endregion
 //#region src/events/git-user.ts
 const execFileAsync$1 = promisify(execFile);
-/**
-* The git user.email of the actor, used as the envelope `user` field (decision
-* \#53). Reads `git config user.email` in the repo (covers local + global), the
-* same value `git` itself stamps on commits. Returns `null` when no email is
-* configured — callers convert that into a friendly error or block at SessionStart.
-*/
 const readGitUserEmail = async (cwd) => {
 	try {
 		const { stdout } = await execFileAsync$1("git", ["config", "user.email"], { cwd });
@@ -509,27 +287,11 @@ const readGitUserEmail = async (cwd) => {
 };
 //#endregion
 //#region src/events/schemas.ts
-/**
-* UTC ISO 8601 timestamp with a literal `Z` suffix — no local offsets allowed
-* (durable rule, decision #25/#27). Accepts millisecond precision optionally:
-* `2026-05-28T14:30:00Z` and `2026-05-28T14:30:00.000Z` both pass.
-*/
 const ISO_Z_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
 const isoTimestamp = () => z.string().regex(ISO_Z_REGEX);
 const nonEmpty = () => z.string().min(1);
-/**
-* Bounded free-form strings. Caps are aligned with the schema doc's
-* recommendations ("one line", "≤ 200 chars recommended") and stay well
-* below `PIPE_BUF` (4096 B) so a single event line remains atomically
-* `O_APPEND`-able.
-*/
 const shortText = () => z.string().min(1).max(200);
 const oneLineText = () => z.string().min(1).max(500);
-/**
-* Envelope every event line carries. `task_id` is optional here; the per-type
-* schemas that need it override it to required via `.extend()`. The Zod schema
-* mirrors `catalog/schemas/tier2-events.md` (authority — the doc wins on conflict).
-*/
 const envelopeBase = z.object({
 	ts: isoTimestamp(),
 	user: nonEmpty(),
@@ -537,13 +299,6 @@ const envelopeBase = z.object({
 	task_id: nonEmpty().optional(),
 	harness_version: nonEmpty()
 });
-/**
-* Optional attribution fields (#217) shared by the two friction events
-* (`review_rejected`, `step_completed`) — they let a line name the component the
-* friction is attributed to. `attributed_kind` is enum-validated; `attributed_name`
-* is a free string this phase (measure-then-decide, see `ATTRIBUTION_KINDS`). Both
-* optional so historical lines and "can't attribute" emits still validate.
-*/
 const attributionFields = {
 	attributed_kind: z.enum(ATTRIBUTION_KINDS).optional(),
 	attributed_name: shortText().optional()
@@ -608,11 +363,6 @@ const stepCompletedSchema = envelopeBase.extend({
 	checkpoint_result: z.enum(CHECKPOINT_RESULTS),
 	...attributionFields
 }).strict();
-/**
-* The on-wire shape of any event line, discriminated by `type`. New types extend
-* the file forward-compatibly: a reader unknown to the new type simply skips the
-* line on dispatch.
-*/
 const eventSchema = z.discriminatedUnion("type", [
 	sessionClosedSchema,
 	specCreatedSchema,
@@ -626,7 +376,6 @@ const eventSchema = z.discriminatedUnion("type", [
 ]);
 //#endregion
 //#region src/events/emit.ts
-/** Per-type fields the CLI must coerce from `--key=value` strings to numbers. */
 const NUMERIC_FIELDS = /* @__PURE__ */ new Set([
 	"session_active_h",
 	"requirements",
@@ -639,11 +388,9 @@ const NUMERIC_FIELDS = /* @__PURE__ */ new Set([
 	"steps",
 	"review_iterations"
 ]);
-/** Per-type fields the CLI must coerce from `--key=value` strings to booleans. */
 const BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["auto_close"]);
 const EVENTS_RELPATH$1 = join(".claude", "state", "events.jsonl");
 const isEventType = (value) => EVENT_TYPES.includes(value);
-/** Coerce a raw `--key=value` string to its declared scalar type. */
 const coerceField = (key, raw) => {
 	if (NUMERIC_FIELDS.has(key)) {
 		const num = Number(raw);
@@ -657,15 +404,6 @@ const coerceField = (key, raw) => {
 	}
 	return raw;
 };
-/**
-* Parse `--key=value` and `--key value` flag pairs into a record. Returns the
-* fields keyed by their (snake_case, kebab→underscore) names. Values are coerced
-* according to their declared types; unknown keys pass through here as raw strings
-* but are then **rejected** by the per-type `.strict()` schema in `runEmit` — so a
-* misspelled flag fails loud rather than being silently persisted into
-* `events.jsonl` (P7/S3 #82). A genuinely new field is added by extending the
-* schema, not by relaxing this parser.
-*/
 const parseFlags = (args) => {
 	const result = {};
 	for (let i = 0; i < args.length; i++) {
@@ -679,14 +417,6 @@ const parseFlags = (args) => {
 	}
 	return result;
 };
-/**
-* Run `lemony emit <type> [--field=value …]`: build the envelope, merge
-* per-type fields, Zod-validate against the discriminated union, and append the
-* resulting line atomically to `.claude/state/events.jsonl`.
-*
-* Returns the validated event so callers (and tests) can inspect what was
-* written.
-*/
 const runEmit = async (options) => {
 	const { repoRoot, harnessVersion, args } = options;
 	const [rawType, ...rest] = args;
@@ -723,7 +453,6 @@ const runEmit = async (options) => {
 };
 //#endregion
 //#region src/labels/labels.constant.ts
-/** 8 mutually-exclusive status labels (#55c), orange→green by lifecycle order. */
 const STATUS_LABELS = [
 	{
 		name: "harness:status:pending",
@@ -766,7 +495,6 @@ const STATUS_LABELS = [
 		description: "Managed task: merged and closed."
 	}
 ];
-/** 4 presence flags (#55d, B2.3) — no value, presence is the signal. */
 const FLAG_LABELS = [
 	{
 		name: "harness:managed",
@@ -786,10 +514,14 @@ const FLAG_LABELS = [
 	{
 		name: "harness:architecture-drift",
 		color: "006b75",
-		description: "Captured architecture.md drift (#148); resolved by the Architect at pickup, not a code change."
+		description: "Captured architecture.md drift; resolved by the Architect at pickup, not a code change."
+	},
+	{
+		name: "harness:needs-design",
+		color: "d4548d",
+		description: "Task touches UI; a design handoff (ui-handoff.md) is owed before spec-ready."
 	}
 ];
-/** 6 discovery types (#55e), presence-based and multi-applicable, alert-red. */
 const DISCOVERY_LABELS = [
 	["T1", "contradiction"],
 	["T2", "unspecified decision"],
@@ -802,10 +534,6 @@ const DISCOVERY_LABELS = [
 	color: "b60205",
 	description: `Discovery (${tier}): ${meaning}.`
 }));
-/**
-* The full, canonical 18-label set. `install`/`update` create/reconcile these;
-* `doctor` reports drift read-only against the same list (single source of truth).
-*/
 const HARNESS_LABELS = [
 	...STATUS_LABELS,
 	...FLAG_LABELS,
@@ -813,13 +541,6 @@ const HARNESS_LABELS = [
 ];
 //#endregion
 //#region src/labels/diff-labels.ts
-/**
-* Diff the desired `harness:*` labels against the repo's existing labels by
-* name. A present label whose color or description differs is `drifted`. Color
-* is compared case-insensitively because GitHub echoes hex in a normalized case
-* that needn't match our literal; description is compared exactly. Pure — all
-* `gh` I/O lives in the caller, so this is trivially testable without a network.
-*/
 const diffLabels = (existing, desired) => {
 	const byName = new Map(existing.map((label) => [label.name, label]));
 	const missing = [];
@@ -839,16 +560,6 @@ const diffLabels = (existing, desired) => {
 };
 //#endregion
 //#region src/labels/sync-labels.ts
-/**
-* Reconcile the repo's `harness:*` labels with the canonical set via `gh label`
-* porcelain (decision B2.1/B2.2). Lists once, diffs (the shared pure `diffLabels`),
-* then creates missing and edits drifted labels. **Non-fatal by contract**: a
-* placeholder slug short-circuits (`skipped`) and any `gh` failure returns
-* `failed` with a reason — the caller (`install`) warns and points at `doctor`
-* rather than aborting the whole install over a recoverable step. Porcelain
-* (`gh label list/create/edit`) is chosen over raw `gh api` so we don't hand-roll
-* status-code handling.
-*/
 const syncLabels = async (repoSlug, provider, desired = HARNESS_LABELS) => {
 	if (repoSlug === "OWNER/REPO") return {
 		status: "skipped",
@@ -920,22 +631,6 @@ const failureReason$2 = (action, result) => {
 };
 //#endregion
 //#region src/labels/ensure-labels.ts
-/**
-* Preflight self-heal for the verbs that add `harness:*` labels to issues (`spinoff`,
-* `discovery`) — ADR 0013. A fresh install whose label sync was skipped or failed (e.g.
-* `gh` unauthenticated at install time, then authenticated later) leaves the repo
-* installed-but-labels-missing; the first verb that does `gh issue create/edit --label`
-* then trips on a "label not found" mid-flow. Running {@link syncLabels} before the
-* mutation reconciles the canonical 18 labels on the fly, turning that failure into a
-* non-event without the user having to run `doctor`/`repair` by hand.
-*
-* **Best-effort by contract**: it never throws and never aborts the verb. `syncLabels`
-* already encodes its outcome in a {@link SyncLabelsResult} (a placeholder slug ⇒
-* `skipped`, a `gh` error ⇒ `failed`); the surrounding try/catch only guards the
-* unlikely case of the command runner rejecting. When the self-heal cannot help (gh
-* still unauthenticated at verb time), the verb proceeds and falls back to its own
-* load-bearing error, which points at `doctor`/`repair`.
-*/
 const ensureLabels = async (repoSlug, provider) => {
 	try {
 		return await syncLabels(repoSlug, provider);
@@ -951,17 +646,6 @@ const ensureLabels = async (repoSlug, provider) => {
 };
 //#endregion
 //#region src/labels/delete-labels.ts
-/**
-* Delete the `harness:*` labels from the task-storage repo via `gh label delete`.
-* Opt-in (`uninstall --labels`) because labels live on the remote and may be
-* attached to live issues. Never throws — returns a status the caller surfaces,
-* symmetric to `syncLabels`.
-*
-* `gh label delete --yes` is idempotent from our side: a non-zero exit for an
-* already-absent label is benign and simply doesn't count toward `deleted`. A
-* missing `gh` (exit 127) skips the whole pass cleanly — the uninstall still
-* succeeded, the labels are just left for the user to remove.
-*/
 const deleteLabels = async (taskStorageRepo, provider) => {
 	if (taskStorageRepo === "OWNER/REPO") return {
 		status: "skipped",
@@ -986,39 +670,17 @@ const deleteLabels = async (taskStorageRepo, provider) => {
 };
 //#endregion
 //#region src/labels/format-labels.ts
-/**
-* Lines reporting the harness:* label reconciliation outcome (decision B2.2),
-* for `install`/`update`/`repair`. An empty array means "print nothing" — the
-* null result (the verb never touched labels). On a non-fatal `skipped`/`failed`
-* the install still succeeded, so it reports two lines: the reason and the fix.
-*/
 const formatLabelSync = (sync) => {
 	if (!sync) return [];
 	if (sync.status === "synced") return [sync.created.length + sync.updated.length === 0 ? "Labels already in sync." : `Labels synced: ${sync.created.length} created, ${sync.updated.length} updated.`];
 	return [`Labels not synced (${sync.status}): ${sync.reason}`, "Run `lemony doctor` to re-check once resolved."];
 };
-/**
-* Lines reporting a verb's best-effort label preflight (ADR 0013, `spinoff`/`discovery`).
-* Unlike {@link formatLabelSync} it stays silent unless the preflight actually created or
-* edited a label — the common case (labels already in sync) must not add noise to every
-* verb run. A fully failed/skipped preflight (nothing changed) is also silent: the verb
-* proceeds and its own load-bearing error (which points at doctor/repair) covers the
-* unrecoverable case. A **partial** failure (some labels synced, then a `gh` call errored)
-* does report — the "Synced N" line alone would otherwise read as a clean success, so it
-* carries a warning.
-*/
 const formatLabelSelfHeal = (sync) => {
 	if (!sync) return [];
 	if (sync.created.length + sync.updated.length === 0) return [];
 	const partialFailure = sync.status === "failed" ? " (warning: some harness:* labels could not be synced — run `lemony doctor`)" : "";
 	return [`Synced ${sync.created.length} missing and ${sync.updated.length} drifted harness:* labels before continuing.${partialFailure}`];
 };
-/**
-* Lines reporting the `uninstall` label outcome — symmetric to {@link formatLabelSync}.
-* When `--labels` was not requested the labels are left in place (they live on remote
-* issues) with a hint to re-run. A null deletion (requested but the pass never ran) is
-* silent. The indentation matches the surrounding uninstall summary block.
-*/
 const formatLabelDeletion = (deletion, requested) => {
 	if (!requested) return ["  Labels left in place (they live on remote issues). Re-run `uninstall --labels` to delete the harness:* labels."];
 	if (!deletion) return [];
@@ -1141,26 +803,13 @@ const createTaskTrackerProvider = (type, runCommand) => {
 };
 //#endregion
 //#region src/discovery/discovery.constant.ts
-/**
-* The status label a paused task wears while a discovery is open. Standalone (no
-* `typeof`-derived type backs it), so it lives here rather than in `discovery.model.ts`.
-* Mirrors `labels.model.ts`'s taxonomy — a guard test asserts the alignment.
-*/
 const PAUSED_STATUS_LABEL = "harness:status:paused-for-clarification";
 //#endregion
 //#region src/discovery/build-labels.ts
-/**
-* Pure builders for the `harness:*` label names the discovery verb toggles. A
-* verb-object logic module of its own (`build-labels`), kept out of `discovery.ts`
-* (the verb orchestration) and `discovery.constant.ts` (values-only).
-*/
-/** Build the full status label name from its suffix. */
 const buildStatusLabel = (status) => `harness:status:${status}`;
-/** Build the full discovery flag name from its tier. */
 const buildDiscoveryLabel = (tier) => `harness:discovery:${tier}`;
 //#endregion
 //#region src/discovery/discovery.model.ts
-/** The six discovery tiers (T1–T6); the issue carries `harness:discovery:T<n>`. */
 const DISCOVERY_TIERS = [
 	"T1",
 	"T2",
@@ -1169,12 +818,6 @@ const DISCOVERY_TIERS = [
 	"T5",
 	"T6"
 ];
-/**
-* The mutually-exclusive status a task may be paused from / resumed to (`paused_from`).
-* Only the three active-work phases — discoveries are raised during spec authoring,
-* implementation, or review, never from `pending`/`spec-ready`/`done`. These must stay a
-* subset of `labels.model.ts`'s status labels; a guard test asserts the alignment.
-*/
 const RESUMABLE_STATUSES = [
 	"spec-in-progress",
 	"in-progress",
@@ -1182,18 +825,6 @@ const RESUMABLE_STATUSES = [
 ];
 //#endregion
 //#region src/discovery/discovery.ts
-/**
-* Reflect a raised/resolved discovery onto its GitHub issue (#109): flip the status
-* label, toggle the `harness:discovery:T<n>` flag, and (on pause) post a comment.
-* Encodes the protocol so the `resolve-discovery` skill stays thin.
-*
-* Two tiers of strictness (ADR 0007): the **label transition is fail-loud** — a failed
-* label op stops the run and returns `ok:false` (the CLI exits 1), because a label is
-* load-bearing, unlike telemetry's fire-and-forget emit. The **pause comment is
-* best-effort** — if it fails the labels still stand (`ok:true`) but `warning` is set
-* and surfaced (visible, not silent). That split also makes a retry safe: a retry after
-* a comment failure re-applies only the idempotent labels, never a duplicate comment.
-*/
 const runDiscovery = async (inputs) => {
 	const action = parseAction(inputs.action);
 	const taskId = requireFlag$1(inputs.taskId, "task-id");
@@ -1242,7 +873,6 @@ const runDiscovery = async (inputs) => {
 		labelSync
 	};
 };
-/** Pause: leave the current status, enter paused, flag the tier. */
 const pauseLabelSteps = (provider, ref, tier, status) => [
 	{
 		label: `removed ${buildStatusLabel(status)}`,
@@ -1257,7 +887,6 @@ const pauseLabelSteps = (provider, ref, tier, status) => [
 		run: () => provider.addLabel(ref, buildDiscoveryLabel(tier))
 	}
 ];
-/** Resume: clear the tier flag, leave paused, restore the prior status. */
 const resumeLabelSteps = (provider, ref, tier, status) => [
 	{
 		label: `removed ${buildDiscoveryLabel(tier)}`,
@@ -1298,55 +927,1099 @@ const failureReason$1 = (result) => {
 	return `\`gh\` failed (exit ${result.code})${suffix}${detail ? `: ${detail}` : ""}`;
 };
 //#endregion
+//#region src/fs/exists.ts
+const pathExists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+//#endregion
+//#region src/fs/list-files.ts
+const listFiles = async (dir) => {
+	const entries = await readdir(dir, { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
+		return [entry.name];
+	}))).flat();
+};
+//#endregion
+//#region src/fs/prune-empty-dirs.ts
+const pruneEmptyDirs = async (repoRoot, removedFiles) => {
+	const dirs = /* @__PURE__ */ new Set();
+	for (const relPath of removedFiles) {
+		let dir = dirname(relPath);
+		while (dir !== "." && dir !== sep) {
+			dirs.add(dir);
+			dir = dirname(dir);
+		}
+	}
+	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
+	for (const dir of ordered) try {
+		await rmdir(join(repoRoot, dir));
+	} catch {}
+};
+//#endregion
+//#region src/fs/write-managed.ts
+const writeManaged = async (root, relPath, content, executable) => {
+	const dest = join(root, relPath);
+	await mkdir(dirname(dest), { recursive: true });
+	await writeFile(dest, content);
+	await chmod(dest, executable ? 493 : 420);
+};
+//#endregion
+//#region src/fs/symlink-guard.ts
+const assertNoSymlinkTraversal = async (root, relPaths) => {
+	const components = /* @__PURE__ */ new Set();
+	for (const relPath of relPaths) {
+		let current = "";
+		for (const part of relPath.split(sep)) {
+			if (part.length === 0) continue;
+			current = current ? join(current, part) : part;
+			components.add(current);
+		}
+	}
+	const offenders = (await Promise.all([...components].map(async (rel) => {
+		try {
+			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
+		} catch {
+			return null;
+		}
+	}))).filter((rel) => rel !== null);
+	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
+};
+//#endregion
+//#region src/design-tokens/design-tokens.constant.ts
+const DESIGN_TOKENS_FILE = "docs/design-tokens.json";
+const SCANNED_EXTENSIONS = [
+	".css",
+	".scss",
+	".sass",
+	".less",
+	".styl",
+	".pcss",
+	".postcss",
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".vue",
+	".svelte",
+	".astro",
+	".mdx",
+	".html"
+];
+const STYLESHEET_EXTENSIONS = [
+	".css",
+	".scss",
+	".sass",
+	".less",
+	".styl",
+	".pcss",
+	".postcss"
+];
+const IGNORED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	".next",
+	".cache",
+	".claude"
+]);
+//#endregion
+//#region src/design-tokens/design-tokens.model.ts
+const TOKEN_TIERS = [
+	"primitive",
+	"semantic",
+	"component"
+];
+//#endregion
+//#region src/design-tokens/token-parse.ts
+const aliasTarget = (value) => {
+	if (typeof value !== "string") return void 0;
+	const match = /^\{([^{}\s]+)\}$/.exec(value.trim());
+	return match ? match[1] : void 0;
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+//#endregion
+//#region src/design-tokens/design-tokens.ts
+const runValidate = async (inputs) => {
+	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+	if (!await pathExists(tokenPath)) return {
+		ok: true,
+		tokensFound: false,
+		tokenCount: 0,
+		filesScanned: 0,
+		violations: []
+	};
+	const fileCheck = validateTokenFile(await readFile(tokenPath, "utf8"));
+	if (!fileCheck.ok) return {
+		ok: false,
+		tokensFound: true,
+		tokenCount: fileCheck.tokenCount,
+		filesScanned: 0,
+		violations: fileCheck.violations
+	};
+	const scanRoot = inputs.scanDir ? join(inputs.repoRoot, inputs.scanDir) : inputs.repoRoot;
+	const extensions = mergeExtensions(inputs.extraExtensions);
+	const sourceViolations = await scanSource(inputs.repoRoot, scanRoot, extensions);
+	return {
+		ok: sourceViolations.violations.length === 0,
+		tokensFound: true,
+		tokenCount: fileCheck.tokenCount,
+		filesScanned: sourceViolations.filesScanned,
+		violations: sourceViolations.violations
+	};
+};
+const validateTokenFile = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return {
+			ok: false,
+			tokenCount: 0,
+			violations: [{
+				kind: "invalid-json",
+				message: `${DESIGN_TOKENS_FILE} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+			}]
+		};
+	}
+	if (!isRecord(parsed)) return {
+		ok: false,
+		tokenCount: 0,
+		violations: [{
+			kind: "malformed-token-file",
+			message: `${DESIGN_TOKENS_FILE} must be a JSON object with primitive/semantic/component tiers.`
+		}]
+	};
+	const violations = [];
+	for (const key of Object.keys(parsed)) {
+		if (key.startsWith("$")) continue;
+		if (!TOKEN_TIERS.includes(key)) violations.push({
+			kind: "malformed-token-file",
+			message: `unknown top-level group "${key}" — only ${TOKEN_TIERS.join("/")} (and $-prefixed metadata) are allowed at the top level.`
+		});
+	}
+	const tokens = /* @__PURE__ */ new Map();
+	for (const tier of TOKEN_TIERS) {
+		const group = parsed[tier];
+		if (group === void 0) continue;
+		if (!isRecord(group)) {
+			violations.push({
+				kind: "malformed-token-file",
+				message: `tier "${tier}" must be an object of token groups.`
+			});
+			continue;
+		}
+		collectTokens$1(group, tier, tier, tokens, violations);
+	}
+	violations.push(...collectAliasViolations(tokens));
+	return {
+		ok: violations.length === 0,
+		tokenCount: tokens.size,
+		violations
+	};
+};
+const collectTokens$1 = (node, tier, path, out, violations) => {
+	for (const [key, child] of Object.entries(node)) {
+		if (key.startsWith("$")) continue;
+		const childPath = `${path}.${key}`;
+		if (!isRecord(child)) {
+			violations.push({
+				kind: "malformed-token-file",
+				message: `"${childPath}" must be a token object or a group, not a bare value.`
+			});
+			continue;
+		}
+		if ("$value" in child) {
+			out.set(childPath, {
+				tier,
+				value: child.$value
+			});
+			const stray = Object.keys(child).filter((k) => !k.startsWith("$"));
+			if (stray.length > 0) violations.push({
+				kind: "malformed-token-file",
+				message: `token "${childPath}" has both a $value and nested group(s) (${stray.join(", ")}) — a token cannot also be a group.`
+			});
+		} else collectTokens$1(child, tier, childPath, out, violations);
+	}
+};
+const collectAliasViolations = (tokens) => {
+	const violations = [];
+	for (const [path, token] of tokens) {
+		const alias = aliasTarget(token.value);
+		if (alias === void 0) continue;
+		if (token.tier === "primitive") {
+			violations.push({
+				kind: "primitive-not-literal",
+				message: `primitive token "${path}" must hold a literal value, not the alias "{${alias}}".`
+			});
+			continue;
+		}
+		if (!tokens.has(alias)) {
+			violations.push({
+				kind: "unresolved-alias",
+				message: `token "${path}" references "{${alias}}", which does not exist.`
+			});
+			continue;
+		}
+		if (aliasChainCycles(path, tokens)) violations.push({
+			kind: "cyclic-alias",
+			message: `token "${path}" has an alias chain that never resolves to a literal value (alias cycle).`
+		});
+	}
+	return violations;
+};
+const aliasChainCycles = (start, tokens) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = start;
+	while (current !== void 0) {
+		if (seen.has(current)) return true;
+		seen.add(current);
+		const token = tokens.get(current);
+		if (token === void 0) return false;
+		current = aliasTarget(token.value);
+	}
+	return false;
+};
+const mergeExtensions = (extra) => {
+	const set = new Set(SCANNED_EXTENSIONS);
+	for (const raw of extra ?? []) {
+		const lower = raw.trim().toLowerCase();
+		if (lower.length === 0) continue;
+		set.add(lower.startsWith(".") ? lower : `.${lower}`);
+	}
+	return set;
+};
+const scanSource = async (repoRoot, scanRoot, extensions) => {
+	if (!await pathExists(scanRoot)) return {
+		filesScanned: 0,
+		violations: []
+	};
+	const files = (await collectSourceFiles(scanRoot, extensions)).toSorted();
+	const violations = [];
+	let filesScanned = 0;
+	for (const file of files) {
+		const content = await readFile(file, "utf8").catch(() => void 0);
+		if (content === void 0) continue;
+		filesScanned += 1;
+		const relPath = relative(repoRoot, file).split(sep).join("/");
+		violations.push(...scanFile(relPath, extname(file).toLowerCase(), content));
+	}
+	return {
+		filesScanned,
+		violations
+	};
+};
+const collectSourceFiles = async (dir, extensions) => {
+	const entries = await readdir(dir, { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (IGNORED_DIRS.has(entry.name)) return [];
+			return collectSourceFiles(full, extensions);
+		}
+		return extensions.has(extname(entry.name).toLowerCase()) ? [full] : [];
+	}))).flat();
+};
+const HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/;
+const FUNCTIONAL_COLOR = /\b(?:rgb|rgba|hsl|hsla)\s*\(/i;
+const PX_DIMENSION = /\b(\d*\.?\d+)px\b/g;
+const EXEMPT_DIMENSIONS = /* @__PURE__ */ new Set(["0", "1"]);
+const scanFile = (relPath, ext, content) => {
+	const isStylesheet = STYLESHEET_EXTENSIONS.includes(ext);
+	const violations = [];
+	content.split("\n").forEach((line, index) => {
+		if (line.includes("design-tokens-allow")) return;
+		const lineNo = index + 1;
+		if (HEX_COLOR.test(line) || FUNCTIONAL_COLOR.test(line)) violations.push({
+			kind: "hardcoded-color",
+			message: `raw color literal — reference a token from ${DESIGN_TOKENS_FILE} instead.`,
+			file: relPath,
+			line: lineNo
+		});
+		if (isStylesheet && hasRawDimension(line)) violations.push({
+			kind: "hardcoded-dimension",
+			message: `raw dimension literal — reference a token from ${DESIGN_TOKENS_FILE} instead.`,
+			file: relPath,
+			line: lineNo
+		});
+	});
+	return violations;
+};
+const hasRawDimension = (line) => {
+	for (const match of line.matchAll(PX_DIMENSION)) {
+		const value = match[1];
+		if (value !== void 0 && !EXEMPT_DIMENSIONS.has(value)) return true;
+	}
+	return false;
+};
+//#endregion
+//#region src/design-tokens/color-contrast.ts
+const clamp = (value, lo, hi) => Math.min(hi, Math.max(lo, value));
+const parseColor = (raw) => {
+	const value = raw.trim();
+	if (value.startsWith("#")) return parseHex(value);
+	const fn = /^(rgba?|hsla?)\(\s*(.*?)\s*\)$/i.exec(value);
+	if (!fn) return void 0;
+	const kind = fn[1]?.toLowerCase() ?? "";
+	const body = fn[2] ?? "";
+	return kind.startsWith("rgb") ? parseRgb(body) : parseHsl(body);
+};
+const expandHex = (s) => s.split("").map((c) => c + c).join("");
+const parseHex = (hex) => {
+	const h = hex.slice(1);
+	if (!/^[0-9a-fA-F]+$/.test(h)) return void 0;
+	const full = h.length === 3 || h.length === 4 ? expandHex(h) : h.length === 6 || h.length === 8 ? h : void 0;
+	if (full === void 0) return void 0;
+	return {
+		r: parseInt(full.slice(0, 2), 16),
+		g: parseInt(full.slice(2, 4), 16),
+		b: parseInt(full.slice(4, 6), 16),
+		a: full.length === 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1
+	};
+};
+const splitBody = (body) => body.replace(/\//g, " ").split(/[\s,]+/).map((token) => token.trim()).filter((token) => token.length > 0);
+const parseChannel = (token) => {
+	if (token.endsWith("%")) {
+		const pct = Number(token.slice(0, -1));
+		return Number.isFinite(pct) ? clamp(pct / 100, 0, 1) * 255 : void 0;
+	}
+	const n = Number(token);
+	return Number.isFinite(n) ? clamp(n, 0, 255) : void 0;
+};
+const parseAlpha = (token) => {
+	if (token.endsWith("%")) {
+		const pct = Number(token.slice(0, -1));
+		return Number.isFinite(pct) ? clamp(pct / 100, 0, 1) : 1;
+	}
+	const n = Number(token);
+	return Number.isFinite(n) ? clamp(n, 0, 1) : 1;
+};
+const parseRgb = (body) => {
+	const parts = splitBody(body);
+	if (parts.length < 3) return void 0;
+	const r = parseChannel(parts[0] ?? "");
+	const g = parseChannel(parts[1] ?? "");
+	const b = parseChannel(parts[2] ?? "");
+	if (r === void 0 || g === void 0 || b === void 0) return void 0;
+	const a = parts[3] !== void 0 ? parseAlpha(parts[3]) : 1;
+	return {
+		r: Math.round(r),
+		g: Math.round(g),
+		b: Math.round(b),
+		a
+	};
+};
+const parseHsl = (body) => {
+	const parts = splitBody(body);
+	if (parts.length < 3) return void 0;
+	const h = Number((parts[0] ?? "").replace(/deg$/i, ""));
+	const s = parsePercent(parts[1] ?? "");
+	const l = parsePercent(parts[2] ?? "");
+	if (!Number.isFinite(h) || s === void 0 || l === void 0) return void 0;
+	const a = parts[3] !== void 0 ? parseAlpha(parts[3]) : 1;
+	return {
+		...hslToRgb((h % 360 + 360) % 360, s, l),
+		a
+	};
+};
+const parsePercent = (token) => {
+	const n = Number(token.endsWith("%") ? token.slice(0, -1) : token);
+	return Number.isFinite(n) ? clamp(n / 100, 0, 1) : void 0;
+};
+const hslToRgb = (h, s, l) => {
+	const c = (1 - Math.abs(2 * l - 1)) * s;
+	const x = c * (1 - Math.abs(h / 60 % 2 - 1));
+	const m = l - c / 2;
+	const [r1, g1, b1] = h < 60 ? [
+		c,
+		x,
+		0
+	] : h < 120 ? [
+		x,
+		c,
+		0
+	] : h < 180 ? [
+		0,
+		c,
+		x
+	] : h < 240 ? [
+		0,
+		x,
+		c
+	] : h < 300 ? [
+		x,
+		0,
+		c
+	] : [
+		c,
+		0,
+		x
+	];
+	return {
+		r: Math.round((r1 + m) * 255),
+		g: Math.round((g1 + m) * 255),
+		b: Math.round((b1 + m) * 255)
+	};
+};
+const WHITE = {
+	r: 255,
+	g: 255,
+	b: 255,
+	a: 1
+};
+const flatten = (color, backdrop) => ({
+	r: color.r * color.a + backdrop.r * (1 - color.a),
+	g: color.g * color.a + backdrop.g * (1 - color.a),
+	b: color.b * color.a + backdrop.b * (1 - color.a),
+	a: 1
+});
+const linearizeChannel = (channel) => {
+	const s = channel / 255;
+	return s <= .03928 ? s / 12.92 : ((s + .055) / 1.055) ** 2.4;
+};
+const relativeLuminance = ({ r, g, b }) => .2126 * linearizeChannel(r) + .7152 * linearizeChannel(g) + .0722 * linearizeChannel(b);
+const contrastRatio = (foreground, background) => {
+	const bg = background.a < 1 ? flatten(background, WHITE) : background;
+	const l1 = relativeLuminance(foreground.a < 1 ? flatten(foreground, bg) : foreground);
+	const l2 = relativeLuminance(bg);
+	const light = Math.max(l1, l2);
+	const dark = Math.min(l1, l2);
+	return Math.round((light + .05) / (dark + .05) * 100) / 100;
+};
+//#endregion
+//#region src/design-tokens/contrast.constant.ts
+const CONTRAST_EXTENSION = "com.lemony.contrast";
+const MODES_EXTENSION = "com.lemony.modes";
+const BASE_MODE = "base";
+const DEFAULT_LEVEL = "text";
+const WCAG_FLOORS = {
+	text: 4.5,
+	large: 3,
+	"non-text": 3
+};
+//#endregion
+//#region src/design-tokens/contrast.model.ts
+const CONTRAST_LEVELS = [
+	"text",
+	"large",
+	"non-text"
+];
+//#endregion
+//#region src/design-tokens/contrast.ts
+const runContrast = async (inputs) => {
+	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+	if (!await pathExists(tokenPath)) return emptyResult$1(false);
+	const raw = await readFile(tokenPath, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return {
+			...emptyResult$1(true),
+			ok: false,
+			problems: [`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`]
+		};
+	}
+	if (!isRecord(parsed)) return {
+		...emptyResult$1(true),
+		ok: false,
+		problems: [`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`]
+	};
+	const tokens = collectTokens(parsed);
+	const problems = [];
+	const pairs = measurePairs(discoverPairs(tokens, problems), declaredModes(tokens), tokens);
+	return {
+		ok: problems.length === 0 && pairs.every((pair) => pair.passes),
+		tokensFound: true,
+		pairsChecked: pairs.length,
+		pairs,
+		problems
+	};
+};
+const emptyResult$1 = (tokensFound) => ({
+	ok: true,
+	tokensFound,
+	pairsChecked: 0,
+	pairs: [],
+	problems: []
+});
+const collectTokens = (parsed) => {
+	const out = /* @__PURE__ */ new Map();
+	const walk = (node, tier, path) => {
+		for (const [key, child] of Object.entries(node)) {
+			if (key.startsWith("$") || !isRecord(child)) continue;
+			const childPath = `${path}.${key}`;
+			if ("$value" in child) out.set(childPath, {
+				tier,
+				value: child.$value,
+				node: child
+			});
+			else walk(child, tier, childPath);
+		}
+	};
+	for (const tier of TOKEN_TIERS) {
+		const group = parsed[tier];
+		if (isRecord(group)) walk(group, tier, tier);
+	}
+	return out;
+};
+const readExtension = (node, namespace) => {
+	const extensions = node["$extensions"];
+	return isRecord(extensions) ? extensions[namespace] : void 0;
+};
+const declaredModes = (tokens) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const token of tokens.values()) {
+		const modes = readExtension(token.node, MODES_EXTENSION);
+		if (isRecord(modes)) {
+			for (const name of Object.keys(modes)) if (name.trim().length > 0) names.add(name);
+		}
+	}
+	return [...names].toSorted();
+};
+const discoverPairs = (tokens, problems) => {
+	const merged = /* @__PURE__ */ new Map();
+	const add = (spec) => {
+		merged.set(`${spec.foreground}|${spec.background}`, spec);
+	};
+	for (const spec of conventionPairs(tokens)) add(spec);
+	for (const spec of extensionPairs(tokens, problems)) add(spec);
+	return [...merged.values()];
+};
+const conventionPairs = (tokens) => {
+	const pairs = [];
+	for (const [path, token] of tokens) {
+		if (token.tier !== "semantic") continue;
+		const segments = path.split(".");
+		const leaf = segments[segments.length - 1] ?? "";
+		if (!leaf.startsWith("on-") || leaf.length <= 3) continue;
+		const basePath = [...segments.slice(0, -1), leaf.slice(3)].join(".");
+		if (!tokens.has(basePath)) continue;
+		if (!resolveColor(path, "base", tokens)) continue;
+		if (!resolveColor(basePath, "base", tokens)) continue;
+		pairs.push({
+			foreground: path,
+			background: basePath,
+			level: DEFAULT_LEVEL,
+			source: "convention"
+		});
+	}
+	return pairs;
+};
+const extensionPairs = (tokens, problems) => {
+	const pairs = [];
+	for (const [path, token] of tokens) {
+		const declaration = readExtension(token.node, CONTRAST_EXTENSION);
+		if (declaration === void 0) continue;
+		const entries = Array.isArray(declaration) ? declaration : [declaration];
+		for (const entry of entries) {
+			if (!isRecord(entry) || typeof entry["against"] !== "string") {
+				problems.push(`token "${path}" has a malformed ${CONTRAST_EXTENSION} declaration — expected { against: "{token.path}", level? }.`);
+				continue;
+			}
+			const against = aliasTarget(entry["against"]) ?? entry["against"];
+			if (against === path) {
+				problems.push(`token "${path}" declares contrast against itself — a pair needs two different tokens.`);
+				continue;
+			}
+			if (!tokens.has(against)) {
+				problems.push(`token "${path}" contrast-against "${entry["against"]}" does not resolve to a known token.`);
+				continue;
+			}
+			if (!resolveColor(against, "base", tokens)) {
+				problems.push(`token "${path}" contrast-against "${entry["against"]}" is not a colour token.`);
+				continue;
+			}
+			if (!resolveColor(path, "base", tokens)) {
+				problems.push(`token "${path}" declares a contrast pair but is not itself a colour token.`);
+				continue;
+			}
+			pairs.push({
+				foreground: path,
+				background: against,
+				level: normalizeLevel(entry["level"], path, problems),
+				source: "extension"
+			});
+		}
+	}
+	return pairs;
+};
+const normalizeLevel = (raw, path, problems) => {
+	if (raw === void 0) return DEFAULT_LEVEL;
+	if (typeof raw === "string" && CONTRAST_LEVELS.includes(raw)) return raw;
+	problems.push(`token "${path}" has an unknown contrast level "${String(raw)}" — use ${CONTRAST_LEVELS.join("/")}.`);
+	return DEFAULT_LEVEL;
+};
+const measurePairs = (specs, modes, tokens) => {
+	const rows = [];
+	for (const spec of specs) {
+		const baseFg = resolveColor(spec.foreground, BASE_MODE, tokens);
+		const baseBg = resolveColor(spec.background, BASE_MODE, tokens);
+		if (!baseFg || !baseBg) continue;
+		rows.push(makeRow(spec, BASE_MODE, baseFg, baseBg));
+		for (const mode of modes) {
+			const fg = resolveColor(spec.foreground, mode, tokens) ?? baseFg;
+			const bg = resolveColor(spec.background, mode, tokens) ?? baseBg;
+			if (sameColor(fg, baseFg) && sameColor(bg, baseBg)) continue;
+			rows.push(makeRow(spec, mode, fg, bg));
+		}
+	}
+	return rows;
+};
+const makeRow = (spec, mode, foreground, background) => {
+	const ratio = contrastRatio(foreground, background);
+	const floor = WCAG_FLOORS[spec.level];
+	return {
+		foreground: spec.foreground,
+		background: spec.background,
+		mode,
+		level: spec.level,
+		ratio,
+		floor,
+		passes: ratio >= floor,
+		source: spec.source
+	};
+};
+const sameColor = (a, b) => a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;
+const resolveColor = (path, mode, tokens, seen = /* @__PURE__ */ new Set()) => {
+	if (seen.has(path) || seen.size >= 64) return void 0;
+	seen.add(path);
+	const token = tokens.get(path);
+	if (!token) return void 0;
+	let value = token.value;
+	if (mode !== "base") {
+		const modes = readExtension(token.node, MODES_EXTENSION);
+		if (isRecord(modes) && modes[mode] !== void 0) value = modes[mode];
+	}
+	const alias = aliasTarget(value);
+	if (alias !== void 0) return resolveColor(alias, mode, tokens, seen);
+	return typeof value === "string" ? parseColor(value) : void 0;
+};
+//#endregion
+//#region src/design-tokens/design-sync.constant.ts
+const DESIGN_TOOL_EXTENSION = "com.lemony.design-tool";
+//#endregion
+//#region src/design-tokens/neutral-mapping.ts
+const KNOWN_TIERS = new Set(TOKEN_TIERS);
+const dtcgToNeutral = (parsed) => {
+	const variables = [];
+	for (const tier of TOKEN_TIERS) {
+		const group = parsed[tier];
+		if (isRecord(group)) walk(group, tier, variables);
+	}
+	return {
+		schemaVersion: 1,
+		variables: variables.toSorted(byName)
+	};
+};
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+const walk = (node, path, out) => {
+	for (const [key, child] of Object.entries(node)) {
+		if (key.startsWith("$") || !isRecord(child)) continue;
+		const childPath = `${path}.${key}`;
+		if ("$value" in child) out.push(toVariable$1(childPath, child));
+		else walk(child, childPath, out);
+	}
+};
+const toVariable$1 = (name, node) => {
+	const type = typeof node["$type"] === "string" ? node["$type"] : "";
+	const modes = readModes(node);
+	const alias = aliasTarget(node["$value"]);
+	const base = {
+		name,
+		type
+	};
+	if (modes) base.modes = modes;
+	if (alias !== void 0) return {
+		...base,
+		ref: alias
+	};
+	return {
+		...base,
+		value: stringifyValue(node["$value"])
+	};
+};
+const stringifyValue = (value) => value === void 0 || value === null ? "" : String(value);
+const readModes = (node) => {
+	const extensions = node["$extensions"];
+	const modes = isRecord(extensions) ? extensions[MODES_EXTENSION] : void 0;
+	if (!isRecord(modes)) return void 0;
+	const out = {};
+	for (const [name, value] of Object.entries(modes)) if (name.trim().length > 0 && typeof value === "string") out[name] = value;
+	return Object.keys(out).length > 0 ? out : void 0;
+};
+const toIncoming = (variable) => {
+	const isAlias = variable.ref !== void 0;
+	const value = isAlias ? `{${variable.ref}}` : variable.value ?? "";
+	const type = variable.type;
+	const first = variable.name.split(".")[0] ?? "";
+	if (KNOWN_TIERS.has(first)) return withModes({
+		path: variable.name,
+		tier: first,
+		type,
+		value
+	}, variable);
+	const tier = isAlias ? "semantic" : "primitive";
+	return withModes({
+		path: `${tier}.${variable.name}`,
+		tier,
+		type,
+		value
+	}, variable);
+};
+const withModes = (token, variable) => variable.modes ? {
+	...token,
+	modes: variable.modes
+} : token;
+const comparisonKey = (type, value, modes) => JSON.stringify({
+	type,
+	value,
+	modes: sortedModes(modes)
+});
+const sortedModes = (modes) => {
+	if (!modes) return null;
+	const out = {};
+	for (const name of Object.keys(modes).toSorted()) out[name] = modes[name] ?? "";
+	return out;
+};
+const diffNeutralAgainstJson = (neutral, parsed) => {
+	const current = /* @__PURE__ */ new Map();
+	for (const variable of dtcgToNeutral(parsed).variables) current.set(variable.name, variable);
+	const changes = [];
+	for (const variable of neutral.variables) {
+		const incoming = toIncoming(variable);
+		const existing = current.get(incoming.path);
+		const after = incoming.value;
+		const before = existing ? neutralValue(existing) : void 0;
+		changes.push({
+			path: incoming.path,
+			tier: incoming.tier,
+			kind: classifyImport(existing, incoming, variable),
+			...before !== void 0 ? { before } : {},
+			after
+		});
+	}
+	return changes.toSorted((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+};
+const neutralValue = (variable) => variable.ref !== void 0 ? `{${variable.ref}}` : variable.value ?? "";
+const classifyImport = (existing, incoming, variable) => {
+	if (!existing) return "new";
+	return comparisonKey(existing.type, neutralValue(existing), existing.modes) === comparisonKey(incoming.type, incoming.value, variable.modes) ? "unchanged" : "changed";
+};
+const mergeNeutralIntoJson = (neutral, parsed, only) => {
+	const merged = structuredClone(parsed);
+	const onlySet = only ? new Set(only) : void 0;
+	const written = [];
+	const skipped = [];
+	for (const variable of neutral.variables) {
+		const incoming = toIncoming(variable);
+		if (onlySet && !onlySet.has(incoming.path)) continue;
+		(setToken(merged, incoming) ? written : skipped).push(incoming.path);
+	}
+	return {
+		merged,
+		written: written.toSorted(),
+		skipped: skipped.toSorted()
+	};
+};
+const isTokenNode = (value) => isRecord(value) && "$value" in value;
+const hasGroupChildren = (value) => isRecord(value) && Object.keys(value).some((key) => !key.startsWith("$"));
+const setToken = (root, incoming) => {
+	const segments = incoming.path.split(".");
+	const leafKey = segments[segments.length - 1];
+	if (!leafKey) return false;
+	let probe = root;
+	for (const segment of segments.slice(0, -1)) {
+		if (!isRecord(probe)) break;
+		const next = probe[segment];
+		if (isTokenNode(next)) return false;
+		probe = next;
+	}
+	if (isRecord(probe) && hasGroupChildren(probe[leafKey])) return false;
+	let node = root;
+	for (const segment of segments.slice(0, -1)) {
+		const next = node[segment];
+		if (!isRecord(next)) node[segment] = {};
+		node = node[segment];
+	}
+	const leaf = { $value: incoming.value };
+	if (incoming.type.length > 0) leaf["$type"] = incoming.type;
+	if (incoming.modes) leaf["$extensions"] = { [MODES_EXTENSION]: incoming.modes };
+	node[leafKey] = leaf;
+	return true;
+};
+const upsertPlan = (parsed, toolState) => {
+	const current = /* @__PURE__ */ new Map();
+	for (const variable of toolState?.variables ?? []) current.set(variable.name, variable);
+	const plan = [];
+	for (const variable of dtcgToNeutral(parsed).variables) plan.push({
+		name: variable.name,
+		kind: classifyExport(variable, current)
+	});
+	return plan;
+};
+const classifyExport = (projected, current) => {
+	const existing = current.get(projected.name);
+	if (!existing) return "create";
+	return comparisonKey(projected.type, neutralValue(projected), projected.modes) === comparisonKey(existing.type, neutralValue(existing), existing.modes) ? "unchanged" : "update";
+};
+//#endregion
+//#region src/design-tokens/sync-io.ts
+const parseNeutralFile = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new Error(`neutral file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed["variables"])) throw new Error("neutral file must be a JSON object with a \"variables\" array.");
+	const schemaVersion = typeof parsed["schemaVersion"] === "number" ? parsed["schemaVersion"] : 0;
+	const provider = typeof parsed["provider"] === "string" ? parsed["provider"] : void 0;
+	return {
+		schemaVersion,
+		...provider ? { provider } : {},
+		variables: parsed["variables"].flatMap(toVariable)
+	};
+};
+const toVariable = (raw) => {
+	if (!isRecord(raw) || typeof raw["name"] !== "string" || raw["name"].trim().length === 0) return [];
+	const type = typeof raw["type"] === "string" ? raw["type"] : "";
+	const variable = {
+		name: raw["name"],
+		type
+	};
+	if (typeof raw["ref"] === "string") variable.ref = raw["ref"];
+	else if (typeof raw["value"] === "string") variable.value = raw["value"];
+	const modes = readStringMap(raw["modes"]);
+	if (modes) variable.modes = modes;
+	return [variable];
+};
+const readStringMap = (raw) => {
+	if (!isRecord(raw)) return void 0;
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) if (key.trim().length > 0 && typeof value === "string") out[key] = value;
+	return Object.keys(out).length > 0 ? out : void 0;
+};
+const readJsonObject = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new Error(`${DESIGN_TOKENS_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)}) — run \`design-tokens validate\` first.`, { cause: error });
+	}
+	if (!isRecord(parsed)) throw new Error(`${DESIGN_TOKENS_FILE} must be a JSON object — run \`design-tokens validate\` first.`);
+	return parsed;
+};
+const writeJsonFile = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const writeNeutralFile = (file) => writeJsonFile(file);
+//#endregion
+//#region src/design-tokens/import-tokens.ts
+const runImport = async (inputs) => {
+	const empty = {
+		tokensFound: false,
+		changes: [],
+		applied: false,
+		written: [],
+		skipped: [],
+		problems: []
+	};
+	if (!await pathExists(inputs.neutralPath)) return {
+		...empty,
+		problems: [`neutral file not found: ${inputs.neutralPath}`]
+	};
+	let neutral;
+	try {
+		neutral = parseNeutralFile(await readFile(inputs.neutralPath, "utf8"));
+	} catch (error) {
+		return {
+			...empty,
+			problems: [asMessage$1(error)]
+		};
+	}
+	if (neutral.schemaVersion !== 1) return {
+		...empty,
+		problems: [`neutral file schemaVersion ${neutral.schemaVersion} is not supported (expected 1).`]
+	};
+	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+	const tokensFound = await pathExists(tokenPath);
+	let parsed;
+	try {
+		parsed = tokensFound ? readJsonObject(await readFile(tokenPath, "utf8")) : {};
+	} catch (error) {
+		return {
+			...empty,
+			tokensFound,
+			problems: [asMessage$1(error)]
+		};
+	}
+	const changes = diffNeutralAgainstJson(neutral, parsed);
+	if (!inputs.apply) return {
+		tokensFound,
+		changes,
+		applied: false,
+		written: [],
+		skipped: [],
+		problems: []
+	};
+	const { merged, written, skipped } = mergeNeutralIntoJson(neutral, parsed, inputs.only);
+	await mkdir(dirname(tokenPath), { recursive: true });
+	await writeFile(tokenPath, writeJsonFile(merged));
+	return {
+		tokensFound,
+		changes,
+		applied: true,
+		written,
+		skipped,
+		problems: []
+	};
+};
+const asMessage$1 = (error) => error instanceof Error ? error.message : String(error);
+//#endregion
+//#region src/design-tokens/drift.ts
+const readBinding = (parsed) => {
+	const extensions = parsed["$extensions"];
+	const binding = isRecord(extensions) ? extensions[DESIGN_TOOL_EXTENSION] : void 0;
+	if (!isRecord(binding)) return void 0;
+	const provider = binding["provider"];
+	if (typeof provider !== "string" || provider.trim().length === 0) return;
+	const lastProjected = binding["lastProjected"];
+	return {
+		provider,
+		...typeof lastProjected === "string" ? { lastProjected } : {}
+	};
+};
+const projectionHash = (parsed) => {
+	const canonical = JSON.stringify(dtcgToNeutral(parsed).variables.map(canonicalVariable));
+	return createHash("sha256").update(canonical).digest("hex");
+};
+const canonicalVariable = (variable) => ({
+	name: variable.name,
+	type: variable.type,
+	value: variable.value ?? null,
+	ref: variable.ref ?? null,
+	modes: variable.modes ? Object.fromEntries(Object.keys(variable.modes).toSorted().map((name) => [name, variable.modes?.[name] ?? ""])) : null
+});
+const driftReport = (parsed) => {
+	const binding = readBinding(parsed);
+	if (!binding) return {
+		tokensFound: true,
+		provider: void 0,
+		state: "n/a"
+	};
+	if (binding.lastProjected === void 0) return {
+		tokensFound: true,
+		provider: binding.provider,
+		state: "never-projected"
+	};
+	const state = projectionHash(parsed) === binding.lastProjected ? "in-sync" : "export-pending";
+	return {
+		tokensFound: true,
+		provider: binding.provider,
+		state
+	};
+};
+//#endregion
+//#region src/design-tokens/export-tokens.ts
+const runExport = async (inputs) => {
+	const empty = {
+		tokensFound: false,
+		plan: [],
+		hash: "",
+		recorded: false,
+		problems: []
+	};
+	const tokenPath = join(inputs.repoRoot, DESIGN_TOKENS_FILE);
+	if (!await pathExists(tokenPath)) return empty;
+	let parsed;
+	try {
+		parsed = readJsonObject(await readFile(tokenPath, "utf8"));
+	} catch (error) {
+		return {
+			...empty,
+			tokensFound: true,
+			problems: [asMessage(error)]
+		};
+	}
+	const binding = readBinding(parsed);
+	if (!binding) return {
+		...empty,
+		tokensFound: true,
+		problems: [`no design tool is declared — add a "${DESIGN_TOOL_EXTENSION}" provider to ${DESIGN_TOKENS_FILE} before exporting.`]
+	};
+	const hash = projectionHash(parsed);
+	let toolState;
+	if (inputs.toolStatePath !== void 0) {
+		if (!await pathExists(inputs.toolStatePath)) return {
+			...empty,
+			tokensFound: true,
+			hash,
+			problems: [`tool-state file not found: ${inputs.toolStatePath}`]
+		};
+		try {
+			toolState = parseNeutralFile(await readFile(inputs.toolStatePath, "utf8"));
+		} catch (error) {
+			return {
+				...empty,
+				tokensFound: true,
+				hash,
+				problems: [asMessage(error)]
+			};
+		}
+	}
+	const plan = upsertPlan(parsed, toolState);
+	if (inputs.outPath !== void 0) {
+		const projection = dtcgToNeutral(parsed);
+		projection.provider = binding.provider;
+		await writeFile(inputs.outPath, writeNeutralFile(projection));
+	}
+	if (inputs.record) {
+		await writeFile(tokenPath, writeJsonFile(stampBaseline(parsed, hash)));
+		return {
+			tokensFound: true,
+			plan,
+			hash,
+			recorded: true,
+			problems: []
+		};
+	}
+	return {
+		tokensFound: true,
+		plan,
+		hash,
+		recorded: false,
+		problems: []
+	};
+};
+const stampBaseline = (parsed, hash) => {
+	const clone = structuredClone(parsed);
+	const extensions = isRecord(clone["$extensions"]) ? { ...clone["$extensions"] } : {};
+	const binding = isRecord(extensions["com.lemony.design-tool"]) ? { ...extensions[DESIGN_TOOL_EXTENSION] } : {};
+	binding["lastProjected"] = hash;
+	extensions[DESIGN_TOOL_EXTENSION] = binding;
+	clone["$extensions"] = extensions;
+	return clone;
+};
+const asMessage = (error) => error instanceof Error ? error.message : String(error);
+//#endregion
 //#region src/spinoff/spinoff.constant.ts
-/**
-* The presence labels a captured stub carries. They mirror `labels.model.ts`'s
-* taxonomy (a guard test asserts the alignment, the same way the discovery verb guards
-* its label strings).
-*/
-/** Every captured stub is a harness-managed task. */
 const MANAGED_LABEL = "harness:managed";
-/** It enters at `pending` — the fit level (L1/L2/L3) is decided at pickup, not capture. */
 const PENDING_STATUS_LABEL = "harness:status:pending";
-/**
-* The kind-routing flag a `--kind=architecture-drift` stub also carries (#148). Its
-* presence tells a later pickup to resolve the stub via the Architect's
-* `update-architecture` (ADR 0011), not a normal code task.
-*/
 const ARCHITECTURE_DRIFT_LABEL = "harness:architecture-drift";
 //#endregion
 //#region src/spinoff/spinoff.model.ts
-/**
-* The `--kind` values `spinoff` accepts (#148). A `kind` tags the stub with a routing
-* label so a later pickup resolves it via the right path — today the only value,
-* `architecture-drift`, routes to the Architect's `update-architecture` (ADR 0011)
-* instead of a normal code task. A coupled `const … as const` + its derived type, so it
-* stays in `.model.ts` per the code-conventions exception.
-*/
 const SPINOFF_KINDS = ["architecture-drift"];
 //#endregion
 //#region src/spinoff/spinoff.ts
-/**
-* Park a non-blocking, independent defect discovered mid-task as a tracked stub (#112,
-* `/spinoff`): open a `harness:managed` + `harness:status:pending` issue (no
-* fit-assessment, no spec — the level is decided at pickup), then emit a
-* `followup_captured` telemetry line linking the stub to its parent task.
-*
-* Two tiers of strictness (mirrors the discovery verb, ADR 0007): the **stub creation
-* is fail-loud** — it is the load-bearing artifact, so a failed create returns
-* `ok:false` (CLI exits 1) and writes no telemetry. The **emit is best-effort** —
-* once the stub exists the capture has succeeded, so a failed emit (or an issue number
-* we can't parse from gh's output) leaves `ok:true` with a surfaced `warning`, never a
-* silent skip and never a misleading failure.
-*
-* Unlike the discovery verb (which mutates an *existing* issue with idempotent label
-* ops), capture is **not idempotent by design**: each run opens a fresh issue, so a
-* repeat `/spinoff` for the same defect creates a second stub. Accepted for Phase 1 —
-* a stub is cheap and dedup would add friction to the capture-and-keep-going path the
-* PRD optimizes for; the human-repeat case is mitigated separately by the proactive
-* offer's "no re-offer the same finding twice in a session" rule. The best-effort emit
-* surfaces "stub #N created" precisely so a retry-on-warning re-creates nothing.
-*/
 const runSpinoff = async (inputs) => {
 	const title = requireFlag(inputs.title, "title");
 	const severity = parseSeverity(inputs.severity);
@@ -1410,15 +2083,9 @@ const runSpinoff = async (inputs) => {
 		labelSync
 	};
 };
-/**
-* Compose the stub body: the captor's detail plus a parent text-reference (PRD minor
-* points — a cheap "Discovered during #N", no new label taxonomy). Either part may be
-* absent; outside a task there is no parent line.
-*/
 const composeBody = (body, parentId) => {
 	return [body?.trim(), parentId !== null ? `Discovered during #${parentId}` : ""].filter(Boolean).join("\n\n");
 };
-/** Parse the trailing issue number from a `gh issue create` URL (…/issues/<n>). */
 const parseIssueId = (url) => url.match(/\/issues\/(\d+)\b/)?.[1];
 const requireFlag = (value, name) => {
 	const trimmed = value?.trim();
@@ -1435,10 +2102,6 @@ const parseKind = (raw) => {
 	if (SPINOFF_KINDS.includes(raw)) return raw;
 	throw new Error(`spinoff: --kind must be one of ${SPINOFF_KINDS.join("|")} (got "${raw}").`);
 };
-/**
-* The presence labels a stub of this kind carries: the two every stub gets, plus the
-* kind's routing label (#148) so a later pickup resolves it via the right path.
-*/
 const kindLabels = (kind) => {
 	const labels = [MANAGED_LABEL, PENDING_STATUS_LABEL];
 	if (kind === "architecture-drift") labels.push(ARCHITECTURE_DRIFT_LABEL);
@@ -1451,18 +2114,6 @@ const failureReason = (result) => {
 };
 //#endregion
 //#region src/telemetry/sanitize.constant.ts
-/**
-* The sanitizer axis of every `(event_type, field)` occurrence — the executable
-* mirror of the axis tables in `catalog/schemas/tier2-events.md` (the authority;
-* the doc wins on conflict). `sanitize-doc-sync.spec.ts` parses the doc and asserts
-* it equals this map; `sanitize.constant.spec.ts` asserts this map's key set is
-* **exactly** the Zod schema's field set per type (no field untagged, none extra) —
-* the fail-closed completeness gate (D9).
-*
-* Every type carries the six envelope fields (spread from `ENVELOPE_AXIS`) plus its
-* own. `task_id` rides `identity` everywhere: a per-project correlator, meaningless
-* once `project` is dropped.
-*/
 const ENVELOPE_AXIS = {
 	type: "internal-enum",
 	ts: "metric",
@@ -1528,13 +2179,6 @@ const FIELD_AXIS = {
 		attributed_name: "internal-enum"
 	}
 };
-/**
-* Which axes survive each export tier (D9). `local-only` is in neither set — it
-* never leaves the laptop. `anonymous` is the strict subset; `project` additionally
-* keeps `identity` + `free-text`. A field is kept iff its axis is in the tier's set;
-* any field whose axis is absent — or that has no axis entry at all — is dropped
-* (fail-closed).
-*/
 const KEEP_BY_TIER = {
 	anonymous: /* @__PURE__ */ new Set(["internal-enum", "metric"]),
 	project: /* @__PURE__ */ new Set([
@@ -1546,17 +2190,6 @@ const KEEP_BY_TIER = {
 };
 //#endregion
 //#region src/telemetry/sanitize.ts
-/**
-* Project one raw `events.jsonl` line to the fields the tier keeps, or `null` to
-* drop the whole line. Fail-closed on every front (D9): malformed JSON, an unknown
-* `type`, an invalid shape, or an unexpected key (Zod `.strict()`) all drop the
-* line; a field whose axis is absent from the tier's keep-set — or that has no axis
-* entry at all — is dropped. Only `internal-enum` + `metric` survive `anonymous`,
-* so a valid event always keeps at least `{ type, ts, harness_version }`.
-*
-* Key order is preserved from the parsed line, so re-serializing the same bytes
-* yields the same output and the same content-hash (D6 idempotency).
-*/
 const sanitizeLine = (raw, tier) => {
 	let parsed;
 	try {
@@ -1578,67 +2211,16 @@ const sanitizeLine = (raw, tier) => {
 };
 //#endregion
 //#region src/telemetry/telemetry.constant.ts
-/** The append-only event log the cursor walks (ADR 0008). */
 const EVENTS_RELPATH = join(".claude", "state", "events.jsonl");
-/** Byte-offset watermark of what has been delivered (D5, gitignored). */
 const CURSOR_RELPATH = join(".claude", "state", "telemetry-cursor.json");
-/**
-* The quarantine log (#227, D17): lines the client decided **not** to send —
-* Zod-invalid (`invalid-schema`) or a single line over the payload cap (`oversize`).
-* Gitignored + inspectable; "nothing is silently lost". One `{ts, reason, line}` JSON
-* object per quarantined line (append-only). NOT the wire — these never leave the box.
-*/
 const REJECTED_RELPATH = join(".claude", "state", "telemetry-rejected.jsonl");
-/**
-* Client-side payload cap (~1MB, D16). The send engine chunks the unsent tail into
-* line-aligned segments whose **sanitized** body stays ≤ this, so a 413 from the
-* Worker (its own ~1MB backstop, #230) can never permanently stall a cursor. Normal
-* batches are KB — this only bites a large uncleanly-closed backlog or a pathological
-* single line. The Worker cap must be ≥ this value so a maxed-out segment is accepted.
-*/
 const PAYLOAD_CAP_BYTES = 1e6;
-/** Per-request hard timeout — the send must never stall a hook (D4). */
 const DEFAULT_TIMEOUT_MS = 3e3;
-/**
-* Prefix-prune threshold (#240, amends ADR 0008's append-only invariant). The send
-* engine collapses the **confirmed-sent prefix** of `events.jsonl` only once that
-* prefix (the cursor offset `C`) has grown past this — so a small log is never
-* rewritten, and the bounded growth is reclaimed in coarse ~5 MB steps (~25-50k tiny
-* events). Only the 2xx-delivered prefix is ever dropped; unsent bytes are preserved.
-*/
 const PRUNE_THRESHOLD_BYTES = 5e6;
-/**
-* Basename of the per-prune drain file: `events.draining.<id>` beside `events.jsonl`,
-* paired with a `.meta` sidecar holding the sent offset `C`. A unique `<id>` per prune
-* (#240) stops two concurrent send processes from clobbering each other's drain via
-* `rename`. Recovery globs `events.draining.*` and replays any orphan left by a crash.
-*/
 const DRAINING_BASENAME = "events.draining";
-/**
-* Base URL of the deployed ingest Worker (`telemetry-worker/`, #225). The
-* `LEMONY_TELEMETRY_ENDPOINT` env var overrides it (e.g. the /tmp e2e smoke or
-* a local `wrangler dev`). An empty value → send is disabled.
-*/
 const TELEMETRY_ENDPOINT = "https://lemony-telemetry.lemoncode.workers.dev";
 //#endregion
 //#region src/telemetry/chunk-tail.ts
-/**
-* Split the unsent raw tail of `events.jsonl` into line-aligned segments whose
-* **sanitized** body stays ≤ `capBytes` (#227, D16) — so a 413 can never permanently
-* stall the cursor (D5). Each segment carries the exact span of **raw** bytes it
-* consumes (kept + rejected + blank lines, newlines included), so the caller advances
-* the cursor per-segment without re-deriving offsets; the raw spans sum to the tail's
-* byte length exactly.
-*
-* Per line (D17): `sanitizeLine` returning `null` ⟺ the same Zod that gates the wire
-* rejected it → an `invalid-schema` reject; a deliverable line whose sanitized form
-* alone exceeds the cap → an `oversize` reject (pathological; free text is bounded).
-* Rejects ride inside the segment that contains them and flush to quarantine only when
-* that segment advances (atomic with the cursor). A segment carrying only rejects/blanks
-* (no deliverable body) has `body: null` and can appear **only** as the trailing segment.
-*
-* Pure and deterministic: no clock, no IO. The flush timestamp is stamped by the caller.
-*/
 const chunkTail = (rawTail, tier, capBytes = PAYLOAD_CAP_BYTES) => {
 	const parts = rawTail.split("\n");
 	const segments = [];
@@ -1693,20 +2275,7 @@ const chunkTail = (rawTail, tier, capBytes = PAYLOAD_CAP_BYTES) => {
 };
 //#endregion
 //#region src/telemetry/consent.constant.ts
-/**
-* Per-repo-local personal opt-out (#229): a developer's "off for *this* checkout"
-* choice, gitignored beside its `state/` siblings so it is never committed (a
-* committed opt-out would silence the whole team — that is the committed
-* `telemetry.enabled: false` lever instead). Read-only here; the `disable`/`enable`
-* writer is the verb set (#232). Shape: `{ "disabled": true }`.
-*/
 const CONSENT_RELPATH = join(".claude", "state", "telemetry-consent.json");
-/**
-* Truthy allow-list for `LEMONY_TELEMETRY_DISABLED` (case-insensitive, trimmed):
-* only these values disable. `0`/`false`/empty/unset have no effect — the env is an
-* off-switch, never an on-switch (the on path is the on-by-default floor). Next.js
-* style (`=1`).
-*/
 const ENV_DISABLE_VALUES = [
 	"1",
 	"true",
@@ -1714,23 +2283,12 @@ const ENV_DISABLE_VALUES = [
 ];
 //#endregion
 //#region src/telemetry/consent.ts
-/** The env var disables only on its truthy allow-list; everything else is inert. */
 const isEnvDisabled = (value) => value !== void 0 && ENV_DISABLE_VALUES.includes(value.trim().toLowerCase());
-/**
-* The cross-tool `DO_NOT_TRACK` standard: present and ≠ `0`/empty → opted out. Unlike
-* the Lemony allow-list, ANY non-`0` value disables (privacy-conservative): a developer
-* who exported it globally wants telemetry off by default, whatever the value (#237).
-*/
 const isDoNotTrackSet = (value) => {
 	if (value === void 0) return false;
 	const trimmed = value.trim();
 	return trimmed !== "" && trimmed !== "0";
 };
-/**
-* Read the per-repo-local opt-out. A missing file, unreadable dir, malformed JSON,
-* or anything other than a literal `disabled: true` → not opted out (tolerant, like
-* the cursor reader): the lever is one-directional, so only `true` silences.
-*/
 const isLocallyOptedOut = async (repoRoot) => {
 	try {
 		const raw = await readFile(join(repoRoot, CONSENT_RELPATH), "utf8");
@@ -1739,22 +2297,6 @@ const isLocallyOptedOut = async (repoRoot) => {
 		return false;
 	}
 };
-/**
-* Resolve whether a telemetry send may proceed (#229). Five **off-switches over an
-* on-by-default floor**, highest precedence first (first OFF wins, short-circuit):
-*
-*   1. env `DO_NOT_TRACK` (cross-tool standard, any non-`0` value) — `source: do-not-track`
-*   2. env `LEMONY_TELEMETRY_DISABLED` (truthy) — `source: env`
-*   3. per-repo-local `.claude/state/telemetry-consent.json` `disabled:true` — `local`
-*   4. committed `harness.config.yml` `telemetry.enabled: false` — `config`
-*   5. nothing set → ON, tier `anonymous` — `source: default`
-*
-* A committed `enabled: true` is a no-op affirmation of the floor, so the ON source
-* is always `default`. **Fail-safe**: if the config is missing or invalid (it throws
-* under `.strict()`), resolve OFF with `source: config` — privacy-conservative, so a
-* broken config never silently sends; consistent with telemetry's silent-fail (D4).
-* The send-engine consults this first and no-ops when OFF (defense-in-depth).
-*/
 const resolveConsent = async ({ repoRoot, env: env$4 = env }) => {
 	if (isDoNotTrackSet(env$4["DO_NOT_TRACK"])) return {
 		enabled: false,
@@ -1786,20 +2328,9 @@ const resolveConsent = async ({ repoRoot, env: env$4 = env }) => {
 };
 //#endregion
 //#region src/telemetry/content-hash.ts
-/**
-* SHA-256 of the batch bytes as lowercase hex — the R2 object key stem (D6).
-* A lost-ack re-send of the same bytes produces the same key and overwrites,
-* never duplicates. Per-content, NOT a persistent install id (safe for
-* anonymous).
-*/
 const contentHash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 //#endregion
 //#region src/telemetry/cursor.ts
-/**
-* Read the byte-offset cursor. A missing, empty, or unparseable cursor is
-* treated as "never sent" (`offset: 0`) — telemetry must never throw into a
-* hook, and resending from the start is safe (idempotent content-hash keys).
-*/
 const readCursor = async (repoRoot) => {
 	try {
 		const raw = await readFile(join(repoRoot, CURSOR_RELPATH), "utf8");
@@ -1815,7 +2346,6 @@ const readCursor = async (repoRoot) => {
 		};
 	}
 };
-/** Persist the cursor (pretty-printed JSON), creating parent dirs as needed. */
 const writeCursor = async (repoRoot, cursor) => {
 	const path = join(repoRoot, CURSOR_RELPATH);
 	await mkdir(dirname(path), { recursive: true });
@@ -1825,30 +2355,12 @@ const writeCursor = async (repoRoot, cursor) => {
 //#region src/telemetry/prune.ts
 const stateDirOf = (repoRoot) => join(repoRoot, dirname(EVENTS_RELPATH));
 const eventsPathOf = (repoRoot) => join(repoRoot, EVENTS_RELPATH);
-/** A drain file is `events.draining.<id>` (its `.meta` sidecar is excluded). */
 const isDrainFile = (name) => name.startsWith(`events.draining.`) && !name.endsWith(".meta");
 const isDrainMeta = (name) => name.startsWith(`events.draining.`) && name.endsWith(".meta");
-/**
-* The unsent boundary in a drain buffer: the sidecar's `sent_offset` when it is a
-* trustworthy line boundary (`C === 0` or the byte before it is `\n`) within bounds,
-* else 0 — meaning "replay everything" (a missing/corrupt sidecar or an off-boundary
-* offset must never let us drop bytes that may be unsent). Mirrors the send engine's
-* cursor-robustness guard.
-*/
 const trustedOffset = (buf, sentOffset) => {
 	if (!Number.isFinite(sentOffset) || sentOffset <= 0 || sentOffset > buf.length) return 0;
 	return buf[sentOffset - 1] === 10 ? sentOffset : 0;
 };
-/**
-* Append the unsent overflow (whole lines) back into the fresh `events.jsonl`, batching
-* up to `ATOMIC_APPEND_BYTES` per write so it can never tear against a concurrent
-* `appendEvent` (#240). Each batch stays ≤ the cap because **every event line is well under
-* `PIPE_BUF` by schema** (`catalog/schemas/tier2-events.md`) — the same invariant the
-* primary emitter (`src/events/append.ts`) relies on for its own `O_APPEND` atomicity; a
-* line over the cap can't exist without already breaking that emitter. Blank lines carry no
-* event and are dropped. A single `O_APPEND` handle is reused for the whole replay; `'a'`
-* re-creates the file if an appender has not yet recreated it.
-*/
 const replayOverflow = async (eventsPath, overflow) => {
 	const handle = await open(eventsPath, "a");
 	try {
@@ -1867,7 +2379,6 @@ const replayOverflow = async (eventsPath, overflow) => {
 		await handle.close();
 	}
 };
-/** Replay one drain file's unsent tail into `events.jsonl`, then delete it + its meta. */
 const drainOne = async (stateDir, drainName) => {
 	const drainPath = join(stateDir, drainName);
 	const metaPath = `${drainPath}.meta`;
@@ -1892,13 +2403,6 @@ const drainOne = async (stateDir, drainName) => {
 	await rm(metaPath, { force: true });
 	return buf.byteLength - from;
 };
-/**
-* Recovery preamble (#240): replay any orphaned `events.draining.*` left by a crashed
-* prune back into `events.jsonl` before the send reads the tail, so a half-finished
-* prune never loses unsent events. Idempotent — re-running re-appends already-replayed
-* lines as harmless byte-identical duplicates (same content-hash R2 key). Never throws
-* (it runs in the fire-and-forget send, D4).
-*/
 const recoverDrainings = async (repoRoot) => {
 	const stateDir = stateDirOf(repoRoot);
 	let entries;
@@ -1911,23 +2415,6 @@ const recoverDrainings = async (repoRoot) => {
 	await Promise.all(entries.filter(isDrainMeta).filter((meta) => !entries.includes(meta.slice(0, -5))).map((meta) => rm(join(stateDir, meta), { force: true }).catch(() => {})));
 	return { recovered };
 };
-/**
-* Collapse the confirmed-sent prefix of `events.jsonl` once it exceeds the threshold
-* (#240), reclaiming bounded local growth without ever dropping unsent bytes. Lock-free
-* and crash-safe via rename + replay-overflow:
-*
-* 1. read `C = cursor.offset` (the 2xx-confirmed watermark); below the threshold → no-op.
-* 2. write the `.meta` sidecar (`{ sent_offset: C }`), then `rename` the live file to a
-*    unique `events.draining.<id>` — atomic; concurrent emitters `O_CREAT` a fresh log.
-* 3. reset the cursor to 0 (it now describes the fresh log; a crash before this leaves a
-*    stale-large cursor the send's past-EOF guard resends from 0).
-* 4. replay the drain's unsent tail (`[C:]`) line-by-line into the fresh log, then delete
-*    the drain + meta.
-*
-* Relies on events being order-independent (aggregation groups by version/component; the
-* cursor counts bytes, not order), so interleaving replay with live appends is safe.
-* Never throws (D4).
-*/
 const prunePrefix = async (repoRoot, options = {}) => {
 	const { thresholdBytes = PRUNE_THRESHOLD_BYTES } = options;
 	try {
@@ -1967,7 +2454,6 @@ const prunePrefix = async (repoRoot, options = {}) => {
 		return { prunedBytes: 0 };
 	}
 };
-/** Remove every `events.draining.*` (drain + meta) — used by `disable --purge-local`. */
 const purgeDrainings = async (repoRoot) => {
 	const stateDir = stateDirOf(repoRoot);
 	let entries;
@@ -1980,16 +2466,6 @@ const purgeDrainings = async (repoRoot) => {
 };
 //#endregion
 //#region src/telemetry/quarantine.ts
-/**
-* Append rejected lines to the quarantine log (#227, D17) — one `{ts, reason, line}`
-* JSON object per line, so "nothing is silently lost": a clock-skewed or otherwise
-* invalid line, or a pathological over-cap one, lands here (gitignored, inspectable)
-* instead of on the wire. Called by the send engine **only when the owning segment
-* advances the cursor**, so a transient `5xx`/offline retry never double-quarantines.
-*
-* Stamps each entry with the injected `now` (the same clock as the cursor) and returns
-* how many were written (0 → no file touched). Append-only; parent dirs created lazily.
-*/
 const appendRejects = async (repoRoot, rejects, now) => {
 	if (rejects.length === 0) return 0;
 	const path = join(repoRoot, REJECTED_RELPATH);
@@ -2007,7 +2483,6 @@ const appendRejects = async (repoRoot, rejects, now) => {
 };
 //#endregion
 //#region src/telemetry/send-telemetry.ts
-/** A result with the wire counters zeroed — the no-op / early-return baseline. */
 const emptyResult = (outcome, extra = {}) => ({
 	outcome,
 	segmentsSent: 0,
@@ -2017,35 +2492,6 @@ const emptyResult = (outcome, extra = {}) => ({
 	keys: [],
 	...extra
 });
-/**
-* Send the unsent tail of `events.jsonl`, robustly (#227). The tail is **sanitized to
-* the `anonymous` tier** (Phase 2 / #226 — the no-leak gate sits before the wire) and
-* **chunked** into line-aligned segments whose sanitized body stays ≤ the payload cap
-* (D16): each is its own content-hash R2 object (`anonymous/<sha256>.jsonl`), and the
-* byte-offset cursor advances **per-segment** so no backlog size or pathological line
-* can permanently stall it. Lines the client won't send (Zod-invalid, or a single
-* over-cap line) are **quarantined** to `telemetry-rejected.jsonl` (D17), never sent.
-*
-* Cursor policy (D17, revising D5's bare "advance only on 2xx"):
-* - `2xx` → advance past the segment + flush its quarantined lines.
-* - `4xx` (should-never-happen post-pre-validate) → loud local log + advance past the
-*   chunk (don't retry forever).
-* - `5xx` / network / timeout → transient: stop, do **not** advance; the next hook
-*   retries the same bytes (preserves the offline invariant, D4).
-*
-* The cursor is also hardened against truncation/desync: a cursor past EOF, or one no
-* longer on a line boundary (events.jsonl edited under us), resends from 0 — idempotent
-* content-hash keys make a re-PUT of already-stored bytes harmless.
-*
-* After delivering, the confirmed-sent prefix of `events.jsonl` is **pruned** once it
-* exceeds `PRUNE_THRESHOLD_BYTES` (#240, amends ADR 0008's append-only invariant) — a
-* crash-safe, lock-free rename + replay-overflow that reclaims bounded local growth
-* without ever dropping unsent bytes. A `recoverDrainings` preamble first replays any
-* drain a previous crashed prune left behind, so its unsent tail joins this run's send.
-*
-* **Never throws.** Every failure path returns a result without losing data, so a hook
-* is never blocked or broken (D4).
-*/
 const sendTelemetry = async (options) => {
 	const { repoRoot, endpoint = TELEMETRY_ENDPOINT, env, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, now = () => /* @__PURE__ */ new Date(), capBytes = PAYLOAD_CAP_BYTES, pruneThresholdBytes } = options;
 	const consent = await resolveConsent({
@@ -2146,37 +2592,14 @@ const sendTelemetry = async (options) => {
 };
 //#endregion
 //#region src/telemetry/consent-writer.ts
-/**
-* The writer counterpart to `consent.ts` (which only reads, #229). The verb set
-* (#232) owns the lever: `disable` writes the per-repo-local opt-out, `enable`
-* clears it. Both touch only `.claude/state/telemetry-consent.json` — never the
-* committed `harness.config.yml` (a team decision the dev must not flip silently)
-* nor the env var (a shell-/machine-wide lever outside the repo).
-*/
-/**
-* Opt this checkout out: write `{ "disabled": true }` (the only value `consent.ts`
-* honors). Creates `.claude/state/` if missing so `disable` works before the first
-* session has written any state.
-*/
 const disableLocally = async (repoRoot) => {
 	const path = join(repoRoot, CONSENT_RELPATH);
 	await mkdir(dirname(path), { recursive: true });
 	await writeFile(path, `${JSON.stringify({ disabled: true }, null, 2)}\n`);
 };
-/**
-* Clear the local opt-out by **deleting** the file — there is no "force on", only a
-* return to the on-by-default floor, so a lingering `{ disabled: false }` artifact
-* would be misleading. `force: true` makes a no-op enable (never disabled) safe.
-*/
 const enableLocally = async (repoRoot) => {
 	await rm(join(repoRoot, CONSENT_RELPATH), { force: true });
 };
-/**
-* `disable --purge-local`: delete the local event log, the send cursor, and any prune
-* drains (#240). Remote deletion is impossible by design (anonymous events carry no
-* identity to match on), so this only wipes what lives on this machine. Best-effort
-* (`force`) — a missing file is success.
-*/
 const purgeLocal = async (repoRoot) => {
 	await rm(join(repoRoot, EVENTS_RELPATH), { force: true });
 	await rm(join(repoRoot, CURSOR_RELPATH), { force: true });
@@ -2184,13 +2607,6 @@ const purgeLocal = async (repoRoot) => {
 };
 //#endregion
 //#region src/telemetry/telemetry-command.constant.ts
-/**
-* Human-readable explanation of which layer decided consent — surfaced by `status`,
-* `disable`, and `enable` so the user always sees *why* telemetry is on or off (the
-* precedence-honesty requirement, #232 C). `config` folds in the fail-safe case: an
-* invalid `harness.config.yml` resolves OFF with `source: config` (#229), so the label
-* names both the explicit `enabled: false` and the broken-config path.
-*/
 const SOURCE_LABEL = {
 	default: "default (on)",
 	"do-not-track": "the DO_NOT_TRACK environment variable (cross-tool standard)",
@@ -2200,13 +2616,6 @@ const SOURCE_LABEL = {
 };
 //#endregion
 //#region src/telemetry/telemetry-status.ts
-/**
-* Build the `telemetry status` report: the **effective** consent decision (whatever
-* the resolver returns, env › local › config › default) plus the send watermark. Pure
-* read — resolves consent and the cursor, never writes. `anonymous` is the only tier
-* in v1, so the report carries no tier field (a committed `tier:` is a `.strict()`
-* error, #229); the formatter labels the ON state "anonymous" inline.
-*/
 const buildTelemetryStatus = async ({ repoRoot, env: env$3 = env }) => {
 	const { enabled, source } = await resolveConsent({
 		repoRoot,
@@ -2220,7 +2629,6 @@ const buildTelemetryStatus = async ({ repoRoot, env: env$3 = env }) => {
 		lastSentTs: cursor.last_sent_ts
 	};
 };
-/** Render the status report as terse, human lines (one per `console.log`). */
 const formatTelemetryStatus = (report) => {
 	const headline = report.enabled ? "Telemetry: ON (anonymous)" : "Telemetry: OFF";
 	const lastSend = report.lastSentTs === "" ? "never" : report.lastSentTs;
@@ -2232,12 +2640,6 @@ const formatTelemetryStatus = (report) => {
 };
 //#endregion
 //#region src/telemetry/telemetry-show.ts
-/**
-* Build the `telemetry show` report — radical transparency (#232 F): every local event
-* in `events.jsonl`, paired with its `anonymous` export projection (`null` when the
-* sanitizer drops the line, e.g. a `local-only` field or an unknown event type). A
-* missing/unreadable log reads as zero events. Read-only.
-*/
 const buildTelemetryShow = async (repoRoot) => {
 	let raw;
 	try {
@@ -2257,11 +2659,6 @@ const buildTelemetryShow = async (repoRoot) => {
 		total: events.length
 	};
 };
-/**
-* Render the show report: the full raw log, then the full sanitized projection, so the
-* user can compare what is stored locally against exactly what would leave the machine.
-* No truncation by default — the user asked for the dump; paging is the shell's job.
-*/
 const formatTelemetryShow = (report) => {
 	if (report.total === 0) return ["No local telemetry events (.claude/state/events.jsonl is empty or absent)."];
 	const lines = [`${report.total} local event(s).`, ""];
@@ -2274,23 +2671,10 @@ const formatTelemetryShow = (report) => {
 };
 //#endregion
 //#region src/telemetry/telemetry-notice.constant.ts
-/**
-* Sentinel that records the **acknowledged consent fingerprint** (`enabled:source`),
-* not just "shown once" (D13): the disclosure re-shows whenever the effective consent
-* changes (fingerprint mismatch). Gitignored beside its `state/` siblings — it is a
-* per-checkout ack, never committed. A dotfile so it does not clutter `state/` listings.
-*/
 const NOTICE_SENTINEL_RELPATH = join(".claude", "state", ".telemetry-notice-shown");
-/**
-* The one-shot opt-out disclosure shown at `install` and on the first SessionStart
-* under on-by-default (D11, R2-critical). Names the exact opt-out verb and points at
-* PRIVACY.md (which lands in Phase 9, #233; the link text is wired now, the publish
-* gates on the file existing).
-*/
 const NOTICE_MESSAGE = "Anonymous telemetry is ON — run `lemony telemetry disable` to opt out. See PRIVACY.md.";
 //#endregion
 //#region src/telemetry/telemetry-notice.ts
-/** Read the acknowledged fingerprint; a missing/unreadable sentinel reads as `''`. */
 const readSentinel = async (repoRoot) => {
 	try {
 		return (await readFile(join(repoRoot, NOTICE_SENTINEL_RELPATH), "utf8")).trim();
@@ -2298,19 +2682,11 @@ const readSentinel = async (repoRoot) => {
 		return "";
 	}
 };
-/** Persist the acknowledged fingerprint, creating `.claude/state/` if needed. */
 const writeSentinel = async (repoRoot, fingerprint) => {
 	const path = join(repoRoot, NOTICE_SENTINEL_RELPATH);
 	await mkdir(dirname(path), { recursive: true });
 	await writeFile(path, `${fingerprint}\n`);
 };
-/**
-* Decide whether the opt-out disclosure should show (D11/D13). The fingerprint is the
-* resolved `enabled:source`; the disclosure prints **only when telemetry is ON** and
-* that fingerprint differs from the sentinel's last ack. When OFF, it never shows —
-* the "telemetry is ON, here's how to opt out" copy is meaningless once it is off, and
-* `telemetry status` covers the off case on demand. Pure read; `runNotice` does the I/O.
-*/
 const resolveNotice = async ({ repoRoot, env: env$1 = env }) => {
 	const { enabled, source } = await resolveConsent({
 		repoRoot,
@@ -2328,13 +2704,6 @@ const resolveNotice = async ({ repoRoot, env: env$1 = env }) => {
 		message: NOTICE_MESSAGE
 	};
 };
-/**
-* Show the disclosure if due, then record the ack so it stays quiet until the effective
-* consent changes. `print` is injected (the CLI passes `console.log`; tests capture).
-* Invoked from `install` (post-install printout) and from `init.sh` on SessionStart
-* (shelled out as `lemony telemetry notice`, #232 G — single TS resolver, no bash
-* duplication). Returns the decision so callers can assert/branch.
-*/
 const runNotice = async ({ repoRoot, env: env$2 = env, print }) => {
 	const decision = await resolveNotice({
 		repoRoot,
@@ -2348,13 +2717,6 @@ const runNotice = async ({ repoRoot, env: env$2 = env, print }) => {
 };
 //#endregion
 //#region src/telemetry/telemetry-flush.ts
-/**
-* Format the result of a `telemetry flush` (#227) as human-readable lines — the
-* verbose, user-facing counterpart to the terse one-liner `telemetry send` prints for
-* the hook. Same engine, richer presentation: it surfaces what the robust send engine
-* did (segments delivered, bytes, quarantined lines, server-rejected chunks) so a human
-* debugging "is my telemetry flowing?" gets the whole picture. Pure (no IO).
-*/
 const formatTelemetryFlush = (result) => {
 	if (result.outcome === "disabled") return [`Telemetry is off${result.source ? ` (source: ${result.source})` : ""} — nothing was sent.`];
 	const reclaimed = result.prunedBytes !== void 0 && result.prunedBytes > 0 ? `  reclaimed: ${result.prunedBytes} byte(s) of confirmed-sent events` : void 0;
@@ -2376,11 +2738,6 @@ const formatTelemetryFlush = (result) => {
 };
 //#endregion
 //#region src/colors/colors.constant.ts
-/**
-* Raw ANSI SGR escape sequences — the whole palette the CLI uses. Kept
-* dependency-free on purpose (#175): four status colors plus dim cover every
-* console report; a color library would be the heavier tool for the same job.
-*/
 const ANSI = {
 	green: "\x1B[32m",
 	yellow: "\x1B[33m",
@@ -2391,23 +2748,12 @@ const ANSI = {
 };
 //#endregion
 //#region src/colors/colors.ts
-/**
-* Color gate per https://no-color.org/: emit ANSI only on a TTY, and honor
-* `NO_COLOR` when it is present **and non-empty** (an empty string does not
-* disable, per the spec's wording). No `--no-color` flag and no `FORCE_COLOR`:
-* the env var + TTY cover every reported need (#175, fork 3).
-*/
 const colorsEnabled = (options) => {
 	const noColor = options.env["NO_COLOR"];
 	return options.isTty && (noColor === void 0 || noColor === "");
 };
 const wrap = (code) => (text) => `${code}${text}${ANSI.reset}`;
 const identity = (text) => text;
-/**
-* Build the palette once per process from the gate's verdict. Callers never
-* branch on color support — they always paint, and a disabled palette paints
-* with the identity.
-*/
 const buildPalette = (enabled) => enabled ? {
 	ok: wrap(ANSI.green),
 	warn: wrap(ANSI.yellow),
@@ -2423,123 +2769,8 @@ const buildPalette = (enabled) => enabled ? {
 };
 //#endregion
 //#region src/install/devdependency.constant.ts
-/**
-* The harness package — the devDependency a Node target should carry so the
-* telemetry CLI resolves from `node_modules/.bin` (#107/#113).
-*/
 const LEMONY_PACKAGE = "@lemoncode/lemony";
 //#endregion
-//#region src/fs/exists.ts
-/** True when a file or directory exists at `path`. */
-const pathExists = async (path) => {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-};
-//#endregion
-//#region src/fs/list-files.ts
-/**
-* List every file under `dir`, recursively, as paths relative to `dir` (using the
-* platform separator). Only files are returned, never directories. Order is not
-* guaranteed. Used to copy a whole skill directory — multi-file skills (a
-* `reference.md`, `scripts/`) keep their resources, not just `SKILL.md`.
-*/
-const listFiles = async (dir) => {
-	const entries = await readdir(dir, { withFileTypes: true });
-	return (await Promise.all(entries.map(async (entry) => {
-		if (entry.isDirectory()) return (await listFiles(join(dir, entry.name))).map((rel) => join(entry.name, rel));
-		return [entry.name];
-	}))).flat();
-};
-//#endregion
-//#region src/fs/prune-empty-dirs.ts
-/**
-* Remove the now-empty managed dirs that removing a set of files left behind (an
-* empty `.claude/skills/<name>/`, `.claude/commands/`, `.claude/agents/`, …). Walks
-* each removed file's ancestry deepest-first and `rmdir`s only empty dirs — a dir
-* that still holds a client file (or `.claude/state`) throws ENOTEMPTY and is left
-* alone. Shared by `uninstall` (whole-tree removal) and the reconcile prune path
-* (`update` / `repair` dropping orphaned vendor files), so a cohesive skill
-* directory never lingers empty after its files go.
-*/
-const pruneEmptyDirs = async (repoRoot, removedFiles) => {
-	const dirs = /* @__PURE__ */ new Set();
-	for (const relPath of removedFiles) {
-		let dir = dirname(relPath);
-		while (dir !== "." && dir !== sep) {
-			dirs.add(dir);
-			dir = dirname(dir);
-		}
-	}
-	const ordered = [...dirs].toSorted((a, b) => b.length - a.length);
-	for (const dir of ordered) try {
-		await rmdir(join(repoRoot, dir));
-	} catch {}
-};
-//#endregion
-//#region src/fs/write-managed.ts
-/**
-* Write a managed file under `root` at a repo-relative path — the one definition of
-* "a managed file is content + exec mode, parent dirs created". Shared by `install`-
-* adjacent writers (`update` apply, `rollback` restore, snapshot working tree) so the
-* mode policy lives in one place.
-*
-* The mode is set **unconditionally**: `writeFile` preserves an existing file's bits,
-* so a file the new catalog flips executable→plain would otherwise keep a stale `+x`.
-* chmod both ways keeps the on-disk mode tracking the source.
-*/
-const writeManaged = async (root, relPath, content, executable) => {
-	const dest = join(root, relPath);
-	await mkdir(dirname(dest), { recursive: true });
-	await writeFile(dest, content);
-	await chmod(dest, executable ? 493 : 420);
-};
-//#endregion
-//#region src/fs/symlink-guard.ts
-/**
-* Refuse the whole operation if any managed path traverses a **symlink** component
-* (P7/S2, closing the S1 deferral). Lexical `..` traversal is already closed; this
-* shuts the symbolic vector: a committed/poisoned file at a managed path (e.g.
-* `.claude/agents/x` → `/etc/cron.d`, lexically clean) would otherwise let the
-* subsequent `writeFile`/`rm` land OUTSIDE the repo, at the user's privilege.
-*
-* Every path component from `root` down to and including the leaf is `lstat`'d: a
-* symlink at any level (a parent dir or the file itself, which `writeFile` would
-* follow) is an offender. Components that don't exist yet (`mkdir` will create them)
-* are fine. Pre-flight by design — it refuses before ANY write, never half-applies.
-*
-* **TOCTOU is out of scope, by design.** The check (`lstat`) and the use
-* (`writeFile`/`rm`) are separate syscalls, so a local process racing the CLI could
-* swap a checked dir for a symlink in the window between them. Closing that would
-* need `O_NOFOLLOW`/`openat` on every component at every writer — and the parent-dir
-* vector still would not fully close. Under the trust model (local dev, single user)
-* the racing process already runs at the user's privilege, so the symlink gains it
-* nothing it could not do directly; this guard is defense-in-depth against a
-* *poisoned committed path*, not a concurrent attacker.
-*/
-const assertNoSymlinkTraversal = async (root, relPaths) => {
-	const components = /* @__PURE__ */ new Set();
-	for (const relPath of relPaths) {
-		let current = "";
-		for (const part of relPath.split(sep)) {
-			if (part.length === 0) continue;
-			current = current ? join(current, part) : part;
-			components.add(current);
-		}
-	}
-	const offenders = (await Promise.all([...components].map(async (rel) => {
-		try {
-			return (await lstat(join(root, rel))).isSymbolicLink() ? rel : null;
-		} catch {
-			return null;
-		}
-	}))).filter((rel) => rel !== null);
-	if (offenders.length > 0) throw new Error("Refusing to write — a managed path traverses a symlink (a redirect could land outside the repo):\n" + offenders.map((rel) => `  ${rel}`).join("\n"));
-};
-//#endregion
 //#region src/install/devdependency.ts
 const inspectDevDependency = async (repoRoot) => {
 	const pkgPath = join(repoRoot, "package.json");
@@ -2553,36 +2784,12 @@ const inspectDevDependency = async (repoRoot) => {
 };
 //#endregion
 //#region src/scan/scan.constant.ts
-/**
-* The repo-relative convention path the scan looks for to set `hasArchitectureDoc`
-* (which gates the `update-architecture` skill via `applies-when: has-architecture-doc`).
-*
-* Lives here, not inline in `scan.ts`, so the same literal is the single source for
-* both the detection (`scanRepo`) and the human-facing latent-capability report
-* (`skills.ts` `CAPABILITY_REGISTRY` → `trigger`). Forward-slash so it doubles as the
-* display string; `join(root, …)` normalizes separators for the on-disk probe.
-*/
 const ARCHITECTURE_DOC_PATH = "docs/architecture.md";
-/**
-* The `package.json` script name whose presence sets `hasMutationTesting` (which gates
-* the `mutation-testing` skill via `applies-when: has-mutation-testing`, #155). Unlike
-* `ARCHITECTURE_DOC_PATH` this is NOT an on-disk path — the probe reads
-* `package.json` → `scripts[MUTATION_SCRIPT_NAME]` — so its human-facing display string
-* is built separately in the `CAPABILITY_REGISTRY` `trigger`. The harness stays
-* tool-agnostic: the script may run Stryker or any mutation tool; only the conventional
-* name is fixed, mirroring how `verify` delegates to the project's declared scripts.
-*/
 const MUTATION_SCRIPT_NAME = "test:mutation";
 //#endregion
 //#region src/scan/scan.ts
 const ORIGIN_URL = /\[remote "origin"\][^[]*?url\s*=\s*(\S+)/;
 const SLUG_FROM_URL = /[/:]([^/:]+)\/([^/]+)$/;
-/**
-* Extract the `owner/name` slug from the origin remote url in a `.git/config`
-* body. Handles both `https://host/owner/name(.git)` and
-* `git@host:owner/name(.git)`. Returns null when there is no origin remote or
-* the url is unparseable.
-*/
 const parseOriginSlug = (gitConfig) => {
 	const url = ORIGIN_URL.exec(gitConfig)?.[1];
 	if (!url) return null;
@@ -2592,13 +2799,6 @@ const parseOriginSlug = (gitConfig) => {
 	if (!owner || !name) return null;
 	return `${owner}/${name}`;
 };
-/**
-* Read `.git/config` and return the origin remote slug (`owner/name`), or null
-* when the file is missing, the repo has no origin, or the url is unparseable.
-* Exposed so callers that only need the slug (the install CLI resolving
-* `task_storage.repo` before deciding whether to prompt) skip the full
-* capability scan.
-*/
 const readOriginSlug = async (root) => {
 	try {
 		return parseOriginSlug(await readFile(join(root, ".git", "config"), "utf8"));
@@ -2606,11 +2806,6 @@ const readOriginSlug = async (root) => {
 		return null;
 	}
 };
-/**
-* Whether `package.json` declares a `test:mutation` script (#155). Reads content
-* (not just existence) and tolerates a missing/malformed manifest — a non-Node repo,
-* absent `scripts`, or unparseable JSON all read as "no mutation testing", never throw.
-*/
 const hasMutationScript = async (root) => {
 	try {
 		const script = JSON.parse(await readFile(join(root, "package.json"), "utf8")).scripts?.[MUTATION_SCRIPT_NAME];
@@ -2619,7 +2814,6 @@ const hasMutationScript = async (root) => {
 		return false;
 	}
 };
-/** Detect the repo capabilities the installer needs to render templates and gate skills. */
 const scanRepo = async (root) => {
 	const [isGitRepo, hasClaudeMd, hasContextMd, hasDocs, hasPackageJson, hasArchitectureDoc, hasMutationTesting] = await Promise.all([
 		pathExists(join(root, ".git")),
@@ -2643,23 +2837,14 @@ const scanRepo = async (root) => {
 };
 //#endregion
 //#region src/skills/frontmatter.ts
-/** Leading `---\n … \n---` block at the very start of a markdown document. */
 const FRONTMATTER_BLOCK$1 = /^---\n([\s\S]*?)\n---/;
-/** A `key: value` line; the key is the first dash/word token before the colon. */
 const FIELD_LINE = /^([\w-]+)\s*:\s*(.*)$/;
-/** Parse a `[a, b, c]` inline list, or return the raw scalar untouched. */
 const parseValue = (raw) => {
 	if (!(raw.startsWith("[") && raw.endsWith("]"))) return raw;
 	const inner = raw.slice(1, -1).trim();
 	if (inner === "") return [];
 	return inner.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 };
-/**
-* Read the leading frontmatter of a markdown document into a flat record. A
-* deliberately minimal YAML subset — scalars and inline `[a, b]` lists — which is
-* all the skill catalog uses; no dependency, matching `renderTemplate`'s style.
-* Returns `{}` when the document has no frontmatter block.
-*/
 const parseFrontmatter = (content) => {
 	const block = FRONTMATTER_BLOCK$1.exec(content)?.[1];
 	if (block === void 0) return {};
@@ -2675,7 +2860,6 @@ const parseFrontmatter = (content) => {
 };
 //#endregion
 //#region src/skills/skills.constant.ts
-/** Human label for each phase, used when rendering the `{{SKILLS}}` block. */
 const PHASE_LABELS = {
 	"pre-implementation": "Pre-implementation",
 	"during-implementation": "During implementation",
@@ -2683,11 +2867,6 @@ const PHASE_LABELS = {
 };
 //#endregion
 //#region src/skills/skills.model.ts
-/**
-* Implementation-lifecycle slot a skill occupies in a sub-agent's `{{SKILLS}}`
-* marker. A skill with no phase is **universal** (e.g. `raise-discovery`) and is
-* listed under every sub-agent that invokes it, regardless of lifecycle position.
-*/
 const PHASES = [
 	"pre-implementation",
 	"during-implementation",
@@ -2695,14 +2874,6 @@ const PHASES = [
 ];
 //#endregion
 //#region src/skills/skills.ts
-/**
-* The registry of opt-in (`applies-when`-gated) capabilities, keyed by capability key.
-* The **capability** owns its metadata here (decision #136): the `predicate` over the
-* scan (the install-time gate, decision #31/#39), the `trigger` convention path the
-* client creates to satisfy it, and a short human `label` for what it unlocks. The
-* skills a key unlocks are NOT listed here — they're derived from the catalog (any skill
-* whose `applies-when` includes the key), so adding a skill never desyncs this table.
-*/
 const CAPABILITY_REGISTRY = {
 	"has-architecture-doc": {
 		predicate: (caps) => caps.hasArchitectureDoc,
@@ -2715,12 +2886,6 @@ const CAPABILITY_REGISTRY = {
 		label: "check test strength with mutation testing in review"
 	}
 };
-/**
-* Whether a single `applies-when` capability key holds for the scanned repo, failing
-* loud on an unknown key — a skill referencing a capability with no registry entry is a
-* catalog bug, not a silent under-gate. Shared by `appliesSatisfied` and
-* `latentCapabilities` so both agree on key validity.
-*/
 const capabilityHolds = (key, caps) => {
 	const entry = CAPABILITY_REGISTRY[key];
 	if (!entry) throw new Error(`unknown applies-when capability key "${key}"`);
@@ -2729,17 +2894,11 @@ const capabilityHolds = (key, caps) => {
 const asString = (value) => typeof value === "string" ? value : void 0;
 const asList = (value) => Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
 const isPhase = (value) => PHASES.includes(value);
-/**
-* Read an enum-valued frontmatter field, failing loud on a malformed value — a
-* mistyped enum (`phase: [post-implementation]`) must error, not silently default
-* and mis-place the skill.
-*/
 const readEnumField = (skillName, field, value, isValid) => {
 	if (value === void 0) return void 0;
 	if (typeof value !== "string" || !isValid(value)) throw new Error(`skill "${skillName}": invalid ${field} ${JSON.stringify(value)}`);
 	return value;
 };
-/** Build a `SkillMeta` from a skill's parsed frontmatter, validating enums. */
 const toSkillMeta = (name, frontmatter) => ({
 	name,
 	phase: readEnumField(name, "phase", frontmatter.phase, isPhase),
@@ -2747,11 +2906,6 @@ const toSkillMeta = (name, frontmatter) => ({
 	appliesWhen: asList(frontmatter["applies-when"]),
 	triggerCondition: asString(frontmatter["trigger-condition"])
 });
-/**
-* Read every skill in the vendor catalog (`<catalogRoot>/skills/<name>/SKILL.md`)
-* into gating metadata, sorted by name for deterministic output. Non-directory
-* entries (the catalog `README.md`) are skipped.
-*/
 const readCatalogSkills = async (catalogRoot) => {
 	const skillsRoot = join(catalogRoot, "skills");
 	const entries = await readdir(skillsRoot, { withFileTypes: true });
@@ -2760,7 +2914,6 @@ const readCatalogSkills = async (catalogRoot) => {
 		return toSkillMeta(entry.name, parseFrontmatter(content));
 	}))).toSorted((a, b) => a.name.localeCompare(b.name));
 };
-/** Whether every `applies-when` key of a skill holds for the scanned repo. */
 const appliesSatisfied = (skill, caps) => skill.appliesWhen.every((key) => {
 	try {
 		return capabilityHolds(key, caps);
@@ -2768,25 +2921,7 @@ const appliesSatisfied = (skill, caps) => skill.appliesWhen.every((key) => {
 		throw new Error(`skill "${skill.name}": ${error.message}`, { cause: error });
 	}
 });
-/**
-* The skills that install for a repo: every `appliesWhen` capability key must hold
-* (#31 — install-time, deterministic). A skill with no `appliesWhen` is always
-* installed (the profile tier #39 is retired — ADR 0015). `triggerCondition` is
-* per-change and stays a runtime concern, not evaluated here.
-*/
 const selectSkills = (skills, capabilities) => skills.filter((skill) => appliesSatisfied(skill, capabilities));
-/**
-* The opt-in capabilities that are **available but not active** for this repo
-* (decision #136): a registry key whose predicate is currently false AND that is the sole
-* blocker for ≥1 otherwise-eligible skill (every *other* `applies-when` key already
-* satisfied). Those skills would land the moment the client creates the `trigger`
-* convention file — so reporting them makes the convention discoverable without the
-* harness creating the artifact (decision #8).
-*
-* Pure and shared by `install` and `doctor` so both surface the same set by construction.
-* A capability whose predicate already holds is omitted (it's active, not latent); one
-* that gates no skill is omitted too (creating the file would unlock nothing here).
-*/
 const latentCapabilities = (skills, capabilities) => Object.entries(CAPABILITY_REGISTRY).toSorted(([a], [b]) => a.localeCompare(b)).filter(([, entry]) => !entry.predicate(capabilities)).flatMap(([key, entry]) => {
 	const unlocked = skills.filter((skill) => skill.appliesWhen.includes(key) && skill.appliesWhen.every((other) => {
 		if (other === key) return true;
@@ -2805,12 +2940,6 @@ const latentCapabilities = (skills, capabilities) => Object.entries(CAPABILITY_R
 	}];
 });
 const renderSkillLine = (skill) => skill.triggerCondition ? `- \`${skill.name}\` — only when ${skill.triggerCondition}` : `- \`${skill.name}\``;
-/**
-* Render a sub-agent's `{{SKILLS}}` marker from the selected skills it invokes,
-* grouped by phase in lifecycle order with universal (phase-less) skills last.
-* Falls back to a sentinel line when the role has no skills so the
-* section never renders empty.
-*/
 const renderRoleSkills = (selected, role) => {
 	const roleSkills = selected.filter((skill) => skill.invokedBy.includes(role));
 	const groups = [];
@@ -2825,13 +2954,9 @@ const renderRoleSkills = (selected, role) => {
 };
 //#endregion
 //#region src/doctor/cli-bin.constant.ts
-/** The telemetry CLI's executable name — the bin the launcher resolves
-* (`node_modules/.bin/lemony` or a `lemony` on PATH). */
 const LEMONY_BIN = "lemony";
 //#endregion
 //#region src/doctor/resolve-cli.ts
-/** True when `path` exists and is executable — mirrors the launcher's `[ -x ]`
-* (both follow symlinks, so a pnpm `.bin` symlink resolves). */
 const isExecutable = async (path) => {
 	try {
 		await access(path, constants.X_OK);
@@ -2840,19 +2965,6 @@ const isExecutable = async (path) => {
 		return false;
 	}
 };
-/**
-* Whether a global `lemony` binary is resolvable on `PATH` — the doctor's
-* pure-Node mirror of the launcher's `command -v lemony` (the launcher's second
-* resolution step, `catalog/hooks/lib/lemony.sh`). For a plain binary on a normal
-* `PATH` a walk matches `command -v`, and it avoids spawning a shell — the doctor runs in
-* the same session env as the hook, so its `process.env.PATH` is the very `PATH` the
-* launcher would search. (Pathological entries diverge — a *directory* named
-* `lemony`, or a non-executable file — but only ever change the `warn` detail
-* wording, never the verdict, which turns solely on the project-local bin.)
-*
-* Pure and injectable: pass an explicit `pathEnv` / `isExe` so a spec can script the
-* outcome against a fixture dir without depending on a real global install.
-*/
 const isCliOnPath = async (pathEnv = process.env.PATH, isExe = isExecutable) => {
 	if (!pathEnv) return false;
 	for (const dir of pathEnv.split(delimiter)) {
@@ -2863,26 +2975,12 @@ const isCliOnPath = async (pathEnv = process.env.PATH, isExe = isExecutable) =>
 };
 //#endregion
 //#region src/doctor/doctor.ts
-/**
-* The vendor hook commands every harnessed repo must wire in `.claude/settings.json`
-* (decision B4.3 — checked at presence level, not a deep merge-settings diff). One
-* per Claude Code event the harness owns.
-*/
 const VENDOR_HOOK_COMMANDS = [
 	".claude/hooks/init.sh",
 	".claude/hooks/session-close.sh",
 	".claude/hooks/require-playbook.sh",
 	".claude/hooks/suggest-playbook.sh"
 ];
-/**
-* Read-only health check (decision B4.2/B4.3): eight diagnostics that **propose**
-* the exact remediation but never mutate. Now that `install` is fresh-only
-* (ADR 0005), label/hook drift points at `lemony repair` (a re-sync at the
-* pinned version, preserving client edits) and version drift at `lemony
-* update`. The config check reuses the Zod
-* validator; the label check reuses the shared pure `diffLabels`; nothing here
-* writes to disk or to GitHub.
-*/
 const runDoctor = async (deps) => {
 	const { repoRoot } = deps;
 	const checks = [];
@@ -2909,6 +3007,7 @@ const runDoctor = async (deps) => {
 	checks.push(checkVersionPin(deps, config));
 	checks.push(await checkCliResolution(deps));
 	checks.push(await checkCapabilities(deps, config));
+	checks.push(await checkDesignToolDrift(deps));
 	return {
 		checks,
 		ok: checks.every((check) => check.status !== "fail")
@@ -3066,18 +3165,6 @@ const checkVersionPin = (deps, config) => {
 		remediation: "If your CLI is newer than the pin, run `lemony update`; if it is older, upgrade your CLI and do NOT run `update` (it would downgrade the repo)."
 	};
 };
-/**
-* Telemetry CLI resolvable via the launcher (#123). The launcher
-* (`catalog/hooks/lib/lemony.sh`) resolves the CLI `node_modules/.bin` →
-* global on PATH → fail-fast (exit 127, no npx — #107/#113/#124). This check is a
-* read-only dry-run of that exact chain, so doctor and the launcher agree by
-* construction: a `node_modules/.bin/lemony` (the durable, package-manager-
-* agnostic setup — pnpm symlinks a direct dep's bin there too) is `ok`; everything
-* else is `warn` (telemetry is best-effort/fail-open, never a hard `fail`), with a
-* remediation tuned to why resolution is fragile. No network — the common path never
-* triggers an install. Resolution is `repoRoot`-relative (cwd, like every other doctor
-* check) — run from the harness repo root, not a subdirectory.
-*/
 const checkCliResolution = async (deps) => {
 	const name = "cli-resolution";
 	if (await isExecutable(join(deps.repoRoot, "node_modules", ".bin", "lemony"))) return {
@@ -3106,21 +3193,6 @@ const checkCliResolution = async (deps) => {
 		remediation: `Install \`${LEMONY_BIN}\` globally and keep it on PATH (this repo has no package.json to pin a devDependency).`
 	};
 };
-/**
-* Opt-in (`applies-when`-gated) capabilities available but not active (#136): each names
-* a convention file the repo could create to unlock a skill that didn't install. Status
-* `info` when ≥1 is latent (opt-in-by-design, never a fault — #8 blesses not keeping the
-* file), `ok` when every applicable capability is already active. Re-derives the set from
-* a fresh scan + the catalog, so it agrees with `install`'s report by construction. Skips
-* (`warn`) when config didn't validate (a broken install isn't worth advising on).
-*
-* Reading the catalog is the only doctor check that touches the vendor bundle, so it is
-* also the only one that a damaged/relocated install can make throw (ENOENT on
-* `<vendorRoot>/skills`, or a catalog skill with an unknown `applies-when` key). Guarded
-* so such a failure degrades to a single `warn` instead of crashing `runDoctor` and
-* taking the other seven diagnostics down with it — a health tool must survive a broken
-* install, which is exactly when it's run.
-*/
 const checkCapabilities = async (deps, config) => {
 	const name = "capabilities";
 	if (!config) return {
@@ -3150,20 +3222,63 @@ const checkCapabilities = async (deps, config) => {
 		name,
 		status: "info",
 		detail: `${latent.length} opt-in ${latent.length === 1 ? "capability" : "capabilities"} available — ${lines}.`,
-		remediation: "Run /add-capability in Claude Code to activate one — the Architect authors the artifact, then `repair` installs the skill (#8: opt-in, never imposed)."
+		remediation: "Run /add-capability in Claude Code to activate one — the Architect authors the artifact, then `repair` installs the skill (opt-in, never imposed)."
 	};
 };
+const checkDesignToolDrift = async (deps) => {
+	const name = "design-tool-drift";
+	const tokenPath = join(deps.repoRoot, DESIGN_TOKENS_FILE);
+	if (!await pathExists(tokenPath)) return {
+		name,
+		status: "info",
+		detail: `No ${DESIGN_TOKENS_FILE} — token sync not in use.`
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+	} catch (error) {
+		return {
+			name,
+			status: "warn",
+			detail: `Could not read ${DESIGN_TOKENS_FILE}: ${error.message}`,
+			remediation: "Run `lemony design-tokens validate` to find the problem."
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		name,
+		status: "warn",
+		detail: `${DESIGN_TOKENS_FILE} is not a JSON object.`,
+		remediation: "Run `lemony design-tokens validate` to find the problem."
+	};
+	const report = driftReport(parsed);
+	switch (report.state) {
+		case "n/a": return {
+			name,
+			status: "info",
+			detail: "No design tool declared — token sync not in use."
+		};
+		case "never-projected": return {
+			name,
+			status: "info",
+			detail: `Design tool "${report.provider}" declared; no projection baseline yet.`,
+			remediation: "Run /sync-design-tokens export in Claude Code to bootstrap the tool."
+		};
+		case "in-sync": return {
+			name,
+			status: "ok",
+			detail: `Tokens are in sync with the "${report.provider}" design tool.`
+		};
+		case "export-pending": return {
+			name,
+			status: "warn",
+			detail: `Tokens changed since the last projection to "${report.provider}" — an export is pending.`,
+			remediation: "Run /sync-design-tokens export in Claude Code to project the change to the tool."
+		};
+	}
+};
 //#endregion
 //#region src/status/status.ts
-/** The state label whose presence on an open issue marks a live discovery (#55c/e). */
 const PAUSED_LABEL = "harness:status:paused-for-clarification";
-/**
-* Build the on-demand orient summary (decision B4.1) — purely read-only. Reads
-* the config (version/slug), the per-dev `current-<user>.md` pointer
-* (active task, last session), git (branch + behind count, local refs only), and
-* — best-effort via `gh` — the count of open issues paused on a discovery. Every
-* source degrades gracefully to null so a partial environment still prints.
-*/
 const runStatus = async (deps) => {
 	const { repoRoot } = deps;
 	const config = await readHarnessConfig(repoRoot);
@@ -3177,10 +3292,21 @@ const runStatus = async (deps) => {
 		branch: branch ?? pointer.branch,
 		behind,
 		lastSession: pointer.lastSession,
-		openDiscoveries
+		openDiscoveries,
+		designToolDrift: await readDriftState(repoRoot)
 	};
 };
-/** Read `active_task` / `branch` / `last_close_ts` from the per-dev pointer frontmatter. */
+const readDriftState = async (repoRoot) => {
+	const tokenPath = join(repoRoot, DESIGN_TOKENS_FILE);
+	if (!await pathExists(tokenPath)) return null;
+	try {
+		const parsed = JSON.parse(await readFile(tokenPath, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		return driftReport(parsed).state;
+	} catch {
+		return null;
+	}
+};
 const readPointer = async (repoRoot, readGitUserEmail) => {
 	const empty = {
 		activeTask: null,
@@ -3209,13 +3335,11 @@ const readPointer = async (repoRoot, readGitUserEmail) => {
 		lastSession: normalize(front.last_close_ts)
 	};
 };
-/** YAML `null`, the literal string "null", and "" all read as "unset". */
 const normalize = (value) => {
 	if (value === null || value === void 0) return null;
 	const trimmed = String(value).trim();
 	return trimmed === "" || trimmed === "null" ? null : trimmed;
 };
-/** Count open issues paused on a discovery; null on any `gh` failure (best-effort). */
 const countOpenDiscoveries = async (provider, slug) => {
 	const result = await provider.listIssues(slug, {
 		state: "open",
@@ -3228,11 +3352,6 @@ const countOpenDiscoveries = async (provider, slug) => {
 		return null;
 	}
 };
-/**
-* The CLI's command surface, in the order they print. This is the single source
-* of truth for both the top-level command list and per-command help; the verbs
-* here must stay in lockstep with the `main` dispatcher in `cli.ts`.
-*/
 const COMMANDS = [
 	{
 		name: "install",
@@ -3279,6 +3398,11 @@ const COMMANDS = [
 		summary: "Reflect a raised/resolved discovery onto its issue (label flip + comment); used by the Orchestrator's resolve-discovery skill.",
 		usage: "lemony discovery <pause|resume> --task-id=<id> --tier=<T1..T6> --status=<spec-in-progress|in-progress|in-review> [--note=<text>]"
 	},
+	{
+		name: "design-tokens",
+		summary: "Validate the 3-tier design-token file (and gate UI source against hardcoded values), check WCAG contrast of token pairs, or sync tokens with a design tool (consume-if-exists; never created).",
+		usage: "lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>"
+	},
 	{
 		name: "spinoff",
 		summary: "Capture a non-blocking defect found mid-task as a pending stub (+ followup_captured event); used by the /spinoff command.",
@@ -3293,7 +3417,6 @@ const COMMANDS = [
 //#endregion
 //#region src/help/help.ts
 const pad = (text, width) => text + " ".repeat(Math.max(0, width - text.length));
-/** The top-level help: tagline, usage, the command table, and the footer hints. */
 const topLevelHelp = () => {
 	const width = Math.max(...COMMANDS.map((c) => c.name.length));
 	return [
@@ -3308,7 +3431,6 @@ const topLevelHelp = () => {
 		"`lemony version` (or `--version` / `-v`) prints the installed CLI version."
 	].join("\n");
 };
-/** Per-command help (usage + summary), or `undefined` for an unknown command. */
 const commandHelp = (name) => {
 	const command = COMMANDS.find((c) => c.name === name);
 	if (!command) return void 0;
@@ -3318,56 +3440,21 @@ const commandHelp = (name) => {
 		command.summary
 	].join("\n");
 };
-/**
-* The unknown-command message. Names the bad input and points at `--help` rather
-* than dumping the full command list, so discovery has one obvious entry point.
-*/
 const unknownCommand = (name) => `Unknown command "${name ?? ""}". Run \`lemony --help\` to see available commands.`;
 //#endregion
 //#region src/render/render.ts
 const PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/g;
-/**
-* Render a template by substituting every `{{ key }}` placeholder with the
-* matching value from `vars`. Surrounding whitespace and dotted keys
-* (`{{ task_storage.repo }}`) are tolerated. Throws when a placeholder has no
-* matching var so a typo fails loudly instead of shipping a literal `{{ }}`.
-*/
 const renderTemplate = (template, vars) => template.replace(PLACEHOLDER, (_match, key) => {
 	if (!Object.hasOwn(vars, key)) throw new Error(`renderTemplate: no value provided for "${key}"`);
 	return vars[key];
 });
 //#endregion
 //#region src/baseline/baseline.ts
-/**
-* The baseline tree root — committed by default (decision D2/ADR 0005), so it
-* travels with the repo and any teammate's `update` is a true 3-way merge. Lives
-* under `.claude/.harness/` beside the gitignored `snapshots/` (added in S2).
-*/
 const BASELINE_ROOT_REL = join(".claude", ".harness", "baseline");
-/**
-* Where a new baseline is built before it is promoted. A dot-prefixed sibling of
-* the version dirs so `findBaselineVersion` skips it: a half-written staging tree
-* (from a crashed write) is never mistaken for a merge base.
-*/
 const STAGING_DIR$1 = ".staging";
-/** True when a filesystem error is "the path does not exist". */
 const isENOENT$1 = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-/** The repo-relative root holding every version's baseline (only one at a time). */
 const baselineRootDir = (repoRoot) => join(repoRoot, BASELINE_ROOT_REL);
-/** The dir holding the pristine vendor tree for one version. */
 const baselineVersionDir = (repoRoot, version) => join(baselineRootDir(repoRoot), version);
-/**
-* Write the pristine vendor tree for `version`, mirroring each file's repo-relative
-* path one level deeper. Only the current version is retained (D7).
-*
-* The write is crash-safe: the new tree is built **fully** under a dot-prefixed
-* `.staging` dir (invisible to `findBaselineVersion`) and only then promoted into
-* place with a single `rename` — the commit point. So a crash mid-write never
-* leaves a half-written version dir to be read as a truncated merge base (which
-* would silently route every absent file to the destructive pick-one path). The
-* old version dir survives untouched until the new one is fully renamed in;
-* `pruneOtherVersions` then enforces single-version retention.
-*/
 const writeBaseline = async (repoRoot, version, files) => {
 	const root = baselineRootDir(repoRoot);
 	const staging = join(root, STAGING_DIR$1);
@@ -3389,7 +3476,6 @@ const writeBaseline = async (repoRoot, version, files) => {
 	await rename(staging, versionDir);
 	await pruneOtherVersions(root, version);
 };
-/** Remove every version dir under `root` except `keep` (single-version retention). */
 const pruneOtherVersions = async (root, keep) => {
 	const entries = await readdir(root, { withFileTypes: true });
 	await Promise.all(entries.filter((entry) => entry.isDirectory() && entry.name !== keep).map((entry) => rm(join(root, entry.name), {
@@ -3397,11 +3483,6 @@ const pruneOtherVersions = async (root, keep) => {
 		force: true
 	})));
 };
-/**
-* Read a version's baseline back as a `relPath → content` map (the merge base for
-* `update`). An absent version dir yields an empty map — the caller treats that as
-* "no baseline" and degrades to the pick-one path (D2), never an error.
-*/
 const readBaseline = async (repoRoot, version) => {
 	const versionDir = baselineVersionDir(repoRoot, version);
 	let relPaths;
@@ -3414,25 +3495,6 @@ const readBaseline = async (repoRoot, version) => {
 	const entries = await Promise.all(relPaths.map(async (relPath) => [relPath, await readFile(join(versionDir, relPath), "utf8")]));
 	return new Map(entries);
 };
-/**
-* The version whose baseline is installed, or null when none is present. Used by
-* `update` to find the merge base and to detect absence (graceful degrade, D2).
-*
-* Single-version retention (D7) normally means exactly one version dir, and the
-* common path returns it directly. Dot-prefixed dirs (`.staging` from an in-flight
-* or crashed write, a stray `.DS_Store`) are skipped so a half-written tree is
-* never read as the merge base.
-*
-* A second version dir only appears in the crash window between promoting a new
-* baseline (`rename`) and pruning the old — and the merge base we want there is the
-* just-promoted tree (the client's files were already merged against it). We can't
-* derive "just-promoted" from the version NAME — a prerelease→release bump
-* (`0.1.0-alpha.0`→`0.1.0`) or a downgrade/repair would mis-order it — so we pick
-* the most-recently-written dir by mtime (the promoted dir carries the staging
-* tree's fresh mtime), with numeric version as a stable tiebreak. A genuinely-absent
-* root degrades to null; an unreadable one propagates (it must not look like "no
-* baseline").
-*/
 const findBaselineVersion = async (repoRoot) => {
 	const root = baselineRootDir(repoRoot);
 	let entries;
@@ -3453,31 +3515,13 @@ const findBaselineVersion = async (repoRoot) => {
 };
 //#endregion
 //#region src/snapshot/snapshot.ts
-/**
-* The snapshots root — gitignored (decision #48), unlike the committed baseline.
-* Holds one `<from-version>/` bundle per `update`, rotated by `keep_snapshots`.
-* Lives under `.claude/.harness/` beside the committed `baseline/`.
-*/
 const SNAPSHOTS_ROOT_REL = join(".claude", ".harness", "snapshots");
-/** Where a bundle is built before promotion — a dot-dir `listSnapshots` skips. */
 const STAGING_DIR = ".staging";
-/** The two file-tree halves of a bundle (ADR 0005 D7). */
 const WORKING_SUBDIR = "working";
 const BASELINE_SUBDIR = "baseline";
-/** True when a filesystem error is "the path does not exist". */
 const isENOENT = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-/** The repo-relative root holding every retained snapshot bundle. */
 const snapshotsRootDir = (repoRoot) => join(repoRoot, SNAPSHOTS_ROOT_REL);
-/** The dir holding one version's two-part snapshot bundle. */
 const snapshotDir = (repoRoot, version) => join(snapshotsRootDir(repoRoot), version);
-/**
-* Read the on-disk files at `relPaths` into a `VendorFile[]`, capturing each one's
-* content and exec mode — the shape a snapshot's `working` half needs. Paths absent on
-* disk are skipped, so the result mirrors the actual current state, nothing more. Shared
-* by every writer that captures a pre-change tree: `reconcile` snapshots the whole
-* baseline registry before an update; `install` snapshots only the client files a
-* vendor-win collision is about to displace (decision D8).
-*/
 const collectWorkingFiles = async (repoRoot, relPaths) => {
 	return (await Promise.all(relPaths.map(async (relPath) => {
 		const filePath = join(repoRoot, relPath);
@@ -3490,15 +3534,9 @@ const collectWorkingFiles = async (repoRoot, relPaths) => {
 		};
 	}))).filter((file) => file !== null);
 };
-/**
-* Write a `VendorFile[]` tree under `destRoot`, preserving each file's exec mode via
-* the shared `writeManaged`. The persisted exec bit is what lets an offline `rollback`
-* restore a runnable hook with no `vendorNew` to re-derive the mode from.
-*/
 const writeWorkingTree = async (destRoot, files) => {
 	await Promise.all(files.map(({ relPath, content, executable }) => writeManaged(destRoot, relPath, content, executable)));
 };
-/** Write a baseline map under `destRoot` (content only — a merge base is never run). */
 const writeBaselineTree = async (destRoot, baseline) => {
 	await Promise.all([...baseline].map(async ([relPath, content]) => {
 		const dest = join(destRoot, relPath);
@@ -3506,15 +3544,6 @@ const writeBaselineTree = async (destRoot, baseline) => {
 		await writeFile(dest, content);
 	}));
 };
-/**
-* Every repo-relative path `writeSnapshot` writes to (or renames into), for the
-* symlink pre-flight (#53). Covers both staging halves and the promote target dir —
-* so the guard `lstat`s every shared ancestor (`.claude/.harness/snapshots[/.staging]`)
-* plus each leaf. The two staging subdir roots and the version dir are included
-* **unconditionally** so the `mkdir` targets and all ancestors are guarded even for an
-* empty bundle — a half with no files would otherwise never pull its `working`/
-* `baseline` subdir into the checked set.
-*/
 const snapshotDestPaths = (version, bundle) => {
 	const stagingRel = join(SNAPSHOTS_ROOT_REL, STAGING_DIR);
 	return [
@@ -3525,20 +3554,6 @@ const snapshotDestPaths = (version, bundle) => {
 		join(SNAPSHOTS_ROOT_REL, version)
 	];
 };
-/**
-* Write the pre-update snapshot bundle for `version` (ADR 0005 D7). Crash-safe like
-* `writeBaseline`: both halves are built **fully** under a dot-prefixed `.staging`
-* dir (invisible to `listSnapshots`) and only then promoted with a single `rename`.
-*
-* Snapshots are keyed by the **from-version** they contain — exactly ONE bundle per
-* version, not a full history. Distinct from-versions coexist (unlike the single-
-* retention baseline) until `rotateSnapshots` prunes by age; but re-departing from the
-* same version (a retried update, or an update after a rollback back to it) REPLACES
-* that version's bundle. So a snapshot always holds the state immediately before the
-* LAST departure from its version — which is precisely what `rollback`'s "undo the
-* last update" contract restores. The committed vendor tree (git) remains the durable
-* record of any earlier state.
-*/
 const writeSnapshot = async (repoRoot, version, bundle) => {
 	const staging = join(snapshotsRootDir(repoRoot), STAGING_DIR);
 	await assertNoSymlinkTraversal(repoRoot, snapshotDestPaths(version, bundle));
@@ -3557,13 +3572,6 @@ const writeSnapshot = async (repoRoot, version, bundle) => {
 	});
 	await rename(staging, dir);
 };
-/**
-* Every retained snapshot version, **newest-first by mtime** (so `rollback` with no
-* `--to` targets the most recent, and `rotateSnapshots` keeps the freshest N).
-* mtime — not version name — orders them, so a downgrade snapshot sorts by when it
-* was taken, not by its (lower) version. Dot-dirs (`.staging`) are skipped; an
-* absent root is an empty list.
-*/
 const listSnapshots = async (repoRoot) => {
 	const root = snapshotsRootDir(repoRoot);
 	let entries;
@@ -3581,11 +3589,6 @@ const listSnapshots = async (repoRoot) => {
 	withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs || b.version.localeCompare(a.version, void 0, { numeric: true }));
 	return withMtime.map((entry) => entry.version);
 };
-/**
-* Read a version's snapshot bundle back, or null when no bundle exists for it. The
-* working half's exec bits are recovered from the on-disk file mode (round-tripping
-* what `writeWorkingTree` chmod'd); the baseline half is content only.
-*/
 const readSnapshot = async (repoRoot, version) => {
 	const dir = snapshotDir(repoRoot, version);
 	if (!await pathExists(dir)) return null;
@@ -3608,11 +3611,6 @@ const readSnapshot = async (repoRoot, version) => {
 		baseline: new Map(baselineEntries)
 	};
 };
-/**
-* Enforce `keep_snapshots` retention: keep the `keep` newest bundles, remove the
-* rest, and return the removed versions (oldest-first by exclusion). `'unlimited'`
-* never rotates. A count at or above the current total removes nothing.
-*/
 const rotateSnapshots = async (repoRoot, keep) => {
 	if (keep === "unlimited") return [];
 	const toRemove = (await listSnapshots(repoRoot)).slice(keep);
@@ -3623,10 +3621,6 @@ const rotateSnapshots = async (repoRoot, keep) => {
 	})));
 	return toRemove;
 };
-/**
-* Remove every snapshot bundle (the `rollback --cleanup` path) and return the
-* versions that were cleared. Drops the whole snapshots root; a no-op when absent.
-*/
 const cleanupSnapshots = async (repoRoot) => {
 	const versions = await listSnapshots(repoRoot);
 	await assertNoSymlinkTraversal(repoRoot, [SNAPSHOTS_ROOT_REL]);
@@ -3638,49 +3632,15 @@ const cleanupSnapshots = async (repoRoot) => {
 };
 //#endregion
 //#region src/merge/conflict-markers.constant.ts
-/**
-* Git-style conflict markers (decision #49). `update`'s 3-way merge writes these
-* around an overlapping hunk it can't auto-resolve; the client edits the file to
-* pick a side and deletes the markers. The labels (`client`/`vendor`) name the two
-* sides so the resolver knows which is theirs and which is the new vendor catalog.
-*/
 const CONFLICT_MARKER_CLIENT = "<<<<<<< client";
 const CONFLICT_MARKER_SEPARATOR = "=======";
 const CONFLICT_MARKER_VENDOR = ">>>>>>> vendor";
 //#endregion
 //#region src/merge/conflict-markers.ts
-/**
-* A line that is exactly one of the two labeled fences a conflict block opens and
-* closes with. Detection keys on the full labeled fence — NOT a bare `=======`
-* (a Markdown setext underline shares it) and NOT a generic `>>>>>>>` prefix (a
-* seven-deep blockquote line `>>>>>>> note` shares that). Requiring the exact
-* `client`/`vendor` label makes a match unambiguously a harness-authored marker,
-* and either fence alone catches a half-resolved block (a deleted partner line).
-*/
 const CONFLICT_FENCE = new RegExp(`^(?:${CONFLICT_MARKER_CLIENT}|${CONFLICT_MARKER_VENDOR})$`, "m");
-/**
-* True when `content` carries a residual conflict fence — a marker a prior merge
-* wrote that the client never resolved. `update` pre-scans every managed file with
-* this and refuses to run while any remain (decision #49), so a second update can't
-* bury an unresolved hunk inside a fresh one.
-*/
 const hasConflictMarkers = (content) => CONFLICT_FENCE.test(content);
 //#endregion
 //#region src/merge/three-way-merge.ts
-/**
-* A line-based 3-way merge — the core of `update` (ADR 0005). Given the pristine
-* vendor `base` (the baseline tree), the client's current file, and the new vendor
-* file, it replays the client and vendor edits against the common base:
-*
-* - a region only one side touched is taken from that side (disjoint edits both land);
-* - a region both sides changed **identically** is taken once;
-* - a region both sides changed **differently** is wrapped in git-style markers and
-*   the result is flagged `conflicted` (decision #49 — never blocks, always reports).
-*
-* The algorithm is the classic diff3 over LCS anchors (Khanna–Kunal–Pierce): diff
-* `base→client` and `base→vendor` into changed regions, sort and coalesce overlapping
-* regions, then emit stable runs verbatim and decide each changed region as above.
-*/
 const threeWayMerge = (base, client, vendor) => {
 	const regions = diff3Regions(base.split("\n"), client.split("\n"), vendor.split("\n"));
 	const out = [];
@@ -3756,12 +3716,6 @@ const diff3Regions = (base, client, vendor) => {
 	emitStable(base.length);
 	return regions;
 };
-/**
-* The slice of `sideLines` that the region `[regionBaseStart, regionBaseEnd)` maps to
-* on one side. A side may have several hunks in the group (or none). Lines the side
-* left untouched map 1:1 to the base, so the span is widened from the side's own
-* hunks by the base-range delta before/after them — exactly node-diff3's bounds math.
-*/
 const projectSide = (group, side, sideLines, regionBaseStart, regionBaseEnd) => {
 	const own = group.filter((h) => h.side === side);
 	let sideStart = Number.POSITIVE_INFINITY;
@@ -3778,11 +3732,6 @@ const projectSide = (group, side, sideLines, regionBaseStart, regionBaseEnd) =>
 	const end = sideEnd + (regionBaseEnd - baseEnd);
 	return sideLines.slice(start, end);
 };
-/**
-* The maximal runs where `other` diverges from `base`, derived from the LCS of the
-* two line sequences. Each match anchors a stable point; the gaps between successive
-* anchors (and the head/tail before the first / after the last) are the diffs.
-*/
 const diffRegions = (base, other) => {
 	const matches = lcsMatches(base, other);
 	const diffs = [];
@@ -3806,12 +3755,6 @@ const diffRegions = (base, other) => {
 	});
 	return diffs;
 };
-/**
-* Longest common subsequence of two line arrays, returned as ascending
-* `[baseIndex, otherIndex]` anchor pairs. Classic O(n·m) DP over a flat Int32Array
-* (typed-array reads are never `undefined`, so the table needs no bounds dance),
-* then a forward walk reconstructs the matched pairs.
-*/
 const lcsMatches = (base, other) => {
 	const n = base.length;
 	const m = other.length;
@@ -3832,45 +3775,13 @@ const lcsMatches = (base, other) => {
 };
 //#endregion
 //#region src/update/engine.ts
-/** The managed skills root — the only multi-file unit the cohesion grouping spans. */
 const SKILLS_PREFIX = join(".claude", "skills");
-/**
-* Cohesion key for orphan prune/adopt grouping (F8). A multi-file skill must be
-* adopted or pruned **as a whole** — never split into a half-skill on disk. So every
-* file under `.claude/skills/<name>/` groups by that skill dir; a client edit to ANY
-* file in it keeps the WHOLE skill (its untouched siblings are kept too, not pruned).
-* Every other path (single-file commands/hooks/agents, the schema, agents.md) is its
-* own singleton group, so non-skill orphans keep the simple per-file behavior.
-*/
 const cohesionKey = (relPath) => {
 	const prefix = SKILLS_PREFIX + sep;
 	if (!relPath.startsWith(prefix)) return relPath;
 	const name = relPath.slice(prefix.length).split(sep)[0];
 	return name ? join(SKILLS_PREFIX, name) : relPath;
 };
-/**
-* The diff engine (ADR 0005, D6). Walks the union of `baseline ∪ vendor-new` paths
-* and decides each one — uniformly across skills, commands, hooks, and agents,
-* because the engine's universe is exactly the materialized vendor tree (the
-* special-cased `settings.json` / `.gitignore` / `harness.config.yml` are NOT in
-* the baseline, so they never reach here — `runReconcile` handles them separately).
-*
-* Per path, keyed on baseline/catalog presence:
-*
-* - **in both** → 3-way merge against the client's on-disk file (markers on overlap,
-*   #49); a deleted client file is restored from the catalog.
-* - **only in the catalog** → a new vendor file: add it, or — when a client file
-*   already sits there with no baseline to merge against — resolve the collision
-*   whole-file by `onConflict` (D5, default vendor).
-* - **only in the baseline** → an orphan removed from the catalog. The prune-or-adopt
-*   choice is made **per cohesion group** (F8): `prune` if the client never touched
-*   any file in the group, else `adopt` the whole group (keep on disk, drop from the
-*   baseline). An already-deleted orphan is a no-op.
-*
-* Pure planner: it reads the client tree through the injected `readClient` but
-* writes nothing — `runReconcile` applies the returned actions. Actions come back in
-* sorted-path order so the report buckets read deterministically.
-*/
 const runEngine = async (inputs) => {
 	const { baseline, readClient, onConflict } = inputs;
 	const vendorNew = new Map(inputs.vendorNew.map((file) => [file.relPath, file]));
@@ -3901,7 +3812,6 @@ const runEngine = async (inputs) => {
 		return action;
 	});
 };
-/** Decide a path the new catalog still ships (`vendor` defined). */
 const decideManaged = async (relPath, base, vendor, client, onConflict) => {
 	const { content, executable } = vendor;
 	if (base === void 0) {
@@ -3944,7 +3854,6 @@ const decideManaged = async (relPath, base, vendor, client, onConflict) => {
 		conflicted: merge.conflicted
 	};
 };
-/** The action for one orphan, given its group's adopt-vs-prune decision. */
 const orphanAction = (relPath, client, adopts) => {
 	if (client === null) return {
 		relPath,
@@ -3958,7 +3867,6 @@ const orphanAction = (relPath, client, adopts) => {
 		kind: "prune"
 	};
 };
-/** Group items by a key, preserving insertion order within each group. */
 const groupBy = (items, key) => {
 	const groups = /* @__PURE__ */ new Map();
 	for (const item of items) {
@@ -3971,35 +3879,10 @@ const groupBy = (items, key) => {
 };
 //#endregion
 //#region src/install/asset-frontmatter.ts
-/** Leading `---\n … \n---` block, with the fences captured so we can rebuild it. */
 const FRONTMATTER_BLOCK = /^(---\n)([\s\S]*?)(\n---)/;
-/** `{{ vendor_version }}` placeholder (whitespace-tolerant, like `renderTemplate`). */
 const VENDOR_VERSION = /\{\{\s*vendor_version\s*\}\}/g;
-/** The first `description:` line within a frontmatter block. */
 const DESCRIPTION_LINE = /^(description:[ \t]*)(.*)$/m;
-/** A YAML block-scalar header — just `|` or `>`, an optional chomping (`+`/`-`)
-* and/or indent digit, and nothing else on the line. Its value lives on the
-* following lines, so the prefix can't be inlined. Matched precisely so a prose
-* description that merely starts with `>` (e.g. `> 50% faster`) is still
-* prefixed, not mistaken for a block scalar. The catalog uses single-line
-* descriptions; this guard keeps a future multi-line one from being mangled. */
 const BLOCK_SCALAR = /^[|>][+-]?\d*$/;
-/**
-* Materialize-time transform for the frontmatter of installed agents, skills and
-* commands. Two jobs, both scoped to the **leading frontmatter block** so a `{{`
-* in a skill body (an example, a code fence) is never touched and never throws:
-*
-*   1. substitute `{{vendor_version}}` with the real catalog version (#116) — the
-*      per-asset version is a placeholder filled at install, not a frozen literal
-*      that drifts behind `catalog/VERSION`;
-*   2. prepend {@link VENDOR_DESCRIPTION_PREFIX} to the `description:` value (#117).
-*
-* Files without a frontmatter block (a bundled skill resource like `reference.md`,
-* the `fit-assessment` doc) pass through unchanged. The description prefix is
-* idempotent — a value already carrying the prefix is left as-is — so a re-render
-* (repair/update materializes the same tree) never double-prefixes. An empty or
-* block-scalar (`|` / `>`) description value is left untouched rather than mangled.
-*/
 const materializeAssetFrontmatter = (content, opts) => {
 	const prefix = opts.descriptionPrefix ?? "🍋";
 	const match = FRONTMATTER_BLOCK.exec(content);
@@ -4013,21 +3896,14 @@ const materializeAssetFrontmatter = (content, opts) => {
 };
 //#endregion
 //#region src/install/materialize.ts
-/**
-* The core agent instances installed in every build (decisions #10/#29). Each
-* sub-agent carries a `{{SKILLS}}` marker the installer fills from the resolved
-* skill set; the Orchestrator (a hat) weaves its skills into prose and has no
-* marker, so its render is a pass-through. The Architect is always installed but
-* invoked on-demand (decision #44).
-*/
 const CORE_AGENTS = [
 	"orchestrator",
 	"spec-author",
 	"implementer",
 	"reviewer",
-	"architect"
+	"architect",
+	"ui-designer"
 ];
-/** Read a template and render its `{{vars}}` to a `VendorFile` at `relPath`. */
 const renderFile = async (templatePath, relPath, vars) => {
 	return {
 		relPath,
@@ -4035,34 +3911,15 @@ const renderFile = async (templatePath, relPath, vars) => {
 		executable: false
 	};
 };
-/** Read a vendor file verbatim into a `VendorFile` at `relPath`. */
 const copyFileEntry = async (srcPath, relPath, executable = false) => ({
 	relPath,
 	content: await readFile(srcPath, "utf8"),
 	executable
 });
-/**
-* Apply the asset-frontmatter transform to a materialized file: fill the
-* `{{vendor_version}}` placeholder and 🍋-prefix the `description` (#116/#117).
-* A no-op for files without a frontmatter block.
-*/
 const withAssetFrontmatter = (file, vendorVersion) => ({
 	...file,
 	content: materializeAssetFrontmatter(file.content, { vendorVersion })
 });
-/**
-* The full set of baseline-eligible vendor files for an install context, in memory
-* (decision D6/ADR 0005). This is the **single definition** of "the managed vendor
-* tree": `install` writes this list to disk and mirrors it into the baseline, and
-* `update` re-runs it against the new catalog to get `vendor-new`. The list is
-* exactly the **plain-merge** and **membership** categories of the diff engine —
-* the files whose presence in the baseline marks them vendor-owned.
-*
-* It deliberately excludes the special-cased artifacts that are NOT pure vendor
-* content: `.claude/settings.json` (hooks-block merge), the `.gitignore` managed
-* block, `harness.config.yml` (client-owned), and the forward-only state scaffold.
-* Those are handled directly by the installer and the update engine's handlers.
-*/
 const materializeVendorFiles = async (ctx) => {
 	const { vendorRoot, target, vars, skills } = ctx;
 	const templateRoot = join(vendorRoot, "templates", target);
@@ -4100,16 +3957,6 @@ const materializeVendorFiles = async (ctx) => {
 };
 //#endregion
 //#region src/install/gitignore.ts
-/**
-* The managed `.gitignore` block — vendor authority is restricted to the lines
-* between these markers (the per-dev state + local rollback snapshots that must
-* never be committed). Shared by `install` and `update`/`repair`: all ensure the
-* block is present and current without disturbing the client's own ignore rules.
-*
-* Note `.claude/.harness/baseline/` is deliberately NOT here — the baseline tree is
-* committed (ADR 0005 D2) so `update` is reproducible by any teammate. Only the
-* `snapshots/` sibling is local/gitignored (#48).
-*/
 const GITIGNORE_BEGIN = "# BEGIN lemony";
 const GITIGNORE_END = "# END lemony";
 const GITIGNORE_BLOCK = [
@@ -4125,14 +3972,6 @@ const GITIGNORE_BLOCK = [
 	".claude/.harness/snapshots/",
 	GITIGNORE_END
 ].join("\n");
-/**
-* Ensure the managed block is present AND current in `.gitignore`. A fresh repo gets
-* the block appended; a repo that already carries it has the block **reconciled** to
-* the canonical content (so a newly-managed ignore — like `snapshots/` added in P7 —
-* lands on the next `update`/`repair` of an already-installed repo, not only on fresh
-* installs). Client lines outside the markers are untouched. Returns the path when it
-* wrote, or null when the block was already byte-identical (idempotent).
-*/
 const appendGitignoreBlock = async (repoRoot) => {
 	const gitignorePath = join(repoRoot, ".gitignore");
 	const current = await pathExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
@@ -4147,19 +3986,6 @@ const appendGitignoreBlock = async (repoRoot) => {
 	await writeFile(gitignorePath, `${current}${current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n"}${GITIGNORE_BLOCK}\n`);
 	return ".gitignore";
 };
-/**
-* Remove the managed `.gitignore` block (symmetric to `appendGitignoreBlock`).
-* Strips the lines from the BEGIN sentinel through the END sentinel (inclusive),
-* leaving every client line outside the block untouched. Returns the relative path
-* when the block was found and removed, else null (no block present / file absent).
-* If stripping the block empties the file, the now-blank `.gitignore` is removed.
-*
-* The trailer is normalized to a single final newline (the inverse of the blank-line
-* separator `appendGitignoreBlock` inserts). This is content-lossless — no client
-* ignore line is ever dropped — but it is not byte-for-byte: a client file that had
-* no final newline, or trailing blank lines, comes back with exactly one. That EOF
-* whitespace carries no `.gitignore` meaning, so the normalization is intentional.
-*/
 const removeGitignoreBlock = async (repoRoot) => {
 	const relPath = ".gitignore";
 	const gitignorePath = join(repoRoot, relPath);
@@ -4178,17 +4004,6 @@ const removeGitignoreBlock = async (repoRoot) => {
 };
 //#endregion
 //#region src/install/merge-settings.ts
-/**
-* Replace (or add) the `hooks` block in `destPath` with the one declared in
-* `templatePath`. Existing keys outside `hooks` are preserved verbatim;
-* `hooks` is replaced **in toto** so removing a stale entry in a vendor update
-* actually removes it.
-*
-* Creates the file (and parent dirs) when missing. Returns the set of custom
-* command paths the merge wiped so the CLI can print a breadcrumb pointing
-* users at `.claude/settings.local.json` (the supported escape hatch for
-* client-side hook customization).
-*/
 const mergeSettingsHooks = async (templatePath, destPath) => {
 	const templateRaw = await readFile(templatePath, "utf8");
 	const template = JSON.parse(templateRaw);
@@ -4211,15 +4026,6 @@ const mergeSettingsHooks = async (templatePath, destPath) => {
 	await writeFile(destPath, `${JSON.stringify(merged, null, 2)}\n`);
 	return { lostCommands };
 };
-/**
-* Remove the vendor `hooks` block from `.claude/settings.json` (symmetric to
-* `mergeSettingsHooks`). Deletes only the `hooks` key — every client-owned key is
-* preserved. If `hooks` was the file's only key, the now-empty settings.json is
-* removed (install effectively owned the whole file). Returns what happened:
-* `'absent'` (no file, empty file, or no `hooks` key), `'stripped'` (hooks removed,
-* file kept with the client's keys), `'removed-file'` (hooks removed, empty file
-* deleted).
-*/
 const removeSettingsHooks = async (settingsPath) => {
 	if (!await pathExists(settingsPath)) return "absent";
 	const raw = await readFile(settingsPath, "utf8");
@@ -4239,13 +4045,6 @@ const removeSettingsHooks = async (settingsPath) => {
 	await writeFile(settingsPath, `${JSON.stringify(rest, null, 2)}\n`);
 	return "stripped";
 };
-/**
-* Walk a hooks block and collect every `command` string under any event type.
-* The Claude Code hooks shape is `{ <EventType>: [{ matcher?, hooks: [{ type:
-* 'command', command: string }] }] }`. Anything that doesn't fit (the user
-* had it the "wrong" way) is skipped silently — we're computing a set diff,
-* not validating shape.
-*/
 const collectCommands = (hooks) => {
 	const result = /* @__PURE__ */ new Set();
 	if (!hooks || typeof hooks !== "object") return result;
@@ -4262,11 +4061,6 @@ const collectCommands = (hooks) => {
 	}
 	return result;
 };
-/**
-* Set diff between the commands found in `existingHooks` and those in
-* `templateHooks`. The result is sorted so the breadcrumb output is stable
-* across runs (otherwise iteration order would vary by JSON parse).
-*/
 const diffLostCommands = (existingHooks, templateHooks) => {
 	const existing = collectCommands(existingHooks);
 	const template = collectCommands(templateHooks);
@@ -4276,18 +4070,6 @@ const diffLostCommands = (existingHooks, templateHooks) => {
 };
 //#endregion
 //#region src/install/resync.ts
-/**
-* Re-sync the two **special-cased** artifacts that sit OUTSIDE the 3-way baseline:
-* the `.claude/settings.json` hooks block (vendor authority is the `hooks` key only)
-* and the managed `.gitignore` block. Both preserve every client-owned line around
-* them. Shared verbatim by `install` (fresh) and `reconcile` (update/repair)
-* — the one sequence that was duplicated between them (issue #81/A3): same template
-* paths, same order, same `lostCommands` surfacing. install also reports the
-* `.gitignore` path it wrote (for `filesWritten`); reconcile ignores it.
-*
-* `templateRoot` is `<vendorRoot>/templates/<target>` — the caller resolves it (it
-* already holds `target` from the config or the install options).
-*/
 const resyncSpecialCased = async (repoRoot, templateRoot) => {
 	const { lostCommands } = await mergeSettingsHooks(join(templateRoot, ".claude", "settings.json.tpl"), join(repoRoot, ".claude", "settings.json"));
 	return {
@@ -4298,35 +4080,19 @@ const resyncSpecialCased = async (repoRoot, templateRoot) => {
 //#endregion
 //#region src/install/install.ts
 const CLAUDE_MD_FILENAME = "CLAUDE.md";
-/** Non-interactive default: vendor wins every collision (the non-TTY contract, D8). */
 const VENDOR_WINS = async () => "vendor";
 const OPERATIVE_TARGET = "claude-code";
-/** Shared, committed state subdirs — scaffolded empty, kept in git via `.gitkeep`. */
 const COMMITTED_STATE_DIRS = ["tasks", "metrics"];
-/** Write a `VendorFile` to disk via the shared managed-write (parent dirs + exec mode). */
 const writeVendorFile = async (repoRoot, file) => {
 	await writeManaged(repoRoot, file.relPath, file.content, file.executable);
 	return file.relPath;
 };
-/** Write `content` to a repo-relative path, creating parent dirs. Returns the path. */
 const writeOut = async (repoRoot, relPath, content) => {
 	const dest = join(repoRoot, relPath);
 	await mkdir(dirname(dest), { recursive: true });
 	await writeFile(dest, content);
 	return relPath;
 };
-/**
-* Install the harness into a client repo — **fresh-only** (ADR 0005, decision D3).
-*
-* Refuses if `harness.config.yml` already exists ("already installed; use
-* `update`"), undoing P6's idempotent-reinstall stopgap now that `update`/`repair`
-* own re-sync and config migration. A fresh install: scans capabilities, renders
-* the entry protocol + agents + skills, writes the **baseline tree** (a verbatim
-* copy of every materialized vendor file at `.claude/.harness/baseline/<version>/`,
-* the merge base for the next `update`), scaffolds `.claude/state/`, appends the
-* managed `.gitignore` block, merges the `settings.json` hooks block, writes
-* `harness.config.yml`, and reconciles the `harness:*` labels.
-*/
 const runInstall = async (options) => {
 	const { repoRoot, vendorRoot } = options;
 	if (await pathExists(join(repoRoot, "harness.config.yml"))) throw new Error(`Lemony is already installed here (${HARNESS_CONFIG_FILENAME} exists). Run \`lemony update\` to change the pinned version.`);
@@ -4437,25 +4203,12 @@ const runInstall = async (options) => {
 		latentCapabilities: latent
 	};
 };
-/**
-* The client files about to be overwritten by a `pick-vendor` collision, captured as a
-* `VendorFile[]` for the rollback snapshot. Called BEFORE any vendor write — the files
-* still hold the client's hand-made copy here. The on-disk read is the shared
-* `collectWorkingFiles` (reconcile snapshots its whole baseline the same way); install
-* just narrows the path set to the losing collisions.
-*/
 const collectLosers = (repoRoot, actions) => {
 	return collectWorkingFiles(repoRoot, actions.filter((action) => action.kind === "pick-vendor").map((action) => action.relPath));
 };
 //#endregion
 //#region src/install/resolve-collision.ts
 const toLines = (text) => text.replace(/\n$/, "").split("\n");
-/**
-* Render a whole-file pick as a unified-ish diff: the client's current copy as removed
-* (`-`) lines, the harness vendor copy as added (`+`) lines. There is no merge base at
-* install (decision D8), so a line-level 3-way diff is neither possible nor meaningful
-* — the choice is whole-file, and seeing both sides verbatim is what the user needs.
-*/
 const renderDiff = (relPath, vendorContent, clientContent) => {
 	return [
 		`--- ${relPath} (your current copy)`,
@@ -4464,14 +4217,6 @@ const renderDiff = (relPath, vendorContent, clientContent) => {
 		...toLines(vendorContent).map((line) => `+ ${line}`)
 	].join("\n");
 };
-/**
-* Build the interactive per-collision resolver the CLI injects into `runInstall` when
-* stdin is a TTY (decision D8). For each pre-existing file that collides with a vendor
-* file, it offers `[keep-vendor (recommended)] / [keep-client] / [diff]`, looping on a
-* `[diff]` request or an unrecognized answer. The empty answer accepts the recommended
-* default (vendor). Non-TTY installs never build this — `runInstall` falls back to its
-* vendor-wins default and reports the collisions instead.
-*/
 const createInteractiveCollisionResolver = (deps) => {
 	return async (relPath, vendorContent, clientContent) => {
 		deps.print("");
@@ -4491,33 +4236,6 @@ const createInteractiveCollisionResolver = (deps) => {
 };
 //#endregion
 //#region src/update/reconcile.ts
-/**
-* The shared baseline-aware reconcile core (ADR 0005, D6). `update` and `repair`
-* are the same operation — "materialize the managed vendor tree for `toVersion`,
-* 3-way merge it against the committed baseline, apply, re-sync the special-cased
-* artifacts, refresh the baseline, bump the config" — differing only in WHAT version
-* they materialize and WHICH config value they bump. Those differences are the
-* `ReconcileInputs`; everything else lives here once.
-*
-* The spine:
-*
-* 1. Read the client config (target/slug/snapshot-retention/from-version) and the
-*    on-disk baseline (the merge base; absent → pick-one degrade, D2).
-* 2. Materialize the catalog's managed tree for `toVersion` (`vendor-new`).
-* 3. **Refuse** if any managed file still carries a residual conflict marker (#49),
-*    and refuse if a managed path is reachable only through a symlink (P7/S2).
-* 4. Run the pure diff engine, then — unless `dryRun` — apply its actions: write
-*    merges/adds/restores, delete prunes, leave adoptions and client picks in place.
-* 5. Re-sync the special-cased artifacts (the `settings.json` hooks block, the
-*    `.gitignore` block) and the `harness:*` labels.
-* 6. Refresh the baseline to `toVersion` (adopted orphans fall out) and apply the
-*    config value-bumps last (the commit point — a crash leaves the old state and a
-*    safe, idempotent retry).
-*
-* `dryRun` short-circuits after the engine with a faithful report and zero writes —
-* the guards in step 3 still run (they are read-only and the preview should reflect
-* a refusal a real run would hit).
-*/
 const runReconcile = async (inputs) => {
 	const { repoRoot, vendorRoot, toVersion, configBumps } = inputs;
 	const dryRun = inputs.dryRun ?? false;
@@ -4606,7 +4324,6 @@ const applyActions = async (repoRoot, actions) => {
 	}));
 	await pruneEmptyDirs(repoRoot, actions.filter((action) => action.kind === "prune").map((action) => action.relPath));
 };
-/** Bucket the engine actions into the report's path lists. */
 const summarize = (actions) => {
 	const conflictedFiles = [];
 	const mergedFiles = [];
@@ -4653,13 +4370,6 @@ const summarize = (actions) => {
 };
 //#endregion
 //#region src/update/update.ts
-/**
-* Update a harnessed repo to the catalog at `vendorRoot` (ADR 0005). A thin wrapper
-* over the shared `runReconcile` core: it resolves the **target version** (the new
-* catalog's `VERSION`) and the bump (`vendor_version`), and lets the core do the
-* materialize → 3-way merge → snapshot → apply → re-sync → refresh-baseline → bump
-* dance. `repair` reuses this wrapper at the same version.
-*/
 const runUpdate = async (options) => {
 	const { repoRoot, vendorRoot } = options;
 	const onConflict = options.onConflict ?? "vendor";
@@ -4683,16 +4393,6 @@ const runUpdate = async (options) => {
 };
 //#endregion
 //#region src/repair/repair.ts
-/**
-* Re-sync a harnessed repo at its **pinned** version (ADR 0005 D3). Repair is
-* `update` with `vendor-old == vendor-new`: the 3-way merge collapses to "restore
-* missing vendor files, leave client edits", and the special-cased artifacts
-* (settings hooks, gitignore block, `harness:*` labels) are re-synced — without
-* clobbering a present, client-edited file (the baseline 3-way detects the edit).
-*
-* It refuses when the catalog is a DIFFERENT version than the pin: that is a version
-* change, which is `update`'s job (a true 3-way + pin bump), not repair's.
-*/
 const runRepair = async (options) => {
 	const { repoRoot, vendorRoot } = options;
 	const config = await readHarnessConfig(repoRoot);
@@ -4707,35 +4407,9 @@ const runRepair = async (options) => {
 };
 //#endregion
 //#region src/uninstall/uninstall.ts
-/** The harness-private tree (baseline + snapshots) — removed wholesale. */
 const HARNESS_DIR = join(".claude", ".harness");
-/** Vendor authority over settings is the `hooks` block only (preserve client keys). */
 const SETTINGS_RELPATH = join(".claude", "settings.json");
-/** All of `docs/` is preserved (D7) — even the vendor `playbooks/README.md`. */
 const DOCS_PREFIX = `docs${sep}`;
-/**
-* `uninstall` — the inverse of install over **vendor-managed** files (ADR 0005 D7).
-*
-* The baseline tree IS the vendor-origin registry (D2): _presence in the baseline_
-* is what marks a file vendor-managed, uniformly across `.md`/`.sh`/`.json`. So
-* uninstall enumerates the baseline keys and removes them — except anything under
-* `docs/` (preserved: a harmless leftover beats touching client docs). Files the
-* client adopted-as-client already fell out of the baseline, so they survive.
-*
-* Beyond the registry it strips the three special-cased artifacts symmetric to
-* install (the `settings.json` hooks block — client keys preserved; the `.gitignore`
-* managed block) and removes the install marker `harness.config.yml` plus the whole
-* `.claude/.harness/` tree (baseline + snapshots).
-*
-* **Preserved**: `CLAUDE.md`, `CONTEXT.md`, all of `docs/`, `.claude/state/**`,
-* `events.jsonl`, adopted-as-client skills. **Labels** are left on the remote unless
-* `--labels` is given (they may be attached to live issues).
-*
-* **Refuses** when not installed (no `harness.config.yml`) and when there is no
-* baseline registry — without it uninstall cannot tell a vendor file from a client
-* one, and a half-removal (config gone, orphan vendor files left) is worse than a
-* clear refusal (HITL call, S3 PR-B). `repair` restores a missing baseline.
-*/
 const runUninstall = async (options) => {
 	const { repoRoot } = options;
 	if (!await pathExists(join(repoRoot, "harness.config.yml"))) throw new Error(`Lemony is not installed here (${HARNESS_CONFIG_FILENAME} not found).`);
@@ -4770,18 +4444,6 @@ const runUninstall = async (options) => {
 };
 //#endregion
 //#region src/rollback/rollback.ts
-/**
-* Roll a harnessed repo back to a pre-update snapshot (#48, ADR 0005 D7), offline.
-* The two-part bundle is restored together: the `working` tree goes back to disk
-* verbatim (with exec modes), and the pristine `baseline` half is re-established as
-* the active merge base — so the next `update` after a rollback is still a true
-* 3-way merge, not a silent pick-one degrade. The pin reverts to the target version.
-*
-* Files added by the update being undone (managed now, absent from the snapshot) are
-* removed so the tree truly reverts. A git-dirty guard refuses if uncommitted changes
-* to a touched managed file would be lost — anything committed is git-recoverable, so
-* only uncommitted work is at risk; `--force` overrides.
-*/
 const runRollback = async (options) => {
 	const { repoRoot, force } = options;
 	const snapshots = await listSnapshots(repoRoot);
@@ -4817,15 +4479,6 @@ const runRollback = async (options) => {
 		removedFiles: removePaths
 	};
 };
-/**
-* The subset of `touched` paths that `git status` reports as changed in the working
-* tree. Uses `--porcelain -z`: NUL-delimited records with **no path quoting** (so a
-* managed file with a space/special char isn't silently missed — the v1 default
-* quotes those, which would defeat the guard). Each record is `XY <path>`; a rename
-* or copy (`R`/`C`) emits the original path as its OWN bare NUL field right after, so
-* both ends are counted. A non-git repo or a git error degrades to "nothing dirty"
-* (best-effort safety, never a hard block on an un-versioned repo).
-*/
 const dirtyManagedPaths = async (repoRoot, run, touched) => {
 	const result = await run("git", [
 		"-C",
@@ -4854,30 +4507,12 @@ const dirtyManagedPaths = async (repoRoot, run, touched) => {
 //#endregion
 //#region src/install/resolve-slug.ts
 const SLUG_PATTERN = TASK_STORAGE_REPO_PATTERN;
-/**
-* Validate a slug at flag-parse time. Throws a friendly message on every
-* rejection reason so the CLI surfaces the cause directly instead of a stack
-* trace. The same regex feeds the interactive prompt; placeholder is rejected
-* separately so the error message can be specific.
-*/
 const validateSlugOrThrow = (slug) => {
 	const trimmed = slug.trim();
 	if (trimmed === "") throw new Error("task_storage.repo cannot be empty.");
 	if (trimmed === "OWNER/REPO") throw new Error(`task_storage.repo cannot be the OWNER/REPO placeholder — set a real slug.`);
 	if (!SLUG_PATTERN.test(trimmed)) throw new Error(`task_storage.repo must be in owner/name format (got "${slug}").`);
 };
-/**
-* Resolve `task_storage.repo` for an install. Order of precedence:
-*
-*   1. `--task-storage-repo=<slug>` flag (explicit, validated by caller).
-*   2. The slug `scanRepo` parsed from the local git origin remote.
-*   3. TTY interactive menu — manual entry, gh-create-and-wire, or skip.
-*   4. Non-TTY → placeholder + warning (the emit-gate refuses placeholder
-*      events later, so polluted telemetry can't escape).
-*
-* The whole interactive flow lives behind `deps` so tests don't need to mock
-* TTY or shell out to `gh`.
-*/
 const resolveTaskStorageRepo = async (input) => {
 	const { scannedSlug, flagSlug, deps } = input;
 	if (flagSlug) return {
@@ -4935,13 +4570,6 @@ const promptManualSlug = async (deps) => {
 		}
 	}
 };
-/**
-* Run `gh repo create <slug> --(private|public) --source=. --remote=origin`.
-* Returns the resolved result on success, or `null` to signal the caller to
-* present the retry menu. gh failures (gh missing, not authed, name taken,
-* etc.) all flow through this same path — the stderr we forward names the
-* specific cause.
-*/
 const tryGhCreate = async (deps) => {
 	const slug = await promptValidSlug(deps, "Full slug (owner/name): ");
 	const visibility = await promptVisibility(deps);
@@ -5015,11 +4643,6 @@ const readHarnessVersion = async () => {
 	if (!parsed.version) throw new Error(`package.json at ${PACKAGE_JSON_PATH} has no version.`);
 	return parsed.version;
 };
-/**
-* Wrap `execFile` as the `{code, stdout, stderr}` shell-out the resolver, label
-* sync, status, and doctor all share. A missing binary (ENOENT) maps to exit 127
-* so callers can show a "not found" path instead of crashing.
-*/
 const makeRunCommand = () => async (cmd, args) => {
 	try {
 		const result = await execFileAsync(cmd, args);
@@ -5042,13 +4665,6 @@ const makeRunCommand = () => async (cmd, args) => {
 		};
 	}
 };
-/**
-* Build the real I/O dependencies the slug resolver needs at the CLI layer.
-* Tests target `resolveTaskStorageRepo` directly with scripted mocks; this
-* builder exists only to wire `readline/promises` + `execFile` for the
-* production path. Returns the deps alongside a `close()` the install command
-* must call so the readline interface releases stdin and the process exits.
-*/
 const buildResolveDeps = () => {
 	const rl = createInterface({
 		input: stdin,
@@ -5066,11 +4682,6 @@ const buildResolveDeps = () => {
 		close: () => rl.close()
 	};
 };
-/**
-* Current branch + how many commits it trails origin's default branch, using
-* only local refs (no fetch) — the same cheap read `init.sh` does. Either field
-* is null when it can't be determined (no remote HEAD ref, detached, etc.).
-*/
 const gitBehind = async (repoRoot) => {
 	const run = makeRunCommand();
 	const branchResult = await run("git", [
@@ -5164,35 +4775,16 @@ const install = async (args) => {
 		});
 	} catch {}
 };
-/**
-* Surface the opt-in capabilities the repo could enable but hasn't (issue #136): each
-* line names the convention file to create and what it unlocks. Warn-only — silent when
-* nothing is latent (every gated capability already active, or none applies). The
-* harness never creates these files (decision #8); it only informs.
-*/
 const reportLatentCapabilities = (latent) => {
 	if (latent.length === 0) return;
 	console.log("Opt-in capabilities available (not installed):");
 	for (const cap of latent) console.log(`  ${cap.trigger} → ${cap.skills.join(", ")}: ${cap.label}.`);
-	console.log("  Run /add-capability in Claude Code to activate one — the Architect authors the artifact for you (#8: opt-in, never imposed).");
-};
-/**
-* Nudge the user to add the harness as a devDependency (#107/#113). The hooks and
-* agents resolve the telemetry CLI from the project-local `node_modules/.bin` first;
-* without it they fall back to a global/`npx` binary that an fnm Node switch can drop,
-* silently skipping telemetry. Warn-only — install never installs deps for the user.
-*/
+	console.log("  Run /add-capability in Claude Code to activate one — the Architect authors the artifact for you (opt-in, never imposed).");
+};
 const reportDevDependency = (devDependencyMissing) => {
 	if (!devDependencyMissing) return;
 	console.log("For reliable telemetry, add the harness as a devDependency: `npm i -D @lemoncode/lemony` — the hooks resolve the CLI from node_modules/.bin first, which survives an fnm/global PATH change.");
 };
-/**
-* Surface the no-baseline collisions reconciliation resolved (decision D8): which
-* hand-made files were kept (client) or overwritten (vendor), and where the displaced
-* client copies were snapshotted. The header names how the pick was made: an explicit
-* `--on-conflict` (`forced`), the interactive TTY prompt, or the non-TTY vendor default
-* — so the suffix never contradicts the per-file lines below it.
-*/
 const reportCollisions = (collisions, snapshotVersion, mode) => {
 	if (collisions.length === 0) return;
 	const vendorWins = collisions.filter((c) => c.winner === "vendor");
@@ -5204,20 +4796,10 @@ const reportCollisions = (collisions, snapshotVersion, mode) => {
 	for (const { relPath } of vendorWins) console.log(`  used vendor copy: ${relPath}`);
 	if (snapshotVersion !== null) console.log(`Your displaced ${vendorWins.length === 1 ? "copy was" : "copies were"} saved — restore with \`lemony rollback --to ${snapshotVersion}\`.`);
 };
-/**
-* Remind the user about an existing `CLAUDE.md` (decision D8, warn-only). The harness
-* never reads or edits it; the user may have guidance there that overlaps the freshly
-* installed agents/skills and should reconcile it by hand.
-*/
 const reportClaudeMd = (claudeMdPresent) => {
 	if (!claudeMdPresent) return;
 	console.log("Found an existing CLAUDE.md — left untouched. Review it for guidance that now overlaps the installed harness (agents.md, .claude/).");
 };
-/**
-* Surface custom hook commands the settings re-merge silently dropped so the user
-* can restore them in `.claude/settings.local.json` (the supported escape hatch —
-* vendor authority is the `hooks` block only). Shared by install and update.
-*/
 const reportLostHooks = (lostHookCommands) => {
 	if (lostHookCommands.length === 0) return;
 	const count = lostHookCommands.length;
@@ -5225,14 +4807,6 @@ const reportLostHooks = (lostHookCommands) => {
 	for (const command of lostHookCommands) console.log(`  ${command}`);
 	console.log("Restore them in .claude/settings.local.json if you want them back.");
 };
-/**
-* `update [--on-conflict=<vendor|client>] [--dry-run] [--allow-downgrade]` — move the
-* install to the catalog version via the shared 3-way reconcile (ADR 0005). `--dry-run`
-* previews the plan (merge/add/prune/adopt counts + per-file picks/adoptions/conflicts)
-* and writes nothing — the read-only refusal guards still run, so the preview reflects a
-* real run. By default `update` refuses a downgrade (installed catalog older than the
-* pin, #172); `--allow-downgrade` forces it.
-*/
 const update = async (args) => {
 	const repoRoot = cwd();
 	const onConflict = parseOnConflict(args);
@@ -5259,11 +4833,6 @@ const update = async (args) => {
 	}
 };
 const isOnConflict = (value) => value === "vendor" || value === "client";
-/**
-* Parse + validate the shared `--on-conflict=<vendor|client>` flag (used by `install`
-* and `update`). Returns the policy, `undefined` when absent, and exits 1 on a bad
-* value so a typo fails fast at the boundary instead of silently no-opping.
-*/
 const parseOnConflict = (args) => {
 	const raw = parseFlag(args, "on-conflict");
 	if (raw === void 0) return void 0;
@@ -5273,12 +4842,6 @@ const parseOnConflict = (args) => {
 	}
 	return raw;
 };
-/**
-* `repair [--dry-run]` — baseline-aware re-sync at the pinned version (ADR 0005 D3):
-* restore missing vendor files + re-sync labels/hooks, never clobbering a client edit.
-* Refuses (pointing at `update`) when the catalog is a different version. `--dry-run`
-* previews the re-sync plan (shared with `update`) and writes nothing.
-*/
 const repair = async (args) => {
 	const dryRun = args.includes("--dry-run");
 	const result = await runRepair({
@@ -5297,12 +4860,6 @@ const repair = async (args) => {
 		reportLostHooks(result.lostHookCommands);
 	}
 };
-/**
-* `uninstall [--labels]` — remove vendor-managed files (ADR 0005, D7). The inverse
-* of install over the baseline registry; preserves CLAUDE.md/CONTEXT.md/docs/state/
-* events.jsonl/adopted skills. Labels stay on the remote unless `--labels` is given.
-* `runUninstall` refuses when not installed or when no baseline registry exists.
-*/
 const uninstall = async (args) => {
 	const requestedLabels = args.includes("--labels");
 	const result = await runUninstall({
@@ -5321,22 +4878,9 @@ const uninstall = async (args) => {
 	console.log("  Preserved: CLAUDE.md, CONTEXT.md, docs/, .claude/state/, events.jsonl, adopted skills.");
 	reportLabelDeletion(result.labelDeletion, requestedLabels);
 };
-/** Print the label outcome for `uninstall` — formatting lives in `formatLabelDeletion`. */
 const reportLabelDeletion = (deletion, requested) => {
 	for (const line of formatLabelDeletion(deletion, requested)) console.log(line);
 };
-/**
-* `rollback [--to=<version>] [--list] [--cleanup] [--force]` — restore a pre-change
-* snapshot (#48), offline. `--list` prints the retained snapshots, `--cleanup` clears
-* them; both are read/metadata operations that never touch the working tree. With
-* neither, the default restores the most recent snapshot (or `--to=<version>`).
-*
-* Note: EVERY mutating command snapshots before it writes — `update` and `repair`.
-* So the "most recent" snapshot a no-arg rollback restores may be the one a `repair`
-* took (same pinned version), not the last `update`. That rollback is a real revert
-* (the pre-change tree + baseline) but leaves the version unchanged; to undo an
-* `update`, target the prior version with `--to=` (see `--list`).
-*/
 const rollback = async (args) => {
 	const repoRoot = cwd();
 	const requestedModes = [
@@ -5377,30 +4921,18 @@ const rollback = async (args) => {
 		console.log("  newest one. To undo an `update`, see `rollback --list` then `rollback --to=<version>`.");
 	}
 };
-/**
-* Print the unresolved-conflict block shared by `update` and `repair`
-* (3-way merge writes markers, never blocks — #49). `trailer` is the verb-specific
-* "the next <verb> refuses until they are gone" hint; `repair` passes none.
-*/
 const reportConflicts = (conflictedFiles, trailer) => {
 	if (conflictedFiles.length === 0) return;
 	console.log(`\n${conflictedFiles.length} file(s) need conflict resolution:`);
 	for (const relPath of conflictedFiles) console.log(`  ${relPath}`);
 	if (trailer) console.log(trailer);
 };
-/**
-* Print the adopted-orphans block (`update`/`repair`) — files the engine kept on disk
-* and dropped from the baseline. `label` carries the caller's tense ("adopted" /
-* "would adopt" for a dry run).
-*/
 const reportAdoptions = (adoptedFiles, label = "adopted") => {
 	for (const relPath of adoptedFiles) console.log(`  ${label} ${relPath} (kept your copy; no longer vendor-managed).`);
 };
-/** Print the harness:* label reconciliation outcome — formatting in `formatLabelSync`. */
 const reportLabelSync = (sync) => {
 	for (const line of formatLabelSync(sync)) console.log(line);
 };
-/** Print a verb's best-effort label preflight — formatting in `formatLabelSelfHeal`. */
 const reportLabelSelfHeal = (sync) => {
 	for (const line of formatLabelSelfHeal(sync)) console.log(line);
 };
@@ -5413,14 +4945,6 @@ const emit = async (args) => {
 	});
 	console.log(`emitted ${event.type} → ${eventsPath}`);
 };
-/**
-* `telemetry <status|show|flush|disable|enable>` — the human control surface for
-* anonymous telemetry (#232/#227). Two actions stay internal/hook-facing: `send` (the
-* terse fire-and-forget flush `session-close.sh` invokes, #225) and `notice` (the
-* SessionStart disclosure `init.sh` shells out to). `flush` (#227) is the user-facing
-* "force a send now": the same robust engine as `send`, with a verbose human report.
-* Bare `telemetry` defaults to `status`.
-*/
 const runTelemetry = async (args) => {
 	const action = args[0] ?? "status";
 	const repoRoot = cwd();
@@ -5452,7 +4976,6 @@ const runTelemetry = async (args) => {
 		default: throw new Error(`Usage: lemony telemetry <status|show|flush|disable|enable>. Unknown action "${action}".`);
 	}
 };
-/** `telemetry status` — print the resolved on/off, decision source, and watermark. */
 const telemetryStatus = async (repoRoot) => {
 	const report = await buildTelemetryStatus({
 		repoRoot,
@@ -5460,16 +4983,10 @@ const telemetryStatus = async (repoRoot) => {
 	});
 	for (const line of formatTelemetryStatus(report)) console.log(line);
 };
-/** `telemetry show` — dump every local event raw, then its sanitized projection. */
 const telemetryShow = async (repoRoot) => {
 	const report = await buildTelemetryShow(repoRoot);
 	for (const line of formatTelemetryShow(report)) console.log(line);
 };
-/**
-* `telemetry disable [--purge-local]` — write the per-repo-local opt-out, optionally
-* wiping the local log + cursor, then print the resolved status (precedence honesty:
-* if a higher lever like the env var already controls, the status names it).
-*/
 const telemetryDisable = async (repoRoot, args) => {
 	await disableLocally(repoRoot);
 	const purge = args.includes("--purge-local");
@@ -5481,11 +4998,6 @@ const telemetryDisable = async (repoRoot, args) => {
 		env
 	}))) console.log(line);
 };
-/**
-* `telemetry enable` — clear the local opt-out. Honest about precedence: clearing the
-* local lever does not force telemetry on if the env var or committed config still
-* disables it, so re-resolve and say so rather than claim "enabled".
-*/
 const telemetryEnable = async (repoRoot) => {
 	await enableLocally(repoRoot);
 	const report = await buildTelemetryStatus({
@@ -5495,11 +5007,6 @@ const telemetryEnable = async (repoRoot) => {
 	console.log(report.enabled ? "Telemetry enabled (anonymous) for this checkout." : "Local opt-out cleared, but telemetry is still OFF for another reason:");
 	for (const line of formatTelemetryStatus(report)) console.log(line);
 };
-/**
-* `telemetry send` — flush the unsent tail of `events.jsonl` to the ingest Worker
-* (#225). Internal/hook-facing: `session-close.sh` invokes it fire-and-forget; the
-* engine never throws and self-times-out (D4), so this only prints a terse one-liner.
-*/
 const telemetrySend = async (repoRoot) => {
 	const result = await sendTelemetry({
 		repoRoot,
@@ -5507,11 +5014,6 @@ const telemetrySend = async (repoRoot) => {
 	});
 	console.log(`telemetry ${result.outcome} (${result.segmentsSent} sent, ${result.quarantined} quarantined)`);
 };
-/**
-* `telemetry flush` — the user-facing "force a send now" (#227). Same robust engine as
-* `send` (chunking + cursor policy + quarantine, consent-gated), with a verbose report
-* of what it did, so a human debugging "is my telemetry flowing?" sees the whole picture.
-*/
 const telemetryFlush = async (repoRoot) => {
 	const result = await sendTelemetry({
 		repoRoot,
@@ -5539,14 +5041,113 @@ const discovery = async (args) => {
 	if (result.applied.length > 0) console.error(`  Applied before failure: ${result.applied.join(", ")}.`);
 	exit(1);
 };
-/**
-* `spinoff --title=<text> [--body=<text>] [--parent=<id>] [--severity=…] [--kind=…]` —
-* park a non-blocking defect found mid-task as a `harness:managed` +
-* `harness:status:pending` stub and emit `followup_captured` (#112). `--kind` adds a
-* routing label (today `architecture-drift` → pickup resolves it via the Architect's
-* `update-architecture`, #148). The stub creation is fail-loud; the telemetry emit is
-* best-effort (a failed emit surfaces a Warning but the capture stands).
-*/
+const designTokens = async (args) => {
+	const action = args[0] ?? "validate";
+	if (action === "validate") return designTokensValidate(args);
+	if (action === "contrast") return designTokensContrast();
+	if (action === "import") return designTokensImport(args);
+	if (action === "export") return designTokensExport(args);
+	throw new Error(`Usage: lemony design-tokens <validate [--scan=<dir>] | contrast | import --from=<file> [--apply] [--only=<paths>] | export [--tool-state=<file>] [--out=<file>] [--record]>. Unknown action "${action}".`);
+};
+const designTokensValidate = async (args) => {
+	const config = await readHarnessConfig(cwd()).catch(() => void 0);
+	const result = await runValidate({
+		repoRoot: cwd(),
+		scanDir: parseFlag(args, "scan"),
+		extraExtensions: config?.design_tokens.scan_extensions
+	});
+	if (!result.tokensFound) {
+		console.log(`No docs/design-tokens.json — design-tokens validate skipped (consume-if-exists; the harness never creates it).`);
+		return;
+	}
+	if (result.ok) {
+		console.log(`design-tokens valid: ${result.tokenCount} token(s), ${result.filesScanned} file(s) scanned, no hardcoded values.`);
+		return;
+	}
+	console.error(`design-tokens validate found ${result.violations.length} violation(s):`);
+	for (const violation of result.violations) {
+		const where = violation.file ? violation.line !== void 0 ? `${violation.file}:${violation.line} ` : `${violation.file} ` : "";
+		console.error(`  ${where}[${violation.kind}] ${violation.message}`);
+	}
+	exit(1);
+};
+const designTokensContrast = async () => {
+	const result = await runContrast({ repoRoot: cwd() });
+	if (!result.tokensFound) {
+		console.log(`No docs/design-tokens.json — design-tokens contrast skipped (consume-if-exists; the harness never creates it).`);
+		return;
+	}
+	const failures = result.pairs.filter((pair) => !pair.passes);
+	if (result.ok) {
+		console.log(result.pairsChecked === 0 ? `design-tokens contrast: no foreground/background pairs found (use the on-* convention or $extensions["com.lemony.contrast"]).` : `design-tokens contrast OK: ${result.pairsChecked} pair(s) meet their WCAG floor.`);
+		return;
+	}
+	console.error(`design-tokens contrast found ${failures.length + result.problems.length} issue(s):`);
+	for (const pair of failures) console.error(`  ${pair.foreground} on ${pair.background} (${pair.mode}, ${pair.level}): ${pair.ratio}:1 < ${pair.floor}:1`);
+	for (const problem of result.problems) console.error(`  ${problem}`);
+	exit(1);
+};
+const designTokensImport = async (args) => {
+	const from = parseFlag(args, "from");
+	if (from === void 0) throw new Error("Usage: lemony design-tokens import --from=<neutral-file> [--apply] [--only=<dotted,paths>]");
+	const only = parseFlag(args, "only")?.split(",").map((path) => path.trim()).filter((path) => path.length > 0);
+	const result = await runImport({
+		repoRoot: cwd(),
+		neutralPath: resolve(cwd(), from),
+		apply: args.includes("--apply"),
+		only
+	});
+	if (result.problems.length > 0) {
+		console.error("design-tokens import could not run:");
+		for (const problem of result.problems) console.error(`  ${problem}`);
+		exit(1);
+	}
+	if (result.applied) {
+		console.log(`design-tokens import applied: wrote ${result.written.length} token(s) to ${DESIGN_TOKENS_FILE}.`);
+		if (result.skipped.length > 0) console.log(`  skipped ${result.skipped.length} path(s) that would clobber an existing group or token — resolve by hand: ${result.skipped.join(", ")}`);
+		return;
+	}
+	const landing = result.changes.filter((change) => change.kind !== "unchanged");
+	const news = landing.filter((change) => change.kind === "new").length;
+	const changed = landing.length - news;
+	console.log(`design-tokens import preview: ${news} new, ${changed} changed, ${result.changes.length - landing.length} unchanged.`);
+	for (const change of landing) {
+		const detail = change.kind === "changed" ? `${change.before} → ${change.after}` : change.after;
+		console.log(`  [${change.kind}] ${change.path} (${change.tier}): ${detail}`);
+	}
+	if (landing.length > 0) console.log(`Curate the slice, then: lemony design-tokens import --from=${from} --apply --only=<paths>`);
+};
+const designTokensExport = async (args) => {
+	const toolState = parseFlag(args, "tool-state");
+	const out = parseFlag(args, "out");
+	if (out !== void 0 && args.includes("--record")) {
+		console.error("design-tokens export: --out and --record are mutually exclusive — preview/push with --out, then --record only after the push succeeds.");
+		exit(1);
+	}
+	const result = await runExport({
+		repoRoot: cwd(),
+		...toolState ? { toolStatePath: resolve(cwd(), toolState) } : {},
+		...out ? { outPath: resolve(cwd(), out) } : {},
+		record: args.includes("--record")
+	});
+	if (!result.tokensFound) {
+		console.log(`No ${DESIGN_TOKENS_FILE} — design-tokens export skipped (consume-if-exists; the harness never creates it).`);
+		return;
+	}
+	if (result.problems.length > 0) {
+		console.error("design-tokens export could not run:");
+		for (const problem of result.problems) console.error(`  ${problem}`);
+		exit(1);
+	}
+	if (result.recorded) {
+		console.log(`design-tokens export recorded: drift baseline stamped (${result.hash.slice(0, 12)}).`);
+		return;
+	}
+	const creates = result.plan.filter((entry) => entry.kind === "create").length;
+	const updates = result.plan.filter((entry) => entry.kind === "update").length;
+	console.log(`design-tokens export plan: ${creates} to create, ${updates} to update (tool-only variables are never deleted).`);
+	if (out !== void 0) console.log(`  projection written to ${out}`);
+};
 const spinoff = async (args) => {
 	const harnessVersion = await readHarnessVersion();
 	const result = await runSpinoff({
@@ -5587,6 +5188,13 @@ const status = async () => {
 	console.log(`  Branch:       ${report.branch ?? "(unknown)"} (${behindText})`);
 	console.log(`  Last session: ${report.lastSession ?? "(none)"}`);
 	console.log(`  Open discoveries: ${discoveries}`);
+	if (report.designToolDrift !== null) console.log(`  Design tool:  ${DESIGN_TOOL_STATUS[report.designToolDrift]}`);
+};
+const DESIGN_TOOL_STATUS = {
+	"n/a": "not in use",
+	"never-projected": "declared, never exported (run /sync-design-tokens export)",
+	"in-sync": "in sync",
+	"export-pending": "export pending (run /sync-design-tokens export)"
 };
 const doctor = async () => {
 	const report = await runDoctor({
@@ -5666,6 +5274,9 @@ const main = async () => {
 		case "discovery":
 			await discovery(args);
 			return;
+		case "design-tokens":
+			await designTokens(args);
+			return;
 		case "spinoff":
 			await spinoff(args);
 			return;