# foreman harness for Grok Bot crews

> A CLI harness for hosted Grok Bot crews that reconciles git-declared crews against gbot, gates completion on independent verdicts, and reports only evidence-backed indicators.

foreman is an open-source command-line harness for hosted Grok Bot crews, published under the Archive228 GitHub account. Crews are declared in git and reconciled against `gbot --json`, with a single write path to the account and shift reports that avoid inventing numbers such as cost.

## What It Is

Grok Bot is a hosted product, and the README notes that it has no dry run, no per-bot spend data, no rollback after an approval, and one shared VM for every bot on an account. foreman adds an owned layer on top: a read-only board, a pinned spec file, declared grants, and a hash-chained audit log. It requires Node 18+ and an authenticated `gbot` on the PATH for live collection, and has zero runtime dependencies.

## The board and indicators

`foreman board` serves a read-only page on loopback showing one card per bot, ordered worst state first: waiting on you, stopped mid-task, repeating itself, went quiet, age unknown, then no indicator fired. Clicking a card shows the detections and the transcript path behind it. The shift report uses twelve transcript-derived indicators, including stall, loop, silent bot, handoff drop, roster drift, unverified claim, VM collision and silent routine. Each is documented with what it is not proof of. Token counts and dollar costs are deliberately not reported because Grok Bot does not expose them.

## Spec-gated completion

Each `spec.json` entry is pinned with a hash over category, description, steps and prerequisites. `foreman dispatch` requires `--spec <id>` or an explicit `--no-spec`, which writes a `spec-waived` audit row. `foreman spec pass` succeeds only when a bound run has an approve verdict from a checker that is not the worker. `Partial` verdicts, where verification failed open, and needs-attention verdicts are refused.

## Grants, exposure and audit

Grants record what each bot is meant to reach, using references such as `env:`, `file:`, `keychain:` or `op://` and never raw secrets. `foreman exposure` prints the gap between declared grants and the shared VM. `foreman gate` returns allowed, held or denied as an advisory decision. Every grant, revoke and gate decision is appended to `data/audit.jsonl`, and `foreman audit --verify` names the first altered row.

## Crew changes

`foreman sync plan` and `apply` form the only write path to hosted bots and groups. `crew status` parses cron schedules and shows the next run for each routine. `pack add` fetches, scans and pins packs, and `pack deploy --trust` materializes them into the repo.

## Features
- Read-only live board with one card per bot ranked by state
- Twelve transcript-derived indicators with stated limitations
- Pinned spec.json entries with hash-based tamper detection
- Completion gate requiring an independent checker approve verdict
- Grants stored as references only, never secrets
- Exposure report comparing declared grants to the shared VM
- Hash-chained audit log with verification
- Cron parsing with next-run display for crew routines
- sync plan/apply as the single write path to hosted bots
- Pack fetch, scan, pin and trusted deploy
- Lint for injection and irreversible-verb gate prediction
- Fixture servers for demoing the board without an account

## Integrations
Grok Bot, gbot CLI, xAI

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/Archive228/foreman
- Repository: https://github.com/Archive228/foreman
- EveryDev.ai: https://www.everydev.ai/tools/foreman-harness-for-grok-bot-crews