docs: README exit codes and CONTRIBUTING platform-skip notes

The README exit-code table understated when exit 1 fires: warning-only
runs with --strict, regressions with --fail-on-regression, and ingest
parse failures all return 1, but the table only mentioned errors and
--strict warnings. The 1-over-3 priority rule was only in CLAUDE.md.
Surfaces both in the public README.

CONTRIBUTING now documents which tests skip on Windows and why, so the
next maintainer can read the test suite output without having to grep
for skipif marks.

Author: Brad Kinnard

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- README exit-codes table expanded: the `1` row now lists every escalation path (errors, warning-only run with `--strict`, regression with `--fail-on-regression`, ingest parse failure) and includes the `1` > `3` priority note that was previously only in `.github/CLAUDE.md`.
+- `CONTRIBUTING.md` documents platform-skipped tests so the next maintainer knows why pass/skip ratios differ across the CI matrix without having to grep the suite.
 - CLI mutual-exclusion block refactored to a single `_PAIRWISE_CONFLICTS` table walked by one loop, replacing nine hand-written `if ... and ...:` branches. Exit code 2 and stderr messages are unchanged.
 - `--history` now fans out across every target path instead of silently writing only when exactly one path is supplied. Each SKILL.md still gets its own per-skill `.skillcheck-history.json` next to it. `--fail-on-regression` escalates to exit 1 when any target regresses.
 - `--show-history` with multiple paths still reads only the first path's ledger (each skill has its own), but the extra paths now produce a stderr warning instead of being silently dropped.

CONTRIBUTING.md

@@ -1,5 +1,24 @@
 # Contributing
 
+## Testing
+
+Run the suite from the repo root after installing the dev extras:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+The README test-count line (`N tests cover ...`) is asserted by `tests/test_readme_test_count_claim.py`; when you add or remove tests, bump the README count in the same commit.
+
+### Platform-skipped tests
+
+A handful of tests skip on Windows because the underlying OS feature is unavailable or behaves differently. `pytest --collect-only` still counts them, so the README's `N tests cover ...` number is the same on every platform; only the pass/skip ratio shifts.
+
+- `tests/test_references.py`: the two `os.symlink`-based tests use the module-level `_skip_symlink = pytest.mark.skipif(sys.platform == "win32", ...)` mark. `os.symlink` on Windows requires developer mode or admin privileges, so the symlink-escape coverage runs on Linux/macOS only.
+- `tests/test_cli_history.py` and `tests/test_history_io.py`: each has one `pytest.mark.skipif(sys.platform == "win32", ...)` test exercising POSIX file-mode permission errors that Windows does not enforce identically.
+- `tests/test_pre_commit.py`: both tests skip wherever the `pre-commit` binary is not installed. CI installs `pre-commit` so they run there; local runs without `pre-commit` show them as skipped.
+
 ## Releasing
 
 Every release pushes two tags pointing to the same commit:

README.md

@@ -96,10 +96,12 @@ The same flow exists for capability graph extraction (`--emit-graph-prompt` / `-
 | Code | Meaning |
 |---|---|
 | `0` | No errors. Warnings alone exit 0 unless `--strict` is set. |
-| `1` | One or more errors, or warnings with `--strict`, or regression with `--fail-on-regression`. |
+| `1` | One or more errors. Also: warnings with `--strict` (the umbrella `--strict-vscode` / `--strict-cursor` only escalate their own diagnostics; the umbrella additionally escalates any warning-only run). Also: `history.skill.regressed` with `--fail-on-regression`. Also: any ingest parse failure. |
 | `2` | Input or argument error (missing path, conflicting flags, malformed input). |
 | `3` | Symbolic checks passed but an ingested critique reported semantic errors. |
 
+When both `1` and `3` would apply, `1` wins so CI consumers see the higher-severity signal.
+
 ## Configuration
 
 Defaults live in a `skillcheck.toml` discovered upward from the validated path. Override per invocation with `--config PATH`. Organization-specific frontmatter keys belong under `[frontmatter] extension_fields`. Override the name reserved-word list with `[frontmatter] reserved_words = ["acme", "internal"]` (an empty array reverts to the defaults).