cli-archguard 7.0.19 → 7.0.28

package/cli.mjs

@@ -2,6 +2,13 @@
 import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { dispatchOfficialSkillCli, runIntakeHandshake } from './installer.mjs'
+import {
+  checkpointFileAndRollback,
+  createBlockSnapshot,
+  initializeCheckpointLedger,
+} from './archguard-local-runner.mjs'
+
+const LOCAL_COMMANDS = new Set(['ledger-init', 'snapshot', 'checkpoint'])
 
 const INTAKE_QUESTIONS = [
   {
@@ -24,14 +31,72 @@ const INTAKE_QUESTIONS = [
   },
 ]
 
-await dispatchOfficialSkillCli({
-  packageRoot: dirname(fileURLToPath(import.meta.url)),
-  runCommand: (context) => runIntakeHandshake(context, {
-    questions: INTAKE_QUESTIONS,
-    outputFile: 'ARCHGUARD-REQUIREMENTS.json',
-    afterCapabilities(output) {
-      const instruction = output.nextStep?.instruction
-      if (typeof instruction === 'string' && instruction.trim()) console.log(instruction)
-    },
-  }),
-})
+function requiredArgument(args, index, name) {
+  const value = args[index]?.trim()
+  if (!value) throw new Error(`${name} is required`)
+  return value
+}
+
+async function runLocalCommand(command, args) {
+  if (command === 'ledger-init') {
+    return initializeCheckpointLedger({
+      repositoryRoot: requiredArgument(args, 0, 'repositoryRoot'),
+      ledgerPath: requiredArgument(args, 1, 'ledgerPath'),
+    })
+  }
+  if (command === 'snapshot') {
+    return createBlockSnapshot({
+      repositoryRoot: requiredArgument(args, 0, 'repositoryRoot'),
+      targetPath: requiredArgument(args, 1, 'targetPath'),
+      snapshotPath: requiredArgument(args, 2, 'snapshotPath'),
+    })
+  }
+  return checkpointFileAndRollback({
+    repositoryRoot: requiredArgument(args, 0, 'repositoryRoot'),
+    contractPath: requiredArgument(args, 1, 'contractPath'),
+    targetPath: requiredArgument(args, 2, 'targetPath'),
+    snapshotPath: requiredArgument(args, 3, 'snapshotPath'),
+    ledgerPath: requiredArgument(args, 4, 'ledgerPath'),
+    blockId: requiredArgument(args, 5, 'blockId'),
+    chainId: requiredArgument(args, 6, 'chainId'),
+    gatePassPath: requiredArgument(args, 7, 'gatePassPath'),
+  })
+}
+
+function localCommandExitCode(command, result) {
+  if (command !== 'checkpoint') return 0
+  return result?.status === 'succeeded'
+    && result?.output?.checkpoint?.writeAllowed === true ? 0 : 2
+}
+
+const command = process.argv[2] ?? 'help'
+if (LOCAL_COMMANDS.has(command)) {
+  try {
+    const result = await runLocalCommand(command, process.argv.slice(3))
+    console.log(JSON.stringify(result))
+    process.exitCode = localCommandExitCode(command, result)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
+    process.exitCode = 1
+  }
+} else {
+  await dispatchOfficialSkillCli({
+    packageRoot: dirname(fileURLToPath(import.meta.url)),
+    extraUsageLines: [
+      'Local trusted execution:',
+      '  cli-archguard ledger-init <repositoryRoot> <ledgerPath>',
+      '  cli-archguard snapshot <repositoryRoot> <targetPath> <snapshotPath>',
+      '  cli-archguard checkpoint <repositoryRoot> <contractPath> <targetPath> <snapshotPath> <ledgerPath> <blockId> <chainId> <gatePassPath>',
+    ],
+    runCommand: (context) => runIntakeHandshake(context, {
+      questions: INTAKE_QUESTIONS,
+      outputFile: 'ARCHGUARD-REQUIREMENTS.json',
+      afterCapabilities(output) {
+        const instruction = output.nextStep?.instruction
+        if (typeof instruction === 'string' && instruction.trim()) console.log(instruction)
+      },
+    }),
+  })
+}
+
+export { localCommandExitCode }

package/installer.mjs

@@ -2,29 +2,33 @@
  * 八个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
  * 禁止第二套超时、第二套版本来源、第二套 bin 名。
  */
-import { randomUUID } from 'node:crypto'
-import { constants, existsSync, readFileSync } from 'node:fs'
-import { cp, lstat, mkdir, open, rm, writeFile } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { cp, mkdir, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
+import {
+  LOOKUP_TIMEOUT_MS,
+  brokerCommandInput,
+  invokeCommandInput,
+  invokeOfficialSkill,
+} from './broker.mjs'
+
+export {
+  CALL_TIMEOUT_MS,
+  LOOKUP_TIMEOUT_MS,
+  authoritativeEvaluation,
+  brainClientAuthorization,
+  brainClientTokenPath,
+  brokerCommandInput,
+  callOfficialSkill,
+  invokeCommandInput,
+  invokeOfficialSkill,
+} from './broker.mjs'
 
-export const LOOKUP_TIMEOUT_MS = 8000
-export const CALL_TIMEOUT_MS = 120_000
 const INSTALL_META = 'install-meta.json'
-const FEEDBACK_API_PATH = '/api/v1/telemetry/skill-usage'
-const BRAIN_CLIENT_TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
-const BRAIN_CLIENT_TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
-const BRAIN_CLIENT_AUTH_SCHEME = 'BrainClient'
-const BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES = 16_384
-const BRAIN_CLIENT_TOKEN_FILE_MODE = 0o600
-const FEEDBACK_COMMENT_MAX = 500
-const FEEDBACK_SCORE_MIN = 0
-const FEEDBACK_SCORE_MAX = 100
-const BRAIN_CLIENT_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
-const FEEDBACK_INVOCATION_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
-const FEEDBACK_SCORE_PATTERN = /^(?:0|[1-9]\d{0,2})$/
+const BROKER_STDIN_MAX_BYTES = 1_048_576
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -94,138 +98,6 @@ export async function fetchLatestVersion(context) {
   }
 }
 
-export async function callOfficialSkill(context, operation, input) {
-  const requestId = `${context.npmName}-${Date.now()}`
-  const response = await fetch(context.endpoint, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      input: {
-        schemaVersion: context.schemaVersion,
-        requestId,
-        operation,
-        input,
-      },
-    }),
-    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
-  })
-  let payload
-  try {
-    payload = await response.json()
-  } catch {
-    throw new Error(`${context.displayName} ${operation} failed: non-JSON response (HTTP ${response.status}). Check ${context.endpoint}.`)
-  }
-  if (!response.ok || payload?.ok !== true) {
-    const message = payload?.error?.message
-    if (typeof message !== 'string' || !message.trim()) {
-      throw new Error(`${context.displayName} ${operation} failed: HTTP ${response.status}`)
-    }
-    throw new Error(`${context.displayName} ${operation} failed: ${message}`)
-  }
-  return payload
-}
-
-export function feedbackCommandInput(args) {
-  const invocationId = requiredString(args[1], 'feedback invocation id')
-  if (!FEEDBACK_INVOCATION_PATTERN.test(invocationId)) {
-    throw new Error('feedback invocation id must be the UUID returned by a real skill response')
-  }
-  const scoreText = requiredString(args[2], 'feedback score')
-  if (!FEEDBACK_SCORE_PATTERN.test(scoreText)) {
-    throw new Error(`feedback score must be an integer between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
-  }
-  const score = Number(scoreText)
-  if (!Number.isInteger(score) || score < FEEDBACK_SCORE_MIN || score > FEEDBACK_SCORE_MAX) {
-    throw new Error(`feedback score must be between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
-  }
-  const userComment = args.slice(3).join(' ').trim()
-  if (!userComment) throw new Error('feedback comment is required')
-  if (userComment.length > FEEDBACK_COMMENT_MAX) {
-    throw new Error(`feedback comment must be at most ${FEEDBACK_COMMENT_MAX} characters`)
-  }
-  return { invocationId, score, userComment }
-}
-
-async function brainClientAuthorization(context, environment) {
-  const configuredPath = typeof environment[BRAIN_CLIENT_TOKEN_FILE_ENV] === 'string'
-    ? environment[BRAIN_CLIENT_TOKEN_FILE_ENV].trim() : ''
-  if (!configuredPath) throw new Error(`${BRAIN_CLIENT_TOKEN_FILE_ENV} is required`)
-  if (process.platform === 'win32' || typeof process.getuid !== 'function') {
-    throw new Error('Brain Client token file ownership cannot be verified')
-  }
-  const tokenFilePath = resolve(configuredPath)
-  const linkStatus = await lstat(tokenFilePath)
-  if (linkStatus.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
-  const handle = await open(tokenFilePath, constants.O_RDONLY | constants.O_NOFOLLOW)
-  try {
-    const status = await handle.stat()
-    if (!status.isFile() || status.uid !== process.getuid()
-      || (status.mode & 0o777) !== BRAIN_CLIENT_TOKEN_FILE_MODE
-      || status.size < 1 || status.size > BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES) {
-      throw new Error('Brain Client token file must be owned by the current user with mode 0600')
-    }
-    const tokenFile = asObject(JSON.parse(await handle.readFile('utf8')), 'Brain Client token file')
-    const expectedKeys = ['authorizationScheme', 'endpoint', 'schemaVersion', 'token']
-    if (Object.keys(tokenFile).sort().join('\n') !== expectedKeys.join('\n')) {
-      throw new Error('Brain Client token file contains unknown or missing fields')
-    }
-    const endpoint = new URL(requiredString(tokenFile.endpoint, 'Brain Client endpoint'))
-    if (tokenFile.schemaVersion !== BRAIN_CLIENT_TOKEN_FILE_VERSION
-      || tokenFile.authorizationScheme !== BRAIN_CLIENT_AUTH_SCHEME
-      || endpoint.origin !== new URL(context.endpoint).origin
-      || endpoint.pathname !== FEEDBACK_API_PATH || endpoint.search || endpoint.hash
-      || endpoint.username || endpoint.password
-      || !BRAIN_CLIENT_TOKEN_PATTERN.test(tokenFile.token)) {
-      throw new Error('Brain Client token file authority is invalid')
-    }
-    return `${BRAIN_CLIENT_AUTH_SCHEME} ${tokenFile.token}`
-  } finally {
-    await handle.close()
-  }
-}
-
-export async function submitOfficialSkillFeedback(context, args, environment, request) {
-  const input = feedbackCommandInput(args)
-  const authorization = await brainClientAuthorization(context, environment)
-  const requestId = `${context.runtimeCode}-${randomUUID()}`
-  let response
-  try {
-    response = await request(new URL(FEEDBACK_API_PATH, context.endpoint), {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: authorization,
-      },
-      body: JSON.stringify({
-        requestId,
-        skillId: context.runtimeCode,
-        invocationId: input.invocationId,
-        score: input.score,
-        userComment: input.userComment,
-      }),
-      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
-    })
-  } catch {
-    throw new Error('cli.tax feedback request failed')
-  }
-  let payload
-  try {
-    payload = asObject(await response.json(), 'cli.tax feedback response')
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('cli.tax feedback response')) throw error
-    throw new Error(`cli.tax feedback failed: non-JSON response (HTTP ${response.status})`)
-  }
-  if (!response.ok || payload.ok !== true) {
-    throw new Error(`cli.tax feedback failed: HTTP ${response.status}`)
-  }
-  if (payload.requestId !== requestId || typeof payload.id !== 'string'
-    || !FEEDBACK_INVOCATION_PATTERN.test(payload.id)
-    || typeof payload.duplicated !== 'boolean') {
-    throw new Error('cli.tax feedback response authority is invalid')
-  }
-  return { id: payload.id, requestId, duplicated: payload.duplicated }
-}
-
 export async function installOfficialSkill(context, explicit) {
   const target = installTarget(context.skillName, explicit)
   await mkdir(target, { recursive: true })
@@ -283,21 +155,52 @@ export function defaultUsage(context, extraLines) {
     `  npx ${context.npmName}@latest check [directory]`,
     '      Check whether the installed skill has a newer version.',
     `  npx ${context.npmName}@latest run`,
-    '      Run the skill handshake: discover capabilities and collect intake answers.',
+    "      Run this skill's applicability or onboarding flow; only a real HTTP invocation can trigger automatic evaluation.",
+    `  npx ${context.npmName}@latest invoke <operation> <JSON-object>`,
+    '      Invoke through the restricted local broker; a valid real HTTP invocation submits one authority-bound evaluation.',
+    `  npx ${context.npmName}@latest broker`,
+    '      Read one {"operation":"...","input":{...}} request from JSON stdin.',
+    'Credential: CLITAX_BRAIN_CLIENT_TOKEN_FILE (the broker reads it; never pass the token).',
     `Endpoint: ${context.endpoint}`,
   ]
   if (extraLines?.length) lines.push('', ...extraLines)
   return lines.join('\n')
 }
 
