@theglitchking/babel-fish 2.5.0 → 2.6.0

package/.claude/templates/structure/monorepo.toml

@@ -0,0 +1,76 @@
+# Layout: monorepo -- several apps and shared packages in one repo, dev (localhost) -> stg -> prod (cloud).
+#
+# A reference, not a rule. `structure-check.py --bootstrap --layout monorepo` copies it,
+# marks each folder active (exists) or planned (not yet), adds a folder for anything
+# it doesn't cover, and lists the remaining differences in `exceptions` by exact
+# path -- adopting it blocks nothing. The
+# structure-bootstrap skill reads it to suggest purposes and changes.
+mode = "monorepo"
+env_file = "infra/env/.env.example"  # the ONE committed env template (every key, every env and app)
+root_files = [
+  "README.md", "LICENSE", "CHANGELOG.md", "CLAUDE.md", "AGENTS.md",
+  ".gitignore", ".gitattributes", ".editorconfig", ".dockerignore", ".mcp.json",
+  "package.json", "package-lock.json", "*.lock", "tsconfig*.json", "*.config.js", "*.config.ts",
+  "pyproject.toml", "requirements*.txt", "go.mod", "go.sum", "Cargo.toml",
+  "Makefile", "Dockerfile",
+  "pnpm-workspace.yaml", "turbo.json", "nx.json", "lerna.json", "go.work",
+]
+
+[[folder]]
+path = "apps"
+purpose = "One folder per deployable app: apps/<name>/ with its own source, tests, manifest and migrations"
+holds = ["*/**", "README.md"]
+
+[[folder]]
+path = "packages"
+purpose = "Shared libraries: packages/<name>/, imported by apps, never deployed alone"
+holds = ["*/**", "README.md"]
+
+[[folder]]
+path = "tests"
+purpose = "Cross-app tests (end-to-end, contract); unit tests live with each app"
+
+[[folder]]
+path = "scripts"
+purpose = "Repo-wide developer and ops scripts"
+
+[[folder]]
+path = "infra/compose"
+purpose = "Compose files: base.yml shared, dev.yml for localhost, remote.yml for the cloud environments"
+holds = ["*.yml", "*.yaml"]
+
+[[folder]]
+path = "infra/env"
+purpose = "Env config: .env.example is the one template (every key, placeholders) and your local .env sits beside it, gitignored. Stg/prod values come from the secret manager or CI, never from files here; <env>/ holds only non-secret per-env deltas"
+holds = [".env.example", "README.md", "*/**"]
+
+[[folder]]
+path = "infra/deploy"
+purpose = "Cloud deploy config: base/ shared, <env>/ holds only what differs (Terraform, k8s, platform files)"
+
+[[folder]]
+path = ".github"
+purpose = "CI workflows -- one deploy workflow that takes the environment as input"
+
+[[folder]]
+path = ".claude"
+purpose = "Claude Code config: rules, skills, the project map and this manifest"
+
+[[folder]]
+path = ".documentation"
+purpose = "Prose docs (hit-em-with-the-docs)"
+
+[[environment]]
+name = "dev"
+target = "local"
+promotes_to = "stg"
+
+[[environment]]
+name = "stg"
+target = "cloud"
+promotes_to = "prod"
+mirrors = "prod"
+
+[[environment]]
+name = "prod"
+target = "cloud"

package/.claude/templates/structure/multi-repo.toml

