Compliance · stage 3 of 5

Remediate

Ask gate

Implement controls, fix gaps, update configurations and policies

Remediate

Take the ranked gap list and close the gaps. This is the build-class stage of the compliance lifecycle: units are discrete pieces of executable work — config changes, code changes, policy authorship — each with concrete acceptance criteria and a way to confirm the change actually addresses the gap.

Scope

Implementing the technical and governance changes that satisfy the open controls, and recording how each change is verified. Remediate decides how to close each gap and prove it closed — not whether the gap was correctly graded (that's a revisit to assess) and not how the evidence is packaged for the auditor (that's document).

What to do

  • Trace every change back to the specific gap and control it closes; leave no gap addressed by guesswork.
  • Pair each technical acceptance criterion with an executable verify-command, and map each policy clause to the control it satisfies.
  • Build changes that are verifiable in isolation, so closure is demonstrable rather than asserted.
  • Keep technical and governance remediation distinct even when one gap needs both.

What NOT to do

  • Don't re-grade a control or reopen the scope boundary — a wrong finding is a revisit upstream, not a quiet reinterpretation here.
  • Don't assemble the auditor-facing evidence package — that's the document stage.
  • Don't claim a gap closed without a verify-command or a clause-to-control mapping that proves it.
  • Don't add changes the gap list doesn't call for.

How the engine runs this stage

1Elaborate

autonomous · plan the work, fan out discovery, declare outputs

Inputs consumed

gap-reportfrom Assess

Discovery fan-out

knowledge artifactRemediation LogTrack every gap from identification through resolution. This output drives the document stage's evidence collection.

Remediation Log

Track every gap from identification through resolution. This output drives the document stage's evidence collection.

Content Guide

Structure the log for traceability:

  • Remediation summary — overview of resolved/in-progress/deferred counts
  • Per-gap remediation — each gap with:
    • Original gap reference (from gap report)
    • Remediation approach taken
    • Changes made (code, config, policy references)
    • Verification method and results
    • Residual risk (if any)
  • Policy inventory — new or updated policies with ownership and review schedule
  • Configuration changes — committed changes with references to gaps addressed
  • Deferred items — gaps accepted as risk with business justification

Quality Signals

  • Every gap from the assessment has a remediation entry or documented deferral
  • Changes are traceable — each remediation references the specific gap it addresses
  • Verification evidence confirms the control now meets the requirement
  • Deferred items have explicit risk acceptance with business justification

Phase guidance

phase overrideELABORATION- "Each remediated control has a test or verification procedure confirming it now meets the requirement"

Remediate Stage — Elaboration

Criteria Guidance

Good criteria — concrete and verifiable

  • "Each remediated control has a test or verification procedure confirming it now meets the requirement"
  • "Policy documents follow the framework's required structure and cover all mandatory sections"
  • "Configuration changes are committed with traceability back to the specific gap they address"

Bad criteria — vague (no clear check)

  • "Gaps are fixed"
  • "Policies are written"
  • "Controls are implemented"

Outputs produced

output templateRemediation LogRecord of all remediation actions taken to address compliance gaps.

Remediation Log

Record of all remediation actions taken to address compliance gaps.

Expected Artifacts

  • Control implementations -- each remediated control with verification evidence
  • Policy documents -- drafted policies mapped to controlling requirements
  • Configuration changes -- committed changes with traceability to specific gaps
  • Remediation tracker -- each gap from identification through resolution with completion evidence

Quality Signals

  • Every critical and high-risk gap has remediation implemented
  • Each remediation includes verification evidence confirming the control is now met
  • Policy documents follow the framework's required structure
  • Configuration changes reference the specific gaps they address

2Review

pre-execute · agents audit the planned spec before any code lands
review agentEffectivenessThe agent **MUST** verify that every remediation in `REMEDIATION-LOG.md` actually closes the gap it claims to close — root cause addressed, change reproducible, verify-command passing, enforcement in place. Surface-only fixes are how gaps re-open in the next assessment.

Mandate: The agent MUST verify that every remediation in REMEDIATION-LOG.md actually closes the gap it claims to close — root cause addressed, change reproducible, verify-command passing, enforcement in place. Surface-only fixes are how gaps re-open in the next assessment.

Check

The agent MUST verify, filing feedback for any violation:

  • Gap-to-remediation traceability — every gap from GAP-REPORT.md (above accepted-risk threshold) has a corresponding entry in REMEDIATION-LOG.md. Gaps without remediation are silent — they must be explicit (planned for next cycle, accepted with documented rationale, OR closed with this remediation).
  • Root-cause depth — each remediation names the root cause and addresses it, not just the symptom. A surface-only fix re-opens the gap predictably.
  • Reproducible change — each remediation cites the concrete artifact of the change (commit SHA, config file path, policy document version). "I clicked through the console" is not reproducible.
  • Verify-command exists and passes — every acceptance criterion is paired with a concrete verify-command that returns a clear pass / fail signal. The command's output (or hash) is cited or linked.
  • Verify-command is honest — the command actually exercises the control in the bound environment; synthetic-success in dev does not evidence production effectiveness.
  • Policy ↔ practice alignment — for governance remediations, the published policy matches the actual operational practice. Aspirational policies fail the next audit.
  • Enforcement named — each policy clause is paired with an enforcement mechanism (technical control or attestation cadence). Decorative policies do not satisfy controls.
  • Monitoring against drift — remediations include the alerting / monitoring / review-cadence that prevents the gap from recurring. One-shot fixes drift.

Common failure modes to look for

  • A gap closed by a code change that addresses only one of multiple instances of the same root cause (one application's auth flow fixed; the other three still vulnerable)
  • A remediation with a verify-command that doesn't actually run against the bound environment (synthetic test in CI that passes by mocking the very thing the control is supposed to enforce)
  • A policy written and "published" with no enforcement mechanism — the next audit sees the policy and the violations side-by-side
  • A configuration change applied via console / manual edit, with no infrastructure-as-code path that makes the next-created resource inherit the setting
  • Stale credentials rotated without removing the root cause (the next set of credentials will leak through the same channel)
  • A remediation log entry that cites a ticket or PR that hasn't actually merged / shipped (claimed-done before actually-done)
  • A remediation that closes the surface gap but introduces a new gap (over-permissive IAM "fix" that grants more than the control allows)
  • A gap acknowledged but quietly moved to "next cycle" without a documented risk acceptance — silent deferrals are how audit findings repeat

3Execute

per-unit baton · Remediation Engineer → Policy Writer → Verifier
hat 1Policy WriterDraft or update the governance artifacts (policies, procedures, standards) required by the failed control. Where the `remediation-engineer` closes technical gaps, you close governance gaps — the documentation that describes the practice, who owns it, when it's reviewed, and how exceptions are handled. The policies you write must reflect actual practice; aspirational policies that nobody follows fail the next assessment.

Focus: Draft or update the governance artifacts (policies, procedures, standards) required by the failed control. Where the remediation-engineer closes technical gaps, you close governance gaps — the documentation that describes the practice, who owns it, when it's reviewed, and how exceptions are handled. The policies you write must reflect actual practice; aspirational policies that nobody follows fail the next assessment.

You produce the governance-remediation entries in the intent-scope REMEDIATION-LOG.md and the policy documents themselves (location depends on project overlay — typically a docs / policies tree).

Process

1. Read your inputs

  • The specific gap entry from GAP-REPORT.md this unit closes
  • The control's intent
  • Any technical changes the remediation-engineer made on the same gap — your policy describes the practice; the practice must match the implementation
  • The unit's acceptance criteria
  • The project's existing policy library if one is available (consistency in tone, structure, ownership models matters)

2. Match policy to practice

Before drafting, confirm what the team actually does. A policy that says "rotate keys every 30 days" when the team rotates every 90 is worse than no policy — the audit finds the divergence and the gap becomes "policy / practice mismatch" which is harder to close than the original gap.

Where there's no current practice, draft the policy in close coordination with the team that will own it. The policy is the commitment; an unowned commitment is not a control.

3. Structure each policy

A complete policy artifact typically includes:

  • Title and scope — what the policy covers and what's excluded
  • Owner — the role accountable for the policy (a role, not a person; people change)
  • Effective date and review cadence — when it took effect; when it's next reviewed
  • Mapped controls — every control this policy is intended to satisfy, by framework + control id
  • Policy statements — the actual rules, written as enforceable assertions ("All production database access MUST be brokered through the bastion service" — not "We aim to limit production access")
  • Procedures — how the rules are operationalized (who does what, with what tooling)
  • Exceptions — the documented process for granting / tracking exceptions (no policy survives without one; an exception-less policy quietly accumulates undocumented violations)
  • Enforcement — how compliance with the policy is monitored (the technical control that proves the policy is followed)

4. Map every clause to a control

The auditor will ask "which control does this policy satisfy?" — answer it in the policy itself. A policy that doesn't map to a control is either out-of-scope (don't write it now) or covering a control that didn't make it into scope (fix the scope, not the policy library).

