Documentation · stage 5 of 5

Publish

Auto gate

Format, validate links, and publish the documentation

Publish

The terminal stage of the documentation lifecycle: ship the reviewed draft to the docs platform, formatted to its conventions, with every link, code block, image, and cross-reference verified. This is where the invisible defects surface — broken links, malformed fences, missing alt text, stale anchors — and catching them here is cheaper than catching them at a reader's 404.

Scope

Formatting to the platform, verifying every embedded reference, and recording the publish. Publish decides how the content goes live and that it's intact on the platform — it does not write or edit content (draft, review). Content defects route back upstream; this stage owns the mechanics of shipping.

What to do

  • Format the content to the platform's conventions — embed shapes, anchors, asset destinations.
  • Verify every link, code block, image, and cross-reference actually resolves.
  • Record the publish: canonical URL, version, and search-indexed timestamp.
  • Route a content or accuracy defect back to the stage that owns it rather than patching prose here.

What NOT to do

  • Don't rewrite prose or restructure content — that's the draft and review stages.
  • Don't re-litigate editorial or technical findings — they were resolved upstream.
  • Don't publish with a broken link, a malformed code block, or a missing asset.
  • Don't ship without a recorded publish artifact at the canonical URL.

How the engine runs this stage

1Elaborate

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

Phase guidance

phase overrideELABORATION- "All internal and external links resolve to valid targets"

Publish Stage — Elaboration

Criteria Guidance

Good criteria — concrete and verifiable

  • "All internal and external links resolve to valid targets"
  • "All critical and major review findings are addressed in the final version"
  • "Documentation renders correctly in the target platform (site, wiki, PDF)"

Bad criteria — vague (no clear check)

  • "Documentation is published"
  • "Links work"
  • "Formatting is done"

Outputs produced

output templatePublished DocsFinal documentation deployed to the target platform with all links validated.

Published Documentation

Final documentation deployed to the target platform with all links validated.

Expected Artifacts

  • Final documentation -- all review findings addressed in the published version
  • Link validation -- all internal and external links resolve to valid targets
  • Platform verification -- documentation renders correctly in the target platform
  • Publication record -- where documentation is published and how to access it

Quality Signals

  • All critical and major review findings are addressed
  • All links resolve to valid targets
  • Documentation renders correctly on the target platform
  • Publication location is documented and accessible

2Review

pre-execute · agents audit the planned spec before any code lands
review agentFormattingThe agent **MUST** verify the published documentation renders correctly on the target platform and is navigable by the named audience.

Mandate: The agent MUST verify the published documentation renders correctly on the target platform and is navigable by the named audience.

Check

The agent MUST verify, file feedback for any violation:

  • Every link resolves — Internal links, anchors, cross-references, external links, and image references all resolve. No 404s, no redirect loops, no broken anchors. Link rot at publish time becomes reader friction immediately.
  • Images and diagrams render at appropriate sizes — Images aren't cut off, distorted, or oversized for the layout. Alt text is present and meaningful — not just image or the filename.
  • Code blocks render with correct syntax highlighting — Language tags match the renderer's expected vocabulary; tagged blocks highlight; untagged blocks are intentional (not accidents).
  • Table of contents and navigation reflect the actual content — The auto-generated TOC matches the heading hierarchy; the platform's navigation surfaces the document at the expected location.
  • Heading hierarchy is clean — Levels don't skip (## to ####); the renderer's TOC reads coherently; screen-reader navigation works.
  • Metadata is complete — Title, description, last-updated, owner, and audience tags are populated and match the target platform's schema.
  • Accessibility holds in the rendered view — Alt text present, color contrast adequate, no reliance on color alone for meaning, headings semantic.
  • Platform-specific conventions honored — Callout shortcodes, banner patterns, and house numbering match the project overlay (if one exists) or the platform's defaults.
  • No placeholder content — TODO, <your X here>, [insert example], untouched scaffolds, or other placeholders don't ship.

Common failure modes to look for

  • A link that resolved when written but broke when the target document was renamed or moved
  • An image referenced by an absolute path that works locally but breaks in the rendered output
  • A code block with no language tag, displayed as plain text in the rendered output
  • A document missing from the navigation because the front matter didn't declare the right category
  • A heading hierarchy with skipped levels that breaks the auto-generated TOC and screen-reader navigation
  • An image with alt text image or screenshot rather than a description of what's shown
  • A page that renders cleanly on desktop but breaks on narrow viewports (table overflow, untruncated code, broken layout)
  • A last-updated timestamp that was never set, so the platform shows the document as ancient
  • Color used as the sole signal (red error text, green success text) with no accessible alternative

Borrowed from other stages

Accuracyfrom Draft

