@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/templates/.agents/skills/review-plan/reference/report-template.en.md

@@ -1,5 +1,7 @@
 # Review Report Template
 
+> Before writing this report, use `task-artifact init --family review-plan` to create the skeleton and preserve every `artifact-section` marker; the skeleton contains no review conclusion.
+
 Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 
 ## Output Template
@@ -12,11 +14,31 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 - **Review Input**:
   - `{plan-artifact}` (the highest-round technical-plan artifact actually reviewed, e.g. `plan-r2.md`; leave blank if it cannot be reliably determined)
 
-## State Check
+## Review Summary
 
-> Paste the raw state-check command output; each command starts with `$ `.
+## Qualification Audit Review
 
-## Review Summary
+> Use `.agents/rules/decision-qualification.md` to review the five tables: constraint dependencies, candidate qualification, classification results, upstream relations, and dependency snapshot.
+
+### Constraint Dependencies
+| constraint_id | constraint_digest | role | evidence |
+| --- | --- | --- | --- |
+
+### Candidate Qualification
+| candidate_id | status | impact | constraint_ids | evidence |
+| --- | --- | --- | --- | --- |
+
+### Classification Results
+| decision_id | classification | evidence |
+| --- | --- | --- |
+
+### Upstream Relations
+| upstream_family | upstream_artifact | upstream_round | upstream_sha256 | relation |
+| --- | --- | --- | --- | --- |
+
+### Dependency Snapshot
+| task_input_digest | non_constraint_input_digest | upstream_artifact_digest |
+| --- | --- | --- |
 
 - **Reviewer**: {reviewer-name}
 - **Review Time**: {timestamp}
@@ -24,7 +46,7 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 - **Overall Verdict**: {Approved / Changes Requested / Rejected}
 - **Findings (AI-actionable)**: {unresolved-blockers} blockers, {unresolved-major} majors, {unresolved-minor} minors / **Manual validation**: 0
 
-## Review Coverage Declaration
+## Inspection Coverage
 
 | pass_id | scope | evidence | result | gaps_or_assumptions |
 |---------|-------|----------|--------|---------------------|
@@ -102,7 +124,7 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 **File**: `{file-path}:{line-number}`
 **Suggestion**: {improvement suggestion}
 
-## Non-blocking Advisories
+## Non-blocking Suggestions
 
 > Record only future optimizations that do not affect the current artifact's completeness, correctness, or acceptance. Advisories do not enter the disagreement ledger, finding counts, or verdict.
 
@@ -121,27 +143,42 @@ Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
 > If this round has no Manual validation items, keep the section heading and write "None".
 
 
-## Review Disagreement Ledger Writeback
+## Conclusion and Recommendation
 
-> Record the structured intents to submit: use `task-ledger finding-upsert` for new findings and `finding-review` for prior responses. The core allocates `PL-N` and validates transitions; do not edit task.md table rows.
-> Every finding escalated to `needs-human-decision` must include a self-contained detail block per `.agents/rules/human-decision-context.md`, with evidence pointing to that stable anchor.
+### Approval Decision
+- [ ] Approved
+- [ ] Changes Requested
+- [ ] Rejected
+
+### Next Steps
+{recommended next step}
+
+## State Check
 
-## Evidence
+> Record the state-check command, review scope, key result, and uncovered parts; each command starts with `$ `.
+> Follow `.agents/rules/evidence-reporting.md`: record review scope, key result, and uncovered parts; do not paste complete successful stdout.
 
-> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present. Every Blocker must be backed by a reproducible command (rg/grep/sed/nl) and its raw output; a judgment that cannot be reproduced must be downgraded or moved to Self-Doubt.
+## Raw Evidence
+
+> Follow `.agents/rules/evidence-reporting.md`: pair each claim with a `$ ` command and proportionate result summary; Blockers, failures, blocking conditions, or disputes require a reproducible command, exact location, and decisive excerpt; a judgment that cannot be reproduced must be downgraded or moved to Self-Doubt.
 
 - Claim: {verified claim}
 ```text
 $ {command}
-{raw output}
+{result summary or decisive excerpt}
 ```
 
-## Self-Doubt
+## Self-critique
 
 > Explicitly declare conclusions, inferences, and assumptions in this review that were **not directly verified**; downstream can rebut them on this basis. Write "None" if there are none.
 
 - {an unverified conclusion or inference; note why it was not verified and the impact if it is overturned}
 
+## Review Disagreement Ledger Write-back
+
+> Record the structured intents to submit: use `task-ledger finding-upsert` for new findings and `finding-review` for prior responses. The core allocates `PL-N` and validates transitions; do not edit task.md table rows.
+> Every finding escalated to `needs-human-decision` must include a self-contained detail block per `.agents/rules/human-decision-context.md`, with evidence pointing to that stable anchor.
+
 ## Highlights
 
 - {what went well}
@@ -150,14 +187,4 @@ $ {command}
 
 - [ ] Implementation matches the technical plan
 - [ ] No unintended scope expansion
