prizmkit 1.0.13 → 1.0.14

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -234,7 +234,7 @@ Wait for Reviewer to return.
 
 ### Phase 7: Summarize & Commit — DO NOT SKIP
 
-**For bug fixes**: skip `prizmkit.summarize`, use `fix(<scope>):` commit prefix.
+**For bug fixes**: skip `prizmkit.summarize`, skip retrospective, and use `fix(<scope>):` commit prefix.
 
 **7a.** Check if feature already committed:
 ```bash
@@ -245,6 +245,20 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 
 **7b.** Run `prizmkit.summarize` → archive to REGISTRY.md
 
+**7b.5.** Update prizm-docs (feature sessions):
+- Read the 'Implementation Log' in `context-snapshot.md` to identify changed files
+- For each changed file, check if any related `.prizm-docs/` L1/L2 doc needs updating (new APIs, changed behavior, new TRAPS)
+- Update `.prizm-docs/changelog.prizm`: append one-line entry `- feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
+- Stage all modified prizm-docs: `git add .prizm-docs/`
+- Pipeline docs pass condition is `REGISTRY.md` OR `.prizm-docs/` changed in final commit
+
+**7b.6.** Run `prizmkit.retrospective` (feature sessions only, **before commit**):
+- Extract lessons from completed feature — compare spec/plan/tasks vs actual
+- Update relevant `.prizm-docs/` sections: TRAPS, RULES, DECISIONS
+- Write `.prizmkit/specs/{{FEATURE_SLUG}}/retrospective.md`
+- Stage any `.prizm-docs/` changes: `git add .prizm-docs/`
+- **Skip if this session is bug-fix-only**
+
 **7c.** Mark feature complete:
 ```bash
 python3 {{VALIDATOR_SCRIPTS_DIR}}/update-feature-status.py \
@@ -269,7 +283,7 @@ Write to: `{{SESSION_STATUS_PATH}}`
   "feature_id": "{{FEATURE_ID}}",
   "feature_slug": "{{FEATURE_SLUG}}",
   "exec_tier": 3,
-  "status": "<success|partial|failed>",
+  "status": "<success|partial|failed|commit_missing|docs_missing>",
   "completed_phases": [0, 1, 2, 3, 4, 5, 6, 7],
   "current_phase": 7,
   "checkpoint_reached": "CP-3",
@@ -278,6 +292,8 @@ Write to: `{{SESSION_STATUS_PATH}}`
   "errors": [],
   "can_resume": false,
   "resume_from_phase": null,
+  "docs_maintained": true,
+  "retrospective_done": true,
   "artifacts": {
     "context_snapshot_path": ".prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md",
     "spec_path": ".prizmkit/specs/{{FEATURE_SLUG}}/spec.md",

package/bundled/dev-pipeline/templates/session-status-schema.json

@@ -15,7 +15,7 @@
     },
     "status": {
       "type": "string",
-      "enum": ["success", "partial", "failed"]
+      "enum": ["success", "partial", "failed", "commit_missing", "docs_missing"]
     },
     "completed_phases": {
       "type": "array",
@@ -58,6 +58,12 @@
     "can_resume": {
       "type": "boolean"
     },
+    "docs_maintained": {
+      "type": "boolean"
+    },
+    "retrospective_done": {
+      "type": "boolean"
+    },
     "resume_from_phase": {
       "type": ["integer", "null"]
     },

package/bundled/dev-pipeline/tests/conftest.py

@@ -0,0 +1,133 @@
+"""Shared fixtures for dev-pipeline tests."""
+
+import json
+import os
+import pytest
+
+
+@pytest.fixture
+def sample_feature_list():
+    """A valid feature-list.json structure."""
+    return {
+        "$schema": "dev-pipeline-feature-list-v1",
+        "app_name": "TestApp",
+        "global_context": {
+            "language": "Python",
+            "framework": "FastAPI",
+        },
+        "features": [
+            {
+                "id": "F-001",
+                "title": "Project Infrastructure Setup",
+                "description": "Set up the project structure.",
+                "priority": 1,
+                "estimated_complexity": "low",
+                "dependencies": [],
+                "acceptance_criteria": ["Has package.json", "Has README.md"],
+                "status": "pending",
+            },
+            {
+                "id": "F-002",
+                "title": "User Authentication",
+                "description": "Implement user login and registration.",
+                "priority": 2,
+                "estimated_complexity": "high",
+                "dependencies": ["F-001"],
+                "acceptance_criteria": ["Login works", "Registration works"],
+                "status": "pending",
+            },
+            {
+                "id": "F-003",
+                "title": "Dashboard View",
+                "description": "Create main dashboard.",
+                "priority": 3,
+                "estimated_complexity": "medium",
+                "dependencies": ["F-001", "F-002"],
+                "acceptance_criteria": ["Dashboard renders"],
+                "status": "pending",
+            },
+        ],
+    }
+
+
+@pytest.fixture
+def sample_bug_list():
+    """A valid bug-fix-list.json structure."""
+    return {
+        "$schema": "dev-pipeline-bug-fix-list-v1",
+        "project_name": "TestProject",
+        "global_context": {
+            "language": "Python",
+        },
+        "bugs": [
+            {
+                "id": "B-001",
+                "title": "Login crash on empty password",
+                "description": "App crashes when password is empty.",
+                "severity": "critical",
+                "priority": 1,
+                "error_source": {
+                    "type": "stack_trace",
+                    "stack_trace": "Traceback ... ValueError",
+                    "error_message": "Password cannot be empty",
+                },
+                "verification_type": "automated",
+                "acceptance_criteria": ["No crash on empty password"],
+                "status": "pending",
+                "affected_feature": "F-002",
+                "affected_modules": ["auth"],
+            },
+            {
+                "id": "B-002",
+                "title": "Slow dashboard loading",
+                "description": "Dashboard takes 10s to load.",
+                "severity": "medium",
+                "priority": 2,
+                "error_source": {
+                    "type": "user_report",
+                    "reproduction_steps": ["Open dashboard", "Wait 10 seconds"],
+                },
+                "verification_type": "manual",
+                "acceptance_criteria": ["Dashboard loads in <2s"],
+                "status": "pending",
+                "affected_feature": "F-003",
+                "environment": {"os": "macOS", "browser": "Chrome"},
+            },
+        ],
+    }
+
+
+@pytest.fixture
+def feature_list_file(tmp_path, sample_feature_list):
+    """Write sample feature list to a temp file and return the path."""
+    path = tmp_path / "feature-list.json"
+    path.write_text(json.dumps(sample_feature_list, indent=2), encoding="utf-8")
+    return str(path)
+
+
+@pytest.fixture
+def bug_list_file(tmp_path, sample_bug_list):
+    """Write sample bug list to a temp file and return the path."""
+    path = tmp_path / "bug-fix-list.json"
+    path.write_text(json.dumps(sample_bug_list, indent=2), encoding="utf-8")
+    return str(path)
+
+
+@pytest.fixture
+def state_dir(tmp_path):
+    """Create and return a basic state directory."""
+    sd = tmp_path / "state"
+    sd.mkdir()
+    features_dir = sd / "features"
+    features_dir.mkdir()
+    return str(sd)
+
+
+@pytest.fixture
+def bugfix_state_dir(tmp_path):
+    """Create and return a basic bugfix state directory."""
+    sd = tmp_path / "bugfix-state"
+    sd.mkdir()
+    bugs_dir = sd / "bugs"
+    bugs_dir.mkdir()
+    return str(sd)

package/bundled/dev-pipeline/tests/test_check_session.py

@@ -0,0 +1,127 @@
+"""Tests for check-session-status.py."""
+
+import json
+import os
+import sys
+import pytest
+
+
+def _import_check_session():
+    import importlib.util
+    path = os.path.join(
+        os.path.dirname(__file__), "..", "scripts", "check-session-status.py"
+    )
+    spec = importlib.util.spec_from_file_location("check_session_status", path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["check_session_status"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+css = _import_check_session()
+validate_required_fields = css.validate_required_fields
+determine_status = css.determine_status
+
+
+class TestValidateRequiredFields:
+    def test_all_present(self):
+        data = {
+            "session_id": "s-001",
+            "feature_id": "F-001",
+            "status": "success",
+            "timestamp": "2024-01-01T00:00:00Z",
+        }
+        missing = validate_required_fields(data)
+        assert missing == []
+
+    def test_missing_session_id(self):
+        data = {
+            "feature_id": "F-001",
+            "status": "success",
+            "timestamp": "2024-01-01T00:00:00Z",
+        }
+        missing = validate_required_fields(data)
+        assert "session_id" in missing
+
+    def test_missing_multiple(self):
+        data = {"feature_id": "F-001"}
+        missing = validate_required_fields(data)
+        assert "session_id" in missing
+        assert "status" in missing
+        assert "timestamp" in missing
+
+    def test_empty_string_field(self):
+        data = {
+            "session_id": "",
+            "feature_id": "F-001",
+            "status": "success",
+            "timestamp": "2024-01-01T00:00:00Z",
+        }
+        missing = validate_required_fields(data)
+        assert "session_id" in missing
+
+    def test_whitespace_only_field(self):
+        data = {
+            "session_id": "   ",
+            "feature_id": "F-001",
+            "status": "success",
+            "timestamp": "2024-01-01T00:00:00Z",
+        }
+        missing = validate_required_fields(data)
+        assert "session_id" in missing
+
+    def test_non_string_field(self):
+        data = {
+            "session_id": 123,
+            "feature_id": "F-001",
+            "status": "success",
+            "timestamp": "2024-01-01T00:00:00Z",
+        }
+        missing = validate_required_fields(data)
+        assert "session_id" in missing
+
+    def test_empty_data(self):
+        missing = validate_required_fields({})
+        assert len(missing) == 4
+
+
+class TestDetermineStatus:
+    def test_success(self):
+        data = {"status": "success"}
+        assert determine_status(data) == "success"
+
+    def test_failed(self):
+        data = {"status": "failed"}
+        assert determine_status(data) == "failed"
+
+    def test_partial_resumable(self):
+        data = {"status": "partial", "can_resume": True}
+        assert determine_status(data) == "partial_resumable"
+
+    def test_partial_not_resumable(self):
+        data = {"status": "partial", "can_resume": False}
+        assert determine_status(data) == "partial_not_resumable"
+
+    def test_partial_no_resume_key(self):
+        data = {"status": "partial"}
+        assert determine_status(data) == "partial_not_resumable"
+
+    def test_commit_missing(self):
+        data = {"status": "commit_missing"}
+        assert determine_status(data) == "commit_missing"
+
+    def test_docs_missing(self):
+        data = {"status": "docs_missing"}
+        assert determine_status(data) == "docs_missing"
+
+    def test_unknown_status(self):
+        data = {"status": "something_weird"}
+        assert determine_status(data) == "crashed"
+
+    def test_empty_status(self):
+        data = {"status": ""}
+        assert determine_status(data) == "crashed"
+
+    def test_missing_status(self):
+        data = {}
+        assert determine_status(data) == "crashed"

package/bundled/dev-pipeline/tests/test_cleanup_logs.py

@@ -0,0 +1,119 @@
+"""Tests for cleanup-logs.py."""
+
+import json
+import os
+import subprocess
+import sys
+import time
+
+
+def _script_path():
+    return os.path.join(
+        os.path.dirname(__file__), "..", "scripts", "cleanup-logs.py"
+    )
+
+
+def _write_log_file(path, content):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def test_iter_log_files_only_sessions_logs(state_dir):
+    # Targeted log path under sessions/*/logs/
+    valid_log = os.path.join(
+        state_dir, "features", "F-001", "sessions", "S-001", "logs", "session.log"
+    )
+    _write_log_file(valid_log, "ok")
+
+    # logs/ not under sessions should be ignored
+    ignored_log = os.path.join(state_dir, "features", "F-001", "logs", "misc.log")
+    _write_log_file(ignored_log, "ignore me")
+
+    # Import script module for direct function test
+    import importlib.util
+
+    path = _script_path()
+    spec = importlib.util.spec_from_file_location("cleanup_logs", path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["cleanup_logs"] = mod
+    spec.loader.exec_module(mod)
+
+    files = list(mod.iter_log_files(state_dir))
+    assert valid_log in files
+    assert ignored_log not in files
+
+
+def test_cleanup_removes_old_logs_by_retention(state_dir):
+    old_log = os.path.join(
+        state_dir, "features", "F-001", "sessions", "S-001", "logs", "session.log"
+    )
+    new_log = os.path.join(
+        state_dir, "features", "F-001", "sessions", "S-002", "logs", "session.log"
+    )
+
+    _write_log_file(old_log, "old")
+    _write_log_file(new_log, "new")
+
+    # Make old log 20 days old
+    old_ts = time.time() - (20 * 86400)
+    os.utime(old_log, (old_ts, old_ts))
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            _script_path(),
+            "--state-dir",
+            state_dir,
+            "--retention-days",
+            "14",
+            "--max-total-mb",
+            "1024",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    report = json.loads(result.stdout)
+    assert report["deleted_by_reason"]["retention"] >= 1
+    assert not os.path.exists(old_log)
+    assert os.path.exists(new_log)
+
+
+def test_cleanup_enforces_total_size_cap(state_dir):
+    log1 = os.path.join(
+        state_dir, "features", "F-001", "sessions", "S-001", "logs", "session.log"
+    )
+    log2 = os.path.join(
+        state_dir, "features", "F-001", "sessions", "S-002", "logs", "session.log"
+    )
+
+    _write_log_file(log1, "a" * 1024)
+    _write_log_file(log2, "b" * 1024)
+
+    # Ensure deterministic ordering: log1 older than log2
+    old_ts = time.time() - 120
+    new_ts = time.time() - 60
+    os.utime(log1, (old_ts, old_ts))
+    os.utime(log2, (new_ts, new_ts))
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            _script_path(),
+            "--state-dir",
+            state_dir,
+            "--retention-days",
+            "999",
+            "--max-total-mb",
+            "0",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    report = json.loads(result.stdout)
+    assert report["deleted_by_reason"]["size"] >= 1
+    assert report["final_total_bytes"] == 0

package/bundled/dev-pipeline/tests/test_detect_stuck.py

@@ -0,0 +1,207 @@
+"""Tests for detect-stuck.py."""
+
+import json
+import os
+import sys
+import pytest
+from datetime import datetime, timezone, timedelta
+
+
+def _import_detect_stuck():
+    import importlib.util
+    path = os.path.join(
+        os.path.dirname(__file__), "..", "scripts", "detect-stuck.py"
+    )
+    spec = importlib.util.spec_from_file_location("detect_stuck", path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["detect_stuck"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+ds = _import_detect_stuck()
+parse_iso_timestamp = ds.parse_iso_timestamp
+check_max_retries = ds.check_max_retries
+check_stuck_checkpoint = ds.check_stuck_checkpoint
+check_dependency_deadlock = ds.check_dependency_deadlock
+
+
+class TestParseIsoTimestamp:
+    def test_standard_z_format(self):
+        result = parse_iso_timestamp("2024-01-15T10:30:00Z")
+        assert result is not None
+        assert result.year == 2024
+        assert result.month == 1
+        assert result.day == 15
+        assert result.hour == 10
+        assert result.minute == 30
+
+    def test_plus_zero_offset(self):
+        result = parse_iso_timestamp("2024-01-15T10:30:00+00:00")
+        assert result is not None
+        assert result.year == 2024
+
+    def test_with_microseconds_z(self):
+        result = parse_iso_timestamp("2024-01-15T10:30:00.123456Z")
+        assert result is not None
+
+    def test_with_microseconds_offset(self):
+        result = parse_iso_timestamp("2024-01-15T10:30:00.123456+00:00")
+        assert result is not None
+
+    def test_invalid_string(self):
+        result = parse_iso_timestamp("not a timestamp")
+        assert result is None
+
+    def test_none_input(self):
+        result = parse_iso_timestamp(None)
+        assert result is None
+
+    def test_integer_input(self):
+        result = parse_iso_timestamp(12345)
+        assert result is None
+
+    def test_empty_string(self):
+        result = parse_iso_timestamp("")
+        assert result is None
+
+
+class TestCheckMaxRetries:
+    def test_below_max(self):
+        status = {"retry_count": 1}
+        result = check_max_retries(status, 3)
+        assert result is None
+
+    def test_at_max(self):
+        status = {"retry_count": 3}
+        result = check_max_retries(status, 3)
+        assert result is not None
+        assert result["reason"] == "max_retries_exceeded"
+
+    def test_above_max(self):
+        status = {"retry_count": 5}
+        result = check_max_retries(status, 3)
+        assert result is not None
+
+    def test_zero_retries(self):
+        status = {"retry_count": 0}
+        result = check_max_retries(status, 3)
+        assert result is None
+
+    def test_missing_retry_count(self):
+        status = {}
+        result = check_max_retries(status, 3)
+        assert result is None  # defaults to 0
+
+    def test_non_int_retry_count(self):
+        status = {"retry_count": "not a number"}
+        result = check_max_retries(status, 3)
+        assert result is None
+
+
+class TestCheckStuckCheckpoint:
+    def _setup_sessions(self, tmp_path, checkpoints):
+        """Create a feature dir with sessions having given checkpoints."""
+        feature_dir = tmp_path / "feature"
+        sessions_dir = feature_dir / "sessions"
+        for i, cp in enumerate(checkpoints):
+            session_dir = sessions_dir / "session-{:03d}".format(i)
+            session_dir.mkdir(parents=True)
+            data = {"checkpoint_reached": cp}
+            (session_dir / "session-status.json").write_text(
+                json.dumps(data), encoding="utf-8"
+            )
+        return str(feature_dir)
+
+    def test_stuck_at_same_checkpoint(self, tmp_path):
+        feature_dir = self._setup_sessions(tmp_path, ["CP-3", "CP-3", "CP-3"])
+        result = check_stuck_checkpoint(feature_dir)
+        assert result is not None
+        assert result["reason"] == "stuck_at_checkpoint"
+        assert "CP-3" in result["details"]
+
+    def test_different_checkpoints(self, tmp_path):
+        feature_dir = self._setup_sessions(tmp_path, ["CP-1", "CP-2", "CP-3"])
+        result = check_stuck_checkpoint(feature_dir)
+        assert result is None
+
+    def test_fewer_than_three_sessions(self, tmp_path):
+        feature_dir = self._setup_sessions(tmp_path, ["CP-3", "CP-3"])
+        result = check_stuck_checkpoint(feature_dir)
+        assert result is None
+
+    def test_no_sessions(self, tmp_path):
+        feature_dir = tmp_path / "feature"
+        feature_dir.mkdir()
+        result = check_stuck_checkpoint(str(feature_dir))
+        assert result is None
+
+    def test_none_checkpoints(self, tmp_path):
+        feature_dir = self._setup_sessions(tmp_path, [None, None, None])
+        result = check_stuck_checkpoint(feature_dir)
+        assert result is None  # None checkpoints don't trigger stuck
+
+    def test_mixed_with_last_three_same(self, tmp_path):
+        feature_dir = self._setup_sessions(
+            tmp_path, ["CP-1", "CP-2", "CP-3", "CP-3", "CP-3"]
+        )
+        result = check_stuck_checkpoint(feature_dir)
+        assert result is not None
+        assert "CP-3" in result["details"]
+
+
+class TestCheckDependencyDeadlock:
+    def test_dependency_failed(self, state_dir):
+        # Create a failed dependency
+        dep_dir = os.path.join(state_dir, "features", "F-001")
+        os.makedirs(dep_dir, exist_ok=True)
+        with open(os.path.join(dep_dir, "status.json"), "w") as f:
+            json.dump({"status": "failed"}, f)
+
+        feature_list_data = {
+            "features": [
+                {"id": "F-001", "dependencies": []},
+                {"id": "F-002", "dependencies": ["F-001"]},
+            ]
+        }
+        result = check_dependency_deadlock("F-002", feature_list_data, state_dir)
+        assert result is not None
+        assert result["reason"] == "dependency_failed"
+        assert "F-001" in result["details"]
+
+    def test_dependency_completed(self, state_dir):
+        dep_dir = os.path.join(state_dir, "features", "F-001")
+        os.makedirs(dep_dir, exist_ok=True)
+        with open(os.path.join(dep_dir, "status.json"), "w") as f:
+            json.dump({"status": "completed"}, f)
+
+        feature_list_data = {
+            "features": [
+                {"id": "F-001", "dependencies": []},
+                {"id": "F-002", "dependencies": ["F-001"]},
+            ]
+        }
+        result = check_dependency_deadlock("F-002", feature_list_data, state_dir)
+        assert result is None
+
+    def test_no_dependencies(self, state_dir):
+        feature_list_data = {
+            "features": [
+                {"id": "F-001", "dependencies": []},
+            ]
+        }
+        result = check_dependency_deadlock("F-001", feature_list_data, state_dir)
+        assert result is None
+
+    def test_none_feature_list(self, state_dir):
+        result = check_dependency_deadlock("F-001", None, state_dir)
+        assert result is None
+
+    def test_feature_not_found(self, state_dir):
+        feature_list_data = {
+            "features": [
+                {"id": "F-001", "dependencies": []},
+            ]
+        }
+        result = check_dependency_deadlock("F-999", feature_list_data, state_dir)
+        assert result is None