@fitlab-ai/agent-infra 0.9.11 → 0.9.13

package/templates/.agents/skills/import-codescan/SKILL.en.md

@@ -34,7 +34,7 @@ This skill **creates** task.md, so there is no file to write at the start. Captu
 
 ### 1. Retrieve Alert Information
 
-Read `.agents/rules/security-alerts.md` before this step, then use its Code Scanning alert read command to fetch the alert details.
+Read `.agents/rules/security-alerts.md` before this step, then run `bash .agents/scripts/security-alerts.sh read-codescan --number {alert-number}` and parse its JSON result to fetch the alert details.
 
 Extract key information:
 - `number`: alert number

package/templates/.agents/skills/import-codescan/SKILL.zh-CN.md

@@ -34,7 +34,7 @@ description: >
 
 ### 1. 获取告警信息
 
-执行前先读取 `.agents/rules/security-alerts.md`，并按其中的 Code Scanning 告警读取命令获取告警详情。
+执行前先读取 `.agents/rules/security-alerts.md`，然后运行 `bash .agents/scripts/security-alerts.sh read-codescan --number {alert-number}`，解析其 JSON 结果获取告警详情。
 
 提取关键信息：
 - `number`：告警编号

package/templates/.agents/skills/import-dependabot/SKILL.en.md

@@ -34,7 +34,7 @@ This skill **creates** task.md, so there is no file to write at the start. Captu
 
 ### 1. Retrieve Alert Information
 
-Read `.agents/rules/security-alerts.md` before this step, then use its Dependabot alert read command to fetch the alert details.
+Read `.agents/rules/security-alerts.md` before this step, then run `bash .agents/scripts/security-alerts.sh read-dependabot --number {alert-number}` and parse its JSON result to fetch the alert details.
 
 Extract key information:
 - `number`: alert number

package/templates/.agents/skills/import-dependabot/SKILL.zh-CN.md

@@ -34,7 +34,7 @@ description: >
 
 ### 1. 获取告警信息
 
-执行前先读取 `.agents/rules/security-alerts.md`，并按其中的 Dependabot 告警读取命令获取告警详情。
+执行前先读取 `.agents/rules/security-alerts.md`，然后运行 `bash .agents/scripts/security-alerts.sh read-dependabot --number {alert-number}`，解析其 JSON 结果获取告警详情。
 
 提取关键信息：
 - `number`：告警编号

package/templates/.agents/skills/init-labels/SKILL.en.md

@@ -15,7 +15,7 @@ Initialize the repository's standard labels taxonomy.
 
 Confirm that:
 - read `.agents/rules/label-milestone-setup.md` first
-- use its authentication commands to verify platform access
+- the repository configuration and requested mapping are ready
 
 If any prerequisite fails, stop and report the matching error.
 
