Skip to content

Commit 88eb867

Browse files
committed
feat: strengthen governance intake and profile overlay
1 parent 7bab37f commit 88eb867

23 files changed

Lines changed: 635 additions & 29 deletions

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ DevCodex 通过 `.github/`(Copilot)、`CLAUDE.md + .claude/ + .mcp.json`(C
4343
- **项目现实扩展**: 先做语义意图初判,再结合目标项目 Profile、目录与当前任务上下文修正最终路由、产物落点和验证方式
4444
- **支撑型 Skill**: `execution-contract` / `test-router` / `release-verification` / `host-contract-verification` / `source-consumer-sync` 为控制面、多批次、测试路线、宿主契约验证与真相源-消费者同步提供可审计支撑,不新增工作流分支
4545
- **README 专项能力**: `readme-authoring` 负责 README 用户/使用者优先写作,`audit-readme` 负责 README / 用户使用文档专项 review
46+
- **规范治理 Intake**: 所有模式下每条用户消息在合理性评估后都会额外检查是否命中可泛化改进;命中时主动写入 `data/process-improvements.md`(优化清单,PI),必要时联动 `data/pending-fixes.md`(PF),并显式回执 `PI/PF`
47+
- **Profile 本地私有配置**: `config.local.json` 支持长期连接、env 引用和 `extensions.<namespace>` 受控扩展位;文件应加入 `.gitignore`,且不能覆盖 `mode` / `agent`
4648
- **执行闭环复审**: dev/fix 完成前执行 ECR 执行闭环复审,交叉验证 CP 产物、报告、daily memory、SUMMARY、diff/commit、测试/探针与 dirty 边界
4749
- **推荐结论**: analyze/audit/report 多建议或多路径场景必须给出推荐结论与推荐理由;无后续动作时明确写“推荐:无后续动作”
4850
- **确认交互降级**: 用户确认先抽象为 ConfirmationRequest,再按宿主能力选择按钮、权限提示、Hook 阻断或文本确认 fallback,不把按钮 UI 承诺为全宿主能力
@@ -189,6 +191,7 @@ AGENTS.md ← 与 instructions.md / copilot-instructions.md / CL
189191
- 单项目任务:写入 `<workspace>/.devcodex/<project>/...`
190192
- 全工作区任务:写入 `<workspace>/.devcodex/workspace/...`
191193
- `config.json`:`workspace/profile` 作为 base,`<project>/profile` 作为 overlay
194+
- `config.local.json`:与 `config.json` 采用相同的 `workspace/profile + <project>/profile` overlay 模型,但仅用于本地私有配置、长期连接和 `extensions.<namespace>`;不覆盖 `mode` / `agent`
192195
- Profile 文档:项目命名空间文件优先,缺失回退到 `workspace/profile`
193196
- CLI / Hook 运行态目录:统一写 active-root;单项目为 `<workspace>/.devcodex/<project>/.memory|.audit-state`,全工作区为 `<workspace>/.devcodex/workspace/.memory|.audit-state`
194197
- 多项目 workspace 根缺少 workspace profile 时,Hook 提示真实路径 `.devcodex/workspace/profile/`;同一宿主会话已识别唯一项目后,后续“继续/确认”会在短 TTL 内沿用该项目和项目 `mode`,新会话、TTL 过期或显式 workspace 请求会重新判断。
@@ -278,7 +281,7 @@ devcodex/
278281
└── plugin.json # 插件元数据
279282
```
280283

281-
规范治理新增 `spec-governance` Skill:记录类动作先做意图识别,再由 RecordRouter 分流到 `violations / pending-fixes / process-improvements / pending-issues / gap-registry`;规范/控制面/路径/模板/部署/校验链变更后必须执行 SCV(Spec Change Verification),避免修复一处后引入漂移。
284+
规范治理新增 `spec-governance` Skill:记录类动作先做意图识别,再由 RecordRouter 分流到 `violations / pending-fixes / process-improvements(优化清单,PI) / pending-issues / gap-registry`;所有模式下每条用户消息还会执行主动 Improvement Intake,把已验证更优且可泛化的策略记录到优化清单,并在暴露规范缺口时同步联动 PF。规范/控制面/路径/模板/部署/校验链变更后必须执行 SCV(Spec Change Verification),避免修复一处后引入漂移。
282285

283286
控制面与长流程当前有五类支撑型 Skill:`execution-contract` 约束 scope / allowedPaths / requiredArtifacts / consumerScope / validationRoute / deviationLog,`test-router` 统一选择验证路线,`release-verification` 在正式 tag / publish 前执行 R0~R7 发布验证链,`host-contract-verification` 负责 direct replay / fixture replay / bootstrap / workspace guard 证据,`source-consumer-sync` 负责 Concept Sync Map 与当前消费者同步边界。
284287

‎changelogs/unreleased.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,5 @@
1515
## 2026-05-29
1616

1717
- README 治理增强:新增 `readme-authoring` / `audit-readme`,将 README 默认主视角收口为用户 / 使用者优先,并补 `V38`、`test-readme-governance`、资产口径同步与专项 README review。
18+
- 治理台账增强:引入 Improvement Intake,`process-improvements.md` 明确升格为“优化清单(PI)”;所有模式下对可泛化更优策略或规范缺口执行主动记录与 `PI/PF` 回执,并补 `V39` 与 `test-governance-intake`。
19+
- Profile 本地 overlay 增强:新增 `config.local.json` 受控模型(长期连接、env 引用、`extensions.<namespace>`、文档说明义务、gitignore 保护),同步到 profile init、MCP profile load、`validate-profile`、`test-validate-profile` 与 `V40`。

‎data/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,5 +56,6 @@ data/
5656

5757
- `data/pending-fixes.md`:承载运行时 PF(规范缺口)记录,主要由 PC4 / spec-radar / audit 轻量登记使用
5858
- `data/pending-issues.md`:承载**已确认但不阻断当前任务**的治理改进项,按批次进入后续需求或 bug 修复流程
59-
- `data/process-improvements.md`:只记录“已确认更优的执行策略”,不替代前两者
59+
- `data/process-improvements.md`:即“优化清单(PI)”,只记录“已确认更优且可泛化的执行策略”,不替代前两者
6060
- `data/violations.md`、`data/pending-fixes.md`、`data/process-improvements.md`、`data/pending-issues.md`、`data/gap-registry.md` 的写入必须先经 `spec-governance` 的 RecordRouter 分流,记录规范化意图、置信度、依据和目标台账
61+
- 若改进建议针对 DevCodex 规范自身、Hook、Skill、模板、validate 或宿主适配链路,而不是当前业务项目,则 `PI/PF` 应写回承载 DevCodex 规范资产的 active-root;不要把规范治理建议落到业务项目台账
Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
# 过程改进记录(template)
1+
# 过程改进记录 / 优化清单(template)
22

33
> **文件定位**:模板。`devcodex init` / `devcodex init --claude` 复制为目标项目运行时 `data/process-improvements.md`(Copilot: `.github/data/process-improvements.md`;Claude Code: `.claude/data/process-improvements.md`)。
4-
> **使用**:C17 触发时追加 PI 条目。
4+
> **使用**:C17 / Improvement Intake 命中时追加 PI 条目;所有模式命中后都需回执 `已记录 PI-xxx` 或 `已记录 PI-xxx / PF-xxx`。
55
> **维护者记录**:不在本包内分发;启用 `workspace-namespace` 时写入对应 active-root,例如 `<工作区根>/.devcodex/<project>/data/process-improvements.md`。
6+
> **归属提醒**:若建议针对 DevCodex 规范自身、Hook、Skill、模板、validate 或宿主适配链路,则应写入承载这些规范资产的 active-root,而不是当前业务项目台账。
67
78
---
89

@@ -12,17 +13,19 @@
1213
|------|------|
1314
| 编号 | `PI-NNN` |
1415
| 日期 | `YYYY-MM-DD` |
15-
| 触发场景 | 用户建议的执行策略 |
16+
| 触发来源 | 用户建议 / AI 复盘 / audit 建议 / 主动 intake |
17+
| 触发场景 | 用户建议的执行策略或主动 Intake 命中的规范改进点 |
1618
| 规范化意图 | `record.process-improvement` |
1719
| 策略来源 | 用户建议 / AI 复盘 / audit 建议 |
1820
| 可泛化理由 | 为什么不是一次性偏好 |
21+
| 关联缺口 | 无 / `PF-NNN`(若同时暴露规范缺口) |
1922
| 采纳证据 | 已确认依据或验证结果 |
2023
| 是否纳规 | ✅ 已纳入规范 / 🔄 待评估 |
2124

2225
---
2326

2427
## 登记表
2528

26-
| 编号 | 日期 | 触发场景 | 规范化意图 | 策略来源 | 可泛化理由 | 采纳证据 | 是否纳规 |
27-
|------|------|---------|--------------|----------|------------|----------|:--------:|
28-
| PI-000 | YYYY-MM-DD | EXAMPLE — 删除本行 | record.process-improvement | 用户建议 | 示例理由 | 示例证据 | 🔄 |
29+
| 编号 | 日期 | 触发来源 | 触发场景 | 规范化意图 | 策略来源 | 可泛化理由 | 关联缺口 | 采纳证据 | 是否纳规 |
30+
|------|------|---------|---------|--------------|----------|------------|----------|----------|:--------:|
31+
| PI-000 | YYYY-MM-DD | EXAMPLE — 删除本行 | EXAMPLE — 删除本行 | record.process-improvement | 用户建议 | 示例理由 | 无 | 示例证据 | 🔄 |

‎index.js‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,9 +131,12 @@ const DEVCODEX_GITIGNORE_ENTRIES = [
131131
'.devcodex/.memory/',
132132
'.devcodex/.audit-state/',
133133
'.devcodex/.tmp/',
134+
'.devcodex/profile/config.local.json',
135+
'.devcodex/workspace/profile/config.local.json',
134136
'.devcodex/*/.memory/',
135137
'.devcodex/*/.audit-state/',
136-
'.devcodex/*/.tmp/'
138+
'.devcodex/*/.tmp/',
139+
'.devcodex/*/profile/config.local.json'
137140
]
138141

139142
function ensureDevCodexGitignore(cwd, dryRun, log = console.log) {
@@ -1021,6 +1024,7 @@ function genProfileReadme(_ctx) {
10211024
| 02-架构约束.md | 目录结构 / 模块边界 |
10221025
| 03-代码风格.md | 编码规范 / lint / 格式化 |
10231026
| config.json | ENV_MODE + agent 兜底标识 |
1027+
| config.local.json | 可选,本地私有 overlay:长期连接、env 引用、\`extensions.<namespace>\`(不提交) |
10241028
`
10251029
}
10261030

