@cleocode/skills 2026.4.14 → 2026.4.16

package/package.json

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

package/skills/ct-grade/SKILL.md

@@ -1,7 +1,21 @@
 ---
 name: ct-grade
-description: Session grading for agent behavioral analysis. Use when evaluating agent session quality, running grade scenarios, or interpreting grade results. Triggers on grading tasks, session quality checks, or behavioral analysis needs.
-version: 1.0.0
+description: >-
+  CLEO session grading and A/B behavioral analysis with token tracking. Evaluates agent
+  session quality via a 5-dimension rubric (S1 session discipline, S2 discovery efficiency,
+  S3 task hygiene, S4 error protocol, S5 progressive disclosure). Supports three modes:
+  (1) scenario — run playbook scenarios S1-S5 via CLI; (2) ab — blind A/B
+  comparison of different CLI configurations for same domain operations with token cost
+  measurement; (3) blind — spawn two agents with different configurations, blind-comparator
+  picks winner, analyzer produces recommendation. Use when grading agent sessions, running
+  grade playbook scenarios, comparing behavioral differences, measuring token
+  usage across configurations, or performing multi-run blind A/B evaluation with statistical
+  analysis and comparative report. Triggers on: grade session, evaluate agent behavior,
+  A/B test CLEO configurations, run grade scenario, token usage analysis, behavioral rubric,
+  protocol compliance scoring.
+version: 2.1.0
+argument-hint: "[mode=scenario|ab|blind] [scenario=s1-s5|all] [runs=N] [session-id=<id>]"
+allowed-tools: ["Bash(python *)", "Bash(cleo-dev *)", "Bash(cleo *)", "Bash(kill *)", "Bash(lsof *)", "Agent", "Read", "Write", "Glob"]
 tier: 2
 core: false
 category: quality

package/skills/ct-grade-v2-1/MIGRATION.md

@@ -0,0 +1,28 @@
+---
+# MIGRATION NOTICE — ct-grade-v2-1
+
+This directory is a **decommissioned staging copy** of `ct-grade` v2.1.
+
+## Status
+
+**Superseded.** All content has been merged into `packages/skills/skills/ct-grade/`.
+
+## What Changed (T429 skill dedupe)
+
+- `ct-grade-v2-1/SKILL.md` description, `argument-hint`, `allowed-tools`, and version
+  (2.1.0) were promoted into `ct-grade/SKILL.md`.
+- `ct-grade-v2-1/manifest-entry.json` remains here as an archived snapshot; the
+  canonical manifest entry lives in `packages/skills/skills/manifest.json` under name
+  `ct-grade`.
+- The `grade-viewer/` tooling in this directory was already reachable from `ct-grade/`
+  via its `agents/` and `evals/` directories. No content was lost.
+
+## Migration Date
+
+2026-04-08 — T429 hygiene wave, epic T382.
+
+## Action Required
+
+None. Do NOT load this skill. Use `ct-grade` instead.
+If you need the A/B or blind-compare modes documented here, they are now part of
+`ct-grade`'s SKILL.md description and invocation modes.

