0.4.0

Release notes

0.4.0 — 2026-09-20

Every one of the 118 engineering Rule items now carries the evidence that makes it active, where 16 did before. That is the substance of this release: a criterion you cite now tells you what its tools cannot decide, or shows you a worked pass and a worked failure, or names the fixtures that forward-test it.

Two contracts changed in ways that need action. Read Upgrade notes before updating if you emit findings or author Rule items.

Upgrade notes

• A finding now carries a maturity. findings-list moved to 2.0.0 because a previously absent element became required. Every finding states ready or provisional — how well prepared the criterion behind it is, taken from the Rule item that produced it. A finding with no deriving Rule item is ready. If you have your own reviewer emitting findings, add the element; if you consume findings, the value is additive and nothing you read today breaks.

• blocking is gone from Rule governance. workflow-rule-governance moved to 2.0.0. Its activation constraint used to scale obligations by "blocking item", a term nothing defined, so the population it reached was undecidable. Each obligation now names its enforcement class directly. If you cited the old wording, cite the class.

• An authored Rule item owes new rows. An automated item owes Verification, a tool-assisted item owes Tool limits, a judgment item owes Worked pass and Worked failure. The rows are conditional on enforcement, so an item missing one is reported as provisional rather than failing validation — your existing items keep working, and the report tells you what they still owe.

• cortex rejects an option a command does not define. cortex update replaces the command you have installed, so this takes effect the moment you update. A script passing an unrecognised flag used to have it ignored and now fails.

• Rollback: nothing in this release writes to your project. Pinning the previous tag restores the previous assets.

Added

• A Rule set for a value written down twice. literal-and-copy-quality, prefix LIT, seven items: one defining place for a value more than one runtime reads, display formats from a formatting API rather than string slicing, whole copy entries rather than concatenated fragments, full language coverage, fallback copies that agree with their source, no time-varying value in the display layer, and a declared, bounded enum where its values are natural-language words.

  None of the seven blocks a merge. The proposal behind them asked for five automated blocking items; the evidence was one project carrying three runtimes, and this repository admits an automated blocking item only after three representative shapes. Every item is tool-assisted or judgment until adopting projects supply that evidence.

• A design-time question about where a value lives. TDES-028 asks a technical design to name the single place each shared value is defined, how each runtime obtains it, and how a copy that cannot read that place is reconciled. It refuses a location stated as intent rather than a path.

• A check that keeps the findings contract from drifting. A review Skill that restates the finding element list, rather than citing the Spec, is now reported. Twelve Skills here had copied that list, so a change to the Spec reached fifteen consumers and silently missed twelve.

Changed

• Every Rule item states what its evidence cannot settle. All 47 tool-assisted items now say what their tool class cannot decide, so a clean tool run is never read as a passed item. A taint analyzer silently passes a sink it has no rule for; a benchmark cannot establish a complexity class from the points it measured; repeated green runs bound flakiness without disproving it.

• Every judgment item shows where the line is. All 41 now carry a worked pass and a worked failure. A judgment item has no tool to calibrate against, so the example is the only place you learn what its author meant. TDES-020 fails on "Postgres, because it is mature and widely adopted" and passes on a reason naming a property of the system being designed.

• Thirty automated items name their verification. Sixteen point at the fixtures that already forward-tested them, ten gained forward tests, and four read adopter — they govern a population this repository cannot host, such as a running service's indicators or a benchmark suite, and CONTRIBUTING now documents how an adopting project returns that evidence.

• The link-graph criteria describe a healthy graph. doc-health-criteria moved to 2.0.0.

• Twelve review Skills cite the findings Spec rather than restating what a finding carries.

Fixed

• A Rule that means to be modeled no longer drops silently out of validation. A misspelt model field used to remove a document from the checked set while the run stayed green.

• cortex no longer ignores an option a command does not define, and its confirm-or---yes branches collapsed into one condition.

• A malformed fixture now names its file. Two scripts reported a parse error with a line and column and no path.

Removed

• The inbound proposal channel. Four months, twelve messages, none acknowledged; nothing reached this repository through it. Proposals go through the contribution process in CONTRIBUTING.

0.3.0

Release notes

0.3.0 — 2026-09-18

A minor release. It adds a tenth engineering Rule set and the reviewer that runs it, so orchestrate-code-review now has a seventh cognitive step. Nothing you already adopted changes its obligations, but one rule you may have copied from now points at two of them instead of stating them.

Added

• A Rule set for where a defect is decided and whether the failure can be acted on. error-surfacing-quality, prefix ERR, six items: decide untrusted input at the boundary it enters, stop once an invariant is known broken, detect at the earliest layer your project declares, and give a person the next action or a program a stable identifier. Two items are major, four are minor.

• review-error-surfacing runs it, and joins orchestrate-code-review as a seventh cognitive step. If you invoke the orchestrator, it runs without any change on your side. The Rule is project-scoped, so it stays in the canonical clone and loads on demand.

• Its sixth item is about your check suite, not your code. A check whose findings are mostly legitimate use must be narrowed, retargeted or withdrawn rather than left for readers to filter — a report that is mostly legitimate teaches its readers to skim. It needs a declared threshold to run, so it stays inactive until you set one.

• Two project parameters, both optional. error.detection_layers lists the layers your project can decide a defect at, earliest first. error.false_positive_threshold is the share of a check's findings that may be legitimate use before the check must be narrowed. Leave either unset and only its own item is unevaluable; the baseline items still run.

• A maintainer guide for releasing this repository, at docs/guides/releasing.md. Relevant if you maintain a fork.

Changed

• standards-coding points at two obligations instead of stating them. Its error-handling constraint had carried "fail fast" and "messages carry context and a suggested resolution"; those are now error-surfacing-quality's, defined precisely enough to waive. Its simplicity constraint had carried "keep no commented-out dead code"; that is architecture-quality ARC-010's. What stays is what only this document says: one consistent error-handling mechanism, and resources released on the error path.

  Worth knowing if you install user-scoped rules only. standards-coding is user-scoped and lands in your editor's rules directory, while both targets are project-scoped and load on demand — so you now get a pointer where you used to get the text.

Upgrading

cortex update

Nothing to migrate, and nothing breaks. The new Rule set is additive, and its two major items only produce findings when you run a review that loads them.

If you want the new reviewer active in your own review runs, nothing is required: orchestrate-code-review dispatches it. If you want its two project parameters to do anything, declare them in .ai-cortex/config.yaml.

cortex update hard-resets the canonical clone onto origin and refuses to run on a dirty tree; keep local edits on a branch or a fork rather than in that clone.

v0.2.1 — a rule you could copy

A patch release. One correction reaches a rule you may have copied from; everything else hardens this repository's own checks and does not change an asset you install.

Fixed

• workflow-documentation carried a regex that could not be copied. The version-narration pattern contains a backtick and sat inside a single-backtick code span, where a backslash does not escape it — the span closed early and the rest rendered as prose. Anyone who copied that pattern got something that does not compile. It is written as a double-backtick span now, and all 35 patterns in that section compile.

Changed

• workflow-documentation says which of its patterns are enforced. Part of its detection list runs in CI and part needs a reader, and the rule now states the split rather than leaving you to assume the whole list is automated. The Chinese conversational residue and heading suffixes are not automated because they match almost nothing; conversational shorthand is not, because the criterion excuses a shorthand that the document defines, and no grep can decide that.
• Five rules take a patch bump: standards-coding 1.0.2, standards-import 1.0.1, standards-shell 1.0.1, writing-chinese-technical 1.3.1, workflow-documentation 1.1.1. Four of them changed only in frontmatter, gaining the artifact_type and status their peers declare.

Upgrading

cortex update

Nothing to migrate. No rule's obligations changed, so a project that adopted these rules needs no action beyond the update.

cortex update hard-resets the canonical clone onto origin and refuses to run on a dirty tree; keep local edits on a branch or a fork rather than in that clone.

Full diff: v0.2.0...v0.2.1

v0.2.0 — engineering criteria leave the Skills

Engineering criteria leave the Skills, and the checks gain teeth.

67 skills · 29 rules · 19 specs · 1 protocol

Review criteria are canonical Rules now

They used to live inside the Skills that executed them, so they could not be applied before coding, configured per project, or cited afterwards. Nine modeled Rule sets now carry 104 items across architecture, security, reliability, performance, observability, testing, implementation alignment, task quality and technical design quality — with stable identifiers that are never reused, applicability profiles, project parameters and auditable waivers. Execution stays in the Skills, six of which are new.

