@fitlab-ai/agent-infra 0.9.11 → 0.9.12

package/templates/.agents/rules/local-artifact-repair.zh-CN.md

@@ -0,0 +1,46 @@
+# 通用规则 - 模型驱动的本地产物修复
+
+本规则只适用于 `review-analysis`、`review-plan`、`review-code` 在 finalizer 失败后处理**同一个受控 review artifact** 的场景。它不适用于 task.md、账本、receipt、源码、Git、平台资源或生命周期状态。
+
+## 授权边界
+
+- finalizer 只负责读取事实、校验状态、规范化成功结果和原子写入；它不维护可修复错误码白名单，不推断 repairability，也不自动选择要删除的报告内容。
+- 首次 finalizer 调用不计入修复次数。只有在机械安全门通过后，模型明确判断当前问题能通过最小、可解释的 artifact 修改解决时，才允许编辑。
+- 模型只能修改当前 review skill 声明的一个普通 review artifact，且该文件必须位于当前 task 目录。不得修改 task.md、审查分歧账本、receipt、源码、其他报告或远端资源。
+- `changed=false`、错误码或某个格式形状只是诊断事实，不是自动批准。模型必须结合完整诊断、artifact 内容和上下文逐例判断。
+
+## 不可绕过的机械安全门
+
+在每次模型编辑前确认：
+
+1. finalizer 返回失败，且没有已提交的 artifact operation；
+2. 任务、stage、artifact、review round、身份和 provenance 仍然一致；
+3. 目标是当前 task 目录内的普通文件，没有并发冲突、权限错误、I/O 不确定性或目标被替换；
+4. 不改变人工裁决语义、裁决详情或账本身份，也不涉及任务状态、receipt、Git、平台或其他外部副作用；已知且可核验的 pending 人工裁决可以保留，但模型必须证明本次修改与该裁决无关。
+
+任一条件不满足，立即停止，不调用模型编辑。安全门不能被模型的语义判断绕过。
+
+## 动态收敛循环
+
+1. 使用固定的 task、stage、artifact 和 orchestrated intent 执行首次 finalizer。
+2. 成功时使用这一次完整结果进入既有完成前门禁；不得重新扫描账本或手工补写摘要。
+3. 失败且安全门通过时，模型读取结构化诊断、当前 artifact 和必要上下文，决定继续修复或停止，并说明修改范围和理由。
+4. 模型选择继续时，只做一次最小 artifact 编辑。只有文件字节实际发生变化，才增加一次 `repairAttempts`，然后完整重跑同一个 finalizer intent。
+5. 每次重跑都重新执行全部安全校验。修复后出现新的、独立且仍局限于该 artifact 的问题，可以再次交给模型判断；不能沿用上一次“可修复”的结论。
+6. 模型无法证明下一步安全，或判断问题属于环境、权限、并发、身份、provenance、状态未知、人工裁决语义/详情不确定或其他非本地问题时，立即停止。已知人工裁决本身不是停止条件。
+7. 诊断重复、artifact 指纹重复、没有实际字节进展或模型没有提出可验证的最小修改时，立即停止。
+8. 每次 skill invocation 最多允许 8 次实际 artifact 修改作为紧急熔断。该上限只防止死循环和资源失控，不是正常业务停止条件，也不表示最多只能修复 8 个问题。达到上限时保留最后结构化诊断并停止。
+
+修复次数只存在于当前 skill invocation 的内存上下文，不写入 task.md、ledger 或公共 receipt。不得按错误码、技能或问题类型设置不同的正常预算。
+
+## 完成事件与用户输出
+
+- 最终一次完整 finalizer 成功后，必须使用同一次返回的 provenance、账本状态、verdict 和计数发布 review completed 事件；`stageStatus.canAdvance=true` 且结论为 Approved 时才可生成跨阶段 next-step 命令，`canAdvance=false` 时仍须登记结果并路由到同阶段修订/复审。
+- 失败、模型停止、无进展、诊断重复或紧急熔断时，不发布 completed 事件，不推进生命周期，不生成跨阶段命令，也不伪造通过结论。
+- 停止推进不等于丢弃审查结果。用户输出必须展示 artifact 路径、已安全读取的最后有效 summary/findings、实际 `repairAttempts`、最后结构化诊断和停止原因。
+- summary 无法安全解析时，只展示 artifact 路径和原始结构化诊断，不推算计数、不补写结论，并明确生命周期推进已停止但产物仍可查看。
+- 停止路径只提示重新运行当前 review skill 或进行人工处理；不能调用 `code-task`、`complete-task` 等跨阶段 helper。
+
+## 生命周期隔离
+
+`complete-task`、告警关闭、恢复任务和其他 task-lifecycle/task-finalization 入口涉及任务状态、receipt、远端结果或归档副作用，不消费本规则。它们继续使用各自的硬失败、同一 intent 重试和状态未知语义。