package/skills/ct-master-tac/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ct-master-tac
+description: >-
+  Master Tactical Bundle for CleoOS autonomous execution. Installs the complete
+  primitive library needed to run the full agentic execution layer on a fresh CleoOS
+  install: 12 CANT protocol files (research, consensus, architecture-decision,
+  specification, decomposition, implementation, validation, testing, contribution,
+  release, artifact-publish, provenance), the canonical platform team definition, and
+  the skills manifest entry. Use when bootstrapping a new CleoOS project, verifying that
+  all protocol primitives are present, or recovering a broken protocol tree. Triggers on:
+  "install master tac", "bootstrap protocols", "tools.skill.install ct-master-tac",
+  "verify protocol bundle", "repair protocol files", "fresh CleoOS install".
+version: 1.0.0
+tier: 1
+core: false
+category: meta
+protocol: null
+argument-hint: "[--verify] [--force]"
+allowed-tools: ["Read", "Write", "Bash(cp *)", "Bash(ls *)", "Bash(mkdir *)", "Bash(test *)"]
+dependencies:
+  - ct-cleo
+sharedResources:
+  - subagent-protocol-base
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+install-hook: "tools.skill.install ct-master-tac"
+---
+
+# ct-master-tac — Master Tactical Bundle
+
+> **Provenance**: @task T430, @epic T382, @umbrella T377
+> **Bundle version**: 1.0.0 — ships with CleoOS v2026.4.x
+
+The Master TAC (Tactical Asset Cache) plugin bundles every protocol primitive the
+autonomous execution layer requires. After `tools.skill.install ct-master-tac`, a
+fresh CleoOS install has batteries-included support for the full RCASD-IVTR+C
+lifecycle.
+
+---
+
+## What's Inside
+
+### 12 CANT Protocol Files (`bundled/protocols/`)
+
+| File | ID | Stage | Skill |
+|------|----|-------|-------|
+| `research.cant` | RSCH | research | ct-research-agent |
+| `consensus.cant` | CONS | consensus | ct-consensus-voter |
+| `architecture-decision.cant` | ADR | architecture-decision | ct-adr-recorder |
+| `specification.cant` | SPEC | specification | ct-spec-writer |
+| `decomposition.cant` | DCMP | decomposition | ct-epic-architect |
+| `implementation.cant` | IMPL | implementation | ct-task-executor |
+| `validation.cant` | VALID | validation | ct-validator |
+| `testing.cant` | TEST | testing | ct-ivt-looper |
+| `contribution.cant` | CONT | cross-cutting | ct-contribution |
+| `release.cant` | REL | release | ct-release-orchestrator |
+| `artifact-publish.cant` | ART | release | ct-artifact-publisher |
+| `provenance.cant` | PROV | release | ct-provenance-keeper |
+
+### Platform Team (`bundled/teams/platform.cant`)
+
+Canonical 3-tier team definition with planning-lead, engineering-lead, and
+validation-lead. Mirrors the `.cleo/teams.cant` seed from a standard CleoOS init.
+
+---
+
+## Install Behaviour
+
+```bash
+tools.skill.install ct-master-tac
+```
+
+The install hook:
+
+1. Copies `bundled/protocols/*.cant` to
+   `packages/core/src/validation/protocols/cant/` (skips files that already exist
+   unless `--force` is provided).
+2. Copies `bundled/teams/platform.cant` to `.cleo/teams.cant` (skips if exists).
+3. Verifies that all 12 protocol files are present and parseable.
+4. Emits an install summary to stdout.
+
+Running install a second time is a no-op (idempotent).
+
+---
+
+## Verify Mode
+
+```bash
+tools.skill.install ct-master-tac --verify
+```
+
+Read-only. Checks that all bundled files are present at their target locations and
+reports any missing or mismatched files without writing anything.
+
+---
+
+## Plugin Boundary (§11 criteria)
+
+This plugin meets all three §11 criteria from `docs/specs/CLEO-OPERATION-CONSTITUTION.md`:
+
+- **(a)** Requires reading protocol CANT files managed outside the core CLI binary.
+- **(b)** Reads `bundled/` assets not managed by the CLEO core package.
+- **(c)** Removing it from core does not break any mandatory agent workflow — it is
+  a bootstrap/recovery utility only.
+
+---
+
+## Upgrade Path
+
+When new protocol files are added, bump `version` in this SKILL.md and
+`manifest.json`, add the new `.cant` file to `bundled/protocols/`, and update the
+`manifest.json` `files` array. The install hook will copy the new file on next run.