Severity is graded by what happens if a finding is left unfixed, so 63 of the 104 block a gate rather than all of them.

Research entries

deep-research, policy-research, market-research, competitive-research and product-opportunity-analysis, with an internal assessment behind the package entry, and the Research Report and Opportunity Package contracts they pass between them.

English is the primary language

The repository reverses from Chinese to English. The immutable records stay as written — existing ADRs, released changelog entries and design snapshots — because rewriting them would falsify what they record.

CI blocks instead of advising

markdownlint over its full default rule set, relative links and reference direction between asset layers, orphaned documents, temporary filenames, and temporary documents that are not labelled as one.

Each check has a fixture suite, and scripts/mutation-check.py seeds 43 defects to require every one of those suites to fail when its checker is broken. A suite that asserts findings over fixtures passes just as happily when the checker has stopped looking; that is what the harness is for.

Breaking changes

• Skills renamed and removed
• Review Skills at 2.x, as their criteria leave them for the canonical Rules
• Chinese-first documents rewritten in English

Upgrading

cortex update

Full changelog — 23 entries

Added

• 语言方案反转:仓库主语言从中文切换为英文。docs/LANGUAGE_SCHEME.md 重写为英文并反转原则——英文为默认,中文仅保留于不可变记录(既有 ADR、已发布 CHANGELOG 条目、设计快照)。这三类按 rules/adr-management.md「写入后不改」保留原文,改写它们等于伪造时点记录。新增第 6 节「翻译质量门槛」:明确禁止机器翻译,要求「重写而非翻译」——本仓库已为机翻付过一次代价(164 处重复直译标题、27 处误译),反向迁移不能重演。第 7 节列出 E0–E6 分阶段迁移表,每阶段独立可发布;skills/INDEX.md 与全部 frontmatter 全程保持英文,因此迁移期间发现与技能匹配不受影响。
• E1 阶段完成:README.md / AGENTS.md / CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md 改写为英文。CONTRIBUTING 新增一条硬要求——外部派生技能的许可证兼容性:本仓库为 MIT,派生自 copyleft 或非商业上游(CC BY-NC-SA、AGPL 等)的技能无法以 MIT 再分发,不予接受,须在动手前而非事后核对上游许可证。README 标题变更导致 15 个技能 README 的锚点 #-安装与使用 失效,已同步更新为 #-install-and-use。
• Engineering review criteria move out of the Skills that executed them and into versioned Rule sets. They had lived inside the cognitive review Skills, so they could not be applied before coding, configured per project, or cited afterwards. specs/rule-modeling.md defines RULE_MODEL_V1 — stable item identifiers that are never reused, three applicability levels, parameter provenance and the waiver object — and nine Rule sets now carry 102 items across architecture, security, reliability, performance, observability, testing, implementation alignment, task quality and technical design quality. Of those, 53 are baseline and apply wherever the set's scope is present, 42 are gated on a profile and 7 on a declared project parameter. Severity is graded by what happens if a finding is left unfixed, so 63 block the gate rather than all 102: absent evidence such as a missing test or measurement raises future risk rather than causing a present failure, and is minor. rules/workflow-rule-governance.md constrains identifier stability, compatibility and the activation evidence each enforcement strength owes — and says when a set should adopt the model at all, which is only when its items must be waived, counted in coverage or cited by another artifact, so requirement and functional design quality deliberately stay checklists. Six review Skills are new (functional design, technical design, tasks, implementation alignment, observability, reliability) and four cognitive reviewers now execute the canonical Rules instead of their own embedded lists. scripts/validate-rules.py validates every modeled document and item, and scripts/test-rule-scenarios.py decides the 15 items that are both automated and blocking over nine representative shapes drawn from three populations — a library, a layered application and a distributed service. Both run in CI. The four rewritten reviewers went to a major version — review-architecture, review-performance, review-security and review-testing, with review-requirements alongside them — although their code-scope → findings-list contract did not change: what changed was the authority their criteria come from and what completeness now means, which is breaking for a caller relying on the old embedded checklists even though the artifact types still match. Recorded in docs/adr/0012-adopt-profiled-engineering-rules.md.
• Five research entries, an internal assessment, and the two contracts they pass between them. deep-research, policy-research, market-research, competitive-research and product-opportunity-analysis are user-invocable; assess-product-opportunity carries the recommendation logic and is internal by repository metadata, while the package entry selects the relevant lanes and aggregates their output. specs/research-evidence.md defines a portable Research Report whose decision-relevant statements trace to a source or to an explicit gap, and specs/opportunity-package.md the decision layer built on it. docs/adr/0013-research-skill-entry-names.md records the narrow naming exception: four of the five names are noun-led and the package entry lacks the usual orchestrate- prefix, which is kept because renaming would break commands already promised to users, and it does not loosen the verb-noun rule for anything else. scripts/test-research-artifacts.py validates 10 positive fixtures and 26 negative cases in CI, including a conflicting report, a stale source and an inaccessible one. Live routing through an authenticated host is not yet verified; docs/references/research-skills-smoke-test.md separates what was checked locally from what still waits.
• Two criteria for code that has outlived its use, which the Rule sets had no item for. architecture-quality 1.0.1 → 1.1.0 adds ARC-010 and ARC-011, bringing the nine sets to 104 items. ARC-010 requires code no consumer reaches to be removed rather than commented out, disabled behind a permanent flag or kept in case it is wanted again, and fixes what counts as knowing it is unreached: unused-symbol analysis over the built artifact, plus a runtime signal over one full business cycle for anything the analyzer cannot resolve — reflection, a class named in configuration, dynamic dispatch, a consumer in another repository. Its pass condition says outright that a clean analyzer run is not evidence about a symbol the analyzer cannot see, which is the failure that deletes something month-end still calls. ARC-011 requires a deprecation marker to record who removes it, by which release or date, and what a caller migrates to; a marker carrying none of the three is a second implementation kept indefinitely rather than a migration in progress. Both are minor and tool-assisted, graded by the set's own rule that debt raising future cost does not block a gate the way a present failure does. review-architecture picks them up with no change to its execution, since it runs whichever items the active Rule version carries; 2.0.1 → 2.1.0 adds a worked example for each, because both turn on a distinction a reviewer gets wrong by default — an analyzer reporting nothing is not a pass for what it cannot resolve. Neither owes a fixture test — constraint 8 of rules/workflow-rule-governance.md asks that of automated blocking items — but the half of each that is mechanical, deciding the obligation once the evidence is in hand, is pinned in scripts/test-rule-scenarios.py regardless, over a fourth shape that brings it to 10: a plugin host that loads handlers by name from configuration, where static analysis is weakest. Writing those cases found a hole in ARC-010 as first published: its pass condition let any removal through, so deleting a reflection-reached symbol on the analyzer's word alone would have passed — the exact failure the item was written to prevent. The condition now requires a runtime signal in that direction too. Seven mutations of the decision were seeded and all seven were caught. review-implementation-alignment 1.0.0 → 1.1.0 states the boundary rather than taking the items on: delivered code nothing reaches is its own, under ALN-003, but the implementation a change replaced and left behind is ARC-010's, decided by the sibling engineering gate over the same scope. The two read alike and would otherwise be reported twice or by neither. review-codebase 1.0.1 → 1.1.0 names both in its tech-debt dimension, which is where a reader first meets them, and routes the decision rather than taking it: neither is settled by reading the code, since one needs a runtime signal and the other needs the fields recorded beside the marker.
• CONTRIBUTING.md gains a Checks section. There had been no list: the scripts were named in one sentence inside "Adding a skill", which is the wrong home for a checker that has nothing to do with skills, and a contributor changing a Rule or a script had nothing to go on. The table says which check to run for which kind of change, and mutation-check.py carries a paragraph of its own, because "run the thing that checks the checks" earns an explanation rather than a line in a table.
• scripts/mutation-test.sh is folded into scripts/mutation-check.py, which now covers both shapes of perturbat...

