peaks-loop 4.1.4 → 4.1.5

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 (240) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +112 -0
  3. package/README-en.md +1 -1
  4. package/README.md +1 -1
  5. package/dist/cli/cli-helpers.d.ts +20 -0
  6. package/dist/cli/cli-helpers.js +34 -0
  7. package/dist/cli/commands/_register.js +2 -0
  8. package/dist/cli/commands/code-commands.d.ts +6 -4
  9. package/dist/cli/commands/code-commands.js +6 -4
  10. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  11. package/dist/cli/commands/code-gate-command.js +49 -9
  12. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  13. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  14. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  15. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  16. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  17. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  18. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  19. package/dist/cli/commands/dispatch-commands.js +12 -5
  20. package/dist/cli/commands/dispatch-preflight.js +46 -0
  21. package/dist/cli/commands/dispatch-prompt-composition.d.ts +6 -0
  22. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  23. package/dist/cli/commands/doc-commands.js +1 -1
  24. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  25. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  26. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  27. package/dist/cli/commands/hook-handle.js +41 -20
  28. package/dist/cli/commands/lint-commands.js +3 -1
  29. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  30. package/dist/cli/commands/perf-audit-commands.js +15 -5
  31. package/dist/cli/commands/project-commands.js +9 -6
  32. package/dist/cli/commands/race-commands.d.ts +15 -0
  33. package/dist/cli/commands/race-commands.js +65 -0
  34. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  35. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  36. package/dist/cli/commands/request-command-options.d.ts +8 -0
  37. package/dist/cli/commands/request-commands.js +2 -0
  38. package/dist/cli/commands/request-init-command.js +67 -12
  39. package/dist/cli/commands/request-retag-command.d.ts +3 -0
  40. package/dist/cli/commands/request-retag-command.js +50 -0
  41. package/dist/cli/commands/request-show-command.d.ts +8 -0
  42. package/dist/cli/commands/request-show-command.js +14 -1
  43. package/dist/cli/commands/request-transition-command.js +12 -4
  44. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  45. package/dist/cli/commands/request-transition-failures.js +45 -3
  46. package/dist/cli/commands/scan-scope-commands.js +2 -2
  47. package/dist/cli/commands/security-audit-commands.js +26 -6
  48. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  49. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  50. package/dist/services/artifacts/artifact-contract-block.js +212 -0
  51. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  52. package/dist/services/artifacts/artifact-prerequisites.js +63 -133
  53. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  54. package/dist/services/artifacts/artifact-templates.js +17 -10
  55. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  56. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  57. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  58. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  59. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  60. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  61. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  62. package/dist/services/artifacts/request-artifact-service.js +23 -51
  63. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +12 -0
  64. package/dist/services/artifacts/request-artifact-state-helpers.js +28 -4
  65. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  66. package/dist/services/artifacts/request-retag-service.js +125 -0
  67. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  68. package/dist/services/artifacts/request-state-order.js +99 -0
  69. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  70. package/dist/services/artifacts/request-type-demand.js +71 -0
  71. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  72. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  73. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  74. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  75. package/dist/services/audit/enforcers/code-ban.js +21 -1
  76. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  77. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  78. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  79. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  80. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  81. package/dist/services/audit-independent/handoff-readers.js +81 -0
  82. package/dist/services/audit-independent/index.d.ts +6 -1
  83. package/dist/services/audit-independent/index.js +6 -1
  84. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  85. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  86. package/dist/services/audit-independent/judged-declaration-check.d.ts +79 -0
  87. package/dist/services/audit-independent/judged-declaration-check.js +155 -0
  88. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  89. package/dist/services/audit-independent/judged-declaration.js +218 -0
  90. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  91. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  92. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  93. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  94. package/dist/services/audit-independent/security-audit-service.js +34 -178
  95. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  96. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  97. package/dist/services/context/build-dispatch-system-prompt.d.ts +3 -3
  98. package/dist/services/context/build-dispatch-system-prompt.js +7 -7
  99. package/dist/services/context/collector.js +5 -1
  100. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  101. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  102. package/dist/services/dispatch/batch-counter.js +1 -2
  103. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  104. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  105. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  106. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  107. package/dist/services/dispatch/karpathy-block.js +101 -0
  108. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  109. package/dist/services/dispatch/ledger-reaper.js +131 -0
  110. package/dist/services/evidence/evidence-generator.js +15 -8
  111. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  112. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  113. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  114. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  115. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  116. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  117. package/dist/services/final-review/final-review-contract.js +64 -0
  118. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  119. package/dist/services/final-review/final-review-delivery.js +26 -12
  120. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  121. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  122. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  123. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  124. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  125. package/dist/services/final-review/final-review-prompt.js +19 -6
  126. package/dist/services/final-review/final-review-runner.js +5 -0
  127. package/dist/services/final-review/final-review-service.d.ts +2 -2
  128. package/dist/services/final-review/index.d.ts +1 -1
  129. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  130. package/dist/services/final-review/pre-post-diff.js +60 -59
  131. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  132. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  133. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  134. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  135. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  136. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  137. package/dist/services/lint/eslint-runner-support.js +2 -1
  138. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  139. package/dist/services/lint/eslint-runner.js +17 -4
  140. package/dist/services/llm/anthropic-runner.js +24 -7
  141. package/dist/services/loop/loop-observability.d.ts +39 -0
  142. package/dist/services/loop/loop-observability.js +55 -0
  143. package/dist/services/loop/monotonic-guard.js +6 -9
  144. package/dist/services/loop/monotonic-runner.js +8 -7
  145. package/dist/services/loop/run-driver.js +18 -22
  146. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  147. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  148. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  149. package/dist/services/memory/project-memory-service/index.js +1 -1
  150. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  151. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  152. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  153. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  154. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  155. package/dist/services/observability/observability-service.d.ts +7 -0
  156. package/dist/services/observability/observability-service.js +2 -1
  157. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  158. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  159. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  160. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  161. package/dist/services/race/gate2-evaluator.js +111 -0
  162. package/dist/services/race/gate2-policy.d.ts +17 -0
  163. package/dist/services/race/gate2-policy.js +31 -0
  164. package/dist/services/race/lane-phase.d.ts +19 -0
  165. package/dist/services/race/lane-phase.js +113 -0
  166. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  167. package/dist/services/race/pilot-gate-store.js +227 -0
  168. package/dist/services/scan/file-size-baseline.d.ts +26 -0
  169. package/dist/services/scan/file-size-baseline.js +150 -0
  170. package/dist/services/scan/file-size-scan.d.ts +42 -3
  171. package/dist/services/scan/file-size-scan.js +58 -42
  172. package/dist/services/scan/type-sanity-service.js +13 -3
  173. package/dist/services/skill/resume-detector.js +3 -3
  174. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  175. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  176. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  177. package/dist/services/skills/hooks-settings-service.js +1 -1
  178. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  179. package/dist/services/skills/presence-lease-order.js +24 -0
  180. package/dist/services/skills/skill-conformance-service.js +1 -0
  181. package/dist/services/skills/skill-statusline-service.js +4 -7
  182. package/dist/services/slice/slice-check-service.js +8 -8
  183. package/dist/services/workflow/pipeline-verify-gate-support.js +2 -1
  184. package/dist/services/workflow/pipeline-verify-service.js +1 -1
  185. package/dist/services/workflow/workflow-skip-service.d.ts +0 -20
  186. package/dist/services/workflow/workflow-skip-service.js +3 -4
  187. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  188. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  189. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  190. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  191. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  192. package/dist/services/workspace/claude-settings-template.js +58 -58
  193. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  194. package/dist/services/workspace/reconcile-service.js +0 -1
  195. package/dist/shared/incrementing-number.d.ts +10 -0
  196. package/dist/shared/incrementing-number.js +27 -0
  197. package/package.json +5 -5
  198. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  199. package/skills/bee/peaks-prd/SKILL.md +1 -1
  200. package/skills/bee/peaks-qa/SKILL.md +1 -1
  201. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  202. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  203. package/skills/bee/peaks-rd/SKILL.md +2 -2
  204. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  205. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  206. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  207. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  208. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  209. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  210. package/skills/bee/peaks-sc/SKILL.md +1 -1
  211. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  212. package/skills/bee/peaks-txt/SKILL.md +4 -3
  213. package/skills/bee/peaks-ui/SKILL.md +3 -3
  214. package/skills/peaks-audit/SKILL.md +29 -1
  215. package/skills/peaks-code/SKILL.md +5 -2
  216. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  217. package/skills/peaks-code/references/fast-mode.md +3 -2
  218. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  219. package/skills/peaks-code/references/micro-cycle.md +3 -3
  220. package/skills/peaks-code/references/resume-detection.md +1 -1
  221. package/skills/peaks-code/references/runbook.md +12 -6
  222. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  223. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  224. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  225. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  226. package/skills/peaks-code/references/worktree-governance.md +4 -4
  227. package/skills/peaks-content/SKILL.md +1 -1
  228. package/skills/peaks-doctor/SKILL.md +1 -1
  229. package/skills/peaks-final-review/SKILL.md +31 -11
  230. package/skills/peaks-ide/SKILL.md +1 -1
  231. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  232. package/skills/peaks-race-code/SKILL.md +185 -0
  233. package/skills/peaks-resume/SKILL.md +1 -1
  234. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  235. package/skills/peaks-solo/SKILL.md +1 -1
  236. package/skills/peaks-sop/SKILL.md +1 -1
  237. package/skills/peaks-status/SKILL.md +1 -1
  238. package/skills/peaks-test/SKILL.md +7 -4
  239. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  240. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
