@michelj/context-guard 0.4.3 → 0.4.4

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.

package/references/register-template.md

@@ -1,85 +0,0 @@
-# Bad Case Register Template
-
-Use this format for `.codex/context/bad-cases.md`, task-local `.codex/context/tasks/<task-id>/bad-cases.md`, or the existing project context register.
-
-```md
-# Bad Case Register
-
-This register tracks bad cases found during development and the guards that prevent them from recurring.
-
-Record only bad cases that are user-visible, recurring, risky, fixed, deferred, or needed to explain a guard. Do not turn the register into a defect diary.
-
-## Active Cases
-
-### BC-YYYYMMDD-001: Short descriptive title
-
-- Status: open | resolved | recurred | deferred | superseded-by-route-change
-- First observed: YYYY-MM-DD
-- Last checked: YYYY-MM-DD
-- Scope: feature, files, tests, route, UI flow, API, or subsystem
-- Context task: `CTX-...` folder or shared
-- Roadmap nodes: `NODE-...`
-- Tags: #hot | #flaky | #ui | #data-loss | #route-risk | custom tags
-- Frequency: first-seen | repeated-N | high-frequency
-- Phenomenon: one-line user-visible behavior or failing output
-- Trigger / reproduction: shortest command, step, input, environment, or precondition
-- Root cause: confirmed cause, suspected cause, or unknown, one line
-- Fix method: code/test/config/documentation change that fixed it, one line
-- Guard type: script | native-test | manual | browser-screenshot | browser-dom | curl | cli | prompt | log-invariant | fixture | unit | integration | e2e | custom
-- Guard / verification: native test, command, reusable script, manual check, screenshot, log, invariant, or reproduction note, one line
-- Run policy: every-dev-completion | relevant-only | manual | release-only | goal-final | disabled-with-reason | user-defined cadence
-- Artifact policy: cleanup-on-pass | preserve-on-fail | manual-preserve | none
-- Blocker handling: credentials | external-service | permissions | resource-limits | network | destructive-confirmation | user-judgment | none
-- Red condition: exact output, visual state, assertion, or symptom that means this bad case has recurred
-- Green condition: exact evidence that means this bad case is absent
-- Expected failure reason: why the guard should fail for the old symptom, not for a broken test or unrelated environment issue
-- Reusable guard path: project test file, `.codex/context/task-cases/...#phase-name`, `.codex/context/bad-case-tests/...`, or none
-- Covered by task case: TC-YYYYMMDD-short-slug phase/checkpoint, or none
-- Test-chain issue: false-positive | false-negative | wrong-granularity | missing-phase | wrong-assertion | unrealistic-setup | missing-cleanup | unclear-localization | none
-- Guard reuse rule: reuse this recorded guard before creating any new test or script for this case
-- Test chain: ordered checks only when multiple checks are genuinely needed
-- High-frequency note: warning text to show Codex when this pattern repeats often
-- Recurrence analysis: why it came back, if it ever did
-- Route-change note: only when an approved technical route change intentionally changes expected behavior
-- Evidence: links to tests, commands run, PRs, commits, screenshots, or logs
-
-## Resolved History
-
-Move old resolved entries here only if the active section becomes noisy. Keep enough detail to replay the guard.
-```
-
-Use the `### BC-...` section form as the canonical editable source. If a session accidentally records loose bullet blocks such as `- ID: BC-...`, `- Title: ...`, `- Status: ...`, or `- Nodes: ...`, the renderer should still project them, but future edits should normalize them back into formal case sections.
-
-## Status Rules
-
-- `open`: bad case is known and not fixed.
-- `resolved`: fix is implemented and verification passed.
-- `recurred`: bad case came back after resolution; must be analyzed and fixed before completion.
-- `deferred`: intentionally not fixed in the current task; requires reason and owner/next step.
-- `superseded-by-route-change`: old behavior is no longer expected because an approved technical route changed it.
-
-## Context Guard Rules
-
-- Use `.codex/context/` as the project folder for bad-case memory. Do not introduce a separate bad-case folder for new projects.
-- Use the configured `.codex/context/preferences.json` `record_language` for bad-case titles, phenomenon, root cause, fix method, guard summaries, and test-chain notes.
-- Preserve exact commands, paths, code identifiers, logs, API names, and error messages in their original language.
-- Prefer existing recorded context, user-approved commands, native tests, screenshots, logs, or manual checks over newly invented tests.
-- When the user creates or approves a test, default its `Run policy` to `every-dev-completion`; Codex must run it at every development completion unless the user sets another cadence.
-- Only the user can demote an approved test to `relevant-only`, `manual`, `release-only`, `goal-final`, `disabled-with-reason`, or a custom cadence. Record why.
-- After user approval, automate the check when feasible; successful automated checks should clean temporary files, while failed checks should preserve concise diagnostic evidence for Codex to analyze and rerun after fixing.
-- Store reusable user-approved automated tests in `.codex/context/test-hub/registry.json` or approved task-case files; do not auto-register ordinary bad-case guards or roadmap `Test chain:` notes as always-run tests.
-- At development completion, prefer `context_guard.py dev-complete --root <project>` so Test Hub runs the approved always-run set and writes `.codex/context/test-hub/last-run.json`.
-- If an approved automated check is blocked by credentials, external services, permissions, resource limits, network, destructive confirmation, or user-only judgment, record the blocker and ask or warn the user instead of looping.
-- For resolved or recurred cases, `Guard / verification`, `Guard type`, `Red condition`, `Green condition`, and `Expected failure reason` are required.
-- The guard must be red-capable: it should fail if the same user-visible symptom returns.
-- When the bad case is part of a longer workflow, attach it to a human-approved task-case checkpoint instead of creating a separate isolated script. The bad-case entry should say which task case phase covers it.
-- If the test chain itself is wrong, record that as a bad case and classify the test-chain issue. Fix the test-chain design before trusting its result.
-- Do not script every bad case. Store bad-case-specific scripts under `.codex/context/bad-case-tests/` only when the user approved the test design, the script is genuinely reusable, and it does not belong in the native test suite.
-- Name any guard script with the bad case ID so it is easy to find and reuse.
-- Update existing context when expected behavior changes; do not create parallel guards for the same case unless the old one is explicitly obsolete.
-- If a guard is manual-only, list the exact manual check and why that is acceptable for now.
-- Link bad cases to roadmap nodes so Codex can quickly see which mainline decisions created or fixed them.
-- Keep record/display linkage explicit: use `Roadmap nodes:` or `Nodes:` on the bad case, or `Linked bad cases:` on the roadmap node.
-- Add tags and frequency notes when a bad case repeats often; high-frequency cases should stand out during quick scanning.
-- Promote high-frequency cases into fixed pressure checks and rerun them whenever related code, UI, context, or hooks change.
-- Keep entries compact. If the same information appears in a roadmap node, link to it instead of duplicating it.