package/skills/ct-master-tac/__tests__/install.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Install verification tests for the ct-master-tac plugin (T431).
+ *
+ * Asserts:
+ * - SKILL.md has valid YAML frontmatter
+ * - manifest.json parses correctly and references the correct files
+ * - All files referenced in manifest.json `files` array exist under bundled/
+ * - Install is idempotent (second run produces no additional writes)
+ * - Bundle contains exactly 12 protocol files + 1 platform team file
+ *
+ * @task T431
+ * @epic T382
+ * @umbrella T377
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const thisFile = fileURLToPath(import.meta.url);
+/** Absolute path to the ct-master-tac root directory */
+const skillRoot = resolve(dirname(thisFile), '..');
+
+/**
+ * Parse YAML frontmatter from a Markdown file.
+ * Returns the raw frontmatter string between the opening and closing `---`.
+ */
+function extractFrontmatter(content: string): string | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content);
+  return match ? match[1] : null;
+}
+
+/**
+ * Minimal frontmatter key extractor — no external deps, just key: value lines.
+ */
+function parseFrontmatterKeys(fm: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const line of fm.split('\n')) {
+    const m = /^(\w[\w-]*):\s*(.*)$/.exec(line.trimEnd());
+    if (m) {
+      result[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Mock install helper for idempotency test
+// ---------------------------------------------------------------------------
+
+interface InstallResult {
+  copiedFiles: string[];
+  skippedFiles: string[];
+}
+
+/**
+ * Simulated install helper — copies bundled/ files to target paths.
+ * Returns lists of copied and skipped files so idempotency can be verified.
+ */
+function mockInstall(
+  manifestFiles: string[],
+  alreadyInstalled: Set<string>,
+): InstallResult {
+  const copiedFiles: string[] = [];
+  const skippedFiles: string[] = [];
+
+  for (const f of manifestFiles) {
+    if (alreadyInstalled.has(f)) {
+      skippedFiles.push(f);
+    } else {
+      copiedFiles.push(f);
+    }
+  }
+
+  return { copiedFiles, skippedFiles };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ct-master-tac plugin (T431)', () => {
+  describe('SKILL.md frontmatter', () => {
+    const skillMdPath = join(skillRoot, 'SKILL.md');
+
+    it('SKILL.md exists', () => {
+      expect(existsSync(skillMdPath)).toBe(true);
+    });
+
+    it('SKILL.md contains valid frontmatter delimiters', () => {
+      const content = readFileSync(skillMdPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      expect(fm).not.toBeNull();
+    });
+
+    it('frontmatter has required fields: name, description, version, tier', () => {
+      const content = readFileSync(skillMdPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      expect(fm).not.toBeNull();
+      const keys = parseFrontmatterKeys(fm!);
+      expect(keys['name']).toBe('ct-master-tac');
+      expect(keys['description'] ?? keys['description']).toBeTruthy();
+      expect(keys['version']).toBeTruthy();
+      expect(keys['tier']).toBeTruthy();
+    });
+  });
+
+  describe('manifest.json', () => {
+    const manifestPath = join(skillRoot, 'manifest.json');
+    let manifest: Record<string, unknown>;
+
+    it('manifest.json exists', () => {
+      expect(existsSync(manifestPath)).toBe(true);
+    });
+
+    it('manifest.json parses as valid JSON', () => {
+      const raw = readFileSync(manifestPath, 'utf-8');
+      expect(() => {
+        manifest = JSON.parse(raw) as Record<string, unknown>;
+      }).not.toThrow();
+    });
+
+    it('manifest has required top-level keys', () => {
+      const raw = readFileSync(manifestPath, 'utf-8');
+      manifest = JSON.parse(raw) as Record<string, unknown>;
+      expect(manifest['name']).toBe('ct-master-tac');
+      expect(manifest['version']).toBeTruthy();
+      expect(Array.isArray(manifest['files'])).toBe(true);
+    });
+
+    it('files array contains exactly 13 entries (12 protocols + 1 team)', () => {
+      const raw = readFileSync(manifestPath, 'utf-8');
+      manifest = JSON.parse(raw) as Record<string, unknown>;
+      const files = manifest['files'] as string[];
+      expect(files).toHaveLength(13);
+    });
+
+    it('files array contains at least 12 protocol entries', () => {
+      const raw = readFileSync(manifestPath, 'utf-8');
+      manifest = JSON.parse(raw) as Record<string, unknown>;
+      const files = manifest['files'] as string[];
+      const protocolFiles = files.filter((f) => f.startsWith('bundled/protocols/'));
+      expect(protocolFiles.length).toBeGreaterThanOrEqual(12);
+    });
+
+    it('files array contains platform team entry', () => {
+      const raw = readFileSync(manifestPath, 'utf-8');
+      manifest = JSON.parse(raw) as Record<string, unknown>;
+      const files = manifest['files'] as string[];
+      expect(files).toContain('bundled/teams/platform.cant');
+    });
+  });
+
+  describe('bundled files exist', () => {
+    it('all files referenced in manifest.json exist under bundled/', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      const missingFiles: string[] = [];
+
+      for (const f of manifest.files) {
+        const abs = join(skillRoot, f);
+        if (!existsSync(abs)) {
+          missingFiles.push(f);
+        }
+      }
+
+      expect(missingFiles).toEqual([]);
+    });
+
+    it('each bundled protocol file is non-empty', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      const emptyFiles: string[] = [];
+
+      for (const f of manifest.files.filter((f) =>
+        f.startsWith('bundled/protocols/'),
+      )) {
+        const abs = join(skillRoot, f);
+        const content = readFileSync(abs, 'utf-8');
+        if (content.trim().length === 0) {
+          emptyFiles.push(f);
+        }
+      }
+
+      expect(emptyFiles).toEqual([]);
+    });
+
+    it('each bundled protocol file has CANT frontmatter (kind: protocol)', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      const badFiles: string[] = [];
+
+      for (const f of manifest.files.filter((f) =>
+        f.startsWith('bundled/protocols/'),
+      )) {
+        const abs = join(skillRoot, f);
+        const content = readFileSync(abs, 'utf-8');
+        if (!content.includes('kind: protocol')) {
+          badFiles.push(f);
+        }
+      }
+
+      expect(badFiles).toEqual([]);
+    });
+  });
+
+  describe('idempotent install (mock)', () => {
+    it('first install copies all 13 files', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      const already = new Set<string>();
+
+      const result = mockInstall(manifest.files, already);
+      expect(result.copiedFiles).toHaveLength(13);
+      expect(result.skippedFiles).toHaveLength(0);
+    });
+
+    it('second install (files already present) skips all 13 files', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      // Simulate first install — all files now "present"
+      const already = new Set<string>(manifest.files);
+
+      const result = mockInstall(manifest.files, already);
+      expect(result.copiedFiles).toHaveLength(0);
+      expect(result.skippedFiles).toHaveLength(13);
+    });
+
+    it('partial install (3 missing) copies only missing files', () => {
+      const raw = readFileSync(join(skillRoot, 'manifest.json'), 'utf-8');
+      const manifest = JSON.parse(raw) as { files: string[] };
+      // 10 of 13 already installed
+      const already = new Set<string>(manifest.files.slice(0, 10));
+
+      const result = mockInstall(manifest.files, already);
+      expect(result.copiedFiles).toHaveLength(3);
+      expect(result.skippedFiles).toHaveLength(10);
+    });
+  });
+
+  describe('bundle completeness', () => {
+    const EXPECTED_PROTOCOLS = [
+      'research.cant',
+      'consensus.cant',
+      'architecture-decision.cant',
+      'specification.cant',
+      'decomposition.cant',
+      'implementation.cant',
+      'validation.cant',
+      'testing.cant',
+      'contribution.cant',
+      'release.cant',
+      'artifact-publish.cant',
+      'provenance.cant',
+    ] as const;
+
+    for (const protocol of EXPECTED_PROTOCOLS) {
+      it(`bundled/protocols/${protocol} exists`, () => {
+        expect(
+          existsSync(join(skillRoot, 'bundled', 'protocols', protocol)),
+        ).toBe(true);
+      });
+    }
+
+    it('bundled/teams/platform.cant exists', () => {
+      expect(existsSync(join(skillRoot, 'bundled', 'teams', 'platform.cant'))).toBe(
+        true,
+      );
+    });
+
+    it('bundle contains exactly 12 CANT protocol files', () => {
+      const protocolFiles = EXPECTED_PROTOCOLS.filter((f) =>
+        existsSync(join(skillRoot, 'bundled', 'protocols', f)),
+      );
+      expect(protocolFiles).toHaveLength(12);
+    });
+  });
+});

