diff --git a/brainstorm/SKILL.md b/brainstorm/SKILL.md index cba045f..b0ecec0 100644 --- a/brainstorm/SKILL.md +++ b/brainstorm/SKILL.md @@ -69,6 +69,12 @@ Before asking any clarifying questions: - If the project has a design ledger configured under `paths.design_ledger`, walk to the relevant contracts for the invariants the new cycle might touch. +- When reading any file under `paths.design_models` (or the + ledger's "model" rows), note its `status` / + `validated-against` frontmatter if present: `status: + aspirational` means its code is a target, not verified fact. + Track which content you may lift from such a source — it is + flagged for lift-time validation (Step 4). - `git log --oneline -20` for the chronological scan. - Identify scope: is this one cycle, or does it need to be decomposed into sub-cycles first? If multi-subsystem, @@ -146,6 +152,16 @@ code to show" is the rationalisation to refuse: an infra cycle that cannot be tied to concrete code is speculative infra. +**Code lifted from an aspirational source is a hypothesis, not +evidence.** If the concrete code here is lifted from a +`design_models` file (or any source marked `status: aspirational`, +per Step 1), it carries no validation by default — the marker +exists precisely because no one has run it through the live tool. +Its `design/` location is not ratification. Treat it as the spec's +most suspect bytes: it must clear the Step-7 parse-every-block +gate before PASS. The marker tells you *which* blocks to distrust +first. + ### Step 5 — Present design in sections Scale each section to its complexity (a few sentences if @@ -375,6 +391,7 @@ Hand off carries: | "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the previous attestation no longer covers them. Re-dispatch is cheap; the alternative is a commit with an attestation that doesn't match the file. | | "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The feature-acceptance criterion is unjudgeable without the worked code; "a user reaches for it" with no shown code is the exact hand-wave the criterion exists to kill. | | "The block obviously parses — I wrote it carefully" | Careful authoring is not a parse. A spec's code blocks are hypotheses until the live tool accepts them; treating them as truth is the compound-hallucination failure the parse-every-block gate exists to kill. If a parser is configured for the block's fence label, run it and paste the trace. | +| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact; its `design/` location is not ratification. Code lifted from a `status: aspirational` source must clear the Step-7 parse gate like any other block, and is in fact the most suspect bytes in the spec. | ## Red Flags — STOP @@ -389,6 +406,9 @@ Hand off carries: - A spec carrying a code block whose fence label has a configured `spec_validation` parser, committed without a parse-trace in the brainstorm chat +- Lifting code verbatim from a `status: aspirational` source (a + `models` / RFC / proposal file) into the spec without flagging + it for the Step-7 parse gate - Editing the spec file after a Step 7.5 PASS without re-dispatching - Jumping straight from spec to `implement` (must go via diff --git a/docs/profile-schema.md b/docs/profile-schema.md index 1797fbe..974d4a9 100644 --- a/docs/profile-schema.md +++ b/docs/profile-schema.md @@ -23,6 +23,37 @@ Omitted optional keys signal that the feature is unused in this project; skills that depend on them either short-circuit or skip the corresponding step. +### Aspirational-source marker (recommendation) + +Files under `design_models` (or an equivalent `RFCs` / +`proposals` directory) commonly carry aspirational code — +constructs written before the surface that would parse them +exists. To let a later brainstorm tell aspirational content from +validated contract, projects are encouraged (not required) to +give each such file a frontmatter marker: + +```yaml +--- +status: aspirational +validated-against: +--- +``` + +`status: aspirational` says "the code here is a target, not a +verified fact"; `validated-against` records the last commit at +which someone actually ran the code through the live tool (or +`"no validation"`). A design ledger (`design_ledger`) is likewise +encouraged to distinguish "model" rows from "contract" rows so a +reading agent can mechanically tell which carry verified +behaviour. + +When a file lacks the marker the signal is simply absent — the +brainstorm degrades to treating its content as unmarked, never +hard-failing. The marker is consumed by the brainstorm skill (see +its Step 1 and Step 4): content lifted from an aspirational source +is flagged and must clear the Step-7 parse-every-block gate before +it ships in a spec. + ## `naming` | Key | Type | Default | Description |