@cleocode/skills 2026.5.83 → 2026.5.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.5.83",
+  "version": "2026.5.84",
   "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
@@ -173,3 +178,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-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).

package/skills/ct-contribution/SKILL.md

@@ -11,6 +11,10 @@ tier: 3
 core: false
 category: meta
 protocol: contribution
+loomStage: contribution
+adrRefs:
+  - ADR-015
+  - ADR-053
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -519,3 +523,79 @@ jq -s '[.[] | select(.epicId == "T2204")] | .[0]' .cleo/contributions/CONTRIBUTI
 | [contribution.schema.json](../../schemas/contribution.schema.json) | **Authoritative** for JSON Schema |
 | [CONTRIBUTION-PROTOCOL-GUIDE.md](../../docs/guides/CONTRIBUTION-PROTOCOL-GUIDE.md) | Usage guide with examples |
 | [CONSENSUS-FRAMEWORK-SPEC.md](../../docs/specs/CONSENSUS-FRAMEWORK-SPEC.md) | Consensus voting thresholds |
+
+---
+
+## LOOM Stage Binding (T9670)
+
+`ct-contribution` is bound to LOOM lifecycle stage **`contribution`** — the terminal node of the RCASD-IVTR+C pipeline. Use this skill to formalize an Epic's contribution back to canon after its work has converged.
+
+### Stage-Transition Contract
+
+The contribution stage is entered from one of two upstream stages depending on the Epic's `kind`:
+
+| Upstream stage | Epic kind | Entry condition |
+|---|---|---|
+| **`release`** | most epics (work, bug, experiment) | Release tag pushed; release manifest recorded |
+| **`testing`** | epics whose `kind` is `release` or that gate on IVTR | IVT loop converged; `ivtLoopConverged: true` recorded |
+| **`specification`** | spec-only epics (no code) | Specification accepted; HITL signoff recorded |
+
+```
+research → consensus → architecture_decision → specification → decomposition
+                                                                   ↓
+                                                            implementation
+                                                                   ↓
+                                                              validation
+                                                                   ↓
+                                                                testing  ← (some epics return here)
+                                                                   ↓
+                                                                release
+                                                                   ↓
+                                                            contribution  ← (this skill)
+```
+
+The transition is enforced by the playbook runtime defined in **ADR-053**. The runtime is a deterministic state machine; `contribution` is its terminal accepting state. Once entered, the Epic is closed in canon.
+
+### Acceptance-Gate Evidence
+
+The contribution stage's completion gate is satisfied by emitting **at least one** of the following ADR-051 evidence atoms, recorded via `cleo verify <epicId> --gate contribution --evidence "<atoms>"`:
+
+| Atom kind | Format | Meaning |
+|---|---|---|
+| `decision:` | `decision:D-<slug>` | A BRAIN decision id that records the contribution outcome. |
+| `files:` | `files:path/a.md,path/b.md` | A list of contribution-format JSON / markdown deliverables produced by `/contribution submit`. |
+| `note:` | `note:<freeform>` | Owner-attested closure rationale; preferred when the contribution is non-textual (e.g. a tag push referenced by SHA in the note). |
+
+Example:
+
+```bash
+cleo verify T9568 --gate contribution \
+  --evidence "decision:D-loom-coverage-001;files:.cleo/contributions/T9568-final.json"
+cleo complete T9568
+```
+
+The gate validator (ADR-051 §2.4) rejects an empty evidence string with `E_EVIDENCE_MISSING`. Stale evidence (modified files after `verify` but before `complete`) fails with `E_EVIDENCE_STALE`.
+
+### Open Follow-Up
+
+A future ADR dedicated to the contribution stage's lifecycle gates (covering automated rollup signals from `cleo saga rollup`, multi-Epic contribution aggregation, and the contribution → "saga close" promotion path) is on the roadmap. File via:
+
+```bash
+cleo add --kind work --type task --severity P2 \
+  --title "T-LOOM-GAP-ADR-CONTRIBUTION: dedicated ADR for contribution stage gates" \
+  --relates T9670 \
+  --acceptance "ADR drafted under .cleo/adrs/|Cross-referenced from ct-contribution SKILL.md|Validator gate updated"
+```
+
+Until that ADR lands, contribution gates derive from ADR-015 (multi-contributor architecture) and ADR-053 (playbook runtime) — both already referenced in this skill's `adrRefs`.
+
+---
+
+## See also / References
+
+This skill binds to the **contribution** LOOM lifecycle stage (the final stage of the RCASD-IVTR+C pipeline). Governing ADRs:
+
+- [ADR-015 — multi-contributor architecture](../../../../.cleo/adrs/ADR-015-multi-contributor-architecture.md) — defines the multi-contributor consensus mechanics that this stage formalizes for an Epic's downstream return path.
+- [ADR-053 — playbook runtime](../../../../.cleo/adrs/ADR-053-playbook-runtime.md) — defines the lifecycle state machine; contribution is its terminal node.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-epic-architect/SKILL.md

