@cleocode/skills 2026.5.83 → 2026.5.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.5.83",
+  "version": "2026.5.86",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/_shared/__tests__/lifecycle-protocol-reconcile.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Lifecycle-protocol reconcile gate (T9672).
+ *
+ * Asserts the SET equality:
+ *
+ *   SET( cleo lifecycle stages )
+ *   ==
+ *   SET( manifest.dispatch_matrix.by_protocol keys )
+ *     − { "artifact-publish", "provenance", "agent-protocol" }   # cross-cutting
+ *
+ * No normalization, no dashed-alias allowance. This is the strict gate that
+ * lands together with the manifest rename `architecture-decision` →
+ * `architecture_decision` so that a future drift fails CI.
+ *
+ * @task T9672
+ * @epic T9568
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const manifestPath = resolve(thisDir, '../../manifest.json');
+
+interface Manifest {
+  dispatch_matrix: {
+    by_protocol: Record<string, string>;
+    by_keyword: Record<string, string>;
+  };
+}
+
+const manifest: Manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
+/**
+ * The canonical 10 LOOM lifecycle stages emitted by `cleo lifecycle --help`.
+ * Underscored form is authoritative — see `packages/core/src/lifecycle/`.
+ */
+const LIFECYCLE_STAGES = [
+  'research',
+  'consensus',
+  'architecture_decision',
+  'specification',
+  'decomposition',
+  'implementation',
+  'validation',
+  'testing',
+  'release',
+  'contribution',
+] as const;
+
+/**
+ * Cross-cutting protocols that live in `dispatch_matrix.by_protocol` but are
+ * not LOOM lifecycle stages.
+ */
+const CROSS_CUTTING_PROTOCOLS = new Set([
+  'artifact-publish',
+  'provenance',
+  'agent-protocol',
+]);
+
+describe('lifecycle ↔ protocol reconcile (T9672)', () => {
+  const byProtocolKeys = new Set(Object.keys(manifest.dispatch_matrix.by_protocol));
+  const stageOnlyKeys = new Set(
+    [...byProtocolKeys].filter((k) => !CROSS_CUTTING_PROTOCOLS.has(k)),
+  );
+  const expected = new Set<string>(LIFECYCLE_STAGES);
+
+  it('every cleo lifecycle stage is present as a strict (underscored) key in dispatch_matrix.by_protocol', () => {
+    for (const stage of LIFECYCLE_STAGES) {
+      expect(
+        byProtocolKeys.has(stage),
+        `lifecycle stage "${stage}" missing from dispatch_matrix.by_protocol — keys: ${[...byProtocolKeys].sort().join(', ')}`,
+      ).toBe(true);
+    }
+  });
+
+  it('dispatch_matrix.by_protocol contains no surplus stage-like keys', () => {
+    for (const key of stageOnlyKeys) {
+      expect(
+        expected.has(key),
+        `dispatch_matrix.by_protocol has key "${key}" which is not a cleo lifecycle stage and not a known cross-cutting protocol`,
+      ).toBe(true);
+    }
+  });
+
+  it('the dashed legacy form "architecture-decision" is NOT a dispatch_matrix.by_protocol key', () => {
+    expect(byProtocolKeys.has('architecture-decision')).toBe(false);
+  });
+
+  it('the dashed legacy form "architecture-decision" IS preserved as a keyword alias', () => {
+    const keywordKeys = Object.keys(manifest.dispatch_matrix.by_keyword);
+    const adrLine = keywordKeys.find((k) => k.includes('adr') && k.includes('formalize'));
+    expect(
+      adrLine,
+      `expected the ct-adr-recorder keyword dispatch line to exist; keys: ${keywordKeys.join(', ')}`,
+    ).toBeDefined();
+    expect(
+      (adrLine ?? '').includes('architecture-decision'),
+      `architecture-decision keyword alias must be retained in ${adrLine}`,
+    ).toBe(true);
+  });
+
+  it('the underscored canonical form "architecture_decision" maps to ct-adr-recorder', () => {
+    expect(manifest.dispatch_matrix.by_protocol.architecture_decision).toBe('ct-adr-recorder');
+  });
+
+  it('the by_protocol stage-only key set is exactly equal to the lifecycle stage set', () => {
+    expect([...stageOnlyKeys].sort()).toEqual([...expected].sort());
+  });
+});

package/skills/_shared/__tests__/loom-adr-links.test.ts