-
-## Conclusion and Recommendation
-
-### Approval Decision
-- [ ] Approved
-- [ ] Changes Requested
-- [ ] Rejected
-
-### Next Steps
-{recommended next step}
 ```

package/templates/.agents/skills/review-plan/reference/report-template.zh-CN.md

@@ -1,5 +1,7 @@
 # 审查报告模板
 
+> 写入本报告前，先用 `task-artifact init --family review-plan` 创建骨架，并保留每个 `artifact-section` marker；骨架不包含审查结论。
+
 编写 `review-plan.md` 或 `review-plan-r{N}.md` 时使用本模板。
 
 ## 输出模板
@@ -12,11 +14,31 @@
 - **审查输入**：
   - `{plan-artifact}`（本轮实际检视的最高轮技术方案产物，如 `plan-r2.md`；无法可靠取得则留空）
 
-## 状态核对
+## 审查摘要
 
-> 粘贴状态核对命令原文；每条命令以 `$ ` 开头。
+## 资格审计复核
 
-## 审查摘要
+> 按 `.agents/rules/decision-qualification.md` 复核：约束依赖、候选资格、分类结果、上游关系和依赖快照五张表。
+
+### 约束依赖
+| constraint_id | constraint_digest | role | evidence |
+| --- | --- | --- | --- |
+
+### 候选资格
+| candidate_id | status | impact | constraint_ids | evidence |
+| --- | --- | --- | --- | --- |
+
+### 分类结果
+| decision_id | classification | evidence |
+| --- | --- | --- |
+
+### 上游关系
+| upstream_family | upstream_artifact | upstream_round | upstream_sha256 | relation |
+| --- | --- | --- | --- | --- |
+
+### 依赖快照
+| task_input_digest | non_constraint_input_digest | upstream_artifact_digest |
+| --- | --- | --- |
 
 - **审查者**：{reviewer-name}
 - **审查时间**：{timestamp}
@@ -121,19 +143,29 @@
 > 如本轮无人工校验项，保留段落标题并写「（无）」。
 
 
-## 审查分歧账本回写
+## 结论与建议
 
-> 本段记录将提交的结构化意图：新 finding 用 `task-ledger finding-upsert`，上一轮响应复核用 `finding-review`；由核心分配 `PL-N` 并校验状态机，禁止手写 task.md 表格。
-> 凡升级为 `needs-human-decision` 的 finding，必须按 `.agents/rules/human-decision-context.md` 在本报告中提供自足详情块，并让 evidence 指向该稳定锚点。
+### 审查决定
+- [ ] 通过
+- [ ] 需要修改
+- [ ] 拒绝
+
+### 下一步
+{recommended next step}
+
+## 状态核对
+
+> 记录状态核对命令、审查范围、关键结果和未覆盖部分；每条命令以 `$ ` 开头。
+> 按 `.agents/rules/evidence-reporting.md` 同时记录审查范围、关键结果和未覆盖部分；正常成功不粘贴完整 stdout。
 
 ## 证据原文
 
-> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。每条 Blocker 必须配可复现命令（rg/grep/sed/nl）及其原文；无法复现的判断须降级或移入「自我质疑」。
+> 遵循 `.agents/rules/evidence-reporting.md`：每条断言配对 `$ ` 命令和相称结果摘要；Blocker、失败、阻塞或争议必须保留可复现命令、准确位置和决定性摘录；无法复现的判断须降级或移入「自我质疑」。
 
 - 断言：{verified claim}
 ```text
 $ {command}
-{raw output}
+{result summary or decisive excerpt}
 ```
 
 ## 自我质疑
@@ -142,6 +174,11 @@ $ {command}
 
 - {未直接验证的结论或推断；说明为何未验证、若被推翻的影响}
 
+## 审查分歧账本回写
+
+> 本段记录将提交的结构化意图：新 finding 用 `task-ledger finding-upsert`，上一轮响应复核用 `finding-review`；由核心分配 `PL-N` 并校验状态机，禁止手写 task.md 表格。
+> 凡升级为 `needs-human-decision` 的 finding，必须按 `.agents/rules/human-decision-context.md` 在本报告中提供自足详情块，并让 evidence 指向该稳定锚点。
+
 ## 亮点
 
 - {what went well}
@@ -150,14 +187,4 @@ $ {command}
 
 - [ ] 实现与技术方案一致
 - [ ] 没有意外的范围扩张
-
-## 结论与建议
-
-### 审查决定
-- [ ] 通过
-- [ ] 需要修改
-- [ ] 拒绝
-
-### 下一步
-{recommended next step}
 ```

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

@@ -12,6 +12,10 @@ Based on the target PR's lifecycle-evidence completeness and change risk, select
 
 ## Boundary / Critical Rules
 
+### Persisted Report Evidence
+
+Before generating the PR review report, read `.agents/rules/evidence-reporting.md`. Normal review records the command, scope, structured result, actual conclusion, and uncovered parts; formal Review, findings, blocking conditions, or disputes retain exact identity fields and decisive evidence.
+
 - Strictly follow the fixed evidence-grading decision flow: host resolution → evidence classification → freshness/alignment → risk grading → mode selection
 - `pr-review*` is an independent artifact family: it does not join the analysis/plan/code stage chain and never changes `current_step`
 - Only a formal PR Review (head SHA, conclusion, findings, receipt, Issue artifact link) is published on the PR; no second full process copy goes to a regular PR comment
