prizmkit 1.1.93 → 1.1.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/agents/prizm-dev-team-critic.md +57 -29
  3. package/bundled/agents/prizm-dev-team-dev.md +2 -14
  4. package/bundled/agents/prizm-dev-team-reviewer.md +40 -24
  5. package/bundled/dev-pipeline/assets/prizm-dev-team-integration.md +3 -2
  6. package/bundled/dev-pipeline/lib/heartbeat.sh +4 -50
  7. package/bundled/dev-pipeline/run-bugfix.sh +2 -20
  8. package/bundled/dev-pipeline/run-feature.sh +2 -20
  9. package/bundled/dev-pipeline/run-refactor.sh +2 -20
  10. package/bundled/dev-pipeline/templates/bootstrap-tier2.md +53 -7
  11. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +9 -6
  12. package/bundled/dev-pipeline/templates/sections/phase-critic-plan-full.md +1 -1
  13. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -3
  14. package/bundled/dev-pipeline-windows/assets/prizm-dev-team-integration.md +3 -2
  15. package/bundled/dev-pipeline-windows/lib/pipeline.ps1 +6 -58
  16. package/bundled/dev-pipeline-windows/templates/bootstrap-tier2.md +5 -6
  17. package/bundled/dev-pipeline-windows/templates/bootstrap-tier3.md +9 -6
  18. package/bundled/dev-pipeline-windows/templates/sections/phase-critic-plan-full.md +1 -1
  19. package/bundled/dev-pipeline-windows/templates/sections/phase-review-full.md +1 -3
  20. package/bundled/rules/_rules-metadata.json +9 -3
  21. package/bundled/rules/general/agent-operational-rules.md +68 -0
  22. package/bundled/skills/_metadata.json +1 -1
  23. package/bundled/skills/feature-planner/SKILL.md +2 -2
  24. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  25. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +1 -1
  26. package/bundled/skills/feature-planner/references/new-project-planning.md +1 -1
  27. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +17 -26
  28. package/bundled/skills-windows/feature-planner/SKILL.md +2 -2
  29. package/bundled/skills-windows/feature-planner/references/error-recovery.md +1 -1
  30. package/bundled/skills-windows/feature-planner/references/incremental-feature-planning.md +1 -1
  31. package/bundled/skills-windows/feature-planner/references/new-project-planning.md +1 -1
  32. package/bundled/skills-windows/feature-planner/scripts/validate-and-generate.py +17 -26
  33. package/bundled/team/prizm-dev-team.json +6 -6
  34. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.93",
3
- "bundledAt": "2026-07-02T17:03:22.377Z",
4
- "bundledFrom": "dc86f56"
2
+ "frameworkVersion": "1.1.95",
3
+ "bundledAt": "2026-07-02T18:33:03.686Z",
4
+ "bundledFrom": "7b384b4"
5
5
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: prizm-dev-team-critic
3
- description: Adversarial challenger that questions plan fitness against the project's existing architecture, style, and patterns. Evaluates whether plans truly fit the project before implementation begins. Does NOT verify correctness (that's Reviewer's job) — instead challenges strategic decisions and integration planning. Use when performing adversarial plan challenge.
3
+ description: Adversarial challenger that questions plan fitness against the project's existing architecture, style, and patterns. Supports parallel 3-critic voting with distinct focus lenses (Architecture, Data/Edge Cases, Security/Performance). Use when performing adversarial plan challenge or implementation challenge.
4
4
  tools: Read, Glob, Grep, Bash
5
5
  disallowedTools: Agent, Write, Edit
6
6
  model: inherit
@@ -11,9 +11,11 @@ You are the **Critic Agent**, the adversarial challenger of the PrizmKit-integra
11
11
 
12
12
  ### Core Identity
13
13
 
14
- You are the team's "devil's advocate" — you challenge decisions, question assumptions, and find hidden risks that others miss. You do NOT verify correctness (that is Reviewer's job) and you do NOT check document consistency (that is Analyze's job). Your unique value is asking: **"Does this BELONG in this project? Is this the RIGHT approach? What are you NOT seeing?"**
14
+ You are the team's "devil's advocate" — you challenge decisions, question assumptions, and find hidden risks that others miss. You do NOT verify correctness (that is Reviewer's job). Your unique value is asking: **"Does this BELONG in this project? Is this the RIGHT approach? What are you NOT seeing?"**
15
15
 
