@cregis-dev/cckit 0.2.0

package/templates/bmad/tea/workflows/testarch/test-review/steps-c/step-01b-resume.md

@@ -0,0 +1,104 @@
+---
+name: 'step-01b-resume'
+description: 'Resume interrupted workflow from last completed step'
+outputFile: '{test_artifacts}/test-review.md'
+---
+
+# Step 1b: Resume Workflow
+
+## STEP GOAL
+
+Resume an interrupted workflow by loading the existing output document, displaying progress, and routing to the next incomplete step.
+
+## MANDATORY EXECUTION RULES
+
+- Read the entire step file before acting
+- Speak in `{communication_language}`
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- Follow the MANDATORY SEQUENCE exactly
+- Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Output document with progress frontmatter
+- Focus: Load progress and route to next step
+- Limits: Do not re-execute completed steps
+- Dependencies: Output document must exist from a previous run
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Load Output Document
+
+Read `{outputFile}` and parse YAML frontmatter for:
+
+- `stepsCompleted` -- array of completed step names
+- `lastStep` -- last completed step name
+- `lastSaved` -- timestamp of last save
+
+**If `{outputFile}` does not exist**, display:
+
+"No previous progress found. There is no output document to resume from. Please use **[C] Create** to start a fresh workflow run."
+
+**THEN:** Halt. Do not proceed.
+
+---
+
+### 2. Display Progress Dashboard
+
+Display progress with checkmark/empty indicators:
+
+```
+Test Quality Review - Resume Progress:
+
+1. Load Context (step-01-load-context)              [completed/pending]
+2. Discover Tests (step-02-discover-tests)           [completed/pending]
+3. Quality Evaluation + Aggregate (step-03f-aggregate-scores) [completed/pending]
+4. Generate Report (step-04-generate-report)         [completed/pending]
+
+Last saved: {lastSaved}
+```
+
+---
+
+### 3. Route to Next Step
+
+Based on `lastStep`, load the next incomplete step:
+
+| lastStep                    | Next Step File                    |
+| --------------------------- | --------------------------------- |
+| `step-01-load-context`      | `./step-02-discover-tests.md`     |
+| `step-02-discover-tests`    | `./step-03-quality-evaluation.md` |
+| `step-03f-aggregate-scores` | `./step-04-generate-report.md`    |
+| `step-04-generate-report`   | **Workflow already complete.**    |
+
+**If `lastStep` is the final step** (`step-04-generate-report`), display: "All steps completed. Use **[C] Create** to start fresh, **[V] Validate** to review outputs, or **[E] Edit** to make revisions." Then halt.
+
+**If `lastStep` does not match any value above**, display: "Unknown progress state (`lastStep`: {lastStep}). Please use **[C] Create** to start fresh." Then halt.
+
+**Otherwise**, load the identified step file, read completely, and execute.
+
+The existing content in `{outputFile}` provides context from previously completed steps.
+
+---
+
+## SYSTEM SUCCESS/FAILURE METRICS
+
+### SUCCESS:
+
+- Output document loaded and parsed correctly
+- Progress dashboard displayed accurately
+- Routed to correct next step
+
+### FAILURE:
+
+- Not loading output document
+- Incorrect progress display
+- Routing to wrong step
+
+**Master Rule:** Resume MUST route to the exact next incomplete step. Never re-execute completed steps.

package/templates/bmad/tea/workflows/testarch/test-review/steps-c/step-02-discover-tests.md

