Skip to content
SapphireIT Labs
Editorial Workflow documentation

How the workflow works

The editorial state machine: the statuses, the legal moves between them, who may make each one, and what each flow looks like end to end.

Everything here is enforced in PHP. The sidebar and the dashboard only render what WorkflowManager told them is currently possible.

  • Statuses live in Sit_CwmWorkflowStatusManager (decision D3).
  • Edges live in Sit_CwmWorkflowTransitionManager::MAP (D4).
  • Capabilities live in Sit_CwmWorkflowPermissionManager (D5).

The status graph

        ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
          draft     every managed post starts here
        ÔööÔöÇÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔöÇÔöÿ
             Ôöé
             Ôû╝
        ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
   ÔöîÔöÇÔöÇÔöÇÔû║Ôöé writing ÔöéÔùäÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
   Ôöé    ÔööÔöÇÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔöÇÔöÿ                       Ôöé
   Ôöé         Ôöé                            Ôöé
   Ôöé         Ôû╝                            Ôöé
   Ôöé    ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ                       Ôöé
   Ôöé    Ôöé review  Ôöé                       Ôöé
   Ôöé    ÔööÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÿ                       Ôöé
   Ôöé       Ôöé   Ôöé                          Ôöé
   Ôöé       Ôöé   ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ               Ôöé
   Ôöé       Ôû╝              Ôû╝               Ôöé
   Ôöé  ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ   ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ    Ôöé
   Ôöé  Ôöé approved ÔöéÔöÇÔöÇÔû║Ôöé needs_changes Ôöé    Ôöé
   Ôöé  ÔööÔöÇÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ   ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔö¼ÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ    Ôöé
   Ôöé       Ôöé                 Ôöé            Ôöé
   Ôöé       Ôöé                 ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ
   Ôöé       Ôû╝
   Ôöé  ÔöîÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÉ
   ÔööÔöÇÔöÇÔöé published Ôöé   (final ÔÇö starts a new cycle by going back to writing)
      ÔööÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÇÔöÿ

Read as a table:

FromMay move to
draftwriting
writingreview
reviewapproved, needs_changes
needs_changeswriting
approvedpublished, needs_changes
publishedwriting

Rules that hold for every edge:

  • No self-transitions. writing ÔåÆ writing is invalid, not a no-op.
  • Any pair not in the table is invalid, whatever capabilities the user holds. An administrator cannot jump draft ÔåÆ approved.
  • The graph is data, not code. sit_cwm_transition_map can replace it wholesale; the result is validated against the status registry, so a filter cannot introduce an unknown status or a self-transition.

Rollbacks

Three edges send content backwards. They are the same edges as above, flagged separately (TransitionManager::ROLLBACKS, filter sit_cwm_rollback_transitions) so the UI can style them as destructive and ask for a confirmation:

FromRollback toMeaning
reviewneeds_changesReviewer sends it back.
approvedneeds_changesApproval withdrawn before publishing.
publishedwritingStart a new editing cycle on live content.

Each transition the API returns carries is_forward and is_rollback, so a client never has to know the graph to style a button.


Who may reach each status

Reaching a status requires all of:

  1. A logged-in user who exists.
  2. A post that exists, whose type is workflow-enabled, and that the user can read.
  3. WordPress’ own edit_post on that specific post.
  4. The capability mapped to the target status:
Target statusCapabilityPlus
draftsit_cwm_change_workflow
writingsit_cwm_change_workflow
reviewsit_cwm_change_workflow
needs_changessit_cwm_review_content
approvedsit_cwm_approve_content
publishedsit_cwm_approve_contentWordPress publish_post on the post
  1. For approved only, while self-approval is prevented: the user is not the post’s author (see Self-approval).
  2. A true return from the sit_cwm_can_transition filter, which runs last and has the final say over steps 3ÔÇô5. It cannot override steps 1ÔÇô2.

Note that the capability is keyed to the target, not to the edge. Moving approved  needs_changes needs sit_cwm_review_content, the same as review  needs_changes, because both land on needs_changes.

What that means per role, with the default grants

DraftWritingReviewNeeds ChangesApprovedPublished
Administrator
Editor
Authorﯔﯔﯔ
Contributorﯔﯔﯔ
SubscriberÔØîÔØîÔØîÔØîÔØîÔØî

