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
@@ -7,7 +7,7 @@
7
7
  import fs from 'node:fs';
8
8
  import os from 'node:os';
9
9
  import path from 'node:path';
10
- import picomatch from 'picomatch';
10
+ import { globMatcher } from './util/glob-match.js';
11
11
  import { toPosix, walkFiles } from './util/paths.js';
12
12
 
13
13
  /** Suite-root name prefix; the guard matches on it. */
@@ -253,21 +253,21 @@ const LINT_ESCAPE = 'test-temp-allow';
253
253
  * Raw OS-temp mints outside {@link makeTempDir}, in explicit globs only.
254
254
  *
255
255
  * @param {string} repoRoot
256
- * @param {string[]} globs repo-relative picomatch patterns
256
+ * @param {string[]} globs repo-relative glob patterns
257
257
  * @param {{ fsImpl?: typeof fs }} [deps]
258
258
  * @returns {{ file: string, line: number, text: string }[]}
259
259
  */
260
260
  export function findRawTmpdirMkdtemp(repoRoot, globs, { fsImpl = fs } = {}) {
261
261
  const patterns = (globs ?? []).filter(Boolean);
262
- // Split negations out: in a mixed picomatch array a `!` entry is its own
262
+ // Split negations out: in a mixed glob array a `!` entry is its own
263
263
  // positive matcher, which widens the scan instead of narrowing it.
264
264
  const include = patterns.filter((p) => !p.startsWith('!'));
265
265
  const exclude = patterns
266
266
  .filter((p) => p.startsWith('!'))
267
267
  .map((p) => p.slice(1));
268
268
  if (include.length === 0) return [];
269
- const isIncluded = picomatch(include);
270
- const isExcluded = exclude.length > 0 ? picomatch(exclude) : () => false;
269
+ const isIncluded = globMatcher(include);
270
+ const isExcluded = exclude.length > 0 ? globMatcher(exclude) : () => false;
271
271
  const findings = [];
272
272
  for (const rel of listJsSources(repoRoot, fsImpl)) {
273
273
  if (!isIncluded(rel) || isExcluded(rel)) continue;
@@ -1,6 +1,6 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
- import picomatch from 'picomatch';
3
+ import { globMatcher } from './util/glob-match.js';
4
4
 
5
5
  /** Slow suites (real git, binary spawns) excluded from `test:quick`. */
6
6
  export const INTEGRATION_INCLUDE = [
@@ -14,7 +14,7 @@ export const INTEGRATION_INCLUDE = [
14
14
  'tests/single-story-close-sync.test.js',
15
15
  ];
16
16
 
17
- const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
17
+ const matchesIntegration = globMatcher(INTEGRATION_INCLUDE, { dot: true });
18
18
 
19
19
  /**
20
20
  * Pack-and-install suites driving the shipped binary — too expensive for
@@ -23,7 +23,7 @@ const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
23
23
  */
24
24
  const E2E_INCLUDE = ['tests/e2e/**/*.test.js'];
25
25
 
26
- const matchesE2E = picomatch(E2E_INCLUDE, { dot: true });
26
+ const matchesE2E = globMatcher(E2E_INCLUDE, { dot: true });
27
27
 
28
28
  const TIERS = ['full', 'quick', 'integration', 'e2e'];
29
29
 
@@ -0,0 +1,64 @@
1
+ /**
2
+ * glob-match.js — the one glob matcher for shipped scripts.
3
+ *
4
+ * Every repo-relative glob (config, audit rules, footprints) is matched here,
5
+ * on POSIX semantics on every platform, so a pattern means the same thing on
6
+ * a Windows runner as on Linux. Built on minimatch; picomatch was dropped
7
+ * because no release fixes GHSA-fc5q-39xc-vjpf.
8
+ */
9
+
10
+ import { Minimatch } from 'minimatch';
11
+
12
+ const BASE_OPTIONS = Object.freeze({ platform: 'linux', nocomment: true });
13
+
14
+ // `dir/**` also matches `dir` itself, as picomatch did; `!dir/**` excludes it.
15
+ function compile(pattern, opts) {
16
+ const options = { ...BASE_OPTIONS, ...opts };
17
+ const mm = new Minimatch(pattern, options);
18
+ if (!pattern.endsWith('/**')) return (file) => mm.match(file);
19
+ const dir = new Minimatch(pattern.slice(0, -3), options);
20
+ return mm.negate
21
+ ? (file) => mm.match(file) && dir.match(file)
22
+ : (file) => mm.match(file) || dir.match(file);
23
+ }
24
+
25
+ /**
26
+ * @param {string|string[]} patterns A path matches when ANY pattern does.
27
+ * @param {{ dot?: boolean }} [opts]
28
+ * @returns {(file: string) => boolean}
29
+ */
30
+ export function globMatcher(patterns, opts = {}) {
31
+ const matchers = [patterns].flat().map((p) => compile(p, opts));
32
+ return (file) => matchers.some((match) => match(file));
33
+ }
34
+
35
+ /**
36
+ * @param {string} file
37
+ * @param {string|string[]} patterns
38
+ * @param {{ dot?: boolean }} [opts]
39
+ * @returns {boolean}
40
+ */
41
+ export function isGlobMatch(file, patterns, opts = {}) {
42
+ return globMatcher(patterns, opts)(file);
43
+ }
44
+
45
+ const hasMagic = (segment) => new Minimatch(segment, BASE_OPTIONS).hasMagic();
46
+
47
+ /**
48
+ * Split a glob into its static directory prefix and whether it has magic. A
49
+ * literal path is its own base; a leading `!` is not part of the base.
50
+ *
51
+ * @param {string} glob
52
+ * @returns {{ base: string, isGlob: boolean }}
53
+ */
54
+ export function scanGlob(glob) {
55
+ const text = String(glob).replace(/^!/, '');
56
+ const segments = text.split('/');
57
+ const firstMagic = segments.findIndex(hasMagic);
58
+ if (firstMagic === -1) return { base: text, isGlob: false };
59
+ const base = segments.slice(0, firstMagic).join('/');
60
+ return {
61
+ base: base === '' && text.startsWith('/') ? '/' : base,
62
+ isGlob: true,
63
+ };
64
+ }
@@ -9,7 +9,7 @@
9
9
  * @module lib/wave-runner/footprint
10
10
  */
11
11
 
12
- import picomatch from 'picomatch';
12
+ import { globMatcher, scanGlob } from '../util/glob-match.js';
13
13
 
14
14
  /**
15
15
  * One class today; kept on the envelope so consumers keyed on `source` stay
@@ -62,7 +62,7 @@ const GLOB_OPTIONS = Object.freeze({ dot: true });
62
62
  * @returns {string}
63
63
  */
64
64
  function globBase(glob) {
65
- return picomatch.scan(glob).base;
65
+ return scanGlob(glob).base;
66
66
  }
67
67
 
68
68
  /**
@@ -117,7 +117,7 @@ function addHit(hits, path, side) {
117
117
  */
118
118
  function collectGlobHits(hits, mine, theirs, side) {
119
119
  for (const glob of mine.globs) {
120
- const matches = picomatch(glob, GLOB_OPTIONS);
120
+ const matches = globMatcher(glob, GLOB_OPTIONS);
121
121
  const covers =
122
122
  theirs.concrete.some((path) => matches(path)) ||
123
123
  theirs.globs.some((other) => globsOverlap(glob, other));
@@ -23,6 +23,7 @@ import { fileURLToPath } from 'node:url';
23
23
  import { assertNoReservedIdStreams } from './check-test-temp-hygiene.js';
24
24
  import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
25
25
  import { runAsCli } from './lib/cli-utils.js';
26
+ import { armGitGuard } from './lib/git-test-guard.js';
26
27
  import { buildWebhookSafeTestEnv } from './lib/test-env.js';
27
28
  import { reportTestRunCredit } from './lib/test-run-credit.js';
28
29
  import {
@@ -224,7 +225,7 @@ export async function runTestSuite({
224
225
  ...options,
225
226
  files,
226
227
  cwd,
227
- env: buildWebhookSafeTestEnv(process.env),
228
+ env: armGitGuard(buildWebhookSafeTestEnv(process.env), process.env),
228
229
  stdout,
229
230
  });
230
231
  } finally {
@@ -0,0 +1,187 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * The one place a session title is built. Workflows cite it with an event and
5
+ * apply the printed title through the host (runbooks/session-titles.md); they
6
+ * never compose a title inline.
7
+ *
8
+ * Exit codes: 0 a title (or `apply: false` when disabled), 2 a usage error.
9
+ */
10
+
11
+ import { parseArgs } from 'node:util';
12
+ import { runAsCli } from './lib/cli-utils.js';
13
+ import { getDeliveryRouting } from './lib/config/delivery-routing.js';
14
+ import { resolveConfig } from './lib/config-resolver.js';
15
+
16
+ const MAX_TITLE = 48;
17
+
18
+ /** event → glyph, fixed verb, and the one input it takes (null: none). */
19
+ const EVENTS = Object.freeze({
20
+ 'plan-seed': { glyph: '○', verb: '', input: 'summary' },
21
+ 'plan-ticket': { glyph: '○', verb: 'Planning', input: 'ids' },
22
+ planned: { glyph: '○', verb: 'Planned', input: 'ids' },
23
+ deliver: { glyph: '◐', verb: 'Delivery', input: 'ids' },
24
+ 'deliver-prompt': { glyph: '◐', verb: '', input: 'summary' },
25
+ delivered: { glyph: '●', verb: 'Delivered', input: 'ids' },
26
+ blocked: { glyph: '⊗', verb: 'Blocked', input: 'ids' },
27
+ orchestrate: { glyph: '◐', verb: 'Orchestrating', input: null },
28
+ audit: { glyph: '◐', verb: 'Audit', input: 'lens' },
29
+ audited: { glyph: '●', verb: 'Audit', input: 'lens' },
30
+ qa: { glyph: '◐', verb: 'QA', input: 'summary' },
31
+ 'qa-done': { glyph: '●', verb: 'QA', input: 'summary' },
32
+ });
33
+
34
+ const INPUTS = ['ids', 'summary', 'lens'];
35
+
36
+ const HELP = `Usage: node .agents/scripts/session-title.js --event <name> [--ids <id,id,...> | --summary "<text>" | --lens <name>] [--json]
37
+
38
+ Builds the host session title for a workflow event and prints one JSON object:
39
+ {"title": "<string>", "apply": true}, or {"title": null, "apply": false,
40
+ "reason": "disabled"} when delivery.routing.sessionTitles is false. How a
41
+ title is applied: .agents/docs/runbooks/session-titles.md.
42
+
43
+ Events (input → title):
44
+ ${Object.entries(EVENTS)
45
+ .map(
46
+ ([name, { glyph, verb, input }]) =>
47
+ ` ${name.padEnd(15)}${(input ? `--${input}` : '(none)').padEnd(11)}${[glyph, verb, input && `<${input}>`].filter(Boolean).join(' ')}`,
48
+ )
49
+ .join('\n')}
50
+
51
+ Flags:
52
+ --event The workflow event (required).
53
+ --ids Comma-separated ids; a leading # is dropped.
54
+ --summary Free text; control characters stripped, whitespace collapsed.
55
+ --lens The audit lens name.
56
+ --json Accepted for symmetry; output is always JSON.
57
+ --help Show this message.
58
+ `;
59
+
60
+ class UsageError extends Error {}
61
+
62
+ /**
63
+ * @param {string} raw
64
+ * @returns {string}
65
+ */
66
+ function formatIds(raw) {
67
+ const ids = raw
68
+ .split(',')
69
+ .map((id) => id.trim().replace(/^#/, ''))
70
+ .filter((id) => id !== '');
71
+ if (ids.length === 0) throw new UsageError('--ids needs at least one id');
72
+ const bad = ids.find((id) => !/^\d+$/.test(id));
73
+ if (bad !== undefined) throw new UsageError(`non-numeric id: ${bad}`);
74
+ if (ids.length <= 3) return ids.map((id) => `#${id}`).join(' ');
75
+ const nums = ids.map(Number);
76
+ return `#${Math.min(...nums)}–#${Math.max(...nums)} (${ids.length})`;
77
+ }
78
+
79
+ /**
80
+ * @param {string} raw
81
+ * @param {string} flag
82
+ * @returns {string}
83
+ */
84
+ function cleanText(raw, flag) {
85
+ const text = raw
86
+ .replace(/\s+/g, ' ')
87
+ .replace(/\p{Cc}/gu, '')
88
+ .replace(/ +/g, ' ')
89
+ .trim();
90
+ if (text === '') throw new UsageError(`--${flag} is empty`);
91
+ return text;
92
+ }
93
+
94
+ /**
95
+ * Cap the title at MAX_TITLE characters, cutting only the free text.
96
+ *
97
+ * @param {string} prefix glyph plus fixed verb
98
+ * @param {string} text
99
+ * @returns {string}
100
+ */
101
+ function fit(prefix, text) {
102
+ if (!text) return prefix;
103
+ const head = `${prefix} `;
104
+ const budget = MAX_TITLE - [...head].length;
105
+ const chars = [...text];
106
+ if (chars.length <= budget) return head + text;
107
+ return `${head}${chars
108
+ .slice(0, budget - 1)
109
+ .join('')
110
+ .trimEnd()}…`;
111
+ }
112
+
113
+ /**
114
+ * @param {{ event?: string, ids?: string, summary?: string, lens?: string }} values
115
+ * @returns {string}
116
+ */
117
+ function buildTitle(values) {
118
+ const spec = EVENTS[values.event];
119
+ if (!spec) {
120
+ throw new UsageError(
121
+ values.event ? `unknown event: ${values.event}` : '--event is required',
122
+ );
123
+ }
124
+ const given = INPUTS.filter((name) => values[name] !== undefined);
125
+ const expected = spec.input ? [spec.input] : [];
126
+ if (given.join() !== expected.join()) {
127
+ throw new UsageError(
128
+ `${values.event} takes ${spec.input ? `--${spec.input}` : 'no input'}`,
129
+ );
130
+ }
131
+ const prefix = [spec.glyph, spec.verb].filter(Boolean).join(' ');
132
+ if (!spec.input) return prefix;
133
+ const raw = values[spec.input];
134
+ const text =
135
+ spec.input === 'ids' ? formatIds(raw) : cleanText(raw, spec.input);
136
+ return fit(prefix, text);
137
+ }
138
+
139
+ /**
140
+ * @param {{ argv?: string[] }} [args]
141
+ * @param {{
142
+ * resolveConfigImpl?: typeof resolveConfig,
143
+ * stdout?: { write: (s: string) => unknown },
144
+ * stderr?: { write: (s: string) => unknown },
145
+ * }} [deps]
146
+ * @returns {Promise<number>} exit code
147
+ */
148
+ export async function runSessionTitle(
149
+ { argv = process.argv.slice(2) } = {},
150
+ {
151
+ resolveConfigImpl = resolveConfig,
152
+ stdout = process.stdout,
153
+ stderr = process.stderr,
154
+ } = {},
155
+ ) {
156
+ let title;
157
+ try {
158
+ const { values } = parseArgs({
159
+ args: argv,
160
+ options: {
161
+ event: { type: 'string' },
162
+ ids: { type: 'string' },
163
+ summary: { type: 'string' },
164
+ lens: { type: 'string' },
165
+ json: { type: 'boolean', default: false },
166
+ },
167
+ strict: true,
168
+ allowPositionals: false,
169
+ });
170
+ title = buildTitle(values);
171
+ } catch (err) {
172
+ stderr.write(`[session-title] ${err.message}\n\n${HELP}`);
173
+ return 2;
174
+ }
175
+ const enabled = getDeliveryRouting(resolveConfigImpl()).sessionTitles;
176
+ const result = enabled
177
+ ? { title, apply: true }
178
+ : { title: null, apply: false, reason: 'disabled' };
179
+ stdout.write(`${JSON.stringify(result)}\n`);
180
+ return 0;
181
+ }
182
+
183
+ runAsCli(import.meta.url, () => runSessionTitle(), {
184
+ source: 'session-title',
185
+ usage: HELP,
186
+ propagateExitCode: true,
187
+ });
@@ -44,6 +44,7 @@ import {
44
44
  NEXT_COMMANDS,
45
45
  terminalFromWaitOutcome,
46
46
  } from './lib/orchestration/story-deliver-terminal.js';
47
+ import { publishDeliveryStage } from './lib/orchestration/story-stage-publish.js';
47
48
  import { PROJECT_ROOT } from './lib/project-root.js';
48
49
  import { createProvider } from './lib/provider-factory.js';
49
50
  import { confirmAndLand } from './lib/single-story/confirm-and-land.js';
@@ -454,6 +455,12 @@ export async function runConfirmMerge({
454
455
  storyBranch,
455
456
  gh: ctx.gh,
456
457
  });
458
+ await publishDeliveryStage({
459
+ provider: ctx.provider,
460
+ storyId,
461
+ stage: 'merge',
462
+ prNumber,
463
+ });
457
464
  if (prNumber == null) return await confirmWithoutPr(ctx);
458
465
  const withPr = { ...ctx, prNumber };
459
466
  return wait ? await resumeMergeWait(withPr) : await probeMergeOnce(withPr);
@@ -49,6 +49,7 @@ import {
49
49
  } from './lib/orchestration/single-story-lease-guard.js';
50
50
  import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
51
51
  import { composeStoryInitResult } from './lib/orchestration/story-init-result.js';
52
+ import { publishDeliveryStage } from './lib/orchestration/story-stage-publish.js';
52
53
  import {
53
54
  STATE_LABELS,
54
55
  transitionTicketState,
@@ -57,7 +58,7 @@ import { createProvider } from './lib/provider-factory.js';
57
58
  import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
58
59
  import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
59
60
  // `sweepMergedStoryBranches` is imported dynamically: its graph reaches
60
- // `picomatch`, which would crash before `assertDepsInstalled()` can report.
61
+ // `minimatch`, which would crash before `assertDepsInstalled()` can report.
61
62
  import { WorktreeManager } from './lib/worktree-manager.js';
62
63
 
63
64
  export { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
@@ -68,11 +69,11 @@ export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
68
69
  * opaque `ERR_MODULE_NOT_FOUND` from deep in the sweep graph. Builtins only.
69
70
  */
70
71
  function assertDepsInstalled(projectRoot) {
71
- const probe = path.join(projectRoot, 'node_modules', 'picomatch');
72
+ const probe = path.join(projectRoot, 'node_modules', 'minimatch');
72
73
  if (!existsSync(probe)) {
73
74
  throw new Error(
74
75
  [
75
- 'Project dependencies are not installed (missing node_modules/picomatch).',
76
+ 'Project dependencies are not installed (missing node_modules/minimatch).',
76
77
  `Run \`npm install\` from ${projectRoot} before invoking this script.`,
77
78
  ].join(' '),
78
79
  );
@@ -763,6 +764,8 @@ export async function runSingleStoryInit({
763
764
  await rollbackClaimOnInitFailure(provider, storyId, config);
764
765
  throw err;
765
766
  }
767
+ // Every mutation has landed: the Story is now in its build stage.
768
+ await publishDeliveryStage({ provider, storyId, stage: 'build' });
766
769
  }
767
770
 
768
771
  // Every path gets the checklist; `buildStoryChecklist` never throws.
@@ -304,6 +304,10 @@ start an arbitrary dev server, and do not fall back to a static-only claim
304
304
  dressed as a runtime one — name the skip and let the static findings stand on
305
305
  their own.
306
306
 
307
+ ## Session title {#session-title}
308
+
309
+ The top-level caller, never an `auditor` subagent, titles the session `node .agents/scripts/session-title.js --event audit --lens <lens>` when the lens starts and `--event audited --lens <lens>` once its report is written ([runbook](../../docs/runbooks/session-titles.md)).
310
+
307
311
  ## Execution strategy {#execution-strategy}
308
312
 
309
313
  A lens is a self-contained, read-only unit of work — exactly the shape a
@@ -87,6 +87,13 @@ The `code-review` provider also maps depth to `claude --effort`: `low` at
87
87
  `light` and `standard`, `high` at `deep`. `delivery.codeReview.effortByDepth`
88
88
  overrides that per depth (`low`/`medium`/`high`/`xhigh`/`max`).
89
89
 
90
+ A Story's **first pass** (its review history holds no run) is always `deep`
91
+ and carries `exhaustive: true`: the LLM-backed providers append one shared
92
+ directive asking the reviewer to sweep every changed file for every instance
93
+ of each defect class it raises, and every added read, write and response path
94
+ for an access or role-narrowing class. The history marks that run
95
+ `exhaustive`. A review with no history seam is never a first pass.
96
+
90
97
  The LLM-backed review providers (code-review, codex, security-review,
91
98
  ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
92
99
  model actually changes thoroughness. The native provider deliberately ignores
@@ -111,7 +118,7 @@ severity rule, excuse a `shortcut:` comment, or change the output shape. Over
111
118
  8,000 characters it is truncated and recorded as a degraded gate.
112
119
 
113
120
  Prose cannot silence a finding. Only `delivery.codeReview.skipPaths`
114
- (picomatch globs) drops findings, after grounding and verification and before
121
+ (globs) drops findings, after grounding and verification and before
115
122
  severity is counted; the report states how many were dropped.
116
123
 
117
124
  ### Bug classes, instances and repeats
@@ -99,22 +99,20 @@ After the self-eval's last fix commit the worker runs **one** command:
99
99
  `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
100
100
 
101
101
  `ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
102
- deferred suite, a base-merge conflict, a non-fast-forward push,
103
- a `commit_refs_rules` push stepping missed or a CRITICAL: fix, commit,
104
- re-run; labels untouched. `blocked` (exit 1) → only a remote-refused push,
105
- an unreachable remote, an unconfirmed base branch, an unregistered merge
106
- driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
107
- `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
102
+ deferred suite, a base-merge conflict, a push to fix or a CRITICAL: fix,
103
+ commit, re-run; labels untouched. `blocked` (exit 1) → only a remote-refused
104
+ push, an unreachable remote, an unconfirmed base branch, an unregistered
105
+ merge driver, `review-cap` or `host-resources` (exit 77): it flips
106
+ `agent::blocked` and posts `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
108
107
 
109
108
  1. **Base merge:** merge `origin/<baseBranch>` into the Story branch
110
109
  **first**, ahead of every check: close's base-sync then no-ops. Then close's **duplication re-score**, committed
111
110
  **untagged** before any credit.
112
- 2. **Preflight — blocking.** `typecheck`/`lint`/`format` (close's credit),
113
- `quality-preview.js --changed-since origin/<baseBranch>`, each baselined
114
- ratchet, `check-baselines`; one `fix-required` lists all. Serial unless
115
- per-host `.agentrc.local.json` sets `delivery.execution.preflightConcurrency`
116
- above 1 (default 1): close's independent gates then run in admitted
117
- lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
111
+ 2. **Preflight — blocking.** Fast lane first: `delivery.handoff.firstChecks`,
112
+ `check-baselines`; a finding stops there. Then `typecheck`/`lint`/`format`
113
+ (close's credit), `quality-preview.js --changed-since origin/<baseBranch>`,
114
+ each baselined ratchet; one `fix-required` lists all. Lanes:
115
+ `preflightConcurrency` — [`deliver-reference.md`](deliver-reference.md) § Preflight.
118
116
  3. **One depositor** (`suiteOfRecord: ci`: CI's), by one predicate close registers `coverage-capture`
119
117
  on — coverage or CRAP gate on **and** a `captureScript`:
120
118
  - **Capture-active** →
@@ -130,8 +128,10 @@ driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
130
128
  …`; then post-capture checks: close's `quality-preview-crap` and `check-baselines`,
131
129
  then `delivery.handoff.postSeatChecks`. Children get `MANDREL_HANDOFF_STEP`.
132
130
  5. **Push** `story-<id>`; the remote ref must equal HEAD.
133
- 6. **Held review** from step 1, beside 2: a CRITICAL skips or aborts 3,
134
- one envelope with any finding — [`deliver-reference.md`](deliver-reference.md) § Held review.
131
+ 6. **Held review**, from a clean fast lane: a CRITICAL skips or aborts 3.
132
+ Fix, commit, re-run: a **review-first retry** settles the review before
133
+ any check; `blocked` (`review-cap`) at `acceptanceEval.maxRounds`
134
+ rounds — [`deliver-reference.md`](deliver-reference.md) § Held review.
135
135
 
136
136
  A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
137
137
  reads the **output**, not the exit code: no signal deposits nothing. Seat order, runner shapes:
@@ -146,25 +146,24 @@ respawned.
146
146
  `single-story-close.js` emits exactly one envelope on stdout between
147
147
  `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
148
148
  [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
149
- — the SSOT. Relay it verbatim; never hand-compose one.
149
+ — the SSOT; relay it verbatim.
150
150
 
151
151
  | `status` | Exit | Meaning | You do |
152
152
  | --- | --- | --- | --- |
153
- | `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. Done. |
153
+ | `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. |
154
154
  | `pending` | 3 | **Resumable, not a failure** — the bounded wait expired healthy, or a human owns the merge. Nothing was mutated. | Run `nextCommand`. Each beat: run every `confirm[]` verbatim, pre-epilogue. |
155
- | `blocked` | 1 | Hard block; `blocked.blockClass` names it | `checks-failed` → fix + resume; else relay |
155
+ | `blocked` | 1 | `blocked.blockClass` names it, `blocked.recovery` who clears it | `agent` (stays `agent::closing`) → fix, push, resume; `operator` → relay, pause |
156
156
  | `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close. `base-sync` conflict (files in `failure.reason`): resolve in `workCwd`, commit, run `nextCommand`; block only if you cannot |
157
157
 
158
158
  Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
159
- `phase` (the schema's enum names where it stopped), `elapsedSeconds`,
160
- `nextCommand`. `gates`
159
+ `phase` (where it stopped), `elapsedSeconds`, `nextCommand`. `gates`
161
160
  reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
162
161
  never omitted, so a missing gate never reads as passing.
163
162
 
164
163
  ## 7. When to leave this file
165
164
 
166
- Unclear state / a re-run refusal → `deliver-recover.js --story <id>`; boot
167
- auto-lists stalled `agent::executing` Stories with it (read-only, advisory).
165
+ Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (boot
166
+ runs it on stalled Stories).
168
167
  Lease, sweep, worktree scope; sequencing, epilogue, checklist threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
169
- [`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
170
- [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
168
+ [`deliver-reference.md`](deliver-reference.md). After the PR opens, loop to
169
+ `landed`: [`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge).
@@ -72,6 +72,8 @@ is not being loosened.
72
72
 
73
73
  ## Procedure
74
74
 
75
+ Title the session `node .agents/scripts/session-title.js --event deliver-prompt --summary "<3–6 words>"` as the path starts ([runbook](../../docs/runbooks/session-titles.md)).
76
+
75
77
  1. **Predict + gate.** Form the predicted footprint (new files, edited files)
76
78
  and record the reason you are taking this path, then run the gate — it
77
79
  documents every flag itself, so run it with `--help` rather than guessing:
@@ -84,7 +86,8 @@ is not being loosened.
84
86
 
85
87
  Branch on `action` in the JSON envelope:
86
88
  - **`proceed-light`** — the receipt Story is authored; read `storyId` and
87
- `nextCommands`, then continue to step 2. The diff backstop in step 4 is
89
+ `nextCommands`, retitle the session `--event deliver --ids <storyId>`,
90
+ then continue to step 2. The diff backstop in step 4 is
88
91
  what bounds the actual change.
89
92
  - **escalation** — no `action` to branch on: the gate emits an
90
93
  **`escalated` terminal envelope** instead (exit 2), attended or not.