feat(opportunity): REQ-0006 qualification, the customer calendar, narrative and approval on status change

[os-elon-musk]

Fixes #1916
Clause-②: no. The change is app metadata on crm_opportunity and adds one flow; it touches no published schema and no accept set.

REQ-0006 for crm_opportunity: the qualification block, the customer's procurement calendar, the deal narrative, a business line beside type, and an approval gate on the won/lost call that ships switched off. One changeset names REQ-0006 (.changeset/opportunity-qualification-and-status-approval.md, minor).

Every REQ-0006 acceptance line is delivered, with the evidence below. Every REQ-0006 field can be edited in the console, and pnpm verify is green on this branch at 5a67d080 (after #1953 raised the src/sales ceilings to 59,000 / 107,000).

What is on the branch

• Qualification (new group): Will Bid, Controllability, Priority, Deal Level, Involves Subcontracting, Subcontracting Note. The values are generic.
• Customer calendar (in Sales Process): Customer Initiation, Expected Tender and Expected Signing dates, plus the tender and signing amounts. None of them is folded into close_date.
• Deal Narrative (new group): Customer Background, Project Background, Risk Analysis, Payment Terms. All four are Field.textarea (see Editing surface).
• Business Line: a separate select beside type.
• Tender This Quarter list view: it windows expected_tender_date and never reads close_date.
• Status-change gate:
  • The parts: opportunity-status-change-approval.flow.ts, requested_status, status_change_approval_status, and a transition gate in opportunity_lifecycle.
  • The switch is that field's defaultValue, shipped as not_required. It is not the flow's status.
  • The rep writes the request. The approved decision writes the stage.
  • Untouched: the opportunity_account_capability hook (Track A · crm_account: registration identifier, a category that GATES capability, business profile, approval — REQ-0003 #1915), the two existing validations[], and opportunity-approval.flow.ts.

Acceptance, line by line

#	REQ-0006 acceptance	Evidence
1	The form renders a qualification group and a narrative group from fieldGroups alone	Browser, 17.6.0, fresh boot of 8333d7ee (served page sections equal to the compiled artifact and to source). The Details tab renders Classification, Campaigns, Sales Process, Qualification, Deal Narrative, Forecast & Metrics, Notes & Next Steps on a seeded deal and on a deal with only its required fields. The page references { group } only; nothing is enumerated. On a fresh boot of 033ba581, Details edit mode gave each of the three narrative fields an editor; typed values were saved, read back over REST, and shown after reload.
2	Customer-side dates reportable without touching close_date	Browser: Tender This Quarter opened on No Tenders Expected This Quarter. After one deal got tender date = today and close date = a year out, it listed exactly that deal. The filter names expected_tender_date only.
3	Gate on: won/lost opens an approval and the stage waits; gate off: amount-tiered behaviour unchanged	Gate on, 17.6.0, armed by flipping the default in a local, never-pushed copy: a new deal was born Pending. A direct close got 409 RECORD_LOCKED and the stage did not move. Requesting closed_won opened one flow:opportunity_status_change_approval request while the stage stayed negotiation. Approve moved the stage to closed_won with the verdict approved. Reject cleared the request and kept the stage; a direct close was still refused, and a re-request opened a fresh approval. Gate off, fresh boot of this branch: a direct close of a $5,000 deal succeeded, the verdict stayed not_required, and zero approval requests existed. A deal raised to $150,000 opened its usual flow:opportunity_approval request, and the new column stayed not_required. opportunity-approval.flow.ts is unchanged.
4	A writer with no session still engages the gate	test/opportunity-status-change-approval-gate.test.ts: fired with no trigger user, the flow passes get_opportunity and stops only at the approval node (the harness ships no approval executor). With runAs stripped, it fails at get_opportunity with the engine's [runAs] refusal.
5	No signing-entity or revenue-recognition field; business line generic	Neither field exists. business_line ships Product, Professional Services, Consulting, Support & Maintenance and Other.
6	pnpm verify green, and a changeset naming REQ-0006	os-verify-lock: VERDICT command-exit 0 on this branch at 5a67d080 (see Verification). The changeset .changeset/opportunity-qualification-and-status-approval.md names REQ-0006.

Editing surface (measured, 17.6.0)

• Details tab, pencil: puts the whole tab into an edit mode with a Save bar. Every new select, boolean, date, currency and textarea field is editable there (saved, then read back over REST). Markdown fields get no editor.
  • So Customer Background, Project Background and Risk Analysis moved from Field.markdown to Field.textarea (033ba581). That is the same declaration payment_terms uses, and one of the two types REQ-0006 names. The maintainer ruled it on 2026-10-03: 「改成 textarea(推荐)」.
  • All three now take input there; the probe values were saved and read back identical.
  • The object's own description stays markdown. It is outside this card and still has no editor in that mode.
• Edit / New dialog (the view's tabbed form): renders no tab for a { group } section. The same is true of the contact form's REQ-0004 buying centre on main. A markdown field that a form names does get an editor (the account dialog's Description).
• This branch keeps { group: 'qualification' } and { group: 'narrative' } in the form. That is rung 2, like the contact precedent. They wait for the renderer, and they are not routed around.
• The customer calendar is named on the form's Forecast tab, with its reason written beside it. tender_this_quarter filters on expected_tender_date, and test/metadata-references.test.ts requires a filtered field to be authorable in a form.
• ea40e43a also named Business Line and Requested Status on the form. 3a907d2e took them out again: Details edit mode covers both, and the ruling on this card refused per-field enumeration.

hideEmpty on the two new page sections

Both are hideEmpty: false, for the reason #1211 gives in PR #1991. Every member is something the seller is expected to write, none of them is in the highlights strip, and no deal that predates REQ-0006 carries any of them. Without the key, both sections would vanish on exactly the deals where a seller needs to fill them in.

Three defects fixed in the gate as built

Each was found by reading the gate against its siblings, pinned by the new runtime file, and ablated (every ablation went red in the direction decided beforehand, and each restore was proven to equal HEAD):

• A rejected deal was ungated. Only pending refused a direct close, so one rejection disarmed the gate for good. rejected now refuses too (as lead_automation does), and the flow re-opens from rejected on a new request. Ablation: 1 of 28 red, the "refused by an approver" case.
• The start condition tested the current value, not the transition. The fix requires a new requested_status on the write, guarded fail-closed, as billing_handoff_closed_won does. Ablation: 2 of 28 red.
  • Measured live, with the term deleted and the gate armed: one re-entry per request, caught only by the engine's self-trigger guard. With the term in place: no re-entry.
  • 92f90e28 said the second run "died on DUPLICATE_REQUEST". That was inferred, not measured, and 8333d7ee corrects the comment.
• The refusal code was APPROVAL_REQUIRED, which is not a platform ErrorCode. It is now RECORD_LOCKED / 409, the declared locked class. The hand-maintained refusal count goes from 20 to 21. Ablation: 4 red across the gate file and refusal-envelope.

Also in this round

• Merge of main (25cd8d78). docs/STATUS.md was recomputed from the merged tree's own pnpm validate: 18 Objects, 361 Fields, 31 Flows (main retired demo_bootstrap). One semantic conflict was resolved in the merge: the two new currency fields dropped scale, which 17.6.0 refuses outright (fix(objects): drop scale from every currency field — objectstack main refuses it #1968).
• The four locale packs: every field and option label, the view label and empty state, and the two section headings. lint:i18n-gate reads 0.
• Docs. New pages sales/opportunity-qualification{,.zh-Hans,.zh-Hant}.mdx. The automation pages get the new row, a 31 count and an Approvals paragraph. opportunities{,…}.mdx get the view row and section, the new groups and fields, and the Details tab described as the object's groups (the old "three sections, seven fields" sentence has been untrue since feat(record-pages): Details tabs reference the objects' fieldGroups (lead, opportunity, case) #1990). README now says 31 flows.
• Changeset: unchanged; the page change keeps it accurate.
• The nine red classes in comment 5695722225 are closed here, all but the ratchet (that one is chore(ratchet): raise the two src/sales token ceilings to their anchor() (59,000 / 107,000) #1953): locale packs, automation docs, view rosters, the refusal sweep count, runtime coverage, metadata-references, docs metadata counts and lint:i18n-gate. The refusal count was edited by hand (20 to 21) and stays hand-maintained, as that comment requires. No guard was skipped, disabled or loosened.

Token ratchet (src/sales)

scope	main 25cd8d7 (before #1953)	this branch 5a67d08	ceiling on main since #1953
business semantics	53,433	55,279	59,000 (headroom 3,721)
interaction layer	27,646	27,996	31,000
authored total	96,558	98,761	107,000 (headroom 8,239)

History: this PR started as a measurement. On 85e5dbd, against 087b7c5, it read 55,986 / 55,000 and 101,395 / 100,000, and #1951 ruling A answered it with 59,000 / 107,000 (PR #1953). No ceiling is raised here, no prose was compressed, and nothing was moved into an unmetered directory.

Verification

• This branch (5a67d080, after merging main 2e3a8b4d, which carries chore(ratchet): raise the two src/sales token ceilings to their anchor() (59,000 / 107,000) #1953, feat(profiles): tenant_admin gains the org-scoped presentation authority (manage_org_presentation) #1994 and chore(deps-dev): bump tsx from 4.23.12 to 4.23.15 #1963 with no conflict): OS_VERIFY_LOCK_SLOT=hotcrm-issue-1916 bash scripts/pm/os-verify-lock.sh -c 'git rev-parse --short HEAD && pnpm verify' gave os-verify-lock: VERDICT command-exit 0.
  • The chain: Validation passed (18 Objects, 361 Fields) · lint 1 warning(s), 17 suggestion(s) · 0 i18n/missing-* issues · source hygiene clean · source token ratchet clean · Build complete · Test Files 175 passed (175), Tests 3735 passed | 1 skipped.
• Before chore(ratchet): raise the two src/sales token ceilings to their anchor() (59,000 / 107,000) #1953 landed, a local, never-pushed merge of 033ba581 with chore(ratchet): raise the two src/sales token ceilings to their anchor() (59,000 / 107,000) #1953's head e7287a65 (a4b6743a) gave the same command-exit 0.
• Lint: 1 warning and 17 suggestions; main has 1 and 16. The 17th is the new approval node's "approvers may resolve empty" suggestion, the same class as its three siblings.

Acceptance notes

• Two platform gaps, filed upstream by the seat as Console 17.6.0: the tabbed Edit/New form dialog renders no tab for a { group } form section, and record:details edit mode offers no editor for a markdown field — so group-referenced fields and markdown fields have no editing surface objectstack#21543:
  • The tabbed form dialog drops { group } sections. This is visible today on the contact form's Buying Centre.
  • Details edit mode has no markdown editor. This card's fields no longer depend on it, but the object's own description still does.
• Not in this PR. REQ-0006's Disposition and Product response also name a step-11 qualification (立项) gate that blocks stage advancement. No acceptance line names it, and this card's title scopes only the status change, so nothing is built for it here. It is filed as follow-up card Track A · crm_opportunity: the 立项 (qualification) approval gate, which blocks stage advancement, bidding and won/lost until approved (REQ-0006 step 11), off by default #1995.
• Armed gate plus CPQ, not measured. quote_on_accepted closes the linked deal as won under the accepter's session. On an armed, pending deal that close would be refused by this gate.
• approved_date. The approving branch also stamps approved_date, the column the amount-tiered flow writes. A later status approval therefore overwrites an earlier amount approval's date. This is left as built.
• Stale docs sentence, not edited. opportunities.mdx's competitors bullet still calls the notes section "collapsible Description". That has been stale since feat(record-pages): Details tabs reference the objects' fieldGroups (lead, opportunity, case) #1990 and is outside this change.

Body rewritten 2026-10-03T05:06Z, after #1953 landed and this branch verified green at 5a67d080. It receipts PR comments 5695540995, 5695672077 and 5695722225.

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Oct 3, 2026 4:57am UTC

[os-elon-musk]

PM 说明：这两道红是预期的，⛔ 本 PR 不由施工席修，也 ⛔ 不重跑 CI

头 85e5dbd · 红的两道：Quality Checks、Build and Test (22.x)。PM 在本地逐条复现，成因只有两个：

① hygiene:tokens —— 本 PR 的阻塞物本身

✗ source token ratchet failed: 2 scope(s) over ceiling
  ✗ src/sales business semantics ~55,986 / 55,000  (超 986)
  ✗ src/sales authored total    ~101,395 / 100,000 (超 1,395)

同因连带 test/source-token-ratchet.test.ts 40 条里红 1 条。

这不是缺陷，是本 PR 的交付物。 本 PR 的目的就是把 REQ-0006 的完整实现写出来并量准，让缺口成为实测数字而不是推算。⛔ 抬天花板需要维护者裁决（scripts/check-source-token-ratchet.mjs 第 132-137 行），⛔ 不是施工席或 PM 能做的。

② lint:i18n-gate —— 132 条 i18n/missing-*，刻意未做

四个语言包故意没有编写。理由成立且 PM 采纳：语言包 ⛔ 不计入棘轮（src/sales/translations 是明文 EXCLUDED），而字段名册正是天花板裁决最可能改动的东西 ⇒ 现在写四份译文，裁决一改就得重写。

裁决在哪

决策卡 #1951（needs-user-decision · pm:blocking · p1）。四条路连同实测代价都在上面，含一条 #1928 时不存在的新选项。

⚠️ 顺带纠一处：57,000 / 103,000 这组数不符合 #1928 确立的 5% 缓冲规则（57,000 对 55,986 只有 1.8%）。按同一条 anchor() 应是 59,000 / 107,000。已写进 #1951。

PM 的处置

• 本 PR 保持 draft，⛔ 不翻 ready、⛔ 不挂自动合并、⛔ 不关闭 —— 完整实现在上面，量过、可复现，裁决一下来就能续。
• ⛔ 不重跑 CI —— 这两道红按构造就不可能变绿，重跑只是烧一次 runner。
• ⛔ 不为凑绿动任何守卫：⛔ 不跳过、不禁用、不隔离 source-token-ratchet.test.ts，⛔ 不改 i18n 门禁。
• Track A · crm_opportunity: the qualification group, milestone dates, subcontracting, narrative, and approval on STATUS CHANGE — REQ-0006 #1916 维持 pm:blocked，裁决落地后 PM 重新派发续做（届时四个语言包按最终字段名册一次写对）。

---

Generated by Claude Code

[os-elon-musk]

⚠️ 更正上一条：我写的「成因只有两个」是错的

上一条评论我写「PM 在本地逐条复现，成因只有两个」。那句话不成立。 我当时只复现了 hygiene:tokens 与 lint:i18n-gate 就下了结论 —— 那是定向子集，不是全量。

完整跑一次 pnpm test（本分支 85e5dbd，exit 1）：

Test Files  9 failed | 163 passed (172)
Tests      23 failed | 3667 passed | 1 skipped (3691)

准确清单（9 个文件 / 23 条）

文件	红	类别
test/i18n-references.test.ts	6	四语言包未编写
test/automation-docs-coverage.test.ts	5	新流程未进 content/docs/administration/automation.{mdx,zh-Hans,zh-Hant}
test/docs-view-rosters.test.ts	4	新视图 tender_this_quarter 未进文档名册
test/refusal-envelope.test.ts	3	新拒绝点未进那份手维护的清扫计数
test/source-token-ratchet.test.ts	1	阻塞物本身
test/lint-i18n-gate.test.ts	1	同四语言包
test/runtime-coverage.test.ts	1	新流程/hook 无运行时测试命名
test/metadata-references.test.ts	1	同上游
test/docs-metadata-counts.test.ts	1	文档所述计数与注册数不符

这改变了什么、没改变什么

⛔ 没改变：阻塞判断与缺口数字。上面 9 类里只有 source-token-ratchet 一条是计量面内的；其余八类动的全是 src/*/translations、content/docs/、test/ 与文档名册 —— 按裁决与按路径都不计入棘轮。⇒ business semantics 超 986、authored total 超 1,395，一个字不动。

改变了：裁决之后的收尾工作量。我上一条让人以为「裁完只剩四个语言包」，实际是四语言包 + 三处文档页 + 视图名册 + 拒绝清扫计数 + 运行时测试命名。这条我先前说少了。

责任在我，⛔ 不在施工席

施工席的报告明写「NOT MEASURED: full pnpm verify and CI, since hygiene:tokens fails inside it by construction」，并只声称「9 files / 314 tests 的定向子集里 2 条红」。它没有宣称全量绿。 是我把定向子集的结果当成了全量结论。

处置不变

• 本 PR 保持 draft，⛔ 不翻 ready、⛔ 不关闭。
• ⛔ 不重跑 CI —— 按构造不可能变绿。
• ⛔ 不为凑绿动任何守卫 —— 特别是 refusal-envelope.test.ts 那份手维护计数：它故意是手维护的（自动跟随的计数发现不了一个悄悄不再被清扫的守卫），⛔ 不许改成自动。
• 裁决仍在 [decision] REQ-0006 needs +986 business-semantics and +1,395 authored-total tokens in src/sales — cutting scope does NOT avoid the question (measured), and a third route now exists #1951。裁下来后重新派发，上述八类一次做全。

---

Generated by Claude Code