mandrel 2.77.0 → 2.79.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 (44) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +2 -3
  3. package/.agents/audit-checklists/architecture.md +1 -0
  4. package/.agents/audit-checklists/clean-code.md +1 -0
  5. package/.agents/audit-checklists/devops.md +4 -1
  6. package/.agents/audit-checklists/security.md +1 -1
  7. package/.agents/docs/configuration.md +1 -1
  8. package/.agents/schemas/agentrc.schema.json +1 -1
  9. package/.agents/scripts/bootstrap.js +87 -16
  10. package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
  11. package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
  12. package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
  13. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
  14. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  15. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  16. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  17. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  18. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  20. package/.agents/scripts/lib/config/explain.js +2 -1
  21. package/.agents/scripts/lib/config-settings-schema.js +2 -1
  22. package/.agents/scripts/lib/findings/severity.js +33 -6
  23. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  24. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  25. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  26. package/.agents/scripts/lib/test-run-credit.js +46 -17
  27. package/.agents/workflows/audit-architecture.md +20 -4
  28. package/.agents/workflows/audit-baselines.md +3 -3
  29. package/.agents/workflows/audit-clean-code.md +17 -1
  30. package/.agents/workflows/audit-devops.md +58 -14
  31. package/.agents/workflows/audit-exceptions.md +3 -2
  32. package/.agents/workflows/audit-performance.md +22 -0
  33. package/.agents/workflows/audit-quality.md +30 -0
  34. package/.agents/workflows/audit-security.md +23 -8
  35. package/.agents/workflows/audit-to-stories.md +9 -6
  36. package/.agents/workflows/helpers/audit-lens-core.md +53 -8
  37. package/README.md +13 -1
  38. package/docs/CHANGELOG.md +22 -0
  39. package/lib/cli/registry.js +85 -12
  40. package/lib/cli/uninstall.js +34 -18
  41. package/lib/cli/update.js +37 -6
  42. package/lib/migrations/index.js +2 -0
  43. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  44. package/package.json +1 -1
@@ -29,6 +29,19 @@ export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
29
29
 
30
30
  export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
31
31
 
32
+ /** The pre-guard `prepare` form; bootstrap and the 2.79.0 migration upgrade it. */
33
+ export const LEGACY_PREPARE_COMMAND = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
34
+
35
+ /**
36
+ * Exits 1 when `.agents/scripts/` exists so `||` runs the projections, and 0
37
+ * otherwise so a manifest-only `npm ci` (no `.agents/` yet) skips them. Only
38
+ * `node -e` and `||`/`&&`/`()` — portable across npm's sh and cmd shells.
39
+ */
40
+ const PREPARE_GUARD = `node -e "process.exit(require('fs').existsSync('.agents/scripts')?1:0)"`;
41
+
42
+ /** The `prepare` script bootstrap writes: guarded, then both projections. */
43
+ export const PREPARE_COMMAND = `${PREPARE_GUARD} || (${LEGACY_PREPARE_COMMAND})`;
44
+
32
45
  export { SYSTEM_PROMPT_BLOCK, SYSTEM_PROMPT_IMPORT };
33
46
 
