mandrel 2.123.0 → 2.125.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 (105) hide show
  1. package/.agents/README.md +1 -1
  2. package/.agents/docs/agentrc-reference.json +2 -0
  3. package/.agents/docs/configuration.md +6 -3
  4. package/.agents/docs/runbooks/dispatch-board.md +174 -0
  5. package/.agents/docs/runbooks/dispatch.md +219 -0
  6. package/.agents/docs/runbooks/session-titles.md +52 -0
  7. package/.agents/runtime-deps.json +2 -2
  8. package/.agents/schemas/agentrc.schema.json +85 -3
  9. package/.agents/schemas/audit-rules.schema.json +1 -1
  10. package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
  11. package/.agents/scripts/acceptance-eval.js +11 -2
  12. package/.agents/scripts/check-doc-links.js +4 -4
  13. package/.agents/scripts/dispatch.js +400 -0
  14. package/.agents/scripts/lib/audit-baselines/surface-entry.js +2 -2
  15. package/.agents/scripts/lib/audit-exceptions/globs.js +2 -2
  16. package/.agents/scripts/lib/audit-exceptions/scope.js +2 -2
  17. package/.agents/scripts/lib/audit-suite/selector.js +3 -3
  18. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +3 -3
  19. package/.agents/scripts/lib/baselines/components.js +2 -2
  20. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +2 -2
  21. package/.agents/scripts/lib/bdd-runner-detect.js +3 -4
  22. package/.agents/scripts/lib/child-detached.js +48 -0
  23. package/.agents/scripts/lib/child-exec.js +11 -0
  24. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +2 -2
  25. package/.agents/scripts/lib/config/delivery-routing.js +15 -12
  26. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  27. package/.agents/scripts/lib/config/handoff.js +21 -6
  28. package/.agents/scripts/lib/config/temp-paths.js +26 -0
  29. package/.agents/scripts/lib/config-settings-schema-delivery.js +64 -10
  30. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  31. package/.agents/scripts/lib/coverage-baseline.js +3 -3
  32. package/.agents/scripts/lib/coverage-capture-delta.js +2 -2
  33. package/.agents/scripts/lib/coverage-capture-own-fix.js +2 -2
  34. package/.agents/scripts/lib/dispatch/environments.js +135 -0
  35. package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
  36. package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
  37. package/.agents/scripts/lib/dispatch/liveness.js +21 -0
  38. package/.agents/scripts/lib/dispatch/record.js +54 -0
  39. package/.agents/scripts/lib/dispatch/status.js +285 -0
  40. package/.agents/scripts/lib/dispatch/targets.js +101 -0
  41. package/.agents/scripts/lib/dispatch/verdict.js +207 -0
  42. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  43. package/.agents/scripts/lib/git-test-guard.js +119 -0
  44. package/.agents/scripts/lib/git-utils.js +3 -0
  45. package/.agents/scripts/lib/maintainability-utils.js +4 -4
  46. package/.agents/scripts/lib/observability/handoff-telemetry.js +2 -0
  47. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  48. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +3 -2
  49. package/.agents/scripts/lib/orchestration/block-class-recovery.js +44 -0
  50. package/.agents/scripts/lib/orchestration/code-review.js +35 -19
  51. package/.agents/scripts/lib/orchestration/diff-magnitude.js +1 -1
  52. package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js +3 -3
  53. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +3 -4
  54. package/.agents/scripts/lib/orchestration/review-history.js +9 -10
  55. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +9 -2
  56. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +8 -5
  57. package/.agents/scripts/lib/orchestration/review-providers/codex.js +3 -11
  58. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  59. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +22 -0
  60. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +10 -2
  61. package/.agents/scripts/lib/orchestration/review-providers/types.js +2 -0
  62. package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js +13 -2
  63. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +40 -15
  64. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
  65. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +8 -1
  66. package/.agents/scripts/lib/orchestration/story-handoff.js +222 -54
  67. package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
  68. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  69. package/.agents/scripts/lib/test-temp.js +5 -5
  70. package/.agents/scripts/lib/test-tiers.js +3 -3
  71. package/.agents/scripts/lib/util/glob-match.js +64 -0
  72. package/.agents/scripts/lib/wave-runner/footprint.js +3 -3
  73. package/.agents/scripts/run-tests.js +2 -1
  74. package/.agents/scripts/session-title.js +187 -0
  75. package/.agents/scripts/single-story-confirm-merge.js +7 -0
  76. package/.agents/scripts/single-story-init.js +6 -3
  77. package/.agents/workflows/helpers/audit-lens-core.md +4 -0
  78. package/.agents/workflows/helpers/code-review.md +8 -1
  79. package/.agents/workflows/helpers/deliver-digest.md +22 -23
  80. package/.agents/workflows/helpers/deliver-light.md +4 -1
  81. package/.agents/workflows/helpers/deliver-reference.md +55 -24
  82. package/.agents/workflows/helpers/deliver-story-reference.md +10 -3
  83. package/.agents/workflows/helpers/deliver-story.md +27 -7
  84. package/.agents/workflows/helpers/qa-core.md +2 -0
  85. package/.agents/workflows/mandrel-deliver.md +14 -4
  86. package/.agents/workflows/mandrel-orchestrate.md +2 -0
  87. package/.agents/workflows/mandrel-plan.md +4 -0
  88. package/README.md +8 -0
  89. package/bin/mandrel.js +35 -13
  90. package/docs/CHANGELOG.md +29 -0
  91. package/lib/cli/dispatch.js +27 -0
  92. package/lib/cli/ui/accounts.js +81 -0
  93. package/lib/cli/ui/board-model.js +372 -0
  94. package/lib/cli/ui/board.css +525 -0
  95. package/lib/cli/ui/board.html +80 -0
  96. package/lib/cli/ui/board.js +676 -0
  97. package/lib/cli/ui/log-tail.js +89 -0
  98. package/lib/cli/ui/panel-model.js +100 -0
  99. package/lib/cli/ui/preferences.js +136 -0
  100. package/lib/cli/ui/request-guard.js +108 -0
  101. package/lib/cli/ui/server.js +211 -0
  102. package/lib/cli/ui/sources.js +202 -0
  103. package/lib/cli/ui/story-detail.js +92 -0
  104. package/lib/cli/ui.js +114 -0
  105. package/package.json +2 -2
