Client Approval States و Revision Branching

1) Why an Approved flag is not enough

Real client feedback arrives through comments, email, chat, review tools and meetings. If every result is collapsed into one mutable Approved=true field, the team quickly loses the answer to four basic questions: who approved, exactly which revision, for what scope, and under what authority? A later edit can then inherit an approval the client never gave.

This lesson builds Client Approval Revision Branch Ledger v1: a bounded auditable record that binds approval, rejection and change requests to an exact revision, branch lineage, reviewer role, authority and rationale.

Core rule: approval is not a floating property of an item; it is a decision record about a specific revision.

2) Lesson boundary

COM-018 owns Client Approval States and Revision Branching. COM-017 owns Content Workflow States, and COM-019 owns the Safe Workflow Lab. This lesson does not redesign the full workflow or the safety harness; it focuses on when a client decision remains valid or becomes stale as revisions and branches change.

It also does not create real client authority, legal authority, production publication rights, billing changes or tenant access. It produces an evidence-backed decision model only.

3) Mental model: Case → Revision → Authority → Decision → Branch → Fresh Review

Each approval case should preserve at least:

1. approval_case_id;
2. content_item_id;
3. explicit baseline and branch;
4. revision_id and revision_digest;
5. reviewer identity and role;
6. decision_authority;
7. decision state;
8. scope and rationale;
9. requested changes;
10. supersession relation;
11. conflict/reopen state;
12. audit event and evidence reference.

If decisive evidence is missing, do not coerce the case into Approved. HOLD, DISPUTED and BLOCKED states are part of a correct system.

4) Separate external facts from MAKNOW design

Current Contentful documentation shows that workflow steps can restrict who may edit, publish or move between steps. Workflows can also move content forward or back for further revisions. Those are platform facts.

They do not define MAKNOW branch names, approval-state vocabulary or merge semantics. Binding a client decision to a precise revision and requiring fresh review after invalidating edits are MAKNOW design rules.

5) Bind approval to revision identity

Keep two concepts explicit:

• revision_id: the logical revision identifier;
• revision_digest: a fingerprint of the content represented by that revision.

If a client approves r17 and the item changes afterward, the decision must not silently carry to r18 or a new digest. Stable item title or URL does not preserve approval evidence.

The ledger therefore treats revision mismatch as BLOCKED_STALE_APPROVAL, not as “close enough to approved.”

6) Branch lineage prevents cross-branch approval reuse

Imagine two sibling branches from the same baseline: one for creative changes and one for a legal correction. Approval on the creative branch does not automatically authorize the legal sibling, even if the diff is small.

branch_id, branch_parent and merge_target must remain traceable. Reusing a decision from another branch should produce BLOCKED_CROSS_BRANCH_APPROVAL and require a new evidence-backed transition.

7) Role is not decision authority

A reviewer may be an Editor, Designer or Legal Reviewer without having authority to issue or supersede the client's final decision. reviewer_role describes function; decision_authority records whether this actor may make that decision.

If an unauthorized reviewer supersedes a client decision, the ledger should block it. UI access, seniority or familiarity with the project is not authority evidence.

8) Use operationally meaningful states

The bounded state vocabulary for this lesson includes:

• APPROVED_REVISION_BOUND;
• CHANGES_REQUESTED;
• REJECTED;
• HOLD_MISSING_EVIDENCE;
• BLOCKED_STALE_APPROVAL;
• BLOCKED_CROSS_BRANCH_APPROVAL;
• BLOCKED_UNAUTHORIZED_SUPERSESSION;
• DISPUTED_CONFLICT;
• PARTIAL_SCOPE_REOPENED.

This vocabulary is intentionally local to the outcome of COM-018; it does not claim ownership of the whole workflow state machine.

9) Preserve conflict and supersession history

When reviewers disagree, overwriting the prior decision destroys auditability. A later decision should reference supersedes_decision_id, while the earlier decision remains traceable.

If conflict_state=OPEN, the branch is not ready to merge as a final approval. It should remain DISPUTED_CONFLICT until a documented resolution exists.

10) Change requests need identifiers and scope

requested_change_ids should not be an ambiguous sentence like “make it better.” Each requested change should have an identifier, scope and rationale so the system can determine which part of the previous approval was invalidated.

When only part of the content changes, accepted scope can remain preserved while the affected scope is reopened. This is the practical value of revision branching.

11) Lab: eight fixtures across failure paths

The lab is offline, synthetic and contains no credentials. Eight fixtures each evaluate six deterministic invariants for 48 assertions total.

Mutations include an edit after approval without fresh review, approval copied to a sibling branch, unauthorized supersession, missing evidence, unresolved conflicts, premature merge and a legal-clause transfer case.

The objective is not merely a green baseline. The learner must diagnose why shortcuts become blocked, disputed or partial.

12) Transfer: reopen only the invalidated scope

Transfer scenario: a client approves an entire campaign bundle, then a legal reviewer reopens one clause. A weak design either leaves the whole approval untouched or sends the entire bundle back through review.

The bounded design preserves unaffected accepted scope, creates a new revision branch for the reopened clause, records the reopen_reason and requested change, and requires fresh approval only for the invalidated scope. Final merge waits for that scope to resolve.

This fixture should produce PARTIAL_SCOPE_REOPENED, not full approval and not a full reset.

13) Summary and pass criteria

Client approval becomes trustworthy when a mutable status flag is replaced with a versioned, authority-bound decision record. Passing this lesson means demonstrating exact revision/digest binding, explicit branch lineage, valid reviewer authority, preserved conflicts, traceable requested changes and fresh review after an invalidating edit.

The final artifact is Client Approval Revision Branch Ledger v1. It is not publication or release authority.

References and freshness

• Contentful Help Center, Workflows — rechecked 2026-09-15.
• Contentful Help Center, Workflow rules: editing and publishing permissions — rechecked 2026-09-15.
• Contentful Help Center, Workflow step change permissions — rechecked 2026-09-15.
• Revision binding, branch semantics, supersession and partial-scope reopen are MAKNOW DESIGN rules, not vendor mandates.