@@ -28,9 +28,9 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 ```
 
 The script and `.agents/rules/label-milestone-setup.md` are responsible for:
-- Capturing the current label snapshot before making changes
-- Creating or updating the standard label set with the platform-specific label command
-- Reporting unmatched platform-default labels such as `question` and `wontfix`
+- Reading the configured `labels.in` mapping and preserving unrelated labels
+- Selecting the provider leaf or returning a clear no-op/degraded result
+- Creating or updating the standard label set and reporting the final summary
 - Printing the final execution summary
 
 ### 3. Standard taxonomy
@@ -69,8 +69,8 @@ Show the current mapping and ask whether it should be updated.
 #### 4.3 Write the mapping and create labels
 
 1. Write the final mapping to `.agents/.airc.json` under `labels.in`.
-2. Create one `in: {key}` label for each mapping key by following the label-create command in `.agents/rules/label-milestone-setup.md`.
-3. After user confirmation, delete stale `in:` labels that are no longer present in the final mapping.
+2. Run `bash .agents/skills/init-labels/scripts/init-labels.sh` to create or update one `in: {key}` label for each mapping key.
+3. After user confirmation, rerun the script with `--cleanup-stale-in` to delete stale `in:` labels that are no longer present in the final mapping.
 
 ### 5. Output and behavior guarantees
 
@@ -82,7 +82,7 @@ The summary must include:
 - Any unmatched platform-default labels still present
 
 Operational notes:
-- The operation is idempotent because the rule-file command updates or overwrites existing labels in place.
+- The operation is idempotent because the provider leaf updates or overwrites existing labels in place.
 - `in:` labels are managed by the AI-guided step together with the `.airc.json` mapping.
 
 ### 6. Inform User
@@ -100,8 +100,7 @@ Next step - initialize milestones (optional):
 
 ## Error Handling
 
-- platform CLI not found: prompt "the platform CLI is not installed"
-- Authentication failed: prompt "the platform CLI is not authenticated"
-- Repository access failed: prompt "Unable to access the current repository with the platform CLI"
+- Provider capability unavailable: report the script's `degraded` or `no-op` result without claiming remote changes.
+- Provider authentication or repository access failure: report the script's non-zero exit status and diagnostic output; do not claim remote changes.
 - Permission error: prompt "No permission to manage labels in this repository"
 - API rate limit: prompt "platform API rate limit reached, please retry later"

package/templates/.agents/skills/init-labels/SKILL.zh-CN.md

@@ -15,7 +15,7 @@ description: >
 
 确认以下条件成立：
 - 执行前先读取 `.agents/rules/label-milestone-setup.md`
-- 按其中的认证命令验证平台访问能力
+- 仓库配置和请求的映射已准备完成
 
 如果任一条件失败，停止并输出对应错误。
 
@@ -28,9 +28,9 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 ```
 
 脚本与 `.agents/rules/label-milestone-setup.md` 共同负责：
-- 在修改前保存当前 label 快照
-- 使用平台对应的 label 创建或更新命令维护标准 label 集合
-- 提示仍然存在的平台预置 labels，例如 `question` 和 `wontfix`
+- 读取配置的 `labels.in` 映射并保留无关 label
+- 选择 provider 叶子，或返回明确的 no-op/degraded 结果
+- 创建或更新标准 label 集合并输出最终摘要
 - 输出最终执行摘要
 
 ### 3. 标准分类体系
@@ -69,8 +69,8 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 #### 4.3 写入配置并创建 label
 
 1. 将最终映射写入 `.agents/.airc.json` 的 `labels.in` 字段。
-2. 为每个映射 key 按 `.agents/rules/label-milestone-setup.md` 的 label 创建命令创建 `in: {key}` label。
-3. 询问用户确认后，清理不在最终映射中的旧 `in:` label。
+2. 执行 `bash .agents/skills/init-labels/scripts/init-labels.sh`，为每个映射 key 创建或更新 `in: {key}` label。
+3. 询问用户确认后，再使用 `--cleanup-stale-in` 重新执行脚本，清理不在最终映射中的旧 `in:` label。
 
 ### 5. 输出与行为保证
 
@@ -82,7 +82,7 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 - 仍然存在的未匹配平台预置 labels
 
 执行说明：
-- 整个操作具备幂等性，因为规则文件中的 label 创建命令按覆盖或更新方式执行。
+- 整个操作具备幂等性，因为 provider 叶子会按覆盖或更新方式处理已有 label。
 - `in:` labels 由 AI 引导步骤和 `.airc.json` 映射统一管理。
 
 ### 6. 告知用户
@@ -100,8 +100,7 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 
 ## 错误处理
 
-- 未找到平台 CLI：提示 "the platform CLI is not installed"
-- 认证失败：提示 "the platform CLI is not authenticated"
-- 仓库访问失败：提示 "Unable to access the current repository with the platform CLI"
+- provider 能力不可用：如实报告脚本的 `degraded` 或 `no-op` 结果，不得声称远端已变更。
+- provider 认证或仓库访问失败：如实报告脚本的非零退出状态和诊断输出；不得声称远端已变更。
 - 权限不足：提示 "No permission to manage labels in this repository"
 - API 限流：提示 "platform API rate limit reached, please retry later"

package/templates/.agents/skills/init-labels/scripts/init-labels.github.sh

@@ -2,6 +2,20 @@
 
 set -e
 
+cleanup_stale_in=false
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --cleanup-stale-in)
+      cleanup_stale_in=true
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
 if ! command -v gh >/dev/null 2>&1; then
   echo "GitHub CLI (\`gh\`) is not installed"
   exit 1
