From 7167d1ae67a850f6a3c0f782946e24596868680a Mon Sep 17 00:00:00 2001 From: Klappy via Claude Date: Sun, 26 Apr 2026 19:22:40 +0000 Subject: [PATCH] cleanup(writings): convert legacy /page/ patterns to klappy:// URIs + amend campaign doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2 PR-2.2 of the link-rot-elimination campaign. Resolver is the first user of itself: every new klappy:// URI was test-resolved against live prod (oddkit v0.25.0) before commit. Writings cleanup (10 link edits across 3 files): - writings/getting-started-with-odd-and-oddkit.md (4 /page/ → klappy://) - writings/from-passive-to-proactive.md (4 /page/ → klappy://) - writings/agentic-software-development.md (1 typo URI: klappy://writings/nothing-new-even-ai → klappy://writings/preface-nothing-new-even-ai — verified via resolver, the actual canonical URI) Verified resolves before commit: - klappy://writings/the-journey-from-ai-tasks-to-ai-augmented-workflows - klappy://docs/oddkit/proactive/proactive-bootstrap - klappy://docs/examples/project-instructions-template - klappy://writings/learning-in-the-open - klappy://writings/getting-started-with-odd-and-oddkit - klappy://writings/preface-nothing-new-even-ai Out-of-scope notes (will not be "fixed" by this PR): - klappy://draft-zeros/appendix-a-the-biblical-roots in writings/the-broken-wall-and-the-buried-talent.md is NOT_FOUND because the target is a draft-zero with stability=placeholder and is filtered from the index by design. A published essay linking to an unpublished draft is a different problem class — content gap, not link rot. Campaign doc amendment (bundled per operator decision): - Named the explicit promote PR (main → prod) step for oddkit changes; CF auto-deploys from prod, not main. The original draft elided this because the author hadn't observed the prod-branch convention; PR-2.1 surfaced it when prod stayed on 0.24.0 after the merge to main. - Corrected PR-2.2's scope: dropped the "re-audit the 49" task. The April 9 audit's 49 remaining items are correctly classified as intentional (template placeholders, site routes, historical archive refs); they fall outside writings/ and don't need re-classification via the new resolver. - Recorded both amendments in Origin section as v2.1. Refs: - klappy://docs/oddkit/specs/oddkit-resolve (DRAFT v4 — KISS, in prod) - klappy://canon/principles/identity-resolved-by-protocol - klappy://docs/planning/link-rot-elimination-campaign (v2.1 amendment) - klappy://canon/principles/vodka-architecture - klappy/oddkit#140 (resolver implementation, merged + promoted) - klappy/oddkit#142 (promote PR, merged) --- docs/planning/link-rot-elimination-campaign.md | 17 ++++++++++++----- writings/agentic-software-development.md | 2 +- writings/from-passive-to-proactive.md | 8 ++++---- writings/getting-started-with-odd-and-oddkit.md | 8 ++++---- 4 files changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/planning/link-rot-elimination-campaign.md b/docs/planning/link-rot-elimination-campaign.md index c87499d7..f659ca56 100644 --- a/docs/planning/link-rot-elimination-campaign.md +++ b/docs/planning/link-rot-elimination-campaign.md @@ -42,12 +42,17 @@ Phase 1 — Foundation (3 PRs, parallelizable) this campaign doc) Phase 2 — Implementation (3 PRs, serial) - ├── PR-2.1 — Implement oddkit_resolve action + ├── PR-2.1 — Implement oddkit_resolve action [klappy/oddkit] │ ⚠️ Release-validation-gate per E0008.3 - ├── PR-2.2 — Convert legacy patterns in writings/ to klappy:// URIs - │ Re-audit the 49 from April-9 audit; fix or delete - └── PR-2.3 — Implement oddkit_audit action + │ ⚠️ Plus separate promote PR: main → prod (CF auto-deploys from prod) + ├── PR-2.2 — Convert legacy patterns in writings/ to klappy:// URIs [klappy/klappy.dev] + │ Validates each new URI against the live resolver before commit. + │ (The 49 from the April-9 audit are correctly classified as + │ intentional/template/route placeholders and out-of-scope here; + │ see docs/audits/reference-integrity-audit-2026-04-09.md.) + └── PR-2.3 — Implement oddkit_audit action [klappy/oddkit] ⚠️ Release-validation-gate per E0008.3 + ⚠️ Plus separate promote PR: main → prod Phase 3 — Enforcement (2 PRs, serial after observation) ├── PR-3.1 — canon-quality.yml workflow (soft-block this cycle) @@ -55,7 +60,7 @@ Phase 3 — Enforcement (2 PRs, serial after observation) (config flip after observation cycle) ``` -Eight PRs total. Critical path is six PRs (PR-1.1 → PR-1.2 → PR-2.1 → PR-2.3 → PR-3.1 → PR-3.2). The other two (PR-1.3, PR-2.2) ship in parallel. +Eight PRs total in klappy/klappy.dev plus two in klappy/oddkit, plus two promote PRs (main→prod) for the oddkit changes that touch load-bearing surface. Critical path is the same six-PR sequence; the promote PRs are mechanical follow-ups (head=main → base=prod, single commit, zero diff vs main) but **must** be opened explicitly because CF deploys from `prod`, not `main`. ## Dependencies @@ -115,3 +120,5 @@ Each of these is a real concern with a real revisit condition. None is in this c ## Origin Drafted on 2026-04-26 as the v2 KISS revision of the campaign. The v1 version had six phases and ~15 PRs and violated Vodka principles by pre-building infrastructure for hypothetical pain. v2 cuts to three phases, eight PRs, and the four-artifact minimum. The cut work moved to the deferred-concerns ledger with explicit revisit triggers. Operator's framing: "Vodka principles, KISS, antifragile, maintainable, consistent." + +**v2.1 amendment (2026-04-26, end of PR-2.1):** Added explicit promote-PR step (main → prod) for any oddkit change touching load-bearing surface. The original draft elided this because the author hadn't observed the prod-branch convention; PR-2.1 surfaced it when prod stayed on 0.24.0 after merging to main. Also corrected PR-2.2's scope: the "re-audit the 49" task was dropped on inspection — the April 9 audit's 49 remaining items are correctly classified as intentional template placeholders, deployed site routes, and historical archive references that fall outside writings/ scope. Both amendments preserve the campaign's KISS shape; neither adds new artifacts. diff --git a/writings/agentic-software-development.md b/writings/agentic-software-development.md index 4d7b29ee..df1cd506 100644 --- a/writings/agentic-software-development.md +++ b/writings/agentic-software-development.md @@ -239,7 +239,7 @@ So what do we do? We build anyway. Frontier models will swallow anything we build. [I build anyway.](klappy://writings/learning-in-the-open) Because if I do not, I wait forever. And if I do, I have a window — however small — where I know we made a difference. -[There is nothing new under the sun.](klappy://writings/nothing-new-even-ai) Not even AI. The principles are ancient. The tools are new. The question is the same one it has always been: will you engage with integrity, or will you bury what you have been given? +[There is nothing new under the sun.](klappy://writings/preface-nothing-new-even-ai) Not even AI. The principles are ancient. The tools are new. The question is the same one it has always been: will you engage with integrity, or will you bury what you have been given? Everything I have referenced is available at klappy.dev. You can read every article. You can listen to AI-generated podcasts of each one — in my voice, because yes, we built that too. You can open the fireside chat and ask my AI questions. And if — only if — the pain is real for you, you can connect oddkit and the Aquifer MCP server to your own tools and see if they help. diff --git a/writings/from-passive-to-proactive.md b/writings/from-passive-to-proactive.md index 5aa2a9b8..abd06beb 100644 --- a/writings/from-passive-to-proactive.md +++ b/writings/from-passive-to-proactive.md @@ -174,7 +174,7 @@ And a bootstrap prompt — the system prompt that teaches the AI its posture fro ## Honesty About Mistakes -This wouldn't be a [Learning in the Open](/page/writings/learning-in-the-open) companion if I didn't include the parts that went wrong. +This wouldn't be a [Learning in the Open](klappy://writings/learning-in-the-open) companion if I didn't include the parts that went wrong. During implementation, the governance articles didn't appear in oddkit's search results. I assumed it was a caching issue — the Cloudflare Worker caches the search index, and propagation takes time. I waited. Checked again. Still missing. @@ -206,7 +206,7 @@ The A/B test proves that governance articles surface when agents search for proa A BM25 score of 29 means the article will be found. It does not mean the agent will read it, follow it, or apply the technique correctly. Behavioral testing — observing real agents in real sessions with real operators — is required to validate outcomes. That testing hasn't happened yet. -I'm publishing this essay before that testing is complete, deliberately. [Learning in the open](/page/writings/learning-in-the-open) means publishing the messy version — the one with open questions and incomplete validation — rather than waiting for the polished version that never ships. +I'm publishing this essay before that testing is complete, deliberately. [Learning in the open](klappy://writings/learning-in-the-open) means publishing the messy version — the one with open questions and incomplete validation — rather than waiting for the polished version that never ships. --- @@ -222,7 +222,7 @@ His words: *"I was reading page after page of it selling it and I was like, I fe The system I built to be proactive and participatory had no getting-started page. No install instructions. No link from the public site to the GitHub repos. The irony was sharp: the canon already said all the right things about progressive disclosure, zero-config onramps, and vocabulary emerging from use. Those principles hadn't been applied to oddkit's own onboarding. -Joshua's gap analysis became the spec for a companion article: [Getting Started with ODD and oddkit](/page/writings/getting-started-with-odd-and-oddkit). The proactive posture and the onboarding gap are the same problem seen from different directions — a system that requires the user to figure things out on their own has delegated its cognition to the wrong party, whether that's remembering to invoke tools or remembering how to install them. +Joshua's gap analysis became the spec for a companion article: [Getting Started with ODD and oddkit](klappy://writings/getting-started-with-odd-and-oddkit). The proactive posture and the onboarding gap are the same problem seen from different directions — a system that requires the user to figure things out on their own has delegated its cognition to the wrong party, whether that's remembering to invoke tools or remembering how to install them. --- @@ -250,4 +250,4 @@ What I know now: if you build a system and find yourself performing the same rit The system acts. The operator reviews. Start wherever it hurts. -*For the practical getting-started guide, see [Getting Started with ODD and oddkit](/page/writings/getting-started-with-odd-and-oddkit). For the previous essay in this series, see [Learning in the Open](/page/writings/learning-in-the-open).* +*For the practical getting-started guide, see [Getting Started with ODD and oddkit](klappy://writings/getting-started-with-odd-and-oddkit). For the previous essay in this series, see [Learning in the Open](klappy://writings/learning-in-the-open).* diff --git a/writings/getting-started-with-odd-and-oddkit.md b/writings/getting-started-with-odd-and-oddkit.md index a2fe637b..efc7eeb8 100644 --- a/writings/getting-started-with-odd-and-oddkit.md +++ b/writings/getting-started-with-odd-and-oddkit.md @@ -66,7 +66,7 @@ You use AI every day. Each session is impressive. But nothing carries over with oddkit is an MCP server — a standard protocol that lets AI tools connect to external services. You add it to whatever AI tool you already use: Claude, ChatGPT, Gemini, Cursor, Claude Code, Lovable, Replit, ElevenLabs voice agents — anything that supports MCP. It takes thirty seconds. Then you bootstrap — paste a short identity statement into your project instructions that teaches the AI to verify before claiming, admit what it hasn't checked, and use oddkit proactively. After that, every session starts from a posture of integrity instead of a blank slate. -This page gets you from zero to running in five minutes. The [deeper journey](/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows) — building your own knowledge base, encoding decisions, making AI collaboration cumulative — is there when you're ready. Start here. +This page gets you from zero to running in five minutes. The [deeper journey](klappy://writings/the-journey-from-ai-tasks-to-ai-augmented-workflows) — building your own knowledge base, encoding decisions, making AI collaboration cumulative — is there when you're ready. Start here. --- @@ -199,9 +199,9 @@ before calling something done. Think of it as an employee handbook that you and the AI both agree to. You're not configuring a tool — you're establishing shared integrity. The creed and axioms aren't aspirational. They're operational constraints that make the AI behave like someone you'd actually trust with your work. -The [full bootstrap prompt](/page/docs/oddkit/proactive/proactive-bootstrap) includes additional guidance on continuous session capture, artifact provenance, and proactive tool usage — use it when you're ready for the complete version. The compact version above is enough to start. +The [full bootstrap prompt](klappy://docs/oddkit/proactive/proactive-bootstrap) includes additional guidance on continuous session capture, artifact provenance, and proactive tool usage — use it when you're ready for the complete version. The compact version above is enough to start. -If you want to see the actual template I use — creed, axioms, time perception, mode discipline, bottleneck respect, and the pointer to the evolving operating contract all in one system prompt — see [Project Instructions Template](/page/docs/examples/project-instructions-template). It's model-agnostic; the same template works for Claude, GPT, Gemini, or any LLM with tool-use and an MCP connection. +If you want to see the actual template I use — creed, axioms, time perception, mode discipline, bottleneck respect, and the pointer to the evolving operating contract all in one system prompt — see [Project Instructions Template](klappy://docs/examples/project-instructions-template). It's model-agnostic; the same template works for Claude, GPT, Gemini, or any LLM with tool-use and an MCP connection. ### A Note on Permissions @@ -257,7 +257,7 @@ This is how I work. It's the difference between using AI for tasks and AI-augmen For an example, browse the [klappy.dev repo](https://github.com/klappy/klappy.dev). You'll find governance (`canon/`), methodology (`odd/`), planning and implementation records (`docs/`), and public essays (`writings/`). You don't need any of that to start. But it's there when you want to see how deep the rabbit hole goes. -The progression — from a few markdown files to a living knowledge base — is described in detail in [The Journey from AI Tasks to AI-Augmented Workflows](/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows). +The progression — from a few markdown files to a living knowledge base — is described in detail in [The Journey from AI Tasks to AI-Augmented Workflows](klappy://writings/the-journey-from-ai-tasks-to-ai-augmented-workflows). ---