@@ -41,7 +45,7 @@ Before making any task-state judgment or user-visible conclusion, run the state
 agent-infra-internal task-snapshot {task-id} --format text
 ```
 
-The task-anchored path records the current task directory and existing `pr-review*` rounds before starting; the one-shot path (no task) records the PR number and target directory. Paste the state-check output into the `## State Check` section of this round's `pr-review-rN.md`.
+The task-anchored path records the current task directory and existing `pr-review*` rounds before starting; the one-shot path (no task) records the PR number and target directory. Record the command, PR/head, review scope, key result, and uncovered parts in this round's `## State Check` section; do not paste complete directory listings or task tails on normal success, and retain decisive raw lines for identity mismatches, failures, blocking conditions, or disputes.
 
 ## Steps
 

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

@@ -12,6 +12,10 @@ description: >
 
 ## 行为边界 / 关键规则
 
+### 持久化报告证据
+
+生成 PR 审查报告时，先读取 `.agents/rules/evidence-reporting.md`。正常审查记录命令、范围、结构化结果、实际结论和未覆盖部分；正式 Review、finding、阻塞或争议的身份字段和决定性证据必须精确保留。
+
 - 严格遵循方案中固化的证据分级主决策流：宿主解析 → 证据分类 → 新鲜度/对齐 → 风险分级 → 模式选择
 - `pr-review*` 是独立 artifact family：不接入 analysis/plan/code 阶段依赖链，不修改 `current_step`
 - PR 上只发布正式 PR Review（head SHA、结论、finding、receipt、Issue artifact 链接），不发第二份完整过程原文到 PR 普通评论
@@ -41,7 +45,7 @@ description: >
 agent-infra-internal task-snapshot {task-id} --format text
 ```
 
-任务锚定路径在开始前记录当前任务目录与既有 `pr-review*` 轮次；一次性路径（无任务）记录 PR 编号与目标目录。状态核对输出粘贴到本轮产物 `pr-review-rN.md` 的 `## 状态核对` 段。
+任务锚定路径在开始前记录当前任务目录与既有 `pr-review*` 轮次；一次性路径（无任务）记录 PR 编号与目标目录。将命令、PR/head、审查范围、关键结果和未覆盖部分写入本轮产物 `pr-review-rN.md` 的 `## 状态核对` 段；正常成功不粘贴完整目录清单或 `task.md` 尾部，身份不一致、失败、阻塞或争议时保留决定性原文行。
 
 ## 执行步骤
 

package/templates/.agents/skills/review-pr/reference/report-template.en.md

@@ -11,7 +11,8 @@ Use the following structure when creating `pr-review.md` or `pr-review-r{N}.md`.
 
 ## State Check
 
-> Paste the state-check command output verbatim; each command starts with `$ `.
+> Record the state-check command, PR/head, review scope, key result, and uncovered parts; each command starts with `$ `.
+> Follow `.agents/rules/evidence-reporting.md`: record PR, head, review scope, key result, and uncovered parts; do not paste complete successful stdout.
 
 ## Identity
 
@@ -76,10 +77,10 @@ Land the following in order before the line-level findings, without impersonatin
 
 ## Evidence
 
-> Every "I verified X" assertion must pair with the corresponding tool output verbatim; the gate only checks this section exists and has at least one `$ ` line.
+> Follow `.agents/rules/evidence-reporting.md`: pair every assertion with a `$ ` command and proportionate result summary; formal Review, failures, blocking conditions, or disputes retain exact identity and decisive excerpts.
 
 - Assertion: {verified claim}
 ```text
 $ {command}
-{raw output}
+{result summary or decisive excerpt}
 ```

package/templates/.agents/skills/review-pr/reference/report-template.zh-CN.md

@@ -11,7 +11,8 @@
 
 ## 状态核对
 
-> 粘贴状态核对命令原文；每条命令以 `$ ` 开头。
+> 记录状态核对命令、PR/head、审查范围、关键结果和未覆盖部分；每条命令以 `$ ` 开头。
+> 按 `.agents/rules/evidence-reporting.md` 同时记录 PR、head、审查范围、关键结果和未覆盖部分；正常成功不粘贴完整 stdout。
 
 ## 身份信息
 
@@ -76,10 +77,10 @@
 
 ## 证据原文
 
-> 每条「我验证了 X」断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。
+> 遵循 `.agents/rules/evidence-reporting.md`：每条断言配对 `$ ` 命令和相称结果摘要；正式 Review、失败、阻塞或争议保留准确身份和决定性摘录。
 
 - 断言：{verified claim}
 ```text
 $ {command}
-{raw output}
+{result summary or decisive excerpt}
 ```

package/templates/.agents/skills/run-manual-validation/SKILL.en.md

