@michelj/context-guard 0.4.1 → 0.4.3

package/README.md

@@ -7,12 +7,16 @@ Context Guard is a Codex skill for durable project memory. It keeps the task rou
 ## What It Does
 
 - **Maintains project context**: creates and updates `.codex/context/`.
+- **Preserves user wording**: stores short user instructions, constraints, preferences, route hints, and bad-case reports in `user-messages.md`.
+- **Keeps secrets local-only**: redacts credentials from public context and stores durable secrets only under `.codex/context/private/`.
 - **Records the roadmap**: tracks main routes, side routes, branch points, and progress.
 - **Tracks bad cases**: records symptoms, triggers, causes, fixes, and recurrence checks.
-- **Generates Roadmap HTML**: shows a human-readable roadmap with clickable node details.
+- **Generates Roadmap HTML**: shows clickable node details with card and compact high-density views.
 - **Separates human and agent views**: HTML is for humans; Markdown/JSON are for Codex.
 - **Supports record language preferences**: writes future context in Chinese or English.
 - **Handles task switches**: parks, resumes, and branches interrupted work.
+- **Binds subagent projects**: maps each agent ID to its real local project root so context does not leak into a parent workspace or SSH server.
+- **Archives concrete repairs**: keeps observed symptoms, causes, fixes, and verification while deduplicating repeated completion events.
 - **Keeps tests human-designed**: Codex reuses approved checks or proposes drafts, but does not silently create durable tests.
 - **Covers bad cases with feature chains**: prefer one real feature/workflow chain covering multiple bad cases over one separate test per bad case.
 - **Runs approved tests by default**: user-created or user-approved tests run at every development completion unless the user sets another cadence.
@@ -38,6 +42,8 @@ Install hooks only when you explicitly want Context Guard reminders at Codex lif
 npx @michelj/context-guard install --with-hooks
 ```
 
+This also enables the current `[features] hooks = true` setting in `~/.codex/config.toml` and migrates the deprecated `codex_hooks` alias without changing other settings.
+
 Use from GitHub before the npm package is published:
 
 ```bash
@@ -50,7 +56,9 @@ Manual install is also supported:
 git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
 cd Context-Guard-Skill
 mkdir -p ~/.codex/skills/context-guard
-rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
+rsync -a --delete \
+  SKILL.md README.md README.zh-CN.md agents references scripts tests \
+  ~/.codex/skills/context-guard/
 ```
 
 After installation, Codex should discover:
@@ -74,6 +82,18 @@ Do not write project context into:
 - a temporary directory
 - an SSH remote server path
 
+Short user prompts that matter for future work are kept in:
+
+```text
+<Codex project root>/.codex/context/user-messages.md
+```
+
+If the user provides a credential that future Codex turns need, Context Guard records only a redacted pointer in public context. Raw durable secrets must stay local-only under:
+
+```text
+<Codex project root>/.codex/context/private/
+```
+
 When running scripts manually, pass the project root explicitly:
 
 ```bash
@@ -89,15 +109,14 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
   --command-text "npm test"
 ```
 
-Register a user-approved feature-chain test:
+Create a proposed feature-chain test:
 
 ```bash
 python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
   --root /path/to/project \
   --title "GPU monitor button" \
   --entry "Click the GPU monitor button" \
-  --exit-check "Open a monitoring page with a valid grafana_url" \
-  --command-text "npm test -- gpu-monitor"
+  --exit-check "Open a monitoring page with a valid grafana_url"
 ```
 
 Attach a bad case to a specific feature-chain checkpoint:
@@ -111,6 +130,53 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-att
   --check "grafana_url is non-empty and the frontend does not hang"
 ```
 
