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
@@ -4,7 +4,10 @@
4
4
  * `{ path, assumption }` (probed at base: present → `refactors-existing`,
5
5
  * absent → `creates`), and a trailing parenthetical on a path is stripped.
6
6
  * Repairs are reported, not refused; an unsalvageable string is left for the
7
- * validator. Kept apart from the validator, whose collectors are pure.
7
+ * validator. A bare `references[]` entry naming a path present at base is
8
+ * derived as a read (`exists`); an absent one stays bare for the
9
+ * file-assumption probe to warn on. Kept apart from the validator, whose
10
+ * collectors are pure.
8
11
  *
9
12
  * @module lib/orchestration/plan-persist/changes-repair
10
13
  */
@@ -14,6 +17,8 @@ import { FILE_ASSUMPTION_VALUES } from '../file-assumption-enum.js';
14
17
 
15
18
  const CHANGES_HEADING_RE = /^#{2,3}\s+Changes\s*$/i;
16
19
 
20
+ const REFERENCES_HEADING_RE = /^#{2,3}\s+References\s*$/i;
21
+
17
22
  const ANY_HEADING_RE = /^#{1,6}\s+\S/;
18
23
 
19
24
  const TRAILING_PARENTHETICAL_RE = /\s*\([^)]*\)\s*$/;
@@ -150,7 +155,64 @@ function repairSectionLine(line, existsAtBase) {
150
155
  }
151
156
 
152
157
  /**
153
- * Touches only the `## Changes` section; the rest stays byte-identical.
158
+ * A bare reference present at base becomes `exists`; anything else is left.
159
+ *
160
+ * @param {unknown} item
161
+ * @param {(path: string) => boolean} existsAtBase
162
+ * @returns {{ entry: { path: string, assumption: 'exists' }, repair: object }|null}
163
+ */
164
+ function deriveReferenceItem(item, existsAtBase) {
165
+ const raw = typeof item === 'string' ? item : null;
166
+ const bareObject =
167
+ item !== null &&
168
+ typeof item === 'object' &&
169
+ item.assumption == null &&
170
+ typeof item.path === 'string';
171
+ const from = raw ?? (bareObject ? item.path : null);
172
+ if (from === null) return null;
173
+ const path = salvagePath(from);
174
+ if (path === null || !existsAtBase(path)) return null;
175
+ return {
176
+ entry: { path, assumption: 'exists' },
177
+ repair: {
178
+ field: 'references',
179
+ from,
180
+ path,
181
+ assumption: 'exists',
182
+ reason: 'derived-read',
183
+ },
184
+ };
185
+ }
186
+
187
+ /**
188
+ * @param {string} line
189
+ * @param {(path: string) => boolean} existsAtBase
190
+ * @returns {{ line: string, repair: object }|null}
191
+ */
192
+ function deriveReferenceLine(line, existsAtBase) {
193
+ const marker = line.match(/^(\s*[-*]\s+)/);
194
+ if (!marker) return null;
195
+ const content = line.slice(marker[1].length).trim();
196
+ if (content === '' || HUMANIZED_RE.test(content) || content.startsWith('{')) {
197
+ return null;
198
+ }
199
+ const derived = deriveReferenceItem(content, existsAtBase);
200
+ if (derived === null) return null;
201
+ return {
202
+ line: `${marker[1]}\`${derived.entry.path}\` — exists`,
203
+ repair: derived.repair,
204
+ };
205
+ }
206
+
207
+ /** Section repairers for the serialized body, keyed by heading. */
208
+ const SECTION_REPAIRERS = [
209
+ { heading: CHANGES_HEADING_RE, repairLine: repairSectionLine },
210
+ { heading: REFERENCES_HEADING_RE, repairLine: deriveReferenceLine },
211
+ ];
212
+
213
+ /**
214
+ * Touches only the `## Changes` / `## References` sections; the rest stays
215
+ * byte-identical.
154
216
  *
155
217
  * @param {string} body
156
218
  * @param {(path: string) => boolean} existsAtBase
@@ -159,19 +221,20 @@ function repairSectionLine(line, existsAtBase) {
159
221
  function repairSerializedBody(body, existsAtBase) {
160
222
  const lines = body.split('\n');
161
223
  const repairs = [];
162
- let inChanges = false;
224
+ let repairer = null;
163
225
  for (let i = 0; i < lines.length; i += 1) {
164
226
  const line = lines[i];
165
- if (CHANGES_HEADING_RE.test(line.trim())) {
166
- inChanges = true;
227
+ const opened = SECTION_REPAIRERS.find((r) => r.heading.test(line.trim()));
228
+ if (opened) {
229
+ repairer = opened;
167
230
  continue;
168
231
  }
169
- if (!inChanges) continue;
232
+ if (repairer === null) continue;
170
233
  if (ANY_HEADING_RE.test(line) || line.trim().startsWith('---')) {
171
- inChanges = false;
234
+ repairer = null;
172
235
  continue;
173
236
  }
174
- const repaired = repairSectionLine(line, existsAtBase);
237
+ const repaired = repairer.repairLine(line, existsAtBase);
175
238
  if (repaired === null) continue;
176
239
  lines[i] = repaired.line;
177
240
  repairs.push(repaired.repair);
@@ -179,6 +242,38 @@ function repairSerializedBody(body, existsAtBase) {
179
242
  return { body: lines.join('\n'), repairs };
180
243
  }
181
244
 
245
+ /**
246
+ * @param {unknown[]|null} list Mutated in place.
247
+ * @param {(item: unknown) => ({ entry: object, repair: object }|null)} repairItem
248
+ * @returns {object[]}
249
+ */
250
+ function repairList(list, repairItem) {
251
+ if (list === null) return [];
252
+ const repairs = [];
253
+ for (let i = 0; i < list.length; i += 1) {
254
+ const repaired = repairItem(list[i]);
255
+ if (repaired === null) continue;
256
+ list[i] = repaired.entry;
257
+ repairs.push(repaired.repair);
258
+ }
259
+ return repairs;
260
+ }
261
+
262
+ /**
263
+ * The body's own array when it has one, else the top-level field.
264
+ *
265
+ * @param {object} ticket
266
+ * @param {'changes'|'references'} field
267
+ * @returns {unknown[]|null}
268
+ */
269
+ function structuredList(ticket, field) {
270
+ const body = ticket.body;
271
+ if (body && typeof body === 'object' && Array.isArray(body[field])) {
272
+ return body[field];
273
+ }
274
+ return Array.isArray(ticket[field]) ? ticket[field] : null;
275
+ }
276
+
182
277
  /**
183
278
  * @param {object} ticket Mutated in place.
184
279
  * @param {(path: string) => boolean} existsAtBase
@@ -191,28 +286,39 @@ function repairTicket(ticket, existsAtBase) {
191
286
  if (repairs.length > 0) ticket.body = next;
192
287
  return repairs;
193
288
  }
194
- const changes =
195
- body && typeof body === 'object' && Array.isArray(body.changes)
196
- ? body.changes
197
- : Array.isArray(ticket.changes)
198
- ? ticket.changes
199
- : null;
200
- if (changes === null) return [];
201
- const repairs = [];
202
- for (let i = 0; i < changes.length; i += 1) {
203
- const repaired = repairStructuredItem(changes[i], existsAtBase);
204
- if (repaired === null) continue;
205
- changes[i] = repaired.entry;
206
- repairs.push(repaired.repair);
207
- }
208
- return repairs;
289
+ return [
290
+ ...repairList(structuredList(ticket, 'changes'), (item) =>
291
+ repairStructuredItem(item, existsAtBase),
292
+ ),
293
+ ...repairList(structuredList(ticket, 'references'), (item) =>
294
+ deriveReferenceItem(item, existsAtBase),
295
+ ),
296
+ ];
297
+ }
298
+
299
+ /**
300
+ * @param {{ slug: string, from: string, path: string, assumption: string, reason: string }} repair
301
+ * @returns {string}
302
+ */
303
+ export function renderChangeRepair(repair) {
304
+ return repair.reason === 'derived-read'
305
+ ? renderDerivedRead(repair)
306
+ : renderPathRepair(repair);
307
+ }
308
+
309
+ /**
310
+ * @param {{ slug: string, from: string, path: string }} repair
311
+ * @returns {string}
312
+ */
313
+ function renderDerivedRead({ slug, from, path }) {
314
+ return `Story "${slug}": references[] entry "${from}" derived as a read of an existing path — {"path":"${path}","assumption":"exists"} by probing base.`;
209
315
  }