@@ -14,36 +14,57 @@ Lifecycle events require explicit trigger data: use `{trigger-initiator}=orchest
 
 The entry point may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Parse `--scope`, `--timeout`, and `--format` before `--`, preserve the user command after `--` verbatim, then call `agent-infra-internal task-context resolve {task-scope}`. Pass through resolution failures without scanning tasks locally. The internal `task-validate` protocol continues to use a positional task ref.
 
+For cross-environment validation (the task workspace lives on another host), pass `--branch <ref>` explicitly to enter the branch-only fallback: skip `task-context resolve` and use that branch ref directly as the positional argument of `task-validate`, which returns branch-only evidence with `taskId: null`. Without `--branch`, a resolution failure is still passed through; never degrade silently. `--task` and `--branch` are mutually exclusive.
+
 ## Boundary
 
+### Persisted Report Evidence
+
+Before generating a validation report, read `.agents/rules/evidence-reporting.md`. Record only the command name, target scope, exit status, sanitized result, and coverage gap; never record complete argv, environment variables, tokens, absolute paths, or a raw sensitive transcript.
+
 - Select the validation mode, call the sole mechanical entry point, and record evidence; do not mark PR manual validation complete.
 - `complete-manual-validation` remains the maintainer's final registration after coverage is judged sufficient.
 - Never manipulate temporary worktrees, leases, or containers directly; only call `agent-infra-internal task-validate`.
-- Never record tokens, environment variables, full argv, absolute user paths, or raw transcripts in the artifact.
+- Never record tokens, environment variables, full argv, absolute user paths, or raw transcripts in the artifact; the core must write one current-only evidence envelope for each validation target.
 - Before generating a validation artifact Markdown file that will be synced to an Issue, read `.agents/rules/sync-content-generation.md` and follow its generator-side constraints; Issue sync remains transparent and does not parse or rewrite the body.
+- The branch-only fallback writes to `.agents/workspace/validations/{branch-slug}/` and is marked `recoverable: false`: no task.md write-back, no lifecycle events, no Issue sync, no `task-verify`; the artifact must be carried back to the host that owns the task workspace for registration.
 
 ## Step 0: State Check (pre-execution hard gate)
 
-Resolve the task reference, then run this command and copy its original output into the artifact:
+Resolve the task reference, then run this command and record the task/artifact scope, key result, and uncovered parts in the artifact; do not paste complete directory listings or task tails on normal success. Retain decisive raw lines only for failures, blocking conditions, identity mismatches, or disputes:
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
 ```
 
+Branch-only has no `{task-id}`: skip this step and record `not-applicable (branch-only)` in the artifact's `## State Check` section.
+
 ## Steps
 
 1. Read `reference/discovery-and-execution.md` and parse the input mode. Stop before started without an artifact for invalid or partial input.
 2. Run `agent-infra-internal task-artifact {task-id} inspect --family validation-run` and read the latest review-code manual-validation items. Then run `agent-infra-internal platform-pr inspect {task-id}` and use the reference status matrix to discover, merge, and number items. Only automatic mode stops before started when reliable sources are empty or the sole possible source is unreadable; valid explicit mode always continues with the user command as effective work.
 3. Take the round and artifact name from the core result. After confirming valid explicit work or a non-empty discovered list, run `agent-infra-internal task-event {task-id} validation-run.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}` and classify each item as `executable|unavailable|unknown|unsafe|unresolved`.
-4. Invoke every executable item separately with `agent-infra-internal task-validate {task-ref} --scope snapshot --format json -- {command...}`. Only make a second explicit inplace invocation for that item when evidence proves it is required. If no item is executable, run no fabricated command but still produce coverage-gap evidence.
+4. Allocate an `{evidence-file}` for each validation target and invoke every executable item separately with `agent-infra-internal task-validate {task-ref} --scope snapshot --format json --evidence-file {evidence-file} -- {command...}`. Only make a second explicit inplace invocation for that item when evidence proves it is required, using its evidence file. If no item is executable, run no fabricated command but still produce coverage-gap evidence.
 5. Read `reference/report-template.md`, create `validation-run.md|validation-run-r{N}.md`, and record the input mode, discovered list, per-item results, CLI JSON allowlist, and sanitized summaries.
 6. Run `agent-infra-internal task-event {task-id} validation-run.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {artifact}`. When an Issue exists, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` and then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {standard-agent-token}`.
 7. Run `agent-infra-internal task-verify {task-id} validation-run.completed --artifact {artifact} --format text`; fix failures and rerun it.
 8. Report the evidence path, coverage gaps, and verification result; explicitly leave the decision to run `complete-manual-validation` to the maintainer. Read `.agents/rules/next-step-output.md` and end with `Completed at`.
 
+## Scenario B: Branch-Only Fallback
+
+With `--branch <ref>`, only the following differ from the steps above; every other constraint (classification, per-item execution, sanitization, never changing PR manual validation state) still applies.
+
+- **Explicit mode only**: `task-artifact` and `platform-pr inspect` both require a task ref, so branch-only cannot discover items. Stop before writing any artifact when the user command after `--` is missing.
+- **Skip Step 0 and the Step 2 discovery**: record both sources as `unavailable` and list this round's items under the `explicit` source in the artifact's `## Discovered Items` section.
+- **Step 3 skips only the event call**: emit no `validation-run.started`, but still classify every item as `executable|unavailable|unknown|unsafe|unresolved`.
+- **Step 4 runs unchanged**: write evidence files in the same branch-only validation directory and invoke `agent-infra-internal task-validate {branch-ref} --scope snapshot --format json --evidence-file {evidence-file} -- {command...}`.
+- **Step 5 relocates the artifact**: write `.agents/workspace/validations/{branch-slug}/validation-run.md|validation-run-r{N}.md` using the same `reference/report-template.md`. Derive `{branch-slug}` from the `--branch` ref character by character: keep `[A-Za-z0-9._-]` and replace everything else (including `/`) with `-`, so the result is a single path segment; if the result is empty or consists only of `.`, treat it as invalid input and stop before writing any artifact.
+- **Skip Steps 6 and 7**: emit no `validation-run.completed`, run no `platform-comment sync`, and run no `task-verify`.
+- **Step 8 adds a notice**: state that the artifact is unrecoverable and unregistered, and must be carried back to the host owning the task workspace before a maintainer runs `complete-manual-validation`.
+
 ## Completion Checklist
 
 - [ ] Used `agent-infra-internal task-validate` for every executable item, or recorded that none were executable
 - [ ] Recorded sanitized validation-run evidence
 - [ ] Did not change PR manual validation completion state
