@fitlab-ai/agent-infra 0.6.2 → 0.6.4

package/lib/version.ts

@@ -1,8 +1,15 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 
-const { version } = JSON.parse(
-  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
-);
+const packageJsonUrl = [
+  new URL('../package.json', import.meta.url),
+  new URL('../../package.json', import.meta.url),
+].find((url) => existsSync(url));
+
+if (!packageJsonUrl) {
+  throw new Error('Unable to locate package.json for agent-infra version');
+}
+
+const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.4.0",
+    "@clack/prompts": "1.5.1",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
@@ -54,15 +54,19 @@
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
-    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts",
-    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts tests/cli/cli.test.ts tests/cli/merge.test.ts tests/cli/sandbox.test.ts tests/core/custom-skills.test.ts tests/core/custom-tuis.test.ts tests/core/demo-regen.test.ts tests/scripts/find-existing-task.test.ts tests/scripts/platform-adapter-defaults.test.ts",
-    "test": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts",
-    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts"
+    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
+    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
+    "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
+    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^25.9.1",
     "@types/semver": "^7.7.1",
     "typescript": "~6.0"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.12"
   }
 }

package/templates/.agents/README.en.md

@@ -193,6 +193,23 @@ Each source should mirror the `.agents/skills/` layout and include `SKILL.md` at
 - Built-in skills are not overridable by custom sources; if a source skill name conflicts with a built-in skill, the source copy is skipped
 - Use `files.ejected` if the project must take ownership of a built-in skill or command
 
+## File Ownership and Sync Strategy
+
+The `files` field in `.agents/.airc.json` groups project files into three categories:
+
+| Category | When the template has the file | When the template does not have the file | Cleanup behavior |
+|----------|--------------------------------|------------------------------------------|------------------|
+| `managed` | Write from the template and overwrite | Treat as removed from the template | Delete the local project copy |
+| `merged` | Merge semantically by AI or humans | Do not write from the template | Keep the local project copy |
+| `ejected` | May be created from the template first; skip overwrite once it exists | Do not write from the template | Keep the local project copy |
+
+`ejected` has two common uses:
+
+1. **Taking over a built-in file**: the project needs full control over a rule, command, or config file that originally came from the template.
+2. **Declaring a project-only file**: the project owns a file under a managed directory wildcard, but the template does not contain that file; list it in `files.ejected` so sync does not treat it as a removed template file.
+
+`ejected` entries support literal paths or globs, using the same matching rules as `merged`.
+
 ## Custom TUI Configuration
 
 Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
@@ -257,6 +274,7 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 
 - Keep SKILL.md as concise as possible; move detailed rules, long templates, and large script blocks into a sibling `reference/` or `scripts/` directory.
 - Store declarative configuration in a sibling `config/` directory, for example `config/verify.json`.
+  When `required_sections` or `required_patterns` contain language-specific text, provide `config/verify.en.json` and `config/verify.zh-CN.json`; sync strips the selected language variant back to `config/verify.json`.
 - Use explicit navigation in the skeleton, such as: `Read reference/xxx.md before executing this step.`
 - Keep scripts in `scripts/` and execute them instead of inlining long bash blocks.
 
@@ -269,6 +287,7 @@ node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact
 ```
 
 - Each skill declares its own checks in `config/verify.json`; keep the file focused on what that skill must validate
+- For language-specific artifact headings or anchors, keep only `required_sections` and language-specific `required_patterns` different between `config/verify.en.json` and `config/verify.zh-CN.json`
 - If a skill also prints next-step guidance, run the gate first and only show those instructions after the gate passes
 - For user-facing final validation, prefer `--format text` so the reply contains a readable summary instead of raw JSON
 - Shared validation logic belongs in `.agents/scripts/validate-artifact.js`; do not move detailed rules back into SKILL.md

package/templates/.agents/README.zh-CN.md

@@ -193,6 +193,23 @@ args: "<task-id>"   # 可选
 - 自定义 source 不能覆盖内置 skill；如果与内置 skill 同名，会跳过该 source skill
 - 如果项目必须接管某个内置 skill 或命令，请使用 `files.ejected`
 
+## 文件归属与同步策略
+
+`.agents/.airc.json` 的 `files` 字段把项目文件分为三类：
+
+| 类别 | 模板中存在时 | 模板中不存在时 | 清理行为 |
+|------|--------------|----------------|----------|
+| `managed` | 从模板写入并覆盖 | 视为模板已下线 | 删除项目本地副本 |
+| `merged` | 由 AI 或人工语义合并 | 不从模板写入 | 保留项目本地副本 |
+| `ejected` | 首次可从模板创建，已存在时跳过覆盖 | 不从模板写入 | 保留项目本地副本 |
+
+`ejected` 有两种常见用法：
+
+1. **接管内置文件**：项目需要完全控制原本来自模板的规则、命令或配置文件，避免后续同步覆盖本地内容。
+2. **声明项目独占文件**：项目自己的文件落在 managed 目录通配下，但模板中没有同名文件；把它列入 `files.ejected`，避免同步时被当作模板已下线文件删除。
+
+`ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
+
 ## 自定义 TUI 配置
 
 当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
