@fitlab-ai/agent-infra 0.8.4 → 0.9.0

package/templates/.agents/skills/release/SKILL.en.md

@@ -2,188 +2,41 @@
 name: release
 description: >
   Run the version release workflow.
-  Use when you are ready to cut and publish a new version.
+  Use when preparing and publishing a version. Parameter: X.Y.Z.
 ---
 
-# Version Release
+# Release
 
-Execute the version release workflow for the specified version.
+Release state is derived from external facts and prepare/publish require separate authorization.
 
-<!-- TODO: Adapt the steps below to your project's release process -->
+## 1. Validate Input and Entropy Report
 
-## Execution Flow
+Confirm SemVer and the human release checkpoint.
 
-### 1. Parse and Validate Version
-
-Extract version from arguments. Must match `X.Y.Z` format.
-
-Parse components:
-- MAJOR = X, MINOR = Y, PATCH = Z
-- Release version = `X.Y.Z`
-
-If format is invalid, error: "Version format incorrect, expected X.Y.Z (e.g. 1.2.3)"
-
-### 2. Verify Clean Workspace
+## 2. Inspect Facts
 
 ```bash
-git status --short
+agent-infra-internal release-workflow inspect {version}
 ```
 
-If there are uncommitted changes, error: "Workspace has uncommitted changes. Please commit or stash first."
-
-### 3. Pre-release Verification
-
-<!-- TODO: Replace with your project's pre-release verification steps -->
-
-Run any checks that must pass before preparing a release:
+## 3. Prepare
 
 ```bash
-git branch --show-current
-# TODO: Replace with your project's test/build verification commands
+agent-infra-internal release-workflow prepare {version} --entropy-report {path}
 ```
 
-Verification guidance:
-- Confirm the release is being prepared from the correct branch for your project
-- Run the full validation commands required by your release process
-
-Handling rules:
-- If the current branch is unexpected, print a warning or exit based on your policy
-- If any verification command fails, stop the release process and fix the issue first
-
-### 4. Update Version References
-
-<!-- TODO: Replace with your project's version update steps -->
-
-Search for version references in project files and update them:
-
-```bash
-# Find files with version references
-# Search for current version pattern
-# Update version strings
-```
+Stop after prepare; never publish implicitly.
 
-**Common files to update**:
-- `package.json` (Node.js)
-- `package-lock.json` (Node.js; run `npm install --package-lock-only` after updating `package.json`)
-- `pom.xml` (Maven)
-- `setup.py` / `pyproject.toml` (Python)
-- `version.go` (Go)
-- `README.md` (documentation)
-- `SECURITY.md` / `SECURITY.zh-CN.md` (supported version table)
-
-**Exclude from version replacement**:
-- `.agents/`, `.agents/workspace/`, `.claude/`, `.codex/`, `.gemini/`, `.opencode/` (AI tool configs)
-
-If the project uses `package-lock.json`, run `npm install --package-lock-only` after updating `package.json` so the lockfile version stays in sync.
-
-### 5. Rebuild Artifacts
-
-<!-- TODO: Replace with your project's artifact rebuild steps -->
-
-If version updates affect generated files, embedded metadata, or bundled assets, rebuild them now:
-
-```bash
-# TODO: Replace with your project's rebuild command(s)
-```
-
-Execution guidance:
-- Run this after updating version references so generated artifacts pick up the new version
-- If your project has no generated artifacts, document that explicitly in the project-specific skill
-- If the rebuild fails, stop the release process and fix the build first
-
-### 6. Create Release Commit
-
-```bash
-git add -A
-git commit -m "chore: release v{version}"
-```
+## 4. Publish Separately
 
-### 7. Create Git Tag
+Only after explicit user authorization:
 
 ```bash
-git tag v{version}
+agent-infra-internal release-workflow publish {version}
 ```
 
-### 8. Manage Milestones
-
-Close the milestone for the released version when it exists, and create the missing planning milestones for the next cycle.
-
-Run:
-
-```bash
-bash .agents/skills/release/scripts/manage-milestones.sh "$MAJOR" "$MINOR" "$PATCH"
-```
-
-The script is responsible for:
-- Read `.agents/rules/label-milestone-setup.md` before this step
-- Use its milestone list and update commands to load and adjust current milestones
-- Closing `{MAJOR}.{MINOR}.{PATCH}` when it exists and is still open
-- Ensuring `{MAJOR}.{MINOR}.{PATCH+1}` and `{MAJOR}.{MINOR}.x` exist
-- When `PATCH=0`, also ensuring `{MAJOR}.{MINOR+1}.0` and `{MAJOR}.{MINOR+1}.x`
-- Printing a milestone summary with the released milestone action and new milestone count
-
-### 9. Output Summary
-
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
-
-```
-Release v{version} prepared.
-
-Release info:
-- Version: {version}
-- Release commit: {commit-hash}
-- Tag: v{version}
-
-Files updated: {count}
-
-Next steps (manual):
-
-1. Push branch:
-   git push origin {current-branch}
-
-2. Push tag:
-   git push origin v{version}
-
-3. (Optional) Generate release notes:
-   - Claude Code / OpenCode: /create-release-note {version}
-   - Gemini CLI: /{{project}}:create-release-note {version}
-   - Codex CLI: $create-release-note {version}
-
-4. (Optional) Run post-release follow-up tasks:
-   - Claude Code / OpenCode: /post-release
-   - Gemini CLI: /{{project}}:post-release
-   - Codex CLI: $post-release
-```
-
-### Rollback Instructions
-
-If something went wrong:
-```bash
-# Delete tag
-git tag -d v{version}
-
-# Reset commit
-git reset --soft HEAD~1
-
-# Restore files
-git checkout -- .
-```
-
-## Notes
-
-1. **Clean workspace required**: Must have no uncommitted changes
-2. **No auto-push**: All operations are local only; user pushes manually
-3. **Pre-release verification**: Replace the Step 3 TODOs with the branch, test, and validation commands your release process requires
-4. **Generated artifacts**: Replace the Step 5 TODOs when version changes affect generated files, bundled assets, or embedded metadata
-5. **Release automation**: If pushing a tag triggers CI/CD or package publishing, confirm the required credentials and pipeline settings first
-6. **Version replacement scope**: Search determines which files to update; exclude AI tool directories
-7. **Adapt to your project**: The version update and rebuild steps above are generic; customize them for your project's versioning scheme
-8. **Milestone coordination**: Releases should create the next planning milestones automatically; initialize the taxonomy first with `init-milestones` when needed
+Push refs normally, preserve partial success for replay, and never force push.
 
-## Error Handling
+## 5. Report Facts
 
-- Invalid version format: Prompt correct format and exit
-- Dirty workspace: Prompt to commit or stash
-- Verification failure: Display the failing check and stop the release
-- Artifact rebuild failure: Display the build error and stop the release
-- Git operation failure: Display error and provide rollback instructions
+Show the snapshot and every TUI command. Treat unknown external state as blocked.

package/templates/.agents/skills/release/SKILL.zh-CN.md

@@ -2,188 +2,41 @@
 name: release
 description: >
   执行版本发布流程。
-  当准备切出并发布新版本时使用。
+  当准备切出并发布新版本时使用。参数：版本号（X.Y.Z）。
 ---
 
 # 版本发布
 
-执行指定版本的版本发布流程。
+发布由事实驱动，并拆为独立授权的 prepare 与 publish。
 
-<!-- TODO: 根据你的项目发布流程调整以下步骤 -->
+## 1. 检查输入与 entropy 报告
 
-## 执行流程
+确认 SemVer 和人工发布检查点已满足。
 
-### 1. 解析并验证版本号
-
-从参数中提取版本。必须匹配 `X.Y.Z` 格式。
-
-解析组件：
-- MAJOR = X，MINOR = Y，PATCH = Z
-- 发布版本 = `X.Y.Z`
-
-如果格式无效，报错："Version format incorrect, expected X.Y.Z (e.g. 1.2.3)"
-
-### 2. 验证工作区干净
+## 2. 检查事实
 
 ```bash
-git status --short
+agent-infra-internal release-workflow inspect {version}
 ```
 
-如果有未提交的变更，报错："Workspace has uncommitted changes. Please commit or stash first."
-
-### 3. 发布前验证
-
-<!-- TODO: 替换为你的项目发布前验证步骤 -->
-
-运行所有在准备发布前必须通过的检查：
+## 3. 准备发布
 
 ```bash
-git branch --show-current
-# TODO: 替换为你的项目测试/构建验证命令
+agent-infra-internal release-workflow prepare {version} --entropy-report {path}
 ```
 
-验证要求：
-- 确认发布使用的是项目规定的分支
-- 运行你的发布流程要求的完整校验命令
-
-处理规则：
-- 如果当前分支不符合预期，按项目策略输出警告或直接退出
-- 如果任何验证命令失败，停止发布流程并先修复问题
-
-### 4. 更新版本引用
-
-<!-- TODO: 替换为你的项目版本更新步骤 -->
-
-搜索项目文件中的版本引用并更新：
-
-```bash
-# 查找包含版本引用的文件
-# 搜索当前版本模式
-# 更新版本字符串
-```
+prepare 后停止，不得隐式 publish。
 
-**常见需要更新的文件**：
-- `package.json`（Node.js）
-- `package-lock.json`（Node.js；更新 `package.json` 后运行 `npm install --package-lock-only` 同步锁文件）
-- `pom.xml`（Maven）
-- `setup.py` / `pyproject.toml`（Python）
-- `version.go`（Go）
-- `README.md`（文档）
-- `SECURITY.md` / `SECURITY.zh-CN.md`（支持版本表格）
-
-**排除以下目录的版本替换**：
-- `.agents/`、`.agents/workspace/`、`.claude/`、`.codex/`、`.gemini/`、`.opencode/`（AI 工具配置）
-
-如果项目使用 `package-lock.json`，在更新 `package.json` 后运行 `npm install --package-lock-only`，确保锁文件中的版本号保持同步。
-
-### 5. 重新生成构建产物
-
-<!-- TODO: 替换为你的项目产物重建步骤 -->
-
-如果版本更新会影响生成文件、内嵌元数据或打包产物，现在重新生成它们：
-
-```bash
-# TODO: 替换为你的项目构建/重建命令
-```
-
-执行要求：
-- 在更新版本引用后运行，确保生成产物使用最新版本号
-- 如果项目没有生成产物，请在项目特化版本中明确说明
-- 如果重建失败，停止发布流程并先修复构建问题
-
-### 6. 创建发布提交
-
-```bash
-git add -A
-git commit -m "chore: release v{version}"
-```
+## 4. 独立发布
 
-### 7. 创建 Git 标签
+仅在用户明确授权后执行：
 
 ```bash
-git tag v{version}
+agent-infra-internal release-workflow publish {version}
 ```
 
-### 8. 管理里程碑
-
-为已发布版本关闭对应版本里程碑，并为下一轮创建缺失的规划里程碑。
-
-执行：
-
-```bash
-bash .agents/skills/release/scripts/manage-milestones.sh "$MAJOR" "$MINOR" "$PATCH"
-```
-
-脚本负责：
-- 执行前先读取 `.agents/rules/label-milestone-setup.md`
-- 使用其中的 milestone 查询与更新命令读取和调整当前里程碑
-- 在 `{MAJOR}.{MINOR}.{PATCH}` 存在且仍为开启状态时将其关闭
-- 确保 `{MAJOR}.{MINOR}.{PATCH+1}` 与 `{MAJOR}.{MINOR}.x` 存在
-- 当 `PATCH=0` 时，同时确保 `{MAJOR}.{MINOR+1}.0` 与 `{MAJOR}.{MINOR+1}.x`
-- 输出包含已发布里程碑动作和新建数量的汇总
-
-### 9. 输出摘要
-
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
-
-```
-版本 v{version} 已准备好发布。
-
-发布信息：
-- 版本：{version}
-- 发布提交：{commit-hash}
-- 标签：v{version}
-
-已更新文件数：{数量}
-
-下一步（手动执行）：
-
-1. 推送分支：
-   git push origin {current-branch}
-
-2. 推送标签：
-   git push origin v{version}
-
-3.（可选）生成发布说明：
-   - Claude Code / OpenCode：/create-release-note {version}
-   - Gemini CLI：/{{project}}:create-release-note {version}
-   - Codex CLI：$create-release-note {version}
-
-4.（可选）执行发布后处理：
-   - Claude Code / OpenCode：/post-release
-   - Gemini CLI：/{{project}}:post-release
-   - Codex CLI：$post-release
-```
-
-### 回滚说明
-
-如果出了问题：
-```bash
-# 删除标签
-git tag -d v{version}
-
-# 重置提交
-git reset --soft HEAD~1
-
-# 恢复文件
-git checkout -- .
-```
-
-## 注意事项
-
-1. **需要干净的工作区**：必须没有未提交的变更
-2. **不自动推送**：所有操作仅在本地执行；用户手动推送
-3. **发布前验证**：将步骤 3 的 TODO 替换为你的项目所需的分支、测试和验证命令
-4. **生成产物**：如果版本变化会影响生成文件、打包产物或内嵌元数据，需要将步骤 5 的 TODO 替换为实际命令
-5. **发布自动化**：如果推送标签会触发 CI/CD 或包发布，请先确认所需凭据和流水线配置
-6. **版本替换范围**：通过搜索确定需要更新哪些文件；排除 AI 工具目录
-7. **适配你的项目**：以上版本更新和产物重建步骤是通用的；请根据你的项目版本方案进行定制
-8. **里程碑联动**：发布时自动创建下一轮里程碑；如果里程碑体系未初始化，建议先运行 `init-milestones`
+逐 ref 普通 push；部分成功可重放，禁止 force push。
 
