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 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,9 @@
1
+ {
2
+ "name": "mandrel-status",
3
+ "version": "0.1.0",
4
+ "description": "Beta, read-only: shows the current /mandrel-deliver Story above the prompt",
5
+ "author": {
6
+ "name": "Mandrel"
7
+ },
8
+ "types": "./types/index.d.ts"
9
+ }
@@ -0,0 +1 @@
1
+ { "modules": ["./register.tsx"] }