@mestreyoda/fabrica 0.2.22 → 0.2.23

package/ARCHITECTURE.md

@@ -0,0 +1,137 @@
+# Architecture
+
+## Core shape
+
+Fabrica is implemented as a local OpenClaw plugin with the local repository as
+its source of truth.
+
+Main areas:
+
+- `lib/intake`
+  Intake, target resolution, impact analysis, task creation and triage.
+- `lib/github`
+  GitHub App auth, webhook ingestion, event store, PR binding, quality gate and
+  governance.
+- `lib/services`
+  Pipeline, heartbeat, queue scans and workflow execution helpers.
+- `lib/machines`
+  `FabricaRunMachine` and `LifecycleMachine` for explicit state transitions.
+- `lib/observability`
+  Pino logging, correlation context and OpenTelemetry spans.
+- `lib/dispatch`
+  DM bootstrap, Telegram topic routing, worker notifications and attachment hooks.
+- `lib/telegram`
+  Telegram config resolution and topic creation services.
+- `defaults`
+  Packaged assets and workflow defaults that ship with the plugin.
+- `genesis`
+  Packaged runtime assets still used by the plugin during the migration away
+  from older shell-driven flows.
+
+## Runtime model
+
+Large/xlarge work can be represented as a parent coordination issue plus child
+execution issues.
+
+Canonical runtime fields live in `project.issueRuntime[issueId]`:
+
+- `parentIssueId`
+- `childIssueIds`
+- `dependencyIssueIds`
+- `decompositionMode`
+- `decompositionStatus`
+- `completedChildIssueIds`
+- `blockedChildIssueIds`
+- `maxParallelChildren`
+
+Operational rules:
+
+- parent issues are coordinator-only and do not enter normal developer execution
+- child issues can enter the normal queue with their own level labels and PR flow
+- dependency-linked children stay blocked until predecessor execution is complete
+- sibling execution is capped by `maxParallelChildren`
+- parent rollups are refreshed from child runtime and can auto-close when the
+  family is complete
+
+## Environment gate
+
+`lib/test-env` provisions the shared toolchain and the project environment
+before dispatching workers in `developer` or `tester` mode.
+
+State model:
+
+`pending -> provisioning -> ready | failed`
+
+Environment contracts are versioned per family using `{family}@v1`
+(for example `python@v1` and `node@v1`).
+
+Operational rules:
+
+- Python uses a shared toolchain in `~/.openclaw/toolchains/python`
+- Python project environments are materialized locally as `.venv`
+- Existing Node repos require a reproducible lockfile before real work starts
+- Failure backoff is 60 seconds
+- A provisioning state older than 10 minutes is treated as stale and retried
+- `dryRun: true` skips environment provisioning entirely and stays side-effect free
+
+## Telegram routing model
+
+New project intake is DM-first. The Fabrica bot accepts a new-project request in
+Telegram DM, asks for missing essentials there if needed, and only creates the
+project topic when the intake is ready to register. For greenfield projects,
+repo provisioning now happens in the TS intake path before registration and
+issue creation.
+
+The canonic route identity for Telegram-backed projects is:
+
+`channel=telegram + channelId + messageThreadId`
+
+This avoids collisions between multiple projects inside the same Telegram forum
+group. After registration:
+
+- the project topic becomes the primary route for project messages
+- follow-ups inside that topic resolve the exact project
+- worker notifications and project lifecycle updates publish back to that topic
+- ops alerts stay in the separate ops group
+
+The hot path for GitHub is:
+
+`webhook -> event store -> FabricaRun -> Quality Gate -> artifactOfRecord -> done`
+
+Important invariants:
+
+- a cycle never closes with an open canonical PR
+- `Done` requires `artifactOfRecord`
+- duplicate GitHub deliveries must not duplicate effects
+- force-push updates the canonical binding instead of spawning duplicate runs
+
+## Installation model
+
+Fabrica is distributed as a self-contained OpenClaw plugin package.
+
+The supported operator path is:
+
+```bash
+openclaw plugins install @mestreyoda/fabrica
+```
+
+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.
+
+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
+
+- Gateway runtime is managed by the OpenClaw systemd service.
+- GitHub webhook ingress is protected by GitHub signature validation inside the
+  plugin; the route itself must remain reachable without gateway bearer auth.
+- GitHub App and webhook credentials are expected to come from the Fabrica
+  plugin config (`openclaw.json`) using direct values and credential file paths;
+  legacy env-based fields remain only as compatibility fallback.
+- Structured logs and OpenTelemetry spans are emitted by the plugin itself.
+- Security validation lives in `openclaw fabrica doctor security --json`.

