devrites 3.0.7 → 3.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 (472) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +67 -47
  3. package/SECURITY.md +31 -29
  4. package/docs/adr/0001-go-engine-as-control-plane.md +1 -1
  5. package/docs/adr/0002-dual-host-harness.md +1 -1
  6. package/docs/adr/0004-state-schema-phases-sections.md +1 -2
  7. package/docs/adr/0006-clock-seam-and-engine-ci-gates.md +3 -4
  8. package/docs/adr/0009-prebuild-decision-coverage-and-readiness.md +67 -0
  9. package/docs/adr/0010-agent-first-fresh-context-orchestration.md +71 -0
  10. package/docs/adr/0011-define-plan-transition-rights.md +28 -0
  11. package/docs/adr/README.md +3 -0
  12. package/docs/agents/triage-labels.md +7 -7
  13. package/docs/architecture.md +157 -140
  14. package/docs/cli.md +41 -12
  15. package/docs/command-map.md +49 -35
  16. package/docs/engine/agent-contract.md +92 -15
  17. package/docs/engine/commands.md +242 -72
  18. package/docs/engine/state-schema.md +52 -23
  19. package/docs/engine/workspace-schema.md +94 -15
  20. package/docs/extensions.md +1 -1
  21. package/docs/flow.md +80 -50
  22. package/docs/harness-compliance.md +29 -5
  23. package/docs/orchestration.md +107 -79
  24. package/docs/quick-reference.md +7 -3
  25. package/docs/release.md +4 -3
  26. package/docs/skills.md +64 -38
  27. package/docs/usage.md +57 -38
  28. package/engine/cmd/releasepack/main.go +219 -0
  29. package/engine/cmd/releasepack/main_test.go +170 -0
  30. package/engine/commands.go +170 -23
  31. package/engine/git_guard.go +187 -0
  32. package/engine/git_guard_test.go +283 -0
  33. package/engine/hookpolicy.go +53 -55
  34. package/engine/hookpolicy_test.go +91 -1
  35. package/engine/hooks.go +296 -75
  36. package/engine/hooks_events_test.go +276 -6
  37. package/engine/hooks_workspace.go +640 -159
  38. package/engine/internal/devritespaths/paths.go +65 -10
  39. package/engine/internal/devritespaths/paths_test.go +110 -0
  40. package/engine/internal/doctor/doctor.go +153 -23
  41. package/engine/internal/doctor/doctor_test.go +74 -0
  42. package/engine/internal/forge/forge.go +940 -0
  43. package/engine/internal/forge/forge_test.go +576 -0
  44. package/engine/internal/forge/git.go +245 -0
  45. package/engine/internal/forge/liveness_unix.go +48 -0
  46. package/engine/internal/forge/liveness_windows.go +67 -0
  47. package/engine/internal/forge/manifest.go +402 -0
  48. package/engine/internal/gate/gate.go +90 -71
  49. package/engine/internal/gate/gate_test.go +71 -2
  50. package/engine/internal/harness/compliance.go +18 -24
  51. package/engine/internal/harness/harness.go +37 -44
  52. package/engine/internal/harness/harness_test.go +21 -5
  53. package/engine/internal/install/install.go +486 -38
  54. package/engine/internal/install/install_test.go +383 -10
  55. package/engine/internal/iohooks/iohooks.go +350 -59
  56. package/engine/internal/iohooks/iohooks_test.go +421 -1
  57. package/engine/internal/lib/buildreadiness.go +35 -18
  58. package/engine/internal/lib/clarifyreturn.go +91 -0
  59. package/engine/internal/lib/clarifyreturn_test.go +123 -0
  60. package/engine/internal/lib/context.go +54 -15
  61. package/engine/internal/lib/cursor_compat_test.go +8 -0
  62. package/engine/internal/lib/extensions.go +2 -3
  63. package/engine/internal/lib/gitauthority.go +601 -0
  64. package/engine/internal/lib/gitauthority_test.go +346 -0
  65. package/engine/internal/lib/jsonout.go +25 -11
  66. package/engine/internal/lib/jsonout_test.go +16 -0
  67. package/engine/internal/lib/lanes.go +14 -8
  68. package/engine/internal/lib/observability_test.go +358 -0
  69. package/engine/internal/lib/packageexistence.go +151 -35
  70. package/engine/internal/lib/packageexistence_test.go +163 -0
  71. package/engine/internal/lib/progress.go +11 -9
  72. package/engine/internal/lib/provenance.go +462 -0
  73. package/engine/internal/lib/provenance_test.go +154 -0
  74. package/engine/internal/lib/readiness_contract.json +111 -0
  75. package/engine/internal/lib/readinessartifact.go +510 -0
  76. package/engine/internal/lib/readinessartifact_test.go +321 -0
  77. package/engine/internal/lib/reconcile.go +712 -88
  78. package/engine/internal/lib/reconcile_test.go +335 -16
  79. package/engine/internal/lib/recoveryattempts.go +298 -0
  80. package/engine/internal/lib/recoveryattempts_test.go +215 -0
  81. package/engine/internal/lib/resolve.go +23 -19
  82. package/engine/internal/lib/runbook_context_test.go +20 -0
  83. package/engine/internal/lib/session.go +701 -9
  84. package/engine/internal/lib/session_test.go +80 -13
  85. package/engine/internal/lib/testintegrity.go +33 -37
  86. package/engine/internal/lib/testintegrity_test.go +63 -1
  87. package/engine/internal/migrate/migrate.go +81 -1
  88. package/engine/internal/migrate/migrate_test.go +22 -1
  89. package/engine/internal/reason/reason.go +180 -0
  90. package/engine/internal/reason/reason_test.go +35 -0
  91. package/engine/internal/rootfacts/facts.go +466 -0
  92. package/engine/internal/rootfacts/facts_test.go +306 -0
  93. package/engine/internal/safepath/safepath.go +55 -0
  94. package/engine/internal/safepath/safepath_test.go +69 -0
  95. package/engine/internal/safepath/safepath_windows_test.go +26 -0
  96. package/engine/internal/state/clarify_transition.go +165 -0
  97. package/engine/internal/state/clarify_transition_test.go +130 -0
  98. package/engine/internal/state/cmd/workflowmanifest/main.go +12 -8
  99. package/engine/internal/state/cursor.go +58 -0
  100. package/engine/internal/state/cursor_test.go +42 -1
  101. package/engine/internal/state/feature.go +35 -48
  102. package/engine/internal/state/schema.go +90 -37
  103. package/engine/internal/state/snapshot.go +18 -2
  104. package/engine/internal/state/state_test.go +187 -7
  105. package/engine/internal/state/status.go +48 -11
  106. package/engine/internal/state/workflow_manifest.json +231 -50
  107. package/engine/internal/toolpolicy/classifier.go +533 -0
  108. package/engine/internal/toolpolicy/classifier_test.go +424 -0
  109. package/engine/internal/toolpolicy/git.go +616 -0
  110. package/engine/internal/toolpolicy/scanner.go +382 -0
  111. package/engine/main.go +160 -77
  112. package/engine/observability_cli_test.go +52 -0
  113. package/engine/root_routing_test.go +277 -0
  114. package/engine/testdata/golden/TestParityBuildReadiness/arg=approved.golden +1 -1
  115. package/engine/testdata/golden/TestParityBuildReadiness/arg=emptystatus.golden +1 -1
  116. package/engine/testdata/golden/TestParityBuildReadiness/arg=noclarify.golden +1 -0
  117. package/engine/testdata/golden/TestParityBuildReadiness/arg=novet.golden +1 -0
  118. package/engine/testdata/golden/TestParityBuildReadiness/arg=stalevet.golden +1 -0
  119. package/engine/testdata/golden/TestParityBuildReadiness/arg=trailhash.golden +1 -1
  120. package/engine/testdata/golden/TestParityBuildReadiness/arg=trailpipe.golden +1 -1
  121. package/engine/testdata/golden/TestParityBuildReadiness/arg=vetnotready.golden +1 -0
  122. package/engine/testdata/golden/TestParityProgress/arg=allbuilt.golden +1 -1
  123. package/engine/testdata/golden/TestParityProgress/arg=done.golden +1 -1
  124. package/engine/testdata/golden/TestParityProgress/arg=mid.golden +1 -1
  125. package/engine/testdata/golden/TestParityProgress/arg=nophase.golden +1 -1
  126. package/engine/testdata/golden/TestParityProgress/arg=noslice.golden +1 -1
  127. package/engine/testdata/golden/TestParityProgress/arg=plan.golden +1 -1
  128. package/engine/testdata/golden/TestParityProgress/arg=seal.golden +1 -1
  129. package/engine/testdata/golden/TestParityReconcile/check-clean.golden +1 -1
  130. package/engine/testdata/golden/TestParityReconcile/inline-fallback.golden +1 -0
  131. package/engine/testdata/golden/TestParityReconcile/snapshot-no-allowlist.golden +1 -0
  132. package/engine/testdata/golden/TestParityWrightScope/devrites-edit-denied.golden +2 -0
  133. package/engine/testdata/golden/TestParityWrightScope/out-of-scope-enforce-denies.golden +1 -1
  134. package/engine/tests/adr_0011_define_plan_test.go +30 -0
  135. package/engine/tests/budget_test.go +19 -8
  136. package/engine/tests/concurrency_cli_test.go +7 -1
  137. package/engine/tests/doctor_cli_test.go +148 -2
  138. package/engine/tests/forge_cli_test.go +463 -0
  139. package/engine/tests/gate_test.go +63 -8
  140. package/engine/tests/hook_test.go +260 -8
  141. package/engine/tests/hooks_io_test.go +94 -3
  142. package/engine/tests/json_contract_test.go +127 -2
  143. package/engine/tests/migrate_cli_test.go +2 -2
  144. package/engine/tests/parity_buildreadiness_test.go +141 -10
  145. package/engine/tests/parity_learnings_test.go +16 -17
  146. package/engine/tests/parity_reconcile_test.go +20 -17
  147. package/engine/tests/parity_resolve_test.go +12 -11
  148. package/engine/tests/parity_test.go +21 -17
  149. package/pack/.claude/agents/devrites-code-reviewer.md +62 -48
  150. package/pack/.claude/agents/devrites-devex-reviewer.md +69 -53
  151. package/pack/.claude/agents/devrites-doubt-reviewer.md +29 -22
  152. package/pack/.claude/agents/devrites-evidence-scout.md +69 -0
  153. package/pack/.claude/agents/devrites-forge-judge.md +74 -61
  154. package/pack/.claude/agents/devrites-frontend-reviewer.md +48 -39
  155. package/pack/.claude/agents/devrites-performance-reviewer.md +49 -40
  156. package/pack/.claude/agents/devrites-plan-drafter.md +71 -0
  157. package/pack/.claude/agents/devrites-plan-reviewer.md +80 -47
  158. package/pack/.claude/agents/devrites-proof-runner.md +74 -0
  159. package/pack/.claude/agents/devrites-retrospector.md +48 -45
  160. package/pack/.claude/agents/devrites-security-auditor.md +46 -36
  161. package/pack/.claude/agents/devrites-simplifier-reviewer.md +50 -46
  162. package/pack/.claude/agents/devrites-slice-wright.md +153 -165
  163. package/pack/.claude/agents/devrites-spec-reviewer.md +34 -32
  164. package/pack/.claude/agents/devrites-strategy-reviewer.md +63 -34
  165. package/pack/.claude/agents/devrites-test-analyst.md +40 -30
  166. package/pack/.claude/settings.json +2 -1
  167. package/pack/.claude/skills/devrites-audit/SKILL.md +40 -61
  168. package/pack/.claude/skills/devrites-debug-recovery/SKILL.md +24 -13
  169. package/pack/.claude/skills/devrites-debug-recovery/reference/build-the-loop.md +24 -21
  170. package/pack/.claude/skills/devrites-debug-recovery/reference/cleanup-and-classify.md +34 -6
  171. package/pack/.claude/skills/devrites-debug-recovery/reference/instrumentation.md +2 -2
  172. package/pack/.claude/skills/devrites-doubt/SKILL.md +25 -17
  173. package/pack/.claude/skills/devrites-interview/SKILL.md +53 -52
  174. package/pack/.claude/skills/devrites-lib/SKILL.md +11 -9
  175. package/pack/.claude/skills/devrites-lib/reference/intent-map.md +3 -2
  176. package/pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md +82 -137
  177. package/pack/.claude/skills/devrites-lib/reference/reply-contract.md +8 -1
  178. package/pack/.claude/skills/devrites-lib/reference/standards/README.md +38 -55
  179. package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md +53 -27
  180. package/pack/.claude/skills/devrites-lib/reference/standards/agents.md +198 -190
  181. package/pack/.claude/skills/devrites-lib/reference/standards/anti-patterns.md +5 -15
  182. package/pack/.claude/skills/devrites-lib/reference/standards/ci-cd.md +27 -58
  183. package/pack/.claude/skills/devrites-lib/reference/standards/code-review.md +16 -52
  184. package/pack/.claude/skills/devrites-lib/reference/standards/coding-style.md +2 -10
  185. package/pack/.claude/skills/devrites-lib/reference/standards/context-hygiene.md +18 -61
  186. package/pack/.claude/skills/devrites-lib/reference/standards/core.md +23 -18
  187. package/pack/.claude/skills/devrites-lib/reference/standards/deprecation.md +17 -57
  188. package/pack/.claude/skills/devrites-lib/reference/standards/development-workflow.md +4 -33
  189. package/pack/.claude/skills/devrites-lib/reference/standards/git-workflow.md +4 -20
  190. package/pack/.claude/skills/devrites-lib/reference/standards/hooks.md +3 -14
  191. package/pack/.claude/skills/devrites-lib/reference/standards/patterns.md +9 -25
  192. package/pack/.claude/skills/devrites-lib/reference/standards/performance.md +0 -9
  193. package/pack/.claude/skills/devrites-lib/reference/standards/principles.md +1 -3
  194. package/pack/.claude/skills/devrites-lib/reference/standards/security.md +17 -7
  195. package/pack/.claude/skills/devrites-lib/reference/standards/testing.md +1 -27
  196. package/pack/.claude/skills/devrites-lib/reference/standards/tooling.md +46 -50
  197. package/pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md +23 -10
  198. package/pack/.claude/skills/devrites-source-driven/SKILL.md +23 -22
  199. package/pack/.claude/skills/rite/SKILL.md +8 -6
  200. package/pack/.claude/skills/rite/reference/menu.md +8 -6
  201. package/pack/.claude/skills/rite-adopt/SKILL.md +33 -37
  202. package/pack/.claude/skills/rite-autocomplete/SKILL.md +33 -28
  203. package/pack/.claude/skills/rite-autocomplete/reference/loop.md +21 -21
  204. package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md +15 -6
  205. package/pack/.claude/skills/rite-build/SKILL.md +35 -30
  206. package/pack/.claude/skills/rite-build/reference/afk-discipline.md +38 -38
  207. package/pack/.claude/skills/rite-build/reference/evidence-standard.md +10 -0
  208. package/pack/.claude/skills/rite-build/reference/forge.md +186 -156
  209. package/pack/.claude/skills/rite-build/reference/one-slice-cycle.md +4 -3
  210. package/pack/.claude/skills/rite-build/reference/phase-contract.md +96 -175
  211. package/pack/.claude/skills/rite-build/reference/wright-dispatch.md +129 -134
  212. package/pack/.claude/skills/rite-clarify/SKILL.md +89 -0
  213. package/pack/.claude/skills/rite-clarify/reference/decision-coverage.md +59 -0
  214. package/pack/.claude/skills/rite-converge/SKILL.md +35 -25
  215. package/pack/.claude/skills/rite-define/SKILL.md +57 -32
  216. package/pack/.claude/skills/rite-define/reference/gates.md +16 -15
  217. package/pack/.claude/skills/rite-define/reference/plan-template.md +16 -8
  218. package/pack/.claude/skills/rite-frame/reference/failure-modes.md +22 -24
  219. package/pack/.claude/skills/rite-plan/SKILL.md +44 -16
  220. package/pack/.claude/skills/rite-plan/reference/task-breakdown.md +4 -0
  221. package/pack/.claude/skills/rite-polish/SKILL.md +27 -23
  222. package/pack/.claude/skills/rite-prototype/SKILL.md +25 -26
  223. package/pack/.claude/skills/rite-prove/SKILL.md +27 -17
  224. package/pack/.claude/skills/rite-resolve/SKILL.md +12 -11
  225. package/pack/.claude/skills/rite-resolve/reference/answer-protocol.md +3 -0
  226. package/pack/.claude/skills/rite-review/SKILL.md +37 -28
  227. package/pack/.claude/skills/rite-seal/reference/phase-contract.md +27 -92
  228. package/pack/.claude/skills/rite-seal/reference/risk-and-rollback.md +13 -0
  229. package/pack/.claude/skills/rite-ship/reference/design-memory.md +31 -36
  230. package/pack/.claude/skills/rite-spec/SKILL.md +84 -135
  231. package/pack/.claude/skills/rite-spec/reference/investigation.md +37 -33
  232. package/pack/.claude/skills/rite-spec/reference/question-protocol.md +6 -2
  233. package/pack/.claude/skills/rite-spec/reference/spec-checklists.md +25 -24
  234. package/pack/.claude/skills/rite-spec/reference/spec-template.md +9 -2
  235. package/pack/.claude/skills/rite-spec/reference/state-workspace.md +13 -3
  236. package/pack/.claude/skills/rite-temper/SKILL.md +62 -47
  237. package/pack/.claude/skills/rite-temper/reference/review-dimensions.md +24 -22
  238. package/pack/.claude/skills/rite-vet/SKILL.md +110 -113
  239. package/pack/.claude/skills/rite-vet/reference/artifacts.md +42 -9
  240. package/pack/.claude/skills/rite-vet/reference/review-axes.md +39 -37
  241. package/pack/generated/claude/agents/devrites-code-reviewer.md +62 -48
  242. package/pack/generated/claude/agents/devrites-devex-reviewer.md +69 -53
  243. package/pack/generated/claude/agents/devrites-doubt-reviewer.md +29 -22
  244. package/pack/generated/claude/agents/devrites-evidence-scout.md +69 -0
  245. package/pack/generated/claude/agents/devrites-forge-judge.md +74 -61
  246. package/pack/generated/claude/agents/devrites-frontend-reviewer.md +48 -39
  247. package/pack/generated/claude/agents/devrites-performance-reviewer.md +49 -40
  248. package/pack/generated/claude/agents/devrites-plan-drafter.md +71 -0
  249. package/pack/generated/claude/agents/devrites-plan-reviewer.md +80 -47
  250. package/pack/generated/claude/agents/devrites-proof-runner.md +74 -0
  251. package/pack/generated/claude/agents/devrites-retrospector.md +48 -45
  252. package/pack/generated/claude/agents/devrites-security-auditor.md +46 -36
  253. package/pack/generated/claude/agents/devrites-simplifier-reviewer.md +50 -46
  254. package/pack/generated/claude/agents/devrites-slice-wright.md +153 -165
  255. package/pack/generated/claude/agents/devrites-spec-reviewer.md +34 -32
  256. package/pack/generated/claude/agents/devrites-strategy-reviewer.md +63 -34
  257. package/pack/generated/claude/agents/devrites-test-analyst.md +40 -30
  258. package/pack/generated/claude/settings.json +2 -1
  259. package/pack/generated/claude/skills/devrites-audit/SKILL.md +40 -61
  260. package/pack/generated/claude/skills/devrites-debug-recovery/SKILL.md +24 -13
  261. package/pack/generated/claude/skills/devrites-debug-recovery/reference/build-the-loop.md +24 -21
  262. package/pack/generated/claude/skills/devrites-debug-recovery/reference/cleanup-and-classify.md +34 -6
  263. package/pack/generated/claude/skills/devrites-debug-recovery/reference/instrumentation.md +2 -2
  264. package/pack/generated/claude/skills/devrites-doubt/SKILL.md +25 -17
  265. package/pack/generated/claude/skills/devrites-interview/SKILL.md +53 -52
  266. package/pack/generated/claude/skills/devrites-lib/SKILL.md +11 -9
  267. package/pack/generated/claude/skills/devrites-lib/reference/intent-map.md +3 -2
  268. package/pack/generated/claude/skills/devrites-lib/reference/parallel-dispatch.md +82 -137
  269. package/pack/generated/claude/skills/devrites-lib/reference/reply-contract.md +8 -1
  270. package/pack/generated/claude/skills/devrites-lib/reference/standards/README.md +38 -55
  271. package/pack/generated/claude/skills/devrites-lib/reference/standards/afk-hitl.md +53 -27
  272. package/pack/generated/claude/skills/devrites-lib/reference/standards/agents.md +198 -190
  273. package/pack/generated/claude/skills/devrites-lib/reference/standards/anti-patterns.md +5 -15
  274. package/pack/generated/claude/skills/devrites-lib/reference/standards/ci-cd.md +27 -58
  275. package/pack/generated/claude/skills/devrites-lib/reference/standards/code-review.md +16 -52
  276. package/pack/generated/claude/skills/devrites-lib/reference/standards/coding-style.md +2 -10
  277. package/pack/generated/claude/skills/devrites-lib/reference/standards/context-hygiene.md +18 -61
  278. package/pack/generated/claude/skills/devrites-lib/reference/standards/core.md +23 -18
  279. package/pack/generated/claude/skills/devrites-lib/reference/standards/deprecation.md +17 -57
  280. package/pack/generated/claude/skills/devrites-lib/reference/standards/development-workflow.md +4 -33
  281. package/pack/generated/claude/skills/devrites-lib/reference/standards/git-workflow.md +4 -20
  282. package/pack/generated/claude/skills/devrites-lib/reference/standards/hooks.md +3 -14
  283. package/pack/generated/claude/skills/devrites-lib/reference/standards/patterns.md +9 -25
  284. package/pack/generated/claude/skills/devrites-lib/reference/standards/performance.md +0 -9
  285. package/pack/generated/claude/skills/devrites-lib/reference/standards/principles.md +1 -3
  286. package/pack/generated/claude/skills/devrites-lib/reference/standards/security.md +17 -7
  287. package/pack/generated/claude/skills/devrites-lib/reference/standards/testing.md +1 -27
  288. package/pack/generated/claude/skills/devrites-lib/reference/standards/tooling.md +46 -50
  289. package/pack/generated/claude/skills/devrites-lib/reference/workspace-artifact-schema.md +23 -10
  290. package/pack/generated/claude/skills/devrites-source-driven/SKILL.md +23 -22
  291. package/pack/generated/claude/skills/rite/SKILL.md +8 -6
  292. package/pack/generated/claude/skills/rite/reference/menu.md +8 -6
  293. package/pack/generated/claude/skills/rite-adopt/SKILL.md +33 -37
  294. package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +33 -28
  295. package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md +21 -21
  296. package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md +15 -6
  297. package/pack/generated/claude/skills/rite-build/SKILL.md +35 -30
  298. package/pack/generated/claude/skills/rite-build/reference/afk-discipline.md +38 -38
  299. package/pack/generated/claude/skills/rite-build/reference/evidence-standard.md +10 -0
  300. package/pack/generated/claude/skills/rite-build/reference/forge.md +186 -156
  301. package/pack/generated/claude/skills/rite-build/reference/one-slice-cycle.md +4 -3
  302. package/pack/generated/claude/skills/rite-build/reference/phase-contract.md +96 -175
  303. package/pack/generated/claude/skills/rite-build/reference/wright-dispatch.md +129 -134
  304. package/pack/generated/claude/skills/rite-clarify/SKILL.md +89 -0
  305. package/pack/generated/claude/skills/rite-clarify/reference/decision-coverage.md +59 -0
  306. package/pack/generated/claude/skills/rite-converge/SKILL.md +35 -25
  307. package/pack/generated/claude/skills/rite-define/SKILL.md +57 -32
  308. package/pack/generated/claude/skills/rite-define/reference/gates.md +16 -15
  309. package/pack/generated/claude/skills/rite-define/reference/plan-template.md +16 -8
  310. package/pack/generated/claude/skills/rite-frame/reference/failure-modes.md +22 -24
  311. package/pack/generated/claude/skills/rite-plan/SKILL.md +44 -16
  312. package/pack/generated/claude/skills/rite-plan/reference/task-breakdown.md +4 -0
  313. package/pack/generated/claude/skills/rite-polish/SKILL.md +27 -23
  314. package/pack/generated/claude/skills/rite-prototype/SKILL.md +25 -26
  315. package/pack/generated/claude/skills/rite-prove/SKILL.md +27 -17
  316. package/pack/generated/claude/skills/rite-resolve/SKILL.md +12 -11
  317. package/pack/generated/claude/skills/rite-resolve/reference/answer-protocol.md +3 -0
  318. package/pack/generated/claude/skills/rite-review/SKILL.md +37 -28
  319. package/pack/generated/claude/skills/rite-seal/reference/phase-contract.md +27 -92
  320. package/pack/generated/claude/skills/rite-seal/reference/risk-and-rollback.md +13 -0
  321. package/pack/generated/claude/skills/rite-ship/reference/design-memory.md +31 -36
  322. package/pack/generated/claude/skills/rite-spec/SKILL.md +84 -135
  323. package/pack/generated/claude/skills/rite-spec/reference/investigation.md +37 -33
  324. package/pack/generated/claude/skills/rite-spec/reference/question-protocol.md +6 -2
  325. package/pack/generated/claude/skills/rite-spec/reference/spec-checklists.md +25 -24
  326. package/pack/generated/claude/skills/rite-spec/reference/spec-template.md +9 -2
  327. package/pack/generated/claude/skills/rite-spec/reference/state-workspace.md +13 -3
  328. package/pack/generated/claude/skills/rite-temper/SKILL.md +62 -47
  329. package/pack/generated/claude/skills/rite-temper/reference/review-dimensions.md +24 -22
  330. package/pack/generated/claude/skills/rite-vet/SKILL.md +110 -113
  331. package/pack/generated/claude/skills/rite-vet/reference/artifacts.md +42 -9
  332. package/pack/generated/claude/skills/rite-vet/reference/review-axes.md +39 -37
  333. package/pack/generated/codex/AGENTS.md +5 -2
  334. package/pack/generated/codex/agents/devrites-code-reviewer.toml +69 -47
  335. package/pack/generated/codex/agents/devrites-devex-reviewer.toml +75 -51
  336. package/pack/generated/codex/agents/devrites-doubt-reviewer.toml +35 -20
  337. package/pack/generated/codex/agents/devrites-evidence-scout.toml +75 -0
  338. package/pack/generated/codex/agents/devrites-forge-judge.toml +80 -59
  339. package/pack/generated/codex/agents/devrites-frontend-reviewer.toml +54 -37
  340. package/pack/generated/codex/agents/devrites-performance-reviewer.toml +55 -38
  341. package/pack/generated/codex/agents/devrites-plan-drafter.toml +77 -0
  342. package/pack/generated/codex/agents/devrites-plan-reviewer.toml +82 -47
  343. package/pack/generated/codex/agents/devrites-proof-runner.toml +80 -0
  344. package/pack/generated/codex/agents/devrites-retrospector.toml +54 -43
  345. package/pack/generated/codex/agents/devrites-security-auditor.toml +53 -35
  346. package/pack/generated/codex/agents/devrites-simplifier-reviewer.toml +56 -44
  347. package/pack/generated/codex/agents/devrites-slice-wright.toml +159 -163
  348. package/pack/generated/codex/agents/devrites-spec-reviewer.toml +40 -30
  349. package/pack/generated/codex/agents/devrites-strategy-reviewer.toml +65 -34
  350. package/pack/generated/codex/agents/devrites-test-analyst.toml +46 -28
  351. package/pack/generated/codex/hooks.json +4 -14
  352. package/pack/generated/codex/skills/devrites-api-interface/SKILL.md +7 -3
  353. package/pack/generated/codex/skills/devrites-audit/SKILL.md +47 -64
  354. package/pack/generated/codex/skills/devrites-browser-proof/SKILL.md +7 -3
  355. package/pack/generated/codex/skills/devrites-debug-recovery/SKILL.md +31 -16
  356. package/pack/generated/codex/skills/devrites-debug-recovery/reference/build-the-loop.md +24 -21
  357. package/pack/generated/codex/skills/devrites-debug-recovery/reference/cleanup-and-classify.md +34 -6
  358. package/pack/generated/codex/skills/devrites-debug-recovery/reference/instrumentation.md +2 -2
  359. package/pack/generated/codex/skills/devrites-doubt/SKILL.md +32 -20
  360. package/pack/generated/codex/skills/devrites-frontend-craft/SKILL.md +7 -3
  361. package/pack/generated/codex/skills/devrites-interview/SKILL.md +60 -55
  362. package/pack/generated/codex/skills/devrites-lib/SKILL.md +18 -12
  363. package/pack/generated/codex/skills/devrites-lib/reference/intent-map.md +3 -2
  364. package/pack/generated/codex/skills/devrites-lib/reference/parallel-dispatch.md +82 -137
  365. package/pack/generated/codex/skills/devrites-lib/reference/reply-contract.md +8 -1
  366. package/pack/generated/codex/skills/devrites-lib/reference/standards/README.md +38 -55
  367. package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md +53 -27
  368. package/pack/generated/codex/skills/devrites-lib/reference/standards/agents.md +198 -190
  369. package/pack/generated/codex/skills/devrites-lib/reference/standards/anti-patterns.md +5 -15
  370. package/pack/generated/codex/skills/devrites-lib/reference/standards/ci-cd.md +27 -58
  371. package/pack/generated/codex/skills/devrites-lib/reference/standards/code-review.md +16 -52
  372. package/pack/generated/codex/skills/devrites-lib/reference/standards/coding-style.md +2 -10
  373. package/pack/generated/codex/skills/devrites-lib/reference/standards/context-hygiene.md +18 -61
  374. package/pack/generated/codex/skills/devrites-lib/reference/standards/core.md +23 -18
  375. package/pack/generated/codex/skills/devrites-lib/reference/standards/deprecation.md +17 -57
  376. package/pack/generated/codex/skills/devrites-lib/reference/standards/development-workflow.md +4 -33
  377. package/pack/generated/codex/skills/devrites-lib/reference/standards/git-workflow.md +4 -20
  378. package/pack/generated/codex/skills/devrites-lib/reference/standards/hooks.md +3 -14
  379. package/pack/generated/codex/skills/devrites-lib/reference/standards/patterns.md +9 -25
  380. package/pack/generated/codex/skills/devrites-lib/reference/standards/performance.md +0 -9
  381. package/pack/generated/codex/skills/devrites-lib/reference/standards/principles.md +1 -3
  382. package/pack/generated/codex/skills/devrites-lib/reference/standards/security.md +17 -7
  383. package/pack/generated/codex/skills/devrites-lib/reference/standards/testing.md +1 -27
  384. package/pack/generated/codex/skills/devrites-lib/reference/standards/tooling.md +46 -50
  385. package/pack/generated/codex/skills/devrites-lib/reference/workspace-artifact-schema.md +23 -10
  386. package/pack/generated/codex/skills/devrites-prose-craft/SKILL.md +7 -3
  387. package/pack/generated/codex/skills/devrites-refresh-indexes/SKILL.md +7 -3
  388. package/pack/generated/codex/skills/devrites-source-driven/SKILL.md +29 -24
  389. package/pack/generated/codex/skills/devrites-ux-shape/SKILL.md +7 -3
  390. package/pack/generated/codex/skills/rite/SKILL.md +19 -13
  391. package/pack/generated/codex/skills/rite/reference/menu.md +8 -6
  392. package/pack/generated/codex/skills/rite-adopt/SKILL.md +40 -40
  393. package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +40 -31
  394. package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md +21 -21
  395. package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md +15 -6
  396. package/pack/generated/codex/skills/rite-build/SKILL.md +42 -33
  397. package/pack/generated/codex/skills/rite-build/reference/afk-discipline.md +38 -38
  398. package/pack/generated/codex/skills/rite-build/reference/evidence-standard.md +10 -0
  399. package/pack/generated/codex/skills/rite-build/reference/forge.md +186 -156
  400. package/pack/generated/codex/skills/rite-build/reference/one-slice-cycle.md +4 -3
  401. package/pack/generated/codex/skills/rite-build/reference/phase-contract.md +96 -175
  402. package/pack/generated/codex/skills/rite-build/reference/wright-dispatch.md +129 -134
  403. package/pack/generated/codex/skills/rite-clarify/SKILL.md +105 -0
  404. package/pack/generated/codex/skills/rite-clarify/reference/decision-coverage.md +59 -0
  405. package/pack/generated/codex/skills/rite-converge/SKILL.md +42 -28
  406. package/pack/generated/codex/skills/rite-customize/SKILL.md +7 -3
  407. package/pack/generated/codex/skills/rite-define/SKILL.md +64 -35
  408. package/pack/generated/codex/skills/rite-define/reference/gates.md +16 -15
  409. package/pack/generated/codex/skills/rite-define/reference/plan-template.md +16 -8
  410. package/pack/generated/codex/skills/rite-doctor/SKILL.md +7 -3
  411. package/pack/generated/codex/skills/rite-dogfood/SKILL.md +7 -3
  412. package/pack/generated/codex/skills/rite-explain/SKILL.md +7 -3
  413. package/pack/generated/codex/skills/rite-frame/SKILL.md +7 -3
  414. package/pack/generated/codex/skills/rite-frame/reference/failure-modes.md +22 -24
  415. package/pack/generated/codex/skills/rite-handoff/SKILL.md +7 -3
  416. package/pack/generated/codex/skills/rite-learn/SKILL.md +7 -3
  417. package/pack/generated/codex/skills/rite-plan/SKILL.md +51 -19
  418. package/pack/generated/codex/skills/rite-plan/reference/task-breakdown.md +5 -1
  419. package/pack/generated/codex/skills/rite-polish/SKILL.md +34 -26
  420. package/pack/generated/codex/skills/rite-pov/SKILL.md +7 -3
  421. package/pack/generated/codex/skills/rite-pr-feedback/SKILL.md +7 -3
  422. package/pack/generated/codex/skills/rite-pressure-test/SKILL.md +7 -3
  423. package/pack/generated/codex/skills/rite-prototype/SKILL.md +32 -29
  424. package/pack/generated/codex/skills/rite-prove/SKILL.md +34 -20
  425. package/pack/generated/codex/skills/rite-quick/SKILL.md +7 -3
  426. package/pack/generated/codex/skills/rite-resolve/SKILL.md +19 -14
  427. package/pack/generated/codex/skills/rite-resolve/reference/answer-protocol.md +3 -0
  428. package/pack/generated/codex/skills/rite-review/SKILL.md +44 -31
  429. package/pack/generated/codex/skills/rite-seal/SKILL.md +7 -3
  430. package/pack/generated/codex/skills/rite-seal/reference/phase-contract.md +27 -92
  431. package/pack/generated/codex/skills/rite-seal/reference/risk-and-rollback.md +13 -0
  432. package/pack/generated/codex/skills/rite-ship/SKILL.md +7 -3
  433. package/pack/generated/codex/skills/rite-ship/reference/design-memory.md +31 -36
  434. package/pack/generated/codex/skills/rite-spec/SKILL.md +91 -138
  435. package/pack/generated/codex/skills/rite-spec/reference/investigation.md +37 -33
  436. package/pack/generated/codex/skills/rite-spec/reference/question-protocol.md +6 -2
  437. package/pack/generated/codex/skills/rite-spec/reference/spec-checklists.md +25 -24
  438. package/pack/generated/codex/skills/rite-spec/reference/spec-template.md +9 -2
  439. package/pack/generated/codex/skills/rite-spec/reference/state-workspace.md +13 -3
  440. package/pack/generated/codex/skills/rite-status/SKILL.md +7 -3
  441. package/pack/generated/codex/skills/rite-temper/SKILL.md +69 -50
  442. package/pack/generated/codex/skills/rite-temper/reference/review-dimensions.md +24 -22
  443. package/pack/generated/codex/skills/rite-vet/SKILL.md +117 -116
  444. package/pack/generated/codex/skills/rite-vet/reference/artifacts.md +42 -9
  445. package/pack/generated/codex/skills/rite-vet/reference/review-axes.md +40 -38
  446. package/pack/generated/codex/skills/rite-zoom-out/SKILL.md +7 -3
  447. package/package.json +1 -1
  448. package/scripts/build-release-tarball.sh +32 -15
  449. package/scripts/check-authority-drift.py +125 -0
  450. package/scripts/check-instruction-size-baseline.mjs +19 -11
  451. package/scripts/check-invocation-integrity.py +2 -0
  452. package/scripts/codex-generate.sh +69 -33
  453. package/scripts/grade-feature.sh +121 -40
  454. package/scripts/live-hosts/agent-result.schema.json +230 -0
  455. package/scripts/live-hosts/claude.sh +87 -0
  456. package/scripts/live-hosts/codex.sh +81 -0
  457. package/scripts/live-hosts/common.sh +113 -0
  458. package/scripts/live-hosts/fake-host.py +264 -0
  459. package/scripts/live-hosts/host-transport.py +287 -0
  460. package/scripts/release-check.sh +5 -1
  461. package/scripts/run-agent-contract-evals.py +1380 -0
  462. package/scripts/run-behavioral-evals.sh +24 -30
  463. package/scripts/run-evals.sh +1 -5
  464. package/scripts/run-live-behavioral-evals.py +1274 -144
  465. package/scripts/run-outcome-evals.sh +414 -88
  466. package/scripts/run-tests.mjs +30 -2
  467. package/scripts/skills-inventory.mjs +1 -1
  468. package/scripts/validate-workflow-security.py +39 -20
  469. package/scripts/validate-workspace-schema.py +362 -10
  470. package/scripts/validate.sh +21 -15
  471. package/engine/testdata/golden/TestParityWrightScope/devrites-edit-allowed.golden +0 -1
  472. /package/engine/testdata/golden/{TestParityReconcile/check-no-claimed.golden → TestParityBuildReadiness/arg=clarifyopen.golden} +0 -0
