gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/scaffold.py

@@ -0,0 +1,250 @@
+"""Initialize a schema world from a connector template or the custom template.
+
+Templates are authored ``gateway-world/1`` contracts shipped with the SDK, one
+directory per connector under ``connectors/``. Initializing copies the authored
+files, compiles them, and writes an empty initial batch; the world starts with
+no records and is filled by ingestion or by hand-authored fixture batches.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from .compiler import Contract, compile_bundle
+from .validation import ContractError, encoded, fail, read_json
+
+TEMPLATES = Path(__file__).resolve().parent / "connectors"
+CUSTOM = "custom"
+MANIFEST = """[environment]
+name = "{name}"
+kind = "mock-tools"
+db = "sqlite"
+connector = "{connector}"
+
+[schema]
+language = "gateway-world/1"
+
+[tools]
+serve = [{serve}]
+
+[db]
+engine = "sqlite"
+"""
+VERIFIER = """-- Scores 1.0 once the world holds any {entity} row; edit for real tasks.
+SELECT CASE WHEN COUNT(*) > 0 THEN 1.0 ELSE 0.0 END FROM "{entity}";
+"""
+
+
+def list_templates() -> list[str]:
+    """Connector slugs that ``init_bundle`` accepts, custom last."""
+    slugs = sorted(p.name for p in TEMPLATES.iterdir() if (p / "world.json").is_file())
+    return [s for s in slugs if s != CUSTOM] + [CUSTOM]
+
+
+def _slug(value: str, location: str) -> str:
+    if not value or any(c not in "abcdefghijklmnopqrstuvwxyz0123456789-_" for c in value):
+        fail("identity", "Use lowercase letters, digits, - or _", location)
+    return value
+
+
+def _resource(path: Path) -> Path:
+    if path.is_symlink() or path.parent.is_symlink() or not path.is_file():
+        fail("template", "Template resources must be regular files, not symlinks", str(path))
+    return path
+
+
+SUPPORTING_SUFFIXES = {".json", ".md", ".toml"}
+GENERATED_NAMES = {"base.json", "runtime.json", "lock.json", "README.md", "tool-schemas.json"}
+#: Template files that are not schema artifacts but travel with a workspace connector.
+TEMPLATE_CODE = {"handlers.py", "api/handlers.py"}
+
+
+def template_digest(files: dict[str, bytes]) -> str:
+    """The same digest the platform computes over an installed template directory:
+    sha256 over sorted ``path\0bytes\0``. A workspace connector's commit and an
+    installed template with identical files therefore pin identically."""
+    import hashlib
+
+    digest = hashlib.sha256()
+    for path in sorted(files):
+        digest.update(path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(files[path])
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def init_bundle_from_files(
+    destination: str | Path, files: dict[str, bytes], *, connector: str, name: str | None = None
+) -> Contract:
+    """Create and compile a schema world from a template held in memory: a workspace
+    connector's files (``world.json``, ``connector.toml``, ``provenance.json``,
+    ``scope.toml``, ``handlers.py``, ``api/handlers.py``, ``scenarios/…``), exactly
+    what :func:`init_bundle` reads from an installed template directory.
+
+    ``connector`` names the template for the manifest; ``name`` the world."""
+    destination = Path(destination)
+    connector = _slug(connector, "/init/connector")
+    name = _slug(name if name is not None else f"{connector}-world", "/init/name")
+    if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
+        fail("state_exists", "Destination must be a new or empty directory", "/init")
+    if "world.json" not in files:
+        fail("template", "A connector template needs world.json", "/init/files")
+    if not all(isinstance(k, str) and k and not k.startswith("/") and ".." not in k.split("/") for k in files):
+        fail("template", "Template paths must be relative and stay inside the template", "/init/files")
+    try:
+        world = json.loads(files["world.json"].decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        fail("template", "world.json is not valid JSON", "/init/files/world.json")
+    if not isinstance(world, dict) or not isinstance(world.get("x-gateway"), dict):
+        fail("template", "world.json is not a gateway-world document", "/init/files/world.json")
+    world["x-gateway"]["package"]["id"] = name
+    tools = sorted(world["x-gateway"].get("tools", {}))
+    try:
+        (destination / "schema").mkdir(parents=True)
+        (destination / "schema/world.json").write_bytes(_pretty(world))
+        shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
+        (destination / "tools").mkdir()
+        handlers = files.get("handlers.py") or files.get("tools/handlers.py")
+        (destination / "tools/handlers.py").write_bytes(handlers if handlers is not None else b"")
+        for path, content in sorted(files.items()):
+            if path in {"world.json", "handlers.py", "tools/handlers.py"} or path.startswith("__pycache__"):
+                continue
+            if path == "connector.toml":
+                target = destination / "connector.toml"
+            elif path.startswith(("api/", "scenarios/")):
+                target = destination / path
+            elif path.startswith("evidence/") or path.startswith("reports/"):
+                continue  # authoring evidence stays with the connector, not the world
+            elif (
+                Path(path).suffix in SUPPORTING_SUFFIXES and Path(path).name not in GENERATED_NAMES and "/" not in path
+            ):
+                target = destination / "schema" / path
+            else:
+                fail("template", "Unsupported or generated template artifact", f"/init/files/{path}")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+        (destination / "gateway-env.toml").write_text(
+            MANIFEST.format(name=name, connector=connector, serve=", ".join(f'"{t}"' for t in tools)),
+            encoding="utf-8",
+        )
+        entities = sorted(world["x-gateway"].get("entities", {}))
+        if not entities:
+            fail("template", "world.json declares no entities", "/init/files/world.json")
+        (destination / "verifiers").mkdir()
+        (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=entities[0]), encoding="utf-8")
+        contract = compile_bundle(destination)
+        (destination / "data").mkdir()
+        (destination / "data/records.json").write_bytes(_pretty([]))
+        (destination / "data/initial.json").write_bytes(
+            encoded(
+                {
+                    "id": f"{name}.initial.v1",
+                    "target": contract.target,
+                    "mapping": {"id": "empty", "version": "1"},
+                    "coverage": "partial",
+                    "mutations": [],
+                }
+            )
+        )
+    except BaseException:
+        shutil.rmtree(destination, ignore_errors=True)
+        raise
+    return contract
+
+
+def init_bundle(destination: str | Path, *, connector: str = CUSTOM, name: str | None = None) -> Contract:
+    """Create and compile a schema world at ``destination`` from a template.
+
+    The destination must not exist or must be an empty directory. ``name``
+    becomes the environment name and package id; the domain ``$id`` stays the
+    connector's so worlds built from one connector share a domain identity.
+    """
+    destination = Path(destination)
+    connector = _slug(connector, "/init/connector")
+    if connector not in list_templates():
+        fail(
+            "template",
+            f"Unknown connector template; choose one of {', '.join(list_templates())}",
+            "/init/connector",
+        )
+    name = _slug(name if name is not None else f"{connector}-world", "/init/name")
+    if destination.exists() and (not destination.is_dir() or any(destination.iterdir())):
+        fail("state_exists", "Destination must be a new or empty directory", "/init")
+    template = TEMPLATES / connector
+    # Templates may carry sibling schema dependencies and model evidence. Keep
+    # every authored artifact in initialized worlds; never silently drop files.
+    supporting_files = []
+    for path in sorted(template.iterdir()):
+        # pip compiles the shipped handler module during installation.
+        if path.name == "__pycache__" and path.is_dir() and not path.is_symlink():
+            continue
+        _resource(path)
+        if path.name in {"world.json", "handlers.py"}:
+            continue
+        if path.suffix not in {".json", ".md", ".toml"} or path.name in {
+            "base.json",
+            "runtime.json",
+            "lock.json",
+            "README.md",
+            "tool-schemas.json",
+        }:
+            fail("template", "Unsupported or generated template artifact", str(path))
+        supporting_files.append(path)
+    world = read_json(_resource(template / "world.json"))
+    world["x-gateway"]["package"]["id"] = name
+    tools = sorted(world["x-gateway"]["tools"])
+    try:
+        (destination / "schema").mkdir(parents=True)
+        (destination / "schema/world.json").write_bytes(_pretty(world))
+        shutil.copyfile(_resource(TEMPLATES / "base.json"), destination / "schema/base.json")
+        for path in supporting_files:
+            # The connection spec sits at the world root, where `worlds connector` and
+            # `worlds serve` look for it; everything else describes the schema.
+            target = destination / path.name if path.name == "connector.toml" else destination / "schema" / path.name
+            if connector == "slack" and path.name == "capabilities.json":
+                from ._slack_fidelity import expand_capabilities
+
+                target.write_bytes(_pretty(expand_capabilities(read_json(_resource(path)))))
+            else:
+                shutil.copyfile(_resource(path), target)
+        (destination / "tools").mkdir()
+        shutil.copyfile(_resource(template / "handlers.py"), destination / "tools/handlers.py")
+        (destination / "gateway-env.toml").write_text(
+            MANIFEST.format(
+                name=name,
+                connector=connector,
+                serve=", ".join(f'"{t}"' for t in tools),
+            ),
+            encoding="utf-8",
+        )
+        first_entity = sorted(world["x-gateway"]["entities"])[0]
+        (destination / "verifiers").mkdir()
+        (destination / "verifiers/state_present.sql").write_text(VERIFIER.format(entity=first_entity), encoding="utf-8")
+        contract = compile_bundle(destination)
+        (destination / "data").mkdir()
+        (destination / "data/records.json").write_bytes(_pretty([]))
+        (destination / "data/initial.json").write_bytes(
+            encoded(
+                {
+                    "id": f"{name}.initial.v1",
+                    "target": contract.target,
+                    "mapping": {"id": "empty", "version": "1"},
+                    "coverage": "partial",
+                    "mutations": [],
+                }
+            )
+        )
+    except BaseException:
+        shutil.rmtree(destination, ignore_errors=True)
+        raise
+    return contract
+
+
+def _pretty(value) -> bytes:
+    return (json.dumps(value, indent=2) + "\n").encode("utf-8")
+
+
+__all__ = ["CUSTOM", "TEMPLATES", "ContractError", "init_bundle", "list_templates"]

gatewaysdk/environment/schema/skill.py

@@ -0,0 +1,118 @@
+"""The skills shipped with the SDK, so any agent can pick them up.
+
+Stdlib only, like the rest of ``environment.schema``: the offline entry point
+(``python -m gatewaysdk.environment.schema skill``) prints and installs them
+from a vendored copy of this subpackage, without the platform client.
+``gatewaysdk.connectors.skill`` re-exports this module.
+
+``gateway worlds skill NAME`` prints one; ``--install DIR`` lands it in a
+repository's ``.claude/`` (the skill's files, plus any agent it ships), the
+layout Claude Code, Cursor and Codex read. The files are package data under
+``gatewaysdk/environment/schema/skills/<name>/``; the repository's own copies
+under ``.claude/`` are the source, mirrored there with a "For agents" note on
+top. ``gateway worlds connector skill`` is the connector-authoring skill's
+older spelling and stays.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List
+
+SKILLS = Path(__file__).resolve().parent / "skills"
+SKILL_NAME = "connector-schema-authoring"
+SKILL_FILES = ("SKILL.md", "CONVENTIONS.md", "CONNECTORS.md")
+AGENT_FILE = "connector-template-author.md"
+#: Agents a skill installs beside itself, under ``.claude/agents/``.
+SKILL_AGENTS = {SKILL_NAME: (AGENT_FILE,)}
+NEXT_STEP = "gateway worlds schema init ./<vendor>-world --connector custom"
+NEXT_STEPS = {
+    SKILL_NAME: NEXT_STEP,
+    "world-data-ingestion": "gateway worlds data import <world> rows.json",
+    "worlds-getting-started": "gateway worlds schema init ./my-world --connector custom",
+}
+
+
+def packaged_skills() -> List[str]:
+    """Every skill the package ships: a directory under ``skills/`` holding a SKILL.md."""
+    return sorted(path.parent.name for path in SKILLS.glob("*/SKILL.md"))
+
+
+def _skill_dir(name: str) -> Path:
+    directory = SKILLS / name
+    if "/" in name or "\\" in name or not (directory / "SKILL.md").is_file():
+        raise KeyError(f"No packaged skill {name!r}; the package ships: {', '.join(packaged_skills())}")
+    return directory
+
+
+def skill_text(name: str = SKILL_NAME) -> str:
+    """The packaged SKILL.md of ``name``: the checklist an agent follows."""
+    return (_skill_dir(name) / "SKILL.md").read_text(encoding="utf-8")
+
+
+def packaged_files(name: str = SKILL_NAME) -> Dict[str, Path]:
+    """Repository-relative destination → packaged source, for every file the skill installs."""
+    directory = _skill_dir(name)
+    files = {
+        f".claude/skills/{name}/{path.relative_to(directory).as_posix()}": path
+        for path in sorted(directory.rglob("*"))
+        if path.is_file() and "__pycache__" not in path.parts
+    }
+    for agent in SKILL_AGENTS.get(name, ()):
+        files[f".claude/agents/{agent}"] = SKILLS / "agents" / agent
+    return files
+
+
+def next_step(name: str = SKILL_NAME) -> str | None:
+    """The command an agent runs once the skill is installed, when the skill has one."""
+    return NEXT_STEPS.get(name)
+
+
+@dataclass
+class InstallReport:
+    written: List[str] = field(default_factory=list)
+    unchanged: List[str] = field(default_factory=list)
+    conflicts: List[str] = field(default_factory=list)
+
+
+def install_skill(destination: str | Path, *, name: str = SKILL_NAME, force: bool = False) -> InstallReport:
+    """Write the skill (and its agents) under ``destination/.claude/``.
+
+    An existing file with the same content is left alone; one with different
+    content is a conflict and nothing is written unless ``force`` — the
+    repository's edits are theirs to keep, so the refusal comes before any write.
+    """
+    root = Path(destination)
+    report = InstallReport()
+    planned: Dict[Path, bytes] = {}
+    for relative, source in packaged_files(name).items():
+        content = source.read_bytes()
+        target = root / relative
+        if target.exists() and target.read_bytes() == content:
+            report.unchanged.append(relative)
+        elif target.exists() and not force:
+            report.conflicts.append(relative)
+        else:
+            planned[target] = content
+            report.written.append(relative)
+    if report.conflicts:
+        report.written = []
+        return report
+    for target, content in planned.items():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+    return report
+
+
+__all__ = [
+    "InstallReport",
+    "NEXT_STEP",
+    "SKILLS",
+    "SKILL_NAME",
+    "install_skill",
+    "next_step",
+    "packaged_files",
+    "packaged_skills",
+    "skill_text",
+]