package/README.md

@@ -43,6 +43,7 @@ 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
+- **Parent/child large-work orchestration** — large initiatives can become one coordinator issue plus execution-ready child issues with dependency-aware scheduling and automatic parent rollups
 - **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

package/defaults/fabrica/prompts/developer.md

@@ -29,18 +29,18 @@ Read the comments carefully — they often contain clarifications, decisions, or
 ```bash
 # Example: task message says Repo: /home/ubuntu/git/acme/myproject
 REPO_ROOT="/absolute/path/from-task-message"
-cd "$REPO_ROOT"
 BRANCH="feature/<issue-id>-<slug>"
 WORKTREE="${REPO_ROOT}.worktrees/${BRANCH}"
-if git worktree list --porcelain | grep -Fq "worktree ${WORKTREE}"; then
+mkdir -p "$(dirname "$WORKTREE")"
+if git -C "$REPO_ROOT" worktree list --porcelain | grep -Fq "worktree ${WORKTREE}"; then
   cd "$WORKTREE"
 else
-  git worktree add "$WORKTREE" -b "$BRANCH"
+  git -C "$REPO_ROOT" worktree add "$WORKTREE" -b "$BRANCH"
   cd "$WORKTREE"
 fi
 ```
 
-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.
+The `.worktrees/` directory sits NEXT TO the repo folder (not inside it). This keeps the main checkout clean for the orchestrator and other workers. Never improvise with `./.worktrees`, `${REPO_ROOT}/.worktrees`, or any other in-repo worktree path. If the assigned worktree already exists from a previous task on the same branch, verify it's clean and reuse it.
 
 Never create or implement the project under `~/.openclaw/workspace/<slug>` unless the task message explicitly says that directory is the canonical repo path. If the repo already contains scaffolded files, do not re-initialize the project with `npm init`, `uv init`, `cargo init`, or a second skeleton generator — keep the existing stack and modify the scaffold inside the assigned worktree. Once you are in the assigned worktree, stay there for the rest of the task and do not switch back to the main checkout.
 
@@ -51,6 +51,15 @@ Never create or implement the project under `~/.openclaw/workspace/<slug>` unles
 - Follow existing code patterns and conventions in the project
 - Run tests/linting if the project has them configured
 
+### Technical Quality Bar
+
+- Prefer the most idiomatic, well-supported solution for the project's stack instead of inventing custom infrastructure.
+- Match the project archetype: API projects need strong boundary validation and error handling; CLI projects need excellent help/exit-code UX; UI projects need clear loading/error states.
+- Choose mature libraries/functions that simplify the codebase and improve reliability. Do not add a dependency when the standard stack already solves the problem cleanly.
+- Keep the implementation simple and cohesive. Avoid overengineering, speculative abstractions, and generic frameworks for a narrow problem.
+- Optimize for maintainability first, then performance where the task actually needs it. Remove obvious inefficiencies in hot paths, repeated I/O, wasteful queries, and duplicated work.
+- If the request is security-sensitive (auth, permissions, secrets, payments, personal data), treat correctness and safe defaults as mandatory, not optional polish.
+
 ### Structure & Hygiene
 
 - **No monolith files.** If a single file exceeds ~200 lines or mixes concerns (routes, business logic, templates), split into focused modules.
@@ -82,7 +91,8 @@ Conventional commits: `feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`
 - **NEVER** include host-system paths outside the repository (e.g., `/home/*/`, `~/.openclaw/`)
 - **NEVER** include raw output of commands not explicitly listed in this template
 
-Use `gh pr create` with the template below. Do NOT deviate from this format:
+Use `gh pr create` with the template below. Do NOT deviate from this format.
+Create the PR with the base body only first — do NOT try to embed multiline `## QA Evidence`, code fences, or raw `scripts/qa.sh` output directly inside the `gh pr create --body "..."` command. That content must be added only by the separate QA Evidence PATCH workflow below.
 
 ```bash
 gh pr create --base "$BASE_BRANCH" \
@@ -106,6 +116,7 @@ Addresses issue #<issue-id>.
 **Do NOT use closing keywords** in the description (no "Closes #X", "Fixes #X"). Use "Addresses issue #X" instead — Fabrica manages issue lifecycle.
 
 **Do NOT invent ad-hoc sections** beyond Summary, Changes, and Security Checklist. The only additional section allowed in the PR body is the canonical `## QA Evidence` section updated in place by the QA workflow below.
