Skip to content

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

Closed as duplicate

Description

@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

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.

Activity

  1. don-petry commented on Jun 14, 2026

    @don-petry
    Collaborator

    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.

  2. don-petry commented on Jun 14, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    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.
  3. don-petry commented on Jun 14, 2026

    @don-petry
    Collaborator

    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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions