dorfl 0.0.0 → 0.1.0

package/dist/workspace.js

@@ -0,0 +1,325 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { git } from './git.js';
+import { encodeRepoKey, ensureMirror, } from './repo-mirror.js';
+import { branchAheadOfArbiter, rebaseContinuedBranchOntoMain, pushContinuedBranchWithStaleLeaseRetry, } from './continue-branch.js';
+import { brand } from './brand.js';
+import { workBranchRef } from './slug-namespace.js';
+/**
+ * Encode a flat, deterministic, unique-per-claim **work-id** from the arbiter
+ * URL + slug: the hierarchical repo key with its `/` separators flattened to
+ * `__`, then `__<slug>` appended (ADR §2). Flat (not hierarchical) so listing /
+ * counting / GC of jobs is a flat `ls`. Reuses the `repo-mirror` repo→key
+ * encoding (dot→dash per segment) — it does NOT duplicate it.
+ *
+ * E.g. `git@github.com:wighawag/dorfl.git` + `feat`
+ *   → `github-com__wighawag__dorfl__feat`.
+ */
+export function encodeWorkId(url, slug) {
+    const key = encodeRepoKey(url).split('/').join('__');
+    return `${key}__${slug}`;
+}
+/**
+ * The on-disk location of a job's worktree: `<workspacesDir>/work/<work-id>/`.
+ * Flat, OUTSIDE the hub (`<workspacesDir>/repos/...`), under `workspacesDir`
+ * (default `~/.dorfl`), never `~/.cache` (ADR §3).
+ */
+export function jobWorktreePath(workspacesDir, url, slug) {
+    return join(workspacesDir, 'work', encodeWorkId(url, slug));
+}
+/** Filename of the per-job record. Derived from the single brand identity
+ * (`.{base}-job.json`) so a rename flips it in lockstep.
+ *
+ * HISTORICAL: this used to be the name of a file written INSIDE the job worktree
+ * (`<work-id>/.dorfl-job.json`). That in-tree location was the mistake —
+ * a runtime control file inside the checked-out worktree got swept onto the work
+ * branch by the runner's broad `git add -A` commits (and once WEDGED a
+ * continue-rebase `git switch`). The record now lives at a SIBLING path OUTSIDE
+ * the worktree ({@link jobRecordPath}); this constant survives only as the
+ * legacy in-tree read-fallback name + as the no-op-build / clean-worktree
+ * classification token in `agent-stop.ts`/`gc.ts` (now inert — the record can no
+ * longer appear in `git status`). */
+export const JOB_RECORD_FILENAME = brand.jobRecordFilename;
+/**
+ * The on-disk location of a job's state record: a SIBLING of its worktree dir,
+ * `<workspacesDir>/work/<work-id>.json` (NEXT TO `<workspacesDir>/work/<work-id>/`,
+ * NOT inside it).
+ *
+ * This is the structural fix for the in-tree leak: the record is still under the
+ * same `workspacesDir/work/` control area (so `discoverJobs`'s single-directory
+ * walk still finds it), but it is PHYSICALLY OUTSIDE the checked-out git
+ * worktree, so the runner's broad `git add -A` commits can NEVER stage it — in
+ * ANY repo, with no `.gitignore` entry needed. A `<work-id>.json` file name can
+ * never collide with the `<work-id>/` worktree DIR (one carries a `.json`
+ * extension, the other does not).
+ *
+ * Derived purely from the worktree `dir` (sibling = `<dir>.json`) so every
+ * existing caller that holds a worktree dir keeps the same `(dir, …)` signature.
+ */
+export function jobRecordPath(dir) {
+    return join(dirname(dir), `${basename(dir)}.json`);
+}
+/** The LEGACY in-tree record path (`<dir>/.dorfl-job.json`) for the
+ * read-fallback below — a job worktree materialised by an OLD binary still has
+ * its record here. */
+function legacyJobRecordPath(dir) {
+    return join(dir, JOB_RECORD_FILENAME);
+}
+const DEFAULT_HARNESS = { adapter: 'null' };
+/**
+ * Create (or recreate) a job: ensure the hub mirror via `repo-mirror`, then
+ * `git worktree add` a per-job worktree OUTSIDE the hub at
+ * `<workspacesDir>/work/<work-id>/` on `work/<slug>`, branched off the
+ * freshly-fetched `<hub>/main`. Writes the per-job record at a SIBLING of the
+ * worktree (`<work-id>.json`, OUTSIDE the tree — {@link jobRecordPath}).
+ *
+ * Distinct slugs ⇒ distinct `work/<slug>` branches, so git's one-branch-per-
+ * worktree constraint is naturally avoided (ADR §2). If a stale worktree/branch
+ * for this work-id already exists it is cleared first (idempotent re-create).
+ */
+export function createJob(options) {
+    const env = options.env;
+    const mirror = ensureMirror({
+        url: options.url,
+        fromRepo: options.fromRepo,
+        arbiter: options.arbiter,
+        workspacesDir: options.workspacesDir,
+        env,
+    });
+    const slug = options.slug;
+    const branch = workBranchRef(options.type ?? 'task', slug);
+    const dir = jobWorktreePath(options.workspacesDir, mirror.url, slug);
+    // CONTINUE-detection (shared with the in-place path, ADR §14 keystone): after
+    // `ensureMirror`'s mirror-style fetch (`+refs/heads/*:refs/heads/*`), a kept
+    // arbiter `work/<slug>` lands as a LOCAL head `work/<slug>` in the bare mirror.
+    // If it is AHEAD of `main` (a requeue kept it), CONTINUE from it; otherwise cut
+    // FRESH off main (the common case — a first attempt, or `requeue --reset` deleted
+    // it).
+    // ARBITER-AUTHORITATIVE continue-detection: `ls-remote` the arbiter (the
+    // mirror's `origin`) so an orphaned local head/tracking-ref in the bare hub
+    // mirror — e.g. a `refs/remotes/origin/work/<slug>` in the namespace no
+    // `remote.origin.fetch` refspec prunes, or a `refs/heads/work/<slug>` that
+    // `ensureMirror`'s `--prune` could not reach — cannot resurrect a branch the
+    // arbiter no longer has (e.g. a cross-machine `gc --remote-branches` delete).
+    const continueFromKept = branchAheadOfArbiter({
+        cwd: mirror.path,
+        arbiterRemote: 'origin',
+        branch,
+        branchRef: branch,
+        mainRef: 'main',
+        env,
+    });
+    let continued = false;
+    let continueRebaseConflict = false;
+    let continuePushFailure;
+    if (continueFromKept) {
+        // The arbiter `work/<slug>` tip the mirror fetched, READ BEFORE the onboard
+        // rebase rewrites the local branch — the value the --force-with-lease push
+        // expects the arbiter to still hold. A requeue-continue can CHURN this ref
+        // after the mirror fetch, making the lease stale; the retry below re-leases
+        // against the freshly-fetched tip (the WORK branch is unshared, so re-observing
+        // + replaying is correct).
+        const expectedRemoteTip = git(['rev-parse', branch], mirror.path, {
+            env,
+        }).trim();
+        // Clear ONLY a stale worktree DIR (never the branch we are continuing), then
+        // cut the worktree FROM the kept branch (not fresh off main).
+        clearStaleWorktreeOnly(mirror.path, dir, env);
+        git(['worktree', 'add', dir, branch], mirror.path, { env });
+        continued = true;
+        // REBASE the continued branch onto the freshly-fetched mirror main at
+        // onboard-time (ADR §10: rebase, not merge) so the agent builds on a CURRENT
+        // base. A CLEAN rebase → update the already-pushed arbiter tip with
+        // --force-with-lease on the WORK branch ONLY (a requeued item is unshared) —
+        // NEVER --force, NEVER to main (§11). A CONFLICT → aborted (never
+        // auto-resolved) + flagged so the caller routes to needs-attention.
+        const rebase = rebaseContinuedBranchOntoMain(dir, 'main', env);
+        if (rebase.kind === 'conflict') {
+            continueRebaseConflict = true;
+        }
+        else {
+            // Push the rebased tip with --force-with-lease, SURVIVING a stale-lease
+            // ("stale info") rejection: re-fetch the arbiter `work/<slug>` + main,
+            // re-rebase onto current main, and retry (bounded) instead of stranding the
+            // committed green work in the worktree. A rebase CONFLICT on a retry is the
+            // SAME abort → needs-attention path (never auto-resolved).
+            //
+            // The helper THROWS on a terminal failure (the stale-lease retry cap, or a
+            // non-stale-lease rejection / unreachable arbiter). BEFORE this task that
+            // throw ESCAPED `createJob` uncaught, crashing the run and leaving the
+            // already-committed kept work silently in `work/in-progress/` on the arbiter
+            // (the stale-lease-strand incident). We now CATCH it and flag
+            // `continuePushFailure` so the caller (`runRemotePipeline`) routes the item
+            // to needs-attention — the kept work stays committed + recoverable on the
+            // branch — instead of stranding it.
+            try {
+                const pushed = pushContinuedBranchWithStaleLeaseRetry({
+                    cwd: dir,
+                    branch,
+                    arbiter: 'origin',
+                    mainRef: 'main',
+                    expectedRemoteTip,
+                    env,
+                });
+                if (pushed.kind === 'conflict') {
+                    continueRebaseConflict = true;
+                }
+            }
+            catch (err) {
+                continuePushFailure = err instanceof Error ? err.message : String(err);
+            }
+        }
+    }
+    else {
+        // Clear any stale registration for this work-id (idempotent re-create): a
+        // leftover worktree dir or branch from a prior crashed run would block the
+        // `worktree add`. We use git's own removal, never a bare rm -rf (ADR §4).
+        clearStale(mirror.path, dir, branch, env);
+        // Cut the worktree OUTSIDE the hub, on a fresh per-slug branch off the
+        // freshly-fetched mirror main. `--force` is not used: the branch is unique.
+        git(['worktree', 'add', '-b', branch, dir, 'main'], mirror.path, { env });
+    }
+    const record = {
+        slug,
+        repoKey: encodeRepoKey(mirror.url),
+        branch,
+        startedAt: new Date().toISOString(),
+        state: 'running',
+        harness: options.harness ?? DEFAULT_HARNESS,
+    };
+    const recordPath = jobRecordPath(dir);
+    writeJobRecord(dir, record);
+    return {
+        dir,
+        branch,
+        slug,
+        arbiterRemote: 'origin',
+        recordPath,
+        record,
+        mirror,
+        continued,
+        continueRebaseConflict,
+        continuePushFailure,
+        dispose() {
+            git(['worktree', 'remove', '--force', dir], mirror.path, { env });
+            removeJobRecord(dir);
+            pruneAndDropBranch(mirror.path, branch, env);
+        },
+    };
+}
+/**
+ * Write (or overwrite) a job's record to its SIBLING path ({@link jobRecordPath},
+ * `<work-id>.json` next to the worktree), OUTSIDE the checked-out tree. `dir` is
+ * the worktree dir, kept as the parameter so every caller is unchanged.
+ */
+export function writeJobRecord(dir, record) {
+    writeFileSync(jobRecordPath(dir), JSON.stringify(record, null, 2) + '\n');
+}
+/**
+ * Read a job's record given its worktree `dir`, or `undefined` if absent/invalid.
+ *
+ * Reads the NEW sibling location ({@link jobRecordPath}) first, then falls back
+ * to the LEGACY in-tree location (`<dir>/.dorfl-job.json`) so a job
+ * worktree materialised by an OLD binary (record still inside the tree) stays
+ * discoverable/reapable until it is torn down. New jobs only ever write the
+ * sibling path, so the fallback is purely for in-flight migration.
+ */
+export function readJobRecord(dir) {
+    for (const path of [jobRecordPath(dir), legacyJobRecordPath(dir)]) {
+        if (!existsSync(path)) {
+            continue;
+        }
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Delete a job's record on teardown — BOTH the new sibling path
+ * ({@link jobRecordPath}) and the legacy in-tree path (an old-binary worktree).
+ * Best-effort + idempotent (a missing file is fine). Called when a worktree is
+ * removed (reaped / disposed / cleared) so the relocated record does not outlive
+ * its worktree as an orphan `<work-id>.json` (when the record lived INSIDE the
+ * worktree it was deleted WITH it by `git worktree remove`; now that it is a
+ * sibling, its teardown must be explicit).
+ */
+export function removeJobRecord(dir) {
+    for (const path of [jobRecordPath(dir), legacyJobRecordPath(dir)]) {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            // best-effort: an unremovable orphan record is harmless (discovery
+            // keys on the worktree DIR, which is gone).
+        }
+    }
+}
+/**
+ * Update a job's record in place (e.g. flip `state` to `needs-attention` after a
+ * rebase conflict), merging the patch over the on-disk record. A no-op if no
+ * record exists.
+ */
+export function updateJobRecord(dir, patch) {
+    const current = readJobRecord(dir);
+    if (!current) {
+        return undefined;
+    }
+    const next = { ...current, ...patch };
+    writeJobRecord(dir, next);
+    return next;
+}
+/** Remove a stale worktree dir / branch registration before re-creating. */
+function clearStale(mirrorPath, dir, branch, env) {
+    if (existsSync(dir)) {
+        // Soft-remove: ignore errors (e.g. the dir is not a registered worktree).
+        try {
+            git(['worktree', 'remove', '--force', dir], mirrorPath, { env });
+        }
+        catch {
+            // fall through to prune below
+        }
+    }
+    pruneAndDropBranch(mirrorPath, branch, env);
+}
+/**
+ * Clear ONLY a stale worktree DIR (and prune dangling registrations) — WITHOUT
+ * dropping the branch. Used on the CONTINUE path so the kept `work/<slug>`
+ * branch (the durable requeue artifact) is NEVER nuked while a leftover worktree
+ * dir from a prior crashed attempt is still cleared so `worktree add` succeeds.
+ */
+function clearStaleWorktreeOnly(mirrorPath, dir, env) {
+    if (existsSync(dir)) {
+        try {
+            git(['worktree', 'remove', '--force', dir], mirrorPath, { env });
+        }
+        catch {
+            // fall through to prune below
+        }
+    }
+    try {
+        git(['worktree', 'prune'], mirrorPath, { env });
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Prune dangling worktree registrations + delete the work branch if present. */
+function pruneAndDropBranch(mirrorPath, branch, env) {
+    try {
+        git(['worktree', 'prune'], mirrorPath, { env });
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        git(['branch', '-D', branch], mirrorPath, { env });
+    }
+    catch {
+        // branch may not exist
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,4 +1,48 @@
 {
   "name": "dorfl",
-  "version": "0.0.0"
-}
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wighawag/dorfl.git",
+    "directory": "packages/dorfl"
+  },
+  "homepage": "https://github.com/wighawag/dorfl#readme",
+  "bugs": "https://github.com/wighawag/dorfl/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "dorfl": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^14.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "as-soon": "^0.1.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/vendor-protocol.mjs",
+    "dev": "as-soon -w src pnpm build",
+    "cli": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/advance-ci-template.ts

@@ -0,0 +1,203 @@
+import {existsSync, readFileSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/**
+ * The CI-integration deliverable for the `advance` loop (prd `advance-loop`,
+ * task `advance-install-ci`, US #27/28): the advance-loop CAPABILITY as a
+ * DOCUMENTED workflow TEMPLATE (not a CLI subcommand; see the task's `##
+ * Decisions`). The template at `docs/ci/advance-loop.yml.template` wires "on cron
+ * / on-answer-committed, run the RIGHT shape" and only INVOKES the existing
+ * `advance` driver; it is NOT entangled with the tick.
+ *
+ * The unified, per-capability `install-ci` CLI (auth/secrets wizard + GitHub
+ * adapter) is owned by the separate `runner-in-ci` prd
+ * (`work/prds/tasked/runner-in-ci.md`); when built it EMITS this template as its
+ * advance-loop capability. This module's job is unchanged either way: locate +
+ * STRUCTURALLY VALIDATE the template, so its shape is a contract the CLI can
+ * safely emit (see `docs/ci/README.md` "Relationship to the `install-ci` CLI").
+ *
+ * This module locates + reads that template and STRUCTURALLY VALIDATES it. The
+ * package depends on NO YAML library (see `frontmatter.ts` for the same
+ * constraint), so {@link validateAdvanceCiTemplate} checks the small set of
+ * invariants the task's acceptance criteria require directly:
+ *
+ *   - triggers on a CRON schedule AND on-answer-committed (a push touching
+ *     `work/questions/**`);
+ *   - `propose` mode → a MATRIX of independent jobs enumerated via the
+ *     mirror-side pool scan (`dorfl scan --json`), one `advance … --propose`
+ *     per item (the `--propose` flag TIES the integration mode to the matrix shape,
+ *     so a leg can never merge to main);
+ *   - `merge` mode → a MATRIX of independent jobs (one per item), each leg
+ *     running `dorfl advance <item> --merge` so build/gate/review run
+ *     concurrently across siblings; the LAND TAIL is serialised by the engine's
+ *     `mergeRetries` CAS-retry loop (the git-alone floor), NOT by this
+ *     workflow's job shape — a host-specific `concurrency:` group would be
+ *     load-bearing for safety, which the floor framing forbids;
+ *   - the dispatch input is `integrationMode` (ONE word, ONE meaning): it drives
+ *     BOTH the integration flag the legs pass AND the job shape, so they cannot
+ *     desync;
+ *   - it references the EXISTING `advance` driver only (no new execution model);
+ *   - it is a `.template` (so it never self-triggers in THIS repo).
+ *
+ * The check is deliberately a set of presence/shape assertions over the raw text
+ * rather than a full YAML parse — it is the dependency-free counterpart of "the
+ * template parses + references the right driver invocations" the task asks for.
+ */
+
+/** A single structural problem found in the template. */
+export interface AdvanceCiTemplateProblem {
+	/** A short, stable id for the violated invariant (for tests/assertions). */
+	id: string;
+	/** Human-readable description of what is missing or wrong. */
+	message: string;
+}
+
+/** The result of {@link validateAdvanceCiTemplate}. */
+export interface AdvanceCiTemplateValidation {
+	/** True iff the template satisfies EVERY structural invariant. */
+	ok: boolean;
+	/** Each violated invariant (empty when `ok`). */
+	problems: AdvanceCiTemplateProblem[];
+}
+
+/**
+ * Locate the workflow template `docs/ci/advance-loop.yml.template`. It is a
+ * REPO doc (the maintainer copies it into a consumer's `.github/workflows/`), so
+ * it is resolved relative to this source file's monorepo position — the same
+ * dev-monorepo walk `resolveProtocolDoc`'s last candidates use. `override`
+ * short-circuits for tests / unusual layouts.
+ */
+export function resolveAdvanceCiTemplatePath(override?: string): string {
+	if (override) {
+		return override;
+	}
+	const here = dirname(fileURLToPath(import.meta.url));
+	// here = .../packages/dorfl/{src,dist}; the doc lives at the monorepo
+	// root under docs/ci/. Walk up to the root from either src/ or dist/.
+	const candidates = [
+		resolve(here, '..', '..', '..', 'docs', 'ci', 'advance-loop.yml.template'),
+		resolve(
+			here,
+			'..',
+			'..',
+			'..',
+			'..',
+			'docs',
+			'ci',
+			'advance-loop.yml.template',
+		),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	// Fall back to the first candidate so the error names the expected path.
+	return candidates[0];
+}
+
+/** Read the raw template text. Throws (ENOENT) if it cannot be located. */
+export function loadAdvanceCiTemplate(override?: string): string {
+	return readFileSync(resolveAdvanceCiTemplatePath(override), 'utf8');
+}
+
+/**
+ * Structurally validate the advance-loop CI workflow template against the task's
+ * acceptance criteria. Dependency-free (no YAML lib): a set of presence/shape
+ * assertions over the raw text.
+ */
+export function validateAdvanceCiTemplate(
+	text: string,
+): AdvanceCiTemplateValidation {
+	const problems: AdvanceCiTemplateProblem[] = [];
+	const require = (id: string, present: boolean, message: string): void => {
+		if (!present) {
+			problems.push({id, message});
+		}
+	};
+
+	// --- Triggers: cron AND on-answer-committed ---------------------------------
+	require('trigger-cron', /\bschedule:\s*[\s\S]*?-\s*cron:/.test(
+		text,
+	), 'must trigger on a cron schedule (`on.schedule[].cron`).');
+	require('trigger-on-answer-committed', /\bpush:\s*[\s\S]*?paths:[\s\S]*?work\/questions\//.test(
+		text,
+	), 'must trigger on-answer-committed (a push touching `work/questions/**`).');
+
+	// --- propose ⇒ a MATRIX enumerated via the mirror-side pool scan -------------
+	require('propose-matrix', /strategy:\s*[\s\S]*?matrix:/.test(
+		text,
+	), '`propose` mode must emit a MATRIX of jobs (`strategy.matrix`).');
+	require('propose-enumerates-via-scan', /dorfl scan --json/.test(
+		text,
+	), 'the matrix items must be ENUMERATED via the mirror-side pool scan ' +
+		'(`dorfl scan --json`).');
+	// The `enumerate` `jq` must UNION taskable prds into the matrix
+	// (`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`): a
+	// task-only `jq` would render `DORFL_AUTO_TASK` dead on the hourly
+	// cron — a ready ungated PRD would never become a matrix leg. The `jq` must
+	// read `scan --json`'s taskable-SPEC pool (`repos[].specs[]` + `cwd.repo.specs[]`)
+	// and emit `spec:<slug>` legs alongside the `task:<slug>` legs.
+	require('propose-enumerates-taskable-specs', /"spec:" \+ \.slug/.test(text) &&
+		/\.specs\[\]/.test(
+			text,
+		), 'the propose-mode `enumerate` `jq` must union taskable specs into the ' +
+		"matrix as `spec:<slug>` legs (read from `scan --json`'s `repos[].specs[]` " +
+		'+ `cwd.repo.specs[]` pools), so a ready ungated SPEC becomes one auto-task ' +
+		'matrix leg alongside the eligible-task legs ' +
+		'(`ci-propose-matrix-must-enumerate-sliceable-prds-not-only-slices`).');
+	require('propose-one-advance-per-item', /dorfl advance "?\$\{\{\s*matrix\./.test(
+		text,
+	), 'each matrix leg must run one `dorfl advance <matrix item>` ' +
+		'(one PR per item).');
+	// The matrix leg must carry `--propose` so the integration mode is TIED to the
+	// matrix shape (it cannot desync from the dispatch `integrationMode` input nor
+	// fall back to a repo config default of `merge`). Scoped to the `advance-propose`
+	// job so it is the LEG that carries it, not merely the file somewhere.
+	require('propose-leg-carries-propose-flag', /advance-propose:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--propose\b/.test(
+		text,
+	), 'each `propose` matrix leg must pass `--propose` so the integration mode is ' +
+		'TIED to the matrix shape (a leg can never merge to main / desync from the ' +
+		'dispatch mode).');
+
+	// --- merge ⇒ a MATRIX per item (parallel build/gate/review, serialised land) -
+	// The engine's `integrateLock` + `mergeRetries` CAS-retry loop is what makes
+	// concurrent merge jobs LAND-SAFE (`land-time-reverify-and-parallel-merge-ceiling`):
+	// build/gate/review fan out across siblings, and a non-fast-forward push
+	// triggers re-rebase + re-gate + retry up to the resolved `mergeRetries` cap.
+	// The cross-job serialiser is the CAS-retry loop itself — the git-alone floor.
+	require('merge-matrix', /advance-merge:[\s\S]*?strategy:\s*[\s\S]*?matrix:/.test(
+		text,
+	), 'the `merge` job must use a MATRIX (parallel build/gate/review per item; ' +
+		"the land tail is serialised by the engine's `mergeRetries` CAS-retry " +
+		"loop, not by the workflow's job shape).");
+	// Each merge matrix leg must run one `dorfl advance <matrix.item> --merge`,
+	// scoped to the `advance-merge:` job so the `--merge` flag is TIED to its leg
+	// (cannot desync from the dispatch `integrationMode` input nor fall back to a
+	// repo config default of `propose`).
+	require('merge-leg-carries-merge-flag', /advance-merge:[\s\S]*?dorfl advance "?\$\{\{\s*matrix\.[\s\S]*?--merge\b/.test(
+		text,
+	), 'each `merge` matrix leg must pass `--merge` so the integration mode is ' +
+		'TIED to the matrix shape (a leg can never propose-only / desync from the ' +
+		'dispatch mode).');
+	// The merge fan-out is the SAFETY-FLOOR shape: no `concurrency:` group on the
+	// `advance-merge:` job, because a GitHub Actions `concurrency:` serialiser
+	// would be load-bearing for cross-job land safety, and the floor must work on
+	// a bare arbiter with no host (Applied Answer q1: scaled CAS-retry is the
+	// floor; the portable cross-job ref-lock is the planned accelerator; GitHub
+	// `concurrency:` is OPTIONAL host sugar only, deliberately not used here).
+	require('merge-no-host-concurrency-serialiser', !/advance-merge:[\s\S]*?\n\s{4}concurrency:/.test(
+		text,
+	), 'the `merge` job must NOT carry a `concurrency:` group: a host-specific ' +
+		'serialiser would make the cross-job land safety depend on a GitHub Actions ' +
+		"feature; the engine's `mergeRetries` CAS-retry loop is the git-alone " +
+		'floor.');
+
+	// --- It only INVOKES the existing `advance` driver (no new execution model) --
+	require('invokes-advance-driver', /dorfl advance\b/.test(
+		text,
+	), 'the workflow must INVOKE the existing `advance` driver.');
+
+	return {ok: problems.length === 0, problems};
+}