horsegraph 0.1.0__tar.gz

horsegraph-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.html
+*.world.json

horsegraph-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

horsegraph-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: horsegraph
+Version: 0.1.0
+Summary: Plan node graphs read through Tiny Horse canonical storage and visualized as ClaySpace worlds.
+Author: Magus
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: clayspace,dependency-graph,git,planning,tinyhorse
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: clayspace<0.2,>=0.1.3
+Requires-Dist: tinyhorse>=0.2.4
+Provides-Extra: gdrive
+Requires-Dist: tinyhorse[gdrive]>=0.2.4; extra == 'gdrive'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# horsegraph
+
+Plan node graphs (`NODE-GRAPH.json`) read through **Tiny Horse** canonical storage and visualized as **ClaySpace** worlds.
+
+- **Tiny Horse** is the source of truth. horsegraph reads the graph from a bound checkout (and can run `tinyhorse doctor` on it), or straight from the canonical bundle in storage (`file:` or `gdrive://`), or from a Drive project by name. When it reads from storage it fetches and verifies the bundle and reads the graph at canonical HEAD, so the view shows what was parked, not unparked local edits.
+- **ClaySpace** draws it. Every node is a ClaySpace Cell, every dependency is a Cell with an arrowhead, and the whole graph is a valid `clayspace.world.snapshot`. The HTML is ClaySpace's own self-contained orbit preview, plus a label, hover-detail and legend overlay.
+
+```bash
+pip install horsegraph            # add [gdrive] for Drive storage / --project
+```
+
+## Use
+
+```bash
+# from a Tiny Horse-bound checkout (default graph path docs/runner-gateway/NODE-GRAPH.json)
+horsegraph render --checkout . --doctor --out plan.html --world plan.world.json
+
+# straight from canonical storage, no checkout needed
+horsegraph render --storage gdrive://FOLDER_ID/DUD3.bundle
+horsegraph render --project "DUD3"            # resolved like `tinyhorse claim`
+
+# plan views
+horsegraph next  --checkout .                 # "Needs you now" / "Claude starts next"
+horsegraph path  --checkout .                 # critical path to the goal node
+horsegraph check --checkout .                 # validate; exit 1 on warnings (e.g. done before its deps)
+
+# any JSON file, no Tiny Horse
+horsegraph render --file examples/NODE-GRAPH.json
+```
+
+`--graph` changes the path inside the repo; `--ref` reads a tag or commit from storage instead of HEAD.
+
+The ClaySpace world it writes with `--world` opens with the usual tools (`clayspace world inspect`, `clayspace world preview`).
+
+## Reading the 3D view
+
+| Shape | Meaning |
+|---|---|
+| low green slab | done |
+| blue block | open, Claude's (agent) node |
+| tall amber tower with a flagpole | open owner action, needs you |
+| cyan | on the critical path to the goal |
+| pink + sphere | goal node |
+| grey, thin | parked (`later`, `after-proof`) |
+
+Columns run left to right by dependency depth, and rows group by track. Drag to orbit, scroll to zoom, and hover a label for the node's title, deps and the contract items it advances.
+
+## Graph format
+
+```json
+{
+  "title": "…", "goal": "G-PROOF",
+  "tracks": {"MAC": "DUD3 for Mac"},
+  "nodes": [
+    {"id": "MAC-4", "title": "…", "owner": "agent", "status": "open",
+     "deps": ["MAC-1", "MAC-2"], "track": "MAC", "closes": ["C2"]}
+  ]
+}
+```
+
+`owner` is `agent` or `owner`. `status` is `done`, `open`, `later`, `after-proof` or `available-verified`. Extra fields are kept. Cycles, unknown deps and duplicate ids are rejected.
+
+## Python
+
+```python
+from horsegraph import from_storage, render
+graph, prov = from_storage("file:/srv/git/dud3.bundle")
+print(graph.critical_path(), [n.id for n in graph.ready("owner")])
+render(graph, "plan.html", provenance=prov.to_dict(), subtitle=prov.summary())
+```
+
+## Release
+
+```bash
+python -m build && twine upload dist/*
+```

horsegraph-0.1.0/README.md

@@ -0,0 +1,76 @@
+# horsegraph
+
+Plan node graphs (`NODE-GRAPH.json`) read through **Tiny Horse** canonical storage and visualized as **ClaySpace** worlds.
+
+- **Tiny Horse** is the source of truth. horsegraph reads the graph from a bound checkout (and can run `tinyhorse doctor` on it), or straight from the canonical bundle in storage (`file:` or `gdrive://`), or from a Drive project by name. When it reads from storage it fetches and verifies the bundle and reads the graph at canonical HEAD, so the view shows what was parked, not unparked local edits.
+- **ClaySpace** draws it. Every node is a ClaySpace Cell, every dependency is a Cell with an arrowhead, and the whole graph is a valid `clayspace.world.snapshot`. The HTML is ClaySpace's own self-contained orbit preview, plus a label, hover-detail and legend overlay.
+
+```bash
+pip install horsegraph            # add [gdrive] for Drive storage / --project
+```
+
+## Use
+
+```bash
+# from a Tiny Horse-bound checkout (default graph path docs/runner-gateway/NODE-GRAPH.json)
+horsegraph render --checkout . --doctor --out plan.html --world plan.world.json
+
+# straight from canonical storage, no checkout needed
+horsegraph render --storage gdrive://FOLDER_ID/DUD3.bundle
+horsegraph render --project "DUD3"            # resolved like `tinyhorse claim`
+
+# plan views
+horsegraph next  --checkout .                 # "Needs you now" / "Claude starts next"
+horsegraph path  --checkout .                 # critical path to the goal node
+horsegraph check --checkout .                 # validate; exit 1 on warnings (e.g. done before its deps)
+
+# any JSON file, no Tiny Horse
+horsegraph render --file examples/NODE-GRAPH.json
+```
+
+`--graph` changes the path inside the repo; `--ref` reads a tag or commit from storage instead of HEAD.
+
+The ClaySpace world it writes with `--world` opens with the usual tools (`clayspace world inspect`, `clayspace world preview`).
+
+## Reading the 3D view
+
+| Shape | Meaning |
+|---|---|
+| low green slab | done |
+| blue block | open, Claude's (agent) node |
+| tall amber tower with a flagpole | open owner action, needs you |
+| cyan | on the critical path to the goal |
+| pink + sphere | goal node |
+| grey, thin | parked (`later`, `after-proof`) |
+
+Columns run left to right by dependency depth, and rows group by track. Drag to orbit, scroll to zoom, and hover a label for the node's title, deps and the contract items it advances.
+
+## Graph format
+
+```json
+{
+  "title": "…", "goal": "G-PROOF",
+  "tracks": {"MAC": "DUD3 for Mac"},
+  "nodes": [
+    {"id": "MAC-4", "title": "…", "owner": "agent", "status": "open",
+     "deps": ["MAC-1", "MAC-2"], "track": "MAC", "closes": ["C2"]}
+  ]
+}
+```
+
+`owner` is `agent` or `owner`. `status` is `done`, `open`, `later`, `after-proof` or `available-verified`. Extra fields are kept. Cycles, unknown deps and duplicate ids are rejected.
+
+## Python
+
+```python
+from horsegraph import from_storage, render
+graph, prov = from_storage("file:/srv/git/dud3.bundle")
+print(graph.critical_path(), [n.id for n in graph.ready("owner")])
+render(graph, "plan.html", provenance=prov.to_dict(), subtitle=prov.summary())
+```
+
+## Release
+
+```bash
+python -m build && twine upload dist/*
+```

