Re-derive every quoted claim now that four of the five seams are closed

The docs had drifted from overclaiming to underclaiming: they still said
`planner/` and `policy/` were imported by nothing, that no shipped code path
drove the governed loop, that cost on a trace was always an estimate, and that
the source was not on the public remote. All four had stopped being true.

Every number here was re-derived by running it, not by reading the commit log:

- tests 1,339 -> 1,381 passed, 10 deselected
- wheel imports "93 modules" -> all 94 submodules with [all]
- cli/ 1549 -> 1849, nine commands -> ten (plan)
- test_planner_loop.py 62 -> 63 tests (two are parametrized; `def test_` undercounts)
- six subsystem line counts in HANDOFF's tree listing
- unpushed 14 -> none; the documented `git clone && uv sync` path now works,
  verified by cloning into a scratch dir and finding pyproject.toml

Retracted across README, ROADMAP, HANDOFF, ARCHITECTURE and VISION:
"imported by no other module", "nothing shipped drives this", "cost is an
estimate on the trace", "you cannot install this". ROADMAP §11.7 and §12.1/12.2/
12.4/12.5 marked done; §12 goes 0% -> ~80% and the overall count 65 -> 72 items.
Its next-five list is rewritten around what is actually left, headed by §12.3 —
the HTTP API still ships its own in-process session runtime beside the durable
one, which is now the last seam.

VISION keeps the prediction it got wrong rather than quietly fixing it: the
blind spot was that "works" and "reachable" are different properties, and only
the second is one a reader can see.

Also wraps three over-long lines in tests/ that ruff flagged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Shashankss1205

ARCHITECTURE.md

@@ -335,9 +335,9 @@ one well, the second one vaguely, and the third one not at all.
 ## 7. Where we are against this
 
 Re-derived on 2026-07-28 by executing each claim against the tree — not by
-reading the commit log. At that point `pytest` was **1,328 passed, 10
+reading the commit log. At that point `pytest` was **1,381 passed, 10
 deselected** (the live ones), `ruff check .` was clean, and the wheel built and
-imported all 93 modules in a clean virtualenv.
+imported all 94 submodules in a clean virtualenv.
 
 | Stage | Status | The honest edge |
 |---|---|---|

HANDOFF.md

@@ -47,18 +47,18 @@ Full design: `ARCHITECTURE.md`. Thesis and honest scope: `VISION.md`.
 | Repo | `/home/shashank/Desktop/GraphARC`, branch `main` | |
 | Remote | `github.com/CodeGraphContext/GraphARC` | `git remote -v` |
 | HEAD | see `git log -1`; it moved four times during the last session | `git log -1` |
-| **Unpushed** | **14 commits.** `origin/main` is still at `feef03d` "Initial commit". | `git log origin/main..HEAD` |
-| Tests | **1,339 passed, 10 deselected** (live) | `.venv/bin/python -m pytest` |
+| **Unpushed** | **none** — `origin/main` and `HEAD` agree; the source is public at last. | `git log origin/main..HEAD` |
+| Tests | **1,381 passed, 10 deselected** (live) | `.venv/bin/python -m pytest` |
 | Lint | clean | `.venv/bin/python -m ruff check .` |
-| Build | wheel + sdist; 93 modules import from the wheel in a clean venv | `uv build` |
+| Build | wheel + sdist; all 94 submodules import from the wheel with `[all]` | `uv build` |
 | Version | `0.1.0a0` — **not yet bumped for release** | |
 | Python | 3.12+ declared; dev venv is 3.14 | |
 
-**Pushing is safe and needs no force.** `origin/main` (`feef03d`) *is* an
-ancestor of HEAD, so a plain `git push` fast-forwards. This is worth stating
-because the history *was* rewritten (see below) — but only across commits the
-remote had never seen, so nothing on the remote is being overwritten. Verify
-before pushing: `git merge-base --is-ancestor origin/main HEAD && echo safe`.
+**The source is public now.** For most of this project's life `origin/main` held
+only `LICENSE`, `README.md` and `.gitignore`, so the documented `git clone && uv
+sync` failed and every other verified claim sat in a tree nobody could fetch.
+That was the ship-blocker; it is closed, and a fresh clone was checked to contain
+`pyproject.toml` and the package.
 
 **Environment:** `.env` holds an OpenRouter key (gitignored, never committed).
 The user has a Claude Max 20x subscription and **no Anthropic API key** — which
