用途:在用户要求初始化 Sift、把 Sift 加入仓库或创建 Sift 目录树时使用。它先解析项目根目录,再幂等地创建或修复 .ai/sift 树,不创建首个工单,也不执行其他 Sift 任务。
主要能力:通过 scripts/sift-gate.sh 只读地向上查找根目录,按优先级采用已有 .ai/sift、.git 或 AGENTS.md/CLAUDE.md 所在目录,并输出 state、root、tier、confidence 等键值。根据退出码决定动作:READY 继续;UNINITIALIZED 高置信度直接初始化,低置信度需先询问;UNRESOLVED 需用户指定根目录;INCOMPLETE 直接修复。
使用方式:先运行 scripts/sift-gate.sh 获取 ROOT;用 scripts/sift-init.sh --suggest-prefix --root "$ROOT" 生成前缀建议,前缀须为 2 到 8 位大写字母或数字且以字母开头,里程碑须为小写 kebab-case,默认 backlog;再运行 scripts/sift-init.sh --root "$ROOT" --prefix ACME [--milestone <name>] 创建缺失条目。重复运行只修复缺失项,保留已有文件,不恢复缺失的 .gitignore。
适用场景:为仓库引入 Sift 工单体系、修复不完整的 .ai/sift 树、检查已安装约定文件是否与技能资产不一致。
限制:初始化只写 .ai/sift,绝不修改仓库根 .gitignore;默认不跟踪该目录,删除 .ai/sift/.gitignore 才纳入跟踪;刷新约定文件需用户明确批准,不自动覆盖;退出码 2 表示用法或环境错误,应停止并报告。