horsegraph-0.1.0/examples/NODE-GRAPH.json

@@ -0,0 +1,51 @@
+{
+  "title": "DUD3 v4: Mac MCP server, phone 496, scripts, proof on Icarus",
+  "goal": "G-PROOF",
+  "tracks": {
+    "SRC": "Source and publication",
+    "MAC": "DUD3 for Mac (dude-mcp, installer)",
+    "PH": "Phone 1.2.8 (496)",
+    "SCR": "DUD3 scripts",
+    "REL": "Release and proof",
+    "THR": "Thorondor router (parallel project)"
+  },
+  "nodes": [
+    {"id": "SRC-0", "title": "DUD3 on Tiny Horse; docs switched; mirror job removed", "owner": "agent", "status": "done", "deps": [], "track": "SRC", "closes": ["C6"], "evidence": ["Tiny Horse DUD3 in_sync", "b3fccbdbe", "snx automaton rm repo-drive-mirror"]},
+    {"id": "SRC-1", "title": "Tiny Horse resumable chunked Drive uploads", "owner": "agent", "status": "open", "deps": ["SRC-1a"], "track": "SRC", "closes": ["C6"], "accept": ["16 MiB chunks, resume from Drive-reported offset, backoff, session survives restart", "If-Match conflict check kept", "md5 verified before success", "fake-Drive tests for stall/503/404/412/kill"]},
+    {"id": "SRC-1a", "title": "Tiny Horse source location", "owner": "owner", "status": "done", "deps": [], "track": "SRC"},
+    {"id": "SRC-2", "title": "Fallback: browser upload of a tinyhorse bundle as a new version of DUD3.bundle, then tinyhorse doctor", "owner": "agent", "status": "available-verified", "deps": [], "track": "SRC"},
+    {"id": "H-0", "title": "Tests isolated from live runner state (RPG-F62)", "owner": "agent", "status": "done", "deps": [], "track": "SRC"},
+    {"id": "MAC-1", "title": "Engine compiled into dude-mcp (embedded-engine-text, scrambled); remove engine-pack capsule, its ack and the refusal", "owner": "agent", "status": "done", "deps": [], "track": "MAC", "closes": ["C3"]},
+    {"id": "MAC-2", "title": "Keys on the Mac: dude-mcp key add <provider> (hidden prompt -> Keychain)", "owner": "agent", "status": "open", "deps": [], "track": "MAC", "closes": ["C2"]},
+    {"id": "MAC-3", "title": "Licence = link: tools on once a link is accepted; remove activation-token path and v3 leftovers", "owner": "agent", "status": "open", "deps": ["MAC-3a"], "track": "MAC", "closes": ["C1"]},
+    {"id": "MAC-3a", "title": "Owner: confirm dropping the activation-token path also drops headless Linux/Windows runners", "owner": "owner", "status": "done", "deps": [], "track": "MAC"},
+    {"id": "MAC-4", "title": "One-file mission format: script id/body + inputs + provider/model + sealed key, signed by phone; Mac handler writes one signed result or a plain error", "owner": "agent", "status": "open", "deps": ["MAC-1", "MAC-2", "MAC-3"], "track": "MAC", "closes": ["C2", "C3", "C4"]},
+    {"id": "MAC-5", "title": "CLI: link (QR in Terminal) + link_qr MCP tool, register, status, update, config, token", "owner": "agent", "status": "open", "deps": ["MAC-3"], "track": "MAC", "closes": ["C1", "C5"]},
+    {"id": "MAC-6", "title": "serve --http: MCP Streamable HTTP on localhost with a bearer token", "owner": "agent", "status": "open", "deps": ["MAC-3"], "track": "MAC"},
+    {"id": "MAC-7", "title": "LaunchAgent + notarized .pkg installer (Developer ID Installer) + uninstall", "owner": "agent", "status": "open", "deps": ["MAC-1", "MAC-2", "MAC-4", "MAC-5", "MAC-6"], "track": "MAC", "closes": ["C5"]},
+    {"id": "MAC-8", "title": "Delete DUD3Runner.app, its updater, v1 build receipt, legacy repository digest, menu UI", "owner": "agent", "status": "open", "deps": ["MAC-7"], "track": "MAC", "closes": ["C5"]},
+    {"id": "MAC-9", "title": "Owner-approved: retire DUD3Runner 164 and the net.llmtech.dud3p0.runner.watch LaunchAgent on this Mac when the pkg lands", "owner": "owner", "status": "open", "deps": ["MAC-7"], "track": "MAC", "closes": ["C5"]},
+    {"id": "PH-1", "title": "Phone sends one-file missions; delete prepareMissionProvider polling, engine-pack publish/ack", "owner": "agent", "status": "open", "deps": ["MAC-4"], "track": "PH", "closes": ["C3", "C4"]},
+    {"id": "PH-2", "title": "Engine scrambled in the iOS binary; leak gate's iOS profile checks engine text", "owner": "agent", "status": "open", "deps": ["MAC-1"], "track": "PH"},
+    {"id": "PH-3", "title": "Pricing in app: $0.99 unlock; grandfather paid-app buyers and Super Mode owners; remove Super Mode paywall/gates", "owner": "agent", "status": "open", "deps": ["PH-3a"], "track": "PH", "closes": ["C1"]},
+    {"id": "PH-3a", "title": "Owner: create the $0.99 non-consumable IAP in App Store Connect and send its product id", "owner": "owner", "status": "open", "deps": [], "track": "PH"},
+    {"id": "PH-4", "title": "'Connect your AI agents' screen (download link, steps); Thorondor promotion; home-screen name DUD3", "owner": "agent", "status": "open", "deps": ["MAC-7"], "track": "PH", "closes": ["C7"]},
+    {"id": "SCR-1", "title": "dud3.script/1 parser + validator (Markdown + header -> wire JSON), locked floor enforced", "owner": "agent", "status": "open", "deps": ["MAC-4"], "track": "SCR", "closes": ["C3"]},
+    {"id": "SCR-2", "title": "Starter pack: research and coding missions rewritten as scripts; one execution path", "owner": "agent", "status": "open", "deps": ["SCR-1"], "track": "SCR", "closes": ["C3"]},
+    {"id": "SCR-3", "title": "MCP: script_list, script_validate, script_save, script_run; scripts as MCP prompts", "owner": "agent", "status": "open", "deps": ["SCR-1"], "track": "SCR", "closes": ["C3"]},
+    {"id": "SCR-4", "title": "Phone: DUD3 drafts a script and sends it to the Mac (one-file)", "owner": "agent", "status": "open", "deps": ["SCR-1", "PH-1"], "track": "SCR", "closes": ["C3"]},
+    {"id": "REL-0", "title": "Owner: enable Remote Login on Icarus (centaur-macmini-1) or allow Screen Sharing", "owner": "owner", "status": "open", "deps": [], "track": "REL"},
+    {"id": "REL-0b", "title": "Icarus clean baseline: read-only inventory, owner-approved removal, record the clean state", "owner": "agent", "status": "open", "deps": ["REL-0"], "track": "REL", "closes": ["C5"]},
+    {"id": "REL-0c", "title": "Owner: an OpenRouter key in a DUD3 provider profile on the iPhone for the live routing call", "owner": "owner", "status": "open", "deps": [], "track": "REL"},
+    {"id": "REL-1b", "title": "dud3.ai: DUD3 for Mac download page for the pkg; retire runner.json and the DMG updater flow", "owner": "agent", "status": "open", "deps": ["MAC-7"], "track": "REL", "closes": ["C7"]},
+    {"id": "REL-1", "title": "Gates + artifacts: local gate, archive 496, notarize pkg, strings gate on IPA and pkg", "owner": "agent", "status": "open", "deps": ["MAC-8", "PH-1", "PH-2", "PH-3", "PH-4", "SCR-2", "SCR-3", "SCR-4", "REL-1b"], "track": "REL", "closes": ["C6"]},
+    {"id": "REL-1c", "title": "Release copy: What's New, App Review notes (guideline 3.1.3(b)), dud3.ai page text", "owner": "agent", "status": "open", "deps": ["PH-3", "PH-4", "REL-1b"], "track": "REL", "closes": ["C7", "C8"]},
+    {"id": "REL-1d", "title": "Owner approves installing the exact builds on the iPhone and the pkg on Icarus", "owner": "owner", "status": "open", "deps": ["REL-1"], "track": "REL"},
+    {"id": "G-PROOF", "title": "Proof on Icarus from the release pkg: t-tool + script from Claude Code and an IDE with the phone off; script sent from the phone; one live OpenRouter call", "owner": "agent", "status": "open", "deps": ["REL-0b", "REL-0c", "REL-1", "REL-1d"], "track": "REL", "closes": ["C1", "C2", "C3", "C4", "C5"]},
+    {"id": "REL-2", "title": "Owner approvals: exact builds; App Store submit; price Free at 496 release; publish pkg + site", "owner": "owner", "status": "open", "deps": ["G-PROOF", "REL-1c"], "track": "REL", "closes": ["C6", "C7", "C8", "C9"]},
+    {"id": "THR-1", "title": "Thorondor: OpenAI-compatible inbound API (/v1/chat/completions, /v1/models)", "owner": "agent", "status": "after-proof", "deps": [], "track": "THR"},
+    {"id": "THR-2", "title": "Thorondor absorbs dude-mcp serve-api; telemetry + learned routing on clean outcomes", "owner": "agent", "status": "open", "deps": ["THR-1", "H-0"], "track": "THR"},
+    {"id": "THR-3", "title": "DUD3 route.rs / completion.rs fallback move onto Thorondor", "owner": "agent", "status": "open", "deps": ["THR-2"], "track": "THR"},
+    {"id": "V5", "title": "Super Mode v5: cloud/browser agents via Thorondor", "owner": "agent", "status": "later", "deps": ["THR-3", "MAC-6", "REL-2"], "track": "THR"}
+  ]
+}

