# Realign > Execute an enforcement-surface audit's findings behind an explicit per-item human gate. Consumes the findings artifact either producer wrote. It never scans or re-judges the surface itself. For each finding the operator accepts, it drives interview → explore and research → plan → implement through presence-gated skill composition, executing every removal down the rollback ladder: config-disable first, observe for a window with a stated end date, delete last with a recorded rationale. Unproven items route to a time-boxed ablation batch; security-class items surface the capped verdict's evidence and wait for the human's own call; remediation owned by an upstream or a forge control plane becomes a delegation rather than a local patch. Use when the ask is to act on an enforcement-surface audit's findings ('realign our enforcement surface', 'the audit says retire it, do it'), to retire or peel back automation already judged, or to start or advance an ablation window ('disable this gate and observe it'). This is th - Skill: `melodic-software/realign` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add melodic-software/realign` - Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/realign/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: melodic-software (https://skillmd.com/u/melodic-software) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/melodic-software/realign --- ## Repository context. Gather first Collect these with **individual** Bash calls, one command per call, never combined into a single invocation: - Branch, `git symbolic-ref --quiet --short HEAD` Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the `source-control` plugin's [worktree/reference/gather-block.md](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/source-control/skills/worktree/reference/gather-block.md), "The pre-compute block runs as one shell invocation". ## Pre-computed context - Today (UTC): !`date -u +%Y-%m-%d 2>/dev/null || echo "unknown (no date command)"` ## Purpose Execute what an `overengineering:audit` run found, one finding at a time, with the operator deciding each one. This is the **only** skill that mutates the surface under scrutiny, and the per-item gate below is the entire reason it is safe to point at a surface nobody has reviewed in a year. The method is **not restated here.** Read `${CLAUDE_PLUGIN_ROOT}/context/scrutiny-method.md` before executing anything: the rollback ladder (§11) that orders every removal, the protected classes and their cap (§7), UNPROVEN triage and its bounded batches (§8), ownership and out-of-repo custody (§12), the verdict ladder (§6) whose tokens the artifact carries, and the scope boundary (§10) that puts tests, review, type checking, and the build outside this work. The artifact's shape, its status vocabulary, its merge rules, and the durable judgment record belong to `${CLAUDE_PLUGIN_ROOT}/context/findings-artifact.md`. Every bare `§N` in this skill is a section of the scrutiny method, and a paraphrase of either document inside a proposal is a drift seed. ## The per-item gate **Nothing mutates without an explicit acceptance of that finding, from the operator, at the moment it is presented.** Say so in the run's opening line, then hold it literally: - **One finding, one acceptance.** Accepting finding A authorizes A's remediation and nothing else, not its neighbours, not the rest of its layer, not the obvious next one. - **Blanket approval is not the gate.** "Approve everything", "do whatever the audit says", and a standing authorization from earlier in the session are all declined, out loud, with an offer to walk the queue instead. A gate that a sentence can switch off was never a gate. - **Silence is not acceptance.** An unanswered finding stays `OPEN`; it does not become `REJECTED`, and it is not carried on a later item's yes. - **Item acceptance is scoped to the rung or act about to execute.** A yes at rung 1 of §11 authorizes the config-disable, not the deletion three rungs later; rung 3 asks again, after the window. - **Change approval shows the exact change before making it.** The file and the line, the config key and its new value, or the entry to be written, shown after the plan, approved before any write, then executed as shown, nothing adjacent. - **No operator present means present and stop.** In a dispatched, scheduled, or background run nobody can accept anything, so realign presents the queue and stops: no status transitions, nothing written anywhere. An absent operator is silence for every item at once. There is no unattended mode to pass, the audit takes that flag for its own intent disposition; realign has nothing it may do without the gate. **Both gates are required and neither substitutes for the other.** *Item acceptance* authorizes working this finding and the act named at that moment; *change approval* authorizes one exact edit. An acceptance given earlier is not an approval of the edit that later falls out of it. ## Before anything: load the artifact 1. **Resolve the branch identity, then the artifact home.** The branch call above yields a branch name or fails with no output (detached HEAD or no checkout). Read its exit status rather than assuming an identity. **`HEAD` is never accepted as a branch identity**, and neither is a failed call. Where the call fails, prefer a logical ref if the environment supplies one that names a branch, after the same normalize-then-validate steps `audit` uses (strip a leading `refs/heads/`, then `git check-ref-format --branch`, refuse `.` / `..` segments); name where it came from. **Otherwise stop**. See "An unresolved branch identity is its own refusal" below. With an identity in hand, resolve the home by running the whole rung order in `${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`. A hardcoded path reads where the audit never wrote, and that failure is indistinguishable from the audit never having run. 2. **No artifact → stop.** Report, visibly, that no findings artifact exists at the resolved home, name the two skills that produce one, `overengineering:audit` for a walk of the enforcement surface and `overengineering:justify` for a single artifact the operator points at, so an operator who wanted one document judged is not sent into a hundred-item walk to get it. Name the home resolved so the operator can tell "never audited" from "resolved elsewhere". **Do not scan, judge, or remediate anything on your own**. This skill has no evidence and no verdict of its own, so an improvised pass would put a mutation behind a gate with nothing behind it. 3. **Refuse a mismatched `branch:`**, naming both; **refuse an artifact whose `branch:` is absent, empty, or the literal `HEAD`**, naming which; and **refuse an unrecognized `schema:`**. `1` and `2` are both recognized. A `schema: 2` artifact additionally carries `mode`, `targets` on a targeted run, and `Basis` on every row a schema-2 run wrote; all three are **displayed with the finding and change no gating decision**. A row carried forward from a schema-1 run has no `Basis`, which is displayed as `not recorded (schema 1)` rather than inferred. Each with a visible message rather than guessing at the shape. The artifact's own frontmatter is what binds it to a branch; the directory it sits in is not evidence (the slug mapping is lossy). A `branch:` that carries no identity is not a match to be evaluated, it is the absence of the thing the check compares, so it takes the refusal branch and never the comparison. 4. **Read the evidence-availability assessment that leads the artifact, and never recompute it.** It changes what UNPROVEN means for every finding below it, and re-deriving it here would make a second record that can disagree with the first. 5. **A `Status` value outside the artifact's closed vocabulary** is reported and that finding is skipped, soft degradation, never a guess about what an unknown state meant. 6. **Surface a verdict that moved under a carried-forward judgment before anything else, and never act on it.** Read the flag whichever producer recomputed the row wrote on merge; never re-derive the trigger, since a second derivation here is a second answer that can disagree with the one on the artifact. What the flag means: an `ACCEPTED` finding now recomputed to `KEEP`, or a `REJECTED` one now recomputed to a retirement-direction verdict, means the evidence moved under a decision the operator already made. **Direction is not the only trigger:** it is set too where the recomputed verdict materially changes *what the acceptance authorized* without flipping direction, an `ACCEPTED` `DOWNGRADE` now recomputed to `CONSOLIDATE` authorizes a different act on a different artifact. Re-confirm the act before anything proceeds; the earlier yes was given to the old one. ## Arguments Parse `$ARGUMENTS`. **Finding ids**, and **layer names** from the artifact's layer vocabulary, narrow the queue to exactly those findings. Anything else is a free-text hint that orders the queue and is reported rather than dropped when it matches nothing. No argument widens the queue, and none replaces the gate. Bare invocation presents every finding awaiting a decision, in the artifact's own order; a queue too long for one sitting is said to be, not rushed, the statuses persist, so stopping halfway is a normal end to a run. ## The queue **A finding this skill cannot execute is presented, judged, and never remediated here.** The operator still decides it and the decision is still recorded; what is withheld is the ladder, not the judgment. Read each finding's `Layer`: where it is one of `decision-records`, `documents`, `components`, `dependencies` or `source`, this skill has no rollback ladder for it. Dispatch on the layer rather than on the `check` producer segment, because `check` is a hash input and never a serialized field, so it cannot be read back off an artifact; the layer partition that makes this sound is stated in `${CLAUDE_PLUGIN_ROOT}/context/findings-artifact.md`, section "Finding ids". The ladder in "Execution order" is enforcement-shaped, and its rung-1 fallback ("nothing registered or wired to disable" leaves deletion as the only remaining act) would turn a lane it does not understand into a deletion. So a row in one of those five layers is **displayed with its evidence, its verdict, and the owner named in that lane's boundary table, and no rung is offered**. Say so in one line where the finding would otherwise be gated, so the operator sees the finding rather than losing it. A lane's findings become executable here once a rollback ladder exists for its layers, and not before. **What such a row loses is the rung, not the decision**: the operator may still judge it `REJECTED`, per "Statuses this skill writes", which is why it is presented rather than merely listed. Present every finding in the artifact's order, those five layers included, and dispose of each by its current status. The rung is what the five layers do not get; the disposition below still runs for them. `REJECTED` is the outcome the missing ladder leaves, and `DELEGATED-EXTERNAL` stays available where the custody read placed the artifact upstream, since a delegation is a handoff rather than a rung: | Status | What this run does with it | |---|---| | `OPEN` | Present the verdict, its evidence, its cost, and the proposed rung; ask for a decision | | `ACCEPTED` | Remediation was authorized in an earlier run, re-confirm the rung about to execute, then continue | | `REJECTED` · `REALIGNED` | Nothing. Report it as already decided; re-asking is the noise the judgment record exists to stop | | `DELEGATED-EXTERNAL` | Report the delegation pointer and its state. Nothing local, ever | | `ABLATION-PENDING` | Gate and execute the rung-1 disable, then move to `ABLATION-ACTIVE` | | `ABLATION-ACTIVE` | Compare today against the recorded end date; before it, report the window as running and stop there | | `ABLATION-CONCLUDED-RETIRE` | Rung 3, behind its own acceptance | | `ABLATION-CONCLUDED-KEEP` | Confirm the mechanism is re-enabled, close as KEEP, and offer the durable judgment entry | ## Per accepted finding: the four movements Interview → explore and research → plan → implement. Each composes a sibling skill **when its plugin is installed** and runs the documented inline fallback when it is not. Check presence, take the fallback, and **say which one ran**. A silent skip is indistinguishable from a step that was never needed. Record the presence answer on the finding. Every skill in the `Composition` column is invoked via the Skill tool. | Movement | Composition (presence-gated) | Inline fallback when absent | |---|---|---| | **Interview**. Settle intent, constraints, and what "done" means for this item | `/planning:interview`, when the planning plugin is installed | Ask the same questions inline as one small numbered set, recommendation first. The questions are the substance; only the mechanics are lost | | **Explore**. What the mechanism touches, where it is wired, what depends on it | `/discovery:explore`, when the discovery plugin is installed | Read the artifact, its registration surface, and its call sites directly, and list the blast radius in the response before proposing anything | | **Research**. Is the native or existing mechanism the rediscovery names real, and current | `/discovery:research`, when the discovery plugin is installed | Check the current official documentation of the proposed replacement yourself and record the check with its date (§5 requires the date, not the memory) | | **Plan**. The rung, the exact edit, the reversal, the observation window | `/planning:plan`, when the planning plugin is installed | Write the plan in the response. Goal, rung, blast radius, how it is reversed, and get it approved before any edit | | **Implement**. Make the change | `/implementation:implement`, when the implementation plugin is installed | Make the change directly against the approved plan, one rung at a time, stopping at the same gates | Run the movements the finding actually needs, a one-key config disable with a settled intent needs no research pass. "Skipped research: the rediscovery names a mechanism already in this repo" is a judgment recorded; skipping it wordlessly is not. ## Execution order. The rollback ladder §11 governs, in order, and the finding records the rung reached: 1. **Config-disable**, wherever a kill switch exists. Check §11's trap first: an "unset means enabled" fallback re-enables a mechanism that was disabled by removing a key, so make the off state explicit and confirm the disable took effect rather than assuming the edit was the effect. 2. **Observe** for the consumer's configured window, with **its end date written on the finding**. A window with no end date is an abandonment wearing an experiment's clothes, and the date belongs on a durable pointer too, the artifact can be gone before the date arrives. 3. **Delete, with the rationale recorded** in the change description: the evidence, the observation result, and what re-adds it. Preserve the re-add surface where one exists. **Withdrawal is a normal outcome, not a failure.** A window showing the mechanism load-bearing ends at rung 1 with it re-enabled and the finding closed as KEEP, carrying the evidence the window produced. Say so when proposing the ladder, it is what makes rung 1 cheap to accept. **When rung 1 is inapplicable.** Nothing registered or wired to disable: a copy nothing reads, a claim in a document, a lane nothing requires. The presentation records *"rung 1 inapplicable: ``"* rather than inventing a disable, and says why rung 2 is uninformative too (disabling what never fires produces no signal). A **reversible non-rung remediation**, correcting a false claim or registering the copy that should have been wired, is then a valid proposal, recorded as one under its own item acceptance. And where the only remaining act is **deletion**, the acceptance must name the deletion explicitly: the ladder's cheap first rung is not there to soften it (see the gotcha below, an accepted finding is not an accepted deletion). **CONSOLIDATE** ends in removing the **redundant copy** once the survivor is named. Where that copy is live the ladder applies unchanged: disable, observe under the survivor, delete. Where it is inert, rung 1 has nothing to disable and rung 2 nothing to observe, route it by the rule above, deletion named in the acceptance. ## UNPROVEN findings. The ablation track An UNPROVEN verdict is not an authorization to disable. Route it to §8's track: take the head of the carry-cost ranking the audit recorded, propose **one bounded batch** an operator can actually attend to, name an owner per item (§12, ownerless is not a terminal state), set one window with its end date, and record a durable pointer so the batch survives the artifact. Each item still passes the per-item gate individually. Items below the batch keep their ranking and wait for the next window. Dozens of concurrent windows destroy attribution and re-check nothing, and protected and intentionally-dormant items (§7) never enter a batch at all. ## Protected findings A `FLAG-FOR-HUMAN` finding is a question, not a task. Present the capped retirement-direction verdict it would otherwise have carried, the evidence in full, the protected class that matched, and the rule that matched it, then **stop and wait for the operator's own call**, on that item, in their words. Never retire a protected mechanism on this skill's own reasoning, and never reach the same end by routing it into an ablation batch. Where the operator overturns the classification, that is their decision to record, and the consumer's tracked configuration is where it belongs. ## Out-of-repo custody. Delegate, never patch locally Where the audit's custody read placed the artifact upstream, organization-level policy, a managed or synced copy, a shared workflow this repo only references, a forge control plane, §12 makes the remediation a **delegation**. Produce the delegation artifact, an upstream change request, an administrator issue, or written instructions handed to the owner, carrying the finding's evidence and the proposed rung, and set the status to `DELEGATED-EXTERNAL` with its pointer. **Never edit the out-of-repo surface in place and never patch a managed copy locally**: the next sync reverts the patch and leaves a report claiming the work is done. ## Statuses this skill writes **Re-read the artifact from disk immediately before every `Status` write, and merge against that copy.** The load in "Before anything" happens before a per-item interview that can run long, and another producer may write in that window; the shared contract binds this skill to the re-read for that reason. A `Status` written onto a copy loaded minutes ago discards whatever landed in between. This skill is the artifact's only writer of `Status`, and it writes one only as the outcome it names actually happens, never ahead of the operator's yes. `ACCEPTED` on acceptance; `REJECTED` when the operator judges the finding and keeps the mechanism; `REALIGNED` when the change has landed; `DELEGATED-EXTERNAL` with its pointer; the `ABLATION-*` states as a batch moves through its window. **A justification-layer row takes `REJECTED` like any other.** The five layers get no rollback rung here, but `REJECTED` is a judgment rather than an execution: it records that the operator read the finding and kept the artifact, and it mutates nothing outside the record. Withholding it would leave those rows permanently `OPEN`, re-presented on every run, and would deny them the durable judgment entry that only `REJECTED` and `ABLATION-CONCLUDED-KEEP` qualify for. What is withheld for those layers is the ladder, never the operator's ability to decide. What each one means is the contract's, not this skill's. Leave every other field exactly as the audit computed it, rewriting a verdict here puts this skill's opinion into the audit's record. ## The durable judgment record A `REJECTED` finding and an `ABLATION-CONCLUDED-KEEP` one are judgments worth more than the memory-tier artifact a branch switch or a reclaimed container loses. **Offer** to persist each as a suppression entry in the consuming repo's tracked `.claude/overengineering.md`, offered, not taken: - **Show the exact entry before writing it**, and write only on an explicit yes, under the same per-item gate that authorized the remediation. - **The `reason` is the operator's own words.** Ask for them. Audit prose recycled into that field is not a stated reason, and an entry nobody can review is an entry nobody can retire. - **The team-tracked layer, not a personal overlay**. A personal-layer entry does not suppress, so writing one there would leave the operator believing a judgment is in effect when it is not. - Entry keys, the constituents-authoritative rule, and the layering are owned by `${CLAUDE_PLUGIN_ROOT}/reference/consumer-config.md`. A `REALIGNED` finding needs no entry: the mechanism is gone, so it cannot recur. ## An unresolved branch identity is its own refusal The branch-match check in "Before anything" step 3 protects the one thing this skill cannot recover from: executing one ref's findings against a different ref's surface. That check is only as good as the two identities it compares, and `git rev-parse --abbrev-ref HEAD` answers the literal string `HEAD` on a detached checkout, which compares equal to itself, so a `HEAD`-to-`HEAD` comparison passes by construction and authorizes mutations from an artifact that may describe another ref entirely. Scheduled and dispatched runners commonly check out detached, so this is an ordinary condition, not an exotic one. The branch call therefore uses `git symbolic-ref`, which fails rather than inventing a name, matching the `audit` and `delta` lanes. **Two distinct unresolved states both refuse, and neither may reach the comparison:** - **This checkout has no branch identity**. The branch call failed and no logical ref was supplied. Stop before reading the artifact. Say so plainly: *"Detached checkout, no logical ref supplied; no branch identity, so the artifact's branch cannot be verified and nothing will be executed."* Nothing is presented as a queue, no status transitions, nothing written anywhere. - **The artifact carries no branch identity**. Its `branch:` is absent, empty, or the literal `HEAD`. Refuse it by name, and say that `overengineering:audit` declines to write an artifact without an identity, so one carrying `HEAD` did not come from this plugin's audit as it stands. Do not repair the field, and do not fall back to the directory it sits in: the slug mapping is lossy, so the home is not evidence of which ref the findings describe. Refusing costs a re-run on an attached checkout. Passing costs a mutation nobody can attribute to a surface, and this is the only skill in the plugin that mutates that surface, so the asymmetry is not close. **Never fall back to `HEAD`, to the commit sha, or to the home's slug to manufacture the missing side of the comparison.** ## Next `/verification:confirm`. The finding stays open until the landed change is verified. ## Gotchas - **`HEAD` is not a branch name.** A detached checkout makes `rev-parse --abbrev-ref` answer `HEAD`, which compares equal to itself and slips a cross-ref artifact through the branch-match refusal. An unresolved identity, on either side of that check, refuses; it never compares. - **An accepted finding is not an accepted deletion.** Acceptance authorizes the rung on the table at that moment; carrying it to rung 3 is how a reversible change becomes an irreversible one that nobody agreed to. - **Disable the copy the runtime actually reads.** Where a guard exists in both a local and a packaged form, disabling the inert copy changes nothing and reports as done, confirm which one the live configuration registers first. - **Do not touch what the finding is not about.** A formatting fix, a stale comment, or an obvious adjacent tidy inside the same file is outside the acceptance that was given. - **A finding you realigned vanishes from the next audit.** Its artifact is gone, so the re-run records it under closed-since-last-run instead, the contract working, not a loss. - **Never argue a quality-enabling practice onto the ladder** (§10). Tests, review, type checking, and the build are outside this method, and so is the record-keeping that makes the evidence tiers readable at all, retiring it would make the next audit weaker than this one.