Reckon models sprints, milestones, ROI and effort — all of which answer when and
how much. None answers toward what. A milestone is a dated target that
completes and is gone; a project's durable direction is a different kind of object, and its
absence shows: across twelve mounted projects and 352 plans, the phrase "north-star" already
appears as prose in dozens of imas-ambix documents, doing real work informally
with no structure behind it.
The purpose of making it structural is not decoration. It is to make it visible when a plan points nowhere. The majority of plans should point at a north-star; a project should carry a handful at most, because a dozen directions is no direction.
North-stars in project state. A north_stars collection
alongside sprints and milestones in docs/state/<project>/, each carrying a
stable id, a name, a one-sentence statement of what winning looks like, and an optional
href to a strategy or research document. The href is the escape
hatch that keeps the entry cheap while allowing depth where a direction needs argument rather
than a sentence. Schema-validated with an advisory cap on the count, so a project drifting
past a handful is reported rather than silently accepted.
The plan label. <meta name="plan-north-star">, parsed
into plan state and validated against the owning project's declared set. A plan naming an
unknown north-star is a wiring finding, consistent with how dangling dependency slugs are
already handled.
Server prominence. A north-star band on the cockpit showing each direction, its statement, and how much live work points at it; a badge on plan pages and in the plan list; a filter on the plans list. Follow the repository's minimal-ink discipline — aligned labels and hairline rules, no card grids or status pills, and a table where the content is labels and values.
Orientation reporting. roadmap gains a per-north-star rollup
— plans, completion and remaining effort pointing at each — plus an
unoriented-plan finding at info severity for live actionable plans that declare
none. Info rather than warn: an unoriented plan is a prompt to think, not a defect to
block on.
Adopt it here first. Declare reckon's own north-stars and label the seven plans of sprints S7 to S9 against them. Partner projects adopt when they choose; the label is optional everywhere and its absence never blocks execution.
| Measure | Required evidence |
|---|---|
| Declared and rendered | Reckon's own north-stars are declared in project state and render in the cockpit band with their statements and live-work counts. Screenshot banked as a figure. |
| Plans point at them | All seven S7–S9 plans carry plan-north-star, each resolving to a declared
id, shown as a badge on the plan page and filterable in the list. |
| Dangling reference caught | A test proving a plan naming an undeclared north-star produces a wiring finding rather than passing silently. |
| Orientation rollup | roadmap reports plans, completion and remaining effort per north-star,
and lists unoriented live plans at info severity. Recorded output for reckon. |
| Count discipline | A test proving a project exceeding the advisory cap is reported, and that the report does not block a write. |
| Optional everywhere | A project with no north-stars declared, and a plan with no label, both continue to read, scan and execute unchanged — asserted by test against an unmigrated project. |
| Suite green | Full reckon suite passes; new-test count recorded. |
Declaring reckon's own directions was blocked by a gap the earlier work left behind. The
collection validates, composes and reads correctly, and the served surfaces render it — but it
cannot be written through the documented write surface. edit_plan refuses
north_stars with unsupported index set path, because the allowed set of
top-level project keys admits only active_sprint_id. Validation was added at the
project-state layer and exercised through that layer's own writer, so nothing in the node's own
gate detected that the surface every agent actually calls has no route to it.
Hand-editing the state file would have hidden exactly that: the adoption step would have succeeded while the write path stayed missing and untested, and the next project to adopt a direction would hit the same wall with no test to explain it. So the write path comes first and adoption follows it.
The general lesson is worth stating beyond this collection: a state field is finished when it is writable, readable and rendered through the same surfaces its neighbours use. A field that only one internal writer can reach is a field with a private door.
| Measure | Required evidence |
|---|---|
| Writable through the tool | Setting the whole collection through edit_plan succeeds and the value
round-trips through a subsequent read, asserted by test. |
| Addressable per entry | A single entry's field is settable by id in the same dotted style sprints and milestones already use, asserted by test. |
| Validation still applies | A write missing a required field, and one carrying a duplicate id, are both refused through the tool rather than only through the internal writer. |
| Advisory cap still advisory | A write exceeding the cap succeeds through the tool and returns the warning, matching the behaviour already proven at the state layer. |
Once the write path exists, reckon declares its own directions and every plan of the three execution sprints points at one. Four are proposed, inside the advisory cap of five, each a durable direction rather than a dated target:
| Direction | What winning looks like |
|---|---|
| State that tells the truth | Every status, number and gate verdict is derived from evidence a reader can re-check, and nothing computable is stored as an assertion. |
| Unattended execution | An orchestrator carries a sprint from ready node to committed evidence without a human in the loop, and holds recoverably rather than failing when it must stop. |
| Legible to human and agent alike | A person and an agent read the same plan state through surfaces suited to each, with neither a second store nor a second truth. |
| Portable across harnesses | Reckon's contracts hold whichever agent harness runs the work, so adding a backend never adds a second execution path. |
The plan's prose says seven plans span the three sprints; the sprint resources hold eight. All eight are labelled, and each of the four directions receives at least one — which is the useful check on the set, since a direction nothing points at is either premature or misnamed.
| Measure | Required evidence |
|---|---|
| Declared | The four directions are present in project state and returned by a read of the project resource. |
| Every plan oriented | All eight plans of the three execution sprints carry a label resolving to a declared id, and the dependency scan reports no undeclared-reference finding. |
| Rollup non-trivial | The per-direction rollup reports a non-zero plan count for each of the four, with the recorded figures. |
| Rendered | The cockpit band shows the four with their live-work counts against a restarted server, banked as a figure. |
How is a north-star modelled?
Reuses the existing rollup machinery that sprints and milestones already use, and the optional href gives prose room without adding a typed root, route resolution, schema type and archive path. A milestone flavour was rejected because milestones complete and north-stars do not — conflating a dated target with a durable direction loses the distinction that makes the label worth having.
How severe is a live plan that declares no north-star?
Orientation is a prompt to think about direction, not a structural fault. Raising it to warn would put it beside genuine wiring errors and train readers to ignore the category. Some plans legitimately point nowhere — infrastructure repairs and cleanups among them.
Land the project-state collection with schema and advisory cap, the plan meta label with dangling-reference validation, cockpit prominence and a plans filter, the roadmap orientation rollup with an info-severity unoriented finding, then declare reckon's own north-stars and label the S7–S9 plans.
/reckon-ship north-star-orientation
Everything §5 needs is landed and green: the collection is writable through edit_plan (commit e8efbc7, 5 tool-boundary tests), the rollup reports per-direction work, and the cockpit band, plan badge and list facet all render. The declaration itself cannot be written from this session because server, parse and render code is not hot — the running HTTP server and every connected MCP stdio process hold the pre-merge code, so both write routes still refuse north_stars with unsupported index set path, and reckon exposes no CLI route to project state.
The unblock is reckon service restart plus an MCP reconnect. That was not taken unilaterally: this server is shared infrastructure that several concurrent agent sessions on this workstation read, and restarting it out from under them is the lead's call rather than a coordinator's. The same restart discharges the four measures across this sprint that need a live instance — the cockpit screenshot here, the 3-second dispatch-to-working latency and the ss -ltnp single-listener check on in-flight visibility, and the watcher navigability screenshot.
After the restart: declare the four directions on the project resource, label all eight plans of the three execution sprints, then re-run the dependency scan and confirm no undeclared-reference finding and a non-zero plan count against each direction.
/reckon-ship north-star-orientation §5