[Phase 1] Open-questions-as-gate: withhold ready-for-dev on affected stories

[github-actions]

Story

As a maintainer reviewing a freshly planned initiative,
I want open-questions to carry the stories they affect, and have apply-plan withhold ready-for-dev from those stories while flagging the epic,
so that contested decisions block release to dev-lead until a maintainer resolves them, instead of flowing through baked into acceptance criteria.

Acceptance Criteria

1. plan.schema.json changes open_questions items from bare strings to objects with a required question string and an affected_story_ids array of local story ids.
2. validate-plan.py rejects an open_question whose affected_story_ids references a story id not present in the plan (mirroring the existing dangling-edge check), and the bats fixture is updated to the new object shape so existing tests pass.
3. apply-plan.sh labels each affected story planning:needs-input and does NOT stamp it ready-for-dev (the per-story status line at apply-plan.sh:80 becomes conditional); stories not referenced by any open-question are unchanged.
4. apply-plan.sh labels the epic with a gate label (e.g. initiative:needs-input) so a maintainer sees resolution is required before initiative:auto, and the discussion summary lists each open question with its affected story numbers.
5. New bats cases prove: an affected story carries planning:needs-input and omits ready-for-dev; an unaffected story is unchanged; the epic carries the gate label.

Tasks / Subtasks

