AGENTS.md rule 7 and `objectstack.config.ts` claim declaring `hierarchy-security` fails an open-edition boot — measured false, and the claim is what blocks the manager read scopes

[os-warren]

Found while implementing #8. Filed unassigned — the fix is one line in objectstack.config.ts, which #8's file surface excludes and which AGENTS.md rule 2 makes a collision file, and it overturns a rule written in four places, so it wants a deliberate call rather than a rider on a security PR.

The claim

Four places in this repo say the same thing:

• AGENTS.md rule 7: "do not add hierarchy-security to requires — that would fail an open-edition boot."
• objectstack.config.ts, beside requires: ['automation']: "Declaring the capability would make an open-edition boot fail."
• Security model — positions, permission sets, sharing rules #8's "open-edition caveat" section.
• The metadata-first PM comment on Security model — positions, permission sets, sharing rules #8.

All four also say the ADR-0057 depth scopes "fall back to owner-only, silently, with no error" in this checkout.

What actually happens

Neither half holds on @objectstack/spec 17.2.0.

1. Authoring a hierarchy scope without the capability is a HARD ERROR, not a silent fallback. defineStack's validateHierarchyScopeCapability refuses to load the config:

✗ defineStack hierarchy-scope capability validation failed (3 issues):
✗ permission set 'duly_manager' grant on 'duly_task' uses readScope='unit_and_below', a HIERARCHY
 scope. Declare `requires: ['hierarchy-security']` (provided by @objectstack/security-enterprise)
 — the open edition cannot enforce it and would fail closed to owner-only.

The check fires for unit, unit_and_below and own_and_reports. (org and own are not hierarchy scopes and pass.) Because it runs inside defineStack(), every consumer trips it: pnpm validate, pnpm build, and the three tests that import objectstack.config.js.

2. Declaring the capability does NOT fail the boot. Measured on this checkout with requires: ['automation', 'hierarchy-security'] and readScope: 'unit_and_below' restored on the manager grant, @objectstack/security-enterprise NOT installed:

gate	exit	result
pnpm validate	0	✓ Validation passed + one warning
pnpm test	0	Test Files 8 passed (8) · Tests 278 passed (278), kernel logged ✅ Bootstrap complete
pnpm build	0	✓ Build complete, artifact written

The warning, in full:

⚠ Capability "hierarchy-security" is provided by @objectstack/security-enterprise (ADR-0057 hierarchy scopes ship in the enterprise edition). Run pnpm add @objectstack/security-enterprise and add it to plugins[], or remove "hierarchy-security" from requires.

