Fulcra Agent Reconcile

Fulcra Agent Reconcile

Enhances the fulcra-agent-teams 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. Alongside the task rows it builds two read-side projections: reviews (coord.reviews.projection.v1 — per-slug verdict state) and forge (coord.forge.projection.v1 — PR responsibility + feedback item ids), which briefing/needs-me serve instead of scanning hundreds of raw shards per wake. The projection build is budgeted (COORD_PROJECTION_BUILD_BUDGET, default 240s) and converges across passes on a large legacy corpus; an incomplete build is marked and left unserved rather than served as current.
• 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)

---
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: user                      # 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 — deleting it is safe, but re-running does not always reproduce it in ONE pass: the review/forge projection sections are budget-bounded and converge over several passes on a large corpus (until then the folds say raw scan — reviews projection incomplete (scanned N/M) and answer correctly the slow way). 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:

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.

coord-engine reconcile <team>            # feed delta (or full-scan fallback) + heal views
coord-engine board    <team>
coord-engine needs-me <team> --agent <id>