devcouncil 0.2.0 → 0.2.1

package/src/devcouncil/repo/sca.py

@@ -1,374 +0,0 @@
-"""Best-effort software-composition analysis (dependency vulnerability awareness).
-
-DevCouncil does not bundle a vulnerability database and must never reach the
-network on its own initiative. This module is a thin, *offline-safe* wrapper
-around whatever auditors the developer already has installed (``pip-audit``,
-``npm audit``, ``osv-scanner``): it detects the auditor + the project's
-lockfiles, runs the local tool with a bounded timeout and a sanitized subprocess
-environment, and parses the output into a structured list of dependency risks.
-
-Design contract:
-- **Never raises.** Every public entry point swallows tool/parse/OS errors and
-  degrades to an empty result, so a missing tool or malformed output can never
-  break ``dev map`` / prompt building / CI scaffolding.
-- **Opt-in / local-only by default.** Nothing here runs unless a caller asks for
-  it; ``ScaScanner.scan`` is the only thing that shells out.
-- **Injectable runner.** ``ScaScanner`` takes an ``auditor_runner`` callable so
-  tests (and offline environments) can feed canned auditor output without any
-  network access or installed tools.
-"""
-
-from __future__ import annotations
-
-import json
-import shutil
-import subprocess
-from collections.abc import Callable
-from dataclasses import asdict, dataclass
-from pathlib import Path
-
-from devcouncil.utils.subprocess_env import clean_subprocess_env
-
-# Default per-auditor timeout. Bounded so a slow/hung auditor can't stall the map.
-DEFAULT_TIMEOUT = 60
-
-
-@dataclass(frozen=True)
-class DependencyRisk:
-    """A single dependency vulnerability finding (auditor-agnostic shape)."""
-
-    package: str
-    installed_version: str
-    severity: str
-    advisory_id: str
-    summary: str
-
-    def as_dict(self) -> dict[str, str]:
-        return asdict(self)
-
-
-@dataclass(frozen=True)
-class AuditorResult:
-    """Raw output of one auditor invocation; ``returncode`` < 0 means it didn't run."""
-
-    returncode: int
-    stdout: str
-    stderr: str
-
-
-# An auditor runner takes the auditor's argv and the project root, and returns the
-# captured result. Injected so tests need no installed tools or network access.
-AuditorRunner = Callable[[list[str], Path], AuditorResult]
-
-
-@dataclass(frozen=True)
-class _Auditor:
-    name: str  # logical auditor name (pip-audit / npm / osv-scanner)
-    executable: str  # the executable to look for on PATH
-    stack: str  # which stack it covers (python / node)
-    # Lockfiles whose presence makes this auditor relevant for the repo.
-    lockfiles: tuple[str, ...]
-
-
-# Ordered so the most specific / preferred auditor for each stack comes first.
-_AUDITORS: tuple[_Auditor, ...] = (
-    _Auditor(
-        name="pip-audit",
-        executable="pip-audit",
-        stack="python",
-        lockfiles=("uv.lock", "requirements.txt", "poetry.lock"),
-    ),
-    _Auditor(
-        name="npm",
-        executable="npm",
-        stack="node",
-        lockfiles=("package-lock.json", "yarn.lock", "pnpm-lock.yaml"),
-    ),
-    _Auditor(
-        name="osv-scanner",
-        executable="osv-scanner",
-        stack="any",
-        lockfiles=(
-            "uv.lock",
-            "requirements.txt",
-            "poetry.lock",
-            "package-lock.json",
-            "yarn.lock",
-            "pnpm-lock.yaml",
-            "go.sum",
-            "Cargo.lock",
-        ),
-    ),
-)
-
-
-def _default_runner(timeout: int) -> AuditorRunner:
-    """Real subprocess runner: bounded timeout + sanitized env; never raises."""
-
-    def run(argv: list[str], project_root: Path) -> AuditorResult:
-        try:
-            completed = subprocess.run(
-                argv,
-                cwd=project_root,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                timeout=timeout,
-                env=clean_subprocess_env(),
-            )
-        except subprocess.TimeoutExpired:
-            return AuditorResult(returncode=-1, stdout="", stderr="timed out")
-        except (FileNotFoundError, OSError) as exc:
-            return AuditorResult(returncode=-1, stdout="", stderr=str(exc))
-        return AuditorResult(
-            returncode=completed.returncode,
-            stdout=completed.stdout or "",
-            stderr=completed.stderr or "",
-        )
-
-    return run
-
-
-class ScaScanner:
-    """Detects locally-available auditors + lockfiles and runs them best-effort.
-
-    Pass ``auditor_runner`` to inject the subprocess behaviour (tests do this to
-    return canned auditor output offline). When omitted, a real bounded-timeout,
-    clean-env subprocess runner is used.
-    """
-
-    def __init__(
-        self,
-        project_root: Path,
-        *,
-        auditor_runner: AuditorRunner | None = None,
-        timeout: int = DEFAULT_TIMEOUT,
-        which: Callable[[str], str | None] = shutil.which,
-    ):
-        self.project_root = Path(project_root)
-        self.timeout = timeout
-        self._which = which
-        # When a runner is injected (tests / offline), the runner itself decides
-        # whether a tool "exists"; we skip the PATH gate so canned output flows.
-        self._injected = auditor_runner is not None
-        self._runner: AuditorRunner = auditor_runner or _default_runner(timeout)
-
-    # -- detection -----------------------------------------------------------
-
-    def _has_lockfile(self, auditor: _Auditor) -> bool:
-        return any((self.project_root / name).exists() for name in auditor.lockfiles)
-
-    def _is_runnable(self, auditor: _Auditor) -> bool:
-        """Relevant to the repo (lockfile present) and runnable (on PATH or injected)."""
-        if not self._has_lockfile(auditor):
-            return False
-        return self._injected or self._which(auditor.executable) is not None
-
-    def available_auditors(self) -> list[str]:
-        """Names of auditors that are both runnable AND relevant to this repo.
-
-        An auditor counts as runnable when its executable is on PATH (real
-        installs) OR when a custom runner is injected (tests/offline).
-        """
-        seen: set[str] = set()
-        ordered: list[str] = []
-        for auditor in _AUDITORS:
-            if self._is_runnable(auditor) and auditor.name not in seen:
-                seen.add(auditor.name)
-                ordered.append(auditor.name)
-        return ordered
-
-    # -- scanning ------------------------------------------------------------
-
-    def scan(self) -> list[DependencyRisk]:
-        """Run every available auditor and merge their findings. Never raises."""
-        risks: list[DependencyRisk] = []
-        seen: set[tuple[str, str, str]] = set()
-        for auditor in _AUDITORS:
-            if not self._is_runnable(auditor):
-                continue
-            try:
-                result = self._runner(self._argv_for(auditor), self.project_root)
-                parsed = self._parse(auditor, result)
-            except Exception:
-                # Best-effort contract: a broken auditor/parse must not propagate.
-                continue
-            for risk in parsed:
-                key = (risk.package, risk.installed_version, risk.advisory_id)
-                if key in seen:
-                    continue
-                seen.add(key)
-                risks.append(risk)
-        return risks
-
-    @staticmethod
-    def _argv_for(auditor: _Auditor) -> list[str]:
-        if auditor.name == "pip-audit":
-            return ["pip-audit", "--format", "json"]
-        if auditor.name == "npm":
-            return ["npm", "audit", "--json"]
-        if auditor.name == "osv-scanner":
-            return ["osv-scanner", "--format", "json", "."]
-        return [auditor.executable]
-
-    def _parse(self, auditor: _Auditor, result: AuditorResult) -> list[DependencyRisk]:
-        if result.returncode < 0 or not result.stdout.strip():
-            return []
-        try:
-            data = json.loads(result.stdout)
-        except (json.JSONDecodeError, ValueError):
-            return []
-        if auditor.name == "pip-audit":
-            return _parse_pip_audit(data)
-        if auditor.name == "npm":
-            return _parse_npm_audit(data)
-        if auditor.name == "osv-scanner":
-            return _parse_osv_scanner(data)
-        return []
-
-
-# ----------------------------------------------------------------------------
-# Per-auditor parsers. Each is defensive: unknown shapes yield no risks.
-# ----------------------------------------------------------------------------
-
-
-def _coerce_str(value: object, default: str = "") -> str:
-    if value is None:
-        return default
-    if isinstance(value, str):
-        return value
-    return str(value)
-
-
-def _parse_pip_audit(data: object) -> list[DependencyRisk]:
-    """pip-audit ``--format json`` -> dependencies[].vulns[]."""
-    risks: list[DependencyRisk] = []
-    deps: object
-    if isinstance(data, dict):
-        deps = data.get("dependencies", [])
-    elif isinstance(data, list):
-        deps = data  # older pip-audit emitted a bare list
-    else:
-        return []
-    if not isinstance(deps, list):
-        return []
-    for dep in deps:
-        if not isinstance(dep, dict):
-            continue
-        name = _coerce_str(dep.get("name"))
-        version = _coerce_str(dep.get("version"))
-        vulns = dep.get("vulns") or []
-        if not isinstance(vulns, list):
-            continue
-        for vuln in vulns:
-            if not isinstance(vuln, dict):
-                continue
-            risks.append(
-                DependencyRisk(
-                    package=name,
-                    installed_version=version,
-                    severity=_coerce_str(vuln.get("severity"), "unknown") or "unknown",
-                    advisory_id=_coerce_str(vuln.get("id"), "UNKNOWN") or "UNKNOWN",
-                    summary=_coerce_str(vuln.get("description") or vuln.get("summary")),
-                )
-            )
-    return risks
-
-
-def _parse_npm_audit(data: object) -> list[DependencyRisk]:
-    """npm audit ``--json`` (npm v7+) -> vulnerabilities{ name: {...} }."""
-    if not isinstance(data, dict):
-        return []
-    vulnerabilities = data.get("vulnerabilities")
-    if not isinstance(vulnerabilities, dict):
-        return []
-    risks: list[DependencyRisk] = []
-    for name, info in vulnerabilities.items():
-        if not isinstance(info, dict):
-            continue
-        severity = _coerce_str(info.get("severity"), "unknown") or "unknown"
-        version = _coerce_str(info.get("range"))
-        via = info.get("via") or []
-        advisory_id = "UNKNOWN"
-        summary = ""
-        if isinstance(via, list):
-            for entry in via:
-                if isinstance(entry, dict):
-                    source = entry.get("source") or entry.get("url")
-                    advisory_id = _coerce_str(source, "UNKNOWN") or "UNKNOWN"
-                    summary = _coerce_str(entry.get("title"))
-                    break
-        risks.append(
-            DependencyRisk(
-                package=_coerce_str(name),
-                installed_version=version,
-                severity=severity,
-                advisory_id=advisory_id,
-                summary=summary,
-            )
-        )
-    return risks
-
-
-def _parse_osv_scanner(data: object) -> list[DependencyRisk]:
-    """osv-scanner ``--format json`` -> results[].packages[].vulnerabilities[]."""
-    if not isinstance(data, dict):
-        return []
-    results = data.get("results")
-    if not isinstance(results, list):
-        return []
-    risks: list[DependencyRisk] = []
-    for result in results:
-        if not isinstance(result, dict):
-            continue
-        packages = result.get("packages") or []
-        if not isinstance(packages, list):
-            continue
-        for package in packages:
-            if not isinstance(package, dict):
-                continue
-            pkg_info = package.get("package") or {}
-            name = _coerce_str(pkg_info.get("name")) if isinstance(pkg_info, dict) else ""
-            version = _coerce_str(pkg_info.get("version")) if isinstance(pkg_info, dict) else ""
-            vulns = package.get("vulnerabilities") or []
-            if not isinstance(vulns, list):
-                continue
-            for vuln in vulns:
-                if not isinstance(vuln, dict):
-                    continue
-                risks.append(
-                    DependencyRisk(
-                        package=name,
-                        installed_version=version,
-                        severity=_osv_severity(vuln),
-                        advisory_id=_coerce_str(vuln.get("id"), "UNKNOWN") or "UNKNOWN",
-                        summary=_coerce_str(vuln.get("summary") or vuln.get("details")),
-                    )
-                )
-    return risks
-
-
-def _osv_severity(vuln: dict) -> str:
-    severity = vuln.get("severity")
-    if isinstance(severity, list) and severity:
-        first = severity[0]
-        if isinstance(first, dict):
-            return _coerce_str(first.get("type") or first.get("score"), "unknown") or "unknown"
-    if isinstance(severity, str) and severity:
-        return severity
-    return "unknown"
-
-
-def scan_dependency_risks(
-    project_root: Path,
-    *,
-    auditor_runner: AuditorRunner | None = None,
-    timeout: int = DEFAULT_TIMEOUT,
-) -> list[dict[str, str]]:
-    """Convenience entry point: returns dependency risks as plain dicts. Never raises."""
-    try:
-        scanner = ScaScanner(project_root, auditor_runner=auditor_runner, timeout=timeout)
-        return [risk.as_dict() for risk in scanner.scan()]
-    except Exception:
-        return []