@@ -53,11 +67,46 @@ help wanted	008672	Extra attention is needed
 dependencies	0366d6	Pull requests that update a dependency file
 EOF
 
+node - ".agents/.airc.json" > "$tmpdir/in.tsv" <<'NODE'
+const fs = require("node:fs");
+
+const configPath = process.argv[2];
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+const mapping = config.labels?.in;
+if (mapping === undefined) process.exit(0);
+if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
+  throw new Error("labels.in must be an object");
+}
+
+for (const key of Object.keys(mapping).sort()) {
+  if (!key || key.includes("\n") || key.includes("\r") || key.includes("\t")) {
+    throw new Error("labels.in keys must be non-empty single-line values");
+  }
+  process.stdout.write(`in: ${key}\tBFD4F2\tModule label for ${key}\n`);
+}
+NODE
+
+cut -f1 "$tmpdir/in.tsv" > "$tmpdir/in-names.txt"
+
+cat "$tmpdir/in.tsv" >> "$tmpdir/common.tsv"
+
 while IFS="$(printf '\t')" read -r name color description; do
   [ -n "$name" ] || continue
   gh label create "$name" --color "$color" --description "$description" --force
 done < "$tmpdir/common.tsv"
 
+if [ "$cleanup_stale_in" = true ]; then
+  while IFS= read -r name; do
+    case "$name" in
+      in:*)
+        if ! grep -Fqx "$name" "$tmpdir/in-names.txt"; then
+          gh label delete "$name" --yes
+        fi
+        ;;
+    esac
+  done < "$tmpdir/existing-names.txt"
+fi
+
 gh label list --limit 200 --json name --jq '.[].name' > "$tmpdir/final-names.txt"
 cp "$tmpdir/final-names.txt" "$tmpdir/final.txt"
 
@@ -69,11 +118,13 @@ for label in bug documentation duplicate enhancement invalid question wontfix; d
 done
 
 common_count="$(wc -l < "$tmpdir/common.tsv" | tr -d ' ')"
+dynamic_count="$(wc -l < "$tmpdir/in.tsv" | tr -d ' ')"
 
 echo "GitHub Labels initialized."
 echo
 echo "Summary:"
 echo "- Common labels created or updated: $common_count"
+echo "- in: labels created or updated: $dynamic_count"
 echo "- Exact-match GitHub defaults overwritten: good first issue, help wanted"
 
 if [ -s "$tmpdir/unmatched-defaults.txt" ]; then
@@ -87,4 +138,9 @@ echo
 echo "Notes:"
 echo "- theme: labels were intentionally not created."
 echo "- The operation is idempotent because every label uses gh label create --force."
-echo "- in: labels are managed by the AI-guided step in the SKILL."
+echo "- in: labels are derived from .agents/.airc.json labels.in."
+if [ "$cleanup_stale_in" = true ]; then
+  echo "- Stale in: labels were removed only for labels absent from the confirmed mapping."
+else
+  echo "- Stale in: labels were preserved; pass --cleanup-stale-in after mapping confirmation to remove them."
+fi

package/templates/.agents/skills/init-labels/scripts/init-labels.sh

@@ -2,5 +2,31 @@
 
 set -e
 
-echo "Label initialization skipped: this code platform does not provide a built-in label adapter." >&2
+cleanup_stale_in=false
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --cleanup-stale-in)
+      cleanup_stale_in=true
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+node - "$cleanup_stale_in" <<'NODE'
+const cleanupStaleIn = process.argv[2] === "true";
+process.stdout.write(`${JSON.stringify({
+  status: "degraded",
+  operation: "init-labels",
+  error: {
+    code: "PLATFORM_LABELS_UNSUPPORTED",
+    message: cleanupStaleIn
+      ? "The current platform does not provide a label adapter; stale labels were not removed."
+      : "The current platform does not provide a label adapter."
+  }
+})}\n`);
+NODE
 exit 0

package/templates/.agents/skills/init-milestones/SKILL.en.md

@@ -15,7 +15,7 @@ Initialize the repository's standard milestones taxonomy.
 
 Confirm that:
 - read `.agents/rules/label-milestone-setup.md` first
-- use its authentication commands to verify platform access
+- the requested milestone arguments are ready
 
 If any prerequisite fails, stop and report the matching error.
 