v0.1.0 — 首个公开发布版

Published retroactively. This release was tagged on 2026-09-09; the page is added later, so GitHub shows today's date above. Its text is the tag's own annotation and the changelog entries as released, reproduced without translation — docs/LANGUAGE_SCHEME.md §2 keeps a released record in the words used at the time.

55 个技能、21 条规则、16 份规范，覆盖治理规划、代码审查、交付发布、
文档资产、集成运维五个领域。

本版为发布到 skills.sh / skillsmp.com 前的整备版本：许可证合规审计、
机翻清理、开源社区标配补齐。

变更日志 — 46 条

Added

• CODE_OF_CONDUCT.md、SECURITY.md、.editorconfig、.github/（issue 模板、PR 模板、lint 工作流）: 补齐开源社区标配。SECURITY.md 明确本仓库的安全面只有两处——bin/cortex 这个会创建删除符号链接的 shell 脚本，以及技能内容本身（措辞若诱导 Agent 执行破坏性或越权操作即构成安全问题），并区分了哪些属于 / 不属于安全问题。CI 分三个 job：链接检查与注册表一致性阻断合并，markdownlint 暂设 continue-on-error —— 仓库已按 MD009/012/022/031/040/047 清理完毕，但默认规则集远不止这些，尚未在 CI 上实跑过完整规则，先以顾问模式收集真实违规再改为阻断。

