Agentic ops core

Agentic Ops Core

Shared model for the agentic-ops cluster. Every spoke — comms, code-host, tracker, knowledge, billing, audit — runs the same loop over a different surface. Keep that loop and its vocabulary consistent here so no spoke claims state it didn't prove and no spoke widens a mutation silently.

1. The operator loop (this cluster's defining model)

Operations are read-before-write and prove-before-claim. Every spoke walks the same five steps; only the surface changes:

Resolve surface ──> Read live state ──> Smallest reversible action ──> Prove it ──> Report exact status
   (which?)            (inspect)           (draft / narrow / no-op)      (evidence)     (one status word)

1. Resolve the exact surface. Which mailbox/account, repo+branch, thread, tracker item, billing customer, or store. Ambiguity here is the #1 source of wrong actions. → every spoke opens with this.
2. Read live state before mutating. Inspect the thread, diff, ticket, invoice, or config now — never act from memory when the live surface is readable. → terminal-ops, email-ops, automation-audit-ops.
3. Smallest reversible action first. Default to read-only / draft / no-op unless a live send/push/refund/delete was explicitly requested. Restore self-serve before refunding; narrow the fix before a repo-wide pass. → customer-billing-ops, terminal-ops.
4. Prove it. Attach concrete evidence: a Sent-folder entry, the branch that moved upstream, the CI run, a file path, a snapshot timestamp, an exact failure signature. A claim without proof is a guess. → finance-billing-ops, terminal-ops.
5. Report one exact status word. No vague "done". Use the spoke's status vocabulary (§3).

Rule: if you cannot prove a step, say what's blocking it rather than asserting completion.

2. Surface taxonomy

Operations group into six surface families. Routing is surface × intent; the orchestrator picks the family, the spoke owns the loop.

Surface family	Spokes	The thing being operated
Communication	email-ops, messages-ops, unified-notifications-ops	inboxes, DMs, alert streams
Code-host & execution	github-ops, git-workflow, terminal-ops	repos, branches, CI, releases
Project flow & trackers	project-flow-ops, jira-integration	issues, PRs, execution lanes
Knowledge & documents	knowledge-ops, google-workspace-ops	KB layers, Drive/Docs/Sheets/Slides
Revenue	customer-billing-ops, finance-billing-ops	subscriptions, invoices, pricing truth
Audit & observability	automation-audit-ops, workspace-surface-audit, connections-optimizer, dashboard-builder	live inventory, env surface, social graph, metrics

3. Status-word vocabulary (the proof contract)

Each spoke reports a bounded, exact final state. Never substitute a vaguer word.

Spoke / family	Allowed terminal states
email-ops	drafted · approval-pending · sent · blocked · awaiting-verification
messages-ops	read · code-found · blocked · awaiting-reply-draft
terminal-ops	inspected · changed-locally · verified-locally · committed · pushed · blocked
automation-audit-ops / project-flow-ops	keep · merge · cut/close · fix-next · park
billing (customer-/finance-)	classified · refunded · preserved · converted · no-op

The rule behind the table: a status word is a promise you can back with evidence. "sent" requires a Sent-folder check; "pushed" requires the upstream branch to have moved; "verified-locally" requires the proving command to have been re-run; "refunded" requires the charge to be classified first.

4. Live vs. snapshot (the freshness rule)

• Prefer live data on every read (live mailbox, live git/gh state, live billing API, live config).
• If data is not live, state the snapshot timestamp explicitly. → finance-billing-ops ("SNAPSHOT — timestamp").
• "Present in config" is not "working". Mark surfaces as configured / authenticated / recently-verified / stale / missing — they are different. → automation-audit-ops, workspace-surface-audit.

5. One canonical home (the no-duplicate rule)

• Keep one canonical home per fact set; avoid parallel copies of the same plan across notes, repo files, and tracker docs. → knowledge-ops.
• Dedupe before storing: search first, then create-or-update. → knowledge-ops, google-workspace-ops (find the current tracker, not the stale duplicate).
• Public vs internal split is deliberate: GitHub = public truth, Linear = internal execution truth; not every issue needs both. → project-flow-ops.
• customer-billing-ops (one customer's remediation) and finance-billing-ops (operator revenue/pricing truth) are a deliberate split, not a duplicate — route per question, don't merge.

6. Shared guardrails

• Read before write; prove before claim. Inspect live state; never assert sent/pushed/fixed/refunded without naming the proof.
• Default-deny on mutation. Draft/read-only/no-op unless the live action was explicitly requested; smallest reversible step first; never use destructive git or blind refunds.
• Secrets & PII. Never expose API keys, tokens, webhook secrets, full card details, or unnecessary customer PII; redact before committing to Git.
• Separate fact from recommendation. Keep revenue fact / customer impact / code-backed truth / recommendation in distinct buckets; same for audit findings vs proposed fixes.
• Audit before remediate. When overlap or breakage is suspected, build the evidence table first (automation-audit-ops, workspace-surface-audit) before merging, cutting, or rewriting.
• Right surface, stated plainly. If the real fix is a different surface — better triage, a hook policy, a product/billing gap — say so instead of forcing the current tool.