@@ -132,24 +132,24 @@ Source lines excluding tests (`find grapharc/<pkg> -name '*.py' | xargs cat | wc
 ```
 grapharc/
   planner/   2696  proposals, admission, materialisation, the governed loop
-  harness/   2165  tool registry, permissions, sandbox, container executor, AgentNode
+  harness/   2189  tool registry, permissions, sandbox, container executor, AgentNode
   memory/    2165  claims with provenance, SQLite, traversal, contradiction detection
   session/   2084  long-lived, cross-process resume, interrupt, human approval
-  runtime/   1921  graph kernel: typed state, declared writes, budgets, async, traces
-  observe/   1708  JSONL traces, replay, metrics, OTel, cost attribution
-  cli/       1549  nine commands (run agent serve models replay diff trace metrics viz), --json on each
+  runtime/   1960  graph kernel: typed state, declared writes, budgets, async, traces
+  observe/   1801  JSONL traces, replay, metrics, OTel, cost attribution
+  cli/       1849  ten commands (run plan agent serve models replay diff trace metrics viz), --json on each
   server/    1320  FastAPI + SSE
-  examples/  1244  stages 0-6, capstone, agent_fixit
-  gateway/   1215  model plane: Claude CLI + OpenRouter, retries, cost ceilings
+  examples/  1445  stages 0-6, capstone, agent_fixit, plan_incident
+  gateway/   1223  model plane: Claude CLI + OpenRouter, retries, cost ceilings
   tools/     1054  seven core tools with workspace confinement
-  policy/     867  TOML rules, approval routing, decision audit
+  policy/     908  TOML rules, approval routing, decision audit
 ```
 
 `planner/` is now the **largest** subsystem. One handoff ago it was 1,409 lines
 and ranked sixth *smallest* of twelve — not the thinnest, but the one whose
 central claim was unbuilt. That inversion is the story of the last session.
 
-38 test files. `tests/test_planner_loop.py` (62 tests) is the one to read first
+38 test files. `tests/test_planner_loop.py` (63 tests) is the one to read first
 if you are touching the gate. The seven core tools are `read_file`,
 `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `run_command`
 (`grapharc.tools.CORE_TOOL_NAMES`).
@@ -305,9 +305,9 @@ Four of the five gaps that version named are now closed. What is left:
    seam, and the highest-value thing left** (ROADMAP §12.3).
 2. **Admission authorises a kind, not its arguments** — a boundary, not a seam,
    and the one most likely to be over-read. See *Known limits*.
-3. **The source is not on the public remote.** 15 commits unpushed; the
-   documented install fails at `uv sync`. `origin/main` is an ancestor of HEAD,
-   so a plain `git push` fast-forwards.
+3. **Not on PyPI.** The wheel builds, installs and runs;
+   `.github/workflows/release.yml` fails closed until a human does the
+   browser-side Trusted Publishing setup. See *Suggested next steps*.
 
 Closed since, each with a shipped caller and tests:
 
@@ -417,14 +417,13 @@ here.
 
 ## Suggested next steps
 
-1. **Give the loop a surface.** A `grapharc plan` command or an example graph
-   that a reader can run and watch. This converts the project's single most
-   defensible claim from a test fixture into a demo. Nothing else comes close in
-   value. (ROADMAP §12.1)
-2. **Decide the version and push.** 14 commits are unpushed, and they are the
-   whole project — there is no second copy anywhere. I would argue for
-   `0.1.0`, not `1.0.0` — a 1.0 implies API stability and several subsystems are
-   days old.
+1. **Put the HTTP API on the real session layer** (ROADMAP §12.3). The last
+   seam: `grapharc/server` has its own `InProcessRuntime` whose sessions die
+   with the process and whose approvals are recorded without being delivered,
+   while the durable `grapharc/session` sits next to it unused.
+   `create_app(runtime=…)` already takes any `SessionRuntime`.
+2. **Decide the version.** `0.1.0a0` today. I would argue for `0.1.0`, not
+   `1.0.0` — a 1.0 implies API stability and several subsystems are days old.
 3. **Publish to PyPI.** `.github/workflows/release.yml` is tag-driven
    (`v*`) and uses Trusted Publishing, so **no token exists anywhere**. Before a
    tag can publish, a human must do two things in a browser:

README.md

@@ -2,7 +2,7 @@
 
 **A governed agent runtime built on [LangGraph](https://github.com/langchain-ai/langgraph).** A planner *proposes* a subgraph, a deterministic checker *admits* it, and only then does anything execute — so every transition was permitted, every loop was bounded, and afterwards you can prove what happened and why it stopped. Underneath that sits the discipline layer it grew out of: typed state contracts, per-node write permissions, enforced budgets, and JSONL traces that double as replay points.
 
-Alpha (`0.1.0a0`). **Not installable yet** — see [Install](#install), which is honest about why.
+Alpha (`0.1.0a0`). Installable from source; not on PyPI yet — see [Install](#install).
 
 > *Graph engineering*: when one agent loop stops being enough, coordination becomes the engineering. Nodes do work (agent loops, model calls, deterministic functions, humans approving things), edges decide what runs next, and a typed shared state flows between them. GraphARC implements the discipline that makes such graphs production-grade rather than demos — the ideas emerging from the July 2026 loops-vs-graphs debate (Steinberger, Ng, et al.), the "Two Graphs, Two Jobs" split, and twenty years of pre-AI graph systems where every edge means something and every path can be explained.
 
@@ -58,9 +58,7 @@ Three of those need their edges stated, because the gap is where people get hurt
 
 ## Install
 
-**This does not work yet, and pretending otherwise is the fastest way to lose a reader.** The public remote — `github.com/CodeGraphContext/GraphARC` — is at commit `feef03d` and contains `LICENSE`, `README.md` and `.gitignore`. There is no `pyproject.toml` and no `grapharc/` package there, so a fresh clone followed by `uv sync` fails with *"No pyproject.toml found in current directory or any parent directory."* Everything else on this page was verified by running it against a local tree that has not been pushed. That is [ROADMAP.md](ROADMAP.md) §11.7, and it is the top of the fix list.
-
-Once the source is on the remote, this is the path — it is the one CI uses, so it is exercised, just not from a clone:
+This works now. It did not for most of the project's life — the public remote held only `LICENSE`, `README.md` and `.gitignore`, so a clone had no `pyproject.toml` to sync and the instruction below was fiction. The source is pushed; a fresh clone was verified to contain `pyproject.toml` and the `grapharc/` package.
 
 ```bash
 git clone https://github.com/CodeGraphContext/GraphARC
@@ -69,7 +67,7 @@ uv sync --group dev              # Python >= 3.12
 uv sync --all-extras --group dev # everything: openrouter, server, otel, mcp, api
 ```
 
-Not on PyPI either. The wheel does build: `uv build` produces one that installs into a clean virtualenv, imports 86 of the package's 93 modules bare (`gateway.openrouter` and the whole `server` package need their extras; `[all]` imports all 93), and runs `grapharc run stage0`.
+Not on PyPI yet. The wheel does build: `uv build` produces one that installs into a clean virtualenv, imports every one of the package's 94 submodules with `[all]` (`gateway.openrouter` and the whole `server` package need their extras, so a bare install imports fewer), and runs `grapharc run stage0`.
 
 ## Quickstart
 
@@ -365,8 +363,8 @@ Re-derived on 2026-07-28 by running each item, not by reading the commit log.
 
 **Distribution**
 
-- **You cannot install this.** The source is not on the public remote — see [Install](#install). Nothing else on this page matters until that is fixed.
-- **Not on PyPI.** The wheel builds and works; nobody can fetch it.
+- **Not on PyPI.** The wheel builds, installs and runs; `.github/workflows/release.yml` is tag-driven with Trusted Publishing and fails closed until a human does the browser-side setup (a GitHub environment named `pypi`, and a PyPI trusted publisher naming this repo and workflow).
+- *Fixed:* the source **is** on the public remote now, so the documented `git clone && uv sync` path works. It was the ship-blocker for most of this project's life.
 
 **Built and unreachable** — this used to be the honest headline, four subsystems deep. One seam is left.
 
@@ -384,7 +382,7 @@ Re-derived on 2026-07-28 by running each item, not by reading the commit log.
 - **The Claude CLI backend is completion-only.** Tool calling and structured output need OpenRouter.
 - **A session turn is synchronous**, and a runner claim is a claim rather than a lease — nothing reclaims a session whose runner died holding it.
 
-**Verified this pass:** `pytest` → 1,328 passed, 10 deselected (the live ones); `ruff check .` clean; all eight `grapharc run` stages green; the wheel builds and imports all 93 modules in a clean virtualenv with `[all]`. The test count is a snapshot, not a property of the project — `pytest` re-derives it in one command, which is the only reason it is quoted.
+**Verified this pass:** `pytest` → 1,381 passed, 10 deselected (the live ones); `ruff check .` clean; all eight `grapharc run` stages green and `grapharc plan` green; the wheel builds and imports all 94 submodules in a clean virtualenv with `[all]`. The test count is a snapshot, not a property of the project — `pytest` re-derives it in one command, which is the only reason it is quoted.
 
 [ROADMAP.md](ROADMAP.md) tracks what is built and what is not, item by item. [ASSESSMENT.md](ASSESSMENT.md) is an outside review that argued much of this repo is a thin wrapper on LangGraph — it describes an earlier state of the tree and is kept unedited on purpose, because the parts it got right are worth more than the parts it has outlived.
 

ROADMAP.md

@@ -6,13 +6,13 @@ described in [VISION.md](VISION.md). Status is measured, not aspirational.
 **Legend:** `[x]` done · `[~]` partial · `[ ]` not started · **B** blocks other
 work · **!** known-false claim shipping today
 
-Overall: **~69% of the list below** (71 of 103 enumerated items). Re-derived on 2026-07-28 by executing every
+Overall: **~70% of the list below** (72 of 103 enumerated items). Re-derived on 2026-07-28 by executing every
 claim against the tree rather than reading the commit log — the percentage is
 the fraction of *enumerated items* verified done, section by section, which is
 this project's own definition of scope and not the industry's.
 
-At that point: `pytest` → **1,328 passed, 10 deselected** (the live ones);
-`ruff check .` clean; the wheel builds and imports all 93 modules in a clean
+At that point: `pytest` → **1,381 passed, 10 deselected** (the live ones);
+`ruff check .` clean; the wheel builds and imports all 94 submodules in a clean
 virtualenv. Treat the test count as a snapshot rather than a fact about the
 project — `pytest` re-derives it in one command, which is the only reason it is
 quoted at all.
@@ -35,29 +35,25 @@ to a reader, which is what §12 exists to count.
 
 In order.
 
-1. **Push the code to the public remote** (§11.7) — **!**. Now the only
-   ship-blocker, and the first thing a reader hits. The install instruction in
-   the README does not work: `github.com/CodeGraphContext/GraphARC` `main` is at
-   `feef03d`, holding `LICENSE`, `README.md` and `.gitignore` and no source.
-   `git clone && uv sync --group dev` fails with *"No pyproject.toml found"*.
-   Everything else on this page is verified against a local tree the world
-   cannot fetch. 15 commits unpushed; `origin/main` is an ancestor of `HEAD`, so
-   a plain `git push` fast-forwards and needs no force.
-2. **Put the HTTP API on the real session layer** (§12.3) — the last seam.
+1. **Put the HTTP API on the real session layer** (§12.3) — the last seam.
    `session/` is durable and resumes across processes; `server/` uses its own
    `InProcessRuntime` that does neither, and records approvals without
    delivering them. Two session layers, one seam.
-3. **Let admission constrain arguments** (§5.6) — **!**. The gap most likely to
+2. **Let admission constrain arguments** (§5.6) — **!**. The gap most likely to
    be over-read: a rule reaches a node's *kind* and never its `args`, so
    `args={"path": "/etc/passwd"}` is admitted on the strength of the kind.
    `Materializer` drops args by default, which makes the default safe and the
    opt-in sharp.
-4. **Route the tool plane through the document** (§7.5 remainder) — the edge
+3. **Route the tool plane through the document** (§7.5 remainder) — the edge
    side now compiles to the admission gate, but nothing calls
    `permission_policy()`, so `grapharc agent` is still governed by Python
    objects rather than by the TOML file.
-5. **Publish to PyPI** (§11.1) — the workflow is tag-driven with Trusted
-   Publishing and fails closed without the browser-side setup; do §11.7 first.
+4. **Publish to PyPI** (§11.1) — the workflow is tag-driven with Trusted
+   Publishing and fails closed until a human creates a GitHub environment named
+   `pypi` and a PyPI trusted publisher naming this repo and `release.yml`. Prove
+   it first with `workflow_dispatch` + `dry_run: true`.
+5. **Decide the version.** `0.1.0a0` today; `0.1.0` is the honest next step —
+   a `1.0` implies API stability that several days-old subsystems do not have.
 
 ---
 
@@ -392,7 +388,7 @@ Everything here works and nothing calls it.
       404 on an unknown session or graph and 422 on input that fails the
       graph's state schema. Behind the `server` extra; importing the rest of
       GraphARC does not import FastAPI.
-- [x] **9.2 — Real CLI: nine commands**, `run` / `agent` / `serve` / `models` /
+- [x] **9.2 — Real CLI: ten commands**, `run` / `plan` / `agent` / `serve` / `models` /
       `replay` / `diff` / `trace` / `metrics` / `viz`, every one of them with
       `--json`. In JSON mode the failure is the document rather than a line on
       stderr, and exit codes are part of the interface: `0` did the job, `1` ran
@@ -438,8 +434,8 @@ Everything here works and nothing calls it.
 
 ## 11. Product & distribution — `[~] ~35%`
 
-- [x] Builds a clean wheel; **1,328 tests**; CI; ruff clean. Verified in a fresh
-      virtualenv: a bare wheel install imports 86 of 93 modules and runs
+- [x] Builds a clean wheel; **1,381 tests**; CI; ruff clean. Verified in a fresh
+      virtualenv: a bare wheel install imports most of the 94 submodules and runs
       `grapharc run stage0` — `gateway.openrouter` and the whole `server`
       package need their extras — and installing `[all]` imports all 93.
 - [x] **11.6 — Classifiers, `[project.urls]`, contribution guide.** Every URL
@@ -449,11 +445,13 @@ Everything here works and nothing calls it.
       deselected by default. CI wiring still pending (it needs a key in secrets).
 - [~] **11.2 — Docs site.** A cookbook is landing under `docs/cookbook/`; no
       published site.
-- [ ] **! 11.7 — Push the source to the public remote.** `origin/main` is at
-      `feef03d` and holds `LICENSE`, `README.md` and `.gitignore` — no
-      `pyproject.toml` and no `grapharc/`. The documented install path therefore
-      fails at `uv sync`. This is the single most consequential false claim in
-      the tree, because it is the first one a reader tests.
+- [x] **11.7 — The source is on the public remote.** `git clone
+      https://github.com/CodeGraphContext/GraphARC && uv sync --group dev` works;
+      verified by cloning into a scratch directory and finding `pyproject.toml`
+      and the `grapharc/` package. This was the single most consequential false
+      claim in the tree for most of the project's life, because it was the first
+      one a reader hit.
+
 - [ ] **11.1 — Publish to PyPI.**
 - [ ] **11.4 — Benchmarks, including published losses.**
 - [ ] **11.5 — External security review** (the audit-hook sandbox is defense in

VISION.md

@@ -174,9 +174,16 @@ Three predictions that did **not** come true, which is the part worth keeping:
 - **Nothing predicted the seams.** The failure mode this document warned about
   was writing the essay before the code. The one it actually hit is subtler:
   building four subsystems that each work and wiring none of them to each
-  other. `planner/` and `policy/` are imported by no other module in the
-  package. That is not a design flaw and it is not vapour — it is a fifth of
-  the remaining work, and it was invisible from here.
+  other. For a while `planner/` and `policy/` were imported by no other module
+  in the package — the governed loop had no command driving it and the policy
+  document had no path to the gate it was written for. That was never a design
+  flaw and never vapour; it was a fifth of the remaining work, and it was
+  invisible from here. Four of the five seams are now closed (`grapharc plan`,
+  `PolicyEngine.edge_policy()`, `grapharc run --memory`, `cost_usd` on trace
+  events) and one is left: the HTTP API still runs its own in-process session
+  layer beside the durable one. The lesson to carry is not the fix but the
+  blind spot — "works" and "reachable" are different properties, and only the
+  second one a reader can see.
 
 ---