@@ -1052,6 +1056,11 @@ function genProjectInfo(ctx) {
10521056
| **当前阶段** | v${ver} 初始草稿 |
10531057
| **主版本分支** | ${branch} |
10541058
| **阶段摘要** | ${changelogTop || '(未在 CHANGELOG.md 中识别)'} |
1059+
1060+
## 本地配置与扩展说明(可选)
1061+
1062+
- 若项目使用 \`config.local.json\` 保存长期连接别名、本机专属配置或 env 引用,请在本文件说明用途与使用方式。
1063+
- 项目级扩展只能写在 \`extensions.<namespace>\` 下,并记录字段语义、取值来源和是否依赖 \`*Env\` / \`secretRef\`。
10551064
`
10561065
}
10571066

‎instructions.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
| C14 | 多任务检查点 | ≥2 个独立任务:每完成一个追加进度到记忆 + 输出进度快照 |
5252
| C15 | 架构质量视角 | dev/fix 涉及代码设计须从架构师+平台工程师双视角评估:可扩展性/可维护性/易上手性 |
5353
| C16 | 批量操作分批 | ≥10 文件批量操作必须主动提出分批方案(推荐每批 10 个),输出计划后等待确认 |
54-
| C17 | 过程改进记录 | 用户建议的策略经确认更优时立即追加 PI 条目到 `data/process-improvements.md` |
54+
| C17 | 过程改进记录 | 用户建议的策略经确认更优,或揭示规范未定义/不完整且可泛化时,必须走 Improvement Intake:将策略写入 `data/process-improvements.md`(优化清单,PI);若同时暴露规范缺口,再联动 `data/pending-fixes.md`(PF)。不得询问是否记录;所有模式命中后都必须显式回执已记录的 `PI-xxx / PF-xxx` |
5555
| C18 | 全模式入口检查不可跳过 | 同 S07 |
5656
| C19 | 确认后前置复审 | 每次用户明确确认后、进入下一阶段前,必须先对当前已确认产物做 1 轮轻量前置复审,并显式输出结果;控制面 / 多文件联动 / 真相源同步 / 模板-示例-校验链场景必须追加交叉验证;若发现阻断性问题,先修正并告知用户,再重新确认;无阻断问题方可推进 |
5757

