diff --git a/.egg-state/contracts/402.json b/.egg-state/contracts/402.json new file mode 100644 index 0000000000..53c26ac1a1 --- /dev/null +++ b/.egg-state/contracts/402.json @@ -0,0 +1,476 @@ +{ + "schemaVersion": "1.0", + "issue": { + "number": 402, + "title": "leverage issue labels for SDLC workflow", + "url": "https://github.com/jwbron/egg/issues/402" + }, + "current_phase": "implement", + "acceptance_criteria": [ + { + "id": "ac-1", + "description": "[TASK-1-1] Script creates all 5 labels with correct colors and descriptions; re-running is safe", + "verified": false + }, + { + "id": "ac-2", + "description": "[TASK-1-2] Label no longer exists; existing issues have it removed", + "verified": false + }, + { + "id": "ac-3", + "description": "[TASK-2-1] Pipeline triggers when sdlc:refine label is added", + "verified": false + }, + { + "id": "ac-4", + "description": "[TASK-2-2] Correct phase label is applied when workflow starts", + "verified": false + }, + { + "id": "ac-5", + "description": "[TASK-2-3] Created PRs get sdlc:pr label", + "verified": false + }, + { + "id": "ac-6", + "description": "[TASK-3-1] When refine/plan phase posts approval checkbox, label is added", + "verified": false + }, + { + "id": "ac-7", + "description": "[TASK-3-2] On approval, old phase label removed, new added, awaiting-approval removed", + "verified": false + }, + { + "id": "ac-8", + "description": "[TASK-3-3] sdlc:awaiting-approval present when decisions pending, removed when resolved", + "verified": false + }, + { + "id": "ac-9", + "description": "[TASK-4-1] When PR is created, sdlc:implement removed and sdlc:pr added", + "verified": false + }, + { + "id": "ac-10", + "description": "[TASK-4-2] Phase completion comments trigger adding sdlc:awaiting-approval", + "verified": false + }, + { + "id": "ac-11", + "description": "[TASK-4-3] Reusable script handles label transitions with error handling", + "verified": false + }, + { + "id": "ac-12", + "description": "[TASK-5-1] Cleanup runs for issues with any SDLC phase label", + "verified": false + }, + { + "id": "ac-13", + "description": "[TASK-5-2] Closed SDLC issues have phase labels removed", + "verified": false + }, + { + "id": "ac-14", + "description": "[TASK-6-1] Contract verification triggers on PRs with sdlc:pr label", + "verified": false + }, + { + "id": "ac-15", + "description": "[TASK-7-1] Documentation describes all SDLC labels and their management", + "verified": false + }, + { + "id": "ac-16", + "description": "[TASK-7-2] No stale references to egg-sdlc remain", + "verified": false + }, + { + "id": "ac-17", + "description": "[TASK-7-3] Test verifies labels transition correctly through phase changes", + "verified": false + } + ], + "phases": [ + { + "id": "phase-1", + "name": "Create Labels and Setup Script", + "status": "pending", + "tasks": [ + { + "id": "task-1-1", + "description": "Create label setup script for SDLC labels (idempotent)", + "status": "pending", + "acceptance_criteria": "Script creates all 5 labels with correct colors and descriptions; re-running is safe", + "files_affected": [ + ".github/scripts/setup-sdlc-labels.sh" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-1-2", + "description": "Delete the existing egg-sdlc label from the repository", + "status": "pending", + "acceptance_criteria": "Label no longer exists; existing issues have it removed", + "files_affected": [], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-2", + "name": "Update Pipeline Trigger Logic", + "status": "pending", + "tasks": [ + { + "id": "task-2-1", + "description": "Update pipeline trigger condition from egg-sdlc to sdlc:refine", + "status": "pending", + "acceptance_criteria": "Pipeline triggers when sdlc:refine label is added", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-2-2", + "description": "Add logic to ensure correct phase label is applied during init", + "status": "pending", + "acceptance_criteria": "Correct phase label is applied when workflow starts", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-2-3", + "description": "Update PR label addition logic to use sdlc:pr instead of egg-sdlc", + "status": "pending", + "acceptance_criteria": "Created PRs get sdlc:pr label", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-3", + "name": "Add Label Transitions in HITL Workflow", + "status": "pending", + "tasks": [ + { + "id": "task-3-1", + "description": "Add sdlc:awaiting-approval label when posting phase completion comments", + "status": "pending", + "acceptance_criteria": "When refine/plan phase posts approval checkbox, label is added", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-3-2", + "description": "Remove sdlc:awaiting-approval and transition phase label on approval", + "status": "pending", + "acceptance_criteria": "On approval, old phase label removed, new added, awaiting-approval removed", + "files_affected": [ + ".github/workflows/sdlc-hitl.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-3-3", + "description": "Update handle-decision job to manage approval label for HITL decisions", + "status": "pending", + "acceptance_criteria": "sdlc:awaiting-approval present when decisions pending, removed when resolved", + "files_affected": [ + ".github/workflows/sdlc-hitl.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-4", + "name": "Add Label Transitions in Main Pipeline", + "status": "pending", + "tasks": [ + { + "id": "task-4-1", + "description": "Add label transition logic when advancing from implement to PR phase", + "status": "pending", + "acceptance_criteria": "When PR is created, sdlc:implement removed and sdlc:pr added", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-4-2", + "description": "Add sdlc:awaiting-approval when posting phase completion comments in pipeline", + "status": "pending", + "acceptance_criteria": "Phase completion comments trigger adding sdlc:awaiting-approval", + "files_affected": [ + ".github/workflows/sdlc-pipeline.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-4-3", + "description": "Add helper script for atomic label transitions", + "status": "pending", + "acceptance_criteria": "Reusable script handles label transitions with error handling", + "files_affected": [ + ".github/scripts/transition-sdlc-label.sh" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-5", + "name": "Update Cleanup Workflow", + "status": "pending", + "tasks": [ + { + "id": "task-5-1", + "description": "Update cleanup trigger condition to check for any sdlc:* label", + "status": "pending", + "acceptance_criteria": "Cleanup runs for issues with any SDLC phase label", + "files_affected": [ + ".github/workflows/on-issue-closed.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-5-2", + "description": "Remove all SDLC labels on issue close", + "status": "pending", + "acceptance_criteria": "Closed SDLC issues have phase labels removed", + "files_affected": [ + ".github/workflows/on-issue-closed.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-6", + "name": "Update Contract Verification Workflow", + "status": "pending", + "tasks": [ + { + "id": "task-6-1", + "description": "Update PR contract verification trigger to check for sdlc:pr label", + "status": "pending", + "acceptance_criteria": "Contract verification triggers on PRs with sdlc:pr label", + "files_affected": [ + ".github/workflows/on-pull-request-contract-verify.yml" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + }, + { + "id": "phase-7", + "name": "Documentation and Testing", + "status": "pending", + "tasks": [ + { + "id": "task-7-1", + "description": "Update docs/guides/sdlc-pipeline.md with new label documentation", + "status": "pending", + "acceptance_criteria": "Documentation describes all SDLC labels and their management", + "files_affected": [ + "docs/guides/sdlc-pipeline.md" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-7-2", + "description": "Update any references to egg-sdlc in other documentation", + "status": "pending", + "acceptance_criteria": "No stale references to egg-sdlc remain", + "files_affected": [ + "docs/guides/sdlc-pipeline.md", + "CLAUDE.md" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + }, + { + "id": "task-7-3", + "description": "Add integration test for label transitions", + "status": "pending", + "acceptance_criteria": "Test verifies labels transition correctly through phase changes", + "files_affected": [ + "integration_tests/sdlc/test_label_transitions.py" + ], + "commit": null, + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "notes": "" + } + ], + "review_cycles": 0, + "max_cycles": 3, + "escalated": false, + "escalation_reason": null, + "review_feedback": [] + } + ], + "decisions": [], + "circuit_breaker": { + "total_cycles": 0, + "max_total_cycles": 10, + "status": "closed" + }, + "workflow_owner": "jwbron", + "audit_log": [ + { + "timestamp": "2026-02-09T03:02:49Z", + "actor": "system", + "role": "reviewer", + "action": "update", + "field_path": "refine_review_cycles", + "old_value": 0, + "new_value": 1, + "reason": "Refine review cycle 1: approved" + }, + { + "timestamp": "2026-02-09T03:04:57Z", + "actor": "jwbron", + "role": "human", + "action": "transition", + "field_path": "current_phase", + "old_value": "refine", + "new_value": "plan", + "reason": "Phase approved by human" + }, + { + "timestamp": "2026-02-09T03:10:53Z", + "actor": "system", + "role": "reviewer", + "action": "update", + "field_path": "plan_review_cycles", + "old_value": 0, + "new_value": 1, + "reason": "Plan review cycle 1: approved" + }, + { + "timestamp": "2026-02-09T03:17:43Z", + "actor": "jwbron", + "role": "human", + "action": "transition", + "field_path": "current_phase", + "old_value": "plan", + "new_value": "implement", + "reason": "Phase approved by human" + } + ], + "refine_review_cycles": 1, + "refine_review_feedback": "", + "plan_review_cycles": 1, + "plan_review_feedback": "", + "pr": { + "title": "Add phase-based labels for SDLC workflow state tracking", + "description": "Implements phase-based labeling for the SDLC pipeline to provide visual status\ntracking and enable filtering issues by pipeline state. Replaces the single\n`egg-sdlc` trigger label with phase labels (`sdlc:refine`, `sdlc:plan`,\n`sdlc:implement`, `sdlc:pr`) plus an approval modifier (`sdlc:awaiting-approval`).\n\nCloses #402." + } +} diff --git a/.egg-state/drafts/402-analysis.md b/.egg-state/drafts/402-analysis.md new file mode 100644 index 0000000000..0c2a7fe094 --- /dev/null +++ b/.egg-state/drafts/402-analysis.md @@ -0,0 +1,169 @@ +# Analysis: Leverage Issue Labels for SDLC Workflow + +> Issue: #402 | Phase: refine + +## Problem Statement + +The SDLC pipeline currently uses the `egg-sdlc` label as the primary trigger for workflow execution, but the label ecosystem doesn't capture the current **state** of an issue as it progresses through the pipeline phases. Users and automation cannot easily determine at a glance whether an issue is in refine, plan, implement, or PR phase—or whether it's awaiting human approval. + +**Current state**: Labels are used as triggers (`egg-sdlc`) and markers (`self-improvement`), but not as state indicators. + +**Desired outcome**: Labels should reflect the current SDLC phase and approval status, enabling: +- Visual dashboard filtering by phase +- Automation queries for issues awaiting approval +- Clear status communication without reading comments + +## Current Behavior + +### Existing Labels +The repository currently has these labels (from `gh label list`): + +| Label | Purpose | Status | +|-------|---------|--------| +| `egg-sdlc` | Pipeline trigger | Active | +| `self-improvement` | Auto-generated improvement issues | Active | +| `bug`, `enhancement`, `documentation` | Standard GitHub labels | Active | +| `dependencies`, `github_actions`, `python` | Dependabot/type labels | Active | + +### Current Pipeline State Tracking +State is tracked via: +1. **Contract JSON**: `.egg-state/contracts/{issue}.json` with `current_phase` field +2. **Workflow job names**: GitHub Actions UI shows which job is running +3. **Issue comments**: Phase completion posts with approval checkboxes + +**Problem**: None of these are queryable via GitHub's label-based filtering. Users cannot filter the issue list to see "all issues awaiting approval" or "all issues in implement phase." + +### Relevant Code Paths +- Pipeline trigger: `.github/workflows/sdlc-pipeline.yml:41-44` listens for `egg-sdlc` label +- Label addition: `.github/workflows/sdlc-pipeline.yml:579-582` adds `egg-sdlc` to PRs +- Contract phase: `.egg-state/contracts/{issue}.json` contains `current_phase` + +## Constraints + +- **Label consistency**: Labels must be added/removed atomically with phase transitions to avoid stale states +- **Workflow triggers**: Adding/removing labels can trigger workflows; must avoid infinite loops +- **Concurrency**: Multiple workflow runs may attempt label changes simultaneously +- **GitHub API rate limits**: Frequent label changes contribute to rate limit consumption +- **Backward compatibility**: Existing `egg-sdlc` trigger must continue to work + +## Options Considered + +### Option A: Phase Labels (Mutually Exclusive) + +**Approach**: Add one label per pipeline phase (`sdlc:refine`, `sdlc:plan`, `sdlc:implement`, `sdlc:pr`) plus an approval state label (`sdlc:awaiting-approval`). Only one phase label is active at a time. + +**Labels to add**: +- `sdlc:refine` (color: `#c2e0c6`) +- `sdlc:plan` (color: `#bfdadc`) +- `sdlc:implement` (color: `#fef2c0`) +- `sdlc:pr` (color: `#d4c5f9`) +- `sdlc:awaiting-approval` (color: `#fbca04`) + +**Implementation**: +1. When phase transitions, remove previous phase label, add new phase label +2. When HITL approval is required, add `sdlc:awaiting-approval` +3. When human approves, remove `sdlc:awaiting-approval` + +**Pros**: +- Clear visual indication of current phase +- Queryable via GitHub search (`label:"sdlc:refine"`) +- Namespace prefix (`sdlc:`) groups related labels +- Approval state is independent of phase (can be in "implement" and "awaiting-approval") + +**Cons**: +- More label churn (add/remove on each transition) +- Requires workflow updates to manage label lifecycle +- Stale labels if workflow fails mid-transition + +### Option B: Compound State Label + +**Approach**: Use a single label that encodes both phase and status (e.g., `sdlc:refine-in-progress`, `sdlc:refine-awaiting-approval`, `sdlc:plan-in-progress`). + +**Labels to add** (10 total): +- `sdlc:refine-in-progress` +- `sdlc:refine-awaiting-approval` +- `sdlc:plan-in-progress` +- `sdlc:plan-awaiting-approval` +- `sdlc:implement-in-progress` +- `sdlc:implement-review` +- `sdlc:pr-ready` +- `sdlc:pr-changes-requested` + +**Pros**: +- Single label captures full state +- No need to track multiple labels + +**Cons**: +- Many labels (combinatorial explosion) +- Harder to query "all awaiting approval" across phases +- More labels to maintain + +### Option C: Phase Labels + Suffix Modifiers + +**Approach**: Use phase labels with optional modifier labels that can apply to any phase. + +**Labels**: +- Phase: `sdlc:refine`, `sdlc:plan`, `sdlc:implement`, `sdlc:pr` +- Modifiers: `awaiting-approval`, `blocked` + +**Pros**: +- Modifiers are reusable across phases +- Can query "awaiting-approval" independent of phase +- Fewer total labels than Option B + +**Cons**: +- Two-label system slightly more complex +- Modifier labels aren't namespaced (could conflict) + +## Recommended Approach + +**Option A: Phase Labels (Mutually Exclusive)** with the `sdlc:awaiting-approval` modifier. + +**Justification**: +1. **Clarity**: Each phase has exactly one label, making state unambiguous +2. **Queryability**: GitHub search supports `label:"sdlc:refine" label:"sdlc:awaiting-approval"` +3. **Namespace**: The `sdlc:` prefix groups labels visually in the label picker +4. **Simplicity**: 5 new labels (vs. 8-10 for Option B) +5. **Alignment with contract**: Labels mirror `current_phase` in the contract JSON + +**Proposed Label Set**: + +| Label | Color | Description | +|-------|-------|-------------| +| `sdlc:refine` | `#c2e0c6` (green) | Issue is in refine phase | +| `sdlc:plan` | `#bfdadc` (teal) | Issue is in plan phase | +| `sdlc:implement` | `#fef2c0` (yellow) | Issue is in implement phase | +| `sdlc:pr` | `#d4c5f9` (purple) | PR created, awaiting human merge | +| `sdlc:awaiting-approval` | `#fbca04` (orange) | Human approval required to proceed | + +**Implementation Steps**: +1. Add labels to repository via `gh label create` +2. Update `sdlc-pipeline.yml` to add/remove phase labels at transitions +3. Update HITL workflows to add `sdlc:awaiting-approval` when pausing for human input +4. Add label removal logic to cleanup workflow (`on-issue-closed.yml`) +5. Document label meanings in `docs/guides/sdlc-pipeline.md` + +## Open Questions + +**Question 1** (multiple-choice via HITL): + +Should the `egg-sdlc` trigger label be retained alongside phase labels, or replaced by the new labels? + +- **Retain both**: Keep `egg-sdlc` as the trigger, add phase labels as state indicators +- **Replace**: Remove `egg-sdlc`, use `sdlc:refine` as the initial trigger +- **Other (explain in reply)** + +--- + +**Question 2** (multiple-choice via HITL): + +How should the pipeline handle label synchronization if a workflow fails mid-transition? + +- **Best effort**: Label may be stale; next workflow run corrects it +- **Reconciliation job**: Periodic job syncs labels with contract state +- **Defensive check**: Each phase reads contract and corrects label before proceeding +- **Other (explain in reply)** + +--- + +*Authored-by: egg* diff --git a/.egg-state/drafts/402-plan.md b/.egg-state/drafts/402-plan.md new file mode 100644 index 0000000000..46e923572e --- /dev/null +++ b/.egg-state/drafts/402-plan.md @@ -0,0 +1,292 @@ +# Plan: Leverage Issue Labels for SDLC Workflow + +> Issue: #402 | Phase: plan + +## Summary + +This plan implements phase-based labeling for the SDLC pipeline, replacing the single `egg-sdlc` trigger label with a set of mutually exclusive phase labels (`sdlc:refine`, `sdlc:plan`, `sdlc:implement`, `sdlc:pr`) plus an approval state modifier (`sdlc:awaiting-approval`). This enables visual status tracking on GitHub's issue list and supports filtering/querying by phase. + +The implementation follows the approach approved in the refine phase analysis: Option A (Phase Labels) with the human decision to **replace** `egg-sdlc` with `sdlc:refine` as the initial trigger. + +## Implementation Phases + +### Phase 1: Create Labels and Setup Script + +**Goal**: Establish the new label set in the repository and create a reusable setup script for label management. + +**Tasks**: +- [TASK-1-1] Create label setup script that can create/update SDLC labels idempotently — Acceptance: Script creates all 5 labels with correct colors and descriptions; re-running is safe (idempotent) +- [TASK-1-2] Delete the existing `egg-sdlc` label from the repository — Acceptance: Label no longer exists; existing issues with the label have it removed + +**Dependencies**: None + +**Exit criteria**: All 5 new labels exist in the repository (`sdlc:refine`, `sdlc:plan`, `sdlc:implement`, `sdlc:pr`, `sdlc:awaiting-approval`); `egg-sdlc` label is removed. + +### Phase 2: Update Pipeline Trigger Logic + +**Goal**: Modify `sdlc-pipeline.yml` to trigger on `sdlc:refine` instead of `egg-sdlc`, and add label management during initialization. + +**Tasks**: +- [TASK-2-1] Update pipeline trigger condition from `egg-sdlc` to `sdlc:refine` — Acceptance: Pipeline triggers when `sdlc:refine` label is added; does not trigger on other labels +- [TASK-2-2] Add logic to ensure correct phase label is applied during init — Acceptance: When workflow starts, the correct phase label is applied (e.g., `sdlc:refine` for new issues, or the current phase label if resuming) +- [TASK-2-3] Update PR label addition logic to use `sdlc:pr` instead of `egg-sdlc` — Acceptance: Created PRs get `sdlc:pr` label instead of `egg-sdlc` + +**Dependencies**: Phase 1 (labels must exist) + +**Exit criteria**: Pipeline triggers on `sdlc:refine`; correct phase label is applied on init; PRs receive `sdlc:pr` label. + +### Phase 3: Add Label Transitions in HITL Workflow + +**Goal**: Implement label transitions during phase approvals and HITL decisions in `sdlc-hitl.yml`. + +**Tasks**: +- [TASK-3-1] Add `sdlc:awaiting-approval` label when posting phase completion comments — Acceptance: When refine/plan phase posts approval checkbox, `sdlc:awaiting-approval` is added +- [TASK-3-2] Remove `sdlc:awaiting-approval` and transition phase label on approval — Acceptance: When human approves, old phase label is removed, new phase label is added, `sdlc:awaiting-approval` is removed +- [TASK-3-3] Update handle-decision job to manage approval label for HITL decisions — Acceptance: When HITL decisions are pending, `sdlc:awaiting-approval` is present; removed when all resolved + +**Dependencies**: Phase 1, Phase 2 + +**Exit criteria**: Labels correctly reflect phase and approval state throughout HITL interactions. + +### Phase 4: Add Label Transitions in Main Pipeline + +**Goal**: Ensure phase labels are updated during automatic phase transitions within `sdlc-pipeline.yml`. + +**Tasks**: +- [TASK-4-1] Add label transition logic when advancing from implement to PR phase — Acceptance: When implement completes and PR is created, `sdlc:implement` is removed and `sdlc:pr` is added +- [TASK-4-2] Add `sdlc:awaiting-approval` when posting phase completion comments in pipeline — Acceptance: Refine and plan phase completion comments trigger adding `sdlc:awaiting-approval` +- [TASK-4-3] Add helper function/script for atomic label transitions (remove old + add new) — Acceptance: Reusable script handles label transitions with error handling; used by both workflows + +**Dependencies**: Phase 1, Phase 2, Phase 3 + +**Exit criteria**: All automatic phase transitions update labels atomically. + +### Phase 5: Update Cleanup Workflow + +**Goal**: Update `on-issue-closed.yml` to handle new label set. + +**Tasks**: +- [TASK-5-1] Update cleanup trigger condition to check for any `sdlc:*` label — Acceptance: Cleanup runs for issues with any SDLC phase label, not just `egg-sdlc` +- [TASK-5-2] Remove all SDLC labels on issue close (optional cleanup) — Acceptance: Closed SDLC issues have phase labels removed for cleanliness + +**Dependencies**: Phase 1 + +**Exit criteria**: Cleanup workflow handles new label scheme. + +### Phase 6: Update Contract Verification Workflow + +**Goal**: Update `on-pull-request-contract-verify.yml` to use new labels. + +**Tasks**: +- [TASK-6-1] Update PR contract verification trigger to check for `sdlc:pr` label — Acceptance: Contract verification triggers on PRs with `sdlc:pr` label + +**Dependencies**: Phase 2 + +**Exit criteria**: PR contract verification works with new label scheme. + +### Phase 7: Documentation and Testing + +**Goal**: Update documentation and verify the implementation works end-to-end. + +**Tasks**: +- [TASK-7-1] Update `docs/guides/sdlc-pipeline.md` with new label documentation — Acceptance: Documentation describes all SDLC labels, their meanings, and how they're managed +- [TASK-7-2] Update any references to `egg-sdlc` in other documentation — Acceptance: No stale references to `egg-sdlc` remain +- [TASK-7-3] Add integration test for label transitions — Acceptance: Test verifies labels transition correctly through mock phase changes + +**Dependencies**: All previous phases + +**Exit criteria**: Documentation is updated; integration tests pass. + +## Test Strategy + +- **Unit tests**: No new unit tests required (workflow YAML doesn't have unit tests) +- **Integration tests**: + - Add test in `integration_tests/sdlc/` that mocks label API calls and verifies correct labels are added/removed during phase transitions + - Test idempotency: running label setup twice produces same result +- **Manual testing**: + 1. Create a test issue, add `sdlc:refine` label + 2. Verify pipeline starts and `sdlc:refine` label is present + 3. Approve refine phase, verify `sdlc:refine` → `sdlc:plan` transition + 4. Continue through pipeline, verifying labels at each phase + 5. Verify `sdlc:awaiting-approval` appears/disappears at HITL checkpoints + +## Rollback Plan + +1. **Immediate rollback**: Revert the PR (all changes are in workflow YAML files) +2. **Label restoration**: + ```bash + gh label create "egg-sdlc" --description "Trigger SDLC pipeline" --color "0e8a16" + ``` +3. **In-flight issues**: Manually add `egg-sdlc` label to any issues that were mid-pipeline +4. **New labels**: Can be left in place or removed; they won't affect anything if workflows are reverted + +The rollback is straightforward because: +- All changes are in workflow YAML files (single PR revert) +- Label operations are idempotent (can recreate old label) +- No database migrations or data transformations + +## Risk Assessment + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| Workflow trigger loops (label change triggers workflow that changes label) | Medium | High | Use `types: [labeled]` filter and only trigger on `sdlc:refine`; other phase labels are internal state only | +| Stale labels if workflow fails mid-transition | Low | Low | Best-effort approach; next workflow run will correct labels based on contract state | +| Concurrent label modifications causing race conditions | Low | Medium | Use GitHub API's `add-label` and `remove-label` which are atomic; accept eventual consistency | +| Existing `egg-sdlc` issues lose their label during migration | Medium | Medium | Before deleting `egg-sdlc`, query for all issues with it and document them; manually triage any active ones | + +## Migration Notes + +**Breaking change**: The `egg-sdlc` label will no longer trigger the pipeline. Users must use `sdlc:refine` instead. + +**Migration steps** (to be done by human before/during deploy): +1. Check for any issues currently using `egg-sdlc` label: `gh issue list --label "egg-sdlc" --state open` +2. For active pipeline issues: wait for completion or manually transition to new labels +3. For issues not yet started: remove `egg-sdlc`, add `sdlc:refine` to trigger + +--- + +## Structured Task Appendix + +The following YAML block is machine-readable and will be extracted into the contract. +It must accurately reflect the tasks described above. The `pr:` section provides the +title and description that will be used when creating the pull request. + +```yaml +# yaml-tasks +pr: + title: "Add phase-based labels for SDLC workflow state tracking" + description: | + Implements phase-based labeling for the SDLC pipeline to provide visual status + tracking and enable filtering issues by pipeline state. Replaces the single + `egg-sdlc` trigger label with phase labels (`sdlc:refine`, `sdlc:plan`, + `sdlc:implement`, `sdlc:pr`) plus an approval modifier (`sdlc:awaiting-approval`). + + Closes #402. +phases: + - id: 1 + name: Create Labels and Setup Script + goal: Establish the new label set in the repository + tasks: + - id: TASK-1-1 + description: Create label setup script for SDLC labels (idempotent) + acceptance: Script creates all 5 labels with correct colors and descriptions; re-running is safe + files: + - .github/scripts/setup-sdlc-labels.sh + - id: TASK-1-2 + description: Delete the existing egg-sdlc label from the repository + acceptance: Label no longer exists; existing issues have it removed + files: [] + - id: 2 + name: Update Pipeline Trigger Logic + goal: Modify sdlc-pipeline.yml to trigger on sdlc:refine + tasks: + - id: TASK-2-1 + description: Update pipeline trigger condition from egg-sdlc to sdlc:refine + acceptance: Pipeline triggers when sdlc:refine label is added + files: + - .github/workflows/sdlc-pipeline.yml + - id: TASK-2-2 + description: Add logic to ensure correct phase label is applied during init + acceptance: Correct phase label is applied when workflow starts + files: + - .github/workflows/sdlc-pipeline.yml + - id: TASK-2-3 + description: Update PR label addition logic to use sdlc:pr instead of egg-sdlc + acceptance: Created PRs get sdlc:pr label + files: + - .github/workflows/sdlc-pipeline.yml + - id: 3 + name: Add Label Transitions in HITL Workflow + goal: Implement label transitions during phase approvals + tasks: + - id: TASK-3-1 + description: Add sdlc:awaiting-approval label when posting phase completion comments + acceptance: When refine/plan phase posts approval checkbox, label is added + files: + - .github/workflows/sdlc-pipeline.yml + - id: TASK-3-2 + description: Remove sdlc:awaiting-approval and transition phase label on approval + acceptance: On approval, old phase label removed, new added, awaiting-approval removed + files: + - .github/workflows/sdlc-hitl.yml + - id: TASK-3-3 + description: Update handle-decision job to manage approval label for HITL decisions + acceptance: sdlc:awaiting-approval present when decisions pending, removed when resolved + files: + - .github/workflows/sdlc-hitl.yml + - id: 4 + name: Add Label Transitions in Main Pipeline + goal: Ensure phase labels are updated during automatic phase transitions + tasks: + - id: TASK-4-1 + description: Add label transition logic when advancing from implement to PR phase + acceptance: When PR is created, sdlc:implement removed and sdlc:pr added + files: + - .github/workflows/sdlc-pipeline.yml + - id: TASK-4-2 + description: Add sdlc:awaiting-approval when posting phase completion comments in pipeline + acceptance: Phase completion comments trigger adding sdlc:awaiting-approval + files: + - .github/workflows/sdlc-pipeline.yml + - id: TASK-4-3 + description: Add helper script for atomic label transitions + acceptance: Reusable script handles label transitions with error handling + files: + - .github/scripts/transition-sdlc-label.sh + - id: 5 + name: Update Cleanup Workflow + goal: Update on-issue-closed.yml to handle new label set + tasks: + - id: TASK-5-1 + description: Update cleanup trigger condition to check for any sdlc:* label + acceptance: Cleanup runs for issues with any SDLC phase label + files: + - .github/workflows/on-issue-closed.yml + - id: TASK-5-2 + description: Remove all SDLC labels on issue close + acceptance: Closed SDLC issues have phase labels removed + files: + - .github/workflows/on-issue-closed.yml + - id: 6 + name: Update Contract Verification Workflow + goal: Update on-pull-request-contract-verify.yml to use new labels + tasks: + - id: TASK-6-1 + description: Update PR contract verification trigger to check for sdlc:pr label + acceptance: Contract verification triggers on PRs with sdlc:pr label + files: + - .github/workflows/on-pull-request-contract-verify.yml + - id: 7 + name: Documentation and Testing + goal: Update documentation and verify implementation + tasks: + - id: TASK-7-1 + description: Update docs/guides/sdlc-pipeline.md with new label documentation + acceptance: Documentation describes all SDLC labels and their management + files: + - docs/guides/sdlc-pipeline.md + - id: TASK-7-2 + description: Update any references to egg-sdlc in other documentation + acceptance: No stale references to egg-sdlc remain + files: + - docs/guides/sdlc-pipeline.md + - CLAUDE.md + - id: TASK-7-3 + description: Add integration test for label transitions + acceptance: Test verifies labels transition correctly through phase changes + files: + - integration_tests/sdlc/test_label_transitions.py +``` + +--- + +## Phase Approval + +### Ready for Review + + +- [ ] Approve and advance to implement phase + +--- + +*Authored-by: egg* diff --git a/.egg/schemas/contract.schema.json b/.egg/schemas/contract.schema.json index 8dfc8be828..a344338724 100644 --- a/.egg/schemas/contract.schema.json +++ b/.egg/schemas/contract.schema.json @@ -70,7 +70,7 @@ }, "workflow_owner": { "type": ["string", "null"], - "description": "GitHub username of the user who initiated the SDLC workflow (added the egg-sdlc label)", + "description": "GitHub username of the user who initiated the SDLC workflow (added the sdlc:refine label)", "default": null }, "audit_log": { diff --git a/.github/scripts/setup-sdlc-labels.sh b/.github/scripts/setup-sdlc-labels.sh new file mode 100755 index 0000000000..372631913d --- /dev/null +++ b/.github/scripts/setup-sdlc-labels.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash +# +# Setup SDLC pipeline labels for the repository. +# This script is idempotent - running it multiple times is safe. +# +# Labels created: +# sdlc:refine - Issue is in the refine phase +# sdlc:plan - Issue is in the plan phase +# sdlc:implement - Issue is in the implement phase +# sdlc:pr - Issue has a PR in review +# sdlc:awaiting-approval - Waiting for human approval +# +# Usage: +# ./setup-sdlc-labels.sh [--repo owner/repo] +# +# Requires: +# - gh CLI authenticated +# - GH_TOKEN environment variable or gh auth login + +set -euo pipefail + +# Default to current repository if not specified +REPO="${REPO:-}" + +# Parse arguments +while [[ $# -gt 0 ]]; do + case "$1" in + --repo) + REPO="$2" + shift 2 + ;; + *) + echo "Unknown argument: $1" >&2 + exit 1 + ;; + esac +done + +# If no repo specified, get from git remote +if [[ -z "$REPO" ]]; then + REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null) || { + echo "Error: Could not determine repository. Use --repo owner/repo" >&2 + exit 1 + } +fi + +echo "Setting up SDLC labels for repository: ${REPO}" + +# Define labels: name|color|description +LABELS=( + "sdlc:refine|0E8A16|SDLC pipeline: refine phase" + "sdlc:plan|1D76DB|SDLC pipeline: plan phase" + "sdlc:implement|D93F0B|SDLC pipeline: implement phase" + "sdlc:pr|5319E7|SDLC pipeline: PR in review" + "sdlc:awaiting-approval|FBCA04|SDLC pipeline: waiting for human approval" +) + +for label_spec in "${LABELS[@]}"; do + IFS='|' read -r name color description <<< "$label_spec" + + # URL-encode the label name for API paths (: becomes %3A) + encoded_name="${name//:/%3A}" + + # Check if label exists + if gh api "repos/${REPO}/labels/${encoded_name}" >/dev/null 2>&1; then + echo "Updating label: ${name}" + gh api "repos/${REPO}/labels/${encoded_name}" \ + -X PATCH \ + -f color="${color}" \ + -f description="${description}" \ + --silent + else + echo "Creating label: ${name}" + gh api "repos/${REPO}/labels" \ + -X POST \ + -f name="${name}" \ + -f color="${color}" \ + -f description="${description}" \ + --silent + fi +done + +echo "SDLC labels setup complete" diff --git a/.github/scripts/transition-sdlc-label.sh b/.github/scripts/transition-sdlc-label.sh new file mode 100755 index 0000000000..934400fce6 --- /dev/null +++ b/.github/scripts/transition-sdlc-label.sh @@ -0,0 +1,165 @@ +#!/usr/bin/env bash +# +# Transition SDLC labels atomically on an issue or PR. +# +# This script handles label transitions with proper error handling +# and ensures the target label is applied before removing the source. +# +# Usage: +# transition-sdlc-label.sh --issue --from