-## 错误处理
+## 5. 输出事实摘要
 
-- 版本格式无效：提示正确格式并退出
-- 工作区不干净：提示提交或暂存
-- 验证失败：显示失败的检查并停止发布流程
-- 产物重建失败：显示构建错误并停止发布流程
-- Git 操作失败：显示错误并提供回滚说明
+完整展示 snapshot 和后续 TUI 命令；unknown 必须视为 blocked。

package/templates/.agents/skills/restore-task/SKILL.en.md

@@ -12,7 +12,7 @@ Restore local task workspace files from platform Issue comments that contain syn
 ## Boundary / Critical Rules
 
 - Restore files only from comments that match the marker registry in `.agents/rules/issue-sync.md`
-- Restore into `.agents/workspace/active/{task-id}/` by default
+- Restore into a controlled staging directory under `.agents/workspace/`, then let lifecycle validate and place it under `active/{task-id}/`
 - Stop immediately if the target directory already exists and ask the user to resolve the conflict first
 - After executing this skill, you **must** immediately update the restored `task.md`
 
@@ -22,15 +22,9 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
-## Step Start: Write the started Marker
+## Step Start: Local Lifecycle Boundary
 
-After prerequisites pass and before this step's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
-
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Restore Task [started]** by {agent} — started
-```
-
-`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+Comment parsing must not write the formal active directory. Step 6 declares one restore intent that validates staging and atomically commits base metadata, the started/done pair, final placement, and short-id allocation.
 
 ## Steps
 
@@ -45,7 +39,7 @@ If the user provided `{task-id}`, validate the `TASK-{yyyyMMdd-HHmmss}` format.
 
 ### 2. Fetch Issue Comments
 
-Read all Issue comments by following the "Read Issue comments" command in `.agents/rules/issue-pr-commands.md`, preserving the original order and comment IDs.
+Run `agent-infra-internal platform-comment list --issue {issue-number}` to read all paginated comments while preserving order and comment IDs; the intent owns platform context, authentication, and upstream resolution.
 
 ### 3. Determine the task-id and Files to Restore
 
@@ -77,40 +71,28 @@ For each file:
 - concatenate chunk bodies into the final file content
 
 Before writing any file, verify that:
-- `.agents/workspace/active/{task-id}/` does not exist
+- no formal active, blocked, or completed directory exists for the task id
+- the unique `.agents/workspace/.restore-staging-*` path shares the active workspace filesystem
 
 If the directory already exists, stop immediately and tell the user to handle it manually first.
 
 ### 5. Write the Local Files
 
-Create `.agents/workspace/active/{task-id}/` and write files back in this order:
+Create the controlled staging directory and write files back in this order:
 
 1. `task.md`
 2. every other restored artifact file in filename order
 
 Write only files that were actually recovered from Issue comments. Do not invent missing files.
 
-### 6. Update the Restored task.md
-
-Get the current time:
+### 6. Apply the Restore Lifecycle Intent
 
 ```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
+agent-infra-internal task-lifecycle {task-id} restore --agent {agent} \
+  --staging-dir "{staging-dir}" --issue-number {issue-number}
 ```
 
-Update the restored `task.md`:
-- `status`: `active`
-- `assigned_to`: {current AI agent}
-- `updated_at`: {current time}
-- `agent_infra_version`: value from `.agents/rules/version-stamp.md`
-
-Append an Activity Log entry indicating the task was restored from the platform Issue.
-
-**Re-allocate short id** (the task directory is back under `active/`; alloc a new `#N`, which may differ from the pre-archival value):
-
-```bash
-node .agents/scripts/task-short-id.js alloc "$task_id"
-```
+Only `status=applied|no-op` means restore completed. The core validates task/Issue identity, file types, and artifact topology before exposing the active path, then commits metadata, Activity Log, placement, and short-id allocation. On `status=failed`, show recovery fields and retry the same intent; do not move staging or allocate manually.
 
 ### 7. Inform User
 