@@ -110,6 +110,7 @@
110110
- Hook Stop/PreCompact 对入口检查块的可见回复验证必须区分 `verified-present` / `verified-missing` / `unverified` 三态;无法解析最终 assistant 内容时只能提示“无法验证最终用户可见回复”并附 payload capture 指引,禁止断言“未输出”。
111111
- 当 `<工作区根>/.devcodex/layout.json` 启用 `workspace-namespace` 时,Profile 与运行态目录按**工作区集中命名空间**读取:
112112
- `config.json`:`<工作区根>/.devcodex/workspace/profile/` 作为 base,`<工作区根>/.devcodex/<project>/profile/` 作为 overlay
113+
- `config.local.json`:与 `config.json` 使用相同的 `workspace base + project overlay` 路径模型,但仅承载本地私有 overlay(长期连接、env 引用、`extensions.<namespace>`);不得覆盖 `mode` / `agent` / `pluginVersion`
113114
- Profile 文档:项目命名空间文件优先,缺失回退到 `workspace/profile/`
114115
- 运行态目录:单项目写 `<工作区根>/.devcodex/<project>/...`,全工作区写 `<工作区根>/.devcodex/workspace/...`
115116
- workspace-namespace 下缺少 workspace profile 的多项目提示必须指向 `.devcodex/workspace/profile/`;同一宿主会话已识别唯一目标项目时,后续“继续 / 确认”等消息可在短 TTL 内沿用 sticky `activeProject` 与项目 `mode`,但新会话、TTL 过期、命中多个项目或用户显式选择 workspace 时必须重新判断。
@@ -122,6 +123,7 @@
122123
| `02-架构约束.md` | 目录结构/边界 | 是 |
123124
| `03-代码风格.md` | 编码规范 | 是 |
124125
| `config.json` | ENV_MODE + agent 兜底标识 | 按需 |
126+
| `config.local.json` | 本地私有 overlay:长期连接、env 引用、`extensions.<namespace>` 扩展位(不提交) | 可选 |
125127

