ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/17-24-rework-prioritize-backlog.md

@@ -1,344 +0,0 @@
-# Story 17.24: Rework prioritize-backlog Skill (Light Rework -- Create from Scratch)
-
-Status: review
-
-## Story
-
-As a **Scrum Master**,
-I want the `prioritize-backlog` skill to reorder items in the `backlog` section of the unified `sprint-status.yaml` using multiple prioritization criteria (severity, business value, dependencies, type, age),
-So that backlog reprioritization works against the single source of truth, is available across all IDE agents and BMAD workflows, and supports interactive, automated, and suggestion-only modes.
-
-## Acceptance Criteria
-
-1. **Given** the `prioritize-backlog` skill is invoked from ANY IDE agent (Claude Code, Cursor, Cline, Roo Code, Gemini, Copilot, Kilocode, etc.) OR from a BMAD workflow,
-   **When** the unified `sprint-status.yaml` exists,
-   **Then** it reads items from the `backlog` section only (items assigned to a sprint are NOT shown and NOT reprioritized),
-   **And** the display shows items in current priority order with columns: Priority, ID, Title, Type, Epic, Severity, Status.
-
-2. **Given** the `backlog` section contains items,
-   **When** the Scrum Master selects **Full** mode (interactive reprioritization),
-   **Then** the skill presents the current backlog order alongside a suggested new order based on multi-criteria analysis,
-   **And** the Scrum Master can accept, modify, or reject the suggested order,
-   **And** upon acceptance the skill renumbers `priority` values 1..N to match the new array positions,
-   **And** writes the reordered `backlog` section back to `sprint-status.yaml` in a single atomic write,
-   **And** updates the `last_updated` metadata timestamp,
-   **And** all other sections (`epics`, `sprints`) are preserved unchanged.
-
-3. **Given** the `backlog` section contains items,
-   **When** the Scrum Master selects **Quick** mode (automated reprioritization),
-   **Then** the skill applies the default prioritization rules automatically without interactive approval,
-   **And** renumbers `priority` values 1..N,
-   **And** writes the reordered backlog in a single atomic write,
-   **And** displays a summary of what changed (items that moved up, down, or stayed in place).
-
-4. **Given** the `backlog` section contains items,
-   **When** the Scrum Master selects **Auto-suggest** mode,
-   **Then** the skill generates a suggested new ordering with per-item rationale,
-   **And** displays the suggestions without modifying `sprint-status.yaml`,
-   **And** no file write occurs.
-
-5. **Given** the prioritization criteria are applied,
-   **When** the skill scores and ranks backlog items,
-   **Then** the following criteria are evaluated in weighted order (FR67):
-   - **Severity** -- critical and high bugs float to the top
-   - **Business value** -- high-value items rank higher
-   - **Dependencies** -- items blocking other items receive a priority boost
-   - **Type weighting** -- bugs receive a slight priority boost over stories (at equal value)
-   - **Age** -- older items (lower epic number or earlier creation) receive a slight boost to prevent starvation
-
-6. **Given** `sprint-status.yaml` does not exist,
-   **When** the skill is invoked,
-   **Then** it reports: "No sprint-status.yaml found. Run sprint planning first to initialize the file.",
-   **And** exits without creating any file.
-
-7. **Given** the `backlog` section is empty (all items assigned to sprints or no items exist),
-   **When** the skill is invoked,
-   **Then** it reports: "Backlog is empty. Nothing to prioritize.",
-   **And** exits without modifying the file.
-
-8. **Given** the old `backlog.yaml` file exists alongside `sprint-status.yaml`,
-   **When** the skill is invoked,
-   **Then** it operates on `sprint-status.yaml` only (the old file is ignored; see Story 17.23 for migration),
-   **And** logs a note: "Legacy backlog.yaml detected. Run migration to consolidate."
-
-9. **Given** the skill source files exist in BOTH deployment pipelines (IDE skill at `skills/prioritize-backlog/` and BMAD extension at `lib/bmad-extension/skills/prioritize-backlog/`),
-   **When** the ma-agents installer is run,
-   **Then** the IDE skill is deployed to all agent directories via `lib/installer.js` (`performInstall`),
-   **And** the BMAD extension skill is deployed via `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`,
-   **And** the installed copies are byte-identical to their source (minus frontmatter injection by the installer for the IDE path).
-
-10. **Given** the skill is invoked from ANY IDE agent OR from a BMAD workflow,
-    **When** it executes,
-    **Then** it works identically in both invocation modes (NFR19).
-
-## Tasks / Subtasks
-
-### Task 1: Create the IDE skill source files (AC: 9, 10) -- NEW
-
-The IDE skill does NOT exist. The previous (rolled-back) Phase 1 implementation only modified an installed copy at `.claude/skills/prioritize-backlog/SKILL.md`, which was wiped on rollback. This task creates the skill from scratch in the correct source location.
-
-- [x] 1.1 Create `skills/prioritize-backlog/skill.json` with metadata:
-  ```json
-  {
-    "name": "prioritize-backlog",
-    "version": "1.0.0",
-    "description": "Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age",
-    "category": "workflow",
-    "tags": ["backlog", "prioritization", "sprint-management"]
-  }
-  ```
-  Note: `always_load` is intentionally omitted (defaults to false) -- this skill is invoked on demand, not loaded for every task.
-
-- [x] 1.2 Create `skills/prioritize-backlog/SKILL.md` with the complete skill workflow (see Task 3 for content specification). This is the canonical skill content that the installer deploys to all IDE agents.
-
-### Task 2: Create the BMAD extension skill source files (AC: 9, 10) -- NEW
-
-The BMAD extension skill does NOT exist. The previous Phase 1 implementation never created files in this pipeline. This task creates the skill from scratch.
-
-- [x] 2.1 Create `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` -- this is a SEPARATE file from the IDE skill SKILL.md. The BMAD extension version is authored for the BMAD Scrum Master agent (`bmm-sm`) context and may have BMAD-specific phrasing (e.g., referencing `_bmad/bmm/config.yaml` for path resolution). The core workflow logic MUST be functionally identical to the IDE version.
-
-- [x] 2.2 Create `lib/bmad-extension/skills/prioritize-backlog/bmad-skill-manifest.yaml`:
-  ```yaml
-  type: skill
-  name: prioritize-backlog
-  module: ma-skills
-  ```
-
-- [x] 2.3 Register the skill in `lib/bmad-extension/module-help.csv` by adding a row:
-  ```csv
-  ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age.",_bmad-output/implementation-artifacts,"backlog",
-  ```
-  The `agent` column is `bmm-sm` (Scrum Master) because backlog prioritization is a Scrum Master responsibility.
-
-### Task 3: Implement the skill workflow content (AC: 1, 2, 3, 4, 5, 6, 7, 8)
-
-The SKILL.md content (for both the IDE and BMAD extension versions) must implement the following workflow. Both versions MUST be functionally identical in their workflow logic.
-
-- [x] 3.1 **Step 0 -- Load configuration and validate file existence:**
-  - Read `sprint-status.yaml` at `_bmad-output/implementation-artifacts/sprint-status.yaml` (or resolve path from config).
-  - If the file does not exist, report error: "No sprint-status.yaml found. Run sprint planning first to initialize the file." Exit (AC 6).
-  - Parse the full file: `epics`, `backlog`, and `sprints` sections.
-  - If a legacy `backlog.yaml` file exists in the same directory, log a note: "Legacy backlog.yaml detected. Run migration to consolidate." Do NOT read or operate on the legacy file (AC 8).
-  - If the `backlog` array is empty, report: "Backlog is empty. Nothing to prioritize." Exit (AC 7).
-
-- [x] 3.2 **Step 1 -- Display current backlog order:**
-  - Read the `backlog` array from the parsed `sprint-status.yaml`.
-  - Display items in current priority order in a table with columns: Priority (#), ID, Title, Type, Epic, Severity, Status.
-  - Show total count of backlog items.
-  - Do NOT display items from any sprint's `items` array -- only `backlog` section items are shown (AC 1).
-
-- [x] 3.3 **Step 2 -- Choose prioritization mode:**
-  - Prompt the Scrum Master to select a mode:
-    - **[f] Full** -- interactive: generates a suggested order, presents current vs proposed side-by-side, user approves or adjusts before write.
-    - **[q] Quick** -- automated: applies default rules and reorders immediately, then shows summary of changes.
-    - **[a] Auto-suggest** -- read-only: generates suggestions with per-item rationale, no file modification.
-  - Store selected mode for the workflow branch.
-
-- [x] 3.4 **Step 3 -- Multi-criteria prioritization analysis (all modes):**
-  - For each item in the `backlog` array, compute a composite priority score using weighted criteria (AC 5, FR67):
-    1. **Severity weight (highest impact):** Items with `severity: critical` get the highest score boost. `high` > `medium` > `low`. Items with `severity: null` (stories) get no severity adjustment.
-    2. **Business value weight:** Inferred from item context -- items in earlier epics or with explicit priority indicators rank higher. If the item's current `priority` value is low (was previously prioritized high), preserve that signal.
-    3. **Dependency weight:** Read `epics.md` to identify explicit dependencies between stories. Items that BLOCK other items (other items depend on them) get a priority boost. Items that ARE BLOCKED get a slight deprioritization (they cannot proceed anyway). Within the same epic, assume stories are sequential (lower story number first).
-    4. **Type weight:** Bugs (`type: bug`) receive a slight priority boost over stories (`type: story`) at otherwise equal scoring, reflecting the principle that defects should be addressed before new features.
-    5. **Age weight (starvation prevention):** Items from lower-numbered epics or with lower item numbers within their epic get a slight boost to prevent indefinite deferral. This is the weakest signal -- it is a tiebreaker, not a dominant factor.
-  - Produce a ranked list sorted by composite score (highest score = priority 1).
-
-- [x] 3.5 **Step 3a -- Full mode workflow (AC: 2):**
-  - Display a comparison table: current order (left) vs suggested order (right), highlighting items that would move.
-  - For each item that changes position, show a brief rationale (e.g., "critical bug", "blocks 3 items", "age > 2 epics").
-  - Prompt: "[a] Accept suggested order / [m] Manually adjust (enter new order) / [c] Cancel"
-  - On `a`: proceed to Step 4 with the suggested order.
-  - On `m`: prompt the user to enter item numbers in their desired order. Validate that all items are accounted for (no duplicates, no missing). Proceed to Step 4 with the manual order.
-  - On `c`: exit without changes.
-
-- [x] 3.6 **Step 3b -- Quick mode workflow (AC: 3):**
-  - Apply the computed ranked order directly without prompting.
-  - Proceed immediately to Step 4 with the computed order.
-
-- [x] 3.7 **Step 3c -- Auto-suggest mode workflow (AC: 4):**
-  - Display the suggested new order with per-item rationale in a detailed table: New Priority, ID, Title, Rationale, Change (e.g., "+3 up", "-2 down", "unchanged").
-  - Display a summary: N items would move up, M items would move down, K items unchanged.
-  - Do NOT proceed to Step 4. Exit with: "Suggestions displayed. No changes written. Run again in Full or Quick mode to apply."
-
-- [x] 3.8 **Step 4 -- Apply reordering and persist (AC: 2, 3):**
-  - Take the confirmed ordering (from Full or Quick mode).
-  - Reorder the `backlog` array to match the new order.
-  - Renumber the `priority` field on each item sequentially: position 0 gets `priority: 1`, position 1 gets `priority: 2`, etc. (schema section 3.3: `priority` is a denormalized index that MUST be kept in sync with array position).
-  - Update the `last_updated` metadata field to the current ISO-8601 timestamp.
-  - Preserve the `generated` metadata field unchanged.
-  - Preserve the `epics` section unchanged.
-  - Preserve the `sprints` section unchanged.
-  - Write the complete `sprint-status.yaml` in a single atomic write (read-modify-write pattern).
-
-- [x] 3.9 **Step 5 -- Summary output:**
-  - Display the reprioritization summary:
-    - Mode used (Full / Quick).
-    - Items reordered: total count.
-    - Items that moved up (with old and new priority).
-    - Items that moved down (with old and new priority).
-    - Items unchanged.
-  - Suggest next steps: `/add-to-sprint` to assign top-priority items to a sprint, `/sprint-status-view` to view overall progress.
-
-### Task 4: Verify no legacy file references (AC: 8)
-
-- [x] 4.1 Confirm neither SKILL.md file contains any instruction to read from or write to `backlog.yaml` as a data source or write target.
-- [x] 4.2 Confirm neither SKILL.md file contains any instruction to write a standalone `backlog.yaml` file.
-- [x] 4.3 Confirm the only data file read/written is `sprint-status.yaml`.
-- [x] 4.4 Confirm neither SKILL.md file references the old `development_status` map or `sprint-plan-*.yaml` files.
-
-### Task 5: Deployment verification (AC: 9)
-
-- [x] 5.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer.
-- [x] 5.2 Verify the IDE skill appears in the installed MANIFEST.yaml for at least one agent (e.g., check `.claude/skills/MANIFEST.yaml` includes `prioritize-backlog`).
-- [x] 5.3 Diff the installed IDE copy (e.g., `.claude/skills/prioritize-backlog/SKILL.md`) against the source (`skills/prioritize-backlog/SKILL.md`) -- the content should match after accounting for frontmatter injection by the installer.
-- [x] 5.4 Verify the BMAD extension copy exists at `_bmad/extensions/ma-agents-skills/skills/prioritize-backlog/SKILL.md` after a BMAD install.
-- [x] 5.5 Verify the BMAD extension copy matches the source at `lib/bmad-extension/skills/prioritize-backlog/SKILL.md`.
-- [x] 5.6 Verify `prioritize-backlog` appears in the BMAD module help output.
-
-## Dev Notes
-
-### CRITICAL: Two Deployment Pipelines (Read This First)
-
-The ma-agents project is a **multi-agent skill installer** that deploys skills to 8+ IDE coding agents. There are TWO independent deployment pipelines, and this story creates source files for BOTH.
-
-**Why this matters:** The previous version of this story was fundamentally wrong -- it directed edits to `.claude/skills/prioritize-backlog/SKILL.md`, which is an INSTALLED COPY (a read-only deployed artifact). That path is where the installer OUTPUTS files, not where source files live. Furthermore, the Phase 1 implementation was rolled back entirely, so `prioritize-backlog` does NOT currently exist in either pipeline. This story creates it from scratch in both locations.
-
-#### Pipeline 1: IDE Skills (all IDE agents) -- NEW
-
-- **Source location:** `skills/prioritize-backlog/skill.json` + `skills/prioritize-backlog/SKILL.md`
-- **Status:** Does NOT exist. Task 1 creates these files from scratch.
-- **Deployed by:** `lib/installer.js` -> `performInstall()` which:
-  1. Reads `skill.json` for metadata
-  2. Falls back through: `templates/<agent>.md` -> `templates/generic.md` -> `SKILL.md`
-  3. Strips existing frontmatter, injects fresh frontmatter from `skill.json`
-  4. Copies to each agent's install directory (e.g., `.claude/skills/`, `.cursor/skills/`, etc.)
-- **Never hardcode agent paths.** The installer handles deployment to all agents automatically.
-- **Reference skill:** See `skills/story-status-lookup/` for a working example of `skill.json` + `SKILL.md`.
-
-#### Pipeline 2: BMAD Extension Skills (BMAD agents only) -- NEW
-
-- **Source location:** `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` + `bmad-skill-manifest.yaml`
-- **Status:** Does NOT exist. Task 2 creates these files from scratch.
-- **Deployed by:** `lib/bmad.js` which copies `lib/bmad-extension/` to `_bmad/extensions/ma-agents-skills/`
-- **Registered in:** `lib/bmad-extension/module-help.csv` (new row mapping to `bmm-sm` agent)
-- **Reference skill:** See `lib/bmad-extension/skills/add-to-sprint/` for a working example of `SKILL.md` + `bmad-skill-manifest.yaml`.
-
-#### Install Locations (NEVER edit these directly)
-
-- `.claude/skills/`, `.cursor/skills/`, `.cline/skills/`, `.roo/skills/`, `.gemini/skills/`, `.github/copilot/skills/`, `.kilocode/skills/` -- all managed by installer
-- `_bmad/extensions/ma-agents-skills/skills/` -- managed by BMAD deployer
-
-### What This Story Changes vs Current Behavior
-
-**Current state (post-rollback):** The `prioritize-backlog` skill does NOT exist in either pipeline. The Phase 1 implementation created an installed copy at `.claude/skills/prioritize-backlog/SKILL.md` that read/wrote a standalone `backlog.yaml` file. That implementation was rolled back in commit `85fad06`. No source files for this skill exist anywhere in the repository.
-
-**New behavior:** The skill is created from scratch in BOTH deployment pipelines. It reads the `backlog` array from `sprint-status.yaml`, applies multi-criteria prioritization scoring, and writes the reordered backlog back to the same file. Three modes are supported: Full (interactive), Quick (automated), and Auto-suggest (read-only). The `sprints` and `epics` sections are preserved unchanged on every write.
-
-### Key Design Decisions
-
-- **Output target:** `sprint-status.yaml` `backlog` section only. No standalone `backlog.yaml` is read or written.
-- **Scope boundary:** Only items in the `backlog` array are subject to reprioritization. Items in `sprints[].items` are completely excluded from the view and from scoring. This respects the single-location invariant (schema section 6.1).
-- **Three modes:** Full (interactive approval), Quick (automated apply), Auto-suggest (display-only). This provides flexibility from full control to quick automation.
-- **Priority renumbering:** After reordering, `priority` values are renumbered 1..N to keep the denormalized index in sync with array positions (schema section 3.3).
-- **Atomic write:** Single read-modify-write to `sprint-status.yaml`. The `backlog` section is replaced with the reordered version; `epics` and `sprints` sections are passed through unchanged.
-- **Weighted criteria (FR67):** Severity > Business Value > Dependencies > Type > Age. Severity is the strongest signal (critical bugs must float to top); age is the weakest (tiebreaker to prevent starvation).
-- **Dependency inference:** Reads `epics.md` for explicit inter-story dependencies. Within the same epic, assumes sequential ordering (lower story number = earlier dependency). Items that block other items get a priority boost.
-- **Legacy file handling:** If `backlog.yaml` exists alongside `sprint-status.yaml`, it is ignored with a logged note suggesting migration (Story 17.23).
-
-### Unified Schema Sections Touched
-
-- **`backlog`** -- read (display items, compute scores) + write (reordered array with renumbered priorities)
-- **`epics`** -- preserved unchanged (pass-through on write)
-- **`sprints`** -- preserved unchanged (pass-through on write); NOT read for item discovery (only `backlog` is in scope)
-- **Metadata** -- `last_updated` is updated on every write; `generated` is preserved unchanged
-
-### Rework Level: Light (but Create from Scratch)
-
-The epics document classifies this as a "Light rework" because the core prioritization logic (multi-criteria scoring, three modes, dependency analysis) is conceptually simple and well-defined. However, because the Phase 1 implementation was fully rolled back, the dev agent must create all files from scratch rather than modifying existing files. The tasks reflect this reality -- there are no files to read or modify, only files to create.
-
-### Prioritization Criteria Details (FR67)
-
-The following criteria are used to compute a composite priority score for each backlog item:
-
-| Criteria | Weight | Signal Source | Effect |
-|----------|--------|---------------|--------|
-| Severity | Highest | `severity` field on item | `critical` = top, `high` = elevated, `medium`/`low` = moderate/slight boost, `null` = no effect |
-| Business Value | High | Existing `priority` value, epic importance | Preserves existing prioritization signals; items from higher-priority epics rank higher |
-| Dependencies | Medium | `epics.md` inter-story dependencies | Blocking items boosted; blocked items slightly deprioritized |
-| Type | Low | `type` field on item | `bug` gets slight boost over `story` at equal composite score |
-| Age | Lowest | Epic number, item position | Lower epic number = older = slight boost; tiebreaker only |
-
-### Reference Files
-
-- **Schema:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (canonical schema, especially section 3 for backlog items, section 3.3 for priority renumbering)
-- **Sprint status:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
-- **Epics source:** `_bmad-output/planning-artifacts/epics.md` (for dependency inference in prioritization scoring)
-- **IDE skill reference:** `skills/story-status-lookup/skill.json` + `skills/story-status-lookup/SKILL.md` (example of `skill.json` + `SKILL.md` structure)
-- **BMAD skill reference:** `lib/bmad-extension/skills/add-to-sprint/` (example of `SKILL.md` + `bmad-skill-manifest.yaml`)
-- **Module help CSV:** `lib/bmad-extension/module-help.csv`
-- **PRD:** `_bmad-output/planning-artifacts/prd.md` (FR67, FR133, FR134)
-
-### Cross-References
-
-- **Story 17.9** (prerequisite): Defines the unified `sprint-status.yaml` schema and the `backlog` array item structure with `priority` field (section 3)
-- **Story 17.15** (prerequisite): `bmad-sprint-planning` bootstraps the file; `prioritize-backlog` requires it to exist
-- **Story 17.10** (prerequisite): `generate-backlog` populates the `backlog` section that this skill reorders
-- **Story 17.11** (downstream): `add-to-sprint` moves top-priority items from the backlog this skill orders into sprints
-- **Story 17.12** (peer): `remove-from-sprint` may return items to backlog, which may then need reprioritization
-- **Story 17.23** (migration): Migrates old `backlog.yaml` to the unified file; this skill ignores the legacy file if present
-
-### PRD Traceability
-
-- **FR67:** Story/bug prioritization supports multiple criteria beyond epic precedence -- criteria include severity, business value, dependencies, type, and age. This is the primary FR for this story; the multi-criteria scoring engine implements it directly.
-- **FR133:** `sprint-status.yaml` includes top-level metadata (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`) -- `last_updated` must be refreshed on write.
-- **FR134:** Each item in the backlog carries a consistent structure (`id`, `type`, `epic`, `title`, `priority`, `status`, `severity`). Prioritization respects section boundaries -- items in `backlog` are reordered; items in `sprints` are untouched.
-- **FR65:** All sprint, backlog, and epic status data is managed in a single `sprint-status.yaml` file. This skill reads from and writes to that single file.
-- **NFR19:** Skills work identically across invocation modes (slash command, menu, workflow).
-
-### Architecture Reference
-
-- Architecture Decision P2-5 in `_bmad-output/planning-artifacts/architecture.md` -- Pre-built Extension Workflows (FR61, FR68-FR70)
-- Architecture Decision P2-11 in `_bmad-output/planning-artifacts/architecture.md` -- Unified sprint-status.yaml model
-- Schema: `_bmad-output/planning-artifacts/sprint-status-schema.md` -- canonical schema, especially section 3 (backlog), section 3.3 (priority renumbering invariant), section 6.1 (single-location invariant)
-
----
-
-## Dev Agent Record
-
-### Implementation Notes
-
-- Created skill from scratch in both deployment pipelines (IDE + BMAD extension).
-- IDE skill (`skills/prioritize-backlog/`) uses `skill.json` + `SKILL.md` pattern — no `always_load` (on-demand skill).
-- BMAD extension (`lib/bmad-extension/skills/prioritize-backlog/`) adds frontmatter triggers and BMAD config path resolution.
-- The BMAD version checks `_bmad/bmm/config.yaml` for a `sprint_status_path` override before defaulting to the standard path.
-- Both versions implement identical multi-criteria scoring (severity, business value, dependencies, type, age) and all three modes (Full, Quick, Auto-suggest).
-- Registered in `lib/bmad-extension/module-help.csv` with `bmm-sm` agent assignment.
-
-### Code Review Findings (2026-04-06)
-
-- AC 1-10: All acceptance criteria implemented.
-- No `backlog.yaml` read/write instructions — only detection + warning (AC 8). PASS.
-- No `development_status` map or `sprint-plan-*.yaml` references. PASS.
-- Priority renumbering 1..N in Step 4. PASS.
-- Epics/sprints/generated preserved unchanged on every write. PASS.
-- Three modes (Full/Quick/Auto-suggest) all implemented. PASS.
-- Cross-repo-validation test failure is pre-existing (unrelated to this story — checked on main branch). PASS.
-
-### File List
-
-**Created:**
-- `skills/prioritize-backlog/skill.json` — IDE skill metadata
-- `skills/prioritize-backlog/SKILL.md` — IDE skill workflow (canonical source)
-- `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` — BMAD extension skill workflow
-- `lib/bmad-extension/skills/prioritize-backlog/bmad-skill-manifest.yaml` — BMAD skill manifest
-
-**Modified:**
-- `lib/bmad-extension/module-help.csv` — Added `prioritize-backlog` row for `bmm-sm` agent
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Status updated to `review`
-- `_bmad-output/implementation-artifacts/17-24-rework-prioritize-backlog.md` — Story status + tasks updated
-
-### Change Log
-
-| Date | Change | Author |
-|------|--------|--------|
-| 2026-04-06 | Created skill from scratch in both deployment pipelines; implemented multi-criteria prioritization with Full/Quick/Auto-suggest modes | Dev Agent |

package/_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md

@@ -1,279 +0,0 @@
-# Story 17.9: Unified sprint-status.yaml Schema
-
-Status: done
-
-## Story
-
-As a **Scrum Master**,
-I want all sprint management data consolidated into a single `sprint-status.yaml` file with three structured sections (epics, backlog, sprints),
-So that there is one source of truth for all sprint/backlog state — eliminating data duplication and cross-file consistency bugs.
-
-## Acceptance Criteria
-
-1. **Given** the unified schema is defined,
-   **When** `sprint-status.yaml` is created or updated by any skill,
-   **Then** it contains exactly three data sections (`epics`, `backlog`, `sprints`) plus top-level metadata fields (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`).
-
-2. **Given** the `epics` section exists,
-   **When** any skill reads it,
-   **Then** it is a YAML **map** keyed by epic ID (e.g., `epic-5:`) with fields `status` (`backlog` | `in-progress` | `done`) and `retrospective` (`optional` | `done` | null).
-
-3. **Given** the `backlog` section exists,
-   **When** any skill reads it,
-   **Then** it is a YAML **array** of item objects. Each item has: `id` (string), `type` (`story` | `bug`), `epic` (integer | null), `title` (string), `priority` (integer), `status` (string), and optional `severity` (null | `critical` | `high` | `medium` | `low`).
-
-4. **Given** the `sprints` section exists,
-   **When** any skill reads it,
-   **Then** it is a YAML **map** keyed by sprint ID (e.g., `sprint-3:`) with fields: `name` (string), `status` (`planning` | `active` | `closed`), `capacity` (integer), `start` (ISO date string or empty), `end` (ISO date string or empty), and `items` (array of item objects — same schema as backlog items but WITHOUT the `priority` field).
-
-5. **Given** a story or bug exists in the file,
-   **When** any skill searches for it,
-   **Then** the item exists in exactly **one** location — either the `backlog` array OR a single sprint's `items` array. Never both.
-
-6. **Given** an item's status changes (e.g., `ready-for-dev` to `in-progress`),
-   **When** the status is updated by any skill,
-   **Then** the `status` field is updated **in-place** on the item in whichever section it resides.
-
-7. **Given** an item reaches `done` status,
-   **When** cleanup runs (Story 17.14),
-   **Then** the item is REMOVED from `sprint-status.yaml` entirely and archived to `done/`.
-
-8. **Given** a sprint transitions from `planning` to `active`,
-   **When** the activation occurs,
-   **Then** only one sprint can have `status: active` at a time. The previous active sprint must be closed first.
-
-9. **Given** the `tracking_system` field is set to `file-system` (default),
-   **When** any sprint skill runs,
-   **Then** it reads/writes the local YAML file. When set to `jira`, skills route to the Jira adapter (Story 17.22).
-
-## Tasks / Subtasks
-
-- [x] Task 1: Define canonical YAML schema (AC: 1-4)
-  - [x] 1.1 Write the canonical schema as a reference specification — this is the contract ALL 13 skills will code against
-  - [x] 1.2 Document the top-level metadata fields and their semantics
-  - [x] 1.3 Document the `epics` map schema with status transitions
-  - [x] 1.4 Document the `backlog` array item schema with all fields
-  - [x] 1.5 Document the `sprints` map schema with sprint entity and items sub-schema
-  - [x] 1.6 Document the item schema difference between backlog (has `priority`) and sprint items (no `priority`)
-- [x] Task 2: Define invariants and constraints (AC: 5-8)
-  - [x] 2.1 Document the single-location invariant — an item ID must appear in exactly one section
-  - [x] 2.2 Document the in-place status update rule
-  - [x] 2.3 Document the done-removal rule
-  - [x] 2.4 Document the single-active-sprint constraint
-  - [x] 2.5 Document valid sprint status transitions: `planning` → `active` → `closed` (no backward)
-  - [x] 2.6 Document valid story status transitions: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
-- [x] Task 3: Define the tracking_system adapter contract (AC: 9)
-  - [x] 3.1 Document the `tracking_system` field semantics (`file-system` vs `jira`)
-  - [x] 3.2 Document that the schema is the canonical data contract for both backends
-- [x] Task 4: Create a reference example file (AC: 1-9)
-  - [x] 4.1 Write a fully populated example `sprint-status.yaml` showing all sections with realistic data from the agents project
-  - [x] 4.2 Include edge cases: a bug in backlog, a closed sprint with empty items, a planning sprint with no items
-
-### Review Findings
-
-- [x] [Review][Decision] #1 `on-hold` and `cancelled` statuses added to schema — Added to epic statuses (Section 2.3) and item statuses (Section 6.6) with transition rules. `on-hold` is bidirectional pause; `cancelled` is terminal from any non-done state. **Resolved.**
-- [x] [Review][Decision] #2 `canceled` status — Resolved by #1. Added `cancelled` as terminal status for both epics and items.
-- [x] [Review][Decision] #3 Priority dual-authority resolved — Array position is now authoritative; `priority` field is denormalized index kept in sync (Section 3.3). Validation rule 12 added.
-- [x] [Review][Decision] #4 `remove-from-sprint` status reset — Status resets to `ready-for-dev` (not `backlog`, because story file already exists). Only `ready-for-dev` items may be added to sprints. Documented in Section 4.5 and Section 6.6. **Resolved.**
-- [x] [Review][Decision] #5 Closed sprint immutability exception — Section 6.7 now has explicit exception for done/cancelled item archival by `cleanup-done`. Section 6.8 added for sprint item disposition on close. **Resolved.**
-- [x] [Review][Decision] #6 Capacity is advisory — Section 4.2 updated: skills SHOULD warn but MUST NOT block when items exceed capacity. **Resolved.**
-- [x] [Review][Patch] #7 P2-11 sprint item `priority` removed — architecture.md line 956 fixed. **Applied.**
-- [x] [Review][Patch] #8 P2-11 backlog status constraint aligned — architecture.md line 969 updated to match schema Section 3.3. **Applied.**
-- [x] [Review][Patch] #9 Story Dev Notes reference fixed — "17.2-17.16" → "17.10-17.24". **Applied.**
-- [x] [Review][Patch] #10 Empty section validity notes added — `backlog: []` and `epics: {}` documented as valid (Sections 2.4 and 3.3). **Applied.**
-- [x] [Review][Patch] #11 Epic-to-item mapping rule added — `epic: N` maps to `epic-N` key; `epic: null` excluded from derivation (Section 3.3). **Applied.**
-- [x] [Review][Patch] #12 Done item movement restriction added — `done` items cannot be moved to backlog; only archived (Section 4.5). **Applied.**
-- [x] [Review][Patch] #13 Priority reassignment rule defined — `max(existing) + 1`; empty backlog gets `priority: 1` (Section 4.5). **Applied.**
-- [x] [Review][Patch] #14 Closed sprint disposition note added — New Section 6.8 documents item disposition before close. **Applied.**
-- [x] [Review][Defer] #15 sprint-status.yaml still uses old flat `development_status` format — deferred, pre-existing (migration is Story 17.23)
-- [x] [Review][Defer] #16 `generated` field in sprint-status.yaml is bare date, not ISO-8601 datetime — deferred, pre-existing (will be reformatted by Story 17.15 bootstrap)
-- [x] [Review][Defer] #17 No `schema_version` metadata field — deferred, out of scope for 17.9 (can be added in a future story if schema evolution is needed)
-- [x] [Review][Defer] #18 Concurrent modification has no locking guidance — deferred, skills run serially in current architecture
-- [x] [Review][Defer] #19 `correct-course` referenced in Section 4.6 but not in skill map — deferred, informational reference only
-
-## Dev Notes
-
-### What This Story IS
-
-This is a **schema definition** story, not a skill implementation story. The deliverable is a canonical YAML schema specification that serves as the contract for all 13 skills that will be reworked in subsequent stories (17.10-17.24). Think of it as the "protobuf definition" — the interface contract that everything else implements against.
-
-### What This Story Is NOT
-
-This story does NOT:
-- Modify any existing skills
-- Write any JavaScript/TypeScript code
-- Change how any skill reads or writes sprint-status.yaml
-- Migrate existing data
-
-Those are all subsequent stories (17.10-17.24).
-
-### Current State (What's Being Replaced)
-
-The current `sprint-status.yaml` uses a **flat `development_status` map**:
-
-```yaml
-generated: 2026-03-15
-project: agents
-tracking_system: file-system
-story_location: _bmad-output/implementation-artifacts
-
-development_status:
-  epic-1: done
-  1-1-ci-cd-yes-flag: done
-  epic-1-retrospective: optional
-  epic-5: in-progress
-  5-5-explicit-parameter-passing: review
-```
-
-**Problems with this format:**
-- Epics, stories, and retrospectives share a flat namespace
-- No sprint entity — just a status list
-- No backlog concept — items are either in the list or not
-- No movement semantics — status is a string, not a lifecycle
-- Separate `backlog.yaml` and `sprints/sprint-N.yaml` files exist but drift out of sync
-
-### New Schema (The Deliverable)
-
-```yaml
-generated: "2026-04-03T12:00:00Z"
-last_updated: "2026-04-03T12:00:00Z"
-project: agents
-project_key: NOKEY
-tracking_system: file-system
-story_location: _bmad-output/implementation-artifacts
-
-epics:
-  epic-5:
-    status: in-progress
-    retrospective: optional
-  epic-17:
-    status: in-progress
-    retrospective: optional
-
-backlog:
-  - id: "17-10-rework-generate-backlog"
-    type: story
-    epic: 17
-    title: "Rework generate-backlog Skill"
-    priority: 1
-    status: backlog
-    severity: null
-  - id: "BUG-path-spaces"
-    type: bug
-    epic: null
-    title: "Fix space-in-path bug"
-    priority: 2
-    status: backlog
-    severity: high
-
-sprints:
-  sprint-3:
-    name: "Sprint 3"
-    status: active
-    capacity: 6
-    start: "2026-04-03"
-    end: "2026-04-14"
-    items:
-      - id: "5-5-explicit-parameter-passing"
-        type: story
-        epic: 5
-        title: "Explicit Parameter Passing"
-        status: in-progress
-        severity: null
-      - id: "5-6-fix-space-in-path-bug"
-        type: story
-        epic: 5
-        title: "Fix Space-in-Path Bug"
-        status: review
-        severity: null
-  sprint-2:
-    name: "Sprint 2"
-    status: closed
-    capacity: 8
-    start: "2026-03-15"
-    end: "2026-03-28"
-    items: []
-```
-
-### Key Schema Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| `epics` is a **map**, not array | Keyed lookup by `epic-N` — matches how skills search for epic status |
-| `backlog` is an **array** | Ordered by priority — position in array = priority rank |
-| `sprints` is a **map** keyed by sprint ID | Fast lookup by `sprint-N` key; matches existing sprint ID convention |
-| Items in backlog have `priority` field | Explicit numeric priority for sorting |
-| Items in sprint do NOT have `priority` | Once in a sprint, priority is implicit (order within the sprint) |
-| `severity` is null for stories | Only bugs have severity; null distinguishes stories from bugs alongside `type` |
-| Sprint `items` uses same schema minus `priority` | Consistency — same item object, just drops one field on move |
-
-### Skills That Will Consume This Schema (13 total)
-
-All of these will be reworked in subsequent stories to read/write the new schema:
-
-| Skill | Story | Operation | Current Schema Assumption |
-|-------|-------|-----------|--------------------------|
-| `bmad-sprint-planning` | 17.15 | Bootstraps entire file | Writes flat `development_status` map |
-| `generate-backlog` | 17.10 | Writes `backlog` section | Writes separate `backlog.yaml` |
-| `add-sprint` | 17.16 | Writes `sprints` section | Creates separate `sprints/sprint-N.yaml` |
-| `add-to-sprint` | 17.11 | Moves items backlog→sprint | Dual-writes `backlog.yaml` + `sprint-N.yaml` |
-| `remove-from-sprint` | 17.12 | Moves items sprint→backlog | Dual-writes reverse |
-| `sprint-status-view` | 17.13 | Reads all sections | Cross-references 3 files |
-| `cleanup-done` | 17.14 | Removes done items | Scans 3 files |
-| `modify-sprint` | 17.17 | Updates sprint entry | Reads/writes `sprint-N.yaml` |
-| `bmad-dev-story` | 17.18 | Updates item status | Writes flat `development_status[key]` |
-| `story-status-lookup` | 17.19 | Searches for item | Reads flat `development_status[key]` |
-| `bmad-sprint-status` | 17.20 | Summarizes sprint health | Parses flat key map |
-| `prioritize-backlog` | 17.24 | Reorders backlog items | Reads/writes `backlog.yaml` |
-| `close-sprint` | 17.21 | Closes sprint lifecycle | NEW — does not exist yet |
-
-### Architecture Reference
-
-- [Architecture P2-11: Unified Sprint-Status File Architecture](../_bmad-output/planning-artifacts/architecture.md) — full schema, design principles, skill integration map, adapter pattern
-- [PRD FR133-FR140](../_bmad-output/planning-artifacts/prd.md) — functional requirements for unified sprint-status
-- [Epics: Epic 17](../_bmad-output/planning-artifacts/epics.md) — all 16 stories with acceptance criteria
-
-### Project Structure Notes
-
-- Schema file location: `{sprint_management_path}/_bmad-output/implementation-artifacts/sprint-status.yaml` (resolved via `config.yaml`, defaults to `_bmad-output/implementation-artifacts/sprint-status.yaml`)
-- `done/` archive folder: `{implementation_artifacts}/done/`
-- Config path: `_bmad/bmm/config.yaml` → `sprint_management_path`, `implementation_artifacts`
-
-### Deliverable Location
-
-The schema specification should be written as a reference document. Suggested location: `_bmad-output/planning-artifacts/sprint-status-schema.md` — a standalone schema reference that dev agents can load when implementing skills 17.10-17.24.
-
-## Dev Agent Record
-
-### Agent Model Used
-
-Claude Opus 4.6 (1M context)
-
-### Debug Log References
-
-- Validated reference YAML example programmatically using Python `yaml.safe_load()` + structural assertions
-- All invariants verified: single-location, single-active-sprint, field completeness, sprint items lack `priority`
-
-### Completion Notes List
-
-- Created canonical schema specification at `_bmad-output/planning-artifacts/sprint-status-schema.md` (10 sections)
-- Section 1: Top-level structure — 6 metadata fields + 3 data sections
-- Section 2: Epics map schema — keyed by `epic-N`, status transitions `backlog → in-progress → done`
-- Section 3: Backlog array schema — 7 required fields per item including `priority`
-- Section 4: Sprints map schema — sprint entity + items sub-schema (6 fields, NO `priority`)
-- Section 5: Tracking system adapter contract — `file-system` vs `jira` backend behavior
-- Section 6: Invariants and constraints — 7 rules (single-location, in-place update, done-removal, single-active-sprint, sprint transitions, item transitions, closed sprint immutability)
-- Section 7: Skill integration map — all 13 consuming skills with rework level
-- Section 8: File location resolution — single-repo and multi-repo modes
-- Section 9: Reference example — fully populated YAML with 3 epics, 4 backlog items, 3 sprints (active/planning/closed)
-- Section 10: Schema validation checklist — 10-point validation rules for writing skills
-
-### Change Log
-
-- 2026-04-03: Created sprint-status-schema.md — canonical YAML schema specification (Story 17.9)
-
-### File List
-
-- `_bmad-output/planning-artifacts/sprint-status-schema.md` (NEW) — canonical schema reference document
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` (MODIFIED) — status updated for story 17-9
-- `_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md` (MODIFIED) — story file updates