system-spec-ref 0.1.0__tar.gz

system_spec_ref-0.1.0/.github/skills/alloy/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: alloy
+description: Formally verify a capability's structural invariants with Alloy and record the result as metamodel Evidence. Use when the constitution's formal verification assessment flags a component whose risk lies in data models, relations, references, permissions or configuration rather than interleaving (prefer the tla skill for concurrency and protocols).
+---
+
+# Alloy Formal Verification
+
+Rules: [constitution § Formal Verification](../../../CONSTITUTION.md#formal-verification). Format: [`spec.md`](../../../spec.md) §§ 4, 8.
+
+## Inputs
+
+- Target capability: `preconditions`, `postconditions`, `invariants`, `failure_modes`.
+- Requirement(s) to verify, with `criteria`.
+- Entities and relations owned by the component.
+
+## Steps
+
+1. **Model**: one module per capability, e.g. [`Inventory.als`](../../../examples/greenfield/Inventory.als) (metamodel example: [`metamodel.als`](../../../reference-implementation/metamodel.als)).
+   - `sig`s and fields: only entities and relations named by the contract.
+   - `fact`s: structural rules the system enforces; never encode properties under check as facts.
+   - One `pred` per operation over pre/post state (`s, s'` or Alloy 6 `var` fields); guard with `preconditions`; model `failure_modes` as explicit outcomes.
+2. **Properties**: one `assert` per contract clause, named after it.
+   - `invariants` → `assert StockNeverNegative { all s: State | s.stock >= 0 }`.
+   - `postconditions` → `assert ReservePost { all s, s': State, q: Int | reserve[s, s', q] => s'.stock = minus[s.stock, q] }`.
+   - One `run` per operation to show it is satisfiable (guards against vacuous checks).
+3. **Scope**: e.g. `check StockNeverNegative for 5 but 4 Int`; small, explicit scopes and bitwidth; record them as assumptions.
+4. **Check**: `java -jar org.alloytools.alloy.dist.jar exec Inventory.als`.
+5. **Review**: confirm the model corresponds to the contract and implementation; on counterexample, fix spec or design, never silently weaken the assertion or add a fact to hide it.
+
+## Evidence
+
+```yaml
+evidence:
+  - id: ev-reserve-alloy
+    requirement_id: req-reserve
+    requirement_version: "1.0"
+    method: model-check
+    bounds: { scope: 5 }
+    passed: true
+    provenance: alloy::Inventory.als
+```
+
+- `provenance` identifies the model; keep scopes, bitwidth, solver, Alloy version, assumptions and output with it ([`spec.md` § 8](../../../spec.md#8-verification)).
+- A bounded `check` is a `model-check` (`bounds` required, e.g. the scope), not an unbounded proof (`method: proof`).
+- Contract changes invalidate the evidence; rerun after `--impact <capability>`.
+
+## Prompt
+
+"Write an Alloy model of `<capability>` from its contract; one named `assert` per invariant/postcondition and a `run` per operation; give scopes and list assumptions."

system_spec_ref-0.1.0/.github/skills/modelable/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: modelable
+description: Derive Modelable `.mdl` from a component's metamodel data_models to generate typed artifacts and check field-level version compatibility, recording results as metamodel Evidence. Use at implementation (greenfield phase 9) and before publishing a new data model version (incl. brownfield Level 2); not for specification, where data_models are authoritative.
+---
+
+# Modelable Data Contracts
+
+Rules: [constitution § Data Contracts](../../../CONSTITUTION.md#data-contracts). Format: [`spec.md`](../../../spec.md) §§ 5, 8. Tool: [Modelable](https://github.com/ktjn/modelable).
+
+`data_models` in the metamodel YAML are the source of truth; `.mdl` is a derived implementation artifact kept with the component's code.
+
+## Inputs
+
+- Target `data_models` entries (validated with `metamodel.py`): `id`, `version`, `owner`, `fields`, `classification`, `derived_from`.
+- Requirement(s) to verify, with `criteria`.
+- Brownfield: existing schemas or DDL (`modelable import`) to compare against `data_models`.
+
+## Mapping
+
+| Metamodel | `.mdl` |
+|---|---|
+| `owner` (component ID) | `domain` with `owner: "<component>"` |
+| `id`, `version` `"N.0"` | `entity`/`event`/`value` `<Name> @ N` |
+| `fields` | Typed fields; exactly one `@key` for entities |
+| `classification` | `@classification("…")`/`@pii` on fields; model level = strictest field. `open` → `public`; `secret` → `restricted` |
+| `derived_from` | `projection … from <src> @ N` / `join <src> @ N`; fields use `<-` or `=` |
+
+## Steps
+
+1. **Derive**: one `domain` per owning component; exactly the fields of `data_models`, never more.
+   - Annotate `@pii`/`@classification` explicitly on every projection field; it is not inherited by generated artifacts.
+2. **Validate**: `modelable validate <dir> --strict`.
+3. **Lineage**: `modelable lineage <domain>.<Projection>@N --path <dir>`; sources must match `derived_from`, otherwise fix the metamodel first.
+4. **Compatibility** (new version): `modelable diff <ref>@N <ref>@N+1 --path <dir>` and `modelable validate-compat --from <old> --to <new> --target <json-schema|protobuf|openapi|…>`. Exit `1` = breaking; bump the `data_models` major version and run `metamodel.py --impact <id>`.
+5. **Generate**: `modelable compile <dir> --target <target> --out <dir>`; keep `modelable-artifact-manifest.json`.
+6. **Drift**: any change starts in `data_models`; regenerate `.mdl` and artifacts, never edit them first.
+
+## Evidence
+
+```yaml
+evidence:
+  - id: ev-order-compat
+    requirement_id: req-order-contract
+    requirement_version: "2.0"
+    method: analysis
+    passed: true
+    provenance: modelable::validate-compat --from v1 --to v2 --target json-schema
+```
+
+- `diff`/`validate-compat` → `analysis`; generated serializer tests → `test`.
+- `provenance` identifies the command and sources; keep tool version and output with it ([`spec.md` § 8](../../../spec.md#8-verification)).
+- Model changes invalidate the evidence; rerun after `--impact <data-model>`.
+
+## Notes
+
+- Requires Python 3.14: `uvx modelable`. If import fails on `selectolax`, use `uvx --with 'selectolax<1' modelable`.
+- `(additive)` versions reject removals; declare breaking versions explicitly.
+
+## Prompt
+
+"Derive `.mdl` for `<data-model>` from its `data_models` entry; one domain per owner, no invented fields, explicit `@pii`/`@classification` on every field and projection field; then compile to `<target>`."

system_spec_ref-0.1.0/.github/skills/tla/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: tla
+description: Formally verify a capability's invariants with TLA+ and TLC, and record the result as metamodel Evidence. Use when the constitution's formal verification assessment flags a component (concurrency, distributed state, financial transactions, safety-critical logic, complex state machines, protocols).
+---
+
+# TLA+ Formal Verification
+
+Rules: [constitution § Formal Verification](../../../CONSTITUTION.md#formal-verification). Format: [`spec.md`](../../../spec.md) §§ 4, 8.
+
+## Inputs
+
+- Target capability: `preconditions`, `postconditions`, `invariants`, `failure_modes`.
+- Requirement(s) to verify, with `criteria`.
+- Consistency boundary of the owning component.
+
+## Steps
+
+1. **Model**: one module per capability, e.g. [`Inventory.tla`](../../../examples/greenfield/Inventory.tla) (config: [`Inventory.cfg`](../../../examples/greenfield/Inventory.cfg)).
+   - `VARIABLES`: only state named by the contract.
+   - `Init`, one action per operation; guard actions with `preconditions`; model `failure_modes` as explicit actions or outcomes.
+   - Model concurrency and retries at the component's consistency boundary.
+2. **Properties**: one per contract clause, named after it.
+   - `invariants` → `INVARIANT` (e.g. `StockNeverNegative == stock >= 0`).
+   - `postconditions` → action properties (e.g. `[][Reserve => stock' = stock - qty]_vars`).
+   - Liveness only when a requirement demands it; state fairness explicitly.
+3. **Config** (`.cfg`): small constants, explicit bounds; record them as assumptions.
+4. **Check**: `java -cp tla2tools.jar tlc2.TLC -config Inventory.cfg Inventory.tla`.
+5. **Review**: confirm the model corresponds to the contract and implementation; on violation, fix spec or design, never silently weaken the property.
+
+## Evidence
+
+```yaml
+evidence:
+  - id: ev-reserve-tla
+    requirement_id: req-reserve
+    requirement_version: "1.0"
+    method: model-check
+    bounds: { products: 2, max_qty: 3 }
+    passed: true
+    provenance: tla+::Inventory.tla
+```
+
+- `provenance` identifies the model; keep the `.cfg`, TLC version, bounds, assumptions and output with it ([`spec.md` § 8](../../../spec.md#8-verification)).
+- A bounded TLC run is a `model-check` (`bounds` required), not an unbounded proof (`method: proof`).
+- Contract changes invalidate the evidence; rerun after `--impact <capability>`.
+
+## Prompt
+
+"Write a TLA+ model of `<capability>` from its contract; one named property per invariant/postcondition; give the `.cfg` with bounds and list assumptions."

system_spec_ref-0.1.0/.github/workflows/metamodel.yml

@@ -0,0 +1,51 @@
+name: metamodel
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      script:
+        description: Script to run
+        type: choice
+        options: [metamodel.py, pytest]
+        default: metamodel.py
+      args:
+        description: "Arguments, paths relative to reference-implementation/ (e.g. 'example.yaml --json', '--impact order', '--schema'); empty validates example.yaml / runs all tests"
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build image
+        run: docker build -t metamodel reference-implementation
+      - name: Run
+        env:
+          SCRIPT: ${{ inputs.script }}
+          ARGS: ${{ inputs.args }}
+        run: |
+          run() { docker run --rm -v "$PWD:/repo" -w /repo/reference-implementation metamodel "$@" 2>&1 | tee -a out.txt; return "${PIPESTATUS[0]}"; }
+          status=0
+          if [ -n "$SCRIPT" ]; then
+            read -ra A <<< "$ARGS"
+            [ "$SCRIPT" = pytest ] && cmd=(pytest -p no:cacheprovider) || cmd=(python metamodel.py)
+            run "${cmd[@]}" "${A[@]}" || status=$?
+          else
+            for c in "pytest -p no:cacheprovider" \
+                     "python metamodel.py example.yaml" \
+                     "python metamodel.py ../examples/greenfield/spec.yaml --stage release" \
+                     "python metamodel.py ../examples/brownfield/level0.yaml --stage inventory" \
+                     "python metamodel.py ../examples/brownfield/level1.yaml --stage architecture" \
+                     "python metamodel.py ../examples/brownfield/old.yaml --stage verification" \
+                     "python metamodel.py ../examples/brownfield/spec.yaml --stage release --compat ../examples/brownfield/old.yaml"; do
+              read -ra cmd <<< "$c"
+              run "${cmd[@]}" || status=$?
+            done
+          fi
+          { echo '```'; cat out.txt; echo '```'; } >> "$GITHUB_STEP_SUMMARY"
+          exit "$status"

system_spec_ref-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+/system_spec_ref/metamodel.py
+/system_spec_ref/toolkit/
+/dist/
+/build/
+/*.egg-info/
+/.venv/
+__pycache__/
+*.pyc
+.pytest_cache/

system_spec_ref-0.1.0/BROWNFIELD.md

@@ -0,0 +1,81 @@
+# Brownfield: Onboarding Existing Systems
+
+Incremental sequencing for existing systems. Artifact rules: [constitution](CONSTITUTION.md). Load this document together with the constitution only.
+
+Overrides the [greenfield](GREENFIELD.md) ordering: existing code is the discovery input, so architecture may be described before capabilities, and implementation precedes verification.
+
+## Adoption Levels
+
+Each level targets a `--stage` ([`spec.md` § 11](spec.md#11-metamodel-validation)); known violations are allowed below `release` as risk waivers ([`spec.md` § 7](spec.md#7-risks)). Level 0 advances directly to Level 1 (`architecture`), skipping standalone `discovery` because existing code supplies architecture and contracts together. Validate with `metamodel.py <spec> --stage <stage>`.
+
+| Level | Goal | Stage |
+|---|---|---|
+| 0 — Inventory | `system`, `external_sources`, deployable units, coarse module boundaries (`status: draft`); identity and syntax only | `inventory` |
+| 1 — Dependency & data mapping | Observed `provides`/`requires`, data ownership, classification, lineage (`status: specified`); layer/cycle/ownership/budget violations recorded as waivers | `architecture` |
+| 2 — Behavioral pinning | As-is contracts and characterization tests (`Evidence`); missing verification categories covered by waivers; external contracts frozen before refactoring | `verification` |
+| 3 — Full conformance | All waivers remediated; layer and context budget rules enforced without exception; all 10 verification categories satisfied (`status: verified`) | `release` |
+
+For each adoption level, use the [shared decision record](CONSTITUTION.md#gate-decision-record): review observed artifacts against the level's criteria, record discrepancies and decide whether to pass, defer via an allowed waiver or rework.
+
+| Level | Bring to review | Decision required before proceeding |
+|---|---|---|
+| 0 — Inventory | Entrypoints, jobs, external sources, deployable units and candidate component boundaries | All active runtime units and external dependencies are registered; unknown boundaries are flagged for discovery |
+| 1 — Dependency & data mapping | Observed capability wiring, data schemas/owners/lineage, and discovered architecture violations with proposed waivers | Observed dependencies and data ownership match the running code; every violation is either remediated or deferred under a scoped, non-expired waiver |
+| 2 — Behavioral pinning | As-is contracts, characterization test results for external/cross-component behavior, compatibility baseline and remaining coverage waivers | External and cross-component behavior is pinned by passing characterization evidence; unverified categories have bounded waivers expiring by release |
+| 3 — Full conformance | Remediated architecture, compatibility results (`--compat`), requirement-linked evidence across all ten categories and risk dispositions | All waivers are closed, contracts and invariants hold without exception, and release evidence is current and reviewed |
+
+If a level review fails (for example, an unrecorded dependency, a characterization test that contradicts the drafted contract, or an expired waiver), keep the level open: correct the specification to match observed behavior or complete the remediation before advancing. Do not hide discrepancies by inventing idealized contracts during discovery.
+
+Worked progression from Level 0 to Level 3: [`examples/brownfield/`](examples/brownfield/README.md).
+
+Real onboarding feedback: [Modelable](archive/feedback/modelable-onboarding.md) records bounded adoption, existing authority/tool mapping, evidence revision binding and unresolved model gaps; it is not a full-conformance example. [Observable](archive/feedback/observable-onboarding.md) records complete brownfield onboarding across all 6 milestones to Level 3 release conformance, covering multi-schema database isolation, schema compatibility matrices, and automated evidence provenance.
+
+## Reverse Discovery
+
+Start with the [intake and gate template](templates/BROWNFIELD-INTAKE.md): record the repository root, exact source revision, adoption scope, existing authorities, product/validator tool map, validator/schema pin and native gates. Use separate whole-product and slice decisions; a slice pass does not advance excluded components. Record external/deferred/unknown boundaries explicitly; an unresolved required provider keeps architecture open. Imported schemas and capability catalogs are discovery inputs, not acceptance evidence.
+
+For local multi-step operations, record transitions, actual Python/Rust/etc. interfaces, confirmation/freshness checks, durable writes and recovery. Distinguish failed-before-commit from committed-with-cleanup-error. Keep transaction ownership intact when choosing context budgets. The template supplies the protocol review record without inventing a new transport or claiming executable state-machine verification.
+
+1. **Boundaries & entrypoints**: APIs, jobs, events, external sources → `system`, capability stubs, `external_sources`.
+2. **Data & state**: schemas, migrations, ORM/DTO models (use [`modelable`](.github/skills/modelable/SKILL.md) `import` where helpful) → `data_models`, owners, classification, lineage.
+3. **Components & dependencies**: cluster modules by transaction/consistency boundaries → `components`, layers, wiring.
+4. **Invariants & failures**: domain guards, error handlers, existing tests → capability contracts, `Requirement.criteria`, initial `Evidence` (use [`tla`](.github/skills/tla/SKILL.md) / [`alloy`](.github/skills/alloy/SKILL.md) for concurrency or relational invariants).
+5. **Gaps & risks**: missing verification categories, unverified mitigations, architecture violations → `risks` and `requirements` backlog.
+
+Rules:
+
+- Record observed behavior, not intended behavior; never invent contracts or fields.
+- Separate **as-is discrepancies** (bugs, coupling, undocumented side effects observed in code) from **target changes** (remediation or modernization requirements).
+- Validate with `metamodel.py` after each step and review the underlying code and test evidence before recording a level decision.
+- Unknown/provisional classification uses `classification: unknown` plus an active `classification_review` requirement and conservative handling policy. Resolve it before architecture; do not allow an implicit public classification.
+- Bind implementation evidence to contract versions and source revisions with `subject_bindings`/`subject_version`; preserve file hashes, execution conditions and explicit `skipped` checks. Run optional `--check-artifacts --root <repository>` for local source/schema/evidence integrity, then retain native semantic and acceptance gates.
+- Evidence paths are relative to that repository root, even when the specification lives in a nested directory. Use one provenance file with an optional `::selector`; declare additional logs and environment records separately in `artifacts`. Preserve the original schema, capture and decisions when migrating validator versions.
+- Attribute skips to the requirements they leave unverified. Separate passing records may cover genuinely independent, executed checks; a suite's passing count does not establish a skipped criterion. Check release diagnostics for binding errors without treating their absence as release acceptance.
+- When components share relational storage or streaming buses, enforce dedicated schema namespaces, eliminate cross-schema foreign keys, and back idempotency guarantees with formal models (`TelemetryDelivery.tla`) and concrete deduplication mechanisms.
+- Require transitional boundary allowlists to monotonically ratchet downward to zero before Level 3 acceptance.
+
+## Waivers
+
+- Known violations (`layer-violation`, `dependency-cycle`, `shared-data-ownership`, `context-budget`, `verification-category`) are linked to a `Risk` (`waives`) with `treatment: mitigation` or `acceptance`.
+- Each waiver requires a remediation requirement in `mitigated_by` and an `expires` bound (ISO date `YYYY-MM-DD` or target stage).
+- Expired waivers fail validation at every stage; no waivers are allowed at `--stage release` (Level 3).
+
+## Characterization, Migration and Acceptance Loop
+
+1. **Pin baseline (Levels 1–2)**: capture observed contracts and run characterization tests before changing internal structure. Record any deferred violations or coverage gaps as scoped waivers with remediation requirements.
+2. **Scope one migration step**: run `--impact <id>` against the pinned baseline to identify affected components, data models, requirements and evidence. Prepare a bounded [implementation handoff](CONSTITUTION.md#implementation-handoff) (`--context <component-id>`) containing the pinned contract, target remediation requirement, allowed boundary changes and characterization suite.
+3. **Refactor or extract**: implement the strangler or boundary change within the handoff scope. If hidden coupling or an undocumented failure mode surfaces, stop and reopen the Level 1 or Level 2 review to update the observed baseline first.
+4. **Verify compatibility and remediation**: check `--compat <pinned-baseline>` for capability and data contracts, rerun invalidated characterization and remediation tests, and update evidence revisions. If a waiver expires or a check fails, recover by completing the remediation or rolling back the step before proceeding.
+5. **Close waivers and accept (Level 3)**: remove remediated waivers once their mitigating requirements have passing, current evidence. Complete all ten verification categories and record the release decision ([`CONSTITUTION.md` § Acceptance](CONSTITUTION.md#acceptance)).
+
+## Prompts
+
+Ask for observed evidence and explicit discrepancy decisions. When serializing the reference format, validate against [`reference-implementation/schema.json`](reference-implementation/schema.json) (`metamodel.py --schema`) and [`spec.md` § 11](spec.md#11-metamodel-validation) invariants; prose findings and review records remain part of the process. Per step:
+
+- **1** (`REF-01`, `DATA-01`): "List entrypoints of `<repo>` as draft `capabilities`, `components` and `external_sources` (`REF-01`, `DATA-01`); record observed behavior only."
+- **2** (`DATA-01`–`DATA-04`): "Extract `data_models` from `<schemas>` with `owner`, `classification` and `derived_from` (`DATA-01`, `DATA-02`, `DATA-03`, `DATA-04`); do not invent fields."
+- **3** (`STAT-02`, `COMP-01`–`COMP-07`): "Cluster `<modules>` into `components` by consistency boundary; list observed `provides`/`requires` and violations (`STAT-02`, `COMP-01`, `COMP-02`, `COMP-03`, `COMP-04`, `COMP-05`, `COMP-06`, `COMP-07`)."
+- **4** (`STAT-01`, `CAP-01`–`CAP-04`): "Derive `preconditions`, `postconditions`, `invariants`, `failure_modes` and `interface` for `<capability>` from guards, handlers and tests (`STAT-01`, `CAP-01`, `CAP-02`, `CAP-03`, `CAP-04`)."
+- **5** (`REQ-01`, `REQ-07`, `RISK-01`–`RISK-08`): "List missing verification categories and architecture violations as `risks` (`waives`, `mitigated_by`, `expires`) and `requirements` (`REQ-01`, `REQ-07`, `RISK-01`, `RISK-02`, `RISK-03`, `RISK-04`, `RISK-08`)."
+- **Level & waiver review** (`EV-04`, `RISK-01`, `RISK-02`, `RISK-08`): "Compare these spec revisions against the observed code/tests and this level's criteria (`EV-04`, `RISK-01`, `RISK-02`, `RISK-08`). Separate observed behavior from intended fixes, verify waiver scope/expiry and record pass, defer or rework."
+- **Migration handoff** (`COMPAT-01`–`COMPAT-09`): "Refactor `<component>` within this bounded `--context` handoff while preserving the pinned contracts (`COMPAT-01`, `COMPAT-02`, `COMPAT-03`, `COMPAT-04`, `COMPAT-05`, `COMPAT-06`, `COMPAT-07`, `COMPAT-08`, `COMPAT-09`) and characterization tests. Report affected revisions, compatibility findings and any newly discovered facts, coupling or model gaps ([self-improvement](CONSTITUTION.md#self-improvement-and-model-feedback))."

system_spec_ref-0.1.0/CONSTITUTION.md

@@ -0,0 +1,205 @@
+# AI System Development Constitution
+
+Shared fundamentals for all work. Track-specific sequencing: [greenfield](GREENFIELD.md) (new systems), [brownfield](BROWNFIELD.md) (existing systems). Metamodel: [`spec.md`](spec.md).
+
+This document defines shared obligations; tracks define sequencing. Tools may check parts of an artifact, but gate decisions require review of its meaning and evidence.
+
+## Fundamental Principle
+
+Implementations are not the source of truth. The source of truth is:
+
+1. Capabilities
+2. Business rules
+3. Invariants
+4. Data contracts
+5. API contracts
+6. Verification specifications
+7. Formal models (where applicable)
+
+Code is one possible implementation of a verified specification.
+
+## Why
+
+- AI quality degrades as context grows: requirement interpretation, architecture discipline, cross-component consistency and traceability suffer.
+- Small components, explicit contracts and layering bound the context each task needs.
+- Tests, not code, are the executable specification:
+
+```text
+Capability → Contract → Data model → Tests → Code
+```
+
+---
+
+# Artifact Rules
+
+## Capabilities
+
+- Format: [`spec.md` § 4](spec.md#4-capabilities).
+- `Purpose`, `Consumers`, `Producers` and `Business value` are discovery context, not fields.
+- Acceptance criteria → `Requirement.criteria`; verification results → `Evidence`.
+- As long as the contract holds, the implementation may change freely.
+
+## Invariants
+
+- A condition that must always hold, e.g. inventory never negative; an order paid at most once; customer email unique.
+- All architectural decisions must preserve invariants.
+
+## Components
+
+- Derived from invariants and consistency requirements, not technology categories.
+  - Bad: `Database`, `REST`, `Kafka` components.
+  - Good: `Customer Management`, `Inventory Management`, `Payments`.
+- Strong consistency inside a component; eventual consistency between components.
+
+```yaml
+components:
+  - id: customer-management
+    version: "1.0"
+    layer: domain
+    consistency: strong
+    provides: [manage-customer]
+    requires: [customer-repository]
+    owns_data: [customer]
+```
+
+- Contracts and invariants belong to `capabilities`; requirements target capabilities, components or data models.
+- No implementation details in component specifications.
+
+## Data Contracts
+
+- Every externally visible structure is explicitly defined.
+- No implicit schemas; never infer or invent fields.
+- `data_models` are authoritative; at implementation or version change, see skill [`modelable`](.github/skills/modelable/SKILL.md).
+
+```yaml
+Customer:
+  id: UUID
+  email: String
+  status: [ACTIVE, BLOCKED]
+```
+
+## API Contracts
+
+Every API defines: endpoint, version, request, response, failure conditions, status codes, idempotency, security. All APIs comply with organizational API guidelines.
+
+## Verification
+
+No implementation is accepted until all categories are addressed:
+
+| Category | Covers | `Requirement.kind` | `Evidence.method` |
+|---|---|---|---|
+| Functional | Expected behaviors | `functional` | `test` |
+| Semantic | Business meaning (e.g. `BLOCKED` denies purchase) | `functional` | `test`, `model-check` or `proof` |
+| Contract | API compatibility, status codes, versioning | `functional` | `test` or `inspection` |
+| Serialization | JSON/XML/protobuf correctness, payload limits | `functional` | `test` |
+| Concurrency | Races, lost updates, duplicate requests | `functional` | `test`, `model-check` or `proof` |
+| Performance | Latency, throughput, resource limits | `non-functional` | `test` or `analysis` |
+| Scalability | Expected load and data volumes | `non-functional` | `test` or `analysis` |
+| Resilience | Timeouts, retries, partial failures | `non-functional` | `test` or `analysis` |
+| Security | Authentication, authorization, input validation | `non-functional` | `test` or `inspection` |
+| Observability | Metrics, tracing, logging, correlation IDs | `non-functional` | `test` or `inspection` |
+
+## Formal Verification
+
+- Assess per component. Indicators: concurrency, distributed state, financial transactions, safety-critical logic, complex state machines, protocols.
+- If applicable, produce TLA+/Alloy models or state machines; see skills [`tla`](.github/skills/tla/SKILL.md) (concurrency, protocols) and [`alloy`](.github/skills/alloy/SKILL.md) (structure, relations).
+- Record bounded checks as `method: model-check` with explicit `bounds` and unbounded proofs as `method: proof` ([`spec.md` § 8](spec.md#8-verification)).
+
+## Layering
+
+```text
+Experience → Application → Domain → Infrastructure
+```
+
+- Higher layers may depend on lower layers, never the reverse.
+- Domain logic must not depend on infrastructure details.
+
+## Context Budget
+
+- A component's complete specification fits on 1–2 pages (defaults: `max_provides: 5`, `max_requires: 8`, `max_owns_data: 4`); otherwise split it.
+- Each AI task receives only the minimum necessary context: these fundamentals, one track document, the applicable skill (if any) and the target component's spec slice (`metamodel.py <spec> --context <component-id>`).
+
+### Implementation Handoff
+
+For each bounded change, give the implementer:
+
+- The capability and expected outcome; accepted contract and data-model versions; affected invariants.
+- For local multi-step APIs, the state transitions, confirmation/freshness obligations, committed writes and recovery for each failure outcome. An exception after commit does not imply rollback.
+- The component boundary, permitted dependencies and relevant consumer/provider contracts.
+- Requirement IDs, measurable acceptance criteria, verification procedures and expected failure cases.
+- Applicable formal-model conclusions, assumptions, open risks and active waivers.
+- Allowed change scope and the evidence to return. Include neighboring contracts without importing unrelated implementation context.
+
+Resolve missing behavior or contradictory contracts before dependent implementation. If the packet cannot fit the context budget, split the work or revisit the component boundary. The implementer returns the change, requirement-linked results, affected revisions and any unmet criteria; it does not silently redefine the contract to fit the code.
+
+## Traceability
+
+```text
+Capability → Requirement → Invariant → Component → Contract → Test → Implementation
+```
+
+- Every test traces to a requirement; every implementation element traces to a capability.
+
+## Acceptance
+
+A system is complete only when capabilities, invariants, components, contracts, data models and APIs are specified; verification is complete; formal models are reviewed; performance and concurrency goals are met; traceability is established; and architecture constraints are preserved.
+
+Implementation completion, verification completion and release acceptance are separate states. Record each only when its obligations have been met.
+
+### Gate Decision Record
+
+Keep a short decision record alongside the specification; no particular tool or file format is required:
+
+| Record | Content |
+|---|---|
+| Scope | Gate/level, capability or change, and exact artifact revisions reviewed |
+| Adoption boundary | Whole product or bounded slice; existing authorities/tool map, repository root, validator/schema pin, native gates and external/deferred/unknown units |
+| Responsibility | Who prepared the artifacts, reviewed the evidence and owns the acceptance decision; one person may hold several roles |
+| Findings | Criteria checked, supporting artifacts, unresolved questions and affected consumers |
+| Outcome | Pass, rework, or defer within an allowed adoption-level waiver; identify the requirements/risks that justify any deferral |
+| Follow-up | Remediation owner, expiry, next action and which gate must be revisited |
+
+- **Pass** permits the next step for the recorded scope. A passing schema or validator result is supporting evidence only.
+- **Rework** keeps the affected gate open. Repair the earliest invalid assumption or artifact, then review dependent outputs again.
+- **Defer** preserves visible debt through an allowed, bounded waiver. It does not mark the waived property verified. Release permits no waiver deferrals.
+
+Review criteria for meaning, not merely presence: failure behavior, measurable thresholds, consumer obligations and formal-model assumptions must match the intended system. Inspect the linked execution artifacts before accepting a claimed result.
+
+Boundary allowlists or transitional dependency waivers (e.g., `component-boundary-allowlist.txt`) are permitted only below Level 3 (`release`) and must follow a monotonic ratcheting rule (entries may only decrease or stay equal; CI fails on additions) until completely zeroed. Multi-schema relational databases must enforce explicit schema namespace ownership and schema-scoped user roles, with zero cross-schema foreign keys.
+
+Use the [brownfield intake template](templates/BROWNFIELD-INTAKE.md) for existing systems. Separate observed classification from provisional handling policy; retain skips and missing provider/data mappings as open obligations. Contract/source bindings and local file hashes support review but do not replace source authenticity, build correspondence or native acceptance gates.
+
+### Change and Reverification Loop
+
+1. Identify the requested behavior change and the last reviewed baseline. Trace affected capabilities, components, data models, consumers and requirements, including transitive dependencies (`--impact <id>`).
+2. Decide whether the contract stays compatible (`--compat`). If it breaks, define consumer migration and recovery before implementation; a version bump alone does not establish compatibility.
+3. Reopen the earliest affected gate. Update its artifacts and verification criteria, then issue a bounded implementation handoff.
+4. Treat evidence affected by changed requirements, subjects or dependencies as historical until rerun. Record requirement version, subject revision and the relevant dependency versions with the new results; preserve earlier failures and justify any supersession.
+5. Review new results against all affected obligations, including risk mitigations and consumer behavior. Record the gate decision and remaining work.
+
+### Self-Improvement and Model Feedback
+
+When discovery, implementation, verification, formal modeling or incident review reveals new facts (undocumented failure modes, hidden coupling, violated assumptions, unmodeled domain constraints or gaps in the metamodel/process itself):
+
+1. **Surface the finding immediately** in the handoff return or [gate decision record](#gate-decision-record); never mask a missing contract clause, invariant or dependency with an ad-hoc code workaround.
+2. **Update the system model**: feed discovered facts back into `capabilities`, `components`, `data_models`, `requirements`, `risks` or formal models, run `--impact`, and reopen the earliest affected gate.
+3. **Improve the metamodel and tooling**: when a finding exposes an uncheckable rule or recurring blind spot in [`spec.md`](spec.md), track workflows or [`metamodel.py`](reference-implementation/metamodel.py), propose a minimal update to `spec.md` § 11, `INVARIANTS`, `schema.json` and `corpus.yaml`.
+
+---
+
+# Metamodel Mapping
+
+| Artifact | Metamodel (`spec.md`) |
+|---|---|
+| Capabilities | `capabilities` (`version`, `preconditions`, `postconditions`, `invariants`, `failure_modes`, `status`) |
+| Invariants | `capabilities.invariants` |
+| Components | `components` (`provides`, `requires`, `owns_data`, `status`, `source_paths`) |
+| Data contracts | `data_models` (`schema_path`, `declassified_by`) |
+| API contracts | Capability contracts, `requirements` and `data_models` (`capabilities.interface`) |
+| Verification | `requirements` (`status`, `category`, `resolved_by`), `evidence` (`subject_revision`, `supersedes`) |
+| Formal verification | `evidence.method: model-check` (with `bounds`) or `proof`; formal models in `provenance` |
+| Layering | `system.layers`, `components.layer` |
+| Context budget | `system.context_budget` (`max_provides`, `max_requires`, `max_owns_data`); per-component override `components.context_budget` |
+| Waivers | `risks` (`mitigated_by`, `waives`, `expires`) |
+| Traceability | Capability, component, requirement, data model and evidence references |
+| Acceptance | `metamodel.py <spec> --stage release` (see [`spec.md` § 11](spec.md#11-metamodel-validation)) |

system_spec_ref-0.1.0/GREENFIELD.md

@@ -0,0 +1,86 @@
+# Greenfield: Creating New Systems
+
+Contract-first sequencing for new systems. Artifact rules: [constitution](CONSTITUTION.md). Load this document together with the constitution only.
+
+## Phases
+
+| # | Phase | Output | Gate |
+|---|---|---|---|
+| 1 | Capability discovery | Capabilities with contracts and failure modes | 1 |
+| 2 | Invariant discovery | Invariants per capability | 1 |
+| 3 | Component identification | Components derived from invariants and consistency boundaries | 2 |
+| 4 | Component specification | Component definitions; no implementation details | 2 |
+| 5 | Data contracts | Data models with owners | 2 |
+| 6 | API contracts | API contracts per capability | 2 |
+| 7 | Verification specification | Requirements covering all 10 categories | 3 |
+| 8 | Formal verification assessment | Formal models where indicated | 3 |
+| 9 | Layering | Layers assigned; rules hold | 2 |
+| 10 | Context budget | Oversized components split | 2 |
+| 11 | Traceability | All artifacts linked | 4 |
+| 12 | Acceptance | Passing, current evidence for all mandatory requirements | 4 |
+
+Rules:
+
+- Do not discuss technical architecture before capabilities are identified.
+- Phase numbers identify work products; execution follows gate order: **1–2 → 3–6 and 9–10 → 7–8 → implementation → 11–12**.
+- Begin implementation only after the discovery, architecture and verification gates pass for the change's scope.
+
+## Gates (`--stage`, see [`spec.md` § 11](spec.md#11-metamodel-validation))
+
+1. **Discovery** (`--stage discovery`): Phases 1–2; capabilities `specified` with non-empty contract clauses.
+2. **Architecture** (`--stage architecture`): Phases 3–6, 9–10; components `specified`, dependencies resolved, layer rules, data models, interface contracts and context budgets satisfied.
+3. **Verification** (`--stage verification`): Phases 7–8; requirements `specified` across all 10 categories; formal models checked with [`tla`](.github/skills/tla/SKILL.md) or [`alloy`](.github/skills/alloy/SKILL.md) where indicated.
+4. **Release** (`--stage release`): Phases 11–12; all active entities `verified`, passing current `Evidence` for all mandatory and mitigating requirements, all risks disposed, zero waivers.
+
+For each gate, use the [shared decision record](CONSTITUTION.md#gate-decision-record): review the artifacts, record findings and decide whether to proceed or rework.
+
+| Gate | Bring to review | Decision required before proceeding |
+|---|---|---|
+| Discovery | User/business outcome, consumers, capability contracts, invariants and failure cases | The scope and observable success/failure behavior are understood; material questions are resolved |
+| Architecture | Component boundaries, dependency/layer map, ownership, data/API contracts and context budget | The composition can preserve the invariants; every dependency has an explicit contract and owner |
+| Verification | Requirement-to-criterion mapping across all ten categories, planned tests/inspections, formal assessment and assumptions | Each obligation has a meaningful way to establish pass/fail; applicable formal checks are reviewed before implementation |
+| Release | Requirement-linked execution results for current revisions, traceability, consumer compatibility/migration results and risk dispositions | All mandatory and mitigating obligations are satisfied, unresolved failures are addressed and no waiver remains |
+
+If a gate fails, return to the earliest affected phase; do not advance by relabeling an incomplete artifact. Validate each gate with `metamodel.py <spec> --stage <gate>` and pass only the target component's slice (`--context <component-id>`) to the coding agent. At implementation (AI Execution Rule step 9), derive `.mdl` and typed data artifacts with [`modelable`](.github/skills/modelable/SKILL.md).
+
+## Implementation and Acceptance Loop
+
+1. Select one capability change whose first three gates have passed. Prepare the [implementation handoff](CONSTITUTION.md#implementation-handoff).
+2. Make verification executable before implementing the intended behavior; confirm a meaningful failing case where behavior is missing. Reused passing checks still need reviewed coverage of the change.
+3. Implement within the accepted component boundary. Return to the affected gate if a contract, ownership or dependency must change.
+4. Run the specified verification and inspect results. Record failures as well as successes with requirement IDs and applicable revisions.
+5. Review traceability, compatibility, evidence freshness and risk treatment at release. Close the scope only after recording the acceptance decision; carry unresolved work explicitly.
+
+Worked example traced through Phases 1–12: [`examples/greenfield/`](examples/greenfield/README.md).
+
+## AI Execution Rule
+
+When asked to design or implement any feature, produce artifacts in this order:
+
+```text
+1. Capability
+2. Invariants
+3. Component definition
+4. Contracts
+5. Data model
+6. Verification specification
+7. Formal model (if applicable)
+8. Architecture impact analysis (--impact)
+9. Implementation
+10. Verification results
+```
+
+- For each step, produce the artifact or cite the reviewed artifact being reused with an impact justification.
+- Never generate implementation before verification has been specified.
+- Treat architecture as provable constraints, not a collection of code files.
+
+## Prompts
+
+Ask for the artifact and the decisions it supports. When serializing the reference format, validate against [`reference-implementation/schema.json`](reference-implementation/schema.json) (`metamodel.py --schema`) and [`spec.md` § 11](spec.md#11-metamodel-validation) invariants; prose decisions and review evidence remain part of the process. Per phase:
+
+- **1–2** (`STAT-01`, `CAP-01`): "List capabilities of `<domain>` (`status: specified`) with non-empty `preconditions` or `postconditions`, `invariants` and `failure_modes` (`STAT-01`, `CAP-01`); no architecture."
+- **3–4** (`STAT-02`, `COMP-01`–`COMP-07`): "Derive components (`status: specified`) from these invariants and consistency boundaries; assign `layer`, `provides`, `requires` and `owns_data` within `context_budget` (`STAT-02`, `COMP-01`, `COMP-02`, `COMP-03`, `COMP-04`, `COMP-05`, `COMP-06`, `COMP-07`)."
+- **5–6** (`DATA-01`–`DATA-04`, `CAP-02`–`CAP-03`): "Define `data_models` and capability `interface` contracts for `<capability>` mapping every failure mode in `errors` (`DATA-01`, `DATA-02`, `DATA-03`, `DATA-04`, `CAP-02`, `CAP-03`); do not invent fields."
+- **7–8** (`STAT-03`, `CAP-04`, `REQ-01`–`REQ-03`, `REQ-07`, `EV-01`): "Write `requirements` (`status: specified`, `category`, matching `kind`) for all 10 verification categories of `<capability>` (`STAT-03`, `CAP-04`, `REQ-01`, `REQ-02`, `REQ-03`, `REQ-07`); flag formal verification candidates (`EV-01`)."
+- **Gate review** (`STAT-04`, `EV-04`, `REQ-04`–`REQ-06`, `RISK-01`–`RISK-08`): "Review these artifact revisions against this gate's criteria and invariants (`STAT-04`, `EV-04`, `REQ-04`, `REQ-05`, `REQ-06`, `RISK-01`, `RISK-02`, `RISK-08`). Identify contradictions and missing evidence; record pass or rework with the next action. Do not infer acceptance from validator output."
+- **Implementation** (`COMPAT-01`–`COMPAT-09`): "Implement this bounded `--context` handoff against the accepted contracts and tests (`COMPAT-01`, `COMPAT-02`, `COMPAT-03`, `COMPAT-04`, `COMPAT-05`, `COMPAT-06`, `COMPAT-07`, `COMPAT-08`, `COMPAT-09`). Return requirement-linked results, affected revisions and any newly discovered facts or model gaps ([self-improvement](CONSTITUTION.md#self-improvement-and-model-feedback)); surface contract changes before implementing dependent behavior."

system_spec_ref-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tommy Alander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.