prizmkit 1.1.193 → 1.1.195

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/bin/create-prizmkit.js +43 -12
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/dev-pipeline/.env.example +5 -0
  4. package/bundled/dev-pipeline/README.md +2 -1
  5. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +111 -30
  6. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +44 -3
  7. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +29 -9
  8. package/bundled/dev-pipeline/prizmkit_runtime/config.py +121 -44
  9. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +190 -37
  10. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -0
  11. package/bundled/dev-pipeline/prizmkit_runtime/iterate.py +2480 -0
  12. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +3 -0
  13. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +32 -8
  14. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +29 -12
  15. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +13 -5
  16. package/bundled/dev-pipeline/prizmkit_runtime/status.py +166 -0
  17. package/bundled/dev-pipeline/scripts/feature_list_contract.py +964 -0
  18. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +18 -40
  19. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +24 -19
  20. package/bundled/dev-pipeline/scripts/prompt_framework.py +24 -8
  21. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +1 -63
  22. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +8 -6
  23. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +0 -10
  24. package/bundled/dev-pipeline/templates/feature-list-schema.json +8 -6
  25. package/bundled/dev-pipeline/templates/iterate/evaluate-prompt.md +97 -0
  26. package/bundled/dev-pipeline/templates/iterate/evaluation-schema.json +538 -0
  27. package/bundled/dev-pipeline/templates/iterate/headless-plan-prompt.md +66 -0
  28. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +2 -2
  29. package/bundled/dev-pipeline/templates/sections/runtime-commit-handoff.md +13 -4
  30. package/bundled/rules/USAGE.md +15 -48
  31. package/bundled/rules/_rules-metadata.json +7 -14
  32. package/bundled/rules/general/coding-baseline.md +23 -0
  33. package/bundled/rules/prizm/prizm-progressive-loading.md +2 -2
  34. package/bundled/skills/_metadata.json +12 -42
  35. package/bundled/skills/app-planner/SKILL.md +2 -2
  36. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -2
  37. package/bundled/skills/app-planner/references/project-state-detection.md +1 -1
  38. package/bundled/skills/app-planner/references/rules-configuration.md +158 -88
  39. package/bundled/skills/app-planner/scripts/validate-rules-configuration.py +543 -12
  40. package/bundled/skills/bug-planner/references/verification.md +4 -5
  41. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +20 -14
  42. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +49 -9
  43. package/bundled/skills/feature-pipeline-launcher/SKILL.md +20 -14
  44. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +49 -9
  45. package/bundled/skills/feature-planner/SKILL.md +3 -3
  46. package/bundled/skills/feature-planner/references/browser-interaction.md +9 -29
  47. package/bundled/skills/iterate-pipeline-launcher/SKILL.md +273 -0
  48. package/bundled/skills/iterate-pipeline-launcher/references/configuration.md +105 -0
  49. package/bundled/skills/prizmkit-code-review/SKILL.md +10 -8
  50. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +4 -1
  51. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +2 -1
  52. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +12 -8
  53. package/bundled/skills/prizmkit-implement/SKILL.md +2 -2
  54. package/bundled/skills/prizmkit-init/SKILL.md +10 -10
  55. package/bundled/skills/prizmkit-init/references/brownfield-deep-init.md +81 -0
  56. package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
  57. package/bundled/skills/prizmkit-plan/assets/plan-template.md +2 -0
  58. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +8 -4
  59. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +8 -7
  60. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +33 -16
  61. package/bundled/skills/prizmkit-prizm-docs/references/op-validate.md +1 -1
  62. package/bundled/skills/prizmkit-retrospective/SKILL.md +29 -12
  63. package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json +126 -2
  64. package/bundled/skills/prizmkit-retrospective/references/rule-evolution-steps.md +86 -0
  65. package/bundled/skills/prizmkit-test/SKILL.md +2 -1
  66. package/bundled/skills/prizmkit-workflow/SKILL.md +8 -0
  67. package/bundled/skills/prizmkit-workflow/references/cold-start-rules.md +84 -0
  68. package/bundled/templates/project-memory-template.md +3 -3
  69. package/package.json +1 -1
  70. package/src/clean.js +2 -3
  71. package/src/config.js +52 -39
  72. package/src/index.js +29 -111
  73. package/src/prompts.js +20 -87
  74. package/src/runtime-passthrough.js +324 -0
  75. package/src/scaffold.js +41 -294
  76. package/src/upgrade.js +7 -39
  77. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +0 -127
  78. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +0 -124
  79. package/src/external-skills.js +0 -103
