devrites 4.0.12 → 4.1.0

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 (238) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +3 -3
  3. package/docs/architecture.md +4 -4
  4. package/docs/command-map.md +4 -3
  5. package/docs/flow.md +2 -1
  6. package/docs/orchestration.md +45 -4
  7. package/docs/skills.md +4 -3
  8. package/engine/internal/devritespaths/paths.go +5 -4
  9. package/engine/internal/hostpack/hostpack.go +9 -4
  10. package/engine/internal/hostpack/hostpack_test.go +16 -7
  11. package/engine/internal/install/install_test.go +5 -0
  12. package/pack/.claude/agents/devrites-code-reviewer.md +6 -1
  13. package/pack/.claude/agents/devrites-plan-drafter.md +5 -0
  14. package/pack/.claude/agents/devrites-plan-reviewer.md +6 -0
  15. package/pack/.claude/agents/devrites-proof-runner.md +7 -1
  16. package/pack/.claude/agents/devrites-retrospector.md +21 -25
  17. package/pack/.claude/agents/devrites-security-auditor.md +7 -3
  18. package/pack/.claude/agents/devrites-slice-wright.md +30 -4
  19. package/pack/.claude/agents/devrites-spec-reviewer.md +5 -0
  20. package/pack/.claude/agents/devrites-strategy-reviewer.md +3 -4
  21. package/pack/.claude/agents/devrites-test-analyst.md +5 -0
  22. package/pack/.claude/skills/devrites-debug-recovery/SKILL.md +12 -16
  23. package/pack/.claude/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
  24. package/pack/.claude/skills/devrites-doubt/SKILL.md +3 -4
  25. package/pack/.claude/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
  26. package/pack/.claude/skills/devrites-lib/reference/standards/README.md +5 -1
  27. package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
  28. package/pack/.claude/skills/devrites-lib/reference/standards/agents.md +11 -3
  29. package/pack/.claude/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
  30. package/pack/.claude/skills/devrites-lib/reference/standards/code-review.md +1 -1
  31. package/pack/.claude/skills/devrites-lib/reference/standards/core.md +5 -0
  32. package/pack/.claude/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
  33. package/pack/.claude/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
  34. package/pack/.claude/skills/devrites-lib/reference/standards/documentation.md +28 -29
  35. package/pack/.claude/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
  36. package/pack/.claude/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
  37. package/pack/.claude/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
  38. package/pack/.claude/skills/devrites-lib/reference/standards/observability.md +10 -0
  39. package/pack/.claude/skills/devrites-lib/reference/standards/patterns.md +20 -0
  40. package/pack/.claude/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
  41. package/pack/.claude/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
  42. package/pack/.claude/skills/devrites-lib/reference/standards/security.md +51 -16
  43. package/pack/.claude/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
  44. package/pack/.claude/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
  45. package/pack/.claude/skills/devrites-lib/reference/standards/testing.md +51 -6
  46. package/pack/.claude/skills/rite/SKILL.md +2 -0
  47. package/pack/.claude/skills/rite-adopt/SKILL.md +8 -10
  48. package/pack/.claude/skills/rite-adopt/reference/adoption.md +13 -15
  49. package/pack/.claude/skills/rite-autocomplete/SKILL.md +18 -11
  50. package/pack/.claude/skills/rite-autocomplete/reference/loop.md +29 -6
  51. package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
  52. package/pack/.claude/skills/rite-build/SKILL.md +7 -1
  53. package/pack/.claude/skills/rite-build/reference/phase-contract.md +6 -1
  54. package/pack/.claude/skills/rite-build/reference/wright-dispatch.md +37 -4
  55. package/pack/.claude/skills/rite-clarify/SKILL.md +3 -2
  56. package/pack/.claude/skills/rite-converge/SKILL.md +4 -2
  57. package/pack/.claude/skills/rite-converge/reference/convergence-assessment.md +8 -4
  58. package/pack/.claude/skills/rite-customize/SKILL.md +16 -18
  59. package/pack/.claude/skills/rite-define/SKILL.md +60 -62
  60. package/pack/.claude/skills/rite-define/reference/plan-template.md +88 -71
  61. package/pack/.claude/skills/rite-explain/SKILL.md +2 -1
  62. package/pack/.claude/skills/rite-learn/SKILL.md +28 -32
  63. package/pack/.claude/skills/rite-plan/SKILL.md +42 -45
  64. package/pack/.claude/skills/rite-plan/reference/dependency-graph.md +11 -2
  65. package/pack/.claude/skills/rite-plan/reference/task-breakdown.md +2 -0
  66. package/pack/.claude/skills/rite-polish/reference/adr-promotion.md +7 -7
  67. package/pack/.claude/skills/rite-pressure-test/SKILL.md +24 -31
  68. package/pack/.claude/skills/rite-prove/SKILL.md +12 -15
  69. package/pack/.claude/skills/rite-prove/reference/acceptance-proof.md +28 -0
  70. package/pack/.claude/skills/rite-review/SKILL.md +5 -4
  71. package/pack/.claude/skills/rite-review/reference/five-axis-review.md +6 -0
  72. package/pack/.claude/skills/rite-review/reference/security-review.md +7 -2
  73. package/pack/.claude/skills/rite-seal/reference/final-evidence.md +3 -0
  74. package/pack/.claude/skills/rite-seal/reference/risk-and-rollback.md +19 -4
  75. package/pack/.claude/skills/rite-ship/reference/rollout.md +62 -43
  76. package/pack/.claude/skills/rite-spec/SKILL.md +8 -1
  77. package/pack/.claude/skills/rite-spec/reference/ai-spec-template.md +13 -6
  78. package/pack/.claude/skills/rite-spec/reference/spec-checklists.md +14 -2
  79. package/pack/.claude/skills/rite-spec/reference/spec-template.md +33 -4
  80. package/pack/.claude/skills/rite-temper/SKILL.md +5 -1
  81. package/pack/.claude/skills/rite-vet/SKILL.md +8 -8
  82. package/pack/.claude/skills/rite-vet/reference/artifacts.md +5 -3
  83. package/pack/.claude/skills/rite-vet/reference/review-axes.md +67 -77
  84. package/pack/.claude/skills/rite-watch-pr/SKILL.md +85 -0
  85. package/pack/.claude/skills/rite-zoom-out/SKILL.md +4 -5
  86. package/pack/.claude/workflows/devrites-readonly-review.js +194 -0
  87. package/pack/generated/README.md +1 -1
  88. package/pack/generated/claude/agents/devrites-code-reviewer.md +6 -1
  89. package/pack/generated/claude/agents/devrites-plan-drafter.md +5 -0
  90. package/pack/generated/claude/agents/devrites-plan-reviewer.md +6 -0
  91. package/pack/generated/claude/agents/devrites-proof-runner.md +7 -1
  92. package/pack/generated/claude/agents/devrites-retrospector.md +21 -25
  93. package/pack/generated/claude/agents/devrites-security-auditor.md +7 -3
  94. package/pack/generated/claude/agents/devrites-slice-wright.md +30 -4
  95. package/pack/generated/claude/agents/devrites-spec-reviewer.md +5 -0
  96. package/pack/generated/claude/agents/devrites-strategy-reviewer.md +3 -4
  97. package/pack/generated/claude/agents/devrites-test-analyst.md +5 -0
  98. package/pack/generated/claude/skills/devrites-debug-recovery/SKILL.md +12 -16
  99. package/pack/generated/claude/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
  100. package/pack/generated/claude/skills/devrites-doubt/SKILL.md +3 -4
  101. package/pack/generated/claude/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
  102. package/pack/generated/claude/skills/devrites-lib/reference/standards/README.md +5 -1
  103. package/pack/generated/claude/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
  104. package/pack/generated/claude/skills/devrites-lib/reference/standards/agents.md +11 -3
  105. package/pack/generated/claude/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
  106. package/pack/generated/claude/skills/devrites-lib/reference/standards/code-review.md +1 -1
  107. package/pack/generated/claude/skills/devrites-lib/reference/standards/core.md +5 -0
  108. package/pack/generated/claude/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
  109. package/pack/generated/claude/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
  110. package/pack/generated/claude/skills/devrites-lib/reference/standards/documentation.md +28 -29
  111. package/pack/generated/claude/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
  112. package/pack/generated/claude/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
  113. package/pack/generated/claude/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
  114. package/pack/generated/claude/skills/devrites-lib/reference/standards/observability.md +10 -0
  115. package/pack/generated/claude/skills/devrites-lib/reference/standards/patterns.md +20 -0
  116. package/pack/generated/claude/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
  117. package/pack/generated/claude/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
  118. package/pack/generated/claude/skills/devrites-lib/reference/standards/security.md +51 -16
  119. package/pack/generated/claude/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
  120. package/pack/generated/claude/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
  121. package/pack/generated/claude/skills/devrites-lib/reference/standards/testing.md +51 -6
  122. package/pack/generated/claude/skills/rite/SKILL.md +2 -0
  123. package/pack/generated/claude/skills/rite-adopt/SKILL.md +8 -10
  124. package/pack/generated/claude/skills/rite-adopt/reference/adoption.md +13 -15
  125. package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +18 -11
  126. package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md +29 -6
  127. package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
  128. package/pack/generated/claude/skills/rite-build/SKILL.md +7 -1
  129. package/pack/generated/claude/skills/rite-build/reference/phase-contract.md +6 -1
  130. package/pack/generated/claude/skills/rite-build/reference/wright-dispatch.md +37 -4
  131. package/pack/generated/claude/skills/rite-clarify/SKILL.md +3 -2
  132. package/pack/generated/claude/skills/rite-converge/SKILL.md +4 -2
  133. package/pack/generated/claude/skills/rite-converge/reference/convergence-assessment.md +8 -4
  134. package/pack/generated/claude/skills/rite-customize/SKILL.md +16 -18
  135. package/pack/generated/claude/skills/rite-define/SKILL.md +60 -62
  136. package/pack/generated/claude/skills/rite-define/reference/plan-template.md +88 -71
  137. package/pack/generated/claude/skills/rite-explain/SKILL.md +2 -1
  138. package/pack/generated/claude/skills/rite-learn/SKILL.md +28 -32
  139. package/pack/generated/claude/skills/rite-plan/SKILL.md +42 -45
  140. package/pack/generated/claude/skills/rite-plan/reference/dependency-graph.md +11 -2
  141. package/pack/generated/claude/skills/rite-plan/reference/task-breakdown.md +2 -0
  142. package/pack/generated/claude/skills/rite-polish/reference/adr-promotion.md +7 -7
  143. package/pack/generated/claude/skills/rite-pressure-test/SKILL.md +24 -31
  144. package/pack/generated/claude/skills/rite-prove/SKILL.md +12 -15
  145. package/pack/generated/claude/skills/rite-prove/reference/acceptance-proof.md +28 -0
  146. package/pack/generated/claude/skills/rite-review/SKILL.md +5 -4
  147. package/pack/generated/claude/skills/rite-review/reference/five-axis-review.md +6 -0
  148. package/pack/generated/claude/skills/rite-review/reference/security-review.md +7 -2
  149. package/pack/generated/claude/skills/rite-seal/reference/final-evidence.md +3 -0
  150. package/pack/generated/claude/skills/rite-seal/reference/risk-and-rollback.md +19 -4
  151. package/pack/generated/claude/skills/rite-ship/reference/rollout.md +62 -43
  152. package/pack/generated/claude/skills/rite-spec/SKILL.md +8 -1
  153. package/pack/generated/claude/skills/rite-spec/reference/ai-spec-template.md +13 -6
  154. package/pack/generated/claude/skills/rite-spec/reference/spec-checklists.md +14 -2
  155. package/pack/generated/claude/skills/rite-spec/reference/spec-template.md +33 -4
  156. package/pack/generated/claude/skills/rite-temper/SKILL.md +5 -1
  157. package/pack/generated/claude/skills/rite-vet/SKILL.md +8 -8
  158. package/pack/generated/claude/skills/rite-vet/reference/artifacts.md +5 -3
  159. package/pack/generated/claude/skills/rite-vet/reference/review-axes.md +67 -77
  160. package/pack/generated/claude/skills/rite-watch-pr/SKILL.md +85 -0
  161. package/pack/generated/claude/skills/rite-zoom-out/SKILL.md +4 -5
  162. package/pack/generated/claude/workflows/devrites-readonly-review.js +194 -0
  163. package/pack/generated/codex/agents/devrites-code-reviewer.toml +6 -1
  164. package/pack/generated/codex/agents/devrites-plan-drafter.toml +5 -0
  165. package/pack/generated/codex/agents/devrites-plan-reviewer.toml +6 -0
  166. package/pack/generated/codex/agents/devrites-proof-runner.toml +7 -1
  167. package/pack/generated/codex/agents/devrites-retrospector.toml +21 -25
  168. package/pack/generated/codex/agents/devrites-security-auditor.toml +7 -3
  169. package/pack/generated/codex/agents/devrites-slice-wright.toml +30 -4
  170. package/pack/generated/codex/agents/devrites-spec-reviewer.toml +5 -0
  171. package/pack/generated/codex/agents/devrites-strategy-reviewer.toml +3 -4
  172. package/pack/generated/codex/agents/devrites-test-analyst.toml +5 -0
  173. package/pack/generated/codex/skills/devrites-debug-recovery/SKILL.md +12 -16
  174. package/pack/generated/codex/skills/devrites-debug-recovery/reference/build-the-loop.md +11 -14
  175. package/pack/generated/codex/skills/devrites-doubt/SKILL.md +3 -4
  176. package/pack/generated/codex/skills/devrites-frontend-craft/reference/reuse-first.md +3 -4
  177. package/pack/generated/codex/skills/devrites-lib/reference/standards/README.md +5 -1
  178. package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md +33 -8
  179. package/pack/generated/codex/skills/devrites-lib/reference/standards/agents.md +11 -3
  180. package/pack/generated/codex/skills/devrites-lib/reference/standards/ci-cd.md +19 -0
  181. package/pack/generated/codex/skills/devrites-lib/reference/standards/code-review.md +1 -1
  182. package/pack/generated/codex/skills/devrites-lib/reference/standards/core.md +5 -0
  183. package/pack/generated/codex/skills/devrites-lib/reference/standards/data-integrity.md +95 -0
  184. package/pack/generated/codex/skills/devrites-lib/reference/standards/developer-experience.md +5 -5
  185. package/pack/generated/codex/skills/devrites-lib/reference/standards/documentation.md +28 -29
  186. package/pack/generated/codex/skills/devrites-lib/reference/standards/edge-case-trace.md +70 -10
  187. package/pack/generated/codex/skills/devrites-lib/reference/standards/integration-reliability.md +79 -0
  188. package/pack/generated/codex/skills/devrites-lib/reference/standards/loop-operations.md +85 -0
  189. package/pack/generated/codex/skills/devrites-lib/reference/standards/observability.md +10 -0
  190. package/pack/generated/codex/skills/devrites-lib/reference/standards/patterns.md +20 -0
  191. package/pack/generated/codex/skills/devrites-lib/reference/standards/repository-topology.md +73 -0
  192. package/pack/generated/codex/skills/devrites-lib/reference/standards/security-checklist.md +6 -2
  193. package/pack/generated/codex/skills/devrites-lib/reference/standards/security.md +51 -16
  194. package/pack/generated/codex/skills/devrites-lib/reference/standards/skill-authoring.md +35 -40
  195. package/pack/generated/codex/skills/devrites-lib/reference/standards/test-proof-checklist.md +4 -0
  196. package/pack/generated/codex/skills/devrites-lib/reference/standards/testing.md +51 -6
  197. package/pack/generated/codex/skills/rite/SKILL.md +2 -0
  198. package/pack/generated/codex/skills/rite-adopt/SKILL.md +8 -10
  199. package/pack/generated/codex/skills/rite-adopt/reference/adoption.md +13 -15
  200. package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +18 -11
  201. package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md +29 -6
  202. package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md +7 -0
  203. package/pack/generated/codex/skills/rite-build/SKILL.md +7 -1
  204. package/pack/generated/codex/skills/rite-build/reference/phase-contract.md +6 -1
  205. package/pack/generated/codex/skills/rite-build/reference/wright-dispatch.md +37 -4
  206. package/pack/generated/codex/skills/rite-clarify/SKILL.md +3 -2
  207. package/pack/generated/codex/skills/rite-converge/SKILL.md +4 -2
  208. package/pack/generated/codex/skills/rite-converge/reference/convergence-assessment.md +8 -4
  209. package/pack/generated/codex/skills/rite-customize/SKILL.md +16 -18
  210. package/pack/generated/codex/skills/rite-define/SKILL.md +60 -62
  211. package/pack/generated/codex/skills/rite-define/reference/plan-template.md +88 -71
  212. package/pack/generated/codex/skills/rite-explain/SKILL.md +2 -1
  213. package/pack/generated/codex/skills/rite-learn/SKILL.md +28 -32
  214. package/pack/generated/codex/skills/rite-plan/SKILL.md +42 -45
  215. package/pack/generated/codex/skills/rite-plan/reference/dependency-graph.md +11 -2
  216. package/pack/generated/codex/skills/rite-plan/reference/task-breakdown.md +2 -0
  217. package/pack/generated/codex/skills/rite-polish/reference/adr-promotion.md +7 -7
  218. package/pack/generated/codex/skills/rite-pressure-test/SKILL.md +24 -31
  219. package/pack/generated/codex/skills/rite-prove/SKILL.md +12 -15
  220. package/pack/generated/codex/skills/rite-prove/reference/acceptance-proof.md +28 -0
  221. package/pack/generated/codex/skills/rite-review/SKILL.md +5 -4
  222. package/pack/generated/codex/skills/rite-review/reference/five-axis-review.md +6 -0
  223. package/pack/generated/codex/skills/rite-review/reference/security-review.md +7 -2
  224. package/pack/generated/codex/skills/rite-seal/reference/final-evidence.md +3 -0
  225. package/pack/generated/codex/skills/rite-seal/reference/risk-and-rollback.md +19 -4
  226. package/pack/generated/codex/skills/rite-ship/reference/rollout.md +62 -43
  227. package/pack/generated/codex/skills/rite-spec/SKILL.md +8 -1
  228. package/pack/generated/codex/skills/rite-spec/reference/ai-spec-template.md +13 -6
  229. package/pack/generated/codex/skills/rite-spec/reference/spec-checklists.md +14 -2
  230. package/pack/generated/codex/skills/rite-spec/reference/spec-template.md +33 -4
  231. package/pack/generated/codex/skills/rite-temper/SKILL.md +5 -1
  232. package/pack/generated/codex/skills/rite-vet/SKILL.md +8 -8
  233. package/pack/generated/codex/skills/rite-vet/reference/artifacts.md +5 -3
  234. package/pack/generated/codex/skills/rite-vet/reference/review-axes.md +67 -77
  235. package/pack/generated/codex/skills/rite-watch-pr/SKILL.md +85 -0
  236. package/pack/generated/codex/skills/rite-zoom-out/SKILL.md +4 -5
  237. package/package.json +1 -1
  238. package/scripts/build-host-artifacts.sh +3 -1