@@ -25,6 +25,18 @@ const DEPTH_DIRECTIVES = Object.freeze({
25
25
  'signature or shape.',
26
26
  });
27
27
 
28
+ /**
29
+ * Follows the depth directive on a Story's first review pass, so it leads with
30
+ * a space; see `BUG_CLASS_RULE`.
31
+ */
32
+ const EXHAUSTIVE_DIRECTIVE =
33
+ ' This is the first review of this Story: make it exhaustive. Enumerate ' +
34
+ 'every defect class you raise. For each class, sweep every changed file ' +
35
+ 'for every instance before returning, and report them all in that ' +
36
+ "finding's `instances`. For an access-control, authorization or " +
37
+ 'role-narrowing class, check every read, write and response path the ' +
38
+ 'diff adds.';
39
+
28
40
  /**
29
41
  * Anything unrecognised, including `undefined`, is `standard`.
30
42
  *
@@ -44,3 +56,13 @@ export function normalizeDepth(depth) {
44
56
  export function renderDepthDirective(depth) {
45
57
  return DEPTH_DIRECTIVES[normalizeDepth(depth)];
46
58
  }
59
+
60
+ /**
61
+ * `EXHAUSTIVE_DIRECTIVE` on a first pass; otherwise empty.
62
+ *
63
+ * @param {boolean|undefined} exhaustive
64
+ * @returns {string}
65
+ */
66
+ export function renderExhaustiveDirective(exhaustive) {
67
+ return exhaustive ? EXHAUSTIVE_DIRECTIVE : '';
68
+ }
@@ -13,7 +13,10 @@ import { spawnSync } from 'node:child_process';
13
13
  import { resolveAgentrcRoot } from '../../config/git-roots.js';
14
14
  import { BUG_CLASS_RULE, parseProviderFindings } from './parse-findings.js';
15
15
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
16
- import { renderDepthDirective } from './review-depth.js';
16
+ import {
17
+ renderDepthDirective,
18
+ renderExhaustiveDirective,
19
+ } from './review-depth.js';
17
20
  import { renderGuidanceBlock } from './review-guidance.js';
18
21
 
19
22
  export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
@@ -122,7 +125,11 @@ export function buildSecurityReviewPrompt(input) {
122
125
  .replace('{headRef}', headRef)
123
126
  .replace('{scopeLabel}', scopeLabel)
124
127
  .replace('{ticketId}', ticketId)
125
- .replace('{depthDirective}', renderDepthDirective(input?.depth))
128
+ .replace(
129
+ '{depthDirective}',
130
+ renderDepthDirective(input?.depth) +
131
+ renderExhaustiveDirective(input?.exhaustive),
132
+ )
126
133
  .replace('{guidance}', () => renderGuidanceBlock(input?.guidance));
127
134
  }
