mandrel 2.90.0 → 2.91.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 +47 -7
- package/.agents/agents/story-worker.md +20 -0
- package/.agents/audit-checklists/lean.md +26 -0
- package/.agents/docs/agentrc-reference.json +5 -6
- package/.agents/docs/configuration.md +31 -30
- package/.agents/docs/workflows.md +7 -1
- package/.agents/instructions.md +3 -1
- package/.agents/runtime-deps.json +0 -2
- package/.agents/schemas/agentrc.schema.json +46 -45
- package/.agents/schemas/audit-rules.json +19 -0
- package/.agents/scripts/acceptance-eval.js +2 -6
- package/.agents/scripts/audit-exceptions.js +2 -4
- package/.agents/scripts/check-arch-cycles.js +1 -5
- package/.agents/scripts/check-context-budget.js +1 -5
- package/.agents/scripts/check-cyclomatic.js +1 -5
- package/.agents/scripts/check-dead-exports.js +23 -14
- package/.agents/scripts/check-doc-links.js +4 -4
- package/.agents/scripts/check-test-temp-hygiene.js +29 -33
- package/.agents/scripts/coverage-capture.js +14 -6
- package/.agents/scripts/diagnose-friction.js +8 -10
- package/.agents/scripts/generate-workflows-doc.js +5 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
- package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
- package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
- package/.agents/scripts/lib/baselines/components.js +5 -5
- package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
- package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
- package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
- package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
- package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
- package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
- package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
- package/.agents/scripts/lib/baselines/writer.js +4 -4
- package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
- package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
- package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
- package/.agents/scripts/lib/child-exec.js +4 -4
- package/.agents/scripts/lib/claude/agents-projection.js +170 -0
- package/.agents/scripts/lib/claude/commands-projection.js +184 -0
- package/.agents/scripts/lib/close-validation/commands.js +28 -117
- package/.agents/scripts/lib/close-validation/gates.js +54 -48
- package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
- package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
- package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
- package/.agents/scripts/lib/config/commands.js +82 -7
- package/.agents/scripts/lib/config/explain.js +2 -1
- package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
- package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
- package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
- package/.agents/scripts/lib/config/gates/shared.js +2 -2
- package/.agents/scripts/lib/config/git-roots.js +120 -0
- package/.agents/scripts/lib/config/quality.js +46 -50
- package/.agents/scripts/lib/config/review-chain-default.js +4 -3
- package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
- package/.agents/scripts/lib/config/temp-paths.js +3 -37
- package/.agents/scripts/lib/config-resolver.js +5 -9
- package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
- package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
- package/.agents/scripts/lib/config-settings-schema.js +6 -7
- package/.agents/scripts/lib/coverage-baseline.js +2 -1
- package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
- package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
- package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
- package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
- package/.agents/scripts/lib/coverage-capture.js +31 -20
- package/.agents/scripts/lib/coverage-utils.js +34 -16
- package/.agents/scripts/lib/cpu-pool.js +2 -4
- package/.agents/scripts/lib/crap-engine.js +19 -1
- package/.agents/scripts/lib/crap-utils.js +2 -1
- package/.agents/scripts/lib/dead-exports-knip.js +29 -11
- package/.agents/scripts/lib/detect-package-manager.js +13 -0
- package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
- package/.agents/scripts/lib/full-suite-lock.js +25 -9
- package/.agents/scripts/lib/gates/baseline-store.js +2 -10
- package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
- package/.agents/scripts/lib/gh-env.js +72 -0
- package/.agents/scripts/lib/gh-exec.js +26 -1
- package/.agents/scripts/lib/maintainability-utils.js +8 -8
- package/.agents/scripts/lib/npm-scripts.js +1 -1
- package/.agents/scripts/lib/observability/signal-validator.js +2 -6
- package/.agents/scripts/lib/observability/terse-result.js +2 -6
- package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
- package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
- package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
- package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
- package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
- package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
- package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
- package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
- package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
- package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
- package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
- package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
- package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
- package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
- package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
- package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
- package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
- package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
- package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
- package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
- package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
- package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
- package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
- package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
- package/.agents/scripts/lib/source-extensions.js +30 -15
- package/.agents/scripts/lib/test-run-credit.js +1 -9
- package/.agents/scripts/lib/test-temp.js +22 -21
- package/.agents/scripts/lib/util/ajv.js +111 -0
- package/.agents/scripts/lib/util/atomic-write.js +30 -0
- package/.agents/scripts/lib/util/paths.js +51 -0
- package/.agents/scripts/lib/util/sleep.js +6 -0
- package/.agents/scripts/lib/util/slug.js +12 -0
- package/.agents/scripts/lib/validation-evidence.js +19 -40
- package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
- package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
- package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
- package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
- package/.agents/scripts/lint-issue-body.js +2 -2
- package/.agents/scripts/plan-context.js +2 -7
- package/.agents/scripts/providers/github/auth.js +3 -3
- package/.agents/scripts/providers/github/errors.js +3 -1
- package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
- package/.agents/scripts/providers/github/issues.js +6 -2
- package/.agents/scripts/providers/github/mappers.js +1 -5
- package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
- package/.agents/scripts/providers/github/search-budget.js +3 -1
- package/.agents/scripts/resolve-doc-tiers.js +7 -20
- package/.agents/scripts/sync-agentrc.js +5 -14
- package/.agents/scripts/sync-claude-agents.js +38 -150
- package/.agents/scripts/sync-claude-commands.js +35 -218
- package/.agents/scripts/update-coverage-baseline.js +1 -1
- package/.agents/scripts/update-crap-baseline.js +1 -1
- package/.agents/scripts/update-duplication-baseline.js +2 -16
- package/.agents/scripts/validate-skills.js +6 -10
- package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
- package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
- package/.agents/workflows/audit-exceptions.md +9 -0
- package/.agents/workflows/audit-lean.md +129 -0
- package/.agents/workflows/helpers/audit-lens-core.md +7 -0
- package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
- package/.agents/workflows/helpers/code-review.md +15 -1
- package/.agents/workflows/helpers/deliver-digest.md +1 -1
- package/.agents/workflows/helpers/deliver-reference.md +2 -2
- package/.agents/workflows/mandrel-plan.md +2 -2
- package/docs/CHANGELOG.md +35 -0
- package/lib/cli/doctor-checks/codex.js +6 -5
- package/lib/cli/doctor-checks/llm-review.js +102 -0
- package/lib/cli/doctor-checks/project-access.js +20 -10
- package/lib/cli/doctor-checks/sync-parity.js +65 -140
- package/lib/cli/doctor-checks/test-credit-path.js +69 -28
- package/lib/cli/doctor-checks/toolchain.js +5 -3
- package/lib/cli/registry.js +5 -0
- package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
- package/lib/migrations/index.js +6 -0
- package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
- package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
- package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
- package/package.json +1 -3
package/.agents/README.md
CHANGED
|
@@ -128,7 +128,18 @@ gitignored:
|
|
|
128
128
|
- **Workflows.** Each Codex skill is a pointer: it tells Codex to read
|
|
129
129
|
`.agents/workflows/<name>.md` (or `.agents/local/workflows/<name>.md`) and
|
|
130
130
|
run it, with the text after `$<name>` as its arguments — e.g.
|
|
131
|
-
`$mandrel-plan add a CSV export`. Loop units are `$loops-<name
|
|
131
|
+
`$mandrel-plan add a CSV export`. Loop units are `$loops-<name>` and run
|
|
132
|
+
once per invocation — Codex has no `/loop` cadence, so re-invoke the unit
|
|
133
|
+
(or schedule it) to iterate.
|
|
134
|
+
- **Code review at close.** The default review chain runs `native` then
|
|
135
|
+
`llm-review`, which reviews through the first CLI on PATH: `claude --print`
|
|
136
|
+
(`code-review`), else `codex exec` (`codex`). A Codex-only host therefore
|
|
137
|
+
gets its LLM review from `codex`, and a host with both CLIs pays for one
|
|
138
|
+
review, not two. With neither, close runs `native` alone with one warning.
|
|
139
|
+
Pin `codeReview.providers` (e.g. `{ "name": "codex" }`) to choose the CLI.
|
|
140
|
+
- **Operator questions.** Workflow prose that says to ask with
|
|
141
|
+
`AskUserQuestion` means the host's question idiom: on Codex, ask in plain
|
|
142
|
+
text and wait for the reply (`instructions.md` § 1.A).
|
|
132
143
|
- **Role agents.** A workflow's `subagent_type: <role>` dispatch spawns the
|
|
133
144
|
project custom agent `<role>` (`story-worker`, `acceptance-critic`,
|
|
134
145
|
`plan-critic`, `auditor`) on Codex, per `instructions.md` § 1.A. The
|
|
@@ -152,7 +163,9 @@ gitignored:
|
|
|
152
163
|
- **Doctor.** `mandrel doctor` adds `codex-skills-in-sync`,
|
|
153
164
|
`codex-agents-in-sync` (remedy: re-run `mandrel sync-commands` /
|
|
154
165
|
`mandrel sync-agents`) and `codex-instructions`, which fails when the
|
|
155
|
-
Mandrel block sits beyond the effective `project_doc_max_bytes`.
|
|
166
|
+
Mandrel block sits beyond the effective `project_doc_max_bytes`. Its
|
|
167
|
+
`llm-review-provider` check names the CLI that will serve the review chain
|
|
168
|
+
and fails only when a pinned, non-optional provider's CLI is missing.
|
|
156
169
|
|
|
157
170
|
---
|
|
158
171
|
|
|
@@ -350,7 +363,7 @@ a single vendored manifest that ships inside the bundle:
|
|
|
350
363
|
|
|
351
364
|
- **[`runtime-deps.json`](runtime-deps.json)** — the single source of
|
|
352
365
|
truth. Its `dependencies` block lists the **required** packages — `ajv`,
|
|
353
|
-
`
|
|
366
|
+
`js-yaml`, `picomatch`, plus the complexity
|
|
354
367
|
kernel's closure (`@babel/parser`, `typhonjs-escomplex-commons`,
|
|
355
368
|
`escomplex-plugin-metrics-module`, `escomplex-plugin-syntax-babylon`,
|
|
356
369
|
`typhonjs-ast-walker`, and `babel-runtime`, which those packages require
|
|
@@ -604,10 +617,37 @@ accounts, give the project its own `gh` credential store in the gitignored
|
|
|
604
617
|
```
|
|
605
618
|
|
|
606
619
|
Log it in once with `GH_CONFIG_DIR=~/.config/gh-work gh auth login`. Relative
|
|
607
|
-
paths resolve against the project root
|
|
608
|
-
missing directory is a config
|
|
609
|
-
|
|
610
|
-
|
|
620
|
+
paths resolve against the project root (the main checkout, also from a Story
|
|
621
|
+
worktree) and `~` expands to your home; a missing directory is a config
|
|
622
|
+
error.
|
|
623
|
+
|
|
624
|
+
**The gh env contract.** The gh boundary owns the gh environment: before
|
|
625
|
+
the first `gh` spawn in a process, `ensureGhEnv()` (`lib/gh-env.js`, called by
|
|
626
|
+
`gh-exec.js`) reads `github.cliConfigDir`
|
|
627
|
+
through the `.agentrc.local.json` overlay and exports `GH_CONFIG_DIR`, so
|
|
628
|
+
every `gh` call and child process Mandrel spawns — `mandrel doctor` and the
|
|
629
|
+
bootstrap preflight included — reads that store (a differing inherited value
|
|
630
|
+
is overridden with a warning). Config resolution itself never sets it. New
|
|
631
|
+
code spawns `gh` only through `exec()` or `runGh()`; an enforcement test fails
|
|
632
|
+
on any other `gh` spawn.
|
|
633
|
+
|
|
634
|
+
**Config anchoring.** A script reads the `.agentrc.json` (and
|
|
635
|
+
`.agentrc.local.json`) of the tree it runs in, not the tree its code lives
|
|
636
|
+
in. The root resolves in this order:
|
|
637
|
+
|
|
638
|
+
1. an explicit `cwd` passed to `resolveConfig`;
|
|
639
|
+
2. `AP_AGENTRC_CWD`, the explicit override for a process that must judge
|
|
640
|
+
another tree;
|
|
641
|
+
3. the nearest directory holding an `.agentrc.json` between the process's
|
|
642
|
+
working directory and its git toplevel (else the toplevel) — a Story
|
|
643
|
+
worktree's own root, so a gate spawned with `cwd` set to the worktree
|
|
644
|
+
reads its config with no env plumbing, and a project nested in a larger
|
|
645
|
+
repo reads its own;
|
|
646
|
+
4. the Mandrel install root, outside any git work tree.
|
|
647
|
+
|
|
648
|
+
A worktree with no `.agentrc.local.json` of its own takes the main
|
|
649
|
+
checkout's (the gitignored overlay is not copied by `git worktree add`).
|
|
650
|
+
`tempRoot` stays anchored on the main checkout either way.
|
|
611
651
|
|
|
612
652
|
**Identity check.** With a real `github.operatorHandle` and a `gh`-store
|
|
613
653
|
credential, the provider checks the login (`GET /user`, once per process)
|
|
@@ -71,6 +71,26 @@ MUST print `story-<storyId>`. If it does not, **STOP** — never commit Story
|
|
|
71
71
|
work to `main` or outside the worktree/branch. Re-run
|
|
72
72
|
`single-story-init.js` (idempotent) to restore it.
|
|
73
73
|
|
|
74
|
+
## Smallest complete change (MUST)
|
|
75
|
+
|
|
76
|
+
Read the code first and list every place the change must reach — callers,
|
|
77
|
+
tests, fixtures, config, exports; that is the scope. Take the first rung
|
|
78
|
+
that fully solves the Story:
|
|
79
|
+
|
|
80
|
+
1. Does it need to exist at all?
|
|
81
|
+
2. Already in this codebase — reuse it the way nearby code does.
|
|
82
|
+
3. The standard library or a platform feature.
|
|
83
|
+
4. An installed dependency — never add one for a few lines.
|
|
84
|
+
5. One line a reader gets at a glance.
|
|
85
|
+
6. Otherwise the minimum code that works.
|
|
86
|
+
|
|
87
|
+
Lazy about the solution, never the change: finish every caller, test and
|
|
88
|
+
fixture it breaks. No unasked abstraction, option, config or "for later"
|
|
89
|
+
code; deletion beats addition; keep the existing layers. Mark a deliberate
|
|
90
|
+
shortcut with the comment `shortcut: <the limit>, <when to upgrade>`. Never
|
|
91
|
+
cut trust-boundary validation, error handling that prevents data loss,
|
|
92
|
+
security, accessibility, or anything `acceptance[]` asks for.
|
|
93
|
+
|
|
74
94
|
## Commit discipline
|
|
75
95
|
|
|
76
96
|
Conventional Commit subjects on `story-<storyId>` per
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
<!-- GENERATED FILE — do not edit by hand.
|
|
2
|
+
Source of truth: .agents/workflows/audit-lean.md
|
|
3
|
+
Regenerate: node .agents/scripts/generate-lens-checklists.js
|
|
4
|
+
Drift is gated by: npm run docs:check
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# Lean Code Audit — authoring checklist
|
|
8
|
+
|
|
9
|
+
> Audit whether code should exist at all — reinvented helpers, stdlib and platform re-implementations, single-implementation abstractions, dependencies carried for a few lines, and semantic near-copies — every finding grounded in a grep before it is judged.
|
|
10
|
+
|
|
11
|
+
Self-check your change against this lens's concerns before you ship:
|
|
12
|
+
|
|
13
|
+
- [ ] Reuse
|
|
14
|
+
- [ ] Stdlib & Platform
|
|
15
|
+
- [ ] YAGNI
|
|
16
|
+
- [ ] Dependency Weight
|
|
17
|
+
- [ ] Near-Copy
|
|
18
|
+
- [ ] Reinvented helpers
|
|
19
|
+
- [ ] Parallel registries
|
|
20
|
+
- [ ] Hand-rolled built-ins
|
|
21
|
+
- [ ] Polyfills past their target
|
|
22
|
+
- [ ] Single-implementation abstractions
|
|
23
|
+
- [ ] Pass-through wrappers
|
|
24
|
+
- [ ] Dead options
|
|
25
|
+
- [ ] Packages carried for a few lines
|
|
26
|
+
- [ ] Semantic duplicates
|
|
@@ -15,8 +15,8 @@
|
|
|
15
15
|
],
|
|
16
16
|
"commands": {
|
|
17
17
|
"test": "npm test",
|
|
18
|
-
"typecheck":
|
|
19
|
-
"lint":
|
|
18
|
+
"typecheck": "npm run typecheck",
|
|
19
|
+
"lint": "npm run lint",
|
|
20
20
|
"formatCheck": "npx biome format .",
|
|
21
21
|
"formatWrite": "npx biome format --write ."
|
|
22
22
|
}
|
|
@@ -128,6 +128,7 @@
|
|
|
128
128
|
}
|
|
129
129
|
},
|
|
130
130
|
"coveragePath": "coverage/coverage-final.json",
|
|
131
|
+
"captureScript": "test:coverage",
|
|
131
132
|
"captureScope": "full",
|
|
132
133
|
"timeoutMs": 600000
|
|
133
134
|
},
|
|
@@ -153,8 +154,7 @@
|
|
|
153
154
|
"skipWhenUnchanged": true,
|
|
154
155
|
"baselineJoin": false
|
|
155
156
|
},
|
|
156
|
-
"coveragePath": null
|
|
157
|
-
"captureScript": "test:coverage"
|
|
157
|
+
"coveragePath": null
|
|
158
158
|
},
|
|
159
159
|
"maintainability": {
|
|
160
160
|
"enabled": true,
|
|
@@ -209,7 +209,6 @@
|
|
|
209
209
|
}
|
|
210
210
|
},
|
|
211
211
|
"targetDirs": ["src"],
|
|
212
|
-
"formats": ["javascript", "jsx", "typescript", "tsx"],
|
|
213
212
|
"ignoreGlobs": []
|
|
214
213
|
}
|
|
215
214
|
},
|
|
@@ -231,7 +230,7 @@
|
|
|
231
230
|
"name": "native"
|
|
232
231
|
},
|
|
233
232
|
{
|
|
234
|
-
"name": "
|
|
233
|
+
"name": "llm-review",
|
|
235
234
|
"scopes": ["story"],
|
|
236
235
|
"optional": true
|
|
237
236
|
}
|
|
@@ -84,11 +84,11 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
84
84
|
| `paths.docsRoot` | Yes | `string` | `"docs"` | Repo-relative root of the project documentation the planner reads for context. |
|
|
85
85
|
| `paths.tempRoot` | Yes | `string` | `"temp"` | Repo-relative gitignored scratch root. Every temporary artifact — gate transcripts, audit reports, plan authoring dirs — lands under it. |
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
|
-
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns
|
|
88
|
-
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`)
|
|
89
|
-
| `commands.typecheck` | No | `string` \| `null` | `
|
|
90
|
-
| `commands.lint` | No | `string` \| `null` | `
|
|
91
|
-
| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
|
|
87
|
+
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns, each run from the repo root. One tri-state per key: absent uses the default shown; an explicit `null` disables an optional gate (`typecheck`, `lint`, `formatCheck`) — close reports it as skipped (`<gate>-disabled`) and runs nothing; a string is that command. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-tool pair in one script and name that. |
|
|
88
|
+
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`). Mandatory: `null` is rejected. |
|
|
89
|
+
| `commands.typecheck` | No | `string` \| `null` | `"npm run typecheck"` | Static type-check command run as a close-validation gate. An explicit `null` disables the gate for projects with no type layer (skip reason `typecheck-disabled`). The empty string is rejected so a typo cannot silently disable it. |
|
|
90
|
+
| `commands.lint` | No | `string` \| `null` | `"npm run lint"` | Lint command run as a close-validation gate and by the handoff preflight. An explicit `null` disables both (skip reason `lint-disabled`). Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. |
|
|
91
|
+
| `commands.formatCheck` | No | `string` \| `null` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`). |
|
|
92
92
|
| `commands.formatWrite` | No | `string` | `"npx biome format --write ."` | Mutating format command the close-time format-autofix step spawns. |
|
|
93
93
|
|
|
94
94
|
### `github` (optional)
|
|
@@ -137,7 +137,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
137
137
|
| Key | Required | Type | Default | Description |
|
|
138
138
|
| --- | --- | --- | --- | --- |
|
|
139
139
|
| `execution` | No | `object` | — | Serialization and capacity admission of the suite spawns delivery drives. |
|
|
140
|
-
| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` /
|
|
140
|
+
| `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / the coverage gate's `captureScript`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
|
|
141
141
|
| `execution.capacity` | No | `integer` | — | Story #5668. The admission budget, in weight units (CPU workers), shared by every suite spawn across this repository's worktrees and sessions — runs in other repositories on the host are not counted. Unset → the host's `os.availableParallelism()`. A declared workload is admitted while the live weights plus its own fit, strictly first-in-first-out: nothing overtakes an earlier live waiter, so a queued full suite is never starved. |
|
|
142
142
|
| `execution.workloads[]` | No | `array<object>` | `[]` | Story #5668. Suite commands declared safe to run alongside others. A spawn whose argv (whitespace-normalized) EXACTLY equals `command` takes that `weight` and `resources`; anything else — and every spawn when this list is empty, the default — runs exclusively (full capacity, today's serialization). Isolation is never inferred from a flag, prefix or diff size. `weight` must count the run's nested worker pool (`--workers 4` → 4), and a full suite needs its own entry before anything can overlap it. Two runs naming a common `resources` entry (a database fixture, a shared coverage file) never overlap; worktree-local outputs need none. A weight above `capacity` refuses the run with exit 78 — nothing spawns, no credit is recorded. An expired wait still exits 75, resumably. Scheduling never changes a run's credit identity. `MANDREL_FULL_SUITE_LOCK=0` (one invocation) or `fullSuiteLock: false` turns admission off entirely; reach for the env hatch only when you have checked the runs share nothing. Each item has: command, weight, resources. |
|
|
143
143
|
| `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
|
|
@@ -169,10 +169,11 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
169
169
|
| `quality.gates.coverage.tolerance` | No | `object` | `{"kind":"absolute","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
170
170
|
| `quality.gates.coverage.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
171
171
|
| `quality.gates.coverage.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
172
|
-
| `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` |
|
|
173
|
-
| `quality.gates.coverage.components` | No | `object<map>` | — |
|
|
174
|
-
| `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `
|
|
175
|
-
| `quality.gates.coverage.
|
|
172
|
+
| `quality.gates.coverage.floors` | No | `object<map>` | `{"*":{"lines":90,"branches":85,"functions":90}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
173
|
+
| `quality.gates.coverage.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
174
|
+
| `quality.gates.coverage.coveragePath` | No | `string` | `"coverage/coverage-final.json"` | Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `captureScript` MUST write Istanbul per-file JSON (the `json` reporter) here — the coverage and CRAP refreshes both read it. A `json-summary` (`coverage-summary.json`) alone cannot feed them, so a green capture that leaves no file here fails and a full-scope refresh refuses to run. Its capture stamp sits beside it (`.capture-stamp.<file>.json`), so another artifact may share its directory. |
|
|
175
|
+
| `quality.gates.coverage.captureScript` | No | `string` | `"test:coverage"` | `package.json` script (never a shell command) the coverage gate's capture runs, spawned as `<pm> run <script>` under the detected package manager (npm, pnpm, yarn or bun). Close registers the coverage-capture gate when the coverage or CRAP gate is enabled and this script exists; the full-suite lock's workload identity and `mandrel doctor`'s `test-credit-path` check follow it. Default `test:coverage`. |
|
|
176
|
+
| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `captureScript`. `affected` runs the consumer-owned `test:coverage:affected` script with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
|
|
176
177
|
| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
|
|
177
178
|
| `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
|
|
178
179
|
| `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
@@ -180,27 +181,27 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
180
181
|
| `quality.gates.crap.tolerance` | No | `object` | `{"kind":"absolute","value":0.05}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
181
182
|
| `quality.gates.crap.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
182
183
|
| `quality.gates.crap.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
183
|
-
| `quality.gates.crap.floors` | No | `object<map>` | `{"*":{"max":30,"p95":20,"methodsAbove20":50}}` |
|
|
184
|
-
| `quality.gates.crap.components` | No | `object<map>` | — |
|
|
184
|
+
| `quality.gates.crap.floors` | No | `object<map>` | `{"*":{"max":30,"p95":20,"methodsAbove20":50}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
185
|
+
| `quality.gates.crap.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
185
186
|
| `quality.gates.crap.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose JS sources the CRAP gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal. |
|
|
186
187
|
| `quality.gates.crap.newMethodCeiling` | No | `integer` | `30` | Hard CRAP ceiling applied to a method the diff introduces. A new method above it fails the gate regardless of the baseline. |
|
|
187
188
|
| `quality.gates.crap.requireCoverage` | No | `boolean` | `true` | When true, the gate refuses to score without a coverage artifact rather than silently reporting complexity-only rows. |
|
|
188
189
|
| `quality.gates.crap.minMethodResolutionRate` | No | `number` | — | Fail-closed floor on the per-method coverage JOIN (Story #4775): the fraction of methods that must resolve a coverage entry, counted only over files that HAVE one, before `update-crap-baseline.js` will persist. A broken join is silent by construction — unresolved methods are simply absent — so the updater refuses rather than writing a thin baseline and logging it as success. Not enforced below 25 joinable methods, where a diff-scoped run’s rate is noise. Default 0.75; a healthy repo resolves ~98%. |
|
|
189
190
|
| `quality.gates.crap.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217). |
|
|
190
|
-
| `quality.gates.crap.incrementalCoverage` | No | `object` | — | The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full
|
|
191
|
+
| `quality.gates.crap.incrementalCoverage` | No | `object` | — | The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full run of the coverage gate's `captureScript` (Story #5065). |
|
|
191
192
|
| `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
|
|
192
193
|
| `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
|
|
193
194
|
| `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the gate’s own default `main` applies. |
|
|
194
|
-
| `quality.gates.crap.coveragePath` | No | `string` \| `null` | `null` | Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it.
|
|
195
|
-
| `quality.gates.crap.captureScript` | No | `string` |
|
|
195
|
+
| `quality.gates.crap.coveragePath` | No | `string` \| `null` | `null` | Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. Its capture stamp sits beside it, so it may share a directory with the coverage gate's artifact. |
|
|
196
|
+
| `quality.gates.crap.captureScript` | No | `string` | — | `package.json` script (never a shell command) that writes the CRAP gate's OWN coverage artifact, spawned as `<pm> run <script>`. Valid only beside an own `coveragePath`: without one the CRAP gate reads the coverage gate's artifact, so this key is refused and `delivery.quality.gates.coverage.captureScript` runs. Unset beside an own `coveragePath`, it is the coverage gate's `captureScript`. |
|
|
196
197
|
| `quality.gates.maintainability` | No | `object` | — | Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score. |
|
|
197
198
|
| `quality.gates.maintainability.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
198
199
|
| `quality.gates.maintainability.baselinePath` | No | `string` | `"baselines/maintainability.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
199
200
|
| `quality.gates.maintainability.tolerance` | No | `object` | `{"kind":"absolute","value":0.5}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
200
201
|
| `quality.gates.maintainability.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
201
202
|
| `quality.gates.maintainability.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
202
|
-
| `quality.gates.maintainability.floors` | No | `object<map>` | `{"*":{"min":70}}` |
|
|
203
|
-
| `quality.gates.maintainability.components` | No | `object<map>` | — |
|
|
203
|
+
| `quality.gates.maintainability.floors` | No | `object<map>` | `{"*":{"min":70}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
204
|
+
| `quality.gates.maintainability.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
204
205
|
| `quality.gates.maintainability.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `[]` | Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal. |
|
|
205
206
|
| `quality.gates.maintainability.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from MI discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217). |
|
|
206
207
|
| `quality.gates.mutation` | No | `object` | — | Stryker mutation-score ratchet. Disabled by default: no framework path runs Stryker, so enable it only alongside a consumer-provided Stryker run that writes the mutation report the baseline is scored from. |
|
|
@@ -209,28 +210,27 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
209
210
|
| `quality.gates.mutation.tolerance` | No | `object` | `{"kind":"percent","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
210
211
|
| `quality.gates.mutation.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
211
212
|
| `quality.gates.mutation.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
212
|
-
| `quality.gates.mutation.floors` | No | `object<map>` | `{"*":{"score":60}}` |
|
|
213
|
-
| `quality.gates.mutation.components` | No | `object<map>` | — |
|
|
213
|
+
| `quality.gates.mutation.floors` | No | `object<map>` | `{"*":{"score":60}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
214
|
+
| `quality.gates.mutation.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
214
215
|
| `quality.gates.bundle-size` | No | `object` | — | Built-artifact size ratchet for web targets. Off by default — it needs declared bundles. |
|
|
215
216
|
| `quality.gates.bundle-size.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
216
217
|
| `quality.gates.bundle-size.baselinePath` | No | `string` | `"baselines/bundle-size.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
217
218
|
| `quality.gates.bundle-size.tolerance` | No | `object` | `{"kind":"percent","value":0}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
218
219
|
| `quality.gates.bundle-size.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
219
220
|
| `quality.gates.bundle-size.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
220
|
-
| `quality.gates.bundle-size.floors` | No | `object<map>` | `{"*":{}}` |
|
|
221
|
-
| `quality.gates.bundle-size.components` | No | `object<map>` | — |
|
|
221
|
+
| `quality.gates.bundle-size.floors` | No | `object<map>` | `{"*":{}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
222
|
+
| `quality.gates.bundle-size.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
222
223
|
| `quality.gates.bundle-size.bundles[]` | No | `array<object>` | `[]` | The artifacts to weigh. Empty means the gate has nothing to do. Each item has: name, path, limit. |
|
|
223
|
-
| `quality.gates.duplication` | No | `object` | — | Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks
|
|
224
|
+
| `quality.gates.duplication` | No | `object` | — | Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks and `ignoreGlobs` to exclude files from the scan. The jscpd formats it reads are derived from the scorable-extension list every other gate scores (JavaScript, JSX, TypeScript, TSX), so they are not configurable (Story #5738). |
|
|
224
225
|
| `quality.gates.duplication.enabled` | No | `boolean` | `false` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
225
226
|
| `quality.gates.duplication.baselinePath` | No | `string` | `"baselines/duplication.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
226
227
|
| `quality.gates.duplication.tolerance` | No | `object` | `{"kind":"absolute","value":1}` | How much a rollup may drift from the committed baseline before the gate reports a regression. |
|
|
227
228
|
| `quality.gates.duplication.tolerance.kind` | Yes | `"absolute"` \| `"percent"` | — | Whether `value` is read as raw metric units (`absolute`) or as a percentage of the baseline (`percent`). |
|
|
228
229
|
| `quality.gates.duplication.tolerance.value` | Yes | `number` | — | The tolerance magnitude. 0 means no drift is allowed. |
|
|
229
|
-
| `quality.gates.duplication.floors` | No | `object<map>` | `{"*":{"percentage":25}}` |
|
|
230
|
-
| `quality.gates.duplication.components` | No | `object<map>` | — |
|
|
231
|
-
| `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose sources
|
|
232
|
-
| `quality.gates.duplication.
|
|
233
|
-
| `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). |
|
|
230
|
+
| `quality.gates.duplication.floors` | No | `object<map>` | `{"*":{"percentage":25}}` | Component-keyed absolute floors: `{ "<component>": { "<metric>": number } }` — the threshold half of the component mapping whose membership half is `components`. `"*"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline. |
|
|
231
|
+
| `quality.gates.duplication.components` | No | `object<map>` | — | Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors["*"]`. Defaults to `{ "*": ["**"] }` at the resolver layer. |
|
|
232
|
+
| `quality.gates.duplication.targetDirs` | No | `string[]` or `{ append?, prepend? }` | `["src"]` | Directories whose scorable sources (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`, `.mts`, `.cts`) the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664). |
|
|
233
|
+
| `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). This is the lever for scanning fewer files. |
|
|
234
234
|
| `quality.autoRefresh` | No | `object` | — | Baseline-attribution auto-refresh: when a gate can prove a regression is a legitimate consequence of the diff, it rewrites the baseline instead of blocking. The single-row CRAP jump cap (5) and the rescore scope (`diff`) are fixed. |
|
|
235
235
|
| `quality.autoRefresh.enabled` | No | `boolean` | `true` | Master switch for the auto-refresh path. When false, every baseline refresh is a deliberate operator action. |
|
|
236
236
|
| `quality.requireBaselines` | No | `boolean` | `false` | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
|
|
@@ -243,7 +243,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
243
243
|
| `mergeWatch.maxWaitSeconds` | No | `integer` | — | Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block. |
|
|
244
244
|
| `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the later of the PR's createdAt and its latest auto-merge arm (`autoMergeRequest.enabledAt`), so a re-close that re-arms starts a fresh budget; without an arm time it falls back to createdAt, then to the invocation start. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked. |
|
|
245
245
|
| `codeReview` | No | `object` | — | Review-provider chain and on-branch remediation threshold for the /mandrel-deliver code-review ceremony. |
|
|
246
|
-
| `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"
|
|
246
|
+
| `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"llm-review","scopes":["story"],"optional":true}]` | Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `llm-review` — the first available of `code-review` (a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge) and `codex` (`codex exec`), so a host with both CLIs runs one LLM review and a host with neither skips it. Pin `code-review` or `codex` to choose the CLI. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
|
|
247
247
|
| `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | Severity threshold for on-branch remediation in /mandrel-deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag. |
|
|
248
248
|
| `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
|
|
249
249
|
| `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
|
|
@@ -374,8 +374,9 @@ A config still carrying the retired key is a hard validation failure; the
|
|
|
374
374
|
applies to `getBaselines(config)`.
|
|
375
375
|
- **`quality.gates.<tier>` common shape.** Every gate shares
|
|
376
376
|
`enabled` / `baselinePath` / `tolerance` (`{ kind, value }`) /
|
|
377
|
-
`floors` (`{ <
|
|
378
|
-
`components` (`{ <component>: [<glob>] }`)
|
|
377
|
+
`floors` (`{ <component>: { <metric>: <number> } }`) /
|
|
378
|
+
`components` (`{ <component>: [<glob>] }`) — the threshold and membership
|
|
379
|
+
halves of one component-keyed mapping. The `crap` / `maintainability` /
|
|
379
380
|
`duplication` `targetDirs` default `["src"]`. `components` slices the floor
|
|
380
381
|
check: `check-baselines` reports one rollup per component that matches a
|
|
381
382
|
row and holds it to `floors.<component>` (else `floors["*"]`), so a
|
|
@@ -24,6 +24,11 @@ marketplace listing. The commands load in every Claude Code environment.
|
|
|
24
24
|
`.agents/skills/workflows/<name>/SKILL.md`, invoked as `$<name>` (e.g.
|
|
25
25
|
`$mandrel-plan`; loop units as `$loops-<name>`). Each skill points Codex at
|
|
26
26
|
the workflow file and passes the text after `$<name>` as its arguments.
|
|
27
|
+
A `$loops-<name>` unit runs once per invocation: Codex has no `/loop`
|
|
28
|
+
cadence, so re-invoke it (or schedule it) to iterate. At close, the default
|
|
29
|
+
review chain's `llm-review` entry reviews through `codex exec` when `claude`
|
|
30
|
+
is absent (`claude` wins when both are present); `mandrel doctor`'s
|
|
31
|
+
`llm-review-provider` check names the CLI that will serve it.
|
|
27
32
|
`npm run sync:agents` likewise writes the role agents a workflow dispatches
|
|
28
33
|
(`subagent_type: <role>`) as Codex custom agents
|
|
29
34
|
`.codex/agents/mandrel-<role>.toml`; Codex loads those only in a trusted
|
|
@@ -46,7 +51,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
46
51
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
47
52
|
description, edit the workflow file’s front-matter and regenerate.
|
|
48
53
|
|
|
49
|
-
## Commands (
|
|
54
|
+
## Commands (33)
|
|
50
55
|
|
|
51
56
|
| Command | Description |
|
|
52
57
|
| --- | --- |
|
|
@@ -60,6 +65,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
60
65
|
| `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
|
|
61
66
|
| `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
|
|
62
67
|
| `/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. |
|
|
68
|
+
| `/audit-lean` | Audit whether code should exist at all — reinvented helpers, stdlib and platform re-implementations, single-implementation abstractions, dependencies carried for a few lines, and semantic near-copies — every finding grounded in a grep before it is judged. |
|
|
63
69
|
| `/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) |
|
|
64
70
|
| `/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. |
|
|
65
71
|
| `/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. |
|
package/.agents/instructions.md
CHANGED
|
@@ -20,7 +20,9 @@ skill or workflow guidance. Role-scoped spawn contexts live under
|
|
|
20
20
|
is a separate fixture concept. **Host mapping:** a `subagent_type: <role>`
|
|
21
21
|
dispatch uses the Agent tool on Claude Code and spawns the project custom
|
|
22
22
|
agent named `<role>` on Codex; `general-purpose` means the host's default
|
|
23
|
-
agent.
|
|
23
|
+
agent. An `AskUserQuestion` ask is the host's question idiom (Codex: ask in
|
|
24
|
+
plain text, wait for the reply). A `/loop` cadence is host-owned: Codex runs
|
|
25
|
+
`$loops-<name>` once per invocation.
|
|
24
26
|
|
|
25
27
|
### B. Skill Activation
|
|
26
28
|
|
|
@@ -3,12 +3,10 @@
|
|
|
3
3
|
"dependencies": {
|
|
4
4
|
"@babel/parser": "^7.29.3",
|
|
5
5
|
"ajv": "^8.20.0",
|
|
6
|
-
"ajv-formats": "^3.0.1",
|
|
7
6
|
"babel-runtime": "^6.26.0",
|
|
8
7
|
"escomplex-plugin-metrics-module": "^0.1.0",
|
|
9
8
|
"escomplex-plugin-syntax-babylon": "^0.1.0",
|
|
10
9
|
"js-yaml": "^4.3.1",
|
|
11
|
-
"minimatch": "^10.0.0",
|
|
12
10
|
"picomatch": "^4.0.4",
|
|
13
11
|
"typhonjs-ast-walker": "^0.2.1",
|
|
14
12
|
"typhonjs-escomplex-commons": "^0.1.1"
|