@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-spec-writer/__tests__/skill-spec-writer.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Regression test for ct-spec-writer/SKILL.md (T9643 / Epic T9629 / Saga T9625).
+ *
+ * Pins the SDK-first spec contract: specs MUST be created via
+ * `cleo docs add --type spec --slug <name>` so they auto-attach to the
+ * parent task and are retrievable by slug. The Output Location section
+ * may still mention `docs/specs/{{SPEC_NAME}}.md` as the published path,
+ * but the canonical write surface is the SDK.
+ *
+ * @task T9643
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-spec-writer SKILL.md — SDK-first contract (T9643)', () => {
+  it('teaches `cleo docs add --type spec` as the canonical write path', () => {
+    expect(skillContent).toMatch(/cleo docs add[\s\S]+--type spec/);
+  });
+
+  it('shows `--slug` as the kebab-case retrieval handle', () => {
+    expect(skillContent).toContain('--slug');
+    expect(skillContent).toMatch(/kebab-case/);
+  });
+
+  it('attaches the spec to a parent task via the owner ID', () => {
+    // Owner ID example must use a T### prefix to demonstrate task linkage
+    expect(skillContent).toMatch(/cleo docs add\s+T\d+\s/);
+  });
+
+  it('shows `cleo docs publish --for ... --to docs/specs/...` for git publication', () => {
+    expect(skillContent).toMatch(/cleo docs publish[\s\S]+--for[\s\S]+--to[\s\S]+docs\/specs/);
+  });
+
+  it('shows `cleo docs fetch <slug>` for downstream retrieval', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('shows `cleo docs list --type spec` for sibling spec discovery', () => {
+    expect(skillContent).toMatch(/cleo docs list[\s\S]+--type spec/);
+  });
+
+  it('marks the old direct-filesystem write as deprecated with a migration note', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem write');
+    expect(skillContent).toMatch(/cleo docs (add|sync)/);
+  });
+
+  it('references E_SLUG_TAKEN for collision handling', () => {
+    expect(skillContent).toContain('E_SLUG_TAKEN');
+  });
+});

package/skills/ct-spec-writer/references/anti-patterns.md