package/skills/ct-master-tac/bundled/README.md

@@ -0,0 +1,40 @@
+# ct-master-tac Bundle Contents
+
+> @task T430 @epic T382 @umbrella T377
+> Source: `packages/skills/skills/ct-master-tac/bundled/`
+
+This directory holds the canonical bundle assets shipped with the `ct-master-tac` plugin.
+
+## protocols/
+
+Copies of the 12 CANT protocol files from
+`packages/core/src/validation/protocols/cant/`.
+
+Each file defines a protocol primitive in the RCASD-IVTR+C lifecycle:
+
+| File | ID | RCASD Stage |
+|------|----|-------------|
+| `research.cant` | RSCH | R — Research |
+| `consensus.cant` | CONS | C — Consensus |
+| `architecture-decision.cant` | ADR | A — Architecture Decision |
+| `specification.cant` | SPEC | S — Specification |
+| `decomposition.cant` | DCMP | D — Decomposition |
+| `implementation.cant` | IMPL | I — Implementation |
+| `validation.cant` | VALID | V — Validation |
+| `testing.cant` | TEST | T — Testing |
+| `contribution.cant` | CONT | cross-cutting |
+| `release.cant` | REL | R — Release |
+| `artifact-publish.cant` | ART | release sub-protocol |
+| `provenance.cant` | PROV | release sub-protocol |
+
+## teams/
+
+| File | Description |
+|------|-------------|
+| `platform.cant` | Canonical 3-tier CleoOS platform team seed |
+
+## Maintenance
+
+When protocol files change in `packages/core/src/validation/protocols/cant/`,
+re-copy them here and bump the version in `ct-master-tac/manifest.json` and
+`ct-master-tac/SKILL.md`.