package/src/devcouncil/reporting/github_check.py

@@ -1,32 +0,0 @@
-from devcouncil.artifacts.graph import ArtifactGraph
-
-class GitHubCheckGenerator:
-    """Generates GitHub Checks API payloads."""
-    
-    @staticmethod
-    def generate(graph: ArtifactGraph) -> dict:
-        summary = graph.coverage_summary()
-        blocking_gaps = graph.blocking_gaps()
-        
-        status = "completed"
-        conclusion = "failure" if summary["blocking_gaps"] > 0 else "success"
-        
-        text = f"**Requirements**: {summary['total_requirements']} | "
-        text += f"**Tasks**: {summary['total_tasks']} | "
-        text += f"**Gaps**: {summary['blocking_gaps']} blocking\n\n"
-        
-        if blocking_gaps:
-            text += "### Blocking Gaps\n"
-            for gap in blocking_gaps:
-                text += f"- **{gap.id}**: {gap.description}\n"
-                
-        return {
-            "name": "DevCouncil Verification",
-            "status": status,
-            "conclusion": conclusion,
-            "output": {
-                "title": f"DevCouncil: {conclusion.capitalize()}",
-                "summary": f"Found {summary['blocking_gaps']} blocking gaps.",
-                "text": text
-            }
-        }