@@ -257,6 +274,7 @@ args: "<task-id>"   # 可选
 
 - SKILL.md 正文尽可能精简，把详细规则、长模板和大段脚本拆分到同级 `reference/` 或 `scripts/` 目录。
 - 声明式配置统一放在同级 `config/` 目录，例如 `config/verify.json`。
+  当 `required_sections` 或 `required_patterns` 包含语言相关文案时，提供 `config/verify.en.json` 和 `config/verify.zh-CN.json`；sync 会把选中的语言变体剥离为 `config/verify.json`。
 - 骨架中使用明确导航，例如：`执行此步骤前，先读取 reference/xxx.md。`
 - 长脚本继续放在 `scripts/` 目录，优先执行脚本而不是内联大段 bash。
 
@@ -269,6 +287,7 @@ node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact
 ```
 
 - 每个 skill 在自己的 `config/verify.json` 中声明需要检查的事项
+- 对语言相关的产物标题或锚点，`config/verify.en.json` 和 `config/verify.zh-CN.json` 之间只应让 `required_sections` 与语言相关的 `required_patterns` 不同
 - 如果 skill 还会展示“下一步”提示，必须先通过完成校验，再输出这些指引
 - 面向用户展示最终校验结果时，优先使用 `--format text` 输出可读摘要，而不是原始 JSON
 - 共享逻辑集中在 `.agents/scripts/validate-artifact.js`，不要把详细校验规则重新塞回 SKILL.md

package/templates/.agents/rules/create-issue.github.en.md

@@ -115,7 +115,25 @@ When applying the Issue Type, follow the "Set Issue Type" command in `.agents/ru
 
 #### milestone
 
-Infer per `.agents/rules/milestone-inference.md` § "Stage 1: `create-task` (when the platform rule creates the Issue)". When the inference is empty or the repo lacks a matching milestone, omit the milestone.
+**Mandatory; do not skip.** This section expands `.agents/rules/milestone-inference.md` Phase 1 in place and keeps the same semantics; do not treat it as optional inference.
+
+Select the milestone using these numbered steps, with priority strictly aligned to Phase 1:
+
+1. If `has_triage=false`: omit `--milestone` immediately and skip this section.
+2. List all open milestones in the repository:
+   ```bash
+   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
+     --jq '.[].title'
+   ```
+3. If task.md frontmatter explicitly provides a `milestone` field and that value appears in the step 2 list: use that value directly as `{milestone-arg}` and skip steps 4 / 5.
+4. Filter the step 2 result with `^[0-9]+\.[0-9]+\.x$`.
+   - Non-empty: sort by major and minor numerically, then choose the smallest release line as `{milestone-arg}`.
+5. If step 4 has no candidates: fall back to `General Backlog`.
+   - `General Backlog` exists in the step 2 result: use that milestone.
+   - `General Backlog` does not exist: omit `--milestone` only in this case.
+6. If the step 2 `gh api` call fails (network / authentication error): handle it as "no candidates" and continue to step 5.
+
+When a milestone is selected, pass the release line (or `General Backlog` or the explicit task.md value) as `{milestone-arg}` to the `gh issue create` command in step 5; keep the expansion rule at the end of §5 unchanged.
 
 ### 5. Call the GitHub CLI to Create the Issue
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -115,7 +115,25 @@ Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板
 
 #### milestone
 
