@cregis-dev/cckit 0.2.0

package/templates/bmad/tea/workflows/testarch/trace/steps-c/step-04-analyze-gaps.md

@@ -0,0 +1,330 @@
+---
+name: 'step-04-analyze-gaps'
+description: 'Complete Phase 1: Generate coverage matrix with gap analysis'
+nextStepFile: './step-05-gate-decision.md'
+outputFile: '{test_artifacts}/traceability-report.md'
+tempOutputFile: '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json'
+---
+
+# Step 4: Complete Phase 1 - Coverage Matrix Generation
+
+## STEP GOAL
+
+**Phase 1 Final Step:** Analyze coverage gaps (including endpoint/auth/error-path blind spots), generate recommendations, and output complete coverage matrix to temp file for Phase 2 (gate decision).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Output coverage matrix to temp file
+- ❌ Do NOT make gate decision (that's Phase 2 - Step 5)
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: requirements from Step 1, tests from Step 2, traceability matrix from Step 3
+- Focus: gap analysis and matrix completion
+- Limits: do not make gate decision (Phase 2 responsibility)
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Gap Analysis
+
+**Identify uncovered requirements:**
+
+```javascript
+const uncoveredRequirements = traceabilityMatrix.filter((req) => req.coverage === 'NONE');
+const partialCoverage = traceabilityMatrix.filter((req) => req.coverage === 'PARTIAL');
+const unitOnlyCoverage = traceabilityMatrix.filter((req) => req.coverage === 'UNIT-ONLY');
+```
+
+**Prioritize gaps by risk:**
+
+```javascript
+const criticalGaps = uncoveredRequirements.filter((req) => req.priority === 'P0');
+const highGaps = uncoveredRequirements.filter((req) => req.priority === 'P1');
+const mediumGaps = uncoveredRequirements.filter((req) => req.priority === 'P2');
+const lowGaps = uncoveredRequirements.filter((req) => req.priority === 'P3');
+```
+
+---
+
+### 2. Coverage Heuristics Checks
+
+Use the heuristics inventory from Step 2 and mapped criteria from Step 3 to flag common coverage blind spots:
+
+```javascript
+const endpointCoverageGaps = coverageHeuristics?.endpoints_without_tests || [];
+const authCoverageGaps = coverageHeuristics?.auth_missing_negative_paths || [];
+const errorPathGaps = coverageHeuristics?.criteria_happy_path_only || [];
+
+const heuristicGapCounts = {
+  endpoints_without_tests: endpointCoverageGaps.length,
+  auth_missing_negative_paths: authCoverageGaps.length,
+  happy_path_only_criteria: errorPathGaps.length,
+};
+```
+
+Heuristics are advisory but must influence gap severity and recommendations, especially for P0/P1 criteria.
+
+---
+
+### 3. Generate Recommendations
+
+**Based on gap analysis:**
+
+```javascript
+const recommendations = [];
+
+// Critical gaps (P0)
+if (criticalGaps.length > 0) {
+  recommendations.push({
+    priority: 'URGENT',
+    action: `Run /bmad:tea:atdd for ${criticalGaps.length} P0 requirements`,
+    requirements: criticalGaps.map((r) => r.id),
+  });
+}
+
+// High priority gaps (P1)
+if (highGaps.length > 0) {
+  recommendations.push({
+    priority: 'HIGH',
+    action: `Run /bmad:tea:automate to expand coverage for ${highGaps.length} P1 requirements`,
+    requirements: highGaps.map((r) => r.id),
+  });
+}
+
+// Partial coverage
+if (partialCoverage.length > 0) {
+  recommendations.push({
+    priority: 'MEDIUM',
+    action: `Complete coverage for ${partialCoverage.length} partially covered requirements`,
+    requirements: partialCoverage.map((r) => r.id),
+  });
+}
+
+if (endpointCoverageGaps.length > 0) {
+  recommendations.push({
+    priority: 'HIGH',
+    action: `Add API tests for ${endpointCoverageGaps.length} uncovered endpoint(s)`,
+    requirements: endpointCoverageGaps.map((r) => r.id || r.endpoint || 'unknown'),
+  });
+}
+
+if (authCoverageGaps.length > 0) {
+  recommendations.push({
+    priority: 'HIGH',
+    action: `Add negative-path auth/authz tests for ${authCoverageGaps.length} requirement(s)`,
+    requirements: authCoverageGaps.map((r) => r.id || 'unknown'),
+  });
+}
+
+if (errorPathGaps.length > 0) {
+  recommendations.push({
+    priority: 'MEDIUM',
+    action: `Add error/edge scenario tests for ${errorPathGaps.length} happy-path-only criterion/criteria`,
+    requirements: errorPathGaps.map((r) => r.id || 'unknown'),
+  });
+}
+
+// Quality issues
+recommendations.push({
+  priority: 'LOW',
+  action: 'Run /bmad:tea:test-review to assess test quality',
+  requirements: [],
+});
+```
+
+---
+
+### 4. Calculate Coverage Statistics
+
+```javascript
+const totalRequirements = traceabilityMatrix.length;
+const coveredRequirements = traceabilityMatrix.filter((r) => r.coverage === 'FULL' || r.coverage === 'PARTIAL').length;
+const fullyCovered = traceabilityMatrix.filter((r) => r.coverage === 'FULL').length;
+
+const safePct = (covered, total) => (total > 0 ? Math.round((covered / total) * 100) : 100);
+const coveragePercentage = safePct(fullyCovered, totalRequirements);
+
+// Priority-specific coverage
+const p0Total = traceabilityMatrix.filter((r) => r.priority === 'P0').length;
+const p0Covered = traceabilityMatrix.filter((r) => r.priority === 'P0' && r.coverage === 'FULL').length;
+const p1Total = traceabilityMatrix.filter((r) => r.priority === 'P1').length;
+const p1Covered = traceabilityMatrix.filter((r) => r.priority === 'P1' && r.coverage === 'FULL').length;
+const p2Total = traceabilityMatrix.filter((r) => r.priority === 'P2').length;
+const p2Covered = traceabilityMatrix.filter((r) => r.priority === 'P2' && r.coverage === 'FULL').length;
+const p3Total = traceabilityMatrix.filter((r) => r.priority === 'P3').length;
+const p3Covered = traceabilityMatrix.filter((r) => r.priority === 'P3' && r.coverage === 'FULL').length;
+
+const p0CoveragePercentage = safePct(p0Covered, p0Total);
+const p1CoveragePercentage = safePct(p1Covered, p1Total);
+const p2CoveragePercentage = safePct(p2Covered, p2Total);
+const p3CoveragePercentage = safePct(p3Covered, p3Total);
+```
+
+---
+
+### 5. Generate Complete Coverage Matrix
+
+**Compile all Phase 1 outputs:**
+
+```javascript
+const coverageMatrix = {
+  phase: 'PHASE_1_COMPLETE',
+  generated_at: new Date().toISOString(),
+
+  requirements: traceabilityMatrix, // Full matrix from Step 3
+
+  coverage_statistics: {
+    total_requirements: totalRequirements,
+    fully_covered: fullyCovered,
+    partially_covered: partialCoverage.length,
+    uncovered: uncoveredRequirements.length,
+    overall_coverage_percentage: coveragePercentage,
+
+    priority_breakdown: {
+      P0: { total: p0Total, covered: p0Covered, percentage: p0CoveragePercentage },
+      P1: { total: p1Total, covered: p1Covered, percentage: p1CoveragePercentage },
+      P2: { total: p2Total, covered: p2Covered, percentage: p2CoveragePercentage },
+      P3: { total: p3Total, covered: p3Covered, percentage: p3CoveragePercentage },
+    },
+  },
+
+  gap_analysis: {
+    critical_gaps: criticalGaps,
+    high_gaps: highGaps,
+    medium_gaps: mediumGaps,
+    low_gaps: lowGaps,
+    partial_coverage_items: partialCoverage,
+    unit_only_items: unitOnlyCoverage,
+  },
+
+  coverage_heuristics: {
+    endpoint_gaps: endpointCoverageGaps,
+    auth_negative_path_gaps: authCoverageGaps,
+    happy_path_only_gaps: errorPathGaps,
+    counts: heuristicGapCounts,
+  },
+
+  recommendations: recommendations,
+};
+```
+
+---
+
+### 6. Output Coverage Matrix to Temp File
+
+**Write to temp file for Phase 2:**
+
+```javascript
+const outputPath = '{tempOutputFile}';
+fs.writeFileSync(outputPath, JSON.stringify(coverageMatrix, null, 2), 'utf8');
+
+console.log(`✅ Phase 1 Complete: Coverage matrix saved to ${outputPath}`);
+```
+
+---
+
+### 7. Display Phase 1 Summary
+
+```
+✅ Phase 1 Complete: Coverage Matrix Generated
+
+📊 Coverage Statistics:
+- Total Requirements: {totalRequirements}
+- Fully Covered: {fullyCovered} ({coveragePercentage}%)
+- Partially Covered: {partialCoverage.length}
+- Uncovered: {uncoveredRequirements.length}
+
+🎯 Priority Coverage:
+- P0: {p0Covered}/{p0Total} ({p0CoveragePercentage}%)
+- P1: {p1Covered}/{p1Total} ({p1CoveragePercentage}%)
+- P2: {p2Covered}/{p2Total} ({p2CoveragePercentage}%)
+- P3: {p3Covered}/{p3Total} ({p3CoveragePercentage}%)
+
+⚠️ Gaps Identified:
+- Critical (P0): {criticalGaps.length}
+- High (P1): {highGaps.length}
+- Medium (P2): {mediumGaps.length}
+- Low (P3): {lowGaps.length}
+
+🔍 Coverage Heuristics:
+- Endpoints without tests: {endpointCoverageGaps.length}
+- Auth negative-path gaps: {authCoverageGaps.length}
+- Happy-path-only criteria: {errorPathGaps.length}
+
+📝 Recommendations: {recommendations.length}
+
+🔄 Phase 2: Gate decision (next step)
+```
+
+---
+
+## EXIT CONDITION
+
+**PHASE 1 COMPLETE when:**
+
+- ✅ Gap analysis complete
+- ✅ Recommendations generated
+- ✅ Coverage statistics calculated
+- ✅ Coverage matrix saved to temp file
+- ✅ Summary displayed
+
+**Proceed to Phase 2 (Step 5: Gate Decision)**
+
+---
+
+### 8. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it using the workflow template (if available) with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-04-analyze-gaps']
+  lastStep: 'step-04-analyze-gaps'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-04-analyze-gaps'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-04-analyze-gaps'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section of the document.
+
+Load next step: `{nextStepFile}`
+
+---
+
+## 🚨 PHASE 1 SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- Coverage matrix complete and accurate
+- All gaps identified and prioritized
+- Recommendations actionable
+- Temp file output valid JSON
+
+### ❌ FAILURE:
+
+- Coverage matrix incomplete
+- Gap analysis missing
+- Invalid JSON output
+
+**Master Rule:** Phase 1 MUST output complete coverage matrix to temp file before Phase 2 can proceed.

package/templates/bmad/tea/workflows/testarch/trace/steps-c/step-05-gate-decision.md

@@ -0,0 +1,266 @@
+---
+name: 'step-05-gate-decision'
+description: 'Phase 2: Apply gate decision logic and generate outputs'
+outputFile: '{test_artifacts}/traceability-report.md'
+---
+
+# Step 5: Phase 2 - Gate Decision
+
+## STEP GOAL
+
+**Phase 2:** Read coverage matrix from Phase 1, apply deterministic gate decision logic, and generate traceability report.
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Read coverage matrix from Phase 1 temp file
+- ✅ Apply gate decision logic
+- ❌ Do NOT regenerate coverage matrix (use Phase 1 output)
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 This is the FINAL step
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Coverage matrix from Phase 1 temp file
+- Focus: gate decision logic only
+- Dependencies: Phase 1 complete (coverage matrix exists)
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Read Phase 1 Coverage Matrix
+
+```javascript
+const matrixPath = '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json';
+const coverageMatrix = JSON.parse(fs.readFileSync(matrixPath, 'utf8'));
+
+console.log('✅ Phase 1 coverage matrix loaded');
+```
+
+**Verify Phase 1 complete:**
+
+```javascript
+if (coverageMatrix.phase !== 'PHASE_1_COMPLETE') {
+  throw new Error('Phase 1 not complete - cannot proceed to gate decision');
+}
+```
+
+---
+
+### 2. Apply Gate Decision Logic
+
+**Decision Tree:**
+
+```javascript
+const stats = coverageMatrix.coverage_statistics;
+const p0Coverage = stats.priority_breakdown.P0.percentage;
+const p1Coverage = stats.priority_breakdown.P1.percentage;
+const hasP1Requirements = (stats.priority_breakdown.P1.total || 0) > 0;
+const effectiveP1Coverage = hasP1Requirements ? p1Coverage : 100;
+const overallCoverage = stats.overall_coverage_percentage;
+const criticalGaps = coverageMatrix.gap_analysis.critical_gaps.length;
+
+let gateDecision;
+let rationale;
+
+// Rule 1: P0 coverage must be 100%
+if (p0Coverage < 100) {
+  gateDecision = 'FAIL';
+  rationale = `P0 coverage is ${p0Coverage}% (required: 100%). ${criticalGaps} critical requirements uncovered.`;
+}
+// Rule 2: Overall coverage must be >= 80%
+else if (overallCoverage < 80) {
+  gateDecision = 'FAIL';
+  rationale = `Overall coverage is ${overallCoverage}% (minimum: 80%). Significant gaps exist.`;
+}
+// Rule 3: P1 coverage < 80% → FAIL
+else if (effectiveP1Coverage < 80) {
+  gateDecision = 'FAIL';
+  rationale = hasP1Requirements
+    ? `P1 coverage is ${effectiveP1Coverage}% (minimum: 80%). High-priority gaps must be addressed.`
+    : `P1 requirements are not present; continuing with remaining gate criteria.`;
+}
+// Rule 4: P1 coverage >= 90% and overall >= 80% with P0 at 100% → PASS
+else if (effectiveP1Coverage >= 90) {
+  gateDecision = 'PASS';
+  rationale = hasP1Requirements
+    ? `P0 coverage is 100%, P1 coverage is ${effectiveP1Coverage}% (target: 90%), and overall coverage is ${overallCoverage}% (minimum: 80%).`
+    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%). No P1 requirements detected.`;
+}
+// Rule 5: P1 coverage 80-89% with P0 at 100% and overall >= 80% → CONCERNS
+else if (effectiveP1Coverage >= 80) {
+  gateDecision = 'CONCERNS';
+  rationale = hasP1Requirements
+    ? `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but P1 coverage is ${effectiveP1Coverage}% (target: 90%).`
+    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but additional non-P1 gaps need mitigation.`;
+}
+
+// Rule 6: Manual waiver option
+const manualWaiver = false; // Can be set via config or user input
+if (manualWaiver) {
+  gateDecision = 'WAIVED';
+  rationale += ' Manual waiver applied by stakeholder.';
+}
+```
+
+---
+
+### 3. Generate Gate Report
+
+```javascript
+const gateReport = {
+  decision: gateDecision,
+  rationale: rationale,
+  decision_date: new Date().toISOString(),
+
+  coverage_matrix: coverageMatrix,
+
+  gate_criteria: {
+    p0_coverage_required: '100%',
+    p0_coverage_actual: `${p0Coverage}%`,
+    p0_status: p0Coverage === 100 ? 'MET' : 'NOT MET',
+
+    p1_coverage_target_pass: '90%',
+    p1_coverage_minimum: '80%',
+    p1_coverage_actual: `${effectiveP1Coverage}%`,
+    p1_status: effectiveP1Coverage >= 90 ? 'MET' : effectiveP1Coverage >= 80 ? 'PARTIAL' : 'NOT MET',
+
+    overall_coverage_minimum: '80%',
+    overall_coverage_actual: `${overallCoverage}%`,
+    overall_status: overallCoverage >= 80 ? 'MET' : 'NOT MET',
+  },
+
+  uncovered_requirements: coverageMatrix.gap_analysis.critical_gaps.concat(coverageMatrix.gap_analysis.high_gaps),
+
+  recommendations: coverageMatrix.recommendations,
+};
+```
+
+---
+
+### 4. Generate Traceability Report
+
+**Use trace-template.md to generate:**
+
+```markdown
+# Traceability Report
+
+## Gate Decision: {gateDecision}
+
+**Rationale:** {rationale}
+
+## Coverage Summary
+
+- Total Requirements: {totalRequirements}
+- Covered: {fullyCovered} ({coveragePercentage}%)
+- P0 Coverage: {p0CoveragePercentage}%
+
+## Traceability Matrix
+
+[Full matrix with requirement → test mappings]
+
+## Gaps & Recommendations
+
+[List of uncovered requirements with recommended actions]
+
+## Next Actions
+
+{recommendations}
+```
+
+**Save to:**
+
+```javascript
+fs.writeFileSync('{outputFile}', reportContent, 'utf8');
+```
+
+---
+
+### 5. Display Gate Decision
+
+```
+🚨 GATE DECISION: {gateDecision}
+
+📊 Coverage Analysis:
+- P0 Coverage: {p0Coverage}% (Required: 100%) → {p0_status}
+- P1 Coverage: {effectiveP1Coverage}% (PASS target: 90%, minimum: 80%) → {p1_status}
+- Overall Coverage: {overallCoverage}% (Minimum: 80%) → {overall_status}
+
+✅ Decision Rationale:
+{rationale}
+
+⚠️ Critical Gaps: {criticalGaps.length}
+
+📝 Recommended Actions:
+{list top 3 recommendations}
+
+📂 Full Report: {outputFile}
+
+{if FAIL}
+🚫 GATE: FAIL - Release BLOCKED until coverage improves
+{endif}
+
+{if CONCERNS}
+⚠️ GATE: CONCERNS - Proceed with caution, address gaps soon
+{endif}
+
+{if PASS}
+✅ GATE: PASS - Release approved, coverage meets standards
+{endif}
+```
+
+---
+
+### 6. Save Progress
+
+**Update the YAML frontmatter in `{outputFile}` to mark this final step complete.**
+
+Since step 4 (Generate Traceability Report) already wrote the report content to `{outputFile}`, do NOT overwrite it. Instead, update only the frontmatter at the top of the existing file:
+
+- Add `'step-05-gate-decision'` to `stepsCompleted` array (only if not already present)
+- Set `lastStep: 'step-05-gate-decision'`
+- Set `lastSaved: '{date}'`
+
+Then append the gate decision summary (from section 5 above) to the end of the existing report content.
+
+---
+
+## EXIT CONDITION
+
+**WORKFLOW COMPLETE when:**
+
+- ✅ Phase 1 coverage matrix read successfully
+- ✅ Gate decision logic applied
+- ✅ Traceability report generated
+- ✅ Gate decision displayed
+
+**Workflow terminates here.**
+
+---
+
+## 🚨 PHASE 2 SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- Coverage matrix read from Phase 1
+- Gate decision made with clear rationale
+- Report generated and saved
+- Decision communicated clearly
+
+### ❌ FAILURE:
+
+- Could not read Phase 1 matrix
+- Gate decision logic incorrect
+- Report missing or incomplete
+
+**Master Rule:** Gate decision MUST be deterministic based on clear criteria (P0 100%, P1 90/80, overall >=80).

package/templates/bmad/tea/workflows/testarch/trace/steps-e/step-01-assess.md

@@ -0,0 +1,65 @@
+---
+name: 'step-01-assess'
+description: 'Load an existing output for editing'
+nextStepFile: './step-02-apply-edit.md'
+---
+
+# Step 1: Assess Edit Target
+
+## STEP GOAL:
+
+Identify which output should be edited and load it.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Master Test Architect
+
+### Step-Specific Rules:
+
+- 🎯 Ask the user which output file to edit
+- 🚫 Do not edit until target is confirmed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+
+## CONTEXT BOUNDARIES:
+
+- Available context: existing outputs
+- Focus: select edit target
+- Limits: no edits yet
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Identify Target
+
+Ask the user to provide the output file path or select from known outputs.
+
+### 2. Load Target
+
+Read the provided output file in full.
+
+### 3. Confirm
+
+Confirm the target and proceed to edit.
+
+Load next step: `{nextStepFile}`
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Target identified and loaded
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without a confirmed target

package/templates/bmad/tea/workflows/testarch/trace/steps-e/step-02-apply-edit.md

@@ -0,0 +1,60 @@
+---
+name: 'step-02-apply-edit'
+description: 'Apply edits to the selected output'
+---
+
+# Step 2: Apply Edits
+
+## STEP GOAL:
+
+Apply the requested edits to the selected output and confirm changes.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Master Test Architect
+
+### Step-Specific Rules:
+
+- 🎯 Only apply edits explicitly requested by the user
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+
+## CONTEXT BOUNDARIES:
+
+- Available context: selected output and user changes
+- Focus: apply edits only
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Confirm Requested Changes
+
+Restate what will be changed and confirm.
+
+### 2. Apply Changes
+
+Update the output file accordingly.
+
+### 3. Report
+
+Summarize the edits applied.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Changes applied and confirmed
+
+### ❌ SYSTEM FAILURE:
+
+- Unconfirmed edits or missing update