@@ -48,6 +48,15 @@ class AIClientResolution:
48
48
  launch_profile: HeadlessLaunchProfile | None = None
49
49
 
50
50
 
51
+ @dataclass(frozen=True)
52
+ class AIClientCapabilities:
53
+ """CLI model-argument and reasoning-effort capabilities for one platform profile."""
54
+
55
+ model_arg_supported: bool
56
+ effort_flag_mode: str
57
+ supported_effort_values: tuple[str, ...]
58
+
59
+
51
60
  @dataclass(frozen=True)
52
61
  class EffortValidationResult:
53
62
  """Platform-aware validation result for PRIZMKIT_EFFORT."""
@@ -92,13 +101,57 @@ AI_CLIENT_PRECEDENCE = (
92
101
  "PATH:agy",
93
102
  )
94
103
 
95
- _EFFORT_VALUES_BY_PLATFORM = {
96
- "claude": ("low", "medium", "high", "xhigh", "max"),
97
- "codex": ("low", "medium", "high", "xhigh"),
98
- "codebuddy": ("low", "medium", "high", "xhigh"),
99
- "pi": ("off", "minimal", "low", "medium", "high", "xhigh", "max"),
100
- "cursor": (),
101
- "antigravity": ("low", "medium", "high", "xhigh", "max"),
104
+ _CAPABILITIES_BY_PLATFORM: dict[str, AIClientCapabilities] = {
105
+ "claude": AIClientCapabilities(
106
+ model_arg_supported=True,
107
+ effort_flag_mode="flag",
108
+ supported_effort_values=("low", "medium", "high", "xhigh", "max"),
109
+ ),
110
+ "codebuddy": AIClientCapabilities(
111
+ model_arg_supported=True,
112
+ effort_flag_mode="flag",
113
+ supported_effort_values=("minimal", "low", "medium", "high", "xhigh", "max"),
114
+ ),
115
+ "antigravity": AIClientCapabilities(
116
+ model_arg_supported=True,
117
+ effort_flag_mode="flag",
118
+ supported_effort_values=("low", "medium", "high", "xhigh", "max"),
119
+ ),
120
+ "pi": AIClientCapabilities(
121
+ model_arg_supported=True,
122
+ effort_flag_mode="flag",
123
+ supported_effort_values=("off", "minimal", "low", "medium", "high", "xhigh", "max"),
124
+ ),
125
+ "codex": AIClientCapabilities(
126
+ model_arg_supported=True,
127
+ effort_flag_mode="config",
128
+ supported_effort_values=("low", "medium", "high", "xhigh"),
129
+ ),
130
+ "cursor": AIClientCapabilities(
131
+ model_arg_supported=True,
132
+ effort_flag_mode="none",
133
+ supported_effort_values=(),
134
+ ),
135
+ "custom": AIClientCapabilities(
136
+ model_arg_supported=False,
137
+ effort_flag_mode="custom_ignored",
138
+ supported_effort_values=(),
139
+ ),
140
+ }
141
+
142
+ _UNRESOLVED_CAPABILITIES = AIClientCapabilities(
143
+ model_arg_supported=False,
144
+ effort_flag_mode="none",
145
+ supported_effort_values=(),
146
+ )
147
+
148
+ _PLATFORM_LABELS: dict[str, str] = {
149
+ "claude": "Claude Code",
150
+ "codex": "Codex",
151
+ "codebuddy": "CodeBuddy",
152
+ "pi": "Pi",
153
+ "cursor": "Cursor Agent CLI",
154
+ "antigravity": "Antigravity",
102
155
  }
103
156
 
104
157
 
@@ -457,52 +510,76 @@ def _resolve_ai_client(paths: RuntimePaths, env: Mapping[str, str]) -> AIClientR
457
510
  )
458
511
 
459
512
 
