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.
Files changed (60) hide show
  1. package/.agents/README.md +65 -20
  2. package/.agents/docs/configuration.md +40 -3
  3. package/.agents/docs/runbooks/mods.md +98 -54
  4. package/.agents/docs/workflows.md +14 -0
  5. package/.agents/instructions.md +4 -1
  6. package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
  7. package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
  8. package/.agents/schemas/agentrc.schema.json +1 -1
  9. package/.agents/scripts/boot-sweep.js +42 -13
  10. package/.agents/scripts/coverage-capture.js +55 -24
  11. package/.agents/scripts/evidence-gate.js +7 -1
  12. package/.agents/scripts/generate-workflows-doc.js +14 -0
  13. package/.agents/scripts/lib/baselines/duplication-scanner.js +26 -2
  14. package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
  15. package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
  16. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
  17. package/.agents/scripts/lib/close-lock-events.js +109 -0
  18. package/.agents/scripts/lib/close-validation/commands.js +12 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +6 -0
  20. package/.agents/scripts/lib/close-validation/process.js +5 -2
  21. package/.agents/scripts/lib/close-validation/runner.js +14 -4
  22. package/.agents/scripts/lib/codex/agents-projection.js +284 -0
  23. package/.agents/scripts/lib/codex/skills-projection.js +291 -0
  24. package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
  25. package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
  26. package/.agents/scripts/lib/config-resolver.js +5 -42
  27. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  28. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  29. package/.agents/scripts/lib/full-suite-lock.js +20 -0
  30. package/.agents/scripts/lib/full-suite-queue.js +24 -56
  31. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  32. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  33. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
  34. package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
  35. package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
  36. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
  37. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +73 -63
  38. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +70 -0
  39. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +3 -0
  40. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
  41. package/.agents/scripts/lib/supervised-suite.js +8 -28
  42. package/.agents/scripts/single-story-init.js +20 -5
  43. package/.agents/scripts/sync-agentrc.js +5 -3
  44. package/.agents/scripts/sync-claude-agents.js +20 -0
  45. package/.agents/scripts/sync-claude-commands.js +64 -27
  46. package/.agents/scripts/sync-codex-agents.js +36 -0
  47. package/.agents/scripts/sync-codex-skills.js +36 -0
  48. package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
  49. package/.agents/workflows/mandrel-update.md +2 -1
  50. package/README.md +167 -216
  51. package/docs/CHANGELOG.md +25 -0
  52. package/lib/cli/guarded-sync.js +3 -2
  53. package/lib/cli/registry.js +248 -0
  54. package/lib/cli/sync-agents.js +5 -2
  55. package/lib/cli/sync-commands.js +5 -2
  56. package/lib/cli/sync.js +45 -14
  57. package/lib/cli/uninstall.js +8 -1
  58. package/lib/migrations/index.js +2 -0
  59. package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
  60. package/package.json +3 -2