34
47
  /** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
@@ -40,6 +53,11 @@ export const GITIGNORE_BLOCKS = Object.freeze({
40
53
  block:
41
54
  '\n# Claude Code command projection is generated from .agents/workflows/ — do not commit.\n.claude/commands/\n',
42
55
  },
56
+ agents: {
57
+ pattern: /^\s*\.claude\/agents\/?\s*$/m,
58
+ block:
59
+ '\n# Claude Code agent projection is generated from .agents/agents/ by `prepare` — do not commit.\n.claude/agents/\n',
60
+ },
43
61
  mcp: {
44
62
  pattern: /^\s*\.mcp\.json\s*$/m,
45
63
  block:
@@ -137,22 +155,38 @@ function ensureScript(scripts, key, command) {
137
155
  return 'added';
138
156
  }
139
157
 
140
- /** Append each projection independently so a partial prepare gains the other. */
141
- function ensurePrepareScript(scripts) {
158
+ /** Each projection `prepare` must run: [script file it names, its command]. */
159
+ const PREPARE_PROJECTIONS = Object.freeze([
160
+ ['sync-claude-commands.js', SYNC_COMMAND],
161
+ ['sync-claude-agents.js', SYNC_AGENTS_COMMAND],
162
+ ]);
163
+
164
+ /** Outcomes that mean `ensurePackageJson` changed the manifest. */
165
+ const PACKAGE_JSON_MUTATIONS = new Set([true, 'added', 'appended', 'upgraded']);
166
+
167
+ /**
168
+ * Seed the guarded `prepare`, upgrade the exact legacy bare form to it, and
169
+ * otherwise append each missing projection so a partial prepare gains the
170
+ * other. An operator `prepare` already naming both scripts is left alone.
171
+ *
172
+ * @param {Record<string, string>} scripts - Mutated in place.
173
+ * @returns {'added'|'upgraded'|'appended'|'already-present'}
174
+ */
175
+ export function ensurePrepareScript(scripts) {
142
176
  const prepare = scripts.prepare;
143
177
  if (!prepare) {
144
- scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
178
+ scripts.prepare = PREPARE_COMMAND;
145
179
  return 'added';
146
180
  }
147
- let next = prepare;
148
- if (!next.includes('sync-claude-commands.js')) {
149
- next = `${next} && ${SYNC_COMMAND}`;
150
- }
151
- if (!next.includes('sync-claude-agents.js')) {
152
- next = `${next} && ${SYNC_AGENTS_COMMAND}`;
181
+ if (prepare === LEGACY_PREPARE_COMMAND) {
182
+ scripts.prepare = PREPARE_COMMAND;
183
+ return 'upgraded';
153
184
  }
154
- if (next === prepare) return 'already-present';
155
- scripts.prepare = next;
185
+ const missing = PREPARE_PROJECTIONS.filter(
186
+ ([script]) => !prepare.includes(script),
187
+ ).map(([, command]) => command);
188
+ if (missing.length === 0) return 'already-present';
189
+ scripts.prepare = [prepare, ...missing].join(' && ');
156
190
  return 'appended';
157
191
  }
158
192
 
@@ -190,8 +224,8 @@ export function ensurePackageJson(ctx) {
190
224
  scriptsPrepare: ensurePrepareScript(pkg.scripts),
191
225
  scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
192
226
  };
193
- const mutated = Object.values(outcomes).some(
194
- (v) => v === true || v === 'added' || v === 'appended',
227
+ const mutated = Object.values(outcomes).some((v) =>
228
+ PACKAGE_JSON_MUTATIONS.has(v),
195
229
  );
196
230
  if (mutated) writeJson(pkgPath, pkg, fsImpl);
197
231
  return { ...outcomes, path: pkgPath, mutated };
@@ -309,8 +343,9 @@ async function validateAgentrc(ctx) {
309
343
  *
310
344
  * @param {object} ctx
311
345
  * @param {typeof fs} [ctx.fsImpl]
346
+ * @param {readonly string[]} [keys] - Restrict to these block keys (default: all).
312
347
  */
313
- export function ensureGitignore(ctx) {
348
+ export function ensureGitignore(ctx, keys = Object.keys(GITIGNORE_BLOCKS)) {
314
349
  const { fsImpl = fs } = ctx;
315
350
  const target = path.join(ctx.projectRoot, '.gitignore');
316
351
  const existing = fsImpl.existsSync(target)
@@ -318,7 +353,8 @@ export function ensureGitignore(ctx) {
318
353
  : '';
319
354
  let body = existing;
320
355
  const outcomes = {};
321
- for (const [key, def] of Object.entries(GITIGNORE_BLOCKS)) {
356
+ for (const key of keys) {
357
+ const def = GITIGNORE_BLOCKS[key];
322
358
  if (def.pattern.test(body)) {
323
359
  outcomes[key] = 'already-present';
324
360
  continue;
@@ -26,6 +26,7 @@ const KNOWN_FLAGS = Object.freeze({
26
26
  'help',
27
27
  'dry-run',
28
28
  'reap-conflicting-workflows',
29
+ 'no-project',
29
30
  ],
30
31
  });
31
32
 
@@ -154,6 +155,30 @@ export function inferDefaults(projectRoot) {
154
155
  * @property {NodeJS.WritableStream} output
155
156
  */
156
157
 
158
+ /** A bare flag (`true`), an empty value, or `none` is an explicit skip. */
159
+ const isSkipToken = (v) =>
160
+ v === true ||
161
+ (typeof v === 'string' && ['', 'none'].includes(v.trim().toLowerCase()));
162
+
163
+ /**
164
+ * Explicit skip for a question carrying `skipFlag` → `''`, which no later
165
+ * resolver or default overrides. An env var skips only when PRESENT and no
166
+ * value flag is set.
167
+ *
168
+ * @param {ResolverContext} ctx
169
+ * @returns {{ kind: 'value'|'skip', value?: string }}
170
+ */
171
+ function resolveExplicitSkip({ q, flags, env }) {
172
+ if (!q.skipFlag) return { kind: 'skip' };
173
+ const flagValue = flags[q.flag];
174
+ const envSkip =
175
+ flagValue === undefined &&
176
+ Object.hasOwn(env, q.env ?? '') &&
177
+ isSkipToken(env[q.env]);
178
+ const skip = flags[q.skipFlag] === true || isSkipToken(flagValue) || envSkip;
179
+ return skip ? { kind: 'value', value: '' } : { kind: 'skip' };
180
+ }
181
+
157
182
  /**
158
183
  * @param {ResolverContext} ctx
159
184
  * @returns {{ kind: 'value'|'skip', value?: string }}
@@ -299,6 +324,7 @@ export function resolveAssumeYes(ctx) {
299
324
 
300
325
  /** Priority order; the first non-`skip` outcome wins. */
301
326
  export const RESOLVERS = Object.freeze([
327
+ resolveExplicitSkip,
302
328
  resolveFromFlag,
303
329
  resolveFromEnv,
304
330
  resolveFromSilent,
@@ -313,11 +339,13 @@ export const RESOLVERS = Object.freeze([
313
339
  * @param {object} args
314
340
  * @param {Array<{ key: string, flag: string, env?: string, message: string,
315
341
  * default?: string|null, required?: boolean,
342
+ * skipFlag?: string,
316
343
  * validate?: (v: string) => string|null }>} args.questions
317
344
  * @param {Record<string, string|boolean>} args.flags
318
345
  * @param {boolean} args.interactive
319
346
  * @param {boolean} args.assumeYes
320
347
  * @param {Iterable<string>} [args.silentAccept]
348
+ * @param {NodeJS.ProcessEnv} [args.env=process.env]
321
349
  * @param {NodeJS.ReadableStream} [args.input=process.stdin]
322
350
  * @param {NodeJS.WritableStream} [args.output=process.stdout]
323
351
  * @returns {Promise<{ answers: Record<string, string>, missing: string[] }>}
@@ -329,6 +357,7 @@ export async function collectAnswers(args) {
329
357
  interactive,
330
358
  assumeYes,
331
359
  silentAccept,
360
+ env = process.env,
332
361
  input = process.stdin,
333
362
  output = process.stdout,
334
363
  } = args;
@@ -345,7 +374,7 @@ export async function collectAnswers(args) {
345
374
  const ctx = {
346
375
  q,
347
376
  flags,
348
- env: process.env,
377
+ env,
349
378
  silentSet,
350
379
  interactive,
351
380
  assumeYes,
@@ -13,6 +13,13 @@ const TYPECHECK_FALLBACK = 'npm run typecheck';
13
13
  */
14
14
  const LINT_FALLBACK = 'npm run lint';
15
15
 
16
+ /**
17
+ * Must stay byte-identical: it is the close `test` gate's argv and the credit
18
+ * identity `test-run-credit` and `verify-credit` hash, so drift would
19
+ * invalidate every recorded `test` evidence record.
20
+ */
21
+ const TEST_FALLBACK = 'npm test';
22
+
16
23
  export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
17
24
 
18
25
  const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
@@ -63,6 +70,32 @@ export function resolveLintCommand(config) {
63
70
  return resolveCommandWithFallback(config, 'lint', LINT_FALLBACK);
64
71
  }
65
72
 
73
+ /**
74
+ * The close `test` gate's command. Like every `project.commands.*` key it is a
75
+ * single argv — the schema rejects `;`, `&&`, pipes and substitution.
76
+ *
77
+ * @param {{ project?: { commands?: object } } | null | undefined} config
78
+ * @returns {string}
79
+ */
80
+ export function resolveTestCommand(config) {
81
+ return resolveCommandWithFallback(config, 'test', TEST_FALLBACK);
82
+ }
83
+
84
+ /**
85
+ * The argv close's `test` gate spawns — the one identity every `test`
86
+ * credit (deposit, close probe, `verify[]` credit) hashes. Whitespace split,
87
+ * as the gate builder splits every other `commands.*` key.
88
+ *
89
+ * @param {{ project?: { commands?: object } } | null | undefined} config
90
+ * @returns {{ cmd: string, args: string[] }}
91
+ */
92
+ export function resolveTestGateArgv(config) {
93
+ const [cmd, ...args] = resolveTestCommand(config)
94
+ .split(/\s+/)
95
+ .filter(Boolean);
96
+ return { cmd, args };
97
+ }
98
+
66
99
  /**
67
100
  * @param {{ project?: { commands?: object } } | null | undefined} config
68
101
  * @returns {string}
@@ -15,6 +15,7 @@ import {
15
15
  resolveFormatCheckCommand,
16
16
  resolveFormatWriteCommand,
17
17
  resolveLintCommand,
18
+ resolveTestGateArgv,
18
19
  resolveTypecheckCommand,
19
20
  } from './commands.js';
20
21
 
@@ -80,16 +81,20 @@ function isCoverageCaptureActive(config, scripts) {
80
81
 
81
82
  /**
82
83
  * The plain `test` gate, unless coverage-capture will run the suite — every
83
- * close must keep exactly one working test gate.
84
+ * close must keep exactly one working test gate. Its argv is
85
+ * `project.commands.test` (default `npm test`).
84
86
  *
85
87
  * @param {boolean} coverageCaptureRunsSuite
88
+ * @param {object|undefined|null} config - Canonical resolved config.
86
89
  * @returns {Gate[]}
87
90
  */
88
- function buildTestGateEntry(coverageCaptureRunsSuite) {
91
+ function buildTestGateEntry(coverageCaptureRunsSuite, config) {
89
92
  if (coverageCaptureRunsSuite) return [];
90
93
  // `fullSuiteLock` serializes this suite behind the host lock; when
91
94
  // coverage-capture runs instead, `runCapture` takes the lock itself.
92
- return [{ name: 'test', cmd: 'npm', args: ['test'], fullSuiteLock: true }];
95
+ return [
96
+ { name: 'test', ...resolveTestGateArgv(config), fullSuiteLock: true },
97
+ ];
93
98
  }
94
99
 
95
100
  const CHECK_BASELINES_HINT =
@@ -424,10 +429,11 @@ export function buildDefaultGates({
424
429
  } = {}) {
425
430
  const scripts = packageScripts ?? readPackageScripts(cwd);
426
431
  const coverageCaptureActive = isCoverageCaptureActive(config, scripts);
427
- // A credited bare `npm test` registers the plain `test` gate beside the
432
+ // A credited `project.commands.test` run registers the plain `test` gate beside the
428
433
  // capture so the credit is reported, never re-spent.
429
434
  const testCredited = resolveTestCredited({
430
435
  coverageCaptureActive,
436
+ config,
431
437
  storyId,
432
438
  cwd,
433
439
  evidenceCwd,
@@ -491,6 +497,7 @@ export function buildDefaultGates({
491
497
  captureSkipPredicted,
492
498
  testCredited,
493
499
  }),
500
+ config,
494
501
  ),
495
502
  {
496
503
  name: 'format',
@@ -45,7 +45,8 @@ const KEY_MEANINGS = Object.freeze({
45
45
  'Root for gitignored scratch output (per-run state, mirrors, logs).',
46
46
  'project.docsContextFiles':
47
47
  'Authoritative files an agent must read before starting any task.',
48
- 'project.commands.test': 'Test command the close-validation chain runs.',
48
+ 'project.commands.test':
49
+ "Test command close's `test` gate runs and its credit identity hashes.",
49
50
  'project.commands.typecheck':
50
51
  'Typecheck command (null disables the typecheck gate).',
51
52
  'project.commands.formatCheck':
@@ -85,7 +85,8 @@ const COMMANDS_SCHEMA = {
85
85
  test: {
86
86
  ...SAFE_STRING,
87
87
  minLength: 1,
88
- description: 'Full test-suite command run by the close-validation chain.',
88
+ description:
89
+ "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`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution).",
89
90
  default: COMMANDS_DEFAULTS.test,
90
91
  },
91
92
  typecheck: {
@@ -29,14 +29,21 @@ const SEVERITY_ALIASES = Object.freeze({
29
29
  trivial: 'info',
30
30
  });
31
31
 
32
+ /**
33
+ * A named declaration, not a module-scope arrow: CRAP `--seat-missing` cannot
34
+ * resolve coverage for an anonymous function with no enclosing one.
35
+ *
36
+ * @param {string} severity
37
+ * @param {number} index
38
+ * @returns {[string, number]}
39
+ */
40
+ function rankEntry(severity, index) {
41
+ return [severity, SEVERITIES.length - 1 - index];
42
+ }
43
+
32
44
  /** @type {Readonly<Record<string, number>>} */
33
45
  export const SEVERITY_RANK = Object.freeze(
34
- Object.fromEntries(
35
- SEVERITIES.map((severity, index) => [
36
- severity,
37
- SEVERITIES.length - 1 - index,
38
- ]),
39
- ),
46
+ Object.fromEntries(SEVERITIES.map(rankEntry)),
40
47
  );
41
48
 
42
49
  /**
@@ -86,6 +93,26 @@ export function highestSeverity(values) {
86
93
  return best;
87
94
  }
88
95
 
96
+ /**
97
+ * Stable highest-first order over items carrying a `severity` field; an
98
+ * unresolvable severity sorts after `info` rather than being dropped.
99
+ *
100
+ * @template {{ severity?: unknown }} T
101
+ * @param {readonly T[]} items
102
+ * @returns {T[]} a new array.
103
+ */
104
+ export function sortBySeverity(items) {
105
+ return [...items].sort(compareSeverityDesc);
106
+ }
107
+
108
+ function rankOf(item) {
109
+ return SEVERITY_RANK[item?.severity] ?? -1;
110
+ }
111
+
112
+ function compareSeverityDesc(a, b) {
113
+ return rankOf(b) - rankOf(a);
114
+ }
115
+
89
116
  /** Test-only: the alias-table invariant is unobservable via the API. */
90
117
  export const __testing = {
91
118
  DEFAULT_SEVERITY,