-- [ ] Updated task.md and passed completion verification
+- [ ] Updated task.md and passed completion verification (branch-only instead: recorded `recoverable: false` and left the task ledger untouched)

package/templates/.agents/skills/run-manual-validation/SKILL.zh-CN.md

@@ -14,36 +14,57 @@ description: >
 
 入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。先解析 `--scope`、`--timeout`、`--format`，在 `--` 后原样保留用户命令，再调用 `agent-infra-internal task-context resolve {task-scope}`。解析失败时透传非零退出码，不自行扫描任务。内部 `task-validate` 协议仍使用位置 task ref。
 
+跨环境校验（任务工作区在另一台宿主）显式传 `--branch <ref>` 进入 branch-only 降级路径：不调用 `task-context resolve`，直接以该分支 ref 作为 `task-validate` 的位置参数，核心据此返回 `taskId: null` 的 branch-only 证据。未传 `--branch` 时解析失败仍透传非零退出码，不得静默降级。`--task` 与 `--branch` 互斥。
+
 ## 行为边界
 
+### 持久化报告证据
+
+生成验证报告时，先读取 `.agents/rules/evidence-reporting.md`。只记录命令名称、目标范围、退出状态、sanitized result 和覆盖缺口；不得记录完整 argv、环境变量、token、绝对路径或原始敏感 transcript。
+
 - 本技能负责选择校验模式、调用唯一机械入口并记录证据；不把 PR 人工校验标为完成。
 - `complete-manual-validation` 仍是维护者确认覆盖充分后的最终登记入口。
 - 禁止直接操作临时 worktree、lease 或 container；只调用 `agent-infra-internal task-validate`。
-- 产物不得记录 token、环境变量、完整 argv、绝对用户路径或原始 transcript。
+- 产物不得记录 token、环境变量、完整 argv、绝对用户路径或原始 transcript；每个验证目标必须由核心写入同一 current-only evidence envelope。
 - 生成会同步到 Issue 的验证 artifact Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；Issue 同步保持透明，不解析或改写正文。
+- branch-only 降级路径走 `.agents/workspace/validations/{branch-slug}/`，标记 `recoverable: false`：不写 task.md、不发 lifecycle 事件、不同步 Issue、不跑 `task-verify`；产物须带回宿主机，由维护者登记。
 
 ## 第 0 步：状态核对（执行前硬约束）
 
-解析任务引用后运行，并把原文写入产物：
+解析任务引用后运行，并在产物中记录任务/产物范围、关键结果和未覆盖部分；正常成功不粘贴完整目录清单或 `task.md` 尾部，失败、阻塞、身份不一致或争议时附决定性原文行：
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
 ```
 
+branch-only 无 `{task-id}`，跳过本步，并在产物 `## 状态核对` 记录 `not-applicable (branch-only)`。
+
 ## 执行步骤
 
 1. 读取 `reference/discovery-and-execution.md`，解析输入模式；非法或半截输入在 started 前停止，不写产物。
 2. 运行 `agent-infra-internal task-artifact {task-id} inspect --family validation-run`，读取最新 review-code 人工校验项；再运行 `agent-infra-internal platform-pr inspect {task-id}`，按 reference 的状态矩阵发现、归并并编号。仅在自动模式下，可靠来源无项或唯一可能来源不可读时才在 started 前停止；合法显式模式始终以用户命令作为有效工作继续。
 3. 从核心结果取得轮次和产物名；确认存在有效显式工作或非空发现清单后，运行 `agent-infra-internal task-event {task-id} validation-run.started --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code}`，并逐项分类为 `executable|unavailable|unknown|unsafe|unresolved`。
-4. 每个可执行项分别调用 `agent-infra-internal task-validate {task-ref} --scope snapshot --format json -- {command...}`；只有证据表明必须原位时才对该项进行第二次显式 inplace 调用。零项可执行时不运行伪造命令，但仍继续产出覆盖缺口证据。
+4. 为每个验证目标分配 `{evidence-file}`，分别调用 `agent-infra-internal task-validate {task-ref} --scope snapshot --format json --evidence-file {evidence-file} -- {command...}`；只有证据表明必须原位时才对该项进行第二次显式 inplace 调用并写入对应 evidence 文件。零项可执行时不运行伪造命令，但仍继续产出覆盖缺口证据。
 5. 读取 `reference/report-template.md`，创建 `validation-run.md|validation-run-r{N}.md`；记录输入模式、发现清单、逐项结果、CLI JSON allowlist 与去敏摘要。
 6. 运行 `agent-infra-internal task-event {task-id} validation-run.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {artifact}`。存在 Issue 时依次运行 `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 {artifact} --agent {standard-agent-token}`。
 7. 运行 `agent-infra-internal task-verify {task-id} validation-run.completed --artifact {artifact} --format text`；未通过则修复后重跑。
 8. 告知用户证据路径、覆盖缺口和验证结果；明确仍需维护者判断是否执行 `complete-manual-validation`。读取 `.agents/rules/next-step-output.md`，最后一行输出 `Completed at`。
 
