@mestreyoda/fabrica 0.2.14 → 0.2.15

package/CHANGELOG.md

@@ -1,11 +1,23 @@
 # Changelog
 
-## 0.2.14 - 2026-04-01
-
-- Made `agent_end` authoritative for reviewer completion as well, so reviewer sessions no longer depend on delayed `subagent_ended` or reviewer polling to advance the FSM.
-- Added session-history fallback for developer/tester/architect lifecycle completion when `agent_end` arrives without the final assistant result line.
-- Hardened Telegram bootstrap ownership so stale attempts stop before stamping `project_registered` data or replaying kickoff, `projectTick`, or completion DM side effects onto a newer attempt.
-- Added regression coverage for reviewer `agent_end` routing, worker lifecycle session-history fallback, and successful bootstrap owner-loss races.
+## 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
 

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

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
 

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
 ```