Company brain: the private tier between the toolkit and a project — template, wiring, CI floor, measured eval

.github/workflows/checks.yml

@@ -36,6 +36,12 @@ jobs:
       - name: No macOS-only assumptions reintroduced (check-portability.sh)
         run: bin/check-portability.sh
 
+      # The public toolkit never cites a private tier (a personal repo, a company brain): five
+      # skills once pointed at files only one person had. templates/company-brain/ is the
+      # sanctioned private tier; this is the direction it must never be cited from.
+      - name: No private-tier citations (check-no-private-citations.sh)
+        run: bin/check-no-private-citations.sh
+
       # The client-NAME denylist is personal and local by design: it lives in the maintainer's
       # gitignored .leakguard-deny and runs in their pre-commit/pre-push hooks
       # (bin/install-hooks.sh) — never in the repo, never required of contributors. In CI the

CLAUDE.md

@@ -77,6 +77,8 @@ git clone https://github.com/MendixMau/mxcli-project-toolkit.git ~/Mendix/mxcli-
 ```
 Each project scaffolded with `bin/init-project.sh` gets the **Baseline routing** table rendered into its `CLAUDE.local.md` (kept current by `bin/sync-project.sh`); its `CLAUDE.md` carries only a short pointer to that file, never a copy of the table (`skills/bootstrap-project.md` Step 2). Only a project with no `CLAUDE.local.md` convention copies the table from `README.md` into `CLAUDE.md` directly. For a self-contained handoff, use a git submodule.
 
+**Company-specific material never lives here either** — own conventions, client-named learnings, house lint rules, approved MPKs go to a *company brain*, a private repo instantiated from `templates/company-brain/` (`skills/company-brain.md`). The public toolkit never cites one: `bin/check-no-private-citations.sh` runs in CI.
+
 **Project output never lives here** — `analysis/`, `sources/`, `knowledge-base/`, `*.mpr` are gitignored. A project's build plan, `PROJECT.md`, and session notes live in that project's own repo; promote reusable patterns into `skills/learned-*.md` instead of accumulating project docs here.
 
 ## Writing in this toolkit — generic first

README.md

@@ -530,6 +530,7 @@ Every mxcli project has a `.ai-context/skills/` directory (bundled by `mxcli ini
 | Generating a new project's CLAUDE.md — baseline routing plus project-specific facts | `skills/bootstrap-project.md` |
 | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | `skills/cloud-dev-environment.md` |
 | Changing an EXISTING Mendix app — adding a feature, altering a flow, restructuring a module — when it has no BRDs, no architecture doc and no wireframes: the knowledge base comes from the live model (Path D), stages 2–4 run over the changed slice plus its blast radius only, and the Track B regression baseline is the precondition; audit-only stays in existing-app-assurance | `skills/existing-app-change.md` |
+| Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ | `skills/company-brain.md` |
 | Cutover and retrospective — promoting proven patterns back into the toolkit | `skills/close-the-loop.md` |
 | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited | `skills/measured-claims.md` |
 | Any review pass that runs more than once — module-review, coherence, monkey, wiring-sweep: findings accumulate across runs, a per-run report cannot show a trend | `skills/improvement-register.md` |
@@ -740,6 +741,8 @@ git clone https://github.com/MendixMau/mxcli-project-toolkit.git ~/Mendix/mxcli-
 Each project's `CLAUDE.local.md` references `~/Mendix/mxcli-project-toolkit`. Pull updates with `git pull` — **everything referenced (skills, runbook, checkpoints, gate-check) updates instantly for all projects.** The artifacts that were *copied* into a project (intake.md, agent stubs, and — only on a project with no `CLAUDE.local.md` — the baseline-routing table in its `CLAUDE.md`) don't: run `bin/sync-project.sh <project-root>` after a pull — it appends new intake questions, refreshes untouched agent stubs (never completed ones), refreshes the Baseline and situational tables in `CLAUDE.local.md` when one exists, and otherwise flags a stale baseline routing table in `CLAUDE.md` for hand update. It also warns (never fetches) when the toolkit clone itself is off `master` or behind `origin/master`; `MXTK_SYNC_SKIP_CLONE_CHECK=1` skips that one check, for the toolkit's own test suite only — real users leave it unset. Then tell any already-running session to re-read the runbook.
 For a self-contained handoff, add it as a git submodule instead. Per pipeline, run `npm install` inside `pipelines/<x>/pipeline` (node_modules is gitignored).
 
