diff --git a/OPS-MANUAL.md b/OPS-MANUAL.md new file mode 100644 index 0000000..627663c --- /dev/null +++ b/OPS-MANUAL.md @@ -0,0 +1,81 @@ +# MOPAC Operations Manual — managing the work queue via Redmine + +Audience: Charles + any COS/human operator. The harness loop(s), PMO, and worker turns all +take their direction from the MOPAC Redmine project. If it is not written in Redmine, it +does not exist. Version 1.0, 2026-08-29. Canonical copy: ukrrs/mopac-pmo `OPS-MANUAL.md`; +mirrored into the harness repo docs and referenced by the morning briefing. + +## 1. The model in one paragraph + +Tickets in the **MOPAC** project (projects.knownelement.com) are the single source of truth. +A machine daemon (the harness loop, containerized, restart-policy) scans a scope — +currently `project=mopac, version=Beta, status=New` — and for each ticket runs one bounded +LLM turn with tools (files, allow-listed bash), writes a REPORT, posts a journal note, and +sets status per the map (New -> Resolved). Humans and PMO verify. Everything else +(planning, priorities, wiring instructions) is expressed by editing tickets. + +## 2. Labeling — what each field means + +| Field | Values | Meaning / effect | +|---|---|---| +| Tracker | Feature / Support / Task | Feature=build, Support=ops/editorial, Task=coordination. Bug is RESERVED for defects only. | +| Status | **New** | = work queue. The loop (and PMO) only pick up New. | +| | **In Progress** | = parked/claimed. Invisible to the loop. Use to hold blocked work. | +| | **Resolved** | = worker claims done. Awaiting human/PMO verification. | +| | **Feedback** | = needs Charles input. Check these daily. | +| | Closed / Rejected | verified-done / not-a-bug-duplicate-wontfix. | +| Version | Selfhost Alpha / Beta / Production | The loop scans ONE version at a time (config `scope_query`). Currently Beta. When Beta closes, PMO flips scope to Production — one line in `harness.toml`. | +| Priority | Immediate > Urgent > High > Normal > Low | Within a version, Immediate is drained first. | +| Category | Briefing, Deployment, Documentation, Infrastructure, Integrations, Model Selection, Quota & Backpressure, Secrets, Task Management | Reporting/Filter only — no routing effect. | +| **Class (custom field)** | study / read / code / review / architecture / summarize / vision / primary | **Model routing.** Missing = default (currently `code` -> glm-5.2). `study`/`read` -> flash (cheap triage). Set it when cheap-and-simple is fine. | +| Due date | date | Ordering + morning briefing "decisions needed" surfacing. | +| Est. hours | number | Briefing + quota planning. | +| Relations | blocks / relates | Sequencing. `A blocks B` = B waits. | + +## 3. Recipes — how to do things + +- **Add work**: create ticket, tracker Feature/Task, version = current active version, + status New, priority by urgency, Class if you care about model cost. One ticket = one + deliverable. Put acceptance criteria in the description — turns are only as good as + the ticket. +- **Requeue / redo**: set status New and add a short note why (the note bump also + refreshes the loop's change detection). +- **Park work** (blocked on creds/wiring/humans): status In Progress + note what unblocks it. +- **Ask Charles something**: status Feedback + note; it surfaces in the next morning briefing. +- **Escalate**: priority Immediate (drained first within the version). +- **Guide an in-flight or finished piece**: journal note on the ticket. Notes are the + conversation thread between you, the PMO, and every worker turn. +- **Stop everything**: `docker compose -f ~/projects/meta/MOPAC/harness/deploy/compose.yaml down` + (kill switch). Start again with `up -d` (see deploy/runbook.md for env: HARNESS_UID=1001, + HARNESS_GID=1001, DOCKER_GID=988). + +## 4. Reading what happened + +- Each turn leaves: `reports/REPORT-demo--.md` (in the harness repo, committed) + + a journal note on the ticket + `state/loop/loop.jsonl` (machine trail) + + `state/loop/status.json` (live heartbeat: scans, dispatched, reports, last errors). +- False "Resolved": a turn can hit limits and still mark Resolved. Verification is human/ + PMO duty — check the REPORT has real content and the repo has real commits before + trusting a status. (Known failure modes, all fixed 8/29: docker perms, model routing, + round budgets. Residual: watch for round_limit REPORTs.) +- Morning briefing (495): arrives 0630 CST via Redmine note on 495 + Discourse when wired. + +## 5. Secrets & wiring + +Keys never live in tickets or the repo. Env files 0600 under `~/.coordinate/secrets/` and +`~/.creds/`. Bitwarden/Vault become the store once keyproxy (497) is live. Charles wiring +nights: postfix/SMTP, BW, Signal, Discord, Google — each unblocks a fleet ticket. + +## 6. Queue hygiene (weekly) + +- Empty version = close the version (roadmap hygiene; see the Phase 3 absorption 8/29). +- Bug tracker = defects only. Duplicates: `relates` + Rejected with note. +- The loop scans one version; keep exactly one active version, others closed or future. + +## 7. Ticket template (copy-paste) + + Subject: + Tracker: Feature | Version: Production | Status: New | Priority: High | Class: code + ## Context + ## Scope + ## Acceptance