Add community evidence hardening overlay

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to MARGINAL are documented here. The project follows Semantic Versioning.
 
+## [Unreleased]
+
+### Added
+
+- opt-in, provider-neutral `DiminishingReturnDetector` with same-state/evidence-aware gain decay;
+- `GovernanceTracker` for MARGINAL decision latency and external governance tokens, USD and latency;
+- explicit counterfactual stop review through `Treasury.record_stop_review(...)` without inferring action causality from task outcomes;
+- public-evaluation fields for repeated calls, governance overhead, reviewed stops and false stops;
+- gross-versus-net savings and intervention status including Graceful Irrelevance through `pass_through`;
+- governance evidence standard, Codex benchmark-readiness guide and Community Feedback Log;
+- structured documentation information architecture by user intent.
+
+### Changed
+
+- public benchmark efficiency counts governance overhead in effective tokens/USD while retaining agent-only metrics and backward-compatible rows;
+- `MarginalPolicy` can optionally discount or reject repeated semantic same-state work;
+- `Treasury` records policy-decision latency and exposes governance evidence in summaries/traces;
+- website and README now lead with a concrete illustrative trace and proof standard before architecture theory;
+- roadmap now treats governance tax, false-stop rate, matched OFF/ON evaluation and pass-through as first-class success criteria;
+- the 10-task Codex canary is explicitly classified as integration validation rather than public performance evidence.
+
+### Scientific limitations
+
+- diminishing-return thresholds are transparent heuristics until calibrated on representative engine telemetry;
+- false stops require external review/counterfactual labels and are not automatically causal estimates;
+- Graceful Irrelevance classifies the measured configuration, not the universal usefulness of MARGINAL;
+- vendor-specific Codex integration and measured public savings remain future v0.3 evidence.
+
 ## [0.2.0] - 2026-08-06
 
 ### Added
@@ -34,32 +62,27 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 
 ### Changed
 
-- redesigned the repository README as a concise, SEO-oriented technical landing page;
+- redesigned the repository README as a concise technical landing page;
 - added a dependency-free, responsive, accessible GitHub Pages product website;
-- consolidated the product website, hero asset, and Killer Demo into one Pages deployment;
-- documented website ownership, deployment, accessibility, privacy, and evidence guardrails.
-
-- `Decision` is backward compatible but now carries recommendation, mode, reason-code, uncertainty, confidence, and estimator metadata;
-- `MarginalPolicy` now has a stable identity and supports both versioned and legacy custom estimators;
-- `Treasury.summary()` includes mode, policy, estimator, observed overruns, failed settlements, outcomes, and estimator observations;
-- child treasuries inherit the parent execution mode;
-- trace events include execution mode plus policy and estimator identity;
-- Decision Ledger records now declare their privacy profile; `local_full` remains backward compatible while strict profiles are opt-in;
-- actual failed-call spend can be accounted without replacing the original execution exception; extraction failures conservatively settle the reserved estimate and remain chained as secondary errors;
-- strict public-benchmark parsing rejects string-like booleans instead of silently coercing them;
-- project description and documentation now consistently describe MARGINAL as a learning-loop foundation rather than only a static wrapper.
+- consolidated product website, hero asset and Killer Demo into one Pages deployment;
+- `Decision` carries recommendation, mode, reason-code, uncertainty, confidence and estimator metadata;
+- `MarginalPolicy` has stable identity and supports versioned/legacy custom estimators;
+- `Treasury.summary()` includes mode, policy, estimator, observed overruns, failed settlements, outcomes and estimator observations;
+- child treasuries inherit parent execution mode;
+- traces include execution mode plus policy and estimator identity;
+- strict public-benchmark parsing rejects string-like booleans.
 
 ### Compatibility
 
-- existing v0.1 constructors, enforced execution, `JsonlTraceSink`, synchronous and asynchronous wrappers, demos, and CLI commands remain supported;
+- existing v0.1 constructors, enforced execution, `JsonlTraceSink`, synchronous/asynchronous wrappers, demos and CLI commands remain supported;
 - new dataclass fields have backward-compatible defaults;
-- the runtime core continues to have zero mandatory dependencies.
+- runtime core continues to have zero mandatory dependencies.
 
 ### Scientific limitations
 
 - historical estimates are observational and do not establish causal action value;
 - policy replay does not simulate unobserved trajectories or prove quality preservation;
-- vendor-specific Codex, Claude Code, GitHub Copilot, and OpenCode adapters remain future milestones;
+- vendor-specific Codex, Claude Code, GitHub Copilot and OpenCode adapters remain future milestones;
 - reference profiles are transparent defaults, not universal calibrations.
 
 ## [0.1.0] - 2026-08-04
@@ -68,12 +91,12 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 
 - provider-neutral `Action`, `Cost`, `Decision`, and `Allocation` value objects;
 - deterministic candidate ranking, authorization, reservation, settlement, and abort;
