✨ feat(playbook): add playbook root boundary placeholder

scripts/playbook.py

@@ -626,10 +626,13 @@ def replace_placeholders(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
+    playbook_root: str | None,
 ) -> str:
     result = text.replace("{{DATE}}", date_value)
     if project_name:
         result = result.replace("{{PROJECT_NAME}}", project_name)
+    if playbook_root:
+        result = result.replace("{{PLAYBOOK_ROOT}}", playbook_root)
     if playbook_scripts:
         result = result.replace("{{PLAYBOOK_SCRIPTS}}", playbook_scripts)
     return result
@@ -649,11 +652,14 @@ def replace_placeholders_in_file(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
+    playbook_root: str | None,
 ) -> None:
     if file_path.suffix != ".md":
         return
     text = file_path.read_text(encoding="utf-8")
-    updated = replace_placeholders(text, project_name, date_value, playbook_scripts)
+    updated = replace_placeholders(
+        text, project_name, date_value, playbook_scripts, playbook_root
+    )
     if updated != text:
         file_path.write_text(updated, encoding="utf-8", newline="\n")
 
@@ -673,6 +679,7 @@ def sync_directory(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
+    playbook_root: str | None,
     force: bool,
     no_backup: bool,
 ) -> None:
@@ -693,6 +700,7 @@ def sync_directory(
             project_name,
             date_value,
             playbook_scripts,
+            playbook_root,
         )
 
 
@@ -720,10 +728,11 @@ def update_agents_section(
     project_name: str | None,
     date_value: str,
     playbook_scripts: str | None,
+    playbook_root: str | None,
 ) -> None:
     template_text = template_path.read_text(encoding="utf-8")
     template_text = replace_placeholders(
-        template_text, project_name, date_value, playbook_scripts
+        template_text, project_name, date_value, playbook_scripts, playbook_root
     )
     block = extract_block_lines(template_text, start_marker, end_marker)
     if not block:
@@ -802,6 +811,7 @@ def sync_agents_template(context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
+    playbook_root = resolve_playbook_root(context)
     date_value = resolve_template_date(context)
 
     agents_dst = project_root / "AGENTS.md"
@@ -828,6 +838,7 @@ def sync_agents_template(context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
+        playbook_root,
     )
     sync_claude_md(project_root, context.get("config", {}))
     return 0
@@ -944,12 +955,15 @@ def sync_rules_action(config: dict, context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
+    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     no_backup = bool(config.get("no_backup", False))
 
     backup_path(rules_dst, no_backup)
     text = rules_src.read_text(encoding="utf-8")
-    text = replace_placeholders(text, project_name, date_value, playbook_scripts)
+    text = replace_placeholders(
+        text, project_name, date_value, playbook_scripts, playbook_root
+    )
     rules_dst.write_text(text.rstrip("\n") + "\n", encoding="utf-8", newline="\n")
     log("Synced: AGENT_RULES.md")
 
@@ -987,6 +1001,7 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
 
     project_name = config.get("project_name")
     playbook_scripts = resolve_playbook_scripts(context)
+    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     force = bool(config.get("force", False))
     no_backup = bool(config.get("no_backup", False))
@@ -999,6 +1014,7 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
+        playbook_root,
         force,
         no_backup,
     )
@@ -1020,6 +1036,7 @@ def sync_prompts_action(config: dict, context: dict) -> int:
 
     project_name = resolve_project_name(context)
     playbook_scripts = resolve_playbook_scripts(context)
+    playbook_root = resolve_playbook_root(context)
     date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
     force = bool(config.get("force", False))
     no_backup = bool(config.get("no_backup", False))
@@ -1033,6 +1050,7 @@ def sync_prompts_action(config: dict, context: dict) -> int:
         project_name,
         date_value,
         playbook_scripts,
+        playbook_root,
         force,
         no_backup,
     )

templates/AGENT_RULES.template.md

@@ -41,6 +41,23 @@
 - 只做当前任务需要的改动，不顺手加功能、不顺手重构
 - 不为一次性操作增加抽象，不为假设的未来需求设计
 
+## 项目边界
+
+### Playbook 目录
+
+- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码、
+  业务文档或当前项目私有规则
+- 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改
+  `{{PLAYBOOK_ROOT}}/` 下内容
+- 当前项目已生效的规则入口是项目根目录的 `AGENT_RULES.md`、
+  `AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/`
+- `{{PLAYBOOK_ROOT}}/templates/` 与 `{{PLAYBOOK_ROOT}}/rulesets/`
+  是模板源；不要把它们当作当前项目已生效规则
+- 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档；
+  读取不代表该目录属于业务改动范围
+- 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`；
+  只有任务目标明确涉及 Playbook 时才纳入
+
 ## 会话启动
 
 每次新会话开始时，按顺序加载以下上下文：

templates/README.md

@@ -141,7 +141,7 @@ python scripts/playbook.py -config playbook.toml
 - **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
 - **no_backup**：默认 false；设为 true 时跳过备份直接覆盖
 - **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
-- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_SCRIPTS}}`
+- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_ROOT}}`、`{{PLAYBOOK_SCRIPTS}}`
 
 ### 典型场景
 
@@ -229,11 +229,15 @@ project/
 | `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
 | `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
 | `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
+| `{{PLAYBOOK_ROOT}}`       | Playbook 根  | ✅ 是    |
 | `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
 | 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |
 
 `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
 未配置时保持原样。
+`{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录
+（默认 `docs/standards/playbook`，
+也可按项目配置改成 `custom/playbook` 等）。
 `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
 （默认 `docs/standards/playbook/scripts`，
 也可按项目配置改成 `custom/playbook/scripts` 等）。