package/src/devcouncil/reporting/json_report.py

@@ -1,30 +0,0 @@
-import json
-from devcouncil.artifacts.graph import ArtifactGraph
-
-class JsonReportGenerator:
-    """Generates a JSON evidence report."""
-    
-    @staticmethod
-    def generate(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        summary = graph.coverage_summary()
-        live_blockers = len((live_review or {}).get("blocking_cards", []))
-        
-        # Three honest states (see markdown_report for rationale):
-        #   blocked    - positive evidence of a problem.
-        #   incomplete - nothing failing, but not every AC has passing evidence.
-        #   passed     - no blocking gaps and every AC proven.
-        if summary["blocking_gaps"] > 0 or live_blockers > 0:
-            verdict = "blocked"
-        elif summary["ac_without_evidence"] > 0:
-            verdict = "incomplete"
-        else:
-            verdict = "passed"
-        report = {
-            "verdict": verdict,
-            "coverage_summary": summary,
-            "blocking_gaps": [g.model_dump() for g in graph.blocking_gaps()]
-        }
-        if live_review is not None:
-            report["live_review"] = live_review
-        
-        return json.dumps(report, indent=2)

package/src/devcouncil/reporting/markdown_report.py

@@ -1,83 +0,0 @@
-from devcouncil.artifacts.graph import ArtifactGraph
-
-class MarkdownReportGenerator:
-    """Generates a Markdown evidence report."""
-
-    MAX_INLINE_GAPS = 25
-    
-    @staticmethod
-    def generate(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        summary = graph.coverage_summary()
-        live_blockers = (live_review or {}).get("blocking_cards", [])
-
-        unverified_ac = summary["ac_without_evidence"]
-
-        md_output = "# DevCouncil Report\n\n"
-        md_output += "## Verdict\n"
-        # Three honest states:
-        #   Blocked    - positive evidence of a problem (blocking gaps / live blockers).
-        #   Incomplete - nothing is failing, but not every acceptance criterion has
-        #                passing evidence yet (un-run, or could not be verified). NOT
-        #                a failure — distinguishing this from Blocked is what keeps the
-        #                "blocked" signal trustworthy (no false negatives on correct work).
-        #   Passed     - no blocking gaps and every acceptance criterion is proven.
-        if summary["blocking_gaps"] > 0 or live_blockers:
-            parts = []
-            if summary["blocking_gaps"] > 0:
-                parts.append(f"{summary['blocking_gaps']} high-severity gap(s)")
-            if live_blockers:
-                parts.append(f"{len(live_blockers)} live-review blocker(s)")
-            md_output += f"**Blocked**: {', '.join(parts)} remain.\n\n"
-        elif unverified_ac > 0:
-            md_output += (
-                f"**Incomplete**: nothing is failing, but {unverified_ac} acceptance "
-                "criterion(s) lack passing evidence (un-run or unverifiable). Not ready "
-                "for release.\n\n"
-            )
-        else:
-            md_output += "**Passed**: Ready for release.\n\n"
-
-        md_output += "## Coverage Summary\n"
-        md_output += f"- **Requirements**: {summary['total_requirements']} ({summary['requirements_without_tasks']} unmapped)\n"
-        md_output += f"- **Tasks**: {summary['total_tasks']} ({summary['tasks_without_requirements']} orphaned)\n"
-        md_output += f"- **Evidence**: {summary['total_ac'] - summary['ac_without_evidence']}/{summary['total_ac']} AC verified\n\n"
-
-        md_output += "## Requirements Coverage Table\n"
-        md_output += "| Requirement | Task Mapping | Status |\n"
-        md_output += "|---|---|---|\n"
-        
-        for req in graph.requirements.values():
-            linked_tasks = [t for t in graph.tasks.values() if req.id in t.requirement_ids]
-            task_str = ", ".join([t.id for t in linked_tasks]) if linked_tasks else "*None*"
-            status_str = "Covered" if linked_tasks else "**Unmapped**"
-            md_output += f"| {req.id} {req.title} | {task_str} | {status_str} |\n"
-                    
-        md_output += "\n## Blocking Gaps\n"
-        blocking_gaps = graph.blocking_gaps()
-        if not blocking_gaps:
-            md_output += "None.\n"
-        else:
-            for gap in blocking_gaps[:MarkdownReportGenerator.MAX_INLINE_GAPS]:
-                md_output += f"### {gap.id}: {gap.description}\n"
-                md_output += f"**Recommended fix**: {gap.recommended_fix}\n\n"
-            if len(blocking_gaps) > MarkdownReportGenerator.MAX_INLINE_GAPS:
-                remaining = len(blocking_gaps) - MarkdownReportGenerator.MAX_INLINE_GAPS
-                md_output += f"_Omitted {remaining} additional blocking gap(s). Use JSON output for the full list._\n"
-
-        if live_review is not None:
-            md_output += "\n## Live Review\n"
-            cards = live_review.get("cards", {})
-            md_output += f"- **Pending signals**: {live_review.get('pending_signals', 0)}\n"
-            md_output += f"- **Open cards**: {cards.get('open', 0)}\n"
-            md_output += f"- **Open critical cards**: {cards.get('critical_open', 0)}\n"
-            if not live_blockers:
-                md_output += "- **Blocking cards in scope**: None.\n"
-            else:
-                md_output += "\n### Blocking Live-Review Cards\n"
-                for card in live_blockers[:MarkdownReportGenerator.MAX_INLINE_GAPS]:
-                    md_output += f"- **{card['id']}**"
-                    if card.get("task_id"):
-                        md_output += f" (`{card['task_id']}`)"
-                    md_output += f": {card['summary']}\n"
-                
-        return md_output

package/src/devcouncil/reporting/report_builder.py

@@ -1,14 +0,0 @@
-from devcouncil.artifacts.graph import ArtifactGraph
-from devcouncil.reporting.markdown_report import MarkdownReportGenerator
-from devcouncil.reporting.json_report import JsonReportGenerator
-
-class ReportBuilder:
-    """Builds reports in various formats from the artifact graph."""
-    
-    @staticmethod
-    def build_markdown(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        return MarkdownReportGenerator.generate(graph, live_review=live_review)
-
-    @staticmethod
-    def build_json(graph: ArtifactGraph, live_review: dict | None = None) -> str:
-        return JsonReportGenerator.generate(graph, live_review=live_review)

package/src/devcouncil/skills/__init__.py

@@ -1,19 +0,0 @@
-"""DevCouncil skills library."""
-
-from devcouncil.skills.registry import (
-    Skill,
-    get_skill,
-    load_skills,
-    render_preamble,
-    scaffold_skills,
-    select_skills,
-)
-
-__all__ = [
-    "Skill",
-    "get_skill",
-    "load_skills",
-    "render_preamble",
-    "scaffold_skills",
-    "select_skills",
-]

package/src/devcouncil/skills/library/README.md

@@ -1,46 +0,0 @@
-# DevCouncil skills library
-
-Each `*.md` file here (except this README) is a **skill**: reusable guidance that
-DevCouncil selects for a goal/repo, embeds into `dev prompt` output, and scaffolds
-into a target repo's `.claude/skills/<name>/SKILL.md`.
-
-A skill is a markdown file with YAML frontmatter:
-
-```markdown
----
-name: my-domain            # required — unique slug; files without a name are ignored
-title: My Domain Intake    # optional human title
-description: One-line directive shown in `dev skills` and embedded into prompts.
-always: false              # true = always selected (only core-engineering uses this)
-triggers:                  # how this skill is auto-selected (omit for always-on)
-  keywords: [foo, bar]     # matched against the goal text (case-insensitive substring)
-  globs: ["*.foo", "build.bar"]   # matched against repo file basenames
----
-
-# Body
-
-The full guidance the agent reads. For domain skills, write a "senior-dev intake":
-what current versions, deprecations, recommended libraries, official guidelines, and
-CLI/build tools to confirm *before* writing code.
-```
-
-## Adding a skill
-
-1. Create `<name>.md` with the frontmatter above.
-2. Choose triggers: `keywords` (goal text) and/or `globs` (repo files). Both are ORed.
-3. Verify: `dev skills` lists it; `dev skills show <name>` prints it.
-
-Selection is keyword-based inside `dev prompt` (fast, no repo walk) and
-keyword-plus-file-based for `dev skills` / `dev skills scaffold` / init scaffolding.
-Keep `description` actionable — it is what the agent sees inline in the task prompt.
-
-## Repo-local skills
-
-You don't have to edit this packaged library to add a skill. Drop your own
-`SKILL.md` (same frontmatter) into a project's **`.claude/skills/<name>/SKILL.md`**
-(or `.devcouncil/skills/*.md`) and DevCouncil discovers it automatically — it shows
-up in `dev skills` (source `repo`), participates in selection, and is folded into the
-codebase-aware prompt enhancer and the task prompts. A repo-local skill **overrides a
-packaged skill with the same name**, so a team can keep its own house rules for
-`android`/`web`/etc. Give it `triggers` (or `always: true`) if you want it
-auto-selected; without triggers it stays available but dormant.

package/src/devcouncil/skills/library/ai-training.md

@@ -1,50 +0,0 @@
----
-name: ai-training
-title: AI / ML Model Training Intake
-description: Before writing model-training code, retrieve current framework versions, hardware/driver constraints, deprecations, dataset/eval practices, and the right tooling — like a senior ML engineer.
-triggers:
-  keywords: [train, training, model, pytorch, torch, tensorflow, keras, jax, huggingface, transformers, finetune, "fine-tune", dataset, llm, ml, cuda, embedding]
-  globs: ["*.ipynb", "train.py", "trainer.py", "requirements.txt", "environment.yml", "pyproject.toml", "accelerate*.yaml", "deepspeed*.json"]
----
-
-# AI / ML Model Training Intake
-
-Do this **before** writing or changing model-training code. Frameworks, hardware
-drivers, and recommended recipes change frequently, and silent version mismatches
-waste expensive compute. Confirm against the framework docs and the project's
-environment files.
-
-## Establish current state first
-
-1. **Framework & environment** — read `requirements.txt` / `environment.yml` /
-   `pyproject.toml`: the framework (PyTorch, TensorFlow/Keras, JAX, Hugging Face
-   `transformers`/`accelerate`/`peft`), its version, Python version, and the
-   CUDA/cuDNN/ROCm requirement. Match the existing stack.
-2. **Hardware & precision** — available accelerators (GPU/TPU), memory budget, and
-   the precision strategy (fp32/fp16/bf16, mixed precision, quantization). Confirm the
-   training approach fits the hardware (single-GPU vs distributed: DDP/FSDP/DeepSpeed).
-3. **Deprecations & API shifts** — note moved/renamed APIs (e.g. `transformers`
-   trainer/argument changes, optimizer/scheduler APIs, dataset loaders) and avoid
-   patterns deprecated in the installed version.
-4. **Recommended practices** — reproducibility (seed, deterministic flags, pinned
-   versions), data pipeline (streaming vs in-memory, tokenization), checkpointing and
-   resume, and evaluation (held-out split, the metric that actually matters, no leakage
-   between train/val/test).
-5. **Cost & safety** — estimate compute/time before launching long runs; log metrics
-   (Weights & Biases / TensorBoard) and checkpoint so a crash isn't a total loss.
-
-## Tools
-
-- `python`/`accelerate launch`/`torchrun` for training entry points.
-- Experiment tracking (W&B, MLflow, TensorBoard) and `nvidia-smi` for GPU monitoring.
-- `datasets`/`dvc` for data, and a pinned environment (`uv`/`conda`/`pip-tools`).
-
-## What to record before coding
-
-- Framework + version, Python + CUDA versions, and the hardware/precision plan.
-- Deprecated APIs to avoid and their current replacements.
-- How the run is validated: the eval split, the metric, the checkpoint cadence, and a
-  short smoke run (a few steps) before the full training job.
-
-Start with a tiny smoke run to validate the pipeline end-to-end before committing to a
-long, expensive training run.