mandrel 2.86.0 → 2.88.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 (165) hide show
  1. package/.agents/README.md +29 -0
  2. package/.agents/agents/auditor.md +4 -3
  3. package/.agents/docs/agentrc-reference.json +2 -1
  4. package/.agents/docs/configuration.md +44 -20
  5. package/.agents/docs/workflows.md +1 -1
  6. package/.agents/schemas/agentrc.schema.json +18 -12
  7. package/.agents/schemas/story-deliver-terminal.schema.json +1 -1
  8. package/.agents/schemas/story-progress.schema.json +5 -0
  9. package/.agents/scripts/audit-to-stories.js +3 -2
  10. package/.agents/scripts/boot-sweep.js +3 -2
  11. package/.agents/scripts/check-arch-cycles.js +19 -41
  12. package/.agents/scripts/check-context-budget.js +16 -44
  13. package/.agents/scripts/check-cyclomatic.js +13 -37
  14. package/.agents/scripts/check-dead-exports.js +16 -46
  15. package/.agents/scripts/clean-worktrees.js +1 -6
  16. package/.agents/scripts/coverage-capture.js +23 -3
  17. package/.agents/scripts/deliver-run.js +11 -0
  18. package/.agents/scripts/diagnose-friction.js +3 -3
  19. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +115 -0
  20. package/.agents/scripts/lib/baselines/coverage-updater-cli.js +122 -29
  21. package/.agents/scripts/lib/baselines/crap-updater-cli.js +45 -14
  22. package/.agents/scripts/lib/baselines/duplication-scanner.js +45 -2
  23. package/.agents/scripts/lib/baselines/env-overrides.js +39 -34
  24. package/.agents/scripts/lib/baselines/kernel.js +3 -2
  25. package/.agents/scripts/lib/baselines/kinds/crap.js +14 -38
  26. package/.agents/scripts/lib/baselines/preview-gates.js +4 -1
  27. package/.agents/scripts/lib/baselines/refresh-service.js +101 -22
  28. package/.agents/scripts/lib/baselines/writer.js +5 -1
  29. package/.agents/scripts/lib/bdd-runner-detect.js +7 -10
  30. package/.agents/scripts/lib/child-exec.js +14 -1
  31. package/.agents/scripts/lib/child-stream.js +122 -0
  32. package/.agents/scripts/lib/clean-temp.js +19 -13
  33. package/.agents/scripts/lib/cli-args.js +49 -0
  34. package/.agents/scripts/lib/codex/skills-projection.js +1 -12
  35. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  36. package/.agents/scripts/lib/config/gates/mutation.schema.js +2 -2
  37. package/.agents/scripts/lib/config/gates/shared.js +1 -1
  38. package/.agents/scripts/lib/config/gh-config-dir.js +63 -0
  39. package/.agents/scripts/lib/config/github.js +2 -0
  40. package/.agents/scripts/lib/config/paths.js +14 -3
  41. package/.agents/scripts/lib/config/quality.js +6 -2
  42. package/.agents/scripts/lib/config-resolver.js +78 -64
  43. package/.agents/scripts/lib/config-settings-schema-delivery.js +4 -3
  44. package/.agents/scripts/lib/config-settings-schema.js +7 -0
  45. package/.agents/scripts/lib/coverage-baseline.js +7 -6
  46. package/.agents/scripts/lib/coverage-capture.js +59 -0
  47. package/.agents/scripts/lib/crap-utils.js +59 -47
  48. package/.agents/scripts/lib/full-suite-lock.js +1 -10
  49. package/.agents/scripts/lib/gates/baseline-store.js +10 -0
  50. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  51. package/.agents/scripts/lib/gh-exec.js +45 -2
  52. package/.agents/scripts/lib/gh-transport.js +27 -0
  53. package/.agents/scripts/lib/git-utils.js +16 -9
  54. package/.agents/scripts/lib/maintainability-engine.js +27 -6
  55. package/.agents/scripts/lib/maintainability-utils.js +14 -1
  56. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  57. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +33 -3
  58. package/.agents/scripts/lib/orchestration/evidence-stream.js +186 -0
  59. package/.agents/scripts/lib/orchestration/file-assumptions.js +2 -19
  60. package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-reap.js +3 -7
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +34 -40
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +4 -3
  63. package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js +2 -19
  64. package/.agents/scripts/lib/orchestration/pr-watch.js +1 -5
  65. package/.agents/scripts/lib/orchestration/project-meta-cache.js +17 -4
  66. package/.agents/scripts/lib/orchestration/reassert-status-column.js +1 -8
  67. package/.agents/scripts/lib/orchestration/resolve-stories.js +1 -0
  68. package/.agents/scripts/lib/orchestration/review-providers/native.js +2 -2
  69. package/.agents/scripts/lib/orchestration/single-story-close/phase-timer.js +43 -0
  70. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +37 -13
  71. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +264 -0
  72. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +68 -0
  73. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +106 -0
  74. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +43 -35
  75. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +52 -0
  76. package/.agents/scripts/lib/orchestration/single-story-close/result.js +273 -0
  77. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +68 -776
  78. package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js +20 -9
  79. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +2 -2
  80. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +20 -12
  81. package/.agents/scripts/lib/orchestration/story-handoff.js +50 -21
  82. package/.agents/scripts/lib/orchestration/story-progress.js +32 -12
  83. package/.agents/scripts/lib/orchestration/ticket-validator.js +3 -13
  84. package/.agents/scripts/lib/qa/resolve-selection.js +1 -8
  85. package/.agents/scripts/lib/single-story/confirm-and-land.js +33 -0
  86. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +43 -11
  87. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +130 -30
  88. package/.agents/scripts/lib/skills/parse-skill.js +1 -4
  89. package/.agents/scripts/lib/story-body/story-body.js +12 -1
  90. package/.agents/scripts/lib/suite-admission.js +3 -11
  91. package/.agents/scripts/lib/temp-retention.js +25 -11
  92. package/.agents/scripts/lib/test-run-credit.js +2 -5
  93. package/.agents/scripts/lib/transpile.js +193 -31
  94. package/.agents/scripts/lib/util/paths.js +31 -0
  95. package/.agents/scripts/lib/util/sleep.js +15 -0
  96. package/.agents/scripts/lib/validation-evidence.js +29 -3
  97. package/.agents/scripts/lib/wave-runner/live-probe.js +24 -0
  98. package/.agents/scripts/lib/workers/crap-worker.js +23 -12
  99. package/.agents/scripts/lib/workers/maintainability-report-worker.js +18 -12
  100. package/.agents/scripts/lib/workflow-closure.js +1 -8
  101. package/.agents/scripts/notify.js +83 -90
  102. package/.agents/scripts/plan-context.js +8 -4
  103. package/.agents/scripts/providers/github/auth.js +14 -30
  104. package/.agents/scripts/providers/github/blocked-by-add.js +11 -27
  105. package/.agents/scripts/providers/github/compose.js +1 -0
  106. package/.agents/scripts/providers/github/gh-token-diagnostics.js +130 -0
  107. package/.agents/scripts/providers/github/identity.js +158 -0
  108. package/.agents/scripts/providers/github/issues.js +2 -2
  109. package/.agents/scripts/providers/github/mappers.js +16 -19
  110. package/.agents/scripts/providers/github/projects-v2-graphql.js +4 -36
  111. package/.agents/scripts/providers/github/request-helpers.js +44 -0
  112. package/.agents/scripts/providers/github/sub-issue-add.js +11 -28
  113. package/.agents/scripts/providers/github.js +10 -2
  114. package/.agents/scripts/quality-preview.js +6 -19
  115. package/.agents/scripts/single-story-confirm-merge.js +8 -20
  116. package/.agents/scripts/single-story-init.js +0 -1
  117. package/.agents/scripts/stories-wave-tick.js +60 -46
  118. package/.agents/scripts/story-handoff.js +2 -23
  119. package/.agents/scripts/story-review-compute.js +3 -22
  120. package/.agents/scripts/sync-claude-agents.js +1 -12
  121. package/.agents/scripts/sync-claude-commands.js +1 -12
  122. package/.agents/scripts/update-bundle-size-baseline.js +56 -0
  123. package/.agents/scripts/update-coverage-baseline.js +16 -41
  124. package/.agents/scripts/update-crap-baseline.js +10 -19
  125. package/.agents/scripts/update-duplication-baseline.js +13 -3
  126. package/.agents/scripts/update-ticket-state.js +44 -45
  127. package/.agents/templates/docs/audit-sweep-runbook.md +1 -1
  128. package/.agents/workflows/audit-accessibility.md +1 -1
  129. package/.agents/workflows/audit-adrs.md +1 -1
  130. package/.agents/workflows/audit-architecture.md +1 -1
  131. package/.agents/workflows/audit-baselines.md +2 -2
  132. package/.agents/workflows/audit-clean-code.md +1 -1
  133. package/.agents/workflows/audit-data-model.md +1 -1
  134. package/.agents/workflows/audit-dependencies.md +1 -1
  135. package/.agents/workflows/audit-devops.md +1 -1
  136. package/.agents/workflows/audit-documentation.md +1 -1
  137. package/.agents/workflows/audit-exceptions.md +2 -2
  138. package/.agents/workflows/audit-mobile.md +1 -1
  139. package/.agents/workflows/audit-navigability.md +1 -1
  140. package/.agents/workflows/audit-performance.md +1 -1
  141. package/.agents/workflows/audit-privacy.md +1 -1
  142. package/.agents/workflows/audit-quality.md +1 -1
  143. package/.agents/workflows/audit-security.md +1 -1
  144. package/.agents/workflows/audit-seo.md +1 -1
  145. package/.agents/workflows/audit-sre.md +1 -1
  146. package/.agents/workflows/audit-to-stories.md +9 -7
  147. package/.agents/workflows/audit-ux-ui.md +1 -1
  148. package/.agents/workflows/helpers/audit-lens-core.md +8 -5
  149. package/.agents/workflows/helpers/deliver-digest.md +4 -5
  150. package/.agents/workflows/helpers/deliver-story-reference.md +4 -4
  151. package/.agents/workflows/mandrel-deliver.md +3 -1
  152. package/README.md +6 -3
  153. package/docs/CHANGELOG.md +36 -0
  154. package/lib/cli/doctor-checks/codex.js +240 -0
  155. package/lib/cli/doctor-checks/merge-driver.js +79 -0
  156. package/lib/cli/doctor-checks/payload.js +201 -0
  157. package/lib/cli/doctor-checks/read-json.js +16 -0
  158. package/lib/cli/doctor-checks/runtime-deps.js +146 -0
  159. package/lib/cli/doctor-checks/spawn.js +18 -0
  160. package/lib/cli/doctor-checks/sync-parity.js +205 -0
  161. package/lib/cli/doctor-checks/test-credit-path.js +270 -0
  162. package/lib/cli/doctor-checks/toolchain.js +137 -0
  163. package/lib/cli/doctor-checks/version-current.js +82 -0
  164. package/lib/cli/registry.js +40 -1330
  165. package/package.json +7 -1
