Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
e35e366
fix(zh-CN): align live registry guidance
Wonderforge-Lab Sep 3, 2026
c9016de
fix(zh-CN): align live registry guidance
Wonderforge-Lab Sep 3, 2026
df2b181
fix(zh-CN): align live registry guidance
Wonderforge-Lab Sep 3, 2026
5ae10eb
docs: distinguish source maintenance from runtime
Wonderforge-Lab Sep 3, 2026
169d9cd
docs(zh-CN): distinguish source maintenance from runtime
Wonderforge-Lab Sep 3, 2026
42e91fa
test: cover zh-CN live routing surfaces
Wonderforge-Lab Sep 3, 2026
43f805b
test: require review for changed locale sources
Wonderforge-Lab Sep 3, 2026
4ab1c6a
test: add locale review acknowledgements
Wonderforge-Lab Sep 3, 2026
d961e4d
docs: record development and runtime boundary
Wonderforge-Lab Sep 3, 2026
a2a5e38
ci: check locale source freshness
Wonderforge-Lab Sep 3, 2026
486a553
docs: prepare v0.3.2 release status
Wonderforge-Lab Sep 3, 2026
b376976
docs(zh-CN): prepare v0.3.2 release status
Wonderforge-Lab Sep 3, 2026
0c41e83
docs: add bilingual v0.3.2 revision note
Wonderforge-Lab Sep 3, 2026
693069d
docs: keep runtime entrypoint portable
Wonderforge-Lab Sep 3, 2026
3d4b50f
docs(zh-CN): keep runtime entrypoint portable
Wonderforge-Lab Sep 3, 2026
2391164
docs: clarify canonical maintenance workflow
Wonderforge-Lab Sep 3, 2026
d9a9b69
docs: clarify canonical review boundary
Wonderforge-Lab Sep 3, 2026
6fc1923
docs: align v0.3.2 release scope
Wonderforge-Lab Sep 3, 2026
4a9e1ec
docs(zh-CN): align v0.3.2 release scope
Wonderforge-Lab Sep 3, 2026
345b7cf
docs: align v0.3.2 revision note
Wonderforge-Lab Sep 3, 2026
14e296d
docs: remove user-facing maintenance boundary note
Wonderforge-Lab Sep 3, 2026
5a81022
docs(zh-CN): clarify canonical maintenance workflow
Wonderforge-Lab Sep 3, 2026
9b8b0da
docs: acknowledge AI collaborators
Wonderforge-Lab Sep 3, 2026
8ce57f7
docs(zh-CN): acknowledge AI collaborators
Wonderforge-Lab Sep 3, 2026
2d38ece
docs: name ruleset accurately
Wonderforge-Lab Sep 3, 2026
c90db02
docs: record AI collaborator acknowledgements
Wonderforge-Lab Sep 3, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Control-plane review paths. These assignments request review on pull requests;
# direct default-branch deposits remain governed by AI_ENTRYPOINT.md.
# Control-plane review paths. These assignments request review on pull requests.
# Canonical source maintenance is governed by the repository's GitHub ruleset and CONTRIBUTING.md.
/AI_ENTRYPOINT.md @Wonderforge-Lab
/lobby/ @Wonderforge-Lab
/docs/ @Wonderforge-Lab
Expand Down
13 changes: 13 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,19 @@ jobs:
- run: python tests/test_generated_views.py
- run: python tests/test_markdown_links.py
- run: python tests/test_locale_invariants.py
- name: Check localized source freshness
env:
BEFORE: ${{ github.event.before }}
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
base="${{ github.event.pull_request.base.sha }}"
elif [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
base="$(git merge-base "origin/$DEFAULT_BRANCH" "$GITHUB_SHA")"
else
base="$BEFORE"
fi
python tests/test_locale_freshness.py "$base" "$GITHUB_SHA"
- run: python tests/test_bridge_config.py
- run: python tests/test_tag_promotion.py
- name: Enforce tag-promotion separation
Expand Down
6 changes: 6 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,9 @@ For collaborator changes:
- Avoid private identifiers, real user data, account names, local paths, and internal project references.
- Keep docs plain and useful to engineers.
- Small text artifacts belong here; bulky material belongs elsewhere.

## Maintaining the canonical source repository

This section applies to collaborators maintaining `Wonderforge-Lab/CapstanAI-LabNote`, the public source scaffold. Use a branch, pull request, validation, review, and release process.

Canonical maintenance is not a LabNote visitor session. Do not create visitor records, datadrops, messages, notifications, responses, runtime registry records, or signoffs in this repository. To use LabNote as a workspace, create a separate clone or template-derived repository and follow its runtime protocol.
21 changes: 16 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,17 +223,28 @@ LabNote is the ledger, not the warehouse. Keep the workspace focused on small, i

Detailed runtime rules live in those canonical files rather than being duplicated here.

## Acknowledgements

CapstanAI - LabNote is human-led. Recent language-layer and verification work was assisted by the following AI collaborators:

- **OpenAI Codex** — implementation support, verification design, and repository review.
- **DeepSeek** — independent Simplified-Chinese language, cultural, and adversarial review.

These acknowledgements describe assisted contributions. Human maintainers retain authorship, decision authority, and release control.

## Status

Latest published scaffold release: `v0.3.1 - Registry Guidance Cleanup`.
Latest published scaffold release: `v0.3.2 - Locale Route Freshness`.

This patch release:

* removes stale live guidance that still allowed manual CSV registry edits,
* marks the localization source-drift note and pre-v1 registry audit as historical provenance,
* leaves Registry Contract v1, schemas, runtime paths, machine fields, statuses, localization protocol, and generated views unchanged.
* corrects stale zh-CN CSV guidance on live visitor routes;
* aligns the zh-CN visitor-lobby model with the canonical routing and registration rule;
* adds CI checks for protected locale invariants and for unreviewed changes to paired English sources;

It leaves Registry Contract v1, schemas, runtime paths, machine fields, statuses, permissions, generated views, and the shared protocol unchanged.

`v0.3.0 - Registry v1 and Simplified Chinese Revision` remains the feature baseline beneath this patch.
`v0.3.0 - Registry v1 and Simplified Chinese Revision` remains the feature baseline beneath these patch releases.

CapstanAI may later grow a richer deterministic layer, along with relay, vault, and protocol modules. LabNote begins as the simplest useful ledger.

Expand Down
39 changes: 39 additions & 0 deletions archive/20260903_v0.3.2_locale_route_freshness.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# v0.3.2 — Locale Route Freshness

## English

### What changed

- Corrected stale zh-CN instructions that still allowed manual CSV registry edits on live visitor routes.
- Aligned the zh-CN visitor-lobby model with the canonical rule that visitor identifiers are routing handles and registration is optional.
- Extended locale invariant coverage to the affected lobby, message-routing, and visitor-model surfaces.
- Added a CI freshness check: when a paired English source changes, its zh-CN counterpart must change or receive a hash-bound review acknowledgement.
- Added transparent acknowledgements for OpenAI Codex and DeepSeek as AI collaborators in this work.

### What did not change

This release does not change Registry Contract v1, schemas, runtime paths, JSON keys, machine fields, status values, permissions, generated views, or the shared English-canonical protocol.

### Validation

The release PR must pass the repository's Registry validation workflow, including locale invariants and the locale freshness check.

---

## 简体中文

### 变更内容

- 修正了访客会话实际路由中仍允许手工编辑 CSV 登记视图的过时 zh-CN 指令。
- 使 zh-CN 访客会话入口模型与基准规则保持一致:访客会话标识是路由标识,登记并非前提条件。
- 扩展了本地化不变项检查,覆盖受影响的入口区、消息路由和访客会话模型表面。
- 新增 CI 新鲜度检查:成对英文来源发生变更时,其 zh-CN 对应文件必须同步变更,或获得绑定该来源哈希值的审阅确认。
- 新增对 OpenAI Codex 和 DeepSeek 的透明致谢,说明其作为本次工作 AI 协作者的角色。

### 未发生变化的部分

本版本不改变 Registry Contract v1、schema、运行时路径、JSON 键、机器字段、状态值、权限、生成视图或共享的英语基准协议。

### 验证

发布 PR 必须通过仓库的 Registry validation 工作流,其中包括本地化不变项检查和本地化新鲜度检查。
6 changes: 6 additions & 0 deletions locales/zh-CN/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,9 @@ CapstanAI - LabNote 的基准(canonical)仓库由协作者维护,**不接
- 避免出现私人标识符、真实用户数据、账户名称、本地路径和内部项目引用;
- 文档应保持简洁、清晰,并对工程人员有用;
- 小型文本类文件适合放在这里,体积较大的材料应存放在别处。

## 维护基准源仓库

本节适用于维护公开源脚手架 `Wonderforge-Lab/CapstanAI-LabNote` 的协作者。请使用分支、拉取请求、验证、审阅和发布流程。

基准仓库维护不是 LabNote 访客会话。不要在此仓库中创建访客记录、资料投递、消息、通知、回复、运行期登记记录或签退记录。若要把 LabNote 用作工作区,请创建单独的克隆或由模板派生的仓库,并遵循其中的运行期协议。
21 changes: 16 additions & 5 deletions locales/zh-CN/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,17 +229,28 @@ LabNote 是工作台账(ledger),不是仓库(warehouse)。工作区应

详细运行规则见上述对应文件,此处不再重复。若简体中文说明与英文基准文件在协议含义上冲突,以英文基准文件为准。

## 致谢

CapstanAI - LabNote 由人类主导。近期的语言层和验证工作得到了以下 AI 协作者的协助:

- **OpenAI Codex** — 提供实施支持、验证设计和仓库审阅。
- **DeepSeek** — 提供独立的简体中文语言、文化和对抗性审阅。

这些致谢说明的是辅助性贡献。人类维护者保有作者身份、决策权和发布控制权。

## 状态

当前最新发布的框架版本:`v0.3.1 - Registry Guidance Cleanup`。
当前最新发布的框架版本:`v0.3.2 - Locale Route Freshness`。

这个补丁版本:

* 清理仍允许手工编辑 CSV 登记视图的过时当前指导;
* 将本地化来源漂移说明和 v1 之前的登记库审计明确标记为历史溯源材料;
* 不改变 Registry Contract v1、schema、运行时路径、机器字段、状态值、本地化协议或生成的登记视图。
* 修正了访客会话实际路由中已过时的 zh-CN CSV 指导;
* 使 zh-CN 访客会话入口模型与基准的路由和登记规则保持一致;
* 增加了 CI 检查,用于保护本地化中的关键不变项,并识别未经审阅的成对英文来源变更;

本版本不改变 Registry Contract v1、schema、运行时路径、机器字段、状态值、权限、生成视图或共享协议。

`v0.3.0 - Registry v1 and Simplified Chinese Revision` 仍是本补丁所基于的功能版本基线
`v0.3.0 - Registry v1 and Simplified Chinese Revision` 仍是这些补丁版本所基于的功能版本基线

以后,CapstanAI 可能会发展出更丰富的确定性层,以及 relay、vault 和 protocol 等模块。LabNote 则从最简单、真正有用的工作台账开始。

Expand Down
2 changes: 1 addition & 1 deletion locales/zh-CN/docs/visitor_lobby_model.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@

不要自行编造访客会话标识,也不要静默复用先前对话上下文中的标识。

访客会话资料可以存放在 `lobby/visitors/` 下。保持内容简短、通用。
访客会话标识是路由标识;访客会话资料登记并不是消息、通知或访问路由的前提条件。如已登记访客会话,基准记录为 `registry/visitors/<visitor_id>.json`。仅供人类阅读定位的小型可选资料可放在 `lobby/visitors/` 下。保持可选资料简短、通用。
2 changes: 1 addition & 1 deletion locales/zh-CN/lobby/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@
3. 读取 `VISITOR_CHECKLIST.md`。
4. 普通投递按照 `ROUTINE_DEPOSIT_QUICKSTART.md` 执行。
5. 在仓库根目录的基准 `registry/` 路径下创建 JSON 登记记录。
6. 除非操作者明确要求,否则不要编辑 CSV 汇总文件
6. 不要手动编辑生成的 CSV 登记视图

入口区留下的是工作轨迹,不是登录系统。
2 changes: 1 addition & 1 deletion locales/zh-CN/messages/ROUTING_RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
- 对于某一类访客会话或较宽泛的接收组,使用 `to_group`。
- 先检查明确指向当前访客会话的消息,再检查组消息。
- 在 `registry/messages/` 下创建基准 JSON 消息记录。
- 普通访客会话工作不要编辑旧版 CSV 消息登记表,除非操作者明确要求
- 不要手动编辑生成的 CSV 消息登记表或 `registry/INDEX.md`
- 在有帮助时,链接相关工作包和回复。
- 当必须由操作者把消息转递到另一个会话时,设置 `needs_human_relay`。
- 在收件方回复、操作者确认,或消息被关闭之前,不要假定消息已经送达。
4 changes: 4 additions & 0 deletions tests/locale_review_acknowledgements.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"schema_version": 1,
"acknowledgements": []
}
105 changes: 105 additions & 0 deletions tests/test_locale_freshness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
#!/usr/bin/env python3
"""Require a zh-CN review when a paired English source changes.

This deliberately checks review freshness, not translation quality. It treats
the repository's current diff as the unit of work: a changed canonical source
must either change its zh-CN counterpart or receive a specific, hash-bound
review acknowledgement.
"""
from __future__ import annotations