package/templates/.agents/rules/milestone-inference.en.md

@@ -1,5 +1,15 @@
 # Milestone Inference
 
-This code platform does not provide milestone inference; `platform-issue sync --milestone ...` returns a structured no-op/degraded result.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-Milestone narrowing and reuse are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Do not block task progress when no platform-specific milestone implementation is available.
+Milestones narrow through declarative Issue intents:
+
+```bash
+# create/import phase
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
+
+# code phase
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
+```
+
+`initial` prefers a valid task milestone, otherwise the lowest open `X.Y.x`, then `General Backlog`. `specific` narrows a release line to the highest open patch version using main/release-line ancestry. Missing facts or triage permission preserve the remote value and return skipped/degraded. `create-pr` reuses the Issue milestone in the 09/10 PR adapter.

package/templates/.agents/rules/milestone-inference.zh-CN.md

@@ -1,5 +1,27 @@
-# Milestone 推断
+# Milestone 推断规则
 
-当前代码平台未提供里程碑推断；`platform-issue sync --milestone ...` 返回结构化 no-op/degraded 结果。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-自定义平台会跳过里程碑收窄和复用逻辑，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。没有平台专属里程碑实现时，不要阻塞任务推进。
+Milestone 继续按生命周期逐步收窄，但候选读取、分支判断、权限降级和写入统一由 `platform-issue` 处理。
+
+## 阶段 1：创建或导入
+
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
+```
+
+优先使用 task.md 中存在且有效的显式 milestone；否则从 open milestones 选择最低 `X.Y.x` 版本线，最后回退 `General Backlog`。`triage=false` 或外部事实不足时保持远端值并返回 skipped/degraded。
+
+## 阶段 2：`code-task`
+
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
+```
+
+版本线收窄规则保持不变：主干模式在当前版本线取最高 patch；多版本分支模式依据 release-line/main 祖先关系选择版本线。无法可靠判断时保持原值。完成门禁仍拒绝 `X.Y.x`。
+
+## 阶段 3：`create-pr`
+
+PR 只复用关联 Issue 的具体 milestone；该 PR 资源写入属于 09/10，不在 `platform-issue` 中实现。
+
+调用方不得重新实现 milestone 列表、排序、分支祖先或平台写入逻辑。

package/templates/.agents/rules/pr-sync.en.md

@@ -2,30 +2,39 @@
 
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, the marker, current HEAD, paginated comment lookup, and create/update/no-op reconciliation.
+The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
 
-## Inputs
+## Three-Layer Isolation
 
-```bash
-agent-infra-internal platform-pr summary-context {task-id}
-```
-
-Use only the returned latest canonical `plan*`, `review-plan*`, `code*`, `review-code*`, and `manual-validation*` for lifecycle claims. The summary covers scope, tests, review history, and exactly one manual-validation state. It also includes a `### PR Code Changes` section based on authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, with reconciled runtime, test, skill/rule, template, documentation, and other categories plus rename, mechanical-mirror, and unnecessary-change analysis.
-
-## Publish
+- `sync-pr:{task-id}:summary` (`platform-pr summary-sync`) is an updatable reviewer summary; it is neither a process copy nor a formal Review.
+- The full `pr-review*` process copy lives in the Issue artifact comment (`platform-comment sync --kind artifact`) and is restored by `restore-task` under its Issue-only contract.
+- A formal PR Review (`platform-pr-review publish`) is the only formal conclusion carrier published to the PR, bound to the reviewed head SHA, and includes conclusion, findings, receipt, and the Issue artifact link.
 