@@ -1,43 +1,62 @@
1
- # Staged rollout & rollback: when the ship includes a live deploy
2
-
3
- Opt-in. `$rite-ship`'s job ends at the git ladder (commit → push → tag / PR) and archiving the
4
- workspace; most projects deploy from CI on merge, and their pipeline owns the rollout. Reach for
5
- this reference only when the ship *itself* drives a live, staged production rollout the agent is
6
- responsible for. When it doesn't apply, skip it: the same no-op discipline as the rest of the pack.
7
-
8
- The governing idea is the one already in [`git-workflow.md`](../../devrites-lib/reference/standards/git-workflow.md) and
9
- [`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md): **a launch is only done when it's reversible,
10
- observable, and incremental.** Write the rollback plan *before* you deploy, not after it breaks.
11
-
12
- ## The rollback plan is a pre-condition
13
- Before the first byte ships, the plan exists, with a measured **time-to-rollback** per mechanism:
14
- feature flag < 1 min, redeploy < 5 min, DB rollback < 15 min. If the fastest reversal is slow, that
15
- is a launch risk to fix (add a flag) before shipping, not after. A destructive/migration step ships
16
- only with its rollback proven (expand→contract, [`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md)).
17
-
18
- ## Advance on evidence: the rollout decision thresholds
19
- Stage the exposure and, at each stage, read the signals ([`observability.md`](../../devrites-lib/reference/standards/observability.md))
20
- against a fixed table: advance on green, hold on yellow, roll back on red. Don't eyeball it.
21
-
22
- | Signal | Green (advance) | Yellow (hold, investigate) | Red (roll back now) |
23
- |---|---|---|---|
24
- | Error rate | within ~10% of baseline | 10-100% over baseline | > 2× baseline |
25
- | p95 latency | within ~20% of baseline | 20-50% over | > 50% over |
26
- | Client JS errors | none new | < 0.1% of sessions | > 0.1% of sessions |
27
- | Business metric on the path | neutral or up | < 5% decline | > 5% decline |
28
-
29
- ## Stage the exposure, with a monitoring window at each step
30
- Internal/team → canary ~5% (hold 24-48h) 25% → 50% → 100%, advancing only when **all** thresholds
31
- are green and you can still roll back to the previous percentage at any point. Data integrity or a
32
- security regression is an **immediate** rollback regardless of the table.
33
-
34
- ## Feature-flag hygiene
35
- Every flag has an owner and an expiry; test both states in CI; don't nest flags (state explodes);
36
- remove the flag and its dead branch within ~2 weeks of full rollout: a lingering flag is the
37
- deprecation debt [`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md) exists to prevent.
38
-
39
- ## Verify in the first hour (a runbook, not a vibe)
40
- Health endpoint returns 200 · the error dashboard is flat · latency within budget · one critical
41
- user flow driven by hand · logs/metrics/traces flowing ([`observability.md`](../../devrites-lib/reference/standards/observability.md)
42
- "verify the telemetry fires") · a rollback dry-run confirmed reversible. Record the observations in
43
- `ship.md` / `evidence.md`: an un-watched launch is an unproven one.
1
+ # Staged rollout and recovery: live deploys only
2
+
3
+ Load this only when `$rite-ship` itself is explicitly authorized to drive a live
4
+ deployment. Git-only Ship stops before rollout; CI-owned deployment follows the pipeline's
5
+ runbook. A Seal GO or AFK setting never authorizes production action.
6
+
7
+ ## Preconditions before exposure
8
+
9
+ Record one rollout sheet in `ship.md`/`evidence.md`:
10
+
11
+ | Item | Required decision/evidence |
12
+ | --- | --- |
13
+ | Units and order | Repository/deployable, schema, config, application, worker, contract, and flag order; safe old/new combinations. |
14
+ | Exposure stages | Project-native internal/canary/cohort/percentage/region stages and hold window. |
15
+ | Advance/hold/abort signals | Project baseline or SLO, measurement window, minimum sample, exact threshold, and owner. |
16
+ | Recovery | Fastest safe mechanism, steps, owner, measured/rehearsed time, and data/external-effect reconciliation. |
17
+ | Observability | Watched dashboard/query/alert, failure signal, and executable first action. |
18
+ | Authorization | Exact target/action approved for this attempt; no inferred retry permission. |
19
+
20
+ Do not import generic percentage, latency, error-rate, or time-to-rollback numbers. Use
21
+ accepted product risk, current baseline/SLO, traffic volume, and platform capability. If the
22
+ project has no defensible threshold or signal, the monitoring gap blocks live exposure.
23
+
24
+ ## Choose the smallest reversible mechanism
25
+
26
+ - A feature flag is useful only when the off path preserves current behavior, both states
27
+ are tested, disabling it stops the risky effect, and it has an owner/removal trigger.
28
+ Do not add a flag to a change already reversible by a safe atomic deploy.
29
+ - A flag cannot reverse destructive data/schema effects. Apply
30
+ [`data-integrity.md`](../../devrites-lib/reference/standards/data-integrity.md) and prove
31
+ restore or forward recovery separately.
32
+ - External APIs, webhooks, queues, jobs, and caches apply
33
+ [`integration-reliability.md`](../../devrites-lib/reference/standards/integration-reliability.md):
34
+ reconcile unknown outcomes, drain/quarantine/replay safely, and protect downstream capacity.
35
+ - Multi-root/service rollout follows
36
+ [`repository-topology.md`](../../devrites-lib/reference/standards/repository-topology.md);
37
+ references to another repository never grant write/deploy authority there.
38
+
39
+ ## Stage, observe, decide
40
+
41
+ At each authorized stage:
42
+
43
+ 1. Verify the intended versions/config/schema and candidate identity on the exact target.
44
+ 2. Exercise one critical success path and the declared degradation/recovery signal.
45
+ 3. Observe for the recorded window and sample; bind results to the stage and baseline.
46
+ 4. **Advance** only when every advance condition holds. **Hold** on ambiguous or
47
+ insufficient evidence. **Abort/recover** immediately on an abort condition, security or
48
+ tenant breach, data-integrity violation, unreconciled duplicate/unknown effect, or loss of
49
+ observability.
50
+ 5. Re-verify after recovery; record partial effects and reconciliation. A rollback command
51
+ exiting zero is not proof the prior state or data was restored.
52
+
53
+ Never compress stages because an early sample "looks fine," continue through a monitoring
54
+ gap, or retry a failed live action without fresh authorization when the attempt/target changes.
55
+
56
+ ## Completion
57
+
58
+ Rollout is complete only when full intended exposure meets the recorded window/signals,
59
+ telemetry is still watched, migrations/backfills and queues/reconciliation are settled,
60
+ documentation matches deployed behavior, and temporary flags/compatibility paths have a
61
+ dated removal owner. Otherwise report the exact current stage and remaining risk; do not call
62
+ the launch done.
@@ -19,6 +19,10 @@ declared invariants; an unavoidable principle violation is blocking.
19
19
  For behavioral/high-risk acceptance, use `spec-grammar.md` plus workspace schema;
20
20
  simple criteria stay flat `AC-###`. Apply
21
21
  [`acceptance-criteria.md`](reference/acceptance-criteria.md) so each is binary and observable.
22
+ Use [`edge-case-trace.md`](../devrites-lib/reference/standards/edge-case-trace.md)
23
+ to populate only relevant edge/prohibition rows. The spec's applicability map routes
24
+ topology, data, integration, security, and delivery concerns to their focused standard;
25
+ load a routed standard to discover required behavior, not to prescribe implementation.
22
26
 
23
27
  ## Operating rules (DevRites core)
24
28
  - No silent assumptions or guessing; prefer conventions; ask on scope,
@@ -65,6 +69,8 @@ simple criteria stay flat `AC-###`. Apply
65
69
  template's specific justification.
66
70
  Identify proof constraints now: human-only credentials, unavailable environments, approval
67
71
  windows, or acceptance not observable through existing test/runtime/browser surfaces.
72
+ An unfamiliar framework/version routes to `devrites-source-driven`; missing or
73
+ contradictory documentation is evidence to reconcile, never a license to guess.
68
74
  Split independent placement, blast-radius, and external-fact questions into at most three
69
75
  bounded `devrites-evidence-scout` tasks on one frozen candidate. Wait for and reconcile every
70
76
  cited dossier before step 4. The scout supplies facts only; it never asks the human or writes
@@ -102,7 +108,8 @@ simple criteria stay flat `AC-###`. Apply
102
108
  unrelated settled content. Write every required artifact and conditional
103
109
  annex exactly from [spec-template](reference/spec-template.md), including its
104
110
  capability impact, existing-behavior preservation, grammar/delta,
105
- coverage-seed, qualified backstops, edge/prohibition, UI, and AI rules. Native
111
+ stakeholder/constraint/invariant, failure/recovery, applicability, coverage-seed,
112
+ qualified backstop, edge/prohibition, UI, and AI rules. Native
106
113
  hierarchical instructions remain stable; do not rewrite `AGENTS.md` or
107
114
  `CLAUDE.md` for the active workspace.
108
115
  5a. **Check the spec prose** with [spec-checklists](reference/spec-checklists.md).
@@ -17,17 +17,24 @@ or LLM output.
17
17
  - Fallback/degradation: <what users see when AI is unavailable>
18
18
 
19
19
  ## Domain evals
20
- | Eval ID | Scenario | Expected signal | Gate |
21
- | --- | --- | --- | --- |
22
- | EVAL-001 | <domain-specific case> | <pass condition> | build/seal |
20
+ | Eval ID | Scenario / slice | Dataset provenance | Expected signal + threshold | Gate |
21
+ | --- | --- | --- | --- | --- |
22
+ | EVAL-001 | <representative/adversarial/empty-context case> | <held-out source/version> | <pass condition and baseline delta> | build/seal |
23
+
24
+ For RAG, cover retrieval relevance/context recall, context precision, answer
25
+ faithfulness, citation support, tenant/ACL isolation, poisoned or conflicting documents,
26
+ and insufficient-context fallback as applicable. A single polished example is not an eval.
23
27
 
24
28
  ## Guardrails
25
29
  - Inputs: <validation, prompt-injection boundaries, tenant/data limits>
26
- - Outputs: <schema checks, refusals, human review, citations>
30
+ - Retrieval: <source provenance, indexing validation, tenant/ACL filter, freshness/deletion>
31
+ - Outputs: <schema checks, refusals, human review, citations only to supporting retrieved sources>
27
32
  - Privacy/security: <data sent to model, retention, secrets policy>
33
+ - Unknown/insufficient context: <abstain, clarify, or bounded fallback; never fabricate>
28
34
 
29
35
  ## Monitoring
30
- - Runtime metrics/logs: <latency, cost, quality, refusal/error rates>
36
+ - Runtime metrics/logs: <latency, cost, retrieval/quality, refusal/error/fallback rates>
31
37
  - Alerts or manual review: <trigger>
32
- - Rollback/kill switch: <mechanism>
38
+ - Rollback/kill switch: <prompt/model/index version and reversible mechanism>
39
+ - Drift evaluation: <reference set, schedule/trigger, regression threshold, owner>
33
40
  ```
@@ -15,8 +15,8 @@ Emit `.devrites/work/<slug>/checklists/<domain>.md` per covered domain; skip
15
15
  | `functional.md` | Functional requirements + scenarios: is each capability stated, bounded, testable? |
16
16
  | `data-model.md` | Key entities / data model: shapes, fields, lifecycle, relationships (skip if "none"). |
17
17
  | `interaction.md` | API / UI impact + UX states: every screen state and contract named (skip if no UI/API). |
18
- | `non-functional.md` | Constraints, auth / data sensitivity, latency / scale / compatibility budgets, human-only proof prerequisites. |
19
- | `edge-cases.md` | Empty / boundary / invalid / concurrent / failure paths the requirements imply. |
18
+ | `non-functional.md` | Invariants; security/privacy/accessibility, latency/scale, compatibility, operations, and human-only proof prerequisites. |
19
+ | `edge-cases.md` | Empty/boundary/invalid/concurrent/failure/recovery paths plus the spec's applicability map. |
20
20
 
21
21
  ## Each item: a question, a verdict, the line it interrogates
22
22
 
@@ -46,9 +46,21 @@ Each question checks one requirement-prose failure mode:
46
46
  names its empty / error / boundary behaviour.
47
47
  - **Clarity:** one entity, one name (no `user`/`customer`/`account` drift); no requirement two
48
48
  readers would implement differently; no "should" where "MUST" is meant.
49
+ - **Assumptions:** no material behavior, scope, data, security, or proof fact survives as a
50
+ hidden assumption; verify it or record an owned/deadlined assumption or blocking question.
49
51
  - **Testability:** each acceptance criterion is binary and names (or clearly implies) its evidence.
50
52
  A criterion only provable by reading code is a fail.
51
53
  - **Consistency:** no requirement contradicts another, the data model, or a non-goal.
54
+ - **Stakeholders:** affected actors/operators are named; conflicting outcomes have an
55
+ explicit priority or decision owner rather than two simultaneously impossible promises.
56
+ - **Applicability:** topology, data, integration, security, UI/i18n/time zone, and
57
+ compatibility/delivery rows are `applies` with IDs or specifically justified `not applicable`.
58
+ - **Failure/recovery:** each partial, timeout, invalid, interrupted, or unavailable state
59
+ implied by an applicable row has a user outcome, system state, and safe retry/recovery rule.
60
+ - **Data:** schema/backfill/concurrency/tenant/retention implications state invariants and
61
+ prohibited loss/leakage; implementation detail stays for Define.
62
+ - **Integration:** timeout, invalid/partial response, auth/rate-limit/outage, duplicate,
63
+ ordering, and version-change behavior is specified when the boundary can produce it.
52
64
  - **Preservation:** each material brownfield outcome appears in `Existing behavior
53
65
  to preserve` with preserving REQ/AC and current evidence. Missing/vague “no
54
66
  regressions” or unjustified `none` is CRITICAL.
@@ -33,10 +33,15 @@ No implementation detail. True greenfield: `none — no existing behavior in the
33
33
  | --- | --- | --- |
34
34
  | <outcome that must not regress> | REQ-001 / AC-001 | <current evidence> |
35
35
 
36
- ## Users / actors
37
- | Actor | Need |
38
- | --- | --- |
39
- | <actor> | <goal> |
36
+ ## Stakeholders and priorities
37
+ | Actor/stakeholder | Observable outcome | Conflict / priority rule |
38
+ | --- | --- | --- |
39
+ | <actor or affected owner> | <goal, protection, or operational need> | <none or how competing goals resolve> |
40
+
41
+ ## Constraints and invariants
42
+ - INV-001: <fact that MUST remain true across success, failure, retry, and recovery>.
43
+ - <security/privacy/accessibility/performance/compatibility/data/operational constraint,
44
+ or `none — <specific reason>` for a materially relevant category>.
40
45
 
41
46
  ## Requirements
42
47
  - REQ-001: The system MUST <observable product behavior>.
@@ -74,6 +79,24 @@ Bespoke only; generic security/privacy stays in standards. Status:
74
79
  | --- | --- | --- | --- |
75
80
  | PROH-001 | REQ-002 | resolved/test | <test/evidence link> |
76
81
 
82
+ ## Failure and recovery behavior
83
+ | Trigger / partial state | User-visible outcome | System state | Recovery / retry rule | Requirement/AC |
84
+ | --- | --- | --- | --- | --- |
85
+ | <timeout, invalid input, interruption, dependency loss> | <clear bounded outcome> | <unchanged/pending/reconciling> | <who/what can safely recover> | <REQ/AC> |
86
+
87
+ ## Applicability map
88
+ Use `applies | not applicable`; a non-applicable row needs a specific reason. The
89
+ status routes Define/Vet/Build/Prove to the named standard without copying it here.
90
+
91
+ | Concern | Status and trigger | Affected REQ/AC/invariant |
92
+ | --- | --- | --- |
93
+ | Repository topology (nested/mono/multi-repo, languages, services, generated/vendor) | <status + reason> | <ids> |
94
+ | Data integrity (writes, schema/migration, concurrency, tenant, retention/privacy) | <status + reason> | <ids> |
95
+ | Integration reliability (API/webhook/queue/job/cache/cross-service) | <status + reason> | <ids> |
96
+ | Security boundary (authn/authz, hostile input/files, secrets, privilege) | <status + reason> | <ids> |
97
+ | UI/accessibility/i18n/time-zone behavior | <status + reason> | <ids> |
98
+ | Compatibility/delivery (old/new versions, config, flag, rollout/rollback) | <status + reason> | <ids> |
99
+
77
100
  ## Edge cases
78
101
  - <Boundary note not captured above.>
79
102
 
@@ -106,9 +129,15 @@ Bespoke only; generic security/privacy stays in standards. Status:
106
129
 
107
130
  ## Readiness gate
108
131
  - [ ] No blocking clarification; REQ/AC IDs are valid and ACs independently provable.
132
+ - [ ] Stakeholder conflicts/priority rules, constraints, and invariants are explicit;
133
+ implementation preferences are not disguised as requirements.
109
134
  - [ ] Existing affected behavior maps to preserving REQ/AC + current evidence, or uses the exact justified greenfield `none`.
110
135
  - [ ] Edge rows target REQ/AC or justify dismissal; every backstop names independent discriminating evidence, else `unresolved`.
111
136
  - [ ] Prohibitions resolve/dismiss; `resolved/test` links evidence.
137
+ - [ ] Each material failure/partial state names user outcome, system state, recovery,
138
+ and REQ/AC; no silent success or blind retry remains.
139
+ - [ ] Every applicability row is `applies` with affected IDs or has a specific
140
+ evidence-backed `not applicable` reason.
112
141
  - [ ] AI has `ai-spec.md` and UI has `design-brief.md`; out-of-scope work states not applicable.
113
142
  - [ ] Non-goals/scope are explicit; capability impact is singular/specific and matches ledger deltas.
114
143
  - [ ] Architecture/flows/decisions are linked, not duplicated; Coverage seed names Clarify surfaces.
@@ -20,7 +20,9 @@ Pull on demand: `patterns.md` +
20
20
  `coding-style.md` (the over-engineering / YAGNI rubric (reuse the pack's standard, don't
21
21
  invent one), `documentation.md` (ADR-style `decisions.md` entries), `afk-hitl.md`
22
22
  (irreversible-risk list + gate ceiling), `elicitation.md` (the move-set to deepen a section
23
- that needs more than the default pre-mortem) selected by the section's risk).
23
+ that needs more than the default pre-mortem) selected by the section's risk). Load
24
+ `repository-topology.md`, `data-integrity.md`, or `integration-reliability.md` only when
25
+ the spec applicability map triggers that risk family.
24
26
 
25
27
  ## Operating rules
26
28
  - **Raise outcome ambition without expanding the solution unnecessarily.** Solve the
@@ -67,6 +69,8 @@ that needs more than the default pre-mortem) selected by the section's risk).
67
69
  **Interruption pre-mortem:** audit the spec forecast and assumptions for unresolved behavior,
