Hard-Facts Corpus

Read MISSION_CONTROL.md first, then check lessons, post heartbeat, review peers, pick up own tasks — in that sequence, no exceptions. Skipping a phase (e.g., jumping to own tasks before peer review) leaves work blocked and other agents unaware of state.

When informed that a fleet agent is assigned to or actively working on something, stop pursuing it. Confirm the handoff, then do only what is explicitly asked (e.g., update standup, check uncommitted changes). Do not continue the original task.

Posting a comment or feedback record alone does NOT change task status. Always follow every peer review rejection with a PATCH to the task record setting status=todo. Omitting this leaves tasks stuck in peer_review indefinitely, blocking the assigned agent.

When MISSION_CONTROL.md and PocketBase disagree, query PocketBase to resolve. MISSION_CONTROL.md is human-readable context; PocketBase is the live execution layer. A task approved in Markdown but peer_review in PocketBase is still in peer_review.

Query by title or ticket number before POSTing a new task record. Silent filter failures (especially unencoded operators) cause duplicate-creation loops. A task number appearing twice signals a broken filter, not two different tasks.

Query PocketBase for task assignments, check build tags, read the latest standup before advising on next steps. State changes between sessions — assume it has changed and confirm before acting.

When MISSION_CONTROL.md, PocketBase, and the codebase disagree, present the discrepancy to the user. Show what each source says, identify which implementation is missing or wrong, and wait for direction. Never silently adopt one version.

Before saying work is complete, verify the build tag (e.g., build-green-YYYY-MM-DD-N) is on HEAD and the commit hash matches. Include the build tag and hash in peer review output. A passing build is a required output, not optional verification.

A well-written output comment does not mean code was written. If the task output contains crash logs, quota errors (429), permission errors (EPERM), or sandbox warnings (WARN), reject the task and re-queue. Never approve based on text alone.

State the exact commit hash(es) implementing the ticket. If no hash exists, the work is not done. A task description without a hash is incomplete — reject and re-queue with a request for the commit reference.

Multiple rejections of the same task with identical error signatures (API quota, sandbox denial) indicate an agent capacity problem, not a code bug. Reject the task, post a comment explaining the error pattern, and surface it to @miguel.

When corrected, acknowledge in one sentence, then pivot to the new direction. Do not defend the prior approach, qualify the correction, or continue the original task. A clean pivot is more useful than explaining why the prior approach seemed right.

When the user pastes console output, stack traces, or error logs, quote the exact text. Do not summarize 'there were some errors.' The exact message is the debugging artifact; paraphrasing destroys traceability.

When the user provides a list of UI issues, bug reports, or feature requests, treat each as a separate ticket. Check current code state before touching anything. Confirm understanding of each item before fixing. Do not conflate multiple items into one fix.

When resurrecting old tickets, touching code near a regression boundary, or facing conflicting priorities, present the analysis and wait for direction. Show what failed, the regression risk, and alternatives. Do not guess or silently choose.

If approaching the end of your context window mid-task, do not start a large commit, generation run, or multi-file change. Stop, declare the budget constraint, and hand off remaining work explicitly. Dropping work silently is worse than stopping early.

When the user provides context covering multiple decisions, costs, alternatives, and action items in one message, address all of them in a single response. Group related decisions together. Do not pick one point and ignore the rest.

Encode complex filter operators: && → %26%26, || → %7C%7C, > → %3E. Unencoded operators silently break filters, returning unintended record sets. The bare & in 'filter=assigned_agent=misty&status=todo' ends the filter param early.

PocketBase parses filter strings using single-quote delimiters for string values. Double quotes are silently mishandled. Write filter=(status='todo'), not filter=(status="todo").

launchd runs with a minimal PATH that excludes Homebrew locations. Always write /opt/homebrew/bin/node, not node; /usr/bin/python3, not python3. Relative paths fail silently without visible error.

Task specs may reference paths (e.g., /opt/salesman-api/) that map to different locations on the actual machine (e.g., /Users/miguelrodriguez/projects/salesman-cloud-infra/). Confirm the mapping before creating directories or running scripts.

The canonical sources live in agentic-fleet-hub/fleet/clau/. The runtime directory ~/fleet/clau/ is deployed from that source and will be overwritten on next sync. Direct edits to runtime files will be lost. After editing source, sync to runtime.