@@ -31,7 +31,7 @@ The script and `.agents/rules/label-milestone-setup.md` are responsible for:
 - Creating and cleaning up a temporary workspace
 - Detecting whether `--history` was requested
 - Scanning all `v*` Git tags, selecting the highest valid version by SemVer precedence, and using compatibility default `0.1.0` when none is valid, without reading ecosystem manifests
-- Listing current milestones with the platform-specific milestone query command
+- Letting the provider leaf list and write current milestones
 - Building the desired milestone set and creating only the missing titles
 - Printing the final execution summary
 
@@ -78,9 +78,7 @@ Next step - initialize labels (optional):
 
 ## Error Handling
 
-- platform CLI not found: prompt "the platform CLI is not installed"
-- Authentication failed: prompt "the platform CLI is not authenticated"
-- Repository access failed: prompt "Unable to access the current repository with the platform CLI"
+- Provider capability, authentication, or repository access failure: report the script's non-zero exit status and diagnostic output; do not claim remote changes.
 - Version detection failed: prompt "Unable to determine current version baseline"
 - No valid SemVer `v*` tags found in `--history` mode: prompt "No valid SemVer history tags found matching v*; only standard milestones will be created"
 - Permission error: prompt "No permission to manage milestones in this repository"

package/templates/.agents/skills/init-milestones/SKILL.zh-CN.md

@@ -15,7 +15,7 @@ description: >
 
 确认以下条件成立：
 - 执行前先读取 `.agents/rules/label-milestone-setup.md`
-- 按其中的认证命令验证平台访问能力
+- 请求的 milestone 参数已准备完成
 
 如果任一条件失败，停止并输出对应错误。
 
@@ -31,7 +31,7 @@ bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
 - 创建并清理临时工作目录
 - 检测是否传入 `--history`
 - 扫描所有 `v*` Git tag，按 SemVer precedence 选择最高合法版本；没有合法版本时使用兼容默认值 `0.1.0`，且不读取任何生态 manifest
-- 使用平台对应的 milestones 查询命令读取当前里程碑
+- 由 provider 叶子读取并写入当前里程碑
 - 构建目标里程碑集合，并且只创建缺失标题
 - 输出最终执行摘要
 
@@ -78,9 +78,7 @@ bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
 
 ## 错误处理
 
-- 未找到平台 CLI：提示 "the platform CLI is not installed"
-- 认证失败：提示 "the platform CLI is not authenticated"
-- 仓库访问失败：提示 "Unable to access the current repository with the platform CLI"
+- provider 能力、认证或仓库访问失败：如实报告脚本的非零退出状态和诊断输出；不得声称远端已变更。
 - 版本解析失败：提示 "Unable to determine current version baseline"
 - `--history` 模式下未找到合法 SemVer `v*` git tags：提示 "No valid SemVer history tags found matching v*; only standard milestones will be created"
 - 权限不足：提示 "No permission to manage milestones in this repository"

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

@@ -9,12 +9,13 @@ description: >
 # Design Technical Plan
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated` and forward it unchanged to the completed event; otherwise bind it to an empty value. Never infer it from `orchestration.json`, environment variables, or prior artifacts.
+If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated` and forward it unchanged to the completed event; otherwise bind it to an empty value. Never infer it from `orchestration.json`, environment variables, or prior artifacts. Lifecycle events also require explicit trigger data: use `{trigger-initiator}=orchestrator` for orchestration and `model` otherwise; `{request-id}` is a stable single-line identifier for this task and artifact round, and `{reason-code}` is `user-request`, `new-requirement`, or `upstream-fact-doubt`. Reuse the same values for started and completed.
 
 ## Boundary / Critical Rules
 
 - This skill only outputs a technical plan document (`plan.md` or `plan-r{N}.md`) and does not modify any business code
 - This is a **mandatory human review checkpoint**; do not automatically proceed to implementation
+- Before generating task or lifecycle Markdown that will be synchronized to an Issue, read `.agents/rules/sync-content-generation.md` and apply its producer-side constraints; the sync path does not parse or rewrite the body
 - When the plan touches compatibility, migration, old formats, or old entry points, read `.agents/rules/compatibility-policy.md` first. Do not design adapters, shims, dual writes, or parallel state machines without passing its admission gate
 - After executing this skill, you **must** immediately update task status in task.md
 
