FS.GG.Coord.Cli 0.88.0

FS.GG.Coord.Cli — the typed coordination engine

The schedulability model behind fsgg-coord, as one total function.

This is not a user-facing tool. scripts/fsgg-coord is the client you run; this is the engine it shells out to. You will normally never invoke it by hand.

One explicit exception is the optional local telemetry view. An installed tool can run telemetry dashboard status or the foreground telemetry dashboard serve [--no-open] command for the repository selected by its private workspace association. The server uses only packaged .NET assemblies and embedded assets, binds loopback, prints a one-use bootstrap URL, and never activates or migrates a store while opening the dashboard. See the local telemetry store reference.

What it is for

scripts/fsgg-coord was 4,000 lines of bash modelling a concurrent, transactional, budget-constrained domain in a substrate with no types, no Result, no atomicity, and whose default failure mode was to fail open — an error, an empty result, and a legitimate "no" were the same value. The defect record follows from the substrate: "is this item startable?" was computed in five places and agreed in none (#485), and the fail-open family (#266) has 51 children.

ADR-0034 moves that domain to a typed F# core. There is no bool in a verdict:

type Verdict<'a> = Green of 'a | Red of string list | NoVerdict of reason: string

type Schedulability =
    | Startable
    | WrongStatus of BoardStatus        // NoStatus is its own case, not a Backlog
    | IssueClosed                       // the issue outranks the board column
    | NoTouchSet                        // an OMISSION
    | DeliberatelyNoTouchSet            // `Paths: none` — a DECISION. Not the same fact.
    | UnusableTouchSet of tokens: string list
    | BlockedBy of Blocker list         // resolved = CLOSED *or MERGED*
    | HeldBy of WorkerId
    | HeldByLiveWork of WorkerId * pr: int   // the lease lapsed; the WORK did not
    | OverlapsInFlight of (string * string) list
    | Undetermined of reason: string    // "I could not decide." NEVER green, never a silent skip.

It reads nothing

The engine performs no IO. No board, no issues, no network, no token. The client has already paid for the board scan and the claim markers by the time it decides, so it hands that state over on stdin and the engine decides from it:

fsgg-coord-engine decide < snapshot.json      # → a typed verdict per candidate, as JSON
fsgg-coord-engine decide --text < snapshot.json

That is what makes the engine pure and reproducible: the verdict is a total function of the snapshot, so the same board state always decides the same way, and a test can state the answer rather than stand a live fixture up — no second scan of the 5,000 pt/hr budget the whole fleet shares (#418).

It is the client now

scripts/fsgg-coord is the ADR-0034 §4.4 shim (ADR-0040 Phase D): it resolves this compiled engine and execs it, passing argv through unchanged. The ~7,000-line bash implementation, and the shadow that once ran both engines side by side and returned bash's answer, are gone — this engine is the one and only coordination client.

Exit codes

These are the engine's, not the client's — the client translates them.

An unreachable answer is not a negative one. That rule is the whole point.

Telemetry, qualification, and roadmap closure (0.82.0)

The engine owns the deterministic telemetry boundary. telemetry usage collect codex|claude emits the stable runtime-usage CSV (or canonical JSONL), including exact model and coherent tool versions; --append retains one CSV header and ignores an already-recorded response identity. Every completed collection also archives the frozen CSV under the canonical owner-private content-addressed receipt store. telemetry usage archive|resolve exposes idempotent archive and digest-verified retrieval; --receipt-store overrides the default $FSGG_USAGE_RECEIPT_STORE / $XDG_STATE_HOME/fsgg/telemetry/usage host-state root, while temporary and repository roots are refused. telemetry lifecycle export-comments|seal-successor|validate elects GitHub-comment order, seals the SHA-256 chain, and resolves immutable receipts from explicit --usage inputs first and then the canonical store. A repeatable --legacy-proof accepts only the closed, separately-reviewed irrecoverability schema and excludes the missing event from accounting; it never reconstructs a CSV or trusts counts copied from public lifecycle JSON. Optional --history-report receipts remain supported. Extraordinary histories that cannot be repaired under the creating or current tool version use the first-class repeatable --synthetic-checkpoint <proof.json> input. The closed fsgg.telemetry.synthetic-checkpoint/v1 proof binds the canonical repository/issue/run/unit and exact frontier revision/digest to an immutable human issue-comment authorization, explicitly sets missing_provenance_required:false and reconstruct_missing_data:false, and carries only passed functional checks with immutable evidence. Exactly one adjacent synthetic-evidence-checkpoint phase consumes the proof digest and establishes a new trusted anchor; validation remains strict after that anchor and rejects missing, wrong-scope, stale-frontier, reused, ambiguous, tampered, or functionally failing checkpoints. telemetry summarize, telemetry critique validate, and telemetry feedback validate are read-only. telemetry qualification validate|run validates or executes the closed exact-checkout qualification contract. telemetry qualification obligation render|verify emits the existing guarded, current-head fsgg:delivery-obligation(s) grammar or verifies a strict GitHub PR comment readback through the same delivery parser, with URL and comment id agreement; it introduces no second marker authority.

roadmap unit prepare inspect|render|verify requires the raw --roadmap Markdown and --catalog roadmap-index alongside a narrow --input registration request. It authenticates the catalog's source digest and per-unit contract hashes, then compiles the first unchecked row whose immediate predecessor is accepted into a content-addressed authority pin, unit/gate registrations, staged-intake drafts, and evidence obligations. The render/verify pair changes only the selected unit's explicit registration marker block and performs no GitHub write. roadmap unit prepare apply is the explicit mutating arm: it routes every compiled draft through the existing receipt-first intake apply transaction, verifies the authoritative receipt readback, and emits exactly one canonical preparation-application receipt (or writes it with --output); replay reuses the bound issues and never creates duplicates. roadmap unit accept inspect|render|verify checks only that a caller-authored envelope is internally coherent; its verdict is explicitly internally-coherent-candidate and these pure actions cannot construct or print an accepted receipt. roadmap unit accept seal is the sole acceptance boundary. It requires --qualification-input and --qualification-execution, reruns the production qualification, then independently checks pinned fsgg-sdd 1.5.0 analyze/verify/ship in a fresh remote checkout. It re-compiles the plan from the immutable .github roadmap and FS.GG.Coordination catalog and independently re-reads exact intake receipts and board projections, the unedited lifecycle ledger bound to the live winning claim and implementation commit, the typed review chain and exact evidence comment, immutable SDD artifacts, merged PR facts, remote commit trees, and protected main. Only after those observations agree does it emit the atomic, self-digested accepted bundle consumed by roadmap close without schema translation.

roadmap close inspect|render|verify is likewise a pure candidate projection: it consumes an evidence manifest whose relative artifact paths bind an accepted unit receipt, delivery receipt, schema-v3 critique, schema-v2 feedback report and audit, feedback binding, cycle update, and one or more check receipts. Every machine receipt is canonical and self-digested; all unit, head, cycle, report, audit, claim, and check identities are joined before rendering. render prints only a candidate document and never confers acceptance. verify additionally requires --source-roadmap, authenticates its --source-digest, and proves that the candidate changed no bytes outside the marked unit block.

Version 0.81.0 established the publish-before-adopt boundary. Current callers and cycle-ledger provider validation use these compiled commands directly; the frozen Python differential corpus remains an independent test oracle, while no Python compatibility helper is packaged or invoked at runtime.

License

MIT