Polaris: Instructions file for Claude Code

CLAUDE.md

本文件用于指导在本仓库工作的 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）

• 对于任何 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 存在冲突，以后两者为准。

0.0) 无人值守项目完成权威（强制）

• 项目完成身份必须精确绑定 (workspace, project_id, run_id, completion_contract_hash)；禁止按“最新 run”、路径猜测、跨 workspace 搜索或 caller 自报字段拼接完成事实。
• Chief Engineer 只拥有整个 PM task-set 的 typed completion contract；合同必须绑定 owner task、required artifact、verifier modality、canonical argv/cwd、entrypoint（或显式 N/A）和合同 hash。Director 只能无损传递该合同及 hash，不能缩减、改写或自行声明项目完成。
• PM 声明的 project_declared_entrypoint_targets 必须按 exact owner task 与其 target_files 交集投影到 CE authority carrier；不得依赖 CE 再次把同一路径标成 semantic_role=entrypoint 才保留入口。CE 可改写入口描述或建议命令，但只允许归一化到同 owner 唯一 PM entrypoint command；全局入口列表不得复制成其他 task 的 authority，缺失、跨 owner、歧义或越 scope 仍 fail-closed。
• factory.verification_guard 只消费 owner contract 并执行物理验证；artifact hash、依赖准备、build/test/lint、entrypoint 都必须形成按 obligation/owner/hash 绑定的 typed receipt。禁止信任 caller-supplied evidence、generic mapping receipt、TaskBoundary、stage gate、日志摘要或“磁盘看起来存在”；audit.evidence 只能保存审计副本，不能制造执行权威。
• orchestration.workflow_runtime 只拥有 durable convergence cursor：残差、依赖、attempt budget、action reservation、settlement 和终态；跨进程更新必须 CAS，effect 前必须先 reserve，崩溃重放必须复用 deterministic action id。禁止在 Factory、adapter、bench 或 Agent 中另藏重试循环/第二事实源。
• runtime.projection 是唯一可签发 completed_verified 的 owner。只有 exact completion contract 与全部 owner-sealed physical receipts 一致、无 missing/failed obligation 时才能完成；VerificationGuard、Director、QA、workflow runtime 和外部 Supervisor 都不得签发最终成功。
• 角色失败必须阶段局部恢复，禁止默认重跑整条 PM -> Chief Engineer -> Director：CE 输出/schema 失败只重试 chief_engineer_review，复用已提交 PM contract；Director/QA 普通失败必须由 workflow_orchestration durable cursor 生成 action/claim，携带完整 owner-sealed diagnostic，并通过 runtime.task_runtime 重开 exact numeric owner row，再执行 bounded edit/repair -> affected verifier。TaskMarket 迁移未完成时不得作为同任务完成动作的第二事实源。PM 仅在 PM contract 本身无效或被显式 supersede 时重跑；局部预算耗尽输出 model_ceiling/结构化 blocker，不自动升级上游。
• retry_phase=planning 必须优先解析到同 phase 内的 last_failed_stage/current_stage；若失败点是 chief_engineer_review，绝不能因 PM 与 CE 共用 planning phase 而固定选择 pm_planning。只有缺少 stage-local failure evidence 时才允许使用 phase 默认阶段。
• mutation_bypass_blocked 是 owner Director 的普通局部恢复态：只有 Director + materialize_changes 可保留同一 session、已提交合同、最终请求上下文、读取结果和失败 receipt，下一 turn 直接 edit/write 后只重跑受影响 verifier；禁止创建新 Director 规划会话或重启 PM/CE。该恢复必须有独立于自适应 extra-turn 的硬预算（当前最多 2 次 bypass）；耗尽后输出 director_quality_repair_stalled、model_ceiling、retry_scope=same_director_task_only 并停止 Provider 调用。inline_patch_escape_blocked 等权限/策略边界仍 fail-closed。
• Verifier 失败归因必须先从生成/编译产物反投影到 authored source，再执行 task write-scope：例如 Node traceback 的 tsconfig.compilerOptions.outDir/*.js 只有在显式 rootDir/outDir 可唯一解析且源文件真实存在时，才能归因到对应 .ts/.tsx/.mts/.cts；不得授权 Director 编辑 dist/ 等生成物，配置缺失/歧义时保持 fail-closed。语言分类必须有真实命令/异常锚点，禁止因临时路径包含 pytest 等子串把 Node/Go/Rust 失败误投影为 Python。归因成功后只回到 exact owner Director task，保留合同/上下文/失败 receipt，并只重跑 exact failed verifier。
• ContextOS control-plane 隔离审计必须区分弱自然语言名词与强 authority 标识：QA workspace-quality data-plane 中的通用 workspace 路径字段和 verifier metrics 文案允许出现在 prompt content，但作为 message metadata / structured projection key 仍必须拒绝；workspace_root、factory_run_id、job_token、capability token 等强标识无论位于何种非当前用户指令内容都必须 fail-closed。禁止 blanket 跳过 [UNTRUSTED_USER_MESSAGE]；taxonomy 变更必须以原始 final provider request 快照重放并证明合法 QA 上下文 PASS、真实 authority 泄漏仍 FAIL。
• Provider structured-output 出现对象/数组被额外 JSON 字符串化、或剩余 root members 被串入首个 object field 时，必须先由 roles.kernel 统一传输层执行 caller-schema-proven 归一化，禁止立刻消耗整角色重试。只允许有界 JSON container 解码与单层已知无效 escape 归一化；重建结果必须仅含 schema 声明字段、保持已结构化 sibling 完全不变并通过完整 JSON Schema，否则 fail-closed。每次适配必须写 schema_normalization_applied / schema_normalization_policy，不得把语义补全伪装成传输归一化。
• Director 局部 repair 的“进展”必须同时满足：authoritative write receipt 对应负责路径的真实 fingerprint 变化、required verifier 复跑、诊断或 missing target 净减少且不引入新诊断。纯读取、同内容写入、只改变诊断签名、等量换错或错误增多一律记为 stagnation；连续 2 次 stagnation 必须停止 Provider 调用，输出 director_quality_repair_stalled + model_ceiling，并保持 retry_scope=same_director_task_only、禁止回退 PM/CE。
• Director 局部 repair 的 attempt/coverage/log evidence 绝不能冒充 mutation evidence。确定性 repair 若只有 source_tool/coverage/失败或 no-op receipt、没有 authoritative write fingerprint，必须继续进入同一 owner Director 的 LLM edit；Node TAP not ok 等已有文件断言失败的最终请求必须携带单一 failure island、当前 UTF-8 目标内容，并强制产生 edit_file effect，禁止用 read_file/execute_command/自然语言响应满足修复轮。长 repair 必须续租原 TaskRuntime execution attempt，停止 heartbeat 后才 settlement；否则 deo_execution_attempt_heartbeat_failed/session_lease_expired 会把真实修复伪装成模型失败。
• Repair mutation receipt 必须同时具备：成功状态、mutation tool/operation、负责路径、before/after SHA-256（允许 create 的 before=file_absent），且 fingerprint 必须变化；缺路径、缺 hash、同 hash 或 heartbeat 曾失败均不得结算 completed。模块拆分后判断 scanner/tool 是否为平台默认实现，必须使用稳定 capability/包身份，禁止硬编码单一 __module__ 精确字符串；否则 _scan 等内部迁移会静默降级到无 typed issues 的旧路径。
• M10 只能修复已有诊断可证明的局部结构，不得为满足 delivery depth 偷造 placeholder tests、领域 class/function 或业务语义。缺 test artifact 必须归还其 PM/CE 声明 owner；缺 export 且 workspace 无既存声明/唯一重导出/编译器 suggestion 时必须 covered_unplannable，由同一 Director task 消费结构化 discrepancy 后 edit，禁止 deterministic invent 假绿。
• JavaScript missing-export repair 只接受显式 unresolved symbol + module/path 诊断，并且只能导出 workspace 已存在声明、class method facade 或重导出已存在 binding。普通 AssertionError/strictEqual/npm test 失败绝不能枚举测试 imports 后改写已导出的函数体，也不能从测试断言发明领域函数、常量或依赖；已导出 symbol 必须视为“非 export 缺陷”并保持零 mutation。DEO write_file/edit_file/edit_blocks 的 file-edit event 必须由真实 before/after 内容计算 patch，禁止硬编码空 patch 后把真实修改投影为 no_content_change。
• TaskRuntime 执行历史与 TaskBoundary 交付权威是独立轴。Factory 权威投影只能从已提交 PM stage event 的 immutable artifact binding 重验并取得 PM 合同任务，禁止从可变 tasks/plan.json/mirror 重建完成义务；PM contract IDs、TaskRuntime IDs、TaskBoundary IDs 归一化后集合必须完全一致。缺失合同任务、N/TASK-N 合同 alias collision、重复 runtime identity 必须 fail-closed，settlement/verifier 辅助行与 boundary 不得新增或污染交付义务。TaskRuntime 已终态 failed/cancelled 时，只有 canonical completed_verified TaskBoundary 同时具备 ledger append/content 坐标、evidence refs、零 missing/failed obligation，才可保留失败历史并授权进入 QA；pending/in_progress/blocked 或仅磁盘扫描永远不得放行。
• Factory stage 失败不得仅以“可能本地修复”为由占住 workspace lease。Director/QA local rework 只有在 durable completion cursor 已提交 owner action receipt、TaskRuntime 已保存同 action/claim/full diagnostic 且 exact owner row 已安全重开时才能 defer drain；单独 TaskMarket receipt、纯 metadata、伪 action ref、辅助 task、错 run/contract/task 一律不得授权。TaskRuntime 行重开后必须由 backend lifespan-owned Factory run driver 消费；HTTP Router 只能提交到该 driver，不得自行持有不可恢复的执行 task。启动恢复必须合并 RUNNING/RECOVERING runs 与 pending exact-row local-rework actions；仅把状态改成 pending 不能计作进展或成功。
• DEO 一旦把 member claim 为 EFFECT_STARTED，所有“物理执行前”的 policy/target drift 拒绝也必须先消费 one-use fence，再以 recovery + DEAD_LETTER 形成终态证据；禁止返回 denied 后把 claimed member 留在非终态。若 fence 消费或终态追加存在歧义，必须保留 reconciliation blocker，不得 abort 相关 contingency 或伪造成功。该规则保证局部 Director repair 可失败、可重排、可重试，但不永久卡住 Factory settlement。
• 运行时观察链不得复制 Durable TaskRuntime/Provider/Tool 全量证据。事实流与持久化快照保留完整 payload；runtime.v2/NATS/状态投影只能发送有界语义摘要、不可变 fact 坐标与可解析 evidence ref，默认单事件预算 64 KiB。高频事件只能按明确 canonical kind 触发 status refresh，并采用单任务 latest-wins 合并；禁止用模糊字符串匹配、每事件/每连接同步全量重建或对子树反复 JSON 序列化，避免 observer 反向拖死执行面。
• Factory HTTP/runtime.v2 状态合同不得内嵌完整 workspace validation、repair rounds、audit bundle 或长 provider/tool 输出；单 metadata value 超过状态预算时必须投影 json_bytes + durable_evidence ref，完整证据由 audit-bundle/ContextOS/ReceiptStore 读取。QA 已有 authoritative failed verdict 时，归因必须优先保留 qa_verdict_failed，不得用由该失败派生的 task_runtime_not_completed 遮蔽首因；这只改变归因优先级，不放宽完成门禁。
• model_ceiling 只能由 owner query 的最终请求快照、physical-attempt、Run Ledger settlement、provider health、repair coverage 和 residual 证据共同封存；禁止 caller 自报 attempt 数、预算或通用 JSON receipt 触发 terminal。未满足证据时必须 fail-closed 为非终态。
• 外层 Supervisor 只做项目级调度（启动、读取归因、推进/暂停/告警），不得进入 Run Ledger 成功条件。Bench 仅在 unit/type/architecture gates 全绿后作为稀缺验证；失败先产出唯一 residual/module attribution，再修 owner Cell，禁止无归因反复长跑。
• /tmp 只允许放可丢弃 scratch/worktree。bench 审计、最终 provider request 快照、缺陷 manifest、handoff 与可复核测试证据必须落在 ~/.polaris/bench_runs、~/.polaris/audit_archives 或仓内治理资产；不得把 /tmp 当唯一证据源。
• 首个 fresh isolated COMPLETED_VERIFIED 经验基线见 src/backend/docs/governance/UNATTENDED_COMPLETION_FIRST_PROOF_20260812.md。后续失败必须按 final provider request -> provider response -> tool lifecycle -> effect receipt/settlement -> TaskBoundary/TaskRuntime -> Run Ledger/QA -> Factory report 顺序动态定位唯一断边；未完成 owner 修复、focused tests 与平台 cascade 前禁止盲目重跑。单项目通过只允许推进下一个顺序项目，不能宣称 L1-L12 或 N-batch 封板。
• QA verdict 只能授权其精确审计的 Director delivery epoch：(task_id, director_run_id) 必须与该 task 最新 canonical TaskBoundary 完全一致。Run Ledger 必须保留历史 verdict，但只把当前 epoch 投影进 effective_gates；Factory 只能消费 effective_gates，raw gates 仅允许无 effective 投影的 legacy 兼容。Director-only retry 使旧 QA verdict 失效，但不得重跑 PM/CE；随后只重跑 QA/受影响 verifier。
• KFS 逻辑证据路径不能靠字符串或旧绝对路径猜测。审计 runtime/qa/*、receipt 或 ContextOS 文件前必须通过当前 workspace 的 storage-root resolver/有界文件清单定位实际 system runtime root；workspace 物理目录中看不到逻辑文件不等于证据丢失。缺失结论必须附 resolved roots 与 searched paths。
• runtime.v2/ContextOS 的正式 Factory 事件必须以结构化 result.status / ok / severity 判定成功或失败，禁止用消息子串作为更高权威。成功摘要会合法包含 error_code=none；若先用 /error/ 文本启发式分类，会把 PM/CE/Director 成功事件伪装成“异常闭环”。结构化成功必须压过文本启发式，结构化失败仍必须保持 error，并有正反回归测试。