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.
- package/bin/create-prizmkit.js +43 -12
- package/bundled/VERSION.json +3 -3
- package/bundled/dev-pipeline/.env.example +5 -0
- package/bundled/dev-pipeline/README.md +2 -1
- package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +111 -30
- package/bundled/dev-pipeline/prizmkit_runtime/cli.py +44 -3
- package/bundled/dev-pipeline/prizmkit_runtime/commands.py +29 -9
- package/bundled/dev-pipeline/prizmkit_runtime/config.py +121 -44
- package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +190 -37
- package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -0
- package/bundled/dev-pipeline/prizmkit_runtime/iterate.py +2480 -0
- package/bundled/dev-pipeline/prizmkit_runtime/paths.py +3 -0
- package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +32 -8
- package/bundled/dev-pipeline/prizmkit_runtime/runners.py +29 -12
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +13 -5
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +166 -0
- package/bundled/dev-pipeline/scripts/feature_list_contract.py +964 -0
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +18 -40
- package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +24 -19
- package/bundled/dev-pipeline/scripts/prompt_framework.py +24 -8
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +1 -63
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +8 -6
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +0 -10
- package/bundled/dev-pipeline/templates/feature-list-schema.json +8 -6
- package/bundled/dev-pipeline/templates/iterate/evaluate-prompt.md +97 -0
- package/bundled/dev-pipeline/templates/iterate/evaluation-schema.json +538 -0
- package/bundled/dev-pipeline/templates/iterate/headless-plan-prompt.md +66 -0
- package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +2 -2
- package/bundled/dev-pipeline/templates/sections/runtime-commit-handoff.md +13 -4
- package/bundled/rules/USAGE.md +15 -48
- package/bundled/rules/_rules-metadata.json +7 -14
- package/bundled/rules/general/coding-baseline.md +23 -0
- package/bundled/rules/prizm/prizm-progressive-loading.md +2 -2
- package/bundled/skills/_metadata.json +12 -42
- package/bundled/skills/app-planner/SKILL.md +2 -2
- package/bundled/skills/app-planner/references/generated-plan-review.md +2 -2
- package/bundled/skills/app-planner/references/project-state-detection.md +1 -1
- package/bundled/skills/app-planner/references/rules-configuration.md +158 -88
- package/bundled/skills/app-planner/scripts/validate-rules-configuration.py +543 -12
- package/bundled/skills/bug-planner/references/verification.md +4 -5
- package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +20 -14
- package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +49 -9
- package/bundled/skills/feature-pipeline-launcher/SKILL.md +20 -14
- package/bundled/skills/feature-pipeline-launcher/references/configuration.md +49 -9
- package/bundled/skills/feature-planner/SKILL.md +3 -3
- package/bundled/skills/feature-planner/references/browser-interaction.md +9 -29
- package/bundled/skills/iterate-pipeline-launcher/SKILL.md +273 -0
- package/bundled/skills/iterate-pipeline-launcher/references/configuration.md +105 -0
- package/bundled/skills/prizmkit-code-review/SKILL.md +10 -8
- package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +4 -1
- package/bundled/skills/prizmkit-code-review/references/review-report-template.md +2 -1
- package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +12 -8
- package/bundled/skills/prizmkit-implement/SKILL.md +2 -2
- package/bundled/skills/prizmkit-init/SKILL.md +10 -10
- package/bundled/skills/prizmkit-init/references/brownfield-deep-init.md +81 -0
- package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
- package/bundled/skills/prizmkit-plan/assets/plan-template.md +2 -0
- package/bundled/skills/prizmkit-prizm-docs/SKILL.md +8 -4
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +8 -7
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +33 -16
- package/bundled/skills/prizmkit-prizm-docs/references/op-validate.md +1 -1
- package/bundled/skills/prizmkit-retrospective/SKILL.md +29 -12
- package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json +126 -2
- package/bundled/skills/prizmkit-retrospective/references/rule-evolution-steps.md +86 -0
- package/bundled/skills/prizmkit-test/SKILL.md +2 -1
- package/bundled/skills/prizmkit-workflow/SKILL.md +8 -0
- package/bundled/skills/prizmkit-workflow/references/cold-start-rules.md +84 -0
- package/bundled/templates/project-memory-template.md +3 -3
- package/package.json +1 -1
- package/src/clean.js +2 -3
- package/src/config.js +52 -39
- package/src/index.js +29 -111
- package/src/prompts.js +20 -87
- package/src/runtime-passthrough.js +324 -0
- package/src/scaffold.js +41 -294
- package/src/upgrade.js +7 -39
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +0 -127
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +0 -124
- package/src/external-skills.js +0 -103
|
@@ -0,0 +1,964 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Deterministic feature-list.json validation, bounded context, and atomic mutation.
|
|
3
|
+
|
|
4
|
+
Maintains 100% contract parity with feature-planner/scripts/validate-and-generate.py
|
|
5
|
+
for validate, context, show, and append (--dry-run, --replace-tail), while extending
|
|
6
|
+
generate with --dry-run, atomic replacement writes, sequential F-001..F-00N checks
|
|
7
|
+
for initial creation, and appended_ids reporting for headless runtime use.
|
|
8
|
+
|
|
9
|
+
Python 3.10+ required. Standard library only.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import argparse
|
|
15
|
+
import collections
|
|
16
|
+
import copy
|
|
17
|
+
import json
|
|
18
|
+
import os
|
|
19
|
+
import re
|
|
20
|
+
import sys
|
|
21
|
+
import tempfile
|
|
22
|
+
from collections.abc import Mapping
|
|
23
|
+
from dataclasses import dataclass
|
|
24
|
+
from datetime import datetime, timezone
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any
|
|
27
|
+
|
|
28
|
+
# ---------------------------------------------------------------------------
|
|
29
|
+
# Constants (kept in 100% parity with feature-planner/scripts/validate-and-generate.py)
|
|
30
|
+
# ---------------------------------------------------------------------------
|
|
31
|
+
|
|
32
|
+
SCHEMA_VERSION = "dev-pipeline-feature-list-v1"
|
|
33
|
+
|
|
34
|
+
VALID_STATUSES = {
|
|
35
|
+
"pending",
|
|
36
|
+
"in_progress",
|
|
37
|
+
"completed",
|
|
38
|
+
"failed",
|
|
39
|
+
"skipped",
|
|
40
|
+
"split",
|
|
41
|
+
"auto_skipped",
|
|
42
|
+
}
|
|
43
|
+
VALID_COMPLEXITIES = {"low", "medium", "high", "critical"}
|
|
44
|
+
VALID_PRIORITIES = {"critical", "high", "medium", "low"}
|
|
45
|
+
ALLOWED_LIST_FIELDS = {
|
|
46
|
+
"$schema",
|
|
47
|
+
"project_name",
|
|
48
|
+
"project_description",
|
|
49
|
+
"created_at",
|
|
50
|
+
"created_by",
|
|
51
|
+
"features",
|
|
52
|
+
"global_context",
|
|
53
|
+
}
|
|
54
|
+
ALLOWED_GLOBAL_CONTEXT_FIELDS = {
|
|
55
|
+
"tech_stack",
|
|
56
|
+
"language",
|
|
57
|
+
"runtime",
|
|
58
|
+
"frontend_framework",
|
|
59
|
+
"frontend_styling",
|
|
60
|
+
"backend_framework",
|
|
61
|
+
"database",
|
|
62
|
+
"orm",
|
|
63
|
+
"design_system",
|
|
64
|
+
"testing_strategy",
|
|
65
|
+
"bundler",
|
|
66
|
+
"project_type",
|
|
67
|
+
}
|
|
68
|
+
CURRENT_FEATURE_FIELDS = {
|
|
69
|
+
"id",
|
|
70
|
+
"title",
|
|
71
|
+
"description",
|
|
72
|
+
"priority",
|
|
73
|
+
"estimated_complexity",
|
|
74
|
+
"dependencies",
|
|
75
|
+
"acceptance_criteria",
|
|
76
|
+
"status",
|
|
77
|
+
"model",
|
|
78
|
+
"completion_notes",
|
|
79
|
+
"user_context",
|
|
80
|
+
"browser_interaction",
|
|
81
|
+
"testing",
|
|
82
|
+
}
|
|
83
|
+
# Historical lists may still carry these keys. They are ignored residue, not
|
|
84
|
+
# current planning fields, and must not fail unknown-field validation.
|
|
85
|
+
LEFTOVER_IGNORED_FEATURE_FIELDS = {"session_granularity", "sub_features"}
|
|
86
|
+
FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
|
|
87
|
+
|
|
88
|
+
UI_KEYWORDS_RE = re.compile(
|
|
89
|
+
r"\b(click|button|modal|page|form|display|navigate|tab|input|opens|shows|"
|
|
90
|
+
r"renders|visible|redirect|download|upload|preview|select|toggle|dropdown|"
|
|
91
|
+
r"popup|toast|menu)\b",
|
|
92
|
+
re.IGNORECASE,
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
@dataclass(frozen=True)
|
|
97
|
+
class ContractOperationResult:
|
|
98
|
+
"""Structured result for programmatic append/generate/validate operations."""
|
|
99
|
+
|
|
100
|
+
ok: bool
|
|
101
|
+
exit_code: int
|
|
102
|
+
errors: tuple[str, ...] = ()
|
|
103
|
+
warnings: tuple[str, ...] = ()
|
|
104
|
+
appended_ids: tuple[str, ...] = ()
|
|
105
|
+
validation: dict[str, Any] | None = None
|
|
106
|
+
output_path: Path | None = None
|
|
107
|
+
dry_run: bool = False
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
# ---------------------------------------------------------------------------
|
|
111
|
+
# Helpers
|
|
112
|
+
# ---------------------------------------------------------------------------
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _err(msg: str) -> None:
|
|
116
|
+
print(f"ERROR: {msg}", file=sys.stderr)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _warn(msg: str) -> None:
|
|
120
|
+
print(f"WARNING: {msg}", file=sys.stderr)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def _info(msg: str) -> None:
|
|
124
|
+
print(f"INFO: {msg}", file=sys.stderr)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _load_json(path: str | Path) -> tuple[Any | None, str | None]:
|
|
128
|
+
file_path = Path(path)
|
|
129
|
+
if not file_path.is_file():
|
|
130
|
+
return None, f"File not found: {path}"
|
|
131
|
+
try:
|
|
132
|
+
with file_path.open("r", encoding="utf-8") as fh:
|
|
133
|
+
return json.load(fh), None
|
|
134
|
+
except json.JSONDecodeError as exc:
|
|
135
|
+
return None, f"JSON parse error in {path}: {exc}"
|
|
136
|
+
except Exception as exc:
|
|
137
|
+
return None, f"Failed to read {path}: {exc}"
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _write_json_atomic(path: str | Path, data: Any) -> None:
|
|
141
|
+
target = Path(path).resolve()
|
|
142
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
143
|
+
fd, temp_path = tempfile.mkstemp(
|
|
144
|
+
prefix=".feature-list-",
|
|
145
|
+
suffix=".tmp",
|
|
146
|
+
dir=str(target.parent),
|
|
147
|
+
)
|
|
148
|
+
try:
|
|
149
|
+
with os.fdopen(fd, "w", encoding="utf-8") as fh:
|
|
150
|
+
json.dump(data, fh, indent=2, ensure_ascii=False)
|
|
151
|
+
fh.write("\n")
|
|
152
|
+
fh.flush()
|
|
153
|
+
os.fsync(fh.fileno())
|
|
154
|
+
os.replace(temp_path, target)
|
|
155
|
+
except Exception:
|
|
156
|
+
try:
|
|
157
|
+
os.unlink(temp_path)
|
|
158
|
+
except OSError:
|
|
159
|
+
pass
|
|
160
|
+
raise
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
# ---------------------------------------------------------------------------
|
|
164
|
+
# Cycle detection (Kahn's algorithm)
|
|
165
|
+
# ---------------------------------------------------------------------------
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _detect_cycles(features: list[dict[str, Any]]) -> tuple[bool, int]:
|
|
169
|
+
"""Return (has_cycles, max_depth) using Kahn's topological sort."""
|
|
170
|
+
id_set = {f["id"] for f in features if isinstance(f, dict) and "id" in f}
|
|
171
|
+
adj: dict[str, list[str]] = {fid: [] for fid in id_set}
|
|
172
|
+
in_degree: dict[str, int] = {fid: 0 for fid in id_set}
|
|
173
|
+
|
|
174
|
+
for feat in features:
|
|
175
|
+
if not isinstance(feat, dict) or "id" not in feat:
|
|
176
|
+
continue
|
|
177
|
+
fid = feat["id"]
|
|
178
|
+
deps = feat.get("dependencies", [])
|
|
179
|
+
if not isinstance(deps, list):
|
|
180
|
+
continue
|
|
181
|
+
for dep in deps:
|
|
182
|
+
if dep in id_set:
|
|
183
|
+
adj[dep].append(fid)
|
|
184
|
+
in_degree[fid] += 1
|
|
185
|
+
|
|
186
|
+
queue = collections.deque(fid for fid, deg in in_degree.items() if deg == 0)
|
|
187
|
+
sorted_order: list[str] = []
|
|
188
|
+
depth: dict[str, int] = {fid: 0 for fid in id_set}
|
|
189
|
+
|
|
190
|
+
while queue:
|
|
191
|
+
node = queue.popleft()
|
|
192
|
+
sorted_order.append(node)
|
|
193
|
+
for neighbour in adj[node]:
|
|
194
|
+
in_degree[neighbour] -= 1
|
|
195
|
+
new_depth = depth[node] + 1
|
|
196
|
+
if new_depth > depth[neighbour]:
|
|
197
|
+
depth[neighbour] = new_depth
|
|
198
|
+
if in_degree[neighbour] == 0:
|
|
199
|
+
queue.append(neighbour)
|
|
200
|
+
|
|
201
|
+
has_cycles = len(sorted_order) != len(id_set)
|
|
202
|
+
max_depth = max(depth.values()) if depth else 0
|
|
203
|
+
return has_cycles, max_depth
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
detect_cycles = _detect_cycles
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
# ---------------------------------------------------------------------------
|
|
210
|
+
# Validation
|
|
211
|
+
# ---------------------------------------------------------------------------
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def _validate_browser_interaction(label: str, browser_interaction: Any, errors: list[str]) -> None:
|
|
215
|
+
if browser_interaction is None:
|
|
216
|
+
return
|
|
217
|
+
if not isinstance(browser_interaction, dict):
|
|
218
|
+
errors.append(f"{label}: browser_interaction must be an object")
|
|
219
|
+
return
|
|
220
|
+
tool = browser_interaction.get("tool")
|
|
221
|
+
if tool is not None and tool != "playwright-cli":
|
|
222
|
+
errors.append(
|
|
223
|
+
f"{label}: browser_interaction.tool must be 'playwright-cli', got {tool!r}"
|
|
224
|
+
)
|
|
225
|
+
blocking = browser_interaction.get("blocking")
|
|
226
|
+
if blocking is not None and not isinstance(blocking, bool):
|
|
227
|
+
errors.append(f"{label}: browser_interaction.blocking must be a boolean")
|
|
228
|
+
verify_steps = browser_interaction.get("verify_steps")
|
|
229
|
+
if verify_steps is not None:
|
|
230
|
+
if not isinstance(verify_steps, list) or not all(isinstance(s, str) for s in verify_steps):
|
|
231
|
+
errors.append(f"{label}: browser_interaction.verify_steps must be an array of strings")
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def validate_feature_list(data: Any, is_new_plan: bool = True) -> dict[str, Any]:
|
|
235
|
+
"""Validate a parsed feature-list structure in parity with validate-and-generate.py."""
|
|
236
|
+
errors: list[str] = []
|
|
237
|
+
warnings: list[str] = []
|
|
238
|
+
|
|
239
|
+
if not isinstance(data, dict):
|
|
240
|
+
return {
|
|
241
|
+
"valid": False,
|
|
242
|
+
"errors": ["Feature list root must be an object"],
|
|
243
|
+
"warnings": [],
|
|
244
|
+
"stats": {
|
|
245
|
+
"total_features": 0,
|
|
246
|
+
"complexity_distribution": {},
|
|
247
|
+
"max_dependency_depth": 0,
|
|
248
|
+
"has_cycles": False,
|
|
249
|
+
},
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
# 1. Top-level schema validation
|
|
253
|
+
unknown_root = set(data) - ALLOWED_LIST_FIELDS
|
|
254
|
+
if unknown_root:
|
|
255
|
+
errors.append(
|
|
256
|
+
"feature list has unknown fields: {}".format(", ".join(sorted(unknown_root)))
|
|
257
|
+
)
|
|
258
|
+
|
|
259
|
+
schema = data.get("$schema")
|
|
260
|
+
if schema != SCHEMA_VERSION:
|
|
261
|
+
errors.append(f"$schema must be '{SCHEMA_VERSION}', got '{schema}'")
|
|
262
|
+
|
|
263
|
+
project_name = data.get("project_name")
|
|
264
|
+
if not isinstance(project_name, str) or not project_name.strip():
|
|
265
|
+
errors.append("project_name must be a non-empty string")
|
|
266
|
+
|
|
267
|
+
global_context = data.get("global_context")
|
|
268
|
+
if global_context is not None:
|
|
269
|
+
if not isinstance(global_context, dict):
|
|
270
|
+
errors.append("global_context must be an object")
|
|
271
|
+
else:
|
|
272
|
+
unknown_context = set(global_context) - ALLOWED_GLOBAL_CONTEXT_FIELDS
|
|
273
|
+
if unknown_context:
|
|
274
|
+
errors.append(
|
|
275
|
+
"global_context has unknown fields: {}".format(
|
|
276
|
+
", ".join(sorted(unknown_context))
|
|
277
|
+
)
|
|
278
|
+
)
|
|
279
|
+
|
|
280
|
+
features = data.get("features")
|
|
281
|
+
if not isinstance(features, list) or len(features) == 0:
|
|
282
|
+
errors.append("features must be a non-empty array")
|
|
283
|
+
return {
|
|
284
|
+
"valid": False,
|
|
285
|
+
"errors": errors,
|
|
286
|
+
"warnings": warnings,
|
|
287
|
+
"stats": {
|
|
288
|
+
"total_features": 0,
|
|
289
|
+
"complexity_distribution": {},
|
|
290
|
+
"max_dependency_depth": 0,
|
|
291
|
+
"has_cycles": False,
|
|
292
|
+
},
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
# 2. Per-feature validation
|
|
296
|
+
required_keys = {
|
|
297
|
+
"id",
|
|
298
|
+
"title",
|
|
299
|
+
"description",
|
|
300
|
+
"priority",
|
|
301
|
+
"dependencies",
|
|
302
|
+
"acceptance_criteria",
|
|
303
|
+
"status",
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
seen_ids: set[Any] = set()
|
|
307
|
+
complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
|
|
308
|
+
has_frontend = bool(
|
|
309
|
+
isinstance(global_context, dict) and global_context.get("frontend_framework")
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
for idx, feat in enumerate(features):
|
|
313
|
+
label = f"features[{idx}]"
|
|
314
|
+
|
|
315
|
+
if not isinstance(feat, dict):
|
|
316
|
+
errors.append(f"{label} is not an object")
|
|
317
|
+
continue
|
|
318
|
+
|
|
319
|
+
missing = required_keys - set(feat.keys())
|
|
320
|
+
if missing:
|
|
321
|
+
errors.append(f"{label} missing required keys: {', '.join(sorted(missing))}")
|
|
322
|
+
|
|
323
|
+
unknown = set(feat.keys()) - CURRENT_FEATURE_FIELDS - LEFTOVER_IGNORED_FEATURE_FIELDS
|
|
324
|
+
if unknown:
|
|
325
|
+
errors.append(f"{label} has unknown fields: {', '.join(sorted(unknown))}")
|
|
326
|
+
|
|
327
|
+
fid = feat.get("id", "")
|
|
328
|
+
if not FEATURE_ID_RE.match(str(fid)):
|
|
329
|
+
errors.append(f"{label}: id '{fid}' does not match pattern F-NNN or F-NNN-X")
|
|
330
|
+
if fid in seen_ids:
|
|
331
|
+
errors.append(f"{label}: duplicate id '{fid}'")
|
|
332
|
+
seen_ids.add(fid)
|
|
333
|
+
|
|
334
|
+
for key in ("title", "description"):
|
|
335
|
+
val = feat.get(key)
|
|
336
|
+
if not isinstance(val, str) or not val.strip():
|
|
337
|
+
errors.append(f"{label}: {key} must be a non-empty string")
|
|
338
|
+
|
|
339
|
+
desc = feat.get("description", "")
|
|
340
|
+
if isinstance(desc, str) and desc.strip():
|
|
341
|
+
word_count = len(desc.split())
|
|
342
|
+
complexity = feat.get("estimated_complexity", "medium")
|
|
343
|
+
min_words = {
|
|
344
|
+
"low": 30,
|
|
345
|
+
"medium": 50,
|
|
346
|
+
"high": 80,
|
|
347
|
+
"critical": 100,
|
|
348
|
+
}.get(complexity, 50)
|
|
349
|
+
if word_count < 15:
|
|
350
|
+
errors.append(
|
|
351
|
+
f"{label}: description too short ({word_count} words, minimum 15). "
|
|
352
|
+
"Include: what to build, key behaviors, integration points, "
|
|
353
|
+
"and data model overview."
|
|
354
|
+
)
|
|
355
|
+
elif word_count < min_words:
|
|
356
|
+
warnings.append(
|
|
357
|
+
f"{label}: description only {word_count} words "
|
|
358
|
+
f"(recommend {min_words}+ for {complexity} complexity). "
|
|
359
|
+
"Richer descriptions produce better pipeline results."
|
|
360
|
+
)
|
|
361
|
+
|
|
362
|
+
priority = feat.get("priority")
|
|
363
|
+
if not (isinstance(priority, str) and priority in VALID_PRIORITIES):
|
|
364
|
+
errors.append(
|
|
365
|
+
f"{label}: priority must be one of 'critical', 'high', 'medium', 'low', got {priority!r}"
|
|
366
|
+
)
|
|
367
|
+
|
|
368
|
+
deps = feat.get("dependencies")
|
|
369
|
+
if not isinstance(deps, list):
|
|
370
|
+
errors.append(f"{label}: dependencies must be an array")
|
|
371
|
+
|
|
372
|
+
criteria = feat.get("acceptance_criteria")
|
|
373
|
+
if isinstance(criteria, list):
|
|
374
|
+
if len(criteria) < 1:
|
|
375
|
+
errors.append(f"{label}: must have at least 1 acceptance criterion")
|
|
376
|
+
elif len(criteria) < 3:
|
|
377
|
+
warnings.append(
|
|
378
|
+
f"{label}: only {len(criteria)} acceptance criteria (recommend at least 3)"
|
|
379
|
+
)
|
|
380
|
+
else:
|
|
381
|
+
errors.append(f"{label}: acceptance_criteria must be an array")
|
|
382
|
+
|
|
383
|
+
status = feat.get("status")
|
|
384
|
+
if status not in VALID_STATUSES:
|
|
385
|
+
errors.append(
|
|
386
|
+
f"{label}: status '{status}' invalid, must be one of: "
|
|
387
|
+
f"{', '.join(sorted(VALID_STATUSES))}"
|
|
388
|
+
)
|
|
389
|
+
if is_new_plan and status and status != "pending":
|
|
390
|
+
warnings.append(
|
|
391
|
+
f"{label}: status is '{status}' (expected 'pending' for new plans)"
|
|
392
|
+
)
|
|
393
|
+
|
|
394
|
+
complexity = feat.get("estimated_complexity")
|
|
395
|
+
if complexity is not None:
|
|
396
|
+
if complexity not in VALID_COMPLEXITIES:
|
|
397
|
+
errors.append(
|
|
398
|
+
f"{label}: estimated_complexity '{complexity}' invalid, must be one of: "
|
|
399
|
+
f"{', '.join(sorted(VALID_COMPLEXITIES))}"
|
|
400
|
+
)
|
|
401
|
+
else:
|
|
402
|
+
complexity_dist[complexity] += 1
|
|
403
|
+
|
|
404
|
+
_validate_browser_interaction(label, feat.get("browser_interaction"), errors)
|
|
405
|
+
|
|
406
|
+
if has_frontend and feat.get("status") != "completed":
|
|
407
|
+
criteria_list = feat.get("acceptance_criteria", [])
|
|
408
|
+
if isinstance(criteria_list, list):
|
|
409
|
+
criteria_text = " ".join(c for c in criteria_list if isinstance(c, str))
|
|
410
|
+
if UI_KEYWORDS_RE.search(criteria_text) and feat.get("browser_interaction") is None:
|
|
411
|
+
warnings.append(
|
|
412
|
+
f"{label}: has UI acceptance criteria but no browser_interaction "
|
|
413
|
+
"field. Consider adding browser verification."
|
|
414
|
+
)
|
|
415
|
+
|
|
416
|
+
# 3. Dependency validation
|
|
417
|
+
all_ids = {f.get("id") for f in features if isinstance(f, dict)}
|
|
418
|
+
for idx, feat in enumerate(features):
|
|
419
|
+
if not isinstance(feat, dict):
|
|
420
|
+
continue
|
|
421
|
+
label = f"features[{idx}]"
|
|
422
|
+
deps = feat.get("dependencies", [])
|
|
423
|
+
if isinstance(deps, list):
|
|
424
|
+
for dep in deps:
|
|
425
|
+
if dep not in all_ids:
|
|
426
|
+
errors.append(
|
|
427
|
+
f"{label}: dependency '{dep}' does not exist in feature list"
|
|
428
|
+
)
|
|
429
|
+
|
|
430
|
+
has_cycles, max_depth = _detect_cycles(features)
|
|
431
|
+
if has_cycles:
|
|
432
|
+
errors.append("Dependency graph contains cycles (not a valid DAG)")
|
|
433
|
+
|
|
434
|
+
return {
|
|
435
|
+
"valid": len(errors) == 0,
|
|
436
|
+
"errors": errors,
|
|
437
|
+
"warnings": warnings,
|
|
438
|
+
"stats": {
|
|
439
|
+
"total_features": len(features),
|
|
440
|
+
"complexity_distribution": complexity_dist,
|
|
441
|
+
"max_dependency_depth": max_depth,
|
|
442
|
+
"has_cycles": has_cycles,
|
|
443
|
+
},
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
# ---------------------------------------------------------------------------
|
|
448
|
+
# Bounded context, show, append, generate (Programmatic API)
|
|
449
|
+
# ---------------------------------------------------------------------------
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
def _next_top_level_id(features: list[dict[str, Any]]) -> str | None:
|
|
453
|
+
"""Return the next F-NNN ID, or None when numeric capacity is exhausted."""
|
|
454
|
+
numbers: list[int] = []
|
|
455
|
+
for feature in features:
|
|
456
|
+
match = FEATURE_ID_RE.match(str(feature.get("id", "")))
|
|
457
|
+
if match:
|
|
458
|
+
numbers.append(int(str(feature["id"])[2:5]))
|
|
459
|
+
next_number = max(numbers, default=0) + 1
|
|
460
|
+
if next_number > 999:
|
|
461
|
+
return None
|
|
462
|
+
return f"F-{next_number:03d}"
|
|
463
|
+
|
|
464
|
+
|
|
465
|
+
next_top_level_id = _next_top_level_id
|
|
466
|
+
|
|
467
|
+
|
|
468
|
+
def _load_valid_existing(path: str | Path) -> tuple[dict[str, Any] | None, dict[str, Any] | None, int, tuple[str, ...]]:
|
|
469
|
+
data, load_err = _load_json(path)
|
|
470
|
+
if load_err:
|
|
471
|
+
return None, None, 2, (load_err,)
|
|
472
|
+
if not isinstance(data, dict):
|
|
473
|
+
return None, None, 1, ("Feature list root must be an object",)
|
|
474
|
+
result = validate_feature_list(data, is_new_plan=False)
|
|
475
|
+
if not result["valid"]:
|
|
476
|
+
return None, result, 1, ("Existing feature list is invalid", *result["errors"])
|
|
477
|
+
return data, result, 0, ()
|
|
478
|
+
|
|
479
|
+
|
|
480
|
+
def extract_context(plan_path: str | Path) -> tuple[dict[str, Any] | None, int, tuple[str, ...]]:
|
|
481
|
+
"""Return bounded project context plus the five most recent features."""
|
|
482
|
+
data, _, exit_code, errors = _load_valid_existing(plan_path)
|
|
483
|
+
if exit_code or data is None:
|
|
484
|
+
return None, exit_code, errors
|
|
485
|
+
|
|
486
|
+
features = data["features"]
|
|
487
|
+
next_id = _next_top_level_id(features)
|
|
488
|
+
if next_id is None:
|
|
489
|
+
return None, 1, ("Feature ID capacity exhausted at F-999",)
|
|
490
|
+
|
|
491
|
+
context = {
|
|
492
|
+
"project_name": data.get("project_name"),
|
|
493
|
+
"project_description": data.get("project_description"),
|
|
494
|
+
"global_context": data.get("global_context") or {},
|
|
495
|
+
"task_count": len(features),
|
|
496
|
+
"next_id": next_id,
|
|
497
|
+
"recent_tasks": [
|
|
498
|
+
{"id": feature.get("id"), "description": feature.get("description")}
|
|
499
|
+
for feature in features[-5:]
|
|
500
|
+
],
|
|
501
|
+
}
|
|
502
|
+
return context, 0, ()
|
|
503
|
+
|
|
504
|
+
|
|
505
|
+
def show_feature(plan_path: str | Path, feature_id: str) -> tuple[dict[str, Any] | None, int, tuple[str, ...]]:
|
|
506
|
+
"""Return one explicitly requested top-level feature."""
|
|
507
|
+
data, _, exit_code, errors = _load_valid_existing(plan_path)
|
|
508
|
+
if exit_code or data is None:
|
|
509
|
+
return None, exit_code, errors
|
|
510
|
+
if not FEATURE_ID_RE.match(str(feature_id)):
|
|
511
|
+
return None, 1, (f"Feature ID '{feature_id}' must match F-NNN or F-NNN-X",)
|
|
512
|
+
|
|
513
|
+
for feature in data["features"]:
|
|
514
|
+
if feature.get("id") == feature_id:
|
|
515
|
+
return feature, 0, ()
|
|
516
|
+
return None, 1, (f"Feature '{feature_id}' not found",)
|
|
517
|
+
|
|
518
|
+
|
|
519
|
+
def _load_draft_source(draft_source: str | Path | Mapping[str, Any]) -> tuple[Any | None, str | None]:
|
|
520
|
+
if isinstance(draft_source, Mapping):
|
|
521
|
+
return copy.deepcopy(dict(draft_source)), None
|
|
522
|
+
return _load_json(draft_source)
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
def append_feature_list(
|
|
526
|
+
draft_source: str | Path | Mapping[str, Any],
|
|
527
|
+
output_path: str | Path,
|
|
528
|
+
*,
|
|
529
|
+
dry_run: bool = False,
|
|
530
|
+
replace_tail: bool = False,
|
|
531
|
+
) -> ContractOperationResult:
|
|
532
|
+
"""Validate and optionally atomically append an additions-only draft."""
|
|
533
|
+
target = Path(output_path)
|
|
534
|
+
base, _, exit_code, base_errors = _load_valid_existing(target)
|
|
535
|
+
if exit_code or base is None:
|
|
536
|
+
return ContractOperationResult(
|
|
537
|
+
ok=False,
|
|
538
|
+
exit_code=exit_code,
|
|
539
|
+
errors=base_errors,
|
|
540
|
+
output_path=target,
|
|
541
|
+
dry_run=dry_run,
|
|
542
|
+
)
|
|
543
|
+
|
|
544
|
+
draft, load_err = _load_draft_source(draft_source)
|
|
545
|
+
if load_err:
|
|
546
|
+
return ContractOperationResult(
|
|
547
|
+
ok=False,
|
|
548
|
+
exit_code=2,
|
|
549
|
+
errors=(load_err,),
|
|
550
|
+
output_path=target,
|
|
551
|
+
dry_run=dry_run,
|
|
552
|
+
)
|
|
553
|
+
if not isinstance(draft, dict) or set(draft.keys()) != {"features"}:
|
|
554
|
+
return ContractOperationResult(
|
|
555
|
+
ok=False,
|
|
556
|
+
exit_code=1,
|
|
557
|
+
errors=("Additions draft must be an object containing only 'features'",),
|
|
558
|
+
output_path=target,
|
|
559
|
+
dry_run=dry_run,
|
|
560
|
+
)
|
|
561
|
+
additions = draft.get("features")
|
|
562
|
+
if not isinstance(additions, list) or not additions:
|
|
563
|
+
return ContractOperationResult(
|
|
564
|
+
ok=False,
|
|
565
|
+
exit_code=1,
|
|
566
|
+
errors=("Additions draft 'features' must be a non-empty array",),
|
|
567
|
+
output_path=target,
|
|
568
|
+
dry_run=dry_run,
|
|
569
|
+
)
|
|
570
|
+
if not all(isinstance(feature, dict) for feature in additions):
|
|
571
|
+
return ContractOperationResult(
|
|
572
|
+
ok=False,
|
|
573
|
+
exit_code=1,
|
|
574
|
+
errors=("Every feature addition must be an object",),
|
|
575
|
+
output_path=target,
|
|
576
|
+
dry_run=dry_run,
|
|
577
|
+
)
|
|
578
|
+
|
|
579
|
+
merge_base = copy.deepcopy(base)
|
|
580
|
+
if replace_tail:
|
|
581
|
+
addition_ids = [feature.get("id") for feature in additions]
|
|
582
|
+
tail_ids = [feature.get("id") for feature in base["features"][-len(additions) :]]
|
|
583
|
+
if len(base["features"]) < len(additions) or tail_ids != addition_ids:
|
|
584
|
+
return ContractOperationResult(
|
|
585
|
+
ok=False,
|
|
586
|
+
exit_code=1,
|
|
587
|
+
errors=(
|
|
588
|
+
"--replace-tail requires additions IDs to match the existing final-list suffix exactly",
|
|
589
|
+
),
|
|
590
|
+
output_path=target,
|
|
591
|
+
dry_run=dry_run,
|
|
592
|
+
)
|
|
593
|
+
merge_base["features"] = merge_base["features"][: -len(additions)]
|
|
594
|
+
|
|
595
|
+
next_id = _next_top_level_id(merge_base["features"])
|
|
596
|
+
if next_id is None:
|
|
597
|
+
return ContractOperationResult(
|
|
598
|
+
ok=False,
|
|
599
|
+
exit_code=1,
|
|
600
|
+
errors=("Feature ID capacity exhausted at F-999",),
|
|
601
|
+
output_path=target,
|
|
602
|
+
dry_run=dry_run,
|
|
603
|
+
)
|
|
604
|
+
start_number = int(next_id[2:])
|
|
605
|
+
prepared = copy.deepcopy(additions)
|
|
606
|
+
for offset, feature in enumerate(prepared):
|
|
607
|
+
expected_id = f"F-{start_number + offset:03d}"
|
|
608
|
+
if start_number + offset > 999:
|
|
609
|
+
return ContractOperationResult(
|
|
610
|
+
ok=False,
|
|
611
|
+
exit_code=1,
|
|
612
|
+
errors=("Feature ID capacity exhausted at F-999",),
|
|
613
|
+
output_path=target,
|
|
614
|
+
dry_run=dry_run,
|
|
615
|
+
)
|
|
616
|
+
if feature.get("id") != expected_id:
|
|
617
|
+
return ContractOperationResult(
|
|
618
|
+
ok=False,
|
|
619
|
+
exit_code=1,
|
|
620
|
+
errors=(f"Feature addition {offset} must use next sequential ID '{expected_id}'",),
|
|
621
|
+
output_path=target,
|
|
622
|
+
dry_run=dry_run,
|
|
623
|
+
)
|
|
624
|
+
feature.setdefault("status", "pending")
|
|
625
|
+
|
|
626
|
+
merged = copy.deepcopy(merge_base)
|
|
627
|
+
merged["features"].extend(prepared)
|
|
628
|
+
result = validate_feature_list(merged, is_new_plan=False)
|
|
629
|
+
appended_ids = tuple(feature["id"] for feature in prepared)
|
|
630
|
+
result["appended_ids"] = list(appended_ids)
|
|
631
|
+
if not result["valid"]:
|
|
632
|
+
return ContractOperationResult(
|
|
633
|
+
ok=False,
|
|
634
|
+
exit_code=1,
|
|
635
|
+
errors=tuple(result["errors"]),
|
|
636
|
+
warnings=tuple(result["warnings"]),
|
|
637
|
+
appended_ids=appended_ids,
|
|
638
|
+
validation=result,
|
|
639
|
+
output_path=target,
|
|
640
|
+
dry_run=dry_run,
|
|
641
|
+
)
|
|
642
|
+
|
|
643
|
+
if dry_run:
|
|
644
|
+
return ContractOperationResult(
|
|
645
|
+
ok=True,
|
|
646
|
+
exit_code=0,
|
|
647
|
+
warnings=tuple(result["warnings"]),
|
|
648
|
+
appended_ids=appended_ids,
|
|
649
|
+
validation=result,
|
|
650
|
+
output_path=target,
|
|
651
|
+
dry_run=True,
|
|
652
|
+
)
|
|
653
|
+
|
|
654
|
+
try:
|
|
655
|
+
_write_json_atomic(target, merged)
|
|
656
|
+
except Exception as exc:
|
|
657
|
+
return ContractOperationResult(
|
|
658
|
+
ok=False,
|
|
659
|
+
exit_code=2,
|
|
660
|
+
errors=(f"Failed to write merged feature list: {exc}",),
|
|
661
|
+
warnings=tuple(result["warnings"]),
|
|
662
|
+
appended_ids=appended_ids,
|
|
663
|
+
validation=result,
|
|
664
|
+
output_path=target,
|
|
665
|
+
dry_run=False,
|
|
666
|
+
)
|
|
667
|
+
|
|
668
|
+
return ContractOperationResult(
|
|
669
|
+
ok=True,
|
|
670
|
+
exit_code=0,
|
|
671
|
+
warnings=tuple(result["warnings"]),
|
|
672
|
+
appended_ids=appended_ids,
|
|
673
|
+
validation=result,
|
|
674
|
+
output_path=target,
|
|
675
|
+
dry_run=False,
|
|
676
|
+
)
|
|
677
|
+
|
|
678
|
+
|
|
679
|
+
def generate_feature_list(
|
|
680
|
+
draft_source: str | Path | Mapping[str, Any],
|
|
681
|
+
output_path: str | Path,
|
|
682
|
+
*,
|
|
683
|
+
dry_run: bool = False,
|
|
684
|
+
require_sequential_ids: bool = False,
|
|
685
|
+
default_created_by: str = "feature-planner",
|
|
686
|
+
) -> ContractOperationResult:
|
|
687
|
+
"""Validate a full feature-list draft and optionally write it atomically."""
|
|
688
|
+
target = Path(output_path)
|
|
689
|
+
raw_data, load_err = _load_draft_source(draft_source)
|
|
690
|
+
if load_err:
|
|
691
|
+
return ContractOperationResult(
|
|
692
|
+
ok=False,
|
|
693
|
+
exit_code=2,
|
|
694
|
+
errors=(load_err,),
|
|
695
|
+
output_path=target,
|
|
696
|
+
dry_run=dry_run,
|
|
697
|
+
)
|
|
698
|
+
if not isinstance(raw_data, dict):
|
|
699
|
+
return ContractOperationResult(
|
|
700
|
+
ok=False,
|
|
701
|
+
exit_code=1,
|
|
702
|
+
errors=("Feature list root must be an object",),
|
|
703
|
+
output_path=target,
|
|
704
|
+
dry_run=dry_run,
|
|
705
|
+
)
|
|
706
|
+
|
|
707
|
+
data = copy.deepcopy(raw_data)
|
|
708
|
+
now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
709
|
+
data.setdefault("$schema", SCHEMA_VERSION)
|
|
710
|
+
data.setdefault("created_at", now)
|
|
711
|
+
data.setdefault("created_by", default_created_by)
|
|
712
|
+
|
|
713
|
+
features = data.get("features")
|
|
714
|
+
if isinstance(features, list):
|
|
715
|
+
for feature in features:
|
|
716
|
+
if isinstance(feature, dict):
|
|
717
|
+
feature.setdefault("status", "pending")
|
|
718
|
+
|
|
719
|
+
is_new_plan = not target.exists()
|
|
720
|
+
result = validate_feature_list(data, is_new_plan=is_new_plan)
|
|
721
|
+
|
|
722
|
+
extra_errors: list[str] = []
|
|
723
|
+
if require_sequential_ids and isinstance(features, list) and features:
|
|
724
|
+
for offset, feature in enumerate(features):
|
|
725
|
+
expected_id = f"F-{offset + 1:03d}"
|
|
726
|
+
if not isinstance(feature, dict):
|
|
727
|
+
continue
|
|
728
|
+
if feature.get("id") != expected_id:
|
|
729
|
+
extra_errors.append(
|
|
730
|
+
f"features[{offset}]: initial feature list must use sequential ID '{expected_id}'"
|
|
731
|
+
)
|
|
732
|
+
first_deps = features[0].get("dependencies") if isinstance(features[0], dict) else None
|
|
733
|
+
if isinstance(first_deps, list) and first_deps:
|
|
734
|
+
extra_errors.append("features[0]: F-001 must have an empty dependencies array")
|
|
735
|
+
|
|
736
|
+
if extra_errors:
|
|
737
|
+
result["errors"].extend(extra_errors)
|
|
738
|
+
result["valid"] = False
|
|
739
|
+
|
|
740
|
+
appended_ids = (
|
|
741
|
+
tuple(str(f.get("id", "")) for f in features if isinstance(f, dict) and f.get("id"))
|
|
742
|
+
if isinstance(features, list)
|
|
743
|
+
else ()
|
|
744
|
+
)
|
|
745
|
+
result["appended_ids"] = list(appended_ids)
|
|
746
|
+
|
|
747
|
+
if not result["valid"]:
|
|
748
|
+
return ContractOperationResult(
|
|
749
|
+
ok=False,
|
|
750
|
+
exit_code=1,
|
|
751
|
+
errors=tuple(result["errors"]),
|
|
752
|
+
warnings=tuple(result["warnings"]),
|
|
753
|
+
appended_ids=appended_ids,
|
|
754
|
+
validation=result,
|
|
755
|
+
output_path=target,
|
|
756
|
+
dry_run=dry_run,
|
|
757
|
+
)
|
|
758
|
+
|
|
759
|
+
if dry_run:
|
|
760
|
+
return ContractOperationResult(
|
|
761
|
+
ok=True,
|
|
762
|
+
exit_code=0,
|
|
763
|
+
warnings=tuple(result["warnings"]),
|
|
764
|
+
appended_ids=appended_ids,
|
|
765
|
+
validation=result,
|
|
766
|
+
output_path=target,
|
|
767
|
+
dry_run=True,
|
|
768
|
+
)
|
|
769
|
+
|
|
770
|
+
try:
|
|
771
|
+
_write_json_atomic(target, data)
|
|
772
|
+
except Exception as exc:
|
|
773
|
+
return ContractOperationResult(
|
|
774
|
+
ok=False,
|
|
775
|
+
exit_code=2,
|
|
776
|
+
errors=(f"Failed to write generated feature list: {exc}",),
|
|
777
|
+
warnings=tuple(result["warnings"]),
|
|
778
|
+
appended_ids=appended_ids,
|
|
779
|
+
validation=result,
|
|
780
|
+
output_path=target,
|
|
781
|
+
dry_run=False,
|
|
782
|
+
)
|
|
783
|
+
|
|
784
|
+
return ContractOperationResult(
|
|
785
|
+
ok=True,
|
|
786
|
+
exit_code=0,
|
|
787
|
+
warnings=tuple(result["warnings"]),
|
|
788
|
+
appended_ids=appended_ids,
|
|
789
|
+
validation=result,
|
|
790
|
+
output_path=target,
|
|
791
|
+
dry_run=False,
|
|
792
|
+
)
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
# ---------------------------------------------------------------------------
|
|
796
|
+
# CLI
|
|
797
|
+
# ---------------------------------------------------------------------------
|
|
798
|
+
|
|
799
|
+
|
|
800
|
+
def cmd_validate(args: argparse.Namespace) -> int:
|
|
801
|
+
data, load_err = _load_json(args.input)
|
|
802
|
+
if load_err:
|
|
803
|
+
_err(load_err)
|
|
804
|
+
result = {
|
|
805
|
+
"valid": False,
|
|
806
|
+
"errors": [load_err],
|
|
807
|
+
"warnings": [],
|
|
808
|
+
"stats": {
|
|
809
|
+
"total_features": 0,
|
|
810
|
+
"complexity_distribution": {},
|
|
811
|
+
"max_dependency_depth": 0,
|
|
812
|
+
"has_cycles": False,
|
|
813
|
+
},
|
|
814
|
+
}
|
|
815
|
+
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
816
|
+
return 2
|
|
817
|
+
|
|
818
|
+
result = validate_feature_list(data, is_new_plan=False)
|
|
819
|
+
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
820
|
+
if result["valid"]:
|
|
821
|
+
_info(f"Validation passed with {len(result['warnings'])} warning(s)")
|
|
822
|
+
else:
|
|
823
|
+
_err(
|
|
824
|
+
f"Validation failed with {len(result['errors'])} error(s) "
|
|
825
|
+
f"and {len(result['warnings'])} warning(s)"
|
|
826
|
+
)
|
|
827
|
+
for err in result["errors"]:
|
|
828
|
+
_err(" " + err)
|
|
829
|
+
for warn in result["warnings"]:
|
|
830
|
+
_warn(" " + warn)
|
|
831
|
+
if args.output and result["valid"]:
|
|
832
|
+
_write_json_atomic(args.output, data)
|
|
833
|
+
_info(f"Validated output written to {args.output}")
|
|
834
|
+
return 0 if result["valid"] else 1
|
|
835
|
+
|
|
836
|
+
|
|
837
|
+
def cmd_context(args: argparse.Namespace) -> int:
|
|
838
|
+
context, exit_code, errors = extract_context(args.input)
|
|
839
|
+
if exit_code or context is None:
|
|
840
|
+
for error in errors:
|
|
841
|
+
_err(error)
|
|
842
|
+
return exit_code
|
|
843
|
+
print(json.dumps(context, indent=2, ensure_ascii=False))
|
|
844
|
+
return 0
|
|
845
|
+
|
|
846
|
+
|
|
847
|
+
def cmd_show(args: argparse.Namespace) -> int:
|
|
848
|
+
feature, exit_code, errors = show_feature(args.input, args.id)
|
|
849
|
+
if exit_code or feature is None:
|
|
850
|
+
for error in errors:
|
|
851
|
+
_err(error)
|
|
852
|
+
return exit_code
|
|
853
|
+
print(json.dumps(feature, indent=2, ensure_ascii=False))
|
|
854
|
+
return 0
|
|
855
|
+
|
|
856
|
+
|
|
857
|
+
def cmd_append(args: argparse.Namespace) -> int:
|
|
858
|
+
op = append_feature_list(
|
|
859
|
+
args.input,
|
|
860
|
+
args.output,
|
|
861
|
+
dry_run=bool(args.dry_run),
|
|
862
|
+
replace_tail=bool(args.replace_tail),
|
|
863
|
+
)
|
|
864
|
+
if op.validation is not None:
|
|
865
|
+
print(json.dumps(op.validation, indent=2, ensure_ascii=False))
|
|
866
|
+
if not op.ok:
|
|
867
|
+
for error in op.errors:
|
|
868
|
+
_err(error)
|
|
869
|
+
return op.exit_code
|
|
870
|
+
if op.dry_run:
|
|
871
|
+
_info(f"Dry run: {len(op.appended_ids)} feature(s) would be appended to {args.output}")
|
|
872
|
+
else:
|
|
873
|
+
_info(f"Appended {len(op.appended_ids)} feature(s) to {args.output}")
|
|
874
|
+
return 0
|
|
875
|
+
|
|
876
|
+
|
|
877
|
+
def cmd_generate(args: argparse.Namespace) -> int:
|
|
878
|
+
if args.input == "-":
|
|
879
|
+
try:
|
|
880
|
+
source: Any = json.load(sys.stdin)
|
|
881
|
+
except json.JSONDecodeError as exc:
|
|
882
|
+
_err(f"Invalid JSON from stdin: {exc}")
|
|
883
|
+
return 2
|
|
884
|
+
else:
|
|
885
|
+
source = args.input
|
|
886
|
+
op = generate_feature_list(
|
|
887
|
+
source,
|
|
888
|
+
args.output,
|
|
889
|
+
dry_run=bool(args.dry_run),
|
|
890
|
+
require_sequential_ids=bool(args.require_sequential_ids),
|
|
891
|
+
)
|
|
892
|
+
if op.validation is not None:
|
|
893
|
+
print(json.dumps(op.validation, indent=2, ensure_ascii=False))
|
|
894
|
+
if not op.ok:
|
|
895
|
+
for error in op.errors:
|
|
896
|
+
_err(error)
|
|
897
|
+
for warning in op.warnings:
|
|
898
|
+
_warn(warning)
|
|
899
|
+
return op.exit_code
|
|
900
|
+
if op.dry_run:
|
|
901
|
+
_info(f"Dry run: {len(op.appended_ids)} feature(s) validated for {args.output}")
|
|
902
|
+
else:
|
|
903
|
+
_info(f"Generated feature-list written to {args.output}")
|
|
904
|
+
return 0
|
|
905
|
+
|
|
906
|
+
|
|
907
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
908
|
+
parser = argparse.ArgumentParser(
|
|
909
|
+
description="Deterministic feature-list.json contract validator and atomic writer.",
|
|
910
|
+
)
|
|
911
|
+
subparsers = parser.add_subparsers(dest="command", help="Command to execute")
|
|
912
|
+
|
|
913
|
+
p_validate = subparsers.add_parser("validate", help="Validate an existing feature-list.json")
|
|
914
|
+
p_validate.add_argument("--input", required=True, help="Path to input feature-list.json")
|
|
915
|
+
p_validate.add_argument("--output", help="Optional path to write validated output")
|
|
916
|
+
|
|
917
|
+
p_context = subparsers.add_parser("context", help="Print bounded root context and 5 recent features")
|
|
918
|
+
p_context.add_argument("--input", required=True, help="Path to existing feature-list.json")
|
|
919
|
+
|
|
920
|
+
p_show = subparsers.add_parser("show", help="Print one top-level feature by ID")
|
|
921
|
+
p_show.add_argument("--input", required=True, help="Path to existing feature-list.json")
|
|
922
|
+
p_show.add_argument("--id", required=True, help="Exact top-level feature ID")
|
|
923
|
+
|
|
924
|
+
p_append = subparsers.add_parser("append", help="Append additions-only draft atomically")
|
|
925
|
+
p_append.add_argument("--input", required=True, help="Path to additions-only draft JSON")
|
|
926
|
+
p_append.add_argument("--output", required=True, help="Path to existing feature-list.json")
|
|
927
|
+
p_append.add_argument("--replace-tail", action="store_true", help="Replace exact matching suffix")
|
|
928
|
+
p_append.add_argument("--dry-run", action="store_true", help="Validate merge without writing")
|
|
929
|
+
|
|
930
|
+
p_generate = subparsers.add_parser("generate", help="Validate full draft and write atomically")
|
|
931
|
+
p_generate.add_argument("--input", required=True, help="Path to full draft JSON (or '-' for stdin)")
|
|
932
|
+
p_generate.add_argument("--output", required=True, help="Path to write feature-list.json")
|
|
933
|
+
p_generate.add_argument("--dry-run", action="store_true", help="Validate generation without writing")
|
|
934
|
+
p_generate.add_argument(
|
|
935
|
+
"--require-sequential-ids",
|
|
936
|
+
action="store_true",
|
|
937
|
+
help="Require sequential F-001..F-00N IDs and empty F-001 dependencies",
|
|
938
|
+
)
|
|
939
|
+
|
|
940
|
+
return parser
|
|
941
|
+
|
|
942
|
+
|
|
943
|
+
def main(argv: list[str] | None = None) -> int:
|
|
944
|
+
parser = build_parser()
|
|
945
|
+
args = parser.parse_args(argv)
|
|
946
|
+
if not args.command:
|
|
947
|
+
parser.print_help(sys.stderr)
|
|
948
|
+
return 2
|
|
949
|
+
dispatch = {
|
|
950
|
+
"validate": cmd_validate,
|
|
951
|
+
"context": cmd_context,
|
|
952
|
+
"show": cmd_show,
|
|
953
|
+
"append": cmd_append,
|
|
954
|
+
"generate": cmd_generate,
|
|
955
|
+
}
|
|
956
|
+
handler = dispatch.get(args.command)
|
|
957
|
+
if handler is None:
|
|
958
|
+
_err(f"Unknown command: {args.command}")
|
|
959
|
+
return 2
|
|
960
|
+
return handler(args)
|
|
961
|
+
|
|
962
|
+
|
|
963
|
+
if __name__ == "__main__":
|
|
964
|
+
raise SystemExit(main())
|