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

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

@@ -5,6 +5,107 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.47] — 2026-10-12
+
+A fifteenth outside reading, the first of the source tree, and a
+sixteenth that ran the invoice example to its harness. Between them:
+a build that refused after writing, an emitter that could leave half a
+project, a sandbox policy the agent could rewrite for the next run, an
+envelope field that assumed a failure wrote nothing -- and an exam that
+could not get past its own pipeline's door.
+
+- **A refusal writes nothing.** The locale was checked after the project
+  and the prediction records had gone to disk, and the refusal said so:
+  "refused after writing code". It is resolved before anything is
+  written now, and a test holds the output directory and the record
+  unchanged after an unknown pack.
+- **A failed build leaves nothing that looks like a build.** The emitter
+  builds in a staging directory beside the destination and moves the
+  finished tree into place whole; a writer that fails halfway takes the
+  staging directory with it. Pinned by a test that breaks a writer.
+- **The exam reaches the thing it examines.** The invoice example's text
+  pairs were refused at the emitted pipeline's own door -- the design's
+  first stage read `pages` -- so every golden case scored as an input
+  error, the adversarial layer "passed" on refusals, and the build had
+  said "wrote". Two changes. The OCR stage now takes already-recognised
+  text as input that enters after it, says so in the envelope, and the
+  harness counts those cases and prints that the reading stage went
+  unexercised: a score on text measures extraction, not OCR. And a build
+  whose golden cases cannot enter its own pipeline is refused in staging,
+  naming the case and the reason, before anything is written. Pinned by
+  a test that builds the invoice example and runs its harness, and one
+  that feeds pairs no contract reads.
+- **The sandbox policy can only narrow.** `ops/agent-policy.yaml` lives
+  inside the directory the agent writes to. It could grant `network:
+  host` with a reason of its own and add a credential to `env_allow`,
+  and the next run honoured both. Now the file names the image and
+  bounded limits (memory within 64g, cpus within 64, pids within 8192;
+  outside them the default applies and the note says so); a network or
+  a name beyond the default allowlist is a request the log shows
+  ungranted, and only `--allow-network "who: why"` and `--env-allow`
+  at the terminal grant them. Names are validated, and names that change
+  what a process loads are refused whoever asks. The file is part of the
+  implement loop's fence: rewritten, it is restored and the round says
+  so; planted where none was, it is removed. Tests for each, including
+  the planted file and a policy asking for 900g.
+- **`mutated` is measured.** The envelope said true only on a writing
+  tool's exit 0, which assumed a failure had written nothing. The
+  record's files are now hashed before and after a writing tool, so a
+  write that failed partway and left changes says true. That is a field
+  changing meaning, so `schema_version` is 2, as the policy published in
+  0.1.45 said it would be; the schema's description says what changed.
+- The sanitisation suite skips, saying why, outside a git checkout: a
+  reviewer running the tests from a source archive saw a collection
+  error where a skip was the truth.
+- Not done, and said so: splitting `emit.py` and `cli.py`. They are
+  large; they are also where every pinned finding lives, and a split
+  without a user asking for a change is churn with the same tests.
+
+## [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.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.45
+Version: 0.1.47
 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
@@ -158,11 +160,13 @@ It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 `stop_when` and `history`, each returning exactly what the terminal prints,
 refusals included, beside a small envelope an agent can branch on without
 parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
-`mutated`, and the workspace. The envelope follows the command's exit,
-never a reading of its text. Its contract is a JSON Schema, `fde mcp
---schema`, that every reply is tested against; a client pins
-`schema_version`, which moves only when a field changes meaning or goes
-away, never when one is added. An engagement is named as `start` named
+`mutated`, and the workspace. The status follows the command's exit,
+never a reading of its text; `mutated` is measured, the record's files
+hashed before and after, so a write that failed partway and left changes
+says so. Its contract is a JSON Schema, `fde mcp --schema`, that every
+reply is tested against; a client pins `schema_version`, which moves
+only when a field changes meaning or goes away, never when one is added
+(it moved to 2 when `mutated` became a measurement). An engagement is named as `start` named
 it (`start(name="acme")`, then `status(engagement="acme")`), or by its
 path. An agent is not a person, so every path it supplies must stay
 inside one workspace, the directory the server started in or
@@ -241,7 +245,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,328 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 +255,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 +324,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 +468,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 +506,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
@@ -587,11 +556,16 @@ declared by the tool.
 - **`fde implement --sandbox docker`** runs the coding agent in a container
   closed by construction: only the project mounted, root read-only with a
   scratch `/tmp`, every capability dropped and none gainable, your own user
