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.
- package/bundled/VERSION.json +3 -3
- package/bundled/agents/prizm-dev-team-critic.md +57 -29
- package/bundled/agents/prizm-dev-team-dev.md +2 -14
- package/bundled/agents/prizm-dev-team-reviewer.md +40 -24
- package/bundled/dev-pipeline/assets/prizm-dev-team-integration.md +3 -2
- package/bundled/dev-pipeline/lib/heartbeat.sh +4 -50
- package/bundled/dev-pipeline/run-bugfix.sh +2 -20
- package/bundled/dev-pipeline/run-feature.sh +2 -20
- package/bundled/dev-pipeline/run-refactor.sh +2 -20
- package/bundled/dev-pipeline/templates/bootstrap-tier2.md +53 -7
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +9 -6
- package/bundled/dev-pipeline/templates/sections/phase-critic-plan-full.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -3
- package/bundled/dev-pipeline-windows/assets/prizm-dev-team-integration.md +3 -2
- package/bundled/dev-pipeline-windows/lib/pipeline.ps1 +6 -58
- package/bundled/dev-pipeline-windows/templates/bootstrap-tier2.md +5 -6
- package/bundled/dev-pipeline-windows/templates/bootstrap-tier3.md +9 -6
- package/bundled/dev-pipeline-windows/templates/sections/phase-critic-plan-full.md +1 -1
- package/bundled/dev-pipeline-windows/templates/sections/phase-review-full.md +1 -3
- package/bundled/rules/_rules-metadata.json +9 -3
- package/bundled/rules/general/agent-operational-rules.md +68 -0
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/feature-planner/SKILL.md +2 -2
- package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +1 -1
- package/bundled/skills/feature-planner/references/new-project-planning.md +1 -1
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +17 -26
- package/bundled/skills-windows/feature-planner/SKILL.md +2 -2
- package/bundled/skills-windows/feature-planner/references/error-recovery.md +1 -1
- package/bundled/skills-windows/feature-planner/references/incremental-feature-planning.md +1 -1
- package/bundled/skills-windows/feature-planner/references/new-project-planning.md +1 -1
- package/bundled/skills-windows/feature-planner/scripts/validate-and-generate.py +17 -26
- package/bundled/team/prizm-dev-team.json +6 -6
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -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.
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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 (
|
|
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
|
|
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:
|
|
55
|
-
CRIT-07:
|
|
56
|
-
CRIT-08:
|
|
57
|
-
CRIT-09:
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
124
|
-
- **Critic-A**: Architecture & scalability
|
|
125
|
-
- **Critic-B**: Data
|
|
126
|
-
- **Critic-C**: Security & performance
|
|
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
|
-
|
|
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
|
-
|
|
158
|
+
4. Do NOT read other critics' reports — independence is the point
|
|
131
159
|
|
|
132
|
-
|
|
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:
|
|
87
|
-
DEV-19:
|
|
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 —
|
|
35
|
-
3.
|
|
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
|
-
|
|
43
|
+
4. Group related findings, establish fix ordering (dependencies first)
|
|
49
44
|
|
|
50
|
-
**Step
|
|
51
|
-
|
|
52
|
-
|
|
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.
|
|
61
|
-
5.
|
|
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.
|
|
68
|
-
3.
|
|
69
|
-
4.
|
|
70
|
-
5.
|
|
71
|
-
6.
|
|
72
|
-
7.
|
|
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
|
|
23
|
-
└── Phase
|
|
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.
|
|
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 [[ "$
|
|
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
|
-
|
|
342
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|