Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d

25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps
2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows
98c3f30 📝 docs(agent_rules): allow plan execution on current branch
16c7230 📝 docs(prompts): define custom verify layering
8efc4dd 🐛 fix(skills): quote commit-message description
bc8498f 🐛 fix(ci): install tomli for gitea tests
55cda3b 🐛 fix(tests): report missing toml parser clearly
c0729c7 🐛 fix(playbook): import Optional for cli compatibility
63e24bf 📦 deps(skills): sync thirdparty skills
d2f9356 🐛 fix(ci): isolate gitea workflow repos
588b81d 🐛 fix(ci): inline gitea workflow bootstrap
e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts
2c5050d ♻️ refactor(skills): rename repo skills source dir
f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills
234b335 ✨ feat(workflow): add superpowers planning and execution state tracking
c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates
2325409 📝 docs(markdown): clarify optional markdownlint usage
214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes
a22b324 📝 docs(templates): add execution and memory-bank prompt templates
223a797 📝 docs(templates): update README for Claude Code and current features
4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules
2431c9d 📝 docs: add claude_md config and use cross-platform paths
d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info
c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root
6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery
6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt
9f8b6b5 📝 docs: update README and config example for Claude Code support
79cff6c 📝 docs(skills): add Claude Code platform support
452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md
e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill
f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows
da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows
7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script
f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout
b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory
64950e7 📦 deps(skills): sync thirdparty skills
a2e3cb0 ✨ feat(playbook): add no_backup deploy controls
8609d59 🐛 fix(docs): repair reference catalog source links
956da11 🐛 fix(playbook): publish hidden ci test fixes
3f67754 📦 deps(skills): sync thirdparty skills
08ca87b 📦 deps(skills): add karpathy thirdparty sync
96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual
3ed5052 📦 deps(skills): sync thirdparty skills
60108dd 📦 deps(skills): sync thirdparty skills
da85d4e 🐛 fix(thirdparty): prune nested project snapshots
a2a697e 📦 deps(skills): sync thirdparty skills
9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills
33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields
91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update
2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline
5b9c1e3 📦 deps(skills): sync superpowers
2f2d34a 📝 docs(readme): normalize subtree command spacing
62db7db 🐛 fix(ci): serialize superpowers update and sync
3463223 🐛 fix(ci): use literal superpowers sync paths
48f6de8 📦 deps(skills): sync superpowers
4b23529 🔧 chore(ci): merge superpowers update and sync workflow
a56d75b 📦 deps(skills): sync superpowers
84bcefa 🔧 chore(ci): use ci[bot] commit author name
00a07e5 📦 deps(skills): sync superpowers
7b84daf 🐛 fix(templates): enforce main loop progress tracking
51373d7 🔧 chore(ci): automate superpowers sync workflow
eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block
79755c6 📦 deps(skills): sync superpowers
836d878 📦 deps(skills): sync superpowers
8216c9f 📦 deps(skills): sync superpowers
9439505 🐛 fix(playbook): address reported repo issues

git-subtree-dir: docs/standards/playbook
git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316

docs/tsl/toolchain.md

@@ -1,76 +1,132 @@
-# TSL 工具链与验证命令（模板）
+# TSL 工具链与验证命令
 
-本文件提供一份**通用占位模板**，用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。
+文档类型：模板页
+是否可直接用于生成代码：否
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：项目自身文档、`scripts/*` 入口脚本、CI 配置
 
-最小必填清单（落地到具体项目时必须补齐，否则文档不可用）：
+这里处理项目执行类问题，不处理通用 TSL 语法事实。
 
-- 工具名称、可执行命令、安装方式（版本要求可选）
-- 至少一个可运行的“最小冒烟”命令（或脚本入口）
-- 失败处理约定（含：无法执行时的替代验证方式）
+如果问题在问执行命令、脚本入口、CI、验证方式、环境变量或部署流程，这不是语法问题，而是项目执行类问题；应先回项目自身文档、`scripts/*` 入口脚本和 CI 配置。默认检索 TSL 语法、代码写法或真实执行命令时，应忽略本页。本页只是一份待补齐模板，不提供真实可执行命令。
 
-使用方式：
+## 模板说明
 
-- 在具体项目中复制本模板并把占位符替换为真实信息；
-- 或在项目文档中引用本模板，并在项目内提供对应的 `scripts/*` 统一入口脚本。
+- 本文件提供一份通用占位模板，不是通用执行手册。
+- 只有在当前项目已经把工具链、执行入口和验证命令补齐后，才可以把它当成执行依据。
+- 如果这页里仍然出现 `<...>` 形式的占位符，说明当前项目还没有补齐真实信息，应回到项目自身文档或脚本入口。
+- 以下命令片段全部属于模板占位，不是真实 CLI 示例，也不应被 AI 直接复制执行。
 
-## 1. TSL 工具链
+## 为什么不可直接执行
 
-### 1.1 解释器/编译器（必填）
+- 占位符没有绑定到当前项目的真实解释器、路径、环境变量和脚本入口。
+- 同一条模板命令在不同项目里可能对应不同的安装方式、权限模型和验证流程。
+- 如果直接照抄本页内容，最常见的错误是路径不存在、可执行入口错误、凭证缺失或验证层级不匹配。
+
+## 项目补齐项
+
+### 解释器/编译器（必填）
 
 - 工具名称：`<tsl/tslcli/内部工具名>`
