docs(governance): publish current technical directions

[huangruiteng]

Summary

• add a bilingual canonical map for LoopX's current technical directions,
  maturity vocabulary, contribution routes, and promotion gates;
• route README, docs navigation, contributor guidance, issue/PR templates,
  CODEOWNERS, support, and governance back to that map;
• replace the stale task-board direction summary and priority rows with the
  current programs and live work state;
• regroup the RFC index into accepted architecture, active research, drafts
  under review, and draft integration proposals;
• extend the durable docs-governance smoke so discovery, stage vocabulary,
  tracker identity, and RFC grouping cannot silently drift.

The matching GitHub governance surfaces are already live:
#3243,
#3244,
#3245, and
#3246, with four
direction/* labels applied to representative RFCs, issues, and integration
PRs. The pinned Discussion will be refreshed after this repository truth
merges.

Product And Architecture Judgment

The contributor problem is not a lack of roadmap prose; it is the absence of
one visible relationship between strategic outcome, maturity, implementation
location, authority boundary, and claimable work. This change keeps that
relationship in versioned repository docs and makes GitHub Discussion a
projection rather than a second roadmap.

The map deliberately treats frontend/IM as an incubation program rather than
shipped main behavior, recognizes @maxliux5 as the current implementation
lead without implying maintainer authority, and names the NoKV direction
Shared Goal Authority and Cross-host Coordination rather than a shared
metadata database. Effect Program is listed as accepted/hardening while the
remaining RFC portfolio keeps its actual Draft or Research status.

No runtime behavior, permissions, release contract, benchmark scoring, or
first-visible README viewport changes are included.

Validation

• python3 examples/docs-governance-smoke.py — passed
• uvx --from mkdocs-material mkdocs build --strict — passed
• focused loopx check --scan-path ... over all changed public files — 0 scan
  errors; two unrelated owner-local runtime-state warnings were not repository
  findings
• loopx canary premerge --from-git-diff --tier quick — passed, including
  diff hygiene, Python compile, three selected catalog canaries, and the public
  boundary scan
• git diff --check origin/main...HEAD — passed

Public / Private Boundary

Ignored issue, Discussion, and PR body drafts plus the generated MkDocs build
were excluded. No credentials, private state, raw benchmark evidence, local
paths, generated logs, or provider payloads are in the diff.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

精确评审头（Exact Head）: 3248@faeda21ce95f4b819eaa44e5372cfe9a7fa7f737
Base: main | 类型: docs/governance + smoke（17 files, +633/-92） | 作者: huangruiteng（owner，GitHub 阻止正式 self-approval，故以 COMMENTED 记录 APPROVE 结论）

---

详细中文评审

动机

仓库此前缺少一份「maintainer 维护的当前技术方向地图」：CONTRIBUTOR_TASKS 里的方向描述、RFC 索引的 Active Drafts 分组、README 的 milestones 段落各自为政，贡献者难以判断哪个方向活跃、成熟度如何、能否认领。PR 用一个版本化地图统一战略方向、成熟度词表、tracker、promotion gate 与贡献入口，并让 RFC 索引按状态分组、任务板/模板/治理文档都指向同一事实源。动机真实：这是把「方向叙事」与「可执行贡献」接起来的正确信息架构层，就近小修（再改一版任务板）无法消除多份方向事实源。

改动思路

主线：新 docs/project/technical-directions.md（+153，中文镜像 +134）定义 5 个成熟度词表（Shipped/hardening、Incubating/qualification、Active research、Draft、Held）、4 个战略方向（长程 benchmark 证据、Operator Surface/IM、Shared Goal Authority、架构与研究孵化器）+ 稳定底座，并给出每个方向的 tracker、stage、贡献入口与边界；README 在 482 行后加「Current Technical Directions」入口；GOVERNANCE 增加 Technical Direction Governance 一节；RFC 索引从「Active Drafts」平铺改为 Accepted Architecture / Active Research Programs / Drafts Under Review / Draft Integration Proposals 四组；CONTRIBUTOR_TASKS 改为按方向分组的可认领板；issue/PR 模板增加 direction 路由与 base branch；docs-governance-smoke 增加对应的持续断言。整个改动刻意把「方向」与「权限/事实」分离：tracker 不是 blanket 授权，Discussion 不覆盖仓库事实，NoKV 是未晋级 provider candidate。

具体改动

• docs/project/technical-directions.md / .zh-CN.md：方向地图主体（+153/+134）。
• README.md / README.zh-CN.md（+35/-4 / +31/-2）：新增方向段与 Project and Community 链接；改动从第 482 行起，Hero/首屏未动。
• .github/GOVERNANCE.md（+29）：Technical Direction Governance 规则（tracker 语义、地图更新 PR 义务、Discussion 投影边界、direction/* label 只路由不授权）。
• docs/architecture/rfcs/README.md（+64/-21）：RFC 索引按状态重组为 4 组。
• CONTRIBUTOR_TASKS.md（+28/-45）：方向化任务板（4 方向 + 核心 hardening），保留 P0/P1/P2 优先级队列。
• .github/ISSUE_TEMPLATE/contributor-task.yml / PULL_REQUEST_TEMPLATE.md / config.yml / SUPPORT.md / CONTRIBUTING.md / docs/README.md / docs/development/README.md / mkdocs.yaml：方向路由、base branch 字段与导航入口。
• examples/docs-governance-smoke.py（+86/-2）：新增 assert_technical_direction_governance_is_current，断言地图/中文镜像/RFC 分组/任务板/模板/治理文案一致性。

关键内容讲解

1. 成熟度词表（technical-directions §How To Read）：5 个固定词（Shipped/hardening、Incubating/qualification、Active research、Draft、Held）让「方向」与「可认领性」解耦；Held 明确「gate 改变前不应开始实现」。这是整个地图可执行性的基础。
2. 四方向表 + tracker：每个方向给出 outcome/stage/start-here，tracker #3243-#3246 与 pinned Discussion 2851 都真实存在（已逐一验证 open）。
3. RFC 索引四组重组：Effect Interpreter 归 Accepted Architecture、benchmark/stride 归 Active Research Programs、其余归 Drafts；与方向地图的阶段标注一致，且 smoke 断言旧 "## Active Drafts" 标题不再出现。
4. 任务板方向化：CONTRIBUTOR_TASKS 从「Project Development Direction 散文」改为「方向 + 当前阶段 + 贡献入口 + 边界」表 + 优先级队列；#3074 状态改为 Claimed（与真实队列一致），#3228 保持 Available（与我们此前 triage 结论一致）。
5. 治理闭环：方向/owner/integration branch/promotion gate 实质变化必须走 PR 更新地图；Discussion 只是投影；direction/* label 不授予权限——与 AGENTS.md 的公开/私有与权限纪律一致。

正向路径

新贡献者读 CONTRIBUTING → 打开方向地图 → 选一个活跃方向 → 看 tracker 的 stage 与边界 → 到任务板找有界行（或开 contributor-task issue，带 direction + base branch + 最小切片 + non-goals + validation）→ PR 模板勾选 direction 与 target base branch → 按 promotion gate 晋级 main。

负向路径

若某 RFC 状态与地图标注不一致 → 未来 smoke 扩展可拦截（当前 smoke 只断言分组标题，尚未逐 RFC 对照状态，见 P2）；若有人把方向 tracker 当 blanket 授权 → 地图明确「tracker 不是实现授权，需单独有界 issue/row」；若 NoKV 被当作控制面权威 → 地图明确「unpromoted provider candidate、agent 不直接连接」。这些负向语义都写清了。

对主干的风险

无阻断项。P2 注意点：

1. 评审时刻 build/pytest IN_PROGRESS：Sign-off 与 dependency-review 已 SUCCESS；docs-governance-smoke.py 在 exact head 独立运行通过。合并前确认剩余两项变绿。
2. RFC 状态双源漂移风险：RFC 索引分组与方向地图的阶段各自维护；当前 smoke 只断言分组标题存在，未逐 RFC 交叉校验「RFC 内 status ↔ 索引分组 ↔ 地图 stage」一致。建议给 RFC 增加 frontmatter status 字段或在 smoke 里做三向交叉断言，否则后续单边改动会静默漂移。
3. README 首屏未动：diff 从 482 行起，Hero/开头导航未改，不触发 first-screen review gate；PR body 也声明 hero unchanged（已核实）。
4. 任务板状态是快照：#3074 标 Claimed、#3228 标 Available 与当前队列一致，但这类行会过期；方向化之后建议在 smoke 里对「Available/Claimed/Needs design」做更细的跨源校验（当前只校验方向与关键文案）。

验证矩阵（exact head 实测）：

场景	结果
examples/docs-governance-smoke.py	PASS
Tracker #3243-#3246	全部 open 且标题匹配
Discussion 2851	open（Current roadmap and known limitations）
RFC 交叉链接 21 个文件（EN/ZH/evidence）	全部存在
technical-directions EN/ZH 标题 parity	9=9 对齐
README 首屏/Hero	未动（diff 从第 482 行起）
评审时刻 checks	Sign-off/dependency-review SUCCESS；build/pytest IN_PROGRESS

我的整体评价

这是把「方向治理」落到仓库事实层的优质改动：地图可执行、tracker 与 Discussion 真实存在、RFC 索引分组清晰、任务板/模板/导航/治理全部指向同一事实源，并有持续 smoke 防漂移。中英镜像标题对齐，链接全部有效，首屏未动。P2 注意点（等 build/pytest 变绿、RFC 状态三向交叉断言、任务板快照校验）均不构成阻塞。结论：APPROVE（author-owned PR，以 COMMENTED 记录批准结论）。

---

English Verdict

Verdict: APPROVE (author-owned PR; recorded as COMMENTED because GitHub blocks formal self-approval)

Exact head: 3248@faeda21ce95f4b819eaa44e5372cfe9a7fa7f737

Summary: Docs/governance change publishing a maintainer-curated technical-directions map (EN+ZH), restructuring the RFC index into status groups, direction-based contributor task board, direction routing in issue/PR templates, and a governance smoke. Verified at the exact head: docs-governance-smoke.py passes, direction trackers #3243-#3246 and Discussion 2851 are open, all 21 RFC cross-links exist, EN/ZH heading parity is 9/9, and README hero/first screen is untouched.

P2 (non-blocking): build and pytest were still IN_PROGRESS at review time (Sign-off and dependency-review SUCCESS) — confirm green before merge. Consider extending the smoke to cross-check each RFC's status against the directions map (three-way consistency), and to validate task-board row states beyond the current direction/key-phrase assertions.

[huangruiteng]

Maintainer review — exact head faeda21ce95f4b819eaa44e5372cfe9a7fa7f737

Findings

No blocking findings.

The diff keeps typed-state and domain boundaries intact: it changes no runtime
state transition, default, permission, benchmark scoring path, or evidence
policy. Maturity terms are explicitly scoped to project governance; the RFC
index preserves each RFC's own Accepted, Research, or Draft status. Machine
obligations in the governance section are named as requirements rather than
guidance.

Product and architecture judgment

This solves the contributor-discovery problem with one versioned direction map
instead of another independent roadmap. README, docs navigation, task routing,
templates, CODEOWNERS, RFC maturity, tracking issues, labels, and the pinned
Discussion all point back to that map.

The most important boundaries are explicit: the frontend/IM program is an
incubation branch rather than shipped main; @maxliux5 is recognized as the
current implementation lead without gaining maintainer authority; NoKV is an
unpromoted coordination provider candidate rather than a shared database or
control-plane authority; and an RFC or tracker does not itself authorize
implementation.

Validation

• python3 examples/docs-governance-smoke.py — passed
• uvx --from mkdocs-material mkdocs build --strict — passed
• focused loopx check --scan-path ... — public scan clean; two unrelated
  owner-local state warnings were outside the repository diff
• loopx canary premerge --from-git-diff --tier quick — passed: direct diff
  checks, changed-Python compile, three catalog canaries, and public-boundary
  scan
• GitHub DCO, dependency review, release-artifact build, Frontstage build, and
  pytest — required before merge; release publish/upload jobs are expected to
  skip on a pull request

No manual holds. Generated docs output and ignored publication-body drafts are
excluded. This coverage is sufficient because the diff is documentation,
contributor metadata, routing, and one focused docs-governance smoke; it does
not touch runtime, permissions, package behavior, benchmark execution, or a
public first viewport.

Merge decision

Approved for maintainer self-merge once the remaining required GitHub checks
finish successfully.