126128
> **Copilot / Claude Code / Codex 三宿主 Bootstrap 提醒**(v1.11.0+):`lifecycle.cjs` 只在宿主实际提供 Hook 事件时形成 runtime 护栏。Claude Code 具备项目级 hooks + MCP,是当前 Full 路径;Codex 通过 `.codex/hooks.json` 接入,阻断输出按事件契约区分顶层 `decision`、`continue:false` 与工具级 `permissionDecision`;Copilot / JetBrains / Cursor 默认按 instruction-fallback 处理,不承诺本地 Hook 硬拦。默认 `safety-only` 模式下,bootstrap / CP / auto 白名单等流程问题输出提醒并放行工具,仅危险命令继续硬拦;设置 `DEVCODEX_HOOK_ENFORCEMENT=strict` 时,只有支持硬拦的事件才停止流程。AI 仍须在首条用户可见回复输出 PC0~PC7 入口检查块(S07/C18)。
127129
@@ -162,6 +164,20 @@
162164

163165
每次记录分流必须输出 `规范化意图`、`置信度`、`依据`、`目标台账`。低置信度不得静默写台账。重复 VL 必须判断是否升级 PF/GAP,不能只追加重复违规。
164166

167+
### Improvement Intake(优化清单)
168+
169+
在所有模式下,每条用户消息在完成合理性评估后,都必须额外判断一次:该消息是否提出了**已验证更优且可泛化的执行策略**,或是否暴露了**规范未定义/不完整**。命中时,不必等待用户显式说“记录一下”,而是主动执行 Improvement Intake:
170+
171+
| 判定 | 处理 |
172+
|------|------|
173+
| 仅更优策略,可泛化 | 记录 `PI`(优化清单) |
174+
| 仅暴露规范缺口 | 记录 `PF` |
175+
| 同时存在更优策略 + 规范缺口 | 同时记录 `PI + PF` |
176+
| 只是当前执行没做到,但规则已存在 | 记录 `VL` |
177+
| 一次性偏好、业务局部需求、不可泛化想法 | `record.none`,不写台账 |
178+
179+
所有模式下,主动 Intake 完成后必须显式回执:`已记录 PI-xxx`、`已记录 PF-xxx` 或 `已记录 PI-xxx / PF-xxx`。`data/process-improvements.md` 在本轮也可称“优化清单(PI)”,但它仍是当前 active-root 的运行时台账;若建议针对 DevCodex 规范自身,则必须归属 DevCodex 规范维护项目的 active-root,而不是业务项目台账。
180+
165181
### 台账落点与关闭证据
166182

