Recommendations

A recommendation is a versioned work item with evidence, impact, confidence, effort, drafts, reviews, and an append-only transition history.

​

Canonical lifecycle

The only active states are proposed, todo, in_review, done, and archived. Restore returns an item archived from an initial proposed or migrated rejected state to proposed. Other archived items return to todo. Every transition includes the expected status, expected state version, and an idempotency key. A stale client receives a conflict instead of overwriting a newer action.

​

Board and drag behavior

The board shows four active columns: Proposed, Todo, In review, and Done. The archive has a separate view. Drag and drop supports pointer, touch, and keyboard interaction, but it applies the same transition rules as explicit buttons. Moving an item to In review requires a current draft. Moving it to Done requires review evidence.

​

Drafts and reviews

Drafts are immutable. A newer draft supersedes the previous current draft without changing its contents. Version 2 drafts require validation steps. A copy_prompt must contain a nonempty prompt. The content hash covers content, provenance, evidence, model, prompt version, pricing, and source digests. Reviews record approved, changes_requested, or rejected. Compliance-flagged work cannot be submitted without the latest approved review or an explicit approval that creates one.

​

Volume generation

Generation has separate SEO and GEO lanes. Open volume counts Proposed, Todo, and In review. Durable canonical keys prevent duplicate work across generation runs. Candidates are ranked by impact, confidence, and effort. The SEO lane reserves for a worst case of up to 40 OpenRouter calls because each of 20 candidates can require copy work and eligible blog items can require full content. The current GEO generation job does not reserve provider cost. Recommendation generation uses the same workspace job slot as measurement, research, and SEO refresh. Start it after the other job has settled.

​

Humanizer style contract

All suggested text generated by this subsystem binds to humanizer-v1. The prompt build fails if that contract is missing. Generated copy must:

• Use plain, direct language
• Preserve technical terms that carry meaning
• Avoid unsupported claims, figures, quotations, and citations
• Tie factual statements to the supplied evidence
• Keep validation steps explicit

This is a generation contract, not a substitute for human review.

​

Stale work

The system can reopen an In review item when fresh evidence shows that its submitted snapshot is stale. This is a system-only transition and must include the evidence that triggered it.