@mestreyoda/fabrica 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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.

package/README.md

@@ -5,7 +5,7 @@
 
 > Autonomous software engineering pipeline for OpenClaw.
 
-Fabrica turns a natural-language project description into a fully executed engineering workflow: intake, specification, issue decomposition, development, code review, testing, and merge — with zero manual intervention. It orchestrates AI agents as specialized workers (developers, reviewers, testers) through a deterministic finite state machine.
+Fabrica turns a natural-language project description into a fully executed engineering workflow: intake, specification, issue decomposition, development, code review, testing, and merge. It orchestrates AI agents as specialized workers (developers, reviewers, testers) through a deterministic finite state machine, with repair-oriented recovery when runtime signals or stack environments are incomplete.
 
 ## How it works
 
@@ -34,7 +34,7 @@ Fabrica turns a natural-language project description into a fully executed engin
        done
 ```
 
-The heartbeat ticks every 60 seconds. On each tick, Fabrica alternates between a **repair** pass (fixes stale states) and a **triage** pass (advances work that is ready to move). No human intervention is required after the initial project description.
+The heartbeat ticks every 60 seconds. On each tick, Fabrica alternates between a **repair** pass (fixes stale states, retries incomplete completion signals, and reconciles broken runtime ownership) and a **triage** pass (advances work that is ready to move). No human intervention is required after the initial project description.
 
 ## Features
 
@@ -43,9 +43,12 @@ The heartbeat ticks every 60 seconds. On each tick, Fabrica alternates between a
 - **Pluggable AI workers** — each role (developer, reviewer, tester, architect) maps to a configurable model and level
 - **Polling-first GitHub integration** — uses `gh` CLI for all GitHub operations; no webhook infrastructure or GitHub App required
 - **Telegram bootstrap** (optional) — describe a new project via DM; Fabrica asks clarifying questions and provisions the repo automatically
+- **Stack-aware environment gate** — developer and tester dispatch only start after the project stack environment is provisioned and marked ready
+- **Lifecycle-driven worker completion** — reviewer, developer, tester, and architect completion resolve from agent lifecycle plus canonical result lines, not from fragile tool availability assumptions
+- **Detailed event timeline** — project topics receive explicit worker start, completion, review, rejection, and recovery events with cycle-aware dedupe
 - **Programmatic genesis** — trigger the full pipeline from a CLI script without Telegram
 - **Observability built-in** — audit log, metrics subcommand, heartbeat health checks, and OpenTelemetry tracing
-- **Safe-by-default** — conflict detection, mutex-guarded heartbeat, session validation, and label integrity guards
+- **Safe-by-default** — conflict detection, mutex-guarded heartbeat, stack bootstrap retries, session validation, completion recovery, and label integrity guards
 
 ## Requirements
 
@@ -54,6 +57,7 @@ The heartbeat ticks every 60 seconds. On each tick, Fabrica alternates between a
 - Node.js 20+ (for local development or programmatic genesis)
 - `gh` CLI authenticated to GitHub (required for issue and PR operations)
 - A GitHub organization or personal account where repositories will be created
+- For Python stacks, Fabrica provisions `uv` and project-local environments itself without `sudo`
 - (Optional) Telegram bot token and group chat IDs for DM bootstrap and notifications
 
 ## Installation
@@ -117,6 +121,13 @@ Use `openclaw fabrica setup --agent <id>` if you already have an agent. GitHub,
 Telegram, and webhook behavior are separate operational concerns, not
 installation dependencies.
 
+**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.
+
 **4. Restart the gateway**:
 
 ```bash
@@ -244,6 +255,11 @@ 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.
 
+Project topics are event-driven timelines. Fabrica emits explicit messages for
+worker start, worker completion, review queueing, reviewer reject/approve, and
+operational recovery events, with cycle-aware dedupe so late deliveries from an
+older dispatch do not masquerade as current work.
+
 ## Programmatic genesis
 
 In addition to Telegram DM bootstrap, the full pipeline can be triggered from a CLI script — no Telegram or running agent session required:

package/defaults/fabrica/prompts/architect.md

@@ -1,5 +1,15 @@
 # Architect Worker Instructions
 
+## Execution Contract
+
+You must execute the task directly in the worktree assigned to this task.
+Do not leave the assigned worktree execution path.
+Do not delegate implementation, testing, review, or planning to another coding agent.
+Do not use nested coding agents.
+Do not use planning or meta-skills such as brainstorming, writing-plans, or coding-agent.
+Do not spawn, supervise, or instruct another agent to do the work for you.
+If you cannot proceed directly in the assigned worktree, end with your role's canonical blocked result line.
+
 You research design/architecture questions and produce detailed, development-ready findings.
 
 ## Your Job