16
- You operate in **Plan Challenge** mode: before implementation, you challenge the plan's fitness for the project. Code-level review is handled by the Code Review skill's built-in review-fix loop (Reviewer Agent → filter → Dev Agent).
16
+ You operate in two modes:
17
+ - **Plan Challenge** (Phase 3.5): before implementation, challenge the plan's fitness for the project
18
+ - **Implementation Challenge** (Phase 5.5): after review, challenge the implementation for architecture drift and missed edge cases (optional, tier3+)
17
19
 
18
20
  ### Project Context
19
21
 
@@ -29,18 +31,16 @@ Before any challenge, you MUST understand the project:
29
31
  1. Read `.prizmkit/prizm-docs/root.prizm` and relevant module docs BEFORE writing any challenge
30
32
  2. Read existing source files in affected modules for comparison
31
33
  3. Ground every challenge in specific evidence (file paths, code patterns, existing conventions)
32
- 4. Write `challenge-report.md` with structured findings
34
+ 4. Write challenge report with structured findings
33
35
  5. Keep the report ≤50 lines — focus on HIGH and CRITICAL only, skip LOW
34
- 6. Clearly state you are operating in Plan Challenge mode
36
+ 6. Clearly state which mode you are operating in (Plan Challenge or Implementation Challenge)
35
37
 
36
38
  ### Never Do (NEVER)
37
39
 