+After the user confirms the flow, approve that same chain:
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-approve \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --command-text "npm test -- gpu-monitor"
+```
+
+Feature-chain commands can emit checkpoint markers so the Test Hub can report the exact failed step:
+
+```text
+CG_CHECKPOINT:Backend returns monitor URL:PASS
+CG_CHECKPOINT:Frontend opens monitor page:FAIL:missing grafana_url
+```
+
+The checkpoint name in each marker must match a registered feature-chain node. Unknown names are treated as test-chain errors. Approved feature-chain commands must report every registered checkpoint unless the checkpoint is explicitly optional.
+
+If a checkpoint should not run every time, mark that checkpoint as optional explicitly:
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-checkpoint \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --node-title "Frontend opens monitor page" \
+  --required optional \
+  --reason "Only runs in browser integration environment"
+```
+
+Audit which checkpoints are required or optional:
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-list \
+  --root /path/to/project \
+  --verbose
+```
+
+If the user says this chain should not run every time, change its cadence:
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-policy \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --run-policy relevant-only \
+  --reason "Only run when GPU monitor flow changes"
+```
+
 After development, hand completion to the Test Hub:
 
 ```bash
@@ -220,8 +286,10 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadma
 - Human-facing titles should read naturally, not like implementation logs.
 - A bad case should help future Codex prevent recurrence.
 - Test design belongs to humans; Codex can run approved checks or draft a proposal for confirmation.
+- When a task is likely to recur or fits a reusable workflow check, Codex should gently ask whether the user wants to create a test task, but must not create durable tests silently.
 - Prefer feature chains as the durable testing unit: one clear entry, one real workflow, ordered checkpoints, and multiple covered bad cases.
 - Attach new bad cases to an existing feature-chain checkpoint first; propose a new chain only when no existing workflow matches.
+- Feature chains start as `proposed`; promote them with `feature-chain-approve` only after user confirmation and checkpoint coverage.
 - User-approved tests default to `every-dev-completion`; Codex may lower that cadence only when the user asks.
 - 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`.
 - 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.
@@ -231,4 +299,4 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadma
 - For frontend or HTML changes, inspect the rendered page or screenshot before claiming success.
 - For any new durable test case, draft a short task-case proposal and confirm with the user before making it active.
 
-See [`skills/context-guard/SKILL.md`](skills/context-guard/SKILL.md) for the full behavior rules.
+See [`SKILL.md`](SKILL.md) for the full behavior rules.

package/README.zh-CN.md

@@ -7,12 +7,16 @@ Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线
 ## 能做什么
 
 - **维护项目 context**：自动创建并更新 `.codex/context/`。
+- **保留用户原话**：把短用户指令、约束、偏好、路线提示和 bad case 反馈写入 `user-messages.md`。
+- **敏感信息只留本地**：公开 context 里只保留脱敏指针，真正需要复用的凭据只放在 `.codex/context/private/`。
 - **记录路线图**：维护主线、支线、分叉节点和当前进度。
 - **记录 bad case**：保存问题现象、触发条件、原因、修复方式和防复发检查。
-- **生成 Roadmap HTML**：给用户查看清晰的路线图，点击节点看详情。
+- **生成 Roadmap HTML**：支持卡片和高密度紧凑总览，点击节点看详情。
 - **区分人类视图和 agent 视图**：HTML 给人看，Markdown/JSON 给 Codex 读取。
 - **支持多语言记录**：按项目偏好用中文或英文写 context。
 - **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
+- **绑定 Subagent 项目**：把 agent ID 绑定到实际本地项目根目录，避免 context 写回父工作区或 SSH 服务器。
+- **沉淀真实修复**：优先保存 Subagent 实际发现的问题、根因、修复和验证；重复完成事件不会重复建节点。
 - **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
 - **用功能链覆盖 bad case**：优先把多个 bad case 挂到同一条真实功能/工作流测试链上，而不是为每个 bad case 单独造测试。
 - **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
@@ -38,6 +42,8 @@ npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
 npx @michelj/context-guard install --with-hooks
 ```
 
+该命令也会在 `~/.codex/config.toml` 中启用当前的 `[features] hooks = true`，并把已弃用的 `codex_hooks` 别名安全迁移，同时保留其他配置。
+
 npm 包正式发布前，也可以直接从 GitHub 使用：
 
 ```bash
