mozyo-bridge 0.5.4

Redmine-gated tmux pane notification bridge for Claude Code and Codex terminals

mozyo-bridge

mozyo-bridge は ClaudeCode / Codex の tmux pane に Redmine journal id を通知するための小さな bridge です。

正本は Redmine です。mozyo-bridge は通知 transport であり、レビュー依頼・監査結果・完了判断の正本にはなりません。

mozyo-bridge is a small CLI that sends Redmine-gated notifications to Claude Code / Codex tmux panes. It is only a notification transport. Redmine remains the source of truth for review requests, audit results, and completion decisions.

Quick Start

This README is the entrypoint for install and bootstrap. Run the steps below first; follow the links into the detailed docs only when a step fails or you need the full stage order.

人間向けのリリースノートは RELEASE_NOTES.md にあります。

1. Install the CLI and confirm tmux is on PATH:

   pipx install mozyo-bridge
   mozyo-bridge --version
   

   Alternative install path:

   python3 -m pip install mozyo-bridge
   python3 -m mozyo_bridge --help
   

2. Run the two health checks, in order, from your project root:

   # Toolchain health: CLI, central rules, agent skills, scaffold, tmux.
   mozyo-bridge doctor --target .
   
   # Repo-local LLM runtime config health (Redmine/Codex workspaces).
   mozyo-bridge instruction doctor --target . --profile redmine-codex
   

3. Read the result:

   • doctor exits non-zero on a toolchain gap (missing rules, skill, scaffold drift, tmux). It prints the next command for each finding.
   • instruction doctor is the source of truth for whether a Redmine/Codex workspace's repo-root runtime config is correct. It is read-only: it never creates, fixes, or writes config. On a failure, see instruction doctor failures below and the FAQ it links to.

For first-time install on a clean machine, or to follow the full install → rules → skill → scaffold → doctor stage order end-to-end, use vibes/docs/logics/bootstrap.md as the detailed stage-order / troubleshooting reference (it is no longer the first thing you read; this Quick Start is).

doctor vs instruction doctor

• mozyo-bridge doctor --target . — toolchain readiness: CLI, central rules, agent skills, scaffold manifest, tmux. Run this first.
• mozyo-bridge instruction doctor --target . --profile redmine-codex — repo-local LLM runtime config: <repo>/.codex/config.toml Redmine default project, the redmine_epic_grid MCP header, and credential-shape hygiene of .codex/config.toml / .mcp.json. This is the machine check that the Redmine-Codex startup config actually exists and is consistent, so an agent cannot silently skip it by skimming the docs.

instruction doctor failures

instruction doctor is read-only and never autofixes. The common failures and the operator action they require:

• <repo>/.codex/config.toml is missing — the workspace has no repo-root Redmine default. Ask the operator before creating it; do not put it in a home config. See the FAQ in vibes/docs/logics/bootstrap.md.
• X-Default-Project mismatch — the MCP header and [redmine].default_project disagree. One of them is wrong; an operator must reconcile them.
• .mcp.json present/absent — reported as info, never a failure on its own. .mcp.json stays non-authoritative until a runtime is verified to read the repo-root file (deferral).
• credential-shape value — a token/key/secret was found in a repo-local config. Remove it; credentials belong in user-level config or a secret store, never in <repo>/.codex/config.toml or <repo>/.mcp.json.

Detailed cause/fix for each, plus the home-config-prohibition rationale and what an agent may auto-fix vs must confirm with an operator, is in vibes/docs/logics/bootstrap.md (Stage 7 — Failure recovery and common pitfalls).

Use the full command in docs and durable task records:

mozyo-bridge <command>

The short alias is available for local interactive use:

mozyo <command>

Bootstrap ownership and local secrets

For bootstrap and day-1 setup, treat this repository and any shared-drive copy of it as the distribution source, not as the place where machine-local secrets live.

Keep in the repo / shared-drive copy:

• portable config and bootstrap docs
• scaffold/rules sources
• install / doctor / bootstrap helper scripts

Keep only on each local machine:

• auth.json
• ~/.mcp-auth/
• Asana OAuth tokens / refresh state
• client secrets or any other user-specific credentials

Do not commit or sync the local-secret files above back into the repository or a shared-drive bootstrap bundle.

Asana OAuth note

Asana OAuth is only required on machines that will actually use the Asana connector / MCP-backed Asana workflow. A plain CLI install, rules install, scaffold, or doctor run does not by itself provision Asana credentials.

When a bootstrap or day-2 workflow reaches an Asana-backed step, the user/operator must complete the OAuth/login flow in that local environment and leave the resulting credentials on that machine only. mozyo-bridge docs may point at the Asana workflow, but the OAuth state is not part of the portable bootstrap payload.

Daily entrypoint: bare mozyo

The fastest way to start a Claude / Codex pair in a repo is to run mozyo with no subcommand:

cd /path/to/your-repo
mozyo

これは以下を一括で行います。

• repo root を解決 (--repo → MOZYO_REPO → .git / .tmux.conf / pyproject.toml を遡る)
• session 名を mozyo-bridge session name と同じ衝突しにくい ASCII 名に導出して、無ければ作る (<repo>/.mozyo-bridge/workspace-defaults.yaml の Redmine identifier 優先、無ければ mozyo-<basename-slug>-<hash>)。--session NAME を明示した場合はそれを優先 (Redmine #10796)
• 1 つの repo-scoped session の中に claude window と codex window を ensure (window 別に分離)
• claude window を default にしてから attach

Window 分離なので、ある時点で画面に出るのは 1 agent の window だけです。tmux は同じ client 内で複数 window を同時表示する仕組みではないため、agent 同士の切り替えは prefix + n / prefix + p などの通常の window 操作で行います。

attach せずに session / window だけ用意したい場合:

mozyo --no-attach

session 名が同じでも repo root の下に pane が 1 つも無い場合 (= 別 project の session が同名で居る場合) は、誤 attach を避けるためにエラーで止まります。明示的に session 名を分離する場合は mozyo --session NAME で session 名を上書きするか、bare mozyo --repo /path/to/another で別 repo root を指定してください。

移行メモ: 以前の bare mozyo は session 名を repo basename にしていました。導出名へ移行したため、古い basename session が残っている repo では bare mozyo 実行時に notice を出します。古い session に入りたい場合は mozyo --session <旧basename> (または tmux attach -t <旧basename>)、空になったら tmux kill-session -t <旧basename> で片付けてください。--target-repo gate と init の同名 window fail-closed は従来どおりです。

open-here / tmux-ui-open / tmux-ui-setup / tmux-ui-ensure-pair / tmux-ui-ensure / tmux-ui-spawn の pane-split 系 subcommand は廃止されました。標準導線は bare mozyo (1 repo = 1 session, 1 agent = 1 window) です。既存の標準 tmux pane や VS Code tmux-integrated pane を agent target にしたい場合は、その pane の中で mozyo-bridge init <agent> を実行して window 名を <agent> に rename してください。

VS Code tmux-integrated の session 名 (mozyo-bridge session name)

VS Code の tmux-integrated 拡張 / TaskPilot menu は workspace basename から tmux session 名を導出します (典型的には basename "$PWD" | sed ...)。basename が日本語など非 ASCII を含むと (2026PBL_ローカル など) 2026PBL_____ のような低情報量名に潰れ、同名の ____ session が複数 workspace で衝突すると mozyo-bridge agents list / --target-repo handoff gate が repo identity を復元できなくなります。

bare mozyo は既にこの導出名で session を作りますが、VS Code は mozyo を経由せず自前で session を立てるため、VS Code 側にも同じ導出名を渡す必要があります。

mozyo-bridge session name は repo path から 衝突しにくい ASCII session 名を導出します。<repo>/.mozyo-bridge/workspace-defaults.yaml の redmine.default_project.identifier があればそれを優先し (mozyo-<identifier-slug>)、無ければ repo path の短い hash を付けた fallback (mozyo-<basename-slug>-<hash>) を返します。非 ASCII basename を ____ に潰すことはなく、同名 basename でも path hash で区別されます。

# 単一行出力 (shell / task script から使う)
mozyo-bridge session name --repo /path/to/your-repo
# => mozyo-giken-3800-mozyo-bridge

# 導出元込みの JSON
mozyo-bridge session name --repo /path/to/your-repo --json

運用方針:

• user-global の tmux-integrated.sessionName 固定値は使わないでください。全 workspace が同一 session 名に collapse し、別 repo へ誤送信する危険が出ます。

• workspace-local で固定する (推奨・機械化)。mozyo-bridge session vscode-settings --repo . --write を実行すると、<repo>/.vscode/settings.json の "tmux-integrated.sessionName" を導出名に設定します。workspace-local 設定のみを触り、credential を含み得る user-global 設定は読み書きしません。コメント付き (JSONC) の settings は壊さず、手編集を促して停止します。--write 無しは適用内容を表示する dry-run です。

  mozyo-bridge session vscode-settings --repo .            # dry-run
  mozyo-bridge session vscode-settings --repo . --write    # .vscode/settings.json に書き込み
  

• TaskPilot / 自前 task menu で動的に session 名を組む場合は、basename "$PWD" | sed ... を mozyo-bridge session name --repo . の出力に置き換えてください。例:

  s=$(mozyo-bridge session name --repo .)
  tmux new-session -A -s "$s"
  

• session name / session vscode-settings (dry-run) は tmux state も Redmine も変更しません。--target-repo gate と init の同名 window fail-closed の安全境界は変更していません。

Subtle window status colors

bare mozyo と mozyo-bridge init <agent> は agent window の tmux status bar entry に控えめな色を付けます。claude は muted sage green (colour108)、codex は muted slate blue (colour67)、それ以外の window は user 設定の default のまま無加工です。配色は fg のみで、背景塗りや点滅は使いません。

色は window 識別のためであり、resolver / handoff routing は依然 window 名 (claude / codex) を exact key として使うため、window 名は変更されません。色を外したい場合は tmux set-window-option -u -t <session>:<window> window-status-style (および window-status-current-style) で個別 unset するか、operator の .tmux.conf 側で上書きしてください。.tmux.conf / ~/.config/mozyo-bridge/tmux.conf の読み込み挙動には影響しません。

tmux UI host wiring (tmux-ui install)

governed preset が配布する .mozyo-bridge/tmux/agent-ui.conf を host 側 tmux 設定 (default ~/.tmux.conf) から自動 source したい場合は、mozyo-bridge tmux-ui install を使います。operator の既存 ~/.tmux.conf を丸ごと上書きすることはなく、# >>> mozyo-bridge tmux-ui >>> / # <<< mozyo-bridge tmux-ui <<< で囲んだ管理ブロックのみを追加 / 更新 / 削除します。ブロック内部は if-shell で snippet の存在確認をしてから source-file するため、repo を移動 / 削除しても tmux 起動が壊れません。

主な操作:

# repo に scaffold 済みの agent-ui.conf を ~/.tmux.conf に wiring する
mozyo-bridge tmux-ui install --target <repo>

# 何が書き換わるか確認だけしたい
mozyo-bridge tmux-ui install --target <repo> --dry-run

# 既存 ~/.tmux.conf のバックアップを残してから wiring する
mozyo-bridge tmux-ui install --target <repo> --backup

# 既存ブロックが別 repo の path を指している (drift) ときに上書きする
mozyo-bridge tmux-ui install --target <repo> --force

# wiring を解除する (管理ブロックのみ削除、surrounding 設定は無傷)
mozyo-bridge tmux-ui uninstall

# wiring 状態を確認する (not-installed / installed / drift)
mozyo-bridge tmux-ui status --target <repo>
mozyo-bridge tmux-ui status --target <repo> --json   # drift 時は exit 1

idempotent な操作です。同じ repo path に対する 2 回目の install は no-op、install → uninstall の round-trip は byte-for-byte で原状復帰します (managed block 周辺の blank line 含む)。host 側の tmux 設定パスを上書きしたい場合 (例: $XDG_CONFIG_HOME/tmux/tmux.conf) は --tmux-conf <path> を指定してください。

doctor は tmux.artifact.host_wiring で同じ状態を report します。installed / not-installed / drift の三状態と、現在 source している path、推奨復旧コマンドを表示します。導入したくない operator は単に install を実行しなければよく、scaffold は host 設定に一切触れません。

Beta Tester Install (GitHub main)

PyPI release 前の beta tester 向け手順です。Quick Start の PyPI install とは別経路で、GitHub main の最新 commit を直接 install します。mozyo-bridge --version が表示する package version 文字列は pyproject.toml の値なので、PyPI release と GitHub main で同じ string になる場合があります。実体差は新規 sub-command (例: mozyo-bridge scaffold status --help / mozyo-bridge doctor --json) や、mozyo-bridge rules install が配布する preset 内容で確認してください。

PyPI / TestPyPI release の検証手順は本節と同じ acceptance smoke を、GitHub main install のかわりに該当 PyPI install で実行してください。release 経路の詳細は vibes/docs/logics/release-flow.md を見ます。

Isolation principle

mozyo-bridge scaffold apply <preset> は対象 directory の AGENTS.md / CLAUDE.md を生成 / 上書きします。本 repository (mozyo_bridge 自身) の tracked router を壊さないために、検証は必ず以下のどちらかで行います。

• ./tmp/mb-smoke-asana / ./tmp/mb-smoke-redmine / ./tmp/mb-smoke-redmine-governed / ./tmp/mb-smoke-redmine-rails のような isolated target を使う (./tmp/ は .gitignore 配下の作業領域)。
• もしくは別 directory で git clone した fresh checkout、または任意の /tmp/... directory を使う。

本 repo の working tree で mozyo-bridge scaffold apply <preset> を --target 無しで実行しないでください。tracked AGENTS.md / CLAUDE.md が上書き候補になり、scaffold apply 自体は default で既存ファイルを保護しますが、--force / --backup を伴うと取り違える可能性があります。事前に mozyo-bridge scaffold diff <preset> で差分を確認してください。

Acceptance smoke

1. GitHub main から install (既存 PyPI install を上書き):

   pipx install --force git+https://github.com/hollySizzle/mozyo_bridge.git
   

2. user-global rules を install して状態を確認:

   mozyo-bridge rules install
   mozyo-bridge rules status
   

   rules status は ${MOZYO_BRIDGE_HOME:-~/.mozyo_bridge}/rules/presets/<preset>/ に展開された user-global 規約 (src/mozyo_bridge/scaffold/presets/presets.yaml の preset registry) の状態を表示します。

   commit する docs / router に貼る portable 表記、または local diagnostics 用の resolved path を直接確認したい場合は mozyo-bridge rules home を使ってください。default は ${MOZYO_BRIDGE_HOME:-~/.mozyo_bridge} を出力するので docs snippet 用にそのまま貼れます。--resolved を付けると環境変数 MOZYO_BRIDGE_HOME と ~ を展開した absolute path を表示しますが、こちらは operator の $HOME を含み得るので committed docs には貼らないでください。

3. agent skill を install (推奨経路):

   # Claude Code: plugin marketplace 経由 (推奨)
   claude plugin marketplace add hollySizzle/mozyo_bridge
   claude plugin install mozyo-bridge-agent@mozyo-bridge --scope user
   
   # Codex: ユーザーが Codex 環境で $skill-installer を実行する
   $skill-installer https://github.com/hollySizzle/mozyo_bridge/tree/main/skills/mozyo-bridge-agent
   

   Claude Code 側は plugins/mozyo-bridge-agent/ (.claude-plugin/plugin.json) を marketplace 経由で取得します。Codex 側は canonical skills/mozyo-bridge-agent/ を、ユーザー/オペレーターが Codex 環境で $skill-installer により同期します。plugins/mozyo-bridge-agent/skills/mozyo-bridge-agent/ は scripts/sync_plugin_skill.sh が canonical から mirror した copy で、drift は unit test で検出します。

   bootstrap では curl/script による skill install は禁止です。詳細と precedence の落とし穴 (Claude Code は同名 skill で personal が project を override) は Agent Skill Install 節と vibes/docs/logics/skill-distribution.md を参照してください。

4. Claude Code / Codex を再起動して、新しい skill と user-global 規約を再読み込みさせます。同 session 内では skill index がキャッシュされるため再起動を省略しないでください。

5. install 直後の前提を確認します。Claude 側は plugin marketplace 経路を、mozyo-bridge doctor は CLI / rules / Codex skill / (fallback path を使った場合のみ) Claude skill を見ます。

   Claude plugin marketplace 経路の確認:

   claude plugin marketplace list
   claude plugin list
   

   claude plugin marketplace list に mozyo-bridge が出て、claude plugin list に mozyo-bridge-agent@mozyo-bridge が出ていれば、Claude Code 側の primary install は成立しています。plugin skill は ~/.claude/plugins/cache/ 配下に展開され、Claude Code 起動時に mozyo-bridge-agent:mozyo-bridge-agent namespace で読み込まれます。

   CLI / rules / Codex skill の確認:

   mozyo-bridge doctor
   

   このタイミングでは scaffold section が missing (-> mozyo-bridge scaffold apply <preset> --target ...) になりますが、cli / rules / codex_skill の 3 section が ok であることを確認します。next_action (-> ...) を読み、不足があれば該当 install / set up を再実行してください。

   claude_skill section の扱い:

   • primary path (plugin marketplace) でだけ install した場合、claude_skill: plugin-managed が出ます。現行 mozyo-bridge doctor は legacy directory (~/.claude/skills/ / <project>/.claude/skills/) に加えて plugin cache (~/.claude/plugins/cache/) も scan しており、plugin だけ検出した状態は plugin-managed という固有 status で healthy として扱われます (next_action は空、overall doctor も ok=true を維持)。primary path の最終確認は上の claude plugin list で行います。
   • fallback path (scripts/install_claude_skill.sh) を併用した場合は legacy directory にも skill が入るので claude_skill: ok が出ます。同名 skill が plugin と legacy 両方に居る状況は plugin namespace (mozyo-bridge-agent:mozyo-bridge-agent) で分離されるため衝突しませんが、scripts/install_claude_skill.sh 経由の legacy global Claude skill は新規 install で deprecated です (vibes/docs/logics/skill-distribution.md の ## Legacy Global Claude Skill Deprecation 節参照)。precedence の落とし穴は Agent Skill Install 節を見てください。

6. isolated target に対して Asana / Redmine の repo-local scaffold を smoke:

   mkdir -p ./tmp/mb-smoke-asana
   mozyo-bridge scaffold diff asana --target ./tmp/mb-smoke-asana  # 任意: 適用前の差分確認
   mozyo-bridge scaffold apply asana --target ./tmp/mb-smoke-asana
   mozyo-bridge scaffold status --target ./tmp/mb-smoke-asana
   mozyo-bridge doctor --target ./tmp/mb-smoke-asana
   
   mkdir -p ./tmp/mb-smoke-redmine
   mozyo-bridge scaffold diff redmine --target ./tmp/mb-smoke-redmine
   mozyo-bridge scaffold apply redmine --target ./tmp/mb-smoke-redmine
   mozyo-bridge scaffold status --target ./tmp/mb-smoke-redmine
   mozyo-bridge doctor --target ./tmp/mb-smoke-redmine
   
   mkdir -p ./tmp/mb-smoke-redmine-governed
   mozyo-bridge scaffold diff redmine-governed --target ./tmp/mb-smoke-redmine-governed
   mozyo-bridge scaffold apply redmine-governed --target ./tmp/mb-smoke-redmine-governed
   cp ./tmp/mb-smoke-redmine-governed/.mozyo-bridge/docs/catalog.yaml.example \
      ./tmp/mb-smoke-redmine-governed/.mozyo-bridge/docs/catalog.yaml
   mozyo-bridge docs validate --repo ./tmp/mb-smoke-redmine-governed
   mozyo-bridge docs validate --check-file-coverage --repo ./tmp/mb-smoke-redmine-governed
   mozyo-bridge docs generate-file-conventions --repo ./tmp/mb-smoke-redmine-governed
   mozyo-bridge docs generate-file-conventions --check --repo ./tmp/mb-smoke-redmine-governed
   mozyo-bridge scaffold status --target ./tmp/mb-smoke-redmine-governed
   mozyo-bridge doctor --target ./tmp/mb-smoke-redmine-governed
   
   mkdir -p ./tmp/mb-smoke-redmine-rails
   mozyo-bridge scaffold diff redmine-rails --target ./tmp/mb-smoke-redmine-rails
   mozyo-bridge scaffold apply redmine-rails --target ./tmp/mb-smoke-redmine-rails
   mozyo-bridge scaffold status --target ./tmp/mb-smoke-redmine-rails
   mozyo-bridge doctor --target ./tmp/mb-smoke-redmine-rails
   

   各 target で scaffold status が result: clean を返し、mozyo-bridge doctor --target ... の scaffold section が ok であれば、user-global 規約・repo-local routers・manifest が整合しています。主要 preset boundary (Asana / Redmine / Redmine Governed / Redmine Rails) を確認します。片側だけで完了させると preset 間 boundary の検証が落ちます。

7. CI / 機械的な acceptance smoke では --json を使います:

   mozyo-bridge doctor --target ./tmp/mb-smoke-asana --json
   

   出力は {"ok": <bool>, "sections": {"cli": {...}, "rules": {...}, "codex_skill": {...}, "claude_skill": {...}, "scaffold": {...}, "tmux": {...}}} 形式で、jq '.sections.scaffold.status == "ok"' 等で gate を組めます。exit code は ok が false の時に非ゼロです。primary path (plugin marketplace) でだけ install した CI は jq '.sections.claude_skill.status' を == "missing" で gate しないでください — 上記 step 5 の通り plugin-managed が期待状態 (healthy) です。jq '.sections.claude_skill.status as $s | $s == "ok" or $s == "plugin-managed"' のように plugin-managed を含めて healthy 判定するか、jq '.ok' で overall gate を組んでください。

mozyo-bridge rules status (user-global 規約の install 状態) と mozyo-bridge scaffold status (repo-local manifest drift) は別責務です。前者は host 全体、後者は 1 つの scaffold 済 project を見ます。mozyo-bridge doctor は両者と CLI / Codex skill / Claude skill (plugin cache + legacy directory) / tmux を 1 command で見る 6-section diagnostic です。Claude 側の primary path (plugin marketplace) は doctor の plugin cache scan 対象に入っており、plugin だけ install した状態は claude_skill: plugin-managed として healthy になります。最終 install 確認は claude plugin list を併用してください。詳細は次の logic docs を正本にしてください。

• vibes/docs/logics/skill-distribution.md
• vibes/docs/logics/scaffold-rules.md

PyPI / TestPyPI release 後に、ルートの AGENTS.md / CLAUDE.md を一旦削除して install 済 package だけで scaffold + 自律 handoff まで復旧できるかを検証する破壊的な acceptance test は別経路です。前提 (clean worktree / git-managed) と手順は vibes/docs/logics/turnkey-e2e-acceptance.md を参照してください。本 Beta Tester Install section の smoke は ./tmp/mb-smoke-* で実行し、本 repo の tracked router を壊しません。

Project Root Resolution

PyPI / pipx などで CLI としてインストールする場合は、インストール先ではなく実行場所から project root を決めます。

優先順位:

1. --repo /path/to/repo
2. MOZYO_REPO=/path/to/repo
3. 現在のディレクトリから親方向に .git / .tmux.conf / pyproject.toml を探索
4. 見つからない場合は現在のディレクトリ

例:

mozyo-bridge status --repo /path/to/repo
MOZYO_REPO=/path/to/repo mozyo

bare mozyo (標準導線) は 1 つの repo-scoped session 内に claude / codex window を ensure し attach します。 .tmux.conf は project root にあればそれを使い、なければ ~/.config/mozyo-bridge/tmux.conf を見ます。

config が default 解決経路のどちらにも存在しない場合、bare mozyo と notify-* は config の source を skip して session / pane 起動だけを実行します。一方 --config-path /path/to/conf を 明示 指定した場合は path 不存在を typo 防止のため tmux config not found で fail-fast します。mozyo-bridge tmux-ui-config (load 専用 command) も従来通り存在しない config は error にします。

Pane Setup

標準導線は mozyo (bare) です。repo root で mozyo を実行すると claude / codex の window が自動で揃い、target resolution はその window 名だけを参照します。

VS Code tmux: New tmux Terminal や hand-managed tmux pane など、別の経路で開いた pane を agent target にしたい場合は、その pane の中で init を実行して window 名を agent 名に変更します。

mozyo-bridge init claude   # 現在の pane を含む window を `claude` にリネーム
mozyo-bridge init codex %42  # 特定 pane の window を `codex` にリネーム

init は pane label (@agent_name) を一切触りません。window の rename だけが agent identity を確立する単一経路です。同じ session に既に <agent> という名前の window が居る場合は明示 error で止まります (tmux は同名 window の重複を黙認しますが resolver はしません)。

状態確認:

mozyo-bridge status

status は引数なしで実行すると、TMUX_PANE から現在の tmux session を解決し、無ければ repo basename にフォールバックします。current session 内に claude / codex window があれば一覧が WINDOW NAME TARGET ACTIVE PROCESS CWD 表で出力されます。無ければ no agent windows in this session という informational 行と、mozyo / mozyo-bridge init claude|codex の hint を表示します。--session NAME で明示指定もできます。

Target resolution (window-only model)

mozyo-bridge message claude ... / read claude / notify-claude のように agent label を target に指定したとき、解決経路は 1 本だけです。

1. 現在の tmux session 内で claude / codex という名前の window を探し、その active pane を target にします。
2. 見つからなければ明示 error で止まります。%pane_id を直接渡すか、対象 pane で mozyo-bridge init claude|codex を打って window を rename してから再実行してください。
3. cross-session fallback はしません。別 session の同名 window へ解決して mis-route した過去事例 (Asana task 1214743574772820 comment 1214746077864452) を踏まないための fail-closed です。

これまで存在した @agent_name label による互換 path は廃止しました。標準 tmux pane を target にしたい場合は mozyo-bridge init <agent> で window 名を正規化してください。

Cross-workspace agent discovery (agents list)

複数 workspace を同時に開いている場合、session / window / pane / process / cwd / repo root / agent 種別を一括で取得できる read-only な discovery surface が必要です。これは mozyo-bridge list (raw single-session pane table) や mozyo-bridge status (current session diagnostics) とは別 namespace に分離してあります。

mozyo-bridge agents list
mozyo-bridge agents list --session other-repo
mozyo-bridge agents list --agent claude --json

• --session NAME で session 名を完全一致 filter できます。
• --agent claude|codex|unknown で window-name agent rail に基づく分類で filter できます。unknown は agent window でない pane を意味します。
• --json で JSON output が出ます (session, window_index, window_name, pane_id, pane_index, pane_active, agent_kind, process, cwd, repo_root, ambiguous)。
• repo_root は pane の cwd から .git / .tmux.conf / pyproject.toml を遡って推定します。markers が見つからない場合は null です。情報用 field で、ここを根拠に handoff を拒否したい場合は下記の --target-repo を使ってください。
• ambiguous=true は同一 session 内で同じ window name が複数 window に存在する状態です (resolver 既存 fail-closed と同じ条件)。

Cross-Workspace Handoff Gate

別 workspace の Claude に直接通知を投げると target workspace の audit boundary (Codex 監査) を bypass してしまいます。これを防ぐため、mozyo-bridge handoff send / reply には次の制約が CLI レベルで入っています (Redmine #10332)。

• Cross-session --to claude は拒否される。sender の tmux session と target pane の session が異なるとき --to claude で送ろうとすると blocked / cross_session_claude で止まります。送信側は --to codex --target <target_session>:codex --mode standard (もしくは --mode pending) で target workspace の Codex window 経由に切り替え、target Codex から local Claude handoff を実行してもらいます。
• Cross-session --to codex は gateway path として許可される。ただし --mode standard か --mode pending を明示する。default の queue-enter rail (v0.4 以降) は no-rollback 契約を sender session に縛るため、cross-session target を receiver に依らず invalid_args で全面拒否します。--mode を省略した cross-session gateway は同じく失敗するので、cross-workspace 送信時は必ず --mode を付けます。
• --target-repo PATH の repo mismatch check (opt-in) — --target-repo /path/to/repo を渡すと、target pane の cwd から walk-up した repo root が一致しない場合 blocked / target_repo_mismatch で止まります。同名 session を別 repo で開いている場合の mis-route 防止に使います。
• queue-enter mode は cross-session 全面禁止 (invalid_args)。本 gate はそれより緩い strict / pending mode でも cross-session の Claude 直撃を遮断する layer です。strict / pending mode 自体は cross-session を許可しますが、--to claude だけは本 gate で fail-closed します。

Claude Code の project skill は repo root の .claude/skills/ から解決されます。 mozyo-bridge status / doctor が claude_pane cwd is outside repo root を出した場合、その pane では /mozyo-bridge-agent などの project skill が解決されない可能性があります。 repo root で Claude Code を起動し直してから mozyo-bridge init claude を再実行してください。

Agent Skill Install

Claude Code (primary: plugin marketplace)

claude plugin marketplace add hollySizzle/mozyo_bridge
claude plugin install mozyo-bridge-agent@mozyo-bridge --scope user

This adds the mozyo-bridge marketplace defined in .claude-plugin/marketplace.json at the repo root and installs the mozyo-bridge-agent plugin from plugins/mozyo-bridge-agent/. The plugin ships its own copy of the shared skill body (kept in lockstep with canonical skills/mozyo-bridge-agent/ by scripts/sync_plugin_skill.sh and the drift test). Plugin skills are namespaced as mozyo-bridge-agent:mozyo-bridge-agent, so they do not conflict with personal or project skills of the same name.

Codex (primary: $skill-installer against canonical GitHub skill path)

Canonical path: https://github.com/hollySizzle/mozyo_bridge/tree/main/skills/mozyo-bridge-agent

The user/operator must run Codex $skill-installer against the canonical skills/mozyo-bridge-agent/ directory in hollySizzle/mozyo_bridge main. The skill body, references, and agents/openai.yaml are all there.

Fallback: curl-based install scripts (legacy, deprecated for new installs)

scripts/install_codex_skill.sh and scripts/install_claude_skill.sh remain for environments where the recommended paths above are not available (offline mirrors, internal forks, fresh-tester acceptance smoke). They are deprecated for new installs — new users should use the plugin marketplace path (Claude) and $skill-installer (Codex) above; bootstrap and onboarding instructions should not use them.

In particular, the Claude personal-skill destination (~/.claude/skills/mozyo-bridge-agent/) that this script writes to is the legacy global Claude skill and is deprecated for new installs (Asana 1214733632421625). It is not removed from existing user homes automatically; existing users may keep it or delete it manually. New installs should use only the plugin marketplace path so the mozyo-bridge-agent:mozyo-bridge-agent namespace prevents the personal-overrides-project precedence gotcha. See vibes/docs/logics/skill-distribution.md ## Legacy Global Claude Skill Deprecation for the policy detail.

Similarly, the tracked project Claude skill at <repo>/.claude/skills/mozyo-bridge-agent/ (loaded when Claude Code is started from this project root, or when MOZYO_BRIDGE_CLAUDE_SCOPE=project is used with the fallback script) is on a grace-period deprecation (Asana 1214733817990357). It is not removed from the repo by this task; the canonical body remains under skills/mozyo-bridge-agent/. New installs should use only the plugin marketplace path; the project-scope adapter is preserved until the documented removal criteria are met. See vibes/docs/logics/skill-distribution.md ## Legacy Project Claude Skill (.claude/skills/mozyo-bridge-agent/) Grace-Period Deprecation for the policy detail.

# Codex skill (fallback)
curl -fsSL https://raw.githubusercontent.com/hollySizzle/mozyo_bridge/main/scripts/install_codex_skill.sh | sh

# Claude Code skill (fallback, user-global / personal)
curl -fsSL https://raw.githubusercontent.com/hollySizzle/mozyo_bridge/main/scripts/install_claude_skill.sh \
  -o /tmp/install_mozyo_bridge_claude_skill.sh
MOZYO_BRIDGE_CLAUDE_SCOPE=global sh /tmp/install_mozyo_bridge_claude_skill.sh

MOZYO_BRIDGE_CLAUDE_SCOPE=global curl ... | sh の形は env var が curl にしか渡らないため、pipe の右側で sh の直前に env を置く形を使ってください。両方に配布したい場合は、明確な意図のもとで script を二度実行します (scope=project と scope=global を順に)。

Claude Code は同名 skill について personal/user skill (~/.claude/skills/) を project skill (<project>/.claude/skills/) より優先します (公式 docs: https://code.claude.com/docs/en/skills)。多くの開発ツールと逆向きの慣習なので注意してください。Plugin skills は plugin-name:skill-name で namespace 分離されるため、personal / project skill とは衝突しません。

Install destinations (fallback scripts):

• ${CODEX_HOME:-$HOME/.codex}/skills/mozyo-bridge-agent/ (Codex user-global)
• ${MOZYO_BRIDGE_CLAUDE_HOME:-$HOME/.claude}/skills/mozyo-bridge-agent/ (Claude user/personal, scope=global)
• ${MOZYO_BRIDGE_CLAUDE_PROJECT_DIR:-$PWD}/.claude/skills/mozyo-bridge-agent/ (Claude project adapter, scope=project)
• ${MOZYO_BRIDGE_CLAUDE_PROJECT_DIR:-$PWD}/skills/mozyo-bridge-agent/ (Claude project shared body, scope=project)

Both fallback scripts fetch hollySizzle/mozyo_bridge main by default. Override the source with MOZYO_BRIDGE_SKILL_REPO, MOZYO_BRIDGE_SKILL_REF, or MOZYO_BRIDGE_SKILL_ARCHIVE_URL (the last accepts any tarball URL, including file:///... for local-checkout install).

Detailed distribution rules live in vibes/docs/logics/skill-distribution.md.

Agent Rules Scaffold

mozyo-bridge can install ticket-system-specific development flow rules and scaffold thin project routers for Claude Code and Codex.

Choose the preset before applying scaffold. The selection order is:

1. durable work system (asana, Redmine, or none);
2. framework surface (Rails vs non-Rails for Redmine projects);
3. governance depth (lightweight routers vs full governed catalog package).

Use redmine-governed / redmine-rails-governed only when the project will maintain Project-Local Additions, .mozyo-bridge/docs/catalog.yaml, generated file conventions, and the corresponding validation checks. Use redmine / redmine-rails when thin routers and project-owned local policy are enough. Use none when there is no durable ticket system. The full decision flow lives in vibes/docs/logics/bootstrap.md; preset semantics live in vibes/docs/logics/scaffold-rules.md.

Repo-Local Guardrail Autonomous Lane (governed presets only) — the redmine-governed and redmine-rails-governed presets ship a Codex autonomous-edit carve-out for vibes/docs/rules/**, vibes/docs/logics/**, vibes/docs/specs/**, and .mozyo-bridge/docs/catalog.yaml. Inside the lane Codex may edit without a pre-edit codex_direct_edit gate journal; instead the preset requires a codex_autonomous_edit journal recorded with the commit (lane, changed_paths, intent, verification, commit_hash, follow_up_review_required). Distributed surfaces — AGENTS.md, CLAUDE.md, .mozyo-bridge/rules/**, skills / plugins, packaged preset templates, src/**, tests/** — stay under the standard gate. See the preset's ### Repo-Local Guardrail Autonomous Lane section for the policy, and vibes/docs/rules/codex-autonomous-guardrail-lane.md in this repo for a concrete adoption example.

Install the central rules store:

mozyo-bridge rules install
mozyo-bridge rules status

Scaffold project routers:

mozyo-bridge scaffold apply asana
mozyo-bridge scaffold apply asana --target /path/to/project
mozyo-bridge scaffold apply redmine --target /path/to/project
mozyo-bridge scaffold apply redmine-governed --target /path/to/project
mozyo-bridge scaffold apply redmine-rails --target /path/to/project
mozyo-bridge scaffold apply none --target /path/to/project

v0.3: 旧 scaffold の rules subcommand は廃止されました。生成は scaffold apply、差分確認は scaffold diff を使います。互換 alias はありません。

When --target or --repo is omitted, scaffold writes to the current working directory. Use an explicit target to scaffold a different directory.

This creates:

• AGENTS.md
• CLAUDE.md
• .mozyo-bridge/scaffold.json

The generated routers point to ${MOZYO_BRIDGE_HOME:-~/.mozyo_bridge}/rules/presets/<preset>/agent-workflow.md. They do not copy the full development flow into each repository.

Preview the diff before applying:

mozyo-bridge scaffold diff asana --target /path/to/project

scaffold diff prints a unified diff of what scaffold apply would write. Exit code 0 when the workspace already matches the rendered output, 1 when at least one file would change. Standard UX is diff -> apply.

Existing AGENTS.md or CLAUDE.md files are not overwritten by default. Use --dry-run on scaffold apply to print the would-write paths, --backup to replace with backups, or --force to replace without backups.

Project-Local Additions (preserved across re-sync)

Scaffold-generated AGENTS.md / CLAUDE.md ships a marker pair:

<!-- mozyo-bridge:project-local-additions:begin -->
... ここに project-local layer を書く ...
<!-- mozyo-bridge:project-local-additions:end -->

mozyo-bridge scaffold apply と mozyo-bridge scaffold diff は、target repo の AGENTS.md / CLAUDE.md にこのマーカー pair が含まれている場合、マーカー間の本文を rendered template 側に substitute します。つまり、operator がマーカー間に書いた project-local layer (Rails / Ruby version、Presenter / YAML 慣習、read-only documentation directory、DB / test 必須環境変数、docs catalog / active-doc resolver / nagger ガバナンス、role-boundary override、private internal tooling など) は scaffold re-sync で消えません。マーカーの 外 の内容は scaffold base の正本扱いで、再生成で上書きされます。

re-sync の標準フロー:

1. 初回 mozyo-bridge scaffold apply <preset> --target /path/to/repo 後、AGENTS.md / CLAUDE.md の Project-Local Additions マーカー間に project-local layer 本文を書く。
2. 以降の re-sync では mozyo-bridge scaffold diff <preset> --target /path/to/repo を走らせる。マーカー間に書いた project-local 追記は rendered 側に保持されるため、diff は scaffold base 側の更新点 (preset version label、generator 行、preset 本文の参照など) だけを表示する。
3. mozyo-bridge scaffold apply <preset> --target /path/to/repo --backup で apply する。--backup は安全網として古い AGENTS.md / CLAUDE.md を AGENTS.md.bak.<timestamp> に退避する。マーカー preservation は同じく適用される。
4. --force も marker preservation の対象。バックアップ無しの上書きでも、マーカー 内 の project-local 追記は保持される。マーカー 外 に書いた追記 (古い scaffold で marker pair が無い時代の追記) は上書きされる。
5. legacy scaffold (router にマーカー pair が無い古い AGENTS.md / CLAUDE.md) は preservation 対象外。再生成前にマーカー pair を含む新しい router へ移行し、project-local layer をマーカー 内 に移すと、以降の re-sync は (3)–(4) のとおり機械的に保持される。

redmine-rails preset には Project-Local Layer (do not erase on scaffold apply) / Project-Local Layer Apply Discipline / Active-Doc Resolver Concept / Dangerous DB / Test Command Category / Presenter / YAML / Doc-Readonly Category / Project Tooling / Local Skill / Role-Boundary Override Category セクションがあり、project-local layer に何を書くべきかをカテゴリで列挙しています。具体的な path / command / 環境変数は preset 側に焼き込まれないので、別 repo に apply しても誤誘導になりません。

redmine-governed: non-Rails guardrail governance package

redmine-governed preset は redmine を extends する full governance 向けの opt-in preset です。Rails 固有の app path、DB command、Presenter / YAML 慣習を含めず、Redmine Issue / Journal gate、docs catalog skeleton、LLM rule authoring、Claude Nagger skeleton、tmux UI artifact を配布します。

mozyo-bridge scaffold apply redmine-governed --target /path/to/repo

非 Rails project で guardrail docs / catalog / runtime guardrail artifact まで導入したい場合は、redmine-rails-governed ではなくこちらを使います。

redmine-rails-governed: full guardrail governance package

redmine-rails-governed preset は redmine-rails を extends する full governance 向けの opt-in preset です。redmine-rails の薄い preset では project-local layer に書くことが推奨されていた強い文言を preset 側で正本にし、scaffold 時に target repo の .mozyo-bridge/ 配下に repo-local rules / catalog skeleton / runtime guardrail artifacts を配布します。docs catalog tooling は target repo に Python source として置かず、mozyo-bridge docs ... CLI として package 側から実行します。

gate schema、agent role、Codex direct edit gate、完了条件は redmine-rails-governed/agent-workflow.md 自体を正本にします。AGENTS.md / CLAUDE.md が読む入口と実行契約を分けないことで、LLM が読むべき正本を 1 本に保ちます。

mozyo-bridge scaffold apply redmine-rails-governed --target /path/to/repo

apply すると、router 一式に加えて以下が target repo に書き込まれます。

• .mozyo-bridge/rules/llm_rule_authoring.md — LLM 向け規約文書の作成・分離・構造化の正本。
• .mozyo-bridge/rules/docs_catalog_governance.yaml — docs catalog、resolver、generator、impact check の統治規約。
• .mozyo-bridge/docs/catalog.yaml.example — 初期 catalog skeleton。target 側で catalog.yaml にコピーして埋める。
• docs catalog tooling は mozyo-bridge package に同梱されており、mozyo-bridge docs validate / resolve / generate-file-conventions / audit-impact で呼び出します。target repo には Python source を vendor copy しません。

これらは scaffold preset 側を正本とし、mozyo-bridge scaffold status が drift を検出します。target 側で個別に編集したい場合は preset へ upstream し、mozyo-bridge scaffold apply --backup で再配布してください。configured catalog (catalog.yaml) は scaffold が触らないため、project 固有 docs / file_conventions を埋めても上書きされません。mozyo-bridge scaffold apply --backup は shipped artifacts も含めて pre-existing files を .bak.<timestamp> に退避します。

catalog には任意 field coverage_roots を定義できます。指定した repo-relative path が mozyo-bridge docs validate --check-file-coverage の走査対象になり、CLI --coverage-root が無い場合の default として使われます。CLI が指定されたときは CLI 側が優先されます。missing root は notice: として印字され exit code には影響しません。scaffold status の出力では manifest 追跡対象を tracked files: セクションで表示します (router 2 件 + governed が追加した repo-local artifacts も同じセクションに並びます)。

scaffold には Claude Nagger 設定 skeleton (.claude-nagger/{config,command_conventions,mcp_conventions}.yaml.example + .gitignore) と tmux agent window 用の UI snippet (.mozyo-bridge/tmux/agent-ui.conf) も default-on で同梱されます。これらは agent 誤動作を減らすための実行時 guardrail として扱い、doctor の claude_nagger セクションと tmux.artifact 行で導入状態を確認できます。Claude Nagger を運用するには .claude-nagger/config.yaml.example を config.yaml にコピーして customise してください。tmux UI を有効化したい operator は source-file <repo>/.mozyo-bridge/tmux/agent-ui.conf を ~/.tmux.conf などに追記します (scaffold は host 設定を一切変更しません)。導入したくない project は scaffold apply --skip-nagger / --skip-tmux-ui で opt-out できます。スキップした category は manifest にも記録されず、scaffold status は引き続き clean を返します。

redmine-rails を選んだ project が後から full governance に乗り換える場合は、mozyo-bridge scaffold apply redmine-rails-governed --target . --backup で切り替えられます。

After upgrading mozyo-bridge (e.g. pipx upgrade mozyo-bridge && mozyo-bridge rules install), check each scaffolded project for drift:

mozyo-bridge scaffold status                       # implicit target = cwd
mozyo-bridge scaffold status --target /path/to/proj
mozyo-bridge scaffold status --target /path/to/proj --json

The command compares the project's .mozyo-bridge/scaffold.json against the installed central preset (content hash, not only the version label) and the on-disk AGENTS.md / CLAUDE.md. Exit code is non-zero when central preset content drifted, when a router was modified locally, when the central preset is missing, or when the manifest is missing. Use mozyo-bridge scaffold apply <preset> --backup to regenerate routers and accept the new central preset content.

Dev Container / ephemeral home: repo-local rules mode

Dev Container, Codespace, and similar workspaces do not persist ~/.mozyo_bridge across container rebuilds, which leaves agents without a guardrail store the first time they start a new session. The repo-local mode keeps the preset inside the target repo so agents can read it without a persistent user home:

# 1. Install the preset into <repo>/.mozyo-bridge/rules/presets/<preset>/
mozyo-bridge rules install --repo-local /path/to/repo
mozyo-bridge rules status  --repo-local /path/to/repo

# 2. Scaffold routers + manifest in repo-local mode.
mozyo-bridge scaffold apply <preset> --target /path/to/repo --repo-local
mozyo-bridge scaffold diff  <preset> --target /path/to/repo --repo-local

# 3. Status auto-detects the mode from .mozyo-bridge/scaffold.json.
mozyo-bridge scaffold status --target /path/to/repo

In repo-local mode the generated routers point at the repo-relative path .mozyo-bridge/rules/presets/<preset>/agent-workflow.md (no ${MOZYO_BRIDGE_HOME:...} expansion needed) and the manifest records mode: "repo-local". --home and --repo-local are mutually exclusive on every command that accepts both; passing both is rejected before any filesystem work. Default behavior without --repo-local is unchanged: central mode under ${MOZYO_BRIDGE_HOME:-~/.mozyo_bridge} and mode: "central" in the manifest. Switching a repo between modes requires re-running both rules install and scaffold apply under the new mode so the store and the manifest stay aligned.

Detailed scaffold semantics (preset registry, manifest, apply/diff/status behavior) live in vibes/docs/logics/scaffold-rules.md.

Notification Commands

agent 間 handoff / reply の standard path は高レベル primitive mozyo-bridge handoff send / mozyo-bridge handoff reply (上位 alias mozyo-bridge reply) です。primitive が receiver pane resolve / deterministic Layer B preflight / marker-prefixed notification の typing / Enter 発行 (--mode queue-enter default、--mode standard strict fallback、--mode pending で typing のみ) をまとめて行います。caller は mozyo-bridge read + mozyo-bridge message の shell-level 組み立てを行いません。

Asana driven のレビュー依頼:

mozyo-bridge handoff send \
  --to codex \
  --source asana \
  --task-id 1214760548032221 \
  --comment-id 1214890105221452 \
  --kind review_request \
  --summary "branch X の review 依頼"

Asana driven の reply (kind は省略すると reply):

mozyo-bridge handoff reply \
  --to claude \
  --source asana \
  --task-id 1214760548032221 \
  --comment-id 1214890105221452 \
  --summary "audit OK"

# 上位 alias
mozyo-bridge reply \
  --to claude \
  --source asana \
  --task-id 1214760548032221 \
  --comment-id 1214890105221452

Redmine driven の review handoff:

mozyo-bridge handoff send \
  --to codex \
  --source redmine \
  --issue 9020 \
  --journal 46005 \
  --kind review_request \
  --summary "commit f7b0398dc"

notify-* wrappers は handoff send を内部 routing する Redmine 互換 entrypoint として残ります。新規 caller は handoff primitive を直接使うほうが durable record に明示的な --kind ラベルが残るため推奨ですが、既存運用は引き続き動作します。

# Redmine 互換 wrapper (内部で handoff primitive を呼ぶ)
mozyo-bridge notify-codex-review \
  --issue 9020 \
  --journal 46005 \
  --commit f7b0398dc

mozyo-bridge notify-claude-review-result \
  --issue 9020 \
  --journal 46007 \
  --commit f7b0398dc

mozyo-bridge notify-codex \
  --issue 9020 \
  --journal 46005 \
  --type design_consultation

mozyo-bridge notify-claude \
  --issue 9020 \
  --journal 46007 \
  --type design_consultation_result

notify-*-legacy-task (.agent_handoff/tasks.yaml queue 経由) は retired-queue cleanup wrapper であり、handoff primitive を経由しません。新規 notification には使いません。

Safety

• Redmine journal を必ず先に作る。
• notify-* には --issue と --journal を渡す。
• pane message の内容だけで作業開始・完了判断をしない。
• 受信側は通知を見たら Redmine gate を確認してから動く。
• agent pane handoff (mozyo-bridge handoff send / handoff reply / notify-* 標準 variants で Claude / Codex pane を target にする送信) の v0.4 normative default は --mode queue-enter。Claude / Codex agent pane 限定で、--force 不可。typing 前に deterministic preflight が走り、いずれかが false なら send-keys -l を発行する前に blocked で die する:
  • explicit --target を渡す場合は receiver 自身の tmux window 配下のみ許容 (Reason: invalid_args)
  • target pane は sender と同じ tmux session にあること (= mozyo session 内から実行) (Reason: invalid_args)
  • target pane は所属 window の active split であること (Reason: invalid_args)
  • foreground process が receiver の allowlist にマッチすること (Reason: target_not_agent): literal claude (receiver=claude) / literal codex (receiver=codex) は strong identity、literal node および versioned native binary basename は Claude Code / Codex CLI どちらも採るため weak identity (両 receiver で admit、cross-binding 防御は window-name binding + operator 規律に retreat)。 すべて pass した場合、marker 観測ありで sent / ok、marker 未観測でも Enter を発行して sent / queue_enter を durable record に残す。default rail の promise は strong preflight 付き practical queued submission であり、confirmed landing ではない。受信側は引き続き Asana task comment / Redmine journal を正本として読む。
• strict explicit fallback は mozyo-bridge handoff send --mode standard (および mozyo-bridge message --submit 標準動作)。短い marker を送信文へ付与し、target pane 上で marker を確認できた場合だけ Enter を送る。確認できない場合は入力欄を C-u で消し、Enter を送らず blocked / marker_timeout で失敗する (fail-closed)。strict landing observation が必要な送信 (regression check / brand-new pane で queue-pickup 確率が未確認 / observability test / 厳格な landing evidence が監査要件) または default scope 外 (mozyo-bridge message / non-agent pane) のときに明示的に選ぶ。v0.4 で default ではなくなったが contract からは削除しない。挙動は v0.1 以降一切変更しない。
• どちらの rail を使った場合でも durable record (Asana task comment / Redmine journal) が正本。pane notification は pointer。詳細・state machine 全体・例外条件は vibes/docs/logics/tmux-send-safety-contract.md の ## Default Delivery Promise (v0.4) / ## Queue-Enter Default Rail 節を参照。

Legacy Queue

通常運用では以下を使いません。

• read-next --wait
• Stop hook による handoff queue 待機
• notify-* --task-id

.agent_handoff/tasks.json は retired queue の棚卸し用であり、standard notification fallback ではありません。退役前 queue の棚卸しだけ、専用コマンドを使います。

mozyo-bridge notify-codex-legacy-task \
  --issue 9020 \
  --task-id legacy-task \
  --type review_request

Utility Commands

mozyo-bridge read / message / type / keys は operator / debug 用の低レベル primitive です。standard な agent 間 handoff / reply の代替には使いません (それは上の "Notification Commands" の mozyo-bridge handoff send/reply を使います)。status / doctor の出力は durable Asana / Redmine anchor が利用可能なときに receiver state / task state の推測 source として使いません — anchor を直接読みます。

pane の内容を読む (operator inspection):

mozyo-bridge read codex 30

ad-hoc operator 会話を送る (handoff/reply ではない):

mozyo-bridge message codex '確認してください'

診断:

mozyo-bridge doctor

message / keys は送信前に read が必要です。これは誤送信を減らすためのガードです。これらは正規 handoff/reply 経路ではないため、mozyo-bridge handoff send / handoff reply のような durable anchor を引数化する structured outcome は emit しません。例外: per-preset Retry Path Checklist で operator/debug fallback として明記された --no-submit retry path のみ、mozyo-bridge read <agent> + mozyo-bridge message <agent> "<resubmit text>" --no-submit --attempt N を operator 経路として使えます (per-preset cap 3 回)。

Documentation Map

• README.md: install/bootstrap entrypoint, core commands, and safety summary. Start here; run doctor + instruction doctor first.
• vibes/docs/logics/bootstrap.md: detailed LLM-first stage-order reference, FAQ, and troubleshooting. Strict stage order from a clean machine through a verified scaffold (install → rules → skill → scaffold → doctor → isolated smoke), plus instruction doctor failure recovery. Follow it from the README Quick Start when a step fails or you need the full sequence — it is no longer the first doc to read.
• vibes/docs/rules/agent-workflow.md: AI agent work rules for this repository.
• vibes/docs/specs/project-map.md: repository structure and source-of-truth routing.
• vibes/docs/logics/skill-distribution.md: Claude/Codex skill layout and install logic.
• vibes/docs/logics/scaffold-rules.md: scaffold preset registry, manifest contract, and YAML registry governance (CLI surface is scaffold apply / scaffold diff / scaffold status).
• vibes/docs/logics/release-flow.md: release and verification gates.
• vibes/docs/logics/turnkey-e2e-acceptance.md: final destructive acceptance test using a published TestPyPI / PyPI install. Separate from Beta Tester Install smoke and run only on a clean git worktree.
• skills/mozyo-bridge-agent/references/: compact runtime references consumed by the shared agent skill.

Tests

python3 -m unittest discover -s tests -v

実 tmux を使う smoke test:

python3 smoke/real_tmux_notify_smoke.py

smoke test はローカル tmux server に依存するため、通常の unit test には含めません。

Use vibes/docs/logics/release-flow.md for the full release verification route.

Release

Build locally:

python3 -m pip install build
python3 -m build

Publishing is intended to run through GitHub Actions and PyPI Trusted Publishing. The local .env / .pypirc path should only be used for temporary release rehearsal, not as the normal production publishing path.

License

MIT