feat: aspirational-source marker convention (issue #1 Fix 5)

Documents a recommended (not plugin-enforced) frontmatter marker for
files under `design_models` / RFCs / proposals:
`status: aspirational` + `validated-against: <sha|"no validation">`,
plus a recommendation that the design ledger distinguish model rows
from contract rows mechanically.

Wires the brainstorm skill to consume the signal: Step 1 notes the
marker when reading model files, Step 4 flags code lifted from an
aspirational source as the spec's most suspect bytes that must clear
the Step-7 parse gate. This is the upstream signal whose downstream
catch is the Fix-1 parse-every-block gate. Adds a Common
Rationalisation and a Red Flag. Missing marker -> signal absent,
graceful degradation, never a hard fail.

Closes the issue #1 hardening set (P0 + Fixes 1-5).

refs #1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-29 14:39:22 +02:00
parent e019d04f83
commit 56ef25cae1
2 changed files with 51 additions and 0 deletions
+31
View File
@@ -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: <commit-sha | "no validation">
---
```
`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 |