@erclx/aitk 0.56.0 → 0.57.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-groundwork/SKILL.md

@@ -7,7 +7,7 @@ description: Opens and runs a numbered groundwork folder under `.claude/groundwo
 
 Groundwork gathers and weighs. A plan commits. A groundwork folder costs nothing to throw away, which is what makes it the right container for a question nobody has answered yet.
 
-Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the reserved numbers, what each required file carries, the conventions, and the anti-patterns.
+Read `.claude/standards/groundwork.md` from the project root before writing any file in the folder, or `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` when the project does not have it. It holds the reserved numbers, the frontmatter and dating rules, what each required file carries, the conventions, and the anti-patterns. Do not work them from memory.
 
 ## Guards
 
@@ -65,19 +65,9 @@ Then read only what a live question needs. Do not read entire directories specul
 
 Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
 
-## Open question format
+## Open questions in chat
 
-Every open question carries a lean, wherever it appears: inside a topic file, in `00-scope.md`, and in the chat output. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
-
-```markdown
-1. <question>
-   - Leaning: <where the evidence currently points>
-   - Overturned by: <the finding that would change it>
-```
-
-- `Leaning:` is weaker than a plan's `- Suggested:`. It records the current read on a question still open by definition, not a decision to accept by default at execution time.
-- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
-- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+The standard sets the open question format and requires it inside a topic file and in `00-scope.md`. Carry the same shape into the chat output, which sits outside the folder the standard governs. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
 
 ## Open mode
 
@@ -85,7 +75,7 @@ Every open question carries a lean, wherever it appears: inside a topic file, in
 2. Write `README.md` first. Writing it first forces the question of what the track is for.
 3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
 4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
-5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the format above.
+5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the standard's format.
 6. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
 
 ## Resume mode

package/claude/skills/claude-intake/SKILL.md

@@ -7,7 +7,7 @@ description: Files a raw brain dump into a numbered intake folder under `.claude
 
 Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
 
-Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter, and the item template.
+Read `.claude/standards/intake.md` from the project root before writing any file in the folder, or `${CLAUDE_SKILL_DIR}/../../standards/intake.md` when the project does not have it. It holds the numbering, the file map, the frontmatter and dating rules, the item format, and the answer contract. Do not work them from memory.
 
 ## Routing
 
@@ -34,7 +34,7 @@ Using the wrong one fails in two shapes. Intake on a question that needs measuri
 - Reading is unrestricted inside the project. Measuring is the work.
 - Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
 
-Nothing outside this body carries the floor, and no path-scoped rule can. The item format and the answer contract are heading for a standard covering this folder and a groundwork track together, which is queued rather than written.
+Nothing outside this body carries the write-scope floor, and no path-scoped rule can. A misrouted write lands on a path the folder's glob never matches, so the rule that ships beside the intake standard carries the item format and the answer contract instead, for a session editing the folder with this skill unloaded.
 
 ## Step 1: detect open or resume
 
@@ -71,7 +71,9 @@ Two heading levels is the right depth. A third means the cluster should have bee
 
 ## Step 5: disposition each item
 
-Write every item in the format below, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot.
+Write every item in the standard's item format, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot, and never fill that slot or read an empty one as agreement.
+
+Where an item's call is the operator's, pair it with a suggestion rather than a bare question. The toolkit's `decision-help` snippet writes the same shape for chat use, and the standard's item format is the whole spec.
 
 ## Step 6: write the index
 
@@ -81,40 +83,6 @@ Each open question in the index is a labeled markdown link to its owning item's
 
 Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
 
