@michelj/context-guard 0.4.0 → 0.4.2

package/skills/context-guard/README.zh-CN.md

@@ -14,6 +14,7 @@ Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线
 - **支持多语言记录**：按项目偏好用中文或英文写 context。
 - **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
 - **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
+- **用功能链覆盖 bad case**：优先把多个 bad case 挂到同一条真实功能/工作流测试链上，而不是为每个 bad case 单独造测试。
 - **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
 - **提供测试中台入口**：`dev-complete` 会统一运行已确认的 always-run 测试，成功清理临时产物，失败保留证据。
 
@@ -22,13 +23,19 @@ Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线
 使用 npx 安装：
 
 ```bash
-npx context-guard install
+npx @michelj/context-guard install
+```
+
+也可以全局安装，让 npm 包自动把 skill 复制到 Codex 的 skill 目录：
+
+```bash
+npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
 ```
 
 只有当你明确希望安装 Codex 生命周期 hook 提醒时，才加 `--with-hooks`：
 
 ```bash
-npx context-guard install --with-hooks
+npx @michelj/context-guard install --with-hooks
 ```
 
 npm 包正式发布前，也可以直接从 GitHub 使用：
@@ -42,14 +49,14 @@ npx github:Michel-Johnson/Context-Guard-Skill install
 ```bash
 git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
 cd Context-Guard-Skill
-mkdir -p ~/.agents/skills/context-guard
-rsync -a --delete skills/context-guard/ ~/.agents/skills/context-guard/
+mkdir -p ~/.codex/skills/context-guard
+rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
 ```
 
 安装后 Codex 应该能发现：
 
 ```text
-~/.agents/skills/context-guard/SKILL.md
+~/.codex/skills/context-guard/SKILL.md
 ```
 
 ## Context 保存在哪里
@@ -70,39 +77,60 @@ Context 必须保存在当前打开的本地项目里：
 如果手动运行脚本，建议显式传入项目根目录：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
 ```
 
 注册一个用户已确认的自动化测试：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-add \
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
   --root /path/to/project \
   --title "Markdown 预览渲染" \
   --command-text "npm test"
 ```
 
+注册一条用户已确认的功能链测试：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
+  --root /path/to/project \
+  --title "GPU 监控按钮" \
+  --entry "点击 GPU 监控按钮" \
+  --exit-check "打开包含有效 grafana_url 的监控页" \
+  --command-text "npm test -- gpu-monitor"
+```
+
+把 bad case 挂到功能链的具体环节：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --node-title "后端返回监控 URL" \
+  --bad-case BC-... \
+  --check "grafana_url 不为空，前端不会卡住"
+```
+
 开发完成后交给测试中台：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
 ```
 
-查看测试中台页面；需要一键运行时启动 localhost 控制台：
+查看只读测试中台页面：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py serve-test-hub --root /path/to/project --port 8772 --open
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
 ```
 
 简单管理测试：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
-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 "只和编辑器改动相关"
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
+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 "只和编辑器改动相关"
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
 ```
 
 ## 常用方式
@@ -122,31 +150,31 @@ Use $context-guard to show the roadmap.
 初始化项目 context：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py init --root /path/to/project
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
 ```
 
 设置记录语言：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
 ```
 
 生成路线图：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
 ```
 
 也可以用 npm CLI 作为轻量封装：
 
 ```bash
-npx context-guard show-roadmap --root /path/to/project
+npx @michelj/context-guard show-roadmap --root /path/to/project
 ```
 
 创建支线任务：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
   --root /path/to/project \
   --title "支线任务标题" \
   --branch "支线名称" \
@@ -156,7 +184,7 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-ta
 记录路线图节点：
 
 ```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
   --root /path/to/project \
   --title "给 Codex 看的源标题" \
   --display-title "给用户看的短标题" \
@@ -192,9 +220,12 @@ python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadm
 - 用户看的标题要像人话，不要像实现日志。
 - bad case 要能帮助未来避免复发。
 - 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
+- 测试的长期单位优先是功能链：一个明确入口、一段真实流程、多个检查点、覆盖多个 bad case。
+- 新 bad case 优先挂到已有功能链节点；没有匹配功能链时，再提出新的功能链草案。
 - 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
-- 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json`，由 `dev-complete` 统一调度。
-- 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个轻量 HTML 控制台和几个管理命令。
+- 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json` 或 `.codex/context/test-hub/feature-chains.json`，由 `dev-complete` 统一调度。
+- 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个只读 HTML 状态页和几个管理命令。
+- Codex 最终总结必须说明当前测试中台结果：已确认的 always-run 测试是否全部通过、失败、阻塞，或当前没有这类测试。
 - 测试链路优先复用已有命令、脚本、截图或人工检查。
 - 不要为了每个 bad case 都新写脚本。
 - 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。

package/skills/context-guard/SKILL.md

@@ -275,6 +275,44 @@ Preferred bad-case source format is one `### BC-YYYYMMDD-001: Title` section per
 
 Recording and display must stay connected. Every bad case that should appear on a roadmap must have either `Roadmap nodes:` / `Nodes:` pointing to one or more `NODE-...` IDs, or the roadmap node must list that case under `Linked bad cases:`. Do not rely on task-level proximity alone.
 