68
70
  proof prerequisites, approvals, access, and irreversible gates. Resolve facts and reversible
69
71
  details now; retain only unavailable-pre-code or mandatory action-time checkpoints.
72
+ Challenge each `not applicable` decision against live evidence and each applicable
73
+ topology/data/integration row against its worst credible partial-state/recovery case.
70
74
  - **Deepen on demand.** When a scope decision, requirement, or risk needs more analysis
71
75
  than the default pre-mortem provides, choose 3-5 techniques from
72
76
  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) whose *when-to-reach-for-it* matches that
@@ -21,7 +21,8 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
21
21
  `coding-style.md`, `testing.md`, `spec-grammar.md`, `performance.md`,
22
22
  `error-handling.md`, `development-workflow.md`, `afk-hitl.md`,
23
23
  `one-shot-actions.md`, `developer-experience.md`, `elicitation.md`, and
24
- `definition-of-done.md`.
24
+ `definition-of-done.md`. Load `repository-topology.md`, `data-integrity.md`, and
25
+ `integration-reliability.md` only when the spec applicability map or live plan triggers them.
25
26
 
26
27
 
27
28
  ## Operating rules
@@ -85,14 +86,13 @@ Pull the standard named by the active axis: `principles.md`, `patterns.md`,
85
86
  [`reference/review-axes.md`](reference/review-axes.md). Search accepted ADRs and
