[hyperpolymath]

What & why

First v0.3 roadmap item: a policy-driven remediation surface. plasma check tells you what's wrong; plasma fix proposes and applies the corrections. This establishes the Action/Plan/apply architecture that later increments extend.

Design

Same purity split as the evaluator:

• plan(policy, evaluation, ctx) -> Plan is pure (plasma-engine/src/action.rs). Each violation becomes either a mechanical Action or a ManualItem with a reason — nothing is silently unfixable. FixContext injects license/author/year (never clock-derived), so planning stays deterministic.
• apply(plan, root, opts) -> ApplyOutcome is the IO boundary (plasma-engine/src/apply.rs, the counterpart to facts.rs). It writes <file>.bak backups first (unless --no-backup) and is idempotent — a file that already has a header is skipped, not double-written.

Action vocabulary (v0.3): AddSpdxHeader (the one auto-action). Missing required files (LICENSE/README), unparsable headers, and prohibitions route to manual. The Action enum and Plan shape are the stable contract; CreateFile/UpdateField come later.

Relationship to plasma audit --fix: that's the license-specific header tool; plasma fix is the general policy-remediation surface driven by engine findings — headers are just its first action class.

CLI

plasma fix [PATH] [--policy F] [--license L] [--author A] [--apply] [--no-backup] [--format human|json]

Dry-run by default (prints the plan; exit 1 when actions are pending, so CI can gate on a clean tree). --apply makes the changes (exit 0 unless an action errored).

$ plasma fix .            # on this repo
Nothing to fix.

Tests & verification

• plasma-engine: 7 new unit tests (planner mapping + apply/backup/idempotency/error). 77 tests total, all green.
• tests/fix_selftest.rs: 4 CLI integration tests (dry-run no-write, apply+backup, idempotent re-run, json plan).
• cargo fmt --all -- --check and cargo clippy --workspace --all-targets -- -D warnings clean.
• plasma check . still passes (0 violations); plasma fix . reports "Nothing to fix."

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run -- fix .                 # dry-run

Docs

docs/engine-v0-design.adoc gains an "Action planner" section (plan pure / apply IO, action vocabulary); docs/cli-design.adoc documents plasma fix; ROADMAP.adoc checks off delivered items; CHANGELOG.md [Unreleased]; Justfile gains a fix recipe.

Out of scope (later v0.3 increments)

CreateFile/UpdateField actions, overlay modify-rules/override-rules semantics, content facts + file-matches-pattern.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JSVSF9HhKUhDrEV4xkMEXq

---

Generated by Claude Code