fulcra-agent-reconcile git:20260724.f160191A

Immutable. This exact content is served forever at /api/v1/blob/5f53dcc81bb15acc.

---
name: fulcra-agent-reconcile
description: "Give a fulcra-agent-teams space self-healing, queryable task views: fold changed OKF task docs from the data-updates feed, retain a fail-closed full-scan fallback, regenerate task/index.md and log.md, and answer status/board/needs-me/search in one read."
homepage: "https://github.com/ashfulcra/fulcra-tools"
license: "MIT"
user-invocable: true
metadata: { "openclaw": { "emoji": "🩺" } }
---

# Fulcra Agent Reconcile

Enhances the [`fulcra-agent-teams`](https://github.com/fulcradynamics/agent-skills) skill. Bare teams
tracks tasks as OKF markdown under `team/<team>/task/` and asks agents to hand-maintain `task/index.md`.
At any real scale that index drifts. This skill makes the index **engine-owned and self-healing** and adds
**structured queries** the convention otherwise lacks — without changing how tasks are written.

## What it does
A bundled stdlib-only tool (`coord-engine`) that, for a given team:
- **Folds** changed `team/<team>/task/*.md` docs from the authoritative
  `data-updates` feed, reading only the changed shards.
- **Heals** `task/index.md` (OKF §6, grouped by status) and appends `task/log.md` (OKF §7, status
  transitions), with a periodic full-scan drift check that loudly rebuilds any divergence.
- **Emits** `team/<team>/_coord/summaries.json` — a fast-path aggregate so reads are one download, not N.
- **Answers** `status` / `board` / `needs-me` / `search` from that aggregate.

Properties: **orphan-proof** (scheduled full-scan drift checks rebuild from ground truth),
**incremental** (a durable feed cursor reads only changed task shards), **degraded-safe** (any
feed/cursor/shard doubt falls back to the full listing scan; if that scan fails, the pass aborts and
leaves the prior index intact — never publishes a truncated view).

## The OKF Task contract (what a task doc looks like)
```yaml
---
type: Task                         # OKF required
title: Fix the widget             # OKF display name
description: one-line summary       # OKF — becomes the index bullet text
timestamp: 2026-07-01T14:00:00Z    # OKF last-change time
tags: [workstream:web, kind:bug]
# coord extensions (OKF-legal producer keys):
status: active                     # proposed|active|waiting|blocked|done|abandoned
priority: P1                       # P0|P1|P2|P3
assignee: ash                      # for needs-me
owner: claude-code:host:web
blocked_on: null
due: null
not_before: null                   # hides from needs-me until this time
---
<body: human notes>
```
Bare-teams tasks that lack the extension keys are still first-class — missing `status`/`priority` are
backfilled (`proposed`/`P2`).

## When to use
- After creating/updating tasks in a team space, to refresh the index and views.
- On a schedule (a heartbeat) to keep a busy team's index healed.
- Whenever you want to query a team's work (`status`/`board`/`needs-me`/`search`) instead of reading files.

## Ownership rule
Once you use this skill, `task/index.md` and `task/log.md` are **engine-owned** — let the tool regenerate
them; edit task *content* docs, not the indexes. `_coord/summaries.json` is a cache (delete + re-run
reproduces it). Recoverable archival is **move-not-delete** (Fulcra `file delete` isn't CLI-undoable).

## Retention (optional add-on)
With `--retention-days N` (or env `COORD_RETENTION_DAYS`), reconcile archives terminal tasks older than N
days to `task/archive/<YYYY-MM>/` — a **verified move** (copy → read-back → delete), never a bare delete —
and moves the task's ack/response shards with it. Once per day, capped per pass. `coord-engine task
restore <team> <slug>` brings one back; `coord-engine search <team> <q> --archived` searches the cold
archive. Retention defaults to 14 days; set `COORD_RETENTION_DAYS=0` or pass
`--retention-days 0` to disable it explicitly.

## Where to start — the re-entrancy probes

Before reconciling or querying, probe whether the engine is usable and whether the aggregate this skill
owns is already fresh. Enter at the **first probe that fails** (per the repo's skill-quality pattern,
`docs/skill-quality-pattern.md`); reconcile is the healer — a full rebuild from ground truth, orphan-proof
and degraded-safe — so re-running it never corrupts state and re-entry is always safe:

| Probe (run in order) | Command | Passes when | If it fails, enter at |
|---|---|---|---|
| Engine + auth usable? | `coord-engine doctor <team>` | exits 0 and the last line is exactly `doctor: healthy` | fix engine/auth first — a `✗` line names the broken leg (launcher not on PATH, or File Store unreachable → `fulcra auth login`); do NOT reconcile against a broken engine |
| Aggregate present + fresh? | `coord-engine status <team>` | output does NOT contain `(no aggregate for team/` (the CLI's missing-aggregate hint, printed only when no aggregate has been built) | **Reconcile** — run `coord-engine reconcile <team>` (see [Usage](#usage)) to fold feed changes or take the fail-closed full scan and build/heal the aggregate, then re-probe |

Both probes pass → the engine is healthy and the aggregate exists, so `status`/`board`/`needs-me`/`search`
read the fresh view; reconcile again on your cadence (or heartbeat) to keep it healed as tasks change.

## Usage
This skill drives the shared **`coord-engine`** tool — invoked as the bare installed binary (never
`uv tool run`, which resolves an ephemeral version; coord-engine is not on PyPI), so the skill itself
stays pure prose + references (no bundled code). Needs `fulcra-api` authenticated and `coord-engine`
installed (`uv tool install <fulcra-tools>/packages/coord-engine` — from the git tag or a checkout).
See [`references/reconcile-cli.md`](references/reconcile-cli.md).
```bash
coord-engine reconcile <team>            # feed delta (or full-scan fallback) + heal views
coord-engine board    <team>
coord-engine needs-me <team> --agent <id>
```