mandrel 2.70.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 (64) 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/deliver-run.js +92 -43
  12. package/.agents/scripts/lib/audit-suite/index.js +1 -1
  13. package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
  14. package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
  15. package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
  16. package/.agents/scripts/lib/cli-args.js +22 -0
  17. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  18. package/.agents/scripts/lib/config/agent-models.js +117 -0
  19. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  20. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  21. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  22. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  23. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  24. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  25. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  26. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  27. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  28. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  29. package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
  30. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  31. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
  32. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  33. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
  34. package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
  35. package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
  36. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
  37. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +151 -56
  38. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +4 -0
  39. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  40. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +26 -17
  41. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  42. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  43. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  44. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  45. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  46. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  47. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  48. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  49. package/.agents/scripts/single-story-close.js +8 -0
  50. package/.agents/scripts/single-story-init.js +17 -32
  51. package/.agents/scripts/story-handoff.js +112 -0
  52. package/.agents/scripts/sync-claude-agents.js +58 -27
  53. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  54. package/.agents/workflows/helpers/code-review.md +3 -3
  55. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  56. package/.agents/workflows/helpers/deliver-light.md +9 -7
  57. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  58. package/.agents/workflows/helpers/deliver-story-reference.md +11 -9
  59. package/.agents/workflows/helpers/deliver-story.md +30 -23
  60. package/.agents/workflows/helpers/plan-reference.md +24 -9
  61. package/docs/CHANGELOG.md +19 -0
  62. package/lib/cli/registry.js +7 -0
  63. package/package.json +4 -3
  64. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -868,6 +868,10 @@ const TEST_CREDIT_DEPOSIT_COMMAND =
868
868
  const COVERAGE_CAPTURE_COMMAND =
869
869
  'node .agents/scripts/coverage-capture.js --cwd <workCwd>';
870
870
 
871
+ /** The worker's one tail command; it runs whichever depositor applies. */
872
+ const STORY_HANDOFF_COMMAND =
873
+ 'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
874
+
871
875
  const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
872
876
 
873
877
  const PRE_PUSH_REMEDY =
