mandrel 2.78.0 → 2.80.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 (57) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +8 -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/data-model.md +9 -1
  6. package/.agents/audit-checklists/devops.md +4 -1
  7. package/.agents/audit-checklists/security.md +1 -1
  8. package/.agents/docs/agentrc-reference.json +3 -0
  9. package/.agents/docs/configuration.md +2 -2
  10. package/.agents/docs/workflows.md +1 -1
  11. package/.agents/schemas/agentrc.schema.json +20 -2
  12. package/.agents/schemas/audit-rules.json +5 -1
  13. package/.agents/scripts/bootstrap.js +87 -16
  14. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  15. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  16. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  17. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  18. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  19. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  20. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  21. package/.agents/scripts/lib/config/explain.js +3 -2
  22. package/.agents/scripts/lib/config-settings-schema.js +20 -2
  23. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  24. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  25. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  26. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  27. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  28. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  29. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
  30. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
  31. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  32. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  33. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  34. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  35. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  36. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  37. package/.agents/scripts/lib/test-run-credit.js +46 -17
  38. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  39. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  40. package/.agents/workflows/audit-architecture.md +20 -4
  41. package/.agents/workflows/audit-clean-code.md +17 -1
  42. package/.agents/workflows/audit-data-model.md +94 -10
  43. package/.agents/workflows/audit-devops.md +58 -14
  44. package/.agents/workflows/audit-performance.md +22 -0
  45. package/.agents/workflows/audit-quality.md +30 -0
  46. package/.agents/workflows/audit-security.md +23 -8
  47. package/.agents/workflows/audit-to-stories.md +22 -7
  48. package/.agents/workflows/helpers/audit-lens-core.md +56 -7
  49. package/.agents/workflows/helpers/plan-reference.md +11 -3
  50. package/README.md +13 -1
  51. package/docs/CHANGELOG.md +24 -0
  52. package/lib/cli/registry.js +85 -12
  53. package/lib/cli/uninstall.js +34 -18
  54. package/lib/cli/update.js +37 -6
  55. package/lib/migrations/index.js +2 -0
  56. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  57. package/package.json +1 -1
