chore: apply engineering-standards (code-repo profile)

.github/engineering-standards.yml

@@ -0,0 +1,9 @@
+# Engineering-Standards-Status dieses Repos.
+# Single source of truth, gilt host- und agent-übergreifend.
+# Schema: siehe byte5ai/engineering-standards.
+
+status: applied          # applied | exempt
+source: byte5ai/engineering-standards
+decided_on: 2026-06-15
+reviewed_on: 2026-06-15
+reason: "Profil: Code-Repo (TS-Plugin-Bündel, siehe plan.md §4). Heute Docs-only; CI wächst mit Phase 0."

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # Code-Repo-Profil: baut/testet, sobald TS-Pakete existieren (Phase 0).
+      # Bis dahin ist der Job grün und validiert nur, dass das Repo konsistent ist.
+      - name: Build & test
+        run: |
+          if [ -f package.json ]; then
+            echo "package.json found — installing, building, testing."
+            if [ -f package-lock.json ]; then npm ci; else npm install; fi
+            npm run build --if-present
+            npm test
+          else
+            echo "No TS packages yet (Stufe A / Phase 0 bootstrap) — nothing to build."
+          fi
+
+      # Solange das Repo Docs-getragen ist, halten wir die zentralen Dokumente
+      # wenigstens auf balancierte Markdown-Code-Fences geprüft (deterministisch,
+      # dependency-frei). Verschwindet, wenn der Code-Test-Pfad oben greift.
+      - name: Docs sanity (balanced code fences)
+        run: |
+          status=0
+          for f in plan.md research.md AGENTS.md CONTRIBUTING.md; do
+            [ -f "$f" ] || continue
+            fences=$(grep -c '^```' "$f" || true)
+            if [ $((fences % 2)) -ne 0 ]; then
+              echo "::error file=$f::unbalanced code fences ($fences)"; status=1
+            fi
+          done
+          exit $status

.hooks/pre-commit

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Pre-commit hook for engineering-standards repos.
+#
+# Two checks, both run on every commit:
+#
+#   1) Main-tree discipline (mandatory engineering standard, see SKILL.md §3)
+#      The main clone never receives commits — every change lands in a
+#      worktree. This is branch-agnostic: an agent whose HEAD got switched
+#      to main by a parallel session is caught here too, not just one that
+#      created a feature branch in the wrong tree.
+#
+#      Bypass (one-off):    ALLOW_MAIN_TREE_BRANCH=1 git commit ...
+#      Opt-out (per repo):  git config engineering-standards.main-tree-discipline false
+#      Global opt-out:      status: exempt in .github/engineering-standards.yml
+#
+#   2) Per-branch path-guard (optional backstop)
+#      Refuses commits that stage paths inconsistent with the current
+#      branch's scope. No-op for branches without a rule in the case
+#      statement below — add per-branch rules as needed.
+#
+# Activated automatically when the repo runs:
+#   git config core.hooksPath .hooks
+
+set -e
+
+# --- (1) Main-tree discipline -------------------------------------------------
+
+mtd_enabled=$(git config --bool --get engineering-standards.main-tree-discipline 2>/dev/null || echo true)
+
+if [ "$mtd_enabled" != "false" ] && [ "${ALLOW_MAIN_TREE_BRANCH:-}" != "1" ]; then
+  main_tree=$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')
+  current_tree=$(git rev-parse --show-toplevel 2>/dev/null)
+  current_branch=$(git branch --show-current 2>/dev/null)
+
+  if [ -n "$main_tree" ] && [ -n "$current_tree" ] && \
+     [ "$main_tree" = "$current_tree" ]; then
+    echo "pre-commit: commits from the main clone are not allowed." >&2
+    echo "Convention: every change — even single-line fixes — lands in a worktree." >&2
+    echo "Reason: the main clone's HEAD can be switched by parallel sessions; commits" >&2
+    echo "from here have unreliable branch attribution." >&2
+    echo "" >&2
+    if [ -n "$current_branch" ] && [ "$current_branch" != "main" ] && [ "$current_branch" != "master" ]; then
+      echo "  git worktree add ../$(basename "$current_tree")-${current_branch//\//-} $current_branch" >&2
+    else
+      echo "  git worktree add ../$(basename "$current_tree")-<feature> -b <branch> main" >&2
+    fi
+    echo "" >&2
+    echo "Bypass (one-off):  ALLOW_MAIN_TREE_BRANCH=1 git commit ..." >&2
+    echo "Opt-out per repo:  git config engineering-standards.main-tree-discipline false" >&2
+    exit 1
+  fi
+fi
+
+# --- (2) Per-branch path-guard ------------------------------------------------
+
+branch="$(git branch --show-current)"
+
+case "$branch" in
+  # --- examples; delete and replace with your own rules ---
+  #
+  # research/foo)
+  #   allow='^(experiments/foo/|docs/foo/)'
+  #   ;;
+  # main)
+  #   forbid='^experiments/'
+  #   ;;
+  # ---------------------------------------------------------
+  *)
+    exit 0
+    ;;
+esac
+
+staged="$(git diff --cached --name-only)"
+
+if [ -n "${allow:-}" ]; then
+  bad="$(printf '%s\n' "$staged" | grep -vE "$allow" || true)"
+  if [ -n "$bad" ]; then
+    echo "pre-commit: branch '$branch' should not stage these paths:" >&2
+    printf '  %s\n' $bad >&2
+    echo "Use a worktree for this branch (see AGENTS.md) to avoid the drift class entirely." >&2
+    exit 1
+  fi
+fi
+
+if [ -n "${forbid:-}" ]; then
+  bad="$(printf '%s\n' "$staged" | grep -E "$forbid" || true)"
+  if [ -n "$bad" ]; then
+    echo "pre-commit: branch '$branch' must not stage these paths:" >&2
+    printf '  %s\n' $bad >&2
+    exit 1
+  fi
+fi

