@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/design/write.mjs

@@ -0,0 +1,275 @@
+/**
+ * lib/design/write.mjs — the effect edge of the design sync (WP-M7 mechanic 4).
+ *
+ * `design-md.mjs` decides WHAT the files say and `refresh-gate.mjs` decides
+ * WHEN; this module is the only place that touches the disk, so the CLI
+ * (`maestro design sync`) and the daemon's poller write the same bytes with the
+ * same modes and the same idempotence rule.
+ *
+ * IDEMPOTENCE IS BY BYTES, not by timestamp. A re-sync of an unchanged
+ * foundation must not touch DESIGN.md — the file is read by editors and skills,
+ * and a pointless mtime bump is how a watcher storms and how a git tree looks
+ * dirty for no reason. So each file is read back and compared before writing.
+ * That also means `generatedAt` must NOT be part of the rendered bytes when
+ * idempotence matters: the caller passes the SAME `generatedAt` it recorded on
+ * the previous sync, or none. (`sync.mjs` callers pass the stored value.)
+ *
+ * EVERY write here goes through `lib/fs-atomic.mjs` — the JSON snapshot and
+ * both markdown files. There are TWO writers of the same two absolute paths (a
+ * hand-run `maestro design sync` and the daemon's 15-minute poll), and a design
+ * skill reads `$AGENT_ROOT/DESIGN.md` at arbitrary moments; an in-place
+ * `writeFileSync` would let it read a half-written frontmatter block. The mode
+ * is applied with an explicit `chmod` after the rename as well as on the temp
+ * file, because Node honours a `mode` option only when it CREATES a file — a
+ * DESIGN.md some other tool left at 0600 would otherwise stay 0600 forever.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/design/write
+ */
+
+"use strict";
+
+import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { writeFileAtomic, writeJsonAtomic } from "../fs-atomic.mjs";
+import { renderDesignBundle } from "./design-md.mjs";
+import { DESIGN_STATE_REL, foundationVersion, foundationVersionLabel } from "./refresh-gate.mjs";
+
+/** The mode the generated docs are written with (readable by any tool on the seat). */
+export const DESIGN_FILE_MODE = 0o644;
+
+/**
+ * The workspace/brand name for the rendered heading, from the loaded org config.
+ *
+ * SHARED ON PURPOSE. `maestro design sync` and the daemon's poller both write
+ * DESIGN.md, and the heading is part of the rendered bytes — two definitions of
+ * "what is this workspace called" would make a hand-run sync and an automatic
+ * one disagree, and the idempotence rule above would then rewrite the file on
+ * every alternation. One function, both callers.
+ *
+ * The foundation's own `positioning` is prose, not a name, so it is never used
+ * here. Nothing is invented: an org config without a name reads "Workspace".
+ *
+ * @param {object} cfg the loaded org config (`lib/org/client.mjs#loadOrgConfig`)
+ * @returns {string}
+ */
+export function workspaceName(cfg) {
+  const org = cfg && typeof cfg === "object" ? cfg.org : null;
+  const cohort = org && typeof org === "object" ? org.cohort : null;
+  const name = cohort && typeof cohort === "object" ? cohort.orgName || cohort.workspace : null;
+  return typeof name === "string" && name.trim() ? name.trim() : "Workspace";
+}
+
+/**
+ * Write the rendered bundle, skipping any file whose bytes are already correct.
+ *
+ * @param {object} o
+ * @param {Array<{rel:string, content:string}>} o.files rendered by `renderDesignBundle`
+ * @param {string} o.outDir  where the two markdown files go
+ * @param {object} [io] injectable I/O for tests: {readFileImpl, writeFileImpl, existsImpl, mkdirImpl}
+ * @returns {{written:string[], unchanged:string[]}}
+ */
+export function writeDesignFiles({ files, outDir }, io = {}) {
+  const readImpl = io.readFileImpl || ((p) => readFileSync(p, "utf8"));
+  const writeImpl = io.writeFileImpl || ((p, data, mode) => {
+    writeFileAtomic(p, data, { mode });
+    // The rename published a file created with `mode`, but only because it was
+    // new. chmod the published name too, so a pre-existing file that some other
+    // tool left at a tighter mode is corrected rather than inherited.
+    try { chmodSync(p, mode); } catch { /* best effort: the bytes matter more than the bits */ }
+  });
+  const existsImpl = io.existsImpl || existsSync;
+  const mkdirImpl = io.mkdirImpl || ((p) => mkdirSync(p, { recursive: true }));
+  const written = [];
+  const unchanged = [];
+  if (!existsImpl(outDir)) mkdirImpl(outDir);
+  for (const file of Array.isArray(files) ? files : []) {
+    if (!file || typeof file.rel !== "string" || typeof file.content !== "string") continue;
+    const target = join(outDir, file.rel);
+    let current = null;
+    try {
+      current = existsImpl(target) ? readImpl(target) : null;
+    } catch {
+      current = null; // unreadable is the same as absent: rewrite it
+    }
+    if (current === file.content) {
+      unchanged.push(file.rel);
+      continue;
+    }
+    writeImpl(target, file.content, DESIGN_FILE_MODE);
+    written.push(file.rel);
+  }
+  return { written, unchanged };
+}
+
+/**
+ * Persist the foundation snapshot the gate reads back next tick.
+ * `{fetchedAt, version, versionLabel, foundation}` — durable JSON, atomic.
+ *
+ * @param {string} agentRoot
+ * @param {{fetchedAt:string, version:string|null, versionLabel?:string, foundation:object}} doc
+ * @param {object} [io] {writeJsonImpl, mkdirImpl}
+ * @returns {string} the path written
+ */
+export function writeFoundationState(agentRoot, doc, io = {}) {
+  const path = join(String(agentRoot || ""), DESIGN_STATE_REL);
+  const mkdirImpl = io.mkdirImpl || ((p) => mkdirSync(p, { recursive: true }));
+  mkdirImpl(dirname(path));
+  (io.writeJsonImpl || writeJsonAtomic)(path, doc);
+  return path;
+}
+
+/**
+ * Read back the last synced snapshot. Returns null when absent or corrupt — a
+ * corrupt snapshot is treated as "never synced", which re-syncs rather than
+ * wedging.
+ * @param {string} agentRoot
+ * @param {object} [io] {readFileImpl}
+ * @returns {{fetchedAt?:string, version?:string|null, versionLabel?:string, foundation?:object}|null}
+ */
+export function readFoundationState(agentRoot, io = {}) {
+  const path = join(String(agentRoot || ""), DESIGN_STATE_REL);
+  try {
+    const raw = (io.readFileImpl || ((p) => readFileSync(p, "utf8")))(path);
+    const doc = JSON.parse(raw);
+    return doc && typeof doc === "object" && !Array.isArray(doc) ? doc : null;
+  } catch {
+    return null; // absent or corrupt → re-sync
+  }
+}
+
+/**
+ * The per-output-directory render stamps from a state snapshot, as a mutable
+ * map of resolved path → ISO string.
+ *
+ * MIGRATION. Snapshots written before the map existed carry one bare
+ * `renderedAt` string, which described the agent dir (the only directory the
+ * daemon ever writes). Reading it as that entry means an upgraded seat finds
+ * its DESIGN.md already matching and rewrites nothing.
+ *
+ * @param {object|null} prior
+ * @param {string} agentRoot
+ * @returns {Record<string,string>}
+ */
+export function priorRenderStamps(prior, agentRoot) {
+  const out = {};
+  const p = prior && typeof prior === "object" ? prior : {};
+  if (p.rendered && typeof p.rendered === "object" && !Array.isArray(p.rendered)) {
+    for (const [k, v] of Object.entries(p.rendered)) {
+      if (typeof k === "string" && typeof v === "string" && v) out[k] = v;
+    }
+  }
+  const legacy = typeof p.renderedAt === "string" && p.renderedAt ? p.renderedAt : "";
+  const rootKey = resolve(String(agentRoot || ""));
+  if (legacy && !out[rootKey]) out[rootKey] = legacy;
+  return out;
+}
+
+/**
+ * Do all rendered files already match what is on disk? The idempotence probe.
+ * @param {Array<{rel:string, content:string}>} files
+ * @param {string} outDir
+ * @param {object} [io]
+ * @returns {boolean}
+ */
+export function filesMatch(files, outDir, io = {}) {
+  const readImpl = io.readFileImpl || ((p) => readFileSync(p, "utf8"));
+  const existsImpl = io.existsImpl || existsSync;
+  for (const file of Array.isArray(files) ? files : []) {
+    const target = join(outDir, file.rel);
+    let current = null;
+    try {
+      current = existsImpl(target) ? readImpl(target) : null;
+    } catch {
+      return false; // unreadable → rewrite
+    }
+    if (current !== file.content) return false;
+  }
+  return true;
+}
+
+/**
+ * Render a fetched foundation and land it on the seat: DESIGN.md + PRODUCT.md in
+ * `outDir`, the snapshot in `state/design/foundation.json`. The ONE code path
+ * both `maestro design sync` and the daemon's poller use, so a hand-run sync and
+ * an automatic one produce identical bytes.
+ *
+ * THE `generatedAt` DANCE. A timestamp inside the rendered bytes would make
+ * every sync a rewrite, defeating the idempotence the whole design turns on. So
+ * the files are first rendered carrying the PREVIOUS sync's stamp: if they then
+ * match the disk byte-for-byte, nothing changed and nothing is written. Only
+ * when something genuinely differs are they re-rendered with `now` — so the
+ * stamp means "when this content was minted", which is the honest reading, and
+ * an unchanged foundation touches no file.
+ *
+ * THE STAMP IS PER OUTPUT DIRECTORY (`rendered`, keyed by resolved path). One
+ * shared stamp is a permanent rewrite loop the moment a second directory
+ * exists: `maestro design sync --out docs/brand` stamps the state with its own
+ * `now`, the daemon's next poll of the agent dir renders with that stamp, does
+ * not match ITS files, rewrites them and re-stamps — and each lane then
+ * invalidates the other's files forever, with a foundation that never changed.
+ * A legacy state file carrying a bare `renderedAt` string is read as the agent
+ * dir's entry, so an existing seat migrates without one spurious rewrite.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot          the agent dir (where state/ lives)
+ * @param {string} [o.outDir]           where the docs go (default: agentRoot)
+ * @param {object} o.result             the `branding.getFoundation` result frame's `result`
+ * @param {number} o.now                epoch ms (injected)
+ * @param {string} [o.name]             workspace/brand name for the heading
+ * @param {string} [o.source]           provenance line
+ * @param {object} [io]                 injectable I/O (see writeDesignFiles / writeFoundationState)
+ * @returns {{written:string[], unchanged:string[], version:string|null, statePath:string, outDir:string}}
+ */
+export function syncDesign(o, io = {}) {
+  const agentRoot = String(o.agentRoot || "");
+  const outDir = String(o.outDir || agentRoot);
+  const now = Number.isFinite(o.now) ? o.now : 0;
+  const nowIso = new Date(now).toISOString();
+  const result = o.result && typeof o.result === "object" ? o.result : {};
+  const foundation = result.foundation && typeof result.foundation === "object" ? result.foundation : {};
+  const version = foundationVersion(result);
+  const versionLabel = foundationVersionLabel(result);
+  const prior = readFoundationState(agentRoot, io);
+  const rendered = priorRenderStamps(prior, agentRoot);
+  const key = resolve(outDir);
+  const priorStamp = rendered[key] || nowIso;
+
+  const base = { name: o.name, source: o.source, versionId: version || "", versionLabel };
+  let renderedAt = priorStamp;
+  let files = renderDesignBundle(foundation, { ...base, generatedAt: renderedAt });
+  let out = { written: [], unchanged: files.map((f) => f.rel) };
+  if (!filesMatch(files, outDir, io)) {
+    renderedAt = nowIso;
+    files = renderDesignBundle(foundation, { ...base, generatedAt: renderedAt });
+    out = writeDesignFiles({ files, outDir }, io);
+  }
+  rendered[key] = renderedAt;
+  const statePath = writeFoundationState(
+    agentRoot,
+    {
+      fetchedAt: nowIso,
+      // The agent dir's own stamp stays at the top level: it is what a reader
+      // (and an older SDK) means by "when was DESIGN.md minted".
+      renderedAt: rendered[resolve(agentRoot)] || renderedAt,
+      rendered,
+      version: version || null,
+      versionLabel,
+      foundation,
+    },
+    io,
+  );
+  return { ...out, version: version || null, statePath, outDir };
+}
+
+export default {
+  workspaceName,
+  priorRenderStamps,
+  writeDesignFiles,
+  writeFoundationState,
+  readFoundationState,
+  filesMatch,
+  syncDesign,
+  DESIGN_FILE_MODE,
+};