+function brokerDependencies() {
+  return { environment: process.env, request: fetch }
+}
+
+async function readBrokerSource(input) {
+  let source = ''
+  for await (const chunk of input) {
+    source += chunk
+    if (Buffer.byteLength(source, 'utf8') > BROKER_STDIN_MAX_BYTES) {
+      throw new Error(`broker request must be at most ${BROKER_STDIN_MAX_BYTES} bytes`)
+    }
+  }
+  if (!source.trim()) throw new Error('broker request is required on stdin')
+  return source
+}
+
+async function runBrokerInvocation(context, commandInput) {
+  const invocation = await invokeOfficialSkill(
+    context, commandInput.operation, commandInput.input, brokerDependencies(),
+  )
+  console.log(JSON.stringify(invocation))
+  return invocation
+}
+
 export async function runIntakeHandshake(context, spec) {
-  const capabilities = await callOfficialSkill(context, 'capabilities', {})
+  const invocation = await invokeOfficialSkill(context, 'capabilities', {}, brokerDependencies())
+  const capabilities = invocation.response
   const output = capabilities.output && typeof capabilities.output === 'object' ? capabilities.output : {}
   const skill = output.skill && typeof output.skill === 'object' ? output.skill : {}
   const version = typeof skill.version === 'string' && skill.version.trim()
     ? skill.version.trim()
     : context.skillVersion
   console.log(`${context.displayName} ${version}`)
+  console.log(`Automatic feedback accepted: ${invocation.feedback.id}`)
   if (typeof spec.afterCapabilities === 'function') spec.afterCapabilities(output)
   const readline = createInterface({ input: stdin, output: stdout })
   const answers = []
@@ -340,9 +243,9 @@ export async function dispatchOfficialSkillCli(options) {
     if (command === 'install') await installOfficialSkill(context, argument)
     else if (command === 'check') await checkOfficialSkill(context, argument)
     else if (command === 'run') await options.runCommand(context)
-    else if (command === 'feedback') {
-      const receipt = await submitOfficialSkillFeedback(context, args, process.env, fetch)
-      console.log(`${context.displayName} feedback accepted: ${receipt.id}`)
+    else if (command === 'invoke') await runBrokerInvocation(context, invokeCommandInput(args))
+    else if (command === 'broker') {
+      await runBrokerInvocation(context, brokerCommandInput(await readBrokerSource(stdin)))
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
       console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))

package/package.json

@@ -2,13 +2,22 @@
   "bin": {
     "cli-archguard": "./cli.mjs"
   },
+  "dependencies": {
+    "@babel/parser": "^8.0.4",
+    "cli-aimlock": "7.0.28",
+    "yaml": "^2.8.1"
+  },
   "description": "ArchGuard skill installer for CLI.Tax: architecture contracts, chunk checkpoints, drift control, and auditable rollback.",
   "files": [
     "cli.mjs",
     "installer.mjs",
+    "broker.mjs",
     "README.md",
     "skill/SKILL.md",
-    "skill/skill.json"
+    "skill/skill.json",
+    "archguard-contextbase-hook.mjs",
+    "archguard-runtime.mjs",
+    "archguard-local-runner.mjs"
   ],
   "license": "UNLICENSED",
   "name": "cli-archguard",
@@ -17,5 +26,5 @@
     "url": "https://github.com/88208555/archguard-clitax.git"
   },
   "type": "module",
-  "version": "7.0.19"
+  "version": "7.0.28"
 }

