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
|
@@ -7,12 +7,21 @@ export type StageName =
|
|
|
7
7
|
| 'close'
|
|
8
8
|
| 'merge';
|
|
9
9
|
|
|
10
|
+
/**
|
|
11
|
+
* What the band says about a Story; it picks the glyph, the color and whether
|
|
12
|
+
* a second line shows. `needs-you` is a `blocked` result (the HITL pause);
|
|
13
|
+
* `failed` is a `failed` / `escalated` result or a PR whose checks are red.
|
|
14
|
+
*/
|
|
15
|
+
export type Attention = 'working' | 'slow' | 'needs-you' | 'failed' | 'landed';
|
|
16
|
+
|
|
10
17
|
/** One stage as the Details pane lists it; times in epoch milliseconds. */
|
|
11
18
|
export type StageRow = {
|
|
12
19
|
name: StageName;
|
|
13
20
|
startedAt: number | null;
|
|
14
21
|
/** The next stage's start, or null while this one is current or pending. */
|
|
15
22
|
endedAt: number | null;
|
|
23
|
+
/** The learned median of the stage, once it has 3+ samples. */
|
|
24
|
+
usualMs: number | null;
|
|
16
25
|
};
|
|
17
26
|
|
|
18
27
|
/** One close phase: its recorded duration and the learned median, in seconds. */
|
|
@@ -28,23 +37,32 @@ export type Focus = {
|
|
|
28
37
|
title: string | null;
|
|
29
38
|
/** `in-flight`, or the terminal envelope's `status`. */
|
|
30
39
|
status: string;
|
|
40
|
+
attention: Attention;
|
|
31
41
|
stage: StageName;
|
|
32
|
-
/** The current stage's step
|
|
33
|
-
|
|
42
|
+
/** The current stage's step, already worded: `check · round 2 · 5/6 met`. */
|
|
43
|
+
step: string;
|
|
44
|
+
/** The last commit subject, shown only in the Details pane. */
|
|
45
|
+
subject: string | null;
|
|
34
46
|
stages: StageRow[];
|
|
35
|
-
handoffSteps: { name: string; at: number }[];
|
|
36
47
|
closePhases: PhaseRow[];
|
|
37
48
|
prNumber: number | null;
|
|
49
|
+
/** The PR's web address: the envelope's `pr.url`, else built from `github`. */
|
|
50
|
+
prUrl: string | null;
|
|
38
51
|
checksStatus: string | null;
|
|
39
52
|
/** The envelope's `elapsedSeconds`, for a finished result. */
|
|
40
53
|
elapsedSeconds: number | null;
|
|
41
54
|
/** Milliseconds into the current phase, while in flight. */
|
|
42
55
|
phaseElapsedMs: number | null;
|
|
43
|
-
/** The learned median of the current phase, once it has 3+ samples. */
|
|
56
|
+
/** The learned median of the current phase or stage, once it has 3+ samples. */
|
|
44
57
|
usualMs: number | null;
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
58
|
+
/** The close phase being timed, when the stage has one. */
|
|
59
|
+
phase: string | null;
|
|
60
|
+
/** Minutes the close-gates log has been quiet, while in close. */
|
|
61
|
+
quietMinutes: number | null;
|
|
62
|
+
/** The gate named by the close-gates log's last line, while in close. */
|
|
63
|
+
lastGate: string | null;
|
|
64
|
+
/** 1-based ids of the newest verdict round's criteria not `met`. */
|
|
65
|
+
unmet: number[];
|
|
48
66
|
/** `blocked.blockClass` or `failure.reason`. */
|
|
49
67
|
problem: string | null;
|
|
50
68
|
nextCommand: string | null;
|
|
@@ -52,12 +70,33 @@ export type Focus = {
|
|
|
52
70
|
followUps: number | null;
|
|
53
71
|
};
|
|
54
72
|
|
|
73
|
+
/** How one ledger Story reads as a run chip. */
|
|
74
|
+
export type ChipState =
|
|
75
|
+
| 'landed'
|
|
76
|
+
| 'needs-you'
|
|
77
|
+
| 'failed'
|
|
78
|
+
| 'focus'
|
|
79
|
+
| 'in-flight'
|
|
80
|
+
| 'undispatched';
|
|
81
|
+
|
|
82
|
+
/** A Story that ended without landing, named by the run roll-up. */
|
|
83
|
+
export type Straggler = {
|
|
84
|
+
storyId: number;
|
|
85
|
+
attention: 'needs-you' | 'failed';
|
|
86
|
+
/** The envelope's `phase`: where it stopped. */
|
|
87
|
+
phase: string | null;
|
|
88
|
+
};
|
|
89
|
+
|
|
55
90
|
/** The newest live multi-Story run ledger. */
|
|
56
91
|
export type RunLine = {
|
|
57
92
|
landed: number;
|
|
58
93
|
total: number;
|
|
59
|
-
|
|
60
|
-
|
|
94
|
+
chips: { storyId: number; state: ChipState }[];
|
|
95
|
+
/** True once every ledger Story has a terminal envelope. */
|
|
96
|
+
isDone: boolean;
|
|
97
|
+
/** From the earliest start to the newest result, once done. */
|
|
98
|
+
spanMs: number | null;
|
|
99
|
+
straggler: Straggler | null;
|
|
61
100
|
};
|
|
62
101
|
|
|
63
102
|
export type Snapshot = {
|
|
@@ -74,17 +113,23 @@ export type Learned = {
|
|
|
74
113
|
phases: Record<string, { medianSeconds: number; samples: number }>;
|
|
75
114
|
};
|
|
76
115
|
|
|
116
|
+
/** The followed Story and stage of the last scan, to see a stage finish. */
|
|
117
|
+
export type Tracked = { storyId: number; stage: StageName };
|
|
118
|
+
|
|
77
119
|
declare module 'claude-code' {
|
|
78
120
|
interface PluginState {
|
|
79
121
|
'mandrel-status': {
|
|
80
122
|
snapshot: Snapshot;
|
|
81
|
-
/** `<storyId
|
|
123
|
+
/** Envelope keys and `<storyId>:slow` of everything already toasted or recorded. */
|
|
82
124
|
seen: string[];
|
|
83
|
-
/** False until the first scan, which records
|
|
125
|
+
/** False until the first scan, which records without a toast. */
|
|
84
126
|
isSeeded: boolean;
|
|
85
127
|
learned: Learned;
|
|
86
|
-
/**
|
|
87
|
-
|
|
128
|
+
/** Durations in seconds of finished stages this mod watched, newest 30 each. */
|
|
129
|
+
stageSamples: Partial<Record<StageName, number[]>>;
|
|
130
|
+
tracked: Tracked | null;
|
|
131
|
+
/** `<band key>:<attention>` the person hid; any change shows the band again. */
|
|
132
|
+
hiddenFor: string | null;
|
|
88
133
|
};
|
|
89
134
|
}
|
|
90
135
|
}
|
|
@@ -77,10 +77,10 @@
|
|
|
77
77
|
},
|
|
78
78
|
"gates": {
|
|
79
79
|
"type": "object",
|
|
80
|
-
"description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran.",
|
|
80
|
+
"description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran. \"degraded\" (codeReview only, Story #5663) means a review surface ran but produced no verdict (CLI not logged in, out of quota, unparseable output); it is reported, not blocking, and ranks below \"overridden\".",
|
|
81
81
|
"additionalProperties": {
|
|
82
82
|
"type": "string",
|
|
83
|
-
"enum": ["passed", "failed", "skipped", "overridden"]
|
|
83
|
+
"enum": ["passed", "failed", "skipped", "overridden", "degraded"]
|
|
84
84
|
}
|
|
85
85
|
},
|
|
86
86
|
"tail": {
|
|
@@ -12,6 +12,9 @@
|
|
|
12
12
|
* trees whose Story is closed or `agent::done` are removed; an open Story's
|
|
13
13
|
* tree and the tree this process runs from are never touched.
|
|
14
14
|
*
|
|
15
|
+
* Then it flips closed Stories stranded at `agent::closing` to
|
|
16
|
+
* `agent::done` (`closingReconcile`).
|
|
17
|
+
*
|
|
15
18
|
* `content-merged` branches (merge-tree equivalence — no merge check ever
|
|
16
19
|
* validated their exact diff) are never reaped here, only reported for
|
|
17
20
|
* `/clean-git`.
|
|
@@ -26,6 +29,7 @@ import { Logger } from './lib/Logger.js';
|
|
|
26
29
|
import { sweepStaleStoryWorktrees } from './lib/orchestration/plan-runner/worktree-sweep.js';
|
|
27
30
|
import { createProvider } from './lib/provider-factory.js';
|
|
28
31
|
import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
|
|
32
|
+
import { reconcileStrandedClosing } from './lib/single-story-sweep/reconcile-closing.js';
|
|
29
33
|
import {
|
|
30
34
|
acquireSweepLock,
|
|
31
35
|
resolveSweepLockPath,
|
|
@@ -58,6 +62,9 @@ worktree, still-open parent Story), then fast-forwards the base branch.
|
|
|
58
62
|
Then removes every .worktrees/story-<id> tree whose Story is closed or
|
|
59
63
|
agent::done (never an open Story's, never the tree this process runs from);
|
|
60
64
|
the outcome lands under "worktreeSweep".
|
|
65
|
+
Then flips closed Stories still labelled agent::closing whose story-<id> PR
|
|
66
|
+
is MERGED to agent::done (at most 10 per run); the outcome lands under
|
|
67
|
+
"closingReconcile".
|
|
61
68
|
Branches detected only via the weaker content-equivalence signal
|
|
62
69
|
(detectedBy: 'content-merged') are never reaped here — they are reported
|
|
63
70
|
under "contentMerged" (and a routing hint in the summary line) for the
|
|
@@ -145,10 +152,11 @@ export async function runWorktreeSweep({
|
|
|
145
152
|
* worktreeSweepFn?: Function,
|
|
146
153
|
* acquireLockFn?: Function,
|
|
147
154
|
* purgeFn?: Function,
|
|
155
|
+
* closingReconcileFn?: Function,
|
|
148
156
|
* logger?: { info?: Function, warn?: Function },
|
|
149
157
|
* }} [args]
|
|
150
158
|
* @returns {Promise<object>} the {@link sweepMergedBranches} envelope plus
|
|
151
|
-
* `worktreeSweep` and `tempPurge`.
|
|
159
|
+
* `worktreeSweep`, `closingReconcile` and `tempPurge`.
|
|
152
160
|
*/
|
|
153
161
|
export async function runBootSweep({
|
|
154
162
|
cwd,
|
|
@@ -163,6 +171,7 @@ export async function runBootSweep({
|
|
|
163
171
|
worktreeSweepFn = sweepStaleStoryWorktrees,
|
|
164
172
|
acquireLockFn = acquireSweepLock,
|
|
165
173
|
purgeFn = sweepTempRetention,
|
|
174
|
+
closingReconcileFn = reconcileStrandedClosing,
|
|
166
175
|
logger = Logger,
|
|
167
176
|
} = {}) {
|
|
168
177
|
const root = path.resolve(cwd ?? PROJECT_ROOT);
|
|
@@ -213,6 +222,16 @@ export async function runBootSweep({
|
|
|
213
222
|
logger,
|
|
214
223
|
});
|
|
215
224
|
|
|
225
|
+
const closingReconcile = await closingReconcileFn({
|
|
226
|
+
provider,
|
|
227
|
+
config,
|
|
228
|
+
cwd: root,
|
|
229
|
+
logger: {
|
|
230
|
+
info: (m) => logger.info?.(`[boot-sweep] ${m}`),
|
|
231
|
+
warn: (m) => logger.warn?.(`[boot-sweep] ${m}`),
|
|
232
|
+
},
|
|
233
|
+
});
|
|
234
|
+
|
|
216
235
|
// Temp-retention catch-up: reaped branches are confirmed merges, so their
|
|
217
236
|
// artifacts are spent; the age floor collects the rest.
|
|
218
237
|
const purge = await purgeFn({
|
|
@@ -221,7 +240,7 @@ export async function runBootSweep({
|
|
|
221
240
|
label: 'boot-sweep',
|
|
222
241
|
logger,
|
|
223
242
|
});
|
|
224
|
-
return { ...result, worktreeSweep, tempPurge: purge };
|
|
243
|
+
return { ...result, worktreeSweep, closingReconcile, tempPurge: purge };
|
|
225
244
|
} catch (err) {
|
|
226
245
|
const msg = err?.message ?? String(err);
|
|
227
246
|
logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
|
|
@@ -239,6 +258,12 @@ export async function runBootSweep({
|
|
|
239
258
|
}
|
|
240
259
|
}
|
|
241
260
|
|
|
261
|
+
/** `; <text>` for a nonzero count, else nothing. */
|
|
262
|
+
function countSuffix(list, render) {
|
|
263
|
+
const count = list?.length ?? 0;
|
|
264
|
+
return count > 0 ? `; ${render(count)}` : '';
|
|
265
|
+
}
|
|
266
|
+
|
|
242
267
|
/**
|
|
243
268
|
* One-line summary; a nonzero `contentMerged` count adds a `/clean-git` hint.
|
|
244
269
|
*
|
|
@@ -247,17 +272,21 @@ export async function runBootSweep({
|
|
|
247
272
|
*/
|
|
248
273
|
export function buildSummaryLine(result) {
|
|
249
274
|
const protectedCount = result.protected?.length ?? 0;
|
|
250
|
-
const
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
275
|
+
const suffixes = [
|
|
276
|
+
countSuffix(
|
|
277
|
+
result.worktreeSweep?.reaped,
|
|
278
|
+
(n) => `removed ${n} closed-Story worktree(s)`,
|
|
279
|
+
),
|
|
280
|
+
countSuffix(
|
|
281
|
+
result.closingReconcile?.reconciled,
|
|
282
|
+
(n) => `flipped ${n} stranded agent::closing Story(ies) to agent::done`,
|
|
283
|
+
),
|
|
284
|
+
countSuffix(
|
|
285
|
+
result.contentMerged,
|
|
286
|
+
(n) => `${n} content-merged branch(es) left for /clean-git`,
|
|
287
|
+
),
|
|
288
|
+
].join('');
|
|
289
|
+
return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${suffixes}.`;
|
|
261
290
|
}
|
|
262
291
|
|
|
263
292
|
/**
|
|
@@ -107,6 +107,7 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
|
|
|
107
107
|
const locked = lockedCapture(runCaptureImpl, config, env, {
|
|
108
108
|
rerunCommand: rerunCommandFor(argv),
|
|
109
109
|
onLockOutcome: lockHooks.onLockOutcome,
|
|
110
|
+
onLockProgress: lockHooks.onLockProgress,
|
|
110
111
|
...lockOptions,
|
|
111
112
|
});
|
|
112
113
|
const credited = creditedCapture(locked, {
|
|
@@ -77,6 +77,20 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
|
|
|
77
77
|
'writes only `.claude/commands/<name>.md` — there is no plugin manifest and no',
|
|
78
78
|
'marketplace listing. The commands load in every Claude Code environment.',
|
|
79
79
|
'',
|
|
80
|
+
'**Codex.** The same sync also writes one Codex skill per command to',
|
|
81
|
+
'`.agents/skills/workflows/<name>/SKILL.md`, invoked as `$<name>` (e.g.',
|
|
82
|
+
'`$mandrel-plan`; loop units as `$loops-<name>`). Each skill points Codex at',
|
|
83
|
+
'the workflow file and passes the text after `$<name>` as its arguments.',
|
|
84
|
+
'`npm run sync:agents` likewise writes the role agents a workflow dispatches',
|
|
85
|
+
'(`subagent_type: <role>`) as Codex custom agents',
|
|
86
|
+
'`.codex/agents/mandrel-<role>.toml`; Codex loads those only in a trusted',
|
|
87
|
+
'project. `mandrel doctor` checks both projections',
|
|
88
|
+
'(`codex-skills-in-sync`, `codex-agents-in-sync`) and that Codex reads the',
|
|
89
|
+
'Mandrel block of `AGENTS.md` (`codex-instructions`). To refresh only the',
|
|
90
|
+
'Codex half, run `node .agents/scripts/sync-codex-skills.js` or',
|
|
91
|
+
'`node .agents/scripts/sync-codex-agents.js`. Setup: the',
|
|
92
|
+
'[`.agents/README.md`](../README.md#running-mandrel-from-codex) Codex section.',
|
|
93
|
+
'',
|
|
80
94
|
'Loop units are the one namespaced exception: files under',
|
|
81
95
|
'`.agents/workflows/loops/<name>.md` project to',
|
|
82
96
|
'`.claude/commands/loops/<name>.md` and are invoked as the namespaced',
|
|
@@ -11,8 +11,24 @@ import path from 'node:path';
|
|
|
11
11
|
/** Entry-doc wiring keys idempotence off this exact import path. */
|
|
12
12
|
export const SYSTEM_PROMPT_IMPORT = '@.agents/instructions.md';
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Prose twin of the import for hosts that load AGENTS.md but expand no `@`
|
|
16
|
+
* imports (Codex). The doctor's `codex-instructions` check locates the block
|
|
17
|
+
* by this exact line, so it stays one line.
|
|
18
|
+
*/
|
|
19
|
+
export const SYSTEM_PROMPT_READ_DIRECTIVE =
|
|
20
|
+
'Hosts that do not expand `@` imports (Codex): before any task, read `.agents/instructions.md`, `.agents/rules/security-baseline.md` and `.agents/rules/git-conventions.md` in full and follow them.';
|
|
21
|
+
|
|
14
22
|
export const SYSTEM_PROMPT_BLOCK = `## System Prompt
|
|
15
23
|
|
|
24
|
+
${SYSTEM_PROMPT_IMPORT}
|
|
25
|
+
|
|
26
|
+
${SYSTEM_PROMPT_READ_DIRECTIVE}
|
|
27
|
+
`;
|
|
28
|
+
|
|
29
|
+
/** The pre-2.84.0 block, which carried the import alone. */
|
|
30
|
+
const LEGACY_SYSTEM_PROMPT_BLOCK = `## System Prompt
|
|
31
|
+
|
|
16
32
|
${SYSTEM_PROMPT_IMPORT}
|
|
17
33
|
`;
|
|
18
34
|
|
|
@@ -69,14 +85,86 @@ function foldEntryDocs({ claude, agents = null }) {
|
|
|
69
85
|
? `${withTrailingNewline(agents)}\n${claudeBody}`
|
|
70
86
|
: claudeBody;
|
|
71
87
|
const lines = dedupeImport(combined.split('\n'));
|
|
72
|
-
|
|
73
|
-
if (
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
88
|
+
const result = withTrailingNewline(lines.join('\n'));
|
|
89
|
+
if (lines.some((line) => line.trim() === SYSTEM_PROMPT_IMPORT)) return result;
|
|
90
|
+
return result.trim().length === 0
|
|
91
|
+
? SYSTEM_PROMPT_ENTRY_DOC
|
|
92
|
+
: insertSystemPromptBlock(result);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Place {@link SYSTEM_PROMPT_BLOCK} at the top of an entry doc — directly
|
|
97
|
+
* after a leading H1 when there is one. Codex stops reading AGENTS.md at
|
|
98
|
+
* `project_doc_max_bytes`, so an appended block in a long file never loads.
|
|
99
|
+
*
|
|
100
|
+
* @param {string} text - entry-doc content without the block.
|
|
101
|
+
* @returns {string}
|
|
102
|
+
*/
|
|
103
|
+
function insertSystemPromptBlock(text) {
|
|
104
|
+
const h1 = /^(?:[ \t]*\r?\n)*# [^\n]*\n?/.exec(text);
|
|
105
|
+
const head = h1 ? withTrailingNewline(h1[0].replace(/^\s+/, '')) : '';
|
|
106
|
+
const rest = text.slice(h1 ? h1[0].length : 0).replace(/^\s*\n/, '');
|
|
107
|
+
const lead = head ? `${head}\n` : '';
|
|
108
|
+
const tail = rest.length > 0 ? `\n${withTrailingNewline(rest)}` : '';
|
|
109
|
+
return `${lead}${SYSTEM_PROMPT_BLOCK}${tail}`;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Byte offset just past a leading H1 and its blank lines — where the block
|
|
114
|
+
* belongs.
|
|
115
|
+
*
|
|
116
|
+
* @param {string} text
|
|
117
|
+
* @returns {number}
|
|
118
|
+
*/
|
|
119
|
+
function topOffset(text) {
|
|
120
|
+
return /^(?:\s*\n)*(?:# [^\n]*\n(?:[ \t]*\n)*)?/.exec(text)[0].length;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Locate a recognizable Mandrel block (current or legacy shape).
|
|
125
|
+
*
|
|
126
|
+
* @param {string} text
|
|
127
|
+
* @returns {{ start: number, end: number, current: boolean } | null}
|
|
128
|
+
*/
|
|
129
|
+
function findSystemPromptBlock(text) {
|
|
130
|
+
for (const [block, current] of [
|
|
131
|
+
[SYSTEM_PROMPT_BLOCK, true],
|
|
132
|
+
[LEGACY_SYSTEM_PROMPT_BLOCK, false],
|
|
133
|
+
]) {
|
|
134
|
+
const start = text.indexOf(block);
|
|
135
|
+
if (start !== -1) return { start, end: start + block.length, current };
|
|
78
136
|
}
|
|
79
|
-
return
|
|
137
|
+
return null;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* True when an entry doc carries a recognizable Mandrel block that is not
|
|
142
|
+
* the current block at the top — the migration's `detect`.
|
|
143
|
+
*
|
|
144
|
+
* @param {string} text
|
|
145
|
+
* @returns {boolean}
|
|
146
|
+
*/
|
|
147
|
+
export function needsSystemPromptHoist(text) {
|
|
148
|
+
const found = findSystemPromptBlock(text);
|
|
149
|
+
if (!found) return false;
|
|
150
|
+
return !(found.current && found.start === topOffset(text));
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Move a recognizable block to the top, upgrading a legacy one. Text with no
|
|
155
|
+
* recognizable block (a hand-edited import) is returned unchanged.
|
|
156
|
+
*
|
|
157
|
+
* @param {string} text
|
|
158
|
+
* @returns {string}
|
|
159
|
+
*/
|
|
160
|
+
export function hoistSystemPromptBlock(text) {
|
|
161
|
+
if (!needsSystemPromptHoist(text)) return text;
|
|
162
|
+
const { start, end } = findSystemPromptBlock(text);
|
|
163
|
+
const without = `${text.slice(0, start)}${text.slice(end)}`.replace(
|
|
164
|
+
/\n{3,}/g,
|
|
165
|
+
'\n\n',
|
|
166
|
+
);
|
|
167
|
+
return insertSystemPromptBlock(without.replace(/\n+$/, '\n'));
|
|
80
168
|
}
|
|
81
169
|
|
|
82
170
|
/**
|
|
@@ -104,11 +192,11 @@ export function foldClaudeMdIntoAgentsMd(projectRoot, fsImpl = fs) {
|
|
|
104
192
|
|
|
105
193
|
/**
|
|
106
194
|
* Wire the system-prompt import into AGENTS.md, folding a CLAUDE.md in first.
|
|
107
|
-
* Creates, folds,
|
|
195
|
+
* Creates, folds, inserts the block at the top, or no-ops.
|
|
108
196
|
*
|
|
109
197
|
* @param {string} projectRoot
|
|
110
198
|
* @param {typeof fs} [fsImpl]
|
|
111
|
-
* @returns {{ action: 'created'|'folded'|'
|
|
199
|
+
* @returns {{ action: 'created'|'folded'|'inserted'|'already-present', path: string }}
|
|
112
200
|
*/
|
|
113
201
|
export function wireEntryDoc(projectRoot, fsImpl = fs) {
|
|
114
202
|
const folded = foldClaudeMdIntoAgentsMd(projectRoot, fsImpl);
|
|
@@ -122,13 +210,8 @@ export function wireEntryDoc(projectRoot, fsImpl = fs) {
|
|
|
122
210
|
if (existing.includes(SYSTEM_PROMPT_IMPORT)) {
|
|
123
211
|
return { action: 'already-present', path: target };
|
|
124
212
|
}
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
target,
|
|
128
|
-
`${existing}${separator}\n${SYSTEM_PROMPT_BLOCK}`,
|
|
129
|
-
'utf8',
|
|
130
|
-
);
|
|
131
|
-
return { action: 'appended', path: target };
|
|
213
|
+
fsImpl.writeFileSync(target, insertSystemPromptBlock(existing), 'utf8');
|
|
214
|
+
return { action: 'inserted', path: target };
|
|
132
215
|
}
|
|
133
216
|
|
|
134
217
|
/**
|
|
@@ -53,17 +53,17 @@ function ideWiringEntries() {
|
|
|
53
53
|
e(
|
|
54
54
|
rel('AGENTS.md'),
|
|
55
55
|
'merge',
|
|
56
|
-
'Wire the @.agents/instructions.md
|
|
56
|
+
'Wire the system-prompt block — the @.agents/instructions.md import plus a read directive for hosts without @-imports — at the top of AGENTS.md (folding any CLAUDE.md into it) so Claude Code and Codex both hydrate the framework on cold start.',
|
|
57
57
|
),
|
|
58
58
|
e(
|
|
59
59
|
rel('.claude', 'commands'),
|
|
60
60
|
'run',
|
|
61
|
-
'Generate the flat command surface (/<name>) from .agents/workflows/.',
|
|
61
|
+
'Generate the flat command surface (/<name>) and the Codex skills (.agents/skills/workflows/, invoked as $<name>) from .agents/workflows/.',
|
|
62
62
|
),
|
|
63
63
|
e(
|
|
64
64
|
rel('.gitignore'),
|
|
65
65
|
'merge',
|
|
66
|
-
'Ignore the .claude/commands/ and .
|
|
66
|
+
'Ignore the .claude/commands/, .claude/agents/, .agents/skills/workflows/ and .codex/agents/mandrel-*.toml projections (generated by prepare), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
|
|
67
67
|
),
|
|
68
68
|
];
|
|
69
69
|
}
|
|
@@ -81,7 +81,7 @@ function repoConfigEntries() {
|
|
|
81
81
|
e(
|
|
82
82
|
rel('package.json'),
|
|
83
83
|
'merge',
|
|
84
|
-
'Seed/merge the sync:commands, sync:agents, prepare, and bootstrap npm scripts. `prepare` is guarded: it exits 0 without writing when .agents/scripts/ is absent (a manifest-only container `npm ci`), and otherwise regenerates the .claude/commands/ and .
|
|
84
|
+
'Seed/merge the sync:commands, sync:agents, prepare, and bootstrap npm scripts. `prepare` is guarded: it exits 0 without writing when .agents/scripts/ is absent (a manifest-only container `npm ci`), and otherwise regenerates the Claude Code (.claude/commands/, .claude/agents/) and Codex (.agents/skills/workflows/, .codex/agents/mandrel-*.toml) projections — all gitignored.',
|
|
85
85
|
),
|
|
86
86
|
e(
|
|
87
87
|
rel('.agentrc.json'),
|
|
@@ -15,6 +15,7 @@ import {
|
|
|
15
15
|
SYSTEM_PROMPT_BLOCK,
|
|
16
16
|
SYSTEM_PROMPT_ENTRY_DOC,
|
|
17
17
|
SYSTEM_PROMPT_IMPORT,
|
|
18
|
+
SYSTEM_PROMPT_READ_DIRECTIVE,
|
|
18
19
|
wireEntryDoc,
|
|
19
20
|
} from './agents-md-fold.js';
|
|
20
21
|
import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
|
|
@@ -42,7 +43,11 @@ const PREPARE_GUARD = `node -e "process.exit(require('fs').existsSync('.agents/s
|
|
|
42
43
|
/** The `prepare` script bootstrap writes: guarded, then both projections. */
|
|
43
44
|
export const PREPARE_COMMAND = `${PREPARE_GUARD} || (${LEGACY_PREPARE_COMMAND})`;
|
|
44
45
|
|
|
45
|
-
export {
|
|
46
|
+
export {
|
|
47
|
+
SYSTEM_PROMPT_BLOCK,
|
|
48
|
+
SYSTEM_PROMPT_IMPORT,
|
|
49
|
+
SYSTEM_PROMPT_READ_DIRECTIVE,
|
|
50
|
+
};
|
|
46
51
|
|
|
47
52
|
/** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
|
|
48
53
|
export const SYSTEM_PROMPT_AGENTS_MD = SYSTEM_PROMPT_ENTRY_DOC;
|
|
@@ -58,6 +63,16 @@ export const GITIGNORE_BLOCKS = Object.freeze({
|
|
|
58
63
|
block:
|
|
59
64
|
'\n# Claude Code agent projection is generated from .agents/agents/ by `prepare` — do not commit.\n.claude/agents/\n',
|
|
60
65
|
},
|
|
66
|
+
codexSkills: {
|
|
67
|
+
pattern: /^\s*\/?\.agents\/skills\/workflows\/?\s*$/m,
|
|
68
|
+
block:
|
|
69
|
+
'\n# Codex skill projection is generated from .agents/workflows/ — do not commit.\n.agents/skills/workflows/\n',
|
|
70
|
+
},
|
|
71
|
+
codexAgents: {
|
|
72
|
+
pattern: /^\s*\/?\.codex\/agents\/mandrel-\*\.toml\s*$/m,
|
|
73
|
+
block:
|
|
74
|
+
'\n# Codex agent projection is generated from .agents/agents/ — do not commit.\n.codex/agents/mandrel-*.toml\n',
|
|
75
|
+
},
|
|
61
76
|
mcp: {
|
|
62
77
|
pattern: /^\s*\.mcp\.json\s*$/m,
|
|
63
78
|
block:
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* (never gate output, which tests can forge). A child claims
|
|
4
|
-
* before spawning, so no suite process can write to it.
|
|
2
|
+
* Lock-wait, suite-timing and live lock-progress events, as NDJSON in a
|
|
3
|
+
* per-run file (never gate output, which tests can forge). A child claims
|
|
4
|
+
* the env var before spawning, so no suite process can write to it.
|
|
5
5
|
*/
|
|
6
6
|
import crypto from 'node:crypto';
|
|
7
7
|
import fs from 'node:fs';
|
|
@@ -10,7 +10,7 @@ import path from 'node:path';
|
|
|
10
10
|
|
|
11
11
|
const CLOSE_LOCK_EVENTS_FILE_ENV = 'MANDREL_CLOSE_LOCK_EVENTS_FILE';
|
|
12
12
|
|
|
13
|
-
const EVENT_KINDS = new Set(['lock-wait', 'suite-timings']);
|
|
13
|
+
const EVENT_KINDS = new Set(['lock-wait', 'suite-timings', 'lock-progress']);
|
|
14
14
|
|
|
15
15
|
function appendEvent(file, event, fsImpl) {
|
|
16
16
|
try {
|
|
@@ -39,6 +39,7 @@ export function createLockEventChannel({
|
|
|
39
39
|
env: { [CLOSE_LOCK_EVENTS_FILE_ENV]: file },
|
|
40
40
|
emit: (event) => appendEvent(file, event, fsImpl),
|
|
41
41
|
read: () => readEvents(file, fsImpl),
|
|
42
|
+
drain: createDrain(file, fsImpl),
|
|
42
43
|
dispose() {
|
|
43
44
|
try {
|
|
44
45
|
fsImpl.rmSync(file, { force: true });
|
|
@@ -47,16 +48,34 @@ export function createLockEventChannel({
|
|
|
47
48
|
};
|
|
48
49
|
}
|
|
49
50
|
|
|
50
|
-
function
|
|
51
|
-
let text;
|
|
51
|
+
function readText(file, fsImpl) {
|
|
52
52
|
try {
|
|
53
|
-
|
|
53
|
+
return fsImpl.readFileSync(file, 'utf8');
|
|
54
54
|
} catch {
|
|
55
|
-
return
|
|
55
|
+
return '';
|
|
56
56
|
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function parseEvents(text) {
|
|
57
60
|
return text.split('\n').filter(Boolean).map(parseEventLine).filter(Boolean);
|
|
58
61
|
}
|
|
59
62
|
|
|
63
|
+
function readEvents(file, fsImpl) {
|
|
64
|
+
return parseEvents(readText(file, fsImpl));
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Each call returns only complete lines appended since the last one. */
|
|
68
|
+
function createDrain(file, fsImpl) {
|
|
69
|
+
let consumed = 0;
|
|
70
|
+
return () => {
|
|
71
|
+
const text = readText(file, fsImpl);
|
|
72
|
+
const end = Math.max(consumed, text.lastIndexOf('\n') + 1);
|
|
73
|
+
const fresh = text.slice(consumed, end);
|
|
74
|
+
consumed = end;
|
|
75
|
+
return parseEvents(fresh);
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
|
|
60
79
|
/**
|
|
61
80
|
* Remove the channel from `env` and return its emitter (a no-op without one).
|
|
62
81
|
*
|
|
@@ -80,7 +99,7 @@ export function claimLockEventSink(env = process.env, { fsImpl = fs } = {}) {
|
|
|
80
99
|
export function summarizeLockEvents(events) {
|
|
81
100
|
let lockWait = null;
|
|
82
101
|
let suiteTimings = null;
|
|
83
|
-
for (const event of events) {
|
|
102
|
+
for (const event of events.filter((e) => e.kind !== 'lock-progress')) {
|
|
84
103
|
if (event.kind === 'lock-wait') lockWait = mergeLockWait(lockWait, event);
|
|
85
104
|
else suiteTimings = timingsOf(event);
|
|
86
105
|
}
|
|
@@ -104,6 +123,7 @@ function timingsOf({ lockWaitMs, hostWaitMs, testRunMs }) {
|
|
|
104
123
|
export function lockEventHooks(emit) {
|
|
105
124
|
return {
|
|
106
125
|
onLockOutcome: (outcome) => emit({ kind: 'lock-wait', ...outcome }),
|
|
126
|
+
onLockProgress: (progress) => emit({ kind: 'lock-progress', ...progress }),
|
|
107
127
|
onTimings: (timings) => emit({ kind: 'suite-timings', ...timings }),
|
|
108
128
|
};
|
|
109
129
|
}
|