86
87
  relevant workspace `decisions.md` files directly. Harden to the smallest
87
88
  behavior-preserving plan; ask only when that changes acceptance or explicit architecture policy.
88
- 2a. **Cross-artifact/project gates.** Apply explicit checklists to spec, tasks,
89
- and traceability. Every AC/REQ maps by ID and meaning to a real slice/proof;
90
- every slice maps back. Check terminology/conflicts, principles, anti-slop, and
91
- conventions. Critical blocks; principle exceptions are human-owned. Recheck
92
- after hardening and write `analysis.md`.
89
+ 2a. **Cross-artifact/project gates.** Check spec/tasks/traceability: every AC/REQ maps by
90
+ ID/meaning to slice/proof and back. Check terms, conflicts, principles, anti-slop, conventions;
91
+ Critical blocks and principle exceptions are human-owned. Recheck, then write `analysis.md`.
93
92
  2b. **Build-entry preflight.** Using [`reference/artifacts.md`](reference/artifacts.md), verify
94
- every exact proof command/cwd/tool/version/prerequisite; package names against authoritative
95
- source and nearest manifest/lockfile; parser-sensitive syntax in an isolated fixture;
93
+ exact command/cwd/tool/version/prerequisite; output filters must preserve upstream failure or
94
+ check producer status separately. Verify packages against authoritative source and nearest
95
+ manifest/lockfile; parser-sensitive syntax in an isolated fixture;
96
96
  applicable UI/browser harnesses. Remeasure decision-bearing counts/versions/state
