mandrel 2.83.0 → 2.85.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 (54) 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/schemas/story-deliver-terminal.schema.json +2 -2
  9. package/.agents/scripts/boot-sweep.js +42 -13
  10. package/.agents/scripts/coverage-capture.js +1 -0
  11. package/.agents/scripts/evidence-gate.js +1 -0
  12. package/.agents/scripts/generate-workflows-doc.js +14 -0
  13. package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
  14. package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
  15. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
  16. package/.agents/scripts/lib/close-lock-events.js +29 -9
  17. package/.agents/scripts/lib/codex/agents-projection.js +284 -0
  18. package/.agents/scripts/lib/codex/skills-projection.js +291 -0
  19. package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
  20. package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
  21. package/.agents/scripts/lib/config-resolver.js +5 -42
  22. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  23. package/.agents/scripts/lib/full-suite-lock.js +2 -0
  24. package/.agents/scripts/lib/full-suite-queue.js +66 -26
  25. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +242 -0
  27. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +151 -111
  28. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
  29. package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
  30. package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
  31. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +12 -5
  33. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +30 -4
  34. package/.agents/scripts/lib/orchestration/story-handoff.js +84 -10
  35. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
  36. package/.agents/scripts/single-story-init.js +20 -5
  37. package/.agents/scripts/sync-agentrc.js +5 -3
  38. package/.agents/scripts/sync-claude-agents.js +20 -0
  39. package/.agents/scripts/sync-claude-commands.js +64 -27
  40. package/.agents/scripts/sync-codex-agents.js +36 -0
  41. package/.agents/scripts/sync-codex-skills.js +36 -0
  42. package/.agents/workflows/helpers/deliver-story-reference.md +6 -0
  43. package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
  44. package/.agents/workflows/mandrel-update.md +2 -1
  45. package/docs/CHANGELOG.md +23 -0
  46. package/lib/cli/guarded-sync.js +3 -2
  47. package/lib/cli/registry.js +248 -0
  48. package/lib/cli/sync-agents.js +5 -2
  49. package/lib/cli/sync-commands.js +5 -2
  50. package/lib/cli/sync.js +45 -14
  51. package/lib/cli/uninstall.js +8 -1
  52. package/lib/migrations/index.js +2 -0
  53. package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
  54. package/package.json +3 -2
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Project the workflow set into Codex skills under `.agents/skills/workflows/`.
5
+ * `sync-claude-commands.js` runs the same projection after the Claude one, so
6
+ * `mandrel sync-commands` and `npm run sync:commands` cover both hosts; this
7
+ * entry point refreshes the Codex half alone.
8
+ */
9
+
10
+ import { runAsCli } from './lib/cli-utils.js';
11
+ import {
12
+ CODEX_SKILLS_DIR,
13
+ syncCodexSkills,
14
+ } from './lib/codex/skills-projection.js';
15
+ import { Logger } from './lib/Logger.js';
16
+
17
+ /** @returns {Promise<void>} */
18
+ async function main() {
19
+ const { written, total } = syncCodexSkills({
20
+ projectRoot: process.cwd(),
21
+ log: (line) => Logger.info(line),
22
+ });
23
+ Logger.info(
24
+ `\n✔ ${written.length} file(s) synced, ${total} total skills in ${CODEX_SKILLS_DIR}/`,
25
+ );
26
+ }
27
+
28
+ runAsCli(import.meta.url, main, {
29
+ source: 'sync-codex-skills',
30
+ usage: {
31
+ invocation: 'node .agents/scripts/sync-codex-skills.js',
32
+ summary:
33
+ 'Regenerate the Codex skill projection of .agents/workflows/ (and .agents/local/workflows/) under .agents/skills/workflows/.',
34
+ flags: [],
35
+ },
36
+ });
@@ -276,6 +276,12 @@ judgment that help text cannot carry.
276
276
  `gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
277
277
  reaching for it twice for the same shape of finding, the gate is
278
278
  miscalibrated — fix the gate, not the run.
279
+ - `gates.codeReview: "degraded"` — not a flag but an envelope value: a
280
+ review surface ran yet produced no verdict (the `claude` CLI is not logged
281
+ in or out of quota, or its output did not parse). The PR comment lists it
282
+ under Degraded Gates. It is reported, not blocking — close still lands —
283
+ so read the diff yourself before trusting the merge. Precedence:
284
+ `overridden` > `degraded` > `passed`.
279
285
  - `--max-wait-seconds <n>` — from a headless caller with no host
280
286
  tool-invocation ceiling, to keep single-block semantics
281
287
  without editing the consumer's config.
@@ -35,9 +35,10 @@ The reconciliation rules:
35
35
 
36
36
  | Scenario | Behavior |
37
37
  | --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
38
- | Project value validates against schema | **Preserve** unconditionally |
38
+ | Merged config (`.agentrc.json` + `.agentrc.local.json`) validates | **Preserve** unconditionally |
39
39
  | Project value fails validation | **Abort** with a list of validation errors |
40
- | Required key missing in project | **Abort via validator** — the schema catches it; the helper does not auto-fill |
40
+ | Required key missing from both files | **Abort via validator** — the schema catches it; the helper does not auto-fill |
41
+ | Required key supplied only by `.agentrc.local.json` | **Valid** — the overlay is merged before validation, as the runtime resolver does |
41
42
  | Optional key missing in project | **Leave absent** — the runtime resolves the framework default at read time |
42
43
  | Project value deep-equals framework default | **Emit `[REDUNDANT]` advisory** (informational only — the file is never modified) |
43
44
  | Identity placeholder paths (`github.owner` / `repo` / …) | **Never flagged** — they carry no usable framework default |
@@ -72,22 +73,28 @@ The script:
72
73
  override). When the file is missing, prints an error asking the
73
74
  operator to run `mandrel init` (new project) or
74
75
  `node .agents/scripts/bootstrap.js` (existing project) and exits 1.
75
- 2. Validates the parsed config against the framework AJV schema
76
+ 2. When a gitignored `.agentrc.local.json` exists, deep-merges it over
77
+ `.agentrc.json` exactly as the runtime resolver does (a malformed overlay
78
+ is reported by name and exits 1). Per-operator identity such as
79
+ `github.operatorHandle` may therefore live in the overlay alone — see
80
+ [Multi-operator repos](../../docs/configuration.md#multi-operator-repos).
81
+ 3. Validates the merged config against the framework AJV schema
76
82
  (`getAgentrcValidator()`). On any failure, prints a single-line error
77
83
  list and exits 1 — the operator must fix the typo / missing required
78
- key before re-running.
79
- 3. Walks every default leaf path. For each path where the project
80
- carries a value deep-equal to the framework default, prints a
81
- `[REDUNDANT]` advisory row. Advisories are informational — the
84
+ key before re-running. A missing `github.operatorHandle` names where to
85
+ set it.
86
+ 4. Walks every default leaf path. For each path where the committed
87
+ `.agentrc.json` carries a value deep-equal to the framework default,
88
+ prints a `[REDUNDANT]` advisory row (overlay leaves are never flagged). Advisories are informational — the
82
89
  project file is never modified.
83
- 4. Prints the summary line and exits 0.
90
+ 5. Prints the summary line and exits 0.
84
91
 
85
92
  ### Exit codes
86
93
 
87
94
  | Code | Meaning |
88
95
  | ---- | ----------------------------------------------------------------------------- |
89
96
  | 0 | Config is valid (advisories may still appear) |
90
- | 1 | Config is missing, malformed JSON, or fails schema validation |
97
+ | 1 | `.agentrc.json` is missing, either file is malformed, or the merged config fails schema validation |
91
98
 
92
99
  ### Flags
93
100
 
@@ -147,7 +147,8 @@ node .agents/scripts/sync-agentrc.js
147
147
  ```
