@wnlen/agent-execution-template 0.8.17 → 0.8.18

package/README.md

@@ -444,11 +444,25 @@ Run the self-test:
 npm test
 ```
 
+Run the release consistency check:
+
+```bash
+npm run check:release
+```
+
 The test suite verifies the core CLI contract:
 
 - `init` creates the expected protocol and project files.
 - `update` does not overwrite `ai/project/**`.
 - `doctor` reports missing and empty required files correctly.
+- `check:release` verifies versions, template shape, installed protocol state,
+  and the spec's package version.
+
+When maintaining this npm package source checkout, test the local CLI with
+`node bin/agent-execution-template.js <command>`. Use
+`npx -y @wnlen/agent-execution-template <command>` in user projects only.
+Maintainer-local `ai/project/**` bootstrap content should not be committed as
+product changes.
 
 ## Contributing
 

package/README.zh-CN.md

@@ -449,11 +449,22 @@ License:  MIT
 npm test
 ```
 
+发布前检查：
+
+```bash
+npm run check:release
+```
+
 测试会验证核心 CLI 契约：
 
 - `init` 创建预期的协议和项目文件。
 - `update` 不覆盖 `ai/project/**`。
 - `doctor` 正确报告缺失文件和空的必要文件。
+- `check:release` 验证版本号、模板结构、安装态协议和规格文档一致。
+
+维护这个 npm 包源码仓库时，用 `node bin/agent-execution-template.js <command>`
+测试当前 checkout；用户项目才使用 `npx -y @wnlen/agent-execution-template <command>`。
+维护者本地 `ai/project/**` 初始化内容不应作为产品改动提交。
 
 ## 贡献
 

package/bin/agent-execution-template.js

@@ -155,6 +155,10 @@ const TEXT = {
     nextReviewProposal: "已有方向修订提案。先审查提案；确认后对 AI 说:",
     nextContinuePrompt: "继续推进这个项目。执行前先拆 L1 任务；若 L1 >= 2，自动启用边界内连续执行；只有 Red 风险停下来确认。",
     repairHint: "缺失的 project 推荐文件可通过重新运行 init 安全补齐；已有 ai/project/** 不会被覆盖。",
+    sourceCheckoutNotice: `维护者提示: 当前目录看起来是 @wnlen/agent-execution-template 源码仓库。
+  源码仓库内调试请使用: node bin/agent-execution-template.js <command>
+  用户项目中安装才使用: npx -y @wnlen/agent-execution-template <command>
+  不要把维护者本地初始化产生的 ai/project/** 当成产品改动提交。`,
     permissionDenied: "无法写入目标路径",
     permissionHint: `请检查 ai/** 的归属和权限。常见修复:
   sudo chown -R "$(id -un):$(id -gn)" ai
@@ -260,6 +264,10 @@ Usage:
     nextReviewProposal: "A direction amendment proposal exists. Review it first; after confirmation, tell the AI:",
     nextContinuePrompt: "Continue this project. Before execution, decompose L1 tasks; if L1 >= 2, automatically use bounded continuous execution; only Red risk stops for confirmation.",
     repairHint: "Missing recommended project files can be safely added by running init again; existing ai/project/** files are not overwritten.",
+    sourceCheckoutNotice: `Maintainer note: this directory looks like the @wnlen/agent-execution-template source checkout.
+  In the source repository, test with: node bin/agent-execution-template.js <command>
+  In user projects, install with: npx -y @wnlen/agent-execution-template <command>
+  Do not commit maintainer-local ai/project/** bootstrap content as product changes.`,
     permissionDenied: "Cannot write target path",
     permissionHint: `Check ownership and permissions under ai/**. Common fix:
   sudo chown -R "$(id -un):$(id -gn)" ai
@@ -291,6 +299,17 @@ function readPackageVersion() {
   }
 }
 
+function readTargetPackageName() {
+  const packageFile = path.join(process.cwd(), "package.json");
+  if (!fs.existsSync(packageFile)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
 function readInstalledLang() {
   const langFile = path.join(TARGET_AI, "template", "LANG");
   if (!fs.existsSync(langFile)) return DEFAULT_LANG;
@@ -298,6 +317,24 @@ function readInstalledLang() {
   return SUPPORTED_LANGS.has(lang) ? lang : DEFAULT_LANG;
 }
 
+function isSourceCheckout() {
+  return process.cwd() === PACKAGE_ROOT &&
+    readTargetPackageName() === "@wnlen/agent-execution-template";
+}
+
+function commandHint(command) {
+  if (isSourceCheckout()) {
+    return `node bin/agent-execution-template.js ${command}`;
+  }
+  return `npx -y @wnlen/agent-execution-template ${command}`;
+}
+
+function printSourceCheckoutNotice(lang) {
+  if (isSourceCheckout()) {
+    console.log(`${getText(lang).sourceCheckoutNotice}\n`);
+  }
+}
+
 function parseLang(args, fallback = DEFAULT_LANG) {
   let lang = fallback;
   for (let index = 0; index < args.length; index += 1) {
@@ -487,12 +524,14 @@ function init({ lang = DEFAULT_LANG, verbose = false, quiet = false } = {}) {
     .map((change) => ({ ...change, path: path.join("ai/project", change.path) })));
 
   if (!quiet) {
+    const sourceNotice = isSourceCheckout() ? `${text.sourceCheckoutNotice}\n\n` : "";
     console.log(`${text.ready}
 
 ${text.initGuide}
 
+${sourceNotice}
 ${text.files}: ${summarizeChanges(changes, lang)}
-${text.check}: npx -y @wnlen/agent-execution-template doctor
+${text.check}: ${commandHint("doctor")}
 `);
 
     if (verbose) {
@@ -546,12 +585,13 @@ function next({ lang = readInstalledLang() } = {}) {
   }
 
   console.log(`${text.nextTitle}\n`);
+  printSourceCheckoutNotice(lang);
 
   const templatePath = path.join(TARGET_AI, "template");
   const projectPath = path.join(TARGET_AI, "project");
   if (!fs.existsSync(templatePath) || !fs.existsSync(projectPath)) {
     console.log(`${text.nextRunInit}
-  npx -y @wnlen/agent-execution-template init
+  ${commandHint("init")}
 `);
     return;
   }
@@ -678,6 +718,7 @@ function doctor() {
   const lang = readInstalledLang();
   const text = getText(lang);
   console.log(`${text.doctorTitle}\n`);
+  printSourceCheckoutNotice(lang);
   console.log(`${text.templateVersion}: ${readVersion(path.join(TARGET_AI, "template")) || text.unknown}`);
   console.log(`${text.templateLang}: ${lang}\n`);
 
@@ -748,7 +789,7 @@ function doctor() {
   }
 
   if (missing > 0) {
-    console.log(`\n[${text.fail}] ${text.runInit}`);
+    console.log(`\n[${text.fail}] ${commandHint("init")}`);
     process.exitCode = 1;
   } else if (warnings > 0) {
     console.log(`\n[${text.pass}] ${text.readyWithWarnings}`);

package/docs/SPEC.md

@@ -22,7 +22,7 @@ npx 安装协议 -> AI 整理项目上下文 -> 人类确认 -> AI 生成任务
 
 ```text
 Protocol: v0.8
-Package: @wnlen/agent-execution-template@0.8.17
+Package: @wnlen/agent-execution-template@0.8.18
 中文安装: npx -y @wnlen/agent-execution-template init
 英文安装: npx -y @wnlen/agent-execution-template init --lang en
 ```
@@ -392,7 +392,7 @@ npx -y @wnlen/agent-execution-template doctor
 ```text
 Agent Execution Template 检查
 
-模板版本: 0.8.17
+模板版本: 0.8.18
 模板语言: zh
 
 [通过] ai/template/LANG

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wnlen/agent-execution-template",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "description": "Low-friction AI execution protocol template for coding agents.",
   "bin": {
     "agent-execution-template": "bin/agent-execution-template.js"
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "doctor": "node bin/agent-execution-template.js doctor",
-    "test": "node test/selftest.js"
+    "check:release": "node test/check-release.js",
+    "test": "node test/selftest.js && node test/check-release.js"
   },
   "keywords": [
     "ai",

package/template/en/ai/README.md

@@ -114,22 +114,5 @@ From a real project back into the template repo:
 - Return only `ai/template/**`.
 - Never return `ai/project/**`.
 
-## Bootstrap Rule
-
-- The human provides intent, hard constraints, and final acceptance.
-- The agent drafts `project/project.md` and relevant `project/refs/*` from existing docs, manifests, refs, and project files.
-- The agent drafts `project/task.md` after the human provides the current task goal.
-- The human reviews and confirms project and task drafts before execution.
-- Bootstrap may write only project context files, plus `project/task.md` when a current task is provided.
-- Bootstrap must not edit source code, tests, configuration, dependency files, generated files, runtime files, result files, or metrics files.
-- Ask at most 3 clarification questions.
-- Ask only when the answer changes scope, risk, permission, or acceptance.
-- Repeated assumptions should become `project/runtime.md` update proposals.
-
-## Model Division Protocol
-
-- Model policy lives in `project/task.md.model_policy`.
-- Use `cheap` by default for routine execution.
-- Use `standard` for moderate implementation complexity.
-- Use `strong` only for planning, risk judgment, architecture review, failure review, or acceptance judgment.
-- Record actual tier, trigger, role, and escalation reason in `project/metrics.json`.
+Detailed execution rules live in `template/protocol.md`,
+`template/bootstrap.md`, `template/execution-policy.md`, and `template/rules/`.

package/template/en/ai/template/VERSION

@@ -1 +1 @@
-0.8.17
+0.8.18

package/template/zh/ai/README.md

@@ -112,22 +112,5 @@ ai/project/inbox/ideas/
 - 只回流 `ai/template/**`。
 - 永远不要回流 `ai/project/**`。
 
-## 引导规则
-
-- 人类提供意图、硬约束和最终验收。
-- Agent 从现有文档、清单、引用和项目文件中起草 `project/project.md` 和相关 `project/refs/*`。
-- 人类提供当前任务目标后，Agent 起草 `project/task.md`。
-- 人类在执行前检查并确认项目和任务草稿。
-- 引导只能写项目上下文文件；当提供当前任务时，也可以写 `project/task.md`。
-- 引导不得编辑源码、测试、配置、依赖文件、生成文件、运行时文件、结果文件或指标文件。
-- 最多问 3 个澄清问题。
-- 只在答案会改变范围、风险、权限或验收时提问。
-- 重复出现的假设应变成 `project/runtime.md` 更新建议。
-
-## 模型分工协议
-
-- 模型策略位于 `project/task.md.model_policy`。
-- 常规执行默认使用 `cheap`。
-- 中等实现复杂度使用 `standard`。
-- 只有规划、风险判断、架构复核、失败复盘或验收判断才使用 `strong`。
-- 在 `project/metrics.json` 中记录实际档位、触发条件、角色和升级原因。
+详细执行规则见 `template/protocol.md`、`template/bootstrap.md`、
+`template/execution-policy.md` 和 `template/rules/`。

package/template/zh/ai/template/VERSION

@@ -1 +1 @@
-0.8.17
+0.8.18

package/test/check-release.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..");
+const packagePath = path.join(repoRoot, "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(repoRoot, relativePath), "utf8");
+}
+
+function listFiles(relativeDir) {
+  const root = path.join(repoRoot, relativeDir);
+  const files = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        files.push(path.relative(root, fullPath).split(path.sep).join("/"));
+      }
+    }
+  }
+
+  walk(root);
+  return files.sort();
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    fail(`${message}\nExpected: ${expected}\nActual: ${actual}`);
+  }
+}
+
+function assertIncludes(content, expected, message) {
+  if (!content.includes(expected)) {
+    fail(`${message}\nMissing: ${expected}`);
+  }
+}
+
+function assertFileListsMatch(leftDir, rightDir, message) {
+  const left = listFiles(leftDir).join("\n");
+  const right = listFiles(rightDir).join("\n");
+  assertEqual(left, right, message);
+}
+
+function assertTreesMatch(leftDir, rightDir, message) {
+  const leftFiles = listFiles(leftDir);
+  const rightFiles = listFiles(rightDir);
+  assertEqual(leftFiles.join("\n"), rightFiles.join("\n"), `${message}: file list differs`);
+
+  for (const file of leftFiles) {
+    const left = read(path.join(leftDir, file));
+    const right = read(path.join(rightDir, file));
+    assertEqual(left, right, `${message}: ${file} differs`);
+  }
+}
+
+function main() {
+  const version = packageJson.version;
+  assertEqual(packageJson.name, "@wnlen/agent-execution-template", "package name changed unexpectedly");
+  assertEqual(
+    packageJson.bin && packageJson.bin["agent-execution-template"],
+    "bin/agent-execution-template.js",
+    "package bin entry should point to the CLI"
+  );
+
+  assertEqual(read("template/zh/ai/template/VERSION").trim(), version, "zh template version must match package version");
+  assertEqual(read("template/en/ai/template/VERSION").trim(), version, "en template version must match package version");
+  assertEqual(read("ai/template/VERSION").trim(), version, "installed zh template version must match package version");
+
+  assertFileListsMatch("template/zh/ai", "template/en/ai", "zh and en templates must expose the same file layout");
+  assertTreesMatch("template/zh/ai/template", "ai/template", "installed ai/template must mirror template/zh/ai/template");
+  assertEqual(read("template/zh/ai/README.md"), read("ai/README.md"), "installed ai/README.md must mirror template/zh/ai/README.md");
+
+  const spec = read("docs/SPEC.md");
+  assertIncludes(spec, `Package: @wnlen/agent-execution-template@${version}`, "SPEC package version must match package.json");
+
+  const scripts = packageJson.scripts || {};
+  assertIncludes(scripts.test || "", "test/selftest.js", "npm test should run the CLI selftest");
+  assertIncludes(scripts.test || "", "test/check-release.js", "npm test should run release consistency checks");
+
+  console.log("release check ok");
+}
+
+main();

package/test/selftest.js

@@ -122,6 +122,7 @@ function testInitUpdateDoctor() {
   assert(initOutput.includes("把 ai/project/inbox/ideas/ 里的新灵感生成方向修订提案"), "init output should provide natural strategy prompt");
   assert(initOutput.includes("agent-execution-template next"), "init output should tell users how to recover the next step");
   assert(initOutput.includes("文件:"), "init output should summarize file changes");
+  assert(!initOutput.includes("维护者提示"), "init output should not show source checkout guidance in user projects");
   assert(!initOutput.includes("[已更新]"), "init output should hide detailed file changes by default");
   assert(!initOutput.includes("Read ai/template/bootstrap.md"), "init output should not use weak Read bootstrap command");
   assert(run(["init", "--verbose"], cwd).includes("[已更新] ai/template/VERSION"), "init --verbose should show detailed file changes");
@@ -202,6 +203,7 @@ function testEnglishInitUpdateDoctor() {
   assert(initOutput.includes("Generate a direction amendment proposal from ai/project/inbox/ideas/"), "English init output should provide natural strategy prompt");
   assert(initOutput.includes("agent-execution-template next"), "English init output should tell users how to recover the next step");
   assert(initOutput.includes("Files:"), "English init output should summarize file changes");
+  assert(!initOutput.includes("Maintainer note"), "English init output should not show source checkout guidance in user projects");
   assert(!initOutput.includes("[UPDATED]"), "English init output should hide detailed file changes by default");
   assert(run(["init", "--lang=en", "--verbose"], cwd).includes("[UPDATED] ai/template/VERSION"), "English init --verbose should show detailed file changes");
 
@@ -338,6 +340,16 @@ function testPermissionErrorIsActionable() {
   }
 }
 
+function testSourceCheckoutNotice() {
+  const doctorOutput = run(["doctor"], repoRoot);
+  assert(doctorOutput.includes("维护者提示"), "doctor should warn when run in the package source checkout");
+  assert(doctorOutput.includes("node bin/agent-execution-template.js <command>"), "source checkout notice should show local node command");
+  assert(doctorOutput.includes("不要把维护者本地初始化产生的 ai/project/** 当成产品改动提交"), "source checkout notice should warn against committing local bootstrap context");
+
+  const nextOutput = run(["next"], repoRoot);
+  assert(nextOutput.includes("维护者提示"), "next should warn when run in the package source checkout");
+}
+
 function main() {
   testInitUpdateDoctor();
   testEnglishInitUpdateDoctor();
@@ -345,6 +357,7 @@ function main() {
   testRefreshBacksUpAndImportsOldProject();
   testNextCommandRoutesByProjectState();
   testPermissionErrorIsActionable();
+  testSourceCheckoutNotice();
   console.log("selftest ok");
 }