@sema-agent/settings-schema 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,175 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 1.3.0 — hooks 域加员 `DirectoryAdded`(CC 2.1.219 新事件;`HooksConfig` 拒键病形修复)
+
+**`HOOK_EVENTS` 30 → 31:`POST_198_HOOK_EVENTS` **尾插** `DirectoryAdded`(1.2.0 三员声明序逐字节不动;重排 = BREAKING,
+免裁)。additive:既有 30 员的 matcher 字段 / owner / 输入形 / `hookSpecificOutput` 臂一字不动(FROZEN 1.2.0 全表字面量夹具钉,
+`test/hooks-directory-added-1.3.0.test.ts`,字面量独立誊自 bfbd140、非从现表派生——1.1.0/1.2.0 safety-merge-spec 夹具同律)。
+版号 minor = 加词(1.2.0 口径)。**
+
+### 病形(修前)
+
+`HooksConfig = z.record(HookEventName, …)` 键集**闭合**(设计如此:wire 上抓 typo)——用户 settings 里 `hooks.DirectoryAdded`
+(壳自 CC 2.1.219 起真会点亮的事件)在 1.2.0 下**整条** hooks 配置被拒(zod `Invalid enum value` at key);同时 `HookInput`
+union 无该臂、`HookEventName` 不收该词。壳认得、schema 不收——与 cli `hooksSchema218.test.ts` 建门帖所述「壳自己认得的
+输入形,壳自己的注册面不收」同形。
+
+### CC 真形(亲读镜像坐标,非按名推断)
+
+来源 = cli 树 `node_modules/@sema-agent/agent-types`(`@anthropic-ai/claude-agent-sdk@0.3.220` `sdk.d.ts` 的镜像,CC 2.1.220,
+与 0.3.219 逐字节同):
+
+- `hooks.d.ts:582-586` `DirectoryAddedHookInput = BaseHookInput & { hook_event_name:'DirectoryAdded'; directory:string;
+  source:'slash_command'|'register_repo_root' }`,`@since CC 2.1.219`(:574-575:目录经 `/add-dir` 或 repo-root 注册加入会话
+  工作集;cli `hooksConfigManager.ts:283-287` 文案:`directory` 为绝对路径)。
+- `hooks.d.ts:638` / `runtime.d.ts:111`:CC 序位于 `FileChanged` 与 `MessageDisplay` 之间;本包**尾插**——声明序非规范,
+  枚举当集合用(与 `MinTrust` 1.2.0 同律);夹具钉「1.2.0 三十员 = `HOOK_EVENTS` 逐字节前缀」。
+- `hooks.d.ts:14-17`:上游**无** `hookSpecificOutput` 臂——本版不加臂,测试钉「缺席」(非遗漏)。
+- **matcher 语义**:cli `src/utils/hooks.ts:1706-1760` `getMatchingHooks` 开关**无** `DirectoryAdded` 臂 → 落 `default` →
+  `matchQuery` 空 → 所有 matcher 组皆触发;`hooksConfigManager.ts` 该员亦无 `matcherMetadata` ⇒
+  `HOOK_EVENT_MATCHER_FIELD.DirectoryAdded = null`(与 CwdChanged / MessageDisplay 同族;entry 上写 `matcher` 仍是合法配置,
+  只是不被查阅)。
+- **owner = `shell`**(工作集在壳;`ENGINE_OWNED_HOOK_EVENTS` 9 员不动,`HOOK_EVENT_OWNER` 为派生表、自动含新员)。
+
+### API 形(全文)
+
+```ts
+export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"] as const; // 尾插
+export const DIRECTORY_ADDED_SOURCES = ["slash_command", "register_repo_root"] as const;
+export const DirectoryAddedHookInput = BaseHookInput.extend({
+  hook_event_name: z.literal("DirectoryAdded"),
+  directory: z.string(),
+  source: z.enum(DIRECTORY_ADDED_SOURCES),
+});
+export type DirectoryAddedHookInput = z.infer<typeof DirectoryAddedHookInput>;
+// HookInput union + 1 臂(尾);HOOK_EVENT_MATCHER_FIELD + 1 行(null);HookSpecificOutput 不动;HooksSlotSemantics 不动(非逐员表)
+```
+
+### 消费方可见(与 1.2.0 同一课:「表不动」≠「消费方零感知」)
+
+- **cli**(`package.json` 范围 `^1.2.0`,但 `package-lock.json:1261-1264` **钉 1.2.0**——`npm ci` 不会静默提到 1.3.0;
+  只有 `npm update` / 无锁重解析才命中):**运行时零影响**——cli `src/` 非测试文件对本包只 import `isAtLeast`
+  (`src/sema/settings/resolver.ts:28`),hook 符号零运行时消费(亲 grep)。提货影响全在常驻门
+  `src/types/hooksSchema218.test.ts`(以本包 `HOOK_EVENTS` 为 canonical 钉三面集合等式):亲读该门代码推断(**未实测**,
+  不动 cli 树)提货 1.3.0 后 **五条**红——**H2**(T1 缺 `DirectoryAdded`)/ **H6**(计数 30≠31)/ **H7**(字面量
+  `CANON.length === 30` 与差集 `=== 3`)/ **H8**(按 CANON 31 键铺满喂 initialize,`DirectoryAdded` 对 T1 的 partialRecord
+  是未知键 ⇒ 拒)/ **H10a**(`OLD_27 = CANON − 3` 亦含新员 ⇒ 同因拒);修法 = 该门自注「三面同动」:`coreSchemas.HOOK_EVENTS`
+  加员 + `HookInputSchema` 加臂 + H7 字面量改 31 / 4。其 :177-178 把「`DirectoryAdded` 该不该进 settings 域」记为候裁,
+  本版加员即回应该候裁项(cli 提货时表态);`coreTypes.HOOK_EVENTS`(31 员)与本版集合恰好相等。发布帖须 @cli 点名
+  (能力显式表态制)。
+- 持 `Record<HookEventName, …>` 字面量 / 对 `HookEventName` 穷举 `switch` 的消费方:升级即**编译错**(响亮,正是要的)。
+- 用 `HookEventName` / `HookInput` / `HooksConfig` 校验**外部**值的 1.2.0 消费方:收不下 `DirectoryAdded`(名词拒、整条
+  config 拒)——这正是本版修的病形;夹具钉住 1.2.0 行为供对照(frozen `z.record(z.enum(HOOK_EVENTS_1_2_0), …)` 拒、1.3.0 收)。
+- **server**(`package.json:58` **精确钉** `"1.2.0"`,无 caret——永不自动提货):亲读 `src/hooks/hook-runner.ts`——
+  `parseHooksConfig` 走 `HooksConfig.safeParse`(:200),`createTaskHooks` 按 `HOOK_EVENT_OWNER` 分流(:1179/:1185);提货后
+  wire 上 `settings.hooks.DirectoryAdded` 不再被拒,落 shell-owned 分支 = `debug("hook_events_shell_owned")` 记账不点亮不告警
+  (:1185-1188)——「配置合法但 owner 是壳」本就是既定语义(非本版新义)。server 无 `Record<HookEventName,…>` 穷举表、
+  无 30 计数钉(亲 grep src + test),提货零编译红零测试红(推断自 grep,提货批自证)。
+
+### 门
+
+- **红先**:修前 solo 跑 `test/hooks.test.ts` + `test/hooks-directory-added-1.3.0.test.ts` = **11 红**(新文件 8:集合/
+  `HooksConfig` 收键/`HookInput` 判别/导出符号/owner/matcher/前缀冻结/1.2.0 对照;`hooks.test.ts` 计数钉 3)+ `tsc --noEmit`
+  **10 错**(全在测试文件——`Record<HookEventName,…>` 无该键、union 收窄为 `never`);修后 34/34 绿、tsc 0 错。
+- **变异刀 4/4 红**(每刀后源文件复原逐字节一致):K1 `POST_198_HOOK_EVENTS` 去员 → vitest 8 红 + tsc 5 错(矩阵多余键 =
+  编译红,穷举表如约响);K2 输入字段 `directory`→`dir` → 判别钉 2 红 + tsc 1 错;K3 matcher `null`→`"directory"` → 1 红;
+  K4 重排到 CC 序(DirectoryAdded 前置 MessageDisplay)→ 前缀冻结钉 2 红。
+- **全门**:`npm run build` exit 0;`npm test` 40 文件 / 631 用例全过;`tsc --noEmit` exit 0;dist 亲验(`node -e` 加载
+  `dist/index.js`):`HOOK_EVENTS.length===31`、末员 `DirectoryAdded`、owner `shell`、matcher `null`、`HooksConfig` 收
+  `{DirectoryAdded:[…]}`;`dist/hooks.d.ts` 含 `DIRECTORY_ADDED_SOURCES` / `DirectoryAddedHookInput`(值+类型)。
+- README 无 hooks 员数句(模块清单未列 hooks 域),无需同步。
+- **codex 对抗复审 R1**(`adversarial-review`,工作树 diff):verdict needs-attention,**1 条 [high]** =「minor 发版必破
+  cli 消费方(`^1.2.0` 自动命中,契约门红),建议先落 cli 再发或改用 `^1.2.0` 选不中的版号」。处置:**不是代码缺陷,是发版
+  协同事实**(且是从本段 CHANGELOG 自述推出的)——实证如上:cli 锁文件钉 1.2.0、cli 运行时零 hook 消费、server 精确钉;
+  「破」的实体 = cli 常驻门(该门建门即自注「三面同动」),提货批修门是 cli 侧既定动作;发布走能力显式表态制 @cli。
+  「改版号避开 `^1.2.0`」= 升 major,与 1.2.0 段 codex R2 严格 semver 异议同类,当时记为**候裁项**——本版沿用 minor 口径,
+  异议原样留档供裁。另:codex 沙箱内 `npm run typecheck && npm test` exit 1——**同命令标准环境复跑 exit 0**(typecheck 0
+  错 + 40 文件 631 用例),归因 codex `--sandbox read-only` 下 vitest 写 `node_modules/.vite/vitest` 缓存失败(目录亲验存在;
+  归因为假设,复跑绿为实测)。
+
+## 1.2.0 — `MinTrust` 排序原语 + `task` 员([5796] 序题 → [5805] schema 认领 / [5807] cli 表态三点)
+
+**新导出 `trustRank(layer)` / `isAtLeast(layer, minTrust)`——规范信任阶梯的**单源**(v2-design §1:29 逐字);
+`MinTrust` **尾插** `task`。发布表 `SAFETY_MERGE_SPEC` **一字不动**(1.1.0 全表字面量冻结钉),枚举声明序不重排
+(重排 = BREAKING,免裁);版号 minor = 加词([5805]/[5807] 双方口径「1.2.0 小批 additive」;codex R2 持严格 semver
+异议,见门段——候裁项,非代码缺陷)。**
+
+> ⚠️ **词表加宽在消费方是可见的**(codex R1-F1,措辞订正):「表不动」≠「消费方零感知」。① 类型面:持
+> `Record<MinTrust, …>` 字面量或对 `MinTrust` 穷举 `switch` 的消费方,升级即**编译错**(响亮——这正是要的:那张表
+> 该退役改经 `trustRank`);② 运行时:用本包 schema(`MinTrust` / `MemberAdmission` / `MergeCategorySpec`)校验
+> **外部** spec 值的消费方,自本版起会**收下** `task`,必须能给它排位——用 `trustRank`,勿自铸五词表(五词表对
+> `task` 取值 `undefined`,`<`/`>=` 比较静默为 `false`,方向随消费方写法而定、且不响)。发包日观察值(亲 grep,
+> 观察 ≠ 规范):cli `src/` 对 `MinTrust` **类型/值零 import**——仅注释提及(`src/sema/settings/keyContracts.ts:14-15,36`),
+> 其 `TrustName` / `TRUST_RANK` 自铸且已含 `task`(按 [5807] ③ 删表改 import 时才首次成为类型消费方);1.1.0 段矩阵
+> 其余邻仓零命中。故①②今日无真实受害者,但契约句必须先说真话。
+> 「另铸六词 schema 保旧 `MinTrust`」不采:等于第二张词表,正是 1.1.0「一枚举无第二词表」钉所禁,且 cli ① 点名要
+> 在 `MinTrust` 加员。
+
+### 阶梯序判定(成文理由,亲读坐标)
+
+- 规范序 = v2-design §1:29(`sema-internal/core/research/settings-product/04-v2-design.md`)逐字:
+  `MANAGED 6 > GLOBAL 5 > PROJECT 4 > LOCAL 3 > SESSION 2 > TASK 1`。
+- `task` 位**不是本仓臆定**:§1:29 本就含 `TASK 1`(最低信任端);§4:74 `KeyContract.minTrust` 词表本就列 `'task'`
+  ——它**是** floor 词(1.1.0 JSDoc「`task` 不是 floor 词」为失真句,本版改述);§2:36 SESSION/TASK = 运行期 overlay
+  非文件、TASK 单 run 清、resume 不重放;§1:31 TASK 最高 precedence 但最低 trust(两序在用户端发散)。§5:96 resolver
+  伪码本就写作 `trustRank(L) < trustRank(contract.minTrust) → throw`——原语**名**亦有真源。
+- **数值本身入契约**(不只是序):与 cli 自铸 `TRUST_RANK`(`src/sema/settings/keyContracts.ts:37-44`,managed 6 … task 1)
+  同值,壳删表改 import 后每次比较结果逐字节不变。
+- 声明序仍非规范:`MinTrust.options` = 1.1.0 五词原序 + `task` 尾插;阶梯**只**经 `trustRank`,不索引枚举。
+- **不建模** v2-design §6.4:138 的 `launch-only`(比 session/task 更窄的「仅本进程显式标志」):它是 `bypassPermissions`
+  的入口限制,不是阶梯词;将来需成词另案。
+
+### API 形(全文)
+
+```ts
+export const MinTrust = z.enum(["local", "session", "project", "global", "managed", "task"]);
+export function trustRank(layer: MinTrust): number;                        // 6/5/4/3/2/1,穷举 switch
+export function isAtLeast(layer: MinTrust, minTrust: MinTrust): boolean;   // trustRank(layer) >= trustRank(minTrust)
+```
+
+- **fail-closed**:`trustRank` 是对 `MinTrust` 的穷举 `switch`——枚举加词漏 rank = **编译错**(`never` 臂);运行时未知词
+  (JS / 反序列化调用方喂 `__proto__` / `constructor` / 大写 provenance 层词 / `launch-only` …)= **`RangeError`**,永不
+  `undefined` / `NaN`(NaN 会让每次比较静默 `false`——方向恰好安全但不响,仍属静默臂)。`isAtLeast` 两参都过 `trustRank`。
+- 既有成员级查询族(`membersOf` / `memberAdmission` / `memberMinTrust` / `resolveMemberAdmission`)**不含比较逻辑**,
+  无需改经;测试侧原本地 `LADDER` 表删除,改用 `isAtLeast`(单源两用);`memberMinTrust` JSDoc 的
+  `rank(layer) ≥ rank(floor)` 改指 `isAtLeast`。
+- `task` 今日**零**类目 / 成员行使用(冻结 1.1.0 schema 全表逐字节解析钉证——1.1.0 消费方永不遇到未知词);
+  `minTrust:"task"` = 最宽 floor(任何层含 task overlay 皆可 set),对 spec **值**合法(`MemberAdmission` / `MergeCategorySpec` 收)。
+
+### 消费方接线
+
+```ts
+import { isAtLeast, memberMinTrust, membersOf } from "@sema-agent/settings-schema";
+for (const m of membersOf("permissions")) {
+  if (!isAtLeast(layer.sourceTrust, memberMinTrust("permissions", m))) { /* loosen ⇒ 待确认建议;tighten 不会走到这 */ }
+}
+```
+
+- cli:删自铸 `TRUST_RANK` 改 import(随 L-29 上收批同落,[5807] ③);四件套成员级门吃同一原语。1.1.0 段「本包尚未导出
+  排序原语」自本版起过期。
+
+### 门
+
+- 红先:11 条新钉 + 1 条改经原语的旧钉先红——运行时 10 红(`trustRank`/`isAtLeast is not a function` ×6、`task` 缺席 ×2、
+  声明序文本钉 ×1、单调钉 ×1),tsc 11 处红(缺导出 2 / `"task"` 不可赋 4 / `@ts-expect-error` 未命中 2 / 连带 3)→ 全绿。
+- 变异六刀各红(主题文件 33 钉):M1 session/local 互换 → 4 红(逐字表 / 单调 / 真值表 / 准入集);M2 `isAtLeast` 用 `>` →
+  5 红(含 1.1.0 方向不变量钉——单源两用之证);M3 枚举去 `task`(switch 仍留)→ 5 红;M4 枚举重排(`task` 置首)→ 2 红
+  (尾插钉 + 文本钉,其余全绿=声明序确非阶梯);M5 未知词返 `NaN` 不抛 → 只红未知词钉(1/33,定点);M6 `task` 排 7 高于
+  managed → 5 红。源文件 sha256 复原逐字节一致。
+- codex adversarial-review R1 三条:F1 [high]「加 `task` 非纯向后兼容」→ **部分采**:头句 / README 措辞订正为「表不动 ≠
+  消费方零感知」+ 消费方迁移句(上 ⚠️ 段);「另铸六词 schema 保旧 `MinTrust`」**驳回**(第二张词表);F2 [medium] 冻结
+  1.1.0 钉拿 `r.data` 对当前值 = 同义反复 → **采**:补独立 1.1.0 全表字面量夹具(commit `9e41eaf` 逐字),第七刀 M7
+  `hooks.minTrust` project→local **只红该钉**(1/33;修前此刀全绿);F3 [medium] README「无消费方自铸表」写成既成事实 →
+  **采**改述为迁移目标(cli 半场未落)。R1 自报 vitest 在其只读沙箱起不来(环境,非发现)。
+- codex R2:F2 / F3 判**已解**;1.1.0 字面量判**独立且完整**(对 `9e41eaf` 逐值,16 类目);`trustRank` / `isAtLeast` /
+  JSDoc / 新钉**无新发现**。余 F1 一条 [high]:「加宽公共枚举按 minor 发,`^1.1.0` 消费方自动收到」→ 建议发 **2.0.0**
+  或另铸六词 schema。处置:另铸 schema **再驳**(第二张词表,理由同上);**major vs minor 是版号政策、不是代码缺陷**
+  ——本批按 [5805]/[5807] 双方口径与任务书走 1.2.0,**候主会话 / clay 裁**;若裁 major,只需改 `package.json` /
+  `package-lock.json` 根版本 / 本段标题三处,代码零动。
+- 全量 39 文件 / 621 用例绿(1.1.0 基线 610 + 11);tsc 0;build 绿(dist `.d.ts` 含两原语);dist 运行时冒烟
+  (`node -e import('./dist/index.js')`)六词/六序/未知词 RangeError 如述。
+
 ## 1.1.0 — `permissions` 成员级准入(权限双通道终裁四件套之④,clay 终裁 [5797];合流形 [5794])
 
 **`SAFETY_MERGE_SPEC` 类目可声明 `members`(成员级 minTrust + 方向);首个也是当前唯一成员化的类目 = `permissions`