@@ -0,0 +1,163 @@
+/**
+ * ADR-link gate for LOOM-stage skills (T9665).
+ *
+ * Enforces two invariants on every canonical LOOM-stage skill in
+ * `packages/skills/skills/manifest.json`:
+ *
+ *   1. The skill entry declares a non-empty `adrRefs[]` array of ADR IDs.
+ *   2. Every ADR id in the array resolves to a real file under `.cleo/adrs/`.
+ *
+ * The mapping of (stage -> required adrRefs minimum) is the authoritative
+ * source-of-truth defined in `docs/skills/loom-coverage-matrix.md` under
+ * the "ADR Bindings Section". When that doc updates, this test updates.
+ *
+ * @task T9665
+ * @epic T9568
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const manifestPath = resolve(thisDir, '../../manifest.json');
+const adrDir = resolve(thisDir, '../../../../../.cleo/adrs');
+
+interface SkillEntry {
+  name: string;
+  loomStage?: string;
+  adrRefs?: string[];
+  [key: string]: unknown;
+}
+
+interface Manifest {
+  skills: SkillEntry[];
+}
+
+const manifest: Manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
+/**
+ * The canonical 10 LOOM lifecycle stages — underscored form is authoritative.
+ * Must match `cleo lifecycle --help` output.
+ */
+const CANONICAL_LOOM_STAGES = [
+  'research',
+  'consensus',
+  'architecture_decision',
+  'specification',
+  'decomposition',
+  'implementation',
+  'validation',
+  'testing',
+  'release',
+  'contribution',
+] as const;
+
+/**
+ * Required ADR-id minimums per stage. The matrix doc may extend each entry;
+ * this gate only enforces the floor.
+ */
+const REQUIRED_ADR_REFS: Record<(typeof CANONICAL_LOOM_STAGES)[number], string[]> = {
+  research: ['ADR-023', 'ADR-070'],
+  consensus: ['ADR-015', 'ADR-023'],
+  architecture_decision: ['ADR-053', 'ADR-070'],
+  specification: ['ADR-014', 'ADR-023'],
+  decomposition: ['ADR-066', 'ADR-073'],
+  implementation: ['ADR-070', 'ADR-062'],
+  validation: ['ADR-051', 'ADR-023'],
+  testing: ['ADR-051', 'ADR-061'],
+  release: ['ADR-053', 'ADR-063', 'ADR-065'],
+  contribution: ['ADR-015', 'ADR-053'],
+};
+
+/**
+ * Build a set of ADR-id prefixes from .cleo/adrs/. Each filename starts
+ * with `ADR-NNN-...`; we extract the prefix before the second dash.
+ */
+function loadAdrIdSet(): Set<string> {
+  const files = readdirSync(adrDir);
+  const ids = new Set<string>();
+  for (const file of files) {
+    const match = file.match(/^(ADR-\d{3})-/);
+    if (match) ids.add(match[1]);
+  }
+  return ids;
+}
+
+const adrIds = loadAdrIdSet();
+const skillsByStage = new Map<string, SkillEntry>();
+for (const s of manifest.skills) {
+  if (typeof s.loomStage === 'string') {
+    skillsByStage.set(s.loomStage, s);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gate 1: every LOOM-stage skill declares a non-empty adrRefs[]
+// ---------------------------------------------------------------------------
+
+describe('LOOM ADR links — adrRefs[] declared on every LOOM-stage skill', () => {
+  for (const stage of CANONICAL_LOOM_STAGES) {
+    it(`stage "${stage}" skill carries a non-empty adrRefs[]`, () => {
+      const skill = skillsByStage.get(stage);
+      expect(skill, `no skill found with loomStage="${stage}"`).toBeDefined();
+      expect(
+        Array.isArray(skill?.adrRefs),
+        `skill ${skill?.name} adrRefs is not an array`,
+      ).toBe(true);
+      expect(
+        (skill?.adrRefs ?? []).length,
+        `skill ${skill?.name} adrRefs is empty`,
+      ).toBeGreaterThan(0);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Gate 2: every adrRef resolves to a real file under .cleo/adrs/
+// ---------------------------------------------------------------------------
+
+describe('LOOM ADR links — every adrRefs entry resolves to .cleo/adrs/<id>-*.md', () => {
+  it('.cleo/adrs/ exists and was loaded', () => {
+    expect(existsSync(adrDir), `.cleo/adrs/ not found at ${adrDir}`).toBe(true);
+    expect(adrIds.size).toBeGreaterThan(0);
+  });
+
+  for (const stage of CANONICAL_LOOM_STAGES) {
+    const skill = skillsByStage.get(stage);
+    const refs = skill?.adrRefs ?? [];
+    for (const ref of refs) {
+      it(`stage "${stage}" skill ${skill?.name} references real ADR file "${ref}"`, () => {
+        expect(
+          adrIds.has(ref),
+          `${ref} not found under .cleo/adrs/ — known prefixes: ${[...adrIds].sort().join(', ')}`,
+        ).toBe(true);
+      });
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Gate 3: required ADR floor per stage is met
+// ---------------------------------------------------------------------------
+
+describe('LOOM ADR links — required ADR floor met per stage', () => {
+  for (const stage of CANONICAL_LOOM_STAGES) {
+    const required = REQUIRED_ADR_REFS[stage];
+    const skill = skillsByStage.get(stage);
+    const refs = new Set(skill?.adrRefs ?? []);
+    for (const requiredAdr of required) {
+      it(`stage "${stage}" includes required ADR "${requiredAdr}" in adrRefs`, () => {
+        expect(
+          refs.has(requiredAdr),
+          `skill ${skill?.name} for stage ${stage} missing required ADR ${requiredAdr} (has: ${[...refs].join(', ')})`,
+        ).toBe(true);
+      });
+    }
+  }
+});

package/skills/_shared/__tests__/loom-stage-coverage.test.ts

@@ -0,0 +1,167 @@
+/**
+ * LOOM-stage coverage gate (T9664).
+ *
+ * Enforces that every canonical LOOM lifecycle stage emitted by `cleo lifecycle`
+ * has a bound skill in `packages/skills/skills/manifest.json` and that the
+ * skill's entry declares a `loomStage` field equal to the lifecycle stage name
+ * in underscored canonical form (the `cleo lifecycle` source-of-truth form).
+ *
+ * Why this exists:
+ * - The lifecycle CLI is the runtime source of truth for stage names.
+ * - The manifest's `dispatch_matrix.by_protocol` is the dispatch routing table.
+ * - Historically those two surfaces drifted (T9568 audit found
+ *   `architecture-decision` dashed in manifest vs `architecture_decision`
+ *   underscored in lifecycle CLI).
+ * - This test pins the contract so future drift fails CI instead of silently
+ *   reaching agents at spawn time.
+ *
+ * @task T9664
+ * @epic T9568
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const manifestPath = resolve(thisDir, '../../manifest.json');
+
+interface SkillEntry {
+  name: string;
+  protocol?: string;
+  loomStage?: string;
+  status?: string;
+  // intentionally permissive — other fields ignored for this gate
+  [key: string]: unknown;
+}
+
+interface Manifest {
+  dispatch_matrix: {
+    by_protocol: Record<string, string>;
+  };
+  skills: SkillEntry[];
+}
+
+const manifest: Manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
+/**
+ * The canonical 10 LOOM lifecycle stages emitted by `cleo lifecycle` (see
+ * `packages/core/src/lifecycle/`). Underscored form is authoritative.
+ * Update this constant ONLY when the lifecycle CLI itself adds or removes
+ * a stage — never to silence a drift failure.
+ */
+const CANONICAL_LOOM_STAGES = [
+  'research',
+  'consensus',
+  'architecture_decision',
+  'specification',
+  'decomposition',
+  'implementation',
+  'validation',
+  'testing',
+  'release',
+  'contribution',
+] as const;
+
+/**
+ * Cross-cutting protocols that live in `dispatch_matrix.by_protocol` but are
+ * NOT LOOM lifecycle stages. They route by capability, not by lifecycle
+ * position, and are excluded from the 10-stage gate.
+ */
+const CROSS_CUTTING_PROTOCOLS = new Set([
+  'artifact-publish',
+  'provenance',
+  'agent-protocol',
+]);
+
+/**
+ * Skill-name lookup keyed by the `name` field.
+ */
+const skillByName = new Map(manifest.skills.map((s) => [s.name, s]));
+
+// ---------------------------------------------------------------------------
+// Gate 1: every canonical stage has a binding in dispatch_matrix.by_protocol
+// ---------------------------------------------------------------------------
+
+describe('LOOM stage coverage — dispatch_matrix.by_protocol', () => {
+  for (const stage of CANONICAL_LOOM_STAGES) {
+    it(`stage "${stage}" is bound to a skill in dispatch_matrix.by_protocol`, () => {
+      // We accept either the underscored form (canonical) or the dashed
+      // legacy alias (architecture-decision) until T9672 reconciles. After
+      // T9672, only the underscored key is required.
+      const dashed = stage.replace(/_/g, '-');
+      const skillName =
+        manifest.dispatch_matrix.by_protocol[stage] ??
+        manifest.dispatch_matrix.by_protocol[dashed];
+      expect(
+        skillName,
+        `LOOM stage "${stage}" has no skill binding in manifest.dispatch_matrix.by_protocol (checked both "${stage}" and "${dashed}")`,
+      ).toBeTruthy();
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Gate 2: every protocol-bound skill carries a matching loomStage frontmatter
+// ---------------------------------------------------------------------------
+
+describe('LOOM stage coverage — loomStage field on bound skills', () => {
+  for (const stage of CANONICAL_LOOM_STAGES) {
+    it(`bound skill for "${stage}" declares loomStage === "${stage}"`, () => {
+      const dashed = stage.replace(/_/g, '-');
+      const skillName =
+        manifest.dispatch_matrix.by_protocol[stage] ??
+        manifest.dispatch_matrix.by_protocol[dashed];
+      const skill = skillName ? skillByName.get(skillName) : undefined;
+      expect(skill, `skill "${skillName}" not found in manifest.skills[]`).toBeDefined();
+      expect(
+        skill?.loomStage,
+        `skill "${skillName}" missing loomStage field; expected "${stage}"`,
+      ).toBe(stage);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Gate 3: every skill that has loomStage uses a canonical (underscored) value
+// ---------------------------------------------------------------------------
+
+describe('LOOM stage coverage — loomStage values are canonical', () => {
+  const stagesSet = new Set<string>(CANONICAL_LOOM_STAGES);
+  const skillsWithLoomStage = manifest.skills.filter((s) => typeof s.loomStage === 'string');
+
+  it('at least 10 skills carry a loomStage field (one per LOOM stage)', () => {
+    expect(skillsWithLoomStage.length).toBeGreaterThanOrEqual(CANONICAL_LOOM_STAGES.length);
+  });
+
+  for (const skill of skillsWithLoomStage) {
+    it(`skill "${skill.name}" loomStage value "${skill.loomStage}" is a canonical LOOM stage`, () => {
+      expect(stagesSet.has(skill.loomStage as string)).toBe(true);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Gate 4: dispatch_matrix.by_protocol keys minus cross-cutting == LOOM stages
+// (the union of the 10 lifecycle stages — checked allowing dashed alias for
+//  architecture_decision until T9672 lands the reconcile)
+// ---------------------------------------------------------------------------
+
+describe('LOOM stage coverage — dispatch_matrix.by_protocol key set', () => {
+  it('by_protocol keys minus cross-cutting protocols cover every canonical LOOM stage', () => {
+    const keys = new Set(Object.keys(manifest.dispatch_matrix.by_protocol));
+    const stageKeys = [...keys].filter((k) => !CROSS_CUTTING_PROTOCOLS.has(k));
+    const normalized = new Set(stageKeys.map((k) => k.replace(/-/g, '_')));
+    for (const stage of CANONICAL_LOOM_STAGES) {
+      expect(
+        normalized.has(stage),
+        `LOOM stage "${stage}" not represented in dispatch_matrix.by_protocol (normalized keys: ${[...normalized].join(', ')})`,
+      ).toBe(true);
+    }
+  });
+});

package/skills/ct-adr-recorder/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: ct-adr-recorder
 description: "Records Architecture Decision Records from accepted consensus verdicts. Use when promoting a consensus outcome to a formal ADR: drafts the document in the proposed-then-accepted HITL lifecycle, links to the originating consensus manifest, persists the decision to the canonical SQLite decisions table, and triggers downstream invalidation when an accepted ADR is later superseded. Triggers on phrases like 'write ADR', 'record architecture decision', 'formalize this decision', 'lock in the choice', 'create ADR-XXX', or when a consensus task reaches completed status and needs formalization."
+protocol: architecture_decision
+loomStage: architecture_decision
+adrRefs:
+  - ADR-053
+  - ADR-070
 ---
 
 # ADR Recorder
@@ -88,6 +93,80 @@ Flags specs T4776, T4781; decomposition epic T4772; live impl T4790.
 
 A longer, realistic example with all six sections filled out lives in [references/examples.md](references/examples.md).
 
+## Through SDK (preferred)
+
+ADRs are first-class docs SSoT records — drafted via
+`cleo docs add --type adr`, attached to the originating consensus task,
+and numbered through the slug. This is the canonical write path; the
+legacy "write to `docs/adr/ADR-NNNN.md` and commit" pattern is
+deprecated below.
+
+### Draft the ADR attached to its consensus task
+
+```bash
+cleo docs add T4798 docs/adr/ADR-0042.md \
+  --type adr \
+  --slug adr-0042-drizzle-v1-beta \
+  --desc "ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access (status: proposed)" \
+  --labels "adr,proposed"
+```
+
+- `--type adr` is the canonical taxonomy value. The closed set is
+  `spec | adr | research | handoff | note | llm-readme`.
+- `--slug` MUST follow `adr-<NNNN>-<short-topic>`. The numeric segment
+  is the canonical ADR id; the topic segment makes the slug human
+  readable. Collisions return `E_SLUG_TAKEN` with 3 alternatives.
+- The owner ID is the consensus task whose verdict drives the ADR
+  (`T4798` above). This is how downstream supersession cascades find
+  the chain — never attach an ADR to an arbitrary task.
+
+### Persist the decision row alongside the doc blob
+
+`cleo docs add --type adr` writes the document and the docs-side
+manifest entry, but per Immutable Constraint ADR-006 the canonical
+`decisions` table MUST also be populated via Drizzle. The two writes
+are paired: doc blob first (SSoT-of-the-prose), then the relational
+row (SSoT-of-the-decision). Skipping either is a validation failure.
+
+### Publish the ADR to a git-tracked path
+
+```bash
+cleo docs publish --for T4798 --to docs/adr/ADR-0042.md
+```
+
+Atomic tmp-then-rename. The published file lands in the next commit;
+the SSoT blob remains the canonical version-history root.
+
+### Fetch the ADR back by slug (for HITL review + downstream supersession)
+
+```bash
+cleo docs fetch adr-0042-drizzle-v1-beta     # latest version
+cleo docs versions --for T4798               # every SHA version
+```
+
+The HITL reviewer reads the proposed ADR via `cleo docs fetch` rather
+than the on-disk file so the review anchors on the canonical SSoT
+blob — drift between the published file and the blob is its own
+review finding.
+
+### List ADRs by type or status
+
+```bash
+cleo docs list --type adr --project          # every ADR in the project
+cleo docs list --task T4798 --type adr       # ADRs attached to T4798
+```
+
+## Deprecated: Direct filesystem write
+
+The legacy "write to `docs/adr/ADR-NNNN.md` and commit" pattern is
+deprecated. The on-disk file drifts from the SSoT, the ADR has no
+slug for the supersession cascade to retrieve it by, and the
+consensus-task↔ADR linkage exists only as a frontmatter field
+(`consensus_manifest_id`) rather than a relational owner edge.
+Migrate to `cleo docs add --type adr --slug adr-<NNNN>-<topic>` for
+every new ADR — and use `cleo docs sync --from docs/adr/ADR-NNNN.md
+--for <taskId>` to back-fill existing on-disk ADRs into the SSoT.
+
 ## HITL Approval Gate
 
 When a draft reaches `proposed`, the skill MUST:
@@ -173,3 +252,16 @@ Exit code 0 = valid. Exit code 65 = `HANDOFF_REQUIRED`. Exit code 18 = `CASCADE_
 6. Superseding an accepted ADR MUST trigger the downstream cascade over linked specs, decomps, and impls.
 7. Agents MUST NOT retry the HITL handoff on a loop; wait for the human reviewer.
 8. Always validate via `cleo check protocol --protocolType architecture-decision` before exiting.
+
+## See also / References
+
+This skill binds to the **architecture_decision** LOOM lifecycle stage (underscored canonical form — `cleo lifecycle` source of truth). Governing ADRs:
+
+- [ADR-053 — playbook runtime](../../../../.cleo/adrs/ADR-053-playbook-runtime.md) — defines the lifecycle state machine; the ADR stage is one of its 10 nodes.
+- [ADR-070 — three-tier orchestration](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Orchestrator HITL gate that owns the `proposed → accepted` ADR transition.
+
+### Naming Note (T9672)
+
+The stage's canonical name is **`architecture_decision`** (underscored) because the `cleo lifecycle` CLI emits it that way. Historically `packages/skills/skills/manifest.json` `dispatch_matrix.by_protocol` used the dashed form `architecture-decision` — T9672 reconciled that key to the underscored form. The dashed form is retained only as a keyword alias under `dispatch_matrix.by_keyword` so legacy dispatch paths continue to resolve. Frontmatter on this skill (`protocol: architecture_decision`, `loomStage: architecture_decision`) uses the underscored form.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-adr-recorder/__tests__/skill-adr-recorder.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Regression test for ct-adr-recorder/SKILL.md (T9643 / Epic T9629 / Saga T9625).
+ *
+ * Pins the SDK-first ADR contract: ADRs MUST be drafted via
+ * `cleo docs add --type adr --slug adr-<NNNN>-<topic>` so the document
+ * is owned by the originating consensus task and addressable by slug
+ * for the HITL approval gate and the downstream supersession cascade.
+ * The relational `decisions` row (ADR-006) is paired with the doc blob
+ * but persisted separately via Drizzle.
+ *
+ * @task T9643
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-adr-recorder SKILL.md — SDK-first contract (T9643)', () => {
+  it('teaches `cleo docs add --type adr` as the canonical write path', () => {
+    expect(skillContent).toMatch(/cleo docs add[\s\S]+--type adr/);
+  });
+
+  it('shows the `adr-<NNNN>-<topic>` slug convention', () => {
+    expect(skillContent).toMatch(/adr-<NNNN>-<.*?topic/i);
+  });
+
+  it('attaches the ADR to the consensus task via the owner ID', () => {
+    // The example MUST use a T### owner ID to demonstrate consensus-task linkage
+    expect(skillContent).toMatch(/cleo docs add\s+T\d+\s/);
+  });
+
+  it('keeps the relational `decisions` write paired with the doc blob (ADR-006)', () => {
+    expect(skillContent).toMatch(/decisions[\s\S]+Drizzle/i);
+    expect(skillContent).toContain('ADR-006');
+  });
+
+  it('shows `cleo docs publish --for ... --to docs/adr/...` for git publication', () => {
+    expect(skillContent).toMatch(/cleo docs publish[\s\S]+--for[\s\S]+--to[\s\S]+docs\/adr/);
+  });
+
+  it('shows `cleo docs fetch <slug>` for HITL review + supersession', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('shows `cleo docs list --type adr` for ADR discovery', () => {
+    expect(skillContent).toMatch(/cleo docs list[\s\S]+--type adr/);
+  });
+
+  it('marks the old direct-filesystem write as deprecated with a migration note', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem write');
+    expect(skillContent).toMatch(/cleo docs (add|sync)/);
+  });
+
+  it('references E_SLUG_TAKEN for collision handling', () => {
+    expect(skillContent).toContain('E_SLUG_TAKEN');
+  });
+});

package/skills/ct-consensus-voter/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: ct-consensus-voter
 description: "Runs structured multi-agent voting for decision tasks with confidence scores, conflict detection, and HITL escalation when the threshold is not met. Use when two or more agents must vote on options: architecture choices, tool selection, policy decisions, when a task carries agent_type:analysis, or on phrases like 'reach consensus', 'vote on options', 'resolve the debate', 'pick the best approach'. Produces a voting matrix JSON, enforces the 0.5 threshold, flags ties within 0.1 confidence as contested and escalates to human tiebreak."
+protocol: consensus
+loomStage: consensus
+adrRefs:
+  - ADR-015
+  - ADR-023
 ---
 
 # Consensus Voter
@@ -156,3 +161,12 @@ This skill typically hands off to ct-adr-recorder on a `PROVEN` verdict so the d
 6. Manifest entry MUST set `agent_type: "analysis"` and include the verdict.
 7. On PROVEN, hand off to ct-adr-recorder; on CONTESTED or INSUFFICIENT_EVIDENCE, hand off to HITL.
 8. Always validate via `cleo check protocol --protocolType consensus`.
+
+## See also / References
+
+This skill binds to the **consensus** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-015 — multi-contributor architecture](../../../../.cleo/adrs/ADR-015-multi-contributor-architecture.md) — defines the consensus framework that this skill implements.
+- [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines how consensus output is validated before downstream stages consume it.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).