package/references/task-case-template.md

@@ -1,63 +0,0 @@
-# Task Case Template
-
-Use task cases for realistic multi-step verification. A task case should simulate a full user or agent workflow and log phase-level checkpoints so failures identify the broken step. Test design is human-owned: Codex can draft a proposal, but a durable task case stays `proposed` until the user confirms it.
-
-```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
-- Blocker handling: credentials | external service | permissions | resource limits | network | destructive confirmation | user judgment | 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
-```
-
-Rules:
-
-- When the user explicitly asks to create, write, generate, design, or add a test/task case, begin the user-visible response with a compact intake line such as `测试创建识别：...` before proposing or implementing the case.
-- Prefer one task case with clear checkpoints over many disconnected bug-level scripts when the same workflow is being exercised.
-- Link bad cases to the checkpoint that catches them.
-- Keep the task case realistic enough to match actual product or agent usage.
-- Once a test is approved, automate it when it can be safely encapsulated. Future Codex turns should run the registered entry instead of reinterpreting the test design.
-- Automated approved tests should be registered in `.codex/context/test-hub/registry.json` or represented by this approved task-case file with `Run policy: every-dev-completion` and an executable `Entry command/prompt`.
-- At development completion, run the approved always-run set through `context_guard.py dev-complete --root <project>` instead of manually reconstructing each test.
-- Automated task cases should clean temporary files after full success and preserve the smallest useful evidence on failure.
-- If the automated case fails, Codex should analyze the failed phase/checkpoint, record or update the bad case, fix in scope, and rerun the same approved test until it passes or a non-actionable blocker is reached.
-- If blocked by credentials, unavailable services, permissions, hardware/resource limits, network, destructive-risk confirmation, or user-only judgment, stop and ask or warn the user with the blocker and evidence path.
-- Keep checkpoint logs concise and useful for localizing failure.
-- Keep the case in `proposed` state until the user confirms the design.
-- Once the user confirms the design, default `Run policy` to `every-dev-completion`; lower the cadence only when the user explicitly asks.
-- In goal mode, use human-approved task cases as phase gates and log phase progress; do not create broad new scripts or active task cases without confirmation unless the user explicitly asked for that exact test.

package/tests/BC-20260618-063.sh

