@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/plugins/materio/assets/references/traditional-workflows.md

@@ -0,0 +1,146 @@
+# Traditional Research Workflows in Material Science
+
+## 1. Experimental Research Workflow
+**Best for**: New material synthesis, property measurement, structure-property relationships
+
+```
+Task 01: Literature review & gap identification
+Task 02: Hypothesis formulation
+Task 03: Experimental design (DOE, sample matrix)
+Task 04: Sample/specimen preparation
+Task 05: Characterization (structure)
+Task 06: Property measurement (mechanical / functional / etc.)
+Task 07: Data analysis & statistical treatment
+Task 08: Interpretation & mechanism identification
+Task 09: Write-up & publication
+```
+
+**Key assumptions to interview about each task**:
+- Task 03: What variables are being controlled? What is the sample size?
+- Task 04: What processing routes are available? What are contamination risks?
+- Task 05: What characterization tools are accessible? What resolution is needed?
+- Task 06: What standards (ASTM, ISO) apply? What test conditions?
+- Task 07: What statistical methods? Are outliers expected?
+
+---
+
+## 2. Computational Research Workflow
+**Best for**: Property prediction, screening, mechanism understanding, new hypothesis generation
+
+```
+Task 01: Literature review & gap identification
+Task 02: Problem formulation & model selection
+Task 03: Parameter validation (benchmarking vs. experiment)
+Task 04: Main simulations / calculations
+Task 05: Convergence & sensitivity testing
+Task 06: Data analysis & visualization
+Task 07: Interpretation & physical insight
+Task 08: Experimental validation (if applicable)
+Task 09: Write-up & publication
+```
+
+**Key assumptions per task**:
+- Task 02: DFT vs. MD vs. phase-field? What exchange-correlation functional?
+- Task 03: What experimental data exists for benchmarking?
+- Task 04: What system sizes and timescales are computationally feasible?
+- Task 05: What convergence criteria are acceptable?
+
+---
+
+## 3. Integrated Experimental + Computational Workflow
+**Best for**: Mechanistic studies, structure-property-processing relationships
+
+```
+Task 01: Literature review & gap identification
+Task 02: Hypothesis formulation
+Task 03: Computational screening / pre-selection
+Task 04: Experimental design based on computational insights
+Task 05: Sample preparation
+Task 06: Characterization
+Task 07: Property measurement
+Task 08: Computational validation / refinement
+Task 09: Mechanism elucidation (combined)
+Task 10: Write-up & publication
+```
+
+---
+
+## 4. Materials Optimization Workflow
+**Best for**: Alloy design, processing parameter optimization, performance maximization
+
+```
+Task 01: Literature review; identify composition/process space
+Task 02: Design of experiments (DOE) or high-throughput plan
+Task 03: Sample library preparation
+Task 04: Rapid characterization (screening)
+Task 05: Property measurement (screening)
+Task 06: Down-selection & focused study
+Task 07: Detailed characterization of top candidates
+Task 08: Mechanism analysis
+Task 09: Performance validation (application-relevant conditions)
+Task 10: Write-up & publication
+```
+
+---
+
+## 5. Literature Review / Meta-Analysis Workflow
+**Best for**: Review papers, meta-analysis, identifying trends across datasets
+
+```
+Task 01: Define scope & inclusion/exclusion criteria
+Task 02: Database search & paper collection
+Task 03: Abstract screening
+Task 04: Full-text review & data extraction
+Task 05: Data harmonization (units, conditions, definitions)
+Task 06: Statistical analysis / meta-analysis
+Task 07: Trend identification & gap analysis
+Task 08: Synthesis & narrative development
+Task 09: Write review paper
+```
+
+---
+
+## 6. Device / Application Workflow
+**Best for**: Proof-of-concept demonstration, prototype development
+
+```
+Task 01: Literature review; material requirements & state of art
+Task 02: Material selection / design
+Task 03: Fabrication process development
+Task 04: Device assembly
+Task 05: Performance testing (device-level)
+Task 06: Degradation / lifetime study
+Task 07: Benchmarking vs. state-of-art
+Task 08: Write-up & publication
+```
+
+---
+
+## Task Type Definitions
+
+| Type | What It Means | Agent Behavior |
+|------|---------------|----------------|
+| `literature` | Search, read, synthesize papers | Review supplied corpus and permitted provided URLs, then summarize → update LITERATURE.md |
+| `experimental` | Physical lab work | Generate protocol + recording template + checklist |
+| `computational` | Simulation / calculation | Generate input files + analysis scripts |
+| `analytical` | Mathematical modeling, theory | Derive equations + validate against data |
+| `data-analysis` | Process existing data | Write analysis code + produce figures |
+| `writing` | Draft paper sections | Prepare author-reviewed paper handoff |
+
+---
+
+## Checkpoint Placement Guidelines
+
+Place `checkpoint:human-action` when:
+- Experimental data needs to be uploaded before analysis can proceed
+- A go/no-go decision is needed based on preliminary results
+- Equipment access or resource availability must be confirmed
+
+Place `checkpoint:decision` when:
+- Two valid experimental paths exist (e.g., XRD vs. neutron diffraction)
+- Computational model must be chosen (DFT vs. MD vs. phase-field)
+- Scope must be narrowed after unexpected preliminary results
+
+Place `checkpoint:human-verify` when:
+- Assumptions have been generated and need domain expert sign-off
+- Analysis results need interpretation before the next task begins

