@cleocode/skills 2026.5.82 → 2026.5.84

package/README.md

@@ -72,7 +72,6 @@ yarn add @cleocode/skills
 | Skill | Purpose | Description |
 |-------|---------|-------------|
 | **ct-grade** | Grading | Session quality evaluation |
-| **ct-grade-v2-1** | Grading V2 | Enhanced grading with scenarios |
 | **ct-stickynote** | Notes | Quick ephemeral sticky notes |
 
 ### Integration Skills

package/package.json

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

package/profiles/recommended.json

@@ -2,6 +2,6 @@
   "name": "recommended",
   "description": "Full LOOM (RCASD-IVTR+C pipeline) skills for epic-driven development",
   "extends": "core",
-  "skills": ["ct-epic-architect", "ct-research-agent", "ct-spec-writer", "ct-validator", "loom"],
+  "skills": ["ct-council", "ct-epic-architect", "ct-research-agent", "ct-spec-writer", "ct-validator", "loom"],
   "includeProtocols": ["research", "consensus", "specification", "decomposition", "validation", "adr"]
 }

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).