@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/verification-types.ts

@@ -1,3 +1,18 @@
+import type fs from 'node:fs';
+
+export type VerificationShared = {
+  repoRoot: string;
+  loadTask: (taskDir: string) => { ok: true; content: string; metadata: Record<string, string> } | { ok: false; message: string };
+  getCheckedRequirements: (content: string) => string[];
+  normalizeContent: (text: unknown) => string;
+  isBlank: (value: unknown) => boolean;
+  escapeRegExp: (value: string) => string;
+  passResult: (type: string, message: string, warnings?: string[]) => VerificationCheckResult;
+  failResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
+  blockedResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
+  safeStat: (filePath: string) => fs.Stats | null;
+};
+
 type VerificationStatus = 'pass' | 'fail' | 'blocked';
 type VerificationCheckResult = {
   type: string;

package/lib/task/verification.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 // checks are provided by typed domain modules without a stdout protocol.
 import { verifyInProcess } from './verification-engine.ts';
 
-import { parseArtifactName } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import type { ArtifactFamily } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { TaskWorkspaceState } from './resolve-ref.ts';

package/lib/task/workflow-command.ts

@@ -0,0 +1,17 @@
+export const TASK_WORKFLOW_COMMANDS = Object.freeze({
+  'artifact-inspect': ['task-artifact', 'inspect'],
+  'artifact-init': ['task-artifact', 'init'],
+  'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+  'review-finalize-summary': ['task-review', 'finalize-summary'],
+  event: ['task-event', null],
+  'ledger-finding-response': ['task-ledger', 'finding-respond'],
+  'ledger-finding-review': ['task-ledger', 'finding-review'],
+  'ledger-finding-upsert': ['task-ledger', 'finding-upsert'],
+  'decision-next-id': ['task-ledger', 'decision-next-id'],
+  'decision-upsert': ['task-ledger', 'decision-upsert'],
+  'invalidation-reconcile': ['task-invalidation', 'reconcile'],
+  'warning-add': ['task-warning', 'add']
+} as const);
+export type TaskWorkflowOperation = keyof typeof TASK_WORKFLOW_COMMANDS;
+export const TASK_WORKFLOW_OPERATIONS = Object.freeze(Object.keys(TASK_WORKFLOW_COMMANDS) as TaskWorkflowOperation[]);
+export type WorkflowCommand = typeof TASK_WORKFLOW_COMMANDS[TaskWorkflowOperation][0];

package/lib/task/workflow-warning-intents.ts

@@ -52,17 +52,6 @@ function nextWarningId(rows: readonly WorkflowWarning[]): string {
   return `WW-${max + 1}`;
 }
 
-function validateRows(rows: readonly WorkflowWarning[]): { code: string; message: string } | null {
-  const ids = new Set<string>();
-  for (const row of rows) {
-    if (!/^WW-[1-9]\d*$/.test(row.id)) return { code: 'WARNING_ID_INVALID', message: `warning id '${row.id}' is invalid` };
-    if (ids.has(row.id)) return { code: 'WARNING_DUPLICATE_ID', message: `duplicate warning id '${row.id}'` };
-    ids.add(row.id);
-    if (!WORKFLOW_WARNING_SEVERITIES.has(row.severity) || !WORKFLOW_WARNING_STATUSES.has(row.status)) return { code: 'WARNING_DOCUMENT_INVALID', message: `warning '${row.id}' has invalid severity or status` };
-  }
-  return null;
-}
-
 function sectionMutation(content: string): TaskMutation[] {
   if (/^##\s+(工作流告警|Workflow Warnings)\s*$/m.test(content)) return [];
   const english = /^##\s+Activity Log\s*$/m.test(content);
@@ -98,8 +87,6 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
     const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : 'WARNING_DOCUMENT_INVALID';
     return failed(intent, code, error instanceof Error ? error.message : String(error), resolved.taskId);
   }
-  const invalid = validateRows(rows);
-  if (invalid) return failed(intent, invalid.code, invalid.message, resolved.taskId);
   if (intent.kind === 'list') {
     if (intent.status && !WORKFLOW_WARNING_STATUSES.has(intent.status)) return failed(intent, 'WARNING_PAYLOAD_INVALID', 'warning status is invalid', resolved.taskId);
     const warnings = rows.filter((row) => !intent.status || row.status === intent.status);

package/lib/task/workflow-warnings.ts

@@ -4,6 +4,7 @@ const WORKFLOW_WARNING_HEADINGS = ['工作流告警', 'Workflow Warnings'];
 const WORKFLOW_WARNING_STATUSES = new Set(['open', 'resolved', 'ignored']);
 const WORKFLOW_WARNING_SEVERITIES = new Set(['IMPORTANT', 'ACTION_REQUIRED']);
 const WORKFLOW_WARNING_COLUMNS = ['id', 'time', 'step', 'severity', 'code', 'status', 'target', 'message', 'action', 'resolved_at', 'resolution'] as const;
+const WARNING_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
 
 type WorkflowWarning = {
   id: string;
@@ -19,14 +20,32 @@ type WorkflowWarning = {
   resolution: string;
 };
 
-/** Parses workflow warning rows and fails closed on malformed table structure. */
+/** Parses warning structure and lifecycle fields using one contract for all readers. */
 function parseWorkflowWarnings(content: string): WorkflowWarning[] {
   const table = parseTable(content, { sectionAliases: WORKFLOW_WARNING_HEADINGS, columns: WORKFLOW_WARNING_COLUMNS });
-  return table?.rows.map(({ values }) => ({
+  const warnings = table?.rows.map(({ values }) => ({
     id: values.id!, time: values.time!, step: values.step!, severity: values.severity!,
     code: values.code!, status: values.status!, target: values.target!, message: values.message!,
     action: values.action!, resolvedAt: values.resolved_at!, resolution: values.resolution!
   })) ?? [];
+  const errors: { code: string; message: string }[] = [];
+  const invalid = (message: string, code = 'WARNING_DOCUMENT_INVALID') => errors.push({ code, message });
+  for (const warning of warnings) {
+    const { id, time, severity, status, action, resolvedAt, resolution } = warning;
+    if (!/^WW-[1-9]\d*$/.test(id)) invalid(`${id || '(empty id)'}: invalid id`, 'WARNING_ID_INVALID');
+    if (!WARNING_TIME_PATTERN.test(time)) invalid(`${id}: invalid time '${time}'`);
+    for (const field of ['step', 'code', 'target', 'message'] as const) {
+      if (!warning[field].trim()) invalid(`${id}: ${field} is required`);
+    }
+    if (!WORKFLOW_WARNING_SEVERITIES.has(severity)) invalid(`${id}: illegal severity '${severity}'`);
+    if (!WORKFLOW_WARNING_STATUSES.has(status)) invalid(`${id}: illegal status '${status}'`);
+    if (status === 'open' && !action.trim()) invalid(`${id}: open warning requires action`);
+    if ((status === 'resolved' || status === 'ignored') && (!resolvedAt.trim() || !resolution.trim())) {
+      invalid(`${id}: ${status} warning requires resolved_at and resolution`);
+    }
+  }
+  if (errors.length) throw Object.assign(new Error(errors.map((error) => error.message).join('; ')), { code: errors[0]!.code });
+  return warnings;
 }
 
 function getOpenWorkflowWarnings(content: string): WorkflowWarning[] {

package/lib/update.ts

@@ -119,6 +119,12 @@ async function cmdSync(): Promise<void> {
     replacements
   );
   ok('Updated .agents/scripts/lib/agent-infra-package.js');
+  renderFile(
+    path.join(templateDir, '.agents', 'scripts', 'package.json'),
+    path.join('.agents', 'scripts', 'package.json'),
+    replacements
+  );
+  ok('Updated .agents/scripts/package.json');
   const added = {
     managed: workflowPlan.projectAssets.registry.managed.filter(
       (entry) => !currentRegistry.managed.includes(entry)

package/lib/version.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs';
-import semver from 'semver';
 
 const packageJsonUrl = [
   new URL('../package.json', import.meta.url),
@@ -13,22 +12,9 @@ if (!packageJsonUrl) {
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const LEGACY_COMPATIBILITY_CUTOFF_VERSION = '1.0.0';
 
 function isValidAgentInfraVersion(value: unknown): value is string {
   return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
 
-function isLegacyCompatibilityEnabled(runtimeVersion = VERSION): boolean {
-  const normalized = runtimeVersion.startsWith('v') ? runtimeVersion.slice(1) : runtimeVersion;
-  const parsed = semver.valid(normalized);
-  return parsed !== null && semver.lt(parsed, LEGACY_COMPATIBILITY_CUTOFF_VERSION);
-}
-
-function legacyCompatibilityError(resource: string, runtimeVersion = VERSION): Error & { code: string } {
-  return Object.assign(new Error(
-    `PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: ${resource} requires migration to the current schema before v${LEGACY_COMPATIBILITY_CUTOFF_VERSION} runtime ${runtimeVersion}`
-  ), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
-}
-
-export { LEGACY_COMPATIBILITY_CUTOFF_VERSION, VERSION, isLegacyCompatibilityEnabled, isValidAgentInfraVersion, legacyCompatibilityError };
+export { VERSION, isValidAgentInfraVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.14",
+  "version": "0.10.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -26,12 +26,13 @@
   "bin": {
     "agent-infra": "./dist/bin/cli.js",
     "ai": "./dist/bin/cli.js",
-    "agent-infra-internal": "./dist/bin/internal-cli.js"
+    "agent-infra-internal": "./bin/internal-cli.sh"
   },
   "files": [
     "dist/",
     "!dist/**/*.map",
     "bin/cli.ts",
+    "bin/internal-cli.sh",
     "lib/",
     "runtime/",
     "templates/"
@@ -54,7 +55,7 @@
     "@clack/prompts": "1.7.0",
     "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
-    "fs-ext-extra-prebuilt": "2.2.13",
+    "fs-native-extensions": "1.5.1",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
     "smol-toml": "^1.6.1",
@@ -67,6 +68,8 @@
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
     "test:smoke": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\"",
     "test:smoke:fast": "node scripts/run-tests.js --skip-build \"tests/unit/**/*.test.ts\"",
+    "test:platform-smoke": "node scripts/run-tests.js \"tests/integration/platform-smoke/**/*.test.ts\"",
+    "test:platform-smoke:fast": "node scripts/run-tests.js --skip-build \"tests/integration/platform-smoke/**/*.test.ts\"",
     "test:core": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
     "test:integration": "node scripts/run-tests.js \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
@@ -85,8 +88,5 @@
   },
   "overrides": {
     "axios": "1.18.1"
-  },
-  "allowScripts": {
-    "fs-ext-extra-prebuilt@2.2.13": true
   }
 }

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -16,7 +16,7 @@ function internalCliInvocation(args) {
   return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
 }
 
-function findCapabilityToken(value, depth = 0) {
+function findCapabilityRef(value, depth = 0) {
   if (depth > 5 || value == null) return '';
   if (typeof value === 'string') {
     const match = /agent-infra-codex-capability:([A-Za-z0-9_-]{20,})/.exec(value);
@@ -24,14 +24,14 @@ function findCapabilityToken(value, depth = 0) {
   }
   if (Array.isArray(value)) {
     for (const entry of value) {
-      const found = findCapabilityToken(entry, depth + 1);
+      const found = findCapabilityRef(entry, depth + 1);
       if (found) return found;
     }
     return '';
   }
   if (typeof value === 'object') {
     for (const entry of Object.values(value)) {
-      const found = findCapabilityToken(entry, depth + 1);
+      const found = findCapabilityRef(entry, depth + 1);
       if (found) return found;
     }
   }
@@ -77,11 +77,11 @@ process.stdin.on('end', () => {
       process.exit(1);
     }
     const managedAgent = /^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''));
-    const capabilityToken = hook === 'post-tool' ? findCapabilityToken(toolResponse) : '';
+    const capabilityRef = hook === 'post-tool' ? findCapabilityRef(toolResponse) : '';
     const parentReconcile = hook === 'post-tool'
       && toolName === 'collaborationwait_agent'
       && toolResponse.timed_out !== true;
-    if (!managedAgent && !parentReconcile && !capabilityToken) process.exit(0);
+    if (!managedAgent && !parentReconcile && !capabilityRef) process.exit(0);
     const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
     const normalized = {
       sessionId: String(event.session_id || ''),
@@ -96,7 +96,7 @@ process.stdin.on('end', () => {
       taskName: String(toolInput.task_name || ''),
       transcriptPath: String(event.transcript_path || '')
     };
-    if (capabilityToken) normalized.capabilityToken = capabilityToken;
+    if (capabilityRef) normalized.capabilityRef = capabilityRef;
     const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
     try {
       const { command, commandArgs, shell } = internalCliInvocation(args);

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

@@ -9,6 +9,6 @@ agent-infra-internal platform-issue create {task-id} --agent {standard-agent-tok
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 
-The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `issue_number` binding.
+The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `platform_issue_identity` binding.
 
 `planned|applied|no-op|degraded` exit 0, `failed` exits 1, and `blocked` exits 2. Callers must not fall back to direct platform CLI or GraphQL orchestration.

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

@@ -8,7 +8,7 @@
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
 ```
 
-命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `issue_number`。
+命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `platform_issue_identity`。
 
 创建后的初始元数据使用同一适配层同步：
 

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

@@ -12,19 +12,21 @@
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
-`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue number and reads only registered Issue markers, with no PR source.
+`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue token and reads only registered Issue markers, with no PR source.
 
 Comments use `platform-comment`; Issue resources use `platform-issue`:
 
 ```bash
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 
 The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.
 
+Task content over the platform comment byte limit is not uploaded; the core returns a skipped operation with `COMMENT_PAYLOAD_TOO_LARGE`. The local task file is unchanged, and platform verification skips the task marker/content check for the same oversized input.
+
 PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.
 
 `planned|applied|no-op|degraded` exit 0; `failed` exits 1; `blocked` exits 2.

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

@@ -16,7 +16,7 @@
 
 `prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
 
-`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 编号并只读注册的 Issue marker，不新增 PR 来源。
+`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 原始 token 并只读注册的 Issue marker，不新增 PR 来源。
 
 ## 平台 intent
 
@@ -24,7 +24,7 @@
 
 ```bash
 agent-infra-internal platform-context resolve [--cwd <path>]
-agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
   --kind task|artifact|summary|cancel --agent {standard-agent-token} \
@@ -33,6 +33,7 @@ agent-infra-internal platform-comment sync <task-ref> \
 
 - `applied|no-op|degraded` → exit 0；`failed` → exit 1；`blocked` → exit 2。
 - task 评论保持 `<details>` frontmatter 可逆格式；artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- task 内容超过平台评论字节上限时不上传，返回 `COMMENT_PAYLOAD_TOO_LARGE` 的 skipped 操作；本地 task 文件保持不变，platform verification 同样跳过 task marker/content 检查。
 - 相同 intent 重放必须收敛为 `no-op`；重复 marker 返回 `COMMENT_MARKER_CONFLICT` 且不写入。
 - 外部贡献者锁定统一使用 `platform-comment owner`；不同作者且无 triage 时返回 `COMMENT_OWNER_CONFLICT`。
 
@@ -59,7 +60,7 @@ agent-infra-internal task-warning {task-id} add \
 ```bash
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -1,57 +1,64 @@
-# General Rule - Model-Driven Local Artifact Repair
+# General Rule - Model-Driven Local Artifact Recovery
 
-This rule applies when `analyze-task`, `plan-task`, or `code-task` handles **the same controlled local artifact** before its completed event, and when `review-analysis`, `review-plan`, or `review-code` handles a finalizer failure for **the same controlled review artifact**. It does not apply to `task.md`, the ledger, receipts, source code, Git, platform resources, or lifecycle state.
+This rule covers the pre-completion gate for `analyze-task`, `plan-task`, and `code-task`, plus the summary finalizers for the three review skills. It handles one canonical artifact in the current task directory only. It does not authorize changes to `task.md`, ledgers, receipts, source code, Git, platform resources, or lifecycle state.
 
-## Pre-completion gate for analysis, plan, and code artifacts
+## Pre-completion gate
 
-- `analyze-task`, `plan-task`, and `code-task` must call `task-artifact ... finalize-local` before publishing a completed event; pass only that call's `artifactSha256` and `semanticDigest` to the completed event.
-- `finalize-local` does not modify the artifact or task state, but it writes a one-shot local provenance intent in the repository workspace. After `failed`, the model may make one minimal edit in the same artifact only when `repairable=true` and the diagnostic explicitly describes one provably safe structural operation (the current shared engine operations are `replace-line` and `insert-section`), then rerun the same call completely; count each byte-changing edit, up to 8.
-- The first repairable failure's semantic digest is retained in that intent; a later `passed` result must match the baseline, and the completed event must verify and atomically transition the same intent to `consumed` before writing `task.md` under the task lock. A consumption failure must not write the task; the consumed intent is durable and retryable, so no failure-prone post-write deletion is attempted. Do not replace a failed baseline with a newly computed digest or publish a completed event without the finalizer.
-- After `failed`, no progress, or a repeated diagnostic or fingerprint, do not publish a completed event. After `passed`, do not rescan or manually write summary data.
+- Run the applicable finalizer before a completed event; pass only that invocation's `artifactSha256` and `semanticDigest` to the event.
+- When artifact content is invalid, the finalizer returns a controlled `recovery` with a `recoveryId`, `candidatePath`, and baseline digests. The formal artifact remains unchanged until recovery commit.
+- After the mechanical safety gates pass, the model may edit only the returned `candidatePath`. After each byte-changing edit, rerun the complete finalizer with the same task, stage/family, artifact, and `--recovery-id`. Never edit the formal artifact directly and call it a candidate.
+- A successful finalizer commits through `finalize-ready → commit-started → passed`; completed events accept only matching `passed` final digests and consume the intent under the task lock.
+- Before `finalize-ready`, the recovery core seals the validated final bytes in the controlled `final.md`; later commit ignores the editable `candidate.md` and validates/publishes only that sealed snapshot, so a post-prepare candidate replacement cannot be published.
+- Candidate-only is a protocol authorization boundary, not OS isolation: a same-UID process with arbitrary host filesystem write access may tamper with recovery internals. Identity, fingerprint, and state checks detect such anomalies and fail closed, but the protocol does not claim an independent security principal or cross-platform isolation.
 
-## Authorization Boundary
+## Authorization boundary
 
-- The finalizer only reads facts, validates state, normalizes successful results, and performs atomic writes. It does not maintain a recoverable-error allowlist, infer repairability, or choose report content to delete.
-- The initial finalizer call is not counted as a repair attempt. Editing is allowed only after the mechanical safety gates pass and the model explicitly determines that the current problem can be solved by a minimal, explainable artifact change.
-- The model may edit only the one ordinary local artifact declared by the current skill, and the file must be inside the current task directory. It must not edit `task.md`, the review disagreement ledger, receipts, source code, other reports, or remote resources.
-- `changed=false`, an error code, or a format shape is diagnostic evidence, not automatic authorization. The model must judge each case using the complete diagnostic, artifact content, and context.
+- The finalizer and recovery core validate identity, state, permissions, stable reads, complete artifact semantics, and fingerprints. They do not infer repairability or expose a text-operation allow-list.
+- The model may edit only the one ordinary artifact declared by the current skill. It must not edit `task.md`, ledgers, receipts, source code, other reports, or remote resources.
+- `changed=false`, an error code, or a format shape is diagnostic evidence, not edit authorization. Stop on unproven human-decision semantics, concurrency, permission, I/O, identity, provenance, or unknown state.
 
-## Non-bypassable Mechanical Safety Gates
+## Non-bypassable mechanical gates
 
-Before every model edit, confirm that:
+Before every candidate edit, confirm that:
 
-1. the finalizer returned a failure and no artifact operation was committed;
-2. the task, stage, artifact, review round, identity, and provenance still match;
-3. the target is an ordinary file inside the current task directory, with no concurrency conflict, permission error, I/O uncertainty, or target replacement;
-4. the change does not alter human-decision semantics, decision-detail or ledger identity, and does not involve task state, receipts, Git, platform, or any other external side effect. A known and verifiable pending human decision may remain when the model proves the edit is unrelated to that decision.
+1. the finalizer failed with the same controlled recovery context and nothing formal was committed;
+2. task, family/stage, round, artifact, request/authority, and baseline fingerprints still match;
+3. `candidatePath` is the ordinary file generated by the recovery core and the formal target has not changed externally;
+4. the edit does not change human-decision semantics, detail or ledger identity, and introduces no other side effect.
 
-If any condition fails, stop immediately without invoking a model edit. The model cannot bypass these gates.
+If any condition fails, stop without editing or publishing a completed event.
 
-## Dynamic Convergence Loop
+## Durable recovery states
 
-1. Run the initial finalizer with the fixed task, stage, artifact, and orchestrated intent.
-2. On success, use that complete result for the existing completion gates; do not rescan the ledger or write summary fields manually.
-3. On failure with the safety gates passed, let the model read the structured diagnostic, current artifact, and required context, then decide whether to repair or stop. It must explain the scope and reason for the proposed change.
-4. If the model continues, perform one minimal edit to the artifact. Increment `repairAttempts` only when the file bytes actually change, then rerun the same finalizer intent completely.
-5. Re-run every safety check after each retry. A new, independent problem still limited to the same artifact may be offered to the model for another decision; the previous repairability decision must not be reused automatically.
-6. Stop immediately when the model cannot establish safety or identifies an environment, permission, concurrency, identity, provenance, unknown-state, uncertain human-decision semantics/details, or other non-local problem. A known human decision is not itself a stop condition.
-7. Stop when the diagnostic or artifact fingerprint repeats, no byte-level progress occurs, or the model cannot propose a verifiable minimal change.
-8. Allow at most 8 actual artifact edits per skill invocation as an emergency circuit breaker. This cap only prevents infinite loops and resource exhaustion; it is not a normal business stop condition and does not mean that at most eight problems may be repaired. Preserve the final structured diagnostic when the cap is reached.
+| State | Formal artifact | Allowed action |
+| --- | --- | --- |
+| `awaiting-recovery` | baseline `B` | Edit only controlled candidate `S`; rerun the same finalizer |
+| `finalize-ready` | `B` | Recovery core starts the commit under the task lock |
+| `commit-started` | `B` or final `F` | Reconcile only; retry, confirm, or restore from verified `B/F` fingerprints |
+| `passed` | `F` | Completed event validates the final digest and consumes the intent |
+| `consumed` | `F` | Cleanup may reclaim the controlled staging and backup |
+| `aborted` | verified restored `B` | Preserve diagnostics; never fabricate success |
 
-The repair count exists only in the in-memory context of the current skill invocation. Do not write it to `task.md`, the ledger, or a public receipt. Do not create different normal budgets by error code, skill, or problem type.
+The intent is current-only schema version 3. Legacy schemas fail closed; do not add migration, adapters, or dual writes. Candidate, baseline, and intent files live in controlled repo-local directories and use canonical recovery IDs, regular-file checks, stable reads, the task lock, and expected-value CAS. No cross-file atomicity is claimed; unknown combinations remain indeterminate and retain their evidence.
 
-## Shared Structural Engine
+## Dynamic convergence loop
 
-The report skeleton is created by `agent-infra-internal task-artifact {task-id} init --family {family} --artifact {artifact}`. The skeleton writes only identity, headings, and `artifact-section:{family}:{section-id}` markers; it does not represent semantic completion. The current skill must fill each slot with real content. When the finalizer returns one provably safe structural operation, use that result's SHA and semantic digest with `task-artifact {task-id} repair --family {family} --artifact {artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`. Repair executes only the one operation from the shared engine, does not write `task.md`, the ledger, receipts, Git, or platform resources, and must be followed by a complete rerun of the original finalizer.
+1. Run the finalizer with the fixed invocation.
+2. If it fails and the gates pass, read the structured diagnostic and `candidatePath`, then make one minimal, explainable candidate edit.
+3. Confirm byte-level progress and rerun every finalizer check with the same `--recovery-id`.
+4. Stop on repeated diagnostics or fingerprints, no byte progress, unknown recovery state, or the eight-edit limit for the current invocation. Do not publish a completed event or generate a cross-stage next step.
 
-## Completion Events and User Output
+## Shared entry points
 
-- After the final complete finalizer result succeeds, publish the review completed event using that same result's provenance, ledger state, verdict, and counts. Generate cross-stage next-step commands only when `stageStatus.canAdvance=true` and the verdict is Approved; when `canAdvance=false`, still record the result and route to same-stage revision/review.
-- On failure, model stop, lack of progress, repeated diagnostics, or the emergency cap, do not publish a completed event, advance the lifecycle, generate cross-stage commands, or fabricate an approval.
-- Stopping advancement does not discard review results. User output must show the artifact path, the last safely readable summary/findings, actual `repairAttempts`, the last structured diagnostic, and the stop reason.
-- If the summary cannot be safely parsed, show only the artifact path and the raw structured diagnostic; do not infer counts or add a conclusion, and state that lifecycle advancement stopped while the artifact remains available.
-- A stop path may only suggest rerunning the current review skill or handling the issue manually. It must not invoke cross-stage helpers such as `code-task` or `complete-task`.
+The current entry points are `task-artifact ... inspect|init|finalize-local` and `task-review ... finalize-summary`. Recovery retries use the `recoveryId` returned by the finalizer, for example:
 
-## Lifecycle Isolation
+```text
+agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact} --recovery-id {recovery-id}
+agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id}
+```
 
-`complete-task`, alert closing, task restoration, and other task-lifecycle/task-finalization entry points involve task state, receipts, remote results, or archival side effects and do not consume this rule. They retain their own hard-stop, same-intent retry, and unknown-state semantics.
+There is no `task-artifact repair`, `replace-line`, `insert-section`, or `repairable` authorization. The structural engine returns diagnostics and digests only; the current skill's gates and the model decide whether and how to edit the candidate.
+
+## Lifecycle isolation
+
+A completed event may legitimately modify `task.md`, but only after finalizer recovery is `passed` and digest, round, request, and authority all match. If authority consumption fails after the event write, retain the formal artifact and use the existing lifecycle recovery compensation; do not replay the completed write or roll back a passed artifact.

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

@@ -1,57 +1,64 @@
-# 通用规则 - 模型驱动的本地产物修复
+# 通用规则 - 模型驱动的本地产物恢复
 
-本规则适用于 `analyze-task`、`plan-task`、`code-task` 在 completed 事件前处理**同一个受控本地产物**，以及 `review-analysis`、`review-plan`、`review-code` 在 finalizer 失败后处理**同一个受控 review artifact** 的场景。它不适用于 task.md、账本、receipt、源码、Git、平台资源或生命周期状态。
+本规则适用于 `analyze-task`、`plan-task`、`code-task` 的本地产物完成前门禁，以及三个 review skill 的 summary finalizer。它只处理当前 task 目录内的一个 canonical artifact；不适用于 `task.md`、账本、receipt、源码、Git、平台资源或生命周期状态。
 
-## 分析、方案和代码产物完成前门禁
+## 完成前门禁
 
-- `analyze-task`、`plan-task` 和 `code-task` 必须在发布 completed 事件前调用 `task-artifact ... finalize-local`；只有同一次返回的 `artifactSha256` 和 `semanticDigest` 才能传给 completed 事件。
-- `finalize-local` 不修改产物或任务状态，但会在仓库工作区写入一次性的本地 provenance intent。返回 `failed` 时，只有 `repairable=true` 且诊断明确为一个可证明安全的结构操作（当前共享引擎操作为 `replace-line` 或 `insert-section`），模型才可在同一产物中执行一次最小编辑，然后完整重跑同一调用；每次实际字节修改计一次，最多 8 次。
-- 首次可修复失败的 semantic digest 会保存在该 intent 中；后续 `passed` 必须匹配该基线，completed event 还必须在任务锁内验证并在写 task.md 前原子转换为 `consumed` 状态。消费失败时不得写任务；转换后的 intent 是可重试的 durable 记录，成功写入后不再执行可能失败的后置删除。不得用重新计算的新摘要替换失败基线，也不得绕过 finalizer 直接发布 completed event。
-- 返回 `failed`、无进展、诊断或指纹重复时不得发布 completed 事件；返回 `passed` 后也不得重新扫描或手工补写摘要。
+- 完成事件前必须运行对应 finalizer；只有同一次返回的 `artifactSha256` 和 `semanticDigest` 才能传给 completed event。
+- finalizer 发现 artifact 内容错误时，返回受控 `recovery`（`recoveryId`、`candidatePath`、baseline 指纹）。正式 artifact 在 recovery commit 前必须保持不变。
+- 只有在机械安全门通过后，模型才可编辑返回的 `candidatePath`；每次实际字节变化后，用同一 task、stage/family、artifact 和 `--recovery-id` 完整重跑 finalizer。不得直接编辑正式 artifact 后假设它属于候选。
+- finalizer 通过后，recovery core 按 `finalize-ready → commit-started → passed` 提交候选；completed event 只接受匹配的 `passed`/final digest，并在任务锁内消费 intent。
+- `finalize-ready` 前 recovery core 会把已校验的最终字节封存为受控 `final.md`；后续 commit 忽略可编辑的 `candidate.md`，只校验并发布该封存快照，避免候选在准备后被替换。
+- candidate-only 是协议授权边界，不是操作系统隔离：拥有同一 UID 且可任意写入宿主文件系统的进程可能篡改 recovery 内部文件；协议会通过身份、指纹和状态校验发现异常并失败关闭，但不承诺独立权限主体或跨平台隔离。
 
 ## 授权边界
 
-- finalizer 只负责读取事实、校验状态、规范化成功结果和原子写入；它不维护可修复错误码白名单，不推断 repairability，也不自动选择要删除的报告内容。
-- 首次 finalizer 调用不计入修复次数。只有在机械安全门通过后，模型明确判断当前问题能通过最小、可解释的 artifact 修改解决时，才允许编辑。
-- 模型只能修改当前 skill 声明的一个普通本地产物，且该文件必须位于当前 task 目录。不得修改 task.md、审查分歧账本、receipt、源码、其他报告或远端资源。
-- `changed=false`、错误码或某个格式形状只是诊断事实，不是自动批准。模型必须结合完整诊断、artifact 内容和上下文逐例判断。
+- finalizer 和 recovery core 只校验身份、状态、权限、稳定读取、完整 artifact 语义和指纹；不根据错误码猜测“可修复”，也不提供文本操作白名单。
+- 模型只能修改当前 skill 声明的一个普通 artifact。不得修改 task.md、账本、receipt、源码、其他报告或远端资源。
+- `changed=false`、错误码和格式形状只是诊断事实，不是编辑授权。人工裁决、并发、权限、I/O、身份、provenance 或未知状态无法证明安全时，立即停止。
 
 ## 不可绕过的机械安全门
 
-在每次模型编辑前确认：
+每次编辑候选前确认：
 
-1. finalizer 返回失败，且没有已提交的 artifact operation；
-2. 任务、stage、artifact、review round、身份和 provenance 仍然一致；
-3. 目标是当前 task 目录内的普通文件，没有并发冲突、权限错误、I/O 不确定性或目标被替换；
-4. 不改变人工裁决语义、裁决详情或账本身份，也不涉及任务状态、receipt、Git、平台或其他外部副作用；已知且可核验的 pending 人工裁决可以保留，但模型必须证明本次修改与该裁决无关。
+1. finalizer 返回失败并提供同一 recovery context，且没有正式提交；
+2. task、family/stage、round、artifact、request/authority 和 baseline 指纹仍匹配；
+3. `candidatePath` 是 recovery core 生成的受控普通文件，formal target 没有外部变化；
+4. 修改不改变人工裁决语义、详情或账本身份，也不引入其他副作用。
 
-任一条件不满足，立即停止，不调用模型编辑。安全门不能被模型的语义判断绕过。
+任一条件不满足，停止，不编辑、不发布 completed。
 
-## 动态收敛循环
+## Durable recovery 状态
+
+| 状态 | formal artifact | 允许动作 |
+| --- | --- | --- |
+| `awaiting-recovery` | baseline `B` | 只编辑受控 candidate `S`，重跑同一 finalizer |
+| `finalize-ready` | `B` | recovery core 在锁内开始提交 |
+| `commit-started` | `B` 或 final `F` | 只允许 reconcile；按 `B/F` 指纹重试、确认或回滚 |
+| `passed` | `F` | completed event 校验 final digest 后消费 |
+| `consumed` | `F` | 可由中间产物清理流程回收受控 staging/backup |
+| `aborted` | 已确认恢复的 `B` | 只保留诊断，不得伪造成功 |
 
-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 个问题。达到上限时保留最后结构化诊断并停止。
+intent 使用 current-only schema version 3。旧 schema 直接失败关闭；不添加迁移、adapter 或双写。candidate、baseline 和 intent 位于 repo-local 受控目录，使用 canonical recovery ID、普通文件检查、stable read、task lock 和 expected-value CAS。跨文件不宣称原子性；未知组合返回 indeterminate 并保留现场。
+
+## 动态收敛循环
 
-修复次数只存在于当前 skill invocation 的内存上下文，不写入 task.md、ledger 或公共 receipt。不得按错误码、技能或问题类型设置不同的正常预算。
+1. 用固定 invocation 运行 finalizer。
+2. 失败且安全门通过时，读取结构化诊断和 `candidatePath`，只作一次最小、可解释的候选编辑。
+3. 确认字节变化后，使用同一 `--recovery-id` 完整重跑全部 finalizer 校验。
+4. 诊断或指纹重复、无字节进展、恢复状态未知或达到当前 invocation 的 8 次编辑上限时停止；不发布 completed，不生成跨阶段 next-step。
 
-## 共享结构引擎
+## 共享入口
 
-报告骨架由 `agent-infra-internal task-artifact {task-id} init --family {family} --artifact {artifact}` 创建。骨架只写身份、标题和 `artifact-section:{family}:{section-id}` marker，不代表语义完成；槽位必须由当前 skill 填入真实内容。finalizer 返回单一可证明结构操作时，使用同一返回值的 SHA 和 semantic digest 调用 `task-artifact {task-id} repair --family {family} --artifact {artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`。repair 只执行共享引擎给出的一个结构操作，不写 task.md、ledger、receipt、Git 或平台资源，之后必须完整重跑原 finalizer。
+`task-artifact ... inspect|init|finalize-local` 和 `task-review ... finalize-summary` 是当前入口。恢复重试使用 finalizer 返回的 `recoveryId`，例如：
 
-## 完成事件与用户输出
+```text
+agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact} --recovery-id {recovery-id}
+agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id}
+```
 
-- 最终一次完整 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。
+不再存在 `task-artifact repair`、`replace-line`、`insert-section` 或 `repairable` 授权。结构引擎只返回诊断和 digest；候选是否安全、如何修改以及何时停止由当前 skill 的机械门和模型逐例判断。
 
 ## 生命周期隔离
 
-`complete-task`、告警关闭、恢复任务和其他 task-lifecycle/task-finalization 入口涉及任务状态、receipt、远端结果或归档副作用，不消费本规则。它们继续使用各自的硬失败、同一 intent 重试和状态未知语义。
+completed event 合法地修改 task.md，但必须发生在 finalizer recovery 已 `passed` 且 digest、round、request/authority 全部匹配之后。若 event 写入后 authority 消费失败，保留正式 artifact，使用既有 lifecycle recovery compensation；不得重放 completed 写入或回滚已通过的 artifact。

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

@@ -43,6 +43,8 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 
 Complete each item below for this repository. Record the chosen behavior and its boundaries so contributors can select and validate tests consistently.
 
+When a project uses a cross-platform smoke boundary, keep real CLI, git, shell, environment-forwarding, and process-lifecycle tests outside the unit tier. Document which operating systems execute that boundary and keep structural tier checks separate from line coverage.
+
 ### 1. Test commands
 
 > TODO: Document the complete test command and any faster commands used during development.

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

@@ -43,6 +43,8 @@ assert.match(content, /^name: code-task$/m);         // 正向断言已足够
 
 请为本仓库填写以下各项，记录选定行为及其边界，以便贡献者一致地选择并验证测试。
 
+如果项目使用跨平台 smoke 边界，应将真实 CLI、git、shell、环境透传和进程生命周期测试放在 unit 层之外；记录该边界运行的操作系统，并将测试层级结构检查与代码行覆盖率分开。
+
 ### 1. 测试命令
 
 > TODO: 记录完整测试命令，以及开发期间使用的可选快速命令。