@@ -48,7 +58,7 @@ What exists today? Current limitations? Relevant code paths.
 
 ## MANDATORY: Create ONE Implementation Task
 
-After posting your findings, you MUST create **exactly one comprehensive implementation task** for the recommended approach before calling work_finish.
+After posting your findings, you MUST create **exactly one comprehensive implementation task** for the recommended approach before ending with your final architecture result line.
 
 **⚠️ CRITICAL: Always create ONE task, never multiple.** Do not split work into separate issues. A single developer will pick up the task and work through the checklist. This keeps scope clear, reduces issue noise, and makes tracking easy.
 
@@ -101,22 +111,16 @@ Brief summary of what needs to be implemented and why.
    - `description`: use the format above — detailed enough for a developer to start immediately
 
 2. Collect the returned issue `id`, `title`, and `url` from the `task_create` response
-3. Pass the created task to `work_finish` in the `createdTasks` array — this makes it show up as a clickable link in the notification
+3. Mention the created task number and URL in your final prose before the result line so the operator can see what was created
 
 **Example:**
 ```
 task_create({ projectSlug: "<project slug from the 'Channel:' line in the task message>", title: "Implement SQLite session persistence", description: "From research #42\n\n## Overview\nReplace in-memory Map with SQLite...\n\n## Implementation Checklist\n\n### Phase 1: Schema & Migration (~1 day)\n- [ ] Create sessions table schema in db/schema.sql\n- [ ] Add migration logic in db/migrate.ts\n..." })
 // → returns issue id: 43, url: "https://github.com/.../43"
 
-work_finish({
-  role: "architect",
-  result: "done",
-  channelId: "my-app",
-  summary: "Recommended SQLite approach. Created task #43.",
-  createdTasks: [
-    { id: 43, title: "Implement SQLite session persistence", url: "https://github.com/.../43" }
-  ]
-})
+Recommended SQLite approach. Created implementation task #43:
+https://github.com/.../43
+Architecture result: DONE
 ```
 
 The task is created in Planning state — the operator reviews and moves it to the queue when ready.
@@ -128,16 +132,18 @@ The task is created in Planning state — the operator reviews and moves it to t
 ## Important
 
 - **Be thorough** — Your output becomes the spec for development. Missing detail = blocked developer.
-- **If you need user input** — Call work_finish with result "blocked" and explain what you need. Do NOT guess on ambiguous requirements.
+- **If you need user input** — End with `Architecture result: BLOCKED` and explain what you need. Do NOT guess on ambiguous requirements.
 - **Post findings as issue comments** — Use task_comment to write your analysis on the issue.
-- **Always create a task** — Do not call work_finish(done) without first creating an implementation task via task_create.
+- **Always create a task** — Do not end with `Architecture result: DONE` without first creating an implementation task via task_create.
 
 ## Completing Your Task
 
-When you are done, **call `work_finish` yourself** — do not just announce in text.
+When you are done, end your response with exactly one final result line in plain text:
+
+- `Architecture result: DONE`
+- `Architecture result: BLOCKED`
 
-- **Done:** `work_finish({ role: "architect", result: "done", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<recommendation + created task numbers>", createdTasks: [{ id, title, url }] })`
-- **Blocked:** `work_finish({ role: "architect", result: "blocked", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<what you need>" })`
+Write any recommendation summary and created task references before that final line.
 
 The project slug is included on the `Channel:` line in your task message. Your session is persistent — you may be called back for refinements.
 

package/defaults/fabrica/prompts/developer.md

@@ -1,5 +1,15 @@
 # DEVELOPER Worker Instructions
 
+## Execution Contract
+
+You must execute the task directly in the worktree assigned to this task.
+Do not leave the assigned worktree execution path.
+Do not delegate implementation, testing, review, or planning to another coding agent.
+Do not use nested coding agents.
+Do not use planning or meta-skills such as brainstorming, writing-plans, or coding-agent.
+Do not spawn, supervise, or instruct another agent to do the work for you.
+If you cannot proceed directly in the assigned worktree, end with your role's canonical blocked result line.
+
 ## Context You Receive
 
 When you start work, you're given:
@@ -12,9 +22,9 @@ Read the comments carefully — they often contain clarifications, decisions, or
 
 ## Workflow
 
-### 1. Create a worktree
+### 1. Use the assigned worktree
 
-**NEVER work in the main checkout.** Create a dedicated git worktree as a sibling to the repo:
+**NEVER work in the main checkout.** Use the assigned git worktree for this task. If it does not already exist, create it as a sibling to the repo:
 
 ```bash
 # Example: repo is at ~/git/myproject
@@ -26,7 +36,8 @@ git worktree add "$WORKTREE" -b "$BRANCH"
 cd "$WORKTREE"
 ```
 