horsegraph-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "horsegraph"
+version = "0.1.0"
+description = "Plan node graphs read through Tiny Horse canonical storage and visualized as ClaySpace worlds."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Magus" }]
+keywords = ["tinyhorse", "clayspace", "dependency-graph", "planning", "git"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Version Control :: Git",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+  "tinyhorse>=0.2.4",
+  "clayspace>=0.1.3,<0.2",
+]
+
+[project.optional-dependencies]
+gdrive = ["tinyhorse[gdrive]>=0.2.4"]
+test = ["pytest>=7"]
+
+[project.scripts]
+horsegraph = "horsegraph.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/horsegraph"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "LICENSE"]

horsegraph-0.1.0/src/horsegraph/__init__.py

@@ -0,0 +1,18 @@
+"""horsegraph: plan node graphs read through Tiny Horse, visualized with ClaySpace."""
+__version__ = "0.1.0"
+
+from .graph import GraphError, Node, NodeGraph
+from .source import DEFAULT_GRAPH_PATH, Provenance, SourceError, from_checkout, from_file, from_project, from_storage
+
+__all__ = ["GraphError", "Node", "NodeGraph", "DEFAULT_GRAPH_PATH", "Provenance", "SourceError",
+           "from_checkout", "from_file", "from_project", "from_storage", "build_world", "render"]
+
+
+def build_world(*a, **k):
+    from .world import build_world as f
+    return f(*a, **k)
+
+
+def render(*a, **k):
+    from .world import render as f
+    return f(*a, **k)

horsegraph-0.1.0/src/horsegraph/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