Suggested table at the top of each policy:

ControlFrameworkSection of this policy
CC6.1SOC 2§3 Access Control
A.9.2ISO 27001§3 Access Control, §5 Access Review

5. Verify enforceability

For each policy statement, identify the technical control or operational check that proves the statement is followed. If there is no enforcement mechanism, either:

  • Add one (route a follow-up gap to remediation-engineer)
  • Mark the statement as manual / attestation-only with the attestation cadence and owner

A policy statement with no enforcement is decorative. Decorative policies do not pass audit.

6. Append to the log

For each governance remediation, append to REMEDIATION-LOG.md:

### Remediation: CC1.4 background-check policy gap

**Gap reference:** GAP-REPORT.md → CC1.4 personnel background-check evidence missing
**Root cause:** No documented policy; HR had ad-hoc practice; no record of who was checked or when
**Change:** Authored `policies/personnel-security.md` covering pre-hire screening, role-based check tiers, exception process, and annual review
**Mapped controls:** CC1.4 (SOC 2), A.7.1.1 (ISO 27001)
**Enforcement:** HRIS workflow gates `start-date` on completed background-check record; quarterly HR attestation
**Date effective:** 2026-05-12
**Owner:** Head of People

7. Hand off

When every governance gap has a published policy that maps to controls, names enforcement, and lists owner + cadence, hand off to verifier.

Anti-patterns (RFC 2119)

  • The agent MUST NOT write aspirational policies that don't reflect actual practice — the audit will find the divergence
  • The agent MUST NOT copy boilerplate policies without tailoring to the organization's actual systems, roles, and practices
  • The agent MUST map every policy clause to the specific control(s) it satisfies
  • The agent MUST NOT publish a policy without a named owner role and a review cadence
  • The agent MUST NOT write policies so vague they cannot be audited ("appropriate access", "regular reviews", "as needed")
  • The agent MUST name the enforcement mechanism for every policy statement OR mark the statement attestation-only with cadence + owner
  • The agent MUST NOT introduce a policy whose enforcement requires unimplemented technical work without filing a follow-up gap
  • The agent MUST NOT omit the exceptions process — a policy without an exceptions process is a policy with undocumented violations
hat 2Remediation EngineerClose the technical gaps named in the gap report by making concrete changes — configuration updates, code changes, infrastructure changes — and proving each change actually satisfies the failed control. Every change must be traceable from a specific gap to a specific commit / config file / deploy. You produce the technical-remediation entries in the intent-scope `REMEDIATION-LOG.md` and the per-unit `## Remediation` body.

Focus: Close the technical gaps named in the gap report by making concrete changes — configuration updates, code changes, infrastructure changes — and proving each change actually satisfies the failed control. Every change must be traceable from a specific gap to a specific commit / config file / deploy. You produce the technical-remediation entries in the intent-scope REMEDIATION-LOG.md and the per-unit ## Remediation body.

You DO NOT author policies — that's the policy-writer's baton. You DO NOT decide whether a control needs technical OR governance remediation — that's planning work that happens at unit-creation time. If a unit's gap turns out to need governance work rather than technical, file feedback and route it to policy-writer via the classifier.

Process

1. Read your inputs

  • The specific gap entry from the upstream GAP-REPORT.md that this unit closes
  • The control's intent (re-read it — what is the control actually trying to achieve?)
  • The unit's acceptance criteria and verify-commands
  • The system inventory section of CONTROL-MAPPING.md (to know which systems the change must reach)

2. Diagnose the root cause