-Write only the summary body to a file, without marker or SHA:
+The three never cross: a regular PR comment does not carry the full process copy; an Issue artifact comment is not treated as a formal Review; a summary is not presented as a formal Review.
 
 ```bash
+agent-infra-internal platform-pr summary-context {task-id}
+
 agent-infra-internal platform-pr summary-sync {task-id} \
   --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
-The core wraps `<!-- sync-pr:{task-id}:summary -->` and current `<!-- last-commit: ... -->`, then creates, updates in place, or returns no-op. Duplicate markers fail deterministically. Callers never assemble shell/heredoc comment commands.
+Use only canonical inputs returned by the context command. Write the plain body without marker or SHA. The core owns `<!-- sync-pr:{task-id}:summary -->`, current `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Summary failure never rolls back a PR or commit.
 
-`create-pr` does not roll back the PR on summary failure; `commit` records a warning without rolling back; manual validation refreshes after its canonical artifact is written.
+The canonical comment envelope produced by the core is:
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## Review Summary
+{manual-validation-section}
+### Key Technical Decisions
+### Review History
+### Test Results
+### PR Code Changes
+```
 
-For a linked task, the caller records a structured warning:
+Canonical inputs include `manual-validation.md`. The manual-validation section is one of `### ✅ Manual Validation Passed`, `### ⚠️ Manual Verification Required`, or `### ✅ No Manual Verification Needed`; `complete-manual-validation` refreshes the same summary in place. The PR code-change section uses authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, reconciles runtime, test, skill/rule, template, documentation, and other categories, and explains renames, mechanical mirrors, and potentially unnecessary changes.
 
 ```bash
 agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -4,13 +4,21 @@
 
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
+## 三层隔离
+
+- `sync-pr:{task-id}:summary`（`platform-pr summary-sync`）是可更新的 reviewer 摘要，不是过程原文，也不是正式 Review。
+- `pr-review*` 完整过程原文在 Issue artifact 评论（`platform-comment sync --kind artifact`），由 `restore-task` 按 Issue-only 契约恢复。
+- 正式 PR Review（`platform-pr-review publish`）是唯一发布到 PR 的正式结论载体，绑定被审 head SHA，含结论、finding、receipt 与 Issue artifact 链接。
+
+三者不串用：PR 普通评论不承载完整过程原文；Issue artifact 评论不当作正式 Review；摘要不冒充正式 Review。
+
 ## 聚合输入
 
 ```bash
 agent-infra-internal platform-pr summary-context {task-id}
 ```
 
-只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`。模型据此生成 reviewer 摘要正文，至少包含：
+只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`（包括 `manual-validation.md`）。模型据此生成 reviewer 摘要正文，至少包含：
 
 - 变更摘要与实现范围
 - 测试结果
@@ -20,6 +28,19 @@ agent-infra-internal platform-pr summary-context {task-id}
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
+core 最终包装出的 canonical 评论结构为：
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## 审查摘要
+{manual-validation-section}
+### 关键技术决策
+### 审查历程
+### 测试结果
+### PR 代码增减
+```
+
 ## 发布
 
 把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：

package/templates/.agents/rules/release-commands.en.md

@@ -1,5 +1,44 @@
-# Release Commands
+# Release Platform Commands
 
-This code platform does not provide a release-note adapter.
+Release-note platform operations use a typed internal intent. Callers consume structured JSON and do not interpret platform commands, raw fields, identity email rules, or authentication errors.
 