@@ -11,9 +11,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
11
11
 
12
12
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
13
13
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
14
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
15
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
16
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
14
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
15
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
16
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
17
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
18
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
19
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
20
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
17
21
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
18
22
 
19
23
 
@@ -12,9 +12,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
12
12
 
13
13
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
14
14
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
15
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
16
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
17
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
15
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
16
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
17
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
18
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
19
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
20
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
21
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
18
22
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
19
23
 
20
24
 
@@ -11,9 +11,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
11
11
 
12
12
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
13
13
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
14
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
15
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
16
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
14
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
15
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
16
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
17
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
18
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
19
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
20
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
17
21
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
18
22
 
19
23
 
@@ -12,16 +12,20 @@ This is the Codex mirror of a DevRites skill. In Codex:
12
12
 
13
13
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
14
14
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
15
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
16
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
17
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
15
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
16
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
17
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
18
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
19
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
20
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
21
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
18
22
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
19
23
 
20
24
 
21
- # $rite-prototype: throwaway code that answers ONE question
25
+ # $rite-prototype: answer one question with throwaway code
22
26
 
23
- A prototype is **throwaway code that answers exactly one question**. The question
24
- chooses the shape: get the shape wrong and the whole prototype wastes the user's time.
27
+ A prototype is throwaway code for exactly one question. Choose its shape from that
28
+ question.
25
29
 