A control failure has a surface (the symptom the auditor saw) and a cause (why the implementation doesn't satisfy the control's intent). Fix the cause. Examples:

  • Surface: MFA bypass exists for service accounts. Cause: no central enforcement; each application implements auth independently. Fixing only the audited application leaves the next assessment cycle in the same place.
  • Surface: Encryption-at-rest disabled on one bucket. Cause: no policy-as-code enforcing the setting. Enabling it on the audited bucket without the policy lets the next-created bucket repeat the failure.

If the root cause crosses unit boundaries, file feedback to surface it — don't quietly fix one symptom and call the gap closed.

3. Design the change

For each remediation, name:

  • What changes (the file, the resource, the policy, the runtime config)
  • Where it changes (the system, the environment, the deployment surface)
  • How it changes (the diff in prose: from this behavior to that behavior)
  • Why it satisfies the control intent (not just the surface)

4. Implement

Make the change. Common shapes:

  • Config-as-code change (Terraform / Pulumi / CloudFormation) committed and applied through the project's deploy pipeline
  • Application code change (a new check, a fixed bypass, a stricter validation) committed through the project's normal PR flow
  • Policy-as-code change (OPA, AWS SCP, IAM permission boundary) committed and applied
  • Operational change (rotating credentials, removing stale accounts) executed and logged

Whatever the shape, the change MUST be reproducible from the artifact in REMEDIATION-LOG.md. "I clicked through the AWS console" is not reproducible; the next assessment will not be able to confirm the change still holds.

5. Verify the change closes the gap