-## Item format
-
-```markdown
-### N. Short title stating the defect
-
-- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
-- **Fix:** the one change proposed
-- **Worth it:** yes, later, or no, with the reason
-- **Open:** only where the call is the operator's
-- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
-- **Overlaps:** the live board task that already owns this item
-- **You:**
-```
-
-- `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
-- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default. The toolkit's `decision-help` snippet writes the same four-line shape for chat use, and the four lines above are the whole spec.
-- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
-
-## The answer contract
-
-`You:` belongs to the operator and ships empty on every item.
-
-Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
-
-That inverts the plan file's contract, where a blank `- Answer:` means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in chat. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
-
-Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
-
-## Numbering
-
-Numbers are read order and nothing else. Reserve `00` for the index and carry the domain in every other filename, so `07-tooling.md` says what it holds before anyone opens it.
-
-Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. `claude-groundwork` reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
-
 ## Output
 
 Emit the full relative path from the project root for every file written, and name the heading and the act beside it. A path alone cannot distinguish three new items from one reworded sentence in a file that holds a dozen items and lives for weeks, so a bare path sends the reader to diff it against memory. This overrides the paths-only reporting the project states generally, which stays right wherever the reader is about to see a diff.

package/governance/rules/claude/556-groundwork.md

@@ -0,0 +1,16 @@
+---
+description: Route .claude/groundwork/ edits to the groundwork standard for numbering, frontmatter, and required file contents
+paths:
+  - '.claude/groundwork/**'
+---
+
+# Groundwork standards
+
+## Measuring and closing
+
+- Never carry a figure from an earlier session without re-measuring it. Mark an inference as an inference.
+- Never close a track while an open question quietly fails an outcome. Resolve it, or record it as knowingly accepted.
+
+## Authority
+
+- Follow `.claude/standards/groundwork.md` for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source.

package/governance/rules/claude/557-intake.md

@@ -0,0 +1,16 @@
+---
+description: Route .claude/intake/ edits to the intake standard for the item format, the answer contract, and numbering
+paths:
+  - '.claude/intake/**'
+---
+
+# Intake standards
+
+## The answer contract
+
+- Never fill a `You:` slot and never infer a disposition from an empty one. Empty means unread, never agreement.
+- Report unread items by count on a resume pass. Do not decide one.
+
+## Authority
+
+- Follow `.claude/standards/intake.md` for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source.

package/governance/stacks/base.toml

@@ -1,2 +1,2 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "501-markdown", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]
+rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "501-markdown", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "556-groundwork", "557-intake", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -45,14 +45,34 @@ for payload in "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$T
   fi
 done
 
-export SKILLS_JSON GOV_JSON STANDARDS_JSON SNIPPETS_JSON TOOLING_JSON
+# The catalogs reach the eval as files rather than as environment entries. Linux
+# caps a single env string at 128KB, and the standards payload crossed it, which
+# fails the exec with E2BIG before any stage can report a stale count. A file
+# path is bounded whatever the catalogs grow to.
+PAYLOAD_DIR="$(mktemp -d)"
+trap 'rm -rf "$PAYLOAD_DIR"' EXIT
+
+printf '%s' "$SKILLS_JSON" >"$PAYLOAD_DIR/skills.json"
+printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
+printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
+printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
+printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
+
+export PAYLOAD_DIR
 export TEMPLATE OUTPUT LISTED PROJECT_ROOT
 
 bun --eval '
-const {
-  SKILLS_JSON, GOV_JSON, STANDARDS_JSON, SNIPPETS_JSON, TOOLING_JSON,
-  TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT,
-} = process.env
+const { readFileSync } = require("node:fs")
+
+const { PAYLOAD_DIR, TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT } = process.env
+
+const payload = (name) => readFileSync(PAYLOAD_DIR + "/" + name + ".json", "utf8")
+
+const SKILLS_JSON = payload("skills")
+const GOV_JSON = payload("gov")
+const STANDARDS_JSON = payload("standards")
+const SNIPPETS_JSON = payload("snippets")
+const TOOLING_JSON = payload("tooling")
 
 const listed = Number(LISTED)
 const skills = JSON.parse(SKILLS_JSON).skills.map((entry) => entry.name)

package/standards/groundwork.md

@@ -0,0 +1,199 @@
+---
+title: Groundwork reference
+description: Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+---
+
+# Groundwork reference
+
+Applies to a groundwork track at `.claude/groundwork/<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
+
+The folder is gitignored and unbacked. No check reaches its contents and no history recovers a deleted one, so every rule here holds only while a session reads it, and the handoff file has to be self-contained.
+
+## Scope
+
+Governs a groundwork track under `.claude/groundwork/<slug>/`: folder layout, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
+
+Does not govern:
+
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- When a project opens a track at all, and the procedure that runs one, which belong to the surface driving it
+
+## What a working track looks like
+
+A track works when a session that has never seen it re-enters from the folder alone and can answer each of these:
+
+- Which single question is being measured, and why is it running now?
+- What is the current state, measured during this pass rather than carried in from an earlier one?
+- Which questions are still open, where does the evidence point, and what would overturn that?
+- What was decided, and what was considered and dropped?
+
+A track failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter and dating
+
+Every file carries `title` and `description`. `README.md` carries one field the others do not.
+
+- `title` (required): the track subject in sentence case
+- `description` (required): one line naming what the track measures
+- `date` (required, `README.md` only): the day the folder opened, as `YYYY-MM-DD`
+
+Carry the opening date as a frontmatter field rather than a sentence in the body. A date written into prose is readable by a person and by nothing that walks the folder, and the two spellings drift once both are permitted. State it once and remove the body sentence rather than leaving the pair in place.
+
+Date the folder once rather than every file. A per-file date leaves every other file stale the first time one is edited, while the opening date never rots. The checkable half is the commit each measurement was taken against, which the file holding that measurement names.
+
+## Reserved numbers
+
+Five slots carry a fixed meaning. The rest are free, which is what lets the middle of a folder follow its subject.
+
+| Number       | Holds                                           | Required                    |
+| ------------ | ----------------------------------------------- | --------------------------- |
+| `00`         | Scope: constraints, risks, question list        | Large tracks only           |
+| `01`         | Current state, measured                         | Always                      |
+| `02` to `05` | Topic files, whatever the subject demands       | As needed                   |
+| `06`         | Decision                                        | To close                    |
+| `07`         | Handoff, self-contained                         | To close                    |
+| `08`         | Spikes: method, result, and cost per experiment | Tracks that run experiments |
+
+A folder missing `06` and `07` is live. That is the only status marker, and no separate tracking is needed.
+
+`08` sits after the closing files because it is an appendix. It holds evidence rather than a topic, so folding it into the `02` to `05` range buries it, and a track closes with or without one.
+
+## README.md
+
+Orients. Holds no findings.
+
+- A one-line definition of the investigation
+- A `## Why` section stating why the track is running now
+- A file-map table of filename and what it holds, kept current as files are added or retired
+- A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
+- A `## Prior art` section
+- A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
+- The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
+
+The file map is how a returning reader re-enters. After the decision, it is the highest-value thing in the folder.
+
+Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. A sentence asserting that a vendor documents something reads the same whether it came from a fetched page or from recall, and a later reader can neither check it nor tell the two apart.
+
+A source found and not read is listed as a lead and is never cited. That half is what keeps the rule from producing citation theater, because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later pass re-searching for what this one already surfaced.
+
+Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
+
+## 01-current-state.md
+
+Facts before opinion. Verified measurement only, taken during this pass.
+
+- Never carry a figure from a previous session without re-measuring. Stale ratios survive a sunset that invalidates them, and every number built on one is quietly wrong.
+- Mark an inference as an inference where one is unavoidable.
+- Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
+
+## 00-scope.md
+
+Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it and carries its questions inside the topic files.
+
+## 06-decision.md
+
+Closes the folder. Everything above it is input.
+
+- The problem stated once
+- The goal
+- The items to do
+- What was considered and dropped
+
+The dropped list pays off later. It is what stops a future session re-proposing something already rejected.
+
+## 07-next-session.md
+
+Written to survive a compaction that loses the conversation. It repeats facts held elsewhere in the folder rather than pointing at them. That duplication is correct here and wrong everywhere else.
+
+## 08-spikes.md
+
+Evidence by experiment, sitting beside the evidence by measurement that `01-current-state.md` holds. Optional, and most tracks never open it, because measuring what is already there settles most questions.
+
+Each spike carries four things:
+
+- The open question it answers, named by file and number. A spike attached to no question is the same runaway the current-state file is capped against.
+- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, the exact command, and how many repetitions were run. An arm pointed at a fixture inside the project measured the project, so the fixture location is part of whether the result stands.
+- The result, and which question it closes. A spike that settles nothing is still recorded, so a later pass does not pay to learn the same thing twice.
+- The measured cost, and the caveats bounding what the result proves.
+
+Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
+
+Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
+
+One method error is worth naming, because it is made rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction naming a path puts that path in the transcript whether or not anything opened it. The check is the tool call.
+
+## Open questions
+
+Every open question carries a lean, wherever it appears. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
+
+```markdown
+1. <question>
+   - Leaning: <where the evidence currently points>
+   - Overturned by: <the finding that would change it>
+```
+
+- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
+- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+- Mark each question open or answered, and repeat the open ones at the end of the file they belong to. That gives the decision file its agenda for free.
+
+A lean is weaker than the suggestion a plan file carries. It records the current read on a question still open by definition, not a decision to accept by default at execution time.
+
+## Conventions
+
+- State a number with what it settles. The strongest sections are the ones where a measurement answers a named question and says so.
+- Send a finding that would change an existing standard or rule to a backlog. Only a demonstrated failure changes one.
+- Let the file count follow the number of genuinely separable questions, not the importance of the topic. A large topic with one question is a small folder.
+
+## Anti-patterns
+
+- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
+- **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
+- **Recording a constraint discovered while defending a decision.** Check a constraint against the alternative design before writing it down, or a fact about the current shape gets written up as inherent to the problem.
+- **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.
+- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+
+## Template
+
+```markdown
+---
+title: <Track subject>
+description: <one line naming what the track measures>
+date: <YYYY-MM-DD>
+---
+
+# <Track subject>
+
+Groundwork phase. Nothing here is a feature plan.
+
+<One line defining the investigation.>
+
+## Why
+
+<Why the track is running now.>
+
+## Files
+
+| File                  | Holds           |
+| --------------------- | --------------- |
+| `01-current-state.md` | <what it holds> |
+
+## Method
+
+<Internal sources used, external sources used, and what is not yet done.>
+
+### Leads
+
+- <external source found but not opened>
+
+## Prior art
+
+<Earlier plans, folders, or decisions this track supersedes or builds on.>
+
+## Source citation
+
+Every claim about a source outside the project carries a link. A source found
+and not read is listed as a lead and is never cited.
+```

