@michelj/context-guard 0.4.3 → 0.6.1

package/references/context-template.md

@@ -1,341 +0,0 @@
-# Context Folder Template
-
-Use this structure for project context:
-
-```text
-<opened Codex project root>/
-.codex/context/
-├── index.md
-├── user-messages.md
-├── roadmap.md
-├── bad-cases.md
-├── preferences.json
-├── private/
-│   └── secrets.local.json
-├── roadmap/
-│   ├── roadmap.html
-│   ├── roadmap-details.html
-│   ├── roadmap.md
-│   └── roadmap.json
-├── tasks/
-│   └── CTX-YYYYMMDD-short-slug/
-│       ├── context.md
-│       └── bad-cases.md
-├── task-cases/
-├── test-hub/
-│   ├── registry.json
-│   ├── feature-chains.json
-│   ├── last-run.json
-│   └── runs/
-├── bad-case-tests/
-└── archive/
-```
-
-The opened Codex project root is the local folder selected in Codex or the local workspace root for the current thread. Do not place this folder inside a skill installation directory, remote SSH path, chat/thread-specific folder, or temporary execution directory unless the user explicitly asks that location to own its own context.
-
-The `private/` folder is local-only sensitive memory. It must be covered by `.codex/.gitignore`, use restrictive local permissions where possible, and never be projected into Roadmap HTML, agent-readable exports, README files, logs, or final answers.
-
-## preferences.json
-
-```json
-{
-  "record_language": "unset",
-  "display_language": "auto",
-  "last_updated": "YYYY-MM-DD",
-  "note": "Set with: context_guard.py set-language --language <language>"
-}
-```
-
-Ask the user for a context record language the first time `record_language` is `unset`, then update this file. Use that language for future source context records. Keep literal code identifiers, paths, commands, logs, API names, and exact error text unchanged. If the user changes language later, update this file and use the new language going forward; do not bulk-translate history unless asked.
-
-## index.md
-
-```md
-# Context Index
-
-This is a dynamic queue of active and recently parked folder context. Keep it short enough to scan in seconds.
-
-## Quick Scan
-
-- Current: CTX-YYYYMMDD-short-slug
-- Latest roadmap node: NODE-YYYYMMDD-001
-- Hot bad-case tags: #hot-ui, #flaky-test
-- Resume candidate: CTX-YYYYMMDD-other-slug
-
-Keep Quick Scan to these four lines unless the user explicitly asks for a fuller view.
-
-## Current
-
-- ID: CTX-YYYYMMDD-short-slug
-- Title: short task title
-- State: current
-- Folder: `.codex/context/tasks/CTX-YYYYMMDD-short-slug/`
-- Last updated: YYYY-MM-DD
-- Summary: one sentence of the current direction
-- Next step: the next useful action
-
-## Parked / Resume Candidates
-
-### CTX-YYYYMMDD-other-slug
-
-- Title: short task title
-- State: parked | resume-candidate
-- Folder: `.codex/context/tasks/CTX-YYYYMMDD-other-slug/`
-- Parked because: urgent bug, unrelated request, waiting on user, etc.
-- Resume prompt: concise question to ask when the interruption is done
-- Last updated: YYYY-MM-DD
-
-## Archived
-
-Keep only concise summaries here. Move detailed stale context to `.codex/context/archive/`.
-```
-
-## user-messages.md
-
-```md
-# User Message Memory
-
-This file preserves concise user wording that future Codex turns may need. It is agent-readable context, not a public transcript.
-
-## Recent User Signals
-
-### YYYY-MM-DD HH:MM:SS
-
-- Mode: verbatim | summary | redacted | ephemeral
-- User message: short original user wording, concise summary for large inputs, or redacted message when secrets are present
-- Secret pointer: USER-SECRET-YYYYMMDD-HHMMSS | ephemeral-not-stored | omitted when not relevant
-- Use: Preserve this wording when deciding task direction, constraints, credentials, preferences, bad-case intake, or roadmap `User request` fields.
-
-## Durable User Constraints
-
-- User preference or rule that should affect future turns.
-
-## Secret Pointers
-
-- USER-SECRET-YYYYMMDD-HHMMSS: redacted purpose only; raw value lives in `.codex/context/private/secrets.local.json`.
-```
-
-Rules:
-
-- Record short user prompts near-verbatim when they contain requirements, preferences, constraints, route changes, bad-case reports, server details, or credentials needed for the task.
-- Summarize large pasted files, logs, attachments, or generated blobs instead of copying them wholesale.
-- Never store raw secrets outside `.codex/context/private/` or a secure OS credential store.
-- Do not persist OTP or short-lived one-time verification codes; record only `ephemeral-not-stored`.
-- Promote durable user requirements into task context or roadmap `User request:` fields, then keep this file as a concise source of recent user wording.
-
-## roadmap.md
-
-```md
-# Context Roadmap
-
-This is the route map through the task. It may contain one mainline, forked side routes, or multiple parallel mainlines. Keep nodes concise. Do not record every tiny action or chat turn.
-
-## Nodes
-
-### NODE-YYYYMMDD-001: Short node title
-
-- Date: YYYY-MM-DD
-- Status: planned | active | done | superseded
-- Level: major | checkpoint
-- Branch: Main | short branch name
-- Parent: NODE-YYYYMMDD-000 when this branch forks, otherwise none
-- Task: `CTX-YYYYMMDD-short-slug`
-- Display title: short human-facing card title; use clear language close to what the user cares about
-- User request: concise summary of the user's actual request, using the user's wording as much as possible
-- Progress summary: short human-facing current progress; omit if Outcome already reads naturally
-- Method summary: short human-facing method; omit if Decision / reason already reads naturally
-- Outcome: one-line result
-- Decision / reason: why this node exists, one line
-- Avoid going back: rejected path or lesson, only if it prevents backtracking
-- Next: next useful node or action
-- Linked bad cases: BC-YYYYMMDD-001, BC-YYYYMMDD-002
-- Test chain: compact checkpoint evidence only; user-facing recurrence checks come from linked bad-case guards
-- End-of-work self-check: changed behavior checked; for frontend/layout work include browser/plugin/screenshot evidence or the exact blocker
-```
-
-Use the `### NODE-...` section form as the canonical editable source. If a session accidentally records loose bullet blocks such as `- ID: NODE-...`, `- Title: ...`, `- Level: ...`, the renderer should still project them, but future edits should normalize them back into formal node sections.
-
-## tasks/<task-id>/context.md
-
-```md
-# Task Context: short task title
-
-- ID: CTX-YYYYMMDD-short-slug
-- State: current | parked | resume-candidate | done | archived
-- Created: YYYY-MM-DD
-- Last updated: YYYY-MM-DD
-
-## Objective
-
-One sentence describing what the user is trying to accomplish.
-
-## Key Points
-
-- Important ideas, constraints, and decisions only.
-- Rejected approaches only when they prevent repeating a wrong route.
-- Product, design, architecture, or implementation notes only when needed to resume.
-
-## Open Questions
-
-- Questions that need user input or future investigation.
-
-## Files / Areas
-
-- Relevant files, modules, commands, screenshots, or external references.
-
-## Bad Cases
-
-- Link to shared `.codex/context/bad-cases.md` entries or task-local `bad-cases.md`.
-
-## Roadmap Nodes
-
-- Link to `NODE-...` entries in `.codex/context/roadmap.md`.
-
-## Verification / Self-Check
-
-- Behavior checked before final answer.
-- Frontend/layout artifacts opened with a browser/plugin or inspected via screenshot when possible.
-- If visual inspection was blocked, record the blocker and residual risk.
-
-## Next Step
-
-The smallest useful action to resume this task.
-```
-
-## task-cases/<task-case-id>.md
-
-Use task cases for realistic multi-step verification flows. They should catch bugs by simulating a real task, not by testing one isolated bug at a time. Task-case design is human-owned: Codex may draft and structure a proposal, but durable task cases must stay `proposed` until the user confirms them.
-
-```md
-# Task Case: short realistic workflow title
-
-- ID: TC-YYYYMMDD-short-slug
-- Status: proposed | approved | active | stable | deferred | obsolete
-- Route/task: `CTX-...` or branch name
-- Scope: feature, service, UI flow, agent workflow, or subsystem
-- Last checked: YYYY-MM-DD
-- Design confirmation: pending | user-approved YYYY-MM-DD
-- Run policy: every-dev-completion | relevant-only | manual | release-only | goal-final | disabled-with-reason | user-defined cadence
-- Automation entry: native command | script path | prompt/manual runner | none
-- Artifact policy: cleanup-on-pass | preserve-on-fail | manual-preserve
-- Linked roadmap nodes: NODE-...
-- Linked bad cases: BC-..., BC-...
-- Entry command/prompt: command, prompt, manual setup, or fixture
-- Not covered: explicit exclusions to avoid fake confidence
-- Stop condition: what means the workflow is complete
-- Cleanup: required cleanup or none
-
-## Phases
-
-### Phase 1: setup or trigger
-
-- Action: one realistic action
-- Expected checkpoint: invariant, log, UI state, file state, API result, or assertion
-- Covers bad cases: BC-...
-- Failure localization: what this phase failure usually means
-- Log note: what the script/agent should record
-
-### Phase 2: transition or recovery
-
-- Action: one realistic action
-- Expected checkpoint: invariant, log, UI state, file state, API result, or assertion
-- Covers bad cases: BC-...
-- Failure localization: what this phase failure usually means
-- Log note: what the script/agent should record
-
-## Result Log
-
-- YYYY-MM-DD: pass/fail, failed phase/checkpoint if any, evidence path or command output summary
-```
-
-## Maintenance Rules
-
-- Keep `index.md` small and useful, not exhaustive.
-- Keep `roadmap.md` as the route map. It should show progress as nodes, not a raw transcript.
-- Use `Level: major` for significant milestones shown as main route cards; use `Level: checkpoint` for minor progress that should live in details.
-- Use `Branch:` for forked or parallel routes. Missing `Branch:` means `Main`; use `Parent:` to point to the node where a branch forked.
-- In the human overview, visible card numbers should be consecutive per route group after checkpoint filtering, not source node numbers with gaps.
-- If the human overview has multiple route groups, show all route lines together with parent/fork markers; keep tests and bad cases in clicked node details, Test Hub, and agent-readable exports by default.
-- Each node should be concise enough for Codex to scan quickly: outcome, decision, next step, linked bad cases.
-- Link nodes to bad cases and test-chain notes instead of duplicating full details.
-- Treat human-facing test coverage as human-designed bad-case recurrence detection. Single-route overview hides the test lane; multi-route compact test routes should be generated only from user-approved tests with explicit `Run policy`, approved task-case checkpoints, or approved test registry entries, not from ordinary linked bad-case guards or roadmap node checkpoint logs.
-- In branch or multi-route views, align each visible test item to the roadmap node whose approved bad-case test or approved task-case checkpoint it covers. If a route has no approved tests, do not show a test route for it. Empty test slots should be subtle timeline placeholders only when the route has at least one approved test elsewhere.
-- Prefer a task-oriented case in `.codex/context/task-cases/` when realistic workflow phases matter more than isolated bug checks. Bad-case guards should often point to a task-case checkpoint that covers them.
-- Prefer a feature chain in `.codex/context/test-hub/feature-chains.json` when one user-visible feature or workflow can cover several bad cases through checkpoint coverage. Attach new bad cases to existing chain checkpoints before proposing a new chain.
-- Before proposing a new feature chain for a bad case, run `context_guard.py feature-chain-plan --root <project> --query "<bad case or feature text>"`; this is a read-only intake to either review an existing chain or propose a `feature-chain-propose` skeleton with checkpoint coverage state. Do not use `feature-chain-add` as the planner skeleton.
-- Before approving automation, or when proposed feature chains sound similar, run `context_guard.py feature-chain-overlap --root <project>`; this is a read-only duplicate-chain audit to help merge or extend an existing workflow instead of creating another always-run test.
-- `feature-chain-add` creates proposed chains by default. After the user confirms the business flow and test design, use `feature-chain-approve --chain-id <id> --command-text "<approved command>"` to promote the same chain. Do not hand-edit `feature-chains.json` or create a duplicate approved chain to bypass the approval gate.
-- If the user says an approved feature chain should not run every time, use `feature-chain-set-policy --chain-id <id> --run-policy <policy> --reason <reason>` to update the same chain. Do not delete or duplicate feature chains just to change cadence.
-- After editing feature chains, run `context_guard.py validate-feature-chains --root <project>` to catch missing entries, exits, approved automation, checkpoint checks, linked bad-case coverage, and artifact policy issues. This validates structure only; it does not approve business test design.
-- Feature-chain commands may emit `CG_CHECKPOINT:<checkpoint title or id>:PASS` or `CG_CHECKPOINT:<checkpoint title or id>:FAIL:<short reason>`; Test Hub treats any `FAIL` marker as a failed chain and reports that checkpoint. Marker names must match registered checkpoint titles or ids; unknown markers are test-chain failures.
-- Task-case scripts or agents should log the phase/checkpoint that failed, so Codex can locate the broken workflow step without re-debugging the whole task.
-- Before writing any new durable task-case script or active task case, ask the user to confirm with only the business path: from what state to what state, the main task, and the major risk. Keep technical phases/checkpoints/logs inside the task-case file, not in the confirmation prompt. If confirmation is unavailable, keep the case `proposed` and avoid broad new scripts.
-- When the user explicitly asks to create, write, generate, design, or add a test/test task/task case, start the user-visible response with `测试创建识别：...` or the folder-language equivalent, then summarize the test target from what state to what state and the main risk it catches.
-- When the user creates or approves a test, register it with `Run policy: every-dev-completion` by default. At the end of every development turn, run all approved tests with that policy or record the exact blocker.
-- Use `.codex/context/test-hub/registry.json` as the explicit Test Hub registry for user-approved automated tests. Do not populate it from ordinary bad-case guards or roadmap node `Test chain:` notes.
-- Keep Test Hub as a simple control layer: registry, `dev-complete`, `last-run.json`, and lightweight commands to list, enable, disable, change policy, or remove registry tests.
-- At development completion, prefer `context_guard.py dev-complete --root <project>` so the hub runs the approved always-run set, handles parallel workers when safe, cleans success artifacts, and preserves failure evidence under `.codex/context/test-hub/runs/`.
-- After approval, automate a test when it can be safely scripted or run as a native command. Future Codex turns should execute the registered entry with minimal reinterpretation.
-- Automated tests should clean temporary files after full success and preserve concise diagnostic artifacts on failure.
-- Failed approved tests become a bad-case analysis loop: inspect the preserved evidence, fix the in-scope cause, rerun the same approved test, and stop only after pass or a non-actionable blocker.
-- If blocked by credentials, unavailable external service, permissions, hardware/resource limits, network, destructive-risk confirmation, or user-only judgment, ask or warn the user with the exact blocker and evidence path.
-- Change a test to `relevant-only`, `manual`, `release-only`, `goal-final`, `disabled-with-reason`, or another cadence only when the user explicitly asks. Record the user's reason beside the policy.
-- During goal mode, task cases should act as phase gates: select an approved case or propose one for confirmation, log phase progress during continuations, and run the smallest human-approved path before claiming the goal complete.
-- Keep multilingual display as an HTML projection concern; do not duplicate source context by language. When supported, localize human-facing record titles, summaries, bad-case labels, and test-chain snippets in the projection.
-- Keep source records in the configured `.codex/context/preferences.json` record language. The HTML roadmap should follow that preference and should not show a visible language selector by default.
-- During goal mode or long-running autonomous work, keep the active goal aligned to the current task, add compact goal checkpoints during meaningful phase changes, and record bad cases as soon as they appear.
-- Treat `.codex/context/index.md`, `.codex/context/roadmap.md`, `.codex/context/bad-cases.md`, and task context files as the source of truth.
-- Treat `.codex/context/user-messages.md` as the source for recent user wording and durable user signals. Use it to populate roadmap `User request:` fields and avoid asking the user to repeat short instructions.
-- Treat `.codex/context/private/` as local-only sensitive memory. Never expose raw secrets in human-facing HTML or git-tracked context.
-- Treat `.codex/context/roadmap/roadmap.html` as a human-facing view only. Codex should not use it for context intake or bad-case management.
-- Treat `.codex/context/roadmap/roadmap.md` and `.codex/context/roadmap/roadmap.json` as stable agent-readable exports for quick scanning, route lookup, bad-case lookup, and recurrence-guard lookup, not as primary editable sources.
-- Keep `NODE-...`, `BC-...`, and `CTX-...` IDs in source files for linking, but hide them in the default human-facing HTML. Show short natural-language node and bad-case labels instead.
-- In human-facing HTML, prefer color, symbols, and compact visual markers over labels like `Status:`, `Nodes:`, `Frequency:`, or fallback text such as `untagged`.
-- Show meaningful `#tags` as compact colored chips with small emoji cues in human-facing HTML. Limit overview tags; show full tags on the detail page; omit the tag row when no tags exist.
-- A sharp task direction change should park the current task before starting a new one.
-- If the user explicitly says a task is a branch/side route/fork/支线/分支, run or emulate `scripts/context_guard.py create-branch-task --title <task title> --branch <branch name> --parent-node <parent NODE id>` before implementation so the task folder, current index entry, and `Branch:`/`Parent:` roadmap node all exist.
-- If work significantly drifts from the mainline architecture without an explicit branch request, ask whether to create a branch before silently continuing.
-- When an interruption finishes, ask whether to resume the most relevant parked task.
-- Do not let parked items grow endlessly. Mark stale items `archived` and compress them to a short summary.
-- Do not delete unresolved user intent unless the user explicitly discards it.
-- Use `scripts/context_guard.py show-roadmap` to generate and display the stable human-friendly overview at `.codex/context/roadmap/roadmap.html`, with details at `.codex/context/roadmap/roadmap-details.html`, agent-readable Markdown at `.codex/context/roadmap/roadmap.md`, and structured lookup at `.codex/context/roadmap/roadmap.json`. Use `export-roadmap --format md` only for Markdown-only export.
-- Do not accumulate timestamped HTML roadmap files. Showing the roadmap overwrites the same stable HTML files.
-- With one route group, the HTML roadmap overview should show only the main route cards. Keep linked bad cases and recurrence checks in clicked node details, source context, and agent-readable exports.
-- In one-route HTML, do not render bad-case/test-chain lanes or a left lane-label column. The route board should size to real content, and main route summaries should remain readable rather than being clipped after a very short fragment.
-- With multiple route groups, the overview should show all route lines as a branch map. If a route has user-approved tests, also show a compact node-aligned test route under that route line. Route selection may affect details, but the default view should not invent tests from ordinary bad-case context.
-- Parent/fork markers should appear only on side routes whose parent node is outside that route. Main route should not show a fork marker just because a later main node references an earlier main node.
-- Side routes should visually start near their parent node's visible position on the parent route, not all from the first column.
-- Branch route labels, parent chips, and checkpoint text should sit near the branch's first visible card by reusing the same spacer/grid coordinate as the branch cards.
-- Branch overview should use one shared horizontal route canvas. Route alignment should use grid spacer columns, not padding that shifts or clips the whole route section.
-- Branch connector lines should use the same offset coordinate as the route's spacer columns, not a fixed left-edge position.
-- Branch connector endpoints should be anchored to the status dots inside the source and target node cards; do not draw connector lines from the whole route section or unrelated card edges.
-- Route progression connectors should be card-to-card through card gaps; branch connectors should be dot-to-dot through an empty branch corridor and must not cross node cards or text.
-- Side routes may drift right from exact column alignment when that creates a cleaner non-crossing branch path.
-- Connector layers should render behind route cards so cards mask any line segment that would otherwise pass over content.
-- Hide heavy native horizontal scrollbar chrome in the roadmap overview while preserving horizontal scroll interaction.
-- Human-facing node detail cards should show only one concise summary sentence, linked bad cases, and linked bad-case recurrence tests. Do not show a standalone status dot under the node detail title. Keep route, parent, decision, avoid-going-back, and next-step source fields in agent-readable context, not in the human detail card.
-- Human-facing bad-case details should localize phenomenon, trigger, root cause, fix, and guard prose to the folder language preference while preserving technical identifiers, commands, and paths.
-- Route color should encode branch depth: main route green, first-level branch cool cyan/teal, deeper branch levels progressively colder toward blue and indigo.
-- Before finalizing frontend, roadmap HTML, or visual layout work, open or render the artifact with an available browser/plugin or screenshot path and inspect for obvious visual bugs. Do not rely only on string assertions for layout changes.
-- Treat Stop hook output as a completion reliability gate. Before claiming fixed/done/passing, record real verification evidence for the changed artifact or workflow and rerun relevant bad-case guards.
-- For UI/browser/binding/frontend work, verify the original user-visible symptom, not only build success or process restart.
-- User-facing projected text should follow the folder language preference; avoid untranslated English prose in Chinese overview output except for intentional technical strings.
-- For a single route group, do not show lane titles or a left label column; the overview is only the main route.
-- Keep overview cards sparse. Put full Outcome, Decision, Next, and guard details in same-file detail anchors and the stable `roadmap-details.html` sidecar.
-- In multi-route branch overview, route cards should read as a compact map skeleton: number, title, date/status cue, and no visible outcome paragraph. Keep route summaries in details and source context.
-- Default overview links should target same-file `#node-*` and `#case-*` anchors, not `roadmap-details.html#...`, to avoid `file://` access-denied navigation.
-
-## Pruning Rules
-
-- Do not record normal implementation chatter.
-- Do not drop short user messages that contain requirements, constraints, preferences, credentials, route changes, or bad-case reports.
-- Do not paste huge files or logs into user-message memory; summarize them.
-- Do not store raw secrets in public context files, roadmap HTML, exports, logs, or final answers.
-- Do not record every command; record only commands that prove a checkpoint or guard a bad case.
-- Do not let roadmap node `Test chain:` history replace bad-case recurrence guards in user-facing roadmap output.
-- Do not split a real workflow into many unrelated bug-level tests when one task case with checkpoints would reveal the failure location more clearly.
-- Do not silently enter test creation. If the user explicitly asks to create a test, acknowledge the test-creation intake first so the user can see the skill activated.
-- Do not wait until goal completion to record important roadmap progress or bad cases.
-- Merge tiny adjacent updates into one roadmap node.
-- Archive stale parked tasks as a one-sentence summary.
-- If a reader cannot use a detail to resume, decide, verify, or avoid recurrence, remove it.

