localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/session.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import uuid
+
+from .config import ensure_home_dirs
+from .paths import write_private
+
+
+Message = dict[str, str]
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class TaskState:
+    task_id: str
+    user_request: str
+    goal_type: str
+    task_kind: str
+    task_slug: str
+    goal_summary: str
+    success_criteria: list[str] = field(default_factory=list)
+    status: str = "in_progress"
+    current_stage: str = ""
+    active_port: int = 0
+    completion_status: str = ""
+    blocked_reason: str = ""
+    turn_count: int = 0
+    created_at: str = field(default_factory=utc_now)
+    updated_at: str = field(default_factory=utc_now)
+    final_response: str = ""
+
+
+@dataclass
+class SessionState:
+    session_id: str
+    repo_root: Path
+    created_at: str
+    profile: str = "e4b"
+    model: str = ""
+    messages: list[Message] = field(default_factory=list)
+    pinned_files: list[str] = field(default_factory=list)
+    last_assistant_text: str = ""
+    events: list[dict[str, str]] = field(default_factory=list)
+    current_task: TaskState | None = None
+    recent_tasks: list[TaskState] = field(default_factory=list)
+    # Working-memory checklist written by the todo_write tool: a list of
+    # {content, status, activeForm} dicts. Persisted so a resumed session
+    # keeps its plan; injected into context each round by the agent loop.
+    todos: list[dict] = field(default_factory=list)
+
+
+class SessionStore:
+    def __init__(self) -> None:
+        home = ensure_home_dirs()
+        self.sessions_dir = home / "sessions"
+
+    def create(self, repo_root: Path, profile: str = "e4b", model: str = "") -> SessionState:
+        session = SessionState(
+            session_id=uuid.uuid4().hex[:12],
+            repo_root=repo_root,
+            created_at=utc_now(),
+            profile=profile,
+            model=model,
+        )
+        self.save(session)
+        return session
+
+    def create_task(self, session: SessionState, *, user_request: str, goal_type: str,
+                    task_kind: str, task_slug: str,
+                    goal_summary: str, success_criteria: list[str]) -> TaskState:
+        task = TaskState(
+            task_id=uuid.uuid4().hex[:12],
+            user_request=user_request,
+            goal_type=goal_type,
+            task_kind=task_kind,
+            task_slug=task_slug,
+            goal_summary=goal_summary,
+            success_criteria=list(success_criteria),
+            turn_count=1,
+            current_stage="planning" if goal_type == "build_app" else "",
+        )
+        session.current_task = task
+        session.recent_tasks.append(task)
+        session.recent_tasks = session.recent_tasks[-20:]
+        self.save(session)
+        return task
+
+    def continue_task(self, session: SessionState, *, user_request: str,
+                      goal_type: str | None = None,
+                      goal_summary: str | None = None,
+                      success_criteria: list[str] | None = None) -> TaskState | None:
+        """Attach a follow-up user turn to the current task.
+
+        Coding agents should treat short corrections as continuations
+        of the task that just ran, not as fresh general chat tasks.
+        Keep the original task identity and only update turn-specific
+        goal details.
+        """
+        task = session.current_task
+        if task is None:
+            return None
+        task.user_request = f"{task.user_request}\n\nFollow-up: {user_request}".strip()
+        if goal_type is not None:
+            task.goal_type = goal_type
+        if goal_summary is not None:
+            task.goal_summary = goal_summary
+        if success_criteria is not None:
+            task.success_criteria = list(success_criteria)
+        task.status = "in_progress"
+        task.completion_status = ""
+        task.blocked_reason = ""
+        task.final_response = ""
+        task.turn_count += 1
+        task.updated_at = utc_now()
+        self.save(session)
+        return task
+
+    def update_task(self, session: SessionState, *, status: str | None = None,
+                    current_stage: str | None = None,
+                    active_port: int | None = None,
+                    completion_status: str | None = None,
+                    blocked_reason: str | None = None,
+                    final_response: str | None = None,
+                    increment_turn: bool = False) -> None:
+        task = session.current_task
+        if task is None:
+            return
+        if increment_turn:
+            task.turn_count += 1
+        if status is not None:
+            task.status = status
+        if current_stage is not None:
+            task.current_stage = current_stage
+        if active_port is not None:
+            task.active_port = active_port
+        if completion_status is not None:
+            task.completion_status = completion_status
+        if blocked_reason is not None:
+            task.blocked_reason = blocked_reason
+        if final_response is not None:
+            task.final_response = final_response
+        task.updated_at = utc_now()
+        self.save(session)
+
+    def load(self, session_id: str) -> SessionState:
+        path = self.sessions_dir / f"{session_id}.json"
+        data = json.loads(path.read_text())
+        current_task = data.get("current_task")
+        recent_tasks = data.get("recent_tasks", [])
+        def _load_task(payload: dict | None) -> TaskState | None:
+            if not isinstance(payload, dict):
+                return None
+            payload = dict(payload)
+            if "task_kind" not in payload:
+                payload.setdefault("task_kind", payload.get("goal_type", ""))
+                payload.setdefault("task_slug", payload.get("task_id", "task"))
+            payload.pop("large_write_escalations", None)
+            return TaskState(**payload)
+        return SessionState(
+            session_id=data["session_id"],
+            repo_root=Path(data["repo_root"]),
+            created_at=data["created_at"],
+            profile=data.get("profile", "e4b"),
+            model=data.get("model", ""),
+            messages=list(data.get("messages", [])),
+            pinned_files=list(data.get("pinned_files", [])),
+            last_assistant_text=data.get("last_assistant_text", ""),
+            events=list(data.get("events", [])),
+            current_task=_load_task(current_task),
+            recent_tasks=[task for task in (_load_task(t) for t in recent_tasks) if task is not None],
+            todos=list(data.get("todos", [])),
+        )
+
+    def save(self, session: SessionState) -> Path:
+        path = self.sessions_dir / f"{session.session_id}.json"
+        payload = {
+            "session_id": session.session_id,
+            "repo_root": str(session.repo_root),
+            "created_at": session.created_at,
+            "profile": session.profile,
+            "model": session.model,
+            "messages": session.messages,
+            "pinned_files": session.pinned_files,
+            "last_assistant_text": session.last_assistant_text,
+            "events": session.events,
+            "todos": session.todos,
+            "current_task": None if session.current_task is None else {
+                "task_id": session.current_task.task_id,
+                "user_request": session.current_task.user_request,
+                "goal_type": session.current_task.goal_type,
+                "task_kind": session.current_task.task_kind,
+                "task_slug": session.current_task.task_slug,
+                "goal_summary": session.current_task.goal_summary,
+                "success_criteria": session.current_task.success_criteria,
+                "status": session.current_task.status,
+                "current_stage": session.current_task.current_stage,
+                "active_port": session.current_task.active_port,
+                "completion_status": session.current_task.completion_status,
+                "blocked_reason": session.current_task.blocked_reason,
+                "turn_count": session.current_task.turn_count,
+                "created_at": session.current_task.created_at,
+                "updated_at": session.current_task.updated_at,
+                "final_response": session.current_task.final_response,
+            },
+            "recent_tasks": [
+                {
+                    "task_id": task.task_id,
+                    "user_request": task.user_request,
+                    "goal_type": task.goal_type,
+                    "task_kind": task.task_kind,
+                    "task_slug": task.task_slug,
+                    "goal_summary": task.goal_summary,
+                    "success_criteria": task.success_criteria,
+                    "status": task.status,
+                    "current_stage": task.current_stage,
+                    "active_port": task.active_port,
+                    "completion_status": task.completion_status,
+                    "blocked_reason": task.blocked_reason,
+                    "turn_count": task.turn_count,
+                    "created_at": task.created_at,
+                    "updated_at": task.updated_at,
+                    "final_response": task.final_response,
+                }
+                for task in session.recent_tasks[-20:]
+            ],
+        }
+        # Secret redaction chokepoint. The transcript is verbatim: a key
+        # the user pasted, or one a tool result echoed, would persist in
+        # cleartext across restarts. Scrub credential VALUES out of every
+        # string in the payload before it hits disk.
+        try:
+            from .redaction import scrub_obj
+            payload = scrub_obj(payload)
+        except Exception:
+            pass
+        # Session JSON is a verbatim transcript (every user message, every
+        # model response, every tool result) — owner-read only.
+        write_private(path, json.dumps(payload, indent=2))
+        return path
+
+    def list_sessions(self) -> list[tuple[str, str, str]]:
+        rows: list[tuple[str, str, str]] = []
+        for path in sorted(self.sessions_dir.glob("*.json"), reverse=True):
+            data = json.loads(path.read_text())
+            rows.append((data["session_id"], data["created_at"], data["repo_root"]))
+        return rows
+
+    def latest_for_repo(self, repo_root: Path) -> SessionState | None:
+        matches: list[SessionState] = []
+        for path in sorted(self.sessions_dir.glob("*.json"), reverse=True):
+            data = json.loads(path.read_text())
+            if Path(data["repo_root"]).resolve() == repo_root.resolve():
+                def _load_task(payload: dict | None) -> TaskState | None:
+                    if not isinstance(payload, dict):
+                        return None
+                    payload = dict(payload)
+                    if "task_kind" not in payload:
+                        payload.setdefault("task_kind", payload.get("goal_type", ""))
+                        payload.setdefault("task_slug", payload.get("task_id", "task"))
+                    payload.pop("large_write_escalations", None)
+                    return TaskState(**payload)
+                matches.append(
+                    SessionState(
+                        session_id=data["session_id"],
+                        repo_root=Path(data["repo_root"]),
+                        created_at=data["created_at"],
+                        profile=data.get("profile", "e4b"),
+                        model=data.get("model", ""),
+                        messages=list(data.get("messages", [])),
+                        pinned_files=list(data.get("pinned_files", [])),
+                        last_assistant_text=data.get("last_assistant_text", ""),
+                        events=list(data.get("events", [])),
+                        current_task=_load_task(data.get("current_task")),
+                        recent_tasks=[task for task in (_load_task(t) for t in data.get("recent_tasks", [])) if task is not None],
+                    )
+                )
+        return matches[0] if matches else None
+
+    def append_event(self, session: SessionState, event_type: str, detail: str, **metadata: str) -> None:
+        event = {
+            "time": utc_now(),
+            "type": event_type,
+            "detail": detail,
+        }
+        if metadata:
+            event.update({k: str(v) for k, v in metadata.items()})
+        session.events.append(event)
+        session.events = session.events[-200:]
+        self.save(session)