-按 `.agents/rules/milestone-inference.md` 的 "阶段 1：`create-task`（平台规则创建 Issue 时）" 规则推断；推断结果为空或仓库无对应 milestone 时省略。
+**必须执行，不得跳过**。本节是 `.agents/rules/milestone-inference.md` 阶段 1 的就地展开，语义与之对齐；不要把它当成"可选推断"。
+
+按以下编号步骤选取 milestone（优先级与阶段 1 严格一致）：
+
+1. 如果 `has_triage=false`：直接省略 `--milestone`，跳过本节。
+2. 列出仓库 open 状态的全部 milestone：
+   ```bash
+   gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
+     --jq '.[].title'
+   ```
+3. 如果 `task.md` frontmatter 显式给出 `milestone` 字段，且该值出现在步骤 2 列表中：直接使用该值作为 `{milestone-arg}`，跳过步骤 4 / 5。
+4. 用正则 `^[0-9]+\.[0-9]+\.x$` 过滤步骤 2 结果。
+   - 非空：按 major、minor 数值升序排序，取最小的版本线作为 `{milestone-arg}`。
+5. 步骤 4 候选为空：尝试回退到 `General Backlog`。
+   - 步骤 2 结果中存在 `General Backlog`：使用该 milestone。
+   - 不存在 `General Backlog`：仅在此情况下省略 `--milestone`。
+6. 步骤 2 的 `gh api` 调用失败（网络 / 认证错误）：按"无候选"处理，落到步骤 5。
+
+设置成功时把版本线（或 `General Backlog` 或 task.md 显式值）作为 `{milestone-arg}` 带入步骤 5 的 `gh issue create` 命令；§5 末尾的展开规则保持不变。
 
 ### 5. 调用 GitHub CLI 创建 Issue
 

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

@@ -44,6 +44,18 @@ Only match titles in `X.Y.x` format and choose the smallest major/minor pair num
 
 Direct milestone writes are triage-gated. When the caller detected `has_triage=false`, omit `--milestone` and continue.
 
+### Backfill when called from `import-issue`
+
+When `import-issue` imports an existing Issue whose current milestone is empty, infer a release line using the priority above, including the `General Backlog` fallback. When a non-empty release line is found, write it back to the remote Issue:
+
+```bash
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}" 2>/dev/null || true
+fi
+```
+
+If `has_triage=false`, inference returns empty, or `gh issue edit` fails, skip and continue without blocking the `import-issue` workflow.
+
 ## Phase 2: `implement-task`
 
 Goal: narrow the Issue milestone from a release line to a concrete version when implementation starts.

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

@@ -44,6 +44,18 @@ gh api "repos/$upstream_repo/milestones?state=open&per_page=100" \
 
 Milestone 设置属于 `has_triage` 权限范围；如果调用方检测到 `has_triage=false`，则省略 `--milestone` 并继续。
 
+### `import-issue` 调用时的兜底
+
+`import-issue` 导入既有 Issue 时，若 Issue 当前 milestone 为空，按上述优先级推断版本线（含 `General Backlog` 回退）。命中非空版本线后，回写到远端 Issue：
+
+```bash
+if [ "$has_triage" = "true" ]; then
+  gh issue edit {issue-number} -R "$upstream_repo" --milestone "{version}" 2>/dev/null || true
+fi
+```
+
+如果 `has_triage=false`、推断结果为空、或 `gh issue edit` 失败，跳过并继续，不阻断 `import-issue` 工作流。
+
 ## 阶段 2：`implement-task`
 
 目标：开始开发时，把 Issue milestone 从版本线收窄到具体版本。

package/templates/.agents/rules/testing-discipline.en.md

@@ -38,3 +38,47 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 - **Over-mocking**: Stub only real boundaries such as network, filesystem, time, or randomness; do not mock the logic of the unit under test, or the test only proves that the mock followed the script.
 - **Testing implementation details**: Prefer assertions on public APIs, artifacts, state changes, or error results; avoid assertions on private functions, internal call order, or temporary data structures.
 - **Insufficient assertions**: Assertions must pin down concrete expected values; do not replace checks on key fields, counts, and boundaries with "does not throw" or "result exists".
