mandrel 2.94.0 → 2.95.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 (110) hide show
  1. package/.agents/runtime-deps.json +6 -6
  2. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  3. package/.agents/scripts/board-backfill.js +1 -1
  4. package/.agents/scripts/boot-sweep.js +1 -1
  5. package/.agents/scripts/check-arch-cycles.js +69 -41
  6. package/.agents/scripts/check-doc-links.js +5 -7
  7. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  8. package/.agents/scripts/clean-temp.js +1 -1
  9. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  10. package/.agents/scripts/diagnose-friction.js +1 -1
  11. package/.agents/scripts/generate-lens-checklists.js +4 -4
  12. package/.agents/scripts/generate-skills-index.js +3 -2
  13. package/.agents/scripts/generate-workflows-doc.js +2 -1
  14. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  15. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  16. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  17. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  18. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  19. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  20. package/.agents/scripts/lib/baselines/components.js +21 -19
  21. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  22. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  23. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  24. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  25. package/.agents/scripts/lib/baselines/writer.js +2 -7
  26. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  27. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  28. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  29. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  30. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  31. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  32. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  33. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  34. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  35. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  36. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  37. package/.agents/scripts/lib/config/defaults.js +2 -1
  38. package/.agents/scripts/lib/config/qa.js +4 -5
  39. package/.agents/scripts/lib/config-schema.js +1 -8
  40. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  41. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  42. package/.agents/scripts/lib/coverage-utils.js +2 -1
  43. package/.agents/scripts/lib/cpu-pool.js +0 -1
  44. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  45. package/.agents/scripts/lib/doc-tiers.js +2 -1
  46. package/.agents/scripts/lib/gh-exec.js +21 -1
  47. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  48. package/.agents/scripts/lib/import-graph.js +13 -28
  49. package/.agents/scripts/lib/json-utils.js +11 -0
  50. package/.agents/scripts/lib/label-constants.js +7 -1
  51. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  52. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  53. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  54. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +9 -12
  55. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  56. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  57. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  58. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  59. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  60. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  63. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  64. package/.agents/scripts/lib/orchestration/merge-block-class.js +47 -48
  65. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  66. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  67. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  68. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  69. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  70. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  71. package/.agents/scripts/lib/orchestration/ticketing/transition.js +17 -21
  72. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  73. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  74. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  75. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  76. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  77. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  78. package/.agents/scripts/lib/util/regex.js +4 -0
  79. package/.agents/scripts/notify.js +1 -1
  80. package/.agents/scripts/plan-context.js +1 -1
  81. package/.agents/scripts/plan-critics.js +3 -11
  82. package/.agents/scripts/providers/github/auth.js +0 -4
  83. package/.agents/scripts/providers/github/project-board.js +0 -1
  84. package/.agents/scripts/providers/github/tickets.js +0 -2
  85. package/.agents/scripts/resync-status-column.js +1 -1
  86. package/.agents/scripts/run-tests.js +1 -1
  87. package/.agents/scripts/test-wrapper.js +1 -1
  88. package/.agents/scripts/update-ticket-state.js +4 -3
  89. package/.agents/scripts/validate-skills.js +2 -1
  90. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  91. package/.agents/workflows/audit-baselines.md +21 -9
  92. package/.agents/workflows/clean-git.md +1 -1
  93. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  94. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  95. package/README.md +1 -1
  96. package/docs/CHANGELOG.md +34 -0
  97. package/lib/cli/claude-code-version.js +13 -7
  98. package/lib/cli/doctor-checks/llm-review.js +12 -5
  99. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  100. package/lib/cli/doctor-checks/project-access.js +21 -8
  101. package/lib/cli/doctor-checks/read-json.js +2 -15
  102. package/lib/cli/doctor-checks/spawn.js +29 -9
  103. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  104. package/lib/cli/doctor-checks/toolchain.js +16 -12
  105. package/lib/cli/doctor.js +31 -8
  106. package/lib/cli/registry.js +7 -10
  107. package/lib/cli/sync.js +46 -10
  108. package/lib/cli/uninstall.js +259 -175
  109. package/lib/cli/update.js +3 -3
  110. package/package.json +23 -20
