@cleocode/skills 2026.5.84 → 2026.5.87

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").

package/skills/ct-spec-writer/references/traceability-matrix.md

@@ -0,0 +1,145 @@
+# Traceability Matrix
+
+Every REQ in a CLEO spec MUST be traceable to (a) the source justifying
+its existence and (b) the test that verifies its implementation. The
+traceability matrix is the table that makes those links explicit and
+machine-readable. Without it, specs decay — requirements survive
+implementations they no longer reflect.
+
+## Three-Way Trace
+
+A complete trace links three artifacts:
+
+```
+[Source]  ── justifies ──>  [Requirement]  ── verified by ──>  [Test]
+```
+
+- **Source.** The research finding, ADR, user need, or upstream spec that
+  motivates the requirement.
+- **Requirement.** The REQ-NNN entry in this spec.
+- **Test.** The test file/case that exercises the requirement.
+
+Each link MUST be a stable identifier — not prose. "REQ-007 was discussed
+in a meeting" is not a trace; "REQ-007 derives from ADR-065 §3" is.
+
+## The Matrix Block
+
+Include this block in every spec, immediately before the `## Compliance`
+section.
+
+```markdown
+## Traceability
+
+| REQ | Source | Verification |
+|-----|--------|--------------|
+| REQ-001 | ADR-065 §3 | `packages/cleo/__tests__/release-pipeline.test.ts::cuts-from-main-tip` |
+| REQ-002 | ADR-065 §3 | `packages/cleo/__tests__/release-pipeline.test.ts::refuses-direct-push` |
+| REQ-003 | T9580 acceptance | `packages/cleo/__tests__/release-ship.test.ts::epic-completeness-check` |
+| REQ-004 | RFC 7230 §3.2 | `packages/transport/__tests__/http.test.ts::header-canonicalization` |
+| REQ-005 | (TODO: assign source) | (TODO: write test) |
+```
+
+Rows with `(TODO: ...)` are acceptable in `draft` status, NOT in
+`accepted`. A spec cannot move to `accepted` while any TODO row remains.
+
+## Source Token Conventions
+
+The source column accepts these forms:
+
+| Form | Example | When to use |
+|------|---------|-------------|
+| ADR reference | `ADR-065 §3` | Decision recorded in `.cleo/adrs/` |
+| Spec reference | `Spec-foo v1.2 REQ-007` | Inherited from upstream spec |
+| Task reference | `T9580 acceptance` | Direct from task acceptance criteria |
+| Research reference | `.cleo/agent-outputs/2026-05-19_caching.md §Findings` | From research output |
+| External standard | `RFC 7230 §3.2` | IETF / W3C / ISO standard |
+| BRAIN reference | `D003` or `O-mpd07uma-0` | Stored decision or observation |
+| User mandate | `Owner directive 2026-05-19` | Direct from user/owner |
+
+The form `(meeting notes)` or `(slack thread)` is NOT acceptable — these
+are ephemeral and not citable.
+
+## Verification Token Conventions
+
+The verification column accepts these forms:
+
+| Form | Example | Meaning |
+|------|---------|---------|
+| Test ID | `pkg/__tests__/foo.test.ts::case-name` | Unit/integration test exists |
+| Eval ID | `eval-suite-x::scenario-7` | Agent eval covers this REQ |
+| Manual procedure | `docs/qa/manual-release-checklist.md §A` | Human verification step |
+| Tool gate | `pnpm run typecheck` | Toolchain enforces this REQ |
+| Linter rule | `biome.json::rules.style.X` | Linter rule covers this REQ |
+
+A REQ that cannot be verified is not a requirement — it is a wish.
+Reject any REQ that lacks a verification plan during draft review.
+
+## Bidirectional Index
+
+Large specs (more than 30 REQs) SHOULD include a reverse index from test
+back to REQ, so a failing test can be located against its requirement
+quickly.
+
+```markdown
+## Test → REQ Reverse Index
+
+- `release-pipeline.test.ts::cuts-from-main-tip` → REQ-001
+- `release-pipeline.test.ts::refuses-direct-push` → REQ-002
+- `release-ship.test.ts::epic-completeness-check` → REQ-003
+- `http.test.ts::header-canonicalization` → REQ-004
+```
+
+Generate this manually for small specs; large specs SHOULD include a
+script at `scripts/extract-trace.ts` that produces it from the forward
+matrix.
+
+## Trace Health Metrics
+
+A healthy spec has these properties — `ct-validator` reports on them.
+
+| Metric | Healthy | Warning | Failure |
+|--------|---------|---------|---------|
+| REQs without source | 0 | 1-2 | 3+ |
+| REQs without verification | 0 | 1-2 | 3+ |
+| Tests not linked from any REQ | low | 10-25% | 25%+ |
+| External standard refs | present | (n/a) | (n/a) |
+| TODO rows in accepted spec | 0 | (cannot be) | any |
+
+## Drift Detection
+
+When the implementation evolves, the matrix drifts. Detect drift with:
+
+```bash
+# List tests that exist on disk
+find packages -name "*.test.ts" -exec grep -l "REQ-" {} \;
+
+# Compare to REQs claimed in the matrix
+grep "^| REQ-" docs/specs/*.md
+
+# Diff yields:
+# - tests referencing REQs not in any matrix (orphan tests)
+# - matrix REQs whose tests have disappeared (broken trace)
+```
+
+This SHOULD run in CI on `pull_request` touching `docs/specs/**`. The
+existing CI `skills` job (or a new `spec-trace-check` job) is the right
+home — the workflow MUST fail when broken traces appear in `accepted`
+specs.
+
+## Inheritance When Specs Refactor
+
+When Spec-A is superseded by Spec-B, copy the matrix forward and add a
+`Supersedes` column for the legacy REQ ID. This preserves test trace
+across the rename.
+
+```markdown
+| REQ (new) | Supersedes | Source | Verification |
+|-----------|------------|--------|--------------|
+| REQ-001 | Spec-A REQ-007 | ADR-065 §3 | test::cuts-from-main-tip |
+| REQ-002 | Spec-A REQ-008 | ADR-065 §3 | test::refuses-direct-push |
+| REQ-003 | (new) | T9580 | test::epic-completeness-check |
+```
+
+The legacy spec MUST mark itself `deprecated` and link forward to the
+successor. Never delete the legacy spec until all tests have been
+re-attributed.

package/skills/ct-task-executor/SKILL.md

@@ -309,3 +309,13 @@ This skill binds to the **implementation** LOOM lifecycle stage. Governing ADRs:
 - [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).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/implementation-patterns.md` — read-before-write, file-placement, ESM imports, quality-gate sequence
+- `references/acceptance-criteria-mapping.md` — mapping table, AC categories, verification commands
+- `references/evidence-and-gates.md` — ADR-051 atom shape, gate ritual, tool resolution + cache
+- `references/common-failures.md` — twelve observed worker failure modes with corrected approach
+- `references/anti-patterns.md` — instant-rejection patterns from AGENTS.md