Complete governed planning CLI and documentation

Author: Shashankss1205

ARCHITECTURE.md

@@ -366,31 +366,36 @@ already-approved path.
 
 ### The gaps that matter
 
-The first four are seams: a subsystem that exists and works, sitting next to a
-subsystem that does not know it exists. They are ROADMAP §12.
-
-1. **Nothing shipped drives the loop.** `grapharc.planner` is imported by no
-   other module in the package: no CLI command, no example graph, no session
-   graph. The cycle above is a library API proven by tests and by the run
-   described above — not something a reader can invoke and watch. Until there
-   is a `grapharc plan`-shaped entry point, ①→③ is a diagram, not a path.
-2. **Policy does not reach admission.** `AdmissionChecker` takes an `EdgePolicy`
-   assembled in Python. `grapharc.policy` parses a TOML document that already
-   understands `node`, `edge`, `tool` and `spend` rules — and there is no bridge
-   between the two, nor any caller of either from the agent or the CLI. Box ④
-   is enforced by code an operator writes in Python, not by the declarative
-   document that was built for it.
+One seam is left: a subsystem that exists and works, sitting next to a
+subsystem that does not know it exists. It is ROADMAP §12.3. Two gaps that were
+here are closed, and are recorded below so the shape of the fix is not lost.
+
+1. *Closed — the loop has a surface.* `grapharc plan <goal>` drives propose →
+   admit → materialise → execute → replan and prints every round with its
+   admission status and rejection codes. ①→③ is a path, not a diagram.
+   `grapharc/examples/plan_incident.py` supplies the kinds; `--registry
+   module:attr` replaces them, along with the `STATE_SCHEMA` and `WRITES` a
+   registry needs to be usable.
+2. *Closed — policy reaches admission.* `PolicyEngine.edge_policy(tenant=…)`
+   compiles the document's `edge` rules into the `EdgePolicy` the checker
+   consults, mirroring `permission_policy()` on the tool side, and `grapharc
+   plan --policy` calls it. Box ④ can now be enforced by the declarative
+   document. What the compiled object still cannot carry is the approver role
+   and the audit record, because `EdgePolicy.decide` returns a bare `Decision`;
+   and nothing yet routes the *tool* plane through the document, so `grapharc
+   agent` is still governed by Python objects.
 3. **The HTTP API and the session runtime are two different things.**
    `grapharc/session` gives durable, cross-process sessions: verified by running
    one interpreter to an approval hold and resuming it by id in a second, with
    each node appearing exactly once in the append-only log. `grapharc/server`
    does not use it — it has its own `InProcessRuntime` whose sessions die with
    the process, never evict, and record `message`/`approval` events without
    delivering them into a running graph. Stage ② holds; stage ① does not reach it.
-4. **The shipped graphs do not use durable memory.** `SQLiteMemoryStore` is
-   verified durable across separate processes, and every `grapharc run` command
-   still constructs the in-process `MemoryStore()`. Box ⑥'s "durable memory with
-   provenance" is true of the library and not of anything you can run.
+4. *Closed — the shipped graphs can use durable memory.* `grapharc run
+   --memory PATH` hands `stage6` and `capstone` a `SQLiteMemoryStore`, verified
+   across a real process boundary; in-process remains the default so a plain run
+   writes nothing nobody asked for. Box ⑥'s "durable memory with provenance" is
+   now true of something you can run.
 
 The fifth is not a seam but a boundary, and it is the one most likely to be
 over-read:

HANDOFF.md

@@ -66,6 +66,18 @@ is why the Claude-CLI gateway backend exists. Run tests with
 `.venv/bin/python -m pytest`. **Never run `pytest -m live` casually — those call
 paid APIs and cost real money.**
 
+> **The subscription buys inference, not agency.** `ClaudeCodeCLIChatModel`
+> implements no `bind_tools`, so it **cannot drive `grapharc agent`** — the very
+> milestone this handoff leads with. That is deliberate, not unfinished: `claude
+> -p` is itself a full agent with its own tools and its own loop, and letting it
+> call tools would put the control plane inside a subprocess GraphARC cannot see
+> or veto, which is the architecture this project exists to replace. So the
+> adapter strips it to pure inference (`--disallowedTools`, `--setting-sources
+> ""`, empty cwd, no session). Consequence to plan around: any node that needs a
+> model to *think* runs free on `claude-cli`; any node that needs a model to
+> *drive tools* needs OpenRouter and real money. `grapharc agent` refuses with a
+> clear error rather than degrading.
+
 > ### The `-qq` trap — read this before you believe a test run
 >
 > `addopts` in `pyproject.toml` is `-q -m 'not live' --strict-markers
@@ -284,23 +296,41 @@ choose which one that is.
 
 `ARCHITECTURE.md` §7 is the current, re-derived gap analysis — **read it rather
 than trusting a copy here**, since a copy is exactly what went stale last time.
-In one line each, the five gaps it names:
-
-1. **Nothing shipped drives the loop.** `grapharc.planner` is imported by no
-   other module: no CLI command, no example, no session graph. The cycle is a
-   library API proven by tests, not something a reader can invoke and watch.
-   **This is the highest-value thing left.**
-2. **Policy does not reach admission.** `grapharc.policy` parses a TOML document
-   that already understands `node`/`edge`/`tool`/`spend` rules;
-   `AdmissionChecker` takes an `EdgePolicy` assembled in Python. No bridge.
-3. **The HTTP API and the session runtime are two different things.**
+Four of the five gaps that version named are now closed. What is left:
+
+1. **The HTTP API and the session runtime are two different things.**
    `grapharc/server` has its own `InProcessRuntime` whose sessions die with the
-   process. The durable, cross-process `grapharc/session` is not what it uses.
-4. **The shipped graphs do not use durable memory.** Every `grapharc run`
-   constructs the in-process `MemoryStore()`, though `SQLiteMemoryStore` is
-   verified durable across processes.
-5. **Admission authorises a kind, not its arguments** — a boundary, not a seam,
+   process and whose approvals are recorded without being delivered. The
+   durable, cross-process `grapharc/session` is not what it uses. **The last
+   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.
+
+Closed since, each with a shipped caller and tests:
+
+- **`grapharc plan <goal>`** drives propose → admit → materialise → execute →
+  replan, printing every round and its rejection codes. Scripted and free by
+  default; `--model` for a real backend, `--registry module:attr` for your own
+  kinds. `grapharc/examples/plan_incident.py` is the demo registry, built so the
+  default run *shows* a refusal: `deploy` is registered and every edge into it
+  denied, so round 1 is refused on `edge_denied` and round 2 replans without it.
+- **`PolicyEngine.edge_policy(tenant=…)`** compiles the TOML document's `edge`
+  rules into the `EdgePolicy` `AdmissionChecker` consults, and `grapharc plan
+  --policy` is the caller. The test that matters: with a `*->deploy` deny rule in
+  the file round 1 is refused; delete the rule and the same run admits it. The
+  document constrains the run rather than answering questions about one.
+- **`grapharc run --memory PATH`** hands `stage6` and `capstone` the durable
+  `SQLiteMemoryStore`. In-process stays the default. Proved across a real
+  process boundary, not just in one interpreter.
+- **`cost_usd` on trace events.** Both gateways publish the provider's price
+  through the same `llm_output` envelope; the runtime's usage callback writes it
+  onto the node's `end` event and an agent writes the per-call figure onto each
+  `model` event. `recorded_cost_usd` is a measurement again, and a backend that
+  reports no price still falls back to a `RateCard` estimate without the two
+  mixing.
 
 ---