• README.md: 补「能力概览」节。此前访客第一眼看不出这仓库有什么——现按五个领域列出 55 个技能的分布与代表能力，并说明与同类资产库的四点区别（四层资产分离、编排与原子分层、判据外置、vendored-only 分发）。

• docs/guides/roadmap-planning-usage.md: new guide — 路线图规划链路的面向使用者入口。此前这条链的九个技能没有任何用户侧入口：skills/INDEX.md 是给 Agent 匹配用的一行描述，各技能 README 的「相关技能」是点对点的拼不出全貌，orchestrate-roadmap-planning 的 SKILL.md 里虽有完整九步表但那是写给 Agent 的。本指南按「你处在什么状态」组织而非复述执行顺序（顺序的权威定义仍在 SKILL.md，避免 SSOT 双写），重点讲三件容易撞上的事：晋升时的容量分配 halt 为什么不自动填、治理文档全空时为什么不从零盘问、依赖为什么必须排在晋升之前。

• rules/roadmap-quality.md (v1.0.0): new rule — 路线图制品的 5 维评审清单。rules/ 下原有 requirement / functional-design / technical-design / task / test-case / test-coverage 六份判据 rule，roadmap 是治理链上唯一缺判据的一层。本文件是路线图判据的唯一权威源：define-roadmap（生产侧）、plan-next（诊断侧）、review-roadmap（评审侧）三方引用同一份表述，避免重蹈 rules/requirement-quality.md 与 review-requirements 各维护一套判据的覆辙。反模式清单由本 rule 自身的五维结构推出，每条对应一维判据的失效形态；涉及的产品管理通用概念在「判据依据」节回溯至公开出版物（《Product Roadmaps Relaunched》、Intercom RICE、《Lean UX》、《Escaping the Build Trap》等）。**制定过程中调研过三个开源 PM 技能仓库，初版曾把其中之一列为判据出处，随后发现该仓库为 CC BY-NC-SA 4.0——其非商业与相同方式共享条款与本仓库 MIT 不兼容，衍生声明会造成许可证冲突。已重写反模式使其从本 rule 的判据结构自洽推出，并将概念出处回溯到一手公开著作，不再声明衍生自任何外部仓库。**另两个调研对象（Apache-2.0 与 MIT）虽许可证兼容，本 rule 亦未复制其表达，故同样不作衍生登记——按 specs/skill-source-modeling.md，SOURCES.yaml 只登记 vendored 的 Skill 本地副本，行业通用概念与文档链接不登记。

• skills/map-item-dependencies/SKILL.md (v1.0.0): new skill — 识别 backlog 与 roadmap 条目间的五类依赖（技术 / 团队 / 外部 / 知识 / 顺序），写入条目 depends_on，产出依赖图、需解决时点与削减建议。此前本仓库对条目间依赖完全空白：promote-roadmap-items 只按 priority 与容量排序，一个「P0 但被仍在 backlog 的条目阻塞」的项会被正常拉进 Now 占着容量不产出。发现依赖环时 halt 并输出环路径，不自行选边打破——拆哪条边是范围决策，超出依赖登记的职责。depends_on 字段语义借用 rules/task-quality.md 的既有约定；已知债务：backlog-item 目前无 spec，结构只由 capture-work-items 的输出模板隐式定义，若该制品字段继续增长应补 specs/backlog-item-modeling.md，此处仅记账不代表已解决。

• skills/update-roadmap/SKILL.md (v1.0.0): new skill — 路线图日常运维入口：改状态、挪期并计算下游影响、产出「本次变更了什么」摘要。此前 define-roadmap 管从零建、promote-roadmap-items 管跨层晋升降级，两者之间的日常动作无处安放。与 promote 的分界写死为「改变层级的归 promote，不改变层级的归本技能」——把 Now 项推迟两周是本技能，把它挪到 Next 是 promote。改为 at risk / blocked 时阻塞原因与缓解方案缺一不写入；依赖数据缺失时明确声明「下游影响未计算」而非假装已分析。

• skills/review-roadmap/SKILL.md (v1.0.0): new skill — 按 rules/roadmap-quality.md 评估既有路线图，输出 findings-list。IO 契约对齐既有的 review-requirements（document-artifact 进、findings-list 出）。输入除 roadmap.md 外还包含佐证源——strategic-goals.md 与 Now 层引用的 backlog 条目：判据中有三条的数据在条目 frontmatter 里（strategic_goal_id / depends_on / priority_decision），只读 roadmap.md 的话这些维度结构上就无从求值，负责检查的技能读不到要检查的东西。读不到佐证源时标「无法评估」，不得记为通过。判据不内嵌，全部引自 rule，这是与 review-requirements 现状的刻意差异。变更频率维度依赖 git log，写明了「发现 → 执行 → 缺失处理」路径：非 git 仓库、浅克隆或无提交历史时标注为「无法评估」并说明原因，不得静默跳过或据此推断通过。判据文件缺失时 halt——没有基准就评估，产出的会是一份看似权威实则无依据的清单。不输出 mode：编排层的上下文检测由编排层自己做。

• skills/orchestrate-roadmap-planning/SKILL.md (v1.0.0): new skill — 编排技能，按固定 9 步串联从战略目标到晋升的原子技能。存在价值是提前满足下游 halt 条件：手工调用最常见的浪费是做到 promote-roadmap-items 才发现缺容量分配、halt、回头跑 define-roadmap 再重来（该回退在 promote 的示例 2 里被当成正常流程写着）。每步标注必选 / 默认 / 推荐三档，档位是各原子技能既有约束的机械映射而非本层判断——步骤 1、2 必选因为对应 promote 明写的 halt 条件；步骤 4 双档位对应 promote 对「全部 unset」halt、对「部分 unset」仅跳过的两种行为；步骤 8 推荐因为 archive-milestone 自身 apply 默认即为 dry-run。档位同时决定失败语义，这是相对 orchestrate-code-review 单一 halt 规则的有意偏离（那里各原子技能彼此独立，这里步骤间有数据依赖）。含与 plan-next / orchestrate-governance-step 的正交边界表，禁止反向调用以避免调用环。

Fixed

• 机翻残留清理：164 处重复直译标题（## 行为（行为）、## 限制（限制）、## 示例（示例）、## 使用场景（用例）、### 输入（输入） 等）改为「中文 + 英文原词」形态；27 处明显误译的技术词修正——preflight 曾译作「飞行前」、flaky tests 译作「片状测试」、AI agent 译作「人工智能代理」、happy path 译作「幸福之路」、prefer 一律译作「更喜欢」。这类痕迹分布在 29 个文件，是公开仓库最扎眼的一类问题。

• markdown 格式清理：全仓 199 处违规清零——117 个代码块补语言标签（保守推断，判不准的标 text，丢高亮但不改语义）、48 处标题与代码块前后补空行、21 处文件结尾换行、连续空行合并。.cortex/vendor/ 下的外部契约不重排格式。

• 坏链修复：3 条路径笔误（docs/adr/0009 的 ../../../ 深度错误、docs/architecture/README.md 指向不存在的 adrs/、rules/claude-md-management.md 的 README 相对路径）。剩余 8 条全部位于历史 ADR 且指向已删除的资产（specs/skill.md、skills/review-code 等），属准确的时点记录，按 rules/adr-management.md「ADR 写入后不改」保留。

• CHANGELOG.md: [Unreleased] 日期从 2026-05-15 更新为 2026-09-09。

• docs/guides/proactive-suggestions.md: 补 5 条路线图相关入口（规划 / 体检 / 运维 / 优先级 / 依赖）。此前今天涉及的 10 个技能里只有 capture-work-items 在表内，本该作为唯一入口的 orchestrate-roadmap-planning 未列。同时移除 tidy-repo 一行——该技能在 skills/ 与 skills/INDEX.md 中均不存在，是条死引用。ADR 0003 / 0004 与 2026-05-08 孤儿技能清理设计文档中的 tidy-repo 引用保留不动：前者按 rules/adr-management.md 写入后不改，后者是记录该技能曾为孤儿的历史快照。

• docs/references/README.md: 注册新指南，避免孤立文档。

• skills/define-roadmap/SKILL.md (v3.2.0 → v4.0.0): 补上一个悬空的除数。promote-roadmap-items 的容量公式是「百分比 × cycle 总容量」，但「cycle 总容量」全仓仅出现一次且是除数，从未有技能负责生成——容量护栏实际算不出结果。新增第 8 步采集总容量基线（人数 × 周期 − 开销，按有效工时 60–70% 折算），写入容量分配章节表头。同时明确缓冲语义：百分比相对于有效容量而非日历容量，未规划工作（紧急问题、快速 win、他团队请求）的余量在折算时已让出，不再单列槽位——原规则要求百分比之和 = 100% 且全部指向 strategic_goal，没有给未规划工作留位置。成功指标从「优先量化」的软要求改为强制三元组（当前值 / 目标值 / 参考系），与 plan-next 自检对齐：此前生产方不保证的格式，消费方在强制检查，正常产出的路线图过不了下游自检。取 MAJOR 而非 MINOR，因为按旧版产出的既有 roadmap.md 不再通过新自检。另补关键举措的可证伪假设句式与里程碑的结果句式（此前只有「成果导向」的要求而无模板，关键举措易退化成名词短语），以及可选章节「本轮明确不做」（此前「不属于路线图的需求默认不做」是隐式规则，读者看不到被排除了什么）。

• skills/prioritize-backlog/SKILL.md (v2.0.0 → v2.2.0): RICE 的 Impact 补齐为五档 3 / 2 / 1 / 0.5 / 0.25。原刻度只有 1/2/3，下限为 1 意味着「几乎没影响」与「中等影响」拿同样乘数，琐碎条目只能靠 Reach 与 Effort 拉开差距，结果是低价值项分数虚高。Confidence 补三档锚点（100% 有数据支撑 / 80% 有部分证据 / 50% 拍脑袋）——原文只写「0-100%」无参照，同一批条目重跑两次会飘。新增 status: declined 终态：MoSCoW 的 Won't 原本映射到 P3，而 P3 默认进 Later，「明确不做」的条目会永远躺在那里参与每一轮全量重评。新增 strategic_override 留痕字段：最终 priority 高于框架结论时必填理由，避免「用户逐项确认」沦为不留证据的旁路。

• skills/promote-roadmap-items/SKILL.md (v1.0.0 → v1.2.1): 定义 Now 层 WIP 默认上限 3–5（原反模式引用「WIP 限制」但该量全仓仅此一处提及、从未定义）。补 Now 层依赖准入护栏：存在未决前置的条目不得进 Now，最高只能到 Next；depends_on 缺失时不静默放行而是提示先跑 map-item-dependencies。补 status: declined 条目跳过规则。容量公式的分母改为指向 define-roadmap 写入的总容量基线。

• skills/capture-work-items/SKILL.md (v2.0.0 → v2.0.1): 第 140 行指示 agent 写 status: capture，但同文件三个输出模板写的是 captured，promote-roadmap-items 消费的也是 captured——照该指令执行会产出下游读不到的条目。