26
30
  ## 0. Read core rules
27
31
 
@@ -37,11 +41,12 @@ down. Examples that count as "the question":
37
41
  - "Which of these three settings layouts feels right?"
38
42
  - "Will the proposed state machine deadlock when X overlaps Y?"
39
43
 
40
- A vague question ("explore this feature") is not enough: push back once to sharpen it.
44
+ A vague request such as "explore this feature" is not enough. Ask once for a specific
45
+ question.
41
46
 
42
47
  ## 2. Pick the branch
43
48
 
44
- Read the user's prompt + the surrounding code. Two branches:
49
+ Read the user's prompt and surrounding code, then choose one branch:
45
50
 
46
51
  | Question shape | Branch | Artifact |
47
52
  |---|---|---|
@@ -51,50 +56,48 @@ Read the user's prompt + the surrounding code. Two branches:
51
56
  If genuinely ambiguous and the user is AFK: pick by the surrounding code (backend module
52
57
  → Logic; page / component → UI) and state the assumption in a comment at the top.
53
58
 
54
- **Variations must differ in shape.** UI prototypes where the variations are just colour
55
- or padding tweaks teach nothing: push each variation to a different *information
56
- architecture* / *interaction model* so the user can pick a direction, not a polish.
59
+ **Variations must differ in structure.** Colour or padding changes alone do not answer
60
+ a design question. Give each variation a different information architecture or
61
+ interaction model.
57
62
 