.hooks/pre-push

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Pre-push hook: block direct pushes to main/master.
+# Override: ALLOW_PUSH_TO_MAIN=1 git push origin main
+
+if [ "$ALLOW_PUSH_TO_MAIN" = "1" ]; then
+  exit 0
+fi
+
+while read -r _local_ref _local_sha remote_ref _remote_sha; do
+  remote_branch="${remote_ref##refs/heads/}"
+  if [[ "$remote_branch" =~ ^(main|master)$ ]]; then
+    echo ""
+    echo "  BLOCKED: Direct push to '$remote_branch' is not allowed."
+    echo "  Create a feature branch and open a pull request instead."
+    echo ""
+    echo "  Override (emergencies only):"
+    echo "    ALLOW_PUSH_TO_MAIN=1 git push origin $remote_branch"
+    echo ""
+    exit 1
+  fi
+done
+
+exit 0

AGENTS.md

@@ -0,0 +1,58 @@
+# Agent Instructions
+
+These rules apply to all AI agents working on this repository (Claude, Codex, Copilot, etc.).
+
+## Git Workflow
+- **Never push directly to `main`.** All changes go through feature branches and pull requests.
+- **Branch naming:** `feat/`, `fix/`, `refactor/`, `docs/`, `chore/`, `test/`, `release/`, `dev/` prefixes.
+- **Conventional commits:** `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, `release:`, `dev:`.
+- **No `Co-Authored-By:` trailers for Claude or other AI agents.** Commits are made under the configured git identity, with no model-attribution footer.
+- **Never force-push** to any shared branch.
+- **Never commit secrets** (`.env`, API keys, tokens, credentials).
+- **Never skip hooks** (`--no-verify`).
+
+## Pull Requests
+- Keep PR titles short (<70 chars), use conventional prefix.
+- One logical change per PR.
+- Ensure tests pass before requesting merge.
+
+## Working in a multi-session repo
+
+**Convention (enforced):** the main clone never receives commits. Every change — even a single-line typo fix — lands in a worktree. This is branch-agnostic: an agent whose HEAD got switched to `main` by a parallel session is caught here too, not just one that created a feature branch in the wrong tree. Enforced by the `.hooks/pre-commit` hook shipped via the engineering-standards skill.
+
+~~~bash
+git worktree add ../<repo>-<feature> -b <branch> main   # create with new branch
+git worktree add ../<repo>-<feature> <existing-branch>  # or attach existing
+# work in ../<repo>-<feature>/
+git worktree remove ../<repo>-<feature>                 # remove the tree
+git branch -D <feature>                                 # remove the branch ref (after merge or discard)
+git worktree list                                       # inspect
+~~~
+
+**After your PR is merged, clean up your worktree.** The two commands above (`git worktree remove …` + `git branch -D …`) are part of the merge workflow, not optional. For accumulated orphans across the repo, `script/prune-worktrees` (if present) reports and safely removes worktrees whose remote branches are gone or merged.
+
+Build artefacts (`target/`, `node_modules/`, etc.) live per worktree — first build per tree is full cost, subsequent builds are independent.
+
+**Bypass levels** (in increasing persistence):
+
+| Level | Effect | How |
+|---|---|---|
+| One-off | this commit only | `ALLOW_MAIN_TREE_BRANCH=1 git commit ...` |
+| Per repo | persistent disable, other standards still apply | `git config engineering-standards.main-tree-discipline false` |
+| Repo exempt | all engineering-standards disabled for this repo | `status: exempt` in `.github/engineering-standards.yml` |
+
+### Drift signals (for any unusual main-tree work that is allowed)
+
+- Run `git branch --show-current` before each commit and confirm it matches what you intended.
+- Treat `git status` anomalies as drift signals: directories you didn't touch showing as `??`, unexpected `M` on files you didn't edit. Don't commit through that — `git reflog | head -20` first to see who moved your HEAD.
+- Don't reach for `git reset --hard` reflexively; another session may have uncommitted work in the shared tree. Inspect `git stash list` and `git diff --stat` first.
+
+## Pre-push Hook
+A `.hooks/pre-push` hook blocks direct pushes to `main`/`master`. Override only when explicitly instructed:
+~~~bash
+ALLOW_PUSH_TO_MAIN=1 git push origin main
+~~~
+
+## Engineering Standards
+This repo's engineering-standards status is tracked in `.github/engineering-standards.yml`.
+Source of truth: the account's `engineering-standards` repo.

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to omadia Proof
+
+`byte5ai/omadia-proof` ist das ANP-Proof-Plugin-Bündel für omadia. Kontext: [plan.md](plan.md) (Implementierungsplan, Codex-reviewed) und [research.md](research.md) (verifizierte Faktenbasis A1–A8). Die Arbeit ist als Issues in Milestones gruppiert (Stufe A + Phase 0–5).
+
+## Dev-Setup
+
+```bash
+script/setup   # konfiguriert git-Hooks; installiert Dependencies, sobald Pakete existieren
+```
+
+## Workflow
+
+Dieses Repo folgt den byte5ai-Engineering-Standards (`.github/engineering-standards.yml`, Details in [AGENTS.md](AGENTS.md)).
+
+- **Nie im Haupt-Klon committen — immer ein Worktree:**
+  ```bash
+  git worktree add ../omadia-proof-<feature> -b feat/<desc> main
+  ```
+  Durchgesetzt durch `.hooks/pre-commit`. Nach Merge aufräumen: `git worktree remove …` + `git branch -D …` (oder `script/prune-worktrees`).
+- **Nie direkt auf `main` pushen.** Feature-Branch + PR; CI (`ci`) muss grün sein.
+- **Conventional Commits:** `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, `release:`.
+- **Branch-Präfixe:** `feat/ fix/ refactor/ docs/ chore/ test/ release/ dev/`.
+- **Keine** `Co-Authored-By:`-Trailer (auch nicht für KI-Agenten). **Nie** `--no-verify`. **Nie** Secrets committen.
+
+## Schema-Backflow (zwingend)
+
+Jede Änderung, die ein ANP-Object-/VC-Schema definiert oder ändert, **MUSS** in derselben Arbeitseinheit einen PR gegen `byte5ai/anp` (Appendix A) eröffnen — siehe [plan.md §1.4](plan.md) und [#2](https://github.com/byte5ai/omadia-proof/issues/2). Der RFC ist kanonisch; bei Divergenz gewinnt die SPEC.