package/lib/design/write.test.mjs

@@ -0,0 +1,241 @@
+/**
+ * write.test.mjs — the effect edge of the design sync (WP-M7 mechanic 4).
+ *
+ * Real files in a temp dir, not stubs: the claims worth holding here are about
+ * the FILESYSTEM — that an unchanged foundation touches no mtime, and that the
+ * two markdown files land at 0644 so any tool on the seat can read them.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync, statSync, utimesSync, existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { syncDesign, writeDesignFiles, writeFoundationState, readFoundationState, filesMatch, workspaceName, DESIGN_FILE_MODE } from "./write.mjs";
+import { renderDesignBundle } from "./design-md.mjs";
+import { DESIGN_STATE_REL } from "./refresh-gate.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+const FIXTURE = JSON.parse(readFileSync(new URL("./fixtures/foundation.json", import.meta.url), "utf8"));
+
+/** A `branding.getFoundation` result frame's `result`. */
+const result = (over = {}) => ({
+  foundation: FIXTURE,
+  version: { id: "bv_01HQZ", seq: 7, label: "V2.7" },
+  headVersionId: "bv_01HQZ",
+  isHead: true,
+  unversioned: false,
+  history: [],
+  ...over,
+});
+
+function tmpRoot(t) {
+  const dir = mkdtempSync(join(tmpdir(), "maestro-design-write-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("a first sync writes both files plus the state snapshot", (t) => {
+  const root = tmpRoot(t);
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  assert.deepEqual(out.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.deepEqual(out.unchanged, []);
+  assert.equal(out.version, "bv_01HQZ");
+  assert.equal(out.outDir, root);
+
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /^---\nname: "Northwind"\n/);
+  assert.match(design, /\{colors\.primary\}/);
+  assert.match(readFileSync(join(root, "PRODUCT.md"), "utf8"), /# Northwind — product voice/);
+
+  const state = JSON.parse(readFileSync(join(root, DESIGN_STATE_REL), "utf8"));
+  assert.equal(state.version, "bv_01HQZ");
+  assert.equal(state.versionLabel, "V2.7");
+  assert.equal(state.fetchedAt, "2026-09-08T12:00:00.000Z");
+  assert.deepEqual(state.foundation, FIXTURE, "the raw foundation is kept verbatim for the next gate read");
+});
+
+test("both markdown files are 0644", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) {
+    assert.equal(statSync(join(root, rel)).mode & 0o777, DESIGN_FILE_MODE, rel);
+  }
+});
+
+test("re-syncing an unchanged foundation rewrites NOTHING — mtimes are untouched", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  // Backdate both files so any rewrite is unmistakable.
+  const old = new Date(NOW - 86_400_000);
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) utimesSync(join(root, rel), old, old);
+  const before = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(root, rel)).mtimeMs);
+
+  // A LATER clock, deliberately: the timestamp inside the file must not be what
+  // makes a sync a rewrite, or the interval poll would churn the tree forever.
+  const again = syncDesign({ agentRoot: root, result: result(), now: NOW + 20 * 60_000, name: "Northwind" });
+  assert.deepEqual(again.written, [], "nothing written");
+  assert.deepEqual(again.unchanged, ["DESIGN.md", "PRODUCT.md"]);
+
+  const after = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(root, rel)).mtimeMs);
+  assert.deepEqual(after, before, "the files were not touched at all");
+
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /\*\*Synced:\*\* 2026-09-08T12:00:00\.000Z/, "the stamp still says when the CONTENT was minted");
+
+  // The snapshot is still refreshed, so the gate knows the seat did check.
+  const state = JSON.parse(readFileSync(join(root, DESIGN_STATE_REL), "utf8"));
+  assert.equal(state.fetchedAt, "2026-09-08T12:20:00.000Z");
+  assert.equal(state.renderedAt, "2026-09-08T12:00:00.000Z");
+});
+
+test("a changed foundation rewrites the affected file and re-stamps it", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  const moved = JSON.parse(JSON.stringify(FIXTURE));
+  moved.colors[2].value = "#111111";
+  const out = syncDesign({
+    agentRoot: root,
+    result: result({ foundation: moved, headVersionId: "bv_02", version: { id: "bv_02", seq: 8, label: "V2.8" } }),
+    now: NOW + 20 * 60_000,
+    name: "Northwind",
+  });
+
+  assert.ok(out.written.includes("DESIGN.md"));
+  assert.equal(out.version, "bv_02");
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /primary-moss: "#111111"/);
+  assert.match(design, /\*\*Synced:\*\* 2026-09-08T12:20:00\.000Z/);
+  assert.match(design, /\*\*Version:\*\* V2\.8/);
+});
+
+test("--out sends the docs elsewhere; the snapshot always stays under the agent root", (t) => {
+  const root = tmpRoot(t);
+  const outDir = join(root, "docs", "brand");
+  const out = syncDesign({ agentRoot: root, outDir, result: result(), now: NOW, name: "Northwind" });
+
+  assert.equal(out.outDir, outDir);
+  assert.ok(existsSync(join(outDir, "DESIGN.md")));
+  assert.ok(!existsSync(join(root, "DESIGN.md")));
+  assert.ok(existsSync(join(root, DESIGN_STATE_REL)));
+});
+
+test("writeDesignFiles skips a file whose bytes already match and rewrites an unreadable one", (t) => {
+  const root = tmpRoot(t);
+  const files = renderDesignBundle(FIXTURE, { name: "Northwind" });
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }).written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }), { written: [], unchanged: ["DESIGN.md", "PRODUCT.md"] });
+
+  writeFileSync(join(root, "DESIGN.md"), "someone edited this by hand\n");
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }).written, ["DESIGN.md"], "a hand edit is overwritten — the file is generated");
+
+  const boom = writeDesignFiles({ files, outDir: root }, { readFileImpl: () => { throw new Error("EIO"); } });
+  assert.deepEqual(boom.written, ["DESIGN.md", "PRODUCT.md"], "unreadable is treated as absent");
+});
+
+test("writeDesignFiles ignores malformed entries rather than throwing", (t) => {
+  const root = tmpRoot(t);
+  const out = writeDesignFiles({ files: [null, { rel: "A.md" }, { content: "x" }, { rel: "ok.md", content: "y" }], outDir: root });
+  assert.deepEqual(out.written, ["ok.md"]);
+  assert.deepEqual(writeDesignFiles({ files: "not a list", outDir: root }), { written: [], unchanged: [] });
+});
+
+test("readFoundationState reads back what writeFoundationState wrote; corrupt reads as never-synced", (t) => {
+  const root = tmpRoot(t);
+  assert.equal(readFoundationState(root), null, "absent → null");
+
+  const path = writeFoundationState(root, { fetchedAt: "2026-09-08T12:00:00.000Z", version: "bv_1", foundation: { colors: [] } });
+  assert.equal(path, join(root, DESIGN_STATE_REL));
+  assert.equal(readFoundationState(root).version, "bv_1");
+
+  writeFileSync(path, "{ not json");
+  assert.equal(readFoundationState(root), null, "corrupt → null → re-sync, never a wedge");
+
+  writeFileSync(path, JSON.stringify([1, 2]));
+  assert.equal(readFoundationState(root), null, "an array is not a snapshot");
+});
+
+test("filesMatch is the idempotence probe the CLI's claim rests on", (t) => {
+  const root = tmpRoot(t);
+  const files = renderDesignBundle(FIXTURE, { name: "Northwind" });
+  assert.equal(filesMatch(files, root), false, "nothing on disk yet");
+  writeDesignFiles({ files, outDir: root });
+  assert.equal(filesMatch(files, root), true);
+  writeFileSync(join(root, "PRODUCT.md"), "drift\n");
+  assert.equal(filesMatch(files, root), false);
+});
+
+test("workspaceName reads the org config and invents nothing", () => {
+  assert.equal(workspaceName({ org: { cohort: { orgName: "Northwind" } } }), "Northwind");
+  assert.equal(workspaceName({ org: { cohort: { workspace: "adaptic-hq" } } }), "adaptic-hq");
+  assert.equal(workspaceName({ org: { cohort: { orgName: "  " } } }), "Workspace");
+  assert.equal(workspaceName({}), "Workspace");
+  assert.equal(workspaceName(null), "Workspace");
+});
+
+test("a state directory that does not exist yet is created", (t) => {
+  const root = join(tmpRoot(t), "not", "made", "yet");
+  mkdirSync(root, { recursive: true });
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  assert.ok(existsSync(out.statePath));
+});
+
+// ── two output directories, one state file ──────────────────────────────────
+
+test("the daemon's agent dir and a --out directory do not invalidate each other, ever", (t) => {
+  // The scenario: an operator runs `maestro design sync --out docs/brand`
+  // (advertised in the guide) on a seat whose daemon polls the agent dir every
+  // 15 minutes. With one shared render stamp, each lane re-stamped the state
+  // and the other lane then found its own files "stale" — both files rewritten
+  // on every tick, forever, with a foundation that never changed.
+  const root = tmpRoot(t);
+  const brand = join(root, "docs", "brand");
+  let now = NOW;
+  const daemon = () => syncDesign({ agentRoot: root, result: result(), now: (now += 900_000), name: "Northwind" });
+  const cli = () => syncDesign({ agentRoot: root, outDir: brand, result: result(), now: (now += 60_000), name: "Northwind" });
+
+  assert.deepEqual(daemon().written, ["DESIGN.md", "PRODUCT.md"], "first write of the agent dir");
+  assert.deepEqual(cli().written, ["DESIGN.md", "PRODUCT.md"], "first write of docs/brand");
+
+  for (let i = 0; i < 6; i++) {
+    assert.deepEqual(daemon().written, [], `daemon poll ${i + 1} rewrote nothing`);
+    assert.deepEqual(cli().written, [], `--out run ${i + 1} rewrote nothing`);
+  }
+
+  const state = readFoundationState(root);
+  assert.equal(typeof state.rendered, "object");
+  assert.equal(Object.keys(state.rendered).length, 2, "one stamp per output directory");
+  assert.equal(state.renderedAt, state.rendered[resolve(root)], "the top-level stamp still describes the agent dir");
+});
+
+test("a legacy state file with a bare renderedAt migrates without a spurious rewrite", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  // Rewrite the snapshot in the pre-map shape, as an older SDK left it.
+  const doc = readFoundationState(root);
+  const legacy = { ...doc };
+  delete legacy.rendered;
+  writeFoundationState(root, legacy);
+  assert.equal(readFoundationState(root).rendered, undefined);
+
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW + 3_600_000, name: "Northwind" });
+  assert.deepEqual(out.written, [], "the old stamp is read as the agent dir's, so the bytes still match");
+  assert.equal(readFoundationState(root).rendered[resolve(root)], legacy.renderedAt);
+});
+
+test("both markdown files are published atomically and forced to 0644 even over a tighter file", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  // Some other tool tightens the mode and truncates the content.
+  chmodSync(join(root, "DESIGN.md"), 0o600);
+  writeFileSync(join(root, "DESIGN.md"), "half a file");
+  syncDesign({ agentRoot: root, result: result(), now: NOW + 1000, name: "Northwind" });
+  assert.equal(statSync(join(root, "DESIGN.md")).mode & 0o777, DESIGN_FILE_MODE, "chmod runs on a rewrite, not only on create");
+
+  // No temp file is left behind by the atomic publish.
+  assert.deepEqual(readdirSync(root).filter((f) => f.includes(".tmp.")), []);
+});

