factory-framework 0.3.1__tar.gz
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.
- factory_framework-0.3.1/LICENSE +21 -0
- factory_framework-0.3.1/PKG-INFO +205 -0
- factory_framework-0.3.1/README.md +169 -0
- factory_framework-0.3.1/pyproject.toml +205 -0
- factory_framework-0.3.1/pyproject.toml.orig +168 -0
- factory_framework-0.3.1/src/ff/__init__.py +18 -0
- factory_framework-0.3.1/src/ff/__main__.py +7 -0
- factory_framework-0.3.1/src/ff/cli.py +320 -0
- factory_framework-0.3.1/src/ff/export.py +234 -0
- factory_framework-0.3.1/src/ff/gitio.py +229 -0
- factory_framework-0.3.1/src/ff/lint.py +202 -0
- factory_framework-0.3.1/src/ff/mcp.py +138 -0
- factory_framework-0.3.1/src/ff/models.py +372 -0
- factory_framework-0.3.1/src/ff/parse.py +457 -0
- factory_framework-0.3.1/src/ff/proofs.py +178 -0
- factory_framework-0.3.1/src/ff/py.typed +0 -0
- factory_framework-0.3.1/src/ff/query.py +118 -0
- factory_framework-0.3.1/src/ff/runner.py +239 -0
- factory_framework-0.3.1/src/ff/scaffold.py +239 -0
- factory_framework-0.3.1/src/ff/schemas.py +141 -0
- factory_framework-0.3.1/src/ff/skill/SKILL.md +47 -0
- factory_framework-0.3.1/src/ff/skill/references/authoring.md +59 -0
- factory_framework-0.3.1/src/ff/skill/references/checks.md +69 -0
- factory_framework-0.3.1/src/ff/skill/references/workflow.md +55 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Médéric Hurier (Fmind)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: factory-framework
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs.
|
|
5
|
+
Keywords: ai,ai-agents,agent-skills,agents-md,fitness-functions,local-first,mcp,model-context-protocol,python,software-engineering,software-factory,spec-driven-development,traceability
|
|
6
|
+
Author: Médéric Hurier
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: MacOS
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
17
|
+
Classifier: Topic :: Software Development :: Testing
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Dist: jsonschema>=4.26.0,<5
|
|
20
|
+
Requires-Dist: markdown>=3.11,<4
|
|
21
|
+
Requires-Dist: pyyaml>=6.0.3,<7
|
|
22
|
+
Requires-Dist: rich>=15.0.0,<16
|
|
23
|
+
Requires-Dist: mcp>=2.3,<3 ; extra == 'mcp'
|
|
24
|
+
Requires-Dist: pydantic>=2.14,<3 ; extra == 'mcp'
|
|
25
|
+
Requires-Dist: uvicorn>=0.54,<1 ; extra == 'mcp'
|
|
26
|
+
Requires-Dist: pytest>=9.1.1,<10 ; extra == 'pytest'
|
|
27
|
+
Requires-Python: >=3.14
|
|
28
|
+
Project-URL: Changelog, https://fmind.github.io/factory-framework/changelog/
|
|
29
|
+
Project-URL: Documentation, https://fmind.github.io/factory-framework/
|
|
30
|
+
Project-URL: Issues, https://github.com/fmind/factory-framework/issues
|
|
31
|
+
Project-URL: Repository, https://github.com/fmind/factory-framework
|
|
32
|
+
Project-URL: Security, https://github.com/fmind/factory-framework/security/policy
|
|
33
|
+
Provides-Extra: mcp
|
|
34
|
+
Provides-Extra: pytest
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<img
|
|
39
|
+
src="docs/assets/factory-framework.svg"
|
|
40
|
+
alt="Factory Framework mirrored F | F logo"
|
|
41
|
+
width="128"
|
|
42
|
+
height="128"
|
|
43
|
+
>
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
# Factory Framework
|
|
47
|
+
|
|
48
|
+
**Turn plain-Markdown requirements into proven software.**
|
|
49
|
+
|
|
50
|
+
[](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [](pyproject.toml) [](LICENSE)
|
|
51
|
+
|
|
52
|
+
Factory Framework (`ff`) connects human product goals to automated tests in plain files inside your repository. Product owners, engineers, and AI coding agents work from one source of truth, and proof reports come from real executions — never manual checkboxes.
|
|
53
|
+
|
|
54
|
+
[Overview](#overview) · [Benefits](#benefits) · [Installation](#installation) · [Usage](#usage) · [Example](#example) · [Documentation](#documentation)
|
|
55
|
+
|
|
56
|
+
## Overview
|
|
57
|
+
|
|
58
|
+
Teams lose alignment when requirements live in wikis, tests check implementation details instead of user outcomes, and nobody knows what is truly proven.
|
|
59
|
+
|
|
60
|
+
`ff` organizes every domain inside `factory/` with 1-to-1 file symmetry:
|
|
61
|
+
|
|
62
|
+
- **Intents** (`intents/<domain>.md`) capture **why** a capability matters for humans (User Stories recommended).
|
|
63
|
+
- **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended).
|
|
64
|
+
- **Checks** (`checks/<domain>.yaml` + `tests/*`) map specs and numeric bounds to real tests in any language.
|
|
65
|
+
- **Proofs** (`proofs/<domain>.json`) record digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
|
|
66
|
+
|
|
67
|
+
<p align="center">
|
|
68
|
+
<a href="docs/assets/how-it-works.png">
|
|
69
|
+
<img
|
|
70
|
+
src="docs/assets/how-it-works.png"
|
|
71
|
+
alt="How Factory Framework links Markdown intents and specs to parallel tests and domain proofs"
|
|
72
|
+
width="960"
|
|
73
|
+
>
|
|
74
|
+
</a>
|
|
75
|
+
</p>
|
|
76
|
+
|
|
77
|
+
## Benefits
|
|
78
|
+
|
|
79
|
+
- **Plain Markdown, zero clutter.** Write pure headings and prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically.
|
|
80
|
+
- **Computed verdicts you can trust.** A spec turns `PROVEN` only when its checks execute, exit `0`, and satisfy every metric bound declared in `checks/<domain>.yaml`.
|
|
81
|
+
- **Polyglot by default.** Run Python, Bash, Node.js, Java, Go, or Rust tests in parallel. Scripts can optionally write JSON metrics and evidence to `$FF_RECORD`, or keep using plain exit codes.
|
|
82
|
+
- **Change accountability built in.** Document contract shifts in `factory/changes/YYYY-MM-DD_<slug>.md` or labeled GitHub issues; `ff verify --base` blocks silent weakening of proven specs, checks, or thresholds.
|
|
83
|
+
- **Built for both humans and coding agents.** Export polished HTML, Markdown, CSV, or JSONL summaries with `ff export`, and equip agents with `/ff` (`ff skill install`) and optional read-only `ff mcp`.
|
|
84
|
+
|
|
85
|
+
## Installation
|
|
86
|
+
|
|
87
|
+
Requires Python 3.14+ on Linux or macOS with [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
uv tool install --python 3.14 factory-framework
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Add optional extras when needed (`[pytest]` for pytest test-suite helpers, `[mcp]` for the read-only MCP server):
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
uv tool install --python 3.14 "factory-framework[pytest,mcp]"
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Usage
|
|
100
|
+
|
|
101
|
+
Scaffold a starter contract, run checks, verify reproducibility, and export a report:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
ff init --example # Add --pytest to scaffold pytest fixtures instead of a standalone script
|
|
105
|
+
ff run
|
|
106
|
+
ff status
|
|
107
|
+
ff verify --strict
|
|
108
|
+
ff export -f html -o proof-report.html
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Everyday commands at a glance:
|
|
112
|
+
|
|
113
|
+
- `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency starter check (or `pytest` fixtures with `--pytest`).
|
|
114
|
+
- `ff status` and `ff ls --tree` — inspect domain verdicts and trace links from intents to specs and checks.
|
|
115
|
+
- `ff show <id>` — read full statements, metric bounds, and latest recorded evidence for any item.
|
|
116
|
+
- `ff lint` and `ff verify` — check domain symmetry (`FF001`–`FF012`), re-run tests, and enforce `--base` anti-weakening rules (`FFR0`–`FFR4`).
|
|
117
|
+
- `ff export -f html|md|csv|jsonl` — share proof reports with stakeholders.
|
|
118
|
+
- `ff skill install` and `ff mcp` — equip coding agents with `/ff` workflow instructions and read-only contract inspection.
|
|
119
|
+
|
|
120
|
+
## Example
|
|
121
|
+
|
|
122
|
+
Suppose you want fast, accurate checkout pricing in domain `checkout`.
|
|
123
|
+
|
|
124
|
+
**1. State why in `factory/intents/checkout.md`:**
|
|
125
|
+
|
|
126
|
+
```markdown
|
|
127
|
+
# Checkout
|
|
128
|
+
|
|
129
|
+
## Fast Totals
|
|
130
|
+
|
|
131
|
+
As a shopper, I want accurate order totals immediately, so that slow pricing never delays my purchase.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**2. State what in `factory/specs/checkout.md`:**
|
|
135
|
+
|
|
136
|
+
```markdown
|
|
137
|
+
# Checkout
|
|
138
|
+
|
|
139
|
+
## Fast Totals
|
|
140
|
+
|
|
141
|
+
### Latency
|
|
142
|
+
|
|
143
|
+
Given a cart with regional shipping rules, when checkout totals are requested, then pricing, tax, and totals return in 50 ms or less.
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
**3. Declare bounds and check targets in `factory/checks/checkout.yaml`:**
|
|
147
|
+
|
|
148
|
+
```yaml
|
|
149
|
+
version: 1
|
|
150
|
+
domain: checkout
|
|
151
|
+
|
|
152
|
+
checks:
|
|
153
|
+
check_checkout_fast-totals_latency:
|
|
154
|
+
file: tests/check_checkout.py
|
|
155
|
+
metrics:
|
|
156
|
+
p95_ms: { max: 50, precision: 0, unit: ms }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**4. Prove it with a behavioral check in `factory/tests/check_checkout.py`:**
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
import json, os
|
|
163
|
+
from pathlib import Path
|
|
164
|
+
|
|
165
|
+
elapsed_ms, body = call_checkout(items=3, region="EU")
|
|
166
|
+
assert body["tax"] > 0 and body["total"] > body["subtotal"]
|
|
167
|
+
|
|
168
|
+
if record_path := os.environ.get("FF_RECORD"):
|
|
169
|
+
Path(record_path).write_text(
|
|
170
|
+
json.dumps(
|
|
171
|
+
{
|
|
172
|
+
"summary": "Checkout returned tax and totals under 50 ms",
|
|
173
|
+
"metrics": {"p95_ms": elapsed_ms},
|
|
174
|
+
"evidence": [f"p95_ms={elapsed_ms}", f"total={body['total']}"],
|
|
175
|
+
}
|
|
176
|
+
),
|
|
177
|
+
encoding="utf-8",
|
|
178
|
+
)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Using Bash, JavaScript, Go, Java, or `pytest`? Point `file:` at `.sh`/`.mjs`/`.js` scripts, use `argv: [go, test, ./...]` for compiled binaries, or pass `--pytest` on `ff init` for `ff_record` pytest fixtures.
|
|
182
|
+
|
|
183
|
+
**5. Run and inspect the verdict:**
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
ff run
|
|
187
|
+
ff status
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
Factory: shop-api | Proofs: fresh | Gate: PASSED
|
|
192
|
+
Intents: 1/1 proven | Specs: 1/1 proven | Checks: 1/1 passing
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Explore [`examples/demo-service/`](examples/demo-service/README.md) for a multi-domain `pytest` + Bash project and [`examples/checks/`](examples/checks/) for reusable check recipes.
|
|
196
|
+
|
|
197
|
+
## Documentation
|
|
198
|
+
|
|
199
|
+
- [Documentation home](docs/docs/index.md) — architecture overview and core principles
|
|
200
|
+
- [Getting started](docs/docs/getting-started.md) — installation, walkthrough, and `factory/` layout
|
|
201
|
+
- [Core concepts](docs/docs/concepts.md) — `<domain>` symmetry, leaf IDs, `$FF_RECORD`, proofs, and changes
|
|
202
|
+
- [Configuration](docs/docs/configuration.md) — `factory/ff.yaml`, `factory/checks/<domain>.yaml`, and polyglot runners
|
|
203
|
+
- [Commands](docs/docs/commands.md) — full CLI reference, rules (`FF001`–`FF012`, `FFR0`–`FFR4`), schemas, and MCP
|
|
204
|
+
- [Workflow](docs/docs/workflow.md) — daily loop, `--base` CI gates, exports, and `/ff` agent setup
|
|
205
|
+
- [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [LICENSE](LICENSE)
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img
|
|
3
|
+
src="docs/assets/factory-framework.svg"
|
|
4
|
+
alt="Factory Framework mirrored F | F logo"
|
|
5
|
+
width="128"
|
|
6
|
+
height="128"
|
|
7
|
+
>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
# Factory Framework
|
|
11
|
+
|
|
12
|
+
**Turn plain-Markdown requirements into proven software.**
|
|
13
|
+
|
|
14
|
+
[](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [](pyproject.toml) [](LICENSE)
|
|
15
|
+
|
|
16
|
+
Factory Framework (`ff`) connects human product goals to automated tests in plain files inside your repository. Product owners, engineers, and AI coding agents work from one source of truth, and proof reports come from real executions — never manual checkboxes.
|
|
17
|
+
|
|
18
|
+
[Overview](#overview) · [Benefits](#benefits) · [Installation](#installation) · [Usage](#usage) · [Example](#example) · [Documentation](#documentation)
|
|
19
|
+
|
|
20
|
+
## Overview
|
|
21
|
+
|
|
22
|
+
Teams lose alignment when requirements live in wikis, tests check implementation details instead of user outcomes, and nobody knows what is truly proven.
|
|
23
|
+
|
|
24
|
+
`ff` organizes every domain inside `factory/` with 1-to-1 file symmetry:
|
|
25
|
+
|
|
26
|
+
- **Intents** (`intents/<domain>.md`) capture **why** a capability matters for humans (User Stories recommended).
|
|
27
|
+
- **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended).
|
|
28
|
+
- **Checks** (`checks/<domain>.yaml` + `tests/*`) map specs and numeric bounds to real tests in any language.
|
|
29
|
+
- **Proofs** (`proofs/<domain>.json`) record digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<a href="docs/assets/how-it-works.png">
|
|
33
|
+
<img
|
|
34
|
+
src="docs/assets/how-it-works.png"
|
|
35
|
+
alt="How Factory Framework links Markdown intents and specs to parallel tests and domain proofs"
|
|
36
|
+
width="960"
|
|
37
|
+
>
|
|
38
|
+
</a>
|
|
39
|
+
</p>
|
|
40
|
+
|
|
41
|
+
## Benefits
|
|
42
|
+
|
|
43
|
+
- **Plain Markdown, zero clutter.** Write pure headings and prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically.
|
|
44
|
+
- **Computed verdicts you can trust.** A spec turns `PROVEN` only when its checks execute, exit `0`, and satisfy every metric bound declared in `checks/<domain>.yaml`.
|
|
45
|
+
- **Polyglot by default.** Run Python, Bash, Node.js, Java, Go, or Rust tests in parallel. Scripts can optionally write JSON metrics and evidence to `$FF_RECORD`, or keep using plain exit codes.
|
|
46
|
+
- **Change accountability built in.** Document contract shifts in `factory/changes/YYYY-MM-DD_<slug>.md` or labeled GitHub issues; `ff verify --base` blocks silent weakening of proven specs, checks, or thresholds.
|
|
47
|
+
- **Built for both humans and coding agents.** Export polished HTML, Markdown, CSV, or JSONL summaries with `ff export`, and equip agents with `/ff` (`ff skill install`) and optional read-only `ff mcp`.
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
Requires Python 3.14+ on Linux or macOS with [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
uv tool install --python 3.14 factory-framework
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Add optional extras when needed (`[pytest]` for pytest test-suite helpers, `[mcp]` for the read-only MCP server):
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
uv tool install --python 3.14 "factory-framework[pytest,mcp]"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Usage
|
|
64
|
+
|
|
65
|
+
Scaffold a starter contract, run checks, verify reproducibility, and export a report:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
ff init --example # Add --pytest to scaffold pytest fixtures instead of a standalone script
|
|
69
|
+
ff run
|
|
70
|
+
ff status
|
|
71
|
+
ff verify --strict
|
|
72
|
+
ff export -f html -o proof-report.html
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Everyday commands at a glance:
|
|
76
|
+
|
|
77
|
+
- `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency starter check (or `pytest` fixtures with `--pytest`).
|
|
78
|
+
- `ff status` and `ff ls --tree` — inspect domain verdicts and trace links from intents to specs and checks.
|
|
79
|
+
- `ff show <id>` — read full statements, metric bounds, and latest recorded evidence for any item.
|
|
80
|
+
- `ff lint` and `ff verify` — check domain symmetry (`FF001`–`FF012`), re-run tests, and enforce `--base` anti-weakening rules (`FFR0`–`FFR4`).
|
|
81
|
+
- `ff export -f html|md|csv|jsonl` — share proof reports with stakeholders.
|
|
82
|
+
- `ff skill install` and `ff mcp` — equip coding agents with `/ff` workflow instructions and read-only contract inspection.
|
|
83
|
+
|
|
84
|
+
## Example
|
|
85
|
+
|
|
86
|
+
Suppose you want fast, accurate checkout pricing in domain `checkout`.
|
|
87
|
+
|
|
88
|
+
**1. State why in `factory/intents/checkout.md`:**
|
|
89
|
+
|
|
90
|
+
```markdown
|
|
91
|
+
# Checkout
|
|
92
|
+
|
|
93
|
+
## Fast Totals
|
|
94
|
+
|
|
95
|
+
As a shopper, I want accurate order totals immediately, so that slow pricing never delays my purchase.
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**2. State what in `factory/specs/checkout.md`:**
|
|
99
|
+
|
|
100
|
+
```markdown
|
|
101
|
+
# Checkout
|
|
102
|
+
|
|
103
|
+
## Fast Totals
|
|
104
|
+
|
|
105
|
+
### Latency
|
|
106
|
+
|
|
107
|
+
Given a cart with regional shipping rules, when checkout totals are requested, then pricing, tax, and totals return in 50 ms or less.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**3. Declare bounds and check targets in `factory/checks/checkout.yaml`:**
|
|
111
|
+
|
|
112
|
+
```yaml
|
|
113
|
+
version: 1
|
|
114
|
+
domain: checkout
|
|
115
|
+
|
|
116
|
+
checks:
|
|
117
|
+
check_checkout_fast-totals_latency:
|
|
118
|
+
file: tests/check_checkout.py
|
|
119
|
+
metrics:
|
|
120
|
+
p95_ms: { max: 50, precision: 0, unit: ms }
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**4. Prove it with a behavioral check in `factory/tests/check_checkout.py`:**
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import json, os
|
|
127
|
+
from pathlib import Path
|
|
128
|
+
|
|
129
|
+
elapsed_ms, body = call_checkout(items=3, region="EU")
|
|
130
|
+
assert body["tax"] > 0 and body["total"] > body["subtotal"]
|
|
131
|
+
|
|
132
|
+
if record_path := os.environ.get("FF_RECORD"):
|
|
133
|
+
Path(record_path).write_text(
|
|
134
|
+
json.dumps(
|
|
135
|
+
{
|
|
136
|
+
"summary": "Checkout returned tax and totals under 50 ms",
|
|
137
|
+
"metrics": {"p95_ms": elapsed_ms},
|
|
138
|
+
"evidence": [f"p95_ms={elapsed_ms}", f"total={body['total']}"],
|
|
139
|
+
}
|
|
140
|
+
),
|
|
141
|
+
encoding="utf-8",
|
|
142
|
+
)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Using Bash, JavaScript, Go, Java, or `pytest`? Point `file:` at `.sh`/`.mjs`/`.js` scripts, use `argv: [go, test, ./...]` for compiled binaries, or pass `--pytest` on `ff init` for `ff_record` pytest fixtures.
|
|
146
|
+
|
|
147
|
+
**5. Run and inspect the verdict:**
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
ff run
|
|
151
|
+
ff status
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
Factory: shop-api | Proofs: fresh | Gate: PASSED
|
|
156
|
+
Intents: 1/1 proven | Specs: 1/1 proven | Checks: 1/1 passing
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Explore [`examples/demo-service/`](examples/demo-service/README.md) for a multi-domain `pytest` + Bash project and [`examples/checks/`](examples/checks/) for reusable check recipes.
|
|
160
|
+
|
|
161
|
+
## Documentation
|
|
162
|
+
|
|
163
|
+
- [Documentation home](docs/docs/index.md) — architecture overview and core principles
|
|
164
|
+
- [Getting started](docs/docs/getting-started.md) — installation, walkthrough, and `factory/` layout
|
|
165
|
+
- [Core concepts](docs/docs/concepts.md) — `<domain>` symmetry, leaf IDs, `$FF_RECORD`, proofs, and changes
|
|
166
|
+
- [Configuration](docs/docs/configuration.md) — `factory/ff.yaml`, `factory/checks/<domain>.yaml`, and polyglot runners
|
|
167
|
+
- [Commands](docs/docs/commands.md) — full CLI reference, rules (`FF001`–`FF012`, `FFR0`–`FFR4`), schemas, and MCP
|
|
168
|
+
- [Workflow](docs/docs/workflow.md) — daily loop, `--base` CI gates, exports, and `/ff` agent setup
|
|
169
|
+
- [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [LICENSE](LICENSE)
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "factory-framework"
|
|
3
|
+
version = "0.3.1"
|
|
4
|
+
description = "Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.14"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
keywords = [
|
|
10
|
+
"ai",
|
|
11
|
+
"ai-agents",
|
|
12
|
+
"agent-skills",
|
|
13
|
+
"agents-md",
|
|
14
|
+
"fitness-functions",
|
|
15
|
+
"local-first",
|
|
16
|
+
"mcp",
|
|
17
|
+
"model-context-protocol",
|
|
18
|
+
"python",
|
|
19
|
+
"software-engineering",
|
|
20
|
+
"software-factory",
|
|
21
|
+
"spec-driven-development",
|
|
22
|
+
"traceability",
|
|
23
|
+
]
|
|
24
|
+
classifiers = [
|
|
25
|
+
"Development Status :: 3 - Alpha",
|
|
26
|
+
"Environment :: Console",
|
|
27
|
+
"Intended Audience :: Developers",
|
|
28
|
+
"Operating System :: MacOS",
|
|
29
|
+
"Operating System :: POSIX :: Linux",
|
|
30
|
+
"Programming Language :: Python :: 3",
|
|
31
|
+
"Programming Language :: Python :: 3.14",
|
|
32
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
33
|
+
"Topic :: Software Development :: Testing",
|
|
34
|
+
"Typing :: Typed",
|
|
35
|
+
]
|
|
36
|
+
dependencies = [
|
|
37
|
+
"jsonschema>=4.26.0,<5",
|
|
38
|
+
"markdown>=3.11,<4",
|
|
39
|
+
"pyyaml>=6.0.3,<7",
|
|
40
|
+
"rich>=15.0.0,<16",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[[project.authors]]
|
|
44
|
+
name = "Médéric Hurier"
|
|
45
|
+
|
|
46
|
+
[project.optional-dependencies]
|
|
47
|
+
mcp = [
|
|
48
|
+
"mcp>=2.3,<3",
|
|
49
|
+
"pydantic>=2.14,<3",
|
|
50
|
+
"uvicorn>=0.54,<1",
|
|
51
|
+
]
|
|
52
|
+
pytest = ["pytest>=9.1.1,<10"]
|
|
53
|
+
|
|
54
|
+
[project.urls]
|
|
55
|
+
Changelog = "https://fmind.github.io/factory-framework/changelog/"
|
|
56
|
+
Documentation = "https://fmind.github.io/factory-framework/"
|
|
57
|
+
Issues = "https://github.com/fmind/factory-framework/issues"
|
|
58
|
+
Repository = "https://github.com/fmind/factory-framework"
|
|
59
|
+
Security = "https://github.com/fmind/factory-framework/security/policy"
|
|
60
|
+
|
|
61
|
+
[project.scripts]
|
|
62
|
+
ff = "ff:main"
|
|
63
|
+
|
|
64
|
+
[build-system]
|
|
65
|
+
requires = ["uv_build>=0.12.10,<0.14"]
|
|
66
|
+
build-backend = "uv_build"
|
|
67
|
+
|
|
68
|
+
[tool.uv.build-backend]
|
|
69
|
+
module-name = "ff"
|
|
70
|
+
|
|
71
|
+
[tool.ruff]
|
|
72
|
+
line-length = 120
|
|
73
|
+
src = [
|
|
74
|
+
"src",
|
|
75
|
+
"tests",
|
|
76
|
+
]
|
|
77
|
+
extend-exclude = ["*.md"]
|
|
78
|
+
|
|
79
|
+
[tool.ruff.per-file-target-version]
|
|
80
|
+
"examples/**/*.py" = "py314"
|
|
81
|
+
"factory/**/*.py" = "py314"
|
|
82
|
+
|
|
83
|
+
[tool.ruff.format]
|
|
84
|
+
docstring-code-format = true
|
|
85
|
+
line-ending = "lf"
|
|
86
|
+
quote-style = "double"
|
|
87
|
+
|
|
88
|
+
[tool.ruff.lint]
|
|
89
|
+
select = [
|
|
90
|
+
"A",
|
|
91
|
+
"ARG",
|
|
92
|
+
"ASYNC",
|
|
93
|
+
"B",
|
|
94
|
+
"BLE",
|
|
95
|
+
"C4",
|
|
96
|
+
"E",
|
|
97
|
+
"ERA",
|
|
98
|
+
"F",
|
|
99
|
+
"FA",
|
|
100
|
+
"FURB",
|
|
101
|
+
"I",
|
|
102
|
+
"ISC",
|
|
103
|
+
"LOG",
|
|
104
|
+
"N",
|
|
105
|
+
"PERF",
|
|
106
|
+
"PGH",
|
|
107
|
+
"PIE",
|
|
108
|
+
"PLE",
|
|
109
|
+
"PLW",
|
|
110
|
+
"PT",
|
|
111
|
+
"PTH",
|
|
112
|
+
"Q",
|
|
113
|
+
"RET",
|
|
114
|
+
"RSE",
|
|
115
|
+
"RUF",
|
|
116
|
+
"S",
|
|
117
|
+
"SIM",
|
|
118
|
+
"SLF",
|
|
119
|
+
"T10",
|
|
120
|
+
"T20",
|
|
121
|
+
"TID",
|
|
122
|
+
"UP",
|
|
123
|
+
"W",
|
|
124
|
+
]
|
|
125
|
+
ignore = [
|
|
126
|
+
"ASYNC240",
|
|
127
|
+
"E501",
|
|
128
|
+
"PLW0108",
|
|
129
|
+
"PLW2901",
|
|
130
|
+
]
|
|
131
|
+
|
|
132
|
+
[tool.ruff.lint.per-file-ignores]
|
|
133
|
+
"examples/**" = [
|
|
134
|
+
"S101",
|
|
135
|
+
"S603",
|
|
136
|
+
"S607",
|
|
137
|
+
"T201",
|
|
138
|
+
]
|
|
139
|
+
"factory/**" = [
|
|
140
|
+
"S101",
|
|
141
|
+
"S603",
|
|
142
|
+
"S607",
|
|
143
|
+
"T201",
|
|
144
|
+
]
|
|
145
|
+
"scripts/**" = [
|
|
146
|
+
"S101",
|
|
147
|
+
"S603",
|
|
148
|
+
"S607",
|
|
149
|
+
"T201",
|
|
150
|
+
]
|
|
151
|
+
"tests/**" = [
|
|
152
|
+
"BLE001",
|
|
153
|
+
"S101",
|
|
154
|
+
"T201",
|
|
155
|
+
]
|
|
156
|
+
|
|
157
|
+
[tool.ty.rules]
|
|
158
|
+
blanket-ignore-comment = "error"
|
|
159
|
+
|
|
160
|
+
[tool.deptry]
|
|
161
|
+
known_first_party = ["ff"]
|
|
162
|
+
|
|
163
|
+
[tool.deptry.per_rule_ignores]
|
|
164
|
+
DEP002 = ["pytest"]
|
|
165
|
+
|
|
166
|
+
[tool.pytest]
|
|
167
|
+
addopts = ["-ra"]
|
|
168
|
+
faulthandler_timeout = "300"
|
|
169
|
+
faulthandler_exit_on_timeout = true
|
|
170
|
+
filterwarnings = ["error"]
|
|
171
|
+
strict = true
|
|
172
|
+
testpaths = ["tests"]
|
|
173
|
+
norecursedirs = [
|
|
174
|
+
".*",
|
|
175
|
+
"build",
|
|
176
|
+
"dist",
|
|
177
|
+
"fixtures",
|
|
178
|
+
]
|
|
179
|
+
|
|
180
|
+
[tool.coverage.run]
|
|
181
|
+
branch = true
|
|
182
|
+
source = ["ff"]
|
|
183
|
+
omit = ["*/ff/skill/*"]
|
|
184
|
+
patch = ["subprocess"]
|
|
185
|
+
|
|
186
|
+
[tool.coverage.report]
|
|
187
|
+
fail_under = 95
|
|
188
|
+
show_missing = true
|
|
189
|
+
skip_covered = true
|
|
190
|
+
skip_empty = true
|
|
191
|
+
|
|
192
|
+
[dependency-groups]
|
|
193
|
+
dev = [
|
|
194
|
+
"deptry>=0.25.1",
|
|
195
|
+
"mcp>=2.3,<3",
|
|
196
|
+
"pydantic>=2.14,<3",
|
|
197
|
+
"pytest-cov>=7.1.0",
|
|
198
|
+
"pytest-xdist>=3.8.0",
|
|
199
|
+
"pytest>=9.1.1",
|
|
200
|
+
"ruff>=0.16.6",
|
|
201
|
+
"ty>=0.0.70,<0.1",
|
|
202
|
+
"uvicorn>=0.54,<1",
|
|
203
|
+
"validate-pyproject[all]>=0.25",
|
|
204
|
+
"zensical>=0.1.0,<0.2",
|
|
205
|
+
]
|