@@ -6,6 +6,10 @@ tier: 1
 core: false
 category: recommended
 protocol: decomposition
+loomStage: decomposition
+adrRefs:
+  - ADR-066
+  - ADR-073
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -329,3 +333,14 @@ Recommendation: [Your recommendation]
 | 6 | Validation | Escape `$` as `\$`, check fields |
 
 **Shell Escaping**: Always `\$` in `--notes`/`--description`. See [shell-escaping.md](references/shell-escaping.md).
+
+---
+
+## See also / References
+
+This skill binds to the **decomposition** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-066 — task taxonomy consolidation](../../../../.cleo/adrs/ADR-066-task-taxonomy-consolidation.md) — defines the Type/Kind/Severity axes the decomposer must populate on every leaf task.
+- [ADR-073 — above-epic naming](../../../../.cleo/adrs/ADR-073-above-epic-naming.md) — defines the Saga/Epic/Task/Subtask hierarchy that decomposition produces.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-ivt-looper/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: ct-ivt-looper
 description: "Runs a project-agnostic autonomous Implement-then-Validate-then-Test compliance loop on any git worktree. Detects the project's test framework (vitest, jest, mocha, pytest, unittest, go-test, cargo-test, rspec, phpunit, bats, or other) and iterates until the implementation satisfies its specification, recording convergence metrics to the manifest. Use when given an implementation task that must ship verified: the IVT loop is the autonomous compliance layer enforced before any release or PR. Triggers on phrases like 'implement and verify', 'run the IVT loop', 'ship this task', 'complete implementation with tests', 'verify against spec', or any implementation task with acceptance criteria. Works in any git worktree regardless of language or framework, never hardcoded to one project's tooling."
+protocol: testing
+loomStage: testing
+adrRefs:
+  - ADR-051
+  - ADR-061
 ---
 
 # IVT Looper
@@ -76,6 +81,24 @@ escalate_to_hitl()                         # IVT-007: exit code 65
 
 The loop is a *single* stage from the lifecycle's point of view. Implement, Validate, and Test are not three separate tasks — they are three phases of one autonomous run that either converges or escalates.
 