97
97
  claims read-only: live facts win; conflicts mark stale artifacts;
98
98
  unmeasurable conflict = gap. Record complete SHA-256 provenance inputs. Require
@@ -47,9 +47,9 @@ One-shot evidence completeness: <n/a | pass: action + retained artifact + bounds
47
47
  Suppressed (confidence ≤4, unverified): <count — one line each>
48
48
 
49
49
  ## 4. Failure modes
50
- | New codepath | Realistic failure | Test? | Handling? | Silent? | Verdict |
51
- |---|---|---|---|---|---|
52
- | <path> | timeout / nil / race / stale | y/n | y/n | y/n | ok / **CRITICAL gap** |
50
+ | New codepath/boundary | Realistic failure | Partial/unknown effect | Recovery owner/path | Proof? | Silent? | Verdict |
51
+ |---|---|---|---|---|---|---|
52
+ | <path> | timeout / duplicate / race / stale | <state/effect> | <owner/action> | y/n | y/n | ok / **CRITICAL gap** |
53
53
 
54
54
  ## 5. Dependency safety
55
55
  <declared order is safe | exact dependency/order correction>
@@ -152,6 +152,8 @@ acceptance/behavior changes route through the **Spec Drift Guard**.
152
152
  - **Write directly into `plan.md` / `tasks.md`** (single canonical writer: you, not the reviewer):
