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