Project-level legibility: run-to-roadmap binding, orro status, worktree hygiene, plan-drift surfacing

[moonweave]

Problem (operator-reported, 2026-07-22)

Run-level honesty is solved (evidence, verdicts, receipts). Project-level work with AI agents is still illegible. Recurring operator pains, verbatim in intent:

1. "Is it looking at the right doc?" — a run never declares which spec/plan it serves, so reading/working off the wrong document is silent.
2. "There was a plan, but it ended up not being followed." — plans exist as documents, not as gates; off-plan work proceeds silently.
3. "Worktrees pile up and nothing gets tidied." — runtime-created worktrees/artifacts have no inventory or lifecycle.
4. "Where on the roadmap are we? What is finished and what is not?" — roadmap-item completion is not bound to evidence; status lives in prose/memory, not in verifiable state.
5. "Automation keeps saying there is a next step" — no single view that says: item X done (evidence ref), item Y in progress (run dir), item Z not started.

Direction (not committed; spec after more real-usage instances)

• Run→roadmap binding: every proofrun/check declares the roadmap/spec item it serves; sealed into evidence; unbound runs are surfaced (off-plan work becomes visible, not blocked by default).
• orro status: read a single roadmap ledger; render per-item state bound to evidence (done = verdict ref, in-progress = run dir, not-started).
• Workspace hygiene: inventory + cleanup for witnessd-created worktrees/run dirs.
• Honest boundary: the tool surfaces binding/drift after the fact; keeping ONE source-of-truth spec per initiative remains an operator/orchestrator practice the tool cannot replace.

Process

This is an epic collecting real dogfood instances before any spec. When a "is it doing the right thing?" moment happens, add a comment here with three lines: doing what / wanted to know / couldn't see. Spec work starts once enough instances accumulate to design against reality instead of speculation.

🤖 Generated with Claude Code

[moonweave]

Legibility v1 shipped (witnessd 2.16.0 on PyPI, ORRO re-pinned):

• .orro/roadmap.json ledger + honest status vocabulary (done (verified) / in-progress / marked-done (unverified) / not-started)
• --roadmap-item <id> binding on proofrun/flow/team go/check (fail-closed on unknown ids)
• orro status — per-item evidence-bound state, off-plan run surfacing, workspace summary
• orro tidy — worktree inventory (default dry-run) + safe --apply

Covers pains 2/3/4/5 from the epic body. Pain 1 ("is it looking at the right doc?") still needs a captured instance — keep adding the three-line comments here. 🤖

[moonweave]

Legibility v1.1 shipped (witnessd 2.17.0 on PyPI, ORRO re-pinned): roadmap items can now declare ordered steps (each one of the five envelopes), runs bind to (item, step) via --roadmap-step, and orro status derives per-step progress purely from evidence and prints the exact next-step command (non-executing). This is Phase A of chain legibility; Phase B (bounded chain execution via orro auto) remains a separate trust decision. 🤖

[moonweave]

Phase B shipped (witnessd 2.18.0 on PyPI, ORRO re-pinned): orro auto --run-item <id> --max-steps N executes an item's declared step chain — the exact commands orro status recommends, evidence-gated at every step (a non-verified step stops the chain, no retry, no input guessing), with honest executes_proofrun:true receipts for this mode only. Chain legibility is now closed end-to-end: declare steps → status shows evidence-derived progress + next command → auto executes the chain behind evidence gates. 🤖

[moonweave]

doing what:
I dogfooded the new orro task begin flow with Herdr as the persistent workspace runtime. It creates/resumes the persistent task worktree and opens it through ORRO_TASK_OPEN_COMMAND, so the old workmux layer is no longer needed.

wanted to know:
How should a GitHub issue such as #105 map to the local .orro/roadmap.json item ID, and where should an operator see the Herdr workspace that owns the task?

couldn't see:
The GitHub issue number is not directly accepted as a task ID; the task requires a local roadmap item. The Herdr handoff is environment-based, so existing sessions do not inherit a newly added ORRO_TASK_OPEN_COMMAND until they are restarted or given the variable explicitly. The ORRO task receipt records the open command and exit code, but not a durable Herdr workspace ID.

[moonweave]

Additional dogfooding observations from the recent ORRO sessions:

• orro task begin receipts expose the open command/exit result but still do not carry a durable Herdr workspace identifier, so it is hard to tell which external workspace owns a task after the session ends.
• Project/plan identity, observed adapter/model/context status, and the task's roadmap binding are not visible together in one status view. A run can be locally present while its source plan or model identity remains ambiguous.
• The current command surface is still easy to misread because active documentation contains removed next/report forms while the wrapper help points to newer canonical commands. This is tracked separately in Keep canonical ORRO command surface and documentation in sync after alias removals #136.

The practical question for an operator is: “Which project/plan/workspace did this task actually run against, what lane/model was observed, and where is its durable evidence?” A single status/receipt view should answer that without reconstructing several directories and session transcripts.