flowviant 0.30.0 → 0.31.0

package/bin/lib/claude.mjs

@@ -271,6 +271,44 @@ Steps:
 Ground every claim in files you actually read. Be efficient — look only at the
 changed area, not the whole repo; spend little quota.`;
 
+/**
+ * CONSULT — someone is planning and asked a question only the repo can answer.
+ *
+ * Strictly read-only, and strictly an ANSWER: no edits, no commits, no branch,
+ * no MCP tools. A consult is not a dispatch, and the prompt says so out loud
+ * because the model is otherwise very willing to start building the thing it was
+ * asked about.
+ */
+export const SYSTEM_CONSULT = `You are a Flowviant build agent, but you are NOT building anything right now.
+Someone is PLANNING a feature and has asked you a question, because you are the
+one with the actual repository in front of you. The planner they are talking to
+sees only a module manifest and wiki summaries — you see the code.
+
+Your entire job is to ANSWER, from files you actually read.
+
+RULES:
+- READ ONLY. Do not edit, create or delete any file. No git writes, no commits,
+  no branches, no PRs. Nothing you do here leaves a trace in the repo.
+- Do NOT start implementing what they are planning, and do not offer to. If the
+  answer is "this needs building", say that and stop — they will dispatch it in
+  its own task thread when they are ready.
+- Ground every claim in something you opened. Cite concrete paths
+  (\`apps/api/src/middleware/auth.ts\`) so the answer can be checked.
+- If it already EXISTS, say so plainly and point at it — that is the single most
+  valuable thing you can tell someone mid-plan, and it is the answer they are
+  least expecting.
+- If the repo genuinely does not settle the question, say THAT rather than
+  guessing. "I can't tell from the code" is a real answer and a useful one.
+- Be brief: a few sentences, or a short list. This lands in a chat thread that a
+  human is reading while they think, not in a document.
+
+Write plain Markdown for a person. No preamble, no restating the question.`;
+
+export const CONSULT_KICKOFF = ({ planTitle, question, askedByName }) =>
+  `${askedByName || 'A teammate'} is planning ${planTitle ? `"${planTitle}"` : 'a feature'} and asked you:\n\n` +
+  `${question}\n\n` +
+  `Read the repo you are running in and answer. Do not change anything.`;
+
 export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages = [] }) =>
   `A feature just merged. Re-ground the knowledge vault (${vaultDir}) for it.\n\n` +
   `Feature: ${title}\n` +

package/bin/lib/fleet.mjs

@@ -54,6 +54,8 @@ import {
   SYSTEM_PLAN_CHECK,
   PLAN_CHECK_KICKOFF,
   REGROUND_KICKOFF,
+  SYSTEM_CONSULT,
+  CONSULT_KICKOFF,
 } from './claude.mjs';
 import { runLiveWorker } from './live.mjs';
 import { reapOrphanPreviews } from './preview.mjs';
@@ -402,6 +404,19 @@ export async function runFleetDaemon() {
     return null;
   };
 
