@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-documentor/references/style-coordination.md

@@ -0,0 +1,195 @@
+# Style Coordination
+
+The CLEO documentation style guide lives at
+`packages/skills/skills/_shared/cleo-style-guide.md` and is referenced
+by both `ct-docs-write` and `ct-docs-review`. As coordinator, the
+documentor's role is to ensure the style guide is enforced consistently
+across the chain — write applies it; review verifies it. This reference
+covers the parts of the style guide most commonly violated and how the
+documentor enforces them.
+
+## Tone Pillars
+
+The CLEO style is **conversational, clear, user-focused**. Three pillars
+the documentor must enforce across the chain.
+
+### 1. Conversational
+
+Write the way you would explain to a colleague — not the way a corporate
+press release would. This shows up at the word level.
+
+| Avoid | Prefer |
+|-------|--------|
+| utilize | use |
+| reference | see / look at |
+| offerings | products / features |
+| we will / we can | CLEO does / CLEO can |
+| cannot, do not | can't, don't |
+| people are able to | people can |
+
+The contraction rule is real and unusual — CLEO docs USE contractions.
+Many style guides ban them; CLEO does the opposite.
+
+### 2. Clear
+
+Lead with the action; explain after. Headings state the point.
+
+| Vague heading | Clear heading |
+|---------------|---------------|
+| "Environment variables" | "Use environment variables for configuration" |
+| "Authentication" | "Authenticate with API tokens" |
+| "Configuration" | "Configure release pipeline before first ship" |
+| "Performance considerations" | "Set timeout to 30s on slow networks" |
+
+Vague headings force the reader to scan the body to learn the point.
+Clear headings let the reader skip the section if it's not what they
+need.
+
+### 3. User-Focused
+
+Use "people" or "companies", not "users". The first refers to humans;
+the second to a system construct. The CLEO docs are for humans.
+
+| Avoid | Prefer |
+|-------|--------|
+| users can | people can |
+| our users | our customers / the companies using CLEO |
+| user input | what people type |
+| user experience | what people see |
+
+This is jarring at first — many docs are full of "users". Once you
+switch, the writing reads more concretely.
+
+## Forbidden Phrases
+
+These never appear in CLEO docs. The review child rejects them on sight.
+
+- "easy" / "simple" / "just" — patronizing; the reader doesn't know if
+  it's easy until they try
+- "obviously" / "of course" — same problem
+- "for free" / "out of the box" — vague
+- "click here" / "read more here" — link text must be descriptive
+- "and so on" / "etc." — be specific or cut the sentence
+- "as mentioned above" — use a stable cross-reference
+
+The forbidden list is the most common reason a draft fails review.
+Pass the list to ct-docs-write as part of the input contract so it
+knows what to avoid.
+
+## Link Discipline
+
+Link text must describe the destination. Never link bare words like
+"here", "this", "read more".
+
+```markdown
+GOOD: See the [release pipeline ADR](../.cleo/adrs/ADR-065.md) for the gate set.
+
+BAD: See ADR-065 [here](../.cleo/adrs/ADR-065.md) for the gate set.
+
+BAD: For more info, [click here](../.cleo/adrs/ADR-065.md).
+```
+
+The full link text MUST make sense out of context — a reader scanning
+just the link list should understand each destination.
+
+## Code Block Discipline
+
+Code blocks include their language tag for syntax highlighting and
+their working-directory context.
+
+````markdown
+GOOD:
+```bash
+# In the project root
+pnpm run test
+```
+
+GOOD:
+```typescript
+// packages/cleo/src/foo.ts
+import { bar } from "@cleocode/contracts";
+```
+
+BAD:
+```
+pnpm run test
+```
+(no language tag)
+
+BAD:
+```ts
+import { bar } from "@cleocode/contracts";
+```
+(use `typescript`, not `ts`)
+````
+
+The full language tags are `bash`, `typescript`, `tsx`, `python`,
+`rust`, `json`, `yaml`, `markdown`. Avoid abbreviations.
+
+## Table Discipline
+
+Tables compress information that would otherwise sprawl. Use them
+liberally — they signal "look up data" mode.
+
+| Use a table when... | Don't use when... |
+|---------------------|-------------------|
+| You have parallel structured items | You have unstructured prose |
+| Each row has the same columns | Each "row" has different fields |
+| The reader will scan, not read | The reader needs narrative |
+
+Keep tables narrow — three to five columns is the sweet spot. Wider
+tables overflow on mobile and look like data dumps.
+
+## Image Discipline
+
+Images are scoped — they show one specific UI element with relevant
+context. They never show full-window screenshots.
+
+| Scope | When to use |
+|-------|-------------|
+| UI element + label | Annotating a feature |
+| Specific dialog | Showing a flow step |
+| Code in editor | Showing syntax highlighting |
+| Whole window | Almost never |
+
+Add alt text that describes what the image conveys, not what the image
+is of. "Screenshot of the release pipeline dashboard showing three
+green checks" rather than "Dashboard screenshot".
+
+## Cross-Skill Drift Detection
+
+Documentor MUST check that write's output and review's checks agree.
+If they disagree, the style guide reference is the tiebreaker.
+
+```text
+write_output = ct-docs-write(input)
+review_findings = ct-docs-review(write_output)
+
+# Possible drift case:
+# write produced "users" (it should have used "people")
+# review didn't flag it (its rule list was outdated)
+# → file a sync task; passing the style guide explicitly to write
+#   on next iteration
+
+# Possible drift case:
+# write produced "click here"
+# review flagged "click here" with high confidence
+# → no drift; write just made a mistake; iterate
+```
+
+When drift is detected, surface it in `needs_followup` so the next
+session updates the shared style guide or the child skill's rules.
+
+## Pre-PR Style Pass
+
+Before opening a PR with documentation changes, the documentor MUST
+run review one more time on the diff:
+
+```bash
+# Review the diff for style violations
+gh pr diff <PR_NUMBER> | ct-docs-review --mode=diff
+```
+
+PR-mode review uses the `mcp__github__*` tools when available;
+otherwise local mode is fine. The pre-PR pass catches drift that
+sneaked in during integration.