+
+## Coverage positioning (informational layer)
+
+> CI emits coverage via `node --test --experimental-test-coverage` as a hint about "which files are weakly tested". It is **not a merge gate**.
+
+### Local run
+
+```bash
+npm run test:coverage
+```
+
+The tail of stdout prints per-file line / branch / function coverage and the uncovered line numbers.
+
+### CI display
+
+`.github/workflows/unit-tests.yml` writes the coverage block into the GitHub Actions step summary on the ubuntu-latest shard (visible on the PR Checks page). Windows / macOS shards do not duplicate this output.
+
+The Codecov badge at the top of the README is generated by Codecov after `.github/workflows/unit-tests.yml` uploads `coverage.lcov` from the ubuntu-latest shard.
+
+### Boundaries
+
+- **No percentage thresholds**: Threshold flags such as `--test-coverage-lines/branches/functions` are forbidden. Goodhart's law reminds us that once coverage becomes a metric, developers write "coverage-friendly but behavior-weak" tests.
+- **Third-party services for the badge only**: Codecov hosts the README coverage badge, but the root `codecov.yml` explicitly disables its project/patch status checks and PR comments — Codecov only displays a number here and does not participate in merge decisions. Do not integrate other services such as coveralls.
+- **No tier split**: Coverage is currently emitted only for the full `test` tier; smoke / core tier coverage has no independent value.
+- **Does not block PRs**: The CI step uses `continue-on-error: true`, so a failed coverage collection does not affect merges.
+
+### Where New Tests Go
+
+The test directory determines which npm script runs a test file:
+
+- `tests/unit/<module>/`: fast structural or pure-function tests; does not spawn the real CLI process or depend on external tools, suitable for `test:smoke`.
+- `tests/integration/<module>/`: combines multiple modules, runs CLI subprocesses, touches temporary filesystems, or verifies template sync flows while staying stable and reasonably fast, suitable for `test:core`.
+- `tests/e2e/<module>/`: slower contract, platform-sync, packaged-output, cross-process, or end-to-end workflow tests, run only by full `npm test`.
+
+Modules remain as second-level directories such as `cli`, `core`, `scripts`, and `templates`. Shared helpers and fixtures stay in `tests/helpers/`, `tests/helpers.ts`, and `tests/fixtures/`; do not place them under a tier.
+
+### Relation to "test tier coverage"
+
+Distinguish two concepts:
+
+- **Test tier coverage** (`tests/unit/core/test-tier-coverage.test.ts` checks test directory placement and npm script tier mapping): governs "which test files belong to which tier" and is orthogonal to source-line coverage.
+- **Source-line coverage** (this section): governs "which lines of production source are exercised by tests".
+
+The two serve different purposes and should not substitute for each other.

package/templates/.agents/rules/testing-discipline.zh-CN.md

@@ -38,3 +38,47 @@ assert.match(content, /^name: implement-task$/m);    // 正向断言已足够
 - **mock 过度**：只在网络、文件系统、时间、随机数等真实边界打桩；不要 mock 被测对象自身逻辑，否则测试只验证 mock 是否按预设运行。
 - **测试实现细节**：优先断言公开接口、产物、状态变化或错误结果；避免断言私有函数、内部调用顺序、临时数据结构。
 - **断言不充分**：断言必须锁定具体期望值；不要用"只要不抛异常""结果存在即可"替代对关键字段、数量和边界的验证。