153
153
  - `plan.md` §Scope boundaries ← "NOT in scope" items.
154
154
  - `plan.md` §Architecture decisions ← reuse-over-rebuild calls + named failure scenarios.
155
+ - `plan.md` §Applicability and system ownership ← corrected topology/data/integration
156
+ routing and each triggered standard's feature-specific output.
155
157
  - `plan.md` §Dependency graph / §Implementation order ← any dependency or ordering fix
156
158
  (e.g. refactor-before-feature split).
157
159
  - `plan.md` §Complexity & deviations gate ← any deviation the §0 challenge surfaced + its justification.
@@ -1,9 +1,7 @@
1
1
  # Vet review: scope, four axes, and outputs
2
2
 
3
- Run §0 first as a blocking gate, then review the four axes in order and produce the
4
- required outputs. Apply the engineering lenses in [`eng-lenses.md`](eng-lenses.md)
5
- throughout rather than as a separate checklist. Calibrate every finding through the
6
- confidence and verification gate before presenting it.
3
+ Run blocking §0, then the four axes and required outputs. Apply
4
+ [`eng-lenses.md`](eng-lenses.md) throughout; calibrate every finding before presenting it.
7
5
 
8
6
  ---
9
7
 
@@ -12,29 +10,33 @@ confidence and verification gate before presenting it.
12
10
  Before reviewing implementation details, check whether the plan includes more work than
