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:
@@ -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
@@ -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
@@ -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`. |
|
||||
|
||||
@@ -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
@@ -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
@@ -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.
|
||||
Reference in New Issue
Block a user