@@ -82,7 +251,7 @@ for (const m of membersOf("permissions")) {            // ["allow","deny","ask"]
 
 - `rank(...)` 仍是消费方自己的阶梯(v2-design §1 `managed > global > project > local > session > task`);本包
   **尚未**导出排序原语——`MinTrust` 枚举的声明序在 session/local 处与 §1 倒置、且零消费方索引它(非规范),
-  排序原语随 [5796] 序题表态另车(本版只把该注释改说真话)。
+  排序原语随 [5796] 序题表态另车(本版只把该注释改说真话)。(→ 1.2.0 已导出 `trustRank` / `isAtLeast`。)
 
 ### 门
 

package/README.md

@@ -68,6 +68,15 @@ sound). `npm ls --prod` therefore shows only `zod`. Node built-ins only (`node:c
   stays the default floor, so consumers that predate `members` behave exactly as before. This package publishes
   the contract only: it performs no admission check and no "degrade a below-floor allow to a pending suggestion"
   step — those live in the consumers (engine import door, shell resolver), each on its own release schedule.
+  1.2.0 adds the **trust ordering primitives**: `trustRank(layer)` (v2-design §1 verbatim, `managed 6 > global 5 >
+  project 4 > local 3 > session 2 > task 1`) and `isAtLeast(layer, minTrust)` — the ladder every resolver is to
+  compare floors against; consumers retire their own rank tables onto it (the CLI's `TRUST_RANK` migration is
+  pending on its side, board [5807] ③ — exporting the primitive does not by itself make it the single source).
+  `MinTrust` gains the `task` word (the runtime task overlay, the loosest floor; appended, declaration order
+  otherwise unchanged — the declaration order is not the ladder, `trustRank` is). The published table does not
+  use `task`; the widened vocabulary is visible to consumers that hold a `Record<MinTrust, …>` / exhaustive
+  switch (compile error on upgrade — migrate to `trustRank`) or that validate external spec values with these
+  schemas (they now accept `task` and must rank it — again `trustRank`, never a five-word table of their own).
 - **Auth wire contract** (`api/auth.ts`, subpath `./api/auth`): the `/api/v1/auth/*` face — RFC 8628
   device flow (code / token poll / approve consent) + rotating refresh + logout, the OAuth error envelope,
   and the pure client helpers `normalizeUserCode` / `nextPollInterval`. Shipped M1 shapes frozen.

package/dist/hooks.d.ts

@@ -2,10 +2,10 @@
  * `hooks` — the CC-parity hooks contract (incl. stop attribution).
  *
  * ONE definition of the FULL hook-event set — 27 CC 2.1.198 events (REF: the `jP` array in
- * claude-cli-2.1.198.pretty.js) + 3 post-198 events the shell already ships (CwdChanged / FileChanged /
- * MessageDisplay). Per the product ruling: the CONTRACT is the full set from day one; the engine
- * hook-runner (service) and the shell light events up in PHASES — adding an event later is pure
- * implementation, never a schema change.
+ * claude-cli-2.1.198.pretty.js) + 4 post-198 events the shell already ships (CwdChanged / FileChanged /
+ * MessageDisplay, and DirectoryAdded from CC 2.1.219). Per the product ruling: the CONTRACT is the full set
+ * from day one; the engine hook-runner (service) and the shell light events up in PHASES — adding an event
+ * later is pure implementation, never a schema change.
  *
  * CONSUMERS
  * - service (sema-server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
@@ -26,11 +26,15 @@
 import { z } from "zod";
 /** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
 export declare const CC_198_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded"];
-/** Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198). */
-export declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay"];
-/** The full 30-event contract set = CC 198's 27 + the 3 post-198 shell events. */
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay"];
-export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay"]>;
+/**
+ * Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198).
+ * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
+ * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
+ */
+export declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
+/** The full 31-event contract set = CC 198's 27 + the 4 post-198 shell events. */
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
+export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"]>;
 export type HookEventName = z.infer<typeof HookEventName>;
 export declare const HookOwner: z.ZodEnum<["engine", "shell"]>;
 export type HookOwner = z.infer<typeof HookOwner>;
@@ -1586,7 +1590,48 @@ export declare const MessageDisplayHookInput: z.ZodObject<{
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
 }>;
-/** Any hook input — discriminated on `hook_event_name` (all 30 events). */
+/** How a directory joined the session working set: the `/add-dir` slash command or repo-root registration. */
+export declare const DIRECTORY_ADDED_SOURCES: readonly ["slash_command", "register_repo_root"];
+/**
+ * Fired after a directory joins the session's working set (CC 2.1.219; agent-types hooks.d.ts:582-586 —
+ * `directory` is the absolute path). Shell-owned; matcher ignored; no hookSpecificOutput arm upstream.
+ */
+export declare const DirectoryAddedHookInput: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    hook_event_name: z.ZodLiteral<"DirectoryAdded">;
+    directory: z.ZodString;
+    source: z.ZodEnum<["slash_command", "register_repo_root"]>;
+}, "strip", z.ZodTypeAny, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}>;
+export type DirectoryAddedHookInput = z.infer<typeof DirectoryAddedHookInput>;
+/** Any hook input — discriminated on `hook_event_name` (all 31 events). */
 export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.ZodObject<{
     session_id: z.ZodString;
     transcript_path: z.ZodString;
@@ -2884,6 +2929,39 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
+}>, z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    hook_event_name: z.ZodLiteral<"DirectoryAdded">;
+    directory: z.ZodString;
+    source: z.ZodEnum<["slash_command", "register_repo_root"]>;
+}, "strip", z.ZodTypeAny, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
 }>]>;
 export type HookInput = z.infer<typeof HookInput>;
 /** Legacy top-level decision (CC): "approve" ≈ allow, "block" feeds `reason` back to the model. */
