fix: harden skill template contracts and scaffolding

Align scaffold slug replacement, Action manifest strict boundaries, metadata prune API, field permission validation, and task_logs readonly semantics with documented template contracts.

Co-authored-by: Cursor <cursoragent@cursor.com>

references/SCHEMA.md

@@ -236,6 +236,16 @@ readonly = 0
 
 ### 模板默认：`task_logs`
 
+`task_logs` 是技能内部**系统自动写入**的任务审计日志（由 `task_logs_repository` INSERT/UPDATE），不是供用户在宿主数据管理中手工维护的业务表。
+
+权限设计：
+
+| 层级 | 值 | 说明 |
+|------|-----|------|
+| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/删除表单 |
+| 所有业务字段 `editable` | `0` | 含 `task_type`、`status`、`error_msg`、`result_summary` 等 |
+| 技能内部 repository | 正常 INSERT/UPDATE | 元数据权限只约束宿主 UI，不限制技能代码写库 |
+
 物理定义（权威顺序）：
 
 ```sql
@@ -258,17 +268,17 @@ CREATE TABLE IF NOT EXISTS task_logs (
 | 物理字段 | 中文名 | editable |
 |----------|--------|----------|
 | id | 编号 | 0 |
-| task_type | 任务类型 | 1 |
-| target_id | 目标编号 | 1 |
-| input_id | 输入编号 | 1 |
-| input_title | 输入标题 | 1 |
-| status | 状态 | 1 |
-| error_msg | 错误信息 | 1 |
-| result_summary | 结果摘要 | 1 |
+| task_type | 任务类型 | 0 |
+| target_id | 目标编号 | 0 |
+| input_id | 输入编号 | 0 |
+| input_title | 输入标题 | 0 |
+| status | 状态 | 0 |
+| error_msg | 错误信息 | 0 |
+| result_summary | 结果摘要 | 0 |
 | created_at | 创建时间 | 0 |
 | updated_at | 更新时间 | 0 |
 
-表中文名：**任务日志**；表级 `readonly = 0`。
+表中文名：**任务日志**；表级 `readonly = 1`（宿主只读；技能 repository 仍可写入）。
 
 ### 通用示例：`demo_items`（测试 fixture 参考）
 
@@ -325,8 +335,41 @@ CREATE TABLE demo_items (
 实现 helper：
 
 - `upsert_table_metadata` / `upsert_column_metadata` — 幂等写入
+- `seed_column_metadata_batch` — 批量 upsert；**可选**传入 `valid_column_names` 时在 upsert 后自动 prune
 - `prune_stale_column_metadata` — 清理已删除物理字段的元数据
 
+### 新增业务表时如何初始化
+
+1. 在 `connection.py`（或迁移脚本）中 `CREATE TABLE` 真实物理表。
+2. 用 `PRAGMA table_info` 或 `list_physical_column_names` 取得**真实物理字段列表**（顺序以 `cid` 为准）。
+3. 调用 `upsert_table_metadata` 写入表级元数据。
+4. 调用 `seed_column_metadata_batch`，并传入 `valid_column_names=physical_column_names`：
+
+```python
+from db.display_metadata import list_physical_column_names, seed_column_metadata_batch, upsert_table_metadata
+
+physical = list_physical_column_names(cursor, "demo_items")
+upsert_table_metadata(cursor, table_name="demo_items", display_name="示例记录", readonly=0)
+seed_column_metadata_batch(
+    cursor,
+    table_name="demo_items",
+    columns=DEMO_ITEMS_COLUMN_METADATA,
+    valid_column_names=physical,
+)
+```
+
+传入 `valid_column_names` 时：先 upsert，再删除不在物理表中的陈旧 `_jiangchang_columns` 行。
+
+### 字段删除或重命名时如何清理
+
+1. 在 DDL / 迁移中完成物理字段删除或重命名。
+2. 重新执行 `seed_column_metadata_batch(..., valid_column_names=当前物理字段列表)`，自动 prune 旧字段元数据。
+3. 或单独调用 `prune_stale_column_metadata(cursor, table_name, valid_column_names)`。
+
+**不传入 `valid_column_names` 时不会自动 prune**——模板不会猜测真实物理字段，避免误删；文档与实现均以此为准。
+
+不要直接修改用户真实数据库作为迁移方式；元数据初始化必须使用真实物理字段列表。
+
 ## 中文命名质量
 
 - 使用普通用户能理解的业务用语：`task_logs` → **任务日志**，`error_msg` → **错误信息**。