-Local `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` still normalizes an external file and returns its digest. Use `context` to receive a structured `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op and do not probe another platform client. Publish with `--expected-sha256` remains a no-op until an adapter is provided.
+## Collect Release-note Context
+
+```bash
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
+```
+
+The result contains `history`, `pullRequests`, `closingIssues`, and commit `authors` with normalized `login` / `resolution` values. `status: no-op` with error code `PLATFORM_RELEASE_NOTES_UNSUPPORTED` means the current platform does not support remote release-note operations.
+
+### Identity Safety Boundary
+
+- Render an identity as `@login` only when `resolution` is `platform-user` or `platform-noreply` and `login` is non-empty.
+- Exclude `resolution: unresolved` identities from the release-note contributor list. Never infer a login from a name, email address, domain, brand, or same-named platform account, and never substitute a guessed personal or organization account.
+- Do not publish unresolved identity emails or identity-verification TODOs in Release notes. Record any required investigation outside the release workflow without creating a platform mention.
+
+## Stage Release Notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+The command accepts only an external regular file, normalizes it atomically, and returns SHA-256 for its exact bytes.
+
+## Publish Release Notes
+
+Call this only after user confirmation:
+
+```bash
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
+```
+
+The command recomputes the digest before platform access and performs no platform write on mismatch. On a match it updates an existing Release or creates it when missing; `--dry-run` returns only the planned operation. Exit code `0` means success, `1` means a stable failure, and `2` means a network or platform block.

package/templates/.agents/rules/release-commands.zh-CN.md

@@ -1,5 +1,44 @@
-# Release 命令
+# Release 平台命令
 
-当前代码平台未提供发布说明 adapter。
+发布说明平台操作统一使用 typed internal intent。调用方只解释结构化 JSON，不解析平台命令、原始字段、身份邮箱规则或认证错误。
 
-本地 `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` 仍可规范化工作树外文件并返回摘要。调用 `context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client；提供 adapter 前，带 `--expected-sha256` 的 publish 同样保持 no-op。
+## 收集发布说明上下文
+
+```bash
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
+```
+
+结果包含 `history`、`pullRequests`、`closingIssues` 和带规范化 `login` / `resolution` 的 commit `authors`。`status: no-op` 且错误码为 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` 表示当前平台不支持远端发布说明能力。
+
+### 身份安全边界
+
+- 只有 `resolution` 为 `platform-user` 或 `platform-noreply` 且 `login` 非空的身份可以渲染为 `@login`。
+- `resolution: unresolved` 的身份不得进入发布说明的贡献者列表；不得从 Name、邮箱、域名、品牌或同名平台账号推断 login，也不得替换成推测的个人或组织账号。
+- 不得把未解析身份的邮箱或身份确认 TODO 写入可发布的 Release notes。需要调查时仅在发布流程外记录，不得产生平台 mention。
+
+## Stage Release notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+命令只接受工作树外普通文件，原子规范化并返回精确 bytes 的 SHA-256。
+
+## 发布 Release notes
+
+用户确认后调用：
+
+```bash
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
+```
+
+命令在平台访问前复算摘要，不匹配时零写入；匹配时更新已有 Release，缺失时创建。`--dry-run` 只返回 planned operation。退出码为 `0` 时成功，`1` 表示稳定失败，`2` 表示网络或平台阻塞。

package/templates/.agents/rules/security-alerts.en.md

@@ -1,5 +1,20 @@
 # Security Alerts
 
-This code platform does not provide built-in security alert integration.
+Read this rule before importing or dismissing dependency or code-scanning alerts.
 
-Code scanning and dependency alert import or close actions are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Track security work through local task artifacts or a platform-specific integration.
+## Shared entry point
+
+All callers use the shared security script and parse its single JSON result:
+
+```text
+bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
+bash .agents/scripts/security-alerts.sh read-codescan --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+```
+
+The result contains `status`, `operation`, and either `data` or `error.code` plus `error.message`. The status is one of `applied`, `no-op`, `degraded`, or `failed`. Diagnostics belong on stderr; stdout must contain exactly one JSON object.
+
+Read the current alert before any dismiss operation. A dismiss reason must use the provider API reason value, and the generated task or Issue comment must be passed through `--comment-file`.
+
+Do not invoke a provider CLI directly from a SKILL. A degraded or failed result must be reported accurately, and cancelled or failed operations must not be recorded as successful.

package/templates/.agents/rules/security-alerts.zh-CN.md

@@ -1,5 +1,20 @@
 # 安全告警
 
-当前代码平台未内置安全告警集成。
+在导入或关闭依赖告警、代码扫描告警前，先阅读本规则。
 
-自定义平台会跳过代码扫描和依赖告警的导入或关闭操作，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请通过本地任务产物或平台专属集成跟踪安全工作。
+## 共享入口
+
+所有调用方都使用共享安全脚本，并解析其单个 JSON 结果：
+
+```text
+bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
+bash .agents/scripts/security-alerts.sh read-codescan --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+```
+
+结果包含 `status`、`operation`，以及 `data` 或 `error.code` 与 `error.message`。`status` 只能是 `applied`、`no-op`、`degraded` 或 `failed`。诊断信息写入 stderr；stdout 必须只包含一个 JSON 对象。
+
+任何关闭操作前都必须先读取当前告警。关闭原因必须使用 provider API 的 reason 值，生成的任务或 Issue 评论必须通过 `--comment-file` 传入。
+
+SKILL 不得直接调用 provider CLI。degraded 或 failed 结果必须如实报告，取消或失败的操作不得记录为成功。

package/templates/.agents/rules/sync-content-generation.en.md

@@ -0,0 +1,8 @@
+# Synchronized Content Generation Rules
+
+This rule applies to controlled generators that write `task.md` or lifecycle artifacts which are synchronized to an Issue. It constrains model output only; it does not parse, rewrite, or block hand-written or external content.
+
+- Render local, workspace, and temporary task-file references as inline code, such as `analysis.md` or `/workspace/file.md`; do not write them as Markdown links.
+- Render non-user-semantic `@` text, such as `@2x`, as inline code; preserve real user mentions, `@` inside email addresses, and fixed release-log formats according to their meaning.
+- Formal Issue, PR, commit, and external links may remain Markdown links.
+- When uncertain, keep ordinary text and do not guess a link target; do not introduce a runtime Markdown parser for this purpose.

package/templates/.agents/rules/sync-content-generation.zh-CN.md

@@ -0,0 +1,8 @@
+# 同步内容生成规则
+
+本规则适用于会写入 `task.md` 或生命周期产物并同步到 Issue 的受控生成端。它只约束模型生成，不解析、改写或阻断手写和外部正文。
+
+- 本地、工作区和临时任务文件引用使用行内代码文本，例如 `analysis.md`、`/workspace/file.md`；不要把它们写成 Markdown 链接。
+- 非用户语义的 `@` 文本（例如 `@2x`）使用行内代码文本；真实用户 mention、邮箱地址中的 `@` 和固定发布格式按语义保留。
+- 正式的 Issue、PR、commit 和外部链接可以保持 Markdown 链接。
+- 不确定时保留普通文本，不猜测链接目标；不要为此引入运行时 Markdown 解析器。

package/templates/.agents/rules/task-management.en.md

@@ -49,7 +49,7 @@ The seven internal commands (`task-event` / `task-lifecycle` / `task-finalizatio
 - `review-plan`: update `current_step`, `updated_at`, `agent_infra_version`
 - `code-task`: update `current_step`, `updated_at`, `agent_infra_version`
 - `review-code`: update `current_step`, `updated_at`, `agent_infra_version`