-- 可执行命令（统一用 `<tsl>` 表示 TSL 可执行入口）：
-  - macOS/Linux：`<tsl>`（例：`tsl` / `sh scripts/tsl.sh`）
-  - Windows：`<tsl>`（例：`tsl.exe` / `powershell -File scripts/tsl.ps1`）
-- 基本执行方式：`<tsl> <path/to/script.tsl> <args...>`（TSL 通常直接执行脚本文件）
-- 版本要求（可选）：`<固定版本或范围，例如：= 3.2.1 / >=3.2,<4.0>`（未知可留空或写
-  `N/A`）
 - 安装方式：`<内部安装包/路径/IDE 自带/CI 镜像等>`
-- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`（封装参数与环境变量，避免每个任务重复猜测）
+- 版本要求：`<固定版本或范围；未知可写 N/A>`
+- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`
 
-### 1.2 运行环境（按需）
+可执行入口模板：
 
-- 必要环境变量：`<TSL_HOME> <TSL_LIB_PATH> <LICENSE_PATH> ...`
-- 外部依赖：`<数据库/服务/共享目录/网络权限/账户权限>`
-- 运行约束：
-  - 是否允许联网：`<yes/no>`
-  - 是否需要许可证/凭证：`<说明如何在本地与 CI 提供；禁止写入仓库>`
-  - 约定：凭证/许可证等敏感信息通过环境变量或 CI
-    secrets 注入；文档只写变量名/获取方式，不写明文值。
+代码块身份：配置片段 / 概念骨架
 
-## 2. 验证命令
+```text
+<tsl>
+<tsl> <path/to/script.tsl> <args...>
+```
 
-> 要求：改动完成后至少能跑通“最小冒烟”；若项目存在测试体系，尽量补到对应层级。
+平台命令模板：
 
-### 2.1 最小冒烟（必须能跑）
+代码块身份：配置片段 / 概念骨架
 
-- macOS/Linux：`<tsl> <path/to/SmokeTest.tsl> <args...>`
-- Windows：`<tsl> <path\\to\\SmokeTest.tsl> <args...>`
-- 或统一入口：
-  - `sh scripts/smoke.sh`
-  - `powershell -File scripts/smoke.ps1`
-- Success
-  signal（建议写清）：退出码为 0；并给出“成功时的关键输出/产物路径”（例如输出包含某行、或生成某文件）。
+```text
+macOS/Linux: <tsl>
+Windows: <tsl>
+```
 
-### 2.2 单元测试（如有）
+### 运行环境（按需）
 
-- `sh scripts/test.sh`
-- 或：`<tsl> <path/to/TestRunner.tsl> <args...>`
-- Success signal：退出码为 0；失败时能定位到具体用例/输入。
+- 必要环境变量模板：
 
-### 2.3 静态检查/格式化（如有）
+代码块身份：配置片段 / 概念骨架
 
-- `sh scripts/lint.sh`
-- `sh scripts/format.sh`
-- Success
-  signal：退出码为 0；formatter 二次运行无新增 diff（若项目提供 formatter）。
+```text
+<TSL_HOME>
+<TSL_LIB_PATH>
+<LICENSE_PATH>
+```
 
-### 2.4 构建/打包（如有）
+- 外部依赖模板：
 
-- `sh scripts/build.sh`
-- Success signal：退出码为 0；产物路径明确且可复现（例如输出目录/包名）。
+代码块身份：配置片段 / 概念骨架
 
-### 2.5 失败处理约定（必填）
+```text
+<数据库/服务/共享目录/网络权限/账户权限>
+```
+
+- 运行约束模板：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+是否允许联网：<yes/no>
+是否需要许可证/凭证：<说明如何在本地与 CI 提供；禁止写入仓库>
+```
+
+- 凭证、许可证等敏感信息应通过环境变量或 CI secrets 注入；文档只写变量名或获取方式，不写明文值。
+
+### 验证命令（必须补齐）
+
+- 至少补齐一个最小冒烟命令。
+- 如果项目存在测试体系，应继续补齐单元测试、静态检查和构建命令。
+- 所有命令都应替换成当前项目的真实入口，不要保留模板占位。
+
+最小冒烟模板：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+<tsl> <path/to/SmokeTest.tsl> <args...>
+sh scripts/smoke.sh
+powershell -File scripts/smoke.ps1
+```
+
+单元测试模板：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+sh scripts/test.sh
+<tsl> <path/to/TestRunner.tsl> <args...>
+```
+
+静态检查 / 格式化模板：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+sh scripts/lint.sh
+sh scripts/format.sh
+```
+
+构建 / 打包模板：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+sh scripts/build.sh
+```
+
+成功信号也必须补齐为真实规则，例如退出码、关键输出或产物路径。
+
+### 失败处理约定（必填）
 
 - 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。
-- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。
-- 建议在输出中记录：执行的命令、退出码、以及关键日志片段（便于 review 与复现）。
+- 若某验证步骤无法执行，必须明确写出原因与替代验证手段，例如最小复现脚本或手动检查清单。
+- 建议记录：执行的命令、退出码、关键日志片段和产物位置，便于 review 与复现。