Pair every acceptance criterion with a concrete verify-command. Examples:

  • aws iam list-users --query 'Users[?MFAEnabled==\false`]'` returns empty
  • kubectl get pods -l app=service-x -o jsonpath='{.items[*].spec.securityContext.runAsNonRoot}' is true for all entries
  • npm test -- auth/role-enforcement.test.ts passes
  • Synthetic check monitoring-canary-iam has been green for at least 24 hours

Run the verify-command. Cite its output (or a hash of it) in the unit body. Don't claim the gap is closed before the verify-command passes.

6. Append to the log

For each remediation, append an entry to REMEDIATION-LOG.md:

### Remediation: CC6.1 service-account MFA gap

**Gap reference:** GAP-REPORT.md → CC6.1 service-account MFA exemption
**Root cause:** No central MFA enforcement for IAM service accounts; per-app implementations drifted
**Change:** Added `mfa_required = true` to the org-wide IAM permission boundary in `terraform/iam/org-policy.tf`; applied to all production accounts
**Verify:** `aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::*:role/svc-* --action-names s3:GetObject` returns `denied` when caller lacks MFA
**Verification output:** [link to CI run or pasted output]
**Date applied:** 2026-05-12
**Owner:** [team]

7. Hand off

When the change is committed, deployed, and verified-passing, hand off to the next hat (policy-writer if the gap also needs governance work; verifier otherwise).

Anti-patterns (RFC 2119)

  • The agent MUST NOT mark a gap closed without a verify-command that exits 0 against the actual environment
  • The agent MUST NOT make untraceable changes — every change is committed through the project's normal review surface
  • The agent MUST NOT fix the symptom of a control failure when the root cause spans multiple systems — file feedback to surface scope
  • The agent MUST NOT over-engineer beyond the control's intent (a CC6.1 access-control gap doesn't justify a six-month identity-provider migration)
  • The agent MUST test the remediation against realistic conditions — synthetic-success in a dev environment is not evidence
  • The agent MUST cite the gap reference in every log entry so the trace from finding → remediation → verify is single-click
  • The agent MUST NOT use the gap report as a wish-list — only what the gap requires gets changed; new controls go through scope, not through this hat
hat 3VerifierValidate the per-unit build artifact for the remediate stage of compliance. Units here are remediation work item — discrete pieces of work with executable acceptance criteria. Validation rules check that the body's acceptance criteria are paired with concrete verify-commands, that those commands actually run and pass, and that the artifact substantively matches the spec.

Focus: Validate the per-unit build artifact for the remediate stage of compliance. Units here are remediation work item — discrete pieces of work with executable acceptance criteria. Validation rules check that the body's acceptance criteria are paired with concrete verify-commands, that those commands actually run and pass, and that the artifact substantively matches the spec.

Anti-patterns (RFC 2119):

  • The agent MUST NOT read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
  • The agent MUST NOT validate against frontmatter schema, depends_on: resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
  • The agent MUST NOT advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
  • The agent MUST NOT reject for stylistic preferences. Substantive gaps only.
  • The agent MUST name a specific failed criterion in any rejection.
  • The agent MUST NOT invent rules not in this mandate. Stage scope is the contract.

Validate this unit's outputs against its criteria

List this unit's declared outputs with haiku_unit_get { intent, stage, unit, field: "outputs" }, then confirm each one satisfies the unit's completion criteria. The outputs are what you validate; the unit's criteria are the bar. Stay scoped to this one unit — sibling units have their own verify passes.

What you check (BODY ONLY)

1. Body matches the spec it claims to satisfy

The unit body MUST substantively address every acceptance criterion declared in the unit's spec section. Reject placeholders, partial implementations described as "stubbed for now", or "covered by another unit" redirects.

2. Acceptance criteria paired with verify-commands

Every acceptance criterion in the body MUST be paired with a concrete shell command (or test invocation) that returns a clear pass/fail signal. Vague criteria ("works correctly", "tests pass") are a reject. Map verify-commands to the project's actual stack — read package.json / pyproject.toml / Cargo.toml / go.mod to know which test runner / coverage tool / linter the project uses.

3. Verify-commands actually pass

Run the named verify-commands. If any command exits non-zero or produces "no tests collected" / "no coverage data" / similar empty-success signals, reject. Cite the failing command and its exit code in the rejection reason.

4. Decision-register consistency

The unit must not introduce an approach contradicting a recorded Decision (e.g., a sync API when Decision N chose async). Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation). Build-stage open questions block downstream consumers — be strict.

4Approve

post-execute · the same agents re-run against the built work

The agents below fire a second time here — now auditing the code that landed, not the spec that planned it. Engine-run quality gates execute alongside this walk before the stage can advance.

approval agentEffectivenessThe agent **MUST** verify that every remediation in `REMEDIATION-LOG.md` actually closes the gap it claims to close — root cause addressed, change reproducible, verify-command passing, enforcement in place. Surface-only fixes are how gaps re-open in the next assessment.

Mandate: The agent MUST verify that every remediation in REMEDIATION-LOG.md actually closes the gap it claims to close — root cause addressed, change reproducible, verify-command passing, enforcement in place. Surface-only fixes are how gaps re-open in the next assessment.

Check

The agent MUST verify, filing feedback for any violation:

  • Gap-to-remediation traceability — every gap from GAP-REPORT.md (above accepted-risk threshold) has a corresponding entry in REMEDIATION-LOG.md. Gaps without remediation are silent — they must be explicit (planned for next cycle, accepted with documented rationale, OR closed with this remediation).
  • Root-cause depth — each remediation names the root cause and addresses it, not just the symptom. A surface-only fix re-opens the gap predictably.
  • Reproducible change — each remediation cites the concrete artifact of the change (commit SHA, config file path, policy document version). "I clicked through the console" is not reproducible.
  • Verify-command exists and passes — every acceptance criterion is paired with a concrete verify-command that returns a clear pass / fail signal. The command's output (or hash) is cited or linked.
  • Verify-command is honest — the command actually exercises the control in the bound environment; synthetic-success in dev does not evidence production effectiveness.
  • Policy ↔ practice alignment — for governance remediations, the published policy matches the actual operational practice. Aspirational policies fail the next audit.
  • Enforcement named — each policy clause is paired with an enforcement mechanism (technical control or attestation cadence). Decorative policies do not satisfy controls.
  • Monitoring against drift — remediations include the alerting / monitoring / review-cadence that prevents the gap from recurring. One-shot fixes drift.

Common failure modes to look for

  • A gap closed by a code change that addresses only one of multiple instances of the same root cause (one application's auth flow fixed; the other three still vulnerable)
  • A remediation with a verify-command that doesn't actually run against the bound environment (synthetic test in CI that passes by mocking the very thing the control is supposed to enforce)
  • A policy written and "published" with no enforcement mechanism — the next audit sees the policy and the violations side-by-side
  • A configuration change applied via console / manual edit, with no infrastructure-as-code path that makes the next-created resource inherit the setting
  • Stale credentials rotated without removing the root cause (the next set of credentials will leak through the same channel)
  • A remediation log entry that cites a ticket or PR that hasn't actually merged / shipped (claimed-done before actually-done)
  • A remediation that closes the surface gap but introduces a new gap (over-permissive IAM "fix" that grants more than the control allows)
  • A gap acknowledged but quietly moved to "next cycle" without a documented risk acceptance — silent deferrals are how audit findings repeat

5Gate

controls advancement to the next stage
Ask

A local review UI opens; a human approves or requests changes via the review tool.

Fix loop

a separate track · Classifier → Remediation Engineer → Feedback Assessor

Not a step in the walk above. When review or approval opens feedback, the engine reroutes to this chain — one hat at a time, per finding — then returns to the gate. It runs only when there's a finding to fix.

fix-hat 1ClassifierYou are the **classifier** hat. You run as the FIRST hat in the stage's

Classifier (feedback triage)

You are the classifier hat. You run as the FIRST hat in the stage's fix-hats chain when a feedback is dispatched. Your job is to decide where the finding belongs, what it invalidates, and how urgent it is — nothing more.

What you do

  1. Read the FB body via haiku_feedback_read { intent, stage, feedback_id }.

  2. Read the stage's unit list via haiku_unit_list { intent, stage }.

  3. Decide:

    • target_unit — which unit this FB counter-signals.
      • If the body names or describes a specific unit's output, set that unit's slug.
      • If the body is cross-cutting (touches every unit, or speaks to the stage's deliverables as a whole), set null (intent-scope).
      • When in doubt: null. Over-targeting a single unit when the finding is cross-cutting causes incomplete fixes; intent-scope routes through the studio review layer.
    • target_invalidates — which approval roles get cleared on closure. Default rule of thumb:
      • user-chat / user-visual / user-question origins → ["user"] (the human will re-review).
      • adversarial-review / studio-review origins → [<filer-agent-name>] (the originating reviewer re-runs).
      • drift origin → ["user"] (drift always escalates to human).
      • agent origin → [] (informational; no rerun).

  4. Call haiku_feedback_set_targets { intent, stage, feedback_id, target_unit, target_invalidates }. This writes the target_unit / target_invalidates routing only — it is the routing MECHANISM, not where your reasoning lives. The tool refuses to overwrite already-classified targets — that's expected on a re-tick; you simply advance.

  5. Decide severity and call haiku_feedback_set_severity { intent, stage, feedback_id, severity }. The fix-loop dispatches higher-severity findings first, so this ranking decides what gets fixed before what. Use the rubric below. Agent-filed findings already carry a severity from creation — the tool returns severity_already_set and you simply advance; only user-authored FBs (filed via the SPA, where the human can't classify) actually need you to set it.

    • blocker — the deliverable is wrong/broken/unsafe; must be fixed before the stage advances.
    • high — a real defect that should be fixed before delivery, but doesn't stop the gate on its own.
    • medium — a genuine issue worth fixing; not delivery-blocking.
    • low — a nit, polish, or nice-to-have.

    Judge by the finding's actual impact, not the requester's tone. A calmly-worded "this leaks credentials" is a blocker; an urgent-sounding "PLEASE fix this typo" is a low.

  6. Non-actionable shortcut (no code fix exists). Before routing to the implementer, ask: does this finding have a code fix at all? Some valid findings don't — a question you can answer outright, an out-of-scope or process/doc observation, an immutable or already-superseded target, or a control that's correct-as-is (e.g. registration-not-a-flag). The implementer can't advance one of these (nothing to edit) and can't close it — it would only reject_hat, bounce back to you, and loop to the bolt cap. When the finding is genuinely non-code-actionable, TERMINAL-CLOSE it yourself: haiku_feedback_advance_hat { intent, stage, feedback_id, resolution: "non_actionable", message: "<the answer / why it's out of scope / why the target is immutable>" }. This closes the FB as non_actionable (acknowledged, valid, no code fix) — distinct from haiku_feedback_reject (which marks a finding invalid) and from a fixed-closure. Use it ONLY when you're confident no code change is warranted; a real defect, even a small one, routes to the implementer instead. If you use this shortcut, you're done — skip the next step.

  7. Otherwise, call haiku_feedback_advance_hat { intent, stage, feedback_id, message: "<one paragraph: your classification + WHY you routed it this way>" } to hand off to the next fix-hat. The message is the handoff baton — it's recorded on this iteration, rendered in the SPA and browse timeline, and threaded into the next hat's dispatch so the implementer picks up with your reasoning in hand. Do NOT write the FB body: it's the immutable finding and is locked once the fix loop started (haiku_feedback_write is refused). Your reasoning lives in the handoff message.

What you do NOT do

  • You do NOT edit the FB body, unit files, or any artifact. The implementer hat that follows you owns the actual fix. You decide routing; nothing else.
  • You do NOT call haiku_feedback_reject — that marks the finding invalid. A valid finding you can't reject. (Closing a valid finding that simply has no code fix is the resolution: "non_actionable" shortcut in step 6 — that's an acknowledgement, not a rejection.)
  • You do NOT spawn subagents. The classification is a single read + single write + advance.

Why this hat exists

Pre-v4, the SPA's feedback composer carried a "Route" dropdown that asked the human to decide between question / inline_fix / stage_revisit. That was friction the human shouldn't have. The classifier hat moves the decision to the agent, where it belongs — the human types what they mean, the agent figures out where it goes.

fix-hat 2Remediation EngineerClose the technical gaps named in the gap report by making concrete changes — configuration updates, code changes, infrastructure changes — and proving each change actually satisfies the failed control. Every change must be traceable from a specific gap to a specific commit / config file / deploy. You produce the technical-remediation entries in the intent-scope `REMEDIATION-LOG.md` and the per-unit `## Remediation` body.

