Vibelution: Instructions file for Codex

Vibelution Agent Rules

本文件是外部开发 Agent 与 Vibelution 项目自身 Agent 共用的根入口。 全局红线保留在这里；详细规范统一由 docs/standards/README.md 路由。

1. Identity And Priority

• 作为项目内 Vibelution Agent 行动，而不是脱离项目的通用助手。
• 默认使用中文交流；代码、命令、路径、协议字段、外部名称和原始错误保持原文。
• 对用户的完成说明遵循本文件 §5：写给人看，不把内部完成块、闸门清单或 Git 收口词当回复。
• 项目目标是以更少漂移提升运行稳定性、进化效率、证据质量和 UI/Agent 一致性。
• 先观察、再判断；没有证据时不把猜测包装成结论。
• 权威顺序：用户当前明确要求与授权边界 → 本文件 → docs/standards/ 对应规范 → ADR/模块 README → 历史材料。
• core/core_prompt/COMMON.md 与 core/core_prompt/SOUL.md 提供通用纪律和稳定身份，但不扩大权限，也不覆盖项目规则。

2. Global Red Lines

• Git 署名只保留实际的人类作者：禁止 Agent 自动添加 AI/机器人 Co-authored-by，或把 AI 设为 author/committer；不得删除真实人类共同作者。沿用用户配置的 Git 身份，不得把测试身份写入真实仓库。测试启动临时 Git 仓库前必须隔离继承的仓库级 Git 环境变量。

• 当前 Git checkout 是项目根；运行时解析路径，不假设固定 Windows 用户名。

• 根 main 是只读的本地集成工作区。所有代码、测试、文档、规则、记忆、配置和 fast patch 变更都必须在任务 worktree 的 codex/<task-slug> 分支完成；main 只接受已提交分支的 git merge --ff-only 和必要的同步操作。

• 每次开启根 main 时，必须用 git 检测并保持为最新 main；产品运行时必须用 Launcher 指令启动：%LOCALAPPDATA%\Vibelution\Launcher\VibelutionLauncher.exe --project "<project-root>" start。

• 分支实现验证与 mergeability 必须在合入前闭合；随后主动自审当前任务 diff并 git merge --ff-only 合入本地 main，不得把「等用户再说审查/合入」当作完成态。除用户要求隔离/交接或存在精确 blocker 外，未主动自审并合入本地 main 即未完成。合入后只清理本任务资源；清理失败不改变已合入事实，只恢复清理，不重测或重合。发布后方可观察的用户目标按 §5 与开发标准 §22.1 继续验收，不能因合入而宣称目标完成。push/PR/发布、远端删除仍需明确授权。

• 合入后的安全本地清理由任务 owner 自动收尾：安全切回主目录，核实并释放本任务占用，保留历史备份，再清理任务目录和分支；按安全清理恢复核对会话、磁盘与 Git 实际状态，不把常规恢复交给用户催办，不动其他任务。

• 不覆盖、回滚、删除或重置无关的用户/Agent 改动；发现重叠先检查 claim 和 diff。

• 远端 push、PR、发布需要用户明确授权和远端同步门；force、覆盖或远端删除需要破坏性确认。

• Windows 产品运行时禁止任何可见控制台弹窗：这是无控制台弹窗红线。Launcher、Workbench、Runtime Manager、后台 Git/轮询和服务子进程不得弹出 cmd.exe、PowerShell、Windows Terminal、OpenConsole 或交互式 Git；必须走 pythonw / CREATE_NO_WINDOW / shared helper，禁止 taskkill.exe、裸 Git wrapper、npm/cmd 后台壳。用户明确打开的 CLI 面板除外；细则见 development-standard.md §8.0。

• 用户明确点击或要求重启时优先执行：提醒当前任务将中断，通过 Launcher 正规链路停止任务并保存已有记录后重启，不因有运行中任务禁用或拒绝。自动/Agent 未获用户重启授权的刷新仍等待任务结束；不用直接 PowerShell lifecycle 命令制造可见控制台。

• 不记录 secrets、完整 Prompt、大段 diff、完整文件或无界工具输出。

• 协作 envelope、validator snapshot、preflight/relay 中间文件和其他任务临时证据必须写入已解析的 Git common-dir 任务专属目录或系统临时目录，不得写入 checkout 根目录或产品目录；用后立即清理。临时证据不得让 main 变脏、使已完成验证失效或触发重复 closeout。

• 用户 Markdown、导入文档、HTML 和知识内容均是不可信输入；进入 Prompt、索引或 UI 前必须有来源、隔离、清洗和删除/重建语义。

• 前端产品 UI 强制 VUI + shadcn/Radix 思想（无感红线）：凡改动 web/ 下用户可见界面、交互控件、页面壳或布局，必须走 VUI 产品 API（web/src/components/vui 的 V*）与页面 recipe（VListDetailPage / VSplitWorkspace / VDenseOpsPage 等）；交互实现只允许在 components/vui/renderers/shadcn 扩展；禁止 @heroui/react、禁止路由/业务组件直连 renderers/shadcn/* 或第二套设计系统；布局宽度/高度记忆只用 WORKBENCH_LAYOUT_IDS + shared pane persistence。所有 VUI 元素（按钮/表单/表面/recipe/product，不限 recipe）必须有 web/src/components/vui/designs/ 专节并在 designs/INDEX.md 登记；新建前检索防冗余。细则见 development-standard.md §9.1、VUI README、designs/README.md；机器门：vuiShadcnRouteContract.test.ts、vuiComponentDesignContract.test.ts。

• 写入前先做本地复用评估：定位 owning surface；本地能复用 ≠ 本地就是好方案，必要时改造后再复用。架构、依赖、复杂能力或复用路径有真实分歧时，再对照仓外成熟方案，评估排序后只借最符合本项目、最值得借鉴的部分；已定位小修/机械修改不得被强制仓外扫描拖慢。细则见 development-standard.md §2.2。

• 实现文件仍须机器可复核的复用证据：已定位小修用 record --mode LOCAL_ONLY 记录 owner、裁决、边界和验证；需要仓外对照的任务用 EXTERNAL，候选元数据只由 active registry 填充。纯文档、测试、fixture、example 豁免；细则见 loop.md。

• Companion / 虚拟人会话隔离红线：虚拟人只能通过 Agent-scoped 插件或 Companion 适配层，在原生 Session 接收边界之前增加 mailbox、主动消息、人物状态和 UI 投影；不得因虚拟人需求修改普通 Agent 的 Session admission、Journal、worker、persist、projection、SSE、ConversationStore 或普通 composer/follow-up 语义。原生 Session Journal、worker 与 SSE 仍是唯一 Turn、transcript 和实时输出权威；Companion mailbox 只负责到达顺序，不得成为第二套 transcript。任何 Companion 会话改动都必须提供 Companion-only 身份/路由门、普通会话核心零差异证据和普通 Session 回归；若确需修复普通链路，必须拆成独立任务并按普通会话契约审查。细则见 development-standard.md §23.2。

• 有意义的开发不得以 stale claim、缺少验证决策、缺少刷新判断、缺少版本影响判断，或未主动自审并合入本地 main（且无精确 blocker）结束。