PRD: close the GitHub issue lifecycle from publication through runtime acceptance #455

Problem Statement

Monday creates and completes engineering work quickly, but its GitHub issue lifecycle is one-way. Issue publication is well specified while ownership, native dependency tracking, partial-PR linkage, runtime acceptance, and parent closeout are inconsistent. This leaves completed parent contracts open, code-complete runtime contracts looking untouched, nearly every item in the same execution queue, malformed issue bodies, and accidental close/reopen cycles.

Solution

Make GitHub Issues the only authoritative work-state store and close the lifecycle at two public seams: issue publication and PR/runtime completion. Every issue carries one category and one triage state, uses native parent and blocked-by relationships, records one owner when active, and represents one independently mergeable and rollbackable behavior or rollout contract. Partial and stacked PRs reference issues without closing them; only a final PR into the default branch may close a code-complete issue. Runtime issues close manually only after immutable target, controller, success, cleanup, and rollback evidence are recorded. Parent issues receive a closeout audit after their last child closes but are never closed automatically.

User Stories

1. As a maintainer, I want every open issue to have one category and one state, so that the queue can be trusted.
2. As a maintainer, I want PRD parents excluded from execution queries, so that roadmap tracking is not mistaken for runnable work.
3. As an agent, I want native parent and blocked-by relationships, so that I do not parse stale prose before starting work.
4. As an agent, I want ready-for-agent to mean runnable now, so that missing authority or infrastructure is visible before a worktree is created.
5. As a reviewer, I want every PR to declare Refs, Closes, or None, so that partial delivery cannot close a larger issue accidentally.
6. As a reviewer, I want stacked PRs to avoid closing keywords before they target the default branch, so that merge order does not corrupt issue state.
7. As a runtime controller, I want deployment and live-evidence contracts separated from code contracts, so that repository merges are not presented as runtime completion.
8. As a runtime controller, I want target, candidate, configuration, rollback, stop-rule, and cleanup identities recorded before mutation, so that rollout remains fail-closed.
9. As a maintainer, I want a parent closeout audit after all children finish, so that completed PRDs do not remain open indefinitely.
10. As a maintainer, I want parent closure to remain a judgment step, so that closed children cannot fabricate an unmet production outcome.
11. As a reporter, I want multiline Markdown published without literal escape sequences, so that issue contracts remain readable.
12. As a Claude or Codex operator, I want PM commands to read GitHub first, so that missing .claude/epics files cannot block valid issue operations.
13. As a repository owner, I want a read-only lifecycle audit before enforcement, so that historical inconsistencies are visible without automatic mutation.
14. As a repository owner, I want enforcement enabled only after a green observed run, so that branch protection is not changed blindly.
15. As a repository owner, I want historical metadata migration to be dry-run first and reversible, so that unresolved acceptance evidence is never rewritten or discarded.
16. As a reviewer, I want code, artifact publication, runtime adoption, and result publication to remain distinct rollback units, so that one PR cannot cross trust domains by convenience.
17. As an operator, I want runtime issues without a named target or controller to remain needs-info or ready-for-human, so that an AFK agent cannot infer production authority.
18. As a maintainer, I want active work to have one assignee and one recorded worktree owner, so that concurrent writers cannot silently overlap.

Implementation Decisions

• GitHub Issues, labels, assignees, native parent/sub-issue relationships, native blocked-by relationships, PR links, and issue events are authoritative. Local .claude/epics state is optional and cannot gate GitHub close/reopen/status operations.
• Category roles remain bug and enhancement. Triage states remain needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix. tracking and runtime are non-state qualifiers.
• PRD parents carry tracking and are excluded from agent pickup queries. Runtime/deployment contracts carry runtime.
• Issue bodies are submitted through a body file or stdin, never through escaped multiline shell strings.
• Engineering, release artifact, runtime adoption, and result publication are separate issues when they can be merged, tested, reverted, authorized, or evidenced independently.
• The PR template exposes one explicit issue relationship field. Refs #N is used for partial work and stacks. Closes #N is allowed only for a contract completed by merge into the default branch. Runtime and tracking issues cannot be closed by PR merge.
• Runtime closure requires immutable target, source/candidate, configuration, rollback, controller, stop-rule, result, and cleanup evidence. A failed run remains open and records the failure without weakening the gate.
• When the last direct sub-issue closes, automation may post one idempotent closeout reminder but must not close the parent.
• Lifecycle auditing is read-only first. Required-check enforcement is a later repository-setting rollout after the audit is green.
• Existing issue metadata is migrated by a separate dry-run-first administrative issue; closure candidates are re-verified rather than bulk closed.
• Legacy PM commands are repaired narrowly. Broad deletion of the legacy PM subsystem is deferred until use is proven absent.

Testing Decisions

• Test the issue-publication seam with fixture issues representing a valid child, missing category, conflicting state, malformed literal newlines, native blockers, tracking parents, and runtime contracts.
• Test the PR-completion seam with valid Refs, valid final Closes, a negated closing phrase, a stacked non-default-base close, a runtime close, and a tracking-parent close.
• Validate PM commands through their GitHub-facing behavior: issue state and relationships remain readable without any .claude/epics directory.
• Run the lifecycle auditor against fixture JSON first, then against the live repository in dry-run mode.
• Observe at least one successful lifecycle check before adding it to branch protection.
• Historical migration acceptance is a before/after readback: all open issues have valid labels and formatting, native relationships match the approved map, and no runtime or parent issue was closed without explicit evidence.

Out of Scope

• Research logic, collectors, evaluator/MCTS behavior, trading authority, production deployment, or live enablement.
• Automatic parent closure.
• Automatic acceptance-criteria completion inferred from merged code.
• A new project-management database or dashboard.
• Broad removal of every legacy .claude/commands/pm file.
• Rewriting historical issue comments or deleting failure evidence.

Further Notes

The correction deliberately separates repository truth, artifact publication, runtime truth, and result publication. The migration may reduce the open count after explicit closeout audits, but reducing the count is not itself an acceptance criterion.