FarmHouse-Holdings/PRD_ADDENDUM.md

# PRD Addendum — Improvements and Reality Checks

**Companion to:** FarmHouse_Holdings_Product_Requirements.md v1.0
**Purpose:** Corrections, constraints, and additions based on the actual deployed environment (4-instance Ollama pool running qwen3.5:9b behind an API redirect, Hermes orchestration already set up, GitHub org created but empty).

---

## 1. Environment corrections to PRD Section 3

The PRD assumes Hermes 3 as the employee reasoning engine. Actual workforce is **qwen3.5:9b across 4 pooled Ollama instances**. This changes several design assumptions:

| PRD assumption | Reality | Consequence |
|---|---|---|
| "Hermes 3 or similar" reasoning engine | qwen3.5:9b (9B params) | Weaker multi-step reasoning; tasks must be decomposed smaller than PRD implies |
| Scheduler balances many workers | Hard cap: **4 concurrent inferences**, period | Scheduler v1 is a simple priority queue with 4 slots, not a complex placement engine |
| Long employee context/memory | ~11 GB VRAM per instance limits usable context (likely 8k–32k tokens depending on quant + KV cache) | Memory layers (PRD §15) must compress aggressively; no "dump the whole knowledge base" prompts |
| Employees run long agent loops | Small models drift, loop, and hallucinate tool calls over long horizons | Every task needs max-iteration caps, token budgets, and repetition detection (see §3 below) |

**Action:** run the capability gate in `PRE_IMPLEMENTATION_CHECKLIST.md` before building any org-model code. If qwen3.5:9b can't reliably emit valid structured messages or working code diffs, the whole employee model needs rethinking (bigger model, tighter task shapes, or heavier consultant reliance).

## 2. Strengthen PRD §13.4 — structured output must be *enforced*, not requested

The PRD says "do not rely on parsing free-form chat." Go further:

- Use Ollama's `format` parameter (JSON schema enforcement) for **every** agent→engine message. The model physically cannot emit non-conforming output.
- Keep schemas small and flat. 9B models degrade on deeply nested schemas.
- Validate server-side anyway; on failure, retry once with the error appended, then mark task blocked. Never silently accept malformed output.
- Version schemas from day one (`schema_version` field), as the PRD already requires for events.

## 3. New requirement — runaway protection for small models

Add to PRD §7.4 (anti-busy-work). Small local models fail differently than frontier models:

- **Per-task hard caps:** max agent-loop iterations (suggest 15), max total tokens, max wall-clock time. Exceeding any cap = task blocked with state preserved, escalate to manager.
- **Repetition detector:** if the model emits near-identical output N times in a row, kill the loop. Cheap check (hash last 3 responses), catches the most common 9B failure mode.
- **Self-assessment distrust:** the PRD already says completion requires evidence, not claims (§9.1). For a 9B model this is load-bearing — deterministic gates (tests pass, lint passes, diff applies) are the *only* completion signal. Never let the model's "done" flag advance state.

## 4. Role-based model routing (extends PRD §13)

One model for everything is wrong even locally. Route by role through the model gateway (LiteLLM, as PRD suggests):

- **Default workforce:** qwen3.5:9b — implementation tasks, summaries, test writing.
- **Coder-tuned variant** (e.g. qwen coder family, fits same VRAM): engineering employees. Worth benchmarking both in the capability gate.
- **Consultants:** Claude/OpenAI via LiteLLM with the PRD §10 budget controls. Practical trigger: any task blocked twice by the runaway caps in §3 auto-generates a consultant *proposal* (not an auto-call).
- Keep model aliases per *role*, not per employee, so swapping models later is one config change (PRD §23.3 preserved).

## 5. Tool gateway — standardize on MCP

PRD §14.1 lists a "tool gateway and isolated execution workers" without a protocol. Recommend **MCP (Model Context Protocol)** for tool exposure:

- Tools (git, shell, Playwright, file ops) become MCP servers; any agent runtime (Hermes Agent, custom loop, future frameworks) consumes them uniformly.
- Permission enforcement lives in the gateway between agent and MCP server — deterministic, outside the LLM, exactly as PRD §8 requires.
- Avoids coupling the platform to Hermes Agent's tool format (PRD §3: "do not hard-code to one agent framework").

## 6. MVP scope trim (amends PRD §20)

The PRD's MVP is ~6 months of work. Prove the risky core first with a smaller slice:

**Slice 1 (prove the engine):** one company, three employees (manager, engineer, QA), Postgres + Redis, structured agent protocol, git worktree isolation, one Playwright test run, evidence bundle, web dashboard read-only view, global pause. **No Discord, no 2D office, no consultants, no schedules.**

**Slice 2:** clarification/approval workflow + Discord channel + consultant path.

**Slice 3:** 2D office + schedules + autonomous work modes.

Rationale: PRD §24 itself says prove the company engine before visualization. Discord and the office are synchronized *views* (PRD §23.5) — they can't be validated until the engine emits real events anyway.

## 7. Observability — concrete picks (fills in PRD §17)

- **Langfuse (self-hosted)** for LLM traces: every prompt, response, latency, token count per employee/task. Purpose-built for exactly PRD §17's model metrics, runs in Docker next to Postgres.
- Engine events table in Postgres doubles as the audit log for v1 — no separate observability stack until it hurts.
- GPU metrics: `nvidia-smi` scrape into the same Postgres, chart later. Skip Prometheus/Grafana until multi-node pain is real.

## 8. Additional gaps worth one line each

- **Backpressure:** 4 slots means queue depth will grow. Dashboard must show queue depth per company from day one or "idle employees" will be a mystery.
- **Warm-model pinning:** with 4 instances and 1–2 models, pin models resident (Ollama `keep_alive=-1`) — cold starts on a 1080 Ti will dominate latency otherwise. PRD §13.3 allows this.
- **Time zone:** PRD sets `America/Indiana/Indianapolis` — store all timestamps UTC, convert at display. State it explicitly in the event schema ADR.
- **Company templates:** the new-company wizard (PRD §18.3) should stamp from a GitHub template repo (see GITHUB_INTEGRATION.md) — cheap and gives every company identical scaffolding.
- **Kill switch semantics:** define now whether "pause" drains in-flight inference or aborts it. Recommend: drain inference (seconds), abort tool executions (side effects). Ambiguity here bites during the first incident.