@@ -0,0 +1,85 @@
+# Layout: multi-repo -- this repo is one of several. Same flat layout as `single`;
+# [[repo]] entries point at the others. Each of those runs its own babel-fish (map,
+# drift, structure check) -- nothing here reaches into them.
+#
+# Environments: dev (localhost) -> stg -> prod (cloud).
+#
+# A reference, not a rule. `structure-check.py --bootstrap --layout multi-repo` copies it,
+# marks each folder active (exists) or planned (not yet), adds a folder for anything
+# it doesn't cover, and lists the remaining differences in `exceptions` by exact
+# path -- adopting it blocks nothing. The
+# structure-bootstrap skill reads it to suggest purposes and changes.
+mode = "multi-repo"
+env_file = "infra/env/.env.example"  # the ONE committed env template (every key, every env and app)
+root_files = [
+  "README.md", "LICENSE", "CHANGELOG.md", "CLAUDE.md", "AGENTS.md",
+  ".gitignore", ".gitattributes", ".editorconfig", ".dockerignore", ".mcp.json",
+  "package.json", "package-lock.json", "*.lock", "tsconfig*.json", "*.config.js", "*.config.ts",
+  "pyproject.toml", "requirements*.txt", "go.mod", "go.sum", "Cargo.toml",
+  "Makefile", "Dockerfile",
+]
+
+[[folder]]
+path = "src"
+purpose = "Application source"
+
+[[folder]]
+path = "tests"
+purpose = "Tests"
+
+[[folder]]
+path = "scripts"
+purpose = "Developer and ops scripts"
+
+[[folder]]
+path = "migrations"
+purpose = "Database migrations -- one folder, the same path forward in every environment"
+
+[[folder]]
+path = "infra/compose"
+purpose = "Compose files: base.yml shared, dev.yml for localhost, remote.yml for the cloud environments"
+holds = ["*.yml", "*.yaml"]
+
+[[folder]]
+path = "infra/env"
+purpose = "Env config: .env.example is the one template (every key, placeholders) and your local .env sits beside it, gitignored. Stg/prod values come from the secret manager or CI, never from files here; <env>/ holds only non-secret per-env deltas"
+holds = [".env.example", "README.md", "*/**"]
+
+[[folder]]
+path = "infra/deploy"
+purpose = "Cloud deploy config: base/ shared, <env>/ holds only what differs (Terraform, k8s, platform files)"
+
+[[folder]]
+path = ".github"
+purpose = "CI workflows -- one deploy workflow that takes the environment as input"
+
+[[folder]]
+path = ".claude"
+purpose = "Claude Code config: rules, skills, the project map and this manifest"
+
+[[folder]]
+path = ".documentation"
+purpose = "Prose docs (hit-em-with-the-docs)"
+
+[[environment]]
+name = "dev"
+target = "local"
+promotes_to = "stg"
+
+[[environment]]
+name = "stg"
+target = "cloud"
+promotes_to = "prod"
+mirrors = "prod"
+
+[[environment]]
+name = "prod"
+target = "cloud"
+
+# One entry per repo this one works with. `path` is a local checkout (warned if
+# missing), `url` the remote; at least one is required.
+# [[repo]]
+# name = "api"
+# path = "../api"
+# url = "https://github.com/<org>/api"
+# purpose = "Backend API"

package/.claude/templates/structure/single.toml

