@indigoai-us/hq-cli 5.345.88 → 5.345.90

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;

package/dist/commands/core-delegate.js

@@ -11,6 +11,7 @@ import { buildCmdExeSpawnPlan, isWindowsBatchFile } from "../utils/windows-spawn
 import { describeCoreCommand } from "./core-command-catalog.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
+import { brainstormFrontmatterSet, brainstormSummary, brainstormTitle } from "./core-delegate-brainstorm.js";
 export const CORE_NATIVE_DELEGATE_FLAG = "core-native-delegate";
 const SCRIPT_ASSETS = {
     resolve: "core/scripts/hq-delegate-resolve.sh",
@@ -52,7 +53,7 @@ const USAGE_TEXT = {
     pickup: "# hq-core: public\n# hq-delegate-pickup.sh — close the delegation loop with a receipt or a FAILED\n# state (2026-09-07).\n#\n# Why: the delegate pipeline ended at \"sent\", which is a send receipt, not a\n# delivery receipt. Seven delegations sat at sent/building with no way to tell\n# whether the recipient could act. This script adds the two missing states:\n#\n#   sent --(evidence)--> picked-up      recipient demonstrably has the work\n#   sent --(silence past window)--> failed   nobody picked it up; sender is told why\n#\n# Evidence, checked in order (any one suffices):\n#   1. --ack \"<text>\"            an explicit acknowledgement (DM reply, chat) —\n#                                recorded verbatim with a timestamp\n#   2. repo branch has a commit by the recipient after sentAt\n#      (manifest.repo.path + repo.branch, author email == to.principal)\n#   3. --evidence \"<free text>\"  any other proof the operator observed\n#\n# Usage:\n#   hq-delegate-pickup.sh --manifest <path> --ack \"<text>\"        # record receipt\n#   hq-delegate-pickup.sh --manifest <path> --evidence \"<text>\"   # record receipt\n#   hq-delegate-pickup.sh --manifest <path> --check [--window-hours N]   # probe repo; fail if silent past window (default 72)\n#   hq-delegate-pickup.sh --manifest <path> --status               # print state line\n#\n# Exit 0: picked-up (or already). Exit 5: failed (window elapsed, no evidence).\n# Exit 6: still waiting (inside window, no evidence). Exit 2: usage/precondition.\nset -uo pipefail\n",
     repo: "hq-delegate-repo.sh — code/branch handover for a delegation: make sure the\nproject's branch exists on the remote, record uncommitted work as NOT\ntransferred, and verify the recipient's repository access read-only.\n\nUsage:\n  core/scripts/hq-delegate-repo.sh --manifest <path> [--yes] [--github-user <login>]\n\nBehavior (driven by the manifest's repo{} block; no-op when repo is null):\n  - records remote URL and the branch's headSha into the manifest\n  - a branch that exists only locally requires confirmation: without --yes\n    the helper prints the plan and exits 2; with --yes it pushes via an\n    explicitly anchored `git -C <abs path> push -u origin <branch>`\n  - dirty/untracked files are captured into repo.dirtyFiles[] and appended\n    to BRIEF.md as work NOT transferred — never silently dropped\n  - recipient access is checked read-only via gh when --github-user is\n    given; otherwise (or on a gh failure) repo.accessVerified stays false\n    and the brief says so plainly — the helper never claims unverified access\n  - never touches vaultPrefixes[] and never pushes repo content to the vault\n\nEnv: HQ_ROOT — HQ root override (default: resolved from script location)\n",
     secrets: "hq-delegate-secrets.sh — grant a delegation recipient access to the secrets\na project needs, BY NAME ONLY. No command in this helper ever reads,\nprints, logs, or interpolates a secret value.\n\nUsage:\n  core/scripts/hq-delegate-secrets.sh --manifest <path> [--yes] [--no-secrets]\n    [--env-schema <path>]\n\nBehavior:\n  - derives required secret NAMES from the project's / repo's .env.schema\n    (--env-schema overrides discovery); no schema -> records secrets: []\n    and says so plainly rather than guessing at credentials\n  - without --yes: prints a full-prose confirmation listing every name and\n    the principal, then exits 2 granting nothing — this step is a privilege\n    handover and gets its own confirmation, separate from the file grants\n  - with --yes: hq secrets share <NAME> --with <principal> --permission read\n    per name, then records the names (and only the names) in the manifest\n  - --no-secrets: skips everything, records {secrets: [], secretsSkipped: true}\n\nConsumption on the recipient's side is via `hq run` / `hq secrets exec` —\ndocumented in the brief; values never appear in any delegation artifact\n(policy hq-delegate-never-inlines-secrets-or-share-urls).\n",
-    transfer: "hq-delegate-transfer.sh — make a delegation real everywhere HQ tracks\nownership: board entry, PRD metadata, work mesh, and the project journal.\n\nUsage:\n  core/scripts/hq-delegate-transfer.sh --manifest <path>\n\nBehavior (mode \"transfer\"; mode \"share\" skips every mutation):\n  1. companies/<co>/board.json — the project's entry gets owner=<recipient>\n     and a bumped updated_at; created (once) if absent\n  2. prd.json metadata gains owner, delegatedFrom, delegatedAt\n  3. work-mesh: `done` event closes the delegator's in-progress thread and\n     broadcasts the reassignment; silently skipped when the helper is\n     unavailable (local/offline installs) — the transfer still succeeds\n  4. a dated \"Delegated\" stanza is appended to the project journal naming\n     the recipient, delegation id, and transferred scope\n\nIdempotent: re-running updates owner/timestamps in place — never a\nduplicate board entry, never a duplicated journal stanza.\n\nThe delegator's own vault access is untouched (granting the recipient\nwrite does not revoke anything).\n\nEnv: HQ_ROOT — HQ root override (default: resolved from script location)\n",
+    transfer: "hq-delegate-transfer.sh — make a delegation real everywhere HQ tracks\nownership: board entry, PRD metadata, work mesh, and the project journal.\n\nUsage:\n  core/scripts/hq-delegate-transfer.sh --manifest <path>\n\nBehavior (mode \"transfer\"; mode \"share\" skips every mutation):\n  1. companies/<co>/board.json — the project's entry gets owner=<recipient>\n     and a bumped updated_at; created (once) if absent. A brainstorm-stage\n     entry (status exploring, brainstorm_path set) is matched by\n     brainstorm_path and keeps its status.\n  2. prd.json metadata gains owner, delegatedFrom, delegatedAt; for a\n     brainstorm-stage project the same three keys land in the\n     brainstorm.md frontmatter (owner, delegated_from, delegated_at)\n  3. work-mesh: `done` event closes the delegator's in-progress thread and\n     broadcasts the reassignment; silently skipped when the helper is\n     unavailable (local/offline installs) — the transfer still succeeds\n  4. a dated \"Delegated\" stanza is appended to the project journal naming\n     the recipient, delegation id, and transferred scope\n\nIdempotent: re-running updates owner/timestamps in place — never a\nduplicate board entry, never a duplicated journal stanza.\n\n",
 };
 function usage(name) {
     return USAGE_TEXT[name];
@@ -189,7 +190,6 @@ export function moveFile(source, target, fileSystem = fs) {
 }
 export function writeJsonAtomically(target, value, siblingTemp = false, fileSystem = fs) {
     const serialized = serializeJqJson(value, "pretty");
-    // Native delegate JSON writers use LF on every platform.
     if (siblingTemp) {
         const temporary = `${target}.tmp.${randomBytes(6).toString("hex")}`;
         let fd;
@@ -918,14 +918,25 @@ function runTransfer(args, context) {
     }
     const now = jqRawPath(document, "ownershipTransferredAt") || new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
     const today = (process.env.HQ_DELEGATE_NOW || new Date().toISOString()).slice(0, 10);
+    const stage = jqRawPath(document, "project.stage", "prd");
     const prdPath = `companies/${company}/projects/${project}/prd.json`;
     const prdAbs = path.join(root, prdPath);
+    const brainstormPath = `companies/${company}/projects/${project}/brainstorm.md`;
+    const brainstormAbs = path.join(root, brainstormPath);
     const projectDir = path.join(root, "companies", company, "projects", project);
     const board = path.join(root, "companies", company, "board.json");
-    if (!fs.existsSync(prdAbs) || !fs.statSync(prdAbs).isFile()) {
+    if (stage !== "prd" && stage !== "brainstorm") {
+        writeErr(`${prefix} manifest project.stage is '${stage}' — expected prd or brainstorm\n`);
+        return 1;
+    }
+    if (stage === "prd" && (!fs.existsSync(prdAbs) || !fs.statSync(prdAbs).isFile())) {
         writeErr(`${prefix} prd not found: ${prdPath}\n`);
         return 1;
     }
+    if (stage === "brainstorm" && (!fs.existsSync(brainstormAbs) || !fs.statSync(brainstormAbs).isFile())) {
+        writeErr(`${prefix} brainstorm.md not found: ${brainstormPath}\n`);
+        return 1;
+    }
     if (fs.existsSync(board)) {
         if (!jqValid(board)) {
             writeErr(`${prefix} board.json is not valid JSON: ${board}\n`);
@@ -936,9 +947,9 @@ function runTransfer(args, context) {
         fs.mkdirSync(path.dirname(board), { recursive: true });
         fs.writeFileSync(board, '{"projects": []}\n');
     }
-    const prd = readJsonFile(prdAbs);
-    const title = jqRawPath(prd, "name");
-    const descriptionValue = jqFallback(jsonAt(prd, "description"), "");
+    const prd = stage === "prd" ? readJsonFile(prdAbs) : undefined;
+    const title = stage === "prd" ? jqRawPath(prd, "name") : brainstormTitle(brainstormAbs);
+    const descriptionValue = stage === "prd" ? jqFallback(jsonAt(prd, "description"), "") : brainstormSummary(brainstormAbs);
     const description = Buffer.from(serializeJqJson(descriptionValue, "raw"), "utf8")
         .subarray(0, 300).toString("utf8").replace(/\n+$/, "");
     const boardDocument = readJsonFile(board);
@@ -948,35 +959,46 @@ function runTransfer(args, context) {
     const projects = Array.isArray(projectsValue)
         ? projectsValue
         : isRecord(projectsValue) ? Object.values(projectsValue) : [];
-    const hasProject = projects.some((entry) => jsonAt(entry, "prd_path") === prdPath);
+    const matchPath = stage === "prd" ? prdPath : brainstormPath;
+    const hasProject = projects.some((entry) => jsonAt(entry, stage === "prd" ? "prd_path" : "brainstorm_path") === matchPath);
     if (hasProject) {
-        boardDocument.projects = projects.map((entry) => jsonAt(entry, "prd_path") === prdPath && isRecord(entry)
+        boardDocument.projects = projects.map((entry) => jsonAt(entry, stage === "prd" ? "prd_path" : "brainstorm_path") === matchPath && isRecord(entry)
             ? { ...entry, owner: principal, updated_at: now }
             : entry);
     }
     else {
-        boardDocument.projects = [...projects, {
-                id: `proj-${project}`,
-                title,
-                description,
-                status: "in_progress",
-                owner: principal,
-                prd_path: prdPath,
-                created_at: now,
-                updated_at: now,
-            }];
+        const entry = {
+            id: `proj-${project}`,
+            title,
+            description,
+            status: stage === "prd" ? "in_progress" : "exploring",
+            owner: principal,
+            prd_path: stage === "prd" ? prdPath : null,
+            created_at: now,
+            updated_at: now,
+        };
+        if (stage === "brainstorm")
+            entry.brainstorm_path = brainstormPath;
+        boardDocument.projects = [...projects, entry];
     }
     boardDocument.updated_at = now;
     writeJsonAtomically(board, boardDocument);
-    if (!isRecord(prd))
-        throw new TypeError("Cannot update non-object prd.json");
-    if (!isRecord(prd.metadata))
-        prd.metadata = {};
-    const metadata = prd.metadata;
-    metadata.owner = principal;
-    metadata.delegatedFrom = from;
-    metadata.delegatedAt = now;
-    writeJsonAtomically(prdAbs, prd);
+    if (stage === "prd") {
+        if (!isRecord(prd))
+            throw new TypeError("Cannot update non-object prd.json");
+        if (!isRecord(prd.metadata))
+            prd.metadata = {};
+        const metadata = prd.metadata;
+        metadata.owner = principal;
+        metadata.delegatedFrom = from;
+        metadata.delegatedAt = now;
+        writeJsonAtomically(prdAbs, prd);
+    }
+    else {
+        brainstormFrontmatterSet(brainstormAbs, "owner", principal);
+        brainstormFrontmatterSet(brainstormAbs, "delegated_from", from);
+        brainstormFrontmatterSet(brainstormAbs, "delegated_at", now);
+    }
     if (commandExists("hq", context.cwd)) {
         const sessionId = process.env.HQ_SESSION_ID || "delegate";
         const mesh = subprocess("hq", ["mesh", "session", "note", "--enqueue", "--session-id", sessionId, "--seq", "1", "--harness", "claude-code", "--adapter-version", "1.0.0", "--company-slug", company, "--project", project, "--summary", `Delegated to ${display} (${principal}) — delegation ${delegationId}; ownership transferred`], context.cwd, { stdout: "inherit" });
@@ -993,12 +1015,17 @@ function runTransfer(args, context) {
         const prefixesValue = jqFallback(document.vaultPrefixes, []);
         const vaultPrefixes = Array.isArray(prefixesValue) ? prefixesValue : [];
         const scope = vaultPrefixes.map((entry) => jqRawPath(entry, "prefix")).join(", ");
-        fs.appendFileSync(journal, `\n## ${today} — Delegated to ${display}\n\n- Delegation: \`${delegationId}\`\n- From: ${from}\n- To: ${display} (${principal})\n- Transferred scope: ${scope}\n- Local board and PRD ownership updated; Work Mesh ownership is unconfirmed. Existing delegator access is unchanged.\n`);
+        const ownershipLine = stage === "prd"
+            ? "Local board and PRD ownership updated; Work Mesh ownership is unconfirmed. Existing delegator access is unchanged."
+            : "Brainstorm-stage project (no PRD yet). Local board and brainstorm.md ownership updated; Work Mesh ownership is unconfirmed. Existing delegator access is unchanged.";
+        fs.appendFileSync(journal, `\n## ${today} — Delegated to ${display}\n\n- Delegation: \`${delegationId}\`\n- From: ${from}\n- To: ${display} (${principal})\n- Transferred scope: ${scope}\n- ${ownershipLine}\n`);
     }
     document.ownershipTransferredAt = now;
     document.workMeshOwnership = "unconfirmed";
     writeJsonAtomically(file, document);
-    writeOut(`${prefix} ownership of '${project}' transferred to ${display} (${principal}) — local board, PRD, and journal updated; Work Mesh ownership unconfirmed\n`);
+    const sourceLabel = stage === "prd" ? "PRD" : "brainstorm.md";
+    const stageLabel = stage === "prd" ? "" : " (brainstorm stage)";
+    writeOut(`${prefix} ownership of '${project}'${stageLabel} transferred to ${display} (${principal}) — local board, ${sourceLabel}, and journal updated; Work Mesh ownership unconfirmed\n`);
     return 0;
 }
 function runNative(name, args, context) {

package/dist/commands/core.js

@@ -268,6 +268,7 @@ export const SCAFFOLD_ONLY_ASSETS = [
     { asset: "core/scripts/lib/session-scope-capability.sh", root: "live", summary: "Session scope-capability lib sourced by hq-session" },
     { asset: "core/scripts/lib/session-id.sh", root: "live", summary: "Session-id resolver lib sourced by hq-session" },
     { asset: "core/scripts/lib/hq-cli-floor.sh", root: "live", summary: "Shared CLI version-floor helper sourced by generated forwarders" },
+    { asset: "core/scripts/lib/delegate-brainstorm.sh", root: "live", summary: "Shared brainstorm-stage data helper sourced by delegate assets" },
     { asset: "core/scripts/lib/forwarder.sh", root: "live", summary: "Shared runtime sourced by generated scaffold forwarders" },
     { asset: "core/scripts/lib/work-mesh-enqueue.sh", root: "live", summary: "Work Mesh Live spool enqueue lib sourced by hooks" },
     { asset: "core/scripts/lib/work-mesh-live-hook.sh", root: "live", summary: "Work Mesh Live hook helpers sourced by rebind" },

package/dist/lib/bot/dm-history.d.ts

@@ -0,0 +1,37 @@
+import { type BotSessionScope } from "./paths.js";
+export declare const DM_HISTORY_MAX_ENTRIES = 40;
+export interface DmHistoryMessage {
+    role: "user" | "assistant";
+    from: string;
+    fromPersonUid?: string;
+    body: string;
+    at: string;
+    eventId?: string;
+}
+export interface DmHistoryFile {
+    v: 1;
+    messages: DmHistoryMessage[];
+    updatedAt: string;
+    /** Successful model turns in this DM. Used to inject history only after a session has existed. */
+    modelTurns?: number;
+}
+export declare function readDmHistory(dir: string, scope: BotSessionScope): DmHistoryFile;
+export declare function writeDmHistory(dir: string, scope: BotSessionScope, history: DmHistoryFile): void;
+/** Record a message, skipping duplicates by eventId and trimming the oldest past the cap. Pure. */
+export declare function withDmHistoryMessage(history: DmHistoryFile, message: DmHistoryMessage, cap?: number): DmHistoryFile;
+export declare function appendDmHistory(dir: string, scope: BotSessionScope, message: DmHistoryMessage, cap?: number): DmHistoryFile;
+/** Count a successful model turn so a later new session knows there is thread to restore. */
+export declare function markDmHistoryModelTurn(dir: string, scope: BotSessionScope, at: string): void;
+export declare function dmHistoryHasModelThread(history: DmHistoryFile): boolean;
+export declare function formatDmHistoryLines(messages: readonly DmHistoryMessage[], opts: {
+    excludeEventId?: string;
+    limit: number;
+    maxChars: number;
+}): string[];
+/** Prefix a DM turn with a "Recent messages:" block. Empty history leaves the prompt unchanged. */
+export declare function withRecentDmHistory(prompt: string, messages: readonly DmHistoryMessage[], opts: {
+    excludeEventId?: string;
+    limit: number;
+    maxChars: number;
+}): string;
+//# sourceMappingURL=dm-history.d.ts.map