@fitlab-ai/agent-infra 0.8.4 → 0.9.0

package/lib/task/write.ts

@@ -0,0 +1,468 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { VERSION } from '../version.ts';
+import {
+  parseTypedTaskFrontmatter,
+  updateTaskFrontmatter
+} from './frontmatter.ts';
+import type { FrontmatterScalar } from './frontmatter.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import type {
+  ResolveTaskRefErrorCode,
+  TaskWorkspaceState
+} from './resolve-ref.ts';
+import { mutateTableRow, upsertSection } from './sections.ts';
+import type {
+  TableRowDeleteMutation,
+  TableRowUpsertMutation
+} from './sections.ts';
+
+type FrontmatterMutation = {
+  kind: 'frontmatter';
+  set: Readonly<Record<string, FrontmatterScalar>>;
+  remove?: readonly string[];
+};
+
+type SectionMutation = {
+  kind: 'section';
+  aliases: readonly string[];
+  heading: string;
+  body: string;
+};
+
+type TaskMutation =
+  | FrontmatterMutation
+  | SectionMutation
+  | TableRowUpsertMutation
+  | TableRowDeleteMutation;
+
+type TaskWriteRequest = {
+  taskRef: string;
+  expectedState: TaskWorkspaceState;
+  mutations: readonly TaskMutation[];
+  dryRun?: boolean;
+};
+
+type TaskOperationSummary =
+  | {
+      index: number;
+      kind: 'frontmatter';
+      fields: readonly string[];
+      wouldChange: boolean;
+    }
+  | {
+      index: number;
+      kind: 'section';
+      heading: string;
+      operation: 'create' | 'update';
+      wouldChange: boolean;
+    }
+  | {
+      index: number;
+      kind: 'table-row';
+      section: string;
+      keyColumn: string;
+      key: string;
+      operation: 'insert' | 'update' | 'delete';
+      wouldChange: boolean;
+    }
+  | {
+      index: -1;
+      kind: 'metadata';
+      fields: readonly ['updated_at', 'agent_infra_version'];
+      wouldChange: boolean;
+    };
+
+type TaskWriteMetadata = {
+  timestamp: string;
+  agentInfraVersion: string;
+};
+
+type TaskWriteErrorCode =
+  | ResolveTaskRefErrorCode
+  | 'TASK_STATE_MISMATCH'
+  | 'TASK_READ_FAILED'
+  | 'TASK_DOCUMENT_INVALID'
+  | 'MUTATION_INVALID'
+  | 'TABLE_NOT_FOUND'
+  | 'TABLE_AMBIGUOUS'
+  | 'TABLE_DUPLICATE_KEY'
+  | 'TABLE_UNKNOWN_COLUMN'
+  | 'TABLE_KEY_COLUMN_IN_VALUES'
+  | 'TABLE_KEY_CONFLICT'
+  | 'TABLE_MISSING_COLUMN'
+  | 'TABLE_DELETE_VALUES_FORBIDDEN'
+  | 'TABLE_CELL_INVALID'
+  | 'METADATA_CAPTURE_FAILED'
+  | 'TEMP_WRITE_FAILED'
+  | 'RENAME_FAILED'
+  | 'TEMP_CLEANUP_FAILED';
+
+type TaskWriteError = { code: TaskWriteErrorCode; message: string };
+
+type TaskWriteSuccessBase = {
+  requestRef: string;
+  expectedState: TaskWorkspaceState;
+  taskId: string;
+  taskMdPath: string;
+  actualState: TaskWorkspaceState;
+  operations: readonly TaskOperationSummary[];
+  timestamp: string;
+  agentInfraVersion: string;
+  error: null;
+};
+
+type TaskWritePlanned = TaskWriteSuccessBase & { status: 'planned'; changed: true };
+type TaskWriteApplied = TaskWriteSuccessBase & { status: 'applied'; changed: true };
+type TaskWriteNoOp = TaskWriteSuccessBase & { status: 'no-op'; changed: false };
+
+type TaskWriteFailed = {
+  status: 'failed';
+  requestRef: string;
+  expectedState: TaskWorkspaceState;
+  taskId: string | null;
+  taskMdPath: string | null;
+  actualState: TaskWorkspaceState | null;
+  changed: false;
+  operations: readonly TaskOperationSummary[];
+  timestamp: string | null;
+  agentInfraVersion: string | null;
+  error: TaskWriteError;
+};
+
+type TaskWriteResult =
+  | TaskWritePlanned
+  | TaskWriteApplied
+  | TaskWriteNoOp
+  | TaskWriteFailed;
+
+type TaskFileSystem = {
+  readFileSync: (file: string) => string;
+  statModeSync: (file: string) => number;
+  writeFileSync: (file: string, content: string, mode: number) => void;
+  renameSync: (from: string, to: string) => void;
+  unlinkSync: (file: string) => void;
+};
+
+type TaskWriteOptions = {
+  repoRoot?: string;
+  taskLocation?: {
+    repoRoot: string;
+    taskId: string;
+    taskMdPath: string;
+    state: TaskWorkspaceState;
+  };
+  metadataProvider?: () => TaskWriteMetadata;
+  randomSuffix?: () => string;
+  fileSystem?: Partial<TaskFileSystem>;
+};
+
+const DEFAULT_FILE_SYSTEM: TaskFileSystem = {
+  readFileSync: (file) => fs.readFileSync(file, 'utf8'),
+  statModeSync: (file) => fs.statSync(file).mode,
+  writeFileSync: (file, content, mode) => {
+    fs.writeFileSync(file, content, { encoding: 'utf8', flag: 'wx', mode });
+  },
+  renameSync: (from, to) => fs.renameSync(from, to),
+  unlinkSync: (file) => fs.unlinkSync(file)
+};
+
+function canonicalTimestamp(): string {
+  const now = new Date();
+  const pad = (value: number) => String(value).padStart(2, '0');
+  const offsetMinutes = -now.getTimezoneOffset();
+  const offsetSign = offsetMinutes >= 0 ? '+' : '-';
+  const offset = Math.abs(offsetMinutes);
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}${offsetSign}${pad(Math.floor(offset / 60))}:${pad(offset % 60)}`;
+}
+
+function captureTaskWriteMetadata(): TaskWriteMetadata {
+  return { timestamp: canonicalTimestamp(), agentInfraVersion: VERSION };
+}
+
+function failure(
+  request: TaskWriteRequest,
+  identity: { taskId: string | null; taskMdPath: string | null; actualState: TaskWorkspaceState | null },
+  code: TaskWriteErrorCode,
+  message: string,
+  operations: readonly TaskOperationSummary[] = [],
+  metadata: TaskWriteMetadata | null = null
+): TaskWriteFailed {
+  return {
+    status: 'failed',
+    requestRef: request.taskRef,
+    expectedState: request.expectedState,
+    taskId: identity.taskId,
+    taskMdPath: identity.taskMdPath,
+    actualState: identity.actualState,
+    changed: false,
+    operations,
+    timestamp: metadata?.timestamp ?? null,
+    agentInfraVersion: metadata?.agentInfraVersion ?? null,
+    error: { code, message }
+  };
+}
+
+function errorDetails(error: unknown, fallback: TaskWriteErrorCode): TaskWriteError {
+  if (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string') {
+    return {
+      code: error.code as TaskWriteErrorCode,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+  return {
+    code: fallback,
+    message: error instanceof Error ? error.message : String(error)
+  };
+}
+
+function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): TaskWriteResult {
+  const resolved = options.taskLocation
+    ? {
+        ok: true as const,
+        repoRoot: options.taskLocation.repoRoot,
+        taskId: options.taskLocation.taskId,
+        taskDir: path.dirname(options.taskLocation.taskMdPath),
+        taskMdPath: options.taskLocation.taskMdPath,
+        state: options.taskLocation.state
+      }
+    : resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) {
+    return failure(
+      request,
+      { taskId: resolved.taskId, taskMdPath: null, actualState: null },
+      resolved.code,
+      resolved.message
+    );
+  }
+  const identity = {
+    taskId: resolved.taskId,
+    taskMdPath: resolved.taskMdPath,
+    actualState: resolved.state
+  };
+  if (resolved.state !== request.expectedState) {
+    return failure(
+      request,
+      identity,
+      'TASK_STATE_MISMATCH',
+      `task ${resolved.taskId} is ${resolved.state}, expected ${request.expectedState}`
+    );
+  }
+
+  const io: TaskFileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+  let original: string;
+  let mode: number;
+  try {
+    original = io.readFileSync(resolved.taskMdPath);
+    mode = io.statModeSync(resolved.taskMdPath);
+  } catch (error) {
+    return failure(
+      request,
+      identity,
+      'TASK_READ_FAILED',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+
+  let candidate = original;
+  const operations: TaskOperationSummary[] = [];
+  try {
+    parseTypedTaskFrontmatter(original);
+    if (!Array.isArray(request.mutations)) {
+      throw Object.assign(new Error('mutations must be an array'), { code: 'MUTATION_INVALID' });
+    }
+    for (const [index, mutation] of request.mutations.entries()) {
+      if (!mutation || typeof mutation !== 'object' || !('kind' in mutation)) {
+        throw Object.assign(new Error(`mutation ${index} is invalid`), { code: 'MUTATION_INVALID' });
+      }
+      const before = candidate;
+      if (mutation.kind === 'frontmatter') {
+        candidate = updateTaskFrontmatter(candidate, mutation.set, mutation.remove);
+        operations.push({
+          index,
+          kind: 'frontmatter',
+          fields: [...Object.keys(mutation.set), ...(mutation.remove ?? [])],
+          wouldChange: candidate !== before
+        });
+      } else if (mutation.kind === 'section') {
+        const result = upsertSection(candidate, mutation);
+        candidate = result.content;
+        operations.push({
+          index,
+          kind: 'section',
+          heading: result.heading,
+          operation: result.operation,
+          wouldChange: candidate !== before
+        });
+      } else if (mutation.kind === 'table-row') {
+        const result = mutateTableRow(candidate, mutation);
+        candidate = result.content;
+        operations.push({
+          index,
+          kind: 'table-row',
+          section: result.section,
+          keyColumn: mutation.keyColumn,
+          key: mutation.key.trim(),
+          operation: result.operation,
+          wouldChange: candidate !== before
+        });
+      } else {
+        throw Object.assign(new Error(`mutation ${index} has an unknown kind`), {
+          code: 'MUTATION_INVALID'
+        });
+      }
+    }
+  } catch (error) {
+    const details = errorDetails(error, 'MUTATION_INVALID');
+    return failure(request, identity, details.code, details.message);
+  }
+
+  let metadata: TaskWriteMetadata;
+  try {
+    metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    if (
+      !metadata ||
+      typeof metadata.timestamp !== 'string' ||
+      !metadata.timestamp ||
+      typeof metadata.agentInfraVersion !== 'string' ||
+      !metadata.agentInfraVersion
+    ) {
+      throw new Error('metadata provider returned invalid metadata');
+    }
+  } catch (error) {
+    return failure(
+      request,
+      identity,
+      'METADATA_CAPTURE_FAILED',
+      error instanceof Error ? error.message : String(error),
+      operations
+    );
+  }
+
+  if (candidate === original) {
+    return {
+      status: 'no-op',
+      requestRef: request.taskRef,
+      expectedState: request.expectedState,
+      taskId: resolved.taskId,
+      taskMdPath: resolved.taskMdPath,
+      actualState: resolved.state,
+      changed: false,
+      operations,
+      timestamp: metadata.timestamp,
+      agentInfraVersion: metadata.agentInfraVersion,
+      error: null
+    };
+  }
+
+  try {
+    const beforeMetadata = candidate;
+    candidate = updateTaskFrontmatter(candidate, {
+      updated_at: metadata.timestamp,
+      agent_infra_version: metadata.agentInfraVersion
+    });
+    operations.push({
+      index: -1,
+      kind: 'metadata',
+      fields: ['updated_at', 'agent_infra_version'],
+      wouldChange: candidate !== beforeMetadata
+    });
+  } catch (error) {
+    const details = errorDetails(error, 'TASK_DOCUMENT_INVALID');
+    return failure(request, identity, details.code, details.message, operations, metadata);
+  }
+
+  const successBase: TaskWriteSuccessBase = {
+    requestRef: request.taskRef,
+    expectedState: request.expectedState,
+    taskId: resolved.taskId,
+    taskMdPath: resolved.taskMdPath,
+    actualState: resolved.state,
+    operations,
+    timestamp: metadata.timestamp,
+    agentInfraVersion: metadata.agentInfraVersion,
+    error: null
+  };
+  if (request.dryRun) {
+    return { ...successBase, status: 'planned', changed: true };
+  }
+
+  const suffix = (options.randomSuffix ?? (() => Math.random().toString(36).slice(2)))();
+  const tempPath = path.join(
+    path.dirname(resolved.taskMdPath),
+    `.task.md.${process.pid}.${suffix}.tmp`
+  );
+  let primary: TaskWriteError | null = null;
+  let shouldCleanupTemp = false;
+  try {
+    io.writeFileSync(tempPath, candidate, mode);
+    shouldCleanupTemp = true;
+  } catch (error) {
+    shouldCleanupTemp = (error as NodeJS.ErrnoException).code !== 'EEXIST';
+    primary = errorDetails(error, 'TEMP_WRITE_FAILED');
+    primary.code = 'TEMP_WRITE_FAILED';
+  }
+  if (!primary) {
+    try {
+      io.renameSync(tempPath, resolved.taskMdPath);
+    } catch (error) {
+      primary = errorDetails(error, 'RENAME_FAILED');
+      primary.code = 'RENAME_FAILED';
+    }
+  }
+  if (primary && shouldCleanupTemp) {
+    try {
+      io.unlinkSync(tempPath);
+    } catch (cleanupError) {
+      const nodeError = cleanupError as NodeJS.ErrnoException;
+      if (nodeError.code !== 'ENOENT') {
+        return failure(
+          request,
+          identity,
+          'TEMP_CLEANUP_FAILED',
+          `${primary.code}: ${primary.message}; failed to clean ${tempPath}: ${nodeError.message}`,
+          operations,
+          metadata
+        );
+      }
+    }
+  }
+  if (primary) {
+    return failure(
+      request,
+      identity,
+      primary.code,
+      primary.message,
+      operations,
+      metadata
+    );
+  }
+  return { ...successBase, status: 'applied', changed: true };
+}
+
+export { writeTask, captureTaskWriteMetadata, canonicalTimestamp };
+export type {
+  FrontmatterMutation,
+  SectionMutation,
+  TaskMutation,
+  TaskWriteRequest,
+  TaskOperationSummary,
+  TaskWriteMetadata,
+  TaskWriteErrorCode,
+  TaskWriteError,
+  TaskWritePlanned,
+  TaskWriteApplied,
+  TaskWriteNoOp,
+  TaskWriteFailed,
+  TaskWriteResult,
+  TaskFileSystem,
+  TaskWriteOptions
+};
+export type { FrontmatterScalar } from './frontmatter.ts';
+export type { ResolveTaskRefErrorCode, TaskWorkspaceState } from './resolve-ref.ts';
+export type {
+  TableRowBase,
+  TableRowUpsertMutation,
+  TableRowDeleteMutation
+} from './sections.ts';

package/lib/update.ts

@@ -194,6 +194,12 @@ async function cmdUpdate(): Promise<void> {
     platformType
   );
   ok('Updated .agents/skills/update-agent-infra/');
+  renderFile(
+    path.join(templateDir, '.agents', 'scripts', 'lib', 'agent-infra-package.js'),
+    path.join('.agents', 'scripts', 'lib', 'agent-infra-package.js'),
+    replacements
+  );
+  ok('Updated .agents/scripts/lib/agent-infra-package.js');
   try {
     fs.unlinkSync(path.join('.agents', 'skills', 'update-agent-infra', 'scripts', 'sync-templates.cjs'));
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -19,13 +19,15 @@
   },
   "bin": {
     "agent-infra": "./dist/bin/cli.js",
-    "ai": "./dist/bin/cli.js"
+    "ai": "./dist/bin/cli.js",
+    "agent-infra-internal": "./dist/bin/internal-cli.js"
   },
   "files": [
     "dist/",
     "!dist/**/*.map",
     "bin/cli.ts",
     "lib/",
+    "runtime/",
     "templates/"
   ],
   "engines": {
@@ -58,6 +60,7 @@
     "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/unit/**/*.test.ts\"",
     "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "test:integration": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
     "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\"",

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

@@ -209,6 +209,8 @@ The `files` field in `.agents/.airc.json` groups project files into three catego
 | `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 |
 