167183
- `data/*.md` 是运行时逻辑台账路径,实际写入必须按当前 active-root 映射:旧布局写 `<项目根>/.devcodex/data/`,workspace-namespace 单项目写 `<工作区根>/.devcodex/<project>/data/`,全工作区写 `<工作区根>/.devcodex/workspace/data/`。

‎instructions/01-common.instructions.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ applyTo: "**"
6161
| C14 | 多任务进度检查点 | 会话包含 ≥2 个独立任务时,每完成一个子任务必须:① 在记忆文件追加该任务进度状态 ② 在对话中输出进度快照(格式严格遵循 `prompts/reply-summary.prompt.md` §6) |
6262
| C15 | 架构质量视角 | dev/fix 任务中涉及代码设计或架构决策的输出须以**架构师与平台工程师**双重视角评估三维质量:① 可扩展性 ② 可维护性 ③ 易上手性。任意维度未达标须说明原因并记录改善方向 |
6363
| C16 | 批量操作分批 | 执行涉及 ≥10 个文件的批量操作(如测试迁移、批量重命名、批量改写)时,必须主动提出分批方案,推荐每批 10 个,并输出分批计划后等待用户确认再开始执行 |
64-
| C17 | 过程改进记录 | 用户建议的执行策略经 AI 确认更优时,必须立即追加一条 PI 条目到 `data/process-improvements.md`(不得询问是否记录),并标注是否已纳入规范 |
64+
| C17 | 过程改进记录 | 用户建议的执行策略经 AI 确认更优,或揭示规范未定义/不完整且可泛化时,必须立即走 Improvement Intake:写入 `data/process-improvements.md`(优化清单,PI);若同时暴露规范缺口,再联动 `data/pending-fixes.md`(PF)。不得询问是否记录;所有模式命中后都必须回执 `已记录 PI-xxx / PF-xxx` |
6565
| C19 | 确认后前置复审 | 每次用户明确确认后、进入下一阶段前,必须先对当前已确认产物做 1 轮轻量前置复审,并显式输出结果;控制面 / 多文件联动 / 真相源同步 / 模板-示例-校验链场景必须追加交叉验证;若发现阻断性问题,先修正并告知用户,再重新确认;无阻断问题方可推进 |
6666

6767
## 统一联查矩阵(C11 扩展)
@@ -289,7 +289,19 @@ applyTo: "**"
289289
- 有明确问题描述
290290
- 有影响范围或适用范围
291291
- 能在后续按批次进入需求/bug 修复流程
292-
- `data/process-improvements.md` 只记录“已确认更优的执行策略”,不替代问题池本身。
292+
- `data/process-improvements.md`(优化清单,PI)只记录“已确认更优且可泛化的执行策略”,不替代问题池本身。
293+
- 若建议针对 DevCodex 规范自身、Hook、Skill、模板、validate 或宿主适配链路,而不是当前业务项目,则 PI/PF 必须写回承载 DevCodex 规范资产的 active-root。
294+
295+
### Improvement Intake(优化清单)
296+
297+
- 所有模式下,每条用户消息完成合理性评估后,都要额外检查是否命中“可泛化更优策略”或“规范缺口暴露”。
298+
- 命中后即使用户没有显式说“记录一下”,也要主动分流:
299+
- 仅更优策略 → PI
300+
- 仅规范缺口 → PF
301+
- 二者并存 → PI + PF
302+
- 已有规则未执行 → VL
303+
- 一次性偏好或业务局部诉求 → 不写台账
304+
- 所有模式命中后都必须显式回执 `已记录 PI-xxx`、`已记录 PF-xxx` 或 `已记录 PI-xxx / PF-xxx`。
293305

294306
### 官方文档优先级
295307

@@ -316,6 +328,7 @@ applyTo: "**"
316328
317329
- **Profile / config 读取**:
318330
- `config.json` 采用 `workspace base + project overlay`
331+
- `config.local.json` 与 `config.json` 同路径模型,但仅用于本地私有 overlay(长期连接、env 引用、`extensions.<namespace>`),不得覆盖 `mode` / `agent` / `pluginVersion`
319332
- `README.md`、`01-项目信息.md`、`02-架构约束.md`、`03-代码风格.md` 采用 `project file first + workspace fallback`
320333
- **运行态目录写入**:采用 `single active scope write`
321334
- 单项目任务:写入 `<工作区根>/.devcodex/<project>/...`

0 commit comments

Comments
 (0)