Enhance local-model assist documentation and add affected line tracking in candidate selection

Author: TMFNK

README.md

@@ -99,7 +99,17 @@ committed public sample outputs from a different input unless
 
 ## Local-model assist
 
-Start an OpenAI-compatible server bound to `127.0.0.1`, then run:
+The review loop needs a local OpenAI-compatible server on
+`http://127.0.0.1:8090/v1`. Any server works; the tested one is
+`llama-server` (llama.cpp) with a 2B-class quant:
+
+```bash
+llama-server -m Qwen3.8-2B-Q6_K.gguf --host 127.0.0.1 --port 8090
+```
+
+The default `--model` alias is `qwen3.8-2b-q6k` (Qwen3.8-2B distill,
+Q6_K, about 2 GB of weights). It runs on CPU: 16 SecOps-2k candidates
+take a few minutes after a short model load. Then run:
 
 ```bash
 uv run trail-lm-assist \
@@ -109,13 +119,16 @@ uv run trail-lm-assist \
   --out-csv results/raw/sample_lm.csv
 ```
 
-The default endpoint is `http://127.0.0.1:8090/v1` and the default model
-alias is `qwen3.8-2b-q6k`; override them with `--base-url` and `--model`.
-Only the literal `127.0.0.1` is accepted. The client bypasses environment
-proxies, rejects redirects, and sends requests one at a time. Use `--dry-run`
+The default endpoint is `http://127.0.0.1:8090/v1`; override endpoint
+and model with `--base-url` and `--model`. Only the literal
+`127.0.0.1` is accepted. The client bypasses environment proxies,
+rejects redirects, and sends requests one at a time. Use `--dry-run`
 to inspect candidates without contacting a model or writing outputs. The
-command aborts above 100 candidates unless `--max-candidates` is explicit.
-It refuses to replace an existing `*_lm.csv` unless `--force` is passed.
+command aborts above 100 candidates unless `--max-candidates` is explicit,
+and refuses to replace an existing `*_lm.csv` unless `--force` is passed.
+Accepts touching more than 10 lines are recorded as `needs-human` and
+never materialized; small-fragment merges still auto-apply. Reviews and
+assisted CSVs live under the ignored `results/raw/` directory.
 `scripts/lm_assist.py` remains a source-checkout compatibility wrapper.
 
 ## Metrics

docs/PHASE2-LM.md

@@ -24,10 +24,14 @@ human or a threshold accepts them. Nothing parses without a trail.
    over an OpenAI-compatible endpoint (`127.0.0.1`, same pattern as
    the Tier A harness server script). Ask one question: same event or
    two? No log leaves the machine.
-4. Append the proposal, cited audit lines, model identity, prompt version,
-   raw response, and accept/reject reason to `*.lm-review.jsonl`.
+4. Append the proposal, cited audit lines, affected-line count, model identity, prompt version,
+   raw response, and accept/reject/needs-human reason to `*.lm-review.jsonl`.
 5. If accepted decisions are applied, write a new assisted CSV. Do not
-   mutate the deterministic CSV or parse audit.
+   mutate the deterministic CSV or parse audit. Accepts touching more
+   than `MAX_AUTO_AFFECTED` lines (10) are recorded as `needs-human`
+   and never materialized: splitting one line out of a large pure
+   cluster, or merging two big clusters, rewrites too much grouping
+   for an unattended model verdict.
 
 The installed `trail-lm-assist` command implements this loop
 (`scripts/lm_assist.py` is a compatibility wrapper). It validates matching

tests/test_assist.py

@@ -83,6 +83,31 @@ def test_committed_sample_candidates_have_three_audit_cited_examples():
         )
 
 
