[Task]: Signal a vocabulary decision when a term is coined, not only after the tree is scanned

[DJC1412]

Task ID or area

area: semantics / control-plane vocabulary — coin-time decision signal (follow-up to #4447)

Technical direction

Core control-plane hardening; Architecture and research incubator

Intent

Open the question #4447's 2026-09-18 tracker update named but deliberately did not track: "how an agent notices it is coining a new term and decides whether it should". That update states the acceptance test — can an agent coining a term in the unregistered majority get a signal? — and says it needs its own issue rather than another milestone on the convergence tracker. This is that issue. It is a design request for maintainer direction; I am not starting implementation before one.

Credit where the measurement is due: the census numbers below are @songoow's, recomputed on 092a28c4e in that comment. Everything marked measured here I re-ran on current main myself.

Goal and acceptance gap

The apparatus classifies a shared vocabulary after it has already drifted. Nothing asks the question at the moment the term appears.

Measured here on current main:

• loopx/semantics/vocabulary_v0.json registers 26 vocabularies, each carrying meaning, tier, status, owners, values, value_notes; coverage_floor records vocabularies: 26, owner_symbols: 51, literal_scan_fields: 1. Only 6 declare producers and 1 declares literal_scan — consistent with the tracker's "6 carry producer evidence (0.9%)" against 664 vocabulary carriers in the tree.
• The disposition taxonomy already exists and is already validated for shape: formal_model.candidate_decisions = compatibility_only, create_vocabulary, extend_vocabulary, external_input, local_only, reuse_existing, unknown, default unknown. Its own meaning says it is advisory with "no per-candidate storage or runtime enforcement".
• The string candidate_decision occurs in the registry exactly once — at its own definition. No vocabulary records the disposition it was admitted under.
• The one live consumer is review-time, not coin-time: loopx/capabilities/pr_review_queue/result_check.py:158 reads candidate_decision, and that capability's README requires it for aligned / new_semantics_justified / advisory / not_yet_proven rows. So the label is asked for when a change is already up for review.
• The instruction surfaces that every agent reads before writing code mention vocabulary governance 0 times: grep -ci vocabular → AGENTS.md 0, CONTRIBUTING.md 0, docs/development/testing-and-quality.md 1.
• The only firing check is the full-tree scan at commit/premerge/CI time. On a source checkout without npm ci --ignore-scripts, examples/semantic-vocabulary-drift-smoke.py does not even reach a verdict: it aborts after ~9s inside loopx/semantics/production.py:140 with TypeScript production parser failed. A coin-time signal that inherits that dependency cannot run where agents actually work.

So the gap is not a missing enum, a missing scanner, or a missing document. It is that the only moment the system speaks is after the term exists in code, reviewed by someone else, at full-tree cost — and on some machines not at all.

Proposed scope

Three boundaries, each independently testable, and none of them a fourth scanner revision (#4447 rules further scan precision out of scope; the existing apparatus is already ~4,145 lines of scanner plus ~4,123 of its own tests plus a ~3,506-line bilingual RFC, and it has repaid 7 forked names and 17 duplicate definitions).

1. Registration admits a disposition. A vocabulary entry in vocabulary_v0.json carries which candidate_decisions value it was coined under, validated by the check that already validates that file. This closes "the taxonomy is defined and used zero times" without new machinery, and it keeps coverage_only_grows honest because a new create_vocabulary is then distinguishable from an extend_vocabulary after the fact.
2. A diff-scoped probe, not a wider scan. Reuse the on-demand inventory the RFC's Q9 already chose: given changed paths, report newly-appearing classification literals that collide with or duplicate a registered vocabulary's value set, and print the disposition question. Cost proportional to the diff. Explicitly not: a resident watcher, a new store, or a second source of vocabulary truth.
3. Say it where agents read. One obligation paragraph in AGENTS.md (and the matching pointer from CONTRIBUTING.md): coining a state-classification or protocol literal names its disposition and reuses an existing owner or justifies a new one. Whether that is machine-enforced or guidance must be stated as such in the text, per the repository's own guidance-versus-obligation rule — I would start with guidance plus the probe, and only promote to enforced once the probe's false-positive rate is measured.

Decisive acceptance question, in the form the tracker asked for: can an agent coining a term in the unregistered majority get a signal, does it arrive before the commit-time full-tree scan, and what does it cost? A fixture answers the first two; a timed run against a changed-files set answers the third.

Intended base branch

main.

Relevant files or commands

• loopx/semantics/vocabulary_v0.json (formal_model.candidate_decisions, coverage_floor, policy)
• examples/semantic-vocabulary-drift-smoke.py (registry shape validation today)
• scripts/generate_semantic_inventory.py (the on-demand inventory Q9 selected)
• docs/architecture/rfcs/semantic-vocabulary-convergence-v0.md (+ .zh-CN), §10 policy record
• AGENTS.md, CONTRIBUTING.md, docs/development/testing-and-quality.md
• loopx/capabilities/pr_review_queue/result_check.py (existing candidate_decision consumer)

Validation plan

Not executed — this issue proposes, it does not deliver. The plan for whichever slice is admitted:

Slice	Decisive validation
Registry disposition	examples/semantic-vocabulary-drift-smoke.py green with the field present, plus a mutation case: a vocabulary whose admitted_as is not one of the seven values fails closed. Existing 26 entries keep passing without rewriting history.
Diff-scoped probe	A synthetic changed-file that coins a term colliding with a registered value set produces the disposition question and exits non-zero; the same file with an explicit reuse_existing justification passes. Timed against a normal-size diff and reported.
Instruction surfaces	examples/docs-governance-smoke.py plus the existing locale-parity check, and the public/private scan over the changed doc paths.
Cross-cutting	tests/architecture/, and one run on a checkout without npm ci so the probe's dependency floor is explicit rather than assumed.

Public/private boundary

• This issue does not include private benchmark traces, verifier output, credentials, internal document links, raw agent sessions, or local runtime state.
• I will not run or duplicate maintainer-owned benchmark cases unless a maintainer explicitly splits out a public task.

Questions for the owner and @songoow

1. Is the registry-disposition field (1) welcome as a standalone first PR, or should it wait for (2) so the value is produced by a real caller rather than back-filled?
2. Should the probe live behind loopx check, behind the existing inventory script, or as a pr_review_queue input — the last option reuses the consumer that already asks for candidate_decision at review time.
3. Guidance or enforcement for AGENTS.md: the review lenses flag prose-only obligations, so I would rather state it as guidance plus a machine-checked probe than write a machine-enforced-sounding sentence that nothing enforces.

[songoow]

Thanks for splitting this out. I support the direction: the decision prompt should arrive when a developer or agent introduces new semantics, not only at the commit-time full-tree scan.

My suggestion is that the first version should be built around one development-time prompt loop that is actually called, and that the registry field should not be the starting point. Answering your three questions in order, with the code I checked.

---

1. admitted_as should not be the standalone first PR

candidate_decision describes a choice made in one specific change, not a permanent property of a vocabulary.

The same vocabulary can be create_vocabulary when introduced, extend_vocabulary when a value is added later, and reuse_existing when a third module adopts it. Those are three different decisions about three different changes; a single static field on the entry cannot hold them without losing which change it refers to.

There is a second reason, which I ran into while working on the source-closure side of #4447. The seven candidate_decisions values are doing two different jobs:

external_input · compatibility_only · local_only · unknown      ← where a value comes from  (backward-looking)
reuse_existing · extend_vocabulary · create_vocabulary          ← what this change decided   (forward-looking)

A source_class is plausibly a stable property of an entry. A coinage decision is not. Putting the combined enum on the entry as admitted_as would make those two axes indistinguishable at exactly the point where they need to be told apart.

So for the first version: record the decision and its reason in the existing PR/review evidence, reuse the existing taxonomy, add no persisted ledger, and do not back-fill unverifiable historical decisions onto the 26 existing entries.

If, after real use, there is a genuine need to answer "why was this vocabulary originally created", then consider a field with a stated meaning — and say whether it records the first introduction or one later change. Please don't add a field with no caller just to move the taxonomy's usage count off zero.

2. Put the probe in the existing inventory script as an explicit advisory mode

I checked the entry point. scripts/generate_semantic_inventory.py:87 calls build_inventory(ROOT) — full tree — but the underlying function already takes a source list:

def build_inventory(
    repo_root: Path, root: str = DEFAULT_ROOT, sources: list[SourceFile] | None = None
) -> dict[str, Any]:
    if sources is None:
        sources = load_sources(repo_root, root)

So the extraction capability is reusable. The development-time mode should branch before the full-tree scan, not compute the whole inventory and then filter to changed paths — otherwise the cost is unchanged and only the output is narrower.

For the first version I would bound it to:

• Compare a named baseline against the working tree and index, reading old/new content for changed files.
• Let the developer explicitly name new source files not yet in the Git index, without sweeping in ignored files, private notes or runtime directories.
• Use the existing registry for owners and possible reuse hints.
• Report: candidate location, enclosing symbol or slot, what changed, any related owner, and the disposition question to answer.

Worth keeping separate: working tree, index, and untracked files are three different input ranges (git diff, git diff --cached, git ls-files --others). A probe that only looks at staged files will miss exactly the case this issue is about — the file an agent just created.

loopx check can wrap this later if there is demand; pr_review_queue can consume its output — but it should not be the only entry point, or the prompt still arrives at review time, which is the gap you are closing.

On cost: I would replace "proportional to the diff" with something measurable — report the enumeration of Git changes, the registry read, and the old/new extraction of changed files separately. Don't promise cost scales only with added lines, and don't require keeping a full-tree snapshot that can go stale.

This mode does not replace the full-tree check, and does not change its scan root, budgets or coverage obligations.

3. The prompt must not be limited to "resembles a registered vocabulary"

This is the part of the acceptance I think most needs widening.

Suppose an agent adds an unregistered state set that resembles nothing in the registry. The tool should still ask, within its supported syntax:

This is a new classification set. Should it reuse an existing owner, extend an existing vocabulary, stay local, or become a new shared contract?

So I would separate two things:

Candidate discovery — within bounded supported forms, find new carriers or new values on existing carriers.
Reuse hints — for each candidate, look for registered contracts with matching or overlapping values, names or slots.

No match does not mean no candidate. Identical strings or identical value sets do not mean identical semantics.

The first version can support only what the existing tooling already recognises reliably — Enum, Literal, named closed sets, bounded TypeScript forms. For unsupported syntax, dynamic construction or unclear slots, print the scope limit or mark it for human judgement. Do not render "not extracted" as "no new semantics."

4. Guidance plus advisory, with exit codes that match the wording

I agree the first version should not add a semantic gate. I would make the three cases explicit:

Situation	First-version behaviour
Probe runs, finds candidates or undecided semantics	print the prompt, exit 0
Unsupported analysis form encountered	print the unanalysed scope, do not claim completeness
Bad argument, missing baseline, unreadable file, internal failure	non-zero, never a clean-looking empty report

This means I would change the validation-plan row that says "produces the disposition question and exits non-zero; the same file with an explicit reuse_existing justification passes."

Writing a justification only records that a decision was proposed. Actually importing the existing owner is what makes reuse observable. Keeping a separate definition with a stated reason is a legitimate outcome, but the candidate and its reason should still be shown. The tool should not hide a candidate because the word reuse_existing appeared next to it.

For the same reason I would not add a # semantics: ignore style suppression marker in the first version.

Promoting this to blocking later needs its own review of detection scope, false positives, false negatives, usage cost and an appeal path — not "we ran it a few times and saw no false positives."

5. The no-npm requirement should be validated through a real path

I would have the first version reuse bounded extraction that does not depend on the TypeScript production parser, rather than invoking the full drift smoke to produce an early hint.

Where a TypeScript form has no reliable support, say "bounded-mode candidates" or "this part was not analysed" — do not claim full TypeScript parsing succeeded, and do not install npm dependencies as a side effect of running the command.

Acceptance should check more than "the command exits without node_modules": it should check that it still produces useful signal for the forms it claims to support, rather than skipping all analysis and returning success.

6. The first PR should ship probe, guidance and a closed loop together

I would not split this into "field first, then docs, then finally a caller." A small but complete slice:

bounded development-time probe + a short AGENTS.md guidance paragraph + a CONTRIBUTING.md pointer + focused tests.

Cases worth covering:

Case	Expected
Copy a registered value set into a new file	prompt the candidate and possible owner; do not declare synonymy
New state set matching nothing in the registry	still prompt for a classification decision
Add a value to an existing unregistered set	detect the addition within supported forms
Two domains coincidentally share a value set	offer the similarity hint; do not demand a merge
Actually switch to importing the existing owner	distinguishable from keeping the duplicate and only writing a reason
Unsupported syntax, untracked file, missing dependency	scope and result stated, never silently treated as clean
Comment or ordinary prose edits	do not promote every string into a shared-semantics obligation

And one real usage check: give another agent a task that introduces an unregistered classification, let it read only the repository guidance, and observe whether it invokes the probe before committing, receives the prompt, and states its decision.

If the result is only visible when a tester runs the tool by hand, call it "a manually invocable development-time prompt" — not automatic coin-time notification.

---

On the review-time consumer

Your reading of result_check.py matches what I see. It validates the shape and internal consistency of the review evidence — that candidate_decision is one of the seven, that unknown cannot claim alignment, that not_applicable cannot pair with extend_vocabulary / create_vocabulary / compatibility_only — and it returns "evidence_truth_verified": False at line 259.

So reusing that taxonomy for the new prompt is reasonable, but a valid label must not be read as proven semantic correctness, and the probe must not treat "a label was supplied" as a reason to stop reporting.

---

Summary

Build the minimum prompt loop first; hold off on admitted_as; add no gate; do not widen #4447's closure scope.

The success criterion for this issue should be: an unregistered new concept has the right reuse-or-create question raised before it reaches the commit-time full-tree scan, and the agent knows where to run it, what the result does and does not establish, and what it cost. Not one more registry field, and not every new term being pushed into the central registry.

These are scope suggestions; the actual boundary is the maintainers' call.

[songoow]

中文版,与上一条英文回复为同一内容的镜像。

感谢把这个问题从 #4447 里独立出来。我支持这个方向:应当在开发者或 Agent 引入新语义的那一刻给出复用或新建的决策提示,而不只是等到提交期的全树检查。

我的建议是:第一版围绕一个真正被调用的开发期提示闭环来做,registry 新字段暂时不作为起点。按你提的三个问题依次回答,并附上我核对过的代码。

---

1. admitted_as 不宜作为独立的第一个 PR

candidate_decision 描述的是某一次具体变更中做出的选择,不是词表的永久属性。

同一个词表在首次引入时是 create_vocabulary,后来加值时是 extend_vocabulary,第三个模块采用它时是 reuse_existing。这是针对三次不同变更的三个不同决定;条目上的单个静态字段装不下,而且会丢掉"它指的是哪一次变更"。

还有第二个理由,来自我在 #4447 来源闭合那一侧的工作。七个 candidate_decisions 值实际上在做两件事:

external_input · compatibility_only · local_only · unknown      ← 值从哪来(回顾性)
reuse_existing · extend_vocabulary · create_vocabulary          ← 这次变更决定了什么(前瞻性)

source_class 可以合理地成为条目的稳定属性,造词决定不行。把合并后的 enum 当作 admitted_as 挂到条目上,恰好会在最需要区分这两个轴的地方把它们混掉。

所以第一版建议:把决定及理由记录在已有的 PR/评审证据中,复用现有分类,不新增持久化账本,也不为现有 26 条回填无法验证的历史决定。

如果实际使用之后确认需要回答"这个词表最初为什么被创建",再考虑一个含义明确的字段,并说明它记录的是首次引入还是某一次变更。请不要为了让 taxonomy 的使用次数从零变成非零,先加一个没有调用方的字段。

2. 探针放进现有 inventory 脚本的独立 advisory 模式

我核对了入口。scripts/generate_semantic_inventory.py:87 调的是 build_inventory(ROOT)(全树),但底层函数本身已经支持传入源码列表:

def build_inventory(
    repo_root: Path, root: str = DEFAULT_ROOT, sources: list[SourceFile] | None = None
) -> dict[str, Any]:
    if sources is None:
        sources = load_sources(repo_root, root)

所以提取能力是可复用的。开发期模式应当在全树扫描之前分支,而不是先算完整个 inventory 再按 changed paths 过滤 —— 否则成本没变,只是输出变窄了。

第一版建议限定为:

• 比较指定基线与工作区/暂存区中的改动文件,读取必要的 old/new 内容。
• 支持开发者显式指定尚未加入 Git 索引的新源码文件,但不自动扫入被忽略文件、私有笔记或运行时目录。
• 使用现有 registry 提供 owner 和可能的复用线索。
• 输出:候选位置、所在符号或槽位、变化内容、可能关联的 owner,以及需要回答的 disposition 问题。

值得单独强调:工作区、暂存区、未跟踪文件是三个不同的输入范围(git diff、git diff --cached、git ls-files --others)。只检查已暂存文件的探针,会漏掉这个 issue 正要解决的那个场景 —— Agent 刚刚创建的新文件。

loopx check 后续确有需求时可以包装它;pr_review_queue 可以消费它的输出 —— 但不应成为唯一入口,否则提示仍然发生在评审阶段,而那正是你要补的缺口。

关于成本,建议把"与 diff 成正比"改成可验证的口径:分别测量 Git 变更枚举、registry 读取,以及改动文件 old/new 内容的提取成本。 不应承诺成本只与新增行数相关,也不应要求保存一个可能过期的全树快照。

这个模式不替代现有全树检查,不改变其扫描根目录、预算和覆盖义务。

3. 提示对象不能只限于"与已注册词表相似"的内容

这是我认为验收部分最需要放宽的地方。

假设 Agent 新增了一个未注册的状态集合,而它和 registry 里任何词表都不相似。工具仍然应当在其明确支持的语法范围内提问:

这是一个新的分类集合。它应该复用现有 owner、扩展已有词表、保持局部定义,还是引入新的共享契约?

所以建议把两件事分开:

候选发现 —— 在有界的支持形式内,发现新增 carrier 或已有 carrier 的新增值。
复用线索 —— 为每个候选寻找与已登记契约相同或重叠的值、名称、槽位。

没有匹配结果,不等于没有候选;字符串相同或值集相同,也不等于语义相同。

第一版可以只支持现有工具已能可靠识别的形式 —— Enum、Literal、命名闭集、有限的 TypeScript 形式。对不支持的语法、动态构造和不明确槽位,输出范围限制或标记待人工判断。不要把"没有提取到"显示成"没有新增语义"。

4. 第一版 guidance + advisory,退出码与表述保持一致

我同意第一版不增加语义门禁。建议把三种情况明确区分:

情况	第一版行为
探针正常执行,发现候选或尚未决定的语义	输出提示,正常退出
遇到不支持的分析形式	明确输出未分析范围,不声称检查完备
参数错误、基线不存在、文件读取失败、工具内部故障	非零退出,绝不返回一个看似干净的空报告

因此,验证计划里那条"发现候选就退出非零,填写 reuse_existing 理由后通过"建议修改。

填写理由只能说明提出了一个决定。真的改为导入现有 owner,才构成可观察的复用;保留独立定义但说明理由,仍然是合法结果,但该候选和理由应当照常显示。工具不应因为旁边出现了 reuse_existing 这个词,就把候选隐藏掉。

同样,不建议第一版增加 # semantics: ignore 一类豁免标记。

后续是否提升为阻断,需要另外评审检测范围、误报、漏报、使用成本和申诉路径 —— 不能仅凭"试过几次没有误报"。

5. 无 npm 的运行要求,应通过真实路径验证

建议第一版优先复用不依赖 TypeScript production parser 的有界提取能力,而不是调用完整 drift smoke 来获得一个早期提示。

如果某类 TypeScript 语法没有可靠支持,应明确显示"有限模式的候选提示"或"该部分未分析",不能声称完整 TypeScript 解析已经成功,也不应在命令执行时自动安装 npm 依赖。

验收不能只确认"没有 node_modules 时命令能退出",还要确认:它对所声明支持的形式仍然能产生有用信号,而不是跳过所有分析后返回成功。

6. 第一份实现 PR 应同时交付探针、简短指引和闭环测试

建议不要拆成"先加字段""再加文档""最后才有调用者"。做一个范围很小但完整的切片:

有界开发期探针 + AGENTS.md 的简短 guidance 段落 + CONTRIBUTING.md 指针 + 聚焦测试。

至少覆盖:

测试情形	期望
在新文件中复制一个已登记值集	提示候选及可能的 owner,不自动宣布同义
新建一个完全不匹配 registry 的状态集合	仍然提示需要作出分类决定
给一个未注册的既有集合增加值	在支持形式内能发现这次新增
两个不同领域恰好使用相同值集	提供相似线索,不自动要求合并
实际改为复用现有 owner	能区别于"仍保留重复定义、只填写理由"
不支持的语法、文件未跟踪、依赖缺失	范围和结果明确,不静默当作无问题
修改注释或普通文案	不把所有字符串都升级成共享语义义务

另外增加一次真实使用验收:给另一个 Agent 一个引入未注册分类的开发任务,只让它读取仓库指引,观察它能否在提交前调用探针、收到提示并说明决定。

如果只有测试人员手动运行工具才能看到结果,应如实称为"可手动调用的开发期提示",而不是已实现自动的 coin-time 提醒。

---

关于评审期那个消费者

你对 result_check.py 的读法与我看到的一致。它校验的是评审证据的形状与内部一致性 —— candidate_decision 必须是七个值之一、unknown 不能声称 alignment、not_applicable 不能与 extend_vocabulary / create_vocabulary / compatibility_only 搭配 —— 并在第 259 行返回 "evidence_truth_verified": False。

所以为新提示复用这套分类是合理的,但标签合法不能被读成语义正确已经得到证明,探针也不应把"提供了一个标签"当作停止报告的理由。

---

归纳

先做最小提示闭环;暂不增加 admitted_as;不新增阻断;不扩大 #4447 的关闭范围。

这个 issue 的成功标准应当是:一个未登记的新概念,在进入提交期全树检查之前,被提出了正确的复用/新建问题,而且 Agent 知道去哪里运行、结果能说明什么、成本是多少。 不是多登记一个字段,也不是让所有新词都必须进入中央 registry。

以上是实现范围建议,具体边界请维护者确认。