@@ -0,0 +1,73 @@
+# Layout: single -- one project, flat layout, dev (localhost) -> stg -> prod (cloud).
+#
+# A reference, not a rule. `structure-check.py --bootstrap --layout single` copies it,
+# marks each folder active (exists) or planned (not yet), adds a folder for anything
+# it doesn't cover, and lists the remaining differences in `exceptions` by exact
+# path -- adopting it blocks nothing. The
+# structure-bootstrap skill reads it to suggest purposes and changes.
+mode = "single"
+env_file = "infra/env/.env.example"  # the ONE committed env template (every key, every env and app)
+root_files = [
+  "README.md", "LICENSE", "CHANGELOG.md", "CLAUDE.md", "AGENTS.md",
+  ".gitignore", ".gitattributes", ".editorconfig", ".dockerignore", ".mcp.json",
+  "package.json", "package-lock.json", "*.lock", "tsconfig*.json", "*.config.js", "*.config.ts",
+  "pyproject.toml", "requirements*.txt", "go.mod", "go.sum", "Cargo.toml",
+  "Makefile", "Dockerfile",
+]
+
+[[folder]]
+path = "src"
+purpose = "Application source"
+
+[[folder]]
+path = "tests"
+purpose = "Tests"
+
+[[folder]]
+path = "scripts"
+purpose = "Developer and ops scripts"
+
+[[folder]]
+path = "migrations"
+purpose = "Database migrations -- one folder, the same path forward in every environment"
+
+[[folder]]
+path = "infra/compose"
+purpose = "Compose files: base.yml shared, dev.yml for localhost, remote.yml for the cloud environments"
+holds = ["*.yml", "*.yaml"]
+
+[[folder]]
+path = "infra/env"
+purpose = "Env config: .env.example is the one template (every key, placeholders) and your local .env sits beside it, gitignored. Stg/prod values come from the secret manager or CI, never from files here; <env>/ holds only non-secret per-env deltas"
+holds = [".env.example", "README.md", "*/**"]
+
+[[folder]]
+path = "infra/deploy"
+purpose = "Cloud deploy config: base/ shared, <env>/ holds only what differs (Terraform, k8s, platform files)"
+
+[[folder]]
+path = ".github"
+purpose = "CI workflows -- one deploy workflow that takes the environment as input"
+
+[[folder]]
+path = ".claude"
+purpose = "Claude Code config: rules, skills, the project map and this manifest"
+
+[[folder]]
+path = ".documentation"
+purpose = "Prose docs (hit-em-with-the-docs)"
+
+[[environment]]
+name = "dev"
+target = "local"
+promotes_to = "stg"
+
+[[environment]]
+name = "stg"
+target = "cloud"
+promotes_to = "prod"
+mirrors = "prod"
+
+[[environment]]
+name = "prod"
+target = "cloud"

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
-    "version": "2.5.0"
+    "version": "2.6.0"
   },
   "plugins": [
     {
       "name": "babel-fish",
       "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-      "version": "2.5.0",
+      "version": "2.6.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-fish",
   "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/.githooks/pre-commit

@@ -38,3 +38,21 @@ if git diff --cached --name-only 2>/dev/null | grep -qE '^(\.claude/)?CLAUDE(\.l
     fi
 fi
 # ── End Context Check ────────────────────────────────────────────────────────
+
+# ── Structure Check: files land where .claude/structure.toml says (#22) ──────
+# Opt-in: runs only once the repo has a manifest. On Python < 3.11 it warns and passes.
+if [ -f ".claude/structure.toml" ]; then
+    CHECK_SCRIPT=".claude/project-map/structure-check.py"
+    if [ -f "$CHECK_SCRIPT" ]; then
+        PYTHON=""
+        if [ -f ".venv/bin/python3" ]; then PYTHON=".venv/bin/python3"
+        elif command -v python3 &>/dev/null; then PYTHON="python3"
+        elif command -v python &>/dev/null; then PYTHON="python"
+        fi
+        if [ -n "$PYTHON" ] && ! $PYTHON "$CHECK_SCRIPT" --staged; then
+            echo "[structure-check] Commit blocked. Each FAIL above has a fix: line -- or change .claude/structure.toml if the structure should change." >&2
+            exit 1
+        fi
+    fi
+fi
+# ── End Structure Check ──────────────────────────────────────────────────────

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.6.0] - 2026-09-30
+
+### Added
+
+- **`structure-check.py`: files land where the repo says they go**
+  ([#22](https://github.com/the-glitch-kingdom/babel-fish/issues/22)). The project map
+  describes where things *are*. The new, opt-in `.claude/structure.toml` says where
+  they *should go*, and the check enforces it at commit time and in CI.
+
+  **Manifest.** Each approved folder declares a `purpose`, optional `holds` globs and
+  a lifecycle status: `planned` (approved, may be created), `active`, or `deprecated`
+  (new files blocked while existing ones move out). The manifest also lists
+  `root_files`, an `exceptions` baseline so adopting the check blocks nothing (only
+  *new* violations fail), and `[[repo]]` pointers for multi-repo setups. Each pointed-to
+  repo runs its own babel-fish; nothing crosses repos. The mode is `single`,
+  `monorepo` or `multi-repo`.
+
+  **Environment lifecycle.** Declared `[[environment]]`s (`target` local or cloud,
+  `promotes_to`, `mirrors`) enforce dev → stg → prod: undeclared environment folders
+  fail, stg must hold the same files as prod, local-only files (Compose, seeds, certs)
+  stay out of cloud environments and deploy config stays out of local ones,
+  environment folders hold deltas only (an identical copy of a shared file fails),
+  migrations are never per-environment, and per-app environment folders outside
+  `env_roots` fail. A tracked `.env` fails in every mode. Only an exact-path
+  exception, added by hand for a committed test fixture, can allow one.
+
+  **One `.env`, as close as the structure allows.** A single committed template
+  (`env_file`, default `infra/env/.env.example`) holds every key for every
+  environment and app; the one real `.env` sits beside it, gitignored; stg/prod values
+  come from the secret manager. Any other template (per-app, per-environment,
+  `.env.sample`, `example.env`) fails with "merge its keys into env_file". A real
+  env file that git would commit fails before it is staged, and scattered local ones
+  warn. Bootstrap keeps an existing single template where it is and puts extra
+  templates in the backlog.
+
+  **Detection and adoption.** `--detect [--json]` reports facts: best-guess mode with
+  reasons, environments seen, top-level folders, sibling repos, and whether the repo is
+  new. `--bootstrap [--layout single|monorepo|multi-repo]` writes a starting manifest
+  and never overwrites an existing one. Uncovered top-level folders become their own
+  entries, leftover violations seed `exceptions` as exact paths, and tracked secrets
+  are never seeded. With
+  no manifest, running the script explains the options and exits 0. Flags for commit
+  and CI: `--staged` and `--since REF`.
+
+  **`structure-bootstrap` skill.** It makes the judgment calls the script can't:
+  folder purposes and `holds` from real contents, which layout fits, planning a new
+  repo from a project description, recipes for adding and retiring folders, apps and
+  environments, and, only on request, for Flow C, or for a new repo, a rules file and
+  a procedure doc.
+
+  The pre-commit hook gets a `Structure Check` block (own marker, so re-running
+  `bash .claude/install.sh` adds it to existing hooks). It runs only when the manifest
+  exists. The installer copies the script and the layouts and never touches
+  `structure.toml`. On Python < 3.11 (no `tomllib`) the check prints a readable warning
+  and passes; the rest of babel-fish still runs on 3.8. When a manifest exists,
+  `PROJECT_MAP.md` gets a one-line pointer to it plus the related repos.
+
 ## [2.5.0] - 2026-09-25
 
 ### Added

package/README.md

@@ -242,6 +242,31 @@ python .claude/project-map/context-check.py --budget 80000 --map-style
 
 ---
 
+## Repo Structure Check *(2.6.0+)*
+
+The map shows where things **are**. An opt-in `.claude/structure.toml` says where they **should go**, and `structure-check.py` blocks the commit (and fails CI) when a file lands somewhere else.
+
+- **Folders with a lifecycle:** each approved folder has a purpose, optional `holds` globs, and a status of `planned`, `active` or `deprecated`. A deprecated folder takes no new files while the old ones move out.
+- **dev → stg → prod:** declared environments must stay separate:
+  - stg holds the same files as prod
+  - environment folders hold only what differs
+  - local tooling stays out of the cloud environments, and deploy config out of local ones
+  - migrations are shared across environments
+  - a real `.env` is never committed
+- **One `.env`, not twenty:** a single committed `.env.example` holds every key for every environment and app, and the one real `.env` sits beside it, gitignored. Stray templates, per-app `.env` files and a `.env` that git would commit all get caught.
+- **Modes:** `single`, `monorepo`, or `multi-repo`. In multi-repo, `[[repo]]` entries point at sibling repos, each running its own babel-fish.
+- **Adoption blocks nothing:** `--bootstrap` seeds an `exceptions` baseline from today's tree, so only *new* violations fail.
+
+```bash
+python .claude/project-map/structure-check.py --detect                      # mode, environments, folders
+python .claude/project-map/structure-check.py --bootstrap --layout monorepo # start a manifest (never overwrites)
+python .claude/project-map/structure-check.py --since origin/main           # CI
+```
+
+Or ask Claude to *"set up the repo structure"*. The `structure-bootstrap` skill reads the tree, fills in each folder's purpose, can plan a new repo from a description, and asks only what it can't infer. Needs Python 3.11+ (on older Python it warns and passes). See [repo structure check](./.documentation/standards/repo-structure-check.md) and [changing repo structure](./.documentation/procedures/changing-repo-structure.md).
+
+---
+
 ## File Structure
 
 ```
@@ -251,11 +276,14 @@ python .claude/project-map/context-check.py --budget 80000 --map-style
 │   ├── grader.py                # Quality grader
 │   ├── mine-sessions.py         # Session vocabulary miner
 │   ├── context-check.py         # Budget + pointer check for auto-loaded files
+│   ├── structure-check.py       # Files vs .claude/structure.toml (opt-in)
 │   ├── PROJECT_MAP.md           # TOC + quick routing guide
 │   ├── sections/                # 19 focused section files
 │   ├── reports/                 # Install and iteration reports
 │   ├── checksums.json           # Skip regeneration if unchanged
 │   └── learned-vocabulary.json  # Persisted session aliases
+├── structure.toml               # Your repo's structure manifest (you own it; never overwritten)
+├── templates/structure/         # Layouts: single, monorepo, multi-repo
 ├── rules/
 │   ├── project-vocabulary.md    # Auto-loaded every session
 │   └── operational-runbook.md   # Auto-loaded every session
@@ -263,7 +291,7 @@ python .claude/project-map/context-check.py --budget 80000 --map-style
     └── <project>-developer-skill/
         └── SKILL.md
 .githooks/
-├── pre-commit                   # Regenerates map; runs the context check
+├── pre-commit                   # Regenerates map; runs the context + structure checks
 └── install.sh                   # Register hooks: bash .githooks/install.sh
 ```
 
@@ -284,7 +312,7 @@ python .claude/project-map/context-check.py --budget 80000 --map-style
 ## Requirements
 
 - AI coding assistant (Claude Code, Cursor, or compatible)
-- Python ≥ 3.8 (auto-installed if missing)
+- Python ≥ 3.8 (auto-installed if missing); the structure check needs ≥ 3.11
 - Bash
 - Optional: `pip install pyyaml` for docker-compose YAML parsing (regex fallback included)
 
@@ -298,6 +326,7 @@ python .claude/project-map/context-check.py --budget 80000 --map-style
 | `python .claude/project-map/grader.py` | Grade map quality (0–100%) |
 | `python .claude/project-map/mine-sessions.py` | Mine session vocabulary |
 | `python .claude/project-map/context-check.py` | Check auto-loaded context: budget, pointers |
+| `python .claude/project-map/structure-check.py` | Check files against `.claude/structure.toml` (`--detect`, `--bootstrap`) |
 | `bash .githooks/install.sh` | (Re)install git hooks |
 | `bash .claude/install.sh` | Re-run full plugin installer |
 

package/checksums.json

@@ -1,4 +1,4 @@
 {
-  "install_sh": "eb3a15ddeaf969b3b0e609fe6cde7792efd7c60ef2305d8593cb761fe812c1aa",
+  "install_sh": "a60cc1de663517c86ec4f6aa35f4171c2e32f2d0c43001202583039d9b7d847a",
   "note": "SHA256 of .claude/install.sh \u2014 verified by the remote installer before execution"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/babel-fish",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/link-skills.js",
-    "test": "python3 .claude/project-map/test_generate.py && python3 .claude/project-map/test_mine_sessions.py && python3 .claude/project-map/test_grader.py && python3 .claude/project-map/test_context_check.py"
+    "test": "python3 .claude/project-map/test_generate.py && python3 .claude/project-map/test_mine_sessions.py && python3 .claude/project-map/test_grader.py && python3 .claude/project-map/test_context_check.py && python3 .claude/project-map/test_structure_check.py"
   },
   "files": [
     "bin/",
@@ -23,10 +23,12 @@
     ".claude/project-map/grader.py",
     ".claude/project-map/mine-sessions.py",
     ".claude/project-map/context-check.py",
+    ".claude/project-map/structure-check.py",
     ".claude/project-map/test_generate.py",
     ".claude/project-map/test_mine_sessions.py",
     ".claude/project-map/test_grader.py",
     ".claude/project-map/test_context_check.py",
+    ".claude/project-map/test_structure_check.py",
     ".githooks/",
     "skills/",
     "install.sh",

package/scripts/link-skills.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // Postinstall — delegates to @theglitchking/claude-plugin-runtime.
-// babel-fish ships one skill (skills/babel-fish-developer-skill/) which
-// the runtime symlinks into <project>/.claude/skills/ so Claude Code
-// can discover it. Runtime also writes the default update-policy config
+// babel-fish ships two skills (skills/babel-fish-developer-skill/ and
+// skills/structure-bootstrap/) which the runtime symlinks into
+// <project>/.claude/skills/ so Claude Code can discover them. Runtime also writes the default update-policy config
 // and registers the SessionStart hook (with plugin-vs-npm dedup).
 //
 // NOTE: npm install only handles the skill + update policy. To get the