58
63
  ## 3. Rules that apply to both branches
59
64
 
60
- 1. **Throwaway from day one, and visibly so.** Place the prototype next to where it
61
- will eventually be used (so context is obvious) but name it so a casual reader sees
62
- it's a prototype: `prototype/`, `__prototype__`, `.scratch/`, etc. Obey the project's
65
+ 1. **Mark it as throwaway.** Place the prototype near its eventual use, but use a name
66
+ that clearly identifies it: `prototype/`, `__prototype__`, `.scratch/`, etc. Obey the project's
63
67
  existing routing / module convention; don't invent a new top-level structure.
64
- 2. **One command to run.** Use whatever task runner the project already has: `pnpm
65
- <name>`, `python <path>`, `bun <path>`. The user must start it without thinking.
68
+ 2. **Provide one run command.** Use the project's existing task runner: `pnpm
69
+ <name>`, `python <path>`, or `bun <path>`.
66
70
  3. **No persistence by default.** State lives in memory. Persistence is usually the
67
71
  thing the prototype is *checking*, not a dependency. If the question explicitly
68
72
  involves a DB, hit a scratch DB or a local file with a name like
69
73
  `PROTOTYPE — wipe me`.
70
- 4. **Skip the polish.** No tests. No error handling beyond what makes it run. No
71
- abstractions. The point is learn fast, delete fast.
74
+ 4. **Skip polish.** Add no tests, abstractions, or error handling beyond what is needed
75
+ to run and answer the question.
72
76
  5. **Surface state.** After every action (Logic) or on every variant switch (UI), print
73
77
  or render the full relevant state so the user can see what changed.
74
- 6. **Delete or absorb when done.** When the question has an answer, either delete the
75
- prototype or fold the validated decision into the real code: don't leave it
76
- rotting in the repo.
78
+ 6. **Delete or absorb when done.** After answering the question, delete the prototype
79
+ or fold the validated decision into production code.
77
80
 
78
81
  ## 4. Capture the answer
79
82
 
80
- The *answer* is the only durable output. Before declaring the prototype done, write
83
+ The answer is the only durable output. Before declaring the prototype done, write
81
84
  one of:
82
85
 
83
86
  - An entry in the active feature's `decisions.md` (`.devrites/work/<slug>/decisions.md`)
84
87
  with the question and the answer.
85
88
  - A `NOTES.md` next to the prototype if no active feature exists.
86
89
 
87
- If the user is around, this is a quick conversation. If they're AFK, the prototype is
88
- complete only once the verdict is filled in: a blank `VERDICT: ___` is not an
89
- answer. Leave it marked **not yet complete** and queue the open question so a later pass
90
- fills the verdict before the prototype is deleted.
90
+ If the user is present, ask for the verdict directly. In AFK, the prototype remains
91
+ incomplete until the verdict is filled in. A blank `VERDICT: ___` is not an answer.
92
+ Mark it **not yet complete**. Queue the question and do not delete the prototype until
93
+ a later pass records the verdict.
91
94
 
92
95
  ## Where this slots in
93
96
 
94
- `$rite-prototype` is a **scoped detour**, not a phase of its own. Typical placements:
97
+ `$rite-prototype` is a scoped detour, not a separate phase. Typical uses:
95
98
 
96
- - **Between `$rite-spec` and `$rite-define`:** a design question is undecidable on
97
- paper; prototype it, capture the answer, return to `$rite-define`.
99
+ - **During `$rite-clarify` (between spec and define):** a product/constraint question is
100
+ undecidable on paper; prototype it, capture the answer, return to `$rite-clarify`.
98
101
  - **Mid-build:** `$rite-build` hit a state-model ambiguity that the spec doesn't
99
102
  resolve. Drop into a Logic prototype, capture the answer, return.
100
103
 
@@ -11,19 +11,23 @@ This is the Codex mirror of a DevRites skill. In Codex:
11
11
 
12
12
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
13
13
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
14
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
15
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
16
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
14
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
15
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
16
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
17
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
18
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
19
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
20
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
17
21
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
18
22
 
19
23
 
20
24
  # $rite-prove: prove the completed feature
21
25
 
22
- Turn "I think it works" into recorded evidence for the **whole feature**. Read the active
23
- workspace first; if none, run `$rite-spec <feature>`.
26
+ Record evidence for the **whole feature**. Read the active workspace first; if none,
27
+ run `$rite-spec <feature>`.
24
28
 
25
- > **Differs from built-in `/verify` and `/run`:** those prove a single change /
26
- > launch the app. `$rite-prove` is feature-scoped. It walks `spec.md` acceptance
29
+ > **Scope:** built-in `/verify` proves one change and `/run` launches the app.
30
+ > `$rite-prove` covers a feature. It walks `spec.md` acceptance
27
31
  > criteria one-by-one, runs the full relevant test suite + build/typecheck/lint,
28
32
  > ascends the browser-proof ladder (step 4),
29
33
  > and writes `evidence.md` + `browser-evidence.md` keyed to the active
@@ -33,12 +37,13 @@ workspace first; if none, run `$rite-spec <feature>`.
33
37
  Read `tasks.md` + `state.md`. **If ANY slice is still pending/unbuilt, STOP** and tell the
34
38
  user to finish it with `$rite-build`: `$rite-prove` runs once, when the full task is
35
39
  complete, not after each slice. (Each slice already got its own targeted tests during
36
- `$rite-build`; this phase is the comprehensive proof of the assembled feature.)
40
+ `$rite-build`; this phase proves the assembled feature as a whole.)
37
41
 
38
- **Never report a pass you didn't observe.** If a command couldn't run, say so and give exact manual steps.
42
+ **Never report an unobserved pass.** If a command could not run, report that and give
43
+ exact manual steps.
39
44
 
40
- **Re-runnable, scoped.** `$rite-prove` runs once when the full feature is assembled, but
41
- it can be **re-run scoped** afterwards: when `$rite-polish` or `$rite-review` edit code,
45
+ **Scoped reruns are allowed.** `$rite-prove` runs once when the full feature is assembled.
46
+ After `$rite-polish` or `$rite-review` edits code,
42
47
  the existing `evidence.md` no longer post-dates the change, so re-run `$rite-prove` over
43
48
  the affected criteria/routes to refresh proof before `$rite-seal`.
44
49
 
@@ -54,7 +59,7 @@ Pull these via `Read` when relevant:
54
59
  user flow): telemetry must be present **and observed to emit**, not assumed.
55
60
  - `developer-experience.md`: when the change ships a developer-facing surface (API / CLI / SDK /
56
61
  webhook / config / error messages / getting-started): **measure** the DX scorecard (run the flow,
57
- time time-to-hello-world, capture the verbatim error text), don't assert it.
62
+ measure time-to-hello-world, and capture verbatim error text), rather than asserting it.
58
63
  - `definition-of-done.md`: standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
59
64
 
60
65
 
@@ -63,6 +68,10 @@ Pull these via `Read` when relevant:
63
68
  blocker; don't refactor unrelated code.
64
69
  - Spec Drift Guard applies: if tests/evidence reveal the spec is wrong, stop and handle
65
70
  drift (`rite-build/reference/spec-drift-guard.md`).
71
+ - **Runner observes; root records; wright fixes.** Use the file-backed fresh-context
72
+ contract in [`agents.md`](../devrites-lib/reference/standards/agents.md). The root owns
73
+ the evidence verdict and canonical writes. Every accepted source/test correction is one
74
+ bounded `devrites-slice-wright` packet, never an inline edit.
66
75
 
67
76
  ## Workflow
68
77
  0. Read `.agents/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules); pull the