+**Company brain.** A company running several projects keeps its own private tier — own skills, conventions, lint rules, MDL snippets, approved MPKs — in a repo shaped like this one: `bin/init-company-brain.sh <dir>` instantiates `templates/company-brain/`, and `bin/init-project.sh <project> --company <dir>` (or `bin/wire-company-brain.sh`) points a project at it with one on-demand block. Rules and the three-tier split: `skills/company-brain.md`.
+
 ### Baseline routing — every consuming project needs this table
 
 The "When to use which skill" table above is *situational* — load a skill when a specific task calls for it. A few skills apply on **every** MDL-writing session regardless of task, and situational discovery quietly misses them, because nothing mid-task prompts loading them. Every consuming project needs this table somewhere an agent reads it before writing MDL — but "somewhere" is not "copy it into `CLAUDE.md`": a project scaffolded with `bin/init-project.sh` already has it in `CLAUDE.local.md`, refreshed by every `bin/sync-project.sh` run, and `CLAUDE.md` there should carry only a short pointer to it (`skills/bootstrap-project.md` Step 2 has the exact block). Paste the table itself into `CLAUDE.md` only on a project with no `CLAUDE.local.md` convention (a non-Claude harness, or one bootstrapped before `init-project.sh` existed):

ROUTING.md

@@ -52,6 +52,7 @@ picks the row up. That is the whole procedure — there is no second list to rem
 | Generating a new project's CLAUDE.md — baseline routing plus project-specific facts | `skills/bootstrap-project.md` | ba | P | ondemand |
 | Setting up or resuming an mxcli project in a cloud/ephemeral container — the one-time setup order (mxcli download → mxcli init → init-project.sh → sources decision → push) and the commit-and-push loop that survives container reclaim | `skills/cloud-dev-environment.md` | all | P | ondemand |
 | Changing an EXISTING Mendix app — adding a feature, altering a flow, restructuring a module — when it has no BRDs, no architecture doc and no wireframes: the knowledge base comes from the live model (Path D), stages 2–4 run over the changed slice plus its blast radius only, and the Track B regression baseline is the precondition; audit-only stays in existing-app-assurance | `skills/existing-app-change.md` | ba,architect | P,0 | ondemand |
+| Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ | `skills/company-brain.md` | all | - | ondemand |
 | Cutover and retrospective — promoting proven patterns back into the toolkit | `skills/close-the-loop.md` | all | 7 | ondemand |
 | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited | `skills/measured-claims.md` | all | - | ondemand |
 | Any review pass that runs more than once — module-review, coherence, monkey, wiring-sweep: findings accumulate across runs, a per-run report cannot show a trend | `skills/improvement-register.md` | mdl,gate,test,review | 5,6 | ondemand |

agents/architect-agent.md