Ô£à here means “holds the capability” ÔÇö the per-post edit_post check still applies. A contributor holds sit_cwm_change_workflow, but WordPress only grants them edit_post on their own unpublished posts, so in practice they move their own drafts and nothing else. An author cannot publish_post on someone else’s post either, whatever sit_cwm_approve_content says.

The other capabilities

CapabilityGrants
sit_cwm_assign_reviewerSet or clear the reviewer and the due date.
sit_cwm_view_activityRead the activity timeline and post workflow comments.
sit_cwm_manage_workflowsThe settings page, and attempting bulk actions.

sit_cwm_manage_workflows gates only the attempt at a bulk action. Every post in a batch is authorized individually, exactly as if the requests had been sent one at a time.

Who can be a reviewer

Only a user who holds sit_cwm_review_content. Assigning anyone else fails with sit_cwm_invalid_user (400), single or bulk. With the default grants that means editors and administrators.

While self-approval is prevented, the post’s author is also left out of its reviewer list and cannot be assigned (sit_cwm_invalid_user, 400).

Self-approval

Since 1.1. Off by default, on fresh installs and upgrades alike. When Prevent people from approving their own content is ticked (Settings  Publish gate), nobody can move a post to approved if they are its post_author.

  • Every route. The rule lives in PermissionManager::can_change_status(), before sit_cwm_can_transition, so it covers the sidebar, the classic meta box, the dashboard bulk action, sit-cwm/v1 REST and the batch route. A refusal is sit_cwm_self_approval (403) instead of the generic sit_cwm_forbidden, and Approve is not offered. The panel then says You can’t approve your own content. Another reviewer has to approve it.
  • Only approved. The author can still send their own post to Review, Needs Changes and so on, as their capabilities allow.
  • Administrators are bound too. With the gate set to Enforce they can still publish unapproved content through sit_cwm_bypass_publish_gate, and that is recorded as a publish without approval, so a one-person site is never stuck.
  • “Author” means post_author. Someone who rewrote a post they are not the author of is not caught.
  • Reviewer list. The author is left out of the assignable reviewers for their own post and cannot be assigned. An assignment made before the setting was turned on is kept; that reviewer just cannot approve.
  • Filter. sit_cwm_prevent_self_approval( bool $prevent, int $post_id ) varies the rule per post. Only boolean true prevents.

Choosing which roles may approve is not a setting of the free plugin. sit_cwm_approve_content is a normal WordPress capability, so a role-editor plugin can grant or remove it.


Worked examples

1. The approval flow

A staff writer drafts a post; an editor reviews and approves it.

#ActorActionStatus afterActivity logged
1AuthorCreates the post.draftÔÇö (implicit default)
2AuthorClicks Start writing.writingstatus_changed draft  writing
3EditorAssigns themselves as reviewer, due Friday.writingreviewer_assigned, due_date_set
4AuthorClicks Send for review.reviewstatus_changed writing  review
5EditorReads it, comments “Ship it.”reviewcomment_added
6EditorClicks Approve.approvedstatus_changed review  approved
7EditorClicks Mark published.publishedstatus_changed approved  published

Step 7 does not publish the post. The WordPress post status is untouched; someone still hits Publish in the editor. The workflow status records that the editorial process finished, and those two facts are allowed to disagree ÔÇö see ARCHITECTURE.md. With the publish gate set to Enforce, Publish only becomes available from step 6 on.

With review attestation required, step 6 has one more action: the editor ticks I confirm I have reviewed this content and approve it for publication. before Approve becomes available, and the status_changed row stores that statement.

At step 2, the author’s sidebar offers exactly one button. The graph allows only draft ÔåÆ writing, so there is nothing else to offer ÔÇö not because the UI hides it, but because available_transitions came back with one entry.

2. The send-back flow

Same post, but the editor wants changes.

#ActorActionStatus afterActivity logged
1ÔÇô4As above.review
5EditorComments “The intro buries the lede.”reviewcomment_added
6EditorClicks Request changes (a rollback  the UI confirms first).needs_changesstatus_changed review  needs_changes
7AuthorRewrites, clicks Resume writing.writingstatus_changed needs_changes  writing
8AuthorClicks Send for review.reviewstatus_changed writing  review