+
+## 覆盖率定位（信息层）
+
+> CI 中通过 `node --test --experimental-test-coverage` 输出覆盖率，仅作为"哪些文件被测试薄弱"的提示，**不作为 merge gate**。
+
+### 本地运行
+
+```bash
+npm run test:coverage
+```
+
+stdout 末尾会打印按文件粒度的行 / 分支 / 函数覆盖率以及未覆盖行号。
+
+### CI 展示
+
+`.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上把覆盖率块写入 GitHub Actions 的 step summary（PR Checks 页可见）。Windows / macOS 分片不重复输出。
+
+README 顶部的 Codecov 徽章由 `.github/workflows/unit-tests.yml` 在 ubuntu-latest 分片上传 `coverage.lcov` 后由 Codecov 生成。
+
+### 边界
+
+- **不设置百分比阈值**：`--test-coverage-lines/branches/functions` 等阈值参数禁止加入；Goodhart's law 提醒我们一旦把覆盖率作为指标，开发者会写"覆盖率友好但行为弱"的测试。
+- **第三方服务仅用于徽章**：已接入 Codecov 托管 README 覆盖率徽章，但通过根 `codecov.yml` 显式关闭其 project/patch status check 与 PR 评论——Codecov 在本项目只展示数字，不参与 merge 决策。不接入 coveralls 等其他服务。
+- **不区分 tier**：当前只对 full `test` tier 输出覆盖率；smoke / core tier 的覆盖率没有独立价值。
+- **不阻塞 PR**：CI 步骤 `continue-on-error: true`，即便覆盖率采集失败也不影响 merge。
+
+### 新测试该放哪一层
+
+测试文件放入哪一层决定它会被哪些 npm script 自动执行：
+
+- `tests/unit/<module>/`：快速、结构性或纯函数类测试；不启动真实 CLI 子进程，不依赖外部工具，适合 `test:smoke`。
+- `tests/integration/<module>/`：会组合多个模块、运行 CLI 子进程、触达临时文件系统或验证模板同步流程，但仍应保持稳定和相对快速，适合 `test:core`。
+- `tests/e2e/<module>/`：较慢的契约、平台同步、打包产物、跨进程或端到端流程测试，只在完整 `npm test` 中运行。
+
+模块继续作为第二级目录（如 `cli`、`core`、`scripts`、`templates`）。共享 helper 和 fixtures 保持在 `tests/helpers/`、`tests/helpers.ts`、`tests/fixtures/`，不要放入任一 tier。
+
+### 与"测试 tier 覆盖"的关系
+
+注意区分两个概念：
+
+- **测试 tier 覆盖**（`tests/unit/core/test-tier-coverage.test.ts` 校验测试文件目录归属与 npm script tier 映射）：管的是"哪些测试文件被纳入哪一 tier"，与代码行覆盖率正交。
+- **代码行覆盖率**（本节）：管的是"业务源码哪些行被测试触达"。
+
+两者目的不同，不要相互替代。

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

@@ -13,6 +13,20 @@ description: "Analyze a task and produce a requirements document"
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
 
+## Step 0: State Check (pre-execution hard gate)
+
+After loading workflow / skill / rules instructions, and before any task-state judgment or user-visible conclusion, run the state check first. Reading instruction files does not count as an external-state action or conclusion.
+
+Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
+
+```bash
+git status -s
+ls -la .agents/workspace/active/{task-id}/
+tail .agents/workspace/active/{task-id}/task.md
+```
+
+Before the state check is complete, do not make external-state assertions such as "the code is unchanged", "tests passed", or "there are no other references", including in reasoning. This gate is only a structural floor; evidence pairing and authenticity still require the report template and review discipline.
+
 ## Steps
 
 ### 1. Verify Prerequisites
@@ -72,6 +86,10 @@ Create `.agents/workspace/active/{task-id}/{analysis-artifact}`.
 - **Analysis round**: Round {analysis-round}
 - **Artifact file**: `{analysis-artifact}`
 
+## State Check
+
+> Paste the raw Step 0 state-check command output; each command starts with `$ `.
+
 ## Requirement Source
 
 **Source type**: {User description / Issue / Code Scanning / Dependabot / Other}
@@ -118,6 +136,14 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - Record the analysis artifact for this round: `{analysis-artifact}` (Round `{analysis-round}`)
 - If the task template contains a `## Analysis` section, update it to link to `{analysis-artifact}`
 - Mark requirement-analysis as complete in workflow progress and include the actual round when the task template supports it
+- Before appending the workflow Activity Log entry, re-estimate `priority` based on the analysis findings (business impact, risks, dependencies, blockers). If the re-estimated value differs from the current value in `task.md`:
+  - Overwrite the `priority` field in frontmatter with the new value
+  - Prepend an Activity Log entry recording the transition (placed before the `Requirement Analysis (Round N)` entry):
+    ```
+    - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analysis Re-estimate** by {agent} — priority {old} → {new} (rationale: {short basis grounded in this analysis})
+    ```
+  Both entries may share the same timestamp; ordering is conveyed by list position only.
+  If the re-estimated value matches the current value, skip the Re-estimate entry. The Flow A sync that follows reads the possibly updated frontmatter and propagates the new value to the Issue automatically.
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):
   ```
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-artifact}

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

@@ -13,6 +13,20 @@ description: "分析任务并输出需求分析文档"
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
 
+## 第 0 步：状态核对（执行前硬约束）
+
+在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
+
+运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+
+```bash
+git status -s
+ls -la .agents/workspace/active/{task-id}/
+tail .agents/workspace/active/{task-id}/task.md
+```
+
+状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。
+
 ## 执行步骤
 
 ### 1. 验证前置条件
@@ -72,6 +86,10 @@ description: "分析任务并输出需求分析文档"
 - **分析轮次**：Round {analysis-round}
 - **产物文件**：`{analysis-artifact}`
 
+## 状态核对
+
+> 粘贴第 0 步状态核对命令原文；每条命令以 `$ ` 开头。
+
 ## 需求来源
 
 **来源类型**：{用户描述 / Issue / Code Scanning / Dependabot / 其他}
@@ -118,6 +136,14 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 记录本轮分析产物：`{analysis-artifact}`（Round `{analysis-round}`）
 - 如任务模板包含 `## 分析` 段落，更新为指向 `{analysis-artifact}` 的链接
 - 在工作流进度中标记 requirement-analysis 为已完成，并注明实际轮次（如果任务模板支持）
