@mestreyoda/fabrica 0.2.9 → 0.2.12

package/ARCHITECTURE.md

@@ -63,17 +63,23 @@ Important invariants:
 
 ## Installation model
 
-The supported local installation is path-based:
+Fabrica is distributed as a self-contained OpenClaw plugin package.
+
+The supported operator path is:
 
 ```bash
-openclaw plugins install -l /path/to/fabrica
+openclaw plugins install @mestreyoda/fabrica
 ```
 
-That means:
+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.
 
-- the repository stays editable in place
-- the installed plugin points back to this directory
-- the loaded runtime should match the local build output in `dist/`
+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
 

package/CHANGELOG.md

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

package/README.md

@@ -64,6 +64,9 @@ The heartbeat ticks every 60 seconds. On each tick, Fabrica alternates between a
 openclaw plugins install @mestreyoda/fabrica
 ```
 
+That install should be enough for OpenClaw to load Fabrica immediately, without
+manual remediation.
+
 ### Via GitHub clone
 
 ```bash
@@ -74,37 +77,53 @@ openclaw plugins install -l ~/fabrica
 After installation, verify the plugin loaded correctly:
 
 ```bash
-openclaw plugins list
-openclaw fabrica doctor
+openclaw plugins inspect fabrica
 ```
 
+## Loadability vs operational readiness
+
+- **Loadable:** the plugin installs and OpenClaw can load it immediately.
+- **Operational:** Fabrica has the GitHub, Telegram, and optional webhook
+  configuration needed for your workflow.
+
+`openclaw plugins inspect fabrica` is the loadability check after install.
+`openclaw fabrica doctor` runs once the plugin is loaded and checks the
+operational/workspace state, then tells you what is still missing.
+
 ## Quick start
 
-**1. Configure the plugin** in `~/.openclaw/openclaw.json`:
+**1. Install Fabrica**:
 
-```json
-{
-  "plugins": {
-    "entries": {
-      "fabrica": {
-        "config": {
-          "github": {
-            "org": "<YOUR_GITHUB_ORG_OR_USER>"
-          }
-        }
-      }
-    }
-  }
-}
+```bash
+openclaw plugins install @mestreyoda/fabrica
+```
+
+The plugin should load immediately after install, without manual remediation.
+
+**2. Confirm loadability**:
+
+```bash
+openclaw plugins inspect fabrica
+```
+
+**3. Configure operational state for a workspace**:
+
+```bash
+openclaw fabrica doctor workspace --workspace /path/to/workspace
+openclaw fabrica setup --workspace /path/to/workspace --new-agent fabrica
 ```
 
-**2. Restart the gateway**:
+Use `openclaw fabrica setup --agent <id>` if you already have an agent. GitHub,
+Telegram, and webhook behavior are separate operational concerns, not
+installation dependencies.
+
+**4. Restart the gateway**:
 
 ```bash
 systemctl --user restart openclaw-gateway.service
 ```
 
-**3. Trigger a new project programmatically**:
+**5. Trigger a new project programmatically**:
 
 ```bash
 cd ~/fabrica  # GitHub clone install only
@@ -116,13 +135,13 @@ npx tsx scripts/genesis-trigger.ts "A CLI tool that counts words in a file" \
 
 Remove `--dry-run` to execute for real.
 
-**4. Watch the pipeline run**:
+**6. Watch the pipeline run**:
 
 ```bash
 tail -f ~/.openclaw/workspace/logs/genesis.log
 ```
 
-**5. Check metrics**:
+**7. Check metrics**:
 
 ```bash
 openclaw fabrica metrics
@@ -132,7 +151,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 +159,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 +212,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 +232,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 +242,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 +283,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,9 +85,9 @@ 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
 

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