package/skills/ct-epic-architect/SKILL.md

@@ -6,6 +6,10 @@ tier: 1
 core: false
 category: recommended
 protocol: decomposition
+loomStage: decomposition
+adrRefs:
+  - ADR-066
+  - ADR-073
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -329,3 +333,14 @@ Recommendation: [Your recommendation]
 | 6 | Validation | Escape `$` as `\$`, check fields |
 
 **Shell Escaping**: Always `\$` in `--notes`/`--description`. See [shell-escaping.md](references/shell-escaping.md).
+
+---
+
+## See also / References
+
+This skill binds to the **decomposition** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-066 — task taxonomy consolidation](../../../../.cleo/adrs/ADR-066-task-taxonomy-consolidation.md) — defines the Type/Kind/Severity axes the decomposer must populate on every leaf task.
+- [ADR-073 — above-epic naming](../../../../.cleo/adrs/ADR-073-above-epic-naming.md) — defines the Saga/Epic/Task/Subtask hierarchy that decomposition produces.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

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,23 @@ 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).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/triggers-and-routing.md` — when to use ct-research-agent and what downstream skill consumes the output
+- `references/source-strategy.md` — codebase + Context7 + web hierarchy, query patterns, time-boxing
+- `references/citation-and-evidence.md` — evidence ladder, citation format, confidence labels
+- `references/anti-patterns.md` — ten failure modes observed in past CLEO sessions and how to avoid them

package/skills/ct-research-agent/references/anti-patterns.md

@@ -0,0 +1,154 @@
+# Anti-Patterns
+
+Common failure modes for research tasks. Each pattern below has been
+observed in real CLEO sessions (some recorded in BRAIN as patterns
+`P-b2e59bf4`, `P-75035d53`, and others). Avoid them by following the
+detection cue and applying the remediation.
+
+## 1. The Hallucinated Citation
+
+**Symptom.** A finding cites a URL, function signature, or API that does
+not actually exist. The agent inferred its existence from naming
+conventions and a plausible domain.
+
+**Detection cue.** Citation has not been retrieved during this session.
+URL was not produced by a tool call; signature was not read from a file.
+
+**Remediation.** Every citation MUST come from a tool call output in this
+session — `WebFetch`, `WebSearch`, `Grep`, `Read`, `ctx7 docs`, or
+`gitnexus_*`. If the source cannot be re-shown by a tool call, it is
+hallucinated. Strip it and either re-fetch or downgrade the finding to
+`hypothesis`.
+
+## 2. The Stale Authority
+
+**Symptom.** A finding cites the official docs for library X — but the
+project uses version Y, and the cited page describes version Z which has
+different semantics.
+
+**Detection cue.** No version qualifier on the citation. The
+`package.json` or `Cargo.toml` for the project specifies a version that
+differs from the doc page version.
+
+**Remediation.** Always pin Context7 queries to the project's actual
+version. Use the `/org/project/version` form when available. Read the
+project's lockfile before citing version-dependent behavior.
+
+## 3. The Single-Blog Cascade
+
+**Symptom.** A blog post made an interesting claim; the research output
+cited it as fact; downstream the spec writer baked it into requirements;
+the implementation fails because the claim was wrong.
+
+**Detection cue.** A finding sourced to a single blog post or Medium
+article is labeled `verified` or `documented` in the output.
+
+**Remediation.** Blog posts are at most `reported` rung-3 evidence.
+Promote to `documented` only after corroborating with the canonical
+source (official docs, source code, or RFC). If no canonical source
+exists, label `anecdotal` and put it under `## Hypotheses`.
+
+## 4. The Boil-the-Ocean
+
+**Symptom.** The research task is "investigate JavaScript build tools".
+The agent spends 90 minutes producing a 50-page survey of every tool from
+Browserify to Bun, exhausts its token budget, and never answers the
+question the orchestrator actually had.
+
+**Detection cue.** Output exceeds 30 KB without a `## Recommendations`
+section in the first 20% of the file.
+
+**Remediation.** Before opening any source, restate the question in one
+sentence and pick the success criterion. "Boil the ocean" tasks SHOULD be
+split into multiple narrower research tasks via the orchestrator — return
+a `needs_followup` list rather than producing one giant document.
+
+## 5. The Confirmation Loop
+
+**Symptom.** The user (or the calling task) implied a preferred answer in
+the question. The agent finds that preferred answer immediately, stops
+searching, and reports it as if it had explored alternatives.
+
+**Detection cue.** The output lists fewer than 2 alternatives even when
+the task description used comparative language ("compare", "evaluate",
+"options"). All findings support a single direction.
+
+**Remediation.** For comparative tasks, mandate one paragraph per
+alternative with stated pros and cons, even if the agent expects to
+recommend one. The reader needs to see the tradeoff space.
+
+## 6. The Ungrounded Recommendation
+
+**Symptom.** The recommendations section contains imperative statements
+("use library X", "adopt pattern Y") that are not tied to any specific
+finding above.
+
+**Detection cue.** Recommendations cannot be traced back to a numbered
+finding or cited source.
+
+**Remediation.** Each recommendation MUST reference at least one finding
+by name or section heading. Use this format:
+
+```markdown
+1. Adopt `defineRelations` for the new schema work.
+   - Based on finding: "Drizzle v1 deprecates `relations()` in favor of
+     `defineRelations` (verified, 0.95)"
+   - Tradeoff: minor migration cost; offset by ergonomics + future-proof.
+```
+
+## 7. The Forgotten Codebase
+
+**Symptom.** Research output cites web sources extensively but never
+references the existing codebase, ADRs, or BRAIN memory. The
+recommendation contradicts a decision already recorded in ADR-XXX.
+
+**Detection cue.** No `.cleo/adrs/`, `packages/`, or `cleo memory find`
+references in the citations.
+
+**Remediation.** ALWAYS run a codebase + BRAIN sweep before opening the
+web. Even when the topic is "external", the project has likely already
+made related decisions that constrain the answer space. ADRs are
+canonical — overriding them requires explicit consensus, not silent
+research recommendation.
+
+## 8. The Manifest Stuffer
+
+**Symptom.** The pipeline_manifest entry's `key_findings` array contains
+20+ items, half of which are minor or duplicative. The orchestrator's
+briefing surface chokes on the noise.
+
+**Detection cue.** `key_findings` length > 7 or contains items shorter
+than 8 words.
+
+**Remediation.** `key_findings` is for the orchestrator's roll-up — 3-7
+sentence-length, action-oriented items only. Detail belongs in the
+output file. If a finding cannot be summarized in one sentence, it is
+two findings.
+
+## 9. The Premature Completion
+
+**Symptom.** Task is marked complete; the output file says "research
+complete" but the recommendations are vague ("further investigation
+needed", "more work required") with no specific followup IDs.
+
+**Detection cue.** Manifest status is `complete` but the file contains
+phrases like "TBD", "future work", or "to be determined".
+
+**Remediation.** If research cannot reach actionable recommendations,
+the manifest status MUST be `partial` or `blocked`, NOT `complete`.
+Specific gaps belong in `needs_followup` as concrete task descriptions,
+not as soft prose in the file body.
+
+## 10. The Format Drift
+
+**Symptom.** Output file does not match the template in SKILL.md.
+Sections are renamed, the manifest entry uses old field names, or the
+file location is wrong.
+
+**Detection cue.** Validator script fails or the orchestrator reports
+"could not parse manifest entry".
+
+**Remediation.** Re-read SKILL.md's "Output File Format" and "Manifest
+Entry Format" sections before writing. The downstream consumers are
+brittle by design — they trust the format and will reject anything
+unexpected.

