diff --git a/.claude/commands/leaf.md b/.claude/commands/leaf.md index c9e5476..4ba857f 100644 --- a/.claude/commands/leaf.md +++ b/.claude/commands/leaf.md @@ -2,7 +2,7 @@ description: Decide whether a catalog item is a leaf worth building, or a trunk that waits --- -Evaluate `$ARGUMENTS` against the leaf/trunk test in `docs/exploration.md`. +Evaluate `$ARGUMENTS` against the leaf/trunk test in `ideas/exploration.md`. Research it only as far as needed to answer accurately — what it actually requires, not what its homepage claims. If it is a protocol or spec, state which parts are mandatory versus optional. @@ -20,5 +20,5 @@ Answer these, briefly: a legitimate answer for a cheap leaf and a disqualifying one for anything expensive. 7. **Verdict:** build now / build when gate X opens / trunk, needs an ADR / no. -Write the verdict as one row in the Verdicts table in `docs/exploration.md`. Do not implement +Write the verdict as one row in the Verdicts table in `ideas/exploration.md`. Do not implement anything in this pass. diff --git a/HARNESS.md b/HARNESS.md index 6683583..62508c3 100644 --- a/HARNESS.md +++ b/HARNESS.md @@ -8,7 +8,8 @@ constitution (always loaded). `docs/` is what the agent needs to build the engine — anything in it may be pulled into context on demand. `ideas/` and `reference/` sit outside `docs/` deliberately: storage, opened only when you name a file, swept by nothing. `.claude/` holds the feature-loop skill (`skills/feature-loop/`), the commands, and `launch.json`. -`scripts/` holds the gate. +`scripts/` holds the gate. `.scratch/continue.md` is uncommitted and holds the plan: what is done, what is +next, and the findings worth carrying that no doc owns. ## How you use it @@ -33,7 +34,9 @@ need to run there rather than pretending to have done it. Occasional maintenance, by you: - "Park this" → the agent writes `ideas/.md`, resumable cold, and indexes it. Name the file - later to pick the thread up; it reads these only when named. + later to pick the thread up; it reads these only when named. `ideas/exploration.md` is the same idea for + engine features nobody has asked for — a catalog, deliberately outside `docs/` so it adds no weight to the + working set. - `/audit` every ~5 features — finds abstractions that never earned their keep. - `/invariants` at arc boundaries, before a freeze, before the first deploy — checks the nine architecture invariants against the code, which no grep can do. diff --git a/docs/README.md b/docs/README.md index 3524c12..734c321 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,15 +11,15 @@ Read the one you need. Do not read them all. | `content-model.md` | On-disk layout, frontmatter, post types, permalinks | When the disk format changes | | `conventions.md` | Go style floor, package layout, perf and test rules | Rarely; via ADR if contested | | `extensions.md` | Extension/plugin contract: target shape + earn gates | When earned or frozen | -| `exploration.md` | Catalog of possible future *engine features*, leaf/trunk verdicts | When a verdict is reached | | `toolchain.md` | Versions and agent-tooling contracts this was built against | When you deliberately move a version | | `theme-contract.md` | What the engine promises a theme; the only theme-facing obligation | When the contract is extended — additively only | | `context-economy.md` | How the agent spends context: what to read, in what form, and the floor no saving may cross | When a technique or a gate for one changes | | `surface.md` | **Generated.** Every top-level declaration with its line — read before opening source | Never by hand; `make surface` | Sibling folders sit **outside** `docs/` because they are storage, not working material: -`../ideas/` (parked ideas, any topic) and `../reference/` (durable facts from conversation). Write -there when asked to park something; open a file only when the human names it. Nothing sweeps them. +`../ideas/` (parked ideas, any topic, and `exploration.md` — the catalog of engine features nobody has asked +for yet) and `../reference/` (durable facts from conversation). Write there when asked to park something; +open a file only when the human names it. Nothing sweeps them. ## Topic ownership — read before you assert @@ -39,8 +39,8 @@ that is the finding to report. | the untrusted boundary, comments, webmentions, form input | ADR-0003 + `extensions.md` | | language, translation, fallback | ADR-0004 + ADR-0009 | | deploy, containers, external services | ADR-0010 | -| whether a future feature is worth building | `exploration.md` + `roadmap.md` | -| what to build next | `.scratch/build-queue.md` if present, otherwise `git log` and `roadmap.md` | +| whether a future feature is worth building | `ideas/exploration.md` + `roadmap.md` | +| what to build next | `.scratch/continue.md` if present, otherwise `git log` and `roadmap.md` | | how the harness works — a gate, counter, budget, the loop | `HARNESS.md` + `scripts/verify.sh` + `CLAUDE.md` | | what one commit contains, and when one happens | `conventions.md` "Git" (shape) + `CLAUDE.md` §4 (cadence, ADR-0052) | | how to read, search, or report without wasting context | `context-economy.md` (+ ADR-0053) | @@ -86,9 +86,9 @@ Update in the Document step of the change that caused them. Not later. | New dependency approved | `scripts/allowed-deps.txt` + ADR | | Budget raised | `scripts/budgets.env` + ADR — once the first feature has shipped. While the harness is still being tuned, edit in place. | | A latent item fixed | remove from the Latent list in `state.md` | -| A queue entry completed | tick it in `.scratch/build-queue.md` and note anything learned that changes a later entry — uncommitted, so the commit message carries what landed | +| A planned item completed | tick it in `.scratch/continue.md` and note anything learned that changes a later one — uncommitted, so the commit message carries what landed | | Arc finished | `roadmap.md` + a retro line in `state.md` | -| Catalog item accepted or rejected | verdict line in `exploration.md` | +| Catalog item accepted or rejected | verdict line in `ideas/exploration.md` | | `CLAUDE.md`, `scripts/` or `.claude/` changed | `HARNESS.md`, same change. Enforced by `verify.sh`. | | A tool version deliberately moved, or a new external contract relied on | `toolchain.md` | | The theme contract extended, or embedded templates changed | `theme-contract.md`, same change. Enforced by `verify.sh`. | diff --git a/docs/architecture.md b/docs/architecture.md index 944d546..5e664e7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -113,7 +113,7 @@ is normal**: search will be an engine-built index and a browser-side query, not 7. **Every feature is a leaf** — a View, Stage, Query, Interaction adapter, Effect, or bundle-as-program, deletable without trauma. Mechanical since ADR-0069: `verify.sh` allows `internal/ext/…` to be imported from `cmd/` and nowhere else, siblings included. Anything wanting a permanent service or a core-model - change is a **trunk** and waits for a human decision (`exploration.md`). + change is a **trunk** and waits for a human decision (`ideas/exploration.md`). 8. **The engine serves correctly with every external service off.** Redis, an index, object storage — each is a shortcut around work the engine can still do itself, slowly. Anything that cannot degrade that way holds canonical state and does not belong there (ADR-0010). diff --git a/docs/extensions.md b/docs/extensions.md index 58a68a5..bad556f 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -86,7 +86,7 @@ tested with an untrusted-input case. there is real logic. 5. Failure degrades: a broken extension logs and is skipped, never takes a request down. 6. Needing a permanent external service or a primitive change makes it a **trunk** — see - `exploration.md`. + `ideas/exploration.md`. 7. One directory, no sibling imports, and a `doc.go` in this shape (ADR-0027): ```go diff --git a/ideas/README.md b/ideas/README.md index 34e76a3..59ad441 100644 --- a/ideas/README.md +++ b/ideas/README.md @@ -8,9 +8,9 @@ re-derivation** — the whole justification for writing it while the context is | It is… | Where | |---|---| -| an engine feature you might build (webmentions, gemtext, galleries) | `docs/exploration.md` catalog line, `/leaf` for a verdict | +| an engine feature you might build (webmentions, gemtext, galleries) | `ideas/exploration.md` catalog line, `/leaf` for a verdict | | that same feature, but with a discussion worth not repeating | an idea file here, linked from the catalog line | -| the harness, agent workflow, token cost, tooling, process | here — `exploration.md` is engine-only | +| the harness, agent workflow, token cost, tooling, process | here — `ideas/exploration.md` is engine-only | | a decision already made | `docs/decisions.md` | | a known code flaw deliberately unfixed | Latent list in `docs/state.md` | | a durable fact, number, or link | `reference/` | @@ -42,4 +42,8 @@ you, not the agent; `verify.sh` keeps it honest without reading it into context. - [deferred-decisions.md](deferred-decisions.md) — five pre-code ADRs demoted to intent; each returns when something implements it. **parked** - [specs-as-secondary-artifacts.md](specs-as-secondary-artifacts.md) — optional per-feature specs, derived by default, plus the named-test convention. **parked** - [engine-design-review.md](engine-design-review.md) — open design decisions for a multi-type site; items graduate to ADRs one at a time. **parked** +- [exploration.md](exploration.md) — the catalog of engine features nobody has asked for, with leaf/trunk verdicts. **catalog** - [token-conservation.md](token-conservation.md) — cut agent token cost without losing output quality. **adopted → `docs/context-economy.md`**, except the subagent question + +It lives here rather than in `docs/` because a catalogue of things nobody has asked for is storage, not +working material: keeping it out of `docs/` keeps it out of the set an agent may pull in on demand. diff --git a/docs/exploration.md b/ideas/exploration.md similarity index 98% rename from docs/exploration.md rename to ideas/exploration.md index 372d4ec..137f2ef 100644 --- a/docs/exploration.md +++ b/ideas/exploration.md @@ -1,5 +1,7 @@ # Exploration catalog +Status: catalog — the verdicts are inside, one row each + Possible futures. Nothing here is committed. Presence in this list is not permission to build. `★` = highest fit-to-effort for this project's identity and values.