@@ -75,23 +84,28 @@ Pull these via `Read` when relevant:
75
84
  [test-command-discovery](reference/test-command-discovery.md): README, package
76
85
  scripts, Makefile, CI configs, Gemfile/Rakefile, pyproject, go.mod, Cargo.toml.
77
86
  **Completion:** exact runnable test/build/typecheck/lint commands are recorded or explicitly unavailable.
78
- 3. **Run the full relevant test suite** for the feature (not a single slice), then the
79
- relevant **build / typecheck / lint**.
80
- 4. **UI feature?** Read `design-brief.md` + `references.md`, then run the browser proof ladder over the feature's routes:
87
+ 3. **Run proof in fresh context.** Freeze the candidate and dispatch
88
+ `devrites-proof-runner` with the exact commands, cwd, prerequisites, acceptance map,
89
+ and scratch boundary. Await and validate its observed full relevant test suite plus
90
+ **build / typecheck / lint** report. The runner writes no canonical evidence.
91
+ 4. **UI feature?** Include `design-brief.md`, `references.md`, routes, browser harness, and
92
+ allowed scratch path in the proof packet, then have the runner apply the browser proof ladder:
81
93
  [proof-ladder](reference/proof-ladder.md) + [browser-proof](reference/browser-proof.md)
82
94
  (`devrites-browser-proof`): routes, viewports, screenshots (opened + described),