3Execute

per-unit baton · Format Planner → Publisher → Verifier
hat 1Format PlannerPlan the publish step before any artifact moves. The publisher will execute mechanical adaptation against the docs platform; your job is to decide *what* gets adapted *how* — platform conventions to apply, anchor / sidebar strategy, asset destinations, link-resolution scope — so the publisher's run is unambiguous.

Focus: Plan the publish step before any artifact moves. The publisher will execute mechanical adaptation against the docs platform; your job is to decide what gets adapted how — platform conventions to apply, anchor / sidebar strategy, asset destinations, link-resolution scope — so the publisher's run is unambiguous.

Process

  1. Read the reviewed draft and the platform's conventions — the assigned section from draft/draft-documentation and any project-overlay notes on the docs platform (Markdown dialect, code-fence syntax, embed shapes, sidebar structure).
  2. Name the conversions — for this section, list which Markdown / format conversions the publisher will apply (e.g., "fence ts → typescript", "image alt-text → required", "anchor slug from heading text").
  3. Name the destination — exact target path / URL on the platform, sidebar position, search-indexing flag.
  4. Identify link-resolution scope — internal links (relative? absolute? anchor-prefixed?), external links (validated against what?), cross-document references (need anchor map updates?).
  5. Surface platform-specific risks — what could the publisher run into that the draft doesn't show? Embed quotas, max-image-size, code-block size limits, broken cross-doc references after rename.
  6. Write the publish-plan as the unit body, then call haiku_unit_advance_hat.

Anti-patterns (RFC 2119)

  • The agent MUST NOT execute the publish itself — that's the publisher hat's role.
  • The agent MUST NOT invent platform conventions not stated in the project overlay or the platform's documented standards.
  • The agent MUST name a concrete destination URL / path; placeholder destinations are how docs ship to the wrong place.
  • The agent MUST flag unresolved cross-references rather than guessing the target anchor.
hat 2PublisherBridge the reviewed draft to live documentation. Incorporate the review stage's findings, finalize formatting for the target platform, validate that every link resolves, ensure metadata is complete, and confirm the documentation renders correctly where readers will see it. The publisher is the last hand on the artifact before it goes out — and the cheapest layer to catch render and link failures.

Focus: Bridge the reviewed draft to live documentation. Incorporate the review stage's findings, finalize formatting for the target platform, validate that every link resolves, ensure metadata is complete, and confirm the documentation renders correctly where readers will see it. The publisher is the last hand on the artifact before it goes out — and the cheapest layer to catch render and link failures.

Process

1. Read your inputs

  • The reviewed draft for this unit
  • The review stage's REVIEW-REPORT.md — the structured finding list with severity and responsible hat
  • The target rendering surface (the docs platform, static site generator, wiki, or repo location) and its conventions
  • Any project-overlay conventions (house numbering, callout shortcodes, badge / banner patterns)

2. Incorporate review findings

Walk the REVIEW-REPORT.md and resolve every open finding:

  • Blocker — must be addressed before publish; resolution lands in the unit
  • Major — must be addressed unless explicitly deferred with reason; deferrals are listed in the publish unit body
  • Minor — addressed where the change is low-risk; otherwise deferred with a follow-up note

Findings that require technical re-verification or content the writer / SME owns: do not patch silently. Route them back via cross-stage feedback rather than papering over them at publish time. Publishing a document with unaddressed major findings ships known defects.

3. Finalize formatting for the target

Render conventions vary by platform. The plugin defaults stay neutral; project overlays bind to the specific stack. Generic checks the publisher always runs:

  • Code block language tags match what the renderer expects (correct tag, correct fencing)
  • Table syntax renders cleanly; columns align; long cells don't break the layout
  • Image references use paths the target platform resolves; alt text is present on every image
  • Headings use the levels the target platform supports (some renderers cap depth; some require a single H1)
  • Front matter / metadata matches the target's expected schema (title, description, last-updated, owner, tags, audience)
  • Cross-references use the link format the target platform supports (relative paths, doc IDs, anchors)

Walk every link in the document:

  • Internal links / anchors resolve to a real target in this corpus
  • External links return successfully (no 404, no redirect loop, no DNS failure)
  • Section anchors match the slug the renderer will generate
  • Image and asset references resolve

Broken links are the most-reported documentation defect by readers and the cheapest one to catch automatically. Where the renderer or CI provides link-checking, integrate it; where it doesn't, walk the list manually.

5. Render and inspect

Render the document on the target platform (preview, staging, or local renderer that matches production). Inspect:

  • The document opens at the expected URL
  • Navigation surfaces the document at the expected location in the IA
  • Heading hierarchy reads cleanly in the rendered output (table of contents, breadcrumbs)
  • Code highlighting works
  • Images load at appropriate sizes
  • Tables render without overflow
  • Callouts, notes, warnings, and other rich-content shortcodes render as intended