package/skill/SKILL.md

@@ -1,52 +1,84 @@
 ---
 name: archguard
-description: Lock a project's architecture contract and check each code block for stack drift, rule violations, and complexity overages while code is being written. Use for multi-file code changes when arch.contract.yaml exists or the user asks to lock the stack. Do not use for read-only analysis, pure documents, calculator generation, or one-line low-risk edits.
+description: '在代码写入期间锁定项目架构合同，并逐块检查技术栈漂移、规则违规与复杂度超限；适用于已有 arch.contract.yaml 或用户明确要求锁定技术栈的多文件修改，不用于只读分析、纯文档、计算工具或单行低风险修改。Lock the architecture contract and check each written code block for stack drift, rule violations, and complexity overages; use for multi-file changes with arch.contract.yaml or an explicit stack-lock request, not read-only analysis, documents, calculators, or one-line low-risk edits. Фиксирует архитектурный контракт и проверяет каждый записанный блок кода на дрейф стека, нарушения и превышение сложности; применяется к многофайловым изменениям с arch.contract.yaml или явным запросом фиксации стека, но не к чтению, документам, калькуляторам и однострочным низкорисковым правкам.'
 ---
 
-# ArchGuard
+# 架构守卫 / ArchGuard / Архитектурный страж
 
-Package version: v7.0.19
+Package version: v7.0.28
 
 Endpoint: https://cli.tax/Ag4Ch8Rd2K
 Request schema: `archguard.skill.request/1.0`
 
