fde-framework 0.1.45__tar.gz → 0.1.46__tar.gz

{fde_framework-0.1.45 → fde_framework-0.1.46}/CHANGELOG.md

@@ -5,6 +5,51 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.46] — 2026-10-12
+
+Three readings in a row asked for the same thing before anything else:
+the decision, as a document a person who never sees the terminal can act
+on. Writing it exposed one more place the record was reading the wrong
+build.
+
+- **`fde report`: the decision brief.** One Markdown file read off the
+  record, before any build is authorised: the problem as the client
+  stated it, where the engagement stands, what the record knows and who
+  said it, the outcome contract, the design with its reasons and rejected
+  alternatives, what it rests on and what was waived, the decision debt,
+  the stop conditions judged against what has been measured, who has been
+  heard, and the next decision. The design and the risks are rendered by
+  the same functions a build uses for ARCHITECTURE.md and RISKS.md, so
+  the brief and a later build say the same thing; the readings that are
+  commands are quoted as the terminal prints them, so the brief cannot
+  say more than the commands do. Nothing in it is estimated. `--today`
+  makes it reproducible to the byte.
+- **The deployment names its build, and the record reads that build.**
+  The banking record, read without `--project`, stood at *stopped*: its
+  last-built marker named the emitted project, whose card is 0.879 on
+  the answered, while the implemented copy beside it -- the one actually
+  served, 0.902 -- passed. `fde deployed --project` records which build
+  was deployed, and every command that reads a project by default reads
+  the deployed one, then the last one built. Refused for a directory that
+  is not an emitted project.
+- **The README's front page answers three questions.** What this is, why
+  use it, how fast a result shows. The audit-pass story and the
+  thirty-line list of what every emission is held to moved verbatim to
+  `HISTORY.md`; the four demos are one line each, saying what each
+  proved. The claim ladder and the demo table are unchanged.
+- **The pictures say what the code says.** The README banner and the
+  social-preview card had carried "seven gates" since before the eighth
+  gate shipped in 0.1.30, drawn once by hand; a fourteenth outside
+  reading found the banner contradicting the README it headed. They are
+  now drawn by `assets/brand.py` from the gate count the gates module
+  reports, each image carries its sentence in a PNG text chunk, and a
+  test holds the pictures to the code. The site's image alt text said the
+  same; corrected.
+- The demo table says what *Stage* is: the record's lifecycle stage,
+  computed from evidence, so `production` on the banking row means
+  deployed, attested and journalled -- on a laptop, as the record says --
+  not production reliability, which the claim ladder keeps unverified.
+
 ## [0.1.45] — 2026-10-11
 
 A twelfth outside reading, and a coding agent driving the server for the

