docs(data-modeling): the field-type decision-tree flowchart routes "Secret value" to `password`, contradicting the same page's table, ADR-0100 and the shipped skill rule

[claude]

Found while deleting the duplicated ASCII decision tree from skills/objectstack-data/rules/field-types.md (#16324): before citing the docs page as the surviving carrier of that tree, its mermaid flowchart was read, and it routes credentials to the wrong field type.

The defect

content/docs/data-modeling/field-type-decision-tree.mdx line 36:

    TEXT -->|Secret value| T8[password]

That edge is the page's own answer to "what type holds a secret value", and it names password. Three sources in this repo say the answer is secret:

• The same page, 100 lines further down. Its quick-reference table, lines 138-139, reads password as "Masked on read; stored plaintext at rest (not hashed) - prefer secret for real credentials" and secret as "Reversible encrypted-at-rest value, masked on read", with api_key / db_password as the secret examples. Line 78 of the same flowchart even carries a second, correct edge: STRUCT -->|Sensitive secret value| S5[secret]. So the page contradicts itself inside one file, twice over.
• ADR-0100 (Accepted, 2026-07-18), docs/adr/0100-credential-field-channels.md - "Credential Field Channels - secret (encrypted) and password (masked)".
• The published skill rule. skills/objectstack-data/rules/field-types.md marks the password row with a warning: on a generic object the value is stored PLAINTEXT at rest, one-way hashing applies only inside the auth subsystem's identity tables, and secret is "The recommended type for credentials".

The runtime agrees with the three, not with line 36: packages/spec/src/data/object.test.ts:2367 pins warns once when a password field is declared on a generic object.

Why this is a card and not a note

It is an authoring trap with a data-at-rest consequence, and the flowchart is the first thing on the page - it is the surface a reader (human or agent) consults before reaching the table that corrects it. Following it yields a field that stores an API key or a DB password in plaintext, and the build then emits the warning the author was just steered into earning. The two nearby closed findings on this same docs tree, #14901 and #14940, are the same shape.

Repro

1. Open /docs/data-modeling/field-type-decision-tree.
2. Follow the flowchart from START through the Text? branch for a secret value. It lands on password.
3. Read the quick-reference table on the same page. It says to prefer secret.

Acceptance

• Line 36's edge names secret, or the Text? branch drops the credential edge entirely and leaves it to the already-correct STRUCT edge at line 78 - whichever keeps the flowchart readable.
• If the password type stays reachable from the flowchart at all, its label says what it is (masked-only, plaintext at rest) rather than "Secret value".
• Whatever lands is consistent with ADR-0100 and with the password / secret rows of the skill's own table.

Docs-only, no package publishes from it. Filed unassigned for triage.

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

分诊：domain:devx / Bug / priority:p2 / pm:queue

域 —— content/docs/data-modeling/field-type-decision-tree.mdx，按车道表 content/docs/** ⇒ domain:devx。非治理面 ⇒ 普通 PR。

当刻复核（origin/main）—— 四个来源全部对上，卡面一字不需要修正

content/docs/data-modeling/field-type-decision-tree.mdx:36   TEXT -->|Secret value| T8[password]        ← 缺陷
content/docs/data-modeling/field-type-decision-tree.mdx:78   STRUCT -->|Sensitive secret value| S5[secret]   ← 同一张图里的正确边
content/docs/data-modeling/field-type-decision-tree.mdx:138  | `password` | Masked on read; stored plaintext at rest (not hashed) — prefer `secret` for real credentials | `user_password` |
content/docs/data-modeling/field-type-decision-tree.mdx:139  | `secret`   | Reversible encrypted-at-rest value, masked on read | `api_key`, `db_password` |
docs/adr/0100-credential-field-channels.md:1                 # ADR-0100: Credential Field Channels — `secret` (encrypted) and `password` (masked)
packages/spec/src/data/object.test.ts:2367                   it('warns once when a password field is declared on a generic object', …)

⇒ 同一个文件里自相矛盾两次（:36 vs :78，:36 vs :138-139），且与 ADR-0100、与已发布 skill 规则、与一条运行时钉子测试全部相反。

类型 Bug，等级 p2

按类型判据「违背已声明契约 ⇒ Bug」：ADR-0100 是 Accepted 状态的已声明契约，这条边与它相反。

p2 而不是文档卡惯常的 p3，判据是后果落在静态数据上：

• 照 :36 走，作者得到一个把 API key / 数据库密码明文存在 rest 上的字段（:138 自己说的：stored plaintext at rest, not hashed）。
• 且这不是理论：object.test.ts:2367 钉着 build 会为此发告警 ⇒ ⭐ 作者被这张图引导去挣得一条警告，然后还得自己判断是图错了还是警告错了。
• ⭐ 位置放大了它：流程图是这一页最先出现的东西，而纠正它的表格在 100 行之后。人也好、agent 也好，都是先读图、图给了答案就不会再往下读。⇒ 可达面接近「每一个查这页的人」。

不到 p1：无运行时失败、无鉴权绕过、无既有数据被改；且 build 会告警（虽然是在作者已经写下之后）。

为什么不进决策箱

:36 与同一文件的 :78 已经给出了这个仓的既定答案（secret），ADR-0100 也已裁定过。⇒ 本卡不是在两种语义间选，是把一处与既定裁决相反的文字改回去。⛔ 无需维护者。

交给认领席

卡面的验收本席原样采纳，并补一条：

• :36 改成指向 secret，或让 Text? 分支干脆不出凭据这条边、交给 :78 那条已经正确的 STRUCT 边 —— 哪种更可读由认领席定。
• ⭐ 若 password 仍从流程图可达，它的边标签必须说清它是什么（masked-only、明文 at rest），⛔ 不能再叫「Secret value」。这是本卡的实质：问题不只是箭头指错，是标签把 password 描述成了 secret 的语义。
• 落地物与 ADR-0100、与 skill 表的 password / secret 两行保持一致。
• ⛔ 不要顺手改 skill（skills/objectstack-data/rules/field-types.md）—— 卡面说它当刻是对的（带警告、并注明 secret 是推荐类型），且它是治理面，带上就把 PR 转成终审四步。
• ⚠️ 行号会腐，按内容重新定位（Secret value 这个标签串当刻在文件里唯一）。

相邻

#16324（删除 skills/objectstack-data/rules/field-types.md 里重复的 ASCII 决策树 —— 本卡就是那次工作中读这一页时发现的）· #14901 / #14940（同一棵 docs 树上两条已闭的同形发现）。⇒ 无重复。

⭐ 顺带记一句给后来者：本卡的成因值得复用 —— 在把一个页面认定为"幸存的唯一载体"之前，先读它一遍。#16324 差一点就把重复的那份删掉、留下这份错的作为唯一来源。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[claude]

Claim: PM loop round 1
Session: session_012GKcPZbMoGq7WPzKLfRBTU
Branch: claude/issue-16366-secret-decision-tree-edge
Worktree: objectstack-issue-16366
Domain: domain:devx
File surface: content/docs/data-modeling/field-type-decision-tree.mdx (stop on breach; explain in the report)
Container & model: S mechanical, mode:subagent, model: sonnet — the floor tier (TIER_FLOOR). ⛔ Not the default: triage verified all four sources against origin/main and reported the card needs not one word corrected, the defect is a single mermaid edge, and the correct answer is already written twice inside the same file. There is no design judgement left to buy.
Clause-②: no
Reason for no: a documentation correction on a non-governed page. No schema, no authorable key, no published contract moves.
Thread-read: 5579447031
Serial constraints cleared: all 22 open PRs' changed-file lists fetched paged to exhaustion at 2026-09-08T11:4xZ and filtered for content/docs/data-modeling/field-type-decision-tree.mdx — zero hits; control, 22 of 22 returned a non-empty list.

---

Generated by Claude Code

[claude]

Dispatch: os-dev out 2026-09-08T11:4xZ · floor tier (triage verified all four sources on origin/main and reported the card needs not one word corrected) · branch claude/issue-16366-secret-decision-tree-edge · ⛔ scope is the docs page ONLY — skills/objectstack-data/rules/field-types.md is a GOVERNED customer-published surface and #16324 is already on it · ⛔ do not "fix" it by changing the table, the correct sibling edge, or ADR-0100 to match the wrong edge · ⛔ password is not being deprecated, only the routing of a SECRET value is wrong · A2 owed: the whole chart re-read against the table, other disagreeing edges listed or a stated zero · lock read FREE at 11:3xZ BEFORE dispatch (arriving depth 1)

---

Generated by Claude Code

[baozhoutao]

os-dev-report

{
  "issue": 16366,
  "status": "done",
  "branch": "claude/issue-16366-secret-decision-tree-edge",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16865",
  "premise_still_valid": true,
  "summary": "Removed the Text?-branch flowchart edge (`TEXT -->|Secret value| T8[password]`) in content/docs/data-modeling/field-type-decision-tree.mdx that routed a secret value to `password`, contradicting the page's own table, ADR-0100, and the shipped skill rule. Instead of relabeling the edge to point at `secret` (which would create a second, differently-labeled edge into the same node), the edge and its now-unused T8 style line were dropped outright, leaving the already-correct STRUCT-branch edge as the flowchart's sole answer for credentials. `password` type and its table row are untouched. Assignee arrived empty on pickup; PM-set field, not written by this session.",
  "tests": "38 gate families derived via `node scripts/pm/dispatch-gates.mjs --commands content/docs/data-modeling/field-type-decision-tree.mdx`. All 38 run; final --ran reconciliation: 38 derived, 38 run, 0 NOT-MEASURED, 0 UNRUN, at commit cfb6e98c1f. 5 families initially hit PREREQUISITE-NOT-MET / stale-build exits (check:docs, check:skill-examples, check:doc-formula-expressions, check:doc-security-posture, check:docs-transcript-drift) because a fresh worktree only had `pnpm install`, not builds; built @objectstack/spec, @objectstack/lint, @objectstack/client, @objectstack/client-react (dependency closure for client-react via `--filter '@objectstack/client-react...'`), then all 5 re-ran green. turbo ls --affected against BASE=12babac137 reports 0 affected packages (content/docs/** sits outside the turbo package graph, apps/docs is excluded from `pnpm build`) so gate family (1) build-closure is empty by that graph -- not a clearance, just outside the graph's blind spot; the actual relevant docs-family gates were derived and run directly via dispatch-gates, not via turbo affected. check:nul-bytes: EXIT=0. No changeset: content/docs/** is part of the private @objectstack/docs app; nothing publishes.",
  "mcp_calls": 4,
  "gates": "38/38 derived families green (commit cfb6e98c1f); see tests field for detail and the two prerequisite-build packages the fresh worktree needed before 5 of them could run.",
  "line_budget": "n/a — not a skills/** change; file diff is -2 lines (content/docs/data-modeling/field-type-decision-tree.mdx), no skill/token ratchet applies.",
  "deviations": "A2 (other disagreeing edges): zero. All 35 flowchart edges checked against their quick-reference-table rows (grep -n on the `-->|` edge lines); only the password edge disagreed, now fixed. Two omissions noted but NOT disagreements and NOT filed: the table's `code` (Structured Data Types) and `html` (mentioned only in the Decision Summary table) rows have no corresponding flowchart edge at all -- that is incompleteness (a missing enumeration member), a different defect class than a contradicting edge per repo scoping rules, so out of scope for this card.",
  "files_changed": [
    "content/docs/data-modeling/field-type-decision-tree.mdx"
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: content/docs/data-modeling/field-type-decision-tree.mdx's flowchart has no edge at all for the table's `code` type (Structured Data Types) or the Decision-Summary-table-only `html` mention -- incompleteness, not a contradicting edge, so a different defect class than this card's bug type; no PR or person currently positioned to pick this up (successor: none)"
  ]
}

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

REWORK — PR #16865 · the wrong answer is gone and now there is no answer

Reviewer of record: domain:devx @ objectstack seat, session_012GKcPZbMoGq7WPzKLfRBTU, 2026-09-08T12:0xZ. Patch round 1 of at most 2. ⛔ Not flipped, not armed.

What is right

The edge is gone, password and its table row are untouched, ADR-0100 and the quick-reference table were not bent to match the defect, and skills/** was correctly left alone. A2 was answered properly: all 35 edges checked against their table rows, one disagreement, now zero — and the two code / html omissions were correctly classified as incompleteness, a different defect class, and not filed. That is the right reading of the filing bar.

Why it cannot land as it stands

The chart's root branches on shape:

START([What kind of data?]) --> TEXT{Text?}
                            --> STRUCT{Structured Data?}

An api_key or a db_password — the table's own two examples for secret — is text. A reader holding one follows TEXT{Text?}, answers yes, and after this change finds no edge for a secret value at all. The only surviving secret edge hangs off STRUCT{Structured Data?}, a question that reader answers no to.

reader with an api_key, following the chart	lands on
before	password — wrong type, but they land somewhere, and the table 100 lines below corrects them
after this PR	nothing — the branch is mute on the case

⇒ The card's complaint was that the page routes credentials to the wrong type. This makes it stop routing them at all, on the branch where a reader with a string credential actually walks. That is not the fix the card asked for; it removes the symptom the card cited while leaving the page worse for the reader who prompted it.

⚠️ The stated reason for deleting rather than relabelling — that pointing the TEXT edge at secret "would create a second, differently-labeled edge into the same node" — does not hold. Two questions legitimately reaching one answer is ordinary in a decision tree, mermaid renders it without complaint, and here it is arguably the correct shape: a secret is reachable both as text and as structured data.

Required change

Point the Text branch at secret instead of deleting its edge — e.g. TEXT -->|Sensitive secret value| S5[secret] — so a reader who answers "Text? yes → is it a secret?" lands on secret. Restore the style line if the node id changes.

Your call, with a recommendation, ⛔ not a ruling: whether the STRUCT edge also stays. This seat would keep both — an api_key is text and a credential blob is structured, and both are true. If you would rather move it wholesale to TEXT, say why in the report and that is acceptable too; what is ⛔ not acceptable is the TEXT branch having no secret answer.

⚠️ Re-run A2 after the change: adding an edge can create a new disagreement, and the zero you established was measured on the deleted-edge shape.

Same claim, same branch, still draft.

---

Generated by Claude Code

[baozhoutao]

os-dev-report

{
  "issue": 16366,
  "status": "done",
  "branch": "claude/issue-16366-secret-decision-tree-edge",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16865",
  "premise_still_valid": true,
  "summary": "REWORK addressed (patch round 1 per coordinator comment 5584743486): round 1 had deleted the Text-branch credential edge outright; that left a reader who answers 'Text? yes' for an api_key/db_password with no secret-value edge at all, since the only surviving `secret` edge hung off `Structured Data?`, which such a reader answers 'no' to. Round 2 restores the Text-branch edge pointed at `secret` (`TEXT -->|Sensitive secret value| S5[secret]`) instead of dropping it, and keeps the pre-existing STRUCT->secret edge too, per reviewer's recommendation (api_key is text, a credential blob is structured, both true). S5 already had a style rule from the Structured branch so no new style line was needed. `password` type/table row remain untouched.",
  "tests": "38 gate families derived via `node scripts/pm/dispatch-gates.mjs --commands content/docs/data-modeling/field-type-decision-tree.mdx` (same 38 as round 1, same single file). All 38 run, all green at commit 856264d8b8; --ran reconciliation: 38 derived, 38 run, 0 NOT-MEASURED, 0 UNRUN. Fresh worktree (rebuilt from scratch for the rework) needed @objectstack/spec, @objectstack/lint, @objectstack/client, @objectstack/client-react built before 10 of the 38 (check:docs, check:skill-examples, check:doc-formula-expressions, check:doc-security-posture, check:docs-transcript-drift and related) could clear PREREQUISITE-NOT-MET; all 10 green after building. Repo also surfaced shallow (`git rev-parse --is-shallow-repository` = true) after the worktree re-add, which blocked the --ran reconciliation with 'no merge base'; `git fetch --unshallow origin` fixed it before reconciling. check:nul-bytes: EXIT=0. No changeset: content/docs/** is part of the private @objectstack/docs app; nothing publishes.",
  "mcp_calls": 3,
  "gates": "38/38 derived families green (commit 856264d8b8); round 1 had already established the same 38-family derivation for this file, so no re-derivation was needed, only a re-run against the new diff.",
  "line_budget": "n/a — not a skills/** change; file diff (both commits combined) is net -1 line (content/docs/data-modeling/field-type-decision-tree.mdx: -2 round 1, +1 round 2), no skill/token ratchet applies.",
  "deviations": "A2 re-run as required after the round-2 edit: 36 edges now (was 35 after round-1's delete). The new TEXT -->|Sensitive secret value| S5[secret] edge matches the `secret` table row (Reversible encrypted-at-rest value, masked on read; api_key, db_password examples) -- zero disagreeing edges, same result as round 1's audit but on the new shape, as required. `code`/`html` omissions: still noted-not-filed (unchanged from round 1's classification, which the coordinator confirmed was the right reading of the filing bar).",
  "files_changed": [
    "content/docs/data-modeling/field-type-decision-tree.mdx"
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: content/docs/data-modeling/field-type-decision-tree.mdx's flowchart has no edge at all for the table's `code` type (Structured Data Types) or the Decision-Summary-table-only `html` mention -- incompleteness, not a contradicting edge, so a different defect class than this card's bug type; no PR or person currently positioned to pick this up (successor: none)"
  ]
}

---

Generated by Claude Code

---

Generated by Claude Code