@maestroagora/agora 1.8.0 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "displayName": "Maestro: Agora",
   "description": "Use /agora for persuasive writing, technical explanation, case studies, investment analysis, spoken or written copy, and explicit publication artifact audits.",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Maestro: Agora writes clear persuasion, technical explanations, case studies, and investment communication, then audits local publication artifacts when requested.",
   "author": {
     "name": "Mark Laursen",

package/README.md

@@ -396,6 +396,7 @@ The mandatory release gate checks skill structure, routing contracts, user-autho
 
 | Version | What changed |
 |---|---|
+| 1.9.0 | Makes first-read clarity automatic. Agora now drafts for factual completeness, rewrites for literal clarity, preserves qualifiers across short passages, names concrete actors and observable results, and rejects vague referents, hidden metaphors, noun stacks, and revisions that only rename ambiguity. Adds rendered label-clearance guidance for technical diagrams. |
 | 1.8.0 | Adds opt-in publication privacy and provenance review plus a packaged read-only audit CLI. Reports configured hidden Unicode, document and image metadata, Office review material, and C2PA carrier or validation signals without changing source files. Redacts sensitive values and paths by default, preserves unknown coverage, and makes no watermark-removal or authorship claim. |
 | 1.7.0 | Adds a progressively loaded conversion-context reference with bounded conversion priors, downstream outcome matching, self-serve and enterprise route design, pricing decision contracts, proof placement, and contradiction handling. Tightens closed-world fact preservation and limits written GEO/AEO requirements to indexable public work. |
 | 1.6.0 | Expands user control across every writing mode. User-selected claims, fiction, urgency, attribution, profile use, and publication choices now control the draft. Claim, evidence, permission, disclosure, confidentiality, diligence, and compliance review are opt-in. Adds a user-responsibility disclaimer and an accurate privacy notice. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestroagora/agora",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Install Maestro: Agora for persuasive writing, technical explanation, case studies, investment communication, and publication artifact review.",
   "type": "module",
   "bin": {

package/skills/agora/SKILL.md

@@ -241,31 +241,30 @@ Plain language is not simple language. It is precise language with low decoding
 
 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
+### Draft twice and return once
 
-Rewrite any sentence an intended reader could not restate after reading it once. A sentence fails when it:
+Draft the factually complete argument first. Then rewrite the whole draft for literal clarity before any style, compression, voice, or publication pass. Compare the rewrite with the factual draft so every supplied fact, qualifier, relationship, and requested claim survives. Return only the rewrite.
 
-- 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.
+Do not treat this as optional polish. The first draft may preserve the facts and still fail because it speaks in internal categories. The second pass must change how the reader receives the meaning, not replace a few flagged words.
 
-### Gate specialized terms
+### Run the literal clarity rewrite
 
-Accuracy alone does not license an internal product, operational, analytical, or methodological term. Before using one, confirm all four:
+Rewrite any sentence an intended reader could not restate after reading it once. For every sentence that carries a mechanism, consequence, qualification, or decision, recover:
 
-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.
+1. The concrete actor, product, component, person, or source.
+2. The finite action.
+3. The concrete object affected.
+4. The observable result, condition, or change when the claim depends on one.
 
-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.
+Apply these checks during the rewrite:
+
+- **Generic referent:** Treat words such as `interface`, `surface`, `system`, `asset`, `signal`, `representation`, `direction`, `property`, `origin`, and `continuity` as review triggers, not banned words. When the reader could reasonably ask which thing the word names, replace it with the concrete referent or identify that referent in the same sentence.
+- **Observable result:** State what a person could see happen. Prefer a named product listing an item, a crawler requesting a page, or a source failing to support a claim over an internal category describing the event.
+- **Specialized term:** Keep a term only when the audience owns it, accuracy requires it, its meaning is clear where it appears, and familiar words would lose material meaning. Otherwise define or remove it. Every term the reader does not own is decision-required and taught in place, or removed.
+- **Metaphor recovery:** If a metaphor carries the mechanism, test, or consequence, replace it with the literal action or result. Keep a metaphor only when the sentence remains clear without decoding it.
+- **Qualification distribution:** Keep every material scope, date, sample, product, market, method, condition, and uncertainty. Distribute them across the shortest clear passage instead of loading them into one sentence.
+- **Noun stack:** When several abstract nouns hide how things relate, convert each needed distinction into an actor and action. Abstract nouns are not banned and must not be counted.
+- **Revision integrity:** Reject a rewrite that swaps one vague noun for another, adds explanatory parentheses, or leaves the reader to recover the same missing relationship. The revised passage must make the actor, action, object, and observable result easier to identify while preserving the facts.
 
 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.
 
@@ -277,24 +276,6 @@ Name the concrete result, finding, number, quote, source, report, study, test, p
 
 Do not narrate internal source review in customer-facing copy unless the user asks for it. Do not narrow or omit a user-selected claim merely because Agora would prefer more support.
 
-### 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.
@@ -387,7 +368,7 @@ After the argument is drafted:
 1. Honor the user's requested claims, framing, tone, and content decisions without adding policy commentary.
 2. For every draft, build a private fact ledger covering the complete response, including headings, labels, fill-in tokens, parentheticals, confirmations, conditional text, and rationale. Match every externally verifiable proposition to an explicit supplied fact, a necessary entailment, or explicit user authorization to invent. Delete or rewrite anything unmatched. When the brief is closed-world, apply the same test to every factual proposition. Plausibility, convention, usefulness, and likely implementation do not count as entailment.
 3. Run claim, evidence, permission, disclosure, or compliance checks only when the user requested that review.
-4. Run the first-read comprehension gate, the delivery-model ownership gate, the rewrite regression gate when rewriting supplied copy, the specialized-term gate, and the CTA gate. These run before any style, compression, or publication pass, and their result outranks all three.
+4. Draft twice and return once. Run the literal clarity rewrite, delivery-model ownership gate, rewrite regression gate when rewriting supplied copy, and CTA gate. These run before any style, compression, voice, or publication pass, and their result outranks all five.
 5. Apply written GEO/AEO only to `INDEXABLE_PUBLIC` work, at passage level rather than sentence level.
 6. Apply technical publication checks only to indexable public work.
 7. Apply the human-voice and AI-writing-tell gate without deleting user-selected claims or diagnostic lists.
@@ -399,7 +380,7 @@ After the argument is drafted:
 13. Make every requested component visibly distinguishable through hierarchy, spacing, or channel-native structure. The worksheet-label ban applies inside ready-to-use copy. Labels remain available outside the copy when the user requests labeled fields, when implementation recommendations need them, or when they are necessary to distinguish requested components.
 14. For conversion compositions, load and apply the surface-specific route, pricing, experiment, proof, and placement contracts in the conversion reference. Verify that visible copy follows any returned placement order, every material qualifier stays attached to the fact it qualifies, conditional steps remain conditional, unknown destinations remain unknown, and proof keeps its supplied form and causal status. Trace the primary-action spine across the flow. Do not let a prerequisite replace the activation event, make an optional post-event action primary, or invent a destination after an unknown transition. Audit every parallel option's primary decision unit for its supported route type, exclusivity, material commitment, and action or destination; an FAQ may reinforce this distinction but cannot supply it first. Audit every checklist or readiness item for a distinct fact-grounded verification, dependency, consequence, or preparation action rather than a generic instruction to review or confirm prior copy. When collection, access, or start order is absent, keep the known terms separate and do not connect them with `after`, `before`, `then`, or `until`. Scale experiment-plan detail to the requested depth without removing the minimum controls needed to interpret the named business outcome. Treat route, term, proof, and qualification completeness as the safety floor; after that floor passes, preserve the strongest supported reader job, task, or operational decision as the argument.
 
-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.
+When a sentence fails the comprehension gate, rewrite the full sentence or short passage through the literal clarity procedure, compare it with the factual draft, then test it again. Do not patch isolated trigger words or repair unclear writing with explanatory parentheses, longer noun phrases, or a vague supporting sentence.
 
 Keep these passes invisible. Mention a blocker only when a host rule or missing requirement makes the requested result impossible.
 

package/skills/agora/references/agora-marketing.md

@@ -334,6 +334,29 @@ A sentence fails when it:
 
 The last item is the hardest to catch from inside the draft, because impressive and clear feel similar to an author who already knows the answer. Use the literal-meaning test in `Required comprehension tests` on any sentence that felt satisfying to write.
 
+### The literal clarity rewrite
+
+Draft twice and return once. Build the factually complete argument first. Then rewrite the entire draft for literal clarity before style, compression, voice, GEO/AEO, or publication work. Compare the rewrite with the factual draft so every supplied fact, qualifier, relationship, and requested claim survives. Return only the rewrite.
+
+This is a passage rewrite, not a word-substitution pass. Run it on every sentence that carries a mechanism, consequence, qualification, or decision:
+
+1. Name the concrete actor, product, component, person, or source.
+2. Use a finite action the reader owns when it preserves the meaning.
+3. Name the concrete object affected.
+4. State the observable result, condition, or change when the claim depends on one.
+
+**Generic-referent gate.** Words such as `interface`, `surface`, `system`, `asset`, `signal`, `representation`, `direction`, `property`, `origin`, and `continuity` are review triggers, not banned words. Keep one when its concrete referent is unmistakable and the word adds meaning. When the reader could reasonably ask which interface, surface, system, asset, signal, representation, direction, property, origin, or continuity the sentence means, name the concrete thing in that sentence.
+
+**Observable-result gate.** Ask what a person could see happen. `The answer listed the product` exposes an event. `The footprint entered an answer surface` hides it inside two categories. For technical or empirical prose, distinguish what happened, how it was observed, and what it may imply. Do not replace the observed event with the method used to classify it.
+
+**Metaphor-recovery gate.** A metaphor may add emphasis after the mechanism is clear. It may not carry the only statement of the mechanism, test, or consequence. If the reader has to translate `carry the trust burden`, `flatten into one voice`, or `the asset breaks` before understanding the point, state the literal check, presentation effect, or failure instead. Keep a metaphor only when removing it leaves the sentence's factual relation intact and obvious.
+
+**Qualification-distribution gate.** Preserve material source, sample, date, product, market, method, condition, and uncertainty at passage level. Give the observed result its own sentence when possible, then place its scope and limit in adjacent sentences. Do not make one sentence independently quotable by forcing every qualifier into it.
+
+**Noun-stack gate.** When several unfamiliar abstract nouns appear together, recover each relationship the reader needs as an actor and action. Do not apply a fixed noun limit. Keep an established concept when it creates useful cohesion or precision; rewrite it when it hides who did what or what changed.
+
+**Revision-integrity gate.** Compare the rewrite with both the source and the failed wording. Reject a revision when it replaces one vague noun with another, converts one hidden action into a different abstraction, adds parentheses around the same unclear phrase, or drops a qualifier to create fluency. The revised passage must make the concrete actor, action, object, and observable result easier to recover without weakening the proposition.
+
 ### The specialized-term gate
 
 Do not expose internal product, operational, analytical, or methodological terminology merely because it is accurate.
@@ -463,14 +486,13 @@ Where this warning fails: internal boredom and a genuine template tell look iden
 
 When copy fails these tests:
 
-1. Preserve the underlying fact.
-2. Identify the concrete actor, action, object, and result.
+1. Preserve the underlying fact and every material qualifier.
+2. Rewrite the full sentence or short passage through `The literal clarity rewrite`.
 3. Remove internal process language unless the reader needs it.
-4. Split overloaded sentences.
-5. Replace abstractions with observable actions or conditions.
-6. Restore necessary context that compression removed.
-7. Rewrite the call to action to name its actual destination.
-8. Test the revision again.
+4. Split overloaded sentences and distribute their qualifications.
+5. Compare the revision with both the factual draft and the failed wording.
+6. Rewrite the call to action to name its actual destination.
+7. Test the revision again.
 
 Do not repair unclear writing by adding more jargon, explanatory parentheses, longer noun phrases, or vague supporting sentences. Those raise word count and decoding effort at the same time.
 
@@ -482,6 +504,11 @@ Run all of these before accepting customer-facing writing.
 |---|---|
 | First-read | Can the intended reader restate the sentence after one reading? |
 | Actor-action-object | Is it clear who or what acts, what the action is, and what it affects? |
+| Generic referent | Does every generic system or category noun identify the concrete thing it means when ambiguity is possible? |
+| Observable result | Can the reader tell what a person could see happen, separately from how the event was classified or interpreted? |
+| Metaphor recovery | If the metaphor is removed, does the sentence still state the literal mechanism, test, or consequence? |
+| Qualification distribution | Does the short passage preserve every material qualifier without forcing them into one sentence? |
+| Revision integrity | Does the rewrite remove the original decoding work instead of renaming it or hiding it elsewhere? |
 | Delivery-model ownership | Does the provider or product still perform the work the offer sells, without invented or magnified buyer burden? |
 | Rewrite regression | Does every source strength outside the requested transformation survive or materially improve? |
 | Abstraction | Can any abstract noun be replaced with a concrete action, object, condition, or result? |
@@ -1384,7 +1411,7 @@ The comprehension and CTA rules were tested against the research literature afte
 
 What survived with real support: jargon measurably reduces processing fluency; naming an actor changes how readers assign cause ([Fausey and Boroditsky, 2010](https://doi.org/10.3758/PBR.17.5.644)); word frequency predicts processing ease; controls should describe their own destination; one canonical label per materially identical action ([W3C, Link Purpose](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html), [NN/g, Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)); persuasion knowledge makes visible motive costly ([Campbell and Kirmani, 2000](https://academic.oup.com/jcr/article-abstract/27/1/69/1791556)); reading aloud improves error detection.
 
-Two findings in this section are house observations from a diagnosed production failure rather than literature: a sentence carrying its full qualification set inline reads as a compliance memo, and a set of marketing headings built on one template reads as generated. Both were observed directly. Neither has a measured effect size.
+The qualification, heading-variance, generic-referent, observable-result, metaphor-recovery, and revision-integrity procedures are house responses to diagnosed production failures rather than measured response laws. They were observed directly in delivered copy. None has a measured effect size. Use them to remove documented decoding work, not to claim a universal reading or conversion effect.
 
 Remaining governance defaults, explicitly not findings: the twelve-headline template-concentration window, and the review trigger for a sentence carrying two or more reader-unowned terms.
 
@@ -1497,6 +1524,7 @@ Change record:
 
 | Date | Change |
 |---|---|
+| 2026-08-13 | Replaced the broad symptom-led comprehension pass with a mandatory draft-twice, return-once literal clarity rewrite. Added contextual gates for generic referents, observable results, metaphors that hide literal meaning, distributed qualification, noun stacks, and revisions that rename rather than remove ambiguity. Extended technical visual guidance to require label clearance and rendered inspection before legibility claims. |
 | 2026-08-09 | Ran the graded research pass against the seven load-bearing claims. Removed four refuted thresholds: the per-sentence unfamiliar-concept limit, the abstract-noun count, the two-or-three-sentence passage unit, and universal heading-template uniqueness. Rebased abstraction control on actor recovery, the verb guidance on word frequency, the slogan-CTA rejection on operational ambiguity rather than a conversion claim, and mechanism naming on the separate awareness and sophistication axes. Split corpus variance by function so parallel syntax survives where it is functional metadata. Added the pronoun-ranking prohibition and the label-consistency boundary. |
 | 2026-08-09 | Marked the new comprehension and CTA rules HOUSE and provisional, and recorded the seven unsourced load-bearing claims in `Evidence register` pending a graded research pass. |
 | 2026-08-09 | Added `Plain language and first-read comprehension`. Raised comprehension to level 3 of the conflict hierarchy and resolved its two standing conflicts with material qualification and with citability. Rebuilt `CTA standard` around action labels, destination clarity, and cross-surface consistency. Scoped passage self-containment to the passage rather than the sentence. Added the differentiation counterweight to `Mechanism and differentiation`, corpus-level repetition to `Structural tells`, six applied pairs across new business types, and matching invariants and quality dimensions. |

package/skills/agora/references/agora-science.md

@@ -190,6 +190,8 @@ For a technical system, show:
 
 Use the minimum sequence the audience needs. Name the actor, action, object, and result. Preserve exact interfaces, units, and state transitions when they carry the explanation.
 
+For general and adjacent-expert readers, run `The literal clarity rewrite` from [agora-marketing.md](agora-marketing.md) after the evidence or technical pass. Name the product, component, source, or person when a generic label could point to several things. State the observable event before its internal classification. The system sequences above remain backstage and must not appear as unexplained editorial labels.
+
 Separate these questions:
 
 1. What happened?
@@ -199,7 +201,7 @@ Separate these questions:
 5. What does it imply for this audience?
 6. What remains unknown?
 
-Rule [HOUSE]: a technical explanation fails when it lists components without showing their relation, or gives a metaphor without returning to the real mechanism.
+Rule [HOUSE]: a technical explanation fails when it lists components without showing their relation, gives a metaphor without returning to the real mechanism, or names a property without stating what a person could observe.
 
 ## Use analogies and visuals as bounded models
 
@@ -221,6 +223,10 @@ For charts and diagrams:
 - Do not crop away a conflicting result or material range.
 - Mark simulated, illustrative, and observed data distinctly.
 - Match the caption's certainty to the visual evidence.
+- Keep labels off lines, shapes, and mixed backgrounds unless an opaque backing treatment preserves clear space.
+- Align text to the actual geometry of its box or mark rather than an approximate baseline.
+
+A color change does not fix overlap. Relocate, back, or remove a label when the visual already carries its meaning. When Agora supplies diagram copy or a visual brief, state the clearance requirement. When the task includes an actual rendered asset, require render-based visual inspection before claiming that the label is legible.
 
 ## Write scientific and technical video
 
@@ -275,6 +281,12 @@ Outside review mode, do not refuse, narrow, qualify, or relabel the user's scien
 
 ## Evaluation contract
 
+Always-on quality gates:
+
+- First-read comprehension survives technical precision.
+- General and adjacent-expert explanations expose concrete actors and observable results.
+- Rendered diagrams receive visual label-clearance inspection before a legibility claim.
+
 Hard gates in explicit scientific review mode:
 
 - Claim classes remain distinct.
@@ -284,7 +296,6 @@ Hard gates in explicit scientific review mode:
 - No invented misconception, consensus, or mechanism.
 - Analogy boundary is explicit when analogy carries the explanation.
 - Title, visual, opening, and body promises agree.
-- First-read comprehension survives technical precision.
 
 Blind-quality dimensions: