@michelj/context-guard 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +55 -24
  2. package/README.zh-CN.md +55 -24
  3. package/bin/context-guard-skill.js +5 -5
  4. package/bin/postinstall.js +28 -0
  5. package/package.json +2 -1
  6. package/skills/context-guard/README.md +55 -24
  7. package/skills/context-guard/README.zh-CN.md +55 -24
  8. package/skills/context-guard/SKILL.md +42 -3
  9. package/skills/context-guard/scripts/context_guard.py +305 -80
  10. package/skills/context-guard/scripts/context_guard_hook.py +59 -2
  11. package/skills/context-guard/tests/BC-20260702-096.sh +45 -0
package/README.md CHANGED
@@ -14,6 +14,7 @@ Context Guard is a Codex skill for durable project memory. It keeps the task rou
14
14
  - **Supports record language preferences**: writes future context in Chinese or English.
15
15
  - **Handles task switches**: parks, resumes, and branches interrupted work.
16
16
  - **Keeps tests human-designed**: Codex reuses approved checks or proposes drafts, but does not silently create durable tests.
17
+ - **Covers bad cases with feature chains**: prefer one real feature/workflow chain covering multiple bad cases over one separate test per bad case.
17
18
  - **Runs approved tests by default**: user-created or user-approved tests run at every development completion unless the user sets another cadence.
18
19
  - **Provides a Test Hub entrypoint**: `dev-complete` runs approved always-run tests, cleans success artifacts, and preserves failed evidence.
19
20
 
@@ -22,13 +23,19 @@ Context Guard is a Codex skill for durable project memory. It keeps the task rou
22
23
  Install with npx:
23
24
 
24
25
  ```bash
25
- npx context-guard install
26
+ npx @michelj/context-guard install
27
+ ```
28
+
29
+ Or install globally and let the package copy the skill into Codex's skill directory automatically:
30
+
31
+ ```bash
32
+ npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
26
33
  ```
27
34
 
28
35
  Install hooks only when you explicitly want Context Guard reminders at Codex lifecycle events:
29
36
 
30
37
  ```bash
31
- npx context-guard install --with-hooks
38
+ npx @michelj/context-guard install --with-hooks
32
39
  ```
33
40
 
34
41
  Use from GitHub before the npm package is published:
@@ -42,14 +49,14 @@ Manual install is also supported:
42
49
  ```bash
43
50
  git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
44
51
  cd Context-Guard-Skill
45
- mkdir -p ~/.agents/skills/context-guard
46
- rsync -a --delete skills/context-guard/ ~/.agents/skills/context-guard/
52
+ mkdir -p ~/.codex/skills/context-guard
53
+ rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
47
54
  ```
48
55
 
49
56
  After installation, Codex should discover:
50
57
 
51
58
  ```text
52
- ~/.agents/skills/context-guard/SKILL.md
59
+ ~/.codex/skills/context-guard/SKILL.md
53
60
  ```
54
61
 
55
62
  ## Where Context Lives
@@ -70,39 +77,60 @@ Do not write project context into:
70
77
  When running scripts manually, pass the project root explicitly:
71
78
 
72
79
  ```bash
73
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
80
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
74
81
  ```
75
82
 
76
83
  Register a user-approved automated test:
77
84
 
78
85
  ```bash
79
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-add \
86
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
80
87
  --root /path/to/project \
81
88
  --title "Markdown preview rendering" \
82
89
  --command-text "npm test"
83
90
  ```
84
91
 
92
+ Register a user-approved feature-chain test:
93
+
94
+ ```bash
95
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
96
+ --root /path/to/project \
97
+ --title "GPU monitor button" \
98
+ --entry "Click the GPU monitor button" \
99
+ --exit-check "Open a monitoring page with a valid grafana_url" \
100
+ --command-text "npm test -- gpu-monitor"
101
+ ```
102
+
103
+ Attach a bad case to a specific feature-chain checkpoint:
104
+
105
+ ```bash
106
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
107
+ --root /path/to/project \
108
+ --chain-id FC-... \
109
+ --node-title "Backend returns monitor URL" \
110
+ --bad-case BC-... \
111
+ --check "grafana_url is non-empty and the frontend does not hang"
112
+ ```
113
+
85
114
  After development, hand completion to the Test Hub:
