pomaster 0.2.0 → 0.4.0

package/README.md

@@ -15,9 +15,10 @@ POMaster = State + Context + Transition + Evidence，在 Authority 与 Adaptive
 POMaster 的全部能力收敛在一条 CLI（`pomaster`）——八拍 Change Loop 的每一拍都有对应命令面。先给一张**命令全景**（机器钉版，与 `pomaster --help` 零漂移；`#` 分节注释仅人读）。第一次使用？直接看下面 [install → init → 第一个 Change](#1-安装) 的全流程。
 
 ```text
-# 0 BOOTSTRAP —— 建基线 / 速览 / 装眼睛 / 可移植性 / 自更新
+# 0 BOOTSTRAP —— 建基线 / 速览 / 可行动项 / 装眼睛 / 可移植性 / 自更新
 pomaster init
 pomaster status
+pomaster alerts
 pomaster doctor
 pomaster portability bootstrap/check
 pomaster update --check/--yes
@@ -41,7 +42,7 @@ pomaster record gate-run/claim
 
 # ⑥ RECONCILE —— delta 三方对账 / 投影视图 / 审计 / 例外台账
 pomaster reconcile --permit <PERMIT.*>
-pomaster view blueprint/task
+pomaster view blueprint/task/attention/decision
 pomaster audit blueprint/task
 pomaster ledger record/list
 
@@ -55,21 +56,24 @@ pomaster closeout <task-id>
 
 # 横切 —— 对象检视 / 图视图 / Discovery / Research / Eval / Catalog / 迁移 / 生产反馈 / 多 Agent / 执行身份
 pomaster resolve "<need>" [--hints ...]
+pomaster new-entity check <governed-id> [--need ...]
 pomaster inspect <governed-id>
 pomaster graph <governed-id> [--view impact]
-pomaster brainstorm start/status/promote
+pomaster brainstorm start/question-gate/status/promote
 pomaster research list/inspect
 pomaster eval --suite behavioral
 pomaster catalog status/explain/relock
 pomaster migrate trellis-spec --analyze --spec-root <dir>
 pomaster production band/evaluate/challenge/diagnose/metrics/self-improvement
-pomaster agents status
+pomaster agents status/dispatch-pack
 pomaster run <task>
 pomaster handoff <task> --to <role>
 pomaster session attach/refresh/list
 pomaster lock acquire/heartbeat/release/steal/list
 pomaster execution begin/end/list
 pomaster trace show/list
+# pomaster session（不带子命令）= 治理速览投影（SessionStart 注入源；≤10k 字符，恒 exit 0）
+# pomaster alerts（重入口轻提醒源）= 可行动项过滤器（干净=空输出，恒 exit 0）
 ```
 
 ### 1. 安装
@@ -95,23 +99,33 @@ pomaster init
 
 | 产物 | 作用 | 会被覆盖吗 |
 |---|---|---|
-| `.pomaster/state/truth-index.json` | Canonical State 唯一事实源（空账本起点） | 否（存在即跳过；损坏显式报错，绝不静默重建） |
+| `.pomaster/state/truth-index.json` | Canonical State 的唯一 root index（空账本起点；受其引用的 `truth/objects/**` 是 Canonical Truth 正文） | 否（存在即跳过；损坏显式报错，绝不静默重建） |
 | `.pomaster/state/authority.json` | Authority Map 骨架（默认登记 `BOOTSTRAP_OWNER`） | 否（人类加注的 owner 一律不动） |
 | `.pomaster/config.yaml` | 治理配置（人类可编辑） | 否（只在缺失时创建） |
-| `AGENTS.md` / `CLAUDE.md` | Agent 轻入口（profile + 状态速览 + 常用命令） | 仅带生成标记的（`CLAUDE.md` 通过 `@AGENTS.md` 导入共享） |
+| `AGENTS.md` / `CLAUDE.md` | Agent 重入口（profile + 状态速览 + 常用命令 + 重入口安装物锚点） | 仅带生成标记的（`CLAUDE.md` 通过 `@AGENTS.md` 导入共享） |
 
-**多平台适配器**：`AGENTS.md` 恒为唯一事实源；`--platforms claude,codex,cursor,qoder` 追加各平台的细指针适配器（`CLAUDE.md` / 根 `AGENTS.md` 即 codex 原生入口 / `.cursor/rules/pomaster.mdc` / `.qoder/rules/pomaster.md`，已存在一律不覆盖）；`--platforms none` 只建 AGENTS.md + 状态骨架。TTY 交互终端直接 `pomaster init` 会出复选清单（◉/◯ 空格勾选 / ↑↓ 移动 / 回车确认；raw 模式不可用时降级为编号输入）；`--json` 恒走确定性缺省（claude）。
+**目录宪法全树预铺**（Owner 裁定 2026-09-04，不分档级）：init 一次性建出 `.pomaster/` 目录宪法 §2 全树（state / truth/objects / evidence 三区 / executions / traces / runtime 四区 / discovery/scratchpads / memory/inbox / production 六区，41 目录 × 各带 README——含 09-04 Batch 1 增量 sources/ 来源权威边界平面 + Batch 2 增量 state/contexts/（Task Context Manifest 落盘位）与 evidence/observations/（感知回执 sidecar 分区）+ Batch 6 增量 baseline/（Project Engineering Baseline 四 lane 分区）与 specs/（Spec Workspace：hard/frontend、hard/backend、hard/stacks、acceptance、evidence）两棵播种子树）+ `.pomaster/layout.json` 机器清单（全目录 status=wired + activation_hint——什么样的项目/需求激活该平面由 AI 按项目复杂度自行判断，目录存在 ≠ 已激活）。目录树与入口形态/平台选择**完全无关**（B7 裁定：init 单一重入口，无模式旗标）；canonical 正文层为 `.pomaster/truth/objects/`，legacy `.pomaster/objects/` 在场会被显式告警（禁静默 merge/覆盖/迁移）。播种面语义（Batch 6）：`baseline/**` 与 `specs/**` 下的内容文件由 init 按种子清单 **seed-once-missing-only** 落盘——缺失才写、在座零触碰、播种件不带生成标记（项目自有可编辑，重跑 init 永不覆盖你的修改；AI 禁静默覆盖）。完整规范见 `.pomaster/layout.json` 与目录宪法文档。
+
+**重入口默认**（D13 修订，2026-09-03）：init 缺省生成重入口全套，让 Agent 一开会话就自动看到治理状态、按需自动触发命令卡——
+
+- **skills 命令卡库**：`/pomaster` 路由全景 + `pomaster-bootstrap` … `pomaster-runtime` 等 15 份命令卡，双镜像安装到 `.agents/skills/`（通用层——Codex / Cursor / Gemini CLI / GitHub Copilot / VS Code / Amp / Warp / OpenCode / Droid 等原生读取）与 `.claude/skills/`（Claude Code 必需位），两份逐字节一致、同指 `pomaster --help` 单一事实源；
+- **hooks 注入（claude）**：`.claude/settings.json` 合并式注册 SessionStart → `pomaster session`（治理速览投影，≤10,000 字符硬上限）与 UserPromptSubmit → `pomaster alerts`（可行动项过滤器，干净=空输出恒 exit 0）；既有 hooks（人类/Trellis 条目）一律保留，坏 JSON fail-closed 不覆盖；
+- **cursor/qoder**：加厚版 rules（命令卡 + Browser Eyes 展开进 `.cursor/rules/pomaster.mdc` / `.qoder/rules/pomaster.md`）。
+
+**多平台适配器**：`AGENTS.md` 恒为唯一事实源；`--platforms claude,codex,cursor,qoder` 追加各平台的适配器（`CLAUDE.md` / 根 `AGENTS.md` 即 codex 原生入口 / `.cursor/rules/pomaster.mdc` / `.qoder/rules/pomaster.md`，本包产物形态升级自动重写，人类异形内容一律不覆盖）；`--platforms none` 只建 AGENTS.md + 状态骨架。TTY 交互终端直接 `pomaster init` 会出复选清单（◉/◯ 空格勾选 / ↑↓ 移动 / 回车确认；raw 模式不可用时降级为编号输入）；`--json` 恒走确定性缺省（claude，重入口）。
+
+装好后 `pomaster session`（无子命令）就是 hook 看到的治理速览；`pomaster doctor` 会用 `heavy_entry_hooks` / `heavy_entry_skills` 探针核对重入口安装物（hooks 注册态 + 双镜像逐字节一致；未安装 → MISSING_CONFIGURATION 并指路重跑 `pomaster init`）。
 
 ### 3. init 之后该配置什么（config.yaml）
 
 ```yaml
 version: 1
-profile: LIGHT            # 治理档位：MINIMAL | LIGHT | STANDARD
+profile: LIGHT            # 治理档位（信息性人类偏好，A1 裁定：不进判卷）：MINIMAL | LIGHT | STANDARD
 triage:
   ttl_hours: 168          # triage 结果有效期，过期必须 re-triage
 ```
 
-**profile 三档怎么选**：
+**profile 三档怎么选**（信息性人类偏好——A1 裁定 2026-09-04：档位只影响呈现与偏好记录，不进任何 gate/permit 判卷、不决定激活；激活由 context compile 的 lane/role/capability 机制承担）：
 
 | 档位 | 适合 | 体感 |
 |---|---|---|
@@ -192,7 +206,7 @@ flowchart TB
 ## SOP 编排：项目生命周期五段式
 
 ```text
-0 BOOTSTRAP ──── init 扫描 / Authority Map / catalog-lock / 轻入口生成
+0 BOOTSTRAP ──── init 扫描 / Authority Map / catalog-lock / 重入口生成（skills/hooks）
                   （有原型→活体走查提五件套；存量项目→纳管已有 registry/spec/记忆）
 1 主循环 ─────── N 次 Change，每次跑下面的八拍 Loop（项目的日常形态）
 2 周期事件 ────── 全量对账 / 紧缩 / 经验入库 / catalog 升级 diff / 自托管基准
@@ -355,6 +369,7 @@ Spec、Task、Gate、Knowledge、Brainstorm……全部是这五个原语的派
 ## 哲学宪法（违者即是 bug）
 
 - Small Constitution：硬约束极少而精——不伪造事实、不越权、不静默冲突、不无证据宣称完成
+- Heavy Entry by Default（D13 修订 2026-09-03 + B7 裁定 2026-09-04）：入口即治理——init 默认安装 skills 库 + hooks 注入，Agent 开会话即见状态；单一重入口、无模式旗标；hook 注入内容永远是 Canonical State 的投影，不是第二事实源
 - No-op is elegant：没有必要的治理动作，零变化就是成功
 - Framework as Review Surface：框架约束好了的人，不需要读 AI 写的每一行代码——但前提是判卷器诚实，所以我们用对抗性用例持续攻击自己的 gate
 - Minimum Sufficient Governance：治理开销必须与变更风险成比例；小改动的体验是"几乎感觉不到 POMaster"

package/catalog/archetypes/archetype.frontend.error_taxonomy.json

@@ -3,10 +3,10 @@
   "kind": "archetype",
   "layer": "PATTERN",
   "title_zh": "前端错误分类",
-  "summary_zh": "前端错误九分型逐字闭包（PRD §21）：每型绑定呈现/重试/遥测/用户话术四语义位；浏览器原生信号只够两分，细分映射责任在 HTTP Client 适配层。",
+  "summary_zh": "前端错误十分型闭包（PRD §21 九分型 + Owner 2026-09-04 裁定补 CANCELED 第十分型）：每型绑定呈现/重试/遥测/用户话术四语义位；浏览器原生信号只够两分，细分映射责任在 HTTP Client 适配层。",
   "semantic": {
-    "responsibility": "把运行时错误归类为九分型闭包，驱动呈现/重试/遥测/话术四列的确定性处置",
-    "when_to_use": "任何触发 HTTP/异步调用的页面组契约错误处置面——错误到分型的映射在 HTTP Client 适配层完成（WHATWG fetch 原生只给 TypeError 与 HTTP status 两分，§21 九分型的映射责任不在浏览器）",
+    "responsibility": "把运行时错误归类为十分型闭包，驱动呈现/重试/遥测/话术四列的确定性处置",
+    "when_to_use": "任何触发 HTTP/异步调用的页面组契约错误处置面——错误到分型的映射在 HTTP Client 适配层完成（WHATWG fetch 原生只给 TypeError 与 HTTP status 两分，十分型的映射责任不在浏览器）",
     "when_not_to_use": "非错误态的加载/空态呈现；后端错误信封字段结构本身（v0.6.1 §44 Error Archetype 承载 type/title/status/detail/instance 等成员）"
   },
   "composition": {
@@ -57,6 +57,12 @@
       "telemetry": "timeout_event",
       "user_message": "请求超时，请重试"
     },
+    "CANCELED": {
+      "presentation_pattern": "cancelled_state_quiet_dismissal",
+      "retry_behavior": "never_retry_user_cancelled",
+      "telemetry": "cancel_event_aborted",
+      "user_message": "操作已取消"
+    },
     "OFFLINE": {
       "presentation_pattern": "offline_banner_persistent",
       "retry_behavior": "auto_resume_on_reconnect",
@@ -72,11 +78,13 @@
   },
   "constraints": [
     "浏览器原生信号只够两分：WHATWG fetch 网络失败 reject TypeError、HTTP 错误状态不 reject（查 Response.status）——TIMEOUT/OFFLINE/AUTHENTICATION 等细分全部依赖 client 适配层信号（axios code/AbortSignal/navigator.onLine/status 映射）",
-    "九分型映射责任在 HTTP Client Archetype 层而非浏览器",
+    "十分型映射责任在 HTTP Client Archetype 层而非浏览器",
+    "CANCELED 第十分型（Owner 2026-09-04 裁定）：axios ERR_CANCELED / fetch AbortError / TanStack cancelQueries 三源业界共识——用户主动取消绝不自动重试，呈现为安静取消态而非错误横幅（九分型缺位会把取消误归 UNKNOWN/TRANSPORT）",
+    "429 归重试处置（Owner 2026-09-04 裁定注记）：ofetch 默认重试列表含 409/429 视作传输层瞬时错误——429 不归 CONFLICT 分型，按 retryable 瞬时处置；409 仍归 CONFLICT（语义张力如实登记）",
     "RFC 9457 about:blank（未给出更具体类型时的缺省）与 UNKNOWN 同构"
   ],
   "x-research-anchors": {
-    "note": "【待 Owner 裁定·差异表 #8 两项】①是否补 CANCELED 第十分型（axios ERR_CANCELED/fetch AbortError/TanStack cancelQueries 三处业界共识，retry 语义绝不重试——九分型缺位会把取消误归 UNKNOWN/TRANSPORT）②429 归属（ofetch 默认重试列表含 409/429 视作传输层瞬时错误，与 CONFLICT 语义有张力）——本物料保持九分型不扩，待裁定后走词汇表式修订。WHATWG fetch TypeError/RFC 9457 成员空间/axios error codes 全表/ofetch 重试列表为规范与官方文档 2026-09-03 实抓",
+    "note": "【已裁定 2026-09-04·差异表 #8 两项】①补 CANCELED 第十分型（九→十）：axios ERR_CANCELED/fetch AbortError/TanStack cancelQueries 三处业界共识，retry 语义绝不重试——已入 categories 且四列绑定齐全；②429 归重试处置：ofetch 默认重试列表含 409/429 视作传输层瞬时错误，429 不归 CONFLICT、按 retryable 瞬时处置注记入 constraints。WHATWG fetch TypeError/RFC 9457 成员空间/axios error codes 全表/ofetch 重试列表为规范与官方文档 2026-09-03 实抓",
     "sources": [
       {
         "url": "https://fetch.spec.whatwg.org/",

package/catalog/archetypes/archetype.frontend.feature_oriented.json

@@ -44,7 +44,7 @@
     "自造新层（FSD：层语义已标准化，不推荐新增）"
   ],
   "x-research-anchors": {
-    "note": "【差异表 #4 部分差异】FSD 现行 7 层（Processes deprecated→有效 6 层）、无独立 API 层（api 是 segment）、widgets 无 PRD 对应、app 层 PRD 未纳入——四行声明随物料落位；import rule 严格向下与 Public API「contract+gate」定位（与 PRD §19 public_api_required 同构）为 feature-sliced.design 官方文档（v3 站点）2026-09-03 实抓",
+    "note": "【已裁定 2026-09-04·差异表 #4】FSD v2 现行映射采纳（六有效层 + Processes deprecated + api 是 segment）：上述 defaults 四行声明即裁定正文——FSD 现行 7 层（Processes deprecated→有效 6 层）、无独立 API 层（api 是各层 segment）、widgets 无 PRD 对应层（optional 位）、app 层为 FSD v2 新增有效层；import rule 严格向下与 Public API「contract+gate」定位（与 PRD §19 public_api_required 同构）为 feature-sliced.design 官方文档（v3 站点）2026-09-03 实抓",
     "sources": [
       {
         "url": "https://feature-sliced.design/docs/reference/layers",

package/catalog/archetypes/archetype.state.async_command.json

@@ -3,10 +3,10 @@
   "kind": "archetype",
   "layer": "PATTERN",
   "title_zh": "异步命令状态机",
-  "summary_zh": "以 XState v5 六概念（state/event/transition/guard/actor/input/output）承载的异步命令原型：命令参数经 input 进入，状态经 guarded transition 确定性转移，final state 产出 output；非法组合经 transition contract 显式声明（实现侧绑定 state.can() 守卫位）。",
+  "summary_zh": "以 XState v5 六概念（state/event/transition/guard/actor/input/output）承载的异步命令原型：命令参数经 input 进入，状态经 guarded transition 确定性转移，final state 产出 output；非法组合可检测——未声明 transition 不存在（XState v5 运行时静默忽略），state.can() 守卫为唯一预检位（Owner 2026-09-04 裁定差异表 #7）。",
   "semantic": {
     "responsibility": "把一次异步命令（提交/保存/执行）建模为显式状态机：idle/running/done|error 转移全部声明在案，guard 纯同步布尔",
-    "when_to_use": "命令的合法状态转移需要显式契约时（非法组合必须可表达为「未声明的 transition 不存在」）；多步骤异步编排（invoke/spawn actor）",
+    "when_to_use": "命令的合法状态转移需要显式契约时（非法组合可检测：「未声明的 transition 不存在」——XState v5 对未匹配事件静默忽略，state.can() 守卫预检）；多步骤异步编排（invoke/spawn actor）",
     "when_not_to_use": "远端取数缓存语义（STATE_ARCHETYPE.SERVER_QUERY）；无需显式转移契约的局部加载布尔"
   },
   "composition": {
@@ -33,10 +33,10 @@
   "forbidden": [
     "在 output 语义位放中途产物（output 仅到达 final state 时存在）",
     "直接改 context（immutable，仅 assign 更新）",
-    "断言未匹配事件会运行时报错（XState v5 现实是静默忽略+state.can() 为 false——非法组合的表达位是 transition contract 声明与 can() 守卫位）"
+    "断言未匹配事件会运行时报错（XState v5 现实是静默忽略+state.can() 为 false——非法组合的可检测位是 transition contract 声明与 can() 守卫预检，Owner 2026-09-04 裁定）"
   ],
   "x-research-anchors": {
-    "note": "【待 Owner 裁定·差异表 #7】PRD「Illegal Transition 必须可表达」在 XState v5（npm 5.32.6）无对应词形：未匹配/未启用事件=「no enabled transition → state does not change」静默忽略，state.can() 显式守卫为唯一查询位。本物料落 PRD 语义意图（非法组合经 transition contract 显式声明）+实现绑定注记 can() 守卫位；是否以治理层概念保留 Illegal Transition 词形待裁定。六概念词形与 guard 序列化命名推荐（reusability+visualization）均为 stately.ai 官方文档 2026-09-03 实抓",
+    "note": "【已裁定 2026-09-04·差异表 #7】Illegal Transition 不引入治理层词形：XState v5（npm 5.32.6）对未匹配/未启用事件按「no enabled transition → state does not change」静默忽略，state.can() 显式守卫为唯一预检位——PRD「非法组合必须可表达」由「可检测（transition contract 声明 + state.can() 守卫预检）」承载。六概念词形与 guard 序列化命名推荐（reusability+visualization）均为 stately.ai 官方文档 2026-09-03 实抓",
     "sources": [
       {
         "url": "https://stately.ai/docs/transitions",