-## Boundary
+## 三语能力摘要 / Trilingual capability summary / Трёхъязычное описание
+
+中文：架构守卫只在真实代码写入期间工作。已有架构合同或用户明确要求锁定技术栈的多文件修改才启用；只读分析、纯文档、计算工具和无架构风险的单行修改不启用。每个代码块都必须用同一合同摘要、快照和只追加台账完成检查点；阻断结果必须回滚该块，不能伪报通过。
+
+English: ArchGuard runs only while real code is being written. Activate it for multi-file work under an architecture contract or an explicit stack-lock request; skip read-only analysis, documents, calculator generation, and one-line edits without architecture risk. Every block uses the same contract digest, snapshot, and append-only ledger; a blocked result requires rollback and can never be reported as passed.
+
+Русский: ArchGuard работает только при реальной записи кода. Он включается для многофайловых изменений по архитектурному контракту или при явном запросе фиксации стека; чтение, документы, генерация калькулятора и однострочная правка без архитектурного риска его не запускают. Каждый блок проверяется с тем же дайджестом контракта, снимком и дописываемым журналом; блокировка требует отката и не может считаться прохождением.
+
+## 边界 / Boundary / Границы
 
 ArchGuard supervises code during execution. It does not plan product scope, dispatch agents, merge branches, replace final validation, or implement any model-thinking sandbox.
 
 Use it when a task writes multiple code blocks and either `arch.contract.yaml` exists or the user explicitly asks to lock the technical stack. Skip it for read-only analysis, pure documentation, Calctool generation, merge-only work, and a one-line Lock edit without architecture risk.
 
