v0.1 W3: gate runtime + Shell CheckSource + trigger tests

[liam-ai-reality]

Closes #3.

What ships

• klasp/src/cmd/gate.rs — full 7-step gate flow per docs/design.md §6:
  1. KLASP_GATE_SCHEMA env handshake (fail-open on mismatch)
  2. stdin JSON parse (fail-open on parse error)
  3. trigger classify (git commit/git push regex; non-match → exit 0)
  4. config load (fail-open on missing/parse error)
  5. run checks sequentially via SourceRegistry
  6. aggregate via Verdict::merge + policy
  7. exit 2 + structured stderr only on Verdict::Fail; everything else exit 0
• klasp/src/sources/{mod,shell}.rs — SourceRegistry + ShellSource impl. sh -c "<command>" with cwd=repo_root, stdio via reader threads, per-check timeout via Child::try_wait poll loop.
• klasp/src/git.rs — repo-root resolver (CLAUDE_PROJECT_DIR first, then walk up from cwd).
• klasp-core/src/trigger.rs — expanded pattern coverage (;/|/&& chains, subshells, flags) + documented edge-case ignores for git -c x=y commit, bash -c, env-prefix, aliases (deliberate non-goals per §6 threat model).
• klasp/tests/gate_flow.rs — 4-case integration test (no-config / no-trigger-match / pass / fail) spawning klasp gate as a subprocess.
• klasp/tests/protocol_contract.rs + fixtures/klasp-gate-v1.sh — three-way schema cross-check: GATE_SCHEMA_VERSION constant ↔ committed fixture ↔ render_hook_script() output. Bumping the constant fails until both other places agree.

Deferred (verdict_path)

The agent's extract_verdict_path dot-notation utility ships ready-to-wire as pub(crate), but the generic Shell source has no reliable way to parse arbitrary tool output — every check tool emits its own JSON shape. The v0.2 named recipes (fallow, pytest, cargo) will own that schema knowledge per design.md §3.5. Wiring verdict_path on Shell is a one-line config + match change the moment the recipe story lands.

If you'd rather land verdict_path now (as Option<String> on CheckConfig), say the word in review and I'll add it as a follow-up commit on this branch.

Reviewer focus

• Fail-open paths in gate.rs — every error in the gate flow must end with exit 0 + stderr notice, never exit 2. The five branches: missing/invalid env var, stdin parse fail, schema mismatch, missing/invalid config, missing check binary. Verify each.
• Trigger regex — klasp-core/src/trigger.rs::tests covers the documented matches and rejects. The #[ignore] tests document deliberate non-goals; do not remove them.
• run_with_timeout in shell.rs — std-only timeout via reader threads + poll loop. The alternative (wait_with_output) blocks indefinitely; this pattern is necessary, not over-engineering.
• Contract test — both fixture and renderer cross-check against GATE_SCHEMA_VERSION. A future schema bump must update fixture and render_hook_script in lockstep.

Verification

cargo fmt --all -- --check       ✓ clean
cargo clippy --all-targets ...   ✓ clean
cargo test --workspace           ✓ 57 passed, 5 ignored, 0 failed

Test breakdown: 37 unit (klasp-core) + 5 deliberately-ignored + 4 gate_flow + 11 install_claude_code + 3 protocol_contract + 2 snapshot.

🤖 Generated with claude-flow

[liam-ai-reality]

Code review

🟢 Approve — no issues found.

Checked for bugs and CLAUDE.md compliance via two parallel Opus agents (one diff-only, one with file-level context); no high-signal findings against the "compile error / definitely wrong regardless of inputs" bar.

Summary

The PR implements the full klasp gate runtime per docs/design.md §6 + §10, with the fail-open invariant holding across every error branch in klasp/src/cmd/gate.rs. The trigger regex in klasp-core/src/trigger.rs is well-tested with documented deliberate-miss #[ignore] cases. The contract test triangulates GATE_SCHEMA_VERSION across constant ↔ fixture ↔ renderer. The 4-case integration test in klasp/tests/gate_flow.rs spawns the real binary against captured Claude payloads.

Critical issues

None.

Suggestions

#	Severity	Finding	Recommendation
—	—	None at the merge-blocking bar	—

What looks good

• Fail-open semantics consistently applied: every error path in gate.rs returns Outcome::Pass → exit 0, only Verdict::Fail → exit 2.
• Reader-thread + try_wait poll-loop pattern in shell.rs::run_with_timeout is the correct std-only approach (wait_with_output blocks indefinitely).
• protocol_contract.rs three-way cross-check is exactly the contract test design.md §7 calls for.
• .gitignore additions for .claude/ / .claude-flow/ are correct hygiene.
• 57 tests passing, clippy clean, fmt clean.

Security / Performance / Tests