localcode/shell.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from dataclasses import dataclass
+from typing import Callable
+
+from ._subproc_env import clean_env
+
+DEFAULT_TIMEOUT = 120  # seconds
+MAX_OUTPUT_CHARS = 100_000
+
+
+@dataclass
+class ShellResult:
+    command: str
+    returncode: int
+    output: str
+    timed_out: bool = False
+
+
+def run_shell(
+    command: str,
+    cwd: str,
+    timeout: int = DEFAULT_TIMEOUT,
+    max_output: int = MAX_OUTPUT_CHARS,
+    on_output: Callable[[str], None] | None = None,
+) -> ShellResult:
+    env = clean_env()
+    env["LOCALCODE_SHELL"] = "1"  # let child processes know they're inside localcode
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=cwd,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            env=env,
+            preexec_fn=os.setsid if hasattr(os, "setsid") else None,
+        )
+    except Exception as exc:
+        return ShellResult(command=command, returncode=1, output=str(exc))
+
+    output_parts: list[str] = []
+    total_chars = 0
+    timed_out = False
+    assert process.stdout is not None
+
+    try:
+        for line in process.stdout:
+            output_parts.append(line)
+            total_chars += len(line)
+            if on_output is not None:
+                on_output(line.rstrip("\n"))
+            if total_chars >= max_output:
+                output_parts.append(f"\n...[output truncated at {max_output} chars]")
+                break
+        returncode = process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        # kill the entire process group
+        try:
+            if hasattr(os, "killpg"):
+                os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+            else:
+                process.kill()
+        except Exception:
+            pass
+        process.wait(timeout=5)
+        output_parts.append(f"\n...[command timed out after {timeout}s]")
+        returncode = 124
+    except Exception as exc:
+        output_parts.append(f"\n...[error: {exc}]")
+        returncode = process.wait()
+
+    return ShellResult(
+        command=command,
+        returncode=returncode,
+        output="".join(output_parts),
+        timed_out=timed_out,
+    )

