mandrel 2.82.0 → 2.84.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 +65 -20
- package/.agents/docs/configuration.md +40 -3
- package/.agents/docs/runbooks/mods.md +98 -54
- package/.agents/docs/workflows.md +14 -0
- package/.agents/instructions.md +4 -1
- package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
- package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/boot-sweep.js +42 -13
- package/.agents/scripts/coverage-capture.js +55 -24
- package/.agents/scripts/evidence-gate.js +7 -1
- package/.agents/scripts/generate-workflows-doc.js +14 -0
- package/.agents/scripts/lib/baselines/duplication-scanner.js +26 -2
- package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
- package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
- package/.agents/scripts/lib/close-lock-events.js +109 -0
- package/.agents/scripts/lib/close-validation/commands.js +12 -0
- package/.agents/scripts/lib/close-validation/gates.js +6 -0
- package/.agents/scripts/lib/close-validation/process.js +5 -2
- package/.agents/scripts/lib/close-validation/runner.js +14 -4
- package/.agents/scripts/lib/codex/agents-projection.js +284 -0
- package/.agents/scripts/lib/codex/skills-projection.js +291 -0
- package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
- package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
- package/.agents/scripts/lib/config-resolver.js +5 -42
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/config-settings-schema.js +1 -1
- package/.agents/scripts/lib/full-suite-lock.js +20 -0
- package/.agents/scripts/lib/full-suite-queue.js +24 -56
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/observability/source-classifier.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
- package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +73 -63
- package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +70 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +3 -0
- package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
- package/.agents/scripts/lib/supervised-suite.js +8 -28
- package/.agents/scripts/single-story-init.js +20 -5
- package/.agents/scripts/sync-agentrc.js +5 -3
- package/.agents/scripts/sync-claude-agents.js +20 -0
- package/.agents/scripts/sync-claude-commands.js +64 -27
- package/.agents/scripts/sync-codex-agents.js +36 -0
- package/.agents/scripts/sync-codex-skills.js +36 -0
- package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
- package/.agents/workflows/mandrel-update.md +2 -1
- package/README.md +167 -216
- package/docs/CHANGELOG.md +25 -0
- package/lib/cli/guarded-sync.js +3 -2
- package/lib/cli/registry.js +248 -0
- package/lib/cli/sync-agents.js +5 -2
- package/lib/cli/sync-commands.js +5 -2
- package/lib/cli/sync.js +45 -14
- package/lib/cli/uninstall.js +8 -1
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -2,252 +2,203 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/dsj1984/mandrel/actions/workflows/ci.yml)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
**Mandrel gives your AI coding assistant a disciplined software process.**
|
|
6
|
+
Out of the box, an assistant like Claude Code will happily write code, but it
|
|
7
|
+
has no shared idea of how work gets planned, verified, reviewed, and shipped.
|
|
8
|
+
Mandrel supplies that: a system prompt, rules, skills, and slash-command
|
|
9
|
+
workflows that turn "build me X" into a planned GitHub Story, an isolated
|
|
10
|
+
branch, a tested change, and a reviewed pull request that merges itself once
|
|
11
|
+
CI is green.
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
It is **Claude Code-first** and **GitHub-native**: planning, execution state,
|
|
14
|
+
and history all live in GitHub Issues, Labels, Pull Requests, and Projects V2,
|
|
15
|
+
so there is no extra service to run and every step leaves a visible record.
|
|
10
16
|
|
|
11
|
-
Mandrel
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
You do **not** need a pre-created Git repo or GitHub remote — `bootstrap.js`
|
|
15
|
-
provisions both as part of a cold start (`git init` → `gh repo create --push`
|
|
16
|
-
→ `gh project create`). You need:
|
|
17
|
+
Mandrel ships as the [`mandrel`](https://www.npmjs.com/package/mandrel) npm
|
|
18
|
+
package. `mandrel sync` copies its payload into your project's `.agents/`
|
|
19
|
+
directory, where your assistant reads it.
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
- **`git`** on your `PATH`.
|
|
20
|
-
- **GitHub CLI `gh`** >= 2.40, authenticated — run `gh auth login` once so
|
|
21
|
-
orchestration scripts pick up your token from the OS keychain. A vanilla
|
|
22
|
-
`gh auth login` token does **not** carry the `project` scope needed to
|
|
23
|
-
provision the GitHub Projects V2 board; bootstrap degrades to
|
|
24
|
-
warn-and-skip-board in that case (no hard failure). To enable board
|
|
25
|
-
provisioning, grant the scope with `gh auth refresh -s project` (re-auth
|
|
26
|
-
in the browser when prompted) before running `bootstrap.js`.
|
|
21
|
+
## What's in `.agents/`
|
|
27
22
|
|
|
28
|
-
|
|
23
|
+
| Path | What it is |
|
|
24
|
+
| ---- | ---------- |
|
|
25
|
+
| `instructions.md` | The always-loaded system prompt — the assistant's core operating protocol. |
|
|
26
|
+
| `rules/` | Non-negotiable standards. A small core (security baseline, git conventions) is always on; the rest (testing, API, CI remediation, Gherkin) load when the work calls for them. |
|
|
27
|
+
| `skills/` | Focused guidance loaded on demand: `core/` for universal practice (code review, security, documentation, quality gates), `stack/` for specific tools (Playwright, Gherkin, the QA harness). |
|
|
28
|
+
| `workflows/` | The slash commands — `/mandrel-plan`, `/mandrel-deliver`, the `/audit-*` lenses, QA, and housekeeping. Projected into `.claude/commands/`. |
|
|
29
|
+
| `agents/` | Role-scoped sub-agent contexts (story worker, auditor, critics). Projected into `.claude/agents/`. |
|
|
30
|
+
| `scripts/` | Deterministic Node.js CLIs that do the mechanical work — GitHub state changes, worktrees, quality gates — so the model judges and the scripts execute. |
|
|
31
|
+
| `schemas/`, `templates/` | JSON Schema contracts and the prompt/planning templates the workflows fill in. |
|
|
32
|
+
| `docs/` | Consumer reference: [configuration](.agents/docs/configuration.md) (every `.agentrc.json` key), the [workflow index](.agents/docs/workflows.md), and operator runbooks. |
|
|
33
|
+
| `local/` | Yours. `mandrel sync` never touches it, so project-specific skills and workflow fragments survive upgrades. |
|
|
29
34
|
|
|
30
|
-
|
|
35
|
+
Project settings live in `.agentrc.json` at your repo root. The full tour of
|
|
36
|
+
the bundle is in [`.agents/README.md`](.agents/README.md).
|
|
31
37
|
|
|
32
|
-
|
|
33
|
-
|
|
38
|
+
## The core loop: plan, then deliver
|
|
39
|
+
|
|
40
|
+
Two commands carry almost all of the work.
|
|
41
|
+
|
|
42
|
+
### `/mandrel-plan`
|
|
43
|
+
|
|
44
|
+
[`/mandrel-plan`](.agents/workflows/mandrel-plan.md) turns an idea into a
|
|
45
|
+
ready-to-execute GitHub Story. There are no flags to remember — it works out
|
|
46
|
+
what you meant from what you typed and tells you what it inferred:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
/mandrel-plan let users export their reports as CSV # plan from a description
|
|
50
|
+
/mandrel-plan 4712 # plan an existing issue
|
|
34
51
|
```
|
|
35
52
|
|
|
53
|
+
It gathers context from your repo, then authors a Story whose `## Spec` holds
|
|
54
|
+
the technical plan and whose `acceptance[]` / `verify[]` lists are the contract
|
|
55
|
+
the delivery is held to. It writes **one Story by default**, splitting only when
|
|
56
|
+
the pieces are truly independent; larger efforts can be grouped under a
|
|
57
|
+
container Epic.
|
|
58
|
+
|
|
59
|
+
### `/mandrel-deliver`
|
|
60
|
+
|
|
61
|
+
[`/mandrel-deliver`](.agents/workflows/mandrel-deliver.md) lands the work:
|
|
62
|
+
|
|
36
63
|
```text
|
|
37
|
-
#
|
|
38
|
-
/mandrel-
|
|
39
|
-
/mandrel-deliver
|
|
64
|
+
/mandrel-deliver 4712 # a single Story
|
|
65
|
+
/mandrel-deliver 4700 # an Epic — delivers its open child Stories
|
|
66
|
+
/mandrel-deliver 4712 - 4716 # a range of Stories
|
|
67
|
+
/mandrel-deliver fix the typo in the login page header # direct text, no plan
|
|
40
68
|
```
|
|
41
69
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
70
|
+
Each Story gets its own `story-<id>` branch in an isolated worktree; the
|
|
71
|
+
assistant implements it, checks its work against the acceptance criteria, runs
|
|
72
|
+
the test suite and quality gates, opens a PR, gets it reviewed, and arms
|
|
73
|
+
auto-merge. Multiple Stories are sequenced by their dependencies, with
|
|
74
|
+
independent ones running in parallel sub-agents. Direct text is for small,
|
|
75
|
+
unplanned work: it authors a receipt Story on the fly and escalates to
|
|
76
|
+
`/mandrel-plan` if the work turns out bigger than it looked.
|
|
77
|
+
|
|
78
|
+
The full process — labels, state, review, troubleshooting — is in
|
|
79
|
+
[`docs/SDLC.md`](docs/SDLC.md).
|
|
80
|
+
|
|
81
|
+
## Audits
|
|
82
|
+
|
|
83
|
+
The `/audit-*` workflows are read-only lenses that examine the codebase along
|
|
84
|
+
one dimension and write a findings report (severity, location, recommendation,
|
|
85
|
+
acceptance signal) under `temp/audits/`. They never change code — fixing is a
|
|
86
|
+
separate, planned pass.
|
|
87
|
+
|
|
88
|
+
| Area | Lenses |
|
|
89
|
+
| ---- | ------ |
|
|
90
|
+
| Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions` |
|
|
91
|
+
| Quality & ops | `quality`, `baselines`, `performance`, `devops`, `sre`, `dependencies` |
|
|
92
|
+
| Security & privacy | `security`, `privacy` |
|
|
93
|
+
| Product & UX | `ux-ui`, `accessibility`, `mobile`, `navigability`, `seo` |
|
|
94
|
+
|
|
95
|
+
Run one manually (e.g. `/audit-security`) for a codebase-wide pass, then run
|
|
96
|
+
**`/audit-to-stories`** to group the findings, deduplicate them against open
|
|
97
|
+
issues, and turn them into Stories — feeding them back into
|
|
98
|
+
`/mandrel-plan` → `/mandrel-deliver`. Multi-Story deliveries can also run the
|
|
99
|
+
relevant cross-cutting lenses over the combined change when they finish.
|
|
54
100
|
|
|
55
|
-
|
|
101
|
+
Other workflows cover QA (`/qa-explore`, `/qa-assist`, `/qa-run`), UI
|
|
102
|
+
prototyping (`/prototype`), ad-hoc commits (`/git-deliver`), and housekeeping
|
|
103
|
+
(`/clean-git`, `/clean-worktrees`, `/clean-temp`). See the
|
|
104
|
+
[workflow index](.agents/docs/workflows.md) for the full list.
|
|
56
105
|
|
|
57
|
-
|
|
58
|
-
|
|
106
|
+
## Getting started
|
|
107
|
+
|
|
108
|
+
### Prerequisites
|
|
109
|
+
|
|
110
|
+
- **Node.js** `>=22.22.1 <25`
|
|
111
|
+
- **`git`** on your `PATH`
|
|
112
|
+
- **GitHub CLI `gh`** `>= 2.40`, authenticated with `gh auth login`. To let
|
|
113
|
+
bootstrap create a Projects V2 board, also grant the `project` scope with
|
|
114
|
+
`gh auth refresh -s project`; without it, bootstrap warns and skips the board.
|
|
115
|
+
|
|
116
|
+
You do **not** need an existing git repo or GitHub remote — bootstrap creates
|
|
117
|
+
both if they're missing.
|
|
118
|
+
|
|
119
|
+
### Install
|
|
59
120
|
|
|
60
121
|
```bash
|
|
61
|
-
|
|
62
|
-
npx mandrel sync # materialize ./.agents/ from the package
|
|
63
|
-
node .agents/scripts/bootstrap.js
|
|
122
|
+
npx mandrel init
|
|
64
123
|
```
|
|
65
124
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
Bootstrap
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
through the `mandrel update` migration.
|
|
82
|
-
|
|
83
|
-
> **pnpm users — hoist mandrel's runtime deps.** The materialized
|
|
84
|
-
> `./.agents/scripts/*.js` run from your project root and resolve their
|
|
85
|
-
> third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
|
|
86
|
-
> npm and yarn hoist transitive deps there automatically; pnpm's default
|
|
87
|
-
> isolated layout does **not** — it keeps them in the `.pnpm` virtual store,
|
|
88
|
-
> so the framework scripts (and `mandrel doctor`'s `runtime-deps` check)
|
|
89
|
-
> cannot see them. Add the following to your `.npmrc` before installing:
|
|
90
|
-
>
|
|
91
|
-
> ```ini
|
|
92
|
-
> # Lift mandrel's runtime deps to the top-level node_modules so the
|
|
93
|
-
> # materialized .agents/scripts can resolve them.
|
|
94
|
-
> shamefully-hoist=true
|
|
95
|
-
> ```
|
|
96
|
-
>
|
|
97
|
-
> Prefer a surgical alternative? Replace `shamefully-hoist` with a scoped
|
|
98
|
-
> `public-hoist-pattern[]=` line per package listed in
|
|
99
|
-
> `.agents/runtime-deps.json` — read the file rather than copying a list from
|
|
100
|
-
> here, since the complexity kernel's closure is several packages. If
|
|
101
|
-
> `mandrel doctor` reports `runtime-deps missing: …`, this is the fix.
|
|
102
|
-
|
|
103
|
-
`bootstrap.js` is interactive on a TTY and auto-accepts the
|
|
104
|
-
owner/repo/base branch/operator handle it can infer from your local
|
|
105
|
-
`git remote` and `git config user.name` — you only get prompted for
|
|
106
|
-
fields it can't infer (typically the optional Projects V2 number). When the
|
|
107
|
-
folder is not yet a git repo, or the GitHub repo doesn't exist, it
|
|
108
|
-
provisions them: `git init` plus a first commit, then
|
|
109
|
-
`gh repo create --source=. --push` (use `--visibility private|public|internal`,
|
|
110
|
-
default `private`, to set the new repo's visibility), then `gh project create`
|
|
111
|
-
for the Projects V2 board. Override anything inferred with `--owner`,
|
|
112
|
-
`--repo`, `--base-branch`, or `--operator-handle`. For CI / scripted installs
|
|
113
|
-
pass `--assume-yes` plus whichever overrides you need. The script is
|
|
114
|
-
idempotent — safe to re-run anytime.
|
|
115
|
-
|
|
116
|
-
For the consumer reference and the end-to-end workflow narrative, see
|
|
117
|
-
[`.agents/README.md`](.agents/README.md) and
|
|
118
|
-
[`docs/SDLC.md`](docs/SDLC.md). Every `.agentrc.json` key is
|
|
119
|
-
documented in [`.agents/docs/configuration.md`](.agents/docs/configuration.md), and the
|
|
120
|
-
slash-command index lives in
|
|
121
|
-
[`.agents/docs/workflows.md`](.agents/docs/workflows.md).
|
|
122
|
-
|
|
123
|
-
## Update
|
|
124
|
-
|
|
125
|
-
Advance `mandrel` to the newest published version and
|
|
126
|
-
re-materialize `./.agents/` in one command:
|
|
125
|
+
This installs `mandrel` (if `.agents/` is absent), materializes `.agents/`, and
|
|
126
|
+
asks whether to **configure now** or stop at **just the files**. Configuring
|
|
127
|
+
runs `bootstrap.js` — which seeds `.agentrc.json`, wires the system prompt, and
|
|
128
|
+
provisions the GitHub side (repo, labels, branch protection, board) — then
|
|
129
|
+
detects your stack, offers to scaffold docs, runs `mandrel doctor`, and hands
|
|
130
|
+
you off to `/mandrel-plan`. Use `--assume-yes` for a non-interactive run.
|
|
131
|
+
|
|
132
|
+
Bootstrap infers owner, repo, base branch, and operator handle from your git
|
|
133
|
+
remote and config, prompting only for what it can't infer. Override with
|
|
134
|
+
`--owner`, `--repo`, `--base-branch`, `--operator-handle`, or
|
|
135
|
+
`--visibility private|public|internal` for a newly created repo. It is
|
|
136
|
+
idempotent — safe to re-run.
|
|
137
|
+
|
|
138
|
+
<details>
|
|
139
|
+
<summary>Manual install</summary>
|
|
127
140
|
|
|
128
141
|
```bash
|
|
129
|
-
|
|
142
|
+
npm install mandrel # pins an exact, provenance-signed version
|
|
143
|
+
npx mandrel sync # materialize ./.agents/ (postinstall usually does this)
|
|
144
|
+
node .agents/scripts/bootstrap.js # wire the project and GitHub
|
|
145
|
+
npx mandrel doctor # verify the install
|
|
130
146
|
```
|
|
131
147
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
version` registry probe) and the currently installed version.
|
|
136
|
-
2. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
|
|
137
|
-
3. **Install** the target version with the project's package manager —
|
|
138
|
-
auto-detected from the lockfile (`pnpm-lock.yaml` ⇒ pnpm, `yarn.lock` ⇒
|
|
139
|
-
yarn, otherwise npm) so the bump lands in your real lockfile. The
|
|
140
|
-
dependency bump is left **staged** on disk — `mandrel update` performs no
|
|
141
|
-
`git add` / `git commit`, so you review and commit the lockfile change
|
|
142
|
-
yourself.
|
|
143
|
-
4. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
|
|
144
|
-
5. **Migrate** — apply version-keyed migration steps for the crossed range.
|
|
145
|
-
6. **Doctor** — run the check registry to verify the resulting install.
|
|
146
|
-
7. **Surface** the target changelog section.
|
|
147
|
-
|
|
148
|
-
### Flags
|
|
149
|
-
|
|
150
|
-
- `--dry-run` — print the resolved target version and the ordered step
|
|
151
|
-
plan, then exit. No dependency is bumped, no file is written, no seam
|
|
152
|
-
runs.
|
|
153
|
-
- `--install-cmd "<cmd>"` — override the auto-detected install command. The
|
|
154
|
-
package manager is normally detected from your lockfile
|
|
155
|
-
(`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
|
|
156
|
-
otherwise `npm install …`), and it keeps your current pin style: an exact
|
|
157
|
-
pin installs with `--save-exact` (`--exact` on yarn), a tilde pin as
|
|
158
|
-
`mandrel@~<target>`, so an override is rarely needed. When you do
|
|
159
|
-
pass one, a `{target}` placeholder is substituted with the resolved newest
|
|
160
|
-
version — e.g. `--install-cmd "pnpm add -D mandrel@{target} -w"` —
|
|
161
|
-
so the override can still consume the auto-probed version. The registry
|
|
162
|
-
probe always stays on `npm view` (it is a PM-agnostic registry query).
|
|
163
|
-
|
|
164
|
-
### Manual equivalent
|
|
165
|
-
|
|
166
|
-
If you prefer to drive the steps by hand:
|
|
148
|
+
Bootstrap adds a guarded `prepare` script that regenerates `.claude/commands/`
|
|
149
|
+
and `.claude/agents/` from `.agents/`. Both are generated and gitignored —
|
|
150
|
+
never commit them.
|
|
167
151
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
152
|
+
</details>
|
|
153
|
+
|
|
154
|
+
> **pnpm users:** the `.agents/scripts/` CLIs resolve their dependencies from
|
|
155
|
+
> your top-level `node_modules`, which pnpm's isolated layout doesn't populate.
|
|
156
|
+
> Add `shamefully-hoist=true` to `.npmrc` (or a `public-hoist-pattern[]=` line
|
|
157
|
+
> per package in `.agents/runtime-deps.json`). If `mandrel doctor` reports
|
|
158
|
+
> `runtime-deps missing`, this is the fix.
|
|
159
|
+
|
|
160
|
+
### Updating
|
|
161
|
+
|
|
162
|
+
Inside Claude Code, run:
|
|
163
|
+
|
|
164
|
+
```text
|
|
165
|
+
/mandrel-update
|
|
172
166
|
```
|
|
173
167
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
reported as distributions with a noise-band, tracking the framework's
|
|
184
|
-
**value-add over the bare-model baseline** across versions and models.
|
|
185
|
-
|
|
186
|
-
The benchmark lives in its own repo on purpose: holding the harness fixed while
|
|
187
|
-
varying the pinned `mandrel` version cleanly decouples harness-version from
|
|
188
|
-
framework-version, and running through the published-package + `mandrel sync`
|
|
189
|
-
path exercises the real consumer contract. The dependency is one-directional —
|
|
190
|
-
`mandrel-bench` depends on `mandrel`, never the reverse. See the
|
|
191
|
-
[mandrel-bench README](https://github.com/dsj1984/mandrel-bench#readme) for the
|
|
192
|
-
dimensions, run model, and how to benchmark a new version.
|
|
193
|
-
|
|
194
|
-
## Contributors
|
|
195
|
-
|
|
196
|
-
The published `mandrel` package ships three directories — `.agents/`, `bin/`,
|
|
197
|
-
and `lib/` — plus the single file `docs/CHANGELOG.md`, and excludes the
|
|
198
|
-
`__tests__` subtrees under `.agents/` and `lib/` (see the `files` array in
|
|
199
|
-
[`package.json`](package.json)).
|
|
200
|
-
`.agents/` is the payload `mandrel sync` materializes into a consumer's
|
|
201
|
-
`./.agents/` directory; `bin/mandrel.js` and its `lib/` implementation stay
|
|
202
|
-
inside `node_modules/mandrel/` and back the `npx mandrel …` CLI used
|
|
203
|
-
throughout this README. Everything else in this repository — `docs/`,
|
|
204
|
-
`tests/`, `.github/`, the root tooling configs — is internal development
|
|
205
|
-
tooling and is not published.
|
|
206
|
-
|
|
207
|
-
Common commands while developing the framework itself:
|
|
168
|
+
It upgrades to the newest published `mandrel`, re-syncs `.agents/`, applies
|
|
169
|
+
migrations, checks the install, and walks you through reconciling your config
|
|
170
|
+
and committing the bump.
|
|
171
|
+
|
|
172
|
+
## Contributing
|
|
173
|
+
|
|
174
|
+
Only `.agents/`, `bin/`, `lib/`, and `docs/CHANGELOG.md` are published (see the
|
|
175
|
+
`files` array in [`package.json`](package.json)); everything else here is
|
|
176
|
+
development tooling for Mandrel itself.
|
|
208
177
|
|
|
209
178
|
```bash
|
|
210
179
|
npm run lint # biome + markdownlint + repo ratchets + generated-doc drift
|
|
211
|
-
npm run format # biome format
|
|
180
|
+
npm run format # biome format (JS/JSON only)
|
|
212
181
|
npm test # framework tests
|
|
213
|
-
npm run test:coverage # tests with coverage gate
|
|
182
|
+
npm run test:coverage # tests with the coverage gate
|
|
214
183
|
```
|
|
215
184
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
- [`.
|
|
223
|
-
|
|
224
|
-
-
|
|
225
|
-
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
CI is green, tags `main`, and publishes `mandrel` to npm.
|
|
234
|
-
|
|
235
|
-
Install scripts are disabled by default: the committed
|
|
236
|
-
[`.npmrc`](.npmrc) sets `ignore-scripts=true`, so `npm install` / `npm ci`
|
|
237
|
-
will not execute dependency lifecycle hooks — a defense-in-depth measure
|
|
238
|
-
against malicious lifecycle scripts in compromised transitive packages
|
|
239
|
-
(CWE-1357). CI passes `--ignore-scripts` explicitly. If you knowingly need
|
|
240
|
-
install scripts for a specific install, run
|
|
241
|
-
`npm install --ignore-scripts=false` for that invocation only.
|
|
242
|
-
|
|
243
|
-
CRAP and Maintainability gates fire at four sites — `.husky/pre-commit`
|
|
244
|
-
(`quality-preview.js --staged`, scored on the staged index), `.husky/pre-push`
|
|
245
|
-
(diff-scoped against `origin/main`), close-validation (story close), and CI
|
|
246
|
-
(`ci.yml`, push + PR) — against the same thresholds from
|
|
247
|
-
`delivery.quality.*` in `.agentrc.json`. All four are **blocking**: the
|
|
248
|
-
pre-commit hook fires earliest and refuses the commit on a threshold
|
|
249
|
-
violation, and a green `npm run lint` / `npm test` / `check-baselines.js`
|
|
250
|
-
run does not predict it.
|
|
185
|
+
A few things to know:
|
|
186
|
+
|
|
187
|
+
- **Quality gates are blocking at four sites** — pre-commit (staged files),
|
|
188
|
+
pre-push (diff vs `origin/main`), Story close, and CI — using the CRAP and
|
|
189
|
+
maintainability thresholds in `delivery.quality.*`. A green `lint`/`test` run
|
|
190
|
+
does not predict them.
|
|
191
|
+
- **Install scripts are off** — the committed [`.npmrc`](.npmrc) sets
|
|
192
|
+
`ignore-scripts=true` as supply-chain defense. Use
|
|
193
|
+
`npm install --ignore-scripts=false` for a one-off exception.
|
|
194
|
+
- **Releases are automated** by release-please from Conventional Commits on
|
|
195
|
+
`main`.
|
|
196
|
+
|
|
197
|
+
Further reading: [`AGENTS.md`](AGENTS.md) (repo orientation),
|
|
198
|
+
[`docs/onboarding.md`](docs/onboarding.md) (layout, commands, standards),
|
|
199
|
+
[`docs/architecture.md`](docs/architecture.md) (module map, tech stack),
|
|
200
|
+
[`docs/release-operations.md`](docs/release-operations.md), and
|
|
201
|
+
[`docs/CHANGELOG.md`](docs/CHANGELOG.md).
|
|
251
202
|
|
|
252
203
|
## License
|
|
253
204
|
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,31 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.84.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.83.0...mandrel-v2.84.0) (2026-10-13)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* make Codex a first-class Mandrel host alongside Claude Code ([#5655](https://github.com/dsj1984/mandrel/issues/5655)) ([#5660](https://github.com/dsj1984/mandrel/issues/5660)) ([14d999e](https://github.com/dsj1984/mandrel/commit/14d999eaebb8f456890e2e4cd49d2e912687f46d))
|
|
24
|
+
* mandrel-status band v2: one quiet line while healthy, a colored action line when a Story needs attention ([#5657](https://github.com/dsj1984/mandrel/issues/5657)) ([#5658](https://github.com/dsj1984/mandrel/issues/5658)) ([19ca2ee](https://github.com/dsj1984/mandrel/commit/19ca2ee2b6387fb828788dce79a89307d8787420))
|
|
25
|
+
* run the `codex` review provider on the Codex CLI instead of Claude ([#5656](https://github.com/dsj1984/mandrel/issues/5656)) ([#5659](https://github.com/dsj1984/mandrel/issues/5659)) ([0829fdf](https://github.com/dsj1984/mandrel/commit/0829fdf525198adf49773776c4d2bfc25e6519ed))
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
* boot sweep finishes the agent::done flip for Stories GitHub closed while still at agent::closing ([#5652](https://github.com/dsj1984/mandrel/issues/5652)) ([#5653](https://github.com/dsj1984/mandrel/issues/5653)) ([f29e5f8](https://github.com/dsj1984/mandrel/commit/f29e5f88cff2ff09729dd2cadbb4248e428bf608))
|
|
31
|
+
* sync-agentrc validates the merged .agentrc.json + .agentrc.local.json, like the resolver ([#5649](https://github.com/dsj1984/mandrel/issues/5649)) ([#5650](https://github.com/dsj1984/mandrel/issues/5650)) ([7d4ee1d](https://github.com/dsj1984/mandrel/commit/7d4ee1d8add1d99a2cfd31d389d5495bfa9d8fd0))
|
|
32
|
+
|
|
33
|
+
## [2.83.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.82.0...mandrel-v2.83.0) (2026-10-12)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
* close-validation: an explicit `project.commands.typecheck: null` skips the typecheck gate instead of running `npm run typecheck` ([#5637](https://github.com/dsj1984/mandrel/issues/5637)) ([#5639](https://github.com/dsj1984/mandrel/issues/5639)) ([907d0b5](https://github.com/dsj1984/mandrel/commit/907d0b52c8ce15d520d5d52d7de0bb18c769d290))
|
|
39
|
+
* close-validation: derive lockWait and suiteTimings from a structured lock-event channel, never from scraped gate stdout ([#5642](https://github.com/dsj1984/mandrel/issues/5642)) ([#5644](https://github.com/dsj1984/mandrel/issues/5644)) ([ab49594](https://github.com/dsj1984/mandrel/commit/ab495945222687d6ebb2071bd25ad9cd2196436a))
|
|
40
|
+
* duplication scanner: resolve target dirs and ignore globs against cwd so a cross-tree scan reads one tree ([#5636](https://github.com/dsj1984/mandrel/issues/5636)) ([#5641](https://github.com/dsj1984/mandrel/issues/5641)) ([f2f43ce](https://github.com/dsj1984/mandrel/commit/f2f43ce36aa1bf88079d18e013fd378cd1d81bfe))
|
|
41
|
+
* single-story-close: reconcile agent::done on the already-closed-as-completed early return ([#5646](https://github.com/dsj1984/mandrel/issues/5646)) ([#5647](https://github.com/dsj1984/mandrel/issues/5647)) ([887df5a](https://github.com/dsj1984/mandrel/commit/887df5af1713631bdfc3c97e083d265e11b3dd34))
|
|
42
|
+
|
|
18
43
|
## [2.82.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.81.0...mandrel-v2.82.0) (2026-10-11)
|
|
19
44
|
|
|
20
45
|
|
package/lib/cli/guarded-sync.js
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
* Shared body of `mandrel sync-commands` / `mandrel sync-agents`: run a
|
|
4
4
|
* `.agents/scripts/` projector in a child process, forwarding its exit code.
|
|
5
5
|
* Refuses first when `.agents/` does not match the running CLI (version
|
|
6
|
-
* marker, else the `agents-drift` check): `.claude
|
|
7
|
-
* stale
|
|
6
|
+
* marker, else the `agents-drift` check): every projection (`.claude/*`, the
|
|
7
|
+
* Codex skills and agents) is gitignored, so a stale one surfaces only when an
|
|
8
|
+
* agent hits a missing module. The projector writes both hosts' trees.
|
|
8
9
|
* The marker is read from `cwd()`; `PROJECT_ROOT` only names this CLI's version.
|
|
9
10
|
*/
|
|
10
11
|
|