mandrel 2.69.0 → 2.71.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 (76) hide show
  1. package/.agents/README.md +8 -9
  2. package/.agents/agents/acceptance-critic.md +1 -0
  3. package/.agents/agents/auditor.md +1 -0
  4. package/.agents/agents/plan-critic.md +1 -0
  5. package/.agents/agents/story-worker.md +63 -64
  6. package/.agents/docs/agentrc-reference.json +2 -1
  7. package/.agents/docs/configuration.md +7 -8
  8. package/.agents/rules/git-conventions-reference.md +2 -2
  9. package/.agents/schemas/agentrc.schema.json +19 -2
  10. package/.agents/scripts/acceptance-eval.js +194 -15
  11. package/.agents/scripts/audit-to-stories.js +39 -247
  12. package/.agents/scripts/deliver-run.js +92 -43
  13. package/.agents/scripts/lib/audit-suite/index.js +1 -1
  14. package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
  15. package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
  16. package/.agents/scripts/lib/audit-to-stories/finding-adapter.js +1 -1
  17. package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
  18. package/.agents/scripts/lib/cli-args.js +22 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  20. package/.agents/scripts/lib/config/agent-models.js +117 -0
  21. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  22. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  23. package/.agents/scripts/lib/findings/route-finding.js +15 -0
  24. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  25. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  26. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  27. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  28. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  29. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  30. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  31. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  32. package/.agents/scripts/lib/orchestration/plan-context.js +31 -11
  33. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +35 -117
  34. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  35. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +24 -22
  36. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  37. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
  38. package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
  39. package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
  40. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
  41. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +151 -56
  42. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +4 -0
  43. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  44. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +26 -17
  45. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  46. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  47. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  48. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  49. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  50. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  51. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  52. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  53. package/.agents/scripts/single-story-close.js +8 -0
  54. package/.agents/scripts/single-story-init.js +17 -32
  55. package/.agents/scripts/story-handoff.js +112 -0
  56. package/.agents/scripts/sync-claude-agents.js +58 -27
  57. package/.agents/templates/docs/audit-sweep-runbook.md +29 -59
  58. package/.agents/workflows/audit-to-stories.md +40 -67
  59. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  60. package/.agents/workflows/helpers/code-review.md +3 -3
  61. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  62. package/.agents/workflows/helpers/deliver-light.md +9 -7
  63. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  64. package/.agents/workflows/helpers/deliver-story-reference.md +11 -9
  65. package/.agents/workflows/helpers/deliver-story.md +30 -23
  66. package/.agents/workflows/helpers/plan-reference.md +24 -9
  67. package/docs/CHANGELOG.md +30 -0
  68. package/lib/cli/registry.js +7 -0
  69. package/lib/migrations/index.js +2 -0
  70. package/lib/migrations/steps/2.70.0-retire-audit-ledger.js +36 -0
  71. package/package.json +4 -3
  72. package/.agents/scripts/lib/audit-to-stories/ledger-commit.js +0 -184
  73. package/.agents/scripts/lib/audit-to-stories/ledger-pr.js +0 -279
  74. package/.agents/scripts/lib/audit-to-stories/ledger-record.js +0 -88
  75. package/.agents/scripts/lib/findings/audit-ledger.js +0 -289
  76. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -18,7 +18,7 @@
18
18
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
19
19
  */
20
20
 
21
- import { readFileSync } from 'node:fs';
21
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
24
  import { parseArgs } from 'node:util';
@@ -26,8 +26,12 @@ import { parseArgs } from 'node:util';
26
26
  import Ajv2020 from 'ajv/dist/2020.js';
27
27
  import addFormats from 'ajv-formats';
28
28
 
29
+ import { deriveCeremony } from './ceremony-derive.js';
29
30
  import { runAsCli } from './lib/cli-utils.js';
31
+ import { getDeliveryRouting } from './lib/config/delivery-routing.js';
32
+ import { resolvedTempRoot } from './lib/config/temp-paths.js';
30
33
  import { getAcceptanceEval, resolveConfig } from './lib/config-resolver.js';
34
+ import { gitSpawn } from './lib/git-utils.js';
31
35
  import { Logger } from './lib/Logger.js';
32
36
  import { appendSignal } from './lib/observability/signals-writer.js';
