@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-validator/references/compliance-reports.md

@@ -0,0 +1,199 @@
+# Compliance Reports
+
+The shape, severity calculus, and downstream consumption of the
+validation report. The report is the validator's product — its format
+is rigid because `ct-ivt-looper`, `ct-release-orchestrator`, and HITL
+gates all parse it.
+
+## Canonical Report Scaffold
+
+Every report MUST use this structure. Sections are mandatory; their
+content varies by mode.
+
+```markdown
+# Validation Report: {{VALIDATION_TARGET}}
+
+**Mode**: schema | code | document | protocol
+**Date**: {{DATE}}
+**Validator**: ct-validator v2.0.0
+
+---
+
+## Summary
+
+- **Status**: PASS | PARTIAL | FAIL
+- **Compliance**: {X}%
+- **Critical Issues**: {N}
+- **Warnings**: {N}
+- **Suggestions**: {N}
+
+## Checklist Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| {CHECK_1} | PASS/FAIL | {Details} |
+| {CHECK_2} | PASS/FAIL | {Details} |
+
+## Issues Found
+
+### Critical
+{List or "None"}
+
+### Warnings
+{List or "None"}
+
+### Suggestions
+{List or "None"}
+
+## Remediation
+
+{Required fixes if FAIL/PARTIAL, or "No remediation required" if PASS}
+
+## Trace
+
+- Target: {file/spec/diff path}
+- Tooling: {versions of tools run}
+- Reproducer: {one command that re-runs this report}
+```
+
+The Trace section is essential — without a reproducer, the report
+cannot be re-run later to confirm a remediation worked.
+
+## Status Calculus
+
+| Mode | PASS | PARTIAL | FAIL |
+|------|------|---------|------|
+| Schema | 0 violations | (n/a) | ≥1 violation |
+| Code | 0 critical, ≤2 warnings | 0 critical, 3+ warnings | ≥1 critical |
+| Document | All required sections present, 0 broken links | 1-2 missing sections | 3+ missing sections OR broken refs |
+| Protocol | 100% REQ compliance | 70-99% compliance | <70% compliance |
+
+The status is not a vote — it is a computed function of the findings.
+Two validators running on the same target MUST produce the same
+status.
+
+PARTIAL is reserved for cases where the target is shippable WITH
+recorded remediation; FAIL means the target cannot ship as-is.
+
+## Severity Definitions
+
+| Severity | Meaning | Examples |
+|----------|---------|----------|
+| Critical | Blocks ship; data corruption, security, AGENTS.md rejection | `any` type, missing required field, broken link in spec |
+| Warning | Should fix soon; degrades quality but does not block | Long body, unused import, missing optional section |
+| Suggestion | Improvement opportunity; no obligation | Extract helper, rename for clarity |
+
+Each finding MUST carry a severity. Findings without severity are
+unactionable — the consumer cannot prioritize.
+
+## Per-Finding Format
+
+```markdown
+### Critical
+
+**C-001**: `packages/cleo/src/dispatch.ts:42` uses `any` type.
+- Rule: AGENTS.md Type Safety §1 — "NEVER use `any` type"
+- Fix: Import the relevant type from `@cleocode/contracts` or
+  define a narrower union.
+- Verification: `pnpm biome check packages/cleo/src/dispatch.ts`
+
+**C-002**: `packages/cleo/src/release.ts:107` catches `err: unknown`.
+- Rule: AGENTS.md Type Safety §5 — "NEVER use `catch (err: unknown)`"
+- Fix: Throw and catch by class from `@cleocode/contracts/errors`.
+- Verification: Replace with `catch (err)` and pattern-match by
+  `instanceof`.
+
+### Warnings
+
+**W-001**: `packages/cleo/src/dispatch.ts` is 487 lines (warn at 400).
+- Rule: ct-skill-validator audit_body §body-length
+- Fix: Extract sub-handlers into sibling files.
+- Verification: re-run audit_body.py.
+
+### Suggestions
+
+**S-001**: `packages/cleo/src/dispatch.ts:120` has a TODO with no task ID.
+- Rule: Internal — TODOs should reference task IDs.
+- Fix: File a task, attach the ID: `// TODO(T9999): ...`.
+```
+
+Each finding gets a stable ID (`C-NNN`, `W-NNN`, `S-NNN`) so subsequent
+reports can reference whether the same issue persists.
+
+## Compliance Percentage
+
+For modes that report a percentage:
+
+```text
+compliance = (passed_checks / total_checks) × 100
+```
+
+Round to one decimal. For Protocol mode (REQ compliance), checks are
+the REQs in the spec's traceability matrix. For Schema mode, "checks"
+is the count of constraints evaluated.
+
+When the denominator is zero (e.g., a spec with no REQs), the
+percentage is undefined — emit `N/A` and report a Critical finding for
+the empty spec.
+
+## Integration with ct-ivt-looper
+
+The IVT loop reads the validator's `status` and `compliance` fields
+to decide whether to continue iterating. The contract:
+
+- `status: PASS` → IVT loop converges; release-orchestrator may proceed.
+- `status: PARTIAL` → IVT loop loops once more with the remediation as
+  input; if still PARTIAL on iteration 3, escalates to HITL.
+- `status: FAIL` → IVT loop blocks; release-orchestrator MUST not
+  proceed; HITL escalation immediate.
+
+This contract is the reason status calculus is rigid — fuzzy statuses
+break the loop's termination conditions.
+
+## Integration with Release
+
+`ct-release-orchestrator` reads the most recent validation report
+for the epic before allowing ship. The release pipeline (ADR-065)
+contains a gate that asserts `status: PASS` on the implementation
+against the spec. PARTIAL reports trigger a recorded remediation
+plan; FAIL reports block.
+
+## Machine-Readable Sidecar
+
+Always emit a JSON sidecar next to the markdown report:
+
+```json
+{
+  "target": "packages/cleo/src/release.ts",
+  "mode": "code",
+  "status": "FAIL",
+  "compliance": 88.5,
+  "findings": {
+    "critical": [
+      {"id": "C-001", "file": "...", "line": 42, "rule": "...", "fix": "..."},
+      {"id": "C-002", "file": "...", "line": 107, "rule": "...", "fix": "..."}
+    ],
+    "warnings": [...],
+    "suggestions": [...]
+  },
+  "trace": {
+    "tooling": ["biome@2.4.11", "tsc@5.6.0"],
+    "reproducer": "pnpm biome check . && pnpm exec tsc -b",
+    "timestamp": "2026-05-19T19:35:00Z"
+  }
+}
+```
+
+The orchestrator parses this when programmatic decisions are needed;
+the human report (.md) is for review.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| Vague finding ("file looks weird") | Cannot remediate |
+| Missing severity | Consumer cannot prioritize |
+| No reproducer in trace | Cannot re-validate after fix |
+| PARTIAL with no remediation plan | Status calculus violation |
+| Findings without rule reference | Disputable, not actionable |
+| Markdown only, no JSON sidecar | Breaks orchestrator integration |

package/skills/ct-validator/references/schema-checking.md

@@ -0,0 +1,191 @@
+# Schema Checking
+
+Deeper guidance for Schema Validation mode (Mode 1 from
+`validation-modes.md`). Schema checking is the most mechanical of the
+four modes — but only if the inputs are correctly configured. This
+reference covers the configuration pitfalls and tool-selection rules.
+
+## Pick the Right Engine
+
+| Engine | Strength | When to use |
+|--------|----------|-------------|
+| AJV (`ajv-cli`) | Fast; draft-07 / 2019-09 / 2020-12 | Generic JSON Schema validation |
+| Zod | Type-safe; integrates with TypeScript | Project-internal data validation |
+| drizzle-orm/zod | Schema → Zod auto-generation | Drizzle ORM consumers |
+| jsonschema (Python) | Cross-language; same draft support | Python-side validation |
+| `cargo schema` / serde | Type-safe; Rust-side | Rust crates |
+
+The CLEO repo's primary engine is Zod (via `@cleocode/contracts`) — most
+internal schemas are exported as Zod schemas with optional drizzle
+codegen. Use Zod's `safeParse` to get structured errors.
+
+For external contracts (LAFS envelope spec, JSON-RPC requests from
+non-CLEO clients), use AJV or jsonschema for cross-language portability.
+
+## Draft Selection
+
+Always state the draft explicitly. Draft-07 and draft-2020-12 have
+incompatible semantics around `$ref`, `if/then/else`, and tuple arrays.
+
+| Draft | Best for | Caveats |
+|-------|----------|---------|
+| draft-04 | Legacy | `id` not `$id`; many engines deprecated this |
+| draft-07 | Industry standard | Most engines support fully |
+| draft-2019-09 | New work, conservative | `$defs` replaces `definitions` |
+| draft-2020-12 | New work, full | Some engines lag |
+
+CLEO contracts target draft-07 unless the schema needs 2020-12-only
+features (typically `prefixItems` for tuple arrays). Add the explicit
+`"$schema"` field on every published schema:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TaskEnvelope",
+  "type": "object",
+  "required": ["success", "meta"],
+  ...
+}
+```
+
+## The Standard Validation Loop
+
+```bash
+# 1. Choose engine; choose draft
+ENGINE=ajv
+DRAFT=draft-07
+
+# 2. Resolve schema file (must include $schema or pass --spec)
+SCHEMA=packages/contracts/schemas/envelope.json
+
+# 3. Iterate over data files
+for DATA in path/to/*.json; do
+  echo "=== $DATA ==="
+  npx ajv validate -s "$SCHEMA" -d "$DATA" --spec=$DRAFT --all-errors
+done
+
+# 4. Aggregate by file in the report
+```
+
+The `--all-errors` flag (AJV) or `--exhaustive` (Zod's `safeParse` does
+this by default) is essential — the spec ground rule is "report every
+violation", not "stop at the first one".
+
+## Pitfalls
+
+### 1. $ref Resolution Failure
+
+**Symptom.** Validator complains "could not resolve $ref" or "unknown
+keyword $ref".
+
+**Cause.** Schema references another file by relative path; the engine
+does not know the base directory.
+
+**Fix.** Pass `--ref` (AJV) pointing at the referenced files, or inline
+the references with `$defs`. For multi-file schemas, use AJV's
+`addSchema()` API or a bundler step that flattens before validation.
+
+### 2. Implicit Type Coercion
+
+**Symptom.** A string `"123"` validates against `{"type": "number"}`.
+
+**Cause.** Engine has coercion enabled (`coerceTypes: true` in AJV).
+
+**Fix.** Disable coercion for strict validation:
+
+```javascript
+new Ajv({ coerceTypes: false, strict: true, allErrors: true })
+```
+
+CLEO contracts are strict by default — incoming data must already be
+typed correctly.
+
+### 3. Missing required not flagged
+
+**Symptom.** A required field is missing; schema says it's required;
+validator passes.
+
+**Cause.** The schema's `required` is at the wrong level (nested vs
+top), or the validator is in non-strict mode.
+
+**Fix.** Re-check the schema structure. `required` must be a peer of
+`properties` at the same nesting level.
+
+### 4. Additional Properties Silently Allowed
+
+**Symptom.** Data has extra fields not in the schema; validator passes.
+
+**Cause.** Schema does not specify `additionalProperties: false`.
+
+**Fix.** CLEO contracts default to `additionalProperties: false` — extra
+fields indicate either drift in the producer or a malicious payload.
+Override only with an inline justification.
+
+## Reporting Schema Violations
+
+Each violation goes in the report as:
+
+```markdown
+### Violations
+
+| Path | Keyword | Actual | Expected | File |
+|------|---------|--------|----------|------|
+| `/data/items/3/id` | required | (absent) | string | manifest-instance.json |
+| `/data/version` | type | "1.2.3" (string) | number | manifest-instance.json |
+| `/meta/timestamp` | format | "today" | date-time | manifest-instance.json |
+| `/error.code` | enum | "E_WUT" | one of [E_NOT_FOUND, E_VALIDATION, ...] | response.json |
+```
+
+The Path column uses JSON Pointer (RFC 6901). The Keyword column names
+the schema constraint violated. Actual + Expected gives the diff
+needed to fix.
+
+## Bulk Schema Validation
+
+When validating many instances (e.g., every manifest file in
+`.cleo/agent-outputs/`), produce a summary table first, then drill
+into failures.
+
+```markdown
+## Summary
+
+- **Files validated**: 47
+- **Pass**: 42
+- **Fail**: 5
+- **Compliance**: 89.4%
+
+## Failed Files
+
+| File | Violations |
+|------|-----------|
+| `.cleo/agent-outputs/2026-05-19_old.md` | 3 |
+| `.cleo/agent-outputs/2026-05-19_draft.md` | 1 |
+| ... | ... |
+
+## Detail (per-file)
+
+### `.cleo/agent-outputs/2026-05-19_old.md`
+
+| Path | Keyword | Actual | Expected |
+|------|---------|--------|----------|
+| ... | ... | ... | ... |
+```
+
+Bulk reports SHOULD be machine-readable. Emit a sibling JSON report
+under the same name when the consumer is automation.
+
+## Self-Test the Schema
+
+Before trusting any schema for validation, verify it accepts known-good
+instances and rejects known-bad instances. Maintain a `fixtures/`
+directory next to the schema:
+
+```text
+packages/contracts/schemas/envelope.json
+packages/contracts/schemas/fixtures/envelope-valid.json
+packages/contracts/schemas/fixtures/envelope-missing-success.json
+packages/contracts/schemas/fixtures/envelope-wrong-type.json
+```
+
+A test that exercises all three confirms the schema does what it
+claims. Without fixtures, schema drift goes undetected.

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

@@ -125,7 +125,13 @@
       "protocol": "implementation",
       "loomStage": "implementation",
       "adrRefs": ["ADR-070", "ADR-062"],
-      "references": [],
+      "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"],
@@ -187,7 +193,12 @@
       "protocol": "research",
       "loomStage": "research",
       "adrRefs": ["ADR-023", "ADR-070"],
-      "references": [],
+      "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"],
@@ -218,7 +229,12 @@
       "protocol": "specification",
       "loomStage": "specification",
       "adrRefs": ["ADR-014", "ADR-023"],
-      "references": [],
+      "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"],
@@ -249,7 +265,12 @@
       "protocol": "validation",
       "loomStage": "validation",
       "adrRefs": ["ADR-051", "ADR-023"],
-      "references": [],
+      "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"],
@@ -305,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"],
@@ -333,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"],
@@ -361,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"],
@@ -389,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"],