-- hard budgets for tokens, direct USD, latency, and risk;
-- pending reservations and hierarchical parent/child accounting;
+- hard token, USD, latency and risk budgets;
+- pending reservations and hierarchical accounting;
 - protected verification reserves;
-- marginal-value policy with token, latency, and risk shadow prices;
-- exact action and callable-input fingerprinting;
-- synchronous and asynchronous guarded-call adapters;
+- marginal-value policy with token, latency and risk shadow prices;
+- exact action/callable-input fingerprinting;
+- synchronous/asynchronous guarded-call adapters;
 - append-only JSONL traces and CLI reporting;
-- synthetic benchmark, public comparison utility, and Killer Demo;
-- Python 3.10–3.13 CI, CodeQL, packaging, and community documentation.
+- synthetic benchmark, public comparison utility and Killer Demo;
+- Python 3.10–3.13 CI, CodeQL, packaging and community documentation.

MIGRATION_MANIFEST.json

@@ -0,0 +1,48 @@
+{
+  "package": "MARGINAL community evidence hardening overlay",
+  "target_repository": "SignalLayerLabs/Marginal",
+  "target_branch": "main",
+  "prepared_against_commit": "d6ab5c745f1a2ec19b2cb2395a1e6bfae66f2de5",
+  "created": "2026-08-07",
+  "package_type": "repository-overlay",
+  "rules": [
+    "Apply to a clean checkout of the target repository.",
+    "Do not add this ZIP or the external Visual Studio prompt to Git.",
+    "Run scripts/reorganize_docs.py after overlay extraction.",
+    "Do not invent benchmark results or mark the Codex adapter as implemented.",
+    "Run all validation commands before committing."
+  ],
+  "moves": {
+    "docs/quickstart.md": "docs/getting-started/quickstart.md",
+    "docs/concepts.md": "docs/product/concepts.md",
+    "docs/architecture.md": "docs/product/architecture.md",
+    "docs/faq.md": "docs/product/faq.md",
+    "docs/api.md": "docs/reference/api.md",
+    "docs/integrations.md": "docs/integrations/overview.md",
+    "docs/benchmarking.md": "docs/evaluation/benchmarking.md",
+    "docs/public-benchmarks.md": "docs/evaluation/public-benchmarks.md",
+    "docs/research.md": "docs/evaluation/research.md",
+    "docs/privacy.md": "docs/operations/privacy.md",
+    "docs/website.md": "docs/operations/website.md",
+    "docs/governance.md": "docs/project/governance.md"
+  },
+  "new_core_modules": [
+    "src/marginal/controls/__init__.py",
+    "src/marginal/controls/diminishing.py",
+    "src/marginal/controls/governance.py"
+  ],
+  "replaced_core_files": [
+    "src/marginal/__init__.py",
+    "src/marginal/cli.py",
+    "src/marginal/policy.py",
+    "src/marginal/public_eval.py",
+    "src/marginal/treasury.py"
+  ],
+  "communication_files": [
+    "README.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "site/index.html",
+    "site/styles.css"
+  ]
+}

PACKAGE_CHECKSUMS.sha256