13
11
  the settled spec requires.
14
12
 
15
- 1. **What already exists?** For each sub-problem in the plan, find the existing code/flow that
16
- already solves it (use a code-intelligence index if available: see `../../devrites-lib/reference/standards/tooling.md`).
17
- Can the plan **capture outputs from an existing
18
- flow** instead of building a parallel one? Reuse extend → build new, in that order
19
- (`coding-style.md`). List every reuse opportunity the plan misses.
20
- 2. **Minimum diff.** Find the smallest set of changes that meets the spec's acceptance
21
- criteria. Flag work that can be deferred without blocking acceptance. Do not cut an
22
- acceptance criterion; that requires the Drift Guard.
23
- 3. **Complexity smell.** If `plan.md` touches **>8 files** or adds **>2 new services / modules /
24
- classes**, treat it as a smell. Check the plan's complexity gate justifies it. If it doesn't
25
- harden to the smallest acceptance-preserving plan. Ask only if reduction changes
26
- acceptance or explicit architecture policy; never start the axes unresolved.
27
- 4. **Built-in check.** For each new pattern / infra component / concurrency approach the plan
28
- introduces, verify a framework/runtime built-in doesn't already do it, and that the choice is
29
- current best practice with no known footgun: invoke `devrites-source-driven` to confirm at
30
- the source and record the citation. A custom roll where a built-in exists is a scope-reduction
31
- finding.
32
- 5. **Completeness check.** Identify shortcuts in edge-case handling, error paths, and
33
- test coverage. Prefer the complete option when AI-assisted implementation makes the
34
- additional work small. Flag shortcuts that save little time but leave known gaps.
13
+ 1. **What exists?** Find existing code/flows for each sub-problem (use the index per
14
+ [`tooling.md`](../../devrites-lib/reference/standards/tooling.md)). Can the plan capture their outputs instead of building parallel work?
15
+ Reuse extend build new; list missed reuse.
16
+ 2. **Minimum diff.** Find the smallest acceptance-complete change. Flag non-blocking work;
17
+ cutting acceptance requires Drift Guard.
18
+ 3. **Complexity smell.** **>8 files** or **>2 new services/modules/classes** needs a justified
19
+ complexity gate; otherwise harden to the smallest acceptance-preserving plan. Ask only if
20
+ reduction changes acceptance or architecture policy.
21
+ 4. **Built-in check.** For each new pattern/infra/concurrency approach, dispatch
22
+ `devrites-source-driven` to verify current framework/runtime support and cite it. Custom
23
+ work where a built-in suffices is a scope-reduction finding.
24
+ 5. **Completeness.** Find edge/error/test shortcuts; prefer the complete option when the
25
+ extra work is small, and flag small savings that leave known gaps.
35
26
  6. **Distribution check.** If the plan introduces a new artifact (CLI binary, package, container,
36
27
  deployable), does it include how it gets built / published / installed? If distribution is
37
28
  deferred, say so explicitly in "NOT in scope": don't let it silently drop.
