@indigoai-us/hq-cli 5.345.88 → 5.345.89

package/assets/scaffold/core/scripts/lib/delegate-brainstorm.sh

@@ -0,0 +1,120 @@
+# shellcheck shell=bash
+# hq-core: public
+# delegate-brainstorm.sh — shared readers for brainstorm-stage projects in the
+# /delegate helpers.
+#
+# SOURCED, never executed:  . "$ROOT/core/scripts/lib/delegate-brainstorm.sh"
+# bash 3.2 safe; no associative arrays, no GNU-only flags.
+#
+# A brainstorm-stage project has companies/<co>/projects/<slug>/brainstorm.md
+# and no prd.json yet (policy hq-brainstorm-leaves-handoffable-project-folder).
+# Every delegation helper that reads the PRD falls back to these readers when
+# the manifest says project.stage == "brainstorm".
+
+# Project stage from the files on disk. Prints "prd", "brainstorm", or "none".
+hq_delegate_project_stage() { # project_dir
+  if [ -f "$1/prd.json" ]; then
+    echo prd
+  elif [ -f "$1/brainstorm.md" ]; then
+    echo brainstorm
+  else
+    echo none
+  fi
+}
+
+# Value of a top-level `key: value` line inside the leading YAML frontmatter.
+# Prints nothing when the file has no frontmatter or the key is absent.
+hq_brainstorm_frontmatter_get() { # file key
+  awk -v key="$2" '
+    NR == 1 { if ($0 != "---") exit; next }
+    /^---[[:space:]]*$/ { exit }
+    {
+      split($0, kv, ":")
+      if (kv[1] == key) {
+        sub("^[^:]*:[[:space:]]*", "", $0)
+        gsub(/^"|"$/, "", $0)
+        print
+        exit
+      }
+    }' "$1"
+}
+
+# One-line summary: the first `> ` blockquote after the H1, else the first
+# non-empty prose line after the H1.
+hq_brainstorm_summary() { # file
+  awk '
+    /^# / && !seen_h1 { seen_h1 = 1; next }
+    !seen_h1 { next }
+    /^> / { sub(/^> /, ""); print; exit }
+    /^#/ { exit }
+    /^[[:space:]]*$/ { next }
+    { print; exit }' "$1"
+}
+
+# Project title: the first H1 without the leading `# `.
+hq_brainstorm_title() { # file
+  awk '/^# / { sub(/^# /, ""); print; exit }' "$1"
+}
+
+# Body of a `## <heading>` section, up to the next `## ` heading. The heading
+# is matched by prefix so `## Recommendation` also matches a decorated title.
+hq_brainstorm_section() { # file heading
+  awk -v heading="$2" '
+    /^## / {
+      if (in_section) exit
+      if (index($0, "## " heading) == 1) { in_section = 1; next }
+    }
+    in_section { print }' "$1" | sed -e '/./,$!d' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'
+}
+
+# Newest journal note by filename, excluding the delegation log the transfer
+# step maintains. Prints the HQ-root-relative path or nothing.
+hq_brainstorm_latest_journal() { # hq_root rel_project_dir
+  local dir="$1/$2/journal" f newest="" name newest_name=""
+  [ -d "$dir" ] || return 0
+  # Bash's pathname expansion is sorted by locale like sort(1), and unlike
+  # find -maxdepth it works with both GNU and macOS/BSD find installations.
+  # Include dotfiles too: find includes them, while Bash's default glob does not.
+  for f in "$dir"/*.md "$dir"/.md "$dir"/.[!.]*.md "$dir"/..?*.md; do
+    [ -f "$f" ] || continue
+    name="${f##*/}"
+    [ "$name" = delegations.md ] && continue
+    case "$name" in *.md) ;; *) continue ;; esac
+    if [ -z "$newest" ]; then newest="$f"; newest_name="$name"; continue; fi
+    if [[ "$name" > "$newest_name" ]]; then newest="$f"; newest_name="$name"; fi
+  done
+  [ -n "$newest" ] || return 0
+  printf '%s\n' "${newest#"$1/"}"
+}
+
+# HQ-root-relative dossier paths for a brainstorm-stage project, one per line:
+# brainstorm.md, every file under research/, the newest journal note.
+hq_brainstorm_dossier() { # hq_root rel_project_dir
+  local root="$1" rel="$2"
+  printf '%s\n' "$rel/brainstorm.md"
+  if [ -d "$root/$rel/research" ]; then
+    (cd "$root" && find "$rel/research" -type f ! -name '.DS_Store' | sort)
+  fi
+  hq_brainstorm_latest_journal "$root" "$rel"
+}
+
+# Write or replace `key: value` inside the frontmatter, creating the
+# frontmatter block when the file has none. Rewrites the file in place through
+# a temp file so a failure leaves the original intact.
+hq_brainstorm_frontmatter_set() { # file key value
+  local file="$1" key="$2" value="$3" tmp
+  tmp="$(mktemp "${file}.tmp.XXXXXX")"
+  if [ "$(head -1 "$file")" = "---" ]; then
+    awk -v key="$key" -v value="$value" '
+      NR == 1 { print; next }
+      !done && /^---[[:space:]]*$/ { print key ": " value; done = 1; print; next }
+      !done {
+        split($0, kv, ":")
+        if (kv[1] == key) { print key ": " value; done = 1; next }
+      }
+      { print }' "$file" > "$tmp"
+  else
+    { printf -- '---\n%s: %s\n---\n' "$key" "$value"; cat "$file"; } > "$tmp"
+  fi
+  mv -f "$tmp" "$file"
+}