83
95
  console, network, interaction paths, and the brief's proof targets. Compare screenshots
84
- with target references, record deltas, fix/re-render, and do not pass with an unresolved
85
- material mismatch.
96
+ with target references and record deltas. An unresolved material mismatch is a failed
97
+ result; the root handles any accepted correction at step 6 before re-rendering.
86
98
  5. **Map proof completely.** Follow
87
99
  [`reference/acceptance-proof.md`](reference/acceptance-proof.md) for acceptance/scenario
88
100
  coverage and the conditional critical-path, observability, developer-surface, and wiring
89
101
  branches. Completion: every criterion, planned interaction, and declared key link has a
90
102
  proof class plus passing evidence, or is recorded as a blocker.
91
103
  6. **On failure** → [failure-triage](reference/failure-triage.md) +
92
- `devrites-debug-recovery`. Reproduce isolate fix within scope → re-run; if a fix
93
- would exceed scope, record a blocker.
94
- 7. Update `evidence.md`, `browser-evidence.md` (if UI), `traceability.md`, and
104
+ `devrites-debug-recovery`. The root reconciles the reproduction. Send an accepted,
105
+ in-scope correction to the sole writer, `devrites-slice-wright`; then freeze the new
106
+ candidate and dispatch a fresh proof runner for affected checks. If a fix would exceed
107
+ scope, record a blocker.
108
+ 7. The root updates `evidence.md`, `browser-evidence.md` (if UI), `traceability.md`, and
95
109
  `state.md`. New proof goes to `evidence.md` (`proof.md` is a read-only alias:
96
110
  see `devrites-lib/reference/workspace-artifact-schema.md`).