-  rather than root, bounded memory, CPU and processes, the environment an
-  allowlist from the emitted `ops/agent-policy.yaml`, and no network
-  unless someone with a name and a reason opened it. The implementation
-  log records the image digest the agent actually ran on; without the
-  sandbox it says the agent had the host.
+  rather than root, bounded memory, CPU and processes, the environment a
+  default allowlist, and no network unless someone with a name and a
+  reason opened it at the terminal (`--allow-network "who: why"`,
+  `--env-allow NAME`). The emitted `ops/agent-policy.yaml` sits inside
+  the directory the agent writes to, so it can only narrow: it names the
+  image and bounded limits, and anything wider it asks for is a request
+  the log shows ungranted. The file is part of the fence -- an agent that
+  rewrites it, or plants one, has the change reverted and the round says
+  so. The implementation log records the image digest the agent actually
+  ran on; without the sandbox it says the agent had the host.
 - **`fde experiment`** runs the protocol in
   [`EXPERIMENT.md`](https://github.com/atulkapoor/fde-framework/blob/main/EXPERIMENT.md)
   on the record: `start` assigns the arm by a seeded draw balanced within
@@ -656,7 +630,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 +685,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.47}/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
@@ -114,11 +115,13 @@ It serves `triage`, `start`, `frame`, `status`, `next`, `stage`, `debt`,
 `stop_when` and `history`, each returning exactly what the terminal prints,
 refusals included, beside a small envelope an agent can branch on without
 parsing prose: `schema_version`, `status` (ok, blocked, refused, failed),
-`mutated`, and the workspace. The envelope follows the command's exit,
-never a reading of its text. Its contract is a JSON Schema, `fde mcp
---schema`, that every reply is tested against; a client pins
-`schema_version`, which moves only when a field changes meaning or goes
-away, never when one is added. An engagement is named as `start` named
+`mutated`, and the workspace. The status follows the command's exit,
+never a reading of its text; `mutated` is measured, the record's files
+hashed before and after, so a write that failed partway and left changes
+says so. Its contract is a JSON Schema, `fde mcp --schema`, that every
+reply is tested against; a client pins `schema_version`, which moves
+only when a field changes meaning or goes away, never when one is added
+(it moved to 2 when `mutated` became a measurement). An engagement is named as `start` named
 it (`start(name="acme")`, then `status(engagement="acme")`), or by its
 path. An agent is not a person, so every path it supplies must stay
 inside one workspace, the directory the server started in or
@@ -197,7 +200,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,328 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 +210,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 +279,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 +423,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 +461,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
@@ -543,11 +511,16 @@ declared by the tool.
 - **`fde implement --sandbox docker`** runs the coding agent in a container
   closed by construction: only the project mounted, root read-only with a
   scratch `/tmp`, every capability dropped and none gainable, your own user
-  rather than root, bounded memory, CPU and processes, the environment an
-  allowlist from the emitted `ops/agent-policy.yaml`, and no network
-  unless someone with a name and a reason opened it. The implementation
-  log records the image digest the agent actually ran on; without the
-  sandbox it says the agent had the host.
+  rather than root, bounded memory, CPU and processes, the environment a
+  default allowlist, and no network unless someone with a name and a
+  reason opened it at the terminal (`--allow-network "who: why"`,
+  `--env-allow NAME`). The emitted `ops/agent-policy.yaml` sits inside
+  the directory the agent writes to, so it can only narrow: it names the
+  image and bounded limits, and anything wider it asks for is a request
+  the log shows ungranted. The file is part of the fence -- an agent that
+  rewrites it, or plants one, has the change reverted and the round says
+  so. The implementation log records the image digest the agent actually
+  ran on; without the sandbox it says the agent had the host.
 - **`fde experiment`** runs the protocol in
   [`EXPERIMENT.md`](https://github.com/atulkapoor/fde-framework/blob/main/EXPERIMENT.md)
   on the record: `start` assigns the arm by a seeded draw balanced within
@@ -612,7 +585,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 +640,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.47}/examples/invoice-extraction/README.md

@@ -60,6 +60,12 @@ fde build engagements/acme --out project
 # wrote project
 # evals: 2 golden, 0 edge, 8 adversarial
 # next: fde implement project --holdout engagements/acme/artifacts/holdout.jsonl
+#
+# The pairs are text, and the design's first stage is OCR. Text enters after
+# it: `python -m evals.harness` reaches the extraction stage (and fails there
+# until fde implement), and says the OCR stage went unexercised -- bring
+# page-shaped pairs to test the reading. A build whose golden cases cannot
+# enter its own pipeline is refused before it is written.
 ```
 
 The emitted `project/` holds `app/` (pipeline in topological order, boundary