gstack v2 瘦身方案深解：以 Eval 守护与 sections/ 模式压缩 2.1MB 技能语料库

本文基于 gstack 仓库的设计规划文档 v2_PLAN.md，完整解读这个项目如何把"所有角色全部开启时消耗 10K+ tokens"的臃肿技能包，改造为"最轻量的有主见技能包（the lightest opinionated skill pack）"。读完你会掌握一套可迁移的技能包压缩方法论：两阶段混合发布拆分、eval 覆盖矩阵作为设计规格、构建期条件化注入、sections/ 懒加载骨架的六层防行为丢失防御，以及用硬 token 预算与质量预算双重 CI 门禁来防止"看着绿、感觉变差"的隐性退化——并且能对照当前仓库源码，验证该计划各阶段的实际落地形态。

背景：一个被第三方引用的"胖"问题

gstack 是 Garry Tan 的 Claude Code 技能包，23+ 个有主见的工具分别扮演 CEO、设计师、工程经理、发布经理、文档工程师和 QA 等角色。问题在于：这些角色全部开启时，技能语料（SKILL.md 语料库）成为每个会话启动都要支付的固定成本。第三方评测（dev.to，2026 年 5 月）直接写道：gstack "can feel bloated when all roles are turned on... potentially consuming 10K+ tokens before any real code is written"。同时，Anthropic 官方的 Skills 指引推荐 "progressive disclosure"（渐进式披露）模式——SKILL.md 骨架 + references/ 按需加载——而 gstack 与之背离。

规划文档给出的问题定量证据：

• 31 个技能，生成的 SKILL.md 语料总量 2.1MB
• 28/31 个技能超过 40KB 软上限（每个约 10K tokens）
• ship.md 达 164KB（约 41K tokens），而其模板 ship/SKILL.md.tmpl 只有 48KB——115KB 是构建期 resolver 注入的，这是杠杆最高的压缩点
• 常驻系统提示中的技能目录（catalog）：50+ 技能 × 多段落描述、语音触发词、主动建议段落

值得注意的一点：gstack 不是"发明"新方案，而是"追赶" Anthropic 的官方模式。

发布形态：混合双发布结构

计划拆成两次协调发布，这个拆分本身来自跨模型评审（Codex 曾质疑 v2 是"没有真正破坏性变更的姿态"）：

	v1.45.0.0（地基发布）	v2.0.0.0（v2 正式启动）
时间	约 1–2 周 CC 工作量	2–4 周后，协调发布
Phase 0	全部 31 个技能的 eval 覆盖矩阵（gate + periodic）	—
Phase A	构建期压缩：条件化 resolver 注入、术语表去重、terse 模式真压缩、目录瘦身、硬 token 预算	—
Phase B	—	5 个最重技能落地 sections/ 模式（ship、plan-ceo、office-hours、plan-eng、plan-design）
Phase C	—	eval 注释 + CI 孤儿检查（WARN→FAIL 渐进）
对外声音	常规发布语气	营销级 CHANGELOG + README v2 横幅 + "最轻量有主见技能包"定位

前提核查（Step 0A 结论）：这是正确的问题（外部验证过）；什么都不做的话，批评会固化——v1.38 → v1.44 的每次发布都在加功能，没有任何一次反方向走；而行动的代价是懒加载会引入"静默行为丢失"这一新故障类别，需要 eval 先行 + 机械强制 + canary 滚动来缓解。

先复用，再新建（reuse-first 审计）

计划明确盘点了可复用资产，这是它工程上"扎实"的地方：

资产	复用方式
scripts/gen-skill-docs.ts 439–450 行	已有字符串替换与按 host 抑制；扩展 appliesTo 门控（约 15 LOC）
scripts/resolvers/types.ts	新增 ResolverEntry 联合类型
scripts/resolvers/preamble.ts	已有 tier 门控组合（1–4）；新增按 resolver 门控
scripts/jargon-list.json	已是单文件；只需停止把它内联 37 次
既有 budget-regression 测试	扩展为按技能硬预算
v1.13.2.0 的 Real-PTY 测试框架	复用于行为契约 eval（约 $0.50/次）
SDK 测试框架	复用于廉价的结构性 eval（尽量 $0/次）
gstack-upgrade/migrations/	状态格式迁移模式已存在；复用于 v2 自动再生
~/.gstack/analytics/skill-usage.jsonl	已在采集；支撑延后的 gstack budget CLI

