truth-firewall 0.1.0__tar.gz

truth_firewall-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Truth Firewall is an early Windows pilot for bounded local Python tasks. Keep original task requirements, acceptance checks, evidence, and final verdicts distinct. Add a regression test when changing verification behavior. Do not treat worker prose or passing worker-owned tests as completion authority.
+
+## Local checks
+
+For development, clone the source and use a virtual environment. Normal users can use the pipx source/artifact installation described in [QUICKSTART.md](QUICKSTART.md); the PyPI command remains planned until publication and public verification.
+
+```powershell
+git clone https://github.com/aldi949/truth-firewall.git
+cd truth-firewall
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest
+```
+
+When reporting a problem, include the command, Python version, platform, and a small reproduction. Redact task text, source, private paths, credentials, and local invocation logs before sharing. Do not commit `.env` files, virtual environments, or `.truth-firewall\runs`.
+
+For release checks, build with `python -m build`, validate with `python -m twine check --strict dist/*` and `python tools/check_dist.py dist`, then run `tools/check_pipx.py` against the wheel from a new temporary directory. See [docs/PUBLISHING.md](docs/PUBLISHING.md). These commands do not publish.

truth_firewall-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Truth Firewall Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

truth_firewall-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE README.md QUICKSTART.md CONTRIBUTING.md PILOT_FEEDBACK.md
+recursive-include docs *.md
+recursive-include tools *.py
+recursive-include tests *.py
+recursive-include src/truth_firewall *.py *.json py.typed
+global-exclude *.py[cod] .env .env.* *.pem *.key *.pfx
+prune .github
+prune .pytest_cache
+prune build
+prune dist
+prune artifacts

truth_firewall-0.1.0/PILOT_FEEDBACK.md

@@ -0,0 +1,14 @@
+# Truth Firewall pilot feedback
+
+Please answer briefly. Do not include API keys, private source code, or confidential task text.
+
+1. What task did you give your agent?
+2. Would you normally have watched or checked it manually?
+3. Did Truth Firewall let you leave it alone?
+4. Was the final decision correct?
+5. Did it block a premature DONE?
+6. Did it block something that was actually complete?
+7. What confused or annoyed you?
+8. Would you use this again? Why?
+9. Would you install it on another repo?
+10. What would make this a must-have?