• skills/design-strategic-goals/SKILL.md (v1.2.0 → v1.3.0): 补冷启动降级模式。该技能第 2 步本就有推导机制（逆向拆解北极星：「要让 NSM 增长，什么必须为真？」），但把愿景与北极星列为必需输入；冷启动时上游五层（mission → vision → north-star → strategic-pillars → strategic-goals）全空，推导无依据可用，整条链在第一步就断。新增降级路径：两者均缺失时不 halt，改为从仓库实证反推候选目标，提取源按意图密度排序（README / AGENTS.md → CHANGELOG → git log → 代码结构 → backlog → docs 其余）；CHANGELOG 与 git log 分列两级并写明相互独立——冷启动演练中 CHANGELOG 缺失而 git log 恰是最富的来源，捆绑写法会被读成「缺其一就跳过这一级」。安全约束不可省略——实证反推的产物读起来会很自洽很顺畅，恰恰因此最可能是脑补填空：每条候选目标必须附指向具体文件的推断依据，推不出依据的不许写；不得自动持久化；落盘文档头部留「缺上游背书、属临时锚」标记。此改动是 rules/agentic-artifact-paradigm.md「提取优先、逼问垫底」在冷启动场景的落地。

• skills/{define-roadmap,capture-work-items,design-strategic-goals}/SKILL.md 与三份 README: 清除 12 处指向不存在 ADR 的引用，理由改为内联。其中 7 处写全名（20260417-unified-value-driven-prioritization-model / 20260417-work-lifecycle-and-skill-responsibilities），docs/adr/ 实际只有 0001–0011；另 5 处简写为「ADR 1 决策 3.4/3.5」，而 docs/adr/0001-io-contract-protocol.md 确实存在但内容是 IO 契约协议，读者顺着编号查会查到一份不相干的文档——这比引用一个不存在的编号更容易误导。四条被内联的理由：四框架不聚合（聚合会掩盖框架间的判断冲突）、容量按 strategic_goal 分配（护栏要按目标控制就必须有可归属的分母）、工程健康目标必填且非零（这类工作无战略代言就永远排不进容量）、工作项必填 strategic_goal_id（晋升时要按目标归集容量）。

• skills/{map-item-dependencies,update-roadmap,review-roadmap,orchestrate-roadmap-planning}/README.md: 为 4 个新技能补 README，对齐 prioritize-backlog / promote-roadmap-items 的现行格式。补前覆盖率 45/55，补后 49/55。

• skills/plan-next/SKILL.md (v13.3.0 → v13.3.1): KPI 三元组格式定义处补指向 rules/roadmap-quality.md 的权威源引用，保证与 define-roadmap 产出侧措辞同步。

• skills/prepare-release/SKILL.md (v1.3.1 → v1.4.0): 补「材料的形态」一节与一条自检项。此前只划受众边界（技术 changelog 装接口/配置/迁移细节，用户 release notes 只写可感知价值），不管形态——于是「面向维护者」被读成「可以不可读」，条目长成一条几百字、塞满编号与路径的段落。新增五条形态约束：一条一个意思、结论先行、背景与佐证不进正文、内部记号克制、升级须知单列。长度阈值刻意不写进本 Skill：它取决于语种、读者与既往基线，写死一个数换个项目就不成立；Skill 只给判据并指出可从项目最早、最可读的那几版量出基线，阈值与红线归项目自己的 rules。源自 recloud-wright 的实测——该仓库条目中位长度五个月从 119 字涨到 636 字，而最早两版本来是可读的。

• skills/consume-nats-message/SKILL.md (v1.1.0 → v1.4.0) + specs/nats-messaging.md (v1.0.0 → v1.1.0): optional consume_pattern wildcard consumption mode for .cortex/nats.yaml — opt-in, backward compatible with existing consume_subjects per-subject mode. Single wildcard durable consumer instead of one-per-subject; per-message dynamic contract resolution (exact-subject match against vendored contract frontmatter); messages on draft/unknown subjects are never blindly acked — inline single-message Bootstrap drafts the contract, then the message is term'd + DLQ'd with X-DLQ-Reason: awaiting contract confirmation (surfaced in the aggregate receipt's new awaiting_confirmation bucket) rather than nak'd forever (which would silently vanish past max_deliver with no DLQ trail). Known limitation: JetStream ack_wait/max_deliver are durable-level, so wildcard mode shares one retry policy across all subjects. The skill now also documents NATS MCP capability discovery, exact-subject vs wildcard routing, local-contract-first behavior, and draft acknowledgment guardrails. v1.4.0 adds two pre-filter rules discovered during real-world dogfooding: self-sourced messages (X-Source == service_source, an echo of the consumer's own outbound traffic under a shared bidirectional subject prefix) and DLQ copies re-matching the same wildcard filter (identified by the self-attached `X-DLQ-Original-...