From b6bf1bd5c1de8c211a0c841f2f076448610a7d1c Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 5 Apr 2026 04:28:31 +0000 Subject: [PATCH 1/9] =?UTF-8?q?feat:=20declare=20E0007.1=20=E2=80=94=20Vod?= =?UTF-8?q?ka=20Architecture=20principles=20and=20posture=20lapse=20detect?= =?UTF-8?q?ion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit E0007.1 extends E0007 (From Passive to Proactive) with: - Vodka Architecture: named design pattern for epistemic infrastructure (thin, stateless, domain-agnostic, load-bearing) - Six principle spinoffs with full governance structure: KISS, DRY, Consistency, Maintainability, Prompt Over Code, Antifragile Each follows ritual-is-a-smell template: smell test → failure modes → exclusions → required response - Posture Lapse: meta-governance article for detecting when proactive cognitive rhythm breaks down - Epoch 7.1 declaration document All principles validated by oddkit's own production evidence. Coined 'Vodka Architecture' from speech-to-text transcription error. 9 new documents. Canon grows from 439 to 448. --- .../antifragile-failures-grow-canon.md | 76 ++++++++ .../consistency-same-pattern-every-time.md | 73 ++++++++ canon/principles/dry-canon-says-it-once.md | 72 ++++++++ .../kiss-simplicity-is-the-ceiling.md | 72 ++++++++ ...maintainability-one-person-indefinitely.md | 73 ++++++++ canon/principles/prompt-over-code.md | 79 +++++++++ canon/principles/vodka-architecture.md | 166 ++++++++++++++++++ docs/appendices/epoch-7-1.md | 106 +++++++++++ docs/oddkit/proactive/posture-lapse.md | 114 ++++++++++++ 9 files changed, 831 insertions(+) create mode 100644 canon/principles/antifragile-failures-grow-canon.md create mode 100644 canon/principles/consistency-same-pattern-every-time.md create mode 100644 canon/principles/dry-canon-says-it-once.md create mode 100644 canon/principles/kiss-simplicity-is-the-ceiling.md create mode 100644 canon/principles/maintainability-one-person-indefinitely.md create mode 100644 canon/principles/prompt-over-code.md create mode 100644 canon/principles/vodka-architecture.md create mode 100644 docs/appendices/epoch-7-1.md create mode 100644 docs/oddkit/proactive/posture-lapse.md diff --git a/canon/principles/antifragile-failures-grow-canon.md b/canon/principles/antifragile-failures-grow-canon.md new file mode 100644 index 00000000..1a16f8d8 --- /dev/null +++ b/canon/principles/antifragile-failures-grow-canon.md @@ -0,0 +1,76 @@ +--- +uri: klappy://canon/principles/antifragile-failures-grow-canon +title: "Antifragile — Every Failure Grows the Canon, Never the Server" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "antifragile", "antifragility", "failure", "stress", "learning", "incidents", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, canon/resonance/antifragile.md, canon/values/axioms.md" +complements: "canon/principles/prompt-over-code.md, canon/principles/ritual-is-a-smell.md" +governs: "All failure response decisions in this program" +status: active +--- + +# Antifragile — Every Failure Grows the Canon, Never the Server + +> When oddkit encounters a governance failure — a missed gate, a hallucinated claim, a governance gap — the fix is a document, not a feature. The Progressive Disclosure Failure incident (February 2026) proved this: an agent shipped three canon documents violating every tier of the Writing Canon checklist. The fix was an incident record and an enforcement wiring document. Zero server code changed. The canon grew. The server stayed the same size. Every governance gap closed across seven epochs has been closed by adding knowledge, not code. + +--- + +## Summary — Stress Grows the Knowledge, Not the Infrastructure + +In vodka architecture (`canon/principles/vodka-architecture.md`), antifragility has a specific structural meaning: failures make the knowledge base more comprehensive and the governance more precise without adding a single line of server code. + +This is ODD's application of Taleb's antifragility (`canon/resonance/antifragile.md`), sharpened by a key divergence: ODD requires that stress leave durable artifacts. Pure antifragility without memory produces resilience without wisdom — systems survive shocks repeatedly without becoming more coherent. In vodka architecture, every failure is captured as a document that alters future behavior permanently. The knowledge base absorbs the stress. The server remains unchanged. + +--- + +## Smell Test — How to Detect an Antifragility Violation + +- **"We need to add error handling for this edge case"** as a server code change when the edge case is a governance gap, not a technical bug. If an agent hallucinated because no governance article covered the topic, the fix is a governance article — not an `if` branch in the server. +- **Incident response that modifies the server.** After a governance failure, the first instinct to open the server codebase instead of writing an incident record is the smell. The question to ask: "Is this a technical bug or a governance gap?" Technical bugs get code fixes. Governance gaps get documents. +- **The server growing after each incident.** If you can correlate server complexity growth with incident history — each failure adding a check, a handler, a special case — the server is absorbing stress that the canon should absorb. +- **The same class of failure recurring.** If similar failures keep happening despite previous fixes, the fixes aren't durable. Code fixes are local — they handle the specific case. Canon fixes are systemic — they alter the governance that prevents the class of failure. +- **Post-incident knowledge staying in someone's head.** If the lesson learned from an incident lives in a Slack message, a meeting note, or a person's memory rather than a committed governance document, the system hasn't captured the stress. It will fail the same way again. + +--- + +## Failure Modes — What Breaks When Antifragility Is Violated + +**Server complexity ratchet.** Each incident adds code. Code is never removed. The server grows monotonically with the number of failures encountered. After enough incidents, the server is a palimpsest of historical edge cases — each individually reasonable, collectively incomprehensible. + +**Diagnostic confusion.** When a new failure occurs in an antifragility-violated system, diagnosing it requires understanding both the canon and the accumulated server-side special cases. The debugging surface is the product of the two, not the sum. The next incident is always harder to diagnose than the last. + +**Resilience without wisdom.** The system handles known failure modes (because they're hardcoded) but fails on novel ones (because no generic governance mechanism exists to prevent new classes of error). The system is robust but not antifragile — it survives what it's seen but doesn't improve against what it hasn't. + +**Canon becomes decorative.** If the server handles governance enforcement through code, the canon governance documents become documentation rather than operating rules. Nobody updates them because updating them changes nothing. The system's actual behavior diverges from its documented behavior — a direct violation of Axiom 1 (Reality Is Sovereign). + +--- + +## What Does NOT Count as an Antifragility Violation + +- **Genuine technical bug fixes.** A parsing error, a network timeout handler, a malformed request check — these are infrastructure bugs, not governance gaps. They belong in code. The test: does this fix prevent a *technical* failure or a *governance* failure? Technical fixes go in code. Governance fixes go in the canon. +- **Performance optimizations.** Caching improvements, index rebuilding, query optimization — these are infrastructure maintenance, not stress responses. +- **Server refactoring for clarity.** Simplifying existing code, reducing coupling, improving naming — these make the server more maintainable without adding new behavior. They're housekeeping, not stress absorption. + +--- + +## Required Response When Detected + +1. **Write an incident record.** Capture what happened, why, and what governance gap allowed it. Commit it to the knowledge base. This is the durable artifact that prevents recurrence. +2. **Write or update a governance article.** Express the missing constraint, gate rule, or preflight check as a canon document. The server's generic enforcement surfaces it automatically. +3. **Verify the fix is systemic.** Confirm that the governance article prevents the *class* of failure, not just the specific instance. If the article only prevents the exact same failure, it's too narrow. +4. **Resist the code fix.** If the instinct is "let me just add a check in the server" — stop. Ask: "Can this be expressed as a governance document that the server surfaces generically?" If yes, write the document. If genuinely no, it's a technical bug, not a governance gap. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern +- [Antifragile (Resonance)](klappy://canon/resonance/antifragile) — ODD's application of Taleb's antifragility with the memory divergence +- [Prompt Over Code](klappy://canon/principles/prompt-over-code) — the sibling principle that makes antifragile response possible: governance in documents, not code +- [Ritual Is a Smell](klappy://canon/principles/ritual-is-a-smell) — post-incident checklists that aren't encoded are ritual smells diff --git a/canon/principles/consistency-same-pattern-every-time.md b/canon/principles/consistency-same-pattern-every-time.md new file mode 100644 index 00000000..a0d6f48e --- /dev/null +++ b/canon/principles/consistency-same-pattern-every-time.md @@ -0,0 +1,73 @@ +--- +uri: klappy://canon/principles/consistency-same-pattern-every-time +title: "Consistency — Same Pattern, Every Knowledge Base, Every Time" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "consistency", "portability", "MCP", "interface", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" +complements: "docs/architecture/epistemic-os-layers.md, canon/principles/kiss-simplicity-is-the-ceiling.md" +governs: "All MCP server interfaces and knowledge base serving patterns in this program" +status: active +--- + +# Consistency — Same Pattern, Every Knowledge Base, Every Time + +> The server behaves identically regardless of what knowledge base it serves. Same MCP interface. Same retrieval algorithm. Same encoding format. Same gate mechanism. oddkit proves this: it serves a 400+-document software architecture canon and a 26-document oral theology corpus through the identical interface without modification. Inconsistency — special cases, domain-specific endpoints, knowledge-base-specific behavior — is the earliest symptom of the Flavored Vodka anti-pattern. + +--- + +## Summary — Consistency Makes the Pattern Portable + +In vodka architecture (`canon/principles/vodka-architecture.md`), consistency is the property that makes the pattern portable. Any MCP-compatible tool that learns to work with one oddkit-served knowledge base works with all of them without adaptation. The tool doesn't need to know whether it's querying theology or software architecture — the interface is the same. + +The moment a server introduces a special case for a specific knowledge base, it has acquired a flavor. It is no longer vodka. Domain-specific behavior belongs in the knowledge base documents themselves: governance articles, gate rules, preflight constraints. The server surfaces them generically. + +--- + +## Smell Test — How to Detect a Consistency Violation + +- **"But for THIS knowledge base we need..."** The most common consistency smell. Every special-case argument sounds reasonable in isolation. Collectively, they make the server opinionated. +- **Domain terms in server code.** If the server source contains words like "Bible," "pastoral," "legal," or any domain-specific vocabulary, it has acquired knowledge it shouldn't have. +- **Different behavior for different `canon_url` values.** If the server checks which repo it's serving and adjusts behavior accordingly, consistency is violated. The server should be blind to content. +- **Onboarding friction for new knowledge bases.** If adding a new KB requires server-side configuration, custom endpoints, or domain-specific setup beyond pointing at a repo URL, the interface isn't consistent. +- **Tools that work with one KB but break with another.** If an agent workflow built against the software canon fails when pointed at the theology KB, the interface promised consistency it didn't deliver. + +--- + +## Failure Modes — What Breaks When Consistency Is Violated + +**Portability collapse.** The entire value proposition of vodka architecture — serve any knowledge base through the same interface — disintegrates. Each KB becomes a custom integration. The server stops being infrastructure and becomes a collection of domain-specific adapters. + +**Tool fragility.** Agents and integrations built against one KB's behavior fail when pointed at another. The interface contract is no longer trustworthy. Developers stop building against the interface and start building against specific KBs. + +**Combinatorial maintenance.** Each special case multiplies the testing surface. N knowledge bases × M special cases = a maintenance burden that grows geometrically. The single maintainer (`canon/principles/maintainability-one-person-indefinitely.md`) cannot sustain it. + +--- + +## What Does NOT Count as a Consistency Violation + +- **Knowledge bases having different content, tags, and structure.** That's expected diversity — the whole point is that different domains produce different documents. The server serves them identically. +- **Different governance rules across KBs.** A theology KB might have strict citation requirements while a strategy KB doesn't. That's governance diversity expressed in the *documents*, not the *server*. The server surfaces both generically. +- **Performance differences based on KB size.** A 400-document KB will naturally be slower to search than a 26-document one. Performance scaling is not a consistency violation — it's physics. + +--- + +## Required Response When Detected + +1. **Identify the special case.** What domain-specific behavior exists in the server? Name it precisely. +2. **Move it to the knowledge base.** Express the special case as a governance document, gate rule, or preflight constraint within the KB that needs it. The server surfaces it generically — the KB owns the specificity. +3. **Verify portability.** Point the server at a different KB and confirm the same interface works without modification. +4. **Remove the server-side special case.** If the governance document approach works, delete the server code. Don't leave it commented out — remove it entirely. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern (see: Flavored Vodka anti-pattern) +- [Epistemic OS Layers](klappy://docs/architecture/epistemic-os-layers) — the four-layer separation that consistency enables +- [KISS — Simplicity Is the Ceiling](klappy://canon/principles/kiss-simplicity-is-the-ceiling) — special cases are complexity in disguise diff --git a/canon/principles/dry-canon-says-it-once.md b/canon/principles/dry-canon-says-it-once.md new file mode 100644 index 00000000..6dd75232 --- /dev/null +++ b/canon/principles/dry-canon-says-it-once.md @@ -0,0 +1,72 @@ +--- +uri: klappy://canon/principles/dry-canon-says-it-once +title: "DRY — The Canon Says It Once, the Server Never Repeats It" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "DRY", "dont-repeat-yourself", "governance", "drift", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, canon/constraints/oddkit-prompt-pattern.md" +complements: "canon/principles/prompt-over-code.md, canon/values/axioms.md" +governs: "All governance rule placement decisions in this program" +status: active +--- + +# DRY — The Canon Says It Once, the Server Never Repeats It + +> If a governance rule exists in the knowledge base, the server must not re-encode that rule in its own logic. Every duplicated rule is a drift surface — the canon version and the server version will eventually disagree, and the server version will win silently because it executes first. oddkit proves this: when the Writing Canon checklist was added to the knowledge base, preflight and validate surfaced it automatically — zero server code changed. Governance is fetched at runtime, never baked in. + +--- + +## Summary — Duplication Creates Silent Drift + +Don't Repeat Yourself in vodka architecture (`canon/principles/vodka-architecture.md`) means one thing precisely: governance lives in the knowledge base, and the server retrieves it. The server never contains governance. + +The danger of duplication is not redundancy — it is divergence. When the same rule exists in two places, updates hit one and miss the other. The server version executes before the canon version is even consulted. The canon says one thing; the system does another. Nobody notices until the gap causes a failure, and by then the drift has compounded across every interaction since the divergence began. + +--- + +## Smell Test — How to Detect a DRY Violation + +- **Governance strings in server code.** If the server source contains phrases like "always check," "must include," or any natural-language rule that also exists in a canon document, the rule is duplicated. +- **Server behavior that doesn't change when the canon changes.** If you update a governance article and the system's behavior stays the same, something in the server is overriding or duplicating the canon's version. +- **System prompt fragments hardcoded in deployment.** If the creed, axioms, or any governance text is baked into the server's system prompt template rather than fetched from the canon at runtime, it's DRY-violating duplication. This is the specific anti-pattern `canon/constraints/oddkit-prompt-pattern.md` was written to prevent. +- **Two documents saying the same thing in different words.** Duplication within the canon itself is also a DRY smell — it creates the same drift risk, just between documents instead of between document and code. + +--- + +## Failure Modes — What Breaks When DRY Is Violated + +**Silent policy drift.** The server enforces rule version 1 while the canon has evolved to version 3. Users experience governance that contradicts the published canon. Trust erodes because the system says one thing and does another — a direct violation of Axiom 1 (Reality Is Sovereign). + +**Update blindness.** Operators update the canon expecting the system to change. It doesn't. They update it again, more aggressively. Still nothing. Eventually they stop trusting the canon as the source of truth and start editing server code directly — which compounds the drift. + +**Forensic confusion.** When something goes wrong, the investigation asks "what are the rules?" The canon says X. The server does Y. Which is authoritative? In DRY-violating systems, the answer is "whichever executes first" — which is always the server, making the canon decorative. + +--- + +## What Does NOT Count as a DRY Violation + +- **The server knowing about markdown structure.** Parsing frontmatter, extracting sections, indexing by tags — this is structural knowledge about the *format*, not the *content*. The server must understand how documents are organized. It must not understand what they say. +- **Retrieval algorithm parameters in server config.** BM25 weighting, result limits, cache TTLs — these are infrastructure settings, not governance rules. They shape how the canon is accessed, not what the canon says. +- **The server's own operational logic.** Rate limiting, error handling, authentication — these are server concerns, not governance duplication. + +--- + +## Required Response When Detected + +1. **Identify the authoritative version.** It's always the canon. If the canon version is outdated, update the canon — not the server. +2. **Remove the server-side duplicate.** Replace hardcoded governance with a runtime fetch from the canon. +3. **Verify with a change test.** Update the canon document and confirm the system's behavior changes without any server deployment. If it doesn't, the duplication isn't fully removed. +4. **Add a regression marker.** If the duplication crept in once, it will try again. Note the pattern in the relevant governance doc so future reviews catch it. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern +- [Prompt Pattern for oddkit-Powered Applications](klappy://canon/constraints/oddkit-prompt-pattern) — governance fetched at runtime, never hardcoded +- [Prompt Over Code](klappy://canon/principles/prompt-over-code) — the sibling principle: governance in documents, not code diff --git a/canon/principles/kiss-simplicity-is-the-ceiling.md b/canon/principles/kiss-simplicity-is-the-ceiling.md new file mode 100644 index 00000000..ef655e9c --- /dev/null +++ b/canon/principles/kiss-simplicity-is-the-ceiling.md @@ -0,0 +1,72 @@ +--- +uri: klappy://canon/principles/kiss-simplicity-is-the-ceiling +title: "KISS — Simplicity Is the Ceiling, Not the Floor" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "KISS", "simplicity", "design", "composability", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" +complements: "canon/principles/ritual-is-a-smell.md, canon/principles/maintainability-one-person-indefinitely.md" +governs: "All MCP servers, tools, and orchestration layers in this program" +status: active +--- + +# KISS — Simplicity Is the Ceiling, Not the Floor + +> Every action, endpoint, or abstraction in an epistemic server must justify its existence against the alternative of not existing. oddkit has ten composable actions — not twenty, not fifty — because every action beyond the minimum is complexity the server carries forever. Prefer fewer tools that compose well over many tools that each handle a narrow case. If the server requires explanation, it has already failed. + +--- + +## Summary — Simplicity Is Structural, Not Aspirational + +Keep It Simple is not a preference. In vodka architecture (`canon/principles/vodka-architecture.md`), it is a structural constraint: the server's behavior must be obvious from its surface area. The proof is oddkit itself: the same ten actions serve a 400+-document software architecture canon and a 26-document oral theology corpus without modification. No action was added for theology. No action was removed for software. + +The ceiling metaphor matters. Simplicity is not the floor you start from and leave behind as the system matures. It is the ceiling you must not exceed. Growth happens in the knowledge base, not the server. When a new capability is needed, the first question is always: can this be composed from existing actions? + +--- + +## Smell Test — How to Detect a KISS Violation + +- **"We need a new action for X"** when X can be accomplished by composing existing actions. orient + search + challenge already covers "evaluate this proposal" — a dedicated `evaluate` action would duplicate their composition. +- **Agent confusion about which tool to use.** When an agent hesitates between two similar actions, the surface area has grown ambiguous. Ten actions is clear. Twenty creates selection paralysis. +- **Documentation growing faster than the knowledge base.** If explaining the server takes more words than explaining the canon it serves, the server has become the product instead of the infrastructure. +- **"Let me explain how this works."** If a new user or agent needs a tutorial to use the server, the server is too complex. oddkit's ten actions are self-describing from their names. + +--- + +## Failure Modes — What Breaks When KISS Is Violated + +**Action sprawl.** Each new action adds documentation, testing surface, edge cases, and cognitive load for every agent that uses the server. The cost is not the action itself — it's the combinatorial complexity of N actions that might interact. + +**Composition death.** When specialized actions exist, agents stop composing. They reach for the specific tool instead of thinking about what sequence of primitives would work. The system loses flexibility because specialized actions are narrower than the compositions they replaced. + +**Maintenance drag.** Every action is a maintenance surface the single maintainer carries indefinitely. Complexity that enters the server never leaves voluntarily — it must be actively removed, which is harder than not adding it. + +--- + +## What Does NOT Count as a KISS Violation + +- **A knowledge base growing to thousands of documents.** That's growth in the right layer — the canon, not the server. +- **Complex governance rules in the canon.** Governance complexity belongs in documents, not server code. A 50-rule gate checklist is not a server complexity problem. +- **Genuinely irreducible new capability.** If composition truly cannot serve a need and the need is grounded in epistemic discipline (not domain convenience), a new action is justified. The burden of proof is on the proposer. + +--- + +## Required Response When Detected + +1. **Attempt composition first.** Document the composition that serves the need using existing actions. +2. **If composition fails, document why.** The failure must be structural ("these actions cannot be sequenced to produce X") not preferential ("it would be easier with a dedicated action"). +3. **If justified, apply the removal test.** Can the server still function without it? If yes, it's convenience, not necessity. +4. **Audit existing actions.** A new action proposal is an opportunity to check whether existing actions have drifted beyond their original scope. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern +- [Ritual Is a Smell](klappy://canon/principles/ritual-is-a-smell) — complexity often compensates for missing simplicity +- [Maintainability — One Person, Indefinitely](klappy://canon/principles/maintainability-one-person-indefinitely) — every action added is maintenance carried forever diff --git a/canon/principles/maintainability-one-person-indefinitely.md b/canon/principles/maintainability-one-person-indefinitely.md new file mode 100644 index 00000000..099fbb87 --- /dev/null +++ b/canon/principles/maintainability-one-person-indefinitely.md @@ -0,0 +1,73 @@ +--- +uri: klappy://canon/principles/maintainability-one-person-indefinitely +title: "Maintainability — One Person, Indefinitely" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "maintainability", "sustainability", "single-maintainer", "cloudflare-worker", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" +complements: "canon/principles/ritual-is-a-smell.md, canon/principles/kiss-simplicity-is-the-ceiling.md" +governs: "All infrastructure sizing and complexity decisions in this program" +status: active +--- + +# Maintainability — One Person, Indefinitely + +> A vodka layer must be maintainable by a single person without heroics. If the server requires a team to operate, it has grown beyond its function. oddkit proves this: it is a single Cloudflare Worker, one deployment, one maintainer. The canon has passed through seven epochs of growth — from dozens of documents to over 400 — without the server requiring a rewrite for any of them. The knowledge base grows. The server stays the same size. + +--- + +## Summary — The Server Cannot Outgrow Its Maintainer + +In vodka architecture (`canon/principles/vodka-architecture.md`), maintainability is the constraint that keeps everything else honest. A server that is simple, DRY, consistent, and antifragile but requires three engineers to keep running has failed the most basic test: can one person sustain this indefinitely? + +This constraint cascades into every decision. Prefer standard protocols over custom ones — because custom protocols require custom knowledge to debug. Prefer configuration over code — because configuration changes don't need a developer. The knowledge base can grow by an order of magnitude without the server growing at all — because the server doesn't know about the documents. + +--- + +## Smell Test — How to Detect a Maintainability Violation + +- **Deployment anxiety.** If deploying the server feels risky, requires a checklist, or prompts "let me make sure everything's ready" — the deployment is too complex for one person to do confidently. +- **"Don't touch that."** If any part of the codebase is understood by only one person and feared by everyone else, the system has accumulated implicit knowledge that isn't sustainable. +- **Debugging takes hours, not minutes.** If diagnosing a server issue requires tracing through multiple abstraction layers, checking caches, or reconstructing state — the server has grown beyond what one person can reason about quickly. +- **Feature freeze from fear.** If the maintainer avoids changes because they're afraid of breaking something, the system has become fragile in the wrong layer. The canon should be where changes happen freely. The server should be stable enough that changes are rare and small. +- **"We need another person for this."** The most direct smell. If the server requires specialized knowledge, on-call rotation, or team coordination to maintain, it has outgrown vodka architecture. + +--- + +## Failure Modes — What Breaks When Maintainability Is Violated + +**Bus factor collapse.** If the single maintainer is unavailable and nobody else can operate the server, the system is down. But the fix is not "add more maintainers" — it's "simplify until anyone can maintain it." A codebase simple enough for one person is simple enough for a replacement. + +**Maintenance debt accumulation.** Complex servers accumulate TODO items, deferred refactors, and known issues that the maintainer carries in their head. Each one is invisible state — a ritual smell (`canon/principles/ritual-is-a-smell.md`). The server should be simple enough that its state is fully visible in the code. + +**Growth coupling.** When the server's complexity grows proportionally to the knowledge base, every new document makes the server harder to maintain. This is the opposite of vodka architecture — the server should be *indifferent* to KB growth. + +--- + +## What Does NOT Count as a Maintainability Violation + +- **The knowledge base requiring domain expertise to maintain.** That's the KB's job, not the server's. A theology KB needs a theologian. A legal KB needs a lawyer. The server needs a single developer who understands markdown and MCP — regardless of domain. +- **Occasional complexity in the canon's governance rules.** Complex gate rules, multi-step preflight checklists, nuanced sensitivity constraints — all of this lives in the knowledge base. The server surfaces it generically. Governance complexity is not server complexity. +- **Standard infrastructure operations.** DNS updates, TLS certificate rotation, Cloudflare dashboard configuration — these are platform operations, not server maintenance. They don't count against the server's complexity budget. + +--- + +## Required Response When Detected + +1. **Simplify, don't staff.** The response to "this is too complex for one person" is never "add another person." It's "remove complexity until one person can handle it." +2. **Audit for implicit state.** List everything the maintainer carries in their head that isn't in the code or documentation. Each item is either a documentation gap or unnecessary complexity. +3. **Apply the fresh-eyes test.** Could a developer who has never seen this codebase deploy and maintain it within a day? If not, what's blocking them? Remove those blockers. +4. **Move complexity to the canon.** If the server has grown complex because it handles governance logic, move that logic to governance documents. If it handles domain logic, move that to the KB. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern +- [Ritual Is a Smell](klappy://canon/principles/ritual-is-a-smell) — heroic maintenance is a ritual compensating for missing design +- [KISS — Simplicity Is the Ceiling](klappy://canon/principles/kiss-simplicity-is-the-ceiling) — maintainability's structural prerequisite diff --git a/canon/principles/prompt-over-code.md b/canon/principles/prompt-over-code.md new file mode 100644 index 00000000..af8ec36b --- /dev/null +++ b/canon/principles/prompt-over-code.md @@ -0,0 +1,79 @@ +--- +uri: klappy://canon/principles/prompt-over-code +title: "Prompt Over Code — Fully Programmable Governance Without Changing the Server" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["canon", "principle", "prompt-over-code", "convention-over-configuration", "governance", "programmable", "vodka-architecture", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/principles/vodka-architecture.md, docs/appendices/convention-requires-an-enforcer.md, canon/constraints/oddkit-prompt-pattern.md" +complements: "odd/prompt-architecture.md, canon/principles/ritual-is-a-smell.md, canon/principles/dry-canon-says-it-once.md" +governs: "All governance rule implementation decisions in this program" +status: active +--- + +# Prompt Over Code — Fully Programmable Governance Without Changing the Server + +> oddkit's entire governance model is prompt over code in production. The Writing Canon gate, the Identity of Integrity creed, the relational sensitivity constraint, the guide posture rules — all are markdown documents in the knowledge base, not code paths in the server. When a new governance constraint is needed, the response is to write an article, not deploy code. The server's generic enforcement mechanisms (gate, preflight, validate) surface *whatever the canon says* at the right moment. Governance is fully programmable by writing documents — no deployment, no code review, no server restart. + +--- + +## Summary — Write a Document, Change the Behavior + +Prompt over code is vodka architecture's (`canon/principles/vodka-architecture.md`) most distinctive property, and oddkit is its proof of concept. The principle: governance belongs in prompts and documents, not in application code. The server is the enforcer. The canon is the law. Changing the law means writing a document, not changing the enforcer. + +This is the principle that `docs/appendices/convention-requires-an-enforcer.md` sharpens: convention alone is insufficient because conventions are optional. A governance document that says "always check the Writing Canon checklist" is a convention. oddkit's preflight action that surfaces that document at the right moment is the enforcer. But the enforcer is generic — it enforces whatever the canon says, not specific rules hardcoded into the server. + +The practical implication is radical: the system's governance is fully programmable by anyone who can write a markdown file. No TypeScript. No deployment pipeline. No server restart. Commit a governance article and oddkit surfaces it automatically at the correct epistemic moment. + +--- + +## Smell Test — How to Detect a Prompt Over Code Violation + +- **Opening the server codebase to add a governance rule.** The most direct violation. If the response to "we need a new constraint" is "let me add a check in the server code," the architecture has failed. The response should be "let me write a governance article." +- **PRs that add behavioral logic for specific policies.** If a pull request to the server repo contains `if` branches that enforce domain-specific rules, governance has leaked into code. +- **Governance that requires deployment to change.** If updating a rule requires a server deployment rather than a canon commit, the rule is in the wrong layer. +- **Non-developers unable to modify governance.** If only people who can write TypeScript can change the system's rules, governance is code-locked. Prompt over code means governance is document-locked — anyone who can write markdown can change the rules. +- **"We'll need to update the server when we add that rule."** This sentence is the smell. The server should never need to know about specific rules. + +--- + +## Failure Modes — What Breaks When Prompt Over Code Is Violated + +**Governance becomes invisible.** Rules buried in code are discoverable only by reading code. They don't appear in search results, aren't surfaced by orient, and can't be challenged or validated. The governance exists but is operationally invisible to the agents and humans who need to follow it. + +**Deployment coupling.** Every governance change becomes a deployment event. Deployments have risk, require testing, and create downtime windows. Governance changes should be instant (commit to canon) not ceremonial (PR → review → merge → deploy → verify). + +**Knowledge concentration.** When governance lives in code, only developers understand the rules. Domain experts — the people who should own governance — are locked out. The system becomes developer-governed by default, not domain-expert-governed by design. + +**DRY violation cascade.** Code-based governance inevitably duplicates canon-based governance, triggering silent drift (`canon/principles/dry-canon-says-it-once.md`). The canon says the rule one way. The code enforces it another way. Users experience the code version. The canon becomes decorative. + +--- + +## What Does NOT Count as a Prompt Over Code Violation + +- **Server code for epistemic primitives.** The search algorithm, encoding format, gate mechanism, retrieval logic — these are infrastructure that *implements* the enforcement, not governance that *defines* the rules. BM25 scoring belongs in code. What gets scored belongs in the canon. +- **Server configuration for operational parameters.** Cache TTLs, rate limits, API keys, deployment settings — these are operational infrastructure, not governance rules. +- **Bug fixes in the server.** If search returns wrong results due to a parsing bug, the fix is code. If search returns wrong results because the governance docs are ambiguous, the fix is a document. + +--- + +## Required Response When Detected + +1. **Write the governance article.** Express the rule as a document in the knowledge base with the same structure as existing governance: clear assertion, smell test, failure modes, required response. +2. **Verify generic surfacing.** Confirm that oddkit's existing actions (gate, preflight, validate, orient) surface the new article at the right moment without server changes. +3. **If surfacing fails, fix the server generically.** If the existing actions can't surface the new rule, the fix is improving the generic surfacing mechanism — not adding a domain-specific code path. The improvement should benefit all governance articles, not just this one. +4. **Remove the code-based governance.** If governance existed in code before, remove it. Don't leave it as a "backup" — that creates the DRY violation it was meant to prevent. + +--- + +## See Also + +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the parent design pattern +- [Convention Requires an Enforcer](klappy://docs/appendices/convention-requires-an-enforcer) — why convention alone is insufficient +- [Prompt Pattern for oddkit-Powered Applications](klappy://canon/constraints/oddkit-prompt-pattern) — governance fetched at runtime, never hardcoded +- [DRY — The Canon Says It Once](klappy://canon/principles/dry-canon-says-it-once) — the sibling principle prompt over code protects +- [Prompt Architecture](klappy://odd/prompt-architecture) — how intent scales without monolithic prompts diff --git a/canon/principles/vodka-architecture.md b/canon/principles/vodka-architecture.md new file mode 100644 index 00000000..59eb8ae9 --- /dev/null +++ b/canon/principles/vodka-architecture.md @@ -0,0 +1,166 @@ +--- +uri: klappy://canon/principles/vodka-architecture +title: "Vodka Architecture — The Design Pattern for Epistemic Infrastructure" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable +tags: ["canon", "architecture", "design-pattern", "vodka", "stateless", "thin-layer", "epistemic-infrastructure", "KISS", "DRY", "antifragile", "convention-over-configuration", "maintainability"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/values/axioms.md, canon/principles/ritual-is-a-smell.md, canon/resonance/antifragile.md, docs/appendices/convention-requires-an-enforcer.md" +complements: "docs/architecture/epistemic-os-layers.md, odd/prompt-architecture.md, canon/constraints/oddkit-prompt-pattern.md" +governs: "All MCP servers, knowledge base serving infrastructure, and orchestration layers in this program" +status: active +--- + +# Vodka Architecture — The Design Pattern for Epistemic Infrastructure + +> Infrastructure so thin and clean it disappears into whatever it carries. A stateless server over a stateful canon. No opinion about the domain — all the opinion about epistemic discipline. Remove it and everything breaks. Add more and you ruin it. The constraint test: if the server has grown thick, has acquired domain opinions, or can be removed without consequence, the architecture has failed. Named from a transcription error that turned "oddkit" into "vodka" — which works better as a metaphor than it should. + +--- + +## Summary — The Server Carries Everything and Tastes Like Nothing + +Vodka Architecture is a design pattern for epistemic infrastructure: the serving layer between a knowledge base and the agents or tools that consume it. The pattern demands that this layer be thin, stateless, and domain-agnostic — all substance comes from the knowledge base it serves, never from the server itself. The server's only job is epistemic discipline: retrieval, gating, encoding, validation. It enforces *how* knowledge is accessed and governed, never *what* the knowledge contains. + +This is not minimalism for its own sake. It is a structural constraint derived from two observations: (1) thick serving layers accumulate domain opinions that conflict with the knowledge bases they serve, creating drift between what the canon says and what the server delivers; and (2) infrastructure that grows beyond its function becomes the bottleneck it was supposed to eliminate. A vodka layer that adds flavor has stopped being infrastructure and started being a product — which changes the maintenance burden, the coupling surface, and the failure modes. + +The pattern applies to oddkit, to any knowledge base MCP server built with oddkit conventions, and to any future orchestration layer in this program. + +--- + +## The Design Heritage — Six Principles, Validated by the System That Embodies Them + +Vodka Architecture did not emerge from a single insight. It is the convergence point of six established design principles, each contributing a specific constraint that shapes the pattern. None of them alone produces vodka architecture. Together, they make anything else structurally wrong. + +These are not theoretical influences. oddkit is the running proof of each one — dogfooding every principle in production. The evidence is the system itself. + +### KISS — Simplicity Is the Ceiling, Not the Floor + +oddkit has ten epistemic actions. Not twenty. Not fifty. Ten composable operations that cover orientation, retrieval, governance, encoding, and validation for any domain. The proof: the same ten actions serve a 400+-document software architecture canon and a 26-document oral theology corpus without modification. Every action beyond the minimum is complexity the server carries forever. If a new capability can be composed from existing actions, it does not become a new action. *([Full article](klappy://canon/principles/kiss-simplicity-is-the-ceiling))* + +### DRY — The Canon Says It Once, the Server Never Repeats It + +oddkit fetches the creed, the axioms, and every gate rule from the canon at runtime. None of these are hardcoded in server logic. The proof: when the Writing Canon checklist was added to the knowledge base, oddkit's preflight and validate actions surfaced it automatically — zero server code changed. If the same governance existed in both the canon and the server, the server version would win silently because it executes first. That silent divergence is the drift DRY prevents. This is a direct application of `canon/constraints/oddkit-prompt-pattern.md`: governance is fetched, never baked in. *([Full article](klappy://canon/principles/dry-canon-says-it-once))* + +### Consistency — Same Pattern, Every Knowledge Base, Every Time + +oddkit serves `klappy/klappy.dev` (391 documents, software architecture) and `klappy/oral-theology-kb` (26 documents, Stringer's dissertations) through the identical MCP interface. Same retrieval algorithm. Same encoding format. Same gate mechanism. The proof: any MCP-compatible tool that learns to work with one oddkit-served knowledge base works with all of them without adaptation. Inconsistency — special cases, domain-specific endpoints, knowledge-base-specific behavior — is the earliest symptom of the Flavored Vodka anti-pattern. *([Full article](klappy://canon/principles/consistency-same-pattern-every-time))* + +### Maintainability — One Person, Indefinitely + +oddkit is a single Cloudflare Worker. One deployment. One person maintains it. The knowledge base has grown from dozens of documents to over 400 without the server growing proportionally — because the server doesn't know about the documents. It knows about markdown, frontmatter, and retrieval. The documents are the knowledge base's concern. The proof: the canon has passed through seven epochs of growth and restructuring. The server has not required a rewrite for any of them. *([Full article](klappy://canon/principles/maintainability-one-person-indefinitely))* + +### Prompt Over Code — Fully Programmable Governance Without Changing the Server + +This is vodka architecture's most distinctive property, and oddkit is its proof of concept. oddkit's entire governance model is prompt over code in production: the Writing Canon gate, the Identity of Integrity creed, the relational sensitivity constraint, the guide posture rules — all are markdown documents in the knowledge base. When a new governance constraint is needed, the correct response is to write an article, not to add a code path. The server's generic enforcement mechanisms (gate, preflight, validate) surface *whatever the canon says* at the right moment. The governance is fully programmable by writing documents — no deployment, no code review, no server restart. + +This is what `docs/appendices/convention-requires-an-enforcer.md` sharpens: convention alone is insufficient because conventions are optional. The enforcement mechanism makes conventions real. But the enforcement mechanism is generic — it enforces the canon's rules, not its own. The server is the enforcer. The canon is the law. *([Full article](klappy://canon/principles/prompt-over-code))* + +### Antifragile — Every Failure Grows the Canon, Never the Server + +When oddkit encountered the Progressive Disclosure Failure incident (February 2026) — where an agent shipped three canon documents that violated every tier of the Writing Canon checklist — the fix was not a new code path in the server. The fix was a new document: `docs/incidents/progressive-disclosure-failure-2026-02.md`, plus enforcement wiring in `docs/oddkit/IMPL-writing-canon-gate.md`. The canon grew. The server stayed the same size. The proof: every governance gap oddkit has encountered across seven epochs has been closed by adding knowledge, not code. This is ODD's application of antifragility (`canon/resonance/antifragile.md`): stress is captured as durable artifacts that alter future behavior. The server surfaces those artifacts. It does not absorb them. *([Full article](klappy://canon/principles/antifragile-failures-grow-canon))* + +This is the convergence: KISS keeps the server simple. DRY keeps governance in one place. Consistency makes the pattern portable. Maintainability keeps it sustainable. Prompt over code makes governance fully programmable without touching the server. Antifragility ensures the canon grows while the server stays thin. Together, they produce infrastructure that disappears into what it serves — which is the definition of vodka architecture. And oddkit is the proof that the convergence works, not just in theory, but across seven epochs, 400+ documents, and multiple domains. + +--- + +## The Three Properties of Vodka Architecture + +### Stateless Server, Stateful Canon + +The server holds no durable state. All truth lives in the knowledge base — git-versioned, content-addressable, inspectable. The server reads the canon on every request (or caches ephemerally for performance), but never writes to it through its own initiative. If the server process dies and restarts, nothing is lost. If the canon is swapped for a different repository, the server serves it identically. + +This property derives from Axiom 1 (Reality Is Sovereign): the actual state of the knowledge base is always the source of truth, not any cached representation the server maintains. A server that accumulates its own state has created a second source of truth — and now two things can disagree. + +### Zero Domain Opinion + +The server has no opinion about what the knowledge base contains. It knows about markdown, frontmatter, retrieval algorithms, epistemic actions (orient, search, gate, encode, challenge, validate). It does not know about Bible translation, pastoral care, software architecture, or any other domain. All domain flavor comes from the knowledge base. + +This means the same server can serve a Bible translation knowledge base, an oral theology corpus, a venture strategy canon, or a personal journal — without modification. The server is the glass. The knowledge base is the drink. + +The constraint: the moment a server-side code path contains an `if` branch that checks for a specific domain term, tag, or content pattern to change behavior, the architecture has been violated. Domain-specific behavior belongs in the knowledge base documents themselves (as governance articles, gate rules, or preflight constraints), not in the server. + +### Removal Breaks Everything, Addition Ruins It + +A correctly built vodka layer is load-bearing. Without it, the knowledge base is just files — no search, no retrieval, no governance, no encoding. The layer is what makes the knowledge *accessible* and *trustworthy* rather than merely *present*. + +But the layer must also resist growth. Every feature added to the server is a maintenance surface, a coupling point, and a potential source of drift. The design constraint is not "keep it small" but "keep it *thin*" — the distinction matters. A thin layer can serve a massive knowledge base. A small layer might not have enough capability. Thin means: every function in the server exists to serve the epistemic discipline, and no function exists for any other reason. + +The test: for any proposed addition to the server, ask — "Does this serve epistemic discipline, or does it serve the domain?" If the answer is domain, the addition belongs in the knowledge base, not the server. + +--- + +## Anti-Patterns — How Vodka Architecture Fails + +### The Flavored Vodka Problem + +The server begins accumulating domain-specific logic. "Just this one helper for Bible verse parsing." "Just this one rule for pastoral confidentiality." Each addition is individually reasonable. Collectively, they make the server opinionated — it now works better for some knowledge bases than others. It has acquired a flavor. The infrastructure has become a product. + +The fix is always the same: move the logic into the knowledge base as a governance document, a preflight constraint, or a gate rule. The server serves governance documents the same way it serves any other document. The domain expertise lives in the content, not the container. + +### The Growing Glass Problem + +The server grows thick with features that serve infrastructure rather than domain — but still violate the pattern. Caching layers, analytics dashboards, user management, multi-tenancy, deployment orchestration. Each is legitimately infrastructure. Each adds surface area. The glass gets heavier until it's harder to hold than the drink. + +The discipline: infrastructure features are acceptable only when they serve the epistemic discipline layer — retrieval performance, governance enforcement, encoding fidelity. Infrastructure that serves operational convenience (monitoring, billing, user management) belongs in a separate service, not in the vodka layer. + +### The Vestigial Layer Problem + +The server exists but isn't load-bearing. Removing it changes nothing — agents access the knowledge base directly, governance happens in system prompts, encoding happens client-side. The server has become ceremony — infrastructure that exists because it was built, not because it's needed. + +The fix: if the layer isn't load-bearing, remove it. Vodka architecture isn't an aspiration — it's a test. Does the server carry the system? Or does the system carry the server? + +--- + +## Examples — Where the Pattern Applies + +**oddkit:** The canonical example. A stateless MCP server serving 400+ documents from a git-backed knowledge base. Epistemic actions (orient, search, challenge, gate, encode, validate) are domain-agnostic. The same server serves software architecture canon and oral theology dissertations without modification. + +**oral-theology-mcp:** A standalone MCP server built with oddkit conventions to serve a 26-document knowledge base of oral theology source material. Surface/archive retrieval pattern, YAML frontmatter, section-level extraction. The server knows about markdown structure and retrieval. It knows nothing about theology. + +**Any future knowledge base MCP server:** The pattern is the template. If someone builds a knowledge base for legal research, pastoral counseling, or venture strategy, the serving layer follows vodka architecture. Domain expertise goes in the documents. The server stays thin. + +--- + +## The Origin — Accident as Metaphor + +The name emerged from a speech-to-text transcription error during a voice session on April 4, 2026. "oddkit" was rendered as "vodka." The accidental metaphor was immediately recognized as more precise than any intentional name: + +You don't taste vodka in a good cocktail — it's just the clean base that carries everything else. You don't *see* oddkit in a well-governed knowledge base — it's just the governance layer that makes everything trustworthy. The metaphor works because the design principle *is* the metaphor: infrastructure that disappears into what it serves. + +--- + +## The Constraint Test — Three Questions + +Before any change to a vodka-architecture server, answer these three questions: + +1. **Has the server grown thick?** If the codebase is expanding faster than the knowledge base it serves, something is wrong. The server should be the thinnest layer in the stack. + +2. **Has the server acquired domain opinions?** If the server behaves differently for different knowledge bases — not because of their structure, but because of their *content* — the architecture is violated. + +3. **Can the server be removed without consequence?** If yes, the layer isn't load-bearing and shouldn't exist. If no, the layer is doing its job. This is the only acceptable answer. + +--- + +## See Also + +### Design Heritage — Full Articles + +- [KISS — Simplicity Is the Ceiling, Not the Floor](klappy://canon/principles/kiss-simplicity-is-the-ceiling) +- [DRY — The Canon Says It Once, the Server Never Repeats It](klappy://canon/principles/dry-canon-says-it-once) +- [Consistency — Same Pattern, Every Knowledge Base, Every Time](klappy://canon/principles/consistency-same-pattern-every-time) +- [Maintainability — One Person, Indefinitely](klappy://canon/principles/maintainability-one-person-indefinitely) +- [Prompt Over Code — Fully Programmable Governance Without Changing the Server](klappy://canon/principles/prompt-over-code) +- [Antifragile — Every Failure Grows the Canon, Never the Server](klappy://canon/principles/antifragile-failures-grow-canon) + +### Related Canon + +- [Antifragile (Resonance)](klappy://canon/resonance/antifragile) — ODD's application of antifragility: stress captured as durable artifacts, not absorbed by infrastructure +- [Convention Requires an Enforcer](klappy://docs/appendices/convention-requires-an-enforcer) — why convention-over-configuration is insufficient without mechanical enforcement +- [Epistemic OS Layers](klappy://docs/architecture/epistemic-os-layers) — the four-layer separation of concerns that vodka architecture serves +- [Ritual Is a Smell](klappy://canon/principles/ritual-is-a-smell) — the complementary principle: if correctness depends on repeated human memory, the design is compensating +- [Prompt Architecture](klappy://odd/prompt-architecture) — how intent scales without collapsing into monolithic prompts +- [Prompt Pattern for oddkit-Powered Applications](klappy://canon/constraints/oddkit-prompt-pattern) — governance fetched at runtime, never hardcoded diff --git a/docs/appendices/epoch-7-1.md b/docs/appendices/epoch-7-1.md new file mode 100644 index 00000000..5b0d8085 --- /dev/null +++ b/docs/appendices/epoch-7-1.md @@ -0,0 +1,106 @@ +--- +uri: klappy://docs/appendices/epoch-7-1 +title: "Epoch 7.1 — Vodka Architecture and Principled Governance" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: stable +tags: ["odd", "epochs", "vodka-architecture", "design-pattern", "principles", "governance", "posture-lapse", "epoch-7", "epoch-7.1"] +epoch: E0007.1 +date: 2026-04-04 +extends: "Epoch 7 (from passive to proactive)" +forcing_fault: "A proactive system without named architectural principles cannot explain why it works or detect when it stops working" +new_invariant: "The architecture is named, the principles are formalized, and posture failure is detectable" +core_shift: "Unnamed conventions → named design pattern. Tool-level governance articles → principle-level governance with smell tests, failure modes, and required responses. No posture lapse detection → structural self-assessment." +documents_introduced: ["canon/principles/vodka-architecture.md", "canon/principles/kiss-simplicity-is-the-ceiling.md", "canon/principles/dry-canon-says-it-once.md", "canon/principles/consistency-same-pattern-every-time.md", "canon/principles/maintainability-one-person-indefinitely.md", "canon/principles/prompt-over-code.md", "canon/principles/antifragile-failures-grow-canon.md", "docs/oddkit/proactive/posture-lapse.md", "docs/appendices/epoch-7-1.md"] +--- + +# Epoch 7.1 — Vodka Architecture and Principled Governance + +> E0007 made the system proactive. E0007.1 names *why* it works and adds the mechanism for detecting *when it stops*. Six design principles — KISS, DRY, Consistency, Maintainability, Prompt Over Code, Antifragile — converge into a named design pattern: Vodka Architecture. Each principle is formalized with smell tests, failure modes, exclusions, and required responses. A posture lapse detection article closes the loop: the system can now diagnose its own governance breakdown. + +--- + +## Summary — From "Act Proactively" to "Here's Why, and Here's How to Tell When You're Not" + +E0007 declared the proactive posture shift and wrote tool-level governance articles — one per oddkit action, each describing when and how to use it proactively. This was correct and necessary. But it left two gaps: + +The first gap was architectural: the principles underlying oddkit's design were practiced but unnamed. The system was thin, stateless, and domain-agnostic — but no document said so, explained why, or defined what violated those properties. An agent or operator encountering oddkit could use it correctly without understanding the architectural constraints that made it work. + +The second gap was diagnostic: the proactive governance articles described what the system *should* do but not how to detect when it *stopped doing it*. A posture lapse — the agent silently ceasing to use oddkit tools — produced no error, no warning, and no structural signal. The failure was invisible because the system had no mechanism for self-assessment. + +E0007.1 closes both gaps. + +--- + +## The Forcing Fault — Unnamed Conventions Cannot Be Enforced + +oddkit's architecture followed six design principles from inception. None were named. None were documented. None had smell tests or failure modes. They existed as tacit knowledge in the operator's head and as implicit constraints in the codebase. + +This mattered because unnamed conventions cannot be enforced by agents, cannot be searched by operators, and cannot be challenged by reviewers. An agent that doesn't know "Vodka Architecture" exists cannot check whether a proposed change violates it. An operator who doesn't know "Prompt Over Code" is a principle cannot search the canon for guidance when choosing between a code change and a governance document. + +The forcing fault was surfaced by two external events: the Claude Code source leak (March 31, 2026) exposed an orchestration harness without a governance layer, and Pliny the Liberator's agent chaos incident demonstrated what happens when behavioral conventions replace structural enforcement. Both validated oddkit's design — but oddkit couldn't explain *why* in terms an agent could discover and apply. + +--- + +## What E0007.1 Introduces + +### Vodka Architecture — The Named Design Pattern + +A design pattern for epistemic infrastructure: infrastructure so thin and clean it disappears into whatever it carries. Stateless server, stateful canon. No domain opinion — all epistemic discipline. Remove it and everything breaks. Add more and you ruin it. + +Named from a transcription error that turned "oddkit" into "vodka" — which works better as a metaphor than it should. The name is now canonical. + +### Six Principle Spinoffs — Full Governance Articles + +Each of the six principles underlying Vodka Architecture is formalized as a standalone governance article following the `ritual-is-a-smell` template: smell test → failure modes → exclusions → required response. Every article is grounded in oddkit's own production evidence — dogfooding each principle. + +| Principle | Core Constraint | +|-----------|----------------| +| KISS | Every action must justify its existence against the alternative of not existing | +| DRY | The canon says it once, the server never repeats it | +| Consistency | Same pattern, every knowledge base, every time | +| Maintainability | One person, indefinitely | +| Prompt Over Code | Governance in documents, enforcement in the server, never the reverse | +| Antifragile | Every failure grows the canon, never the server | + +### Posture Lapse Detection — The Diagnostic Mechanism + +A meta-governance article that defines how to detect when the proactive cognitive rhythm has broken down. Includes tool silence indicators, behavioral signals, failure modes, self-detection vs operator-detection response paths, and a five-question posture health check. + +This closes the gap between E0007's tool-level "when to use" articles and the system-level question "is the proactive posture actually working?" + +--- + +## What E0007.1 Does Not Change + +- **The four axioms carry forward unchanged.** +- **The creed carries forward unchanged.** +- **All E0007 invariants remain in force.** The system still acts first. The operator still reviews. +- **All E0007 tool-level governance articles remain valid.** E0007.1 adds principle-level and system-level governance on top of them. +- **The proactive posture is not modified.** E0007.1 names and diagnoses it — it does not change it. + +--- + +## Epoch 7.1 Documents + +| Document | Purpose | +|----------|---------| +| `canon/principles/vodka-architecture.md` | Parent design pattern — six principles, three properties, three anti-patterns, constraint test | +| `canon/principles/kiss-simplicity-is-the-ceiling.md` | KISS principle with smell tests, failure modes, required response | +| `canon/principles/dry-canon-says-it-once.md` | DRY principle with smell tests, failure modes, required response | +| `canon/principles/consistency-same-pattern-every-time.md` | Consistency principle with smell tests, failure modes, required response | +| `canon/principles/maintainability-one-person-indefinitely.md` | Maintainability principle with smell tests, failure modes, required response | +| `canon/principles/prompt-over-code.md` | Prompt Over Code principle with smell tests, failure modes, required response | +| `canon/principles/antifragile-failures-grow-canon.md` | Antifragile principle with smell tests, failure modes, required response | +| `docs/oddkit/proactive/posture-lapse.md` | Posture lapse detection — system-level governance self-assessment | +| This document | Sub-epoch declaration | + +--- + +## Compatibility + +- E0007 artifacts remain valid. E0007.1 extends E0007 — it does not supersede it. +- E0007.1 adds architectural and diagnostic governance that E0007 did not include. +- E0007.1 is the current sub-epoch within E0007. diff --git a/docs/oddkit/proactive/posture-lapse.md b/docs/oddkit/proactive/posture-lapse.md new file mode 100644 index 00000000..5573d8ec --- /dev/null +++ b/docs/oddkit/proactive/posture-lapse.md @@ -0,0 +1,114 @@ +--- +uri: klappy://docs/oddkit/proactive/posture-lapse +title: "Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["oddkit", "proactive", "governance", "lapse", "breakdown", "cognitive-rhythm", "smell", "failure-mode", "orient", "gate", "search", "encode", "challenge", "preflight", "validate", "tool-use", "epoch-7", "design-smell"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "docs/appendices/epoch-7.md, canon/principles/ritual-is-a-smell.md, canon/values/axioms.md" +complements: "docs/oddkit/proactive/proactive-orient.md, docs/oddkit/proactive/proactive-gate.md, docs/oddkit/proactive/proactive-search.md, docs/oddkit/proactive/proactive-challenge.md, docs/oddkit/proactive/proactive-validate.md, docs/oddkit/proactive/proactive-preflight.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/proactive-identity-of-integrity.md" +governs: "All agent behavior in oddkit-powered sessions" +status: active +--- + +# Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down + +> The proactive posture is a cognitive rhythm: orient at every context shift, search before claiming, gate at every mode transition, challenge before encoding, encode at every milestone, validate before claiming done. When this rhythm breaks — when the agent stops using oddkit tools and starts improvising — governance becomes behavioral instead of structural. This article defines the smell tests, failure modes, and required responses for detecting and recovering from a posture lapse. + +--- + +## Summary — The Rhythm Breaks Silently + +E0007's core shift (`docs/appendices/epoch-7.md`) moved oddkit from passive (wait for invocation) to proactive (act as cognitive rhythm). The rhythm is: orient → search → challenge → gate → encode → validate, invoked continuously throughout every session, not just at designated moments. + +The most dangerous failure mode is not using a tool wrong — it's *forgetting to use it at all*. An agent that stops calling oddkit doesn't produce errors. It produces plausible-sounding output without governance. The operator can't tell the difference unless they know what's missing. This is why posture lapse is a governance problem, not a tooling problem: the system must detect its own silence. + +--- + +## Smell Test — How to Detect a Posture Lapse + +### Tool Silence + +- **No orient call after a context shift.** The operator changed topics, introduced a new goal, or shifted from asking to directing — and the agent didn't reorient. The session is now operating in an unverified mode. +- **No search before a factual claim about the canon.** The agent says "the canon says..." or "this principle means..." without having searched first. Every claim about canon content is a debt until search verifies it (Axiom 2). +- **No gate at a mode transition.** The conversation moved from exploration to planning or planning to execution, and no gate checked prerequisites. The most common version: the agent starts building an artifact during what was still an exploration conversation. +- **No challenge before encoding a consequential decision.** A decision is being recorded without having been pressure-tested. The encoded artifact may contain unexamined assumptions. +- **No encode at a milestone.** Durable insights, decisions, or constraints emerged in conversation but weren't encoded. They exist only in the transcript — which is ephemeral context, not durable governance. +- **No validate before claiming done.** The agent declares completion without checking whether the deliverable meets the definition of done. + +### Behavioral Indicators + +- **The agent stops quoting canon and starts paraphrasing from memory.** When output shifts from grounded retrieval to plausible-sounding assertions, the agent has stopped searching. +- **The creed and axioms haven't been surfaced in a long session.** The Identity of Integrity is not a session-start ritual — it's a drift-correction mechanism. If it hasn't been resurfaced during a long or complex session, drift may be accumulating. +- **The operator has to remind the agent to use oddkit.** If the operator says "did you check the canon?" or "shouldn't you gate this?" — the proactive posture has already failed. The whole point of E0007 is that the agent initiates, not the operator. +- **Output quality degrades toward the end of long sessions.** Context window pressure causes agents to drop governance tools first (because they seem optional) and keep content production (because it seems essential). This is backwards — governance tools prevent the errors that make content production worthless. + +--- + +## Failure Modes — What Breaks When the Rhythm Collapses + +**Ungrounded claims compound.** Without search, the agent's assertions about the canon drift from what the canon actually says. Each unverified claim becomes the foundation for the next. By mid-session, the agent may be confidently asserting things the canon contradicts — and the operator has no reason to doubt it. + +**Premature convergence.** Without gate, exploration collapses into execution without the planning phase that would have revealed missing constraints. The deliverable gets built, then fails review because prerequisites were never checked. This is the most expensive failure mode — the work is done but wrong. + +**Undurable decisions.** Without encode, decisions made during conversation exist only in the transcript. Next session, the agent doesn't know what was decided. The operator repeats themselves. Work is redone. The system doesn't compound — it loops. + +**Hallucination without correction.** Without challenge, the agent's internal consistency goes unexamined. Hallucinated facts, circular reasoning, and ungrounded assertions pass without resistance. The Identity of Integrity creed exists to correct this — but only if it's surfaced. + +**Invisible governance debt.** Every turn without oddkit tools is a turn of ungoverned output. The debt is invisible because the output looks normal. It becomes visible only when a downstream consumer acts on unverified claims and the chain of trust breaks. + +--- + +## What Does NOT Count as a Posture Lapse + +- **Not calling every tool on every turn.** Proactive doesn't mean compulsive. A simple factual question doesn't need orient + search + gate + challenge. The rhythm applies to *context shifts*, *mode transitions*, *consequential decisions*, and *milestone completions* — not to every message exchange. +- **The operator explicitly declining a tool invocation.** If the agent offers to gate and the operator says "skip it, I know what I'm doing" — that's the operator exercising judgment, not the agent lapsing. The gap was named, which is the point. +- **Tools returning unhelpful results.** If search returns irrelevant hits or orient gives low-confidence mode assessment, the tools are working — the results just aren't useful for this query. That's a knowledge base coverage issue, not a posture lapse. +- **Quick exchanges in settled territory.** If the conversation is operating within a well-established mode on a well-understood topic, lighter tool use is appropriate. The smell test is whether the agent would *notice* if the mode changed — not whether it gates every sentence. + +--- + +## Required Response When Detected + +### Self-Detection (Agent Detects Its Own Lapse) + +1. **Acknowledge the gap.** Name what was missed: "I've been responding without searching the canon" or "I should have gated before starting to build that." +2. **Retroactively apply the missed tool.** Run the search, gate, or challenge now. If the results contradict what was already produced, surface the contradiction rather than hiding it. +3. **Encode the lapse itself.** The posture lapse is an observation worth encoding — it reveals where the rhythm is weakest and what conditions cause it to break. +4. **Resurface the creed.** The Identity of Integrity is the recovery mechanism. Reading it resets the posture. + +### Operator Detection (Human Notices the Lapse) + +1. **The operator's reminder is the signal, not the fix.** If the operator had to remind the agent, the proactive posture failed. Acknowledge this directly rather than just doing the requested tool call. +2. **Diagnose the cause.** What caused the lapse? Context window pressure? A topic shift that wasn't detected? A long session without resurfacing the creed? The cause determines the prevention. +3. **Propose a structural fix.** If the lapse is recurring, it may indicate a ritual smell — the posture depends on the agent remembering to act, which is the exact problem E0007 was supposed to solve. The structural fix might be a governance article that triggers at the detected failure point. + +--- + +## The Posture Health Check + +At any point during a session, an agent can self-assess its proactive posture by answering: + +1. **When did I last orient?** If the answer is "session start" and the context has shifted since, the posture has lapsed. +2. **Am I currently searching or remembering?** If the answer is "remembering," a search is overdue. +3. **Has the mode changed since my last gate?** If yes and ungated, the gate is overdue. +4. **Have I encoded anything this session?** If the session has produced decisions, observations, or constraints and nothing has been encoded, the encode is overdue. +5. **Would the creed change my current behavior?** If reading the creed would cause the agent to act differently, the creed should have been surfaced earlier. + +--- + +## See Also + +- [Epoch 7 — From Passive to Proactive](klappy://docs/appendices/epoch-7) — the epoch that introduced proactive posture +- [Proactive Orient](klappy://docs/oddkit/proactive/proactive-orient) — reorient at every context shift +- [Proactive Gate](klappy://docs/oddkit/proactive/proactive-gate) — gate at every mode transition +- [Proactive Search](klappy://docs/oddkit/proactive/proactive-search) — search before claiming +- [Proactive Challenge](klappy://docs/oddkit/proactive/proactive-challenge) — challenge before encoding +- [Continuous Encoding](klappy://docs/oddkit/proactive/continuous-encoding) — encode at every turn +- [Proactive Validate](klappy://docs/oddkit/proactive/proactive-validate) — validate before claiming done +- [Proactive Identity of Integrity](klappy://docs/oddkit/proactive/proactive-identity-of-integrity) — surface the creed to prevent drift +- [Ritual Is a Smell](klappy://canon/principles/ritual-is-a-smell) — if the posture depends on remembering, the design has a gap From 2d7d66fa5e5c3b190d6c4211b174ba44e62a6e4a Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 5 Apr 2026 04:51:35 +0000 Subject: [PATCH 2/9] =?UTF-8?q?feat:=20add=20essay=20=E2=80=94=20The=20Fea?= =?UTF-8?q?ture=20I=20Never=20Shipped=20(the=206th=20B:=20Bypass)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The story of oddkit's write path: four planning sessions, twenty-five decisions, two feature branches, two PRs — none shipped. Then the problem dissolved when the platform caught up. Introduces Bypass as the 6th B in the 5B method: the discipline of recognizing that friction might not be yours to solve. Grounded in real session history. Zero maintenance code. 45 docs/week. --- writings/the-feature-i-never-shipped.md | 155 ++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 writings/the-feature-i-never-shipped.md diff --git a/writings/the-feature-i-never-shipped.md b/writings/the-feature-i-never-shipped.md new file mode 100644 index 00000000..4c72c984 --- /dev/null +++ b/writings/the-feature-i-never-shipped.md @@ -0,0 +1,155 @@ +--- +uri: klappy://writings/the-feature-i-never-shipped +title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" +audience: public +exposure: draft +public: false +tier: 2 +voice: first_person +stability: semi_stable +tags: ["writings", "essay", "5B", "bypass", "write-path", "oddkit", "use-only-what-hurts", "strategic-patience", "ai-augmented-workflows"] +epoch: E0007.1 +date: 2026-04-04 +derives_from: "canon/methods/borrow-bend-break-beget-build.md, odd/constraint/use-only-what-hurts.md" +complements: "writings/learning-in-the-open.md, canon/principles/vodka-architecture.md" +--- + +# The Feature I Never Shipped — And Why It's the Best Thing I've Built + +> I spent months planning a write path for oddkit — four planning sessions, twenty-five encoded decisions, two feature branches, two pull requests, an implementation spec, a decision record, and an epoch definition. None of it shipped. Then the problem dissolved on its own. The 6th B isn't Build. It's Bypass — the discipline of recognizing that the friction might not be yours to solve. + +--- + +## Summary — Sometimes the Best Engineering Is Strategic Patience + +If you've ever stared at a feature branch that's been open for weeks, knowing it's important but knowing it doesn't feel right — this is for you. The instinct to build is strong. The discipline to wait is stronger. This essay tells the story of oddkit's write path: the most planned, most documented, most debated feature in the system's history. It never shipped. And the system is better for it. + +--- + +## The Pain Was Real + +Here's what my workflow looked like for months: I'd have a conversation with Claude. We'd produce something worth keeping — a decision, an article, a governance document. Then came the ritual. Copy the content. Open Claude Code. Paste a handoff document. Watch Claude Code try to write files. Watch it time out. Try again. Watch it time out again. Give up. Open my editor. Create the file manually. Copy-paste the content. Commit. Push. + +Every session. Every artifact. The same ritual. + +Some days were worse than others. I'd be on my phone — the only device available — and Claude Code's mobile client would time out seven times in a row on a single file. Not a complex file. A 287-line markdown document. Seven attempts. Seven failures. The content was right there, fully formed, ready to go. The last mile — getting it from the conversation into the repository — was broken. + +I started keeping a mental list of articles I'd written that never made it to the repo. Governance documents that existed only in conversation transcripts. Decisions that were encoded but never persisted. The system was producing valuable work and then losing it in the gap between "I made this" and "it's in the repo." + +The frustration built. If you've been in that place — watching good work evaporate because the tooling can't close the loop — you know the feeling. It's not anger at any one tool. It's the accumulated weight of a friction that never gets fixed. + +--- + +## The Obvious Solution: Build It + +So I did what any engineer would do. I planned the feature. + +I planned it thoroughly. Four full sessions. Twenty-five encoded decisions. An epoch definition — E0005.2, "The Write Path: One Action, Progressive Protection." A decision record. An implementation spec with tiered rollout. Visual diagrams. Team workflow mapping. Two user journey articles. + +The design was elegant: one action, `oddkit_write`, that would accept file content and write it to a GitHub repository through the API. Tier 1 would use the simple Contents API for single files. Tier 2 would add atomic multi-file commits through the Git Data API. Tier 3 would add branch creation and pull request support. Tier 4 would add context detection and recommendations. + +I even had a constraint for orphan prevention — the write action would track existing branches and update them rather than spawning new ones for every write attempt. + +Then I tried to build it. + +The first implementation landed on a feature branch: `feature/oddkit-write`. Pull request #56. It had structural gaps. The model that generated it didn't fully understand the spec. The validation logic was incomplete. The API integration had edge cases. + +So I commissioned a second attempt. A clean branch: `feature/oddkit-write-v2`. A fresh implementation from a stronger model, with the spec fully loaded and the first attempt available for comparison. + +Neither branch ever merged. + +--- + +## Why It Never Felt Right + +I kept punting. Week after week. The branches sat there, growing stale. I'd look at the PRs and think: this is important. This solves a real problem. This has been thoroughly planned. Why can't I merge it? + +The honest answer took months to arrive: it didn't feel right because it was solving the problem in the wrong layer. + +oddkit is a stateless MCP server. Its job is epistemic discipline — retrieval, gating, encoding, validation. It reads the canon and enforces governance. That's it. That's the entire architecture. We'd later name this Vodka Architecture: infrastructure so thin it disappears into whatever it carries. + +Adding a GitHub API integration — OAuth flows, content encoding, branch management, conflict resolution, retry logic — would have made oddkit thick. The server would have grown from "epistemic discipline" to "epistemic discipline plus deployment infrastructure." It would have acquired opinions about git workflows that had nothing to do with its core purpose. + +Every time I looked at the implementation, I could feel the Vodka Architecture principle pushing back — even before it had a name. The server would have worked. The feature would have been useful. But the architecture would have been wrong. The glass would have gotten heavier than the drink. + +--- + +## The Problem Dissolved + +Then, sometime in early 2026, Claude's web interface gained the ability to execute code, run bash commands, and access the network. Not Claude Code — the regular conversation interface. The one I was already using for everything else. + +I didn't notice the implications immediately. But the first time I needed to commit a batch of files, I tried something different. Instead of copying content to Claude Code, I just... asked the conversation to push it. + +Clone the repo. Create a branch. Copy the files. Commit. Push. Create a PR via the GitHub API. Plain git. Ninety seconds. + +No `oddkit_write`. No GitHub Data API integration. No OAuth. No content encoding. No branch management logic. No retry handlers. No orphan prevention. Just git — the tool that already existed, running in an environment that already had network access, authenticated with a token I already had. + +The months of planning around `oddkit_write` had been solving the wrong problem. The bottleneck was never "how do we build a write path." The bottleneck was "which environment has the right capabilities." The answer turned out to be: the one I was already sitting in. I just had to wait for it to grow the feature I needed. + +--- + +## The 6th B + +I have a method called 5B: Borrow, Bend, Break, Beget, Build. It's a sequence for maximizing the amount of work not done. Before building anything yourself, attempt to borrow what exists, bend it to your context, let the breaks reveal what's missing, offload what you can to others, and only build what nobody else can carry. + +The write path story revealed a step the sequence was missing. A step that comes before Borrow — or maybe after Break and before Beget. A step I'd been practicing without naming: + +**Bypass.** + +Bypass is the discipline of recognizing that the friction you're experiencing might not be yours to solve. Not because it's unimportant — the write path pain was very real. Not because you can't solve it — the implementation spec was solid. But because the problem might dissolve if you give it time. + +Bypass is not procrastination. Procrastination avoids the problem. Bypass watches it. You stay aware of the friction. You keep feeling the pain. You keep noting what breaks. But you don't build — because you've observed that the landscape is shifting and the thing you'd build today might be unnecessary tomorrow. + +The signals that Bypass is appropriate: + +The friction is in a layer you don't own. The write path bottleneck was in Claude's execution environment — a layer Anthropic controls. I could build around it, but I couldn't fix it. And Anthropic had every incentive to fix it themselves. + +The problem is widely shared. I wasn't the only person who needed to get content from AI conversations into repositories. Every developer using AI tools had the same last-mile problem. When a problem is shared widely enough, someone will solve it — and their solution will be better than yours because they can solve it at the platform level. + +Your workaround is sustainable. The copy-paste ritual was painful but not fatal. Sessions still produced value. Work still got committed — just with more friction than necessary. If the workaround had been truly unsustainable, building would have been justified. "Use Only What Hurts" cuts both ways — if the pain is survivable, the build can wait. + +The architecture tells you not to. This is the one that took months to hear. oddkit's architecture was pushing back against the write path not because writing was unimportant, but because writing wasn't oddkit's job. The epistemic discipline layer shouldn't also be the deployment layer. The server should stay thin. + +--- + +## What I Learned + +The hardest part of Bypass isn't the waiting. It's the guilt. I had a thorough plan, a clean spec, and two implementations. Shipping would have felt productive. Not shipping felt like failure — like I was afraid to build, or couldn't execute, or was overthinking it. + +But oddkit today has zero lines of write-path code and full write capability. The canon grew from zero to over four hundred documents in ten weeks — roughly forty-five per week. That production rate didn't change when the write path dissolved. The documents were always being produced that fast. What changed was where the bottleneck lived. Before, the bottleneck was the last mile — getting finished work from the conversation into the repository. After, that friction disappeared and the bottleneck shifted downstream to review, cross-referencing, and publication. Articles get committed in ninety seconds. Pull requests get created from conversations. The write path works — and I maintain none of it. + +If I'd shipped `oddkit_write`, I'd be maintaining a GitHub API integration, handling OAuth token refresh, debugging content encoding edge cases, managing branch conflict resolution, and fielding bug reports every time GitHub changed their API. I'd be carrying infrastructure that has nothing to do with epistemic discipline. + +Instead, I carry nothing. The platform caught up. The workaround became unnecessary. The feature I never shipped is the best thing I've built — because I didn't build it. + +--- + +## The Updated Sequence + +The 5B method is now 5B+1. The sequence is: + +**Bypass** — recognize when the friction isn't yours to solve. Watch, don't build. Stay aware. Let the landscape shift. + +**Borrow** — use what exists without modification. + +**Bend** — compose or repurpose for your context. + +**Break** — identify where borrowed and bent tools fail. + +**Beget** — offload to others who can own that piece. + +**Build** — only what nobody else can carry. + +Bypass doesn't replace Borrow as the first step. It's the step before the sequence starts — the question you ask before entering the method at all: "Is this my problem to solve, or is the world about to solve it for me?" + +Most of the time, the answer is: enter the sequence. Build what needs building. But sometimes — when the friction is in a layer you don't own, when the problem is widely shared, when your workaround is sustainable, and when your architecture is telling you not to — the answer is: wait. Not passively. Strategically. With your eyes open and your branches stale. + +The best feature of oddkit is one I never committed. And two pull requests sit open to this day, monuments to the discipline of not building. + +--- + +## See Also + +- [Method: Borrow, Bend, Break, Beget, Build](klappy://canon/methods/borrow-bend-break-beget-build) — the 5B method this essay extends +- [Vodka Architecture](klappy://canon/principles/vodka-architecture) — the design pattern that told me not to build +- [Use Only What Hurts](klappy://odd/constraint/use-only-what-hurts) — the constraint that governs whether to act From e9d958307a1c6bdfc657525d6823b84035ca6df7 Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 5 Apr 2026 04:53:31 +0000 Subject: [PATCH 3/9] =?UTF-8?q?feat:=20add=20DOLCHE=20vocabulary=20?= =?UTF-8?q?=E2=80=94=20supersedes=20OLDC+H=20with=206th=20artifact=20type?= =?UTF-8?q?=20(Encode)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DOLCHE = Decisions, Observations, Learnings, Constraints, Handoffs, Encodes. The E closes the loop: the act of encoding is itself trackable. Reorders to lead with Decisions (highest stakes). Backward-compatible with OLDC+H journals. --- docs/oddkit/proactive/dolche-vocabulary.md | 93 ++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/oddkit/proactive/dolche-vocabulary.md diff --git a/docs/oddkit/proactive/dolche-vocabulary.md b/docs/oddkit/proactive/dolche-vocabulary.md new file mode 100644 index 00000000..ea402aad --- /dev/null +++ b/docs/oddkit/proactive/dolche-vocabulary.md @@ -0,0 +1,93 @@ +--- +uri: klappy://docs/oddkit/proactive/dolche-vocabulary +title: "DOLCHE — The Six Standard Artifact Types for Session Capture" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable +tags: ["odd", "oddkit", "dolche", "oldc-h", "observations", "learnings", "decisions", "constraints", "handoffs", "encodes", "vocabulary", "session-capture", "project-journal", "epoch-7.1"] +epoch: E0007.1 +date: 2026-04-04 +supersedes: "docs/oddkit/proactive/oldc-h-vocabulary.md" +derives_from: "canon/values/axioms.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/encode-does-not-persist.md" +complements: "docs/oddkit/proactive/posture-lapse.md, docs/oddkit/proactive/proactive-session-close.md, odd/ledger/project-journal-best-practices.md" +governs: "All session capture, project journal entries, and encode invocations" +status: active +--- + +# DOLCHE — The Six Standard Artifact Types for Session Capture + +> Decisions, Observations, Learnings, Constraints, Handoffs, Encodes. Six categories that capture everything significant in a session — what was chosen, what was seen, what was understood, what now governs, what comes next, and the act of crystallization itself. DOLCHE supersedes OLDC+H by adding the sixth type (Encode) and reordering to lead with Decisions. The E closes the loop: the act of encoding is itself a trackable artifact, making the system's own crystallization visible and auditable. + +--- + +## Summary — The E Closes the Loop + +OLDC+H (`docs/oddkit/proactive/oldc-h-vocabulary.md`) defined five artifact types for session capture: Observations, Learnings, Decisions, Constraints, Handoffs. These five cover what happened in a session. But they don't cover *what the system did about it*. + +Every time oddkit's encode action is invoked, it produces a structured artifact — a quality score, a status, a persist_required flag, and suggestions for improvement. That encoding action is itself significant. It tells you: this insight was crystallized. This decision was formalized. This constraint was recorded. Without tracking the encoding itself, you can't distinguish between "this was discussed" and "this was captured." + +DOLCHE adds Encode as the sixth type, closing the loop. The system doesn't just track what happened — it tracks that it tracked what happened. This makes the session's own epistemic discipline visible and auditable. + +The reordering — from OLDC+H to DOLCHE — leads with Decisions because decisions are the highest-stakes artifacts. A missed observation can be recovered from the transcript. A missed decision may not surface again. + +--- + +## The Six Types + +**Decisions (D)** — What was chosen. Explicit commitments with rationale. Decisions close options and create direction. They are the highest-stakes artifacts because they constrain all subsequent work. A decision without rationale is a debt (Axiom 2). A decision without a constraint test is untested. + +**Observations (O)** — What was seen or noticed. Raw facts without interpretation. Observations are the evidence layer — they describe reality as encountered, not reality as theorized. An observation that nobody recorded is an observation that never happened for the system's purposes. + +**Learnings (L)** — What was understood from the observations. Interpretation with evidence. Learnings connect observations to meaning. They are the bridge between "what did we see?" and "what does it mean?" A learning without an observation is speculation. A learning with an observation is knowledge. + +**Constraints (C)** — What now governs future work. Rules, boundaries, and non-negotiables that emerged from the session. Constraints bind future behavior — they are the artifacts most likely to prevent future mistakes. A constraint without enforcement is a suggestion (`canon/principles/ritual-is-a-smell.md`). + +**Handoffs (H)** — What comes next and what context the next session needs. Explicit transfer of state across conversation boundaries. Handoffs are the artifacts most likely to be lost because they describe what hasn't happened yet. A session without handoffs forces the next session to reconstruct context from scratch. + +**Encodes (E)** — What was crystallized and when. The encode action itself as a trackable event. Each encode records that the system attempted to formalize an insight, what quality score it received, whether persistence was required, and what gaps remained. Encodes make the system's own epistemic discipline visible. A session with many observations but no encodes produced raw material that was never refined. A session with encodes that were never persisted produced crystallized artifacts that were then lost. + +--- + +## Why the E Matters + +The encode-persistence gap (`docs/oddkit/proactive/encode-does-not-persist.md`) taught a painful lesson: encode does not persist. It returns structured artifacts in the response stream. If the caller doesn't save them, they're lost. Tracking encodes as a first-class artifact type makes this gap visible in the journal itself. + +When a DOLCHE journal shows three Decisions, two Observations, one Learning — and zero Encodes — the journal is telling you: this session produced insights that were never crystallized. The gap between "discussed" and "captured" is now a measurable distance. + +When a journal shows four Encodes with `persist_required: true` — and no corresponding file writes — the journal is telling you: crystallization happened but persistence didn't. The artifacts exist in the encode output but not in durable storage. + +The E makes both gaps visible. Without it, you'd need to audit the transcript to discover what was encoded and what was lost. With it, the journal self-reports its own completeness. + +--- + +## Usage + +When the operator says "encode DOLCHE," "journal this," or "run the gauntlet," the agent captures all six types from the current session. The categories are tags on narrative entries, not section headers — they identify what kind of artifact each entry is without separating the narrative into disconnected lists. + +The trigger phrases are equivalent: "encode DOLCHE," "journal this," and "run the oddkit gauntlet" all invoke the same behavior — comprehensive session capture across all six types, followed by persistence to the project journal. + +--- + +## Migration from OLDC+H + +DOLCHE is backward-compatible with OLDC+H. All five original types retain their definitions. The only additions are the E type and the reordering. Existing OLDC+H journals do not need to be rewritten — they are valid DOLCHE journals that happen to have zero E entries. + +The trigger phrase "encode OLDC+H" continues to work and is treated as equivalent to "encode DOLCHE." Agents should use DOLCHE in their output regardless of which trigger phrase the operator uses. + +--- + +## Discoverability + +This article exists so that any search for "DOLCHE," "OLDC+H," "session capture," "journal," "encode vocabulary," "project journal format," "observations learnings decisions constraints handoffs encodes," or "what to track in a session" surfaces this vocabulary. + +--- + +## See Also + +- [OLDC+H (superseded)](klappy://docs/oddkit/proactive/oldc-h-vocabulary) — the prior five-type vocabulary this document extends +- [Encode Does Not Persist](klappy://docs/oddkit/proactive/encode-does-not-persist) — the gap that motivated tracking encodes as artifacts +- [Continuous Encoding](klappy://docs/oddkit/proactive/continuous-encoding) — encoding at every turn, not just session end +- [Proactive Posture Lapse](klappy://docs/oddkit/proactive/posture-lapse) — detecting when encoding (among other tools) stops happening +- [Project Journal Best Practices](klappy://odd/ledger/project-journal-best-practices) — sizing, timestamps, and format for journals From 5a376c881e39990eeddbf094364ff3e96daaf427 Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 5 Apr 2026 13:31:18 +0000 Subject: [PATCH 4/9] =?UTF-8?q?fix:=20reframe=20DOLCHE=20=E2=80=94=20Encod?= =?UTF-8?q?e=20is=20meta-level=20action,=20not=20sixth=20artifact=20type?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The E tracks the act of crystallization itself, not a category of content. Five artifact types (D, O, L, C, H) + one meta-level action (E). Added storage-at-scale note (format-agnostic, implementation-neutral). --- docs/oddkit/proactive/dolche-vocabulary.md | 38 ++++++++++++++++------ 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/docs/oddkit/proactive/dolche-vocabulary.md b/docs/oddkit/proactive/dolche-vocabulary.md index ea402aad..b86fc180 100644 --- a/docs/oddkit/proactive/dolche-vocabulary.md +++ b/docs/oddkit/proactive/dolche-vocabulary.md @@ -1,6 +1,6 @@ --- uri: klappy://docs/oddkit/proactive/dolche-vocabulary -title: "DOLCHE — The Six Standard Artifact Types for Session Capture" +title: "DOLCHE — Six Dimensions of Session Capture" audience: docs exposure: nav tier: 2 @@ -16,25 +16,25 @@ governs: "All session capture, project journal entries, and encode invocations" status: active --- -# DOLCHE — The Six Standard Artifact Types for Session Capture +# DOLCHE — Six Dimensions of Session Capture -> Decisions, Observations, Learnings, Constraints, Handoffs, Encodes. Six categories that capture everything significant in a session — what was chosen, what was seen, what was understood, what now governs, what comes next, and the act of crystallization itself. DOLCHE supersedes OLDC+H by adding the sixth type (Encode) and reordering to lead with Decisions. The E closes the loop: the act of encoding is itself a trackable artifact, making the system's own crystallization visible and auditable. +> Decisions, Observations, Learnings, Constraints, Handoffs, Encodes. Five artifact types and one meta-level action that tracks the crystallization of all the others. DOLCHE supersedes OLDC+H by adding Encode — not as a sixth category of content, but as the act of encoding itself made visible. The E closes the loop: when you encode a Decision, the Encode tracks *that you did it*, when you did it, what quality it achieved, and whether it was persisted. Without the E, you can't distinguish between "this was discussed" and "this was captured." --- -## Summary — The E Closes the Loop +## Summary — Five Artifact Types, One Meta-Level Action -OLDC+H (`docs/oddkit/proactive/oldc-h-vocabulary.md`) defined five artifact types for session capture: Observations, Learnings, Decisions, Constraints, Handoffs. These five cover what happened in a session. But they don't cover *what the system did about it*. +OLDC+H (`docs/oddkit/proactive/oldc-h-vocabulary.md`) defined five artifact types for session capture: Observations, Learnings, Decisions, Constraints, Handoffs. These five cover what happened in a session. But they don't cover *the system's own crystallization work*. -Every time oddkit's encode action is invoked, it produces a structured artifact — a quality score, a status, a persist_required flag, and suggestions for improvement. That encoding action is itself significant. It tells you: this insight was crystallized. This decision was formalized. This constraint was recorded. Without tracking the encoding itself, you can't distinguish between "this was discussed" and "this was captured." +Every time oddkit's encode action is invoked, it takes one or more of those five artifact types and crystallizes them — producing a quality score, a status, a persist_required flag, and suggestions for improvement. That encoding action is not another artifact type. It is the meta-level act of *processing* the artifacts. But it needs to be tracked, because without it you can't answer: "Did we just discuss this, or did we actually capture it? And if we captured it, did we persist it?" -DOLCHE adds Encode as the sixth type, closing the loop. The system doesn't just track what happened — it tracks that it tracked what happened. This makes the session's own epistemic discipline visible and auditable. +DOLCHE adds Encode as the meta-level dimension, closing the loop. The system doesn't just track what happened — it tracks that it tracked what happened. This makes the session's own epistemic discipline visible and auditable. The reordering — from OLDC+H to DOLCHE — leads with Decisions because decisions are the highest-stakes artifacts. A missed observation can be recovered from the transcript. A missed decision may not surface again. --- -## The Six Types +## The Five Artifact Types **Decisions (D)** — What was chosen. Explicit commitments with rationale. Decisions close options and create direction. They are the highest-stakes artifacts because they constrain all subsequent work. A decision without rationale is a debt (Axiom 2). A decision without a constraint test is untested. @@ -46,13 +46,23 @@ The reordering — from OLDC+H to DOLCHE — leads with Decisions because decisi **Handoffs (H)** — What comes next and what context the next session needs. Explicit transfer of state across conversation boundaries. Handoffs are the artifacts most likely to be lost because they describe what hasn't happened yet. A session without handoffs forces the next session to reconstruct context from scratch. -**Encodes (E)** — What was crystallized and when. The encode action itself as a trackable event. Each encode records that the system attempted to formalize an insight, what quality score it received, whether persistence was required, and what gaps remained. Encodes make the system's own epistemic discipline visible. A session with many observations but no encodes produced raw material that was never refined. A session with encodes that were never persisted produced crystallized artifacts that were then lost. +--- + +## The Meta-Level Action — Encode (E) + +Encode is not a sixth artifact type. It is the act of crystallizing all the others — the moment where a Decision, Observation, Learning, Constraint, or Handoff is structured, quality-scored, and flagged for persistence. Tracking encodes makes the system's own epistemic work visible. + +Each encode event records: what was crystallized, when, what quality score it received, whether persistence was required, and what gaps remained. An encode is not content — it is a receipt that crystallization happened. + +This distinction matters operationally. A journal entry tagged D (Decision) tells you what was chosen. An encode event tells you that the decision was formally processed through oddkit's encode action, scored for quality, and flagged to be saved. Without the E, the journal can't distinguish between a decision that was casually mentioned and a decision that was formally captured. + +The E is what makes DOLCHE self-auditing. A session journal with five Decisions and zero Encodes says: decisions were made but never crystallized. A journal with five Decisions and five Encodes where none were persisted says: crystallization happened but the artifacts were lost in the response stream. Both gaps are now visible from the journal itself. --- ## Why the E Matters -The encode-persistence gap (`docs/oddkit/proactive/encode-does-not-persist.md`) taught a painful lesson: encode does not persist. It returns structured artifacts in the response stream. If the caller doesn't save them, they're lost. Tracking encodes as a first-class artifact type makes this gap visible in the journal itself. +The encode-persistence gap (`docs/oddkit/proactive/encode-does-not-persist.md`) taught a painful lesson: encode does not persist. It returns structured artifacts in the response stream. If the caller doesn't save them, they're lost. Tracking encodes as a meta-level action makes this gap visible in the journal itself. When a DOLCHE journal shows three Decisions, two Observations, one Learning — and zero Encodes — the journal is telling you: this session produced insights that were never crystallized. The gap between "discussed" and "captured" is now a measurable distance. @@ -62,6 +72,14 @@ The E makes both gaps visible. Without it, you'd need to audit the transcript to --- +## Storage at Scale + +DOLCHE entries are structured data: each has a type (D/O/L/C/H/E), a timestamp, a summary, a body, and tags. At personal scale — a few entries per session — markdown journals work fine. At production scale — dozens of entries per day across multiple projects — structured tabular formats (TSV, CSV) offer faster parsing, appendability, and git-diffability. + +The storage format is an implementation concern, not a vocabulary concern. DOLCHE defines *what* to capture. How entries are stored, indexed, and queried depends on the context: markdown for human-readable journals, tabular formats for machine-queryable session history, or both in parallel. The vocabulary is portable across any storage format. + +--- + ## Usage When the operator says "encode DOLCHE," "journal this," or "run the gauntlet," the agent captures all six types from the current session. The categories are tags on narrative entries, not section headers — they identify what kind of artifact each entry is without separating the narrative into disconnected lists. From b37692a28533ca239aa48cc56dda72e712051d65 Mon Sep 17 00:00:00 2001 From: Klappy Date: Sun, 5 Apr 2026 13:39:33 +0000 Subject: [PATCH 5/9] =?UTF-8?q?feat:=20add=20DOLCHE=20extensibility=20?= =?UTF-8?q?=E2=80=94=20custom=20types=20through=20governance=20documents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DOLCHE types are defaults, not a closed set. Any KB can extend with custom types (P for Prayer Requests, R for Rulings, A for Automations) via governance documents. oddkit handles any type string generically. Prompt over code applied to the vocabulary itself. --- docs/oddkit/proactive/dolche-vocabulary.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/oddkit/proactive/dolche-vocabulary.md b/docs/oddkit/proactive/dolche-vocabulary.md index b86fc180..502334a2 100644 --- a/docs/oddkit/proactive/dolche-vocabulary.md +++ b/docs/oddkit/proactive/dolche-vocabulary.md @@ -80,6 +80,18 @@ The storage format is an implementation concern, not a vocabulary concern. DOLCH --- +## Extensibility — Custom Types Through Governance + +DOLCHE's five artifact types and one meta-level action are defaults, not a closed set. The type field is a string, not an enum. Any knowledge base can extend DOLCHE with custom types by adding a governance document that defines them. + +A pastoral knowledge base might add "P" for Prayer Requests — entries that track pastoral commitments across sessions. A legal knowledge base might add "R" for Rulings — entries that capture case law citations as they surface. A smart home knowledge base might add "A" for Automations — entries that record governance rules derived from user preferences ("I like the house cooler at night"). + +The extension mechanism is a governance document in the knowledge base, not a code change in oddkit. The governance document defines: what the new type letter means, when it should be used, what makes a valid entry of that type, and how it relates to the five defaults. oddkit's generic infrastructure — TSV parsing, BM25 search, type-based filtering — handles any type string without modification. The server doesn't need to know about Prayer Requests. It needs to know about type fields. + +This is prompt over code applied to the vocabulary itself. The defaults are universal. The extensions are domain-specific. The capability is open. The semantics are governed. + +--- + ## Usage When the operator says "encode DOLCHE," "journal this," or "run the gauntlet," the agent captures all six types from the current session. The categories are tags on narrative entries, not section headers — they identify what kind of artifact each entry is without separating the narrative into disconnected lists. From ac94228c02c173c3436df8d6d081291a78a88d43 Mon Sep 17 00:00:00 2001 From: Klappy Date: Mon, 6 Apr 2026 11:30:36 +0000 Subject: [PATCH 6/9] fix: quote all frontmatter values per project conventions All scalar values now quoted. Fixes potential renderer issues with unquoted dates (parsed as date objects), unquoted integers (tier), and unquoted strings (audience, exposure, etc.). Project instructions require: 'YAML frontmatter: all values quoted, inline tag arrays use quoted strings.' All 11 files corrected. --- .../antifragile-failures-grow-canon.md | 18 +++++++++--------- .../consistency-same-pattern-every-time.md | 18 +++++++++--------- canon/principles/dry-canon-says-it-once.md | 18 +++++++++--------- .../kiss-simplicity-is-the-ceiling.md | 18 +++++++++--------- .../maintainability-one-person-indefinitely.md | 18 +++++++++--------- canon/principles/prompt-over-code.md | 18 +++++++++--------- canon/principles/vodka-architecture.md | 18 +++++++++--------- docs/appendices/epoch-7-1.md | 16 ++++++++-------- docs/oddkit/proactive/dolche-vocabulary.md | 18 +++++++++--------- docs/oddkit/proactive/posture-lapse.md | 18 +++++++++--------- writings/the-feature-i-never-shipped.md | 16 ++++++++-------- 11 files changed, 97 insertions(+), 97 deletions(-) diff --git a/canon/principles/antifragile-failures-grow-canon.md b/canon/principles/antifragile-failures-grow-canon.md index 1a16f8d8..f5d6a082 100644 --- a/canon/principles/antifragile-failures-grow-canon.md +++ b/canon/principles/antifragile-failures-grow-canon.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/antifragile-failures-grow-canon +uri: "klappy://canon/principles/antifragile-failures-grow-canon" title: "Antifragile — Every Failure Grows the Canon, Never the Server" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "antifragile", "antifragility", "failure", "stress", "learning", "incidents", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, canon/resonance/antifragile.md, canon/values/axioms.md" complements: "canon/principles/prompt-over-code.md, canon/principles/ritual-is-a-smell.md" governs: "All failure response decisions in this program" -status: active +status: "active" --- # Antifragile — Every Failure Grows the Canon, Never the Server diff --git a/canon/principles/consistency-same-pattern-every-time.md b/canon/principles/consistency-same-pattern-every-time.md index a0d6f48e..bf4deea9 100644 --- a/canon/principles/consistency-same-pattern-every-time.md +++ b/canon/principles/consistency-same-pattern-every-time.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/consistency-same-pattern-every-time +uri: "klappy://canon/principles/consistency-same-pattern-every-time" title: "Consistency — Same Pattern, Every Knowledge Base, Every Time" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "consistency", "portability", "MCP", "interface", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "docs/architecture/epistemic-os-layers.md, canon/principles/kiss-simplicity-is-the-ceiling.md" governs: "All MCP server interfaces and knowledge base serving patterns in this program" -status: active +status: "active" --- # Consistency — Same Pattern, Every Knowledge Base, Every Time diff --git a/canon/principles/dry-canon-says-it-once.md b/canon/principles/dry-canon-says-it-once.md index 6dd75232..b8a7f884 100644 --- a/canon/principles/dry-canon-says-it-once.md +++ b/canon/principles/dry-canon-says-it-once.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/dry-canon-says-it-once +uri: "klappy://canon/principles/dry-canon-says-it-once" title: "DRY — The Canon Says It Once, the Server Never Repeats It" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "DRY", "dont-repeat-yourself", "governance", "drift", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, canon/constraints/oddkit-prompt-pattern.md" complements: "canon/principles/prompt-over-code.md, canon/values/axioms.md" governs: "All governance rule placement decisions in this program" -status: active +status: "active" --- # DRY — The Canon Says It Once, the Server Never Repeats It diff --git a/canon/principles/kiss-simplicity-is-the-ceiling.md b/canon/principles/kiss-simplicity-is-the-ceiling.md index ef655e9c..2d5c076a 100644 --- a/canon/principles/kiss-simplicity-is-the-ceiling.md +++ b/canon/principles/kiss-simplicity-is-the-ceiling.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/kiss-simplicity-is-the-ceiling +uri: "klappy://canon/principles/kiss-simplicity-is-the-ceiling" title: "KISS — Simplicity Is the Ceiling, Not the Floor" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "KISS", "simplicity", "design", "composability", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "canon/principles/ritual-is-a-smell.md, canon/principles/maintainability-one-person-indefinitely.md" governs: "All MCP servers, tools, and orchestration layers in this program" -status: active +status: "active" --- # KISS — Simplicity Is the Ceiling, Not the Floor diff --git a/canon/principles/maintainability-one-person-indefinitely.md b/canon/principles/maintainability-one-person-indefinitely.md index 099fbb87..32ab2578 100644 --- a/canon/principles/maintainability-one-person-indefinitely.md +++ b/canon/principles/maintainability-one-person-indefinitely.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/maintainability-one-person-indefinitely +uri: "klappy://canon/principles/maintainability-one-person-indefinitely" title: "Maintainability — One Person, Indefinitely" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "maintainability", "sustainability", "single-maintainer", "cloudflare-worker", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "canon/principles/ritual-is-a-smell.md, canon/principles/kiss-simplicity-is-the-ceiling.md" governs: "All infrastructure sizing and complexity decisions in this program" -status: active +status: "active" --- # Maintainability — One Person, Indefinitely diff --git a/canon/principles/prompt-over-code.md b/canon/principles/prompt-over-code.md index af8ec36b..74323b03 100644 --- a/canon/principles/prompt-over-code.md +++ b/canon/principles/prompt-over-code.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/prompt-over-code +uri: "klappy://canon/principles/prompt-over-code" title: "Prompt Over Code — Fully Programmable Governance Without Changing the Server" -audience: canon -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "principle", "prompt-over-code", "convention-over-configuration", "governance", "programmable", "vodka-architecture", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/principles/vodka-architecture.md, docs/appendices/convention-requires-an-enforcer.md, canon/constraints/oddkit-prompt-pattern.md" complements: "odd/prompt-architecture.md, canon/principles/ritual-is-a-smell.md, canon/principles/dry-canon-says-it-once.md" governs: "All governance rule implementation decisions in this program" -status: active +status: "active" --- # Prompt Over Code — Fully Programmable Governance Without Changing the Server diff --git a/canon/principles/vodka-architecture.md b/canon/principles/vodka-architecture.md index 59eb8ae9..e3025c68 100644 --- a/canon/principles/vodka-architecture.md +++ b/canon/principles/vodka-architecture.md @@ -1,18 +1,18 @@ --- -uri: klappy://canon/principles/vodka-architecture +uri: "klappy://canon/principles/vodka-architecture" title: "Vodka Architecture — The Design Pattern for Epistemic Infrastructure" -audience: canon -exposure: nav -tier: 1 -voice: neutral -stability: semi_stable +audience: "canon" +exposure: "nav" +tier: "1" +voice: "neutral" +stability: "semi_stable" tags: ["canon", "architecture", "design-pattern", "vodka", "stateless", "thin-layer", "epistemic-infrastructure", "KISS", "DRY", "antifragile", "convention-over-configuration", "maintainability"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/values/axioms.md, canon/principles/ritual-is-a-smell.md, canon/resonance/antifragile.md, docs/appendices/convention-requires-an-enforcer.md" complements: "docs/architecture/epistemic-os-layers.md, odd/prompt-architecture.md, canon/constraints/oddkit-prompt-pattern.md" governs: "All MCP servers, knowledge base serving infrastructure, and orchestration layers in this program" -status: active +status: "active" --- # Vodka Architecture — The Design Pattern for Epistemic Infrastructure diff --git a/docs/appendices/epoch-7-1.md b/docs/appendices/epoch-7-1.md index 5b0d8085..d9096e26 100644 --- a/docs/appendices/epoch-7-1.md +++ b/docs/appendices/epoch-7-1.md @@ -1,14 +1,14 @@ --- -uri: klappy://docs/appendices/epoch-7-1 +uri: "klappy://docs/appendices/epoch-7-1" title: "Epoch 7.1 — Vodka Architecture and Principled Governance" -audience: docs -exposure: nav -tier: 2 -voice: neutral -stability: stable +audience: "docs" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "stable" tags: ["odd", "epochs", "vodka-architecture", "design-pattern", "principles", "governance", "posture-lapse", "epoch-7", "epoch-7.1"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" extends: "Epoch 7 (from passive to proactive)" forcing_fault: "A proactive system without named architectural principles cannot explain why it works or detect when it stops working" new_invariant: "The architecture is named, the principles are formalized, and posture failure is detectable" diff --git a/docs/oddkit/proactive/dolche-vocabulary.md b/docs/oddkit/proactive/dolche-vocabulary.md index 502334a2..04d6dc68 100644 --- a/docs/oddkit/proactive/dolche-vocabulary.md +++ b/docs/oddkit/proactive/dolche-vocabulary.md @@ -1,19 +1,19 @@ --- -uri: klappy://docs/oddkit/proactive/dolche-vocabulary +uri: "klappy://docs/oddkit/proactive/dolche-vocabulary" title: "DOLCHE — Six Dimensions of Session Capture" -audience: docs -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "docs" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["odd", "oddkit", "dolche", "oldc-h", "observations", "learnings", "decisions", "constraints", "handoffs", "encodes", "vocabulary", "session-capture", "project-journal", "epoch-7.1"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" supersedes: "docs/oddkit/proactive/oldc-h-vocabulary.md" derives_from: "canon/values/axioms.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/encode-does-not-persist.md" complements: "docs/oddkit/proactive/posture-lapse.md, docs/oddkit/proactive/proactive-session-close.md, odd/ledger/project-journal-best-practices.md" governs: "All session capture, project journal entries, and encode invocations" -status: active +status: "active" --- # DOLCHE — Six Dimensions of Session Capture diff --git a/docs/oddkit/proactive/posture-lapse.md b/docs/oddkit/proactive/posture-lapse.md index 5573d8ec..f9e9a7ab 100644 --- a/docs/oddkit/proactive/posture-lapse.md +++ b/docs/oddkit/proactive/posture-lapse.md @@ -1,18 +1,18 @@ --- -uri: klappy://docs/oddkit/proactive/posture-lapse +uri: "klappy://docs/oddkit/proactive/posture-lapse" title: "Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down" -audience: docs -exposure: nav -tier: 2 -voice: neutral -stability: semi_stable +audience: "docs" +exposure: "nav" +tier: "2" +voice: "neutral" +stability: "semi_stable" tags: ["oddkit", "proactive", "governance", "lapse", "breakdown", "cognitive-rhythm", "smell", "failure-mode", "orient", "gate", "search", "encode", "challenge", "preflight", "validate", "tool-use", "epoch-7", "design-smell"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "docs/appendices/epoch-7.md, canon/principles/ritual-is-a-smell.md, canon/values/axioms.md" complements: "docs/oddkit/proactive/proactive-orient.md, docs/oddkit/proactive/proactive-gate.md, docs/oddkit/proactive/proactive-search.md, docs/oddkit/proactive/proactive-challenge.md, docs/oddkit/proactive/proactive-validate.md, docs/oddkit/proactive/proactive-preflight.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/proactive-identity-of-integrity.md" governs: "All agent behavior in oddkit-powered sessions" -status: active +status: "active" --- # Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down diff --git a/writings/the-feature-i-never-shipped.md b/writings/the-feature-i-never-shipped.md index 4c72c984..2679ec90 100644 --- a/writings/the-feature-i-never-shipped.md +++ b/writings/the-feature-i-never-shipped.md @@ -1,15 +1,15 @@ --- -uri: klappy://writings/the-feature-i-never-shipped +uri: "klappy://writings/the-feature-i-never-shipped" title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" -audience: public -exposure: draft +audience: "public" +exposure: "draft" public: false -tier: 2 -voice: first_person -stability: semi_stable +tier: "2" +voice: "first_person" +stability: "semi_stable" tags: ["writings", "essay", "5B", "bypass", "write-path", "oddkit", "use-only-what-hurts", "strategic-patience", "ai-augmented-workflows"] -epoch: E0007.1 -date: 2026-04-04 +epoch: "E0007.1" +date: "2026-04-04" derives_from: "canon/methods/borrow-bend-break-beget-build.md, odd/constraint/use-only-what-hurts.md" complements: "writings/learning-in-the-open.md, canon/principles/vodka-architecture.md" --- From af5cf9e1de45e508b6ebc6c876633e24f30c77e5 Mon Sep 17 00:00:00 2001 From: Klappy Date: Mon, 6 Apr 2026 12:35:49 +0000 Subject: [PATCH 7/9] feat: add frontmatter schema governance + fix essay metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New: canon/meta/frontmatter-schema.md — authoritative reference for all YAML frontmatter fields. Defines universal required fields, audience-specific fields, quoting rules, smell tests, and required responses. Supersedes template-based field guidance. Fix: writings/the-feature-i-never-shipped.md — add missing required essay fields (slug, author, type, public, description, hook, subtitle, og_title, og_description). Quote public as string. These fields were missing because no schema existed to enforce them. --- canon/meta/frontmatter-schema.md | 244 ++++++++++++++++++++++++ writings/the-feature-i-never-shipped.md | 10 +- 2 files changed, 253 insertions(+), 1 deletion(-) create mode 100644 canon/meta/frontmatter-schema.md diff --git a/canon/meta/frontmatter-schema.md b/canon/meta/frontmatter-schema.md new file mode 100644 index 00000000..36dd60f4 --- /dev/null +++ b/canon/meta/frontmatter-schema.md @@ -0,0 +1,244 @@ +--- +uri: "klappy://canon/meta/frontmatter-schema" +title: "Frontmatter Schema — The Authoritative Reference for All Document Metadata" +audience: "canon" +exposure: "nav" +tier: "1" +voice: "neutral" +stability: "semi_stable" +tags: ["canon", "meta", "frontmatter", "schema", "YAML", "metadata", "governance", "template", "validation"] +epoch: "E0007.1" +date: "2026-04-04" +derives_from: "canon/meta/writing-canon.md, canon/values/axioms.md" +complements: "canon/meta/TEMPLATE.md, docs/TEMPLATE.md, canon/constraints/definition-of-done.md" +governs: "All YAML frontmatter in all documents across all directories" +status: "active" +supersedes: "Frontmatter sections in canon/meta/TEMPLATE.md and docs/TEMPLATE.md (those remain as structural templates; this document is the authoritative field reference)" +--- + +# Frontmatter Schema — The Authoritative Reference for All Document Metadata + +> Every YAML frontmatter value must be quoted as a string. Every document must include the eight universal fields: uri, title, audience, exposure, tier, voice, stability, tags. Additional fields are required or optional per audience. This document is the single source of truth for frontmatter — not templates, not other documents, not pattern-matching from existing files. When in doubt, consult this document. When this document and another disagree, this document wins. + +--- + +## Summary — One Schema, All Documents, No Guessing + +The canon has over 400 documents with no authoritative frontmatter schema. Fields, types, and quoting rules have been copied ad-hoc from whatever document an agent finds first. This has produced: unquoted values that parse as wrong types (dates as date objects, tiers as integers, booleans as booleans), inconsistent field presence across documents of the same audience, and silent rendering failures when the site's build system encounters unexpected types. + +This document fixes the problem by defining the schema once. Templates (`canon/meta/TEMPLATE.md`, `docs/TEMPLATE.md`) define document structure. This document defines field requirements. When they disagree, this document wins. + +--- + +## The Universal Rule — All Values Quoted + +Every scalar value in YAML frontmatter must be wrapped in double quotes. No exceptions. + +```yaml +# CORRECT +uri: "klappy://canon/principles/example" +title: "Example Title" +audience: "canon" +tier: "2" +date: "2026-04-04" +public: "false" +epoch: "E0007" + +# WRONG — these parse as non-string types +uri: klappy://canon/principles/example +tier: 2 # parses as integer +date: 2026-04-04 # parses as date object +public: false # parses as boolean +epoch: E0007 # usually fine but inconsistent +``` + +Arrays use inline format with quoted strings: + +```yaml +# CORRECT +tags: ["canon", "principle", "example"] + +# WRONG +tags: + - canon + - principle +``` + +This rule exists because YAML silently coerces unquoted values. `2026-04-04` becomes a date object. `false` becomes a boolean. `1` becomes an integer. The site's renderer expects strings. When it gets a date object, the page goes blank. Quoting everything prevents the entire class of error. + +--- + +## Universal Required Fields — Every Document, Every Audience + +These eight fields are required on every document in the knowledge base, regardless of audience: + +| Field | Format | Description | +|-------|--------|-------------| +| `uri` | `"klappy://path/to/slug"` | Canonical URI. Must match the file's logical location. | +| `title` | `"Full Title — With Stance"` | Document title. Must name concept and signal position (Writing Canon Tier 1). | +| `audience` | `"canon"` `"docs"` `"public"` `"odd"` `"operators"` `"apocrypha"` | Which audience this document serves. Determines required fields below. | +| `exposure` | `"nav"` `"public"` `"draft"` `"hidden"` `"internal"` | Visibility level. `nav` = navigable but not promoted. `public` = published on site. `draft` = work in progress. `hidden` = exists but not listed. `internal` = team-only. | +| `tier` | `"1"` `"2"` `"3"` `"4"` | Epistemic obligation level. `1` = foundational. `2` = governance. `3` = operational. `4` = ephemeral. See `canon/definitions/epistemic-obligation-and-document-tiers.md`. | +| `voice` | `"first_person"` `"neutral"` `"direct"` `"narrative"` `"conversational"` `"authoritative"` | Writing voice. `first_person` = Klappy speaks. `neutral` = system documentation. | +| `stability` | `"stable"` `"semi_stable"` `"evolving"` `"draft"` `"experimental"` | How likely this document is to change. Governs how confidently agents should rely on it. | +| `tags` | `["tag1", "tag2"]` | Inline array of quoted strings. Used for search and categorization. Must not be empty — at minimum include the audience and one topic tag. | + +--- + +## Audience-Specific Fields + +### audience: "canon" + +Canon documents define program-level constraints. + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | recommended | `"E0007"` | Which epoch introduced this document | +| `date` | recommended | `"2026-04-04"` | Date created or last substantively revised | +| `derives_from` | recommended | `"path/to/source.md, path/to/other.md"` | What this document is grounded in. Full file paths, not floating names. | +| `complements` | optional | `"path/to/sibling.md"` | Related documents that work alongside this one | +| `governs` | optional | `"description of what this constrains"` | What behavior or documents this constrains | +| `status` | optional | `"active"` `"proposed"` `"final"` | Lifecycle status | +| `supersedes` | optional | `"path/to/old.md"` | What this replaces | + +### audience: "docs" + +Docs documents define implementation details, planning, and operational guides. + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | recommended | `"E0007"` | Which epoch this belongs to | +| `date` | recommended | `"2026-04-04"` | Date created | +| `derives_from` | optional | `"path/to/source.md"` | What this is grounded in | +| `complements` | optional | `"path/to/sibling.md"` | Related documents | +| `governs` | optional | `"description"` | What this constrains | +| `supersedes` | optional | `"path or description"` | What this replaces | +| `forcing_fault` | epoch docs only | `"description"` | What friction triggered this epoch | +| `new_invariant` | epoch docs only | `"statement"` | What's now true that wasn't before | +| `core_shift` | epoch docs only | `"old → new"` | What changed | +| `documents_introduced` | epoch docs only | `["path1.md", "path2.md"]` | Files added in this epoch | +| `extends` | sub-epoch docs | `"Epoch N (description)"` | Parent epoch this extends | + +### audience: "public" + +Public documents include essays, articles, about pages, and website navigation pages. Essays and articles have additional required fields for site rendering. + +**All public documents:** + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | recommended | `"E0007"` | Which epoch | +| `date` | recommended | `"2026-04-04"` | Publication or creation date | +| `derives_from` | recommended | `"path/to/source.md"` | Grounding | +| `complements` | optional | `"path/to/sibling.md"` | Related content | + +**Additional fields required when `type` is `"essay"` or `"article"`:** + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `slug` | **required** | `"kebab-case-url-slug"` | URL path. Used by the site renderer to generate page URLs. **Without this, pages render blank.** | +| `author` | **required** | `"Klappy"` | Author name. Always `"Klappy"` for this project. | +| `type` | **required** | `"essay"` or `"article"` | Content type. Used by the renderer to select template. | +| `public` | **required** | `"true"` or `"false"` | Whether this is published on the site. `"false"` = draft, not visible. | +| `description` | **required** | `"1-2 sentence description"` | Used for SEO meta description and social sharing. | +| `hook` | **required** | `"One compelling sentence"` | Used for teaser text in listings and cards. | +| `subtitle` | recommended | `"Explanatory subtitle"` | Appears below title on the page | +| `og_title` | recommended | `"Title for social sharing"` | OpenGraph title. Defaults to `title` if omitted. | +| `og_description` | recommended | `"Description for social sharing"` | OpenGraph description. Defaults to `description` if omitted. | +| `og_type` | optional | `"article"` | OpenGraph type | +| `og_image` | optional | `"/images/slug-og.png"` | OpenGraph image path | +| `twitter_card` | optional | `"summary_large_image"` | Twitter card type | +| `twitter_title` | optional | `"Title for Twitter"` | Twitter title | +| `twitter_description` | optional | `"Description for Twitter"` | Twitter description | +| `twitter_image` | optional | `"/images/slug-og.png"` | Twitter image path | +| `related` | optional | `[{uri, label, relationship}]` | Related content links (YAML object array) | +| `provenance` | optional | `{trigger, author_interventions, ...}` | Detailed authorship record (YAML object) | +| `book_part` | book chapters only | `"Part N — Title"` | Book section | +| `book_chapter` | book chapters only | `"5"` | Chapter number (quoted) | + +**About pages, indexes, and navigation pages** (`about/`, READMEs, positioning docs) do not need slug, author, type, or social metadata. They render through structural routes, not content templates. + +### audience: "operators" + +Operator documents are tool references and MCP server documentation. + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | optional | `"E0007"` | Which epoch | +| `date` | optional | `"2026-04-04"` | Date | +| `derives_from` | optional | `"path/to/source.md"` | Grounding | +| `complements` | optional | `"path/to/sibling.md"` | Related docs | +| `governs` | optional | `"description"` | What this constrains | + +### audience: "apocrypha" + +Apocrypha documents are system-voice fragments, predocumentaries, and reconstructions. + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | recommended | `"E0005"` | Origin epoch | +| `type` | recommended | `"fragment"` `"predocumentary"` `"reconstruction"` | Apocrypha subtype | +| `depends_on` | optional | `["path1.md", "path2.md"]` | Source dependencies | +| `confidence` | optional | `"experiential"` `"unknown"` | Interpretive confidence | +| `provenance` | optional | `"cinematic"` `"disputed"` `"uncertain"` | Origin classification | +| `classification` | optional | `"post-stability record"` | Temporal classification | + +### audience: "odd" + +ODD documents define universal philosophy and methodology. + +| Field | Required? | Format | Notes | +|-------|-----------|--------|-------| +| `epoch` | optional | `"E0005"` | Which epoch | +| `date` | optional | `"2026-04-04"` | Date | +| `derives_from` | optional | `"path/to/source.md"` | Grounding | +| `version` | optional | `"1.0"` (quoted) | Document version | +| `slug` | if site-rendered | `"kebab-case"` | URL slug for public-facing ODD docs | + +--- + +## Archived Documents + +Any document can be archived by adding: + +```yaml +archived: "true" +archived_reason: "E0005.1 — superseded by description" +``` + +Archived documents remain in the knowledge base for history but are excluded from active navigation and search prioritization. + +--- + +## Smell Test — How to Detect a Frontmatter Violation + +- **YAML parse warnings or type coercion.** If a value parses as a non-string type (date, integer, boolean), it's unquoted. +- **Blank pages in PR previews.** The most common symptom of frontmatter errors. Usually caused by unquoted dates, missing `slug` on public docs, or missing `type` on essays. +- **Copying frontmatter from another document.** The smell itself. If the source of truth for frontmatter is "whatever document I found first," the schema is not being consulted. Consult this document instead. +- **Fields that don't appear in this schema.** If you're adding a field that doesn't appear here, either this schema needs updating (propose the addition) or the field is ad-hoc and shouldn't be added. + +--- + +## Required Response When a Violation Is Detected + +1. **Quote the value.** Every scalar value must be a quoted string. +2. **Check required fields.** Consult the audience-specific table above. If required fields are missing, add them. +3. **Consult this document, not other documents.** Do not copy frontmatter from another file to fix the problem. This schema is the source of truth. +4. **If this schema is incomplete, update it.** If a legitimate field is missing from this schema, add it here first, then use it. The schema must stay current with actual usage. + +--- + +## Enforcement + +This schema is a preflight and validate checkpoint. When the deliverable is a document, frontmatter compliance is a Definition of Done requirement alongside the Writing Canon checklist. + +The schema was derived from corpus analysis of 389 documents on April 4, 2026, and should be maintained as the canon evolves. Fields that appear in fewer than 5% of documents within an audience are not listed unless they serve a specific structural purpose. + +--- + +## See Also + +- [Writing Canon](klappy://canon/meta/writing-canon) — progressive disclosure and structural requirements for document bodies +- [Canon Article Template](klappy://canon/meta/TEMPLATE.md) — structural template for canon documents (consult this schema for field requirements) +- [Epistemic Obligation and Document Tiers](klappy://canon/definitions/epistemic-obligation-and-document-tiers) — what tier values mean +- [Definition of Done](klappy://canon/constraints/definition-of-done) — completion requirements including frontmatter compliance diff --git a/writings/the-feature-i-never-shipped.md b/writings/the-feature-i-never-shipped.md index 2679ec90..1b39b8e5 100644 --- a/writings/the-feature-i-never-shipped.md +++ b/writings/the-feature-i-never-shipped.md @@ -1,9 +1,12 @@ --- uri: "klappy://writings/the-feature-i-never-shipped" title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" +subtitle: "How strategic patience became the 6th B" +author: "Klappy" +type: "essay" audience: "public" exposure: "draft" -public: false +public: "false" tier: "2" voice: "first_person" stability: "semi_stable" @@ -12,6 +15,11 @@ epoch: "E0007.1" date: "2026-04-04" derives_from: "canon/methods/borrow-bend-break-beget-build.md, odd/constraint/use-only-what-hurts.md" complements: "writings/learning-in-the-open.md, canon/principles/vodka-architecture.md" +hook: "I spent months planning a feature. Four sessions. Twenty-five decisions. Two branches. None shipped. Then the problem dissolved on its own." +description: "The story of oddkit's write path — the most planned feature that never shipped — and why strategic patience is sometimes the best engineering. Introduces Bypass as the 6th B in the 5B method." +slug: "the-feature-i-never-shipped" +og_title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" +og_description: "I spent months planning a feature. Four sessions. Twenty-five decisions. Two branches. None shipped. Then the problem dissolved on its own." --- # The Feature I Never Shipped — And Why It's the Best Thing I've Built From 7a14e970f164e7a58469412d14d92cf87d797802 Mon Sep 17 00:00:00 2001 From: Klappy Date: Mon, 6 Apr 2026 12:36:34 +0000 Subject: [PATCH 8/9] =?UTF-8?q?fix:=20update=20epoch-7-1=20declaration=20?= =?UTF-8?q?=E2=80=94=20add=20DOLCHE,=20schema,=20correct=20document=20coun?= =?UTF-8?q?t?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/appendices/epoch-7-1.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/appendices/epoch-7-1.md b/docs/appendices/epoch-7-1.md index d9096e26..d00e0b30 100644 --- a/docs/appendices/epoch-7-1.md +++ b/docs/appendices/epoch-7-1.md @@ -13,7 +13,7 @@ extends: "Epoch 7 (from passive to proactive)" forcing_fault: "A proactive system without named architectural principles cannot explain why it works or detect when it stops working" new_invariant: "The architecture is named, the principles are formalized, and posture failure is detectable" core_shift: "Unnamed conventions → named design pattern. Tool-level governance articles → principle-level governance with smell tests, failure modes, and required responses. No posture lapse detection → structural self-assessment." -documents_introduced: ["canon/principles/vodka-architecture.md", "canon/principles/kiss-simplicity-is-the-ceiling.md", "canon/principles/dry-canon-says-it-once.md", "canon/principles/consistency-same-pattern-every-time.md", "canon/principles/maintainability-one-person-indefinitely.md", "canon/principles/prompt-over-code.md", "canon/principles/antifragile-failures-grow-canon.md", "docs/oddkit/proactive/posture-lapse.md", "docs/appendices/epoch-7-1.md"] +documents_introduced: ["canon/principles/vodka-architecture.md", "canon/principles/kiss-simplicity-is-the-ceiling.md", "canon/principles/dry-canon-says-it-once.md", "canon/principles/consistency-same-pattern-every-time.md", "canon/principles/maintainability-one-person-indefinitely.md", "canon/principles/prompt-over-code.md", "canon/principles/antifragile-failures-grow-canon.md", "docs/oddkit/proactive/posture-lapse.md", "docs/oddkit/proactive/dolche-vocabulary.md", "canon/meta/frontmatter-schema.md", "docs/appendices/epoch-7-1.md"] --- # Epoch 7.1 — Vodka Architecture and Principled Governance @@ -71,6 +71,14 @@ A meta-governance article that defines how to detect when the proactive cognitiv This closes the gap between E0007's tool-level "when to use" articles and the system-level question "is the proactive posture actually working?" +### DOLCHE — Superseding OLDC+H + +DOLCHE (Decisions, Observations, Learnings, Constraints, Handoffs, Encodes) supersedes OLDC+H by adding Encode as a meta-level action — not a sixth artifact type, but the act of crystallizing the other five, made visible and trackable. The vocabulary is extensible through governance documents: any knowledge base can add custom types without changing oddkit's server. + +### Frontmatter Schema — The Authoritative Reference + +A governance document defining every valid frontmatter field per audience, required types, quoting rules, and required vs optional status. Derived from corpus analysis of 389 documents. Supersedes template-based field guidance. Addresses the recurring "blank pages from broken frontmatter" problem by making the schema a preflight checkpoint rather than a copy-from-existing-doc ritual. + --- ## What E0007.1 Does Not Change @@ -95,6 +103,8 @@ This closes the gap between E0007's tool-level "when to use" articles and the sy | `canon/principles/prompt-over-code.md` | Prompt Over Code principle with smell tests, failure modes, required response | | `canon/principles/antifragile-failures-grow-canon.md` | Antifragile principle with smell tests, failure modes, required response | | `docs/oddkit/proactive/posture-lapse.md` | Posture lapse detection — system-level governance self-assessment | +| `docs/oddkit/proactive/dolche-vocabulary.md` | DOLCHE vocabulary — supersedes OLDC+H with meta-level Encode action | +| `canon/meta/frontmatter-schema.md` | Frontmatter schema — authoritative field reference for all documents | | This document | Sub-epoch declaration | --- From ee274f52d6020f86c77f63f9ddd33fdf44a2cfac Mon Sep 17 00:00:00 2001 From: Klappy Date: Mon, 6 Apr 2026 16:17:57 +0000 Subject: [PATCH 9/9] =?UTF-8?q?fix:=20undo=20string=20quoting=20=E2=80=94?= =?UTF-8?q?=20renderer=20expects=20native=20YAML=20types?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit quoted all values as strings. The site renderer expects native YAML types: booleans (public: true), integers (tier: 2), dates (date: 2026-04-04), and simple identifiers (audience: canon) must be UNQUOTED. Only strings with special characters get quotes. Fixed all 12 files. Updated frontmatter-schema.md to document the correct quoting rules derived from working articles. --- canon/meta/frontmatter-schema.md | 86 ++++++++++--------- .../antifragile-failures-grow-canon.md | 18 ++-- .../consistency-same-pattern-every-time.md | 18 ++-- canon/principles/dry-canon-says-it-once.md | 18 ++-- .../kiss-simplicity-is-the-ceiling.md | 18 ++-- ...maintainability-one-person-indefinitely.md | 18 ++-- canon/principles/prompt-over-code.md | 18 ++-- canon/principles/vodka-architecture.md | 18 ++-- docs/appendices/epoch-7-1.md | 16 ++-- docs/oddkit/proactive/dolche-vocabulary.md | 18 ++-- docs/oddkit/proactive/posture-lapse.md | 18 ++-- writings/the-feature-i-never-shipped.md | 24 +++--- 12 files changed, 148 insertions(+), 140 deletions(-) diff --git a/canon/meta/frontmatter-schema.md b/canon/meta/frontmatter-schema.md index 36dd60f4..797dd0c8 100644 --- a/canon/meta/frontmatter-schema.md +++ b/canon/meta/frontmatter-schema.md @@ -1,24 +1,24 @@ --- -uri: "klappy://canon/meta/frontmatter-schema" +uri: klappy://canon/meta/frontmatter-schema title: "Frontmatter Schema — The Authoritative Reference for All Document Metadata" -audience: "canon" -exposure: "nav" -tier: "1" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable tags: ["canon", "meta", "frontmatter", "schema", "YAML", "metadata", "governance", "template", "validation"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/meta/writing-canon.md, canon/values/axioms.md" complements: "canon/meta/TEMPLATE.md, docs/TEMPLATE.md, canon/constraints/definition-of-done.md" governs: "All YAML frontmatter in all documents across all directories" -status: "active" +status: active supersedes: "Frontmatter sections in canon/meta/TEMPLATE.md and docs/TEMPLATE.md (those remain as structural templates; this document is the authoritative field reference)" --- # Frontmatter Schema — The Authoritative Reference for All Document Metadata -> Every YAML frontmatter value must be quoted as a string. Every document must include the eight universal fields: uri, title, audience, exposure, tier, voice, stability, tags. Additional fields are required or optional per audience. This document is the single source of truth for frontmatter — not templates, not other documents, not pattern-matching from existing files. When in doubt, consult this document. When this document and another disagree, this document wins. +> YAML frontmatter values must match the types the site renderer expects: booleans unquoted, integers unquoted, dates unquoted, simple identifiers unquoted, strings with special characters quoted. Every document must include the eight universal fields: uri, title, audience, exposure, tier, voice, stability, tags. Additional fields are required or optional per audience. This document is the single source of truth for frontmatter — not templates, not other documents, not pattern-matching from existing files. When in doubt, consult this document. When this document and another disagree, this document wins. --- @@ -30,41 +30,49 @@ This document fixes the problem by defining the schema once. Templates (`canon/m --- -## The Universal Rule — All Values Quoted +## The Universal Rule — Quote Only What Needs Quoting -Every scalar value in YAML frontmatter must be wrapped in double quotes. No exceptions. +YAML frontmatter values follow a simple pattern derived from the working corpus: quote strings that contain special characters, leave simple identifiers and native types unquoted. ```yaml -# CORRECT -uri: "klappy://canon/principles/example" -title: "Example Title" -audience: "canon" -tier: "2" -date: "2026-04-04" -public: "false" -epoch: "E0007" - -# WRONG — these parse as non-string types +# Simple identifiers — unquoted +audience: canon +exposure: nav +voice: neutral +stability: semi_stable +type: essay +author: Klappy +slug: my-article-slug +epoch: E0007 +status: active + +# Integers — unquoted +tier: 2 + +# Booleans — unquoted +public: true +archived: false + +# Dates — unquoted +date: 2026-04-04 + +# URIs — unquoted uri: klappy://canon/principles/example -tier: 2 # parses as integer -date: 2026-04-04 # parses as date object -public: false # parses as boolean -epoch: E0007 # usually fine but inconsistent -``` -Arrays use inline format with quoted strings: +# Strings with special characters — quoted +title: "My Title — With Dashes and Colons: Like This" +subtitle: "Why it matters" +description: "A sentence with punctuation, dashes — and other characters." +hook: "The one-liner that grabs attention." +derives_from: "canon/values/axioms.md, canon/principles/other.md" +complements: "docs/path/to/sibling.md" +governs: "All documents in this scope" -```yaml -# CORRECT +# Arrays — inline with quoted strings tags: ["canon", "principle", "example"] - -# WRONG -tags: - - canon - - principle ``` -This rule exists because YAML silently coerces unquoted values. `2026-04-04` becomes a date object. `false` becomes a boolean. `1` becomes an integer. The site's renderer expects strings. When it gets a date object, the page goes blank. Quoting everything prevents the entire class of error. +The test is simple: if the value is a single word or simple identifier (no spaces, no special characters), leave it unquoted. If it contains spaces, punctuation, or special characters, quote it. Booleans, integers, and dates are always unquoted — the renderer expects native YAML types, not strings. --- @@ -212,8 +220,8 @@ Archived documents remain in the knowledge base for history but are excluded fro ## Smell Test — How to Detect a Frontmatter Violation -- **YAML parse warnings or type coercion.** If a value parses as a non-string type (date, integer, boolean), it's unquoted. -- **Blank pages in PR previews.** The most common symptom of frontmatter errors. Usually caused by unquoted dates, missing `slug` on public docs, or missing `type` on essays. +- **Type mismatches.** If a boolean field like `public` is quoted as `"false"` (a truthy string) instead of `false` (a boolean), the renderer behaves incorrectly. If an integer field like `tier` is quoted as `"2"` instead of `2`, type comparisons fail. +- **Blank pages in PR previews.** The most common symptom of frontmatter errors. Usually caused by quoted booleans/integers that should be native types, missing `slug` on public essays, or missing `type` on essays. - **Copying frontmatter from another document.** The smell itself. If the source of truth for frontmatter is "whatever document I found first," the schema is not being consulted. Consult this document instead. - **Fields that don't appear in this schema.** If you're adding a field that doesn't appear here, either this schema needs updating (propose the addition) or the field is ad-hoc and shouldn't be added. @@ -221,7 +229,7 @@ Archived documents remain in the knowledge base for history but are excluded fro ## Required Response When a Violation Is Detected -1. **Quote the value.** Every scalar value must be a quoted string. +1. **Match the type the renderer expects.** Booleans unquoted (`true`/`false`), integers unquoted (`2`), dates unquoted (`2026-04-04`), simple identifiers unquoted (`canon`, `nav`), complex strings quoted (`"Title — With Special Characters"`). 2. **Check required fields.** Consult the audience-specific table above. If required fields are missing, add them. 3. **Consult this document, not other documents.** Do not copy frontmatter from another file to fix the problem. This schema is the source of truth. 4. **If this schema is incomplete, update it.** If a legitimate field is missing from this schema, add it here first, then use it. The schema must stay current with actual usage. diff --git a/canon/principles/antifragile-failures-grow-canon.md b/canon/principles/antifragile-failures-grow-canon.md index f5d6a082..1a16f8d8 100644 --- a/canon/principles/antifragile-failures-grow-canon.md +++ b/canon/principles/antifragile-failures-grow-canon.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/antifragile-failures-grow-canon" +uri: klappy://canon/principles/antifragile-failures-grow-canon title: "Antifragile — Every Failure Grows the Canon, Never the Server" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "antifragile", "antifragility", "failure", "stress", "learning", "incidents", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, canon/resonance/antifragile.md, canon/values/axioms.md" complements: "canon/principles/prompt-over-code.md, canon/principles/ritual-is-a-smell.md" governs: "All failure response decisions in this program" -status: "active" +status: active --- # Antifragile — Every Failure Grows the Canon, Never the Server diff --git a/canon/principles/consistency-same-pattern-every-time.md b/canon/principles/consistency-same-pattern-every-time.md index bf4deea9..a0d6f48e 100644 --- a/canon/principles/consistency-same-pattern-every-time.md +++ b/canon/principles/consistency-same-pattern-every-time.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/consistency-same-pattern-every-time" +uri: klappy://canon/principles/consistency-same-pattern-every-time title: "Consistency — Same Pattern, Every Knowledge Base, Every Time" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "consistency", "portability", "MCP", "interface", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "docs/architecture/epistemic-os-layers.md, canon/principles/kiss-simplicity-is-the-ceiling.md" governs: "All MCP server interfaces and knowledge base serving patterns in this program" -status: "active" +status: active --- # Consistency — Same Pattern, Every Knowledge Base, Every Time diff --git a/canon/principles/dry-canon-says-it-once.md b/canon/principles/dry-canon-says-it-once.md index b8a7f884..6dd75232 100644 --- a/canon/principles/dry-canon-says-it-once.md +++ b/canon/principles/dry-canon-says-it-once.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/dry-canon-says-it-once" +uri: klappy://canon/principles/dry-canon-says-it-once title: "DRY — The Canon Says It Once, the Server Never Repeats It" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "DRY", "dont-repeat-yourself", "governance", "drift", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, canon/constraints/oddkit-prompt-pattern.md" complements: "canon/principles/prompt-over-code.md, canon/values/axioms.md" governs: "All governance rule placement decisions in this program" -status: "active" +status: active --- # DRY — The Canon Says It Once, the Server Never Repeats It diff --git a/canon/principles/kiss-simplicity-is-the-ceiling.md b/canon/principles/kiss-simplicity-is-the-ceiling.md index 2d5c076a..ef655e9c 100644 --- a/canon/principles/kiss-simplicity-is-the-ceiling.md +++ b/canon/principles/kiss-simplicity-is-the-ceiling.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/kiss-simplicity-is-the-ceiling" +uri: klappy://canon/principles/kiss-simplicity-is-the-ceiling title: "KISS — Simplicity Is the Ceiling, Not the Floor" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "KISS", "simplicity", "design", "composability", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "canon/principles/ritual-is-a-smell.md, canon/principles/maintainability-one-person-indefinitely.md" governs: "All MCP servers, tools, and orchestration layers in this program" -status: "active" +status: active --- # KISS — Simplicity Is the Ceiling, Not the Floor diff --git a/canon/principles/maintainability-one-person-indefinitely.md b/canon/principles/maintainability-one-person-indefinitely.md index 32ab2578..099fbb87 100644 --- a/canon/principles/maintainability-one-person-indefinitely.md +++ b/canon/principles/maintainability-one-person-indefinitely.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/maintainability-one-person-indefinitely" +uri: klappy://canon/principles/maintainability-one-person-indefinitely title: "Maintainability — One Person, Indefinitely" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "maintainability", "sustainability", "single-maintainer", "cloudflare-worker", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, canon/values/axioms.md" complements: "canon/principles/ritual-is-a-smell.md, canon/principles/kiss-simplicity-is-the-ceiling.md" governs: "All infrastructure sizing and complexity decisions in this program" -status: "active" +status: active --- # Maintainability — One Person, Indefinitely diff --git a/canon/principles/prompt-over-code.md b/canon/principles/prompt-over-code.md index 74323b03..af8ec36b 100644 --- a/canon/principles/prompt-over-code.md +++ b/canon/principles/prompt-over-code.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/prompt-over-code" +uri: klappy://canon/principles/prompt-over-code title: "Prompt Over Code — Fully Programmable Governance Without Changing the Server" -audience: "canon" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["canon", "principle", "prompt-over-code", "convention-over-configuration", "governance", "programmable", "vodka-architecture", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/principles/vodka-architecture.md, docs/appendices/convention-requires-an-enforcer.md, canon/constraints/oddkit-prompt-pattern.md" complements: "odd/prompt-architecture.md, canon/principles/ritual-is-a-smell.md, canon/principles/dry-canon-says-it-once.md" governs: "All governance rule implementation decisions in this program" -status: "active" +status: active --- # Prompt Over Code — Fully Programmable Governance Without Changing the Server diff --git a/canon/principles/vodka-architecture.md b/canon/principles/vodka-architecture.md index e3025c68..59eb8ae9 100644 --- a/canon/principles/vodka-architecture.md +++ b/canon/principles/vodka-architecture.md @@ -1,18 +1,18 @@ --- -uri: "klappy://canon/principles/vodka-architecture" +uri: klappy://canon/principles/vodka-architecture title: "Vodka Architecture — The Design Pattern for Epistemic Infrastructure" -audience: "canon" -exposure: "nav" -tier: "1" -voice: "neutral" -stability: "semi_stable" +audience: canon +exposure: nav +tier: 1 +voice: neutral +stability: semi_stable tags: ["canon", "architecture", "design-pattern", "vodka", "stateless", "thin-layer", "epistemic-infrastructure", "KISS", "DRY", "antifragile", "convention-over-configuration", "maintainability"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/values/axioms.md, canon/principles/ritual-is-a-smell.md, canon/resonance/antifragile.md, docs/appendices/convention-requires-an-enforcer.md" complements: "docs/architecture/epistemic-os-layers.md, odd/prompt-architecture.md, canon/constraints/oddkit-prompt-pattern.md" governs: "All MCP servers, knowledge base serving infrastructure, and orchestration layers in this program" -status: "active" +status: active --- # Vodka Architecture — The Design Pattern for Epistemic Infrastructure diff --git a/docs/appendices/epoch-7-1.md b/docs/appendices/epoch-7-1.md index d00e0b30..a3f5742f 100644 --- a/docs/appendices/epoch-7-1.md +++ b/docs/appendices/epoch-7-1.md @@ -1,14 +1,14 @@ --- -uri: "klappy://docs/appendices/epoch-7-1" +uri: klappy://docs/appendices/epoch-7-1 title: "Epoch 7.1 — Vodka Architecture and Principled Governance" -audience: "docs" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "stable" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: stable tags: ["odd", "epochs", "vodka-architecture", "design-pattern", "principles", "governance", "posture-lapse", "epoch-7", "epoch-7.1"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 extends: "Epoch 7 (from passive to proactive)" forcing_fault: "A proactive system without named architectural principles cannot explain why it works or detect when it stops working" new_invariant: "The architecture is named, the principles are formalized, and posture failure is detectable" diff --git a/docs/oddkit/proactive/dolche-vocabulary.md b/docs/oddkit/proactive/dolche-vocabulary.md index 04d6dc68..502334a2 100644 --- a/docs/oddkit/proactive/dolche-vocabulary.md +++ b/docs/oddkit/proactive/dolche-vocabulary.md @@ -1,19 +1,19 @@ --- -uri: "klappy://docs/oddkit/proactive/dolche-vocabulary" +uri: klappy://docs/oddkit/proactive/dolche-vocabulary title: "DOLCHE — Six Dimensions of Session Capture" -audience: "docs" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["odd", "oddkit", "dolche", "oldc-h", "observations", "learnings", "decisions", "constraints", "handoffs", "encodes", "vocabulary", "session-capture", "project-journal", "epoch-7.1"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 supersedes: "docs/oddkit/proactive/oldc-h-vocabulary.md" derives_from: "canon/values/axioms.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/encode-does-not-persist.md" complements: "docs/oddkit/proactive/posture-lapse.md, docs/oddkit/proactive/proactive-session-close.md, odd/ledger/project-journal-best-practices.md" governs: "All session capture, project journal entries, and encode invocations" -status: "active" +status: active --- # DOLCHE — Six Dimensions of Session Capture diff --git a/docs/oddkit/proactive/posture-lapse.md b/docs/oddkit/proactive/posture-lapse.md index f9e9a7ab..5573d8ec 100644 --- a/docs/oddkit/proactive/posture-lapse.md +++ b/docs/oddkit/proactive/posture-lapse.md @@ -1,18 +1,18 @@ --- -uri: "klappy://docs/oddkit/proactive/posture-lapse" +uri: klappy://docs/oddkit/proactive/posture-lapse title: "Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down" -audience: "docs" -exposure: "nav" -tier: "2" -voice: "neutral" -stability: "semi_stable" +audience: docs +exposure: nav +tier: 2 +voice: neutral +stability: semi_stable tags: ["oddkit", "proactive", "governance", "lapse", "breakdown", "cognitive-rhythm", "smell", "failure-mode", "orient", "gate", "search", "encode", "challenge", "preflight", "validate", "tool-use", "epoch-7", "design-smell"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "docs/appendices/epoch-7.md, canon/principles/ritual-is-a-smell.md, canon/values/axioms.md" complements: "docs/oddkit/proactive/proactive-orient.md, docs/oddkit/proactive/proactive-gate.md, docs/oddkit/proactive/proactive-search.md, docs/oddkit/proactive/proactive-challenge.md, docs/oddkit/proactive/proactive-validate.md, docs/oddkit/proactive/proactive-preflight.md, docs/oddkit/proactive/continuous-encoding.md, docs/oddkit/proactive/proactive-identity-of-integrity.md" governs: "All agent behavior in oddkit-powered sessions" -status: "active" +status: active --- # Proactive Posture Lapse — Detecting When the Cognitive Rhythm Breaks Down diff --git a/writings/the-feature-i-never-shipped.md b/writings/the-feature-i-never-shipped.md index 1b39b8e5..a587d01b 100644 --- a/writings/the-feature-i-never-shipped.md +++ b/writings/the-feature-i-never-shipped.md @@ -1,23 +1,23 @@ --- -uri: "klappy://writings/the-feature-i-never-shipped" +uri: klappy://writings/the-feature-i-never-shipped title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" subtitle: "How strategic patience became the 6th B" -author: "Klappy" -type: "essay" -audience: "public" -exposure: "draft" -public: "false" -tier: "2" -voice: "first_person" -stability: "semi_stable" +author: Klappy +type: essay +audience: public +exposure: draft +public: false +tier: 2 +voice: first_person +stability: semi_stable tags: ["writings", "essay", "5B", "bypass", "write-path", "oddkit", "use-only-what-hurts", "strategic-patience", "ai-augmented-workflows"] -epoch: "E0007.1" -date: "2026-04-04" +epoch: E0007.1 +date: 2026-04-04 derives_from: "canon/methods/borrow-bend-break-beget-build.md, odd/constraint/use-only-what-hurts.md" complements: "writings/learning-in-the-open.md, canon/principles/vodka-architecture.md" hook: "I spent months planning a feature. Four sessions. Twenty-five decisions. Two branches. None shipped. Then the problem dissolved on its own." description: "The story of oddkit's write path — the most planned feature that never shipped — and why strategic patience is sometimes the best engineering. Introduces Bypass as the 6th B in the 5B method." -slug: "the-feature-i-never-shipped" +slug: the-feature-i-never-shipped og_title: "The Feature I Never Shipped — And Why It's the Best Thing I've Built" og_description: "I spent months planning a feature. Four sessions. Twenty-five decisions. Two branches. None shipped. Then the problem dissolved on its own." ---