Code Change Guardian

Code Change Guardian

Protect a code change from proposal through proof. Lead with a native Markdown report, distinguish evidence from inference, and never claim safety without verification.

Select a mode

• impact: Analyze a proposed change without editing project files. Use this by default when the user asks what could break or says not to change code.
• refactor: Analyze, request approval, capture baseline behavior, edit incrementally, and verify behavior preservation.
• verify: Inspect an existing diff, branch, commit, or pull request and determine what it may break. Do not rewrite it unless asked.

If the request is ambiguous, start in impact mode. State the selected mode in the report.

Create the report first

Create CODE-CHANGE-REPORT.md in the repository root, unless the user specifies another path. Write the report in English. Keep updating the same file throughout the task so it remains the single source of truth inside Codex.

Use scripts/collect_change_context.mjs for the initial repository snapshot when Node.js is available:

node <skill-dir>/scripts/collect_change_context.mjs \
  --root <repository-root> \
  --mode impact \
  --request "<requested change>" \
  --out .codex/change-guardian/context.json

Read analysis-playbook.md before tracing impact. Read risk-model.md before scoring risks. Populate a report model following report-schema.md, then render it:

node <skill-dir>/scripts/generate_report.mjs \
  --input .codex/change-guardian/report.json \
  --out CODE-CHANGE-REPORT.md

Do not wait until the end to create the report. A partial, clearly labeled report is preferable to an invisible analysis.

Phase 1: Establish scope and baseline

1. Resolve the repository root and inspect local instructions.
2. Record the requested outcome, explicit non-goals, selected mode, current branch, HEAD, and dirty working-tree files.
3. Preserve unrelated user changes. Never discard or overwrite them.
4. Discover relevant validation commands from package manifests, CI configuration, build files, and repository docs.
5. Run only proportionate read-only baseline checks. Record exact commands, results, duration when available, and skipped checks with reasons.

Phase 2: Map the blast radius

Start from the requested symbol, file, endpoint, schema, dependency, or current diff. Trace outward using repository-native tools and rg:

1. Identify definitions, imports, exports, callers, consumers, registrations, routes, schemas, configuration, persistence, side effects, and tests.
2. Inspect dynamic and implicit connections: string keys, reflection, dependency injection, event names, environment variables, generated code, serialization, migrations, feature flags, native boundaries, and public package exports.
3. Use Git history only when it adds evidence: files that change together, prior regressions, reversions, and ownership hotspots.
4. Classify each affected surface as direct, transitive, contractual, operational, or test-only.
5. Attach evidence to every material claim with a file path, symbol, command result, diff hunk, or commit. Label unsupported conclusions Inference or Unknown.

Do not treat a text search as a complete dependency graph. Explicitly list blind spots.

Phase 3: Model failure and risk

For each credible failure mode, record:

• trigger and affected user or system behavior;
• evidence and impacted files;
• likelihood, severity, detectability, and blast-radius scores;
• total risk tier using risk-model.md;
• prevention, detection, rollback, and remaining uncertainty.

Prioritize behavioral and contract risks over aesthetic code-quality observations.

Phase 4: Build a safe change plan

Produce an ordered plan with small reversible steps. For each step include files, preserved behavior, validation, rollback boundary, and prerequisites.

In impact mode, stop after the report and recommend the next safest action.

In refactor mode, pause before editing and request explicit approval for the proposed file scope and verification plan. Analysis does not authorize implementation.

Phase 5: Preserve behavior and change incrementally

After approval in refactor mode:

1. Add or identify characterization tests for behavior that is important but insufficiently protected.
2. Capture baseline outputs for observable contracts when tests are impractical.
3. Make one coherent change at a time with recoverable checkpoints.
4. Run the narrowest relevant checks after each step.
5. Stop and update the report if the observed impact contradicts the plan or unrelated user changes overlap the target.

Do not call a feature change a refactor. If externally observable behavior intentionally changes, document the changed contract and obtain approval.

Phase 6: Verify and conclude

Run validation in layers: focused tests, contract or integration tests, type checking and linting, build, then broader suites when proportionate. Compare baseline and final behavior.

Update CODE-CHANGE-REPORT.md with:

• final verdict: SAFE TO PROCEED, PROCEED WITH CONDITIONS, NOT SAFE YET, or INCONCLUSIVE;
• what was analyzed or changed;
• proof ledger with exact commands and results;
• residual risks, skipped checks, blind spots, and rollback plan;
• links to the most important local files.

Use SAFE TO PROCEED only when all high-risk paths have relevant passing evidence and no material unknown remains. Passing tests alone never prove universal safety.

Report quality rules

• Keep the executive summary useful without reading the rest.
• Include at least one compact impact table and one risk table.
• Include a Mermaid impact map only when it clarifies three or more relationships.
• Prefer clickable repository-relative paths in the report.
• Never fabricate coverage, call graphs, test results, or Git history.
• Separate Observed, Inferred, and Unknown evidence.
• Make the file readable as a decision artifact, not a raw scanner dump.