diff --git a/docs/oddkit/IMPL-A-explain-mode-annotation.md b/docs/oddkit/IMPL-A-explain-mode-annotation.md index c68d89a7..85da9bec 100644 --- a/docs/oddkit/IMPL-A-explain-mode-annotation.md +++ b/docs/oddkit/IMPL-A-explain-mode-annotation.md @@ -6,11 +6,16 @@ exposure: internal tier: 3 voice: neutral stability: evolving +status: superseded tags: ["oddkit", "implementation", "epistemic-modes"] --- # Implementation Instruction Set A +**Superseded (E0005.1):** The `explain` action described here was never implemented as a standalone tool. The concept of epistemic mode annotation is handled by `oddkit_orient`, which returns `current_mode` and `mode_confidence` in every response. + +--- + ## Lightly annotate oddkit explain output with detected epistemic mode --- diff --git a/docs/oddkit/IMPL-B-mode-headers.md b/docs/oddkit/IMPL-B-mode-headers.md index d85cb510..d77368e3 100644 --- a/docs/oddkit/IMPL-B-mode-headers.md +++ b/docs/oddkit/IMPL-B-mode-headers.md @@ -6,11 +6,16 @@ exposure: internal tier: 3 voice: neutral stability: evolving +status: superseded tags: ["oddkit", "implementation", "epistemic-modes"] --- # Implementation Instruction Set B +**Superseded (E0005.1):** Mode headers described here were not implemented. Explicit mode declaration is handled by the `declared_mode` parameter in `oddkit_orient`. + +--- + ## Add optional epistemic mode headers in conversations --- diff --git a/docs/oddkit/IMPL-content-addressed-caching.md b/docs/oddkit/IMPL-content-addressed-caching.md index 9b019542..34d799b8 100644 --- a/docs/oddkit/IMPL-content-addressed-caching.md +++ b/docs/oddkit/IMPL-content-addressed-caching.md @@ -6,12 +6,17 @@ exposure: internal tier: 2 voice: neutral stability: evolving +status: implemented tags: ["oddkit", "implementation", "caching", "content-addressed", "anti-cache-lying"] derives_from: "odd/constraint/anti-cache-lying.md" --- # Implementation: Replace TTL Caching with Content-Addressed Storage in OddKit +**Implemented:** Content-addressed caching with commit-SHA-keyed storage is live in oddkit v0.14.0. The `invalidate_cache` action was replaced by `cleanup_storage`, which is storage hygiene only — never required for correctness. + +--- + > OddKit's TTL-based baseline cache must be replaced with commit-SHA-keyed immutable storage. The current strategy served stale canon for days undetected and its `invalidate_cache` action only cleared `.zip` files (see `docs/incidents/oddkit-stale-cache-2026-02.md`). The target: on every session's first request, fetch the current commit SHA (one lightweight call), use it as the storage namespace, serve from storage only when the SHA matches, and fetch fresh when it doesn't. No TTL. No staleness window. No flush for correctness. `invalidate_cache` becomes orphan cleanup or is removed entirely. --- diff --git a/docs/oddkit/epistemic-instructions.md b/docs/oddkit/epistemic-instructions.md index e8dcf773..eaec9ea6 100644 --- a/docs/oddkit/epistemic-instructions.md +++ b/docs/oddkit/epistemic-instructions.md @@ -13,7 +13,7 @@ oddkit is a compliance surface, not an epistemic engine. oddkit MUST: -- obey the Epistemic Contract (`odd://contract/epistemic-contract`) +- obey the Epistemic Contract (`odd/contract/epistemic-contract.md`, URI: `odd://contract/epistemic-contract`) - derive behavior from documented artifacts - surface which rule authorized a move - refuse to act when prerequisites are unmet diff --git a/docs/oddkit/modes.md b/docs/oddkit/modes.md index 56d9e60e..42419696 100644 --- a/docs/oddkit/modes.md +++ b/docs/oddkit/modes.md @@ -6,6 +6,7 @@ exposure: nav tier: 2 voice: neutral stability: evolving +epoch: E0005 tags: ["oddkit", "agents", "epistemic-modes"] --- @@ -17,7 +18,8 @@ tags: ["oddkit", "agents", "epistemic-modes"] This document depends on: -- **Canon: Epistemic Modes** +- **Canon: Epistemic Modes** — `canon/definitions/epistemic-modes.md` +- **Canon: Axioms** — `canon/values/axioms.md` (values-first grounding for mode behavior) If Canon changes, this document must adapt. @@ -61,13 +63,13 @@ Refusals MUST cite the epistemic reason, not a tool limitation. ## Interaction with Other oddkit Capabilities -- **Librarian** respects mode by: +- **Search / Get / Catalog** (`oddkit_search`, `oddkit_get`, `oddkit_catalog`) respects mode by: - preferring governing docs in Planning - allowing broader sources in Exploration -- **Validation** triggers only in Execution +- **Validate** (`oddkit_validate`) triggers only in Execution -- **Promotions** occur only after repeated Execution outcomes +- ~~**Promotions**~~ — Historical concept from the lane era; not present in the current oddkit action set. --- diff --git a/docs/oddkit/prompts/epistemic-guide.md b/docs/oddkit/prompts/epistemic-guide.md index d8823e53..b2884438 100644 --- a/docs/oddkit/prompts/epistemic-guide.md +++ b/docs/oddkit/prompts/epistemic-guide.md @@ -15,7 +15,7 @@ tags: ["oddkit", "prompt", "mcp", "epistemics", "guide", "orchestration"] ## Description -This MCP prompt composes four epistemic tools — `oddkit_orient`, `oddkit_challenge`, `oddkit_gate`, and `oddkit_encode` — into a coherent guidance flow. It turns a chat assistant into a sparring partner that helps users think clearly, avoid premature commitment, and make durable decisions. +OddKit exposes 12 tools organized in four clusters. This MCP prompt specifically orchestrates the four epistemic core tools — `oddkit_orient`, `oddkit_challenge`, `oddkit_gate`, and `oddkit_encode` — into a coherent guidance flow. It turns a chat assistant into a sparring partner that helps users think clearly, avoid premature commitment, and make durable decisions. The remaining tools (discovery, implementation bookends, maintenance) are used directly by agents and documented below. The prompt does not replace the tools. Models that never read this prompt can still call each tool independently and get useful results. This prompt is an optimization layer for models that support MCP prompts — it sequences tool calls, interprets combined results, and maintains epistemic continuity across a conversation. @@ -34,6 +34,40 @@ You operate inside an Outcomes-Driven Development (ODD) system. Knowledge must b | `oddkit_gate` | Check transition readiness | Before any phase change. Evaluates boundary exit and entry conditions. | | `oddkit_encode` | Record durable decisions | After a decision is reached. Captures what was decided, rejected, and why. | +## Full Tool Surface + +OddKit exposes 12 actions organized in four clusters. This prompt orchestrates the epistemic core, but agents should be aware of the full surface: + +### Discovery — Finding and Retrieving Canon + +| Tool | Purpose | +|------|---------| +| `oddkit_search` | Semantic search by meaning — find docs without knowing paths | +| `oddkit_get` | Fetch a specific document by URI — returns full content | +| `oddkit_catalog` | List all docs with counts, categories, and start-here suggestions | + +Most agent sessions start here. Use search when exploring, get when you have a URI, catalog for corpus overview. + +### Epistemic Core — Reasoning About What You Find + +The four tools above — orient, challenge, gate, encode. See [The Four Tools](#the-four-tools) and [Flow](#flow) for orchestration details. + +### Implementation Bookends — Before and After Coding + +| Tool | Purpose | +|------|---------| +| `oddkit_preflight` | Pre-implementation check: relevant docs, constraints, definition of done | +| `oddkit_validate` | Post-implementation check: verify completion claim against required artifacts | + +Preflight before implementing. Validate before claiming done. These are mandatory per AGENTS.md. + +### System Maintenance + +| Tool | Purpose | +|------|---------| +| `oddkit_version` | Current version and baseline URL — diagnostic | +| `oddkit_cleanup_storage` | Storage hygiene — clears orphaned cache data (never required for correctness) | + ## Flow ### 1. Orient First @@ -111,6 +145,7 @@ Encourage the user to name what was rejected and why. The most durable records i - Choose between valid options - Override human judgment - Replace domain expertise with process +- Orchestrate discovery or implementation tools — those are used directly by agents - Add ceremony for its own sake The guide clears the epistemic path. The user walks it. diff --git a/docs/oddkit/tools/oddkit_catalog.md b/docs/oddkit/tools/oddkit_catalog.md new file mode 100644 index 00000000..d263e150 --- /dev/null +++ b/docs/oddkit/tools/oddkit_catalog.md @@ -0,0 +1,81 @@ +--- +uri: oddkit://tools/catalog +title: "oddkit_catalog" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "catalog", "discovery", "navigation"] +--- + +# oddkit_catalog + +> List all available documentation with counts, categories, and start-here suggestions. + +## Description + +`oddkit_catalog` provides a high-level map of the entire documentation corpus. It returns total document counts, a breakdown between canon and baseline, the full set of categories (derived from tags), and a curated list of start-here entry points for new users or agents. + +This tool answers the question "what exists?" without returning any document content. It is the right starting point when orienting in an unfamiliar repo or verifying corpus shape after structural changes. For actual document content, follow up with `oddkit_search` (by topic) or `oddkit_get` (by URI). + +## When to Use + +- Understanding the size and shape of the documentation corpus +- Finding entry points when starting work in an unfamiliar repo +- Verifying document counts after structural changes or migrations +- Discovering available categories before running a targeted search +- Orienting a new agent to the repo's documentation landscape + +## Tool Definition + +**Name:** `oddkit_catalog` + +**Description:** Lists available documentation with categories, counts, and start-here suggestions. Returns total document counts (canon vs. baseline), category distribution from tags, and curated entry points. Use to understand corpus shape, find starting points, or verify doc counts. Does not return document content — use search or get for that. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline." + } + }, + "required": [] +} +``` + +### Response Shape + +```json +{ + "action": "catalog", + "result": { + "total": "number — total documents in the corpus", + "canon": "number — documents classified as canon", + "baseline": "number — documents from the baseline (remote main branch)", + "categories": [ + "string — category names derived from document tags" + ], + "start_here": [ + "string — file paths recommended as entry points" + ] + } +} +``` + +## Behavioral Rules + +1. **Return counts and categories, not content.** Catalog provides structural metadata only. For document content, use `oddkit_search` or `oddkit_get`. +2. **Start-here docs are curated entry points.** These are documents explicitly marked as starting points for new users or agents. They represent the recommended reading order for orientation. +3. **Categories reflect tag distribution.** The categories list is derived from frontmatter tags across all indexed documents. It represents what the corpus covers, not a fixed taxonomy. +4. **Report canon vs. baseline breakdown.** The distinction between canon (immutable governing documents) and baseline (all indexed documents from remote main) is always surfaced. +5. **Lightweight and side-effect free.** Catalog reads index metadata only. It does not modify state, fetch document content, or trigger reindexing. + +## Canon References + +- `klappy://canon/README` — Canon root document, typically appears in start-here suggestions +- `klappy://canon/epistemic-modes` — Epistemic modes that inform how agents orient using catalog results diff --git a/docs/oddkit/tools/oddkit_challenge.md b/docs/oddkit/tools/oddkit_challenge.md index f206a325..1f39fa28 100644 --- a/docs/oddkit/tools/oddkit_challenge.md +++ b/docs/oddkit/tools/oddkit_challenge.md @@ -39,56 +39,51 @@ This tool operationalizes the epistemic challenge constraint (`klappy://canon/ep { "type": "object", "properties": { - "claim": { + "input": { "type": "string", "description": "The claim, assumption, or proposal to challenge. State it as the claimant would." }, - "claim_type": { + "mode": { "type": "string", - "enum": ["assertion", "assumption", "proposal", "completion_claim", "scope_decision"], - "description": "Optional. The nature of what is being challenged. Helps calibrate proportional pressure." + "enum": ["exploration", "planning", "execution"], + "description": "Optional. Epistemic mode for proportional challenge." }, - "context": { + "canon_url": { "type": "string", - "description": "Optional. Surrounding context — current mode, prior decisions, relevant constraints, or evidence already gathered." - }, - "stakes": { - "type": "string", - "enum": ["low", "moderate", "high", "irreversible"], - "description": "Optional. How consequential this claim is. Higher stakes trigger more rigorous challenge. Defaults to moderate." + "description": "Optional. GitHub repo URL for canon override." } }, - "required": ["claim"] + "required": ["input"] } ``` -### Response Shape +### Response Shape (Observed) ```json { - "challenged": "string — restated version of the claim being tested", - "tensions": [ - { - "source": "string — canon reference, prior decision, or evidence that creates tension", - "description": "string — what the tension is", - "type": "contradiction | gap | drift | scope_mismatch | weak_evidence" - } - ], - "missing_evidence": [ - { - "what": "string — evidence that would strengthen or refute the claim", - "smallest_artifact": "string — the cheapest artifact that would increase certainty" - } - ], - "risks": [ - { - "risk": "string — an unexamined risk exposed by the challenge", - "severity": "low | moderate | high", - "mitigation": "string — what would reduce this risk" - } - ], - "next_step": "string — one actionable step to increase certainty", - "posture": "SUPPORTED | INSUFFICIENT_EVIDENCE | CONTESTED" + "action": "challenge", + "result": { + "status": "CHALLENGED", + "claim_type": "string — inferred type: observation | assertion | assumption | proposal", + "tensions": [ + "string — tensions with canon or prior decisions" + ], + "missing_prerequisites": [ + "string — evidence or prerequisites not yet provided" + ], + "challenges": [ + "string — specific questions that would need answers to proceed" + ], + "suggested_reframings": [ + "string — alternative framings that would be stronger" + ], + "canon_constraints": [ + { + "citation": "string — file path#Section Name", + "quote": "string — relevant excerpt from canon" + } + ] + } } ``` diff --git a/docs/oddkit/tools/oddkit_cleanup_storage.md b/docs/oddkit/tools/oddkit_cleanup_storage.md new file mode 100644 index 00000000..4e2c9130 --- /dev/null +++ b/docs/oddkit/tools/oddkit_cleanup_storage.md @@ -0,0 +1,78 @@ +--- +uri: oddkit://tools/cleanup_storage +title: "oddkit_cleanup_storage" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "maintenance", "storage", "cleanup", "cache"] +--- + +# oddkit_cleanup_storage + +> Storage hygiene — clears orphaned cached data from old commit SHAs. Never required for correctness. + +## Description + +`oddkit_cleanup_storage` removes orphaned storage namespaces keyed to commit SHAs that are no longer current. It is a garbage collection operation, not a correctness operation. The system serves correct content regardless of whether cleanup has run, because content-addressed storage ensures that a SHA mismatch always triggers a fresh fetch. + +This tool exists because OddKit's storage model keys all cached artifacts to the commit SHA of the baseline branch (see `docs/oddkit/IMPL-content-addressed-caching.md`). Over time, old SHA-keyed namespaces accumulate as the baseline advances. Cleanup removes these orphans to reclaim storage space. It does not affect what content is served — that is determined solely by the current SHA. + +This tool evolved from the former `invalidate_cache` action, which was a correctness tool that attempted to flush stale content. The content-addressed storage redesign made correctness-oriented flushing unnecessary. Unlike `invalidate_cache`, `cleanup_storage` is never needed for correct operation. See `docs/oddkit/IMPL-content-addressed-caching.md` for the full design rationale and the incident that motivated the change. + +## When to Use + +- When storage is growing large and orphaned SHA namespaces should be reclaimed +- As periodic maintenance (not urgent — accumulation is bounded and harmless) +- Never for correctness — if results seem stale, the issue is elsewhere (check the current SHA, not the cache) + +## Tool Definition + +**Name:** `oddkit_cleanup_storage` + +**Description:** Storage hygiene — clears orphaned cached data from old commit SHAs. NOT required for correctness. Content-addressed caching ensures fresh content is served automatically when the baseline changes. This is a garbage collection operation that removes storage namespaces keyed to SHAs that are no longer current. Safe to skip entirely. May take time for large caches. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override. If not provided, uses the default configured canon repository." + } + }, + "required": [] +} +``` + +### Response Shape + +```json +{ + "action": "cleanup_storage", + "result": { + "status": "cleaned | nothing_to_clean", + "removed_items": "number — count of orphaned storage namespaces removed" + } +} +``` + +> **Note:** This response shape is approximate. The tool timed out during testing on a large cache. The structure is documented based on the tool's described purpose from the MCP server and the content-addressed caching implementation document. + +## Behavioral Rules + +1. **Does NOT affect correctness.** The system serves correct content based on the current commit SHA regardless of whether cleanup has run. If results seem stale, do not call cleanup — investigate the SHA resolution instead. +2. **May take time for large caches.** Cleanup iterates over stored namespaces and compares them to the current SHA. Large accumulated caches may cause the operation to take significant time or time out. +3. **Safe to skip entirely.** This is a hygiene operation. Skipping it indefinitely has no effect on the truthfulness or accuracy of served content. Storage space is the only cost of not running it. +4. **Cleans orphaned SHA-keyed namespaces.** Only removes storage keyed to commit SHAs that are no longer the current baseline SHA. The current SHA's storage is never touched. +5. **Not a correctness recovery tool.** Unlike the former `invalidate_cache`, this tool cannot and should not be used to "fix" stale results. Content-addressed storage makes stale results structurally impossible when the SHA resolution is correct. +6. **No partial cleanup risk.** Because all artifacts are keyed to the same SHA namespace, cleanup removes entire namespaces atomically — there is no risk of clearing some artifacts while leaving others stale (the failure mode of the former `invalidate_cache`). + +## Canon References + +- `klappy://odd/constraint/anti-cache-lying` — The constraint that drove the content-addressed storage redesign +- `klappy://docs/oddkit/impl-content-addressed-caching` — Full design rationale, incident background, and acceptance criteria +- `klappy://canon/values/axioms` — Axiom 1 (Reality Is Sovereign) — the system must not serve stale content as truth diff --git a/docs/oddkit/tools/oddkit_encode.md b/docs/oddkit/tools/oddkit_encode.md index 8ae7cc6f..d5f87bfc 100644 --- a/docs/oddkit/tools/oddkit_encode.md +++ b/docs/oddkit/tools/oddkit_encode.md @@ -40,69 +40,53 @@ This tool operationalizes the canon constraint that epistemic decisions must be { "type": "object", "properties": { - "decision": { + "input": { "type": "string", - "description": "What was decided. State the decision clearly and completely." - }, - "type": { - "type": "string", - "enum": ["scope_closure", "boundary_definition", "refusal_condition", "default_assumption", "done_criteria", "evidence_standard", "insight", "constraint"], - "description": "The kind of epistemic decision being encoded." - }, - "rejected": { - "type": "array", - "items": { - "type": "object", - "properties": { - "option": { "type": "string", "description": "What was rejected" }, - "reason": { "type": "string", "description": "Why it was rejected" } - }, - "required": ["option", "reason"] - }, - "description": "Optional. Alternatives that were considered and rejected. Including rejections prevents future re-litigation." - }, - "evidence": { - "type": "string", - "description": "Optional. Evidence that supported the decision. If the decision remains a hypothesis, state that explicitly." + "description": "The decision, insight, or boundary to capture. State it clearly. Include 'because...' for rationale." }, "context": { "type": "string", - "description": "Optional. The goal, phase, or situation in which this decision was made." + "description": "Optional. Supporting context — goal, phase, alternatives considered, or constraints." }, - "invalidation_conditions": { - "type": "array", - "items": { "type": "string" }, - "description": "Optional. Conditions under which this decision should be revisited. Makes the decision challengeable without requiring re-litigation from scratch." + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override." } }, - "required": ["decision", "type"] + "required": ["input"] } ``` -### Response Shape +### Response Shape (Observed) ```json { - "record": { - "id": "string — stable identifier for this decision record", - "decision": "string — the encoded decision", - "type": "scope_closure | boundary_definition | refusal_condition | default_assumption | done_criteria | evidence_standard | insight | constraint", - "decided_at": "string — timestamp or phase marker", - "rejected": [ - { - "option": "string — what was rejected", - "reason": "string — why" - } - ], - "evidence": "string — supporting evidence or 'hypothesis' if none", - "invalidation_conditions": [ - "string — when to revisit" - ], - "status": "active | superseded | invalidated" - }, - "warnings": [ - "string — missing rejections, weak evidence, or other encoding quality signals" - ] + "action": "encode", + "result": { + "status": "ENCODED", + "artifact": { + "title": "string — truncated title derived from the decision", + "type": "decision", + "decision": "string — the full decision text", + "rationale": "string — extracted rationale, or '(not provided)' if missing", + "constraints": [ + "string — constraints created by this decision" + ], + "status": "draft | active", + "timestamp": "string — ISO 8601 timestamp" + }, + "quality": { + "level": "insufficient | adequate | strong", + "score": "number — 1-5 quality score", + "max_score": 5, + "gaps": [ + "string — missing elements that would improve the record" + ], + "suggestions": [ + "string — specific improvements to strengthen the encoding" + ] + } + } } ``` diff --git a/docs/oddkit/tools/oddkit_gate.md b/docs/oddkit/tools/oddkit_gate.md index dcff49d5..b6245833 100644 --- a/docs/oddkit/tools/oddkit_gate.md +++ b/docs/oddkit/tools/oddkit_gate.md @@ -39,67 +39,48 @@ This tool operationalizes two canon constraints: boundary transitions require de { "type": "object", "properties": { - "from_mode": { + "input": { "type": "string", - "enum": ["exploration", "planning", "execution"], - "description": "The current epistemic mode being exited." + "description": "The proposed transition (e.g., 'ready to build', 'moving to planning'). Describe the transition and any supporting evidence." }, - "to_mode": { + "context": { "type": "string", - "enum": ["exploration", "planning", "execution"], - "description": "The target epistemic mode being entered." + "description": "Optional. What has been decided so far — prior decisions, artifacts, or evidence." }, - "evidence": { + "canon_url": { "type": "string", - "description": "Optional. Evidence, artifacts, or context that support the transition. What has been produced, decided, or validated so far." - }, - "goal": { - "type": "string", - "description": "Optional. The goal or initiative being transitioned. Provides context for evaluating readiness." + "description": "Optional. GitHub repo URL for canon override." } }, - "required": ["from_mode", "to_mode"] + "required": ["input"] } ``` -### Response Shape +### Response Shape (Observed) ```json { - "gate_status": "pass | block | conditional", - "transition": { - "from": "exploration | planning | execution", - "to": "exploration | planning | execution", - "direction": "forward | revert | skip" - }, - "boundary_exit": { - "obligations_met": [ - "string — current-mode obligations that have been satisfied" - ], - "obligations_unmet": [ - "string — current-mode obligations that remain unsatisfied" - ], - "closures_needed": [ - "string — decisions or scope items that must be encoded before leaving" - ] - }, - "boundary_entry": { - "prerequisites": [ - "string — what must exist before entering the target mode" - ], - "active_constraints": [ - "string — constraints that govern behavior in the target mode" - ], - "risks_to_accept": [ - "string — risks inherent to the target mode that must be explicitly acknowledged" - ] - }, - "conditions_to_proceed": [ - "string — specific conditions that, if met, would change a block to pass" - ], - "warnings": [ - "string — drift signals, skipped phases, or assumption smuggling detected" - ] + "action": "gate", + "result": { + "status": "PASS | BLOCK", + "transition": { + "from": "string — detected or declared source mode", + "to": "string — detected or declared target mode" + }, + "prerequisites": { + "met": [ + "string — prerequisites satisfied" + ], + "unmet": [ + "string — prerequisites not yet satisfied" + ], + "unknown": [ + "string — prerequisites that could not be evaluated" + ], + "required_met": "number — count of met prerequisites", + "required_total": "number — count of total prerequisites" + } + } } ``` diff --git a/docs/oddkit/tools/oddkit_get.md b/docs/oddkit/tools/oddkit_get.md new file mode 100644 index 00000000..45c88955 --- /dev/null +++ b/docs/oddkit/tools/oddkit_get.md @@ -0,0 +1,93 @@ +--- +uri: oddkit://tools/get +title: "oddkit_get" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "retrieval", "get", "lookup"] +--- + +# oddkit_get + +> Fetch a specific canonical document by its URI, returning full content and a content hash. + +## Description + +`oddkit_get` retrieves a single document by its `klappy://` URI. It returns the full markdown content — including frontmatter — along with a content hash that enables content-addressed caching. This is the direct-access complement to `oddkit_search`: use search when you don't know the URI, use get when you do. + +The content hash is a short, stable identifier derived from the document's content. If the hash has not changed since your last retrieval, the content has not changed. This enables agents to cache documents locally and skip re-reading when the hash matches, without risking stale data. + +## When to Use + +- When you know the exact `klappy://` URI and need the full document +- After `oddkit_search` returns a URI and you need the complete content +- When you need to verify a content hash has not changed since a prior retrieval +- When citing a document and you need the full text to quote accurately + +## Tool Definition + +**Name:** `oddkit_get` + +**Description:** Fetch a canonical document by klappy:// URI. Returns full content, including frontmatter, and a content hash for cache validation. Use when you know the exact URI — after search returns a hit, when a canon reference needs reading, or when verifying content freshness via hash comparison. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "input": { + "type": "string", + "description": "A klappy:// URI identifying the document to fetch (e.g., 'klappy://canon/values/axioms')." + }, + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline." + } + }, + "required": ["input"] +} +``` + +### Response Shape + +**Success:** + +```json +{ + "action": "get", + "result": { + "path": "string — file path relative to repo root", + "content": "string — full markdown content of the document including frontmatter", + "content_hash": "string — short content-addressed hash for cache validation" + } +} +``` + +**Not found:** + +```json +{ + "action": "get", + "result": { + "error": "string — error message describing what was not found", + "path": "string — the path that was resolved from the URI" + } +} +``` + +## Behavioral Rules + +1. **Only resolve `klappy://` URIs.** Other URI schemes are not supported. If a non-klappy URI is provided, return an error — do not attempt to fetch arbitrary URLs. +2. **Return full document content including frontmatter.** The response includes the complete markdown file as stored in the baseline, not a summary or excerpt. +3. **Content hash enables content-addressed caching.** The hash is derived from the document content. Same hash means same content — agents can skip re-reading when the hash matches a cached version. +4. **Return a clear error for unknown URIs.** If the URI does not resolve to a document, return an error with the resolved path. Do not return empty content or fabricate a document. +5. **Fetch from the baseline, not local state.** Documents are retrieved from the remote main branch, ensuring consistency regardless of local modifications. + +## Canon References + +- `klappy://canon/values/axioms` — Axiom 4 (You Cannot Verify What You Did Not Observe) — get provides direct observation of document state +- `klappy://odd/contract` — System contract defines URI resolution semantics +- `klappy://docs/agents/librarian/trusted-sources` — Trusted source hierarchy for retrieval diff --git a/docs/oddkit/tools/oddkit_orient.md b/docs/oddkit/tools/oddkit_orient.md index 4732cdc4..00d8215c 100644 --- a/docs/oddkit/tools/oddkit_orient.md +++ b/docs/oddkit/tools/oddkit_orient.md @@ -38,49 +38,44 @@ This tool applies the epistemic modes defined in Canon (`klappy://canon/epistemi { "type": "object", "properties": { - "goal": { + "input": { "type": "string", "description": "The goal, idea, or situation to assess. Describe what you are trying to achieve or understand." }, - "context": { + "canon_url": { "type": "string", - "description": "Optional. Relevant prior decisions, artifacts, constraints, or evidence that bear on the goal." - }, - "declared_mode": { - "type": "string", - "enum": ["exploration", "planning", "execution"], - "description": "Optional. The mode the caller believes they are in. If provided, orient will validate this claim against available evidence." + "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline." } }, - "required": ["goal"] + "required": ["input"] } ``` -### Response Shape +### Response Shape (Observed) ```json { - "mode": { - "current": "exploration | planning | execution", - "confidence": "high | moderate | low", - "basis": "string — what evidence or signals determined the mode" - }, - "unresolved": [ - { - "item": "string — what remains open", - "type": "assumption | unknown | tension | dependency", - "impact": "string — why this matters for progression" - } - ], - "questions": [ - "string — specific questions to answer before progressing" - ], - "valid_actions": [ - "string — actions that are legitimate in the current mode" - ], - "warnings": [ - "string — drift signals, mode mismatches, or epistemic smells detected" - ] + "action": "orient", + "result": { + "status": "ORIENTED", + "creed": [ + "string — orientation creed lines from canon/values/orientation.md" + ], + "current_mode": "exploration | planning | execution", + "mode_confidence": "high | moderate | low", + "assumptions": [ + "string — assumptions detected in the input" + ], + "suggested_questions": [ + "string — questions to answer before progressing" + ], + "canon_refs": [ + { + "path": "string — file path#Section Name", + "quote": "string — relevant excerpt from the referenced document" + } + ] + } } ``` diff --git a/docs/oddkit/tools/oddkit_preflight.md b/docs/oddkit/tools/oddkit_preflight.md new file mode 100644 index 00000000..2f230fc4 --- /dev/null +++ b/docs/oddkit/tools/oddkit_preflight.md @@ -0,0 +1,86 @@ +--- +uri: oddkit://tools/preflight +title: "oddkit_preflight" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "preflight", "implementation", "constraints"] +--- + +# oddkit_preflight + +> Pre-implementation check that surfaces relevant docs, constraints, and definition of done before coding begins. + +## Description + +`oddkit_preflight` prepares an agent or operator for implementation by returning the documents, constraints, and definition of done relevant to a described task. Given a description of what is about to be implemented, it ranks available documentation by relevance, surfaces applicable constraints, and returns the definition of done — ensuring the implementer has read the governing material before writing code. + +This tool operationalizes the principle that implementation without context is drift. The returned `start_here` documents are not suggestions — they are the minimum reading required before the described work can proceed with epistemic integrity. Skipping them risks violating constraints that were available but unread. + +For document deliverables, preflight includes the Writing Canon (`klappy://canon/meta/writing-canon`) as an applicable constraint, ensuring progressive disclosure requirements are visible before authoring begins. + +## When to Use + +- Before implementing any feature, fix, or change +- As part of the AGENTS.md mandatory checkpoints (orient → **preflight** → validate) +- When starting work on a new task and needing to know what governs it +- When unsure which constraints apply to a specific type of work +- Before writing documentation, to surface the Writing Canon and structural requirements + +## Tool Definition + +**Name:** `oddkit_preflight` + +**Description:** Pre-implementation check. Returns relevant docs to read, applicable constraints, definition of done, and pitfalls for the described task. The returned start_here documents should be READ before coding. Surfaces constraints ranked by relevance to the specific task. Always returns the definition of done. For document deliverables, includes Writing Canon as a constraint. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "input": { + "type": "string", + "description": "Description of what you are about to implement. Be specific — the more detail provided, the more precisely relevant the returned docs and constraints will be." + } + }, + "required": ["input"] +} +``` + +### Response Shape + +```json +{ + "action": "preflight", + "result": { + "topic": "string — the implementation description echoed back", + "start_here": [ + "string — file paths to docs ranked by relevance to the described task" + ], + "dod": "string — path to the definition of done document", + "constraints": [ + "string — paths to constraint documents applicable to this task" + ], + "docs_available": "number — total docs in the corpus, for awareness" + } +} +``` + +## Behavioral Rules + +1. **Return start_here docs ranked by relevance.** The most relevant documents appear first. Ranking is based on semantic similarity to the described task, not alphabetical order or recency. +2. **Always return the definition of done.** Regardless of the task type, the `dod` field must reference the canonical definition of done. Implementation without knowing what "done" means is not implementation. +3. **Surface constraints applicable to the specific task.** Do not return all constraints — return the subset that governs the described work. Generic constraints (like the constraints README) may be included for orientation. +4. **Return doc count for awareness.** The `docs_available` field tells the caller how large the corpus is, signaling whether the returned subset is narrow (well-targeted) or broad (more reading may be needed). +5. **The returned start_here docs must be read before coding.** Preflight output is not informational — it is prescriptive. The listed documents contain governing material. Ignoring them and proceeding is a policy violation. +6. **Include Writing Canon for document deliverables.** If the described task involves creating or modifying documents, the Writing Canon must appear in the constraints list. + +## Canon References + +- `klappy://canon/constraints/definition-of-done` — The definition of done returned by every preflight +- `klappy://canon/constraints/README` — Index of all constraints, returned when broadly applicable +- `klappy://canon/meta/writing-canon` — Progressive disclosure checklist, included for document deliverables +- `klappy://canon/epistemic-modes` — Mode obligations that inform what "ready to implement" means diff --git a/docs/oddkit/tools/oddkit_search.md b/docs/oddkit/tools/oddkit_search.md new file mode 100644 index 00000000..1b4cd9a6 --- /dev/null +++ b/docs/oddkit/tools/oddkit_search.md @@ -0,0 +1,100 @@ +--- +uri: oddkit://tools/search +title: "oddkit_search" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "search", "retrieval", "discovery"] +--- + +# oddkit_search + +> Semantic search across all canon and baseline documents by meaning, not exact text. + +## Description + +`oddkit_search` finds relevant documents by natural language query or tags. Given a query, it searches the full baseline (remote main branch) and returns ranked results with relevance scores, direct quotes as evidence, and canonical URIs for each hit. + +This tool is the primary discovery mechanism for navigating the corpus. Unlike `oddkit_get`, which requires a known URI, search accepts natural language and returns the most relevant documents — making it the right entry point when you know *what* you need but not *where* it lives. + +Results include both hits (ranked document summaries with scores) and evidence (direct quotes with citations). The evidence section provides ready-to-cite material without requiring a follow-up `oddkit_get` call for simple policy questions. + +## When to Use + +- Finding relevant documents without knowing exact paths or URIs +- Exploring unfamiliar areas of the corpus +- Answering policy questions with cited evidence +- Discovering canon constraints that bear on a current decision +- Locating prior decisions or encoded artifacts on a topic + +## Tool Definition + +**Name:** `oddkit_search` + +**Description:** Search canon and baseline docs by natural language query or tags. Returns ranked results with citations and excerpts. Use when you need to find relevant documents without knowing exact URIs, explore unfamiliar areas, or answer policy questions with evidence. Always prefer this over answering from memory when canon or baseline docs may contain the answer. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "input": { + "type": "string", + "description": "Natural language query or tags to search for. Describe what you are looking for in plain language." + }, + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline." + } + }, + "required": ["input"] +} +``` + +### Response Shape + +```json +{ + "action": "search", + "result": { + "status": "FOUND | NOT_FOUND", + "hits": [ + { + "uri": "oddkit://... — canonical URI for this document", + "path": "string — file path relative to repo root", + "title": "string — document title from frontmatter", + "tags": ["string — tags from frontmatter"], + "score": "number — relevance score (higher is more relevant)", + "snippet": "string — excerpt from the document", + "source": "baseline" + } + ], + "evidence": [ + { + "quote": "string — direct quote from the document", + "citation": "string — path#Section Name", + "source": "baseline" + } + ], + "docs_considered": "number — total documents in the search index" + } +} +``` + +## Behavioral Rules + +1. **Return ranked results by relevance score.** Higher scores indicate stronger semantic match to the query. Results are ordered by descending score. +2. **Include direct quotes as evidence.** Evidence entries provide exact quotes with file path and section citations, ready for use without follow-up retrieval. +3. **Search the baseline, not local state.** Results come from the remote main branch (baseline), ensuring consistency across agents and sessions. +4. **Never invent results.** If no documents match, return `NOT_FOUND` with zero hits. Do not fabricate documents, URIs, or quotes. +5. **Report docs_considered for transparency.** The total number of documents in the search index is always returned, providing corpus size context. +6. **Prefer search over memory for policy questions.** When a question might be answered by canon or baseline docs, search first — do not answer from model knowledge. + +## Canon References + +- `klappy://canon/values/axioms` — Axiom 1 (Reality Is Sovereign) requires retrieval over fabrication +- `klappy://canon/constraints/definition-of-done` — Evidence standards that search helps satisfy +- `klappy://docs/agents/librarian/trusted-sources` — Citation rules governing how search results should be used diff --git a/docs/oddkit/tools/oddkit_validate.md b/docs/oddkit/tools/oddkit_validate.md new file mode 100644 index 00000000..49ff2157 --- /dev/null +++ b/docs/oddkit/tools/oddkit_validate.md @@ -0,0 +1,86 @@ +--- +uri: oddkit://tools/validate +title: "oddkit_validate" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "validation", "completion", "evidence"] +--- + +# oddkit_validate + +> Validate completion claims against required artifacts. Returns VERIFIED or NEEDS_ARTIFACTS. + +## Description + +`oddkit_validate` checks whether a completion claim meets the evidence requirements defined by the Definition of Done. It extracts claims from the input, identifies what artifact types are required, compares them against what was provided, and returns a binary verdict: VERIFIED or NEEDS_ARTIFACTS. + +This tool operationalizes the Definition of Done (`klappy://canon/constraints/definition-of-done`). A claim of completion creates an evidence obligation (Axiom 2 — A Claim Is a Debt). Validate enforces that obligation by refusing to render a VERIFIED verdict until the required artifacts are present. It does not accept partial verdicts — the claim is either fully supported or it has gaps. + +For document deliverables, validate also checks compliance with the Writing Canon (`klappy://canon/meta/writing-canon`), ensuring progressive disclosure structure is present — not just that the file exists. + +## When to Use + +- Before claiming "done" on any task +- As part of the AGENTS.md mandatory checkpoints (orient → preflight → **validate**) +- When a user or agent asserts completion and evidence must be audited +- After producing artifacts, to confirm the evidence set is sufficient +- When reviewing whether a deliverable meets the Definition of Done + +## Tool Definition + +**Name:** `oddkit_validate` + +**Description:** Validates completion claims against required artifacts. Returns VERIFIED or NEEDS_ARTIFACTS with specific gaps. Extracts claims from input, checks for required evidence types (screenshots, test output, recordings, rendered output), and identifies what is missing. Does not render partial verdicts — either the evidence is sufficient or it is not. Per the Definition of Done, requires: change description, verification performed, observed behavior, evidence produced, self-audit completed. For document deliverables, checks Writing Canon compliance. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "input": { + "type": "string", + "description": "The completion claim with artifact references. Describe what was done and reference the evidence produced (file paths, screenshots, test output, commands run)." + } + }, + "required": ["input"] +} +``` + +### Response Shape + +```json +{ + "action": "validate", + "result": { + "verdict": "VERIFIED | NEEDS_ARTIFACTS", + "claims": [ + "string — completion claims extracted from the input" + ], + "provided_artifacts": [ + "string — artifacts referenced in the input" + ], + "gaps": [ + "string — required evidence types that are missing" + ] + } +} +``` + +## Behavioral Rules + +1. **Extract claims explicitly.** Parse the input for specific completion assertions. Do not infer claims that were not stated. +2. **Check against the full Definition of Done.** Every claim is evaluated against the five DoD requirements: change description, verification performed, observed behavior, evidence produced, self-audit completed. Missing any one produces NEEDS_ARTIFACTS. +3. **Binary verdicts only.** The result is VERIFIED or NEEDS_ARTIFACTS. There is no "partially verified," "probably done," or "close enough." Ambiguity resolves to NEEDS_ARTIFACTS. +4. **Name the gaps specifically.** When the verdict is NEEDS_ARTIFACTS, the `gaps` array must contain concrete, actionable descriptions of what is missing (e.g., "visual proof (screenshot or recording)" not "more evidence"). +5. **Check document deliverables against Writing Canon.** If the completion claim involves a document targeting `canon/`, `odd/`, or `docs/`, validate progressive disclosure compliance per `canon/meta/writing-canon.md`. A document that exists but fails structural requirements is not done. +6. **Do not fabricate artifacts.** If the input references evidence that cannot be verified, treat it as provided but note that verification of the artifact itself is the caller's responsibility. + +## Canon References + +- `klappy://canon/constraints/definition-of-done` — The five requirements that define completion +- `klappy://canon/meta/writing-canon` — Progressive disclosure checklist for document deliverables +- `klappy://canon/values/axioms` — Axiom 2 (A Claim Is a Debt) and Axiom 4 (You Cannot Verify What You Did Not Observe) diff --git a/docs/oddkit/tools/oddkit_version.md b/docs/oddkit/tools/oddkit_version.md new file mode 100644 index 00000000..0ce6ada3 --- /dev/null +++ b/docs/oddkit/tools/oddkit_version.md @@ -0,0 +1,71 @@ +--- +uri: oddkit://tools/version +title: "oddkit_version" +audience: operators +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["oddkit", "tool", "epistemics", "version", "maintenance"] +--- + +# oddkit_version + +> Return the current OddKit version and the authoritative baseline target. + +## Description + +`oddkit_version` reports the running OddKit version (semver) and the baseline URL that OddKit is currently fetching canon from. This is a diagnostic tool — it answers "what version am I talking to?" and "where is it getting its documents?" + +The baseline URL indicates the remote source of truth. When OddKit behavior seems unexpected — missing documents, stale content, unfamiliar responses — checking the version and baseline URL is the first diagnostic step. If the baseline URL points to an unexpected branch or repository, that explains the discrepancy. + +## When to Use + +- Diagnosing unexpected OddKit behavior (missing docs, stale content) +- Verifying which baseline source OddKit is serving from +- Checking version compatibility before relying on specific tool features +- Confirming the MCP server is reachable and responding + +## Tool Definition + +**Name:** `oddkit_version` + +**Description:** Returns oddkit version and the authoritative canon target (commit/mode). Use for diagnostics — verifying which version is running, confirming the baseline source URL, or checking that the MCP server is responding. Lightweight call with no side effects. + +### Input Schema + +```json +{ + "type": "object", + "properties": { + "canon_url": { + "type": "string", + "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline." + } + }, + "required": [] +} +``` + +### Response Shape + +```json +{ + "action": "version", + "result": { + "oddkit_version": "string — semver version of the running OddKit instance", + "baseline_url": "string — URL of the remote baseline OddKit fetches documents from" + } +} +``` + +## Behavioral Rules + +1. **Returns current version as semver.** The version string follows semantic versioning and identifies the running OddKit instance. +2. **Baseline URL indicates the document source.** This URL is where OddKit fetches canon and baseline documents from. If it points to an unexpected location, document retrieval behavior will differ accordingly. +3. **Lightweight call with no side effects.** Version does not modify state, trigger reindexing, or fetch documents. It reads local configuration only. +4. **Use as a first diagnostic step.** When other OddKit tools return unexpected results, check version and baseline URL before investigating further. + +## Canon References + +- `klappy://odd/contract` — System contract defines version semantics and baseline resolution