feat(pdftract-4sky1): implement doctor exit code policy

- Add exit code policy to doctor command help text
- Update --exit-on-fail flag help to clarify default behavior
- Add code comment explaining why --exit-on-fail is a no-op

Exit codes per plan section 6.10:
- Exit 0: all checks OK or WARN (no FAIL)
- Exit 1: at least one check is FAIL
- Exit 2: CLI parse error (clap default)

Closes: pdftract-4sky1
Co-Authored-By: Claude Code <noreply@anthropic.com>

.needle-predispatch-sha

@@ -1 +1 @@
-14a9408a31d7444af4127464e86bea2e186c3f87
+e7c2b64c22432585a38464e4d2f7bd54fab854f8

crates/pdftract-cli/src/doctor/mod.rs

@@ -184,7 +184,13 @@ pub fn run(opts: DoctorOptions) -> Result<()> {
         })?;
     }
 
-    // Determine exit code
+    // Determine exit code per plan section 6.10 line 2520-2521:
+    // - Exit 0: all checks OK or WARN (no FAIL)
+    // - Exit 1: at least one check is FAIL
+    // - Exit 2: CLI parse error (clap default, unreachable here)
+    // Note: opts.exit_on_fail is unused in the computation because the default policy
+    // already exits 1 on any FAIL. The flag is retained for CI script readability and
+    // forward-compatibility (future --warn-as-fail or --no-exit-on-fall would invert).
     let has_fail = results.iter().any(|r| r.status == CheckStatus::Fail);
     if has_fail {
         std::process::exit(1);

crates/pdftract-cli/src/main.rs

@@ -170,6 +170,9 @@ enum Commands {
         root: Option<PathBuf>,
     },
     /// Check environment health and dependencies
+    ///
+    /// Exit code policy: exits 0 if no checks FAIL (WARN does not affect exit code);
+    /// exits 1 if any check FAILs; exits 2 on argument parse errors.
     Doctor {
         /// Print compiled features and exit
         #[arg(long)]
@@ -183,7 +186,10 @@ enum Commands {
         #[arg(long)]
         no_color: bool,
 
-        /// Exit with code 1 if any check reports FAIL
+        /// Explicit form of the default policy (exit 1 if any check FAILs).
+        ///
+        /// This flag is the default behavior and is provided for CI script
+        /// readability. WARN does not affect exit code regardless of this flag.
         #[arg(long)]
         exit_on_fail: bool,
 

notes/pdftract-4sky1.md

@@ -0,0 +1,35 @@
+# pdftract-4sky1: Exit code policy implementation
+
+## Summary
+Implemented the exit code policy for pdftract doctor per plan section 6.10 lines 2520-2521.
+
+## Changes made
+
+### 1. Updated doctor command help text (`crates/pdftract-cli/src/main.rs`)
+- Added exit code policy documentation to the doctor command description
+- Updated `--exit-on-fail` flag help text to clarify it's the default behavior and provided for CI script readability
+
+### 2. Added code comment (`crates/pdftract-cli/src/doctor/mod.rs`)
+- Added explanatory comment about the exit code policy and why `--exit-on-fail` is a no-op (default policy already exits 1 on any FAIL)
+
+## Exit code behavior (per plan)
+- Exit 0: all checks OK or WARN (no FAIL)
+- Exit 1: at least one check is FAIL (regardless of --exit-on-fail flag)
+- Exit 2: CLI parse error (clap default)
+
+## Acceptance criteria verification
+
+| Criterion | Result | Test output |
+|-----------|--------|-------------|
+| pdftract doctor with OK + WARN → exit 0 | **PASS** | `5 OK, 1 WARN, 0 FAIL` → exit 0 |
+| pdftract doctor with FAIL → exit 1 | **PASS** | `4 OK, 1 WARN, 1 FAIL` → exit 1 |
+| pdftract doctor --exit-on-fail with FAIL → exit 1 | **PASS** | `4 OK, 1 WARN, 1 FAIL` → exit 1 |
+| pdftract doctor --exit-on-fail with OK/WARN → exit 0 | **PASS** | `5 OK, 1 WARN, 0 FAIL` → exit 0 |
+| pdftract doctor --bogus-flag → exit 2 | **PASS** | `error: unexpected argument` → exit 2 |
+| pdftract doctor --help → exit 0 | **PASS** | Help displayed → exit 0 |
+
+## Notes
+- The `--exit-on-fail` flag is accepted but does NOT change behavior (the default policy already exits 1 on any FAIL)
+- The flag is retained for explicit CI-script readability and forward-compatibility (future `--warn-as-fail` or `--no-exit-on-fail` would invert)
+- N/A status does NOT affect exit code
+- WARN status does NOT affect exit code (calibrated: WARN = "watch this but don't block deployment")