horsegraph-0.1.0/src/horsegraph/cli.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .graph import GraphError, NodeGraph
+from .source import DEFAULT_GRAPH_PATH, Provenance, SourceError, from_checkout, from_file, from_project, from_storage
+
+
+def _add_source(p: argparse.ArgumentParser) -> None:
+    src = p.add_mutually_exclusive_group()
+    src.add_argument("--checkout", metavar="PATH", help="Tiny Horse-bound git checkout (default: .)")
+    src.add_argument("--storage", metavar="LOCATOR", help="Tiny Horse locator: file:... or gdrive://FOLDER/FILE.bundle")
+    src.add_argument("--project", metavar="NAME", help="Tiny Horse Drive project by exact name")
+    src.add_argument("--file", metavar="JSON", help="a NODE-GRAPH.json on disk (no Tiny Horse)")
+    p.add_argument("--graph", default=DEFAULT_GRAPH_PATH, help=f"graph path inside the repo (default: {DEFAULT_GRAPH_PATH})")
+    p.add_argument("--ref", help="commit/ref to read from storage (default: canonical HEAD)")
+    p.add_argument("--doctor", action="store_true", help="with --checkout: run tinyhorse doctor and record the relation")
+
+
+def _load(args) -> tuple[NodeGraph, Provenance]:
+    if args.file:
+        return from_file(args.file)
+    if args.storage:
+        return from_storage(args.storage, args.graph, ref=args.ref)
+    if args.project:
+        return from_project(args.project, args.graph, ref=args.ref)
+    return from_checkout(args.checkout or ".", args.graph, doctor=args.doctor)
+
+
+def _line(n) -> str:
+    return f"  {n.id:<9} {n.title}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="horsegraph",
+                                     description="Plan node graphs read through Tiny Horse, visualized with ClaySpace.")
+    parser.add_argument("--version", action="version", version=f"horsegraph {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("render", help="build a ClaySpace world and a self-contained 3D HTML view")
+    _add_source(p)
+    p.add_argument("--out", default="node-graph.html", help="HTML output (default: node-graph.html)")
+    p.add_argument("--world", metavar="JSON", help="also save the ClaySpace world snapshot here")
+    p.add_argument("--no-labels", action="store_true", help="plain ClaySpace preview, no label/legend overlay")
+
+    p = sub.add_parser("check", help="validate the graph and print stats + warnings (exit 1 on warnings)")
+    _add_source(p)
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("next", help="what can start now: Claude's nodes and yours")
+    _add_source(p)
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("path", help="critical path to the goal node")
+    _add_source(p)
+    p.add_argument("--goal", help="override the graph's goal node")
+
+    args = parser.parse_args(argv)
+    try:
+        graph, prov = _load(args)
+        if args.cmd == "render":
+            from .world import render
+            out = render(graph, args.out, provenance=prov.to_dict(), subtitle=prov.summary(),
+                         labels=not args.no_labels, world_out=args.world)
+            print(json.dumps({"html": str(Path(out).resolve()), "world": args.world,
+                              "provenance": prov.to_dict(), "stats": graph.stats()}, indent=2))
+            return 0
+        if args.cmd == "check":
+            warn = graph.problems()
+            if args.json:
+                print(json.dumps({"provenance": prov.to_dict(), "stats": graph.stats(), "warnings": warn}, indent=2))
+            else:
+                print(prov.summary())
+                print("  " + "  ".join(f"{k}={v}" for k, v in graph.stats().items()))
+                for w in warn:
+                    print("  warning: " + w)
+            return 1 if warn else 0
+        if args.cmd == "next":
+            agent, owner = graph.ready("agent"), graph.ready("owner")
+            if args.json:
+                print(json.dumps({"agent": [n.id for n in agent], "owner": [n.id for n in owner]}))
+            else:
+                print("Needs you now:")
+                print("\n".join(map(_line, owner)) or "  (nothing)")
+                print("Claude starts next:")
+                print("\n".join(map(_line, agent)) or "  (nothing)")
+            return 0
+        if args.cmd == "path":
+            chain = graph.critical_path(args.goal)
+            if not chain:
+                print("no goal: pass --goal or set \"goal\" in the graph", file=sys.stderr)
+                return 2
+            for nid in chain:
+                n = graph.nodes[nid]
+                print(f"  [{'x' if n.done else ' '}] {n.id:<9} {n.owner:<5} {n.title}")
+            return 0
+    except (GraphError, SourceError, OSError, ValueError, RuntimeError) as exc:
+        print(f"horsegraph: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

horsegraph-0.1.0/src/horsegraph/graph.py

@@ -0,0 +1,193 @@
+"""NODE-GRAPH.json model: load, validate, and derive plan views.
+
+A node graph is a JSON object with a ``nodes`` array. Each node has an ``id``,
+``title``, ``owner`` ("agent" or "owner"), ``status``, ``deps`` (ids that must
+be done first) and an optional ``track``. Extra fields (``closes``, ``accept``,
+``evidence``, ``note``) are carried through untouched.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DONE = "done"
+PARKED = frozenset({"later", "after-proof"})
+
+
+class GraphError(ValueError):
+    pass
+
+
+@dataclass
+class Node:
+    id: str
+    title: str
+    owner: str = "agent"
+    status: str = "open"
+    deps: list[str] = field(default_factory=list)
+    track: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def done(self) -> bool:
+        return self.status == DONE
+
+    @property
+    def parked(self) -> bool:
+        return self.status in PARKED
+
+    def to_dict(self) -> dict[str, Any]:
+        out = {"id": self.id, "title": self.title, "owner": self.owner,
+               "status": self.status, "deps": list(self.deps)}
+        if self.track is not None:
+            out["track"] = self.track
+        out.update(self.extra)
+        return out
+
+
+@dataclass
+class NodeGraph:
+    nodes: dict[str, Node]
+    title: str | None = None
+    goal: str | None = None
+    tracks: dict[str, str] = field(default_factory=dict)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    # ---- construction -------------------------------------------------
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "NodeGraph":
+        if not isinstance(data, dict) or not isinstance(data.get("nodes"), list):
+            raise GraphError("node graph must be an object with a 'nodes' array")
+        nodes: dict[str, Node] = {}
+        known = {"id", "title", "owner", "status", "deps", "track"}
+        for i, raw in enumerate(data["nodes"]):
+            if not isinstance(raw, dict):
+                raise GraphError(f"nodes[{i}] must be an object")
+            nid = raw.get("id")
+            if not isinstance(nid, str) or not nid.strip():
+                raise GraphError(f"nodes[{i}] needs a non-empty string id")
+            if nid in nodes:
+                raise GraphError(f"duplicate node id {nid}")
+            deps = raw.get("deps", [])
+            if not isinstance(deps, list) or not all(isinstance(d, str) for d in deps):
+                raise GraphError(f"{nid}: deps must be a list of ids")
+            nodes[nid] = Node(
+                id=nid, title=str(raw.get("title", nid)),
+                owner=str(raw.get("owner", "agent")), status=str(raw.get("status", "open")),
+                deps=list(deps), track=raw.get("track"),
+                extra={k: v for k, v in raw.items() if k not in known},
+            )
+        tracks = data.get("tracks") or {}
+        g = cls(nodes=nodes, title=data.get("title"), goal=data.get("goal"),
+                tracks=dict(tracks) if isinstance(tracks, dict) else {},
+                meta={k: v for k, v in data.items() if k not in {"nodes", "title", "goal", "tracks"}})
+        g.validate()
+        return g
+
+    @classmethod
+    def from_json(cls, text: str | bytes) -> "NodeGraph":
+        return cls.from_dict(json.loads(text))
+
+    @classmethod
+    def load(cls, path: str | Path) -> "NodeGraph":
+        return cls.from_json(Path(path).read_bytes())
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = dict(self.meta)
+        if self.title:
+            out["title"] = self.title
+        if self.goal:
+            out["goal"] = self.goal
+        if self.tracks:
+            out["tracks"] = dict(self.tracks)
+        out["nodes"] = [n.to_dict() for n in self.nodes.values()]
+        return out
+
+    # ---- checks -------------------------------------------------------
+    def validate(self) -> None:
+        for n in self.nodes.values():
+            for d in n.deps:
+                if d not in self.nodes:
+                    raise GraphError(f"{n.id} depends on unknown node {d}")
+        if self.goal and self.goal not in self.nodes:
+            raise GraphError(f"goal {self.goal} is not a node")
+        self.depths()  # raises on cycles
+
+    def problems(self) -> list[str]:
+        """Soft consistency warnings (graph is still usable)."""
+        out = []
+        for n in self.nodes.values():
+            if n.done:
+                for d in n.deps:
+                    if not self.nodes[d].done:
+                        out.append(f"{n.id} is done but its dependency {d} is {self.nodes[d].status}")
+            if n.owner not in ("agent", "owner"):
+                out.append(f"{n.id} has unknown owner {n.owner!r}")
+        return out
+
+    # ---- derived views ------------------------------------------------
+    def depths(self) -> dict[str, int]:
+        depth: dict[str, int] = {}
+        visiting: set[str] = set()
+
+        def visit(nid: str, chain: tuple[str, ...]) -> int:
+            if nid in depth:
+                return depth[nid]
+            if nid in visiting:
+                cyc = chain[chain.index(nid):] + (nid,)
+                raise GraphError("dependency cycle: " + " -> ".join(cyc))
+            visiting.add(nid)
+            deps = self.nodes[nid].deps
+            depth[nid] = 1 + max(visit(d, chain + (nid,)) for d in deps) if deps else 0
+            visiting.discard(nid)
+            return depth[nid]
+
+        for nid in self.nodes:
+            visit(nid, ())
+        return depth
+
+    def critical_path(self, goal: str | None = None) -> list[str]:
+        """Longest dependency chain ending at ``goal`` (root first)."""
+        goal = goal or self.goal
+        if not goal:
+            return []
+        depth = self.depths()
+        path = [goal]
+        cur = goal
+        while self.nodes[cur].deps:
+            cur = max(self.nodes[cur].deps, key=lambda d: depth[d])
+            path.append(cur)
+        return path[::-1]
+
+    def ready(self, owner: str | None = None) -> list[Node]:
+        """Open nodes whose dependencies are all done."""
+        out = [n for n in self.nodes.values()
+               if not n.done and not n.parked and n.status != "available-verified"
+               and all(self.nodes[d].done for d in n.deps)]
+        return [n for n in out if owner is None or n.owner == owner]
+
+    def blocked(self, owner: str | None = None) -> list[Node]:
+        out = [n for n in self.nodes.values()
+               if not n.done and not n.parked and any(not self.nodes[d].done for d in n.deps)]
+        return [n for n in out if owner is None or n.owner == owner]
+
+    def stats(self) -> dict[str, int]:
+        ns = list(self.nodes.values())
+        return {
+            "nodes": len(ns),
+            "done": sum(n.done for n in ns),
+            "open": sum(n.status == "open" for n in ns),
+            "owner_open": sum(n.owner == "owner" and not n.done for n in ns),
+            "ready_agent": len(self.ready("agent")),
+            "ready_owner": len(self.ready("owner")),
+        }
+
+    def track_order(self) -> list[str]:
+        seen: list[str] = list(self.tracks)
+        for n in self.nodes.values():
+            t = n.track or "-"
+            if t not in seen:
+                seen.append(t)
+        return seen

horsegraph-0.1.0/src/horsegraph/source.py

@@ -0,0 +1,116 @@
+"""Read a node graph through Tiny Horse.
+
+Three sources, all returning ``(NodeGraph, Provenance)``:
+
+* :func:`from_checkout` - a git checkout bound with ``.tinyhorse.toml``; the
+  provenance records HEAD, dirtiness and (optionally) ``tinyhorse doctor``.
+* :func:`from_storage` - a Tiny Horse storage locator (``file:...`` or
+  ``gdrive://FOLDER/FILE.bundle``). The canonical bundle is fetched and
+  verified, and the graph is read from its HEAD commit - no checkout needed.
+* :func:`from_project` - a Drive project by display name (as ``tinyhorse
+  projects`` lists it), resolved to its locator, then read like storage.
+"""
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from tinyhorse.config import ConfigError, load_config
+from tinyhorse.git import bundle_head, repository_state, verify_bundle
+from tinyhorse.storage import backend_for
+
+from .graph import NodeGraph
+
+DEFAULT_GRAPH_PATH = "docs/runner-gateway/NODE-GRAPH.json"
+
+
+class SourceError(RuntimeError):
+    pass
+
+
+@dataclass
+class Provenance:
+    kind: str                      # "file" | "checkout" | "storage"
+    graph_path: str
+    project: str | None = None
+    storage: str | None = None
+    commit: str | None = None
+    dirty: bool | None = None
+    relation: str | None = None    # from tinyhorse doctor, when asked
+    doctor_ok: bool | None = None
+    details: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v not in (None, [])}
+
+    def summary(self) -> str:
+        bits = [self.project or Path(self.graph_path).name]
+        if self.commit:
+            bits.append(self.commit[:12] + (" +dirty" if self.dirty else ""))
+        if self.relation:
+            bits.append(f"tinyhorse {self.relation}")
+        return " · ".join(bits)
+
+
+def from_file(path: str | Path) -> tuple[NodeGraph, Provenance]:
+    return NodeGraph.load(path), Provenance(kind="file", graph_path=str(path))
+
+
+def from_checkout(repo: str | Path = ".", graph_path: str = DEFAULT_GRAPH_PATH,
+                  *, doctor: bool = False) -> tuple[NodeGraph, Provenance]:
+    state = repository_state(repo)
+    root = Path(state.root)
+    target = root / graph_path
+    if not target.is_file():
+        raise SourceError(f"{graph_path} not found in {root}")
+    prov = Provenance(kind="checkout", graph_path=graph_path,
+                      commit=state.head, dirty=state.dirty)
+    try:
+        cfg = load_config(root)
+        prov.project, prov.storage = cfg.project, cfg.storage
+    except ConfigError as exc:
+        prov.details.append(f"not bound to Tiny Horse: {exc}")
+    if doctor and prov.storage:
+        from tinyhorse.workflow import doctor as th_doctor
+        result = th_doctor(root)
+        prov.relation, prov.doctor_ok = result.relation, result.ok
+        prov.details.extend(result.details)
+    return NodeGraph.load(target), prov
+
+
+def _git(*args: str) -> bytes:
+    proc = subprocess.run(["git", "--no-replace-objects", *args],
+                          stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if proc.returncode != 0:
+        raise SourceError(proc.stderr.decode(errors="replace").strip() or f"git {args[0]} failed")
+    return proc.stdout
+
+
+def from_storage(locator: str, graph_path: str = DEFAULT_GRAPH_PATH, *,
+                 ref: str | None = None, project: str | None = None) -> tuple[NodeGraph, Provenance]:
+    """Fetch the canonical bundle from Tiny Horse storage and read the graph at HEAD (or ``ref``)."""
+    with tempfile.TemporaryDirectory(prefix="horsegraph-") as td:
+        bundle = Path(td) / "canonical.bundle"
+        backend_for(locator).get(bundle)
+        verify_bundle(bundle)
+        mirror = Path(td) / "canonical.git"
+        _git("clone", "--quiet", "--mirror", str(bundle), str(mirror))
+        commit = _git("--git-dir", str(mirror), "rev-parse", ref).decode().strip() if ref else bundle_head(bundle)
+        try:
+            raw = _git("--git-dir", str(mirror), "show", f"{commit}:{graph_path}")
+        except SourceError as exc:
+            raise SourceError(f"{graph_path} not found at {commit[:12]} in {locator}: {exc}") from exc
+    prov = Provenance(kind="storage", graph_path=graph_path, project=project,
+                      storage=locator, commit=commit, dirty=False)
+    return NodeGraph.from_json(raw), prov
+
+
+def from_project(name: str, graph_path: str = DEFAULT_GRAPH_PATH, *,
+                 ref: str | None = None) -> tuple[NodeGraph, Provenance]:
+    """Resolve a Tiny Horse Drive project by display name and read its canonical graph."""
+    from tinyhorse.storage import resolve_google_drive_project
+    found = resolve_google_drive_project(name)  # exact match only, like `tinyhorse claim`
+    return from_storage(found.locator, graph_path, ref=ref, project=found.project)

horsegraph-0.1.0/src/horsegraph/world.py

@@ -0,0 +1,212 @@
+"""Turn a NodeGraph into a ClaySpace world and render it.
+
+Layout: x runs along dependency depth (left = no deps), z runs across rows
+inside a column (grouped by track). Every node is a ClaySpace Cell; its height
+encodes state (done = low slab, open = block, owner action = tall tower,
+parked = thin). Every dependency edge is its own Cell: a beam with an
+arrowhead, placed and yawed from the dependency to the dependant.
+"""
+from __future__ import annotations
+
+import html
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+import clayspace as cs
+
+from .graph import Node, NodeGraph
+
+DX, DZ = 7.0, 5.5          # column / row pitch, meters
+FOOT = 3.0                  # node footprint
+COLORS = {
+    "done": "#6cc070",
+    "owner": "#e7a13e",
+    "agent": "#a7d7ff",
+    "path": "#4fe0e6",
+    "parked": "#6b777d",
+    "edge": "#46545b",
+    "edge_path": "#4fe0e6",
+    "goal": "#ff7ab6",
+}
+
+
+def _height(n: Node) -> float:
+    if n.done:
+        return 0.35
+    if n.parked:
+        return 0.6
+    return 2.6 if n.owner == "owner" else 1.4
+
+
+def _color(n: Node, on_path: bool, goal: bool) -> str:
+    if goal:
+        return COLORS["goal"]
+    if n.done:
+        return COLORS["done"]
+    if n.parked:
+        return COLORS["parked"]
+    if n.owner == "owner":
+        return COLORS["owner"]
+    return COLORS["path"] if on_path else COLORS["agent"]
+
+
+def _slug(text: str) -> str:
+    return "".join(c if c.isalnum() or c in "-_." else "-" for c in text)
+
+
+def layout(graph: NodeGraph) -> dict[str, tuple[float, float]]:
+    """Node id -> (x, z) centre, columns by depth, rows grouped by track."""
+    depth = graph.depths()
+    order = graph.track_order()
+    cols: dict[int, list[Node]] = {}
+    for n in graph.nodes.values():
+        cols.setdefault(depth[n.id], []).append(n)
+    pos = {}
+    for d, col in cols.items():
+        col.sort(key=lambda n: order.index(n.track or "-"))
+        offset = (len(col) - 1) / 2
+        for i, n in enumerate(col):
+            pos[n.id] = (d * DX, (i - offset) * DZ)
+    return pos
+
+
+def node_cell(n: Node, *, on_path: bool = False, goal: bool = False) -> dict:
+    h = _height(n)
+    cell = cs.new_box_cell(cell_id=f"horsegraph:node:{n.id}", name=n.title, size=(FOOT, h, FOOT))
+    color = _color(n, on_path, goal)
+    cell["geometry"][0]["stroke"] = color          # ClaySpace preview honours per-shape stroke
+    if goal:
+        cell = cs.add_sphere(cell, object_id="GOAL", position=(0, h + 0.9, 0), radius=0.6)
+        cell["geometry"][-1]["stroke"] = color
+    if n.owner == "owner" and not n.done:
+        # a flag on owner actions so they read as "needs a human" from any angle
+        cell = cs.add_cylinder(cell, object_id="FLAGPOLE", position=(FOOT / 2 - 0.2, h + 0.6, FOOT / 2 - 0.2),
+                               radius=0.05, height=1.2, segments=8)
+        cell["geometry"][-1]["stroke"] = color
+    cell["horsegraph"] = {"node": n.to_dict()}      # host metadata; ClaySpace ignores it
+    return cell
+
+
+def edge_cell(src: str, dst: str, length: float, *, on_path: bool) -> dict:
+    """A beam along +x of ``length`` with an arrowhead at the far end; origin at the start."""
+    color = COLORS["edge_path" if on_path else "edge"]
+    thick = 0.12 if on_path else 0.06
+    beam = max(length - 0.6, 0.1)
+    cell = cs.new_box_cell(cell_id=f"horsegraph:edge:{src}->{dst}", name=f"{src} -> {dst}",
+                           size=(beam, thick, thick))
+    cell = cs.move_geometry(cell, object_id="MASS-001", position=(beam / 2, 0.25, 0))
+    cell = cs.add_prism(cell, object_id="ARROW", footprint_xz=[(beam, -0.3), (beam, 0.3), (length, 0)],
+                        y0=0.2, y1=0.3)
+    for g in cell["geometry"]:
+        g["stroke"] = color
+    return cell
+
+
+def build_world(graph: NodeGraph, *, provenance: dict[str, Any] | None = None,
+                world_id: str | None = None) -> dict:
+    pos = layout(graph)
+    path = set(graph.critical_path())
+    title = graph.title or "Node graph"
+    world = cs.new_world(world_id=world_id or f"horsegraph:{_slug(title)[:48]}", label=title)
+
+    for n in graph.nodes.values():
+        x, z = pos[n.id]
+        cell = node_cell(n, on_path=n.id in path, goal=n.id == graph.goal)
+        world = cs.place_cell(world, cell, entity_id=f"node:{n.id}", position=(x, 0, z),
+                              display_name=f"{n.id}: {n.title}")
+    half = FOOT / 2
+    for n in graph.nodes.values():
+        for d in n.deps:
+            (x1, z1), (x2, z2) = pos[d], pos[n.id]
+            x1 += half
+            x2 -= half
+            dx, dz = x2 - x1, z2 - z1
+            length = math.hypot(dx, dz)
+            cell = edge_cell(d, n.id, length, on_path=d in path and n.id in path)
+            world = cs.place_cell(world, cell, entity_id=f"edge:{d}->{n.id}", position=(x1, 0, z1),
+                                  yaw_radians=math.atan2(dz, dx), display_name=f"{d} -> {n.id}")
+    world["metadata"] = {
+        "generator": "horsegraph",
+        "stats": graph.stats(),
+        "criticalPath": graph.critical_path(),
+        "provenance": provenance or {},
+    }
+    check = cs.validate_world_snapshot(world)
+    if not check["valid"]:
+        raise ValueError("horsegraph built an invalid ClaySpace world: " + "; ".join(check["errors"]))
+    return world
+
+
+def _overlay(graph: NodeGraph, world: dict, subtitle: str) -> str:
+    """Labels, hover details and a legend layered on ClaySpace's own preview."""
+    pos = layout(graph)
+    path = set(graph.critical_path())
+    labels = []
+    for n in graph.nodes.values():
+        x, z = pos[n.id]
+        labels.append({
+            "p": [x, _height(n) + 0.5, z], "id": n.id, "t": n.title, "s": n.status, "o": n.owner,
+            "d": n.deps, "c": _color(n, n.id in path, n.id == graph.goal),
+            "k": n.extra.get("closes", []),
+        })
+    data = json.dumps(labels, ensure_ascii=False).replace("</", "<\\/")
+    stats = graph.stats()
+    legend = "".join(
+        f'<span><i style="background:{c}"></i>{html.escape(t)}</span>' for t, c in [
+            ("done", COLORS["done"]), ("Claude / agent", COLORS["agent"]), ("owner action", COLORS["owner"]),
+            ("critical path", COLORS["path"]), ("goal", COLORS["goal"]), ("parked", COLORS["parked"])])
+    return f"""
+<style>
+#hg{{position:fixed;right:14px;top:12px;background:#111c;padding:10px 12px;border:1px solid #ffffff22;border-radius:8px;backdrop-filter:blur(6px);max-width:min(360px,calc(100vw - 40px));font:12px ui-monospace,Menlo,monospace;color:#ddd}}
+#hg .lg{{display:flex;flex-wrap:wrap;gap:6px 12px;margin-top:6px}}#hg i{{display:inline-block;width:10px;height:10px;border-radius:2px;margin-right:5px;vertical-align:-1px}}
+#hgtip{{position:fixed;pointer-events:none;display:none;background:#000d;border:1px solid #ffffff33;border-radius:6px;padding:8px 10px;max-width:340px;font:12px system-ui,sans-serif;color:#eee}}
+#hgtip b{{font-family:ui-monospace,Menlo,monospace}}#hgtip small{{display:block;color:#aaa;margin-top:4px}}
+@media (max-width:640px){{#hg{{top:auto;bottom:12px;left:14px;right:14px;max-width:none}}}}
+</style>
+<div id="hg"><div>{html.escape(subtitle)}</div>
+<div>{stats['nodes']} nodes · {stats['done']} done · {stats['ready_agent']} ready for Claude · {stats['ready_owner']} waiting on you</div>
+<div class="lg">{legend}</div><label style="display:block;margin-top:6px"><input type="checkbox" id="hglab" checked> labels</label></div>
+<div id="hgtip"></div>
+<script>
+const HG={data};
+(function(){{
+  const tip=document.getElementById('hgtip'),tog=document.getElementById('hglab');
+  let shown=[];const base=draw;
+  draw=function(){{base();shown=[];if(!tog.checked)return;const b=bounds(collect());
+    ctx.font='600 11px ui-monospace,Menlo,monospace';ctx.textAlign='center';
+    for(const L of HG){{const p=project(L.p,b);shown.push([p,L]);ctx.fillStyle='#000a';const w=ctx.measureText(L.id).width+8;
+      ctx.fillRect(p[0]-w/2,p[1]-14,w,16);ctx.fillStyle=L.c;ctx.fillText(L.id,p[0],p[1]-2);}}}};
+  tog.onchange=()=>draw();
+  // start (and reset) looking down the plan: depth left->right, tracks top->bottom
+  const home=()=>{{yaw=0;pitch=-1.3;zoom=6;draw()}};
+  document.getElementById('reset').onclick=home;canvas.ondblclick=home;
+  yaw=0;pitch=-1.3;zoom=6;
+  canvas.addEventListener('pointermove',e=>{{if(drag){{tip.style.display='none';return}}let best=null,bd=18;
+    for(const [p,L] of shown){{const d=Math.hypot(p[0]-e.clientX,p[1]-8-e.clientY);if(d<bd){{bd=d;best=L}}}}
+    if(!best){{tip.style.display='none';return}}
+    const esc=s=>String(s).replace(/[&<>]/g,c=>({{'&':'&amp;','<':'&lt;','>':'&gt;'}})[c]);
+    tip.innerHTML='<b>'+esc(best.id)+'</b> · '+esc(best.o)+' · '+esc(best.s)+'<div>'+esc(best.t)+'</div>'+
+      (best.d.length?'<small>after '+best.d.map(esc).join(', ')+'</small>':'')+(best.k.length?'<small>advances '+best.k.map(esc).join(', ')+'</small>':'');
+    tip.style.display='block';tip.style.left=Math.min(e.clientX+14,innerWidth-350)+'px';tip.style.top=(e.clientY+14)+'px';}});
+  draw();
+}})();
+</script>
+"""
+
+
+def render(graph: NodeGraph, out: str | Path, *, provenance: dict[str, Any] | None = None,
+           subtitle: str | None = None, labels: bool = True, world_out: str | Path | None = None,
+           overwrite: bool = True) -> Path:
+    """Build the ClaySpace world, render ClaySpace's preview to ``out``, add the overlay."""
+    world = build_world(graph, provenance=provenance)
+    if world_out:
+        cs.save_world_snapshot(world, world_out, overwrite=overwrite)
+    out = Path(out)
+    cs.preview_world(world, out)
+    if labels:
+        page = out.read_text(encoding="utf-8")
+        page += _overlay(graph, world, subtitle or "horsegraph")
+        out.write_text(page, encoding="utf-8")
+    return out

horsegraph-0.1.0/tests/test_horsegraph.py

@@ -0,0 +1,132 @@
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import clayspace as cs
+import pytest
+
+from horsegraph import GraphError, NodeGraph, from_checkout, from_storage
+from horsegraph.cli import main
+from horsegraph.world import build_world, render
+
+EXAMPLE = Path(__file__).resolve().parents[1] / "examples" / "NODE-GRAPH.json"
+
+
+def g(nodes, **kw):
+    return NodeGraph.from_dict({"nodes": nodes, **kw})
+
+
+def test_example_loads_and_views():
+    graph = NodeGraph.load(EXAMPLE)
+    s = graph.stats()
+    assert s["nodes"] == 37 and s["done"] == 5
+    assert {n.id for n in graph.ready("owner")} == {"PH-3a", "REL-0", "REL-0c"}
+    # matches the plan page's "Claude starts next" panel
+    assert {n.id for n in graph.ready("agent")} == {"SRC-1", "MAC-2", "MAC-3", "PH-2"}
+    path = graph.critical_path()
+    assert path[-1] == "G-PROOF" and path[0] in {"MAC-3a", "MAC-1", "MAC-2"}
+    assert graph.problems() == []
+
+
+def test_cycle_and_unknown_dep_rejected():
+    with pytest.raises(GraphError, match="cycle"):
+        g([{"id": "a", "deps": ["b"]}, {"id": "b", "deps": ["a"]}])
+    with pytest.raises(GraphError, match="unknown"):
+        g([{"id": "a", "deps": ["zz"]}])
+    with pytest.raises(GraphError, match="duplicate"):
+        g([{"id": "a"}, {"id": "a"}])
+
+
+def test_done_before_dep_warns():
+    graph = g([{"id": "a"}, {"id": "b", "deps": ["a"], "status": "done"}])
+    assert graph.problems()
+
+
+def test_world_is_valid_clayspace(tmp_path):
+    graph = NodeGraph.load(EXAMPLE)
+    world = build_world(graph)
+    check = cs.inspect_world_snapshot(world)
+    assert check["valid"], check["errors"]
+    edges = sum(len(n.deps) for n in graph.nodes.values())
+    assert check["entityCount"] == len(graph.nodes) + edges
+    assert check["embeddedCellCount"] == check["entityCount"]
+    out = render(graph, tmp_path / "g.html", world_out=tmp_path / "w.json")
+    page = out.read_text()
+    assert "ClaySpace" in page and "const HG=" in page and "G-PROOF" in page
+    assert cs.validate_world_snapshot(cs.load_world_snapshot(tmp_path / "w.json"))["valid"]
+
+
+def test_edge_points_at_dependant():
+    graph = g([{"id": "a"}, {"id": "b", "deps": ["a"]}, {"id": "c", "deps": ["a"]}, {"id": "d", "deps": ["b", "c"]}])
+    world = build_world(graph)
+    from horsegraph.world import layout
+    import math
+    pos = layout(graph)
+    for e in world["entities"]:
+        if not e["entityId"].startswith("edge:"):
+            continue
+        src, dst = e["entityId"][5:].split("->")
+        yaw = e["placement"]["yawRadians"]
+        start = e["placement"]["position"]
+        length = max(p[0] for gm in e["payload"]["cell"]["geometry"] if gm["primitive"] == "prism" for p in gm["footprintXZ"])
+        end = (start[0] + math.cos(yaw) * length, start[2] + math.sin(yaw) * length)
+        target = (pos[dst][0] - 1.5, pos[dst][1])
+        assert math.dist(end, target) < 1e-6
+
+
+git_missing = shutil.which("git") is None
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True)
+
+
+@pytest.fixture
+def tinyhorse_repo(tmp_path):
+    repo = tmp_path / "proj"
+    (repo / "docs/runner-gateway").mkdir(parents=True)
+    shutil.copy(EXAMPLE, repo / "docs/runner-gateway/NODE-GRAPH.json")
+    _git(repo, "init", "-q", "-b", "main")
+    _git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "add", ".")
+    _git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "graph")
+    locator = f"file:{tmp_path / 'store' / 'proj.bundle'}"
+    (tmp_path / "store").mkdir()
+    from tinyhorse.workflow import init_project, push
+    init_project(repo, locator, "Proj")
+    _git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "add", ".tinyhorse.toml")
+    _git(repo, "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "bind")
+    push(repo)
+    return repo, locator
+
+
+@pytest.mark.skipif(git_missing, reason="git not installed")
+def test_checkout_with_doctor(tinyhorse_repo):
+    repo, locator = tinyhorse_repo
+    graph, prov = from_checkout(repo, doctor=True)
+    assert len(graph.nodes) == 37
+    assert prov.project == "Proj" and prov.storage == locator
+    assert prov.relation == "in_sync" and prov.doctor_ok
+
+
+@pytest.mark.skipif(git_missing, reason="git not installed")
+def test_storage_reads_canonical_head_without_checkout(tinyhorse_repo, tmp_path):
+    repo, locator = tinyhorse_repo
+    head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo, capture_output=True, text=True).stdout.strip()
+    # local edit that was never parked must NOT show up when reading from storage
+    p = repo / "docs/runner-gateway/NODE-GRAPH.json"
+    data = json.loads(p.read_text())
+    data["nodes"][0]["status"] = "open"
+    p.write_text(json.dumps(data))
+    graph, prov = from_storage(locator)
+    assert prov.commit == head
+    assert graph.nodes["SRC-0"].status == "done"
+    out = tmp_path / "s.html"
+    assert main(["render", "--storage", locator, "--out", str(out)]) == 0 and out.exists()
+
+
+def test_cli_file(tmp_path, capsys):
+    assert main(["check", "--file", str(EXAMPLE)]) == 0
+    assert main(["next", "--file", str(EXAMPLE), "--json"]) == 0
+    assert "REL-0" in capsys.readouterr().out
+    assert main(["path", "--file", str(EXAMPLE)]) == 0