package/dist/commands/core-delegate-brainstorm.d.ts

@@ -0,0 +1,9 @@
+export type BrainstormStage = "prd" | "brainstorm" | "none";
+export declare function projectStage(projectDir: string): BrainstormStage;
+export declare function brainstormFrontmatterGet(file: string, key: string): string;
+export declare function brainstormTitle(file: string): string;
+export declare function brainstormSummary(file: string): string;
+export declare function brainstormSection(file: string, heading: string): string;
+export declare function brainstormDossier(root: string, relativeProject: string): string[];
+export declare function brainstormFrontmatterSet(file: string, key: string, value: string): void;
+//# sourceMappingURL=core-delegate-brainstorm.d.ts.map

package/dist/commands/core-delegate-brainstorm.js

@@ -0,0 +1,161 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function projectStage(projectDir) {
+    if (fs.existsSync(path.join(projectDir, "prd.json")))
+        return "prd";
+    if (fs.existsSync(path.join(projectDir, "brainstorm.md")))
+        return "brainstorm";
+    return "none";
+}
+export function brainstormFrontmatterGet(file, key) {
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    if (lines[0] !== "---")
+        return "";
+    for (const line of lines.slice(1)) {
+        if (/^---[\t ]*$/.test(line))
+            break;
+        const colon = line.indexOf(":");
+        if (colon < 0 || line.slice(0, colon) !== key)
+            continue;
+        return line.slice(colon + 1).replace(/^[\t ]*/, "").replace(/^"|"$/g, "");
+    }
+    return "";
+}
+export function brainstormTitle(file) {
+    return fs.readFileSync(file, "utf8").split("\n").find((line) => line.startsWith("# "))?.slice(2) ?? "";
+}
+export function brainstormSummary(file) {
+    let seenH1 = false;
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        if (!seenH1 && line.startsWith("# ")) {
+            seenH1 = true;
+            continue;
+        }
+        if (!seenH1)
+            continue;
+        if (line.startsWith("> "))
+            return line.slice(2);
+        if (line.startsWith("#"))
+            return "";
+        if (!line.trim())
+            continue;
+        return line;
+    }
+    return "";
+}
+export function brainstormSection(file, heading) {
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    const section = [];
+    let inSection = false;
+    for (const line of lines) {
+        if (line.startsWith("## ")) {
+            if (inSection)
+                break;
+            if (line.startsWith(`## ${heading}`)) {
+                inSection = true;
+                continue;
+            }
+        }
+        if (inSection)
+            section.push(line);
+    }
+    while (section[0] === "")
+        section.shift();
+    while (section.at(-1) === "")
+        section.pop();
+    return section.join("\n");
+}
+function filesBelow(directory) {
+    if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory())
+        return [];
+    const files = [];
+    const visit = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const target = path.join(current, entry.name);
+            if (entry.isDirectory())
+                visit(target);
+            else if (entry.isFile() && entry.name !== ".DS_Store")
+                files.push(target);
+        }
+    };
+    visit(directory);
+    return files;
+}
+export function brainstormDossier(root, relativeProject) {
+    const projectDir = path.join(root, relativeProject);
+    const result = [`${relativeProject}/brainstorm.md`];
+    result.push(...filesBelow(path.join(projectDir, "research"))
+        .map((file) => path.relative(root, file).split(path.sep).join("/")).sort());
+    const journal = path.join(projectDir, "journal");
+    if (fs.existsSync(journal) && fs.statSync(journal).isDirectory()) {
+        const newest = fs.readdirSync(journal)
+            .filter((name) => name.endsWith(".md") && name !== "delegations.md" && isRegularFile(path.join(journal, name)))
+            .sort().at(-1);
+        if (newest)
+            result.push(`${relativeProject}/journal/${newest}`);
+    }
+    return result;
+}
+function isRegularFile(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function brainstormFrontmatterSet(file, key, value) {
+    const contents = fs.readFileSync(file, "utf8");
+    const lines = contents.split("\n");
+    let output;
+    if (lines[0] === "---") {
+        output = [];
+        let done = false;
+        let closed = false;
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index] ?? "";
+            if (index === 0) {
+                output.push(line);
+                continue;
+            }
+            if (/^---[\t ]*$/.test(line)) {
+                if (!done) {
+                    output.push(`${key}: ${value}`);
+                    done = true;
+                }
+                output.push(line);
+                output.push(...lines.slice(index + 1));
+                closed = true;
+                break;
+            }
+            const colon = line.indexOf(":");
+            if (!done && colon >= 0 && line.slice(0, colon) === key) {
+                output.push(`${key}: ${value}`);
+                done = true;
+            }
+            else
+                output.push(line);
+        }
+        if (!closed)
+            output = output.length ? output : lines;
+    }
+    else {
+        output = ["---", `${key}: ${value}`, "---", ...lines];
+    }
+    const temporary = `${file}.tmp.${randomBytes(6).toString("hex")}`;
+    const rewritten = output.join("\n");
+    const contentsToWrite = lines[0] === "---" && !rewritten.endsWith("\n") ? `${rewritten}\n` : rewritten;
+    fs.writeFileSync(temporary, contentsToWrite, { mode: 0o600, flag: "wx" });
+    try {
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch { /* retain primary failure */ }
+        throw error;
+    }
+}
+//# sourceMappingURL=core-delegate-brainstorm.js.map

