preflight-verify

name	preflight-verify
description	Run canonical session-start gates (HEAD pin, working tree clean, settings.local.json baseRef, bd lint parse) with machine-parseable output for linter consumption.

Preflight verify

When to invoke

At session start before opening any non-trivial work; before issuing any agent dispatch; before any commit-on-main. The four checks together establish the baseline environmental contract that downstream tools assume.

What it does

Invokes tools/preflight-verify.sh to run four canonical gates (HEAD pin, working tree porcelain, .claude/settings.local.json worktree.baseRef presence, bd lint --json parse) and returns a single aggregated JSON object describing each check's pass/fail state. The output shape is documented in the script header as the o4fp.2 GSOM linter extensibility contract.

Contract with primitive

• Primitive: tools/preflight-verify.sh
• Flags / inputs:
  • --check <head|tree|settings|bd-lint|all> (default all)
  • --expected-head <sha> (optional; pin HEAD to a known SHA)
  • --json (machine-readable output)
• Output shape:

  {
    "checks": [
      {"name": "head",     "pass": true,  "actual": "<sha>",        "expected": "<sha-or-empty>"},
      {"name": "tree",     "pass": true,  "actual": "",             "expected": ""},
      {"name": "settings", "pass": true,  "actual": "<baseRef>",    "expected": "<non-MISSING>"},
      {"name": "bd-lint",  "pass": true,  "actual": "total=<n>",    "expected": "parses"}
    ],
    "all_pass": true
  }
  

• Exit semantics: 0 if all_pass is true; 1 if any check fails.

Example invocation

tools/preflight-verify.sh --check all --json
tools/preflight-verify.sh --check head --expected-head 62aaf6842da1b0fd614dd0b9303f93ee0f2da022 --json

Halt conditions

• head check fails (HEAD missing or mismatched against --expected-head) — blocking; halt + surface the actual SHA.
• tree check fails (working tree dirty) — blocking; halt + surface the porcelain output.
• settings check fails (file missing, JSON unparseable, or worktree.baseRef MISSING) — warning-class; surface but do not block routine engineering work.
• bd-lint check fails (cannot parse bd lint --json) — warning-class; surface and continue.

Related

• ADR-016 §6 (Evidence Bundle Schema): the output JSON shape is shaped to be ingestible by the linter consumer.
• amnesia-o4fp.2 GSOM linter: downstream consumer of the schema; this primitive's output is one input source.
• Sibling primitives: tools/divergence-report.sh (HEAD vs remote drift), tools/bundle-extract.sh (post-dispatch artifact extraction).