gatewaysdk/environment/schema/skills/agents/connector-template-author.md

@@ -0,0 +1,202 @@
+---
+name: connector-template-author
+model: opus
+description: |
+  Implements ONE connector schema template under the unified gateway-world/1
+  contract from a brief in .claude/skills/connector-schema-authoring/briefs/.
+  Owns exactly one directory (gatewaysdk/environment/schema/connectors/<slug>/)
+  plus that connector's rows in the reference tables, and nothing else, so many
+  authors run in parallel without overlap. Follows the connector-schema-authoring
+  skill checklist and the generation conventions; the conventions test is the
+  merge gate.
+
+  <example>
+  Context: Briefs exist for every connector; time to build the templates in parallel.
+  user: "Implement the Okta connector template from its brief"
+  assistant: "I'll spawn connector-template-author with briefs/okta.md; it owns connectors/okta/ only."
+  </example>
+
+  <example>
+  Context: A template exists but was hand-typed before the vendor spec was pinned.
+  user: "Re-derive the GitHub template from the published OpenAPI and pin provenance"
+  assistant: "I'll spawn connector-template-author with briefs/github.md in re-import mode."
+  </example>
+---
+
+# Connector Template Author
+
+## Role Contract
+
+You are: A schema author who turns one connector brief into a faithful `gateway-world/1`
+template. The data model is the deliverable. Tools are optional and only what the brief
+asks for.
+
+Goal: `gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/<slug>/` contains
+`world.json`, `provenance.json`, `scope.toml` (if imported), and `handlers.py` (if the
+brief ships tools), such that `init --connector <slug>` produces a world that compiles,
+checks, runs, and passes `test_committed_templates_follow_the_generation_conventions`
+and the scaffold suite.
+
+Constraints:
+- Write ONLY inside your slug's directory, plus the rows the brief names in
+  `CONNECTORS.md` (your connector's row in "Status of templates" and your dossier block)
+  and your slug's line in the `PREFIXES` table of `test_schema_scaffold.py`.
+- Never touch `base.json`, `scaffold.py`, the compiler, the store, other templates, or
+  another connector's rows. If a shared file must change, stop and report it.
+- Never invent vendor facts. Every entity, field, enum, and error comes from the source the
+  brief pins; anything you could not confirm is listed under `unverified` in `provenance.json`.
+- Never put vendor or customer data in `data/records.json` or goldens; synthetic only.
+- Keep every scratch file in your OWN subdirectory (`<scratch root>/<slug>/`). Authors run in
+  parallel and share one scratch root; generic names like `roundtrip.py` clobber a peer's work.
+- Never bend the model to fit a tool or an MCP surface; report mismatches in the summary.
+
+## Work Protocol
+
+### Phase 1: Read, then confirm scope
+
+1. Read, in order: the brief; `SKILL.md`, `CONVENTIONS.md`, `CONNECTORS.md` in
+   `.claude/skills/connector-schema-authoring/`; `documentation/features/world-schema.md`.
+2. Read one existing template of the same shape as a pattern (the brief names it).
+3. Fetch the pinned sources from the brief. Record URL, version, and SHA-256 for
+   `provenance.json` before reading them.
+
+```
+SCOPE CONFIRMATION:
+- Brief: briefs/<slug>.md
+- Shape: base | mixed | tenant-shaped
+- Prefix: <prefix_> (reserved in PREFIXES)
+- Files I own: connectors/<slug>/*, my rows in CONNECTORS.md, my PREFIXES line
+- Files I will NOT touch: everything else
+- Sources pinned: [url, version, sha256] ...
+```
+
+### Phase 2: Model
+
+Build `world.json` entity by entity from the pinned source, in the brief's order:
+
+- primary key = the vendor's id; composite keys in containment order
+- relationships on the child, `on_delete: restrict`; membership as its own entity
+- vendor casing on field names; `base.json` primitives by `$ref`
+- nullable vs optional exactly as the vendor documents; enums verbatim, vendor order
+- the error table from the brief's error format
+- for tenant-shaped connectors, the skeleton only: standard objects, and a note in
+  `provenance.json` that describe-on-bind is required
+
+Write `scope.toml` (imported models) with the allowlist, key overrides, relationship
+hints, `polymorphic`, and the reason for every exclusion.
+
+### Phase 2c: Connection and served API (`connector.toml`)
+
+When the brief names a vendor API (base URL, auth scheme, operations the agent calls),
+ship `connector.toml` in the template directory. `init` copies it to the world root, where
+`gateway worlds connector capture|ingest`, `gateway worlds serve` and `gateway bench push` read it.
+The format is documented in `SKILL.md` under "Custom connections" and "Serving the vendor's API":
+
+- `[connector]` slug and `base_url`; `[auth]` scheme (`header|bearer|basic|query|oauth2|none`),
+  `name`, and `secret_env` naming the environment variable, never a value.
+- `[capture]` pacing (`requests_per_minute` low; providers ask us to be sparing), cursor
+  pagination when the vendor has it (`cursor_field` in the body or `cursor_header`);
+  `[redact]` `hash`/`drop` for every PII field the vendor documents returning, `round` for
+  coordinates. Field names keep the vendor's casing.
+- Every operation the vendor's client writes with is a write here: `[operations.api] action`
+  `create`/`update`/`delete` with `body`/`defaults`/`generate`, and `action = "handler"` for
+  anything computed or stateful (executes, status polls, summaries) in the world's
+  `api/handlers.py`. A read-only world is not 1:1; declare `status`, `single`, `envelope`
+  and `page` the way the vendor answers.
+- When a vendor OpenAPI exists, `gateway worlds connector conform <world> --openapi <doc>` is the
+  definition of done: every documented operation answers the documented status with a body the
+  vendor's schema accepts. Seed every entity a by-id route reads; make every create accept the
+  minimal body the vendor's request schema requires. Report the summary line.
+- `[[operations]]` for exactly the operations the brief lists as agent-facing: `name`
+  (the vendor's operationId where it has one), `method`, `path` with `{args}`, `params`,
+  `entity`, and `results` (the dotted path to the row array in the vendor envelope).
+- `[api]` `envelope` matching the vendor's list envelope, and `unauthorized`/`not_found`
+  as the vendor's documented error bodies (JSON strings); `[operations.api] filter` mapping
+  each path argument to the row field it selects on.
+
+Then prove it: `gateway worlds connector validate` on an initialized world, and
+`gateway worlds serve` answering one route from synthetic rows you inserted during
+verification (curl it; check the envelope and the 401 body). Never call the live vendor.
+
+### Phase 3: Tools (only if the brief lists them)
+
+Generate the default set the brief names (`list_<entities>`, `get_<entity>`, one write)
+with handlers on `gateway_env.store`; raise the vendor's error string where the brief lists
+one. If the brief says "no tools", `x-gateway.tools` is `{}` and there is no `handlers.py`.
+
+### Phase 4: Data and verify loop
+
+1. Build a handful of synthetic rows per entity, enough to exercise every relationship
+   (child-first ordering is fine; the store defers reference checks). A template cannot
+   ship `data/records.json` today, so insert them through `store` during verification and
+   record the coverage in `provenance.json` rather than committing a fixture file.
+2. In a temp directory: `gateway worlds schema init <tmp> --connector <slug>` then
+   `compile`, `check`; `init_from_path`, branch, list every entity, run every tool.
+3. `pytest tests/environment/test_schema_scaffold.py -q` and then the full
+   `tests/environment` suite. Iterate until green. Max 3 fix rounds per failure class;
+   then document.
+
+```
+ITERATION LOG:
+Round 1: [change] → [result]
+Round 2: ...
+```
+
+### Phase 5: Reference rows and provenance
+
+- Add or update your row in `CONNECTORS.md` "Status of templates" and your dossier block
+  if the brief changed a fact.
+- `provenance.json`: `shape`, `source` (`kind`, `url`, `version`, `sha256`),
+  `importer` or `authored_by`, `scope_hash`, `generated_at`, `unverified: []`.
+
+### Phase 6: Self-check
+
+```
+SELF-CHECK BEFORE FINALIZING:
+
+SCOPE:
+[ ] Only my directory, my CONNECTORS.md rows, my PREFIXES line changed
+[ ] No shared file changed (base.json, scaffold, compiler, store, other templates)
+
+FIDELITY:
+[ ] Every entity, field, enum, and error traces to a pinned source or is listed unverified
+[ ] Keys, relationships, nullability follow the vendor, not my preference
+[ ] Tenant-shaped: skeleton only, describe-on-bind noted
+[ ] No vendor or customer data anywhere
+
+CONVENTIONS:
+[ ] $id, package id, prefix, plural names, verb_noun tools, closed inputs, layout
+[ ] test_committed_templates_follow_the_generation_conventions passes
+[ ] Full tests/environment suite passes
+
+REPORT:
+[ ] Summary lists: entities, tools, unverified items, mismatches with any MCP surface,
+    anything that needs a shared-file change (not done, reported)
+```
+
+## Output
+
+A single summary in this shape, nothing else:
+
+```
+CONNECTOR: <slug>  SHAPE: <shape>  PREFIX: <prefix_>
+FILES: connectors/<slug>/{world.json, provenance.json[, scope.toml][, handlers.py][, connector.toml]}
+ENTITIES: name (key) [→ relationships] ...
+TOOLS: none | list ...
+CONNECTION: none | <n> operations, auth <scheme>, served <route> -> <status> during verification
+SOURCES: url@version sha256 ...
+UNVERIFIED: ...
+TESTS: scaffold N passed; environment N passed
+NEEDS ORCHESTRATOR: shared-file changes or conflicts, or "none"
+```
+
+## Red Lines
+
+1. **One directory.** Writing outside your slug's directory and your named rows breaks
+   parallel safety; stop and report instead.
+2. **No invented vendor facts.** Unconfirmed becomes `unverified`, never a guess.
+3. **No vendor or customer data** in the template.
+4. **Never edit generated artifacts** (`db/schema.sql`, `runtime.json`, `README.md`,
+   `tool-schemas.json`, `lock.json`); they come from `compile`.
+5. **Never bend the model** to satisfy a tool, a surface, or a test; report the mismatch.
+6. **Never skip the test loop** or finish with a red conventions test.