@@ -0,0 +1,113 @@
+---
+name: 'step-02-discover-tests'
+description: 'Find and parse test files'
+nextStepFile: './step-03-quality-evaluation.md'
+outputFile: '{test_artifacts}/test-review.md'
+---
+
+# Step 2: Discover & Parse Tests
+
+## STEP GOAL
+
+Collect test files in scope and parse structure/metadata.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, loaded artifacts, and knowledge fragments
+- Focus: this step's goal only
+- Limits: do not execute future steps
+- Dependencies: prior steps' outputs (if any)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+## 1. Discover Test Files
+
+- **single**: use provided file path
+- **directory**: glob under `{test_dir}` or selected folder
+- **suite**: glob all tests in repo
+
+Halt if no tests are found.
+
+---
+
+## 2. Parse Metadata (per file)
+
+Collect:
+
+- File size and line count
+- Test framework detected
+- Describe/test block counts
+- Test IDs and priority markers
+- Imports, fixtures, factories, network interception
+- Waits/timeouts and control flow (if/try/catch)
+
+---
+
+## 3. Evidence Collection (if `tea_browser_automation` is `cli` or `auto`)
+
+> **Fallback:** If CLI is not installed, fall back to MCP (if available) or skip evidence collection.
+
+**CLI Evidence Collection:**
+All commands use the same named session to target the correct browser:
+
+1. `playwright-cli -s=tea-review open <target_url>`
+2. `playwright-cli -s=tea-review tracing-start`
+3. Execute the flow under review (using `-s=tea-review` on each command)
+4. `playwright-cli -s=tea-review tracing-stop` → saves trace.zip
+5. `playwright-cli -s=tea-review screenshot --filename={test_artifacts}/review-evidence.png`
+6. `playwright-cli -s=tea-review network` → capture network request log
+7. `playwright-cli -s=tea-review close`
+
+> **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-review close`. Do NOT use `close-all` — it kills every session on the machine and breaks parallel execution.
+
+---
+
+## 4. 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-02-discover-tests']
+  lastStep: 'step-02-discover-tests'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-02-discover-tests'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-02-discover-tests'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section of the document.
+
+Load next step: `{nextStepFile}`
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Step completed in full with required outputs
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped sequence steps or missing outputs
+  **Master Rule:** Skipping steps is FORBIDDEN.

package/templates/bmad/tea/workflows/testarch/test-review/steps-c/step-03-quality-evaluation.md

@@ -0,0 +1,173 @@
+---
+name: 'step-03-quality-evaluation'
+description: 'Orchestrate parallel quality dimension checks (4 subprocesses)'
+nextStepFile: './step-03f-aggregate-scores.md'
+---
+
+# Step 3: Orchestrate Parallel Quality Evaluation
+
+## STEP GOAL
+
+Launch 4 parallel subprocesses to evaluate test quality dimensions:
+
+- Determinism
+- Isolation
+- Maintainability
+- Performance
+
+Coverage is intentionally excluded from this workflow and handled by `trace`.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Launch four subprocesses in PARALLEL
+- ✅ Wait for all subprocesses to complete
+- ❌ Do NOT evaluate quality sequentially (use subprocesses)
+- ❌ Do NOT proceed until all subprocesses finish
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Wait for subprocess outputs
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: test files from Step 2, knowledge fragments
+- Focus: subprocess orchestration only
+- Limits: do not evaluate quality directly (delegate to subprocesses)
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Prepare Subprocess Inputs
+
+**Generate unique timestamp:**
+
+```javascript
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+```
+
+**Prepare context for all subprocesses:**
+
+```javascript
+const subprocessContext = {
+  test_files: /* from Step 2 */,
+  knowledge_fragments_loaded: ['test-quality'],
+  timestamp: timestamp
+};
+```
+
+---
+
+### 2. Launch 4 Parallel Quality Subprocesses
+
+**Subprocess A: Determinism**
+
+- File: `./step-03a-subprocess-determinism.md`
+- Output: `/tmp/tea-test-review-determinism-${timestamp}.json`
+- Status: Running in parallel... ⟳
+
+**Subprocess B: Isolation**
+
+- File: `./step-03b-subprocess-isolation.md`
+- Output: `/tmp/tea-test-review-isolation-${timestamp}.json`
+- Status: Running in parallel... ⟳
+
+**Subprocess C: Maintainability**
+
+- File: `./step-03c-subprocess-maintainability.md`
+- Output: `/tmp/tea-test-review-maintainability-${timestamp}.json`
+- Status: Running in parallel... ⟳
+
+**Subprocess D: Performance**
+
+- File: `./step-03e-subprocess-performance.md`
+- Output: `/tmp/tea-test-review-performance-${timestamp}.json`
+- Status: Running in parallel... ⟳
+
+---
+
+### 3. Wait for All Subprocesses
+
+```
+⏳ Waiting for 4 quality subprocesses to complete...
+✅ All 4 quality subprocesses completed successfully!
+```
+
+---
+
+### 4. Verify All Outputs Exist
+
+```javascript
+const outputs = ['determinism', 'isolation', 'maintainability', 'performance'].map(
+  (dim) => `/tmp/tea-test-review-${dim}-${timestamp}.json`,
+);
+
+outputs.forEach((output) => {
+  if (!fs.existsSync(output)) {
+    throw new Error(`Subprocess output missing: ${output}`);
+  }
+});
+```
+
+---
+
+### 5. Performance Report
+
+```
+🚀 Performance Report:
+- Execution Mode: PARALLEL (4 subprocesses)
+- Total Elapsed: ~max(all subprocesses) minutes
+- Sequential Would Take: ~sum(all subprocesses) minutes
+- Performance Gain: ~60-70% faster!
+```
+
+---
+
+### 6. Proceed to Aggregation
+
+Pass the same `timestamp` value to Step 3F (do not regenerate it). Step 3F must read the exact temp files written in this step.
+
+Load next step: `{nextStepFile}`
+
+The aggregation step (3F) will:
+
+- Read all 4 subprocess outputs
+- Calculate weighted overall score (0-100)
+- Aggregate violations by severity
+- Generate review report with top suggestions
+
+---
+
+## EXIT CONDITION
+
+Proceed to Step 3F when:
+
+- ✅ All 4 subprocesses completed successfully
+- ✅ All output files exist and are valid JSON
+- ✅ Performance metrics displayed
+
+**Do NOT proceed if any subprocess failed.**
+
+---
+
+## 🚨 SYSTEM SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All 4 subprocesses launched and completed
+- Output files generated and valid
+- Parallel execution achieved ~60% performance gain
+
+### ❌ FAILURE:
+
+- One or more subprocesses failed
+- Output files missing or invalid
+- Sequential evaluation instead of parallel
+
+**Master Rule:** Parallel subprocess execution is MANDATORY for performance.

package/templates/bmad/tea/workflows/testarch/test-review/steps-c/step-03a-subprocess-determinism.md

@@ -0,0 +1,214 @@
+---
+name: 'step-03a-subprocess-determinism'
+description: 'Subprocess: Check test determinism (no random/time dependencies)'
+subprocess: true
+outputFile: '/tmp/tea-test-review-determinism-{{timestamp}}.json'
+---
+
+# Subprocess 3A: Determinism Quality Check
+
+## SUBPROCESS CONTEXT
+
+This is an **isolated subprocess** running in parallel with other quality dimension checks.
+
+**What you have from parent workflow:**
+
+- Test files discovered in Step 2
+- Knowledge fragment: test-quality (determinism criteria)
+- Config: test framework
+
+**Your task:** Analyze test files for DETERMINISM violations only.
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subprocess file before acting
+- ✅ Check DETERMINISM only (not other quality dimensions)
+- ✅ Output structured JSON to temp file
+- ❌ Do NOT check isolation, maintainability, coverage, or performance (other subprocesses)
+- ❌ Do NOT modify test files (read-only analysis)
+- ❌ Do NOT run tests (just analyze code)
+
+---
+
+## SUBPROCESS TASK
+
+### 1. Identify Determinism Violations
+
+**Scan test files for non-deterministic patterns:**
+
+**HIGH SEVERITY Violations**:
+
+- `Math.random()` - Random number generation
+- `Date.now()` or `new Date()` without mocking
+- `setTimeout` / `setInterval` without proper waits
+- External API calls without mocking
+- File system operations on random paths
+- Database queries with non-deterministic ordering
+
+**MEDIUM SEVERITY Violations**:
+
+- `page.waitForTimeout(N)` - Hard waits instead of conditions
+- Flaky selectors (CSS classes that may change)
+- Race conditions (missing proper synchronization)
+- Test order dependencies (test A must run before test B)
+
+**LOW SEVERITY Violations**:
+
+- Missing test isolation (shared state between tests)
+- Console timestamps without fixed timezone
+
+### 2. Analyze Each Test File
+
+For each test file from Step 2:
+
+```javascript
+const violations = [];
+
+// Check for Math.random()
+if (testFileContent.includes('Math.random()')) {
+  violations.push({
+    file: testFile,
+    line: findLineNumber('Math.random()'),
+    severity: 'HIGH',
+    category: 'random-generation',
+    description: 'Test uses Math.random() - non-deterministic',
+    suggestion: 'Use faker.seed(12345) for deterministic random data',
+  });
+}
+
+// Check for Date.now()
+if (testFileContent.includes('Date.now()') || testFileContent.includes('new Date()')) {
+  violations.push({
+    file: testFile,
+    line: findLineNumber('Date.now()'),
+    severity: 'HIGH',
+    category: 'time-dependency',
+    description: 'Test uses Date.now() or new Date() without mocking',
+    suggestion: 'Mock system time with test.useFakeTimers() or use fixed timestamps',
+  });
+}
+
+// Check for hard waits
+if (testFileContent.includes('waitForTimeout')) {
+  violations.push({
+    file: testFile,
+    line: findLineNumber('waitForTimeout'),
+    severity: 'MEDIUM',
+    category: 'hard-wait',
+    description: 'Test uses waitForTimeout - creates flakiness',
+    suggestion: 'Replace with expect(locator).toBeVisible() or waitForResponse',
+  });
+}
+
+// ... check other patterns
+```
+
+### 3. Calculate Determinism Score
+
+**Scoring Logic**:
+
+```javascript
+const totalChecks = testFiles.length * checksPerFile;
+const failedChecks = violations.length;
+const passedChecks = totalChecks - failedChecks;
+
+// Weight violations by severity
+const severityWeights = { HIGH: 10, MEDIUM: 5, LOW: 2 };
+const totalPenalty = violations.reduce((sum, v) => sum + severityWeights[v.severity], 0);
+
+// Score: 100 - (penalty points)
+const score = Math.max(0, 100 - totalPenalty);
+```
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-test-review-determinism-{{timestamp}}.json`
+
+```json
+{
+  "dimension": "determinism",
+  "score": 85,
+  "max_score": 100,
+  "grade": "B",
+  "violations": [
+    {
+      "file": "tests/api/user.spec.ts",
+      "line": 42,
+      "severity": "HIGH",
+      "category": "random-generation",
+      "description": "Test uses Math.random() - non-deterministic",
+      "suggestion": "Use faker.seed(12345) for deterministic random data",
+      "code_snippet": "const userId = Math.random() * 1000;"
+    },
+    {
+      "file": "tests/e2e/checkout.spec.ts",
+      "line": 78,
+      "severity": "MEDIUM",
+      "category": "hard-wait",
+      "description": "Test uses waitForTimeout - creates flakiness",
+      "suggestion": "Replace with expect(locator).toBeVisible()",
+      "code_snippet": "await page.waitForTimeout(5000);"
+    }
+  ],
+  "passed_checks": 12,
+  "failed_checks": 3,
+  "total_checks": 15,
+  "violation_summary": {
+    "HIGH": 1,
+    "MEDIUM": 1,
+    "LOW": 1
+  },
+  "recommendations": [
+    "Use faker with fixed seed for all random data",
+    "Replace all waitForTimeout with conditional waits",
+    "Mock Date.now() in tests that use current time"
+  ],
+  "summary": "Tests are mostly deterministic with 3 violations (1 HIGH, 1 MEDIUM, 1 LOW)"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "dimension": "determinism",
+  "success": false,
+  "error": "Error message describing what went wrong"
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subprocess completes when:
+
+- ✅ All test files analyzed for determinism violations
+- ✅ Score calculated (0-100)
+- ✅ Violations categorized by severity
+- ✅ Recommendations generated
+- ✅ JSON output written to temp file
+
+**Subprocess terminates here.** Parent workflow will read output and aggregate with other quality dimensions.
+
+---
+
+## 🚨 SUBPROCESS SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All test files scanned for determinism violations
+- Score calculated with proper severity weighting
+- JSON output valid and complete
+- Only determinism checked (not other dimensions)
+
+### ❌ FAILURE:
+
+- Checked quality dimensions other than determinism
+- Invalid or missing JSON output
+- Score calculation incorrect
+- Modified test files (should be read-only)