AutoLang Agent Guidelines & Workflows
Standard (Design + Plan + Worktree) Workflow
All AI coding assistants working in this repository must strictly adhere to the following workflow principles based on task complexity.
开发范式（2026-08-28 起，Plan 467）：标准流程采用 auto-plan 四技能范式 （
/auto-plan:new→/auto-plan:work→/auto-plan:review→/auto-plan:merge）， 范式设计与规约见 docs/design/autoplan-spec-ledger.md 与 docs/specs/README.md §4。路径映射（四技能为 auto-os 仓书写， 在本仓执行时以此为准）：技能文档中的docs/plans/archived/在本仓为docs/plans/archive/； 技能文档中的.worktrees/plan-<NNN>-dev在本仓为D:/autostack/.wt/lang-<NNN>/auto-lang（Plan 529 分组平铺布局；在途的 525/526 仍用旧.worktrees/，fold 后退役）；.autoos/specs.json两仓一致。 Plan 状态机：drafting → executing → execution_done → reviewed → archived（终态）。Worktree 红线（2026-09-03 三仓 .git 删除事故，Plan 529）：worktree 内禁止创建任何 junction/symlink——
git worktree remove的递归删除会穿透链接删除目标仓内容（实测复现）。 跨仓依赖用解析序解决：$AUTO_LANG_ROOT 等 env 覆盖 → 组内 ../auto-lang → D:/autostack/auto-lang 主检出。移除任何 worktree 前必须先跑bash D:/autostack/wt-guard.sh <worktree 路径>（reparse point 扫描，非空即拒）。
1. Task Sizing & Triage
- L0: Trivial Fixes (轻微修改)
- Criteria: Minor typos, comment updates, or 1-2 line simple bugfixes without side-effects.
- Action (2026-09-15 用户裁定：小型改动同样必须走 worktree，master 零 WIP 代码):
轻量路径（无需正式 plan 文档）：
git worktree add D:/autostack/.wt/fix-<slug>/auto-lang -b fix-<slug>（或一键建组含 auto-down 兄弟仓：bash scripts/new-wt-group.sh fix-<slug> --branch fix-<slug>， PLAN-726 T-04——组内 cargo 解析即开即用，缺兄弟仓时 check 直接失败） → 修改 + 按改动范围跑验证门禁 → 提交 → 合回 master →bash D:/autostack/wt-guard.sh D:/autostack/.wt/fix-<slug>/auto-lang（必须 clean）→ 移除 worktree/分支/组目录。 实机走查/核查会话中的顺手修复同样适用本条（2026-09-15 三线 WIP 直接落 master 的事后矫正）。 master 上仅允许计划簿记类改动（docs/plans/**、.next-id、specs/docs 沉淀）。
- L1: Feature / Module Tasks (模块/特性任务)
- Criteria: Any new feature, multi-file change, complex bugfix, or cross-backend parity implementation.
- Action:
- Run
scripts/new-plan.sh <slug>on the default checkout (master) to atomically take the next<NNN>plan ID fromdocs/plans/.next-idand create the plan skeleton (v2 frontmatter). - Fill
docs/plans/<NNN>-<plan-name>.md(needs-analysis seeded from docs/specs/overview.md) detailing goals, design, task checklist, and verification plan; present for confirmation before executing. - Create a dedicated worktree in the sibling-group layout (Plan 529):
git worktree add D:/autostack/.wt/lang-<NNN>/auto-lang -b plan-<NNN>-dev，或一键bash scripts/new-wt-group.sh lang-<NNN> --branch plan-<NNN>-dev（自动补 auto-down 兄弟 detached；基面恒钉 master，PLAN-726 T-04）. Cross-repo plans add sibling worktrees into the same group dir (e.g..wt/down-047/{auto-down, auto-lang}) so../auto-langresolves uniformly. - Perform all code implementation and testing inside that worktree; plan-file bookkeeping (
[✅]markers, frontmatter flips) stays on the default checkout.
- Run
- L2: Architectural Overhaul (重大架构级任务)
- Criteria: Changes impacting overall architecture, compiler/VM pipelines, core protocol definitions, or cross-system runtime contracts.
- Action:
- First create/update a formal architecture design document in
docs/design/<NN>-<topic>.md(register it indocs/design/00-intro.md). - Decompose the design into 1 to N moderate-sized, independently executable Plan documents in
docs/plans/<NNN>-*.md. - Execute each Plan sequentially in its own dedicated worktree (one worktree per plan for its whole lifetime).
- First create/update a formal architecture design document in
2. Execution Discipline in Worktree
- Always perform code modifications, builds, and test runs within the plan's worktree (
D:/autostack/.wt/lang-<NNN>/auto-lang; legacy in-flight plans keep their.worktrees/path until folded) to keepmasterclean (one worktree per plan per repo; multi-phase plans fold per phase and re-sync). - Never place junctions/symlinks inside a worktree (see red line above); resolve cross-repo deps via the documented order (env → group sibling → main checkout), never via links.
- Fast Iteration during Development:
- During development, DO NOT run full test suites repeatedly. Use fast syntax/type checks:
- Fast type check:
cargo check -p auto-lang - Scoped single-module test (optional):
cargo t <module_name>(e.g.cargo t iced)
- Fast type check:
- Reuse standardized automation scripts from
.agents/skills/autoui-verifier/scripts/(test_vm_mcp.py,test_vue_playwright.mjs) instead of writing ad-hoc scripts.
- During development, DO NOT run full test suites repeatedly. Use fast syntax/type checks:
- Change-Scoped Verification Gate (按改动范围分级测试门禁):
- Category A: Pure Verification / Asset / Doc-Only Tasks (纯验证/示例资产/计划跟踪):
- 若未修改
crates/下的 Rust 源码（仅截图、更新docs/plans/矩阵或修改测试脚本），严禁运行cargo t和docs_gen。仅完成目标验证即可直接合入。
- 若未修改
- Category B: Scoped Rust Code Changes (局部 Rust 模块改动):
- 快速语法/类型检查：
cargo check -p auto-lang - 开发迭代：
cargo t <module_name>（如cargo t iced或cargo t ui） - 复审门禁 = 分级门禁（fix-test-tiering，2026-09-30 裁定）：复审/合入前在 plan
worktree 跑裸
cargo t（全日常面）+ 触面档：VM/编译器→cargo tv、trans→cargo tt、book→cargo tb、UI 代码生成（ui_gen/**四生成器）→cargo tu、 碰 aavm 触发路径→按 §AAVM/AA2R 作用域映射跑taa。cargo tf不再是 per-plan 复审门禁——已改判为批量回归档：merge 收尾时 到期判定（计划号 %5 落地，或 >48h 且期间有合并——L0fix-*计入；收据docs/plans/.last-batch-regression.json，缺失即到期）后由/auto-plan:regress技能在主检出单实例执行（Plan 466 全量语义保留：1M churn + 语料族 + 画廊围栏）。 依据：tf 是机器独占负载（内嵌 cargo build + ~800s 零缓存围栏 + 全池测试进程）， 多 agent 并行 worktree 各跑 tf 必然资源互毁（2026-09-30 实录）。 cargo tu= UI 生成档（fix-ui-tier 2026-09-30）：ui_gen::整族已从日常档 default-filter 移除（854 例 × 每进程 ~1.2s 注册表构建税曾占日常档 6250/7900 测试秒）； tu 刻意用单进程 libtest——WidgetRegistry::with_defaults()的 OnceLock 在单进程内 全档只建一次。纯函数代码生成测试无进程级全局态/重内存，单进程安全；tu 无 nextest slow-timeout 保护，新加入的 ui_gen 测试须自带截止时间（网络/等待类不得入此族）。 tf 批量档对 ui_gen 仍全覆盖（nextest-full 不排除）。- 并行纪律：多 agent 并行时，worktree 内只跑
cargo check/ scopedt/tv级负载；全量档（tf/ta/taa/t3）一律主检出单实例串行。 重型测试族（画廊围栏 / 1M churn）自 PLAN-726 T-02 起带机器级单实例闸门 （heavy_gate.rs::machine_gate，锁D:/autostack/.locks/<family>.lock）： 多跑并发时第二实例秒级确定性红（含持锁者 PID/cwd 提示），不再互毁挂死； 持锁进程死亡的陈锁自动接管。aavm XL/LG 族经 2026-10-02 裁定豁免 （aavm/aa2r 拟退役短期不跑；恢复运行时补接线即可）。 - AAVM 专项（Plan 568）：改 VM/编译器的复审随身跑
cargo tv（PLAN-700 语料三族， 与 t/tf 同二进制零重编），全量收口归批量回归档；aavm 无实用面，不需要关心是否被 改坏，守护=本地taa/ta（PLAN-763 已移除旧 CI）。只有 diff 触及 aavm 代码（packages/aavm/lib/*.at、test/vm/aavm2/**、test/parity/**、aavm2 测试基建）才跑cargo taa，且按 §AAVM/AA2R Test Tier 作用域 映射缩小范围，不全量跑。
- 快速语法/类型检查：
- Category C: Docs / Schema Changes (文档与元数据改动):
- 仅当修改了文档生成器、Schema 定义文件或语法参考时，才运行
cargo test -p auto-lang --test docs_gen。
- 仅当修改了文档生成器、Schema 定义文件或语法参考时，才运行
- AutoUI 跨端验证（双端模式）:
- Vue 模式：
auto run - VM 模式：
auto run -r vm - 自动化双端一致性：调用
autoui-verifier技能 (.agents/skills/autoui-verifier)。
- Vue 模式：
- Category A: Pure Verification / Asset / Doc-Only Tasks (纯验证/示例资产/计划跟踪):
AAVM/AA2R Test Tier (Plan 568)
概念："改 VM/编译器后的回归"（cargo tv，纯 .at 语料 golden）与"AAVM 自举展示"（cargo taa）是两个独立概念。AAVM（packages/aavm/lib/*.at 自举 + a2r.at 发射对齐）目前无实用面，平时改 VM/编译器不需要测 aavm（守护=cargo ta 全量档 + fold 前裸 taa；PLAN-763 删除未维护的 vm-files-ci.yml）。
双重解释器路径裁定（2026-09-06 用户，Plan 574 落地）：avm+aavm / avm+aa2r 进程内双重解释路径（宿主 VM run_with_capture 拼 470KB lib 形态）非真实需求（2×2 对称性产物）；其进程内执行栈需求随 lib 规模增长，已越过 run_autovm_capture 硬编码 4MB 执行线程栈（探针定量 4MB 爆/5MB 过，RUST_MIN_STACK 护栏被显式 stack_size 绕过），与用例规模无关。12 个该路径语料测试已 #[cfg_attr(windows, ignore)]（Linux/CI 保留全量）。新计划/新能力验收避免该路径重型化——重型对拍一律走转译+编译+运行形态（⑤腿 compile corpus / at_mode / gen2 管道）；规约注记见 docs/specs/aavm/project.md 验证矩阵节，对账表 docs/reports/p574-coverage-map.md。
触发条件（只有这些路径的改动才跑 taa）：packages/aavm/lib/*.at、test/vm/aavm2/**、test/parity/**、crates/auto-lang/src/tests/aavm2_*.rs / aavm_runner_tests.rs、lib.rs 的 aavm2_lib_source/AUTO_LIB_FILES*。其余改动零触发。
作用域映射（改什么 → 跑哪个闸门；耗时为 2026-09-05 实测）：
| 改动位置 | 跑什么 | 耗时 |
|---|---|---|
corpus_m1/** |
cargo taa aavm2_m1 |
31s |
corpus_m2/** |
cargo taa aavm2_m2 |
172s |
corpus_m3/** |
cargo taa aavm2_m3 |
47s |
corpus_m4/** |
cargo taa aavm2_m4 |
~315s |
corpus_use/** |
cargo taa aavm2_m4 aavm2_m5 |
~127s |
corpus_a2r/** |
cargo taa aavm2_a2r |
~185s |
packages/aavm/lib/engine.at（终段执行器） |
cargo taa aavm2_m5 |
~350s |
packages/aavm/lib/a2r.at（终段发射器） |
cargo taa aavm2_a2r aavm_at_mode |
~260s |
packages/aavm/lib/{token,lexer,parser,typeinfo,codegen}.at（上游共享） |
全管线级联，直接裸 cargo taa |
~10min 量级 |
review/fold 前无论改了什么 aavm 文件，一律裸 cargo taa 全量兜底。闸门粒度=测试目录级（单语料文件由所属闸门整体覆盖）。compile 腿（compile_corpus/compile_use_corpus）现场 cargo build 产物按内容 hash 缓存，二次运行秒级。
全档资源表（测试数/耗时/内存；"待实测"由 Plan 568 T7 回填）：
| 档位 | 适用场景 | 测试数 | 实测耗时 | 内存 |
|---|---|---|---|---|
cargo t |
日常快速回归 + per-plan 复审门禁（1M churn + 语料族 + 画廊围栏 + ui_gen 排除，PLAN-700/fix-tiering 系） | 4976（2026-10-02 实测选择面；含 PLAN-726 闸门单测 5） | 54.1s（PLAN-726 merge 实测 2026-10-02，轻度竞争；e4 红已清偿[PLAN-724 T-02]——62s 旧值含其 30s 长尾；余量含预存红族红时长：plan606 10.2s/schema_fence 10.5s/plan707 flake 5.1s，14 预存红族见 §1 非目标/批量回执） | 轻池 <50MB/测 |
cargo tf |
批量回归档（/auto-plan:regress 触发，主检出单实例；含 1M churn + 语料族 + 画廊围栏，PLAN-700；fix-test-tiering 2026-09-30 起非 per-plan 门禁） |
5689（2026-09-24 实测） | 77.2s（Plan 564）+语料段 ~4s（tv 同源实测）；画廊围栏冷态 ~800s 另计（每进程全量重编，无跨进程缓存）；围栏与 1M churn 自 PLAN-726 带机器级单实例闸门（并发第二实例秒级红，见 §2 并行纪律） | ≤2GB 预算 |
cargo tv |
改 VM/编译器后定向语料回归——filter 档（profile tv）与 t/tf 同二进制零重编（不含 aavm；PLAN-700） | 162 | 3.95s（2026-09-24 实测） | 同日常档 |
cargo tt |
改 transpiler 后 | 3786（trans 增量 ~360） | 43s（冷编译另计 ~1min） | 轻池 |
cargo tb |
改 book/文档后 | 3494（book 增量 69，单测 <0.4s——旧"5-7s/测"注释已过时） | 24s | 轻池 |
cargo tu |
改 UI 代码生成后（ui_gen/**：vue/jet/ark/rust 四生成器；fix-ui-tier 2026-09-30 从日常档析出） |
863（内联，2 ignored；2026-10-11 实测） | 测试段 0.85s（单进程 libtest 实测 2026-09-30；warm 全档含 nextest→libtest 零重编切换 ~29s 内）；a2vue desktop 金样预存红已清（2026-10-11 fix-a2vue-desktop-golden 再基线：09-22 pin 同步 e85143621 带入深/浅主题菜单项后金样漏再生——4f123a50e 四红末枚）；bp root_resolution env 竞争已清（2026-10-11 fix-bp-root-env-lock：BLUEPRINTS_ROOT_TEST_SERIALIZER 全触点串行+poison 接管+panic 恢复回归，镜像 F-759-R2；reader=scan_tests×4+plan640/643/649/657 同锁；附带修 plan643 t01/t02 共享 pid scratch 互删 os error 32——裸单进程预存 flake，标准档不可见） | 轻池（无重内存/无全局态；tu 档内禁止 env set_var 类进程级全局测试——plan646 改 builder 前车之鉴） |
cargo taa |
仅 aavm 改动后（触发条件/作用域见上） | 3600（其中 aavm 21，XL 9 个 78-303s/个） | 182s（-j6 实测；564 组限流合入后 XL 串行将更长）。P574 后 Windows 本地：双重解释器 12 测试 cfg_attr 跳过（607 skipped），~24s，唯一余红=charts_gallery 预存 | XL 单测 0.8-1.2GB；并发受 jobs 限制 |
cargo ta |
终极全量（VM+aavm+trans+book+1M churn） | 4023 | 407s（-j6 实测） | 同上 |
cargo th |
改 HTTP 服务后（真 TCP，串行） | 20 | ~50s（本机实测 ≥3 环境相关红，归因见 plan 568 T7；fix-test-tiering 2026-09-30 后 back_proxy 固定端口族（39xx/40xx 撞 Hyper-V 保留段 WSAEACCES）已改 OS 临时分配清零，plan707 帧时序断言并行负载下偶发 flake 在案=4f123a50e） | 轻（真 TCP 端口） |
Heavy-Mem Test Tiering (Plan 564)
- Per-test peak weights live in
.config/test-mem-weights.md(single source of truth; measured bypython scripts/measure_test_mem.py <filter>, nextest--jobs=1serial + per-process peak polling). - Tiers: XL ≥800MB, LG 300-800MB, MD 100-300MB. nextest
[test-groups]in.config/nextest.toml+nextest-full.toml+nextest-t3.tomlenforce xl/lg/md = 1/1/2 threads. Since Plan 568's feature split, aavm heavy tests run undertaa/ta(full config) andt3— the daily tier never includes them (structural exclusion viatest-aavmfeature); groups in the daily config remain as a guard for ad-hoccargo nextest run --features test-aavmwithout--config-file. - XL/LG tests carry an in-body
heavy_gateguard (crates/auto-lang/src/tests/heavy_gate.rs): under barecargo test(noNEXTESTenv) they SKIP instantly — the 2026-09-05 incident (bare run, 12 threads, 9.78GB peak) cannot recur. SKIP guidance is visible with--nocapture; force-run withAUTO_LANG_HEAVY_MEM=1. - Registering a new heavy test (3 steps): measure → classify in the weights file → add to nextest overrides (all three configs) + wire
heavy_gateat the test's first line.
Cargo Test Aliases Reference (from .cargo/config.toml)
cargo t- Fast daily tests (~3200 unit tests via nextest in parallel; 1M churn + corpus tiers + gallery fence excluded, Plan 466/PLAN-700/fix-test-tiering)cargo tf- Full-scale daily tests (all tests incl. 1M churn + corpus tiers) — batch regression tier:/auto-plan:regresson the main checkout, single instance, NOT a per-plan review gate (Plan 466 semantics; fix-test-tiering 2026-09-30)cargo tv- 语料筛选档（nextest--profile tv筛语料三族，与 t/tf 同二进制零重编，PLAN-700）——纯 .at 语料 golden，不含 aavm（aavm 在taa档）cargo tt- Transpiler tests (--features test-trans)cargo tb- Book listing tests (--features test-book)cargo tu- UI codegen tier (vue/jet/ark/rust generator inline tests; bare cargo test = single process on purpose so the ~1.2s WidgetRegistry setup is paid once per tier, not per nextest process; fix-ui-tier 2026-09-30, daily tier excludesui_gen::)cargo taa- AAVM/AA2R self-hosting tier (--features test-aavm, PLAN-700 起独立空 feature)——仅 aavm 改动后使用，裸跑=全集兜底、追加滤串缩小作用域（如cargo taa aavm2_m5）；触发条件/作用域映射/资源表见 §AAVM/AA2R Test Tiercargo ta- All test suites combined (--features test-aavm,test-trans,test-book; full scale)cargo t3- Milestone tier (大版本升级专用,Plan 532;频率最稀少档):全量 (ta 语义含 1M churn)+ 嵌套塔解释栈零漂移最终验收。塔测试体内T3_MILESTONEenv 自守门(未设秒退,防裸 cargo test / tf / ta 误触发 小时级运行),完整里程碑形态:T3_MILESTONE=1 cargo t3
3. Mandatory Independent Review Gate (独立复审)
Before merging or archiving, the agent must explicitly execute an independent review step (/auto-plan:review paradigm — verify, don't trust):
- Checklist Audit: Re-verify every acceptance criterion in
docs/plans/<NNN>-*.mdagainst the actual code/diff — a checked box is a claim, not evidence. - 遗漏/延后/Workaround Scan: Hunt explicitly for dropped sub-items, unapproved deferrals, and workaround patches; record findings as debt candidates in
docs/plans/KNOWN-DEBT-AND-RISKS.md. - Health Check: Ensure zero unhandled compiler warnings, clean formatting, and no stray debug print statements.
- Fill the spec-impact metadata (
supersedes_spec_components/new_spec_components/touched_goals) so merge knows what to deposit.
4. Plan Archiving & Status Tracking
- Update
docs/plans/<NNN>-<plan-name>.mdwith the review record (复审记录) and completion summary; flipstatus: reviewed. - Deposit knowledge per
/auto-plan:merge+ docs/specs/README.md §4 extension (.autoos/specs.jsonupsert + module overview/ADR/plans.md 回写 +python scripts/spec-index.py). - Archive the plan (terminal state — archived plans do not go back):
git mv docs/plans/<NNN>-<plan-name>.md docs/plans/archive/status: archivedin its frontmatter. Note: the user-level auto-plan skills writedocs/plans/archived/— in THIS repo the archive directory isdocs/plans/archive/. docs/plans/.next-idis bumped atomically byscripts/new-plan.shat plan creation time.
5. Worktree Merge & Cleanup
- Switch to
master, merge theplan-<NNN>-devbranch (or cherry-pick/fast-forward) with Conventional Commit format:feat(<scope>): <description> (Plan <NNN>) - Remove the temporary worktree and branch (guard first — mandatory):
bash D:/autostack/wt-guard.sh D:/autostack/.wt/lang-<NNN>/auto-lang # 必须输出 clean 才继续 git worktree remove D:/autostack/.wt/lang-<NNN>/auto-lang git branch -d plan-<NNN>-dev # 组内已无兄弟 worktree 时删除组目录：rmdir D:/autostack/.wt/lang-<NNN> - Summarize the completed work.