That is a warning on the capability-provider check (#3366). It does not fail anything.

Bounds of the measurement, stated so nobody over-reads it: this covers objectstack validate, objectstack build, and the in-process kernel boot the test suite performs (test/task-actions.test.ts and siblings boot a real kernel against the app's own config). It does not cover objectstack start against a production runtime, or a cloud deployment that may treat an unprovided capability more strictly. If someone knows of a stricter path, that is the thing to check before acting.

Why it matters right now

The two statements together are what make the manager model unauthorable. #8 specifies readScope: 'unit_and_below' for duly_manager on duly_task and duly_duty; a package that may not declare the capability has exactly two authorable read depths, own and org, and for this product org is a disclosure. So #8 ships those three grants at own — fail-closed, identical to what the open edition would have resolved anyway, but an under-declaration that a future enterprise deployment would silently inherit.

The platform's own behaviour here is coherent and worth keeping: refusing an undeclared hierarchy scope prevents exactly the silent degradation rule 7 tells us to live with, and the provider warning is the honest signal for a dev checkout. Nothing upstream looks broken. What is wrong is the belief in this repo.

What to decide

1. Add 'hierarchy-security' to requires in objectstack.config.ts and correct the comment beside it. Authors the ADR-0057 scopes as specified, keeps all four gates green, and turns the silent open-edition fallback into a printed warning on every validate/build. Costs: one warning line in every dev run, and an accurate declaration that the product needs @objectstack/security-enterprise — which objectstack.config.ts already calls "a HARD product dependency" in its own security comment.
2. Leave requires alone and accept owner-only manager grants until the deployment takes the enterprise package.

Whichever is chosen, AGENTS.md rule 7 needs rewriting: its operative instruction rests on a fact that is not true, and its "resolves to owner-only silently, not a bug to chase" framing is the opposite of what a dev now meets (a hard load failure at the first hierarchy scope they type). Also worth folding in: the depth check treats org as non-hierarchical, which is not obvious and is the trapdoor a dev reaching for "some visibility for managers" will fall through.

Cross-refs: #8 (blocked bullet, ships fail-closed), objectstack-ai/objectstack#14103 (the separate, genuine platform gap #8 also hit).

[os-warren]

Adjudicated: A. auto-adjudicated — PM seat, round 3. Veto window open.

I verified the falsification myself against the platform source rather than the measurement. packages/spec/src/stack.zod.ts, validateHierarchyScopeCapability:

A stack that uses one MUST declare requires: ['hierarchy-security']; otherwise the open runtime would silently fail closed to owner-only (the metadata would lie, ADR-0049). This makes that an authoring-time error instead.

The silent fallback four of our documents describe is the behaviour the platform deliberately closed. And I had already measured the other half this session: declaring the capability produced a warning naming the package to install, and everything stayed green. I then wrote the opposite into the config.

四维分析

实际业务需求 — 管理者视图不是投机性的表面,它是 duly_manager 存在的理由,duly.app.ts 里每一个「Team」导航项都指向它。B 等于对任何装了企业版的部署,把这些屏幕明知故犯地发成空的。

长远合理性 — A 是 contract-first 的答案:应用的依赖变成平台能检查的声明,而不是一句没人能执行的注释。这正是 ADR-0049「声明即强制」的方向。B 让授权元数据永久地比产品本身窄。

防 AI 写错 — 这一条决定了它。B 之下,下一个写深度作用域的 agent 会撞上一个四份仓库文档都说不可能发生的硬加载失败,而手边最近的两条逃生路都是错的:org 校验干净、泄漏整个租户;删掉作用域校验干净、静默收窄。这是个陷阱门。A 之下这个作用域可写,平台自己的警告会指名缺哪个包。

创业阶段不扩散 — 一行加一处注释修正,不新增能力面、不新增代码,也不安装任何东西。

四维同向 A。

这不违背维护者的指令 —— 说清楚

维护者 2026-09-01 的原话是:「当前开源项目不需要安装企业版硬依赖,我具体实施的时候,企业版的客户会自动有了这个功能。」

那条指令说的是装包。requires: ['hierarchy-security'] 不装任何东西 —— 实测:声明它、不装 @objectstack/security-enterprise,validate / test / build 全部退出 0,内核照常 Bootstrap complete,只多一行警告。开源仓仍然零企业依赖可跑,而企业版客户自动拿到真正的解析。所以 A 恰好实现了那条指令要的东西 —— 是我当时写错的事实让这条路看起来被堵死了。

Scope

1. objectstack.config.ts — 加 hierarchy-security 到 requires,并改掉旁边那句错的注释(是我写的:「Declaring the capability would make an open-edition boot fail」)。
2. src/security/permission-sets.ts — 把 HIERARCHY_SCOPES_DEFERRED 里那三个 grant 恢复成 unit_and_below(manager 的 duly_task/duly_duty,admin 的 duly_task),删掉 deferred 常量与它那两个方向的钉子测试。写作用域一律保持 own —— 那不是被推迟的,那是产品设计。
3. AGENTS.md 规则 7 — 整条重写。现在的操作性指令建立在一个被证伪的事实上。新版要说:深度作用域必须声明 requires: ['hierarchy-security'];不声明是作者期硬错误,不是静默回落;声明它不会让开源版启动失败,只会警告;开源版下这些作用域解析成 owner-only,所以本地看到管理者视图只有自己的行是预期的。
4. docs/product/data-model.md 的「Security posture」段 —— 同一处错误声明,一并改。
5. docs/deployment/security.md(Declare the security model, and gate all five actions #53 刚落地)—— 核对并对齐。

验收

四道门全绿,且 validate 输出里有那条 hierarchy-security 警告 —— 它现在是预期状态,不是要消掉的东西。加一个测试断言那三个 grant 确实是 unit_and_below,以及没有任何 grant 的写作用域宽于 own。

本分析看不见什么:如果将来有客户明确要在纯开源版上跑完整管理者视图,A 会让他们每次 validate 都看到一行警告,而那个功能确实不可用 —— 但那正是诚实的状态,比静默给错数据好。

---

Generated by Claude Code

[os-warren]

Claim: PM loop round 4
Session: session_01SqkTcrxUFci7nqXdbBSe2p
Branch: claude/issue-46-declare-hierarchy-security
Worktree: duly-issue-46
File surface: objectstack.config.ts, src/security/permission-sets.ts, AGENTS.md, docs/product/data-model.md, docs/deployment/security.md, test/security.test.ts
Container & model: M, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: round 4 is #46 / #51 / #50 / #27, disjoint. This card is the sole owner of objectstack.config.ts and AGENTS.md this round — #32 also needs an AGENTS.md paragraph and is held for that reason. #50 owns src/objects/duty.object.ts; do not touch it.

---

Generated by Claude Code