目标态增量（dream state delta）

TODAY                              v1.45.0.0                         v2.0.0.0
──────                             ─────────                         ────────
2.1MB 语料                          ~1.3MB (-40%)                     ~700KB (-67%)
ship.md: 164KB                     ship.md: ~80KB (-50%)             ship.md: ~15KB 骨架
                                                                     + 5×~5KB sections
28/31 超 40KB 上限                   ~10/31 超限                      ~3/31 超限（cso、
                                                                     document-release、
                                                                     design-consultation 保留单体）
目录：多段落描述、语音触发词          目录：每技能一行（-70%）          目录：每技能一行
无 eval 覆盖矩阵                    每技能 ≥1 gate eval + ≥1 periodic  section 级 eval 注释
                                                              + CI 孤儿检查

Phase 0 — Eval 覆盖矩阵（计划中真正的承重墙）

目标：每个技能至少带一个 gate 级 eval 和一个 periodic 级 eval，断言一个必须保留的行为。"eval 套件就是设计规格"——这是整个计划的承重声明，必须最先做。

计划记录了跨模型张力：Codex 认为"eval 先行是拖延陷阱、形状断言太浅"，用户仍明确选择全量分层覆盖（决策 D9 = A），理由是"eval 套件就是设计规格；这一承诺是整个计划的承重声明"。对 Codex "形状 vs 质量"批评的缓解：对编排/判断类技能（plan-ceo、office-hours、autoplan），"必须有"的不是确定性输出，而是结构性合规——是否以正确形状调用 AskUserQuestion？是否遵守 section 顺序？是否持久化了产物？无法做结构 eval 的部分明确标注为"判断依赖、非 eval 保护"，然后不删除这些未受保护的判断性文字。

当时缺少专门 E2E 覆盖的 20 个技能（eval 编写目标，含单次运行成本估算）：

技能	Gate eval 目标	Periodic eval 目标	估算成本 gate / periodic
qa-only	report-only 标志触发	禁用 fix-loop 的完整 QA 流程	$0.30 / $1.50
retro	周聚合运行无错误	完整 retro 产出排序输出	$0.20 / $2.00
document-release	读 CHANGELOG、产出 Diataxis 映射	完整发布后文档更新	$0.30 / $1.80
document-generate	从 prompt 生成 4 种文档	E2E 生成过质量线	$0.30 / $2.00
context-save	状态持久化到预期路径	往返恢复保留上下文	$0.10 / $0.50
context-restore	读最新保存并应用到会话	跨工作区恢复可用	$0.10 / $0.50
gstack-upgrade	检测安装类型、运行升级	完整升级 + 迁移往返	$0.20 / $1.00
sync-gbrain	索引刷新无错误	完整同步产出可搜索语料	$0.20 / $1.50
setup-gbrain	路径 1–4 检测正确	每条路径端到端安装	$0.20 / $2.00
setup-browser-cookies	选择器 UI 加载无错误	cookie 导入往返	$0.20 / $1.00
setup-deploy	检测配置、写出预期文件	完整部署配置安装	$0.20 / $1.00
design-consultation	DESIGN.md 模板渲染	完整设计系统生成	$0.30 / $2.50
design-shotgun	变体生成并保存	完整多变体探索	$0.30 / $2.00
open-gstack-browser	浏览器启动无错误	侧边栏附着并显示活动	$0.20 / $0.80
pair-agent	生成 setup key、打印说明	带第二 agent 的完整结对流程	$0.20 / $1.50
land-and-deploy	合并门禁正确检查	完整 merge → deploy → canary	$0.30 / $3.00
canary	部署后循环运行并干净退出	带告警模拟的完整 canary 周期	$0.20 / $1.50
benchmark	运行并产出分数	完整回归检测	$0.20 / $2.00
plan-devex-review	模式路由正确	带评分的完整 DX review	$0.40 / $3.00
devex-review	实时 DX 审计产出记分卡	E2E DX 测量对照计划基线	$0.40 / $2.50

估算新增 CI 成本：gate 约 $5/次、periodic 约 $30/次；加上既有 E2E 套件（gate ~$15、periodic ~$30），合计约 $20/每个 PR、$60/每周——可接受。

