README: state the project's scope and its departures from GNU shadow (#296)

Until now the repository had no written scope: no statement of which tools
it means to ship, which it will not, or why a given behaviour differs from
the GNU tool. Every other project in the organisation at this stage has one,
and the questions it answers are the ones a reviewer, a packager and a
contributor each ask first.

The denominator is the binary set of the upstream suite as the distributions
package it -- established from package metadata and man pages, never from
the upstream source, which this project does not read. Debian and Fedora do
not ship the same set; the 22 they agree on are all implemented, and the
remainder is listed with its status. Debian's packaging scripts and Fedora's
adduser symlink are named as out of scope so nobody files them as missing.

Three tools the GNU suite ships are provided elsewhere in the organisation
and are deliberately not duplicated: nologin in uutils/util-linux, su in
sudo-rs, and login here -- uutils/login was archived pointing at this
repository, so login is inherited rather than optional. This is the rule
procps and util-linux already apply between themselves.

The departures from GNU are collected in one place with the rule behind
them: differences are bugs, except where reproducing a behaviour would
quietly weaken the system, and then the refusal is loud, names the
alternative, and is documented in the man page. Each entry already exists
in a man page; the README now says they are one policy and not five
accidents.

Author: pierre-warnier

CHANGELOG.md

@@ -64,6 +64,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- The README states the project's scope: the binary set of the upstream
+  suite as the distributions package it, established from package metadata and
+  man pages rather than source; which tools remain; and the three boundaries
+  within the organisation -- `login` is this project's, `nologin` is
+  `uutils/util-linux`'s, `su` is `sudo-rs`'s. It also lists every place this
+  project deliberately departs from GNU shadow, with the rule behind them
+
 - `shadow_core::process::spawn_with_signals_unblocked` starts a child with a
   clean signal mask. A tool that blocks `SIGINT` while it holds a lock passes
   that mask to every child, and an editor started under it could not be

README.md

@@ -78,6 +78,53 @@ default-in-Ubuntu in under 3 years. This project follows that playbook.
 | `grpconv` | **Implemented.** `pwconv` for group and gshadow. |
 | `grpunconv` | **Implemented.** `pwunconv` for group and gshadow. |
 
+## Scope
+
+The target is the set of binaries the upstream shadow suite ships, as the
+distributions package it. That set was established from package metadata and
+man pages, never from the upstream source: this project is a clean-room
+reimplementation and reads no GPL code.
+
+Debian and Fedora do not ship the same set. The 22 tools they agree on are all
+implemented. Of the rest:
+
+| tool | status |
+|---|---|
+| `login` | in scope, not yet shipped. Debian 13 and Ubuntu 25.10 take `login` from util-linux, but every release in service today — Ubuntu 20.04, 22.04 and 24.04, Debian 12 — ships shadow's, and `uutils/login` was archived pointing here. The target is the option set the two implementations share |
+| `expiry`, `groupmems` | Debian's tail; in scope, not yet shipped. `faillog` and `lastlog` left the Debian package with 13 and are not planned |
+| `newuidmap`, `newgidmap` | Fedora's pair, the basis of rootless containers; in scope, not yet shipped |
+| `shadowconfig`, `cpgr`, `cppw`, `adduser` | Debian packaging scripts and a Fedora symlink, not upstream tools; out of scope |
+
+Three tools that the GNU suite ships are provided by other projects in this
+organisation, and are deliberately not duplicated here — the same rule
+`uutils/procps` and `uutils/util-linux` apply between themselves:
+
+- `nologin` is in [`uutils/util-linux`](https://github.com/uutils/util-linux). Debian has taken it from util-linux for years; shadow's copy is not shipped.
+- `su` is in [`sudo-rs`](https://github.com/trifectatechfoundation/sudo-rs).
+- `login` is here, per the table above: on the installed base it is shadow's tool, whatever the newest releases do.
+
+### Where this differs from GNU shadow
+
+Differences with the GNU tools are treated as bugs, with one class of
+exceptions: a behaviour that quietly weakens the system is refused rather than
+reproduced. Each refusal is loud, names the alternative, and is documented in
+the tool's man page under *Differences from GNU shadow*. The pattern so far:
+
+- Insecure hashing schemes (`-m`, `-c MD5`, `-c DES`) and unhashed storage
+  (`-c NONE`) are refused by `chpasswd`, `chgpasswd` and `newusers`.
+- An empty password in plaintext mode is refused: hashing `""` yields a hash a
+  bare Enter matches, which is an account anyone can enter, not one with no
+  password.
+- `vipw` and `vigr` parse the edited file before installing it — GNU installs
+  whatever the editor saved — and keep the edit when they refuse it.
+- `newusers` refuses a group name that does not exist rather than leaving the
+  account pointing at a GID that is not there.
+- `newgrp` and `sg` prompt for a password whether or not the group has one, so
+  the presence of a prompt no longer reveals which groups are worth attacking.
+
+Nothing falls back silently. Where the GNU tool and this one disagree on a
+result, the exit code says so.
+
 ## Building
 
 ### Requirements