@michelj/context-guard 0.4.0

package/README.md

@@ -0,0 +1,203 @@
+# Context Guard Skill
+
+Language: **English** | [中文](README.zh-CN.md)
+
+Context Guard is a Codex skill for durable project memory. It keeps the task route, branches, bad cases, and verification paths inside the project's own `.codex/context/` folder, so Codex can understand where the work is, what went wrong before, and how to avoid repeating fixed mistakes across sessions.
+
+## What It Does
+
+- **Maintains project context**: creates and updates `.codex/context/`.
+- **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.
+- **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.
+- **Keeps tests human-designed**: Codex reuses approved checks or proposes drafts, but does not silently create durable tests.
+- **Runs approved tests by default**: user-created or user-approved tests run at every development completion unless the user sets another cadence.
+- **Provides a Test Hub entrypoint**: `dev-complete` runs approved always-run tests, cleans success artifacts, and preserves failed evidence.
+
+## Install
+
+Install with npx:
+
+```bash
+npx context-guard install
+```
+
+Install hooks only when you explicitly want Context Guard reminders at Codex lifecycle events:
+
+```bash
+npx context-guard install --with-hooks
+```
+
+Use from GitHub before the npm package is published:
+
+```bash
+npx github:Michel-Johnson/Context-Guard-Skill install
+```
+
+Manual install is also supported:
+
+```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/
+```
+
+After installation, Codex should discover:
+
+```text
+~/.agents/skills/context-guard/SKILL.md
+```
+
+## Where Context Lives
+
+Context must be saved under the local project currently opened in Codex:
+
+```text
+<Codex project root>/.codex/context/
+```
+
+Do not write project context into:
+
+- the skill install directory
+- a chat/thread directory
+- a temporary directory
+- an SSH remote server path
+
+When running scripts manually, pass the project root explicitly:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+```
+
+Register a user-approved automated test:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-add \
+  --root /path/to/project \
+  --title "Markdown preview rendering" \
+  --command-text "npm test"
+```
+
+After development, hand completion to the Test Hub:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
+```
+
+Open the Test Hub page; use the localhost console for one-click runs:
+
+```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
+```
+
+Manage tests lightly:
+
+```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 "not needed every time"
+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 "only editor changes need it"
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
+```
+
+## Common Usage
+
+Ask Codex to maintain context:
+
+```text
+Use $context-guard to maintain this task context.
+```
+
+Show the current roadmap:
+
+```text
+Use $context-guard to show the roadmap.
+```
+
+Initialize project context:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py init --root /path/to/project
+```
+
+Set the record language:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
+```
+
+Generate the roadmap:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+```
+
+Or use the npm CLI as a thin wrapper:
+
+```bash
+npx context-guard show-roadmap --root /path/to/project
+```
+
+Create a branch task:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
+  --root /path/to/project \
+  --title "branch task title" \
+  --branch "branch name" \
+  --parent-node NODE-YYYYMMDD-001
+```
+
+Record a roadmap checkpoint:
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
+  --root /path/to/project \
+  --title "source title for Codex" \
+  --display-title "short human title" \
+  --user-request "what the user asked" \
+  --progress-summary "current progress" \
+  --method-summary "method used" \
+  --branch Main \
+  --level major \
+  --outcome "result"
+```
+
+## Main Files
+
+```text
+.codex/context/
+|-- index.md              # quick index and active task
+|-- roadmap.md            # agent-readable roadmap
+|-- bad-cases.md          # bad-case register
+|-- preferences.json      # language and project preferences
+|-- roadmap/
+|   |-- roadmap.html      # human-facing roadmap
+|   |-- roadmap.md        # agent-readable export
+|   `-- roadmap.json      # structured index
+|-- tasks/                # task-level context
+|-- task-cases/           # task-oriented test cases
+|-- test-hub/             # test registry, latest result, and failed evidence
+`-- bad-case-tests/       # reusable bad-case checks
+```
+
+## Principles
+
+- Record only meaningful progress, not every small action.
+- 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.
+- 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` and be scheduled through `dev-complete`.
+- 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.
+- Verification should reuse existing commands, scripts, screenshots, or manual checks first.
+- Do not create a new script for every bad case.
+- 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.

package/README.zh-CN.md

@@ -0,0 +1,203 @@
+# Context Guard Skill
+
+语言：[English](README.md) | **中文**
+
+Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线、支线、bad case 和验证链路保存在项目自己的 `.codex/context/` 里，让 Codex 在不同 session 之间也能知道“现在做到哪里、踩过哪些坑、下次怎么检查”。
+
+## 能做什么
+
+- **维护项目 context**：自动创建并更新 `.codex/context/`。
+- **记录路线图**：维护主线、支线、分叉节点和当前进度。
+- **记录 bad case**：保存问题现象、触发条件、原因、修复方式和防复发检查。
+- **生成 Roadmap HTML**：给用户查看清晰的路线图，点击节点看详情。
+- **区分人类视图和 agent 视图**：HTML 给人看，Markdown/JSON 给 Codex 读取。
+- **支持多语言记录**：按项目偏好用中文或英文写 context。
+- **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
+- **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
+- **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
+- **提供测试中台入口**：`dev-complete` 会统一运行已确认的 always-run 测试，成功清理临时产物，失败保留证据。
+
+## 安装
+
+使用 npx 安装：
+
+```bash
+npx context-guard install
+```
+
+只有当你明确希望安装 Codex 生命周期 hook 提醒时，才加 `--with-hooks`：
+
+```bash
+npx context-guard install --with-hooks
+```
+
+npm 包正式发布前，也可以直接从 GitHub 使用：
+
+```bash
+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/
+```
+
+安装后 Codex 应该能发现：
+
+```text
+~/.agents/skills/context-guard/SKILL.md
+```
+
+## Context 保存在哪里
+
+Context 必须保存在当前打开的本地项目里：
+
+```text
+<Codex 打开的项目根目录>/.codex/context/
+```
+
+不要把 context 写到：
+
+- skill 安装目录
+- chat/thread 名称对应的目录
+- 临时目录
+- SSH 远程服务器路径
+
+如果手动运行脚本，建议显式传入项目根目录：
+
+```bash
+python3 ~/.agents/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 \
+  --root /path/to/project \
+  --title "Markdown 预览渲染" \
+  --command-text "npm test"
+```
+
+开发完成后交给测试中台：
+
+```bash
+python3 ~/.agents/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
+```
+
+简单管理测试：
+
+```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-...
+```
+
+## 常用方式
+
+让 Codex 启用并维护 context：
+
+```text
+Use $context-guard to maintain this task context.
+```
+
+展示当前路线图：
+
+```text
+Use $context-guard to show the roadmap.
+```
+
+初始化项目 context：
+
+```bash
+python3 ~/.agents/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 中文
+```
+
+生成路线图：
+
+```bash
+python3 ~/.agents/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
+```
+
+创建支线任务：
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py create-branch-task \
+  --root /path/to/project \
+  --title "支线任务标题" \
+  --branch "支线名称" \
+  --parent-node NODE-YYYYMMDD-001
+```
+
+记录路线图节点：
+
+```bash
+python3 ~/.agents/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
+  --root /path/to/project \
+  --title "给 Codex 看的源标题" \
+  --display-title "给用户看的短标题" \
+  --user-request "用户实际提出的问题" \
+  --progress-summary "当前进展" \
+  --method-summary "采取的方法" \
+  --branch Main \
+  --level major \
+  --outcome "结果"
+```
+
+## 主要文件
+
+```text
+.codex/context/
+|-- index.md              # 快速索引和当前任务
+|-- roadmap.md            # agent 可读路线图
+|-- bad-cases.md          # bad case 登记表
+|-- preferences.json      # 语言和项目偏好
+|-- roadmap/
+|   |-- roadmap.html      # 用户查看的路线图
+|   |-- roadmap.md        # agent 快速读取版
+|   `-- roadmap.json      # 结构化索引
+|-- tasks/                # 任务级 context
+|-- task-cases/           # 任务导向测试 case
+|-- test-hub/             # 测试注册表、最近结果和失败证据
+`-- bad-case-tests/       # 可复用 bad case 检查脚本
+```
+
+## 使用原则
+
+- 路线图只记录关键进展，不记录每个小动作。
+- 用户看的标题要像人话，不要像实现日志。
+- bad case 要能帮助未来避免复发。
+- 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
+- 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
+- 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json`，由 `dev-complete` 统一调度。
+- 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个轻量 HTML 控制台和几个管理命令。
+- 测试链路优先复用已有命令、脚本、截图或人工检查。
+- 不要为了每个 bad case 都新写脚本。
+- 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。
+- 任何新的长期测试 case 都先写简短草案，让用户确认后再变成 active 测试。
+
+详细行为规则见 [`skills/context-guard/SKILL.md`](skills/context-guard/SKILL.md)。

package/bin/context-guard-skill.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const sourceSkillDir = path.join(packageRoot, "skills", "context-guard");
+const sourceHooksPath = path.join(packageRoot, "hooks.json");
+const pythonScript = path.join(sourceSkillDir, "scripts", "context_guard.py");
+
+function usage() {
+  console.log(`Context Guard Skill
+
+Usage:
+  context-guard install [--target <dir>] [--with-hooks] [--hooks-target <file>]
+  context-guard path
+  context-guard <context_guard.py command> [args...]
+
+Examples:
+  npx context-guard install
+  npx context-guard install --with-hooks
+  npx context-guard show-roadmap --root /path/to/project
+`);
+}
+
+function fail(message) {
+  console.error(`[context-guard-skill] ${message}`);
+  process.exit(1);
+}
+
+function expandHome(inputPath) {
+  if (!inputPath) return inputPath;
+  if (inputPath === "~") return os.homedir();
+  if (inputPath.startsWith("~/")) return path.join(os.homedir(), inputPath.slice(2));
+  return inputPath;
+}
+
+function defaultSkillTarget() {
+  if (process.env.CONTEXT_GUARD_SKILL_TARGET) {
+    return path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET));
+  }
+  const agentsHome = process.env.AGENTS_HOME || path.join(os.homedir(), ".agents");
+  return path.join(agentsHome, "skills", "context-guard");
+}
+
+function defaultHooksTarget() {
+  if (process.env.CONTEXT_GUARD_HOOKS_TARGET) {
+    return path.resolve(expandHome(process.env.CONTEXT_GUARD_HOOKS_TARGET));
+  }
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "hooks.json");
+}
+
+function parseInstallArgs(args) {
+  const options = {
+    target: defaultSkillTarget(),
+    withHooks: false,
+    hooksTarget: defaultHooksTarget(),
+    dryRun: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--target") {
+      const value = args[++i];
+      if (!value) fail("--target requires a directory");
+      options.target = path.resolve(expandHome(value));
+    } else if (arg === "--with-hooks" || arg === "--hooks") {
+      options.withHooks = true;
+    } else if (arg === "--hooks-target") {
+      const value = args[++i];
+      if (!value) fail("--hooks-target requires a file path");
+      options.hooksTarget = path.resolve(expandHome(value));
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "-h" || arg === "--help") {
+      usage();
+      process.exit(0);
+    } else {
+      fail(`unknown install option: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function copySkill(target, dryRun) {
+  if (!fs.existsSync(path.join(sourceSkillDir, "SKILL.md"))) {
+    fail(`source skill folder is missing: ${sourceSkillDir}`);
+  }
+  if (dryRun) {
+    console.log(`[context-guard-skill] would install skill to ${target}`);
+    return;
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.cpSync(sourceSkillDir, target, { recursive: true });
+  console.log(`[context-guard-skill] installed skill: ${target}`);
+}
+
+function rewriteHookCommands(hooksConfig, skillTarget) {
+  const hookScript = path.join(skillTarget, "scripts", "context_guard_hook.py");
+  const encodedHookScript = JSON.stringify(hookScript);
+  const next = JSON.parse(JSON.stringify(hooksConfig));
+  for (const groups of Object.values(next.hooks || {})) {
+    for (const group of groups || []) {
+      for (const hook of group.hooks || []) {
+        if (hook.type === "command" && typeof hook.command === "string" && hook.command.includes("context_guard_hook.py")) {
+          hook.command = `python3 ${encodedHookScript} ${hook.command.split(" ").pop()}`;
+        }
+      }
+    }
+  }
+  return next;
+}
+
+function mergeHooks(existing, incoming) {
+  const merged = existing && typeof existing === "object" ? existing : {};
+  merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
+  for (const [event, groups] of Object.entries(incoming.hooks || {})) {
+    const current = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    const withoutOldContextGuard = current.filter((group) => {
+      const hooks = Array.isArray(group && group.hooks) ? group.hooks : [];
+      return !hooks.some((hook) => String(hook.command || "").includes("context_guard_hook.py"));
+    });
+    merged.hooks[event] = withoutOldContextGuard.concat(groups);
+  }
+  return merged;
+}
+
+function installHooks(skillTarget, hooksTarget, dryRun) {
+  if (!fs.existsSync(sourceHooksPath)) {
+    fail(`source hooks file is missing: ${sourceHooksPath}`);
+  }
+  const rawIncoming = JSON.parse(fs.readFileSync(sourceHooksPath, "utf8"));
+  const incoming = rewriteHookCommands(rawIncoming, skillTarget);
+  let existing = {};
+  if (fs.existsSync(hooksTarget)) {
+    existing = JSON.parse(fs.readFileSync(hooksTarget, "utf8"));
+  }
+  const merged = mergeHooks(existing, incoming);
+  if (dryRun) {
+    console.log(`[context-guard-skill] would install hooks to ${hooksTarget}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(hooksTarget), { recursive: true });
+  if (fs.existsSync(hooksTarget)) {
+    const backupPath = `${hooksTarget}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    fs.copyFileSync(hooksTarget, backupPath);
+    console.log(`[context-guard-skill] backed up hooks: ${backupPath}`);
+  }
+  fs.writeFileSync(hooksTarget, `${JSON.stringify(merged, null, 2)}\n`);
+  console.log(`[context-guard-skill] installed hooks: ${hooksTarget}`);
+}
+
+function install(args) {
+  const options = parseInstallArgs(args);
+  copySkill(options.target, options.dryRun);
+  if (options.withHooks) {
+    installHooks(options.target, options.hooksTarget, options.dryRun);
+  }
+}
+
+function runPython(args) {
+  if (!fs.existsSync(pythonScript)) {
+    fail(`context_guard.py is missing: ${pythonScript}`);
+  }
+  const result = spawnSync("python3", [pythonScript, ...args], { stdio: "inherit" });
+  if (result.error) fail(result.error.message);
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === "-h" || command === "--help" || command === "help") {
+  usage();
+} else if (command === "install") {
+  install(rest);
+} else if (command === "path") {
+  console.log(sourceSkillDir);
+} else {
+  runPython([command, ...rest]);
+}

package/hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py session-start",
+            "timeout": 10,
+            "statusMessage": "Initializing context folder"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py user-prompt-submit",
+            "timeout": 10,
+            "statusMessage": "Checking context intake"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py stop",
+            "timeout": 10,
+            "statusMessage": "Checking context checkpoint"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@michelj/context-guard",
+  "version": "0.4.0",
+  "description": "Install and run the Context Guard Codex skill.",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Michel-Johnson/Context-Guard-Skill.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "context-guard-skill": "bin/context-guard-skill.js",
+    "context-guard": "bin/context-guard-skill.js"
+  },
+  "files": [
+    "README.md",
+    "README.zh-CN.md",
+    "hooks.json",
+    "bin/",
+    "skills/context-guard/"
+  ],
+  "scripts": {
+    "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"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}