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
@@ -1,15 +1,17 @@
1
1
  #!/usr/bin/env python3
2
- """Validate app-planner Rules Configuration resources as one coherent contract."""
2
+ """Validate app-planner Rules Configuration resources and generated layer-rules outputs."""
3
3
 
4
4
  from __future__ import annotations
5
5
 
6
6
  import argparse
7
+ from dataclasses import dataclass, field
7
8
  import json
8
- import re
9
9
  from pathlib import Path
10
+ import re
10
11
  from typing import Any
11
12
 
12
13
  LAYERS = ("frontend", "backend", "database", "mobile")
14
+ ALLOWED_OUTPUT_FILENAMES = {f"{layer}-rules.md": layer for layer in LAYERS}
13
15
  SCHEMA_VERSION = "app-planner-question-manifest-v2"
14
16
  REQUIRED_RENDER_CONTRACT = {
15
17
  "fixed_rules_policy": "invariants_only",
@@ -40,6 +42,206 @@ FIXED_RULE_FORBIDDEN_PATTERNS = (
40
42
  "all deep links must use universal links",
41
43
  )
42
44
 
45
+ # Output validation constants and contracts
46
+ OUTPUT_SOFT_WARN_BYTES = 12 * 1024 # 12 KB
47
+ OUTPUT_HARD_MAX_BYTES = 16 * 1024 # 16 KB
48
+ MAX_EVOLVED_ENTRIES = 20
49
+
50
+ UNIFIED_SECTIONS = (
51
+ "## 1. Confirmed Stack & Scope Decisions",
52
+ "## 2. Invariant Baseline",
53
+ "## 3. Stack-Specific Rules",
54
+ "## 4. AI Change Permissions & Active Deny List",
55
+ "## 5. Project-Evolved Rules",
56
+ )
57
+ COLD_START_SECTIONS = (
58
+ "## 1. Verified Stack Summary",
59
+ "## 2. High-Signal Rules",
60
+ "## 3. Change Boundaries",
61
+ "## 4. Override Precedence",
62
+ "## 5. Project-Evolved Rules",
63
+ )
64
+ PROVENANCE_TOKENS = (
65
+ "verified-from-code",
66
+ "confirmed-by-user",
67
+ "ai-inferred-default",
68
+ )
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class ModeContract:
73
+ """Required headers and sections for one generated layer-rules mode."""
74
+
75
+ name: str
76
+ required_headers: tuple[str, ...]
77
+ required_sections: tuple[str, ...]
78
+ expected_owner: str | None = None
79
+ check_provenance_warning: bool = False
80
+
81
+
82
+ MODE_CONTRACTS: dict[str, ModeContract] = {
83
+ "ai-synthesized": ModeContract(
84
+ name="ai-synthesized",
85
+ required_headers=("owner", "mode", "layer", "stack snapshot"),
86
+ required_sections=UNIFIED_SECTIONS,
87
+ expected_owner="app-planner",
88
+ check_provenance_warning=True,
89
+ ),
90
+ "manual-questionnaire": ModeContract(
91
+ name="manual-questionnaire",
92
+ required_headers=("owner", "mode", "layer", "stack snapshot"),
93
+ required_sections=UNIFIED_SECTIONS,
94
+ expected_owner="app-planner",
95
+ check_provenance_warning=False,
96
+ ),
97
+ "cold-start-lightweight": ModeContract(
98
+ name="cold-start-lightweight",
99
+ required_headers=("mode",),
100
+ required_sections=COLD_START_SECTIONS,
101
+ expected_owner=None,
102
+ check_provenance_warning=False,
103
+ ),
104
+ }
105
+
106
+
107
+ @dataclass
108
+ class OutputFileReport:
109
+ """Validation result for a single generated layer-rules file."""
110
+
111
+ path: str
112
+ layer: str | None = None
113
+ mode: str | None = None
114
+ bytes: int = 0
115
+ evolved_count: int = 0
116
+ warnings: list[str] = field(default_factory=list)
117
+ errors: list[str] = field(default_factory=list)
118
+
119
+ def to_dict(self) -> dict[str, Any]:
120
+ return {
121
+ "path": self.path,
122
+ "layer": self.layer,
123
+ "mode": self.mode,
124
+ "bytes": self.bytes,
125
+ "evolved_count": self.evolved_count,
126
+ "valid": not self.errors,
127
+ "warnings": self.warnings,
128
+ "errors": self.errors,
129
+ }
130
+
131
+
132
+ HEADER_LINE_RE = re.compile(r"^\s*(?:>\s*)?([A-Za-z][A-Za-z ]*?)\s*:\s*(.+?)\s*$")
133
+ H2_HEADING_RE = re.compile(r"^##\s+.+$", re.MULTILINE)
134
+ HTML_COMMENT_RE = re.compile(r"<!--[\s\S]*?-->")
135
+ LIST_ITEM_RE = re.compile(r"^\s*(?:[-*+]|\d+\.)\s+\S", re.MULTILINE)
136
+
137
+ UNRESOLVED_PLACEHOLDER_RE = re.compile(r"\{\{\s*(?:[A-Za-z0-9_.-]+|\.\.\.)\s*\}\}")
138
+ RAW_QUESTION_ID_RE = re.compile(r"(?<![A-Za-z0-9_])Q(?:[1-9]|[12][0-9])[a-z]?(?![A-Za-z0-9_])")
139
+ OPTION_SHORTHAND_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
140
+ ("Chinese option shorthand", re.compile(r"(?:方案|选项)\s*[A-Za-z](?![A-Za-z0-9_])")),
141
+ (
142
+ "option-letter shorthand",
143
+ re.compile(
144
+ r"(?<![A-Za-z0-9_])(?i:use\s+|choose\s+|select(?:ed)?\s+)?(?i:option|choice)\s+[A-F](?![A-Za-z0-9_])",
145
+ ),
146
+ ),
147
+ ("manifest option-ID expression", re.compile(r"(?:==|!=)\s*[A-F](?![A-Za-z0-9_])")),
148
+ ("manifest option-set expression", re.compile(r"(?<![A-Za-z0-9_])in\s*\[[A-F](?:,\s*[A-F])*\]")),
149
+ (
150
+ "blanket recommendation or conversational shorthand",
151
+ re.compile(
152
+ r"(?:按推荐走|全部按照推荐|所有问题都按你的推荐处理|use all recommendations"
153
+ r"|go with your recommendation|same as above|as discussed earlier"
154
+ r"|用户本轮回答|【Recommended】)",
155
+ re.IGNORECASE,
156
+ ),
157
+ ),
158
+ )
159
+ TRANSCRIPT_PROVENANCE_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
160
+ ("original-response annotation", re.compile(r"\(?\s*original\s+response\s*:", re.IGNORECASE)),
161
+ ("Chinese transcript provenance", re.compile(r"(?:用户回答|用户选择)\s*[::]")),
162
+ (
163
+ "English transcript provenance",
164
+ re.compile(
165
+ r"\b(?:user\s+(?:answered|replied|said|chose)|assistant\s+(?:asked|recommended))\s*:",
166
+ re.IGNORECASE,
167
+ ),
168
+ ),
169
+ ("dialogue-role prefix", re.compile(r"^\s*(?:User|Assistant|Human)\s*:", re.MULTILINE)),
170
+ ("transient brainstorm path", re.compile(r"\.agents/brainstorm/")),
171
+ )
172
+ PLATFORM_PATH_RE = re.compile(
173
+ r"(?:\.claude/(?:skills|commands|command-assets)/"
174
+ r"|\.codebuddy/skills/"
175
+ r"|\.agents/(?:skills|plugins)/"
176
+ r"|\.cursor/skills/"
177
+ r"|\.pi/skills/)"
178
+ )
179
+ RETIRED_SKILL_RE = re.compile(
180
+ r"(?:generated by the\s+)?`(?:frontend|backend|database|mobile)-rules`\s+skill"
181
+ r"|\b(?:frontend|backend|database|mobile)-rules\s+skill\b"
182
+ r"|/(?:frontend|backend|database|mobile)-rules(?!\.md)\b",
183
+ re.IGNORECASE,
184
+ )
185
+ WORKFLOW_TASK_ID_RE = re.compile(r"(?<![A-Za-z0-9_])(?:F|B|R|T)-\d{3,}(?![A-Za-z0-9_])")
186
+ CHECKPOINT_ID_RE = re.compile(r"(?<![A-Za-z0-9_])CP-(?:AP|FP|BP)-\d+(?:\.\d+)?(?![A-Za-z0-9_])")
187
+ ARTIFACT_PATH_RE = re.compile(r"\.prizmkit/(?:specs|dev-pipeline|state)/")
188
+ SESSION_META_RE = re.compile(r"\b(?:session_id|run_id|pipeline_id|workflow_id)\s*[:=]", re.IGNORECASE)
189
+ BRANCH_HEADER_RE = re.compile(r"^\s*(?:>\s*)?(?:Branch|Git\s+Branch)\s*:\s*\S+", re.IGNORECASE | re.MULTILINE)
190
+ BRANCH_NAME_RE = re.compile(r"(?<![A-Za-z0-9_./-])(?:feature|bugfix|hotfix|release)/[A-Za-z0-9._-]+")
191
+
192
+ DEP_FORBID_RE = re.compile(
193
+ r"\b(?:never|forbid(?:den|s)?|prohibit(?:ed|s)?|must\s+not|do\s+not)\b"
194
+ r"(?:"
195
+ r".{0,60}\b(?:add(?:ing)?|install(?:ing)?|introduc(?:e|ing))\b"
196
+ r".{0,40}\b(?:new\s+)?(?:dependenc(?:y|ies)|packages?|libraries|npm\s+packages?)\b"
197
+ r"|.{0,60}\b(?:modif(?:y|ying)|edit(?:ing)?|chang(?:e|ing)|updat(?:e|ing))\b"
198
+ r".{0,60}(?:\bdependenc(?:y|ies)\s+(?:declarations?|manifests?|files?)\b"
199
+ r"|\blockfiles?\b"
200
+ r"|`?(?:package\.json|pubspec\.yaml|Podfile|build\.gradle|pyproject\.toml|go\.mod|Cargo\.toml)`?)"
201
+ r")",
202
+ re.IGNORECASE,
203
+ )
204
+ NON_BINDING_OR_NEGATED_RE = re.compile(
205
+ r"\b(?:must\s+not|do\s+not|don't|never|not\s+(?:be\s+)?(?:written|treated)\s+as"
206
+ r"|non-binding|unless\s+(?:already|the\s+decision\s+ledger|selected)"
207
+ r"|already\s+(?:present|installed|in\s+`?package\.json`?))\b",
208
+ re.IGNORECASE,
209
+ )
210
+ MUST_INSTALL_DIRECTIVE_RES: tuple[re.Pattern[str], ...] = (
211
+ re.compile(r"\bMust[- ]install\b[:\s]*`?([@A-Za-z0-9_./-]+)`?", re.IGNORECASE),
212
+ re.compile(
213
+ r"\bMUST\b\s*:?\s*(?:always\s+)?install\s+(?:the\s+)?`([@A-Za-z0-9_./-]+)`",
214
+ re.IGNORECASE,
215
+ ),
216
+ re.compile(
217
+ r"\bMUST\b\s*:?\s*(?:always\s+)?add\s+(?:the\s+)?"
218
+ r"(?:(?:npm\s+)?package|dependency|library|crate|gem)\s+`([@A-Za-z0-9_./-]+)`",
219
+ re.IGNORECASE,
220
+ ),
221
+ re.compile(
222
+ r"\bMUST\b\s*:?\s*(?:always\s+)?add\s+`([@A-Za-z0-9_./-]+)`\s+"
223
+ r"(?:package|dependency|library|to\s+`?(?:package\.json|pyproject\.toml|go\.mod|Cargo\.toml|pubspec\.yaml)`?)",
224
+ re.IGNORECASE,
225
+ ),
226
+ )
227
+ FORBID_TOKEN_CLAUSE_RE = re.compile(
228
+ r"\b(?:never|must\s+not|do\s+not|forbid(?:den|s)?|prohibit(?:ed|s)?|ban(?:ned|s)?|disallow(?:ed|s)?)\b"
229
+ r"[^.\n;]{0,40}\b(?:us(?:e|ing)|install(?:ing)?|add(?:ing)?|import(?:ing)?|introduc(?:e|ing)|requir(?:e|ing)|adopt(?:ing)?)\b([^;\n]*)",
230
+ re.IGNORECASE,
231
+ )
232
+ FORBID_DIRECT_OBJECT_RE = re.compile(
233
+ r"\b(?:forbid(?:den|s)?|prohibit(?:ed|s)?|ban(?:ned|s)?|disallow(?:ed|s)?)\b\s*:?\s*"
234
+ r"(`[@A-Za-z0-9_./-]+`(?:\s*(?:,|or|and|/)\s*`[@A-Za-z0-9_./-]+`)*)",
235
+ re.IGNORECASE,
236
+ )
237
+ REQUIRE_TOKEN_CLAUSE_RE = re.compile(
238
+ r"\b(?:MUST\s*:?\s*(?:always\s+)?(?:use|install|add|import|adopt)|Must[- ]install)\b([^;\n]*)",
239
+ re.IGNORECASE,
240
+ )
241
+ CLAUSE_SPLIT_RE = re.compile(r";|\.(?:\s+|$)")
242
+ TABLE_SEPARATOR_RE = re.compile(r"^\s*\|(?:\s*:?-{2,}:?\s*\|)+\s*$")
243
+ BACKTICK_TOKEN_RE = re.compile(r"`([@A-Za-z0-9_./-]+)`")
244
+
43
245
 