+**Never place `## QA Evidence` directly in the initial `gh pr create --body` text.** Create the PR first, then update that section via the dedicated PATCH flow below.
 
 ### Handling PR Feedback (changes requested / To Improve)
 
@@ -130,10 +141,15 @@ When your task message includes a **PR Feedback** section, it means a reviewer r
 
 ### QA Evidence (MANDATORY)
 
-After implementing (or after addressing reviewer feedback), run `scripts/qa.sh` in the worktree. The QA script is expected to bootstrap project-local test dependencies when needed; do not rely on a shared host-level venv or globally preinstalled project packages. Then **replace the PR description body's existing `## QA Evidence` section** with fresh sanitized output (never append a second section):
+After implementing (or after addressing reviewer feedback), run `scripts/qa.sh` in the worktree. The QA script is expected to bootstrap project-local test dependencies when needed; do not rely on a shared host-level venv or globally preinstalled project packages. Then **replace the PR description body's existing `## QA Evidence` section** with fresh sanitized output (never append a second section).
+Do this as a second step after PR creation — not inline in `gh pr create` — because multiline QA output, code fences, and shell quoting frequently corrupt the initial PR creation command:
+
+**Do NOT weaken, replace, or bypass the canonical `scripts/qa.sh` contract just to make the task pass.** Preserve the five canonical gates (`lint`, `types`, `security`, `tests`, `coverage`) and fix the product code or project setup instead. Ad-hoc scenario scripts, one-off smoke tests, or custom gate names do not satisfy Fabrica's QA Evidence validator.
 
 ```bash
 # Get current PR body, replace QA Evidence, update
+# IMPORTANT: keep this as a separate PATCH step after `gh pr create` succeeds.
+# Never paste multiline QA output directly into the `gh pr create --body` command.
 PR_NUM=$(gh pr list --head "$BRANCH" --json number -q '.[0].number')
 QA_RAW=$(bash scripts/qa.sh 2>&1); QA_EXIT=$?
 # MANDATORY: sanitize before embedding in PR — strip lines with tokens/keys/env vars/host paths

package/defaults/fabrica/prompts/reviewer.md

@@ -91,8 +91,23 @@ Do **not** treat the task envelope (`Repo:`, `Project:`, `Channel:`, branch hint
 
 - Read the PR diff carefully
 - Check the code against the review checklist
+- Reject work that solves the wrong problem, uses an obviously poor approach for the stack, or adds unnecessary complexity
 - Output your decision in the format described in **Completing Your Task** below
 
+## Technical Review Bar
+
+Your job is not to ask whether the code merely works. Your job is to decide whether it is good enough to represent Fabrica-quality delivery.
+
+Reject when you find any of these:
+- a solution that technically works but does not faithfully match the issue's requested behavior or constraints
+- a weak stack fit (wrong library choice, brittle custom infrastructure, or avoiding a mature standard tool without reason)
+- unnecessary complexity, speculative abstraction, or architecture inflation for a narrow task
+- poor maintainability (unclear module boundaries, duplicated logic, confusing names, or hidden side effects)
+- avoidable performance mistakes in likely hot paths or repeated I/O/query work
+- security-sensitive code treated as optional polish instead of a correctness requirement
+
+When you approve, it means you checked fidelity, technical approach, maintainability, and risk — not only style.
+
 ## Conventions
 
 - **Do NOT use closing keywords in PR/MR descriptions** (no "Closes #X", "Fixes #X", "Resolves #X"). Use "As described in issue #X" or "Addresses issue #X". Fabrica manages issue state — auto-closing bypasses the review lifecycle.

package/defaults/fabrica/prompts/tester.md

@@ -75,6 +75,15 @@ For each AC in the issue:
 - If an AC is ambiguous, note what you checked and mark CONDITIONAL
 - **Every single AC must be verified** — do not skip any
 
+### Quality & Evidence Bar
+
+- Your job is to produce evidence proportional to the project archetype, not a superficial green check.
+- For API work, verify request/response behavior, validation, and key failure paths.
+- For CLI work, verify help output, exit codes, invalid-argument handling, and the main happy path.
+- For UI work, verify the main flow plus loading/error behavior when applicable.
+- For security-sensitive work (auth, permissions, secrets, payments, personal data), treat missing negative tests or weak evidence as a real failure, not a nit.
+- If the implementation technically runs but the evidence is too weak to trust the result, prefer `Test result: FAIL` or `Test result: REFINE` over a false PASS.
+
 ### 4. Check for regressions
 
 - Run the full test suite if available