@@ -0,0 +1,31 @@
+0ffc751f0c3ac86b0cb1a201c4ae3773ebfcc30b8672fccdcda5df6ea3cc35a1  ./CHANGELOG.md
+54940f6294de06328fe6826f81a51ab86f81df1a1b0da15626b6e7480631d9b4  ./MIGRATION_MANIFEST.json
+cdee908544415e8c05c4ff308dc30c8884f25663c3676684077213bcefb39c57  ./PACKAGE_README.md
+bed65f82a0fb147f7eee6f30d67aa1c1a07d5a8503a1e1fff4a1dc12fee2c6a7  ./README.md
+c1f177cf4291ebef10d4023c8d4144bed109a9e97cbeca18f09ff0772bb16097  ./ROADMAP.md
+878ebab0f0d6e8eeddebd3aaea8aa48ce20ddf5f98720ca203d4e207bdeb9a92  ./docs/evaluation/governance-evidence.md
+5474b9a310e857c213f578cfe8a1e743a38b33ba5209bfc619dabb05d535de48  ./docs/index.md
+c74df4b2fdc280eae409e9d49f21d7e4bfa68c88003a0e02d9e8eb35d1fdef51  ./docs/integrations/codex-benchmark-readiness.md
+4503e66d5b74e51233a1306a43c658aa948df0199898c9aa5ef846dbec6cff2f  ./docs/operations/website-review-2026-08-07.md
+c0e591c130bb6de3e269339f3105af93f98f721442161d39520df762f664350e  ./docs/project/community-feedback.md
+d9962b32c01d847ff91709b129cc7993d0beccb5111f9afe394615a8de235c13  ./docs/superpowers/plans/2026-08-07-community-evidence-hardening.md
+fba3bedaebedc8e898d2ba0caccbac7de5b2d3c0a2abf976cb4c24c7e676d487  ./docs/superpowers/specs/2026-08-07-community-evidence-hardening-design.md
+300b13720c873f38fdb566ba2fa2b9b8a18a9cdc52253bbbaae6cb1f016540e0  ./scripts/reorganize_docs.py
+07a5f282687514233e809c237c6171fc3a3e29ca1ef3d88e493db20d04ef6fcc  ./scripts/validate_community_hardening.py
+32ca56be9daaab6f22fcb3d817fade2e7260302d302beefdb854edd12d3eeff7  ./scripts/validate_readme_pages.py
+94a26f0f90fd09babaf13b7cdddf7d03351745f2dbdd14fe5646a80c0dc4c60b  ./site/index.html
+3888918324e1351e749437806f7b37937c3c8fe48304eefde7ea1a4b729e1f0b  ./site/styles.css
+8b505e6dcc12b6679c234d39c9f344cfe61295091a790835f3bdf7c1e396a70c  ./src/marginal/__init__.py
+ceff13a46267520b6a62864967ab275d87af52bf82b941ffa078947d08dcd3f1  ./src/marginal/cli.py
+0fa38295e579e012b4b24ebb5e06cad89af6a0549f457d0bfbd41f60401551eb  ./src/marginal/controls/__init__.py
+ad8ca98aac20adbdb55363905f4f197ddc9dc04a77b9cdecd8520006da038dab  ./src/marginal/controls/diminishing.py
+9cc63951146cfd68b8e7923035d805c03e9db3509f302d8ca66570bcb4a01a2c  ./src/marginal/controls/governance.py
+992d48c98f6e0f421745939713eac8b4459f7f49cf9baad4128efe800adb9ce1  ./src/marginal/policy.py
+d3357ef4a93cba5f92eb161c7eea417fd063b7936e175cefbc2f7d08eea5165e  ./src/marginal/public_eval.py
+16095e6c42b0e5c8f41b23a7f26a929599ac726f1d39a21c6aab9c89888b636f  ./src/marginal/treasury.py
+37dcd6e3d0672c1da8db67cb34c868ac59257f9ec570220bcd835f9ee979046e  ./tests/controls/test_diminishing.py
+1b30b9ad2bef94ac0be34b5731ef7647b38289bf17c16ccac36648e63ea14c48  ./tests/controls/test_governance.py
+0c633fd64787e45794a8d36a66ea53cb0b5adb84695c87538bbe8506488bf990  ./tests/controls/test_policy_diminishing.py
+c4da184c1017e2407a6a72cfa784cbb04ff048b0e2c393ddcd43f8fde4d93afb  ./tests/controls/test_treasury_governance.py
+d941eb513a4a191a41b7e4dae28b700b48e2c70ef5fc4106b5147b5289090ae7  ./tests/evaluation/test_cli_public_eval_governance.py
+244f5b01bcafb56bf864f092ddb03eacb657dcb160b48062b0815f3365017e87  ./tests/evaluation/test_public_eval_governance.py

PACKAGE_MANIFEST.json

@@ -9,7 +9,7 @@
     "VISUAL_STUDIO_COMMIT_PROMPT.md",
     "docs/superpowers/plans/2026-08-06-readme-pages.md",
     "docs/superpowers/specs/2026-08-06-readme-pages-design.md",
-    "docs/website.md",
+    "docs/operations/website.md",
     "scripts/validate_readme_pages.py",
     "site/404.html",
     "site/app.js",

PACKAGE_README.md

@@ -0,0 +1,29 @@
+# MARGINAL Community Hardening Overlay
+
+This ZIP is a repository overlay prepared for `SignalLayerLabs/Marginal` `main` at commit `d6ab5c745f1a2ec19b2cb2395a1e6bfae66f2de5`.
+
+## What it contains
+
+- model-independent diminishing-return control;
+- governance-tax and explicit false-stop accounting;
+- net-value public benchmark reporting and CLI gates;
+- evidence-first README / GitHub Pages rewrite;
+- community feedback decision log;
+- Codex benchmark-readiness specification;
+- documentation reorganization tooling;
+- focused tests and validators.
+
+## Important
+
+This package does **not** contain a completed Codex adapter and does not contain benchmark results. It prepares the evidence/control layer for v0.3.
+
+The Visual Studio upload prompt is intentionally distributed separately and must not be committed.
+
+## Apply order
+
+1. Start from a clean checkout of `SignalLayerLabs/Marginal` `main`.
+2. Extract this ZIP over the repository root, replacing matching files.
+3. Run `python scripts/reorganize_docs.py` once.
+4. Review `MIGRATION_MANIFEST.json` and the resulting `git diff`.
+5. Run the focused validators and the full repository quality gate described in the external Visual Studio prompt.
+6. Commit the source changes only; do not commit this ZIP or the external prompt.