package/skills/ct-research-agent/references/citation-and-evidence.md

@@ -0,0 +1,140 @@
+# Citation and Evidence
+
+Research is only useful if it is verifiable. This reference defines the
+evidence ladder, citation format, and confidence labels that every research
+finding in CLEO MUST carry. The downstream consumers — `ct-spec-writer`,
+`ct-consensus-voter`, the orchestrator's HITL gates — rely on these signals
+to weight findings correctly.
+
+## Evidence Ladder
+
+Findings sit on a five-rung ladder. Each finding in the output file MUST be
+marked with the strongest rung that applies.
+
+| Rung | Label | Meaning | Citable? |
+|------|-------|---------|----------|
+| 5 | `verified` | Reproduced locally or confirmed in two independent canonical sources | Yes |
+| 4 | `documented` | Confirmed in one canonical source (official docs, RFC, source code) | Yes |
+| 3 | `reported` | Stated in a credible community source (named blog, conference talk, well-cited GitHub issue) | Yes, with caveat |
+| 2 | `anecdotal` | Stated in an uncredentialed source (random blog, forum post) | No — needs corroboration |
+| 1 | `hypothesis` | Inferred but not verified | Never |
+
+Findings at rung 1-2 MUST live in a separate `## Hypotheses` section, never
+mixed with verified findings. The spec writer downstream will silently treat
+all findings as verified facts unless the rung labels are explicit.
+
+## Canonical Sources by Domain
+
+| Domain | Canonical source |
+|--------|------------------|
+| HTTP/REST semantics | IETF RFCs (RFC 7230-7235, RFC 9110) |
+| TLS/crypto | RFC + IANA registries + NIST publications |
+| JavaScript language | ECMAScript spec (tc39.es) + MDN |
+| TypeScript | typescript-go source or microsoft/TypeScript |
+| Node.js APIs | nodejs.org/api/* + Node source code |
+| Library X | github.com/<owner>/<repo> README + docs + release notes |
+| CLEO architecture | `.cleo/adrs/ADR-*.md` (project-internal canon) |
+| CLEO past decisions | `cleo memory find` + `.cleo/agent-outputs/` |
+| Cloud platforms (AWS/GCP/Azure) | Vendor's "what's new" page + product docs |
+
+Blog posts and Medium articles are NOT canonical — they are interpretive
+layer that may have drifted from the source.
+
+## Citation Format Standards
+
+Every citable finding includes at minimum: source identifier, retrieval
+location, and (where relevant) retrieval date.
+
+### Web Source
+
+```markdown
+According to the [Next.js 15 caching docs](https://nextjs.org/docs/app/building-your-application/caching),
+the default fetch cache behavior changed from `force-cache` to `no-store`.
+Retrieved 2026-05-19.
+```
+
+### Official Repository
+
+```markdown
+The `defineRelations` API was introduced in
+[drizzle-team/drizzle-orm@e2b9c1a](https://github.com/drizzle-team/drizzle-orm/commit/e2b9c1a)
+and replaces the legacy `relations()` helper.
+```
+
+### Project-Internal (ADR)
+
+```markdown
+ADR-065 §3 establishes the PR-gated release pipeline — direct pushes to
+`main` are prohibited (`.cleo/adrs/ADR-065-release-pipeline.md`).
+```
+
+### Project-Internal (Code)
+
+```markdown
+The current implementation in `packages/core/src/store/openCleoDb.ts:42-78`
+routes all DB opens through a single chokepoint per Decision D003.
+```
+
+### Project-Internal (BRAIN)
+
+```markdown
+BRAIN observation `O-mpd07uma-0` records that pub1-diagnoser correctly
+refused under broken dispatcher — confirming the protocol-correct refusal
+pattern is exercising at agent-level.
+```
+
+### Context7 Fetch
+
+```markdown
+Context7 query `/vercel/next.js/v15` against the question "how do I set
+revalidation interval" returns the `revalidate` segment-config option as
+the canonical mechanism.
+```
+
+## Conflict Handling
+
+When two canonical sources disagree, the research output MUST surface the
+conflict rather than silently picking one. Recommended pattern:
+
+```markdown
+### Finding: Default cache behavior in Next.js 15
+
+- The [official caching docs](https://nextjs.org/docs/app/.../caching)
+  state the default is `no-store`.
+- The [release notes for 15.0](https://nextjs.org/blog/next-15) describe
+  the change but also mention a `staleTimes` config that softens it.
+- Resolution: the default IS `no-store`, but `staleTimes` can restore
+  per-segment caching when explicitly configured.
+```
+
+Conflict surfaces are the most valuable research output — they prevent
+downstream consumers from making decisions on partial information.
+
+## Confidence Labels
+
+In addition to the evidence rung, each `key_findings` entry in the manifest
+SHOULD carry a confidence band when the rung is below 4. The orchestrator
+uses this for HITL gating in `ct-consensus-voter`.
+
+| Confidence | Meaning |
+|------------|---------|
+| 0.9–1.0 | Verified — multiple canonical sources agree |
+| 0.7–0.9 | High — one canonical source, no conflicts |
+| 0.5–0.7 | Medium — community sources agree, no canonical |
+| 0.3–0.5 | Low — single source or conflicting evidence |
+| 0.0–0.3 | Speculation — hypothesis only, not citable |
+
+The manifest entry MUST reflect these in `key_findings`:
+
+```json
+{
+  "key_findings": [
+    "Next.js 15 default cache is no-store (verified, 0.95)",
+    "staleTimes config can restore caching (documented, 0.85)",
+    "Migration path for existing apps requires per-route audit (reported, 0.6)"
+  ]
+}
+```
+
+Downstream skills filter by confidence — `ct-spec-writer` ignores findings
+below 0.5 unless the user explicitly opts in.