@mestreyoda/fabrica 0.2.15 → 0.2.16

package/README.md

@@ -96,7 +96,17 @@ operational/workspace state, then tells you what is still missing.
 
 ## Quick start
 
-**1. Install Fabrica**:
+This is the minimum recommended path to get Fabrica working end-to-end with the official product flow.
+
+**1. Authenticate GitHub CLI**:
+
+```bash
+gh auth status || gh auth login
+```
+
+Fabrica uses authenticated `gh` CLI for GitHub operations in the default setup.
+
+**2. Install Fabrica**:
 
 ```bash
 openclaw plugins install @mestreyoda/fabrica
@@ -104,37 +114,69 @@ openclaw plugins install @mestreyoda/fabrica
 
 The plugin should load immediately after install, without manual remediation.
 
-**2. Confirm loadability**:
+**3. Confirm loadability**:
 
 ```bash
 openclaw plugins inspect fabrica
 ```
 
-**3. Configure operational state for a workspace**:
+**4. Configure Fabrica for a workspace**:
 
 ```bash
 openclaw fabrica doctor workspace --workspace /path/to/workspace
 openclaw fabrica setup --workspace /path/to/workspace --new-agent fabrica
 ```
 
-Use `openclaw fabrica setup --agent <id>` if you already have an agent. GitHub,
-Telegram, and webhook behavior are separate operational concerns, not
-installation dependencies.
+Use `openclaw fabrica setup --agent <id>` if you already have an agent.
+
+When the official Telegram DM bootstrap flow is configured (`bootstrapDmEnabled=true`
+plus `projectsForumChatId`), `openclaw fabrica setup` also prepares the dedicated
+internal `genesis` agent automatically.
+
+**5. Configure Telegram for the official Fabrica flow**:
+
+The official flow is:
+- Telegram DM with the bot for new-project intake
+- one Telegram forum group for project topics/timelines
+
+At minimum, when DM bootstrap is enabled, set:
+- `plugins.entries.fabrica.config.telegram.bootstrapDmEnabled=true`
+- `plugins.entries.fabrica.config.telegram.projectsForumChatId=<YOUR_PROJECTS_FORUM_CHAT_ID>`
+
+If `projectsForumChatId` is missing while DM bootstrap is enabled, Fabrica can accept the DM but will fail when it needs to create the project topic.
+
+**6. Validate operational readiness**:
+
+```bash
+openclaw plugins inspect fabrica
+openclaw fabrica doctor workspace --workspace /path/to/workspace
+```
 
 **Environment provisioning note**:
 
-Developer and tester pickup now pass through a stack environment gate. For
-supported stacks such as `python-cli`, Fabrica provisions the required toolchain
-and project-local environment before dispatching workers, instead of discovering
-missing dependencies inside a live worker run.
+Developer and tester pickup pass through a stack environment gate. Fabrica
+prepares the project environment before dispatching real work, instead of
+finding missing dependencies inside a live worker run.
+
+For Python projects, this includes just-in-time `uv` installation when needed,
+a shared toolchain, and a project-local `.venv`.
 
-**4. Restart the gateway**:
+For existing Node projects, Fabrica expects a reproducible lockfile
+(`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lock`) before
+real developer/tester dispatch. Greenfield scaffold mode can materialize the
+first deterministic lockfile, but regular runtime pickup fails closed without
+one.
+
+`dryRun: true` skips environment provisioning entirely and remains side-effect
+free.
+
+**7. Restart the gateway if needed**:
 
 ```bash
 systemctl --user restart openclaw-gateway.service
 ```
 
-**5. Trigger a new project programmatically**:
+**8. Trigger a new project programmatically**:
 
 ```bash
 cd ~/fabrica  # GitHub clone install only
@@ -146,13 +188,13 @@ npx tsx scripts/genesis-trigger.ts "A CLI tool that counts words in a file" \
 
 Remove `--dry-run` to execute for real.
 
-**6. Watch the pipeline run**:
+**9. Watch the pipeline run**:
 
 ```bash
 tail -f ~/.openclaw/workspace/logs/genesis.log
 ```
 
-**7. Check metrics**:
+**10. Check metrics**:
 
 ```bash
 openclaw fabrica metrics
@@ -223,7 +265,11 @@ Use plugin config when you want explicit webhook behavior or provider auth profi
 
 ### With Telegram
 
-Telegram enables DM-based project bootstrap, per-project forum topics, and a separate ops chat for heartbeat and cron notifications.
+Telegram is the primary human-facing entrypoint for Fabrica:
+- DM with the bot for new-project intake and short clarifications
+- one Telegram forum group where Fabrica creates one topic per project
+
+Recommended minimum Telegram configuration:
 
 ```json
 {
@@ -243,8 +289,7 @@ Telegram enables DM-based project bootstrap, per-project forum topics, and a sep
           "telegram": {
             "bootstrapDmEnabled": true,
             "projectsForumChatId": "<YOUR_PROJECTS_FORUM_CHAT_ID>",
-            "projectsForumAccountId": "<OPTIONAL_TELEGRAM_ACCOUNT_ID>",
-            "opsChatId": "<YOUR_OPS_CHAT_ID>"
+            "projectsForumAccountId": "<OPTIONAL_TELEGRAM_ACCOUNT_ID>"
           }
         }
       }