+def test_candidates_carry_affected_line_counts():
+    contents = {1: "event a", 2: "event b", 3: "event c"}
+    records = []
+    rows = []
+    for i in range(1, 13):
+        content = contents.get(i, "event a")
+        decision = "matched" if i == 2 else "new_cluster"
+        records.append(
+            {
+                "line": i,
+                "cluster": "T1",
+                "decision": decision,
+                "similarity": 0.5 if i == 2 else 0.0,
+                "template": "event <*>",
+            }
+        )
+        rows.append(row(i, "T1", "event <*>", content))
+
+    (candidate,) = select_candidates(records, rows)
+
+    assert candidate.kind == "low_confidence"
+    assert candidate.target_line == 2
+    assert candidate.affected_lines == 12
+
+
 def test_candidates_without_three_examples_are_not_sent():
     records = [
         {
@@ -345,5 +370,97 @@ def test_apply_decisions_rejects_unequal_length_merge():
         apply_decisions(source, [{"change": "merge", "cluster_ids": ["T1", "T2"]}])
 
 
+def test_big_split_is_held_for_human_review():
+    candidate = Candidate(
+        kind="low_confidence",
+        cluster_ids=("T3",),
+        cited_audit_lines=(18, 3, 21),
+        examples=("target", "peer one", "peer two"),
+        templates=("event <*>",),
+        similarity=0.5,
+        target_line=18,
+        affected_lines=410,
+    )
+    assert decide(candidate, "TWO") == (
+        "needs-human",
+        "none",
+        "split of 410 lines in T3 held for human review",
+    )
+
+
+def test_big_merge_is_held_for_human_review():
+    candidate = Candidate(
+        kind="near_duplicate",
+        cluster_ids=("T7", "T11"),
+        cited_audit_lines=(7, 15, 10),
+        examples=("event a", "event b", "event c"),
+        templates=("event <*>", "event <*>"),
+        similarity=None,
+        target_line=None,
+        affected_lines=160,
+    )
+    assert decide(candidate, "SAME") == (
+        "needs-human",
+        "none",
+        "merge of 160 lines in T7,T11 held for human review",
+    )
+
+
+def test_small_accepts_still_apply():
+    split = Candidate(
+        kind="low_confidence",
+        cluster_ids=("T1",),
+        cited_audit_lines=(2, 1, 3),
+        examples=("target", "peer one", "peer two"),
+        templates=("event <*>",),
+        similarity=0.5,
+        target_line=2,
+        affected_lines=3,
+    )
+    assert decide(split, "TWO") == ("accept", "split", "model said TWO")
+    merge = Candidate(
+        kind="near_duplicate",
+        cluster_ids=("T1", "T2"),
+        cited_audit_lines=(1, 2, 3),
+        examples=("event a", "event b", "event c"),
+        templates=("event <*>", "event <*>"),
+        similarity=None,
+        target_line=None,
+        affected_lines=6,
+    )
+    assert decide(merge, "SAME") == ("accept", "merge", "model said SAME")
+
+
+def test_needs_human_records_are_not_materialized():
+    source = [
+        row(1, "T1", "event <*>", "event a"),
+        row(2, "T1", "event <*>", "event b"),
+        row(3, "T2", "event <*>", "event c"),
+    ]
+    reviews = [
+        {
+            "decision": "needs-human",
+            "change": "none",
+            "target_line": 2,
+            "cluster_ids": ["T1"],
+        },
+        {
+            "decision": "needs-human",
+            "change": "none",
+            "target_line": None,
+            "cluster_ids": ["T1", "T2"],
+        },
+    ]
+
+    assisted = apply_decisions(source, reviews)
+
+    assert [item["EventId"] for item in assisted] == ["T1", "T1", "T2"]
+    assert [item["EventTemplate"] for item in assisted] == [
+        "event <*>",
+        "event <*>",
+        "event <*>",
+    ]
+
+
 def test_apply_decisions_accepts_empty_parse():
     assert apply_decisions([], []) == []

trailparse/assist.py

@@ -17,6 +17,12 @@
 LOW_SIMILARITY = 0.7
 MAX_EXAMPLES = 3
 DEFAULT_MAX_CANDIDATES = 100
+# Auto-apply ceiling: a model accept touching more lines than this is
+# recorded as needs-human and never materialized. Splitting one line
+# out of a large pure cluster (or merging two big ones) rewrites the
+# grouping of every line involved; that blast radius needs a human.
+# Small sudo-fragment merges (a handful of lines) still auto-apply.
+MAX_AUTO_AFFECTED = 10
 _WORD = re.compile(r"[A-Za-z]+")
 _THINK = re.compile(r"<think>.*?</think>", re.I | re.S)
 
@@ -30,6 +36,11 @@ class Candidate:
     templates: tuple[str, ...]
     similarity: float | None
     target_line: int | None
+    # Lines whose grouping would change if this candidate is applied:
+    # the whole cluster for a split, both clusters for a merge.
+    # select_candidates always sets it; the 0 default keeps older
+    # unit-test constructions on the previous accept/reject behavior.
+    affected_lines: int = 0
 
 
 def token_edit_distance(left: list[str], right: list[str]) -> int:
@@ -215,6 +226,7 @@ def select_candidates(
                 templates=(templates[cid],),
                 similarity=rec["similarity"],
                 target_line=target_line,
+                affected_lines=len(members[cid]),
             )
         )
         if len(candidates) > max_candidates:
@@ -239,6 +251,7 @@ def select_candidates(
                 templates=(templates[left_id], templates[right_id]),
                 similarity=None,
                 target_line=None,
+                affected_lines=len(members[left_id]) + len(members[right_id]),
             )
         )
     return candidates
@@ -287,13 +300,28 @@ def decide(candidate: Candidate, proposal: str | None) -> tuple[str, str, str]:
         return "reject", "none", "unparsed model reply"
     if candidate.kind == "low_confidence":
         if proposal == "TWO":
+            if candidate.affected_lines > MAX_AUTO_AFFECTED:
+                return (
+                    "needs-human",
+                    "none",
+                    f"split of {candidate.affected_lines} lines in "
+                    f"{candidate.cluster_ids[0]} held for human review",
+                )
             return "accept", "split", "model said TWO"
         return "reject", "none", "model said SAME; keep miner join"
     if proposal == "SAME":
         if len(candidate.templates[0].split()) != len(
             candidate.templates[1].split()
         ):
             return "reject", "none", "unequal-length merge is not materialized"
+        if candidate.affected_lines > MAX_AUTO_AFFECTED:
+            clusters = ",".join(candidate.cluster_ids)
+            return (
+                "needs-human",
+                "none",
+                f"merge of {candidate.affected_lines} lines in "
+                f"{clusters} held for human review",
+            )
         return "accept", "merge", "model said SAME"
     return "reject", "none", "model said TWO; keep clusters split"
 
@@ -317,6 +345,7 @@ def review_candidate(
         "cluster_ids": list(candidate.cluster_ids),
         "cited_audit_lines": list(candidate.cited_audit_lines),
         "target_line": candidate.target_line,
+        "affected_lines": candidate.affected_lines,
         "templates": list(candidate.templates),
         "examples": list(candidate.examples),
         "similarity": candidate.similarity,