docs(contracts): write manual termination and sharing against the profiles and the status machine (#872)

[yinlianghui]

Fixes #872

Three sentences on the Contracts page, rewritten against src/ and the engine, in all three languages. Documentation only — src/** untouched, no guard added.

Premise re-verification (baseline includes PR #874)

This PR is cut from 6cd53d2e, which is #874's merge. All three sentences were relocated on that baseline and re-measured; all three premises hold.

#	Sentence	Issue said	On this baseline (same line in all 3 locales)	Premise
1	"The owner can change status to Terminated"	:120-121	:124	holds
2	"terminated contracts can't be reactivated"	:120-121	:124	holds
3	"The contract owner reads and edits their own contracts" (PM's addition)	—	:145	holds

• 1. src/profiles/sales-rep.profile.ts:52 grants crm_contract with allowEdit: false (read-only, readScope: 'own'). Only sales-manager.profile.ts:24 and system-admin.profile.ts:28 hold edit; the other four profiles do not grant the object at all. The owner is very often a rep: src/objects/quote.hook.ts:141-143 copies the quote's owner_id onto the contract quote_on_accepted inserts.
• 2. src/objects/contract.object.ts:258-273 — contract_status_progression, severity: 'warning', terminated: []. Engine re-read at node_modules/@objectstack/objectql/dist/core.mjs:2434-2441: only severity === "error" pushes onto errors (which then throws ValidationError); every other level takes the else branch, logs a warning, and the loop continues. The save proceeds.
• 3. Two independent gates. Object gate: @objectstack/plugin-security maps update to allowEdit and denies unless a permission set grants allowEdit or modifyAllRecords (dist/index.mjs:1742-1814). Record gate: @objectstack/plugin-sharing's canEdit (dist/index.mjs:1978-2003) — ownership within write depth, or an explicit write-level share. Its comment on the neighbouring canDelete states the direction outright: "sharing widens rows, never verbs". crm_contract is sharingModel: 'private' (contract.object.ts:19) and src/sharing/ carries no contract rule.

The subsection's third sentence — "Audit log records who and when" — was checked and kept: status carries trackHistory: true (contract.object.ts:95), as does owner_id (:45). The rewrite grounds it rather than dropping it.

Before and after

1 + 2 — Manual termination (:123-124 → :123-129). Before (EN): "The owner can change status to Terminated. This is a one-way action — terminated contracts can't be reactivated. Audit log records who and when." After: who may terminate is an object-level right that ownership does not extend; the gap lands on the common case because the accepted-quote hook stamps the rep as owner; and the dead end is declared at warning severity, so a revival is logged and saved anyway. Per the dispatch the advice semantics of "one-way" are kept — it is what the status means and how everything downstream reads it — but the page now says plainly that nothing enforces it and that enforcement is an admin's job.

zh-Hans and zh-Hant carry the same three paragraphs. Status names keep the form this subsection and its neighbours already use (*Terminated* / *Activated* italic); the CJK status vocabulary stays in Built-in rules, where #874 established it.

3 — Sharing (:145-146 → :151-152). Before (EN): "The contract owner reads and edits their own contracts" / "…edits stay with the owner except for admins." After, the first bullet separates the layers — ownership buys read, and whether you hold edit at all is settled earlier by the profile's object-level rights, so no sharing rule and no record share turns that read into an edit. The second bullet's trailing clause had to move with it: once the first bullet says the owner cannot edit, "edits stay with the owner" is a fresh self-contradiction on the same list. It is now a plain permission-table statement.

How this sits with #874 / #831

Nothing either PR wrote was reverted; the new text echoes without restating.

• Built-in rules :137 (docs(contracts): 按视图、选项集、hook 与 profile 写实合同页其余四处 (#832) #874) — "The status progression is advice, not a gate." carries the mechanism at length. Termination does not repeat it: it states the consequence for this transition and points at that bullet by name.
• Built-in rules :139 (docs(contracts): 按视图、选项集、hook 与 profile 写实合同页其余四处 (#832) #874) — "nothing stops an activated contract from being deleted": same defect class, and the closing move is deliberately parallel ("an admin has to author that"). Delete and edit stay distinct — Sales Manager holds edit and holds no delete, which both passages now say consistently.
• Tips for sales reps :172 / :174 (docs(contracts): 按视图、选项集、hook 与 profile 写实合同页其余四处 (#832) #874) — rep-facing advice. The new Sharing bullet is the mechanism behind it (object gate vs record gate), at a different altitude; termination ends on the same referral without re-teaching it.
• Sharing :153 (docs(contracts): 按到期/续约 flow 与 contract.object.ts 重写三语剩余三处失真 (#826) #831/docs: controlled_by_parent 可达范围按实测改写(#694 本仓侧纠偏) #699) — the "follows the account" paragraph is untouched.

Verification

Shared lock plus a 4 GB heap, all in this worktree.

Step	Exit	Key output
pnpm validate	0	✓ Validation passed (2407ms) · Data: 17 Objects 344 Fields · 5 pre-existing warnings, unchanged
pnpm typecheck	0	tsc --noEmit, no output
pnpm build	0	✓ Build complete (1486ms) · Artifact: dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66) · Tests 1587 passed, 1 skipped (1588)
pnpm lint	0	13 warning(s), 14 suggestion(s) — all pre-existing
pnpm hygiene	0	✓ no raw control bytes in first-party files · ✓ source hygiene clean

The ✗ source hygiene: scanned director(y|ies) missing lines inside the test run are that meta-test's own expected stderr.

Control bytes: this repo's scan is scripts/check-source-hygiene.mjs (via pnpm hygiene, covering 397 files under content and .changeset) — there is no check-nul-bytes.mjs here. An independent scan of the four changed files for 0x00-0x08, 0x0b, 0x0c, 0x0e-0x1f returned zero matches.

Prose only, so no pin test, and no @objectstack/* upgrade.

Filed separately, not fixed here

• Sales Manager 对 crm_contract 有 allowEdit 却没有写深度：报价自动起草的合同（挂在 rep 名下）只有 System Administrator 改得了 #880 — Sales Manager holds allowEdit on crm_contract but no writeScope, with modifyAllRecords: false, so the effective write depth is own; with no contract sharing rule anywhere, a manager cannot edit a contract a rep owns — only a System Administrator can. Same failure shape as Seeded contracts are ownerless at the platform level (owner_id null) — nobody, admin included, can edit one #622/campaign_leadership_* 的论证注释把 crm_campaign 说成 private-OWD，实际是 public_read —— 规则本身仍有用，理由是错的 #724 on two other objects. This is why this PR's wording stays at the object-gate altitude ("hold edit on it") instead of claiming a manager can terminate any contract. It does mean :174's referral is optimistic, which is for triage.
• contracts 的 zh-Hans / zh-Hant「共享」小节收尾段停在 #699 改写之前（controlled_by_parent 的 org-wide 实测结论只进了英文页） #881 — the Sharing section's closing paragraph is drifted across locales: docs: controlled_by_parent 可达范围按实测改写(#694 本仓侧纠偏) #699 rewrote the English one and did not carry it to zh-Hans / zh-Hant. Same shape as automation 的 zh-Hans / zh-Hant 缺了英文页「计划类自动化」节的第三段（#615 落地的预测分工说明） #836.

On #549: this PR describes only what is measured today. If #549 settles on a different account for the read side, this bullet should move with it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 2:34am

[yinlianghui]

[PM 更正] 本 PR 正文「Two findings filed separately」段引用的编号有误:文中写的 #875 / #876 实为并行 dev(#869 单)先行占用的编号(src/docs/crm_sales.md 经理声明 / sla-and-escalation 升级描述)。本 PR 实际立的两单是:

• Sales Manager 对 crm_contract 有 allowEdit 却没有写深度：报价自动起草的合同（挂在 rep 名下）只有 System Administrator 改得了 #880 — Sales Manager 对 crm_contract 有 allowEdit 但无 writeScope 且 modifyAllRecords:false,有效写深度为 own(正文所述「Sales Manager holds allowEdit … a manager cannot edit a contract a rep owns」对应此单)
• contracts 的 zh-Hans / zh-Hant「共享」小节收尾段停在 #699 改写之前（controlled_by_parent 的 org-wide 实测结论只进了英文页） #881 — contracts 的 zh-Hans/zh-Hant「共享」小节收尾段停在 docs: controlled_by_parent 可达范围按实测改写(#694 本仓侧纠偏) #699 改写之前(正文所述 locale drift 对应此单)

以更正后的编号为准。

---

Generated by Claude Code