+Ordinary `managed` files keep their overwrite semantics. A small set of platform lifecycle workflows can be registered as guarded managed files. The synchronizer stores each rendered source SHA-256 in `files.managedBaselines` and uses a three-way comparison: accept template-only upgrades, preserve user-only changes, and report a conflict without overwriting when both sides changed or the origin is unknown. This mapping is tool-maintained and should not be edited manually.
+
 `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.
@@ -398,14 +400,15 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 For skills that produce structured artifacts or mutate task state, run the verification gate before claiming completion:
 
 ```bash
-node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact-file] [--format json|text]
+agent-infra-internal task-verify {task-id} <verification-event> [--artifact <artifact>] --format text
 ```
 
 - Each skill declares its own checks in `config/verify.json`; keep the file focused on what that skill must validate
+- The typed verification catalog maps business events to skill, workspace, artifact, and gate/check order; callers must not assemble those mechanical parameters
 - 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
+- Use `--format text` for readable user-facing final validation
+- `task-verify` executes the typed catalog/check registry in-process; skills must not duplicate validation algorithms or pass mechanical check sequences
 - Keep the gate output in the reply as fresh evidence; without output from the current run, do not claim completion
 
 ## FAQ

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

@@ -209,6 +209,8 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 | `merged` | 由 AI 或人工语义合并 | 不从模板写入 | 保留项目本地副本 |
 | `ejected` | 首次可从模板创建，已存在时跳过覆盖 | 不从模板写入 | 保留项目本地副本 |
 
+普通 `managed` 文件仍采用覆盖语义。少数平台生命周期 workflow 可登记为 guarded managed：同步器在 `files.managedBaselines` 保存渲染后来源的 SHA-256，并用三方比较自动接收官方单边升级、保留用户单边修改，在双方都变化或来源未知时报告冲突而不覆盖。该映射由工具维护，不建议手工编辑。
+
 `ejected` 有两种常见用法：
 
 1. **接管内置文件**：项目需要完全控制原本来自模板的规则、命令或配置文件，避免后续同步覆盖本地内容。
@@ -398,14 +400,15 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 对会产生结构化产物或任务状态变更的 skill，统一在结束前运行完成校验：
 
 ```bash
