/backfill

name: backfill
description: 'FluencyLoop safety net. Reconstruct store records for work that shipped without going through the loop — reads a merged diff, records the feature, session, decisions, knowledge, and architectural concepts, and defaults reconstructed decisions to unverified. Use post-merge, or when the user says "fluencyloop backfill", "document this PR after the fact", or "we skipped the loop on this one".'

Backfill — reconstruct, make fluent, then flag

FluencyLoop never blocks a merge. The safety net for work that skipped the loop is **post-merge backfill**: it gives ad-hoc work a home retroactively. Backfilled rationale *usually* had no real-time teaching in FluencyLoop's format to force honesty, so it is the entry most at risk of plausible post-hoc fiction — which is why every backfilled entry is stamped `trust: ⚠ unverified` by default. It lands immediately and never asks for a confirmation; a contemporaneous record can strengthen the reconstruction without changing that default.

Backfill is not just bookkeeping. Its job is to recover the durable explanation of the components the work touched — the fluency the missing real-time loop never gave them. Record that explanation as the same feature, session, decision, knowledge, and concept records a live loop would write, while making uncertainty visible in the record rather than turning it into a conversation gate.

Bundled CLI (Codex)

On macOS, Linux, Git Bash, and WSL, the trusted SessionStart hook maintains an owned `~/.local/bin/fluencyloop` shim for this installed plugin. Invoke `fluencyloop …` directly so Codex shows the readable command in its transcript. Do not resolve its path, check PATH, or describe the shim to the developer.

If that command reports `command not found` because hooks have not run yet, invoke the bundled dispatcher from the loaded skill path as a silent fallback. On native Windows, invoke the adjacent `fluencyloop.ps1` with `pwsh`.

Local site — open once

Before the first user-visible response, run `fluencyloop site --ensure --open-once --json`. This ensures the reader for every workflow entry, but opens a browser tab only once while that managed reader is alive. If it reports `running: true` and no earlier assistant message in this session starts with `FluencyLoop site:`, say `FluencyLoop site: <url> (opened in browser).` once, using its returned URL. Do not mention an unavailable site or repeat the announcement.

Generated prose — ASD-STE100

Write generated user-facing technical prose in ASD-STE100 style: use short, direct sentences, active voice, one main action per sentence, and stable, unambiguous terms. Preserve product names, code identifiers, CLI commands, field names, and exact recorded values. Do not claim formal ASD-STE100 compliance: that requires checking the official controlled dictionary and rules.

Automatic trust handling

Backfill never asks for a trust confirmation. It records uncertainty as `trust: unverified`; only a later, volunteered correction may append a superseding `trust: verified` record.

0. Preconditions

Run `fluencyloop check --json`. If `git_repo` or `fluency` is false, run `fluencyloop init --json` without asking the developer. Backfill commonly starts in a repository that skipped FluencyLoop, so this creates the state required by `fluencyloop feature` and `fluencyloop session` below.

For that `fluencyloop init --json` command in Codex, request sandbox elevation before its first execution. It may create or update Codex-protected `.git` metadata; do not first attempt it in the standard sandbox.

1. Scope the work

Identify what to backfill — a merged PR, a commit range, or the current branch's diff vs its base:

git log --oneline <base>..<ref>
git diff <base>..<ref>

If `.fluencyloop/state.json` exists, read it for the `feature` slug and `base_ref` rather than guessing. Usually it's **absent** for backfill (the work skipped the loop, so nothing wrote it) — derive the base from git as above; §3 writes a fresh state record when it reconstructs the feature.

**Quantify the drift deterministically** with `fluencyloop check --json`: its `unjournaled_commits` counts commits since the last journaled session. A non-zero count with no matching sessions is exactly the skipped-loop work backfill exists to catch — let it scope how much there is to reconstruct.

**Look for a contemporaneous record first.** Work that skipped *FluencyLoop's* loop may still have a real-time log — a `SESSION.md`, ADRs, a spec-kit session summary, design notes, a rich PR description. If one exists, **reconstruct from it**, cite it as a source, and frame the entries as backed by a contemporaneous record (stronger than post-hoc memory) — do **not** write "no real-time teaching happened" when it did. Only a genuine from-nothing reconstruction gets the blind-backfill framing. Such a log is also the best raw material for a rich knowledge-transfer record (step 4).

Legacy repository migration

When automatic import has found a pre-0.3 history (feature records carry `imported_from` and `docs/fluencyloop/features/` contains multiple historical feature directories), the default scope is **every imported feature**, not the current branch or the first plausible release. Enumerate those feature directories in a stable order, read their imported decisions and knowledge plus the relevant history, and examine every one before reporting migration complete. Only use a narrower scope when the developer explicitly names one PR, commit range, or feature.

The importer has already declared each historical feature and its `000-legacy-import` session. Do **not** call `fluencyloop feature` or `fluencyloop session` for them: those commands create or switch branches. Attribute concrete reconstructed records directly to the existing imported session instead:

fluencyloop decision --feature "<legacy-slug>" --session 000-legacy-import ...
fluencyloop knowledge --feature