210
316
 
211
317
  /**
212
318
  * @param {{ slug: string, from: string, path: string, assumption: string, reason: string }} repair
213
319
  * @returns {string}
214
320
  */
215
- export function renderChangeRepair({ slug, from, path, assumption, reason }) {
321
+ function renderPathRepair({ slug, from, path, assumption, reason }) {
216
322
  const why =
217
323
  reason === 'plain-string'
218
324
  ? 'plain-string bullet'
@@ -33,7 +33,7 @@ import {
33
33
  } from '../ticket-validator-conflicts.js';
34
34
  import { upsertStructuredComment } from '../ticketing.js';
35
35
  import { renderRepair } from './acceptance-handle-repair.js';
36
- import { recordAuditFilings, withAuditLabels } from './audit-provenance.js';
36
+ import { resolveSeedProvenance, withAuditLabels } from './audit-provenance.js';
37
37
  import {
38
38
  resolveContainerEpic,
39
39
  resolveCrossPlanLinks,
@@ -310,10 +310,11 @@ async function enforceReachability(reachability, config) {
310
310
  * @param {object} args
311
311
  * @returns {Promise<void>}
312
312
  */
313
- async function persistStoryArtifacts({ provider, created, summaryBody }) {
313
+ async function persistStoryArtifacts({ provider, created, summaryFor }) {
314
314
  await concurrentMap(
315
315
  created,
316
- (story) => writePlanSummaryComment(provider, story.id, summaryBody),
316
+ (story) =>
317
+ writePlanSummaryComment(provider, story.id, summaryFor(story.id)),
317
318
  { concurrency: FANOUT_CONCURRENCY },
318
319
  );
319
320
  await markStoriesReady({ provider, created });
@@ -423,6 +424,8 @@ export async function runPlanPersist({
423
424
  const runStartedAt = opts.metricsSince ?? new Date().toISOString();
424
425
 
425
426
  assertPersistablePlan(rawStories);
427
+ // Before any write: a truncated seed that lost its footers refuses here.
428
+ const seedProvenance = resolveSeedProvenance(planContextEnvelope);
426
429
 
427
430
  Logger.info(
428
431
  `[plan-persist] Running cross-validation on ${rawStories.length} Story ticket(s)...`,
@@ -451,14 +454,13 @@ export async function runPlanPersist({
451
454
  epicId: opts.adoptEpicId ?? null,
452
455
  });
453
456
 
454
- const seedContent = planContextEnvelope?.seed?.content ?? '';
455
457
  const { stories: assembled, warnings: supersedeWarnings } =
456
458
  assemblePlanStories(rawStories, {
457
459
  sharedSpec: techSpecContent,
458
460
  sourceTicketIds,
459
461
  // Audit footers carried onto every Story that did not attribute its own
460
462
  // `provenance`; empty for a `--tickets` run.
461
- provenanceSource: seedContent,
463
+ provenanceSource: seedProvenance,
462
464
  });
463
465
 
464
466
  warnings.push(...supersedeWarnings);
@@ -466,7 +468,7 @@ export async function runPlanPersist({
466
468
 
467
469
  // The dedup corpus is listed by `audit::*` label; footers alone leave the
468
470
  // Story invisible to an indexed sweep.
469
- const stories = withAuditLabels(assembled, seedContent);
471
+ const stories = withAuditLabels(assembled, seedProvenance);
470
472
 
471
473
  const assembledConflicts = analyzeAssembledStories({
472
474
  stories,
@@ -496,8 +498,6 @@ export async function runPlanPersist({
496
498
  opts: { dryRun },
497
499
  });
498
500
 
499
- recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
500
-
501
501
  const primary = created[0];
502
502
 
503
503
  const planMetricsLine = await renderRunScopedPlanMetricsLine({
@@ -507,22 +507,24 @@ export async function runPlanPersist({
507
507
  mode: dryRun ? 'dry-run' : 'persist',
508
508
  });
509
509
 
510
- const summaryBody = buildPlanSummaryCommentBody({
511
- epicId: primary.id,
512
- ticketCount: created.length,
513
- forceReview,
514
- freshness,
515
- healthcheck: { skipped: true },
516
- waveTable,
517
- mode: 'stories',
518
- planMetricsLine,
519
- stories: created,
520
- conflictFindings: assembledConflicts,
521
- waveCollisions,
522
- });
510
+ // Each Story's comment heading names that Story.
511
+ const summaryFor = (storyId) =>
512
+ buildPlanSummaryCommentBody({
513
+ storyId,
514
+ ticketCount: created.length,
515
+ forceReview,
516
+ freshness,
517
+ healthcheck: { skipped: true },
518
+ waveTable,
519
+ mode: 'stories',
520
+ planMetricsLine,
521
+ stories: created,
522
+ conflictFindings: assembledConflicts,
523
+ waveCollisions,
524
+ });
523
525
 
524
526
  if (!dryRun) {
525
- await persistStoryArtifacts({ provider, created, summaryBody });
527
+ await persistStoryArtifacts({ provider, created, summaryFor });
526
528
  }
527
529
 
528
530
  // Last among the writes: the Epic needs the children's numbers and database
@@ -202,6 +202,7 @@ function bodyObjectFromTicket(ticket) {
202
202
  goal: ticket.goal ?? '',
203
203
  slicing: ticket.slicing ?? '',
204
204
  spec: ticket.spec ?? '',
205
+ context: ticket.context ?? '',
205
206
  changes: ticket.changes ?? [],
206
207
  acceptance: ticket.acceptance ?? [],
207
208
  verify: ticket.verify ?? [],
@@ -89,11 +89,12 @@ function renderSharedEditorLines(conflictFindings) {
89
89
  }
90
90
 
91
91
  /**
92
- * @param {object} input
92
+ * @param {object} input `storyId` is the Story the comment is posted on; its
93
+ * heading names that Story, never a sibling.
93
94
  * @returns {string}
94
95
  */
95
96
  export function buildPlanSummaryCommentBody({
96
- epicId,
97
+ storyId,
97
98
  ticketCount,
98
99
  forceReview = false,
99
100
  freshness,
@@ -139,7 +140,7 @@ export function buildPlanSummaryCommentBody({
139
140
  : '/mandrel-deliver <storyId> [<storyId> ...]';
140
141
 
141
142
  return [
142
- `#### 📋 Plan Summary — Story #${epicId} is \`agent::ready\``,
143
+ `#### 📋 Plan Summary — Story #${storyId} is \`agent::ready\``,
143
144
  '',
144
145
  `- ${ticketCount} Story ticket(s) persisted: ${storyList}.`,
145
146
  ...reviewLines,
@@ -7,7 +7,7 @@
7
7
  */
8
8
 
9
9
  import { extractEpicIdFromBody, parseBlockedBy } from '../dependency-parser.js';
10
- import { TYPE_LABELS } from '../label-constants.js';
10
+ import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
11
11
  import { buildStoryAdjacency } from '../story-adjacency.js';
12
12
  import {
13
13
  extractChangePaths,
@@ -83,13 +83,21 @@ export function toStoryRecord(issue, requestedId, { allowUnlabelled } = {}) {
83
83
  }
84
84
 
85
85
  /**
86
- * Refuse an unplanned Story (audit sweeps file them unlabelled on purpose).
86
+ * Refuse a Story still awaiting planning (`agent::review-spec`, which the
87
+ * issue form applies) or an unplanned one (audit sweeps file them unlabelled
88
+ * on purpose).
87
89
  *
88
90
  * @param {number} id
89
91
  * @param {string[]} labels
90
92
  * @param {boolean} [allowUnlabelled]
91
93
  */
92
94
  function assertDispatchable(id, labels, allowUnlabelled) {
95
+ if (labels.includes(AGENT_LABELS.REVIEW_SPEC)) {
96
+ throw new Error(
97
+ `[resolve-stories] Story #${id} is labelled ${AGENT_LABELS.REVIEW_SPEC}, so it is awaiting ` +
98
+ `planning before delivery. Run /mandrel-plan ${id} first, which applies agent::ready.`,
99
+ );
100
+ }
93
101
  if (allowUnlabelled) return;
94
102
  if (labels.some((l) => l.startsWith(AGENT_LABEL_PREFIX))) return;
95
103
  throw new Error(
@@ -1,7 +1,8 @@
1
1
  /**
2
- * review-providers/native.js — in-process ReviewProvider: scoped lint plus
3
- * maintainability scoring of the changed files. MI honours the gate's
4
- * exemptions (lint has its own); `input.depth` is ignored by design.
2
+ * review-providers/native.js — in-process ReviewProvider: maintainability
3
+ * scoring of the changed files, honouring the gate's exemptions. It runs no
4
+ * lint — lint is a close-validation gate the worker's preflight also runs.
5
+ * `input.depth` is ignored by design.
5
6
  *
6
7
  * @typedef {import('./types.js').Finding} Finding
7
8
  * @typedef {import('./types.js').ReviewInput} ReviewInput
@@ -15,23 +16,12 @@ import {
15
16
  calculateReport,
16
17
  classifyReport,
17
18
  } from '../../maintainability-engine.js';
18
- import {
19
- emitRuntimeFriction,
20
- RUNTIME_FRICTION_CATEGORIES,
21
- } from '../../observability/runtime-friction.js';
22
19
  import { PROJECT_ROOT } from '../../project-root.js';
23
20
  import { transpileIfNeeded } from '../../transpile.js';
24
21
  import {
25
22
  resolveMaintainabilityIgnoreGlobs,
26
23
  scopeMaintainabilityFiles,
27
24
  } from './mi-exemptions.js';
28
- import {
29
- parseLintOutput,
30
- partitionFilesForLint,
31
- runScopedLint,
32
- } from './scoped-lint.js';
33
-
34
- export { parseLintOutput, partitionFilesForLint, runScopedLint };
35
25
 
36
26
  const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
37
27
  '../../workers/maintainability-report-worker.js',
@@ -244,138 +234,29 @@ export async function analyzeChangedFiles(
244
234
  return results;
245
235
  }
246
236
 
247
- /**
248
- * Findings come from parsed counts, never `executionFailed` (an OR across
249
- * surfaces), so one absent runner cannot discard the other's errors.
250
- *
251
- * @param {{ errors: number, warnings: number, parsed?: boolean, skipped?: boolean, mode?: string, executionFailed?: boolean, evidenceSkipped?: boolean }} lintSummary
252
- * @returns {Finding[]}
253
- */
254
- export function buildLintFindings(lintSummary) {
255
- if (lintSummary.mode === 'off') return [];
256
- if (lintSummary.evidenceSkipped) return [];
257
- if (lintSummary.skipped) return [];
258
- if (lintSummary.parsed === false) return [];
259
- const findings = [];
260
- if (lintSummary.errors > 0) {
261
- findings.push({
262
- severity: 'high',
263
- title: `Lint check failed (${lintSummary.errors} error(s))`,
264
- body:
265
- `Scoped lint reported ${lintSummary.errors} error(s) and ` +
266
- `${lintSummary.warnings} warning(s) on the changed surface. ` +
267
- 'Fix errors before merging.',
268
- category: 'lint',
269
- });
270
- } else if (lintSummary.warnings > 0) {
271
- findings.push({
272
- severity: 'suggestion',
273
- title: `Lint check passed with ${lintSummary.warnings} warning(s)`,
274
- body:
275
- `Scoped lint reported ${lintSummary.warnings} warning(s) on the ` +
276
- 'changed surface. Treat as suggestions.',
277
- category: 'lint',
278
- });
279
- }
280
- return findings;
281
- }
282
-
283
- async function runLintPhase({
284
- scopeLint,
285
- changedFiles,
286
- runScopedLintFn,
287
- logger,
288
- }) {
289
- if (scopeLint === 'off') {
290
- logger?.info?.(
291
- '[native-review] Lint scoped off (scopeLint=off); skipping.',
292
- );
293
- return {
294
- errors: 0,
295
- warnings: 0,
296
- parsed: false,
297
- skipped: true,
298
- mode: 'off',
299
- executionFailed: false,
300
- degradations: [],
301
- surfaces: [],
302
- };
303
- }
304
- logger?.info?.(
305
- '[native-review] Linting changed files only (biome + markdownlint, scoped to diff)...',
306
- );
307
- return runScopedLintFn(changedFiles, PROJECT_ROOT);
308
- }
309
-
310
- /**
311
- * Degradation records for an `executionFailed` summary; one without
312
- * per-surface rows degrades to a single gate-wide record, never silence.
313
- *
314
- * @param {{ executionFailed?: boolean, degradations?: Array<{ surface: string, reason: string }> }} lintSummary
315
- * @returns {Array<{ tool: string, gate: string, surface: string, reason: string }>}
316
- */
317
- function buildLintDegradations(lintSummary) {
318
- if (!lintSummary.executionFailed) return [];
319
- const rows = Array.isArray(lintSummary.degradations)
320
- ? lintSummary.degradations
321
- : [];
322
- const surfaces =
323
- rows.length > 0
324
- ? rows
325
- : [{ surface: 'scoped-lint', reason: 'unparseable-output' }];
326
- return surfaces.map((row) => ({
327
- tool: 'native-review-lint',
328
- gate: 'scoped-lint',
329
- surface: row.surface,
330
- reason: row.reason,
331
- }));
332
- }
333
-
334
237
  /**
335
238
  * @param {{
336
239
  * gitSpawnFn?: typeof gitSpawn,
337
- * runScopedLintFn?: typeof runScopedLint,
338
240
  * analyzeChangedFilesFn?: typeof analyzeChangedFiles,
339
- * buildLintFindingsFn?: typeof buildLintFindings,
340
- * emitToolDegradationFn?: typeof emitRuntimeFriction,
341
241
  * resolveIgnoreGlobsFn?: typeof resolveMaintainabilityIgnoreGlobs,
342
242
  * logger?: { info?: Function, warn?: Function, error?: Function },
343
- * scopeLint?: 'changed-only'|'off',
344
243
  * }} [deps]
345
244
  * @returns {ReviewProvider}
346
245
  */
347
246
  export function createNativeProvider(deps = {}) {
348
247
  const {
349
248
  gitSpawnFn = gitSpawn,
350
- runScopedLintFn = runScopedLint,
351
249
  analyzeChangedFilesFn = analyzeChangedFiles,
352
- buildLintFindingsFn = buildLintFindings,
353
- emitToolDegradationFn = emitRuntimeFriction,
354
250
  resolveIgnoreGlobsFn = resolveMaintainabilityIgnoreGlobs,
355
251
  logger,
356
- scopeLint = 'changed-only',
357
252
  } = deps;
358
253
 
359
- /**
360
- * Degradations from the latest `runReview`, travelling beside findings.
361
- *
362
- * @type {Array<{ tool: string, gate: string, surface: string, reason: string }>}
363
- */
364
- let recordedDegradations = [];
365
-
366
254
  return {
367
- /**
368
- * @returns {Array<{ tool: string, gate: string, surface: string, reason: string }>}
369
- */
370
- getDegradations() {
371
- return recordedDegradations;
372
- },
373
255
  /**
374
256
  * @param {ReviewInput} input
375
257
  * @returns {Promise<Finding[]>}
376
258
  */
377
259
  async runReview(input) {
378
- recordedDegradations = [];
379
260
  const { scope, ticketId, baseRef, headRef } = input ?? {};
380
261
  if (!baseRef || !headRef) {
381
262
  throw new TypeError(
@@ -427,49 +308,8 @@ export function createNativeProvider(deps = {}) {
427
308
  gitSpawnFn,
428
309
  });
429
310
 
430
- const lintSummary = await runLintPhase({
431
- scopeLint,
432
- changedFiles,
433
- runScopedLintFn,
434
- logger,
435
- });
436
-
437
- if (lintSummary.executionFailed) {
438
- // A tool that could not execute is a degradation, recorded on the
439
- // outcome and in friction telemetry — never a finding.
440
- recordedDegradations = buildLintDegradations(lintSummary);
441
- logger?.warn?.(
442
- `[native-review] Lint runner could not execute (${recordedDegradations
443
- .map((d) => `${d.surface}: ${d.reason}`)
444
- .join(
445
- '; ',
446
- )}) — reported as a degraded gate on the review outcome and recorded as friction telemetry; the degradation itself is never a finding, and any surface that did run still reports its own errors. Verify with the canonical \`npm run lint\` before merging.`,
447
- );
448
- try {
449
- await emitToolDegradationFn({
450
- storyId: ticketId,
451
- category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
452
- tool: 'native-review-lint',
453
- details: {
454
- surface: 'scoped-lint',
455
- reason:
456
- 'lint runner produced no parseable output (binary missing, parse failure, or environment issue)',
457
- },
458
- });
459
- } catch {
460
- // Observability must never fail the review.
461
- }
462
- }
463
-
464
- const lintFindings = buildLintFindingsFn(lintSummary);
465
-
466
311
  // Severity order; only matters for fixture stability.
467
- return [
468
- ...results.criticalFindings,
469
- ...lintFindings.filter((f) => f.severity === 'high'),
470
- ...results.mediumFindings,
471
- ...lintFindings.filter((f) => f.severity === 'suggestion'),
472
- ];
312
+ return [...results.criticalFindings, ...results.mediumFindings];
473
313
  },
474
314
  };
475
315
  }
@@ -82,10 +82,22 @@ export function gatesForFailedPhase(phase, args = {}) {
82
82
  return { ...gates, ...baselinesGatesObserved(args.observedGates) };
83
83
  }
84
84
 
85
+ /**
86
+ * @param {unknown} err
87
+ * @param {number} storyId
88
+ * @returns {string}
89
+ */
90
+ function nextCommandFor(err, storyId) {
91
+ const tagged = err?.closeNextCommand;
92
+ return typeof tagged === 'string' ? tagged : NEXT_COMMANDS.recover(storyId);
93
+ }
94
+
85
95
  /**
86
96
  * Never throws: a build failure here must not replace the original error as
87
97
  * the run's reported cause, so it returns null and the caller rethrows.
88
- * `err.closePhase` and `err.closeGates` are tagged by the runner.
98
+ * `err.closePhase` and `err.closeGates` are tagged by the runner; a phase
99
+ * that knows its own resume (a handed-back base-sync conflict re-runs close)
100
+ * tags `err.closeNextCommand`.
89
101
  *
90
102
  * @param {unknown} err
91
103
  * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
@@ -105,7 +117,7 @@ export function failedTerminalFor(err, args = {}) {
105
117
  observedGates: err?.closeGates ?? null,
106
118
  }),
107
119
  failure: { reason: String(err?.message ?? err) },
108
- nextCommand: NEXT_COMMANDS.recover(storyId),
120
+ nextCommand: nextCommandFor(err, storyId),
109
121
  elapsedSeconds: 0,
110
122
  phaseDurations: err?.closePhaseDurations ?? undefined,
111
123
  });