@maestroagora/agora 1.2.1 → 1.3.0

package/scripts/voice-measure.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+// agora-voice: the measurement engine behind VOICE.
+//
+// `voice build` is a measurement task, not a description task. A model asked to
+// describe an author's voice writes flattery, so every number this tool reports
+// is computed from the corpus by a frozen pipeline and anything the corpus
+// cannot support is written as insufficient data rather than guessed.
+//
+// Profiles are written to ~/.agora/voices/, never inside the skill directory.
+// The documented update path replaces the installed skill directory, so a
+// profile stored there is destroyed silently on the next update.
+
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { buildOverlapIndex, compare, phraseOverlap, renderReport } from "./voice/check.mjs";
+import { measure } from "./voice/features.mjs";
+import { runGates } from "./voice/gates.mjs";
+import { collectCorpus } from "./voice/ingest.mjs";
+import { PIPELINE } from "./voice/pipeline.mjs";
+import { renderProfile } from "./voice/profile.mjs";
+
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+function usage() {
+  return `agora-voice: measure a corpus, write a voice profile, check a draft against one.
+
+Usage:
+  agora-voice build --name <slug> --from <path|url> [--from <path|url>]...
+  agora-voice list
+  agora-voice check --voice <slug> <draft path>
+  agora-voice default --voice <slug>
+
+Options:
+  --name <slug>       Profile slug. Lowercase letters, digits, and hyphens.
+  --from <path|url>   Corpus source. A file, a directory, or an http(s) URL.
+                      Repeatable. Directories expand to readable text files.
+  --register <name>   Label applied to every --from that follows it, until the
+                      next --register. A register earns its own numbers only at
+                      2,500 clean words across 3 independent documents.
+  --voice <slug>      Profile to check against or to make the default.
+  --store <path>      Profile directory. Defaults to ~/.agora/voices.
+  --keep-headings     Count headings as author prose. Off by default, because
+                      headlines are often house-written.
+  --now <iso date>    Freeze the created and updated dates. For reproducible runs.
+  --json              Machine-readable output.
+  -h, --help          Show this help.
+
+Markdown, plain text, and HTML are read. Binary document formats are refused by
+name rather than partially extracted, because a partial extraction would move
+every admission threshold without saying so.
+
+Examples:
+  agora-voice build --name house --register blog --from ./posts --register email --from ./letters
+  agora-voice check --voice house ./draft.md`;
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    name: null,
+    voice: null,
+    store: null,
+    sources: [],
+    positional: [],
+    keepHeadings: false,
+    now: null,
+    json: false,
+    help: false,
+  };
+  let register = null;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const takeValue = () => {
+      const next = argv[index + 1];
+      if (!next || next.startsWith("--")) throw new Error(`${arg} requires a value`);
+      index += 1;
+      return next;
+    };
+
+    if (arg === "-h" || arg === "--help") options.help = true;
+    else if (arg === "--json") options.json = true;
+    else if (arg === "--keep-headings") options.keepHeadings = true;
+    else if (arg === "--name") options.name = takeValue();
+    else if (arg === "--voice") options.voice = takeValue();
+    else if (arg === "--store") options.store = takeValue();
+    else if (arg === "--now") options.now = takeValue();
+    else if (arg === "--register") register = takeValue();
+    else if (arg === "--from") options.sources.push({ source: takeValue(), register });
+    else if (arg.startsWith("--")) throw new Error(`unknown option: ${arg}`);
+    else if (options.command === null) options.command = arg;
+    else options.positional.push(arg);
+  }
+  options.register = register;
+  return options;
+}
+
+function storeDirectory(options) {
+  return options.store ? resolve(options.store) : join(homedir(), ".agora", "voices");
+}
+
+async function readIndex(directory) {
+  try {
+    return JSON.parse(await readFile(join(directory, "index.json"), "utf8"));
+  } catch {
+    return { default: null, profiles: {} };
+  }
+}
+
+async function writeIndex(directory, index) {
+  await writeFile(join(directory, "index.json"), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+
+function assertSlug(slug, option) {
+  if (!slug) throw new Error(`${option} is required`);
+  if (!SLUG_PATTERN.test(slug)) {
+    throw new Error(`${option} must be lowercase letters, digits, and hyphens: got '${slug}'`);
+  }
+}
+
+function reportGates(gates, corpus, refusedFirst = true) {
+  const lines = [];
+  if (refusedFirst && corpus.refused.length > 0) {
+    lines.push("Refused sources:", ...corpus.refused.map((message) => `  ${message}`), "");
+  }
+  lines.push(
+    `Documents:   ${corpus.documents.length}`,
+    `Clean words: ${gates.clean_words} (raw ${corpus.documents.reduce((total, document) => total + document.raw_words, 0)})`,
+    `Tier:        ${gates.tier.disposition}. ${gates.tier.reason}`,
+    `Independence: ${gates.independence.passed ? "passed" : "failed"}`,
+  );
+  for (const failure of gates.independence.failures) lines.push(`  ${failure}`);
+  lines.push("Registers:");
+  for (const entry of gates.registers) {
+    lines.push(
+      `  ${entry.register}: ${entry.clean_words} clean words across ${entry.documents} documents, ${entry.numeric ? "own numbers issued" : `qualitative only (${entry.note})`}`,
+    );
+  }
+  if (gates.stability.length > 0) {
+    const unstable = gates.stability.filter((entry) => !entry.stable);
+    lines.push(
+      `Feature stability: ${gates.stability.length - unstable.length} of ${gates.stability.length} core features stable`,
+    );
+    for (const entry of unstable) lines.push(`  dropped ${entry.feature}: ${entry.reason}`);
+  }
+  if (gates.heterogeneity.stopped) {
+    lines.push("Heterogeneity stop: this corpus is not profileable as one voice.");
+    for (const reason of gates.heterogeneity.reasons) lines.push(`  ${reason}`);
+    if (gates.heterogeneity.remedy) lines.push(`  ${gates.heterogeneity.remedy}`);
+  }
+  return lines.join("\n");
+}
+
+async function build(options) {
+  assertSlug(options.name, "--name");
+  if (options.sources.length === 0) throw new Error("build needs at least one --from source");
+
+  // Collect one source group at a time so each document carries the register
+  // label that was in force when its --from was named.
+  const corpus = { documents: [], refused: [] };
+  const seen = new Set();
+  for (const entry of options.sources) {
+    const group = await collectCorpus([entry.source], { keepHeadings: options.keepHeadings });
+    corpus.refused.push(...group.refused);
+    for (const document of group.documents) {
+      if (seen.has(document.source)) continue;
+      seen.add(document.source);
+      corpus.documents.push({ ...document, register: entry.register });
+    }
+  }
+  corpus.documents.sort((left, right) => left.source.localeCompare(right.source));
+
+  if (corpus.documents.length === 0) {
+    const detail = corpus.refused.length > 0 ? `\n\nRefused sources:\n  ${corpus.refused.join("\n  ")}` : "";
+    throw new Error(`no readable documents were found in the supplied sources${detail}`);
+  }
+
+  const pooledText = corpus.documents.map((document) => document.text).join("\n\n");
+  const measured = measure(pooledText);
+  const gates = runGates(corpus.documents, measured);
+  const now = options.now || new Date().toISOString().slice(0, 10);
+
+  if (!gates.certified) {
+    const report = [
+      "No profile was certified.",
+      "",
+      reportGates(gates, corpus),
+      "",
+      "Nothing was written. Report what the corpus needs, supply it, and rerun.",
+    ].join("\n");
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify({ certified: false, gates, refused: corpus.refused }, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${report}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const directory = storeDirectory(options);
+  await mkdir(directory, { recursive: true });
+  const profilePath = join(directory, `${options.name}.md`);
+  const measurementsPath = join(directory, `${options.name}.measurements.json`);
+
+  await writeFile(profilePath, renderProfile({ name: options.name, measured, gates, corpus, pipeline: PIPELINE, now }), "utf8");
+  await writeFile(
+    measurementsPath,
+    `${JSON.stringify(
+      {
+        name: options.name,
+        updated: now,
+        pipeline: PIPELINE,
+        confidence: gates.tier.confidence,
+        measured,
+        registers: gates.registers.map((entry) => ({
+          register: entry.register,
+          numeric: entry.numeric,
+          measured: entry.measured,
+        })),
+        // Hashed token runs only. The store never holds the corpus prose.
+        overlap_index: buildOverlapIndex(corpus.documents),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+
+  const index = await readIndex(directory);
+  index.profiles[options.name] = {
+    documents: corpus.documents.length,
+    clean_words: gates.clean_words,
+    registers: gates.registers.map((entry) => entry.register),
+    confidence: gates.tier.confidence,
+    pipeline: PIPELINE,
+    updated: now,
+  };
+  if (!index.default) index.default = options.name;
+  await writeIndex(directory, index);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ certified: true, profile: profilePath, gates }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(
+    [
+      `Wrote ${profilePath}`,
+      `Wrote ${measurementsPath}`,
+      "",
+      reportGates(gates, corpus),
+      "",
+      "Read the profile's `## Not captured` section before writing with it. It lists what this corpus could not tell us.",
+      "",
+    ].join("\n"),
+  );
+}
+
+async function list(options) {
+  const directory = storeDirectory(options);
+  const index = await readIndex(directory);
+  const names = Object.keys(index.profiles).sort();
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ store: directory, ...index }, null, 2)}\n`);
+    return;
+  }
+  if (names.length === 0) {
+    process.stdout.write(`No profiles in ${directory}.\n`);
+    return;
+  }
+  process.stdout.write(`Profiles in ${directory}:\n`);
+  for (const name of names) {
+    const entry = index.profiles[name];
+    process.stdout.write(
+      `  ${name}${index.default === name ? " (default)" : ""}: ${entry.clean_words} clean words, ${entry.documents} documents, registers [${entry.registers.join(", ")}], confidence ${entry.confidence}, updated ${entry.updated}\n`,
+    );
+  }
+}
+
+async function check(options) {
+  const directory = storeDirectory(options);
+  const index = await readIndex(directory);
+  const slug = options.voice || index.default;
+  assertSlug(slug, "--voice");
+  const draftPath = options.positional[0];
+  if (!draftPath) throw new Error("check needs a draft path");
+
+  let stored;
+  try {
+    stored = JSON.parse(await readFile(join(directory, `${slug}.measurements.json`), "utf8"));
+  } catch {
+    throw new Error(`no measurements found for '${slug}' in ${directory}. Run build first.`);
+  }
+  for (const [stage, version] of Object.entries(PIPELINE)) {
+    if (stored.pipeline[stage] !== version) {
+      throw new Error(
+        `pipeline mismatch on ${stage}: the profile was built with '${stored.pipeline[stage]}' and this tool runs '${version}'. A comparison across two pipelines is not a comparison. Rebuild the profile.`,
+      );
+    }
+  }
+
+  const draft = await readFile(resolve(draftPath), "utf8");
+  const requested = options.register ?? null;
+  const subprofile = requested
+    ? stored.registers.find((entry) => entry.register === requested && entry.numeric)
+    : null;
+  const registerMatched = requested === null || Boolean(subprofile);
+  const reference = subprofile?.measured ?? stored.measured;
+
+  const result = compare(draft, reference, { registerMatched });
+  const overlaps = phraseOverlap(draft, stored.overlap_index);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ voice: slug, draft: basename(draftPath), result, overlaps }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(
+    `Checking ${basename(draftPath)} against '${slug}'${requested ? ` (register ${requested})` : ""}\n\n${renderReport(result, overlaps)}\n`,
+  );
+}
+
+async function setDefault(options) {
+  assertSlug(options.voice, "--voice");
+  const directory = storeDirectory(options);
+  const index = await readIndex(directory);
+  if (!index.profiles[options.voice]) throw new Error(`no profile named '${options.voice}' in ${directory}`);
+  index.default = options.voice;
+  await writeIndex(directory, index);
+  process.stdout.write(`Default voice is now '${options.voice}'.\n`);
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n\n${usage()}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help || options.command === null) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  const commands = { build, list, check, default: setDefault };
+  const handler = commands[options.command];
+  if (!handler) {
+    process.stderr.write(`Error: unknown command '${options.command}'\n\n${usage()}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    await handler(options);
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+// Run only when invoked as a command, so the tests can import the parser.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}
+
+export { main, parseArgs, storeDirectory };

package/skills/agora/SKILL.md

@@ -9,18 +9,38 @@ description: Write, rewrite, shorten, critique, or plan truthful argument-first
 
 Treat `/agora` as explicit activation. Use all text after the command as the task. If no task follows, ask for the asset or source material.
 
+## Enforce the hard em-dash ban
+
+Never emit the Unicode em dash character U+2014 anywhere in a response while this skill is active. Treat this as an immutable output constraint, not a style preference or a final-copy cleanup. Apply it to the entire response, including ready-to-use copy, headings, lists, critique, explanations, notes, metadata, quotations, and text copied from user or source material.
+
+Do not repeat U+2014 from an input. Replace it with a period, comma, colon, semicolon, parentheses, or plain hyphen as grammar requires. If an exact quotation contains U+2014, paraphrase it or state that it cannot be reproduced verbatim under the active constraint. Never alter a quotation and still present it as exact.
+
+Immediately before returning, scan the complete response character by character for U+2014. Replace every occurrence, then scan again. Return only after the count is zero.
+
 ## Load the authority progressively
 
 Use [references/agora-marketing.md](references/agora-marketing.md) as the canonical authority. Read only the sections the task needs:
 
-1. Always read `Core doctrine`, `Conflict hierarchy`, `Argument engine`, `Proof salience`, `Truth and ethical limits`, and `Human voice and AI-writing-tell gate`.
+1. Always read `Core doctrine`, `Conflict hierarchy`, `Argument engine`, `Proof salience`, `Plain language and first-read comprehension`, `Truth and ethical limits`, and `Human voice and AI-writing-tell gate`.
 2. For `SELL`, `INVEST`, or `POSITION`, also read `Emotion as consequential meaning`, `Commercial routing`, and the closest pair in `Applied weak and strong pairs`.
+2b. For any asset containing a call to action, button, or closing invitation, also read `CTA standard`.
 3. For a written asset, read `Written GEO/AEO and citability`. For indexable public work, also read `Technical publication boundaries`.
 4. For spoken work, read `Spoken delivery`. Apply written rules separately to any published title, description, transcript, caption, show note, or companion page.
 5. Read `Evidence register` only when making or reviewing a research-backed general claim.
 
 Locate the named headings and read those sections only. Do not load the entire reference unless the task genuinely spans most of it.
 
+[references/agora-craft.md](references/agora-craft.md) is a second, narrower authority covering four domains the first one does not. Load it only for the job it covers:
+
+- `Headlines and titles` for any headline, subheading, page title, search title, social title, subject line, video title, or a set of headings written for one deliverable.
+- `Awareness and sophistication staging` when the brief states or implies what the reader already knows, when deciding whether to name a mechanism, or when routing one fact set across several reader states.
+- `Emotion under a truth constraint` when choosing the emotional job, and whenever the supplied facts contain no outcome data, testimonials, or market claims.
+- `Prosody and rhythm` when rewriting for cadence, when a draft reads as machine-uniform, or when applying an authorized voice profile.
+
+Do not load it for routine drafting, claim review, compliance questions, or work that the first reference already covers.
+
+[references/agora-voice.md](references/agora-voice.md) governs `VOICE`. Load it only when the task builds a voice profile, writes with `--voice`, inspects a profile, or checks a draft against one. Do not load it for ordinary human-voice cleanup, which the tell gate already covers.
+
 Treat source material supplied in the current task as the available product truth. Do not import facts, claim rules, or release controls from another task, repository, company, or example. Examples teach structure, never facts.
 
 ## Resolve conflicts
@@ -29,13 +49,21 @@ Apply this order:
 
 1. Truth, safety, law, and immutable requirements.
 2. Supplied facts, approved sources, and material qualifiers.
-3. The requested decision and surface.
-4. Decision relevance and proof salience.
-5. Emotional relevance and channel fit.
-6. Compression and human voice.
-7. Silent publication hygiene when it does not reduce factual clarity.
+3. Immediate comprehension by the intended audience.
+4. The requested decision and surface.
+5. Decision relevance, proof salience, and differentiation.
+6. Emotional relevance and channel fit.
+7. Compression, rhythm, style, and publication optimization.
 
-When soft rules conflict, preserve the strongest truthful argument. Ask only when missing information would materially change the audience, offer, claim, or action. Otherwise narrow or omit the unsupported point.
+Compression, cleverness, citability, technical precision, and rhetorical force never make the writing harder to understand than the facts require. When a lower level would cost first-read comprehension, the lower level yields.
+
+Two specific conflicts resolve as follows, because both have produced accurate but unreadable copy:
+
+- **Qualification against comprehension.** Level 2 requires preserving scope, date, condition, and uncertainty. It does not require carrying every qualifier inside every sentence. Qualify at the passage or section level. A sentence that carries its full qualification set inline reads as a compliance memo and fails level 3.
+- **Citability against comprehension.** Written GEO/AEO asks for passages that stay accurate when quoted alone. That rule governs the passage, not the sentence. Do not compress a paragraph of context into one self-sufficient sentence. Self-containment is achieved by keeping a short passage together, not by loading one clause.
+- **Voice against everything above it.** An active voice profile enters at level 6. It never licenses a claim the facts do not support, never overrides required or legal phrasing, and never overrides the U+2014 ban. Where an author's habitual certainty exceeds the evidence, the evidence wins and the profile yields for that sentence.
+
+When soft rules conflict, preserve the strongest truthful argument that the reader can follow on the first pass. Ask only when missing information would materially change the audience, offer, claim, or action. Otherwise narrow or omit the unsupported point.
 
 ## Choose the job
 
@@ -49,6 +77,21 @@ Select one primary mode. An explicit mode wins unless it would require factual d
 | `INFORM` | Editorial or educational work |
 | `TRANSACT` | Buttons, confirmations, alerts, forms, or utility microcopy |
 
+`VOICE` is the exception to selecting one mode. It is a modifier, not a job: `--voice <name>` loads a measured author profile on top of whichever mode was already chosen, and `voice build`, `voice list`, and `voice check` are its own operations. Profiles are stored at `~/.agora/voices/`, never inside the skill directory, because the documented update path replaces that directory and would destroy them.
+
+Apply the default profile to every mode. When `~/.agora/voices/index.json` names a default and the request carries no voice instruction, load that profile for `POSITION`, `SELL`, `INVEST`, `INFORM`, and `TRANSACT` alike:
+
+| Instruction | Effect |
+|---|---|
+| none, and a default profile exists | Load the default profile |
+| `--voice <name>` | Load that profile instead of the default |
+| `--no-voice` or `neutral` | Load no profile at all |
+| none, and no profile exists | Nothing to load; write as normal |
+
+Default-on changes nothing above level 6. Required phrasing, legal and regulatory wording, disclosures, accurate quotation, and the U+2014 ban continue to outrank the profile. That matters most on `TRANSACT` microcopy and `INVEST` material, where a required form is common and the profile yields to it for that string.
+
+Measurement is computed, never estimated from reading. Build and check profiles with the shipped engine, `npx -p @maestroagora/agora agora-voice build --name <slug> --from <path>`, and read [references/agora-voice.md](references/agora-voice.md) before running it. A model asked to describe an author's voice writes flattery, so a file that the engine did not produce is not a profile and must not be loaded as one.
+
 Directory placement or an investor-adjacent audience does not activate `INVEST` by itself. Keep investor relevance implicit in descriptive profiles. Do not write phrases such as `for investors`, `investors should consider`, or `merits evaluation` unless the user explicitly requires that wording.
 
 ## Route the surface separately
@@ -97,6 +140,94 @@ Rank candidate facts by decision relevance, differentiation, verifiability, spec
 
 Every included fact must prove a premise, resolve an objection, distinguish the mechanism, or enable action.
 
+## Pass the first-read comprehension gate
+
+Factual accuracy is not sufficient. Copy also fails when the wording makes the reader decode internal terminology, reconstruct a missing relationship, or translate an abstraction into a concrete action.
+
+Plain language is not simple language. It is precise language with low decoding effort. Expert audiences keep their technical precision and still lose the unnecessary abstraction, compressed syntax, and in-house shorthand.
+
+### Model the reader
+
+Write for someone who is intelligent, understands their own job, has not read the documentation, does not know the organization's internal vocabulary, will not stop to decode a sentence, and is deciding whether the next line deserves attention. Familiarity with an industry is not familiarity with one organization's terms.
+
+### Test every customer-facing sentence
+
+Rewrite any sentence an intended reader could not restate after reading it once. A sentence fails when it:
+
+- depends on undefined internal terminology;
+- introduces more than one unfamiliar concept at a time;
+- hides the actor, the action, the object, or the result;
+- uses an abstract noun where a concrete verb would be clearer;
+- describes an internal method instead of what the reader needs to know;
+- compresses several reasoning steps into insider shorthand;
+- sounds like a specification, a compliance memo, or an academic method section when the surface does not call for that register;
+- is technically correct and practically unclear;
+- needs a different paragraph to become understandable;
+- sounds impressive before it communicates anything concrete.
+
+### Gate specialized terms
+
+Accuracy alone does not license an internal product, operational, analytical, or methodological term. Before using one, confirm all four:
+
+1. The intended audience already knows it.
+2. It is necessary for accuracy.
+3. Its meaning is clear from the sentence it appears in.
+4. An everyday expression would lose material meaning.
+
+If any answer is no, replace the term or define it in place. Every term the reader does not already own is either decision-required and taught where it appears, or removed. Treat a sentence carrying two or more reader-unowned terms as a review trigger and not as an automatic error, and treat that count as a governance default rather than a measured limit.
+
+Treat a noun the organization coined as a term the reader has no reason to know. Naming an internal method, stage, score, record type, or framework in customer-facing copy requires the reader to gain something from learning it. Otherwise state what happens and drop the name.
+
+### Prefer actor, action, object, result
+
+Answer these before drafting a sentence: who or what acts, what it does, what it acts on, and what changes for the reader.
+
+Choose the highest-frequency verb the reader already owns that preserves the factual relation and tells them what the action does. Verbs such as check, compare, find, show, verify, measure, review, choose, send, create, remove, correct, approve, reject, schedule, and calculate are a useful house lexicon, not a required set. A specialized verb wins whenever it names the exact action and the reader owns that word.
+
+Rewrite noun-heavy constructions into direct actions. Abstract nouns are not banned and must not be counted. Rewrite an abstraction when it conceals an actor, action, causal relation, or consequence the reader needs, and leave it when it carries cohesion or names an established concept. The check on each abstract noun is whether a specific actor, a finite action, and the object or result can still be recovered, and whether the reader needs them.
+
+Weak:
+
+> Evaluate whether configured operational surfaces produced compliant outcomes for the declared workflow scope.
+
+Strong:
+
+> Check whether each system finished the task you assigned it.
+
+The strong version is longer in words and shorter in effort. That trade is correct.
+
+### Reject slogans that survive only on tone
+
+For every headline, subheading, closing line, and call to action, ask what it means literally, what action or condition it names, whether it stays useful once the dramatic tone is removed, whether twenty unrelated companies could publish it unchanged, and whether the reader learns anything or only receives a mood. If the literal meaning is thin, rewrite it.
+
+Run the last question as a procedure rather than a judgment where the line is short enough to search: paste it into a search engine and read how many unrelated companies already publish it unchanged. Ask also what would make the sentence false. A sentence nothing could contradict is not a claim, whatever its tone. Neither check applies to navigation labels, category nouns, or utility microcopy, which are not claims and are not supposed to be falsifiable.
+
+### Manage shape across a corpus
+
+Repeating one sanctioned shape across a page or site can produce a corpus that reads as generated even when every line passes on its own. Split this by function before acting on it.
+
+Where headings belong to the same task or information class, parallel syntax is correct and should be kept. Forcing variety into a procedure list damages it.
+
+Where headings and hooks compete for attention, manage concentration instead of demanding uniqueness. Across roughly twelve such headings, keep at least four distinct syntactic families and avoid more than two consecutive instances of one family. Treat that as a working default, not a measured threshold.
+
+The team's own fatigue with a line is not a reader-side signal. The people who write and approve the copy see it every working day and the buyer sees it once, so "we have been saying this forever" is not evidence that anything is failing. Change a line because a reader-side test failed it, because the facts changed, or because a measured result says so. This removes one bad reason to change; it is not a defence of an unvaried corpus, so still run the variance check on the artifact.
+
+## Write the CTA as an action label
+
+A call to action names an action, not a mood. It tells the reader what happens after they choose it.
+
+Use `clear verb + concrete object, destination, or result`. Match the commitment to the destination and to the evidence the copy has actually delivered. Do not put a dramatic or high-commitment label on an informational destination.
+
+Workable shapes include `View the report`, `Compare plans`, `Check eligibility`, `See the recommended fixes`, `Review the evidence`, `Book a product demo`, `Start the assessment`, `Download the guide`, `Contact the sales team`, and `Retry the payment`.
+
+Reject slogan-shaped labels such as `Take control`, `Move with confidence`, `Fix what matters`, `See the difference`, `Unlock your potential`, `Transform your results`, `Start your journey`, `Make it count`, and `Get clarity`. Reject them for operational ambiguity, because the reader cannot tell what the control does. Do not claim they convert worse; no controlled evidence supports that. Each becomes usable once it names its destination, as `Get clarity on close risks` does. A slogan may sit beside the control as persuasion copy.
+
+Avoid the generic labels for the same reason: `Learn more`, `Get started`, `Submit`, `Explore`, `Discover`, `Click here`, and bare product names. On a consequential or irreversible dialog, name the operation rather than using `OK` or `Yes`.
+
+Never make the reader infer what opens, what they receive, what they must supply, whether the action is immediate, whether it begins a purchase, form, demo, download, or review, or what commitment it creates.
+
+Keep one canonical label for one materially identical action. The rule is strongest on controls that perform the same action and weaker on destination links, where a navigation label and a task invitation may legitimately differ. Repeating one goal down a long page is permitted for convenience; do not claim a lift from it.
+
 ## Enforce truth and ethical limits
 
 Keep fact, inference, interpretation, aspiration, and promise distinct. Preserve source, date, scope, conditions, and uncertainty where material.
@@ -107,19 +238,28 @@ Do not convert an operational fact into financial, legal, compliance, reputation
 
 Preserve agency. Do not manufacture fear, shame, guilt, identity pressure, exclusivity, or scarcity. Threat requires a real material risk and a credible response. Ambition requires a mechanism and supportable path.
 
+Refuse to build or apply a voice profile of a named third party where the purpose is publication under that person's name. Learning from a writer for work published under your own name is ordinary craft; producing text designed to pass as a specific real person's authored work is not, and it is declined rather than negotiated. The same refusal covers fabricated endorsements, invented positions attributed to a named person, and consequential advice written under someone else's identity without their authorization.
+
 ## Reject flat or synthetic drafts
 
 Rebuild when the draft:
 
-- reads as a category definition, source-ledger paraphrase, feature inventory, or operational taxonomy;
+- describes the subject only in category terms, or reads as a source-ledger paraphrase, feature inventory, or operational taxonomy;
 - has no felt stake, consequential shift, meaningful mechanism, or defensible destination belief;
-- could describe a competitor after changing the name;
+- repeats a line that unrelated companies already publish unchanged, which the search-paste check makes testable;
 - uses generic brand verbs such as `helps`, `shows`, `supports`, or `built for` when a stronger supported causal verb exists;
 - lets minor features bury a decisive fact;
 - opens a very short `POSITION` asset with the subject followed by an operational verb list when the facts contain a verified trigger, threshold, conflict, or exception that can lead instead;
 - announces buyer or investor relevance instead of earning it;
 - exposes compliance, reasoning, routing, or publication process;
-- uses emotion that the facts do not support.
+- uses emotion that the facts do not support;
+- names an internal method, stage, record type, or score where the reader only needs to know what happens;
+- stacks abstract nouns instead of naming an actor, an action, and a result;
+- reads as quotable while its literal meaning stays thin;
+- closes on a call to action that hides what the reader gets;
+- runs one attention-oriented heading template through a whole deliverable.
+
+Naming the category is orientation, not taxonomy, and the two are opposite defects. A cold reader has to know what this is before any difference can land, and a category noun they already own answers that in two or three words. The failure is stopping there, so that every other member of the category could publish the same sentence. Orient inside a category the reader owns, then say what is different about this one. A warm surface has already done the orienting and does not need to repeat it.
 
 When facts describe an input conflict, blocked action, threshold, exception, or before-and-after state, use that verified condition as the opening situation. Do not add a downstream cost or risk that the facts do not establish.
 
@@ -146,14 +286,20 @@ Channel rules change depth and tone. They do not erase the argument.
 After the argument is drafted:
 
 1. Verify each claim and causal link.
-2. Apply written GEO/AEO only to written deliverables.
-3. Apply technical publication checks only to indexable public work.
-4. Apply the human-voice and AI-writing-tell gate without deleting facts or diagnostic lists.
-5. Compress repetition and decoration last.
+2. Run the first-read comprehension gate, the specialized-term gate, and the CTA gate. These run before any style, compression, or publication pass, and their result outranks all three.
+3. Apply written GEO/AEO only to written deliverables, at passage level rather than sentence level.
+4. Apply technical publication checks only to indexable public work.
+5. Apply the human-voice and AI-writing-tell gate without deleting facts or diagnostic lists.
+6. Compress repetition and decoration last, and only where compression does not raise decoding effort.
+7. Run the final U+2014 scan across the complete response and confirm zero occurrences.
+
+When a sentence fails the comprehension gate, keep the underlying fact, name the concrete actor, action, object, and result, remove internal process language the reader does not need, split the overloaded sentence, restore any context the compression removed, rewrite the call to action to name its real destination, then test again. Do not repair unclear writing by adding explanatory parentheses, longer noun phrases, or a vague supporting sentence.
 
 Keep these passes invisible. Mention a blocker only when silence would make the result misleading, legally unusable, or operationally unshippable.
 
-Do not generate em dashes or curly or smart quotes in final copy. Remove prompt leakage, canned framing, generic significance tails, inflated abstractions, fake human texture, and repeated stock templates. Avoid decorative three-part rhetoric, but preserve necessary factual series. Never promise detector evasion. Never change facts or legal meaning to sound human.
+An active voice profile carries one narrow exception to the AI-vocabulary ban. The words on that profile's owned-vocabulary list, and only those words, are exempt, because they were measured as this author's own across the corpus. Without the exception the tell gate strips the voice it was loaded to keep. The exception covers vocabulary alone: it never suppresses the stock-template bans, the significance-tail bans, the structural-tell rules, the curly-quote ban, or the U+2014 ban, and it never makes an unsupported claim writable.
+
+Do not generate curly or smart quotes in final copy. Remove prompt leakage, canned framing, generic significance tails, inflated abstractions, fake human texture, and repeated stock templates. Avoid decorative three-part rhetoric, but preserve necessary factual series. Never promise detector evasion. Never change facts or legal meaning to sound human.
 
 ## Return the result
 

package/skills/agora/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Maestro: Agora"
-  short_description: "Argument-first copy that earns belief"
-  default_prompt: "Use $agora to turn verified facts into the strongest channel-native argument the evidence can support."
+interface:
+  display_name: "Maestro: Agora"
+  short_description: "Argument-first copy that earns belief"
+  default_prompt: "Use $agora to turn verified facts into the strongest channel-native argument the evidence can support."