tegwick
71a8c1424b
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9
97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
# Pattern schema 0.1
|
||
|
||
Status: working contract · 2026-09-24 · FEP-WP-0002-T01
|
||
|
||
[Pattern template](../templates/Pattern.md) is the authoring skeleton;
|
||
[vocabulary.yaml](vocabulary.yaml) owns serialized enum values and force IDs.
|
||
The template is intentionally incomplete and is not a pattern record.
|
||
|
||
## Identity and lifecycle
|
||
|
||
- `schema_version: '0.1'` identifies this metadata contract.
|
||
- `id`: `FEP-` followed by four digits, allocated once when creating a pattern file.
|
||
IDs do not encode families or scale; moving or renaming a pattern retains its ID.
|
||
Never reuse a retired ID. Check all pattern frontmatter before allocating the next
|
||
unused number. Candidate P01 identities remain scoped to their source workspace.
|
||
- `name`: human-readable name; `family`: nonempty list of family keys; `scales`:
|
||
nonempty list of distinct L0–L7 keys. Do not serialize `cross-scale` or `L3/L6`.
|
||
- `status`: draft, reviewed or deprecated. Reviewed means an editorial review is
|
||
recorded in Evidence; it does not establish empirical maturity. Deprecation must
|
||
explain the replacement or reason, and existing references remain resolvable.
|
||
- `evidence.maturity`: hypothesis (untested generalization), emerging (traceable
|
||
support and contrasting cases with explicit gaps), established (independent known
|
||
uses and documented limits), canonical (established evidence plus explicit corpus
|
||
review for reference use). None means universally desirable. Promotion requires
|
||
a linked review, never a model score or a count of citations alone.
|
||
|
||
## Context, prerequisites and forces
|
||
|
||
`context` and `prerequisites` are lists of explanatory strings. Prerequisites are
|
||
conditions such as identifiable commands or a durability requirement. They are
|
||
not unresolved pattern names. Use a `requires` relation only when another pattern
|
||
is genuinely required, with its ID and a rationale.
|
||
|
||
`forces.improves` and `forces.worsens` contain vocabulary keys such as
|
||
`interaction-latency` and `implementation-complexity`. At least two distinct forces
|
||
must be present overall, with both benefits and costs explained in prose. A force
|
||
may appear on both sides only when the Forces section explains the conditions.
|
||
Do not infer direction just from a label (lower latency is generally favorable).
|
||
|
||
## Relations
|
||
|
||
`relations` is a list of objects:
|
||
|
||
```yaml
|
||
- type: enables
|
||
target:
|
||
kind: pattern
|
||
ref: FEP-0002
|
||
rationale: Explain the conditional dependency or effect.
|
||
evidence: [E1]
|
||
```
|
||
|
||
The nine pattern relation types in vocabulary.yaml target a `pattern` by stable ID.
|
||
`implemented-by` targets `technology`; `observed-in` targets `system` or
|
||
`architecture`. External targets use a repository-relative Markdown path to an
|
||
existing mapping or case record. A product label or URL alone is not a graph node.
|
||
`rationale` is required. `evidence` contains local evidence-entry IDs, or is empty
|
||
when the relation is explicitly marked as a hypothesis in its rationale.
|
||
|
||
Use kebab-case relation names everywhere. Relations are recorded from this pattern
|
||
to the target. Do not infer inverse edges, transitivity or symmetric closure.
|
||
In particular, a cycle of complements is not itself an inconsistency. Requires
|
||
cycles warrant review; a generic graph cycle count is not a correctness verdict.
|
||
|
||
## Evidence and known uses
|
||
|
||
`evidence.sources` is a list with these fields:
|
||
|
||
```yaml
|
||
- id: E1
|
||
source: SRC-0001
|
||
locator: Source section, page, paragraph or repository revision.
|
||
review: research/cases/ExampleReview.md
|
||
claims: [C01]
|
||
```
|
||
|
||
Source IDs resolve in `research/catalog/SourceCatalog.md`. Each review path exists;
|
||
claim IDs resolve within that review. E1 is local to the pattern, not a global ID.
|
||
Source statements and our interpretations must be separate in the review.
|
||
An empty evidence list is allowed for a draft hypothesis, with the gap stated.
|
||
A source citation is not independent confirmation of all claims in a pattern.
|
||
|
||
`known_uses` is a list of `{name, locator, evidence}` objects: a named observed use,
|
||
a version-specific URL or source locator, and local evidence IDs supporting the
|
||
observation. A hypothetical example belongs in Implementation Notes, not Known Uses.
|
||
|
||
## Prose and admission
|
||
|
||
All sections in the template are required. Explain a recurring problem, competing
|
||
forces, reusable solution, dynamics, resulting context, consequences and failure
|
||
modes. State unknowns explicitly rather than leaving misleading empty claims.
|
||
A technique or framework feature alone does not establish a reusable pattern.
|
||
|
||
[Worked fixtures](../research/examples/schema-contract.yaml) demonstrate resolution
|
||
in a deliberately isolated synthetic corpus. Their IDs are not reserved in the
|
||
real corpus and their contents provide no research evidence. The fixture check is
|
||
an acceptance check for this contract, not the future full corpus validator.
|