prizmkit 1.1.48 → 1.1.51

package/bundled/skills/bug-planner/scripts/validate-bug-list.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
 """
-Validate .prizmkit/plans/bug-fix-list.json against the PrizmKit bug-fix-list schema.
+Validate and generate .prizmkit/plans/bug-fix-list.json files
+for the dev-pipeline system.
+
+Commands:
+  validate    Validate an existing bug-fix-list.json
+  generate    Validate a draft JSON and generate final bug-fix-list.json with defaults
 
 Usage:
-    python3 validate-bug-list.py [.prizmkit/plans/bug-fix-list.json] [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
 
 Exit codes:
-    0 = valid
-    1 = validation errors found
-    2 = file not found or JSON parse error
+  0 = valid / generated
+  1 = validation errors found
+  2 = file not found or JSON parse error
+
+Python 3.6+ required. No external dependencies.
 """
 
+import argparse
 import json
 import sys
 import os
 import re
+from datetime import datetime, timezone
 
 VALID_SEVERITIES = {"critical", "high", "medium", "low"}
 VALID_SOURCE_TYPES = {"stack_trace", "user_report", "failed_test", "log_pattern", "monitoring_alert"}
@@ -24,129 +34,289 @@ BUG_ID_PATTERN = re.compile(r"^B-\d{3}$")
 SCHEMA_VERSION = "dev-pipeline-bug-fix-list-v1"
 
 
-def validate(bug_list_path, feature_list_path=None):
-    errors = []
-    warnings = []
+def _err(msg):
+    """Print an error message to stderr."""
+    print("ERROR: {}".format(msg), file=sys.stderr)
+
+
+def _warn(msg):
+    """Print a warning message to stderr."""
+    print("WARN: {}".format(msg), file=sys.stderr)
+
 
-    # Load bug-fix-list.json
+def _info(msg):
+    """Print an informational message to stderr."""
+    print("INFO: {}".format(msg), file=sys.stderr)
+
+
+def _load_json(path):
+    """Load and return parsed JSON from a file. Returns (data, error_string)."""
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
     try:
-        with open(bug_list_path) as f:
+        with open(path, "r", encoding="utf-8") as f:
             data = json.load(f)
-    except FileNotFoundError:
-        print(f"ERROR: File not found: {bug_list_path}", file=sys.stderr)
-        return 2
+        return data, None
     except json.JSONDecodeError as e:
-        print(f"ERROR: Invalid JSON in {bug_list_path}: {e}", file=sys.stderr)
-        return 2
+        return None, "Invalid JSON in {}: {}".format(path, e)
+    except Exception as e:
+        return None, "Cannot read {}: {}".format(path, e)
 
-    # Load feature-list.json (optional, for cross-reference)
-    feature_ids = set()
-    if feature_list_path:
-        try:
-            with open(feature_list_path) as f:
-                fl_data = json.load(f)
-            feature_ids = {f.get("id") for f in fl_data.get("features", [])}
-        except (FileNotFoundError, json.JSONDecodeError):
-            warnings.append(f"Could not load feature-list.json at {feature_list_path}")
+
+def _write_json(path, data):
+    """Write data as pretty-printed JSON to path. Creates parent dirs if needed."""
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def validate(data, feature_ids=None):
+    """Validate a parsed bug-fix-list data structure.
+
+    Returns a dict with keys: valid, errors, warnings, stats.
+    """
+    errors = []
+    warnings = []
 
     # Top-level required fields
     if "$schema" not in data:
         errors.append("Missing required field: $schema")
     elif data["$schema"] != SCHEMA_VERSION:
-        errors.append(f"Invalid $schema: expected '{SCHEMA_VERSION}', got '{data['$schema']}'")
+        errors.append("Invalid $schema: expected '{}', got '{}'".format(SCHEMA_VERSION, data["$schema"]))
 
     if not data.get("project_name"):
         errors.append("Missing or empty required field: project_name")
 
     bugs = data.get("bugs", [])
-    if not bugs:
+    if not bugs or not isinstance(bugs, list):
         errors.append("Missing or empty required field: bugs")