-- `create-pr`: update `pr_number`, `updated_at`, `agent_infra_version`
+- `create-pr`: update the verified `pr_delivery_fact`, `updated_at`, `agent_infra_version`
 - `commit`: update `updated_at`, `agent_infra_version`; update `current_step` when needed (see `commit/reference/task-status-update.md`)
 - `complete-task`: update `status`, `current_step`, `completed_at`, `updated_at`, `agent_infra_version`
 - `block-task`: update `status`, `blocked_at`, `updated_at`, `agent_infra_version`

package/templates/.agents/rules/task-management.zh-CN.md

@@ -49,7 +49,7 @@
 - `review-plan`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `code-task`：更新 `current_step`、`updated_at`、`agent_infra_version`
 - `review-code`：更新 `current_step`、`updated_at`、`agent_infra_version`
-- `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
+- `create-pr`：通过 `pr_delivery_fact` writer 更新 PR 绑定事实、`updated_at`、`agent_infra_version`
 - `commit`：更新 `updated_at`、`agent_infra_version`；必要时更新 `current_step`（详见 `commit/reference/task-status-update.md`）
 - `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`
 - `block-task`：更新 `status`、`blocked_at`、`updated_at`、`agent_infra_version`

package/templates/.agents/scripts/security-alerts.github.sh

@@ -0,0 +1,151 @@
+#!/bin/sh
+
+set -e
+
+operation="${1:-}"
+shift || true
+number=""
+reason=""
+comment_file=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --number)
+      number="${2:-}"
+      shift
+      ;;
+    --reason)
+      reason="${2:-}"
+      shift
+      ;;
+    --comment-file)
+      comment_file="${2:-}"
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+emit_error() {
+  code="$1"
+  message="$2"
+  node - "$operation" "$code" "$message" <<'NODE'
+const [operation, code, message] = process.argv.slice(2);
+process.stdout.write(`${JSON.stringify({ status: "failed", operation, error: { code, message } })}\n`);
+NODE
+}
+
+case "$operation" in
+  read-dependabot|dismiss-dependabot|read-codescan|dismiss-codescan) ;;
+  *)
+    emit_error "SECURITY_OPERATION_INVALID" "Unknown security alert operation."
+    exit 1
+    ;;
+esac
+
+case "$number" in
+  ''|*[!0-9]*)
+    emit_error "SECURITY_NUMBER_INVALID" "Alert number must be a positive integer."
+    exit 1
+    ;;
+esac
+
+if ! command -v gh >/dev/null 2>&1; then
+  emit_error "PLATFORM_CLI_MISSING" "The platform CLI is not installed."
+  exit 1
+fi
+if ! gh auth token >/dev/null 2>&1; then
+  emit_error "PLATFORM_NOT_AUTHENTICATED" "The platform CLI is not authenticated."
+  exit 1
+fi
+repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')" || {
+  emit_error "PLATFORM_REPOSITORY_UNAVAILABLE" "Unable to access the current repository."
+  exit 1
+}
+
+case "$operation" in
+  *dependabot*) endpoint="repos/$repo/dependabot/alerts/$number" ;;
+  *codescan*) endpoint="repos/$repo/code-scanning/alerts/$number" ;;
+esac
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT HUP INT TERM
+
+if [ "$operation" = "read-dependabot" ] || [ "$operation" = "read-codescan" ]; then
+  if ! gh api "$endpoint" > "$tmpdir/response.json" 2> "$tmpdir/error.txt"; then
+    emit_error "SECURITY_API_FAILED" "Unable to read the security alert."
+    exit 2
+  fi
+else
+  if [ -z "$reason" ] || [ -z "$comment_file" ] || [ ! -f "$comment_file" ]; then
+    emit_error "SECURITY_DISMISS_INPUT_INVALID" "Dismissal reason and comment file are required."
+    exit 1
+  fi
+  if ! gh api "$endpoint" > "$tmpdir/current.json" 2> "$tmpdir/error.txt"; then
+    emit_error "SECURITY_API_FAILED" "Unable to read the security alert before dismissal."
+    exit 2
+  fi
+  state="$(node - "$tmpdir/current.json" <<'NODE'
+const fs = require("node:fs");
+try {
+  const alert = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+  process.stdout.write(typeof alert.state === "string" ? alert.state : "invalid");
+} catch {
+  process.stdout.write("invalid");
+}
+NODE
+)"
+  case "$state" in
+    open) ;;
+    dismissed|fixed)
+      node - "$operation" "$tmpdir/current.json" <<'NODE'
+const fs = require("node:fs");
+const [operation, responsePath] = process.argv.slice(2);
+const data = JSON.parse(fs.readFileSync(responsePath, "utf8"));
+process.stdout.write(`${JSON.stringify({ status: "no-op", operation, data })}\n`);
+NODE
+      exit 0
+      ;;
+    *)
+      emit_error "SECURITY_RESPONSE_INVALID" "The platform returned an alert without a valid state."
+      exit 1
+      ;;
+  esac
+  node - "$reason" "$comment_file" > "$tmpdir/payload.json" <<'NODE'
+const fs = require("node:fs");
+const [reason, commentFile] = process.argv.slice(2);
+process.stdout.write(JSON.stringify({
+  state: "dismissed",
+  dismissed_reason: reason,
+  dismissed_comment: fs.readFileSync(commentFile, "utf8")
+}));
+NODE
+  if ! gh api --method PATCH "$endpoint" --input "$tmpdir/payload.json" > "$tmpdir/response.json" 2> "$tmpdir/error.txt"; then
+    emit_error "SECURITY_API_FAILED" "Unable to dismiss the security alert."
+    exit 2
+  fi
+fi
+
+node - "$operation" "$tmpdir/response.json" <<'NODE'
+const fs = require("node:fs");
+const [operation, responsePath] = process.argv.slice(2);
+const raw = fs.readFileSync(responsePath, "utf8").trim();
+let data = null;
+if (raw) {
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    process.stdout.write(`${JSON.stringify({
+      status: "failed",
+      operation,
+      error: { code: "SECURITY_RESPONSE_INVALID", message: "The platform returned invalid JSON." }
+    })}\n`);
+    process.exit(1);
+  }
+}
+process.stdout.write(`${JSON.stringify({ status: "applied", operation, data })}\n`);
+NODE

package/templates/.agents/scripts/security-alerts.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+
+set -e
+
+operation="${1:-}"
+
+node - "$operation" <<'NODE'
+const operation = process.argv[2] || "";
+const known = new Set([
+  "read-dependabot",
+  "dismiss-dependabot",
+  "read-codescan",
+  "dismiss-codescan"
+]);
+const payload = known.has(operation)
+  ? {
+      status: "degraded",
+      operation,
+      error: {
+        code: "PLATFORM_SECURITY_UNSUPPORTED",
+        message: "The current platform does not provide a security alert adapter."
+      }
+    }
+  : {
+      status: "failed",
+      operation,
+      error: { code: "SECURITY_OPERATION_INVALID", message: "Unknown security alert operation." }
+    };
+process.stdout.write(`${JSON.stringify(payload)}\n`);
+process.exit(known.has(operation) ? 0 : 1);
+NODE

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

@@ -15,6 +15,7 @@ If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--or
 
 - This skill only outputs a requirements analysis document (`analysis.md` or `analysis-r{N}.md`) and does not modify any business code
 - Base the analysis strictly on the existing task input, requirements, context, and source information in `task.md`
+- 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 old behavior, data, schemas, or callers are involved, read `.agents/rules/compatibility-policy.md` first. State current-only when admission evidence is absent; do not turn speculation into a requirement
 - After executing this skill, you **must** immediately update task status in task.md
 

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

@@ -15,6 +15,7 @@ description: >
 
 - 本技能仅产出需求分析文档（`analysis.md` 或 `analysis-r{N}.md`）—— 不修改任何业务代码
 - 严格基于 `task.md` 中已有的任务输入、需求、上下文和来源信息展开分析
+- 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 涉及旧行为、旧数据、旧 schema 或旧调用方时，先读取 `.agents/rules/compatibility-policy.md`；没有兼容准入证据时明确采用 current-only，不把推测写成需求
 - 执行本技能后，你**必须**立即更新 task.md 中的任务状态
 

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

@@ -23,7 +23,7 @@ The skill still owns the security-alert API. When a related task exists, Step 7
 
 ### 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.
 
 Verify that the alert is in the `open` state. If it is already dismissed or fixed, inform the user and exit.
 
@@ -71,7 +71,7 @@ Confirm? (y/N)
 
 ### 6. Execute the Dismissal
 
-Dismiss the alert by following the Code Scanning dismiss command in `.agents/rules/security-alerts.md`, passing the mapped `{api-reason}` and the user's explanation.
+Write the user's explanation to `{comment-file}`, then run `bash .agents/scripts/security-alerts.sh dismiss-codescan --number {alert-number} --reason {api-reason} --comment-file {comment-file}`. Parse the JSON result and continue only when the dismissal is `applied` or `no-op`.
 
 **API reason mapping** (per the Code Scanning API):
 - False Positive -> `false positive`

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

@@ -23,7 +23,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 结果获取告警详情。
 
 验证告警处于 `open` 状态。如果已被关闭/修复，告知用户并退出。
 
@@ -71,7 +71,7 @@ Code Scanning 告警 #{alert-number}
 
 ### 6. 执行关闭
 
-按 `.agents/rules/security-alerts.md` 中的 Code Scanning 告警关闭命令执行关闭操作，并传入映射后的 `{api-reason}` 与用户说明。
+将用户说明写入 `{comment-file}`，然后运行 `bash .agents/scripts/security-alerts.sh dismiss-codescan --number {alert-number} --reason {api-reason} --comment-file {comment-file}`。解析 JSON 结果，仅当关闭状态为 `applied` 或 `no-op` 时继续。
 
 **API reason 映射**（按 Code Scanning API）：
 - 误报 -> `false positive`