• Change the open_questions schema in plan.schema.json to an array of {question, affected_story_ids} objects. (AC: test issue from agent #1)
• Extend validate-plan.py to validate affected_story_ids against the story id set, reusing the existing id-existence pattern. (AC: Go-live improvements for PR review agent #2)
• Make the story status/label logic in apply-plan.sh conditional on whether the story is referenced by an open-question; add the planning:needs-input story label and the initiative:needs-input epic label. (AC: Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)
• Render each open question with its affected story numbers in the discussion summary. (AC: Optimize review: small-PR and incremental fast paths #4)
• Update the bats fixture to the object shape and add the gate-label cases. (AC: Go-live improvements for PR review agent #2, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

• Today open_questions is string[] (plan.schema.json) rendered as a flat list in the discussion comment at apply-plan.sh:122; the bats fixture at tests/test_initiative_planner.bats:35 uses the string form — update it to the object form or downstream tests break.
• Story status is a hard-coded line Status: ready-for-dev appended at apply-plan.sh:80, and a test asserts it at tests/test_initiative_planner.bats:130 — make it conditional and update that assertion.
• Reuse the id-existence loop in validate-plan.py:62-70 (the blocked_by dangling-edge check) for affected_story_ids.
• The labels planning:needs-input and initiative:needs-input likely do NOT exist in the repo yet — see open_questions. create_issue posts to repos/{repo}/issues with a labels array (lib/mutations.sh:62-67); the labels must exist in the repo label set first.
• hands_off stories already withhold auto-release via initiative:hold (apply-plan.sh:82-85); this is the ANALOGOUS gate for unresolved questions — keep the two mechanisms distinct.

Project Structure Notes

Touches the schema/validator/apply trio together; this is the schema-shape change so the fixture in tests must move in lockstep. New labels are repo configuration, not code.

References

• scripts/initiative-planner/plan.schema.json
• scripts/initiative-planner/validate-plan.py#L62-L70
• scripts/initiative-planner/apply-plan.sh#L80-L125
• tests/test_initiative_planner.bats#L35-L130

Likely target surface

• scripts/initiative-planner/plan.schema.json
• scripts/initiative-planner/validate-plan.py
• scripts/initiative-planner/apply-plan.sh
• tests/test_initiative_planner.bats

Story prepared by the BMAD Scrum Master (Bob) for epic #597. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #600 — [Phase 1] Open-questions-as-gate: withhold ready-for-dev on affected stories

Scope

Add affected_story_ids to open_questions so apply-plan withholds ready-for-dev and stamps planning:needs-input on contested stories, flags the epic with initiative:needs-input, and lists each question's affected story numbers in the discussion summary.

Reconciliation note

Since this story was written, #682 evolved open_questions into oneOf[string, {question, blocking}]. Rather than reverting to bare strings, I will keep that shape and ADD an optional affected_story_ids array to the object branch — preserving the blocking gate and existing tests. The blocking gate (creates nothing) and this needs-input gate (withholds per-story release) stay distinct, analogous to hands_off/initiative:hold.

Implementation Checklist

• plan.schema.json: add affected_story_ids (int array, default []) to the open_questions object branch + update description
• validate-plan.py: reject affected_story_ids referencing a story id absent from the plan (mirrors the dangling blocked_by check)
• apply-plan.sh: precompute affected story-id set; make the per-story status line + labels conditional (planning:needs-input, withhold ready-for-dev); add initiative:needs-input to the epic when any story is affected; render each open question with its affected story numbers in the discussion summary
• tests/test_initiative_planner.bats: move base fixture open_questions to object shape

Tests to Write

• validator rejects an open_question with a dangling affected_story_ids
• affected story carries planning:needs-input and omits ready-for-dev
• unaffected story unchanged (ready-for-dev, no needs-input label)
• epic carries initiative:needs-input gate label
• discussion summary lists the question with its affected story number

Test Command

bats tests/test_initiative_planner.bats and python3 scripts/initiative-planner/validate-plan.py <plan>

Out-of-code follow-up

The repo label set must gain planning:needs-input and initiative:needs-input (repo configuration, not code) for the live path to apply them.

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• plan.schema.json: added optional affected_story_ids (int array, default []) to the open_questions object branch + updated description (AC test issue from agent #1)
• validate-plan.py: rejects an affected_story_ids entry that references a story id absent from the plan, mirroring the dangling blocked_by check (AC Go-live improvements for PR review agent #2)
• apply-plan.sh: precomputes the affected story-id set; the per-story status line + labels are now conditional (planning:needs-input, ready-for-dev withheld); the epic gains initiative:needs-input when any story is affected; the discussion summary renders each open question with its affected story numbers (AC Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)
• tests/test_initiative_planner.bats: base fixture open_questions moved to object shape; new validator + apply-plan gate cases added (AC Go-live improvements for PR review agent #2, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Reconciliation note

The story was authored against a bare-string[] open_questions, but #682 has since evolved it into oneOf[string, {question, blocking}]. Rather than reverting to bare strings (which would break the blocking gate and existing tests), I kept that shape and added the optional affected_story_ids to the object branch. The blocking gate (creates nothing) and this needs-input gate (materializes but withholds per-story release) remain distinct — the analogue of hands_off / initiative:hold.

Test Results

1..24
ok 1 validate-plan accepts a well-formed acyclic plan
ok 2 validate-plan accepts open_questions carrying a blocking flag
ok 3 validate-plan rejects a self-blocking story
ok 4 validate-plan rejects a dependency cycle (with an entry point present)
ok 5 validate-plan rejects a dangling blocked_by reference
ok 6 validate-plan accepts an open_question affecting an existing story id
ok 7 validate-plan rejects an open_question affecting a nonexistent story id
ok 8 validate-plan rejects a plan with no entry point
ok 9 apply-plan (DRY_RUN) creates epic + stories + edges and posts comment
ok 10 apply-plan threads distinct issue numbers in dry-run
ok 11 apply-plan NEVER applies initiative:auto to any created issue
ok 12 apply-plan marks hands_off story with hold + hands-off labels
ok 13 existing-issue prerequisite edge references the real issue number
ok 14 apply-plan gates on a blocking open question: creates zero issues and exits 0
ok 15 apply-plan blocking gate posts the open questions back to the discussion
ok 16 apply-plan does NOT gate on a non-blocking open question
ok 17 apply-plan skips creation when an epic already exists for the discussion
ok 18 apply-plan still creates the full DAG when no existing epic is found
ok 19 story bodies are rendered in the BMAD create-story template
ok 20 apply-plan flags an affected story with planning:needs-input and withholds ready-for-dev
ok 21 apply-plan leaves a story unaffected by any open question unchanged
ok 22 apply-plan labels the epic initiative:needs-input when an open question affects a story
ok 23 apply-plan does NOT label the epic initiative:needs-input when no story is affected
ok 24 apply-plan summary lists each open question with its affected story numbers

Required repo lint (.dev-lead/scripts/dev-lead-lint.sh): all checks passed (shellcheck on 51 files + 4 agent profiles).

Files Changed

• scripts/initiative-planner/plan.schema.json: affected_story_ids added to the open_questions object branch
• scripts/initiative-planner/validate-plan.py: dangling-affected_story_ids semantic check + docstring invariant
• scripts/initiative-planner/apply-plan.sh: needs-input gate — conditional story status/labels, epic gate label, summary renders affected story numbers
• tests/test_initiative_planner.bats: fixture moved to object shape; 7 new cases (2 validator, 5 apply-plan)

Notes

• Out-of-code follow-up: the repo label set must gain planning:needs-input and initiative:needs-input for the live (non-DRY_RUN) path to apply them — this is repo configuration, not code, and is out of scope for this change. create_issue posts a labels array to repos/{repo}/issues, which requires the labels to pre-exist.
• Plain-string and blocking:true open questions are unaffected; affected_story_ids is optional with a [] default, so existing plans validate unchanged.
• A question may affect multiple stories and multiple questions may affect the same story; the set is de-duplicated (unique) before labelling.

[don-petry]

Superseded by #682 → shipped in #707 (merged to main).

#682/#707 implemented the open-questions gate as a hard, all-or-nothing block: if the plan carries any blocking:true open question, apply-plan.sh creates zero issues and posts the questions back to the source discussion — rather than this issue's design of materializing the epic but withholding ready-for-dev on the affected stories.

Closing as a duplicate of #682.

⚠️ Design-difference note: the finer per-story behavior described here (still create the epic/DAG, but mark only the stories touched by an open question as not-ready) was not implemented — #707 is all-or-nothing. If that granularity is still wanted, it should be a fresh story under #597.

---

Generated by Claude Code