driftseal 1.1.3 → 1.1.5

package/README.md

@@ -36,7 +36,12 @@ driftseal init
 
 `driftseal init` writes the protocol to `AGENTS.md`, including how to `absorb`
 colliding worktree logs, and configures the local git merge driver. It can be
-run again without duplicating either. DriftSeal requires Node.js 18+.
+run again without duplicating either. Pass `--lang zh-CN` (or another
+[BCP 47](https://www.rfc-editor.org/rfc/rfc5646.html) tag) to declare the
+language agents should use for intent and decision prose; the default is `en`.
+Command names, flags, status tokens, ids, and MADR section headings stay in
+English. Re-running `init` without `--lang` preserves the declared language
+while upgrading the protocol. DriftSeal requires Node.js 18+.
 
 For local development from this checkout:
 
@@ -231,7 +236,7 @@ content change starts a new work round.
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | Install the repository-pinned MCP server into Codex, Kimi Code, OpenCode, Claude Code, or Cursor. |
 | `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | Install advisory lifecycle reminders into Kimi Code, Claude Code, or Codex. |
 | `driftseal hook prompt\|stop [--format plain\|claude-code]` | Emit the reminder a lifecycle hook injects; never blocks. |
-| `driftseal init` | Add the adoption protocol to `AGENTS.md` and configure the git merge driver. |
+| `driftseal init [--lang <tag>]` | Add the adoption protocol to `AGENTS.md` and configure the git merge driver. `--lang` sets the intent/decision log language (BCP 47, default `en`). |
 | `driftseal --version` or `driftseal -V` | Print the installed DriftSeal version. |
 | `driftseal help` | Print CLI usage. |
 
@@ -274,8 +279,10 @@ conflicts cannot block later decision work.
 New events carry a schema version. DriftSeal rejects newer unsupported schemas and
 fails closed if a legacy client closes a linked intent without reconciliation.
 `driftseal init` writes versioned managed blocks and upgrades only exact, recognized
-older blocks. It refuses newer protocol versions and any unrecognized or
-customized block without changing `AGENTS.md`.
+older blocks. Current-version blocks that differ only by log language are also
+recognized, so `--lang` can change the language without rewriting policy by hand.
+It refuses newer protocol versions and any unrecognized or customized block
+without changing `AGENTS.md`.
 
 `--count` prints only the number of records remaining after status filtering.
 It cannot be combined with `--last`, whose limiting semantics would make the

package/README.zh-CN.md

@@ -35,7 +35,11 @@ driftseal init
 ```
 
 `driftseal init` 会把协议写入 `AGENTS.md`（包括 worktree 撞号后如何 `absorb`），
-并配置 local git merge driver。重复运行不会产生副本。DriftSeal 需要 Node.js 18+。
+并配置 local git merge driver。重复运行不会产生副本。用 `--lang zh-CN`（或其他
+[BCP 47](https://www.rfc-editor.org/rfc/rfc5646.html) 标签）声明 agent 写入
+intent / decision 正文时应使用的语言，默认是 `en`。命令名、flag、status token、
+id 以及 MADR 小节标题仍保持英文。再次运行不带 `--lang` 的 `init` 会保留已声明
+的语言并升级协议。DriftSeal 需要 Node.js 18+。
 
 从当前 checkout 本地开发时：
 
@@ -220,7 +224,7 @@ Git 操作完全不计入 intent log，因为 Git 会自行维护历史。查看
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | 把固定到 repository 的 MCP server 安装到 Codex、Kimi Code、OpenCode、Claude Code 或 Cursor。 |
 | `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | 把建议性的 lifecycle 提醒安装到 Kimi Code、Claude Code 或 Codex。 |
 | `driftseal hook prompt\|stop [--format plain\|claude-code]` | 输出 lifecycle hook 注入的提醒；绝不阻断。 |
-| `driftseal init` | 把接入协议写入 `AGENTS.md`，并配置 git merge driver。 |
+| `driftseal init [--lang <tag>]` | 把接入协议写入 `AGENTS.md`，并配置 git merge driver。`--lang` 设置 intent / decision log 的语言（BCP 47，默认 `en`）。 |
 | `driftseal --version` 或 `driftseal -V` | 输出当前安装的 DriftSeal 版本。 |
 | `driftseal help` | 查看 CLI 用法。 |
 
@@ -257,8 +261,9 @@ recovery 只处理当前 intent，因此历史冲突不会阻塞之后的 decisi
 新 event 带有 schema version。遇到更高且不支持的版本时，DriftSeal 会拒绝继续；如果
 旧 client 未经 reconciliation 就关闭 linked intent，新 client 也会 fail closed。
 `driftseal init` 会写入带版本的 managed blocks，并且只升级内容完全匹配的已知旧版本。
-遇到更新的协议版本、无法识别的 block 或自定义内容时，它会保持 `AGENTS.md`
-不变并拒绝继续。
+当前版本的 block 如果只是 log language 不同，也会被识别，因此可以用 `--lang`
+改语言而不必手改协议。遇到更新的协议版本、无法识别的 block 或自定义内容时，
+它会保持 `AGENTS.md` 不变并拒绝继续。
 
 `--count` 只输出 status 筛选后的记录总数。它不能与 `--last` 一起使用，以免
 “先限制再计数”造成歧义。Decision 文件名会构成一个轻量的内存索引：`show` 只

package/bin/driftseal.js

@@ -36,7 +36,8 @@ const DECISION_STATUSES = [
   'superseded',
 ];
 const EVENT_SCHEMA_VERSION = 3;
-const PROTOCOL_VERSION = 10;
+const PROTOCOL_VERSION = 11;
+const DEFAULT_LOG_LANGUAGE = 'en';
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const MAX_DECISION_SLUG_LENGTH = 180;
@@ -1122,10 +1123,213 @@ const INTENT_PROTOCOL_MARKER = '<!-- driftseal -->';
 const INTENT_PROTOCOL_END = '<!-- /driftseal -->';
 const DECISION_PROTOCOL_MARKER = '<!-- driftseal-decisions -->';
 const DECISION_PROTOCOL_END = '<!-- /driftseal-decisions -->';
+const LOG_LANGUAGE_COMMENT_RE = /^<!-- driftseal-log-language: ([^>\r\n]+) -->\r?$/m;
+const LOG_LANGUAGE_PROSE_RE = /\*\*Log language:\*\* `([^`]+)`/;
+const IRREGULAR_GRANDFATHERED_TAGS = new Map([
+  ['en-gb-oed', 'en-GB-oed'],
+  ['i-ami', 'i-ami'],
+  ['i-bnn', 'i-bnn'],
+  ['i-default', 'i-default'],
+  ['i-enochian', 'i-enochian'],
+  ['i-hak', 'i-hak'],
+  ['i-klingon', 'i-klingon'],
+  ['i-lux', 'i-lux'],
+  ['i-mingo', 'i-mingo'],
+  ['i-navajo', 'i-navajo'],
+  ['i-pwn', 'i-pwn'],
+  ['i-tao', 'i-tao'],
+  ['i-tay', 'i-tay'],
+  ['i-tsu', 'i-tsu'],
+  ['sgn-be-fr', 'sgn-BE-FR'],
+  ['sgn-be-nl', 'sgn-BE-NL'],
+  ['sgn-ch-de', 'sgn-CH-DE'],
+]);
+
+function titleCaseSubtag(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+}
+
+function isBcp47Variant(subtag) {
+  return /^[A-Za-z0-9]{5,8}$/.test(subtag) || /^[0-9][A-Za-z0-9]{3}$/.test(subtag);
+}
+
+function isBcp47Singleton(subtag) {
+  return /^[0-9A-WY-Za-wy-z]$/.test(subtag);
+}
+
+function parsePrivateUseSubtags(subtags, start, parts) {
+  if (start >= subtags.length || !/^x$/i.test(subtags[start])) return null;
+  parts.push('x');
+  let index = start + 1;
+  let count = 0;
+  while (index < subtags.length && /^[A-Za-z0-9]{1,8}$/.test(subtags[index])) {
+    parts.push(subtags[index].toLowerCase());
+    index += 1;
+    count += 1;
+  }
+  if (count === 0 || index !== subtags.length) return null;
+  return parts.join('-');
+}
+
+function wellFormedBcp47(tag) {
+  if (typeof tag !== 'string' || tag.length === 0 || tag.startsWith('-') || tag.endsWith('-')) {
+    return null;
+  }
+  const irregular = IRREGULAR_GRANDFATHERED_TAGS.get(tag.toLowerCase());
+  if (irregular) return irregular;
+
+  const subtags = tag.split('-');
+  if (subtags.some((subtag) => subtag.length === 0)) return null;
+
+  const parts = [];
+  if (/^x$/i.test(subtags[0])) return parsePrivateUseSubtags(subtags, 0, parts);
+
+  let index = 0;
+  const language = subtags[index];
+  if (!/^[A-Za-z]{2,8}$/.test(language)) return null;
+  parts.push(language.toLowerCase());
+  index += 1;
+  if (language.length <= 3) {
+    let extlang = 0;
+    while (index < subtags.length && /^[A-Za-z]{3}$/.test(subtags[index]) && extlang < 3) {
+      parts.push(subtags[index].toLowerCase());
+      index += 1;
+      extlang += 1;
+    }
+  }
+
+  if (index < subtags.length && /^[A-Za-z]{4}$/.test(subtags[index])) {
+    parts.push(titleCaseSubtag(subtags[index]));
+    index += 1;
+  }
+
+  if (index < subtags.length && /^[A-Za-z]{2}$/.test(subtags[index])) {
+    parts.push(subtags[index].toUpperCase());
+    index += 1;
+  } else if (index < subtags.length && /^[0-9]{3}$/.test(subtags[index])) {
+    parts.push(subtags[index]);
+    index += 1;
+  }
+
+  const variants = new Set();
+  while (index < subtags.length && isBcp47Variant(subtags[index])) {
+    const variant = subtags[index].toLowerCase();
+    if (variants.has(variant)) return null;
+    variants.add(variant);
+    parts.push(variant);
+    index += 1;
+  }
+
+  const singletons = new Set();
+  while (index < subtags.length && isBcp47Singleton(subtags[index])) {
+    const singleton = subtags[index].toLowerCase();
+    if (singletons.has(singleton)) return null;
+    singletons.add(singleton);
+    parts.push(singleton);
+    index += 1;
+    let following = 0;
+    while (index < subtags.length && /^[A-Za-z0-9]{2,8}$/.test(subtags[index])) {
+      parts.push(subtags[index].toLowerCase());
+      index += 1;
+      following += 1;
+    }
+    if (following === 0) return null;
+  }
+
+  if (index < subtags.length && /^x$/i.test(subtags[index])) {
+    return parsePrivateUseSubtags(subtags, index, parts);
+  }
+  if (index !== subtags.length) return null;
+  return parts.join('-');
+}
+
+function canonicalizeLogLanguage(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    fail('invalid log language: use a BCP 47 tag such as en or zh-CN');
+  }
+  const canonical = wellFormedBcp47(value.trim());
+  if (!canonical) {
+    fail(`invalid log language "${value}": use a BCP 47 tag such as en or zh-CN`);
+  }
+  return canonical;
+}
+
+function intentLogLanguageParagraph(language) {
+  return `**Log language:** \`${language}\`. Write intent-log prose (intent, note,
+verify-result, and reclaim/unreclaim reason) in that language. Keep command
+names, flags, status tokens, and ids in English.`;
+}
+
+function decisionLogLanguageParagraph(language) {
+  return `**Log language:** \`${language}\`. Write decision-log prose (title, context,
+outcome, drivers, options, consequences, and update notes) in that language.
+Keep MADR section headings, status tokens, and ids in English.`;
+}
+
+function parseLogLanguageFromBlock(block, label) {
+  const commentMatch = block.match(LOG_LANGUAGE_COMMENT_RE);
+  const proseMatch = block.match(LOG_LANGUAGE_PROSE_RE);
+  const comment = commentMatch ? canonicalizeLogLanguage(commentMatch[1]) : null;
+  const prose = proseMatch ? canonicalizeLogLanguage(proseMatch[1]) : null;
+  if (comment && prose && comment !== prose) {
+    fail(
+      `${label} declares different log languages in the comment (${comment}) and prose (${prose}); pass --lang to set one`
+    );
+  }
+  return comment || prose || null;
+}
 
-function intentProtocolBlock(version = PROTOCOL_VERSION) {
+function extractManagedBlock(content, marker, endMarker) {
+  const start = content.indexOf(marker);
+  if (start === -1) return null;
+  const end = content.indexOf(endMarker, start);
+  if (end === -1) return null;
+  return content.slice(start, end + endMarker.length);
+}
+
+function resolveInitLogLanguage(requested, content) {
+  if (requested !== undefined) return canonicalizeLogLanguage(requested);
+  const languages = new Set();
+  const intent = extractManagedBlock(content, INTENT_PROTOCOL_MARKER, INTENT_PROTOCOL_END);
+  const decision = extractManagedBlock(content, DECISION_PROTOCOL_MARKER, DECISION_PROTOCOL_END);
+  if (intent) {
+    const language = parseLogLanguageFromBlock(intent, 'intent protocol');
+    if (language) languages.add(language);
+  }
+  if (decision) {
+    const language = parseLogLanguageFromBlock(decision, 'decision protocol');
+    if (language) languages.add(language);
+  }
+  if (languages.size > 1) {
+    fail(
+      `intent and decision protocols declare different log languages (${[...languages].join(', ')}); pass --lang to set one`
+    );
+  }
+  return languages.size === 1 ? [...languages][0] : DEFAULT_LOG_LANGUAGE;
+}
+
+function protocolBlockKey(block) {
+  return block
+    .replace(/^<!-- driftseal-log-language: [^>\r\n]+ -->\r?$/m, '<!-- driftseal-log-language: -->')
+    .replace(/\*\*Log language:\*\* `[^`]+`/g, '**Log language:** ``');
+}
+
+function stripIntentLogLanguage(block, language = DEFAULT_LOG_LANGUAGE) {
+  return block
+    .replace(`\n<!-- driftseal-log-language: ${language} -->`, '')
+    .replace(`\n${intentLogLanguageParagraph(language)}\n`, '');
+}
+
+function stripDecisionLogLanguage(block, language = DEFAULT_LOG_LANGUAGE) {
+  return block
+    .replace(`\n<!-- driftseal-log-language: ${language} -->`, '')
+    .replace(`\n${decisionLogLanguageParagraph(language)}\n`, '');
+}
+
+function intentProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE) {
   return `${INTENT_PROTOCOL_MARKER}
 <!-- driftseal-version: ${version} -->
+<!-- driftseal-log-language: ${language} -->
 
 ## Agent protocol: intent write-ahead log
 
@@ -1135,6 +1339,8 @@ This \`AGENTS.md\` protocol is the source of truth. Use the \`driftseal\` CLI by
 default; the companion skill only helps discover and resume the workflow, while
 MCP and lifecycle hooks are optional adapters.
 
+${intentLogLanguageParagraph(language)}
+
 1. **Write intent first**, before modifying, creating, or deleting files, or
    making any other non-Git change that may need a rollback:
    \`driftseal begin "<what this round will accomplish>" --verify "<command or check that proves it>"\`.
@@ -1178,8 +1384,9 @@ ${INTENT_PROTOCOL_END}`;
 }
 
 function previousIntentProtocolBlock(version) {
-  const v9 = intentProtocolBlock(version)
-    .replace(
+  const v10 = stripIntentLogLanguage(intentProtocolBlock(version, DEFAULT_LOG_LANGUAGE));
+  if (version >= 10) return v10;
+  const v9 = v10.replace(
       '1. **Write intent first**, before modifying, creating, or deleting files, or\n' +
         '   making any other non-Git change that may need a rollback:\n' +
         '   `driftseal begin "<what this round will accomplish>" --verify "<command or check that proves it>"`.\n' +
@@ -1258,9 +1465,10 @@ function protocolEol(content, eol) {
   return eol === '\n' ? content : content.replace(/\n/g, eol);
 }
 
-function decisionProtocolBlock(version = PROTOCOL_VERSION) {
+function decisionProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE) {
   return `${DECISION_PROTOCOL_MARKER}
 <!-- driftseal-decisions-version: ${version} -->
+<!-- driftseal-log-language: ${language} -->
 
 ## Agent protocol: decision log
 
@@ -1270,6 +1478,8 @@ revisiting, non-obvious rationale behind a long-lived or costly-to-reverse accep
 choice, or a deprecated or superseded decision. Do not record routine, local,
 readily reversible choices.
 
+${decisionLogLanguageParagraph(language)}
+
 \`driftseal decision add "<title>" --context "<problem and constraints>" --outcome "<decision and rationale>" --driver "<decision driver>" --option "<considered option>" --consequence "<result>"\`
 
 Add one \`--driver\`, \`--option\`, or \`--consequence\` flag per item. Use
@@ -1338,9 +1548,9 @@ Commit \`.decision-log/\` with the code.`;
 }
 
 function previousDecisionProtocolBlock(version) {
-  const v9 = decisionProtocolBlock(version);
-  if (version >= 9) return v9;
-  const v8 = v9.replace(
+  const v10 = stripDecisionLogLanguage(decisionProtocolBlock(version, DEFAULT_LOG_LANGUAGE));
+  if (version >= 9) return v10;
+  const v8 = v10.replace(
     '\nAfter a merge, colliding decision ids are remapped with `driftseal absorb`;\n' +
       'concurrent edits of a shared decision are not auto-merged.',
     ''
@@ -1381,7 +1591,11 @@ function upgradeManagedBlock({
         `protocol version ${version} requires a newer DriftSeal client (supported: ${PROTOCOL_VERSION})`
       );
     }
-    if (block !== replacement && !knownManagedBlocks.includes(block)) {
+    if (
+      block !== replacement &&
+      !knownManagedBlocks.includes(block) &&
+      protocolBlockKey(block) !== protocolBlockKey(replacement)
+    ) {
       fail(`cannot safely upgrade customized protocol block beginning with ${marker}`);
     }
     return {
@@ -3322,14 +3536,15 @@ const commands = {
   },
 
   init(argv) {
-    const { positionals } = parseArgs(argv, {});
-    if (positionals.length > 0) fail('usage: driftseal init');
+    const { positionals, flags } = parseArgs(argv, { lang: 'single' });
+    if (positionals.length > 0) fail('usage: driftseal init [--lang <tag>]');
     const target = path.join(process.cwd(), 'AGENTS.md');
     const existed = fs.existsSync(target);
     const current = existed ? fs.readFileSync(target, 'utf8') : '';
     const eol = current.includes('\r\n') ? '\r\n' : '\n';
-    const intentBlock = protocolEol(intentProtocolBlock(), eol);
-    const decisionBlock = protocolEol(decisionProtocolBlock(), eol);
+    const language = resolveInitLogLanguage(flags.lang, current);
+    const intentBlock = protocolEol(intentProtocolBlock(PROTOCOL_VERSION, language), eol);
+    const decisionBlock = protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, language), eol);
     let updated = current;
     const intent = upgradeManagedBlock({
       content: updated,
@@ -3346,6 +3561,7 @@ const commands = {
         protocolEol(previousIntentProtocolBlock(7), eol),
         protocolEol(previousIntentProtocolBlock(8), eol),
         protocolEol(previousIntentProtocolBlock(9), eol),
+        protocolEol(previousIntentProtocolBlock(10), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyIntentProtocolBlock(), eol)],
     });
@@ -3365,6 +3581,7 @@ const commands = {
         protocolEol(previousDecisionProtocolBlock(7), eol),
         protocolEol(previousDecisionProtocolBlock(8), eol),
         protocolEol(previousDecisionProtocolBlock(9), eol),
+        protocolEol(previousDecisionProtocolBlock(10), eol),
       ],
       knownLegacyBlocks: [protocolEol(legacyDecisionProtocolBlock(), eol)],
     });
@@ -3445,7 +3662,8 @@ usage:
                                  targets: kimi-code (global only), claude-code, codex (prompt only)
   driftseal hook prompt|stop [--format plain|claude-code]
                                  emit the reminder a lifecycle hook injects; never blocks
-  driftseal init                       inject protocols into ./AGENTS.md and configure the git merge driver
+  driftseal init [--lang <tag>]        inject protocols into ./AGENTS.md and configure the git merge driver
+                                 --lang sets the intent/decision log language (BCP 47, default: en)
   driftseal --version | -V             print the installed DriftSeal version
   driftseal help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",