@@ -65,6 +65,7 @@ You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you ne
 | `skills/coverage-ledger.md` | Building the Stage 4 coverage ledger — every requirement either claimed by a build-plan row or catalogued with a reason, never invisible |
 | `bin/coverage-check.sh` | Checking a coverage ledger against its BRD — every scalar leaf CLAIMED, LEDGERED, UNCLAIMED, PHANTOM or DOUBLE-CLAIMED, so coverage is measured rather than remembered |
 | `skills/mendix-agents.md` | Building a Mendix AI agent — the agent is runtime data not a model document, so JSON import, tool microflows, knowledge base chunk loading and the runtime wiring all sit outside MDL, and mxbuild stays green when they are wrong |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/measured-claims.md` | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited |
 | `skills/agent-permission-friction.md` | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing |

agents/ba-agent.md

@@ -80,6 +80,7 @@ You run discovery and the interview gates for {{PROJECT}}. You never touch the `
 | `skills/kb-generation.md` | Extracting Excel/Word/PDF specs into a knowledge base |
 | `skills/brd-generation.md` | Writing or enriching a BRD JSON |
 | `skills/brd-validation.md` | Validating BRDs against the code and document KB |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/measured-claims.md` | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited |
 | `skills/agent-permission-friction.md` | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing |

agents/gate-agent.md

@@ -57,6 +57,7 @@ own bug log before running anything you have not run here before.
 | `project-bin/conformance-check.sh` | Running the ledger rung alone — recompute every stored ledger status against the live model and catch the STALE rows that claim built for something the model no longer has |
 | `project-bin/graph-sweep.sh` | Running the wiring rung alone — a module imported but never reached, an element built but wired to nothing, a boundary crossed; mxbuild and e2e are blind to all three |
 | `project-bin/test-stack-up.sh` | Before any runtime test — brings the stack up unattended and PROVES the thing that answered is this project's app; --check makes it report-only |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/report-schema.md` | Writing or reading docs/report.json — the append-only contract every instrument writes to and every renderer reads; open BEFORE building a new instrument or a second renderer |
 | `skills/measured-claims.md` | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited |

agents/mdl-agent.md

@@ -75,6 +75,7 @@ a rule below names an asset (e.g. "the wireframe", "the brief"), it means the pa
 | `skills/mendix-agents.md` | Building a Mendix AI agent — the agent is runtime data not a model document, so JSON import, tool microflows, knowledge base chunk loading and the runtime wiring all sit outside MDL, and mxbuild stays green when they are wrong |
 | `skills/mendix-agent-ui.md` | Embedding a copilot chat panel — the frame is yours, ConversationalUI owns the conversation; wireframe to tokens to snippet to page placement |
 | `skills/mendix-agent-setup.md` | Standing up a project's GenAI agents in any environment — MxCloud key import, model-to-agent binding, KB indexing and the agent-answers-a-question proof are all UI-only (no MDL/SQL path), driven with Playwright; you need the resource keys handed to you as env vars first |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/measured-claims.md` | Before citing ANY behavioural claim about the harness, the Mendix runtime or a test tool as evidence — a claim not in the register may not be cited |
 | `skills/agent-permission-friction.md` | Any refused, denied or blocked command — BEFORE rewriting a permission rule and before telling the user a tool is blocked. A rule matches the START of the command line, so an allowlisted tool prefixed with cd matches nothing |

agents/review-agent.md

