Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
17 changes: 3 additions & 14 deletions .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -1,16 +1,5 @@
#!/usr/bin/env sh

# Sync content to public folder and generate manifest
npm run sync

# Generate the klappy book export
npm run book

# Build docs index for Librarian fast-lookup
npm run docs:index

# Stage the generated files so they are included in the commit
git add public/content/
git add public/content/manifest.json
git add public/_compiled/index/
git add klappy-dev-book-export.md
# E0005.1: Pre-commit hooks for defunct pipeline removed.
# sync-content, export-book, and build-docs-index scripts
# were part of the lane-era pipeline (see D0016).
25 changes: 10 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,12 @@ Start with **ODD** (Outcomes-Driven Development) — the core philosophy that sh

If that resonates, the **Canon** contains the principles, constraints, and verification standards that guide decisions.

If you want to see the philosophy applied, browse the **Projects**.
If you want to see the philosophy applied, browse the **Derivative Works** documentation.

There is no required order. Follow your curiosity.

- `/docs/WHAT_THIS_REPO_IS_NOT.md` — what this repository is intentionally not
- `/projects/agentic-memory-portability.md` — the memory portability project
- `/docs/appendices/WHAT_THIS_REPO_IS_NOT.md` — what this repository is intentionally not
- `/docs/derivative-works.md` — how derivative products relate to ODD

---

Expand All @@ -75,7 +75,6 @@ It does not execute anything by itself and is intentionally separated from tooli

The Canon uses pack-level versioning with a single changelog:

- `/public/content/manifest.json` — generated inventory of what exists (compiled from per-file frontmatter)
- `/canon/CHANGELOG.md` — record of changes

Individual files are not versioned independently to avoid unnecessary ceremony.
Expand Down Expand Up @@ -106,22 +105,18 @@ If you're new and want a concrete path, here's a reasonable order:
- `/canon/index.md` (orientation)
- Supporting documents on constraints, decision rules, evidence, and verification

4. **Projects** — proofs of concept and experiments (added over time)
4. **Derivative Works** — how products relate to ODD (`/docs/derivative-works.md`)

---

## Web App (Phase 1)
## Structure

This repository includes a static SPA for browsing content via a chat-first interface.
This repository is organized around a three-tier hierarchy:

```bash
npm install
npm run dev
```

The app lives in `/src` and serves content from `/public/content/`.

**Note:** `/public/content/` contains copies of source content (`/canon`, `/odd`, `/about`, `/projects`) for the SPA to serve. The source folders remain the canonical authoring location; `/public/content/` is the rendered content root for the web app.
- `/odd/` — Universal ODD philosophy (timeless, product-agnostic)
- `/canon/` — Program constraints (shared governance)
- `/docs/` — Implementation details (how we do it here)
- `/about/` — Author context and credibility

---

Expand Down
4 changes: 3 additions & 1 deletion canon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,9 @@ Prefer stable file and URI naming over clever branding. Rename rarely.
First-person documents may be consumed as-is or translated by clients. The Canon itself does not require a specific rendering voice.

**5. Multi-Lane PRD Architecture**
PRDs are organized into independent product lanes. Each lane has its own active PRD, attempts, and lifecycle. Lanes share canon, not lifecycle. See `/docs/appendices/product-lanes.md` for the full model.
PRDs are organized into independent product lanes. Each lane has its own active PRD, attempts, and lifecycle. Lanes share canon, not lifecycle.

> ⚠️ **E0005.1 Review:** This meta rule references the archived lane/product model. The linked doc (`/docs/appendices/product-lanes.md`) has been archived to `docs/archive/`. This rule is under review as part of E0005.1 (Structure-Agnostic ODD) and may be revised or removed.

---

Expand Down
6 changes: 4 additions & 2 deletions canon/constraints/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Constraints define the baseline assumptions and design defaults applied to most
- MUST design for offline-first unless explicitly stated otherwise; core functionality must work without network
- MUST treat AI as accelerator, not authority; this constraint is always in effect with no exceptions
- MUST verify work with evidence; assertions like "it works" are insufficient
- MUST keep lane artifacts self-contained within `products/<lane>/`; no cross-directory dependencies
- MUST keep lane artifacts self-contained; no cross-directory dependencies *(path under E0005.1 review)*
- MUST make tradeoffs explicit and visible; every decision excludes alternatives
- MUST assume systems will outlive original creators and change hands
- MUST establish single-agent integrity before scaling collaboration; integrity precedes participation
Expand Down Expand Up @@ -89,7 +89,7 @@ Constraints define the baseline assumptions and design defaults applied to most
- System works without network (for offline-first requirements)
- Evidence produced demonstrates actual behavior, not assertion
- Tradeoffs documented with explicit acknowledgment of downsides
- Lane can be understood by reading only its `products/<lane>/` directory
- Lane can be understood by reading only its directory *(path under E0005.1 review)*
- Next maintainer (who is not the author) can understand and modify the system