+## Out of Scope (T9675)
+
+`ct-ivt-looper` operates on the **`testing`** LOOM lifecycle stage (stage 8). It performs the **dynamic** Implement-then-Validate-then-Test loop with framework detection and iterate-until-green convergence semantics.
+
+This skill does NOT:
+
+- Audit static artifacts for schema/compliance/RFC-2119 keyword usage, ADR-document structure, or JSON Schema conformance. Those belong to **`ct-validator`** at the `validation` stage (stage 7). When the question is "is this document/manifest well-formed?" rather than "does this code converge on its spec?", chain to `ct-validator` rather than expanding scope here.
+- Promote a green loop to release. Release sequencing belongs to **`ct-release-orchestrator`** at stage 9.
+
+### Chain handoffs
+
+| Direction | When | Handoff |
+|---|---|---|
+| `ct-ivt-looper` → `ct-validator` | Loop converged; need to audit the resulting artifacts (e.g. final manifest, spec back-references) against schema/compliance | Emit the convergence manifest entry, then dispatch the `validation` stage |
+| `ct-validator` → `ct-ivt-looper` | Spec is valid but implementation needs dynamic verification | Receive a dispatch from the `validation` stage; iterate the IVT loop on the worktree |
+
+Governance: see **ADR-051** (programmatic gate integrity) which defines the evidence atoms (`tool:test`, `test-run:<json>`) the loop emits and that downstream `cleo verify --gate testsPassed` re-validates, and **ADR-061** (project-agnostic verify tools) which defines the canonical tool-resolution layer.
+
 ## Framework Detection
 
 Framework detection is project-agnostic: the skill walks the worktree, inspects config files, and selects the correct test command. No language or framework is special-cased above another. The full detection table lives in [references/frameworks.md](references/frameworks.md). In summary: detection reads the project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, or `.cleo/project-context.json#testing.command`) and selects one of: `vitest`, `jest`, `mocha`, `pytest`, `unittest`, `go-test`, `cargo-test`, `rspec`, `phpunit`, `bats`, `other`.
@@ -179,3 +202,12 @@ cleo check protocol \
 6. Record `framework`, `testsRun`, `testsPassed`, `testsFailed`, `ivtLoopConverged`, `ivtLoopIterations` in the manifest.
 7. On non-convergence, exit 65 and leave the worktree untouched.
 8. Validate every run via `cleo check protocol --protocolType testing`.
+
+## See also / References
+
+This skill binds to the **testing** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-051 — programmatic gate integrity](../../../../.cleo/adrs/ADR-051-programmatic-gate-integrity.md) — defines the evidence atoms (`tool:test`, `test-run:<json>`) that the IVT loop emits and that downstream `cleo verify --gate testsPassed` re-validates.
+- [ADR-061 — project-agnostic verify tools](../../../../.cleo/adrs/ADR-061-project-agnostic-verify-tools.md) — defines the canonical tool-resolution layer (`test`, `build`, `lint`, `typecheck`) that the loop walks for framework-agnostic execution.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-release-orchestrator/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: ct-release-orchestrator
 description: "Orchestrates the full release pipeline: version bump, then changelog, then commit, then tag, then conditionally forks to artifact-publish and provenance based on release config. Parent protocol that composes ct-artifact-publisher and ct-provenance-keeper as sub-protocols: not every release publishes artifacts (source-only releases skip it), and artifact publishers delegate signing and attestation to provenance. Use when shipping a new version, running cleo release ship, or promoting a completed epic to released status."
+protocol: release
+loomStage: release
+adrRefs:
+  - ADR-053
+  - ADR-063
+  - ADR-065
 ---
 
 # Release Orchestrator
@@ -132,3 +138,13 @@ For source-only releases, pass `--no-artifacts` to skip the artifact-publish han
 6. `released` entries are immutable; hotfixes go into new entries.
 7. Manifest entry MUST set `agent_type: "documentation"` and record the full chain via `record_release()`.
 8. Always validate via `cleo check protocol --protocolType release` before declaring the release done.
+
+## See also / References
+
+This skill binds to the **release** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-053 — project-agnostic release pipeline](../../../../.cleo/adrs/ADR-053-project-agnostic-release-pipeline.md) — defines the language-agnostic version bump → changelog → tag flow.
+- [ADR-063 — release pipeline](../../../../.cleo/adrs/ADR-063-release-pipeline.md) — defines the 12-step `cleo release ship` integration with CI.
+- [ADR-065 — PR-required release flow](../../../../.cleo/adrs/ADR-065-pr-required-release-flow.md) — defines the PR-gated path; direct pushes to `main` are prohibited.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-research-agent/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: false
 category: recommended
 protocol: research
+loomStage: research
+adrRefs:
+  - ADR-023
+  - ADR-070
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -224,3 +228,14 @@ If research cannot proceed (access denied, topic too broad, etc.):
 - **Prioritized** - Most important first
 - **Justified** - Tied to specific findings
 - **Feasible** - Achievable within project constraints