package/library/plugins/materio/assets/scripts/check_physics.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+check_physics; scan Materio task outputs for physically impossible or
+implausible numeric values.
+
+It reads generated protocol / results / input files, extracts (value, unit)
+pairs, and checks them against physical bounds:
+
+  * absolute temperature below 0 K (or below -273.15 C / -459.67 F)  -> ERROR
+  * density <= 0, or implausibly high (> 30 g/cm3)                   -> ERROR / WARN
+  * a fraction unit (wt%, at%, mol%, vol%) outside 0-100             -> ERROR
+  * a plain % tied to a bounded quantity (porosity, purity, ...)     -> ERROR
+  * an alloy composition block whose wt%/at% values do not sum ~100  -> WARN
+
+DESIGN; to keep false positives low, v1 only asserts things that are
+unconditionally true. It does not flag a value merely for being negative:
+many materials quantities are legitimately negative (DFT total / formation
+energies, binding enthalpies, stresses, thermal-expansion mismatch,
+coordinates), as are temperature differences, rates, and gradients. Only
+quantities that are non-negative by definition (absolute temperature,
+density, a bounded fraction) are sign-checked.
+
+Exit status: non-zero if any ERROR. Zero deps (Python stdlib only).
+
+Usage:
+  python3 assets/scripts/check_physics.py .research/tasks/task-01/*.md
+  python3 assets/scripts/check_physics.py --json protocol.md
+"""
+import argparse
+import json
+import re
+import sys
+
+# A signed number that is NOT the tail of a range like "250-300" or "5.0-6".
+# The lookbehind rejects a preceding digit/dot/comma so range internals and
+# en-dash ranges ("250–300", en-dash is not a sign) are not read as negative.
+_NUM = r"(?<![\d.,])([-−]?\d[\d,]*\.?\d*(?:[eE][+-]?\d+)?)"
+
+
+def _to_float(s):
+    return float(s.replace(",", "").replace("−", "-"))
+
+
+# ---- findings -------------------------------------------------------------
+
+class Findings:
+    def __init__(self):
+        self.errors = []
+        self.warnings = []
+
+    def error(self, path, line, rule, msg):
+        self.errors.append((path, line, rule, msg))
+
+    def warn(self, path, line, rule, msg):
+        self.warnings.append((path, line, rule, msg))
+
+
+# ---- individual checks ----------------------------------------------------
+
+def _iter_matches(pattern, text):
+    for m in re.finditer(pattern, text):
+        line_no = text.count("\n", 0, m.start()) + 1
+        yield m, line_no
+
+
+# A temperature UNIT also appears in signed quantities that are legitimately
+# negative: differences (ΔT), rates (K/s), and gradients (K/mm). We only
+# sign-check a value that reads as an ABSOLUTE temperature; one not followed
+# by "/" (a rate/gradient) and not on a line about a delta/rate/gradient.
+_TEMP_SIGNED_CTX = re.compile(
+    r"Δ|∆|\bdelta\b|\bgradient\b|\brate\b|\bchange\b|\bdifference\b",
+    re.IGNORECASE)
+
+
+def check_temperature(text, path, fnd):
+    for ln, line in enumerate(text.splitlines(), 1):
+        signed = _TEMP_SIGNED_CTX.search(line)
+        for m in re.finditer(_NUM + r"\s*K\b(?!\s*/)", line):
+            v = _to_float(m.group(1))
+            if v < 0 and not signed:
+                fnd.error(path, ln, "temp-kelvin",
+                          f"{v:g} K is below absolute zero (0 K)")
+            elif v > 100000:
+                fnd.warn(path, ln, "temp-kelvin",
+                         f"{v:g} K is implausibly high; check units")
+        for m in re.finditer(_NUM + r"\s*(?:°\s*C|degC|℃)(?!\s*/)", line):
+            v = _to_float(m.group(1))
+            if v < -273.15 and not signed:
+                fnd.error(path, ln, "temp-celsius",
+                          f"{v:g} C is below absolute zero (-273.15 C)")
+        for m in re.finditer(_NUM + r"\s*(?:°\s*F|degF|℉)(?!\s*/)", line):
+            v = _to_float(m.group(1))
+            if v < -459.67 and not signed:
+                fnd.error(path, ln, "temp-fahrenheit",
+                          f"{v:g} F is below absolute zero (-459.67 F)")
+
+
+# density units -> factor to convert into g/cm^3
+_DENSITY = [
+    (r"g\s*/\s*cm\s*(?:\^?3|³)", 1.0),
+    (r"g\s*/\s*cc\b", 1.0),
+    (r"g\s*/\s*mL\b", 1.0),
+    (r"kg\s*/\s*m\s*(?:\^?3|³)", 0.001),
+]
+
+
+def check_density(text, path, fnd):
+    for unit_re, factor in _DENSITY:
+        for m, ln in _iter_matches(_NUM + r"\s*(?:" + unit_re + r")", text):
+            v = _to_float(m.group(1)) * factor
+            if v <= 0:
+                fnd.error(path, ln, "density",
+                          f"density {v:g} g/cm^3 must be positive")
+            elif v > 30:
+                fnd.warn(path, ln, "density",
+                         f"density {v:g} g/cm^3 exceeds any known solid "
+                         "(osmium ~22.6); check value/units")
+
+
+# Fraction units are bounded 0-100 by definition.
+_FRACTION_UNITS = r"(?:wt|at|mol|vol)\s*\.?\s*%"
+# A bare % counts as a bounded fraction only near one of these words.
+_BOUNDED_KEYWORDS = re.compile(
+    r"porosit|relative density|rel\.?\s*density|densit|purit|"
+    r"fraction|content|concentrat|abundance|yield|efficien|"
+    r"conversion|selectivit|recover", re.IGNORECASE)
+# ...but not when the % is a relative change (which can exceed 100%), e.g.
+# "efficiency improved by 250%".
+_RELATIVE_CHANGE = re.compile(
+    r"\b(?:improv\w*|increas\w*|decreas\w*|reduc\w*|gain\w*|higher|lower\w*|"
+    r"relativ\w*|baselin\w*|faster|slower|growth)\b|×|\bx\d",
+    re.IGNORECASE)
+
+
+def check_fractions(text, path, fnd):
+    for m, ln in _iter_matches(_NUM + r"\s*(?:" + _FRACTION_UNITS + r")", text):
+        v = _to_float(m.group(1))
+        if v < 0 or v > 100:
+            fnd.error(path, ln, "fraction",
+                      f"{v:g}% is outside the valid 0-100% range")
+    for line_no, line in enumerate(text.splitlines(), 1):
+        if not _BOUNDED_KEYWORDS.search(line) or _RELATIVE_CHANGE.search(line):
+            continue
+        for m in re.finditer(_NUM + r"\s*%(?![a-zA-Z])", line):
+            v = _to_float(m.group(1))
+            if v < 0 or v > 100:
+                fnd.error(path, line_no, "fraction",
+                          f"{v:g}% is outside 0-100% for a bounded quantity")
+
+
+def check_composition(text, path, fnd):
+    """
+    Flag an alloy composition group whose wt%/at%/mol% values do not sum to
+    ~100%. A group is either an inline list (>=2 same-unit values on one line,
+    e.g. "Ti 90 wt%, Al 6 wt%, V 4 wt%") or a contiguous run of lines each
+    carrying exactly one same-unit value (a vertical table). Conservative:
+    needs >=2 values and a total in a sane window, so unrelated scattered
+    percentages are not summed together.
+    """
+    unit = re.compile(_NUM + r"\s*(" + _FRACTION_UNITS + r")")
+    lines = text.splitlines()
+
+    def check_group(values, kind, ref_line, span):
+        if len(values) >= 2:
+            total = sum(values)
+            if 80 <= total <= 120 and abs(total - 100) > 1.0:
+                fnd.warn(path, ref_line, "composition",
+                         f"{kind} composition {span} sums to {total:g}% "
+                         f"(expected ~100%)")
+
+    run, start_line, run_kind = [], None, None
+
+    def flush(end_line):
+        span = (f"block (lines {start_line}-{end_line})"
+                if end_line != start_line else f"on line {start_line}")
+        check_group(run, run_kind, start_line, span)
+
+    for i, line in enumerate(lines, 1):
+        by_kind = {}
+        for val, u in unit.findall(line):
+            k = re.sub(r"[\s.]", "", u).lower()
+            by_kind.setdefault(k, []).append(_to_float(val))
+
+        inline = {k: v for k, v in by_kind.items() if len(v) >= 2}
+        if inline:                                   # inline composition list
+            if run:
+                flush(i - 1)
+                run, start_line, run_kind = [], None, None
+            for k, vals in inline.items():
+                check_group(vals, k, i, f"on line {i}")
+            continue
+
+        if len(by_kind) == 1 and sum(len(v) for v in by_kind.values()) == 1:
+            k = next(iter(by_kind))                  # single value: vertical run
+            if run and k != run_kind:
+                flush(i - 1)
+                run, start_line, run_kind = [], None, None
+            if not run:
+                start_line, run_kind = i, k
+            run.append(by_kind[k][0])
+        else:
+            if run:
+                flush(i - 1)
+            run, start_line, run_kind = [], None, None
+    if run:
+        flush(len(lines))
+
+
+CHECKS = [check_temperature, check_density, check_fractions, check_composition]
+
+
+# ---- driver ---------------------------------------------------------------
+
+def scan(paths):
+    fnd = Findings()
+    for p in paths:
+        try:
+            with open(p, encoding="utf-8") as f:
+                text = f.read()
+        except OSError as e:
+            print(f"WARN: cannot read {p}: {e}", file=sys.stderr)
+            continue
+        for check in CHECKS:
+            check(text, p, fnd)
+    return fnd
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Physical sanity checks for "
+                                             "Materio task outputs.")
+    ap.add_argument("paths", nargs="+", help="files to scan (.md, input files)")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args()
+
+    unreadable = []
+    for path in args.paths:
+        try:
+            with open(path, encoding="utf-8") as source:
+                source.read()
+        except (OSError, UnicodeError) as error:
+            unreadable.append({"file": path, "reason": str(error)})
+    readable = [path for path in args.paths if path not in {item["file"] for item in unreadable}]
+    fnd = scan(readable)
+
+    if args.json:
+        print(json.dumps({
+            "coverage": {"files_requested": len(args.paths), "files_read": len(readable), "unreadable": unreadable},
+            "errors": [{"file": p, "line": l, "rule": r, "message": m}
+                       for p, l, r, m in fnd.errors],
+            "warnings": [{"file": p, "line": l, "rule": r, "message": m}
+                         for p, l, r, m in fnd.warnings],
+        }, indent=2))
+    else:
+        def emit(items, label):
+            if not items:
+                return
+            print(f"\n{label} ({len(items)}):")
+            for p, l, r, m in sorted(items):
+                print(f"  {p}:{l}  [{r}]  {m}")
+        emit(fnd.errors, "IMPOSSIBLE (errors)")
+        emit(fnd.warnings, "IMPLAUSIBLE (warnings)")
+        n = len(fnd.errors) + len(fnd.warnings)
+        print(f"\ncheck-physics: {len(fnd.errors)} error(s), "
+              f"{len(fnd.warnings)} warning(s)."
+              + ("" if n else " No physical-sanity issues found."))
+
+    return 2 if unreadable else 1 if fnd.errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/library/plugins/materio/assets/scripts/check_scripts.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+check_scripts; "runnable by construction" checks for the Materio code
+generates in computational / data-analysis tasks. A generated script that
+doesn't parse, imports a package that doesn't exist, or is a silent stub
+fails only when the researcher runs it; these checks catch that earlier.
+
+For each generated file this checks, without executing anything:
+
+  Python (.py)
+    * syntax       ; ast.parse; a SyntaxError is a hard bug          -> ERROR
+    * imports      ; top-level imports that are neither stdlib, a
+                      recognized scientific package, nor a sibling
+                      script (likely a typo / hallucinated package)   -> WARN
+    * stubs        ; bare `...`, `raise NotImplementedError`,
+                      pass-only functions, or template placeholders
+                      (path/to/, YOUR_, <...>, TODO/FIXME)            -> WARN
+  Shell (.sh, .bash)
+    * syntax       ; `bash -n`                                       -> ERROR
+
+Nothing is imported or run, so this is safe on untrusted generated code and
+has no environment dependencies (a package being importable in the user's
+env is deliberately NOT required; that would false-positive in CI).
+
+Exit status: non-zero if any ERROR. Zero third-party deps.
+
+Usage:
+  python3 assets/scripts/check_scripts.py .research/tasks/task-01/*.py
+  python3 assets/scripts/check_scripts.py --json task-01-analysis.py
+"""
+import argparse
+import ast
+import json
+import os
+import re
+import subprocess
+import sys
+
+# Common scientific / materials-science packages an analysis script may import.
+# Anything here OR in the stdlib OR a sibling .py is "recognized".
+KNOWN_PACKAGES = {
+    "numpy", "scipy", "pandas", "matplotlib", "mpl_toolkits", "seaborn",
+    "sklearn", "skimage", "sympy", "statsmodels", "networkx", "numba", "cython",
+    "h5py", "netCDF4", "xarray", "zarr", "plotly", "bokeh", "altair",
+    "tensorflow", "torch", "keras", "jax", "jaxlib", "pint", "uncertainties",
+    "lmfit", "tqdm", "requests", "yaml", "toml", "joblib", "numexpr", "dask",
+    "ase", "pymatgen", "phonopy", "phono3py", "spglib", "MDAnalysis",
+    "mdanalysis", "openmm", "rdkit", "pyvista", "vtk", "mayavi", "ovito",
+    "atomman", "lammps", "gpaw", "abipy", "aiida", "monty", "click", "typer",
+    "mp_api", "matminer", "fireworks", "custodian", "emmet", "pybamm",
+    "fenics", "dolfin", "meshio", "gmsh", "pillow", "PIL", "cv2", "numpydoc",
+    "pytest", "hypothesis", "sqlalchemy", "polars", "pyarrow",
+}
+
+
+# Fallback for Python < 3.10, which has no sys.stdlib_module_names. Not
+# exhaustive: a stdlib module missing here surfaces as an advisory import
+# warning on an old interpreter, never as a crash.
+_STDLIB_FALLBACK = {
+    "abc", "argparse", "ast", "asyncio", "base64", "bisect", "builtins",
+    "collections", "concurrent", "contextlib", "copy", "csv", "dataclasses",
+    "datetime", "decimal", "difflib", "enum", "errno", "fractions",
+    "functools", "glob", "gzip", "hashlib", "heapq", "http", "importlib",
+    "inspect", "io", "itertools", "json", "logging", "math",
+    "multiprocessing", "operator", "os", "pathlib", "pickle", "platform",
+    "pprint", "queue", "random", "re", "shlex", "shutil", "signal", "socket",
+    "statistics", "string", "struct", "subprocess", "sys", "tarfile",
+    "tempfile", "textwrap", "threading", "time", "timeit", "traceback",
+    "types", "typing", "unittest", "urllib", "uuid", "warnings", "weakref",
+    "xml", "zipfile", "zlib",
+}
+
+
+def stdlib_names():
+    """Top-level stdlib module names: sys.stdlib_module_names on 3.10+,
+    the hardcoded fallback set otherwise."""
+    names = getattr(sys, "stdlib_module_names", None)
+    return set(names) if names else set(_STDLIB_FALLBACK)
+
+
+class Findings:
+    def __init__(self):
+        self.errors = []
+        self.warnings = []
+
+    def error(self, path, line, rule, msg):
+        self.errors.append((path, line, rule, msg))
+
+    def warn(self, path, line, rule, msg):
+        self.warnings.append((path, line, rule, msg))
+
+
+_PLACEHOLDER_TEXT = re.compile(
+    r"path/to/|/path/to|YOUR_[A-Z]|<[a-z_]+>|\bTODO\b|\bFIXME\b|"
+    r"REPLACE_ME|FILL_IN|XXXX", re.IGNORECASE)
+
+
+def _top_module(name):
+    return (name or "").split(".")[0]
+
+
+def _stub_findings(tree, path, fnd):
+    for node in ast.walk(tree):
+        # bare `...` used as a statement (not numpy `a[...]` indexing)
+        if (isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant)
+                and node.value.value is Ellipsis):
+            fnd.warn(path, node.lineno, "stub",
+                     "bare `...` placeholder; body not implemented")
+        if isinstance(node, ast.Raise):
+            exc = node.exc
+            name = None
+            if isinstance(exc, ast.Call):
+                name = getattr(exc.func, "id", None)
+            elif isinstance(exc, ast.Name):
+                name = exc.id
+            if name == "NotImplementedError":
+                fnd.warn(path, node.lineno, "stub",
+                         "raises NotImplementedError; not implemented")
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            body = node.body
+            if body and isinstance(body[0], ast.Expr) and \
+                    isinstance(body[0].value, ast.Constant) and \
+                    isinstance(body[0].value.value, str):
+                body = body[1:]                    # drop docstring
+            if len(body) == 1 and isinstance(body[0], ast.Pass):
+                fnd.warn(path, node.lineno, "stub",
+                         f"function '{node.name}' has an empty (pass-only) body")
+
+
+def check_python(text, path, fnd, local_modules):
+    try:
+        tree = ast.parse(text, filename=path)
+    except SyntaxError as e:
+        fnd.error(path, e.lineno or 0, "syntax",
+                  f"SyntaxError: {e.msg}")
+        return
+    # imports
+    known = stdlib_names() | KNOWN_PACKAGES | local_modules
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                mod = _top_module(alias.name)
+                if mod and mod not in known:
+                    fnd.warn(path, node.lineno, "import",
+                             f"'{mod}' is not stdlib or a recognized package "
+                             "— check spelling / that it's real")
+        elif isinstance(node, ast.ImportFrom):
+            if node.level:                          # relative import: skip
+                continue
+            mod = _top_module(node.module)
+            if mod and mod not in known:
+                fnd.warn(path, node.lineno, "import",
+                         f"'{mod}' is not stdlib or a recognized package "
+                         "— check spelling / that it's real")
+    # stubs (AST-based) + textual placeholders
+    _stub_findings(tree, path, fnd)
+    for i, line in enumerate(text.splitlines(), 1):
+        m = _PLACEHOLDER_TEXT.search(line)
+        if not m:
+            continue
+        where = "in comment" if line.lstrip().startswith("#") else "in code"
+        fnd.warn(path, i, "placeholder",
+                 f"template placeholder {where}: '{m.group(0)}'")
+
+
+def check_shell(path, fnd):
+    try:
+        r = subprocess.run(["bash", "-n", path], capture_output=True,
+                           text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError) as e:
+        fnd.warn(path, 0, "shell", f"could not run `bash -n`: {e}")
+        return
+    if r.returncode != 0:
+        msg = (r.stderr or "").strip().splitlines()
+        fnd.error(path, 0, "syntax",
+                  "bash syntax error: " + (msg[-1] if msg else "see bash -n"))
+
+
+def scan(paths):
+    fnd = Findings()
+    local_modules = {os.path.splitext(os.path.basename(p))[0]
+                     for p in paths if p.endswith(".py")}
+    for p in paths:
+        try:
+            if p.endswith(".py"):
+                with open(p, encoding="utf-8") as f:
+                    check_python(f.read(), p, fnd, local_modules)
+            elif p.endswith((".sh", ".bash")):
+                check_shell(p, fnd)
+        except OSError as e:
+            print(f"WARN: cannot read {p}: {e}", file=sys.stderr)
+    return fnd
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Runnable-by-construction checks for generated scripts.")
+    ap.add_argument("paths", nargs="+", help=".py / .sh files to check")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args()
+
+    unreadable = []
+    for path in args.paths:
+        try:
+            with open(path, encoding="utf-8") as source:
+                source.read()
+        except (OSError, UnicodeError) as error:
+            unreadable.append({"file": path, "reason": str(error)})
+    readable = [path for path in args.paths if path not in {item["file"] for item in unreadable}]
+    fnd = scan(readable)
+
+    if args.json:
+        print(json.dumps({
+            "coverage": {"files_requested": len(args.paths), "files_read": len(readable), "unreadable": unreadable},
+            "errors": [{"file": p, "line": l, "rule": r, "message": m}
+                       for p, l, r, m in fnd.errors],
+            "warnings": [{"file": p, "line": l, "rule": r, "message": m}
+                         for p, l, r, m in fnd.warnings],
+        }, indent=2))
+    else:
+        def emit(items, label):
+            if not items:
+                return
+            print(f"\n{label} ({len(items)}):")
+            for p, l, r, m in sorted(items):
+                loc = f"{p}:{l}" if l else p
+                print(f"  {loc}  [{r}]  {m}")
+        emit(fnd.errors, "WILL NOT RUN (errors)")
+        emit(fnd.warnings, "SUSPECT (warnings)")
+        for item in unreadable:
+            print(f"  UNREAD  {item['file']}  {item['reason']}")
+        n = len(fnd.errors) + len(fnd.warnings)
+        verdict = ""
+        if unreadable:
+            verdict = (f" {len(unreadable)} path(s) could not be read as script files"
+                       " (pass .py/.sh files, not directories); coverage is incomplete.")
+        elif not readable:
+            verdict = " No files were checked."
+        elif not n:
+            verdict = " Checked scripts parse cleanly."
+        print(f"\ncheck-scripts: {len(fnd.errors)} error(s), "
+              f"{len(fnd.warnings)} warning(s)." + verdict)
+
+    return 2 if unreadable else 1 if fnd.errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())