mandrel 2.100.0 → 2.102.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.
- package/.agents/agents/story-worker.md +7 -1
- package/.agents/audit-checklists/resilience.md +40 -0
- package/.agents/audit-checklists/sre.md +2 -4
- package/.agents/docs/agentrc-reference.json +3 -0
- package/.agents/docs/configuration.md +3 -0
- package/.agents/docs/workflows.md +2 -1
- package/.agents/rules/ci-remediation.md +8 -0
- package/.agents/schemas/agentrc.schema.json +26 -0
- package/.agents/schemas/audit-rules.json +44 -2
- package/.agents/schemas/audit-rules.schema.json +2 -2
- package/.agents/schemas/story-deliver-terminal.schema.json +17 -3
- package/.agents/schemas/validation-evidence.schema.json +10 -0
- package/.agents/scripts/lib/audit-suite/selector.js +80 -1
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/close-lock-events.js +18 -5
- package/.agents/scripts/lib/close-validation/gates.js +6 -1
- package/.agents/scripts/lib/close-validation/runner.js +10 -11
- package/.agents/scripts/lib/close-validation/test-delta.js +124 -0
- package/.agents/scripts/lib/config/pull-request.js +25 -0
- package/.agents/scripts/lib/config-settings-schema-delivery.js +22 -0
- package/.agents/scripts/lib/config-settings-schema.js +5 -0
- package/.agents/scripts/lib/coverage-capture-delta.js +2 -1
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/git/sync-from-base.js +4 -2
- package/.agents/scripts/lib/orchestration/ci-red-handling.js +4 -3
- package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +81 -25
- package/.agents/scripts/lib/orchestration/handoff-state.js +41 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +97 -28
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +22 -4
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +104 -57
- package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +16 -16
- package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +28 -13
- package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pr-body-trailers.js +38 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +24 -16
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +18 -7
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +60 -34
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +1 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +36 -9
- package/.agents/scripts/lib/test-run-credit.js +26 -0
- package/.agents/scripts/lib/validation-evidence.js +6 -0
- package/.agents/workflows/audit-resilience.md +290 -0
- package/.agents/workflows/audit-sre.md +12 -21
- package/.agents/workflows/helpers/deliver-reference.md +28 -1
- package/docs/CHANGELOG.md +25 -0
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
|
+
import { sourcedTimings } from '../../close-lock-events.js';
|
|
1
2
|
import { buildDefaultGates } from '../../close-validation/gates.js';
|
|
2
3
|
import { runCloseValidation } from '../../close-validation/runner.js';
|
|
3
4
|
import { getCiDelivery } from '../../config/ci.js';
|
|
4
|
-
import { resolveWorktreeEnabled } from '../../config/runtime.js';
|
|
5
5
|
import { resolveConfig } from '../../config-resolver.js';
|
|
6
6
|
import { gh as defaultGh } from '../../gh-exec.js';
|
|
7
7
|
import { getStoryBranch, gitSpawn, gitSync } from '../../git-utils.js';
|
|
@@ -15,6 +15,7 @@ import { createProvider } from '../../provider-factory.js';
|
|
|
15
15
|
import { flipLabelAndNotify } from '../../single-story/story-merged-notify.js';
|
|
16
16
|
import { WorktreeManager } from '../../worktree-manager.js';
|
|
17
17
|
import { runCodeReview as runCodeReviewDefault } from '../code-review.js';
|
|
18
|
+
import { readCreditTimings } from '../handoff-state.js';
|
|
18
19
|
import { resolveOperatorFromCandidates } from '../lease-guard-shared.js';
|
|
19
20
|
import { resolveRunScopedConfig } from '../run-scoped-config.js';
|
|
20
21
|
import {
|
|
@@ -38,10 +39,7 @@ import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
|
|
|
38
39
|
import { runPrePushPhases } from './phases/pre-push.js';
|
|
39
40
|
import { pickHeadPullRequest } from './phases/pull-request.js';
|
|
40
41
|
import { reconcileDoneLabel } from './phases/reconcile-done.js';
|
|
41
|
-
import {
|
|
42
|
-
existingWorktreePath,
|
|
43
|
-
resolveStoryWorktree,
|
|
44
|
-
} from './phases/worktree-restore.js';
|
|
42
|
+
import { resolveStoryWorktree } from './phases/worktree-restore.js';
|
|
45
43
|
import {
|
|
46
44
|
alreadyClosedResult,
|
|
47
45
|
closeEnvelopeGates,
|
|
@@ -260,16 +258,28 @@ async function resolveBasePhase(ctx, deps) {
|
|
|
260
258
|
return null;
|
|
261
259
|
}
|
|
262
260
|
|
|
261
|
+
/** First SHA of a `show-ref` / `ls-remote` line; `''` on an empty read. */
|
|
262
|
+
function firstSha(stdout) {
|
|
263
|
+
return String(stdout ?? '')
|
|
264
|
+
.trim()
|
|
265
|
+
.split(/\s+/)[0];
|
|
266
|
+
}
|
|
267
|
+
|
|
263
268
|
/**
|
|
264
|
-
*
|
|
265
|
-
*
|
|
266
|
-
*
|
|
269
|
+
* Tip SHAs of the surviving story refs (local, then origin). Only
|
|
270
|
+
* `ls-remote`'s "no such ref" (exit 2) proves the remote gone; any other
|
|
271
|
+
* failure yields `''`, which matches no PR head.
|
|
267
272
|
*/
|
|
268
|
-
function
|
|
273
|
+
function survivingStoryHeads(ctx) {
|
|
269
274
|
const cwd = ctx.options.cwd;
|
|
270
|
-
const
|
|
271
|
-
const local = gitSpawn(
|
|
272
|
-
|
|
275
|
+
const heads = [];
|
|
276
|
+
const local = gitSpawn(
|
|
277
|
+
cwd,
|
|
278
|
+
'show-ref',
|
|
279
|
+
'--verify',
|
|
280
|
+
`refs/heads/${ctx.storyBranch}`,
|
|
281
|
+
);
|
|
282
|
+
if (local.status === 0) heads.push(firstSha(local.stdout));
|
|
273
283
|
const remote = gitSpawn(
|
|
274
284
|
cwd,
|
|
275
285
|
'ls-remote',
|
|
@@ -278,28 +288,38 @@ function storyBranchSurvives(ctx) {
|
|
|
278
288
|
'origin',
|
|
279
289
|
ctx.storyBranch,
|
|
280
290
|
);
|
|
281
|
-
|
|
291
|
+
if (remote.status !== 2)
|
|
292
|
+
heads.push(remote.status === 0 ? firstSha(remote.stdout) : '');
|
|
293
|
+
return heads;
|
|
282
294
|
}
|
|
283
295
|
|
|
284
296
|
/**
|
|
285
|
-
* The Story's PR, when it already merged and nothing newer is in flight
|
|
286
|
-
*
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
* Any read failure reads as "not merged"
|
|
297
|
+
* The Story's PR, when it already merged and nothing newer is in flight. A
|
|
298
|
+
* surviving branch is not evidence of unlanded work (the land tail's reap may
|
|
299
|
+
* be pending or failed), but a surviving tip past the merged PR's head is: it
|
|
300
|
+
* takes the normal path. An OPEN PR on the head wins (a re-delivery), as
|
|
301
|
+
* `ensurePullRequestWith` decides. Any read failure reads as "not merged".
|
|
290
302
|
*
|
|
291
|
-
* @returns {Promise<{ prUrl: string, prNumber: number|null }|null>}
|
|
303
|
+
* @returns {Promise<{ prUrl: string, prNumber: number|null, mergedAt: string }|null>}
|
|
292
304
|
*/
|
|
293
305
|
async function findLandedPr(ctx, deps) {
|
|
294
|
-
if (storyBranchSurvives(ctx)) return null;
|
|
295
306
|
try {
|
|
296
307
|
const rows = await (deps.gh ?? defaultGh).pr.list(
|
|
297
308
|
['--head', ctx.storyBranch, '--state', 'all'],
|
|
298
|
-
['url', 'state', 'mergedAt'],
|
|
309
|
+
['url', 'state', 'mergedAt', 'headRefOid'],
|
|
299
310
|
);
|
|
300
311
|
const head = pickHeadPullRequest(rows);
|
|
301
|
-
|
|
302
|
-
|
|
312
|
+
if (head?.state !== 'MERGED') return null;
|
|
313
|
+
const row = rows.find((r) => String(r?.url ?? '').trim() === head.url);
|
|
314
|
+
const landed = survivingStoryHeads(ctx).every(
|
|
315
|
+
(sha) => sha === row.headRefOid,
|
|
316
|
+
);
|
|
317
|
+
return landed
|
|
318
|
+
? {
|
|
319
|
+
prUrl: head.url,
|
|
320
|
+
prNumber: parsePrNumber(head.url),
|
|
321
|
+
mergedAt: row.mergedAt ?? 'an unknown time',
|
|
322
|
+
}
|
|
303
323
|
: null;
|
|
304
324
|
} catch {
|
|
305
325
|
return null;
|
|
@@ -307,22 +327,17 @@ async function findLandedPr(ctx, deps) {
|
|
|
307
327
|
}
|
|
308
328
|
|
|
309
329
|
/**
|
|
310
|
-
* A
|
|
311
|
-
*
|
|
330
|
+
* A head whose PR already merged short-circuits to the confirm before any
|
|
331
|
+
* worktree restore; otherwise a missing worktree is recreated.
|
|
312
332
|
*/
|
|
313
333
|
async function resolveCloseWorktree(ctx, deps) {
|
|
314
|
-
|
|
315
|
-
const wtIsolation = deps.config.delivery?.worktreeIsolation;
|
|
316
|
-
const missing =
|
|
317
|
-
!existingWorktreePath({ cwd, wtIsolation, storyId: ctx.storyId }) &&
|
|
318
|
-
resolveWorktreeEnabled({ config: deps.config });
|
|
319
|
-
ctx.landedPr = missing ? await findLandedPr(ctx, deps) : null;
|
|
334
|
+
ctx.landedPr = await findLandedPr(ctx, deps);
|
|
320
335
|
if (ctx.landedPr) {
|
|
321
336
|
ctx.recordPrNumber(ctx.landedPr.prNumber);
|
|
322
337
|
return null;
|
|
323
338
|
}
|
|
324
339
|
return await resolveStoryWorktree({
|
|
325
|
-
cwd,
|
|
340
|
+
cwd: ctx.options.cwd,
|
|
326
341
|
config: deps.config,
|
|
327
342
|
storyId: ctx.storyId,
|
|
328
343
|
storyBranch: ctx.storyBranch,
|
|
@@ -340,7 +355,7 @@ function unlessLanded(phase, onLanded) {
|
|
|
340
355
|
function landedPrePush(ctx) {
|
|
341
356
|
progress(
|
|
342
357
|
'INIT',
|
|
343
|
-
`⏭ PR ${ctx.landedPr.prUrl} already merged — skipping validation, sync and push.`,
|
|
358
|
+
`⏭ PR ${ctx.landedPr.prUrl} already merged at ${ctx.landedPr.mergedAt} — skipping validation, sync and push.`,
|
|
344
359
|
);
|
|
345
360
|
ctx.options = { ...ctx.options, skipValidation: true, skipSync: true };
|
|
346
361
|
ctx.prePush = {
|
|
@@ -433,7 +448,7 @@ function buildPrContext(ctx, deps) {
|
|
|
433
448
|
phaseTimer: ctx.phaseTimer,
|
|
434
449
|
worker: ctx.worker,
|
|
435
450
|
lockWait: ctx.prePush.lockWait,
|
|
436
|
-
suiteTimings: ctx
|
|
451
|
+
suiteTimings: envelopeSuiteTimings(ctx, deps),
|
|
437
452
|
gates: closeEnvelopeGates(
|
|
438
453
|
options,
|
|
439
454
|
ctx.prePush.validationGates,
|
|
@@ -443,6 +458,17 @@ function buildPrContext(ctx, deps) {
|
|
|
443
458
|
};
|
|
444
459
|
}
|
|
445
460
|
|
|
461
|
+
/**
|
|
462
|
+
* The suite close spawned (`source: 'close'`), else — when its gates ran and
|
|
463
|
+
* honoured the handoff's credit — the credited run's figures.
|
|
464
|
+
*/
|
|
465
|
+
function envelopeSuiteTimings(ctx, deps) {
|
|
466
|
+
const { validationGates, suiteTimings } = ctx.prePush;
|
|
467
|
+
if (suiteTimings || !validationGates) return suiteTimings;
|
|
468
|
+
const credit = readCreditTimings(ctx.storyId, deps.config);
|
|
469
|
+
return credit && sourcedTimings(credit, 'credited-run');
|
|
470
|
+
}
|
|
471
|
+
|
|
446
472
|
function decideWaitForMerge(ctx, deps) {
|
|
447
473
|
const { options, arm } = ctx;
|
|
448
474
|
const decision = resolveWaitForMerge({
|
|
@@ -116,7 +116,7 @@ function compact(obj) {
|
|
|
116
116
|
* @param {object|null} [args.waitBudget]
|
|
117
117
|
* @param {{ waitedSeconds: number, expired: boolean, holder?: object }|null} [args.lockWait]
|
|
118
118
|
* Full-suite lock wait; `waitBudget` is merge-wait only.
|
|
119
|
-
* @param {{ lockWaitMs: number, hostWaitMs: number|null, testRunMs: number }|null} [args.suiteTimings]
|
|
119
|
+
* @param {{ lockWaitMs: number, hostWaitMs: number|null, testRunMs: number, source: 'close'|'credited-run', spawns: object[] }|null} [args.suiteTimings]
|
|
120
120
|
* @param {Record<string, number>|null} [args.phaseDurations] Seconds per phase.
|
|
121
121
|
* @param {string} [args.timestamp]
|
|
122
122
|
* @param {{ schema: object|null, error: string|null }} [args.schemaSource]
|
|
@@ -23,7 +23,10 @@ import path from 'node:path';
|
|
|
23
23
|
import { fileURLToPath } from 'node:url';
|
|
24
24
|
|
|
25
25
|
import { spawnStreamAsync } from '../child-exec.js';
|
|
26
|
-
import {
|
|
26
|
+
import {
|
|
27
|
+
createLockEventChannel,
|
|
28
|
+
summarizeLockEvents,
|
|
29
|
+
} from '../close-lock-events.js';
|
|
27
30
|
import {
|
|
28
31
|
resolveGateCommand,
|
|
29
32
|
resolveTestGateArgv,
|
|
@@ -48,6 +51,7 @@ import { describeBlocking } from '../suite-admission.js';
|
|
|
48
51
|
import { writeFileAtomic } from '../util/atomic-write.js';
|
|
49
52
|
import { defaultSleep } from '../util/sleep.js';
|
|
50
53
|
import { runStreamed } from './evidence-stream.js';
|
|
54
|
+
import { handoffStatePath } from './handoff-state.js';
|
|
51
55
|
import { probeHeldReviewDiff } from './review-deposit.js';
|
|
52
56
|
import { createStoryProgress, handoffStepName } from './story-progress.js';
|
|
53
57
|
import {
|
|
@@ -254,11 +258,16 @@ function durations({ waitMs, executionMs }) {
|
|
|
254
258
|
/**
|
|
255
259
|
* Tail a fresh lock-event channel while `run(env)` runs, forwarding each
|
|
256
260
|
* `lock-progress` event once; never the child's output, which can be forged.
|
|
261
|
+
* `timings` summarizes every event drained (the lock wait and suite spawns).
|
|
262
|
+
*
|
|
263
|
+
* @returns {Promise<{ result: any, timings: ReturnType<typeof summarizeLockEvents> }>}
|
|
257
264
|
*/
|
|
258
265
|
async function withLockProgress(ctx, run) {
|
|
259
266
|
const channel = ctx.createLockChannel();
|
|
267
|
+
const events = [];
|
|
260
268
|
const forward = () => {
|
|
261
269
|
for (const event of channel.drain()) {
|
|
270
|
+
events.push(event);
|
|
262
271
|
if (event.kind === 'lock-progress') {
|
|
263
272
|
ctx.progress('LOCK', describeLockProgress(event));
|
|
264
273
|
}
|
|
@@ -272,13 +281,15 @@ async function withLockProgress(ctx, run) {
|
|
|
272
281
|
if (running) forward();
|
|
273
282
|
}
|
|
274
283
|
})().catch(() => {});
|
|
284
|
+
let result;
|
|
275
285
|
try {
|
|
276
|
-
|
|
286
|
+
result = await run({ ...ctx.env, ...channel.env });
|
|
277
287
|
} finally {
|
|
278
288
|
running = false;
|
|
279
289
|
forward();
|
|
280
290
|
channel.dispose();
|
|
281
291
|
}
|
|
292
|
+
return { result, timings: summarizeLockEvents(events) };
|
|
282
293
|
}
|
|
283
294
|
|
|
284
295
|
/**
|
|
@@ -477,22 +488,29 @@ async function stepCreditedRun(ctx) {
|
|
|
477
488
|
// Close's `test` gate argv, so the deposit keys on its credit identity.
|
|
478
489
|
...testGateArgv(ctx.config),
|
|
479
490
|
];
|
|
480
|
-
const run = await withLockProgress(ctx, (env) =>
|
|
491
|
+
const { result: run, timings } = await withLockProgress(ctx, (env) =>
|
|
481
492
|
runLogged(ctx, 'credited-run', 'node', args, env),
|
|
482
493
|
);
|
|
483
|
-
const
|
|
494
|
+
const { lockWait, suiteTimings, spawns } = timings;
|
|
495
|
+
const extra = {
|
|
496
|
+
evidencePath: run.evidencePath,
|
|
497
|
+
depositor: ctx.depositor,
|
|
498
|
+
lockWait,
|
|
499
|
+
suiteTimings,
|
|
500
|
+
};
|
|
484
501
|
if (run.status !== 0) {
|
|
485
502
|
return fixRequired(name, describeSuiteFailure(run.status), extra);
|
|
486
503
|
}
|
|
487
504
|
const [ranSignal, freshSignal] = capture
|
|
488
505
|
? [SIGNALS.captureRan, SIGNALS.captureFresh]
|
|
489
506
|
: [SIGNALS.testRan, SIGNALS.testFresh];
|
|
507
|
+
const credit = { head: ctx.head, lockWait, suiteTimings, spawns };
|
|
490
508
|
if (ranSignal.test(run.output)) {
|
|
491
|
-
ctx
|
|
509
|
+
recordCredit(ctx, credit);
|
|
492
510
|
return ran(name, `${ctx.depositor} deposited credit`, extra);
|
|
493
511
|
}
|
|
494
512
|
if (freshSignal.test(run.output)) {
|
|
495
|
-
ctx
|
|
513
|
+
recordCredit(ctx, credit);
|
|
496
514
|
return skipped(name, `${ctx.depositor} credit already fresh`, extra);
|
|
497
515
|
}
|
|
498
516
|
return fixRequired(
|
|
@@ -502,6 +520,12 @@ async function stepCreditedRun(ctx) {
|
|
|
502
520
|
);
|
|
503
521
|
}
|
|
504
522
|
|
|
523
|
+
/** Credit and its run's figures move together, keyed by the credited head. */
|
|
524
|
+
function recordCredit(ctx, creditTimings) {
|
|
525
|
+
ctx.state.creditHead = creditTimings.head;
|
|
526
|
+
ctx.state.creditTimings = creditTimings;
|
|
527
|
+
}
|
|
528
|
+
|
|
505
529
|
/**
|
|
506
530
|
* @param {Function} git
|
|
507
531
|
* @param {string} cwd
|
|
@@ -547,7 +571,7 @@ async function commitSeatedRows(ctx, total, evidencePath) {
|
|
|
547
571
|
// Both capture-stamp digests leave `baselines/` out, so a baseline-JSON-only
|
|
548
572
|
// commit keeps the credit it already holds.
|
|
549
573
|
if (creditedPrior && ctx.depositor === 'coverage-capture') {
|
|
550
|
-
ctx.state.
|
|
574
|
+
recordCredit(ctx, { ...ctx.state.creditTimings, head: ctx.head });
|
|
551
575
|
}
|
|
552
576
|
return ran(name, `seated ${total} row(s) and committed them`, {
|
|
553
577
|
evidencePath,
|
|
@@ -822,7 +846,7 @@ function precheck(ctx) {
|
|
|
822
846
|
*
|
|
823
847
|
* @param {string} statePath
|
|
824
848
|
* @param {(tag: string, msg: string) => void} progress
|
|
825
|
-
* @returns {{ preflightHead?: string, creditHead?: string, seatHead?: string }}
|
|
849
|
+
* @returns {{ preflightHead?: string, creditHead?: string, creditTimings?: object, seatHead?: string }}
|
|
826
850
|
*/
|
|
827
851
|
function readState(statePath, progress) {
|
|
828
852
|
let raw;
|
|
@@ -934,7 +958,7 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
934
958
|
warn: (m) => progress('BLOCK', m),
|
|
935
959
|
}));
|
|
936
960
|
fs.mkdirSync(logDir, { recursive: true });
|
|
937
|
-
const statePath =
|
|
961
|
+
const statePath = handoffStatePath(logDir, storyId);
|
|
938
962
|
const branch = getStoryBranch(storyId);
|
|
939
963
|
const evidencePathFor = (name) =>
|
|
940
964
|
path.join(logDir, `story-handoff-${storyId}-${name}.log`);
|
|
@@ -1001,6 +1025,7 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
1001
1025
|
}
|
|
1002
1026
|
|
|
1003
1027
|
const status = stop?.stop ?? HANDOFF_STATUS.READY;
|
|
1028
|
+
const credited = steps.find((s) => s.name === 'credited-run');
|
|
1004
1029
|
if (status === HANDOFF_STATUS.BLOCKED) {
|
|
1005
1030
|
await block({ storyId, config, reason: stop.reason, detail: stop.detail });
|
|
1006
1031
|
}
|
|
@@ -1013,6 +1038,8 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
|
|
|
1013
1038
|
depositor: ctx.depositor,
|
|
1014
1039
|
steps: steps.map(({ stop: _stop, ...rest }) => rest),
|
|
1015
1040
|
review: ctx.review,
|
|
1041
|
+
lockWait: credited?.lockWait ?? null,
|
|
1042
|
+
suiteTimings: credited?.suiteTimings ?? null,
|
|
1016
1043
|
...(stop
|
|
1017
1044
|
? {
|
|
1018
1045
|
failedStep: stop.name,
|
|
@@ -201,6 +201,32 @@ export function predictsTestEvidenceCredit({
|
|
|
201
201
|
}
|
|
202
202
|
}
|
|
203
203
|
|
|
204
|
+
/** Does `sha` hold `test` credit under the full-suite identity? Uncertainty is `false`. */
|
|
205
|
+
export function hasTestCreditAt({
|
|
206
|
+
config,
|
|
207
|
+
storyId,
|
|
208
|
+
cwd,
|
|
209
|
+
evidenceCwd,
|
|
210
|
+
sha,
|
|
211
|
+
shouldSkipImpl = defaultShouldSkip,
|
|
212
|
+
} = {}) {
|
|
213
|
+
if (!sha) return false;
|
|
214
|
+
try {
|
|
215
|
+
const verdict = shouldSkipImpl(
|
|
216
|
+
{
|
|
217
|
+
storyId,
|
|
218
|
+
gateName: GATE_NAME,
|
|
219
|
+
currentSha: sha,
|
|
220
|
+
configHash: testGateConfigHash(config, cwd),
|
|
221
|
+
},
|
|
222
|
+
{ cwd: evidenceCwd ?? cwd, standalone: true },
|
|
223
|
+
);
|
|
224
|
+
return verdict.skip === true;
|
|
225
|
+
} catch {
|
|
226
|
+
return false;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
|
|
204
230
|
/**
|
|
205
231
|
* @param {{ storyId: number, sha: string, cwd: string, config: object|null, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
|
|
206
232
|
* @returns {{ deposited: boolean, reason: string, storyId: number, sha: string }}
|
|
@@ -165,6 +165,8 @@ export function loadEvidence(scopeId, opts = {}) {
|
|
|
165
165
|
* configHash: string,
|
|
166
166
|
* exitCode?: number,
|
|
167
167
|
* durationMs?: number|null,
|
|
168
|
+
* scope?: 'full'|'delta',
|
|
169
|
+
* since?: string,
|
|
168
170
|
* }} input
|
|
169
171
|
* @param {{ cwd?: string, tempDir?: string, standalone?: boolean, fs?: object, now?: Function }} opts
|
|
170
172
|
* @returns {object} The persisted record.
|
|
@@ -178,6 +180,8 @@ export function recordPass(
|
|
|
178
180
|
exitCode = 0,
|
|
179
181
|
durationMs = null,
|
|
180
182
|
inputFingerprint = null,
|
|
183
|
+
scope,
|
|
184
|
+
since,
|
|
181
185
|
},
|
|
182
186
|
opts = {},
|
|
183
187
|
) {
|
|
@@ -201,6 +205,8 @@ export function recordPass(
|
|
|
201
205
|
inputFingerprint: isNonEmptyString(inputFingerprint)
|
|
202
206
|
? inputFingerprint
|
|
203
207
|
: null,
|
|
208
|
+
...(scope ? { scope } : {}),
|
|
209
|
+
...(since ? { since } : {}),
|
|
204
210
|
timestamp: resolved.now().toISOString(),
|
|
205
211
|
};
|
|
206
212
|
doc.records = [...doc.records.filter((r) => r.gateName !== gateName), record];
|
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: >-
|
|
3
|
+
Audit every external dependency, platform binding and cross-service seam:
|
|
4
|
+
whether failure is bounded, whether the system degrades on purpose, what the
|
|
5
|
+
user sees, and whether a human is told and how fast. A deliberately-global
|
|
6
|
+
lens that builds a dependency inventory and follows each failure to a human.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Resilience Audit
|
|
10
|
+
|
|
11
|
+
You are a Staff Reliability Engineer auditing this project's **dependency
|
|
12
|
+
barriers and integration points**. A per-file grep can ask whether a call has
|
|
13
|
+
a timeout. It cannot ask whether the retry budget still fits the lane that
|
|
14
|
+
drives it, whether the reconcile job's filter covers every state a failure
|
|
15
|
+
leaves behind, or whether the sink a money-path error lands in pages anyone.
|
|
16
|
+
Those are relationships between places, and they are this lens's primary
|
|
17
|
+
finding class.
|
|
18
|
+
|
|
19
|
+
The shared lens machinery lives in
|
|
20
|
+
[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
|
|
21
|
+
`{{auditResultsDir}}/audit-resilience-results.md`. Dimension values:
|
|
22
|
+
`Inventory | Barrier | Integrity | Signal Path | Landing | Background Lane |
|
|
23
|
+
Assumption Drift`. Every finding adds a **Dependency:** field naming the
|
|
24
|
+
inventory row it cites. The report adds four mandatory sections: **Dependency
|
|
25
|
+
Inventory**, **Signal Path**, **Corrections** and **Verified strengths** (see
|
|
26
|
+
Report additions).
|
|
27
|
+
|
|
28
|
+
## Whole-project scope (global lens)
|
|
29
|
+
|
|
30
|
+
A barrier and the lane or sink it depends on sit in files no change set names,
|
|
31
|
+
so this lens **always evaluates the whole project**. It declares
|
|
32
|
+
`"scope": "global"` and `"target": "integrations"` in
|
|
33
|
+
[`audit-rules.json`](../schemas/audit-rules.json): the selector skips it on a
|
|
34
|
+
project with no integration SDK, no outbound call outside tests and no
|
|
35
|
+
platform-binding config, per the core's absent-vs-inapplicable rule.
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
{{changedFiles}}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- For this lens, **ignore** the `{{changedFiles}}` block above as a filter even
|
|
42
|
+
when it is populated: the project is evaluated whole. When populated, use it
|
|
43
|
+
as a **prioritization hint** — walk the dependencies a changed file touches
|
|
44
|
+
first — never as a limit on what is audited or reported.
|
|
45
|
+
|
|
46
|
+
## Execution strategy
|
|
47
|
+
|
|
48
|
+
Run this lens as one `subagent_type: auditor` dispatch per the core's
|
|
49
|
+
Execution strategy: the auditor builds the inventory (Step 1), then judges the
|
|
50
|
+
dimensions. Fan out only when the operator's invocation asks for it. The
|
|
51
|
+
caller then builds the inventory first and dispatches one auditor per
|
|
52
|
+
dimension, or per dependency family on a large inventory, in a single turn.
|
|
53
|
+
Each child receives the inventory table as context, and the caller merges the
|
|
54
|
+
results under the core's self-cross-check.
|
|
55
|
+
|
|
56
|
+
Two invocation modes narrow a manual run:
|
|
57
|
+
|
|
58
|
+
- `--inventory-only` runs Step 1 alone and writes only the Dependency
|
|
59
|
+
Inventory: no findings and no judgement. It is a cheap standing artifact a
|
|
60
|
+
consumer can diff between sweeps.
|
|
61
|
+
- `--dependency <name>` narrows the inventory and every dimension to the one
|
|
62
|
+
named dependency.
|
|
63
|
+
|
|
64
|
+
## Step 1: Dependency inventory (tool-first)
|
|
65
|
+
|
|
66
|
+
Build the inventory before judging anything. Every later finding cites a row.
|
|
67
|
+
|
|
68
|
+
- Census the dependencies:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Third-party SDK imports (JS/TS; adapt the pattern for Python/Go)
|
|
72
|
+
rg -n --glob '!**/*.{test,spec}.*' "from ['\"](@?[a-z0-9-]+)(/[^'\"]*)?['\"]" | \
|
|
73
|
+
rg -i "stripe|clerk|auth0|resend|sendgrid|postmark|mailgun|twilio|telnyx|aws-sdk|google-cloud|pinecone|openai|anthropic|sentry|libsql|turso"
|
|
74
|
+
# Outbound call sites outside tests
|
|
75
|
+
rg -n --glob '!**/*.{test,spec}.*' --glob '!**/{test,tests,__tests__}/**' \
|
|
76
|
+
"\b(fetch|axios(\.\w+)?|got|ky|http\.request|https\.request)\s*\(|requests\.(get|post)|httpx\.|http\.Get\("
|
|
77
|
+
# Bindings and secrets the runtime expects
|
|
78
|
+
ls wrangler.* serverless.* .env.example 2>/dev/null; rg -n "^\[\[?(kv_namespaces|r2_buckets|d1_databases|vectorize|ai|queues|services)" --glob 'wrangler.*'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Emit one row per dependency in the **Dependency Inventory** table (columns
|
|
82
|
+
under Report additions): its callers, its timeout and whether that timeout
|
|
83
|
+
covers the body read, its retry posture, what the system does when it fails,
|
|
84
|
+
what it does when its secret or binding is absent, the user-visible message,
|
|
85
|
+
the alert path, and the detection lag for a full outage.
|
|
86
|
+
|
|
87
|
+
## Step 2: Evaluation dimensions
|
|
88
|
+
|
|
89
|
+
Every finding takes exactly one of these as its `Dimension`. Inventory is the
|
|
90
|
+
artifact itself; a missing or contradictory row (a caller with no timeout
|
|
91
|
+
recorded anywhere) is the only Inventory finding.
|
|
92
|
+
|
|
93
|
+
### Barrier
|
|
94
|
+
|
|
95
|
+
- Run the barrier greps:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# Outbound calls with no timeout or signal on the same line
|
|
99
|
+
rg -n "\b(fetch|axios(\.\w+)?|http\.request|got|ky)\s*\(" --glob '!**/*.test.*' | \
|
|
100
|
+
rg -v -i "timeout|signal|AbortController|AbortSignal"
|
|
101
|
+
# Empty catch blocks (a failure that leaves no signal)
|
|
102
|
+
rg -n "catch\s*(\([^)]*\))?\s*\{\s*\}"
|
|
103
|
+
# Retry and backoff sites (check each is bounded and idempotent)
|
|
104
|
+
rg -n -i "retr(y|ies)|backoff|circuit.?breaker|p-retry"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- **Timeout scope** — a timeout that covers the headers but not the body read
|
|
108
|
+
is a partial barrier; a slow body still holds the request.
|
|
109
|
+
- **Retry safety** — a retry that can replay an ambiguous write without an
|
|
110
|
+
idempotency key.
|
|
111
|
+
- **Outage as empty** — a deadline or failure path that resolves to an empty
|
|
112
|
+
result instead of rejecting. An outage must never read as "no rows".
|
|
113
|
+
- **Fail-open vs fail-closed** — left implicit at a seam where the choice
|
|
114
|
+
matters.
|
|
115
|
+
- **Missing secret or binding** — crashes, or silently disables, instead of
|
|
116
|
+
entering an explicit disabled mode with a reason.
|
|
117
|
+
- **Bypassed primitive** — a raw call that skips the project's own bounded
|
|
118
|
+
fetch helper when one exists.
|
|
119
|
+
|
|
120
|
+
### Integrity
|
|
121
|
+
|
|
122
|
+
Money and safety under partial failure, wherever an external side effect is
|
|
123
|
+
involved:
|
|
124
|
+
|
|
125
|
+
- **Idempotency keys** on every money-moving write.
|
|
126
|
+
- **Claim before transmit** on every external send (email, SMS, push), so a
|
|
127
|
+
crash between transmit and ledger cannot duplicate.
|
|
128
|
+
- **Webhook receivers** return a 5xx on downstream failure so the provider
|
|
129
|
+
retries, and keep a replay ledger. A 200 that loses the event is the
|
|
130
|
+
finding.
|
|
131
|
+
- **Reconciliation coverage** — the job exists **and its candidate set covers
|
|
132
|
+
every state a failure can leave**, not only the happy-path pending state.
|
|
133
|
+
- **Compensation** — a multi-step write cleans up the blob store when the
|
|
134
|
+
record write fails.
|
|
135
|
+
- **Fan-out settlement** — per recipient, not "any recipient was reached".
|
|
136
|
+
|
|
137
|
+
### Signal Path
|
|
138
|
+
|
|
139
|
+
For each failure class in the inventory, trace signal → sink → rule → human
|
|
140
|
+
and name the lag.
|
|
141
|
+
|
|
142
|
+
- **Sink classification** — a log store with bounded retention and no
|
|
143
|
+
alerting is **not** an alert, whatever level the line carries.
|
|
144
|
+
- **Capture census** — every error-tracker capture site by level and
|
|
145
|
+
fingerprint: money or safety conditions captured at `warning`, captured with
|
|
146
|
+
an opt-out tag, or not captured at all.
|
|
147
|
+
- **Storms and collapse** — un-fingerprinted per-request captures that storm,
|
|
148
|
+
and shared helpers whose `new Error(name)` collapses distinct failures into
|
|
149
|
+
one group.
|
|
150
|
+
- **Silent producers** — alert queries that swallow their own failure
|
|
151
|
+
(`catch { return 0 }`), so a broken alert reads as healthy.
|
|
152
|
+
- **Sink posture** — the sink's own storm guard and quota on its tier; one
|
|
153
|
+
flood must not blind every other pager.
|
|
154
|
+
- **Watch the watcher** — walk every hop of the alert pipeline (tracker →
|
|
155
|
+
relay → issue tracker → chat) and ask what fires when that hop fails. Find
|
|
156
|
+
first-seen-only rules that miss regressions.
|
|
157
|
+
|
|
158
|
+
### Landing
|
|
159
|
+
|
|
160
|
+
- **Error page** — every app ships a branded error page; an SSR throw is never
|
|
161
|
+
a blank body.
|
|
162
|
+
- **Outage shape** — an outage never borrows the empty-state shape ("you have
|
|
163
|
+
nothing" on a database failure).
|
|
164
|
+
- **Retry affordance** — the client honours a server-sent `503` with
|
|
165
|
+
`Retry-After`, and a transient failure offers a retry.
|
|
166
|
+
- **Error boundaries** on revenue and safety flows.
|
|
167
|
+
- **Report path** — "report a problem" still works when the primary store is
|
|
168
|
+
down, and the copy names what to do.
|
|
169
|
+
|
|
170
|
+
### Background Lane
|
|
171
|
+
|
|
172
|
+
- **Per-job isolation** — one throw does not stop the other jobs in a fire.
|
|
173
|
+
- **Per-job deadline** — one hung upstream cannot consume the whole fire.
|
|
174
|
+
- **Overlap safety** and at-most-once claims around side effects.
|
|
175
|
+
- **Heartbeats** with explicit completed-vs-passed semantics, and a streak
|
|
176
|
+
threshold so a job failing every fire for days is noticed rather than
|
|
177
|
+
grouped into one issue created on day one.
|
|
178
|
+
- **Missing secret** skips the job with a reason; it never crashes the fire.
|
|
179
|
+
|
|
180
|
+
### Assumption Drift
|
|
181
|
+
|
|
182
|
+
Constants and comments justified by a fact the tree has since changed: a retry
|
|
183
|
+
budget "chosen against the hourly cadence" after the drain moved to an
|
|
184
|
+
every-minute lane, "same trade as the sibling app" after the sibling was
|
|
185
|
+
fixed, a grace window tuned to a schedule that was later shortened. No other
|
|
186
|
+
lens owns this pass, and it is cheap:
|
|
187
|
+
|
|
188
|
+
- Find the drift candidates:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
# Cadence and parity words next to constants or config
|
|
192
|
+
rg -n -i -B2 -A2 "hourly|every (minute|hour|day)|\bcron\b|cadence|same as|mirrors|like the sibling" \
|
|
193
|
+
--glob '!**/*.{test,spec}.*' --glob '!**/*.md' | rg -i "[0-9]|const |= "
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
For every hit, find the fact the comment cites (the cron expression, the lane
|
|
197
|
+
membership, the sibling's current code) and check it still holds. A constant
|
|
198
|
+
whose justification no longer holds is the finding; cite both places.
|
|
199
|
+
|
|
200
|
+
## Step 3: Evidence and severity
|
|
201
|
+
|
|
202
|
+
This lens adds four rules to the core's self-cross-check:
|
|
203
|
+
|
|
204
|
+
1. **Second read for every Critical and High.** Re-verify each one by reading
|
|
205
|
+
the actual control-flow order (middleware sequence, call order, lane
|
|
206
|
+
membership), not a comment or a single file. A boundary that looks like it
|
|
207
|
+
swallows a throw may sit outside the wrapper that captures it. A Critical
|
|
208
|
+
or High that fails the second read is dropped and recorded under
|
|
209
|
+
`## Corrections` with the reason, so the next sweep does not re-raise it.
|
|
210
|
+
2. **Alert gaps name the route.** An alert-gap finding names the sink, its
|
|
211
|
+
retention or level, and the rule (or the absence of one) that would carry it
|
|
212
|
+
to a human. "Not in the error tracker" alone is not a finding.
|
|
213
|
+
3. **Timeouts name the cost.** A missing-timeout finding names what the hang
|
|
214
|
+
holds: a request, a claim, a cron fire. An unbounded call with no downstream
|
|
215
|
+
consequence is `Low`.
|
|
216
|
+
4. **Severity calibration**:
|
|
217
|
+
`Critical` or `High` — money or safety integrity, a whole-surface outage, or
|
|
218
|
+
a missing human signal for either. `Medium` — degraded UX with no feedback,
|
|
219
|
+
or a signal that arrives hours late. `Low` — polish and consistency.
|
|
220
|
+
|
|
221
|
+
## Step 4: Boundaries with sibling lenses
|
|
222
|
+
|
|
223
|
+
Drop anything a sibling owns whole, and cite that sibling when you do:
|
|
224
|
+
|
|
225
|
+
- `audit-sre` keeps rollback, migration reversibility, kill switches,
|
|
226
|
+
runbooks, health endpoints, graceful shutdown and the release-readiness
|
|
227
|
+
checklist.
|
|
228
|
+
- `audit-performance` keeps TOCTOU, unawaited promises and non-atomic writes;
|
|
229
|
+
this lens asks the integrity question only where an external side effect is
|
|
230
|
+
involved.
|
|
231
|
+
- `audit-security` keeps webhook signature verification; this lens asks about
|
|
232
|
+
the response code on downstream failure, the replay ledger and the retry
|
|
233
|
+
contract, not the crypto.
|
|
234
|
+
- `audit-privacy` keeps what the sinks contain; this lens asks where they go
|
|
235
|
+
and whether anyone reads them.
|
|
236
|
+
- `audit-devops` keeps CI and deploy pipeline resilience.
|
|
237
|
+
|
|
238
|
+
## Constraint
|
|
239
|
+
|
|
240
|
+
Read-only and static: no live probing of vendors, no remediation. A consumer's
|
|
241
|
+
smoke lane is a finding input, not something this lens runs.
|
|
242
|
+
|
|
243
|
+
## Report additions
|
|
244
|
+
|
|
245
|
+
Beyond the core's shared skeleton, this lens adds its title, the four
|
|
246
|
+
mandatory sections and the `Dependency` finding field. Write `_No findings._`
|
|
247
|
+
under a section rather than omitting it:
|
|
248
|
+
|
|
249
|
+
```markdown
|
|
250
|
+
# Resilience Audit Report
|
|
251
|
+
|
|
252
|
+
## Executive Summary
|
|
253
|
+
|
|
254
|
+
[Headline read.]
|
|
255
|
+
|
|
256
|
+
Self-cross-check: kept <k> / dropped <d>.
|
|
257
|
+
Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
|
|
258
|
+
|
|
259
|
+
## Dependency Inventory
|
|
260
|
+
|
|
261
|
+
| Dependency | Callers | Timeout (covers body?) | Retry (bounded / backoff / idempotent) | On failure | On missing secret | User sees | Alert path | Detection lag |
|
|
262
|
+
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
263
|
+
| [name] | `path:line` | [value — yes/no] | [posture] | [degraded mode] | [disabled mode] | [message] | [sink → rule → human] | [lag] |
|
|
264
|
+
|
|
265
|
+
## Signal Path
|
|
266
|
+
|
|
267
|
+
| Failure class | Signal | Reaches a human via | Detection lag | Gap |
|
|
268
|
+
| --- | --- | --- | --- | --- |
|
|
269
|
+
| [class] | [capture / log / metric] | [sink → rule → channel] | [lag] | [gap or none] |
|
|
270
|
+
|
|
271
|
+
## Detailed Findings
|
|
272
|
+
|
|
273
|
+
### `path/to/primary-file.ext` — [Short title of the issue]
|
|
274
|
+
|
|
275
|
+
- **Dimension:** [Inventory | Barrier | Integrity | Signal Path | Landing | Background Lane | Assumption Drift]
|
|
276
|
+
- **Severity:** [Critical | High | Medium | Low | Info]
|
|
277
|
+
- **Dependency:** [the inventory row this finding cites]
|
|
278
|
+
- [Location, Current State, Recommendation & Rationale, Acceptance signal —
|
|
279
|
+
per the core skeleton]
|
|
280
|
+
|
|
281
|
+
## Corrections
|
|
282
|
+
|
|
283
|
+
| Dropped finding | Severity as drafted | Why the second read cleared it |
|
|
284
|
+
| --- | --- | --- |
|
|
285
|
+
| [title] | [High] | [the control-flow order actually read, with `path:line`] |
|
|
286
|
+
|
|
287
|
+
## Verified strengths
|
|
288
|
+
|
|
289
|
+
- [A primitive that works and that fix PRs must not erode — `path:line`]
|
|
290
|
+
```
|