@@ -21,6 +21,19 @@ function buildShowPayload(result, options) {
21
21
  const transformed = applyPerArtifactFormat(result, override ?? format);
22
22
  return transformed === result ? { ...result, format } : transformed;
23
23
  }
24
+ /**
25
+ * The type a `request show` reports is the EFFECTIVE one: an artifact that
26
+ * records no type still reads as `feature`, and a reader who cannot tell that
27
+ * from a chosen `feature` cannot tell which prerequisite table the next gate
28
+ * will apply. The field says which; this line says it in words.
29
+ */
30
+ export function typeProvenanceWarning(result) {
31
+ if (result.requestTypeSource !== 'default')
32
+ return [];
33
+ return [
34
+ `request type '${result.requestType}' is the DEFAULT — this artifact records no type, so the '${result.requestType}' prerequisite table applies. Set one with: peaks request retag <request-id> --role ${result.role} --type <type> --project <path>`
35
+ ];
36
+ }
24
37
  async function runRequestShow(requestId, options, io) {
25
38
  try {
26
39
  const showOptions = {
@@ -36,7 +49,7 @@ async function runRequestShow(requestId, options, io) {
36
49
  failShowNotFound(io, options, requestId);
37
50
  return;
38
51
  }
39
- printResult(io, ok('request.show', buildShowPayload(result, options)), options.json);
52
+ printResult(io, ok('request.show', buildShowPayload(result, options), typeProvenanceWarning(result)), options.json);
40
53
  }
41
54
  catch (error) {
42
55
  printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);
@@ -1,9 +1,9 @@
1
1
  import { transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
2
2
  import { parseRole, parseStateForRole, VALID_ROLES } from './request-format-helpers.js';
3
3
  import { fail, ok } from 'peaks-loop-shared/result';
4
- import { addJsonOption, printResult } from '../cli-helpers.js';
4
+ import { addJsonOption, printableWarningText, printResult } from '../cli-helpers.js';
5
5
  import { runTransitionPreflight } from './request-transition-preflight.js';
6
- import { reportTransitionFailure } from './request-transition-failures.js';
6
+ import { reportTransitionFailure, softWarningExpiryClause } from './request-transition-failures.js';
7
7
  import { buildPrdHandoffResult, collectQaHandoffHooks, preCompactNote } from './request-transition-hooks.js';
8
8
  const TRANSITION_DESCRIPTION = 'Move a per-request artifact to a new state defined by its role state machine';
9
9
  const TRANSITION_REQUEST_ID_HELP = 'request id, e.g. 2026-05-23-add-foo';
@@ -11,7 +11,7 @@ const TRANSITION_STATE_HELP = 'new state name; allowed values depend on role';
11
11
  const TRANSITION_PROJECT_HELP = 'target project root';
12
12
  const TRANSITION_SESSION_HELP = 'restrict to a specific session id';
13
13
  const TRANSITION_REASON_HELP = 'reason appended as a transition note; required when --allow-incomplete is set';
14
- const TRANSITION_ALLOW_INCOMPLETE_HELP = 'bypass artifact prerequisite checks; requires --reason and records the bypass in the artifact';
14
+ const TRANSITION_ALLOW_INCOMPLETE_HELP = 'bypass the prerequisite, lint, file-size and state-order checks; requires --reason and records the bypass in the artifact';
15
15
  const TRANSITION_CONFIRM_HELP = 'skip the confirmation gate (for non-interactive / LLM contexts)';
16
16
  const TRANSITION_FORCE_CONFIRM_HELP = 'bypass mode-enforced confirmation (use with caution)';
17
17
  function buildTransitionOptions(requestId, role, newState, options) {
@@ -71,7 +71,15 @@ function printTransitionResult(io, options, result, hooks) {
71
71
  codegraphRefresh: hooks.codegraphRefresh
72
72
  }, [
73
73
  ...(note === null ? [] : [note]),
74
- ...(hooks.codegraphWarning === null ? [] : [hooks.codegraphWarning])
74
+ ...(hooks.codegraphWarning === null ? [] : [hooks.codegraphWarning]),
75
+ // A soft-passed prerequisite is a warning, not a silent pass: the
76
+ // envelope carries it (and `printResult` puts it on stderr for a human
77
+ // run). `data.prerequisiteWarnings` holds the structured entries.
78
+ // `softWarningExpiryClause` adds the one thing the entry cannot say
79
+ // without `message` moving: whether the window it names has closed.
80
+ ...(result.prerequisiteWarnings ?? []).map((warning) => `Soft prerequisite (not enforced): ${printableWarningText(warning.path)} ` +
81
+ `[${printableWarningText(warning.code)}] — ${printableWarningText(warning.message)}` +
82
+ softWarningExpiryClause(warning))
75
83
  ]), options.json);
76
84
  }
77
85
  async function runRequestTransition(requestId, options, io) {
@@ -1,5 +1,19 @@
1
1
  import { type ProgramIO } from '../cli-helpers.js';
2
2
  import type { RequestTransitionOptions } from './request-command-options.js';
3
+ /**
4
+ * The clause a soft-pass warning gains once its back-compat window has closed.
5
+ * It renders the `expiredWindow` the resolver set (the release the table
6
+ * declared, plus the build it was compared against) and is empty while the
7
+ * window is open — an open window is already the future tense the warning's own
8
+ * message uses, so it needs no clause.
9
+ *
10
+ * Shared with `printTransitionResult` in `request-transition-command.ts`: the
11
+ * success arm and this refusal arm render one fact one way, so an operator who
12
+ * sees the same soft pass through either arm reads the same sentence.
13
+ */
14
+ export declare function softWarningExpiryClause(warning: {
15
+ expiredWindow?: string;
16
+ }): string;
3
17
  /**
4
18
  * Map a thrown transition error to its envelope. `InvalidArgumentError` is
5
19
  * re-thrown: Commander raises it for an unparsable `--state`, and swallowing it
@@ -4,9 +4,26 @@
4
4
  // readable and every branch keeps setting `process.exitCode = 1`.
5
5
  import { InvalidArgumentError } from 'commander';
6
6
  import { PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError } from '../../services/artifacts/request-artifact-service.js';
7
+ import { StateOrderViolationError } from '../../services/artifacts/request-state-order.js';
7
8
  import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
8
9
  import { fail } from 'peaks-loop-shared/result';
9
- import { getErrorMessage, printResult } from '../cli-helpers.js';
10
+ import { getErrorMessage, printableWarningText, printResult } from '../cli-helpers.js';
11
+ /**
12
+ * The clause a soft-pass warning gains once its back-compat window has closed.
13
+ * It renders the `expiredWindow` the resolver set (the release the table
14
+ * declared, plus the build it was compared against) and is empty while the
15
+ * window is open — an open window is already the future tense the warning's own
16
+ * message uses, so it needs no clause.
17
+ *
18
+ * Shared with `printTransitionResult` in `request-transition-command.ts`: the
19
+ * success arm and this refusal arm render one fact one way, so an operator who
20
+ * sees the same soft pass through either arm reads the same sentence.
21
+ */
22
+ export function softWarningExpiryClause(warning) {
23
+ return warning.expiredWindow === undefined
24
+ ? ''
25
+ : ` — past expiry: ${printableWarningText(warning.expiredWindow)}`;
26
+ }
10
27
  function reportPrerequisitesFailure(io, options, error) {
11
28
  // The `warnings` list is surfaced inside the 1-minor-release back-compat
12
29
  // window (e.g. MUT_REPORT) so the operator sees both the hard-blocked
@@ -20,7 +37,11 @@ function reportPrerequisitesFailure(io, options, error) {
20
37
  warnings: error.warnings
21
38
  }, [
22
39
  ...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
23
- ...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${w.path} — ${w.message}`),
40
+ // Sanitised for the same reason the success branch sanitises: a
41
+ // `gateEvidence.<key>` warning can carry a control character decoded out
42
+ // of the handoff frontmatter, and `printResult` puts these on stderr.
43
+ ...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${printableWarningText(w.path)} — ` +
44
+ `${printableWarningText(w.message)}${softWarningExpiryClause(w)}`),
24
45
  'Once every required artifact exists, rerun this transition.',
25
46
  'For exceptional cases (docs-only / config-only change), bypass with: --allow-incomplete --reason "<justification>"'
26
47
  ]), options.json);
