maestro-flow 0.4.6 → 0.4.8

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -68,15 +68,17 @@ $maestro-ui-codify "src/styles" --output-dir .workflow/packages --overwrite -y
 ### tasks.csv (Master State)
 
 ```csv
-id,wave,title,description,agent_type,deps,status,findings,output_path,error
-"discover-1","1","Discover design files","Scan source directory, categorize files by type (CSS/SCSS/JS/TS/HTML), build file inventory with import relationships","discover","","","","",""
-"style-1","2","Extract visual design tokens","Extract color, typography, spacing, border, shadow tokens from source files. Output design-tokens.json","extract-style","discover-1","","","",""
-"anim-1","2","Extract animation tokens","Extract animation/transition declarations: keyframes, durations, easings, motion patterns. Output animation-tokens.json","extract-animation","discover-1","","","",""
-"layout-1","2","Extract layout patterns","Extract component layout patterns: grid/flex systems, responsive breakpoints, container patterns. Output layout-templates.json","extract-layout","discover-1","","","",""
-"package-1","3","Generate reference package","Copy token JSONs to package dir, generate preview.html + preview.css interactive showcase","package","style-1;anim-1;layout-1","","","",""
-"knowhow-1","4","Build knowledge assets","Read token JSONs, build knowhow-manifest.json, write knowhow files + spec entries, cleanup temp workspace","knowhow","package-1","","","",""
+id,wave,title,description,agent_type,deps
+"discover-1","1","Discover design files","Scan source directory, categorize files by type (CSS/SCSS/JS/TS/HTML), build file inventory with import relationships","discover",""
+"style-1","2","Extract visual design tokens","Extract color, typography, spacing, border, shadow tokens from source files. Output design-tokens.json","extract-style","discover-1"
+"anim-1","2","Extract animation tokens","Extract animation/transition declarations: keyframes, durations, easings, motion patterns. Output animation-tokens.json","extract-animation","discover-1"
+"layout-1","2","Extract layout patterns","Extract component layout patterns: grid/flex systems, responsive breakpoints, container patterns. Output layout-templates.json","extract-layout","discover-1"
+"package-1","3","Generate reference package","Copy token JSONs to package dir, generate preview.html + preview.css interactive showcase","package","style-1;anim-1;layout-1"
+"knowhow-1","4","Build knowledge assets","Read token JSONs, build knowhow-manifest.json, write knowhow files + spec entries, cleanup temp workspace","knowhow","package-1"
 ```
 
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns. Output columns are returned exclusively via output_schema.
+
 **Columns**:
 
 | Column | Phase | Description |
@@ -87,7 +89,7 @@ id,wave,title,description,agent_type,deps,status,findings,output_path,error
 | `description` | Input | Detailed instructions for this task |
 | `agent_type` | Input | Agent type: discover/extract-style/extract-animation/extract-layout/package/knowhow |
 | `deps` | Input | Semicolon-separated dependency task IDs |
-| `status` | Output | `pending` -> `completed` / `failed` |
+| `result_status` | Output | `completed` / `failed` (returned via output_schema) |
 | `findings` | Output | Key findings summary (max 500 chars) |
 | `output_path` | Output | Path to generated artifact |
 | `error` | Output | Error message if failed |
@@ -272,11 +274,11 @@ spawn_agents_on_csv({
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
 })
 ```
 
-Merge results into master `tasks.csv`, delete `wave-1.csv`.
+Merge wave-1-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `wave-1.csv` and `wave-1-results.csv`.
 
 #### Wave 2: Parallel Extraction (3 agents)
 
@@ -290,11 +292,11 @@ spawn_agents_on_csv({
   max_concurrency: 3,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
 })
 ```
 
-Merge results into master `tasks.csv`, delete `wave-2.csv`.
+Merge wave-2-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `wave-2.csv` and `wave-2-results.csv`.
 
 **Degradation**: If animation agent fails (W001), continue — animation is optional. If style or layout agent fails, warn but continue with available results.
 
