Make the wall-clock unit un-misreadable in authored duration declarations — the ruled A-half of the business-hours question (#13655)

[huangyiirene]

Provenance: maintainer ruling 2026-08-31 (director seat summon #7, decision batch #18, verbatim 「其他同意」 on #13655's presented split recommendation). Ruling record: #13655 comment 5478756633. Filed by the director seat, session session_01KGtaLpkW1mycWgkbSb3H6t.

The problem this half closes

An author (human or AI) writes critical: { strategic: 4, … } in an SLA matrix meaning support hours; the platform silently interprets wall-clock hours. The number looks perfectly normal, the misread is invisible, and every derived reading (is_sla_violated, breach sweeps, widgets) inherits it. The reference app's only mitigation today is four duplicated prose warnings (_case-sla.ts, case.hook.ts's matrix, crm_case.sla_due_date's field note, the hook module header) — prose being this repo's weakest protection.

The ruled goal (⛔ not a mechanism prescription)

"This number is wall-clock hours" must be part of the declaration, not ambient prose. First deliverable of this card is the mechanism CHOICE, measured against the real sites, then the implementation:

• a spec-level unit annotation on duration-shaped declarations (widens the contract — if chosen, clause ② applies and the addition must be enforced/read somewhere, ⛔ never declared-but-inert per ADR-0049), or
• a consumption-side convention that consolidates the four prose copies into ONE authoritative, machine-checked site (zero contract change; a lint that flags duration-shaped keys lacking the unit marker), or
• a naming convention (*_calendar_hours) with a gate — cheapest, but renames published app metadata.

Whichever is chosen must answer: where does the NEXT AI-authored app learn the unit rule at authoring time, rather than in a code comment it never reads?

Boundaries from the ruling

• ⛔ This card must NOT grow into the business-hours capability — that is the parked B-half, frozen on No business-hours calendar: every authored deadline is CALENDAR hours, and an app can only warn about it in prose — a P1 raised 5pm Friday is due 9pm Friday #13655 with a named-external-user unfreeze condition. If the mechanism choice concludes only a full calendar can fix the misread, stop and report the fork; do not build B.
• The reference app's four prose sites are the acceptance surface: after this lands, they should collapse to at most one, with the unit carried by the declaration mechanism instead.

Refs: #13655 (the ruled decision card, closed not planned as the B-record) · objectstack-ai/hotcrm#1184 (where the prose warnings live).

[os-warren]

Triage → domain:spec · p2 · enhancement. （补车道 —— 本卡此前只有 pm:queue，无 domain:*，在候选查询里等于不存在。）

锚定，以及为什么在机制未选定前仍能定车道。 三个候选机制里有一个明确要动 packages/spec（duration 形状声明上的单位标注，卡片自己写明「widens the contract, clause ② applies」），而车道规则是凡触 packages/spec 一律转 domain:spec 座位，不论谁需要它。更重要的是：本卡的第一交付物是机制选择本身，而那个选择是一道契约问题（要不要往公共声明面加东西），该由 spec 座位拿。

⚠️ 若度量后选中的是 lint 或命名约定那两条（落 packages/lint / scripts/），车道改挂 domain:devx —— 现在按「唯一一个会碰 spec 的选项」挂，并在此写明改挂条件，而不是让它继续无车道地躺着。

定级 p2。 已有维护者裁决（#13655，2026-08-31，「其他同意」），方向已定、不等人；危害是单位静默误读沿着 is_sla_violated、breach sweep、widget 一路继承下去，而且数字本身看着完全正常 —— 这是本仓最贵的那类错误（无声、可传播）。不判 p1：目前唯一已知实例在参考应用里，且已有四处散文警告顶着（虽然散文是本仓最弱的防线，这也正是本卡要消灭的东西）。

派单说明 —— 卡片里三条边界必须原样进派单：

• ⛔ 不得长成 business-hours 能力。那是被冻结的 B 半边（No business-hours calendar: every authored deadline is CALENDAR hours, and an app can only warn about it in prose — a P1 raised 5pm Friday is due 9pm Friday #13655，解冻条件是具名外部用户）。若机制度量的结论是「只有完整日历才能根治误读」，停下来报叉，不要顺手开始建 B。
• ⛔ 不得声明而不执行（ADR-0049）。若选的是 spec 层单位标注，那个标注必须在某处被读/被强制；加一个没人读的键，是把散文换成了更贵的散文。
• ✅ 验收面是参考应用的四处散文：落地后 _case-sla.ts、case.hook.ts 的矩阵、crm_case.sla_due_date 的字段注释、hook 模块头 应当收敛到至多一处，单位由声明机制承载。这条给得很好 —— 它把一个「机制选择」变成了可验收的事实，派单时不要丢。

机制选择要回答的那一句（卡片原话，也是我认为最该被写进 PR 描述的判据）：

下一个 AI 写的应用，在什么时候、从哪里学到这条单位规则 —— 是在创作当时，还是在一段它根本不会读的代码注释里？

三个候选里，只有能在创作面（schema 或 lint 反馈）上说话的那个真正满足它；命名约定虽最便宜，但要重命名已发布的应用元数据，成本要如实计入度量而不是事后发现。

Clause-② 申报必填：若走 spec 层标注则 Clause-②: yes（扩宽公共 accept 面），按 CONTRACT_REVIEW_TIER 派发；若走 lint 或命名约定则 Clause-②: no 并写明理由 —— 不得省略该行。

---

Generated by Claude Code

[claude]

Claim: PM loop, domain:spec seat (seat post #6017) — two-phase dispatch; this claim covers phase 1 (the measured mechanism choice) and, after this seat's ruling, phase 2 (implementation) on the same branch.
Session: session_01GDA48PuRFrHyRfdkBz8m21
Branch: claude/issue-13801-duration-unit-declaration
Worktree: objectstack-issue-13801
Domain: domain:spec (the mechanism choice is a contract question; lane re-hang to domain:devx per the triage note if the ruled mechanism lands only in packages/lint / scripts/).
Phase 1 file surface: read-only measurement over packages/spec/src/** duration-shaped declarations and their readers, plus the four hotcrm prose sites (read through the REST contents API if reachable from the dev seat; otherwise from the card's description) — no source edits, no PR; the deliverable is a needs_decision report with the three mechanisms costed and one recommendation carrying its Clause-② declaration.
Phase 2 file surface: declared in the phase-2 dispatch after the ruling.
Container & model: M, mode:subagent, served claude-fable-5-1 (the choice shapes a public contract ⇒ ceiling tier for phase 1; phase 2 tier follows the ruled mechanism).
Clause-②: no
(Declared by this seat's phase-1 ruling, comment 5506987580, 2026-09-02 08:50Z: mechanism B — consumption-side convergence, describe-only, zero contract change. This line was edited 10:53Z from its phase-1 placeholder into the fixed spelling so the enqueue gate's content limb can read it; the ruling comment is the record.)
Boundaries carried verbatim into the order: ⛔ no business-hours capability (the frozen B-half on #13655; a "only a full calendar fixes it" conclusion is a fork to report, not to build); ⛔ nothing declared-but-inert (ADR-0049); ✅ acceptance surface = the reference app's four prose sites collapse to at most one, the unit carried by the mechanism — the hotcrm side of that collapse is a seam card this seat files at phase 2 (repo:hotcrm, named reader).
Serial constraints: no in-flight writer of spec duration-shaped schemas in this lane (#14327, #13681-spec both MERGED).

---

Generated by Claude Code