-## Required sequence
+## 强制流程 / Required sequence / Обязательная последовательность
 
 1. Call `capabilities` first and use the returned `operationSchemas`.
 2. If the project has no contract and this is a new project, call `template-list`, `intake`, then `contract-create` before Blueprint.
 3. Before changing an existing contract, call `contract-get`; `contract-update` requires its exact digest, explicit confirmation, actor, and reason.
-4. Before each code-block write, create a block snapshot. After the block is complete, call `checkpoint` with the contract, block, and checkpoint history.
+4. Before each code-block write, run `cli-archguard snapshot ...`. The write itself must carry the Aimlock chainId and signed gate pass. After the block is complete, run `cli-archguard checkpoint ...` with the same snapshot, contract, append-only ledger, chainId, and gate pass.
 5. A blocking finding means the block cannot remain: restore that block's snapshot, apply the returned correction, then recheck.
 6. Three consecutive blocks with the same blocking rule are a red-light interrupt. Stop mutation and request human direction.
 7. At task end call `rules-scan`, `complexity-report`, and `drift-status`; pass the ledger to Validator as process evidence.
 
-## Contract authority
+## 合同权威 / Contract authority / Полномочия контракта
 
 - The canonical contract is `arch.contract.yaml` with schema `archguard.contract/1.0`.
 - A contract locks stack, allowed/forbidden dependencies, rules, and budgets.