86
115
 
87
116
  ```bash
88
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
117
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
89
118
  ```
90
119
 
91
- Open the Test Hub page; use the localhost console for one-click runs:
120
+ Open the read-only Test Hub page:
92
121
 
93
122
  ```bash
94
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
95
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py serve-test-hub --root /path/to/project --port 8772 --open
123
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
96
124
  ```
97
125
 
98
126
  Manage tests lightly:
99
127
 
100
128
  ```bash
101
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
102
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "not needed every time"
103
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
104
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "only editor changes need it"
105
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
129
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
130
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "not needed every time"
131
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
132
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "only editor changes need it"
133
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
106
134
  ```
107
135
 
108
136
  ## Common Usage
@@ -122,31 +150,31 @@ Use $context-guard to show the roadmap.
122
150
  Initialize project context:
123
151
 
124
152
  ```bash
125
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py init --root /path/to/project
153
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
126
154
  ```
127
155
 
128
156
  Set the record language:
129
157
 
130
158
  ```bash
131
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
159
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
132
160
  ```
133
161
 
134
162
  Generate the roadmap:
135
163
 
136
164
  ```bash
137
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
165
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
138
166
  ```
139
167
 
140
168
  Or use the npm CLI as a thin wrapper:
141
169
 
142
170
  ```bash
143
- npx context-guard show-roadmap --root /path/to/project
171
+ npx @michelj/context-guard show-roadmap --root /path/to/project
144
172
  ```
145
173
 
146
174
  Create a branch task:
147
175
 
148
176
  ```bash
149
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
177
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
150
178
  --root /path/to/project \
151
179
  --title "branch task title" \
152
180
  --branch "branch name" \
@@ -156,7 +184,7 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-ta
156
184
  Record a roadmap checkpoint:
157
185
 
158
186
  ```bash
159
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
187
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
160
188
  --root /path/to/project \
161
189
  --title "source title for Codex" \
162
190
  --display-title "short human title" \
@@ -192,9 +220,12 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadm
192
220
  - Human-facing titles should read naturally, not like implementation logs.
193
221
  - A bad case should help future Codex prevent recurrence.
194
222
  - Test design belongs to humans; Codex can run approved checks or draft a proposal for confirmation.
223
+ - Prefer feature chains as the durable testing unit: one clear entry, one real workflow, ordered checkpoints, and multiple covered bad cases.
224
+ - Attach new bad cases to an existing feature-chain checkpoint first; propose a new chain only when no existing workflow matches.
195
225
  - User-approved tests default to `every-dev-completion`; Codex may lower that cadence only when the user asks.
196
- - Approved automated tests should go into `.codex/context/test-hub/registry.json` and be scheduled through `dev-complete`.
197
- - Keep the Test Hub simple: one registry, one `dev-complete` runner, one latest-result file, one lightweight HTML control panel, and a few management commands.
226
+ - Approved automated tests should go into `.codex/context/test-hub/registry.json` or `.codex/context/test-hub/feature-chains.json` and be scheduled through `dev-complete`.
227
+ - Keep the Test Hub simple: one registry, one `dev-complete` runner, one latest-result file, one read-only HTML status page, and a few management commands.
228
+ - Final Codex summaries should state the current Test Hub result: whether approved always-run tests all passed, failed, blocked, or do not exist.
198
229
  - Verification should reuse existing commands, scripts, screenshots, or manual checks first.
199
230
  - Do not create a new script for every bad case.
200
231
  - For frontend or HTML changes, inspect the rendered page or screenshot before claiming success.
package/README.zh-CN.md CHANGED
@@ -14,6 +14,7 @@ Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线
14
14
  - **支持多语言记录**：按项目偏好用中文或英文写 context。
15
15
  - **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
16
16
  - **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
