Repository navigation
fix(init): land init --help contract and --dry-run on top of origin/main - #124
Merged
Merged
Conversation
added 4 commits
October 28, 2026 09:35
Two related defects in the `cortex-agent init` command:
1. `cortex-agent init --help` (and `-h`) silently ran the full init
instead of printing help. The MS-003 help dispatcher (P-009 / M-035)
routes commands to a .help/<name>.md contract before any argument
validation runs, but `init` had no contract registered. Help
requests fell through to the actual init() path, where the
presence of an AGENTS.md at the project root routed the run into
general mode — surprising the user with template writes they did
not intend.
Fix: register `"init": "init.md"` in
lib/commands/agent/help-dispatch.js#CONTRACTS and add .help/init.md
describing --mode / --lang / --track / --global / --platforms /
--update-scripts / --force-scripts / --fix / --dry-run / --verify /
--verify-full / --report / --project. `init --help` and `init -h`
now print the contract and exit zero.
2. `cortex-agent init --mode code` was rejected with
"Unsupported --mode value: code. Only 'general' is implemented in
MS-002. Omit --mode to use the default code-project init." The
MS-002 routing block in bin/cli.js entered on
`options.mode === "general" || args.includes("--mode") ||
args.includes("-m")`, so any `--mode <value>` was funnelled into
the general branch and then rejected if the value was not
`general`. The error message itself contradicted the behaviour
by recommending "omit --mode to use the default code-project init",
leaving users with no way to be explicit about code mode.
Fix: key the MS-002 routing on `options.mode === "general"`
alone. Explicit `--mode code` (and any future mode value) now
falls through to the default code-project init, matching the
behaviour already implied by the error message and by the MS-003
auto-inference in mode-infer.js.
3. Anchor version catch-up: docs/cortex-agent/anchor.md still read
v1.13.0 even though the package was bumped to 1.14.0 in commit
0d1c6fe. The next `init` would rewrite it to v1.14.0; this
commit carries that one-line correction forward so the public
anchor matches the released framework version.
Verified:
cortex-agent init --help # prints .help/init.md
cortex-agent init -h # same
cortex-agent init --mode code --lang zh # routes to default init, no rejection
cortex-agent init --mode general # still routes to initModeGeneral (unchanged)
`cortex-agent init --mode <m> --dry-run` previously ignored the
`--dry-run` flag. The flag was parsed in bin/cli.js (around the
`if (arg === "--dry-run")` block) and forwarded into `ctx.options`,
but neither lib/commands/init.js#init() nor bin/cli.js#initModeGeneral()
read it. As a result:
* `init --mode code --dry-run` still ran migrateOldConfigs +
copyRecursive + script-manifest writes + writePublicAnchor +
linkGlobalConfig + applyGitExclusion.
* `init --mode general --dry-run` did the same on the general
path (data layer copy + general template overlay + version +
anchor + git exclusion + global config link).
Meanwhile cli.js honoured `--dry-run` only for `upgrade` and
`update` (see lines around `installStateGithooks`), so init was the
only mutating command that ignored the flag.
Fix:
* Add `printInitDryRunPlan({ cwd, lang, templateDir, options, mode })`
helper to lib/commands/init.js. Prints a numbered plan covering the
shared-layer copy, template-layer copy, target mode, AGENTS.md
handling (general), platform picker, version / script-manifest /
anchor writes, and Git tracking mode. Bilingual (zh / en) using
the same `isZh` branching as the rest of init.
* Short-circuit at the top of init() and initModeGeneral() when
options.dryRun is set. Returns after printing the plan; no fs
mutation, no platform picker, no anchor write.
* Export printInitDryRunPlan from lib/commands/init.js so
bin/cli.js#initModeGeneral() can call it without duplicating the
plan format.
* In bin/cli.js, wrap the `case "init":` installStateGithooks call
in `if (!ctx.options.dryRun)`, mirroring the upgrade + update
branches.
Verified end-to-end in a throwaway directory:
cd /tmp/cortex-agent-dryrun-test && cortex-agent init --mode code --lang zh --track --dry-run
-> plan printed, directory remained empty, .agent/ mtime unchanged
cortex-agent init --mode general --lang zh --dry-run
-> plan printed (mode: general, AGENTS.md keep-or-seed line shown),
no files written
Subsequent real init in the same directory (no --dry-run) wrote the
expected .agent/ tree + anchor + AGENTS.md + platform configs without
regression on the dry-run code path.
Rebasing the local init commits onto origin/main surfaced the CLI's zero-write help guard: `tests/cli/help-zero-write.test.js` asserts that `init --help` prints a literal `Usage: cortex-agent ...` line. The .help/init.md contract used the `## Usage` + indented block form that the other .help/ contracts use, so the assertion failed even though the contract itself was correct and the command wrote nothing. Add the usage line under the title, matching how every other CLI command emits its usage (e.g. `Usage: cortex-agent export-anchor ...`). Verified: cli/help-zero-write, cli/help-distribution, cli/upgrade-help-zero-write, commands/anchor all pass.
Sync the governance repo pointer to the merged state that carries the local decision / experience / update records and the context-budget, friction and mission-progress skills, on top of the 547 commits pulled from the governance repo's own origin/main. The governance repo merge resolved 19 add/add conflicts by taking the remote (Chinese source-of-truth) side; the local-only assets were kept, and the .gitignore was extended with *.bak / *.bak.prev.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
本地
main停在e2baa3e（2026-08-13），落后origin/main383 个 commit，本地另有 2 个未推送的独有 commit。本 PR 是把这 2 个 commit 重放到当前上游之上后的结果。变更内容
1.
fix(init): surface init --help and route --mode code to default init（d996f0f）.help/init.md契约文档（84 行），把init接入上游.help/契约分发机制（
help-dispatch.js的CONTRACTS映射新增init→init.md）init --help/-h在参数校验之前解析契约，缺失必填参数也不阻塞 helpinit --mode code路由到默认 init 流程，不再被拒绝docs/cortex-agent/anchor.md版本锚点同步2.
fix(init): honour --dry-run for code and general init（f80a680）lib/commands/init.js新增--dry-run：只打印 init 计划、不写任何文件3.
fix(help): align init contract with the CLI zero-write assertion（40a033e）Rebase 后暴露出上游
tests/cli/help-zero-write.test.js断言init --help输出需含字面量Usage: cortex-agent ...，而契约文档用的是## Usage+ 缩进块式。在标题下补一行 Usage，与其它 CLI 命令（如
Usage: cortex-agent export-anchor ...）保持一致。4.
chore(agent): 推进治理仓 gitlink 至 d24459e1（798a060）把治理仓（
Kucell/cortex-agent-agent.git）指针推进到合并后的状态：本地落后 547 commit，合并后带入本地独有的决策 / 经验 / 更新记录与 context-budget、friction、mission-progress 技能。
治理仓合并的 19 个 add/add 冲突全部取远程版本（远程是完整中文正本，本地是未完成的英文骨架；
hooks/claude-code-transcript-link-reporter.sh远程版还把示例里硬编码的/Users/xueyq/myworks/换成了
<user>占位符）。.gitignore取远程版并补*.bak/*.bak.prev。Rebase 冲突处理
唯一冲突是
docs/cortex-agent/anchor.md的版本锚点：本地刷到v1.14.0，上游已通过fix(anchor): 锚点纳入版本载体，随发布自动刷新 (#118)自动刷到v1.15.6。采用上游版本，锚点保持
v1.15.6。验证
全量测试 489 个用例，本地 489/489 全绿（失败文件 0），GitHub CI 全 SUCCESS。
过程中的一次归因修正
Rebase 完成后本地一度有 25 个测试文件失败。当时做了两组对照（「本地 2 commit」与
「纯 origin/main」各跑一遍全量），两组失败集合几乎一致，于是初步判为「上游既有失败」。
这个归因是错的。 真正原因是主仓的
.agent是 submodule（独立仓Kucell/cortex-agent-agent.git），本地落后 547 commit，而大量测试直接require("../../.agent/skills/...")读取它的脚本 —— 两组对照共用同一个落后的 submodule，失败必然同时出现，对照因此失效。把
.agent合并到最新后，失败文件从 25 降到 0。也就是说：这不是本 PR 引入的回归，而是本地依赖落后；本 PR 的治理仓同步（
798a060）正是修复它的那一环。
备注
tests/cli/help-zero-write.test.js在40a033e后由失败转为通过。decisions/D-approved-ordering-2026-09-27.json、experiences/EXP-004.md、updates/U-*.json、skills/context-budget/scripts/*、skills/friction/、skills/mission-progress/、scripts/proposal-share.js、general/skills/prompt-inject/）在合并中全部保留。🤖 Generated with Claude Code