@@ -253,7 +298,15 @@ Telegram enables DM-based project bootstrap, per-project forum topics, and a sep
 }
 ```
 
-With Telegram enabled, send a project idea to the bot in a DM. Fabrica will ask clarifying questions, provision the GitHub repo, create a dedicated forum topic for the project, and keep ops-only notifications on the separate `opsChatId` route.
+`projectsForumChatId` is the key Fabrica-specific Telegram setting for the official DM → topic flow.
+
+When both `bootstrapDmEnabled=true` and `projectsForumChatId` are present,
+`openclaw fabrica setup` automatically prepares the internal `genesis` agent used
+for the DM intake path.
+
+`opsChatId` still exists in plugin config for deployments that want a separate ops-only route, but it is not required for the core product flow.
+
+With Telegram enabled, send a project idea to the bot in a DM. Fabrica will ask clarifying questions, provision the GitHub repo, create a dedicated forum topic for the project, and continue the project lifecycle in that topic.
 
 Project topics are event-driven timelines. Fabrica emits explicit messages for
 worker start, worker completion, review queueing, reviewer reject/approve, and

package/dist/index.js

@@ -111347,8 +111347,8 @@ import fsSync from "node:fs";
 import path5 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 function getCurrentVersion() {
-  if ("0.2.15") {
-    return "0.2.15";
+  if ("0.2.16") {
+    return "0.2.16";
   }
   try {
     const pkgPath = path5.join(THIS_DIR, "..", "..", "package.json");
@@ -127660,6 +127660,7 @@ async function registerProject(params) {
     }
     await writeProjects(workspaceDir, data);
     projectsPersisted = true;
+    let finalResolvedConfig = resolvedConfig;
     if (autonomousProject) {
       workflowOverrideCreated = await ensureAutonomousWorkflowOverride(
         workspaceDir,
@@ -127676,6 +127677,7 @@ async function registerProject(params) {
           `Autonomous DM bootstrap resolved reviewPolicy="${persistedConfig.workflow.reviewPolicy}" for "${slug}", expected "${expectedReviewPolicy}"`
         );
       }
+      finalResolvedConfig = persistedConfig;
     }
     promptsCreated = await scaffoldPromptFiles(workspaceDir, slug);
     await log(workspaceDir, "project_register", {
@@ -127690,7 +127692,7 @@ async function registerProject(params) {
       deployUrl: deployUrl || null,
       isNewProject: !existing,
       workflowOverrideCreated,
-      reviewPolicy: resolvedConfig.workflow.reviewPolicy ?? "human"
+      reviewPolicy: finalResolvedConfig.workflow.reviewPolicy ?? "human"
     });
     const action = existing ? "Channel added to existing project" : `Project "${name}" created`;
     const promptsNote = promptsCreated ? " Prompt files scaffolded." : "";
@@ -127710,8 +127712,8 @@ async function registerProject(params) {
       workflowOverrideCreated,
       isNewProject: !existing,
       activeWorkflow: {
-        reviewPolicy: resolvedConfig.workflow.reviewPolicy ?? "human",
-        testPhase: Object.values(resolvedConfig.workflow.states).some(
+        reviewPolicy: finalResolvedConfig.workflow.reviewPolicy ?? "human",
+        testPhase: Object.values(finalResolvedConfig.workflow.states).some(
           (s2) => s2.role === "tester" && (s2.type === "queue" || s2.type === "active")
         ),
         hint: "The user can change the review policy or enable the test phase \u2014 call workflow_guide for the full reference."
@@ -129995,9 +129997,11 @@ async function ensureGenesisAgent(runtime, runCommand, opts) {
     throw new Error(`Failed to create genesis agent: ${err.message}`);
   }
   const updatedConfig = runtime.config.loadConfig();
-  const bindings = (updatedConfig.bindings ?? []).filter(
-    (b) => !(b.match?.channel === "telegram" && !b.match?.peer && b.agentId === "main")
-  );
+  const bindings = (updatedConfig.bindings ?? []).filter((b) => {
+    const isMainChannelWideTelegram = b.match?.channel === "telegram" && !b.match?.peer && b.agentId === "main";
+    if (!isMainChannelWideTelegram) return true;
+    return !opts?.forumGroupId;
+  });
   if (!bindings.some((b) => b.agentId === "genesis" && b.match?.channel === "telegram" && !b.match?.peer)) {
     bindings.push({ agentId: "genesis", match: { channel: "telegram" } });
   }
@@ -135830,12 +135834,13 @@ async function ensurePythonToolchain(runCommand, homeDir) {
     }
     await fs32.rm(toolchainPath, { recursive: true, force: true });
   }
+  const uvCmd = await ensureUv(runCommand);
   await fs32.mkdir(path32.dirname(toolchainPath), { recursive: true });
-  const venvResult = await runCommand("uv", ["venv", toolchainPath], { timeout: 6e4 });
+  const venvResult = await runCommand(uvCmd, ["venv", toolchainPath], { timeout: 6e4 });
   if (venvResult.exitCode !== 0) {
     throw new Error(`Failed to create toolchain venv: ${venvResult.stderr}`);
   }
-  const installResult = await runCommand("uv", [
+  const installResult = await runCommand(uvCmd, [
     "pip",
     "install",
     "-p",
@@ -136103,7 +136108,7 @@ async function ensurePythonEnvironment(repoPath, stack, runCommand) {
       fingerprint
     };
   }
-  await ensureUv(runCommand);
+  const uvCmd = await ensureUv(runCommand);
   const uvLock = await pathExists2(path32.join(repoPath, "uv.lock"));
   const pyproject = await pathExists2(path32.join(repoPath, "pyproject.toml"));
   const requirements = await pathExists2(path32.join(repoPath, "requirements.txt"));
@@ -136122,10 +136127,25 @@ async function ensurePythonEnvironment(repoPath, stack, runCommand) {
       reason: "missing_pyproject_or_requirements"
     };
   }
+  if (uvLock && !pyproject) {
+    return {
+      ready: false,
+      skipped: false,
+      stack,
+      family: "python",
+      toolchain: "uv",
+      packageManager: "uv",
+      lockfile: "uv.lock",
+      environmentPath: null,
+      commandsRun,
+      fingerprint,
+      reason: "uv_lock_requires_pyproject"
+    };
+  }
   await ensurePythonToolchain(runCommand);
   if (uvLock) {
     await runAndAssert(runCommand, repoPath, commandsRun, {
-      cmd: "uv",
+      cmd: uvCmd,
       args: ["sync", "--locked"],
       reason: "uv sync"
     });
@@ -136144,13 +136164,13 @@ async function ensurePythonEnvironment(repoPath, stack, runCommand) {
     };
   }
   await runAndAssert(runCommand, repoPath, commandsRun, {
-    cmd: "uv",
+    cmd: uvCmd,
     args: ["venv", ".venv"],
     reason: "create project-local virtualenv with uv"
   });
-  if (requirements) {
+  if (requirements && !pyproject) {
     await runAndAssert(runCommand, repoPath, commandsRun, {
-      cmd: "uv",
+      cmd: uvCmd,
       args: ["pip", "install", "--python", ".venv/bin/python", "-r", "requirements.txt"],
       reason: "install requirements.txt dependencies with uv"
     });
@@ -136158,7 +136178,7 @@ async function ensurePythonEnvironment(repoPath, stack, runCommand) {
   if (pyproject) {
     const hasDevExtra = await hasPyprojectDevExtra(repoPath);
     await runAndAssert(runCommand, repoPath, commandsRun, {
-      cmd: "uv",
+      cmd: uvCmd,
       args: ["pip", "install", "--python", ".venv/bin/python", "-e", hasDevExtra ? ".[dev]" : "."],
       reason: hasDevExtra ? "install editable project with dev extras via uv" : "install editable project via uv"
     });
@@ -137436,6 +137456,7 @@ function getProjectEnvironmentState(project, stack) {
 
 // lib/test-env/runtime.ts
 var STALE_PROVISIONING_WINDOW_MS = 10 * 60 * 1e3;
+var FAILED_RETRY_DELAY_MS = 60 * 1e3;
 function projectEnvironmentStateFor(project, stack, updates) {
   const current = getProjectEnvironmentState(project, stack);
   return getProjectEnvironmentState({
@@ -137449,6 +137470,7 @@ function projectEnvironmentStateFor(project, stack, updates) {
 async function ensureEnvironmentReady(opts) {
   const contract = resolveStackEnvironmentContract(opts.stack);
   const current = getProjectEnvironmentState(opts.project, opts.stack);
+  const retryAtMs = current.nextProvisionRetryAt ? Date.parse(current.nextProvisionRetryAt) : Number.NaN;
   if (current.status === "ready") {
     return { ready: true, state: current };
   }
@@ -137456,6 +137478,16 @@ async function ensureEnvironmentReady(opts) {
     const provisioningStartedAt = current.provisioningStartedAt ? Date.parse(current.provisioningStartedAt) : Number.NaN;
     const provisioningIsFresh = Number.isFinite(provisioningStartedAt) && Date.now() - provisioningStartedAt < STALE_PROVISIONING_WINDOW_MS;
     if (provisioningIsFresh) {
+      await log(opts.workspaceDir, "environment_bootstrap_blocked", {
+        projectSlug: opts.projectSlug,
+        stack: opts.stack,
+        mode: opts.mode,
+        status: current.status,
+        reason: "provisioning_in_progress",
+        provisioningStartedAt: current.provisioningStartedAt ?? null,
+        contractVersion: current.contractVersion ?? contract.version
+      }).catch(() => {
+      });
       return { ready: false, state: current };
     }
     await log(opts.workspaceDir, "environment_bootstrap_retry_scheduled", {
@@ -137466,7 +137498,18 @@ async function ensureEnvironmentReady(opts) {
     }).catch(() => {
     });
   }
-  if (current.status === "failed" && current.nextProvisionRetryAt && Date.parse(current.nextProvisionRetryAt) > Date.now()) {
+  if (current.status === "failed" && current.nextProvisionRetryAt && Number.isFinite(retryAtMs) && retryAtMs > Date.now()) {
+    await log(opts.workspaceDir, "environment_bootstrap_blocked", {
+      projectSlug: opts.projectSlug,
+      stack: opts.stack,
+      mode: opts.mode,
+      status: current.status,
+      reason: "retry_backoff_active",
+      blockedUntil: current.nextProvisionRetryAt,
+      lastProvisionError: current.lastProvisionError ?? null,
+      contractVersion: current.contractVersion ?? contract.version
+    }).catch(() => {
+    });
     return { ready: false, state: current };
   }
   await updateProjectEnvironment(opts.workspaceDir, opts.projectSlug, {
@@ -137480,6 +137523,8 @@ async function ensureEnvironmentReady(opts) {
   await log(opts.workspaceDir, "environment_bootstrap_started", {
     projectSlug: opts.projectSlug,
     stack: opts.stack,
+    mode: opts.mode,
+    previousStatus: current.status,
     contractVersion: contract.version
   }).catch(() => {
   });
@@ -137505,7 +137550,7 @@ async function ensureEnvironmentReady(opts) {
     reason: error48 instanceof Error ? error48.message : "environment_bootstrap_failed"
   }));
   if (!result.ready) {
-    const nextRetryAt = new Date(Date.now() + 6e4).toISOString();
+    const nextRetryAt = new Date(Date.now() + FAILED_RETRY_DELAY_MS).toISOString();
     const state2 = projectEnvironmentStateFor(opts.project, opts.stack, {
       status: "failed",
       stack: opts.stack,
@@ -137526,8 +137571,11 @@ async function ensureEnvironmentReady(opts) {
     await log(opts.workspaceDir, "environment_bootstrap_retry_scheduled", {
       projectSlug: opts.projectSlug,
       stack: opts.stack,
+      mode: opts.mode,
       nextRetryAt,
-      reason: state2.lastProvisionError ?? "environment_bootstrap_failed"
+      retryDelayMs: FAILED_RETRY_DELAY_MS,
+      reason: state2.lastProvisionError ?? "environment_bootstrap_failed",
+      contractVersion: state2.contractVersion ?? contract.version
     }).catch(() => {
     });
     return { ready: false, state: state2 };
@@ -137554,6 +137602,9 @@ async function ensureEnvironmentReady(opts) {
   await log(opts.workspaceDir, "environment_ready_confirmed", {
     projectSlug: opts.projectSlug,
     stack: opts.stack,
+    mode: opts.mode,
+    previousStatus: current.status,
+    lastProvisionedAt: provisionedAt,
     contractVersion: contract.version
   }).catch(() => {
   });
@@ -137620,6 +137671,15 @@ async function cleanupExpired(workspaceDir, ttlMs = DEFAULT_TTL_MS2) {
 
 // lib/services/tick.ts
 init_registry();
+function classifyEnvironmentGateSkip(state) {
+  if (state.status === "provisioning") return "environment_provisioning_in_progress";
+  if (state.status === "failed") {
+    if (state.nextProvisionRetryAt) return "environment_retry_backoff_active";
+    return "environment_failed";
+  }
+  if (state.status === "pending") return "environment_pending_provisioning";
+  return "environment_not_ready";
+}
 async function projectTick(opts) {
   const {
     workspaceDir,
@@ -137859,12 +137919,16 @@ async function projectTick(opts) {
         runCommand
       });
       if (!environment.ready) {
-        skipped.push({ role, reason: "environment_not_ready" });
+        const environmentSkipReason = classifyEnvironmentGateSkip(environment.state);
+        skipped.push({ role, reason: environmentSkipReason });
         await log(workspaceDir, "dispatch_blocked_environment_not_ready", {
           projectSlug,
           role,
           issueId: issue2.iid,
-          environmentStatus: environment.state.status
+          reason: environmentSkipReason,
+          environmentStatus: environment.state.status,
+          nextProvisionRetryAt: environment.state.nextProvisionRetryAt ?? null,
+          lastProvisionError: environment.state.lastProvisionError ?? null
         }).catch(() => {
         });
         continue;
@@ -140081,14 +140145,16 @@ Erro: ${result.error ?? "erro desconhecido"}`
   );
 }
 function registerTelegramBootstrapHook(api, ctx) {
+  const telegramConfig = readFabricaTelegramConfig(ctx.pluginConfig);
   const apiRuntime = api.runtime;
   const hasGenesis = apiRuntime ? hasGenesisAgent(apiRuntime) : false;
-  if (!hasGenesis) {
+  const usesDedicatedGenesisBootstrap = hasGenesis && telegramConfig.bootstrapDmEnabled && Boolean(telegramConfig.projectsForumChatId);
+  if (!usesDedicatedGenesisBootstrap) {
     api.on("before_dispatch", async (event, eventCtx) => {
       const hookCtx = eventCtx;
       if (hookCtx.channelId !== "telegram") return void 0;
-      const telegramConfig = readFabricaTelegramConfig(ctx.pluginConfig);
-      if (!telegramConfig.bootstrapDmEnabled) return void 0;
+      const telegramConfig2 = readFabricaTelegramConfig(ctx.pluginConfig);
+      if (!telegramConfig2.bootstrapDmEnabled) return void 0;
       const conversationId = resolveTelegramBootstrapDmConversationIdFromHookContext(hookCtx);
       if (!conversationId) return void 0;
       const dispatchEvent = event;
@@ -140172,11 +140238,11 @@ function registerTelegramBootstrapHook(api, ctx) {
       }
     });
   }
-  if (hasGenesis) return;
+  if (usesDedicatedGenesisBootstrap) return;
   api.on("message_received", async (event, eventCtx) => {
     if (eventCtx.channelId !== "telegram") return;
-    const telegramConfig = readFabricaTelegramConfig(ctx.pluginConfig);
-    if (!telegramConfig.bootstrapDmEnabled) return;
+    const telegramConfig2 = readFabricaTelegramConfig(ctx.pluginConfig);
+    if (!telegramConfig2.bootstrapDmEnabled) return;
     const rawConversationId = String(eventCtx.conversationId ?? "").trim();
     const content = String(event.content ?? "").trim();
     if (!rawConversationId || !content) return;
@@ -142373,6 +142439,8 @@ function createSetupTool(ctx) {
 ${written.map((f3) => `  ${f3}`).join("\n")}` : "All files already exist \u2014 nothing to write."
         });
       }
+      const telegramConfig = readFabricaTelegramConfig(ctx.pluginConfig);
+      const shouldEnsureGenesis = telegramConfig.bootstrapDmEnabled && Boolean(telegramConfig.projectsForumChatId);
       const result = await runSetup({
         runtime: ctx.runtime,
         newAgentName: params.newAgentName,
@@ -142382,7 +142450,9 @@ ${written.map((f3) => `  ${f3}`).join("\n")}` : "All files already exist \u2014
         workspacePath: params.newAgentName ? void 0 : toolCtx.workspaceDir,
         models: params.models,
         projectExecution: params.projectExecution,
-        runCommand: ctx.runCommand
+        runCommand: ctx.runCommand,
+        ensureGenesis: shouldEnsureGenesis,
+        forumGroupId: telegramConfig.projectsForumChatId
       });
       const lines = [
         result.agentCreated ? `Agent "${result.agentId}" created` : `Configured "${result.agentId}"`,
@@ -142536,16 +142606,19 @@ Call \`setup\` with the collected answers:
 After setup completes, explain the current operating model:
 
 \u{1F4F1} **Telegram Guidance:**
-Fabrica uses:
+Fabrica uses the following official path:
 1. **DM with the bot** for new-project bootstrap and short clarifications
 2. **One forum group for projects** with **one topic per project**
-3. **One separate ops group** for health/cron/status
 
-**Recommended Setup:**
+**Minimum recommended setup:**
 1. Keep the bot reachable in DM
 2. Add the bot to the projects forum group
 3. Ensure the bot can create/manage topics there
-4. Keep cron/ops notifications in a separate group
+4. Set 'plugins.entries.fabrica.config.telegram.projectsForumChatId' to that forum group ID
+
+**Optional / advanced:**
+- 'projectsForumAccountId' if a specific Telegram account should own forum actions
+- 'opsChatId' only if you want a separate ops-only route; it is not required for the core product flow
 
 **Step 5: Project Registration**
 Explain that the canonical path for new projects is:
@@ -142562,10 +142635,10 @@ Manual \`project_register\` remains available for admin recovery and exceptional
 **Step 6: Workflow Overview**
 After project registration, briefly tell the user about their active workflow:
 
-- **Review policy**: agent for autonomous DM-created projects \u2014 PRs flow through Fabrica review by default.
-- **Test phase**: skipped by default \u2014 the testing step is in the workflow but issues bypass it automatically. To enable testing for a specific issue, remove the \`test:skip\` label. To enable globally, set \`testPolicy: agent\` in workflow.yaml.
-- **Customization**: They can change the review policy (human/agent/auto), enable testing (testPolicy: agent), or override settings per project. Point them to \`workflow.yaml\` in the Fabrica workspace data directory.
-- Say: "Autonomous projects created from DM use **agent review** and **testing skipped** by default. You can enable testing per-issue by removing the \`test:skip\` label, or globally by setting \`testPolicy: agent\` in your workflow.yaml."
+- **Review policy**: autonomous DM-created projects use **agent review** by default as a quality guardrail.
+- **Test phase**: the current workflow still defaults to 'testPolicy: skip' unless explicitly enabled. Explain this as the current operational default, not the quality ideal of the product.
+- **Customization**: They can change the review policy ('human', 'agent', 'skip'), enable testing ('testPolicy: agent'), or override settings per project. Point them to 'workflow.yaml' in the Fabrica workspace data directory.
+- Say: "Autonomous projects created from DM use **agent review** by default. Testing is still skipped by default in the current workflow unless you enable it, so if you need stricter QA by default you should change 'testPolicy' in your workflow.yaml."
 
 ## Guidelines
 - Be conversational and friendly. Ask one question at a time.
@@ -144163,19 +144236,20 @@ async function checkConfigLoads(workspacePath) {
   }
 }
 function checkTelegramBootstrapConfig(pluginConfig) {
-  const telegram = pluginConfig?.telegram;
-  if (!telegram?.bootstrapDmEnabled) {
+  const rawTelegram = pluginConfig?.telegram ?? {};
+  const telegram = readFabricaTelegramConfig(pluginConfig);
+  if (rawTelegram.bootstrapDmEnabled === false) {
     return {
       name: "config:telegram-bootstrap",
       severity: "ok",
-      message: "Telegram DM bootstrap is disabled (bootstrapDmEnabled not set)"
+      message: "Telegram DM bootstrap is disabled (bootstrapDmEnabled=false)"
     };
   }
-  if (!telegram?.projectsForumChatId) {
+  if (!telegram.projectsForumChatId) {
     return {
       name: "config:telegram-bootstrap",
       severity: "warn",
-      message: "Telegram DM bootstrap is enabled (bootstrapDmEnabled=true) but projectsForumChatId is not configured \u2014 DM bootstrap will fail at runtime"
+      message: "Telegram DM bootstrap is active by default but projectsForumChatId is not configured in plugins.entries.fabrica.config.telegram \u2014 the official DM \u2192 topic flow will fail at runtime"
     };
   }
   return {
@@ -144442,13 +144516,21 @@ async function runSecurityDoctor(openclawHome) {
     severity: residualPlugins.length > 0 ? "warn" : "ok",
     message: residualPlugins.length > 0 ? `Residual plugins still enabled: ${residualPlugins.join(", ")}` : "No residual non-essential plugins enabled"
   });
-  const routerBinding = (config2.bindings ?? []).find(
+  const legacyRouterBinding = (config2.bindings ?? []).find(
     (binding) => binding.agentId === "genesis-router" && binding.match?.channel === "telegram"
   );
   checks.push({
     name: "bindings:telegram-router",
-    severity: routerBinding ? "warn" : "ok",
-    message: routerBinding ? "Telegram is still bound to genesis-router" : "Telegram is not bound to legacy genesis-router"
+    severity: legacyRouterBinding ? "warn" : "ok",
+    message: legacyRouterBinding ? "Telegram is still bound to legacy genesis-router" : "Telegram is not bound to legacy genesis-router"
+  });
+  const genesisBinding = (config2.bindings ?? []).find(
+    (binding) => binding.agentId === "genesis" && binding.match?.channel === "telegram" && !binding.match?.peer
+  );
+  checks.push({
+    name: "bindings:telegram-genesis",
+    severity: genesisBinding ? "ok" : "warn",
+    message: genesisBinding ? "Genesis agent owns the channel-wide Telegram DM binding" : "Genesis agent does not own a channel-wide Telegram binding"
   });
   try {
     await fs42.access(checklistPath);
@@ -144763,13 +144845,17 @@ function registerCli(program, ctx) {
       }
       if (Object.keys(roleModels).length > 0) models[role] = roleModels;
     }
+    const telegramConfig = readFabricaTelegramConfig(ctx.pluginConfig);
+    const shouldEnsureGenesis = telegramConfig.bootstrapDmEnabled && Boolean(telegramConfig.projectsForumChatId);
     const result = await runSetup({
       runtime: ctx.runtime,
       newAgentName: opts.newAgent,
       agentId: opts.agent,
       workspacePath: opts.workspace,
       models: Object.keys(models).length > 0 ? models : void 0,
-      runCommand: ctx.runCommand
+      runCommand: ctx.runCommand,
+      ensureGenesis: shouldEnsureGenesis,
+      forumGroupId: telegramConfig.projectsForumChatId
     });
     if (result.agentCreated) {
       console.log(`Agent "${result.agentId}" created`);
@@ -144791,9 +144877,15 @@ function registerCli(program, ctx) {
       }
     }
     console.log("\nDone! Next steps:");
-    console.log("  1. Keep the bot reachable in DM");
-    console.log("  2. Add the bot to the projects forum group and allow topic creation");
-    console.log("  3. Send the project idea to the bot in DM to bootstrap the project automatically");
+    if (shouldEnsureGenesis) {
+      console.log("  1. Keep the bot reachable in DM");
+      console.log("  2. Add the bot to the projects forum group and allow topic creation");
+      console.log("  3. Send the project idea to the bot in DM to bootstrap the project automatically");
+    } else {
+      console.log("  1. Run `openclaw fabrica doctor workspace --workspace <path>` to confirm workspace readiness");
+      console.log("  2. If you want the official Telegram DM \u2192 topic flow, set plugins.entries.fabrica.config.telegram.projectsForumChatId");
+      console.log("  3. Re-run `openclaw fabrica setup` after the Telegram forum config is in place");
+    }
   });
   const doctor = fabrica.command("doctor").description("Diagnose workspace integrity and optionally auto-fix issues");
   doctor.command("workspace").description("Diagnose workspace integrity and optionally auto-fix issues").option("-w, --workspace <path>", "Workspace directory").option("--fix", "Apply fixes for detected issues").action(async (opts) => {
@@ -146107,7 +146199,7 @@ var plugin = {
       },
       telegram: {
         type: "object",
-        description: "Telegram routing for DM bootstrap, project forum topics, and ops notifications.",
+        description: "Telegram routing for the official DM \u2192 project-topic flow. Core settings are DM bootstrap and the projects forum chat.",
         properties: {
           bootstrapDmEnabled: {
             type: "boolean",
@@ -146116,15 +146208,15 @@ var plugin = {
           },
           projectsForumChatId: {
             type: "string",
-            description: "Telegram forum group chat ID where Fabrica creates one topic per project."
+            description: "Telegram forum group chat ID where Fabrica creates one topic per project. This is the key Telegram setting for the official Fabrica flow."
           },
           projectsForumAccountId: {
             type: "string",
-            description: "Optional Telegram account ID to use when creating/sending project forum topics."
+            description: "Optional Telegram account ID to use when creating or sending project forum topic updates."
           },
           opsChatId: {
             type: "string",
-            description: "Telegram group/chat ID for cron, health, and ops-only notifications."
+            description: "Optional Telegram group/chat ID for separate ops-only notifications. Not required for the core DM \u2192 topic product flow."
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mestreyoda/fabrica",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "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",
@@ -18,8 +18,6 @@
     "genesis/",
     "fabrica.manifest.json",
     "openclaw.plugin.json",
-    "ARCHITECTURE.md",
-    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -50,7 +48,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/MestreY0d4-Uninter/fabrica.git"
+    "url": "git+https://github.com/MestreY0d4-Uninter/fabrica.git"
   },
   "homepage": "https://github.com/MestreY0d4-Uninter/fabrica#readme",
   "bugs": {

package/ARCHITECTURE.md

@@ -1,93 +0,0 @@
-# Architecture
-
-## Core shape
-
-Fabrica is implemented as a local OpenClaw plugin with the local repository as
-its source of truth.
-
-Main areas:
-
-- `lib/intake`
-  Intake, target resolution, impact analysis, task creation and triage.
-- `lib/github`
-  GitHub App auth, webhook ingestion, event store, PR binding, quality gate and
-  governance.
-- `lib/services`
-  Pipeline, heartbeat, queue scans and workflow execution helpers.
-- `lib/machines`
-  `FabricaRunMachine` and `LifecycleMachine` for explicit state transitions.
-- `lib/observability`
-  Pino logging, correlation context and OpenTelemetry spans.
-- `lib/dispatch`
-  DM bootstrap, Telegram topic routing, worker notifications and attachment hooks.
-- `lib/telegram`
-  Telegram config resolution and topic creation services.
-- `defaults`
-  Packaged assets and workflow defaults that ship with the plugin.
-- `genesis`
-  Packaged runtime assets still used by the plugin during the migration away
-  from older shell-driven flows.
-
-## Runtime model
-
-## Telegram routing model
-
-New project intake is DM-first. The Fabrica bot accepts a new-project request in
-Telegram DM, asks for missing essentials there if needed, and only creates the
-project topic when the intake is ready to register. For greenfield projects,
-repo provisioning now happens in the TS intake path before registration and
-issue creation.
-
-The canonic route identity for Telegram-backed projects is:
-
-`channel=telegram + channelId + messageThreadId`
-
-This avoids collisions between multiple projects inside the same Telegram forum
-group. After registration:
-
-- the project topic becomes the primary route for project messages
-- follow-ups inside that topic resolve the exact project
-- worker notifications and project lifecycle updates publish back to that topic
-- ops alerts stay in the separate ops group
-
-The hot path for GitHub is:
-
-`webhook -> event store -> FabricaRun -> Quality Gate -> artifactOfRecord -> done`
-
-Important invariants:
-
-- a cycle never closes with an open canonical PR
-- `Done` requires `artifactOfRecord`
-- duplicate GitHub deliveries must not duplicate effects
-- force-push updates the canonical binding instead of spawning duplicate runs
-
-## Installation model
-
-Fabrica is distributed as a self-contained OpenClaw plugin package.
-
-The supported operator path is:
-
-```bash
-openclaw plugins install @mestreyoda/fabrica
-```
-
-The installed extension must be loadable in isolation. Fabrica may depend on
-OpenClaw only through the plugin host ABI and runtime objects passed by the
-host. It must not require manual symlinks, local `npm install`, or host-global
-module resolution to load.
-
-External credentials and routes such as GitHub auth, Telegram chat IDs, and
-webhook secrets are operational configuration, not installation dependencies.
-Fabrica's `doctor` and `setup` flows guide and validate that operational
-configuration where applicable.
-
-## Operational notes
-
-- Gateway runtime is managed by the OpenClaw systemd service.
-- GitHub webhook ingress is protected by GitHub signature validation inside the
-  plugin; the route itself must remain reachable without gateway bearer auth.
-- GitHub App and webhook credentials are expected to come from the Fabrica
-  plugin config (`openclaw.json`) using direct values and credential file paths;
-  legacy env-based fields remain only as compatibility fallback.
-- Structured logs and OpenTelemetry spans are emitted by the plugin itself.
-- Security validation lives in `openclaw fabrica doctor security --json`.

package/CHANGELOG.md

@@ -1,42 +0,0 @@
-# Changelog
-
-## 0.2.15 - 2026-04-03
-
-- Hardened Telegram DM intake around durable `pending_classify` / `classifying` recovery, newer-attempt ownership, and explicit late-classify reconciliation.
-- Added runtime-aware DM claiming via `before_dispatch` plus short-lived message/conversation guards so Telegram prompts stay inside Fabrica instead of leaking to the generic OpenClaw agent.
-- Fixed greenfield scaffold canonical repo path handling so `metadata.repo_path` / `scaffold_plan.repo_local` survive all the way into `scaffold-project.sh` and published genesis assets.
-- Tightened bootstrap and register fail-closed behavior for unsupported stacks and missing materialized repositories, preventing half-registered validation projects.
-- Reset and revalidated the temporary Telegram validation harness, including a reusable runner path and regression coverage for read/wait flows.
-- Extended regression coverage for Telegram bootstrap recovery, scaffold path ownership, classify-step typing, and end-to-end hot-path stability.
-
-## 0.2.14 - 2026-04-02
-
-- Added a stack-aware environment gate so developer and tester pickup only start after project environments are provisioned and marked ready.
-- Hardened Python stack bootstrap around durable environment state, retry scheduling, and stale provisioning recovery without `sudo`.
-- Reworked worker recovery so observable activity without a canonical result enters bounded completion recovery instead of immediately corrupting dispatch health.
-- Made heartbeat distinguish accepted-but-idle dispatches, inconclusive completion, terminal sessions, and true dead sessions with cycle-aware ownership checks.
-- Added explicit timeline events for reviewer outcomes and worker recovery exhaustion, with cycle-aware dedupe and corrected destination-state messaging.
-- Preserved reviewer notification routing through plugin notification config instead of bypassing runtime settings.
-- Extended regression coverage for environment provisioning, gateway session transcript activity, heartbeat recovery, reviewer notifications, and end-to-end hot-path orchestration.
-
-## 0.2.13 - 2026-03-31
-
-- Disabled automatic pretty logging on TTY so the plugin no longer depends on `pino-pretty` during load.
-- Added a safe one-shot fallback to structured logs when pretty transport resolution or initialization fails.
-- Added logger transport regression coverage and promoted it into the hot-path test lane.
-
-## 0.2.12 - 2026-03-31
-
-- Made the published plugin self-contained by replacing remaining runtime helper imports from `openclaw/plugin-sdk`.
-- Added release gates for runtime-boundary and isolated installability verification, with fail-closed behavior, timeouts, and cleanup.
-- Documented the real install contract and workspace-scoped operational setup flow in the package README and architecture notes.
-- Aligned local deploy to the same contract by removing the extension `node_modules` symlink fallback.
-
-## 0.2.11 - 2026-03-31
-
-- Unified reviewer completion around the canonical `Review result: APPROVE|REJECT` contract.
-- Hardened dispatch identity and reduced heartbeat progression to repair-oriented behavior.
-- Enforced canonical PR selection across reviewer/tester and queue-side flows.
-- Preserved and hardened the Telegram three-plane model: DM bootstrap, project forum topics, and ops routing.
-- Restored confidence lanes for release verification with explicit `test:unit`, `test:e2e`, and `test:hot-path`.
-- Aligned plugin config governance and observability surfaces so runtime knobs are real and misleading signals no longer present themselves as authoritative.