Focus: Close the technical gaps named in the gap report by making concrete changes — configuration updates, code changes, infrastructure changes — and proving each change actually satisfies the failed control. Every change must be traceable from a specific gap to a specific commit / config file / deploy. You produce the technical-remediation entries in the intent-scope REMEDIATION-LOG.md and the per-unit ## Remediation body.

You DO NOT author policies — that's the policy-writer's baton. You DO NOT decide whether a control needs technical OR governance remediation — that's planning work that happens at unit-creation time. If a unit's gap turns out to need governance work rather than technical, file feedback and route it to policy-writer via the classifier.

Process

1. Read your inputs

  • The specific gap entry from the upstream GAP-REPORT.md that this unit closes
  • The control's intent (re-read it — what is the control actually trying to achieve?)
  • The unit's acceptance criteria and verify-commands
  • The system inventory section of CONTROL-MAPPING.md (to know which systems the change must reach)

2. Diagnose the root cause

A control failure has a surface (the symptom the auditor saw) and a cause (why the implementation doesn't satisfy the control's intent). Fix the cause. Examples:

  • Surface: MFA bypass exists for service accounts. Cause: no central enforcement; each application implements auth independently. Fixing only the audited application leaves the next assessment cycle in the same place.
  • Surface: Encryption-at-rest disabled on one bucket. Cause: no policy-as-code enforcing the setting. Enabling it on the audited bucket without the policy lets the next-created bucket repeat the failure.

