AGENT SKILL

preflight

Select and run the existing SemEngine verification gates for a concrete diff and record their evidence. Use before implementation pushes or when assessing local readiness.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
preflight
description
Select and run the existing SemEngine verification gates for a concrete diff and record their evidence. Use before implementation pushes or when assessing local readiness.

03 SKILL.md 正文

Verify a SemEngine change

The shared protocol owns claims and landing. Read it first. This skill selects existing checks and records evidence; it grants no merge, tag or cleanup authority.

1. Establish the diff and its owner

Work in the claim's worktree. Verify its branch, HEAD, dirty/untracked files, upstream and PR target before choosing checks. Compare the committed diff against the actual PR base, including a non-default target in a stack; also inspect the staged and unstaged work. Do not assume the discovery checkout's local main is current. Before every commit or push, verify the branch still matches the claimed PR head.

2. Select the existing gates

One Task entrypoint serves local work and CI. task --list shows what exists; inspect the Taskfile.yml and the workflows under .github/ when exact coverage matters. A task name or old successful log does not prove parity with current CI.

Task What it does
task fmt Formats Go sources; the only task here that changes files
task fmt:check Fails if any Go source needs formatting; writes nothing
task doctor Reports tool versions and Docker reachability against their pins; starts no workloads
task ateam:doctor ateam doctor --check with the session variables unset: agent-setup files, skills and adapters, hooks, MCP, review policy, AGENTS.md size and rule-row parity; warnings do not fail it
task spec:check Validates all OpenSpec changes and specs strictly, and fails on a Hold: written outside every task
task spec:queue Shows each in-flight OpenSpec change with its holds and blocking conditions
task docs:check Lints Markdown with markdownlint-cli2
task tidy:check Fails if go.mod or go.sum are not tidy
task build Builds all packages
task vet go vet
task lint Pinned revive
task vuln Pinned govulncheck; review findings against reachable behavior
task cleanup-roots:check Fails if a test stops, closes, or terminates under context.Background() or TODO()
task ledger:check Validates docs/admission-ledger.yaml against its schema
task test:unit Unit tests once with the race detector at one CPU; every package except the three tool packages (toolcheck, mutcheck, pindiff)
task test:tools The tool packages once with the race detector at one CPU; task test:tools:changed runs the same only when a file under their trigger paths (scripts/, internal/harness/, .github/, Taskfile.yml, go.mod, go.sum and the others in toolcheck/doc.go) changed against the base, and says so when it skips
task test:integration Docker-backed tests: plain go test -tags=integration with pinned flags (race detector, two packages at a time, shuffled, 10-minute timeout) and the coverage profile task cover:check reads; runs only packages that have an integration-tagged test; -- <pkgs> to focus
task cover:check Fails below 80% coverage on each target in scripts/cover-check.sh (16 today: the harness's natsfixture, lifecycletest, probe, and each ported package on the SETUP 03B critical list, setup-03b-contract-boundary design.md D10); a package on that list joins when it is ported
task test:repeat Unit tests (not the tool packages, not the repository guards in internal/harness/contract) five times at one CPU without the race detector, in shuffled order; -- <pkgs> to focus
task mutate:check -- -pkg … -test … -file … -mutant … -expect … Run by hand: applies one wrong change to a Go source file through go test -overlay and prints detection, survivor, invalid or inconclusive (the mutation-check spec); fails unless the verdict is detection; writes nothing in the repository
task merge:check -- <n> ateam review gate run via scripts/ateam, the pin (task tools:ateam installs it; docs/testing.md): fails while the rules on main do not require an up-to-date head, while PR n is a code pull request, not a draft, without implemented-by: and reviewed-by: lines naming a not-weaker other agent and an approving review record at its head, or while an open class:flake issue is not closed by PR n; reads GitHub
task verify ateam:doctor first, then the checks above except doctor, fmt, spec:queue, mutate:check, merge:check, cheapest first with test:tools:changed after test:unit and test:repeat last; prints each step's time; fails on tracked-file change; task verify -- checks and task verify -- integration run the two halves CI runs as separate jobs (integration: ateam:doctor, test:integration, cover:check; checks: the rest)

CI has two workflows: in ci.yml, the jobs checks and integration run the two halves of task verify in parallel and required fails if either failed, is missing, or was skipped or cancelled; merge-check.yml runs scripts/merge-check.sh for a pull request that is not a draft, from the base commit, on every push, ready and description edit. task verify needs a reachable Docker daemon for test:integration; a daemon that is not reachable is a failing gate, never a skipped one. A consumer lane joins task verify when its workload exists; until then no task for it exists, and a missing lane is not a passing one.

Select by what the diff changes:

  • Documentation or skill instructions only: task fmt:check, task docs:check, and git diff --check; add task spec:check when openspec/ changed.
  • Agent setup (AGENTS.md, CLAUDE.md, .agents/, .claude/, .codex/, .gemini/): task ateam:doctor and task test:unit (TestAgentSetupParity).
  • An OpenSpec change: task spec:check, then read task spec:queue in this worktree.
  • Go behavior: task test:unit (plus task test:tools when scripts/, internal/harness/, .github/ or Taskfile.yml changed), task vet, task lint, task build; focused tests first during iteration.
  • Docker-backed behavior (internal/harness/natsfixture, any *_integration_test.go): task test:integration -- <pkgs> to focus, then task cover:check, which reads the profile of the last passing integration run and refuses one taken on a different tree. A plain go test -tags integration run is fine while iterating. The NATS image is the one line in internal/harness/natsfixture/nats-image; to try another, edit that line in a branch.
  • docs/admission-ledger.yaml: task ledger:check.
  • Dependencies or go.mod: task tidy:check and task vuln in addition to the Go gates.
  • Before any implementation push: task verify.
  • Immediately before merging: task merge:check -- <n>, in a shell where GITHUB_ACTIONS is not set. It sees a flake filed, a closing line removed, or a review record posted, since the pull request's last Merge check run.

Do not hand-run a narrower command in place of a gate CI runs: the task owns flags and pins.

3. Protect shared test infrastructure

Serialize heavy work on a shared host. Docker inspection is diagnostic: container age, a timeout signature, or a name pattern does not establish that a resource is abandoned or that a failure is infrastructure-only. Preserve other sessions' resources. Cleanup is limited to an identified completed or abandoned run this session is authorized to clean up; host-wide pruning and stopping an unknown port holder are not preflight steps.

4. Record Evidence and remaining gates

Record the tested HEAD (or dirty snapshot), exact command, exit status, assertions/tests actually exercised, and log/artifact location. A log under a path git ignores (such as coverage/) is on this host only: say so, and put the output a reader needs in the PR. Separate failure, skip, no selected tests and compilation-only results. When the implementation changes, older green results remain evidence for the older revision. Preserve the command's failure status when filtering output; do not infer success from a quiet log.

Resolve failures from evidence; a successful re-run is not a fix for a flake. A red that your diff does not explain is filed as an issue before the next push, labelled class:flake when it is a test or check that passes and fails on the same tree. A network fetch that did not answer is not a flake, and a local red whose host: line shows a one-minute load average at or above twice the core count is a host-load suspect first: follow the protocol's "Known flakes" item for both. An open flake is fixed; nothing else gets a pull request past it, and Merge check fails every pull request that does not close it. Long or paid runs need the role contract's active progress checks and bounded stopping behavior.

After local verification, assess the PR's current-head hosted checks and the protocol's review/archive gates. Local green is not merge authorization. Follow existing user authorization without asking for it again, while preserving all outstanding required gates.

04 同仓库更多 Skills