17
+ - **用功能链覆盖 bad case**：优先把多个 bad case 挂到同一条真实功能/工作流测试链上，而不是为每个 bad case 单独造测试。
17
18
  - **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
18
19
  - **提供测试中台入口**：`dev-complete` 会统一运行已确认的 always-run 测试，成功清理临时产物，失败保留证据。
19
20
 
@@ -22,13 +23,19 @@ Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线
22
23
  使用 npx 安装：
23
24
 
24
25
  ```bash
25
- npx context-guard install
26
+ npx @michelj/context-guard install
27
+ ```
28
+
29
+ 也可以全局安装，让 npm 包自动把 skill 复制到 Codex 的 skill 目录：
30
+
31
+ ```bash
32
+ npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
26
33
  ```
27
34
 
28
35
  只有当你明确希望安装 Codex 生命周期 hook 提醒时，才加 `--with-hooks`：
29
36
 
30
37
  ```bash
31
- npx context-guard install --with-hooks
38
+ npx @michelj/context-guard install --with-hooks
32
39
  ```
33
40
 
34
41
  npm 包正式发布前，也可以直接从 GitHub 使用：
@@ -42,14 +49,14 @@ npx github:Michel-Johnson/Context-Guard-Skill install
42
49
  ```bash
43
50
  git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
44
51
  cd Context-Guard-Skill
45
- mkdir -p ~/.agents/skills/context-guard
46
- rsync -a --delete skills/context-guard/ ~/.agents/skills/context-guard/
52
+ mkdir -p ~/.codex/skills/context-guard
53
+ rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
47
54
  ```
48
55
 
49
56
  安装后 Codex 应该能发现：
50
57
 
51
58
  ```text
52
- ~/.agents/skills/context-guard/SKILL.md
59
+ ~/.codex/skills/context-guard/SKILL.md
53
60
  ```
54
61
 
55
62
  ## Context 保存在哪里
@@ -70,39 +77,60 @@ Context 必须保存在当前打开的本地项目里：
70
77
  如果手动运行脚本，建议显式传入项目根目录：
71
78
 
72
79
  ```bash
73
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
80
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
74
81
  ```
75
82
 
76
83
  注册一个用户已确认的自动化测试：
77
84
 
78
85
  ```bash
79
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-add \
86
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
80
87
  --root /path/to/project \
81
88
  --title "Markdown 预览渲染" \
82
89
  --command-text "npm test"
83
90
  ```
84
91
 
92
+ 注册一条用户已确认的功能链测试：
93
+
94
+ ```bash
95
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
96
+ --root /path/to/project \
97
+ --title "GPU 监控按钮" \
98
+ --entry "点击 GPU 监控按钮" \
99
+ --exit-check "打开包含有效 grafana_url 的监控页" \
100
+ --command-text "npm test -- gpu-monitor"
101
+ ```
102
+
103
+ 把 bad case 挂到功能链的具体环节：
104
+
105
+ ```bash
106
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
107
+ --root /path/to/project \
108
+ --chain-id FC-... \
109
+ --node-title "后端返回监控 URL" \
110
+ --bad-case BC-... \
111
+ --check "grafana_url 不为空，前端不会卡住"
112
+ ```
113
+
85
114
  开发完成后交给测试中台：
86
115
 
87
116
  ```bash
88
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
117
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
89
118
  ```
90
119
 
91
- 查看测试中台页面；需要一键运行时启动 localhost 控制台：
120
+ 查看只读测试中台页面：
92
121
 
93
122
  ```bash
94
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
95
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py serve-test-hub --root /path/to/project --port 8772 --open
123
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
96
124
  ```
97
125
 
98
126
  简单管理测试：
99
127
 
100
128
  ```bash
101
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
102
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
103
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
104
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "只和编辑器改动相关"
105
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
129
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
130
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
131
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
132
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "只和编辑器改动相关"
133
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
106
134
  ```
107
135
 
108
136
  ## 常用方式
@@ -122,31 +150,31 @@ Use $context-guard to show the roadmap.
122
150
  初始化项目 context：
123
151
 
124
152
  ```bash
125
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py init --root /path/to/project
153
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
126
154
  ```