97
111
 
@@ -11,9 +11,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
11
11
 
12
12
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
13
13
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
14
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
15
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
16
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
14
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
15
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
16
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
17
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
18
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
19
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
20
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
17
21
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
18
22
 
19
23
 
@@ -12,24 +12,28 @@ This is the Codex mirror of a DevRites skill. In Codex:
12
12
 
13
13
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
14
14
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
15
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
16
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
17
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
15
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
16
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
17
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
18
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
19
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
20
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
21
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
18
22
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
19
23
 
20
24
 
21
25
  # $rite-resolve: answer the human gate
22
26
 
23
- `$rite-resolve` is the canonical resume verb for **async** human gates: a checkpoint that
24
- already paused and **stopped the session** (an AFK blocking/escalating/irreversible queue, or a
25
- HITL pause the human walked away from), plus `--batch`. When `$rite-build` asks a gap **inline**
27
+ `$rite-resolve` resumes an **async** human gate: a checkpoint that already paused and
28
+ **stopped the session** (an AFK blocking/escalating/irreversible queue, or a HITL pause
29
+ left unanswered), plus `--batch`. When `$rite-build` asks a question **inline**
26
30
  via `AskUserQuestion` and the human is present, that pick resolves the gate **in place** through
27
31
  the same `devrites-engine resolve` writer. You don't type `$rite-resolve` for it. For the async case this
28
32
  skill takes the human's answer (or `--drop` / `--batch`), writes it to `questions.md`, updates
29
33
  `state.md` (clears `Awaiting human`, sets `Status: running`), and recommends the next command.
30
34
 
