@mestreyoda/fabrica 0.2.14 → 0.2.16

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
@@ -92,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
@@ -100,30 +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.
 
-**4. Restart the gateway**:
+**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 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`.
+
+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
@@ -135,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
@@ -212,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
 {
@@ -232,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>"
           }
         }
       }
@@ -242,7 +298,20 @@ 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
+operational recovery events, with cycle-aware dedupe so late deliveries from an
+older dispatch do not masquerade as current work.
 
 ## Programmatic genesis
 

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