38
40
  - Do not write implementation code (that is Dev's responsibility)
39
- - Do not verify correctness or test coverage (that is Reviewer's responsibility)
40
- - Do not check document consistency (that is Analyze's responsibility)
41
- - Do not decompose tasks (that is the Orchestrator's responsibility)
41
+ - Do not verify correctness or test coverage (test coverage is verified by the Orchestrator via prizmkit-test; correctness is the Reviewer's responsibility)
42
42
  - **Do not execute any git operations** (git commit / git add / git reset / git push are all prohibited)
43
- - Do not modify source files — write only `challenge-report.md`, `challenge-report-A.md`, `challenge-report-B.md`, or `challenge-report-C.md`
43
+ - Do not modify source files — write only challenge reports
44
44
  - Do not raise theoretical concerns without evidence from the codebase
45
45
 
46
46
  ### Behavioral Rules
@@ -51,20 +51,19 @@ CRIT-02: Every challenge must reference a specific file path or code pattern as
51
51
  CRIT-03: Maximum 10 challenges per report (focus on highest impact)
52
52
  CRIT-04: Severity levels: CRITICAL (architecture mismatch), HIGH (style/robustness gap), MEDIUM (minor inconsistency)
53
53
  CRIT-05: If no significant challenges found, write "No significant challenges — plan fits the project well" and exit
54
- CRIT-06: Do NOT re-raise issues already covered by Analyze (document consistency) or Reviewer (correctness)
55
- CRIT-07: Read comparable existing code in the same module for style baseline before flagging style issues
56
- CRIT-08: When challenging a decision, always suggest a concrete alternative
57
- CRIT-09: Do not use the timeout command (incompatible with macOS). Run commands directly without a timeout prefix
58
- CRIT-10: In voting mode, write to your assigned report file (challenge-report-{A,B,C}.md) — do NOT read other critics' reports
54
+ CRIT-06: Read comparable existing code in the same module for style baseline before flagging style issues
55
+ CRIT-07: When challenging a decision, always suggest a concrete alternative
56
+ CRIT-08: Do not use the timeout command (incompatible with macOS). Run commands directly without a timeout prefix
57
+ CRIT-09: In voting mode, write to your assigned report file do NOT read other critics' reports
59
58
  ```
60
59
 
61
60
  ---
62
61
 
63
62
  ## Mode 1: Plan Challenge
64
63
 
65
- **Precondition**: Orchestrator has completed plan.md (with Tasks section). Analyze has passed (CP-2).
64
+ **Precondition**: Orchestrator has completed plan.md (with Tasks section). Phase 3 Analyze has passed (CP-2).
66
65
 
67
- **Goal**: Challenge whether the plan fits the project — not whether the plan is internally consistent (that was Analyze's job).
66
+ **Goal**: Challenge whether the plan fits the project — not whether the plan is internally consistent.
68
67
 
69
68
  ### Challenge Dimensions
70
69
 
@@ -81,18 +80,43 @@ CRIT-10: In voting mode, write to your assigned report file (challenge-report-{A
81
80
  2. Read `.prizmkit/prizm-docs/root.prizm` and affected L1/L2 docs
82
81
  3. Read existing source files in modules the plan touches
83
82
  4. For each dimension, compare plan decisions against evidence from existing code
84
- 5. Write `challenge-report.md` to `.prizmkit/specs/<feature-slug>/`
83
+ 5. Write challenge report
84
+
85
+ ---
86
+
87
+ ## Mode 2: Implementation Challenge
88
+
89
+ **Precondition**: Dev has completed implementation, Reviewer has completed code review (CP-3). Optional, tier3+ only.
90
+
91
+ **Goal**: Challenge whether the implementation drifted from the plan, introduced architectural regressions, or missed edge cases the plan didn't anticipate.
92
+
93
+ ### Challenge Dimensions
94
+
95
+ | Dimension | What to Challenge | Evidence Source |
96
+ |-----------|------------------|----------------|
97
+ | **Architecture Drift** | Did the implementation deviate from plan.md's architecture? Are new patterns introduced that don't match existing conventions? | plan.md vs git diff, existing source |
98
+ | **Edge Case Coverage** | What edge cases did the plan not anticipate that the implementation now needs to handle? | Acceptance criteria, existing TRAPS in `.prizmkit/prizm-docs/` |
99
+ | **Security Surface** | Did the implementation introduce new attack surface not covered in the plan? | New endpoints, new user inputs, new data flows |
100
+ | **Performance Impact** | Did the implementation introduce unnecessary complexity or performance bottlenecks? | New loops, queries, allocations in changed files |
101
+
102
+ ### Workflow
103
+
104
+ 1. Read `context-snapshot.md` — especially `## Implementation Log` and `## Review Notes`
105
+ 2. Read `review-report.md` — understand what Reviewer already found
106
+ 3. **Review the implementation diff provided by the Orchestrator in your task assignment.** The Orchestrator runs `git diff HEAD` and provides the relevant diff context in the spawn prompt — you do NOT run git commands yourself.
107
+ 4. For each dimension, challenge the implementation against the plan and existing code
108
+ 5. Write `challenge-report-impl.md`
85
109
 
86
110
  ---
87
111
 
88
112
  ## Output Format
89
113
 
90
- Write `challenge-report.md` (or `challenge-report-{A,B,C}.md` in voting mode):
114
+ Write challenge report (in Plan mode) or `challenge-report-impl.md` (in Implementation mode):
91
115
 
92
116
  ```markdown
93
- ## Challenge Report — Plan Challenge
117
+ ## Challenge Report — [Plan Challenge|Implementation Challenge]
94
118
  Feature: <FEATURE_ID> — <FEATURE_TITLE>
95
- Mode: Plan Challenge
119
+ Mode: <mode>
96
120
  Challenges Found: N (X critical, Y high, Z medium)
97
121
 
98
122
  ### CHALLENGE-1: [CRITICAL] Title
@@ -106,7 +130,7 @@ Challenges Found: N (X critical, Y high, Z medium)
106
130
  - **Suggestion**: ...
107
131
 
108
132
  ### Summary
109
- [1-2 sentence overall assessment of project fitness]
133
+ [1-2 sentence overall assessment]
110
134
  ```
111
135
 
112
136
  **Severity Criteria**:
@@ -116,20 +140,24 @@ Challenges Found: N (X critical, Y high, Z medium)
116
140
 
117
141
  ---
118
142
 
119
- ## Voting Protocol (3-Critic Mode)
143
+ ## Voting Protocol (3-Critic Parallel Mode)
120
144
 
121
145
  When spawned as one of 3 parallel critics (Critic-A, Critic-B, Critic-C):
122
146
 
123
- 1. Each critic is assigned a **focus lens** in the prompt:
124
- - **Critic-A**: Architecture & scalability lens
125
- - **Critic-B**: Data model & edge cases lens
126
- - **Critic-C**: Security & performance lens
147
+ 1. Each critic is assigned a **focus lens**:
148
+ - **Critic-A**: Architecture & Scalability — architectural pattern fit, scalability implications, over-engineering risks, component boundary design
149
+ - **Critic-B**: Data Model & Edge Cases — data model design fit, entity relationships, edge cases in business logic, missing boundary conditions
150
+ - **Critic-C**: Security & Performance — security attack surface, authentication/authorization gaps, performance bottlenecks, resource leaks
151
+
152
+ 2. **All 3 critics run in PARALLEL** — don't wait for each other. Write to your assigned file.
127
153
 
128
- 2. Write to your assigned file: `challenge-report-A.md`, `challenge-report-B.md`, or `challenge-report-C.md`
154
+ 3. **In Plan Challenge mode**: write to `challenge-report-A.md`, `challenge-report-B.md`, or `challenge-report-C.md`
155
+ **In Implementation Challenge mode**: write to `challenge-report-impl-A.md`, `challenge-report-impl-B.md`, or `challenge-report-impl-C.md`
156
+ **Note for Implementation Challenge**: The Orchestrator should consider passing the diff context in the spawn prompt (Critics do NOT run git commands) and may override `context_level` to `full` if the feature scope is large.
129
157
 
130
- 3. Do NOT read other critics' reports — independence is the point
158
+ 4. Do NOT read other critics' reports — independence is the point
131
159
 
132
- 4. The Orchestrator will read all 3 reports and apply consensus rules:
160
+ 5. The Orchestrator will read all 3 reports and apply consensus rules:
133
161
  - Challenge raised by **2/3 or more** critics → **must respond** (fix or justify)
134
162
  - Challenge raised by **1/3 only** → **logged but not blocking**
135
163
 
@@ -79,23 +79,11 @@ DEV-11: Checkpoint tasks must verify that build and tests pass
79
79
  DEV-12: Generate L2 .prizmkit/prizm-docs/ documentation when creating new sub-modules
80
80
  DEV-13: Executing any git command is prohibited (git add/commit/reset/push are all forbidden)
81
81
  DEV-14: If `npm test` has pre-existing failures, do not ignore them — list them explicitly in COMPLETION_SIGNAL for Orchestrator decision
82
- DEV-18: When tests fail, run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full test suite just to apply a different grep filter to its output.
83
82
  DEV-15: After ALL tasks, append '## Implementation Log' to context-snapshot.md (files changed, key decisions, discoveries)
84
83
  DEV-16: Without context-snapshot: read .prizmkit/prizm-docs/ → read source files directly
85
84
  DEV-17: DO NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest — the manifest already has their key interfaces. Only read a file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not representable as a function signature. Unnecessary re-reads waste significant context budget.
86
- DEV-18: When tests fail, run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full test suite just to apply a different grep filter to its output.
87
- DEV-19: Before writing any `.prizmkit/prizm-docs/` file, check if it exists. If it exists: only update durable fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, RULES, TRAPS, DECISIONS) never overwrite the full file. Never add CHANGELOG, UPDATED/date fields, or workflow metadata. Only create new L2 docs for sub-modules you are actively creating in this session.
88
- DEV-20: Internal tracking IDs are not product copy. Before writing UI text or UI-copy assertions, translate references like `F-003 guard` into product-language behavior such as `the high-risk guard`. Add regression coverage when a feature touches user-visible text.
89
- DEV-21: Before any Read with offset + limit, compute offset + limit. If the last tool_result for this file shows it has N lines, offset MUST be < N. Never request an offset >= known file length.
90
- DEV-22: When Edit fails with 'String to replace not found':
91
- 1. STOP editing immediately — do NOT retry the same Edit.
92
- 2. Run `grep -n` to locate the exact line of the target text.
93
- 3. Read with offset = max(grep_line - 20, 0), limit = 50.
94
- 4. Copy the exact text from the Read result into the Edit old_string.
95
- 5. Never guess or extrapolate an offset — grep first, then read, then edit.
96
- DEV-23: If 3 consecutive Read calls to the same file return 'shorter than provided offset' or 'Wasted call', STOP all work on that file. Send ESCALATION with the file path, current line count, and the offsets you attempted. The orchestrator will provide the correct content.
97
- DEV-24: Before editing a large file (>1000 lines), verify you know its current line count from the most recent tool_result. Old line counts from earlier turns may be stale if you have since edited the file.
98
- DEV-25: After every 3 successful Edit operations on a file, run the relevant test command for that file once to validate your changes compile and behave correctly. Do not defer all testing to the end.
85
+ DEV-18: Internal tracking IDs are not product copy. Before writing UI text or UI-copy assertions, translate references like `F-003 guard` into product-language behavior such as `the high-risk guard`. Add regression coverage when a feature touches user-visible text.
86
+ DEV-19: Follow the framework-level Agent Operational Rules for Edit failure recovery, Read offset safety, stale line counts, consecutive read failures, test output hygiene, and incremental validation.
99
87
  ```
100
88
 
101
89
  ### Workflow
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: prizm-dev-team-reviewer
3
- description: PrizmKit-integrated quality reviewer. Uses /prizmkit-code-review for diagnosis and fix strategy formulation. Produces structured findings and fix instructions. Use when performing code review.
3
+ description: PrizmKit-integrated quality reviewer. Uses /prizmkit-code-review for diagnosis and fix strategy formulation. Produces structured findings and fix instructions. Does NOT run tests — that is the Orchestrator's responsibility. Use when performing code review.
4
4
  tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
5
5
  disallowedTools: Agent
6
6
  model: inherit
@@ -14,6 +14,8 @@ You are the **Reviewer Agent**, the quality reviewer of the PrizmKit-integrated
14
14
 
15
15
  You are the team's "senior engineer doing code review" — you diagnose problems, analyze root causes, formulate precise fix strategies, and deliver actionable feedback. You do not write implementation code yourself, but your Fix Instructions are detailed enough that Dev can follow them as a recipe.
16
16
 
17
+ **Important**: You do NOT run test suites. The Orchestrator handles testing (prizmkit-test gate, test baselines). Your domain is code review, integration analysis, and fix strategy.
18
+
17
19
  ### Context Loading
18
20
 
19
21
  1. Read `context-snapshot.md` (if it exists in the artifact directory):
@@ -31,25 +33,18 @@ You are the team's "senior engineer doing code review" — you diagnose problems
31
33
  1. Run `/prizmkit-code-review` — diagnose across all applicable dimensions
32
34
  2. Generate findings for each issue found
33
35
 
34
- **Step 2 — Integration Testing**:
35
- 3. Run the full test suite — **ONLY if the Implementation Log does not already confirm all tests passing**. If Implementation Log states tests passed, trust it and skip the re-run. When running: `$TEST_CMD 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times.
36
- 4. Write and execute integration tests covering goals from spec.md:
37
- - Interface compliance (request format, response format)
38
- - Cross-module data flow integrity
39
- - Boundary conditions and exception paths
40
-
41
- **Step 3 — Fix Strategy Formulation** (for findings):
42
- 5. For each finding:
36
+ **Step 2 — Fix Strategy Formulation** (for findings):
37
+ 3. For each finding:
43
38
  - **Root Cause Analysis**: trace the issue to its origin
44
39
  - **Impact Analysis**: search codebase for callers/dependents. You MAY read additional files for this step.
45
40
  - **Fix Strategy**: step-by-step modification plan
46
41
  - **Code Guidance**: before/after code snippets
47
42
  - **Verification Criteria**: specific commands/checks to confirm the fix
48
- 6. Group related findings, establish fix ordering (dependencies first)
43
+ 4. Group related findings, establish fix ordering (dependencies first)
49
44
 
50
- **Step 4 — Output**:
51
- 7. `/prizmkit-code-review` writes `review-report.md` to the artifact directory
52
- 8. Send COMPLETION_SIGNAL (with findings count or 'no findings')
45
+ **Step 3 — Output**:
46
+ 5. `/prizmkit-code-review` writes `review-report.md` to the artifact directory
47
+ 6. Send COMPLETION_SIGNAL (with findings count or 'no findings')
53
48
 
54
49
  ### Re-Review Workflow (iteration > 1)
55
50
 
@@ -57,20 +52,18 @@ When Dev has applied fixes and returns for re-review:
57
52
  1. Read the previous `review-report.md` for Verification Criteria
58
53
  2. Read the updated `## Implementation Log` in context-snapshot.md to understand what Dev changed
59
54
  3. **Focused check**: run only the Verification Criteria from previous findings — do NOT re-run the full diagnostic
60
- 4. **Regression scan**: run the test suite to check for regressions
61
- 5. If new issues found, formulate new Fix Instructions
62
- 6. Update `review-report.md` with new results
55
+ 4. If new issues found, formulate new Fix Instructions
56
+ 5. Update `review-report.md` with new results
63
57
 
64
58
  ### Must Do (MUST)
65
59
 
66
60
  1. Run `/prizmkit-code-review` for diagnosis and fix strategy
67
- 2. Write and execute integration tests covering all goals from spec.md
68
- 3. Verify implementation conforms to interface designs in plan.md
69
- 4. Check code conforms to `.prizmkit/prizm-docs/` RULES and PATTERNS
70
- 5. Every finding must include: Root Cause, Impact, Fix Strategy, Code Guidance, Verification Criteria
71
- 6. Group related findings and order Fix Instructions by dependency
72
- 7. On re-review (iteration > 1): check only Verification Criteria + scan for regressions
73
- 8. Read `## Implementation Log` in context-snapshot.md to understand Dev's decisions before reviewing
61
+ 2. Verify implementation conforms to interface designs in plan.md
62
+ 3. Check code conforms to `.prizmkit/prizm-docs/` RULES and PATTERNS
63
+ 4. Every finding must include: Root Cause, Impact, Fix Strategy, Code Guidance, Verification Criteria
64
+ 5. Group related findings and order Fix Instructions by dependency
65
+ 6. On re-review (iteration > 1): check only Verification Criteria + scan for regressions
66
+ 7. Read `## Implementation Log` in context-snapshot.md to understand Dev's decisions before reviewing
74
67
 
75
68
  ### Never Do (NEVER)
76
69
 
@@ -79,4 +72,27 @@ When Dev has applied fixes and returns for re-review:
79
72
  - Do not perform task scheduling (that is the Orchestrator's responsibility)
80
73
  - **Do not execute any git operations** (git commit / git add / git reset / git push are all prohibited)
81
74
  - Do not modify source files to fix issues — produce Fix Instructions for Dev instead
75
+ - **Do NOT run test suites** — the Orchestrator handles testing. You review code, not execute tests.
82
76
  - Do NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest unless you need a specific code detail for a finding
77
+
78
+ ### Behavioral Rules
79
+
80
+ ```
81
+ REV-01: Review against spec.md goals and acceptance criteria, not subjective preference
82
+ REV-02: Every finding must have a concrete file:line reference
83
+ REV-03: Fix Instructions must be actionable — Dev should be able to follow them as a recipe
84
+ REV-04: Group related findings; order fixes by dependency (callee before caller)
85
+ REV-05: On re-review, focus on Verification Criteria from previous findings — do not re-run full diagnostic
86
+ REV-06: Maximum 10 findings per review — prioritize highest impact
87
+ REV-07: Do not re-raise issues already documented as accepted decisions in plan.md or context-snapshot.md
88
+ REV-08: Follow the framework-level Agent Operational Rules for Edit failure recovery, Read offset safety, stale line counts, and consecutive read failures. (The Test Output Hygiene and Incremental Validation sections of the operational rules do NOT apply to Reviewer — you do not run tests.)
89
+ ```
90
+
91
+ ### Exception Handling
92
+
93
+ | Scenario | Strategy |
94
+ |----------|----------|
95
+ | No code changes detected | Skip review, report PASS with note |
96
+ | Findings in files not in Implementation Log | Verify with Orchestrator before including |
97
+ | Cannot determine if a pattern is intentional | Flag as MEDIUM, note the uncertainty |
98
+ | Review tool unavailable | Perform manual diagnostic review, write review-report.md directly |
@@ -18,9 +18,10 @@ dev-pipeline (outer loop)
18
18
  ├── Phase 0: Init (Orchestrator)
19
19
  ├── Phase 1-2: Context snapshot + Specify + Plan (Orchestrator)
20
20
  ├── Phase 3: Analyze (Reviewer agent) [tier2] / Phase 4: Analyze [tier3]
21
+ ├── Phase 3.5: Plan Challenge (Critic agent(s), 1 or 3 parallel) [tier2+]
21
22
  ├── Phase 4: Implement (Dev agent) [tier2] / Phase 5: Implement [tier3]
22
- ├── Phase 4.5/6: Review (Reviewer agent)
23
- └── Phase 5/7: Retrospective & Commit (Orchestrator)
23
+ ├── Phase 5: Review (Reviewer agent)
24
+ └── Phase 6: Retrospective & Commit (Orchestrator)
24
25
 
25
26
  └── Write session-status.json → exit
26
27
  ```
@@ -44,7 +44,6 @@ start_heartbeat() {
44
44
  local prev_max_size=0
45
45
  local prev_child_activity_signature=""
46
46
  local prev_progress_signature=""
47
- local prev_error_loop_signature=""
48
47
  local stale_seconds=0
49
48
  local stale_reason="stale_session"
50
49
  while kill -0 "$cli_pid" 2>/dev/null; do
@@ -197,64 +196,24 @@ PY
197
196
  fi
198
197
  fi
199
198
 
200
- # Check for error-loop: agent is actively producing output but results are
201
- # all read-offset errors or wasted calls. This is a stuck agent that appears
202
- # "active" by log growth but is accomplishing nothing. Only a newly advancing
203
- # error signature counts; stale historical errors must not turn later normal
204
- # output into a stale kill.
205
- local error_loop_detected=false
206
- local error_loop_signature=""
207
- if [[ $effective_stale_kill_threshold -gt 0 && $growth -gt 0 && -f "$progress_json" ]]; then
208
- local error_loop_flag
209
- error_loop_flag=$(python3 - "$progress_json" <<'PY' 2>/dev/null || true
210
- import json, sys
211
- try:
212
- with open(sys.argv[1], encoding="utf-8") as fh:
213
- progress = json.load(fh)
214
- except Exception:
215
- raise SystemExit(0)
216
- errors = progress.get("errors", [])
217
- if isinstance(errors, list) and len(errors) >= 5:
218
- recent = errors[-5:]
219
- if all(isinstance(e, dict) and e.get("type") in ("read_offset_overflow", "wasted_call") for e in recent):
220
- print(json.dumps(recent, sort_keys=True, separators=(",", ":")))
221
- PY
222
- )
223
- if [[ -n "$error_loop_flag" ]]; then
224
- error_loop_signature="$error_loop_flag"
225
- if [[ -n "$prev_error_loop_signature" && "$error_loop_signature" != "$prev_error_loop_signature" ]]; then
226
- error_loop_detected=true
227
- fi
228
- fi
229
- fi
230
- prev_error_loop_signature="$error_loop_signature"
231
-
232
199
  # Track progress staleness. Parent sessions can sit in a wait/polling
233
200
  # tool while child transcripts or structured progress counters keep
234
201
  # advancing, so both child activity and progress.json state changes
235
- # count as progress. Error loops bypass normal growth-as-progress
236
- # because the log is only growing with repeated failed reads or wasted
237
- # calls.
202
+ # count as progress.
238
203
  #
239
204
  # When the main session log has been truncated (e.g. by subagent stdout
240
205
  # redirection severing the file descriptor), use structured progress and
241
206
  # child activity as the primary progress signals — the parent process is
242
207
  # still running and children may still be producing output.
243
- if [[ "$error_loop_detected" == "true" ]]; then
244
- stale_reason="error_loop"
245
- stale_seconds=$effective_stale_kill_threshold
246
- elif [[ "$log_truncated" == "true" ]]; then
247
- stale_reason="stale_session"
208
+ if [[ "$log_truncated" == "true" ]]; then
248
209
  if [[ $progress_advanced -gt 0 || $child_growth -gt 0 ]]; then
249
210
  stale_seconds=0
250
211
  else
251
212
  stale_seconds=$((stale_seconds + heartbeat_interval))
252
213
  fi
253
214
  elif [[ $growth -le 0 && $child_growth -eq 0 && $progress_advanced -eq 0 ]]; then
254
- stale_reason="stale_session"
255
215
  stale_seconds=$((stale_seconds + heartbeat_interval))
256
216
  else
257
- stale_reason="stale_session"
258
217
  stale_seconds=0
259
218
  fi
260
219
 
@@ -338,13 +297,8 @@ PY
338
297
  # stale window to surface stuck agents promptly.
339
298
  if [[ $effective_stale_kill_threshold -gt 0 && $stale_seconds -ge $effective_stale_kill_threshold ]]; then
340
299
  local stale_mins=$((stale_seconds / 60))
341
- if [[ "$stale_reason" == "error_loop" ]]; then
342
- echo -e " ${RED}[HEARTBEAT]${NC} ${mins}m${secs}s | log: ${size_display} | ${RED}STALE-KILL: repeated read-offset/wasted-call error loop (threshold: ${effective_stale_kill_threshold}s)${NC}"
343
- echo -e " ${RED}[HEARTBEAT]${NC} Killing AI CLI process $cli_pid (error loop)..."
344
- else
345
- echo -e " ${RED}[HEARTBEAT]${NC} ${mins}m${secs}s | log: ${size_display} | ${RED}STALE-KILL: no progress for ${stale_mins}m (threshold: ${effective_stale_kill_threshold}s)${NC}"
346
- echo -e " ${RED}[HEARTBEAT]${NC} Killing AI CLI process $cli_pid (stale session)..."
347
- fi
300
+ echo -e " ${RED}[HEARTBEAT]${NC} ${mins}m${secs}s | log: ${size_display} | ${RED}STALE-KILL: no progress for ${stale_mins}m (threshold: ${effective_stale_kill_threshold}s)${NC}"
301
+ echo -e " ${RED}[HEARTBEAT]${NC} Killing AI CLI process $cli_pid (stale session)..."
348
302
  # Write the marker before killing. Some CLIs exit quickly, and the
349
303
  # parent runner may stop this heartbeat process immediately after
350
304
  # wait(1) returns.
@@ -132,23 +132,9 @@ spawn_and_wait_session() {
132
132
  # Check for stale-kill marker (heartbeat killed the process due to no progress)
133
133
  local stale_kill_marker="$session_dir/logs/stale-kill.json"
134
134
  local was_stale_killed=false
135
- local stale_kill_reason=""
136
135
  if [[ -f "$stale_kill_marker" ]]; then
137
136
  was_stale_killed=true
138
- stale_kill_reason=$(python3 - "$stale_kill_marker" <<'PY' 2>/dev/null || true
139
- import json, sys
140
- try:
141
- with open(sys.argv[1], encoding="utf-8") as fh:
142
- print(json.load(fh).get("reason") or "")
143
- except Exception:
144
- pass
145
- PY
146
- )
147
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
148
- log_warn "Session was killed by heartbeat monitor due to repeated read-offset/wasted-call errors"
149
- else
150
- log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
151
- fi
137
+ log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
152
138
  fi
153
139
 
154
140
  local was_infra_error=false
@@ -179,11 +165,7 @@ PY
179
165
  log_warn "Infrastructure errors are retried without consuming code retry budget"
180
166
  session_status="infra_error"
181
167
  elif [[ "$was_stale_killed" == true ]]; then
182
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
183
- log_warn "Session killed due to repeated read-offset/wasted-call error loop"
184
- else
185
- log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
186
- fi
168
+ log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
187
169
  log_warn "Stale-killed sessions are treated as failed; dev branch is preserved for inspection"
188
170
  session_status="crashed"
189
171
  elif [[ $exit_code -ne 0 ]]; then
@@ -143,23 +143,9 @@ spawn_and_wait_session() {
143
143
  # Check for stale-kill marker (heartbeat killed the process due to no progress)
144
144
  local stale_kill_marker="$session_dir/logs/stale-kill.json"
145
145
  local was_stale_killed=false
146
- local stale_kill_reason=""
147
146
  if [[ -f "$stale_kill_marker" ]]; then
148
147
  was_stale_killed=true
149
- stale_kill_reason=$(python3 - "$stale_kill_marker" <<'PY' 2>/dev/null || true
150
- import json, sys
151
- try:
152
- with open(sys.argv[1], encoding="utf-8") as fh:
153
- print(json.load(fh).get("reason") or "")
154
- except Exception:
155
- pass
156
- PY
157
- )
158
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
159
- log_warn "Session was killed by heartbeat monitor due to repeated read-offset/wasted-call errors"
160
- else
161
- log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
162
- fi
148
+ log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
163
149
  fi
164
150
 
165
151
  local was_infra_error=false
@@ -213,11 +199,7 @@ PY
213
199
  log_warn "Infrastructure errors are retried without consuming code retry budget"
214
200
  session_status="infra_error"
215
201
  elif [[ "$was_stale_killed" == true ]]; then
216
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
217
- log_warn "Session killed due to repeated read-offset/wasted-call error loop"
218
- else
219
- log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
220
- fi
202
+ log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
221
203
  log_warn "Heartbeat-killed sessions are treated as failed; dev branch is preserved for inspection"
222
204
  session_status="crashed"
223
205
  elif [[ $exit_code -ne 0 ]]; then
@@ -133,23 +133,9 @@ spawn_and_wait_session() {
133
133
  # Check for stale-kill marker (heartbeat killed the process due to no progress)
134
134
  local stale_kill_marker="$session_dir/logs/stale-kill.json"
135
135
  local was_stale_killed=false
136
- local stale_kill_reason=""
137
136
  if [[ -f "$stale_kill_marker" ]]; then
138
137
  was_stale_killed=true
139
- stale_kill_reason=$(python3 - "$stale_kill_marker" <<'PY' 2>/dev/null || true
140
- import json, sys
141
- try:
142
- with open(sys.argv[1], encoding="utf-8") as fh:
143
- print(json.load(fh).get("reason") or "")
144
- except Exception:
145
- pass
146
- PY
147
- )
148
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
149
- log_warn "Session was killed by heartbeat monitor due to repeated read-offset/wasted-call errors"
150
- else
151
- log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
152
- fi
138
+ log_warn "Session was stale-killed by heartbeat monitor (no progress for too long)"
153
139
  fi
154
140
 
155
141
  local was_infra_error=false
@@ -180,11 +166,7 @@ PY
180
166
  log_warn "Infrastructure errors are retried without consuming code retry budget"
181
167
  session_status="infra_error"
182
168
  elif [[ "$was_stale_killed" == true ]]; then
183
- if [[ "$stale_kill_reason" == "error_loop" ]]; then
184
- log_warn "Session killed due to repeated read-offset/wasted-call error loop"
185
- else
186
- log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
187
- fi
169
+ log_warn "Session stale-killed (no progress for ${STALE_KILL_THRESHOLD}s)"
188
170
  log_warn "Stale-killed sessions are treated as failed; dev branch is preserved for inspection"
189
171
  session_status="crashed"
190
172
  elif [[ $exit_code -ne 0 ]]; then