The author cannot perform step 6 themselves. While the post sits at review, its only outgoing edges are approved and needs_changes, which need sit_cwm_approve_content and sit_cwm_review_content respectively ÔÇö neither of which an author holds. available_transitions comes back empty and the sidebar shows no status buttons at all. The post is parked with the reviewer, which is the point.

3. The re-review flow

Content that was already published needs a correction.

#ActorActionStatus after
1EditorPost is live, workflow at published.published
2EditorClicks Start new cycle (a rollback ÔÇö confirmed).writing
3AuthorEdits, Send for review.review
4EditorApprove.approved
5EditorMark published.published

Throughout, the post stays publicly published. The workflow cycles underneath it. This is the scenario the separate-status design exists for: collapsing the two fields would mean either un-publishing live content to edit it, or losing the record that a second review happened.

4. Approval withdrawn

#ActorActionStatus after
1EditorApproves.approved
2Editor-in-chiefSpots a problem, clicks Request changes.needs_changes
3AuthorResume writing.writing

approved  needs_changes exists precisely so that withdrawing an approval does not require a trip back through review.


Concurrency

Two editors on the same post is normal, so a status change is conditional. The client sends the status it believed was current:

POST /wp-json/sit-cwm/v1/posts/125/workflow
{ "from": "review", "status": "approved" }

If the stored status is no longer review ÔÇö someone sent it back while this editor was reading ÔÇö the request fails with sit_cwm_status_conflict (409) and nothing is written. The UI refetches and shows the real state rather than silently clobbering the other person’s decision.

The check is application-level, not a database lock: it closes the read-modify-write window that the UI opens, not a simultaneous-write race between two PHP processes. See ARCHITECTURE.md.


Publishing and the publish gate

Workflow status and WordPress post status stay separate fields: publishing a post never changes its workflow status, and reaching published in the workflow never publishes the post. What the publish gate adds is a rule between them: optionally, WordPress may not make content live until its workflow says it was approved.

Modes

Each workflow-enabled post type has its own mode, set under Editorial Workflow  Settings  Publish gate and stored in sit_cwm_settings under publish_gate.

ModeRule checked?Publishing restricted?What is recorded
Off (default)nonoNothing from the gate. Publications are still logged (below).
Log onlyyesnoA publish that fails the rule: publish_gate_bypassed, reason log_only.
EnforceyesyesA refused attempt: publish_gate_refused. A publish by someone holding the bypass capability: publish_gate_bypassed, reason capability.

A missing or unknown mode, and a post type that is no longer workflow-enabled, both count as Off. Upgrading from 1.0 therefore leaves every type at Off. The sit_cwm_publish_gate_mode filter can change the mode per post type (and receives the post id, or 0 when the question is not about one post).

The rule

A publish attempt passes when the post’s stored workflow status is approved or published. Anything else fails, including an unknown stored status and a brand-new post, which starts at draft.

The result goes through sit_cwm_publish_gate_passes( $passes, $post_id, $workflow_status, $mode ). Only boolean true passes; false and a WP_Error both fail.

When the gate judges a write

Only a write that moves content into a published state is judged. All of these must hold:

  1. The post type is workflow-enabled and its mode is not Off.
  2. Either the target post status is publish and the stored one is not publish, or the target is future and the stored one is neither publish nor future.
  3. The write is not an autosave or a revision.

So:

  • Live content is never taken down by the gate. A published post that goes back to writing or review for a correction stays publish through every later Update, Quick Edit or REST save. This is the carve-out that the re-review flow depends on.
  • An already scheduled post is not re-judged on unrelated edits. It is judged again at go-live, when cron publishes it. A post scheduled while approved and then sent back to needs_changes does not go live.
  • private is not gated.

What happens on a refusal

PathWhat the user sees
Block editorThe Publish / Schedule button becomes Submit for Review, and the workflow panel says Publishing is locked until this content is approved. No JavaScript from the plugin is involved: the wp:action-publish link core’s editor reads is removed from the REST response.
wp/v2 REST create or update403 with code sit_cwm_publish_gated. Nothing is written.
Classic editor, Quick Edit, Bulk Edit, wp_insert_post() / wp_update_post() from any code, WP-CLI wp post create|updateThe save goes through, but as draft (or pending, when that is what was stored) instead of publish/future. An admin notice tells the person on their next screen: “ÔǪ” was not published: it has to be approved in the editorial workflow first.
Scheduled publishing (cron)The post is set back to draft before core publishes it, and the post’s author gets the same admin notice.
Anything else that makes a post publish (e.g. wp_publish_post() on a draft)The backstop puts it back to draft straight after the transition, and notifies the actor (or the author, when there is no actor).