@@ -40,7 +41,7 @@ Before the state check is complete, do not make external-state assertions such a
 
 ## Step Start: Write the started Marker
 
-After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-token}` and verify the returned `artifactContext`.
+After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}` and verify the returned `artifactContext`.
 
 ## Steps
 
@@ -114,7 +115,17 @@ Update `.agents/workspace/active/{task-id}/task.md`:
   - Overwrite the `effort` field in frontmatter with the new value
   - Append a `## Effort Re-estimate` section to this round's plan artifact `{plan-artifact}`, recording: `effort {old} → {new} (rationale: {short basis grounded in this plan})`
   If the re-estimated value matches the current value, skip it: do not write the `## Effort Re-estimate` section. The Flow A sync that follows reads the possibly updated frontmatter and propagates the new value to the Issue automatically.
-After the business fields are updated, run `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --artifact {plan-artifact} {execution-flag}` so the core atomically records the link, stage, agent, metadata, and Activity Log.
+After writing the local artifact, run the pre-completion gate:
+
+```bash
+agent-infra-internal task-artifact {task-id} finalize-local --family plan --artifact {plan-artifact}
+```
+
+- On `status=passed`, save that result's `artifactSha256` and `semanticDigest`; the finalizer has recorded the matching one-shot local provenance intent.
+- On `status=failed` with `repairable=true`, apply only the diagnostic's `replace-line` operation once, then rerun the same command completely; count an attempt only after bytes change, up to 8 attempts.
+- The first repairable failure's `semanticDigest` is retained as the baseline; a retried `status=passed` result must match it. On baseline mismatch, any other failure, no progress, or a repeated diagnostic, stop without publishing a completed event.
+
+Use the digests from that same `status=passed` result in `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {plan-artifact} --artifact-sha256 {artifact-sha256} --semantic-digest {semantic-digest} {execution-flag}` so the core records the link, stage, agent, metadata, and Activity Log atomically.
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Task (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
   ```
 

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

@@ -9,11 +9,12 @@ description: >
 # 设计技术方案
 > `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。
+若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。生命周期事件还必须携带显式触发信息：编排调用使用 `{trigger-initiator}=orchestrator`，否则使用 `model`；`{request-id}` 是本任务与本轮产物的稳定单行标识，`{reason-code}` 使用 `user-request`、`new-requirement` 或 `upstream-fact-doubt`；started 与 completed 使用同一组值。
 
 ## 行为边界 / 关键规则
 
 - 本技能仅产出技术方案文档（`plan.md` 或 `plan-r{N}.md`）—— 不修改任何业务代码
+- 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 这是一个**强制性的人工审查检查点** —— 不要自动进入实现阶段
 - 方案涉及兼容、迁移、旧格式或旧入口时，先读取 `.agents/rules/compatibility-policy.md`；未通过准入门槛时不得设计 adapter、shim、双写或并行状态机
 - 执行本技能后，你**必须**立即更新 task.md 中的任务状态
@@ -43,7 +44,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 确认前置条件和轮次后、本轮第一个产出动作之前执行：
 
 ```bash
-agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-token}
+agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}
 ```
 
 ## 执行步骤
@@ -113,7 +114,14 @@ agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-t
   - 用新值覆盖 frontmatter 的 `effort` 字段
   - 在本轮方案产物 `{plan-artifact}` 中追加 `## 工作量重估` 段，记录一条：`effort {old} → {new} (rationale: {基于本轮方案的简短依据})`
   若重估值与当前值一致，跳过：不写入 `## 工作量重估` 段。后续 Flow A 同步会读取可能更新过的 frontmatter，并自动把新值同步到 Issue。
-- 完成业务内容更新后执行 `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --artifact {plan-artifact} {execution-flag}`，由核心原子登记链接、阶段、代理、时间、版本和 Activity Log。
+- 完成本地产物后，先执行本地完成前门禁：
+  ```bash
+  agent-infra-internal task-artifact {task-id} finalize-local --family plan --artifact {plan-artifact}
+  ```
+  - `status=passed`：保存本次返回的 `artifactSha256` 和 `semanticDigest`；finalizer 已记录对应的一次性本地 provenance intent。
+  - `status=failed` 且 `repairable=true`：仅按诊断中的 `replace-line` 操作做一次最小修改，然后完整重跑同一命令；实际字节发生变化才计一次 `repairAttempts`，最多 8 次。
+  - 首次可修复失败的 `semanticDigest` 由 finalizer 保留为基线；重试后的 `status=passed` 必须匹配该基线。基线不匹配、其他失败、无进展或重复诊断：停止，不发布 completed 事件。
+- 使用同一次 `status=passed` 返回的摘要执行 `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {plan-artifact} --artifact-sha256 {artifact-sha256} --semantic-digest {semantic-digest} {execution-flag}`，由核心登记链接、阶段、代理、时间、版本和 Activity Log。
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status pending-design-work --fields`

package/templates/.agents/skills/review-analysis/SKILL.en.md

@@ -9,13 +9,14 @@ description: >
 # Requirement Analysis Review
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated` and forward it unchanged to both the summary finalizer and completed event; otherwise bind it to an empty value. Never infer it from `orchestration.json`, environment variables, or prior artifacts.
+If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--orchestrated` and forward it unchanged to both the summary finalizer and completed event; otherwise bind it to an empty value. Never infer it from `orchestration.json`, environment variables, or prior artifacts. Lifecycle events also require explicit trigger data: use `{trigger-initiator}=orchestrator` for orchestration and `model` otherwise; `{request-id}` is a stable single-line identifier for this task and artifact round, and `{reason-code}` is `user-request` or `review-finding`. Reuse the same values for started and completed.
 
 Review the latest analysis artifact and produce `review-analysis.md` or `review-analysis-r{N}.md`.
 
 ## Boundary / Critical Rules
 
 - This skill only reviews analysis artifacts and writes a report; it does not modify product code.
+- Before generating task or lifecycle Markdown that will be synchronized to an Issue, read `.agents/rules/sync-content-generation.md` and apply its producer-side constraints; the sync path does not parse or rewrite the body
 - After executing this skill, you **must** immediately update task.md.
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
@@ -38,7 +39,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## Step Start: Declare the started Event
 
-After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} review-analysis.started --agent {standard-agent-token}`.
+After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} review-analysis.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}`.
 
 ## Steps
 
@@ -69,7 +70,7 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}` exactly once.
+After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, make the initial call to `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`; after a failure, follow `.agents/rules/local-artifact-repair.md` to decide whether to edit and rerun, and never treat an error type or `changed=false` as automatic authorization.
 
 Bind and reuse this structured mapping from that one response:
 