@@ -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':
@@ -172,7 +173,7 @@ const PREFIX_MEANINGS = Object.freeze([
172
173
  ],
173
174
  [
174
175
  'qa.environments',
175
- 'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate).',
176
+ 'QA harness deployment target (baseUrl, per-environment sign-in seam, allowWrites gate, optional read-only database audit target).',
176
177
  ],
177
178
  ['qa.personas', 'QA harness persona / credential mapping.'],
178
179
  [
@@ -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: {
@@ -466,15 +467,31 @@ const QA_PERSONAS_SCHEMA = {
466
467
  ],
467
468
  };
468
469
 
470
+ // The connection string is a secret, so the config carries only the NAME of
471
+ // the environment variable that holds it — a literal URL cannot match the
472
+ // pattern, and there is no `url` key to put one in.
473
+ const QA_DATABASE_SCHEMA = {
474
+ type: 'object',
475
+ description:
476
+ 'Database target for the `/audit-data-model` read-only live-schema pass. `urlEnv` is the name of the environment variable carrying the connection string — never the URL itself. `allowAudit` opts the environment in to that pass; it defaults to true only for `local`.',
477
+ properties: {
478
+ urlEnv: { type: 'string', pattern: '^[A-Z_][A-Z0-9_]*$' },
479
+ allowAudit: { type: 'boolean' },
480
+ },
481
+ required: ['urlEnv'],
482
+ additionalProperties: false,
483
+ };
484
+
469
485
  const QA_ENVIRONMENTS_SCHEMA = {
470
486
  type: 'object',
471
487
  description:
472
- 'Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.',
488
+ "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`.",
473
489
  // Illustrative; `staging` omits `signInSeam` to show it is optional.
474
490
  default: {
475
491
  local: {
476
492
  baseUrl: 'http://localhost:3000',
477
493
  signInSeam: { urlTemplate: '/dev/sign-in-as/{persona}' },
494
+ database: { urlEnv: 'DATABASE_URL' },
478
495
  },
479
496
  staging: {
480
497
  baseUrl: 'https://staging.example.test',
@@ -488,6 +505,7 @@ const QA_ENVIRONMENTS_SCHEMA = {
488
505
  baseUrl: { ...SAFE_STRING, minLength: 1 },
489
506
  signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
490
507
  allowWrites: { type: 'boolean' },
508
+ database: QA_DATABASE_SCHEMA,
491
509
  },
492
510
  // No seam is a state QA workflows handle (unauthenticated drive).
493
511
  required: ['baseUrl'],
@@ -0,0 +1,95 @@
1
+ /**
2
+ * lib/findings/audit-finding-record.js — the seed-only `audit-finding` record:
3
+ * one finding's exact sha → files → label identity, so plan-persist can
4
+ * attribute it to the Stories whose `changes[]` cover its files. Sits beside
5
+ * the footer helpers in `route-finding.js`, whose `extractProvenanceFooters`
6
+ * carries these records through a truncated seed.
7
+ *
8
+ * @module lib/findings/audit-finding-record
9
+ */
10
+
11
+ import { SHA1_RE } from './route-finding.js';
12
+
13
+ const RECORD_MARKER = 'audit-finding:';
14
+
15
+ /**
16
+ * Render one record. Every value is URI-encoded: no path can inject the `,`, space or `>` the record
17
+ * is delimited by. Never stamped on a Story body.
18
+ *
19
+ * @param {{ sha: string, key?: string, label?: string|null, files?: string[] }} record
20
+ * @returns {string}
21
+ */
22
+ export function auditFindingRecord({
23
+ sha,
24
+ key = '',
25
+ label = null,
26
+ files = [],
27
+ }) {
28
+ if (typeof sha !== 'string' || !SHA1_RE.test(sha)) {
29
+ throw new Error(
30
+ 'auditFindingRecord: sha must be a 40-char sha1 hex string',
31
+ );
32
+ }
33
+ const enc = encodeURIComponent;
34
+ const parts = [`sha=${sha}`, `key=${enc(key ?? '')}`];
35
+ if (typeof label === 'string' && label.length > 0) {
36
+ parts.push(`label=${enc(label)}`);
37
+ }
38
+ parts.push(`files=${(files ?? []).map(enc).join(',')}`);
39
+ return `<!-- ${RECORD_MARKER} ${parts.join(' ')} -->`;
40
+ }
41
+
42
+ /**
43
+ * @param {string} raw
44
+ * @returns {string|null} null when the value is not valid URI encoding.
45
+ */
46
+ function decodeRecordValue(raw) {
47
+ try {
48
+ return decodeURIComponent(raw);
49
+ } catch {
50
+ return null;
51
+ }
52
+ }
53
+
54
+ /**
55
+ * @param {string} inner — the record's `k=v k=v` payload.
56
+ * @returns {{ sha: string, key: string, label: string|null, files: string[] }|null}
57
+ */
58
+ function parseRecordPayload(inner) {
59
+ const fields = new Map();
60
+ for (const token of inner.trim().split(/\s+/)) {
61
+ const eq = token.indexOf('=');
62
+ if (eq > 0) fields.set(token.slice(0, eq), token.slice(eq + 1));
63
+ }
64
+ const sha = fields.get('sha') ?? '';
65
+ if (!SHA1_RE.test(sha)) return null;
66
+ const files = (fields.get('files') ?? '')
67
+ .split(',')
68
+ .filter((f) => f.length > 0)
69
+ .map(decodeRecordValue);
70
+ const key = decodeRecordValue(fields.get('key') ?? '');
71
+ const label = fields.has('label')
72
+ ? decodeRecordValue(fields.get('label'))
73
+ : '';
74
+ if (key === null || label === null || files.includes(null)) return null;
75
+ return { sha, key, label: label || null, files };
76
+ }
77
+
78
+ /**
79
+ * Every well-formed `audit-finding` record in `text`, first-seen per sha.
80
+ *
81
+ * @param {unknown} text
82
+ * @returns {Array<{ sha: string, key: string, label: string|null, files: string[] }>}
83
+ */
84
+ export function parseAuditFindingRecords(text) {
85
+ if (typeof text !== 'string') return [];
86
+ const out = [];
87
+ const seen = new Set();
88
+ for (const match of text.matchAll(/<!--\s*audit-finding:([^>]*?)-->/g)) {
89
+ const record = parseRecordPayload(match[1]);
90
+ if (!record || seen.has(record.sha)) continue;
91
+ seen.add(record.sha);
92
+ out.push(record);
93
+ }
94
+ return out;
95
+ }
@@ -192,8 +192,9 @@ function parseAllFooterValues(text, pattern, isValid) {
192
192
 
193
193
  /**
194
194
  * Every provenance footer in `text`, verbatim, one per line — the whole of
195
- * what `carryProvenanceFooters` and `parseAuditLabelFooter` read from a seed,
196
- * small enough to survive a seed that is cut for size.
195
+ * what `carryProvenanceFooters`, `parseAuditLabelFooter` and
196
+ * `parseAuditFindingRecords` (`audit-finding-record.js`) read from a seed, small enough to survive a seed
197
+ * that is cut for size.
197
198
  *
198
199
  * @param {unknown} text
199
200
  * @returns {string}
@@ -201,7 +202,7 @@ function parseAllFooterValues(text, pattern, isValid) {
201
202
  export function extractProvenanceFooters(text) {
202
203
  if (typeof text !== 'string') return '';
203
204
  const pattern =
204
- /<!--\s*audit-(?:fingerprints|semantic-keys|labels):[^>]*-->/g;
205
+ /<!--\s*audit-(?:fingerprints|semantic-keys|labels|finding):[^>]*-->/g;
205
206
  return [...text.matchAll(pattern)].map((m) => m[0]).join('\n');
206
207
  }
207
208