mandrel 2.70.0 → 2.72.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 (79) 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/schemas/story-deliver-terminal.schema.json +10 -1
  11. package/.agents/scripts/acceptance-eval.js +194 -15
  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/bootstrap/issue-forms-template.js +1 -1
  17. package/.agents/scripts/lib/cli-args.js +22 -0
  18. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  19. package/.agents/scripts/lib/config/agent-models.js +117 -0
  20. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  21. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  23. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  24. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  25. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  26. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  27. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  28. package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
  29. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  30. package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
  31. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  32. package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
  33. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  34. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
  35. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  36. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
  37. package/.agents/scripts/lib/orchestration/pr-watch.js +14 -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/auto-merge.js +45 -0
  42. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +162 -58
  43. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +58 -6
  44. package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
  45. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  46. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
  47. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
  48. package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
  49. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
  50. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
  51. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +187 -74
  52. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
  53. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  54. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  55. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  56. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  57. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  58. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  59. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  60. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  61. package/.agents/scripts/pr-watch-with-update.js +5 -0
  62. package/.agents/scripts/single-story-close.js +8 -0
  63. package/.agents/scripts/single-story-confirm-merge.js +34 -3
  64. package/.agents/scripts/single-story-init.js +17 -32
  65. package/.agents/scripts/story-handoff.js +112 -0
  66. package/.agents/scripts/sync-claude-agents.js +58 -27
  67. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  68. package/.agents/workflows/helpers/code-review.md +3 -3
  69. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  70. package/.agents/workflows/helpers/deliver-light.md +9 -7
  71. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  72. package/.agents/workflows/helpers/deliver-story-reference.md +39 -18
  73. package/.agents/workflows/helpers/deliver-story.md +30 -23
  74. package/.agents/workflows/helpers/plan-reference.md +24 -9
  75. package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
  76. package/docs/CHANGELOG.md +31 -0
  77. package/lib/cli/registry.js +7 -0
  78. package/package.json +4 -3
  79. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -1,4 +1,5 @@
1
1
  import { parseArgs } from 'node:util';
2
+ import { AGENT_MODEL_PATTERN } from './config/agent-models.js';
2
3
 
3
4
  /**
4
5
  * Positive integer with an optional leading `#`; `null` when invalid.
@@ -157,6 +158,25 @@ export function parseWorkerTokens(value) {
157
158
  };
158
159
  }
159
160
 
161
+ /**
162
+ * Best-effort, like {@link parseWorkerTokens}, except that absence is the
163
+ * normal inline case and carries no warning.
164
+ *
165
+ * @param {unknown} value
166
+ * @returns {{ model: string|null, warning: string|null }}
167
+ */
168
+ export function parseWorkerModel(value) {
169
+ if (value == null) return { model: null, warning: null };
170
+ const raw = String(value).trim();
171
+ if (new RegExp(AGENT_MODEL_PATTERN).test(raw)) {
172
+ return { model: raw, warning: null };
173
+ }
174
+ return {
175
+ model: null,
176
+ warning: `--worker-model must be an agent model value (got ${JSON.stringify(value)}); telemetry.workerModel records null.`,
177
+ };
178
+ }
179
+
160
180
  /**
161
181
  * Throws when a validating flag parser rejects a value; error handlers use
162
182
  * {@link parseSprintArgsTolerant} instead of re-calling this.
@@ -189,6 +209,7 @@ export function parseSprintArgs(
189
209
  'rerun-advisory': { type: 'string' },
190
210
  'override-review-block': { type: 'string' },
191
211
  'worker-tokens': { type: 'string' },
212
+ 'worker-model': { type: 'string' },
192
213
  executor: { type: 'string' },
193
214
  cwd: { type: 'string' },
194
215
  'recut-of': { type: 'string' },
@@ -220,6 +241,7 @@ export function parseSprintArgs(
220
241
  ? tolerantOverrideReviewBlock(values['override-review-block'])
221
242
  : parseOverrideReviewBlock(values['override-review-block']),
222
243
  workerTokens: values['worker-tokens'],
244
+ workerModel: values['worker-model'],
223
245
  executor: values.executor ?? null,
224
246
  cwd:
225
247
  (typeof values.cwd === 'string' && values.cwd.trim()) ||
@@ -60,12 +60,27 @@ function buildBaselinesGateEnv(baseBranch) {
60
60
  * @param {object|undefined|null} config - Canonical resolved config.
61
61
  * @returns {boolean}
62
62
  */