@@ -0,0 +1,201 @@
1
+ // lib/cli/doctor-checks/payload.js — Doctor checks: agents-drift, pin-current.
2
+
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import {
6
+ defaultResolvePackageRoot,
7
+ listFiles as listPayloadFiles,
8
+ } from '../sync.js';
9
+ import {
10
+ compareVersions as compareSemver,
11
+ resolveConsumerPinSpec,
12
+ satisfiesPinSpec,
13
+ } from '../version-helpers.js';
14
+
15
+ // check: agents-drift
16
+
17
+ /**
18
+ * A size mismatch proves drift without reading contents; equal sizes fall
19
+ * through to a byte compare. `statSync` is optional on the seam.
20
+ *
21
+ * @param {string} src - absolute path to the package-payload file
22
+ * @param {string} dest - absolute path to the materialized file
23
+ * @param {{ readFileSync: Function, statSync?: Function }} fsImpl
24
+ * @returns {boolean} `true` when the files differ
25
+ */
26
+ function payloadFileDrifted(src, dest, fsImpl) {
27
+ if (
28
+ typeof fsImpl.statSync === 'function' &&
29
+ fsImpl.statSync(src).size !== fsImpl.statSync(dest).size
30
+ ) {
31
+ return true;
32
+ }
33
+ return !fsImpl.readFileSync(src).equals(fsImpl.readFileSync(dest));
34
+ }
35
+
36
+ /**
37
+ * Compare materialized `./.agents/` bytes to the installed package payload
38
+ * (excluding `.agents/local/`) and report the first missing or drifted file.
39
+ * Only paths and counts are reported, never contents.
40
+ *
41
+ * @param {{
42
+ * cwd?: () => string,
43
+ * fsImpl?: { existsSync: (p: string) => boolean, readdirSync: Function, readFileSync: Function, statSync?: Function },
44
+ * resolvePackageRoot?: (fromDir: string) => string,
45
+ * }} [opts]
46
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
47
+ */
48
+ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
49
+ const getCwd = cwd ?? (() => process.cwd());
50
+ const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
51
+ const projectRoot = getCwd();
52
+
53
+ let packageRoot;
54
+ try {
55
+ packageRoot = resolveRoot(projectRoot);
56
+ } catch {
57
+ // agents-materialized owns the "not installed" remedy.
58
+ return {
59
+ ok: true,
60
+ detail: 'mandrel not installed — drift skipped',
61
+ };
62
+ }
63
+
64
+ const sourceRoot = path.join(packageRoot, '.agents');
65
+ if (!fsImpl.existsSync(sourceRoot)) {
66
+ return {
67
+ ok: true,
68
+ detail: 'mandrel ships no .agents/ payload — drift skipped',
69
+ };
70
+ }
71
+
72
+ const destRoot = path.join(projectRoot, '.agents');
73
+ if (!fsImpl.existsSync(destRoot)) {
74
+ return { ok: true, detail: './.agents/ not materialized — drift skipped' };
75
+ }
76
+
77
+ const files = listPayloadFiles(sourceRoot, fsImpl);
78
+ let comparedCount = 0;
79
+ let missingCount = 0;
80
+
81
+ for (const rel of files) {
82
+ const src = path.join(sourceRoot, rel);
83
+ const dest = path.join(destRoot, rel);
84
+ const relLabel = path.join('.agents', rel);
85
+
86
+ if (!fsImpl.existsSync(dest)) {
87
+ missingCount += 1;
88
+ return {
89
+ ok: false,
90
+ detail: `${relLabel} is missing from ./.agents/ (${missingCount} of ${files.length} payload files checked so far)`,
91
+ remedy:
92
+ 'Run `mandrel sync` to restore the materialized .agents/ payload.',
93
+ };
94
+ }
95
+
96
+ comparedCount += 1;
97
+ if (payloadFileDrifted(src, dest, fsImpl)) {
98
+ return {
99
+ ok: false,
100
+ detail: `${relLabel} differs from the installed package payload`,
101
+ remedy:
102
+ 'Run `mandrel sync` to overwrite local edits, or move intentional changes into the `.agents/local/` zone.',
103
+ };
104
+ }
105
+ }
106
+
107
+ return {
108
+ ok: true,
109
+ detail: `${comparedCount} materialized file(s) match the package payload`,
110
+ };
111
+ }
112
+
113
+ // check: pin-current
114
+
115
+ /**
116
+ * Fatal: does the installed `mandrel` satisfy the consumer's declared range?
117
+ * Distinct from `agents-drift` (file contents) and `version-current` (newer
118
+ * published). Graded by range satisfaction, not identity, because `^2.1.0` +
119
+ * 2.4.0 after `npm update` is the normal steady state:
120
+ * - satisfies and equals the base → pass;
121
+ * - satisfies but newer than the base → pass, advisory in `detail`;
122
+ * - behind the base → fail (distinct message);
123
+ * - otherwise outside the range → fail.
124
+ * No resolvable semver pin (absent, `workspace:`, `git+`, `latest`, …) skips.
125
+ *
126
+ * @param {{
127
+ * cwd?: () => string,
128
+ * fsImpl?: typeof fs,
129
+ * resolvePackageRoot?: (fromDir: string) => string,
130
+ * }} [opts]
131
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
132
+ */
133
+ export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
134
+ const getCwd = cwd ?? (() => process.cwd());
135
+ const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
136
+ const projectRoot = getCwd();
137
+
138
+ const spec = resolveConsumerPinSpec(projectRoot, fsImpl);
139
+ if (!spec) {
140
+ return {
141
+ ok: true,
142
+ detail: 'no resolvable mandrel dependency pin — skipped',
143
+ };
144
+ }
145
+
146
+ let installedRoot;
147
+ try {
148
+ installedRoot = resolveRoot(projectRoot);
149
+ } catch {
150
+ return {
151
+ ok: true,
152
+ detail: 'mandrel not installed — pin check skipped',
153
+ };
154
+ }
155
+
156
+ let installed;
157
+ try {
158
+ const parsed = JSON.parse(
159
+ fsImpl.readFileSync(path.join(installedRoot, 'package.json'), 'utf8'),
160
+ );
161
+ installed = String(parsed.version);
162
+ } catch {
163
+ return {
164
+ ok: true,
165
+ detail: 'installed version unreadable — pin check skipped',
166
+ };
167
+ }
168
+
169
+ const declared = `${spec.operator}${spec.version}`;
170
+
171
+ if (compareSemver(installed, spec.version) < 0) {
172
+ return {
173
+ ok: false,
174
+ detail: `package.json pins ${declared} but an older v${installed} is installed`,
175
+ remedy:
176
+ 'Run `npm install` to install a version satisfying the package.json pin.',
177
+ };
178
+ }
179
+
180
+ if (!satisfiesPinSpec(installed, spec)) {
181
+ return {
182
+ ok: false,
183
+ detail: `package.json pins ${declared} but v${installed} is installed — outside the declared range`,
184
+ remedy:
185
+ 'Run `mandrel update` to reconcile the package.json pin with the installed version.',
186
+ };
187
+ }
188
+
189
+ if (compareSemver(installed, spec.version) > 0) {
190
+ // The doctor prints only `detail` for a pass, so the advisory rides there.
191
+ return {
192
+ ok: true,
193
+ detail: `v${installed} satisfies the ${declared} pin but is newer than it — run \`mandrel update\` to re-pin (advisory)`,
194
+ };
195
+ }
196
+
197
+ return {
198
+ ok: true,
199
+ detail: `pin ${declared} matches the installed version`,
200
+ };
201
+ }
@@ -0,0 +1,16 @@
1
+ // lib/cli/doctor-checks/read-json.js — shared JSON read for the doctor checks.
2
+
3
+ /**
4
+ * Raw JSON read; any failure degrades to `null`.
5
+ *
6
+ * @param {string} absPath
7
+ * @param {{ readFileSync: Function }} fsImpl
8
+ * @returns {object | null}
9
+ */
10
+ export function readJsonSafe(absPath, fsImpl) {
11
+ try {
12
+ return JSON.parse(fsImpl.readFileSync(absPath, 'utf8'));
13
+ } catch {
14
+ return null;
15
+ }
16
+ }
@@ -0,0 +1,146 @@
1
+ // lib/cli/doctor-checks/runtime-deps.js — Doctor checks: runtime-deps, agents-materialized.
2
+
3
+ import fs from 'node:fs';
4
+ import { createRequire } from 'node:module';
5
+ import path from 'node:path';
6
+ import { isResolvable } from '../../../.agents/scripts/lib/runtime-deps/dep-resolution.js';
7
+ import { describeParserMajorError } from '../../../.agents/scripts/lib/runtime-deps/parser-major.js';
8
+
9
+ // check: runtime-deps
10
+
11
+ /**
12
+ * Presence is not enough: a declared range cannot pin which `@babel/parser`
13
+ * major the consumer's node_modules supplies, and the wrong one fails
14
+ * scoring mid-scan with an opaque error — so report it here.
15
+ *
16
+ * @param {() => string|null} parserMajorError
17
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
18
+ */
19
+ function allPresentVerdict(parserMajorError) {
20
+ const parserProblem = parserMajorError();
21
+ if (parserProblem === null) {
22
+ return { ok: true, detail: 'all dependencies found' };
23
+ }
24
+ return {
25
+ ok: false,
26
+ detail: 'dependency version unsupported',
27
+ remedy: parserProblem,
28
+ };
29
+ }
30
+
31
+ /**
32
+ * Are the runtime deps resolvable from the consumer root? Anchored at
33
+ * `process.cwd()`, not the package root: under pnpm isolated mode the
34
+ * consumer's node_modules are invisible from `node_modules/mandrel/`.
35
+ *
36
+ * @param {{ projectRoot?: string, resolve?: (dep: string) => string, manifestRequired?: string[] }} [opts]
37
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
38
+ */
39
+ export function runRuntimeDeps({
40
+ projectRoot,
41
+ resolve: resolveSeam,
42
+ manifestRequired,
43
+ parserMajorError = describeParserMajorError,
44
+ } = {}) {
45
+ const root = projectRoot ?? process.cwd();
46
+
47
+ let required = manifestRequired;
48
+ if (!required) {
49
+ try {
50
+ const manifestPath = path.join(root, '.agents', 'runtime-deps.json');
51
+ const raw = fs.readFileSync(manifestPath, 'utf8');
52
+ const parsed = JSON.parse(raw);
53
+ required = Object.keys(parsed.dependencies ?? {});
54
+ } catch {
55
+ required = [];
56
+ }
57
+ }
58
+
59
+ if (required.length === 0) {
60
+ return { ok: true, detail: 'all dependencies found' };
61
+ }
62
+
63
+ const missing = [];
64
+
65
+ // `isResolvable` also probes `<name>/package.json`: a dep with no `main`
66
+ // and no `exports` cannot be resolved by bare name yet is installed.
67
+ const resolve =
68
+ resolveSeam ?? createRequire(path.join(root, 'package.json')).resolve;
69
+ for (const dep of required) {
70
+ if (!isResolvable(dep, resolve)) missing.push(dep);
71
+ }
72
+
73
+ if (missing.length === 0) return allPresentVerdict(parserMajorError);
74
+ return {
75
+ ok: false,
76
+ detail: `missing: ${missing.join(', ')}`,
77
+ remedy:
78
+ 'The framework runtime deps are not resolvable from the consumer root, ' +
79
+ 'where the materialized .agents/scripts/*.js run. npm and yarn hoist ' +
80
+ "them automatically — run the installer if you haven't. pnpm's default " +
81
+ 'isolated layout does NOT hoist transitive deps to the top level: add ' +
82
+ '`shamefully-hoist=true` (or a scoped `public-hoist-pattern[]` for ' +
83
+ 'each dep) to your `.npmrc` and reinstall. ' +
84
+ `Missing: ${missing.join(', ')}`,
85
+ };
86
+ }
87
+
88
+ // check: agents-materialized
89
+
90
+ /**
91
+ * Is `./.agents/instructions.md` present? Absent with the package installed
92
+ * means postinstall was skipped (`--ignore-scripts`, sandboxed CI). Both
93
+ * lookups anchor at the consumer's cwd.
94
+ *
95
+ * @param {{
96
+ * cwd?: () => string,
97
+ * existsSync?: (p: string) => boolean,
98
+ * resolvePackage?: (fromDir: string) => string,
99
+ * }} [opts]
100
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
101
+ */
102
+ export function runAgentsMaterialized({
103
+ cwd,
104
+ existsSync,
105
+ resolvePackage,
106
+ } = {}) {
107
+ const getCwd = cwd ?? (() => process.cwd());
108
+ const exists = existsSync ?? ((p) => fs.existsSync(p));
109
+ const root = getCwd();
110
+ const instructionsPath = path.join(root, '.agents', 'instructions.md');
111
+
112
+ if (exists(instructionsPath)) {
113
+ return { ok: true, detail: '.agents/ materialized' };
114
+ }
115
+
116
+ const resolvePkg =
117
+ resolvePackage ??
118
+ ((fromDir) => {
119
+ const requireFrom = createRequire(path.join(fromDir, 'noop.js'));
120
+ return requireFrom.resolve('mandrel/package.json');
121
+ });
122
+
123
+ let packageInstalled = false;
124
+ try {
125
+ resolvePkg(root);
126
+ packageInstalled = true;
127
+ } catch {
128
+ packageInstalled = false;
129
+ }
130
+
131
+ if (packageInstalled) {
132
+ return {
133
+ ok: false,
134
+ detail: 'mandrel installed but ./.agents/ not materialized',
135
+ remedy:
136
+ 'Run `mandrel sync` to materialize the .agents/ payload (postinstall was skipped).',
137
+ };
138
+ }
139
+
140
+ return {
141
+ ok: false,
142
+ detail: 'mandrel not installed and ./.agents/ absent',
143
+ remedy:
144
+ 'Install the framework (`npm install mandrel`), then run `mandrel sync`.',
145
+ };
146
+ }
@@ -0,0 +1,18 @@
1
+ // lib/cli/doctor-checks/spawn.js — Shared `spawnSync` wrapper for the doctor checks.
2
+
3
+ import { spawnSync } from 'node:child_process';
4
+
5
+ /**
6
+ * @param {string} cmd
7
+ * @param {string[]} args
8
+ * @returns {{ status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }}
9
+ */
10
+ export function spawn(cmd, args, opts = {}) {
11
+ const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
12
+ return {
13
+ status: r.status,
14
+ stdout: typeof r.stdout === 'string' ? r.stdout : '',
15
+ stderr: typeof r.stderr === 'string' ? r.stderr : '',
16
+ error: r.error,
17
+ };
18
+ }
@@ -0,0 +1,205 @@
1
+ // lib/cli/doctor-checks/sync-parity.js — Doctor checks: commands-in-sync, agents-in-sync.
2
+
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { isCommandExcluded } from '../../../.agents/scripts/lib/command-header.js';
6
+ import { getDeliveryRouting } from '../../../.agents/scripts/lib/config/delivery-routing.js';
7
+ import { readJsonSafe } from './read-json.js';
8
+
9
+ // check: commands-in-sync
10
+
11
+ /**
12
+ * Parity of `.claude/commands/*.md` against the union of `.agents/workflows/`
13
+ * and `.agents/local/workflows/`. A basename is expected iff at least one
14
+ * source copy is not `command: false`, mirroring the sync script's
15
+ * payload-wins shadowing; an unreadable source counts as projected.
16
+ *
17
+ * The root defaults to `process.cwd()`, never `resolveProjectRoot()` — that
18
+ * lands on `node_modules/mandrel/` in an installed consumer, where the
19
+ * command tree never exists, producing a permanent false "not synced".
20
+ *
21
+ * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[], readFile?: (file: string) => string | null }} [opts]
22
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
23
+ */
24
+ export function runCommandsInSync({
25
+ projectRoot,
26
+ cwd,
27
+ readDir,
28
+ readFile,
29
+ } = {}) {
30
+ const getCwd = cwd ?? (() => process.cwd());
31
+ const root = projectRoot ?? getCwd();
32
+ const listDir =
33
+ readDir ??
34
+ ((dir) => {
35
+ try {
36
+ return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
37
+ } catch {
38
+ return [];
39
+ }
40
+ });
41
+ const readSource =
42
+ readFile ??
43
+ ((file) => {
44
+ try {
45
+ return fs.readFileSync(file, 'utf8');
46
+ } catch {
47
+ return null;
48
+ }
49
+ });
50
+
51
+ const srcDirs = [
52
+ path.join(root, '.agents', 'workflows'),
53
+ path.join(root, '.agents', 'local', 'workflows'),
54
+ ];
55
+ const destDir = path.join(root, '.claude', 'commands');
56
+
57
+ // Top-level .md only (helpers/ are included modules, not commands).
58
+ const expected = new Set();
59
+ for (const srcDir of srcDirs) {
60
+ for (const f of listDir(srcDir)) {
61
+ if (f.startsWith('.')) continue;
62
+ const content = readSource(path.join(srcDir, f));
63
+ if (content != null && isCommandExcluded(content)) continue;
64
+ expected.add(f);
65
+ }
66
+ }
67
+ const sources = [...expected].sort();
68
+ const dests = listDir(destDir)
69
+ .filter((f) => !f.startsWith('.'))
70
+ .sort();
71
+
72
+ const dstSet = new Set(dests);
73
+ const missing = sources.filter((f) => !dstSet.has(f));
74
+ const extra = dests.filter((f) => !expected.has(f));
75
+
76
+ if (missing.length === 0 && extra.length === 0) {
77
+ return { ok: true, detail: `${sources.length} commands up to date` };
78
+ }
79
+
80
+ const parts = [];
81
+ if (missing.length > 0) parts.push(`${missing.length} not synced`);
82
+ if (extra.length > 0) parts.push(`${extra.length} stale`);
83
+ return {
84
+ ok: false,
85
+ detail: parts.join(', '),
86
+ remedy:
87
+ 'Run `npm run sync:commands` to regenerate the `.claude/commands/` tree.',
88
+ };
89
+ }
90
+
91
+ // check: agents-in-sync
92
+
93
+ /**
94
+ * Resolve `delivery.routing.roleScopedAgents` without `resolveConfig()`,
95
+ * which pulls in AJV and would break the built-ins-only contract. Shallow-
96
+ * merges only `delivery.routing` from `.agentrc.json` and
97
+ * `.agentrc.local.json` (local wins).
98
+ *
99
+ * @param {string} projectRoot
100
+ * @param {typeof fs} fsImpl
101
+ * @returns {boolean}
102
+ */
103
+ function resolveRoleScopedAgentsFlag(projectRoot, fsImpl) {
104
+ const base = readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl);
105
+ const local = readJsonSafe(
106
+ path.join(projectRoot, '.agentrc.local.json'),
107
+ fsImpl,
108
+ );
109
+ const merged = {
110
+ delivery: {
111
+ routing: {
112
+ ...(base?.delivery?.routing ?? {}),
113
+ ...(local?.delivery?.routing ?? {}),
114
+ },
115
+ },
116
+ };
117
+ return getDeliveryRouting(merged).roleScopedAgents;
118
+ }
119
+
120
+ /**
121
+ * Parity of `.claude/agents/*.md` against `.agents/agents/*.md` (root anchored
122
+ * at `process.cwd()` as in `commands-in-sync`). A never-materialized tree is
123
+ * fatal while `roleScopedAgents` is on — the acceptance critic would silently
124
+ * fail to spawn and fall back to a weaker inline critic — and advisory when it
125
+ * is off. Drift in a materialized tree always fails.
126
+ *
127
+ * @param {{
128
+ * projectRoot?: string,
129
+ * cwd?: () => string,
130
+ * readDir?: (dir: string) => string[],
131
+ * fsImpl?: typeof fs,
132
+ * roleScopedAgents?: boolean,
133
+ * }} [opts]
134
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
135
+ */
136
+ export function runAgentsInSync({
137
+ projectRoot,
138
+ cwd,
139
+ readDir,
140
+ fsImpl = fs,
141
+ roleScopedAgents,
142
+ } = {}) {
143
+ const getCwd = cwd ?? (() => process.cwd());
144
+ const root = projectRoot ?? getCwd();
145
+ const listDir =
146
+ readDir ??
147
+ ((dir) => {
148
+ try {
149
+ return fsImpl.readdirSync(dir).filter((f) => f.endsWith('.md'));
150
+ } catch {
151
+ return [];
152
+ }
153
+ });
154
+
155
+ const srcDir = path.join(root, '.agents', 'agents');
156
+ const destDir = path.join(root, '.claude', 'agents');
157
+
158
+ const sources = listDir(srcDir)
159
+ .filter((f) => !f.startsWith('.'))
160
+ .sort();
161
+ const dests = listDir(destDir)
162
+ .filter((f) => !f.startsWith('.'))
163
+ .sort();
164
+
165
+ if (dests.length === 0) {
166
+ if (sources.length === 0) {
167
+ return { ok: true, detail: '0 agents up to date' };
168
+ }
169
+ const resolvedFlag =
170
+ typeof roleScopedAgents === 'boolean'
171
+ ? roleScopedAgents
172
+ : resolveRoleScopedAgentsFlag(root, fsImpl);
173
+ if (!resolvedFlag) {
174
+ return {
175
+ ok: true,
176
+ detail: `${sources.length} agent def(s) not materialized (roleScopedAgents is disabled)`,
177
+ };
178
+ }
179
+ return {
180
+ ok: false,
181
+ detail: `${sources.length} agent def(s) not yet materialized in .claude/agents/`,
182
+ remedy:
183
+ 'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
184
+ };
185
+ }
186
+
187
+ const srcSet = new Set(sources);
188
+ const dstSet = new Set(dests);
189
+ const missing = sources.filter((f) => !dstSet.has(f));
190
+ const extra = dests.filter((f) => !srcSet.has(f));
191
+
192
+ if (missing.length === 0 && extra.length === 0) {
193
+ return { ok: true, detail: `${sources.length} agents up to date` };
194
+ }
195
+
196
+ const parts = [];
197
+ if (missing.length > 0) parts.push(`${missing.length} not synced`);
198
+ if (extra.length > 0) parts.push(`${extra.length} stale`);
199
+ return {
200
+ ok: false,
201
+ detail: parts.join(', '),
202
+ remedy:
203
+ 'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
204
+ };
205
+ }