[v0.1 W4] klasp doctor + Windows audit + cross-platform CI

[liam-ai-reality]

Week 4 of v0.1 implementation. References: design.md §5, §10, §14.

• klasp/src/cmd/doctor.rs — checks: config exists + parses, hook installed + has correct KLASP_GATE_SCHEMA, settings.json contains klasp entry, each check command resolves on PATH
• klasp/src/cmd/init.rs — write example klasp.toml with --force flag
• --dry-run flag wiring on install/uninstall (returns rendered script preview without writing files)
• Windows path handling audit: shim runs under Git for Windows bash; settings.json paths use forward slashes; Rust binary handles platform paths internally; chmod 0o755 no-op on Windows
• .github/workflows/test.yml matrix on the 5 target platforms (darwin-arm64, darwin-x64, linux-x64-gnu, linux-arm64-gnu, win-x64): green cargo check + cargo test + cargo fmt --check + cargo clippy

[liam-ai-reality]

W4 build plan (Step 03/04 of agentic-flow)

Splitting this into 3 logically-independent chunks so they can be implemented in parallel. File scopes are disjoint between chunks and disjoint from #3 (gate runtime), which is mid-rebase.

Decisions locked in

Question	Decision
CI matrix	Add linux-arm64-gnu only (4 platforms). darwin-x64 stays deferred to W5 release workflow per #9. The issue body's "5 target platforms" line is updated implicitly by this.
klasp doctor exit codes	0 = healthy, 1 = any FAIL. WARN does not fail. Stderr carries aggregate; stdout has per-check OK/WARN/FAIL <msg> lines.
klasp doctor hook check	Byte-equality re-render diff — re-render via surface.render_hook_script(InstallContext{schema_version: GATE_SCHEMA_VERSION,..}) and diff against on-disk hook file. Catches schema drift.
klasp init when klasp.toml exists	Error and exit 1: klasp.toml already exists at <path>; pass --force to overwrite.
DoctorArgs flags	Empty for v0.1. No --agent, no --strict. Defer to v0.2 when there are multiple surfaces.

Chunk A — klasp doctor

Files: klasp/src/cmd/doctor.rs (replace stub), klasp/tests/doctor.rs (new), klasp/Cargo.toml (add which, promote serde_json to [dependencies]).

Checks (run all, aggregate):

1. ConfigV1::load(&repo_root) parses (FAIL on missing/version mismatch/parse error).
2. Per surface where surface.detect(): hook file byte-equality vs re-rendered template (FAIL on missing or schema drift).
3. Per surface where surface.detect(): .claude/settings.json walks to hooks.PreToolUse[*]{matcher=="Bash"}.hooks[*]{command==ClaudeCodeSurface::HOOK_COMMAND} (FAIL on missing).
4. Per config.checks: extract_argv0 (skips KEY=VAL env-prefix tokens) → which::which (WARN only — missing dev tools shouldn't fail doctor).

Edge cases: repo not under git → exit 1 immediately. Config missing → checks 2-3 still run. Zero detected surfaces → WARN, not FAIL.

Tests (10): healthy, missing config, hook missing, schema drift, settings entry missing, no surfaces detected, not-a-git-repo, missing PATH command, env-var-prefixed command, output prefix invariant.

Chunk B — klasp init + --force

Files: klasp/src/cmd/init.rs (replace stub), klasp/src/cli.rs (add force: bool to InitArgs), klasp/tests/init.rs (new), klasp/Cargo.toml (move tempfile from dev-deps to [dependencies]).

Behaviour: resolve repo root via crate::cmd::install::resolve_repo_root (already pub(crate)), atomic-write EXAMPLE_TOML to repo_root/klasp.toml. Refuse if exists without --force.

EXAMPLE_TOML body (every uncommented field validated against ConfigV1::parse):
```toml

klasp.toml — generated by `klasp init`

Docs: https://github.com/klasp-dev/klasp

Verify this install: run `klasp doctor`

version = 1

[gate]
agents = ["claude_code"]
policy = "any_fail"

[[checks]]

name = "lint"

triggers = [{ on = ["commit"] }]

timeout_secs = 60

[checks.source]

type = "shell"

command = "ruff check ." # or: cargo clippy --all-targets -- -D warnings

[[checks]]

name = "test"

triggers = [{ on = ["commit"] }]

[checks.source]

type = "shell"

command = "pytest -q" # or: cargo test --workspace

```

Tests (5): creates klasp.toml; output parses via ConfigV1::from_file; refuses without --force; --force overwrites; not-a-git-repo errors.

Chunk C — Windows audit + CI matrix

Files: klasp-agents-claude/src/surface.rs (comments only — module docstring + the #[cfg(not(unix))] block in apply_mode), .github/workflows/ci.yml (add 1 matrix entry).

Windows audit findings (no logic changes):

• current_mode / apply_mode are #[cfg(unix)]-gated; on Windows both are no-ops, which is correct.
• Hook script uses #!/usr/bin/env bash — needs Git for Windows' bash.exe on PATH (default Git for Windows install satisfies this).
• All Path::join calls use std::path::Path and produce platform-correct separators.
• ${CLAUDE_PROJECT_DIR} placeholder in HOOK_COMMAND keeps settings.json portable.

CI yaml diff (in cross-platform-build.matrix.target):
```yaml

• • { os: ubuntu-24.04-arm, triple: aarch64-unknown-linux-gnu }
    ```
    The check job (cargo check + fmt + clippy + test on ubuntu-latest x64) is not expanded — those checks are arch-independent for the codebase as it stands. Build matrix on arm64 catches any genuine target-specific issues at PR time.

Coordination

• Both A and B touch klasp/Cargo.toml. A adds which, A promotes serde_json from dev-deps → deps; B promotes tempfile from dev-deps → deps. Three deterministic, non-overlapping line edits.
• Avoid: anything in klasp/src/cmd/gate.rs, klasp/src/sources/, klasp/src/git.rs, klasp/tests/{gate_flow,protocol_contract}.rs, klasp-core/src/trigger.rs — those are W3's ([v0.1 W3] klasp gate runtime + trigger + Shell CheckSource #3) territory.

Risks

1. ubuntu-24.04-arm runner availability on a public OSS repo (klasp-dev/klasp is public — should be fine; fallback would be cross on ubuntu-latest).
2. tempfile::NamedTempFile::persist on Windows — same-volume is required; new_in(parent_dir) guarantees it (mirrors W2's surface.rs::atomic_write).
3. Settings JSON walk (Chunk A check 3) hardcodes Claude Code's current schema. Same assumption as W2's settings::merge_hook_entry; both update together if Claude Code's schema changes.
4. Hook byte-equality on Windows: hook is written with \\n newlines and read back through fs::read_to_string; comparison stays correct (Rust does not normalise line endings on read).
5. which::which on Windows finds .cmd/.bat wrappers — desired behaviour.

Verification (end-to-end)

```
cargo check --workspace && cargo test --workspace && cargo fmt --check && cargo clippy --workspace -- -D warnings
klasp init # writes example
klasp init --force # overwrites
klasp install --dry-run # already works on main; sanity-check it still does
klasp doctor # exit 0 in fresh post-install state
```
CI matrix green on macos-arm64, linux-x64, windows-x64, linux-arm64.

—

Generated by /feature-dev:feature-dev. Implementation dispatching now in 3 parallel agents.