+        return {
+            "valid": False,
+            "errors": errors,
+            "warnings": warnings,
+            "stats": {"total_bugs": 0, "severity_distribution": {}},
+        }
 
     # Per-bug validation
     seen_ids = set()
-    seen_priorities = set()
+    severity_counts = {}
 
     for i, bug in enumerate(bugs):
-        prefix = f"bugs[{i}]"
+        prefix = "bugs[{}]".format(i)
 
         # Required fields
         bug_id = bug.get("id", "")
         if not bug_id:
-            errors.append(f"{prefix}: missing required field 'id'")
+            errors.append("{}: missing required field 'id'".format(prefix))
         elif not BUG_ID_PATTERN.match(bug_id):
-            errors.append(f"{prefix}: id '{bug_id}' does not match pattern B-NNN")
+            errors.append("{}: id '{}' does not match pattern B-NNN".format(prefix, bug_id))
 
         if bug_id in seen_ids:
-            errors.append(f"{prefix}: duplicate bug id '{bug_id}'")
+            errors.append("{}: duplicate bug id '{}'".format(prefix, bug_id))
         seen_ids.add(bug_id)
 
         if not bug.get("title"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'title'")
+            errors.append("{} ({}): missing required field 'title'".format(prefix, bug_id))
 
         if not bug.get("description"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'description'")
+            errors.append("{} ({}): missing required field 'description'".format(prefix, bug_id))
 
         severity = bug.get("severity", "")
         if severity not in VALID_SEVERITIES:
-            errors.append(f"{prefix} ({bug_id}): invalid severity '{severity}' — must be one of {VALID_SEVERITIES}")
+            errors.append("{} ({}): invalid severity '{}' — must be one of {}".format(
+                prefix, bug_id, severity, sorted(VALID_SEVERITIES)))
+        else:
+            severity_counts[severity] = severity_counts.get(severity, 0) + 1
 
         # error_source
         error_source = bug.get("error_source", {})
         source_type = error_source.get("type", "") if isinstance(error_source, dict) else ""
         if source_type not in VALID_SOURCE_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid error_source.type '{source_type}' — must be one of {VALID_SOURCE_TYPES}")
+            errors.append("{} ({}): invalid error_source.type '{}' — must be one of {}".format(
+                prefix, bug_id, source_type, sorted(VALID_SOURCE_TYPES)))
 
         # verification_type
         vtype = bug.get("verification_type", "")
         if vtype not in VALID_VERIFICATION_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid verification_type '{vtype}' — must be one of {VALID_VERIFICATION_TYPES}")
+            errors.append("{} ({}): invalid verification_type '{}' — must be one of {}".format(
+                prefix, bug_id, vtype, sorted(VALID_VERIFICATION_TYPES)))
 
         # acceptance_criteria
         ac = bug.get("acceptance_criteria", [])
         if not ac or not isinstance(ac, list):
-            errors.append(f"{prefix} ({bug_id}): missing or empty acceptance_criteria array")
+            errors.append("{} ({}): missing or empty acceptance_criteria array".format(prefix, bug_id))
 
         # status
         status = bug.get("status", "")
         if status not in VALID_STATUSES:
-            errors.append(f"{prefix} ({bug_id}): invalid status '{status}' — must be one of {VALID_STATUSES}")
+            errors.append("{} ({}): invalid status '{}' — must be one of {}".format(
+                prefix, bug_id, status, sorted(VALID_STATUSES)))
 
         # Priority validation (optional field)
         priority = bug.get("priority")
         if priority is not None:
             if priority not in ("high", "medium", "low"):
-                errors.append(f"{prefix} ({bug_id}): invalid priority '{priority}' — must be one of 'high', 'medium', 'low'")
+                errors.append("{} ({}): invalid priority '{}' — must be one of 'high', 'medium', 'low'".format(
+                    prefix, bug_id, priority))
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "stats": {
+            "total_bugs": len(bugs),
+            "severity_distribution": severity_counts,
+        },
+    }
+
+
+def cmd_validate(args):
+    """Handle the 'validate' command."""
+    bug_list = args.input
+    feature_list = args.feature_list
+
+    data, load_err = _load_json(bug_list)
+    if load_err:
+        _err(load_err)
+        return 2
+
+    # Load feature-list.json (optional, for cross-reference)
+    if feature_list:
+        fl_data, fl_err = _load_json(feature_list)
+        if not fl_data:
+            _warn("Could not load feature-list.json at {}: {}".format(feature_list, fl_err))
+
+    result = validate(data)
 
+    # Print results to stdout
+    print(json.dumps(result, indent=2, ensure_ascii=False))
 
-    # Output results
-    if errors:
-        print(f"VALIDATION FAILED — {len(errors)} error(s), {len(warnings)} warning(s)\n")
-        for e in errors:
-            print(f"  ERROR: {e}")
-        for w in warnings:
-            print(f"  WARN:  {w}")
+    if result["valid"]:
+        bug_count = result["stats"]["total_bugs"]
+        sev = result["stats"]["severity_distribution"]
+        sev_str = ", ".join("{}={}".format(k, v) for k, v in sorted(sev.items()))
+        _info("VALIDATION PASSED — {} bugs ({})".format(bug_count, sev_str))
+        return 0
+    else:
+        _err("VALIDATION FAILED — {} error(s), {} warning(s)".format(
+            len(result["errors"]), len(result["warnings"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        for w in result["warnings"]:
+            _warn("  WARN: {}".format(w))
         return 1
+
+
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final bug-fix-list.json.
+    """
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
     else:
-        bug_count = len(bugs)
-        severity_counts = {}
-        for b in bugs:
-            s = b.get("severity", "unknown")
-            severity_counts[s] = severity_counts.get(s, 0) + 1
-        sev_str = ", ".join(f"{k}={v}" for k, v in sorted(severity_counts.items()))
-        print(f"VALIDATION PASSED — {bug_count} bugs ({sev_str})")
-        if warnings:
-            for w in warnings:
-                print(f"  WARN:  {w}")
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "bug-planner")
+
+    # Set default status for bugs without one
+    for bug in data.get("bugs", []):
+        bug.setdefault("status", "pending")
+
+    # Validate
+    result = validate(data)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated bug-fix-list written to {}".format(args.output))
         return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        return 1
 
 
-if __name__ == "__main__":
-    bug_list = sys.argv[1] if len(sys.argv) > 1 else ".prizmkit/plans/bug-fix-list.json"
-    feature_list = None
+def main():
+    # Backward compatibility: if first arg is a file path (not a subcommand),
+    # treat it as 'validate' command
+    if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in ("validate", "generate"):
+        sys.argv.insert(1, "validate")
+
+    parser = argparse.ArgumentParser(
+        description="Validate and generate .prizmkit/plans/bug-fix-list.json files.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/bug-fix-list.json\n"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # -- validate --
+    p_validate = subparsers.add_parser(
+        "validate",
+        help="Validate an existing bug-fix-list.json",
+    )
+    p_validate.add_argument(
+        "input", help="Path to bug-fix-list.json"
+    )
+    p_validate.add_argument(
+        "--feature-list", default=None, help="Path to feature-list.json for cross-reference"
+    )
 
-    if "--feature-list" in sys.argv:
-        idx = sys.argv.index("--feature-list")
-        if idx + 1 < len(sys.argv):
-            feature_list = sys.argv[idx + 1]
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final bug-fix-list.json with defaults",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final bug-fix-list.json"
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 2
 
-    sys.exit(validate(bug_list, feature_list))
+    dispatch = {
+        "validate": cmd_validate,
+        "generate": cmd_generate,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        _err("Unknown command: {}".format(args.command))
+        return 2
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled/skills/feature-planner/SKILL.md

@@ -263,9 +263,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Generate next sequential feature IDs
 4. Draft features (title + description + acceptance_criteria + dependencies)
-5. Run validation script immediately
+5. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode incremental
+   ```
 6. If valid → summarize and recommend next step
-7. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+7. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## Browser Interaction Planning
 
@@ -309,10 +312,13 @@ Key requirements:
   - `high` → **standard** (orchestrator + dev + reviewer, 3 agents)
   - `critical` → **full** (full team + critic agents, 5 agents). Use for: architectural changes touching 10+ files, cross-module refactoring with API surface changes, features requiring multi-critic voting
 
-Run the validation script after generation:
+**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
+1. Write a draft JSON to a temporary path (e.g., `.prizmkit/plans/feature-list.draft.json`)
+2. Call the generate script to validate and produce the final file:
 ```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input <output-path> --mode <new|incremental>
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode <new|incremental>
 ```
+The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes. If validation fails, fix the draft and retry.
 
 ## Testing Defaults (Phase 8)
 

package/bundled/skills/feature-planner/scripts/validate-and-generate.py

@@ -6,12 +6,14 @@ for the dev-pipeline system.
 Commands:
   validate    Validate an existing .prizmkit/plans/feature-list.json
   template    Generate a blank template .prizmkit/plans/feature-list.json
+  generate    Validate a draft JSON and generate final feature-list.json with defaults
   summary     Print a summary table of features from a .prizmkit/plans/feature-list.json
   grade       Generate grading results from eval runs (for npm run skill:review)
 
 Usage:
   python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json] [--mode new|incremental]
   python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
+  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json [--mode new|incremental]
   python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
   python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
 
@@ -716,6 +718,66 @@ def cmd_template(args):
     return 0
 
 
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final feature-list.json.
+    """
+    if not args.input:
+        _err("--input is required for the generate command")
+        return 2
+    if not args.output:
+        _err("--output is required for the generate command")
+        return 2
+
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
+    else:
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "feature-planner")
+
+    # Ensure project_name from app_name if needed
+    if "project_name" not in data and "app_name" in data:
+        data["project_name"] = data["app_name"]
+
+    # Set default status for features without one
+    for feature in data.get("features", []):
+        feature.setdefault("status", "pending")
+
+    # Validate
+    mode = getattr(args, "mode", "new") or "new"
+    result = validate_feature_list(data, planning_mode=mode)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated feature-list written to {}".format(args.output))
+        return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  " + e)
+        for w in result.get("warnings", []):
+            _warn("  " + w)
+        return 1
+
+
 def cmd_summary(args):
     """Handle the 'summary' command."""
     if not args.input:
@@ -857,6 +919,7 @@ def main():
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json --mode incremental\n"
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
             "  %(prog)s template --output .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
         ),
@@ -891,6 +954,24 @@ def main():
         "--output", required=True, help="Path to write template file"
     )
 
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final feature-list.json with defaults filled in",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final feature-list.json"
+    )
+    p_generate.add_argument(
+        "--mode",
+        choices=["new", "incremental"],
+        default="new",
+        help="Validation mode (default: new)",
+    )
+
     # -- summary --
     p_summary = subparsers.add_parser(
         "summary",
@@ -931,6 +1012,7 @@ def main():
     dispatch = {
         "validate": cmd_validate,
         "template": cmd_template,
+        "generate": cmd_generate,
         "summary": cmd_summary,
         "grade": cmd_grade,
     }

package/bundled/skills/prizmkit-implement/SKILL.md

@@ -40,6 +40,9 @@ For each unchecked task in plan.md, in order:
 
 1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
 2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+   - **Cover three paths for each function**: happy path (valid inputs producing expected behavior), edge cases (boundary values specific to the parameter type and domain — e.g., zero/min/max for numeric, empty collection, boundary index), and error conditions (inputs that should trigger error handling). Determine edge cases from the function's parameter types and domain logic, not from a fixed checklist. If a function has no edge or error paths, don't force them.
+   - **No redundant tests**: Check if a test for this behavior already exists before writing. Each test must verify a uniquely different code path — don't write multiple tests that exercise the same logic.
+   - **Test your own code only**: Don't test framework behavior, third-party library internals, or language built-ins. For library calls, test the integration point (correct parameters passed, return value correctly handled), not the library itself.
 3. Mark task as `[x]` in `plan.md` immediately after completion — not batched at the end. Immediate marking means plan.md always reflects true progress, even if the session is interrupted.
 4. **Parallel tasks**: If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group. Sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
 5. **Checkpoint tasks** (`CP:` prefix in plan.md): When a checkpoint task is reached, verify build passes and tests pass before continuing. Checkpoints catch integration errors early — skipping them means cascading failures in later phases.