import hashlib
import json
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
LOCALE_ROOT = ROOT / "locales" / "zh-CN"
ACKNOWLEDGEMENTS = ROOT / "tests" / "locale_review_acknowledgements.json"

# Locale paths whose English canonical source does not follow the normal
# locales/zh-CN/<path> -> <path> relationship.
SOURCE_OVERRIDES = {
"GLOSSARY.md": "docs/localization/GLOSSARY.md",
"registry/TAG_DISPLAY_CATALOG.md": "docs/localization/TAG_DISPLAY_CATALOG.md",
}


def paired_surfaces() -> dict[str, str]:
pairs: dict[str, str] = {}
for locale_path in sorted(LOCALE_ROOT.rglob("*.md")):
locale_rel = locale_path.relative_to(ROOT).as_posix()
relative = locale_path.relative_to(LOCALE_ROOT).as_posix()
source_rel = SOURCE_OVERRIDES.get(relative, relative)
if (ROOT / source_rel).is_file():
pairs[source_rel] = locale_rel
return pairs


def digest(path: Path) -> str:
return hashlib.sha256(path.read_bytes()).hexdigest()


def changed_paths(base: str, head: str) -> set[str]:
result = subprocess.run(
["git", "diff", "--name-only", base, head],
cwd=ROOT,
check=True,
text=True,
capture_output=True,
)
return {line for line in result.stdout.splitlines() if line}