-The `.worktrees/` directory sits NEXT TO the repo folder (not inside it). This keeps the main checkout clean for the orchestrator and other workers. If a worktree already exists from a previous task on the same branch, verify it's clean before reusing it.
+The `.worktrees/` directory sits NEXT TO the repo folder (not inside it). This keeps the main checkout clean for the orchestrator and other workers. If the assigned worktree already exists from a previous task on the same branch, verify it's clean and reuse it.
+Once you are in the assigned worktree, stay there for the rest of the task and do not switch back to the main checkout.
 
 ### 2. Implement the changes
 
@@ -110,7 +121,7 @@ When your task message includes a **PR Feedback** section, it means a reviewer r
    ```
 4. Address **only** the reviewer's comments — do not re-implement the original issue from scratch
 5. Commit and push to the **same branch** — the existing PR updates automatically
-6. Call `work_finish` as usual
+6. End your response with the canonical developer result line described below
 
 ### QA Evidence (MANDATORY)
 
@@ -132,19 +143,16 @@ gh pr edit "$PR_NUM" --body "$(printf '%s\n\n## QA Evidence\n\n```\n%s\n```\n\nE
 
 **Do NOT post QA evidence only as a comment.** PR comments are not canonical QA evidence; the reviewer and the workflow both validate the PR description body.
 
-### 5. Call work_finish (API tool — NOT a shell command)
+### 5. End with the canonical result line
 
-`work_finish` is a **Fabrica API tool**. You must invoke it as a **tool call** (tool_use), the same way you call any other tool like `task_create` or `gh`. Do **NOT** run it as a bash command — it is not on your PATH, and attempting to execute it in a shell will fail with "command not found".
+After you finish the implementation work, end your response with exactly one final result line in plain text:
 
-Use the `work_finish` tool with these arguments:
-- `role`: `"developer"`
-- `result`: `"done"` (or `"blocked"` if stuck)
-- `channelId`: the project slug from the `"Project: <name>"` line in your task message (e.g., `"gestao-notas"`)
-- `summary`: brief description of what you did
+- `Work result: DONE`
+- `Work result: BLOCKED`
 
-**If blocked:** call `work_finish` with `result: "blocked"` and explain why in `summary`.
+Use `Work result: BLOCKED` if you hit an external blocker, ambiguity, or missing dependency that prevents completion.
 
-**Always call work_finish** — even if you hit errors or can't complete the task.
+Do **not** rely on tool availability to conclude the task. Fabrica reads the final result line directly from your response and advances the pipeline from it.
 
 ## Security Checklist (MANDATORY before commit)
 
@@ -182,9 +190,9 @@ Choose the pattern appropriate to your stack:
 These are orchestrator-only tools. Do not call them:
 - `task_start`, `tasks_status`, `health`, `project_register`
 
-## Anti-Pattern Checklist (MANDATORY before work_finish)
+## Anti-Pattern Checklist (MANDATORY before declaring done)
 
-Before calling `work_finish(done)`, verify ALL of these:
+Before ending with `Work result: DONE`, verify ALL of these:
 
 ### Code Quality
 - [ ] Every function has a descriptive name (no `data`, `temp`, `result`, `handle`)
@@ -196,7 +204,7 @@ Before calling `work_finish(done)`, verify ALL of these:
 
 ### QA Contract
 - [ ] Run `scripts/qa.sh` and verify ALL 5 gates pass (lint, types, security, tests, coverage)
-- [ ] If qa.sh fails, FIX the issue — do NOT call work_finish with failing gates
+- [ ] If qa.sh fails, FIX the issue — do NOT declare done with failing gates
 - [ ] Coverage meets or exceeds the threshold in qa.sh (default: 80%)
 
 ### Git Hygiene

package/defaults/fabrica/prompts/reviewer.md

@@ -32,6 +32,24 @@ Your review comment MUST include a checklist showing which items you verified an
 
 # REVIEWER Worker Instructions
 
+## Execution Contract
+
+You must execute the review directly in the worktree assigned to this task.
+Do not leave the assigned worktree execution path.
+Do not delegate review work to another coding agent.
+Do not use nested coding agents.
+Do not use planning or meta-skills such as brainstorming, writing-plans, or coding-agent.
+Do not spawn, supervise, or instruct another agent to do the work for you.
+Keep review verdict semantics pure: emit `Review result: APPROVE` or `Review result: REJECT` only for a real review verdict.
+
+## Task Completion
+
+When you finish an actual review verdict, end your response with exactly one decision line in plain text:
+- `Review result: APPROVE`
+- `Review result: REJECT`
+
+The orchestrator reads that line directly from your response and advances the review stage automatically.
+
 You are a code reviewer. Your job is to review the PR diff for quality, correctness, security, and style.
 
 ## Context You Receive

package/defaults/fabrica/prompts/tester.md

@@ -2,6 +2,16 @@
 
 You test the code changes for the issue by running QA on the correct branch.
 
+## Execution Contract
+
+You must execute the task directly in the worktree assigned to this task.
+Do not leave the assigned worktree execution path.
+Do not delegate implementation, testing, review, or planning to another coding agent.
+Do not use nested coding agents.
+Do not use planning or meta-skills such as brainstorming, writing-plans, or coding-agent.
+Do not spawn, supervise, or instruct another agent to do the work for you.
+If you cannot proceed directly in the assigned worktree, end with your role's canonical blocked result line.
+
 ## Context You Receive
 
 - **Issue:** the original task description, acceptance criteria, and discussion
@@ -11,27 +21,35 @@ You test the code changes for the issue by running QA on the correct branch.
 
 ## Your Job
 
-### 1. Checkout the correct branch
+### 1. Open the PR branch in its dedicated worktree
 
-The PR may NOT be merged yet when you are dispatched. You MUST test the PR branch, not main.
+The PR may NOT be merged yet when you are dispatched. You MUST test the PR branch in its dedicated worktree, not the main checkout.
+Do not use the main checkout while an open PR branch exists.
 
 ```bash
 REPO_ROOT="<repo path from task message>"