矩阵的单一事实来源：test/helpers/skill-coverage-matrix.ts 把每个技能映射到其 gate + periodic eval 测试文件；CI 检查在 test/skill-coverage-matrix.test.ts，任何技能缺条目即构建失败。当前仓库中该测试的头部注释写着 "Skill coverage matrix CI gate (v1.45.0.0 T1)"，断言逻辑是：每个磁盘上的技能在 SKILL_COVERAGE 中至少有一条 gate 级条目，路径必须以 test/ 开头、以 .test.ts 结尾。

关键新增文件（计划视角）：test/skill-coverage-matrix.ts 注册表；约 20 个新 test/skill-e2e-*.test.ts；test/helpers/touchfiles.ts 登记新测试以支持 diff 选择。

Phase A — 构建期压缩（六项低风险收益）

A.1 条件化 resolver 注入

核心思路：ship.md 的 164KB 中 115KB 是 resolver 注入的，但很多注入内容只与特定技能相关。计划为 scripts/resolvers/types.ts 引入门控条目类型：

// scripts/resolvers/types.ts
export type ResolverFn = (ctx: TemplateContext, args?: string[]) => string;
export type ResolverEntry = ResolverFn | {
  resolve: ResolverFn;
  appliesTo?: (ctx: TemplateContext) => boolean;
};

在 scripts/resolvers/index.ts 中给重型 resolver 装门控，并审计全部 21 个 resolver 按真实使用量门控：

QUESTION_TUNING: {
  resolve: generateQuestionTuning,
  appliesTo: (ctx) => ['plan-ceo-review','plan-eng-review','office-hours'].includes(ctx.skillName),
},
REVIEW_ARMY: {
  resolve: generateReviewArmy,
  appliesTo: (ctx) => ['ship','review'].includes(ctx.skillName),
},
REVIEW_DASHBOARD: {
  resolve: generateReviewDashboard,
  appliesTo: (ctx) => ['ship','plan-ceo-review','plan-eng-review','plan-design-review','plan-devex-review','devex-review'].includes(ctx.skillName),
},

生成器侧在 scripts/gen-skill-docs.ts 约 444 行检查门控：

const entry = RESOLVERS[resolverName];
const resolver = typeof entry === 'function' ? entry : entry.resolve;
const gate = typeof entry === 'function' ? undefined : entry.appliesTo;
if (gate && !gate(ctx)) return '';
return args.length > 0 ? resolver(ctx, args) : resolver(ctx);

从当前仓库的源码结构看，这段演进留下了耐人寻味的痕迹：scripts/resolvers/types.ts 末尾的注释说明，ResolverEntry 门控机制"已完整构建并测试过，但 65 个注册表条目中没有一个使用它——按技能门控要么在模板层（占位符天然条件化）、要么通过 resolver 内部显式的 ctx.skillName 分支实现，故被删除而非保留为投机性 API"。也就是说，基础设施建好后，模板层的条件化占位符已经天然承担了门控职责——这正是"先测量、再架构"（Codex #10）的体现。

A.2 术语表去重

scripts/resolvers/preamble/generate-writing-style.ts 当时把完整的 1.8KB 术语表内联进 37 个技能。改为引用："术语规范列表，首次使用时 Read ~/.claude/skills/gstack/scripts/jargon-list.json"。语料层面共省约 66KB。当前仓库中 scripts/jargon-list.json 存在，v1.46 的 CHANGELOG 确认了这一项落地：80 个术语不再内联，## Writing Style 改为引用 JSON 路径，代理每次会话首个遇到术语时 Read 一次，跨语料共省约 70KB。

A.3 让 terse 模式真正压缩

当时的问题：explain_level: terse 只改变运行时模型行为，字节照样随技能发出。修复：gen-skill-docs.ts 在构建时读一次 ~/.gstack/config.yaml，把 explainLevel 传入 TemplateContext，让 writing-style / completeness / confusion-protocol / context-health 四个 preamble 生成器在 terse 下返回 ''；再加 --explain-level=terse 构建旗标供基准测试使用。当前 scripts/resolvers/types.ts 中 TemplateContext.explainLevel 字段的文档注释完整保留了这一设计：'terse' 会把四节 preamble 压缩为一行指针，每个 tier-2+ 技能省约 3–5KB；默认构建保持运行期条件行为不变，terse 构建则把压缩变成结构性的——"字节从一开始就不发出"。