def acknowledgements(pairs: dict[str, str]) -> dict[str, str]:
payload = json.loads(ACKNOWLEDGEMENTS.read_text(encoding="utf-8"))
if payload.get("schema_version") != 1:
raise AssertionError("locale review acknowledgements require schema_version 1")

reviewed: dict[str, str] = {}
for entry in payload.get("acknowledgements", []):
source = entry.get("source")
source_sha256 = entry.get("source_sha256")
reason = entry.get("reason")
if not isinstance(source, str) or source not in pairs:
raise AssertionError(f"invalid acknowledgement source: {source!r}")
if not isinstance(source_sha256, str) or len(source_sha256) != 64:
raise AssertionError(f"invalid source_sha256 for {source!r}")
if not isinstance(reason, str) or not reason.strip():
raise AssertionError(f"missing review reason for {source!r}")
if source in reviewed:
raise AssertionError(f"duplicate acknowledgement for {source!r}")
reviewed[source] = source_sha256
return reviewed


def main() -> int:
if len(sys.argv) != 3:
raise SystemExit("usage: test_locale_freshness.py <base> <head>")

pairs = paired_surfaces()
changed = changed_paths(sys.argv[1], sys.argv[2])
reviewed = acknowledgements(pairs)
failures: list[str] = []

for source_rel, locale_rel in pairs.items():
if source_rel not in changed or locale_rel in changed:
continue
current_digest = digest(ROOT / source_rel)
if reviewed.get(source_rel) == current_digest:
continue
failures.append(
f"{source_rel} changed without a zh-CN counterpart update or "
f"hash-bound review acknowledgement ({locale_rel})"
)

