factory-framework 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ff/schemas.py ADDED
@@ -0,0 +1,141 @@
1
+ """Draft 2020-12 JSON Schemas for `ff.yaml`, `checks`, `record`, and `proofs`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ from collections.abc import Sequence
7
+ from typing import Any, Literal
8
+
9
+ from jsonschema import Draft202012Validator
10
+
11
+ from ff import models as m
12
+
13
+ SchemaKind = Literal["ff.yaml", "checks", "record", "proofs"]
14
+ SCHEMA_KINDS: tuple[SchemaKind, ...] = ("ff.yaml", "checks", "record", "proofs")
15
+ _A1: dict[str, SchemaKind] = {"config": "ff.yaml", "ff.yaml": "ff.yaml", "check": "checks", "checks": "checks"}
16
+ _A2: dict[str, SchemaKind] = {"checks.yaml": "checks", "record": "record", "ff-record": "record", "proof": "proofs"}
17
+ _ALIASES: dict[str, SchemaKind] = _A1 | _A2 | {"$ff_record": "record", "proofs": "proofs"}
18
+ _DRAFT = "https://json-schema.org/draft/2020-12/schema"
19
+ _BASE = "https://fmind.github.io/factory-framework/schemas"
20
+ _SHA256 = r"^sha256:[0-9a-f]{64}$"
21
+ _SPEC_ST = ("PROVEN", "FAILING", "ERROR", "UNPROVEN", "UNCLEAR")
22
+ _INTENT_ST = ("PROVEN", "PARTIAL", "FAILING", "ERROR", "UNPROVEN", "UNCLEAR", "UNCOVERED")
23
+
24
+
25
+ def _s(max_len: int = 2048, *, min_len: int = 0, pat: str = "") -> dict[str, Any]:
26
+ out: dict[str, Any] = {"type": "string", "maxLength": max_len}
27
+ return out | ({"minLength": min_len} if min_len else {}) | ({"pattern": pat} if pat else {})
28
+
29
+
30
+ def _en(*vals: str) -> dict[str, Any]:
31
+ return {"type": "string", "enum": list(vals)}
32
+
33
+
34
+ def _arr(items: dict[str, Any], *, min_items: int = 0, max_items: int = 0, unique: bool = False) -> dict[str, Any]:
35
+ out: dict[str, Any] = {"type": "array", "items": items} | ({"uniqueItems": True} if unique else {})
36
+ return out | ({"minItems": min_items} if min_items else {}) | ({"maxItems": max_items} if max_items else {})
37
+
38
+
39
+ def _opt(inner: dict[str, Any]) -> dict[str, Any]:
40
+ return {"anyOf": [inner, {"type": "null"}]}
41
+
42
+
43
+ def _obj(
44
+ props: dict[str, Any] | None = None,
45
+ *,
46
+ req: Sequence[str] = (),
47
+ req_all: bool = False,
48
+ extra: Any = False,
49
+ names: str = "",
50
+ ) -> dict[str, Any]:
51
+ out: dict[str, Any] = {"type": "object", "additionalProperties": extra}
52
+ if req_keys := (list(props) if (req_all and props) else list(req)):
53
+ out["required"] = req_keys
54
+ if names:
55
+ out["propertyNames"] = {"pattern": names}
56
+ return out | ({"properties": props} if props is not None else {})
57
+
58
+
59
+ def _doc(slug: str, title: str, desc: str, body: dict[str, Any]) -> dict[str, Any]:
60
+ return {"$schema": _DRAFT, "$id": f"{_BASE}/{slug}.schema.json", "title": title, "description": desc, **body}
61
+
62
+
63
+ _VER, _NUM, _BOOL = {"type": "integer", "const": m.FORMAT}, {"type": "number"}, {"type": "boolean"}
64
+ _INT0 = {"type": "integer", "minimum": 0}
65
+ _TIMEOUT, _PREC = {"type": "integer", "minimum": 1, "maximum": 3600}, {"type": "integer", "minimum": 0, "maximum": 6}
66
+ _IID, _SID = _s(128, pat=m.INTENT_ID_PAT), _s(128, pat=m.SPEC_ID_PAT)
67
+ _CID, _DOM = _s(128, pat=m.CHECK_ID_PAT), _s(128, pat=m.DOMAIN_PAT)
68
+ _TTL, _PTH = _s(512, min_len=1), _s(1024, min_len=1)
69
+ _I_ARR, _S_ARR, _C_ARR = _arr(_IID, unique=True), _arr(_SID, unique=True), _arr(_CID, unique=True)
70
+ _MRULE = _obj({"min": _opt(_NUM), "max": _opt(_NUM), "precision": _opt(_PREC), "unit": _s(64)})
71
+ _MRULES = _obj(extra=_MRULE, names=m.METRIC_PAT)
72
+ _REC_1 = {"check": _CID, "status": _en("pass", "fail", "error"), "summary": _s(2048)}
73
+ _REC_P = _REC_1 | {"metrics": _obj(extra=_NUM, names=m.METRIC_PAT), "evidence": _arr(_s(1024), max_items=64)}
74
+ _GATE_ARR, _ARGV = _arr(_en(*m.GATE_TOKENS), unique=True), _opt(_arr(_PTH, min_items=1, max_items=64))
75
+ _RUNNERS = _obj(extra=_arr(_PTH, min_items=1, max_items=16), names=m.RUNNER_EXT_PAT)
76
+ _RUN_1 = {"pytest": _opt(_arr(_PTH, min_items=1, max_items=32)), "runners": _opt(_RUNNERS)}
77
+ _RUN_2 = {"jobs": {"type": "integer", "minimum": 0, "maximum": 128}, "timeout": _TIMEOUT}
78
+ _RUN_F = _RUN_1 | _RUN_2 | {"env": _arr(_s(128, min_len=1), max_items=64, unique=True)}
79
+ _CHG_CFG = _obj({"source": _en("files", "github"), "github_label": _s(64, min_len=1)})
80
+ _CFG_1 = {"version": _VER, "name": _s(128, min_len=1), "gate": _opt(_obj({"fail_on": _GATE_ARR}))}
81
+ _CFG_P = _CFG_1 | {"changes": _opt(_CHG_CFG), "run": _opt(_obj(_RUN_F))}
82
+ _CHK_SPEC = _obj({"serves": _opt(_arr(_IID, min_items=1, unique=True)), "metrics": _opt(_MRULES)})
83
+ _CHK_ITEM_1 = {"file": _opt(_PTH), "argv": _ARGV, "proves": _opt(_arr(_SID, min_items=1, unique=True))}
84
+ _CHK_ITEM = _obj(_CHK_ITEM_1 | {"metrics": _opt(_MRULES), "timeout": _opt(_TIMEOUT), "serial": _BOOL})
85
+ _CHK_MAP = _obj(extra=_CHK_ITEM, names=m.CHECK_ID_PAT)
86
+ _CHK_DOM = {"version": _VER, "domain": _opt(_DOM), "file": _opt(_PTH)}
87
+ _CHK_DOM |= {"specs": _opt(_obj(extra=_CHK_SPEC, names=m.SPEC_ID_PAT)), "checks": _opt(_CHK_MAP)}
88
+ _PRF_MV1 = {"value": _opt(_NUM), "min": _opt(_NUM), "max": _opt(_NUM), "unit": _s(64)}
89
+ _PRF_MVAL = _obj(_PRF_MV1 | {"passed": _BOOL, "check": _opt(_CID)}, req_all=True)
90
+ _PRF_SP_1 = {"id": _SID, "title": _TTL, "status": _en(*_SPEC_ST), "serves": _I_ARR, "checks": _C_ARR}
91
+ _PRF_SPEC = _obj(_PRF_SP_1 | {"metrics": _obj(extra=_PRF_MVAL, names=m.METRIC_PAT)}, req_all=True)
92
+ _PRF_IN = {"id": _IID, "title": _TTL, "status": _en(*_INTENT_ST), "specs": _S_ARR, "proven": _INT0, "total": _INT0}
93
+ _PRF_INT = _obj(_PRF_IN, req_all=True)
94
+ _PRF_SUM = _obj({"intents": _obj(extra=_INT0), "specs": _obj(extra=_INT0), "checks": _obj(extra=_INT0)}, req_all=True)
95
+ _PRF_FILES = _obj(extra=_s(71, pat=_SHA256), names=r"^[^/\\]+(?:/[^/\\]+)*$")
96
+ _PRF_CHK = _obj(extra=_obj({**_REC_P, "proves": _S_ARR}, req_all=True), names=m.CHECK_ID_PAT)
97
+ _PRF_1 = {"version": _VER, "domain": _DOM, "digest": _s(71, pat=_SHA256), "files": _PRF_FILES}
98
+ _PRF_2 = {"status": _en(*_INTENT_ST), "summary": _PRF_SUM, "checks": _PRF_CHK}
99
+ _PRF_3 = {"specs": _obj(extra=_PRF_SPEC, names=m.SPEC_ID_PAT), "intents": _obj(extra=_PRF_INT, names=m.INTENT_ID_PAT)}
100
+ _PRF_P = _PRF_1 | _PRF_2 | _PRF_3
101
+ _SCHEMAS: dict[SchemaKind, dict[str, Any]] = {
102
+ "ff.yaml": _doc("ff-yaml", "Factory Configuration", "Global settings and runners.", _obj(_CFG_P, req=("version",))),
103
+ "checks": _doc("checks", "Domain Check Config", "Specs, checks, bounds.", _obj(_CHK_DOM, req=("version",))),
104
+ "record": _doc("record", "Check Record ($FF_RECORD)", "Subprocess check record.", _obj(_REC_P)),
105
+ "proofs": _doc("proofs", "Domain Proof Report", "Digests, records, verdicts.", _obj(_PRF_P, req_all=True)),
106
+ }
107
+ _VALIDATORS = {k: Draft202012Validator(v) for k, v in _SCHEMAS.items()}
108
+
109
+
110
+ def resolve_kind(name: str) -> SchemaKind:
111
+ key = name.strip().lower()
112
+ if key not in _ALIASES:
113
+ raise m.InputError(f"unknown schema '{name}'; choose from: {', '.join(SCHEMA_KINDS)}")
114
+ return _ALIASES[key]
115
+
116
+
117
+ def schema_for(name: str) -> dict[str, Any]:
118
+ return copy.deepcopy(_SCHEMAS[resolve_kind(name)])
119
+
120
+
121
+ def all_schemas() -> dict[str, dict[str, Any]]:
122
+ return {kind: copy.deepcopy(_SCHEMAS[kind]) for kind in SCHEMA_KINDS}
123
+
124
+
125
+ def _unwrap(err: Any) -> list[Any]:
126
+ if err.validator == "anyOf" and err.instance is not None and err.context:
127
+ non_null = [sub for sub in err.context if sub.schema != {"type": "null"}]
128
+ if non_null:
129
+ out: list[Any] = []
130
+ for sub in non_null:
131
+ out.extend(_unwrap(sub))
132
+ return out
133
+ return [err]
134
+
135
+
136
+ def validate(name: str, payload: object, *, label: str = "") -> list[str]:
137
+ kind = resolve_kind(name)
138
+ pfx = f"{label}: " if label else ""
139
+ flat = [leaf for err in _VALIDATORS[kind].iter_errors(payload) for leaf in _unwrap(err)]
140
+ errs = sorted(flat, key=lambda e: ([str(p) for p in e.absolute_path], e.message))
141
+ return [f"{pfx}{'.'.join(str(p) for p in err.absolute_path) or '<root>'}: {err.message}" for err in errs]
ff/skill/SKILL.md ADDED
@@ -0,0 +1,47 @@
1
+ ---
2
+ name: ff
3
+ description: Set up, author, verify, audit, and export Factory Framework (ff) contracts in factory/: Markdown intents and specs, domain checks YAML, polyglot tests, change notes, and deterministic domain proofs.
4
+ ---
5
+
6
+ # Factory Framework (`ff`)
7
+
8
+ `ff` stores a verifiable delivery contract in `factory/`: human-readable CommonMark intents and specs, per-domain check configs, behavioral test runners, and deterministic domain proofs.
9
+
10
+ ## When to use
11
+
12
+ - Initializing `factory/` or inspecting contract health (`status`, `ls`, `show`, `lint`).
13
+ - Authoring intents, specs, `checks/<domain>.yaml`, behavioral checks in `tests/`, or change notes.
14
+ - Investigating failing checks, proof regressions, `--base` anti-weakening errors (`FFR0`–`FFR4`), or exporting reports.
15
+
16
+ ## Read first (read-only discovery)
17
+
18
+ ```bash
19
+ ff status --json
20
+ ff ls --tree
21
+ ff lint --strict --json
22
+ ```
23
+
24
+ Read `factory/ff.yaml`, `factory/checks/<domain>.yaml`, and targeted items via `ff show <ID>` before proposing edits.
25
+
26
+ ## Guardrails
27
+
28
+ - **Protect human intent**: Ask the user before editing or removing files under `factory/intents/`.
29
+ - **Compute done, never type it**: Never write `[x]` checkboxes (`FF003`) or inline `serves:` metadata in Markdown, and never hand-edit `factory/proofs/*.json`.
30
+ - **Keep 1-to-1 `<domain>` symmetry**: Align `intents/<domain>.md`, `specs/<domain>.md`, `checks/<domain>.yaml`, and generated `proofs/<domain>.json` (`FF010`, `FF011`).
31
+ - **Keep checks honest and behavioral**: Place tests in `factory/tests/`, target observable behavior, never weaken metric bounds or `gate.fail_on`, and never silence failures.
32
+ - **Document changes honestly**: Record breaking or weakening contract changes via `factory/changes/YYYY-MM-DD_<slug>.md` (or labeled GitHub issues when configured).
33
+
34
+ ## Quick workflow
35
+
36
+ 1. Inspect state: run `ff status`, `ff ls --tree`, and `ff show <ID>`.
37
+ 2. Edit contract files: update `factory/intents/<domain>.md` (with approval), `factory/specs/<domain>.md`, `factory/checks/<domain>.yaml`, or `factory/tests/*`.
38
+ 3. Validate structure: run `ff lint` (or `ff lint --base main --strict`).
39
+ 4. Run checks and generate proofs: run `ff run` (or `ff run --domain <domain>`).
40
+ 5. Verify reproducibility end-to-end: run `ff verify --base main --strict`.
41
+ 6. Export stakeholder summaries when requested: run `ff export -f md|html|csv|jsonl`.
42
+
43
+ ## Reference guides
44
+
45
+ - [Authoring contracts, naming conventions, and domain layout](references/authoring.md)
46
+ - [Configuring `checks/<domain>.yaml`, polyglot runners, `$FF_RECORD`, and `--pytest`](references/checks.md)
47
+ - [Daily workflow, `FF001`–`FF012` & `FFR0`–`FFR4` rules, exports, hooks, CI, and MCP](references/workflow.md)
@@ -0,0 +1,59 @@
1
+ # Authoring Contracts in `factory/`
2
+
3
+ ## Repository layout
4
+
5
+ ```text
6
+ factory/
7
+ ├── ff.yaml # Global settings: name, gate, changes, run defaults
8
+ ├── intents/<domain>.md # Why a capability matters (User Story recommended)
9
+ ├── specs/<domain>.md # What the system guarantees (Given/When/Then or EARS)
10
+ ├── checks/<domain>.yaml # Domain wiring, proves overrides, metric bounds, check targets
11
+ ├── tests/ # Behavioral test scripts (Python, Bash, JS, pytest, binaries)
12
+ ├── changes/YYYY-MM-DD_<slug>.md # Change notes explaining contract updates or weakening
13
+ └── proofs/<domain>.json # Generated deterministic domain proof (never hand-edit)
14
+ ```
15
+
16
+ ## Pure CommonMark headings and IDs
17
+
18
+ - Author plain CommonMark headings without `{#id}` anchors (`FF004`), `[x]` checkboxes (`FF003`), or inline metadata lines.
19
+ - Only **leaf headings** (headings with no child headings inside the same file) compile to contract items:
20
+ - In `intents/<domain>.md`: leaf headings compile to `intent_<domain>_...`.
21
+ - In `specs/<domain>.md`: leaf headings compile to `spec_<domain>_...`.
22
+ - Slugification joins heading levels with `_` and words within a heading with `-` (lowercase ASCII):
23
+ - `# Checkout` -> `## Fast Totals` in `intents/checkout.md` compiles to `intent_checkout_fast-totals`.
24
+ - `# Checkout` -> `## Fast Totals` -> `### Latency` in `specs/checkout.md` compiles to `spec_checkout_fast-totals_latency`.
25
+ - End any unclear requirement heading with `[?]` while open questions remain; `ff` marks it `UNCLEAR` (`FF009`).
26
+
27
+ ## Recommended prose styles
28
+
29
+ - **Intents (User Story)**: Keep stakeholder value clear:
30
+ - _"As a [role], I want [capability], so that [measurable outcome]."_
31
+ - **Specs (Given/When/Then or EARS)**: State testable system behavior concisely:
32
+ - _"Given [context], when [trigger], then [observable guarantee]."_
33
+ - Or EARS: _"When [trigger], the system shall [observable response]."_
34
+
35
+ ## 1-to-1 `<domain>` symmetry and auto-linking
36
+
37
+ - Every domain shares one stem `<domain>` across `intents/<domain>.md`, `specs/<domain>.md`, `checks/<domain>.yaml`, and generated `proofs/<domain>.json` (`FF010`, `FF011`).
38
+ - Default convention links `intent <- spec <- check` without boilerplate:
39
+ - `spec_<prefix>_*` automatically serves matching `intent_<prefix>` (longest matching prefix wins).
40
+ - Check stems `test_<spec>` or `check_<spec>` (with optional `__<case>` suffix, e.g. `test_checkout_fast-totals_latency__eu`) automatically prove `spec_<spec>`.
41
+ - Override links explicitly in `factory/checks/<domain>.yaml` using `specs.<id>.serves` or `checks.<id>.proves`.
42
+
43
+ ## Global `factory/ff.yaml` settings
44
+
45
+ ```yaml
46
+ version: 1
47
+ name: my-service
48
+ gate:
49
+ fail_on: [FAILING, ERROR] # Options: FAILING, ERROR, UNPROVEN, UNCLEAR
50
+ changes:
51
+ source: files # Or: github (issues labeled with github_label)
52
+ github_label: ff-change
53
+ run:
54
+ pytest: auto # auto | true | false
55
+ jobs: 4
56
+ timeout: 120
57
+ ```
58
+
59
+ Inspect Draft 2020-12 JSON Schemas anytime with `ff schema [ff.yaml|checks|record|proofs]`.
@@ -0,0 +1,69 @@
1
+ # Domain Checks, Polyglot Runners, and `$FF_RECORD`
2
+
3
+ ## Domain check config (`factory/checks/<domain>.yaml`)
4
+
5
+ Declare specs, metric bounds, and runnable checks for one domain:
6
+
7
+ ```yaml
8
+ version: 1
9
+ domain: checkout
10
+ specs:
11
+ spec_checkout_fast-totals_latency:
12
+ serves: [intent_checkout_fast-totals] # Optional override
13
+ metrics:
14
+ p95_ms: { max: 50, precision: 0, unit: ms }
15
+ checks:
16
+ check_checkout_fast-totals_latency:
17
+ file: tests/check_checkout.py
18
+ metrics:
19
+ p95_ms: { max: 50, precision: 0, unit: ms }
20
+ timeout: 30
21
+ ```
22
+
23
+ - Each entry under `checks:` identifies either `file` (relative to `factory/` or project root) OR explicit `argv` (array of strings; `file` and `argv` are mutually exclusive).
24
+ - Use `serial: true` only when checks contend for a shared port, database, or local lock.
25
+ - Metric bounds support `min`, `max`, `precision` (decimals), and `unit`; `specs.<id>.metrics` overrides or refines check metrics on that spec.
26
+
27
+ ## Polyglot runners (`run.runners` & `argv`)
28
+
29
+ `ff run` maps extensions via built-in defaults (customizable in `ff.yaml` under `run.runners`):
30
+
31
+ - `.py` -> `["python3", "{file}"]`
32
+ - `.sh` -> `["bash", "{file}"]`
33
+ - `.js`, `.mjs`, `.cjs` -> `["node", "{file}"]`
34
+
35
+ For Java, Go, Rust, or custom commands, set `argv` directly on the check (executed with `shell=False` from the repository root):
36
+
37
+ ```yaml
38
+ checks:
39
+ check_ledger_balance:
40
+ argv: [go, test, ./..., -run, TestLedgerBalance]
41
+ proves: [spec_ledger_balance]
42
+ ```
43
+
44
+ ## File-based `$FF_RECORD` contract
45
+
46
+ For every check subprocess, `ff` creates temporary storage and exports `$FF_CHECK`, `$FF_RECORD` (path to write JSON), and `$FF_ARTIFACTS` (directory for coverage XML/JSON, screenshots, or build output) under an allowlisted environment (`TZ=UTC`).
47
+
48
+ Writing `$FF_RECORD` is optional:
49
+
50
+ - If a polyglot script omits `$FF_RECORD`, exit code `0` passes and non-zero fails.
51
+ - When written, `$FF_RECORD` must match the `record` schema (`additionalProperties: false`); every field is optional:
52
+
53
+ ```json
54
+ {
55
+ "check": "check_checkout_fast-totals_latency",
56
+ "status": "PASS",
57
+ "summary": "Checkout P95 latency stayed at 31 ms across 50 requests",
58
+ "metrics": { "p95_ms": 31 },
59
+ "evidence": ["p95_ms=31", "sample_size=50"]
60
+ }
61
+ ```
62
+
63
+ - Valid `status` values: `"PASS"`, `"FAIL"`, `"SKIP"`. Conservative reconciliation applies: explicit `"FAIL"`, `"SKIP"`, or non-zero exit always produces failure/error.
64
+
65
+ ## Opt-in `--pytest` mode
66
+
67
+ - `ff init --example` scaffolds a zero-`pytest` check (`tests/check_hello.py`) that writes `$FF_RECORD`.
68
+ - Pass `--pytest` (`ff init --example --pytest`) or install `factory-framework[pytest]` to scaffold `factory/tests/conftest.py` (`ff_record` fixture, `record_property` bridge, and skip/zero-test guard) plus `tests/test_*.py`.
69
+ - Set top-level `file: tests/test_<domain>.py` in `checks/<domain>.yaml` when sharing one pytest file across checks in a domain.
@@ -0,0 +1,55 @@
1
+ # CLI Workflow, Rules, Governance, and Integrations
2
+
3
+ ## CLI commands
4
+
5
+ - `ff init [DIR] [--example] [--pytest]` — scaffold `factory/` (stdlib check by default; `--pytest` adds `conftest.py`).
6
+ - `ff lint [--base REF] [--strict]` — validate contract Markdown, YAML, 1-to-1 domains, proofs, and change rules.
7
+ - `ff run [CHECK...] [--domain D] [-j N] [--no-write]` — run checks in parallel and update `factory/proofs/<domain>.json`.
8
+ - `ff verify [--base REF] [-j N] [--strict]` — lint, re-run all checks from scratch, verify proofs match, and enforce `gate.fail_on`.
9
+ - `ff status` and `ff ls [--kind K] [--domain D] [--status S] [--tree] [-n N]` — inspect verdicts and graph links.
10
+ - `ff show <ID>` — view full text, metrics, bounds, and latest check evidence for an intent, spec, check, or change note.
11
+ - `ff export [-f {html,csv,md,jsonl}] [--domain D] [--summary FILE] [-o FILE]` — render executive proof reports.
12
+ - `ff schema [ff.yaml|checks|record|proofs]` — print Draft 2020-12 JSON Schemas.
13
+ - `ff hook [print] {pre-commit,lefthook,github-actions}` — emit two-tier hook/CI config.
14
+ - `ff mcp [--transport {stdio,http}] [--port 8765]` — start read-only MCP server (`ff_status`, `ff_ls`, `ff_show`, `ff_lint`).
15
+ - `ff skill install [DIR] [--check]` — install or verify exact sync of the `/ff` skill.
16
+
17
+ Use `--factory PATH` to target another contract directory and `--json` for machine-readable output.
18
+
19
+ ## Lint and `--base` anti-weakening rules
20
+
21
+ - **Errors (`FF001`–`FF008`)**: missing/unreadable `ff.yaml` or YAML parse failure, duplicate IDs, manual `[x]` checkboxes, inline anchors/metadata, dangling links, unreachable specs, unlinked intents (`FF008`).
22
+ - **Info/Warnings (`FF009`–`FF012`)**:
23
+ - `FF009` (info): `[?]` unresolved intent/spec heading (`UNCLEAR`).
24
+ - `FF010` / `FF011` (warning, error under `--strict`): mismatched `<domain>` files across `intents/`, `specs/`, and `checks/`.
25
+ - `FF012` (warning on missing/stale/orphan `proofs/<domain>.json`; error on corrupt JSON).
26
+ - **Base diff rules (`FFR0`–`FFR4` with `--base REF`)**:
27
+ - `FFR0` (warning, error under `--strict`): contract modified since `REF` without a change note or matching GitHub issue.
28
+ - `FFR1`–`FFR4` (error): removing or weakening proven intents/specs (`FFR1`), proving checks (`FFR2`), metric bounds (`FFR3`), or `gate.fail_on` / proof status (`FFR4`) without a change note or issue.
29
+
30
+ ## Change notes & GitHub issues
31
+
32
+ Create `factory/changes/YYYY-MM-DD_<slug>.md` with `## Motivation` and `## Changes` (optional YAML frontmatter `touches:`, `resolves:`, `supersedes:`):
33
+
34
+ ```markdown
35
+ ---
36
+ touches: [checks/checkout.yaml, specs/checkout.md]
37
+ ---
38
+
39
+ # Tighten checkout latency bound
40
+
41
+ ## Motivation
42
+
43
+ Explain why the contract changed or tightened/relaxed bounds.
44
+
45
+ ## Changes
46
+
47
+ - Updated `p95_ms` threshold in `checks/checkout.yaml`.
48
+ ```
49
+
50
+ When `changes.source: github` in `ff.yaml`, labeled GitHub issues (`github_label`, default `ff-change`) referenced as `#<number>` in commit messages or `$GH_PR_BODY` satisfy `FFR0`–`FFR4`.
51
+
52
+ ## MCP and hooks
53
+
54
+ - Run `ff verify --strict` before wrapping up; `ff hook github-actions` emits CI workflows calling `ff lint --base ... --strict` and `ff verify --strict` with `$GITHUB_STEP_SUMMARY` output.
55
+ - Configure `ff mcp` in coding harnesses for read-only inspection without mutating `factory/`.