mandrel 2.83.0 → 2.84.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 (43) hide show
  1. package/.agents/README.md +65 -20
  2. package/.agents/docs/configuration.md +36 -0
  3. package/.agents/docs/runbooks/mods.md +98 -54
  4. package/.agents/docs/workflows.md +14 -0
  5. package/.agents/instructions.md +4 -1
  6. package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
  7. package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
  8. package/.agents/scripts/boot-sweep.js +42 -13
  9. package/.agents/scripts/generate-workflows-doc.js +14 -0
  10. package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
  11. package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
  12. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
  13. package/.agents/scripts/lib/codex/agents-projection.js +284 -0
  14. package/.agents/scripts/lib/codex/skills-projection.js +291 -0
  15. package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
  16. package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
  17. package/.agents/scripts/lib/config-resolver.js +5 -42
  18. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  19. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  20. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
  21. package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
  22. package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
  23. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
  24. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +12 -5
  25. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
  26. package/.agents/scripts/single-story-init.js +20 -5
  27. package/.agents/scripts/sync-agentrc.js +5 -3
  28. package/.agents/scripts/sync-claude-agents.js +20 -0
  29. package/.agents/scripts/sync-claude-commands.js +64 -27
  30. package/.agents/scripts/sync-codex-agents.js +36 -0
  31. package/.agents/scripts/sync-codex-skills.js +36 -0
  32. package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
  33. package/.agents/workflows/mandrel-update.md +2 -1
  34. package/docs/CHANGELOG.md +15 -0
  35. package/lib/cli/guarded-sync.js +3 -2
  36. package/lib/cli/registry.js +248 -0
  37. package/lib/cli/sync-agents.js +5 -2
  38. package/lib/cli/sync-commands.js +5 -2
  39. package/lib/cli/sync.js +45 -14
  40. package/lib/cli/uninstall.js +8 -1
  41. package/lib/migrations/index.js +2 -0
  42. package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
  43. package/package.json +3 -2
@@ -11,8 +11,13 @@
11
11
  import { spawnSync } from 'node:child_process';
12
12
  import fs from 'node:fs';
13
13
  import { createRequire } from 'node:module';
14
+ import os from 'node:os';
14
15
  import path from 'node:path';
15
16
  import { fileURLToPath } from 'node:url';