33
37
  import {
@@ -101,12 +105,16 @@ function parseCliArgs(argv) {
101
105
  verdict: { type: 'string' },
102
106
  'expected-criteria': { type: 'string' },
103
107
  'no-signal': { type: 'boolean', default: false },
108
+ init: { type: 'boolean', default: false },
109
+ cwd: { type: 'string' },
104
110
  },
105
111
  strict: false,
106
112
  });
107
113
  const storyId = Number.parseInt(values.story ?? '', 10);
108
114
  return {
109
115
  storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
116
+ init: values.init === true,
117
+ cwd: values.cwd ?? null,
110
118
  verdictPath: values.verdict ?? null,
111
119
  expectedCriteria: values['expected-criteria'] ?? null,
112
120
  emitSignal: values['no-signal'] !== true,
@@ -119,14 +127,13 @@ const MERGE_CONTRACT =
119
127
  'before scoring.';
120
128
 
121
129
  /**
122
- * The Story body's `acceptance[]` count; any failure yields `null`, never a
123
- * manufactured count.
130
+ * The Story body's `acceptance[]` items, in order; any failure yields `null`.
124
131
  *
125
132
  * @param {{ storyId: number, config: object }} args
126
133
  * @param {{ createProviderFn?: typeof createProvider, parseBodyFn?: typeof parseStoryBody }} [deps]
127
- * @returns {Promise<number|null>}
134
+ * @returns {Promise<string[]|null>}
128
135
  */
129
- export async function readStoryAcceptanceCount(
136
+ export async function readStoryAcceptance(
130
137
  { storyId, config },
131
138
  { createProviderFn = createProvider, parseBodyFn = parseStoryBody } = {},
132
139
  ) {
@@ -136,13 +143,155 @@ export async function readStoryAcceptanceCount(
136
143
  if (body === null) return null;
137
144
  const acceptance = parseBodyFn(body)?.body?.acceptance;
138
145
  return Array.isArray(acceptance) && acceptance.length > 0
139
- ? acceptance.length
146
+ ? acceptance
140
147
  : null;
141
148
  } catch {
142
149
  return null;
143
150
  }
144
151
  }
145
152
 
153
+ /**
154
+ * The Story body's `acceptance[]` count; any failure yields `null`, never a
155
+ * manufactured count.
156
+ *
157
+ * @param {{ storyId: number, config: object }} args
158
+ * @param {Parameters<typeof readStoryAcceptance>[1]} [deps]
159
+ * @returns {Promise<number|null>}
160
+ */
161
+ export async function readStoryAcceptanceCount(args, deps) {
162
+ const acceptance = await readStoryAcceptance(args, deps);
163
+ return acceptance ? acceptance.length : null;
164
+ }
165
+
166
+ /**
167
+ * The `--init` skeleton: one record per `acceptance[]` item, in order, with
168
+ * `index` and `criterion` filled and `verdict` / `evidence` left empty for
169
+ * the verdict owner. Deliberately schema-invalid until filled.
170
+ *
171
+ * @param {{ storyId: number, acceptance: string[], round: number, commitSha: string|null }} args
172
+ * @returns {object}
173
+ */
174
+ export function buildVerdictSkeleton({
175
+ storyId,
176
+ acceptance,
177
+ round,
178
+ commitSha,
179
+ }) {
180
+ return {
181
+ storyId,
182
+ schemaVersion: 1,
183
+ round,
184
+ commitSha,
185
+ criteria: acceptance.map((criterion, index) => ({
186
+ index,
187
+ criterion,
188
+ verdict: '',
189
+ evidence: '',
190
+ })),
191
+ };
192
+ }
193
+
194
+ /**
195
+ * Indices of records still carrying the skeleton's empty `verdict` or
196
+ * `evidence`.
197
+ *
198
+ * @param {unknown} verdict
199
+ * @returns {number[]}
200
+ */
201
+ export function findUnfilledCriteria(verdict) {
202
+ const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
203
+ const blank = (v) => typeof v !== 'string' || v.trim().length === 0;
204
+ return criteria
205
+ .map((c, i) =>
206
+ blank(c?.verdict) || blank(c?.evidence) ? (c?.index ?? i) : null,
207
+ )
208
+ .filter((i) => i !== null);
209
+ }
210
+
211
+ /**
212
+ * Refuse a verdict with unfilled records before schema validation or
213
+ * scoring, so the mistake costs no round.
214
+ *
215
+ * @param {unknown} verdict
216
+ * @returns {void}
217
+ */
218
+ export function assertVerdictFilled(verdict) {
219
+ const unfilled = findUnfilledCriteria(verdict);
220
+ if (unfilled.length === 0) return;
221
+ throw new Error(
222
+ `acceptance-eval: verdict record(s) at index ${unfilled.join(', ')} are unfilled — ` +
223
+ 'every record needs a verdict (met|partial|unmet) and evidence before scoring. No round was consumed.',
224
+ );
225
+ }
226
+
227
+ /** @param {string} cwd @returns {string|null} */
228
+ function readHeadSha(cwd) {
229
+ const res = gitSpawn(cwd, 'rev-parse', 'HEAD');
230
+ const sha = res.status === 0 ? `${res.stdout ?? ''}`.trim() : '';
231
+ return /^[0-9a-f]{7,64}$/.test(sha) ? sha : null;
232
+ }
233
+
234
+ /**
235
+ * `--init`: derive the change set and verdict owner with ceremony-derive's
236
+ * own function, write the skeleton under `<tempRoot>/scratch/story-<id>/`,
237
+ * and return what the owner needs to fill it.
238
+ *
239
+ * @param {{ storyId: number, cwd: string, config: object }} input
240
+ * @param {{
241
+ * readAcceptanceImpl?: typeof readStoryAcceptance,
242
+ * deriveCeremonyImpl?: typeof deriveCeremony,
243
+ * resolveRoundImpl?: typeof resolveAcceptanceEvalRound,
244
+ * readHeadImpl?: typeof readHeadSha,
245
+ * writeFileImpl?: (file: string, text: string) => void,
246
+ * }} [deps]
247
+ * @returns {Promise<{ verdictPath: string, files: string[]|null, verdictOwner: string, round: number, criteria: number }>}
248
+ */
249
+ export async function initVerdictSkeleton({ storyId, cwd, config }, deps = {}) {
250
+ const {
251
+ readAcceptanceImpl = readStoryAcceptance,
252
+ deriveCeremonyImpl = deriveCeremony,
253
+ resolveRoundImpl = resolveAcceptanceEvalRound,
254
+ readHeadImpl = readHeadSha,
255
+ writeFileImpl = (file, text) => {
256
+ mkdirSync(path.dirname(file), { recursive: true });
257
+ writeFileSync(file, text, 'utf8');
258
+ },
259
+ } = deps;
260
+ const acceptance = await readAcceptanceImpl({ storyId, config });
261
+ if (!acceptance) {
262
+ throw new Error(
263
+ `acceptance-eval --init: Story #${storyId}'s acceptance[] could not be read — no skeleton written.`,
264
+ );
265
+ }
266
+ const ceremony = deriveCeremonyImpl({
267
+ storyId,
268
+ baseRef: config?.project?.baseBranch ?? 'main',
269
+ cwd,
270
+ ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
271
+ });
272
+ const { round } = resolveRoundImpl({ epicId: null, storyId, config });
273
+ const skeleton = buildVerdictSkeleton({
274
+ storyId,
275
+ acceptance,
276
+ round,
277
+ commitSha: readHeadImpl(cwd),
278
+ });
279
+ const verdictPath = path.join(
280
+ resolvedTempRoot(config),
281
+ 'scratch',
282
+ `story-${storyId}`,
283
+ `acceptance-verdict-round-${round}.json`,
284
+ );
285
+ writeFileImpl(verdictPath, `${JSON.stringify(skeleton, null, 2)}\n`);
286
+ return {
287
+ verdictPath,
288
+ files: ceremony.files,
289
+ verdictOwner: ceremony.verdictOwner,
290
+ round,
291
+ criteria: acceptance.length,
292
+ };
293
+ }
294
+
146
295
  /**
147
296
  * The derived count wins; a disagreeing flag is a wiring error and throws.
148
297
  *
@@ -354,6 +503,31 @@ export async function runAcceptanceEval(
354
503
  return { envelope, exitCode };
355
504
  }
356
505
 
506
+ /** @param {number|null} storyId */
507
+ function requireStoryId(storyId) {
508
+ if (storyId) return;
509
+ throw new Error(
510
+ 'Usage: node acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
511
+ );
512
+ }
513
+
514
+ /**
515
+ * `--init`: write the skeleton and print its summary; scores nothing.
516
+ *
517
+ * @param {{ storyId: number, cwd: string|null, resolveConfigImpl: typeof resolveConfig, logger: { info: Function }, deps: { initSkeletonImpl?: typeof initVerdictSkeleton } }} args
518
+ * @returns {Promise<object>}
519
+ */
520
+ async function runInitCli({ storyId, cwd, resolveConfigImpl, logger, deps }) {
521
+ const workCwd = path.resolve(cwd ?? process.cwd());
522
+ const skeleton = await (deps.initSkeletonImpl ?? initVerdictSkeleton)({
523
+ storyId,
524
+ cwd: workCwd,
525
+ config: resolveConfigImpl({ cwd: workCwd }),
526
+ });
527
+ logger.info(JSON.stringify(skeleton));
528
+ return skeleton;
529
+ }
530
+
357
531
  /**
358
532
  * CLI core: argv → verdict → validation → coverage → decision → envelope.
359
533
  *
@@ -364,9 +538,10 @@ export async function runAcceptanceEval(
364
538
  * validateVerdictImpl?: typeof validateVerdict,
365
539
  * runAcceptanceEvalImpl?: typeof runAcceptanceEval,
366
540
  * readAcceptanceCountImpl?: typeof readStoryAcceptanceCount,
541
+ * initSkeletonImpl?: typeof initVerdictSkeleton,
367
542
  * logger?: { info: Function, warn?: Function },
368
543
  * }} [deps]
369
- * @returns {Promise<object>} the emitted envelope.
544
+ * @returns {Promise<object>} the emitted envelope (the skeleton summary under `--init`).
370
545
  */
371
546
  export async function runAcceptanceEvalCli(
372
547
  argv = process.argv.slice(2),
@@ -380,15 +555,13 @@ export async function runAcceptanceEvalCli(
380
555
  readAcceptanceCountImpl = readStoryAcceptanceCount,
381
556
  logger = Logger,
382
557
  } = deps;
383
- const { storyId, verdictPath, expectedCriteria, emitSignal } =
558
+ const { storyId, init, cwd, verdictPath, expectedCriteria, emitSignal } =
384
559
  parseCliArgs(argv);
385
560
  const flagged = resolveExpectedCriteria(expectedCriteria);
386
561
 
387
- if (!storyId) {
388
- throw new Error(
389
- 'Usage: node acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
390
- );
391
- }
562
+ requireStoryId(storyId);
563
+ if (init)
564
+ return runInitCli({ storyId, cwd, resolveConfigImpl, logger, deps });
392
565
  if (!verdictPath) {
393
566
  throw new Error('acceptance-eval: --verdict <path> is required.');
394
567
  }
@@ -415,6 +588,7 @@ export async function runAcceptanceEvalCli(
415
588
  );
416
589
  }
417
590
 
591
+ assertVerdictFilled(parsed);
418
592
  const verdict = validateVerdictImpl(parsed);
419
593
 
420
594
  const config = resolveConfigImpl();
@@ -470,11 +644,16 @@ runAsCli(import.meta.url, main, {
470
644
  source: 'acceptance-eval',
471
645
  usage: {
472
646
  invocation:
473
- 'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
647
+ 'node .agents/scripts/acceptance-eval.js --story <id> (--init [--cwd <workCwd>] | --verdict <path> [--expected-criteria <n>] [--no-signal])',
474
648
  summary:
475
- "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision.",
649
+ "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision; --init writes the verdict skeleton to fill first.",
476
650
  flags: [
477
651
  ['--story <id>', 'GitHub issue number of the Story (required).'],
652
+ [
653
+ '--init',
654
+ 'Write the verdict skeleton (one empty record per acceptance[] item, the next round, HEAD) under <tempRoot>/scratch/story-<id>/ and print its path, the derived change set `files` and the `verdictOwner`. Scoring a skeleton with an unfilled record is refused without consuming a round.',
655
+ ],
656
+ ['--cwd <workCwd>', 'Worktree the --init change set is derived in.'],
478
657
  ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
479
658
  [
480
659
  '--expected-criteria <n>',