+
+---
+
+## See also / References
+
+This skill binds to the **research** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines how research output is validated before downstream stages consume it.
+- [ADR-070 — three-tier orchestration](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Orchestrator → Phase Lead → Worker tiers; research runs as a leaf Worker.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-spec-writer/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: false
 category: recommended
 protocol: specification
+loomStage: specification
+adrRefs:
+  - ADR-014
+  - ADR-023
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -187,3 +191,14 @@ Specifications go in: `docs/specs/{{SPEC_NAME}}.md`
 - [ ] Manifest entry appended
 - [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
 - [ ] Return summary message only
+
+---
+
+## See also / References
+
+This skill binds to the **specification** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-014 — RCASD rename and protocol validation](../../../../.cleo/adrs/ADR-014-rcasd-rename-and-protocol-validation.md) — defines the specification stage's role inside the RCASD-IVTR+C lifecycle.
+- [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines how specifications are validated before decomposition.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-task-executor/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: true
 category: core
 protocol: implementation
+loomStage: implementation
+adrRefs:
+  - ADR-070
+  - ADR-062
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -294,3 +298,14 @@ cleo session gc --include-active
 | Partial deliverables | Missing outputs | Complete all or report partial |
 | Undocumented changes | Lost context | Write detailed output file |
 | Silent failures | Orchestrator unaware | Report via manifest status |
+
+---
+
+## See also / References
+
+This skill binds to the **implementation** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-070 — three-tier orchestration](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Worker tier that ct-task-executor occupies.
+- [ADR-062 — worktree merge, not cherry-pick](../../../../.cleo/adrs/ADR-062-worktree-merge-not-cherry-pick.md) — defines the integration path that preserves the executor's commit SHAs end-to-end.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-validator/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: false
 category: recommended
 protocol: validation
+loomStage: validation
+adrRefs:
+  - ADR-051
+  - ADR-023
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -41,6 +45,26 @@ Context injection for compliance validation tasks spawned via cleo-subagent. Pro
 
 ---
 
+## Out of Scope (T9675)
+
+`ct-validator` operates on the **`validation`** LOOM lifecycle stage (stage 7). It performs **static** schema, compliance, and audit checks against artifacts that already exist on disk (specs, ADRs, JSON files, RFC 2119 keyword usage, manifest schemas).
+
+This skill does NOT:
+
+- Run a test suite, framework detection, or iterative IVT loop. Those belong to **`ct-ivt-looper`** at the `testing` stage (stage 8). When dynamic verification is required — e.g. "does the implementation actually pass its tests?" — chain to `ct-ivt-looper` rather than expanding scope here.
+- Modify code or apply fixes. The validator reports; downstream skills remediate.
+
+### Chain handoffs
+
+| Direction | When | Handoff |
+|---|---|---|
+| `ct-validator` → `ct-ivt-looper` | Spec is valid but implementation needs dynamic verification | Emit a manifest entry, then dispatch the `testing` stage |
+| `ct-ivt-looper` → `ct-validator` | IVT loop converged; need to audit the resulting artifacts against schema/compliance | Dispatch the `validation` stage after the test convergence record |
+
+Governance: see **ADR-051** (programmatic gate integrity) which defines the evidence atoms each stage emits and that the other stage may re-validate, and **ADR-023** (protocol validation dispatch) which routes between them.
+
+---
+
 ## Validation Methodology
 
 ### Standard Workflow
@@ -214,3 +238,14 @@ When invoked by orchestrator, expect these context tokens:
 | Vague findings | Unclear remediation | Specific issue + file/line + fix |
 | Missing severity | Can't prioritize | Always classify: critical/warning/suggestion |
 | No remediation | Findings not actionable | Always provide fix for FAIL/PARTIAL |
+
+---
+
+## See also / References
+
+This skill binds to the **validation** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-051 — programmatic gate integrity](../../../../.cleo/adrs/ADR-051-programmatic-gate-integrity.md) — defines the evidence-atom grammar that the validator emits and re-validates.
+- [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines the protocol-validation routing layer that dispatches to this skill.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/manifest.json

@@ -1,11 +1,13 @@
 {
   "$schema": "https://cleo-dev.com/schemas/v1/skills-manifest.schema.json",
   "_meta": {
-    "schemaVersion": "2.4.0",
-    "lastUpdated": "2026-04-07",
+    "schemaVersion": "2.7.0",
+    "lastUpdated": "2026-05-19",
     "totalSkills": 22,
-    "generatedFrom": "T260 — lifecycle pipeline rework: dedicated skills for ADR, IVT loop, consensus, release, artifact-publish, provenance",
-    "architectureNote": "Universal Subagent Architecture: All spawns use provider-neutral delegation with skill/protocol injection. Pipeline stages and cross-cutting protocols each have a dedicated skill — no overloading."
+    "generatedFrom": "T260 — lifecycle pipeline rework: dedicated skills for ADR, IVT loop, consensus, release, artifact-publish, provenance. T9664/T9665/T9672 (epic T9568) — adds loomStage + adrRefs fields on every LOOM-stage skill entry (underscored canonical form matching `cleo lifecycle` stage names; ADR refs point at .cleo/adrs/). T9672 reconciled dispatch_matrix.by_protocol key 'architecture-decision' → 'architecture_decision' matching the lifecycle CLI source of truth; the dashed form is retained as a keyword alias.",
+    "architectureNote": "Universal Subagent Architecture: All spawns use provider-neutral delegation with skill/protocol injection. Pipeline stages and cross-cutting protocols each have a dedicated skill — no overloading.",
+    "loomStageContract": "Each of the 10 LOOM lifecycle stages (research, consensus, architecture_decision, specification, decomposition, implementation, validation, testing, release, contribution) MUST have a bound skill whose manifest entry declares loomStage matching the lifecycle CLI stage name. The legacy `protocol` field is retained as an alias; dispatch_matrix.by_protocol is the authoritative routing table. See docs/skills/loom-coverage-matrix.md.",
+    "adrRefsContract": "Each LOOM-stage skill MUST declare an adrRefs[] array naming the ADR file(s) that govern the stage. Every referenced ADR-NNN MUST resolve to a file under .cleo/adrs/. The Vitest gate at packages/skills/skills/_shared/__tests__/loom-adr-links.test.ts enforces both conditions."
   },
   "dispatch_matrix": {
     "_comment": "Maps task types/keywords to skill NAMES. Provider adapter decides HOW to execute.",
@@ -33,7 +35,7 @@
       "spec|rfc|protocol|contract": "ct-spec-writer",
       "validate|verify|audit|compliance": "ct-validator",
       "consensus|vote|verdict|resolve the debate": "ct-consensus-voter",
-      "adr|architecture decision|formalize|lock in the choice": "ct-adr-recorder",
+      "adr|architecture decision|architecture-decision|formalize|lock in the choice": "ct-adr-recorder",
       "release|version|ship|changelog|cut release": "ct-release-orchestrator",
       "artifact|publish|registry|npm publish|docker push": "ct-artifact-publisher",
       "provenance|attestation|sbom|sigstore|slsa": "ct-provenance-keeper"
@@ -41,7 +43,7 @@
     "by_protocol": {
       "research": "ct-research-agent",
       "consensus": "ct-consensus-voter",
-      "architecture-decision": "ct-adr-recorder",
+      "architecture_decision": "ct-adr-recorder",
       "specification": "ct-spec-writer",
       "decomposition": "ct-epic-architect",
       "implementation": "ct-task-executor",
@@ -120,6 +122,9 @@
       "status": "active",
       "tier": 0,
       "token_budget": 8000,
+      "protocol": "implementation",
+      "loomStage": "implementation",
+      "adrRefs": ["ADR-070", "ADR-062"],
       "references": [],
       "capabilities": {
         "inputs": ["TASK_ID", "TASK_NAME", "TASK_INSTRUCTIONS", "DELIVERABLES_LIST", "ACCEPTANCE_CRITERIA"],
@@ -148,6 +153,9 @@
       "status": "active",
       "tier": 1,
       "token_budget": 8000,
+      "protocol": "decomposition",
+      "loomStage": "decomposition",
+      "adrRefs": ["ADR-066", "ADR-073"],
       "references": ["skills/ct-epic-architect/references/bug-epic-example.md", "skills/ct-epic-architect/references/commands.md", "skills/ct-epic-architect/references/feature-epic-example.md"],
       "capabilities": {
         "inputs": ["TASK_ID", "FEATURE_NAME", "EPIC_ID", "SESSION_ID"],
@@ -176,6 +184,9 @@
       "status": "active",
       "tier": 1,
       "token_budget": 8000,
+      "protocol": "research",
+      "loomStage": "research",
+      "adrRefs": ["ADR-023", "ADR-070"],
       "references": [],
       "capabilities": {
         "inputs": ["TASK_ID", "TOPIC", "RESEARCH_QUESTIONS"],
@@ -204,6 +215,9 @@
       "status": "active",
       "tier": 1,
       "token_budget": 8000,
+      "protocol": "specification",
+      "loomStage": "specification",
+      "adrRefs": ["ADR-014", "ADR-023"],
       "references": [],
       "capabilities": {
         "inputs": ["TASK_ID", "SPEC_NAME", "spec_topic"],
@@ -232,6 +246,9 @@
       "status": "active",
       "tier": 1,
       "token_budget": 6000,
+      "protocol": "validation",
+      "loomStage": "validation",
+      "adrRefs": ["ADR-051", "ADR-023"],
       "references": [],
       "capabilities": {
         "inputs": ["TASK_ID", "VALIDATION_TARGET", "VALIDATION_CRITERIA"],
@@ -239,7 +256,7 @@
         "dependencies": [],
         "dispatch_triggers": ["validate", "verify", "check compliance", "audit"],
         "compatible_subagent_types": ["general-purpose"],
-        "chains_to": [],
+        "chains_to": ["ct-ivt-looper"],
         "dispatch_keywords": {
           "primary": ["validate", "verify", "audit", "compliance"],
           "secondary": ["check", "conformance", "standards", "requirements"]
@@ -400,6 +417,9 @@
       "status": "active",
       "tier": 2,
       "token_budget": 6000,
+      "protocol": "contribution",
+      "loomStage": "contribution",
+      "adrRefs": ["ADR-015", "ADR-053"],
       "references": [],
       "capabilities": {
         "inputs": ["TASK_ID", "contribution_type", "context"],
@@ -484,7 +504,9 @@
       "status": "active",
       "tier": 2,
       "token_budget": 8000,
-      "protocol": "architecture-decision",
+      "protocol": "architecture_decision",
+      "loomStage": "architecture_decision",
+      "adrRefs": ["ADR-053", "ADR-070"],
       "references": [
         "skills/ct-adr-recorder/references/cascade.md",
         "skills/ct-adr-recorder/references/examples.md"
@@ -523,6 +545,8 @@
       "tier": 2,
       "token_budget": 10000,
       "protocol": "testing",
+      "loomStage": "testing",
+      "adrRefs": ["ADR-051", "ADR-061"],
       "references": [
         "skills/ct-ivt-looper/references/escalation.md",
         "skills/ct-ivt-looper/references/frameworks.md",
@@ -562,6 +586,8 @@
       "tier": 2,
       "token_budget": 6000,
       "protocol": "consensus",
+      "loomStage": "consensus",
+      "adrRefs": ["ADR-015", "ADR-023"],
       "references": ["skills/ct-consensus-voter/references/matrix-examples.md"],
       "capabilities": {
         "inputs": ["task-id", "question", "candidate-options"],
@@ -597,6 +623,8 @@
       "tier": 2,
       "token_budget": 8000,
       "protocol": "release",
+      "loomStage": "release",
+      "adrRefs": ["ADR-053", "ADR-063", "ADR-065"],
       "references": [
         "skills/ct-release-orchestrator/references/composition.md",
         "skills/ct-release-orchestrator/references/release-types.md"