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.

pip install horsegraph            # add [gdrive] for Drive storage / --project

Use

# 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/Demo.bundle
horsegraph render --project "Demo"            # 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

Flat graphs use columns by dependency depth and rows grouped by track. Graphs with parent relationships use nested regions and a containment outline. Borders and indentation mean containment; solid arrows mean prerequisites and dashed arrows mean authored semantic relations. Drag to orbit, scroll to zoom, and hover a label for the node's title, ancestry, deps and contract items it advances.

Graph format

{
  "title": "…", "goal": "G-RELEASE",
  "tracks": {"CLI": "Command Line Interface"},
  "nodes": [
    {"id": "CLI-2", "title": "…", "owner": "agent", "status": "open",
     "deps": ["CLI-1", "CORE-2"], "track": "CLI", "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.

Optional parent identifies the node containing a record. Missing or null means a root. Each node has at most one parent; unknown parents, invalid parent values, and containment cycles are rejected. Containment is independent of deps: it does not change readiness, blocked state, dependency depth, critical paths, or completion rules. Existing flat graphs retain their layout.

See nested containment usage and development for a synthetic example, query API, and validation commands. Accepted containment is now on canonical main; feature/nested-containment-recovery-20261006 preserves the original accepted feature commit. Provenance records implementation attribution and the isolated recovery process. Checkpoint workflow describes the required Drive-centered park, clear, and fresh-restore boundary between finite milestones.

Optional top-level relations express authored links such as challenges, revises, influenced_by, and supported_by, with explicit IDs and preserved evidence/provenance. They never change task readiness or imply confidence/truth. See typed relation API, synthetic example, and preview. Typed relations are accepted on canonical main; the original reviewed commit is preserved on feature/typed-relations-20261006.

An optional synthetic inquiry/action example records a bounded proposal, explicit authorization, one manual start, a result and a subsequent reflection. Its code inspector and read-only spatial history retain purpose, sources, budgets and unanswered questions. It is an opt-in example, not part of core graph semantics or an execution engine. This example is included in the source distribution.

Python

from horsegraph import from_storage, render
graph, prov = from_storage("file:/srv/git/demo.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

python -m build && twine upload dist/*

0.2.0

Adds nested containment, authored typed relationships, compact readable labels, full identity/provenance disclosures and robust embedded-canvas initialization. Relationships remain independent of prerequisite readiness and containment.

Four public JSON examples are included in the wheel under horsegraph/examples and can be located with importlib.resources.files("horsegraph").joinpath("examples"). Optional Python adapters and synthetic tests are included in the source distribution. Private Woolf source/annotation catalogs are intentionally omitted from public artifacts; use an explicitly supplied source catalog for archive projections.

Unreleased: 0.2.1.dev0

Independent connection layers add visibility controls for containment, prerequisites and semantic relationships, relation-type filters, and selectable connections with complete endpoint/provenance details. This Drive checkpoint is separate from the published 0.2.0 release.