@@ -1,116 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/context_guard.py}"
-
-python3 - "$SCRIPT" <<'PY'
-from __future__ import annotations
-
-import json
-import shutil
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-script = Path(sys.argv[1])
-root = Path(tempfile.mkdtemp(prefix="context-guard-branch-test-"))
-
-try:
-    subprocess.run(["python3", str(script), "init", "--root", str(root)], check=True, capture_output=True, text=True)
-    subprocess.run(["python3", str(script), "set-language", "--language", "zh", "--root", str(root)], check=True, capture_output=True, text=True)
-
-    ctx = root / ".codex" / "context"
-    (ctx / "index.md").write_text(
-        """# Context Index
-
-## Quick Scan
-
-- Current: CTX-20260618-main
-- Latest roadmap node: NODE-20260618-001
-- Hot bad-case tags: none
-- Resume candidate: none
-
-## Current
-
-- ID: CTX-20260618-main
-- Title: 主线任务
-- State: current
-- Folder: `.codex/context/tasks/CTX-20260618-main/`
-- Last updated: 2026-06-18
-- Summary: 正在推进主线任务。
-- Next step: 继续主线。
-
-## Parked / Resume Candidates
-
-None.
-
-## Archived
-
-None.
-""",
-        encoding="utf-8",
-    )
-    (ctx / "roadmap.md").write_text(
-        """# Context Roadmap
-
-## Nodes
-
-### NODE-20260618-001: 主线起点
-
-- Date: 2026-06-18
-- Status: done
-- Level: major
-- Branch: Main
-- Parent: none
-- Task: `CTX-20260618-main`
-- Outcome: 主线已经建立。
-- Decision / reason: 作为支线父节点。
-- Avoid going back: 不要把支线写回主线。
-- Next: 等待支线。
-- Linked bad cases: none
-- Test chain: none
-""",
-        encoding="utf-8",
-    )
-
-    result = subprocess.run(
-        [
-            "python3",
-            str(script),
-            "create-branch-task",
-            "--root",
-            str(root),
-            "--title",
-            "后端状态机设计",
-            "--branch",
-            "后端状态机",
-            "--parent-node",
-            "NODE-20260618-001",
-        ],
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-
-    output = result.stdout + result.stderr
-    assert "CTX-" in output, output
-    assert "NODE-" in output, output
-
-    index = (ctx / "index.md").read_text(encoding="utf-8")
-    roadmap = (ctx / "roadmap.md").read_text(encoding="utf-8")
-    exports = json.loads((ctx / "roadmap" / "roadmap.json").read_text(encoding="utf-8"))
-
-    assert "- Current: CTX-20260618-main" not in index, index
-    assert "后端状态机设计" in index, index
-    assert "主线任务" in index and "resume-candidate" in index, index
-    assert "- Branch: 后端状态机" in roadmap, roadmap
-    assert "- Parent: NODE-20260618-001" in roadmap, roadmap
-    assert "- Task: `CTX-" in roadmap, roadmap
-    assert any(route["branch"] == "后端状态机" for route in exports["routes"]), exports
-
-    task_dirs = list((ctx / "tasks").glob("CTX-*"))
-    assert any((path / "context.md").exists() and "后端状态机设计" in (path / "context.md").read_text(encoding="utf-8") for path in task_dirs), task_dirs
-finally:
-    shutil.rmtree(root, ignore_errors=True)
-PY

package/tests/BC-20260618-065.sh

@@ -1,66 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/context_guard.py}"
-ROOT="$(mktemp -d "${TMPDIR:-/tmp}/context-guard-marker-test-XXXXXX")"
-trap 'rm -rf "$ROOT"' EXIT
-
-python3 "$SCRIPT" init --root "$ROOT" >/dev/null
-python3 "$SCRIPT" set-language --language zh --root "$ROOT" >/dev/null
-
-CTX="$ROOT/.codex/context"
-cat > "$CTX/roadmap.md" <<'MD'
-# Context Roadmap
-
-## Nodes
-
-### NODE-20260618-001: 标记测试节点
-
-- Date: 2026-06-18
-- Status: done
-- Level: major
-- Branch: Main
-- Parent: none
-- Task: `CTX-20260618-marker`
-- Outcome: 检查问题案例标题行标记布局。
-- Decision / reason: 标记不能单独占一行。
-- Avoid going back: 不要把状态点放在标题前面。
-- Next: none
-- Linked bad cases: BC-20260618-999
-- Test chain: none
-MD
-
-cat > "$CTX/bad-cases.md" <<'MD'
-# Bad Case Register
-
-## Active Cases
-
-### BC-20260618-999: 这是一个很长的问题案例标题用于触发换行但标记不能单独成行
-
-- Status: resolved
-- First observed: 2026-06-18
-- Last checked: 2026-06-18
-- Scope: roadmap marker layout
-- Context task: `CTX-20260618-marker`
-- Roadmap nodes: NODE-20260618-001
-- Tags: #roadmap-ux
-- Frequency: repeated-2
-- Phenomenon: 状态点和频率点不应该单独一行。
-- Trigger / reproduction: 生成 roadmap 并检查 badcase-head。
-- Root cause: 标记位于标题前，窄列时容易变成单独一行。
-- Fix method: 将标记移到标题右侧的 inline marker 容器。
-- Guard / verification: 本脚本检查 HTML 结构。
-- Reusable guard path: none
-- Test chain: none
-MD
-
-python3 "$SCRIPT" show-roadmap --root "$ROOT" >/dev/null
-HTML="$CTX/roadmap/roadmap.html"
-
-grep -q 'class="badcase-markers"' "$HTML"
-grep -q '.badcase-head { display: grid; grid-template-columns: minmax(0, 1fr) auto;' "$HTML"
-if grep -q '<div class="badcase-head"><span class="status-dot' "$HTML"; then
-  echo "badcase marker still starts a separate title row" >&2
-  exit 1
-fi
-grep -q '<a class="detail-link" href="#case-1">' "$HTML"

