@cleocode/skills 2026.5.82 → 2026.5.84

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",
-    "totalSkills": 21,
-    "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."
+    "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. 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"
@@ -700,6 +728,50 @@
         "requires_session": false,
         "requires_epic": false
       }
+    },
+    {
+      "name": "ct-council",
+      "version": "1.0.0",
+      "description": "Convene \"The Council\" — a 5-advisor, shuffled gate-based peer-review, chairman-synthesis workflow for reviewing a plan, decision, architecture, or piece of work inside the current project. Operates on the current codebase — each advisor grounds their analysis in actual files/commits before opining. Output is validated by scripts/validate.py.",
+      "path": "skills/ct-council",
+      "tags": ["council", "review", "peer-review", "multi-perspective", "stress-test"],
+      "status": "active",
+      "tier": 2,
+      "token_budget": 8000,
+      "references": [
+        "skills/ct-council/references/chairman.md",
+        "skills/ct-council/references/contrarian.md",
+        "skills/ct-council/references/evidence-pack.md",
+        "skills/ct-council/references/examples.md",
+        "skills/ct-council/references/executor.md",
+        "skills/ct-council/references/expansionist.md",
+        "skills/ct-council/references/first-principles.md",
+        "skills/ct-council/references/outsider.md",
+        "skills/ct-council/references/peer-review.md"
+      ],
+      "capabilities": {
+        "inputs": ["proposal", "plan", "architecture-decision", "task-id"],
+        "outputs": ["council-verdict", "advisor-reports", "convergence-report"],
+        "dependencies": [],
+        "dispatch_triggers": [
+          "convene the council",
+          "council review",
+          "run the five advisors",
+          "stress-test this",
+          "get multiple perspectives"
+        ],
+        "compatible_subagent_types": ["general-purpose"],
+        "chains_to": [],
+        "dispatch_keywords": {
+          "primary": ["council", "advisors", "stress-test", "peer-review"],
+          "secondary": ["contrarian", "first-principles", "expansionist", "outsider", "executor", "chairman"]
+        }
+      },
+      "constraints": {
+        "max_context_tokens": 80000,
+        "requires_session": false,
+        "requires_epic": false
+      }
     }
   ]
 }

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

@@ -1,28 +0,0 @@
----
-# 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-grade-v2-1/SKILL.md