31
- It is **deliberately small**: one verb, one source of truth (`questions.md`), one cursor
32
- (`state.md`). The full AFK / HITL contract lives in
35
+ It has one verb, one source of truth (`questions.md`), and one cursor (`state.md`). The
36
+ full AFK / HITL contract lives in
33
37
  [`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md).
34
38
 
35
39
  ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
@@ -57,9 +61,9 @@ Pull these via `Read` when shaping the resolve:
57
61
  unblocked slice's `Slice mode` (step 4, the named exception); everything else goes through
58
62
  the script, never by hand.
59
63
  - **Human gates are for human-only decisions, not the agent's work.** A `questions.md` entry the
60
- human must answer is a genuine *decision* (a scope / design / risk call only the human can make).
61
- Not a task the agent can do itself. If a question is really agent-doable ("should I write the
62
- test?", "go implement X"), don't record a human answer that punts the agent's own job back to it:
64
+ human must answer is a genuine decision (a scope / design / risk call only the human can make),
65
+ not a task the agent can do. If a question is really agent-doable ("should I write the
66
+ test?", "go implement X"), do not record a human answer that returns the agent's work to it:
63
67
  flag the mis-tag and route it to the right skill (`$rite-build`, `$rite-plan unblock`,
64
68
  `devrites-debug-recovery`). The human resolves decisions; the agent does the work.
65
69
 
@@ -79,9 +83,10 @@ Pull these via `Read` when shaping the resolve:
79
83
  `tasks.md`. Confirm the qid is `status: open`. If `state.md` `Status` is not
80
84
  `awaiting_human` and the question's `gate` is `blocking`, surface the inconsistency
81
85
  before proceeding (don't auto-repair: flag it).
82
- 3. **Render preview.** Echo the qid, the question, the proposed answer (if any), the
83
- user's answer, and which slice unblocks. Stop here and ask `confirm? (y/N)` **unless**
84
- the answer was provided non-interactively via `--batch`.
86
+ 3. **Apply explicit consent.** Supplying `<qid> "<answer>"`, `--drop`, or `--batch` is the
87
+ user's explicit consent for this local workspace mutation. Echo the qid, answer/drop,
88
+ and slice being unblocked, then continue immediately; do not ask the user to confirm the
89
+ command they just typed.
85
90
  4. **Mutate.** Run `devrites-engine resolve` with the same
86
91
  arguments. The script:
87
92
  - flips the qid's `status` to `answered` / `dropped` and stamps `answered_at` + `answer`;
@@ -6,6 +6,9 @@ shapes, the batch file format, and the rules the underlying `devrites-engine res
6
6
 
7
7
  ## Three input shapes
8
8
 
9
+ Each form is an explicit local mutation command. Supplying it is the confirmation; the
10
+ skill applies it once after validation and reports the result instead of asking for `y` again.
11
+
9
12
  ### 1. Single answer
10
13
 
11
14
  ```
@@ -11,21 +11,25 @@ This is the Codex mirror of a DevRites skill. In Codex:
11
11
 
12
12
  - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
13
13
  - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
14
- - When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
15
- - The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
16
- - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
14
+ - **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
15
+ - For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
16
+ - If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
17
+ - Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
18
+ - If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
19
+ - Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
20
+ - Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
17
21
  - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
18
22
 
19
23
 
20
24
  # $rite-review: feature-scoped review
21
25
 
22
- Senior review of the **active feature scope only**. **Read the active workspace first**;
23
- if none, tell the user to run `$rite-spec <feature>`.
26
+ Review the **active feature scope only**. **Read the active workspace first**; if none,
27
+ tell the user to run `$rite-spec <feature>`.
24
28
 
25
- > **Differs from built-in `/code-review` in:** `/code-review` is a generic
26
- > diff review with no workspace context. `$rite-review` reads
29
+ > **Scope:** `/code-review` is a generic diff review with no workspace context.
30
+ > `$rite-review` reads
27
31
  > `.devrites/work/<slug>/spec.md` first, runs Spec ↔ Code-review axes as
28
- > parallel subagents (see [`parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md)), and gates feeding
32
+ > parallel fresh-context reviewers (see [`parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md)), and gates feeding
29
33
  > into `$rite-seal`. Use `/code-review` for a one-off diff; use
30
34
  > `$rite-review` for a DevRites feature where the spec is the contract.
31
35
 
@@ -34,7 +38,7 @@ Pull these via `Read` when the diff demands them:
34
38
  - `code-review.md`: small PRs, severity labels, tests-first review focus.
35
39
  - `review-checklist.md`: compact pass/fail sweep before reporting the verdict.
36
40
  - `principles.md`: declared project invariants (`.devrites/principles.md`); a diff that violates one with no recorded exception is a Critical, blocking finding.
37
- - `testing.md`: confirm the tests prove the spec, not just pass.
41
+ - `testing.md`: confirm that passing tests actually prove the spec.
38
42
  - `agents.md`: when to fan out to which review subagent.
39
43
  - `security.md`: when input / auth / data / integrations / secrets are in scope.
40
44
  - `security-checklist.md`: for the same security-sensitive scope, the compact trust-boundary sweep.
@@ -44,10 +48,14 @@ Pull these via `Read` when the diff demands them:
44
48
  - **Feature scope only.** Review touched files + the diff. **NO whole-project refactors,
45
49
  NO drive-by cleanup.** DO NOT delete suspected dead code outside this feature without
46
50
  asking. Spec Drift Guard applies.
47
- - **Reviews the finished product.** `$rite-polish` has already done **code simplification**
48
- + UI normalize/polish. Review judges; if it reveals a real complexity issue polish
49
- missed, flag it as a finding: don't re-run a simplification sweep here.
50
- - Findings are labeled (below). Re-prove after any change you make.
51
+ - **Review the finished product.** `$rite-polish` has already simplified code and
52
+ normalized or polished UI. If review finds a remaining complexity issue, record it as
53
+ a finding rather than rerunning a simplification pass.
54
+ - Findings are labeled (below). Re-prove after any accepted correction.
55
+ - **Reviewers judge; root reconciles; wright fixes.** Follow
56
+ [`agents.md`](../devrites-lib/reference/standards/agents.md). The root owns the verdict and
57
+ canonical writes; every accepted source/test correction routes to
58
+ `devrites-slice-wright`.
51
59
 
52
60
  ## Workflow
53
61
  0. Read `.agents/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules); pull the
@@ -64,13 +72,14 @@ Pull these via `Read` when the diff demands them:
64
72
  2. **Review tests first:** do they prove the acceptance criteria? Missing,
65
73
  weak, or wrong tests are the first findings.
66
74
  **Completion:** every acceptance criterion maps to a proven test or a labeled finding.
67
- 3. **Spec Code-review split (parallel sub-agents, fresh context).** A change can pass
75
+ 3. **Review spec and code separately in parallel.** A change can pass
68
76
  one axis and fail the other: code that follows every project standard but
69
77
  implements the wrong thing (Code-review pass, Spec fail), or code that does exactly
70
78
  what the spec asked but breaks project conventions (Spec pass, Code-review fail).
71
- Running them serially in one context lets one mask the other. So:
72
- - Dispatch **two** read-only reviewers in **parallel** via the `Task` tool, each
73
- with its own narrow brief and no cross-pollination:
79
+ Separate contexts prevent one axis from masking the other:
80
+ - Freeze the candidate and fresh-context dispatch **two** read-only reviewers in
81
+ parallel, each with its own `agent-packet/v1`, narrow brief, and no
82
+ cross-pollination:
74
83
  - **Spec axis** → `devrites-spec-reviewer`: "Apply your documented discipline on
75
84
  the active feature workspace + diff. Report (a) criteria the spec asked for that
76
85
  are missing or partial, (b) behaviour in the diff the spec did not ask for
@@ -113,15 +122,20 @@ Pull these via `Read` when the diff demands them:
113
122
  6. **Performance:** apply `devrites-audit perf`
114
123
  ([performance-review](reference/performance-review.md)) only when performance is
115
124
  relevant or a regression risk is visible (measure first).
116
- 7. Apply only in-scope fixes; **run verification after changes** (`$rite-prove` logic).
117
- 8. Update `review.md`, `evidence.md`, and `state.md`.
118
- 9. **Guard against the silent reviewer.** After `review.md` is written, run:
125
+ 7. Reconcile and accept only in-scope fixes. Consolidate them into one bounded wright
126
+ correction packet; never edit source in the reviewing context. Freeze the new candidate
127
+ and **run affected verification after changes** (`$rite-prove` logic), then perform at
128
+ most one narrow recheck of affected findings.
129
+ 8. The root updates `review.md`, `evidence.md`, and `state.md`.
130
+ **Completion:** the records name the reviewed candidate identity and every accepted
131
+ correction has affected proof plus its narrow recheck.
132
+ 9. **Require an account from every reviewer.** After `review.md` is written, run:
119
133
  ```bash
120
134
  devrites-engine review-integrity
121
135
  devrites-engine review-fingerprints --write
122
136
  ```
123
- Exit 1 means an adversarial axis reported nothing and justified nothing: a suspected
124
- rubber-stamp. Re-run that axis or add its `No-findings:` justification; do not carry a silent
137
+ Exit 1 means an adversarial axis reported neither findings nor a justification. Re-run
138
+ that axis or add its `No-findings:` justification; do not carry a silent
125
139
  axis into `$rite-seal` (where it surfaces as an Important).
126
140
 
127
141
  ## Finding labels
@@ -131,13 +145,13 @@ Pull these via `Read` when the diff demands them:
131
145
  - **Nit:** trivial/style.
132
146
  - **FYI:** context, no action implied.
133
147
 
134
- **Action decoration (orthogonal to severity).** Also tag each finding with how to act on it:
148
+ **Action tag (separate from severity).** Tag each finding with how to act on it:
135
149
  `blocking` (fix before seal), `non-blocking` (fix when convenient), or `if-minor` (fix only if the
136
150
  change is already small: a pure noise-economics lever). Only a **`blocking` Critical** gates the
137
151
  seal; a `non-blocking` / `if-minor` finding is recorded, not a stop.
138
152
 
139
- ## Confidence + signal-to-noise
140
- Borrow `$rite-vet`'s discipline so review stays **trusted, not noisy**: a reviewer that posts
153
+ ## Confidence and signal-to-noise
154
+ Apply `$rite-vet`'s confidence rules. A reviewer that posts
141
155
  18 comments per PR teaches the team to ignore every one (below ~10% false-positive rate devs
142
156
  investigate each finding; past ~30% they label the tool noisy and skip it):
143
157
  - **Confidence-band each finding** (1-10) and state the band. A low-confidence finding (≤4)
@@ -145,21 +159,20 @@ investigate each finding; past ~30% they label the tool noisy and skip it):
145
159
  (low-confidence): n` line, never raised as Critical/Important.
146
160
  - **Verify before you escalate.** Every Critical/Important quotes the spec line or cites the
147
161
  `file:line` that proves it: no unverified blockers.
148
- - **Budget the noise.** Roll up trivia ("N style nits") into a single line; tooling already
162
+ - **Limit low-value comments.** Roll up trivia ("N style nits") into a single line; tooling already
149
163
  catches style. Review's job is correctness + spec fidelity, not a lint dump.
150
164
  - **A silent axis is suspicious, not clean.** An adversarial axis that raises nothing must earn
151
165
  it: end its `## Spec` / `## Code review` section with a **`No-findings:`** line naming the
152
166
  passes it ran (missing/partial/incorrect for spec; edge cases, error paths, the riskiest
153
167
  decision, a changed behavior whose test may not cover it for code) and why each came back
154
- empty. This is the mirror of confidence-banding: banding kills the false positive, this catches
155
- the false negative ([`code-review.md` § Zero findings is suspicious](../devrites-lib/reference/standards/code-review.md)).
168
+ empty. Confidence bands suppress false positives; this requirement catches silent false
169
+ negatives ([`code-review.md` § Zero findings is suspicious](../devrites-lib/reference/standards/code-review.md)).
156
170
 
157
171
  ## Severity orientation (labels, not score)
158
172
 
159
173
  After labeling, summarize findings as `Critical / Important / Suggestion / Nit /
160
- FYI` counts. There is no composite number `$rite-seal` gates on
161
- `Critical == 0` and on acceptance + drift. Inventing a number invites gaming;
162
- the labels do the work.
174
+ FYI` counts. There is no composite number. `$rite-seal` gates on
175
+ `Critical == 0` and on acceptance plus drift. Do not invent a composite score.
163
176
 
164
177
  > **Mid-flight discipline.** When tempted to demote a Critical, hide a finding, fix without re-verification, or wander out of scope: see [`anti-patterns`](reference/anti-patterns.md). Load it the moment you reach for the excuse.
165
178