prizmkit 1.0.12 → 1.0.14

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

@@ -130,6 +130,7 @@ Prompt:
 > 2. Run prizmkit-code-review: verify all acceptance criteria, check code quality and correctness. Only read files mentioned in the Implementation Log.
 > 3. Run the test suite and report results.
 > 4. Append a 'Review Notes' section to `context-snapshot.md`: issues found (severity), test results, final verdict.
+> 5. If review uncovers durable pitfalls or conventions, add corresponding TRAPS/RULES notes to relevant `.prizm-docs/` files.
 > Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
 
 Wait for Reviewer to return.
@@ -137,6 +138,21 @@ Wait for Reviewer to return.
 
 **CP-2**: Tests pass, verdict is not NEEDS_FIXES.
 
+### Phase 4.5: Prizm Doc Update (mandatory for feature sessions)
+
+Run `prizmkit.doc.update` and sync project docs before commit:
+1. Use `git diff --cached --name-status` (fallback: `git diff --name-status`) to locate changed modules
+2. Update affected `.prizm-docs/` files (L1/L2, changelog.prizm)
+3. Stage documentation updates (`git add .prizm-docs/`) if changed
+
+Doc maintenance pass condition (pipeline-enforced): `REGISTRY.md` **or** `.prizm-docs/` changed in the final commit.
+
+### Phase 4.7: Retrospective (feature sessions only, before commit)
+
+If this session is a feature (not a bug-fix-only commit), run `prizmkit.retrospective` now — **before committing**.
+Retrospective must update relevant `.prizm-docs/` sections (TRAPS/RULES/DECISIONS) when applicable, so those changes are included in the feature commit.
+Stage any `.prizm-docs/` changes produced: `git add .prizm-docs/`
+
 ### Phase 5: Commit
 
 - Run `prizmkit.summarize` → archive to REGISTRY.md
@@ -148,6 +164,7 @@ Wait for Reviewer to return.
     --feature-id "{{FEATURE_ID}}" --session-id "{{SESSION_ID}}" --action complete
   ```
 - Run `prizmkit.committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
+- MANDATORY: commit must be done via `prizmkit.committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 
 ---
 
@@ -161,7 +178,7 @@ Write to: `{{SESSION_STATUS_PATH}}`
   "feature_id": "{{FEATURE_ID}}",
   "feature_slug": "{{FEATURE_SLUG}}",
   "exec_tier": 2,
-  "status": "<success|partial|failed>",
+  "status": "<success|partial|failed|commit_missing|docs_missing>",
   "completed_phases": [0, 1, 2, 3, 4, 5],
   "current_phase": 5,
   "checkpoint_reached": "CP-2",
@@ -170,6 +187,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",
     "plan_path": ".prizmkit/specs/{{FEATURE_SLUG}}/plan.md",
@@ -180,6 +199,23 @@ Write to: `{{SESSION_STATUS_PATH}}`
 }
 ```
 
+### Step 3.1: Final Clean Check (before exit)
+
+After writing `session-status.json`, verify repository is clean:
+
+```bash
+git status --short
+```
+
+If any files remain, include them in the last commit:
+
+```bash
+git add -A
+git commit --amend --no-edit
+```
+
+Re-check `git status --short` and ensure it is empty before exiting.
+
 ## Critical Paths
 
 | Resource | Path |
@@ -197,5 +233,6 @@ Write to: `{{SESSION_STATUS_PATH}}`
 - Build context-snapshot.md FIRST; all subagents read it instead of re-reading source files
 - Do NOT use `run_in_background=true` when spawning subagents
 - ALWAYS write session-status.json before exiting
-- `prizmkit.committer` is mandatory
+- `prizmkit.committer` is mandatory, and must not be replaced with manual git commit commands
+- Before exiting, `git status --short` must be empty
 - On timeout: check snapshot → model:lite → remaining steps only → max 2 retries → orchestrator fallback

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 \
@@ -255,6 +269,8 @@ python3 {{VALIDATOR_SCRIPTS_DIR}}/update-feature-status.py \
 
 **7d.** Run `prizmkit.committer` → `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`, do NOT push
 
+**7e.** MANDATORY: commit must be done via `prizmkit.committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
+
 ---
 
 ## Step 3: Write Session Status
@@ -267,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",
@@ -276,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",
@@ -287,6 +305,23 @@ Write to: `{{SESSION_STATUS_PATH}}`
 }
 ```
 
+### Step 3.1: Final Clean Check (before exit)
+
+After writing `session-status.json`, verify repository is clean:
+
+```bash
+git status --short
+```
+
+If any files remain, include them in the last commit:
+
+```bash
+git add -A
+git commit --amend --no-edit
+```
+
+Re-check `git status --short` and ensure it is empty before exiting.
+
 ## Step 4: Team Cleanup
 
 No team cleanup needed — agents were spawned directly without TeamCreate.
@@ -311,4 +346,6 @@ No team cleanup needed — agents were spawned directly without TeamCreate.
 - context-snapshot.md is the team knowledge base: PM writes it once, all agents read it
 - Do NOT use `run_in_background=true` when spawning agents
 - ALWAYS write session-status.json before exiting
+- Commit phase must use `prizmkit.committer`; do NOT replace with manual git commit commands
+- Before exiting, `git status --short` must be empty
 - On timeout: check snapshot → model:lite → remaining steps only → max 2 retries → orchestrator fallback

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