verify-e2e

End-to-end smoke of the whole markgate CLI. The companion to make lint (static) and go test ./... (unit / integration); this one is the black-box layer that drives the built binary against real git init sandboxes the way a user would.

When to invoke

• After a non-trivial change anywhere under cmd/ or internal/cli/ — the unit tests cover most of this, but the black-box harness catches wiring regressions (cobra command registration, flag exposure, exit-code mapping in Execute).
• Before opening a PR for a CLI-touching change. Faster than waiting on CI.
• Before declaring a multi-PR merge wave done.
• When the user asks "is everything still working?".

The PreToolUse hook e2e-pre-merge.sh runs the same script automatically before any gh pr merge ..., so you usually do not need to invoke this skill immediately before merging — but it is the manual entry point and a good rehearsal step before pushing.

What it covers

Three layers of assertions (the script prints the count on every run; it is deliberately not restated here, because a number copied into prose drifts):

Core primitives

• set / verify / clear cycle including clear idempotency
• Default key (no positional arg) → default
• --hash files requires --include; respects scope
• --state-dir flag override; marker NOT in default location
• MARKGATE_STATE_DIR env override
• Precedence chain: flag > env > state_dir: > default
• run: child runs on miss, skips on match, exit propagates, marker NOT advanced on child failure
• init writes .markgate.yml and is non-clobbering
• version prints something

2026-05-09 batch features

• completion: bash script emit, unknown-shell exit=2, dynamic gate-key completion via __complete
• config lint: clean exit=0, dirty exit=1, dead glob / unknown-field detection, --json shape
• TTL: fresh→0, expired→1 with stderr message, set resets, 1mo rejected at config load
• --explain / -e: scope to stderr, exit code unchanged, pretty-printed JSON shape {key, scope, hasher, state}
• Bare status: header, all rows, (configured) / (unconfigured) notes, single-key backward compat, snake_case --json
• composes (loose): unconditional set, verify-time propagation
• requires (strict): set refused exit=2 naming offending child
• Config-load errors: cycle / missing child / both fields set all reject at exit=2

hash: diff

• set / verify on a branch ahead of the base; status records the base ref and the resolved merge base
• unrelated base-branch change merged in -> still fresh; a change to a file the branch also touched -> stale
• uncommitted in-scope edit / untracked in-scope file -> stale; out-of-scope edit -> fresh
• clean base-branch checkout -> verify and set both exit=2 naming hash=diff; bare status degrades the row instead of aborting the listing
• unresolvable base -> exit=2 naming the ref
• --hash diff --base flags; --hash diff without --base and --base without hash=diff both exit=2
• config without base rejected; base on a files gate lints dirty with an explanatory message

Dead include globs (both scoped modes)

• an include list matching nothing -> set exit=2 naming the pattern, on files and diff alike, and no marker is written; verify reports it as a mismatch (exit=1), not an error
• a scope cleaned away between builds still rebuilds: a second run cycle after the scope is deleted executes its child and re-records
• the candidate universe differs per mode: an include matching only gitignored paths is live for files (which hashes them) and dead for diff (whose delta can never contain them)
• the other empty scopes stay usable: a quiet branch with a live include, and exclude emptying what include matched
• bootstrapping is preserved: verify with no marker is exit=1 without hashing, so run still executes its child and records the marker once the child creates the scope
• when the child runs and the scope is still empty, the marker is refused (child ran, no marker written)
• --explain stays diagnostic: it renders the empty scope, so adding the flag never suppresses run's child — including when the scope cannot be computed at all (a malformed glob)
• a rename that kills a live scope -> verify exit=1 and set exit=2; bare status degrades that row and keeps rendering the others

clear survives an invalid config (#77)

• a validation error elsewhere in the document no longer blocks removal, and the gate's own state_dir is still honored
• set / verify / status still refuse the same config
• unparseable YAML: clear names the exact path it looked at, warns when nothing was there, and --state-dir still resolves exactly
• flag typos (--hash bogus) are still refused on a valid config

How it caches

The hook wraps the script in go run ./cmd/markgate run hook-e2e-pre-merge -- bash .claude/scripts/e2e.sh, so:

• First run after a source change: full ~10–15s execution (build + every assertion, the script does its own go build to the temp dir).
• Repeat run with no source change: ~0.1s skip, marker hit.

The marker lives at .git/markgate/hook-e2e-pre-merge.json (default state-dir, git-ignored). Default git-tree hash means any source change invalidates it.

Running it

bash .claude/scripts/e2e.sh             # full run, one PASS line per assertion + summary
QUIET=1 bash .claude/scripts/e2e.sh     # only print section headers + failures

Exit code = number of failed assertions (0 on all-pass).

When this skill is NOT enough

• The script does not exercise marker-file atomicity under concurrent writes — that's covered by internal/state unit tests, and re-testing it from a black-box harness is unreliable.
• It does not run make lint or go test ./.... Those remain the static / unit gates and are independent. Run them separately when introducing new code (the audit-before-done skill is the canonical pre-push checklist).
• It uses a temp sandbox under /tmp and does not exercise the user's actual .markgate.yml or shared state-dir. If you changed sharing / multi-host behavior, smoke that path manually too.

Adding a new assertion

When a new feature lands in the markgate CLI:

1. Add a section to .claude/scripts/e2e.sh (mirror the existing cyan "=== feature ===" + new_repo + assert_* pattern).
2. Run bash .claude/scripts/e2e.sh once and confirm the new assertions pass.
3. Update the "what it covers" list in this SKILL.md so the description stays honest.