128
135
 
@@ -211,6 +218,7 @@ export function createSecurityReviewProvider(deps = {}) {
211
218
  baseRef,
212
219
  headRef,
213
220
  depth: input.depth,
221
+ exhaustive: input.exhaustive,
214
222
  guidance: input.guidance,
215
223
  });
216
224
  if (result.status !== 0) {
@@ -40,6 +40,8 @@
40
40
  * providers MUST render it into their prompt. Absent → `standard`.
41
41
  * @property {string=} effort - `claude --effort` level resolved from `depth`;
42
42
  * absent → `low`.
43
+ * @property {boolean=} exhaustive - The Story's first review pass; LLM-backed
44
+ * providers render it via `renderExhaustiveDirective`.
43
45
  * @property {(string|null)=} guidance - Project review guidance; LLM-backed
44
46
  * providers render it via `renderGuidanceBlock`.
45
47
  *
@@ -9,7 +9,10 @@
9
9
  * @typedef {import('./types.js').ReviewInput} ReviewInput
10
10
  */
11
11
 
12
- import { renderDepthDirective } from './review-depth.js';
12
+ import {
13
+ renderDepthDirective,
14
+ renderExhaustiveDirective,
15
+ } from './review-depth.js';
13
16
 
14
17
  export const ULTRAREVIEW_PROMPT_TEMPLATE =
15
18
  '💡 **Suggested:** Consider running `/ultrareview` on this ' +
@@ -29,7 +32,15 @@ export function buildUltrareviewMessage(input) {
29
32
  return ULTRAREVIEW_PROMPT_TEMPLATE.replace('{scopeLabel}', scopeLabel)
30
33
  .replace('{baseRef}', baseRef)
31
34
  .replace('{headRef}', headRef)
32
- .replace('{depthDirective}', renderDepthDirective(input?.depth));
35
+ .replace('{depthDirective}', directives(input));
36
+ }
37
+
38
+ /** The depth directive, then the exhaustive one on a first pass. */
39
+ function directives(input) {
40
+ return (
41
+ renderDepthDirective(input?.depth) +
42
+ renderExhaustiveDirective(input?.exhaustive)
43
+ );
33
44
  }
34
45
 
35
46
  /**
@@ -15,8 +15,8 @@
15
15
  * check fails fast instead of burning the budget.
16
16
  *
17
17
  * Terminals: `landed` (confirmed, post-land tail ran); `pending` (nothing
18
- * mutated); `blocked` (classified, `merge.unlanded` emitted, friction posted,
19
- * Story → `agent::blocked`); `blocked`/`merged-flip-failed` (merged but the
18
+ * mutated); `blocked` (classified, `merge.unlanded` emitted, friction posted;
19
+ * only an operator-recovery class flips `agent::blocked`); `blocked`/`merged-flip-failed` (merged but the
20
20
  * `agent::done` write failed — its own event and wording, since the merge
21
21
  * is not in question).
22
22
  */
@@ -32,6 +32,7 @@ import {
32
32
  import { pollUntil } from '../../../util/poll-loop.js';
33
33
  import { defaultSleep } from '../../../util/sleep.js';
34
34
  import { applyBehindUpdate } from '../../behind-recovery.js';
35
+ import { recoveryOf } from '../../block-class-recovery.js';
35
36
  import {
36
37
  checkVerdict,
37
38
  classifyRollupEntry,
@@ -495,10 +496,17 @@ function formatUnlandedFriction({
495
496
  `gave up after ${elapsedSeconds}s without observing a confirmed merge.\n\n` +
496
497
  `**Block class:** \`${blockClass}\`\n\n` +
497
498
  `**Reason:** ${reason}\n\n` +
498
- `Story transitioned to \`agent::blocked\`.\n\n${remedy}`
499
+ `${recoveryLine(blockClass)}\n\n${remedy}`
499
500
  );
500
501
  }
501
502
 
503
+ /** Agent-class blocks stay `agent::closing`: the session owns the fix. */
504
+ function recoveryLine(blockClass) {
505
+ return recoveryOf(blockClass) === 'agent'
506
+ ? 'Story stays at `agent::closing` — the delivering session fixes and resumes it (recovery: agent).'
507
+ : 'Story transitioned to `agent::blocked` — an operator must act (recovery: operator).';
508
+ }
509
+
502
510
  /** Friction for a merge that landed but whose `agent::done` write failed. */
503
511
  function formatFlipFailedFriction({
504
512
  storyId,
@@ -927,6 +935,34 @@ function pinnedRun(run) {
927
935
  return { writeDigestFn: (args) => writeCiDigest({ ...args, checkRunFn }) };
928
936
  }
929
937
 
938
+ /** Only an operator-class block is the HITL pause; best-effort. */
939
+ async function blockIfOperatorOwned({
940
+ provider,
941
+ storyId,
942
+ blockClass,
943
+ progress,
944
+ }) {
945
+ if (recoveryOf(blockClass) === 'agent') {
946
+ progress?.(
947
+ 'CONFIRM',
948
+ `🔧 Story #${storyId} stays agent::closing (${blockClass}, recovery: agent).`,
949
+ );
950
+ return;
951
+ }
952
+ try {
953
+ await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
954
+ progress?.(
955
+ 'CONFIRM',
956
+ `🛑 Story #${storyId} → agent::blocked (${blockClass}).`,
957
+ );
958
+ } catch (err) {
959
+ progress?.(
960
+ 'CONFIRM',
961
+ `⚠️ Failed to flip Story #${storyId} to agent::blocked: ${err?.message ?? err}`,
962
+ );
963
+ }
964
+ }
965
+
930
966
  /** Classify, emit `merge.unlanded`, post friction, block — all best-effort. */
931
967
  async function blockOnUnlanded({
932
968
  storyId,
@@ -999,18 +1035,7 @@ async function blockOnUnlanded({
999
1035
  progress,
1000
1036
  });
1001
1037
 
1002
- try {
1003
- await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
1004
- progress?.(
1005
- 'CONFIRM',
1006
- `🛑 Story #${storyId} → agent::blocked (${blockClass}).`,
1007
- );
1008
- } catch (err) {
1009
- progress?.(
1010
- 'CONFIRM',
1011
- `⚠️ Failed to flip Story #${storyId} to agent::blocked: ${err?.message ?? err}`,
1012
- );
1013
- }
1038
+ await blockIfOperatorOwned({ provider, storyId, blockClass, progress });
1014
1039
 
1015
1040
  return {
1016
1041
  confirmed: false,
@@ -23,6 +23,7 @@ import {
23
23
  releaseStoryLease,
24
24
  } from '../single-story-lease-guard.js';
25
25
  import { createStoryProgress } from '../story-progress.js';
26
+ import { publishStagePhase } from '../story-stage-publish.js';
26
27
  import { createPhaseTimer } from './phase-timer.js';
27
28
  import { parsePrNumber } from './phases/code-review.js';
28
29
  import { runConfirmMergePhase } from './phases/confirm-merge.js';
@@ -520,6 +521,7 @@ async function finishPhase(ctx, deps) {
520
521
 
521
522
  /** Each phase extends the shared context; a non-null return ends the run. */
522
523
  const CLOSE_PIPELINE = Object.freeze([
524
+ publishStagePhase('close'),
523
525
  loadStoryPhase,
524
526
  graphqlPreflightPhase,
525
527
  resolveBasePhase,
@@ -8,6 +8,7 @@ import nodeFs from 'node:fs';
8
8
  import { storyTerminalEnvelopePath } from '../config/temp-paths.js';
9
9
  import { resolveConfig } from '../config-resolver.js';
10
10
  import { writeFileAtomic } from '../util/atomic-write.js';
11
+ import { BLOCK_CLASS_RECOVERY } from './block-class-recovery.js';
11
12
  import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
12
13
 
13
14
  export { validateTerminalEnvelope };
@@ -95,6 +96,12 @@ function compact(obj) {
95
96
  return out;
96
97
  }
97
98
 
99
+ /** An unknown class gets no `recovery`, so the schema rejects the envelope. */
100
+ function withRecovery(blocked) {
101
+ if (!blocked) return null;
102
+ return { ...blocked, recovery: BLOCK_CLASS_RECOVERY[blocked.blockClass] };
103
+ }
104
+
98
105
  /**
99
106
  * Throws a `TypeError` on a schema violation — callers trust the status
100
107
  * without re-probing GitHub. An unreadable schema does not throw.
@@ -163,7 +170,7 @@ export function buildTerminalEnvelope({
163
170
  pr: pr ?? null,
164
171
  gates,
165
172
  tail: tail ?? null,
166
- blocked: blocked ?? null,
173
+ blocked: withRecovery(blocked),
167
174
  failure: failure ?? null,
168
175
  escalation: escalation ?? null,
169
176
  nextCommand: nextCommand ?? null,