package/skills/ct-master-tac/bundled/protocols/architecture-decision.cant

@@ -0,0 +1,90 @@
+---
+kind: protocol
+version: 1.0.0
+id: ADR
+title: "Architecture Decision Record Protocol"
+status: active
+type: conditional
+audience: "llm-agent, orchestrator"
+tags: "adr, architecture, decisions"
+skillRef: ct-adr-recorder
+lastUpdated: 2026-04-08
+enforcement: advisory
+stage: "architecture-decision"
+consult-when: "Recording a formal architecture decision after consensus reaches PROVEN verdict; superseding an existing ADR; any task carrying --protocol adr flag"
+input:
+  consensus_manifest_id: "string — ID of the originating consensus manifest (required)"
+  decision_title: "string — short title for the ADR"
+  options_evaluated: "string[] — options that were considered"
+output:
+  adr_id: "string — canonical ADR identifier (ADR-NNN)"
+  status: "proposed | accepted | superseded"
+  stored_at: "string — path to .cleo/adrs/<id>.md and decisions table row"
+---
+
+# Architecture Decision Record (ADR) Protocol
+#
+# Provenance: @task T4798 (ADR-006 Implementation), @task T428 (gap patch)
+# Type: Conditional Protocol
+# Stage: RCADSD - A (ADR)
+# Max Active: 3 protocols (including base)
+#
+# Trigger Conditions
+#
+# This protocol activates when the task involves:
+#   Decision Recording: "decision", "adr", "architecture decision"
+#   Stage Transition: "after consensus", "begin adr"
+#   Formalization: "lock in decision", "formalize choice", "decide"
+#   Architectural Shift: "pivot", "new architecture", "supersede"
+#   Record Creation: "create adr", "write adr", "record decision"
+#
+# Explicit Override: --protocol adr flag on task creation.
+#
+# Requirements (RFC 2119)
+#
+# MUST:
+#   ADR-001: MUST be generated from an accepted Consensus report verdict
+#   ADR-002: MUST include a consensus_manifest_id linking to its originating consensus
+#   ADR-003: MUST require explicit HITL approval to transition from proposed to accepted
+#   ADR-004: MUST include Context, Options Evaluated, Decision, Rationale, and Consequences sections
+#   ADR-005: MUST trigger downstream invalidation if superseded
+#   ADR-006: MUST be stored in the canonical decisions SQLite table via Drizzle ORM
+#   ADR-007: MUST set agent_type: "decision" in manifest entry
+#   ADR-008: MUST block the Specification stage until the ADR status is accepted
+#
+# SHOULD:
+#   ADR-010: SHOULD document the exact data structures or schema changes required
+#   ADR-011: SHOULD explicitly list which existing ADRs are superseded, with rationale
+#   ADR-012: SHOULD flag known technical debt introduced by the decision
+#   ADR-013: SHOULD document rejected alternatives with rationale for rejection
+#
+# MAY:
+#   ADR-020: MAY include diagrams (Mermaid) illustrating the architectural shift
+#   ADR-021: MAY link to external prior art or research documents
+#   ADR-022: MAY reference related ADRs that are not superseded but contextually relevant
+#
+# Decision Status Lifecycle:
+#   proposed -> accepted -> superseded
+#                       \-> deprecated
+#
+# HITL Gate:
+#   1. Agent drafts the ADR based on consensus verdict
+#   2. Status is set to proposed
+#   3. Pipeline pauses (HANDOFF_REQUIRED - exit code 65)
+#   4. Human reviews the proposed ADR
+#   5. If approved, status transitions to accepted
+#   6. Only an accepted ADR unlocks the Specification stage
+#
+# Exit Codes:
+#   65: HANDOFF_REQUIRED - ADR drafted as proposed, awaiting HITL acceptance
+#   84: PROVENANCE_REQUIRED - Attempted to create ADR without linked Consensus report
+#   18: CASCADE_FAILED - Downstream work blocked because governing ADR was superseded
+#
+# Anti-Patterns:
+#   - Creating ADR without consensus (decisions lack evidence foundation)
+#   - Auto-accepting without HITL review (bypasses human oversight gate)
+#   - Omitting downstream impact section (future implementers unaware of cascade)
+#   - Superseding without updating specs (creates orphaned specifications)
+#   - Using ADR to define implementation requirements (that is Specification's role)
+#   - Storing ADR only as markdown without SQLite record (loses relational queries)
+#   - Skipping rejected alternatives (loses institutional knowledge)