@@ -50,7 +56,9 @@ npx github:Michel-Johnson/Context-Guard-Skill install
 git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
 cd Context-Guard-Skill
 mkdir -p ~/.codex/skills/context-guard
-rsync -a --delete skills/context-guard/ ~/.codex/skills/context-guard/
+rsync -a --delete \
+  SKILL.md README.md README.zh-CN.md agents references scripts tests \
+  ~/.codex/skills/context-guard/
 ```
 
 安装后 Codex 应该能发现：
@@ -74,6 +82,18 @@ Context 必须保存在当前打开的本地项目里：
 - 临时目录
 - SSH 远程服务器路径
 
+对后续工作有价值的短用户消息会保存在：
+
+```text
+<Codex 打开的项目根目录>/.codex/context/user-messages.md
+```
+
+如果用户提供了后续需要复用的凭据，Context Guard 只会在公开 context 中记录脱敏指针。原始凭据必须只保存在本地私有目录：
+
+```text
+<Codex 打开的项目根目录>/.codex/context/private/
+```
+
 如果手动运行脚本，建议显式传入项目根目录：
 
 ```bash
@@ -89,15 +109,14 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
   --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"
+  --exit-check "打开包含有效 grafana_url 的监控页"
 ```
 
 把 bad case 挂到功能链的具体环节：
@@ -111,6 +130,53 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-att
   --check "grafana_url 不为空，前端不会卡住"
 ```
 
+用户确认流程后，再批准同一条功能链：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-approve \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --command-text "npm test -- gpu-monitor"
+```
+
+功能链命令可以输出 checkpoint 标记，让测试中台知道具体哪一步失败：
+
+```text
+CG_CHECKPOINT:后端返回监控 URL:PASS
+CG_CHECKPOINT:前端打开监控页:FAIL:缺少 grafana_url
+```
+
+标记里的 checkpoint 名称必须匹配已登记的功能链节点；未知名称会被当成测试链路错误。已批准的功能链默认必须报告每个已登记 checkpoint，除非该 checkpoint 被明确标为 optional。
+
+如果某个 checkpoint 不适合每次都跑，显式标为 optional：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-checkpoint \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --node-title "前端打开监控页" \
+  --required optional \
+  --reason "只在浏览器集成环境运行"
+```
+
+查看每条功能链哪些 checkpoint 必跑、哪些可选：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-list \
+  --root /path/to/project \
+  --verbose
+```
+
+如果用户说这条链不需要每次都跑，修改运行频率：
+
+```bash
+python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-policy \
+  --root /path/to/project \
+  --chain-id FC-... \
+  --run-policy relevant-only \
+  --reason "只在修改 GPU 监控流程时运行"
+```
+
 开发完成后交给测试中台：
 
 ```bash
@@ -220,8 +286,10 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadma
 - 用户看的标题要像人话，不要像实现日志。
 - bad case 要能帮助未来避免复发。
 - 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
+- 当任务容易复发或适合沉淀为流程检查时，Codex 应温和提醒用户是否创建测试任务，但不能擅自创建长期测试。
 - 测试的长期单位优先是功能链：一个明确入口、一段真实流程、多个检查点、覆盖多个 bad case。
 - 新 bad case 优先挂到已有功能链节点；没有匹配功能链时，再提出新的功能链草案。
+- 功能链默认是 `proposed` 草案；用户确认后，用 `feature-chain-approve` 在检查覆盖完整时再批准。
 - 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
 - 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json` 或 `.codex/context/test-hub/feature-chains.json`，由 `dev-complete` 统一调度。
 - 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个只读 HTML 状态页和几个管理命令。
@@ -231,4 +299,4 @@ python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadma
 - 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。
 - 任何新的长期测试 case 都先写简短草案，让用户确认后再变成 active 测试。
 
-详细行为规则见 [`skills/context-guard/SKILL.md`](skills/context-guard/SKILL.md)。
+详细行为规则见 [`SKILL.md`](SKILL.md)。