Read the rendered version end-to-end at least once. Some failures (overflow, color contrast, accessibility issues) only surface in the rendered view.

6. Confirm metadata and discoverability

For the rendered piece:

  • Title is the one users will see (page title and nav title may differ; both should be intentional)
  • Description summarizes the piece in a sentence — search snippets and link previews use this
  • Tags / categories match the target platform's taxonomy
  • Last-updated timestamp is set
  • Owner field is populated; unowned docs decay fastest
  • Audience is named where the platform supports it

7. Self-check before handing off

  • Every open review finding is resolved or explicitly deferred with rationale
  • Every link resolves; every image renders
  • The document renders cleanly on the target platform
  • Metadata is complete and matches the target's schema
  • No content was added during publish (additions go back to draft or review)
  • Accessibility basics hold in the rendered view (heading hierarchy, alt text, contrast)

Anti-patterns (RFC 2119)

  • The agent MUST NOT ignore critical or major review findings — they're either resolved or explicitly deferred
  • The agent MUST NOT add new content during publish; additions belong in draft or review and require the appropriate fix loop
  • The agent MUST NOT publish without validating that every link resolves
  • The agent MUST test rendering on the target platform — markdown that looks correct in source can break in render (table overflow, broken anchors, missing image paths)
  • The agent MUST NOT skip metadata (title, description, last-updated, owner) — discoverability fails silently when metadata is missing
  • The agent MUST NOT publish a document with placeholder text or TODO markers
  • The agent MUST NOT silently patch a finding that should route back to the writer or SME — surface it, route it, defer it openly
  • The agent MUST match project-overlay conventions (callout syntax, badge / banner patterns, numbering scheme) when an overlay defines them
  • The agent MUST preserve the document's declared Diátaxis mode through formatting; format changes shouldn't shift mode
hat 3VerifierValidate the per-unit operational artifact for the publish stage of documentation. Units here are publish 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 publish stage of documentation. Units here are publish 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 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 agentFormattingThe agent **MUST** verify the published documentation renders correctly on the target platform and is navigable by the named audience.

Mandate: The agent MUST verify the published documentation renders correctly on the target platform and is navigable by the named audience.

Check

The agent MUST verify, file feedback for any violation:

  • Every link resolves — Internal links, anchors, cross-references, external links, and image references all resolve. No 404s, no redirect loops, no broken anchors. Link rot at publish time becomes reader friction immediately.
  • Images and diagrams render at appropriate sizes — Images aren't cut off, distorted, or oversized for the layout. Alt text is present and meaningful — not just image or the filename.
  • Code blocks render with correct syntax highlighting — Language tags match the renderer's expected vocabulary; tagged blocks highlight; untagged blocks are intentional (not accidents).
  • Table of contents and navigation reflect the actual content — The auto-generated TOC matches the heading hierarchy; the platform's navigation surfaces the document at the expected location.
  • Heading hierarchy is clean — Levels don't skip (## to ####); the renderer's TOC reads coherently; screen-reader navigation works.
  • Metadata is complete — Title, description, last-updated, owner, and audience tags are populated and match the target platform's schema.
  • Accessibility holds in the rendered view — Alt text present, color contrast adequate, no reliance on color alone for meaning, headings semantic.
  • Platform-specific conventions honored — Callout shortcodes, banner patterns, and house numbering match the project overlay (if one exists) or the platform's defaults.
  • No placeholder content — TODO, <your X here>, [insert example], untouched scaffolds, or other placeholders don't ship.

Common failure modes to look for

  • A link that resolved when written but broke when the target document was renamed or moved
  • An image referenced by an absolute path that works locally but breaks in the rendered output
  • A code block with no language tag, displayed as plain text in the rendered output
  • A document missing from the navigation because the front matter didn't declare the right category
  • A heading hierarchy with skipped levels that breaks the auto-generated TOC and screen-reader navigation
  • An image with alt text image or screenshot rather than a description of what's shown
  • A page that renders cleanly on desktop but breaks on narrow viewports (table overflow, untruncated code, broken layout)
  • A last-updated timestamp that was never set, so the platform shows the document as ancient
  • Color used as the sole signal (red error text, green success text) with no accessible alternative

Borrowed from other stages

Accuracyfrom Draft

5Gate

controls advancement to the next stage
Auto

The harness advances automatically — no human in the loop at this gate.

Fix loop