package/lib/prompts/parallelism.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/prompts/parallelism.mjs — the fleet-wide parallelism directive (WP-M7).
+ *
+ * THE GAP this closes (owner directive 2026-09-09): a session handed a plan with
+ * six independent tasks ran them one at a time, because nothing in its prompt
+ * ever said it was allowed not to. The directive below is the standing
+ * permission — plus the ONE safety rule that makes parallel dispatch safe on a
+ * shared checkout (no two agents editing the same file).
+ *
+ * It is a CONSTANT, not a template: the same bytes reach `maestro session spawn`
+ * (peer sessions) and `scripts/daemon/prompt-builder.mjs` (escalate/guarded
+ * sub-sessions), so the wording can be audited in one place and a test can pin
+ * it byte-for-byte.
+ *
+ * {@link withParallelism} is IDEMPOTENT. Two prompt seams compose (a daemon
+ * prompt handed to `session spawn`), and a directive repeated twice reads as
+ * emphasis to a model, which is exactly how "maximum safe parallelism" turns
+ * into "ignore the file-scope rule" — so a prompt that already carries the text
+ * is returned unchanged.
+ *
+ * Pure: no clock, no env, no I/O. Node builtins only. ESM.
+ *
+ * @module lib/prompts/parallelism
+ */
+
+"use strict";
+
+/**
+ * The directive, verbatim (design spec 2026-09-08 §WP-M7 mechanic 5). Do not
+ * reword without changing the spec — `parallelism.test.mjs` pins these bytes.
+ * @type {string}
+ */
+export const PARALLELISM_DIRECTIVE = `You are allowed to run multiple sub-agents concurrently.
+
+When the plan contains independent tasks, dispatch them together in a single parallel batch rather than waiting for each task to finish before starting the next.
+
+Only run tasks sequentially when one task genuinely depends on the output of another.
+
+Before dispatching any batch, check the planned file scope for each task and ensure that no two agents are assigned to edit the same file. If tasks would overlap on a file, sequence those tasks or redefine their scope to eliminate the conflict.
+
+Default to maximum safe parallelism.`;
+
+/**
+ * Prepend {@link PARALLELISM_DIRECTIVE} to a prompt, exactly once.
+ *
+ * A prompt that already contains the directive anywhere in its body is returned
+ * unchanged (idempotent — see the module docstring). A non-string or empty
+ * prompt yields the directive alone, so a caller that lost its prompt still
+ * sends something coherent rather than `undefined`.
+ *
+ * @param {string} prompt the prompt to lead
+ * @returns {string}
+ */
+export function withParallelism(prompt) {
+  const body = typeof prompt === "string" ? prompt : "";
+  if (body.includes(PARALLELISM_DIRECTIVE)) return body;
+  if (!body.trim()) return PARALLELISM_DIRECTIVE;
+  return `${PARALLELISM_DIRECTIVE}\n\n${body}`;
+}
+
+/**
+ * How many times the directive appears in a string. The seam a test (or a
+ * caller composing two prompts) uses to assert "exactly once".
+ * @param {string} text
+ * @returns {number}
+ */
+export function countParallelism(text) {
+  const body = typeof text === "string" ? text : "";
+  if (!body) return 0;
+  let n = 0;
+  let i = body.indexOf(PARALLELISM_DIRECTIVE);
+  while (i !== -1) {
+    n += 1;
+    i = body.indexOf(PARALLELISM_DIRECTIVE, i + PARALLELISM_DIRECTIVE.length);
+  }
+  return n;
+}
+
+export default { PARALLELISM_DIRECTIVE, withParallelism, countParallelism };