@@ -79,13 +80,13 @@ Bind and reuse this structured mapping from that one response:
 {unresolved-minor} = stageStatus.unresolvedFindingCounts.minor
 ```
 
-The intent atomically finalizes the report summary and returns the same ledger snapshot. Do not call `stage-status`, replace placeholders manually, or rescan the finding list. If finalization fails or a response field is missing, stop before the completion event. Derive the verdict and next-step branch from the same response's `stageStatus.canAdvance`: only `canAdvance=true` permits `approved`; otherwise use `changes-requested` or `rejected`. Then run `agent-infra-internal task-event {task-id} review-analysis.completed --agent {standard-agent-token} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n} {execution-flag}`.
+The intent atomically finalizes the report summary and returns the same ledger snapshot. Do not call `stage-status`, replace placeholders manually, or rescan the finding list. After a failure, the model may edit the same controlled artifact and rerun the same intent only when the shared rule's mechanical gates pass; reassess convergence after every failure. The final complete result determines the verdict and counts from that same snapshot: `stageStatus.canAdvance=true` with an Approved conclusion permits cross-stage advancement; `stageStatus.canAdvance=false` still requires `agent-infra-internal task-event {task-id} review-analysis.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n} {execution-flag}`, using `changes-requested` and routing to same-stage revision/review (use `rejected` when the report explicitly rejects). On failure, model stop, lack of progress, or the emergency cap, do not publish a completion event or cross-stage command; use the `repair-stop` scenario in `reference/output-templates.md` to show existing summary/findings, the artifact, actual repair attempts, the last diagnostic, and the stop reason.
 
 `manual-validation` is the data source for the `Manual-validation` count folded into review rows in `ai task log`; do not add a parallel manual-verification field.
 
 If task.md has a valid `issue_number`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {standard-agent-token}`.
 