29
+ 7. **Applicability check.** Compare `spec.md`'s topology/data/integration/security/delivery
30
+ decisions with live seams. A false `not applicable` or an `applies` row without the
31
+ focused standard's owner, failure/recovery, deployment order, and proof output is `broken`.
32
+ 8. **Decision horizons.** Independently apply
33
+ [`plan-template.md`](../../rite-define/reference/plan-template.md#decision-horizons) to the
34
+ plan, questions, assumptions, decisions, and checkpoints; no known item may disappear.
35
+ Reject `local` for blockers or public contracts, security/data invariants, acceptance,
36
+ migration/rollback, dependencies, or cross-slice interfaces. Local/checkpoint deferral
37
+ needs bounded owner, evidence trigger, fallback, and resolution proof; a risk spike needs
38
+ necessary executable evidence, discriminating criteria, and fallback branches. Any defect is
39
+ `broken`; unresolved human blockers return to Clarify.
38
40
 
39
41
  > **STOP discipline.** Fold technical reduction into the plan; ask and stop only for a
40
42
  > human-owned choice.
@@ -45,46 +47,43 @@ If the smell does not trip, present the §0 findings and proceed to Axis 1.
45
47
 
46
48
  ## Four axes (one at a time, at most 8 findings each)
47
49
 
48
- For each axis, fold verified technical findings into the plan, then walk each human-owned
49
- decision via one coherent `AskUserQuestion` packet. Supporting findings may combine only
50
- with one owner/trade-off. HITL pauses there; AFK follows `depth.md`. Never invent findings.
50
+ Fold verified technical findings into the plan; present each human-owned decision in one
51
+ `AskUserQuestion` packet. Combine support only for one owner/trade-off. HITL pauses; AFK
52
+ uses `depth.md`. Never invent findings.
51
53
 
52
54
  ### 1. Architecture
53
- - Component boundaries, coupling, data-flow patterns, single points of failure. Architecture records invariants, not scaffolding: each medium+ decision should state `Binds:` and `Prevents:` so the builder knows what divergence it prevents.
54
- - Scaling characteristics; where the plan's approach breaks under real load.
55
+ - Boundaries, coupling, data flow, single points of failure. Record invariants, not
56
+ scaffolding; medium+ decisions state `Binds:`/`Prevents:`.
57
+ - Repository/deployable roots, canonical contract and mutable-state ownership, shared
58
+ resources, dependency cycles, and old/new deployment combinations when applicable.
59
+ - Scaling ceiling under real load.
55
60
  - Security architecture at the seams (auth, data access, API boundaries): does the plan name
56
61
  the trust boundary for each untrusted input?
57
- - For each new codepath / integration point: **one realistic production failure scenario** and
58
- whether the plan accounts for it (feeds the failure-mode table).
62
+ - One realistic production failure per new codepath/integration (feeds failure-mode table).
59
63
  - Does any key flow deserve an ASCII diagram in the plan or an inline comment in the code the
60
64
  build will write? Name the files that should carry one.
61
65
 
62
66
  ### 2. Plan code-quality
63
- - Module structure the plan implies; DRY across the slices (flag planned repetition aggressively).
67
+ - Implied modules and planned cross-slice repetition.
64
68
  - Error-handling + edge cases the plan names, and the ones it doesn't (call those out explicitly).
65
69
  - Over-engineering (premature abstraction, an extension point with no second caller) vs
66
70
  under-engineering (fragile / hacky) relative to `patterns.md` + `coding-style.md`.
67
- - Tech-debt hotspots the plan walks into; existing inline diagrams in touched files that the
68
- change will make stale.
71
+ - Tech-debt hotspots and diagrams the change makes stale.
69
72
 
70
73
  ### 3. Test-coverage design
71
- Design tests before code so the build writes them alongside the implementation.
72
- - **Framework detection:** find the project's existing test runner + conventions; match them
73
- (never introduce a new runner to prove one change: `testing.md`).
74
- - **Map acceptance → tests.** Every spec acceptance criterion must map to ≥1 planned, surface-anchored test (the API response/UI state/CLI output the criterion names, not an internal proxy).
75
- - **Tool per path:** unit (pure logic, single function, edge cases), integration/E2E (a user
76
- flow spanning 3+ components, an auth/payment/data-loss path, a mock-hides-failure boundary),
77
- eval (an LLM/prompt change that needs a quality bar).
78
- - **Interaction inventory (UI slices): enumerate every interactive element + flow.** List each
79
- input field, checkbox, radio, select, toggle, button, and actionable link, plus each user
80
- flow; assign each ≥1 asserting test **at the right level**: elements/fields → unit/component,
81
- critical journeys → one E2E (never one-per-field). Every element/flow with no asserting test
82
- is a GAP; no element ships unverified. Write the inventory to `test-plan.md` (table in
83
- `artifacts.md`). This is `testing.md` "Completeness" made concrete for the plan.
84
- - **Regression rule (mandatory, no question):** when the plan modifies existing behavior and the
85
- current suite doesn't cover the changed path, a regression test is added to the plan as a
86
- **Critical** requirement: no `AskUserQuestion`, no skipping. Regressions are the highest-priority
87
- test because they prove something broke. When unsure whether a change is a regression, write the test.
74
+ Design tests before code.
75
+ - **Framework:** match the existing runner/conventions; never add a runner for one change.
76
+ - **Acceptance tests.** Every AC maps to a planned surface assertion, not an internal proxy.
77
+ - **Map applicable risk → tests.** Data and integration rows cover their relevant
78
+ duplicate/retry/concurrency/interruption/tenant/timeout/partial/outage/order/rollback cases,
79
+ or record an evidence-backed dismissal. A mock that cannot exhibit the named risk is a GAP.
80
+ - **Tool per path:** unit for pure logic; integration/E2E for 3+ components,
81
+ auth/payment/data-loss, or mock-hidden failure; eval for LLM/prompt quality.
82
+ - **UI inventory:** list every interactive element/flow in `test-plan.md`; assign
83
+ elements/fields a unit/component assertion and critical journeys an E2E. Untested = GAP;
84
+ no one-E2E-per-field (`artifacts.md`).
85
+ - **Regression (mandatory):** changed behavior without path coverage adds a **Critical**
86
+ regression test—no question or skip. If uncertain, write it.
88
87
  - Produce the **coverage diagram** (shape below) and add a specific test requirement per GAP.
89
88
 
90
89
  #### Coverage diagram (write to `test-plan.md`)
@@ -119,45 +118,36 @@ Tag each finding `[severity] (confidence: N/10) <plan/task/spec ref> — finding
119
118
  - **5-6** moderate → report with "verify this is real".
120
119
  - **≤4** speculative → **suppress from the walk-through**, appendix only.
121
120
 
122
- Before raising a finding, quote the lines that support it. If no line supports it, set
123
- confidence to 4 or lower and suppress it. Do not inflate confidence to avoid suppression.
124
- `devrites-plan-reviewer` follows the same rule.
121
+ Quote supporting lines. Without them confidence is ≤4 and suppressed; never inflate it.
122
+ `devrites-plan-reviewer` follows this rule.
125
123
 
126
124
  ---
127
125
 
128
126
  ## Present human-owned decisions
129
- Use `AskUserQuestion` per the pack's standard. Plan-review specifics:
127
+ Use standard `AskUserQuestion`:
130
128
  - **One decision = one call.** Never ask about agent work or batch unrelated choices.
131
129
  - Concrete: name the plan/task section + the quoted line.
132
130
  - 2-3 options, including "do nothing / proceed as-is" where reasonable.
133
- - Per option, one line: **effort** (human ~X / with the build agent ~Y), **risk**, **maintenance**.
134
- If the complete option is only marginally more effort than the shortcut (AI makes it cheap),
135
- recommend complete.
131
+ - Per option: **effort** (human/build agent), **risk**, **maintenance**; recommend complete
132
+ when marginally costlier than a shortcut.
136
133
  - **Map to a rule.** One sentence tying the recommendation to a DevRites rule (reuse-first,
137
134
  fail-fast, test-behavior, measure-first, minimum diff).
138
- - **Coverage vs kind:** if the options differ in *coverage* (more tests vs fewer, complete vs
139
- happy-path), add `Completeness: N/10` per option. If they differ in *kind* (two different
140
- architectures), skip the score and note "options differ in kind, not coverage". Never fabricate
141
- a score on a kind question.
142
- - Every material call ends as a **recorded decision**: behavior-preserving technical hardening
143
- goes to `decisions.md`; a human-owned HITL choice gets a resolved `questions.md` qid; AFK
144
- records the allowed recommendation in `decisions.md`. The review must leave an auditable
145
- trail without turning agent work into questions.
135
+ - **Coverage vs kind:** coverage options get `Completeness: N/10`; architecture/kind options
136
+ state “differ in kind” and get no fabricated score.
137
+ - Record every material call: technical hardening/AFK in `decisions.md`; HITL in a resolved
138
+ `questions.md` qid. Do not turn agent work into questions.
146
139
 
147
140
  ---
148
141
 
149
142
  ## Required outputs (after the axes)
150
- 1. **"NOT in scope":** work considered and explicitly deferred, one-line rationale each. Folds
151
- into `plan.md` §Scope boundaries + `spec.md` Non-goals (via the Guard) so it can't silently re-enter.
152
- 2. **"What already exists":** existing code/flows that solve sub-problems, and whether the plan
153
- reuses or rebuilds them. Every missed reuse becomes a §0 finding.
154
- 3. **Failure-mode table:** for each new codepath: a realistic failure, and whether (a) a test
155
- covers it, (b) error handling exists, (c) the user sees a clear error or a silent failure. A
156
- failure with **no test AND no handling AND silent** is a **Critical gap**. (Shape in
157
- [`artifacts.md`](artifacts.md).)
158
- 4. **Dependency safety:** verify the declared dependency graph, required execution order,
159
- and conflicts where slices touch the same module. Correct unsafe or missing ordering in the
160
- plan; do not create a lane/scheduler artifact—the native host schedules eligible work.
143
+ 1. **"NOT in scope":** considered/deferred work + rationale, folded into plan boundaries and
144
+ spec Non-goals via the Guard.
145
+ 2. **"What exists":** solving code/flows and reuse/rebuild disposition; missed reuse is §0.
146
+ 3. **Failure-mode table:** per new codepath: realistic failure, partial/unknown effect,
147
+ recovery owner, test, handling, and user-visible/silent result. No test + no handling +
148
+ silent = **Critical** (`artifacts.md`).
149
+ 4. **Dependency safety:** verify graph/order and shared file/state/contract/lock/port/queue/env
150
+ conflicts. Correct the plan; native host scheduling needs no lane artifact.
161
151
  5. **Build-entry preflight:** commands/cwds, tools, package state, parser/browser smoke,
162
152
  prerequisites, and provenance ([`artifacts.md`](artifacts.md)).
163
153
  6. **Implementation readiness:** goal-backward coverage, wiring, dependency simulation,