mandrel 2.79.0 → 2.81.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 (55) hide show
  1. package/.agents/agents/auditor.md +8 -3
  2. package/.agents/audit-checklists/data-model.md +9 -1
  3. package/.agents/audit-checklists/security.md +15 -1
  4. package/.agents/docs/agentrc-reference.json +4 -0
  5. package/.agents/docs/configuration.md +4 -3
  6. package/.agents/docs/execution-reference.md +25 -5
  7. package/.agents/docs/workflows.md +2 -2
  8. package/.agents/schemas/agentrc.schema.json +31 -3
  9. package/.agents/schemas/audit-rules.json +15 -2
  10. package/.agents/scripts/deliver-run.js +43 -8
  11. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  12. package/.agents/scripts/lib/baselines/duplication-scanner.js +7 -1
  13. package/.agents/scripts/lib/baselines/refresh-service.js +6 -0
  14. package/.agents/scripts/lib/cli-args.js +16 -2
  15. package/.agents/scripts/lib/config/explain.js +1 -1
  16. package/.agents/scripts/lib/config/gates/duplication.schema.js +10 -2
  17. package/.agents/scripts/lib/config-settings-schema.js +18 -1
  18. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  19. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  20. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  21. package/.agents/scripts/lib/observability/close-telemetry.js +17 -2
  22. package/.agents/scripts/lib/orchestration/complexity-gate.js +58 -11
  23. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  24. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  25. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  26. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +56 -9
  27. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +177 -0
  28. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +202 -57
  29. package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js +57 -15
  30. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  31. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  32. package/.agents/scripts/lib/orchestration/resolve-stories.js +12 -3
  33. package/.agents/scripts/lib/orchestration/resume-effort.js +121 -0
  34. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +13 -2
  35. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +10 -2
  36. package/.agents/scripts/lib/orchestration/ticketing/reads.js +3 -0
  37. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  38. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  39. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  40. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  41. package/.agents/scripts/plan-persist.js +20 -6
  42. package/.agents/scripts/providers/github/tickets.js +2 -1
  43. package/.agents/scripts/resolve-stories.js +8 -2
  44. package/.agents/scripts/single-story-close.js +11 -3
  45. package/.agents/workflows/audit-data-model.md +94 -10
  46. package/.agents/workflows/audit-security.md +136 -49
  47. package/.agents/workflows/audit-to-stories.md +22 -7
  48. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  49. package/.agents/workflows/helpers/deliver-reference.md +7 -2
  50. package/.agents/workflows/helpers/deliver-story.md +5 -3
  51. package/.agents/workflows/helpers/plan-reference.md +53 -5
  52. package/.agents/workflows/mandrel-deliver.md +9 -4
  53. package/.agents/workflows/mandrel-plan.md +7 -1
  54. package/docs/CHANGELOG.md +25 -0
  55. package/package.json +2 -1
@@ -467,15 +467,31 @@ const QA_PERSONAS_SCHEMA = {
467
467
  ],
468
468
  };
469
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
+
470
485
  const QA_ENVIRONMENTS_SCHEMA = {
471
486
  type: 'object',
472
487
  description:
473
- '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`.",
474
489
  // Illustrative; `staging` omits `signInSeam` to show it is optional.
475
490
  default: {
476
491
  local: {
477
492
  baseUrl: 'http://localhost:3000',
478
493
  signInSeam: { urlTemplate: '/dev/sign-in-as/{persona}' },
494
+ database: { urlEnv: 'DATABASE_URL' },
479
495
  },
480
496
  staging: {
481
497
  baseUrl: 'https://staging.example.test',
@@ -489,6 +505,7 @@ const QA_ENVIRONMENTS_SCHEMA = {
489
505
  baseUrl: { ...SAFE_STRING, minLength: 1 },
490
506
  signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
491
507
  allowWrites: { type: 'boolean' },
508
+ database: QA_DATABASE_SCHEMA,
492
509
  },
493
510
  // No seam is a state QA workflows handle (unauthenticated drive).
494
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