17
+ import {
18
+ SYSTEM_PROMPT_IMPORT,
19
+ SYSTEM_PROMPT_READ_DIRECTIVE,
20
+ } from '../../.agents/scripts/lib/bootstrap/agents-md-fold.js';
16
21
  import {
17
22
  BASELINE_MERGE_DRIVER_CONFIG_KEY,
18
23
  BASELINE_MERGE_DRIVER_REMEDY,
@@ -24,6 +29,16 @@ import {
24
29
  REQUIRED_NODE_FLOOR,
25
30
  satisfiesNodeEngine,
26
31
  } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
32
+ import {
33
+ CODEX_AGENTS_DIR,
34
+ expectedCodexAgents,
35
+ listGeneratedCodexAgents,
36
+ } from '../../.agents/scripts/lib/codex/agents-projection.js';
37
+ import {
38
+ CODEX_SKILLS_DIR,
39
+ expectedCodexSkills,
40
+ listGeneratedCodexSkills,
41
+ } from '../../.agents/scripts/lib/codex/skills-projection.js';
27
42
  import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
28
43
  import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
29
44
  import { isResolvable } from '../../.agents/scripts/lib/runtime-deps/dep-resolution.js';
@@ -392,6 +407,227 @@ function runAgentsInSync({
392
407
  };
393
408
  }
394
409
 
410
+ // check: codex-skills-in-sync / codex-agents-in-sync
411
+
412
+ /**
413
+ * Compare a generated tree against what its projector would write now.
414
+ * `readEntry(name)` returns the on-disk text or null.
415
+ *
416
+ * @param {{
417
+ * expected: () => Map<string, string>,
418
+ * onDisk: string[],
419
+ * readEntry: (name: string) => string | null,
420
+ * noun: string,
421
+ * where: string,
422
+ * remedy: string,
423
+ * }} spec
424
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
425
+ */
426
+ function projectionParity({
427
+ expected,
428
+ onDisk,
429
+ readEntry,
430
+ noun,
431
+ where,
432
+ remedy,
433
+ }) {
434
+ let want;
435
+ try {
436
+ want = expected();
437
+ } catch (err) {
438
+ return { ok: false, detail: err.message, remedy };
439
+ }
440
+ const have = new Set(onDisk);
441
+ const missing = [...want.keys()].filter((n) => !have.has(n));
442
+ const stale = [...want.entries()].filter(
443
+ ([n, body]) => have.has(n) && readEntry(n) !== body,
444
+ );
445
+ const extra = onDisk.filter((n) => !want.has(n));
446
+ if (missing.length + stale.length + extra.length === 0) {
447
+ return { ok: true, detail: `${want.size} ${noun} up to date in ${where}` };
448
+ }
449
+ const parts = [];
450
+ if (missing.length > 0) parts.push(`${missing.length} not synced`);
451
+ if (stale.length + extra.length > 0) {
452
+ parts.push(`${stale.length + extra.length} stale`);
453
+ }
454
+ return { ok: false, detail: `${parts.join(', ')} in ${where}`, remedy };
455
+ }
456
+
457
+ /**
458
+ * @param {string} file
459
+ * @returns {string | null}
460
+ */
461
+ function readTextOrNull(file) {
462
+ try {
463
+ return fs.readFileSync(file, 'utf8');
464
+ } catch {
465
+ return null;
466
+ }
467
+ }
468
+
469
+ /**
470
+ * Parity of `.agents/skills/workflows/` against the workflow set — the Codex
471
+ * twin of `commands-in-sync`, byte-for-byte rather than by name.
472
+ *
473
+ * @param {{ projectRoot?: string, cwd?: () => string }} [opts]
474
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
475
+ */
476
+ export function runCodexSkillsInSync({ projectRoot, cwd } = {}) {
477
+ const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
478
+ const destDir = path.join(root, ...CODEX_SKILLS_DIR.split('/'));
479
+ return projectionParity({
480
+ expected: () => expectedCodexSkills({ projectRoot: root }),
481
+ onDisk: listGeneratedCodexSkills(destDir),
482
+ readEntry: (name) => readTextOrNull(path.join(destDir, name, 'SKILL.md')),
483
+ noun: 'Codex skills',
484
+ where: `${CODEX_SKILLS_DIR}/`,
485
+ remedy: `Run \`mandrel sync-commands\` to regenerate the Codex skills under \`${CODEX_SKILLS_DIR}/\`.`,
486
+ });
487
+ }
488
+
489
+ /**
490
+ * Parity of `.codex/agents/mandrel-*.toml` against `.agents/agents/` — the
491
+ * Codex twin of `agents-in-sync`.
492
+ *
493
+ * @param {{ projectRoot?: string, cwd?: () => string }} [opts]
494
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
495
+ */
496
+ export function runCodexAgentsInSync({ projectRoot, cwd } = {}) {
497
+ const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
498
+ const destDir = path.join(root, ...CODEX_AGENTS_DIR.split('/'));
499
+ return projectionParity({
500
+ expected: () => expectedCodexAgents({ projectRoot: root }),
501
+ onDisk: listGeneratedCodexAgents(destDir),
502
+ readEntry: (name) => readTextOrNull(path.join(destDir, name)),
503
+ noun: 'Codex agents',
504
+ where: `${CODEX_AGENTS_DIR}/`,
505
+ remedy: `Run \`mandrel sync-agents\` to regenerate \`${CODEX_AGENTS_DIR}/mandrel-<role>.toml\`.`,
506
+ });
507
+ }
508
+
509
+ // check: codex-instructions
510
+
511
+ /** Codex's default `project_doc_max_bytes`. */
512
+ export const CODEX_PROJECT_DOC_MAX_BYTES = 32768;
513
+
514
+ /**
515
+ * A top-level `project_doc_max_bytes = <int>` line before any `[table]`
516
+ * header; anything else (absent file, nested key, non-integer) is null. No
517
+ * TOML dependency — this one key is all the check needs.
518
+ *
519
+ * @param {string | null} text
520
+ * @returns {number | null}
521
+ */
522
+ export function readProjectDocMaxBytes(text) {
523
+ if (typeof text !== 'string') return null;
524
+ for (const line of text.split(/\r?\n/)) {
525
+ if (/^\s*\[/.test(line)) return null;
526
+ const match = /^\s*project_doc_max_bytes\s*=\s*(\d+)\s*(?:#.*)?$/.exec(
527
+ line,
528
+ );
529
+ if (match) return Number(match[1]);
530
+ }
531
+ return null;
532
+ }
533
+
534
+ /**
535
+ * Effective limit and where it came from: project `.codex/config.toml`, then
536
+ * `$CODEX_HOME/config.toml` (default `~/.codex`), else the default.
537
+ *
538
+ * @param {string} root
539
+ * @param {NodeJS.ProcessEnv} env
540
+ * @param {string} homeDir
541
+ * @param {(file: string) => string | null} readText
542
+ * @returns {{ limit: number, source: string }}
543
+ */
544
+ function resolveProjectDocLimit(root, env, homeDir, readText) {
545
+ const codexHome = env.CODEX_HOME || path.join(homeDir, '.codex');
546
+ for (const [file, source] of [
547
+ [path.join(root, '.codex', 'config.toml'), '.codex/config.toml'],
548
+ [path.join(codexHome, 'config.toml'), '$CODEX_HOME/config.toml'],
549
+ ]) {
550
+ const limit = readProjectDocMaxBytes(readText(file));
551
+ if (limit !== null) return { limit, source };
552
+ }
553
+ return { limit: CODEX_PROJECT_DOC_MAX_BYTES, source: 'the Codex default' };
554
+ }
555
+
556
+ const HOIST_REMEDY =
557
+ 'Move the `## System Prompt` block to the top of the file, or run `mandrel update` (its 2.84.0 migration moves it).';
558
+
559
+ /**
560
+ * Does Codex load the Mandrel block? Sizes the root `AGENTS.override.md`, else
561
+ * `AGENTS.md`, against the effective `project_doc_max_bytes`. Fails when the
562
+ * block (import through read directive) does not end inside the limit, or
563
+ * carries no directive Codex can follow; an oversized file whose block still
564
+ * loads passes with an advisory. No entry doc at all skips, as
565
+ * `claude-code-version` does.
566
+ *
567
+ * @param {{
568
+ * projectRoot?: string,
569
+ * cwd?: () => string,
570
+ * env?: NodeJS.ProcessEnv,
571
+ * homeDir?: string,
572
+ * readText?: (file: string) => string | null,
573
+ * }} [opts]
574
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
575
+ */
576
+ export function runCodexInstructions({
577
+ projectRoot,
578
+ cwd,
579
+ env = process.env,
580
+ homeDir = os.homedir(),
581
+ readText = readTextOrNull,
582
+ } = {}) {
583
+ const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
584
+ const { limit, source } = resolveProjectDocLimit(
585
+ root,
586
+ env,
587
+ homeDir,
588
+ readText,
589
+ );
590
+ const override = readText(path.join(root, 'AGENTS.override.md'));
591
+ const docName = override === null ? 'AGENTS.md' : 'AGENTS.override.md';
592
+ const text = override ?? readText(path.join(root, 'AGENTS.md'));
593
+ if (text === null) {
594
+ return { ok: true, detail: 'skipped: no AGENTS.md' };
595
+ }
596
+ const importAt = text.indexOf(SYSTEM_PROMPT_IMPORT);
597
+ const directiveAt = text.indexOf(SYSTEM_PROMPT_READ_DIRECTIVE);
598
+ if (importAt === -1 || directiveAt === -1) {
599
+ return {
600
+ ok: false,
601
+ detail: `${docName} carries no Mandrel read directive for hosts without @-imports — Codex would not load .agents/instructions.md`,
602
+ remedy: HOIST_REMEDY,
603
+ };
604
+ }
605
+ const bytes = (s) => Buffer.byteLength(s, 'utf8');
606
+ const start = bytes(text.slice(0, Math.min(importAt, directiveAt)));
607
+ const end = bytes(
608
+ text.slice(0, directiveAt + SYSTEM_PROMPT_READ_DIRECTIVE.length),
609
+ );
610
+ const total = bytes(text);
611
+ const limitLabel = `project_doc_max_bytes ${limit} (${source})`;
612
+ if (end > limit) {
613
+ return {
614
+ ok: false,
615
+ detail: `the Mandrel block in ${docName} spans bytes ${start}–${end}, beyond ${limitLabel} — Codex never reads it`,
616
+ remedy: HOIST_REMEDY,
617
+ };
618
+ }
619
+ if (total > limit) {
620
+ return {
621
+ ok: true,
622
+ detail: `${docName} is ${total} bytes, over ${limitLabel}: the Mandrel block (bytes ${start}–${end}) loads, the last ${total - limit} bytes do not — raise project_doc_max_bytes in .codex/config.toml to load them`,
623
+ };
624
+ }
625
+ return {
626
+ ok: true,
627
+ detail: `${docName} is ${total} bytes, within ${limitLabel}; the Mandrel block loads`,
628
+ };
629
+ }
630
+
395
631
  // check: runtime-deps
396
632
 
397
633
  /**
@@ -1134,6 +1370,18 @@ export const registry = [
1134
1370
  name: 'agents-in-sync',
1135
1371
  run: (opts) => runAgentsInSync(opts),
1136
1372
  },
1373
+ {
1374
+ name: 'codex-skills-in-sync',
1375
+ run: (opts) => runCodexSkillsInSync(opts),
1376
+ },
1377
+ {
1378
+ name: 'codex-agents-in-sync',
1379
+ run: (opts) => runCodexAgentsInSync(opts),
1380
+ },
1381
+ {
1382
+ name: 'codex-instructions',
1383
+ run: (opts) => runCodexInstructions(opts),
1384
+ },
1137
1385
  {
1138
1386
  name: 'runtime-deps',
1139
1387
  run: (opts) => runRuntimeDeps(opts),
@@ -1,11 +1,14 @@
1
1
  // lib/cli/sync-agents.js
2
- /** `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/`. */
2
+ /**
3
+ * `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/` and,
4
+ * in the same run, into Codex custom agents `.codex/agents/mandrel-<role>.toml`.
5
+ */
3
6
 
4
7
  import { runGuardedSync } from './guarded-sync.js';
5
8
 
6
9
  const SPEC = {
7
10
  command: 'sync-agents',
8
- target: '.claude/agents/',
11
+ target: '.claude/agents/ and .codex/agents/',
9
12
  script: 'sync-claude-agents.js',
10
13
  };
11
14
 
@@ -1,11 +1,14 @@
1
1
  // lib/cli/sync-commands.js
2
- /** `mandrel sync-commands`: project `.agents/workflows/` into `.claude/commands/`. */
2
+ /**
3
+ * `mandrel sync-commands`: project `.agents/workflows/` into `.claude/commands/`
4
+ * and, in the same run, into Codex skills under `.agents/skills/workflows/`.
5
+ */
3
6
 
4
7
  import { runGuardedSync } from './guarded-sync.js';
5
8
 
6
9
  const SPEC = {
7
10
  command: 'sync-commands',
8
- target: '.claude/commands/',
11
+ target: '.claude/commands/ and .agents/skills/workflows/',
9
12
  script: 'sync-claude-commands.js',
10
13
  };
11
14
 
package/lib/cli/sync.js CHANGED
@@ -19,6 +19,7 @@ import path from 'node:path';
19
19
 
20
20
  import { ensureBaselineMergeDriver } from '../../.agents/scripts/lib/bootstrap/baseline-merge-driver.js';
21
21
  import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/install-ledger.js';
22
+ import { CODEX_SKILLS_DIR } from '../../.agents/scripts/lib/codex/skills-projection.js';
22
23
 
23
24
  export const PACKAGE_NAME = 'mandrel';
24
25
 
@@ -72,6 +73,46 @@ export const GENERATED_FILES = Object.freeze([
72
73
  toManagedZoneRelative(LEDGER_RELATIVE_PATH),
73
74
  ]);
74
75
 
76
+ /**
77
+ * Framework-generated `.agents/` directories, the prefix sibling of
78
+ * {@link GENERATED_FILES}: everything under one is a projection `sync-commands`
79
+ * regenerates, so neither the payload copy, the prune pass nor the
80
+ * `agents-drift` comparison treats it as payload. Keyed off the projector's
81
+ * exported constant.
82
+ */
83
+ export const GENERATED_DIRS = Object.freeze([
84
+ toManagedZoneRelative(CODEX_SKILLS_DIR),
85
+ ]);
86
+
87
+ /**
88
+ * The top-level local zone or a {@link GENERATED_DIRS} directory — skipped by
89
+ * both the payload walk and the prune walk.
90
+ *
91
+ * @param {import('node:fs').Dirent} ent
92
+ * @param {string} rel - `.agents/`-relative path (OS separators).
93
+ * @param {string} prefix - Parent's relative path (`''` at the top level).
94
+ * @returns {boolean}
95
+ */
96
+ function isSkippedDir(ent, rel, prefix) {
97
+ if (!ent.isDirectory()) return false;
98
+ if (prefix === '' && ent.name === LOCAL_ZONE_DIR) return true;
99
+ return GENERATED_DIRS.includes(rel);
100
+ }
101
+
102
+ /**
103
+ * Whether the prune walk leaves an entry alone: {@link isSkippedDir}, a
104
+ * `*.local.*` override, or a {@link GENERATED_FILES} file.
105
+ *
106
+ * @param {import('node:fs').Dirent} ent
107
+ * @param {string} rel
108
+ * @param {string} prefix
109
+ * @returns {boolean}
110
+ */
111
+ function isPruneExempt(ent, rel, prefix) {
112
+ if (ent.isDirectory()) return isSkippedDir(ent, rel, prefix);
113
+ return LOCAL_OVERRIDE_RE.test(ent.name) || GENERATED_FILES.includes(rel);
114
+ }
115
+
75
116
  /**
76
117
  * Version of the payload just copied, read at `packageRoot` — not the
77
118
  * running CLI's own version, which may differ.
@@ -123,7 +164,7 @@ export function defaultResolvePackageRoot(fromDir) {
123
164
 
124
165
  /**
125
166
  * Every file under `dir` (relative, OS separators), skipping the top-level
126
- * local zone only.
167
+ * local zone and {@link GENERATED_DIRS}.
127
168
  *
128
169
  * @param {string} dir - Absolute directory to walk.
129
170
  * @param {typeof nodeFs} fsImpl
@@ -133,10 +174,8 @@ export function defaultResolvePackageRoot(fromDir) {
133
174
  export function listFiles(dir, fsImpl, prefix = '') {
134
175
  const out = [];
135
176
  for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
136
- if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
137
- continue;
138
- }
139
177
  const rel = prefix ? path.join(prefix, ent.name) : ent.name;
178
+ if (isSkippedDir(ent, rel, prefix)) continue;
140
179
  const abs = path.join(dir, ent.name);
141
180
  if (ent.isDirectory()) {
142
181
  out.push(...listFiles(abs, fsImpl, rel));
@@ -149,7 +188,7 @@ export function listFiles(dir, fsImpl, prefix = '') {
149
188
 
150
189
  /**
151
190
  * Destination-tree enumeration for pruning. Skips the top-level local zone,
152
- * `*.local.*` overrides, and {@link GENERATED_FILES}.
191
+ * `*.local.*` overrides, {@link GENERATED_FILES} and {@link GENERATED_DIRS}.
153
192
  *
154
193
  * @param {string} dir - Absolute directory to walk.
155
194
  * @param {typeof nodeFs} fsImpl
@@ -165,16 +204,8 @@ function listDestFiles(dir, fsImpl, prefix = '') {
165
204
  return out;
166
205
  }
167
206
  for (const ent of entries) {
168
- if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
169
- continue;
170
- }
171
- if (!ent.isDirectory() && LOCAL_OVERRIDE_RE.test(ent.name)) {
172
- continue;
173
- }
174
207
  const rel = prefix ? path.join(prefix, ent.name) : ent.name;
175
- if (!ent.isDirectory() && GENERATED_FILES.includes(rel)) {
176
- continue;
177
- }
208
+ if (isPruneExempt(ent, rel, prefix)) continue;
178
209
  const abs = path.join(dir, ent.name);
179
210
  if (ent.isDirectory()) {
180
211
  out.push(...listDestFiles(abs, fsImpl, rel));
@@ -26,6 +26,7 @@ import {
26
26
  SYSTEM_PROMPT_AGENTS_MD,
27
27
  SYSTEM_PROMPT_BLOCK,
28
28
  SYSTEM_PROMPT_IMPORT,
29
+ SYSTEM_PROMPT_READ_DIRECTIVE,
29
30
  } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
30
31
  import {
31
32
  DOWNSTREAM_PRE_COMMIT,
@@ -61,6 +62,12 @@ const FRAMEWORK_NPM_SCRIPTS = Object.freeze({
61
62
  * @property {string} detail
62
63
  */
63
64
 
65
+ /** The block's own lines, stripped one by one from a hand-edited block. */
66
+ const FRAMEWORK_PROMPT_LINES = new Set([
67
+ SYSTEM_PROMPT_IMPORT,
68
+ SYSTEM_PROMPT_READ_DIRECTIVE,
69
+ ]);
70
+
64
71
  /**
65
72
  * Strip the system-prompt import block from a root entry doc. The file is
66
73
  * deleted only when byte-identical to the install template — a heading-only
@@ -95,7 +102,7 @@ function revertEntryDoc(rel, projectRoot, fsImpl) {
95
102
  if (next.includes(SYSTEM_PROMPT_IMPORT)) {
96
103
  next = next
97
104
  .split('\n')
98
- .filter((line) => line.trim() !== SYSTEM_PROMPT_IMPORT)
105
+ .filter((line) => !FRAMEWORK_PROMPT_LINES.has(line.trim()))
99
106
  .join('\n');
100
107
  }
101
108
  next = next.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
@@ -19,6 +19,7 @@ import { baselineMergeQueueShape } from './steps/2.63.0-baseline-merge-queue-sha
19
19
  import { foldClaudeMdIntoAgentsMdStep } from './steps/2.65.0-fold-claude-md-into-agents-md.js';
20
20
  import { retireAuditLedger } from './steps/2.70.0-retire-audit-ledger.js';
21
21
  import { containerSafeProjections } from './steps/2.79.0-container-safe-projections.js';
22
+ import { hoistSystemPromptBlockStep } from './steps/2.84.0-hoist-system-prompt-block.js';
22
23
  import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
23
24
 
24
25
  /**
@@ -46,6 +47,7 @@ export const migrations = [
46
47
  foldClaudeMdIntoAgentsMdStep,
47
48
  retireAuditLedger,
48
49
  containerSafeProjections,
50
+ hoistSystemPromptBlockStep,
49
51
  ];
50
52
 
51
53
  export { compareVersions };
@@ -0,0 +1,64 @@
1
+ // lib/migrations/steps/2.84.0-hoist-system-prompt-block.js
2
+ /**
3
+ * Move an already-appended Mandrel system-prompt block to the top of
4
+ * AGENTS.md (after a leading H1) and upgrade it to carry the prose read
5
+ * directive. Codex stops reading AGENTS.md at `project_doc_max_bytes` and
6
+ * expands no `@` imports, so a block appended to a long file never loads
7
+ * there. Shares the bootstrap placement contract.
8
+ */
9
+
10
+ import nodeFs from 'node:fs';
11
+ import path from 'node:path';
12
+
13
+ import {
14
+ hoistSystemPromptBlock,
15
+ needsSystemPromptHoist,
16
+ } from '../../../.agents/scripts/lib/bootstrap/agents-md-fold.js';
17
+
18
+ const ENTRY_DOC = 'AGENTS.md';
19
+
20
+ /**
21
+ * @param {{ projectRoot?: string }} [ctx]
22
+ * @param {typeof nodeFs} fsImpl
23
+ * @returns {string | null} AGENTS.md text, or null when absent.
24
+ */
25
+ function readEntryDoc(ctx, fsImpl) {
26
+ const target = path.join(ctx?.projectRoot ?? process.cwd(), ENTRY_DOC);
27
+ try {
28
+ return fsImpl.readFileSync(target, 'utf8');
29
+ } catch {
30
+ return null;
31
+ }
32
+ }
33
+
34
+ export const hoistSystemPromptBlockStep = {
35
+ version: '2.84.0',
36
+ description:
37
+ 'move the AGENTS.md system-prompt block to the top and add the read ' +
38
+ 'directive for hosts without @-imports (Story #5655)',
39
+ /**
40
+ * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
41
+ * @param {typeof nodeFs} [fsImpl]
42
+ * @returns {boolean}
43
+ */
44
+ detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
45
+ const text = readEntryDoc(ctx, fsImpl);
46
+ return text !== null && needsSystemPromptHoist(text);
47
+ },
48
+ /**
49
+ * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
50
+ * @param {typeof nodeFs} [fsImpl]
51
+ * @returns {void}
52
+ */
53
+ apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
54
+ const text = readEntryDoc(ctx, fsImpl);
55
+ if (text === null) return;
56
+ const next = hoistSystemPromptBlock(text);
57
+ if (next === text) return;
58
+ fsImpl.writeFileSync(
59
+ path.join(ctx?.projectRoot ?? process.cwd(), ENTRY_DOC),
60
+ next,
61
+ 'utf8',
62
+ );
63
+ },
64
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.83.0",
3
+ "version": "2.84.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/",
@@ -8,7 +8,8 @@
8
8
  "docs/CHANGELOG.md",
9
9
  "lib/",
10
10
  "!lib/**/__tests__",
11
- "!.agents/**/__tests__"
11
+ "!.agents/**/__tests__",
12
+ "!.agents/skills/workflows"
12
13
  ],
13
14
  "publishConfig": {
14
15
  "access": "public",