A.4 目录瘦身（Codex 认定的最高杠杆项）

常驻系统提示中的技能目录，从多段落描述裁到每技能一行：

- <skill-name>: <one-line outcome description, ≤80 chars> (gstack)

语音触发词从目录描述移入技能正文；主动建议段落移入独立的 proactive-suggestions.json，仅当 agent 需要路由指引时加载。预计目录削减约 70%——这是常驻提示上最大的单项缩减。当前仓库中各技能 SKILL.md 的 frontmatter 确实已是单行描述加 (gstack) 标签的形态（例如 ship/SKILL.md 的 description 仅一句话），路由文字移入正文的 ## When to invoke 段落。

A.5 cso/ 定向压缩

cso（安全技能）做 resolver 去重 + 目录瘦身，但安全指引文字保持单体不压，直到 Phase B 审计证明特定段落可以在有 eval 覆盖的前提下移入 sections/。不是"豁免"，只是排在最后。

A.6 硬 token 预算

定义并在 budget-regression 测试中强制：

预算	v1.44 实际	v1.45 目标	v2.0 目标
系统提示目录 tokens 上限	~25K	~8K	~6K
单技能 SKILL.md 大小上限	164KB（ship）	100KB	30KB（重型技能）
语料总量上限	2.1MB	1.3MB	700KB
首次调用延迟（重型）	~即时	~即时	<500ms section 读取

任何预算超限 CI 失败，通过既有 budget-regression jsonl 跟踪历史。工程评审（D3）进一步补上 CI 成本上限：EVALS_BUDGET_HARD_CAP=$30 环境变量由预算回归测试强制，单套件上限 EVALS_BUDGET_HARD_CAP_GATE=$25、EVALS_BUDGET_HARD_CAP_PERIODIC=$70；超限需 EVALS_BUDGET_OVERRIDE_REASON="<理由>" 环境变量解锁，CI 会打印理由形成审计轨迹。v1.46 的 CHANGELOG 确认这套上限已落地，覆盖路径写入 ~/.gstack/analytics/spend-overrides.jsonl。

Phase B — sections/ 模式：v2 的架构断裂

五个最重技能转为 Anthropic 官方的"骨架 + 按需 section"形态：

ship/
├── SKILL.md              # 12–15KB 决策树骨架 + section 清单
├── SKILL.md.tmpl         # 骨架的源模板
├── sections/
│   ├── manifest.json     # 结构化 section 注册表（Codex #3 缓解项）
│   ├── version-bump.md
│   ├── changelog.md
│   ├── review-army.md
│   ├── todos-cleanup.md
│   ├── pr-body.md
│   └── ...

六层防御对抗"静默行为丢失"

这是计划最有价值的设计判断：懒加载的最大风险是 agent 忘了 Read section，行为悄悄降级。计划要求分层防御而非单纯自我检查：

1. Section 清单（sections/manifest.json）：结构化注册表，决策树骨架按 ID 引用条目，而非自由散文；
2. 命令式骨架措辞："STOP. Read sections/version-bump.md before computing the bump."——不是 "see ... for details."；
3. 文件顶部 section 索引表：情境 → section 文件映射；
4. 技能末尾自我检查："确认你 Read 了决策树指向的每个 section，列出来"（最弱一层，仅作兜底）；
5. Eval 测试的 requiredReads 声明：E2E 断言给定 fixture 下哪些 section 必须出现在转录的 Read 调用中——测试层的机械强制，不只是 prompt 层；
6. Canary 组的转录检查：发布首周记录真实会话实际 Read 了哪些 section，对标记为必需却漏读的 section 告警。

当前仓库中这六层都有实物可查。ship/sections/manifest.json 的 note 字段逐字记录了"PASSIVE registry（v2 plan T9 / CM2）。字段只有 ID、文件路径、人类可读标题和触发文字。骨架决策树散文是唯一决定何时读 section 的地方；required-reads 放在 E2E fixture 里。这里没有机器谓词——见 docs/designs/v2_PLAN.md:663"——与计划 D1"manifest 是被动数据、不发明第四种条件语言"完全一致。ship/SKILL.md 第 1074 行可见命令式措辞："STOP. Before running the test suites... Read ~/.claude/skills/gstack/ship/sections/tests.md and execute it"。test/skill-e2e-ship-section-loading.test.ts（断言 /ship 按决策树 Read 了预期 section）、test/section-manifest-consistency.test.ts（manifest 与文件系统一致性）均在当前仓库中存在。

