@michelj/context-guard 0.4.3 → 0.4.4

package/README.md

@@ -2,301 +2,196 @@
 
 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.
+Context Guard is a durable project-memory skill for Codex, Cursor, and Claude. It keeps the task route, branches, bad cases, and verification paths inside the project's own `.codex/context/` folder, so agents 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/`.
-- **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 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.
-- **Provides a Test Hub entrypoint**: `dev-complete` runs approved always-run tests, cleans success artifacts, and preserves failed evidence.
+- **Four stores**: sessions, bugs, tasks, map — in the opened project’s `.codex/context/`
+- **First-use map**: the agent and the human decide the first layer together (several candidate cuts, then lock L1), then L2, then L3. Titles must be instantly readable. Later sessions open that map
+- **Human workbench**: people confirm in `prototype/workbench.html`. Agents read small indexes, not the whole map
+- **User wording**: durable prompts go in `user-messages.md`; secrets stay under `private/`
+- **Record language**: Chinese or English per folder
+- **Lifecycle**: create session records, retain user messages, and persist agent-identified bad cases through one command
 
-## Install
-
-Install with npx:
+v1 does **not** include Roadmap HTML, Test Hub, or feature chains.
 
-```bash
-npx @michelj/context-guard install
-```
+## Human workbench
 
-Or install globally and let the package copy the skill into Codex's skill directory automatically:
+People confirm the architecture map in the workbench. With hooks installed, a new session starts one local workbench instance and opens it in the browser. Agents read the small indexes under `.codex/context/`; they do not drive the canvas.
 