package/tests/BC-20260626-080.sh

@@ -1,48 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/context_guard.py}"
-ROOT="$(mktemp -d "${TMPDIR:-/tmp}/context-guard-readable-map-XXXXXX")"
-trap 'rm -rf "$ROOT"' EXIT
-
-python3 "$SCRIPT" init --root "$ROOT" >/dev/null
-python3 "$SCRIPT" set-language --language zh --root "$ROOT" >/dev/null
-
-CTX="$ROOT/.codex/context"
-cat > "$CTX/roadmap.md" <<'MD'
-# Context Roadmap
-
-## Nodes
-
-### NODE-20260626-001: 主线起点
-
-- Date: 2026-06-26
-- Status: done
-- Level: major
-- Branch: Main
-- Parent: none
-- Outcome: 这是一段很长的主线摘要，过去会直接显示在多路线概览卡片里，让路线图看起来像卡片墙而不是路线骨架。
-- Next: none
-- Linked bad cases: none
-
-### NODE-20260626-002: 支线入口
-
-- Date: 2026-06-26
-- Status: done
-- Level: major
-- Branch: 可读性支线
-- Parent: NODE-20260626-001
-- Outcome: 这是一段很长的支线摘要，应该留在详情里，而不是占据概览卡片的主要视觉空间。
-- Next: none
-- Linked bad cases: none
-MD
-
-python3 "$SCRIPT" show-roadmap --root "$ROOT" >/dev/null
-HTML="$CTX/roadmap/roadmap.html"
-
-grep -q 'class="route-stack branch-map"' "$HTML"
-grep -q '.track-grid.route-only {' "$HTML"
-grep -q 'grid-auto-columns: minmax(180px, 230px);' "$HTML"
-grep -q '.branch-map .summary {' "$HTML"
-grep -q 'display: none;' "$HTML"
-grep -q -- '-webkit-line-clamp: 3;' "$HTML"

package/tests/BC-20260626-081.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/context_guard.py}"
-ROOT="$(mktemp -d "${TMPDIR:-/tmp}/context-guard-hidden-details-XXXXXX")"
-trap 'rm -rf "$ROOT"' EXIT
-
-python3 "$SCRIPT" init --root "$ROOT" >/dev/null
-python3 "$SCRIPT" set-language --language zh --root "$ROOT" >/dev/null
-
-CTX="$ROOT/.codex/context"
-cat > "$CTX/roadmap.md" <<'MD'
-# Context Roadmap
-
-## Nodes
-
-### NODE-20260626-001: 可点击路线节点
-
-- Date: 2026-06-26
-- Status: done
-- Level: major
-- Branch: Main
-- Parent: none
-- Outcome: 这个节点的详细概括只能在点击节点后显示，不能默认铺在 roadmap 下方。
-- Next: none
-- Linked bad cases: none
-MD
-
-python3 "$SCRIPT" show-roadmap --root "$ROOT" >/dev/null
-HTML="$CTX/roadmap/roadmap.html"
-
-grep -q '<a class="lane-link" href="#node-1">' "$HTML"
-grep -q '<section class="inline-details" hidden data-inline-details' "$HTML"
-grep -q 'function setupInlineDetails()' "$HTML"
-grep -q 'class="detail-card" id="node-1"' "$HTML"
-
-if grep -q '<section class="inline-details" aria-label="Roadmap details">' "$HTML"; then
-  echo "inline details are visible by default" >&2
-  exit 1
-fi