148
148
 
149
149
  The helper is default-aware and **read-only**: it validates
150
- the consumer config against the new schema (non-zero exit → fix the
150
+ the consumer config — `.agentrc.json` with any gitignored
151
+ `.agentrc.local.json` merged over it, as the runtime does — against the new schema (non-zero exit → fix the
151
152
  validation error and re-run before proceeding), never auto-fills missing
152
153
  optional keys (the runtime layers defaults at read time), and flags
153
154
  project values that deep-equal the framework default as `[REDUNDANT]`
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,29 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.85.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.84.0...mandrel-v2.85.0) (2026-10-13)
19
+
20
+
21
+ ### Added
22
+
23
+ * code-review held review: structured output, bounded context, and a degraded gate when no verdict is produced ([#5663](https://github.com/dsj1984/mandrel/issues/5663)) ([#5665](https://github.com/dsj1984/mandrel/issues/5665)) ([0927d4d](https://github.com/dsj1984/mandrel/commit/0927d4d3099e9cdb7e8f8491663f72f10f2042ac))
24
+ * stream full-suite lock wait progress live during story handoffs ([#5662](https://github.com/dsj1984/mandrel/issues/5662)) ([#5664](https://github.com/dsj1984/mandrel/issues/5664)) ([8a679cf](https://github.com/dsj1984/mandrel/commit/8a679cf248491642aa58990c8ae24532a49f286c))
25
+
26
+ ## [2.84.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.83.0...mandrel-v2.84.0) (2026-10-13)
27
+
28
+
29
+ ### Added
30
+
31
+ * make Codex a first-class Mandrel host alongside Claude Code ([#5655](https://github.com/dsj1984/mandrel/issues/5655)) ([#5660](https://github.com/dsj1984/mandrel/issues/5660)) ([14d999e](https://github.com/dsj1984/mandrel/commit/14d999eaebb8f456890e2e4cd49d2e912687f46d))
32
+ * mandrel-status band v2: one quiet line while healthy, a colored action line when a Story needs attention ([#5657](https://github.com/dsj1984/mandrel/issues/5657)) ([#5658](https://github.com/dsj1984/mandrel/issues/5658)) ([19ca2ee](https://github.com/dsj1984/mandrel/commit/19ca2ee2b6387fb828788dce79a89307d8787420))
33
+ * run the `codex` review provider on the Codex CLI instead of Claude ([#5656](https://github.com/dsj1984/mandrel/issues/5656)) ([#5659](https://github.com/dsj1984/mandrel/issues/5659)) ([0829fdf](https://github.com/dsj1984/mandrel/commit/0829fdf525198adf49773776c4d2bfc25e6519ed))
34
+
35
+
36
+ ### Fixed
37
+
38
+ * boot sweep finishes the agent::done flip for Stories GitHub closed while still at agent::closing ([#5652](https://github.com/dsj1984/mandrel/issues/5652)) ([#5653](https://github.com/dsj1984/mandrel/issues/5653)) ([f29e5f8](https://github.com/dsj1984/mandrel/commit/f29e5f88cff2ff09729dd2cadbb4248e428bf608))
39
+ * sync-agentrc validates the merged .agentrc.json + .agentrc.local.json, like the resolver ([#5649](https://github.com/dsj1984/mandrel/issues/5649)) ([#5650](https://github.com/dsj1984/mandrel/issues/5650)) ([7d4ee1d](https://github.com/dsj1984/mandrel/commit/7d4ee1d8add1d99a2cfd31d389d5495bfa9d8fd0))
40
+
18
41
  ## [2.83.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.82.0...mandrel-v2.83.0) (2026-10-12)
19
42
 
20
43
 
@@ -3,8 +3,9 @@
3
3
  * Shared body of `mandrel sync-commands` / `mandrel sync-agents`: run a
4
4
  * `.agents/scripts/` projector in a child process, forwarding its exit code.
5
5
  * Refuses first when `.agents/` does not match the running CLI (version
6
- * marker, else the `agents-drift` check): `.claude/*` is gitignored, so a
7
- * stale projection surfaces only when an agent hits a missing module.
6
+ * marker, else the `agents-drift` check): every projection (`.claude/*`, the
7
+ * Codex skills and agents) is gitignored, so a stale one surfaces only when an
8
+ * agent hits a missing module. The projector writes both hosts' trees.
8
9
  * The marker is read from `cwd()`; `PROJECT_ROOT` only names this CLI's version.
9
10
  */
10
11
 
@@ -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 };