docs(agent-hook): install dev role hooks (CLAUDE.md, AGENTS.md) — 文殊 batch 2026-04-27

AGENTS.md

@@ -0,0 +1,67 @@
+<!-- agents-md-role: dev -->
+
+# AGENTS.md — dev role
+
+> Open-standard agent contract per [agents.md](https://agents.md).
+> Companion to `CLAUDE.md` (Claude-specific) — this file works for any
+> AI coding agent (Cursor, Aider, Codex, OpenHands, etc.).
+
+## Dev environment tips
+
+- Default branch convention: `main` = prod, `dev` = rolling integration,
+  `release/*` = release candidates, `feat/*` = ephemeral feature branches.
+  If this repo currently uses something else (`im-dev`, `bundle`,
+  `4411-1`, `release`, `20260203`), see
+  `dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md` for the
+  migration plan.
+- For Vue 3 + Vite repos: `npm run build-only` (not `npm run build`)
+  to bypass legacy `tsc` errors that block clean builds.
+- For Flutter repos: `flutter pub get && flutter test` before any change.
+- For Swift repos: `xcodebuild -workspace ... -scheme ... test` from the
+  workspace root.
+
+## Testing instructions
+
+- TDD-first. Diff that changes behavior MUST add or update a test that
+  fails on the parent commit and passes on this branch.
+- Find existing tests by language:
+  - `tests/`, `core/tests/`, `__tests__/` (Python / JS)
+  - `test/`, `integration_test/` (Flutter / Dart)
+  - `*Tests/` (Swift)
+- Run with the lightest scope that proves the change:
+  `pytest core/tests/test_<module>.py` / `vitest run <pattern>` /
+  `flutter test test/<file>` / `xcodebuild test -only-testing:<TestClass>`.
+- Pre-existing failures unrelated to your change are NOT in scope to fix
+  unless explicitly requested. Note them in your PR body.
+
+## PR instructions
+
+- Title: `<type>(<scope>): <subject>` lowercase, no trailing period.
+- Body: `Why:` + `How:` + `Refs:` + `Co-Authored-By:` trailer.
+- Default branch is read at runtime — never hardcode `"main"` in
+  PR-create / merge calls. See `wen_shu_hub.auto_pr_botdev` for the
+  canonical pattern.
+- Idempotency: any artifact (issue, PR, comment) the agent creates MUST
+  carry an idempotency key in body so re-runs dedupe. Pattern:
+  `<!-- idem:<sha16> -->`.
+
+## Hard rules (production-incident-driven)
+
+1. **Fail-closed defaults** when uncertain about routing / permissions /
+   platforms. Default to the safer outcome (no fan-out, no auto-promote,
+   no auto-merge). See `_MODULE_PLATFORMS` in
+   `claude-worker-universe/core/wen_shu_hub.py` for the canonical pattern.
+2. **Portable links only.** Never write `/Users/...` in commits, issues,
+   comments, or test artifacts. Use Gitea web URL with per-segment UTF-8
+   percent-encoding. Helper: `_qa_spec_gitea_url`.
+3. **No inline PAT in remote URL.** If you see
+   `https://oauth2:<token>@host/...` in a remote, that's an existing
+   smell — don't propagate.
+
+## References
+
+- Master design: `claude-worker-universe/.omc/notes/master-design.md`
+- Build machine review: `dasheng-repos/.omc/notes/packing-machine-arch-2026-04-27.md`
+- Big-co patterns reused: Stripe Idempotency, Linear AI agents,
+  GitHub Copilot for Issues, Datadog rolling-3-window WARN, AWS IAM
+  fail-closed.

CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- claude-md-role: dev -->
+
+# CLAUDE.md — dev repo hook (autoinstalled by lobster-wenshu-bot)
+
+> This file is the project's CLAUDE.md hook for the **dev** role.
+> When Claude Code opens this repo, this is the first context it reads.
+> Author: 文殊菩萨 / `lobster-wenshu-bot`. Last updated: 2026-04-27.
+
+## Identity
+
+This repo is a **product / dev** repo. Code that ships to users.
+Bot owners: `lobster-worker-bot*` (iOS), `xurishu_bot` / `kevins-studio-bot` /
+`jarvis_theone_bot` / `andyjanebot` (H5). PR review: 八戒 (`lobster-qa-bot`)
+or human gate. Deploy: `mini-build-all` orchestrator (see also
+`packing-machine-arch-2026-04-27.md` in claude-worker-universe `.omc/notes/`).
+
+## Top rules
+
+1. **TDD-first.** Before changing behavior, the diff must include a new or
+   updated test that *fails* on `main` and passes on this branch. No
+   exceptions for "trivial" fixes — historically the trivial ones are the
+   ones that come back as P0 production bugs (idem-label collapse, label
+   string→int64 422, bold-colon regex, fail-closed iOS routing — all
+   shipped without enough tests).
+2. **Fail-closed defaults.** When a routing / permission / platform table
+   is unsure, default to the *safer* answer (no fan-out, no auto-promote,
+   no auto-merge). See `_MODULE_PLATFORMS` and `_PLATFORM_OWNER_BOTS` in
+   `claude-worker-universe/core/wen_shu_hub.py` for the canonical pattern.
+3. **Idempotency markers in the body.** Any artifact this repo creates
+   (issues, PRs, comments, files) should carry an idempotency key in its
+   body (e.g. `<!-- idem:<sha16> -->`) so re-runs / retries de-dupe. The
+   *labels* field on Gitea issues is **not** authoritative — it requires
+   the bot account to be a repo collaborator (most aren't). Cross-ref
+   commit `3a1013b` in claude-worker-universe.
+4. **Portable links only.** Never write a per-machine path
+   (`/Users/pp-bot/...`) into a commit, issue, or comment. Use the Gitea
+   web URL (`<host>/<org>/<repo>/src/branch/<branch>/<path>`) with
+   per-segment UTF-8 percent-encoding. See `_qa_spec_gitea_url` for the
+   canonical helper.
+5. **Branch convention** (target end state): `main` is prod, `dev` is
+   rolling integration, `release/*` is tagged. If this repo currently
+   uses something else (`im-dev`, `bundle`, `4411-1`, `release`, `20260203`),
+   read the latest `packing-machine-arch-2026-04-27.md` for the migration
+   plan and **don't unilaterally rename**.
+6. **Default branch is read at runtime** — never hardcode `"main"` in
+   PR-create / merge calls. `auto_pr_botdev` got bitten by this; the fix
+   reads `RepoState.default_branch` dynamically.
+
+## Big-co patterns reused in this codebase
+
+- **Stripe Idempotency-Key** → `_idempotency_key()` (sha16 hash; body
+  marker is the source of truth, not the label).
+- **Linear AI agents / GitHub Copilot for Issues** → @-mention
+  `_PLATFORM_OWNER_BOTS` in body; assignees are best-effort with 422
+  fallback because most bots aren't repo collaborators.
+- **Datadog rolling-window WARN** → `distribute.summary` JSON +
+  `distribute.idem_storm` after 3 consecutive ticks at idem_rate > 0.9.
+- **AWS IAM fail-closed default-deny** → `_MODULE_PLATFORMS` opt-in for
+  iOS routing; default H5-only.
+- **GitHub Actions/Vercel preview-smoke contract** → `headless-smoke`
+  CLI command (Playwright + Chromium against built dist/, emits PASS/FAIL
+  + screenshot + exit code).
+
+## Agent tier guidance for this repo
+
+- Trivial lookups → Haiku
+- Standard implementation → Sonnet
+- Architecture, race conditions, security review → Opus
+
+For multi-step work in this repo, route via the wenshu CLI:
+`python3 .../core/wen_shu_hub.py <subcommand>` — `gen` / `distribute` /
+`poll` / `auto-pr` / `state` / `daemon` / `headless-smoke` /
+`align-bot-dev` / `figma`.
+
+## Run commands
+
+If `package.json` exists: `npm install && npm run build-only` (skip
+type-check until repo's TS errors are clean — see lessons_learned).
+If `pyproject.toml` exists: `python3 -m pytest core/tests/`.
+If `pubspec.yaml` exists: this is a Flutter repo — see
+`packing-machine-arch-2026-04-27.md` for build hooks (worker-knowledge,
+bajie merge).
+
+## Commit style
+
+`<type>(<scope>): <subject in lowercase, no trailing period>`
+Body: `Why:` + `How:` + `Refs:`. End every commit with the `Co-Authored-By`
+trailer for the bot that authored it.
+
+## What this hook deliberately does NOT do
+
+- It does NOT pin a Python / Node / Flutter version (varies per repo).
+- It does NOT enforce a license / formatter — repos diverge.
+- It does NOT bypass review — `bot-dev → main` PRs still need human or
+  八戒 sign-off (master-design D2 / §6.2).