-Before writing the summary, the finalization intent checks decision-detail ids; it auto-removes a duplicate only when exactly one formal `[needs-human-decision]` block remains and every other same-id block is clearly short and informal, then reruns the read-only check. Ambiguous duplicates fail closed. If this check or repair fails, stop before the completion event.
+Before writing the summary, the finalization intent checks decision-detail ids; any visible duplicate returns a structured failure and preserves the artifact bytes, while the model decides whether a minimal edit is safe under the shared rule. If the safety gates fail, diagnostics repeat, no byte-level progress occurs, or the emergency cap is reached, stop before the completion event; the stop path must still show the existing review result instead of hiding the artifact.
 
 ### 7. Run Completion Gate
 

package/templates/.agents/skills/review-analysis/SKILL.zh-CN.md

@@ -9,13 +9,14 @@ description: >
 # 需求分析审查
 > `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 summary finalizer 与 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。
+若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 summary finalizer 与 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。生命周期事件还必须携带显式触发信息：编排调用使用 `{trigger-initiator}=orchestrator`，否则使用 `model`；`{request-id}` 是本任务与本轮产物的稳定单行标识，`{reason-code}` 使用 `user-request` 或 `review-finding`；started 与 completed 使用同一组值。
 
 审查最新需求分析产物，并产出 `review-analysis.md` 或 `review-analysis-r{N}.md`。
 
 ## 行为边界 / 关键规则
 
 - 本技能只审查分析产物并写报告，不修改业务代码
+- 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 执行本技能后，你**必须**立即更新 task.md
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
@@ -40,7 +41,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## 步骤开始：声明 started 事件
 
-确认前置条件和产物上下文后、本轮第一个产出动作之前执行 `agent-infra-internal task-event {task-id} review-analysis.started --agent {standard-agent-token}`。
+确认前置条件和产物上下文后、本轮第一个产出动作之前执行 `agent-infra-internal task-event {task-id} review-analysis.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}`。
 
 ## 执行步骤
 ### 1. 验证前置条件
@@ -72,7 +73,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ### 6. 更新任务状态
 
-报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后只调用一次 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`。
+报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后首次调用 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`；失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`，不能把失败类型或 `changed=false` 当作自动授权。
 
 从该次返回值绑定并复用以下结构化映射：
 