+- Forbidden dependencies are checked in source imports and in `package.json`, `requirements*.txt`, `pom.xml`, and `Cargo.toml`.
 - Never change the contract to make failing code pass. Only an explicitly confirmed versioned `contract-update` may change it.
 - Aimlock owns the contract-file snapshot and mutation scope. ArchGuard owns block checkpoints and architecture findings.
 
-## Checkpoint decisions
+## 检查点裁决 / Checkpoint decisions / Решения контрольной точки
 
 - `passed`: the block may remain.
 - `blocked`: restore the block snapshot when `rollbackRequired` is true; do not report the worker step green.
 - Standard-level findings are report-only by default. Architecture and complexity findings block. A contract may explicitly make standard rules blocking.
 - The checkpoint ledger is append-only evidence. Do not fabricate ledger entries or success states.
+- Checkpoint history is mandatory. Red drift requires three consecutive blocked checkpoints sharing the same blocking rule; unrelated or non-consecutive findings never trigger it.
+
+## 可信本地执行 / Trusted local execution / Доверенное локальное выполнение
+
+Remote JSON `checkpoint` never accepts caller-supplied `astFindings`. When the contract contains AST rules, a remote checkpoint is blocked with `ARCH-AST-LOCAL-RUNNER-REQUIRED`.
+
+Use the bundled CLI in the repository being checked:
+
+```bash
+cli-archguard ledger-init . .archguard/ledger.json
+cli-archguard snapshot . src/example.ts .archguard/example.snapshot.json
+cli-archguard checkpoint . arch.contract.yaml src/example.ts .archguard/example.snapshot.json .archguard/ledger.json block-1 <chainId> <gatePassPath>
+```
 
-## Operations
+中文：本地运行器把每个快照和台账绑定到真实仓库根目录，只接受 `.archguard/` 下不含符号链接或目录联接的相对路径；绝对路径、父级穿越和覆盖非受管文件均被拒绝。
+
+English: The local runner binds every snapshot and ledger to the real repository root and accepts only relative `.archguard/` paths without symlinks or junctions. It refuses absolute or parent-traversing paths and never overwrites an unmanaged file.
+
+Русский: Локальный исполнитель привязывает каждый снимок и журнал к реальному корню репозитория и принимает только относительные пути в `.archguard/` без символических ссылок и соединений каталогов. Абсолютные пути, выход к родителю и перезапись неуправляемых файлов отклоняются.
+
+The runner verifies the Aimlock Ed25519 pass against the real repository before evaluating a block. A missing, forged, expired, wrong-chain, or out-of-scope pass rejects the block and restores its snapshot. It then reads the file and contract without following symlinks, computes AST findings in-process, restores a blocked snapshot, appends its ledger entry, and emits a ContextBase invalidation event when that derived cache is initialized. Missing local evidence is blocked, never treated as an empty AST result.
+
+The local CLI exits with code `0` only when a checkpoint permits the write. A blocked checkpoint that has been rolled back exits with code `2`; an execution error exits with code `1`. Automation must read the JSON evidence and the exit code.
+
+## 操作 / Operations / Операции
 
 `capabilities`, `help`, `intake`, `contract-create`, `contract-get`, `contract-update`, `template-list`, `checkpoint`, `rules-scan`, `complexity-report`, `drift-status`, `ledger-query`.
 
 Built-in templates: React + TypeScript + Vite, Vue 3 + TypeScript + Vite, Next.js, NestJS, FastAPI, Spring Boot, WeChat Mini Program, and Tauri desktop.
 
-## Chain routing
+## 链路路由 / Chain routing / Маршрутизация цепочки
 
 - Existing code with contract: Aimlock → Blueprint → Swarm → ArchGuard checkpoints → MergeGuard when a merge is requested → Validator.
 - Existing code without contract: Aimlock → Blueprint → Swarm → Validator; recommend contract creation without blocking the current task.
@@ -54,12 +86,15 @@ Built-in templates: React + TypeScript + Vite, Vue 3 + TypeScript + Vite, Next.j
 
 Before handing off, preserve the exact contract digest, checkpoint ledger, full findings, rollback outcome, and drift light. Missing evidence is not success.
 
-## Automated feedback
-
-Only after a real ArchGuard HTTP call succeeds and returns `feedbackInvocationId`, the IDE may automatically submit an honest score and comment with:
-
-`npx cli-archguard@latest feedback <feedbackInvocationId> <score> <comment...>`
+## 受限调用与自动评价闭环
 
