prizmkit 1.1.162 → 1.1.165
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/bin/create-prizmkit.js +4 -4
- package/bundled/VERSION.json +3 -3
- package/bundled/adapters/cursor/assets/prizmkit-hook.cjs +65 -0
- package/bundled/adapters/cursor/hooks-adapter.js +139 -0
- package/bundled/adapters/cursor/paths.js +11 -0
- package/bundled/adapters/cursor/rules-adapter.js +49 -0
- package/bundled/adapters/cursor/skill-adapter.js +27 -0
- package/bundled/dev-pipeline/README.md +18 -5
- package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +3 -25
- package/bundled/dev-pipeline/prizmkit_runtime/config.py +71 -14
- package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +28 -4
- package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +5 -2
- package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +21 -3
- package/bundled/dev-pipeline/prizmkit_runtime/runners.py +19 -5
- package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +123 -28
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +2 -0
- package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +1 -42
- package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +43 -6
- package/bundled/dev-pipeline/scripts/init-pipeline.py +46 -8
- package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +41 -6
- package/bundled/dev-pipeline/scripts/parse-stream-progress.py +143 -27
- package/bundled/dev-pipeline/scripts/update-feature-status.py +2 -2
- package/bundled/dev-pipeline/scripts/utils.py +3 -12
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +4 -2
- package/bundled/dev-pipeline/templates/feature-list-schema.json +4 -2
- package/bundled/dev-pipeline/templates/refactor-list-schema.json +4 -2
- package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +2 -1
- package/bundled/dev-pipeline/tests/test_checkpoint_state.py +5 -23
- package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +2 -2
- package/bundled/dev-pipeline/tests/test_python_runner_parity.py +231 -0
- package/bundled/dev-pipeline/tests/test_unified_cli.py +406 -30
- package/bundled/dev-pipeline/tests/test_utils.py +23 -0
- package/bundled/rules/USAGE.md +3 -0
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/app-planner/SKILL.md +18 -9
- package/bundled/skills/app-planner/references/app-design-guide.md +7 -5
- package/bundled/skills/app-planner/references/brainstorm-guide.md +13 -21
- package/bundled/skills/app-planner/references/generated-plan-review.md +6 -2
- package/bundled/skills/bug-planner/SKILL.md +13 -5
- package/bundled/skills/bug-planner/assets/bug-confirmation-template.md +11 -7
- package/bundled/skills/bug-planner/references/generated-plan-review.md +7 -3
- package/bundled/skills/bug-planner/references/verification.md +0 -2
- package/bundled/skills/bug-planner/scripts/validate-bug-list.py +37 -7
- package/bundled/skills/feature-planner/SKILL.md +17 -11
- package/bundled/skills/feature-planner/assets/planning-guide.md +13 -13
- package/bundled/skills/feature-planner/references/completeness-review.md +8 -4
- package/bundled/skills/feature-planner/references/generated-plan-review.md +6 -2
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +43 -19
- package/bundled/skills/prizmkit-init/SKILL.md +1 -1
- package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
- package/bundled/skills/prizmkit-plan/SKILL.md +15 -4
- package/bundled/skills/prizmkit-plan/assets/plan-template.md +18 -3
- package/bundled/skills/prizmkit-plan/assets/spec-template.md +17 -5
- package/bundled/skills/prizmkit-plan/references/clarify-guide.md +26 -24
- package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +7 -5
- package/bundled/skills/prizmkit-plan/references/verification-checklist.md +15 -6
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
- package/bundled/skills/refactor-planner/SKILL.md +18 -11
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +6 -2
- package/bundled/skills/refactor-planner/references/planning-phases.md +14 -9
- package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +8 -2
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +38 -9
- package/package.json +4 -2
- package/src/ai-cli-launch.js +9 -2
- package/src/clean.js +42 -6
- package/src/config.js +51 -10
- package/src/detect-platform.js +30 -8
- package/src/external-skills.js +33 -99
- package/src/index.js +5 -0
- package/src/manifest.js +30 -4
- package/src/platforms.js +11 -4
- package/src/prompts.js +12 -4
- package/src/scaffold.js +75 -4
- package/src/upgrade.js +15 -14
|
@@ -42,6 +42,21 @@ VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "s
|
|
|
42
42
|
VALID_COMPLEXITIES = {"low", "medium", "high", "critical"}
|
|
43
43
|
VALID_PRIORITIES = {"critical", "high", "medium", "low"}
|
|
44
44
|
VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
|
|
45
|
+
ALLOWED_LIST_FIELDS = {
|
|
46
|
+
"$schema", "project_name", "project_description", "created_at",
|
|
47
|
+
"created_by", "features", "global_context",
|
|
48
|
+
}
|
|
49
|
+
ALLOWED_GLOBAL_CONTEXT_FIELDS = {
|
|
50
|
+
"tech_stack", "language", "runtime", "frontend_framework",
|
|
51
|
+
"frontend_styling", "backend_framework", "database", "orm",
|
|
52
|
+
"design_system", "testing_strategy", "bundler", "project_type",
|
|
53
|
+
}
|
|
54
|
+
ALLOWED_FEATURE_FIELDS = {
|
|
55
|
+
"id", "title", "description", "priority", "estimated_complexity",
|
|
56
|
+
"dependencies", "acceptance_criteria", "status", "session_granularity",
|
|
57
|
+
"sub_features", "model", "completion_notes", "user_context",
|
|
58
|
+
"browser_interaction", "testing",
|
|
59
|
+
}
|
|
45
60
|
FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
|
|
46
61
|
SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
|
|
47
62
|
|
|
@@ -170,17 +185,33 @@ def validate_feature_list(data, is_new_plan=True):
|
|
|
170
185
|
# ------------------------------------------------------------------
|
|
171
186
|
# 1. Top-level schema validation
|
|
172
187
|
# ------------------------------------------------------------------
|
|
188
|
+
unknown_root = set(data) - ALLOWED_LIST_FIELDS
|
|
189
|
+
if unknown_root:
|
|
190
|
+
errors.append("feature list has unknown fields: {}".format(
|
|
191
|
+
", ".join(sorted(unknown_root))
|
|
192
|
+
))
|
|
193
|
+
|
|
173
194
|
schema = data.get("$schema")
|
|
174
195
|
if schema != SCHEMA_VERSION:
|
|
175
196
|
errors.append(
|
|
176
197
|
"$schema must be '{}', got '{}'".format(SCHEMA_VERSION, schema)
|
|
177
198
|
)
|
|
178
199
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
if not isinstance(app_name, str) or not app_name.strip():
|
|
200
|
+
project_name = data.get("project_name")
|
|
201
|
+
if not isinstance(project_name, str) or not project_name.strip():
|
|
182
202
|
errors.append("project_name must be a non-empty string")
|
|
183
203
|
|
|
204
|
+
global_context = data.get("global_context")
|
|
205
|
+
if global_context is not None:
|
|
206
|
+
if not isinstance(global_context, dict):
|
|
207
|
+
errors.append("global_context must be an object")
|
|
208
|
+
else:
|
|
209
|
+
unknown_context = set(global_context) - ALLOWED_GLOBAL_CONTEXT_FIELDS
|
|
210
|
+
if unknown_context:
|
|
211
|
+
errors.append("global_context has unknown fields: {}".format(
|
|
212
|
+
", ".join(sorted(unknown_context))
|
|
213
|
+
))
|
|
214
|
+
|
|
184
215
|
features = data.get("features")
|
|
185
216
|
if not isinstance(features, list) or len(features) == 0:
|
|
186
217
|
errors.append("features must be a non-empty array")
|
|
@@ -225,6 +256,12 @@ def validate_feature_list(data, is_new_plan=True):
|
|
|
225
256
|
label, ", ".join(sorted(missing))
|
|
226
257
|
))
|
|
227
258
|
|
|
259
|
+
unknown = set(feat.keys()) - ALLOWED_FEATURE_FIELDS
|
|
260
|
+
if unknown:
|
|
261
|
+
errors.append("{} has unknown fields: {}".format(
|
|
262
|
+
label, ", ".join(sorted(unknown))
|
|
263
|
+
))
|
|
264
|
+
|
|
228
265
|
# -- ID format & uniqueness --
|
|
229
266
|
fid = feat.get("id", "")
|
|
230
267
|
if not FEATURE_ID_RE.match(str(fid)):
|
|
@@ -335,15 +372,6 @@ def validate_feature_list(data, is_new_plan=True):
|
|
|
335
372
|
# -- Sub-features --
|
|
336
373
|
subs = feat.get("sub_features")
|
|
337
374
|
|
|
338
|
-
# -- Retired fields --
|
|
339
|
-
for retired_field in ("critic", "critic_count"):
|
|
340
|
-
if retired_field in feat:
|
|
341
|
-
errors.append(
|
|
342
|
-
"{}: '{}' field is retired; remove it from feature-list data".format(
|
|
343
|
-
label, retired_field
|
|
344
|
-
)
|
|
345
|
-
)
|
|
346
|
-
|
|
347
375
|
# -- Browser interaction check (warning for frontend features) --
|
|
348
376
|
has_frontend = bool(
|
|
349
377
|
data.get("global_context", {}).get("frontend_framework")
|
|
@@ -546,11 +574,11 @@ def _build_dependency_graph_text(features):
|
|
|
546
574
|
|
|
547
575
|
def generate_summary_markdown(data):
|
|
548
576
|
"""Generate a markdown summary of the feature list."""
|
|
549
|
-
|
|
577
|
+
project_name = data.get("project_name", "Unknown")
|
|
550
578
|
features = data.get("features", [])
|
|
551
579
|
|
|
552
580
|
lines = []
|
|
553
|
-
lines.append("# Feature Summary: {}".format(
|
|
581
|
+
lines.append("# Feature Summary: {}".format(project_name))
|
|
554
582
|
lines.append("")
|
|
555
583
|
|
|
556
584
|
# Table header
|
|
@@ -636,7 +664,7 @@ def generate_summary_json(data):
|
|
|
636
664
|
})
|
|
637
665
|
|
|
638
666
|
return {
|
|
639
|
-
"project_name": data.get("project_name",
|
|
667
|
+
"project_name": data.get("project_name", ""),
|
|
640
668
|
"features": feature_summaries,
|
|
641
669
|
"stats": {
|
|
642
670
|
"total_features": len(features),
|
|
@@ -749,10 +777,6 @@ def cmd_generate(args):
|
|
|
749
777
|
data.setdefault("created_at", now)
|
|
750
778
|
data.setdefault("created_by", "feature-planner")
|
|
751
779
|
|
|
752
|
-
# Ensure project_name from app_name if needed
|
|
753
|
-
if "project_name" not in data and "app_name" in data:
|
|
754
|
-
data["project_name"] = data["app_name"]
|
|
755
|
-
|
|
756
780
|
# Set default status for features without one
|
|
757
781
|
for feature in data.get("features", []):
|
|
758
782
|
feature.setdefault("status", "pending")
|
|
@@ -82,7 +82,7 @@ BROWNFIELD WORKFLOW (existing project):
|
|
|
82
82
|
- TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
|
|
83
83
|
- SUB-MODULES: directories INSIDE a top-level module (e.g. `src/routes/`, `src/models/`)
|
|
84
84
|
- Exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); sub-module S maps to nested `.prizmkit/prizm-docs/<M>/<S>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
|
|
85
|
-
- Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
|
|
85
|
+
- Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, `.cursor/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
|
|
86
86
|
- **Bounded discovery contract** — use the current Host's available directory-listing or file-search capability to enumerate at most two directory levels, apply the exclusions above before analysis, preserve parent/child relationships, and report the resulting project-relative structure. Do not require a POSIX shell pipeline or any other operating-system-specific command.
|
|
87
87
|
3. Identify entry points by language convention
|
|
88
88
|
4. Catalog dependencies (external packages)
|
|
@@ -20,13 +20,13 @@ Handles re-init without losing user edits:
|
|
|
20
20
|
| Field | Type | Description |
|
|
21
21
|
|-------|------|-------------|
|
|
22
22
|
| `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
|
|
23
|
-
| `platform` | string | Installed payload metadata: `"codebuddy"` \| `"claude"` \| `"codex"` \| `"pi"` \| `"all"`. It records installation, not a canonical behavior allowlist. |
|
|
23
|
+
| `platform` | string | Installed payload metadata: `"codebuddy"` \| `"claude"` \| `"codex"` \| `"pi"` \| `"cursor"` \| `"all"`. It records installation, not a canonical behavior allowlist. |
|
|
24
24
|
| `tech_stack` | object | Detected or user-provided tech stack |
|
|
25
25
|
| `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
|
|
26
26
|
| `detected_layers` | string[] | Development layers observed in the project. Written by prizmkit-init Phase 4.5. Values: `frontend` / `backend` / `database` / `mobile`. Empty only when no layers are observed. Always refreshed from code and never cleared by rule-adoption choices. |
|
|
27
27
|
| `enabled_rule_profiles` | string[] | Rule profiles the user explicitly enabled. This is independent from `detected_layers`; an empty array means no custom profile is enabled, not that the project has no detected layers. |
|
|
28
28
|
|
|
29
|
-
Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, `pi`, or `all`.
|
|
29
|
+
Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, `pi`, `cursor`, or `all`.
|
|
30
30
|
|
|
31
31
|
## Examples
|
|
32
32
|
|
|
@@ -32,6 +32,15 @@ A change artifact can describe a feature, bug fix, refactor, migration, test imp
|
|
|
32
32
|
|
|
33
33
|
`prizmkit-plan` owns specification, plan, task generation, and planning-quality review for one supplied requirement. Its terminal outputs are `PLAN_READY` or `PLAN_BLOCKED`; it stops after producing that result.
|
|
34
34
|
|
|
35
|
+
## Intent-Aligned Planning Policy
|
|
36
|
+
|
|
37
|
+
Before proposing or finalizing a plan:
|
|
38
|
+
1. Establish the **intent baseline**: confirmed goal, success outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
|
|
39
|
+
2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or recommendation into user intent.
|
|
40
|
+
3. **Clarify by decision impact**. Ask before choices that materially change goals, external behavior, scope, compatibility, safety, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
|
|
41
|
+
4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
|
|
42
|
+
5. Produce a **minimum-sufficient** plan: every plan element maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence. Defer unsupported future work.
|
|
43
|
+
|
|
35
44
|
## Phase 0: Initialization Check and Context
|
|
36
45
|
|
|
37
46
|
1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
|
|
@@ -49,13 +58,14 @@ Skip regeneration when `spec.md` already exists and still matches the requested
|
|
|
49
58
|
- otherwise derive the normalized title slug, allocate the next collision-safe number, and create `.prizmkit/specs/<number>-<slug>/`.
|
|
50
59
|
3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
|
|
51
60
|
- focus on WHAT and WHY, not HOW;
|
|
61
|
+
- record the intent baseline and evidence status without turning recommendations into requirements;
|
|
52
62
|
- include only relevant sections;
|
|
53
63
|
- give every goal acceptance criteria;
|
|
54
|
-
- mark
|
|
64
|
+
- mark consequential ambiguity with `[NEEDS CLARIFICATION]`; retain low-risk unknowns as explicit assumptions when safe.
|
|
55
65
|
4. For persistence changes, inspect existing schemas and add a Data Model section using project conventions.
|
|
56
66
|
5. Resolve clarification markers:
|
|
57
|
-
- interactive: use `${SKILL_DIR}/references/clarify-guide.md
|
|
58
|
-
- non-interactive: choose conservative defaults, annotate them, and block when a safe default
|
|
67
|
+
- interactive: use `${SKILL_DIR}/references/clarify-guide.md`; ask about consequential decisions and record safe low-risk assumptions without silently defaulting user intent;
|
|
68
|
+
- non-interactive: choose conservative defaults only when they are safe and reversible, annotate them, and block when a consequential decision has no safe default.
|
|
59
69
|
|
|
60
70
|
Internal ID hygiene: PrizmKit IDs, task/session/run IDs, branch names, absolute worktree paths, and internal artifact paths may exist in change artifacts but must not leak into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
|
|
61
71
|
|
|
@@ -69,7 +79,8 @@ Precondition: `spec.md` exists with no unresolved blocker.
|
|
|
69
79
|
- concise for small, well-scoped formal requirements;
|
|
70
80
|
- comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
|
|
71
81
|
4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
|
|
72
|
-
- change approach;
|
|
82
|
+
- change approach and goal/constraint traceability;
|
|
83
|
+
- decision rationale and alternatives only when materially different viable paths exist;
|
|
73
84
|
- component and file changes;
|
|
74
85
|
- data migration approach when relevant;
|
|
75
86
|
- interface/API contract design when relevant;
|
|
@@ -1,7 +1,18 @@
|
|
|
1
1
|
# Plan: [TITLE]
|
|
2
2
|
|
|
3
3
|
## Change Approach
|
|
4
|
-
[Description of the technical approach — how these changes integrate with the existing system]
|
|
4
|
+
[Description of the minimum-sufficient technical approach — how these changes integrate with the existing system]
|
|
5
|
+
|
|
6
|
+
## Decision Traceability
|
|
7
|
+
| Goal / Constraint / Existing Contract / Evidenced Risk | Design Response | Evidence Status and Rationale | Completion Evidence |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| [G-1 or constraint] | [Necessary design response] | [confirmed fact / inference / recommendation / assumption] | [Observable test or check] |
|
|
10
|
+
|
|
11
|
+
## Alternatives and Decision Rationale
|
|
12
|
+
<!-- Include only when materially different viable paths exist. Do not manufacture alternatives to fill this section. Delete when not applicable. -->
|
|
13
|
+
- Selected approach: [Complete meaning and why it fits the confirmed intent]
|
|
14
|
+
- Material alternatives: [Alternative + meaningful trade-off]
|
|
15
|
+
- Reconsider when: [Constraint or evidence change that would alter the decision]
|
|
5
16
|
|
|
6
17
|
## Component Design
|
|
7
18
|
|
|
@@ -85,12 +96,16 @@
|
|
|
85
96
|
- [ ] CI/CD pipeline update needed
|
|
86
97
|
|
|
87
98
|
## Pre-Implementation Gates
|
|
88
|
-
- [ ]
|
|
99
|
+
- [ ] Intent fidelity: goals, success outcome, scope, and non-goals match the confirmed requirement
|
|
100
|
+
- [ ] Evidence honesty: facts, inferences, recommendations, assumptions, and unknowns remain distinct
|
|
101
|
+
- [ ] Spec coverage: all goals mapped to components and observable completion evidence
|
|
102
|
+
- [ ] Design necessity: every component/task maps to a goal, confirmed constraint, existing contract, or evidenced risk
|
|
103
|
+
- [ ] Minimum sufficiency: unsupported future work and unjustified abstractions are absent
|
|
89
104
|
- [ ] Data model reviewed — existing schema conventions documented and followed (if applicable)
|
|
90
105
|
- [ ] All `[NEEDS CLARIFICATION]` items resolved
|
|
91
106
|
- [ ] Testing approach agreed
|
|
92
107
|
- [ ] Behavior preservation strategy defined (if modifying existing behavior)
|
|
93
|
-
- [ ] Root cause confirmed with reproduction
|
|
108
|
+
- [ ] Root cause is confirmed with evidence or explicitly retained as a bounded hypothesis/unknown with reproduction and investigation tasks (if fixing a defect)
|
|
94
109
|
|
|
95
110
|
## Tasks
|
|
96
111
|
|
|
@@ -3,6 +3,13 @@
|
|
|
3
3
|
## Overview
|
|
4
4
|
[One paragraph describing the purpose and motivation]
|
|
5
5
|
|
|
6
|
+
## Intent and Evidence
|
|
7
|
+
- Confirmed intent: [User goal and successful outcome, expressed by complete meaning]
|
|
8
|
+
- Confirmed facts: [Evidence-backed current state and constraints]
|
|
9
|
+
- Evidence-backed inferences: [Inference + supporting evidence; delete if none]
|
|
10
|
+
- Assumptions: [Low-risk, local, reversible assumptions + verification point; delete if none]
|
|
11
|
+
- Unknowns: [Consequential unknowns use `[NEEDS CLARIFICATION]`; non-blocking unknowns retain their evidence status]
|
|
12
|
+
|
|
6
13
|
## Goals
|
|
7
14
|
|
|
8
15
|
### G-1: [Goal Title]
|
|
@@ -29,10 +36,12 @@
|
|
|
29
36
|
- [Existing test suites that must continue to pass]
|
|
30
37
|
|
|
31
38
|
## Root Cause
|
|
32
|
-
<!-- Include this section when the task is fixing a defect. Delete if not applicable. -->
|
|
39
|
+
<!-- Include this section when the task is fixing a defect. Delete if not applicable. Do not invent a root cause merely to complete the template. -->
|
|
33
40
|
- Error classification: [Runtime / Network / Auth / Data / Logic / Config / External]
|
|
34
|
-
- Root
|
|
35
|
-
-
|
|
41
|
+
- Root-cause status: [confirmed / evidence-backed hypothesis / unknown]
|
|
42
|
+
- Root cause or hypothesis: [specific mechanism when supported; otherwise state the bounded investigation question]
|
|
43
|
+
- Evidence: [reproduction, failing test, trace, source observation, or other concrete basis]
|
|
44
|
+
- Affected files: [evidence-backed file list with purpose; use unknown when not established]
|
|
36
45
|
- Impact: [blast radius — which modules / features are affected]
|
|
37
46
|
|
|
38
47
|
## Dependencies
|
|
@@ -62,7 +71,8 @@
|
|
|
62
71
|
- [Constraint 1]
|
|
63
72
|
|
|
64
73
|
## Clarifications
|
|
65
|
-
|
|
74
|
+
<!-- Use markers only for consequential ambiguity. Keep safe low-risk assumptions in Intent and Evidence instead of turning every uncertainty into a question. -->
|
|
75
|
+
[NEEDS CLARIFICATION]: [Decision, materially different outcomes, and why confirmation is required]
|
|
66
76
|
|
|
67
77
|
## Review Checklist
|
|
68
78
|
- [ ] All goals have acceptance criteria
|
|
@@ -70,4 +80,6 @@
|
|
|
70
80
|
- [ ] Dependencies are identified
|
|
71
81
|
- [ ] No implementation details (WHAT not HOW)
|
|
72
82
|
- [ ] Behavior preservation defined (if modifying existing behavior)
|
|
73
|
-
- [ ] Root cause
|
|
83
|
+
- [ ] Root cause is evidence-backed or explicitly labeled as hypothesis/unknown (if fixing a defect)
|
|
84
|
+
- [ ] Facts, inferences, recommendations, assumptions, and unknowns are not conflated
|
|
85
|
+
- [ ] Every goal has observable completion evidence and no scope item lacks a requirement or confirmed constraint
|
|
@@ -6,35 +6,36 @@ Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLA
|
|
|
6
6
|
|
|
7
7
|
## Question Strategy
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Classify each uncertainty before asking:
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
|
|
11
|
+
- **Consequential ambiguity** — different answers materially change the goal, external behavior, scope, compatibility, safety, cost, data, or an irreversible decision. Ask the user and keep `[NEEDS CLARIFICATION]` until resolved.
|
|
12
|
+
- **Evidence-resolvable uncertainty** — project docs, source, schemas, or existing contracts determine the answer. Inspect the bounded evidence and record the confirmed fact instead of asking.
|
|
13
|
+
- **Low-risk assumption** — the choice is local, reversible, and does not alter user-visible intent. Record the assumption and its verification point; let the user override it without blocking progress.
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
1.
|
|
18
|
-
2.
|
|
19
|
-
3.
|
|
20
|
-
4.
|
|
21
|
-
|
|
15
|
+
For each question or tightly related batch:
|
|
16
|
+
1. Cite the exact location in `spec.md` (for example, "§Goals G-1" or "§Scope").
|
|
17
|
+
2. State what is ambiguous, which outcomes differ, and why the decision is consequential.
|
|
18
|
+
3. Provide an explicitly labeled **recommendation** with rationale when evidence supports one; it remains a recommendation until the user confirms it.
|
|
19
|
+
4. Group questions that share one decision context. Ask sequentially only when one answer changes which later question is relevant.
|
|
20
|
+
|
|
21
|
+
Prioritize by consequence and reversibility, not by a universal domain order. Data integrity, safety, public contracts, and destructive migrations are commonly high impact; a data-model, UX, performance, or integration detail is consequential only when its alternatives materially change the requirement.
|
|
22
22
|
|
|
23
23
|
## Update Discipline
|
|
24
24
|
|
|
25
|
-
After
|
|
26
|
-
-
|
|
27
|
-
- Remove the resolved `[NEEDS CLARIFICATION]` marker
|
|
28
|
-
-
|
|
25
|
+
After each answer or related answer batch:
|
|
26
|
+
- Update `spec.md` with the complete selected meaning, not an answer token or conversation reference.
|
|
27
|
+
- Remove only the resolved `[NEEDS CLARIFICATION]` marker.
|
|
28
|
+
- Reclassify newly exposed uncertainty as consequential, evidence-resolvable, or a low-risk assumption.
|
|
29
29
|
|
|
30
|
-
##
|
|
30
|
+
## Convergence Policy
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
32
|
+
Use no arbitrary target number of questions. Clarification converges when:
|
|
33
|
+
- no consequential `[NEEDS CLARIFICATION]` marker remains;
|
|
34
|
+
- confirmed facts, recommendations, assumptions, and unknowns are not conflated;
|
|
35
|
+
- unresolved low-risk assumptions are explicit and have a verification point; and
|
|
36
|
+
- the acceptance criteria let a fresh implementation session determine completion.
|
|
36
37
|
|
|
37
|
-
|
|
38
|
+
Do not keep questioning merely to reach subjective "full confidence" or specify low-level implementation choices that the plan can safely leave to implementation. If a user answer creates a new consequential conflict, surface that conflict and ask; otherwise preserve the uncertainty with its correct evidence status.
|
|
38
39
|
|
|
39
40
|
## Early Termination
|
|
40
41
|
|
|
@@ -62,6 +63,7 @@ If the user says "done", "stop", or "enough" — end immediately and output a su
|
|
|
62
63
|
|
|
63
64
|
## Guidelines
|
|
64
65
|
|
|
65
|
-
- Stay at WHAT/WHY level — no implementation details (HOW) in spec
|
|
66
|
-
- If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
|
|
67
|
-
-
|
|
66
|
+
- Stay at WHAT/WHY level — no implementation details (HOW) in spec.
|
|
67
|
+
- If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence.
|
|
68
|
+
- Do not present a project default or general best practice as confirmed user intent.
|
|
69
|
+
- If the user seems fatigued, summarize the remaining consequential decisions and offer to continue now or save them as explicit blockers; do not silently default them.
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Run this local planning-quality gate after `spec.md` and `plan.md` are drafted or updated, before returning `PLAN_READY`.
|
|
6
6
|
|
|
7
|
-
This
|
|
7
|
+
This mandatory Main-Agent baseline runs inside `prizmkit-plan` to improve the planning artifacts only. Its maximum of two local rounds remains independent of the optional Reviewer described in `independent-plan-review.md`.
|
|
8
8
|
|
|
9
9
|
## Non-Goals
|
|
10
10
|
|
|
@@ -13,7 +13,6 @@ Do not do any of the following from this guide:
|
|
|
13
13
|
- Start implementation or edit product/source code.
|
|
14
14
|
- Run tests, builds, lint, or package commands.
|
|
15
15
|
- Start implementation or any other execution process.
|
|
16
|
-
- Spawn or require a Critic agent inside this Main-Agent loop. The separate optional independent review is considered only after this loop converges and only through `independent-plan-review.md`.
|
|
17
16
|
- Create a separate review-loop skill.
|
|
18
17
|
- Expand scope beyond improving `spec.md` and `plan.md`.
|
|
19
18
|
|
|
@@ -31,13 +30,16 @@ Review both artifacts against these dimensions:
|
|
|
31
30
|
|
|
32
31
|
| Dimension | Check |
|
|
33
32
|
|---|---|
|
|
34
|
-
|
|
|
33
|
+
| Intent fidelity | Goals, success outcomes, scope, non-goals, and constraint precedence preserve confirmed user meaning instead of substituting AI preferences or generic best practices. |
|
|
34
|
+
| Evidence status | Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; consequential choices are not silently defaulted. |
|
|
35
|
+
| Ambiguity | Consequential requirements, scope, terms, or expected behavior are unclear or internally inconsistent; low-risk reversible assumptions are explicit rather than over-questioned. |
|
|
35
36
|
| Acceptance criteria completeness | Each goal has verifiable acceptance criteria; edge/error cases are included when meaningful. |
|
|
36
37
|
| Missing constraints | Security, data, compatibility, performance, platform, deployment, migration, or non-goal constraints are absent where relevant. |
|
|
37
38
|
| Task ordering errors | Tasks are sequenced before their prerequisites, checkpoints are misplaced, or dependency order is unsafe. |
|
|
38
39
|
| Dependency assumptions | The plan assumes missing APIs, schemas, files, services, packages, auth, environment variables, or generated artifacts without evidence. |
|
|
39
40
|
| Scope drift | The plan adds unrelated work, backlog items, nice-to-haves, or implementation beyond the spec. |
|
|
40
|
-
| Overengineering | The plan introduces abstractions, services, agents, workflows, data stores,
|
|
41
|
+
| Overengineering | The plan introduces abstractions, services, agents, workflows, data stores, cross-module rewrites, or speculative future work that no goal, confirmed constraint, existing contract, or evidenced risk justifies. |
|
|
42
|
+
| Decision traceability | Every design element has a justified source and every goal maps to observable completion evidence; material alternatives are compared only when genuine viable paths exist. |
|
|
41
43
|
| Implementation readiness | Tasks are actionable, file-scoped when possible, testable, and resumable; blockers are explicit. |
|
|
42
44
|
| Source-reading overhead | The implementation plan avoids broad rereads and identifies the minimum context/files needed for execution. |
|
|
43
45
|
|
|
@@ -87,7 +89,7 @@ Optional findings do not block planning completion.
|
|
|
87
89
|
4. Do not apply `OPTIONAL` findings unless they clearly improve readiness without expanding scope.
|
|
88
90
|
5. If any fixes were applied, rerun this review once.
|
|
89
91
|
6. Stop after at most 2 total review rounds.
|
|
90
|
-
7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not
|
|
92
|
+
7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not treat independent review as blocker recovery.
|
|
91
93
|
8. If no unresolved blockers remain, report that the mandatory Main-Agent planning quality gate passed and hand off to the optional independent Plan review boundary in `independent-plan-review.md`.
|
|
92
94
|
|
|
93
95
|
## Output Summary
|
|
@@ -4,9 +4,16 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## Intent and Evidence
|
|
8
|
+
|
|
9
|
+
- [ ] Confirmed goals, successful outcomes, scope, non-goals, and explicit constraints preserve the user's meaning without adding AI preferences as requirements
|
|
10
|
+
- [ ] Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns are labeled distinctly
|
|
11
|
+
- [ ] No consequential decision was silently defaulted in an interactive plan
|
|
12
|
+
- [ ] Low-risk assumptions are local, reversible, disclosed, and paired with a verification point
|
|
13
|
+
|
|
7
14
|
## Coverage
|
|
8
15
|
|
|
9
|
-
- [ ] Every goal (G-N) in spec.md has at least one task in plan.md
|
|
16
|
+
- [ ] Every goal (G-N) in spec.md has at least one task in plan.md and observable completion evidence
|
|
10
17
|
- [ ] Every task has a target file path (`— file: path/to/file`)
|
|
11
18
|
- [ ] Risk assessment contains at least one concrete risk with a mitigation plan
|
|
12
19
|
- [ ] The plan contains at least one verification checkpoint; a small plan may use one final checkpoint
|
|
@@ -18,15 +25,17 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
|
|
|
18
25
|
- [ ] No near-duplicate requirements exist across spec.md sections (same intent, different wording)
|
|
19
26
|
- [ ] If duplicates found, consolidate to the clearer phrasing and remove the other
|
|
20
27
|
|
|
21
|
-
## Orphan Detection
|
|
28
|
+
## Orphan and Design-Necessity Detection
|
|
22
29
|
|
|
23
|
-
- [ ] No task exists without a mapped goal
|
|
24
|
-
- [ ] No plan component exists without a corresponding
|
|
30
|
+
- [ ] No task exists without a mapped goal, confirmed constraint, existing contract, or evidenced risk
|
|
31
|
+
- [ ] No plan component exists without a corresponding requirement or justified preservation obligation
|
|
32
|
+
- [ ] No speculative future feature, abstraction, infrastructure component, or cleanup expands the confirmed scope
|
|
25
33
|
|
|
26
34
|
## Ambiguity Scan
|
|
27
35
|
|
|
28
|
-
- [ ] No
|
|
29
|
-
- [ ]
|
|
36
|
+
- [ ] No consequential `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` marker remains
|
|
37
|
+
- [ ] Non-blocking unknowns and low-risk assumptions retain their evidence status instead of being presented as facts
|
|
38
|
+
- [ ] No vague criterion uses a measurable threshold unless that threshold is confirmed or supported by project evidence; otherwise clarify the observable condition
|
|
30
39
|
|
|
31
40
|
## Terminology Consistency
|
|
32
41
|
|
|
@@ -592,7 +592,7 @@ HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-modul
|
|
|
592
592
|
|
|
593
593
|
CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init does not create semantic or mirrored L2 placeholders; later Update/Rebuild/Migrate may create complete L2 documents when durable knowledge and unambiguous identity exist.
|
|
594
594
|
|
|
595
|
-
EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .prizmkit/
|
|
595
|
+
EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .cursor/, .prizmkit/
|
|
596
596
|
SOURCE_BOUNDARY: Excluding `.prizmkit/` excludes the installed Runtime at `.prizmkit/dev-pipeline/`; never exclude a repository's canonical top-level `dev-pipeline/` source module by basename.
|
|
597
597
|
|
|
598
598
|
## 9.2 Post-Init Behavior
|
|
@@ -11,7 +11,7 @@ STEPS:
|
|
|
11
11
|
- TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
|
|
12
12
|
- SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the direct-child parent L1; if durable L2 is created later, its nested path mirrors the sub-module.
|
|
13
13
|
- HIERARCHY RULE: exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); directory X inside M maps to nested `.prizmkit/prizm-docs/<M>/<X>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
|
|
14
|
-
- Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
|
|
14
|
+
- Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .cursor/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
|
|
15
15
|
3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
|
|
16
16
|
4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist. Do not create placeholder detail files.
|
|
17
17
|
5. Generate `root.prizm` (L0) with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
|
|
@@ -11,6 +11,15 @@ Plan executable refactoring items for later autonomous dev-pipeline execution. T
|
|
|
11
11
|
|
|
12
12
|
Always produce a validated `.prizmkit/plans/refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
|
|
13
13
|
|
|
14
|
+
## Intent-Aligned Planning Policy
|
|
15
|
+
|
|
16
|
+
Before proposing or finalizing refactor contracts:
|
|
17
|
+
1. Establish the **intent baseline**: confirmed structural goal, preserved behavior, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
|
|
18
|
+
2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never present an inferred target architecture or scope expansion as confirmed user intent.
|
|
19
|
+
3. **Clarify by decision impact**. Ask before choices that materially change target structure, public contracts, behavior preservation, scope, compatibility, safety, cost, or irreversible migration state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
|
|
20
|
+
4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful architectural trade-offs without manufacturing an option count or applying a universal pattern.
|
|
21
|
+
5. Produce a **minimum-sufficient** refactor contract: every operation maps to a confirmed structural goal, constraint, existing contract, or evidenced risk, and every preservation goal maps to observable completion evidence of equivalence. Defer unrelated cleanup and speculative redesign.
|
|
22
|
+
|
|
14
23
|
## Invocation Commitment (Hard Rule)
|
|
15
24
|
|
|
16
25
|
**When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
|
|
@@ -52,7 +61,7 @@ Every new or changed refactor item is an executable contract for a fresh AI sess
|
|
|
52
61
|
1. **Self-contained contract**: The item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, and completion evidence. Preserve substantive user requirements at matching detail.
|
|
53
62
|
2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may contain scoped exact excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh refactor session must still know the current structure, target architecture, allowed scope, forbidden changes, preservation strategy, and verification evidence.
|
|
54
63
|
3. **Purposeful scope**: Every path in `scope.files` and every related path reference must be a purpose-tagged target path in the task contract or supplementary evidence, stating what to inspect or change. The scope array may remain schema-compatible path strings, while `description` explains each path or coherent path group's role.
|
|
55
|
-
4. **Clarify, do not guess**: Ask
|
|
64
|
+
4. **Clarify by impact, do not guess**: Ask when multiple meanings of target architecture, scope boundaries, preservation behavior, material applicability, or relative references would materially change the refactor contract. Keep AI-proposed architecture labeled as a recommendation until confirmed; retain low-risk reversible implementation details as explicit assumptions when safe.
|
|
56
65
|
5. **Item isolation**: Each refactor contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence.
|
|
57
66
|
|
|
58
67
|
### Artifact-Wide AI Readability
|
|
@@ -213,14 +222,14 @@ Support 4 input formats (users may mix formats):
|
|
|
213
222
|
> "There's a circular dependency between auth and user modules"
|
|
214
223
|
> "The database layer is tightly coupled to the HTTP layer"
|
|
215
224
|
|
|
216
|
-
For each input,
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
220
|
-
-
|
|
221
|
-
-
|
|
225
|
+
For each input, establish:
|
|
226
|
+
- The confirmed structural pain point and desired outcome.
|
|
227
|
+
- Evidence-backed target files, modules, patterns, consumers, and purpose-tagged inspection paths.
|
|
228
|
+
- Behavior invariants, public contracts, scope boundaries, and non-goals.
|
|
229
|
+
- Behavior-preservation and completion evidence.
|
|
230
|
+
- Motivation and constraints that determine whether a target architecture is necessary.
|
|
222
231
|
|
|
223
|
-
|
|
232
|
+
If the user has not selected a target architecture, inspect the code first and present a recommendation or meaningful alternatives only when materially different viable paths exist. Ask about consequential structure/scope/preservation decisions; group related questions and retain safe low-risk reversible details as explicit assumptions. Continue until the user indicates no additional goals and no consequential ambiguity remains.
|
|
224
233
|
|
|
225
234
|
**CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
|
|
226
235
|
|
|
@@ -335,7 +344,7 @@ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the sin
|
|
|
335
344
|
|
|
336
345
|
## Verification Defaults
|
|
337
346
|
|
|
338
|
-
Set behavior-preservation and testing expectations for each refactor item.
|
|
347
|
+
Set behavior-preservation and testing expectations for each refactor item.
|
|
339
348
|
|
|
340
349
|
| Priority | Complexity | Verification expectation |
|
|
341
350
|
|----------|-----------|--------------------------|
|
|
@@ -344,8 +353,6 @@ Set behavior-preservation and testing expectations for each refactor item. Do no
|
|
|
344
353
|
| high | high | Scoped tests for changed boundaries plus review gate |
|
|
345
354
|
| other combinations | any | Smallest meaningful behavior-preservation check |
|
|
346
355
|
|
|
347
|
-
Never emit `critic` or `critic_count`; those fields are fully removed and validators reject them.
|
|
348
|
-
|
|
349
356
|
---
|
|
350
357
|
|
|
351
358
|
## Fast Path
|
|
@@ -29,6 +29,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
|
|
|
29
29
|
|
|
30
30
|
For every reviewed refactor entry, check:
|
|
31
31
|
|
|
32
|
+
- Intent fidelity: confirmed structural outcome, behavior invariants, scope, non-goals, and constraints preserve user intent rather than an AI-selected architecture
|
|
33
|
+
- Evidence status honesty: current-state facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; proposed target architecture is not presented as confirmed until selected
|
|
34
|
+
- Minimum-sufficient scope: every operation maps to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk; unrelated cleanup and speculative redesign are absent
|
|
32
35
|
- Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
|
|
33
36
|
- Dependency/DAG soundness, including safe behavior-preserving order
|
|
34
37
|
- Description completeness: objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, completion evidence, and headless execution readiness
|
|
@@ -45,14 +48,15 @@ For every reviewed refactor entry, check:
|
|
|
45
48
|
|
|
46
49
|
Repeat the pre-generation simulation for every reviewed new or changed refactor as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
|
|
47
50
|
|
|
48
|
-
1. What exact problem or outcome is this task responsible for?
|
|
49
|
-
2. What current architecture exists and what target architecture must replace it?
|
|
51
|
+
1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
|
|
52
|
+
2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
|
|
50
53
|
3. Which approach was selected, expressed by meaning rather than an option label?
|
|
51
54
|
4. What scope boundaries, constraints, and non-goals must be preserved?
|
|
52
55
|
5. Why is each reference material and target path relevant?
|
|
53
56
|
6. How can completion and behavior preservation be verified?
|
|
54
57
|
7. Does any phrase require an unseen earlier question, recommendation, or option list?
|
|
55
58
|
8. Do quoted source materials agree with the final task decision?
|
|
59
|
+
9. Does every operation have a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
|
|
56
60
|
|
|
57
61
|
Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable refactor contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
|
|
58
62
|
|