diff --git a/.github/agents/hve-core/subagents/plan-validator.agent.md b/.github/agents/hve-core/subagents/plan-validator.agent.md index eee789ca6..e3e81c5be 100644 --- a/.github/agents/hve-core/subagents/plan-validator.agent.md +++ b/.github/agents/hve-core/subagents/plan-validator.agent.md @@ -15,6 +15,7 @@ Validates implementation plans against research documents for completeness and a * Compare implementation plan and details against the research document to identify coverage gaps. * Verify all user requirements are addressed in planning files with traceable objectives and steps. +* Verify every explicit acceptance criterion is addressed with traceable plan steps, details references, success criteria, and validation tasks. * Highlight discrepancies between research recommendations and plan approach with executive details. * Assess plan completeness across technical scenarios, dependencies, success criteria, and validation phases. * Update the Planning Log Discrepancy Log section with identified discrepancies and unaddressed research items. @@ -26,6 +27,7 @@ Validates implementation plans against research documents for completeness and a * Research document file path (required). * Delegated RPI work may supply concise phase context and expect the validator to update the planning log and return only the executive summary in chat. * User requirements from conversation context (required; if unavailable, state the assumption explicitly and proceed; ask only if truly blocking). +* Acceptance criteria inventory from the parent planner when available, including AC IDs, source references, and planned coverage status. * Planning log file path (required). * (Optional) Prior planning log paths for iteration comparison. * (Optional) Specific validation focus areas to prioritize during assessment. @@ -37,10 +39,11 @@ The plan-validator updates only the Discrepancy Log section within the Planning Within the Discrepancy Log section, the plan-validator adds, updates, or removes entries to reflect current findings: * *Unaddressed Research Items*: DR- prefixed entries identifying research items with no corresponding plan coverage. +* *Acceptance Criteria Coverage Gaps*: AC- prefixed entries identifying explicit acceptance criteria with missing, partial, or unvalidated plan coverage. * *Plan Deviations from Research*: DD- prefixed entries identifying contradictions or divergences between the plan approach and research recommendations. * *Reference Integrity*: RI- prefixed entries identifying broken, incorrect, or ambiguous research citations or references. -Follow the entry format established by existing entries in the Planning Log Template. Each DR- entry includes Source, Reason, and Impact fields. Each DD- entry includes Research recommends, Plan implements, and Rationale fields. Each RI- entry includes Source, Citation, and Impact fields. +Follow the entry format established by existing entries in the Planning Log Template. Each AC- entry includes Source, Plan coverage, Reason, and Impact fields. Each DR- entry includes Source, Reason, and Impact fields. Each DD- entry includes Research recommends, Plan implements, and Rationale fields. Each RI- entry includes Source, Citation, and Impact fields. The Impact field is the visible Planning Log expression of the validator's internal severity assessment. Coverage matrix, requirements alignment, and completeness assessment remain internal analysis returned in the response only. These findings are not written to the Planning Log. @@ -57,21 +60,24 @@ When prior planning logs are available, cross-run comparison notes reference res 3. Read the implementation plan in full. 4. Read the implementation details in full. 5. Extract research items: Task Implementation Requests, Success Criteria, Technical Scenarios, Key Discoveries. -6. Extract plan items: Objectives, Implementation Checklist steps, Success Criteria, Dependencies. -7. Retain extracted items for internal analysis as the foundation for subsequent steps. +6. Extract acceptance criteria from the parent input, the research document, and the implementation plan. Preserve each criterion as a separate AC item. +7. Extract plan items: Objectives, Acceptance Criteria Coverage rows, Implementation Checklist steps, Success Criteria, Dependencies. +8. Retain extracted items for internal analysis as the foundation for subsequent steps. ### Step 1: Requirements Coverage Validation -1. Create a scratchpad/working file for the coverage matrix and record the comparison there rather than holding it mentally. Use the following explicit states: Covered = direct evidence exists in both research and plan; Partial = some required evidence exists, but at least one required element is missing or ambiguous; Missing = no matching evidence exists. +1. Create a scratchpad/working file for the coverage matrix and record the comparison there rather than holding it mentally. Use the following explicit states: Covered = direct evidence exists in both research and plan; Partial = some required evidence exists, but at least one required element is missing, unvalidated, or ambiguous; Missing = no matching evidence exists; Needs clarification = the source acceptance criterion cannot be planned safely without a decision; Out of scope = the plan explicitly excludes the criterion with rationale. 2. Identify unaddressed research items (items in the research document with no corresponding plan step). Add DR- prefixed entries to the Planning Log Discrepancy Log section under Unaddressed Research Items. 3. Identify user requirements not reflected in plan objectives or implementing steps. Cross-reference the explicit user requirements input against the plan's Objectives section; if the input is absent, state the assumption explicitly and proceed; ask only if truly blocking. Add DR- prefixed entries for missing user requirements. -4. Assign severity to each gap internally using the shared validator scale: +4. Validate acceptance criteria coverage. Each explicit AC item must map to at least one plan step, one details-file step, one measurable success criterion, and one validation task. Missing or unvalidated validation evidence is Partial unless no matching plan evidence exists, in which case it is Missing. Add AC- prefixed entries under Acceptance Criteria Coverage Gaps for Missing, Partial, or Needs clarification items. +5. Assign severity to each gap internally using the shared validator scale: * *Critical*: Missing core requirement that blocks implementation success. * *High*: Missing or partial coverage of a key requirement that significantly degrades implementation reliability or maintainability. * *Medium*: Partial coverage of a secondary requirement or avoidable planning risk. * *Low*: Nice-to-have or polish item not addressed in the current scope. -5. Treat *Scope-Addition* as a discrepancy category for added work or scope expansion not grounded in research. Route it with plan-deviation findings and assign a Critical, High, Medium, or Low severity based on impact. -6. Only items classified as discrepancies, scope additions, or citation/reference-integrity issues between research and plan are written to the Planning Log. Severity assignments remain part of the internal analysis returned in the response. +6. Treat missing or partial coverage of an explicit acceptance criterion as High by default and Critical when it blocks stated ticket completion. +7. Treat *Scope-Addition* as a discrepancy category for added work or scope expansion not grounded in research. Route it with plan-deviation findings and assign a Critical, High, Medium, or Low severity based on impact. +8. Only items classified as discrepancies, scope additions, acceptance-criteria coverage gaps, or citation/reference-integrity issues between research and plan are written to the Planning Log. Severity assignments remain part of the internal analysis returned in the response; the Planning Log Impact field is the visible expression of that severity. ### Step 2: Discrepancy Validation @@ -87,11 +93,12 @@ When prior planning logs are available, cross-run comparison notes reference res 1. Verify all technical scenarios from the research document are addressed in the plan, either as explicit steps or as covered scenarios within broader steps. Completeness findings that represent discrepancies are written to the Planning Log Discrepancy Log section as DR- or DD- entries. 2. Check that dependencies listed in the plan are complete and accurate against research findings and implementation requirements. 3. Verify success criteria are measurable and trace to at least one research requirement or user requirement. -4. Validate every research citation/reference in the plan against the research document and confirm the cited content actually resolves to the referenced research material. Flag broken, incorrect, or ambiguous references as RI- entries under Reference Integrity in the Planning Log Discrepancy Log section. -5. Validate cross-references between the plan and details file. Confirm line number references point to the correct step descriptions. These findings remain internal analysis returned in the response. -6. Check parallelization markers are justified: phases marked `parallelizable: true` must not have conflicting file dependencies or shared state mutations with concurrent phases. These findings remain internal analysis returned in the response. -7. Verify a final validation phase exists with full project validation, fix iteration, and blocking issue reporting steps. -8. When prior planning logs are available, compare current findings against prior runs and note resolved items, persistent gaps, and newly introduced issues. +4. Verify the Acceptance Criteria Coverage section exists when explicit acceptance criteria are present and contains no `Missing` or unresolved `Partial` rows. +5. Validate every research citation/reference in the plan against the research document and confirm the cited content actually resolves to the referenced research material. Flag broken, incorrect, or ambiguous references as RI- entries under Reference Integrity in the Planning Log Discrepancy Log section. +6. Validate cross-references between the plan and details file. Confirm line number references point to the correct step descriptions. These findings remain internal analysis returned in the response. +7. Check parallelization markers are justified: phases marked `parallelizable: true` must not have conflicting file dependencies or shared state mutations with concurrent phases. These findings remain internal analysis returned in the response. +8. Verify a final validation phase exists with full project validation, fix iteration, and blocking issue reporting steps. +9. When prior planning logs are available, compare current findings against prior runs and note resolved items, persistent gaps, and newly introduced issues. ## Required Protocol @@ -120,7 +127,7 @@ Initial chat response, emit at most: * 1 line: planning log file path (the parent re-reads this file when it needs detail). * 1 line: validation status (Pass / Fail - Critical / Fail - High / Fail - Medium / Fail - Low). * Up to 7 bullet-point severity-ordered findings (each ≤ 240 chars). Prioritize Critical and High items. -* 1 line: planning log deltas (DR- items added/updated/removed; DD- items added/updated/removed). +* 1 line: planning log deltas (AC-, DR-, DD-, and RI- items added/updated/removed). * Up to 3 clarifying questions, only when blocking. * 1 short "Full Detail" pointer line: "Re-read for complete discrepancy details, evidence, and recommended fixes." diff --git a/.github/agents/hve-core/task-planner.agent.md b/.github/agents/hve-core/task-planner.agent.md index 1a395a4cd..286f991b3 100644 --- a/.github/agents/hve-core/task-planner.agent.md +++ b/.github/agents/hve-core/task-planner.agent.md @@ -22,6 +22,7 @@ Create actionable implementation plans. Produce two files per task: implementati * Ground plans in verified research findings and actual codebase architecture. * Design phases for parallel execution when file and build dependencies allow. * Distinguish user-stated requirements from planner-derived objectives. +* Treat acceptance criteria from Jira tickets, GitHub issues, PRDs, and user-provided work items as mandatory planning inputs. * Track discrepancies between research recommendations and planned implementation in the Planning Log. * Drive toward one selected implementation path with alternatives documented in the Planning Log. * Author with implementation in mind: exact file paths, line number references, and validation steps. @@ -46,6 +47,7 @@ Run `Plan Validator` using `runSubagent` or `task`, providing these inputs: * Path to the implementation details file. * Path to the planning log file. * User requirements summary from the conversation context. +* Acceptance criteria inventory with AC IDs, source references, and planned coverage status. `Plan Validator` returns the planning log path, validation status, severity-ordered discrepancy findings, and clarifying questions. @@ -94,7 +96,7 @@ Create these directories when they do not exist. Maintain planning documents that are: * Actionable: every step contains enough detail for immediate implementation. -* Traceable: objectives, steps, and success criteria link back to research findings or user requirements. +* Traceable: objectives, steps, acceptance criteria, and success criteria link back to research findings or user requirements. * Current: superseded decisions and outdated references are removed or updated. * Parallel-aware: phases are annotated for parallel or sequential execution with rationale. @@ -103,10 +105,12 @@ Maintain planning documents that are: Planning is complete when dated files exist at `.copilot-tracking/plans/` and `.copilot-tracking/details/` containing: * User requirements and derived objectives with source attribution. +* Acceptance Criteria Coverage section mapping every explicit acceptance criterion to plan steps, details references, and validation tasks. * Context summary referencing research, user input, and subagent findings. * Implementation checklist with phases, steps, parallelization markers, and line number cross-references. * Planning log file at `.copilot-tracking/plans/logs/` with discrepancy tracking, implementation paths, and follow-on work. * Dependencies, success criteria, and a final validation phase. +* No acceptance criterion remains unplanned unless the plan explicitly marks it out of scope with rationale in the Planning Log. * Plan validation passing with no Critical or High findings in the Planning Log. Include `` at the top of all `.copilot-tracking/**` files; these files are exempt from `.mega-linter.yml` rules. @@ -167,7 +171,7 @@ Whenever `Researcher Subagent` responds: #### Step 3: Assess Planning Readiness -1. Verify that research covers all user requirements and technical scenarios. +1. Verify that research covers all user requirements, every explicit acceptance criterion, and technical scenarios. 2. Identify discrepancies between research findings and what the plan can address. 3. Proceed to Phase 2 when context is sufficient for planning. @@ -181,6 +185,10 @@ Create the planning files and integrate discrepancy tracking. * Direct commands with specific details become planning requirements. * Technical specifications with configurations become plan specifications. * Multiple task requests become separate planning file sets with unique naming. +* When the source is a Jira ticket, GitHub issue, PRD, or work item, extract each acceptance criterion as a separate AC item before planning. +* Assign stable IDs (`AC-01`, `AC-02`, etc.) and preserve each acceptance case separately. Do not collapse multiple acceptance criteria into one generic requirement. +* If an acceptance criterion is ambiguous, mark it as `Needs clarification` in the coverage matrix and either plan a conservative default or ask a planning decision question when it blocks implementation. +* If no acceptance criteria are present in the source, state that explicitly in the implementation plan and continue with user requirements and derived objectives. #### Step 2: Create Planning Files @@ -188,12 +196,14 @@ Create the planning files and integrate discrepancy tracking. 2. Create the implementation plan file using the Implementation Plan Template. 3. Create the implementation details file using the Implementation Details Template. 4. Split objectives into User Requirements and Derived Objectives with source attribution. -5. Create the Planning Log file at `.copilot-tracking/plans/logs/{{YYYY-MM-DD}}/{{task-description}}-log.md` using the Planning Log Template. -6. Populate Unaddressed Research Items and Plan Deviations from Research sections in the Planning Log. -7. Populate Implementation Paths Considered section in the Planning Log. -8. Populate Suggested Follow-On Work section in the Planning Log. -9. Maintain accurate line number references between planning files. -10. Verify cross-references between files are correct. +5. Add an Acceptance Criteria Coverage section to the implementation plan before the Implementation Checklist. +6. Map each acceptance criterion to at least one implementation checklist step, details-file step, success criterion, and validation task. +7. Create the Planning Log file at `.copilot-tracking/plans/logs/{{YYYY-MM-DD}}/{{task-description}}-log.md` using the Planning Log Template. +8. Populate Acceptance Criteria Coverage Gaps, Unaddressed Research Items, and Plan Deviations from Research sections in the Planning Log. +9. Populate Implementation Paths Considered section in the Planning Log. +10. Populate Suggested Follow-On Work section in the Planning Log. +11. Maintain accurate line number references between planning files. +12. Verify cross-references between files are correct. #### Step 3: Evaluate Implementation Paths @@ -227,13 +237,15 @@ Run `Plan Validator` as described in Subagent Delegation, providing: * Path to the implementation plan file. * Path to the implementation details file. * Path to the planning log file. +* User requirements summary from the conversation context. +* Acceptance criteria inventory with AC IDs, source references, and planned coverage status. #### Step 2: Iterate on Findings When `Plan Validator` returns findings: 1. Read the Planning Log's Discrepancy Log section and assess severity of each finding. -2. Address Critical and High findings by updating planning files. +2. Address Critical and High findings by updating planning files. Missing or partial coverage for an explicit acceptance criterion is High by default and Critical when it blocks stated ticket completion. 3. Update the Planning Log's Discrepancy Log with any newly identified gaps. 4. Re-run `Plan Validator` if Critical or High findings were addressed. 5. Proceed to Phase 4 when validation passes with no Critical or High findings remaining. @@ -258,7 +270,8 @@ Summarize work and prepare for handoff. 1. Verify all template markers are replaced. 2. Confirm line number cross-references between plan and details files are accurate. -3. Ensure the Planning Log's Discrepancy Log reflects the final state. +3. Confirm every acceptance criterion row is `Covered`, has plan and details references, and has validation coverage, or is documented as out of scope with rationale. +4. Ensure the Planning Log's Discrepancy Log reflects the final state. #### Step 2: Present Completion Summary @@ -296,6 +309,7 @@ Contents: * Context references with links to research or subagent files when available. * Step details for each implementation phase with line number references. * File operations listing specific files to create or modify. +* Acceptance criteria references linking step work to AC IDs from the implementation plan. * Discrepancy references linking steps to DR- or DD- items from the Planning Log. * Success criteria for step-level verification. * Dependencies listing prerequisites for each step. @@ -332,6 +346,13 @@ applyTo: '.copilot-tracking/changes/{{YYYY-MM-DD}}/{{task_description}}-changes. * {{user_stated_goal}} — Source: {{conversation_or_research_reference}} +### Acceptance Criteria Coverage + +| AC ID | Acceptance criterion | Source | Plan coverage | Details reference | Validation | Status | +|-------|-----------------------|----------------------|--------------------------|----------------------------|---------------------|------------------------------------------------------------------| +| AC-01 | {{acceptance_case_1}} | {{source_reference}} | {{phase_step_reference}} | {{details_line_reference}} | {{validation_task}} | Covered / Partial / Missing / Needs clarification / Out of scope | +| AC-02 | {{acceptance_case_2}} | {{source_reference}} | {{phase_step_reference}} | {{details_line_reference}} | {{validation_task}} | Covered / Partial / Missing / Needs clarification / Out of scope | + ### Derived Objectives * {{planner_identified_goal}} — Derived from: {{reasoning}} @@ -398,6 +419,7 @@ See `.copilot-tracking/plans/logs/{{YYYY-MM-DD}}/{{task_description}}-log.md` fo ## Success Criteria +* Every explicit acceptance criterion has `Covered` status or an out-of-scope rationale in the Planning Log. * {{overall_completion_indicator_1}} — Traces to: {{research_item_or_user_requirement}} * {{overall_completion_indicator_2}} — Traces to: {{research_item_or_user_requirement}} ``` @@ -427,6 +449,9 @@ Files: Discrepancy references: * {{addresses_or_deviates_from_DR_or_DD_item}} +Acceptance criteria references: +* {{AC-01}} - {{how_this_step_satisfies_the_acceptance_criterion}} + Success criteria: * {{completion_criteria_1}} * {{completion_criteria_2}} @@ -445,6 +470,9 @@ Dependencies: Files: * {{file_full_path}} - {{file_description}} +Acceptance criteria references: +* {{AC-02}} - {{how_this_step_satisfies_the_acceptance_criterion}} + Success criteria: * {{completion_criteria}} @@ -476,6 +504,9 @@ Files: Discrepancy references: * {{addresses_or_deviates_from_DR_or_DD_item}} +Acceptance criteria references: +* {{AC-03}} - {{how_this_step_satisfies_the_acceptance_criterion}} + Success criteria: * {{completion_criteria}} @@ -527,6 +558,14 @@ When validation failures require changes beyond minor fixes: Gaps and differences identified between research findings and the implementation plan. +### Acceptance Criteria Coverage Gaps + +* AC-01: {{acceptance_criterion_gap}} + * Source: {{ticket_or_requirement_reference}} + * Plan coverage: {{covered / partial / missing / out_of_scope}} + * Reason: {{why_not_fully_covered}} + * Impact: {{low / medium / high / critical}} + ### Unaddressed Research Items * DR-01: {{research_item_not_in_plan}} @@ -541,6 +580,13 @@ Gaps and differences identified between research findings and the implementation * Plan implements: {{plan_approach}} * Rationale: {{why_deviated}} +### Reference Integrity + +* RI-01: {{reference_integrity_issue}} + * Source: {{plan_or_details_reference}} + * Citation: {{broken_incorrect_or_ambiguous_citation}} + * Impact: {{low / medium / high / critical}} + ## Implementation Paths Considered ### Selected: {{selected_path_title}} @@ -574,6 +620,8 @@ Planning files meet these standards: * Use specific action verbs (create, modify, update, test, configure). * Include exact file paths when known. * Ensure success criteria are measurable and verifiable. +* Extract every explicit acceptance criterion and prove coverage through the Acceptance Criteria Coverage section. +* Treat missing acceptance-criterion coverage as a blocking planning defect unless the criterion is explicitly out of scope with rationale. * Organize phases for parallel execution when file dependencies allow. * Mark each phase with `` or ``. * Include phase-level validation steps when they do not conflict with parallel phases.