@@ -34,6 +55,21 @@ function reportLintGateFailure(io, options, error) {
34
55
  ]), options.json);
35
56
  process.exitCode = 1;
36
57
  }
58
+ function reportStateOrderFailure(io, options, error) {
59
+ printResult(io, fail('request.transition', error.code, error.message, {
60
+ role: error.role,
61
+ from: error.from,
62
+ newState: error.to,
63
+ skipped: error.skipped
64
+ }, [
65
+ error.kind === 'unreadable'
66
+ ? "Restore the artifact's '- state:' line: an unreadable state fails this gate closed"
67
+ : `Walk the states in order — from '${error.from}' the next legal state is ` +
68
+ `'${error.skipped[0] ?? error.to}'`,
69
+ 'Or bypass with: --allow-incomplete --reason "<justification>"'
70
+ ]), options.json);
71
+ process.exitCode = 1;
72
+ }
37
73
  function reportTypeSanityFailure(io, options, error) {
38
74
  printResult(io, fail('request.transition', error.code, error.message, {
39
75
  declaredType: error.declaredType,
@@ -47,7 +83,9 @@ function reportTypeSanityFailure(io, options, error) {
47
83
  }
48
84
  function reportFileSizeFailure(io, options, error) {
49
85
  printResult(io, fail('request.transition', error.code, error.message, { violations: error.violations }, [
50
- ...error.violations.map((v) => `Split ${v.file} (${v.lines} lines) below its ${v.cap}-line cap`),
86
+ ...error.violations.map((v) => v.previousLines === null
87
+ ? `Split ${v.file} (${v.lines} lines) below its ${v.cap}-line cap — this change created it over the cap`
88
+ : `Split ${v.file} back below its ${v.cap}-line cap, or at least down to the ${v.previousLines} lines it had at the base ref (grew +${v.lines - v.previousLines})`),
51
89
  'Or bypass with: --allow-incomplete --reason "<justification>"'
52
90
  ]), options.json);
53
91
  process.exitCode = 1;
@@ -73,6 +111,10 @@ export function reportTransitionFailure(io, options, requestId, error) {
73
111
  reportLintGateFailure(io, options, error);
74
112
  return;
75
113
  }
114
+ if (error instanceof StateOrderViolationError) {
115
+ reportStateOrderFailure(io, options, error);
116
+ return;
117
+ }
76
118
  if (error instanceof TypeSanityViolationError) {
77
119
  reportTypeSanityFailure(io, options, error);
78
120
  return;
@@ -16,7 +16,7 @@ import { acceptanceCoverageNextActions, diffVsScopeNextActions, printAcceptanceC
16
16
  const REQUEST_TYPE_SANITY_DESCRIPTION = 'Cross-verify a declared --type against the actual git diff file mix (catches "feature mis-declared as docs" workflow violations)';
17
17
  const ACCEPTANCE_COVERAGE_DESCRIPTION = 'Verify every PRD "Acceptance criteria" item has at least one linked QA test case (via `- **Acceptance:** A1, A2` field in qa/test-cases/<rid>.md)';
18
18
  const DIFF_VS_SCOPE_DESCRIPTION = 'Verify every file in the git diff matches the RD artifact "Red-line scope" patterns; flags out-of-scope writes and unclassified files';
19
- const FILE_SIZE_DESCRIPTION = 'Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First"; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)';
19
+ const FILE_SIZE_DESCRIPTION = 'Check git diff for files this change grew past the line-count cap, or created over it (karpathy-skills "Simplicity First"; a file already over cap at the base ref is accepted, as the gate baseline ratchets it; a rename is measured against its pre-rename size; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)';
20
20
  function runScanRequestTypeSanity(options, io) {
21
21
  try {
22
22
  const serviceOptions = {
@@ -108,7 +108,7 @@ function runScanFileSize(options, io) {
108
108
  });
109
109
  const nextActions = [];
110
110
  if (!result.ok) {
111
- nextActions.push(`${result.violations.length} file(s) exceed their file-size cap. Split into smaller modules.`);
111
+ nextActions.push(`${result.violations.length} file(s) exceed their file-size cap because this change grew them past it (or created them over it). Split into smaller modules.`);
112
112
  }
113
113
  printResult(io, ok('scan.file-size', result, [], nextActions), options.json);
114
114
  if (!result.ok) {
@@ -2,6 +2,14 @@ import { readFileSync } from 'node:fs';
2
2
  import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit } from '../../services/audit-independent/index.js';
3
3
  import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
4
4
  import { fail, ok } from 'peaks-loop-shared/result';
5
+ /**
6
+ * The judged paths as the service takes them. A call, not a `??` inside the
7
+ * action, because the action's branch budget is already at its cap and a second
8
+ * operator there is a `complexity` finding on the whole command.
9
+ */
10
+ function resolveJudgedPaths(judged) {
11
+ return judged ?? [];
12
+ }
5
13
  function resolveEnvelope(envelopePath) {
6
14
  if (envelopePath === undefined || envelopePath === '-') {
7
15
  // Read from stdin
@@ -19,9 +27,7 @@ function readStdinSync() {
19
27
  // Node 22: read stdin synchronously via fs.readFileSync(0, 'utf8').
20
28
  // We use the file descriptor 0 convention.
21
29
  try {
22
- // Lazy import to avoid pulling readline at module load
23
- const { readFileSync: rfs } = require('node:fs');
24
- const raw = rfs(0, 'utf8');
30
+ const raw = readFileSync(0, 'utf8');
25
31
  if (raw.trim().length === 0) {
26
32
  throw new Error('stdin was empty; expected JSON envelope on stdin or --envelope <path>');
27
33
  }
@@ -63,7 +69,14 @@ export function registerSecurityAuditCommands(program, io) {
63
69
  });
64
70
  const envelope = detect.state === 'ready'
65
71
  ? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
66
- : fail('security-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]);
72
+ : {
73
+ // `fail()` builds `warnings: []`, so the detector's own diagnosis is
74
+ // spread over it. Without this the human-readable refusal drops the
75
+ // sentence saying WHY the run is not ready, while `--json` keeps it
76
+ // at `data.detect.warnings` — the 9.2 shape, one surface over.
77
+ ...fail('security-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]),
78
+ warnings: [...detect.warnings]
79
+ };
67
80
  printResult(io, envelope, options.json);
68
81
  if (detect.state !== 'ready') {
69
82
  process.exitCode = 1;
@@ -86,7 +99,8 @@ export function registerSecurityAuditCommands(program, io) {
86
99
  .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
87
100
  .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
88
101
  .option('--project <path>', 'project root (default: cwd)')
89
- .option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')).action((options) => {
102
+ .option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')
103
+ .option('--judged <paths...>', 'project-relative paths this audit judged; written into the artifact as the declaration the rd:qa-handoff gate reads back. Not enforced by the parser: an empty or unhashable list is refused by the run itself, which exits 1 and writes nothing.')).action((options) => {
90
104
  const projectRoot = options.project ?? process.cwd();
91
105
  const sid = options.sid;
92
106
  const rid = options.rid;
@@ -115,10 +129,16 @@ export function registerSecurityAuditCommands(program, io) {
115
129
  sessionId: sid,
116
130
  rid,
117
131
  generatedAt: new Date().toISOString(),
132
+ judgedPaths: resolveJudgedPaths(options.judged),
118
133
  envelope: envelopeValue
119
134
  });
120
135
  if (result.detect.state !== 'ready' || result.artifactPath === null) {
121
- printResult(io, fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]), options.json);
136
+ printResult(io, {
137
+ // Same spread as the detect arm: the run's refusal is the only place
138
+ // the detector's warning would reach a person, and `fail()` empties it.
139
+ ...fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]),
140
+ warnings: [...result.detect.warnings]
141
+ }, options.json);
122
142
  process.exitCode = 1;
123
143
  return;
124
144
  }
@@ -66,7 +66,7 @@ function printGcOk(io, options, ctx) {
66
66
  dryRun
67
67
  ? `[dry-run] Would gc ${swept.length} lease(s); no filesystem changes were made.`
68
68
  : `Gc'd ${swept.length} lease(s).`,
69
- 'For per-lease detail, run `peaks worktree status --lease-id <id>`.'
69
+ 'For per-lease detail, run `peaks worktree lease-status --lease-id <id>`.'
70
70
  ]), options.json);
71
71
  }
72
72
  function printGcFailed(io, options, err, sessionId) {
@@ -0,0 +1,53 @@
1
+ import { type RequestType } from './artifact-prerequisites.js';
2
+ import { type RequestTypeSource } from './request-artifact-metadata.js';
3
+ /**
4
+ * The block, or `''` when this role has nothing gated to say under this type.
5
+ * The empty string is the whole byte-identity contract: callers concatenate it,
6
+ * and a role with no gated artifacts must add zero bytes to the prompt.
7
+ */
8
+ export declare function buildArtifactContractBlock(input: {
9
+ role: string;
10
+ requestType: RequestType;
11
+ requestTypeSource: RequestTypeSource;
12
+ requestId: string;
13
+ }): string;
14
+ /**
15
+ * Append the block unless the text already carries one.
16
+ *
17
+ * Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
18
+ * already hold a copy — a re-dispatch, or a resume from a stored prompt — and
19
+ * two sections can DISAGREE (the type may have been declared between the two
20
+ * runs), so a reader cannot tell which contract is authoritative. The presence
21
+ * test is the block's own heading, which nothing else emits.
22
+ *
23
+ * An empty block adds zero bytes even when the text already carries one, so an
24
+ * unaffected dispatch stays byte-identical.
25
+ */
26
+ export declare function ensureArtifactContractBlock(text: string, block: string): string;
27
+ export type ArtifactTypeReading = {
28
+ requestType: RequestType;
29
+ requestTypeSource: RequestTypeSource;
30
+ };
31
+ /**
32
+ * The type recorded for `requestId`, read through the same reader the rest of
33
+ * the CLI uses. Every request artifact of the id is a candidate because the
34
+ * dispatched role's own file frequently does not exist yet at dispatch time —
35
+ * a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
36
+ * them at the time of writing, a count the session is still growing): 18 had any
37
+ * request artifact for the id on disk before the dispatch and 10 had one that
38
+ * declared a type — while a sibling role may have recorded the type already. A
39
+ * `default` result is a real answer — nothing declared it.
40
+ */
41
+ export declare function readArtifactType(input: {
42
+ projectRoot: string;
43
+ sessionId: string;
44
+ requestId: string;
45
+ role: string;
46
+ }): Promise<ArtifactTypeReading>;
47
+ /** The composed block for a dispatch, reading the type from disk first. */
48
+ export declare function readArtifactContractBlock(input: {
49
+ projectRoot: string;
50
+ sessionId: string;
51
+ requestId: string;
52
+ role: string;
53
+ }): Promise<string>;
@@ -0,0 +1,212 @@
1
+ // The artifact contract block a dispatched sub-agent receives: for its own role
2
+ // and the request's type, every artifact the prerequisite gate will demand and
3
+ // the literal body markers each one must carry.
4
+ //
5
+ // Generated from the table the gate reads (`getPrerequisitesFor`), never from a
6
+ // second hand-written list: the markers are matched as case-insensitive
7
+ // substrings of the artifact body, so a list kept in prose drifts the moment a
8
+ // marker changes and the gate then refuses a producer it never told.
9
+ import { DEFAULT_REQUEST_TYPE, getPrerequisitesFor } from './artifact-prerequisites.js';
10
+ import { ALLOWED_STATES_PER_ROLE } from './request-artifact-state-helpers.js';
11
+ import { extractMetadata } from './request-artifact-metadata.js';
12
+ import { REQUEST_ID_PATTERN, showRequestArtifact } from './request-artifact-service.js';
13
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
14
+ /** Roles whose request artifact may carry a `- type:` line, in search order. */
15
+ const TYPE_SOURCE_ROLES = ['rd', 'prd', 'qa', 'ui', 'sc'];
16
+ /** True for the five roles the state table is keyed on. */
17
+ function isRequestArtifactRole(role) {
18
+ return Object.prototype.hasOwnProperty.call(ALLOWED_STATES_PER_ROLE, role);
19
+ }
20
+ /**
21
+ * The prerequisite's path with the request id substituted for its `<rid>`.
22
+ *
23
+ * Deliberately NOT exported. A test that called this would no longer be
24
+ * independent of the renderer it checks, and that independence is the whole
25
+ * value of the pinning case.
26
+ */
27
+ function resolveContractPath(prerequisite, requestId) {
28
+ return prerequisite.relativePath.replace('<rid>', requestId);
29
+ }
30
+ function quoteAll(markers) {
31
+ return markers.map((marker) => `\`${marker}\``).join(', ');
32
+ }
33
+ /**
34
+ * The marker fields, in the order the block renders them. A table rather than a
35
+ * chain of `if`s: the three fields are independent and uniform, so listing them
36
+ * keeps the renderer's complexity flat as the vocabulary grows.
37
+ */
38
+ const MARKER_CLAUSES = [
39
+ { markers: (candidate) => candidate.mustContain, label: 'must contain' },
40
+ { markers: (candidate) => candidate.mustContainAny, label: 'must contain at least one of' },
41
+ {
42
+ markers: (candidate) => candidate.headingMustContain,
43
+ label: 'must appear as markdown headings'
44
+ }
45
+ ];
46
+ /**
47
+ * One line's worth of "what this file must carry", or the explicit statement
48
+ * that there is nothing to carry. `mustContainAny` is rendered as an
49
+ * alternative set rather than as three requirements — the gate passes on one.
50
+ */
51
+ function describePrerequisite(prerequisite) {
52
+ const clauses = MARKER_CLAUSES.flatMap(({ markers, label }) => {
53
+ const list = markers(prerequisite) ?? [];
54
+ return list.length === 0 ? [] : [`${label}: ${quoteAll(list)}`];
55
+ });
56
+ if (prerequisite.backCompat === true) {
57
+ const until = prerequisite.backCompatUntil ?? 'the window closes';
58
+ clauses.push(`a missing file only warns until ${until}`);
59
+ }
60
+ return clauses.length === 0 ? 'the file must exist; it has no body markers' : clauses.join('; ');
61
+ }
62
+ /**
63
+ * The command that reaches a state, spelled with every option
64
+ * `src/cli/commands/request-transition-command.ts` registers as MANDATORY.
65
+ * `--project` is one of them, and an earlier revision of this line omitted it —
66
+ * the prompt therefore handed the producer a command the CLI refuses for a
67
+ * missing option, which is this block's own defect class turned on itself. The
68
+ * pinning test now compares the emitted options against the command's own
69
+ * `mandatory` set, so a newly required flag fails the suite rather than reaching
70
+ * a prompt. `.` because a dispatched sub-agent's working directory is the
71
+ * project root.
72
+ */
73
+ function transitionCommand(role, state, requestId) {
74
+ return `peaks request transition ${requestId} --role ${role} --state ${state} --project .`;
75
+ }
76
+ function renderStateRow(role, state, prerequisites, requestId) {
77
+ const lines = prerequisites.map((entry) => `- \`${resolveContractPath(entry, requestId)}\` — ${describePrerequisite(entry)}`);
78
+ const reached = transitionCommand(role, state, requestId);
79
+ return {
80
+ state,
81
+ text: `\nAt \`${role}:${state}\` (reached with \`${reached}\`):\n${lines.join('\n')}\n`
82
+ };
83
+ }
84
+ /**
85
+ * One row per state of `role` that demands at least one artifact under
86
+ * `requestType`. A state with an empty row (`rd:implemented` for a feature, for
87
+ * instance) is left out rather than rendered as "nothing required" — the block
88
+ * is a list of obligations, and a state with none is not an obligation.
89
+ */
90
+ function stateRows(role, requestType, requestId) {
91
+ if (!isRequestArtifactRole(role))
92
+ return [];
93
+ const rows = [];
94
+ for (const state of ALLOWED_STATES_PER_ROLE[role]) {
95
+ const prerequisites = getPrerequisitesFor(role, state, requestType);
96
+ if (prerequisites.length === 0)
97
+ continue;
98
+ rows.push(renderStateRow(role, state, prerequisites, requestId));
99
+ }
100
+ return rows;
101
+ }
102
+ const BODY_RULE = 'The gate matches each marker below as a case-insensitive substring of the artifact body, and a ' +
103
+ 'heading marker must be a real markdown heading. Content under a different spelling is refused, ' +
104
+ 'so write the marker literally. Paths are relative to `.peaks/_runtime/<session-id>/`.';
105
+ /**
106
+ * The scope bound, always true of the block regardless of what the gate does:
107
+ * it says what the rows ARE (necessary) and not what they are not (sufficient).
108
+ */
109
+ const SCOPE_BASE = 'This block is generated from the prerequisite table alone, so the rows below are necessary and are ' +
110
+ 'not a complete contract.';
111
+ /**
112
+ * The addendum for a state the gate really does guard with more than the table.
113
+ * Measured on a probe project and again on this slice's own rid: an artifact set
114
+ * satisfying every `rd:qa-handoff` row was still refused once, on a declaration
115
+ * outside the table. The earlier wording said a gate "may also check something
116
+ * the table does not carry", which under-claims a systematic gap at exactly the
117
+ * state this block guides a producer to.
118
+ */
119
+ const SCOPE_HANDOFF = ' At `rd:qa-handoff` the gate also runs checks that are not rows of this table, so satisfying every ' +
120
+ 'row below does not by itself open that transition.';
121
+ const ARTIFACT_CONTRACT_HEADING = '## Artifact contract (generated from the prerequisite table)';
122
+ /**
123
+ * The block, or `''` when this role has nothing gated to say under this type.
124
+ * The empty string is the whole byte-identity contract: callers concatenate it,
125
+ * and a role with no gated artifacts must add zero bytes to the prompt.
126
+ */
127
+ export function buildArtifactContractBlock(input) {
128
+ const rows = stateRows(input.role, input.requestType, input.requestId);
129
+ if (rows.length === 0)
130
+ return '';
131
+ const typeLine = input.requestTypeSource === 'declared'
132
+ ? `request type \`${input.requestType}\` (recorded by a \`- type:\` line)`
133
+ : `request type \`${input.requestType}\` — the DEFAULT, not a recorded choice: this request ` +
134
+ 'records no `- type:` line, so the gate applies the default table. If the work is really a ' +
135
+ 'different type, the demand set below is the wrong one';
136
+ // Conditional on the ROWS, not on a hand-written type list: whichever types
137
+ // render an `rd:qa-handoff` row are exactly the ones the extra checks run for.
138
+ const guardedHandoff = input.role === 'rd' && rows.some((row) => row.state === 'qa-handoff');
139
+ return (`\n${ARTIFACT_CONTRACT_HEADING}\n` +
140
+ `Role \`${input.role}\`, ${typeLine}.\n` +
141
+ `${BODY_RULE}\n` +
142
+ `${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}\n` +
143
+ rows.map((row) => row.text).join('') +
144
+ '\n');
145
+ }
146
+ /**
147
+ * Append the block unless the text already carries one.
148
+ *
149
+ * Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
150
+ * already hold a copy — a re-dispatch, or a resume from a stored prompt — and
151
+ * two sections can DISAGREE (the type may have been declared between the two
152
+ * runs), so a reader cannot tell which contract is authoritative. The presence
153
+ * test is the block's own heading, which nothing else emits.
154
+ *
155
+ * An empty block adds zero bytes even when the text already carries one, so an
156
+ * unaffected dispatch stays byte-identical.
157
+ */
158
+ export function ensureArtifactContractBlock(text, block) {
159
+ if (block.length === 0 || text.includes(ARTIFACT_CONTRACT_HEADING))
160
+ return text;
161
+ return `${text}${block}`;
162
+ }
163
+ /**
164
+ * The type recorded for `requestId`, read through the same reader the rest of
165
+ * the CLI uses. Every request artifact of the id is a candidate because the
166
+ * dispatched role's own file frequently does not exist yet at dispatch time —
167
+ * a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
168
+ * them at the time of writing, a count the session is still growing): 18 had any
169
+ * request artifact for the id on disk before the dispatch and 10 had one that
170
+ * declared a type — while a sibling role may have recorded the type already. A
171
+ * `default` result is a real answer — nothing declared it.
172
+ */
173
+ export async function readArtifactType(input) {
174
+ const fallback = {
175
+ requestType: DEFAULT_REQUEST_TYPE,
176
+ requestTypeSource: 'default'
177
+ };
178
+ if (isUnsafePathInput(input.sessionId) || !REQUEST_ID_PATTERN.test(input.requestId)) {
179
+ return fallback;
180
+ }
181
+ const candidates = [];
182
+ for (const candidate of [input.role, ...TYPE_SOURCE_ROLES]) {
183
+ if (isRequestArtifactRole(candidate) && !candidates.includes(candidate)) {
184
+ candidates.push(candidate);
185
+ }
186
+ }
187
+ for (const role of candidates) {
188
+ const found = await showRequestArtifact({
189
+ projectRoot: input.projectRoot,
190
+ sessionId: input.sessionId,
191
+ role,
192
+ requestId: input.requestId
193
+ });
194
+ if (found === null)
195
+ continue;
196
+ const metadata = extractMetadata(found.content);
197
+ if (metadata.requestTypeSource === 'declared') {
198
+ return { requestType: metadata.requestType, requestTypeSource: 'declared' };
199
+ }
200
+ }
201
+ return fallback;
202
+ }
203
+ /** The composed block for a dispatch, reading the type from disk first. */
204
+ export async function readArtifactContractBlock(input) {
205
+ const reading = await readArtifactType(input);
206
+ return buildArtifactContractBlock({
207
+ role: input.role,
208
+ requestId: input.requestId,
209
+ requestType: reading.requestType,
210
+ requestTypeSource: reading.requestTypeSource
211
+ });
212
+ }
@@ -55,6 +55,10 @@ export type ArtifactPrerequisite = {
55
55
  * the last of those, so the oldest tier still has to resolve.
56
56
  */
57
57
  legacyRelativePaths?: ReadonlyArray<string>;
58
+ /** Back-compat window — a missing file warns instead of failing; see `prerequisite-checks.ts`. */
59
+ backCompat?: boolean;
60
+ /** The release that CLOSES that window (e.g. `v2.14.0`); the warning code's suffix. */
61
+ backCompatUntil?: string;
58
62
  };
59
63
  export type PrerequisiteCheckResult = {
60
64
  ok: boolean;
@@ -63,15 +67,19 @@ export type PrerequisiteCheckResult = {
63
67
  description: string;
64
68
  }>;
65
69
  /**
66
- * path that is currently missing but is in a 1-minor-release
67
- * back-compat window. The transition gate does not throw on
68
- * `missing`-only (so legacy callers keep working) but surfaces the
69
- * warning to the operator so they can plan the v2.14.0 hard cut.
70
+ * Missing files inside a back-compat window (see
71
+ * `ArtifactPrerequisite.backCompat`). NOT a failure — the gate does not throw
72
+ * on these, so legacy callers keep working. They ARE reported:
73
+ * `transitionRequestArtifact` copies the list onto its success result and
74
+ * `peaks request transition` prints each one as an envelope warning, so a
75
+ * soft-passed prerequisite is not read as a passed one. `code` is derived per
76
+ * prerequisite (`prerequisite-checks.ts`), so it names which artifact.
70
77
  */
71
78
  warnings: Array<{
72
79
  path: string;
73
80
  code: string;
74
81
  message: string;
82
+ expiredWindow?: string;
75
83
  }>;
76
84
  };
77
85
  export type CheckPrerequisitesOptions = {
@@ -85,20 +93,20 @@ export type CheckPrerequisitesOptions = {
85
93
  role: RequestArtifactRole;
86
94
  newState: RequestArtifactState;
87
95
  requestId: string;
88
- requestType?: RequestType;
96
+ /**
97
+ * Required, with no default. The `?? DEFAULT_REQUEST_TYPE` that used to sit in
98
+ * `getPrerequisitesFor`'s signature let a caller silently select the `feature`
99
+ * table by omitting an argument; a caller that wants the default now has to
100
+ * write it, and the one place that legitimately substitutes it is the artifact
101
+ * reader (`request-artifact-metadata.ts`), which labels the substitution.
102
+ */
103
+ requestType: RequestType;
104
+ /**
105
+ * False for a caller that is not a state move — the retag command's impact
106
+ * probe reads the table without transitioning anything, and the event stream
107
+ * is read as a record of transitions.
108
+ */
109
+ emitEvents?: boolean;
89
110
  };
90
- export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
91
- /**
92
- * The contract's BODY checks for one prerequisite, applied to `body`. Returns
93
- * one human-readable message per failed check, empty when the body satisfies
94
- * the contract.
95
- *
96
- * Exported because this contract has a SECOND enforcer: `peaks workflow
97
- * verify-pipeline` probes the same table for the paths it checks
98
- * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
99
- * `existsSync` passed files this function rejects — a guard laxer than the
100
- * contract it claims to read. Both callers now share this one implementation,
101
- * so the checker cannot drift from the table again.
102
- */
103
- export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
111
+ export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType: RequestType): ReadonlyArray<ArtifactPrerequisite>;
104
112
  export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;