@@ -1010,6 +1014,9 @@ function describePrePushHook(projectRoot, readFileImpl) {
1010
1014
  function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
1011
1015
  const root = projectRoot ?? process.cwd();
1012
1016
  const parts = [
1017
+ {
1018
+ detail: `the worker's \`${STORY_HANDOFF_COMMAND}\` runs the credited run close reads`,
1019
+ },
1013
1020
  describeCreditedRun({
1014
1021
  scripts: readProjectScripts(root, readFile),
1015
1022
  crapEnabled: isCrapEnabled(root, readFile),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.70.0",
3
+ "version": "2.71.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",
@@ -85,7 +85,7 @@
85
85
  "author": "",
86
86
  "license": "MIT",
87
87
  "bin": {
88
- "mandrel": "./bin/mandrel.js"
88
+ "mandrel": "bin/mandrel.js"
89
89
  },
90
90
  "type": "module",
91
91
  "bugs": {
@@ -141,11 +141,12 @@
141
141
  "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
142
142
  "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
143
143
  "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
144
+ "overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT markdown-it 14.1.1, which carries GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths block the event loop). The advisory’s vulnerable range is everything < 14.3.1, so this tree-wide ^14.3.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.23.3, a breaking bump coupled to the js-yaml major above; do not take it. `npm run lint` is what must be re-run if this pin moves.",
144
145
  "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
145
146
  },
146
147
  "overrides": {
147
148
  "js-yaml": "^4.3.2",
148
- "markdown-it": "^14.2.0",
149
+ "markdown-it": "^14.3.1",
149
150
  "smol-toml": "^1.7.1"
150
151
  }
151
152
  }
@@ -1,272 +0,0 @@
1
- /**
2
- * review-providers/scoped-lint.js — scoped biome + markdownlint over the
3
- * changed surface. Runners resolve on disk before spawning (`npx --no biome`
4
- * exits 0 silently when biome is absent), and each surface is classified
5
- * independently so one failure cannot become the other's verdict.
6
- */
7
-
8
- import { spawnSync } from 'node:child_process';
9
- import { existsSync } from 'node:fs';
10
- import path from 'node:path';
11
-
12
- const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
13
-
14
- /**
15
- * npx's unresolvable-bin output: the legacy message or current npm's E404.
16
- * Matching the E404 code, not any `npm error` line, keeps genuine runner
17
- * errors out.
18
- */
19
- const NPX_UNRESOLVABLE =
20
- /could not determine executable to run|npm (?:error|ERR!)\s+code\s+E404/i;
21
-
22
- /** Biome's exit-1 when every path is config-excluded: an empty scope, not a failure. */
23
- const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
24
-
25
- /**
26
- * Markdown runners in preference order, each with its own argument shape:
27
- * cli2 rejects `--ignore`, which cli v1 takes.
28
- */
29
- const MARKDOWN_RUNNERS = Object.freeze([
30
- Object.freeze({ bin: 'markdownlint-cli2', extraArgs: Object.freeze([]) }),
31
- Object.freeze({
32
- bin: 'markdownlint',
33
- extraArgs: Object.freeze(['--ignore', 'node_modules']),
34
- }),
35
- ]);
36
-
37
- const CODE_RUNNERS = Object.freeze([
38
- Object.freeze({ bin: 'biome', extraArgs: Object.freeze([]) }),
39
- ]);
40
-
41
- const DEGRADATION_REASONS = Object.freeze({
42
- RUNNER_NOT_INSTALLED: 'runner-not-installed',
43
- RUNNER_NOT_RESOLVABLE: 'runner-not-resolvable',
44
- UNPARSEABLE_OUTPUT: 'unparseable-output',
45
- });
46
-
47
- /**
48
- * Spawn one lint runner through `npx --no` (never install on the fly).
49
- *
50
- * @param {string} bin
51
- * @param {string[]} args
52
- * @param {string} cwd
53
- * @returns {{ status: number, stdout: string, stderr: string }}
54
- */
55
- function spawnLintRunner(bin, args, cwd) {
56
- const result = spawnSync('npx', ['--no', bin, ...args], {
57
- cwd,
58
- encoding: 'utf-8',
59
- shell: process.platform === 'win32',
60
- });
61
- return {
62
- status: result.status ?? 1,
63
- stdout: result.stdout ?? '',
64
- stderr: result.stderr ?? '',
65
- };
66
- }
67
-
68
- /**
69
- * First candidate installed under `<cwd>/node_modules/.bin`, else `null`.
70
- * Deliberately local-only: a global runner reads as absent and degrades
71
- * honestly rather than trusting an unresolved spawn.
72
- *
73
- * @param {ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>} candidates
74
- * @param {string} cwd
75
- * @param {(p: string) => boolean} existsFn Injected for testing.
76
- * @returns {{ bin: string, extraArgs: ReadonlyArray<string> }|null}
77
- */
78
- function resolveRunner(candidates, cwd, existsFn) {
79
- for (const candidate of candidates) {
80
- const base = path.join(cwd, 'node_modules', '.bin', candidate.bin);
81
- if (existsFn(base)) return candidate;
82
- if (
83
- process.platform === 'win32' &&
84
- (existsFn(`${base}.cmd`) || existsFn(`${base}.ps1`))
85
- ) {
86
- return candidate;
87
- }
88
- }
89
- return null;
90
- }
91
-
92
- /**
93
- * Zero counts with `executionFailed: true`, so it can never read as clean.
94
- *
95
- * @returns {ReturnType<typeof parseLintOutput>}
96
- */
97
- function unresolvedRunnerSummary() {
98
- return {
99
- errors: 0,
100
- warnings: 0,
101
- parsed: false,
102
- executionFailed: true,
103
- emptyScope: false,
104
- reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
105
- };
106
- }
107
-
108
- /**
109
- * Resolve one surface's runner and, only if it resolved, spawn and classify it.
110
- *
111
- * @param {{
112
- * label: string,
113
- * candidates: ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>,
114
- * buildArgs: (runner: { bin: string, extraArgs: ReadonlyArray<string> }) => string[],
115
- * cwd: string,
116
- * runnerFn: typeof spawnLintRunner,
117
- * existsFn: (p: string) => boolean,
118
- * }} args
119
- * @returns {{ surface: string, summary: ReturnType<typeof parseLintOutput> }}
120
- */
121
- function runSurface({ label, candidates, buildArgs, cwd, runnerFn, existsFn }) {
122
- const runner = resolveRunner(candidates, cwd, existsFn);
123
- if (runner === null) {
124
- return { surface: label, summary: unresolvedRunnerSummary() };
125
- }
126
- return {
127
- surface: runner.bin,
128
- summary: parseLintOutput(runnerFn(runner.bin, buildArgs(runner), cwd)),
129
- };
130
- }
131
-
132
- /**
133
- * @param {string[]} changedFiles
134
- * @returns {{ code: string[], md: string[] }}
135
- */
136
- export function partitionFilesForLint(changedFiles) {
137
- const code = [];
138
- const md = [];
139
- for (const f of changedFiles) {
140
- if (CODE_EXTENSIONS.test(f)) code.push(f);
141
- else if (/\.md$/i.test(f)) md.push(f);
142
- }
143
- return { code, md };
144
- }
145
-
146
- /**
147
- * A non-zero exit matching no reporter format is `executionFailed`, except
148
- * biome's empty-scope exit.
149
- *
150
- * @param {{ status?: number, stdout?: string, stderr?: string }} result
151
- * @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean, emptyScope: boolean, reason: string|null }}
152
- */
153
- export function parseLintOutput(result) {
154
- const combined = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
155
-
156
- let errors = 0;
157
- let warnings = 0;
158
- let parsed = false;
159
-
160
- for (const m of combined.matchAll(/Found\s+(\d+)\s+error/gi)) {
161
- errors += Number(m[1]);
162
- parsed = true;
163
- }
164
- for (const m of combined.matchAll(/Found\s+(\d+)\s+warning/gi)) {
165
- warnings += Number(m[1]);
166
- parsed = true;
167
- }
168
- const mdSummary = combined.match(/Summary:\s+(\d+)\s+error/i);
169
- if (mdSummary) {
170
- errors += Number(mdSummary[1]);
171
- parsed = true;
172
- }
173
-
174
- const failedExit = !parsed && (result.status ?? 0) !== 0;
175
- const emptyScope = failedExit && BIOME_EMPTY_SCOPE.test(combined);
176
- const executionFailed = failedExit && !emptyScope;
177
- const reason = executionFailed
178
- ? NPX_UNRESOLVABLE.test(combined)
179
- ? DEGRADATION_REASONS.RUNNER_NOT_RESOLVABLE
180
- : DEGRADATION_REASONS.UNPARSEABLE_OUTPUT
181
- : null;
182
-
183
- return { errors, warnings, parsed, executionFailed, emptyScope, reason };
184
- }
185
-
186
- /**
187
- * Counts add and `executionFailed` is the OR; `surfaces[]` keeps what the
188
- * lossy OR cannot answer.
189
- *
190
- * @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
191
- */
192
- function mergeSurfaceSummaries(surfaces) {
193
- const rows = surfaces.map(({ surface, summary }) => ({
194
- surface,
195
- parsed: summary.parsed,
196
- errors: summary.errors,
197
- warnings: summary.warnings,
198
- executionFailed: summary.executionFailed,
199
- reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
200
- }));
201
- const total = (field) => rows.reduce((sum, row) => sum + row[field], 0);
202
-
203
- return {
204
- errors: total('errors'),
205
- warnings: total('warnings'),
206
- parsed: rows.some((row) => row.parsed),
207
- executionFailed: rows.some((row) => row.executionFailed),
208
- skipped: false,
209
- mode: 'changed-only',
210
- degradations: rows
211
- .filter((row) => row.executionFailed)
212
- .map(({ surface, reason }) => ({ surface, reason })),
213
- surfaces: rows.map(({ reason, ...row }) => row),
214
- };
215
- }
216
-
217
- /**
218
- * @param {string[]} changedFiles
219
- * @param {string} cwd
220
- * @param {typeof spawnLintRunner} [runnerFn]
221
- * @param {{ existsFn?: (p: string) => boolean }} [deps]
222
- * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }>, surfaces: Array<{ surface: string, parsed: boolean, errors: number, warnings: number, executionFailed: boolean }> }}
223
- */
224
- export function runScopedLint(
225
- changedFiles,
226
- cwd,
227
- runnerFn = spawnLintRunner,
228
- deps = {},
229
- ) {
230
- const { existsFn = existsSync } = deps;
231
- const { code, md } = partitionFilesForLint(changedFiles);
232
- if (code.length === 0 && md.length === 0) {
233
- return {
234
- errors: 0,
235
- warnings: 0,
236
- parsed: false,
237
- skipped: true,
238
- mode: 'changed-only',
239
- executionFailed: false,
240
- degradations: [],
241
- surfaces: [],
242
- };
243
- }
244
-
245
- const surfaces = [];
246
- if (code.length > 0) {
247
- surfaces.push(
248
- runSurface({
249
- label: 'biome',
250
- candidates: CODE_RUNNERS,
251
- buildArgs: (runner) => ['lint', ...code, ...runner.extraArgs],
252
- cwd,
253
- runnerFn,
254
- existsFn,
255
- }),
256
- );
257
- }
258
- if (md.length > 0) {
259
- surfaces.push(
260
- runSurface({
261
- label: 'markdownlint',
262
- candidates: MARKDOWN_RUNNERS,
263
- buildArgs: (runner) => [...md, ...runner.extraArgs],
264
- cwd,
265
- runnerFn,
266
- existsFn,
267
- }),
268
- );
269
- }
270
-
271
- return mergeSurfaceSummaries(surfaces);
272
- }