@@ -69,6 +69,7 @@ protects: you have no Write or Edit tool, and you never run `mxcli exec`.
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
 | `skills/learned-skill-ux-audit.md` | UX audit and screenshot-loop discipline |
 | `skills/learned-skill-scope-delta.md` | Tracking scope delta between the BRD and the built state |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/report-schema.md` | Writing or reading docs/report.json — the append-only contract every instrument writes to and every renderer reads; open BEFORE building a new instrument or a second renderer |
 | `skills/harness-architecture.md` | Installing, extending, debugging or porting the verification harness — which part owns what, which parts run standalone, and what a missing part must report |

agents/test-agent.md

@@ -48,6 +48,7 @@ and `"DESCRIBE ..."` reads are always fine, and are how you ground every name yo
 | `skills/fixture-seeding.md` | Establishing the data and identities a journey run needs — BEFORE it runs. Derive and measure with project-bin/fixture-manifest.sh first; interview only the residue, and never seed from inside the harness |
 | `skills/journey-proof.md` | Proving a module's user journey end-to-end — the deep form of step 3 PROVE; use whenever an instrument reports green and you cannot say what would have made it red |
 | `skills/monkey-test.md` | Running the fuzz/crash net on a module whose journeys are already green — and reading the result, which is NOT evidence the module works |
+| `skills/company-brain.md` | Setting up or wiring a COMPANY BRAIN — the private tier between the toolkit and a project for own skills, conventions, lint rules, MDL snippets and approved MPKs; and deciding whether something goes to the toolkit, the company brain or docs/brain/ |
 | `skills/close-the-loop.md` | Cutover and retrospective — promoting proven patterns back into the toolkit |
 | `skills/report-schema.md` | Writing or reading docs/report.json — the append-only contract every instrument writes to and every renderer reads; open BEFORE building a new instrument or a second renderer |
 | `skills/harness-architecture.md` | Installing, extending, debugging or porting the verification harness — which part owns what, which parts run standalone, and what a missing part must report |

bin/check-no-private-citations.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# check-no-private-citations.sh — the public toolkit never cites a private tier.
+#
+#   bin/check-no-private-citations.sh [root]     # exit 1 on any hit
+#
+# Real incident (USI workshop research, 2026-08): five skills cited by this public repo existed
+# only in a private repo, so an engineer following the pointer got nothing. A company brain
+# (templates/company-brain/) may cite the toolkit; the toolkit must never cite a company brain,
+# a personal repo, or any path under a user's home that is not this repo. This is the CI floor
+# for that rule.
+#
+# Matches: a path segment named like a private tier (`personal-toolkit/`, `<x>company-brain<y>/`),
+# or `~/Mendix/<repo>/` where <repo> is not mxcli-project-toolkit. Override or extend with
+# PRIVATE_TIER_REGEX (extended regex). Prose mentions without a path ("a personal-toolkit design
+# note") are credits, not pointers, and do not match.
+#
+# Exempt: CHANGELOG.md (history), contrib/inbox/ (unreviewed by definition; nothing may cite it),
+# process/ and dated bug-log retest/archive records (evidence, not routing), tests/ and evals/ (fixtures plant hits on purpose), templates/ (must
+# name what it forbids), and
+# this script. Everything else tracked (or, outside git, every regular file) is scanned.
+set -u
+ROOT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+cd "$ROOT" || exit 2
+RE="${PRIVATE_TIER_REGEX:-(personal-toolkit/|company-brain/|(~|\\\$HOME|/Users/[^/\` ]+|/home/[^/\` ]+)/Mendix/[A-Za-z0-9_.-]+/)}"
+# The toolkit's own paths are not private tiers: its template directory, and its own clone path.
+ALLOW="${PRIVATE_TIER_ALLOW:-templates/company-brain/|/Mendix/mxcli-project-toolkit/}"
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+  files="$(git ls-files)"
+else
+  files="$(find . -type f -not -path './.git/*' | sed 's|^\./||')"
+fi
+hits=0
+while IFS= read -r f; do
+  [ -f "$f" ] || continue
+  case "$f" in
+    CHANGELOG.md|process/*|bug-logs/*retest*|bug-logs/archive-*|contrib/inbox/*|tests/*|evals/*|templates/*|bin/check-no-private-citations.sh|*.mpk|*.png|*.jpg|*.webp|*.zip|*.pdf) continue ;;
+  esac
+  m="$(grep -nE "$RE" "$f" 2>/dev/null | grep -vE "$ALLOW")" || continue
+  printf '❌ %s\n%s\n' "$f" "$(printf '%s\n' "$m" | sed 's/^/    /')"
+  hits=$((hits+1))
+done <<< "$files"
+if [ "$hits" -gt 0 ]; then
+  echo "check-no-private-citations: $hits file(s) cite a private tier. Reword to the toolkit's own file, or drop the pointer." >&2
+  exit 1
+fi
+echo "check-no-private-citations: clean"