+- 在追加工作流 Activity Log 条目之前，基于分析结果（业务影响、风险、依赖、阻塞条件）重估 `priority`。若重估值与 `task.md` 当前值不一致：
+  - 用新值覆盖 frontmatter 的 `priority` 字段
+  - 在 `Requirement Analysis (Round N)` 条目之前追加一条转移记录：
+    ```
+    - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analysis Re-estimate** by {agent} — priority {old} → {new} (rationale: {基于本轮分析的简短依据})
+    ```
+  两条条目可共用同一时间戳，顺序仅通过列表位置表达。
+  若重估值与当前值一致，跳过 Re-estimate 条目。后续 Flow A 同步会读取可能更新过的 frontmatter，并自动把新值同步到 Issue。
 - **追加**到 `## Activity Log`（不要覆盖之前的记录）：
   ```
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-artifact}

package/templates/.agents/skills/analyze-task/config/verify.en.json

@@ -0,0 +1,51 @@
+{
+  "skill": "analyze-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "agent_infra_version",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "requirement-analysis"
+    },
+    "artifact": {
+      "file_pattern": "analysis.md|analysis-r{N}.md",
+      "required_sections": [
+        "Requirement Source",
+        "Requirement Understanding",
+        "Related Files",
+        "Impact Assessment",
+        "Technical Risks",
+        "Effort and Complexity Assessment",
+        "State Check"
+      ],
+      "freshness_minutes": 30,
+      "required_patterns": [
+        "^\\$ "
+      ]
+    },
+    "activity-log": {
+      "expected_action_pattern": "Requirement Analysis \\(Round \\d+\\)",
+      "freshness_minutes": 30
+    },
+    "platform-sync": {
+      "when": "issue_number_exists",
+      "expected_status_label": "status: pending-design-work",
+      "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
+      "verify_comment_content": true,
+      "verify_task_comment_content": true,
+      "verify_issue_type": true,
+      "verify_issue_fields": false,
+      "verify_milestone": true,
+      "expected_status_label_key": "pendingDesignWork",
+      "expected_comment_marker_key": "artifact"
+    }
+  }
+}

package/templates/.agents/skills/analyze-task/config/{verify.json → verify.zh-CN.json}

@@ -23,9 +23,13 @@
         "相关文件",
         "影响评估",
         "技术风险",
-        "工作量和复杂度评估"
+        "工作量和复杂度评估",
+        "状态核对"
       ],
-      "freshness_minutes": 30
+      "freshness_minutes": 30,
+      "required_patterns": [
+        "^\\$ "
+      ]
     },
     "activity-log": {
       "expected_action_pattern": "Requirement Analysis \\(Round \\d+\\)",

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

@@ -12,6 +12,20 @@ description: "Mark a task as completed and archive it"
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
 
+## Step 0: State Check (pre-execution hard gate)
+
+After loading workflow / skill / rules instructions, and before any task-state judgment or user-visible conclusion, run the state check first. Reading instruction files does not count as an external-state action or conclusion.
+
+Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
+
+```bash
+git status -s
+ls -la .agents/workspace/active/{task-id}/
+tail .agents/workspace/active/{task-id}/task.md
+```
+
+Before the state check is complete, do not make external-state assertions such as "the code is unchanged", "tests passed", or "there are no other references", including in reasoning. This gate is only a structural floor; evidence pairing and authenticity still require the report template and review discipline.
+
 ## Steps
 
 ### 1. Verify Task Exists
@@ -64,6 +78,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `completed_at`: {current timestamp}
 - `updated_at`: {current timestamp}
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
+- Add or update the `## State Check` section with the raw Step 0 audit command output, including `$ ` prompt lines, before `## Activity Log`
 - Mark all workflow steps as complete
 - Verify and check off all items in `## Completion Checklist` (change `- [ ]` to `- [x]`)
 - **Append** to `## Activity Log` (do NOT overwrite previous entries):

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