127
155
 
128
156
  设置记录语言：
129
157
 
130
158
  ```bash
131
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
159
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
132
160
  ```
133
161
 
134
162
  生成路线图：
135
163
 
136
164
  ```bash
137
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
165
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
138
166
  ```
139
167
 
140
168
  也可以用 npm CLI 作为轻量封装：
141
169
 
142
170
  ```bash
143
- npx context-guard show-roadmap --root /path/to/project
171
+ npx @michelj/context-guard show-roadmap --root /path/to/project
144
172
  ```
145
173
 
146
174
  创建支线任务：
147
175
 
148
176
  ```bash
149
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
177
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
150
178
  --root /path/to/project \
151
179
  --title "支线任务标题" \
152
180
  --branch "支线名称" \
@@ -156,7 +184,7 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-ta
156
184
  记录路线图节点：
157
185
 
158
186
  ```bash
159
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
187
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
160
188
  --root /path/to/project \
161
189
  --title "给 Codex 看的源标题" \
162
190
  --display-title "给用户看的短标题" \
@@ -192,9 +220,12 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadm
192
220
  - 用户看的标题要像人话，不要像实现日志。
193
221
  - bad case 要能帮助未来避免复发。
194
222
  - 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
223
+ - 测试的长期单位优先是功能链：一个明确入口、一段真实流程、多个检查点、覆盖多个 bad case。
224
+ - 新 bad case 优先挂到已有功能链节点；没有匹配功能链时，再提出新的功能链草案。
195
225
  - 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
196
- - 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json`，由 `dev-complete` 统一调度。
197
- - 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个轻量 HTML 控制台和几个管理命令。
226
+ - 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json` 或 `.codex/context/test-hub/feature-chains.json`，由 `dev-complete` 统一调度。
227
+ - 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个只读 HTML 状态页和几个管理命令。
228
+ - Codex 最终总结必须说明当前测试中台结果：已确认的 always-run 测试是否全部通过、失败、阻塞，或当前没有这类测试。
198
229
  - 测试链路优先复用已有命令、脚本、截图或人工检查。
199
230
  - 不要为了每个 bad case 都新写脚本。
200
231
  - 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。
package/bin/context-guard-skill.js CHANGED
@@ -20,9 +20,9 @@ Usage:
20
20
  context-guard <context_guard.py command> [args...]
21
21
 
22
22
  Examples:
23
- npx context-guard install
24
- npx context-guard install --with-hooks
25
- npx context-guard show-roadmap --root /path/to/project
23
+ npx @michelj/context-guard install
24
+ npx @michelj/context-guard install --with-hooks
25
+ npx @michelj/context-guard show-roadmap --root /path/to/project
26
26
  `);
27
27
  }
28
28
 
@@ -42,8 +42,8 @@ function defaultSkillTarget() {
42
42
  if (process.env.CONTEXT_GUARD_SKILL_TARGET) {
43
43
  return path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET));
44
44
  }
45
- const agentsHome = process.env.AGENTS_HOME || path.join(os.homedir(), ".agents");
46
- return path.join(agentsHome, "skills", "context-guard");
45
+ const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
46
+ return path.join(codexHome, "skills", "context-guard");
47
47
  }
48
48
 
49
49
  function defaultHooksTarget() {
package/bin/postinstall.js ADDED
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ const path = require("path");
5
+ const { spawnSync } = require("child_process");
6
+
7
+ const isGlobalInstall = String(process.env.npm_config_global || "").toLowerCase() === "true";
8
+ const autoInstall = process.env.CONTEXT_GUARD_AUTO_INSTALL === "1";
9
+ const skipInstall = process.env.CONTEXT_GUARD_SKIP_AUTO_INSTALL === "1";
10
+
11
+ if (skipInstall) {
12
+ process.exit(0);
13
+ }
14
+
15
+ if (!isGlobalInstall && !autoInstall) {
16
+ console.log("[context-guard-skill] package installed. Run `npx @michelj/context-guard install` to install the Codex skill.");
17
+ process.exit(0);
18
+ }
19
+
20
+ const cli = path.join(__dirname, "context-guard-skill.js");
21
+ const result = spawnSync(process.execPath, [cli, "install"], { stdio: "inherit" });
22
+
23
+ if (result.error) {
24
+ console.warn(`[context-guard-skill] auto install skipped: ${result.error.message}`);
25
+ process.exit(0);
26
+ }
27
+
28
+ process.exit(result.status === null ? 0 : result.status);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@michelj/context-guard",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "Install and run the Context Guard Codex skill.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -22,6 +22,7 @@
22
22
  "skills/context-guard/"
23
23
  ],
24
24
  "scripts": {
25
+ "postinstall": "node bin/postinstall.js",
25
26
  "test": "bash tests/npm-install-smoke.sh && python3 -m py_compile skills/context-guard/scripts/context_guard.py skills/context-guard/scripts/context_guard_hook.py"
26
27
  },
27
28
  "engines": {
package/skills/context-guard/README.md CHANGED
@@ -14,6 +14,7 @@ Context Guard is a Codex skill for durable project memory. It keeps the task rou
14
14
  - **Supports record language preferences**: writes future context in Chinese or English.
15
15
  - **Handles task switches**: parks, resumes, and branches interrupted work.
16
16
  - **Keeps tests human-designed**: Codex reuses approved checks or proposes drafts, but does not silently create durable tests.
17
+ - **Covers bad cases with feature chains**: prefer one real feature/workflow chain covering multiple bad cases over one separate test per bad case.
17
18
  - **Runs approved tests by default**: user-created or user-approved tests run at every development completion unless the user sets another cadence.
18
19
  - **Provides a Test Hub entrypoint**: `dev-complete` runs approved always-run tests, cleans success artifacts, and preserves failed evidence.
19
20
 
@@ -22,13 +23,19 @@ Context Guard is a Codex skill for durable project memory. It keeps the task rou
22
23
  Install with npx:
23
24
 
24
25
  ```bash
25
- npx context-guard install
26
+ npx @michelj/context-guard install
27
+ ```
28
+
29
+ Or install globally and let the package copy the skill into Codex's skill directory automatically:
30
+
31
+ ```bash
32
+ npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
26
33
  ```
27
34
 
28
35
  Install hooks only when you explicitly want Context Guard reminders at Codex lifecycle events:
29
36
 
30
37
  ```bash
31
- npx context-guard install --with-hooks
38
+ npx @michelj/context-guard install --with-hooks
32
39
  ```
33
40
 
34
41
  Use from GitHub before the npm package is published:
@@ -42,14 +49,14 @@ Manual install is also supported:
42
49
  ```bash
43
50
  git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
44
51
  cd Context-Guard-Skill
45
- mkdir -p ~/.agents/skills/context-guard
46
- rsync -a --delete skills/context-guard/ ~/.agents/skills/context-guard/
52
+ mkdir -p ~/.codex/skills/context-guard
53
+ rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
47
54
  ```
48
55
 
49
56
  After installation, Codex should discover:
50
57
 
51
58
  ```text
52
- ~/.agents/skills/context-guard/SKILL.md
59
+ ~/.codex/skills/context-guard/SKILL.md
53
60
  ```
54
61
 
55
62
  ## Where Context Lives
@@ -70,39 +77,60 @@ Do not write project context into:
70
77
  When running scripts manually, pass the project root explicitly:
71
78
 
72
79
  ```bash
73
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
80
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
74
81
  ```
75
82
 
76
83
  Register a user-approved automated test:
77
84
 
78
85
  ```bash
79
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-add \
86
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
80
87
  --root /path/to/project \
81
88
  --title "Markdown preview rendering" \
82
89
  --command-text "npm test"
