[TristanKruse]

Summary

Closes #72. First bounded CLI delivery milestone from #66; the broader roadmap stays open.

• Ship archunit init, check, explain, --help, and --version as a packaged gem executable without replacing RSpec/Minitest.
• Declare uniquely named Checkable rules in trusted .archunit.rb configuration, with project-rooted file/layer/slice/metric helpers.
• Reuse existing violation wording/rationale and preserve the import-only default plus explicit expanded-mode opt-in.
• Define exit 0 = successful command / all checks pass; 1 = violations; 2 = argument, configuration, or technical analysis errors. Provide text and schema-v1 JSON, including structured parser diagnostics and honest partial/error results.
• Make init exclusive/non-destructive; explain loads trusted configuration but does not run checks and never labels configured rules as passing.
• Add CLI subprocess acceptance to each compatibility job and to the isolated installed-package job, plus unit/packaging/workflow tests and README/API documentation.
• Prepare an additive unreleased 1.1.0 development version. Published 1.0.0 and its tag are untouched; this PR does not publish or authorize publication.

Trust and milestone limits

Configuration is executable Ruby, not a sandbox. The tool does not automatically execute target application source, Gemfiles, or gemspecs; custom configuration and a caller's own Bundler invocation keep their normal Ruby semantics. Use your own trusted config when analyzing an untrusted repository. JSON-mode configuration should not write to stdout.

explain lists names, rationale, selected project, and analysis settings. It is not a semantic dependency trace or a focused-path report. Baselines/stale entries, semantic call/protocol rules, presets, and larger Rails performance work remain separate roadmap deliveries.

Validation

• COVERAGE=true bundle exec rake: 667 examples, zero failures, nine native-symlink skips on this Windows account; Linux/native-capable Windows CI exercises the symlink cases. Runtime-library coverage keeps the unchanged 98% / 90% gates; all 278 Ruby files lint-clean.
• bundle exec rake docs: 185 generated pages with API/internal-link validation.
• Fresh security scan: 1,284 advisories, no findings, vulnerable-fixture scanner-health check passed.
• All six pinned Rack/Rake/RSpec corpus + analysis-mode graph/rule/cache baselines passed unchanged.
• Strict gem build, fresh isolated local installation, exact installed version/path check, actual Windows command wrapper, CLI subprocess acceptance, and both existing dependency-analysis smoke scripts passed without loading the checkout.
• Development release metadata synchronized; runtime dependencies unchanged. No RubyGems publication or release tag created for 1.1.0.

Review also reproduced and fixed an accidental exit 0 in configuration returning success before any rule check. Ordinary configuration exits are now explicit exit-2 errors, covered in process-isolated acceptance as well as unit tests. This is fail-closed behavior for mistakes, not a sandbox claim about arbitrary trusted Ruby.

Native-capable Windows CI exposed that File::CREAT | File::EXCL alone followed a dangling symlink. Initialization now checks File.lstat before opening, with both a portable pre-open rejection test and the original native symlink test retained. This does not claim to sandbox concurrent hostile filesystem changes.

[TristanKruse]

Final verification — 2026-10-27

Head: e61844831f3c9eb2d39ce870b98610201d898e33.

• All push and PR checks are green, including fresh PR CI, security, and all pinned canaries. The installed-gem CLI acceptance also passed in the Ubuntu package job.
• The originally failing native Windows dangling-symlink regression is retained and now passes. No test was removed or converted into a platform skip to resolve the failure.
• Final full local run: 667 examples, zero failures, nine symlink skips on this non-privileged Windows account. Runtime-library coverage 98.54% line / 91.82% branch; all 278 Ruby files lint-clean; strict build and 185-page documentation validation passed.
• Review reproduced and fixed an accidental configuration exit 0 producing false success, with process-isolated regression coverage. Initialization also rejects an existing filesystem entry before opening on Windows.
• Fresh isolated installation and actual Windows command-wrapper acceptance passed during development; final rebuilt-artifact acceptance is independently exercised in the green CI package job.

Ready for review/merge. This is unreleased 1.1.0 development work: no 1.1.0 publication, tag, or release-workflow dispatch occurred. Published 1.0.0 remains unchanged. The broader #66 roadmap remains open.