-The command requires the member IDE client token file through `CLITAX_BRAIN_CLIENT_TOKEN_FILE`. Humans must not choose or submit ratings.
+- IDE / 智能体必须通过本包 `invoke` 或 JSON-stdin `broker` 调用，不得直接拼装技能 HTTP 请求，也不得读取 BrainClient token。
+- broker 从 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 读取身份；macOS/Linux 文件必须为当前 broker 账户所有且权限 `0600`，Windows 文件必须位于受限 `%LOCALAPPDATA%\CLI.Tax\broker` 目录。
+- broker 只需要 Brain Client HTTPS、受限身份文件和调用方显式传入的路径，本身不需要完整磁盘访问。若要保证 IDE 无法读取身份文件，必须把 broker 放进独立低权限系统账户或沙箱服务，并只暴露受限 IPC；broker 与 IDE 同账户运行时，`0600` 不能隔离二者，禁止声称令牌已隔离。
+- broker 只用 `Authorization: BrainClient …` 发起一次 runtime 请求。HTTP 成功后必须保留响应顶层原始 `feedbackReceiptId`、`feedbackInvocationId` 和 `feedbackEvaluation.digest`，不得生成、猜测、复用或跨调用转移。
+- Brain Client 服务端必须严格绑定请求/响应的 `requestId` 和 `schemaVersion`，再根据真实状态、验证结果、服务端耗时与 findings 生成并持久化权威评分、评语和摘要。broker 不得生成分数或评语。
+- 同一次 runtime 请求在服务端事务内生成并持久化评价，再返回 `feedbackReceiptId`、`feedbackInvocationId` 和权威摘要；broker 只验证已提交回执，不发起第二次评价写入。`not-reported`、验证不完整、P0/P1 findings、`blocked` 或 `failed` 都不得生成好评。
+- 缺少凭证或 ID、身份不匹配、摘要不匹配、响应非法以及任何 HTTP 失败都必须显式失败，不得静默、不重试成重复评价。
+- 本地 CLI 不提供手工评分或评语提交命令，人类不得选择技能分数或填写技能评价；日常聊天不属于评价协议。
 
-只有真实响应顶层包含 `feedbackInvocationId` 时才允许回传；会员账号实名入库，禁止伪造、猜测、复用调用编号，禁止让人类选择分数，任何 HTTP 失败都必须视为回传失败。
+调用示例：`npx cli-archguard@latest invoke <operation> '<JSON对象>'`。IDE 集成可向 `npx cli-archguard@latest broker` 的 stdin 发送 `{"operation":"capabilities","input":{}}`。

package/skill/skill.json

@@ -1,10 +1,10 @@
 {
-  "description": "ArchGuard 是技能链的执行中架构守卫。它用版本化架构合同锁定语言、框架、脚手架、依赖与复杂度预算，在每个代码块完成后执行 checkpoint，发现栈漂移、规则违规或复杂度超限时拒绝该块并给出回滚指令；连续三块同类违规进入红灯中断。支持 8 个栈模板、全操作 JSON Schema、规则扫描、复杂度报告、漂移状态和审计台账。仅用于代码写入过程；纯分析、纯文档、计算工具和无代码落盘任务不调用。",
+  "description": "架构守卫在代码写入期间用版本化合同锁定技术栈、依赖与复杂度预算，逐块检查并记录可审计回滚；仅用于有合同或明确锁栈要求的多文件修改。ArchGuard locks stack, dependencies, and complexity budgets with a versioned contract, checks every written block, and records auditable rollback; use only for multi-file work with a contract or explicit stack-lock request. Архитектурный страж фиксирует стек, зависимости и бюджеты сложности версионированным контрактом, проверяет каждый записанный блок и ведёт аудит отката; применяется только к многофайловой работе с контрактом или явной фиксацией стека.",
   "displayName": "ArchGuard",
   "endpoint": "https://cli.tax/Ag4Ch8Rd2K",
   "method": "POST",
   "name": "archguard",
   "type": "Skill",
-  "version": "v7.0.19",
+  "version": "v7.0.28",
   "schemaVersion": "archguard.skill.request/1.0"
 }