@@ -145,6 +145,63 @@ function revertClaudeMd(projectRoot, fsImpl) {
145
145
  );
146
146
  }
147
147
 
148
+ /**
149
+ * Delete `obj[parent][child]`, then `obj[parent]` once it is left empty.
150
+ *
151
+ * @param {Record<string, any>} obj
152
+ * @param {string} parent
153
+ * @param {string} child
154
+ * @returns {boolean} whether the child key was present (and so removed).
155
+ */
156
+ function dropNestedKey(obj, parent, child) {
157
+ if (obj[parent]?.[child] === undefined) return false;
158
+ delete obj[parent][child];
159
+ if (Object.keys(obj[parent]).length === 0) delete obj[parent];
160
+ return true;
161
+ }
162
+
163
+ /**
164
+ * @param {unknown} hook
165
+ * @returns {boolean}
166
+ */
167
+ function isFrameworkHook(hook) {
168
+ return (
169
+ typeof hook?.command === 'string' &&
170
+ hook.command.includes('sync-claude-commands.js')
171
+ );
172
+ }
173
+
174
+ /**
175
+ * @param {any} group
176
+ * @returns {boolean}
177
+ */
178
+ function hasSyncHook(group) {
179
+ return Array.isArray(group?.hooks) && group.hooks.some(isFrameworkHook);
180
+ }
181
+
182
+ /**
183
+ * Splice the sync hook out of `settings.hooks.UserPromptSubmit`, dropping
184
+ * emptied groups and an emptied `hooks` object.
185
+ *
186
+ * @param {Record<string, any>} settings
187
+ * @returns {boolean} whether a hook was removed.
188
+ */
189
+ function stripSyncHook(settings) {
190
+ const groups = settings.hooks?.UserPromptSubmit;
191
+ if (!Array.isArray(groups) || !groups.some(hasSyncHook)) return false;
192
+ const kept = groups.flatMap((group) => {
193
+ if (!hasSyncHook(group)) return [group];
194
+ const hooks = group.hooks.filter((h) => !isFrameworkHook(h));
195
+ return hooks.length > 0 ? [{ ...group, hooks }] : [];
196
+ });
197
+ if (kept.length > 0) {
198
+ settings.hooks.UserPromptSubmit = kept;
199
+ } else {
200
+ dropNestedKey(settings, 'hooks', 'UserPromptSubmit');
201
+ }
202
+ return true;
203
+ }
204
+
148
205
  /**
149
206
  * Splice the sync hook and any legacy plugin-enablement keys out of
150
207
  * `.claude/settings.json`, keeping everything else; delete the file if empty.
@@ -160,52 +217,13 @@ function revertClaudeSettings(projectRoot, fsImpl) {
160
217
  return { kind: 'skipped', target: rel, detail: 'file absent' };
161
218
  }
162
219
  const settings = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
163
- const groups = settings?.hooks?.UserPromptSubmit;
164
- const isFrameworkHook = (h) =>
165
- typeof h?.command === 'string' &&
166
- h.command.includes('sync-claude-commands.js');
167
-
168
- let mutated = false;
169
-
170
- if (
171
- settings.enabledPlugins &&
172
- settings.enabledPlugins['mandrel@mandrel'] !== undefined
173
- ) {
174
- delete settings.enabledPlugins['mandrel@mandrel'];
175
- if (Object.keys(settings.enabledPlugins).length === 0) {
176
- delete settings.enabledPlugins;
177
- }
178
- mutated = true;
179
- }
180
- if (settings.extraKnownMarketplaces?.mandrel !== undefined) {
181
- delete settings.extraKnownMarketplaces.mandrel;
182
- if (Object.keys(settings.extraKnownMarketplaces).length === 0) {
183
- delete settings.extraKnownMarketplaces;
184
- }
185
- mutated = true;
186
- }
187
-
188
- if (Array.isArray(groups)) {
189
- const kept = groups
190
- .map((group) => ({
191
- ...group,
192
- hooks: (group?.hooks ?? []).filter((h) => !isFrameworkHook(h)),
193
- }))
194
- .filter((group) => (group.hooks ?? []).length > 0);
195
- if (kept.length !== groups.length) {
196
- if (kept.length === 0) {
197
- delete settings.hooks.UserPromptSubmit;
198
- } else {
199
- settings.hooks.UserPromptSubmit = kept;
200
- }
201
- if (settings.hooks && Object.keys(settings.hooks).length === 0) {
202
- delete settings.hooks;
203
- }
204
- mutated = true;
205
- }
206
- }
207
-
208
- if (!mutated) {
220
+ // Every step runs (no short-circuit): each strips its own wiring.
221
+ const mutations = [
222
+ dropNestedKey(settings, 'enabledPlugins', 'mandrel@mandrel'),
223
+ dropNestedKey(settings, 'extraKnownMarketplaces', 'mandrel'),
224
+ stripSyncHook(settings),
225
+ ];
226
+ if (!mutations.includes(true)) {
209
227
  return { kind: 'skipped', target: rel, detail: 'framework wiring absent' };
210
228
  }
211
229
  if (Object.keys(settings).length === 0) {
@@ -333,6 +351,28 @@ function stripPrepare(prepare) {
333
351
  return { changed: next !== prepare, next };
334
352
  }
335
353
 
354
+ /**
355
+ * Remove the seeded framework scripts (and the framework part of `prepare`)
356
+ * from `scripts` in place.
357
+ *
358
+ * @param {Record<string, unknown>} scripts
359
+ * @returns {string[]} the names of the removed (or rewritten) scripts.
360
+ */
361
+ function stripFrameworkScripts(scripts) {
362
+ const removed = Object.entries(FRAMEWORK_NPM_SCRIPTS)
363
+ .filter(([name, cmd]) => scripts[name] === cmd)
364
+ .map(([name]) => name);
365
+ for (const name of removed) delete scripts[name];
366
+ const prepare = stripPrepare(scripts.prepare);
367
+ if (!prepare.changed) return removed;
368
+ if (prepare.next === '') {
369
+ delete scripts.prepare;
370
+ } else {
371
+ scripts.prepare = prepare.next;
372
+ }
373
+ return [...removed, 'prepare'];
374
+ }
375
+
336
376
  /**
337
377
  * @param {string} projectRoot
338
378
  * @param {typeof fs} fsImpl
@@ -348,22 +388,7 @@ function revertPackageJson(projectRoot, fsImpl) {
348
388
  if (!pkg.scripts || typeof pkg.scripts !== 'object') {
349
389
  return { kind: 'skipped', target: rel, detail: 'no framework scripts' };
350
390
  }
351
- const removed = [];
352
- for (const [name, cmd] of Object.entries(FRAMEWORK_NPM_SCRIPTS)) {
353
- if (pkg.scripts[name] === cmd) {
354
- delete pkg.scripts[name];
355
- removed.push(name);
356
- }
357
- }
358
- const prepare = stripPrepare(pkg.scripts.prepare);
359
- if (prepare.changed) {
360
- if (prepare.next === '') {
361
- delete pkg.scripts.prepare;
362
- } else {
363
- pkg.scripts.prepare = prepare.next;
364
- }
365
- removed.push('prepare');
366
- }
391
+ const removed = stripFrameworkScripts(pkg.scripts);
367
392
  if (removed.length === 0) {
368
393
  return { kind: 'skipped', target: rel, detail: 'no framework scripts' };
369
394
  }
@@ -526,166 +551,225 @@ function formatOutcome(outcome) {
526
551
  }
527
552
 
528
553
  /**
529
- * @param {{
530
- * projectRoot?: string,
531
- * cwd?: () => string,
532
- * fsImpl?: typeof fs,
533
- * write?: (s: string) => void,
534
- * exit?: (code: number) => void,
535
- * includeGithub?: boolean,
536
- * dryRun?: boolean,
537
- * }} [opts]
554
+ * @param {number} revertedCount
555
+ * @param {number} manualCount
556
+ * @param {boolean} ledgerFound
557
+ * @param {number} parseErrorCount
538
558
  * @returns {{ revertedCount: number, manualCount: number, ledgerFound: boolean, parseErrorCount: number }}
539
559
  */