---
Expand Down Expand Up @@ -338,6 +338,8 @@ Every decision excludes alternatives. Unspoken tradeoffs cause confusion later.

## 11. Lane Self-Containment

> ⚠️ **E0005.1 Review:** This constraint references the `products/<lane>/` directory model which has been archived as part of E0005.1 (Structure-Agnostic ODD). The substantive principle (self-containment of work units) may be preserved in revised form. This section is under human review — do not delete or rewrite.

I require product lanes to be self-contained units.

**Why this matters**
Expand Down
2 changes: 1 addition & 1 deletion canon/meta/TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Do NOT add to Canon when:

- It's implementation-specific → `/docs/`
- It's universal philosophy → `/odd/`
- It's lane-specific → `/products/<lane>/`
- It's project-specific → project docs

**Litmus test:** Should all products obey this? → Canon ✓

Expand Down
2 changes: 0 additions & 2 deletions canon/resonance/lean-startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,4 @@ ODD absorbs Lean Startup's speed while rejecting its tolerance for epistemic amn

## Related Canon

- [Attempts](/odd/appendices/attempt-lifecycle.md)
- [Lane Architecture](/docs/appendices/product-lanes.md)
- [Evolution Not Automation](/odd/appendices/evolution-not-automation.md)
2 changes: 0 additions & 2 deletions canon/resonance/ooda-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,5 +71,3 @@ ODD treats orientation as cumulative capital. By externalizing it into artifacts
## Related Canon

- [ODD Manifesto](/odd/manifesto.md)
- [Lane Architecture](/docs/appendices/product-lanes.md)
- [Attempts](/docs/appendices/ATTEMPTS.md)
38 changes: 9 additions & 29 deletions docs/CONTENT-MAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,7 @@ This map provides navigational links to ALL content in the repository, including
|------|---------|
| [/docs/README.md](/docs/README.md) | Docs index |
| [/docs/oddkit/WHY.md](/docs/oddkit/WHY.md) | **Why oddkit exists** — Start here for oddkit |
| [/docs/appendices/ATTEMPTS.md](/docs/appendices/ATTEMPTS.md) | Attempt lifecycle |
| [/docs/TRUTH_MAP.md](/docs/TRUTH_MAP.md) | Authoritative sources per domain |
| [/docs/derivative-works.md](/docs/derivative-works.md) | Derivative works and product guidance |
| [/docs/incidents/README.md](/docs/incidents/README.md) | Incident records — failures that changed the canon |

**Subdirectories:**
Expand All @@ -95,8 +94,9 @@ This map provides navigational links to ALL content in the repository, including
- `/docs/history/` — What happened, with evidence
- `/docs/plans/` — Forward-looking design & planning
- `/docs/migrations/` — How we change the system
- `/docs/infra/` — Infrastructure documentation
- `/docs/promotions/` — Canon promotion process
- `/docs/templates/` — Document templates (PRD, etc.)
- `/docs/archive/` — Archived content from prior structure

---

Expand Down Expand Up @@ -161,32 +161,12 @@ This map provides navigational links to ALL content in the repository, including
| [/about/faq.md](/about/faq.md) | Frequently asked questions |
| [/about/why-this-exists.md](/about/why-this-exists.md) | Why this repository exists |

### Projects (`/projects/`)
### Archived Areas (see `/docs/archive/`)

| File | Purpose |
|------|---------|
| [/projects/index.md](/projects/index.md) | Projects index |
| [/projects/agentic-memory-portability.md](/projects/agentic-memory-portability.md) | Memory portability project |
| [/projects/ADDING-A-PROJECT.md](/projects/ADDING-A-PROJECT.md) | How to add projects |
| `/projects/repo-as-a-system/` | Repo-as-system exploration |

### Products (`/products/`)

Active product lanes:
- `/products/website/` — Web app
- `/products/agent-skill/` — Agent skill product
- `/products/odd-teaser/` — ODD teaser
- `/products/fluent-mobile/` — Mobile product
- `/products/ai-navigation/` — Navigation product

### Infrastructure (`/infra/`)

| Path | Purpose |
|------|---------|
| `/infra/orchestrator/` | oddkit orchestrator code |
| `/infra/scripts/` | Build and compile scripts |
| `/infra/runners/` | Recipe pack runners |
| `/infra/prompts/` | Prompt templates |
The following areas have been archived as part of E0005 (Structure-Agnostic ODD):
- `projects/` — archived to `docs/archive/projects/`
- `products/` — archived to `docs/archive/products/`
- `infra/` — archived to `docs/archive/infra/`

---

Expand All @@ -197,7 +177,7 @@ Active product lanes:
| **ODD** | Outcomes-Driven Development | [/odd/README.md](/odd/README.md) |
| **ESE** | Epistemic Surface Extraction | [/canon/methods/epistemic-surface-extraction.md](/canon/methods/epistemic-surface-extraction.md) |
| **MCP** | Model Context Protocol | `/interfaces/mcp/` |
| **PRD** | Product Requirements Document | `/docs/PRD.md` |
| **PRD** | Product Requirements Document | `/docs/templates/PRD_TEMPLATE.md` |
| **ADR** | Architecture Decision Record | `/canon/decisions/decision-record-standard.md` |