工程评审锁定的三条架构决策：

• D1（manifest 格式）：JSON、机器可读供 gen-skill-docs CI 检查；骨架用 markdown 标题 + 命令式散文块；匹配 Anthropic 文档的 references/ 风格；不发明 DSL；
• D2（漂移控制）：sections/*.md.tmpl 是单一事实来源，sections/*.md 是生成物；gen-skill-docs 遍历 <skill>/sections/*.tmpl 写入 <skill>/sections/*.md，走与 SKILL.md 相同的 resolver 管线（约 30 LOC），消除 test/ship-version-sync.test.ts 长期受苦的漂移类别；
• D3（CI 成本上限）：如上所述。

转换顺序与排除名单

一次一个，验证一个再动下一个：

1. ship/——调用最多、成本最大、风险最高；单独落地，观察一周；
2. plan-ceo-review/——对话型，有打断流程风险；第二个落地，仔细观察；
3. office-hours/——最对话化；仅当前两个干净才做；
4. plan-eng-review/ 与 plan-design-review/——形状相似，捆绑处理。

明确不转（除非日后显式批准）：autoplan（已是编排器）、design-review（UI 流已紧凑）、qa（单一目的）、investigate（单一目的）。当前仓库中 ship/sections/ 含 9 个 section（apple-release、tests、test-coverage、plan-completion、review-army、greptile、adversarial、changelog、pr-body，均成对出现 .md + .md.tmpl），plan-ceo-review/sections/ 也已生成 manifest.json 与 section 文件，与计划的前两步顺序吻合。

Phase C — Eval 注释与 CI 孤儿检查（warn-before-fail）

每个 section 带 eval 注释，且注释必须包含覆盖语义（保护了什么行为）而不只是路径——只有路径是虚假信心：

<!-- eval: test/skill-e2e-ship-version-bump.test.ts -->
<!-- coverage: asserts the queue-aware bump picks the next available version when the claimed version is taken -->

CI 检查（gen-skill-docs 遍历器）渐进收紧：v2.0.0.0 以 WARN 模式发布（孤儿进 PR 摘要但构建通过）；v2.1.0.0（或 v2.0 后两个发布周期）WARN 升级为 FAIL；豁免语法 <!-- eval: none — accept loss, reviewed YYYY-MM-DD by @user -->。这避免了"强制注释但无语义"的维护表演，同时给用户过渡窗口。

Codex 二轮咨询后，孤儿检查升级为三级分类：

• 生成物孤儿（sections/foo.md 存在但无 .md.tmpl）→ 立即 FAIL；
• manifest 孤儿（.md.tmpl 存在但不在 manifest.json）→ v2.0 WARN，v2.1+ FAIL；
• 被手改的生成文件（.md 与再生结果不一致）→ 立即 FAIL，并提示 "this file is generated, edit .tmpl instead"。

迁移、fork 兼容与滚动策略

迁移（轻触式，决策 D11）：v2.0.0.0 的发布说明解释 sections/ 格式变更的具体用户影响（fork/复制粘贴的 SKILL.md 需重新获取；重型技能首次调用增加约 200–500ms 的 section 读取延迟）；/gstack-upgrade 下次调用时自动再生，无交互迁移提示；vendored 安装首次接触 v2 时获得一行警告；提供 gstack-upgrade --explain-v2 旗标按需给出完整解释。

fork/定制兼容（Codex #11）：直接读/抄/改重型 SKILL.md 的人——文件现在是骨架，行为在 sections/*.md，建议把技能当黑盒（推荐）或 fork 含 sections/ 的完整技能目录；本地改过 SKILL.md.tmpl 的 fork 再生时冲突概率高，fork 文档需更新迁移指引；指向生成 SKILL.md 特定行号的文档/博客，行号会漂移，建议改链模板 + section 名。

滚动：v1.45 单 PR 落地，既有 budget-regression 测试捕获单技能尺寸回归，eval 矩阵 CI 捕获漏网技能，dogfood 一周再宣布；v2.0 先经 v2.0.0-rc.1 灰度组（Real-PTY 框架记录五大工作流 /ship、/qa、/review、/plan-ceo-review、/autoplan 的 section Read 行为，必需 section 漏读即告警），打正式 tag 前人工跑通五大工作流并保存前后转录作为 eval 基线，回归面板用既有 bun run eval:summary 扩展出 v1 vs v2 逐技能 token 与行为合规对比；回滚 = revert PR + bun run gen:skill-docs 再生旧形态。

落地验证：当前仓库（v1.71.0.0）中计划走到了哪一步

计划本身是 v1 时代写下的，对照当前仓库源码，可以验证其落地轨迹。注意一个细节：计划中的"v1.45.0.0 地基"实际以 v1.46.0.0 发布（CHANGELOG.md 的 1.46.0.0 条目标题即 "gstack v2 foundation lands"，且测试文件头部注释仍自称 "v1.45.0.0 T1"）。

v1.46.0.0 的实测数字（来源：bun run scripts/capture-baseline.ts --tag v1.46.0.0 对照锁定的 v1.44.1 基线 test/fixtures/parity-baseline-v1.44.1.json，可用 bun test test/skill-size-budget.test.ts 本地复现）：

指标	v1.44.1	v1.46.0.0	Δ
目录 tokens（常驻系统提示）	~9,319	~4,045	−56.6%
SKILL.md 语料总量	2,847 KB	2,813 KB	−1.2%
gate 级 eval 覆盖技能数	32/51	51/51	地板达成
大教堂 parity 不变量	0	10	结构 + 内容
CI 捕获的预算回归测试文件	（无）	5 个新测试文件	单技能、语料、目录、eval 成本 gate/periodic

两点值得注意：技能数从计划时的 31 增长到 51，说明"eval 先行地板"（新技能没有 test/skill-coverage-matrix.ts 条目即 CI 失败）确实约束住了增长；语料总量几乎没动，是因为目录瘦身是"搬"路由文字从 frontmatter 到正文段落，而非删除——真正省掉的是每次会话启动都支付的常驻面（约 5,274 tokens）。

大教堂 parity 套件（Codex 二轮咨询把范围"max it out to 11"的产物）落地形态：test/helpers/parity-harness.ts + parity 套件，PARITY_INVARIANTS 注册表为每个技能家族钉住必须保留的短语（cso: OWASP/STRIDE；plan-ceo: SCOPE EXPANSION / HOLD SCOPE；ship: VERSION/CHANGELOG/PR），防止未来的压缩悄悄剥掉承重散文。另有 test/skill-coverage-floor.test.ts 做逐技能结构性冒烟（frontmatter 形状、生成头、正文非平凡、无泄漏的 {{TEMPLATE}} 占位符），51 个技能 309 条断言、免费（纯文件 IO）。

sections/ 管线：ship/、plan-ceo-review/ 已完成骨架 + sections/*.md + sections/*.md.tmpl + manifest.json 的四件套；test/template-context-parity.test.ts 对应计划中"section 生成必须与 SKILL.md 生成使用同一 TemplateContext（同 skillName、同 host 抑制、同 explainLevel、同 tier 门控）"的契约断言。

尚未达到的状态（如实说明）：截至当前 VERSION（1.71.0.0），语料总量约 2.9MB（51 个技能）、ship/SKILL.md 约 91KB——计划中"700KB 语料 + 15KB 骨架"的 v2.0.0.0 协调发布目标在仓库当前状态下尚未完全兑现，sections/ 提取已覆盖首批重型技能（ship、plan-ceo-review 等，office-hours/SKILL.md 仍约 102KB 单体），这与计划"一次一个、验证后再转下一个"的保守节奏一致。

故障模式注册表

计划的"零关键缺口"结论来自逐故障模式登记。合并工程评审与 Codex 二轮补充后：

代码路径	故障模式	有救援？	有测试？	用户看到	记录位置
gen-skill-docs 门控检查	resolver appliesTo 抛错	是——try/catch 记录并跳过	是	"resolver X errored, skipped"	stderr
运行期 section Read	section 文件缺失	是——agent 回退到仅骨架行为	是	agent 散文中的警告	会话转录
CI 孤儿遍历器	sections/*.md 缺 eval 注释	v2.0 WARN；v2.1+ FAIL	是	PR 摘要列出孤儿	PR 评论
迁移脚本 v2.0.0.0.sh	损坏安装上再生失败	是——脚本中止并打印修复步骤	是	清晰错误 + 修复步骤	~/.gstack/analytics/migrations.jsonl
目录单行生成器	frontmatter 缺单行描述	是——gen-skill-docs 大声失败	是	构建错误	stderr
Canary section-Read 记录器	某重型技能缺记录器	是——静默跳过，缺口在面板可见	是	无直接感知	~/.gstack/analytics/section-reads.jsonl
sections/*.md.tmpl 生成器	模板引用缺失 resolver	是——gen-skill-docs 大声失败	是	构建错误	stderr
manifest ↔ 文件系统	manifest 引用不存在的 section	是——CI 检查失败	是（section-manifest-consistency 测试）	构建错误	PR 摘要
manifest ↔ 文件系统	section 存在但不在 manifest	v2.0 WARN；v2.1+ FAIL	是	PR 摘要	PR 评论
预算上限	单次或聚合超 EVALS_BUDGET_HARD_CAP	是——CI 失败	是	构建错误 + 成本分解	stderr
section 管线 TemplateContext	section 以漂移的 ctx 生成	是——parity 测试失败	是	构建错误	stderr
手改生成 section	用户直接编辑 .md 而非 .tmpl	是——CI 带明确消息失败	是	"this file is generated, edit .tmpl instead"	PR 摘要
质量预算	v2 压缩后 LLM-judge parity 掉 >2 分	是——CI 失败	是	"v2 X.md dropped from 9.2 to 6.4"	PR 评论 diff
预算上限覆盖审计	使用了 OVERRIDE_REASON	否（有意逃生阀）	是（审计日志测试）	理由打印 + 记入审计 jsonl	analytics/spend-overrides.jsonl
parity 基线漂移	每周监控检出回归	是——告警 + 工单	是	团队频道告警	analytics/parity-drift.jsonl

范围外与延期项

明确不做（用户要求"保留全部功能"）：不删技能（qa-only、design-shotgun、pair-agent、open-gstack-browser 全留）；不重命名（保持 CLI 表面稳定）。延期至 v2 之后的 TODO（9 项，合并后批量入 TODOS.md）：

TODO	优先级	工作量（人 / CC）	依赖
gstack lite 安装档案（5 技能核心）	P2	2 天 / 3–4 小时	v2.0.0.0
gstack pro 可选升级路径	P2	1 天 / 1 小时	gstack lite
gstack budget CLI（逐技能 token 使用量遥测）	P2	1 天 / 1 小时	v1.45.0.0
逐技能 eval 覆盖徽章（list 输出 + README）	P3	1 天 / 1 小时	Phase 0
跨工具可移植性测试/演示（Codex CLI、Cursor）	P3	2 天 / 2 小时	v2.0.0.0
技能调用时的 token 成本预览	P3	1 天 / 1 小时	budget CLI
技能自加载遥测（死重检测）	P3	2 天 / 2 小时	v1.45.0.0
gstack diff PR 评论（逐 PR 预算增量）	P3	1 天 / 1 小时	budget-regression 扩展
section 级 eval 注释对用户可见（信心信号）	P3	半天 / 30 分钟	Phase C

v2 发布文案规范

DX 评审把发布文案直接写进计划作为 T15 的交付规格（T15 逐字实现，除非发布时打磨出"可度量更好"的版本）：

JUST_UPGRADED 通知（面向老用户升级）：由 gstack-update-check 检出 JUST_UPGRADED v1.x v2.0.0.0 触发，替换通用提示。文案要点：先讲收益（"~67% lighter"）、给具体数字、安抚肌肉记忆（"/ship、/qa、/review 命令没变"）、留逃生口（/gstack-upgrade --explain-v2）、不用破折号、瞄准 5 秒读完。

CHANGELOG 数字表（v1 vs v2，占位值需在 T15 用实测替换）：语料 2.1MB → ~700KB（−67%）；ship.md 164KB → ~15KB 骨架 + 5×~5KB sections（首次 Read −76%）；目录 ~25K → ~6K tokens（−76%）；典型 /ship 会话 ~41K → ~14K tokens（约 −60%）；eval 覆盖 ~16/31 → 31/31 + parity 基线；parity 分数 ≥9.0/10 地板（CI 强制）。

README v2 横幅：置于现有 Karpathy 引言上方，发布后保留 60 天再折叠为一行。文案规则：先讲定位（"lightest opinionated skill pack"）、给具体数字（2.1MB → 700KB）、给严谨性证明（eval 保护 + parity 监控）、迁移路径明确、瞄准 10 秒读完。

实现纪律（计划原文）：v1.44 基线数字必须在 Phase A 再生开始前锁进 test/helpers/parity-baseline-v1.44.1/，delta 只有在同单位测量下才准引用（token 用 tiktoken、字节用 wc -c、eval 覆盖用 coverage-matrix）；若实测数字不如草稿好看，改草稿而不是编数字——"营销级发布时刻在读到一个能用 wc -c 证伪的数字那一瞬间就死了"。当前仓库中 test/fixtures/parity-baseline-v1.44.1.json 就是这条纪律的实物。

验证清单（按发布）

v1.45/1.46（地基）：

1. bun run gen:skill-docs 无错误成功（对应 package.json 的 gen:skill-docs 脚本）
2. bun test 通过（skill-validation、gen-skill-docs 测试、browse 集成、新的 skill-coverage-matrix 测试）
3. bun run test:evals 通过——新 gate eval 全绿，既有 eval 无回归
4. bun run test:evals:periodic 通过
5. 目录系统提示尺寸实测 ≤8K tokens（计划估算值；v1.46 实测为 9,319 → 4,045），前后值写进 PR 正文
6. 语料总字节 ≤1.3MB（对照 2.1MB）
7. 最重 3 个技能在 100KB 之下
8. 手动冒烟：新 Claude Code 会话调用 /ship、/plan-ceo-review、/office-hours，确认无行为缺失，转录存为基线

v2.0.0.0：

1. 上述 v1.45 检查全过
2. 分 section 技能的语料总量 ≤700KB；重型骨架各自 ≤30KB
3. test/skill-e2e-ship-section-loading.test.ts 断言 /ship 按决策树 Read 预期 section
4. Canary 组：v2.0.0-rc.1 一周 dogfood + 转录记录，标记必需的 section 零漏读
5. 五大工作流人工验证，转录对照 v1.45 基线
6. 迁移：v1.45 安装的 gstack-upgrade 无提示干净再生；vendored 安装出现一次警告
7. CHANGELOG 数字表与实测一致
8. WARN 模式孤儿检查：PR 摘要显示孤儿列表，构建仍通过

执行序与跨模型共识

v1.45 在单分支串行执行 T1 → T8（Codex 二轮批评指出 T2 与 T4 几乎必然在编译期互相触碰，并行分支各自绿、集成炸；AI 压缩让串行的挂钟成本可接受），v2.0 走 T9 → T15 的集成序，T16（TODOS 批量入册）随时落地。任务粒度示例：T2（条件化 resolver 门控，CC 约 1 小时，改 types.ts + gen-skill-docs.ts:444 + resolvers/index.ts）；T9（ship/ 转骨架 + sections/，CC 约 3 小时，验收 = 新的 section-loading 测试绿 + ship.md 骨架 <15KB）；T10（ship/ canary 组，产出 test/helpers/transcript-section-logger.ts）。

最终裁决（五轮评审：CEO + ENG + Codex×2 + DX）：CEO/ENG/DX 全部 CLEAR，0 个未解决决策。混合 v1.45/v2.0 拆分降低了"胖"口碑修复的风险；sections/*.md.tmpl 管线（D2）消灭漂移；CI 成本上限 + 覆盖审计（D3）防止 eval 花费失控；大教堂 parity 套件捕获 section-loading 与预算测试都看不见的注意力架构隐性回归；串行执行用挂钟换集成安全；发布文案规范让营销级发布时刻同时命中 persona A（老用户升级者）与 persona B（新评估者）。

对读者可迁移的方法论：这份计划的普适价值不在于 gstack 本身，而在于它示范了"给一个已发布、被外部依赖的 prompt 资产做减法"的完整工程纪律——先锁定行为基线（parity 快照）再动结构，用 eval 把"必须有"变成可断言的契约，用结构化 manifest 加命令式散文加测试层机械检查三层防懒加载丢行为，用"先测量、再架构、数字必须可复现"拒绝一切营销数字。这套顺序反过来做（先瘦身后补测试），静默退化几乎必然发生。