perchai-cli 2.4.33 → 2.4.34

package/dist/perch.mjs

@@ -75566,6 +75566,7 @@ var init_payroll = __esm({
 // lib/perchBusinessTools/index.ts
 var init_perchBusinessTools = __esm({
   "lib/perchBusinessTools/index.ts"() {
+    "use strict";
     init_generateAPAuditPacket();
     init_inventoryFolder();
     init_loadBusinessTables();
@@ -76218,6 +76219,7 @@ function getToolDisplayName(toolName) {
 var NON_MODULE_TOOL_OWNERS, TOOL_RISK, TOOL_DISPLAY_NAMES;
 var init_catalog = __esm({
   "features/perchTerminal/runtime/toolSystem/catalog.ts"() {
+    "use strict";
     init_toolNames();
     NON_MODULE_TOOL_OWNERS = {
       [TOOL_NAMES.listSources]: "lane",
@@ -83125,7 +83127,6 @@ function listFinancialRoleIds() {
 var FINANCIAL_ROLE_REGISTRY, evidenceScoutManifest;
 var init_financialRoles = __esm({
   "features/perchTerminal/agentPlatform/financialRoles.ts"() {
-    "use strict";
     FINANCIAL_ROLE_REGISTRY = /* @__PURE__ */ new Map();
     evidenceScoutManifest = {
       workerId: "evidence_scout",
@@ -86723,6 +86724,7 @@ function truncateHistoryLine(value, max2) {
 }
 var init_operatorTruth = __esm({
   "features/perchTerminal/runtime/operatorTruth.ts"() {
+    "use strict";
   }
 });
 
@@ -135928,13 +135930,38 @@ function getDesktopToolDefinitions() {
       type: "function",
       function: {
         name: TOOL_NAMES.spawnWorker,
-        description: "Spawn one bounded specialist sub-agent. Use simple capability-shaped workers when possible: source_reader for scoped local-file evidence, math_checker for exact sandbox totals/reconciliation, contradiction_verifier for conflict checks, financial_writer/general_writer for narrative from provided facts. Best for independent work where the main loop only needs the conclusion. Do not use context-only managed analysts as raw-folder readers; give them pre-read JSON. The main loop remains owner of decisions, writing, and real actions. Prefer dispatch_agent for parallel batches. Do not repeat source_reader after it returns a DONE/PARTIAL manifest; advance to math_checker or verification.",
+        description: "Spawn one bounded specialist sub-agent. Use simple capability-shaped workers when possible: source_reader for scoped local-file evidence, math_checker for exact sandbox totals/reconciliation, contradiction_verifier for conflict checks, financial_writer/general_writer for narrative from provided facts. When no registered worker fits, pass custom{} instead of workerId to spawn a one-off ad-hoc worker with its own name and minimal tool scope. Best for independent work where the main loop only needs the conclusion. Do not use context-only managed analysts as raw-folder readers; give them pre-read JSON. The main loop remains owner of decisions, writing, and real actions. Prefer dispatch_agent for parallel batches. Do not repeat source_reader after it returns a DONE/PARTIAL manifest; advance to math_checker or verification.",
         parameters: {
           type: "object",
           properties: {
             workerId: {
               type: "string",
-              description: "Registered worker or role id. Simple roles: source_reader, math_checker, contradiction_verifier, financial_writer, general_writer. Quill roles: legal_source_scout, legal_case_scout, source_verifier, doc_writer, email_sender, calendar_scheduler."
+              description: "Registered worker or role id. Simple roles: source_reader, math_checker, contradiction_verifier, financial_writer, general_writer. Quill roles: legal_source_scout, legal_case_scout, source_verifier, doc_writer, email_sender, calendar_scheduler. Omit when passing custom."
+            },
+            custom: {
+              type: "object",
+              description: "Inline ad-hoc worker spec, used INSTEAD of workerId when no registered worker fits. The worker is run-scoped: registered for this spawn, unregistered after. Orchestration tools are never granted; write tools require writesWorkspace=true.",
+              properties: {
+                displayName: {
+                  type: "string",
+                  description: 'Short task-specific role name, e.g. "Changelog Summarizer".'
+                },
+                allowedTools: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Minimal tool names this worker needs. Unknown/forbidden tools are dropped."
+                },
+                writesWorkspace: {
+                  type: "boolean",
+                  description: "True only if the worker must edit files inside the workspace root."
+                },
+                outputContract: {
+                  type: "string",
+                  description: "Short contract for the worker's structured output."
+                }
+              },
+              required: ["displayName"],
+              additionalProperties: false
             },
             objective: {
               type: "string",
@@ -135963,7 +135990,7 @@ function getDesktopToolDefinitions() {
               description: "Optional child loop cap. Defaults to the worker manifest cap."
             }
           },
-          required: ["workerId", "objective"],
+          required: ["objective"],
           additionalProperties: false
         }
       }
@@ -205266,7 +205293,159 @@ var init_sendWorkerMessage2 = __esm({
   }
 });
 
+// features/perchTerminal/runtime/workers/adhocManifest.ts
+function buildAdhocWorkerManifest(spec) {
+  const displayName = spec.displayName.replace(/\s+/g, " ").trim().slice(0, MAX_NAME_CHARS) || "Ad-hoc Worker";
+  const writesWorkspace = spec.writesWorkspace === true;
+  const outputContract = (spec.outputContract ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_CONTRACT_CHARS) || DEFAULT_OUTPUT_CONTRACT;
+  const requested = [...new Set(spec.allowedTools ?? [])].filter(
+    (tool) => typeof tool === "string" && tool.trim().length > 0
+  );
+  const droppedTools = [];
+  const allowedTools = requested.filter((tool) => {
+    if (ADHOC_FORBIDDEN_TOOLS.includes(tool)) {
+      droppedTools.push(tool);
+      return false;
+    }
+    if (!writesWorkspace && ADHOC_WRITE_TOOLS.has(tool)) {
+      droppedTools.push(tool);
+      return false;
+    }
+    return true;
+  });
+  const maxIterations = clampInt(spec.maxIterations, 1, ADHOC_MAX_ITERATIONS, 6);
+  const workerId = uniqueAdhocWorkerId(displayName);
+  const manifest = {
+    workerId,
+    name: displayName,
+    description: `Ad-hoc worker (run-scoped): ${displayName}.`,
+    lane: writesWorkspace ? "code_worker" : "fast_worker",
+    systemPrompt: [
+      `You are ${displayName}, one bounded ad-hoc worker spawned for a single objective.`,
+      "Work only on the objective you are given. Never delegate, never spawn other workers, never start suites.",
+      `Respect the output contract exactly: ${outputContract}.`,
+      writesWorkspace ? "You may edit files, but only inside the active workspace root, and only edits the objective requires." : "You are read-only: never write, move, or delete files."
+    ].join("\n"),
+    allowedTools,
+    maxIterations,
+    callableAgents: [],
+    outputContract
+  };
+  return { manifest, droppedTools };
+}
+function uniqueAdhocWorkerId(displayName) {
+  const slug = displayName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 24) || "worker";
+  const base = `adhoc_${Date.now().toString(36)}_${slug}`;
+  let candidate = base;
+  let bump = 0;
+  while (getWorkerManifest(candidate)) {
+    bump += 1;
+    candidate = `${base}_${bump}`;
+  }
+  return candidate;
+}
+function clampInt(value, min2, max2, fallback) {
+  const num = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.min(Math.max(num, min2), max2);
+}
+var ADHOC_FORBIDDEN_TOOLS, ADHOC_WRITE_TOOLS, ADHOC_MAX_ITERATIONS, MAX_NAME_CHARS, MAX_CONTRACT_CHARS, DEFAULT_OUTPUT_CONTRACT;
+var init_adhocManifest = __esm({
+  "features/perchTerminal/runtime/workers/adhocManifest.ts"() {
+    "use strict";
+    init_toolNames();
+    init_registry();
+    init_types();
+    ADHOC_FORBIDDEN_TOOLS = [
+      ...WORKER_DISALLOWED_TOOLS,
+      TOOL_NAMES.dispatchAgent,
+      TOOL_NAMES.sendWorkerMessage,
+      TOOL_NAMES.taskStop,
+      TOOL_NAMES.runSuite,
+      TOOL_NAMES.listSuiteCatalog,
+      TOOL_NAMES.proposeSuitePlan,
+      TOOL_NAMES.executeSuitePlan,
+      TOOL_NAMES.proposeWork,
+      TOOL_NAMES.executeWork,
+      TOOL_NAMES.proposePlan
+    ];
+    ADHOC_WRITE_TOOLS = /* @__PURE__ */ new Set([
+      TOOL_NAMES.writeLocalFile,
+      TOOL_NAMES.editLocalFile,
+      TOOL_NAMES.deleteLocalFile,
+      TOOL_NAMES.moveLocalFile,
+      TOOL_NAMES.copyLocalFile,
+      TOOL_NAMES.createDirectory
+    ]);
+    ADHOC_MAX_ITERATIONS = 10;
+    MAX_NAME_CHARS = 40;
+    MAX_CONTRACT_CHARS = 240;
+    DEFAULT_OUTPUT_CONTRACT = "Return a short structured summary of what was found or done.";
+  }
+});
+
+// features/perchTerminal/runtime/flock/flockNicknames.ts
+function seedFromFlockId(flockId) {
+  let hash = 2166136261;
+  for (let i = 0; i < flockId.length; i++) {
+    hash ^= flockId.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function flockNicknameRotation(flockId) {
+  const names = [...FLOCK_NICKNAMES];
+  let state = seedFromFlockId(flockId) || 1;
+  const nextRandom = () => {
+    state = Math.imul(state, 1664525) + 1013904223 >>> 0;
+    return state / 4294967296;
+  };
+  for (let i = names.length - 1; i > 0; i--) {
+    const j = Math.floor(nextRandom() * (i + 1));
+    [names[i], names[j]] = [names[j], names[i]];
+  }
+  return names;
+}
+function flockNicknameFor(flockId, index) {
+  const rotation = flockNicknameRotation(flockId);
+  return rotation[index % rotation.length];
+}
+var FLOCK_NICKNAMES;
+var init_flockNicknames = __esm({
+  "features/perchTerminal/runtime/flock/flockNicknames.ts"() {
+    "use strict";
+    FLOCK_NICKNAMES = [
+      "Little Dum Dum",
+      "Molly",
+      "Boomer",
+      "Shawarma",
+      "Curie",
+      "Eagle",
+      "Noether",
+      "Wonky",
+      "Lovelace",
+      "Bell",
+      "Turing",
+      "Faraday",
+      "Biscuit",
+      "Ice Cream",
+      "Minsky"
+    ];
+  }
+});
+
 // features/perchTerminal/runtime/toolSystem/tools/workers/spawnWorker.ts
+function parseAdhocSpec(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const record = raw;
+  if (typeof record.displayName !== "string" || !record.displayName.trim()) return null;
+  return {
+    displayName: record.displayName,
+    allowedTools: Array.isArray(record.allowedTools) ? record.allowedTools.filter((tool) => typeof tool === "string") : void 0,
+    writesWorkspace: record.writesWorkspace === true,
+    maxIterations: typeof record.maxIterations === "number" ? record.maxIterations : void 0,
+    outputContract: typeof record.outputContract === "string" ? record.outputContract : void 0
+  };
+}
 var spawnWorkerTool;
 var init_spawnWorker = __esm({
   "features/perchTerminal/runtime/toolSystem/tools/workers/spawnWorker.ts"() {
@@ -205276,12 +205455,49 @@ var init_spawnWorker = __esm({
     init_agentDispatch();
     init_localScope();
     init_toolNames();
+    init_adhocManifest();
+    init_registry();
+    init_flockNicknames();
     spawnWorkerTool = {
       name: TOOL_NAMES.spawnWorker,
       classification: { native: false },
       handler: async (args, ctx) => {
-        const workerId = String(args.workerId ?? "");
+        let workerId = String(args.workerId ?? "");
         const objective = String(args.objective ?? "");
+        let adhocManifestId = null;
+        let adhocNickname = null;
+        const customSpec = parseAdhocSpec(args.custom);
+        if (!workerId && args.custom !== void 0 && !customSpec) {
+          return {
+            ok: false,
+            workerId: "",
+            summary: "spawn_worker custom spec is invalid: custom.displayName (non-empty string) is required.",
+            errorCode: "adhoc_spec_invalid"
+          };
+        }
+        if (!workerId && customSpec) {
+          const { manifest, droppedTools } = buildAdhocWorkerManifest(customSpec);
+          registerWorkerManifest(manifest);
+          adhocManifestId = manifest.workerId;
+          adhocNickname = flockNicknameFor(manifest.workerId, 0);
+          workerId = manifest.workerId;
+          if (droppedTools.length > 0 && ctx.onEvent) {
+            ctx.onEvent({
+              type: "diagnostic",
+              code: "adhoc_worker_tools_dropped",
+              message: `Ad-hoc worker "${manifest.name}" was not granted: ${droppedTools.join(", ")} (orchestration or write tools outside its scope).`,
+              ts: (/* @__PURE__ */ new Date()).toISOString()
+            });
+          }
+        }
+        if (!workerId) {
+          return {
+            ok: false,
+            workerId: "",
+            summary: "spawn_worker requires either workerId (registered worker) or custom { displayName, allowedTools, ... } for an ad-hoc worker.",
+            errorCode: "worker_id_missing"
+          };
+        }
         const context = typeof args.context === "string" || typeof args.context === "object" && args.context !== null && !Array.isArray(args.context) ? args.context : void 0;
         const lane = typeof args.lane === "string" ? args.lane : void 0;
         const maxIterations = typeof args.maxIterations === "number" ? args.maxIterations : void 0;
@@ -205312,26 +205528,31 @@ var init_spawnWorker = __esm({
 Proceed with the available context. If a missing fact is essential, ask the user for that fact instead of stopping.` : "",
           capabilityNote ? `Capability note: ${capabilityNote}` : ""
         ].filter(Boolean).join("\n\n");
-        return spawnWorker(
-          { workerId, objective: workerObjective, context: enrichedContext, lane, maxIterations },
-          {
-            workspaceRoot: effectiveWorkspaceRoot(ctx),
-            desktopConnected: ctx.desktopConnected,
-            activeRootPath: ctx.activeRootPath,
-            permissionMode: ctx.permissionMode,
-            workspaceId: ctx.workspaceId,
-            threadId: ctx.threadId,
-            selectedSourceId: ctx.selectedSourceId,
-            supabaseConfigured: ctx.supabaseConfigured,
-            supabase: ctx.supabase,
-            runId: ctx.runId,
-            founderModelSelection: ctx.founderModelSelection ?? null,
-            onEvent: ctx.onEvent,
-            signal: ctx.signal,
-            parentToolCallId: ctx.parentToolCallId,
-            mcpTools: ctx.mcpTools ?? []
-          }
-        );
+        try {
+          const result2 = await spawnWorker(
+            { workerId, objective: workerObjective, context: enrichedContext, lane, maxIterations },
+            {
+              workspaceRoot: effectiveWorkspaceRoot(ctx),
+              desktopConnected: ctx.desktopConnected,
+              activeRootPath: ctx.activeRootPath,
+              permissionMode: ctx.permissionMode,
+              workspaceId: ctx.workspaceId,
+              threadId: ctx.threadId,
+              selectedSourceId: ctx.selectedSourceId,
+              supabaseConfigured: ctx.supabaseConfigured,
+              supabase: ctx.supabase,
+              runId: ctx.runId,
+              founderModelSelection: ctx.founderModelSelection ?? null,
+              onEvent: ctx.onEvent,
+              signal: ctx.signal,
+              parentToolCallId: ctx.parentToolCallId,
+              mcpTools: ctx.mcpTools ?? []
+            }
+          );
+          return adhocNickname ? { ...result2, nickname: adhocNickname } : result2;
+        } finally {
+          if (adhocManifestId) unregisterWorkerManifest(adhocManifestId);
+        }
       }
     };
   }
@@ -221145,56 +221366,6 @@ var init_flockModelHints = __esm({
   }
 });
 
-// features/perchTerminal/runtime/flock/flockNicknames.ts
-function seedFromFlockId(flockId) {
-  let hash = 2166136261;
-  for (let i = 0; i < flockId.length; i++) {
-    hash ^= flockId.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return hash >>> 0;
-}
-function flockNicknameRotation(flockId) {
-  const names = [...FLOCK_NICKNAMES];
-  let state = seedFromFlockId(flockId) || 1;
-  const nextRandom = () => {
-    state = Math.imul(state, 1664525) + 1013904223 >>> 0;
-    return state / 4294967296;
-  };
-  for (let i = names.length - 1; i > 0; i--) {
-    const j = Math.floor(nextRandom() * (i + 1));
-    [names[i], names[j]] = [names[j], names[i]];
-  }
-  return names;
-}
-function flockNicknameFor(flockId, index) {
-  const rotation = flockNicknameRotation(flockId);
-  return rotation[index % rotation.length];
-}
-var FLOCK_NICKNAMES;
-var init_flockNicknames = __esm({
-  "features/perchTerminal/runtime/flock/flockNicknames.ts"() {
-    "use strict";
-    FLOCK_NICKNAMES = [
-      "Little Dum Dum",
-      "Molly",
-      "Boomer",
-      "Shawarma",
-      "Curie",
-      "Eagle",
-      "Noether",
-      "Wonky",
-      "Lovelace",
-      "Bell",
-      "Turing",
-      "Faraday",
-      "Biscuit",
-      "Ice Cream",
-      "Minsky"
-    ];
-  }
-});
-
 // features/perchTerminal/runtime/flock/flockRoles.ts
 function listFlockRoleSpecs() {
   return Object.values(FLOCK_ROLES);
@@ -221448,6 +221619,53 @@ var init_flockRoles = __esm({
           "Return JSON with continuityStatus (pass|partial|fail), contradictions (string[]), styleIssues (string[]), warnings (string[])."
         )
       },
+      legal_drafter: {
+        roleId: "legal_drafter",
+        workerId: "flock_legal_drafter",
+        displayName: "Legal Drafter",
+        role: "worker",
+        lane: "writer",
+        allowedTools: [
+          TOOL_NAMES.searchKnowledge,
+          TOOL_NAMES.glob,
+          TOOL_NAMES.grep,
+          TOOL_NAMES.readLocalFile,
+          TOOL_NAMES.listLocalSources,
+          TOOL_NAMES.readLocalSourceFile,
+          TOOL_NAMES.writeLocalFile
+        ],
+        writesWorkspace: true,
+        maxIterations: 10,
+        outputContract: "JSON { title, markdown, irac: { issue, rules, application, conclusion }, authoritiesCited, needsVerification, notes }",
+        objectiveTemplate: (task) => bounded(
+          task,
+          "Draft a legal memo in strict IRAC form \u2014 Issue, Rule, Application, Conclusion, every section present and labeled. First call searchKnowledge for IRAC memo exemplars or templates and imitate their structure and register when any exist. Closed universe: cite ONLY authorities found in the provided case packet (local sources), with pin cites; never invent or import outside authority. Propositions you cannot support from the packet go in needsVerification, never in the prose as settled law.",
+          "Return JSON with title, markdown, irac {issue, rules, application, conclusion}, authoritiesCited (string[]), needsVerification (string[]), notes (string[])."
+        )
+      },
+      legal_citation_checker: {
+        roleId: "legal_citation_checker",
+        workerId: "flock_legal_citation_checker",
+        displayName: "Legal Citation Checker",
+        role: "verifier",
+        lane: "verifier",
+        // Closed universe by construction: no web or global knowledge tools — the packet is the law.
+        allowedTools: [
+          TOOL_NAMES.glob,
+          TOOL_NAMES.grep,
+          TOOL_NAMES.readLocalFile,
+          TOOL_NAMES.listLocalSources,
+          TOOL_NAMES.readLocalSourceFile
+        ],
+        writesWorkspace: false,
+        maxIterations: 10,
+        outputContract: "JSON { verificationStatus: 'pass'|'partial'|'fail', verifiedCitations, unsupportedCitations: [{ citation, claim, reason }], missingFromPacket, warnings }",
+        objectiveTemplate: (task) => bounded(
+          task,
+          "Closed-universe citation check: for every authority cited in the provided draft or memo, locate it in the provided case packet (local sources via listLocalSources/grep/readLocalFile). Verify the authority exists in the packet, quoted language appears in it, and each pin cite supports the stated proposition. Mark pass only when the packet supports the citation. Never consult outside sources \u2014 an authority absent from the packet is reported in missingFromPacket, not assumed valid.",
+          "Return JSON with verificationStatus (pass|partial|fail), verifiedCitations, unsupportedCitations ({citation, claim, reason}[]), missingFromPacket (string[]), warnings (string[])."
+        )
+      },
       browser_operator: {
         roleId: "browser_operator",
         // Reuses the roster manifest from workers/registry — its system prompt and
@@ -221519,6 +221737,22 @@ function planFlock(rawTask, options = {}) {
   if ((options.surface ?? detectFlockSurface()) === "cli") {
     selected.delete("browser_operator");
   }
+  if (selected.has("legal_drafter")) {
+    if (!/\b(write|draft|compose|prepare)\b/i.test(task)) {
+      selected.delete("legal_drafter");
+      selected.add("legal_citation_checker");
+    }
+    selected.delete("writer");
+    selected.delete("researcher");
+    selected.delete("citation_checker");
+    selected.delete("consistency_checker");
+    selected.delete("source_verifier");
+  }
+  if (selected.has("legal_drafter")) {
+    selected.add("legal_citation_checker");
+  } else if (selected.has("legal_citation_checker")) {
+    selected.add("workspace_scout");
+  }
   if (selected.has("patch_worker") || selected.has("test_runner") || selected.has("ui_reviewer")) {
     selected.add("workspace_scout");
   }
@@ -221592,6 +221826,7 @@ var init_flockPlanner = __esm({
       { roleId: "writer", pattern: /\b(write|draft|compose|essay|memo|report|article|document|copy)\b/i },
       { roleId: "citation_checker", pattern: /\b(citations?|verify|check sources?|fact.?check|references?)\b/i },
       { roleId: "consistency_checker", pattern: /\b(fiction|stor(?:y|ies)|novel|chapters?|poems?|screenplay|scripts?|lyrics)\b/i },
+      { roleId: "legal_drafter", pattern: /\b(irac|memorandum|legal (?:memo|brief|writing|citations?)|case ?packet|bluebook|pin ?cites?)\b/i },
       { roleId: "browser_operator", pattern: /\b(browser|open|navigate|click|fill|submit|login|webpage|url|site)\b/i }
     ];
     ROLE_TRIM_PRIORITY = [
@@ -221599,6 +221834,8 @@ var init_flockPlanner = __esm({
       "writer",
       "test_runner",
       "workspace_scout",
+      "legal_drafter",
+      "legal_citation_checker",
       "researcher",
       "citation_checker",
       "consistency_checker",
@@ -221641,6 +221878,7 @@ function buildFlockPlannerPrompts(ctx) {
     "- dependsOn: ids of earlier workers whose output this worker needs. No cycles. You decide the graph: parallel where independent, chained where not. Final verifier/reducer workers usually benefit from depending on the workers they check \u2014 guidance, not a requirement.",
     "- baseWorkerId: set ONLY to reuse an id from existingWorkers; otherwise null. Prefer reusing existingWorkers ids when a role matches instead of inventing a near-duplicate.",
     "- Writing tasks: pair the draft with exactly ONE draft verifier \u2014 reuse flock_citation_checker (together with flock_researcher) when the piece makes factual or source-backed claims, or flock_consistency_checker for creative/fiction drafts (continuity, voice, pacing \u2014 no researcher, never demand citations from fiction).",
+    "- Legal writing or citation-checking tasks (IRAC memos, briefs, case packets, pin cites): reuse flock_legal_drafter and flock_legal_citation_checker instead of the generic writing roles. Closed universe \u2014 verification runs ONLY against the user's provided case packet/local sources, never the open web; a legal draft must include flock_legal_citation_checker.",
     "- Decline (accepted=false, with reason) tasks that are trivial, conversational, or need no fanout."
   ].join("\n");
   ensureFlockWorkersRegistered();
@@ -221746,7 +221984,7 @@ function validateLlmFlockPlan(record, ctx) {
     const objective = sanitizeText(worker.objective, MAX_OBJECTIVE_CHARS);
     if (!displayName || !objective) return null;
     const role = VALID_ROLES.has(worker.phase) ? worker.phase : "worker";
-    const outputContract = sanitizeLine(worker.outputContract, MAX_CONTRACT_CHARS) || "Return a short structured summary of what was found or done.";
+    const outputContract = sanitizeLine(worker.outputContract, MAX_CONTRACT_CHARS2) || "Return a short structured summary of what was found or done.";
     const requestedTools = Array.isArray(worker.allowedTools) ? worker.allowedTools.filter((tool) => typeof tool === "string") : [];
     let allowedTools = [...new Set(requestedTools)].filter(
       (tool) => available.has(tool) && !FLOCK_FORBIDDEN_TOOLS.includes(tool)
@@ -221757,7 +221995,7 @@ function validateLlmFlockPlan(record, ctx) {
     if (!writesWorkspace) {
       allowedTools = allowedTools.filter((tool) => !WRITE_TOOLS.has(tool));
     }
-    const maxIterations = clampInt(worker.maxIterations, 1, caps.maxIterationsPerWorker, 6);
+    const maxIterations = clampInt2(worker.maxIterations, 1, caps.maxIterationsPerWorker, 6);
     const baseWorkerId = typeof worker.baseWorkerId === "string" && worker.baseWorkerId.trim() ? worker.baseWorkerId.trim() : null;
     const reusedManifest = baseWorkerId ? resolveWorkerManifest(baseWorkerId) : null;
     const flockWorkerId = `fw${index + 1}_${slugify(displayName)}`;
@@ -221823,14 +222061,56 @@ function validateLlmFlockPlan(record, ctx) {
       }
     }
   }
-  const writerWorker = surfacedWorkers.find(
-    (worker) => worker.workerId === FLOCK_ROLES.writer.workerId
+  const legalDrafterWorker = surfacedWorkers.find(
+    (worker) => worker.workerId === FLOCK_ROLES.legal_drafter.workerId
   );
+  if (legalDrafterWorker && !surfacedWorkers.some((worker) => worker.workerId === FLOCK_ROLES.legal_citation_checker.workerId)) {
+    const spec = FLOCK_ROLES.legal_citation_checker;
+    const genericVerifierIndex = surfacedWorkers.findIndex(
+      (worker) => worker.workerId === FLOCK_ROLES.citation_checker.workerId || worker.workerId === FLOCK_ROLES.consistency_checker.workerId
+    );
+    if (genericVerifierIndex >= 0) {
+      const existing = surfacedWorkers[genericVerifierIndex];
+      surfacedWorkers[genericVerifierIndex] = {
+        ...existing,
+        workerId: spec.workerId,
+        displayName: spec.displayName,
+        role: spec.role,
+        objective: spec.objectiveTemplate(ctx.task),
+        maxIterations: Math.min(spec.maxIterations, caps.maxIterationsPerWorker),
+        allowedTools: [...spec.allowedTools],
+        writesWorkspace: false,
+        writeScope: null,
+        outputContract: spec.outputContract,
+        dependsOn: [legalDrafterWorker.flockWorkerId],
+        dynamicManifest: null
+      };
+    } else if (surfacedWorkers.length < FLOCK_MAX_WORKERS) {
+      const index = surfacedWorkers.length;
+      surfacedWorkers.push({
+        flockWorkerId: `fw${index + 1}_${spec.roleId}`,
+        workerId: spec.workerId,
+        displayName: spec.displayName,
+        nickname: flockNicknameFor(ctx.flockId, index),
+        role: spec.role,
+        objective: spec.objectiveTemplate(ctx.task),
+        maxIterations: Math.min(spec.maxIterations, caps.maxIterationsPerWorker),
+        allowedTools: [...spec.allowedTools],
+        writesWorkspace: false,
+        writeScope: null,
+        outputContract: spec.outputContract,
+        dependsOn: [legalDrafterWorker.flockWorkerId],
+        modelOverride: null,
+        dynamicManifest: null
+      });
+    }
+  }
+  const writerWorker = legalDrafterWorker ?? surfacedWorkers.find((worker) => worker.workerId === FLOCK_ROLES.writer.workerId);
   if (writerWorker && !surfacedWorkers.some((worker) => worker.role === "verifier") && surfacedWorkers.length < FLOCK_MAX_WORKERS) {
     const hasResearch = surfacedWorkers.some(
       (worker) => worker.workerId === FLOCK_ROLES.researcher.workerId
     );
-    const spec = hasResearch ? FLOCK_ROLES.citation_checker : FLOCK_ROLES.consistency_checker;
+    const spec = legalDrafterWorker ? FLOCK_ROLES.legal_citation_checker : hasResearch ? FLOCK_ROLES.citation_checker : FLOCK_ROLES.consistency_checker;
     const index = surfacedWorkers.length;
     surfacedWorkers.push({
       flockWorkerId: `fw${index + 1}_${spec.roleId}`,
@@ -221900,11 +222180,11 @@ function sanitizeText(value, max2) {
   if (typeof value !== "string") return "";
   return value.trim().slice(0, max2);
 }
-function clampInt(value, min2, max2, fallback) {
+function clampInt2(value, min2, max2, fallback) {
   const num = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
   return Math.min(Math.max(num, min2), max2);
 }
-var FLOCK_FORBIDDEN_TOOLS, WRITE_TOOLS, GUI_ONLY_WORKER_IDS, GUI_ONLY_TOOLS, VALID_ROLES, MAX_DISPLAY_NAME_CHARS, MAX_OBJECTIVE_CHARS, MAX_CONTRACT_CHARS, MAX_ROSTER_IN_PROMPT, MAX_TOOLS_IN_PROMPT;
+var FLOCK_FORBIDDEN_TOOLS, WRITE_TOOLS, GUI_ONLY_WORKER_IDS, GUI_ONLY_TOOLS, VALID_ROLES, MAX_DISPLAY_NAME_CHARS, MAX_OBJECTIVE_CHARS, MAX_CONTRACT_CHARS2, MAX_ROSTER_IN_PROMPT, MAX_TOOLS_IN_PROMPT;
 var init_flockLlmPlanner = __esm({
   "features/perchTerminal/runtime/flock/flockLlmPlanner.ts"() {
     "use strict";
@@ -221945,7 +222225,7 @@ var init_flockLlmPlanner = __esm({
     VALID_ROLES = /* @__PURE__ */ new Set(["scout", "worker", "verifier", "reducer"]);
     MAX_DISPLAY_NAME_CHARS = 40;
     MAX_OBJECTIVE_CHARS = 1200;
-    MAX_CONTRACT_CHARS = 240;
+    MAX_CONTRACT_CHARS2 = 240;
     MAX_ROSTER_IN_PROMPT = 24;
     MAX_TOOLS_IN_PROMPT = 80;
   }
@@ -222088,14 +222368,19 @@ async function runFlockTurn(input, deps, options = {}) {
     }
     const spawnFn = options.spawnWorkerFn ?? spawnWorker;
     const outcomes = [];
+    const revisionOutcomes = [];
+    let revisionReport = null;
     const outputByFlockWorkerId = /* @__PURE__ */ new Map();
-    const sharedContext = { task };
+    const sharedContext = {
+      task,
+      currentDate: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+    };
     let toolCallsUsed = 0;
     let toolCallsReserved = 0;
     let workersAwaitingLaunch = plan.workers.length;
     try {
       const phases = [...new Set(plan.workers.map((worker) => FLOCK_ROLE_ORDER[worker.role]))].sort((a, b2) => a - b2);
-      const runReadyWorker = async (worker) => {
+      const runReadyWorker = async (worker, contextOverride) => {
         const workersLeftIncludingThis = Math.max(1, workersAwaitingLaunch);
         workersAwaitingLaunch = Math.max(0, workersAwaitingLaunch - 1);
         if (flockRun.controller.signal.aborted) {
@@ -222130,11 +222415,14 @@ async function runFlockTurn(input, deps, options = {}) {
         toolCallsReserved += reservedToolCalls;
         emitWorkerUpdate(emit, plan, worker, "running");
         try {
+          const context = contextOverride ?? buildWorkerContext(worker, sharedContext, outputByFlockWorkerId, plan);
+          const objective = worker.role === "worker" && contextContainsSources(context) ? `${worker.objective}
+${FLOCK_GROUNDING_CONTRACT}` : worker.objective;
           const result2 = await spawnFn(
             {
               workerId: worker.workerId,
-              objective: worker.objective,
-              context: buildWorkerContext(worker, sharedContext, outputByFlockWorkerId, plan),
+              objective,
+              context,
               maxIterations: worker.maxIterations,
               maxToolCalls: reservedToolCalls
             },
@@ -222191,7 +222479,9 @@ async function runFlockTurn(input, deps, options = {}) {
             break;
           }
           for (const worker of readyWorkers) pending.delete(worker.flockWorkerId);
-          const batchOutcomes = await Promise.all(readyWorkers.map(runReadyWorker));
+          const batchOutcomes = await Promise.all(
+            readyWorkers.map((worker) => runReadyWorker(worker))
+          );
           for (const outcome of batchOutcomes) {
             outcomes.push(outcome);
             if (!outcome.result) continue;
@@ -222201,6 +222491,43 @@ async function runFlockTurn(input, deps, options = {}) {
           }
         }
       }
+      const candidate = findRevisionCandidate(plan, outcomes, outputByFlockWorkerId);
+      if (candidate && !flockRun.controller.signal.aborted) {
+        revisionReport = candidate;
+        const revisionWorker = {
+          ...candidate.draftWorker,
+          flockWorkerId: `${candidate.draftWorker.flockWorkerId}_r1`,
+          displayName: `${candidate.draftWorker.displayName} (revision)`,
+          objective: buildRevisionObjective(task, candidate),
+          dependsOn: []
+        };
+        const revisionOutcome = await runReadyWorker(revisionWorker, {
+          task,
+          currentDate: sharedContext.currentDate,
+          draft: candidate.draftOutput,
+          verifierFindings: candidate.findings.raw
+        });
+        revisionOutcomes.push(revisionOutcome);
+        candidate.revised = revisionOutcome.status === "done";
+        if (revisionOutcome.result) {
+          const revisedOutput = revisionOutcome.result.structuredOutput ?? clampLine(revisionOutcome.result.summary, 1200);
+          sharedContext[revisionWorker.displayName] = revisedOutput;
+          outputByFlockWorkerId.set(revisionWorker.flockWorkerId, revisedOutput);
+          const recheckWorker = {
+            ...candidate.verifierWorker,
+            flockWorkerId: `${candidate.verifierWorker.flockWorkerId}_r1`,
+            displayName: `${candidate.verifierWorker.displayName} (recheck)`,
+            dependsOn: []
+          };
+          const recheckOutcome = await runReadyWorker(recheckWorker, {
+            task,
+            currentDate: sharedContext.currentDate,
+            dependencies: { [revisionWorker.displayName]: revisedOutput }
+          });
+          revisionOutcomes.push(recheckOutcome);
+          candidate.recheckFindings = recheckOutcome.result ? extractVerifierFindings(recheckOutcome.result.structuredOutput) : null;
+        }
+      }
     } finally {
       clearTimeout(wallTimer);
       finishRuntimeRun(
@@ -222213,7 +222540,14 @@ async function runFlockTurn(input, deps, options = {}) {
     const workersFailed = outcomes.filter((outcome) => outcome.status === "failed").length;
     const flockStatus = userCancelled || wallTimeHit && workersDone === 0 ? "cancelled" : workersFailed === 0 && workersDone === plan.workers.length ? "completed" : workersDone > 0 ? "partial" : "failed";
     const assistantText = [
-      buildFlockSummary(plan, outcomes, flockStatus, toolCallsUsed, wallTimeHit),
+      buildFlockSummary(
+        plan,
+        [...outcomes, ...revisionOutcomes],
+        flockStatus,
+        toolCallsUsed,
+        wallTimeHit
+      ),
+      ...buildVerificationSection(revisionReport),
       ...modelOverrides.applied.map(
         (override) => `Model override: ${override.displayName} ran on ${override.label}.`
       ),
@@ -222300,7 +222634,117 @@ function buildWorkerContext(worker, sharedContext, outputByFlockWorkerId, plan)
     const depWorker = plan.workers.find((candidate) => candidate.flockWorkerId === dep);
     dependencies[depWorker?.displayName ?? dep] = output;
   }
-  return { task: sharedContext.task, dependencies };
+  return { task: sharedContext.task, currentDate: sharedContext.currentDate, dependencies };
+}
+function contextContainsSources(context) {
+  const scan = (value, depth) => {
+    if (!value || typeof value !== "object" || Array.isArray(value) || depth > 3) return false;
+    const record = value;
+    const sources = record.sources;
+    if (Array.isArray(sources) && sources.some(
+      (source) => source && typeof source === "object" && typeof source.url === "string"
+    )) {
+      return true;
+    }
+    return Object.values(record).some((nested) => scan(nested, depth + 1));
+  };
+  return scan(context, 0);
+}
+function extractVerifierFindings(output) {
+  if (!output || typeof output !== "object" || Array.isArray(output)) return null;
+  const record = output;
+  const verdictRaw = record.verificationStatus ?? record.continuityStatus ?? record.verdict;
+  const verdict = typeof verdictRaw === "string" ? verdictRaw.trim().toLowerCase() : null;
+  const issues = [];
+  for (const key of [
+    "unsupportedClaims",
+    "unsupportedCitations",
+    "missingFromPacket",
+    "contradictions",
+    "styleIssues",
+    "unsupported"
+  ]) {
+    const value = record[key];
+    if (!Array.isArray(value)) continue;
+    for (const item of value) {
+      const text = typeof item === "string" ? item : JSON.stringify(item);
+      const clean = clampLine(text, 200);
+      if (clean && clean !== "{}") issues.push(clean);
+    }
+  }
+  return { verdict, issues, raw: record };
+}
+function verifierFindingsNeedRevision(findings) {
+  if (!findings) return false;
+  return findings.issues.length > 0 || findings.verdict === "fail" || findings.verdict === "partial";
+}
+function findRevisionCandidate(plan, outcomes, outputByFlockWorkerId) {
+  for (const outcome of outcomes) {
+    if (outcome.worker.role !== "verifier" || outcome.status !== "done" || !outcome.result) {
+      continue;
+    }
+    const findings = extractVerifierFindings(outcome.result.structuredOutput);
+    if (!verifierFindingsNeedRevision(findings)) continue;
+    const draftWorker = resolveDraftWorkerForVerifier(plan, outcome.worker, outcomes);
+    if (!draftWorker) continue;
+    const draftOutput = outputByFlockWorkerId.get(draftWorker.flockWorkerId);
+    if (draftOutput === void 0) continue;
+    return {
+      verifierWorker: outcome.worker,
+      draftWorker,
+      draftOutput,
+      findings,
+      revised: false,
+      recheckFindings: null
+    };
+  }
+  return null;
+}
+function resolveDraftWorkerForVerifier(plan, verifier, outcomes) {
+  for (const dep of verifier.dependsOn) {
+    const worker = plan.workers.find((candidate) => candidate.flockWorkerId === dep);
+    if (worker?.role === "worker") return worker;
+  }
+  const doneWorkers = outcomes.filter((outcome) => outcome.status === "done" && outcome.worker.role === "worker").map((outcome) => outcome.worker);
+  const writer = doneWorkers.find(
+    (worker) => worker.workerId === "flock_legal_drafter" || worker.workerId === "flock_writer"
+  );
+  if (writer) return writer;
+  const writingWorkers = doneWorkers.filter((worker) => worker.writesWorkspace);
+  if (writingWorkers.length === 1) return writingWorkers[0];
+  return doneWorkers.length === 1 ? doneWorkers[0] : null;
+}
+function buildRevisionObjective(task, candidate) {
+  return [
+    "Bounded Flock revision \u2014 stay strictly inside this scope.",
+    `Task: ${task}`,
+    `A verifier (${candidate.verifierWorker.displayName}) reviewed your draft (context key "draft") and reported findings (context key "verifierFindings").`,
+    "Revise the draft: fix what the findings support fixing; remove or explicitly flag any claim you cannot support. Keep the draft's purpose, format, and output contract. Do not start over.",
+    `Output contract: ${candidate.draftWorker.outputContract}`,
+    "Do not delegate, spawn workers, or start suites. Stop when the findings are addressed."
+  ].join("\n");
+}
+function buildVerificationSection(report) {
+  if (!report) return [];
+  const lines = [];
+  lines.push(
+    `Verification (${report.verifierWorker.displayName}): ${report.findings.verdict ?? "issues found"} \u2014 ${report.findings.issues.length} finding(s).`
+  );
+  const shown = report.findings.issues.slice(0, 6);
+  for (const issue of shown) lines.push(`- ${issue}`);
+  if (report.findings.issues.length > shown.length) {
+    lines.push(`- \u2026and ${report.findings.issues.length - shown.length} more.`);
+  }
+  if (report.revised) {
+    const recheck = report.recheckFindings;
+    lines.push(
+      recheck ? `The draft was revised once; recheck verdict: ${recheck.verdict ?? "no structured verdict"}${recheck.issues.length ? ` (${recheck.issues.length} remaining finding(s))` : ""}.` : "The draft was revised once; the recheck returned no structured verdict."
+    );
+  } else {
+    lines.push("No revision pass ran \u2014 the findings above stand as reported.");
+  }
+  lines.push("Ask about any finding to discuss it, or rerun /flock to retry with adjustments.");
+  return lines;
 }
 function buildSpawnContext(input, flockId, signal, emit, worker) {
   return {
@@ -222365,6 +222809,7 @@ function makeFlockRunId() {
 function now11() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+var FLOCK_GROUNDING_CONTRACT;
 var init_runFlockTurn = __esm({
   "features/perchTerminal/runtime/flock/runFlockTurn.ts"() {
     "use strict";
@@ -222378,6 +222823,12 @@ var init_runFlockTurn = __esm({
     init_flockLlmPlanner();
     init_flockPlanner();
     init_flockRoles();
+    FLOCK_GROUNDING_CONTRACT = [
+      "Grounding contract: your context includes sources[] gathered by research.",
+      "Every nontrivial factual claim in the draft must carry an inline [n] marker mapping to one of those sources, with a numbered source list at the end.",
+      "Claims you cannot support from sources[] belong in needsVerification, never in the prose as fact.",
+      "Do not cite anything that is not in sources[]."
+    ].join(" ");
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perchai-cli",
-  "version": "2.4.33",
+  "version": "2.4.34",
   "description": "Perch AI command-line interface",
   "bin": {
     "perch": "bin/perch"