feat(init): --adopt flow detects + mirrors existing gates (closes #97)

[liam-ai-reality]

Summary

• New klasp init --adopt --mode <inspect|mirror|chain> flow that detects existing quality gates (pre-commit framework, Husky, Lefthook, plain .git/hooks, lint-staged) and proposes a klasp.toml mirroring them
• inspect prints the plan only; mirror writes a round-trip-validated klasp.toml without touching any hook config; chain is explicitly rejected in v1 with a follow-up message pointing at manual integration instructions
• klasp doctor now surfaces missing pre-commit on PATH for adopted checks (issue First-run gate adoption: detect and mirror existing pre-commit/Husky/Lefthook setups #97 AC W5 release workflow: reintroduce x86_64-apple-darwin (macos-13) for tag-push artefact builds #9)

Acceptance criteria coverage

All 9 AC items from #97 covered with integration tests in klasp/tests/init_adopt.rs:

• --mode inspect prints plan, writes nothing
• --mode mirror writes klasp.toml without modifying user config
• mirror never touches .git/hooks, .husky/, lefthook.yml, .pre-commit-config.yaml
• --mode chain rejected with explanatory message (exit 2)
• pre-commit detector emits type = "pre_commit"
• Husky detector picks pkg-manager-aware lint-staged command via lockfile sniff
• Lefthook detector emits per-run: shell checks
• plain .git/hooks never overwritten by default
• klasp doctor surfaces missing pre-commit on PATH

Architecture

• klasp/src/adopt/plan.rs — shared AdoptionPlan / DetectedGate API
• klasp/src/adopt/detect_*.rs — one detector per gate type, all returning io::Result<Vec<DetectedGate>>
• klasp/src/adopt/render.rs — plan formatter (matches issue's example output)
• klasp/src/adopt/writer.rs — atomic klasp.toml generator with round-trip parse validation
• klasp/src/adopt/mode.rs — chain-mode rejection message
• docs/adopt.md — user-facing doc

Test plan

• cargo build --workspace clean (4 dead-code warnings only — ChainSupport::AutoSafe and GateDetector trait reserved for chain-mode future work)
• cargo test --workspace: 647 passed, 6 ignored, 0 failed
• 10 integration tests in init_adopt.rs cover all ACs
• ~70 unit tests across detectors, render, writer, mode

🤖 Generated with Claude Code

[liam-ai-reality]

Code review

Summary

PR #101 adds klasp init --adopt --mode <inspect|mirror|chain> (closes #97). 12 new files under klasp/src/adopt/ (Plan API + 5 detectors + render + writer + mode + fs_util), 10 integration tests in klasp/tests/init_adopt.rs, doctor extended for pre-commit PATH coverage, docs/adopt.md user doc.

After the simplify pass (refactor(adopt): apply simplify pass) the diff is tight: typed TriggerKind / HookStage enums, no dead Confidence field, atomic_write_text shared via crate::fs_util, TOCTOU-free reads. Workspace builds clean (1 dead-code warning on planned GateType::Tooling variant). 442 tests pass.

Reviewed against /Users/liammccarthy/Projects/CLAUDE.md. 4 reviewers (2× CLAUDE.md compliance + 2× bugs/security) + 7 validation passes. 5 raised findings rejected as INVALID (theoretical / dead-code / repo-wide convention / tested-and-deliberate).

Critical issues

#	File	Issue
—	—	None. Round-trip parse in writer.rs:39-47 gates filesystem writes. No path-traversal vector (every repo_root.join(...) uses a hardcoded literal). No shell-injection elevation (writer mirrors what already runs via sh -c; an attacker editing .husky/pre-commit already has commit-time code execution).

Suggestions

#	File	Issue	Suggested fix
1	klasp/src/adopt/detect_husky.rs	first_substantive_command returns only the FIRST substantive line of a Husky hook. Realistic hooks like pnpm lint\npnpm test get silently mirrored as just pnpm lint — no warning emitted. Drifts from the PR's "agents see the same checks your humans hit" goal.	Either (a) emit one ProposedCheck per substantive line, or (b) when >1 substantive line is present, emit a warning ("husky hook contains N commands; only first mirrored — review manually"). Add a multi-command fixture to the integration tests.
2	klasp/src/adopt/detect_plain_hooks.rs	MANAGED_MARKERS includes bare substrings "husky" and "lefthook". False-positive: a plain user hook with a comment like # we used to use husky defers and produces no finding. False-attribution: a hook invoking /opt/husky-tool/bin/run gets wrongly skipped.	Tighten to husky.sh (Husky's actual generated source line) and require lefthook run / line-leading anchoring. Keep .husky/ (already specific) and # Generated by pre-commit (already specific).

What looks good

• Typed Plan API after simplify pass — TriggerKind/HookStage enums, no stringly-typed slots in the public surface.
• Atomic write helper extracted to klasp/src/fs_util.rs and shared between init scaffold and adopt writer (no copy-paste).
• Round-trip ConfigV1::parse validation in writer.rs:42-47 BEFORE filesystem write — generated TOML is provably parseable or the operation aborts with a clean InvalidData error.
• Mirror mode tested to be non-destructive: mirror_pre_commit_writes_klasp_toml and mirror_plain_git_hook_does_NOT_overwrite_hook both byte-compare hook configs pre/post-run.
• --force semantics tested both ways (mirror_existing_klasp_toml_without_force_errors + _with_force_overwrites).
• Chain mode rejection tested with explicit exit-code-2 assertion (chain_mode_rejects_with_explanatory_message); 2 is consistent with klasp's existing convention (klasp/src/cmd/gate.rs:48 uses 2 for Outcome::Block), not a clap usage-error collision.
• doctor.rs surfaces missing pre-commit binary on PATH for adopted checks (AC W5 release workflow: reintroduce x86_64-apple-darwin (macos-13) for tag-push artefact builds #9).

Verdict

🟡 OK to merge with follow-ups filed. Both suggestions are correctness gaps in detector edge cases, not blockers — mirror mode runs ALONGSIDE the human gate, so silent under-mirroring degrades to "klasp covers a subset of human gate checks" rather than producing wrong output. File two follow-up issues for the husky multi-line and managed-marker tightening; merge this PR; address in a follow-up that can carry tests for the realistic-input cases neither detector currently exercises.

[liam-ai-reality]

Review remediation

Both code-review suggestions addressed inline. No follow-up issues filed — fixed in this PR.

#	Suggestion	Resolution	Commit
1	detect_husky.rs::first_substantive_command silently dropped multi-line hook bodies	Renamed to substantive_commands returning Vec<String>; emits one ProposedCheck per substantive line (each gets per-command name detection: lint-staged / test / lint / fallback). Multi-command unit + integration tests added.	026c2c4
2	detect_plain_hooks.rs::MANAGED_MARKERS substrings "husky" / "lefthook" too loose	Tightened to "husky.sh" (Husky's actual generated source line) + "lefthook run" (Lefthook's actual generator command). Existing .husky/ and # Generated by pre-commit retained. Added regression tests for user-comment false-positive and husky-named-tool false-attribution cases.	026c2c4

CI fmt + clippy enforcement that the local cargo build did not catch was patched in 10c66f1 (cargo fmt --all across adopt module + #[allow(dead_code)] on the planned GateType::Tooling variant).

	Status
Critical findings deferred	none
Suggestions deferred	none
Tests after remediation	451 passed, 1 ignored, 0 failed
Clippy / fmt	clean