540
- export function runUninstall({
541
- projectRoot,
542
- cwd,
543
- fsImpl = fs,
544
- write = (s) => process.stdout.write(s),
545
- exit = (code) => process.exit(code),
546
- includeGithub = false,
547
- dryRun = false,
548
- } = {}) {
549
- const root = projectRoot ?? resolveProjectRoot(cwd);
560
+ function result(revertedCount, manualCount, ledgerFound, parseErrorCount) {
561
+ return { revertedCount, manualCount, ledgerFound, parseErrorCount };
562
+ }
550
563
 
564
+ /**
565
+ * Read and validate the install ledger. Returns the ledger, or the message
566
+ * and exit code that end the run instead.
567
+ *
568
+ * @param {string} root
569
+ * @returns {{ ledger: object } | { message: string, code: number, ledgerFound: boolean }}
570
+ */
571
+ function loadLedger(root) {
551
572
  let ledger;
552
573
  try {
553
574
  ledger = readInstallLedger(root);
554
575
  } catch (err) {
555
- write(`❌ Install ledger is unreadable: ${err.message}\n`);
556
- exit(1);
557
576
  return {
558
- revertedCount: 0,
559
- manualCount: 0,
577
+ message: `❌ Install ledger is unreadable: ${err.message}\n`,
578
+ code: 1,
560
579
  ledgerFound: false,
561
- parseErrorCount: 0,
562
580
  };
563
581
  }
564
-
565
582
  if (!ledger) {
566
- write('❌ No install ledger found — nothing to uninstall.\n');
567
583
  // Never installed or already uninstalled: a benign no-op.
568
- exit(0);
569
584
  return {
570
- revertedCount: 0,
571
- manualCount: 0,
585
+ message: '❌ No install ledger found — nothing to uninstall.\n',
586
+ code: 0,
572
587
  ledgerFound: false,
573
- parseErrorCount: 0,
574
588
  };
575
589
  }
576
-
577
590
  if (ledger.schemaVersion !== LEDGER_SCHEMA_VERSION) {
578
- write(
579
- `❌ Install ledger schema v${ledger.schemaVersion} is not supported by this mandrel (expected v${LEDGER_SCHEMA_VERSION}). Upgrade/downgrade mandrel to match, then re-run.\n`,
580
- );
581
- exit(1);
582
591
  return {
583
- revertedCount: 0,
584
- manualCount: 0,
592
+ message: `❌ Install ledger schema v${ledger.schemaVersion} is not supported by this mandrel (expected v${LEDGER_SCHEMA_VERSION}). Upgrade/downgrade mandrel to match, then re-run.\n`,
593
+ code: 1,
585
594
  ledgerFound: true,
586
- parseErrorCount: 0,
587
595
  };
588
596
  }
597
+ return { ledger };
598
+ }
589
599
 
590
- const { fileTargets, manual, executedActionByTarget } = planUninstall(ledger);
600
+ /**
601
+ * Never acted on automatically; --include-github only acknowledges them.
602
+ *
603
+ * @param {{ target: string, detail: string }} entry
604
+ * @param {boolean} includeGithub
605
+ * @returns {string}
606
+ */
607
+ function formatManual(entry, includeGithub) {
608
+ const note = includeGithub
609
+ ? `${entry.detail} (acknowledged — reverse manually via the GitHub UI/API)`
610
+ : `${entry.detail} (left untouched — pass --include-github to acknowledge)`;
611
+ return formatOutcome({ kind: 'manual', target: entry.target, detail: note });
612
+ }
591
613
 
592
- if (dryRun) {
593
- write('mandrel uninstall — planned reversal (dry run)\n');
594
- for (const target of fileTargets) {
595
- write(
596
- formatOutcome({
597
- kind: 'reverted',
598
- target,
599
- detail: '(would be reverted)',
600
- }),
601
- );
602
- }
603
- for (const entry of manual) {
604
- const note = includeGithub
605
- ? `${entry.detail} (acknowledged — reverse manually via the GitHub UI/API)`
606
- : `${entry.detail} (left untouched — pass --include-github to acknowledge)`;
607
- write(
608
- formatOutcome({ kind: 'manual', target: entry.target, detail: note }),
609
- );
610
- }
611
- write(
612
- `Dry run: ${fileTargets.length} file target(s) would be reverted, ` +
613
- `${manual.length} manual follow-up(s).\n`,
614
- );
615
- exit(0);
614
+ /**
615
+ * Run one target's reversal. One corrupt operator file must not abort a
616
+ * half-done uninstall: a throw becomes a skipped outcome flagged `failed`.
617
+ *
618
+ * @param {string} target
619
+ * @param {string} root
620
+ * @param {typeof fs} fsImpl
621
+ * @param {string} [executedAction]
622
+ * @returns {{ outcome: ReversalOutcome, failed: boolean }}
623
+ */
624
+ function revertTarget(target, root, fsImpl, executedAction) {
625
+ try {
616
626
  return {
617
- revertedCount: 0,
618
- manualCount: manual.length,
619
- ledgerFound: true,
620
- parseErrorCount: 0,
627
+ outcome: REVERSAL_BY_TARGET[target](root, fsImpl, executedAction),
628
+ failed: false,
621
629
  };
622
- }
623
-
624
- let revertedCount = 0;
625
- let parseErrorCount = 0;
626
- for (const target of fileTargets) {
627
- let outcome;
628
- try {
629
- outcome = REVERSAL_BY_TARGET[target](
630
- root,
631
- fsImpl,
632
- executedActionByTarget[target],
633
- );
634
- } catch (err) {
635
- // One corrupt operator file must not abort a half-done uninstall;
636
- // report it and keep the ledger so a re-run can resume.
637
- outcome = {
630
+ } catch (err) {
631
+ return {
632
+ outcome: {
638
633
  kind: 'skipped',
639
634
  target,
640
635
  detail: `unparseable — revert manually (${err.message})`,
641
- };
642
- parseErrorCount += 1;
643
- }
644
- if (outcome.kind === 'reverted') revertedCount += 1;
645
- write(formatOutcome(outcome));
636
+ },
637
+ failed: true,
638
+ };
646
639
  }
640
+ }
647
641
 
648
- // Never acted on automatically; --include-github only acknowledges them.
649
- let manualCount = 0;
650
- for (const entry of manual) {
651
- manualCount += 1;
652
- const note = includeGithub
653
- ? `${entry.detail} (acknowledged — reverse manually via the GitHub UI/API)`
654
- : `${entry.detail} (left untouched — pass --include-github to acknowledge)`;
655
- write(
656
- formatOutcome({ kind: 'manual', target: entry.target, detail: note }),
657
- );
658
- }
642
+ const LEDGER_TARGET = '.agents/.install-manifest.json';
659
643
 
660
- // Ledger goes last, and stays when any target failed, so a re-run resumes.
644
+ /**
645
+ * The ledger goes last, and stays when any target failed, so a re-run
646
+ * resumes.
647
+ *
648
+ * @param {string} root
649
+ * @param {typeof fs} fsImpl
650
+ * @param {number} parseErrorCount
651
+ * @returns {ReversalOutcome|null} the ledger's outcome, or null when absent.
652
+ */
653
+ function retireLedger(root, fsImpl, parseErrorCount) {
661
654
  const lp = ledgerPath(root);
662
- if (fsImpl.existsSync(lp) && parseErrorCount === 0) {
663
- fsImpl.rmSync(lp, { force: true });
655
+ if (!fsImpl.existsSync(lp)) return null;
656
+ if (parseErrorCount > 0) {
657
+ return {
658
+ kind: 'skipped',
659
+ target: LEDGER_TARGET,
660
+ detail: 'ledger retained — re-run after fixing unparseable file(s)',
661
+ };
662
+ }
663
+ fsImpl.rmSync(lp, { force: true });
664
+ return {
665
+ kind: 'reverted',
666
+ target: LEDGER_TARGET,
667
+ detail: 'removed install ledger',
668
+ };
669
+ }
670
+
671
+ /**
672
+ * @param {{ fileTargets: string[], manual: Array<{ target: string, detail: string }> }} plan
673
+ * @param {boolean} includeGithub
674
+ * @param {(s: string) => void} write
675
+ */
676
+ function printDryRun({ fileTargets, manual }, includeGithub, write) {
677
+ write('mandrel uninstall — planned reversal (dry run)\n');
678
+ for (const target of fileTargets) {
664
679
  write(
665
680
  formatOutcome({
666
681
  kind: 'reverted',
667
- target: '.agents/.install-manifest.json',
668
- detail: 'removed install ledger',
682
+ target,
683
+ detail: '(would be reverted)',
669
684
  }),
670
685
  );
671
- revertedCount += 1;
672
- } else if (parseErrorCount > 0 && fsImpl.existsSync(lp)) {
673
- write(
674
- formatOutcome({
675
- kind: 'skipped',
676
- target: '.agents/.install-manifest.json',
677
- detail: 'ledger retained — re-run after fixing unparseable file(s)',
678
- }),
686
+ }
687
+ for (const entry of manual) write(formatManual(entry, includeGithub));
688
+ write(
689
+ `Dry run: ${fileTargets.length} file target(s) would be reverted, ` +
690
+ `${manual.length} manual follow-up(s).\n`,
691
+ );
692
+ }
693
+
694
+ /**
695
+ * @param {{ fileTargets: string[], manual: Array<{ target: string, detail: string }>, executedActionByTarget: Record<string, string> }} plan
696
+ * @param {{ root: string, fsImpl: typeof fs, write: (s: string) => void, includeGithub: boolean }} ctx
697
+ * @returns {{ revertedCount: number, manualCount: number, parseErrorCount: number }}
698
+ */
699
+ function applyUninstall(plan, { root, fsImpl, write, includeGithub }) {
700
+ let revertedCount = 0;
701
+ let parseErrorCount = 0;
702
+ for (const target of plan.fileTargets) {
703
+ const { outcome, failed } = revertTarget(
704
+ target,
705
+ root,
706
+ fsImpl,
707
+ plan.executedActionByTarget[target],
679
708
  );
709
+ if (failed) parseErrorCount += 1;
710
+ if (outcome.kind === 'reverted') revertedCount += 1;
711
+ write(formatOutcome(outcome));
712
+ }
713
+ for (const entry of plan.manual) write(formatManual(entry, includeGithub));
714
+ const ledgerOutcome = retireLedger(root, fsImpl, parseErrorCount);
715
+ if (ledgerOutcome) {
716
+ if (ledgerOutcome.kind === 'reverted') revertedCount += 1;
717
+ write(formatOutcome(ledgerOutcome));
718
+ }
719
+ return { revertedCount, manualCount: plan.manual.length, parseErrorCount };
720
+ }
721
+
722
+ /**
723
+ * @param {{
724
+ * projectRoot?: string,
725
+ * cwd?: () => string,
726
+ * fsImpl?: typeof fs,
727
+ * write?: (s: string) => void,
728
+ * exit?: (code: number) => void,
729
+ * includeGithub?: boolean,
730
+ * dryRun?: boolean,
731
+ * }} [opts]
732
+ * @returns {{ revertedCount: number, manualCount: number, ledgerFound: boolean, parseErrorCount: number }}
733
+ */
734
+ export function runUninstall({
735
+ projectRoot,
736
+ cwd,
737
+ fsImpl = fs,
738
+ write = (s) => process.stdout.write(s),
739
+ exit = (code) => process.exit(code),
740
+ includeGithub = false,
741
+ dryRun = false,
742
+ } = {}) {
743
+ const root = projectRoot ?? resolveProjectRoot(cwd);
744
+
745
+ const loaded = loadLedger(root);
746
+ if (!loaded.ledger) {
747
+ write(loaded.message);
748
+ exit(loaded.code);
749
+ return result(0, 0, loaded.ledgerFound, 0);
750
+ }
751
+
752
+ const plan = planUninstall(loaded.ledger);
753
+
754
+ if (dryRun) {
755
+ printDryRun(plan, includeGithub, write);
756
+ exit(0);
757
+ return result(0, plan.manual.length, true, 0);
680
758
  }
681
759
 
760
+ const { revertedCount, manualCount, parseErrorCount } = applyUninstall(plan, {
761
+ root,
762
+ fsImpl,
763
+ write,
764
+ includeGithub,
765
+ });
682
766
  write(
683
767
  `✅ Uninstalled (${revertedCount} reversed, ${manualCount} manual follow-up${
684
768
  manualCount === 1 ? '' : 's'
685
769
  })\n`,
686
770
  );
687
771
  exit(0);
688
- return { revertedCount, manualCount, ledgerFound: true, parseErrorCount };
772
+ return result(revertedCount, manualCount, true, parseErrorCount);
689
773
  }
690
774
 
691
775
  /**
package/lib/cli/update.js CHANGED
@@ -552,7 +552,7 @@ export async function fetchChangelogFromGitHub(
552
552
 
553
553
  for (const tag of tags) {
554
554
  const url = `${GITHUB_RAW_BASE}${tag}/docs/CHANGELOG.md`;
555
- // eslint-disable-next-line no-await-in-loop
555
+ // Sequential on purpose: tags are tried newest-first and the first hit wins.
556
556
  const { status, body } = await httpGet(url);
557
557
  if (status >= 200 && status < 300) {
558
558
  return body;
@@ -939,13 +939,13 @@ async function executePlan({
939
939
  'mandrel update: npmUpdate seam is required to bump the dependency',
940
940
  );
941
941
  }
942
- // eslint-disable-next-line no-await-in-loop
942
+ // Steps run in order: each phase depends on the one before it.
943
943
  await npmUpdate(target, { installCmd });
944
944
  stepsRun.push(step.label);
945
945
  continue;
946
946
  }
947
947
 
948
- // eslint-disable-next-line no-await-in-loop
948
+ // Steps run in order: each phase depends on the one before it.
949
949
  const result = await spawnPhase(step.phase, step.args, {
950
950
  binPath: binScript(),
951
951
  cwd: projectRoot,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.94.0",
3
+ "version": "2.95.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",
@@ -47,6 +47,7 @@
47
47
  "maintainability:update": "node .agents/scripts/update-maintainability-baseline.js",
48
48
  "maintainability:reanchor": "node .agents/scripts/update-maintainability-baseline.js --full-scope",
49
49
  "check:arch": "node .agents/scripts/check-arch-cycles.js",
50
+ "arch:update": "node .agents/scripts/check-arch-cycles.js --update",
50
51
  "//resident-context-reports": "check:context-budget and check:workflow-citations are REPORTS, not ratchets (Story #5340, ADR 20260917-5340). check:context-budget still fails when the alwaysLoaded tier exceeds its recorded total plus the committed tolerance; its workflow tier, and check:workflow-citations in full, print and always exit 0. A green run is not evidence the numbers held — read the output.",
51
52
  "check:context-budget": "node .agents/scripts/check-context-budget.js",
52
53
  "check:cyclomatic": "node .agents/scripts/check-cyclomatic.js",
@@ -100,30 +101,30 @@
100
101
  "node": ">=22.22.1 <25"
101
102
  },
102
103
  "devDependencies": {
103
- "@biomejs/biome": "^2.5.0",
104
- "@commitlint/cli": "^21.0.2",
105
- "@commitlint/config-conventional": "^21.0.2",
104
+ "@biomejs/biome": "^2.6.2",
105
+ "@commitlint/cli": "^21.2.4",
106
+ "@commitlint/config-conventional": "^21.2.4",
106
107
  "@cucumber/gherkin": "^42.0.1",
107
- "c8": "^11.0.0",
108
- "chokidar": "^5.0.0",
108
+ "c8": "^12.0.0",
109
+ "chokidar": "^6.0.0",
109
110
  "fast-check": "^4.10.2",
110
111
  "husky": "^9.1.7",
111
- "jscpd": "^4.2.5",
112
- "knip": "^6.17.1",
113
- "lint-staged": "^17.0.7",
114
- "markdownlint-cli2": "^0.22.1",
115
- "memfs": "^4.57.7",
112
+ "jscpd": "^4.3.0",
113
+ "knip": "^6.42.1",
114
+ "lint-staged": "^17.6.0",
115
+ "markdownlint-cli2": "^0.24.0",
116
+ "memfs": "^4.80.0",
116
117
  "node-pty": "^1.0.0",
117
118
  "typescript": "^6.0.3"
118
119
  },
119
120
  "dependencies": {
120
- "@babel/parser": "^7.29.3",
121
+ "@babel/parser": "^7.29.9",
121
122
  "ajv": "^8.20.0",
122
123
  "babel-runtime": "^6.26.0",
123
124
  "escomplex-plugin-metrics-module": "^0.1.0",
124
125
  "escomplex-plugin-syntax-babylon": "^0.1.0",
125
- "js-yaml": "^4.3.2",
126
- "picomatch": "^4.0.4",
126
+ "js-yaml": "^5.4.3",
127
+ "picomatch": "^4.0.7",
127
128
  "typhonjs-ast-walker": "^0.2.1",
128
129
  "typhonjs-escomplex-commons": "^0.1.1"
129
130
  },
@@ -145,14 +146,16 @@
145
146
  },
146
147
  "//": {
147
148
  "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
148
- "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
149
+ "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: an npm override wins over every transitive package's own pin, so this tree-wide ^5.4.3 is imposed on every js-yaml consumer regardless of what they declare. markdownlint-cli2 0.24.x declares an exact js-yaml 5.4.3, which the override matches; cosmiconfig (under @commitlint/cli) declares ^4.1.0 and was confirmed to load commitlint config under js-yaml 5 before this pin moved. Earlier pins existed for advisories against 4.x (GHSA-52cp-r559-cp3m, GHSA-h67p-54hq-rp68, GHSA-2883-xcg3-v3hh); letting any consumer fall back below 4.3.2 reintroduces that history. The shipped .agents/runtime-deps.json resolves from a Mandrel consumer's own root, where their tooling may keep 4.x, so it accepts ^4.3.2 || ^5.4.3 instead of mirroring this pin. js-yaml 5 has no default export, so framework code imports the named `load`. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit, re-checking cosmiconfig; renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. check-pinned-override-notes.js fails the build if this sentence and the pin disagree.",
149
150
  "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
150
- "overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT markdown-it 14.1.1, which carries GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths block the event loop). The advisory’s vulnerable range is everything < 14.3.1, so this tree-wide ^14.3.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.23.3, a breaking bump coupled to the js-yaml major above; do not take it. `npm run lint` is what must be re-run if this pin moves.",
151
- "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
151
+ "overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.24.x declares an EXACT markdown-it 15.0.3, and this tree-wide ^15.0.3 pin keeps every markdown-it consumer on that patched major. The 14.x line carried GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths) and GHSA-gfr2-rv44-r23c (high — quadratic-time rendering of a multi-line link reference definition, vulnerable >=14.1.0 <14.3.3); the pin's floor tracks markdownlint-cli2's own declaration so the two never split. `npm run lint` is what must be re-run if this pin moves.",
152
+ "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.24.x declares an EXACT smol-toml 1.9.1, and this tree-wide ^1.9.1 pin keeps every smol-toml consumer at or above it. Older lines carried GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML, vulnerable <= 1.7.0) and GHSA-r4xh-jqrq-34v2 (moderate — quadratic-time parse(), vulnerable <= 1.8.0). knip declares ^1.6.1 and is satisfied natively. `npm run lint` is what must be re-run if this pin moves. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync.",
153
+ "overrides.katex": "Clears GHSA-238p-pmpm-9mq7 (low — prototype pollution bypassing trust restrictions, vulnerable >=0.11.0 <0.18.2). katex reaches the tree only through markdownlint (micromark-extension-math declares ^0.16.0, so no lockfile-only resolution reaches the fix). markdownlint imports only the math SYNTAX extension, never the HTML renderer that loads katex, so this tree-wide ^0.18.2 pin changes no executed code; `npm run lint` is what must be re-run if it moves. katex is NOT a direct dependency, so there is no lockstep duplicate range."
152
154
  },
153
155
  "overrides": {
154
- "js-yaml": "^4.3.2",
155
- "markdown-it": "^14.3.1",
156
- "smol-toml": "^1.7.1"
156
+ "js-yaml": "^5.4.3",
157
+ "markdown-it": "^15.0.3",
158
+ "smol-toml": "^1.9.1",
159
+ "katex": "^0.18.2"
157
160
  }
158
161
  }