feat(forgeplan-orchestra): 8 improvements from live sync — checklists from acceptance criteria, chat as evidence trail, orphan/UID/status gaps

[explosivebit]

Summary

Eight improvements to forgeplan-orchestra, all surfaced by running a real TASKS.md → Orchestra sync against a live server. Follow-up to #208 (which fixed the field-write path only).

Each item below is checked against what is actually on disk in plugins/forgeplan-orchestra/ as of v1.5.0, so the "already covered" cases are called out rather than re-litigated.

Two of these (#2 and #3) are not repairs — they are a new link between forgeplan and Orchestra, and #3 requires an explicit policy decision. Those need artifacts before implementation.

---

Already shipped in #208

8. Mechanics section — UID resolution, failedFields, send-only-changed-fields. Done in v1.5.0: 03-fields/custom-fields.md documents the full contract, /sync Step 2 builds and retains the UID maps, and both silent-failure traps are written down where implementers hit them.

---

Small documentation gaps

1. Never auto-delete orphans — add the reasoning. The prohibition already exists twice (commands/sync.md:139 "NEVER delete without explicit confirmation" + a Safety Rule for delete_entity). What is missing is why. In one real session five orphans accumulated and all five were meaningful: three renamed tasks and two pieces of work removed from the file but not actually closed. Auto-deletion would have silently destroyed them. A rule without its reason gets relaxed by the next person who finds it inconvenient.

4. Do not anchor on get_current_context; pin workspace/project UIDs. The plugin never calls it today, so this is preventive. get_current_context returns the workspace the user currently has open in the app — mid-run a user clicked into another space and the same script resolved a different spaceUid and reported the target project missing. Had it been writing rather than reading, it would have written into the wrong workspace and reported success. Add an explicit rule: resolve and pin the workspace + project UID once; use get_current_context only to report a mismatch.

6. Blocked is missing from the Status mapping. 03-fields/custom-fields.md maps Backlog / To Do / Doing / Review / Done. Live workspaces carry a sixth Status option, Blocked, which the mapping does not mention — so a blocked task has no defined Phase counterpart.

7. Group tasks under their artifact, with the real title. Neither parent nor move_entity appears in the playbook scenarios, so tasks land flat. Titles should come from the artifact itself (forgeplan get) rather than being reconstructed.

---

New functionality — needs artifacts first

2. Checklists from acceptance criteria. The plugin does not work with checklists at all: manage_checklist is never mentioned; "checklist" appears three times in passing (as something Orchestra owns, and as "add a checklist" in one brownfield step). Meanwhile forgeplan already holds exactly the content that maps onto them one-to-one — acceptance criteria from PRD/SPEC, and ## Implementation Phases from RFC.

The value is that acceptance criteria stop being dead text inside an artifact and become something visible on the card that cannot be closed without passing. Used as a gate in practice, a "Done with an unfinished checklist" check immediately found four tasks closed without walking their items — one of them closed with the note "deferred", i.e. not because it was done.

3. Chat as the evidence trail. The plugin syncs artifacts and tasks but never touches chat. Minimal version: post the verdict into the parent task's chat when an EVIDENCE artifact is activated, plus five markers (▶ START, ✗ DEAD END, ! FINDING, ✓ GATE, → HANDOFF) so that search_messages("DEAD END", chatUid) returns every dead end for that task.

This conflicts with a standing prohibition and cannot be added quietly. send_message appears four times in the plugin and every occurrence is a ban — commands/sync.md:146 reads "NEVER use mcp__orch__send_message (safety rule — no automated messages)", and both READMEs plus orchestra-advisor.md repeat it. The MCP server's own instructions say the same: messages are visible to the whole team and trigger push notifications. Auto-posting an EVIDENCE verdict is an automated message. So this is a policy change: decide what exactly is permitted (e.g. only structured marker lines, opt-in per workspace), then rewrite the rule — do not route around it.

5. Description idempotency via a fingerprint, not a text diff. Descriptions are stored as blocks and re-rendered on read, so what comes back is never what went in (## Why dropped, - item → * item, _text_ → *text*). A read-compare-write idempotency check therefore never converges: the integration rewrites every description on every run and destroys any human edit made in the UI. The workaround is to embed a fingerprint of the source in the body and compare that. The plugin does not touch descriptions today, so this is preventive — but it must be settled before it does.

---

The bigger point

Items 2 and 3 are the reason the integration was built in the first place. Right now the plugin syncs metadata — ID, status, phase. The most valuable content in an artifact, the acceptance criteria and the verdicts, stays inside markdown that nobody opens while working.

If criteria become a checklist and verdicts become chat messages, the card starts holding the whole cycle: why the work exists, what must become true, what was tried, what certified it. That is the value the link was meant to deliver, and it is currently about half-built.

---

Proposed sequencing

1. Items 1, 4, 6, 7 — one small documentation PR, no decisions required.
2. Items 2, 3, 5 — forgeplan artifacts first (the policy decision in docs: USAGE-GUIDE expansion + small fixes v1.3.1 #3 belongs in an ADR), then implementation.

Refs: #208