@@ -5442,7 +5520,7 @@ export declare const HookMatcherEntry: z.ZodObject<{
 export type HookMatcherEntry = z.infer<typeof HookMatcherEntry>;
 /**
  * The hooks config record — the shape `TaskRequest.settings.hooks` carries on the wire and the shell
- * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 30
+ * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 31
  * contract events (an unknown event name fails parse — catch typos at the wire); all keys optional.
  */
 export type HooksConfig = Partial<Record<HookEventName, HookMatcherEntry[]>>;

package/dist/hooks.js

@@ -2,10 +2,10 @@
  * `hooks` — the CC-parity hooks contract (incl. stop attribution).
  *
  * ONE definition of the FULL hook-event set — 27 CC 2.1.198 events (REF: the `jP` array in
- * claude-cli-2.1.198.pretty.js) + 3 post-198 events the shell already ships (CwdChanged / FileChanged /
- * MessageDisplay). Per the product ruling: the CONTRACT is the full set from day one; the engine
- * hook-runner (service) and the shell light events up in PHASES — adding an event later is pure
- * implementation, never a schema change.
+ * claude-cli-2.1.198.pretty.js) + 4 post-198 events the shell already ships (CwdChanged / FileChanged /
+ * MessageDisplay, and DirectoryAdded from CC 2.1.219). Per the product ruling: the CONTRACT is the full set
+ * from day one; the engine hook-runner (service) and the shell light events up in PHASES — adding an event
+ * later is pure implementation, never a schema change.
  *
  * CONSUMERS
  * - service (sema-server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
@@ -55,9 +55,13 @@ export const CC_198_HOOK_EVENTS = [
     "WorktreeRemove",
     "InstructionsLoaded",
 ];
-/** Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198). */
-export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay"];
-/** The full 30-event contract set = CC 198's 27 + the 3 post-198 shell events. */
+/**
+ * Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198).
+ * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
+ * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
+ */
+export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
+/** The full 31-event contract set = CC 198's 27 + the 4 post-198 shell events. */
 export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
 export const HookEventName = z.enum(HOOK_EVENTS);
 // ── ownership (owner-single) ─────────────────────────────────────────────────────────────────────
@@ -119,6 +123,7 @@ export const HOOK_EVENT_MATCHER_FIELD = {
     CwdChanged: null,
     FileChanged: "file_path", // matched against basename(file_path)
     MessageDisplay: null,
+    DirectoryAdded: null, // the shell's getMatchingHooks switch has no arm for it → every entry matches (CwdChanged family)
 };
 // ── shared enums (CC-verbatim) ─────────────────────────────────────────────────────────────────────────
 export const PermissionBehavior = z.enum(["allow", "deny", "ask"]);
@@ -382,7 +387,18 @@ export const MessageDisplayHookInput = BaseHookInput.extend({
     /** Newly completed lines since the prior flush (final flush may end mid-line / be empty). */
     delta: z.string(),
 });
-/** Any hook input — discriminated on `hook_event_name` (all 30 events). */
+/** How a directory joined the session working set: the `/add-dir` slash command or repo-root registration. */
+export const DIRECTORY_ADDED_SOURCES = ["slash_command", "register_repo_root"];
+/**
+ * Fired after a directory joins the session's working set (CC 2.1.219; agent-types hooks.d.ts:582-586 —
+ * `directory` is the absolute path). Shell-owned; matcher ignored; no hookSpecificOutput arm upstream.
+ */
+export const DirectoryAddedHookInput = BaseHookInput.extend({
+    hook_event_name: z.literal("DirectoryAdded"),
+    directory: z.string(),
+    source: z.enum(DIRECTORY_ADDED_SOURCES),
+});
+/** Any hook input — discriminated on `hook_event_name` (all 31 events). */
 export const HookInput = z.discriminatedUnion("hook_event_name", [
     PreToolUseHookInput,
     PostToolUseHookInput,
@@ -414,6 +430,7 @@ export const HookInput = z.discriminatedUnion("hook_event_name", [
     CwdChangedHookInput,
     FileChangedHookInput,
     MessageDisplayHookInput,
+    DirectoryAddedHookInput,
 ]);
 // ── hook output / decision semantics (CC-verbatim, with the service-receipt design points pinned) ────────
 //

package/dist/index.js

@@ -14,7 +14,7 @@ export * from "./cross-domain.js"; // pure half only (no fleet placement)
 export * from "./remote-exec.js";
 export * from "./safety-merge-spec.js"; // #14 per-category safety merge-spec (settings resolver authority)
 export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (pure: type + parse/serialize + SchedulerStore interface; fs binding in ./node)
-export * from "./hooks.js"; // CC-parity hooks contract (30-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
+export * from "./hooks.js"; // CC-parity hooks contract (31-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
 export * from "./fleet.js"; // scheduling/fleet contract (drain protocol · instance discovery · dispatch policy · quota lease · usage report · quota reset event) — CONTROL-PLANE-SCHEDULING-DESIGN, pure/browser-safe
 export * from "./migrate.js"; // 0.5→0.6 migration tools (hosts grandfathering + worker.model→catalog migration PLAN — report/draft only, E1; EXPERT-REDESIGN §2-2/§3), pure/browser-safe
 export * from "./api/auth.js"; // /api/v1/auth/* wire contract (RFC 8628 device flow + rotating refresh + logout + approve) — REGISTRY-REBUILD-DESIGN §2, M1 shipped shapes frozen, pure/browser-safe

package/dist/safety-merge-spec.d.ts

@@ -38,18 +38,41 @@
  *   silences classifier asks only; it can never silence a MANDATED ask (shellGate "always", org policy,
  *   requiresRealApproval). Consumers read admission through {@link memberAdmission} / {@link memberMinTrust} /
  *   {@link membersOf} — never through a hardcoded allow/deny/ask table of their own (single source).
+ *
+ * TRUST ORDERING PRIMITIVES (1.2.0 — board [5796] ordering question → [5805] claim / [5807] consumer statement):
+ *   The floor words are only meaningful against a LADDER, and that ladder is v2-design §1:29, verbatim:
+ *   `MANAGED 6 > GLOBAL 5 > PROJECT 4 > LOCAL 3 > SESSION 2 > TASK 1`. {@link trustRank} publishes exactly those
+ *   numbers and {@link isAtLeast} the comparison a resolver makes (`rank(layer) ≥ rank(floor)` ⇒ admitted), so no
+ *   consumer keeps a rank table of its own (cli's `TRUST_RANK` retires onto these). `task` joins {@link MinTrust}
+ *   (v2-design §4:74 lists it in `KeyContract.minTrust`; §2:36 — session/task are runtime overlays, never files):
+ *   the loosest floor, "any layer including the task overlay may set this". No row of {@link SAFETY_MERGE_SPEC}
+ *   uses it today (the frozen-1.1.0 conformance pin holds that). The enum's DECLARATION ORDER stays what 1.1.0
+ *   published, `task` appended — reordering would be breaking ([5807] ②) and the declaration order is NOT the
+ *   ladder anyway; only {@link trustRank} is.
  */
 import { z } from "zod";
 /** How values from different layers/principals combine for a category. */
 export declare const MergeShape: z.ZodEnum<["denyFirst", "replace", "runAll", "overrideByName", "concat"]>;
 export type MergeShape = z.infer<typeof MergeShape>;
 /** The trust-tier VOCABULARY a category — or, since 1.1.0, one of its members — names as its admission floor
- *  (the MINIMUM trust a layer/principal must have to set it). The RANK is v2-design §1:
- *  `managed > global > project > local > session` (`task` is a layer tier below all of these and is not a floor
- *  word). ⚠️ This enum's DECLARATION ORDER is not that rank (session/local are listed the other way round) and no
- *  consumer indexes it — a published rank primitive is a separate follow-up (board [5796] question). */
-export declare const MinTrust: z.ZodEnum<["local", "session", "project", "global", "managed"]>;
+ *  (the MINIMUM trust a layer/principal must have to set it). The RANK is v2-design §1:29,
+ *  `managed 6 > global 5 > project 4 > local 3 > session 2 > task 1`, published as {@link trustRank}; compare with
+ *  {@link isAtLeast}. `task` (1.2.0) is the runtime task overlay — the lowest trust, the loosest floor.
+ *  ⚠️ This enum's DECLARATION ORDER is NOT the rank (it is the 1.1.0 order with `task` appended — kept byte-stable
+ *  because reordering is breaking); never index it as a ladder — use {@link trustRank}. */
+export declare const MinTrust: z.ZodEnum<["local", "session", "project", "global", "managed", "task"]>;
 export type MinTrust = z.infer<typeof MinTrust>;
+/** The trust RANK of a floor / layer word — v2-design §1:29 verbatim (`MANAGED 6 > GLOBAL 5 > PROJECT 4 > LOCAL 3 >
+ *  SESSION 2 > TASK 1`), the ONE published ladder every resolver compares against (1.2.0). Higher = more trusted.
+ *  The numbers themselves are contract (a consumer may persist or log them), not merely their order.
+ *  Exhaustive over {@link MinTrust}: a word added to the enum without a rank is a COMPILE error here; a word that
+ *  is not in the enum at runtime (a JavaScript / deserialized caller) is a loud RangeError — never `undefined` or
+ *  `NaN`, which would turn every comparison into a silent `false`. */
+export declare function trustRank(layer: MinTrust): number;
+/** `trustRank(layer) ≥ trustRank(minTrust)` — "is a source at `layer` trusted enough to set a key / member whose
+ *  floor is `minTrust`?" (1.2.0). The comparison a resolver's admission check is; reflexive (a floor admits its
+ *  own tier). Both arguments are validated by {@link trustRank} (unknown word ⇒ RangeError). */
+export declare function isAtLeast(layer: MinTrust, minTrust: MinTrust): boolean;
 /** Which way a MEMBER moves the engine's unattended surface (1.1.0). `loosen` = admits an action without a human
  *  that would otherwise ask/deny — a privilege, so it needs trust; `tighten` = only ever narrows — restricting is
  *  safe from anyone, so any settings-file layer may add it. The word is what a consumer branches on for the
@@ -63,13 +86,13 @@ export type MemberDirection = z.infer<typeof MemberDirection>;
  *  only by SAYING so; omission never lowers it (fail-closed by construction). */
 export declare const MemberAdmission: z.ZodObject<{
     direction: z.ZodEnum<["loosen", "tighten"]>;
-    minTrust: z.ZodOptional<z.ZodEnum<["local", "session", "project", "global", "managed"]>>;
+    minTrust: z.ZodOptional<z.ZodEnum<["local", "session", "project", "global", "managed", "task"]>>;
 }, "strip", z.ZodTypeAny, {
     direction: "loosen" | "tighten";
-    minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+    minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
 }, {
     direction: "loosen" | "tighten";
-    minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+    minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
 }>;
 export type MemberAdmission = z.infer<typeof MemberAdmission>;
 /** The RESOLVED admission a consumer branches on — the category fallback already applied, so `minTrust` is never
@@ -129,7 +152,7 @@ export declare const TightenRule: z.ZodDiscriminatedUnion<"rule", [z.ZodObject<{
 export type TightenRule = z.infer<typeof TightenRule>;
 export declare const MergeCategorySpec: z.ZodObject<{
     mergeShape: z.ZodEnum<["denyFirst", "replace", "runAll", "overrideByName", "concat"]>;
-    minTrust: z.ZodEnum<["local", "session", "project", "global", "managed"]>;
+    minTrust: z.ZodEnum<["local", "session", "project", "global", "managed", "task"]>;
     tighten: z.ZodDiscriminatedUnion<"rule", [z.ZodObject<{
         rule: z.ZodLiteral<"none">;
     }, "strip", z.ZodTypeAny, {
@@ -178,13 +201,13 @@ export declare const MergeCategorySpec: z.ZodObject<{
      *  category `minTrust` when the row omits one); the member set is closed — {@link membersOf} enumerates it. */
     members: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         direction: z.ZodEnum<["loosen", "tighten"]>;
-        minTrust: z.ZodOptional<z.ZodEnum<["local", "session", "project", "global", "managed"]>>;
+        minTrust: z.ZodOptional<z.ZodEnum<["local", "session", "project", "global", "managed", "task"]>>;
     }, "strip", z.ZodTypeAny, {
         direction: "loosen" | "tighten";
-        minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+        minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
     }, {
         direction: "loosen" | "tighten";
-        minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+        minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
     enforcement: "gate" | "server" | "resolver" | "client";
@@ -201,13 +224,13 @@ export declare const MergeCategorySpec: z.ZodObject<{
         rule: "enumRank";
         order: string[];
     };
-    minTrust: "local" | "session" | "global" | "project" | "managed";
+    minTrust: "local" | "session" | "global" | "project" | "managed" | "task";
     mergeShape: "concat" | "replace" | "denyFirst" | "runAll" | "overrideByName";
     fail: "closed" | "open";
     seam: string;
     members?: Record<string, {
         direction: "loosen" | "tighten";
-        minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+        minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
     }> | undefined;
     coreAxis?: "permissionDecision" | "toolEffect" | "egress" | "irreversibility" | "safetyAxis" | "severity" | "shellGate" | undefined;
 }, {
@@ -225,13 +248,13 @@ export declare const MergeCategorySpec: z.ZodObject<{
         rule: "enumRank";
         order: string[];
     };
-    minTrust: "local" | "session" | "global" | "project" | "managed";
+    minTrust: "local" | "session" | "global" | "project" | "managed" | "task";
     mergeShape: "concat" | "replace" | "denyFirst" | "runAll" | "overrideByName";
     fail: "closed" | "open";
     seam: string;
     members?: Record<string, {
         direction: "loosen" | "tighten";
-        minTrust?: "local" | "session" | "global" | "project" | "managed" | undefined;
+        minTrust?: "local" | "session" | "global" | "project" | "managed" | "task" | undefined;
     }> | undefined;
     coreAxis?: "permissionDecision" | "toolEffect" | "egress" | "irreversibility" | "safetyAxis" | "severity" | "shellGate" | undefined;
 }>;
@@ -446,5 +469,5 @@ export declare function resolveMemberAdmission(spec: MergeCategorySpec, member:
  *  Unknown category or member ⇒ RangeError (never a fallback). */
 export declare function memberAdmission<C extends SafetyMergeCategory>(category: C, member: SafetyMergeMember<C>): ResolvedMemberAdmission;
 /** A member's admission FLOOR from the published table — the word a resolver compares the layer's trust against
- *  (`rank(layer) ≥ rank(floor)` ⇒ admitted). Convenience over {@link memberAdmission}. */
+ *  (`isAtLeast(layer, floor)` ⇒ admitted; the ladder is {@link trustRank}). Convenience over {@link memberAdmission}. */
 export declare function memberMinTrust<C extends SafetyMergeCategory>(category: C, member: SafetyMergeMember<C>): MinTrust;

package/dist/safety-merge-spec.js

@@ -38,16 +38,54 @@
  *   silences classifier asks only; it can never silence a MANDATED ask (shellGate "always", org policy,
  *   requiresRealApproval). Consumers read admission through {@link memberAdmission} / {@link memberMinTrust} /
  *   {@link membersOf} — never through a hardcoded allow/deny/ask table of their own (single source).
+ *
+ * TRUST ORDERING PRIMITIVES (1.2.0 — board [5796] ordering question → [5805] claim / [5807] consumer statement):
+ *   The floor words are only meaningful against a LADDER, and that ladder is v2-design §1:29, verbatim:
+ *   `MANAGED 6 > GLOBAL 5 > PROJECT 4 > LOCAL 3 > SESSION 2 > TASK 1`. {@link trustRank} publishes exactly those
+ *   numbers and {@link isAtLeast} the comparison a resolver makes (`rank(layer) ≥ rank(floor)` ⇒ admitted), so no
+ *   consumer keeps a rank table of its own (cli's `TRUST_RANK` retires onto these). `task` joins {@link MinTrust}
+ *   (v2-design §4:74 lists it in `KeyContract.minTrust`; §2:36 — session/task are runtime overlays, never files):
+ *   the loosest floor, "any layer including the task overlay may set this". No row of {@link SAFETY_MERGE_SPEC}
+ *   uses it today (the frozen-1.1.0 conformance pin holds that). The enum's DECLARATION ORDER stays what 1.1.0
+ *   published, `task` appended — reordering would be breaking ([5807] ②) and the declaration order is NOT the
+ *   ladder anyway; only {@link trustRank} is.
  */
 import { z } from "zod";
 /** How values from different layers/principals combine for a category. */
 export const MergeShape = z.enum(["denyFirst", "replace", "runAll", "overrideByName", "concat"]);
 /** The trust-tier VOCABULARY a category — or, since 1.1.0, one of its members — names as its admission floor
- *  (the MINIMUM trust a layer/principal must have to set it). The RANK is v2-design §1:
- *  `managed > global > project > local > session` (`task` is a layer tier below all of these and is not a floor
- *  word). ⚠️ This enum's DECLARATION ORDER is not that rank (session/local are listed the other way round) and no
- *  consumer indexes it — a published rank primitive is a separate follow-up (board [5796] question). */
-export const MinTrust = z.enum(["local", "session", "project", "global", "managed"]);
+ *  (the MINIMUM trust a layer/principal must have to set it). The RANK is v2-design §1:29,
+ *  `managed 6 > global 5 > project 4 > local 3 > session 2 > task 1`, published as {@link trustRank}; compare with
+ *  {@link isAtLeast}. `task` (1.2.0) is the runtime task overlay — the lowest trust, the loosest floor.
+ *  ⚠️ This enum's DECLARATION ORDER is NOT the rank (it is the 1.1.0 order with `task` appended — kept byte-stable
+ *  because reordering is breaking); never index it as a ladder — use {@link trustRank}. */
+export const MinTrust = z.enum(["local", "session", "project", "global", "managed", "task"]);
+/** The trust RANK of a floor / layer word — v2-design §1:29 verbatim (`MANAGED 6 > GLOBAL 5 > PROJECT 4 > LOCAL 3 >
+ *  SESSION 2 > TASK 1`), the ONE published ladder every resolver compares against (1.2.0). Higher = more trusted.
+ *  The numbers themselves are contract (a consumer may persist or log them), not merely their order.
+ *  Exhaustive over {@link MinTrust}: a word added to the enum without a rank is a COMPILE error here; a word that
+ *  is not in the enum at runtime (a JavaScript / deserialized caller) is a loud RangeError — never `undefined` or
+ *  `NaN`, which would turn every comparison into a silent `false`. */
+export function trustRank(layer) {
+    switch (layer) {
+        case "managed": return 6;
+        case "global": return 5;
+        case "project": return 4;
+        case "local": return 3;
+        case "session": return 2;
+        case "task": return 1;
+        default: {
+            const unknown = layer;
+            throw new RangeError(`MinTrust: unknown trust word '${String(unknown)}' (words: ${MinTrust.options.join(", ")})`);
+        }
+    }
+}
+/** `trustRank(layer) ≥ trustRank(minTrust)` — "is a source at `layer` trusted enough to set a key / member whose
+ *  floor is `minTrust`?" (1.2.0). The comparison a resolver's admission check is; reflexive (a floor admits its
+ *  own tier). Both arguments are validated by {@link trustRank} (unknown word ⇒ RangeError). */
+export function isAtLeast(layer, minTrust) {
+    return trustRank(layer) >= trustRank(minTrust);
+}
 /** Which way a MEMBER moves the engine's unattended surface (1.1.0). `loosen` = admits an action without a human
  *  that would otherwise ask/deny — a privilege, so it needs trust; `tighten` = only ever narrows — restricting is
  *  safe from anyone, so any settings-file layer may add it. The word is what a consumer branches on for the
@@ -171,7 +209,7 @@ export function memberAdmission(category, member) {
     return resolveMemberAdmission(categorySpec(category), member, category);
 }
 /** A member's admission FLOOR from the published table — the word a resolver compares the layer's trust against
- *  (`rank(layer) ≥ rank(floor)` ⇒ admitted). Convenience over {@link memberAdmission}. */
+ *  (`isAtLeast(layer, floor)` ⇒ admitted; the ladder is {@link trustRank}). Convenience over {@link memberAdmission}. */
 export function memberMinTrust(category, member) {
     return memberAdmission(category, member).minTrust;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",