truth_firewall-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: truth-firewall
+Version: 0.1.0
+Summary: Independently verify bounded local Python coding tasks completed by Codex.
+Author: Truth Firewall Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aldi949/truth-firewall
+Project-URL: Repository, https://github.com/aldi949/truth-firewall
+Project-URL: Issues, https://github.com/aldi949/truth-firewall/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Your coding agent says “DONE”. That doesn’t mean the job is done.
+
+**Truth Firewall won’t accept `DONE` until the work is independently verified.**
+
+Your coding agent says:
+
+> “Done. Tests pass.”
+
+Maybe it is.
+
+Maybe it skipped a requirement.\
+Maybe an edge case is broken.\
+Maybe it changed something it shouldn’t have.
+
+And then **you** have to check everything anyway.
+
+That defeats the whole point of having an agent.
+
+# Truth Firewall stops that.
+
+**The agent does the work.**\
+**Truth Firewall decides whether `DONE` is actually earned.**
+
+Give Codex the task.
+
+Walk away.
+```text
+Codex works
+    ↓
+Codex says DONE
+    ↓
+Truth Firewall verifies the required work
+    ↓
+┌──────────────────┬──────────────────┬──────────────────┐
+↓                  ↓                  ↓
+VERIFIED_DONE    REJECT_DONE       HUMAN_REQUIRED
+                     ↓
+              Codex keeps working
+```
+
+## Install the package
+
+**Planned PyPI command — not published or verified from PyPI yet:**
+
+```powershell
+pipx install truth-firewall
+```
+
+Have **Python 3.11+ and pipx** installed first. On Windows, you can install pipx with `py -3.11 -m pip install --user pipx`, run `py -3.11 -m pipx ensurepath`, and reopen PowerShell. Use an installed supported Python version in those commands. Installing Truth Firewall does not install Python, pipx, Node.js, or Codex, and does not sign you into Codex.
+
+Until PyPI publication, use Git plus the reviewed GitHub revision, or install a locally built wheel:
+
+```powershell
+pipx install "git+https://github.com/aldi949/truth-firewall.git@95d0fc00de59134527af979de6f07eda1bd65d8a"
+# Local release candidate, after building/downloading the actual artifact:
+pipx install .\truth_firewall-0.1.0-py3-none-any.whl
+truth-firewall --help
+truth-firewall --version
+truth-firewall demo
+```
+
+The offline demo needs no Codex account and explicitly labels its fixtures as demonstrations, not live accuracy. Package installation is isolated by pipx; the real task runner is currently a **Windows pilot**. See [QUICKSTART.md](QUICKSTART.md) for setup and [publication gates](docs/PUBLISHING.md) for the unpublished candidate. Do not use the planned PyPI command until a release has been published and verified to belong to this repository.
+
+## First-time Codex setup
+
+Real tasks require Node.js and an installed, authenticated Codex CLI for the same Windows user. Install those separately using the [Codex CLI instructions](https://developers.openai.com/codex/cli). Verify `node --version`, `codex --version`, and `codex login status`; sign in with `codex login` if necessary. Truth Firewall's pilot expects the npm Codex JavaScript entry point under the current user's `%APPDATA%\npm\node_modules\@openai\codex\bin\codex.js`. Nonstandard installations can set `TRUTH_FIREWALL_CODEX_JS` to their actual `codex.js` path. Codex may require an eligible account or API billing; pipx installation does not provide authentication or credits.
+
+## Run a bounded Python task
+
+Open PowerShell in the Python repository you want Truth Firewall to work on, then run:
+
+```powershell
+truth-firewall init
+notepad .\.truth-firewall\task.json
+truth-firewall activate
+truth-firewall run
+```
+
+`init` asks for your task text and an optional required output file. It runs locally without an LLM and validates `.truth-firewall/task.json` using the same spec loader as `run`. A supplied file creates only a file-existence starter check; leaving it blank creates a clearly marked editable template. Both remain unreviewed and cannot authorize completion. Review the file and add checks for **every mandatory requirement**, replacing any `EDIT_ME` placeholder, then explicitly confirm with `truth-firewall activate`. An unreviewed spec stops before Codex starts. Truth Firewall cannot infer omitted requirements or guarantee that review makes the checks complete. Existing task files are preserved unless you explicitly use `truth-firewall init --overwrite`. Existing manually authored `--spec` contracts remain supported; an `EDIT_ME` placeholder always blocks completion. The verifier cannot infer from arbitrary task prose that a check targets the intended source file, so inspect paths carefully. See [QUICKSTART.md](QUICKSTART.md) for examples and PATH troubleshooting; clone/venv development setup is in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Activation records a SHA-256 digest of the reviewed task and checks. If you edit the task or checks afterward, `run` returns `HUMAN_REQUIRED` before Codex starts; review the changed contract and run `truth-firewall activate` again. The digest detects ordinary edits, not deliberate rewriting of both the contract and its digest by someone with access to your files.
+
+Legacy manually authored specs remain accepted without review metadata. If both `acceptance_review` and `onboarding_note` are removed from a generated concrete starter, it becomes indistinguishable from a legacy spec; keep those fields and use `activate` after reviewing the checks.
+
+The supported checks are `file_exists` (a repository-relative path exists or does not exist), `python_function` (a top-level function has the exact parameter list), and `black_box` (JSON argument lists produce expected return values). Give each condition a unique `id`. Every listed condition is mandatory, and requirements missing from `task.json` cannot be verified.
+
+## What the decisions mean
+
+- `VERIFIED_DONE`: all listed mandatory checks passed for the observed final repository state. The terminal shows the original task, check summary, and attempts used.
+- `REJECT_DONE`: a worker completion claim failed at least one mandatory check. This is an intermediate decision; Truth Firewall sends actionable failures back to Codex and continues within the three-attempt limit.
+- `HUMAN_REQUIRED`: completion could not be proven, including when attempts are exhausted or a mandatory condition cannot be checked. Review the named requirements and decide what to do next.
+- `ERROR`: the worker, verifier, or runtime could not complete the run. This is an execution problem, not a verdict that the task failed.
+
+## Why this exists
+
+A worker saying “done,” code existing, or worker-owned tests passing does not establish that your original requirements were met. Truth Firewall checks the acceptance conditions you supplied after each attempt and blocks an unsupported completion claim. It can continue Codex automatically when a check fails, so you do not have to watch each turn.
+
+## What `VERIFIED_DONE` actually means
+
+It means the listed mandatory checks passed on the final observed workspace state. It does **not** prove that an omitted requirement was met, that the checks themselves are complete, or that all possible behavior is correct. Author the checks to cover the task before you start; if the supported checks cannot establish completion, treat the outcome as requiring human judgment.
+
+## Current pilot scope
+
+This first release supports local repositories, bounded Python coding tasks, a Codex CLI worker, deterministic file/API/input-output checks, and at most three worker attempts. A small local run summary is written under `.truth-firewall\runs\<run-id>\summary.json`; it records the decision and attempt counts without task text or source code.
+
+## Limitations
+
+This is not a hostile-worker security boundary or a claim of universal correctness. Codex runs as your normal user and can access files available to that account, including the task specification. Use disposable or nonsensitive repositories for the pilot. Subjective quality, UI behavior, deployment, external services, broad repository work, and requirements that cannot be observed with the supported checks are outside this pilot.
+
+## Privacy
+
+Truth Firewall does not automatically upload telemetry, source code, or task text. Codex sends task instructions and the context it reads to its configured service under your account settings. Detailed local invocation logs are stored in the operating system's temporary directory and may contain the task prompt and worker output. Review those settings before using private code.
+
+## Feedback and license
+
+Trying Truth Firewall on a real task? Please use [PILOT_FEEDBACK.md](PILOT_FEEDBACK.md). Contribution guidance and local test commands are in [CONTRIBUTING.md](CONTRIBUTING.md). Truth Firewall is [MIT licensed](LICENSE).

truth_firewall-0.1.0/QUICKSTART.md

@@ -0,0 +1,107 @@
+# Quickstart: local Python task with Codex
+
+Use **Windows PowerShell** for real tasks. Package installation and Codex setup are separate.
+
+## Package installation
+
+**Planned command after PyPI publication — not currently a verified public PyPI install:**
+
+```powershell
+pipx install truth-firewall
+```
+
+Prerequisites: Python 3.11+ and pipx on PATH. Installing the package supplies neither Python nor pipx. If needed, install pipx with `py -3.11 -m pip install --user pipx`, run `py -3.11 -m pipx ensurepath`, and reopen PowerShell. Substitute your installed supported Python version. Check `pipx --version` before continuing.
+
+Before publication, the available GitHub installation requires Git and uses the reviewed published commit:
+
+```powershell
+pipx install "git+https://github.com/aldi949/truth-firewall.git@95d0fc00de59134527af979de6f07eda1bd65d8a"
+```
+
+For a locally built candidate wheel instead, use `pipx install .\truth_firewall-0.1.0-py3-none-any.whl`. These are actual source/artifact installs, not proof that `pipx install truth-firewall` resolves to this project on PyPI. Publication instructions and gates are in [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+From any working directory, check the installed executable:
+
+```powershell
+truth-firewall --help
+truth-firewall --version
+truth-firewall demo
+```
+
+The offline demo uses bundled fixtures and labels them **NOT LIVE PRODUCT ACCURACY**. It needs no Node.js or Codex authentication. pipx upgrade and uninstall commands after publication are `pipx upgrade truth-firewall` and `pipx uninstall truth-firewall`. For a newer local wheel, use `pipx install --force .\path\to\new.whl`; `pipx upgrade` of a wheel-pinned installation does not switch it to PyPI.
+
+## First-time Codex setup
+
+Install Node.js and Codex CLI separately for the current Windows user, following the [official Codex CLI instructions](https://developers.openai.com/codex/cli). Confirm `node --version` and `codex --version`, then run `codex login` and check `codex login status`. You need valid Codex authentication; installing Truth Firewall does not configure an account, provide credits, install Node.js, or install Codex.
+
+The pilot expects the npm Codex entry point at `%APPDATA%\npm\node_modules\@openai\codex\bin\codex.js`. For another installation layout, set `TRUTH_FIREWALL_CODEX_JS` to the real `codex.js` path. If Node.js or that entry point is missing, a reviewed task reports a setup `ERROR`; an unreviewed contract still blocks before attempting a worker. Runtime support beyond Windows is not claimed by this pilot.
+
+Open PowerShell in the Python repository you want Truth Firewall to work on, then run:
+
+```powershell
+truth-firewall init
+notepad .\.truth-firewall\task.json
+truth-firewall activate
+truth-firewall run
+```
+
+## Prepare the task
+
+Run `init` from the root of a disposable or nonsensitive local Python repository. It asks for your task text and optionally a repository-relative output file that your task must create. It is deterministic, local, and needs no LLM or API key. It validates the generated JSON through the existing task/spec loader before reporting success.
+
+A supplied path creates a `file_exists` starter check only. Leaving the path blank creates a valid, explicitly marked editable template with `EDIT_ME_required_output.py` as a placeholder. **Replace that placeholder before activation.** Both starter forms are unreviewed and cannot authorize completion. Neither option infers behavior or guarantees full coverage. Open the contract to review and extend it before activation:
+
+```powershell
+notepad .\.truth-firewall\task.json
+```
+
+Keep `task` as your bounded request. Edit `conditions` to check **every mandatory requirement**. The `onboarding_note` is an editing reminder, not an acceptance check. Each condition has a unique `id` and a repository-relative `path`:
+
+- `file_exists`: `path` and `exists` (`true` or `false`).
+- `python_function`: `path`, top-level `symbol`, and exact `parameters` list.
+- `black_box`: `path`, top-level `symbol`, and one or more `cases` with JSON `args` and `expected` return value.
+
+For example, if your task is specifically to implement `add_one(value)` in `app.py`, you could use these conditions (adapt them to your actual request):
+
+```json
+[
+  {"id": "file", "kind": "file_exists", "path": "app.py", "exists": true},
+  {"id": "api", "kind": "python_function", "path": "app.py", "symbol": "add_one", "parameters": ["value"]},
+  {"id": "behavior", "kind": "black_box", "path": "app.py", "symbol": "add_one", "cases": [{"args": [1], "expected": 2}]}
+]
+```
+
+All listed conditions are mandatory. Truth Firewall cannot infer requirements omitted from the file, and explicit review does not guarantee complete task coverage. If the supported checks cannot establish your task's requirements, do not treat the result as proof of completion. Check that every condition points to the intended file: the verifier cannot soundly match paths against arbitrary natural-language task text. `init` refuses to overwrite an existing contract; use `truth-firewall init --overwrite` only when you intend to replace it.
+
+## Run
+
+From the task repository after reviewing and editing the contract, confirm the displayed task and checks, then run:
+
+```powershell
+truth-firewall activate
+truth-firewall run
+```
+
+The default spec is `.truth-firewall/task.json`. For a generated contract at another path, use `truth-firewall activate --spec path\to\task.json`. Existing manually authored contracts remain usable with `truth-firewall run --spec path\to\task.json`; generated contracts require activation. An unreviewed starter returns `HUMAN_REQUIRED` before launching Codex, even if its file-existence check would pass. An `EDIT_ME` placeholder cannot authorize `VERIFIED_DONE`.
+
+Activation stores a digest of the task and acceptance checks you reviewed. After changing either, review the file and run `truth-firewall activate` again before `run`; a changed reviewed contract returns `HUMAN_REQUIRED` without launching Codex. This detects ordinary edits, but the digest is not an authenticated signature against someone who can rewrite both it and the contract.
+
+Keep the generated `acceptance_review` and `onboarding_note` fields. Removing both from a concrete starter makes it indistinguishable from an older manually authored spec, which remains accepted for compatibility. Review and activate the generated contract instead.
+
+Truth Firewall runs Codex, verifies the checks after each attempt, and automatically continues after `REJECT_DONE`, up to three attempts. The final result is:
+
+- `VERIFIED_DONE`: all listed checks passed on the observed final state; the terminal shows the original task, checks, evidence summary, and attempts used.
+- `HUMAN_REQUIRED`: completion remains unproven; the terminal names unresolved or failed checks and asks you to review them.
+- `ERROR`: execution or setup failed; the terminal gives the runtime reason. This is not a task-failure verdict.
+
+A minimal local run summary is saved in `.truth-firewall\runs\<run-id>\summary.json`. It does not include task text or source. Detailed local invocation logs are stored in the operating system's temporary directory and may contain the task prompt and Codex output.
+
+## Supported scope
+
+This Windows pilot uses a local Python repository, Codex CLI, bounded tasks, and deterministic acceptance checks. Codex runs as your normal user. The pilot does not isolate a hostile worker, prove unlisted requirements, or cover subjective review, UI behavior, deployment, and external services. Truth Firewall does not upload telemetry; Codex service data handling follows your Codex account settings.
+
+## If the command is not found
+
+Run `pipx ensurepath`, reopen PowerShell, and check `pipx list`. pipx installs the CLI in its own environment; your system `py -m truth_firewall` is not expected to see a pipx-installed package. If multiple Python versions are installed, use `pipx install --python 3.11 ...` (or another supported version) to choose one. Developer clone/venv instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+On Windows Python 3.11, pipx's own shared-library storage can fail in a non-ASCII path (`UnicodeEncodeError` or `No module named pip`). Before installation, set `$env:PIPX_HOME` to a new writable ASCII-only absolute path and `$env:PYTHONUTF8 = "1"`, then retry. Keep that `PIPX_HOME` setting for subsequent pipx lifecycle commands. The hosted Python 3.11 checks use ASCII pipx storage and non-ASCII project directories; they do not establish support for non-ASCII pipx storage. These settings do not change Truth Firewall's acceptance checks.

truth_firewall-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Your coding agent says “DONE”. That doesn’t mean the job is done.
+
+**Truth Firewall won’t accept `DONE` until the work is independently verified.**
+
+Your coding agent says:
+
+> “Done. Tests pass.”
+
+Maybe it is.
+
+Maybe it skipped a requirement.\
+Maybe an edge case is broken.\
+Maybe it changed something it shouldn’t have.
+
+And then **you** have to check everything anyway.
+
+That defeats the whole point of having an agent.
+
+# Truth Firewall stops that.
+
+**The agent does the work.**\
+**Truth Firewall decides whether `DONE` is actually earned.**
+
+Give Codex the task.
+
+Walk away.
+```text
+Codex works
+    ↓
+Codex says DONE
+    ↓
+Truth Firewall verifies the required work
+    ↓
+┌──────────────────┬──────────────────┬──────────────────┐
+↓                  ↓                  ↓
+VERIFIED_DONE    REJECT_DONE       HUMAN_REQUIRED
+                     ↓
+              Codex keeps working
+```
+
+## Install the package
+
+**Planned PyPI command — not published or verified from PyPI yet:**
+
+```powershell
+pipx install truth-firewall
+```
+
+Have **Python 3.11+ and pipx** installed first. On Windows, you can install pipx with `py -3.11 -m pip install --user pipx`, run `py -3.11 -m pipx ensurepath`, and reopen PowerShell. Use an installed supported Python version in those commands. Installing Truth Firewall does not install Python, pipx, Node.js, or Codex, and does not sign you into Codex.
+
+Until PyPI publication, use Git plus the reviewed GitHub revision, or install a locally built wheel:
+
+```powershell
+pipx install "git+https://github.com/aldi949/truth-firewall.git@95d0fc00de59134527af979de6f07eda1bd65d8a"
+# Local release candidate, after building/downloading the actual artifact:
+pipx install .\truth_firewall-0.1.0-py3-none-any.whl
+truth-firewall --help
+truth-firewall --version
+truth-firewall demo
+```
+
+The offline demo needs no Codex account and explicitly labels its fixtures as demonstrations, not live accuracy. Package installation is isolated by pipx; the real task runner is currently a **Windows pilot**. See [QUICKSTART.md](QUICKSTART.md) for setup and [publication gates](docs/PUBLISHING.md) for the unpublished candidate. Do not use the planned PyPI command until a release has been published and verified to belong to this repository.
+
+## First-time Codex setup
+
+Real tasks require Node.js and an installed, authenticated Codex CLI for the same Windows user. Install those separately using the [Codex CLI instructions](https://developers.openai.com/codex/cli). Verify `node --version`, `codex --version`, and `codex login status`; sign in with `codex login` if necessary. Truth Firewall's pilot expects the npm Codex JavaScript entry point under the current user's `%APPDATA%\npm\node_modules\@openai\codex\bin\codex.js`. Nonstandard installations can set `TRUTH_FIREWALL_CODEX_JS` to their actual `codex.js` path. Codex may require an eligible account or API billing; pipx installation does not provide authentication or credits.
+
+## Run a bounded Python task
+
+Open PowerShell in the Python repository you want Truth Firewall to work on, then run:
+
+```powershell
+truth-firewall init
+notepad .\.truth-firewall\task.json
+truth-firewall activate
+truth-firewall run
+```
+
+`init` asks for your task text and an optional required output file. It runs locally without an LLM and validates `.truth-firewall/task.json` using the same spec loader as `run`. A supplied file creates only a file-existence starter check; leaving it blank creates a clearly marked editable template. Both remain unreviewed and cannot authorize completion. Review the file and add checks for **every mandatory requirement**, replacing any `EDIT_ME` placeholder, then explicitly confirm with `truth-firewall activate`. An unreviewed spec stops before Codex starts. Truth Firewall cannot infer omitted requirements or guarantee that review makes the checks complete. Existing task files are preserved unless you explicitly use `truth-firewall init --overwrite`. Existing manually authored `--spec` contracts remain supported; an `EDIT_ME` placeholder always blocks completion. The verifier cannot infer from arbitrary task prose that a check targets the intended source file, so inspect paths carefully. See [QUICKSTART.md](QUICKSTART.md) for examples and PATH troubleshooting; clone/venv development setup is in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Activation records a SHA-256 digest of the reviewed task and checks. If you edit the task or checks afterward, `run` returns `HUMAN_REQUIRED` before Codex starts; review the changed contract and run `truth-firewall activate` again. The digest detects ordinary edits, not deliberate rewriting of both the contract and its digest by someone with access to your files.
+
+Legacy manually authored specs remain accepted without review metadata. If both `acceptance_review` and `onboarding_note` are removed from a generated concrete starter, it becomes indistinguishable from a legacy spec; keep those fields and use `activate` after reviewing the checks.
+
+The supported checks are `file_exists` (a repository-relative path exists or does not exist), `python_function` (a top-level function has the exact parameter list), and `black_box` (JSON argument lists produce expected return values). Give each condition a unique `id`. Every listed condition is mandatory, and requirements missing from `task.json` cannot be verified.
+
+## What the decisions mean
+
+- `VERIFIED_DONE`: all listed mandatory checks passed for the observed final repository state. The terminal shows the original task, check summary, and attempts used.
+- `REJECT_DONE`: a worker completion claim failed at least one mandatory check. This is an intermediate decision; Truth Firewall sends actionable failures back to Codex and continues within the three-attempt limit.
+- `HUMAN_REQUIRED`: completion could not be proven, including when attempts are exhausted or a mandatory condition cannot be checked. Review the named requirements and decide what to do next.
+- `ERROR`: the worker, verifier, or runtime could not complete the run. This is an execution problem, not a verdict that the task failed.
+
+## Why this exists
+
+A worker saying “done,” code existing, or worker-owned tests passing does not establish that your original requirements were met. Truth Firewall checks the acceptance conditions you supplied after each attempt and blocks an unsupported completion claim. It can continue Codex automatically when a check fails, so you do not have to watch each turn.
+
+## What `VERIFIED_DONE` actually means
+
+It means the listed mandatory checks passed on the final observed workspace state. It does **not** prove that an omitted requirement was met, that the checks themselves are complete, or that all possible behavior is correct. Author the checks to cover the task before you start; if the supported checks cannot establish completion, treat the outcome as requiring human judgment.
+
+## Current pilot scope
+
+This first release supports local repositories, bounded Python coding tasks, a Codex CLI worker, deterministic file/API/input-output checks, and at most three worker attempts. A small local run summary is written under `.truth-firewall\runs\<run-id>\summary.json`; it records the decision and attempt counts without task text or source code.
+
+## Limitations
+
+This is not a hostile-worker security boundary or a claim of universal correctness. Codex runs as your normal user and can access files available to that account, including the task specification. Use disposable or nonsensitive repositories for the pilot. Subjective quality, UI behavior, deployment, external services, broad repository work, and requirements that cannot be observed with the supported checks are outside this pilot.
+
+## Privacy
+
+Truth Firewall does not automatically upload telemetry, source code, or task text. Codex sends task instructions and the context it reads to its configured service under your account settings. Detailed local invocation logs are stored in the operating system's temporary directory and may contain the task prompt and worker output. Review those settings before using private code.
+
+## Feedback and license
+
+Trying Truth Firewall on a real task? Please use [PILOT_FEEDBACK.md](PILOT_FEEDBACK.md). Contribution guidance and local test commands are in [CONTRIBUTING.md](CONTRIBUTING.md). Truth Firewall is [MIT licensed](LICENSE).

truth_firewall-0.1.0/docs/PUBLISHING.md

@@ -0,0 +1,166 @@
+# Publication checklist (manual publication only)
+
+The initial candidate is `truth-firewall` version `0.1.0`, from
+`https://github.com/aldi949/truth-firewall`. The reviewed packaging baseline
+is `5536cc7fa451354fb1e8fa53f341da6932ac22fa`. Packaging changes must be reviewed
+before they are committed, pushed, tagged, or published. None of those actions is
+authorized by running the local checks.
+
+On 2026-10-13, `https://pypi.org/pypi/truth-firewall/json` returned HTTP 404.
+No existing project was visible. This does not reserve the name or establish that
+PyPI will accept it. Recheck immediately before publication. If another publisher
+owns the name, stop: do not install or upload an unrelated package. Choose a new
+distribution name with the owner and update metadata/docs/tests together.
+
+## Build and inspect
+
+Use Python 3.11+ in a development environment. The product has no runtime
+dependencies. Build, test, pipx and upload-validation tools are development tools:
+
+```powershell
+python -m pip install build==1.6.1 twine==7.0.0 pipx==1.17.14 pytest==9.1.1
+python -m pytest
+python -m build
+python -m twine check --strict dist/*
+python tools/check_dist.py dist
+$wheel = (Get-ChildItem dist/*.whl).FullName
+python tools/check_pipx.py --wheel "$wheel" --work "$env:TEMP\TF candidate check"
+```
+
+The check directory must be new. `check_pipx.py` uses private pipx paths, launches
+the installed executable outside the repository, checks all seven bundled demo
+fixtures, completion controls, review invalidation, and missing-runtime errors,
+then tests reinstall, same-artifact upgrade, and uninstall. It does not modify
+the user's normal pipx installation or PATH. Hosted checks keep pipx storage ASCII
+because pipx's shared-library path handling on Windows Python 3.11 failed in a
+non-ASCII storage path; installed CLI checks still run in non-ASCII project paths.
+See QUICKSTART for the explicit storage workaround. An optional `--upgrade-wheel` can
+test a later locally built version via a local-only package resolver. Such a
+test-only version must never be published as the release candidate.
+
+Rebuild the sdist into a wheel in a fresh directory and install that wheel too.
+Record archive contents and SHA-256 hashes. Check that version `0.1.0` in
+`pyproject.toml`, `truth_firewall.__version__`, and wheel metadata agree. Update
+both version declarations deliberately for a later release; never overwrite a
+version already uploaded to PyPI. The `package-checks.yml` workflow runs tests,
+builds, archive checks, pipx checks and sdist installation on Windows and Linux
+with Python 3.11 and 3.14, and uploads downloadable artifacts. It has only
+`contents: read`, no OIDC permission, no publishing step, and no credentials
+persisted in its checkout. New hosted CI results remain NOT_RUN until the changes
+are explicitly approved and pushed; local Windows execution is separate evidence.
+
+For a bounded real integration check, run `tools/smoke_installed.py --exe ...
+--python ... --work ... --real-codex` against the actual installed executable and
+its pipx interpreter. This requires separately installed Node.js, Codex CLI, and
+valid Codex authentication. Without the flag, the positive/negative controls call
+the installed verifier directly and are **not** a real end-to-end Codex run.
+
+## Deliberate Trusted Publishing setup
+
+The prepared `.github/workflows/publish-pypi.yml` has only a manual dispatch
+trigger; adding or merging it does not publish a package. Before enabling it on
+main, verify the `pypi` environment's branch restriction and the manual-only trigger.
+Pending-publisher setup requires the PyPI owner's authenticated account. No PyPI
+publisher configuration is implied by the presence of this workflow.
+
+After explicit setup approval, and before a separately authorized publication:
+
+1. Recheck the name and the exact approved source revision and artifacts. Require
+   all local gates and hosted Windows checks for that revision to pass.
+2. Create a GitHub environment named `pypi`, restricted to the `main` branch only
+   (not tags). The sole maintainer explicitly chose no required reviewers and no
+   self-review prevention. Verify the exact branch policy. This configuration has
+   no GitHub deployment approval gate: the operator must obtain the owner's
+   separate explicit publication approval before manually dispatching a release.
+3. In the PyPI owner's account, add a **pending Trusted Publisher** with project
+   `truth-firewall`, owner `aldi949`, repository `truth-firewall`, workflow filename
+   `publish-pypi.yml`, and environment `pypi`. A pending publisher does not reserve
+   the name. Do not put an API token in this repository.
+4. Only after setup authorization and verified environment restriction, merge the
+   prepared `.github/workflows/publish-pypi.yml`. Keep it manual-only.
+   Do not add push, tag, release, or pull-request publication triggers.
+
+The prepared workflow uses the following official actions pinned to revisions
+inspected during preparation. Review those revisions again before publication:
+
+```yaml
+name: Deliberate PyPI publication
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Approved version (must match pyproject.toml)
+        required: true
+        type: string
+permissions:
+  contents: read
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.11'
+      - run: python -m pip install build==1.6.1 twine==7.0.0 pytest==9.1.1
+      - name: Confirm approved version
+        env:
+          APPROVED_VERSION: ${{ inputs.version }}
+        run: python -c "import os,tomllib; assert tomllib.load(open('pyproject.toml','rb'))['project']['version'] == os.environ['APPROVED_VERSION']"
+      - run: python -m pytest
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python tools/check_dist.py dist
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: approved-pypi-artifacts
+          path: dist/*
+          if-no-files-found: error
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: approved-pypi-artifacts
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+```
+
+Do not dispatch the workflow until publication is explicitly authorized. Obtain
+the owner's approval of the exact source commit and version first. Manual-only
+dispatch does not technically prevent a repository user with sufficient access
+from initiating publication; the environment restricts the deployment ref only. See
+[PyPI's pending-publisher instructions](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+and [environment restrictions](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+## Public verification after publication (G12)
+
+Before publication, G12 and `PUBLIC_PYPI_INSTALL` must remain **NOT_RUN**. Local
+wheels and GitHub installs cannot satisfy this gate.
+
+After approval and upload, use a new environment and the real public index:
+
+```powershell
+pipx install truth-firewall
+pipx list
+truth-firewall --version
+truth-firewall --help
+truth-firewall demo
+```
+
+Confirm the installed distribution identity, version, dependencies and bundled
+fixtures against the approved artifact; then repeat unreviewed blocking, activation,
+review invalidation and a bounded real task. Independently download the PyPI wheel
+and compare its SHA-256 to the approved upload. Only then remove the planned-command
+label from README/QUICKSTART and claim verified public PyPI installation.
+
+Review and hashing do not solve omitted natural-language requirements, stale-target
+or incomplete acceptance checks, malicious same-user rewriting of contract/digest,
+or legacy metadata-removal ambiguity. Preserve those existing limitations.