chore: project skeleton — module contracts, docs plan, GPLv3

docs/PLAN.md

@@ -0,0 +1,90 @@
+# jmove — Product Plan
+
+## Vision
+
+The `mv` for source code that never breaks imports: fast, safe (dry-run +
+atomic rollback), single static Rust binary — usable by humans in a
+terminal and by AI agents over `--json`, with zero external toolchains.
+
+## Competitive landscape
+
+The closest analog is **refac / ai_refac** (github: jav-ed/ai_refac):
+moves sources and updates imports/paths across the project, aimed at
+AI agents without an IDE.
+
+| | refac/ai_refac | jmove |
+|---|---|---|
+| Languages | TS/JS (ts-morph+Bun), Python (Rope), Rust (rust-analyzer LSP), Go (gopls), Dart, Markdown | TS/JS → Java → Python/Go |
+| Under the hood | spawns external toolchains/LSPs per run | pure Rust, tree-sitter grammars in-process |
+| Dry-run | **none** — writes straight to disk | core feature, unified diff |
+| Atomicity/rollback | not described | rewrite-then-move, rollback on failure |
+| TS limit | 30 files per call | none (index-based) |
+| Go behaviour | moves whole package for any file | per-file moves |
+| Java | not supported, not planned | **open niche — headline feature** |
+| UX | agent-oriented CLI | human UX + first-class `--json` agent mode |
+
+**Conclusion:** the idea is validated, the product is not. jmove wins on
+dry-run, speed (no LSP startup), human UX, single-binary distribution,
+the `split` command (nobody has it) and Java.
+
+## Why Java is the wedge
+
+Java imports are fully-qualified package paths hard-coupled to directory
+layout:
+
+```
+src/com/example/utils/Parser.java
+→ package com.example.utils;           // must change
+→ import com.example.utils.Parser;     // must change in every importer
+→ + physical file move
+```
+
+Three coordinated edits per move; outside IntelliJ nobody automates it.
+In headless/CI/agent contexts there is no IntelliJ. Implementation:
+tree-sitter Java grammar (mature) + directory⇄package convention +
+source-root detection (`src/main/java`, `src/`, ...). This is the feature
+that makes jmove *the* answer for "move a Java file in CI".
+
+## AI-agent design
+
+Existing tools ship a raw `.agents/skills/` folder; we do it properly:
+
+- `--json` on every command. Envelope:
+  `{ "status": "ok" | "dry_run" | "error", "operation": "...", ... }`
+- Stable error codes + actionable hints:
+  `{ "status":"error", "code":"TARGET_EXISTS", "message":"...", "hint":"Use --force or choose another target" }`
+- `mv --dry-run --json` → `{ would_move, would_update, affected_files }`
+  so agents preview → confirm → apply → `check --json`.
+- Exit codes: `0` ok · `1` error · `2` broken imports (from `check`).
+- `docs/SKILL.md` — machine-readable instructions an agent can drop into
+  context: short, no fluff, workflow-first.
+
+## Correctness principles
+
+1. Rewrite **only the specifier string** (byte span), never reformat the
+   statement — no formatter dependency, minimal diffs.
+2. Resolution must match the language's own lookup: TS extension guessing
+   + `index.*`; Java package⇄path; (Phase 2) tsconfig `paths` aliases.
+3. Imports are rewritten **before** the move; any error rolls back all
+   writes. Prefer `git mv` when inside a repo to preserve history.
+4. Beyond imports, warn (don't silently rewrite) about other references:
+   `package.json` exports, jest mocks, `tsconfig` includes, markdown links.
+
+## Phases
+
+- **Phase 1 (MVP)** — as in `todo.md`: TS/JS scan+index, graph, mv with
+  dry-run/atomic apply. Add to MVP: relative-path resolution incl.
+  `index.*` (without it the tool is toy-grade); `check` as the self-test.
+- **Phase 1.5 — Java.** The differentiator, as soon as the TS pipeline is
+  proven. Also: `--json` + SKILL.md ship *with* Java, not after.
+- **Phase 2** — disk index cache (`.jmove/`), incremental reindex,
+  tsconfig paths, rayon parallelism, `--git` integration.
+- **Phase 3** — Python, Go (per-file, unlike refac), `split` command.
+- **Later** — LSP server mode (become the thing refac spawns), watch mode,
+  VS Code wrapper.
+
+## Rules (binding, see todo.md)
+
+KISS · DRY · SOLID · ≤250 lines/file · ≤4 files/folder · fmt+clippy
+`-D warnings` per commit · no dead code, no `#[allow(dead_code)]` ·
+English Javadoc-style comments on all public API.