-node .agents/scripts/validate-artifact.js gate <skill-name> <task-dir> [artifact-file] [--format json|text]
+agent-infra-internal task-verify {task-id} <verification-event> [--artifact <artifact>] --format text
 ```
 
 - 每个 skill 在自己的 `config/verify.json` 中声明需要检查的事项
+- typed verification catalog 将业务事件映射到 skill、workspace、artifact 和 gate/check 顺序；调用方不得自行拼接这些机械参数
 - 对语言相关的产物标题或锚点，`config/verify.en.json` 和 `config/verify.zh-CN.json` 之间只应让 `required_sections` 与语言相关的 `required_patterns` 不同
 - 如果 skill 还会展示“下一步”提示，必须先通过完成校验，再输出这些指引
-- 面向用户展示最终校验结果时，优先使用 `--format text` 输出可读摘要，而不是原始 JSON
-- 共享逻辑集中在 `.agents/scripts/validate-artifact.js`，不要把详细校验规则重新塞回 SKILL.md
+- 面向用户展示最终校验结果时使用 `--format text` 输出可读摘要
+- `task-verify` 在进程内按 typed catalog/check registry 执行；SKILL 不得复制校验算法或传机械 check 序列
 - 在回复中保留当次校验输出作为当次验证输出；没有当次校验输出，不得声明完成
 
 ## 常见问题

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

@@ -15,18 +15,19 @@ so you can quickly find "which ones to read" without opening each file.
 
 ## Issue / PR
 
-- [`issue-pr-commands.md`](issue-pr-commands.md) — GitHub commands to verify auth and read/write Issues / PRs.
+- [`issue-pr-commands.md`](issue-pr-commands.md) — PR commands and Issue intent entry points.
 - [`pr-checks-commands.md`](pr-checks-commands.md) — Commands to watch PR required checks and pull failure logs (`watch-pr`).
-- [`create-issue.md`](create-issue.md) — Cascading Issue creation after `create-task` writes `task.md`.
-- [`issue-sync.md`](issue-sync.md) — Sync markers and flow for task artifacts ↔ Issue comments / labels / fields.
-- [`issue-fields.md`](issue-fields.md) — Read/write flow for Issue Type pinned fields (Priority/Effort/dates).
+- [`create-issue.md`](create-issue.md) — Declarative Issue creation after `create-task` writes `task.md`.
+- [`issue-sync.md`](issue-sync.md) — Issue comment markers and declarative metadata intent contract.
+- [`issue-fields.md`](issue-fields.md) — Dynamic Issue Type pinned-field mapping boundary.
 - [`pr-sync.md`](pr-sync.md) — Sync rule for the single reviewer-facing PR summary comment.
 
 ## Task Workflow
 
 - [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
 - [`review-handshake.md`](review-handshake.md) — Three-stage bidirectional review handshake: four-state disposition, symmetric evidence, disagreement ledger, convergence and post-review commit gate.
-- [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of `#NN` / bare-number short ids.
+- [`human-decision-context.md`](human-decision-context.md) — Self-contained context and canonical structure for new human-decision details.
+- [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of bare-number short ids.
 - [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.
 - [`label-milestone-setup.md`](label-milestone-setup.md) — Platform commands to initialize labels / milestones.
 - [`security-alerts.md`](security-alerts.md) — Commands to import / close Dependabot and Code Scanning alerts.

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

@@ -14,18 +14,19 @@
 
 ## Issue / PR
 
-- [`issue-pr-commands.md`](issue-pr-commands.md) — 验证平台认证、读写 Issue / PR 的 GitHub 命令集。
+- [`issue-pr-commands.md`](issue-pr-commands.md) — PR 命令集与 Issue intent 入口说明。
 - [`pr-checks-commands.md`](pr-checks-commands.md) — 监控 PR required checks、拉取失败日志的命令集（`watch-pr`）。
-- [`create-issue.md`](create-issue.md) — `create-task` 落盘后级联创建 Issue 的规则。
-- [`issue-sync.md`](issue-sync.md) — task 产物与 Issue 评论 / 标签 / 字段的同步标记与流程。
-- [`issue-fields.md`](issue-fields.md) — Issue Type pinned 字段（Priority/Effort/日期）的读写流程。
+- [`create-issue.md`](create-issue.md) — `create-task` 落盘后的声明式 Issue 创建 intent。
+- [`issue-sync.md`](issue-sync.md) — Issue 评论 marker 与声明式元数据 intent 契约。
+- [`issue-fields.md`](issue-fields.md) — 动态 Issue Type pinned 字段映射边界。
 - [`pr-sync.md`](pr-sync.md) — 面向 reviewer 的唯一 PR 摘要评论的同步规则。
 
 ## 任务工作流
 
 - [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
 - [`review-handshake.md`](review-handshake.md) — 三阶段双向审查握手协议：四态处置、对称证据、分歧账本、收敛与 post-review commit 门禁。
-- [`task-short-id.md`](task-short-id.md) — 任务短号 `#NN` / 裸数字的解析、分配与生命周期。
+- [`human-decision-context.md`](human-decision-context.md) — 新建人工裁决详情的自足上下文与规范结构。
+- [`task-short-id.md`](task-short-id.md) — 裸数字任务短号的解析、分配与生命周期。
 - [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。
 - [`label-milestone-setup.md`](label-milestone-setup.md) — 初始化 label / milestone 的平台命令集。
 - [`security-alerts.md`](security-alerts.md) — 导入 / 关闭 Dependabot 与 Code Scanning 告警的命令集。

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

@@ -1,5 +1,5 @@
 # Issue Creation
 
-This code platform does not provide an Issue creation rule.
+This code platform does not provide an Issue adapter. `platform-issue create` returns a structured no-op/degraded result.
 
 `create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `code-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.