83
90
  ```
84
91
 
92
+ Register a user-approved feature-chain test:
93
+
94
+ ```bash
95
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
96
+ --root /path/to/project \
97
+ --title "GPU monitor button" \
98
+ --entry "Click the GPU monitor button" \
99
+ --exit-check "Open a monitoring page with a valid grafana_url" \
100
+ --command-text "npm test -- gpu-monitor"
101
+ ```
102
+
103
+ Attach a bad case to a specific feature-chain checkpoint:
104
+
105
+ ```bash
106
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
107
+ --root /path/to/project \
108
+ --chain-id FC-... \
109
+ --node-title "Backend returns monitor URL" \
110
+ --bad-case BC-... \
111
+ --check "grafana_url is non-empty and the frontend does not hang"
112
+ ```
113
+
85
114
  After development, hand completion to the Test Hub:
86
115
 
87
116
  ```bash
88
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
117
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
89
118
  ```
90
119
 
91
- Open the Test Hub page; use the localhost console for one-click runs:
120
+ Open the read-only Test Hub page:
92
121
 
93
122
  ```bash
94
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
95
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py serve-test-hub --root /path/to/project --port 8772 --open
123
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
96
124
  ```
97
125
 
98
126
  Manage tests lightly:
99
127
 
100
128
  ```bash
101
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
102
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "not needed every time"
103
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
104
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "only editor changes need it"
105
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
129
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
130
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "not needed every time"
131
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
132
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "only editor changes need it"
133
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
106
134
  ```
107
135
 
108
136
  ## Common Usage
@@ -122,31 +150,31 @@ Use $context-guard to show the roadmap.
122
150
  Initialize project context:
123
151
 
124
152
  ```bash
125
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py init --root /path/to/project
153
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
126
154
  ```
127
155
 
128
156
  Set the record language:
129
157
 
130
158
  ```bash
131
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
159
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
132
160
  ```
133
161
 
134
162
  Generate the roadmap:
135
163
 
136
164
  ```bash
137
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
165
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
138
166
  ```
139
167
 
140
168
  Or use the npm CLI as a thin wrapper:
141
169
 
142
170
  ```bash
143
- npx context-guard show-roadmap --root /path/to/project
171
+ npx @michelj/context-guard show-roadmap --root /path/to/project
144
172
  ```
145
173
 
146
174
  Create a branch task:
147
175
 
148
176
  ```bash
149
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
177
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
150
178
  --root /path/to/project \
151
179
  --title "branch task title" \
152
180
  --branch "branch name" \
@@ -156,7 +184,7 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-ta
156
184
  Record a roadmap checkpoint:
157
185
 
158
186
  ```bash
159
- python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
187
+ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
160
188
  --root /path/to/project \
161
189
  --title "source title for Codex" \
162
190
  --display-title "short human title" \
@@ -192,9 +220,12 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadm
192
220
  - Human-facing titles should read naturally, not like implementation logs.
193
221
  - A bad case should help future Codex prevent recurrence.
194
222
  - Test design belongs to humans; Codex can run approved checks or draft a proposal for confirmation.
223
+ - Prefer feature chains as the durable testing unit: one clear entry, one real workflow, ordered checkpoints, and multiple covered bad cases.
224
+ - Attach new bad cases to an existing feature-chain checkpoint first; propose a new chain only when no existing workflow matches.
195
225
  - User-approved tests default to `every-dev-completion`; Codex may lower that cadence only when the user asks.
196
- - Approved automated tests should go into `.codex/context/test-hub/registry.json` and be scheduled through `dev-complete`.
197
- - Keep the Test Hub simple: one registry, one `dev-complete` runner, one latest-result file, one lightweight HTML control panel, and a few management commands.
226
+ - Approved automated tests should go into `.codex/context/test-hub/registry.json` or `.codex/context/test-hub/feature-chains.json` and be scheduled through `dev-complete`.
227
+ - Keep the Test Hub simple: one registry, one `dev-complete` runner, one latest-result file, one read-only HTML status page, and a few management commands.
228
+ - Final Codex summaries should state the current Test Hub result: whether approved always-run tests all passed, failed, blocked, or do not exist.
198
229
  - Verification should reuse existing commands, scripts, screenshots, or manual checks first.
199
230
  - Do not create a new script for every bad case.
200
231
  - For frontend or HTML changes, inspect the rendered page or screenshot before claiming success.