513
+ def _capability_platform(platform: str | None) -> str | None:
514
+ normalized = _normalize_platform(platform)
515
+ return normalized if normalized in _CAPABILITIES_BY_PLATFORM else None
516
+
517
+
518
+ def ai_cli_capabilities(platform: str | None) -> AIClientCapabilities:
519
+ """Return immutable model and effort capabilities for one platform profile."""
520
+ resolved = _capability_platform(platform)
521
+ if resolved is None:
522
+ return _UNRESOLVED_CAPABILITIES
523
+ return _CAPABILITIES_BY_PLATFORM[resolved]
524
+
525
+
460
526
  def supported_effort_values(platform: str | None) -> tuple[str, ...]:
461
527
  """Return supported PRIZMKIT_EFFORT values for the detected platform."""
462
- return _EFFORT_VALUES_BY_PLATFORM.get(
463
- _concrete_platform(platform) or "codebuddy",
464
- _EFFORT_VALUES_BY_PLATFORM["codebuddy"],
465
- )
528
+ return ai_cli_capabilities(platform).supported_effort_values
466
529
 
467
530
 
468
- def validate_effort(effort: str | None, platform: str | None) -> EffortValidationResult:
469
- """Validate PRIZMKIT_EFFORT without exiting the process."""
470
- supported = supported_effort_values(platform)
531
+ def validate_effort(effort: str | None, *, platform: str | None = None) -> str | None:
532
+ """Validate and normalize PRIZMKIT_EFFORT against platform capabilities."""
471
533
  if effort is None or str(effort).strip() == "":
534
+ return None
535
+ normalized_effort = str(effort).strip().lower()
536
+ resolved_platform = _capability_platform(platform)
537
+ capabilities = ai_cli_capabilities(resolved_platform)
538
+ if normalized_effort in capabilities.supported_effort_values:
539
+ return normalized_effort
540
+ if resolved_platform == "cursor":
541
+ raise ValueError(
542
+ f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
543
+ "(Cursor Agent CLI). Cursor Agent CLI exposes no documented effort parameter; "
544
+ "leave PRIZMKIT_EFFORT unset."
545
+ )
546
+ if resolved_platform == "custom":
547
+ raise ValueError(
548
+ f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the custom AI CLI launch profile "
549
+ "(custom). Custom launch profiles do not forward model or effort flags; "
550
+ "leave PRIZMKIT_EFFORT unset or pass provider flags via ai_cli_launch.extra_args."
551
+ )
552
+ if resolved_platform is None:
553
+ raise ValueError(
554
+ f"PRIZMKIT_EFFORT='{normalized_effort}' cannot be validated because no supported AI CLI platform "
555
+ "was resolved. Configure or install a supported AI CLI platform, or leave PRIZMKIT_EFFORT unset."
556
+ )
557
+ label = _PLATFORM_LABELS[resolved_platform]
558
+ raise ValueError(
559
+ f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
560
+ f"({label}). Supported values for {label}: {', '.join(capabilities.supported_effort_values)}"
561
+ )
562
+
563
+
564
+ def _evaluate_effort_config(effort: str | None, platform: str | None) -> EffortValidationResult:
565
+ resolved_platform = _capability_platform(platform)
566
+ supported = ai_cli_capabilities(resolved_platform).supported_effort_values
567
+ try:
568
+ validated = validate_effort(effort, platform=resolved_platform)
569
+ except ValueError as exc:
570
+ normalized = str(effort).strip().lower() if effort is not None else ""
472
571
  return EffortValidationResult(
473
- effort=None,
474
- platform=_concrete_platform(platform),
475
- valid=True,
572
+ effort=normalized or None,
573
+ platform=resolved_platform,
574
+ valid=False,
476
575
  supported_values=supported,
576
+ message=str(exc),
477
577
  )
478
- normalized_effort = str(effort).strip()
479
- valid = normalized_effort in supported
480
- message = ""
481
- if not valid:
482
- label = {
483
- "claude": "Claude Code",
484
- "codex": "Codex",
485
- "codebuddy": "CodeBuddy",
486
- "pi": "Pi",
487
- "cursor": "Cursor Agent CLI",
488
- "antigravity": "Antigravity",
489
- }.get(_concrete_platform(platform) or "codebuddy", "CodeBuddy")
490
- if not supported:
491
- message = (
492
- f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
493
- f"({label}). Cursor Agent CLI exposes no documented effort parameter; leave PRIZMKIT_EFFORT unset."
494
- )
495
- else:
496
- message = (
497
- f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
498
- f"({label}). Supported values for {label}: {', '.join(supported)}"
499
- )
500
578
  return EffortValidationResult(
501
- effort=normalized_effort,
502
- platform=_concrete_platform(platform),
503
- valid=valid,
579
+ effort=validated,
580
+ platform=resolved_platform,
581
+ valid=True,
504
582
  supported_values=supported,
505
- message=message,
506
583
  )