+## 场景 B：branch-only 降级
+
+传入 `--branch <ref>` 时，相对上述步骤只有以下差异；其余约束（分类、逐项执行、去敏、不改 PR 人工验证完成状态）不变。
+
+- **仅接受显式模式**：`task-artifact` 和 `platform-pr inspect` 都要求 task ref，branch-only 无法自动发现。缺少 `--` 后的用户命令时，在写入任何产物前停止。
+- **跳过第 0 步与第 2 步的发现**：把两个来源记为 `unavailable`，并在产物 `## 发现清单` 用 `explicit` 来源登记本轮项。
+- **第 3 步只跳过事件调用**：不发 `validation-run.started`，但逐项分类为 `executable|unavailable|unknown|unsafe|unresolved` 照常执行。
+- **第 4 步照常执行**：将 evidence 文件写入同一 branch-only validation 目录，调用 `agent-infra-internal task-validate {branch-ref} --scope snapshot --format json --evidence-file {evidence-file} -- {command...}`。
+- **第 5 步改写产物位置**：写入 `.agents/workspace/validations/{branch-slug}/validation-run.md|validation-run-r{N}.md`，沿用同一份 `reference/report-template.md`。`{branch-slug}` 由 `--branch` 的 ref 逐字符转换：保留 `[A-Za-z0-9._-]`，其余（含 `/`）一律换成 `-`，结果必须是单层目录名；若结果为空或仅由 `.` 组成，判为非法输入并在写入任何产物前停止。
+- **跳过第 6、7 步**：不发 `validation-run.completed`，不做 `platform-comment sync`，不跑 `task-verify`。
+- **第 8 步追加提示**：明确告知产物不可恢复、未登记账本，需带回持有任务工作区的宿主机后再由维护者执行 `complete-manual-validation`。
+
 ## 完成检查清单
 
 - [ ] 每个可执行项均已使用 `agent-infra-internal task-validate`，或已记录零项可执行
 - [ ] 已记录去敏 validation-run 证据
 - [ ] 未修改 PR 人工验证完成状态
-- [ ] 已更新 task.md 并通过完成校验
+- [ ] 已更新 task.md 并通过完成校验（branch-only 改为：已记录 `recoverable: false` 且未触碰任务账本）

package/templates/.agents/skills/run-manual-validation/reference/discovery-and-execution.en.md

@@ -10,9 +10,12 @@ Read this file before parsing input, discovering manual-validation items, or con
 | A literal `--` is present but the target or command is empty | Invalid input; stop before `validation-run.started` |
 | No `--` and only a task ref | Automatic mode |
 | No `--` and additional positional arguments | Invalid or partial input; do not ignore arguments or guess a command |
+| `--branch <ref>` is passed | Branch-only fallback; must also be explicit mode, so a missing command after `--` is invalid input |
 
 Explicit mode still reads available sources to map coverage, but it must not synthesize another command for the same target. Only automatic mode constructs actions for discovered items.
 
+Branch-only has no task ref, so both discovery sources are unreadable and are recorded as `unavailable`; this round's items are listed under the `explicit` source and must not trigger the automatic-mode source stop conditions.
+
 ## Work Gate Matrix
 
 | mode | source state | gate |
@@ -58,7 +61,7 @@ Only `executable` items may run. Commands must not expose credentials, environme
 1. Invoke each executable item separately:
 
    ```bash
-   agent-infra-internal task-validate {task-ref} --scope snapshot --format json -- {command...}
+   agent-infra-internal task-validate {task-ref|branch-ref} --scope snapshot --format json -- {command...}
    ```
 
 2. Only when the item or first-run evidence proves a dependency on uncommitted content, original mounts, or in-place permissions, explicitly invoke that item a second time with `--scope inplace` and record the reason.

package/templates/.agents/skills/run-manual-validation/reference/discovery-and-execution.zh-CN.md

@@ -10,9 +10,12 @@
 | 存在 literal `--`，但目标或命令为空 | 非法输入；在 `validation-run.started` 前停止 |
 | 不存在 `--`，且只有 task ref | 自动模式 |
 | 不存在 `--`，但还有位置参数 | 非法/半截输入；不得忽略参数或猜测命令 |
+| 传入 `--branch <ref>` | branch-only 降级；必须同时是显式模式，缺少 `--` 后命令即非法输入 |
 
 显式模式也要读取可用来源以映射覆盖范围，但不得为同一目标另行合成命令。自动模式才为发现项构造动作。
 
+branch-only 没有 task ref，两个发现来源都不可读，一律记为 `unavailable`；本轮项以 `explicit` 来源登记，不得据此触发自动模式的来源停止条件。
+
 ## 工作门禁矩阵
 
 | mode | source state | gate |
@@ -58,7 +61,7 @@
 1. 每个可执行项分别调用：
 
    ```bash
-   agent-infra-internal task-validate {task-ref} --scope snapshot --format json -- {command...}
+   agent-infra-internal task-validate {task-ref|branch-ref} --scope snapshot --format json -- {command...}
    ```
 
 2. 仅当项目要求或首次证据证明依赖未提交内容、原挂载或原位权限时，再为该项显式调用一次 `--scope inplace`，并记录升级理由。

package/templates/.agents/skills/run-manual-validation/reference/report-template.en.md

@@ -3,6 +3,7 @@
 ## Input Mode
 
 - Mode: `{explicit|automatic}`
+- Context: `{task-bound|branch-only}` (branch-only also records `recoverable: false`)
 - Input decision: {sanitized-input-decision}
 - PR source status: `{success|no-op|failed|blocked}` / `{stable-code-or-none}`
 
