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.
Files changed (41) hide show
  1. package/.agents/audit-checklists/exceptions.md +24 -0
  2. package/.agents/docs/runbooks/mods.md +78 -16
  3. package/.agents/docs/workflows.md +2 -1
  4. package/.agents/mods/mandrel-status/hooks/register.tsx +942 -108
  5. package/.agents/mods/mandrel-status/types/index.d.ts +67 -11
  6. package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
  7. package/.agents/schemas/audit-rules.json +43 -0
  8. package/.agents/schemas/story-progress.schema.json +48 -0
  9. package/.agents/scripts/audit-exceptions.js +145 -0
  10. package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
  11. package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
  12. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
  13. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
  14. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
  15. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
  16. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
  17. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
  18. package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
  19. package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
  20. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
  21. package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
  22. package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
  23. package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
  24. package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
  25. package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
  26. package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
  27. package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
  28. package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
  29. package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
  30. package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
  31. package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
  32. package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
  33. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  34. package/.agents/scripts/lib/config/temp-paths.js +15 -0
  35. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  36. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
  37. package/.agents/scripts/lib/orchestration/story-handoff.js +7 -0
  38. package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
  39. package/.agents/workflows/audit-exceptions.md +235 -0
  40. package/docs/CHANGELOG.md +20 -0
  41. 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 one dim line above
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
- | State on disk | The line |
21
- | --- | --- |
22
- | A `.worktrees/story-<id>/` with no newer terminal envelope | `mandrel · Story #<id> implementing` |
23
- | …and close has written `close-gates-<id>.log` | `mandrel · Story #<id> closing` |
24
- | …and that log has been quiet for 10 minutes | `… · stalled? no gate output for <n>m` |
25
- | Otherwise, the newest `story-deliver-terminal-<id>.json` from the last 2 hours | `mandrel · Story #<id> <status> · PR #<n> checks <state> · <elapsed>` |
26
- | None of the above, or no `.agents/` in the working directory | nothing |
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
- The files sit under `<tempRoot>/orchestration/`. `tempRoot` is
33
- `project.paths.tempRoot` from `.agentrc.local.json`, then `.agentrc.json`,
34
- and defaults to `temp`. It refreshes on session start, after each turn and
35
- every 15 seconds.
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 no `tool.call`, `prompt.submit`, `command.run` or `session.append`
67
- event. It never writes files, spawns processes, calls the network or the
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 (31)
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. |