examples: add parallel research planner registry

[only-ouc]

Summary

• add a deterministic plan_research registry demonstrating fan-out, join, fork, and fan-in
• enforce one distinct state-field write permission per investigative kind and deny page_oncall
• document the registry in the README and governance cookbook
• test the scripted CLI path, policy refusal, write boundaries, and topology trace

Testing

• uv run pytest tests/test_plan_research.py -q
• uv run pytest tests/test_readme.py tests/test_cookbook_governance.py -q
• uv run pytest tests/test_cli.py -q -k plan
• uv run pytest tests/test_planner_loop.py -q
• uv run ruff check .

The full suite was also attempted on Windows; existing platform-dependent tests requiring symlink privileges, POSIX process semantics, or the Claude CLI fail in this environment.

Fixes #51

[Shashankss1205]

Apologies for the long silence on this — the delay is on us, not on your branch.

I re-ran CI and dug into what was actually failing. Your code is fine. The only failure is one assertion, on all three Python versions:

tests/test_deep_dive.py::test_the_quoted_selection_is_what_pytest_selects
AssertionError: update the **Verified this pass** paragraph in deep-dive.md:
it says 2,151 selected, this tree has 2,155

Your four new tests move the suite from 2,151 to 2,155, and docs/deep-dive.md quotes that figure as a verified number, so tests/test_deep_dive.py deliberately fails rather than letting the line go stale. It is guarding the docs, not judging your change.

The fix

One number, on line 257 of docs/deep-dive.md:

-**Verified this pass:** `pytest` → green, 2,151 selected and 13 deselected (the live ones);
+**Verified this pass:** `pytest` → green, 2,155 selected and 13 deselected (the live ones);

The deselected count stays at 13 — you added no live tests.

That should take the run green. Sorry you had to wait on a stale figure in a paragraph; that this can happen to a contributor is a problem with the guard's ergonomics rather than with anything you did, and I'm looking at making the figure re-derive itself instead of failing a newcomer's first PR.

Thanks for the contribution — a fan-out example is exactly what #51 asked for.

[Shashankss1205]

Following up on the ergonomics half of this, since it was our problem and not yours: #119 makes that figure refreshable with one command instead of a hand edit.

GRAPHARC_UPDATE_FIGURES=1 uv run pytest tests/test_deep_dive.py

Once it lands, a branch that adds tests — like this one — runs that and commits the result, and CONTRIBUTING.md says so where you'd actually look. The check itself stays strict in CI; what changes is that the failure now tells you what to run.

Your branch doesn't need to wait for it. The single-number edit in my earlier comment still takes this green today, and I'd rather review your example than have you rebase onto process changes.

[Shashankss1205]

Merged — thank you, and sorry it took a month to get there.

To be straight about what happened, because none of it was your branch's fault:

1. The run sitting here since August was waiting for maintainer approval. Fork pull requests need a click before their workflows run, and nobody clicked. I got that wrong earlier in this thread too — I said approval was not the blocker, having re-run the old run, which skips the gate. A new run needs it. That is the actual reason this sat.
2. Once approved, the only failure on all three Python versions was tests/test_deep_dive.py — the selected-test figure, which your four tests move. Your registry and tests were green everywhere.

I brought your branch up to date with main and merged it. The figure had to equal the count after the merge, and I could not push that one line to your branch from here, so it went to main directly right behind your commit — main's head is green.

Since then the figure is refreshable with one command instead of a hand edit, which is #119, filed because this happened to you:

GRAPHARC_UPDATE_FIGURES=1 uv run pytest tests/test_deep_dive.py

CONTRIBUTING.md documents it now, under "If you added or removed a test".

Your registry does exactly what #51 asked for, verified on the merged code: 4-way fan-out from START, a 4-way join at correlate, a fork into test_hypothesis and estimate_impact, and a fan-in at write_report — 8 nodes, 13 edges, admitted. #51 is closed by this.