State Ops

---
name: state-ops
description: Inspect fakoli-state project state — list tasks, show task details, find the next claimable task, summarize active claims and blockers, check file-conflict warnings, and reconcile state with the filesystem and git. Use this skill when you want to see what fakoli-state knows without changing anything.
---

# State-Ops — State Inspection

Read the canonical SQLite state that fakoli-state maintains: project summary, task inventory, claim activity, dependency graph, conflict warnings, and filesystem reconciliation. This skill makes no mutations.

---

## When to Use

- When orienting before starting a work session — run `status` first, always.
- Before claiming a task — confirm the PRD is approved and the task is `ready`.
- When a claim was interrupted and the state of the queue is unclear.
- When multiple agents are active and conflict risk is non-trivial.
- When a task shows as `blocked` and the blocker chain needs tracing.
- When suspicious that orphan branches or stale packets exist on disk.
- When reporting project progress to a human or another skill.

State-ops is NOT for authoring or reviewing PRDs — use the `prd` skill. State-ops is NOT for generating plans or scoring tasks — use the `plan` skill. State-ops is NOT for claiming work or submitting evidence — use the `claim` and `execute` skills. This skill only reads.

---

## Prerequisites

The project must have run `fakoli-state init` at least once. Check for the sentinel file:

```bash
ls .fakoli-state/state.db 2>/dev/null || echo "MISSING: run fakoli-state init first"
```

If `.fakoli-state/state.db` does not exist, refuse to proceed and tell the caller to run:

```bash
fakoli-state init --name "<project-name>"
```

Do not attempt to read state, list tasks, or call any other `fakoli-state` command until `state.db` is confirmed present.

---

## Workflow

### Step 1 — Get the project summary

**Phase 2 — available now.**

```bash
fakoli-state status
```

Returns: PRD status (`draft` / `reviewed` / `approved`), total task count, per-status breakdown (`proposed`, `drafted`, `reviewed`, `ready`, `claimed`, `in_progress`, `done`), active claim count, blocker count, and sync state.

Run this first. The output orients every subsequent decision — it answers whether work is even possible before touching any other command.

Key signals to look for:

- `prd-status: draft` — the claim gate is closed. No task can be claimed until the PRD reaches `approved`. Proceed to the `prd` skill instead.
- `ready-tasks: 0` — all tasks are either upstream of ready or already active. Check blockers or the plan skill.
- `blockers: N` where N > 0 — identify which tasks are blocked before picking new work.
- `active-claims: N` — determine whether adding another claim creates conflict risk.

### Step 2 — List tasks by filter

**Phase 3 — pending.**

```bash
fakoli-state list [--status STATUS] [--feature FEATURE_ID]
```

Returns: a table of `TaskID`, title, status, priority, and `agent_suitability` score (1-5).

Filters:

- `--status ready` — tasks available to claim right now.
- `--status in_progress` — tasks currently under active claims.
- `--feature F001` — all tasks scoped to a specific feature.

Use this to audit plan coverage, pick the next work item by priority, or confirm a feature is fully drafted before raising it for review.

### Step 3 — Drill into a specific task

**Phase 3 — pending.**

```bash
fakoli-state show TASK_ID
```

Example:

```bash
fakoli-state show T012
```

Returns: full task detail including title, intent, acceptance criteria, six-dimension scores (`complexity`, `parallelizability`, `context_load`, `blast_radius`, `review_risk`, `agent_suitability`), `expected_files`, dependencies, and current claim status (agent, lease expiry, heartbeat).

Run `show` before claiming to confirm:

- The acceptance criteria are concrete and independently verifiable.
- `complexity` is under 4 (if 4+, expand first via the `plan` skill).
- No active claim already covers this task.
- `expected_files` does not overlap files currently claimed by another agent.

### Step 4 — Find the next claimable task

**Phase 4 — pending.**

```bash
fakoli-state next
```

Returns: the single highest-priority `ready` task that has no unmet dependencies and no file conflicts with currently-active claims.

This is the standard agent-loop entry point. Run it instead of manually scanning `list` output when the goal is simply to find work. After `next` returns a task ID, run `show TASK_ID` to read the full detail before claiming.

If `next` returns nothing, check `status` — the queue is either empty, fully claimed, or PRD-gated.

### Step 5 — Check for conflicts