44
246
  def _load_json(path: Path) -> dict[str, Any]:
45
247
  data = json.loads(path.read_text(encoding="utf-8"))
@@ -134,29 +336,29 @@ def _validate_layer(rules_root: Path, layer: str, errors: list[str]) -> None:
134
336
  f"{layer}: question {question_id} options_vary_by must reference "
135
337
  "an earlier question"
136
338
  )
137
- for field in CONDITION_FIELDS:
138
- condition = question.get(field)
339
+ for field_name in CONDITION_FIELDS:
340
+ condition = question.get(field_name)
139
341
  if condition is None:
140
342
  continue
141
343
  if not isinstance(condition, str):
142
- errors.append(f"{layer}: question {question_id} {field} must be a string")
344
+ errors.append(f"{layer}: question {question_id} {field_name} must be a string")
143
345
  continue
144
346
  match = CONDITION_RE.fullmatch(condition)
145
347
  if match is None:
146
348
  errors.append(
147
- f"{layer}: question {question_id} {field} has invalid option-ID "
349
+ f"{layer}: question {question_id} {field_name} has invalid option-ID "
148
350
  f"condition syntax: {condition!r}"
149
351
  )
150
352
  continue
151
353
  referenced_question = match.group(1) or match.group(2)
152
354
  if referenced_question not in question_positions:
153
355
  errors.append(
154
- f"{layer}: question {question_id} {field} references unknown "
356
+ f"{layer}: question {question_id} {field_name} references unknown "
155
357
  f"question {referenced_question}"
156
358
  )
157
359
  elif question_positions[referenced_question] >= index:
158
360
  errors.append(
159
- f"{layer}: question {question_id} {field} must reference an earlier question"
361
+ f"{layer}: question {question_id} {field_name} must reference an earlier question"
160
362
  )
161
363
 
162
364
  bank_text = required_files["bank"].read_text(encoding="utf-8")
@@ -271,18 +473,347 @@ def validate_rules_root(rules_root: Path) -> dict[str, object]:
271
473
  }
272
474
 
273
475
 
476
+ def _parse_headers(text: str) -> dict[str, str]:
477
+ headers: dict[str, str] = {}
478
+ first_h2 = H2_HEADING_RE.search(text)
479
+ preamble = text[: first_h2.start()] if first_h2 else text
480
+ for raw_line in preamble.splitlines():
481
+ stripped = raw_line.strip()
482
+ if not stripped or stripped.startswith("#"):
483
+ continue
484
+ match = HEADER_LINE_RE.match(raw_line)
485
+ if match:
486
+ key = " ".join(match.group(1).strip().lower().split())
487
+ value = match.group(2).strip()
488
+ headers[key] = value
489
+ return headers
490
+
491
+
492
+ def _extract_h2_section(text: str, exact_heading: str) -> str | None:
493
+ pattern = re.compile(rf"^{re.escape(exact_heading)}\s*$", re.MULTILINE)
494
+ match = pattern.search(text)
495
+ if match is None:
496
+ return None
497
+ rest = text[match.end() :]
498
+ next_h2 = H2_HEADING_RE.search(rest)
499
+ return rest[: next_h2.start()] if next_h2 else rest
500
+
501
+
502
+ FORBID_CONTRAST_SPLIT_RE = re.compile(
503
+ r"\b(?:instead\s+use|use\s+instead|prefer(?:ring)?|favor(?:ing)?|unless|except)\b",
504
+ re.IGNORECASE,
505
+ )
506
+ REQUIRE_CONTRAST_SPLIT_RE = re.compile(
507
+ r"\b(?:instead\s+of|rather\s+than|over|avoid(?:ing)?|not|never|without)\b",
508
+ re.IGNORECASE,
509
+ )
510
+
511
+
512
+ def _section1_missing_provenance_count(section1_clean: str) -> int:
513
+ entries: list[str] = []
514
+ in_table_body = False
515
+ for raw_line in section1_clean.splitlines():
516
+ stripped = raw_line.strip()
517
+ if not stripped or stripped.startswith("#"):
518
+ in_table_body = False
519
+ continue
520
+ if stripped.startswith("|"):
521
+ if TABLE_SEPARATOR_RE.match(stripped):
522
+ in_table_body = True
523
+ elif in_table_body:
524
+ entries.append(stripped)
525
+ continue
526
+ in_table_body = False
527
+ if LIST_ITEM_RE.match(raw_line):
528
+ entries.append(stripped)
529
+
530
+ if entries:
531
+ return sum(
532
+ 1 for entry in entries if not any(tok in entry for tok in PROVENANCE_TOKENS)
533
+ )
534
+ if section1_clean and not any(tok in section1_clean for tok in PROVENANCE_TOKENS):
535
+ return 1
536
+ return 0
537
+
538
+
539
+ def _check_contradictions(text: str, errors: list[str]) -> None:
540
+ clean_text = HTML_COMMENT_RE.sub("", text)
541
+ lines = clean_text.splitlines()
542
+ has_dep_forbid = any(DEP_FORBID_RE.search(line) for line in lines)
543
+
544
+ forbidden_tokens: set[str] = set()
545
+ required_tokens: set[str] = set()
546
+ must_install_packages: list[str] = []
547
+
548
+ for line in lines:
549
+ for clause in CLAUSE_SPLIT_RE.split(line):
550
+ clause = clause.strip()
551
+ if not clause:
552
+ continue
553
+
554
+ is_non_binding_or_negated = bool(NON_BINDING_OR_NEGATED_RE.search(clause))
555
+ if has_dep_forbid and not is_non_binding_or_negated:
556
+ for pattern in MUST_INSTALL_DIRECTIVE_RES:
557
+ for match in pattern.finditer(clause):
558
+ pkg = match.group(1).strip("`.,;:")
559
+ if pkg:
560
+ must_install_packages.append(pkg)
561
+
562
+ if not re.search(r"\b(?:unless\s+already|when\s+absent)\b", clause, re.IGNORECASE):
563
+ for forbid_match in FORBID_TOKEN_CLAUSE_RE.finditer(clause):
564
+ scoped_clause = FORBID_CONTRAST_SPLIT_RE.split(
565
+ forbid_match.group(1), maxsplit=1
566
+ )[0]
567
+ for token in BACKTICK_TOKEN_RE.findall(scoped_clause):
568
+ forbidden_tokens.add(token)
569
+ for direct_match in FORBID_DIRECT_OBJECT_RE.finditer(clause):
570
+ for token in BACKTICK_TOKEN_RE.findall(direct_match.group(1)):
571
+ forbidden_tokens.add(token)
572
+
573
+ if not is_non_binding_or_negated:
574
+ for req_match in REQUIRE_TOKEN_CLAUSE_RE.finditer(clause):
575
+ scoped_clause = REQUIRE_CONTRAST_SPLIT_RE.split(
576
+ req_match.group(1), maxsplit=1
577
+ )[0]
578
+ for token in BACKTICK_TOKEN_RE.findall(scoped_clause):
579
+ required_tokens.add(token)
580
+
581
+ if has_dep_forbid and must_install_packages:
582
+ unique_pkgs = sorted(set(must_install_packages))
583
+ errors.append(
584
+ "Deny List vs Must-install contradiction: dependency-forbid policy conflicts with "
585
+ f"Must-install directive(s): {unique_pkgs}"
586
+ )
587
+
588
+ conflicting_tokens = sorted(forbidden_tokens.intersection(required_tokens))
589
+ if conflicting_tokens:
590
+ errors.append(
591
+ "Deny List contradiction: prohibited token(s) also mandated by positive MUST / "
592
+ f"Must-install rule(s): {conflicting_tokens}"
593
+ )
594
+
595
+
596
+ def _validate_output_file(file_path: Path) -> OutputFileReport:
597
+ expected_layer = ALLOWED_OUTPUT_FILENAMES.get(file_path.name)
598
+ report = OutputFileReport(path=str(file_path), layer=expected_layer)
599
+
600
+ if expected_layer is None:
601
+ report.errors.append(
602
+ f"disallowed layer-rules filename {file_path.name!r}; expected one of "
603
+ f"{sorted(ALLOWED_OUTPUT_FILENAMES)}"
604
+ )
605
+ return report
606
+
607
+ try:
608
+ raw_bytes = file_path.read_bytes()
609
+ except OSError as exc:
610
+ report.errors.append(f"failed to read file: {exc}")
611
+ return report
612
+
613
+ report.bytes = len(raw_bytes)
614
+ if report.bytes > OUTPUT_HARD_MAX_BYTES:
615
+ report.errors.append(
616
+ f"raw UTF-8 size {report.bytes} bytes exceeds 16 KB hard limit "
617
+ f"({OUTPUT_HARD_MAX_BYTES} bytes)"
618
+ )
619
+ elif report.bytes >= OUTPUT_SOFT_WARN_BYTES:
620
+ report.warnings.append(
621
+ f"raw UTF-8 size {report.bytes} bytes reached 12 KB soft warning band "
622
+ f"({OUTPUT_SOFT_WARN_BYTES} bytes)"
623
+ )
624
+
625
+ try:
626
+ text = raw_bytes.decode("utf-8")
627
+ except UnicodeDecodeError as exc:
628
+ report.errors.append(f"invalid UTF-8 encoding: {exc}")
629
+ return report
630
+
631
+ headers = _parse_headers(text)
632
+ detected_mode = headers.get("mode")
633
+ report.mode = detected_mode
634
+
635
+ contract = MODE_CONTRACTS.get(detected_mode or "")
636
+ if contract is None:
637
+ report.errors.append(
638
+ f"missing or invalid Mode header: {detected_mode!r}; expected one of "
639
+ f"{sorted(MODE_CONTRACTS)}"
640
+ )
641
+ else:
642
+ for req_header in contract.required_headers:
643
+ if not headers.get(req_header):
644
+ report.errors.append(f"missing required header: {req_header.title()}")
645
+ if (
646
+ contract.expected_owner is not None
647
+ and headers.get("owner")
648
+ and headers["owner"].strip().lower() != contract.expected_owner
649
+ ):
650
+ report.errors.append(
651
+ f"invalid Owner header: {headers['owner']!r}; expected {contract.expected_owner!r}"
652
+ )
653
+
654
+ h2_headings = [match.group(0).strip() for match in H2_HEADING_RE.finditer(text)]
655
+ for req_section in contract.required_sections:
656
+ if req_section not in h2_headings:
657
+ report.errors.append(f"missing required section: {req_section}")
658
+
659
+ if contract.check_provenance_warning:
660
+ section1 = _extract_h2_section(text, "## 1. Confirmed Stack & Scope Decisions")
661
+ if section1 is not None:
662
+ section1_clean = HTML_COMMENT_RE.sub("", section1).strip()
663
+ missing_count = _section1_missing_provenance_count(section1_clean)
664
+ if missing_count > 0:
665
+ report.warnings.append(
666
+ f"## 1. Confirmed Stack & Scope Decisions has {missing_count} "
667
+ f"entry/entries lacking provenance labels ({', '.join(PROVENANCE_TOKENS)})"
668
+ )
669
+
670
+ declared_layer = headers.get("layer")
671
+ if declared_layer is not None:
672
+ normalized_layer = declared_layer.strip().lower()
673
+ if normalized_layer not in LAYERS:
674
+ report.errors.append(
675
+ f"invalid Layer header: {declared_layer!r}; expected one of {list(LAYERS)}"
676
+ )
677
+ elif normalized_layer != expected_layer:
678
+ report.errors.append(
679
+ f"Layer header {normalized_layer!r} does not match filename layer {expected_layer!r}"
680
+ )
681
+
682
+ placeholders = sorted(set(UNRESOLVED_PLACEHOLDER_RE.findall(text)))
683
+ if placeholders:
684
+ report.errors.append(f"unresolved template placeholder(s): {placeholders}")
685
+
686
+ question_ids = sorted(set(RAW_QUESTION_ID_RE.findall(text)))
687
+ if question_ids:
688
+ report.errors.append(f"raw questionnaire question-ID token(s) found: {question_ids}")
689
+
690
+ for label, pattern in OPTION_SHORTHAND_PATTERNS:
691
+ matches = sorted(set(pattern.findall(text)))
692
+ if matches:
693
+ report.errors.append(f"{label} found: {matches}")
694
+
695
+ for label, pattern in TRANSCRIPT_PROVENANCE_PATTERNS:
696
+ matches = sorted(set(pattern.findall(text)))
697
+ if matches:
698
+ report.errors.append(f"transcript provenance ({label}) found: {matches}")
699
+
700
+ platform_paths = sorted(set(PLATFORM_PATH_RE.findall(text)))
701
+ if platform_paths:
702
+ report.errors.append(f"platform-specific path(s) found: {platform_paths}")
703
+
704
+ retired_skills = sorted(set(RETIRED_SKILL_RE.findall(text)))
705
+ if retired_skills:
706
+ report.errors.append(f"retired layer-rules skill reference(s) found: {retired_skills}")
707
+
708
+ task_ids = sorted(set(WORKFLOW_TASK_ID_RE.findall(text)))
709
+ if task_ids:
710
+ report.errors.append(f"prohibited workflow task ID(s) found: {task_ids}")
711
+
712
+ checkpoint_ids = sorted(set(CHECKPOINT_ID_RE.findall(text)))
713
+ if checkpoint_ids:
714
+ report.errors.append(f"prohibited checkpoint ID(s) found: {checkpoint_ids}")
715
+
716
+ artifact_paths = sorted(set(ARTIFACT_PATH_RE.findall(text)))
717
+ if artifact_paths:
718
+ report.errors.append(f"prohibited internal artifact path(s) found: {artifact_paths}")
719
+
720
+ session_meta = sorted(set(SESSION_META_RE.findall(text)))
721
+ if session_meta:
722
+ report.errors.append(f"prohibited workflow/session metadata found: {session_meta}")
723
+
724
+ branch_hits = sorted(
725
+ set(BRANCH_HEADER_RE.findall(text)) | set(BRANCH_NAME_RE.findall(text))
726
+ )
727
+ if branch_hits:
728
+ report.errors.append(f"prohibited branch metadata/name(s) found: {branch_hits}")
729
+
730
+ section5 = _extract_h2_section(text, "## 5. Project-Evolved Rules")
731
+ if section5 is not None:
732
+ section5_clean = HTML_COMMENT_RE.sub("", section5)
733
+ evolved_entries = LIST_ITEM_RE.findall(section5_clean)
734
+ report.evolved_count = len(evolved_entries)
735
+ if report.evolved_count > MAX_EVOLVED_ENTRIES:
736
+ report.errors.append(
737
+ f"## 5. Project-Evolved Rules has {report.evolved_count} entries "
738
+ f"(exceeds hard cap of {MAX_EVOLVED_ENTRIES})"
739
+ )
740
+
741
+ _check_contradictions(text, report.errors)
742
+ return report
743
+
744
+
745
+ def validate_output(target: Path) -> dict[str, object]:
746
+ file_reports: list[OutputFileReport] = []
747
+ warnings: list[str] = []
748
+ errors: list[str] = []
749
+
750
+ if not target.exists():
751
+ errors.append(f"output path does not exist: {target}")
752
+ elif target.is_file():
753
+ file_report = _validate_output_file(target)
754
+ file_reports.append(file_report)
755
+ elif target.is_dir():
756
+ entries = sorted(
757
+ entry for entry in target.iterdir() if not entry.name.startswith(".")
758
+ )
759
+ if not entries:
760
+ errors.append(f"no layer-rules files found in directory: {target}")
761
+ for entry in entries:
762
+ if entry.is_dir():
763
+ errors.append(f"{entry.name}: unexpected subdirectory in layer-rules directory")
764
+ continue
765
+ file_reports.append(_validate_output_file(entry))
766
+ else:
767
+ errors.append(f"unsupported output target: {target}")
768
+
769
+ for file_report in file_reports:
770
+ prefix = Path(file_report.path).name
771
+ for warning in file_report.warnings:
772
+ warnings.append(f"{prefix}: {warning}")
773
+ for error in file_report.errors:
774
+ errors.append(f"{prefix}: {error}")
775
+
776
+ return {
777
+ "valid": not errors,
778
+ "mode": "validate-output",
779
+ "files": [file_report.to_dict() for file_report in file_reports],
780
+ "warnings": warnings,
781
+ "errors": errors,
782
+ }
783
+
784
+
274
785
  def main() -> int:
275
786
  parser = argparse.ArgumentParser(
276
- description="Validate app-planner Rules Configuration manifests and rendering resources."
787
+ description=(
788
+ "Validate app-planner Rules Configuration static resources (--rules-root) "
789
+ "or generated .prizmkit/rules/<layer>-rules.md outputs (--validate-output)."
790
+ )
277
791
  )
278
- parser.add_argument(
792
+ mode_group = parser.add_mutually_exclusive_group()
793
+ mode_group.add_argument(
279
794
  "--rules-root",
280
795
  type=Path,
281
- default=Path(__file__).resolve().parent.parent / "references" / "rules",
796
+ default=None,
282
797
  help="Path containing frontend/backend/database/mobile rules resources.",
283
798
  )
799
+ mode_group.add_argument(
800
+ "--validate-output",
801
+ type=Path,
802
+ default=None,
803
+ help="Path to a generated <layer>-rules.md file or directory to validate.",
804
+ )
284
805
  args = parser.parse_args()
285
- report = validate_rules_root(args.rules_root.expanduser().resolve())
806
+
807
+ if args.validate_output is not None:
808
+ report = validate_output(args.validate_output.expanduser().resolve())
809
+ else:
810
+ rules_root = (
811
+ args.rules_root
812
+ if args.rules_root is not None
813
+ else Path(__file__).resolve().parent.parent / "references" / "rules"
814
+ )
815
+ report = validate_rules_root(rules_root.expanduser().resolve())
816
+
286
817
  print(json.dumps(report, indent=2, ensure_ascii=False))
287
818
  return 0 if report["valid"] else 1
288
819
 
@@ -19,9 +19,8 @@ All bug fixes need verification that matches severity, reproduction clarity, and
19
19
 
20
20
  ## Browser Verification
21
21
 
22
- Use `browser_interaction` for UI-reproducible bugs.
22
+ Qualifying UI-reproducible bugs default directly to `browser_interaction` with `tool: "playwright-cli"`. Include affected bugs in the batch summary so the user can opt out specific items or override `verify_steps`/`blocking` per item.
23
23
 
24
- - `tool: auto` lets the runtime choose the best browser tool.
25
- - `tool: playwright-cli` is best for local dev-server verification in an isolated browser.
26
- - `tool: opencli` is best when an existing Chrome login/session or third-party integration cookies are needed.
27
- - `verify_steps` should describe what to prove, not low-level click scripts.
24
+ - `tool`: `"playwright-cli"` (default and sole supported tool for local dev-server verification in an isolated browser).
25
+ - `blocking`: optional boolean (default `false`) controlling whether browser verification failure blocks commit.
26
+ - `verify_steps`: describe what to prove, not low-level click scripts.