Who is judged: the logged-in user. Scheduled publishing, other cron jobs and WP-CLI without --user run as user 0, who never holds the bypass capability, so in Enforce they are refused. Run imports as an administrator: wp --user=<admin> .

The bypass capability

sit_cwm_bypass_publish_gate lets its holder publish unapproved content while the gate is set to Enforce. Administrators get it (on activation, and on upgrade from 1.0 without reactivation); no other role does. In the editor they see This content is not approved yet. You can still publish it, and that will be recorded as a bypass of the review.

Every use is recorded as publish_gate_bypassed, reason capability, when the post actually goes live, not when it is scheduled. Scheduling unapproved content under the bypass stores the scheduler’s user id in _sit_cwm_publish_bypass_by; at go-live the bypass is honoured only if that user still holds the capability. The marker is deleted whenever the post leaves future.

Failing open

Every gate layer runs inside a try/catch. If one throws, the publish goes ahead rather than locking the site, and it is recorded as publish_gate_bypassed with reason error (when the post id is known). The sit_cwm_publish_gate_failed action fires, and with WP_DEBUG on the error is written to the PHP error log.

What the gate covers

The block editor, the classic editor, Quick Edit, Bulk Edit, the wp/v2 REST API (including application passwords), WP-CLI wp post create|update, scheduled publishing, and any plugin that publishes through wp_insert_post(), wp_update_post() or wp_publish_post(). Code that asks current_user_can( 'publish_post', $id ) gets an answer that agrees with the gate. Which layer covers which path is in ARCHITECTURE.md.

What the gate does not cover

Stated plainly, because a governance claim is only worth what it does not overstate:

  • Direct database writes. Code that updates wp_posts.post_status through $wpdb (or any SQL) never passes a WordPress hook, so the gate cannot see it. Neither the publication log nor the gate records it.
  • Code that removes the plugin’s hooks, e.g. remove_all_filters( 'wp_insert_post_data' ).
  • private content. Making content private is not gated.
  • Post types without a workflow, or with the gate set to Off.
  • The backstop acts after the fact. A path that only the backstop catches (one that skips wp_insert_post_data, like wp_publish_post()) does reach publish for a moment before it is reverted, so hooks other plugins run on that transition (social sharing, pings, caches) may already have fired.
  • A refused REST create is not recorded. A wp/v2 request that tries to create content as publish is refused before the post exists, so there is no post to record the refusal against. A refused create through wp_insert_post() (including WP-CLI) is saved as a draft and recorded under its new id.

Governance: AI use, attestation, disclosure and the report

Since 1.2. Each feature is optional and starts off (or, for AI use, “Not declared”), so a site upgraded from 1.1 behaves exactly as before.

AI use

Every workflow item can say how it was made:

ValueLabel
humanHuman-written
ai_assistedAI-assisted
ai_generatedAI-generated
(nothing yet)Not declared

AI use is declared, not detected. The plugin never inspects the text. Someone states the value, and the plugin records who stated it and when.

  • Where: the AI use control in the editor’s Workflow panel (and the classic editor box), with the help text Declare how this content was made. This is recorded in the activity log; it is not detected automatically. Agents and scripts set it through the REST API; see docs/AGENTS.md.
  • Who: anyone who can change the workflow and edit that post: by default authors and contributors on their own content, editors and administrators on everyone’s.
  • Defaults: Workflow ÔåÆ Settings ÔåÆ AI use default picks a value recorded on new content of each type when it is created. Authors can change it; every change is logged. An agent’s own declaration on create wins over the default.
  • Change, never withdraw. Once declared, the value can be changed but not set back to “Not declared”.
  • Logged: each change is an AI use declared entry in the timeline. When the content is published, the publication entry records the AI use at that moment too.

Review attestation

