move the feature catalogue out of docs, and replace the queue with a plan

Two structural changes, both about what an agent may pull into context.

exploration.md catalogues engine features nobody has asked for. That is storage,
not working material, so it moves to ideas/ where nothing sweeps it and it is
opened only when named — the same rule the other parked material already
follows. Six references repointed; the ideas gates then demanded an index line
and a status, and both were supplied rather than exempted.

build-queue.md was 516 lines, nearly all of it entries 0-23 finished months of
work ago, with the plan buried at the top. It becomes .scratch/continue.md at
49: where the code is, what is planned, and the findings worth carrying that no
doc owns — chiefly that silent damage to prose is this engine's recurring
failure mode, and that three defects this arc were invisible to curl.

Docs and HARNESS point at the new names. No rule, gate or threshold changed.
This commit is contained in:
Claude Opus 5
2026-08-02 00:57:55 +06:00
committed by bdeshi
parent 25d7045133
commit 77c658bf98
7 changed files with 24 additions and 15 deletions
+2 -2
View File
@@ -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.
+5 -2
View File
@@ -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/<slug>.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.
+7 -7
View File
@@ -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`. |
+1 -1
View File
@@ -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).
+1 -1
View File
@@ -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
+6 -2
View File
@@ -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.
@@ -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.