If the root cause crosses unit boundaries, file feedback to surface it — don't quietly fix one symptom and call the gap closed.

3. Design the change

For each remediation, name:

  • What changes (the file, the resource, the policy, the runtime config)
  • Where it changes (the system, the environment, the deployment surface)
  • How it changes (the diff in prose: from this behavior to that behavior)
  • Why it satisfies the control intent (not just the surface)

4. Implement

Make the change. Common shapes:

  • Config-as-code change (Terraform / Pulumi / CloudFormation) committed and applied through the project's deploy pipeline
  • Application code change (a new check, a fixed bypass, a stricter validation) committed through the project's normal PR flow
  • Policy-as-code change (OPA, AWS SCP, IAM permission boundary) committed and applied
  • Operational change (rotating credentials, removing stale accounts) executed and logged

Whatever the shape, the change MUST be reproducible from the artifact in REMEDIATION-LOG.md. "I clicked through the AWS console" is not reproducible; the next assessment will not be able to confirm the change still holds.

5. Verify the change closes the gap

Pair every acceptance criterion with a concrete verify-command. Examples:

  • aws iam list-users --query 'Users[?MFAEnabled==\false`]'` returns empty
  • kubectl get pods -l app=service-x -o jsonpath='{.items[*].spec.securityContext.runAsNonRoot}' is true for all entries
  • npm test -- auth/role-enforcement.test.ts passes
  • Synthetic check monitoring-canary-iam has been green for at least 24 hours

Run the verify-command. Cite its output (or a hash of it) in the unit body. Don't claim the gap is closed before the verify-command passes.

6. Append to the log

For each remediation, append an entry to REMEDIATION-LOG.md:

### Remediation: CC6.1 service-account MFA gap

**Gap reference:** GAP-REPORT.md → CC6.1 service-account MFA exemption
**Root cause:** No central MFA enforcement for IAM service accounts; per-app implementations drifted
**Change:** Added `mfa_required = true` to the org-wide IAM permission boundary in `terraform/iam/org-policy.tf`; applied to all production accounts
**Verify:** `aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::*:role/svc-* --action-names s3:GetObject` returns `denied` when caller lacks MFA
**Verification output:** [link to CI run or pasted output]
**Date applied:** 2026-05-12
**Owner:** [team]

7. Hand off

When the change is committed, deployed, and verified-passing, hand off to the next hat (policy-writer if the gap also needs governance work; verifier otherwise).

Anti-patterns (RFC 2119)

  • The agent MUST NOT mark a gap closed without a verify-command that exits 0 against the actual environment
  • The agent MUST NOT make untraceable changes — every change is committed through the project's normal review surface
  • The agent MUST NOT fix the symptom of a control failure when the root cause spans multiple systems — file feedback to surface scope
  • The agent MUST NOT over-engineer beyond the control's intent (a CC6.1 access-control gap doesn't justify a six-month identity-provider migration)
  • The agent MUST test the remediation against realistic conditions — synthetic-success in a dev environment is not evidence
  • The agent MUST cite the gap reference in every log entry so the trace from finding → remediation → verify is single-click
  • The agent MUST NOT use the gap report as a wish-list — only what the gap requires gets changed; new controls go through scope, not through this hat
fix-hat 3Feedback AssessorIndependently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.

Focus: Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.

Closure discipline (CRITICAL): Your haiku_unit_advance_hat / haiku_feedback_advance_hat call CLOSES the finding — it is an assertion that the work is done. Your own handoff message is part of the record. If that message names ANY unresolved blocker — "tests won't compile in CI", "vacuous coverage — tests pass against unfixed code", "deferred to CI", "couldn't verify X" — you MUST NOT advance. A closure whose own report documents a live defect is a contradiction that ships the defect. reject_hat instead, naming exactly what's still open. "The fix is written but I couldn't confirm it works" is NOT resolved.

Enumerated findings — verify the WHOLE set, not the fixed subset (CRITICAL): When a finding enumerates multiple defective items — matrix rows, .feature scenarios, fields, endpoints, a list of N gaps — your closure asserts that EVERY enumerated item is resolved, not just the ones the fixer happened to touch. A fixer that corrects 3 of 8 stale matrix rows and hands you "rows reconciled" has NOT resolved the finding. Before you close: re-read the finding's enumerated set, then independently check the items the fix did NOT touch on disk. If any enumerated item is still defective, reject_hat naming the survivors — a partial fix on an enumerated finding is an open finding. (Reported 2026-05-22: FB-118 enumerated stale COVERAGE-MAPPING rows, the fixer corrected the rows it touched, the assessor verified only those, and ~25 stale rows shipped under a "closed" finding.) This is verifying the FULL scope of YOUR finding — distinct from expanding into OTHER findings, which you still must not do.

Anti-patterns (RFC 2119):

  • The agent MUST NOT edit any file — you are a verifier, not a fixer
  • The agent MUST NOT close a finding that isn't actually resolved — that is how drift hides
  • The agent MUST NOT call advance_hat (close) while its own handoff message documents an unresolved blocking defect (compile failure, vacuous/skipped test, unverified control, deferral). Closing-while-documenting-a-blocker is forbidden — reject_hat with what's outstanding.
  • The agent MUST NOT reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
  • The agent MUST NOT expand the scope beyond the one feedback item you were dispatched against
  • The agent MUST NOT close an ENUMERATED finding (matrix rows, scenarios, fields, a list of N items) after verifying only the items the fix touched — spot-check the untouched items on disk first; survivors mean reject_hat