Workflow  Settings  Review attestation  Require approvers to confirm they reviewed the content. When this is on, approving needs an explicit confirmation, which is stored with the approval in the activity log.

  • In the sidebar, the approver ticks the statement I confirm I have reviewed this content and approve it for publication. and only then can click Approve. Bulk approval on the dashboard asks for the same tick once for the whole selection, and records it on every post.
  • An approval without the confirmation is refused with Confirm that you reviewed this content before approving it. A user who may not approve at all is simply refused, as before.
  • In the timeline, an attested approval carries the marker Review confirmed. Approvers may also tick it when it is not required; that is recorded the same way.
  • Only the move to Approved is affected. Developers can require it for some content only with the sit_cwm_require_attestation filter.

Front-end disclosure

Workflow  Settings  Front-end disclosure  Show review disclosures on published content. This enables the Review disclosure block and the [sit_cwm_review_disclosure] shortcode. They show who approved the content and when, plus its declared AI use:

Reviewed by Dana Okafor on 2 November 2026.

This content was generated with AI and reviewed by a person.

The disclosure shows nothing until all of these are true: the setting is on, the content type is in the workflow, the post is published in WordPress, its workflow status is Approved or Published, and an approval is on record. If the approver’s account was deleted, the “Reviewed by” line is left out. With nothing declared, the AI line is left out. The block has two toggles, Show reviewer and date and Show AI use; the shortcode takes reviewer="0" or ai="0" to hide either line.

Governance report

Workflow  Governance report, for administrators (anyone holding both sit_cwm_view_activity and sit_cwm_manage_workflows). Choose Last 30 days, Last 90 days or Last 12 months:

TileWhat it counts
Published after approvalPublications in the period whose content was Approved or Published at that moment, as a share of all publications
Published while the gate was off or logging onlyPublications in the period while the content type’s gate was Off or Log only
Publishing blockedPublishes the gate refused in the period
Published without approvalUnapproved content that went live in the period (Log only, the bypass capability, or a gate failure)
Overdue reviewsContent in the workflow whose due date has passed, right now

Two tables follow: AI use: all workflow content (as declared now) and AI use: published in this period (as declared at publication). “Not recorded” counts publications logged before version 1.2, which did not record AI use.

The same screen, and the dashboard, offer Export activity log (CSV): the whole activity log, every post and every action, for audits and spreadsheets.


What gets recorded

Every successful change writes exactly one row to wp_sit_cwm_activity:

Action slugWritten when
status_changedA transition succeeds. old_value/new_value are the slugs.
reviewer_assignedA reviewer is set. Values are user IDs.
reviewer_clearedThe reviewer is removed.
due_date_setA due date is set or changed.
due_date_clearedThe due date is removed.
comment_addedA workflow comment is posted. message holds the text.
ai_origin_changedSince 1.2. The declared AI use changes. Values are human, ai_assisted, ai_generated (null before the first declaration); the context says how it arrived (workflow, post_api or default).
post_publishedManaged content goes live (publish), in every gate mode including Off. Values are post statuses.
post_unpublishedManaged content stops being live, including to the trash.
publish_gate_refusedThe gate refused a publish or schedule in Enforce.
publish_gate_bypassedUnapproved content went live: in Log only, under the bypass capability, or because a gate layer failed open.

The four publication rows also store, in context, the workflow status at that moment, the gate mode, where the request came from (cron, cli, rest, ajax, admin or other) and, for the gate rows, the layer and the bypass reason. The timeline shows them as Published, Unpublished, Publishing blocked and Published without approval. Since 1.2, post_published and post_unpublished also store the declared AI use at that moment, and an attested approval’s status_changed row stores the statement the approver confirmed.

Rules:

  • A failed workflow change writes nothing ÔÇö no meta, no activity row, no action hook. (A refused publish is the exception: recording it is the point.)
  • A no-op writes nothing. Re-assigning the same reviewer or re-setting the same date returns success and logs nothing.
  • A bulk action writes one row per affected post, not one aggregate row. There is no such thing as a “bulk” activity entry.
  • Rows are never edited or deleted by the plugin. Uninstalling drops the table.

Reading the timeline needs sit_cwm_view_activity plus edit_post on that post.

Last updated:

Black Friday sale

Black Friday: 80% off every Pro plugin

Your first year, on every plan. The coupon is added for you at checkout.

Ends in The offer ends at 00:00 GMT on 5 December 2026.

Claim deal