@@ -10,8 +11,10 @@
 
 ```text
 $ agent-infra-internal task-snapshot {task-id} --format text
-{raw-output}
+{command-summary-and-key-result}
 ```
+> Follow `.agents/rules/evidence-reporting.md`: record command name, target scope, exit status, sanitized result, and coverage gap; do not paste complete argv or sensitive transcripts.
+> Branch-only has no `{task-id}`: record `not-applicable (branch-only)` in this section.
 
 ## Validation Target
 
@@ -67,3 +70,4 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 $ agent-infra-internal task-validate {task-ref} --scope {scope} --format json -- {redacted-command}
 {sanitized-result}
 ```
+> Keep only the allowed public command and sanitized structured result; complete successful stdout is not default report content.

package/templates/.agents/skills/run-manual-validation/reference/report-template.zh-CN.md

@@ -3,6 +3,7 @@
 ## 输入模式
 
 - 模式：`{explicit|automatic}`
+- 上下文：`{task-bound|branch-only}`（branch-only 另记 `recoverable: false`）
 - 输入判定：{sanitized-input-decision}
 - PR 来源状态：`{success|no-op|failed|blocked}` / `{stable-code-or-none}`
 
@@ -10,8 +11,10 @@
 
 ```text
 $ agent-infra-internal task-snapshot {task-id} --format text
-{raw-output}
+{command-summary-and-key-result}
 ```
+> 按 `.agents/rules/evidence-reporting.md` 记录命令名称、目标范围、退出状态、sanitized result 和覆盖缺口；不得粘贴完整 argv 或敏感 transcript。
+> branch-only 无 `{task-id}`，本段记 `not-applicable (branch-only)`。
 
 ## 验证目标
 
@@ -67,3 +70,4 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 $ agent-infra-internal task-validate {task-ref} --scope {scope} --format json -- {redacted-command}
 {sanitized-result}
 ```
+> 仅保留允许公开的命令与脱敏结构化结果；完整成功 stdout 不属于默认报告内容。

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

@@ -17,7 +17,7 @@ The orchestrator delegates only and never executes a stage skill itself. First r
 2. Before `begin-or-resume`, Codex selects a host. Without `AGENT_INFRA_CONTROL_TOKEN`, use direct-host. With task-bound control authority but no `AGENT_INFRA_CODEX_CONTROLLER_CONTEXT`, only run `codex-sandbox-controller run` with the complete policy and wait; the outer loop must not create a run, baseline, or receipt. With a context, run `verify-context` first. Stop on protocol, task/controller/process, lease, or source/profile discovery failures. Package/build/contract or hook/profile content drift is delivered as a structured warning and tells the user to rebuild the sandbox.
 3. Run `task-orchestration {task-id} begin-or-resume --client {client}` with the complete explicit policy. With no explicit policy, core reads that client's configured policy; existing runs use persisted policy. Disk state outside the complete current structure fails closed without rewriting; finish or clear active runs before upgrading. Stop on paused/completed results.
 4. Run `route`. On `completed`, run `agent-infra-internal task-verify {task-id} run-task.completed --format text` and stop. Only a `running` result with non-null `next` supplies action, role, round, artifact, requested model, and requested effort.
-5. Codex runs `codex-lifecycle capability-arm --task-id {task-id}` once. The current loop's real PostToolUse must attest that ordinary tool response. Pass its marker token, the exact routed model, and the exact routed reasoning effort to `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-token {token}`. Core first validates the exact routed model/effort, capability provenance, and controller binding, then captures a read-only snapshot, builds an in-memory prepared receipt, atomically consumes the token, and saves the prepared state with the capability session, turn, and tool-use origin. Activation then verifies that spawn belongs to the same session and turn and uses a distinct tool-use. Other clients use the same prepare without a token. Failure creates no baseline, receipt, or child.
+5. Codex runs `codex-lifecycle capability-arm --task-id {task-id}` once. The current loop's real PostToolUse must attest that ordinary tool response. Pass its `capabilityRef` marker, the exact routed model, and the exact routed reasoning effort to `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-ref {capabilityRef}`. Core accepts only the phase attestation issued by the current controller issuer: `orchestration.prepare` reserves the capability, then `artifact-finalize-local` and `task-event.completed` validate and consume their own phases; the underlying capability is terminally consumed only after the completed commit is confirmed. Without current controller proof, direct-host returns `LOCAL_EXECUTION_AUTHORITY_UNAVAILABLE` and creates no recovery intent, baseline, receipt, or child. Activation then verifies that spawn belongs to the same session and turn and uses a distinct tool-use. Other clients use the same prepare without authority. Failure creates no baseline, receipt, or child.
 6. After prepare, run `task-orchestration <task-ref> dispatch` immediately before calling the fresh native child, then use route's exact model/effort and only the short task ref, skill, `--orchestrated`, and stage identity. The trusted hook-spawn first-observation time must fall between dispatch and the deadline. Its first provenance-sensitive command must be `await-activation --stage ... --round ... --artifact ... --role ...`; before `running`, it must not snapshot, emit stage-started, or write business files. The code stage may create a local checkpoint only through code-task's durable intent core; it must not delegate a separate commit stage or push. Only explicit `recover-prepared` may clear an expired orphan when the task fingerprint is exact and no matching unconsumed active lifecycle evidence remains.
 7. Codex uses SubagentStart/Stop and App Server actual evidence to activate, consume, and seal one receipt; trusted parent fallback must produce the same complete provenance. Timed-out waits do nothing. Advance only a sealed receipt and repeat step 4 only while running.
 8. Create a fresh child each round and never follow up with an old reviewer. Each requested/actual mismatch needs its own host fallback reason. Protocol, capability, receipt hook/evidence binding, source, controller, identity, ledger, or fingerprint failure pauses and fails closed; cross-root package/build/contract or hook/profile content drift is delivered as a warning instead of blocking natural evolution.

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

