@mestreyoda/fabrica 0.2.19 → 0.2.21

package/dist/index.js

@@ -113905,8 +113905,8 @@ import fsSync from "node:fs";
 import path5 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 function getCurrentVersion() {
-  if ("0.2.19") {
-    return "0.2.19";
+  if ("0.2.21") {
+    return "0.2.21";
   }
   try {
     const pkgPath = path5.join(THIS_DIR, "..", "..", "package.json");
@@ -114883,7 +114883,7 @@ function resolve2(config2, sourceLayers, trace2) {
     dispatchMs: config2.timeouts?.dispatchMs ?? 6e5,
     staleWorkerHours: config2.timeouts?.staleWorkerHours ?? 2,
     sessionContextBudget: config2.timeouts?.sessionContextBudget ?? 0.6,
-    stallTimeoutMinutes: config2.timeouts?.stallTimeoutMinutes ?? 5,
+    stallTimeoutMinutes: config2.timeouts?.stallTimeoutMinutes ?? 25,
     sessionConfirmAttempts: config2.timeouts?.sessionConfirmAttempts ?? 5,
     sessionConfirmDelayMs: config2.timeouts?.sessionConfirmDelayMs ?? 250,
     sessionLabelMaxLength: config2.timeouts?.sessionLabelMaxLength ?? 64,
@@ -118561,6 +118561,34 @@ var conduct_interview_exports = {};
 __export(conduct_interview_exports, {
   conductInterviewStep: () => conductInterviewStep
 });
+function deriveFeatureScopeFromRawIdea(rawIdea) {
+  const text = rawIdea.toLowerCase();
+  const scope = [];
+  const add = (item) => {
+    if (!scope.includes(item)) scope.push(item);
+  };
+  if (/\b(auth|oauth|jwt|login|register|session|role-based access|rbac|permissions?)\b/i.test(text)) {
+    add("Implement authentication, authorization, and role-aware access rules");
+  }
+  if (/\b(incident|project|task|owner|assign|timeline|status|update)s?\b/i.test(text)) {
+    add("Implement the core domain workflows and CRUD endpoints for the main entities");
+  }
+  if (/\b(alert|alerts|notif|notification|notifications|reminder|reminders|escalation|escalations)\b/i.test(text)) {
+    add("Implement notifications, reminders, and escalation flows for key events");
+  }
+  if (/\b(background process|background worker|worker|queue|job|celery|bull|sidekiq|scheduler)\b/i.test(text)) {
+    add("Implement the background processing pipeline required for asynchronous work");
+  }
+  if (/\b(admin view|admin panel|admin console|dashboard|audit history|audit log|activity history)\b/i.test(text)) {
+    add("Implement administrative visibility and audit/history capabilities for operators");
+  }
+  if (scope.length < 3) {
+    add("Implement the primary user workflow described in the request");
+    add("Expose the key interactions needed to operate the system end to end");
+    add("Add validation and persistence rules for the main business flow");
+  }
+  return scope.slice(0, 5);
+}
 function fallbackSpecData(type, rawIdea) {
   const title = rawIdea.slice(0, 120);
   const base = {
@@ -118588,7 +118616,12 @@ function fallbackSpecData(type, rawIdea) {
       base.acceptance_criteria = ["Infrastructure change applied and verified"];
       break;
     default:
-      base.acceptance_criteria = ["Feature works as described in the objective"];
+      base.scope_v1 = deriveFeatureScopeFromRawIdea(rawIdea);
+      base.acceptance_criteria = [
+        "The primary workflow works end to end as requested",
+        "Role, validation, or delivery constraints from the request are enforced",
+        "The asynchronous/background behavior works for the main operational path"
+      ];
   }
   return base;
 }
@@ -124987,6 +125020,20 @@ function buildMessage(event) {
       }
       return msg;
     }
+    case "workerProgress": {
+      const worker = formatWorkerString(event.role, {
+        name: event.name,
+        level: event.level
+      });
+      let msg = `\u23F3 ${worker} still working on #${event.issueId}: ${event.issueTitle}`;
+      if (event.summary) msg += `
+${event.summary}`;
+      if (event.minutesActive != null) msg += `
+\u{1F552} Active for ${event.minutesActive} min`;
+      msg += `
+\u{1F4CB} [Issue #${event.issueId}](${event.issueUrl})`;
+      return msg;
+    }
     case "workerComplete": {
       const icons = {
         done: "\u2705",
@@ -126282,6 +126329,25 @@ async function validatePrExistsForDeveloper(issueId, repoPath, provider, runComm
     const branchPrIsReviewable = !!branchPr?.url && branchPr.state !== PrState.MERGED && branchPr.state !== PrState.CLOSED;
     const prStatus = preferIssuePr ? issuePrIsReviewable ? issuePr : branchPr ?? issuePr : branchPrIsReviewable ? branchPr : issuePr;
     if (!prStatus.url || prStatus.state === PrState.MERGED || prStatus.state === PrState.CLOSED) {
+      if (preferIssuePr && isCurrentProjectBaseBranch(branchName, baseBranch)) {
+        const currentBase = branchName || baseBranch || "main";
+        const suggestedBranch = `feature/${issueId}-${projectSlug.replace(/[^a-z0-9]+/g, "-").slice(0, 40)}`;
+        throw new Error(
+          `Cannot mark work_finish(done) while on the base branch ("${currentBase}") without an open PR.
+
+You must implement changes on a feature branch and open a PR before calling work_finish.
+
+Steps to fix:
+  1. git worktree add ../${projectSlug}.worktrees/${suggestedBranch} -b ${suggestedBranch}
+  2. cd ../${projectSlug}.worktrees/${suggestedBranch}
+  3. Implement the changes there, commit, push, and create a PR:
+     git push -u origin ${suggestedBranch}
+     gh pr create --base ${baseBranch ?? "main"} --head ${suggestedBranch} --title "feat: ..." --body "Closes #${issueId}"
+  4. Then call work_finish again.
+
+If the worktree already exists, cd into it and continue from there.`
+        );
+      }
       const currentBranch = branchName || "current-branch";
       const reason = !prStatus.url ? `\u2717 No PR found for branch: ${currentBranch}` : prStatus.state === PrState.MERGED ? `\u2717 Last linked PR is already merged: ${prStatus.url}` : `\u2717 Last linked PR is closed and not reviewable: ${prStatus.url}`;
       throw new Error(
@@ -126290,7 +126356,7 @@ async function validatePrExistsForDeveloper(issueId, repoPath, provider, runComm
 ${reason}
 
 Please create a PR first:
-  gh pr create --base main --head ${currentBranch} --title "..." --body "..."
+  gh pr create --base ${baseBranch ?? "main"} --head ${currentBranch} --title "..." --body "Closes #${issueId}"
 
 Then call work_finish again.`
       );
@@ -126722,6 +126788,10 @@ function createTaskCreateTool(ctx) {
         pickup: {
           type: "boolean",
           description: "If true, immediately pick up this issue for DEV after creation. Defaults to false."
+        },
+        parentIssueId: {
+          type: "number",
+          description: "Optional parent/epic issue ID when creating a child task as part of a decomposition plan."
         }
       }
     },
@@ -126730,12 +126800,17 @@ function createTaskCreateTool(ctx) {
       const description = params.description ?? "";
       const assignees = params.assignees ?? [];
       const pickup = params.pickup ?? false;
+      const parentIssueId = Number.isFinite(params.parentIssueId) ? Number(params.parentIssueId) : null;
       const workspaceDir = requireWorkspaceDir(toolCtx);
       const { project, route } = await resolveProjectFromContext(workspaceDir, toolCtx, params.channelId);
       const resolvedConfig = await loadConfig(workspaceDir, project.slug);
       const label = resolvedConfig.workflow.states[resolvedConfig.workflow.initial]?.label ?? "Planning";
       const { provider, type: providerType } = await resolveProvider(project, ctx.runCommand);
-      const issue2 = await provider.createIssue(title, description, label, assignees);
+      let body = description;
+      if (parentIssueId) {
+        body = `${description}${description.trim().length > 0 ? "\n\n" : ""}Parent issue: #${parentIssueId}`;
+      }
+      const issue2 = await provider.createIssue(title, body, label, assignees);
       provider.reactToIssue(issue2.iid, "eyes").catch(() => {
       });
       const primaryChannel = findPrimaryChannel(project);
@@ -126749,13 +126824,31 @@ function createTaskCreateTool(ctx) {
       );
       autoAssignOwnerLabel(workspaceDir, provider, issue2.iid, project).catch(() => {
       });
+      if (parentIssueId) {
+        await updateIssueRuntime(workspaceDir, project.slug, issue2.iid, {
+          parentIssueId
+        }).catch(() => {
+        });
+        const parentRuntime = project.issueRuntime?.[String(parentIssueId)] ?? {};
+        const previousChildren = Array.isArray(parentRuntime.childIssueIds) ? parentRuntime.childIssueIds : [];
+        await updateIssueRuntime(workspaceDir, project.slug, parentIssueId, {
+          childIssueIds: [.../* @__PURE__ */ new Set([...previousChildren, issue2.iid])]
+        }).catch(() => {
+        });
+        provider.addComment(
+          parentIssueId,
+          `\u{1F4CC} Child task created: [#${issue2.iid}: ${issue2.title}](${issue2.web_url})`
+        ).catch(() => {
+        });
+      }
       await log(workspaceDir, "task_create", {
         project: project.name,
         issueId: issue2.iid,
         title,
         label,
         provider: providerType,
-        pickup
+        pickup,
+        parentIssueId
       });
       const hasBody = description && description.trim().length > 0;
       let announcement = `\u{1F4CB} Created #${issue2.iid}: "${title}" (${label})`;
@@ -128816,6 +128909,7 @@ async function dispatchTask(opts) {
     inconclusiveCompletionAt: null,
     inconclusiveCompletionReason: null,
     sessionCompletedAt: null,
+    progressNotifiedAt: null,
     lastSessionKey: sessionKey
   }).catch((err) => {
     log(workspaceDir, "dispatch_warning", { step: "record_dispatch_requested", issue: issueId, err: String(err) }).catch(() => {
@@ -131313,6 +131407,7 @@ async function checkWorkerHealth(opts) {
     completionRecoveryWindowMs = COMPLETION_RECOVERY_WINDOW_MS,
     executionContractRecoveryWindowMs = EXECUTION_CONTRACT_RECOVERY_WINDOW_MS,
     runCommand,
+    stallTimeoutMinutes = 25,
     notificationConfig
   } = opts;
   const fixes = [];
@@ -131812,7 +131907,120 @@ async function checkWorkerHealth(opts) {
         continue;
       }
       if (slot.active && slot.startTime && sessionKey && sessions && sessionAlive) {
-        const hours = (Date.now() - new Date(slot.startTime).getTime()) / 36e5;
+        const startedAtMs = new Date(slot.startTime).getTime();
+        const minutesActive = (Date.now() - startedAtMs) / 6e4;
+        const hours = minutesActive / 60;
+        let hasReviewableArtifact = Boolean(
+          issueRuntime?.currentPrNumber || issueRuntime?.currentPrUrl || issueRuntime?.artifactOfRecord?.prNumber
+        );
+        if (!hasReviewableArtifact && issueIdNum) {
+          try {
+            const prStatus = await provider.getPrStatus(issueIdNum);
+            hasReviewableArtifact = Boolean(
+              prStatus.url && prStatus.state !== PrState.MERGED && prStatus.state !== PrState.CLOSED && prStatus.currentIssueMatch !== false
+            );
+          } catch {
+          }
+        }
+        if (role === "developer" && issue2 && issueIdNum && !hasReviewableArtifact && minutesActive >= Math.max(5, Math.floor(stallTimeoutMinutes / 2)) && !issueRuntime?.progressNotifiedAt) {
+          const channel = project.channels?.[0];
+          await notify(
+            {
+              type: "workerProgress",
+              project: project.name,
+              issueId: issueIdNum,
+              issueUrl: issue2.web_url,
+              issueTitle: issue2.title,
+              role,
+              level,
+              minutesActive: Math.round(minutesActive),
+              summary: "Still iterating on implementation/QA without a PR yet.",
+              dispatchCycleId: slot.dispatchCycleId ?? issueRuntime?.lastDispatchCycleId ?? null,
+              dispatchRunId: slot.dispatchRunId ?? issueRuntime?.dispatchRunId ?? null
+            },
+            {
+              workspaceDir,
+              config: notificationConfig,
+              target: channel ? {
+                channelId: channel.channelId,
+                channel: channel.channel,
+                accountId: channel.accountId,
+                messageThreadId: channel.messageThreadId
+              } : void 0,
+              runCommand
+            }
+          ).catch(() => {
+          });
+          await updateIssueRuntime(workspaceDir, projectSlug, issueIdNum, {
+            progressNotifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            lastSessionKey: sessionKey
+          }).catch(() => {
+          });
+        }
+        if (role === "developer" && issue2 && issueIdNum && !hasReviewableArtifact && minutesActive >= stallTimeoutMinutes) {
+          const fix = {
+            issue: {
+              type: "completion_recovery_exhausted",
+              severity: "critical",
+              project: project.name,
+              projectSlug,
+              role,
+              level,
+              sessionKey,
+              issueId: slot.issueId,
+              slotIndex,
+              message: `${role.toUpperCase()} ${level}[${slotIndex}] active for ${Math.round(minutesActive)}m without a PR or terminal result`
+            },
+            fixed: false
+          };
+          if (autoFix) {
+            const channel = project.channels?.[0];
+            await notify(
+              {
+                type: "workerRecoveryExhausted",
+                project: project.name,
+                issueId: issueIdNum,
+                issueUrl: issue2.web_url,
+                issueTitle: issue2.title,
+                role,
+                detail: `No PR or canonical completion after ${Math.round(minutesActive)} minutes of active work. Re-queueing for a fresh attempt.`,
+                nextState: slotQueueLabel,
+                dispatchCycleId: slot.dispatchCycleId ?? issueRuntime?.lastDispatchCycleId ?? null,
+                dispatchRunId: slot.dispatchRunId ?? issueRuntime?.dispatchRunId ?? null
+              },
+              {
+                workspaceDir,
+                config: notificationConfig,
+                target: channel ? {
+                  channelId: channel.channelId,
+                  channel: channel.channel,
+                  accountId: channel.accountId,
+                  messageThreadId: channel.messageThreadId
+                } : void 0,
+                runCommand
+              }
+            ).catch(() => {
+            });
+            await revertLabel(fix, expectedLabel, slotQueueLabel);
+            if (!fix.labelRevertFailed) {
+              await deactivateSlot();
+              await updateIssueRuntime(workspaceDir, projectSlug, issueIdNum, {
+                inconclusiveCompletionAt: (/* @__PURE__ */ new Date()).toISOString(),
+                inconclusiveCompletionReason: "stalled_without_artifact",
+                progressNotifiedAt: null
+              }).catch(() => {
+              });
+              fix.fixed = true;
+              await auditHealthFixApplied(workspaceDir, fix, {
+                action: "requeue_issue",
+                fromLabel: expectedLabel,
+                toLabel: slotQueueLabel
+              });
+            }
+          }
+          fixes.push(fix);
+          continue;
+        }
         if (hours > staleWorkerHours) {
           const fix = {
             issue: {
@@ -139671,11 +139879,44 @@ var createTaskStep = {
 };
 
 // lib/intake/lib/triage-logic.ts
-function calculateEffort(filesChanged, acCount) {
-  if (filesChanged <= 3 && acCount <= 3) return "small";
-  if (filesChanged <= 10 && acCount <= 7) return "medium";
-  if (filesChanged <= 25 && acCount <= 15) return "large";
-  return "xlarge";
+function detectRawIdeaComplexity(rawIdea) {
+  const text = rawIdea.toLowerCase();
+  const signals = [];
+  const subsystemPatterns = [
+    [/\b(worker|background.?job|background process|background service|background worker|queue|celery|bull|sidekiq|task.?runner|scheduler|job processor)\b/i, "background-worker"],
+    [/\b(websocket|server.?sent|sse|real.?time|realtime|socket\.io|push.?notif)\b/i, "realtime"],
+    [/\b(auth|oauth|jwt|login|register|session|user.?account|signup|role-based access|rbac|permission[s]?)\b/i, "auth"],
+    [/\b(notif|notification[s]?|alert[s]?|email|sms|webhook|subscription|subscribe|reminder[s]?|escalation[s]?)\b/i, "notifications"],
+    [/\b(database|banco|db|postgres|mysql|mongodb|redis|sqlite|orm|audit history|audit log|activity history)\b/i, "database"],
+    [/\b(api\s+rest|rest\s+api|endpoint|rota|route|graphql|grpc)\b/i, "api-layer"],
+    [/\b(docker|kubernetes|k8s|deploy|ci|cd|pipeline)\b/i, "infra"],
+    [/\b(dashboard|frontend|interface|ui|tela|p[aá]gina|admin view|admin panel|admin console)\b/i, "frontend"]
+  ];
+  for (const [regex, label] of subsystemPatterns) {
+    if (regex.test(text)) signals.push(label);
+  }
+  let floor = null;
+  if (signals.length >= 4) floor = "large";
+  else if (signals.length >= 3) floor = "medium";
+  else if (signals.length >= 2) floor = "medium";
+  return { floor, signals };
+}
+function calculateEffort(filesChanged, acCount, rawIdea) {
+  let effort;
+  if (filesChanged <= 3 && acCount <= 3) effort = "small";
+  else if (filesChanged <= 10 && acCount <= 7) effort = "medium";
+  else if (filesChanged <= 25 && acCount <= 15) effort = "large";
+  else effort = "xlarge";
+  if (rawIdea) {
+    const { floor } = detectRawIdeaComplexity(rawIdea);
+    if (floor) {
+      const ORDER = ["small", "medium", "large", "xlarge"];
+      if (ORDER.indexOf(floor) > ORDER.indexOf(effort)) {
+        effort = floor;
+      }
+    }
+  }
+  return effort;
 }
 function calculatePriority(type, effort, totalRisks, matrix) {
   for (const rule of matrix.priority_rules_v2) {
@@ -139742,7 +139983,7 @@ function determineLevel(effort, targetState) {
   return level;
 }
 function runTriageLogic(input, matrix) {
-  const effort = calculateEffort(input.filesChanged, input.acCount);
+  const effort = calculateEffort(input.filesChanged, input.acCount, input.rawIdea);
   const { priority, label: priorityLabel } = calculatePriority(input.type, effort, input.totalRisks, matrix);
   const effortLabel = matrix.effort_rules[effort]?.label ?? `effort:${effort}`;
   const typeLabel = matrix.auto_labels[input.type] ?? "";
@@ -139806,6 +140047,38 @@ function loadMatrix() {
   cachedMatrix = _require3("../configs/triage-matrix.json");
   return cachedMatrix;
 }
+function buildChildDrafts(payload, issueNumber, effort) {
+  const spec = payload.spec;
+  const scopeItems = spec.scope_v1.filter((item) => item.trim().length > 0);
+  const maxChildren = effort === "xlarge" ? 4 : 3;
+  const chunkSize = 2;
+  const drafts = [];
+  for (let i2 = 0; i2 < scopeItems.length && drafts.length < maxChildren; i2 += chunkSize) {
+    const slice = scopeItems.slice(i2, i2 + chunkSize);
+    if (slice.length === 0) continue;
+    const childIndex = drafts.length + 1;
+    drafts.push({
+      title: `${spec.title} \u2014 Part ${childIndex}`,
+      description: [
+        `## Objective`,
+        spec.objective,
+        "",
+        `## Parent Issue`,
+        `Parent issue: #${issueNumber}`,
+        "",
+        `## This Part`,
+        ...slice.map((item) => `- ${item}`),
+        "",
+        `## Acceptance Criteria`,
+        ...spec.acceptance_criteria.map((item) => `- ${item}`),
+        "",
+        `## Definition of Done`,
+        ...spec.definition_of_done.map((item) => `- ${item}`)
+      ].join("\n")
+    });
+  }
+  return drafts;
+}
 var triageStep = {
   name: "triage",
   shouldRun: (payload) => !!payload.issues?.length && !payload.dry_run,
@@ -139825,9 +140098,9 @@ var triageStep = {
       totalRisks: (impact?.risk_areas?.length ?? 0) + (payload.security?.spec_security_notes?.length ?? 0),
       objective: spec.objective,
       rawIdea: payload.raw_idea,
-      acText: spec.acceptance_criteria.join(" "),
-      scopeText: spec.scope_v1.join(" "),
-      oosText: spec.out_of_scope.join(" "),
+      acText: spec.acceptance_criteria.join("\n"),
+      scopeText: spec.scope_v1.join("\n"),
+      oosText: spec.out_of_scope.join("\n"),
       authSignal: payload.metadata?.auth_gate?.signal ?? false
     }, matrix);
     const repoUrl = payload.scaffold?.repo_url ?? payload.metadata?.repo_url ?? "";
@@ -139837,8 +140110,12 @@ var triageStep = {
     const initialLabel = resolvedConfig?.workflow.states[resolvedConfig.workflow.initial]?.label ?? "Planning";
     const allLabels = [decision.priorityLabel, decision.effortLabel];
     if (decision.typeLabel) allLabels.push(decision.typeLabel);
-    if (!decision.readyForDispatch) allLabels.push("needs-human");
+    if (!decision.readyForDispatch || decision.specQualityBlock) allLabels.push("needs-human");
     const uniqueLabels = Array.from(new Set(allLabels.filter(Boolean)));
+    const shouldDecompose = decision.readyForDispatch && !decision.specQualityBlock && ["large", "xlarge"].includes(decision.effort);
+    const decompositionDrafts = shouldDecompose ? buildChildDrafts(payload, issue2.number, decision.effort) : [];
+    const canDecompose = decompositionDrafts.length >= 2;
+    let createdChildIssueNumbers = [];
     if (ctx.createIssueProvider && repoPath) {
       try {
         const { provider } = await ctx.createIssueProvider({
@@ -139848,7 +140125,36 @@ var triageStep = {
         for (const label of uniqueLabels) {
           await provider.addLabel(issue2.number, label);
         }
-        if (decision.readyForDispatch) {
+        if (decision.specQualityBlock) {
+          await provider.addComment(issue2.number, [
+            "\u{1F6AB} Spec quality gate blocked automatic dispatch.",
+            "",
+            "The request needs a stronger objective, more concrete scope items, and verifiable acceptance criteria before creating execution tasks."
+          ].join("\n"));
+        } else if (canDecompose) {
+          await provider.addLabel(issue2.number, "decomposition:parent");
+          const childIssues = [];
+          for (const draft of decompositionDrafts) {
+            const child = await provider.createIssue(draft.title, draft.description, initialLabel);
+            childIssues.push({ iid: child.iid, title: child.title, web_url: child.web_url });
+            createdChildIssueNumbers.push(child.iid);
+            for (const label of uniqueLabels) {
+              await provider.addLabel(child.iid, label);
+            }
+            await provider.addLabel(child.iid, "decomposition:child");
+          }
+          await provider.addComment(issue2.number, [
+            "## Decomposition Plan",
+            ...childIssues.map((child) => `- [ ] #${child.iid} ${child.title}`)
+          ].join("\n"));
+        } else if (shouldDecompose) {
+          await provider.addLabel(issue2.number, "needs-human");
+          await provider.addComment(issue2.number, [
+            "\u26A0\uFE0F Automatic decomposition was requested, but the generated spec did not yield at least two independently scoped child tasks.",
+            "",
+            "Refine the scope/acceptance criteria or split the plan manually before dispatch."
+          ].join("\n"));
+        } else if (decision.readyForDispatch) {
           await provider.transitionLabel(issue2.number, initialLabel, decision.targetState);
           const dispatchLabels = [];
           if (decision.targetState === "To Do" && decision.dispatchLabel) {
@@ -139913,8 +140219,14 @@ var triageStep = {
       project_channel_id: null,
       labels_applied: uniqueLabels,
       issue_number: issue2.number,
-      ready_for_dispatch: decision.readyForDispatch && decision.errors.length === 0,
-      errors: decision.errors
+      ready_for_dispatch: decision.readyForDispatch && decision.errors.length === 0 && !decision.specQualityBlock && !canDecompose,
+      errors: [
+        ...decision.errors,
+        ...decision.specQualityBlock ? ["spec_quality_block"] : [],
+        ...shouldDecompose && !canDecompose ? ["decomposition_needs_human"] : []
+      ],
+      decomposition_mode: canDecompose ? "parent_child" : "none",
+      child_issue_numbers: createdChildIssueNumbers
     };
     ctx.log(`Triage: ${triage.priority}, effort=${triage.effort}, ready=${triage.ready_for_dispatch}`);
     return {
@@ -140996,6 +141308,22 @@ var BOOTSTRAP_MESSAGES = {
     pt: "Como voc\xEA quer chamar o projeto? Se preferir, posso escolher um nome.",
     en: "What do you want to name the project? If you prefer, I can pick one."
   },
+  clarifyScope: {
+    pt: (idea) => `Recebi! Seu pedido envolve v\xE1rios subsistemas (autentica\xE7\xE3o, notifica\xE7\xF5es, worker, banco de dados...). Para montar uma spec de qualidade, preciso de algumas defini\xE7\xF5es:
+
+1. **Stack/linguagem**: qual prefere? (Python/FastAPI, Node.js/Express, Go...)
+2. **Banco de dados**: PostgreSQL, MongoDB, Redis, outro?
+3. **Autentica\xE7\xE3o**: JWT, OAuth2, sess\xE3o?
+
+Se preferir deixar a escolha comigo, responda "livre" e eu decido.`,
+    en: (idea) => `Got it! Your request involves multiple subsystems (auth, notifications, background worker, DB...). To produce a quality spec, I need a few decisions:
+
+1. **Stack/language**: which do you prefer? (Python/FastAPI, Node.js/Express, Go...)
+2. **Database**: PostgreSQL, MongoDB, Redis, other?
+3. **Auth**: JWT, OAuth2, session?
+
+If you want me to choose, reply "your call" and I'll decide.`
+  },
   registered: {
     pt: (name, link) => `Projeto "${name}" registrado.
 Vou continuar o fluxo em ${link}`,
@@ -141003,12 +141331,39 @@ Vou continuar o fluxo em ${link}`,
 I'll continue the flow at ${link}`
   }
 };
+function detectScopeAmbiguity(rawIdea, stackHint) {
+  const text = rawIdea.toLowerCase();
+  if (/\b(livre|free.?choice|your.?call|pode.?escolher|voc[eê].?decide|qualquer)\b/i.test(text)) {
+    return false;
+  }
+  const subsystems = [
+    /\b(worker|background.?job|queue|task.?runner|celery|bull)\b/i,
+    /\b(websocket|sse|real.?time|realtime|push.?notif)\b/i,
+    /\b(auth|oauth|jwt|login|register|signup|autenticac)\b/i,
+    /\b(notif|alert|assinatura|subscription|subscribe|email|sms)\b/i,
+    /\b(banco|database|db|postgres|mysql|mongodb|redis|sqlite)\b/i,
+    /\b(api\s+rest|rest\s+api|endpoint|graphql|grpc)\b/i,
+    /\b(dashboard|frontend|interface|ui|tela)\b/i
+  ];
+  const matchedSubsystems = subsystems.filter((r2) => r2.test(text)).length;
+  if (matchedSubsystems < 3) return false;
+  const hasExplicitDB = /\b(postgres(ql)?|mysql|mongodb|mongo|redis|sqlite|supabase|dynamodb|cockroach)\b/i.test(text);
+  const hasExplicitAuth = /\b(jwt|oauth2?|basic.?auth|api.?key|session.?based|cookie.?auth)\b/i.test(text);
+  const hasExplicitStack = !!stackHint && !["api", "rest-api", "backend"].includes(stackHint);
+  const unspecifiedDimensions = [!hasExplicitDB, !hasExplicitAuth, !hasExplicitStack].filter(Boolean).length;
+  return unspecifiedDimensions >= 2;
+}
 function inferProjectSlug(text) {
   let cleaned = text.replace(/^(create|build|crie|cria|criar|fazer?|quero|i need|i want)\s+(uma|um|me\s+a?|an|a)?\s*/i, "").replace(/\s+(that|which|que|para|for|pra)\s+.*/i, "").trim();
   if (!cleaned) cleaned = text;
   const slug = cleaned.toLowerCase().normalize("NFKD").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, 64);
   return slug || void 0;
 }
+function normalizeProjectNameCandidate(value) {
+  const normalized = normalizeText3(value);
+  if (!normalized) return void 0;
+  return inferProjectSlug(normalized) ?? void 0;
+}
 function normalizeText3(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : void 0;
@@ -141032,7 +141387,7 @@ function detectStackHint(text) {
 }
 function parseField(text, labels) {
   for (const label of labels) {
-    const regex = new RegExp(`^\\s*${label}\\s*:\\s*(.+)$`, "im");
+    const regex = new RegExp(`(?:^|[\\n.,;!?]\\s*)${label}\\s*:\\s*(.+)$`, "im");
     const match = text.match(regex);
     if (match?.[1]) return normalizeText3(match[1]);
   }
@@ -141044,12 +141399,12 @@ function parseIdeaBlock(text) {
 }
 function parseExplicitProjectName(text) {
   const match = text.match(/\b(?:called|named|chamado)\s+[`"'“”‘’]?([a-z0-9][a-z0-9-]{1,63})[`"'“”‘’]?(?=$|[\s.,!?;:])/i);
-  return match?.[1]?.toLowerCase();
+  return normalizeProjectNameCandidate(match?.[1]?.toLowerCase());
 }
 function parseBootstrapRequest(text) {
   const repoUrl = parseField(text, ["repository url", "repo url", "reposit[o\xF3]rio url", "github repo"]);
   const rawIdea = parseIdeaBlock(text) ?? text.trim();
-  const projectName = parseField(text, ["project name", "nome do projeto", "repo name", "repository name"]) ?? parseExplicitProjectName(text);
+  const projectName = normalizeProjectNameCandidate(parseField(text, ["project name", "nome do projeto", "repo name", "repository name"])) ?? parseExplicitProjectName(text);
   const repoPath = parseField(text, ["local repository path", "repo path", "caminho local", "local path"]);
   const explicitStack = parseField(text, ["stack", "framework", "linguagem"]);
   const stackHint = (explicitStack ? normalizeStackHint(explicitStack) : "") || detectStackHint(text);
@@ -141228,25 +141583,26 @@ function parseClarificationResponse(text, session) {
     if (autoPatterns.test(normalizeUserResponse(text))) {
       return { recognized: true, projectName: inferProjectSlug(session.rawIdea) ?? `project-${Date.now()}`, stackHint: session.stackHint ?? void 0 };
     }
-    const nameField = parseField(text, ["project name", "nome do projeto", "nome", "name"]);
+    const nameField = normalizeProjectNameCandidate(parseField(text, ["project name", "nome do projeto", "nome", "name"]));
     if (nameField) {
       return { recognized: true, projectName: nameField, stackHint: session.stackHint ?? void 0 };
     }
-    if (trimmed.length > 0 && trimmed.length <= 64) {
-      return { recognized: true, projectName: trimmed, stackHint: session.stackHint ?? void 0 };
+    const normalizedInlineName = trimmed.length <= 64 ? normalizeProjectNameCandidate(trimmed) : void 0;
+    if (normalizedInlineName) {
+      return { recognized: true, projectName: normalizedInlineName, stackHint: session.stackHint ?? void 0 };
     }
     return { recognized: false };
   }
+  const projectNameFromField = normalizeProjectNameCandidate(parseField(text, ["project name", "nome do projeto", "nome", "name"]));
+  const nameItMatch = !projectNameFromField ? text.match(/(?:name|call|chamar?)\s+(?:it\s+)?([\w-]{2,64})/i) : null;
+  const inlineName = projectNameFromField ?? normalizeProjectNameCandidate(nameItMatch?.[1]);
   const stackField = parseField(text, ["stack", "framework", "linguagem", "language"]);
   if (stackField) {
     const normalizedStack = normalizeStackHint(stackField) || detectStackHint(stackField) || stackField;
-    return { recognized: true, stackHint: normalizedStack };
+    return { recognized: true, stackHint: normalizedStack, projectName: inlineName };
   }
   const detectedStack = detectStackHint(text);
   if (detectedStack) {
-    const projectNameFromField = parseField(text, ["project name", "nome do projeto", "nome", "name"]);
-    const nameItMatch = !projectNameFromField ? text.match(/(?:name|call|chamar?)\s+(?:it\s+)?([\w-]{2,64})/i) : null;
-    const inlineName = projectNameFromField ?? (nameItMatch ? nameItMatch[1].toLowerCase().replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-") || void 0 : void 0);
     return { recognized: true, stackHint: detectedStack, projectName: inlineName };
   }
   const lower2 = normalizeUserResponse(text);
@@ -141471,6 +141827,27 @@ async function handleTelegramBootstrapDmMessage(ctx, rawConversationId, content)
     ));
     return;
   }
+  if (detectScopeAmbiguity(content, parsed.stackHint)) {
+    const existingSession2 = await readTelegramBootstrapSession(workspaceDir, conversationId);
+    const alreadyAskedScope = existingSession2?.pendingClarification === "scope";
+    if (!alreadyAskedScope) {
+      await upsertTelegramBootstrapSession(workspaceDir, {
+        conversationId,
+        rawIdea: content,
+        stackHint: parsed.stackHint ?? void 0,
+        projectName: parsed.projectName ?? parsed.projectSlug ?? void 0,
+        status: "clarifying",
+        pendingClarification: "scope",
+        language
+      });
+      const clarifyMsg = BOOTSTRAP_MESSAGES.clarifyScope[language](content);
+      await sendTelegramText(ctx, rawConversationId, clarifyMsg);
+      return;
+    }
+    if (existingSession2?.stackHint) {
+      incomingRequest.stackHint = existingSession2.stackHint;
+    }
+  }
   const handled = await runBootstrapPreflightOrFail(
     ctx,
     conversationId,
@@ -143844,6 +144221,7 @@ async function performHealthPass(workspaceDir, projectSlug, project, sessions, p
       workflow: resolvedConfig?.workflow,
       dispatchConfirmTimeoutMs: resolvedConfig?.timeouts?.dispatchConfirmTimeoutMs,
       healthGracePeriodMs: resolvedConfig?.timeouts?.healthGracePeriodMs,
+      stallTimeoutMinutes,
       runCommand,
       notificationConfig: notifyConfig
     });
@@ -146221,8 +146599,18 @@ function stringifyAnswerRecord(record2) {
   }
   return normalized;
 }
-function deriveProjectName(repoUrl, projectName) {
+function extractExplicitProjectName(text) {
+  if (!text) return null;
+  const fieldMatch = text.match(/(?:^|[\n.,;!?]\s*)(?:project name|repo name|repository name|nome do projeto)\s*:\s*([a-z0-9][a-z0-9-]{1,63})\b/i);
+  if (fieldMatch?.[1]) return fieldMatch[1].trim().toLowerCase();
+  const inlineMatch = text.match(/\b(?:called|named|chamado)\s+[`"'“”‘’]?([a-z0-9][a-z0-9-]{1,63})[`"'“”‘’]?(?=$|[\s.,!?;:])/i);
+  if (inlineMatch?.[1]) return inlineMatch[1].trim().toLowerCase();
+  return null;
+}
+function deriveProjectName(repoUrl, projectName, freeText) {
   if (projectName) return projectName;
+  const parsedFromText = extractExplicitProjectName(freeText ?? null);
+  if (parsedFromText) return parsedFromText;
   if (!repoUrl) return null;
   const sanitized = repoUrl.replace(/\/+$/, "");
   const lastSegment = sanitized.split("/").pop();
@@ -146312,9 +146700,11 @@ function normalizeGenesisRequest(params, existingPayload) {
     throw new Error('phase is required and must be "discover" or "commit"');
   }
   const repoUrl = normalizeOptionalString(params.repo_url) ?? existingPayload?.metadata.repo_url ?? null;
+  const freeTextProjectSource = normalizeOptionalString(params.idea) ?? normalizeOptionalString(params.command) ?? existingPayload?.raw_idea ?? null;
   const projectName = deriveProjectName(
     repoUrl,
-    normalizeOptionalString(params.project_name) ?? existingPayload?.metadata.project_name ?? null
+    normalizeOptionalString(params.project_name) ?? existingPayload?.metadata.project_name ?? null,
+    freeTextProjectSource
   );
   const answersJson = {
     ...existingPayload?.metadata.answers_json ?? {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mestreyoda/fabrica",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Autonomous software engineering pipeline for OpenClaw. Turns ideas into deployed code via intake, dispatch, review, test, and merge.",
   "type": "module",
   "main": "./dist/index.js",