mandrel 2.74.0 → 2.76.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/audit-checklists/exceptions.md +24 -0
- package/.agents/docs/runbooks/mods.md +78 -16
- package/.agents/docs/workflows.md +2 -1
- package/.agents/mods/mandrel-status/hooks/register.tsx +942 -108
- package/.agents/mods/mandrel-status/types/index.d.ts +67 -11
- package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
- package/.agents/schemas/audit-rules.json +43 -0
- package/.agents/schemas/story-progress.schema.json +48 -0
- package/.agents/scripts/audit-exceptions.js +145 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
- package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
- package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
- package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
- package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
- package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
- package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
- package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
- package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
- package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
- package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
- package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
- package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/config/temp-paths.js +15 -0
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
- package/.agents/scripts/lib/orchestration/story-handoff.js +7 -0
- package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
- package/.agents/workflows/audit-exceptions.md +235 -0
- package/docs/CHANGELOG.md +20 -0
- package/package.json +1 -1
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
<!-- GENERATED FILE — do not edit by hand.
|
|
2
|
+
Source of truth: .agents/workflows/audit-exceptions.md
|
|
3
|
+
Regenerate: node .agents/scripts/generate-lens-checklists.js
|
|
4
|
+
Drift is gated by: npm run docs:check
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# Exception & Override Audit — authoring checklist
|
|
8
|
+
|
|
9
|
+
> Audit every exception and escape valve — inline suppressions, tool-config exemptions, dependency overrides, patches and allowlists, CI gate exemptions, test skips and code allowlists — and flag the ones that are dead, expired, orphaned, unjustified, or papering over a real fix.
|
|
10
|
+
|
|
11
|
+
Self-check your change against this lens's concerns before you ship:
|
|
12
|
+
|
|
13
|
+
- [ ] `degradations`.
|
|
14
|
+
- [ ] `skipped[]`.
|
|
15
|
+
- [ ] `delegated[]`.
|
|
16
|
+
- [ ] `truncated`.
|
|
17
|
+
- [ ] Dead.
|
|
18
|
+
- [ ] Expired.
|
|
19
|
+
- [ ] Orphaned.
|
|
20
|
+
- [ ] Unjustified.
|
|
21
|
+
- [ ] Fix Properly.
|
|
22
|
+
- [ ] Dead bundle template
|
|
23
|
+
- [ ] Unjustified template
|
|
24
|
+
- [ ] Fix Properly template
|
|
@@ -14,25 +14,85 @@ until a developer loads it. This runbook is listed at the end of every
|
|
|
14
14
|
|
|
15
15
|
## `mandrel-status`
|
|
16
16
|
|
|
17
|
-
[`mods/mandrel-status/`](../../mods/mandrel-status/) draws
|
|
18
|
-
the prompt while you work in a Mandrel checkout
|
|
17
|
+
[`mods/mandrel-status/`](../../mods/mandrel-status/) draws a short band
|
|
18
|
+
above the prompt while you work in a Mandrel checkout. It follows one
|
|
19
|
+
Story: the newest one in flight (a `.worktrees/story-<id>/` with no newer
|
|
20
|
+
terminal envelope), otherwise the newest
|
|
21
|
+
`story-deliver-terminal-<id>.json` from the last 2 hours. With neither, or
|
|
22
|
+
with no `.agents/` in the checkout, it draws nothing.
|
|
23
|
+
|
|
24
|
+
**Line 1** is an outcome glyph (none, `✓` or `✗`), then
|
|
25
|
+
`mandrel · #<id> <title>`, with the PR and its checks on the right when
|
|
26
|
+
they are known. **Line 2** is the stage strip, the current step and the
|
|
27
|
+
time:
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
mandrel · #5552 mandrel-status band v2 · PR #5560 checks pending
|
|
31
|
+
✓ start ─ ✓ build ─ ✓ check ─ ✓ handoff ─ ● close ─ ○ merge · gate lint · 1m10s of usual ~1m30s
|
|
32
|
+
```
|
|
19
33
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
34
|
+
`✓` marks a finished stage, `●` the current one and `○` the ones to come.
|
|
35
|
+
Each stage comes from a file delivery already writes, and the latest
|
|
36
|
+
evidence wins:
|
|
37
|
+
|
|
38
|
+
| Stage | Evidence | Detail shown |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| `start` | `<tempRoot>/orchestration/story-init-result-<id>.log` | `initialized`; the Story title on line 1 comes from this log |
|
|
41
|
+
| `build` | `commit…` lines in the worktree's reflog (`logs/HEAD` under its gitdir) | commit count and the last subject |
|
|
42
|
+
| `check` | the highest `<tempRoot>/scratch/story-<id>/acceptance-verdict-round-<n>.json` | `round <n> · <met>/<total> met` |
|
|
43
|
+
| `handoff` | the newest `story-handoff-<id>-<step>.log`; `story-handoff-<id>.json` ends the stage | the step name, or `handed off` |
|
|
44
|
+
| `close` | `close-gates-<id>.log` | the gate named by its last line's `[name]` prefix |
|
|
45
|
+
| `merge` | a terminal envelope with `status` `pending`, or a progress file in `auto-merge` / `confirm-merge` | the PR number and the phase |
|
|
46
|
+
|
|
47
|
+
A commit made after the last verdict round puts the Story back in `build`.
|
|
48
|
+
When `story-progress-<id>.json` is present and newer than everything else,
|
|
49
|
+
it decides the stage, the step or close phase and the PR number. The band
|
|
50
|
+
never needs it: without it, every stage still shows, and only the close
|
|
51
|
+
sub-phase after validation is unknown.
|
|
52
|
+
|
|
53
|
+
**Learned ETAs.** For each close phase, the band takes the median of
|
|
54
|
+
`phaseDurations` over the newest 30 terminal envelopes on disk, and
|
|
55
|
+
recomputes it at most every 10 minutes. Once a phase has 3 or more samples,
|
|
56
|
+
line 2 reads `<elapsed> of usual ~<median>`. The phase counts as stalled when
|
|
57
|
+
its elapsed time passes the larger of twice the median and 2 minutes. With
|
|
58
|
+
fewer samples, a close whose gate log has been quiet for 10 minutes is
|
|
59
|
+
stalled instead (`stalled? no gate output for <n>m`). Elapsed time runs from
|
|
60
|
+
the progress file's `phaseStartedAt` when it is there, else from when the
|
|
61
|
+
stage's evidence began.
|
|
62
|
+
|
|
63
|
+
**Results.** A `landed` envelope collapses the band to one line:
|
|
64
|
+
`✓ mandrel · #<id> <title> · landed in <elapsed> · PR #<n> · <k> follow-ups`,
|
|
65
|
+
where `k` counts the bullets in `follow-ups-rollup-<id>.md`. A `blocked`,
|
|
66
|
+
`failed` or `escalated` envelope puts its `blocked.blockClass` or
|
|
67
|
+
`failure.reason` on line 1 and replaces line 2 with `next: <nextCommand>`,
|
|
68
|
+
the command that resumes the work.
|
|
69
|
+
|
|
70
|
+
**Run line.** When a `<tempRoot>/run-<id>/ledger.json` was updated in the
|
|
71
|
+
last 2 hours and still has a Story without a `landed` envelope, a third line
|
|
72
|
+
reads `run <landed>/<total> landed · #<id> <stage> · <queued> queued`.
|
|
73
|
+
|
|
74
|
+
**Colors.** Dim by default, yellow when stalled, red for `blocked` /
|
|
75
|
+
`failed` / `escalated`, green for `landed`.
|
|
76
|
+
|
|
77
|
+
**Width.** Under 80 body columns only line 1 shows. Long text is cut short
|
|
78
|
+
with `…`, never wrapped.
|
|
79
|
+
|
|
80
|
+
**Buttons.** `Hide` hides the band for this session until the followed
|
|
81
|
+
Story changes. `Details` opens the `mandrel-status` pane, which lists each
|
|
82
|
+
stage with its start time and duration, the handoff steps, and the close
|
|
83
|
+
phases with their recorded and usual durations.
|
|
27
84
|
|
|
28
85
|
It also toasts once when a terminal envelope appears with `status` `landed`
|
|
29
86
|
or `blocked`. Results already on disk when the session starts are not
|
|
30
87
|
toasted, and a hot reload does not repeat one.
|
|
31
88
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
89
|
+
**Where it reads.** Every path is relative to the main checkout. A session
|
|
90
|
+
running in a linked worktree (for example `.claude/worktrees/<name>`, which
|
|
91
|
+
holds no `temp/` or `.worktrees/`) has a `.git` file reading
|
|
92
|
+
`gitdir: <main>/.git/worktrees/<name>`, and the band reads from that
|
|
93
|
+
`<main>`. `tempRoot` is `project.paths.tempRoot` from
|
|
94
|
+
`.agentrc.local.json`, then `.agentrc.json`, and defaults to `temp`. The
|
|
95
|
+
band refreshes on session start, after each turn and every 15 seconds.
|
|
36
96
|
|
|
37
97
|
### Turn it on
|
|
38
98
|
|
|
@@ -62,9 +122,11 @@ Turn it off by removing the entry or the flag.
|
|
|
62
122
|
### The read-only invariant
|
|
63
123
|
|
|
64
124
|
A Mandrel mod may only read files (`$.fs.read`, `list`, `stat`, `exists`),
|
|
65
|
-
draw (`$.ui.*`), keep session state (`$.state`) and keep time (`$.clock`).
|
|
66
|
-
It hooks
|
|
67
|
-
|
|
125
|
+
draw and open its own pane (`$.ui.*`), keep session state (`$.state`) and keep time (`$.clock`).
|
|
126
|
+
It hooks only `session.start`, `turn.complete` and `ui.render` (the
|
|
127
|
+
`AbovePrompt` band and its own `Pane`), and its buttons only change
|
|
128
|
+
`$.state` or call `$.ui.open`. It hooks no `tool.call`, `prompt.submit`,
|
|
129
|
+
`command.run` or `session.append` event. It never writes files, spawns processes, calls the network or the
|
|
68
130
|
model. Guardrails stay in `.claude/settings.json` command hooks, which load
|
|
69
131
|
in environments where plugins do not. `claude plugin validate` lists every
|
|
70
132
|
hook and `$` call a mod makes. Check that list against this invariant when
|
|
@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
32
32
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
33
33
|
description, edit the workflow file’s front-matter and regenerate.
|
|
34
34
|
|
|
35
|
-
## Commands (
|
|
35
|
+
## Commands (32)
|
|
36
36
|
|
|
37
37
|
| Command | Description |
|
|
38
38
|
| --- | --- |
|
|
@@ -45,6 +45,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
45
45
|
| `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
|
|
46
46
|
| `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
|
|
47
47
|
| `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
|
|
48
|
+
| `/audit-exceptions` | Audit every exception and escape valve — inline suppressions, tool-config exemptions, dependency overrides, patches and allowlists, CI gate exemptions, test skips and code allowlists — and flag the ones that are dead, expired, orphaned, unjustified, or papering over a real fix. |
|
|
48
49
|
| `/audit-mobile` | Audit mobile and tablet UX — layout and viewport correctness, touch ergonomics, responsive assets, and whether anything actually verifies them at a small viewport (static-first, with an optional runtime viewport pass) |
|
|
49
50
|
| `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
|
|
50
51
|
| `/audit-performance` | Audit performance by measuring first — profile hot paths, I/O, memory, and payload against the repo's own numbers — and audit interleaving/partial-failure correctness (TOCTOU, unawaited promises, non-atomic writes) as a first-class dimension. |
|