+  /** A clean detached checkout at base — what "the real code" has to mean for a
+   *  question about the repo, rather than whatever half-finished state an agent
+   *  worktree happens to be in. Shared by the plan check and consults. */
+  const ensureWikiWorktree = () => {
+    if (existsSync(wikiWt)) return;
+    try {
+      git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+    } catch {
+      git(['worktree', 'prune'], repoRoot);
+      git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
+    }
+  };
+
   const PLAN_CHECK_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/plan-check-done');
   const checkingPlans = new Set();
   const processPlanCheckJobs = (jobs) => {
@@ -413,17 +428,7 @@ export async function runFleetDaemon() {
       (async () => {
         try {
           note(`${c.cyan('plan')} ${c.dim(`— checking "${job.title}" against your code…`)}`);
-          // Reuse the wiki worktree: a clean detached checkout at base, which is
-          // what "the real code" should mean here — not whatever half-finished
-          // state an agent worktree happens to be in.
-          if (!existsSync(wikiWt)) {
-            try {
-              git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
-            } catch {
-              git(['worktree', 'prune'], repoRoot);
-              git(['worktree', 'add', '--detach', wikiWt, baseRef], repoRoot);
-            }
-          }
+          ensureWikiWorktree();
           const out = await runTurn({
             prompt: PLAN_CHECK_KICKOFF({ title: job.title, intents: job.intents }),
             resume: false,
@@ -456,6 +461,57 @@ export async function runFleetDaemon() {
     }
   };
 
+  // Consults — a planning question aimed at THIS machine, answered by reading
+  // the repo. Deliberately the lightest job on the roster: same read-only
+  // detached checkout the plan check uses, no MCP, no writes, no run recorded.
+  const CONSULT_DONE_URL = FLEET_URL.replace(/\/agents\/?$/, '/consult-done');
+  const answering = new Set();
+  const processConsultJobs = (jobs) => {
+    for (const job of jobs ?? []) {
+      if (!job || typeof job.id !== 'string' || !job.question) continue;
+      if (answering.has(job.id)) continue;
+      answering.add(job.id);
+      (async () => {
+        try {
+          note(`${c.cyan('ask')} ${c.dim(`— ${job.askedByName || 'someone'} asked about "${job.planTitle || 'a plan'}"`)}`);
+          ensureWikiWorktree();
+          const out = await runTurn({
+            prompt: CONSULT_KICKOFF({
+              planTitle: job.planTitle,
+              question: job.question,
+              askedByName: job.askedByName,
+            }),
+            resume: false,
+            system: SYSTEM_CONSULT,
+            cwd: wikiWt,
+            wikiPerm: true, // read-only file perms — no MCP, no shell writes
+            label: c.cyan('[ask]'),
+          });
+          const answer = (out || '').trim();
+          await reportMergeOutcome(CONSULT_DONE_URL, {
+            consultId: job.id,
+            ok: answer.length > 0,
+            // Scrub: an answer can quote config or env-adjacent code.
+            answer: envScrub(answer).slice(0, 8000),
+          });
+          ok(`${c.cyan('ask')} ${c.dim('— answered in the plan thread')}`);
+        } catch (e) {
+          // Settle it either way. A question that cannot be answered must not
+          // re-burn a Claude turn on every poll, and silence would leave the
+          // human waiting on a machine that already gave up.
+          await reportMergeOutcome(CONSULT_DONE_URL, {
+            consultId: job.id,
+            ok: false,
+            answer: e?.message ?? 'the read failed',
+          });
+          warn(`consult failed: ${e?.message ?? e}`);
+        } finally {
+          answering.delete(job.id);
+        }
+      })();
+    }
+  };
+
   const processMergeJobs = (jobs) => {
     for (const job of jobs ?? []) {
       if (!job || typeof job.id !== 'string') continue; // a null element would wedge the loop
@@ -1022,6 +1078,7 @@ export async function runFleetDaemon() {
     processMergeJobs(roster.mergeJobs);
     processPatchRevertJobs(roster.patchRevertJobs);
     processPlanCheckJobs(roster.planCheckJobs);
+    processConsultJobs(roster.consultJobs);
     processCleanupJobs(roster.cleanupJobs);
     const rosterIds = new Set(roster.agents.map((a) => a.agentId));
 

package/bin/lib/live.mjs

@@ -172,12 +172,35 @@ questions, delivery summaries, commits, or PRs — reference keys by NAME only
 (e.g. "set STRIPE_KEY"). Never screenshot a terminal or page that displays a
 credential, and never commit an env file.`;
 
-/** The brief minus the conversation — that is rendered as prose, not JSON. */
+/** The brief minus the parts rendered as prose below (conversations, the ask). */
 function briefWithoutThread(brief) {
-  const { thread: _thread, lastMessageId: _lastMessageId, ...rest } = brief ?? {};
+  const {
+    thread: _thread,
+    lastMessageId: _lastMessageId,
+    plan: _plan,
+    asked: _asked,
+    ...rest
+  } = brief ?? {};
   return rest;
 }
 
+/** The plan this task was carved out of, when there was one. A slice cannot
+ *  reconstruct WHY it was cut this way from its own spec. */
+function planContext(brief) {
+  const plan = brief?.plan;
+  if (!plan) return [];
+  const turns = (plan.recentTurns ?? [])
+    .map((m) => `${m.authorName || m.role}: ${m.content}`)
+    .join('\n');
+  return [
+    ``,
+    `This task is ONE SLICE of a larger plan: "${plan.title || 'untitled plan'}".`,
+    plan.description ? `The plan:\n${plan.description}` : '',
+    turns ? `How the team was talking about it, most recent last:\n${turns}` : '',
+    `Build only YOUR slice — the rest is there so its shape makes sense.`,
+  ].filter(Boolean);
+}
+
 function seedPrompt(runId, brief, transcript, resumedInPlace) {
   return [
     `Your run id is ${runId}. Use it for every flowviant MCP tool call.`,
@@ -193,6 +216,17 @@ function seedPrompt(runId, brief, transcript, resumedInPlace) {
     // The conversation is rendered below as readable turns, not dumped twice as
     // JSON — it is the longest thing in the brief and the least useful as data.
     JSON.stringify(briefWithoutThread(brief), null, 2),
+    ...(brief?.asked
+      ? [
+          ``,
+          `What the human originally asked for, in their words:`,
+          `  "${brief.asked}"`,
+          `The specification above is someone's reading of that sentence, written`,
+          `without access to the repo. Where the two disagree, this is the one with`,
+          `a person behind it — say so rather than quietly picking one.`,
+        ]
+      : []),
+    ...planContext(brief),
     ...(transcript
       ? [
           ``,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {