msdevflow 0.8.0 → 0.8.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2025-2026 GitCode msdevflow contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/bootstrap.js

@@ -1180,10 +1180,16 @@ function npmGitcodeDiagnosis(executable, doctor) {
         };
       }
     } catch {
-      // Fall through to the fail-closed ownership error.
+      // Fall through to coexist.
     }
   }
-  throw new BootstrapError(`Existing gitcode has unknown ownership: ${executable}. Refusing to overwrite it.`, 3);
+  // doctor failed: existing gitcode is not the npm official CLI.
+  // Coexist by installing npm CLI alongside and using gitcode-npm.
+  return {
+    classification: "python", // triggers coexist mode, installs npm CLI separately
+    existingExecutable: executable,
+    workflowCommand: "gitcode-npm",
+  };
 }
 
 export function diagnoseGitcode(run, platform) {
@@ -1512,6 +1518,10 @@ function wrapperContent(details, platform) {
     : `#!/usr/bin/env bash\nexec ${shellQuote(details.cliTarget)} "$@"\n`;
 }
 
+function isNpmGitcodeShim(content) {
+  return /@gitcode-cli|gitcode\.js/i.test(content);
+}
+
 function validateWrapper(details, platform) {
   const existing = readOptionalFile(details.wrapper);
   if (existing === null) {
@@ -1521,7 +1531,7 @@ function validateWrapper(details, platform) {
   if (platform !== "win32") {
     accepted.push(`#!/usr/bin/env bash\nexec "${details.cliTarget}" "$@"\n`);
   }
-  if (!accepted.includes(existing)) {
+  if (!accepted.includes(existing) && !isNpmGitcodeShim(existing)) {
     throw new BootstrapError(`Refusing to overwrite unrelated wrapper: ${details.wrapper}`, 3);
   }
 }
@@ -1562,6 +1572,32 @@ function writeWrapper(details, platform) {
   }
 }
 
+function removeNpmGitcodeShims(npmPrefix, platform) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const candidates = platform === "win32"
+    ? ["gitcode.cmd", "gitcode"]
+    : ["gitcode"];
+  for (const name of candidates) {
+    const file = pathApi.join(npmPrefix, name);
+    try {
+      const metadata = lstatSync(file);
+      if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        continue;
+      }
+      const content = readFileSync(file, "utf8");
+      // Only remove if it looks like an npm shim for @gitcode-cli/cli.
+      if (!/@gitcode-cli|gitcode\.js/i.test(content)) {
+        continue;
+      }
+      unlinkSync(file);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
 async function installGitcode(plan, runLong, run, platform) {
   await runLong(plan.installInvocation);
   if (plan.gitcodeInstall.mode === "coexist") {
@@ -1570,6 +1606,8 @@ async function installGitcode(plan, runLong, run, platform) {
       `Installed GitCode npm CLI target not found: ${plan.gitcodeInstall.cliTarget}.`,
     );
     writeWrapper(plan.gitcodeInstall, platform);
+    // Remove any global npm gitcode shims so PATH falls through to Python gitcode.
+    removeNpmGitcodeShims(plan.gitcodeInstall.wrapperDir, platform);
     return {
       command: plan.gitcodeInstall.workflowCommand,
       executable: plan.gitcodeInstall.wrapper,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {
@@ -27,5 +27,5 @@
     "gitcode",
     "setup"
   ],
-  "license": "UNLICENSED"
+  "license": "MIT"
 }

package/skill/msd/SKILL.md

@@ -64,7 +64,9 @@ msd-merge
 4. 不执行下游 action。例如 `action=ci` 通过后不得处理 feedback 或 merge；`action=pr` 创建 PR 后不得自动触发 CI。
 5. action 自身为安全完成所必需的复验属于本 action：例如 `pr` 在提交前重新运行适用本地门禁，`feedback` 修改后运行受影响本地测试。这不授权执行独立的下游 `ci`、补做缺失的产品实现或扩大范围。
 6. `ci` 和完整 E2E 在 openLiBing 只读接口返回 401/403 时可运行 OAuth 认证子流程并恢复原流程；这是读取当前 CI 证据的必要步骤，不视为越界执行显式 `openlibing-auth` action。
-7. 所有远端写仍遵循 guided/autonomous 授权、UTF-8、尾签、幂等和最终 merge 确认规则。
+7. 每个 action 在自身边界内连续执行到完成状态；不得在分析、设计、编辑、验证等中间步骤询问是否继续。能从权威证据、仓库约定和已确认目标可靠推导的结论直接采用，并报告依据，不把可自行完成的判断转交用户。
+8. 只有证据缺失或矛盾且不同选择会实质改变范围、公共行为、兼容性、性能目标或风险，或安全契约明确要求确认时才询问；其余不影响已确认语义的实现细节选择最小、可逆且符合仓库惯例的方案。
+9. action 内端到端完成不授权执行其上游或下游 action，也不替代 guided/autonomous 授权、UTF-8、尾签、幂等和最终 merge 确认规则。
 
 ## 完整作者 E2E
 
@@ -109,7 +111,7 @@ discovered -> claimed -> verified -> analyzed -> designed
 -> approved -> merge-confirmed -> merged
 ```
 
-任一状态可进入 `blocked`。状态晋级必须有远端或本地证据，不能只依据先前文本声明。`issue-created` 和 `openlibing-authenticated` 是独立 action 的完成状态，不改变作者主流程的业务阶段；`issue-created` 不自动进入 `claimed`，`openlibing-authenticated` 也只作为 `ci`/E2E 的条件性认证子状态。`review-findings`、`review-passed` 和 `review-incomplete` 仅属于独立 `code-review`，按 reviewer 与固定 `review_head_sha` 绑定，不进入作者状态机。
+任一状态可进入 `blocked`。状态晋级必须有远端或本地证据，不能只依据先前文本声明。`designed` 的证据按 [references/design-and-development.md](references/design-and-development.md) 的分级和实际触发维度确定：simple 使用最小设计记录；standard/complex 使用决策树结论，并分别为行为、领域与数据、兼容性、性能等触发维度提供对应证据，未触发的维度不强制生成产物。用户原始请求已完整表达 simple 的最小设计时即视为确认；其他适用设计内容由用户整体确认后才进入实现。`issue-created` 和 `openlibing-authenticated` 是独立 action 的完成状态，不改变作者主流程的业务阶段；`issue-created` 不自动进入 `claimed`，`openlibing-authenticated` 也只作为 `ci`/E2E 的条件性认证子状态。`review-findings`、`review-passed` 和 `review-incomplete` 仅属于独立 `code-review`，按 reviewer 与固定 `review_head_sha` 绑定，不进入作者状态机。
 
 ## 全局不变量
 

package/skill/msd/references/design-and-development.md

@@ -4,32 +4,69 @@
 
 ## Phase 3：需求分析与设计决策树
 
-先搜索 Issue、评论、仓库文档和代码；材料中已有的事实不要反问用户。输出：
+先只读搜索 Issue、评论、仓库文档和受影响代码，优先从材料建立事实；材料中已有答案时不得反问用户。先按下方门禁完成一次分级，该结果同时决定设计负载和归档要求。
 
-- 当前理解；
-- 范围和非目标；
-- 验收标准；
-- 兼容性与风险；
-- 依赖和待确认项；
-- 候选方案及权衡。
+### 设计分级与归档门禁
 
-对关键歧义建立决策树：上游目标和行为优先，下游模块、实现和测试随后；显式标明依赖。每轮只问一个最高价值问题，同时给推荐答案和理由，直到用户确认方案。
+识别本次变更触发的风险维度：
 
-### 设计归档门禁
+- **行为**：新增或改变用户流程、交互语义、可访问性语义、公共行为或接口契约；按已有明确契约恢复原行为，或做不改变语义的局部文案/样式修正，不单独触发本维度；
+- **领域与数据**：正确性依赖表关系、基数、唯一性、顺序、时间语义等领域不变量；
+- **兼容性**：新旧数据、接口、行为或调用方需要共存或迁移；
+- **性能**：改动可能改变查询计划、I/O 或调用次数、遍历/匹配/过滤范围、缓存命中、内存分配，或其他随数据规模增长的成本；仅修改不影响执行路径的查询常量或拼写不触发本维度。
 
-先分类变更复杂度。满足任一条件时，必须在仓库约定位置创建或更新 RFC/design：
+按且仅按以下一档执行：
 
-- 新增或改变用户交互、快捷键、可见 UI 或公共行为；
-- 新增会话/持久化状态、数据模型、接口或生命周期重置规则；
-- 横跨多个组件、模块或前后端；
-- 涉及兼容性、迁移、安全、性能或重要测试策略；
-- Issue、仓库规范或维护者要求设计文档。
+1. **simple**：局部、预期行为已有明确证据、无风险维度、无新状态，且不引入新的公共语义；可以恢复已有明确契约，或做不改变语义的局部文案/样式修正。只输出需求事实、改动范围、验收方式和跳过独立设计文档的理由；用户原始请求已明确覆盖这些内容时即视为整体确认，不重复询问，否则最多询问一个会影响实现的未决事实，并把回复视为整体确认。
+2. **standard**：范围限于单个组件且只触发一个风险维度，并且不新增或改变持久化状态、数据模型、公共接口，不涉及迁移或安全。建立决策树，只产出被触发维度的证据，不要求独立 RFC/design。
+3. **complex**：触发两个及以上风险维度；或跨多个组件/模块/前后端；或新增、改变持久化状态、数据模型、公共接口、生命周期、迁移、安全或重要测试策略；或 Issue、仓库规范、维护者要求设计文档。建立完整决策树，并在仓库约定位置创建或更新 RFC/design。
 
-只有局部、行为明确、无新状态且不改变用户可见行为的简单修复，才可以不创建独立设计文档；跳过时必须记录理由。
+分级不确定时按更高一级处理。simple 的最小设计记录、standard 的决策树结论、complex 的归档文档都是 `designed` 状态的设计产物。
 
-设计产物至少包含：需求事实、范围/非目标、决策树结论、状态与数据模型、交互流程、文件级计划、兼容性/风险、重置与恢复、测试方案、候选方案及取舍。实现复用建议必须与产品需求语义分开描述。
+### 决策树与提问
 
-**硬门禁：设计产物已落盘、路径已报告、内容经用户确认之前，不得创建工作分支或修改代码。** 若发现已经越过门禁，立即暂停实现，盘点现有修改，补齐并确认设计；不得用事后文档默认为已批准。
+standard 和 complex 按依赖顺序建立决策树，上游未闭环前不得跳入下游：
+
+1. **目标与成功标准**；
+2. **范围与非目标**；
+3. **事实、约束和风险维度**；
+4. **目标模块、行为与接口契约**；
+5. **实现策略**：数据结构、算法、过滤时机和复用边界；
+6. **测试、性能验证、迁移/回滚和 PR 范围**。
+
+显式标明决策依赖和被否决方案。只有材料缺失、矛盾、过时或无法证明且会改变设计的事项才问用户；每轮只问一个最高价值问题，并给出推荐答案和理由。所有分支闭环后合并展示一次完整设计供用户确认；用户已明确确认完整方案时不重复确认各小节。
+
+### 领域事实与数据模型
+
+触发"领域与数据"维度时先发现后确认，不得只凭变量名、单个样本或实现习惯推断：
+
+- 读取受影响链路中的权威定义和最小充分上下文，如 schema/迁移、实体或协议定义、生产者写入逻辑、消费者查询、现有测试和代表性样本；
+- 对关键结论引用可定位的文件、符号、测试或命令证据；样本只能证明现象，不能单独证明唯一性等不变量；
+- 列出关键字段、基数关系（1:1 / 1:N / N:M）、唯一确定规则、顺序与时间语义、缺失/重复数据行为；
+- 将结论区分为已验证事实、由证据推导的结论和仍未证实的假设；只有最后一类且会影响设计时才询问用户。
+
+### 兼容性分析
+
+触发"兼容性"维度时：
+
+- 记录改前行为，并用仓库内引用、签名和数据格式枚举已知调用方；可能存在仓库外消费者时显式记录风险，不假装已穷举；
+- 列出新旧数据、接口和可见行为的差异，以及旧路径、旧格式、错误/缺失数据的处理方式；
+- 明确兼容或迁移策略、回退方式、退役条件和验证用例。除非 Issue 明确要求改变，现有可观察行为默认保持不变。
+
+### 性能基线
+
+触发"性能"维度时：
+
+- 必须先记录改前静态基线及证据：查询/I/O 次数、遍历与数据结构、处理数据范围、时间和空间复杂度；不得只用同阶 Big-O 证明性能不劣化；
+- 有现成 benchmark、profiling 工具或可重复代表性数据时，改码前运行并记录命令、环境、数据规模和结果；热点路径、查询次数或同阶算法常数可能变化时，应优先补最小可重复基准；
+- 无法安全获得运行基线时不伪造数据，改用查询次数、扫描范围、分配量和复杂度上界作为静态预算，并披露未测量风险；
+- 写明改后目标和最终复测方法。默认不得增加渐进复杂度、查询往返或无界扫描，也不得出现超出测量波动的稳定回退；确需接受劣化时必须在设计阶段说明收益和代价并取得用户确认。
+
+### 设计产物门禁
+
+设计产物按分级包含最小记录或归档文档：simple 覆盖需求事实与证据、改动范围和验收方式；standard/complex 还须覆盖范围/非目标、决策树结论、触发风险维度的分析、文件级计划、测试与回滚。实现复用建议必须与产品需求语义分开描述。
+
+**硬门禁：对应分级的设计产物已展示、内容经用户整体确认之前，不得创建工作分支或修改代码；complex 还必须先落盘并报告路径。** 若发现已经越过门禁，立即暂停实现，盘点现有修改，补齐并确认设计；不得用事后文档默认为已批准。
 
 ## Phase 4：分支和计划
 
@@ -61,15 +98,27 @@ git switch -c <branch> <canonical-remote>/<default-branch>
 
 失败必须修复或记录 blocker。不能验证 UI 或运行全量测试时，执行风险匹配的最小集合并披露未运行项。不得声称未执行的检查通过。
 
+### 实现对照设计验证
+
+- **simple**：实现后运行受影响测试和最小适用门禁，确认结果符合最小设计记录。
+- **standard/complex**：逐项修改后只核验该项实际影响的设计维度，不重复验证未受影响维度；实现全部完成后，在进入 `locally-verified` 前对所有触发维度至少完整验证一次。
+- 触发"领域与数据"时，用测试或可重复查询验证关键基数、唯一性、顺序、时间范围及缺失/重复数据行为。
+- 触发"兼容性"时，分别验证设计产物中的新旧路径和行为差异清单。
+- 触发"性能"时，执行设计产物约定的复测并与改前基线或静态预算对比；无法实际测量时报告未验证项，不得声称性能未劣化。
+
+正常实现不暂停询问用户。只有发现影响范围、行为、兼容性、性能目标或已确认领域事实的实质偏差时才停止，集中报告偏差、影响和推荐处理方式；命名或局部结构等不改变设计的小偏差直接修正并在最终报告披露。
+
 实现完成后展示：
 
 ```text
 Changed files and purpose
 Scope deviations: none | details
+Design dimensions verified: behavior | domain/data | compatibility | performance
+Performance comparison: not-applicable | baseline vs result | static budget | unverified + reason
 Local gate commands and results
 Unrun checks and reason
 git diff summary
 Next state: locally-verified | blocked
 ```
 
-达到 `locally-verified` 后立即停止，确认工作分支不是默认分支，且变更范围与已确认设计一致。显式 `action=develop` 不 commit、不 push、不创建 PR；建议下一个 action 为 `pr`。
+达到 `locally-verified` 后立即停止，确认工作分支不是默认分支；simple 的变更范围与最小设计记录一致，standard/complex 的变更范围与已确认设计产物一致。显式 `action=develop` 不 commit、不 push、不创建 PR；建议下一个 action 为 `pr`。

package/skill/msd/references/state-and-safety.md

@@ -107,11 +107,13 @@ Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普
 
 ## Guided 检查点
 
+确认只用于真实决策或受保护动作，不用于汇报内部步骤。每个 action 在取得适用确认后连续执行到自身完成条件，不询问“是否继续分析/修改/测试”，也不要求用户代选可由权威证据、仓库约定和已确认目标可靠推导的实现细节。用户原始请求或本轮已确认内容已经明确授权同一目标、范围和动作时不重复确认；安全契约明确规定必须针对当前事实重新确认的 merge、`code-review` finding/`/lgtm` 等例外不复用旧确认。
+
 开始以下动作前确认：
 
 - 创建 Issue 的最终目标、模板、标题、正文、开放里程碑选择和其他元数据预览；
 - 自领/修改 Issue assignee 或发布接取评论；
-- 需求分析和方案选择；
+- 权威证据和用户原始请求无法唯一确定、且会实质改变范围、公共行为、兼容性、性能目标或风险的需求结论和方案选择；
 - 修改范围发生变化；
 - 首次 push；
 - 创建 PR，包括从目标 Issue 继承的里程碑及创建后必要的 `pr edit --milestone`；