507
584
 
508
585
 
@@ -512,7 +589,7 @@ def load_runtime_config(paths: RuntimePaths, env: Mapping[str, str] | None = Non
512
589
  runtime_env = load_env_file(paths.prizmkit_dir / ".env", provided_env)
513
590
  ai_client = _resolve_ai_client(paths, runtime_env)
514
591
  effort = runtime_env.get("PRIZMKIT_EFFORT")
515
- effort_validation = validate_effort(effort, ai_client.platform)
592
+ effort_validation = _evaluate_effort_config(effort, ai_client.platform)
516
593
  environment = RuntimeEnvironment(
517
594
  env_file=paths.prizmkit_dir / ".env",
518
595
  config_file=paths.prizmkit_dir / "config.json",
@@ -35,13 +35,26 @@ class DaemonPaths:
35
35
  start_lock: Path
36
36
 
37
37
 
38
+ @dataclass(frozen=True)
39
+ class _DaemonTarget:
40
+ """Cohesive daemon filesystem/identity target for family or iterate daemons."""
41
+
42
+ kind: str
43
+ state_dir: Path
44
+ plan_path: Path | None = None
45
+
46
+
38
47
  @dataclass(frozen=True)
39
48
  class DaemonStartOptions:
40
49
  """Parsed daemon start/restart arguments."""
41
50
 
42
- list_path: Path
51
+ list_path: Path | None = None
43
52
  env_overrides: str = ""
44
53
  features_filter: str = ""
54
+ max_rounds: int | None = None
55
+ focus: str = ""
56
+ checkpoint_every: int | None = None
57
+ no_checkpoint: bool = False
45
58
  help_requested: bool = False
46
59
 
47
60
 
@@ -74,29 +87,35 @@ PROGRESS_COUNTS_BY_KIND = {
74
87
  }
75
88
 
76
89
 
90
+ def _daemon_target_for(kind: str, paths) -> RunnerFamily | _DaemonTarget:
91
+ if kind == "iterate":
92
+ return _DaemonTarget(kind="iterate", state_dir=paths.iterate_state_dir, plan_path=None)
93
+ return family_for(kind, paths)
94
+
95
+
77
96
  def run_daemon_command(kind: str, action: str, legacy_args: tuple[str, ...], paths) -> CommandResult:
78
- """Run a daemon lifecycle command for feature or bugfix."""
79
- family = family_for(kind, paths)
80
- daemon_paths = _daemon_paths(family)
97
+ """Run a daemon lifecycle command for feature, bugfix, or iterate."""
98
+ target = _daemon_target_for(kind, paths)
99
+ daemon_paths = _daemon_paths(target)
81
100
  if action == "start":
82
- return _start(family, daemon_paths, legacy_args, paths)
101
+ return _start(target, daemon_paths, legacy_args, paths)
83
102
  if action == "status":
84
- return _status(family, daemon_paths)
103
+ return _status(target, daemon_paths)
85
104
  if action == "stop":
86
- return _stop(family, daemon_paths)
105
+ return _stop(target, daemon_paths)
87
106
  if action in {"logs", "log"}:
88
- return _logs(family, daemon_paths, legacy_args)
107
+ return _logs(target, daemon_paths, legacy_args)
89
108
  if action == "restart":
90
- stop_result = _stop(family, daemon_paths)
109
+ stop_result = _stop(target, daemon_paths)
91
110
  if stop_result.exit_code != 0:
92
111
  return stop_result
93
- start_result = _start(family, daemon_paths, legacy_args, paths)
112
+ start_result = _start(target, daemon_paths, legacy_args, paths)
94
113
  stderr = "\n".join(part for part in (stop_result.stderr, start_result.stderr) if part)
95
114
  return CommandResult(start_result.exit_code, start_result.title, start_result.message, stdout=start_result.render(), stderr=stderr)
96
115
  return CommandResult(1, f"Python {kind} daemon", f"Unsupported daemon action: {action}")
97
116
 
98
117
 
99
- def _daemon_paths(family: RunnerFamily) -> DaemonPaths:
118
+ def _daemon_paths(family: RunnerFamily | _DaemonTarget) -> DaemonPaths:
100
119
  return DaemonPaths(
101
120
  state_dir=family.state_dir,
102
121
  pid_file=family.state_dir / ".pipeline.pid",
@@ -106,14 +125,17 @@ def _daemon_paths(family: RunnerFamily) -> DaemonPaths:
106
125
  )
107
126
 
108
127
 
109
- def _start(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[str, ...], paths) -> CommandResult:
128
+ def _start(family: RunnerFamily | _DaemonTarget, daemon_paths: DaemonPaths, legacy_args: tuple[str, ...], paths) -> CommandResult:
110
129
  options = _parse_start_args(family, legacy_args)
111
130
  if options.help_requested:
112
131
  return CommandResult(0, f"Python {family.kind} daemon", _help_text(family))
113
- list_path = options.list_path if options.list_path.is_absolute() else (paths.project_root / options.list_path).resolve()
114
- if not list_path.is_file():
115
- stderr = f"{family.kind} list not found: {list_path}"
116
- return CommandResult(2, f"Python {family.kind} daemon", stderr, stdout="", stderr=stderr)
132
+ list_path: Path | None = None
133
+ if family.kind != "iterate":
134
+ assert options.list_path is not None
135
+ list_path = options.list_path if options.list_path.is_absolute() else (paths.project_root / options.list_path).resolve()
136
+ if not list_path.is_file():
137
+ stderr = f"{family.kind} list not found: {list_path}"
138
+ return CommandResult(2, f"Python {family.kind} daemon", stderr, stdout="", stderr=stderr)
117
139
 
118
140
  daemon_paths.state_dir.mkdir(parents=True, exist_ok=True)
119
141
  try:
@@ -175,10 +197,11 @@ def _start(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[s
175
197
  failure_stderr.extend(tail)
176
198
  return CommandResult(1, f"Python {family.kind} daemon", message, stdout="", stderr="\n".join(failure_stderr))
177
199
 
200
+ stderr_lines.append(f"Launching {family.kind} pipeline...")
201
+ if list_path is not None:
202
+ stderr_lines.append(f"{family.kind} list: {list_path}")
178
203
  stderr_lines.extend(
179
204
  [
180
- f"Launching {family.kind} pipeline...",
181
- f"{family.kind} list: {list_path}",
182
205
  f"Log file: {daemon_paths.log_file}",
183
206
  f"Pipeline started successfully (PID: {pid})",
184
207
  ]
@@ -190,7 +213,7 @@ def _start(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[s
190
213
  return CommandResult(1, f"Python {family.kind} daemon", message, stdout="", stderr=message)
191
214
 
192
215
 
193
- def _status(family: RunnerFamily, daemon_paths: DaemonPaths) -> CommandResult:
216
+ def _status(family: RunnerFamily | _DaemonTarget, daemon_paths: DaemonPaths) -> CommandResult:
194
217
  daemon_paths.state_dir.mkdir(parents=True, exist_ok=True)
195
218
  stderr_lines: list[str] = []
196
219
  stale_warning = _clean_stale_pid(daemon_paths)
@@ -209,8 +232,6 @@ def _status(family: RunnerFamily, daemon_paths: DaemonPaths) -> CommandResult:
209
232
  stderr_lines.extend(tail)
210
233
  return CommandResult(1, f"Python {family.kind} daemon status", "not running", stdout=json.dumps({"running": False}), stderr="\n".join(stderr_lines))
211
234
 
212
- list_key = LIST_META_KEY_BY_KIND[family.kind]
213
- list_path = str(meta.get(list_key) or "")
214
235
  log_size_kb = daemon_paths.log_file.stat().st_size // 1024 if daemon_paths.log_file.is_file() else 0
215
236
  started_at = str(meta.get("started_at") or "")
216
237
  payload: dict[str, object] = {
@@ -219,13 +240,36 @@ def _status(family: RunnerFamily, daemon_paths: DaemonPaths) -> CommandResult:
219
240
  "log_file": str(daemon_paths.log_file),
220
241
  "log_size_kb": log_size_kb,
221
242
  "started_at": started_at,
222
- list_key: list_path,
223
243
  }
224
- if family.kind != "feature":
225
- payload["pipeline_type"] = family.kind
226
- progress = _progress_summary(family, Path(list_path) if list_path else None)
227
- if progress:
228
- payload["progress"] = progress
244
+ if family.kind == "iterate":
245
+ payload["pipeline_type"] = "iterate"
246
+ if meta.get("max_rounds") is not None:
247
+ payload["max_rounds"] = meta.get("max_rounds")
248
+ if meta.get("focus"):
249
+ payload["focus"] = meta.get("focus")
250
+ iterate_state_file = daemon_paths.state_dir / "state.json"
251
+ if iterate_state_file.is_file():
252
+ try:
253
+ state_data = json.loads(iterate_state_file.read_text(encoding="utf-8"))
254
+ if isinstance(state_data, dict):
255
+ payload["iterate_state"] = {
256
+ "status": state_data.get("status"),
257
+ "phase": state_data.get("phase"),
258
+ "current_round": state_data.get("current_round"),
259
+ "completed_rounds": state_data.get("completed_rounds"),
260
+ "active_feature_id": state_data.get("active_feature_id"),
261
+ }
262
+ except (OSError, json.JSONDecodeError):
263
+ pass
264
+ else:
265
+ list_key = LIST_META_KEY_BY_KIND[family.kind]
266
+ list_path = str(meta.get(list_key) or "")
267
+ payload[list_key] = list_path
268
+ if family.kind != "feature":
269
+ payload["pipeline_type"] = family.kind
270
+ progress = _progress_summary(family, Path(list_path) if list_path else None)
271
+ if progress:
272
+ payload["progress"] = progress
229
273
 
230
274
  stderr_lines.append(f"Pipeline is running (PID: {pid})")
231
275
  if started_at:
@@ -271,7 +315,78 @@ def _logs(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[st
271
315
  return CommandResult(0, f"Python {family.kind} daemon logs", "logs", stdout="\n".join(_tail_lines(daemon_paths.log_file, options.lines)))
272
316
 
273
317
 
274
- def _parse_start_args(family: RunnerFamily, legacy_args: tuple[str, ...]) -> DaemonStartOptions:
318
+ def _parse_positive_daemon_int(raw: str, label: str) -> int:
319
+ try:
320
+ value = int(str(raw).strip())
321
+ except ValueError as exc:
322
+ raise ValueError(f"{label} must be a positive integer, got {raw!r}") from exc
323
+ if value < 1:
324
+ raise ValueError(f"{label} must be >= 1, got {value}")
325
+ return value
326
+
327
+
328
+ def _parse_iterate_start_args(legacy_args: tuple[str, ...]) -> DaemonStartOptions:
329
+ env_overrides = ""
330
+ max_rounds: int | None = None
331
+ focus = ""
332
+ checkpoint_every: int | None = None
333
+ no_checkpoint = False
334
+ help_requested = False
335
+ index = 0
336
+ while index < len(legacy_args):
337
+ arg = legacy_args[index]
338
+ if arg in {"--help", "-h"}:
339
+ help_requested = True
340
+ elif arg == "--no-checkpoint":
341
+ no_checkpoint = True
342
+ elif arg == "--env":
343
+ if index + 1 >= len(legacy_args):
344
+ raise ValueError("--env requires a KEY=VALUE string")
345
+ index += 1
346
+ env_overrides = legacy_args[index]
347
+ elif arg.startswith("--env="):
348
+ env_overrides = arg.split("=", 1)[1]
349
+ elif arg == "--max-rounds":
350
+ if index + 1 >= len(legacy_args):
351
+ raise ValueError("--max-rounds requires a positive integer")
352
+ index += 1
353
+ max_rounds = _parse_positive_daemon_int(legacy_args[index], "--max-rounds")
354
+ elif arg.startswith("--max-rounds="):
355
+ max_rounds = _parse_positive_daemon_int(arg.split("=", 1)[1], "--max-rounds")
356
+ elif arg == "--focus":
357
+ if index + 1 >= len(legacy_args):
358
+ raise ValueError("--focus requires a value")
359
+ index += 1
360
+ focus = legacy_args[index]
361
+ elif arg.startswith("--focus="):
362
+ focus = arg.split("=", 1)[1]
363
+ elif arg == "--checkpoint-every":
364
+ if index + 1 >= len(legacy_args):
365
+ raise ValueError("--checkpoint-every requires a positive integer")
366
+ index += 1
367
+ checkpoint_every = _parse_positive_daemon_int(legacy_args[index], "--checkpoint-every")
368
+ elif arg.startswith("--checkpoint-every="):
369
+ checkpoint_every = _parse_positive_daemon_int(arg.split("=", 1)[1], "--checkpoint-every")
370
+ else:
371
+ raise ValueError(f"Unsupported option: {arg}")
372
+ index += 1
373
+ options = DaemonStartOptions(
374
+ list_path=None,
375
+ env_overrides=env_overrides,
376
+ max_rounds=max_rounds,
377
+ focus=focus,
378
+ checkpoint_every=checkpoint_every,
379
+ no_checkpoint=no_checkpoint,
380
+ help_requested=help_requested,
381
+ )
382
+ if not options.help_requested:
383
+ _daemon_env(options)
384
+ return options
385
+
386
+
387
+ def _parse_start_args(family: RunnerFamily | _DaemonTarget, legacy_args: tuple[str, ...]) -> DaemonStartOptions:
388
+ if family.kind == "iterate":
389
+ return _parse_iterate_start_args(legacy_args)
275
390
  env_overrides = ""
276
391
  features_filter = ""
277
392
  help_requested = False
@@ -320,7 +435,7 @@ def _parse_log_args(legacy_args: tuple[str, ...]) -> DaemonLogOptions:
320
435
  return DaemonLogOptions(lines=lines, follow=follow)
321
436
 
322
437
 
323
- def _payload_command(family: RunnerFamily, paths, list_path: Path, options: DaemonStartOptions) -> list[str]:
438
+ def _payload_command(family: RunnerFamily | _DaemonTarget, paths, list_path: Path | None, options: DaemonStartOptions) -> list[str]:
324
439
  command = [
325
440
  sys.executable,
326
441
  str(paths.pipeline_root / "cli.py"),
@@ -330,27 +445,49 @@ def _payload_command(family: RunnerFamily, paths, list_path: Path, options: Daem
330
445
  str(paths.pipeline_root),
331
446
  "run",
332
447
  family.kind,
333
- str(list_path),
334
448
  ]
449
+ if family.kind == "iterate":
450
+ if options.max_rounds is not None:
451
+ command.extend(["--max-rounds", str(options.max_rounds)])
452
+ if options.focus:
453
+ command.extend(["--focus", options.focus])
454
+ if options.checkpoint_every is not None:
455
+ command.extend(["--checkpoint-every", str(options.checkpoint_every)])
456
+ if options.no_checkpoint:
457
+ command.append("--no-checkpoint")
458
+ return command
459
+ assert list_path is not None
460
+ command.append(str(list_path))
335
461
  if family.kind == "feature" and options.features_filter:
336
462
  command.extend(["--features", options.features_filter])
337
463
  return command
338
464
 
339
465
 
466
+ def _strip_matching_outer_quotes(text: str) -> str:
467
+ if len(text) >= 2 and text[0] == text[-1] and text[0] in "'\"":
468
+ return text[1:-1]
469
+ return text
470
+
471
+
340
472
  def _daemon_env(options: DaemonStartOptions) -> dict[str, str]:
341
473
  env: dict[str, str] = {"PRIZMKIT_LIVE_OUTPUT": "0"}
342
474
  if not options.env_overrides.strip():
343
475
  return env
476
+ posix = os.name != "nt"
344
477
  try:
345
- tokens = shlex.split(options.env_overrides, posix=(os.name != "nt"))
478
+ tokens = shlex.split(options.env_overrides, posix=posix)
346
479
  except ValueError as exc:
347
480
  raise ValueError(f"Invalid --env syntax: {exc}") from exc
348
- for token in tokens:
481
+ for raw_token in tokens:
482
+ token = _strip_matching_outer_quotes(raw_token) if not posix else raw_token
483
+ token_unquoted = token != raw_token
349
484
  if "=" not in token:
350
- raise ValueError(f"Invalid --env token (expected KEY=VALUE): {token}")
485
+ raise ValueError(f"Invalid --env token (expected KEY=VALUE): {raw_token}")
351
486
  key, value = token.split("=", 1)
352
487
  if not _ENV_KEY_PATTERN.fullmatch(key):
353
488
  raise ValueError(f"Invalid --env variable name: {key!r}")
489
+ if not posix and not token_unquoted:
490
+ value = _strip_matching_outer_quotes(value)
354
491
  env[key] = value
355
492
  return env
356
493
 
@@ -375,15 +512,21 @@ def _read_pid(path: Path) -> int | None:
375
512
  return None
376
513
 
377
514
 
378
- def _write_meta(family: RunnerFamily, path: Path, pid: int, started_at: str, list_path: Path, options: DaemonStartOptions, log_file: Path) -> None:
515
+ def _write_meta(family: RunnerFamily | _DaemonTarget, path: Path, pid: int, started_at: str, list_path: Path | None, options: DaemonStartOptions, log_file: Path) -> None:
379
516
  data: dict[str, object] = {
380
517
  "pid": pid,
381
518
  "pipeline_type": family.kind,
382
519
  "started_at": started_at,
383
- LIST_META_KEY_BY_KIND[family.kind]: str(list_path),
384
520
  "env_overrides": options.env_overrides,
385
521
  "log_file": str(log_file),
386
522
  }
523
+ if family.kind == "iterate":
524
+ data["max_rounds"] = options.max_rounds
525
+ data["focus"] = options.focus
526
+ data["checkpoint_every"] = options.checkpoint_every
527
+ data["no_checkpoint"] = options.no_checkpoint
528
+ else:
529
+ data[LIST_META_KEY_BY_KIND[family.kind]] = str(list_path)
387
530
  write_json_atomic(path, data)
388
531
 
389
532
 
@@ -426,14 +569,24 @@ def _progress_summary(family: RunnerFamily, list_path: Path | None) -> dict[str,
426
569
  return {"total": total, **counts, "percent": percent}
427
570
 
428
571
 
429
- def _write_log_separator(family: RunnerFamily, log_file: Path, list_path: Path, started_at: str, options: DaemonStartOptions) -> None:
572
+ def _write_log_separator(family: RunnerFamily | _DaemonTarget, log_file: Path, list_path: Path | None, started_at: str, options: DaemonStartOptions) -> None:
430
573
  log_file.parent.mkdir(parents=True, exist_ok=True)
431
574
  lines = [
432
575
  "",
433
576
  "================================================================",
434
577
  f" {family.kind.title()} Pipeline Daemon Started: {started_at}",
435
- f" {family.kind.title()} list: {list_path}",
436
578
  ]
579
+ if list_path is not None:
580
+ lines.append(f" {family.kind.title()} list: {list_path}")
581
+ if family.kind == "iterate":
582
+ if options.max_rounds is not None:
583
+ lines.append(f" Max rounds: {options.max_rounds}")
584
+ if options.focus:
585
+ lines.append(f" Focus: {options.focus}")
586
+ if options.no_checkpoint:
587
+ lines.append(" Checkpoint review: disabled")
588
+ elif options.checkpoint_every is not None:
589
+ lines.append(f" Checkpoint every: {options.checkpoint_every}")
437
590
  if options.features_filter:
438
591
  lines.append(f" Features filter: {options.features_filter}")
439
592
  if options.env_overrides:
@@ -11,6 +11,7 @@ from .paths import RuntimePaths, resolve_runtime_paths
11
11
  UTILITY_ENTRYPOINTS = {
12
12
  "check-session-status": "scripts/check-session-status.py",
13
13
  "detect-stuck": "scripts/detect-stuck.py",
14
+ "feature-list-contract": "scripts/feature_list_contract.py",
14
15
  "generate-bootstrap-prompt": "scripts/generate-bootstrap-prompt.py",
15
16
  "generate-bugfix-prompt": "scripts/generate-bugfix-prompt.py",
16
17
  "init-bugfix-pipeline": "scripts/init-bugfix-pipeline.py",