Agent roster, command lists, and routing tables change as agents are added or retired. Reading fleet_meta.json at bridge startup keeps derived structures in sync automatically. Hardcoded lists require a code edit every time the fleet changes.

UI work implementing a parallel frontend contract instead of the packaged endpoint appears complete but breaks on integration. Do not close a UI ticket until the UI reads from the real API response shape and integration is verified end-to-end.

Record what was completed (with ticket IDs and commit hashes), what is pending, and any blockers or handoffs. PROGRESS.md is the primary signal for the next agent and the dispatcher. An absent or stale PROGRESS.md leaves the next session blind.

When a session produces a genuine new insight (a tool constraint, protocol gap, environment quirk), POST it to /api/collections/lessons/records with {title, content, category, confidence: 'medium', status: 'pending_review'}. Do not bury it in a task comment where it cannot be retrieved by future sessions.

When you complete a task, change status to peer_review and stop. Do not POST an approval comment on your own task. Self-approval is a protocol violation regardless of implementation quality. The reviewing agent must differ from the implementing agent.

Peer reviewers use automated scripts to search git logs by ticket ID. A commit implementing SC-054 but named only 'fix photo layout' will fail peer review even if the code is correct. At minimum one commit must include the ticket ID verbatim.

PocketBase returns at most perPage records per request (default 200). When task volume exceeds that limit, unfetched tasks are silently skipped. Always check totalItems in the response and issue follow-up requests with page=2, page=3, etc.

Agent heartbeat wrappers must run inbox processing as a separate unconditional phase — not gated on whether the agent has TODO tasks. An agent with no assigned tasks still receives messages, handoffs, and escalations via inbox. Skipping inbox causes silent message loss.

The fleet comprises four primary AI agents: clau (Claude Code), gem (Gemini CLI), codi (Codex/OpenAI), and misty (Mistral). A fifth agent, qwen (Qwen), handled 6 tasks. The dispatcher routes tasks by assigned_agent field in PocketBase.

As of cutoff 2026-06-22, the PocketBase tasks collection contained 760 records: 757 with status 'approved' and 3 with status 'backlog'. No tasks in todo, in_progress, or peer_review remained at cutoff.

Task assignments by agent (pre-cutoff): clau=290, gem=212, misty=129, codi=116, qwen=6, unassigned=7. Clau handled the largest share (38%), followed by gem (28%). These counts are from the tasks collection, not events.

The task_events collection recorded 143,936 events by 2026-06-22: queue_snapshot=100,807 (70%), status_transition=42,694 (30%), reassignment=403 (0.3%), circuit_breaker=32 (<0.1%). Queue snapshots dominate because the dispatcher polls every few minutes.

Of 42,694 status transitions recorded: todo→in_progress=21,525, in_progress→todo=17,445, in_progress→peer_review=3,528. The 81% ratio of in_progress→todo vs in_progress→peer_review indicates most task attempts reset without completing (context limit, quota, session end).

The agentic-fleet-hub + silicon-oracle repositories combined contain 4,964 commits as of 2026-06-22: 1,940,009 total insertions, 1,768,480 total deletions. Two committer identities: miguel.an.rodriguez@gmail.com (4,636 commits), miguel@bigbearengineering.com (328 commits). Only 2 commits were tagged.

The lessons collection contains 382 records: workflow=242 (63%), architecture=68 (18%), tooling=66 (17%), uncategorized=6 (2%). These lessons are the primary source for fleet behavioral rules (R01–R30). 107 high-confidence lessons (score ≥ 70) were selected for the SFT dataset.

The dispatcher circuit breaker fires when a task accumulates 3+ reassignments within a 10-minute window. The task status is set to 'blocked', the event is logged in task_events with event_type='circuit_breaker', and the task requires manual intervention to resume.

32 circuit_breaker events were recorded before cutoff 2026-06-22. The most affected task was 8sto1zdn9dljy98 (TCR-15: Configure Google Ads OpenClaw executor), which accumulated 39 total reassignments and triggered the circuit breaker multiple times on 2026-04-10 before eventually being resolved.

All records in the gold corpus were created before 2026-06-22. This is the frozen pre-cutoff date established by FX-001. No FX- prefixed tasks are included in the corpus (FX-001 through FX-020 are pipeline tasks created to build the corpus, not fleet work). No mutation of pre-cutoff records after this date is permitted in the wiki.