• Security: No command-injection vector found. Agent-supplied tool input is only matched against the trigger regex; shell commands come from klasp.toml (repo-owner trust boundary, by design).
• Performance: Sequential check execution is the v0.1 design; rayon-based parallelism deferred to v0.2.5 per roadmap.
• Tests: The bug-review agent flagged that no integration test exercises the source-level runtime error fail-open path (e.g., ShellSource::run returning Err during a real klasp gate invocation). The invariant holds per code reading, but it's untested end-to-end. Worth a follow-up issue rather than blocking this PR — the unit-level coverage is solid and gate.rs's error branches are clearly fail-open by inspection.

Follow-up observations (non-blocking, candidates for a "Follow-ups from PR #11" issue)

These are below the merge-blocking bar but worth tracking:

1. Child process cleanup on try_wait error. When child.try_wait() itself returns Err, run_with_timeout returns immediately without child.kill() + child.wait(). The dropped Child doesn't kill or reap on drop. try_wait errors are kernel-rare, but on every such occurrence the gate orphans a process and detaches two reader threads.
2. Reader-thread joins on timeout. JoinHandles are dropped (not joined) on the timeout path. The threads will exit when the killed child's pipes close, so this is transient — but a let _ = handle.join() before returning would tidy it.
3. Test coverage gap. Add an integration test that triggers a real source runtime error (e.g., timeout-tripping check) and asserts exit 0 + stderr notice. Confirms the gate.rs handler at line 159-166 actually fires.
4. git::find_repo_root_from_cwd name vs behaviour. When CLAUDE_PROJECT_DIR is unset, the function relies on inheriting cwd from the parent process. Function name is honest but the contract is "if the env var doesn't resolve, we trust the parent's cwd" — worth a doc-comment line.
5. gate_flow.rs::missing_klasp_toml_fails_open weak assertion. Asserts only the exit code; doesn't check that the klasp-gate: stderr notice was emitted. A future refactor that silently passes (no notice) would still satisfy the test.
6. gate_flow.rs::non_git_command_skips_checks_and_returns_0 — the inline klasp.toml omits policy = "any_fail" from [gate]. If policy is required without a default, the test still passes (exit 0 via fail-open) but for a different reason than the test's intent. Either add the field or document that this test exercises the trigger short-circuit specifically and the config doesn't matter.

Verdict

🟢 Approve. Ship it. File the six follow-ups above as a single issue per Step 10 of the agentic-flow protocol if you want them tracked; none are merge blockers.

CI status: pending (5/6 last I checked); merge after green per Step 11 gating.

🤖 Generated by agentic-flow Step 06 (/code-review:code-review) + Step 07 (auto-post)

[liam-ai-reality]

Review remediation + simplify pass

Findings → fixes

Finding	Resolution
🔴 Critical issues	None — no on-branch fixes needed.
🟡 Important to fix on branch	None — no on-branch fixes needed.
🔵 Polish / observability / test coverage	All 6 below-blocker observations deferred to follow-up issue #12.

No fix commits were added during review remediation because the review was 🟢 Approve at the merge-blocking bar.

/simplify pass

Skipped. Step 09's prerequisite (review fixes applied and pushed) wasn't met — no fixes were applied. The implementer's brief in step 05 explicitly enforced no-over-engineering rules (file size <500 lines, no async runtime, fail-open everywhere), and the diff inspection during code review surfaced no bloat candidates.

Verification

• cargo fmt --all -- --check ✓
• cargo clippy --all-targets --workspace -- -D warnings ✓
• cargo test --workspace ✓ — 57 tests passed, 5 deliberately ignored, 0 failed
  • 37 unit tests (klasp-core)
  • 4 integration tests (gate_flow.rs)
  • 11 integration tests (install_claude_code.rs — W2)
  • 3 contract tests (protocol_contract.rs)
  • 2 snapshot tests (klasp-agents-claude)
• CI matrix: ✓ macos-14 · ✓ ubuntu-latest · ✓ windows-latest · ✓ npm dry-run · ✓ pypi build + twine check · ✓ fmt + clippy

Deferred follow-ups

• Follow-ups from PR #11 review (W3 gate runtime) #12 — Follow-ups from PR v0.1 W3: gate runtime + Shell CheckSource + trigger tests #11 review (W3 gate runtime)
  • Do-next: source-runtime-error fail-open integration test; child-process cleanup on try_wait error
  • Medium: reader-thread join on timeout; weaker assertions in 2 gate_flow tests
  • Low: doc comment on git::find_repo_root_from_cwd resolution order

Step 11 gate

Per agentic-flow Step 11 prerequisites:

• ✓ CI green (6/6 checks)
• ✓ Step 07 review comment posted
• ✓ Step 10 remediation comment posted (this one)
• ✓ No deferred Critical findings (Follow-ups from PR #11 review (W3 gate runtime) #12 is all 🔵 polish)

Merging now via gh pr merge --squash --delete-branch.

🤖 Generated by agentic-flow Step 10 phase 2