prizmkit 1.1.175 → 1.1.177
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/dev-pipeline/prizmkit_runtime/runners.py +2 -2
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +104 -1
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +0 -2
- package/bundled/dev-pipeline/scripts/update-checkpoint.py +31 -3
- package/bundled/dev-pipeline/templates/bootstrap-prompt.md +1 -1
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +1 -9
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
- package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +1 -1
- package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +2 -2
- package/bundled/dev-pipeline/templates/sections/runtime-commit-handoff.md +3 -3
- package/bundled/dev-pipeline/tests/test_checkpoint_state.py +44 -3
- package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +31 -4
- package/bundled/dev-pipeline/tests/test_runtime_commit.py +155 -0
- package/bundled/rules/prizm/prizm-commit-workflow.md +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/bug-planner/SKILL.md +27 -31
- package/bundled/skills/bug-planner/references/error-recovery.md +24 -24
- package/bundled/skills/bug-planner/references/generated-plan-review.md +5 -1
- package/bundled/skills/feature-planner/SKILL.md +17 -17
- package/bundled/skills/feature-planner/references/error-recovery.md +25 -15
- package/bundled/skills/feature-planner/references/generated-plan-review.md +5 -1
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +5 -3
- package/bundled/skills/feature-planner/references/new-project-planning.md +7 -4
- package/bundled/skills/prizmkit/SKILL.md +5 -5
- package/bundled/skills/prizmkit-committer/SKILL.md +21 -24
- package/bundled/skills/prizmkit-workflow/SKILL.md +9 -9
- package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +8 -7
- package/bundled/skills/refactor-planner/SKILL.md +18 -12
- package/bundled/skills/refactor-planner/references/error-recovery.md +16 -8
- package/bundled/skills/refactor-planner/references/fast-path.md +4 -3
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +5 -1
- package/package.json +1 -1
- package/bundled/dev-pipeline/templates/sections/subagent-timeout-recovery.md +0 -9
|
@@ -12,6 +12,7 @@ from prizmkit_runtime.checkpoint_state import load_checkpoint_state
|
|
|
12
12
|
from prizmkit_runtime.runtime_commit import (
|
|
13
13
|
finalize_accepted_workspace_commit,
|
|
14
14
|
finalize_runtime_commit,
|
|
15
|
+
prepare_runtime_commit_handoff,
|
|
15
16
|
)
|
|
16
17
|
|
|
17
18
|
|
|
@@ -174,6 +175,30 @@ def _write_commit_ready_checkpoint(root: Path) -> tuple[Path, Path]:
|
|
|
174
175
|
return artifact_dir, checkpoint_path
|
|
175
176
|
|
|
176
177
|
|
|
178
|
+
def _rewind_to_ai_request_ready(checkpoint_path: Path) -> None:
|
|
179
|
+
"""Model the state after Committer wrote a request but before Runtime adoption."""
|
|
180
|
+
checkpoint = json.loads(checkpoint_path.read_text(encoding="utf-8"))
|
|
181
|
+
committer = next(
|
|
182
|
+
step for step in checkpoint["steps"]
|
|
183
|
+
if step["skill"] == "prizmkit-committer"
|
|
184
|
+
)
|
|
185
|
+
committer["status"] = "in_progress"
|
|
186
|
+
committer.pop("stage_result", None)
|
|
187
|
+
semantic = checkpoint["feature_state"]
|
|
188
|
+
semantic.update(
|
|
189
|
+
{
|
|
190
|
+
"stage": "committer",
|
|
191
|
+
"status": "in_progress",
|
|
192
|
+
"current_stage": "prizmkit-committer",
|
|
193
|
+
"next_stage": "prizmkit-committer",
|
|
194
|
+
"terminal_status": None,
|
|
195
|
+
}
|
|
196
|
+
)
|
|
197
|
+
semantic.pop("stage_result", None)
|
|
198
|
+
semantic.pop("blocked_reason", None)
|
|
199
|
+
checkpoint_path.write_text(json.dumps(checkpoint), encoding="utf-8")
|
|
200
|
+
|
|
201
|
+
|
|
177
202
|
def _write_request(root: Path, artifact_dir: Path, base_head: str) -> Path:
|
|
178
203
|
request_path = artifact_dir / "runtime-commit-request.json"
|
|
179
204
|
request_path.write_text(
|
|
@@ -190,6 +215,136 @@ def _write_request(root: Path, artifact_dir: Path, base_head: str) -> Path:
|
|
|
190
215
|
return request_path
|
|
191
216
|
|
|
192
217
|
|
|
218
|
+
def test_runtime_prepares_pending_from_ai_request_without_git_mutation(tmp_path):
|
|
219
|
+
base_head = _init_repo(tmp_path)
|
|
220
|
+
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
221
|
+
_rewind_to_ai_request_ready(checkpoint_path)
|
|
222
|
+
(tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
|
|
223
|
+
_write_request(tmp_path, artifact_dir, base_head)
|
|
224
|
+
|
|
225
|
+
result = prepare_runtime_commit_handoff(
|
|
226
|
+
tmp_path,
|
|
227
|
+
artifact_dir=artifact_dir,
|
|
228
|
+
checkpoint_path=checkpoint_path,
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
assert result.status == "ready"
|
|
232
|
+
assert result.reason == "runtime_commit_handoff_prepared"
|
|
233
|
+
assert _git(tmp_path, "rev-parse", "HEAD") == base_head
|
|
234
|
+
state = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
|
|
235
|
+
assert state.semantic_commit_ready is True
|
|
236
|
+
committer = next(
|
|
237
|
+
step for step in state.steps if step.skill == "prizmkit-committer"
|
|
238
|
+
)
|
|
239
|
+
assert committer.status == "in_progress"
|
|
240
|
+
assert committer.stage_result == "COMMIT_PENDING"
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def test_runtime_commit_auto_prepares_ai_request_and_finalizes(tmp_path):
|
|
244
|
+
base_head = _init_repo(tmp_path)
|
|
245
|
+
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
246
|
+
_rewind_to_ai_request_ready(checkpoint_path)
|
|
247
|
+
(tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
|
|
248
|
+
_write_request(tmp_path, artifact_dir, base_head)
|
|
249
|
+
|
|
250
|
+
result = finalize_runtime_commit(
|
|
251
|
+
tmp_path,
|
|
252
|
+
artifact_dir=artifact_dir,
|
|
253
|
+
checkpoint_path=checkpoint_path,
|
|
254
|
+
)
|
|
255
|
+
|
|
256
|
+
assert result.status == "committed"
|
|
257
|
+
assert result.commit_hash == _git(tmp_path, "rev-parse", "HEAD")
|
|
258
|
+
assert load_checkpoint_state(
|
|
259
|
+
checkpoint_path,
|
|
260
|
+
project_root=tmp_path,
|
|
261
|
+
).semantic_complete is True
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def test_runner_adopts_request_without_ai_publishing_pending(tmp_path):
|
|
265
|
+
from types import SimpleNamespace
|
|
266
|
+
|
|
267
|
+
from prizmkit_runtime.runners import _finalize_prepared_runtime_commit
|
|
268
|
+
|
|
269
|
+
base_head = _init_repo(tmp_path)
|
|
270
|
+
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
271
|
+
_rewind_to_ai_request_ready(checkpoint_path)
|
|
272
|
+
(tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
|
|
273
|
+
_write_request(tmp_path, artifact_dir, base_head)
|
|
274
|
+
|
|
275
|
+
result = _finalize_prepared_runtime_commit(
|
|
276
|
+
tmp_path,
|
|
277
|
+
SimpleNamespace(
|
|
278
|
+
checkpoint_path=checkpoint_path,
|
|
279
|
+
artifact_path=artifact_dir,
|
|
280
|
+
),
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
assert result.status == "committed"
|
|
284
|
+
assert load_checkpoint_state(
|
|
285
|
+
checkpoint_path,
|
|
286
|
+
project_root=tmp_path,
|
|
287
|
+
).semantic_complete is True
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def test_runtime_prepare_does_not_override_terminal_commit_block(tmp_path):
|
|
291
|
+
base_head = _init_repo(tmp_path)
|
|
292
|
+
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
293
|
+
_rewind_to_ai_request_ready(checkpoint_path)
|
|
294
|
+
checkpoint = json.loads(checkpoint_path.read_text(encoding="utf-8"))
|
|
295
|
+
committer = next(
|
|
296
|
+
step for step in checkpoint["steps"]
|
|
297
|
+
if step["skill"] == "prizmkit-committer"
|
|
298
|
+
)
|
|
299
|
+
committer["status"] = "failed"
|
|
300
|
+
committer["stage_result"] = "COMMIT_BLOCKED"
|
|
301
|
+
checkpoint["feature_state"].update(
|
|
302
|
+
{
|
|
303
|
+
"status": "failed",
|
|
304
|
+
"stage_result": "COMMIT_BLOCKED",
|
|
305
|
+
"current_stage": None,
|
|
306
|
+
"next_stage": None,
|
|
307
|
+
"blocked_reason": "commit_blocked",
|
|
308
|
+
"terminal_status": "WORKFLOW_BLOCKED",
|
|
309
|
+
}
|
|
310
|
+
)
|
|
311
|
+
checkpoint_path.write_text(json.dumps(checkpoint), encoding="utf-8")
|
|
312
|
+
_write_request(tmp_path, artifact_dir, base_head)
|
|
313
|
+
|
|
314
|
+
result = prepare_runtime_commit_handoff(
|
|
315
|
+
tmp_path,
|
|
316
|
+
artifact_dir=artifact_dir,
|
|
317
|
+
checkpoint_path=checkpoint_path,
|
|
318
|
+
)
|
|
319
|
+
|
|
320
|
+
assert result.status == "not_ready"
|
|
321
|
+
assert result.reason == "workflow_checkpoint_blocked"
|
|
322
|
+
persisted = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
|
|
323
|
+
assert persisted.semantic_blocked is True
|
|
324
|
+
assert _git(tmp_path, "rev-parse", "HEAD") == base_head
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def test_runtime_prepare_rejects_stale_request_without_publishing_pending(tmp_path):
|
|
328
|
+
base_head = _init_repo(tmp_path)
|
|
329
|
+
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
330
|
+
_rewind_to_ai_request_ready(checkpoint_path)
|
|
331
|
+
_write_request(tmp_path, artifact_dir, "a" * 40)
|
|
332
|
+
|
|
333
|
+
result = prepare_runtime_commit_handoff(
|
|
334
|
+
tmp_path,
|
|
335
|
+
artifact_dir=artifact_dir,
|
|
336
|
+
checkpoint_path=checkpoint_path,
|
|
337
|
+
)
|
|
338
|
+
|
|
339
|
+
assert result.status == "failed"
|
|
340
|
+
assert result.reason == "base_head_mismatch"
|
|
341
|
+
state = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
|
|
342
|
+
assert state.semantic_commit_ready is False
|
|
343
|
+
assert state.current_step is not None
|
|
344
|
+
assert state.current_step.stage_result is None
|
|
345
|
+
assert _git(tmp_path, "rev-parse", "HEAD") == base_head
|
|
346
|
+
|
|
347
|
+
|
|
193
348
|
def test_runtime_commit_executes_complete_workspace_and_finalizes_only_checkpoint(tmp_path):
|
|
194
349
|
base_head = _init_repo(tmp_path)
|
|
195
350
|
artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
|
|
@@ -10,9 +10,9 @@ For a formal requirement:
|
|
|
10
10
|
1. Complete `/prizmkit-retrospective` after Test and before Committer; it synchronizes durable documentation or records `NO_DOC_CHANGE` but never stages or commits.
|
|
11
11
|
2. Use `/prizmkit-committer` for one local commit operation and one truthful Conventional Commit message.
|
|
12
12
|
3. The commit candidate is the complete current Git-visible workspace: staged, unstaged, added, deleted, renamed, copied, and non-ignored untracked content, regardless of when or where each valid change originated.
|
|
13
|
-
4. Final Code Review and Test authority must cover every behavior-affecting candidate. Committer inspects the complete final workspace, blocks stale or unsafe evidence,
|
|
14
|
-
5.
|
|
13
|
+
4. Final Code Review and Test authority must cover every behavior-affecting candidate. Committer inspects the complete final workspace, blocks stale or unsafe evidence, reports every visible change and message, and continues without an additional confirmation pause.
|
|
14
|
+
5. Direct Committer revalidates and stages the complete workspace automatically. Explicit Runtime preparation writes a schema-v2 pathless request and stops; Python Runtime validates that request, atomically publishes `COMMIT_PENDING`, and re-enumerates and stages the complete validated workspace.
|
|
15
15
|
6. Ignored paths remain local, never block, and are never force-added. Path provenance or namespace alone never admits or excludes content.
|
|
16
|
-
7. Merge conflicts, Secrets, sensitive local content, known incorrect or incoherent changes, and unverifiable content still block. Only the exact active
|
|
16
|
+
7. Merge conflicts, Secrets, sensitive local content, known incorrect or incoherent changes, and unverifiable content still block. Only the exact active direct-workflow state or Runtime request/checkpoint and post-commit receipt writes may remain outside the snapshot because their causal finalization follows the commit.
|
|
17
17
|
8. Runtime verifies the base, parent, message, non-empty commit, recovery receipt, and checkpoint finalization before integration.
|
|
18
18
|
9. Remote publication and deployment remain separate.
|
|
@@ -40,7 +40,7 @@ This skill is PLANNING ONLY. It may create, append, validate, and review bug pla
|
|
|
40
40
|
|
|
41
41
|
Your ONLY writable outputs are:
|
|
42
42
|
1. `.prizmkit/plans/bug-fix-list.json`
|
|
43
|
-
2.
|
|
43
|
+
2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `bug-fix-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
|
|
44
44
|
|
|
45
45
|
After planning is complete, you MUST:
|
|
46
46
|
1. Present the summary and recommended next step (invoking `bugfix-pipeline-launcher`)
|
|
@@ -49,6 +49,10 @@ After planning is complete, you MUST:
|
|
|
49
49
|
4. NEVER auto-execute the pipeline, launcher, composite workflow, or any fix step
|
|
50
50
|
5. Return the validated bug list to the caller; only `bugfix-pipeline-launcher` prepares the runtime command
|
|
51
51
|
|
|
52
|
+
## Draft Lifecycle (Hard Rule)
|
|
53
|
+
|
|
54
|
+
In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result only after cleanup succeeds or a retained recovery reason is surfaced. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
|
|
55
|
+
|
|
52
56
|
## Fresh-Session Task Contract (Hard Rule)
|
|
53
57
|
|
|
54
58
|
Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
@@ -161,8 +165,8 @@ For any content-generating flow that appends to an existing `.prizmkit/plans/bug
|
|
|
161
165
|
2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
162
166
|
3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to B-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
163
167
|
4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`.
|
|
164
|
-
5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
|
|
165
|
-
6.
|
|
168
|
+
5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. This bounded draft is internal transport/recovery state, not a user approval artifact. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
|
|
169
|
+
6. After consequential decisions and the pre-generation gate pass, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the new-list/full-rewrite path.
|
|
166
170
|
## Scenario Routing
|
|
167
171
|
|
|
168
172
|
Classify user intent first:
|
|
@@ -319,18 +323,18 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
|
|
|
319
323
|
|
|
320
324
|
**Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
|
|
321
325
|
|
|
322
|
-
For any items that need attention, ask targeted questions to fill gaps. Iterate until
|
|
326
|
+
For any items that need attention, ask targeted questions to fill consequential gaps. Iterate until every flagged semantic gap is resolved. Present the prompt:
|
|
323
327
|
|
|
324
328
|
> "Above is the completeness review. Every `NEEDS_FIXES` item must be clarified before generation. Which flagged item should we address first?"
|
|
325
329
|
|
|
326
|
-
For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the artifact-alone questions
|
|
330
|
+
For every `NEEDS_FIXES` result, ask only for the consequential missing decision, update the draft/source bug contract, and rerun the artifact-alone questions until all new or changed bugs return `PASS`. Then proceed directly to Phase 5; do not add a separate approval merely to write the already-confirmed content.
|
|
327
331
|
|
|
328
332
|
**Gate → CP-BP-4**: All new or changed bugs pass the Headless Context Completeness Gate without relying on conversation history or `user_context`.
|
|
329
333
|
|
|
330
334
|
### Phase 5: Generate & Validate
|
|
331
335
|
|
|
332
|
-
1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object.
|
|
333
|
-
2. **Generate or append and validate
|
|
336
|
+
1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object as internal transport/recovery state.
|
|
337
|
+
2. **Generate or append immediately and validate** — once required semantic gates pass, invoke the matching writer without a second draft-approval pause:
|
|
334
338
|
- New list or explicit full-list rewrite:
|
|
335
339
|
```bash
|
|
336
340
|
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
@@ -342,28 +346,21 @@ For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the
|
|
|
342
346
|
`generate` fills root defaults for a complete draft. `append` preserves root metadata and historical bugs, defaults missing new statuses, and writes only after the merged full list validates.
|
|
343
347
|
3. **If validation fails**: Fix the draft and retry (max 3 attempts). If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
|
|
344
348
|
4. **Run the mandatory Local Generated-Plan Review Gate** (see §Local Generated-Plan Review Gate below): load `${SKILL_DIR}/references/generated-plan-review.md` and review only newly added/changed bug entries after validation passes and before success output.
|
|
345
|
-
5. **
|
|
349
|
+
5. **Complete cleanup and output**: After local review returns `PASS` and final validation passes, follow §Draft Lifecycle, then report the file path, summary, local review, validation, cleanup result, and next steps.
|
|
346
350
|
|
|
347
351
|
**Gate → CP-BP-5**: `bug-fix-list.json` passes validation script with zero errors.
|
|
348
352
|
|
|
349
|
-
**Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, and
|
|
353
|
+
**Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained.
|
|
350
354
|
|
|
351
355
|
## Local Generated-Plan Review Gate
|
|
352
356
|
|
|
353
357
|
Run this gate after `.prizmkit/plans/bug-fix-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final bug entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
354
358
|
|
|
355
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation,
|
|
359
|
+
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
|
|
356
360
|
|
|
357
361
|
#### Success Output
|
|
358
362
|
|
|
359
|
-
|
|
360
|
-
.prizmkit/plans/bug-fix-list.json generated with 3 bugs (1 critical, 1 medium, 1 low)
|
|
361
|
-
Local generated-plan review: PASS, reviewed B-001..B-003, accepted fixes: none, final validation: PASS
|
|
362
|
-
|
|
363
|
-
Next steps:
|
|
364
|
-
- Review: cat .prizmkit/plans/bug-fix-list.json
|
|
365
|
-
- Start fixing: say "start fixing" to launch the bugfix pipeline via bugfix-pipeline-launcher
|
|
366
|
-
```
|
|
363
|
+
Report the final path and bug counts, Local Generated-Plan Review verdict and reviewed IDs, accepted fixes, final validation result, draft cleanup result, and `bugfix-pipeline-launcher` handoff.
|
|
367
364
|
|
|
368
365
|
### Checkpoints (Mandatory Gates)
|
|
369
366
|
|
|
@@ -376,7 +373,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
376
373
|
| **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
|
|
377
374
|
| **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
|
|
378
375
|
| **CP-BP-5** | File Generated | `bug-fix-list.json` passes validation script | 5 |
|
|
379
|
-
| **CP-BP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, and
|
|
376
|
+
| **CP-BP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 5 |
|
|
380
377
|
|
|
381
378
|
**Resume Detection**: If existing `.prizmkit/plans/bug-fix-list.json` or draft found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
|
|
382
379
|
|
|
@@ -386,7 +383,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
386
383
|
|
|
387
384
|
Triggers: "parse this error log", "here's a stack trace", "parse these errors".
|
|
388
385
|
|
|
389
|
-
Batch-parse error logs with minimal interaction: parse automatically,
|
|
386
|
+
Batch-parse error logs with minimal interaction: parse automatically, resolve consequential gaps through targeted questions, then write the final list immediately:
|
|
390
387
|
|
|
391
388
|
1. Accept log file path or piped content
|
|
392
389
|
2. Parse all unique errors (deduplicate by error message pattern)
|
|
@@ -397,11 +394,10 @@ Batch-parse error logs with minimal interaction: parse automatically, then requi
|
|
|
397
394
|
- error_source: populated from log content
|
|
398
395
|
- verification_type: default to `automated`
|
|
399
396
|
- acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
|
|
400
|
-
4. Write
|
|
397
|
+
4. Write `.prizmkit/plans/bug-fix-list.draft.json` as internal transport/recovery state.
|
|
401
398
|
5. Run the Phase 4 Headless Context Completeness Gate on every parsed bug. Ask targeted clarification for missing expected behavior, selected scope, severity rationale, or verification decisions; update the draft until all entries pass.
|
|
402
|
-
6.
|
|
403
|
-
7.
|
|
404
|
-
8. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
|
|
399
|
+
6. Immediately use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
|
|
400
|
+
7. If validation passes, run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
|
|
405
401
|
|
|
406
402
|
## Operation: From Tests
|
|
407
403
|
|
|
@@ -413,11 +409,10 @@ Batch-parse failed test output:
|
|
|
413
409
|
2. Parse each failed test case as a separate bug entry
|
|
414
410
|
3. Auto-populate `failed_test_path`, `error_message`
|
|
415
411
|
4. Set verification_type to `automated` (test already exists)
|
|
416
|
-
5. Write
|
|
417
|
-
6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug;
|
|
418
|
-
7.
|
|
419
|
-
8.
|
|
420
|
-
9. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
|
|
412
|
+
5. Write `.prizmkit/plans/bug-fix-list.draft.json` as internal transport/recovery state.
|
|
413
|
+
6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ask only for consequential missing expected behavior or scope, and allow needed edits, merges, or removals until all entries pass.
|
|
414
|
+
7. Immediately use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
|
|
415
|
+
8. If validation passes, run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
|
|
421
416
|
|
|
422
417
|
## Operation: Validate
|
|
423
418
|
|
|
@@ -470,8 +465,9 @@ Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeli
|
|
|
470
465
|
After `.prizmkit/plans/bug-fix-list.json` is generated, validated, and reviewed, present:
|
|
471
466
|
1. Summary of generated bugs (count, severity breakdown)
|
|
472
467
|
2. Local generated-plan review result: verdict, reviewed bug IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
|
|
473
|
-
3.
|
|
474
|
-
4.
|
|
468
|
+
3. Draft cleanup result: `removed`, or retained path and recovery reason
|
|
469
|
+
4. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
|
|
470
|
+
5. Alternative: fix a single bug interactively via `bug-fix-workflow`
|
|
475
471
|
|
|
476
472
|
## Error Handling
|
|
477
473
|
|
|
@@ -7,22 +7,22 @@ Reference document for bug-planner error handling and session recovery. Load thi
|
|
|
7
7
|
### Warnings Only
|
|
8
8
|
|
|
9
9
|
If `validate-bug-list.py` returns warnings but no errors:
|
|
10
|
-
1. Present warnings
|
|
11
|
-
2.
|
|
12
|
-
3.
|
|
13
|
-
4.
|
|
10
|
+
1. Present the warnings
|
|
11
|
+
2. Continue the deterministic writer/review flow when they are informational
|
|
12
|
+
3. Ask the user only when a warning exposes a consequential behavior, scope, severity, or verification decision
|
|
13
|
+
4. Apply any confirmed correction to the planner-owned draft and re-run the matching writer; do not add a generic draft-promotion approval
|
|
14
14
|
|
|
15
15
|
### Errors Found
|
|
16
16
|
|
|
17
17
|
If validation returns errors:
|
|
18
18
|
1. Group errors by type (missing fields, invalid values, duplicate IDs, broken references)
|
|
19
|
-
2.
|
|
19
|
+
2. Apply unambiguous mechanical fixes to the planner-owned draft where possible:
|
|
20
20
|
- Missing `status` → set to `pending`
|
|
21
21
|
- Duplicate IDs → re-number with next sequential B-NNN
|
|
22
|
-
- Invalid `priority` → re-derive from severity using the mapping table
|
|
23
|
-
3.
|
|
24
|
-
4. Re-
|
|
25
|
-
5. Maximum 3 total validation attempts — if still failing after 3 rounds, present the raw errors and ask user for guidance
|
|
22
|
+
- Invalid `priority` → re-derive from the already confirmed severity using the mapping table
|
|
23
|
+
3. Ask only when a correction changes confirmed behavior, scope, severity, verification, or dependency semantics
|
|
24
|
+
4. Re-run the matching writer and validation after fixes
|
|
25
|
+
5. Maximum 3 total validation attempts — if still failing after 3 rounds, retain the draft, present the raw errors, and ask user for guidance
|
|
26
26
|
|
|
27
27
|
### JSON Parse Failure
|
|
28
28
|
|
|
@@ -39,22 +39,21 @@ When bug-planner detects existing artifacts, determine the last completed checkp
|
|
|
39
39
|
|
|
40
40
|
| Existing Artifact | Last Checkpoint | Resume From |
|
|
41
41
|
|---|---|---|
|
|
42
|
-
| `.prizmkit/plans/bug-fix-list.json` (valid) | CP-BP-
|
|
43
|
-
| `.prizmkit/plans/bug-fix-list.json` (invalid) | CP-BP-4 |
|
|
44
|
-
| `.prizmkit/plans/bug-fix-list.draft.json` | CP-BP-2
|
|
42
|
+
| `.prizmkit/plans/bug-fix-list.json` (valid), no draft | CP-BP-6 | Offer: "Valid bug list exists. Append new bugs (Route B) or regenerate?" |
|
|
43
|
+
| `.prizmkit/plans/bug-fix-list.json` (invalid) | CP-BP-4 | Resume Phase 5 repair through the source draft |
|
|
44
|
+
| `.prizmkit/plans/bug-fix-list.draft.json` only | CP-BP-2 through CP-BP-5 | Load draft, determine phase from actual completeness, resume |
|
|
45
|
+
| Valid final plus `.prizmkit/plans/bug-fix-list.draft.json` | CP-BP-5 or cleanup failure | Treat as interrupted review or cleanup-failure state; inspect and offer resume review, discard, or a new append rather than assuming either artifact wins |
|
|
45
46
|
| `.prizmkit/config.json` with tech_stack | CP-BP-1 (partial) | Skip project context questions, start at Phase 2 |
|
|
46
47
|
| No artifacts | — | Start from Phase 1 |
|
|
47
48
|
|
|
48
49
|
### Resume Detection Flow
|
|
49
50
|
|
|
50
|
-
1. Check for `.prizmkit/plans/bug-fix-list.json`
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
- If exists with tech_stack → skip Phase 1 context gathering
|
|
57
|
-
4. If no artifacts → start fresh (Route A)
|
|
51
|
+
1. Check for both `.prizmkit/plans/bug-fix-list.json` and `.prizmkit/plans/bug-fix-list.draft.json` before choosing a route.
|
|
52
|
+
2. If both exist, validate the final and inspect the draft's actual completeness. Resume unfinished review/recovery or discard the draft only after its state is understood; ask the user if session evidence cannot distinguish interruption from cleanup failure.
|
|
53
|
+
3. If only the final exists, offer Route B for a valid list or resume writer/validation repair for an invalid list.
|
|
54
|
+
4. If only the draft exists, load it, determine which semantic and validation gates remain, and resume there.
|
|
55
|
+
5. Check `.prizmkit/config.json`; if it contains `tech_stack`, skip Phase 1 context gathering.
|
|
56
|
+
6. If no artifacts exist, start fresh (Route A).
|
|
58
57
|
|
|
59
58
|
### Session Interruption Recovery
|
|
60
59
|
|
|
@@ -67,7 +66,8 @@ If a bug-planner session is interrupted mid-planning:
|
|
|
67
66
|
|
|
68
67
|
## Draft Management
|
|
69
68
|
|
|
70
|
-
-
|
|
71
|
-
-
|
|
72
|
-
-
|
|
73
|
-
-
|
|
69
|
+
- Use one planner-owned `.prizmkit/plans/bug-fix-list.draft.json`. In an ordinary writer flow it must be either a complete new-list source or a complete additions-only object; an explicitly saved pre-generation recovery draft may be incomplete and must not enter `generate` or `append` until the semantic gates and required shape pass.
|
|
70
|
+
- Keep the ordinary draft through generation/append, validation, and the complete Local Generated-Plan Review fix loop. Generation success alone is not a cleanup boundary because review repairs still use the draft as source.
|
|
71
|
+
- After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
|
|
72
|
+
- Retain a draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason. Cleanup failure leaves a reviewed final list valid but must be reported as stale recovery state.
|
|
73
|
+
- Keep at most one active draft. Do not archive or duplicate an ambiguous draft until the user chooses to discard or preserve it.
|
|
@@ -6,6 +6,8 @@ Use this local review loop after `.prizmkit/plans/bug-fix-list.json` has been ge
|
|
|
6
6
|
|
|
7
7
|
Run only when the current `bug-planner` session generated, appended, or rewrote final bug planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
|
|
8
8
|
|
|
9
|
+
In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
|
|
10
|
+
|
|
9
11
|
## Direct Artifact Reads
|
|
10
12
|
|
|
11
13
|
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
@@ -89,9 +91,10 @@ For a new list or explicit full-list rewrite, regenerate through the existing sc
|
|
|
89
91
|
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth.
|
|
94
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
93
95
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
94
96
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
97
|
+
8. After `PASS`, delete `.prizmkit/plans/bug-fix-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
|
|
95
98
|
|
|
96
99
|
## Report Format
|
|
97
100
|
|
|
@@ -101,4 +104,5 @@ Report in the final handoff summary:
|
|
|
101
104
|
- Reviewed bug IDs and reviewed root prose (`project_description` / `global_context`) when applicable
|
|
102
105
|
- Accepted fixes, or `none`
|
|
103
106
|
- Final validation result
|
|
107
|
+
- Draft cleanup result: `removed`, or retained path and recovery reason
|
|
104
108
|
- Note when review was not applicable because no new final planning content was written
|
|
@@ -48,7 +48,7 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
48
48
|
|
|
49
49
|
**Your ONLY writable outputs are:**
|
|
50
50
|
1. `.prizmkit/plans/feature-list.json` (`.prizmkit/plans/`)
|
|
51
|
-
2.
|
|
51
|
+
2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `feature-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
|
|
52
52
|
|
|
53
53
|
**After planning is complete**, you MUST:
|
|
54
54
|
1. Present the summary and recommended next step (invoking `feature-pipeline-launcher` )
|
|
@@ -57,6 +57,10 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
57
57
|
4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
|
|
58
58
|
5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
|
|
59
59
|
|
|
60
|
+
## Draft Lifecycle (Hard Rule)
|
|
61
|
+
|
|
62
|
+
In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
|
|
63
|
+
|
|
60
64
|
## Fresh-Session Task Contract (Hard Rule)
|
|
61
65
|
|
|
62
66
|
Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
@@ -238,8 +242,8 @@ For ordinary incremental planning, NEVER read the complete existing `.prizmkit/p
|
|
|
238
242
|
2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
239
243
|
3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to F-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
240
244
|
4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`.
|
|
241
|
-
5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
|
|
242
|
-
6.
|
|
245
|
+
5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. This bounded draft is internal transport/recovery state, not a user approval artifact. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
|
|
246
|
+
6. After consequential decisions and the pre-generation gate pass, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the initial-plan/full-rewrite path.
|
|
243
247
|
## Scenario Routing
|
|
244
248
|
Classify user intent first:
|
|
245
249
|
|
|
@@ -310,8 +314,8 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
|
|
|
310
314
|
7. Build or append `.prizmkit/plans/feature-list.json`
|
|
311
315
|
8. Apply default testing strategy (see §Testing Defaults below)
|
|
312
316
|
9. Validate and fix until pass
|
|
313
|
-
10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
|
|
314
|
-
11. Summarize final feature table with local review result and
|
|
317
|
+
10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass, then complete §Draft Lifecycle cleanup
|
|
318
|
+
11. Summarize final feature table with local review result, validation outcome, and draft cleanup result
|
|
315
319
|
|
|
316
320
|
### Checkpoints (Mandatory Gates)
|
|
317
321
|
|
|
@@ -327,7 +331,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
327
331
|
| **CP-FP-3.3** | Completeness Review Passed | Every new or changed feature passes fresh-session simulation from `description` and `acceptance_criteria` without conversation history or `user_context` | 6 |
|
|
328
332
|
| **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
|
|
329
333
|
| **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
|
|
330
|
-
| **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, and
|
|
334
|
+
| **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 10-11 |
|
|
331
335
|
|
|
332
336
|
**Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
|
|
333
337
|
|
|
@@ -374,11 +378,11 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
374
378
|
3. Generate next sequential feature IDs
|
|
375
379
|
4. Draft features (title + description + acceptance_criteria + dependencies)
|
|
376
380
|
5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
|
|
377
|
-
6. Write
|
|
381
|
+
6. Write the additions-only draft as internal input and immediately call the append command without a second draft-approval pause:
|
|
378
382
|
```bash
|
|
379
383
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
380
384
|
```
|
|
381
|
-
7. If valid → run the mandatory Local Generated-Plan Review Gate, then
|
|
385
|
+
7. If valid → run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
|
|
382
386
|
8. If invalid → apply fixes to the additions-only draft, re-run `append` (max 2 attempts, then escalate to full workflow)
|
|
383
387
|
|
|
384
388
|
## Browser Interaction Planning
|
|
@@ -429,13 +433,13 @@ Key requirements:
|
|
|
429
433
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
430
434
|
```
|
|
431
435
|
|
|
432
|
-
`generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. If either command fails, fix its source draft and retry.
|
|
436
|
+
`generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. In ordinary incremental flow, call `append` immediately after semantic gates; the draft is not a second approval checkpoint. If either command fails, fix its source draft and retry. Do not delete the draft until the Local Generated-Plan Review and final validation pass; then follow §Draft Lifecycle.
|
|
433
437
|
|
|
434
438
|
## Local Generated-Plan Review Gate
|
|
435
439
|
|
|
436
440
|
Run this gate after `.prizmkit/plans/feature-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final feature entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
437
441
|
|
|
438
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation,
|
|
442
|
+
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat the local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
|
|
439
443
|
|
|
440
444
|
## Testing Defaults (Phase 8)
|
|
441
445
|
|
|
@@ -459,11 +463,7 @@ Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-p
|
|
|
459
463
|
|
|
460
464
|
If validation fails or a session is interrupted → read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
|
|
461
465
|
|
|
462
|
-
Key behaviors:
|
|
463
|
-
- Warnings only → proceed with user approval
|
|
464
|
-
- Critical errors → group by type, auto-fix where possible, max 3 total attempts
|
|
465
|
-
- Interrupted session → detect checkpoint from existing artifacts, offer resume or restart
|
|
466
|
-
- `.prizmkit/plans/feature-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/feature-list.json`)
|
|
466
|
+
Key behaviors: continue informational warnings without a draft-promotion pause; clarify consequential warnings; group critical errors and retry safe fixes at most three times; resume interrupted state from actual artifacts; always write the final list at project-root `.prizmkit/plans/feature-list.json`.
|
|
467
467
|
|
|
468
468
|
## Session Exit Gate
|
|
469
469
|
|
|
@@ -480,7 +480,7 @@ When the session appears to be ending:
|
|
|
480
480
|
1. **Remind**: "You set out to produce `.prizmkit/plans/feature-list.json` but we haven't completed it yet."
|
|
481
481
|
2. Use `AskUserQuestion` with one question:
|
|
482
482
|
- **Continue to completion (Recommended)** — resume from current phase
|
|
483
|
-
- **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json`
|
|
483
|
+
- **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json` and retain it as explicit recovery state; terminal cleanup does not apply until planning resumes and completes
|
|
484
484
|
- **Abandon** — exit without saving
|
|
485
485
|
|
|
486
486
|
## Handoff Message Template
|
|
@@ -489,7 +489,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
|
|
|
489
489
|
1. Output file path
|
|
490
490
|
2. Total features + newly added features
|
|
491
491
|
3. Dependency and priority highlights
|
|
492
|
-
4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"),
|
|
492
|
+
4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), final validation result, and draft cleanup result (`removed` or retained path/reason)
|
|
493
493
|
5. Recommended next action: `feature-pipeline-launcher`
|
|
494
494
|
|
|
495
495
|
Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
|