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,8 +12,8 @@ Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]
|
|
|
12
12
|
### Decision Tree
|
|
13
13
|
|
|
14
14
|
**if `error_count == 0` (warnings only):**
|
|
15
|
-
-
|
|
16
|
-
-
|
|
15
|
+
- Continue the deterministic writer/review flow when warnings are informational
|
|
16
|
+
- Ask the user only when a warning exposes a consequential product, scope, compatibility, or verification decision; do not add a generic draft-promotion approval
|
|
17
17
|
|
|
18
18
|
**elif `error_count > 0` (critical errors):**
|
|
19
19
|
|
|
@@ -34,15 +34,14 @@ Group errors by type and apply targeted fixes:
|
|
|
34
34
|
```
|
|
35
35
|
For auto-fixable errors:
|
|
36
36
|
1. Show summary: "Found N schema/ID/format issues"
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
5. If new errors → loop (max 2 more attempts)
|
|
37
|
+
2. Apply unambiguous mechanical fixes to the planner-owned draft
|
|
38
|
+
3. Re-run the matching deterministic writer and validation
|
|
39
|
+
4. If new errors → loop (max 2 more attempts)
|
|
41
40
|
|
|
42
|
-
For
|
|
43
|
-
1.
|
|
44
|
-
2.
|
|
45
|
-
3.
|
|
41
|
+
For semantic fixes (dependencies, acceptance-criteria content):
|
|
42
|
+
1. Ask only for the consequential missing decision
|
|
43
|
+
2. Apply the confirmed correction to the planner-owned draft, never directly to the final list
|
|
44
|
+
3. Re-run the matching writer and validation (max 2 more attempts)
|
|
46
45
|
|
|
47
46
|
if all_retries_exceeded:
|
|
48
47
|
→ Escalate: "After 3 attempts, validation still fails.
|
|
@@ -61,13 +60,16 @@ Check for artifact files in `.prizmkit/plans/`:
|
|
|
61
60
|
| Artifacts Found | Resume Action |
|
|
62
61
|
|-----------------|---------------|
|
|
63
62
|
| None | Start fresh planning (Phase 1) |
|
|
64
|
-
| `feature-list.json` exists but not validated |
|
|
65
|
-
| `feature-list.json`
|
|
66
|
-
| `feature-list.draft.json` only | Resume interactive planning from
|
|
63
|
+
| `feature-list.json` exists but not validated | Resume writer/validation repair through the source draft |
|
|
64
|
+
| Valid `feature-list.json` only | Offer handoff to `feature-pipeline-launcher` |
|
|
65
|
+
| `feature-list.draft.json` only | Resume interactive planning from the draft's actual completeness |
|
|
66
|
+
| Valid `feature-list.json` plus `feature-list.draft.json` | Treat as interrupted review or cleanup-failure state; inspect the draft and offer to resume review, discard it, or start a new increment rather than assuming either artifact wins |
|
|
67
67
|
|
|
68
|
-
When
|
|
68
|
+
When only a valid final list is detected, suggest:
|
|
69
69
|
> "Existing plan found with N features. Resume incremental planning? (Y/n)"
|
|
70
70
|
|
|
71
|
+
When final and draft both exist, identify the two artifacts explicitly and ask whether to resume the unfinished review/recovery state or discard it before starting a new increment.
|
|
72
|
+
|
|
71
73
|
### Incremental Mode Abort
|
|
72
74
|
|
|
73
75
|
If in Incremental mode but existing `feature-list.json` not found:
|
|
@@ -84,8 +86,16 @@ Before writing, verify the directory exists: `mkdir -p .prizmkit/plans`
|
|
|
84
86
|
<project-root>/
|
|
85
87
|
└── .prizmkit/plans/
|
|
86
88
|
├── feature-list.json # Primary output
|
|
87
|
-
├── feature-list.draft.json #
|
|
89
|
+
├── feature-list.draft.json # Temporary writer/review input or explicit recovery state
|
|
88
90
|
└── <ISO-timestamp>.backup.json # Optional incremental backups
|
|
89
91
|
```
|
|
90
92
|
|
|
93
|
+
## Draft Management
|
|
94
|
+
|
|
95
|
+
- An ordinary writer draft must remain available while generation, append, validation, or Local Generated-Plan Review repair is incomplete.
|
|
96
|
+
- After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
|
|
97
|
+
- Retain a draft only after explicit **Save draft & exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
|
|
98
|
+
- Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
|
|
99
|
+
- If both final and draft exist on resume, do not delete or promote the draft blindly. Determine whether review was interrupted or cleanup failed from the artifacts and available session evidence; ask the user when that outcome remains ambiguous.
|
|
100
|
+
|
|
91
101
|
> **Note**: For cross-session workflow recovery (e.g., interrupted pipeline execution, branch-level state detection), use `recovery-workflow` instead. This error-recovery reference handles only within-session validation retries and checkpoint resumption.
|
|
@@ -6,6 +6,8 @@ Use this local review loop after `.prizmkit/plans/feature-list.json` has been ge
|
|
|
6
6
|
|
|
7
7
|
Run only when the current `feature-planner` session generated, appended, or rewrote final feature 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:
|
|
@@ -90,9 +92,10 @@ For an initial plan or explicit full-list rewrite, regenerate through the existi
|
|
|
90
92
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
91
93
|
```
|
|
92
94
|
|
|
93
|
-
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth.
|
|
95
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
94
96
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
95
97
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
98
|
+
8. After `PASS`, delete `.prizmkit/plans/feature-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.
|
|
96
99
|
|
|
97
100
|
## Report Format
|
|
98
101
|
|
|
@@ -102,4 +105,5 @@ Report in the final handoff summary:
|
|
|
102
105
|
- Reviewed feature IDs and reviewed root prose (`project_description` / `global_context`) when applicable
|
|
103
106
|
- Accepted fixes, or `none`
|
|
104
107
|
- Final validation result
|
|
108
|
+
- Draft cleanup result: `removed`, or retained path and recovery reason
|
|
105
109
|
- Note when review was not applicable because no new final planning content was written
|
|
@@ -81,7 +81,7 @@ The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one roo
|
|
|
81
81
|
}
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
-
Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft.
|
|
84
|
+
Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft. Treat it as internal transport/recovery state, not as a user approval artifact.
|
|
85
85
|
|
|
86
86
|
### Step 4: Rebalance Priority
|
|
87
87
|
|
|
@@ -89,13 +89,13 @@ Default to append only. Reprioritizing historical tasks is an explicit old-task
|
|
|
89
89
|
|
|
90
90
|
### Step 5: Append and Validate
|
|
91
91
|
|
|
92
|
-
|
|
92
|
+
After consequential decisions and the pre-generation semantic gate pass, immediately merge the additions-only draft with untouched history outside AI context:
|
|
93
93
|
|
|
94
94
|
```bash
|
|
95
95
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
96
96
|
```
|
|
97
97
|
|
|
98
|
-
The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list.
|
|
98
|
+
The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Do not ask for separate user approval merely to promote the additions draft into the final list. Fix invalid additions and rerun until valid; during local review, correct the exact current suffix with `append --replace-tail`. Keep the draft through that fix loop. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. For a later adjustment, recreate only the exact current additions from confirmed in-memory entries or explicit-ID `show` results before using `append --replace-tail`. Use `generate` only for an initial plan or an explicit full-list rewrite.
|
|
99
99
|
|
|
100
100
|
## Merge/Rewrite Rules
|
|
101
101
|
|
|
@@ -120,6 +120,8 @@ Use concise prompts during interaction:
|
|
|
120
120
|
- [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
|
|
121
121
|
- [ ] Old dependency IDs represent real execution prerequisites
|
|
122
122
|
- [ ] Additions-only draft contains no root metadata or historical features
|
|
123
|
+
- [ ] Atomic append ran immediately after semantic gates without a post-draft approval pause
|
|
123
124
|
- [ ] Existing project conventions preserved from project evidence
|
|
124
125
|
- [ ] Complete merged dependency graph validates through `append`
|
|
126
|
+
- [ ] Ordinary internal draft was deleted after review and final validation, or its retained recovery path and reason were reported
|
|
125
127
|
- [ ] Next step recommendation: `feature-pipeline-launcher`
|
|
@@ -53,12 +53,14 @@ Split into `sub_features` when:
|
|
|
53
53
|
|
|
54
54
|
### Phase 6: Generate + Validate
|
|
55
55
|
|
|
56
|
-
1. Write `.prizmkit/plans/feature-list.draft.json
|
|
57
|
-
2.
|
|
56
|
+
1. Write `.prizmkit/plans/feature-list.draft.json` as internal writer/review input after the main Skill's consequential decision and pre-generation gates pass.
|
|
57
|
+
2. Immediately generate the final file without a separate draft-approval pause:
|
|
58
58
|
```bash
|
|
59
59
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
60
60
|
```
|
|
61
|
-
3. Fix draft errors, then re-run generate.
|
|
61
|
+
3. Fix draft errors, then re-run `generate` until validation passes.
|
|
62
|
+
4. Run the main Skill's mandatory Local Generated-Plan Review and apply accepted fixes through the complete draft.
|
|
63
|
+
5. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Retain it only under the main Skill's explicit recovery conditions and report the reason.
|
|
62
64
|
|
|
63
65
|
## Quality Rules
|
|
64
66
|
|
|
@@ -77,5 +79,6 @@ Split into `sub_features` when:
|
|
|
77
79
|
- [ ] User confirmed initial feature scope
|
|
78
80
|
- [ ] IDs are sequential
|
|
79
81
|
- [ ] `status` initialized to `pending`
|
|
80
|
-
- [ ] Validation
|
|
82
|
+
- [ ] Validation and Local Generated-Plan Review pass
|
|
83
|
+
- [ ] Ordinary internal draft was deleted, or its retained recovery path and reason were reported
|
|
81
84
|
- [ ] Next step recommendation: `feature-pipeline-launcher`
|
|
@@ -74,11 +74,11 @@ Typos, pure formatting, small documentation edits, and other explicitly low-risk
|
|
|
74
74
|
| `prizmkit-code-review` | Review, repair, verify, and converge on the supplied change. | `PASS` |
|
|
75
75
|
| `prizmkit-test` | Test the supplied change with a consistent report/result pair. | `TEST_PASS` |
|
|
76
76
|
| `prizmkit-retrospective` | Synchronize durable documentation or record no change. | `RETRO_COMPLETE` |
|
|
77
|
-
| `prizmkit-committer` |
|
|
77
|
+
| `prizmkit-committer` | Automatically create a validated direct local commit, or explicitly prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
|
|
78
78
|
|
|
79
79
|
### `prizmkit-workflow`
|
|
80
80
|
|
|
81
|
-
Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and
|
|
81
|
+
Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and continues through the validated local commit without another confirmation pause. It handles exactly one requirement per invocation.
|
|
82
82
|
|
|
83
83
|
### `prizmkit-init`
|
|
84
84
|
|
|
@@ -121,7 +121,7 @@ Automatic outer repair is limited to three rounds. The workflow stops with a res
|
|
|
121
121
|
|
|
122
122
|
## Commit and Deployment Boundary
|
|
123
123
|
|
|
124
|
-
The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and
|
|
124
|
+
The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and, for direct execution, only the exact causal bookkeeping path whose finalization must follow the commit. Direct use automatically validates and creates a local commit without another confirmation. Explicit preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
|
|
125
125
|
|
|
126
126
|
Pushing to a remote is a separate explicit action. Deployment is always a separate invocation of `/prizmkit-deploy`.
|
|
127
127
|
|
|
@@ -139,7 +139,7 @@ Then:
|
|
|
139
139
|
1. Optionally run /prizmkit-init when entering a project for the first time.
|
|
140
140
|
2. Start a formal requirement with /prizmkit-plan.
|
|
141
141
|
3. Continue through implement → code-review → test → retrospective → committer.
|
|
142
|
-
4.
|
|
142
|
+
4. Direct `/prizmkit-committer` use validates and creates the local commit automatically; pipeline runtimes keep using explicit preparation mode and execute Git themselves.
|
|
143
143
|
5. Invoke /prizmkit-deploy separately when deployment or operations work is needed.
|
|
144
144
|
```
|
|
145
145
|
|
|
@@ -151,7 +151,7 @@ The toolkit does not promise universal automatic handoff, universal deployment a
|
|
|
151
151
|
|
|
152
152
|
If the user says only "ship it", ask whether they mean:
|
|
153
153
|
|
|
154
|
-
1. Use `/prizmkit-committer operation=interactive-commit` for
|
|
154
|
+
1. Use `/prizmkit-committer operation=interactive-commit` for an automatically validated local commit, or preparation mode when a Python pipeline runtime owns Git execution.
|
|
155
155
|
2. Deploy or operate the project with `/prizmkit-deploy`.
|
|
156
156
|
|
|
157
157
|
Do not route an ambiguous "ship it" directly to either action.
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: "prizmkit-committer"
|
|
3
|
-
description: "Perform one commit stage for a caller-supplied final change.
|
|
3
|
+
description: "Perform one commit stage for a caller-supplied final change. By default, validate and automatically commit the complete Git-visible workspace locally without a confirmation pause. An explicit prepare-runtime-commit operation still writes the pathless Runtime request without Git mutation. Returns only commit-stage results. (project)"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# PrizmKit Committer
|
|
7
7
|
|
|
8
|
-
`/prizmkit-committer` handles one caller-supplied final workspace through one
|
|
8
|
+
`/prizmkit-committer` handles one caller-supplied final workspace through one commit operation:
|
|
9
9
|
|
|
10
|
-
- `operation=interactive-commit`: inspect the complete Git-visible workspace,
|
|
11
|
-
- `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
|
|
10
|
+
- direct/default invocation or `operation=interactive-commit`: inspect the complete Git-visible workspace, report the validated candidate, then stage, commit, and verify it locally without asking for another confirmation;
|
|
11
|
+
- explicit `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
|
|
12
12
|
|
|
13
13
|
Remote publication is outside this Skill.
|
|
14
14
|
|
|
@@ -17,18 +17,18 @@ Remote publication is outside this Skill.
|
|
|
17
17
|
| Parameter | Required | Description |
|
|
18
18
|
|---|---|---|
|
|
19
19
|
| `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
|
|
20
|
-
| `operation` |
|
|
20
|
+
| `operation` | No | Defaults to direct local commit. `interactive-commit` is the compatible explicit name for that behavior; `prepare-runtime-commit` must be supplied explicitly for request-only preparation. |
|
|
21
21
|
| `evidence_paths` | Yes | Exact caller-supplied artifacts that establish final Review/Test/Retrospective readiness. |
|
|
22
|
-
| `causal_bookkeeping_path` |
|
|
22
|
+
| `causal_bookkeeping_path` | Direct-commit conditional | The one exact caller-owned coordinator state whose truthful finalization must follow this commit. It cannot exclude ordinary content. |
|
|
23
23
|
| `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
|
|
24
24
|
|
|
25
|
-
There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or
|
|
25
|
+
There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or choose preparation mode from provider, platform, prompt style, tracking policy, checkout cleanliness, or human availability. Reject any non-empty `operation` value other than `interactive-commit` or `prepare-runtime-commit`. Only explicit `operation=prepare-runtime-commit` selects request-only preparation; an omitted operation or `operation=interactive-commit` uses direct local commit.
|
|
26
26
|
|
|
27
27
|
## Stage Boundary
|
|
28
28
|
|
|
29
|
-
This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content.
|
|
29
|
+
This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content. Each invocation creates at most one local commit and never amends, resets, merges, pushes, opens a pull request, deploys, or publishes.
|
|
30
30
|
|
|
31
|
-
In preparation mode it must not stage, unstage,
|
|
31
|
+
In preparation mode it must not stage, unstage, or commit. It may write only the exact Runtime request after validation succeeds.
|
|
32
32
|
|
|
33
33
|
## Complete Git-Visible Workspace
|
|
34
34
|
|
|
@@ -40,11 +40,11 @@ The candidate commit is the complete current Git-visible workspace:
|
|
|
40
40
|
|
|
41
41
|
Ignored files remain naturally absent, stay local, do not block, and are never force-added. Git visibility is independent of path provenance: product, test, documentation, `.prizmkit`, generated, instruction, lock, host-support, or previously existing content receives no namespace-based admission or exclusion. A non-clean starting checkout is acceptable when the combined final workspace is correct and fully validated.
|
|
42
42
|
|
|
43
|
-
The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied
|
|
43
|
+
The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied direct-commit coordinator-state path, or the automated request/checkpoint and post-commit receipt. This is a causal operation boundary, not a directory allowlist, denylist, or general exclusion mechanism.
|
|
44
44
|
|
|
45
45
|
## Step 1: Validate Evidence and the Complete Final Workspace
|
|
46
46
|
|
|
47
|
-
1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional
|
|
47
|
+
1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional direct-commit `causal_bookkeeping_path`, and preparation `request_path` exactly as supplied. Reject any causal path not proven to be the active caller-owned coordinator state finalized after this operation.
|
|
48
48
|
2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing readiness evidence.
|
|
49
49
|
3. Inventory staged, unstaged, untracked, deleted, renamed, and copied Git-visible files with bounded Git status and diff commands. Do not discover ignored files. Identify only the exact active causal bookkeeping path for the selected operation; every other visible path remains a candidate.
|
|
50
50
|
4. Inspect every candidate path and its relevant diff/content. Correct pre-existing or requirement-adjacent changes may be included even when they were not created in the current implementation session.
|
|
@@ -65,19 +65,16 @@ Generate one concise single-line Conventional Commit message describing the comb
|
|
|
65
65
|
|
|
66
66
|
A heterogeneous but coherent workspace may use the narrowest truthful shared scope and description. If no truthful single commit description exists, block as incoherent content rather than silently omit files.
|
|
67
67
|
|
|
68
|
-
## Step 3A:
|
|
68
|
+
## Step 3A: Direct Local Commit
|
|
69
69
|
|
|
70
|
-
For `operation=interactive-commit`:
|
|
70
|
+
For a default/direct invocation or `operation=interactive-commit`:
|
|
71
71
|
|
|
72
|
-
1.
|
|
73
|
-
2.
|
|
74
|
-
3.
|
|
75
|
-
4.
|
|
76
|
-
5.
|
|
77
|
-
6.
|
|
78
|
-
7. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
|
|
79
|
-
|
|
80
|
-
If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.
|
|
72
|
+
1. Report the complete Git-visible candidate set, the exact validated causal bookkeeping path retained locally when visible, change summary, diff statistics, sensitive-content result, proposed message, and that every candidate will be committed while ignored files stay local. This is an informational report, not a confirmation gate.
|
|
73
|
+
2. Immediately before Git mutation, repeat the bounded whole-workspace status, evidence-freshness, merge-state, and sensitive-content checks. If the workspace changed, rebuild the candidate and message and validate again; block when coherence or safety cannot be re-established. Never ask the user merely to continue the validated commit.
|
|
74
|
+
3. Stage the complete workspace with ordinary `git add -A -- .` semantics, then reset only the validated `causal_bookkeeping_path` in the index to `HEAD` when it is Git-visible. Never force-add ignored content or accept any other exclusion.
|
|
75
|
+
4. Verify that the staged paths equal the latest validated candidate set, no non-ignored unstaged/untracked candidate remains outside the exact causal state, no incidental path appeared, and the staged snapshot still passes global sensitive-content checks.
|
|
76
|
+
5. Create the local commit and verify its hash, single parent, message, committed path set, and remaining Git-visible workspace against the validated snapshot.
|
|
77
|
+
6. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
|
|
81
78
|
|
|
82
79
|
## Step 3B: Runtime Commit Request
|
|
83
80
|
|
|
@@ -110,10 +107,10 @@ Schema version 1 path-manifest requests are not silently reinterpreted as worksp
|
|
|
110
107
|
|
|
111
108
|
## Output
|
|
112
109
|
|
|
113
|
-
|
|
110
|
+
Direct/default and `interactive-commit` operations return exactly one of:
|
|
114
111
|
|
|
115
112
|
```text
|
|
116
|
-
COMMITTED |
|
|
113
|
+
COMMITTED | COMMIT_BLOCKED
|
|
117
114
|
```
|
|
118
115
|
|
|
119
116
|
Preparation operation returns exactly one of:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: "prizmkit-workflow"
|
|
3
|
-
description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to
|
|
3
|
+
description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to verified local commit. Use when the user invokes prizmkit-workflow or explicitly asks for the full six-stage lifecycle, a plan-to-commit workflow, or one formal requirement completed end to end. Do not trigger on generic build, implement, feature, bug, or refactor requests; those belong to the applicable individual skill or an external integration. (project)"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# PrizmKit Workflow
|
|
@@ -98,7 +98,7 @@ Expected transitions:
|
|
|
98
98
|
| `prizmkit-code-review` | `PASS` plus valid `review-report.md` | `prizmkit-test` |
|
|
99
99
|
| `prizmkit-test` | `TEST_PASS` plus a consistent report/result pair with `production_changed=false` | `prizmkit-retrospective` |
|
|
100
100
|
| `prizmkit-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
|
|
101
|
-
| `prizmkit-committer` | `COMMITTED` after
|
|
101
|
+
| `prizmkit-committer` | `COMMITTED` after automatic direct-commit validation and verification | end |
|
|
102
102
|
|
|
103
103
|
Before accepting a Test transition, require `production_changed` to be a boolean and agree between `test-report.md` and `test-result.json`. A passing result with `production_changed=true` follows the bounded production-repair route below and is not final Test authority for Retrospective.
|
|
104
104
|
|
|
@@ -115,7 +115,7 @@ The composite must not:
|
|
|
115
115
|
- claim tests passed without a consistent `test-report.md` and terminal `test-result.json`;
|
|
116
116
|
- reinterpret testing-domain results as runtime/session outcomes;
|
|
117
117
|
- perform retrospective documentation changes itself;
|
|
118
|
-
- stage or commit before `prizmkit-committer` completes
|
|
118
|
+
- stage or commit before `prizmkit-committer` completes final-workspace validation and enters its direct-commit boundary;
|
|
119
119
|
- invoke `prizmkit-deploy` as a hidden seventh stage.
|
|
120
120
|
|
|
121
121
|
## Failure and Repair Routing
|
|
@@ -207,17 +207,17 @@ When the limit is reached:
|
|
|
207
207
|
|
|
208
208
|
The internal `prizmkit-code-review` limit of ten completed review rounds remains separate and does not increment `repair_round`.
|
|
209
209
|
|
|
210
|
-
##
|
|
210
|
+
## Automatic Local Commit Boundary
|
|
211
211
|
|
|
212
|
-
The composite reaches `/prizmkit-committer operation=interactive-commit
|
|
212
|
+
The composite reaches `/prizmkit-committer operation=interactive-commit`, which automatically creates the validated local commit without another user-confirmation pause.
|
|
213
213
|
|
|
214
214
|
The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` source-change paths for retrospective input, and validate its result. Code Review and Test must have treated the complete behavior-affecting Git-visible workspace as their final scope, including correct changes that predated this implementation session or live in framework, generated, instruction, lock, or host-support namespaces. If production behavior changes after those final gates, re-enter Review/Test rather than carrying stale authority into Committer.
|
|
215
215
|
|
|
216
|
-
Invoke Committer with the same `artifact_dir`, exact `evidence_paths`, `operation=interactive-commit`, and `causal_bookkeeping_path` equal to this workflow's exact state path. Do not assemble or pass `intended_paths`, support-path admission records, namespace classifications, or ordinary content exclusions. Committer inventories and validates the complete current Git-visible workspace,
|
|
216
|
+
Invoke Committer with the same `artifact_dir`, exact `evidence_paths`, `operation=interactive-commit`, and `causal_bookkeeping_path` equal to this workflow's exact state path. Do not assemble or pass `intended_paths`, support-path admission records, namespace classifications, or ordinary content exclusions. Committer inventories and validates the complete current Git-visible workspace, reports the candidate and message, revalidates immediately before mutation, and then stages, creates, and verifies the local commit without asking the user to continue. A non-clean starting checkout is not a blocker when the combined final content is correct and validated.
|
|
217
217
|
|
|
218
|
-
Ignored paths remain naturally absent, stay local, and never block or require force-add. Global Secret, sensitive-content, merge-state, evidence-freshness, and content-correctness checks apply to every Git-visible candidate without provenance exceptions. The exact `.prizmkit/state/workflows/<requirement-identity>.json` remains local during the
|
|
218
|
+
Ignored paths remain naturally absent, stay local, and never block or require force-add. Global Secret, sensitive-content, merge-state, evidence-freshness, and content-correctness checks apply to every Git-visible candidate without provenance exceptions. The exact `.prizmkit/state/workflows/<requirement-identity>.json` remains local during the direct commit because this coordinator must finalize it after Committer returns. Exact active Runtime request/checkpoint and post-commit receipt writes follow the same causal rule in automation; no broader or caller-selected exclusion is allowed.
|
|
219
219
|
|
|
220
|
-
External headless orchestration supplies explicit readiness evidence to `operation=prepare-runtime-commit
|
|
220
|
+
External headless orchestration supplies explicit readiness evidence to `operation=prepare-runtime-commit` and stops after `COMMIT_REQUEST_READY` and the exact request exist. Python Runtime validates the schema-v2 pathless request, atomically publishes its pending checkpoint state, commits the complete validated Git-visible workspace with only exact causal bookkeeping omitted, verifies Git, and finalizes `COMMITTED`. Remote publication remains separate.
|
|
221
221
|
|
|
222
222
|
## Automatic Handoff and Manual Fallback
|
|
223
223
|
|
|
@@ -268,7 +268,7 @@ push: not performed automatically
|
|
|
268
268
|
next_action: invoke /prizmkit-deploy separately if deployment is needed
|
|
269
269
|
```
|
|
270
270
|
|
|
271
|
-
|
|
271
|
+
There is no confirmation-decline state for direct local commit. If Committer returns `COMMIT_BLOCKED`, preserve the committer stage as incomplete with the exact safety, evidence, coherence, or Git blocker and the `/prizmkit-committer operation=interactive-commit` resume entry. `COMMIT_PENDING` remains reserved for a validated Runtime commit request.
|
|
272
272
|
|
|
273
273
|
If blocked, report:
|
|
274
274
|
|
|
@@ -104,7 +104,7 @@ retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED → status=completed
|
|
|
104
104
|
retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE → status=completed, stage_result=RETRO_COMPLETE
|
|
105
105
|
retrospective outcome=RETRO_BLOCKED → status=failed, stage_result=RETRO_BLOCKED
|
|
106
106
|
runtime commit preparation → status=in_progress, stage_result=COMMIT_PENDING
|
|
107
|
-
local commit
|
|
107
|
+
local commit verified → status=completed, stage_result=COMMITTED
|
|
108
108
|
commit blocked → status=failed, stage_result=COMMIT_BLOCKED
|
|
109
109
|
```
|
|
110
110
|
|
|
@@ -155,26 +155,27 @@ Any outer repair or continuation policy is independently owned by the caller and
|
|
|
155
155
|
|
|
156
156
|
## Commit Execution Ownership
|
|
157
157
|
|
|
158
|
-
|
|
158
|
+
Direct local commit execution:
|
|
159
159
|
|
|
160
160
|
```text
|
|
161
161
|
coordinator validates final Review, Test, and Retrospective authority for the complete behavior-affecting Git-visible workspace
|
|
162
162
|
→ committer inventories and inspects the complete current Git-visible workspace without caller-supplied paths
|
|
163
163
|
→ committer applies global correctness, freshness, merge-state, and Secret checks
|
|
164
|
-
→ committer
|
|
165
|
-
→
|
|
164
|
+
→ committer reports every visible change and one truthful message without pausing for confirmation
|
|
165
|
+
→ committer revalidates immediately before mutation
|
|
166
166
|
→ stages the complete workspace, creates, and verifies the local commit
|
|
167
167
|
```
|
|
168
168
|
|
|
169
|
-
Git visibility
|
|
169
|
+
Git visibility and validated final content determine commit scope; path provenance does not. Correct changes may predate the active requirement or live under `.prizmkit/**`, generated, instruction, lock, or host-support namespaces. Ignored files remain absent, stay local, never block, and are never force-added. If behavior-affecting content appears after final Review/Test, the evidence is stale and the workflow re-enters those gates. Sensitive, conflicted, incorrect, incoherent, unreadable, or unverifiable content blocks on its actual state rather than an unknown-path category. The exact active workflow-state path derived from the artifact basename remains outside the direct-commit snapshot only because the coordinator finalizes it after Committer returns; it is not a general framework exclusion.
|
|
170
170
|
|
|
171
171
|
Pipeline execution:
|
|
172
172
|
|
|
173
173
|
```text
|
|
174
174
|
external coordinator validates its required gates and supplies exact readiness evidence
|
|
175
175
|
→ committer validates the complete Git-visible workspace and writes a schema-v2 pathless runtime-commit-request.json without Git mutation
|
|
176
|
-
→ external coordinator
|
|
177
|
-
→ Python
|
|
176
|
+
→ external coordinator stops after COMMIT_REQUEST_READY and the exact request exist
|
|
177
|
+
→ Python Runtime validates the request and atomically publishes the checkpoint's in_progress/COMMIT_PENDING state
|
|
178
|
+
→ Python Runtime re-enumerates and stages the complete non-ignored workspace
|
|
178
179
|
→ Python runtime verifies the commit, writes its receipt, and finalizes checkpoint completed/COMMITTED
|
|
179
180
|
→ remote publication remains separate
|
|
180
181
|
```
|
|
@@ -44,7 +44,7 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
44
44
|
|
|
45
45
|
**Your ONLY writable outputs are:**
|
|
46
46
|
1. `.prizmkit/plans/refactor-list.json` (`.prizmkit/plans/`)
|
|
47
|
-
2.
|
|
47
|
+
2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
|
|
48
48
|
|
|
49
49
|
**After planning is complete**, you MUST:
|
|
50
50
|
1. Present the summary and recommended next step
|
|
@@ -54,6 +54,10 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
54
54
|
5. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
|
|
55
55
|
6. Return the validated refactor list to the caller; only `refactor-pipeline-launcher` prepares the runtime command
|
|
56
56
|
|
|
57
|
+
## Draft Lifecycle (Hard Rule)
|
|
58
|
+
|
|
59
|
+
In an ordinary successful flow, `.prizmkit/plans/refactor-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.
|
|
60
|
+
|
|
57
61
|
## Fresh-Session Task Contract (Hard Rule)
|
|
58
62
|
|
|
59
63
|
Every new or changed refactor item 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:
|
|
@@ -168,12 +172,12 @@ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, N
|
|
|
168
172
|
```bash
|
|
169
173
|
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
|
|
170
174
|
```
|
|
171
|
-
5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this
|
|
172
|
-
6.
|
|
175
|
+
5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this bounded internal transport/recovery state.
|
|
176
|
+
6. After consequential decisions and the pre-generation gate pass, immediately run `append` outside AI context:
|
|
173
177
|
```bash
|
|
174
178
|
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
175
179
|
```
|
|
176
|
-
The command validates the
|
|
180
|
+
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. Existing `generate` remains the new-list/full-rewrite path.
|
|
177
181
|
|
|
178
182
|
## Operation Modes
|
|
179
183
|
|
|
@@ -315,8 +319,8 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
|
|
|
315
319
|
**Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
|
|
316
320
|
|
|
317
321
|
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
318
|
-
1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object.
|
|
319
|
-
2.
|
|
322
|
+
1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object as internal transport/recovery state.
|
|
323
|
+
2. Once required semantic gates pass, immediately use the matching deterministic writer without a second draft-approval pause:
|
|
320
324
|
- New list or explicit full-list rewrite:
|
|
321
325
|
```bash
|
|
322
326
|
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
@@ -327,12 +331,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
|
|
|
327
331
|
```
|
|
328
332
|
`generate` fills root defaults for a complete draft. `append` preserves root metadata and historical refactors, defaults missing new statuses, and writes only after the merged full list validates.
|
|
329
333
|
3. If validation fails -> fix the draft and retry (max 3 attempts)
|
|
330
|
-
4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan,
|
|
331
|
-
5. If review and validation pass ->
|
|
334
|
+
4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, use `append --replace-tail` for ordinary appended entries, and revalidate until pass
|
|
335
|
+
5. If review and validation pass -> delete the ordinary internal draft under §Draft Lifecycle; retain and report it only for an explicit recovery condition or cleanup failure
|
|
336
|
+
6. Present the final written result, summary, and draft cleanup result. For later user 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 ordinary appended entries
|
|
332
337
|
|
|
333
338
|
**CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
|
|
334
339
|
|
|
335
|
-
**CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and
|
|
340
|
+
**CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained.
|
|
336
341
|
|
|
337
342
|
## Checkpoints (Mandatory Gates)
|
|
338
343
|
|
|
@@ -345,13 +350,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
|
|
|
345
350
|
| **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
|
|
346
351
|
| **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
|
|
347
352
|
| **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
|
|
348
|
-
| **CP-RP-7** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and
|
|
353
|
+
| **CP-RP-7** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 7 |
|
|
349
354
|
|
|
350
355
|
## Local Generated-Plan Review Gate
|
|
351
356
|
|
|
352
357
|
Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
353
358
|
|
|
354
|
-
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 refactor. 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 refactor. 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.
|
|
355
360
|
|
|
356
361
|
## Output Rules
|
|
357
362
|
|
|
@@ -460,4 +465,5 @@ After successful validation and the Local Generated-Plan Review Gate, report:
|
|
|
460
465
|
3. Dependency ordering highlights (which items must run first)
|
|
461
466
|
4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
|
|
462
467
|
5. Local generated-plan review result: verdict, reviewed refactor IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
|
|
463
|
-
6.
|
|
468
|
+
6. Draft cleanup result: `removed`, or retained path and recovery reason
|
|
469
|
+
7. Recommended next action: `refactor-pipeline-launcher`
|
|
@@ -4,8 +4,8 @@ Load this reference when validation fails, the planning session is interrupted,
|
|
|
4
4
|
|
|
5
5
|
## Validation Recovery
|
|
6
6
|
|
|
7
|
-
- Warnings only: present the
|
|
8
|
-
- Validation errors: group related errors,
|
|
7
|
+
- Warnings only: present them and continue when informational. Ask the user only when a warning exposes a consequential architecture, scope, behavior-preservation, or verification decision; do not add a generic draft-promotion approval.
|
|
8
|
+
- Validation errors: group related errors, apply unambiguous mechanical corrections to the planning draft, and rerun the matching writer. Ask before semantic corrections, and limit automatic correction to three attempts before retaining the draft and asking the user how to proceed.
|
|
9
9
|
- Keep `.prizmkit/plans/refactor-list.json` at the project-root `.prizmkit/plans/` path.
|
|
10
10
|
- Do not alter source code or run project tests while recovering a planning artifact.
|
|
11
11
|
|
|
@@ -14,11 +14,12 @@ Load this reference when validation fails, the planning session is interrupted,
|
|
|
14
14
|
| Artifact Found | Resume Point |
|
|
15
15
|
|---|---|
|
|
16
16
|
| No planning artifact | Phase 1: Project Context |
|
|
17
|
-
| Draft in `.prizmkit/plans/` | Phase matching the draft's completeness |
|
|
18
|
-
| Incomplete final refactor list |
|
|
19
|
-
| Valid final refactor list | Mode D: Summary |
|
|
17
|
+
| Draft only in `.prizmkit/plans/` | Phase matching the draft's actual completeness |
|
|
18
|
+
| Incomplete final refactor list | Resume writer/validation repair through the source draft |
|
|
19
|
+
| Valid final refactor list only | Mode D: Summary or a new bounded append |
|
|
20
|
+
| Valid final plus draft | Treat as interrupted review or cleanup-failure state; inspect and offer resume review, discard, or a new append rather than assuming either artifact wins |
|
|
20
21
|
|
|
21
|
-
Read the
|
|
22
|
+
Read the artifacts directly because `.prizmkit` content may be gitignored. Preserve existing valid entries and resume only unfinished planning work. When final and draft both exist and available evidence cannot distinguish interrupted review from cleanup failure, ask the user before deleting or promoting the draft.
|
|
22
23
|
|
|
23
24
|
## Session Exit Gate
|
|
24
25
|
|
|
@@ -31,7 +32,14 @@ Activate the exit gate when all of these are true:
|
|
|
31
32
|
Use `AskUserQuestion` with these options:
|
|
32
33
|
|
|
33
34
|
- **Continue to completion (Recommended)** — resume from the detected planning phase.
|
|
34
|
-
- **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json
|
|
35
|
+
- **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json` and retain it as explicit recovery state.
|
|
35
36
|
- **Abandon** — exit without saving new planning content.
|
|
36
37
|
|
|
37
|
-
When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again.
|
|
38
|
+
When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again. Terminal cleanup does not apply until resumed planning completes.
|
|
39
|
+
|
|
40
|
+
## Draft Management
|
|
41
|
+
|
|
42
|
+
- Keep an ordinary writer draft through generation/append, validation, and the complete Local Generated-Plan Review fix loop.
|
|
43
|
+
- After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
|
|
44
|
+
- Retain a draft only for explicit **Save draft and exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
|
|
45
|
+
- Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
|
|
@@ -31,12 +31,13 @@ For simple refactoring with minimal scope.
|
|
|
31
31
|
**NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
|
|
32
32
|
3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
|
|
33
33
|
4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
|
|
34
|
-
5. Write `.prizmkit/plans/refactor-list.draft.json
|
|
34
|
+
5. Write `.prizmkit/plans/refactor-list.draft.json` as internal transport/recovery state. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and immediately call `append` without a second draft-approval pause:
|
|
35
35
|
```bash
|
|
36
36
|
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
|
|
37
37
|
```
|
|
38
|
-
6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill
|
|
39
|
-
7.
|
|
38
|
+
6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill. After review returns `PASS` and final validation passes, delete the ordinary internal draft under the main Skill's Draft Lifecycle, then present the final written result before recommending `refactor-pipeline-launcher`.
|
|
39
|
+
7. For a later adjustment after cleanup, recreate only 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.
|
|
40
|
+
8. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
|
|
40
41
|
|
|
41
42
|
## When NOT to Use Fast Path
|
|
42
43
|
- More than 2 refactor items
|