headline-options: scored headline candidates in the editor

A WordPress plugin that, on a click, asks a model for several headline candidates and scores each one and the current headline with plain rules. It never changes a headline on its own. Written from scratch from an idea, v0.1.0.

headline-options is a WordPress plugin that, on a click in the editor, asks a language model for several headline candidates, scores each one and the current headline with plain rules, and shows them side by side. It is for editors who want options and a way to judge them. Licence MIT. Version v0.1.0, released 18 November 2026.

It was written from scratch from an idea, as one of the utilities described on the engineering blog. It has not run on a live site, and the PRD claims no numbers from a deployment.

The problem

An editor writes one headline, often in a hurry, and publishes it. Nobody sees the better ones that were never written. When an editor does ask a model for headlines, the usual tools make two mistakes. They overwrite the title field without asking, so a draft headline is lost and an unchecked line goes live. Or they return ten lines with no way to tell a sound headline from a clickbait one.

A model also invents. A headline that says “12 dead” over a report that says “at least ten” is a correction waiting to happen. So is a headline that names a minister the article never mentions. Plain rules catch most of this without a second model call.

Length is easy to count wrongly. The sibling script-share project measured that a large share of the code points in a plain Hindi news sentence are combining marks. A limit written in code points cuts Indic headlines far shorter than a reader sees them. This plugin counts grapheme clusters.

What it does

  • Generates three to ten candidates per click, with a JSON schema, from the on-screen article text.
  • Scores every candidate and the current headline from 0 to 100 with ten transparent rules, and shows a band (good from 75, fair from 50, weak below) and a “Why” list.
  • Scores a headline you type, with no model call and no cost.
  • Lets the editor press Use, which puts a candidate in the title field, unsaved.
  • Offers WP-CLI commands for status, scoring, generation and stored sets.

How it works

The click calls a REST route, POST /headline-options/v1/posts/{id}/generate, which needs a nonce and the edit_post capability. The plugin converts the article to plain text, with shortcodes stripped and never run. It refuses articles under a minimum word count before any spend, takes a per-post lock, checks the caps, asks spend-meter if it is active, and makes one call through llm-json-php or through a caller you supply. It then cleans, de-duplicates and scores the candidates and stores the last five sets per post as protected post meta.

Each scoring rule returns pass, warn, fail or not applicable with a one-line reason. Pass earns the full weight, warn half, fail nothing, and not applicable counts neither way. The rules are length (weight 25), clickbait (20), numeral_support (20), entity_support (20), script_match (10), and the smaller withheld_subject, numeral_presence, shouting, punctuation and emoji (5 each). numeral_support requires every number in the headline to appear in the article, compared as digit strings after native digits are mapped and grouping such as 1,00,000 is removed. entity_support requires every name to appear in the article.

A custom rule is a class implementing IndianOpinion\HeadlineOptions\Scoring\Rule, added through the headline_options_rules filter. Scoring works without WordPress:

php examples/score-without-wordpress.php

Guard rails

  • Nothing runs on save, publish, import or cron. The plugin hooks no post lifecycle action.
  • The plugin never writes post_title, the slug, the excerpt or a revision. Use edits editor state only, and the editor’s own undo reverts it.
  • Generation is off on install. The constant HEADLINE_OPTIONS_DISABLED forces it off on every site.
  • Defaults are 50 generations a day for the site, 15 per user and 4 a minute per user. Setting a cap to 0 turns generation off. A call counts when it is attempted, because a failed call may still be billed.
  • Caps live in one option row changed only while a lock row is held, taken with INSERT IGNORE, so two requests at cap minus one cannot both pass.
  • Generation fails closed, so any failure leaves the headline alone. Scoring fails open, so a broken rule is reported as not applicable and the others still run.
  • Scores are advice. They never hide, block or reorder the current headline, and measure craft and accuracy signals, not clicks.
  • No reader data, user email, author name or user id is sent to the provider.

What review changed

An independent review of the build PR fixed these before the merge.

  • Lock rows could be freed by the wrong request. A request whose lock had expired and been taken over could release the new holder’s lock and let a third request past the cap. Lock rows now carry an owner token.
  • Prompt injection. Entities are decoded, so an escaped closing tag in an article became a real one and could end the data block. Block tags inside values are now removed.
  • The label-prefix rule accepted a bare hyphen, so “Option-trading volumes…” lost its first word. A dash now needs a space before it.
  • headline_options_generate() skipped the capability and edit_post checks that the REST route applies. It now applies the same checks.

The review also fixed backslashes in model output being lost on save, a provider key option that autoloaded, and two debounce timers in the editor panel that cancelled each other.

Limits and what is next

  • Entities are found by plain rules. In scripts without case, only tags, categories, Latin words and names you supply are checked.
  • The clickbait, withheld-subject and number-word lists are English only. Add yours through filters.
  • Without ext-intl, length is code points less combining marks, which is close to but not exactly what a reader sees for some conjuncts.
  • The script check needs script-share, otherwise that rule is not applicable.
  • Caps count generations, not money. SEO titles, social titles and slugs are out of scope.

No issues are open on the repo. Test status: this is v0.1.0. 151 PHPUnit tests with 1,186 assertions and 10 of 10 Node tests pass, with PHPStan level 8 and phpcs clean. WordPress and model calls are tested against stubs and mocks. CI has not yet run on GitHub, and it has no production mileage.

Install

It needs WordPress 6.4 or later and PHP 8.1 or later with mbstring. The sibling packages are not on Packagist yet, so add them as VCS repositories.

composer config repositories.llm-json-php vcs https://github.com/IndianOpinion/llm-json-php
composer config repositories.headline-options vcs https://github.com/IndianOpinion/headline-options
composer require indianopinion/headline-options

All 47 utilities · headline-options on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.