Complete the end-to-end CLI parity audit

docs/cli-parity.md

@@ -0,0 +1,90 @@
+# CLI parity and executable audit
+
+The `ironstorage` binary is a presentation and interaction adapter over
+`crates/storage`. The compatibility target is password-store 1.7.4 at
+`1078f2514d579178d5df7042c6a790e9c9b731ad` and pass-otp 1.2.0 at
+`1e9d10ca75ae1a8672a7f192809713463657778e`. The checked-in `behavior.toml`
+catalog contains 108 original, data-only cases. A contract test submits every
+case to the Rust parser, while domain and CLI workflow tests exercise the
+corresponding storage effects.
+
+## Command matrix
+
+| Upstream surface | IronStorage command | Rust owner and evidence |
+| --- | --- | --- |
+| default/list, `show`, `ls`, `list` | same, including implicit entry dispatch, line selection, clipboard and QR | `read`, `presentation`; command-contract, read-domain, presentation and CLI tests |
+| `find`, `search`, `grep` | same aliases; supported grep flags are explicit | `read`; compatibility catalog, read-domain and complete CLI workflow tests |
+| `init -p/--path` | same, including removal through an empty identity | `recipient`; recipient-policy and complete CLI workflow tests |
+| `insert`, `add` | hidden-confirmed, echoed and multiline input, force and confirmation | `write`; write-domain and complete CLI workflow tests |
+| `edit` | same logical edit session through the configured/default editor | `write`; editor-adapter, write-domain and complete CLI workflow tests |
+| `generate` | length, no-symbols, force, in-place, clipboard and QR | `generate`; generation and CLI presentation tests |
+| `rm`, `remove`, `delete` | force and recursive behavior | `mutation`; tree-mutation and complete CLI workflow tests |
+| `mv`, `rename`, `cp`, `copy` | same aliases, destination and overwrite behavior | `mutation`; tree-mutation and complete CLI workflow tests |
+| `git` | `init`, `status`, `log`, helper-free decrypted `diff`, `add`, `commit`, `remote`, safe local `config`, `fetch`, `pull`, `push`, `sync` | `git`; embedded Git, smart-HTTP and complete CLI workflow tests |
+| pass-otp default/code/show | `otp ENTRY`, `otp code`, `otp show`, clipboard | `otp`; RFC, fixture and CLI tests |
+| pass-otp insert/add/append | URI or secret input and issuer/account derivation | `otp`; fixture, transaction and CLI tests |
+| pass-otp uri/validate/help/version | terminal, clipboard, QR and the pinned upstream version string | `otp`, `presentation`, `command`; fixture and CLI tests |
+| help/version | command, `-h`/`--help`, `-V`/`--version` forms | `command`; contract and stream/exit-code tests |
+
+`ironstorage completion SHELL` generates Bash, Elvish, Fish, PowerShell or Zsh
+completion source in process with `clap_complete`. It writes the script to
+standard output and neither searches for nor invokes a shell or completion
+helper.
+
+## Deliberate boundaries
+
+Upstream extension discovery executes files named `pass-*`. IronStorage does
+not execute extensions; the first-party OTP surface is built in and typed.
+Upstream `pass git` forwards arbitrary arguments to the Git executable.
+IronStorage instead exposes the documented embedded workflows in the matrix.
+Arbitrary passthrough such as `rebase`, `reflog`, hooks, filters, credential
+helpers and helper transports is rejected. This is the only compatibility gap
+in the first-party command surface and follows directly from the no-process
+rule.
+
+The sole runtime process boundary is `apps/cli/src/editor.rs`. It launches the
+resolved editor program directly with parsed arguments and the private edit
+file path; it never invokes a shell. A missing configured/default editor is a
+typed configuration error printed on standard error, the entry is unchanged,
+and the command fails. Editor failure, cancellation, oversized output and
+cleanup failure are likewise typed and leave no committed mutation.
+
+All prompts and errors use standard error. Trees, plaintext explicitly
+requested for terminal display, Git reports, help, versions and completion
+scripts use standard output. Clipboard and QR paths do not copy their secret
+payload back to standard output. Parse and ordinary operation errors return 1,
+configuration errors 78, unavailable operating-system services 69, and
+success returns 0.
+
+## Compatibility and security evidence
+
+The compatibility fixtures contain GnuPG-produced armored and binary keys,
+GPG-encrypted entries, root/nested/multiple/signed `.gpg-id` policies,
+pass-otp URIs, and valid loose-object Git repositories. Tests independently
+decrypt and authenticate every entry, verify recipient signatures and Git
+objects, round-trip OTP URIs, and exercise automatic commits. No compatibility
+test requires an upstream executable at runtime.
+
+The executable audit checks project Rust sources for process construction and
+permits it only in the editor adapter. Every project crate forbids unsafe Rust.
+Git repository configuration rejects executable helpers and all non-HTTPS,
+credential-bearing or rewritten remote forms before transport. Error and debug
+models redact secret bytes; CLI presentation tests assert clipboard, QR, OTP
+and generated values do not appear on unintended streams.
+
+The activated dependency graph was reviewed with `cargo tree -e features` and
+`cargo metadata --locked`. Gix default features are disabled and only the
+embedded index, merge, revision, tree editing and Rustls smart-HTTP features
+are selected. Platform secret-store implementations may compile operating-
+system IPC/runtime support, but IronStorage never calls dependency APIs that
+spawn a helper. Direct dependency licenses and the remaining project-license
+release decision are recorded in `DEPENDENCIES.md`.
+
+Run the executable gate from the workspace root:
+
+```sh
+cargo fmt --all -- --check
+RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+```