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.
- package/.agents/README.md +65 -20
- package/.agents/docs/configuration.md +36 -0
- package/.agents/docs/runbooks/mods.md +98 -54
- package/.agents/docs/workflows.md +14 -0
- package/.agents/instructions.md +4 -1
- package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
- package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
- package/.agents/schemas/story-deliver-terminal.schema.json +2 -2
- package/.agents/scripts/boot-sweep.js +42 -13
- package/.agents/scripts/coverage-capture.js +1 -0
- package/.agents/scripts/evidence-gate.js +1 -0
- package/.agents/scripts/generate-workflows-doc.js +14 -0
- package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
- package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
- package/.agents/scripts/lib/close-lock-events.js +29 -9
- package/.agents/scripts/lib/codex/agents-projection.js +284 -0
- package/.agents/scripts/lib/codex/skills-projection.js +291 -0
- package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
- package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
- package/.agents/scripts/lib/config-resolver.js +5 -42
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/full-suite-lock.js +2 -0
- package/.agents/scripts/lib/full-suite-queue.js +66 -26
- package/.agents/scripts/lib/observability/source-classifier.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +242 -0
- package/.agents/scripts/lib/orchestration/review-providers/code-review.js +151 -111
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
- package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
- package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +12 -5
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +30 -4
- package/.agents/scripts/lib/orchestration/story-handoff.js +84 -10
- package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
- package/.agents/scripts/single-story-init.js +20 -5
- package/.agents/scripts/sync-agentrc.js +5 -3
- package/.agents/scripts/sync-claude-agents.js +20 -0
- package/.agents/scripts/sync-claude-commands.js +64 -27
- package/.agents/scripts/sync-codex-agents.js +36 -0
- package/.agents/scripts/sync-codex-skills.js +36 -0
- package/.agents/workflows/helpers/deliver-story-reference.md +6 -0
- package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
- package/.agents/workflows/mandrel-update.md +2 -1
- package/docs/CHANGELOG.md +23 -0
- package/lib/cli/guarded-sync.js +3 -2
- package/lib/cli/registry.js +248 -0
- package/lib/cli/sync-agents.js +5 -2
- package/lib/cli/sync-commands.js +5 -2
- package/lib/cli/sync.js +45 -14
- package/lib/cli/uninstall.js +8 -1
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
- 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
|
-
|
|
|
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
|
|
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.
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
`
|
|
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
|
-
|
|
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 |
|
|
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
|
|
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
|
|
package/lib/cli/guarded-sync.js
CHANGED
|
@@ -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
|
|
7
|
-
* stale
|
|
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
|
|
package/lib/cli/registry.js
CHANGED
|
@@ -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),
|
package/lib/cli/sync-agents.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
// lib/cli/sync-agents.js
|
|
2
|
-
/**
|
|
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
|
|
package/lib/cli/sync-commands.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
// lib/cli/sync-commands.js
|
|
2
|
-
/**
|
|
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
|
|
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
|
|
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 (
|
|
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));
|
package/lib/cli/uninstall.js
CHANGED
|
@@ -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()
|
|
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+/, '');
|
package/lib/migrations/index.js
CHANGED
|
@@ -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 };
|