Polaris: Instructions file for Claude Code

CLAUDE.md

主线研发（用户决定，2026-10-20）

所有源码修改与提交直接在主仓 main 进行，不再创建开发分支或开发 worktree。已存在的冻结副本只读保留证据；测试与审计资料继续放在 ~/.polaris/。

本文件用于指导在本仓库工作的 AI 编码代理。仅保留可执行、可验证的技术约束。

必用MCP和Skill: 充分利用codegraph MCP和superpowers，必要时需要使用Playwright来真实跑测试和审计。

-1) 强制工具链：RTK + CodeGraph + Caveman

• RTK：每条 shell 命令及每个 chained segment 都必须以 rtk 开头。优先使用 RTK 原生命令；无对应命令时使用 rtk proxy <command>。裸 shell 命令只允许用于明确的 RTK 故障诊断。
• CodeGraph：源码发现、架构/调用链/影响分析、代码审查及修改前上下文必须先调用 mcp__codegraph__codegraph_explore。返回源码视为已读，禁止再用 rg/reader 重复读取；只有 CodeGraph 未覆盖、未索引或明确不可用时，才允许使用 RTK fallback，并记录原因。
• Caveman：默认启用 caveman 的 full 模式，压缩过程更新与结果，删除重复叙述和无关日志，但必须保留精确技术名、错误文本、命令、验证数字、风险与未完成门禁。安全警告、不可逆操作和可能产生歧义的多步流程恢复完整表达。
• 三者必须共同使用，不能用其中一个替代另两个。标准顺序：加载适用 Skill -> CodeGraph 定位/审计 -> RTK 执行与验证 -> Caveman 压缩汇报。

0) 后端权威入口（2026-03-22）

• 用户事件降噪：成功的 stage/task/worker 心跳仅用于保活与审计，禁止刷入普通“最近事件”或重复通知。展示过滤必须在窗口截取之前；不删底层事实，不隐藏心跳失败/告警、阶段切换、工具结果或交付进展。仅有保活或当前窗口缺少调用证据，不能宣称模型从未执行；前端验收需真实 runtime.v2 推送、无 reload/产品轮询。
• 对于任何 src/backend 任务，必须先读 src/backend/AGENTS.md。
• 统一架构执行标准入口：src/backend/docs/AGENT_ARCHITECTURE_STANDARD.md。
• 后端强制规则：Cell 开发先复用已有 Cell 公开能力；所有新开发必须基于 KernelOne 底座能力与契约链路。
• 若本文件与 src/backend/AGENTS.md 或 src/backend/docs/AGENT_ARCHITECTURE_STANDARD.md 存在冲突，以后两者为准。

当前工程主线

1. 新工程运行的唯一 owner 是现有 roles.runtime.public.engineering_service.EngineeringRunService。HTTP、CLI、UI、取消、恢复与错误路径共用该服务，不新增 Cell、任务表、ledger 或第二 controller。
2. 默认 workflow=direct，Director 读取目标、调用工具、根据真实结果继续工作；PM/Chief Engineer 按需只读咨询。显式 workflow=collaborative 才执行 PM、Chief Engineer、Director 协作；未调用角色显示 not_called。咨询一层返回，不递归派生总控；讨论不创建工程 run。
3. PM/CE 使用可读文本提供规划、设计或审阅。新运行不要求 PM 合同、CE portfolio/blueprint、handoff/hash、OBL/covers 图、semantic patch、Task Market、JobToken/DEO/Run Ledger 旧链准入，也不受旧一 turn 一 batch 规则约束。普通编译/测试失败回到同一 Director，不自动 deterministic repair 或重启规划。
4. 工具授权来自 host 持久化且不可由模型扩大的 PermissionScope、当前 profile、预算与 deadline；显式空权限保持为空。归一化后仍须检查真实路径/symlink/允许根，经 KFS 读写和 OS/process sandbox 执行命令；不支持 containment 时明确拒绝，禁止裸跑。PM/CE/QA 默认只读，同 workspace 仅一个源码写入者。
5. 唯一工程事实记录是 <workspace>/.polaris/runtime/engineering/sessions.sqlite3，保存运行、事件、真实工具观察和验证；新运行不写旧 TaskBoard/TaskMarket/Run Ledger/role-session 镜像。保留 runtime.v2/Nats-JetStream、ContextOS 最终 provider request、UTF-8、实例 workspace 绑定与 storage 单根。
6. 角色回复结束与 completed 不等于 accepted。实际检查必须绑定当前源码；用户已声明检查必须保留，未声明时由 Director 结合实际工程选择并实际执行验证。空检查、模型自报、快照条数或 QA 文本不得冒充通过；任务要求的独立 QA 必须审查同一当前候选，拒绝后继续同一任务。
7. 恢复使用原身份、workspace、原始权限与 deadline，并重新校验当前 host policy；保留失败、interrupted/UNKNOWN 和未知效果，不自动重放可能已执行的命令或写入。旧 ID 不升级为新 run；历史按 engine_version 只读，旧在途运行留在原冻结 owner，不在新进程恢复旧写入口。
8. 旧 Factory/RoleRuntimeService/execute_role_session/RoleExecutionKernel 写准入与自动 fallback 退役；历史解码器、只读查询与显式可选技术工具可保留，禁止据此声称历史源码已全部删除。旧规范仅解释旧记录，不能重新约束新运行。底层 hash 可用于证据/快照完整性，不能要求模型填写业务 hash。真实 HTTP 次数与费用仅用物理证据，未知保持 UNKNOWN。