@@ -0,0 +1,291 @@
1
+ /**
2
+ * Codex skill projection of the workflow set: one
3
+ * `.agents/skills/workflows/<name>/SKILL.md` per projectable workflow, from the
4
+ * same source set and exclusions as the Claude command projection. Each skill
5
+ * is a pointer to its workflow file, never a copy. Node built-ins only, so
6
+ * the doctor registry can import it before third-party packages exist.
7
+ *
8
+ * @module codex/skills-projection
9
+ */
10
+
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+
14
+ import { isCommandExcluded } from '../command-header.js';
15
+ import { extractDescription } from '../mandrel-catalog.js';
16
+ import {
17
+ collectLocalSkillFiles,
18
+ collectSkillFiles,
19
+ } from '../skills/walk-skill-files.js';
20
+
21
+ /**
22
+ * Project-relative POSIX home of the projection. Outside the `core`/`stack`
23
+ * tiers, so the skills index never walks it; not dot-prefixed, because Codex
24
+ * skips hidden directories when it scans `.agents/skills/`.
25
+ */
26
+ export const CODEX_SKILLS_DIR = '.agents/skills/workflows';
27
+
28
+ /** Codex's skill-metadata limits. */
29
+ const CODEX_SKILL_NAME_MAX = 64;
30
+ const CODEX_SKILL_DESCRIPTION_MAX = 1024;
31
+
32
+ /** Every generated SKILL.md carries this; the reap touches nothing without it. */
33
+ const CODEX_SKILL_MARKER = '<!-- AUTO-GENERATED by mandrel';
34
+
35
+ const LOOPS_NS = 'loops';
36
+
37
+ /**
38
+ * @param {string} dir
39
+ * @returns {boolean}
40
+ */
41
+ function dirExists(dir) {
42
+ try {
43
+ return fs.statSync(dir).isDirectory();
44
+ } catch {
45
+ return false;
46
+ }
47
+ }
48
+
49
+ /**
50
+ * @param {string} dir
51
+ * @param {(entry: import('node:fs').Dirent) => boolean} keep
52
+ * @returns {string[]}
53
+ */
54
+ function mdFilesIn(dir, keep) {
55
+ if (!dirExists(dir)) return [];
56
+ return fs
57
+ .readdirSync(dir, { withFileTypes: true })
58
+ .filter((e) => e.isFile() && e.name.endsWith('.md') && keep(e))
59
+ .map((e) => e.name)
60
+ .sort();
61
+ }
62
+
63
+ /**
64
+ * The workflows both projections expose: top-level `*.md` plus `loops/*.md`
65
+ * (minus its README) from the payload, then the local zone. The payload wins
66
+ * a collision; a `command: false` workflow is skipped.
67
+ *
68
+ * @param {{ payloadSrc: string, localSrc: string }} sources
69
+ * @returns {Array<{ name: string, sourcePath: string, content: string }>}
70
+ */
71
+ function listProjectableWorkflows({ payloadSrc, localSrc }) {
72
+ const byName = new Map();
73
+ for (const dir of [payloadSrc, localSrc]) {
74
+ const candidates = [
75
+ ...mdFilesIn(dir, () => true).map((f) => ({
76
+ name: f.replace(/\.md$/, ''),
77
+ sourcePath: path.join(dir, f),
78
+ })),
79
+ ...mdFilesIn(
80
+ path.join(dir, LOOPS_NS),
81
+ (e) => e.name.toLowerCase() !== 'readme.md',
82
+ ).map((f) => ({
83
+ name: `${LOOPS_NS}-${f.replace(/\.md$/, '')}`,
84
+ sourcePath: path.join(dir, LOOPS_NS, f),
85
+ })),
86
+ ];
87
+ for (const candidate of candidates) {
88
+ if (byName.has(candidate.name)) continue;
89
+ const content = fs.readFileSync(candidate.sourcePath, 'utf8');
90
+ if (isCommandExcluded(content)) continue;
91
+ byName.set(candidate.name, { ...candidate, content });
92
+ }
93
+ }
94
+ return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
95
+ }
96
+
97
+ /**
98
+ * @param {string} projectRoot
99
+ * @param {string} absPath
100
+ * @returns {string}
101
+ */
102
+ function toPosixRelative(projectRoot, absPath) {
103
+ return path.relative(projectRoot, absPath).split(path.sep).join('/');
104
+ }
105
+
106
+ /**
107
+ * @param {string | null} description
108
+ * @param {string} name
109
+ * @returns {string}
110
+ */
111
+ function skillDescription(description, name) {
112
+ const text = description ?? `Run the Mandrel ${name} workflow.`;
113
+ return text.length > CODEX_SKILL_DESCRIPTION_MAX
114
+ ? `${text.slice(0, CODEX_SKILL_DESCRIPTION_MAX - 1)}…`
115
+ : text;
116
+ }
117
+
118
+ /**
119
+ * The SKILL.md for one workflow. `description` is a JSON string, which is
120
+ * also a valid YAML double-quoted scalar whatever the workflow text holds.
121
+ *
122
+ * @param {{ name: string, description: string | null, workflowPath: string }} input
123
+ * `workflowPath` is project-relative POSIX.
124
+ * @returns {string}
125
+ */
126
+ function renderCodexSkill({ name, description, workflowPath }) {
127
+ return [
128
+ '---',
129
+ `name: ${name}`,
130
+ `description: ${JSON.stringify(skillDescription(description, name))}`,
131
+ '---',
132
+ '',
133
+ `${CODEX_SKILL_MARKER} from ${workflowPath} — do not edit. Re-run: npm run sync:commands -->`,
134
+ '',
135
+ `# $${name}`,
136
+ '',
137
+ `Read \`${workflowPath}\` in full and execute it as the workflow for this`,
138
+ `request. Treat the text that follows \`$${name}\` in the request as the`,
139
+ "workflow's ARGUMENTS.",
140
+ '',
141
+ ].join('\n');
142
+ }
143
+
144
+ /**
145
+ * Every projected skill keyed by name, with the exact SKILL.md it should hold.
146
+ * Throws on a name Codex cannot load or that collides with an authored skill.
147
+ *
148
+ * @param {{ projectRoot: string, payloadSrc?: string, localSrc?: string }} opts
149
+ * @returns {Map<string, string>}
150
+ */
151
+ export function expectedCodexSkills({
152
+ projectRoot,
153
+ payloadSrc = path.join(projectRoot, '.agents', 'workflows'),
154
+ localSrc = path.join(projectRoot, '.agents', 'local', 'workflows'),
155
+ }) {
156
+ const expected = new Map();
157
+ for (const wf of listProjectableWorkflows({ payloadSrc, localSrc })) {
158
+ expected.set(
159
+ wf.name,
160
+ renderCodexSkill({
161
+ name: wf.name,
162
+ description: extractDescription(wf.content),
163
+ workflowPath: toPosixRelative(projectRoot, wf.sourcePath),
164
+ }),
165
+ );
166
+ }
167
+ assertProjectableNames(projectRoot, expected.keys());
168
+ return expected;
169
+ }
170
+
171
+ /**
172
+ * `name:` of a SKILL.md's front-matter, or null.
173
+ *
174
+ * @param {string} file
175
+ * @returns {string | null}
176
+ */
177
+ function skillNameOf(file) {
178
+ try {
179
+ const source = fs.readFileSync(file, 'utf8');
180
+ const fm = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
181
+ return fm?.[1].match(/^name:\s*["']?([^"'\s]+)/m)?.[1] ?? null;
182
+ } catch {
183
+ return null;
184
+ }
185
+ }
186
+
187
+ /**
188
+ * Fails loudly on a projected name Codex cannot load or that would collide
189
+ * with a hand-authored payload or local skill.
190
+ *
191
+ * @param {string} projectRoot
192
+ * @param {Iterable<string>} names
193
+ */
194
+ function assertProjectableNames(projectRoot, names) {
195
+ const taken = new Map();
196
+ for (const file of [
197
+ ...collectSkillFiles(projectRoot),
198
+ ...collectLocalSkillFiles(projectRoot),
199
+ ]) {
200
+ const skillName = skillNameOf(file);
201
+ if (skillName) taken.set(skillName, toPosixRelative(projectRoot, file));
202
+ }
203
+ for (const name of names) {
204
+ if (name.length > CODEX_SKILL_NAME_MAX) {
205
+ throw new Error(
206
+ `codex skill projection: workflow name '${name}' exceeds Codex's ${CODEX_SKILL_NAME_MAX}-character skill-name limit.`,
207
+ );
208
+ }
209
+ if (taken.has(name)) {
210
+ throw new Error(
211
+ `codex skill projection: workflow '${name}' collides with the skill of the same name at ${taken.get(name)} — rename one of them.`,
212
+ );
213
+ }
214
+ }
215
+ }
216
+
217
+ /**
218
+ * Generated skill directories currently on disk (marker-bearing only).
219
+ *
220
+ * @param {string} destDir
221
+ * @returns {string[]}
222
+ */
223
+ export function listGeneratedCodexSkills(destDir) {
224
+ if (!dirExists(destDir)) return [];
225
+ return fs
226
+ .readdirSync(destDir, { withFileTypes: true })
227
+ .filter((e) => e.isDirectory())
228
+ .map((e) => e.name)
229
+ .filter((name) => {
230
+ try {
231
+ return fs
232
+ .readFileSync(path.join(destDir, name, 'SKILL.md'), 'utf8')
233
+ .includes(CODEX_SKILL_MARKER);
234
+ } catch {
235
+ return false;
236
+ }
237
+ })
238
+ .sort();
239
+ }
240
+
241
+ /**
242
+ * Write the projection, reap marker-bearing orphans, skip unchanged files.
243
+ *
244
+ * @param {{
245
+ * projectRoot: string,
246
+ * payloadSrc?: string,
247
+ * localSrc?: string,
248
+ * destDir?: string,
249
+ * log?: (line: string) => void,
250
+ * }} opts
251
+ * @returns {{ written: string[], removed: string[], total: number }}
252
+ */
253
+ export function syncCodexSkills({
254
+ projectRoot,
255
+ payloadSrc,
256
+ localSrc,
257
+ destDir = path.join(projectRoot, ...CODEX_SKILLS_DIR.split('/')),
258
+ log = () => {},
259
+ }) {
260
+ const expected = expectedCodexSkills({ projectRoot, payloadSrc, localSrc });
261
+
262
+ const removed = [];
263
+ for (const name of listGeneratedCodexSkills(destDir)) {
264
+ if (expected.has(name)) continue;
265
+ fs.rmSync(path.join(destDir, name), { recursive: true, force: true });
266
+ removed.push(name);
267
+ log(` removed ${CODEX_SKILLS_DIR}/${name} (no longer in workflows)`);
268
+ }
269
+
270
+ const written = [];
271
+ for (const [name, body] of expected) {
272
+ const file = path.join(destDir, name, 'SKILL.md');
273
+ let current = null;
274
+ try {
275
+ current = fs.readFileSync(file, 'utf8');
276
+ } catch {
277
+ // absent — written below
278
+ }
279
+ if (current === body) continue;
280
+ if (current !== null && !current.includes(CODEX_SKILL_MARKER)) {
281
+ throw new Error(
282
+ `codex skill projection: ${CODEX_SKILLS_DIR}/${name}/SKILL.md is hand-authored — move it out of the generated directory.`,
283
+ );
284
+ }
285
+ fs.mkdirSync(path.dirname(file), { recursive: true });
286
+ fs.writeFileSync(file, body, 'utf8');
287
+ written.push(name);
288
+ log(` synced ${CODEX_SKILLS_DIR}/${name}`);
289
+ }
290
+ return { written, removed, total: expected.size };
291
+ }
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The `.agentrc.local.json` overlay, shared by the runtime resolver and the
3
+ * read-only `sync-agentrc` check so both validate the same effective config.
4
+ */
5
+
6
+ import path from 'node:path';
7
+
8
+ const LOCAL_AGENTRC = '.agentrc.local.json';
9
+
10
+ function isPlainObject(value) {
11
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
12
+ }
13
+
14
+ /**
15
+ * Deep-merge plain objects for the overlay. Arrays and scalars from
16
+ * `override` replace the base value at that key.
17
+ *
18
+ * @param {unknown} base
19
+ * @param {unknown} override
20
+ * @returns {unknown}
21
+ */
22
+ export function deepMergeObjects(base, override) {
23
+ if (!isPlainObject(override)) return override;
24
+ if (!isPlainObject(base)) return { ...override };
25
+ const out = { ...base };
26
+ for (const key of Object.keys(override)) {
27
+ out[key] = mergeValue(base[key], override[key]);
28
+ }
29
+ return out;
30
+ }
31
+
32
+ function mergeValue(baseVal, overrideVal) {
33
+ if (isPlainObject(overrideVal) && isPlainObject(baseVal)) {
34
+ return deepMergeObjects(baseVal, overrideVal);
35
+ }
36
+ return overrideVal;
37
+ }
38
+
39
+ /**
40
+ * Merge the project's overlay, when present, over the committed config.
41
+ * Throws a parse error naming `.agentrc.local.json`.
42
+ *
43
+ * @param {{ fsImpl: typeof import('node:fs'), projectRoot: string, committed: object }} opts
44
+ * @returns {{ effective: object, localPath: string|null }}
45
+ */
46
+ export function applyLocalOverlay({ fsImpl, projectRoot, committed }) {
47
+ const localPath = path.join(projectRoot, LOCAL_AGENTRC);
48
+ if (!fsImpl.existsSync(localPath)) {
49
+ return { effective: committed, localPath: null };
50
+ }
51
+ const local = parseOverlay(fsImpl, localPath);
52
+ return { effective: deepMergeObjects(committed, local), localPath };
53
+ }
54
+
55
+ function parseOverlay(fsImpl, localPath) {
56
+ try {
57
+ return JSON.parse(fsImpl.readFileSync(localPath, 'utf8'));
58
+ } catch (err) {
59
+ const wrapped = new Error(
60
+ `Failed to parse ${LOCAL_AGENTRC}: ${err.message}`,
61
+ );
62
+ wrapped.localPath = localPath;
63
+ throw wrapped;
64
+ }
65
+ }
66
+
67
+ const OPERATOR_HANDLE_REMEDY = `set github.operatorHandle in the gitignored ${LOCAL_AGENTRC} (per-operator), or keep the "@[USERNAME]" placeholder committed in .agentrc.json`;
68
+
69
+ function isMissingOperatorHandle(e) {
70
+ return (
71
+ e.keyword === 'required' &&
72
+ e.instancePath === '/github' &&
73
+ e.params?.missingProperty === 'operatorHandle'
74
+ );
75
+ }
76
+
77
+ /**
78
+ * Render AJV errors for an `.agentrc` validation failure, one string per
79
+ * error. A missing `github.operatorHandle` carries where to put it.
80
+ *
81
+ * @param {Array<{ instancePath?: string, message?: string, keyword?: string, params?: object }>|null|undefined} errors
82
+ * @returns {string[]}
83
+ */
84
+ export function formatAgentrcErrors(errors) {
85
+ return (errors || []).map((e) => {
86
+ const line = `${e.instancePath || '(root)'} ${e.message}`;
87
+ return isMissingOperatorHandle(e)
88
+ ? `${line} — ${OPERATOR_HANDLE_REMEDY}`
89
+ : line;
90
+ });
91
+ }
@@ -1,13 +1,16 @@
1
1
  /**
2
- * Read-only `.agentrc.json` reconciliation: validate against the schema
3
- * (never silently strip), never auto-fill defaults (the runtime layers them
4
- * at read time), and flag leaves equal to their default as `[REDUNDANT]`.
2
+ * Read-only `.agentrc.json` reconciliation: validate the effective config —
3
+ * `.agentrc.local.json` deep-merged over `.agentrc.json`, as the runtime
4
+ * resolver does — against the schema (never silently strip), never auto-fill
5
+ * defaults (the runtime layers them at read time), and flag committed leaves
6
+ * equal to their default as `[REDUNDANT]`.
5
7
  */
6
8
 
7
9
  import fs from 'node:fs';
8
10
  import path from 'node:path';
9
11
  import { AGENTRC_SCHEMA, getAgentrcValidator } from '../config-schema.js';
10
12
  import { deepEqual } from '../json-utils.js';
13
+ import { applyLocalOverlay, formatAgentrcErrors } from './agentrc-overlay.js';
11
14
  import {
12
15
  getAgentrcDefaults,
13
16
  IDENTITY_PLACEHOLDER_PATHS,
@@ -29,6 +32,7 @@ import {
29
32
  * @property {SyncChange[]} changes
30
33
  * @property {string[]} errors
31
34
  * @property {string} configPath
35
+ * @property {string|null} [localPath] the merged `.agentrc.local.json`, if any
32
36
  * @property {boolean} wrote whether `.agentrc.json` was rewritten
33
37
  */
34
38
 
@@ -69,20 +73,23 @@ export function syncAgentrc(opts) {
69
73
  };
70
74
  }
71
75
 
76
+ let overlay;
77
+ try {
78
+ overlay = applyLocalOverlay({ fsImpl, projectRoot, committed: raw });
79
+ } catch (err) {
80
+ return invalidResult(configPath, err.localPath, [err.message]);
81
+ }
82
+
72
83
  const validate = getAgentrcValidator();
73
- if (!validate(raw)) {
74
- const errors = (validate.errors || []).map(
75
- (e) => `${e.instancePath || '(root)'} ${e.message}`,
76
- );
77
- return {
78
- status: 'invalid',
79
- changes: [],
80
- errors,
84
+ if (!validate(overlay.effective)) {
85
+ return invalidResult(
81
86
  configPath,
82
- wrote: false,
83
- };
87
+ overlay.localPath,
88
+ formatAgentrcErrors(validate.errors),
89
+ );
84
90
  }
85
91
 
92
+ // Advisories target the committed file only: the overlay is per-machine.
86
93
  const changes = collectRedundantAdvisories(raw, defaults);
87
94
 
88
95
  return {
@@ -90,6 +97,18 @@ export function syncAgentrc(opts) {
90
97
  changes,
91
98
  errors: [],
92
99
  configPath,
100
+ localPath: overlay.localPath,
101
+ wrote: false,
102
+ };
103
+ }
104
+
105
+ function invalidResult(configPath, localPath, errors) {
106
+ return {
107
+ status: 'invalid',
108
+ changes: [],
109
+ errors,
110
+ configPath,
111
+ localPath,
93
112
  wrote: false,
94
113
  };
95
114
  }
@@ -168,16 +187,13 @@ export function formatSyncReport(result) {
168
187
  return lines.join('\n');
169
188
  }
170
189
  if (result.status === 'invalid') {
171
- lines.push('[sync-agentrc] ❌ Validation failed:');
190
+ lines.push(`[sync-agentrc] ❌ Validation failed${overlayNote(result)}:`);
172
191
  for (const err of result.errors) lines.push(` - ${err}`);
173
192
  return lines.join('\n');
174
193
  }
175
194
  const redundant = result.changes.filter((c) => c.op === 'REDUNDANT');
176
- if (redundant.length === 0) {
177
- lines.push('[sync-agentrc] ✅ No changes required.');
178
- return lines.join('\n');
179
- }
180
- lines.push('[sync-agentrc] ✅ No changes required.');
195
+ lines.push(`[sync-agentrc] ✅ No changes required${overlayNote(result)}.`);
196
+ if (redundant.length === 0) return lines.join('\n');
181
197
  lines.push(
182
198
  `[sync-agentrc] Advisories: ${redundant.length} project key(s) match framework defaults — informational only.`,
183
199
  );
@@ -190,6 +206,10 @@ export function formatSyncReport(result) {
190
206
  return lines.join('\n');
191
207
  }
192
208
 
209
+ function overlayNote(result) {
210
+ return result.localPath ? ` (with overlay ${result.localPath})` : '';
211
+ }
212
+
193
213
  function previewValue(value) {
194
214
  let s;
195
215
  try {
@@ -6,6 +6,10 @@
6
6
 
7
7
  import fs from 'node:fs';
8
8
  import path from 'node:path';
9
+ import {
10
+ deepMergeObjects,
11
+ formatAgentrcErrors,
12
+ } from './config/agentrc-overlay.js';
9
13
  import { getCiDelivery } from './config/ci.js';
10
14
  import { getCommands } from './config/commands.js';
11
15
  import { getGitHub } from './config/github.js';
@@ -90,45 +94,6 @@ function applyDeliveryDefaults(rawDelivery) {
90
94
  return delivery;
91
95
  }
92
96
 
93
- /**
94
- * Deep-merge plain objects for the `.agentrc.local.json` overlay. Arrays and
95
- * scalars from `override` replace the base value at that key.
96
- *
97
- * @param {unknown} base
98
- * @param {unknown} override
99
- * @returns {unknown}
100
- */
101
- function deepMergeObjects(base, override) {
102
- if (
103
- override === null ||
104
- typeof override !== 'object' ||
105
- Array.isArray(override)
106
- ) {
107
- return override;
108
- }
109
- if (base === null || typeof base !== 'object' || Array.isArray(base)) {
110
- return { ...override };
111
- }
112
- const out = { ...base };
113
- for (const key of Object.keys(override)) {
114
- const baseVal = base[key];
115
- const overrideVal = override[key];
116
- if (
117
- overrideVal !== null &&
118
- typeof overrideVal === 'object' &&
119
- !Array.isArray(overrideVal) &&
120
- baseVal !== null &&
121
- typeof baseVal === 'object' &&
122
- !Array.isArray(baseVal)
123
- ) {
124
- out[key] = deepMergeObjects(baseVal, overrideVal);
125
- } else {
126
- out[key] = overrideVal;
127
- }
128
- }
129
- return out;
130
- }
131
-
132
97
  /** @param {import('node:fs')} fsImpl */
133
98
  function readJsonConfigFile(fsImpl, filePath, label) {
134
99
  try {
@@ -231,9 +196,7 @@ export function resolveConfig(opts) {
231
196
  if (validate) {
232
197
  const validateAgentrc = getAgentrcValidator();
233
198
  if (!validateAgentrc(raw)) {
234
- const details = (validateAgentrc.errors || [])
235
- .map((e) => `${e.instancePath || '(root)'} ${e.message}`)
236
- .join(', ');
199
+ const details = formatAgentrcErrors(validateAgentrc.errors).join(', ');
237
200
  throw new Error(`[config] Invalid .agentrc.json: ${details}`);
238
201
  }
239
202
  }
@@ -71,7 +71,7 @@ export const CODE_REVIEW_SCHEMA = {
71
71
  description:
72
72
  'Review-provider chain and on-branch remediation threshold for the /mandrel-deliver code-review ceremony.',
73
73
  properties: {
74
- // An adapter whose probe fails (e.g. codex without `/codex:review`)
74
+ // An adapter whose probe fails (e.g. codex without the Codex CLI)
75
75
  // hard-fails at construction — no silent fallback to native.
76
76
  providers: {
77
77
  type: 'array',
@@ -92,7 +92,7 @@ const COMMANDS_SCHEMA = {
92
92
  typecheck: {
93
93
  ...NULLABLE_NONEMPTY_SAFE_STRING,
94
94
  description:
95
- 'Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it.',
95
+ 'Static type-check command run as a close-validation gate. Left unset (the `null` default), it falls back to `npm run typecheck`. An explicit `null` disables the gate for projects with no type layer: close reports it as skipped (`typecheck-disabled`) and runs nothing. The empty string is rejected so a typo cannot silently disable it.',
96
96
  default: COMMANDS_DEFAULTS.typecheck,
97
97
  },
98
98
  lint: {
@@ -49,6 +49,7 @@ const LOCK_DEFAULTS = Object.freeze({
49
49
  sleepFn: (ms) => defaultSleep(ms),
50
50
  acquireOnceFn: (opts) => acquireSweepLock(opts),
51
51
  onWaitExpired: () => LOCK_WAIT_EXPIRED_EXIT_CODE,
52
+ onLockOutcome: () => {},
52
53
  rerunCommand: 'the same command',
53
54
  });
54
55
 
@@ -168,6 +169,7 @@ function consult(probe, applies) {
168
169
  * lockPath?: string,
169
170
  * skipIfSatisfied?: () => T|undefined,
170
171
  * onWaitExpired?: (holder: import('./full-suite-queue.js').LockHolder) => T,
172
+ * onLockOutcome?: (outcome: object) => void,
171
173
  * rerunCommand?: string,
172
174
  * }} opts A non-`undefined` `skipIfSatisfied` return stands in for the spawn.
173
175
  * @param {(timing: { lockWaitMs: number }) => Promise<T>} spawn
@@ -180,6 +182,7 @@ export async function withFullSuiteLockAsync(options, spawn) {
180
182
  lock === null && lockPath !== null
181
183
  ? await waitInLine({ ...opts, lockPath })
182
184
  : { held: lock, expired: false, waited: false, waitedMs: 0 };
185
+ reportOutcome(opts.onLockOutcome, wait);
183
186
  try {
184
187
  return await spawnOrStandIn(opts, wait, spawn);
185
188
  } finally {
@@ -187,6 +190,23 @@ export async function withFullSuiteLockAsync(options, spawn) {
187
190
  }
188
191
  }
189
192
 
193
+ /** An I/O-error wait is no outcome; a throwing callback never costs the spawn. */
194
+ function reportOutcome(onLockOutcome, wait) {
195
+ if (!isFinishedWait(wait)) return;
196
+ try {
197
+ onLockOutcome(lockOutcome(wait));
198
+ } catch {}
199
+ }
200
+
201
+ function isFinishedWait(wait) {
202
+ return wait.waited && (wait.expired || Boolean(wait.held?.acquired));
203
+ }
204
+
205
+ function lockOutcome({ waitedMs, expired, holder }) {
206
+ const outcome = { waitedSeconds: Math.round(waitedMs / 1000), expired };
207
+ return expired && holder ? { ...outcome, holder } : outcome;
208
+ }
209
+
190
210
  function withDefaults(options) {
191
211
  const opts = { ...LOCK_DEFAULTS };
192
212
  for (const [key, value] of Object.entries(options)) {