{fde_framework-0.1.45 → fde_framework-0.1.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.45
+Version: 0.1.46
 Summary: The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist.
 Project-URL: Homepage, https://github.com/atulkapoor/fde-framework
 Project-URL: Documentation, https://atulkapoor.github.io/fde-framework/
@@ -31,6 +31,7 @@ Requires-Dist: pypdf>=4; extra == 'all'
 Requires-Dist: python-docx>=1; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mcp<3,>=2; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: documents
@@ -89,6 +90,7 @@ pip install fde-framework
 fde start acme --statement "Extract fields from supplier invoices."
 fde ask acme --role admin        # role-scoped discovery interview
 fde architect acme               # topology + chosen approaches (rationale lands in ARCHITECTURE.md)
+fde report acme                  # the decision brief, for whoever has to act on it and is not here
 fde build acme --out project     # refuses: eight gates guard the build
 # ...verify data access, capture the baseline, name the eval owner (each gate prints its remedy), then:
 fde build acme --out project     # code + evals + deploy assets + runbook
@@ -241,7 +243,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
+| The framework is implemented | verified | 1,321 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |
@@ -251,54 +253,30 @@ ladder, so nothing here can be over-read:
 
 **Demonstrated**: four complete engagements have run end to end on real
 data, all public with every refusal preserved.
-[fde-demo-receipts](https://github.com/atulkapoor/fde-demo-receipts) —
-626 scanned receipts through gates, build, and an agent-driven implement
-loop (`fde implement`, graded against held-out cases the agent never sees)
-whose holdout refused an overfit implementation and whose measured plateau
-flipped the design from rules to a model, reason on the record.
-[fde-demo-complaints](https://github.com/atulkapoor/fde-demo-complaints) —
-2,034 real consumer complaints through the decision shape: the exam
-refused ambiguous ground truth before it existed, the agent posture was
-decided from the facts, and the loop finished **green with the holdout
-passing** — the framework's first.
-[fde-demo-rfc-qa](https://github.com/atulkapoor/fde-demo-rfc-qa) —
-freeform QA over 58 real RFCs: 100% recall@10 on real queries, a green
-loop, and then the calibration gate **refusing its own judge** exactly as
-the prediction published beforehand said it would (73.7% agreement,
-refused; the judge's 89.5% was 26 points of flattery over the hand-graded
-63.2%). Six of this framework's releases (0.1.6–0.1.11) shipped from what
-these runs found -- and after five independent audit passes reshaped the
-emitter (0.1.17–0.1.21), the complaints engagement was built and implemented
-again on 0.1.21: green in round 2, holdout 76.7% against the original's
-63.3%, the run committed beside the original for comparison. A sixth pass,
-widened to the exam, the components and the fine-tuning path, signed off
-the freeform shape with conditions and refused the decision shape for
-reasons that were the generator's; 0.1.22 answered each as a check first.
-A seventh pass found those checks holding and the shape-specific work
-stopping short -- a mis-specified baseline, an in-sample exam, a training
-recipe that trained unshuffled on a prompt it never served -- and 0.1.23
-answered again the same way. 0.1.24 then ran the fine-tuning recipe for
-real on a small base model: the adapter learned the house style on cases
-it never saw, and the six defects that run exposed in the harness, the
-serving path and the comparison are fixed and pinned. An eighth pass gave
-the decision shape its first sign-off, with conditions, and 0.1.25 met
-them: probes on typical cases, label phrases rather than words, a merge
-path that trains, a comparison that says what it can claim. A ninth pass
-read the first industry run and the scorecard that measured it, and found
-the card measuring self-consistency rather than fitness; 0.1.27 gave it
-fitness rows -- the generalisation gap, an external exam a memoriser cannot
-pass, the engagement's own error-rate bar -- and gave the routed decision
-an abstain path and a reason on every answer.
-[fde-demo-banking](https://github.com/atulkapoor/fde-demo-banking) —
-an industry use case: support intent routing for a retail bank over
-13,083 real messages and seventy-seven queues (Banking77). The framework's
-own reading of a seventy-seven-way decision, its brief parser, its label
-rule and one governance template each failed on it and were fixed before
-a number was quoted; the finished deliverable is an assist-mode router
-that abstains and says why, at 90.2% on what it routes with 18% handed to
-a person, scored on a 3,036-case holdout and the vendor's own test split,
-with `fde scorecard` saying which rows measure fitness and which measure
-self-consistency.
+
+- [fde-demo-receipts](https://github.com/atulkapoor/fde-demo-receipts) --
+  626 scanned receipts: the holdout refused an overfit implementation, and
+  a measured plateau flipped the design from rules to a model, reason on
+  the record.
+- [fde-demo-complaints](https://github.com/atulkapoor/fde-demo-complaints) --
+  2,034 real consumer complaints through the decision shape: the exam
+  refused ambiguous ground truth before it existed, and the loop finished
+  **green with the holdout passing**, the framework's first.
+- [fde-demo-rfc-qa](https://github.com/atulkapoor/fde-demo-rfc-qa) --
+  freeform QA over 58 real RFCs: 100% recall@10 on real queries, then the
+  calibration gate **refusing its own judge** exactly as the prediction
+  published beforehand said it would (73.7% agreement, refused; the
+  judge's 89.5% was 26 points of flattery over the hand-graded 63.2%).
+- [fde-demo-banking](https://github.com/atulkapoor/fde-demo-banking) --
+  an industry use case: support intent routing for a retail bank over
+  13,083 real messages and seventy-seven queues. The finished deliverable
+  is an assist-mode router that abstains and says why, at 90.2% on what
+  it routes with 18% handed to a person, scored on a 3,036-case holdout
+  and the vendor's own test split.
+
+Fourteen outside readings have shaped the releases since, each finding
+pinned as a check before it was fixed; the story, pass by pass, is in
+[`HISTORY.md`](https://github.com/atulkapoor/fde-framework/blob/main/HISTORY.md).
 
 **Built**: the pipeline exists end to end — intake (prose, documents, sample
 pairs, role-scoped interview, hardware scan) → fact log with provenance →
@@ -344,6 +322,13 @@ drill).
 | rfc-qa | prototype | 16/23 | 30.0% on 10 | 30.0% | -- |
 | banking | production (a laptop, attested as such; stopped once by its own stop condition, cleared at the shipped 1.0-nat margin) | 23/25; does not beat the bank's baseline, on coverage | 73.8% on 3,036, abstaining 18.2% | 90.2% | 71.6% on 3,079 |
 
+*Stage* is the record's lifecycle stage, computed from its evidence by
+`fde stage`. `production` means the build was deployed and attested by
+name and the field has been journalled through it -- here on a laptop, as
+the record says -- not that production reliability is proven; the claim
+ladder above keeps that unverified until a client's production says
+otherwise.
+
 ## Two rules
 
 Every intake surface — prose, interviews, scans, sample pairs, the client's
@@ -481,31 +466,12 @@ project/
 
 Emitted quality is a pinned property, not a promise: the framework's own
 test suite emits projects across representative architecture shapes and
-holds every emission to the operational contract — every environment
-variable the code reads is documented, everything the systemd unit demands
-is created by a shipped installer, CI has a lane that goes green without a
-model, the smoke test passes on a fresh emission, the code is lint-clean,
-the payload path composes end to end and refuses garbage at the door, a
-caller cannot forge a result, a hostile document or a long query costs
-milliseconds, the journal stays one JSON line per event under threads, an
-error closes its connection, a bad corpus file is skipped and counted, the
-boundary refuses an endpoint outside it, the ledger survives a restart and
-a torn line, a stopword cannot cite a document and a one-document corpus
-still answers, compaction cannot drop a live key, every eval entry point
-honours the boundary, an oversized corpus refuses the boot with one line,
-readiness degrades rather than denies on a stray file, and the service
-carries a request id on every answer, a truncated query is never a silent
-miss, two processes cannot both reserve one key, a decision read off
-labelled text ships a fitted classifier that refuses to serve a constant,
-refuses an exam that changed since the build, beats the majority on the
-holdout and says which of its scores are in-sample, the exam's probes and
-edges come from cases the baseline was not fitted on and each steering
-probe says what it steers toward, an uncalibrated judge is red until asked
-for by name, a fact learned from a person is marked asserted rather than
-established, and a fine-tuning decision ships a recipe that trains on the
-prompt it serves -- and the deliverable ships its own edge tests, which
-its CI runs. Eight independent audit passes took it from "every request
-500s" to a sign-off with conditions on the decision shape. A quality finding lands there as a check before
+holds every emission to the operational contract, from every environment
+variable the code reads being documented to a classifier that refuses to
+serve a constant; the full list of what is held, and the audit passes that
+put each check there, is in
+[`HISTORY.md`](https://github.com/atulkapoor/fde-framework/blob/main/HISTORY.md).
+A quality finding lands there as a check before
 it lands anywhere as a fix ([`tests/test_acceptance.py`](tests/test_acceptance.py),
 [`tests/test_finetune.py`](tests/test_finetune.py)). And the claim is
 measurable per build: `fde scorecard <project> --holdout <file> --external
@@ -538,9 +504,10 @@ declared by the tool.
   the holdout row, hours and money from the recorded baseline, build and run
   costs from the caller, payback, and a Wilson interval on the accuracy.
   Every line says what it rests on, so the number is argued row by row.
-- **`fde deployed`** and **`fde outcome`** are attestations: where it runs and
-  who put it there; adoption, time to first value, whatever the client
-  measured. **`fde outcomes`** prints what the record shows without anyone's
+- **`fde deployed`** and **`fde outcome`** are attestations: where it runs,
+  who put it there and which build it is (`--project`, which every command
+  that reads a project by default then reads); adoption, time to first
+  value, whatever the client measured. **`fde outcomes`** prints what the record shows without anyone's
   opinion -- transitions, days to pilot, loop rounds, reversals, incidents.
 - **`fde stakeholders`** maps the engagement's people as the record shows
   them: which of the five roles has been heard (every session carries the
@@ -656,7 +623,7 @@ fde implement project                # drive a coding agent until it's green
 fde scorecard project --holdout engagements/acme/artifacts/holdout.jsonl   # measure it
 
 fde stage acme --project project     # where it stands, computed off the record
-fde deployed acme --note "runs in the client VPC; platform team put it there"
+fde deployed acme --note "runs in the client VPC; platform team put it there" --project project
 fde drift acme --journal service.log --project project   # the field against the exam
 fde incident acme close inc-001 --note "holdout re-scored; pairs redrawn"
 fde outcome acme --metric adoption=0.62 --note "support lead's dashboard, week 3"
@@ -711,12 +678,13 @@ the same receipts the emitted `ARCHITECTURE.md` prints.
 | `fde reuse <eng> <stack>` | record what the client already operates, so reuse can beat adoption |
 | `fde locale <eng> eu-gdpr` | jurisdiction pack: presets plus obligations emitted as COMPLIANCE.md |
 | `fde architect <eng>` | the design, rationale and rejections |
+| `fde report <eng> [--out brief.md]` | the decision brief: the problem as stated, the stage, what is known and who said it, the outcome contract, the design with its reasons and rejections, what it rests on, the debt, the stop conditions, the next decision -- one Markdown file, before any build |
 | `fde build <eng> --out project` | emit; refuses while gates block |
 | `fde implement project/` | drive a coding agent until the emitted evals pass, inside guardrails |
 | `fde scorecard project/ --holdout <file>` | measure production grade: every property the deliverable can prove, with the number, in `SCORECARD.md` |
 | `fde scorecard project/ --holdout <file> --coverage-floor 0.97 --max-gap 0.08` | the engagement's own bars: the share the system must answer for the baseline row to hold (default: 1 minus the baseline's exception rate), and its limit on the golden-to-holdout gap (protocol default 20%) |
 | `fde stage <eng>` | where the engagement stands, computed from the record; transitions appended to `lifecycle.jsonl` (`--no-record` to look without appending) |
-| `fde deployed <eng> --note "..."` | attest the deployment: where it runs and who put it there |
+| `fde deployed <eng> --note "..." [--project <dir>]` | attest the deployment: where it runs, who put it there, which build |
 | `fde drift <eng> --journal <log>` | the field against the exam: abstention, mix, errors, margins; opens an incident and exits 1 when it moved |
 | `fde incident <eng> list \| close <id> --note "..."` | incidents on the record; an open one holds the stage at pilot |
 | `fde outcome <eng> --metric adoption=0.62` / `fde outcomes <eng>` | outcomes measured in the field; what the record shows without opinion |

{fde_framework-0.1.45 → fde_framework-0.1.46}/README.md

@@ -45,6 +45,7 @@ pip install fde-framework
 fde start acme --statement "Extract fields from supplier invoices."
 fde ask acme --role admin        # role-scoped discovery interview
 fde architect acme               # topology + chosen approaches (rationale lands in ARCHITECTURE.md)
+fde report acme                  # the decision brief, for whoever has to act on it and is not here
 fde build acme --out project     # refuses: eight gates guard the build
 # ...verify data access, capture the baseline, name the eval owner (each gate prints its remedy), then:
 fde build acme --out project     # code + evals + deploy assets + runbook
@@ -197,7 +198,7 @@ ladder, so nothing here can be over-read:
 
 | Claim | Status | The evidence, and where it stops |
 |---|---|---|
-| The framework is implemented | verified | 1,316 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
+| The framework is implemented | verified | 1,321 tests on three Pythons in CI; lint clean; every audit finding pinned as a check before it was fixed; every release installed from the published wheel into a fresh interpreter and walked through the first five minutes |
 | A build is reproducible | verified | byte-identical rebuild pinned by test; each public demo carries a Reproduce section and its digests |
 | The decisions generalise | partial | four shapes (extraction, freeform QA, a labelled decision, seventy-seven-way routing) on real data; one industry set; `fde kb sweep` names the shapes nothing serves |
 | The deliverable is production-reliable | unverified | no production engagement; the banking operating loop ran on a laptop and its record says so |
@@ -207,54 +208,30 @@ ladder, so nothing here can be over-read:
 
 **Demonstrated**: four complete engagements have run end to end on real
 data, all public with every refusal preserved.
-[fde-demo-receipts](https://github.com/atulkapoor/fde-demo-receipts) —
-626 scanned receipts through gates, build, and an agent-driven implement
-loop (`fde implement`, graded against held-out cases the agent never sees)
-whose holdout refused an overfit implementation and whose measured plateau
-flipped the design from rules to a model, reason on the record.
-[fde-demo-complaints](https://github.com/atulkapoor/fde-demo-complaints) —
-2,034 real consumer complaints through the decision shape: the exam
-refused ambiguous ground truth before it existed, the agent posture was
-decided from the facts, and the loop finished **green with the holdout
-passing** — the framework's first.
-[fde-demo-rfc-qa](https://github.com/atulkapoor/fde-demo-rfc-qa) —
-freeform QA over 58 real RFCs: 100% recall@10 on real queries, a green
-loop, and then the calibration gate **refusing its own judge** exactly as
-the prediction published beforehand said it would (73.7% agreement,
-refused; the judge's 89.5% was 26 points of flattery over the hand-graded
-63.2%). Six of this framework's releases (0.1.6–0.1.11) shipped from what
-these runs found -- and after five independent audit passes reshaped the
-emitter (0.1.17–0.1.21), the complaints engagement was built and implemented
-again on 0.1.21: green in round 2, holdout 76.7% against the original's
-63.3%, the run committed beside the original for comparison. A sixth pass,
-widened to the exam, the components and the fine-tuning path, signed off
-the freeform shape with conditions and refused the decision shape for
-reasons that were the generator's; 0.1.22 answered each as a check first.
-A seventh pass found those checks holding and the shape-specific work
-stopping short -- a mis-specified baseline, an in-sample exam, a training
-recipe that trained unshuffled on a prompt it never served -- and 0.1.23
-answered again the same way. 0.1.24 then ran the fine-tuning recipe for
-real on a small base model: the adapter learned the house style on cases
-it never saw, and the six defects that run exposed in the harness, the
-serving path and the comparison are fixed and pinned. An eighth pass gave
-the decision shape its first sign-off, with conditions, and 0.1.25 met
-them: probes on typical cases, label phrases rather than words, a merge
-path that trains, a comparison that says what it can claim. A ninth pass
-read the first industry run and the scorecard that measured it, and found
-the card measuring self-consistency rather than fitness; 0.1.27 gave it
-fitness rows -- the generalisation gap, an external exam a memoriser cannot
-pass, the engagement's own error-rate bar -- and gave the routed decision
-an abstain path and a reason on every answer.
-[fde-demo-banking](https://github.com/atulkapoor/fde-demo-banking) —
-an industry use case: support intent routing for a retail bank over
-13,083 real messages and seventy-seven queues (Banking77). The framework's
-own reading of a seventy-seven-way decision, its brief parser, its label
-rule and one governance template each failed on it and were fixed before
-a number was quoted; the finished deliverable is an assist-mode router
-that abstains and says why, at 90.2% on what it routes with 18% handed to
-a person, scored on a 3,036-case holdout and the vendor's own test split,
-with `fde scorecard` saying which rows measure fitness and which measure
-self-consistency.
+
+- [fde-demo-receipts](https://github.com/atulkapoor/fde-demo-receipts) --
+  626 scanned receipts: the holdout refused an overfit implementation, and
+  a measured plateau flipped the design from rules to a model, reason on
+  the record.
+- [fde-demo-complaints](https://github.com/atulkapoor/fde-demo-complaints) --
+  2,034 real consumer complaints through the decision shape: the exam
+  refused ambiguous ground truth before it existed, and the loop finished
+  **green with the holdout passing**, the framework's first.
+- [fde-demo-rfc-qa](https://github.com/atulkapoor/fde-demo-rfc-qa) --
+  freeform QA over 58 real RFCs: 100% recall@10 on real queries, then the
+  calibration gate **refusing its own judge** exactly as the prediction
+  published beforehand said it would (73.7% agreement, refused; the
+  judge's 89.5% was 26 points of flattery over the hand-graded 63.2%).
+- [fde-demo-banking](https://github.com/atulkapoor/fde-demo-banking) --
+  an industry use case: support intent routing for a retail bank over
+  13,083 real messages and seventy-seven queues. The finished deliverable
+  is an assist-mode router that abstains and says why, at 90.2% on what
+  it routes with 18% handed to a person, scored on a 3,036-case holdout
+  and the vendor's own test split.
+
+Fourteen outside readings have shaped the releases since, each finding
+pinned as a check before it was fixed; the story, pass by pass, is in
+[`HISTORY.md`](https://github.com/atulkapoor/fde-framework/blob/main/HISTORY.md).
 
 **Built**: the pipeline exists end to end — intake (prose, documents, sample
 pairs, role-scoped interview, hardware scan) → fact log with provenance →
@@ -300,6 +277,13 @@ drill).
 | rfc-qa | prototype | 16/23 | 30.0% on 10 | 30.0% | -- |
 | banking | production (a laptop, attested as such; stopped once by its own stop condition, cleared at the shipped 1.0-nat margin) | 23/25; does not beat the bank's baseline, on coverage | 73.8% on 3,036, abstaining 18.2% | 90.2% | 71.6% on 3,079 |
 
+*Stage* is the record's lifecycle stage, computed from its evidence by
+`fde stage`. `production` means the build was deployed and attested by
+name and the field has been journalled through it -- here on a laptop, as
+the record says -- not that production reliability is proven; the claim
+ladder above keeps that unverified until a client's production says
+otherwise.
+
 ## Two rules
 
 Every intake surface — prose, interviews, scans, sample pairs, the client's
@@ -437,31 +421,12 @@ project/
 
 Emitted quality is a pinned property, not a promise: the framework's own
 test suite emits projects across representative architecture shapes and
-holds every emission to the operational contract — every environment
-variable the code reads is documented, everything the systemd unit demands
-is created by a shipped installer, CI has a lane that goes green without a
-model, the smoke test passes on a fresh emission, the code is lint-clean,
-the payload path composes end to end and refuses garbage at the door, a
-caller cannot forge a result, a hostile document or a long query costs
-milliseconds, the journal stays one JSON line per event under threads, an
-error closes its connection, a bad corpus file is skipped and counted, the
-boundary refuses an endpoint outside it, the ledger survives a restart and
-a torn line, a stopword cannot cite a document and a one-document corpus
-still answers, compaction cannot drop a live key, every eval entry point
-honours the boundary, an oversized corpus refuses the boot with one line,
-readiness degrades rather than denies on a stray file, and the service
-carries a request id on every answer, a truncated query is never a silent
-miss, two processes cannot both reserve one key, a decision read off
-labelled text ships a fitted classifier that refuses to serve a constant,
-refuses an exam that changed since the build, beats the majority on the
-holdout and says which of its scores are in-sample, the exam's probes and
-edges come from cases the baseline was not fitted on and each steering
-probe says what it steers toward, an uncalibrated judge is red until asked
-for by name, a fact learned from a person is marked asserted rather than
-established, and a fine-tuning decision ships a recipe that trains on the
-prompt it serves -- and the deliverable ships its own edge tests, which
-its CI runs. Eight independent audit passes took it from "every request
-500s" to a sign-off with conditions on the decision shape. A quality finding lands there as a check before
+holds every emission to the operational contract, from every environment
+variable the code reads being documented to a classifier that refuses to
+serve a constant; the full list of what is held, and the audit passes that
+put each check there, is in
+[`HISTORY.md`](https://github.com/atulkapoor/fde-framework/blob/main/HISTORY.md).
+A quality finding lands there as a check before
 it lands anywhere as a fix ([`tests/test_acceptance.py`](tests/test_acceptance.py),
 [`tests/test_finetune.py`](tests/test_finetune.py)). And the claim is
 measurable per build: `fde scorecard <project> --holdout <file> --external
@@ -494,9 +459,10 @@ declared by the tool.
   the holdout row, hours and money from the recorded baseline, build and run
   costs from the caller, payback, and a Wilson interval on the accuracy.
   Every line says what it rests on, so the number is argued row by row.
-- **`fde deployed`** and **`fde outcome`** are attestations: where it runs and
-  who put it there; adoption, time to first value, whatever the client
-  measured. **`fde outcomes`** prints what the record shows without anyone's
+- **`fde deployed`** and **`fde outcome`** are attestations: where it runs,
+  who put it there and which build it is (`--project`, which every command
+  that reads a project by default then reads); adoption, time to first
+  value, whatever the client measured. **`fde outcomes`** prints what the record shows without anyone's
   opinion -- transitions, days to pilot, loop rounds, reversals, incidents.
 - **`fde stakeholders`** maps the engagement's people as the record shows
   them: which of the five roles has been heard (every session carries the
@@ -612,7 +578,7 @@ fde implement project                # drive a coding agent until it's green
 fde scorecard project --holdout engagements/acme/artifacts/holdout.jsonl   # measure it
 
 fde stage acme --project project     # where it stands, computed off the record
-fde deployed acme --note "runs in the client VPC; platform team put it there"
+fde deployed acme --note "runs in the client VPC; platform team put it there" --project project
 fde drift acme --journal service.log --project project   # the field against the exam
 fde incident acme close inc-001 --note "holdout re-scored; pairs redrawn"
 fde outcome acme --metric adoption=0.62 --note "support lead's dashboard, week 3"
@@ -667,12 +633,13 @@ the same receipts the emitted `ARCHITECTURE.md` prints.
 | `fde reuse <eng> <stack>` | record what the client already operates, so reuse can beat adoption |
 | `fde locale <eng> eu-gdpr` | jurisdiction pack: presets plus obligations emitted as COMPLIANCE.md |
 | `fde architect <eng>` | the design, rationale and rejections |
+| `fde report <eng> [--out brief.md]` | the decision brief: the problem as stated, the stage, what is known and who said it, the outcome contract, the design with its reasons and rejections, what it rests on, the debt, the stop conditions, the next decision -- one Markdown file, before any build |
 | `fde build <eng> --out project` | emit; refuses while gates block |
 | `fde implement project/` | drive a coding agent until the emitted evals pass, inside guardrails |
 | `fde scorecard project/ --holdout <file>` | measure production grade: every property the deliverable can prove, with the number, in `SCORECARD.md` |
 | `fde scorecard project/ --holdout <file> --coverage-floor 0.97 --max-gap 0.08` | the engagement's own bars: the share the system must answer for the baseline row to hold (default: 1 minus the baseline's exception rate), and its limit on the golden-to-holdout gap (protocol default 20%) |
 | `fde stage <eng>` | where the engagement stands, computed from the record; transitions appended to `lifecycle.jsonl` (`--no-record` to look without appending) |
-| `fde deployed <eng> --note "..."` | attest the deployment: where it runs and who put it there |
+| `fde deployed <eng> --note "..." [--project <dir>]` | attest the deployment: where it runs, who put it there, which build |
 | `fde drift <eng> --journal <log>` | the field against the exam: abstention, mix, errors, margins; opens an incident and exits 1 when it moved |
 | `fde incident <eng> list \| close <id> --note "..."` | incidents on the record; an open one holds the stage at pilot |
 | `fde outcome <eng> --metric adoption=0.62` / `fde outcomes <eng>` | outcomes measured in the field; what the record shows without opinion |

{fde_framework-0.1.45 → fde_framework-0.1.46}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name matches the repository and stays unique on any index;
 # the import package and the CLI command remain the short `fde`.
 name = "fde-framework"
-version = "0.1.45"
+version = "0.1.46"
 description = "The decision before the AI build: evidence in, an architecture with receipts out, a scored build or a stop. For Forward Deployed Engineers and anyone deciding whether an AI system should exist."
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -32,7 +32,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "ruff>=0.6", "mcp>=2,<3"]
+dev = ["pytest>=8", "ruff>=0.6", "mcp>=2,<3", "pillow>=10"]  # pillow draws assets/
 # Document readers are optional: plain-text intake needs nothing, and an
 # air-gapped install should not drag in what it will not use.
 documents = ["pypdf>=4", "python-docx>=1"]

{fde_framework-0.1.45 → fde_framework-0.1.46}/src/fde/cli.py

@@ -1894,10 +1894,16 @@ def scan_cmd(
 
 
 def _project_of(engagement, project: Path | None) -> Path | None:
-    """The project a command should read: the one given, else the last
-    build recorded by fde build."""
+    """The project a command should read: the one given, else the build the
+    deployment attestation names, else the last build recorded by fde
+    build. The banking record once read as stopped from its emitted build
+    while the implemented copy beside it, the one actually served, passed
+    its stop condition: the default followed the build, not the deployment."""
     if project is not None:
         return Path(project)
+    deployed = engagement.deployed_project()
+    if deployed and Path(deployed).exists():
+        return Path(deployed)
     record = engagement.root / ".last-out"
     if record.exists():
         candidate = Path(record.read_text().strip())
@@ -1943,17 +1949,27 @@ def stage_cmd(
 def deployed_cmd(
     root: Annotated[Path, typer.Argument(help="The engagement directory.")],
     note: Annotated[str, typer.Option(help="Where it runs and who put it there.")],
+    project: Annotated[Path | None, typer.Option(
+        "--project", help="The build that was deployed. Every command that reads a "
+        "project by default then reads this one, not the last one built."
+    )] = None,
     today: Annotated[str, typer.Option(help="For the record; defaults to today.")] = "",
     by: Annotated[str, typer.Option(help="Who signs this: a name for the record.")] = "",
 ) -> None:
-    """Attest that the deliverable is deployed. The lifecycle's production
-    stage reads this; nothing infers it from a build."""
+    """Attest that the deliverable is deployed, and which build it is. The
+    lifecycle's production stage reads this; nothing infers it from a build."""
     engagement = _engagement(root)
     if not note.strip():
         typer.echo("a deployment attestation needs a note", err=True)
         raise typer.Exit(1)
-    engagement.record_deployed(note, today or date.today().isoformat(), by=by)
-    typer.echo("deployment recorded")
+    if project is not None and not (project / "scorecard.json").exists() \
+            and not (project / "evals").is_dir():
+        typer.echo(f"{project}: not an emitted project (no evals/ and no scorecard.json)",
+                   err=True)
+        raise typer.Exit(1)
+    engagement.record_deployed(note, today or date.today().isoformat(), by=by,
+                               project=str(project) if project is not None else "")
+    typer.echo("deployment recorded" + (f" for {project}" if project is not None else ""))
 
 
 @app.command("drift")
@@ -2431,6 +2447,37 @@ def mcp_cmd(
         raise typer.Exit(1) from exc
 
 
+@app.command("report")
+def report_cmd(
+    root: Annotated[Path, typer.Argument(help="The engagement directory.")],
+    out: Annotated[Path | None, typer.Option(
+        "--out", help="Where to write the brief; default artifacts/REPORT.md in the engagement."
+    )] = None,
+    registry_root: Annotated[Path, typer.Option("--registry")] = DEFAULT_ROOT,
+    today: Annotated[str, typer.Option(help="The date on the brief; defaults to today.")] = "",
+) -> None:
+    """Write the decision brief: the problem as stated, where the engagement
+    stands, what the record knows and who said it, the outcome contract,
+    the design with its reasons, what it rests on, the decision debt, the
+    stop conditions, the next decision -- one Markdown file for the person
+    who has to act on the decision and is not at this terminal. Works
+    before any build is authorised; every figure is read off the record."""
+    from fde.report import render_report
+
+    registry = _registry(registry_root)
+    engagement = _engagement(root)
+    # The commands the brief quotes run in-process and get the registry as
+    # an absolute path, so the brief reads one corpus wherever it is run from.
+    corpus = Path(registry_root)
+    text = render_report(engagement, registry, corpus.resolve() if corpus.exists() else corpus,
+                         today=today)
+    target = out or (engagement.root / "artifacts" / "REPORT.md")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text)
+    sections = text.count("\n## ")
+    typer.echo(f"wrote {target} ({sections} sections, {len(text.splitlines())} lines)")
+
+
 @app.command("debt")
 def debt_cmd(
     root: Annotated[Path, typer.Argument(help="The engagement directory.")],

{fde_framework-0.1.45 → fde_framework-0.1.46}/src/fde/emit.py

@@ -139,13 +139,25 @@ def _write_risks(
     receiving the project could not tell that the baseline gate had been
     waived, let alone that the baseline file was then deleted.
     """
-    flat = _flat
-
-    undecided = architecture.decisions.undecided()
     scaffolds = sorted(
         p.stem for p in (out / "app" / "components").glob("*.py")
         if SCAFFOLD_MARK.split("  #")[0] in p.read_text()
     )
+    (out / "RISKS.md").write_text(
+        render_risks(waivers, overrides, architecture, registry, scaffolds=scaffolds))
+
+
+def render_risks(
+    waivers, overrides, architecture: Architecture, registry: Registry | None = None,
+    scaffolds: list[str] | tuple[str, ...] = (),
+) -> str:
+    """The risk page as text: what a build would write to RISKS.md, which
+    `fde report` carries before any build exists. `scaffolds` names the
+    emitted modules that still raise; a brief written before emission has
+    none."""
+    flat = _flat
+
+    undecided = architecture.decisions.undecided()
     lines = ["# Risks accepted", ""]
     if not waivers and not overrides and not architecture.unrealizable and not undecided:
         lines += [
@@ -237,7 +249,7 @@ def _write_risks(
             for component, reason in sorted(architecture.unrealizable.items())
         ]
         lines.append("")
-    (out / "RISKS.md").write_text("\n".join(lines) + "\n")
+    return "\n".join(lines) + "\n"
 
 
 # --- refusals ------------------------------------------------------------

{fde_framework-0.1.45 → fde_framework-0.1.46}/src/fde/factlog.py

@@ -207,13 +207,25 @@ class Engagement:
         state["data_access"] = _signed({"note": note, "at": at}, by)
         self._write_gate_state(state)
 
-    def record_deployed(self, note: str, at: str, by: str = "") -> None:
+    def record_deployed(self, note: str, at: str, by: str = "", project: str = "") -> None:
         """The deployment, attested like data access: where it runs and who
-        put it there. The lifecycle reads it; nothing else infers it."""
+        put it there, and which build it is. The lifecycle reads it; nothing
+        else infers it. Naming the build matters once implementation has
+        produced a second project directory beside the emitted one: every
+        command that reads a project by default then reads the deployed
+        one, not the last one built."""
         state = self._raw_gate_state()
-        state["deployed"] = _signed({"note": note, "at": at}, by)
+        entry = {"note": note, "at": at}
+        if project:
+            entry["project"] = project
+        state["deployed"] = _signed(entry, by)
         self._write_gate_state(state)
 
+    def deployed_project(self) -> str | None:
+        """The build the deployment attestation names, if it names one."""
+        deployed = self._raw_gate_state().get("deployed")
+        return deployed.get("project") or None if isinstance(deployed, dict) else None
+
     def record_security_review(self, note: str, at: str, by: str = "") -> None:
         state = self._raw_gate_state()
         state["security_review"] = _signed({"note": note, "at": at}, by)