mandrel 2.73.0 → 2.75.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/README.md +3 -0
- package/.agents/docs/runbooks/mods.md +157 -0
- package/.agents/mods/mandrel-status/.claude-plugin/plugin.json +9 -0
- package/.agents/mods/mandrel-status/hooks/hooks.json +1 -0
- package/.agents/mods/mandrel-status/hooks/register.tsx +1068 -0
- package/.agents/mods/mandrel-status/types/index.d.ts +90 -0
- package/.agents/schemas/story-progress.schema.json +48 -0
- package/.agents/scripts/lib/audit-suite/selector.js +6 -1
- package/.agents/scripts/lib/close-validation/gates.js +37 -9
- package/.agents/scripts/lib/config/temp-paths.js +15 -0
- package/.agents/scripts/lib/coverage-capture-affected.js +5 -16
- package/.agents/scripts/lib/coverage-capture-delta.js +25 -1
- package/.agents/scripts/lib/coverage-capture-fullscope.js +8 -5
- package/.agents/scripts/lib/coverage-capture-incremental.js +8 -5
- package/.agents/scripts/lib/coverage-capture.js +129 -8
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +15 -18
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
- package/.agents/scripts/lib/orchestration/story-handoff.js +21 -7
- package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
- package/.agents/workflows/helpers/deliver-reference.md +12 -5
- package/.agents/workflows/mandrel-update.md +4 -0
- package/docs/CHANGELOG.md +21 -0
- package/lib/cli/sync.js +38 -0
- package/package.json +1 -1
package/.agents/README.md
CHANGED
|
@@ -355,6 +355,7 @@ what keeps that footer refused. The execution-model contract is owned by
|
|
|
355
355
|
| [`scripts/lib/checks/`](scripts/lib/checks/) | Discovery-based self-healing checks registry for preflight, the `diagnose.js` viewer, and retro surfaces. |
|
|
356
356
|
| [`schemas/`](schemas/) | JSON Schema contracts for config, manifests, reports, and persisted runtime artefacts. |
|
|
357
357
|
| [`templates/`](templates/) | Prompt and planning templates used by the orchestration flow. |
|
|
358
|
+
| [`mods/`](mods/) | Beta, opt-in Claude Code mods. Inert until a developer loads one; see [`docs/runbooks/mods.md`](docs/runbooks/mods.md). |
|
|
358
359
|
|
|
359
360
|
---
|
|
360
361
|
|
|
@@ -378,6 +379,8 @@ what keeps that footer refused. The execution-model contract is owned by
|
|
|
378
379
|
| Bootstrap script (project + GitHub setup) | [`scripts/bootstrap.js`](scripts/bootstrap.js) |
|
|
379
380
|
| Adopt the QA workflows (`/qa-explore`, `/qa-assist`, `/qa-run`) in your project | [§ Adopting the QA harness](#adopting-the-qa-harness) |
|
|
380
381
|
| Coordinate two operators on the same repo (lease model) | [§ Multi-developer coordination](#multi-developer-coordination) |
|
|
382
|
+
| Opt into the beta `mandrel-status` band above the prompt | [`docs/runbooks/mods.md`](docs/runbooks/mods.md) |
|
|
383
|
+
| Operator runbooks (listed at the end of every `mandrel sync` / `init` / `update`) | [`docs/runbooks/`](docs/runbooks/) |
|
|
381
384
|
|
|
382
385
|
---
|
|
383
386
|
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Claude Code mods (beta)
|
|
2
|
+
|
|
3
|
+
> **Beta, optional, read-only.** Mandrel works the same with or without a
|
|
4
|
+
> mod. Nothing in Mandrel loads, references or depends on one, and no
|
|
5
|
+
> `.agentrc.json` key turns one on. The decision record is
|
|
6
|
+
> [ADR `20261002-5544`](https://github.com/dsj1984/mandrel/blob/main/docs/decisions.md#adr-20261002-5544-claude-code-mods-are-a-beta-optional-read-only-add-on).
|
|
7
|
+
|
|
8
|
+
A Claude Code mod is a plugin of function hooks: a module that draws on
|
|
9
|
+
Claude Code's own surfaces (a band above the prompt, a pane, a toast) and
|
|
10
|
+
reacts to session events. Mandrel ships its mods under `.agents/mods/`, so
|
|
11
|
+
`mandrel sync` copies them into every consumer checkout. A mod stays inert
|
|
12
|
+
until a developer loads it. This runbook is listed at the end of every
|
|
13
|
+
`mandrel sync`, `init` and `update`, like every file in `docs/runbooks/`.
|
|
14
|
+
|
|
15
|
+
## `mandrel-status`
|
|
16
|
+
|
|
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
|
+
```
|
|
33
|
+
|
|
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.
|
|
84
|
+
|
|
85
|
+
It also toasts once when a terminal envelope appears with `status` `landed`
|
|
86
|
+
or `blocked`. Results already on disk when the session starts are not
|
|
87
|
+
toasted, and a hot reload does not repeat one.
|
|
88
|
+
|
|
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.
|
|
96
|
+
|
|
97
|
+
### Turn it on
|
|
98
|
+
|
|
99
|
+
Per developer, per machine. Pick one:
|
|
100
|
+
|
|
101
|
+
- **Every session:** add the folder's absolute path to
|
|
102
|
+
`CLAUDE_CODE_PLUGIN_DIRS` in the `env` block of `~/.claude/settings.json`
|
|
103
|
+
(separate several paths with the platform's path-list separator):
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"env": {
|
|
108
|
+
"CLAUDE_CODE_PLUGIN_DIRS": "/absolute/path/to/project/.agents/mods/mandrel-status"
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Claude Code reads this variable from the process environment or from user
|
|
114
|
+
settings, never from a project's `.claude/settings.json`. A committed file
|
|
115
|
+
cannot switch the mod on for anyone else. In a directory with no `.agents/`
|
|
116
|
+
folder the mod draws nothing, so a user-wide entry is harmless elsewhere.
|
|
117
|
+
|
|
118
|
+
- **One session:** `claude --plugin-dir .agents/mods/mandrel-status`.
|
|
119
|
+
|
|
120
|
+
Turn it off by removing the entry or the flag.
|
|
121
|
+
|
|
122
|
+
### The read-only invariant
|
|
123
|
+
|
|
124
|
+
A Mandrel mod may only read files (`$.fs.read`, `list`, `stat`, `exists`),
|
|
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
|
|
130
|
+
model. Guardrails stay in `.claude/settings.json` command hooks, which load
|
|
131
|
+
in environments where plugins do not. `claude plugin validate` lists every
|
|
132
|
+
hook and `$` call a mod makes. Check that list against this invariant when
|
|
133
|
+
you change one.
|
|
134
|
+
|
|
135
|
+
### Develop and test
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
claude plugin validate .agents/mods/mandrel-status
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
claude plugin test .agents/mods/mandrel-status
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The tests live in `__tests__/*.test.ts`. They answer the mod's file reads
|
|
146
|
+
from an in-memory checkout and drive the clock by hand. `npm test` does not
|
|
147
|
+
run them, since its tiers collect `*.test.js` only, and CI has no `claude`
|
|
148
|
+
binary. Run both commands locally before you push a change to a mod. The
|
|
149
|
+
npm package excludes `__tests__/`.
|
|
150
|
+
|
|
151
|
+
## Removing mods
|
|
152
|
+
|
|
153
|
+
Delete `.agents/mods/`, this runbook, and its two rows in `.agents/README.md`. Then
|
|
154
|
+
mark the ADR Superseded. No other file references a mod, so no other gate
|
|
155
|
+
changes. Consumers lose the folder on their next `mandrel sync`, which
|
|
156
|
+
prunes files that are no longer in the payload. Anyone who set
|
|
157
|
+
`CLAUDE_CODE_PLUGIN_DIRS` should remove that entry.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{ "modules": ["./register.tsx"] }
|