+### Feature-Oriented Test Chains
+
+Use as few durable test chains as possible to cover as many bad-case recurrence checks as possible. The durable testing unit is a feature or workflow chain, not an individual bad case.
+
+A feature chain has:
+
+- a clear input or entry point, such as clicking a button, submitting a task, opening a page, or starting a workflow
+- ordered checkpoints that match the real user/business flow
+- strict red and green conditions for the final result and any critical intermediate step
+- linked bad cases attached to the specific checkpoint where they can recur
+
+When a new bad case appears:
+
+1. First ask whether it belongs to an existing feature chain.
+2. If it does, attach the bad case to the matching chain node and strengthen that node's checkpoint instead of creating a separate long-lived test.
+3. If no existing chain matches the feature or workflow, propose a new feature chain with the same short human-facing confirmation style as task cases.
+4. Only approve or automate the chain after user confirmation, unless the user explicitly provided the exact test to implement.
+
+Store feature chains in `.codex/context/test-hub/feature-chains.json`. Use:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-add \
+  --root <project> \
+  --title "GPU 监控按钮" \
+  --entry "点击 GPU 监控按钮" \
+  --exit-check "打开包含有效 grafana_url 的监控页" \
+  --command-text "<approved command>"
+
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
+  --root <project> \
+  --chain-id FC-YYYYMMDD-001 \
+  --node-title "后端返回监控 URL" \
+  --bad-case BC-YYYYMMDD-001 \
+  --check "grafana_url 不为空且前端没有卡住"
+```
+
+Approved feature chains with `Run policy: every-dev-completion` are included in `dev-complete` and the Stop hook. Relevant-only or proposed chains remain context until the user approves or asks to run them.
+
 ### Task-Oriented Test Cases
 
 When verification would otherwise become many tiny bug-specific tests, prefer a task-oriented case that simulates a real workflow end to end. A task case is a scenario with phases, checkpoints, logs, and linked bad-case coverage.
@@ -372,10 +410,10 @@ Use the Test Hub as the automation control plane for approved tests. The hub col
 - Register only user-created or user-approved tests. Do not auto-promote ordinary bad-case guards, roadmap `Test chain:` notes, or Codex implementation logs into the registry.
 - A registry entry with `status: approved | active | stable` and `run_policy: every-dev-completion` is part of the always-run set.
 - Manage registry tests with `test-hub-list`, `test-hub-enable`, `test-hub-disable`, `test-hub-set-policy`, and `test-hub-remove`.
-- Use `show-test-hub` to write the stable human-facing page at `.codex/context/test-hub/test-hub.html`.
-- Use `serve-test-hub` when the user wants a clickable local control panel. The static `file://` page is read-only; one-click test execution is only enabled from the localhost server.
+- Use `show-test-hub` to write the stable read-only human-facing page at `.codex/context/test-hub/test-hub.html`.
+- The Test Hub HTML is a status page only. Do not make users start tests from HTML buttons; approved tests run from the Stop hook or `dev-complete`.
 - Task cases in `.codex/context/task-cases/` may also join the always-run set only when they are `approved | active | stable`, have `Run policy: every-dev-completion`, and include an automated entry command.
-- At development completion, prefer `scripts/context_guard.py dev-complete --root <project>` over hand-running registered tests one by one. Use `--jobs <n>` only when parallel execution is safe for the registered tests.
+- At development completion, the Stop hook should invoke `scripts/context_guard.py dev-complete --root <project>` so registered tests run automatically. If running manually, use `dev-complete` over hand-running tests one by one. Use `--jobs <n>` only when parallel execution is safe for the registered tests.
 - `dev-complete` must report passed, failed, and blocked tests. On full success it should clean the run artifacts; on failure or blocker it should preserve evidence under `.codex/context/test-hub/runs/`.
 - If the user says a test should not run every time, update the registry or task case run policy instead of silently skipping it.
 - If no approved every-dev-completion tests exist, the hub should report that clearly and exit successfully; Codex should not invent tests to fill the gap.
@@ -511,6 +549,7 @@ At the end of every response, include a compact context summary when development
 - Bad-case intake result from this turn.
 - BC archived/updated this turn. If none were changed, say `none`.
 - Current unresolved BC. Use concise human-readable bad-case titles and, when useful, one symptom phrase plus status; do not report only `BC-...` IDs. If none are open/deferred/recurred/unknown, say `none`.
+- Current Test Hub status. Say whether all currently approved `every-dev-completion` tests passed, failed, blocked, or whether no approved always-run tests exist. Include concise counts such as `3 passed, 0 failed, 0 blocked`.
 - New or updated context, limited to key nodes and bad cases.
 - End-of-work self-check performed, including visual inspection evidence for frontend/layout artifacts or the exact blocker if visual inspection was not possible.
 - Previously resolved cases rechecked, including reused context, tests, commands, scripts, or manual checks.