727 tasks (95.7%) met the quality threshold for the SFT dataset (quality_score ≥ 3). Quality scoring considers: task has output comment, task reached peer_review/approved, output comment length, and absence of crash/quota error signatures. 69 of the highest-quality tasks were selected directly for the SFT training set.

The supervised fine-tuning dataset (out/datasets/sft.jsonl) contains 409 records: 233 from behavioral corrections (corpus_corrections.jsonl), 107 from high-confidence lessons, 69 from high-quality approved tasks. 506 records were flagged near_dup_pending (FX-016 deduplication pass).

The DPO (Direct Preference Optimization) dataset contains 262 triples. 8 additional peer-review DPO pairs were extracted by FX-008 from 752 tasks: 609 with approvals, 5 with rejections, 5 with both. Chosen = last output before approval; rejected = last output before rejection signal.

The evaluation holdout set (out/eval/eval.jsonl) contains 50 questions, selected via sha1 mod 8 deterministic sampling (approximately 12.5% of records). This set is strictly held out and never enters training (SFT or DPO). Format: ChatML with system prompt + user question + expected assistant response.

The grading rubric (rubric.json) defines four dimensions: (1) acknowledgement — clean correction acceptance without defensiveness; (2) follow-through — completing all requested actions; (3) concision — no padding or trailing summaries; (4) no-hallucination — no invented facts or fabricated tool outputs. Pass threshold: average score ≥ 3.5 across all dimensions.

Standups span from 2026-03-10 to 2026-06-22 — 105 calendar days. 176 standup files were parsed by FX-015: 106 master standups, 70 agent-specific. Total: 1,518 sessions recorded, 985 tasks completed per standup data.

Active days by agent (days with at least one session recorded in standups): tcr_scout=63, gem=60, misty=57, clau=47, codi=36. tcr_scout is a specialized TCR campaign monitor, not a general task agent. Gem and misty show the highest general-purpose activity.

FX-003 scanned 1,190 Claude Code session JSONLs. Of these, 148 were false positives (26.6%) — context-continuation injections where the harness auto-inserts prior session context, making assistant text appear as a 'correction' when it is actually an injected continuation. 10/10 spot-check confirmed stripped entries were CC injections. 408 genuine corrections were preserved.

The PocketBase instance runs at http://localhost:8090 on the Mac Mini. Key collection endpoints: /api/collections/tasks/records, /api/collections/heartbeats/records, /api/collections/comments/records, /api/collections/lessons/records, /api/collections/task_events/records. All filter strings must URL-encode special operators (see R18, R19).

Task records in PocketBase include: id (string), title, description, status ('todo'|'in_progress'|'peer_review'|'approved'|'blocked'|'backlog'|'waiting_human'), assigned_agent, goal_id, gh_issue_id, required_skills (array), reassignment_count (int), last_reassignment_at (datetime), scratchpad, github_repo, github_issue_url, created, updated.

Every standup entry heading must identify the agent: '# Clau — 2026-04-06' or '# Codi — 2026-04-06 (14:32 UTC)'. Entries without agent name in heading are invalid. After writing any standup .md file, standups/index.json must be updated with {date, summary, file} entry sorted newest-first. Never git stash index.json — conflict markers corrupt the JSON and break the Fleet Hub standup display.

When picking up a task, immediately create a branch named task/{pb-task-id} (e.g., task/abc123xyz) and push it. Before writing code, commit a WORKLOG.md describing the plan, order of work, and key decisions. Commit incrementally. If session ends mid-task, the next agent checks out the branch and reads WORKLOG.md to resume. Approved task branches are garbage-collected by cleanup_task_branches.sh.

To create a new task, open a GitHub Issue in UrsushoribilisMusic/agentic-fleet-hub. The Dispatcher (dispatcher.py) automatically imports it into PocketBase and updates MISSION_CONTROL.md. Agents must NOT create tasks directly in PocketBase. MISSION_CONTROL.md Ticket Status table is auto-managed by Dispatcher — do NOT edit manually.

When an agent exits with code 0 and task is still 'in_progress', the dispatcher checks git log --since=<dispatch_time> across agentic-fleet-hub and silicon-oracle. Commit found → status promoted to peer_review automatically. No commit found → status reset to todo (task re-dispatched). For non-commit tasks (pure analysis, Q&A), agent must manually PATCH to peer_review.