package/references/feature-chain-methodology.md

@@ -1,228 +0,0 @@
-# Feature Chain Methodology
-
-Use feature chains when the goal is to prevent fixed bad cases from reappearing without creating one durable test per bad case.
-
-## Core Idea
-
-The durable test unit is a user-visible feature or workflow. A bad case is coverage attached to one checkpoint inside that workflow.
-
-```text
-Feature chain
-  Entry: the real trigger users or Codex will perform
-  Checkpoint 1: expected intermediate state
-    Covers: BC-...
-  Checkpoint 2: expected transition or output
-    Covers: BC-..., BC-...
-  Exit check: strict final green condition
-```
-
-## Creation Rule
-
-When a bad case appears:
-
-1. Identify the feature entry that can reproduce or guard the symptom.
-2. Search existing feature chains for the same entry, workflow, component, route, or service. Use the read-only planning helper first:
-
-   ```bash
-   python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-plan --root <project> --query "<bad case or feature text>"
-   ```
-
-   The query can be natural language or a `BC-...` ID. The planner is read-only: it either says `action: review-existing-chain` with match evidence and an after-confirmation attach-command skeleton, or `action: propose-new-chain` with a compact user-confirmation prompt and a `feature-chain-propose` command skeleton. The proposed skeleton must contain a checkpoint and explicit coverage state: use `--bad-cases` for a real bad-case seed, or `--coverage-pending-reason` for a user-described test target that has no concrete bad case yet. If the input is only a `BC-...` ID, the prompt should describe the bad case by title or summary instead of asking the user to confirm an opaque ID. It must not create a feature chain, attach a bad case, or approve automation; run the skeleton only after user confirmation.
-
-3. Use `feature-chain-suggest` when you only need raw candidate chains/checkpoints. If only a bad-case ID is available, the helper expands it from `bad-cases.md` first so matching uses the case title, summary, phenomenon, trigger, cause, and tags rather than the opaque ID alone.
-4. Use `feature-chain-coverage` when you need the whole register view. It should show covered cases, unassigned candidates, and possible existing chains for visible candidates without changing the registry. Strong suggestions should include short match evidence terms; if the evidence is weak or unreadable, treat the suggestion as planning noise rather than coverage.
-5. Use `feature-chain-candidates` when the unassigned list is too large. It groups unassigned bad cases by shared feature tags, prefers more specific tag combinations over broad single tags, suppresses repeated groups that add little new coverage, and proposes a small set of candidate feature chains. Treat `new coverage` as the key signal: a candidate with high total count but low new coverage may be a subcase of an earlier chain. It must not create, attach, or approve anything; it only helps choose which user-visible flow is worth designing.
-6. Use `feature-chain-overlap` before approving automation, or whenever several proposed chains sound similar. It is read-only and flags pairs that likely describe the same workflow. If it reports overlap, merge the intent or extend one chain before creating another always-run test.
-7. If a chain exists and the match is semantically correct, attach the bad case to the closest checkpoint and tighten that checkpoint.
-8. If no chain exists, propose a new chain in one short business-facing sentence and wait for user confirmation before approving or automating it.
-
-For natural-language test requests, keep the user's business intent but remove the request wrapper before writing the confirmation prompt. For example, `写一个测试，检验每次开发完成后 Markdown 编辑器里的单行、多行和矩阵公式都能正常渲染` should become a compact subject such as `Markdown 编辑器里的单行、多行和矩阵公式能正常渲染`, not a verbatim copy of the whole chat sentence. This keeps the prompt useful for human confirmation while avoiding agent-invented workflow details.
-
-When the user already gives a workflow shape, preserve it. A request like `创建一个测试任务：从编辑器输入 Markdown 到预览正确渲染，主要验证公式渲染回归` should be confirmed as `从「编辑器输入 Markdown」到「预览正确渲染」，主要验证「公式渲染回归」`. Do not replace explicit entry/exit/risk wording with generic "相关入口到正确结果" language.
-
-For this explicit shape, `feature-chain-plan` may prefill the after-confirmation `feature-chain-propose` skeleton with the stated entry and exit check, and may print the stated risk as a suggested checkpoint. This is still only a confirmation aid: it must not create the chain, approve automation, or invent missing checkpoint details before the user confirms the business flow.
-
-CLI rule: `feature-chain-add` creates `status: proposed` by default. Do not treat this as an approved test. `feature-chain-add --test-status approved` is not allowed for `every-dev-completion` chains because it skips the user confirmation and approval dry-run gates. Use `feature-chain-approve` on the same proposed chain instead.
-
-After the user confirms a candidate flow, use `feature-chain-propose` when you need to record a safe draft with seed bad-case coverage:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-propose \
-  --root <project> \
-  --title "<confirmed feature title>" \
-  --entry "<confirmed user-visible entry>" \
-  --exit-check "<confirmed strict final green condition>" \
-  --node-title "<confirmed checkpoint>" \
-  --bad-cases "BC-..., BC-..." \
-  --check "<checkpoint recurrence check>"
-```
-
-This command creates only a `proposed` chain. It records the user-confirmed shape and seed bad cases, but it does not add an executable command and must not enter `dev-complete` until `feature-chain-approve` is run with user-approved automation.
-
-If the user confirms the feature flow before any concrete bad case exists, keep the same command but replace `--bad-cases ...` with `--coverage-pending-reason "<why there is no linked bad case yet>"`. This records the draft so it is not lost, but it is not recurrence coverage and cannot be approved for `every-dev-completion` until a real bad case is attached to a checkpoint.
-
-When a later bad case appears, run `feature-chain-plan` first. If it points to a coverage-pending chain/checkpoint, attach the bad case there with `feature-chain-attach-bc` and tighten the checkpoint text. The attach step should clear the pending-coverage note, because the checkpoint now has real bad-case coverage.
-
-The expected lifecycle is:
-
-1. `feature-chain-plan` turns user wording or a bad-case ID into a read-only confirmation prompt.
-2. After user confirmation, `feature-chain-propose` records a non-executable draft with either linked bad cases or a coverage-pending reason.
-3. Later bad cases are routed through `feature-chain-plan` and attached to the nearest existing checkpoint when semantically correct.
-4. `feature-chain-summary` gives the fast coverage map; `feature-chain-overlap` checks duplicate workflow coverage before approval.
-5. `feature-chain-approve` is the only path into the always-run set and must pass the checkpoint dry run.
-6. `dev-complete` runs the approved chain with structured checkpoint markers and cleans success artifacts.
-
-This lifecycle is the core experiment: fewer feature chains should cover more bad-case recurrence checks without Codex inventing a broad test suite.
-
-Multi-project trials are the sanity check for this method. These trials must start from fresh sandbox projects instead of reusing an existing project, existing context folder, or previous test registry; otherwise the result may only prove that old context happened to work. The sandbox themes should also be genuinely different, such as a life utility, a creative tool, and a game or interaction, not merely three variants of the same engineering workflow. In small linear flows, one feature chain with two to four checkpoints can cover about three related bad cases and localize the failed phase. Treat planner checkpoint suggestions as hints, not business truth: Codex or the user must attach each bad case to the real phase where it can recur. When the workflow has queues, retries, multiple workers, recovery branches, or cross-process cleanup, upgrade the design to a task case instead of stretching a simple feature chain.
-
-A single-chain trial is not enough to validate Context Guard itself. A system-level regression should include at least two independent approved feature chains in one fresh project, then prove that `dev-complete` runs both, reports one chain failure without hiding the other chain's pass result, preserves the failing evidence, and returns to all-pass after the same chain is fixed. This checks the Test Hub orchestration layer rather than only the lifecycle of one feature chain.
-
-Before approving automation, use a dry run when the proposed command or checkpoint markers need validation:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-dry-run \
-  --root <project> \
-  --chain-id FC-YYYYMMDD-001 \
-  --command-text "<candidate command>"
-```
-
-Dry run executes the candidate command against the proposed chain's registered checkpoints, reports missing/failed/unknown checkpoint markers, cleans success artifacts, and preserves failure evidence under `.codex/context/test-hub/dry-runs/`. It does not approve the chain, does not write the command into `feature-chains.json`, and does not add the chain to `dev-complete`.
-
-Dry-run evidence paths must be unique per run. Fast repeated or parallel dry runs must not reuse or overwrite a previous failure directory, because the preserved evidence is what lets Codex locate the failed checkpoint without reinterpreting the whole task.
-
-## Approval Rule
-
-After the user confirms the feature flow and test design, promote the existing proposed chain with:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-approve \
-  --root <project> \
-  --chain-id FC-YYYYMMDD-001 \
-  --command-text "<approved command>"
-```
-
-Approval is a safety gate and the only supported path from proposed feature-chain automation to `every-dev-completion`. It refuses a chain that has no checkpoint, no checkpoint check text, no linked bad-case coverage, or no automated command when the run policy is `every-dev-completion`. For `every-dev-completion` automation, approval must also run a dry-run preflight before mutating the registry. If the command misses a required checkpoint marker, emits an unknown marker, emits a `FAIL` marker, times out, or hits a blocker, approval fails and the chain stays `proposed`. Do not bypass this by hand-editing `feature-chains.json`, using `feature-chain-add --test-status approved`, or creating a second approved chain.
-
-## Policy Rule
-
-After approval, the user's cadence still wins. If the user says a feature chain should not run after every development turn, update the existing chain instead of deleting or duplicating it:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-set-policy \
-  --root <project> \
-  --chain-id FC-YYYYMMDD-001 \
-  --run-policy relevant-only \
-  --reason "User said this chain is only needed when touching GPU monitor flows."
-```
-
-Keep the reason short and human-readable. Use `disabled-with-reason` only when the user asks to disable the chain or it cannot be run safely.
-
-## Design Heuristic
-
-A good chain has:
-
-- one clear entry point
-- one realistic flow, not a pile of unrelated checks
-- two to five checkpoints
-- strict red and green conditions
-- failure localization, so the runner reports which checkpoint broke
-- cleanup-on-pass and preserve-on-fail behavior
-
-Avoid:
-
-- one script per bad case when one feature flow can cover them
-- broad suites that run unrelated product areas
-- checks that only prove code executed but cannot catch the old symptom
-- durable tests written from agent guesses without user confirmation
-
-## Storage
-
-Store chain metadata in:
-
-```text
-.codex/context/test-hub/feature-chains.json
-```
-
-Store large scenario specs in `.codex/context/task-cases/` only when the workflow needs richer phases, logs, or human-readable execution notes.
-
-## Execution
-
-Approved chains with `status: approved | active | stable` and `run_policy: every-dev-completion` are part of Test Hub. At development completion, run them through:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py dev-complete --root <project>
-```
-
-The runner should execute the approved command with minimal Codex reinterpretation, clean success artifacts, preserve failure evidence, and report the failed checkpoint or blocker.
-
-A feature-chain experiment is not complete just because one happy path passes. It should prove the closed loop: one chain covers multiple bad cases, a failing checkpoint preserves evidence with an actionable reason, and the fixed path passes while cleaning temporary artifacts.
-
-When an approved chain fails, do not design a new test to prove the same workflow. Treat the failed checkpoint as the recurrence signal, fix the cause, and rerun the same approved chain. A good runner makes this loop cheap by emitting readable checkpoint markers, preserving only the useful failure evidence, and cleaning success artifacts after the rerun passes.
-
-Feature-chain commands can report phase-level status with lightweight markers:
-
-```text
-CG_CHECKPOINT:<checkpoint title or id>:PASS
-CG_CHECKPOINT:<checkpoint title or id>:FAIL:<short reason>
-```
-
-Test Hub treats any `FAIL` marker as a failed feature chain, even if the command exits 0. Prefer these markers when one command covers several checkpoints, because the preserved result will point to the broken workflow step instead of only saying that the whole command failed.
-
-Marker names must match registered checkpoint titles or ids. Unknown markers fail the chain because they usually mean the script no longer matches the approved workflow. Keep non-English checkpoint titles readable and distinct; do not collapse them into generic ids.
-
-Approved feature-chain commands must report every registered checkpoint unless a checkpoint is explicitly optional (`optional: true` or `required: false`). Missing markers fail the chain, because an unreported checkpoint was not proven to run.
-
-If the user or business flow says one checkpoint should not be required every time, change that checkpoint explicitly instead of weakening the whole chain:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-set-checkpoint \
-  --root <project> \
-  --chain-id FC-YYYYMMDD-001 \
-  --node-title "前端打开监控页" \
-  --required optional \
-  --reason "Only runs in browser integration environment."
-```
-
-Use `--required required` to restore the checkpoint to every-run coverage. This keeps the chain strict by default while allowing intentional, documented exceptions.
-
-Audit required/optional coverage without opening JSON:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-list --root <project> --verbose
-```
-
-Audit the compact coverage map before creating new coverage:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-summary --root <project>
-```
-
-This is the quickest way to see whether a small number of feature chains already covers several bad cases, and which checkpoints are still waiting for a real bad case before approval.
-Treat the `coverage density`, `reuse signal`, and `next:` lines as decision aids: they should push Codex toward reusing or extending an existing workflow when possible, not toward creating another standalone test.
-
-Audit possible duplicate feature chains before approval:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-overlap --root <project>
-```
-
-This is a route-choice guard, not a test runner. It compares existing chain wording and linked bad cases, then prints pairs that may be the same workflow. Use it to avoid turning one business flow into multiple always-run tests.
-
-Audit bad-case coverage across chains without mutating records:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py feature-chain-coverage --root <project>
-```
-
-Use this to decide whether a new bad case should attach to an existing chain or remain a standalone guard. Treat unassigned cases as candidates, not as required new tests.
-
-## Quality Gate
-
-After editing feature chains, run:
-
-```bash
-python3 ~/.agents/skills/context-guard/scripts/context_guard.py validate-feature-chains --root <project>
-```
-
-This gate checks structure, not business judgment. It catches approved chains that are missing an entry point, exit check, automated command, checkpoint nodes, checkpoint check text, linked bad-case coverage, or a clear artifact policy. It does not create tests, approve tests, or decide whether the user's workflow deserves a durable chain.