@@ -12,6 +12,20 @@ description: "标记任务完成并归档"
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
 
+## 第 0 步：状态核对（执行前硬约束）
+
+在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
+
+运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+
+```bash
+git status -s
+ls -la .agents/workspace/active/{task-id}/
+tail .agents/workspace/active/{task-id}/task.md
+```
+
+状态核对完成前，禁止任何关于外部状态的断言（例如“代码没变”“测试已通过”“没有其他引用”），包括思考阶段。本门禁只提供结构下限；逐条证据配对和真实性仍需按报告模板与审查要求核对。
+
 ## 执行步骤
 
 ### 1. 验证任务存在
@@ -64,6 +78,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `completed_at`：{当前时间戳}
 - `updated_at`：{当前时间戳}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
+- 新增或更新 `## 状态核对` 段，粘贴第 0 步审计命令原文（含 `$ ` 前缀行），放在 `## 活动日志` 之前
 - 标记所有工作流步骤为已完成
 - 逐项验证并勾选 `## 完成检查清单` 中的所有条目（将 `- [ ]` 改为 `- [x]`）
 - **追加**到 `## Activity Log`（不要覆盖之前的记录）：

package/templates/.agents/skills/complete-task/config/{verify.json → verify.en.json}

@@ -33,6 +33,16 @@
       "verify_issue_fields": false,
       "verify_milestone": true,
       "expected_comment_marker_key": "summary"
+    },
+    "artifact": {
+      "file_pattern": "task.md",
+      "required_sections": [
+        "State Check"
+      ],
+      "required_patterns": [
+        "^\\$ "
+      ],
+      "freshness_minutes": 30
     }
   }
 }

package/templates/.agents/skills/complete-task/config/verify.zh-CN.json

@@ -0,0 +1,48 @@
+{
+  "skill": "complete-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "agent_infra_version",
+        "current_step",
+        "assigned_to",
+        "completed_at"
+      ],
+      "expected_status": "completed",
+      "require_completed_at": true
+    },
+    "activity-log": {
+      "expected_action_pattern": "Completed",
+      "freshness_minutes": 30
+    },
+    "completion-checklist": {
+      "require_all_checked": true
+    },
+    "platform-sync": {
+      "when": "issue_number_exists",
+      "expected_comment_marker": "<!-- sync-issue:{task-id}:summary -->",
+      "verify_task_comment_content": true,
+      "sync_checked_requirements": true,
+      "verify_issue_type": true,
+      "verify_issue_fields": false,
+      "verify_milestone": true,
+      "expected_comment_marker_key": "summary"
+    },
+    "artifact": {
+      "file_pattern": "task.md",
+      "required_sections": [
+        "状态核对"
+      ],
+      "required_patterns": [
+        "^\\$ "
+      ],
+      "freshness_minutes": 30
+    }
+  }
+}

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

@@ -116,6 +116,8 @@ The rule's content is determined by the configured code platform:
 - A platform that supports Issue creation: contains the full flow for auth detection, template detection, label/type/milestone inference, the create-Issue call, and writing back to `task.md`
 - Custom or empty platforms (no platform-specific variant provided): the rule body is a no-op notice, and this step is skipped entirely
 
+> **Hard constraint**: the milestone sub-step in `.agents/rules/create-issue.md` §4 is mandatory; missing it fails the step 5 gate (`verify_milestone: true`) and aborts create-task.
+
 Handle the result:
 - Rule successfully created the Issue: `issue_number` has been written back to task.md per the rule; continue by reading `.agents/rules/issue-sync.md`, completing upstream repository and permission detection, then sync the task comment and set `status: waiting-for-triage` by rule
 - Rule failed (auth / network / template parse / etc.): do not roll back task.md; do NOT append an extra Activity Log entry; follow "Scenario C: Issue creation failed" output to surface `error_code` and `error_message` to the user so they can decide whether to retry manually or write `issue_number` later