package/templates/.agents/skills/restore-task/SKILL.zh-CN.md

@@ -12,7 +12,7 @@ description: >
 ## 行为边界 / 关键规则
 
 - 只从匹配 `.agents/rules/issue-sync.md` 标记注册表的评论恢复文件
-- 默认恢复到 `.agents/workspace/active/{task-id}/`
+- 先恢复到 `.agents/workspace/` 内的受控 staging，校验后由 lifecycle 原子落位到 `active/{task-id}/`
 - 如果目标目录已存在，立即停止并提示用户先处理目录冲突
 - 执行本技能后，你**必须**立即更新恢复出的 `task.md`
 
@@ -22,15 +22,9 @@ description: >
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
-## 步骤开始：写入 started 标记
+## 步骤开始：本地生命周期边界
 
-确认前置条件后、本步骤第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
-
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Restore Task [started]** by {agent} — started
-```
-
-`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+评论解析阶段不写正式 active 目录。步骤 6 的单次 restore intent 统一校验 staging，并原子完成基础元数据、started/done 日志、正式落位和短号分配。
 
 ## 执行步骤
 ### 1. 验证输入与环境
@@ -44,7 +38,7 @@ description: >
 
 ### 2. 获取 Issue 评论
 
-按 `.agents/rules/issue-pr-commands.md` 中的 “Issue 评论读取” 命令读取 Issue 的全部评论，保留原始顺序和评论 ID。
+调用 `agent-infra-internal platform-comment list --issue {issue-number}` 读取全部分页评论，保留原始顺序和评论 ID；平台上下文、认证和 upstream 由 internal intent 处理。
 
 ### 3. 确定 task-id 与待恢复文件
 
@@ -76,40 +70,28 @@ description: >
 - 拼接得到最终文件内容
 
 在写文件前检查：
-- `.agents/workspace/active/{task-id}/` 不存在
+- `.agents/workspace/active/{task-id}/`、`blocked/{task-id}/`、`completed/{task-id}/` 均不存在
+- 创建唯一 `.agents/workspace/.restore-staging-*` 路径，且与 active 位于同一文件系统
 
 如果目录已存在，立即停止并提示用户先手动处理。
 
 ### 5. 写回本地文件
 
-创建 `.agents/workspace/active/{task-id}/`，按以下顺序写回：
+创建受控 staging 目录，按以下顺序写回：
 
 1. `task.md`
 2. 其余产物文件（按文件名排序）
 
 仅写回从 Issue 评论中实际恢复出的文件，不补造缺失文件。
 
-### 6. 更新恢复后的 task.md
-
-获取当前时间：
+### 6. 执行 restore 生命周期意图
 
 ```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
+agent-infra-internal task-lifecycle {task-id} restore --agent {agent} \
+  --staging-dir "{staging-dir}" --issue-number {issue-number}
 ```
 
-更新恢复出的 `task.md`：
-- `status`：`active`
-- `assigned_to`：{当前 AI 代理}
-- `updated_at`：{当前时间}
-- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
-
-追加 Activity Log，说明任务已从平台 Issue 还原。
-
-**重新分配短号**（已把任务目录写回 `active/`，需要在锁内重新 alloc；新短号可能与归档前不同）：
-
-```bash
-node .agents/scripts/task-short-id.js alloc "$task_id"
-```
+仅 `status=applied|no-op` 视为恢复完成。核心在正式 active 路径暴露前校验 task/Issue 身份、文件类型与 artifact topology，并统一更新 active 元数据、Activity Log、目录和短号。`status=failed` 时展示 recovery 字段，以同一 intent 重试；不得手工移动 staging 或分配短号。
 
 ### 7. 告知用户
 

package/templates/.agents/skills/restore-task/config/verify.json

@@ -17,8 +17,7 @@
       "require_issue_number": true
     },
     "activity-log": {
-      "expected_action_pattern": "Restore Task",
-      "freshness_minutes": 30
+      "expected_action_pattern": "Restore Task"
     },
     "platform-sync": null
   }