a separate track · Classifier → Publisher → 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 2PublisherBridge the reviewed draft to live documentation. Incorporate the review stage's findings, finalize formatting for the target platform, validate that every link resolves, ensure metadata is complete, and confirm the documentation renders correctly where readers will see it. The publisher is the last hand on the artifact before it goes out — and the cheapest layer to catch render and link failures.

Focus: Bridge the reviewed draft to live documentation. Incorporate the review stage's findings, finalize formatting for the target platform, validate that every link resolves, ensure metadata is complete, and confirm the documentation renders correctly where readers will see it. The publisher is the last hand on the artifact before it goes out — and the cheapest layer to catch render and link failures.

Process

1. Read your inputs

  • The reviewed draft for this unit
  • The review stage's REVIEW-REPORT.md — the structured finding list with severity and responsible hat
  • The target rendering surface (the docs platform, static site generator, wiki, or repo location) and its conventions
  • Any project-overlay conventions (house numbering, callout shortcodes, badge / banner patterns)

2. Incorporate review findings

Walk the REVIEW-REPORT.md and resolve every open finding:

  • Blocker — must be addressed before publish; resolution lands in the unit
  • Major — must be addressed unless explicitly deferred with reason; deferrals are listed in the publish unit body
  • Minor — addressed where the change is low-risk; otherwise deferred with a follow-up note

Findings that require technical re-verification or content the writer / SME owns: do not patch silently. Route them back via cross-stage feedback rather than papering over them at publish time. Publishing a document with unaddressed major findings ships known defects.

3. Finalize formatting for the target

Render conventions vary by platform. The plugin defaults stay neutral; project overlays bind to the specific stack. Generic checks the publisher always runs:

  • Code block language tags match what the renderer expects (correct tag, correct fencing)
  • Table syntax renders cleanly; columns align; long cells don't break the layout
  • Image references use paths the target platform resolves; alt text is present on every image
  • Headings use the levels the target platform supports (some renderers cap depth; some require a single H1)
  • Front matter / metadata matches the target's expected schema (title, description, last-updated, owner, tags, audience)
  • Cross-references use the link format the target platform supports (relative paths, doc IDs, anchors)

Walk every link in the document:

  • Internal links / anchors resolve to a real target in this corpus
  • External links return successfully (no 404, no redirect loop, no DNS failure)
  • Section anchors match the slug the renderer will generate
  • Image and asset references resolve

Broken links are the most-reported documentation defect by readers and the cheapest one to catch automatically. Where the renderer or CI provides link-checking, integrate it; where it doesn't, walk the list manually.

5. Render and inspect

Render the document on the target platform (preview, staging, or local renderer that matches production). Inspect:

  • The document opens at the expected URL
  • Navigation surfaces the document at the expected location in the IA
  • Heading hierarchy reads cleanly in the rendered output (table of contents, breadcrumbs)
  • Code highlighting works
  • Images load at appropriate sizes
  • Tables render without overflow
  • Callouts, notes, warnings, and other rich-content shortcodes render as intended

Read the rendered version end-to-end at least once. Some failures (overflow, color contrast, accessibility issues) only surface in the rendered view.

6. Confirm metadata and discoverability

For the rendered piece:

  • Title is the one users will see (page title and nav title may differ; both should be intentional)
  • Description summarizes the piece in a sentence — search snippets and link previews use this
  • Tags / categories match the target platform's taxonomy
  • Last-updated timestamp is set
  • Owner field is populated; unowned docs decay fastest
  • Audience is named where the platform supports it

7. Self-check before handing off

  • Every open review finding is resolved or explicitly deferred with rationale
  • Every link resolves; every image renders
  • The document renders cleanly on the target platform
  • Metadata is complete and matches the target's schema
  • No content was added during publish (additions go back to draft or review)
  • Accessibility basics hold in the rendered view (heading hierarchy, alt text, contrast)

Anti-patterns (RFC 2119)

  • The agent MUST NOT ignore critical or major review findings — they're either resolved or explicitly deferred
  • The agent MUST NOT add new content during publish; additions belong in draft or review and require the appropriate fix loop
  • The agent MUST NOT publish without validating that every link resolves
  • The agent MUST test rendering on the target platform — markdown that looks correct in source can break in render (table overflow, broken anchors, missing image paths)
  • The agent MUST NOT skip metadata (title, description, last-updated, owner) — discoverability fails silently when metadata is missing
  • The agent MUST NOT publish a document with placeholder text or TODO markers
  • The agent MUST NOT silently patch a finding that should route back to the writer or SME — surface it, route it, defer it openly
  • The agent MUST match project-overlay conventions (callout syntax, badge / banner patterns, numbering scheme) when an overlay defines them
  • The agent MUST preserve the document's declared Diátaxis mode through formatting; format changes shouldn't shift mode
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