-```bash
-npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
-```
+**Current workbench:** [prototype/workbench.html](https://github.com/Michel-Johnson/Context-Guard-Skill/blob/main/prototype/workbench.html) · [open in browser](https://raw.githack.com/Michel-Johnson/Context-Guard-Skill/main/prototype/workbench.html)
 
-Install hooks only when you explicitly want Context Guard reminders at Codex lifecycle events:
+The first browser open may show GitHack’s “One more step” page (it is only a proxy and does not review the HTML). Click **Open the page**.
 
-```bash
-npx @michelj/context-guard install --with-hooks
-```
+To decide the first layer: click the repo name, switch to **OpenClaw** (first use), then **See first-layer cuts**. Picking one lands it on the canvas. Titles are still prepared; the cut is yours.
 
-This also enables the current `[features] hooks = true` setting in `~/.codex/config.toml` and migrates the deprecated `codex_hooks` alias without changing other settings.
+The workbench chrome is Chinese or English. Use **中 / EN** in the top bar. Map titles, purposes, and memories stay in the language they were written.
 
-Use from GitHub before the npm package is published:
+Start or stop it manually when needed:
 
 ```bash
-npx github:Michel-Johnson/Context-Guard-Skill install
+context-guard workbench --root /path/to/project
+context-guard workbench --root /path/to/project --stop
 ```
 
-Manual install is also supported:
+### Overview
 
-```bash
-git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
-cd Context-Guard-Skill
-mkdir -p ~/.codex/skills/context-guard
-rsync -a --delete \
-  SKILL.md README.md README.zh-CN.md agents references scripts tests \
-  ~/.codex/skills/context-guard/
-```
+Root catalog: 4–8 module cards. Click a card to enter. Bugs stay in the right-hand list.
 
-After installation, Codex should discover:
+![Workbench overview](docs/shots/workbench/overview.png)
 
-```text
-~/.codex/skills/context-guard/SKILL.md
-```
+### Inside a module
 
-## Where Context Lives
+Work units hang under the module. Hierarchy is parent–child solid curves.
 
-Context must be saved under the local project currently opened in Codex:
+![Inside a module](docs/shots/workbench/module.png)
 
-```text
-<Codex project root>/.codex/context/
-```
+### Module relations
 
-Do not write project context into:
+「关系」 highlights produce/consume partners and dims the rest. It does not enter the module.
 
-- the skill install directory
-- a chat/thread directory
-- a temporary directory
-- an SSH remote server path
+![Module relations](docs/shots/workbench/relations.png)
 
-Short user prompts that matter for future work are kept in:
-
-```text
-<Codex project root>/.codex/context/user-messages.md
-```
+### Session flow
 
-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:
+Click a bug with an assigned session. The path from the root to that node lights up; current session beads run along the chain.
 
-```text
-<Codex project root>/.codex/context/private/
-```
+![Session flow](docs/shots/workbench/session-flow.png)
 
-When running scripts manually, pass the project root explicitly:
+### Auth / inspect mode
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
-```
+「授权模式」 marks which slices this session’s agent may read. Grey cards are not authorized.
 
-Register a user-approved automated test:
+![Auth mode](docs/shots/workbench/auth-mode.png)
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
-  --root /path/to/project \
-  --title "Markdown preview rendering" \
-  --command-text "npm test"
-```
+## Install
 
-Create a proposed feature-chain test:
+Install with npx. The installer detects Codex, Cursor, and Claude, then installs both the skill and lifecycle hooks while preserving existing configuration:
 
 ```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"
+npx @michelj/context-guard install
 ```
 
-Attach a bad case to a specific feature-chain checkpoint:
+Or install globally and let the package configure detected clients automatically:
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --node-title "Backend returns monitor URL" \
-  --bad-case BC-... \
-  --check "grafana_url is non-empty and the frontend does not hang"
+npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
 ```
 
-After the user confirms the flow, approve that same chain:
+Force installation for all three clients:
 
 ```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"
+npx @michelj/context-guard install --platform all
 ```
 
-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:
+Hooks are installed by default. To copy only the skill, opt out 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"
+npx @michelj/context-guard install --no-hooks
 ```
 
-Audit which checkpoints are required or optional:
+Default skill paths are `~/.codex/skills/context-guard`, `~/.cursor/skills/context-guard`, and `~/.claude/skills/context-guard`. The installer backs up and merges existing hook/settings files. For Codex it also enables `[features] hooks = true` and migrates the deprecated `codex_hooks` alias.
 
-```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:
+Use from GitHub before the npm package is published:
 
 ```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"
+npx github:Michel-Johnson/Context-Guard-Skill install
 ```
 
-After development, hand completion to the Test Hub:
+Manual install is also supported:
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
+git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
+cd Context-Guard-Skill
+mkdir -p ~/.codex/skills/context-guard
+rsync -a --delete \
+  SKILL.md README.md README.zh-CN.md agents prototype references scripts \
+  ~/.codex/skills/context-guard/
 ```
 
-Open the read-only Test Hub page:
+After installation, the matching clients should discover:
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
+```text
+~/.codex/skills/context-guard/SKILL.md
+~/.cursor/skills/context-guard/SKILL.md
+~/.claude/skills/context-guard/SKILL.md
 ```
 
-Manage tests lightly:
+## Publishing
 
-```bash
-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 "not needed every time"
-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 "only editor changes need it"
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
-```
+GitHub Releases are not part of this package's delivery path. Users install the skill from npm, so publishing is driven by a version tag:
 
-## Common Usage
+1. Update `package.json` to the next stable version and merge that commit into `main`.
+2. Create the matching `vX.Y.Z` tag on that commit.
+3. Push the tag. `.github/workflows/npm-publish.yml` validates, packs, smoke-tests, and publishes that exact tarball to npm.
 
-Ask Codex to maintain context:
+The workflow has no manual trigger. Pushing a matching version tag starts the complete publish pipeline automatically; the validated tarball is retained as a GitHub Actions artifact for 14 days. It reuses npm Trusted Publishing for `Michel-Johnson/Context-Guard-Skill`, workflow filename `npm-publish.yml`, with the `npm publish` action allowed. Local npm login is not required for Actions publishing. See the [release and recovery runbook](https://github.com/Michel-Johnson/Context-Guard-Skill/blob/main/docs/npm-release-runbook.md).
 
-```text
-Use $context-guard to maintain this task context.
-```
+## Where Context Lives
 
-Show the current roadmap:
+Context stays under the opened local project, independent of the client:
 
 ```text
-Use $context-guard to show the roadmap.
+<project root>/.codex/context/
 ```
 
-Initialize project context:
+Do not write project context into:
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
-```
+- the skill install directory
+- a chat/thread directory
+- a temporary directory
+- an SSH remote server path
 
-Set the record language:
+Short user prompts that matter for future work are kept in:
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language English
+```text
+<project root>/.codex/context/user-messages.md
 ```
 
-Generate the roadmap:
+If the user provides a credential that future turns need, Context Guard records only a redacted pointer in public context. Raw durable secrets must stay local-only under:
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
+```text
+<project root>/.codex/context/private/
 ```
 
-Or use the npm CLI as a thin wrapper:
+When running scripts manually, pass the project root:
 
 ```bash
-npx @michelj/context-guard show-roadmap --root /path/to/project
+python3 scripts/context_guard.py init --root /path/to/project
+python3 scripts/context_guard.py set-language --root /path/to/project --language English
 ```
 
-Create a branch task:
+On the first session, if `record_language` is still `unset`, the hook instructs the agent to ask “中文 or English?” and persist the answer. Later sessions do not ask again. The `workbench` command starts the local server and returns its browser URL.
 
-```bash
-python3 ~/.codex/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
-```
+## Common Usage
 
-Record a roadmap checkpoint:
+```text
+Use $context-guard. Four stores: sessions, bugs, tasks, map.
+```
 
 ```bash
-python3 ~/.codex/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"
+python3 scripts/context_guard.py init --root /path/to/project
+python3 scripts/context_guard.py set-language --root /path/to/project --language English
+python3 scripts/context_guard.py workbench --root /path/to/project
 ```
 
+Run `context-guard workbench --root /path/to/project` to see the map.
+
 ## 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.
-- 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.
-- Final Codex summaries should state the current Test Hub result: whether approved always-run tests all passed, failed, blocked, or do not exist.
-- 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 [`SKILL.md`](SKILL.md) for the full behavior rules.
+|-- FIND.md
+|-- sessions.jsonl
+|-- sessions/
+|-- bugs-index.json
+|-- bugs/ and fixes/
+|-- tasks/
+|-- map.json
+|-- owns-index.json and cards/   # generated
+|-- preferences.json
+|-- user-messages.md
+`-- private/                     # gitignored
+```
+
+See [`SKILL.md`](SKILL.md) (one page) and `.codex/context/FIND.md`.