@@ -1,235 +0,0 @@
----
-name: ct-grade
-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.
-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"]
----
-
-# ct-grade v2.1 — CLEO Grading and A/B Testing
-
-Session grading and A/B behavioral analysis for CLEO protocol compliance. Three operating modes cover everything from single-session scoring to multi-run blind comparisons between different CLI configurations.
-
-## On Every /ct-grade Invocation
-
-Before parsing arguments, start the grade viewer server:
-
-```bash
-# Kill any existing viewer on port 3119
-lsof -ti :3119 | xargs kill -TERM 2>/dev/null || true
-
-# Start grade viewer in background
-python $CLAUDE_SKILL_DIR/grade-viewer/generate_grade_review.py . \
-  --port 3119 --no-browser &
-echo "Grade viewer: http://localhost:3119"
-```
-
-When user says "end grading", "stop", "done", or "close viewer":
-```bash
-lsof -ti :3119 | xargs kill -TERM 2>/dev/null || true
-echo "Grade viewer stopped."
-```
-
----
-
-## Operating Modes
-
-| Mode | Purpose | Key Output |
-|---|---|---|
-| `scenario` | Run playbook scenarios S1-S5 as graded sessions | GradeResult per scenario |
-| `ab` | Run same domain operations with two configurations, compare | comparison.json + token delta |
-| `blind` | Two agents run same task, blind comparator picks winner | analysis.json + winner |
-
-## Parameters
-
-| Parameter | Values | Default | Description |
-|---|---|---|---|
-| `mode` | `scenario\|ab\|blind` | `scenario` | Operating mode |
-| `scenario` | `s1\|s2\|s3\|s4\|s5\|all` | `all` | Grade playbook scenario(s) to run |
-| `interface` | `cli` | `cli` | Interface to exercise (CLI only) |
-| `domains` | comma list | `tasks,session` | Domains to test in `ab` mode |
-| `runs` | integer | `3` | Runs per configuration for statistical confidence |
-| `session-id` | string | — | Grade a specific existing session (skips execution) |
-| `output-dir` | path | `ab_results/<ts>` | Where to write all run artifacts |
-
-## Quick Start
-
-**Grade an existing session:**
-```
-/ct-grade session-id=<id>
-```
-
-**Run scenario S4 (Full Lifecycle):**
-```
-/ct-grade mode=scenario scenario=s4
-```
-
-**A/B compare two configurations for tasks + session domains (3 runs each):**
-```
-/ct-grade mode=ab domains=tasks,session runs=3
-```
-
-**Full blind A/B test across all scenarios:**
-```
-/ct-grade mode=blind scenario=all runs=3
-```
-
----
-
-## Execution Flow
-
-### Mode: scenario
-
-1. Set up output dir with `python $CLAUDE_SKILL_DIR/scripts/setup_run.py --mode scenario --scenario <id> --output-dir <dir>`
-2. For each scenario, spawn a `scenario-runner` agent:
-   - Agent start: `cleo session start --scope global --name "<scenario-id>" --grade`
-   - Agent executes the scenario operations (see [references/playbook-v2.md](references/playbook-v2.md))
-   - Agent end: `cleo session end`
-   - Agent runs: `ct grade <sessionId>`
-   - Agent saves: `GradeResult` to `<output-dir>/<scenario>/grade.json`
-3. Capture `total_tokens` + `duration_ms` from task notification → `timing.json`
-4. Run: `python $CLAUDE_SKILL_DIR/scripts/generate_report.py --run-dir <dir> --mode scenario`
-
-### Mode: ab
-
-1. Set up run dir with `python $CLAUDE_SKILL_DIR/scripts/setup_run.py --mode ab --output-dir <dir>`
-2. For each target domain, spawn TWO agents in the SAME turn:
-   - **Arm A**: `agents/scenario-runner.md` with configuration A
-   - **Arm B**: `agents/scenario-runner.md` with configuration B
-   - Capture tokens from both task notifications immediately
-3. Pass both outputs to `agents/blind-comparator.md` (does NOT know which configuration is which)
-4. Comparator writes `comparison.json`
-5. Run `python $CLAUDE_SKILL_DIR/scripts/generate_report.py --run-dir <dir> --mode ab`
-
-### Mode: blind
-
-Same as `ab` but configurations may differ (e.g., different session scopes, different agent prompts). The comparator is always blind to configuration identity.
-
----
-
-## Token Capture — MANDATORY
-
-After EVERY Agent task notification, immediately update `timing.json`:
-
-```python
-timing = {
-  "total_tokens": task.total_tokens,     # from task notification — EPHEMERAL
-  "duration_ms": task.duration_ms,       # from task notification
-  "arm": "arm-A",
-  "interface": "cli",
-  "scenario": "s4",
-  "run": 1,
-  "executor_start": start_iso,
-  "executor_end": end_iso,
-}
-# Write to: <output-dir>/<scenario>/arm-<interface>/timing.json
-```
-
-**`total_tokens` is EPHEMERAL** — it cannot be recovered if missed. Capture it immediately.
-
-If running without task notifications (no total_tokens available):
-- Fall back: `output_chars / 3.5` from operations.jsonl (JSON responses)
-- Record `"method": "output_chars_estimate"` in timing.json
-
----
-
-## Grade Rubric Summary
-
-5 dimensions × 20 pts = 100 max. See [references/grade-spec-v2.md](references/grade-spec-v2.md) for full scoring logic.
-
-| Dim | Points | What it measures |
-|---|---|---|
-| S1 Session Discipline | 20 | `session.list` before task ops (+10), `session.end` present (+10) |
-| S2 Discovery Efficiency | 20 | `find:list` ratio ≥80% (+15), `tasks.show` used (+5) |
-| S3 Task Hygiene | 20 | Starts 20, -5 per add without description, -3 if subtask no exists check |
-| S4 Error Protocol | 20 | Starts 20, -5 per unrecovered E_NOT_FOUND, -5 if duplicates |
-| S5 Progressive Disclosure | 20 | `admin.help`/skill lookup (+10), progressive disclosure used (+10) |
-
-**Grade letters:** A>=90, B>=75, C>=60, D>=45, F<45
-
----
-
-## Output Structure
-
-```
-<output-dir>/
-  run-manifest.json          # run config, arms, timing summary
-  report.md                  # human-readable comparative report
-  token-summary.json         # aggregated token stats across all runs
-  <scenario-or-domain>/
-    arm-A/
-      grade.json             # GradeResult (from check.grade)
-      timing.json            # token + duration data
-      operations.jsonl       # operations executed (one per line)
-    arm-B/
-      grade.json
-      timing.json
-      operations.jsonl
-    comparison.json          # blind comparator output
-    analysis.json            # analyzer output
-```
-
----
-
-## Agents
-
-| Agent | Role | Input | Output |
-|---|---|---|---|
-| [agents/scenario-runner.md](agents/scenario-runner.md) | Executes grade scenario | scenario, interface | grade.json, timing.json |
-| [agents/blind-comparator.md](agents/blind-comparator.md) | Blind A/B judge | outputs A and B | comparison.json |
-| [agents/analysis-reporter.md](agents/analysis-reporter.md) | Post-hoc synthesis | all comparison.json | analysis.json |
-
----
-
-## Scripts
-
-```bash
-# Set up run directory and print execution plan
-python $CLAUDE_SKILL_DIR/scripts/setup_run.py --mode <mode> --scenario <s> --output-dir <dir>
-
-# Aggregate token data after runs complete
-python $CLAUDE_SKILL_DIR/scripts/token_tracker.py --run-dir <dir>
-
-# Generate final report (markdown)
-python $CLAUDE_SKILL_DIR/scripts/generate_report.py --run-dir <dir> --mode <mode>
-```
-
----
-
-## Viewers
-
-### Grade Results Viewer (A/B run artifacts) — port 3119
-```bash
-python $CLAUDE_SKILL_DIR/grade-viewer/generate_grade_viewer.py --run-dir <ab-run-dir>
-python $CLAUDE_SKILL_DIR/grade-viewer/generate_grade_viewer.py --run-dir <ab-run-dir> --static results.html
-```
-Shows per-scenario grade cards with dimension bars, A/B comparison tables, token economy stats, blind comparator results, and recommendations. Refreshes on browser reload.
-
-### General Grade Review (GRADES.jsonl browsing) — port 3119
-```bash
-python $CLAUDE_SKILL_DIR/grade-viewer/generate_grade_review.py <workspace>
-python $CLAUDE_SKILL_DIR/grade-viewer/generate_grade_review.py <workspace> --static grade-report.html
-```
-Shows historical grades from GRADES.jsonl, A/B summaries from any workspace subdirectory.
-
----
-
-## CLI Grade Operations
-
-| Command | Description |
-|---------|-------------|
-| `ct grade <sessionId>` | Grade a specific session |
-| `ct grade --list` | List past grade results |
-| `ct session start --scope global --name "<n>" --grade` | Start graded session |
-| `ct session end` | End session |