roblox-guard 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Andriansyah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="" width="88" height="88">
+
+# roblox-optimum
+
+Professional Roblox and Luau standards for AI agents, and a checker that runs without one.
+
+[![CI](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml/badge.svg)](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml)
+[![version](https://img.shields.io/github/package-json/v/andrian-syh/roblox-optimum?label=version&color=blue)](CHANGELOG.md)
+[![license](https://img.shields.io/github/license/andrian-syh/roblox-optimum?color=green)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
+
+</div>
+
+An AI agent writing Luau tends to produce code that runs and then leaks, trusts the client, or
+lays out every file differently. This repository fixes that from two directions at once.
+
+## Two parts
+
+**The standards** are written for an agent to follow while it works: server-authoritative,
+leak-free, framework-agnostic, and laid out the same way in every file. They install as skills in
+Claude Code, and as a project instruction file everywhere else. [AGENTS.md](AGENTS.md) ships
+ready to copy, along with a matching file for Cursor, Windsurf, Cline, Kiro, Qoder, Copilot,
+Qwen Code, and Antigravity.
+
+**The checker** is [`scripts/roblox-guard.mjs`](scripts/roblox-guard.mjs), one Node file with no
+dependencies. It reads Luau and reports the same findings whoever wrote the file, so it works as
+an agent hook, a commit hook, or a CI step. It never asks a model anything, which is why it still
+holds after a long session has been summarized and the rules have fallen out of context.
+
+Guidance drifts. A check does not.
+
+## Install
+
+Claude Code:
+
+```
+/plugin marketplace add andrian-syh/roblox-optimum
+/plugin install roblox-optimum@andrian-syh
+```
+
+Codex:
+
+```
+codex plugin marketplace add andrian-syh/roblox-optimum
+codex plugin add roblox-optimum@andrian-syh
+```
+
+Qwen Code:
+
+```
+qwen extensions install https://github.com/andrian-syh/roblox-optimum
+```
+
+Cursor, Antigravity, and Kiro install it as a plugin from this repository. For those, plus
+OpenCode, Copilot, or a plain commit hook, see **[INSTALL.md](INSTALL.md)**, which also states
+plainly what each setup can and cannot do.
+
+## Skills
+
+| Skill | Use it for |
+|---|---|
+| `best-practices` | Writing, refactoring, or implementing any Luau system |
+| `code-review` | Reviewing a file or diff, auditing a place, scoring architectural health |
+| `studio-ops` | Studio MCP, sync toolchains, and proving a change works in a running session |
+
+The split follows what the task is rather than what it is about: one skill produces code, one
+judges it, one drives the tooling around it. A review that turns into a fix hands control back
+to `best-practices`, which owns the layout and comment rules the fix has to land inside.
+
+In Claude Code these are invoked as `/roblox-optimum:best-practices` and so on. Elsewhere they are
+read as project instructions.
+
+## Agent
+
+`roblox-auditor` audits a project in its own context and returns a scored report rather than the
+files it opened. It is read-only and has no write tools.
+
+Use it when an audit would otherwise mean reading a large part of the project into your
+conversation. For one file or one diff, `code-review` is cheaper. Claude Code only, since it
+depends on subagents.
+
+## Supervision
+
+How much the agent confirms before acting.
+
+| Level | Behaviour |
+|---|---|
+| `ask` | Stops at every decision |
+| `bal` | Asks only when a choice is consequential |
+| `go` | Runs autonomously, reports its assumptions afterwards |
+
+Per request, as an argument or inline:
+
+```
+/roblox-optimum:best-practices go
+```
+
+Or once, as a standing preference:
+
+```
+/plugin configure roblox-optimum@andrian-syh
+```
+
+This is the only setting stored. The other facts a session needs, such as which community
+libraries the project uses, whether it is server-authoritative, and whether it is Studio-native
+or synced, belong to a project rather than to a person, and are resolved per session.
+
+## What the checker catches
+
+Deprecated APIs and out-of-order section headers. Where the agent can receive them, findings go
+straight back to it and it fixes its own output before you see it.
+
+The check is deliberately conservative, because a wrong complaint gets a guard switched off:
+
+- Comments and string literals are excluded, so a rule quoted in prose is never reported as a
+  use of it.
+- `.lua` is only checked when the file proves it is Roblox.
+- A module with no functions is data or types, and is exempt from the layout.
+- The layout is only judged when the file already uses the section names. A project running its
+  own scheme is left alone.
+- A section is only judged on its order. One left out because it would be empty is correct, and
+  the standards ban writing the header anyway.
+- Package directories are skipped. Their code belongs to its publisher.
+
+Measured on a 387 file project: 0 findings, after the three causes of a wrong complaint found on
+its first real run were fixed in [0.1.4](CHANGELOG.md).
+
+Set `ROBLOX_GUARD=off` to silence it without uninstalling.
+
+## What the standards cover
+
+- **Layout.** Every script is VARIABLES, FUNCTIONS, INITIALIZATION, in that order, with a
+  specified ordering inside each section.
+- **Server authority.** Every remote argument is validated for type, range, ownership, and rate
+  before it is trusted.
+- **Cleanup.** Every connection has an owner and a teardown path.
+- **Data safety.** `UpdateAsync` with backoff, save on `PlayerRemoving`, flush on `BindToClose`,
+  and a stated failure policy after the last retry.
+- **No deprecated APIs.** `wait`, `spawn`, `delay`, `tick`, lowercase `:connect`, `Body*` movers,
+  and the rest.
+- **Engine facts are cited, not remembered.** A newer API is confirmed against the version dump
+  or an in-Studio probe before it is relied on.
+
+Recommendations only. Nothing is refactored unasked, and your instructions always win.
+
+## Documentation
+
+| File | Contents |
+|---|---|
+| [INSTALL.md](INSTALL.md) | Setup for every supported agent, and what each one can do |
+| [AGENTS.md](AGENTS.md) | The standards as one instruction file, ready to copy into a project |
+| [CHANGELOG.md](CHANGELOG.md) | What changed in each version |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "roblox-guard",
+  "version": "0.4.0",
+  "description": "Deterministic Roblox and Luau standards checks: deprecated APIs and out-of-order section headers, as an agent hook, a commit hook, or a CI step.",
+  "keywords": [
+    "roblox",
+    "luau",
+    "lint",
+    "linter",
+    "static-analysis",
+    "pre-commit",
+    "game-development",
+    "ai-agent"
+  ],
+  "type": "module",
+  "bin": {
+    "roblox-guard": "scripts/roblox-guard.mjs"
+  },
+  "files": [
+    "scripts/roblox-guard.mjs"
+  ],
+  "scripts": {
+    "test": "node scripts/roblox-guard.mjs --selftest"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/andrian-syh/roblox-optimum#using-the-checks-without-claude-code",
+  "bugs": "https://github.com/andrian-syh/roblox-optimum/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrian-syh/roblox-optimum.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/roblox-guard.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+/**
+ * Deterministic standards checks for Luau files, driven by the plugin's hooks.
+ * What the skill can only ask for, this enforces, and it keeps working after the
+ * rules have fallen out of the model's context.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Proof that a source file is Roblox rather than another Lua dialect. */
+const ROBLOX_MARKERS =
+  /\bgame:GetService\s*\(|\bscript\.Parent\b|\bworkspace\b|\bInstance\.new\s*\(/;
+
+/** Proof that a directory is a Roblox project. */
+const PROJECT_MARKERS = [
+  "default.project.json",
+  "sourcemap.json",
+  ".robloxrc",
+  "wally.toml",
+  "rokit.toml",
+  "aftman.toml",
+];
+
+/**
+ * APIs the skill forbids outright, each paired with the replacement to offer. A deprecated
+ * name that community libraries also expose is left out, because a hook cannot tell the two
+ * apart and a wrong complaint costs more than a missed one. Review still catches those.
+ */
+const DEPRECATED = [
+  [/(?<![.:\w])wait\s*\(/, "wait()", "task.wait()"],
+  [/(?<![.:\w])spawn\s*\(/, "spawn()", "task.spawn()"],
+  [/(?<![.:\w])delay\s*\(/, "delay()", "task.delay()"],
+  [/(?<![.:\w])tick\s*\(/, "tick()", "os.clock() or os.time()"],
+  [/:connect\s*\(/, ":connect()", ":Connect()"],
+  [/[Hh]umanoid[\w.]*:LoadAnimation\s*\(/, "Humanoid:LoadAnimation()", "Animator:LoadAnimation()"],
+  [/:SetPrimaryPartCFrame\s*\(/, "SetPrimaryPartCFrame()", "Model:PivotTo()"],
+  [
+    /\bBody(?:Velocity|Position|Gyro|AngularVelocity|Force|Thrust)\b/,
+    "Body* mover",
+    "a constraint (LinearVelocity, AlignPosition, AlignOrientation, VectorForce)",
+  ],
+];
+
+const SECTIONS = ["VARIABLES", "FUNCTIONS", "INITIALIZATION"];
+
+/**
+ * Directories holding code from elsewhere. A package manager rewrites them, so a finding there
+ * names a file the reader is not allowed to edit.
+ */
+const VENDOR = ["Packages", "DevPackages", "ServerPackages", "_Index", "node_modules"];
+
+const HOME_PAGE = "https://github.com/andrian-syh/roblox-optimum";
+
+/** A directory that cannot exist, so the selftest can prove an unopenable path is skipped. */
+const ROOT_ABSENT = "/roblox-guard-no-such-directory";
+
+/** Why a path was passed over, so a run that checked nothing can say what it saw. */
+const SKIP_REASON = {
+  "not-luau": "not a .lua or .luau file",
+  "not-roblox": "a .lua file with no Roblox API in it",
+  vendored: "inside a package directory, so its publisher owns it",
+  unreadable: "could not be read as a file",
+};
+
+const USAGE = `roblox-guard - deterministic Roblox and Luau standards checks
+
+Usage:
+  roblox-guard --check <file...>   Check files. Exit 1 when a file has findings.
+  roblox-guard --selftest          Run the built-in assertions.
+  roblox-guard                     Read a post-write hook payload on stdin. Exit 2 reports
+                                   findings back to the agent.
+  roblox-guard --compact           Read a session-start payload on stdin.
+  roblox-guard --help              Show this text.
+
+Exit codes: 0 nothing to report, 1 findings, 2 findings for an agent or a usage error.
+Set ROBLOX_GUARD=off to disable every check without uninstalling.
+
+Standards: ${HOME_PAGE}
+`;
+
+/**
+ * Blanks the prose in a source file so that a rule named in a comment or a string is never
+ * mistaken for a use of it. Line and column positions are preserved.
+ *
+ * @param source string -- Luau source as written to disk.
+ * @param keepLineComments boolean -- Leave single-line comments in place, for callers that read them.
+ * @return string -- The same source with the selected prose blanked.
+ */
+export function stripNonCode(source, keepLineComments = false) {
+  const out = source.split("");
+  const n = source.length;
+  let i = 0;
+
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < n; k++) {
+      if (out[k] !== "\n") out[k] = " ";
+    }
+  };
+
+  while (i < n) {
+    const two = source.slice(i, i + 2);
+    const long = /^(--)?\[(=*)\[/.exec(source.slice(i, i + 12));
+
+    if (long && (two === "--" || source[i] === "[")) {
+      const close = "]" + long[2] + "]";
+      const end = source.indexOf(close, i + long[0].length);
+      const stop = end === -1 ? n : end + close.length;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+
+    if (two === "--") {
+      const end = source.indexOf("\n", i);
+      const stop = end === -1 ? n : end;
+      if (!keepLineComments) blank(i, stop);
+      i = stop;
+      continue;
+    }
+
+    if (source[i] === '"' || source[i] === "'") {
+      const quote = source[i];
+      let j = i + 1;
+      while (j < n && source[j] !== quote && source[j] !== "\n") {
+        j += source[j] === "\\" ? 2 : 1;
+      }
+      blank(i, Math.min(j + 1, n));
+      i = Math.min(j + 1, n);
+      continue;
+    }
+
+    i++;
+  }
+
+  return out.join("");
+}
+
+/**
+ * Whether a file opted into this section layout. A project is entitled to its own scheme and
+ * one shared word is not consent, so a file is judged only once it uses most of the names.
+ *
+ * @param names table -- Section names found in the file, in the order they appear.
+ * @return boolean
+ */
+function usesThisLayout(names) {
+  return new Set(names).size >= 2;
+}
+
+/**
+ * Returns the standards violations found in one Luau source, ready to print. A module that
+ * declares no function is treated as data or types and is exempt from the layout.
+ *
+ * A section with nothing to hold is left out on purpose, because the standards ban an empty
+ * header. Only the headers a file carries are judged, and only on their order.
+ *
+ * @param source string -- Luau source as written to disk.
+ * @return table -- One string per violation; empty means the file passes.
+ */
+export function inspect(source) {
+  const problems = [];
+  const code = stripNonCode(source);
+
+  if (/\bfunction\b/.test(code)) {
+    const seen = [];
+    stripNonCode(source, true).split("\n").forEach((line, idx) => {
+      if (!line.trimStart().startsWith("--")) return;
+      for (const name of SECTIONS) {
+        if (new RegExp(`\\b${name}\\b`).test(line)) seen.push({ name, line: idx + 1 });
+      }
+    });
+
+    const order = seen.map((s) => s.name);
+
+    if (usesThisLayout(order)) {
+      const present = SECTIONS.map((s) => seen.find((x) => x.name === s)).filter(Boolean);
+      for (let k = 1; k < present.length; k++) {
+        if (present[k].line < present[k - 1].line) {
+          problems.push(
+            `Section order is wrong: ${present[k].name} (line ${present[k].line}) appears before ` +
+              `${present[k - 1].name} (line ${present[k - 1].line}). Required order: ${SECTIONS.join(" > ")}.`,
+          );
+          break;
+        }
+      }
+    }
+  }
+
+  const lines = code.split("\n");
+  for (const [pattern, name, replacement] of DEPRECATED) {
+    for (let k = 0; k < lines.length; k++) {
+      if (pattern.test(lines[k])) {
+        problems.push(`Line ${k + 1}: ${name} is deprecated. Use ${replacement}.`);
+        break;
+      }
+    }
+  }
+
+  return problems;
+}
+
+/** Files named by an apply_patch body, which is how Codex reports an edit. */
+const PATCH_TARGET = /^\*\*\* (?:Add|Update|Move to) File:\s*(.+?)\s*$/gm;
+
+/**
+ * Returns the files a post-write hook payload says were written. Claude Code nests the path,
+ * Cursor puts it at the top level, and Codex sends a patch body instead, so all three shapes
+ * are read and one hook entry serves any of them.
+ *
+ * @param payload table -- The parsed hook payload.
+ * @return table -- Absolute paths, empty when the payload names no file.
+ */
+export function targetsFromPayload(payload) {
+  const direct = payload?.tool_input?.file_path ?? payload?.file_path;
+  if (typeof direct === "string") return [direct];
+
+  const command = payload?.tool_input?.command;
+  if (typeof command !== "string") return [];
+
+  const base = typeof payload?.cwd === "string" ? payload.cwd : process.cwd();
+  return [...command.matchAll(PATCH_TARGET)].map((m) => resolve(base, m[1]));
+}
+
+/**
+ * Checks one path and returns its report, or null when the file is out of scope. A path that
+ * is unreadable, not Luau, or not provably Roblox is skipped rather than guessed at.
+ *
+ * @param path string -- Path to a file the agent wrote.
+ * @return table -- `{ path, problems }`, or null when nothing should be said.
+ */
+export function checkFile(path) {
+  if (typeof path !== "string") return { path: String(path), status: "unreadable", problems: [] };
+  if (!/\.luau?$/i.test(path)) return { path, status: "not-luau", problems: [] };
+
+  const parts = path.split(sep).flatMap((p) => p.split("/"));
+  if (parts.some((p) => VENDOR.includes(p))) return { path, status: "vendored", problems: [] };
+
+  let source;
+  try {
+    source = readFileSync(path, "utf8");
+  } catch {
+    return { path, status: "unreadable", problems: [] };
+  }
+
+  if (!/\.luau$/i.test(path) && !ROBLOX_MARKERS.test(source)) {
+    return { path, status: "not-roblox", problems: [] };
+  }
+
+  const problems = inspect(source);
+  return { path, status: problems.length === 0 ? "clean" : "problems", problems };
+}
+
+/**
+ * Renders reports as the text every entry point shares, so a finding reads the same whether it
+ * reached the developer through an agent, a commit hook, or CI. Each finding carries its own
+ * replacement, so the text stands alone wherever the checker was installed from.
+ *
+ * @param reports table -- Reports from checkFile whose status is "problems".
+ * @return string
+ */
+export function formatReport(reports) {
+  const body = reports
+    .map((r) => `Roblox standards check failed for ${r.path}:\n` + r.problems.map((p) => `  - ${p}`).join("\n"))
+    .join("\n\n");
+
+  return `${body}\n\nStandards: ${HOME_PAGE}\n`;
+}
+
+/**
+ * Returns the hook payload the agent sends, or empty when there is none.
+ * Synchronous reads are not portable when stdin is a pipe.
+ *
+ * @return string
+ */
+async function readStdin() {
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Checks the file the agent just wrote and prints what it must fix. Anything unreadable,
+ * unrecognized, or outside Roblox passes without comment.
+ *
+ * @return number -- Process exit code; the failing code is what surfaces the report.
+ */
+async function runPostToolUse() {
+  if (process.env.ROBLOX_GUARD === "off") return 0;
+
+  let payload;
+  try {
+    payload = JSON.parse((await readStdin()) || "{}");
+  } catch {
+    return 0;
+  }
+
+  const reports = targetsFromPayload(payload)
+    .map(checkFile)
+    .filter((r) => r.status === "problems");
+  if (reports.length === 0) return 0;
+
+  process.stderr.write(formatReport(reports));
+  return 2;
+}
+
+/**
+ * Checks paths given on the command line, for a commit hook, CI, or a hand run. Exit 1 is the
+ * convention a build step expects, unlike the exit 2 an agent hook uses to speak to the model.
+ *
+ * @param paths table -- File paths to check.
+ * @return number -- Process exit code.
+ */
+function runCheck(paths) {
+  if (process.env.ROBLOX_GUARD === "off") return 0;
+
+  if (paths.length === 0) {
+    process.stderr.write(`roblox-guard --check needs at least one file.\n\n${USAGE}`);
+    return 2;
+  }
+
+  const results = paths.map(checkFile);
+  const reports = results.filter((r) => r.status === "problems");
+
+  if (reports.length > 0) {
+    process.stderr.write(formatReport(reports));
+    return 1;
+  }
+
+  // Silence after checking nothing reads as a pass, so name what was skipped and why.
+  if (!results.some((r) => r.status === "clean")) {
+    const why = results.map((r) => `  - ${r.path}: ${SKIP_REASON[r.status]}`).join("\n");
+    process.stderr.write(`roblox-guard checked no files.\n${why}\n`);
+  }
+
+  return 0;
+}
+
+/**
+ * Tells the agent to re-read the skill once a summary has dropped the rules, and stays
+ * silent outside a Roblox project so unrelated sessions are not disturbed.
+ *
+ * @return number -- Process exit code.
+ */
+async function runCompactReminder() {
+  let payload;
+  try {
+    payload = JSON.parse((await readStdin()) || "{}");
+  } catch {
+    return 0;
+  }
+
+  const cwd = payload?.cwd || process.cwd();
+  if (!PROJECT_MARKERS.some((m) => existsSync(join(cwd, m)))) return 0;
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext:
+          "This session was summarized. If Luau work continues, re-read the " +
+          "roblox-optimum best-practices SKILL.md before writing any code - the section " +
+          "layout, comment rules, and runtime non-negotiables do not survive a summary, " +
+          "and reconstructing them from memory produces confidently wrong files.",
+      },
+    }),
+  );
+  return 0;
+}
+
+/** Asserts the checker still behaves, so a regression fails here and not in a user's session. */
+function selftest() {
+  const ok = (cond, label) => {
+    if (!cond) {
+      console.error(`FAIL ${label}`);
+      process.exitCode = 1;
+    }
+  };
+
+  const good = `-- // VARIABLES // --
+local Players = game:GetService("Players")
+
+-- // FUNCTIONS // --
+local function greet(player)
+\ttask.wait(1)
+\tprint(player.Name)
+end
+
+-- // INITIALIZATION // --
+Players.PlayerAdded:Connect(greet)
+`;
+  ok(inspect(good).length === 0, "clean file passes");
+
+  ok(
+    inspect(good.replace("task.wait(1)", "wait(1)")).some((p) => p.includes("wait()")),
+    "bare wait() is caught",
+  );
+  ok(
+    !inspect(good).some((p) => p.includes("wait()")),
+    "task.wait() is not mistaken for wait()",
+  );
+  ok(
+    !inspect(`-- never call wait() here\nlocal x = "spawn("\nreturn { a = 1 }`).some((p) =>
+      p.includes("deprecated"),
+    ),
+    "API names inside comments and strings are ignored",
+  );
+  ok(
+    inspect(`-- // VARIABLES // --\nlocal ACTIONS = { "show" }\n\n-- // INITIALIZATION // --\nreturn function(registry)\n\tregistry:Register(ACTIONS)\nend`).length === 0,
+    "a file whose only function belongs to INITIALIZATION needs no FUNCTIONS header",
+  );
+  ok(
+    inspect(`-- // FUNCTIONS // --\nlocal function f() end\n-- // INITIALIZATION // --\nf()`).length === 0,
+    "a file with no top-level state needs no VARIABLES header",
+  );
+  ok(
+    inspect(`local Players = game:GetService("Players")\nlocal function f() end\nf()`).length === 0,
+    "a file using no section headers at all is left alone",
+  );
+  ok(
+    inspect(`--== SERVICES ==--\nlocal Players = game:GetService("Players")\n--== VARIABLES ==--\nlocal sessions = {}\n--== MAIN ==--\nlocal function f() end\nf()`).length === 0,
+    "another project's scheme sharing one word is not treated as this layout",
+  );
+  ok(
+    inspect(`-- // FUNCTIONS // --\nlocal function f() end\n-- // VARIABLES // --\nlocal a = 1\n-- // INITIALIZATION // --\nf()`).some(
+      (p) => p.includes("order is wrong"),
+    ),
+    "out-of-order sections are caught",
+  );
+  ok(
+    inspect(`local Items = {\n\tSword = { damage = 10 },\n}\nreturn Items`).length === 0,
+    "a pure data module is exempt from the layout",
+  );
+  ok(
+    inspect(good.replace("print(player.Name)", "player.Character:SetPrimaryPartCFrame(cf)")).some(
+      (p) => p.includes("PivotTo"),
+    ),
+    "SetPrimaryPartCFrame is caught",
+  );
+  ok(
+    inspect("--[[\n-- // VARIABLES // --\n-- // FUNCTIONS // --\n]]\nlocal function f() end\nf()").length === 0,
+    "headers quoted inside a long comment do not opt the file in",
+  );
+  ok(
+    inspect(`${good.split("-- // FUNCTIONS // --")[0]}-- // FUNCTIONS // --\nlocal function f()\n\tPromise.new():wait()\nend\n-- // INITIALIZATION // --\nf()`).length === 0,
+    "a library method sharing a deprecated name is not reported",
+  );
+
+  ok(
+    targetsFromPayload({ tool_input: { file_path: "/tmp/a.luau" } }).join() === "/tmp/a.luau",
+    "a payload naming the file directly is read",
+  );
+  ok(
+    targetsFromPayload({
+      cwd: "/proj",
+      tool_input: { command: "*** Begin Patch\n*** Update File: src/a.luau\n*** Add File: src/b.luau\n*** End Patch" },
+    }).length === 2,
+    "both files in an apply_patch body are read",
+  );
+  ok(
+    targetsFromPayload({ tool_input: { command: "ls -la" } }).length === 0,
+    "a shell command naming no file yields nothing",
+  );
+  ok(
+    targetsFromPayload({ file_path: "/tmp/a.luau", edits: [] }).join() === "/tmp/a.luau",
+    "a payload with the path at the top level is read",
+  );
+  ok(
+    inspect(good.replace("print(player.Name)", "player.Character.Humanoid:LoadAnimation(a)")).some(
+      (p) => p.includes("Animator"),
+    ),
+    "LoadAnimation on a Humanoid is caught",
+  );
+  ok(
+    !inspect(good.replace("print(player.Name)", "local t = animator:LoadAnimation(a)")).some((p) =>
+      p.includes("Animator"),
+    ),
+    "LoadAnimation on an Animator is not reported",
+  );
+
+  ok(checkFile("notes.txt").status === "not-luau", "a non-Luau path is reported as skipped");
+  ok(
+    checkFile(join("proj", "Packages", "Cmdr.luau")).status === "vendored",
+    "a file inside a package tree is skipped",
+  );
+  ok(
+    checkFile(join(ROOT_ABSENT, "missing.luau")).status === "unreadable",
+    "a path that cannot be opened is reported as skipped",
+  );
+  ok(checkFile(undefined).status === "unreadable", "a missing path does not throw");
+
+  if (!process.exitCode) console.log("roblox-guard selftest: all checks passed");
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  const [mode, ...rest] = process.argv.slice(2);
+  if (mode === "--selftest") selftest();
+  else if (mode === "--compact") process.exit(await runCompactReminder());
+  else if (mode === "--check") process.exit(runCheck(rest));
+  else if (mode === "--help" || mode === "-h") process.stdout.write(USAGE);
+  else if (mode === undefined) process.exit(await runPostToolUse());
+  else {
+    process.stderr.write(`roblox-guard: unknown option ${mode}\n\n${USAGE}`);
+    process.exit(2);
+  }
+}