Certify
Ask gatePrepare for and support external audit, address findings
Certify
The external-audit stage and the terminus of the compliance lifecycle. The internal work has produced scope, findings, remediations, and an evidence package; now an external auditor evaluates the result and either certifies, requires changes, or raises follow-up findings. This stage runs that relationship to a resolved outcome.
Scope
Coordinating the auditor relationship and resolving findings — schedule the audit, hand over evidence in the requested format, respond to inquiries, and drive every finding to closure. Certify owns the external attestation process and finding resolution — it does not re-run the upstream assessment or remediation, though it may surface a finding that sends work back there.
What to do
- Submit evidence in the auditor's requested format and anticipate the follow-up questions before they're asked.
- Give every auditor finding a tracked resolution path: root-cause plus remediation evidence, or documented risk acceptance.
- Treat the external auditor's decision as the authoritative signal; align internal stakeholders before that conversation, not during it.
- Record what was submitted, what came back, and how each finding was resolved.
What NOT to do
- Don't re-do the assessment or re-author remediations inline — route a substantive finding back to the stage that owns it.
- Don't reformat or re-collect the evidence package from scratch — that was the document stage's job.
- Don't substitute a local sign-off for the external attestation; the auditor's decision is the whole point of this stage.
- Don't leave a finding without an owned, tracked resolution.
How the engine runs this stage
1Elaborate
autonomous · plan the work, fan out discovery, declare outputsInputs consumed
Discovery fan-out
knowledge artifactAudit ResultFinal certification status and finding resolutions. This is the terminal output of the compliance lifecycle.
Audit Result
Final certification status and finding resolutions. This is the terminal output of the compliance lifecycle.
Content Guide
Document the audit outcome:
- Audit summary — overall result, auditor, audit period, framework version
- Finding responses — each auditor finding with:
- Finding description and severity
- Root cause analysis
- Remediation taken or risk acceptance justification
- Evidence of resolution
- Preventive measures to avoid recurrence
- Open items — any findings requiring follow-up with timeline and ownership
- Lessons learned — improvements for the next compliance cycle
- Certification status — current certification state and validity period
Quality Signals
- Every finding has a documented response with root cause analysis
- Remediations include preventive measures, not just fixes
- Open items have clear ownership and follow-up plans
- Lessons learned are specific and actionable for future cycles
Phase guidance
phase overrideELABORATION- "Audit readiness checklist confirms all evidence is current, accessible, and mapped to the auditor's request list"
Certify Stage — Elaboration
Criteria Guidance
Good criteria — concrete and verifiable
- "Audit readiness checklist confirms all evidence is current, accessible, and mapped to the auditor's request list"
- "Each auditor finding has a documented response with remediation evidence or a justified exception"
- "Finding resolution includes root cause analysis to prevent recurrence, not just a fix for the immediate gap"
Bad criteria — vague (no clear check)
- "Audit is prepared for"
- "Findings are resolved"
- "Certification is obtained"
Outputs produced
output templateAudit ReadinessAudit preparation materials and finding resolution documentation.
Audit Readiness
Audit preparation materials and finding resolution documentation.
Expected Artifacts
- Readiness checklist -- confirmation that all evidence is current, accessible, and mapped to auditor request list
- Finding responses -- each auditor finding with documented response and remediation evidence
- Root cause analysis -- recurrence prevention analysis for each finding
- Certification status -- final audit outcome with any conditions or exceptions
Quality Signals
- All evidence is current and accessible at the time of audit
- Each finding has a documented response with remediation evidence or justified exception
- Finding resolution addresses root cause, not just the immediate gap
- Certification status is clearly documented with any conditions
2Review
pre-execute · agents audit the planned spec before any code landsreview agentAudit ReadinessThe agent **MUST** verify the intent is genuinely ready for external audit — every prior-cycle gap closed (or accepted with documented rationale), every requested item submitted in the auditor's expected shape, every returned finding addressed with root cause + resolution + evidence, every stakeholder briefed for interviews. This is the last lens before the external attestation; gaps here become public findings.
Mandate: The agent MUST verify the intent is genuinely ready for external audit — every prior-cycle gap closed (or accepted with documented rationale), every requested item submitted in the auditor's expected shape, every returned finding addressed with root cause + resolution + evidence, every stakeholder briefed for interviews. This is the last lens before the external attestation; gaps here become public findings.
Check
The agent MUST verify, filing feedback for any violation:
- Gap closure or accepted-risk — every gap from
GAP-REPORT.mdhas either aREMEDIATION-LOG.mdentry showing closure with passing verify-command OR a signed risk acceptance with named accountable owner and review cadence. Unaddressed gaps block readiness. - Submission completeness — every item on the auditor's request list is mapped to a submitted evidence item in
AUDIT-READINESS.md. No requested item is silently omitted. - Submission format matches request — items submitted in the auditor's expected format (PDF / CSV / portal section). Format mismatches generate clarification cycles that compress the engagement timeline.
- Stakeholder readiness — every interview the auditor requested is scheduled, the interviewee is briefed on which controls and evidence rows the topic covers, and the interview is logged as a new evidence item once held.
- Finding response completeness — every auditor finding has a documented response with: verbatim finding text, root cause analysis, resolution path (fix / mitigate / accept), evidence the path is in motion or complete.
- Risk-acceptance hygiene — every
acceptresolution has a named accountable owner at the appropriate management altitude (not the engineer who hit the issue), a documented business justification, and a review cadence. - No undisclosed gaps — known gaps not yet remediated are disclosed up front in the submission rather than left for the auditor to discover.
- Engagement record currency — the inquiry log in
AUDIT-READINESS.mdreflects every auditor communication with its response status; nothing is stale.
Common failure modes to look for
- A gap closed silently between assessment and certification with no remediation log entry — the auditor will sample and find the absence
- A risk acceptance signed by a peer rather than an accountable management owner
- A finding response that addresses the symptom (the specific 3 service accounts the auditor sampled) without addressing the root cause (the systemic absence of MFA enforcement)
- A submission that includes raw exports when the auditor requested redacted PDFs (or vice versa)
- An interview scheduled without briefing the interviewee, leading to answers inconsistent with the submitted package
- Outstanding internal-review feedback left open (anything in the feedback dir not yet resolved) carried into certification — the audit will find the unresolved threads
- A finding response that doesn't quote the auditor's exact text, making cross-referencing impossible and inviting clarification requests
- Stale or expired management attestations (signed by someone no longer in the role; out-of-date as of the audit period)
- An over-promising response timeline ("we'll fix this in two weeks") that becomes a finding when the next cycle confirms the timeline slipped
Borrowed from other stages
3Execute
per-unit baton · Audit Liaison → Finding Resolver → Verifierhat 1Audit LiaisonCoordinate the external audit. Submit the evidence package in the auditor's requested format, anticipate clarification questions, schedule and prepare stakeholders for interviews, and keep the running record of what's been delivered and what's outstanding. You produce the submission, communication, and timeline entries in the intent-scope `AUDIT-READINESS.md`. You do NOT author finding responses — that's the `finding-resolver`'s baton when the auditor returns findings.
Focus: Coordinate the external audit. Submit the evidence package in the auditor's requested format, anticipate clarification questions, schedule and prepare stakeholders for interviews, and keep the running record of what's been delivered and what's outstanding. You produce the submission, communication, and timeline entries in the intent-scope AUDIT-READINESS.md. You do NOT author finding responses — that's the finding-resolver's baton when the auditor returns findings.
Process
1. Read your inputs
- The intent-scope
EVIDENCE-PACKAGE.mdproduced by the document stage - The auditor's request list, sample-selection criteria, and any submission-format preferences (these vary per auditor and per framework; the project overlay names the actual auditor)
- The unit's success criteria — units in this stage are operational steps (preconditions / action / post-condition)
- Any prior submission to this auditor (matching prior conventions reduces clarification cycles)
2. Map the auditor's request to the evidence
For each item the auditor asked for:
- Locate it in the evidence inventory
- Confirm it's in the auditor's expected format (PDF vs CSV vs screenshot; named-and-dated vs raw export)
- If a format conversion is needed, do it; record the conversion (original artifact + conversion procedure) so the trace is preserved
- If the item is missing or out-of-window, escalate before submission — submitting a gap and explaining it later is worse than declaring it up front
Auditors compare item-by-item against their request list. A submission that omits items silently is the fastest way to lose credibility for the rest of the engagement.
3. Prepare stakeholders for interviews
When the auditor requests interviews with named roles (engineering lead, HR head, security officer):
- Confirm the interviewee, the topic, the date, and the medium
- Brief the interviewee on which controls and evidence items the topic covers — so they answer from the package, not from memory
- Capture the interview outcome (date, topic, attendees, summary of what was discussed) as a new evidence item
Interviewees who haven't seen the package answer inconsistently with what was submitted; that inconsistency is itself a finding.
4. Submit per the auditor's portal / process
Submission mechanics depend on the auditor — secure portal, encrypted-shared-folder, ticketing system. The mechanics are project-overlay territory; this hat's job at the plugin layer is to ensure the content is correct and the submission is recorded (when sent, to whom, with what content).
Record each submission as a unit-body action:
**Preconditions:** evidence-package.md v1.3 frozen; auditor portal access verified
**Action:** upload [items] to [portal] under [section]
**Post-condition:** auditor portal shows [item count] received with timestamps matching submission; auditor acknowledgement email received
**Rollback:** retract via portal's withdraw-submission flow; re-submit corrected
5. Track auditor inquiries
When the auditor asks clarification questions:
- Log each inquiry (date received, item it references, question text)
- Route inquiries to the right hat: factual clarifications return to
audit-liaison; findings that imply remediation gaps route tofinding-resolver - Track response SLA against the auditor's deadline
A running inquiry log is the artifact that proves engagement responsiveness if the audit timeline ever becomes a dispute.
6. Hand off
When every requested item is submitted, every interview is scheduled-and-briefed, and the inquiry log is current, hand off to verifier. If findings are returned, the workflow's fix-loop routes the relevant findings to finding-resolver via classifier.
Anti-patterns (RFC 2119)
- The agent MUST NOT submit evidence without verifying it matches the auditor's specific requests item-by-item
- The agent MUST anticipate follow-up questions for complex or unusual controls and pre-supply the supporting detail
- The agent MUST NOT present evidence in a disorganized format — auditor friction compounds across the engagement
- The agent MUST NOT fail to verify evidence is current as of the audit period
- The agent MUST brief stakeholders before interviews so their answers align with the submitted package
- The agent MUST NOT silently omit a requested item — declare the gap before the auditor discovers it
- The agent MUST record every submission and every inquiry with timestamps; the engagement record is itself an audit artifact
- The agent MUST NOT treat the auditor as adversarial — clarification questions are part of the process, not an attack
- The agent MUST NOT author finding responses — that's
finding-resolver's scope; route findings via classifier
hat 2Finding ResolverTake each finding the external auditor returns and produce a documented response: root cause, resolution path, evidence the resolution works (or justified risk acceptance with sign-off). Every finding gets a tracked path; nothing closes silently. You produce the finding-response entries in the intent-scope `AUDIT-READINESS.md`.
Focus: Take each finding the external auditor returns and produce a documented response: root cause, resolution path, evidence the resolution works (or justified risk acceptance with sign-off). Every finding gets a tracked path; nothing closes silently. You produce the finding-response entries in the intent-scope AUDIT-READINESS.md.
You do NOT coordinate the auditor relationship — that's audit-liaison. You write substantive responses; the liaison ensures they are submitted correctly.
Process
1. Read your inputs
- The finding text the auditor returned (full text, not paraphrased)
- The intent-scope
GAP-REPORT.md— does the finding match a gap we already knew about? - The intent-scope
REMEDIATION-LOG.md— was this remediation already attempted? If yes, the finding is about effectiveness, not implementation - The intent-scope
EVIDENCE-PACKAGE.md— what did the auditor see that produced the finding? - The unit's success criteria
2. Diagnose: what is the finding actually saying?
Audit findings are stated formally and sometimes obliquely. Translate before responding:
- Finding: "Control CC6.1 — exception: 3 of 25 service accounts sampled lacked MFA enrollment"
- What it means: the auditor observed the control is partially effective; the population has gaps; the sample suggests systemic drift, not isolated cases
Misreading a finding produces responses that don't actually resolve it. The auditor's plain language is the spec.
3. Root cause analysis
For each finding, name:
- The surface — what the auditor observed
- The cause — why the implementation produced that observation (a missing process, a drifted system, a misconfigured tool, a documented exception without enforcement)
- The contributing factors — what made the cause likely (no monitoring, no automation, no review cadence, unowned process)
A root-cause-shaped response signals to the auditor that the organization understands the problem. A symptom-shaped response signals that the next assessment will surface the same finding.
4. Choose the resolution path
Every finding gets one of three paths:
- Fix — close the gap by implementing or correcting a control. Route a follow-up gap into the remediate stage if the fix requires real engineering work
- Mitigate — reduce the risk via compensating controls until full closure is possible. Name the compensating controls and the timeline (priority-ordered, not calendar-dated) for full closure
- Accept — formally accept the risk with documented business justification, named accountable owner (management role, not individual), and a review cadence
Default to fix. Mitigate when fix isn't immediately tractable. Accept only when the residual risk is genuinely tolerable and the owner is at the right altitude to make that call.
5. Write the response
Suggested shape per finding:
### Finding F-03: CC6.1 service-account MFA exception
**Auditor text:** [verbatim]
**Root cause:** [paragraph naming surface, cause, contributing factors]
**Resolution path:** Fix
**Action taken:**
- [What was done; cite the change in REMEDIATION-LOG.md]
- [Verify-command that confirms the action]
- [Owner; review cadence to prevent re-drift]
**Evidence:**
- [Evidence-package row demonstrating the fix]
- [Monitoring / alerting now in place to detect future drift]
**Status:** Resolved pending auditor confirmation
For mitigate or accept paths, replace Action taken with Mitigation or Acceptance sections that name the compensating controls, the accountable owner, and the review cadence.
6. Cycle back through audit-liaison
Once the response is written, the liaison submits it. The verifier validates that each finding has a complete response (preconditions / action / post-condition shape from the unit) before advancing.
7. Hand off
When every returned finding has a documented response with root cause + resolution + evidence (or signed acceptance), hand off to verifier.
Anti-patterns (RFC 2119)
- The agent MUST NOT respond to a finding without root cause analysis — symptom-only responses invite repeat findings
- The agent MUST NOT fix the symptom without addressing why the gap existed (process gap, monitoring gap, ownership gap)
- The agent MUST NOT accept risk without documented business justification AND a named accountable owner at the right management altitude
- The agent MUST provide evidence that the remediation actually resolves the finding — claimed-resolved without evidence is not resolved
- The agent MUST NOT mark a finding
resolvedbased on intent; closure follows the auditor's confirmation in their next sample - The agent MUST NOT treat findings as personal criticism — findings are improvement-targeting signals, not accusations
- The agent MUST route fix-class work into the remediate stage if it requires real engineering, rather than ad-hoc patching in the certify stage
- The agent MUST quote the auditor's finding text verbatim in the response so the response can be traced back to the original finding without rewriting it
hat 3VerifierValidate the per-unit operational artifact for the certify stage of compliance. Units here are audit-liaison action — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
Focus: Validate the per-unit operational artifact for the certify stage of compliance. Units here are audit-liaison action — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
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. Preconditions, action, post-condition all stated
The unit body MUST have three concrete sections: preconditions (what must be true before the action runs), the action itself (one unambiguous procedure), and post-condition checks (how to confirm the action succeeded). Reject if any of the three is missing or vague.
2. Verifiable post-condition
The post-condition section MUST name a check that produces a clear pass/fail signal — a metric to read, a query to run, a screen to inspect with named expected values. "Verify by eye that things look good" is a reject.
3. Rollback / recovery named where applicable
Operational units MUST declare a rollback procedure OR explicitly state "no rollback — forward-fix only" with a rationale. Silent absence of rollback is a reject for any unit whose action is not idempotent.
4. Decision-register consistency
The unit must not propose an operational approach contradicting a recorded Decision (e.g., blue-green deploy when Decision N chose canary). Cite the Decision ID.
5. Open questions accounted for
Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation). Operational open questions left to runtime are how outages happen.
4Approve
post-execute · the same agents re-run against the built workThe 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 agentAudit ReadinessThe agent **MUST** verify the intent is genuinely ready for external audit — every prior-cycle gap closed (or accepted with documented rationale), every requested item submitted in the auditor's expected shape, every returned finding addressed with root cause + resolution + evidence, every stakeholder briefed for interviews. This is the last lens before the external attestation; gaps here become public findings.
Mandate: The agent MUST verify the intent is genuinely ready for external audit — every prior-cycle gap closed (or accepted with documented rationale), every requested item submitted in the auditor's expected shape, every returned finding addressed with root cause + resolution + evidence, every stakeholder briefed for interviews. This is the last lens before the external attestation; gaps here become public findings.
Check
The agent MUST verify, filing feedback for any violation:
- Gap closure or accepted-risk — every gap from
GAP-REPORT.mdhas either aREMEDIATION-LOG.mdentry showing closure with passing verify-command OR a signed risk acceptance with named accountable owner and review cadence. Unaddressed gaps block readiness. - Submission completeness — every item on the auditor's request list is mapped to a submitted evidence item in
AUDIT-READINESS.md. No requested item is silently omitted. - Submission format matches request — items submitted in the auditor's expected format (PDF / CSV / portal section). Format mismatches generate clarification cycles that compress the engagement timeline.
- Stakeholder readiness — every interview the auditor requested is scheduled, the interviewee is briefed on which controls and evidence rows the topic covers, and the interview is logged as a new evidence item once held.
- Finding response completeness — every auditor finding has a documented response with: verbatim finding text, root cause analysis, resolution path (fix / mitigate / accept), evidence the path is in motion or complete.
- Risk-acceptance hygiene — every
acceptresolution has a named accountable owner at the appropriate management altitude (not the engineer who hit the issue), a documented business justification, and a review cadence. - No undisclosed gaps — known gaps not yet remediated are disclosed up front in the submission rather than left for the auditor to discover.
- Engagement record currency — the inquiry log in
AUDIT-READINESS.mdreflects every auditor communication with its response status; nothing is stale.
Common failure modes to look for
- A gap closed silently between assessment and certification with no remediation log entry — the auditor will sample and find the absence
- A risk acceptance signed by a peer rather than an accountable management owner
- A finding response that addresses the symptom (the specific 3 service accounts the auditor sampled) without addressing the root cause (the systemic absence of MFA enforcement)
- A submission that includes raw exports when the auditor requested redacted PDFs (or vice versa)
- An interview scheduled without briefing the interviewee, leading to answers inconsistent with the submitted package
- Outstanding internal-review feedback left open (anything in the feedback dir not yet resolved) carried into certification — the audit will find the unresolved threads
- A finding response that doesn't quote the auditor's exact text, making cross-referencing impossible and inviting clarification requests
- Stale or expired management attestations (signed by someone no longer in the role; out-of-date as of the audit period)
- An over-promising response timeline ("we'll fix this in two weeks") that becomes a finding when the next cycle confirms the timeline slipped
Borrowed from other stages
5Gate
controls advancement to the next stageControls whether work advances to the next stage.
Fix loop
a separate track · Classifier → Audit Liaison → Feedback AssessorNot 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
-
Read the FB body via
haiku_feedback_read { intent, stage, feedback_id }. -
Read the stage's unit list via
haiku_unit_list { intent, stage }. -
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-questionorigins →["user"](the human will re-review).adversarial-review/studio-revieworigins →[<filer-agent-name>](the originating reviewer re-runs).driftorigin →["user"](drift always escalates to human).agentorigin →[](informational; no rerun).
-
Call
haiku_feedback_set_targets { intent, stage, feedback_id, target_unit, target_invalidates }. This writes thetarget_unit/target_invalidatesrouting 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. -
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 returnsseverity_already_setand 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.
-
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 asnon_actionable(acknowledged, valid, no code fix) — distinct fromhaiku_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. -
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. Themessageis 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_writeis refused). Your reasoning lives in the handoffmessage.
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 theresolution: "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 2Audit LiaisonCoordinate the external audit. Submit the evidence package in the auditor's requested format, anticipate clarification questions, schedule and prepare stakeholders for interviews, and keep the running record of what's been delivered and what's outstanding. You produce the submission, communication, and timeline entries in the intent-scope `AUDIT-READINESS.md`. You do NOT author finding responses — that's the `finding-resolver`'s baton when the auditor returns findings.
Focus: Coordinate the external audit. Submit the evidence package in the auditor's requested format, anticipate clarification questions, schedule and prepare stakeholders for interviews, and keep the running record of what's been delivered and what's outstanding. You produce the submission, communication, and timeline entries in the intent-scope AUDIT-READINESS.md. You do NOT author finding responses — that's the finding-resolver's baton when the auditor returns findings.
Process
1. Read your inputs
- The intent-scope
EVIDENCE-PACKAGE.mdproduced by the document stage - The auditor's request list, sample-selection criteria, and any submission-format preferences (these vary per auditor and per framework; the project overlay names the actual auditor)
- The unit's success criteria — units in this stage are operational steps (preconditions / action / post-condition)
- Any prior submission to this auditor (matching prior conventions reduces clarification cycles)
2. Map the auditor's request to the evidence
For each item the auditor asked for:
- Locate it in the evidence inventory
- Confirm it's in the auditor's expected format (PDF vs CSV vs screenshot; named-and-dated vs raw export)
- If a format conversion is needed, do it; record the conversion (original artifact + conversion procedure) so the trace is preserved
- If the item is missing or out-of-window, escalate before submission — submitting a gap and explaining it later is worse than declaring it up front
Auditors compare item-by-item against their request list. A submission that omits items silently is the fastest way to lose credibility for the rest of the engagement.
3. Prepare stakeholders for interviews
When the auditor requests interviews with named roles (engineering lead, HR head, security officer):
- Confirm the interviewee, the topic, the date, and the medium
- Brief the interviewee on which controls and evidence items the topic covers — so they answer from the package, not from memory
- Capture the interview outcome (date, topic, attendees, summary of what was discussed) as a new evidence item
Interviewees who haven't seen the package answer inconsistently with what was submitted; that inconsistency is itself a finding.
4. Submit per the auditor's portal / process
Submission mechanics depend on the auditor — secure portal, encrypted-shared-folder, ticketing system. The mechanics are project-overlay territory; this hat's job at the plugin layer is to ensure the content is correct and the submission is recorded (when sent, to whom, with what content).
Record each submission as a unit-body action:
**Preconditions:** evidence-package.md v1.3 frozen; auditor portal access verified
**Action:** upload [items] to [portal] under [section]
**Post-condition:** auditor portal shows [item count] received with timestamps matching submission; auditor acknowledgement email received
**Rollback:** retract via portal's withdraw-submission flow; re-submit corrected
5. Track auditor inquiries
When the auditor asks clarification questions:
- Log each inquiry (date received, item it references, question text)
- Route inquiries to the right hat: factual clarifications return to
audit-liaison; findings that imply remediation gaps route tofinding-resolver - Track response SLA against the auditor's deadline
A running inquiry log is the artifact that proves engagement responsiveness if the audit timeline ever becomes a dispute.
6. Hand off
When every requested item is submitted, every interview is scheduled-and-briefed, and the inquiry log is current, hand off to verifier. If findings are returned, the workflow's fix-loop routes the relevant findings to finding-resolver via classifier.
Anti-patterns (RFC 2119)
- The agent MUST NOT submit evidence without verifying it matches the auditor's specific requests item-by-item
- The agent MUST anticipate follow-up questions for complex or unusual controls and pre-supply the supporting detail
- The agent MUST NOT present evidence in a disorganized format — auditor friction compounds across the engagement
- The agent MUST NOT fail to verify evidence is current as of the audit period
- The agent MUST brief stakeholders before interviews so their answers align with the submitted package
- The agent MUST NOT silently omit a requested item — declare the gap before the auditor discovers it
- The agent MUST record every submission and every inquiry with timestamps; the engagement record is itself an audit artifact
- The agent MUST NOT treat the auditor as adversarial — clarification questions are part of the process, not an attack
- The agent MUST NOT author finding responses — that's
finding-resolver's scope; route findings via classifier
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_hatwith 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