package/standards/index.md

@@ -11,6 +11,8 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
+- [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+- [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
 - [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan run against finished text leaving through a channel no automated check covers

package/{claude/skills/claude-intake/references/folder-format.md → standards/intake.md}

@@ -1,14 +1,37 @@
 ---
-title: Intake folder reference
-description: Reserved index number, file map, frontmatter and dating, the item template, retrieval, and anti-patterns
+title: Intake reference
+description: Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 ---
 
-# Intake folder reference
+# Intake reference
 
-Applies to an intake folder at `.claude/intake/<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem and a verdict.
+Applies to an intake folder at `.claude/intake/<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem, one proposed fix, and a verdict.
 
 The folder is gitignored and unbacked. No check reaches its contents, so the shape below survives only by being read.
 
+## Scope
+
+Governs an intake folder under `.claude/intake/<slug>/`: folder layout, the reserved index number, frontmatter and dating, the item format, the answer contract, and retrieval.
+
+Does not govern:
+
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- The task file promoting an item onto the board, and the origin line pointing back at the folder: `tasks.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- Which findings belong in a dump at all, and the procedure that files one, which belong to the surface driving it
+
+## What a working intake looks like
+
+An intake works when a reader returning weeks later can act on it from the folder alone:
+
+- Which items are ready to promote, and what does shipping each one cost?
+- What measurement stands behind each problem line, and against which commit was it taken?
+- Which items has the operator answered, and which has nobody reached?
+- Which live board task does an item already overlap?
+
+An intake failing these is non-conforming even when it satisfies every shape rule below.
+
 ## Files
 
 | File                 | Holds                                                        | Required |
@@ -19,13 +42,19 @@ The folder is gitignored and unbacked. No check reaches its contents, so the sha
 
 `00` is the only reserved number. Everything else is read order, and the domain rides in the filename so a reader knows what `07-tooling.md` holds without opening it.
 
-Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. Groundwork reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
+Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. A folder whose shape is fixed can reserve its numbers, and that half of the convention does not transfer.
 
 Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
 
 ## Frontmatter and dating
 
-Every file carries `title` and `description` per the project's prose standard. `00-overview.md` carries one field the others do not, a `date` holding the day the folder opened.
+Every file carries `title` and `description`. `00-overview.md` carries one field the others do not.
+
+- `title` (required): the dump subject in sentence case
+- `description` (required): one line naming what the dump covers
+- `date` (required, `00-overview.md` only): the day the folder opened, as `YYYY-MM-DD`
+
+Carry the opening date as a frontmatter field rather than a sentence in the body. A date written into prose is readable by a person and by nothing that walks the folder, and the two spellings drift once both are permitted.
 
 Date the folder once rather than every file. Twelve dated files leave eleven stale the first time one cluster is edited, and the opening date never rots. The checkable half is the commit, which the overview body names as what the claims were measured against.
 
@@ -44,7 +73,7 @@ The index carries no answer slot. One question in two answerable places has no r
 
 Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
 
-## Item template
+## Item format
 
 ```markdown
 ### N. Short title stating the defect
@@ -58,11 +87,23 @@ Where an item touches a task already on the board, say so in the index rather th
 - **You:**
 ```
 
-`Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. `Open:` appears only where the call is the operator's, `Suggested:` is required whenever it does, and `Overlaps:` is optional and never replaces the verdict.
+- `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
+- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default.
+- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
 
 Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file.
 
-An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything that fits the four bullets belongs in them.
+An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything fitting the four bullets belongs in them.
+
+## The answer contract
+
+`You:` belongs to the operator and ships empty on every item.
+
+Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
+
+That inverts the plan file's contract, where a blank answer slot means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in conversation. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
+
+Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
 
 ## Retrieval
 
@@ -95,3 +136,45 @@ Both walk `###` headings, which is the mechanical reason an answer typed anywher
 - **The overlap that ate the verdict.** Replacing `Worth it:` with `Overlaps:` drops the call on the items most likely to change what a live task should do.
 - **A question in two places.** An open question answerable in the index and on the item resolves to whichever a reader happens to open.
 - **The dump filed as one concern.** Forty findings under one heading is a folder nobody can promote from, and the split by domain is what makes each item liftable on its own.
+- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+
+## Template
+
+```markdown
+---
+title: <Dump subject>
+description: <one line naming what the dump covers>
+date: <YYYY-MM-DD>
+---
+
+# <Dump subject>
+
+<One line on what the dump covers and the commit it was measured against.>
+
+## Item format
+
+<the item format block, copied so a returning session picks the shape up here>
+
+## The answer contract
+
+`You:` ships empty and empty means unread. Accepting a verdict is typed as
+`- **You:** ok`. Nothing here is decided by silence.
+
+## Clusters
+
+| File             | Holds           | Items | Open |
+| ---------------- | --------------- | ----- | ---- |
+| `NN-<domain>.md` | <what it holds> | <n>   | <n>  |
+
+## Verdicts
+
+<counts across the folder>
+
+## Ready
+
+- <item, grouped by what shipping it costs>
+
+## Open questions
+
+1. [<question>](NN-<domain>.md#n-short-title-stating-the-defect)
+```

package/claude/skills/claude-groundwork/references/folder-format.md

@@ -1,107 +0,0 @@
----
-title: Groundwork folder reference
-description: Reserved file numbers, required file contents, and anti-patterns for a .claude/groundwork/ folder
----
-
-# Groundwork folder reference
-
-Applies to a groundwork folder at `.claude/groundwork/<slug>/`. The numbering is the table of contents: a reader opens the folder and knows where to start and what follows, with no index maintained inside each file. Protect that first, because the instinct when adding a file mid-track is to name it for its topic instead.
-
-The folder is gitignored and unbacked. It dies with the machine, which is why the handoff file has to be self-contained.
-
-## Reserved numbers
-
-Five slots carry a fixed meaning. The rest are free, which is what lets the middle of a folder follow its subject.
-
-| Number       | Holds                                           | Required                    |
-| ------------ | ----------------------------------------------- | --------------------------- |
-| `00`         | Scope: constraints, risks, question list        | Large tracks only           |
-| `01`         | Current state, measured                         | Always                      |
-| `02` to `05` | Topic files, whatever the subject demands       | As needed                   |
-| `06`         | Decision                                        | To close                    |
-| `07`         | Handoff, self-contained                         | To close                    |
-| `08`         | Spikes: method, result, and cost per experiment | Tracks that run experiments |
-
-A folder missing `06` and `07` is live. That is the only status marker, and no separate tracking is needed.
-
-`08` sits after the closing files because it is an appendix. It holds evidence rather than a topic, so folding it into the `02` to `05` range buries it, and a track closes with or without one.
-
-## README.md
-
-Orients. Holds no findings.
-
-- A one-line definition of the investigation
-- The date opened
-- A `## Why` section stating why the track is running now
-- A file-map table of filename and what it holds, kept current as files are added or retired
-- A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
-- A `## Prior art` section
-- A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
-- The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
-
-The file map is how a returning reader re-enters. After the decision, it is the highest-value thing in the folder.
-
-Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. A sentence asserting that the vendor documents something reads the same whether it came from a fetched page or from recall, and a later reader can neither check it nor tell the two apart.
-
-A source found and not read is listed as a lead and is never cited. That half is what keeps the rule from producing citation theater, because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later pass re-searching for what this one already surfaced.
-
-Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
-
-## 01-current-state.md
-
-Facts before opinion. Verified measurement only, taken during this pass.
-
-- Never carry a figure from a previous session without re-measuring. Stale ratios survive a sunset that invalidates them, and every number built on top of one is quietly wrong.
-- Mark an inference as an inference where one is unavoidable.
-- Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
-
-## 00-scope.md
-
-Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it and carries its questions inside the topic files.
-
-## 06-decision.md
-
-Closes the folder. Everything above it is input.
-
-- The problem stated once
-- The goal
-- The items to do
-- What was considered and dropped
-
-The dropped list pays off later. It is what stops a future session re-proposing something already rejected.
-
-## 07-next-session.md
-
-Written to survive a compaction that loses the conversation. It repeats facts held elsewhere in the folder rather than pointing at them. That duplication is correct here and wrong everywhere else.
-
-## 08-spikes.md
-
-Evidence by experiment, sitting beside the evidence by measurement `01-current-state.md` holds. Optional, and most tracks never open it, because measuring what is already there settles most questions.
-
-Each spike carries four things:
-
-- The open question it answers, named by file and number. A spike attached to no question is the same runaway the current-state file is capped against.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, the exact command, and how many repetitions were run. A headless arm pointed at a fixture inside the repository measured the repository, so the fixture location is part of whether the result stands.
-- The result, and which question it closes. A spike that settles nothing is still recorded, so a later pass does not pay to learn the same thing twice.
-- The measured cost, and the caveats that bound what the result proves.
-
-Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
-
-Reach for a test harness the project already carries before building one. A track that needs an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
-
-One method error is worth naming here, because it was made and corrected rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction that names a path puts that path in the transcript whether or not anything opened it. The check is the tool call.
-
-## Conventions
-
-- Questions carry an open or answered marker, and open ones repeat at the end of the file they belong to. That gives `06-decision.md` its agenda for free.
-- Every open question carries a lean and what would overturn it, in the open question format in `SKILL.md`. A measurement question records that it needs measuring instead of guessing.
-- State a number with what it settles. The strongest sections are the ones where a measurement answers a named question and says so.
-- Send findings that would change an existing standard or rule to a backlog. Only a demonstrated failure changes one.
-- Let the file count follow the number of genuinely separable questions, not the importance of the topic. A large topic with one question is a small folder.
-
-## Anti-patterns
-
-- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
-- **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
-- **Recording a constraint discovered while defending a decision.** Check a constraint against the alternative design before writing it down, or a fact about the current shape gets written up as inherent to the problem.
-- **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.