@mestreyoda/fabrica 0.2.7 → 0.2.11

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 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.

package/README.md

@@ -80,24 +80,22 @@ openclaw fabrica doctor
 
 ## Quick start
 
-**1. Configure the plugin** in `~/.openclaw/openclaw.json`:
+**1. Enable the plugin** in `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "plugins": {
     "entries": {
       "fabrica": {
-        "config": {
-          "github": {
-            "org": "<YOUR_GITHUB_ORG_OR_USER>"
-          }
-        }
+        "enabled": true
       }
     }
   }
 }
 ```
 
+For polling-first GitHub usage via authenticated `gh`, no extra plugin config is required. Fabrica's plugin config is only for control-plane settings such as heartbeat cadence, Telegram routing, notifications, and provider/webhook auth. Worker models, levels, and workflow routing live in the workspace files and can be generated or updated with `openclaw fabrica setup`.
+
 **2. Restart the gateway**:
 
 ```bash
@@ -132,7 +130,7 @@ openclaw fabrica metrics
 
 ### Minimal (gh CLI only)
 
-This configuration uses `gh` CLI for all GitHub operations (no GitHub App needed):
+This mode uses authenticated `gh` CLI for all GitHub operations. Worker models, levels, and workflow routing live in the project workflow files, not in `openclaw.json`.
 
 ```json
 {
@@ -140,13 +138,49 @@ This configuration uses `gh` CLI for all GitHub operations (no GitHub App needed
     "entries": {
       "fabrica": {
         "config": {
-          "github": {
-            "org": "<YOUR_GITHUB_ORG_OR_USER>"
+          "work_heartbeat": {
+            "enabled": true,
+            "intervalSeconds": 60,
+            "maxPickupsPerTick": 4
           },
-          "workers": {
-            "developer": { "model": "gpt-4o", "level": "medior" },
-            "reviewer":  { "model": "gpt-4o", "level": "senior" },
-            "tester":    { "model": "gpt-4o", "level": "medior" }
+          "projectExecution": "parallel",
+          "notifications": {
+            "workerStart": true,
+            "workerComplete": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Optional GitHub App/webhook settings also live under `plugins.entries.fabrica.config.providers.github`.
+
+### With GitHub App / webhook config
+
+Use plugin config when you want explicit webhook behavior or provider auth profiles:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "fabrica": {
+        "config": {
+          "providers": {
+            "github": {
+              "defaultAuthProfile": "app",
+              "webhookMode": "optional",
+              "webhookPath": "/plugins/fabrica/github/webhook",
+              "webhookSecretEnv": "FABRICA_GITHUB_WEBHOOK_SECRET",
+              "authProfiles": {
+                "app": {
+                  "mode": "github-app",
+                  "appIdEnv": "FABRICA_GITHUB_APP_ID",
+                  "privateKeyPathEnv": "FABRICA_GITHUB_APP_KEY_PATH"
+                }
+              }
+            }
           }
         }
       }
@@ -157,7 +191,7 @@ This configuration uses `gh` CLI for all GitHub operations (no GitHub App needed
 
 ### With Telegram
 
-Telegram enables DM-based project bootstrap and per-project forum topic notifications.
+Telegram enables DM-based project bootstrap, per-project forum topics, and a separate ops chat for heartbeat and cron notifications.
 
 ```json
 {
@@ -177,6 +211,7 @@ Telegram enables DM-based project bootstrap and per-project forum topic notifica
           "telegram": {
             "bootstrapDmEnabled": true,
             "projectsForumChatId": "<YOUR_PROJECTS_FORUM_CHAT_ID>",
+            "projectsForumAccountId": "<OPTIONAL_TELEGRAM_ACCOUNT_ID>",
             "opsChatId": "<YOUR_OPS_CHAT_ID>"
           }
         }
@@ -186,7 +221,7 @@ Telegram enables DM-based project bootstrap and per-project forum topic notifica
 }
 ```
 
-With Telegram enabled, send a project idea to the bot in a DM. Fabrica will ask clarifying questions, provision the GitHub repo, and create a dedicated forum topic for the project. All subsequent worker updates, review results, and the final merge notification appear in that topic.
+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.
 
 ## Programmatic genesis
 
@@ -227,6 +262,8 @@ Run tests:
 
 ```bash
 npm test
+npm run test:all
+npm run test:hot-path
 ```
 
 Build:

package/defaults/fabrica/prompts/architect.md

@@ -96,7 +96,7 @@ Brief summary of what needs to be implemented and why.
 ### How to Create
 
 1. Call `task_create` with:
-   - `projectSlug`: same as your task message
+   - `projectSlug`: the value from the `Channel:` line in your task message (`task_create` still expects this field name)
    - `title`: clear, actionable title (e.g. "Implement SQLite session persistence")
    - `description`: use the format above — detailed enough for a developer to start immediately
 
@@ -105,13 +105,13 @@ Brief summary of what needs to be implemented and why.
 
 **Example:**
 ```
-task_create({ projectSlug: "my-app", 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..." })
+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",
-  projectSlug: "my-app",
+  channelId: "my-app",
   summary: "Recommended SQLite approach. Created task #43.",
   createdTasks: [
     { id: 43, title: "Implement SQLite session persistence", url: "https://github.com/.../43" }
@@ -136,10 +136,10 @@ The task is created in Planning state — the operator reviews and moves it to t
 
 When you are done, **call `work_finish` yourself** — do not just announce in text.
 
-- **Done:** `work_finish({ role: "architect", result: "done", projectSlug: "<from task message>", summary: "<recommendation + created task numbers>", createdTasks: [{ id, title, url }] })`
-- **Blocked:** `work_finish({ role: "architect", result: "blocked", projectSlug: "<from task message>", summary: "<what you need>" })`
+- **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>" })`
 
-The `projectSlug` is included in your task message. Your session is persistent — you may be called back for refinements.
+The project slug is included on the `Channel:` line in your task message. Your session is persistent — you may be called back for refinements.
 
 ## Tools You Should NOT Use
 

package/defaults/fabrica/prompts/reviewer.md

@@ -73,7 +73,7 @@ Do **not** treat the task envelope (`Repo:`, `Project:`, `Channel:`, branch hint
 
 - Read the PR diff carefully
 - Check the code against the review checklist
-- Submit your review using **one of the two methods below** (prefer `review_submit` if available)
+- Output your decision in the format described in **Completing Your Task** below
 
 ## Conventions
 
@@ -85,55 +85,37 @@ Do **not** treat the task envelope (`Repo:`, `Project:`, `Channel:`, branch hint
 
 ## Filing Follow-Up Issues
 
-If you discover unrelated bugs or needed improvements, call `task_create`:
+If you discover unrelated bugs or needed improvements, call `task_create` with the project slug from the `Channel:` line in your task message:
 
-`task_create({ projectSlug: "<from task message>", title: "Bug: ...", description: "..." })`
+`task_create({ projectSlug: "<project slug from the 'Channel:' line in the task message>", title: "Bug: ...", description: "..." })`
 
 ## Completing Your Task
 
-When you are done, submit your review using **Method A** if the tools are available, or **Method B** otherwise.
+After writing your review, you **MUST** output your final decision on a dedicated line in **exactly** one of these two formats:
 
-### Method A — Fabrica tools (preferred)
+```
+Review result: APPROVE
+```
+```
+Review result: REJECT
+```
 
-1. Call `review_submit` to write the review artifact to the PR:
-   - **Approve:** `review_submit({ channelId: "<project slug>", issueId: <issue number>, result: "approve", body: "<what you checked>" })`
-   - **Reject:** `review_submit({ channelId: "<project slug>", issueId: <issue number>, result: "reject", body: "<specific issues>" })`
-   - Capture the returned `artifactId` and `artifactType`.
-2. Then call `work_finish`:
-   - **Approve:** `work_finish({ role: "reviewer", result: "approve", channelId: "<project slug>", summary: "<what you checked>", reviewArtifactId: <artifactId>, reviewArtifactType: "<artifactType>" })`
-   - **Reject:** `work_finish({ role: "reviewer", result: "reject", channelId: "<project slug>", summary: "<specific issues>", reviewArtifactId: <artifactId>, reviewArtifactType: "<artifactType>" })`
-   - **Blocked:** `work_finish({ role: "reviewer", result: "blocked", channelId: "<project slug>", summary: "<what you need>" })`
+The Fabrica orchestrator reads your session output and advances the pipeline automatically based on this line. **You do not need to call any tool or run any CLI command.** Just output the line above and your work is done.
 
-> **IMPORTANT:** The `channelId` parameter accepts the project slug (e.g., "gestao-notas").
-> Extract it from the "Project: <name>" line in your task message. Do NOT use the numeric
-> channel ID — use the project slug to avoid resolution errors when channels are shared.
+- Output `Review result: APPROVE` if all quality gates pass and the code is ready to proceed.
+- Output `Review result: REJECT` if any blocking issue was found that the developer must fix.
 
-### Method B — GitHub CLI fallback (use only if `review_submit` / `work_finish` are unavailable)
+> **IMPORTANT:** The decision line must appear in your response text, not inside a code block. It is case-insensitive but must follow the `Review result: APPROVE/REJECT` format exactly.
 
-Extract from your task message:
-- `OWNER/REPO` from the `Repo:` line
-- `PR_NUMBER` from the PR URL in the diff header or the `Branch:` line
-- `ISSUE_NUMBER` from the `Issue:` field
+### Optional: submit PR comment (best-effort)
 
-**Approve:**
-```bash
-gh pr review PR_NUMBER --repo OWNER/REPO --approve -b "$(cat <<'EOF'
-<your full review body here>
-EOF
-)"
-```
+If `gh` is available and the PR author is not the same GitHub account you are logged in as, you may optionally leave a PR comment for visibility:
 
-**Reject (request changes):**
-```bash
-gh pr review PR_NUMBER --repo OWNER/REPO --request-changes -b "$(cat <<'EOF'
-<specific issues and how to fix them>
-EOF
-)"
+```
+gh pr comment <PR_NUMBER> --repo <OWNER/REPO> --body "<summary of your findings>"
 ```
 
-After submitting via `gh pr review`, the Fabrica heartbeat will detect the PR review state and advance the pipeline automatically. **Do NOT manually edit issue labels.**
-
-**Never call `task_comment` for review findings.** Your review must be posted on the PR itself.
+This is informational only — the orchestrator does not require it to advance the pipeline.
 
 ## Tools You Should NOT Use
 

package/defaults/fabrica/prompts/tester.md

@@ -124,13 +124,14 @@ Use `task_comment` to post your findings in this format:
 
 ### 6. Call work_finish
 
-- **Pass:** `work_finish({ role: "tester", result: "pass", channelId: "<project slug from 'Project:' field in task message>", summary: "<brief summary>" })`
-- **Fail:** `work_finish({ role: "tester", result: "fail", channelId: "<project slug from 'Project:' field in task message>", summary: "<specific failures>" })`
-- **Refine:** `work_finish({ role: "tester", result: "refine", channelId: "<project slug from 'Project:' field in task message>", summary: "<what needs human input>" })`
-- **Blocked:** `work_finish({ role: "tester", result: "blocked", channelId: "<project slug from 'Project:' field in task message>", summary: "<what you need>" })`
+- **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>" })`
 
 > **IMPORTANT:** The `channelId` parameter accepts the project slug (e.g., "gestao-notas").
-> Extract it from the "Project: <name>" line in your task message. Do NOT use the numeric
+> 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.
 
 ## Conventions
@@ -140,9 +141,9 @@ Use `task_comment` to post your findings in this format:
 
 ## Filing Follow-Up Issues
 
-If you discover unrelated bugs or needed improvements during your work, call `task_create`:
+If you discover unrelated bugs or needed improvements during your work, call `task_create` with the project slug from the `Channel:` line in your task message:
 
-`task_create({ projectSlug: "<from task message>", title: "Bug: ...", description: "..." })`
+`task_create({ projectSlug: "<project slug from the 'Channel:' line in the task message>", title: "Bug: ...", description: "..." })`
 
 ## Tools You Should NOT Use