---
Expand Down
24 changes: 8 additions & 16 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,11 @@ tags: ["docs", "implementation", "reference", "index"]

| Content Type | Examples | Why Here |
|--------------|----------|----------|
| CLI commands | `attempt:register`, `attempt:nuke` | Tool-specific |
| Specific paths | `/products/<lane>/attempts/...` | Repo-specific |
| CLI commands | `oddkit orient`, `oddkit validate` | Tool-specific |
| Specific paths | `/docs/archive/...`, `/docs/templates/...` | Repo-specific |
| Cloudflare config | Branch deploys, preview URLs | Vendor-specific |
| Lane names | `website`, `ai-navigation`, `agent-skill` | Instance-specific |
| Epoch definitions | E0001, E0002, E0003 | Instance-specific |
| Tooling runbooks | ATTEMPTS.md, PREVIEW.md | Procedural |
| Epoch definitions | E0001–E0005 | Instance-specific |
| Tooling runbooks | Agent kickoff, orchestrator guides | Procedural |

---

Expand Down Expand Up @@ -68,20 +67,14 @@ tags: ["docs", "implementation", "reference", "index"]

| File | Purpose |
|------|---------|
| [appendices/ATTEMPTS.md](./appendices/ATTEMPTS.md) | Attempt lifecycle, CLI commands, artifact locations |
| [appendices/ATTEMPT_KICKOFF.md](./appendices/ATTEMPT_KICKOFF.md) | Human workflow for starting attempts |
| [agents/AGENT_KICKOFF.md](./agents/AGENT_KICKOFF.md) | Canonical agent entry point |
| [infra/PREVIEW.md](./infra/PREVIEW.md) | Local and Cloudflare preview guide |
| [infra/CLOUDFLARE_CONFIG.md](./infra/CLOUDFLARE_CONFIG.md) | Deploy configuration |
| [derivative-works.md](./derivative-works.md) | Derivative works and product guidance |

### Reference Documents

| File | Purpose |
|------|---------|
| [TRUTH_MAP.md](./TRUTH_MAP.md) | Authoritative source for each domain |
| [PRD.md](./PRD.md) | PRD orientation and routing |
| [appendices/WHAT_THIS_REPO_IS_NOT.md](./appendices/WHAT_THIS_REPO_IS_NOT.md) | Scope boundaries |
| [appendices/context-packs-and-projection-detail.md](./appendices/context-packs-and-projection-detail.md) | Detail levels for context pack projection (full, medium, low) |

### Templates

Expand All @@ -90,7 +83,7 @@ tags: ["docs", "implementation", "reference", "index"]
| [TEMPLATE.md](./TEMPLATE.md) | General article template |
| [TEMPLATE_README.md](./TEMPLATE_README.md) | Folder README index template |
| [decisions/TEMPLATE.md](./decisions/TEMPLATE.md) | Decision record template |
| [PRD/PRD_TEMPLATE.md](./PRD/PRD_TEMPLATE.md) | PRD template |
| [templates/PRD_TEMPLATE.md](./templates/PRD_TEMPLATE.md) | PRD template |

### Subfolders

Expand All @@ -104,14 +97,13 @@ tags: ["docs", "implementation", "reference", "index"]
| [decisions/](./decisions/) | Implementation decision records (ADRs) | 15 files |
| [examples/](./examples/) | Case studies and examples | 1 file |
| [history/](./history/) | What happened, with evidence | 2 files |
| [infra/](./infra/) | Infrastructure documentation | 3 files |
| [klappy-dev/](./klappy-dev/) | Project-specific documentation | 3 files |
| [migrations/](./migrations/) | How we change the system | 2 files |
| [oddkit/](./oddkit/) | Oddkit subsystem documentation | 7 files |
| [orchestrator/](./orchestrator/) | Orchestrator reference guides | 5 files |
| [plans/](./plans/) | Forward-looking design & planning | 1 file |
| [promotions/](./promotions/) | Canon promotion process | 3 files |
| [PRD/](./PRD/) | Lane PRDs and template | 3 files |
| [templates/](./templates/) | Document templates (PRD, etc.) | 1 file |
| [archive/](./archive/) | Archived docs from prior structure | — |

---

Expand Down
10 changes: 5 additions & 5 deletions docs/TEMPLATE_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,18 +89,18 @@ tags: ["canon", "index"]
---
```

### Product lanes (`/products/<lane>/`)
### Project documentation

```yaml
---
uri: klappy://products/website
title: "Website Lane"
uri: klappy://docs/templates/prd-template
title: "PRD Template"
audience: docs
exposure: nav
tier: 2
voice: neutral
stability: evolving
tags: ["products", "website", "lane", "index"]
stability: stable
tags: ["docs", "templates", "prd"]
---
```

Expand Down
Loading