Skip to content

[Phase 1] Idempotency guard: never create a duplicate epic for the same idea #598

Closed

Description

@github-actions

Story

As a maintainer running the initiative-planner,
I want apply-plan.sh to detect an already-materialized epic for the same discussion and skip creation instead of producing a duplicate,
so that a second dispatch or auto-trigger for the same idea never creates a duplicate epic + DAG.

Acceptance Criteria

  1. Before creating the epic, apply-plan.sh searches open initiative issues for the back-reference it already embeds in every epic body (Planned from idea discussion #<N>) for the current source discussion number.
  2. If a matching epic is found, apply-plan.sh creates no issues, prints a clear already planned (epic #X) message plus a step-summary note, and exits 0 (a benign re-run, not a failure).
  3. If no match is found, behavior is unchanged: the epic + story sub-issues + DAG are created exactly as today.
  4. The search is performed via a DRY_RUN-aware helper in lib/mutations.sh that the offline bats suite can stub, so both paths are tested without touching the network.
  5. New bats cases in tests/test_initiative_planner.bats prove: with a simulated existing epic the run logs zero create_issue ops; with none it still logs the 4 creates.

Tasks / Subtasks

Dev Notes

  • The epic body already embeds the back-reference at apply-plan.sh:42-44 (Planned from idea discussion #${src}). Reuse that EXACT string as the idempotency key — do not invent a new marker.
  • Put the search in scripts/initiative-planner/lib/mutations.sh alongside create_issue/link_sub_issue so it inherits the DRY_RUN switch and stays stubbable; the bats suite is fully offline (DRY_RUN=1, DRY_RUN_LOG).
  • The concurrency group in .github/workflows/initiative-planner.yml:45-48 only blocks CONCURRENT runs, not sequential re-dispatches — confirmed in discussion 💡 Adversarial Plan-Critic + Structural Gates for the Initiative-Planner (Bob) #593; this guard closes that gap.
  • Skip must exit 0, not error: a duplicate dispatch is benign. Emit to GITHUB_STEP_SUMMARY like the existing block at apply-plan.sh:129-137.
  • Testing: mirror the existing DRY_RUN patterns in tests/test_initiative_planner.bats (grep -c '"op":"create_issue"' on the log).

Project Structure Notes

Pure addition to existing planner scripts; no new files beyond test cases. New shell must pass shellcheck --severity=warning -x (AGENTS.md / lint.yml shellcheck job).

References

  • scripts/initiative-planner/apply-plan.sh#L37-L48
  • scripts/initiative-planner/lib/mutations.sh#L41-L68
  • .github/workflows/initiative-planner.yml#L45-L48
  • tests/test_initiative_planner.bats#L75-L101

Likely target surface

  • scripts/initiative-planner/apply-plan.sh
  • scripts/initiative-planner/lib/mutations.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 12, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #598 — [Phase 1] Idempotency guard: never create a duplicate epic for the same idea

    Scope

    Add a DRY_RUN-aware find_existing_epic helper to lib/mutations.sh and call it in apply-plan.sh before epic creation, short-circuiting (message + step-summary + exit 0) when an open initiative epic already embeds the Planned from idea discussion #<N> back-reference for the current source discussion.

    Implementation Checklist

    • scripts/initiative-planner/lib/mutations.sh: add find_existing_epic <repo> <back_reference> — live runs gh issue list --repo --label initiative --state open --search, filters by exact body contains, prints matching epic number or empty; DRY_RUN returns empty unless DRY_RUN_EXISTING_EPIC stub env is set
    • scripts/initiative-planner/apply-plan.sh: extract the exact Planned from idea discussion #${src} string into a reused idempotency-key var; call helper before the epic create_issue; on match, print already planned (epic #X), write a step-summary note, and exit 0
    • Confirm the no-match path leaves the create/link/edge flow untouched

    Tests to Write

    • tests/test_initiative_planner.bats: skip path — DRY_RUN_EXISTING_EPIC set → 0 create_issue ops, exit 0, already planned (epic #X) in output
    • tests/test_initiative_planner.bats: no-match path — guard unset → still logs the 4 create_issue ops

    Test Command

    bats tests/test_initiative_planner.bats and bash .dev-lead/scripts/dev-lead-lint.sh

  2. don-petry commented on Jun 12, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • Added DRY_RUN-aware find_existing_epic <repo> <back_reference> to lib/mutations.sh (live: gh issue list --label initiative --state open --search, re-filtered with an exact contains body match; DRY_RUN returns the DRY_RUN_EXISTING_EPIC stub env, empty if unset)
    • Extracted the exact Planned from idea discussion #${src} string into a reused idem_key var in apply-plan.sh and called the guard immediately before the epic create_issue
    • On match: prints already planned (epic #X), writes a GITHUB_STEP_SUMMARY note, and exit 0 (benign re-run)
    • Confirmed the no-match path leaves the create/link/edge flow untouched
    • Added bats coverage for both the skip and the normal path
    • dev-lead-lint.sh (shellcheck warning -x + agent frontmatter) passes

    Test Results

    1..13
    ok 1 validate-plan accepts a well-formed acyclic plan
    ok 2 validate-plan rejects a self-blocking story
    ok 3 validate-plan rejects a dependency cycle (with an entry point present)
    ok 4 validate-plan rejects a dangling blocked_by reference
    ok 5 validate-plan rejects a plan with no entry point
    ok 6 apply-plan (DRY_RUN) creates epic + stories + edges and posts comment
    ok 7 apply-plan threads distinct issue numbers in dry-run
    ok 8 apply-plan NEVER applies initiative:auto to any created issue
    ok 9 apply-plan marks hands_off story with hold + hands-off labels
    ok 10 existing-issue prerequisite edge references the real issue number
    ok 11 apply-plan skips creation when an epic already exists for the discussion
    ok 12 apply-plan still creates the full DAG when no existing epic is found
    ok 13 story bodies are rendered in the BMAD create-story template
    

    Files Changed

    • scripts/initiative-planner/lib/mutations.sh: new find_existing_epic helper (DRY_RUN-aware, stubbable via DRY_RUN_EXISTING_EPIC)
    • scripts/initiative-planner/apply-plan.sh: idempotency guard before epic creation — reuses the exact back-reference key, short-circuits with message + step summary + exit 0 on a match
    • tests/test_initiative_planner.bats: two new cases (skip path logs 0 creates; no-match path still logs 4 creates)

    Notes

    • The live search re-filters gh results with an exact contains($ref) so a tokenized full-text hit on a different discussion cannot produce a false match.
    • The guard only runs when a source discussion number is known (src non-empty); with no source, behavior is unchanged.
    • No new files beyond test cases, per the story's project-structure note.
  3. added 2 commits that reference this issue on Jun 14, 2026
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