flightopsDocumentation
Reference: history

Optional retrospective AI

2 min readdocs/reference/retrospective-ai.md (source repository)

flightops retrospective prepares an explicit disclosure and makes at most one bounded request through the selected API provider. Standard mode returns ai_disabled with zero calls, even if evidence is unavailable. No model is needed for deterministic evidence, contracts, review-change or reduce-recording commands.

A request JSON contains question, a configuration snapshot, and 1โ€“8 selections. Owned-source selections bind item_id, exact revision, and a line range (start inclusive, end exclusive) or JSON pointer. Recording selections bind segment_id, topic, start_ns, end_ns and optional numeric field/reduction, unit and bounded sample counts. The source policy must separately allow retention, inference and sharing with the selected endpoint. Repeat --allow-source for selected revision IDs, owned-item IDs and every upstream source. A config flag alone cannot grant source rights.

sh
flightops retrospective --database catalog.sqlite --allow-source SOURCE \
  prepare request.json -o disclosure.json
flightops retrospective --database catalog.sqlite --allow-source SOURCE \
  run disclosure.json --expect-digest REVIEWED_PREVIEW_SHA -o proposal.json
flightops retrospective --database catalog.sqlite --allow-source SOURCE \
  --allow-source PROPOSAL_ARTIFACT show proposal.json --receipt RECEIPT_ID

Preparation names the exact endpoint, model, evidence, supplied configuration and limits without making a provider call. The run refuses changed content, source policy, provider/configuration or disclosure digest. It uses one child process, a maximum 60-second provider wall budget, 60 CPU seconds, 2 GiB address space, a 64 KiB output-file ceiling, at most 64 KiB selected context and a 32 KiB proposal. Source selection has its own existing byte/time limits. Unsupported resource-limit platforms fail closed. Saved citation bindings retain exact selectors, clock limits and omissions, plus the catalogued configuration snapshot identity. API credentials remain managed by the existing provider configuration. Only API adapters are supported; the separate managed Codex subscription route returns unsupported_retrospective_route without silently selecting another provider. The normal interactive Codex route remains available.

Replies must satisfy a fixed JSON proposal schema and cite selected evidence IDs. Unrecognized citations, invalid JSON and any tool call are refused. Citation existence is checked; semantic support, root cause, applicability and independent verification are not established by schema validation. Proposals stay quarantined and cannot execute commands, modify a check, grant rights or approve a release. Failures and unknowns must remain visible. Usage reports include provider token counts when available, with no invented money cost.

Current permissions are resolved again after the response and before retention. A withdrawal withholds the proposal. Saved proposals have immutable evidence receipts and parent lineage, outward use denied by default; show rechecks current rights and exact file bytes. The result file is an explicitly owned local export, not a background managed retention service. Its owner must delete that file and any other copies when retention is withdrawn; managed access immediately refuses. Files are never overwritten, and no result implies a training authorization or model update. Full provider, real-source and user acceptance remain deferred.