Make integration-preflight a mandatory step 0 with a dependency smoke test (oleks/cluster#271) #1

2026-07-21T16:13:49+03:00

oleks commented

2026-07-21 16:13:49 +03:00

Implements oleks/cluster#271. The preflight skill was already well written — the problem is that it is never invoked. This change makes it a checklist gate rather than a judgment call, and adds the one check both 2026-07-21 ZeroTier sessions were missing.

What changed

skills/integration-preflight/SKILL.md

Reframed as step 0 of every multi-step rollout, non-optional, with the retro quote inline: "the session verified its outputs rigorously but its inputs lazily — every major stall traces to an unchecked precondition, not an unchecked result."
New procedure step 6: smoke-test every external dependency from the runtime context — one real authenticated request per endpoint (controller/admission API, registry, webhook target, database, object store, auth issuer), issued from where the code will actually run (pod / runner / target host), status code pasted into the plan. Worked example is oleks/armer#171: byte-identical token, 200 from 127.0.0.1, 401 from the ZT IP the pods call from. Sub-rules cover source address, real credential, actual verb (authorization is per-route), no-comment-is-a-smoke-test, and unreachable-from-runtime = blocker.
Output section now requires two tables (layers, dependencies); either left blank means the preflight did not run.
description: frontmatter rewritten so the skill routes on rollout-shaped work rather than only on an explicit "run a preflight" request — this is the actual fix for "it is never invoked".

Entry gates — onboard-host, integrate-service, finish-migration each now open with an explicit "Step 0 — entry gate: run integration-preflight (mandatory)" section citing F12/F13. onboard-host previously said "run it first if any existing drift could interact" (a judgment call); finish-migration had it only as an exit audit in the done-criteria and now has it at entry too.

references/failure-catalog.md — two new classes in the existing F-class style:

F12 External dependency never smoke-tested from the runtime context (oleks/armer#171).
F13 Preflight treated as a judgment call (oleks/cluster#260 + oleks/armer#171).

README.md — preflight row + F1–F13 list updated. plugin.json — 1.0.0 → 1.0.1.

Not done (parent's call)

The oleks/cluster#271 acceptance item "update CLAUDE.md rollout guidance" is not in this PR — that is the user's global ~/.claude/CLAUDE.md, outside this repo and outside an agent's authority to edit.
Not merged, not published to the registry index.

Docs-only change; no CI exists in this repo.

Implements oleks/cluster#271. The preflight skill was already well written — the problem is that it is never invoked. This change makes it a checklist gate rather than a judgment call, and adds the one check both 2026-07-21 ZeroTier sessions were missing. ## What changed **`skills/integration-preflight/SKILL.md`** - Reframed as **step 0 of every multi-step rollout, non-optional**, with the retro quote inline: *"the session verified its outputs rigorously but its inputs lazily — every major stall traces to an unchecked precondition, not an unchecked result."* - New procedure step 6: **smoke-test every external dependency from the runtime context** — one real authenticated request per endpoint (controller/admission API, registry, webhook target, database, object store, auth issuer), issued from where the code will actually run (pod / runner / target host), status code pasted into the plan. Worked example is oleks/armer#171: byte-identical token, 200 from `127.0.0.1`, 401 from the ZT IP the pods call from. Sub-rules cover source address, real credential, actual verb (authorization is per-route), no-comment-is-a-smoke-test, and unreachable-from-runtime = blocker. - Output section now requires **two** tables (layers, dependencies); either left blank means the preflight did not run. - `description:` frontmatter rewritten so the skill routes on rollout-shaped work rather than only on an explicit "run a preflight" request — this is the actual fix for "it is never invoked". **Entry gates** — `onboard-host`, `integrate-service`, `finish-migration` each now open with an explicit "Step 0 — entry gate: run `integration-preflight` (mandatory)" section citing F12/F13. `onboard-host` previously said "run it first *if* any existing drift could interact" (a judgment call); `finish-migration` had it only as an *exit* audit in the done-criteria and now has it at entry too. **`references/failure-catalog.md`** — two new classes in the existing F-class style: - **F12** External dependency never smoke-tested from the runtime context (oleks/armer#171). - **F13** Preflight treated as a judgment call (oleks/cluster#260 + oleks/armer#171). **`README.md`** — preflight row + F1–F13 list updated. **`plugin.json`** — 1.0.0 → 1.0.1. ## Not done (parent's call) - The oleks/cluster#271 acceptance item "update CLAUDE.md rollout guidance" is **not** in this PR — that is the user's global `~/.claude/CLAUDE.md`, outside this repo and outside an agent's authority to edit. - Not merged, not published to the registry index. Docs-only change; no CI exists in this repo.

oleks added 1 commit 2026-07-21 16:13:49 +03:00

preflight: make integration-preflight a mandatory step 0 with a dependency smoke test 8a28233417

Closes-part-of oleks/cluster#271.

- integration-preflight: framed as the non-skippable step 0 of any
  multi-step rollout; new procedure step 6 requires ONE real authenticated
  request against every external endpoint FROM THE RUNTIME CONTEXT, with
  the allowManagementFrom case (oleks/armer#171) as the worked example;
  output now carries a dependency table alongside the layer table;
  description rewritten so the skill actually routes on rollout-shaped work.
- onboard-host / integrate-service / finish-migration: each names
  integration-preflight as its step 0 entry gate.
- failure-catalog: adds F12 (external dependency never smoke-tested from
  the runtime context, oleks/armer#171) and F13 (preflight treated as a
  judgment call, oleks/cluster#260 + oleks/armer#171).
- README + plugin.json 1.0.0 -> 1.0.1.

oleks merged commit 182ca54bc5 into main

2026-07-21 16:19:39 +03:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: oleks/claude-plugin-fleet-integration#1