From 0314179ec2905dbba11786ed92b6b28d7dd43407 Mon Sep 17 00:00:00 2001 From: bdeshi Date: Thu, 30 Jul 2026 01:30:48 +0600 Subject: [PATCH] keep the build queue in an uncommitted .scratch/ The queue is a working plan, not a record: git log already carries what landed on each step, so committing the plan duplicates it and invites the two to disagree. .scratch/ is gitignored and skipped by the gate the way ideas/ and reference/ are, so exploratory files there need not compile. state.md keeps a conditional pointer rather than a path it cannot promise: if the scratch file is absent, the log is the plan. --- .gitignore | 1 + HARNESS.md | 4 ++-- docs/README.md | 2 ++ docs/state.md | 28 ++-------------------------- scripts/verify.sh | 4 ++-- 5 files changed, 9 insertions(+), 30 deletions(-) diff --git a/.gitignore b/.gitignore index 0194520..62b1548 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ *.test *.out .DS_Store +.scratch/ diff --git a/HARNESS.md b/HARNESS.md index ae76e28..d9af4c3 100644 --- a/HARNESS.md +++ b/HARNESS.md @@ -98,8 +98,8 @@ untriaged one, so the list drains instead of becoming a graveyard. **This repo is engine source only.** The site root — `content/`, `static/`, optional `templates/` — lives in its own repository and is passed to the binary with `-site` (ADR-0011), and validating content -is the engine's own job rather than the gate's. The gate skips `ideas/` and `reference/` as well, so -exploratory scratch code parked there never has to compile. +is the engine's own job rather than the gate's. The gate skips `ideas/`, `reference/` and the uncommitted +`.scratch/`, so exploratory code parked there never has to compile. **The architecture gate.** `verify.sh` enforces the layering in `conventions.md` from `go list` output: content imports no sibling, render imports neither web nor ext, web imports no ext, nothing diff --git a/docs/README.md b/docs/README.md index ea43fa0..eb93305 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,6 +38,7 @@ that is the finding to report. | 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` | | how the harness works — a gate, counter, budget, the loop | `HARNESS.md` + `scripts/verify.sh` + `CLAUDE.md` | | a tool version, or why agent tooling stopped working | `toolchain.md` | | templates, layout, presentation, what a theme can rely on | `theme-contract.md` (+ ADR-0019, ADR-0023) | @@ -81,6 +82,7 @@ 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 | | Arc finished | `roadmap.md` + a retro line in `state.md` | | Catalog item accepted or rejected | verdict line in `exploration.md` | | `CLAUDE.md`, `scripts/` or `.claude/` changed | `HARNESS.md`, same change. Enforced by `verify.sh`. | diff --git a/docs/state.md b/docs/state.md index 7397095..b5bd736 100644 --- a/docs/state.md +++ b/docs/state.md @@ -54,32 +54,8 @@ Every ADR in `decisions.md` is accepted; none is open or proposed. ## Build queue -The prompt sequence to a Grav-level engine. **Completed through 1.** Update this line as each lands; a -context refresh loses the conversation, not the plan. - -- [x] 0 · ADRs: pagination shape (0028), parse-failure policy (0029), rename (0030), path guard (0031) -- [x] 1 · bundle loading: `os.Root`, frontmatter, key/lang, NFC, collisions, skip-loudly -- [ ] 2 · serve a bundle at its permalink: `-site`, trailing-slash redirect, goldmark, reference theme -- [ ] 3 · language variants: `/bn/…`, fallback chain, `/en/…` redirect *(2nd routing case → resolver)* -- [ ] 4 · aliases -- [ ] 5 · section index pages, paginated *(first collection page → Query)* -- [ ] 6 · settings cascade *(re-adopt from `ideas/deferred-decisions.md`)* -- [ ] 7 · declared content types *(re-adopt)* -- [ ] 8 · template composition: per-type sets, block override, site `templates/` -- [ ] 9 · tags: global namespace, tag listings *(re-adopt)* -- [ ] 10 · sequences: series, sparse order, prev/next/archive -- [ ] 11 · typography + Bengali numerals transforms -- [ ] 12 · shortcodes *(3rd transform → Stage pipeline)* -- [ ] 13 · image derivatives *(first Effect)* -- [ ] 14 · feeds: primary, per-section, per-tag *(2nd Effect → Effect runner)* -- [ ] 15 · sitemap, robots, OpenGraph/JSON-LD -- [ ] 16 · in-process page cache with the validity record *(re-adopt)* -- [ ] 17 · `check` command -- [ ] 18 · `new` command -- [ ] 19 · `-dev`: reveal drafts and future-dated, template reload -- [ ] 20 · extras *(re-adopt)* -- [ ] 21 · polled change detection + Dockerfile -- [ ] 22 · complete the reference theme against the full contract +Working plan lives in `.scratch/build-queue.md`, which is deliberately not committed — `git log` is the +record of what actually landed. If that file is absent, read the log and rebuild the plan from it. ## Arc retro log diff --git a/scripts/verify.sh b/scripts/verify.sh index 015d67a..a730e46 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -171,7 +171,7 @@ mod=$(awk '/^module /{print $2; exit}' go.mod) # Engine source only. The site root is outside this repo (ADR-0011); ideas/ and reference/ may hold # exploratory scratch code, which is not the engine and is never formatted, vetted, built or budgeted. gofiles=$(find . -name '*.go' -not -path './vendor/*' -not -path './.git/*' \ - -not -path './ideas/*' -not -path './reference/*' 2>/dev/null) + -not -path './ideas/*' -not -path './reference/*' -not -path './.scratch/*' 2>/dev/null) if [ -z "$gofiles" ]; then head_ "go" note "go.mod present but no .go files yet — nothing to verify." @@ -179,7 +179,7 @@ if [ -z "$gofiles" ]; then fi head_ "correctness" -pkgs=$(go list ./... 2>/dev/null | grep -vE "^$mod/(ideas|reference)(/|$)") +pkgs=$(go list ./... 2>/dev/null | grep -vE "^$mod/(ideas|reference|\.scratch)(/|$)") if [ -z "$pkgs" ]; then head_ "go"; note "no engine packages yet — nothing to verify." result_and_exit