**Phase 5 — pending.**

```bash
fakoli-state conflicts
```

Returns: conflict groups — sets of active claims whose `expected_files` overlap. Each group lists the claim IDs, the overlapping file paths, and the agents holding each claim.

Run this proactively before claiming a task that touches shared files (e.g., a module's `__init__.py`, a schema file, or a config). A conflict warning at this step is cheaper than a merge conflict later.

`fakoli-state claim` also warns on overlap at claim time, but `conflicts` gives the full picture across all active claims, not just the one being attempted.

### Step 6 — Reconcile with filesystem and git

**Phase 8 — pending.**

```bash
fakoli-state sync
```

Returns: a reconciliation report listing orphans — branches that exist in git but have no corresponding claim in `state.db`, packets in `.fakoli-state/packets/` with no matching task, and claims with expired leases that were never force-released.

Run this after a session ends abruptly, after a force-push cleans up stale branches, or periodically during long-running projects to keep state clean.

To apply fixes interactively:

```bash
fakoli-state sync --fix
```

The `--fix` flag prompts before each remediation. It does not delete data silently. Pass `--yes` to auto-confirm when running in a non-interactive context (confirm this is safe first).

---

## Hook-Friendly Output

The `SessionStart` hook (`detect-state.sh`) calls `status` in compact form for machine consumption:

```bash
fakoli-state status --hook-format
```

Emits exactly one line:

```
active-claims:N ready-tasks:N blockers:N prd-status:STATUS
```

Where `STATUS` is one of: `none` (no PRD found), `draft`, `reviewed`, or `approved`.

Parse this format when reading `status` from a hook or another skill. Do not parse the human-readable `status` output — its layout may change. The `--hook-format` contract is stable.

Example of a healthy project at the start of an execute session:

```
active-claims:0 ready-tasks:4 blockers:0 prd-status:approved
```

Example of a PRD-gated project:

```
active-claims:0 ready-tasks:8 blockers:0 prd-status:draft
```

The second example blocks claiming even though `ready-tasks` is non-zero — the PRD gate is enforced by the claims manager, not by `ready-tasks` count.

---

## Common Pitfalls

- **Claiming before PRD is approved.** The claims manager enforces this gate — `fakoli-state claim` will error if `prd-status` is not `approved`. Run `status` first and check `prd-status` before attempting any claim.
- **Manually editing `state.db`.** Do not use sqlite3 directly on `state.db` to fix state. Every mutation should go through the CLI so the change is recorded in `events.jsonl`. Manual edits produce state that cannot be replayed or audited.
- **Assuming stale claims block the queue.** Stale leases are detected and cleared automatically on the next CLI or MCP operation — no manual intervention is needed. Wait one cycle (run any `fakoli-state` command) and the task returns to `ready`.
- **Confusing `conflicts` (file overlap) with `blockers` (dependency blockers).** `status` reports both separately. `blockers` are tasks stuck in `blocked` status due to unmet task dependencies. `conflicts` are active claims that overlap on files. Address them differently.
- **Running `sync --fix --yes` without reading the report first.** Run `sync` (without `--fix`) first to read the orphan report, then decide whether auto-remediation is appropriate.

---

## Composition with Other Skills

State-ops fits into a repeating inspection-then-action cycle:

| Sequence | Skill |
|---|---|
| Nothing precedes state-ops | State-ops is read-only and safe to run at any point in any session |
| `status` shows `prd-status: draft` | Proceed to the `prd` skill to author or approve the PRD |
| `status` shows `prd-status: approved`, `ready-tasks: 0` | Proceed to the `plan` skill — tasks may need scoring, expand, or review-to-ready promotion |
| `list` or `next` returns a task ID | Proceed to the `claim` skill (Phase 4) to take ownership |
| `show TASK_ID` reveals `complexity ≥ 4` | Return to the `plan` skill — run `fakoli-state expand TASK_ID` before claiming |
| `conflicts` shows overlap | Resolve the conflict first (wait for the other claim to complete, or coordinate with the other agent) before proceeding to `claim` |

State-ops is the starting point of every agent work session. It answers "what is true right now" before any skill decides "what to do next."

---

## Sync operations

Phase 8 ships the bidirectional sync surface. Three entry points cover
day-to-day operation.

### Reconciliation only (no network)

```bash
fakoli-state sync
```

Runs `ReconciliationEngine` and prints discrepancies — orphan branches,
orphan packets, orphan worktrees, stale claims, missing `SyncMapping`
rows for `done` tasks, drifted `sync_state`. No provider call. Safe to
run at any time.

Add `--fix --yes` to apply each auto-fixable suggestion. The
`missing_sync_mapping` and `drift_sync_state` kinds print a
`fakoli-state sync provider <id> --pull --task <id>` command in their
suggested fix but require manual execution.

### Push + pull against GitHub

```bash
fakoli-state sync github
```

Alias for `sync provider github_issues`. Pushes every local task to its
mapped issue, then pulls each one back. Per-task failures (rate limit,
auth, deleted issue) surface on stderr and do not abort the batch.
Conflicts honour the `SyncMapping.conflict_resolution_strategy` enum.

Useful variants:

| Command                                     | When                                                      |
|---------------------------------------------|-----------------------------------------------------------|
| `fakoli-state sync github --push`           | Right after `apply --approve`, when remote is the destination only. |
| `fakoli-state sync github --pull`           | When the remote has been edited and local needs reconciling.        |
| `fakoli-state sync github --task T001`      | Single-task scope; faster than the full pass.                        |
| `fakoli-state sync github --watch`          | Long-running poll; Ctrl-C exits cleanly.                              |
| `fakoli-state sync github --fix`            | Force `remote_wins` for every conflict in this run.                   |

See [`docs/github-sync.md`](../../docs/github-sync.md) for the full CLI
reference and the status-label mapping.

### Provider health check

```bash
fakoli-state sync github --health
```

Probes the GitHub provider's reachability + credential state without
touching local state. Prints `available`, `auth_configured`,
`last_check_at`, and an `error` line if either bool is False. Always
run this before a first sync against a fresh checkout.

Exits without error even when the provider is broken — the agent reads
the printed `auth_configured` line and decides whether to escalate to
the user (`gh auth login` or set `GITHUB_TOKEN`).

### Resolving a `conflict` `SyncMapping`

When an agent's inspection (e.g. via the state-keeper agent or a
manual `sqlite3` query) shows a `SyncMapping` with `sync_state ==
"conflict"`, the local and remote diverged after the last sync and the
configured strategy did not resolve in this iteration. Two paths:

1. **Operator-driven merge.** The `manual_merge` strategy writes
   `.fakoli-state/.sync-conflicts/<task_id>.md` with local and remote
   side-by-side. Edit the file, choose a winner, delete the file, then
   rerun `fakoli-state sync github`. The batch exits with code `2`
   while any task is parked.

2. **Auto-pick a winner.** Set the mapping's
   `conflict_resolution_strategy` to `local_wins` or `remote_wins` and
   rerun sync. The decision is recorded as `local_wins_deferred` /
   `remote_wins_deferred` in the `sync.conflict_detected` audit event;
   the mutation rides the next push/pull pass.

Explain both options to the user when surfacing the conflict — never
silently pick one. The audit log is the source of truth for what
happened; check `events.jsonl` for `sync.conflict_detected` events on
the affected task before recommending a fix.

---

## Phase 2 Limitations

The current branch (`feat/fakoli-state-phase-2-state-engine`) ships only two working CLI commands. All other commands listed in this skill will error with `command not found` or `NotImplementedError` until their respective phases land.

### Working in Phase 2

| Command | Status |
|---|---|
| `fakoli-state init` | Phase 2 — available |
| `fakoli-state status` | Phase 2 — available |
| `fakoli-state status --hook-format` | Phase 2 — available |
| `fakoli-state status --cwd PATH` | Phase 2 — available |

### Pending (do not invoke)

| Command | Target Phase |
|---|---|
| `fakoli-state list` | Phase 3 |
| `fakoli-state show TASK_ID` | Phase 3 |
| `fakoli-state next` | Phase 4 |
| `fakoli-state claim TASK_ID` | Phase 4 |
| `fakoli-state conflicts` | Phase 5 |
| `fakoli-state sync` | Phase 8 |

During Phase 2, the full state-ops workflow collapses to: run `fakoli-state status`, read the output, and proceed to whichever skill the summary indicates. Do not call any command not in the working list — they will error and produce no useful output.