feat(lifecycle): sub-issue board hygiene — parent-aware gates + reconciler-owned de-boarding

[aagnone3]

Closes #265

Summary

Makes the lifecycle engine sub-issue-aware so the board matches the committed design ("the Project tracks the parent"):

• Parent-aware state + sub_issue gate verdict (feat(lifecycle): parent-aware issue state + sub_issue gate verdict #266). The issue-state GraphQL read now selects the native parent { number } link (IssueState.parent_number). Every gate (--gate <cmd>) and --groom-entry short-circuits an OPEN parented issue to a new closed sub_issue verdict carrying parent: N and a next instruction — no gate ever routes a task unit to grooming from its own (noise) board stage. The reproduced docs(wf-skills): state owned lifecycle transitions as observable postconditions in the wf-* routers #263 misroute (route_to_plan for a sub-issue of a planned parent) is a regression fixture.
• Reconciler rule 6 + best-effort de-board (feat(lifecycle): reconciler rule 6 de-boards open sub-issues; decompose/groom-verify best-effort de-board + docs #267). The closed repair set grows to six: an OPEN parented issue with a board item is archived (gh project item-archive — reversible via --undo) with an audit comment naming the parent. --decompose and --groom-verify best-effort de-board the subs they touch; --groom-verify reports still-boarded subs as warnings (never failures — the auto-add CI fires asynchronously and can land after verification; the TTL-cached reconciler is the convergence guarantee).
• Docs. lifecycle.md documents rule 6, the sub_issue verdict row, and the auto-repaired board-membership invariant; verdict tables in workflows-work.md, workflows-plan.md, and workflows-brainstorm.md gained the sub_issue row. Vendored script copies synced.

Key decisions: archive (not delete) as the removal primitive — reversible and non-destructive; rule 6 evaluated before the stage-regression rules (de-boarding supersedes Status repair on a noise stage); terminal (CLOSED) sub-issues untouched.

Testing

• 25 new unittest cases (132 → 157): parent-link parsing, all-gates sub_issue rerouting, the docs(wf-skills): state owned lifecycle transitions as observable postconditions in the wf-* routers #263 regression fixture, rule-6 pure-core + integration (archive + audit comment, idempotent second run, CLOSED/parentless untouched, rule-ordering preemption, CI-add-after-verify race, failed-archive reporting), decompose/groom-verify de-board seams and warnings.
• All gates green: python3 -m unittest plugins/agentic-engineering/tests/lifecycle_board_test.py (157 OK), bun test (426 pass), bun run typecheck, bun run skills:check (20 copies in sync), bun run docs:build && bun run docs:check.
• Live spot-check: --gate work --issue 266 returned verdict: sub_issue, parent: 265 against the real board.

Post-Deploy Monitoring & Validation

• What to monitor/search
  • Reconciler output at gate touches: repairs_applied[].rule == "sub_issue_on_board" and repairs_failed[].error_code == "deboard_failed".
  • Audit comments on sub-issues referencing "the Project tracks the parent".
• Validation checks (queries/commands)
  • python3 plugins/agentic-engineering/scripts/lifecycle_board.py --gate work --issue <open-sub> → verdict: sub_issue with the correct parent.
  • python3 plugins/agentic-engineering/scripts/lifecycle_board.py --reconcile --force → any leaked open sub-issue (e.g. docs(wf-skills): state owned lifecycle transitions as observable postconditions in the wf-* routers #263/test(plugin): guardrail — every owned lifecycle transition maps to an engine procedure and read-back #264 if still boarded) leaves the board with an audit comment; a second run is a no-op.
• Expected healthy behavior
  • Freshly decomposed plans show no stub task units on the board; gates never tell an agent to groom a sub-issue.
• Failure signal(s) / rollback trigger
  • Rule 6 archiving a non-sub-issue item, or repeated deboard_failed errors → revert the PR (the rule is additive; archived items are restorable via gh project item-archive --undo or --backfill).
• Validation window & owner
  • Window: first week of gate/reconcile activity. Owner: @aagnone3.

---

🤖 Generated with Claude Code

[aagnone3]

Comprehensive review record (wf-review)

Three lenses ran against the risk surface (acceptance-criteria conformance, Python correctness/failure handling, test sufficiency). Findings and dispositions:

Severity	Finding	Disposition
P1	Global reconcile sweep never enumerated the no-Status/early columns, so the CI-auto-add race rule 6 was built for never converged via a global reconcile	Fixed in c120a12 — sweep gained no:status/stub/brainstormed/planned legs + sweep-level regression test
P1	projectItems includes archived items by default → de-board was non-idempotent in production (re-archive + duplicate audit comment per run)	Fixed in c120a12 — isArchived selected; archived items parse as not-on-board; idempotency tests rewritten against realistic post-archive payloads
P2	verb_gate/verb_groom_entry threading of parent_number untested (reverting it passed the suite while reproducing the #263 misroute)	Fixed in c120a12 — verb-level FakeRunner tests pin the end-to-end verdict
P3	_deboard_subissue never-raises contract missed json.JSONDecodeError; rule-3 preemption + provenance-ordering unfrozen; stale orchestrate comment	Fixed in c120a12
P3	--groom-verify N+1 reads + three de-board writers (design improvement)	Deferred to #284

Both P1 fixes were re-verified by the original finding reviewer: CONFIRMED-RESOLVED, no new defects; residual verb_set_status archived-item edge documented in-code as deliberate.

Acceptance-criteria lens: PASS on all 11 criteria across #265/#266/#267, including an empirical failing-then-passing check of the regression fixture against main (54 failures pre-change, 0 post-change).

Final gates on HEAD c120a12: 164 unittest OK · bun test 426 pass · typecheck clean · skills:check 20 copies in sync · docs current.

Review verdict: ready (no unresolved P1/P2).