@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-validator/references/validation-modes.md

@@ -0,0 +1,185 @@
+# Validation Modes
+
+`ct-validator` operates in four distinct modes. Each has different inputs,
+different verification mechanics, and different report shape. The mode is
+determined by the target type — the spawn prompt or task body MUST make
+the mode explicit.
+
+## Mode 1: Schema Validation
+
+**Target.** A data instance (JSON, YAML, TOML, etc.) checked against a
+schema (JSON Schema, Zod, drizzle/zod, ajv, JSON-LD).
+
+**Inputs.**
+- One or more data files (or stdin)
+- A schema (file path or inline)
+- Optional: schema dialect (draft-07, draft-2020-12, etc.)
+
+**Mechanics.** Run the schema engine; collect every violation; classify
+by JSON Path. Do not short-circuit on first failure — exhaustive
+reporting is the whole value-add.
+
+**Tool examples.**
+
+```bash
+# AJV (Node)
+npx ajv validate -s schema.json -d data.json --spec=draft7
+
+# Zod (Node, via project's contracts)
+node -e "
+  import { Schema } from '@cleocode/contracts';
+  const result = Schema.safeParse(JSON.parse(input));
+  if (!result.success) console.log(JSON.stringify(result.error.format()));
+"
+
+# jsonschema (Python)
+python -m jsonschema -i data.json schema.json
+```
+
+**Report shape.** Each violation gets file + JSON Path + violated keyword
++ actual value + expected. Group by file when validating many instances.
+
+## Mode 2: Code Compliance
+
+**Target.** A code change (PR, diff, or working-tree state) checked
+against project standards — lint rules, style guide, naming conventions,
+import boundaries, type discipline.
+
+**Inputs.**
+- A diff (or branch comparison)
+- The project's lint/format configs (biome.json, .eslintrc, clippy.toml)
+- The relevant AGENTS.md / ADR rules
+
+**Mechanics.** Run each tool; collect findings; classify by severity.
+Aggregate the toolchain (biome + tsc + project-specific rules) into a
+single report.
+
+**Tool examples.**
+
+```bash
+# Biome (lint + format in one)
+pnpm biome check . --reporter=json
+
+# TypeScript strict
+pnpm exec tsc -b --pretty false
+
+# Custom AGENTS.md rule checks
+grep -rn "catch (err: unknown)" packages/ --include='*.ts'
+grep -rn ": any\b" packages/ --include='*.ts'
+
+# Package-boundary check
+find packages -name "*.ts" -exec grep -l "../../../" {} \;
+```
+
+**Report shape.** Each finding gets file + line + rule + severity + fix
+suggestion. The AGENTS.md "INSTANT REJECTION" anti-patterns get
+`critical` severity; biome warnings get `warning` severity.
+
+## Mode 3: Document Validation
+
+**Target.** A markdown document (spec, ADR, agent-output, skill) checked
+against a structural standard — required sections, frontmatter, link
+validity, style guide.
+
+**Inputs.**
+- The document(s) under validation
+- The structural standard (e.g., "every spec MUST have RFC 2119
+  boilerplate, REQ-NNN numbered requirements, and a Compliance section")
+- The CLEO style guide (`packages/skills/skills/_shared/cleo-style-guide.md`)
+
+**Mechanics.** Parse the document; check section presence; validate
+links; scan for placeholder text; verify formatting.
+
+**Tool examples.**
+
+```bash
+# Use the ct-skill-validator scripts as a model
+python packages/skills/skills/ct-skill-validator/scripts/validate.py <skill-dir>
+python packages/skills/skills/ct-skill-validator/scripts/audit_body.py <skill-dir>
+
+# Generic markdown link check
+markdown-link-check docs/specs/*.md
+
+# Section presence check (ad-hoc)
+for f in docs/specs/*.md; do
+  grep -q "^## Compliance" "$f" || echo "FAIL: $f missing Compliance"
+  grep -q "RFC 2119" "$f" || echo "FAIL: $f missing RFC 2119 boilerplate"
+done
+```
+
+**Report shape.** Each finding gets file + section/line + violated rule
++ fix suggestion. Document-mode reports are the most useful when paired
+with traceability — see Mode 4.
+
+## Mode 4: Protocol Compliance
+
+**Target.** An implementation checked against its specification — the
+spec defines REQ-NNN, the implementation MUST satisfy each.
+
+**Inputs.**
+- The specification document (with traceability matrix)
+- The implementation source
+- The test suite (each REQ should have a verifying test)
+
+**Mechanics.** For each REQ in the matrix, run the verifying test;
+record pass/fail; record any REQs that lack a verifying test. Compute
+compliance percentage.
+
+**Tool examples.**
+
+```bash
+# Run the specific test for each REQ
+pnpm vitest run --testNamePattern="REQ-001|REQ-002|REQ-003"
+
+# Extract REQ→test map from the spec's traceability matrix
+grep -E "^\| REQ-" docs/specs/foo-spec.md | awk -F'|' '{print $2, "->", $4}'
+
+# Detect REQs without verification
+grep -E "^\| REQ-.*\| \(TODO" docs/specs/foo-spec.md
+```
+
+**Report shape.** Compliance percentage + per-REQ pass/fail + list of
+unverified REQs. This is the input to release-gate decisions.
+
+## Mode Selection Cheat Sheet
+
+| Signal in task description | Mode |
+|----------------------------|------|
+| "validate this JSON against schema X" | Schema |
+| "check the PR for style violations" | Code |
+| "review this spec for completeness" | Document |
+| "verify the implementation satisfies the spec" | Protocol |
+| "audit the release pipeline against ADR-065" | Protocol |
+| "lint the changes" | Code |
+| "validate the LAFS envelope" | Schema |
+| "review the agent-output for style guide compliance" | Document |
+
+## Mode Composition
+
+A single task may chain modes. Example: "validate the new release-plan
+implementation."
+
+1. Mode 3 (Document) — does `docs/specs/release-plan-spec.md` have
+   RFC 2119 boilerplate, numbered REQs, traceability matrix, compliance
+   section?
+2. Mode 4 (Protocol) — does the implementation pass each REQ's test?
+3. Mode 2 (Code) — does the implementation's diff pass lint + typecheck?
+4. Mode 1 (Schema) — do the LAFS envelopes the new code emits validate
+   against the contract schema?
+
+When composing, run the modes in this order — document → protocol →
+code → schema. Each later mode assumes the earlier modes have passed,
+so they bail early on irrelevant failures.
+
+## Output Per Mode
+
+| Mode | Status fields | Key metric |
+|------|---------------|------------|
+| Schema | `status: PASS|FAIL`, `violations: [...]` | violation count |
+| Code | `status: PASS|FAIL`, `findings: [...]` | finding count by severity |
+| Document | `status: PASS|FAIL`, `sections_missing: [...]` | missing-section count |
+| Protocol | `status: PASS|PARTIAL|FAIL`, `compliance: X%`, `unverified: [...]` | compliance percentage |
+
+All modes share the canonical report scaffold in SKILL.md — `## Summary`,
+`## Checklist Results`, `## Issues Found`, `## Remediation`. Only the
+content differs.

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,7 +122,16 @@
       "status": "active",
       "tier": 0,
       "token_budget": 8000,
-      "references": [],
+      "protocol": "implementation",
+      "loomStage": "implementation",
+      "adrRefs": ["ADR-070", "ADR-062"],
+      "references": [
+        "skills/ct-task-executor/references/implementation-patterns.md",
+        "skills/ct-task-executor/references/acceptance-criteria-mapping.md",
+        "skills/ct-task-executor/references/evidence-and-gates.md",
+        "skills/ct-task-executor/references/common-failures.md",
+        "skills/ct-task-executor/references/anti-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["TASK_ID", "TASK_NAME", "TASK_INSTRUCTIONS", "DELIVERABLES_LIST", "ACCEPTANCE_CRITERIA"],
         "outputs": ["deliverables", "manifest-entry"],
@@ -148,6 +159,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,7 +190,15 @@
       "status": "active",
       "tier": 1,
       "token_budget": 8000,
-      "references": [],
+      "protocol": "research",
+      "loomStage": "research",
+      "adrRefs": ["ADR-023", "ADR-070"],
+      "references": [
+        "skills/ct-research-agent/references/triggers-and-routing.md",
+        "skills/ct-research-agent/references/source-strategy.md",
+        "skills/ct-research-agent/references/citation-and-evidence.md",
+        "skills/ct-research-agent/references/anti-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["TASK_ID", "TOPIC", "RESEARCH_QUESTIONS"],
         "outputs": ["research-file", "manifest-entry"],
@@ -204,7 +226,15 @@
       "status": "active",
       "tier": 1,
       "token_budget": 8000,
-      "references": [],
+      "protocol": "specification",
+      "loomStage": "specification",
+      "adrRefs": ["ADR-014", "ADR-023"],
+      "references": [
+        "skills/ct-spec-writer/references/rfc2119-language.md",
+        "skills/ct-spec-writer/references/spec-templates.md",
+        "skills/ct-spec-writer/references/traceability-matrix.md",
+        "skills/ct-spec-writer/references/anti-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["TASK_ID", "SPEC_NAME", "spec_topic"],
         "outputs": ["specification-file", "manifest-entry"],
@@ -232,14 +262,22 @@
       "status": "active",
       "tier": 1,
       "token_budget": 6000,
-      "references": [],
+      "protocol": "validation",
+      "loomStage": "validation",
+      "adrRefs": ["ADR-051", "ADR-023"],
+      "references": [
+        "skills/ct-validator/references/validation-modes.md",
+        "skills/ct-validator/references/schema-checking.md",
+        "skills/ct-validator/references/compliance-reports.md",
+        "skills/ct-validator/references/anti-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["TASK_ID", "VALIDATION_TARGET", "VALIDATION_CRITERIA"],
         "outputs": ["validation-report", "manifest-entry"],
         "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"]
@@ -288,7 +326,12 @@
       "status": "active",
       "tier": 2,
       "token_budget": 8000,
-      "references": [],
+      "references": [
+        "skills/ct-documentor/references/chain-orchestration.md",
+        "skills/ct-documentor/references/doc-types-and-templates.md",
+        "skills/ct-documentor/references/style-coordination.md",
+        "skills/ct-documentor/references/anti-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["TASK_ID", "documentation_topic"],
         "outputs": ["documentation-file", "manifest-entry", "review-report"],
@@ -316,7 +359,11 @@
       "status": "active",
       "tier": 2,
       "token_budget": 6000,
-      "references": [],
+      "references": [
+        "skills/ct-docs-lookup/references/ctx7-workflow.md",
+        "skills/ct-docs-lookup/references/library-id-resolution.md",
+        "skills/ct-docs-lookup/references/version-specific-docs.md"
+      ],
       "capabilities": {
         "inputs": ["library_name", "query", "version"],
         "outputs": ["documentation-content", "code-examples"],
@@ -344,7 +391,11 @@
       "status": "active",
       "tier": 2,
       "token_budget": 6000,
-      "references": [],
+      "references": [
+        "skills/ct-docs-write/references/cleo-style-guide.md",
+        "skills/ct-docs-write/references/markdown-patterns.md",
+        "skills/ct-docs-write/references/audience-targeting.md"
+      ],
       "capabilities": {
         "inputs": ["file_path", "content_topic", "audience"],
         "outputs": ["documentation-file", "markdown-content"],
@@ -372,7 +423,11 @@
       "status": "active",
       "tier": 2,
       "token_budget": 6000,
-      "references": [],
+      "references": [
+        "skills/ct-docs-review/references/style-violations.md",
+        "skills/ct-docs-review/references/pr-review-mode.md",
+        "skills/ct-docs-review/references/inline-comment-patterns.md"
+      ],
       "capabilities": {
         "inputs": ["file_path", "pr_url", "diff_content"],
         "outputs": ["review-comments", "style-violations"],
@@ -400,6 +455,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 +542,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 +583,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 +624,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 +661,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"