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
|
@@ -98,7 +98,11 @@ Conventional Commit subjects on `story-<storyId>` per
|
|
|
98
98
|
chars, `(refs #<storyId>)`. Never bypass a hook (`--no-verify` /
|
|
99
99
|
`--no-gpg-sign`); if one fails, fix the cause in a follow-up commit, never
|
|
100
100
|
amend. Docs are digest-first: read the digest your caller passes and pull
|
|
101
|
-
files on demand; a null digest path means no docs mandate.
|
|
101
|
+
files on demand; a null digest path means no docs mandate. When the
|
|
102
|
+
consumer declares `delivery.pullRequest.bodyTrailers`, record each required
|
|
103
|
+
declaration as a git trailer on a branch commit
|
|
104
|
+
(`git commit --trailer 'Key: value'`): close lifts the last one into the PR
|
|
105
|
+
body, and you never edit a PR.
|
|
102
106
|
|
|
103
107
|
## Acceptance self-eval (MUST)
|
|
104
108
|
|
|
@@ -130,6 +134,8 @@ review, then prints one envelope (what each step runs:
|
|
|
130
134
|
`ready` → return. `fix-required` (exit 2) → fix the cause it names, commit,
|
|
131
135
|
re-run it; the same cause surviving the same fix twice is your blocked path.
|
|
132
136
|
`blocked` (exit 1) → it already flipped `agent::blocked`; exit non-zero.
|
|
137
|
+
A close after a base move re-runs only the affected tests when the
|
|
138
|
+
consumer declares `project.commands.testChanged`.
|
|
133
139
|
|
|
134
140
|
If it outruns the host's sync Bash ceiling, dispatch it in the
|
|
135
141
|
**background**: its completion re-invokes you. Never spawn a task to poll or
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
<!-- GENERATED FILE — do not edit by hand.
|
|
2
|
+
Source of truth: .agents/workflows/audit-resilience.md
|
|
3
|
+
Regenerate: node .agents/scripts/generate-lens-checklists.js
|
|
4
|
+
Drift is gated by: npm run docs:check
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# Resilience Audit — authoring checklist
|
|
8
|
+
|
|
9
|
+
> Audit every external dependency, platform binding and cross-service seam: whether failure is bounded, whether the system degrades on purpose, what the user sees, and whether a human is told and how fast. A deliberately-global lens that builds a dependency inventory and follows…
|
|
10
|
+
|
|
11
|
+
Self-check your change against this lens's concerns before you ship:
|
|
12
|
+
|
|
13
|
+
- [ ] Timeout scope
|
|
14
|
+
- [ ] Retry safety
|
|
15
|
+
- [ ] Outage as empty
|
|
16
|
+
- [ ] Fail-open vs fail-closed
|
|
17
|
+
- [ ] Missing secret or binding
|
|
18
|
+
- [ ] Bypassed primitive
|
|
19
|
+
- [ ] Idempotency keys
|
|
20
|
+
- [ ] Claim before transmit
|
|
21
|
+
- [ ] Webhook receivers
|
|
22
|
+
- [ ] Reconciliation coverage
|
|
23
|
+
- [ ] Compensation
|
|
24
|
+
- [ ] Fan-out settlement
|
|
25
|
+
- [ ] Sink classification
|
|
26
|
+
- [ ] Capture census
|
|
27
|
+
- [ ] Storms and collapse
|
|
28
|
+
- [ ] Silent producers
|
|
29
|
+
- [ ] Sink posture
|
|
30
|
+
- [ ] Watch the watcher
|
|
31
|
+
- [ ] Error page
|
|
32
|
+
- [ ] Outage shape
|
|
33
|
+
- [ ] Retry affordance
|
|
34
|
+
- [ ] Error boundaries
|
|
35
|
+
- [ ] Report path
|
|
36
|
+
- [ ] Per-job isolation
|
|
37
|
+
- [ ] Per-job deadline
|
|
38
|
+
- [ ] Overlap safety
|
|
39
|
+
- [ ] Heartbeats
|
|
40
|
+
- [ ] …see the full lens for the remaining concerns
|
|
@@ -10,17 +10,15 @@
|
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
13
|
-
- [ ] Run the
|
|
13
|
+
- [ ] Run the readiness battery.
|
|
14
14
|
- [ ] Rollback Path
|
|
15
15
|
- [ ] Migration Reversibility
|
|
16
16
|
- [ ] Feature-Flag Kill Switch
|
|
17
17
|
- [ ] Structured Logging
|
|
18
18
|
- [ ] Metrics & Tracing
|
|
19
19
|
- [ ] Alerting & SLOs
|
|
20
|
-
- [ ] Timeouts & Cancellation
|
|
21
|
-
- [ ] Retry & Backoff
|
|
22
20
|
- [ ] Graceful Shutdown
|
|
23
|
-
- [ ]
|
|
21
|
+
- [ ] Dependency barriers
|
|
24
22
|
- [ ] Runbook Coverage
|
|
25
23
|
- [ ] Health & Readiness
|
|
26
24
|
- [ ] On-Call Escalation
|
|
@@ -86,6 +86,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
87
|
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns, each run from the repo root. One tri-state per key: absent uses the default shown; an explicit `null` disables an optional gate (`typecheck`, `lint`, `formatCheck`) — close reports it as skipped (`<gate>-disabled`) and runs nothing; a string is that command. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-tool pair in one script and name that. |
|
|
88
88
|
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`). Mandatory: `null` is rejected. |
|
|
89
|
+
| `commands.testChanged` | No | `string` \| `null` | — | Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files. Absent or `null` keeps the full re-run. |
|
|
89
90
|
| `commands.typecheck` | No | `string` \| `null` | `"npm run typecheck"` | Static type-check command run as a close-validation gate. An explicit `null` disables the gate for projects with no type layer (skip reason `typecheck-disabled`). The empty string is rejected so a typo cannot silently disable it. |
|
|
90
91
|
| `commands.lint` | No | `string` \| `null` | `"npm run lint"` | Lint command run as a close-validation gate and by the handoff preflight. An explicit `null` disables both (skip reason `lint-disabled`). Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. |
|
|
91
92
|
| `commands.formatCheck` | No | `string` \| `null` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`). |
|
|
@@ -258,6 +259,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
258
259
|
| `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
|
|
259
260
|
| `ci.advisoryAllowlist` | No | `array<string>` | `[]` | Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks. |
|
|
260
261
|
| `ci.rerunAdvisory` | No | `integer` | `0` | Story #5266. How many times close may re-run a failed advisory workflow run before blocking on it, per close invocation. Default 0: close spends no CI minutes and issues no GitHub mutation on an advisory red unless asked. At n > 0 the failed run(s) are re-run within that allowance and the merge wait re-polls inside its existing budget, landing or blocking on the re-run verdict. Overridden per invocation by --rerun-advisory <n>. |
|
|
262
|
+
| `pullRequest` | No | `object` | — | Story #5875. What close writes into the pull request it opens, beyond the title and the `Closes #<id>` line. |
|
|
263
|
+
| `pullRequest.bodyTrailers` | No | `array<string>` | `[]` | Story #5875. Git-trailer keys close lifts from the Story branch commits into the PR body, for a consumer whose required check reads a body line (e.g. `Policy-impact`). For each key the last branch commit carrying `<Key>: <value>` as a trailer wins, and the line is appended after the auto-opened marker and before any `BREAKING CHANGE:` footer. A key no commit carries appends nothing and logs one info line. Workers record the value with `git commit --trailer`. Default [] leaves the body unchanged. |
|
|
261
264
|
| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343. |
|
|
262
265
|
| `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full entry-doc (AGENTS.md or CLAUDE.md) @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
|
|
263
266
|
| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | `"standard"` | Acceptance-ceremony depth — who authors the Story acceptance verdict. minimal and standard (default) = the inline self-eval, whatever the diff touches; strict = a fresh-context maker-blind critic. Review depth is a separate decision and still derives `deep` for any sensitive path (review-depth.js). |
|
|
@@ -51,7 +51,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
51
51
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
52
52
|
description, edit the workflow file’s front-matter and regenerate.
|
|
53
53
|
|
|
54
|
-
## Commands (
|
|
54
|
+
## Commands (37)
|
|
55
55
|
|
|
56
56
|
| Command | Description |
|
|
57
57
|
| --- | --- |
|
|
@@ -73,6 +73,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
73
73
|
| `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
|
|
74
74
|
| `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
|
|
75
75
|
| `/audit-red-team` | Audit the project as a goal-directed adversary — attack paths that chain two or more crossings, abuse of intended features, agent exposure to hostile repository or inbound content, hostile operations and operator hazards — graded under a reproduced-or-reasoned evidence bar. A deliberately-global lens that runs on any project. |
|
|
76
|
+
| `/audit-resilience` | Audit every external dependency, platform binding and cross-service seam: whether failure is bounded, whether the system degrades on purpose, what the user sees, and whether a human is told and how fast. A deliberately-global lens that builds a dependency inventory and follows each failure to a human. |
|
|
76
77
|
| `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, auth boundaries, and the trust-boundary attack classes the baseline is silent on (business logic, SSRF/traversal, deserialization, crypto misuse, feature abuse, LLM tool-binding); emit a structured High/Medium/Low findings report. |
|
|
77
78
|
| `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
|
|
78
79
|
| `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
|
|
@@ -186,6 +186,14 @@ alongside the failing check-run identity. On green it adjudicates:
|
|
|
186
186
|
digest) before the delivery proceeds.
|
|
187
187
|
- **New head SHA** → fix at source. The digest is retired, auto-merge is
|
|
188
188
|
re-armed, and the delivery continues unobstructed.
|
|
189
|
+
- **Same head SHA, every recorded failure advisory, each now green**
|
|
190
|
+
(`advisory-cleared`) → an advisory red disarmed the PR under
|
|
191
|
+
`delivery.ci.blockOnAdvisoryFailure` (the digest records each failure's
|
|
192
|
+
`required: false`), and the check has since gone green — a body fix or a
|
|
193
|
+
re-run, no new commit. The merge wait (a `--wait` resume included)
|
|
194
|
+
re-arms auto-merge once and lands. A required red, a still-red or unread
|
|
195
|
+
advisory check, or a digest without the `required` flag keeps the
|
|
196
|
+
verdicts above; `delivery.ci.autoMerge: 'strict'` never re-arms.
|
|
189
197
|
|
|
190
198
|
A delivery that never went red has no digest and is untouched.
|
|
191
199
|
|
|
@@ -84,6 +84,15 @@
|
|
|
84
84
|
"description": "Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`). Mandatory: `null` is rejected.",
|
|
85
85
|
"default": "npm test"
|
|
86
86
|
},
|
|
87
|
+
"testChanged": {
|
|
88
|
+
"type": ["string", "null"],
|
|
89
|
+
"minLength": 1,
|
|
90
|
+
"not": {
|
|
91
|
+
"type": "string",
|
|
92
|
+
"pattern": "([;&|`]|\\$\\()"
|
|
93
|
+
},
|
|
94
|
+
"description": "Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files. Absent or `null` keeps the full re-run."
|
|
95
|
+
},
|
|
87
96
|
"typecheck": {
|
|
88
97
|
"type": ["string", "null"],
|
|
89
98
|
"minLength": 1,
|
|
@@ -1458,6 +1467,23 @@
|
|
|
1458
1467
|
},
|
|
1459
1468
|
"additionalProperties": false
|
|
1460
1469
|
},
|
|
1470
|
+
"pullRequest": {
|
|
1471
|
+
"type": "object",
|
|
1472
|
+
"description": "Story #5875. What close writes into the pull request it opens, beyond the title and the `Closes #<id>` line.",
|
|
1473
|
+
"properties": {
|
|
1474
|
+
"bodyTrailers": {
|
|
1475
|
+
"type": "array",
|
|
1476
|
+
"items": {
|
|
1477
|
+
"type": "string",
|
|
1478
|
+
"pattern": "^[A-Za-z][A-Za-z0-9-]*$"
|
|
1479
|
+
},
|
|
1480
|
+
"uniqueItems": true,
|
|
1481
|
+
"description": "Story #5875. Git-trailer keys close lifts from the Story branch commits into the PR body, for a consumer whose required check reads a body line (e.g. `Policy-impact`). For each key the last branch commit carrying `<Key>: <value>` as a trailer wins, and the line is appended after the auto-opened marker and before any `BREAKING CHANGE:` footer. A key no commit carries appends nothing and logs one info line. Workers record the value with `git commit --trailer`. Default [] leaves the body unchanged.",
|
|
1482
|
+
"default": []
|
|
1483
|
+
}
|
|
1484
|
+
},
|
|
1485
|
+
"additionalProperties": false
|
|
1486
|
+
},
|
|
1461
1487
|
"routing": {
|
|
1462
1488
|
"type": "object",
|
|
1463
1489
|
"description": "v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343.",
|
|
@@ -196,8 +196,7 @@
|
|
|
196
196
|
"rollback",
|
|
197
197
|
"error budget",
|
|
198
198
|
"on-call",
|
|
199
|
-
"incident"
|
|
200
|
-
"resilience"
|
|
199
|
+
"incident"
|
|
201
200
|
],
|
|
202
201
|
"filePatterns": [
|
|
203
202
|
"**/Dockerfile",
|
|
@@ -482,6 +481,49 @@
|
|
|
482
481
|
},
|
|
483
482
|
"scope": "global",
|
|
484
483
|
"substitutionKeys": []
|
|
484
|
+
},
|
|
485
|
+
"audit-resilience": {
|
|
486
|
+
"triggers": {
|
|
487
|
+
"gates": ["gate1", "gate3"],
|
|
488
|
+
"keywords": [
|
|
489
|
+
"resilience",
|
|
490
|
+
"graceful degradation",
|
|
491
|
+
"fallback",
|
|
492
|
+
"timeout",
|
|
493
|
+
"retry",
|
|
494
|
+
"backoff",
|
|
495
|
+
"idempotency",
|
|
496
|
+
"idempotent",
|
|
497
|
+
"circuit breaker",
|
|
498
|
+
"outage",
|
|
499
|
+
"upstream",
|
|
500
|
+
"webhook",
|
|
501
|
+
"reconcile",
|
|
502
|
+
"reconciliation",
|
|
503
|
+
"dead letter",
|
|
504
|
+
"alerting",
|
|
505
|
+
"pager",
|
|
506
|
+
"on-call"
|
|
507
|
+
],
|
|
508
|
+
"filePatterns": [
|
|
509
|
+
"**/webhooks/**",
|
|
510
|
+
"**/webhook/**",
|
|
511
|
+
"**/integrations/**",
|
|
512
|
+
"**/adapters/**",
|
|
513
|
+
"**/providers/**",
|
|
514
|
+
"**/*outbox*",
|
|
515
|
+
"**/*retry*",
|
|
516
|
+
"**/*queue*",
|
|
517
|
+
"**/wrangler.toml",
|
|
518
|
+
"**/wrangler.json",
|
|
519
|
+
"**/wrangler.jsonc",
|
|
520
|
+
"**/serverless.yml",
|
|
521
|
+
"**/serverless.yaml"
|
|
522
|
+
]
|
|
523
|
+
},
|
|
524
|
+
"target": "integrations",
|
|
525
|
+
"scope": "global",
|
|
526
|
+
"substitutionKeys": []
|
|
485
527
|
}
|
|
486
528
|
},
|
|
487
529
|
"sensitivePaths": {
|
|
@@ -61,8 +61,8 @@
|
|
|
61
61
|
},
|
|
62
62
|
"target": {
|
|
63
63
|
"type": "string",
|
|
64
|
-
"enum": ["web", "data-model", "policies", "any"],
|
|
65
|
-
"description": "Target-applicability gate: the kind of project this lens can say anything about. `web` — the lens reads a rendered web surface (pages, routes, HTML/CSS, design tokens) and is skipped entirely on a project that has none, however well its keyword or file-pattern triggers match. `data-model` — the lens reads a persistence layer (ORM models, schema migrations, seed data) and is skipped entirely on a project that has none. `policies` — the lens reads a published customer-facing policy corpus (Terms, Privacy, Cookie, refund/cancellation, consent and waiver text) and is skipped entirely on a project that has none. `any` — always applicable. ABSENT MEANS `any`: omitting the key never changes a lens's behaviour. Applicability is decided by a probe in lib/audit-suite/selector.js from observables in the consumer's own checkout — hasWebSurface() for `web` (configured navigability routeGlobs, a declared web-framework dependency, or a tracked .html/.css/.jsx/.tsx source file), hasPersistenceLayer() for `data-model` (a declared ORM dependency, a database migrations directory, or a tracked .prisma/.sql schema file), hasPolicyCorpus() for `policies` (configured project.policies.corpusGlobs, or a policy text file under a policies/ or legal/ directory or whose basename carries an explicit policy compound such as privacy-policy or terms-of-service) — and, outside project.policies.corpusGlobs, NOT from an .agentrc key, so a consumer with a real surface keeps these lenses with no configuration. Each probe fails OPEN: an indeterminate answer treats the project as capable, because a wasted lens run is recoverable and silently dropped coverage is not.",
|
|
64
|
+
"enum": ["web", "data-model", "policies", "integrations", "any"],
|
|
65
|
+
"description": "Target-applicability gate: the kind of project this lens can say anything about. `web` — the lens reads a rendered web surface (pages, routes, HTML/CSS, design tokens) and is skipped entirely on a project that has none, however well its keyword or file-pattern triggers match. `data-model` — the lens reads a persistence layer (ORM models, schema migrations, seed data) and is skipped entirely on a project that has none. `policies` — the lens reads a published customer-facing policy corpus (Terms, Privacy, Cookie, refund/cancellation, consent and waiver text) and is skipped entirely on a project that has none. `integrations` — the lens reads a project's external dependencies (third-party SDKs, outbound calls, platform bindings) and is skipped entirely on a project that has none. `any` — always applicable. ABSENT MEANS `any`: omitting the key never changes a lens's behaviour. Applicability is decided by a probe in lib/audit-suite/selector.js from observables in the consumer's own checkout — hasWebSurface() for `web` (configured navigability routeGlobs, a declared web-framework dependency, or a tracked .html/.css/.jsx/.tsx source file), hasPersistenceLayer() for `data-model` (a declared ORM dependency, a database migrations directory, or a tracked .prisma/.sql schema file), hasPolicyCorpus() for `policies` (configured project.policies.corpusGlobs, or a policy text file under a policies/ or legal/ directory or whose basename carries an explicit policy compound such as privacy-policy or terms-of-service), hasExternalDependencies() for `integrations` (a declared integration SDK or HTTP-client dependency, a platform-binding config such as wrangler.toml or serverless.yml, or an outbound call in non-test source) — and, outside project.policies.corpusGlobs, NOT from an .agentrc key, so a consumer with a real surface keeps these lenses with no configuration. Each probe fails OPEN: an indeterminate answer treats the project as capable, because a wasted lens run is recoverable and silently dropped coverage is not.",
|
|
66
66
|
"default": "any"
|
|
67
67
|
},
|
|
68
68
|
"substitutionKeys": {
|
|
@@ -227,12 +227,26 @@
|
|
|
227
227
|
},
|
|
228
228
|
"suiteTimings": {
|
|
229
229
|
"type": ["object", "null"],
|
|
230
|
-
"description": "Story #5485 — the
|
|
231
|
-
"required": ["lockWaitMs", "hostWaitMs", "testRunMs"],
|
|
230
|
+
"description": "Story #5485 — the last full-suite run split into three separate figures: lockWaitMs (queued on the host full-suite lock), hostWaitMs (spawn until the suite signalled MANDREL_SUITE_READY_FILE; null when it did not use the handshake) and testRunMs (the test phase the coverage.timeoutMs kill bound applies to). Story #5879 — source says which run: close (this close spawned the suite) or credited-run (close honoured the handoff's credited run, whose figures these are); spawns lists every suite spawn of that run in order. null when neither ran a full suite.",
|
|
231
|
+
"required": ["lockWaitMs", "hostWaitMs", "testRunMs", "source", "spawns"],
|
|
232
232
|
"properties": {
|
|
233
233
|
"lockWaitMs": { "type": "number", "minimum": 0 },
|
|
234
234
|
"hostWaitMs": { "type": ["number", "null"], "minimum": 0 },
|
|
235
|
-
"testRunMs": { "type": "number", "minimum": 0 }
|
|
235
|
+
"testRunMs": { "type": "number", "minimum": 0 },
|
|
236
|
+
"source": { "enum": ["close", "credited-run"] },
|
|
237
|
+
"spawns": {
|
|
238
|
+
"type": "array",
|
|
239
|
+
"items": {
|
|
240
|
+
"type": "object",
|
|
241
|
+
"required": ["lockWaitMs", "hostWaitMs", "testRunMs"],
|
|
242
|
+
"properties": {
|
|
243
|
+
"lockWaitMs": { "type": "number", "minimum": 0 },
|
|
244
|
+
"hostWaitMs": { "type": ["number", "null"], "minimum": 0 },
|
|
245
|
+
"testRunMs": { "type": "number", "minimum": 0 }
|
|
246
|
+
},
|
|
247
|
+
"additionalProperties": false
|
|
248
|
+
}
|
|
249
|
+
}
|
|
236
250
|
},
|
|
237
251
|
"additionalProperties": false
|
|
238
252
|
},
|
|
@@ -72,6 +72,16 @@
|
|
|
72
72
|
"type": ["string", "null"],
|
|
73
73
|
"description": "Optional sha256 (or other stable digest) of the byte-identical inputs the gate consumed. When present, shouldSkip() will match on this even if the commit SHA has moved — letting docs-only or whitespace-only commits skip an unchanged gate."
|
|
74
74
|
},
|
|
75
|
+
"scope": {
|
|
76
|
+
"type": "string",
|
|
77
|
+
"enum": ["full", "delta"],
|
|
78
|
+
"description": "Optional note on how the pass was earned. `delta` is close's `test` delta re-credit: after a base sync, only the tests affected by the commits since `since` ran (`project.commands.testChanged`), and the record credits the merged tree under the full-suite identity."
|
|
79
|
+
},
|
|
80
|
+
"since": {
|
|
81
|
+
"type": "string",
|
|
82
|
+
"pattern": "^[0-9a-f]{7,64}$",
|
|
83
|
+
"description": "With `scope: delta`, the credited commit the affected-tests run was keyed on."
|
|
84
|
+
},
|
|
75
85
|
"timestamp": {
|
|
76
86
|
"type": "string",
|
|
77
87
|
"format": "date-time",
|
|
@@ -445,6 +445,80 @@ export function hasPolicyCorpus({ config, projectRoot = PROJECT_ROOT } = {}) {
|
|
|
445
445
|
return result;
|
|
446
446
|
}
|
|
447
447
|
|
|
448
|
+
/** Integration families, matched segment-wise like {@link WEB_FRAMEWORK_PACKAGES}. */
|
|
449
|
+
const INTEGRATION_PACKAGES = Object.freeze(
|
|
450
|
+
'stripe clerk auth0 resend sendgrid postmark mailgun nodemailer twilio telnyx aws-sdk google-cloud pinecone openai anthropic-ai sentry axios got node-fetch undici ky'.split(
|
|
451
|
+
' ',
|
|
452
|
+
),
|
|
453
|
+
);
|
|
454
|
+
|
|
455
|
+
const BINDING_CONFIG_FILE_PATTERN =
|
|
456
|
+
/^(wrangler\.(toml|jsonc?)|serverless\.(ya?ml|ts)|Chart\.yaml)$/;
|
|
457
|
+
|
|
458
|
+
const OUTBOUND_SOURCE_PATTERN = /\.(c?js|mjs|tsx?|py|go)$/;
|
|
459
|
+
|
|
460
|
+
const OUTBOUND_CALL_PATTERN =
|
|
461
|
+
/\bfetch\(|\bhttps?\.request\(|\brequests\.(get|post|put|patch|delete)\(|\bhttpx\.|\bhttp\.Get\(/;
|
|
462
|
+
|
|
463
|
+
const OUTBOUND_SNIFF_BYTES = 64 * 1024;
|
|
464
|
+
|
|
465
|
+
/** @type {Map<string, boolean>} */
|
|
466
|
+
const _externalDepsFsCache = new Map();
|
|
467
|
+
|
|
468
|
+
/** Test-only. */
|
|
469
|
+
export function _resetExternalDependenciesCache() {
|
|
470
|
+
_externalDepsFsCache.clear();
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
const TEST_FILE_PATTERN = /\.(test|spec)\./;
|
|
474
|
+
|
|
475
|
+
/** First {@link OUTBOUND_SNIFF_BYTES} of a file, or `''` when unreadable. */
|
|
476
|
+
function readHead(file) {
|
|
477
|
+
try {
|
|
478
|
+
return readFileSync(file, 'utf8').slice(0, OUTBOUND_SNIFF_BYTES);
|
|
479
|
+
} catch {
|
|
480
|
+
return '';
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
function hasOutboundCall(dir, name) {
|
|
485
|
+
return (
|
|
486
|
+
OUTBOUND_SOURCE_PATTERN.test(name) &&
|
|
487
|
+
!TEST_FILE_PATTERN.test(name) &&
|
|
488
|
+
OUTBOUND_CALL_PATTERN.test(readHead(path.join(dir, name)))
|
|
489
|
+
);
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
function isIntegrationMarker(dir, name) {
|
|
493
|
+
return BINDING_CONFIG_FILE_PATTERN.test(name) || hasOutboundCall(dir, name);
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/** `null` from either signal is indeterminate, not false — fail open. */
|
|
497
|
+
function probeExternalDependencies(root) {
|
|
498
|
+
return (
|
|
499
|
+
declaresDependencyIn(root, INTEGRATION_PACKAGES) !== false ||
|
|
500
|
+
scanNearRoot(root, { isMarkerFile: isIntegrationMarker }) !== false
|
|
501
|
+
);
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
/**
|
|
505
|
+
* Applicability predicate for `target: "integrations"` lenses: an integration
|
|
506
|
+
* SDK or HTTP-client dependency, a platform-binding config, or an outbound call
|
|
507
|
+
* in non-test source. Fails OPEN like {@link hasWebSurface}.
|
|
508
|
+
*
|
|
509
|
+
* @param {{ config?: object|null, projectRoot?: string }} [params]
|
|
510
|
+
* @returns {boolean}
|
|
511
|
+
*/
|
|
512
|
+
export function hasExternalDependencies({ projectRoot = PROJECT_ROOT } = {}) {
|
|
513
|
+
if (!_externalDepsFsCache.has(projectRoot)) {
|
|
514
|
+
_externalDepsFsCache.set(
|
|
515
|
+
projectRoot,
|
|
516
|
+
probeExternalDependencies(projectRoot),
|
|
517
|
+
);
|
|
518
|
+
}
|
|
519
|
+
return _externalDepsFsCache.get(projectRoot);
|
|
520
|
+
}
|
|
521
|
+
|
|
448
522
|
/** Single file × single glob, with the project's matcher semantics (`dot: true`). */
|
|
449
523
|
export function matchesFilePattern(pattern, file) {
|
|
450
524
|
return picomatch(pattern, { dot: true })(file);
|
|
@@ -531,6 +605,7 @@ export function changeSetLacksSiblingTest(changedFiles) {
|
|
|
531
605
|
* @param {typeof hasWebSurface} [params.hasWebSurfaceFn]
|
|
532
606
|
* @param {typeof hasPersistenceLayer} [params.hasPersistenceLayerFn]
|
|
533
607
|
* @param {typeof hasPolicyCorpus} [params.hasPolicyCorpusFn]
|
|
608
|
+
* @param {typeof hasExternalDependencies} [params.hasExternalDependenciesFn]
|
|
534
609
|
*/
|
|
535
610
|
export async function selectAudits({
|
|
536
611
|
ticketId,
|
|
@@ -545,6 +620,7 @@ export async function selectAudits({
|
|
|
545
620
|
hasWebSurfaceFn = hasWebSurface,
|
|
546
621
|
hasPersistenceLayerFn = hasPersistenceLayer,
|
|
547
622
|
hasPolicyCorpusFn = hasPolicyCorpus,
|
|
623
|
+
hasExternalDependenciesFn = hasExternalDependencies,
|
|
548
624
|
}) {
|
|
549
625
|
const config = resolveConfig();
|
|
550
626
|
const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
|
|
@@ -594,6 +670,7 @@ export async function selectAudits({
|
|
|
594
670
|
hasWebSurfaceFn,
|
|
595
671
|
hasPersistenceLayerFn,
|
|
596
672
|
hasPolicyCorpusFn,
|
|
673
|
+
hasExternalDependenciesFn,
|
|
597
674
|
}),
|
|
598
675
|
});
|
|
599
676
|
|
|
@@ -740,7 +817,7 @@ function matchesAnyKeyword(keywords, content) {
|
|
|
740
817
|
* Lazily memoized per target, so a roster without a `web` lens never pays the
|
|
741
818
|
* filesystem scan.
|
|
742
819
|
*
|
|
743
|
-
* @param {{ config: object, hasWebSurfaceFn: Function, hasPersistenceLayerFn: Function, hasPolicyCorpusFn: Function }} params
|
|
820
|
+
* @param {{ config: object, hasWebSurfaceFn: Function, hasPersistenceLayerFn: Function, hasPolicyCorpusFn: Function, hasExternalDependenciesFn: Function }} params
|
|
744
821
|
* @returns {(target: string) => boolean}
|
|
745
822
|
*/
|
|
746
823
|
function makeTargetApplicabilityProbe({
|
|
@@ -748,11 +825,13 @@ function makeTargetApplicabilityProbe({
|
|
|
748
825
|
hasWebSurfaceFn,
|
|
749
826
|
hasPersistenceLayerFn,
|
|
750
827
|
hasPolicyCorpusFn,
|
|
828
|
+
hasExternalDependenciesFn,
|
|
751
829
|
}) {
|
|
752
830
|
const probes = {
|
|
753
831
|
web: hasWebSurfaceFn,
|
|
754
832
|
'data-model': hasPersistenceLayerFn,
|
|
755
833
|
policies: hasPolicyCorpusFn,
|
|
834
|
+
integrations: hasExternalDependenciesFn,
|
|
756
835
|
};
|
|
757
836
|
const memo = new Map();
|
|
758
837
|
return (target) => {
|
|
@@ -91,19 +91,32 @@ export function claimLockEventSink(env = process.env, { fsImpl = fs } = {}) {
|
|
|
91
91
|
}
|
|
92
92
|
|
|
93
93
|
/**
|
|
94
|
-
* Waits sum, an expiry sticks, the last holder wins;
|
|
94
|
+
* Waits sum, an expiry sticks, the last holder wins; `spawns` keeps every
|
|
95
|
+
* suite's timings in order and `suiteTimings` is the last of them.
|
|
95
96
|
*
|
|
96
97
|
* @param {object[]} events
|
|
97
|
-
* @returns {{ lockWait: object|null, suiteTimings: object|null }}
|
|
98
|
+
* @returns {{ lockWait: object|null, suiteTimings: object|null, spawns: object[] }}
|
|
98
99
|
*/
|
|
99
100
|
export function summarizeLockEvents(events) {
|
|
100
101
|
let lockWait = null;
|
|
101
|
-
|
|
102
|
+
const spawns = [];
|
|
102
103
|
for (const event of events.filter((e) => e.kind !== 'lock-progress')) {
|
|
103
104
|
if (event.kind === 'lock-wait') lockWait = mergeLockWait(lockWait, event);
|
|
104
|
-
else
|
|
105
|
+
else spawns.push(timingsOf(event));
|
|
105
106
|
}
|
|
106
|
-
return { lockWait, suiteTimings };
|
|
107
|
+
return { lockWait, suiteTimings: spawns.at(-1) ?? null, spawns };
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* The envelope's `suiteTimings`: the last spawn tagged with the run it came
|
|
112
|
+
* from, beside every spawn; `null` when the run spawned none.
|
|
113
|
+
*
|
|
114
|
+
* @param {{ suiteTimings: object|null, spawns: object[] }} summary
|
|
115
|
+
* @param {'close'|'credited-run'} source
|
|
116
|
+
* @returns {object|null}
|
|
117
|
+
*/
|
|
118
|
+
export function sourcedTimings({ suiteTimings, spawns }, source) {
|
|
119
|
+
return suiteTimings && { ...suiteTimings, source, spawns };
|
|
107
120
|
}
|
|
108
121
|
|
|
109
122
|
function mergeLockWait(tally, event) {
|
|
@@ -35,6 +35,9 @@ import {
|
|
|
35
35
|
* @property {{ reason: string }} [skip] - Pre-decided skip: recorded, never spawned.
|
|
36
36
|
* @property {Record<string, string>} [env] - Overlay merged over `process.env` for this gate's child only.
|
|
37
37
|
* @property {boolean} [lockEventChannel] - The child reports on close's lock-event channel.
|
|
38
|
+
* @property {{ cmd: string, args: string[] }} [evidenceIdentity] - Evidence argv, if not the spawned one.
|
|
39
|
+
* @property {{ scope: 'delta', since: string }} [evidenceNote]
|
|
40
|
+
* @property {string} [label]
|
|
38
41
|
* @property {(cmd: string, args: string[], opts: { cwd: string, gateName?: string, log?: (m: string) => void, signal?: AbortSignal, env?: Record<string, string> }) => Promise<{ status: number }> | { status: number }} [run]
|
|
39
42
|
* - In-process runner used instead of spawning `cmd`/`args`.
|
|
40
43
|
*/
|
|
@@ -108,7 +111,9 @@ function isCoverageCaptureActive(config, scripts) {
|
|
|
108
111
|
/**
|
|
109
112
|
* The plain `test` gate, unless coverage-capture will run the suite — every
|
|
110
113
|
* close must keep exactly one working test gate. Its argv is
|
|
111
|
-
* `project.commands.test` (default `npm test`)
|
|
114
|
+
* `project.commands.test` (default `npm test`); after a base move close's
|
|
115
|
+
* phase may swap it for the delta re-credit (`test-delta.js`), which runs
|
|
116
|
+
* `testChanged` keyed on `MANDREL_CHANGED_SINCE`.
|
|
112
117
|
*
|
|
113
118
|
* @param {boolean} coverageCaptureRunsSuite
|
|
114
119
|
* @param {object|undefined|null} config - Canonical resolved config.
|
|
@@ -210,6 +210,7 @@ export async function runCloseValidation({
|
|
|
210
210
|
exitCode: 0,
|
|
211
211
|
durationMs,
|
|
212
212
|
inputFingerprint: gate.inputFingerprint ?? treeSha,
|
|
213
|
+
...gate.evidenceNote,
|
|
213
214
|
},
|
|
214
215
|
evidenceStoreOpts,
|
|
215
216
|
);
|
|
@@ -227,7 +228,7 @@ export async function runCloseValidation({
|
|
|
227
228
|
*/
|
|
228
229
|
const dispatchGate = async (gate, signal, configHash) => {
|
|
229
230
|
log(
|
|
230
|
-
`[close-validation] ▶ ${gate.name}${worktreePath ? ` (cwd=${worktreePath})` : ''}`,
|
|
231
|
+
`[close-validation] ▶ ${gate.label ?? gate.name}${worktreePath ? ` (cwd=${worktreePath})` : ''}`,
|
|
231
232
|
);
|
|
232
233
|
if (typeof onGateStart === 'function') onGateStart(gate);
|
|
233
234
|
const dispatcher = typeof gate.run === 'function' ? gate.run : runner;
|
|
@@ -284,11 +285,7 @@ export async function runCloseValidation({
|
|
|
284
285
|
});
|
|
285
286
|
return;
|
|
286
287
|
}
|
|
287
|
-
const configHash =
|
|
288
|
-
cmd: execution.cmd,
|
|
289
|
-
args: execution.args,
|
|
290
|
-
cwd: spawnCwd,
|
|
291
|
-
});
|
|
288
|
+
const configHash = gateConfigHash(gate, execution, spawnCwd);
|
|
292
289
|
const verdict = evidenceVerdict(gate, configHash);
|
|
293
290
|
if (verdict.skip) {
|
|
294
291
|
skipped.push({ gate, reason: verdict.reason });
|
|
@@ -359,6 +356,12 @@ export async function runCloseValidation({
|
|
|
359
356
|
return { ok: failed.length === 0, failed, skipped };
|
|
360
357
|
}
|
|
361
358
|
|
|
359
|
+
/** The gate's `evidenceIdentity` argv hash, else its spawned argv's. */
|
|
360
|
+
function gateConfigHash(gate, execution, cwd) {
|
|
361
|
+
const { cmd, args } = gate.evidenceIdentity ?? execution;
|
|
362
|
+
return hashCommandConfig({ cmd, args, cwd });
|
|
363
|
+
}
|
|
364
|
+
|
|
362
365
|
/**
|
|
363
366
|
* The `fullSuiteLock` gate shares coverage capture's timeout
|
|
364
367
|
* (`coverage.timeoutMs`) so a hung suite fails instead of holding the host
|
|
@@ -453,11 +456,7 @@ async function runSerialGates(
|
|
|
453
456
|
});
|
|
454
457
|
continue;
|
|
455
458
|
}
|
|
456
|
-
const configHash =
|
|
457
|
-
cmd: execution.cmd,
|
|
458
|
-
args: execution.args,
|
|
459
|
-
cwd: spawnCwd,
|
|
460
|
-
});
|
|
459
|
+
const configHash = gateConfigHash(gate, execution, spawnCwd);
|
|
461
460
|
const verdict = evidenceVerdict(gate, configHash);
|
|
462
461
|
if (verdict.skip) {
|
|
463
462
|
skipped.push({ gate, reason: verdict.reason });
|