package/dist/commands/core-delegate-w1b.js

@@ -1,5 +1,5 @@
 /** Native implementations of the second Wave 1 delegate command family. */
-import { createHash } from "node:crypto";
+import { createHash, randomInt } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -13,7 +13,10 @@ import { ACL_SOURCE_DISPLAY_LABELS } from "../utils/files-browse-acl.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 import { resolveWindowsBash } from "../utils/windows-bash.js";
 import { createShellCompatibleJqInvoker } from "../utils/jq-windows-compat.js";
+import { brainstormDossier, brainstormFrontmatterGet, brainstormSection, brainstormSummary, projectStage } from "./core-delegate-brainstorm.js";
 const FLAG = "core-native-delegate";
+const MKTEMP_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const MKTEMP_SUFFIX_LENGTH = 10;
 const ASSETS = {
     bundle: "core/scripts/hq-delegate-bundle.sh",
     grant: "core/scripts/hq-delegate-grant.sh",
@@ -32,7 +35,7 @@ const USAGE = {
     bundle: "hq-delegate-bundle.sh — freeze a project into a portable delegation bundle.\n\nUsage:\n  core/scripts/hq-delegate-bundle.sh build \\\n    --company <slug> --project <name> --to <principal> \\\n    [--to-kind person|agent] [--to-name <display name>] \\\n    [--mode transfer|share] [--dry-run]\n\n--dry-run prints the manifest JSON to stdout and writes nothing.\n\nWrites workspace/delegations/<delegationId>/{manifest.json,BRIEF.md} and\n",
     grant: "hq-delegate-grant.sh — materialize a delegation's dossier in the vault and\nwrite the ACL grants its manifest declares, verifying each one landed.\n\nUsage:\n  core/scripts/hq-delegate-grant.sh --manifest <path> [--yes]\n\nWithout --yes: prints the full grant plan (prefix, principal, permission —\nthe write grant is a privilege escalation and needs explicit confirmation)\nand exits 2 without mutating anything. The caller (the /delegate skill)\nconfirms with the user, then re-invokes with --yes.\n\nWith --yes:\n  1. hq sync push the project directory so the vault prefix exists\n  2. hq files share each manifest vaultPrefix to the recipient\n  3. read each grant back with hq files acl and match grantee + permission\n  4. advance manifest status building -> granted, stamping verifiedAt\n\nDirect ACL grants ONLY — this helper never mints a share-session URL\n(policy hq-delegate-never-inlines-secrets-or-share-urls).\n\nIdempotent: a prefix whose grant already exists is reported, not an error.\nA failed read-back exits non-zero and leaves manifest status unchanged.\n\n",
     send: "hq-delegate-send.sh — generate the self-sufficient pickup prompt for a\ndelegation and deliver it by DM. The prompt IS the handoff: pasted into a\nfresh agent session on a clean HQ install, it pulls every file on demand\n(hq files get per prefix — no /hq-sync run) and reaches the first\nnext-step with no follow-up question to the delegator.\n\nUsage:\n  core/scripts/hq-delegate-send.sh --manifest <path> [--send]\n    [--headline <text>] [--note <text>]\n\nWithout --send: (re)generates PICKUP-PROMPT.md next to the manifest and\nprints its path — inspectable, idempotent, sends nothing.\nWith --send: requires manifest status \"verified\" (the US-008 probe must\nhave passed), then delivers ONE `hq dm` with --prompt-file/--details-file\nand advances status to \"sent\", recording the DM eventId.\n\nThe caller (the /delegate skill) humanizes --headline / --note per\ncore/knowledge/public/hq-core/humanize-before-send.md (channel dm, light)\nBEFORE invoking; this helper never rewrites recipients, flags, or the\ngenerated command lines.\n\nFail-closed: the generated prompt is scanned for secret-shaped content and\nshare-session URLs; a match aborts before anything is written or sent\n(policy hq-delegate-never-inlines-secrets-or-share-urls).\n\n",
-    verify: "hq-delegate-verify.sh — prove a delegation can actually be picked up\nbefore anyone is told it is theirs, or print the full plan without\ntouching anything.\n\nUsage (probe mode — after grants, before the DM):\n  core/scripts/hq-delegate-verify.sh --manifest <path>\n\nProbes every manifest vaultPrefix with `hq files browse` and requires it\nreachable AND non-empty. All pass -> manifest advances granted -> verified\n(send is gated on this). Any failure -> non-zero, the failing prefix and\nlikely cause named, status left at its last successful value so a re-run\nresumes without re-granting.\n\nUsage (dry-run mode — full plan, zero mutation):\n  core/scripts/hq-delegate-verify.sh --dry-run \\\n    --company <slug> --project <name> --to <principal> [--mode transfer|share]\n\nPrints recipient, mode, every prefix with its permission, the secret\nnames an .env.schema would grant, repo + branch, and the DM headline that\nwould be sent. Exits 0. Creates nothing under workspace/delegations/ and\ninvokes no mutating command.\n\nEnv: HQ_ROOT — HQ root override (default: resolved from script location)\n",
+    verify: "hq-delegate-verify.sh — prove a delegation can actually be picked up\nbefore anyone is told it is theirs, or print the full plan without\ntouching anything.\n\nUsage (probe mode — after grants, before the DM):\n  core/scripts/hq-delegate-verify.sh --manifest <path>\n\nProbes every manifest vaultPrefix with `hq files browse` and requires it\nreachable AND non-empty. All pass -> manifest advances granted -> verified\n(send is gated on this). Any failure -> non-zero, the failing prefix and\nlikely cause named, status left at its last successful value so a re-run\nresumes without re-granting.\n\nUsage (dry-run mode — full plan, zero mutation):\n  core/scripts/hq-delegate-verify.sh --dry-run \\\n    --company <slug> --project <name> --to <principal> [--mode transfer|share]\n\nPrints recipient, mode, project stage (prd, or brainstorm with the dossier\nfiles and the /plan next step), every prefix with its permission, the secret\nnames an .env.schema would grant, repo + branch, and the DM headline that\nwould be sent. Exits 0. Creates nothing under workspace/delegations/ and\ninvokes no mutating command.\n\n",
     publish: "usage: --manifest <path>",
 };
 function out(value) { process.stdout.write(value); }
@@ -56,6 +59,9 @@ function currentTime() {
     const date = value === undefined ? new Date() : new Date(value);
     return Number.isNaN(date.getTime()) ? "Invalid Date" : date.toISOString().replace(/\.\d{3}Z$/, "Z");
 }
+function mktempCompatibleSuffix() {
+    return Array.from({ length: MKTEMP_SUFFIX_LENGTH }, () => MKTEMP_ALPHABET[randomInt(MKTEMP_ALPHABET.length)]).join("");
+}
 function jsonFile(file) {
     try {
         const value = readJsonFile(file);
@@ -254,17 +260,23 @@ function runBundle(args, context, onMalformedWhoami) {
     const prdPath = path.join(projectDir, "prd.json");
     if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory())
         return fail("bundle", `project directory not found: companies/${company}/projects/${project}`);
-    if (!fs.existsSync(prdPath) || !fs.statSync(prdPath).isFile())
-        return fail("bundle", `project has no prd.json: companies/${company}/projects/${project}/prd.json`);
+    const stage = projectStage(projectDir);
+    if (stage === "none")
+        return fail("bundle", `project has neither prd.json nor brainstorm.md: companies/${company}/projects/${project} (run /brainstorm or /plan first)`);
     let prd;
-    try {
-        prd = readJsonFile(prdPath);
-    }
-    catch {
-        return fail("bundle", `prd.json is not valid JSON: ${prdPath}`);
+    if (stage === "prd") {
+        try {
+            prd = readJsonFile(prdPath);
+        }
+        catch {
+            return fail("bundle", `prd.json is not valid JSON: ${prdPath}`);
+        }
+        if (prd === null || prd === false)
+            return fail("bundle", `prd.json is not valid JSON: ${prdPath}`);
     }
-    if (prd === null || prd === false)
-        return fail("bundle", `prd.json is not valid JSON: ${prdPath}`);
+    const projectRelative = `companies/${company}/projects/${project}`;
+    const brainstormPath = path.join(projectDir, "brainstorm.md");
+    const brainstormRelative = `${projectRelative}/brainstorm.md`;
     const who = subprocess("hq", ["whoami", "--json"], context.cwd, { stdout: "capture" });
     if (who.code !== 0)
         return fail("bundle", "could not read sender identity; update hq-cli if --json is unsupported");
@@ -283,7 +295,8 @@ function runBundle(args, context, onMalformedWhoami) {
         return fail("bundle", "sender identity is missing or expired; run hq login");
     const fromEmail = text(identityValue.email) || null;
     const fromUid = text(identityValue.personUid) || text(identityValue.agentUid) || null;
-    const knowledge = list(getPath(prd, "metadata.knowledge", [])).filter((entry) => typeof entry === "string").map(String);
+    const knowledge = (stage === "prd" ? list(getPath(prd, "metadata.knowledge", [])) : [])
+        .filter((entry) => typeof entry === "string").map(String);
     const readPrefixes = [...new Set(knowledge.filter((entry) => entry.startsWith(`companies/${company}/`)).map((entry) => {
             const relative = entry.slice(`companies/${company}/`.length);
             if (relative.endsWith("/"))
@@ -297,7 +310,7 @@ function runBundle(args, context, onMalformedWhoami) {
     ].sort((a, b) => a.prefix.localeCompare(b.prefix));
     if (vaultPrefixes.some(({ prefix }) => !prefix.endsWith("/") || prefix.startsWith("companies/")))
         return fail("bundle", "internal error: derived a non-folder or company-anchored prefix");
-    const repoPath = text(getPath(prd, "metadata.repoPath"));
+    const repoPath = stage === "prd" ? text(getPath(prd, "metadata.repoPath")) : "";
     const repo = repoPath ? {
         path: repoPath,
         remote: null,
@@ -312,7 +325,9 @@ function runBundle(args, context, onMalformedWhoami) {
     const board = jsonFile(boardFile);
     if (board) {
         const projects = list(board.projects);
-        const boardEntry = projects.find((entry) => isRecord(entry) && entry.prd_path === `companies/${company}/projects/${project}/prd.json`);
+        const lookupPath = stage === "prd" ? `${projectRelative}/prd.json` : brainstormRelative;
+        const lookupKey = stage === "prd" ? "prd_path" : "brainstorm_path";
+        const boardEntry = projects.find((entry) => isRecord(entry) && entry[lookupKey] === lookupPath);
         if (isRecord(boardEntry) && jqTrue(boardEntry.id))
             boardId = boardEntry.id;
     }
@@ -323,6 +338,9 @@ function runBundle(args, context, onMalformedWhoami) {
     const idTime = createdAt.replace(/[-:TZ]/g, "").slice(0, 8) + "-" + createdAt.slice(11, 19).replaceAll(":", "");
     const delegationId = `dlg-${idTime}-${project}`;
     const policies = knowledge.filter((entry) => entry.startsWith(`companies/${company}/policies/`));
+    const projectManifest = stage === "prd"
+        ? { name: project, stage, prdPath: `${projectRelative}/prd.json`, sourcePath: `${projectRelative}/prd.json`, boardId }
+        : { name: project, stage, prdPath: null, sourcePath: brainstormRelative, boardId, dossier: brainstormDossier(root, projectRelative) };
     const manifest = {
         schemaVersion: 1,
         delegationId,
@@ -331,7 +349,7 @@ function runBundle(args, context, onMalformedWhoami) {
         from: { email: fromEmail, personUid: fromUid },
         to: { kind: toKind, principal: recipient, displayName: toName || null },
         company,
-        project: { name: project, prdPath: `companies/${company}/projects/${project}/prd.json`, boardId },
+        project: projectManifest,
         vaultPrefixes: vaultPrefixes.filter((entry, index, all) => all.findIndex((candidate) => candidate.prefix === entry.prefix) === index),
         repo,
         secrets: [],
@@ -340,6 +358,16 @@ function runBundle(args, context, onMalformedWhoami) {
         checksums,
         status: "building",
     };
+    if (stage === "brainstorm") {
+        const summary = brainstormSummary(brainstormPath) || "No summary recorded in brainstorm.md.";
+        const recommendation = brainstormSection(brainstormPath, "Recommendation");
+        const unknowns = brainstormSection(brainstormPath, "What We Don't Know");
+        const dossierList = projectManifest.dossier
+            .map((entry) => `- \`${entry}\``)
+            .join("\n");
+        const brief = `# Delegation brief — ${project}\n\nThis brief describes the **${project}** project in the **${company}** company. Completed handoff steps are recorded in the manifest. Pull the files and acknowledge receipt; report any access error to the sender.\n\n## What this project is\n\n${summary}\n\n## Where things stand\n\nThis project is at the brainstorm stage. There is no PRD yet and no stories have been written; the source of truth is \`${projectRelative}/brainstorm.md\`, with research notes and the latest session journal alongside it.\n\n${recommendation ? `## Recommendation so far\n\n${recommendation}\n\n` : ""}${unknowns ? `## Open questions\n\n${unknowns}\n\n` : ""}## Recommended next step\n\nRun \`/plan ${project}\` to turn the brainstorm into a PRD with stories. Read brainstorm.md and the research notes first; the recommendation and open questions above come from them.\n\n## Where everything lives\n\nThe dossier for this handoff:\n\n${dossierList}\n\nThe pickup prompt that accompanied this brief pulls every file you need on demand — you do not need to run a full sync.\n`;
+        return writeBundle(context, { manifest, brief, dryRun, project });
+    }
     const description = text(getPath(prd, "description"), "No description recorded.");
     const goal = text(getPath(prd, "metadata.goal"));
     const stories = list(getPath(prd, "userStories", []));
@@ -365,27 +393,54 @@ function runBundle(args, context, onMalformedWhoami) {
     if (traps)
         brief += `\n## Known traps and conventions\n\n${traps}\n`;
     brief += `\n## Where everything lives\n\nThe full PRD (every story, acceptance criteria, and decision history) is at \`companies/${company}/projects/${project}/prd.json\`. The pickup prompt that accompanied this brief pulls every file you need on demand — you do not need to run a full sync.\n`;
-    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-"));
+    return writeBundle(context, { manifest, brief, dryRun, project });
+}
+function writeBundle(context, input) {
+    const root = context.root ?? context.cwd;
+    const { manifest, brief, dryRun, project } = input;
+    const delegationId = jqRawPath(manifest, "delegationId");
+    const destinationParent = path.join(root, "workspace", "delegations");
+    // The shell uses `mktemp -d`, which honors TMPDIR on every supported shell.
+    const stageBase = process.env.TMPDIR || os.tmpdir();
+    const stage = path.join(stageBase, `tmp.${mktempCompatibleSuffix()}`);
+    fs.mkdirSync(stage, { mode: 0o700 });
+    const bundleFileSystem = context.bundleFileSystem ?? fs;
     const manifestFile = path.join(stage, "manifest.json");
     const briefFile = path.join(stage, "BRIEF.md");
-    fs.writeFileSync(manifestFile, jsonText(manifest));
-    fs.writeFileSync(briefFile, brief);
-    if (!secretScan("bundle", [manifestFile, briefFile])) {
-        fs.rmSync(stage, { recursive: true, force: true });
-        return fail("bundle", "generated bundle matched a secret-detection pattern — nothing written (see stderr above)");
-    }
-    if (dryRun) {
-        out(fs.readFileSync(manifestFile, "utf8"));
-        fs.rmSync(stage, { recursive: true, force: true });
-        err("hq-delegate-bundle: dry run — nothing written\n");
+    try {
+        fs.writeFileSync(manifestFile, jsonText(manifest));
+        fs.writeFileSync(briefFile, brief);
+        if (!secretScan("bundle", [manifestFile, briefFile])) {
+            return fail("bundle", "generated bundle matched a secret-detection pattern — nothing written (see stderr above)");
+        }
+        if (dryRun) {
+            out(fs.readFileSync(manifestFile, "utf8"));
+            err("hq-delegate-bundle: dry run — nothing written\n");
+            return 0;
+        }
+        const dest = path.join(destinationParent, delegationId);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        try {
+            bundleFileSystem.renameSync(stage, dest);
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? error.code
+                : undefined;
+            if (code !== "EXDEV" && code !== "EPERM")
+                throw error;
+            // `mv` crosses volumes by recursively copying a directory before
+            // removing the source. copyFileSync cannot handle this directory.
+            bundleFileSystem.cpSync(stage, dest, { recursive: true });
+            bundleFileSystem.rmSync(stage, { recursive: true, force: true });
+        }
+        out(`${delegationId}\n`);
+        err(`hq-delegate-bundle: wrote workspace/delegations/${delegationId}/{manifest.json,BRIEF.md}\n`);
         return 0;
     }
-    const dest = path.join(root, "workspace", "delegations", delegationId);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    moveFile(stage, dest);
-    out(`${delegationId}\n`);
-    err(`hq-delegate-bundle: wrote workspace/delegations/${delegationId}/{manifest.json,BRIEF.md}\n`);
-    return 0;
+    finally {
+        bundleFileSystem.rmSync(stage, { recursive: true, force: true });
+    }
 }
 function runHq(args, context, stdout = "capture") {
     return subprocess("hq", args, context.cwd, { stdout });
@@ -737,22 +792,41 @@ function runPublish(args, context) {
         const bundleDir = path.dirname(path.resolve(manifestPath));
         const brief = path.join(bundleDir, "BRIEF.md");
         const prd = path.join(projectDir, "prd.json");
+        const brainstorm = path.join(projectDir, "brainstorm.md");
+        const stageKind = jqRawPath(manifest, "project.stage", "prd");
         if (!fs.existsSync(brief) || !fs.statSync(brief).isFile())
             return fail("publish", "BRIEF.md missing");
-        if (!fs.existsSync(prd) || !fs.statSync(prd).isFile())
+        if (stageKind === "prd" && (!fs.existsSync(prd) || !fs.statSync(prd).isFile()))
             return fail("publish", "PRD missing");
+        if (stageKind === "brainstorm" && (!fs.existsSync(brainstorm) || !fs.statSync(brainstorm).isFile()))
+            return fail("publish", "brainstorm.md missing");
+        if (stageKind !== "prd" && stageKind !== "brainstorm")
+            return fail("publish", `unknown project stage '${stageKind}'`);
         if (jqRawPath(manifest, "mode") === "transfer") {
             const expectedOwner = jqRawPath(manifest, "to.principal");
-            const prdValue = jsonFile(prd);
-            if (!prdValue || jqRawPath(prdValue, "metadata.owner") !== expectedOwner)
-                return fail("publish", "local PRD owner does not match recipient");
+            if (stageKind === "prd") {
+                const prdValue = jsonFile(prd);
+                if (!prdValue || jqRawPath(prdValue, "metadata.owner") !== expectedOwner)
+                    return fail("publish", "local PRD owner does not match recipient");
+            }
+            else if (brainstormFrontmatterGet(brainstorm, "owner") !== expectedOwner)
+                return fail("publish", "local brainstorm.md owner does not match recipient");
         }
         stage = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-"));
         const stagedBrief = path.join(stage, "BRIEF.md");
         fs.copyFileSync(brief, stagedBrief);
         const hashFile = path.join(stage, "hashes");
         const hashed = {};
-        for (const file of [prd, path.join(projectDir, "README.md"), path.join(projectDir, "journal", "delegations.md")]) {
+        const snapshotFiles = stageKind === "prd"
+            ? [prd, path.join(projectDir, "README.md"), path.join(projectDir, "journal", "delegations.md")]
+            : [...list(getPath(manifest, "project.dossier", [])).map((entry) => path.join(root, text(entry))), path.join(projectDir, "journal", "delegations.md")];
+        if (stageKind === "brainstorm") {
+            for (const file of snapshotFiles.slice(0, -1)) {
+                if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+                    return fail("publish", `dossier file missing: ${path.relative(root, file).split(path.sep).join("/")}`);
+            }
+        }
+        for (const file of snapshotFiles) {
             if (fs.existsSync(file) && fs.statSync(file).isFile()) {
                 const key = path.relative(root, file).split(path.sep).join("/");
                 hashed[key] = checksum(file);
@@ -891,10 +965,20 @@ function runSend(args, context) {
         const prdRelative = jqRawPath(manifest, "project.prdPath");
         const prdAbs = path.join(root, prdRelative);
         const prd = fs.existsSync(prdAbs) ? jsonFile(prdAbs) : undefined;
+        const stageKind = jqRawPath(manifest, "project.stage", "prd");
+        const brainstormAbs = path.join(root, "companies", company, "projects", project, "brainstorm.md");
         let goal = "";
         let stateLine = "";
         let nextSteps = "";
-        if (prd) {
+        let dossierLine = `Start with the project dossier: \`companies/${company}/projects/${project}/\` now contains the PRD (\`prd.json\`), a full brief (\`README.md\` / the DM's details pane), and the delegation journal.`;
+        if (stageKind === "brainstorm") {
+            if (fs.existsSync(brainstormAbs))
+                goal = brainstormSummary(brainstormAbs);
+            stateLine = `This project is at the brainstorm stage: no PRD yet, no stories. The source of truth is \`companies/${company}/projects/${project}/brainstorm.md\`.`;
+            nextSteps = `1. **Read the brainstorm** — \`brainstorm.md\`, the notes under \`research/\`, and the latest journal entry under \`journal/\`.\n2. **Turn it into a PRD** — run \`/plan ${project}\` to write \`prd.json\` with stories.\n3. **Start the first story** — once the PRD exists, \`/run-project ${project}\` or \`/execute-task\` picks it up.`;
+            dossierLine = `Start with the project dossier: \`companies/${company}/projects/${project}/\` contains \`brainstorm.md\`, the \`research/\` notes, the latest journal entry, a full brief (the DM's details pane), and the delegation journal. There is no \`prd.json\` yet.`;
+        }
+        else if (prd) {
             goal = text(jqFallback(getPath(prd, "metadata.goal"), getPath(prd, "description", "")));
             const stories = list(getPath(prd, "userStories", []));
             const complete = stories.filter((entry) => isRecord(entry) && entry.passes === true).length;
@@ -935,7 +1019,7 @@ function runSend(args, context) {
             body += `## The goal\n\n${goal}\n\n`;
         if (stateLine)
             body += `## Where things stand\n\n${stateLine}\n\n`;
-        body += `## Pull the files (on demand — no sync)\n\nRun these from your HQ root; each materializes exactly that path locally:\n\n\`\`\`bash\n${getLines}\n\`\`\`\n\nStart with the project dossier: \`companies/${company}/projects/${project}/\` now contains the PRD (\`prd.json\`), a full brief (\`README.md\` / the DM's details pane), and the delegation journal.\n\n`;
+        body += `## Pull the files (on demand — no sync)\n\nRun these from your HQ root; each materializes exactly that path locally:\n\n\`\`\`bash\n${getLines}\n\`\`\`\n\n${dossierLine}\n\n`;
         if (repoSection)
             body += `${repoSection}\n\n`;
         if (secretsSection)
@@ -1090,7 +1174,17 @@ function runVerify(args, context) {
             secretNames = names.length ? `${names.join(" ")} ` : "(none declared)";
         }
         out("Delegation dry run — nothing will be pushed, granted, transferred, or sent.\n\n");
-        out(`  Recipient:  ${recipient}\n  Mode:       ${mode}\n  Company:    ${company}\n  Project:    ${project}\n\n`);
+        const stageKind = jqRawPath(manifest, "project.stage", "prd");
+        out(`  Recipient:  ${recipient}\n  Mode:       ${mode}\n  Company:    ${company}\n  Project:    ${project}\n`);
+        if (stageKind === "brainstorm") {
+            out(`  Stage:      brainstorm — no PRD yet; source of truth is brainstorm.md; recommended next step is /plan ${project}\n\n`);
+            out("  Dossier files that would be published:\n");
+            for (const file of list(getPath(manifest, "project.dossier", [])))
+                out(`    ${text(file)}\n`);
+        }
+        else
+            out("  Stage:      prd\n");
+        out("\n");
         out("  Vault grants that would be written:\n");
         for (const entry of list(getPath(manifest, "vaultPrefixes", [])))
             out(`    ${jqRawPath(entry, "permission")}\ton ${jqRawPath(entry, "prefix")}\t(${jqRawPath(entry, "reason")})\n`);

package/dist/commands/core-delegate.d.ts

@@ -7,8 +7,10 @@ export type DelegateContext = {
     cwd: string;
     root?: string;
     atomicWriteFileSystem?: DelegateAtomicWriteFileSystem;
+    bundleFileSystem?: DelegateBundleFileSystem;
 };
 export type DelegateAtomicWriteFileSystem = Pick<typeof fs, "openSync" | "writeFileSync" | "closeSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync">;
+export type DelegateBundleFileSystem = Pick<typeof fs, "renameSync" | "cpSync" | "rmSync">;
 type CommandResult = {
     code: number;
     stdout?: string;