@@ -310,11 +312,11 @@ spawn_agents_on_csv({
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-3-results.csv`,
-  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
 })
 ```
 
-Merge results into master `tasks.csv`, delete `wave-3.csv`.
+Merge wave-3-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `wave-3.csv` and `wave-3-results.csv`.
 
 #### Wave 4: Knowledge Assets (Barrier)
 
@@ -328,11 +330,11 @@ spawn_agents_on_csv({
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-4-results.csv`,
-  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
 })
 ```
 
-Merge results into master `tasks.csv`, delete `wave-4.csv`.
+Merge wave-4-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `wave-4.csv` and `wave-4-results.csv`.
 
 ### Step 5: Results & Completion
 

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -80,12 +80,12 @@ When `--yes` or `-y`: Auto-confirm rebuild (implies --force), skip all prompts.
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,doc_dimension,output_path,deps,context_from,wave,status,findings,error
-"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Output JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols.","components",".workflow/codebase/doc-index.json#components","","","1","","",""
-"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if .workflow/.spec/ exists. Output JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase.","features",".workflow/codebase/doc-index.json#features","","","1","","",""
-"3","Requirement Linker","If .workflow/.spec/ exists, scan SPEC-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Output JSON arrays for requirements and architecture_decisions.","requirements",".workflow/codebase/doc-index.json#requirements","","","1","","",""
-"4","Tech Registry Writer","For each component discovered, generate a markdown documentation file in .workflow/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Generate _index.md with component table. Output file count and paths.","tech-registry",".workflow/codebase/tech-registry/","","","1","","",""
-"5","Feature Map Writer","For each feature discovered, generate a markdown documentation file in .workflow/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Generate _index.md with feature table. Output file count and paths.","feature-maps",".workflow/codebase/feature-maps/","","","1","","",""
+id,title,description,doc_dimension,output_path,deps,context_from,wave
+"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Output JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols.","components",".workflow/codebase/doc-index.json#components","","","1"
+"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if .workflow/.spec/ exists. Output JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase.","features",".workflow/codebase/doc-index.json#features","","","1"
+"3","Requirement Linker","If .workflow/.spec/ exists, scan SPEC-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Output JSON arrays for requirements and architecture_decisions.","requirements",".workflow/codebase/doc-index.json#requirements","","","1"
+"4","Tech Registry Writer","For each component discovered, generate a markdown documentation file in .workflow/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Generate _index.md with component table. Output file count and paths.","tech-registry",".workflow/codebase/tech-registry/","","","1"
+"5","Feature Map Writer","For each feature discovered, generate a markdown documentation file in .workflow/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Generate _index.md with feature table. Output file count and paths.","feature-maps",".workflow/codebase/feature-maps/","","","1"
 ```
 
 **Columns**:
@@ -100,9 +100,16 @@ id,title,description,doc_dimension,output_path,deps,context_from,wave,status,fin
 | `deps` | Input | Empty (all independent) |
 | `context_from` | Input | Empty (no cross-task context needed) |
 | `wave` | Computed | Always 1 (single wave, independent parallel) |
-| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
-| `findings` | Output | Generation summary -- counts, paths, notes (max 500 chars) |
-| `error` | Output | Error message if failed |
+
+**Output columns** (returned exclusively via `output_schema`, NOT in wave CSV):
+
+| Column | Description |
+|--------|-------------|
+| `result_status` | `completed` / `failed` (mapped to master `status` on merge) |
+| `result_findings` | Generation summary -- counts, paths, notes (max 500 chars) |
+| `error` | Error message if failed |
+
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + prev_context. Output columns are returned exclusively via output_schema.
 
 ### Per-Wave CSV (Temporary)
 
@@ -207,16 +214,16 @@ spawn_agents_on_csv({
     type: "object",
     properties: {
       id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
+      result_status: { type: "string", enum: ["completed", "failed"] },
+      result_findings: { type: "string" },
       error: { type: "string" }
     },
-    required: ["id", "status", "findings"]
+    required: ["id", "result_status", "result_findings"]
   }
 })
 ```
 
-Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`.
+Merge `wave-1-results.csv` into master `tasks.csv`: map `result_status` -> master `status`, `result_findings` -> master `findings`, copy `error` as-is. After merge, delete temporary files (`wave-1.csv` and `wave-1-results.csv`).
 
 ### Phase 3: Results -> .workflow/codebase/
 

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -78,16 +78,16 @@ When `--yes` or `-y`: Auto-confirm perspective selection, skip interactive valid
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,perspective,scope_glob,deps,context_from,wave,status,findings,issues_found,severity_distribution,error
-"1","Security Scan","Scan codebase for security vulnerabilities: authentication bypass, injection flaws, XSS, CSRF, sensitive data exposure, insecure crypto, secrets in code. Rate each finding critical/high/medium/low with file:line references.","security","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"2","Performance Scan","Scan codebase for performance issues: N+1 queries, unbounded loops, missing caching, memory leaks, large payloads, blocking operations, unoptimized algorithms.","performance","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"3","Reliability Scan","Scan codebase for reliability issues: unhandled errors, missing retry logic, race conditions, data integrity gaps, missing graceful degradation, silent failures.","reliability","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"4","Maintainability Scan","Scan codebase for maintainability issues: code duplication, tight coupling, missing abstractions, unclear naming, dead code, overly complex functions.","maintainability","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"5","Scalability Scan","Scan codebase for scalability issues: hardcoded limits, single-threaded bottlenecks, stateful assumptions, schema rigidity, missing pagination.","scalability","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"6","UX Scan","Scan codebase for UX issues: confusing flows, missing user feedback, inconsistent behavior, missing loading states, poor error messages.","ux","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"7","Accessibility Scan","Scan codebase for accessibility issues: missing ARIA labels, keyboard navigation gaps, color contrast problems, missing alt text, focus management issues.","accessibility","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"8","Compliance Scan","Scan codebase for compliance issues: logging gaps, missing audit trails, data retention violations, privacy control gaps, regulatory requirement gaps.","compliance","src/**/*.{ts,tsx,js,jsx}","","","1","","","","",""
-"9","Dedup + Issue Creation","Aggregate all perspective findings. Deduplicate by file path + description similarity (keep higher severity). Generate ISS-YYYYMMDD-NNN issue records. Append to .workflow/issues/issues.jsonl.","dedup","","1;2;3;4;5;6;7;8","1;2;3;4;5;6;7;8","2","","","","",""
+id,title,description,perspective,scope_glob,deps,context_from,wave
+"1","Security Scan","Scan codebase for security vulnerabilities: authentication bypass, injection flaws, XSS, CSRF, sensitive data exposure, insecure crypto, secrets in code. Rate each finding critical/high/medium/low with file:line references.","security","src/**/*.{ts,tsx,js,jsx}","","","1"
+"2","Performance Scan","Scan codebase for performance issues: N+1 queries, unbounded loops, missing caching, memory leaks, large payloads, blocking operations, unoptimized algorithms.","performance","src/**/*.{ts,tsx,js,jsx}","","","1"
+"3","Reliability Scan","Scan codebase for reliability issues: unhandled errors, missing retry logic, race conditions, data integrity gaps, missing graceful degradation, silent failures.","reliability","src/**/*.{ts,tsx,js,jsx}","","","1"
+"4","Maintainability Scan","Scan codebase for maintainability issues: code duplication, tight coupling, missing abstractions, unclear naming, dead code, overly complex functions.","maintainability","src/**/*.{ts,tsx,js,jsx}","","","1"
+"5","Scalability Scan","Scan codebase for scalability issues: hardcoded limits, single-threaded bottlenecks, stateful assumptions, schema rigidity, missing pagination.","scalability","src/**/*.{ts,tsx,js,jsx}","","","1"
+"6","UX Scan","Scan codebase for UX issues: confusing flows, missing user feedback, inconsistent behavior, missing loading states, poor error messages.","ux","src/**/*.{ts,tsx,js,jsx}","","","1"
+"7","Accessibility Scan","Scan codebase for accessibility issues: missing ARIA labels, keyboard navigation gaps, color contrast problems, missing alt text, focus management issues.","accessibility","src/**/*.{ts,tsx,js,jsx}","","","1"
+"8","Compliance Scan","Scan codebase for compliance issues: logging gaps, missing audit trails, data retention violations, privacy control gaps, regulatory requirement gaps.","compliance","src/**/*.{ts,tsx,js,jsx}","","","1"
+"9","Dedup + Issue Creation","Aggregate all perspective findings. Deduplicate by file path + description similarity (keep higher severity). Generate ISS-YYYYMMDD-NNN issue records. Append to .workflow/issues/issues.jsonl.","dedup","","1;2;3;4;5;6;7;8","1;2;3;4;5;6;7;8","2"
 ```
 
 **Columns**:
@@ -102,12 +102,14 @@ id,title,description,perspective,scope_glob,deps,context_from,wave,status,findin
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Computed | Wave number (1 = perspective scans, 2 = dedup + issue creation) |
-| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
+| `result_status` | Output | `completed` / `failed` / `skipped` (mapped to master `status` on merge) |
 | `findings` | Output | Key scan findings summary (max 500 chars) |
 | `issues_found` | Output | JSON array of discovered issues: `[{"title":"...","severity":"critical","description":"...","location":"file:line","fix_direction":"...","affected_components":["..."]}]` |
 | `severity_distribution` | Output | JSON: `{"critical":N,"high":N,"medium":N,"low":N}` |
 | `error` | Output | Error message if failed |
 
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + prev_context. Output columns are returned exclusively via output_schema.
+
 ### Per-Wave CSV (Temporary)
 
 Each wave generates `wave-{N}.csv` with extra `prev_context` column.
@@ -249,18 +251,18 @@ spawn_agents_on_csv({
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { // required: id, status, findings
-    id: "string", status: "completed|failed",
+  output_schema: { // required: id, result_status, findings
+    id: "string", result_status: "completed|failed",
     findings: "string", issues_found: "string",
     severity_distribution: "string", error: "string"
   }
 })
 ```
 
-6. Merge `wave-1-results.csv` into master `tasks.csv`
+6. Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` -> master `status` column)
 7. Save per-perspective findings to `{discoveryDir}/{perspective}-findings.json`
 8. Update `discovery-state.json` with completed perspectives
-9. Delete `wave-1.csv`
+9. Delete temporary files: `wave-1.csv` and `wave-1-results.csv`
 
 **Perspective scan agent protocol**:
 - Scan all source files matching scope_glob
@@ -284,8 +286,8 @@ spawn_agents_on_csv({
    ```
 5. Write `wave-2.csv` with `prev_context` column
 6. Execute `spawn_agents_on_csv` for dedup agent
-7. Merge results into master `tasks.csv`
-8. Delete `wave-2.csv`
+7. Merge results into master `tasks.csv` (map `result_status` -> master `status` column)
+8. Delete temporary files: `wave-2.csv` and `wave-2-results.csv`
 
 **Dedup agent protocol**:
 - Merge all perspective findings from prev_context into single list

package/.codex/skills/quality-debug/SKILL.md

@@ -54,7 +54,7 @@ Find where incorrect value appears → trace backward through call chain → fix
 |                                                                           |
 |  Phase 3: Results Aggregation                                             |
 |     +-- Export results.csv with all investigation + fix outcomes           |
-|     +-- Generate context.md with diagnosis summary                        |
+|     +-- Generate understanding.md with diagnosis summary                        |
 |     +-- Update UAT gaps with diagnosis (if --from-uat)                    |
 |     +-- Update issues.jsonl with diagnosis results                        |
 |     +-- Display summary with next steps                                   |
@@ -83,7 +83,7 @@ $quality-debug --continue "20260318-debug-P3-jwt-expiry"
 When `--yes` or `-y`: Auto-confirm hypothesis selection, skip interactive symptom gathering (require bug description in args), use defaults for mode detection.
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
-**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `understanding.md` (human-readable report)
 </context>
 
 <csv_schema>
@@ -91,56 +91,60 @@ When `--yes` or `-y`: Auto-confirm hypothesis selection, skip interactive sympto
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,hypothesis,evidence_for,evidence_against,deps,context_from,wave,status,findings,fix_applied,verified,error
-"H1","Null pointer in login handler","Investigate whether login handler crashes due to null user object after failed DB lookup","User object is null when DB returns empty result; login.ts:42 dereferences without null check","","","","","1","","","","",""
-"H2","Missing error boundary","Investigate whether unhandled promise rejection in auth middleware propagates to 500","Auth middleware catches DB errors but not validation errors; middleware.ts:78 has no catch block","","","","","1","","","","",""
-"H3","Stale session token","Investigate whether expired session tokens bypass refresh logic","Session refresh only triggers on 403 but server returns 401 for expired tokens; session.ts:15","","","","","1","","","","",""
-"FIX-H1","Fix null pointer in login","Apply null check before user object dereference in login handler","","","","H1","H1","2","","","","",""
-"FIX-H3","Fix session token refresh","Update refresh trigger to also handle 401 status codes","","","","H3","H3","2","","","","",""
+id,title,description,hypothesis,deps,context_from,wave
+"H1","Null pointer in login handler","Investigate whether login handler crashes due to null user object after failed DB lookup","User object is null when DB returns empty result; login.ts:42 dereferences without null check","","","1"
+"H2","Missing error boundary","Investigate whether unhandled promise rejection in auth middleware propagates to 500","Auth middleware catches DB errors but not validation errors; middleware.ts:78 has no catch block","","","1"
+"H3","Stale session token","Investigate whether expired session tokens bypass refresh logic","Session refresh only triggers on 403 but server returns 401 for expired tokens; session.ts:15","","","1"
+"FIX-H1","Fix null pointer in login","Apply null check before user object dereference in login handler","","H1","H1","2"
+"FIX-H3","Fix session token refresh","Update refresh trigger to also handle 401 status codes","","H3","H3","2"
 ```
 
 **Columns**:
 
-| Column | Phase | Description |
+| Column | Layer | Description |
 |--------|-------|-------------|
 | `id` | Input | Unique task identifier: `H{N}` for hypotheses (wave 1), `FIX-H{N}` for fixes (wave 2) |
 | `title` | Input | Short hypothesis or fix title |
 | `description` | Input | Detailed investigation/fix instructions |
 | `hypothesis` | Input | The hypothesis being tested (wave 1) or empty (wave 2) |
-| `evidence_for` | Output | Evidence supporting the hypothesis |
-| `evidence_against` | Output | Evidence refuting the hypothesis |
 | `deps` | Input | Semicolon-separated dependency task IDs (wave 2 depends on wave 1) |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
-| `wave` | Computed | Wave number (1 = investigation, 2 = fix attempt) |
-| `status` | Output | `pending` -> `confirmed` / `refuted` / `inconclusive` / `fixed` / `fix_failed` / `skipped` |
+| `wave` | Input | Wave number (1 = investigation, 2 = fix attempt) |
+| `result_status` | Output | `confirmed` / `refuted` / `inconclusive` / `fixed` / `fix_failed` / `failed` |
 | `findings` | Output | Key findings summary (max 500 chars) |
+| `evidence_for` | Output | Evidence supporting the hypothesis (wave 1) |
+| `evidence_against` | Output | Evidence refuting the hypothesis (wave 1) |
 | `fix_applied` | Output | Description of fix applied (wave 2 only) |
 | `verified` | Output | `true` / `false` -- whether fix was verified to work (wave 2 only) |
 | `error` | Output | Error message if failed |
 
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + `prev_context`. Output columns are returned exclusively via `output_schema`.
+
 ### Per-Wave CSV (Temporary)
 
-Each wave generates `wave-{N}.csv` with extra `prev_context` column.
+Each wave generates `wave-{N}.csv` with Input columns + `prev_context` only. Output columns (`result_status`, `findings`, etc.) are NEVER included in wave CSV — they come from `output_schema` in the results CSV.
 
 ### Output Artifacts
 
 | File | Purpose | Lifecycle |
 |------|---------|-----------|
 | `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
-| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `wave-{N}.csv` | Per-wave input (temporary) | Deleted after merge |
+| `wave-{N}-results.csv` | Per-wave output (temporary) | Deleted after merge into tasks.csv |
 | `results.csv` | Final export of all task results | Created in Phase 3 |
 | `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
-| `context.md` | Human-readable diagnosis report | Created in Phase 3 |
+| `understanding.md` | Human-readable diagnosis report | Created in Phase 3 |
 
 ### Session Structure
 
 ```
 .workflow/.csv-wave/{YYYYMMDD}-debug-P{N}-{slug}/
-+-- tasks.csv
-+-- results.csv
-+-- discoveries.ndjson
-+-- context.md
-+-- wave-{N}.csv (temporary)
++-- tasks.csv              (master state, persisted)
++-- results.csv            (final export, persisted)
++-- discoveries.ndjson     (shared board, persisted)
++-- understanding.md       (diagnosis report, persisted)
++-- wave-{N}.csv           (temporary, deleted after merge)
++-- wave-{N}-results.csv   (temporary, deleted after merge)
 ```
 </csv_schema>
 
@@ -151,7 +155,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 4. **Context Propagation**: prev_context built from master CSV, not from memory
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Skip on Refuted**: Wave 2 fix tasks skip if their hypothesis was refuted or inconclusive
-7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+7. **Cleanup Temp Files**: Remove wave-{N}.csv AND wave-{N}-results.csv after results are merged into master tasks.csv
 8. **DO NOT STOP**: Continuous execution until all waves complete
 </invariants>
 
@@ -240,12 +244,12 @@ spawn_agents_on_csv({
   instruction: buildInvestigationInstruction(sessionFolder),  // agent: ~/.codex/agents/workflow-debugger.toml
   max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { id, status: [confirmed|refuted|inconclusive|failed], findings, evidence_for, evidence_against, error }
+  output_schema: { id, result_status: [confirmed|refuted|inconclusive|failed], findings, evidence_for, evidence_against, error }
 })
 ```
 
-3. Merge results into master `tasks.csv`, delete `wave-1.csv`
-4. **Filter for wave 2**: Mark fix tasks as `skipped` if their hypothesis was `refuted` or `inconclusive`
+3. Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), delete `wave-1.csv` and `wave-1-results.csv`
+4. **Filter for wave 2**: Mark fix tasks as `skipped` if their hypothesis `result_status` was `refuted` or `inconclusive`
 
 #### Wave 2: Fix Attempts (Parallel, Confirmed Only)
 
@@ -260,11 +264,11 @@ spawn_agents_on_csv({
   instruction: buildFixInstruction(sessionFolder),  // agent: ~/.codex/agents/workflow-debugger.toml
   max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: { id, status: [fixed|fix_failed|failed], findings, fix_applied, verified, error }
+  output_schema: { id, result_status: [fixed|fix_failed|failed], findings, fix_applied, verified, error }
 })
 ```
 
-4. Merge results into master `tasks.csv`, delete `wave-2.csv`
+4. Merge `wave-2-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), delete `wave-2.csv` and `wave-2-results.csv`
 
 ### Phase 3: Results Aggregation
 
@@ -272,11 +276,11 @@ spawn_agents_on_csv({
 
 1. Export final `tasks.csv` as `results.csv`
 
-2. **Generate context.md**: Debug report with summary (mode, hypothesis/confirmed/fixed/verified counts), per-hypothesis results (hypothesis, evidence for/against, findings, status), per-fix results (fix applied, verified, findings), aggregated root causes, and next steps.
+2. **Generate understanding.md**: Debug report with summary (mode, hypothesis/confirmed/fixed/verified counts), per-hypothesis results (hypothesis, evidence for/against, findings, status), per-fix results (fix applied, verified, findings), aggregated root causes, and next steps.
 
 2b. **Debug confidence scoring**:
 
-   Dimensions (4): hypothesis_quality, evidence_completeness, root_cause_isolation, fix_confidence. Factors (weights): evidence_depth(.30), evidence_strength(.25), coverage_breadth(.20), reproduction(.15), consistency(.10). Map to legacy: <40% = low, 40-70% = medium, >70% = high. Append confidence assessment to context.md.
+   Dimensions (4): hypothesis_quality, evidence_completeness, root_cause_isolation, fix_confidence. Factors (weights): evidence_depth(.30), evidence_strength(.25), coverage_breadth(.20), reproduction(.15), consistency(.10). Map to legacy: <40% = low, 40-70% = medium, >70% = high. Append confidence assessment to understanding.md.
 
 3. **UAT update** (if --from-uat): Update `uat.md` gaps with `root_cause`, `fix_direction`, `affected_files` for confirmed hypotheses.
 
@@ -353,9 +357,9 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"root_cause","data":{"location":"src/
 - [ ] Wave 1 hypotheses investigated in parallel
 - [ ] Refuted/inconclusive hypotheses correctly skip wave 2 fix tasks
 - [ ] Wave 2 fixes attempted only for confirmed hypotheses
-- [ ] context.md produced with diagnosis summary
+- [ ] understanding.md produced with diagnosis summary
 - [ ] Multi-factor confidence scored per hypothesis replacing simple high/medium/low
-- [ ] Confidence assessment appended to context.md
+- [ ] Confidence assessment appended to understanding.md
 - [ ] UAT gaps updated (if --from-uat)
 - [ ] Issues updated with diagnosis results
 - [ ] discoveries.ndjson append-only throughout

package/.codex/skills/quality-refactor/SKILL.md

@@ -39,10 +39,10 @@ $quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume e
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,category,scope,convergence_criteria,read_first,verification_cmd,risk,deps,wave,status,findings,files_modified,tests_passed,retry_count,strategy_adjustment,error
-"TASK-001","Extract shared validation","Extract duplicated email/phone validation logic into shared utils module","duplication","src/auth/login.ts;src/auth/register.ts","src/utils/validation.ts contains export function validateEmail(; grep -r 'validateEmail' shows single import source","src/auth/login.ts;src/auth/register.ts;src/utils/","npm test","low","","1","","","","","0","",""
-"TASK-002","Simplify token refresh","Reduce cyclomatic complexity in token refresh handler from 12 to <6","complexity","src/auth/token.ts","src/auth/token.ts function refreshToken has no more than 2 levels of nesting","src/auth/token.ts;src/auth/types.ts","npm test -- --grep token","medium","","2","","","","","0","",""
-"TASK-003","Remove dead session code","Remove unused session cleanup functions identified in analysis","dead_code","src/session/","grep -r 'cleanupExpired' returns 0 matches outside test files","src/session/cleanup.ts","npm test","low","","1","","","","","0","",""
+id,title,description,category,scope,convergence_criteria,read_first,verification_cmd,risk,deps,wave,status,retry_count,strategy_adjustment
+"TASK-001","Extract shared validation","Extract duplicated email/phone validation logic into shared utils module","duplication","src/auth/login.ts;src/auth/register.ts","src/utils/validation.ts contains export function validateEmail(; grep -r 'validateEmail' shows single import source","src/auth/login.ts;src/auth/register.ts;src/utils/","npm test","low","","1","pending","0",""
+"TASK-002","Simplify token refresh","Reduce cyclomatic complexity in token refresh handler from 12 to <6","complexity","src/auth/token.ts","src/auth/token.ts function refreshToken has no more than 2 levels of nesting","src/auth/token.ts;src/auth/types.ts","npm test -- --grep token","medium","","2","pending","0",""
+"TASK-003","Remove dead session code","Remove unused session cleanup functions identified in analysis","dead_code","src/session/","grep -r 'cleanupExpired' returns 0 matches outside test files","src/session/cleanup.ts","npm test","low","","1","pending","0",""
 ```
 
 **Columns**:
@@ -60,13 +60,21 @@ id,title,description,category,scope,convergence_criteria,read_first,verification
 | `risk` | Input | `low` / `medium` / `high` |
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `wave` | Computed | Wave number — same-risk independent tasks can share a wave |
-| `status` | Output | `pending` -> `completed` / `failed` / `blocked` / `skipped` |
-| `findings` | Output | Implementation notes (max 500 chars) |
-| `files_modified` | Output | Semicolon-separated list of changed files |
-| `tests_passed` | Output | `true` / `false` — verification result |
+| `status` | Input | Task lifecycle state in master CSV: `pending` / `completed` / `failed` / `blocked` / `skipped` |
 | `retry_count` | State | Current retry count (max 2) |
 | `strategy_adjustment` | State | Strategy change note for retry |
-| `error` | Output | Error message if failed |
+
+**Output columns** (returned exclusively via `output_schema`, NOT in wave CSV):
+
+| Column | Description |
+|--------|-------------|
+| `result_status` | `completed` / `failed` / `blocked` — wave execution result |
+| `findings` | Implementation notes (max 500 chars) |
+| `files_modified` | Semicolon-separated list of changed files |
+| `tests_passed` | `true` / `false` — verification result |
+| `error` | Error message if failed |
+
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns. Output columns are returned exclusively via output_schema.
 
 ### Per-Wave CSV (Temporary)
 
@@ -168,16 +176,16 @@ spawn_agents_on_csv({
 2. Apply refactoring described in description targeting scope files
 3. Verify convergence_criteria via grep (all criteria must pass)
 4. Run verification_cmd and report test result
-5. If tests fail: revert ALL changes for this task, set status=failed
+5. If tests fail: revert ALL changes for this task, set result_status=failed
 6. Append discoveries to ${sessionFolder}/discoveries.ndjson
 Report: files_modified (semicolon-separated), tests_passed (true/false), findings (what was changed and why)`,
   max_concurrency: 1, max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
-  output_schema: { id, status: [completed|failed|blocked], findings, files_modified, tests_passed, error }
+  output_schema: { id, result_status: [completed|failed|blocked], findings, files_modified, tests_passed, error }
 })
 ```
 
-4. Merge results into master `tasks.csv`, delete `wave-{N}.csv`
+4. Merge results into master `tasks.csv`: map `result_status` -> master `status` column, copy `findings`, `files_modified`, `tests_passed`, `error` into master. Delete temporary `wave-{N}.csv` and `wave-{N}-results.csv`.
 
 **5b. Reflect per wave:**
 

package/.codex/skills/quality-review/SKILL.md

@@ -81,19 +81,19 @@ When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validat
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave,status,findings,severity_counts,top_issues,error
-"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1","","","","",""
-"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1","","","","",""
-"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
-"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1","","","","",""
-"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
-"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
-"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2","","","","",""
+id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave
+"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1"
+"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1"
+"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
+"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1"
+"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
+"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1"
+"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2"
 ```
 
 **Columns**:
 
-| Column | Phase | Description |
+| Column | Layer | Description |
 |--------|-------|-------------|
 | `id` | Input | Unique task identifier (string) |
 | `title` | Input | Short task title |
@@ -105,12 +105,14 @@ id,title,description,dimension,changed_files,project_specs,review_level,deps,con
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Computed | Wave number (1 = dimension review, 2 = aggregation) |
-| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
+| `result_status` | Output | `completed` / `failed` (returned via output_schema) |
 | `findings` | Output | Key review findings summary (max 500 chars) |
 | `severity_counts` | Output | JSON: `{"critical":N,"high":N,"medium":N,"low":N}` |
 | `top_issues` | Output | Top 5 issues with `[severity] description (file:line)` format |
 | `error` | Output | Error message if failed |
 
+**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + prev_context. Output columns are returned exclusively via output_schema.
+
 ### Per-Wave CSV (Temporary)
 
 Each wave generates `wave-{N}.csv` with extra `prev_context` column.
@@ -120,7 +122,8 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 | File | Purpose | Lifecycle |
 |------|---------|-----------|
 | `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
-| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after merge |
+| `wave-{N}-results.csv` | Per-wave output from spawn_agents_on_csv (temporary) | Created by spawn_agents_on_csv, deleted after merge |
 | `results.csv` | Final export of all task results | Created in Phase 3 |
 | `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
 | `context.md` | Human-readable review report | Created in Phase 3 |
@@ -135,7 +138,8 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 +-- discoveries.ndjson
 +-- context.md
 +-- review.json
-+-- wave-{N}.csv (temporary)
++-- wave-{N}.csv (temporary, deleted after merge)
++-- wave-{N}-results.csv (temporary, deleted after merge)
 ```
 </csv_schema>
 
@@ -146,7 +150,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 4. **Context Propagation**: prev_context built from master CSV, not from memory
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
 6. **Skip on Failure**: If all dimension agents failed, skip aggregation
-7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+7. **Cleanup Temp Files**: Remove wave-{N}.csv and wave-{N}-results.csv after results are merged
 8. **DO NOT STOP**: Continuous execution until all waves complete
 </invariants>
 
@@ -220,25 +224,25 @@ spawn_agents_on_csv({
     type: "object",
     properties: {
       id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
+      result_status: { type: "string", enum: ["completed", "failed"] },
       findings: { type: "string" },
       severity_counts: { type: "string" },
       top_issues: { type: "string" },
       error: { type: "string" }
     },
-    required: ["id", "status", "findings"]
+    required: ["id", "result_status", "findings"]
   }
 })
 ```
 
-Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`.
+Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), then delete both `wave-1.csv` and `wave-1-results.csv`.
 
 #### Wave 2: Aggregation + Deep-Dive
 
 Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation.
 
 Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
-Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results → delete `wave-2.csv`.
+Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results into master `tasks.csv` (map `result_status` → master `status` column) → delete both `wave-2.csv` and `wave-2-results.csv`.
 
 ### Phase 3: Results Aggregation