becwright 0.1.0__tar.gz

becwright-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alonso David De Leon Rodarte
+
+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.

becwright-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: becwright
+Version: 0.1.0
+Summary: Deterministically enforces constraints (BECs) on your code, blocking commits that violate them.
+Author: Alonso David De Leon Rodarte
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+> **English** · [Español](README.es.md)
+
+# becwright
+
+[![CI](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml/badge.svg)](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml)
+
+**Rules that run, not notes that get ignored.**
+
+`becwright` enforces constraints on your code deterministically: instead of
+*asking* an AI agent to respect a rule (the way `CLAUDE.md`, `.cursorrules`,
+etc. do — which the agent can read and ignore), becwright **verifies the
+result** and blocks the commit if the rule is broken.
+
+## The problem
+
+An AI agent writes code and leaves a note: *"this must never log session
+tokens"*. That note is text. Three months later, another agent regenerates the
+module, doesn't read it, and drops the token into the logs. Nobody notices
+until it blows up in production.
+
+Notes are **probabilistic** (they depend on the agent reading, understanding and
+obeying). becwright is **deterministic**: the rule runs against the real code
+and returns pass/fail, no matter which agent or model made the change.
+
+| | Note in CLAUDE.md | becwright rule |
+|---|---|---|
+| What it does | *Asks* to be respected | *Verifies* it was respected |
+| Depends on | The agent reading and obeying | Nothing — it runs against the code |
+| Result | Likely | Guaranteed |
+| Analogy | A "speed limit" sign | A physical bump in the road |
+
+The two layers are complementary: CLAUDE.md prevents (so 95% comes out right the
+first time), becwright is the safety net for the 5% that slips through.
+
+## Core concept: BEC (Bound Executable Constraint)
+
+A BEC is a constraint with three properties that no current artifact has
+together:
+
+- **Bound** — the rule is born tied to the *intent* and the decision that
+  created it (the *why*); it is not a loose rule without context.
+- **Executable** — it carries a check that runs and returns pass/fail; it is not
+  prose someone promises to respect.
+- **Portable** — it can be exported from one repo and imported into another,
+  like a package (this is what creates the network effect over time).
+
+## How to use it
+
+becwright is installed once as a tool; each repo only contributes its own
+`.bec/rules.yaml`.
+
+```bash
+# 1. Install the engine (once, global)
+pipx install git+https://github.com/DataDave-Dev/becwright.git   # or local: pipx install .
+
+# 2. In the repo where you want the rules, install the git hook
+becwright install                   # writes .git/hooks/pre-commit
+
+# 3. Write your rules in .bec/rules.yaml (see examples below)
+# 4. Done: each commit runs the checks; if a blocking rule fails, it stops.
+```
+
+Available commands:
+
+| Command | What it does |
+|---|---|
+| `becwright check` | Runs the rules over the staged files |
+| `becwright install` | Installs the native `pre-commit` hook |
+| `becwright uninstall` | Removes the hook |
+| `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
+| `becwright import <file\|URL>` | Imports a BEC from another repo |
+
+A rule in `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-token-in-logs
+    intent: >
+      Session tokens and credentials must never reach any log.
+    why_it_matters: >
+      If a token shows up in the logs, anyone with access to them can steal a
+      user's session.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.no_token_in_logs"
+    severity: blocking   # blocking = stops the commit | warning = only warns
+```
+
+## Included checks
+
+becwright ships ready-to-use checks. Each one is a module invoked from the
+`check` field. They are **text/regex based** (no AST analysis), so they are
+conservative and may have edge cases; the value is in tying each rule to its
+*why*.
+
+| Check | What it detects | Language | Suggested severity |
+|---|---|---|---|
+| `forbid` | Any regex you pass (`--pattern`) | any | depends on the case |
+| `no_token_in_logs` | Tokens/credentials in log calls | Python | `blocking` |
+| `hardcoded_secrets` | AWS keys, private keys, `password = "..."` literals | any | `blocking` |
+| `debug_remnants` | Forgotten `breakpoint()`, `pdb.set_trace()`, `import pdb` | Python | `blocking` |
+| `dangerous_eval` | `eval()` / `exec()` calls | any | `blocking` |
+| `wildcard_imports` | `from x import *` | Python | `warning` |
+
+Example rules to copy into your `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-hardcoded-secrets
+    intent: >
+      No secret (key, token, password) should be hardcoded in the code.
+    why_it_matters: >
+      A secret in the repo stays in git history forever and is visible to
+      anyone with access to the code.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.hardcoded_secrets"
+    severity: blocking
+
+  - id: no-debug-remnants
+    intent: >
+      Debug code (breakpoints, pdb) must not be committed.
+    why_it_matters: >
+      A forgotten breakpoint hangs the process in production or CI.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.debug_remnants"
+    severity: blocking
+
+  - id: no-dangerous-eval
+    intent: >
+      Do not use eval()/exec(), which execute arbitrary code.
+    why_it_matters: >
+      eval/exec on untrusted input is remote code execution.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.dangerous_eval"
+    severity: blocking
+
+  - id: no-wildcard-imports
+    intent: >
+      Avoid 'from x import *', which pollutes the namespace.
+    why_it_matters: >
+      Wildcard imports hide where each name comes from and break static
+      analysis.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.wildcard_imports"
+    severity: warning
+```
+
+## Any language
+
+becwright is **language-agnostic**: the engine only filters files by their
+`paths` (globs) and runs the `check` as a command; it never assumes Python. You
+can watch JavaScript, Go, Rust, or anything else.
+
+The fastest way to write a rule for another language —without writing code— is
+the `forbid` check, which fails if a regex appears in the files:
+
+```yaml
+rules:
+  - id: no-debugger-js
+    intent: >
+      Do not leave 'debugger;' in JavaScript/TypeScript code.
+    why_it_matters: >
+      A forgotten 'debugger' halts execution and should not reach production.
+    paths: ["**/*.js", "**/*.ts"]
+    check: "python3 -m becwright.checks.forbid --pattern '\\bdebugger\\b'"
+    severity: blocking
+```
+
+`forbid` accepts `--pattern REGEX`, `--ignore-case` and `--message TEXT`. For
+finer checks, write your own script in whatever language you want (an executable
+that reads the file list from stdin and exits with code 0/1) and point `check`
+at it.
+
+## Sharing BECs between repos
+
+A BEC is **portable**: you can take it out of one repo and install it in
+another. A bundle is a single self-contained `.bec.yaml` file (the rule + the
+check's code if it is custom).
+
+```bash
+# In the source repo: export a rule to a file
+becwright export no-token-in-logs -o no-token-in-logs.bec.yaml
+
+# In another repo: import it (from a file or an http/https URL)
+becwright import no-token-in-logs.bec.yaml
+becwright import https://example.com/no-token-in-logs.bec.yaml
+```
+
+On import, becwright **shows the check's code and asks for confirmation** before
+installing it: importing a BEC is importing code that will run on every commit.
+Use `--yes` to skip the confirmation in automated environments.
+
+There is a **catalog of ready-to-use BECs** in [`becs/`](becs/) that you can
+import directly from their raw URL.
+
+Built-in checks (`python3 -m becwright.checks.*`) travel with the package, so
+the bundle only stores their name. A **custom** check (`.bec/checks/foo.py`)
+travels with its code embedded and lands in `.bec/checks/` of the target repo.
+
+## Current status
+
+The **installable MVP** is built and verified end-to-end: packaged engine
+(`src/becwright/`), CLI (`check` / `install` / `uninstall` / `export` /
+`import`), native git hook that blocks a commit with a token in a log, included
+checks (Python + the generic `forbid` for any language), BEC portability between
+repos, a catalog with Python and JS/TS BECs, and a green test suite. The original
+prototype is **archived** under `prototype/` as a reference.
+
+Future work (AST analysis, deep per-language tooling, cryptographic signing of
+verifications) is documented in the project plan.

becwright-0.1.0/README.md

@@ -0,0 +1,209 @@
+> **English** · [Español](README.es.md)
+
+# becwright
+
+[![CI](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml/badge.svg)](https://github.com/DataDave-Dev/becwright/actions/workflows/ci.yml)
+
+**Rules that run, not notes that get ignored.**
+
+`becwright` enforces constraints on your code deterministically: instead of
+*asking* an AI agent to respect a rule (the way `CLAUDE.md`, `.cursorrules`,
+etc. do — which the agent can read and ignore), becwright **verifies the
+result** and blocks the commit if the rule is broken.
+
+## The problem
+
+An AI agent writes code and leaves a note: *"this must never log session
+tokens"*. That note is text. Three months later, another agent regenerates the
+module, doesn't read it, and drops the token into the logs. Nobody notices
+until it blows up in production.
+
+Notes are **probabilistic** (they depend on the agent reading, understanding and
+obeying). becwright is **deterministic**: the rule runs against the real code
+and returns pass/fail, no matter which agent or model made the change.
+
+| | Note in CLAUDE.md | becwright rule |
+|---|---|---|
+| What it does | *Asks* to be respected | *Verifies* it was respected |
+| Depends on | The agent reading and obeying | Nothing — it runs against the code |
+| Result | Likely | Guaranteed |
+| Analogy | A "speed limit" sign | A physical bump in the road |
+
+The two layers are complementary: CLAUDE.md prevents (so 95% comes out right the
+first time), becwright is the safety net for the 5% that slips through.
+
+## Core concept: BEC (Bound Executable Constraint)
+
+A BEC is a constraint with three properties that no current artifact has
+together:
+
+- **Bound** — the rule is born tied to the *intent* and the decision that
+  created it (the *why*); it is not a loose rule without context.
+- **Executable** — it carries a check that runs and returns pass/fail; it is not
+  prose someone promises to respect.
+- **Portable** — it can be exported from one repo and imported into another,
+  like a package (this is what creates the network effect over time).
+
+## How to use it
+
+becwright is installed once as a tool; each repo only contributes its own
+`.bec/rules.yaml`.
+
+```bash
+# 1. Install the engine (once, global)
+pipx install git+https://github.com/DataDave-Dev/becwright.git   # or local: pipx install .
+
+# 2. In the repo where you want the rules, install the git hook
+becwright install                   # writes .git/hooks/pre-commit
+
+# 3. Write your rules in .bec/rules.yaml (see examples below)
+# 4. Done: each commit runs the checks; if a blocking rule fails, it stops.
+```
+
+Available commands:
+
+| Command | What it does |
+|---|---|
+| `becwright check` | Runs the rules over the staged files |
+| `becwright install` | Installs the native `pre-commit` hook |
+| `becwright uninstall` | Removes the hook |
+| `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
+| `becwright import <file\|URL>` | Imports a BEC from another repo |
+
+A rule in `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-token-in-logs
+    intent: >
+      Session tokens and credentials must never reach any log.
+    why_it_matters: >
+      If a token shows up in the logs, anyone with access to them can steal a
+      user's session.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.no_token_in_logs"
+    severity: blocking   # blocking = stops the commit | warning = only warns
+```
+
+## Included checks
+
+becwright ships ready-to-use checks. Each one is a module invoked from the
+`check` field. They are **text/regex based** (no AST analysis), so they are
+conservative and may have edge cases; the value is in tying each rule to its
+*why*.
+
+| Check | What it detects | Language | Suggested severity |
+|---|---|---|---|
+| `forbid` | Any regex you pass (`--pattern`) | any | depends on the case |
+| `no_token_in_logs` | Tokens/credentials in log calls | Python | `blocking` |
+| `hardcoded_secrets` | AWS keys, private keys, `password = "..."` literals | any | `blocking` |
+| `debug_remnants` | Forgotten `breakpoint()`, `pdb.set_trace()`, `import pdb` | Python | `blocking` |
+| `dangerous_eval` | `eval()` / `exec()` calls | any | `blocking` |
+| `wildcard_imports` | `from x import *` | Python | `warning` |
+
+Example rules to copy into your `.bec/rules.yaml`:
+
+```yaml
+rules:
+  - id: no-hardcoded-secrets
+    intent: >
+      No secret (key, token, password) should be hardcoded in the code.
+    why_it_matters: >
+      A secret in the repo stays in git history forever and is visible to
+      anyone with access to the code.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.hardcoded_secrets"
+    severity: blocking
+
+  - id: no-debug-remnants
+    intent: >
+      Debug code (breakpoints, pdb) must not be committed.
+    why_it_matters: >
+      A forgotten breakpoint hangs the process in production or CI.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.debug_remnants"
+    severity: blocking
+
+  - id: no-dangerous-eval
+    intent: >
+      Do not use eval()/exec(), which execute arbitrary code.
+    why_it_matters: >
+      eval/exec on untrusted input is remote code execution.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.dangerous_eval"
+    severity: blocking
+
+  - id: no-wildcard-imports
+    intent: >
+      Avoid 'from x import *', which pollutes the namespace.
+    why_it_matters: >
+      Wildcard imports hide where each name comes from and break static
+      analysis.
+    paths: ["src/**/*.py"]
+    check: "python3 -m becwright.checks.wildcard_imports"
+    severity: warning
+```
+
+## Any language
+
+becwright is **language-agnostic**: the engine only filters files by their
+`paths` (globs) and runs the `check` as a command; it never assumes Python. You
+can watch JavaScript, Go, Rust, or anything else.
+
+The fastest way to write a rule for another language —without writing code— is
+the `forbid` check, which fails if a regex appears in the files:
+
+```yaml
+rules:
+  - id: no-debugger-js
+    intent: >
+      Do not leave 'debugger;' in JavaScript/TypeScript code.
+    why_it_matters: >
+      A forgotten 'debugger' halts execution and should not reach production.
+    paths: ["**/*.js", "**/*.ts"]
+    check: "python3 -m becwright.checks.forbid --pattern '\\bdebugger\\b'"
+    severity: blocking
+```
+
+`forbid` accepts `--pattern REGEX`, `--ignore-case` and `--message TEXT`. For
+finer checks, write your own script in whatever language you want (an executable
+that reads the file list from stdin and exits with code 0/1) and point `check`
+at it.
+
+## Sharing BECs between repos
+
+A BEC is **portable**: you can take it out of one repo and install it in
+another. A bundle is a single self-contained `.bec.yaml` file (the rule + the
+check's code if it is custom).
+
+```bash
+# In the source repo: export a rule to a file
+becwright export no-token-in-logs -o no-token-in-logs.bec.yaml
+
+# In another repo: import it (from a file or an http/https URL)
+becwright import no-token-in-logs.bec.yaml
+becwright import https://example.com/no-token-in-logs.bec.yaml
+```
+
+On import, becwright **shows the check's code and asks for confirmation** before
+installing it: importing a BEC is importing code that will run on every commit.
+Use `--yes` to skip the confirmation in automated environments.
+
+There is a **catalog of ready-to-use BECs** in [`becs/`](becs/) that you can
+import directly from their raw URL.
+
+Built-in checks (`python3 -m becwright.checks.*`) travel with the package, so
+the bundle only stores their name. A **custom** check (`.bec/checks/foo.py`)
+travels with its code embedded and lands in `.bec/checks/` of the target repo.
+
+## Current status
+
+The **installable MVP** is built and verified end-to-end: packaged engine
+(`src/becwright/`), CLI (`check` / `install` / `uninstall` / `export` /
+`import`), native git hook that blocks a commit with a token in a log, included
+checks (Python + the generic `forbid` for any language), BEC portability between
+repos, a catalog with Python and JS/TS BECs, and a green test suite. The original
+prototype is **archived** under `prototype/` as a reference.
+
+Future work (AST analysis, deep per-language tooling, cryptographic signing of
+verifications) is documented in the project plan.

becwright-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+# Packaging for becwright. Target Python 3.12 (current environment has 3.14).
+# Minimal dependencies on purpose: only pyyaml (project convention).
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "becwright"
+version = "0.1.0"
+description = "Deterministically enforces constraints (BECs) on your code, blocking commits that violate them."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Alonso David De Leon Rodarte" }]
+license = { text = "MIT" }
+dependencies = ["pyyaml>=6"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+# The global command. `pipx install .` makes `becwright` available on PATH.
+[project.scripts]
+becwright = "becwright.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

becwright-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

becwright-0.1.0/src/becwright/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

becwright-0.1.0/src/becwright/bundle.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import re
+import subprocess
+import textwrap
+from pathlib import Path
+
+import yaml
+
+from .rules import Rule
+
+BUNDLE_VERSION = 1
+
+_BUILTIN = re.compile(r"^python3?\s+-m\s+becwright\.checks\.(\w+)(?:\s+(.*))?$")
+_PY_PATH = re.compile(r"[\w./-]+\.py")
+_ITEM_INDENT = re.compile(r"^([ \t]+)-\s", re.MULTILINE)
+_EMPTY_RULES = re.compile(r"^rules:[ \t]*(?:\[[ \t]*\]|\{[ \t]*\})[ \t]*$", re.MULTILINE)
+
+
+class BundleError(RuntimeError):
+    pass
+
+
+def _clean(value):
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, list):
+        return [v.strip() if isinstance(v, str) else v for v in value]
+    return value
+
+
+def _origin(root: Path) -> str:
+    res = subprocess.run(
+        ["git", "config", "--get", "remote.origin.url"],
+        cwd=root, capture_output=True, text=True,
+    )
+    return res.stdout.strip() or root.name
+
+
+def classify_check(command: str, root: Path) -> dict:
+    command = command.strip()
+    builtin = _BUILTIN.match(command)
+    if builtin:
+        out = {"kind": "builtin", "module": builtin.group(1)}
+        if builtin.group(2):
+            out["args"] = builtin.group(2).strip()
+        return out
+    for token in _PY_PATH.findall(command):
+        candidate = root / token
+        if candidate.is_file():
+            return {
+                "kind": "script",
+                "filename": Path(token).name,
+                "source": candidate.read_text(encoding="utf-8"),
+            }
+    return {"kind": "command", "command": command}
+
+
+def export_bec(rule: Rule, root: Path) -> str:
+    rule_fields: dict = {"id": rule.id}
+    if rule.intent:
+        rule_fields["intent"] = rule.intent
+    if rule.why_it_matters:
+        rule_fields["why_it_matters"] = rule.why_it_matters
+    if rule.rejected_alternatives:
+        rule_fields["rejected_alternatives"] = list(rule.rejected_alternatives)
+    rule_fields["paths"] = list(rule.paths)
+    rule_fields["severity"] = rule.severity
+
+    bundle = {
+        "becwright_bec": BUNDLE_VERSION,
+        "exported_from": _origin(root),
+        "rule": rule_fields,
+        "check": classify_check(rule.check, root),
+    }
+    return yaml.safe_dump(bundle, sort_keys=False, allow_unicode=True)
+
+
+def parse_bundle(text: str) -> dict:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise BundleError(f"The bundle is not valid YAML: {e}")
+    if not isinstance(data, dict):
+        raise BundleError("The bundle is empty or malformed.")
+    if data.get("becwright_bec") != BUNDLE_VERSION:
+        raise BundleError(
+            f"Unsupported bundle version: {data.get('becwright_bec')!r} "
+            f"(expected {BUNDLE_VERSION})."
+        )
+    rule = data.get("rule")
+    check = data.get("check")
+    if not isinstance(rule, dict) or "id" not in rule:
+        raise BundleError("The bundle has no valid rule (missing 'rule.id').")
+    if not isinstance(check, dict) or "kind" not in check:
+        raise BundleError("The bundle has no valid check (missing 'check.kind').")
+    required = {"builtin": ("module",), "script": ("filename", "source"), "command": ("command",)}
+    kind = check["kind"]
+    if kind not in required:
+        raise BundleError(f"Unknown check kind: {kind!r}.")
+    missing = [f for f in required[kind] if not check.get(f)]
+    if missing:
+        raise BundleError(f"The '{kind}' check is missing fields: {', '.join(missing)}.")
+    return data
+
+
+def materialize(bundle: dict, root: Path) -> dict:
+    check = bundle["check"]
+    kind = check.get("kind")
+    if kind == "builtin":
+        command = f"python3 -m becwright.checks.{check['module']}"
+        if check.get("args"):
+            command += f" {check['args']}"
+    elif kind == "script":
+        filename = Path(check["filename"]).name
+        dest = root / ".bec" / "checks" / filename
+        source = check["source"]
+        if dest.exists() and dest.read_text(encoding="utf-8") != source:
+            raise BundleError(
+                f"A different check already exists at {dest}. Not overwriting it; resolve by hand."
+            )
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(source, encoding="utf-8")
+        dest.chmod(0o755)
+        command = f"python3 .bec/checks/{filename}"
+    elif kind == "command":
+        command = check["command"]
+    else:
+        raise BundleError(f"Unknown check kind: {kind!r}")
+
+    rule = bundle["rule"]
+    out: dict = {"id": rule["id"]}
+    for key in ("intent", "why_it_matters", "rejected_alternatives"):
+        if rule.get(key):
+            out[key] = _clean(rule[key])
+    out["paths"] = rule.get("paths", [])
+    out["check"] = command
+    out["severity"] = rule.get("severity", "blocking")
+    return out
+
+
+def append_rule(rules_path: Path, rule_dict: dict) -> None:
+    dumped = yaml.safe_dump([rule_dict], sort_keys=False, allow_unicode=True)
+    if not rules_path.exists():
+        rules_path.parent.mkdir(parents=True, exist_ok=True)
+        rules_path.write_text("rules:\n" + textwrap.indent(dumped, "  "), encoding="utf-8")
+        return
+    # Normalize an empty inline list (`rules: []`) so block items can follow it.
+    text = _EMPTY_RULES.sub("rules:", rules_path.read_text(encoding="utf-8"), count=1)
+    if text and not text.endswith("\n"):
+        text += "\n"
+    if not re.search(r"^rules:", text, re.MULTILINE):
+        text += "rules:\n"
+    # Match the indentation the file already uses for list items.
+    existing = _ITEM_INDENT.search(text)
+    prefix = existing.group(1) if existing else "  "
+    rules_path.write_text(text + textwrap.indent(dumped, prefix), encoding="utf-8")