Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(devex): fix isolation guidance and steer stamphog on exemptions (#128131)

Julian Bezd387f19c330a
diff --git a/.stamphog/README.md b/.stamphog/README.md
index 1a995fe634b3..47c79083f022 100644
--- a/.stamphog/README.md
+++ b/.stamphog/README.md
@@ -22,6 +22,7 @@ The repository uses the shipped default `review-guidance.md`.
`steering.md` tells the reviewer to refuse a diff that adds a suppression or an exemption for one of those guards.
A path rule cannot see these, because the marker sits in product code or in a busy file.
+That covers the isolation exemptions inside `tach.toml` and the product `turbo.json` files, which stay off the deny list because most of their edits are routine `depends_on` and input additions.
`ownership` comes from the shipped default, which declares one `hogli-resolver` source at the repo root, so stamphog reads the same merged view the reviewer auto-assigner builds.
diff --git a/.stamphog/steering.md b/.stamphog/steering.md
index e6d964f43d70..10c1d8f5765c 100644
--- a/.stamphog/steering.md
+++ b/.stamphog/steering.md
@@ -4,7 +4,12 @@ Refuse when the diff adds a suppression or an exemption for one of these guards:
- a `nosemgrep` marker for a rule in `.semgrep/rules/devex/` or for `prefer-codegen-api`, or a bare `nosemgrep` with no rule id
- a `# tach-ignore` marker
- an `ignore_imports` entry in the `[tool.importlinter]` section of `pyproject.toml`
-- a new line in `products/model_crossing_uses_baseline.txt`, or a new `exposes` entry in `tach.toml`
+- a new line in `products/model_crossing_uses_baseline.txt`
+- a new `expose` pattern in `tach.toml`, or a product name added to the `from` list of an `[[interfaces]]` table
+- a new `# isolation:permanent-interface` marker in `tach.toml`
+- a removed or narrowed entry, or an added `!` exclusion, in the `backend:contract-check` `inputs` of a `products/*/turbo.json`
- a new name in `ENUM_NAME_OVERRIDES` in `posthog/settings/web.py`
Removed lines and removed markers are fine: the guard got tighter.
+An added positive `contract-check` input is fine too: the product watches more code.
+A `depends_on` change in `tach.toml` is fine: it declares the import graph, not an exemption.
diff --git a/docs/internal/monorepo-layout.md b/docs/internal/monorepo-layout.md
index 5f0a8b59a3fc..da11ebd55a9a 100644
--- a/docs/internal/monorepo-layout.md
+++ b/docs/internal/monorepo-layout.md
@@ -80,8 +80,8 @@ Turbo cannot hash files behind a path link, so `products/desktop/scripts/build-a
Most products are a Django app plus React scenes — and most already carry more: an `mcp/` directory of MCP tool definitions, often a `skills/` directory of agent skills. A product can own anything attributable to it, runtime and tooling alike. Nest it under the product instead of scattering it across top-level dirs:
-- `products/<product>/mcp/` — MCP tool definitions (`tools.yaml`) and UI apps (most products)
-- `products/<product>/skills/` — agent skills for the product (many products)
+- `products/<product>/mcp/` — MCP tool definitions (`tools.yaml`) and UI apps (most products). Hand-written tool hooks stay in `services/mcp/src/tools/`, because `tools.yaml` resolves `hooks:` paths there.
+- `products/<product>/skills/` — published agent skills for the product (many products). A skill that needs a checkout of this repository goes in `.agents/skills/`, even when one product owns it (see `/writing-skills`).
- `products/<product>/services/<svc>/` — a service or worker the product deploys
- `products/<product>/packages/<lib>/` — a library or CLI the product owns
- dev/CI/backfill scripts, benchmarks, audits, fixtures and dummy-data generators, a standalone console — same idea
diff --git a/products/README.md b/products/README.md
index 746cc4f2c4c4..f4b47a45b2bf 100644
--- a/products/README.md
+++ b/products/README.md
@@ -49,7 +49,7 @@ products/
logics/
generated/ # OpenAPI-generated TypeScript types
mcp/ # MCP tool definitions (tools.yaml) and UI apps — most products
- skills/ # agent skills for the product — many products
+ skills/ # published agent skills for the product — many products
services/ # optional: a service this product deploys
packages/ # optional: a library/CLI this product owns
```
@@ -112,7 +112,7 @@ Keep shared code minimal to avoid tight coupling.
Beyond `backend/` + `frontend/` + `manifest.tsx` + `package.json`, most products also carry:
- `mcp/` — MCP tool definitions (`tools.yaml`) and UI apps (the majority of products expose these)
-- `skills/` — agent skills for the product (many products)
+- `skills/` — published agent skills for the product (many products). A skill that needs a repository checkout goes in `.agents/skills/` (see `/writing-skills`)
And anything else attributable to a single product — nest it here rather than in a top-level dir:
diff --git a/products/architecture.md b/products/architecture.md
index ae437d3dc1bd..3ac25b0376d6 100644
--- a/products/architecture.md
+++ b/products/architecture.md
@@ -111,9 +111,10 @@ These cross the boundary as classes — allowed only under all three rules:
The lint reads coverage per location rather than per subtree, so it cannot hold that scope; the repo invariant `test_product_analytics_drives_only_the_watched_subtree` does, and it fails when a line names code outside the watched subtree.
The other locations stay in the inputs by presence until their channel (Celery task names, Temporal workflow names, Max tool names) is read the same way.
3. **Validated registration.**
- Registration points check `issubclass(cls, Base)` and reject anything else.
+ A registration point accepts only implementations of its base and rejects anything else.
Import linters (tach, import-linter) see only the import graph; _what an object is_ can only be checked at runtime, at the door.
- `ee/hogai/registry.py` (MaxTool) is the reference implementation: subclass auto-registration with validation.
+ `MaxTool` is the reference implementation: a class registers itself by subclassing (`__init_subclass__` in `ee/hogai/tool.py`), so only a `MaxTool` enters the registry, and the hook rejects an unknown tool name.
+ The Temporal worker, Celery task discovery and `get_query_runner` do not validate yet: they accept whatever the wiring location holds.
Django models never cross, with or without an approved base.
A model cannot be narrowed: whatever interface it presents, the object still carries managers, `save()`/`delete()`, FK descriptors that query other tables on attribute access, and reverse relations added by other apps.