@@ -17,7 +17,7 @@ description: >
 2. Codex 在 `begin-or-resume` 前选择宿主：没有 `AGENT_INFRA_CONTROL_TOKEN` 时使用 direct-host；有 task-bound control authority 但没有 `AGENT_INFRA_CODEX_CONTROLLER_CONTEXT` 时，只调用 `agent-infra-internal codex-sandbox-controller run`（转发完整显式策略）并等待其终态，外层不得创建 run、baseline 或 receipt；已有 context 时先调用 `verify-context`。protocol、task/controller/process、lease 或 source/profile discovery 校验失败即停止；package/build/contract 或 hook/profile 内容漂移只输出结构化 warning，并提示用户重建 sandbox。
 3. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume --client {client}` 并转发完整显式策略。完全没有显式策略时由核心读取当前 client 的 `agentClients[].orchestration`；existing run 使用持久化策略。磁盘状态不符合当前完整结构时核心失败关闭且不改写；升级前必须完成或清空 active run。仅当核心返回 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，先用 `agent-client model-selection` 展示 complete/partial/interactive-only 来源，再一次收集完整策略；未回答则不创建 run。若为 paused/completed，按结构化结果停止。
 4. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得自行推断。
-5. Codex 先调用一次 `agent-infra-internal codex-lifecycle capability-arm --task-id {task-id}`。该普通工具调用必须由当前 loop 的真实 PostToolUse 回写 attestation；把 route 返回的精确 model、effort 和 marker 中 token 一并传给 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-token {token}`。核心先校验精确的 model/effort、capability provenance 与 controller binding，再只读捕获快照、构造内存中的 prepared receipt，最后原子消费 token 并保存 prepared 状态，同时持久化 capability 的 session、turn、tool-use 来源。activation 再校验 spawn 与该来源属于同一 session/turn，且 spawn 使用独立的 tool-use。其他客户端直接调用同一 prepare（无 token）。任一失败不得创建 baseline、receipt 或 child。
+5. Codex 先调用一次 `agent-infra-internal codex-lifecycle capability-arm --task-id {task-id}`。该普通工具调用必须由当前 loop 的真实 PostToolUse 回写 attestation；把 route 返回的精确 model、effort 和 marker 中的 `capabilityRef` 一并传给 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-ref {capabilityRef}`。核心只接受当前 controller issuer 根据 typed lifecycle authority request 签发的 phase attestation：`orchestration.prepare` 只 reserve capability，随后由 `artifact-finalize-local` 和 `task-event.completed` 各自独立校验并消费 phase；底层 capability 仅在 completed commit 已确认后 terminal consume。没有 current controller proof 时 direct-host 返回 `LOCAL_EXECUTION_AUTHORITY_UNAVAILABLE`，不得创建 recovery intent、baseline、receipt 或 child。activation 再校验 spawn 与该来源属于同一 session/turn，且 spawn 使用独立的 tool-use。其他客户端直接调用同一 prepare（无 authority）。任一失败不得创建 baseline、receipt 或 child。
 6. prepare 成功后，在调用 fresh 原生子 Agent 的紧邻前一步执行 `task-orchestration <task-ref> dispatch`，再显式覆盖 route 返回的 model/effort；只传短任务引用、skill 名、`--orchestrated` 与 stage/round/artifact/role。可信 hook-spawn 首次观察时间必须位于 dispatch 与 deadline 之间。child 的第一条 provenance-sensitive 命令必须是 `await-activation --stage ... --round ... --artifact ... --role ...`；返回 running 前禁止 snapshot、阶段 started 或业务写入；代码阶段的本地 checkpoint 只能通过 code-task 的持久化 intent 核心完成，禁止单独委派 commit 阶段或推送。超时由核心暂停；崩溃遗留 prepared receipt 只能在 exact workspace fingerprint、无匹配的未消费 active lifecycle evidence 且 deadline 已过时显式 `recover-prepared`。
 7. Codex 用 SubagentStart/Stop 与 App Server actual evidence 激活、消费并封存唯一 receipt；受信 parent fallback 仍必须形成相同的完整 provenance。timed-out wait 无动作；只有 empty turns 或协议 `inProgress` 可等待，malformed、身份/传输错误或异常 terminal 均暂停。子 Agent 返回后只对 sealed receipt 调用 `advance`；只有 `running` 才重复步骤 4。
 8. 每轮创建新 child；禁止 follow-up 复用 reviewer。actual model/effort 与 requested 不同时必须有各自的宿主降级理由。protocol、capability、receipt 内 hook/evidence binding、source、controller、身份、账本或 fingerprint 异常都调用 `pause` 并失败关闭；跨根 package/build/contract 或 hook/profile 内容漂移按 warning 交付，不把自然演进差异当成硬失败。