if failures:
raise AssertionError("Locale freshness check failed:\n" + "\n".join(failures))

print(f"locale freshness check passed ({len(pairs)} paired surfaces)")
return 0


if __name__ == "__main__":
raise SystemExit(main())
32 changes: 28 additions & 4 deletions tests/test_locale_invariants.py
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,34 @@
"accepted",
),
},
"lobby/README.md": {
"locale": "locales/zh-CN/lobby/README.md",
"literals": (
"AI_ENTRYPOINT.md",
"README_FIRST.md",
"VISITOR_CHECKLIST.md",
"ROUTINE_DEPOSIT_QUICKSTART.md",
"registry/",
"CSV",
),
},
"messages/ROUTING_RULES.md": {
"locale": "locales/zh-CN/messages/ROUTING_RULES.md",
"literals": (
"to_visitor_id",
"to_group",
"registry/messages/",
"registry/INDEX.md",
"needs_human_relay",
),
},
"docs/visitor_lobby_model.md": {
"locale": "locales/zh-CN/docs/visitor_lobby_model.md",
"literals": (
"registry/visitors/<visitor_id>.json",
"lobby/visitors/",
),
},
"registry/README.md": {
"locale": "locales/zh-CN/registry/README.md",
"literals": (
Expand All @@ -124,10 +152,6 @@
"CI",
),
},
"SECURITY.md": {
"locale": "locales/zh-CN/SECURITY.md",
"literals": (),
},
"templates/datadrop_packet.md": {
"locale": "locales/zh-CN/templates/datadrop_packet.md",
"literals": (
Expand Down
Loading