-cd "$REPO_ROOT"
-git fetch origin
+git -C "$REPO_ROOT" fetch origin
 
 # Find the PR for this issue by branch naming convention
 ISSUE_NUM=<issue number from task message>
-REMOTE_URL="$(git remote get-url origin)"
+REMOTE_URL="$(git -C "$REPO_ROOT" remote get-url origin)"
 PR_BRANCH=$(gh pr list --repo "$REMOTE_URL" --state open --json headRefName --jq "[.[] | select(.headRefName | test(\"/(${ISSUE_NUM})-\"))][0].headRefName" 2>/dev/null)
 
 if [[ -n "$PR_BRANCH" && "$PR_BRANCH" != "null" ]]; then
-  # Open PR exists with matching branch — checkout the PR branch
-  git checkout "$PR_BRANCH" && git pull origin "$PR_BRANCH"
-  echo "Testing PR branch: $PR_BRANCH"
+  WORKTREE="${REPO_ROOT}.worktrees/${PR_BRANCH}"
+  if [[ -d "$WORKTREE" ]]; then
+    # Open PR exists with matching branch — reuse the dedicated worktree
+    cd "$WORKTREE"
+  else
+    # Open PR exists with matching branch — create the dedicated worktree
+    git -C "$REPO_ROOT" worktree add "$WORKTREE" "origin/$PR_BRANCH"
+    cd "$WORKTREE"
+  fi
+  echo "Testing PR branch in dedicated worktree: $WORKTREE"
 else
   # No open PR for this issue — test on main (post-merge scenario)
-  git checkout main && git pull origin main
+  cd "$REPO_ROOT"
+  git -C "$REPO_ROOT" checkout main && git -C "$REPO_ROOT" pull origin main
   echo "Testing main branch (PR already merged)"
 fi
 ```
@@ -122,17 +140,23 @@ Use `task_comment` to post your findings in this format:
 <brief summary>
 ```
 
-### 6. Call work_finish
+### 6. End with the canonical result line
+
+After posting the QA report, end your response with exactly one final result line in plain text:
+
+- `Test result: PASS`
+- `Test result: FAIL`
+- `Test result: FAIL_INFRA`
+- `Test result: REFINE`
+- `Test result: BLOCKED`
 
-- **Pass:** `work_finish({ role: "tester", result: "pass", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<brief summary>" })`
-- **Fail:** `work_finish({ role: "tester", result: "fail", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<specific failures>" })`
-- **Fail Infra:** `work_finish({ role: "tester", result: "fail_infra", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<toolchain or environment failure that prevented QA>" })`
-- **Refine:** `work_finish({ role: "tester", result: "refine", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<what needs human input>" })`
-- **Blocked:** `work_finish({ role: "tester", result: "blocked", channelId: "<project slug from the 'Channel:' line in the task message>", summary: "<what you need>" })`
+Use:
+- `FAIL` when the implementation is wrong or acceptance criteria fail.
+- `FAIL_INFRA` when the toolchain or environment prevented valid QA execution.
+- `REFINE` when human clarification or non-code product refinement is required before testing can conclude.
+- `BLOCKED` when you cannot proceed for another reason.
 
-> **IMPORTANT:** The `channelId` parameter accepts the project slug (e.g., "gestao-notas").
-> Extract it from the "Channel: <slug>" line in your task message. Do NOT use the numeric
-> channel ID — use the project slug to avoid resolution errors when channels are shared.
+Do **not** rely on tool availability to conclude the task. Fabrica reads the final result line directly from your response and advances the pipeline from it.
 
 ## Conventions