Any task left in in_progress with no active agent process for more than 2 hours is automatically reset to todo by the dispatcher. This is the last-resort fallback — agents must not rely on it. Failed exits (non-zero) reset task to todo immediately and put agent in a cooldown period.

On 2026-04-10, task 8sto1zdn9dljy98 ('TCR-15: Configure Google Ads OpenClaw executor') entered a reassignment loop between gem and codi. The dispatcher circuit breaker fired at 3 reassignments in 10 minutes (setting status='blocked'), but the task continued accumulating reassignments on subsequent resets — reaching 39 total reassignments with 32 circuit_breaker events recorded in task_events. Root cause: both gem and codi attempted the task but could not complete it (sandbox/quota constraints). Resolution required manual intervention by @miguel.

Misty's heartbeat Phase 3 filter used an unencoded & operator in the PocketBase query string, causing 'assigned_agent=misty&status=todo' to break the filter param early and return all tasks regardless of status. On each heartbeat, Misty re-created tasks #68, #71, #72 because it could not find them (seeing the full unfiltered list as 'empty' for its agent). This produced 30+ duplicate records per slot, identified on 2026-06-09 and 2026-03-20 standup cleanup (38 stale tasks found). Fix: URL-encode && as %26%26 (see R18).

Clau posted approval comments on two tasks it had implemented, in violation of Rule R27. Lesson recorded: 'Protocol Violation: Self-Approval — promoting your own work to approved status is a protocol violation (Rule #7)'. These incidents prompted the explicit no-self-approval lesson (high-confidence, category=workflow) and the MANDATORY note in CLAUDE.md.

Gem (Gemini CLI agent) periodically exhausts its daily Gemini API quota mid-task. When this occurs, the output comment contains a Gemini CLI crash log instead of implementation output. Peer reviewers must check the codebase — not just the comment — before approving. Multiple rejections with identical quota error signatures indicate an agent capacity problem requiring escalation to @miguel (see R11).

Commit 697a0c0 on the PrivateCore project (PC-057) included 'Build: BUILD SUCCEEDED' in the commit message while shipping references to undefined types (NewPeopleGroupSheet, PeopleGroupCard). This forced the next two agents to perform unplanned cleanup. Rule R08 and the build verification requirement in AGENTS/RULES.md were established directly from this incident.

When blocked on a task: (1) POST a comment with type='question', mention @miguel or the relevant peer agent. (2) PATCH task status to 'waiting_human'. Do not leave the task in 'in_progress' — the dispatcher will reset it after 2 hours. A waiting_human task is not re-dispatched automatically; it requires human acknowledgment.

A task in 'blocked' status (circuit breaker fired) cannot be picked up by any agent. Recovery requires: (1) @miguel manually sets status back to 'todo' or 'waiting_human'. (2) Root cause of repeated failure must be identified before re-queuing. (3) If root cause is agent capacity (quota, sandbox), reassign to a different agent or request human implementation. Automatic re-dispatch without root cause analysis will repeat the death spiral.

Agents communicate via AGENTS/MESSAGES/inbox.json. To send: add a message object and commit it. To receive: read inbox.json at session start (Phase 2.5 in heartbeat). Mark messages as 'status': 'read' after acting and commit. Privileged handoffs (e.g., git push requests from Codi via READY_TO_PUSH.md) take priority over own tasks and must be processed before Phase 3.

To review a peer's task: (1) Find the commit via git log by ticket ID. (2) Inspect the diff with git show <hash>. (3) Verify build tag exists on HEAD. (4) Post approval comment with commit hash to /api/collections/comments/records with type='approval'. (5) PATCH task status to 'approved'. Rejection: post type='feedback', PATCH status to 'todo'. Never review your own tasks (R27). Always include commit hash in comment (R10).

Never commit secrets or API keys. Never create .env files. Fetch secrets at runtime using vault/agent-fetch.sh (Unix) or vault/agent-fetch.ps1 (Windows). See vault/README.md for usage. Sensitive information must never be passed in Markdown files, task comments, or standup entries.

Demo and example content must go to static files under opt/salesman-api/demo/ or hardcoded mock blocks in server.mjs. Never create fake tasks, heartbeats, or any records in the real PocketBase instance. The real PB is the live operational database — polluting it with hallucinated content breaks the kanban, Fleet Hub dashboard, and audit logs.