63
- function isCrapGateEnabled(config) {
63
+ export function isCrapGateEnabled(config) {
64
64
  if (!config || typeof config !== 'object') return true;
65
65
  const enabled = config?.delivery?.quality?.gates?.crap?.enabled;
66
66
  return typeof enabled === 'boolean' ? enabled : true;
67
67
  }
68
68
 
69
+ /**
70
+ * The credited-run depositor predicate — the ONE home, shared by close's gate
71
+ * registration and the worker's `story-handoff.js`, so the two cannot pick
72
+ * different depositors: coverage-capture runs the suite when the CRAP gate is
73
+ * on AND a `test:coverage` script exists; any other project takes the plain
74
+ * `test` gate (the evidence-gate `npm test` credit).
75
+ *
76
+ * @param {object|undefined|null} config - Canonical resolved config.
77
+ * @param {Record<string, string>|null|undefined} scripts - `package.json` scripts.
78
+ * @returns {boolean}
79
+ */
80
+ export function isCoverageCaptureActive(config, scripts) {
81
+ return isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
82
+ }
83
+
69
84
  /**
70
85
  * The plain `test` gate, unless coverage-capture will run the suite — every
71
86
  * close must keep exactly one working test gate.
@@ -381,8 +396,7 @@ export function buildDefaultGates({
381
396
  shouldSkipImpl,
382
397
  } = {}) {
383
398
  const scripts = packageScripts ?? readPackageScripts(cwd);
384
- const coverageCaptureActive =
385
- isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
399
+ const coverageCaptureActive = isCoverageCaptureActive(config, scripts);
386
400
  // A credited bare `npm test` registers the plain `test` gate beside the
387
401
  // capture so the credit is reported, never re-spent.
388
402
  const testCredited = resolveTestCredited({
@@ -0,0 +1,117 @@
1
+ /**
2
+ * `delivery.routing.agentModels`: a per-role override of the `model:`
3
+ * frontmatter default each `.agents/agents/<role>.md` declares, applied when
4
+ * `sync-claude-agents` projects `.claude/agents/`. It never selects or changes
5
+ * the operator's session model.
6
+ */
7
+
8
+ import fs from 'node:fs';
9
+ import path from 'node:path';
10
+
11
+ import { getDeliveryRouting } from './delivery-routing.js';
12
+
13
+ /** The role-scoped agents `.agents/agents/` ships — the `agentModels` keys. */
14
+ export const ROLE_AGENT_NAMES = Object.freeze([
15
+ 'story-worker',
16
+ 'acceptance-critic',
17
+ 'plan-critic',
18
+ 'auditor',
19
+ ]);
20
+
21
+ /** A model alias, a full model id, or `inherit` — shell-safe by construction. */
22
+ export const AGENT_MODEL_PATTERN = '^[A-Za-z0-9][A-Za-z0-9._:-]*$';
23
+
24
+ /** What an agent with no `model:` runs on: the operator's session model. */
25
+ const INHERIT_MODEL = 'inherit';
26
+
27
+ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
28
+ const MODEL_LINE_RE = /^model:[^\r\n]*$/m;
29
+
30
+ /**
31
+ * The valid overrides only: an unknown role or an unsafe value is dropped
32
+ * (config validation already refuses both on load).
33
+ *
34
+ * @param {object | null | undefined} config
35
+ * @returns {Record<string, string>}
36
+ */
37
+ export function getAgentModels(config) {
38
+ const raw = config?.delivery?.routing?.agentModels;
39
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
40
+ const pattern = new RegExp(AGENT_MODEL_PATTERN);
41
+ return Object.fromEntries(
42
+ Object.entries(raw).filter(
43
+ ([role, model]) =>
44
+ ROLE_AGENT_NAMES.includes(role) &&
45
+ typeof model === 'string' &&
46
+ pattern.test(model),
47
+ ),
48
+ );
49
+ }
50
+
51
+ /**
52
+ * The `model:` a role file's frontmatter declares, or null.
53
+ *
54
+ * @param {string} content
55
+ * @returns {string|null}
56
+ */
57
+ function frontmatterModel(content) {
58
+ const block = String(content ?? '').match(FRONTMATTER_RE);
59
+ const line = block?.[1].match(MODEL_LINE_RE);
60
+ const value = line?.[0].slice('model:'.length).trim();
61
+ return value || null;
62
+ }
63
+
64
+ /**
65
+ * The model a role runs on: its `agentModels` override, else its frontmatter
66
+ * default, else `inherit`.
67
+ *
68
+ * @param {{ role: string, config?: object|null, content?: string }} args
69
+ * @returns {string}
70
+ */
71
+ function resolveAgentModel({ role, config, content }) {
72
+ const override = getAgentModels(config)[role];
73
+ return override ?? frontmatterModel(content) ?? INHERIT_MODEL;
74
+ }
75
+
76
+ /**
77
+ * Write `model` into a role file's frontmatter, replacing a declared default
78
+ * or appending one; content without frontmatter is returned unchanged.
79
+ *
80
+ * @param {string} content
81
+ * @param {string} model
82
+ * @returns {string}
83
+ */
84
+ export function applyAgentModel(content, model) {
85
+ const block = content.match(FRONTMATTER_RE);
86
+ if (!block) return content;
87
+ const inner = MODEL_LINE_RE.test(block[1])
88
+ ? block[1].replace(MODEL_LINE_RE, `model: ${model}`)
89
+ : `${block[1]}\nmodel: ${model}`;
90
+ return `---\n${inner}\n---\n${content.slice(block[0].length)}`;
91
+ }
92
+
93
+ /**
94
+ * The model a dispatched story-worker runs on: its `agentModels` override,
95
+ * else the role file's default. With role-scoped agents off, the worker is a
96
+ * `general-purpose` spawn on the session model.
97
+ *
98
+ * @param {{ config?: object, mainRepo: string }} args
99
+ * @param {{ readFileFn?: typeof fs.readFileSync }} [deps]
100
+ * @returns {string}
101
+ */
102
+ export function resolveStoryWorkerModel(
103
+ { config, mainRepo },
104
+ { readFileFn = fs.readFileSync } = {},
105
+ ) {
106
+ if (!getDeliveryRouting(config).roleScopedAgents) return INHERIT_MODEL;
107
+ let content = '';
108
+ try {
109
+ content = readFileFn(
110
+ path.join(mainRepo, '.agents', 'agents', 'story-worker.md'),
111
+ 'utf8',
112
+ );
113
+ } catch {
114
+ // An absent role file declares no default: the resolver falls to inherit.
115
+ }
116
+ return resolveAgentModel({ role: 'story-worker', config, content });
117
+ }
@@ -3,6 +3,10 @@
3
3
  // delivery.* sub-schemas of AGENTRC_SCHEMA.
4
4
 
5
5
  import { ACCEPTANCE_EVAL_DEFAULTS } from './config/acceptance-eval.js';
6
+ import {
7
+ AGENT_MODEL_PATTERN,
8
+ ROLE_AGENT_NAMES,
9
+ } from './config/agent-models.js';
6
10
  import { CI_DELIVERY_DEFAULTS } from './config/ci.js';
7
11
  import { DELIVERY_ROUTING_DEFAULTS } from './config/delivery-routing.js';
8
12
  import { DEFAULT_CODE_REVIEW } from './config/runners.js';
@@ -189,6 +193,14 @@ const ROUTING_SCHEMA = {
189
193
  'When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge.',
190
194
  default: DELIVERY_ROUTING_DEFAULTS.closeAndLand,
191
195
  },
196
+ agentModels: {
197
+ type: 'object',
198
+ description:
199
+ 'Per-role model override for the role-scoped agents, keyed by role name (`story-worker`, `acceptance-critic`, `plan-critic`, `auditor`; any other key is a validation error). A value is a Claude Code agent model: an alias (`sonnet`, `opus`, `haiku`), a full model id, or `inherit` (the operator\'s session model). It replaces the role file\'s `model:` frontmatter default when `sync-claude-agents` projects `.claude/agents/<role>.md`. Defaults: story-worker, acceptance-critic and plan-critic `inherit` (a checker runs at least as strong as the maker); auditor `sonnet` (a read-heavy lens sweep). Nothing here selects or changes the operator\'s session model, and a one-Story run stays inline in that session. A multi-Story close records the dispatched story-worker\'s resolved model as `telemetry.workerModel` beside `workerTokens` (null for an inline close), so opting workers down, e.g. `{ "story-worker": "sonnet" }`, is decided from measured outcomes.',
200
+ propertyNames: { enum: [...ROLE_AGENT_NAMES] },
201
+ additionalProperties: { type: 'string', pattern: AGENT_MODEL_PATTERN },
202
+ default: {},
203
+ },
192
204
  },
193
205
  additionalProperties: false,
194
206
  };
@@ -202,7 +214,7 @@ const CI_DELIVERY_SCHEMA = {
202
214
  type: 'string',
203
215
  enum: ['trust-ci', 'strict'],
204
216
  description:
205
- "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
217
+ "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' skips arming auto-merge, so the operator owns the merge; it adds no review gate.",
206
218
  default: CI_DELIVERY_DEFAULTS.autoMerge,
207
219
  },
208
220
  blockOnAdvisoryFailure: {
@@ -132,7 +132,7 @@ export const CODE_REVIEW_SCHEMA = {
132
132
  additionalProperties: false,
133
133
  },
134
134
  description:
135
- "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (scoped lint + MI) then an optional story-scoped `code-review` — a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge; hosts without the `claude` CLI skip it. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
135
+ "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `code-review` — a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge; hosts without the `claude` CLI skip it. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
136
136
  default: DEFAULT_REVIEW_PROVIDERS,
137
137
  },
138
138
  autoFixSeverity: {