Proposal: Markdown-hosted NDF clauses that embed the owning ASL

[zhoubot]

Proposal: Markdown-hosted NDF clauses that embed the owning ASL

中文摘要：在带有可执行 owner 的项目（如 pto-spec）里，NDF 条款应该作为 Markdown 文件存放在 docs/ 中，并通过 embed 机制关联对应的 ASL 定义，而不是以注释区的形式塞进 ASCII-only 的 .asl 源文件里。Markdown 条款是给人看的描述层（可用完整 Markdown 结构、可中英文双语、措辞可自由改进），ASL 仍是行为的唯一规范性来源。为此格式需要新增：描述性锚点条款种类、条款级多语言正文与译文陈旧追踪、编辑性 vs 实质性修改的区分，以及带存在性校验的 ndf:embed 机制。

Motivation

In PTO-SPEC, executable ASL is the sole normative authority for instruction behavior and architectural state transitions. NDF clauses currently live as comment-only NDF-BEGIN regions inside the .asl sources. After rewriting a pilot batch of clauses for readability, three frictions became concrete:

1. Host-language constraints leak into the prose layer. ASL sources must stay ASCII for ASLRef compatibility, and region bodies must be plain comment lines. That rules out Chinese text, lists, tables, and rationale blocks — most of the clause anatomy in §4.2 is unusable where the clauses actually live.
2. Prose is forced into RFC-2119 clothing even though ASL owns the constraint. A clause describing an executable owner reads like requirement boilerplate ("X MUST implement the mnemonic-local canonical assembly, encoded legality, ..."), and any attempt to make it describe real behavior drifts toward a second normative statement, which the project explicitly forbids. What these clauses want to be is a human-readable description of what the entry defines.
3. The human-readable layer had to be invented outside the format. pto-spec maintains bilingual (en + zh-CN) per-clause summaries in a side JSON file with a custom checker. That layer is invisible to ndf query / ndf impact, carries no refines edges, and duplicates what the format's refinement ladder (§4.6, "all layers stay alive") already promises.

Proposal

Allow NDF clauses to be hosted in Markdown files under docs/, and let each clause embed its owning ASL instead of sitting inside it:

## ADD — scalar add {#PTO-ADD-DECISION-BINDING-001}
<!-- ndf: kind=contract level=L1 layer=scalar status=accepted binds=PTO-INST-SCALAR-ADD -->

本条目定义 32 位独立标量指令 ADD：汇编形式、五个编码字段、省略后缀时的默认值、
目的地与丢弃规则、顺序和异常边界。operation 区域是同一份定义的可执行形式。

This entry defines ADD, a standalone 32-bit scalar instruction: the assembly
form, the five encoded fields, the defaults for an omitted suffix, the
destination and discard rules, the ordering, and the fault boundary. The
operation region is the same definition in executable form.

<!-- ndf:embed source=asl/scalar/alu/ADD.asl region=operation -->

The compiler validates that the embed target exists, records the binds / defined-in edges, and splices the referenced ASL region into generated views. The Markdown clause is the human face; the ASL remains the only normative statement of behavior.

What the format would need to add

1. A descriptive-anchor clause kind. The prose is informative; normativity comes from the bound executable owner. The normative-keyword lint does not apply to this kind, and the body may freely summarize what the owner defines.
2. Clause-level multilingual bodies. Language-tagged segments (or parallel translations) with staleness tracking: when the source-language body changes, translations are flagged stale. Today every project reinvents this as side files.
3. Editorial vs. semantic change classes for release impact. Rewording a description or updating a translation is editorial (compatible), not breaking; only substance changes — or a changed/moved binding target — are breaking. The current "any body change is breaking" rule penalizes exactly the readability maintenance this proposal wants to encourage.
4. An ndf:embed mechanism. source=<path> region=<name> with existence and uniqueness validation, and deterministic extraction so the canonical graph never depends on generated splices.

What stays unchanged

• Stable clause IDs, the tree/graph/history discipline, exact-commit dependency pinning.
• The ASL adapter continues to index PTO-INSTRUCTION / PTO-STATE / in-source NDF regions for projects that keep clauses inside ASL comments; Markdown hosting is additive, not a migration mandate.

pto-spec is willing to pilot this layout across its ~400 explicit clauses and report back on tooling needs.