@omega.js/manager 0.1.0

package/claude-plugin/README.md

@@ -0,0 +1,139 @@
+# OMEGA — the Claude plugin
+
+OMEGA's knowledge for Claude sessions, shipped as a Claude Code plugin from the monorepo that holds the code it describes. Install it and any session working on an OMEGA project gets the current conventions, without the knowledge living in any one developer's personal harness.
+
+## Why it lives here
+
+A skill kept anywhere else is a hand-maintained pointer into a repo that moves on its own schedule — nothing makes the two agree, and nothing notices when they stop. A skill that ships beside the code is version-matched by construction, and it is the same commit that changes the framework and the sentence describing it.
+
+## Install
+
+In this monorepo, install is automatic: the committed `.claude/settings.json` registers the repo-root marketplace (`.claude-plugin/marketplace.json`, relative path) and enables `omega@omega` — Claude Code asks one trust question on first open, then the plugin loads every session. For any other checkout, the manual form:
+
+```sh
+claude plugin marketplace add <path-to-this-monorepo-checkout>
+claude plugin install omega@omega
+```
+
+Plugins load at startup, so a new (or restarted) session — or `/reload-plugins` — is what puts a change into effect. Installed plugins are cache copies; live plugin development runs `claude --plugin-dir ./agent-plugins/claude` instead.
+
+A marketplace added from a local path is read in place — nothing is cloned, so living in a monorepo costs a local install nothing. Installing from GitHub is what makes repo size matter, and the marketplace entry switches to the `git-subdir` source for that: a url plus `"path": "agent-plugins/claude"`, which Claude Code fetches with a sparse partial clone rather than pulling the whole monorepo. Make that change when the plugin is first installed from a remote, not before — the relative `./agent-plugins/claude` source is the right one while every install is local.
+
+## Layout
+
+```
+agent-plugins/
+└── claude/
+    ├── .claude-plugin/plugin.json   the manifest
+    ├── .mcp.json                    the one MCP declaration — the @omega.js/mcp-router endpoint
+    ├── README.md                    this file
+    ├── hooks/                       hooks.json, the inject/gate/guard/shape/quality hooks, and lib/ (the shared scope guard, skill map, and gate-marker naming)
+    └── skills/                      the skills, one directory each (see skills/README.md)
+```
+
+`agent-plugins/` is the parent for every coding agent OMEGA ships knowledge to, and `claude/` is the Claude Code one. A second provider gets a sibling directory rather than a rearrangement.
+
+Structure is validated by `scripts/agent-plugins.test.js` at the monorepo root, which runs in `npm test`.
+
+## The inject hook
+
+The plugin carries the mechanism that loads its own skills. `hooks/inject/run.sh` runs on every prompt (`UserPromptSubmit`), reads the project's `package.json` — the working directory's own, else the nearest one up to the git root — and asks the session to invoke the skill for the framework it finds:
+
+| package | skill |
+|---|---|
+| `@omega.js/web` | `omega:web` |
+| `@omega.js/backend` | `omega:backend` |
+| `@omega.js/desktop` | `omega:desktop` |
+| `@omega.js/extension` | `omega:extension` |
+| `@omega.js/manager` | `omega:manager` |
+| `@omega.js/client` | `omega:client` — the project's own `name` only |
+| `omega` (the monorepo root) | `omega:main` — the project's own `name` only |
+
+Every row also matches the manifest's own `name`, which is what covers working inside a `packages/<pkg>` directory in this monorepo. `@omega.js/client` is the exception the other way: the runtime is embedded by web, desktop, and extension, so a dependency on it says nothing about what the session is working on — only being the package asks for its skill.
+
+**At a brand root, the nearest manifest is not the answer.** It carries `@omega.js/manager` alone, so a session at a brand root used to hear about the manager and nothing about the targets it was there to build. The hook now recognizes a brand — a directory carrying `config/omega.json5`, or one whose manifest depends on `@omega.js/manager`, found by walking up to the git root — and reads the level below it: `config/omega.json5`'s `targets` keys AND every `targets/*/package.json` (plus the `functions/package.json` a Firebase backend keeps its framework in). The whole set comes back at once: `omega:main` and `omega:manager` always, plus one `omega:<framework>` per target. A target no framework owns (`type: 'custom'`) and `mobile` (parked) map to nothing.
+
+A brand injection also names the framework map — the brand `AGENTS.md` import line, `node_modules/@omega.js/AGENTS.md` — as required reading BEFORE the first edit, which is what the gate hook below enforces.
+
+Each skill is asked for once per session per SKILL (a marker file under `TMPDIR`, keyed on the session id), so a target that appears mid-session still gets its own line while the skills already asked for stay quiet. The hook fails open — no `package.json`, unparseable JSON, an unreadable config, no `jq`, and it exits silently without touching the prompt. Behavior is covered by the inject cases in `scripts/agent-plugins.test.js`, which run the script directly against fixture projects.
+
+## The gate hook
+
+Injecting a line only SUGGESTS a skill, and a session that skipped the line built a whole `targets/website` app without ever loading `omega:web` — hand-rolled markup, and a documented validator rule filed as a framework bug. So the skills are enforced. `hooks/gate/run.sh` serves two events from one script — the surface question has ONE answer — and refuses a write to a surface whose skill was never invoked:
+
+| Surface written or edited | Gated on |
+|---|---|
+| `<brand>/targets/<t>/**` | that target's framework skill, read from its own `package.json` (a custom target gates on nothing) |
+| `<brand>/config/omega.json5` | `omega:manager` — the file the manage walk reconciles |
+| `<monorepo>/packages/<pkg>/**`, where the manifest IS `@omega.js/<pkg>` | that package's skill: `omega:web`, `omega:backend`, `omega:desktop`, `omega:extension`, `omega:client`, `omega:manager` |
+| a WEB theme surface, on top of the row above: the packaged `themes/**`, a website target's `themes/**` or `src/themes/**`, its `src/_sections/**` and `src/_components/**` (one override lane), and its `src/assets/css/main.scss` | `omega:theme` IN ADDITION to that surface's own skill — the cascade has its own contract, and it is a web mechanism, so a `themes/` dir in a backend target is not one |
+
+A surface can therefore answer with MORE than one skill, and the gate refuses until EVERY one of them has been invoked — a half-loaded theme edit is refused naming only what is still missing. The inject hook wires none of this: it answers "what does this PROJECT run?" from manifest deps and config target keys, never from a path, so a skill that fires on a surface rather than a package has nothing to add there.
+
+Everything else is free: docs, scripts, the plugin's own files, a brand's root files, a `packages/` directory in somebody else's repo, and every internal package with no skill (`devkit`, `config`, `account`, `analytics`, `monitoring`, `template-kit`, `mcp-router`). Read-only tools are never in scope — the matcher is `Write|Edit`, so reading the code before loading the skill is exactly right.
+
+On `PostToolUse` (matcher `Skill`) the hook records every skill the session invoked, in either spelling — the namespaced `omega:web` or the bare `web` the plugin namespaces. On `PreToolUse` (`Write|Edit`) an unrecorded surface exits 2 with the skill to invoke, so the model is told what to do rather than what it did wrong. Markers live under `TMPDIR/omega-gate`, keyed on the session id.
+
+**Two lanes record the read, and only two.** In the main chat the agent has a Skill tool, so invoking `omega:web` records itself and nothing else is needed. An agent with NO Skill tool (the workkit worker class writes its files through Bash, which a `Write|Edit` matcher never sees) reads the guide its brief names, then runs the ONE sanctioned command: `hooks/gate/mark.sh omega:web` (either spelling the Skill event takes, `omega:web` or bare `web`), which writes the same marker through the same lib (`hooks/lib/omega-gate.sh`) and prints the path it wrote. The script lives at `agent-plugins/claude/hooks/gate/mark.sh` in this monorepo and at `node_modules/@omega.js/manager/claude-plugin/hooks/gate/mark.sh` in a brand on a published install. It takes the session id from `--session <id>` when given (explicit beats ambient), else from `$CLAUDE_SESSION_ID`, else `$CLAUDE_CODE_SESSION_ID`; with none it exits 1 with its usage. Writing a marker by hand, or running `mark.sh` before reading the guide, is a process breach rather than a third lane: the gate is a reading contract, not a lock to pick, and the verifier checks that the worker's report names the guide it read. The gate itself stays a MAIN-CHAT guard on purpose: it does not try to match the paths a heredoc, `sed`, or a python one-liner targets, because best-effort path parsing misses more than it catches ([#760](https://github.com/Omega-JS-Stack/omega/issues/760)).
+
+The gate and the inject hook read ONE table: `hooks/lib/omega-skills.sh`, which owns the framework → skill map, the brand walk, the JSON5 target-key scan, and the surface lookup — so the hook that ASKS for a skill and the hook that REFUSES an edit without it agree on the map itself. They can still ask different questions of it: inject reads the config's target keys too, while the gate resolves a target from its own manifest alone, so a target declared in `omega.json5` before its directory exists is asked for and not gated. That is fail-open by design — the gate refuses only what it can positively identify. Fail-open throughout: no `jq`, an unreadable manifest or config, an unusable marker directory, and the gate lets the write through. Covered by the gate cases in `scripts/agent-plugins.test.js`.
+
+## The guard hook
+
+The gate makes a session READ the framework docs; the guard makes it act on them. `hooks/guard/run.sh` runs on `PreToolUse` (`Write|Edit`) beside the gate and refuses an edit to a framework-owned file inside a CONSUMER BRAND — the upstream-first rule as a mechanism, because "a framework hole gets a framework issue, never a consumer patch" had to be restated three times in one migration session before the hand-written rules and templates stopped landing ([#452](https://github.com/Omega-JS-Stack/omega/issues/452)). Two classes:
+
+| Class | What it catches | Escape |
+|---|---|---|
+| 1. Generated or vendored | any path under `node_modules/`, any `dist/` tree, a file whose first 20 lines say `GENERATED FILE` + `DO NOT EDIT` or `Generated by @omega.js/`, and `database.rules.json` (the OMEGA-managed rules block) | none — the message names the real source to edit instead (the config, the build source, the brand's own `firestore.rules`) |
+| 2. Shadow copies | a brand file whose path mirrors a file the installed framework ships through its OVERRIDE LAYER | `omega:consumer-override: <reason>` in the file's first 5 lines, in any comment syntax (`//`, `#`, `<!--`, `{#`, `/*`), or `OMEGA_CONSUMER_OVERRIDE=1` for the session |
+
+The shadow map is read from the LIVE install (`<brand>/node_modules/@omega.js/<framework>/`), never a hardcoded list, so the knowledge matches the version the brand actually runs. ONE table in the hook holds the lookup roots — `<framework>|<consumer prefix, relative to the target root>|<framework root>`, one row per real override-layer root:
+
+| Framework | Consumer prefix | Framework roots |
+|---|---|---|
+| `web` | `src/_layouts/` | `core/_layouts/`, `themes/*/_layouts/` |
+| `web` | `src/_includes/` | `core/_includes/`, `themes/*/_includes/` |
+| `web` | `src/_sections/` | `themes/*/_sections/` |
+| `web` | `src/_components/` | `themes/*/_components/` |
+| `web` | `src/assets/css/` | `core/css/`, `themes/*/css/` |
+| `backend` | `src/routes/` | `src/manager/routes/` |
+| `backend` | `src/schemas/` | `src/manager/schemas/` |
+| `backend` | (the target root) | `templates/` |
+
+The web rows mirror `packages/web/src/overrides.js` `overrideLanes()` (sections, includes, css) plus the engine's layered `_layouts`: the MECHANISM lanes, where first-layer-wins resolution means a consumer file genuinely takes the framework's place. Sections sit in the theme layers only, because core ships none. The backend rows are the two lanes that really replace a framework file BY NAME — `packages/backend/src/manager/index.js` resolves a consumer route or schema of the same name and method over the framework's — plus the framework half of the rules that ships in `templates/`.
+
+**Pages are never guarded.** `src/pages/` is CONTENT: the designed place for a brand to write its own homepage, about page and pricing page, whether or not the framework ships a default of that name. There is no `defaults/` row and no page row. **There is no js row either**, because page and layout modules are a UNION ([#624](https://github.com/Omega-JS-Stack/omega/issues/624) — every layer's file runs, in layer order) rather than a shadow, so a brand's `src/assets/js/pages/blog.js` replaces nothing.
+
+Two exemption sets, both by name and both traceable to a document:
+
+- **The consumer's own entry files**, which the docs hand to the brand outright: `src/assets/css/main.scss` ([docs/shared/theming.md](../../docs/shared/theming.md) § Consumer customization, tier 1), plus `src/assets/js/main.js` and `src/assets/js/first-paint.js` ([docs/web/index.md](../../docs/web/index.md) — the one REPLACE-with-extend lane, where a consumer file reaches the framework's through `omega:main`). Owning one of those IS the documented recipe, so the guard never asks about it.
+- **The backend seeds** the target checks (`omega test`) write once and the brand owns from then on, each healed by a check in `@omega.js/backend`'s `src/cli/commands/setup-tests/`: `firestore.rules`, `storage.rules`, `firebase.json`, `firestore.indexes.json`, `remoteconfig.template.json`, `public/`, `config/`, and `storage-lifecycle-*.json`.
+
+**Desktop and extension have no rows at all**, and that is a finding rather than an omission: neither framework ships an override layer. Their `src/defaults/` tree is scaffolded ONCE and the brand owns every file in it afterwards — `src/main.js`, `gulpfile.js`, `hooks/build/pre.js` are yours by design — so there is nothing there for a brand file to shadow.
+
+`omega customize` closes the loop from the other side: materializing a file writes the `omega:consumer-override:` marker into its own provenance header (`packages/web/src/overrides.js` `provenanceHeader()`), so the sanctioned way to take a copy produces a file the guard already accepts.
+
+The monorepo itself is exempt — `packages/` is the framework's own source and `brands/` are the crew's fixtures — found by walking to the git root for a manifest named `omega` beside a `packages/` directory, which is what keeps a brand fixture from answering first. Everything else fails open: no `jq`, no brand root, no framework in the target's manifest, no install to read, and the write goes through. Covered by the guard cases in `scripts/agent-plugins.test.js`.
+
+## The quality hook
+
+The four quality skills do not wait to be remembered. `hooks/quality/run.sh` serves two events from one script — so the surface table has one home — and fires them off the files a session actually edits:
+
+| Surface written or edited | Skills asked for |
+|---|---|
+| a page (`*/pages/*.html`, `*/pages/*.md`), a layout, a `.liquid` template | `omega:seo`, `omega:accessibility` |
+| the core head/foot chrome | `omega:seo`, `omega:accessibility` |
+| an include, section, or component partial; page/core JS | `omega:accessibility` |
+| `.scss` / `.css` | `omega:accessibility`, `omega:brandcheck` |
+| `omega.json5`, section data JSON, a section schema | `omega:brandcheck` |
+| a web flow page or auth module (`*/core/js/pages/*`, `*/core/js/libs/auth/*`) | `omega:analytics` (plus `omega:accessibility` from the core-JS row) |
+| a backend payment route, payments-webhook or auth event | `omega:analytics` |
+| the analytics package itself (`*/packages/analytics/*`) | `omega:analytics` |
+
+On `PostToolUse` (Write|Edit) a match names its skills once per session per skill and records the file. On `Stop` the recorded list comes back as a block: the surfaces edited this session, the checklists they owe, and a refusal to sign off on an unreviewed pass. The block runs once per batch of edits (the list clears, so a later edit re-arms it) and never inside its own turn (`stop_hook_active`). Same scope guard as the shape hook, literally: both source `hooks/lib/omega-scope.sh`, which walks up from the edited file to the nearest `package.json` (stopping at the git root) and answers whether that project is or depends on `@omega.js/*`. The inject hook asks a different question — a project from a cwd, with its `functions/` manifest joined in — and keeps its own walk. Fail-open throughout. Covered by the quality cases in `scripts/agent-plugins.test.js`.
+
+## What is here, and what is not built yet
+
+Thirteen skills — `main` (the hub: the package roster, the docs topology, the brand map, where project state lives), one router per package a session works in (`web`, `backend`, `desktop`, `extension`, `client`, `manager`), `browser` (driving the MCP router's Chrome upstreams), the four quality checklists (`seo`, `accessibility`, `brandcheck`, `analytics`) the quality hook fires on the surfaces they own, and `theme` (the cascade's own checklist), which the GATE fires on the theme surfaces in the table above rather than the quality hook. Each one names where the knowledge lives, in the monorepo and in a consumer project, and carries only the handful of rules a session needs before it knows which document to open. One thing is still open.
+
+**The staleness mechanism.** This is the point of the move, not a bonus. Whatever ships needs something that fails when a skill names an export, a path, a config key, or a CLI command the code no longer has. A test in this repo is the strongest form; a generated section is next; a review trigger tied to a release is the floor. A plugin that goes stale quietly has only relocated the problem.

package/claude-plugin/hooks/gate/mark.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# omega:gate mark — the ONE sanctioned way for an agent with NO Skill tool (the
+# worker class writes its files through Bash) to record that it read the guide
+# a skill routes to. It writes exactly the marker the hook's PostToolUse half
+# writes, through the same lib, so the two lanes cannot drift.
+# The main chat never needs this: invoking the skill records itself.
+# Writing a marker by hand, or running this before reading the guide, is a
+# process breach — the gate is a reading contract, not a lock to pick.
+#
+# Usage: mark.sh <skill> [--session <id>]
+#   The session id is --session when given (explicit beats ambient), else
+#   $CLAUDE_SESSION_ID, else $CLAUDE_CODE_SESSION_ID. The skill takes either
+#   spelling the Skill event takes (omega:web or bare web). Prints the marker
+#   path it wrote.
+
+set -euo pipefail
+
+usage() {
+  echo "usage: mark.sh <skill> [--session <id>]   (e.g. mark.sh omega:web)" >&2
+  exit 1
+}
+
+skill=""
+session="${CLAUDE_SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-}}"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --session)
+      [ $# -ge 2 ] || usage
+      session="$2"
+      shift 2
+      ;;
+    -*) usage ;;
+    *)
+      [ -z "$skill" ] || usage
+      skill="$1"
+      shift
+      ;;
+  esac
+done
+
+[ -n "$skill" ] || usage
+[ -n "$session" ] || usage
+
+# The PostToolUse half records a bare name as its namespaced form; the same
+# spelling has to unlock the same surface here.
+case "$skill" in
+  omega:*) ;;
+  *) skill="omega:$skill" ;;
+esac
+
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-gate.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../lib/omega-gate.sh"
+
+marker=$(omega_gate_marker "$session" "$skill")
+mkdir -p "$(omega_gate_state_dir)"
+: > "$marker"
+echo "$marker"