@@ -82,13 +83,13 @@ agent-infra-internal task-snapshot {task-id} --format text
 {unresolved-minor} = stageStatus.unresolvedFindingCounts.minor
 ```
 
-该 intent 原子最终化报告摘要并返回同一次账本快照；不得再调用 `stage-status`、手工替换占位符或扫描问题清单。最终化失败或返回字段缺失时，停止在完成事件之前。以同一次返回的 `stageStatus.canAdvance` 决定 verdict 和下一步：仅 `canAdvance=true` 可用 `approved`，否则必须用 `changes-requested` 或 `rejected`。随后执行 `agent-infra-internal task-event {task-id} review-analysis.completed --agent {standard-agent-token} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n} {execution-flag}`。
+该 intent 原子最终化报告摘要并返回同一次账本快照；不得再调用 `stage-status`、手工替换占位符或扫描问题清单。失败后，模型只能在共享规则的机械安全门通过时修改同一个受控 artifact，并完整重跑相同 intent；每次失败都重新判断是否收敛。最终一次完整成功返回决定同一快照的 verdict 和计数：`stageStatus.canAdvance=true` 且结论为 Approved 时允许跨阶段推进；`stageStatus.canAdvance=false` 时仍须执行 `agent-infra-internal task-event {task-id} review-analysis.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n} {execution-flag}`，使用 `changes-requested` 并路由到同阶段修订/复审（报告明确拒绝时使用 `rejected`）。失败、模型停止、无进展或紧急熔断时，不发布完成事件或跨阶段命令，但必须按 `reference/output-templates.md` 的 `repair-stop` 场景展示已有 summary/findings、artifact、实际修复次数、最后诊断和停止原因。
 
 `manual-validation` 是 `ai task log` 中 review 行「人工校验点」（EN `Manual-validation`）计数的数据源；不要新增并行人工验证字段。
 
 如果 task.md 中存在有效的 `issue_number`，调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`，再调用 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {standard-agent-token}`；失败按 `.agents/rules/issue-sync.md` 记录 warning。
 
-最终化 intent 会在写入摘要前检查详情块 ID；只有“一个正式 `[needs-human-decision]` 块 + 明确的简短非正式重复块”才会自动删除重复块并重新做只读检查，无法唯一判断时失败关闭。该检查或自动修复失败时，停止在完成事件之前。
+最终化 intent 会在写入摘要前检查详情块 ID；任何可见重复都返回结构化失败并保持 artifact 字节不变，由模型按共享规则判断是否进行最小编辑。无法通过安全门、诊断重复、没有实际字节变化或达到紧急熔断时，停止在完成事件之前；停止路径仍必须展示已有审查结果，不得吞掉 artifact 内容。
 
 ### 7. 完成校验
 

package/templates/.agents/skills/review-analysis/reference/output-templates.en.md

@@ -18,6 +18,24 @@ Rules:
 - The selected scenario must generate `{next-step-commands}` through the shared helper
 - The count line shows 4 numbers. `Human-decision` (`{h}`) counts this stage's `needs-human-decision` rows; because those rows are unresolved, `{h} > 0` means `canAdvance=false`. Expand the "Pending human-decision pre-block" from `.agents/rules/next-step-output.md` and show revision and re-review paths only.
 
+### Scenario R: Finalization stopped with results visible
+
+When the finalizer fails, or the model stops because of a safety gate, lack of progress, repeated diagnostics, or the emergency cap, use this scenario. Do not call the shared helper or output cross-stage commands.
+
+```text
+Task {task-id} review results were generated, but lifecycle advancement stopped.
+- Review artifact: .agents/workspace/active/{task-id}/{review-artifact}
+- Last valid summary/findings: {last-readable-review-result}
+- Local repair attempts: {repairAttempts}
+- Last diagnostic: {last-structured-diagnostic}
+- Stop reason: {stop-reason}
+- Completion event: not published | Cross-stage commands: not generated
+
+Note: only lifecycle advancement stopped; the existing review result remains available. Handle it manually or rerun the current review skill.
+```
+
+If the summary cannot be parsed safely, set `{last-readable-review-result}` to "summary could not be parsed safely" and retain the artifact path and raw structured diagnostic; do not infer counts or add a conclusion.
+
 ### Scenario A: Approved with no findings
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.

package/templates/.agents/skills/review-analysis/reference/output-templates.zh-CN.md

@@ -18,6 +18,24 @@
 - 所选场景必须通过统一 helper 生成 `{next-step-commands}`
 - 计数行固定显示 4 个数字。`人工裁决`（`{h}`）是本阶段 `needs-human-decision` 行数；它属于未闭环账本状态，因此 `{h} > 0` 时 `canAdvance=false`，必须按 `.agents/rules/next-step-output.md` 的「人工裁决待办前置块」展开详情，并只输出修订与复审路径。
 
+### 场景 R：最终化停止但结果可见
+
+当 finalizer 失败，或模型因安全门、无进展、重复诊断或紧急熔断停止时，使用本场景，不调用统一 helper，也不输出跨阶段命令。
+
+```text
+任务 {task-id} 审查结果已生成，但生命周期未推进。
+- 审查产物：.agents/workspace/active/{task-id}/{review-artifact}
+- 最后有效 summary/findings：{last-readable-review-result}
+- 本地修复次数：{repairAttempts}
+- 最后诊断：{last-structured-diagnostic}
+- 停止原因：{stop-reason}
+- 完成事件：未发布 | 跨阶段命令：未生成
+
+说明：本次仅停止生命周期推进，已有审查结果仍可查看。请先进行人工处理，或重新运行当前审查技能。
+```
+
+如果 summary 无法安全解析，`{last-readable-review-result}` 必须改为“摘要不可安全解析”，并保留 artifact 路径和原始结构化诊断；不得推算计数或补写结论。
+
 ### 场景 A：通过且无问题
 
 使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。