@surlymochan/evalid 0.5.18 → 0.5.20

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project are documented here. Detailed notes live in
 [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
+## [0.5.20] - 2026-11-10
+
+### Added
+- **M4 slice 3: workflow run auto-selects lite (#102)**: `xflow workflow run` with no explicit flag runs the slice-1 classifier first and picks the track itself — small diff → lite (spec ritual skipped, seal + replay only), big diff → full, explicit `--lite` / `--full` always wins (both flags together resolve to full), classifier failure falls back to full and records the failure, never silently lite. The decision rides in the workflow events as `lite_track_decision` (`{source, track, reason, files, added, removed, total, base, force_full}`, source `auto` / `explicit-lite` / `explicit-full` / `auto-fallback-full`), next to slice 1's `lite_fast_track` field; the CLI prints `Lite fast track: <source> → <track>`. Test evidence: 19 new tests in `test/lite-track-auto.test.js` (resolver, flag priority, executor event recording with mock atoms, CLI dry-run wiring) RED→GREEN; PR CI runs verify 42702996913 (3m31s) and ledger 42702997046 (8s) both pass; merged main CI run 42703634292 success.
+- **M4 slice 4: classifier ignores workflow-written change artifacts (#104)**: the auto end-to-end acceptance demo on main HEAD caught a real bug — run 1 auto-decided lite and sealed the red proof, but the resume flipped to full because run 1 had rewritten the tracked `specs/changes/<id>/status.json` itself (+268/−2 lines) and the force-full rule fired on the `specs/` path. `classify_repo` in `xflow/atoms/lite_track.py` now excludes workflow-generated artifacts under `specs/changes/<id>/` (`status.json`, `verify_proof.json`, `spec_delta_review.json/.md`, `tdd/`, `cr/`) from the measured stats before the verdict; human-authored spec files (`proposal.md` / `plan.md` / `tasks.md`) still force full. Test evidence: 4 new classifier unit tests in `test/lite-track.test.js` (status.json churn, generated proof artifacts, proposal.md still forces full, committed status.json churn) 4/4 fail without the fix and 4/4 pass with it; new end-to-end regression test `test/lite-track-auto-acceptance.test.js` (real small fix, no flag, red → fix → resume stays lite with `source: auto, track: lite` in both runs' events, seal + clean replay with binding hash; 400-line control stays auto-full across resume) fails on main HEAD before the fix and passes after it; full `npm run verify` exit 0 — 61 test files, 560 tests, 559 pass, 0 fail (1 skipped); PR CI runs verify 42722307306 (3m31s) and ledger 42722307186 (8s) both pass; merged main CI run 42722893282 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice4-auto-resume.md, n=1 per track, same auto demo flow, Linux VM / node v24.22.1 / python 3.12.3): auto demo lite 4,995 ms vs full 6,363 ms (ratio 0.785) isolated, and lite 8,239 ms vs full 7,124 ms (ratio 1.157) inside `npm run verify`; the slice-2 demo re-measured 1.291 in the same suite run. Same demo, same machine, ratios 0.785–1.291 minutes apart — n=1 demo timings are dominated by per-process startup and machine load (the suite runs test files in parallel), not by the spec ritual. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+Milestone M4 "lite fast track" — **not yet accepted**: slices 1–4 are merged checkpoints; the auto end-to-end acceptance is now demonstrated (real small change through auto-lite across the red→green resume, real large change judged auto-full, seal + clean replay), but the wall-clock verdict still awaits bench numbers. This release makes no M4 acceptance claim.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2 / P1-3 / P2-1 / P2-3 still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 82/135 with the 12th relaunch in flight. No bench numbers are claimed in this release.
+
+## [0.5.19] - 2026-11-10
+
+### Added
+- **M4 slice 1: lite fast-track classifier and `--lite` switch (#98)**: `xflow/atoms/lite_track.py` classifies a diff `lite` / `full` against the merge-base (`git diff --numstat`, added + removed); thresholds `max_files = 10`, `max_lines = 300`; any touch under `specs/` or `workflows/` forces `full`; empty diff is `lite`; unified-diff text mode (`--diff-file`) also supported. `xflow workflow run` gains an explicit `--lite` flag — the classifier is the decision procedure, no silent auto-switching. Executor `lite_skip` (`src/core/workflow-executor.js` + schema): phases/atoms marked `lite_skip: true` are skipped in a `--lite` run and logged `phase_skipped` / `atom_skipped` (reason `lite_track`); a deterministic gate on a lite-skipped atom passes with verdict `lite_skipped`; `workflow_started` / `workflow_completed` record `lite_fast_track: true/false`. `workflows/yolo.yaml` wiring: `proposal-consistency-check` phase is `lite_skip`; `J4a` / `J4b` atoms in `verify-consistency` are `lite_skip`. Kept in lite mode: TDD run + proof seal + i6d gate (`tdd-green`), full test run (`J1`), code review (`J6`), and `xflow audit` replay. Test evidence: 11 new tests in `test/lite-track.test.js` (classifier on real git fixtures, yolo.yaml wiring, `WorkflowExecutor` lite/full runs with mock atoms) RED→GREEN; full `npm run verify` exit 0 (58 test files); PR CI runs verify 42664527969 and ledger 42664528087 both pass; merged main CI run 42665066351 success.
+- **M4 slice 2: lite acceptance demo + wall-clock preliminary numbers (#99)**: `test/lite-track-acceptance.test.js` proves the lite track end to end through the real `WorkflowExecutor` and real `workflows/yolo.yaml` (dogfood fix: `classify_repo --uncommitted` in `lite_track.py` merged committed and worktree numstats with `max()`, overcounting partially reverted lines — now reads the worktree diff against the base directly; regression test in `test/lite-track.test.js`, 11/12 pass without the fix). Lite run: `proposal-consistency-check` logged `phase_skipped` (reason `lite_track`); `J4a` / `J4b` logged `atom_skipped`; the `verify-consistency` gate passed with verdict `lite_skipped`; `workflow_completed` recorded `lite_fast_track: true`. Seal + clean replay: red proof `passed: false` (`failure_kind: assertion`); green proof `passed: true` with binding hash and snapshot scope; I6b validated both. I6d, I6c, J1 and J6 all passed in both tracks. Full-track control (same flow, `--lite` off): J4a / J4d / J4b all executed and passed; no `lite_track` skip anywhere; `lite_fast_track: false`. Classifier controls: the real 2-file fix classifies `lite`; a 400-line addition classifies `full`; a one-line touch under `specs/` classifies `full` (force-full). Test evidence: 2 new tests (regression + acceptance) RED→GREEN; full `npm run verify` exit 0 — 59 test files, 536 tests, 535 pass, 0 fail (1 pre-existing todo); PR CI runs verify and ledger both pass; merged main CI run 42689050732 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice2-wallclock.md, n=1 per track, same demo flow, Linux VM / node v24.22.1 / python 3.12.3): standalone acceptance test lite 5,050 ms vs full 6,330 ms (ratio 0.798); inside `npm run verify` lite 10,420 ms vs full 16,191 ms (ratio 0.644). The two runs disagree by ~0.15 on the ratio minutes apart on the same machine — that spread is why these numbers are preliminary. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+Milestone M4 "lite fast track" — **not yet accepted**: slices 1 and 2 are merged checkpoints only; the end-to-end acceptance evidence (real small change through `--lite`, real large change judged `full`, wall-clock verdict from bench numbers) is not yet in place. This release makes no M4 acceptance claim.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2 / P1-3 / P2-1 / P2-3 still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is still running. No bench numbers are claimed in this release.
+
 ## [0.5.18] - 2026-11-09
 
 ### Added

package/RELEASE_NOTES.md

@@ -1,5 +1,33 @@
 # Release Notes
 
+## 0.5.20 - M4 lite fast track, slices 3–4 (milestone M4 not yet accepted)
+
+Patch release. Two merged PRs since 0.5.19, both verified end to end in CI and locally.
+
+**M4 slice 3: workflow run auto-selects lite (#102).** `xflow workflow run` with no explicit flag runs the classifier first and picks the track itself — small diff → lite, big diff → full, explicit `--lite` / `--full` always wins, classifier failure falls back to full and records it. The decision is written into the workflow events as `lite_track_decision`, next to `lite_fast_track`. Test evidence: 19 new tests in `test/lite-track-auto.test.js` RED→GREEN; PR CI runs verify 42702996913 and ledger 42702997046 both pass; merged main CI run 42703634292 success.
+
+**M4 slice 4: classifier ignores workflow-written change artifacts (#104).** The auto end-to-end acceptance demo on main HEAD caught a real bug: run 1 auto-decided lite and sealed the red proof, but the resume flipped to full because run 1 had rewritten the tracked `specs/changes/<id>/status.json` itself (+268/−2 lines) and the force-full rule fired on the `specs/` path. `classify_repo` now excludes workflow-generated artifacts under `specs/changes/<id>/` (`status.json`, `verify_proof.json`, `spec_delta_review.*`, `tdd/`, `cr/`) from the measured stats; human spec files still force full. Test evidence: 4 new classifier unit tests RED→GREEN (4/4 fail without the fix); new end-to-end regression test `test/lite-track-auto-acceptance.test.js` (real small fix, no flag, resume stays lite; 400-line control stays auto-full) fails before the fix, passes after; full `npm run verify` exit 0 — 61 test files, 560 tests, 559 pass, 0 fail; PR CI runs verify 42722307306 and ledger 42722307186 both pass; merged main CI run 42722893282 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice4-auto-resume.md, n=1 per track, same auto demo flow, Linux VM / node v24.22.1 / python 3.12.3): auto demo lite 4,995 ms vs full 6,363 ms (ratio 0.785) isolated, lite 8,239 ms vs full 7,124 ms (ratio 1.157) inside `npm run verify`; slice-2 demo re-measured 1.291 in the same suite run. Same demo, same machine, ratios 0.785–1.291 — n=1 demo timings are dominated by startup and machine load, not by the spec ritual. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+**Milestone M4 "lite fast track" — not yet accepted.** Slices 1–4 are merged checkpoints; the auto end-to-end acceptance is now demonstrated (real small change through auto-lite across the red→green resume, real large change judged auto-full, seal + clean replay), but the wall-clock verdict still awaits bench numbers.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2, P1-3, P2-1 and P2-3 — the wall-clock/token/resolved lines from issue #5 — still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), at 82/135 with the 12th relaunch in flight. No bench numbers are claimed in this release.
+
+## 0.5.19 - M4 lite fast track, slices 1–2 (milestone M4 not yet accepted)
+
+Patch release. Two merged PRs since 0.5.18, both verified end to end in CI and locally.
+
+**M4 slice 1: lite fast-track classifier and `--lite` switch (#98).** `xflow/atoms/lite_track.py` classifies a diff `lite` / `full` against the merge-base; thresholds `max_files = 10`, `max_lines = 300`; any touch under `specs/` or `workflows/` forces `full`; empty diff is `lite`. `xflow workflow run` gains an explicit `--lite` flag — the classifier decides, no silent auto-switching. Executor `lite_skip` skips the spec ritual in a `--lite` run (`proposal-consistency-check` phase, `J4a` / `J4b` atoms) and logs the skips; kept in lite mode: TDD run + proof seal + i6d gate, full test run (`J1`), code review (`J6`), and `xflow audit` replay. Test evidence: 11 new tests in `test/lite-track.test.js` RED→GREEN; full `npm run verify` exit 0 (58 test files); PR CI runs verify 42664527969 and ledger 42664528087 both pass; merged main CI run 42665066351 success.
+
+**M4 slice 2: lite acceptance demo + wall-clock preliminary numbers (#99).** `test/lite-track-acceptance.test.js` proves the lite track end to end through the real executor and real `workflows/yolo.yaml` (dogfood fix: `classify_repo --uncommitted` overcounted partially reverted lines — now reads the worktree diff against the base directly; regression test, 11/12 pass without the fix). Lite run: `proposal-consistency-check` skipped (reason `lite_track`), `J4a` / `J4b` skipped, `verify-consistency` gate passed with verdict `lite_skipped`, `lite_fast_track: true`; seal + clean replay (red proof `passed: false`, green proof `passed: true`, I6b validated both); I6d, I6c, J1 and J6 passed in both tracks. Full-track control ran all spec atoms, `lite_fast_track: false`. Classifier controls: 2-file fix → `lite`; 400-line addition → `full`; one-line `specs/` touch → `full`. Test evidence: 2 new tests RED→GREEN; full `npm run verify` exit 0 — 59 test files, 536 tests, 535 pass, 0 fail (1 pre-existing todo); PR CI verify and ledger both pass; merged main CI run 42689050732 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice2-wallclock.md, n=1 per track, same demo flow, Linux VM / node v24.22.1 / python 3.12.3): standalone acceptance test lite 5,050 ms vs full 6,330 ms (ratio 0.798); inside `npm run verify` lite 10,420 ms vs full 16,191 ms (ratio 0.644). The two runs disagree by ~0.15 on the ratio minutes apart on the same machine — that spread is why these numbers are preliminary. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+**Milestone M4 "lite fast track" — not yet accepted.** Slices 1 and 2 are merged checkpoints only; the end-to-end acceptance evidence (real small change through `--lite`, real large change judged `full`, wall-clock verdict from bench numbers) is not yet in place.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2, P1-3, P2-1 and P2-3 — the wall-clock/token/resolved lines from issue #5 — still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is still running. No bench numbers are claimed in this release.
+
 ## 0.5.18 - Proof verdicts as SARIF for code scanning (issue #73 closed)
 
 Patch release. One merged PR since 0.5.17, verified end to end in CI and locally, with the Security-tab acceptance evidence from a demo PR.

package/bin/xflow.js

@@ -5478,6 +5478,21 @@ async function handleWorkflow(sub, args) {
         }
       }
       ensureChangeId(changeId, 'workflow run', projectRoot);
+      // M4 slice 3 (evalid #101): auto-select the lite track. With no
+      // explicit flag the classifier decides (small diff -> lite, big diff
+      // -> full, classifier failure -> full); --lite / --full always win.
+      // The decision is attached to the workflow input so the executor
+      // records it in the workflow_started / workflow_completed events.
+      const { decideLiteTrack, resolveLiteTrackAuto } = await import('../src/core/lite-track-auto.js');
+      const autoDecision = (parsedArgs.lite === true || parsedArgs.full === true)
+        ? null
+        : resolveLiteTrackAuto({ projectRoot });
+      const { lite: effectiveLite, decision: liteDecision } = decideLiteTrack({
+        lite: parsedArgs.lite, full: parsedArgs.full, autoDecision,
+      });
+      if (effectiveLite) input.lite = true;
+      input.lite_track_decision = liteDecision;
+      console.log(`Lite fast track: ${liteDecision.source} → ${liteDecision.track} (${liteDecision.reason})`);
       const { load, dryRun } = await import('../src/core/workflow-loader.js');
       if (isDryRun) {
         dryRun(yamlPath);
@@ -6692,6 +6707,20 @@ Commands:
   validate <yaml|yolo|corps>  Validate workflow YAML as preflight only
 
 Options:
+  --lite                  M4 lite fast track: skip spec-ritual steps
+                          (proposal-consistency-check phase, J4a/J4b atoms)
+                          and keep seal + replay only. Always wins over the
+                          auto verdict (see below).
+  --full                  M4 lite fast track: force the full track, skipping
+                          the auto verdict. Wins over --lite when both are
+                          given.
+                          With neither --lite nor --full, the run classifies
+                          the working-tree diff first
+                          (python3 xflow/atoms/lite_track.py --repo .)
+                          and auto-selects lite for a small diff, full for a
+                          big one; a classifier failure falls back to full.
+                          The decision is printed and recorded in the run's
+                          workflow events as lite_track_decision.
   help, -h, --help Show this help message
 `);
 }

package/docs/evidence/m4-slice2-wallclock.md

@@ -0,0 +1,61 @@
+# M4 slice 2: lite vs full wall-clock — local preliminary numbers
+
+Date: 2026-11-10 (Asia/Singapore). Source of truth for the demo itself is
+`test/lite-track-acceptance.test.js` (re-run it to reproduce).
+
+## Status: preliminary — NOT the ≤1.3× conclusion
+
+These are local n=1 measurements of the acceptance demo harness. The formal
+wall-clock verdict for issue #5 P1-2 (small tasks ≤1.3× baseline) waits for
+the bench full-matrix numbers; P1-2 stays unticked and no ≤1.3× claim is
+made here.
+
+## Method
+
+Same demo flow per track, in a throwaway git repo holding a buggy copy of
+`lite_track.py`: the real `WorkflowExecutor` runs the real
+`workflows/yolo.yaml` phases (`proposal-consistency-check`, `tdd-red`,
+`tdd-green`, `verify-consistency`) with the real atom registry. First run
+(red seals, green stops pre-fix), fix applied, resume run (green seals,
+verify runs). The lite run skips the spec ritual; the full run executes it.
+Each total below is first run + resume run.
+
+Machine: Linux x86_64 VM, AMD EPYC 9D25, 4 vCPU; node v24.22.1, python 3.12.3.
+
+## Numbers
+
+| Run | lite (first + resume) | full (first + resume) | lite/full |
+| --- | --- | --- | --- |
+| Standalone acceptance test | 2,198 ms + 2,852 ms = 5,050 ms | 2,816 ms + 3,514 ms = 6,330 ms | 0.798 |
+| Inside `npm run verify` (full suite) | 4,120 ms + 6,300 ms = 10,420 ms | 7,601 ms + 8,590 ms = 16,191 ms | 0.644 |
+
+n=1 per track per run. The two runs, minutes apart on the same machine,
+disagree by ~0.15 on the ratio — that spread is itself the reason these
+numbers are preliminary: the demo's absolute times are dominated by
+per-process startup (node + python atoms) and machine load, not by the
+spec ritual alone. Do not quote 0.64 or 0.80 as the lite-track speedup.
+
+## What the demo proved (functional, not timing)
+
+- Classifier: the real fix (2 files, `lite_track.py` + `test/demo.test.mjs`)
+  classifies `lite`; a 400-line addition classifies `full`; a one-line
+  touch under `specs/` classifies `full` (force-full).
+- Lite run: `proposal-consistency-check` logged `phase_skipped`
+  (reason `lite_track`); `J4a` / `J4b` logged `atom_skipped` (reason
+  `lite_track`); the `verify-consistency` gate passed with verdict
+  `lite_skipped`; `workflow_completed` recorded `lite_fast_track: true`.
+- Seal + clean replay: red proof `passed: false`
+  (`failure_kind: assertion`); green proof `passed: true` with binding
+  hash and snapshot scope; I6b validated both (binding recomputed,
+  snapshot hashes checked, command re-run on the snapshot).
+  I6d, I6c, J1 and J6 all passed in both tracks.
+- Full run (control): J4a / J4d / J4b all executed and passed; no
+  `lite_track` skip anywhere; `workflow_completed` recorded
+  `lite_fast_track: false`.
+
+## Reproduce
+
+```sh
+node test/lite-track-acceptance.test.js   # prints a [m4-slice2-wallclock] line
+npm run verify                            # full suite; same line appears
+```

package/docs/evidence/m4-slice4-auto-resume.md

@@ -0,0 +1,96 @@
+# M4 slice 4: auto-lite resume flips to full on workflow-written status.json
+
+Date: 2026-11-10 (Asia/Singapore). Source of truth for the demo itself is
+`test/lite-track-auto-acceptance.test.js` (re-run it to reproduce).
+Parent issue: #97; slice issue: #103; PR: slice 4 (this change).
+
+## Status: preliminary wall clock — NOT the ≤1.3× conclusion
+
+The wall-clock numbers below are local n=1 measurements of the acceptance
+demo harness. The formal wall-clock verdict for issue #5 P1-2 (small tasks
+≤1.3× baseline) waits for the bench full-matrix numbers; P1-2 stays
+unticked and no ≤1.3× claim is made here.
+
+## The bug (found by the auto acceptance demo on main HEAD 4668b6ab)
+
+A real small fix through `xflow workflow run` with **no flag**: run 1
+(pre-fix, clean tree) auto-decides lite, seals the red proof, stops at
+tdd-green. The fix is applied, run 2 (resume) re-runs the classifier —
+and flips to **full**:
+
+| Run | `lite_track_decision` (from the workflow events) | `lite_fast_track` |
+| --- | --- | --- |
+| Run 1, pre-fix | `{source: auto, track: lite, reason: 'empty diff: nothing to ritualise', files: 0, total: 0}` | `true` |
+| Run 2, resume (pre-fix code) | `{source: auto, track: full, reason: 'touches specs/ paths (specs/changes/chg-m4-auto-demo/status.json): spec/workflow drift needs the full track', files: 3, total: 281}` | `false` |
+
+Root cause: run 1 rewrites the tracked
+`specs/changes/<id>/status.json` itself (stage transitions +
+`workflow_integrity` block, +268/−2 lines in the demo; the worktree diff
+at resume time is 3 files, 277 insertions / 13 deletions). The classifier
+measures the worktree diff against the merge-base, sees a `specs/` path,
+and the force-full rule fires. The actual user change is still the same
+2-file, 20-line fix. The two halves of one change then run on different
+tracks: the resume re-executes the spec ritual (J4a/J4b) that run 1
+skipped.
+
+Scope note: evalid's own repo gitignores `specs/changes/`, so dogfooding
+does not hit this — but any repo that tracks change state does, and the
+repo's own acceptance demo (the M4 bar) fails on main HEAD. The defect is
+in the shipped classifier, not the demo, so the fix is in the classifier.
+
+## The fix
+
+`classify_repo` in `xflow/atoms/lite_track.py` now excludes
+workflow-generated artifacts under `specs/changes/<id>/` from the measured
+stats before the verdict: `status.json`, `verify_proof.json`,
+`spec_delta_review.json` / `.md`, and the `tdd/` / `cr/` trees.
+Human-authored spec files (`proposal.md` / `plan.md` / `tasks.md`) still
+force full. No CLI / executor / env / phanes call-surface change.
+
+## Numbers (post-fix demo runs, n=1 each, preliminary)
+
+| Run | lite (first + resume) | full (first + resume) | lite/full |
+| --- | --- | --- | --- |
+| Auto acceptance test, isolated | 2,446 ms + 2,549 ms = 4,995 ms | 2,854 ms + 3,509 ms = 6,363 ms | 0.785 |
+| Auto acceptance test, inside `npm run verify` | 4,135 ms + 4,104 ms = 8,239 ms | 4,126 ms + 2,998 ms = 7,124 ms | 1.157 |
+
+Same demo, same machine, two runs minutes apart: 0.785 vs 1.157. The
+slice-2 demo re-measured inside the same suite run gives 1.291 this time
+(7,655 ms vs 5,928 ms), against its original 0.644 / 0.798. The spread
+itself is the finding: n=1 demo timings are dominated by per-process
+startup and machine load (the suite runs test files in parallel), not by
+the spec ritual. Do not quote any of these ratios as the lite-track
+speedup; the formal ≤1.3× verdict still waits for the bench full-matrix
+numbers.
+
+Machine for all runs above: Linux x86_64 VM, AMD EPYC 9D25, 4 vCPU;
+node v24.22.1, python 3.12.3.
+
+## What the demo proved (functional, not timing)
+
+- Post-fix resume decision: `{source: auto, track: lite, reason:
+  'within thresholds (2 files, 20 lines <= 10 files, 300 lines)',
+  files: 2, added: 9, removed: 11, total: 20, force_full: []}` — the
+  resume stays lite on the same fix that run 1 lite'd.
+- Lite run: `proposal-consistency-check` logged `phase_skipped` (reason
+  `lite_track`); `J4a` / `J4b` logged `atom_skipped` (reason
+  `lite_track`); the `verify-consistency` gate passed with verdict
+  `lite_skipped`; `workflow_completed` recorded `lite_fast_track: true`
+  with the auto decision in both `workflow_started` and
+  `workflow_completed`.
+- Seal + clean replay: red proof `passed: false`; green proof
+  `passed: true` with binding hash `8f5f78b44be55c3d` and snapshot scope
+  (`lite_track.py`, `test/demo.test.mjs`); I6b validated both; I6d, I6c,
+  J1 and J6 all passed.
+- Full control (400-line file staged, no flag): first run auto-full
+  (`400 lines > 300 max_lines`, 1 file), resume auto-full (420 lines,
+  3 files); J4a / J4d / J4b all executed and passed; no `lite_track`
+  skip anywhere; `workflow_completed` recorded `lite_fast_track: false`.
+
+## Reproduce
+
+```sh
+node --test test/lite-track-auto-acceptance.test.js  # prints [m4-auto-*] lines
+node --test test/lite-track.test.js                   # classifier unit tests
+npm run verify                                        # full suite
+```

package/docs/launch-dossier.md

@@ -1,6 +1,6 @@
 # evalid Launch Dossier
 
-Generated: 2026-11-09T05:51:48.645Z
+Generated: 2026-11-09T20:25:08.664Z
 Mode: post_publish
 Verdict: conditionally ready: engine and adoption evidence are strong, registry publication remains required for a splash launch
 Launch ready: not yet
@@ -117,7 +117,7 @@ Evidence:
 - Adoption records: 1; status: pass
 - Goal audit: pass; goal: Keep evalid credible as an open-source agent delivery runtime: repo-owned workflow contracts, executable verification gates, durable project context, and honest benchmark evidence.
 - Package evidence: missing; source: registry_json
-- Package name/version: @surlymochan/evalid@0.5.18
+- Package name/version: @surlymochan/evalid@0.5.20
 
 ## Passing Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surlymochan/evalid",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "description": "Claimed != verified: a runtime verification layer for coding agents. It seals each test run and replays it from a clean snapshot, with a zero-judge gate pipeline (spec clarification, code review, TDD proof) and the xflow CLI.",
   "keywords": [
     "ai-agents",

package/schemas/workflow.schema.json

@@ -40,6 +40,10 @@
           "label": { "type": "string" },
           "catalog_ref": { "type": "integer", "minimum": 1, "maximum": 27 },
           "required": { "type": "boolean" },
+          "lite_skip": {
+            "type": "boolean",
+            "description": "M4 lite fast track: skip this whole phase when the run has input.lite=true (spec ritual only; the verification spine never carries this flag)"
+          },
           "condition": {
             "type": "object",
             "description": "Skip phase unless condition met",
@@ -56,6 +60,10 @@
               "properties": {
                 "id": { "type": "string" },
                 "with": { "type": "object" },
+                "lite_skip": {
+                  "type": "boolean",
+                  "description": "M4 lite fast track: skip this atom when the run has input.lite=true (spec ritual atoms only; a deterministic gate on a lite-skipped atom passes with verdict lite_skipped)"
+                },
                 "parallel_group": { "type": "string" },
                 "parallel_weight": { "type": "integer", "minimum": 1, "maximum": 16 }
               }

package/src/core/lite-track-auto.js

@@ -0,0 +1,126 @@
+/**
+ * M4 lite fast track, slice 3 (evalid #101, parent #97): auto-select the
+ * track for `xflow workflow run`.
+ *
+ * With no explicit flag the run classifies the change first (slice 1's
+ * `xflow/atoms/lite_track.py`, working-tree diff against the merge-base,
+ * `--uncommitted`): a small diff walks the lite track, a big diff stays
+ * full. Explicit `--lite` / `--full` always wins; both flags together
+ * resolve to full (conservative). Any classifier failure falls back to
+ * full and records the failure -- a run must never silently go lite.
+ *
+ * The returned decision object is JSON-serialisable on purpose: the CLI
+ * attaches it to the workflow input as `lite_track_decision` and the
+ * executor records it in the `workflow_started` / `workflow_completed`
+ * events, next to slice 1's `lite_fast_track` field.
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_CLASSIFIER_PATH = resolve(__dirname, '..', '..', 'xflow', 'atoms', 'lite_track.py');
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Run the classifier against `projectRoot` and return the auto decision.
+ *
+ * `runClassifier` is injectable (defaults to `spawnSync`) so tests can
+ * stub the classifier invocation without touching git or python.
+ */
+export function resolveLiteTrackAuto({
+  projectRoot,
+  classifierPath = DEFAULT_CLASSIFIER_PATH,
+  python = process.env.PYTHON || 'python3',
+  runClassifier = spawnSync,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const fallback = (detail) => ({
+    source: 'auto-fallback-full',
+    track: 'full',
+    reason: `classifier failed (${detail}); falling back to full track`,
+    files: null,
+    added: null,
+    removed: null,
+    total: null,
+    base: null,
+    force_full: [],
+  });
+
+  let result;
+  try {
+    result = runClassifier(
+      python,
+      [classifierPath, '--repo', projectRoot, '--uncommitted', '--json'],
+      { encoding: 'utf8', timeout: timeoutMs },
+    );
+  } catch (err) {
+    return fallback(`spawn error: ${err?.message || String(err)}`);
+  }
+  if (!result || result.status !== 0) {
+    const detail = String(
+      result?.stderr?.trim() || result?.error?.message || `exit ${result?.status ?? 'unknown'}`,
+    ).slice(0, 200);
+    return fallback(detail);
+  }
+  let verdict;
+  try {
+    verdict = JSON.parse(result.stdout);
+  } catch {
+    return fallback('unparseable classifier output');
+  }
+  if (verdict?.track !== 'lite' && verdict?.track !== 'full') {
+    return fallback(`unexpected verdict: ${JSON.stringify(verdict).slice(0, 200)}`);
+  }
+  return {
+    source: 'auto',
+    track: verdict.track,
+    reason: verdict.reason || '',
+    files: verdict.files ?? null,
+    added: verdict.added ?? null,
+    removed: verdict.removed ?? null,
+    total: verdict.total ?? null,
+    base: verdict.base ?? null,
+    force_full: verdict.force_full || [],
+  };
+}
+
+/**
+ * Resolve the effective track from explicit flags and (when neither flag
+ * is given) the auto decision. Returns `{ lite, decision }`.
+ */
+export function decideLiteTrack({ lite, full, autoDecision }) {
+  if (lite === true && full === true) {
+    return {
+      lite: false,
+      decision: {
+        source: 'explicit-full',
+        track: 'full',
+        reason: 'both --lite and --full given; --full wins (conservative)',
+      },
+    };
+  }
+  if (lite === true) {
+    return {
+      lite: true,
+      decision: { source: 'explicit-lite', track: 'lite', reason: 'explicit --lite flag' },
+    };
+  }
+  if (full === true) {
+    return {
+      lite: false,
+      decision: { source: 'explicit-full', track: 'full', reason: 'explicit --full flag' },
+    };
+  }
+  if (!autoDecision) {
+    return {
+      lite: false,
+      decision: {
+        source: 'auto-fallback-full',
+        track: 'full',
+        reason: 'no classifier verdict available; falling back to full track',
+      },
+    };
+  }
+  return { lite: autoDecision.track === 'lite', decision: autoDecision };
+}

package/src/core/workflow-executor.js

@@ -11,6 +11,14 @@
  *
  * E6 ≡ E1+E2 invariant enforced: executor routes ALL deterministic gate checks
  * through E6.gate.local_precheck Python atom, never re-implementing logic here.
+ *
+ * M4 lite fast track (evalid #97): when input.lite is true, phases and atoms
+ * marked `lite_skip: true` in the workflow YAML are skipped (the spec ritual:
+ * J4a/J4b/J4d), while the verification spine (TDD run + proof seal + i6d
+ * gate + full test run + CR review) still runs. Skips are logged as
+ * `phase_skipped` / `atom_skipped` with reason `lite_track`, and a
+ * deterministic gate whose gate atom is lite-skipped passes with verdict
+ * `lite_skipped` instead of re-running the spec check.
  */
 
 import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from 'fs';
@@ -67,6 +75,17 @@ export class WorkflowExecutor {
 
   // ─── Main execution loop ─────────────────────────────────────────────────
 
+  // M4 lite fast track: `input.lite === true` engages it. Slice 1 set this
+  // only from the explicit `--lite` flag; slice 3 (evalid #101) lets the
+  // CLI resolve it first -- `decideLiteTrack` in lite-track-auto.js runs
+  // the classifier when no explicit flag is given and sets `input.lite`
+  // when the verdict is lite, so the executor itself never decides. The
+  // decision itself arrives as `input.lite_track_decision` and is recorded
+  // in the workflow_started / workflow_completed events.
+  isLiteFastTrack() {
+    return this.input?.lite === true;
+  }
+
   // ─── Phase cost accounting ─────────────────────────────────────────────
 
   recordPhaseCost(phase, status, startedAtMs) {
@@ -121,6 +140,11 @@ export class WorkflowExecutor {
       workflow_run_id: this.runtime.workflowRunId,
       workflow: this.workflow.name,
       track: this.workflow.track,
+      lite_fast_track: this.isLiteFastTrack(),
+      // M4 slice 3: how the track was chosen (auto / explicit-lite /
+      // explicit-full / auto-fallback-full); null when the run was started
+      // without the CLI decision step (e.g. direct executor use).
+      lite_track_decision: this.input?.lite_track_decision ?? null,
       workflow_integrity: this.workflowManifest,
       max_parallel_agents: this.maxParallelAgents,
       parallel_policy: this.concurrencyPolicy.mode,
@@ -189,6 +213,28 @@ export class WorkflowExecutor {
         }
       }
 
+      // M4 lite fast track: skip whole phases marked lite_skip (the spec
+      // ritual). Logged like a condition skip so proof still sees the phase
+      // as accounted for; the reason distinguishes the two.
+      if (phase.lite_skip && this.isLiteFastTrack()) {
+        console.log(`  ↷ Skipping (lite fast track: phase "${phase.id}" is spec ritual)`);
+        await this.logExecutionEvent('phase_skipped', {
+          workflow_run_id: this.runtime.workflowRunId,
+          workflow: this.workflow.name,
+          track: this.workflow.track,
+          phase_id: phase.id,
+          phase_label: phase.label || null,
+          phase_index: i,
+          reason: 'lite_track',
+          change_id: this.changeId || null,
+          mission_id: this.runtime.missionId || null,
+          workflow_integrity_digest: this.workflowManifest.digest,
+        });
+        this.recordPhaseCost(phase, 'skipped', phaseStartedAtMs);
+        this.saveState({ ...state, last_completed_phase: phase.id });
+        continue;
+      }
+
       // Preconditions
       if (phase.preconditions?.length > 0) {
         const precondOk = this.checkPreconditions(phase.preconditions);
@@ -203,12 +249,33 @@ export class WorkflowExecutor {
         this.ensurePlanArtifact();
       }
 
-      // Run atoms
+      // Run atoms (M4 lite: atoms marked lite_skip are filtered out first
+      // and logged individually, so mixed phases keep their spine).
       const atomsToRun = rerunRequest?.phase_id === phase.id && rerunRequest?.atom_id
         ? (phase.atoms || []).filter((atomRef) => atomRef.id === rerunRequest.atom_id)
         : (phase.atoms || []);
-      if (atomsToRun.length > 0) {
-        for (const batch of this.buildAtomBatches(atomsToRun)) {
+      const runnableAtoms = [];
+      for (const atomRef of atomsToRun) {
+        if (atomRef.lite_skip && this.isLiteFastTrack()) {
+          console.log(`  ↷ Skipping atom (lite fast track): ${atomRef.id}`);
+          await this.logExecutionEvent('atom_skipped', {
+            workflow_run_id: this.runtime.workflowRunId,
+            workflow: this.workflow.name,
+            track: this.workflow.track,
+            phase_id: phase.id,
+            phase_label: phase.label || null,
+            atom_id: atomRef.id,
+            reason: 'lite_track',
+            change_id: this.changeId || null,
+            mission_id: this.runtime.missionId || null,
+            workflow_integrity_digest: this.workflowManifest.digest,
+          });
+          continue;
+        }
+        runnableAtoms.push(atomRef);
+      }
+      if (runnableAtoms.length > 0) {
+        for (const batch of this.buildAtomBatches(runnableAtoms)) {
           this.ensureNotAborted();
           const results = batch.parallel
             ? await this.runParallelBatch(batch.atoms, phase)
@@ -291,6 +358,8 @@ export class WorkflowExecutor {
       workflow_run_id: this.runtime.workflowRunId,
       workflow: this.workflow.name,
       track: this.workflow.track,
+      lite_fast_track: this.isLiteFastTrack(),
+      lite_track_decision: this.input?.lite_track_decision ?? null,
       workflow_integrity: this.workflowManifest,
       change_id: this.changeId || null,
       mission_id: this.runtime.missionId || null,
@@ -567,6 +636,12 @@ export class WorkflowExecutor {
 
     switch (gate.type) {
       case 'deterministic': {
+        // M4 lite: a gate whose atom is lite-skipped in this phase must not
+        // re-run the spec check it gates — the skip is the verdict.
+        if (gate.atom && this.isLiteFastTrack()
+          && (phase.atoms || []).some((atomRef) => atomRef.id === gate.atom && atomRef.lite_skip)) {
+          return { ok: true, verdict: 'lite_skipped' };
+        }
         // Route through E6 (Python) for ALL structural checks — invariant enforced
         if (gate.atom) {
           const result = await this.runAtom({ id: gate.atom, with: gate.with }, phase);

package/workflows/yolo.yaml

@@ -80,10 +80,14 @@ phases:
       type: artifact-verify
       on_fail: stop
 
+  # M4 lite fast track (evalid #97): this whole phase is spec ritual — a
+  # `--lite` run skips it (executor logs phase_skipped, reason lite_track)
+  # and keeps the verification spine (tdd seal + i6d + J1 + J6).
   - id: proposal-consistency-check
     label: "07 · Proposal consistency check"
     catalog_ref: 7
     required: true
+    lite_skip: true
     atoms:
       - id: J4a.spec_consistency.structural
       - id: J4d.spec_clarify.gate
@@ -205,8 +209,14 @@ phases:
     required: true
     atoms:
       - id: J1.tests.run
+      # M4 lite fast track (evalid #97): J4a/J4b are spec ritual — a `--lite`
+      # run skips them (atom_skipped, reason lite_track) and the phase's
+      # deterministic J4a gate passes with verdict lite_skipped. J1 (full
+      # test run) and J6 (code review) stay: they are verification, not ritual.
       - id: J4a.spec_consistency.structural
+        lite_skip: true
       - id: J4b.spec_delta.review
+        lite_skip: true
       - id: J6.cr.review
       - id: B3.status.transition
         with: { to_stage: "verify" }

package/xflow/atoms/lite_track.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+M4 lite fast-track: diff-size classifier (slice 1).
+
+Decides whether a change is small enough to skip the spec ritual and run
+seal (i6b) + clean replay only. The verdict is measured against the change's
+merge-base, reusing M3 slice 2's importable parts from
+``i6d_assertion_execution``: ``resolve_diff_base`` for the branch point,
+``changed_lines`` / ``changed_lines_from_diff`` for the changed-line map.
+Line/file counts come from ``git diff --numstat`` (added + removed, which
+also catches deletion-only and binary files that the changed-line map
+excludes by design).
+
+Thresholds (initial values, see evalid #97 for the calibration):
+
+* ``max_files = 10``, ``max_lines = 300`` (added + removed). This repo's own
+  merged PRs calibrate it: routine slices / fixes / releases land at 4-28
+  lines; the only recent feature slice above the line is P1-3 (#34, 330
+  lines), which correctly stays full-track.
+* Force-full overrides: any touched path under ``specs/`` or ``workflows/``
+  flips the verdict to ``full`` -- the spec ritual exists precisely to catch
+  drift there, so a small diff touching spec/workflow definitions must not
+  skip it. An empty diff classifies ``lite``.
+* Workflow-generated artifacts under ``specs/changes/<id>/`` do not count
+  (slice 4, evalid #103): the workflow itself rewrites ``status.json``
+  (+268 lines in the M4 demo) and writes proof artifacts (``tdd/``,
+  ``cr/``, ``verify_proof.json``, ``spec_delta_review.*``) during a run,
+  so a resume re-measuring the worktree would otherwise flip an auto-lite
+  change to full on its own state. Human-authored spec files
+  (``proposal.md`` / ``plan.md`` / ``tasks.md``) still force full.
+
+CLI (always prints one JSON object; exit 0, exit 2 on git/usage errors)::
+
+    python3 lite_track.py --repo . [--diff-base main] [--json]
+    python3 lite_track.py --repo . --diff-file patch.diff [--json]
+    python3 lite_track.py --repo . --max-files 10 --max-lines 300
+
+The classifier is the *decision procedure*; the enforcement switch is the
+explicit ``--lite`` flag on ``xflow workflow run``. Run the classifier
+first and add ``--lite`` only when it says ``lite`` -- slice 1 does no
+silent auto-switching.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from i6d_assertion_execution import (  # noqa: E402
+    changed_lines,
+    changed_lines_from_diff,
+    resolve_diff_base,
+)
+
+DEFAULT_MAX_FILES = 10
+DEFAULT_MAX_LINES = 300
+FORCE_FULL_PREFIXES = ("specs/", "workflows/")
+VERSION = 1
+
+# Files the workflow itself writes under specs/changes/<id>/ -- machine
+# state and proof artifacts, not spec prose (slice 4, evalid #103).
+GENERATED_CHANGE_FILES = (
+    "status.json",
+    "verify_proof.json",
+    "spec_delta_review.json",
+    "spec_delta_review.md",
+)
+GENERATED_CHANGE_DIRS = ("tdd/", "cr/")
+
+
+def _is_generated_change_artifact(path):
+    """True when ``path`` is workflow-generated state under a change dir.
+
+    ``specs/changes/<id>/status.json`` is rewritten by the workflow on
+    every run (stage transitions, integrity block); ``tdd/`` / ``cr/``
+    hold sealed proofs and review output, ``verify_proof.json`` and
+    ``spec_delta_review.*`` likewise. None of these is a human spec edit,
+    so none of them may force the full track or inflate the measured
+    diff. Anything else under ``specs/changes/<id>/`` -- in particular
+    ``proposal.md`` / ``plan.md`` / ``tasks.md`` -- still counts.
+    """
+    parts = path.split("/")
+    if len(parts) < 4 or parts[0] != "specs" or parts[1] != "changes":
+        return False
+    rest = parts[3:]
+    if len(rest) == 1 and rest[0] in GENERATED_CHANGE_FILES:
+        return True
+    return bool(rest) and (rest[0] + "/") in GENERATED_CHANGE_DIRS
+
+
+def _git(repo, *argv):
+    proc = subprocess.run(
+        ["git", *argv], cwd=repo, capture_output=True, text=True, timeout=30,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"git {' '.join(argv)} failed ({proc.returncode}): "
+            f"{proc.stderr.strip()}"
+        )
+    return proc.stdout
+
+
+def _numstat(repo, base_sha):
+    """``{relpath: (added, removed)}`` from ``git diff --numstat``.
+
+    Binary files report ``-`` counts; they count as a touched file with
+    zero counted lines.
+    """
+    raw = _git(repo, "diff", "--numstat", base_sha, "HEAD", "--")
+    stats = {}
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        added_s, removed_s, path = line.split("\t", 2)
+        added = 0 if added_s == "-" else int(added_s)
+        removed = 0 if removed_s == "-" else int(removed_s)
+        stats[path] = (added, removed)
+    return stats
+
+
+def _diff_text_files_and_counts(diff_text):
+    """``(files, added, removed)`` parsed from a unified diff text.
+
+    Counts ``+``/``-`` lines (excluding the ``+++``/``---`` headers);
+    files come from the ``+++`` headers so deletion-only files are
+    included, unlike the changed-line map.
+    """
+    files = []
+    added = 0
+    removed = 0
+    for line in diff_text.splitlines():
+        if line.startswith("+++ "):
+            target = line[4:].strip()
+            if target in ("/dev/null", ""):
+                continue
+            if target.startswith("b/"):
+                target = target[2:]
+            if len(target) >= 2 and target.startswith('"') and target.endswith('"'):
+                target = json.loads(target)
+            files.append(target)
+        elif line.startswith("+") and not line.startswith("+++"):
+            added += 1
+        elif line.startswith("-") and not line.startswith("---"):
+            removed += 1
+    return files, added, removed
+
+
+def _verdict(files, added, removed, max_files, max_lines):
+    """Shared verdict logic. ``files`` are repo-relative paths."""
+    total = added + removed
+    force_full = sorted({path for path in files if path.startswith(FORCE_FULL_PREFIXES)})
+    if force_full:
+        which = "specs/" if any(p.startswith("specs/") for p in force_full) else "workflows/"
+        return "full", (
+            f"touches {which} paths ({', '.join(force_full)}): "
+            "spec/workflow drift needs the full track"
+        ), force_full
+    if len(files) > max_files:
+        return "full", (
+            f"exceeds file budget: {len(files)} files > {max_files} max_files"
+        ), []
+    if total > max_lines:
+        return "full", (
+            f"exceeds line budget: {total} lines > {max_lines} max_lines"
+        ), []
+    if not files:
+        return "lite", "empty diff: nothing to ritualise", []
+    return "lite", (
+        f"within thresholds ({len(files)} files, {total} lines "
+        f"<= {max_files} files, {max_lines} lines)"
+    ), []
+
+
+def _numstat_worktree(repo, base_sha):
+    """``{relpath: (added, removed)}`` from ``git diff --numstat`` of the
+    working tree (staged + unstaged) against ``base_sha``.
+
+    Binary files report ``-`` counts; they count as a touched file with
+    zero counted lines.
+    """
+    raw = _git(repo, "diff", "--numstat", base_sha, "--")
+    stats = {}
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        added_s, removed_s, path = line.split("\t", 2)
+        stats[path] = (
+            0 if added_s == "-" else int(added_s),
+            0 if removed_s == "-" else int(removed_s),
+        )
+    return stats
+
+
+def classify_repo(repo, base="main", max_files=DEFAULT_MAX_FILES,
+                  max_lines=DEFAULT_MAX_LINES, uncommitted=False):
+    """Classify the committed (or, with ``uncommitted``, working-tree) diff."""
+    base_sha = resolve_diff_base(repo, base)
+    _, changed = changed_lines(repo, base, uncommitted=uncommitted)
+    if uncommitted:
+        # changed_lines(..., uncommitted=True) unions the working tree, so
+        # the numstat side must measure that same union: the worktree diff
+        # against the base. Merging the committed and worktree numstats
+        # with max() overcounts whenever the worktree partially reverts
+        # committed lines (a branch that added 10 lines, cut back by 5 in
+        # the worktree, read as 15 changed lines instead of the true 5).
+        stats = _numstat_worktree(repo, base_sha)
+    else:
+        stats = _numstat(repo, base_sha)
+    # Workflow-generated artifacts under specs/changes/<id>/ are the
+    # workflow's own state, not the change under review (slice 4): drop
+    # them before the verdict so a resume cannot flip to full on its own
+    # status.json rewrite, and so their lines cannot inflate the budget.
+    stats = {
+        path: counts
+        for path, counts in stats.items()
+        if not _is_generated_change_artifact(path)
+    }
+    files = sorted(stats)
+    added = sum(a for a, _ in stats.values())
+    removed = sum(r for _, r in stats.values())
+    track, reason, force_full = _verdict(files, added, removed, max_files, max_lines)
+    return {
+        "version": VERSION,
+        "track": track,
+        "reason": reason,
+        "files": len(files),
+        "added": added,
+        "removed": removed,
+        "total": added + removed,
+        "max_files": max_files,
+        "max_lines": max_lines,
+        "base": base_sha,
+        "force_full": force_full,
+        "changed_new_lines": sum(len(lines) for lines in changed.values()),
+        "source": "repo",
+    }
+
+
+def classify_diff_text(diff_text, repo, max_files=DEFAULT_MAX_FILES,
+                       max_lines=DEFAULT_MAX_LINES):
+    """Classify a unified diff *text* (e.g. ``gh pr diff`` output)."""
+    changed = changed_lines_from_diff(diff_text, repo)
+    files, added, removed = _diff_text_files_and_counts(diff_text)
+    track, reason, force_full = _verdict(files, added, removed, max_files, max_lines)
+    return {
+        "version": VERSION,
+        "track": track,
+        "reason": reason,
+        "files": len(files),
+        "added": added,
+        "removed": removed,
+        "total": added + removed,
+        "max_files": max_files,
+        "max_lines": max_lines,
+        "base": None,
+        "force_full": force_full,
+        "changed_new_lines": sum(len(lines) for lines in changed.values()),
+        "source": "diff-text",
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="M4 lite fast-track diff-size classifier.")
+    parser.add_argument("--repo", default=".", help="repo to classify (default: .)")
+    parser.add_argument("--diff-base", default="main", help="base branch (default: main)")
+    parser.add_argument("--diff-file", default=None, help="classify a unified diff file instead of the repo diff")
+    parser.add_argument("--max-files", type=int, default=DEFAULT_MAX_FILES)
+    parser.add_argument("--max-lines", type=int, default=DEFAULT_MAX_LINES)
+    parser.add_argument("--uncommitted", action="store_true",
+                        help="include uncommitted working-tree edits (repo mode)")
+    parser.add_argument("--json", action="store_true", help="print the verdict as JSON (default output)")
+    args = parser.parse_args(argv)
+
+    repo = os.path.realpath(args.repo)
+    try:
+        if args.diff_file:
+            with open(args.diff_file, encoding="utf-8") as handle:
+                diff_text = handle.read()
+            result = classify_diff_text(diff_text, repo, args.max_files, args.max_lines)
+        else:
+            result = classify_repo(repo, args.diff_base, args.max_files, args.max_lines, args.uncommitted)
+    except (RuntimeError, OSError) as exc:
+        print(f"lite_track: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())