package/claude-plugin/hooks/gate/run.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# omega:gate — PreToolUse (Write|Edit) + PostToolUse (Skill) hook
+# The enforcement half of the inject hook: injecting a line only SUGGESTS the
+# skill, and a session that skipped the line built a whole website target
+# without ever reading the docs. So the surfaces a skill owns are refused until
+# that skill was actually invoked — a target's tree, a brand's config/omega.json5,
+# and a monorepo package that has a skill. Read-only tools are never in scope
+# (the matcher is Write|Edit), and every other path stays free.
+# One script for both events so the surface question has ONE answer; the event
+# comes off hook_event_name. Fails open on anything unexpected.
+
+set -euo pipefail
+
+input=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+event=$(jq -r '.hook_event_name // ""' <<<"$input" 2>/dev/null || true)
+session_id=$(jq -r '.session_id // ""' <<<"$input" 2>/dev/null || true)
+
+# The marker naming is shared with mark.sh, the sanctioned command for an agent
+# with no Skill tool: one lib, so the two writers cannot drift apart.
+gate_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-gate.sh"
+[ -r "$gate_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-gate.sh
+. "$gate_lib"
+
+state_dir=$(omega_gate_state_dir)
+
+marker_for() {
+  omega_gate_marker "$session_id" "$1"
+}
+
+# --- PostToolUse (Skill): the record --------------------------------------
+# The Skill tool's input names the skill it ran; the spelling is the tool's
+# business, so both the namespaced form (omega:web) and the bare skill name
+# (web, which the plugin namespaces) count as the same invocation.
+if [ "$event" = "PostToolUse" ]; then
+  mkdir -p "$state_dir" 2>/dev/null || true
+  values=$(jq -r '[.tool_input // {} | .. | strings] | .[]' <<<"$input" 2>/dev/null || true)
+
+  # The brace group is what makes the failure silent: redirections apply left to
+  # right, so a bare `: > file 2>/dev/null` still prints its own failure.
+  while read -r skill; do
+    [ -n "$skill" ] || continue
+    { : > "$(marker_for "$skill")"; } 2>/dev/null || true
+  done < <(grep -oE 'omega:[a-z][a-z-]*' <<<"$values" 2>/dev/null || true)
+
+  while read -r name; do
+    [ -n "$name" ] || continue
+    { : > "$(marker_for "omega:$name")"; } 2>/dev/null || true
+  done < <(grep -xE '[a-z][a-z-]*' <<<"$values" 2>/dev/null || true)
+
+  exit 0
+fi
+
+# --- PreToolUse (Write|Edit): the refusal ---------------------------------
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input" 2>/dev/null || true)
+[ -n "$file_path" ] || exit 0
+
+skills_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-skills.sh"
+[ -r "$skills_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-skills.sh
+. "$skills_lib"
+
+# A surface can answer with MORE than one skill — a theme surface owns its
+# framework's skill and omega:theme both — so the answer is read line by line
+# and every skill has to have been invoked before the write goes through.
+skills=$(omega_skill_for_file "$file_path")
+[ -n "$skills" ] || exit 0
+
+# No usable state dir means the record half could never have written a marker,
+# so every write would refuse forever. Fail open instead of deadlocking.
+mkdir -p "$state_dir" 2>/dev/null || true
+{ [ -d "$state_dir" ] && [ -w "$state_dir" ]; } || exit 0
+
+missing=()
+while read -r skill; do
+  [ -n "$skill" ] || continue
+  [ -f "$(marker_for "$skill")" ] && continue
+  missing+=("$skill")
+done <<<"$skills"
+
+[ "${#missing[@]}" -gt 0 ] || exit 0
+
+skill=$(printf ', %s' "${missing[@]}")
+skill="${skill:2}"
+
+cat >&2 <<EOF
+omega:gate — $skill has not been loaded, and owns this surface: $file_path
+Invoke $skill via the Skill tool, read the framework map it routes to
+(the brand's AGENTS.md import line, node_modules/@omega.js/AGENTS.md), and
+then make this edit. The framework has conventions for this surface — pages,
+sections, config keys, routes — and hand-rolling it is the failure this gate
+exists to stop. Reading tools are free; this refusal only covers writes.
+EOF
+exit 2

package/claude-plugin/hooks/guard/run.sh

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# omega:guard — PreToolUse (Write|Edit) hook
+# The upstream-first boundary ([#452](https://github.com/Omega-JS-Stack/omega/issues/452)):
+# inside a CONSUMER BRAND, an edit to a framework-owned file is refused, because
+# a framework hole filled with a brand patch is a hole every later brand digs
+# again. Two classes, treated differently:
+#   1. generated or vendored (node_modules, dist, a generated header, the
+#      OMEGA-managed database.rules.json) — hard refusal, no escape hatch; the
+#      message names the real source to edit.
+#   2. shadow copies — a brand file whose path mirrors a file the installed
+#      framework ships through its OVERRIDE LAYER, read from the live install.
+#      Refused with the upstream-first message and two exits: the in-file
+#      `omega:consumer-override:` marker, or OMEGA_CONSUMER_OVERRIDE=1.
+# The monorepo itself is exempt — packages/ is the framework's source and
+# brands/ are the crew's own fixtures. Fails open on anything unexpected.
+
+set -euo pipefail
+
+input=$(cat)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+file_path=$(jq -r '.tool_input.file_path // ""' <<<"$input" 2>/dev/null || true)
+[ -n "$file_path" ] || exit 0
+# Only a Write carries content — which is the only thing a brand-new shadow
+# path can be judged on, since there is no file to read the marker out of yet.
+content=$(jq -r '.tool_input.content // ""' <<<"$input" 2>/dev/null || true)
+
+skills_lib="$(dirname "${BASH_SOURCE[0]}")/../lib/omega-skills.sh"
+[ -r "$skills_lib" ] || exit 0
+# shellcheck source-path=SCRIPTDIR source=../lib/omega-skills.sh
+. "$skills_lib"
+
+# --- scope: a consumer brand, and never this monorepo ----------------------
+# The monorepo walk runs to the git root on its own, because a brand FIXTURE
+# under brands/ answers the brand walk long before the monorepo root is reached.
+in_monorepo() {
+  local dir="$1"
+  # `dirname` bottoms out at "." for a relative path and stays there forever,
+  # so an unanchored walk never terminates. Nothing to resolve, fail open.
+  case "$dir" in /*) ;; *) return 1 ;; esac
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ -f "$dir/package.json" ] && [ -d "$dir/packages" ] \
+      && [ "$(jq -r '.name // ""' "$dir/package.json" 2>/dev/null || true)" = "omega" ]; then
+      return 0
+    fi
+    [ -e "$dir/.git" ] && return 1
+    dir=$(dirname "$dir")
+  done
+  return 1
+}
+
+in_monorepo "$(dirname "$file_path")" && exit 0
+
+brand=$(omega_brand_root "$(dirname "$file_path")")
+[ -n "$brand" ] || exit 0
+[ -f "$brand/package.json" ] || [ -f "$brand/config/omega.json5" ] || exit 0
+
+rel="${file_path#"$brand"/}"
+
+refuse() {
+  cat >&2
+  exit 2
+}
+
+# --- class 1: generated or vendored, no escape hatch -----------------------
+case "$file_path" in
+  */node_modules/*)
+    refuse <<EOF
+omega:guard — $rel is inside node_modules (an installed @omega.js package).
+A dependency bug is fixed UPSTREAM: change it in the Omega monorepo and re-link
+(\`omega i local\`), or file an issue on Omega-JS-Stack/omega. Patching an
+install in place is erased by the next npm install and ships to nobody.
+EOF
+    ;;
+esac
+
+case "$rel" in
+  dist/*|*/dist/*)
+    refuse <<EOF
+omega:guard — $rel is build output (a dist/ tree).
+Edit the SOURCE it is built from and re-run the target's build (\`npx omega build\`).
+A hand edit to dist/ is gone the next time the verb runs.
+EOF
+    ;;
+esac
+
+if [ "$(basename "$file_path")" = "database.rules.json" ]; then
+  refuse <<EOF
+omega:guard — $rel carries the OMEGA-managed realtime-database rules block.
+That block is generated: edit config/omega.json5 for what it reflects, and let
+the target checks rewrite the file (\`npx omega test\` in the backend target).
+The brand's OWN security rules source is firestore.rules, which is yours.
+EOF
+fi
+
+# The header a framework writer stamps on a generated artifact. Read off the
+# file on disk — the stamp is the artifact's own claim about itself.
+if [ -f "$file_path" ]; then
+  header=$(head -n 20 "$file_path" 2>/dev/null || true)
+  if grep -q 'Generated by @omega\.js/' <<<"$header" \
+    || { grep -qi 'GENERATED FILE' <<<"$header" && grep -qi 'DO NOT EDIT' <<<"$header"; }; then
+    refuse <<EOF
+omega:guard — $rel says in its own header that it is generated.
+Edit the source it is rendered from — config/omega.json5, or the framework
+template behind it — and re-run the verb that wrote it. Every edit here is
+overwritten on the next build.
+EOF
+  fi
+fi
+
+# --- class 2: shadow copies of the framework's override layer --------------
+# The target the file belongs to, and the framework that owns that target. A
+# brand with no targets/ directory (a single-target repo) is its own target.
+target_root="$brand"
+case "$file_path" in
+  "$brand"/targets/*/*)
+    rest="${file_path#"$brand"/targets/}"
+    target_root="$brand/targets/${rest%%/*}"
+    ;;
+esac
+
+framework=""
+for manifest in "$target_root/package.json" "$target_root/functions/package.json"; do
+  [ -f "$manifest" ] || continue
+  while read -r dep; do
+    case "$dep" in
+      @omega.js/web|@omega.js/backend|@omega.js/desktop|@omega.js/extension)
+        framework="${dep#@omega.js/}"
+        break
+        ;;
+    esac
+  done < <(omega_manifest_deps "$manifest")
+  [ -n "$framework" ] && break
+done
+[ -n "$framework" ] || exit 0
+
+# Read from the LIVE install, never a hardcoded list — the knowledge has to
+# match the version this brand actually runs.
+install=""
+for candidate in "$target_root/node_modules/@omega.js/$framework" "$brand/node_modules/@omega.js/$framework"; do
+  if [ -d "$candidate" ]; then
+    install="$candidate"
+    break
+  fi
+done
+[ -n "$install" ] || exit 0
+
+rel_target="${file_path#"$target_root"/}"
+
+# THE lookup table: `<framework>|<consumer prefix, relative to the target
+# root>|<framework root, glob allowed>`. A brand path under the prefix is
+# stripped of it and looked up under the framework root; a hit means the brand
+# file SHADOWS that framework file. ONE row per real override-layer root.
+#   web      the MECHANISM lanes, mirroring src/overrides.js overrideLanes()
+#            (sections, includes, css) plus the engine's layered _layouts:
+#            first-layer-wins, consumer src/ → active theme → base → core.
+#            Sections live in the theme layers only (core ships none), and the
+#            css lane is the one sass resolves by layer.
+#            NOT here, on purpose: src/pages/ is CONTENT — the designed place
+#            for a brand's own copy, so a page is never guarded — and the js
+#            lane has no row at all, because page and layout modules are a
+#            UNION ([#624](https://github.com/Omega-JS-Stack/omega/issues/624),
+#            every layer's file runs) rather than a shadow.
+#   backend  the two lanes that really replace a framework file BY NAME
+#            (src/manager/index.js: a consumer route or schema of the same name
+#            and method replaces the framework's), plus the framework half of
+#            the rules that ships in templates/.
+# desktop and extension ship NO override layer: their src/defaults/ tree is
+# scaffolded once and the brand owns every file in it afterwards, so there is
+# nothing there to shadow.
+SHADOW_ROOTS="
+web|src/_layouts/|core/_layouts/
+web|src/_layouts/|themes/*/_layouts/
+web|src/_includes/|core/_includes/
+web|src/_includes/|themes/*/_includes/
+web|src/_sections/|themes/*/_sections/
+web|src/_components/|themes/*/_components/
+web|src/assets/css/|core/css/
+web|src/assets/css/|themes/*/css/
+backend|src/routes/|src/manager/routes/
+backend|src/schemas/|src/manager/schemas/
+backend||templates/
+"
+
+# The files the DOCS name as the consumer's own entry, and the seeds a brand
+# owns once the target checks have written them. Exempt by name, never by guesswork:
+#   web      main.scss is theming.md tier 1 and main.js/first-paint.js are the
+#            same REPLACE-with-extend lane in docs/web/index.md — a consumer
+#            file there reaches the framework's through `omega:main`, which is
+#            the documented way to own it.
+#   backend  every seed in templates/ the target checks write once and never again
+#            (src/cli/commands/setup-tests/ in @omega.js/backend heals each).
+case "$framework/$rel_target" in
+  web/src/assets/css/main.scss|web/src/assets/js/main.js|web/src/assets/js/first-paint.js)
+    exit 0
+    ;;
+  backend/firestore.rules|backend/storage.rules|backend/firebase.json|backend/firestore.indexes.json|backend/remoteconfig.template.json|backend/public/*|backend/config/*|backend/storage-lifecycle-*.json)
+    exit 0
+    ;;
+esac
+
+shadow=""
+while IFS='|' read -r fw prefix root; do
+  [ -n "$fw" ] || continue
+  [ "$fw" = "$framework" ] || continue
+
+  sub="$rel_target"
+  if [ -n "$prefix" ]; then
+    case "$sub" in
+      "$prefix"*) sub="${sub#"$prefix"}" ;;
+      *) continue ;;
+    esac
+  fi
+  [ -n "$sub" ] || continue
+
+  # $root is deliberately unquoted so a themes/*/ row expands to every theme.
+  for candidate in "$install"/$root"$sub"; do
+    if [ -f "$candidate" ]; then
+      shadow="${candidate#"$install"/}"
+      break
+    fi
+  done
+  if [ -n "$shadow" ]; then break; fi
+done <<EOF
+$SHADOW_ROOTS
+EOF
+
+[ -n "$shadow" ] || exit 0
+
+# The exits. The env flag covers a whole session; the marker covers one file
+# forever, and lives in the first five lines in whatever comment syntax the
+# file speaks (//, #, <!--, {#, /*).
+[ "${OMEGA_CONSUMER_OVERRIDE:-}" = "1" ] && exit 0
+
+if [ -f "$file_path" ] && head -n 5 "$file_path" 2>/dev/null | grep -qF 'omega:consumer-override:'; then
+  exit 0
+fi
+if [ -n "$content" ] && printf '%s\n' "$content" | head -n 5 | grep -qF 'omega:consumer-override:'; then
+  exit 0
+fi
+
+refuse <<EOF
+omega:guard — $rel shadows @omega.js/$framework/$shadow (framework-owned).
+If this is a framework gap, file an issue on Omega-JS-Stack/omega instead
+(upstream-first). If this brand genuinely needs its own copy, add
+\`// omega:consumer-override: <reason>\` to the top of the file and retry
+(OMEGA_CONSUMER_OVERRIDE=1 skips this check for the session).
+EOF

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/shape/run.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/gate/run.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/guard/run.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/quality/run.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/gate/run.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/quality/run.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/inject/run.sh"
+          }
+        ]
+      }
+    ]
+  }
+}