localcode/skills/debug.md

@@ -0,0 +1,21 @@
+---
+name: debug
+description: Diagnose a bug — reproduce, read, hypothesize, fix, verify. Don't guess.
+when_to_use: User reports an error, a test is failing, unexpected output, or "this doesn't work".
+---
+
+Debug the reported issue. Follow in order, don't skip.
+
+1. **Reproduce.** Run the exact command or code path that surfaced the bug. Capture the actual error text — don't paraphrase it.
+2. **Read the relevant code.** Use `grep` / `read_file` to find the failing location. Read enough surrounding context to understand what was expected. (Use the `locate` skill if the target isn't obvious.)
+3. **Form ONE hypothesis** about the root cause. Write it in your reply before acting. "I think X because Y."
+4. **Make the minimal fix.** If you're wrong, the error will still be there — that's fine, iterate. (Rule 16: diagnose before retrying.)
+5. **Verify.** Re-run the reproduction command. If it now passes, use `edit-verified` / `run-tests` to confirm no regressions.
+
+Don't:
+- Guess fixes before reading the code.
+- "Fix" by disabling the failing assertion / test.
+- Add try/except that swallows the error.
+- Declare victory without re-running the repro.
+
+If you can't reproduce → ask for the exact command, environment, and full error output. Guessing wastes the user's time.

localcode/skills/edit-verified.md

@@ -0,0 +1,30 @@
+---
+name: edit-verified
+description: Make a code edit, then IMMEDIATELY verify it with syntax check + targeted test run before declaring done.
+when_to_use: Any time you call write_file or edit_file. This is the SWE-agent linter-gate pattern — the ablation evidence for small-model edit reliability.
+---
+
+Edit + verify in one atomic flow. Based on the SWE-agent linter-gate
+ablation (Yang et al. 2024) — guarded edits were the single largest ACI
+delta for small models.
+
+After every `edit_file` or `write_file`, run in this order:
+
+1. **Syntax check** (language-appropriate, non-blocking on stdout):
+   - Python: `python -c "import ast; ast.parse(open('<path>').read())"`
+   - TS/JS: `node --check <path>` (JS only) or `npx tsc --noEmit <path>`
+   - Go: `gofmt -e <path>` (errors if syntax bad)
+   - Rust: covered by `cargo check` in step 2
+
+2. **Targeted test run** — only tests that could plausibly exercise this change:
+   - Python: `pytest tests/test_<same-basename>.py -q` if it exists; else scope by keyword `pytest -k <function-name>`
+   - JS: `npm test -- <path-to-test>` or `vitest run <path>`
+   - Rust: `cargo test <test-name>`
+   - Go: `go test ./<pkg> -run <TestName>`
+
+3. **If step 1 or 2 fails**: report the error verbatim, fix, re-run. Do NOT claim done.
+   If step 1 passes and step 2 has no matching test: say "syntax OK, no test covers this change" — don't imply tests ran when they didn't (rule 17).
+
+4. **If no tests exist anywhere**: run the smallest reproducer that exercises the change (import the module, call the function with a trivial input). Report what you ran.
+
+Don't: claim "should work", "this is correct", or "the fix is straightforward" without the verify step. Don't re-run identical failing commands (rule 16).

localcode/skills/explain.md

@@ -0,0 +1,19 @@
+---
+name: explain
+description: Walk through a file or function for a newcomer — purpose, flow, gotchas, concise.
+when_to_use: User asks "explain X" / "how does Y work" / "I don't understand this". Also as a pre-edit orientation step before a non-trivial change.
+---
+
+Explain the target code.
+
+Structure:
+1. **Purpose** — one sentence. What problem does this solve?
+2. **Flow** — walk through the key logic in order of execution. Skip boilerplate (imports, trivial setters).
+3. **Gotchas** — 1-3 things a reader might miss:
+   - Non-obvious state mutations
+   - Side effects (I/O, globals, env vars)
+   - Subtle ordering dependencies
+   - Comments or naming that's misleading
+4. **What it does NOT do** — common misconceptions.
+
+Concise. Reference `path:line` for key chunks. End with "Ask follow-ups if anything is unclear" — don't re-summarize. Small models tend to repeat themselves; resist.

localcode/skills/finish-verified.md

@@ -0,0 +1,11 @@
+---
+name: finish-verified
+description: Finish a coding task once each requested outcome has concrete evidence.
+when_to_use: Before declaring a coding task complete or when work is drifting into optional polish.
+---
+
+1. Restate the requested outcomes as a short checklist.
+2. Attach one concrete proof to each outcome: a focused test, build, runtime probe, or exact file inspection.
+3. Treat exit code zero as shell success, not automatically task success. Check output for masked errors, fallbacks, skipped checks, and pipelines that hide an upstream failure.
+4. Resolve only missing requested outcomes. Do not add unrelated cleanup or polish.
+5. When every outcome has evidence, stop and report the evidence. If one cannot be proven, name that gap precisely.

localcode/skills/git-commit-safely.md

@@ -0,0 +1,30 @@
+---
+name: git-commit-safely
+description: Stage and commit safely — new commit not amend, no --no-verify, no `git add -A`, match project message style.
+when_to_use: User asks to commit. ALSO when they say "ship" / "save progress" / "wrap this up".
+---
+
+Create a git commit safely.
+
+Pre-commit checks (run in parallel):
+- `git status` — see everything that's changed. NEVER use `-uall` (memory issue on large repos).
+- `git diff --cached` — what's already staged.
+- `git log --oneline -5` — the project's message style. Match it.
+
+Rules:
+- **NEW commits only.** Don't `--amend` unless the user explicitly says "amend". A failed pre-commit hook means the commit did NOT happen — amending would rewrite the PREVIOUS commit and potentially destroy work.
+- **Never `git add -A` or `git add .`** — stage specific paths by name. Prevents accidentally committing `.env`, credentials, build output.
+- **Never skip hooks** (`--no-verify`, `--no-gpg-sign`). Fix the hook failure; don't bypass.
+- **Never force-push to main/master.** Warn before any force-push.
+
+Use a HEREDOC for multi-line messages:
+```
+git commit -m "$(cat <<'EOF'
+Summary line here.
+
+Optional body explaining why.
+EOF
+)"
+```
+
+If there's nothing staged, don't create an empty commit. Tell the user.

localcode/skills/locate.md

@@ -0,0 +1,21 @@
+---
+name: locate
+description: Find the exact file → class/function → line range to edit BEFORE reading or changing anything. Prevents aimless exploration.
+when_to_use: User asks to change/fix/review a specific behavior without naming the file, or the task is "where does X happen?". First step for any non-trivial edit on an unfamiliar repo.
+---
+
+Locate the target before acting. Based on the Agentless pattern
+(Xia et al. 2024) — the strongest small-model SWE-bench delta came
+from structured localization, not better planning.
+
+Process:
+1. **Surface search** — `grep -rn "<the name-ish thing from the request>" src/ --include='*.py'`. Start wide, don't assume the exact symbol spelling.
+2. **Narrow to a file** — pick the most-referenced or most-obvious match. If 3+ files look equally relevant, say so and ask the user which one.
+3. **Inside that file, find the region** — `grep -En 'def <name>|class <name>' <file>` to get the line number of the specific function/class. (`-E` uses extended regex so `|` alternates without backslash.)
+4. **Read a bounded window** — `read_file(path=<file>, offset=<start-10>, limit=80)`. Don't read the whole file; 2-3 bit models choke on 1500-line blobs.
+5. **State what you found BEFORE editing**: "Target: `path/to/file.py:123` — `def foo(...)`. Making change because <reason>."
+
+Anti-patterns (don't do):
+- `list_files(.)` as first move when the user named a specific behavior.
+- Reading a full file when a grep would pinpoint 40 lines.
+- Editing before stating what you found.

localcode/skills/plan-task.md

@@ -0,0 +1,51 @@
+---
+name: plan-task
+description: Decompose a multi-step task into a written checklist BEFORE coding. Read-and-update the checklist between steps.
+when_to_use: Task will likely take >4 tool calls — new feature, multi-file change, migration, debugging an unknown. Skip for trivial edits.
+disable-model-invocation: true
+---
+
+Externalize the plan. Small quantized models (2-3 bit) drift on long
+horizon tasks; a written plan becomes durable state they re-read.
+Evidence: Agentless externalized-plan beat agent loops at comparable
+compute (Xia et al. 2024); Voyager skill composition relies on the
+same principle.
+
+Format (output this as a markdown block BEFORE your first tool call):
+
+```
+Goal: <one sentence — what "done" looks like>
+
+Steps:
+1. [ ] <step 1 — small enough to verify independently>
+       verify: <command or assertion that proves it worked>
+2. [ ] <step 2>
+       verify: <...>
+3. [ ] <step 3>
+       verify: <...>
+
+Risks: <1-2 things that could go wrong>
+```
+
+Then execute ALL steps end-to-end in the SAME turn. After each step
+completes, immediately move to the next step's tool call — do NOT
+write a "progress so far / next steps" summary mid-task and stop. The
+plan is a checklist for YOU to follow continuously, not a milestone
+report for the user.
+
+Only stop before finishing all steps if:
+- A step's verify FAILS (then surface the failure and ask the user)
+- The user explicitly asked you to stop after step N
+- Tool execution returns REJECTED with a hard error you cannot recover from
+
+Otherwise: keep going until every step is done. Save the final
+summary for the very end, after the last step's verify passes.
+
+Keep the plan ≤6 steps. If it's longer, the task is probably two
+separate tasks — surface that to the user.
+
+Anti-patterns:
+- Re-planning after every step (wastes tokens).
+- A 12-step plan that covers every imaginable branch.
+- Writing "Current Progress / Next Steps" summary while steps remain.
+- Treating completed-this-turn as completed-the-whole-task.

localcode/skills/review.md

@@ -0,0 +1,22 @@
+---
+name: review
+description: Review code changes for correctness, security, performance, style — specific line-numbered feedback.
+when_to_use: User asks for a review. Also as a second-pass sanity check after a non-trivial diff. Prefer this over informal "does this look right?"
+---
+
+Review the diff (or scope the user named).
+
+Focus in priority order:
+1. **Correctness** — bugs, off-by-one, wrong conditions, unhandled edge cases.
+2. **Security** — injection (SQL/command/XSS), auth gaps, data exposure, unsanitized input crossing a trust boundary.
+3. **Performance** — obvious N+1 queries, unbounded loops, blocking I/O on hot paths.
+4. **Style** — matches project conventions? Naming consistent?
+
+Process:
+- `git diff` (or the user-named scope) first. Don't review what you haven't seen.
+- For each issue, cite `path:line` and explain why it matters.
+- Suggest fixes as `edit_file` calls when confident. Describe and defer when unsure.
+- Don't flag stylistic preferences that aren't in the project's style. Don't nitpick.
+- End with 1-line verdict: ship / fix-first / blocked.
+
+If the diff is clean, say so briefly. A 2-line "LGTM, one tiny suggestion" review beats a 40-line manufactured-concerns one.

localcode/skills/run-tests.md

@@ -0,0 +1,24 @@
+---
+name: run-tests
+description: Run the project's AUTOMATED TEST SUITE (pytest / jest / cargo test / go test) to verify correctness. DO NOT use this to launch or start a user-facing app — for running an app, execute its entry point directly via the bash tool.
+when_to_use: User explicitly says "run tests", "run the tests", "are tests passing", "check the tests". NOT when they say "run it" or "run the app" — that means launch the app, not the test suite.
+---
+
+Detect and run the test suite.
+
+Framework detection — check in this order:
+1. `pyproject.toml` has `[tool.pytest]` or `pytest` in dependencies → `pytest -q`
+2. `package.json` has a `test` script → `npm test` (or `pnpm`/`yarn` based on lockfile)
+3. `Cargo.toml` exists → `cargo test`
+4. `go.mod` exists → `go test ./...`
+5. Fallback: look for `tests/`, `test/`, `__tests__/`. Ask the user if unclear.
+
+Scope to affected files when possible (faster):
+- `pytest tests/test_foo.py` for a change to `src/foo.py`
+- `pytest -k <function-name>` for a change to a specific function
+- `cargo test <mod>::` for a single Rust module
+
+Report faithfully per rule 17:
+- **Passing**: "N tests ran, all passed."
+- **Failing**: quote the exact failure output (first 20 lines). Don't hide.
+- **Crashed** (didn't run): "Tests crashed during collection: <error>. I did NOT run them."