@@ -0,0 +1,176 @@
+# Anti-Patterns
+
+Common failure modes when writing CLEO specs. Each pattern degrades the
+spec from a testable contract into prose. Detection cues and remediations
+are listed; many of these were caught in past `ct-validator` reports and
+in council reviews on previously-shipped specs.
+
+## 1. The Ambiguous MUST
+
+**Symptom.** A requirement uses MUST but the failure condition cannot be
+mechanically determined.
+
+**Example (bad)**
+
+> **REQ-005**: The system MUST handle errors gracefully.
+
+**Detection cue.** Words like "gracefully", "appropriately", "reasonably",
+"properly", "sensibly" appear in the requirement body.
+
+**Remediation.** Replace fuzzy adverbs with measurable conditions.
+
+> **REQ-005**: The system MUST return an LAFS envelope with
+> `success: false` and `error.code` matching one of the registered
+> error codes (see `packages/contracts/src/errors.ts`) on any failure
+> reaching the command dispatcher.
+
+## 2. The Tautological Requirement
+
+**Symptom.** The requirement restates the function's name.
+
+**Example (bad)**
+
+> **REQ-003**: The `validate()` function MUST validate the input.
+
+**Detection cue.** The requirement body's main verb matches the
+subject's name without adding constraint.
+
+**Remediation.** State the contract — what defines successful validation,
+what the function returns on failure, what side effects it has.
+
+> **REQ-003**: The `validate()` function MUST return `{ ok: true }` if
+> the input matches the schema, or `{ ok: false, errors: [...] }`
+> containing one entry per violation otherwise. It MUST NOT mutate
+> the input.
+
+## 3. The Compound Requirement
+
+**Symptom.** A single REQ asserts multiple independent constraints joined
+by "and" or commas.
+
+**Example (bad)**
+
+> **REQ-009**: The release pipeline MUST run lint, MUST run tests, MUST
+> generate a changelog, AND MUST push the tag.
+
+**Detection cue.** Multiple MUST/MUST NOT/SHOULD phrases in one REQ; or
+"and" connecting verb phrases.
+
+**Remediation.** Split into atomic REQs so each can be tested
+independently and traced individually.
+
+> **REQ-009**: The release pipeline MUST run lint.
+> **REQ-010**: The release pipeline MUST run tests after lint passes.
+> **REQ-011**: The release pipeline MUST generate a changelog.
+> **REQ-012**: The release pipeline MUST push the tag only after all
+> prior REQs in this sequence have passed.
+
+## 4. The Implementation Detail Spec
+
+**Symptom.** The spec dictates HOW the implementation should work, not
+WHAT it must achieve.
+
+**Example (bad)**
+
+> **REQ-014**: The cache MUST be implemented using a Map<string, Buffer>
+> with LRU eviction.
+
+**Detection cue.** Concrete data structures, library names, or algorithm
+choices appear in MUST clauses.
+
+**Remediation.** State the observable contract; let implementations
+choose the structure.
+
+> **REQ-014**: The cache MUST support O(1) lookup by string key.
+> **REQ-015**: The cache MUST evict the least-recently-used entry when
+> capacity is exceeded.
+
+## 5. The Untestable SHOULD
+
+**Symptom.** SHOULD is used to mean "MAY" or to defer the test problem.
+
+**Example (bad)**
+
+> **REQ-017**: The orchestrator SHOULD be efficient.
+
+**Detection cue.** SHOULD without a measurable cap, threshold, or
+comparison.
+
+**Remediation.** Either make it testable, or downgrade to MAY.
+
+> **REQ-017**: The orchestrator SHOULD complete a 5-task wave dispatch
+> within 2 seconds on the reference hardware (T9396).
+> [— OR —]
+> **REQ-017**: The orchestrator MAY parallelize wave dispatch.
+
+## 6. The Forgotten Edge Case
+
+**Symptom.** The happy-path requirement is stated, but failure modes
+(timeouts, partial completion, concurrent invocation) are unspecified.
+
+**Detection cue.** No requirement mentions error codes, retries,
+timeouts, or concurrent semantics — yet the implementation will face
+all of these.
+
+**Remediation.** For every operation, add at minimum:
+
+- Timeout behavior (REQ: "after N seconds without progress, MUST return
+  E_TIMEOUT")
+- Concurrent invocation (REQ: "MUST serialize concurrent calls per
+  resource ID")
+- Partial state (REQ: "on failure mid-operation, MUST roll back to
+  pre-call state OR persist a recovery record")
+
+## 7. The Spec Without Conformance
+
+**Symptom.** The spec has 20 REQs but no `## Compliance` section.
+
+**Detection cue.** Last section heading is not `## Compliance`.
+
+**Remediation.** Add the section. Without it, `ct-validator` cannot
+produce pass/fail reports, and implementations cannot self-attest. A
+spec without a compliance criteria block is unfinished.
+
+## 8. The Stealth Decision
+
+**Symptom.** The spec contains a phrase like "we chose X over Y for
+reasons A, B, C" — but that decision was not recorded in any ADR.
+
+**Detection cue.** Spec body explains *why* a choice was made, instead
+of *what* the requirement is.
+
+**Remediation.** Pull the decision into a proper ADR. Reference the ADR
+from the REQ's source column. The spec body asserts the requirement
+flatly; the rationale lives in the ADR.
+
+## 9. The Drift-Prone Cross-Reference
+
+**Symptom.** A REQ cross-references another section by prose ("as
+discussed in the previous section") or by page number.
+
+**Detection cue.** No `REQ-NNN` token in cross-references.
+
+**Remediation.** Always reference by stable identifier — `REQ-001`,
+`CON-007`, `§3.2`, `ADR-065`. Prose references rot when sections
+reorder.
+
+## 10. The Version Hostage
+
+**Symptom.** The spec hard-codes the version of a dependency or the
+specific commit of an ADR that motivated it.
+
+**Example (bad)**
+
+> **REQ-021**: The pipeline MUST use drizzle-orm@1.0.0-beta.
+
+**Detection cue.** Pinned version in a requirement body.
+
+**Remediation.** Pin only the behavior; pin the version in the
+implementation's manifest. If a specific version is genuinely required,
+state the constraint as a range.
+
+> **REQ-021**: The pipeline MUST use a Drizzle ORM release that
+> supports `defineRelations` (introduced in v1.0.0-beta or later).
+
+This preserves the spec across patch upgrades that do not change
+contracts.

package/skills/ct-spec-writer/references/rfc2119-language.md

@@ -0,0 +1,138 @@
+# RFC 2119 Language
+
+The skill MUST use RFC 2119 keywords correctly. This reference defines each
+keyword precisely, gives positive and negative examples, and lists the
+common misuses that downstream test writers and validators catch most
+often. A spec is only as testable as its language is unambiguous.
+
+## The Five Keywords
+
+| Keyword | Synonyms | Precise meaning |
+|---------|----------|-----------------|
+| **MUST** | REQUIRED, SHALL | Absolute requirement. Non-compliance is a defect. |
+| **MUST NOT** | SHALL NOT | Absolute prohibition. Non-compliance is a defect. |
+| **SHOULD** | RECOMMENDED | Recommended; non-compliance requires recorded rationale. |
+| **SHOULD NOT** | NOT RECOMMENDED | Discouraged; non-compliance requires recorded rationale. |
+| **MAY** | OPTIONAL | Truly optional; compliance and non-compliance are both fine. |
+
+These keywords are case-sensitive in their normative meaning. Use UPPERCASE
+when carrying RFC 2119 weight; lowercase ("must", "should") is prose and
+does not bind implementations.
+
+## The Mandatory Header
+
+Every CLEO specification MUST open with the IETF boilerplate, exactly:
+
+```markdown
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in RFC 2119.
+```
+
+If the boilerplate is missing, the document is a guide, not a spec.
+Downstream tooling — `ct-validator`, the IVT loop, the consensus voter —
+will not enforce normative weight on un-boilerplated documents.
+
+## Positive Examples
+
+**Absolute requirement (MUST)**
+
+> **REQ-007**: The release-ship command MUST cut the release branch from
+> the tip of `main` after passing all quality gates.
+
+This is testable: the test reads the branch's merge-base; if it is not
+the `main`-tip-at-cut-time, the test fails.
+
+**Conditional requirement (MUST + when-clause)**
+
+> **REQ-008**: When `release.branchModel` is `feat-to-main`, the
+> release pipeline MUST refuse direct pushes to `main`.
+
+This is testable: with the config set, attempt a direct push; assert
+rejection.
+
+**Recommendation (SHOULD)**
+
+> **REQ-012**: The orchestrator SHOULD batch parallel-safe tasks into
+> waves rather than serializing them.
+
+Compliant if waves exist; if serialization happens for a documented
+reason (e.g. a dependency the auto-detector missed) the implementation
+remains compliant — but the rationale MUST be recorded.
+
+**Truly optional (MAY)**
+
+> **REQ-019**: Implementations MAY cache the resolved skill manifest
+> for the duration of a single orchestration session.
+
+No conformance pressure either way. Caching and re-fetching are both
+valid implementations.
+
+## Negative Examples (Anti-Spec Language)
+
+These phrasings look normative but are not. Replace each before the spec
+ships.
+
+| Anti-pattern | Why it fails | Replacement |
+|--------------|--------------|-------------|
+| "The system needs to validate input" | "Needs to" is aspirational, not binding | "The system MUST validate input" |
+| "It is recommended that you encrypt at rest" | "It is recommended" is passive prose | "Implementations SHOULD encrypt at rest" |
+| "We will use HTTPS" | First-person future tense is a plan, not a requirement | "All transports MUST use HTTPS" |
+| "Should ideally be idempotent" | "Ideally" weakens SHOULD into nothing | "MUST be idempotent" or "SHOULD be idempotent" |
+| "Try to keep payloads under 1MB" | "Try to" is unmeasurable | "Payloads SHOULD NOT exceed 1MB" |
+| "Cannot exceed 100 requests/minute" | "Cannot" is descriptive, not normative | "MUST NOT exceed 100 requests/minute" |
+
+## When to Pick Which Keyword
+
+Use this decision rubric:
+
+1. **Will an implementation that violates this rule fail user expectations
+   or break interoperability?**
+   - Yes → MUST / MUST NOT
+   - Maybe → continue
+2. **Is there a legitimate operating environment where violating this rule
+   is the right call?**
+   - Yes → SHOULD / SHOULD NOT
+   - No → revisit step 1
+3. **Is the behavior genuinely a choice with no preferred direction?**
+   - Yes → MAY
+   - No → revisit steps 1-2
+
+If you cannot decide between MUST and SHOULD, the requirement is probably
+under-specified — sharpen the failure condition first, then re-evaluate.
+
+## Cross-Reference Patterns
+
+When one requirement depends on another, link them explicitly so the test
+matrix can build the dependency graph.
+
+```markdown
+**REQ-021**: The skill MUST emit a `pipeline_manifest` entry per
+**REQ-008** before completing the task.
+```
+
+Avoid prose-cross-references ("as mentioned above") — they cannot be
+machine-extracted. Use the `REQ-NNN` token.
+
+## Compliance Statements
+
+Every spec MUST close with a `## Compliance` section that enumerates the
+conditions under which an implementation is conformant.
+
+```markdown
+## Compliance
+
+An implementation is **conformant** if and only if:
+
+1. All MUST and MUST NOT requirements (REQ-001 through REQ-007) hold.
+2. Each SHOULD or SHOULD NOT requirement either holds OR is accompanied
+   by a recorded rationale in the implementation's `decisions` table.
+3. MAY requirements are reported in the implementation's capability
+   manifest if applicable.
+
+Non-conformant implementations SHOULD provide a remediation plan with
+target conformance date.
+```
+
+This section is what `ct-validator` reads when producing the validation
+report — without it, validation cannot proceed.

package/skills/ct-spec-writer/references/spec-templates.md

@@ -0,0 +1,233 @@
+# Spec Templates
+
+Templates for the spec types that CLEO produces most frequently. Each
+template includes the canonical sections, required cross-references, and
+the conformance criteria block that `ct-validator` reads downstream.
+
+## Protocol Specification
+
+For inter-component or inter-process contracts. Examples: the
+`cleo-subagent` protocol, the `pipeline_manifest` schema, the LAFS
+envelope contract.
+
+```markdown
+# {Protocol Name} Specification v{X.Y.Z}
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in RFC 2119.
+
+**Status**: draft | proposed | accepted | deprecated
+**Supersedes**: (none) | {ADR-XXX} | {Spec-Name v{X.Y.Z-1}}
+**Related ADRs**: ADR-XXX, ADR-YYY
+
+---
+
+## Abstract
+
+{One paragraph: what this protocol governs and why it exists.}
+
+## Definitions
+
+| Term | Definition |
+|------|------------|
+| {term} | {precise definition; avoid synonyms} |
+
+## Roles
+
+- **{Role A}**: {responsibilities}
+- **{Role B}**: {responsibilities}
+
+## Message Types / Operations
+
+### {Operation 1}
+
+**REQ-001**: {what MUST happen}.
+- Inputs: {field list with types}
+- Outputs: {field list with types}
+- Errors: {error code enumeration}
+
+### {Operation 2}
+...
+
+## State Machine (if applicable)
+
+| State | Transitions | Triggers |
+|-------|-------------|----------|
+| init | → ready | start() |
+| ready | → running, → cancelled | run(), cancel() |
+| running | → done, → failed | (auto) |
+
+## Security Considerations
+
+{What can go wrong; threat model.}
+
+## Compliance
+
+An implementation is conformant if {enumerated conditions}.
+```
+
+## API Specification
+
+For HTTP, gRPC, or CLI-level interfaces.
+
+```markdown
+# {API Name} Specification v{X.Y.Z}
+
+{RFC 2119 boilerplate}
+
+## Overview
+
+{One paragraph.}
+
+## Endpoints / Commands
+
+### `{METHOD} /path` or `cleo {verb} {noun}`
+
+**REQ-001**: The endpoint MUST return 2xx on success, 4xx on client
+error, 5xx on server error.
+
+**Request schema**:
+```json
+{ "field": "type", "field2": "type" }
+```
+
+**Response schema (success)**:
+```json
+{ "result": "type" }
+```
+
+**Errors**:
+| Code | Meaning | When |
+|------|---------|------|
+| E_NOT_FOUND | Resource missing | {trigger} |
+| E_VALIDATION | Bad input | {trigger} |
+
+**REQ-002**: The endpoint SHOULD complete within {N}ms p95.
+
+## Authentication
+
+{Required headers, scopes, etc.}
+
+## Versioning
+
+{How breaking changes are communicated.}
+
+## Compliance
+
+{Conditions.}
+```
+
+## Architecture Document
+
+For high-level structural decisions that do not fit the ADR (single
+decision) shape but need normative weight. The ADR records the decision;
+the architecture document specifies the resulting structure.
+
+```markdown
+# {System Name} Architecture v{X.Y.Z}
+
+{RFC 2119 boilerplate}
+
+## Context
+
+{Why this system exists; what problem it solves.}
+
+## Constraints
+
+| ID | Constraint | Source |
+|----|------------|--------|
+| CON-001 | All DB opens go through openCleoDb() | ADR-D003 |
+| CON-002 | No raw new DatabaseSync() outside chokepoint | ADR-D003 |
+
+## Components
+
+### {Component A}
+- **Responsibility**: {one sentence}
+- **Inputs**: {what it consumes}
+- **Outputs**: {what it produces}
+- **Constraints**: CON-XXX, CON-YYY
+
+### {Component B}
+...
+
+## Dependencies
+
+```mermaid
+graph LR
+  A[Component A] --> B[Component B]
+  B --> C[Component C]
+```
+
+## Cross-cutting Concerns
+
+- **Observability**: {logging, metrics, tracing requirements}
+- **Security**: {authn, authz, secrets handling}
+- **Resilience**: {failure modes, recovery}
+
+## Compliance
+
+{Conditions.}
+```
+
+## Requirements Document (small/targeted)
+
+For a single feature where a full protocol spec is overkill but a
+testable contract is needed.
+
+```markdown
+# {Feature Name} Requirements v{X.Y.Z}
+
+{RFC 2119 boilerplate}
+
+## Scope
+
+{What's in; what's out.}
+
+## Requirements
+
+**REQ-001**: {requirement}
+- Rationale: {why}
+- Verification: {how to test}
+
+**REQ-002**: {requirement}
+- Rationale: {why}
+- Verification: {how to test}
+
+## Constraints
+
+{CON-XXX list if relevant.}
+
+## Open Questions
+
+{Anything not yet resolved — these block acceptance.}
+
+## Compliance
+
+{Conditions.}
+```
+
+## Naming Conventions
+
+| Type | Filename pattern | Location |
+|------|------------------|----------|
+| Protocol spec | `<name>-protocol-v<x>.md` | `docs/specs/protocols/` |
+| API spec | `<name>-api-v<x>.md` | `docs/specs/apis/` |
+| Architecture | `<name>-architecture-v<x>.md` | `docs/architecture/` |
+| Requirements | `<name>-requirements.md` | `docs/specs/requirements/` |
+| ADR | `ADR-NNN-<short-slug>.md` | `.cleo/adrs/` |
+
+When in doubt: protocol vs requirements — a protocol governs a contract
+between two parties; requirements govern behavior of a single party.
+
+## Versioning Rules
+
+| Bump | Trigger |
+|------|---------|
+| Patch (`X.Y.Z+1`) | Clarification, typo fix, no semantic change |
+| Minor (`X.Y+1.0`) | Added requirement (additive) |
+| Major (`X+1.0.0`) | Changed or removed requirement (breaking) |
+
+A major bump REQUIRES a corresponding deprecation period for the prior
+major version. State the period in `## Status` (e.g., "v2.x deprecated
+2026-Q3, removed 2026-Q4").