@surlymochan/evalid 0.5.18 → 0.5.19

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project are documented here. Detailed notes live in
 [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
+## [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,19 @@
 # Release Notes
 
+## 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

@@ -6692,6 +6692,11 @@ 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. Run the classifier
+                          first (python3 xflow/atoms/lite_track.py --repo .)
+                          and add --lite only when it says lite.
   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/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.19
 
 ## Passing Evidence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surlymochan/evalid",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "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/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,13 @@ export class WorkflowExecutor {
 
   // ─── Main execution loop ─────────────────────────────────────────────────
 
+  // M4 lite fast track: explicit `--lite` input only (the classifier in
+  // xflow/atoms/lite_track.py is the decision procedure; this flag is the
+  // enforcement switch). No silent auto-switching.
+  isLiteFastTrack() {
+    return this.input?.lite === true;
+  }
+
   // ─── Phase cost accounting ─────────────────────────────────────────────
 
   recordPhaseCost(phase, status, startedAtMs) {
@@ -121,6 +136,7 @@ export class WorkflowExecutor {
       workflow_run_id: this.runtime.workflowRunId,
       workflow: this.workflow.name,
       track: this.workflow.track,
+      lite_fast_track: this.isLiteFastTrack(),
       workflow_integrity: this.workflowManifest,
       max_parallel_agents: this.maxParallelAgents,
       parallel_policy: this.concurrencyPolicy.mode,
@@ -189,6 +205,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 +241,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 +350,7 @@ export class WorkflowExecutor {
       workflow_run_id: this.runtime.workflowRunId,
       workflow: this.workflow.name,
       track: this.workflow.track,
+      lite_fast_track: this.isLiteFastTrack(),
       workflow_integrity: this.workflowManifest,
       change_id: this.changeId || null,
       mission_id: this.runtime.missionId || null,
@@ -567,6 +627,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,247 @@
+#!/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``.
+
+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
+
+
+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)
+    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())