skein-setup

# skein-setup — 初始化 / 结构维护 > 🔒 全局流程规则（状态机/调度/优先级等）以 skein-flow/references/ 为单一真值源。 两用途：**① 未初始化仓库 → 建 `.skein/` 工作区**；**② 已初始化 → 手动优化 `.skein/` 结构**。**幂等** — 重跑安全。 > 触发: 用户显式要求初始化 / 迁移 / 维护 SKEIN 工作区, 或 SessionStart hook 注入「无 `.skein/`」提示后 main 主动调用。 ## 分流 ```bash skein setup # 幂等 scaffold + 输出 manifest JSON ``` | manifest / 现状 | 用途 | 见 | |---|---|---| | 无 `.skein/` (`trellis_present:false`) | **① 初始化** — main 直接跑, 纯机械 | 下 §初始化 | | 已有 `.skein/`, `spec/` 已是 `rules/product/map/external` 新结构 | **② 结构维护** — 用户手动优化 | 下 §结构维护 | | 已有 `.skein/`, 检出 `spec/core/` (旧两层结构残留) | **② 的前置** — 提示迁移新 namespace 结构, 用户拒绝仍可继续②用旧路径 | `../skein-spec/references/migration-v2.md` | | 检测到 `.trellis/` (`trellis_present:true`) | ① 的一种场景 — 派 agent 语义迁移 | `references/trellis-migration.md` | ## ① 初始化 (未初始化仓库) 1. **新仓** → main 直接跑 `skein setup` (纯机械, 不派 agent): 建 `.skein/` + config + gitignore + 本地 `.skein/spec` 库 (直接落 `rules/product/map/external` 四 namespace 目录, 不经过旧两层结构)。完成即可用。 2. **既有 trellis 仓 (`.trellis/`)** → 🛑 检测到 `.trellis/` 时 main 用 `AskUserQuestion` 让用户选迁移模式 (缺省兼容 · STOP, `--full` 整删不可逆): 兼容 (留 `.trellis/` 数据) / `--full` (整删 `.trellis/`); 接线 (hooks/scripts/settings) 两模式都删。据选定跑 `setup` 或 `setup --full`, 语义迁移 (派 skein-setup agent) 详见 `references/trellis-migration.md` (目标结构同 §②旧结构检出: 四 namespace)。 ## 旧两层结构检出 (`spec/core/` 存在, 独立于 trellis 迁移) 已初始化仓 (`.skein/` 已存在) 若检出 `spec/core/` 目录 (旧 core/recall 两层, 迁移新 namespace×inclusion 结构前的遗留) → 🛑 main 用 `AskUserQuestion` 提示「检测到旧两层结构, 是否迁移新 namespace 结构 (rules/product/map/external)」。用户同意 → 走 [migration-v2.md](../skein-spec/references/migration-v2.md) 两阶段流程 (阶段 1 机械改名无损, 阶段 2 语义分拣 product/map 无硬性完成线)。用户拒绝 → 旧结构继续可用 (`skein-spec` 各命令兼容旧路径读取, 新写入统一走新结构), 不阻塞正常使用, 不强迁。 ## ② 结构维护 (已初始化, 用户手动优化) 用户想调整 `.skein/` 布局时用。可调项 + 落地方式： | 想改 | 怎么改 | 收尾 | |---|---|---| | 并发上限 (max_active) | 直接 Edit `.skein/config.yaml` | 无 | | spec 类目重组 (类目 = namespace 内子目录, 自由取名 git/test/arch/build/style/domain/ops...) | 移动 / 改名 `.skein/spec/<namespace>/<category>/*.md` (`namespace` 自由目录, 默认 `rules/product/map/external`) | `skein-spec reindex` | | 调加载策略 (页过重超 `spec.always_budget` 会告警, 数值见 `.skein/config.yaml`) | 改规则文件 frontmatter 的 `inclusion:` (`always`/`auto`/`fileMatch`/`manual` 四值, 与 namespace 正交), **不要搬文件** — 目录 = namespace(内容类型), 与加载策略无关; 或跑 `skein-spec degrade <cat>/<name>` 自动改 (`always`→`auto`) | `skein-spec reindex` | | 新增一条规则 | `skein-spec sediment --namespace <ns> [--inclusion always\|auto] --category <cat> --topic <主题> --title <T>` | 追加为主题文件章节 + 自动 reindex | - **改 spec 盘后必 `reindex`** — 索引 (三份 index.md) 落后于实际盘面 = 召回失效。 - **task.json / task.md 禁手改** — 经 `skein task create/confirm/...` 命令维护, PreToolUse hook 硬阻直接写。 ## 铁律 (通用) - **幂等** — 已初始化重跑不覆盖 (config/spec 存在则跳过); `.skein/spec` 已存在则不重复拷贝。 - **spec 盘面变更后 reindex** — 手动重组 / 迁移后同步索引。 - **task 状态经脚本** — 不直接编辑 `.skein/task*`。 ## ✅ 正向配方 (命中反面=流程错误) > 🔒 铁律: 幂等可重跑; task.json/task.md 经脚本不经手改 (PreToolUse hook 硬阻)。 | 场景 | 正确做法 (❌ 反面) | |---|---| | 改 `.skein/task*` | 经 `skein task create/confirm/...` 命令改 (❌ 手改绕脚本 → PreToolUse hook 硬阻 + 破坏索引一致性) | | 改 spec 盘面后 | 必跑 `skein-spec reindex` (❌ 不 reindex → 三份 index.md 落后盘面 = 召回失效) | | 检测到 `.trellis/` | 先 `AskUserQuestion` 选兼容 / `--full` 再迁移 (❌ 直接 `setup --full` → 未问用户整删可能丢数据) | | 已初始化仓重跑 | 正常重跑, config/spec 存在则跳过 (❌ 当报错 → setup 幂等, 重跑安全不覆盖) | | 规则归类 | 默认 `namespace=rules` + `inclusion=auto`, `inclusion=always` 只留命令式硬契约 (❌ 什么都堆进 always 常驻 → 超预算告警, 稀释硬约束) | | 检出 `spec/core/` 旧结构 | `AskUserQuestion` 征同意再走 migration-v2 两阶段迁移 (❌ 不问用户直接批量改路径, 或放任旧结构不提示) | ## 失败模式 (if-then 三段式: 触发 → 一线修复 → 仍失败兜底) | 触发 | 一线修复 | 仍失败兜底 | |---|---|---| | `skein setup` 报错 | 读 manifest JSON `error` 字段定位 (权限 / 路径占用 / 已存在) | 仍失败 → 报用户, 禁手工拼凑 `.skein/` | | `skein-spec reindex` 报错 | 读 stderr 定位 (类目名非法 / 路径) | 仍失败 → 停手报用户, 禁半写坏索引 | | trellis 迁移中断 | 数据仍在 `.trellis/` (兼容模式未删), 重跑迁移 | 仍中断 → 报用户, 禁手工拼凑 `.skein/` |