@maestroagora/agora 1.8.0 → 1.10.0

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

@@ -1,12 +1,13 @@
 # Agora voice authority
 
-This reference governs `VOICE`: building a measured voice profile from a corpus, writing to that profile, and checking a draft against it. Load it only when the task builds, applies, inspects, or checks a voice profile.
+This reference governs two separate voice tiers: measured persistent profiles and task-only sketches from samples supplied with one task. Load it when the task builds, applies, inspects, or checks either tier.
 
-Voice is a modifier. It changes how a proposition is expressed. User authority in [agora-marketing.md](agora-marketing.md) controls profile use, and [agora-craft.md](agora-craft.md) supplies the rhythm controls a profile replaces. Agora does not authenticate corpus ownership, identity, attribution rights, endorsement rights, or publication permission. The user controls those decisions.
+Voice is a modifier. It changes how a proposition is expressed. User authority in [agora-marketing.md](agora-marketing.md) controls profile use. Numeric rhythm measurements remain optional diagnostics and never become drafting quotas. Agora does not authenticate corpus ownership, identity, attribution rights, endorsement rights, or publication permission. The user controls those decisions.
 
 ## Contents
 
 - [What VOICE is](#what-voice-is)
+- [Task-only voice sketches](#task-only-voice-sketches)
 - [Where profiles live](#where-profiles-live)
 - [Corpus admission](#corpus-admission)
 - [What gets measured](#what-gets-measured)
@@ -18,7 +19,7 @@ Voice is a modifier. It changes how a proposition is expressed. User authority i
 
 ## What VOICE is
 
-`VOICE` sits alongside `POSITION`, `SELL`, `INVEST`, `INFORM`, and `TRANSACT` with one difference: it is not mutually exclusive with them. Every other mode answers what job the copy is doing. `VOICE` answers whose habits the copy is written in, and it rides on top of whichever mode was already selected.
+`VOICE` sits alongside `POSITION`, `SELL`, `INVEST`, `INFORM`, and `TRANSACT` with one difference: it is not mutually exclusive with them. Every other mode answers what job the copy is doing. `VOICE` answers which observed habits shape the expression. Resolve register and voice before argument planning.
 
 The surface:
 
@@ -50,10 +51,33 @@ npx -p @maestroagora/agora agora-voice default --voice <slug>
 
 `voice build` is a measurement task, not a description task. A model asked to describe an author's voice writes flattery. The profile leads with numbers computed from the corpus, because a number is checkable and a later draft can be measured against it. Adjectives belong in the interpretation sections, underneath the measurements they interpret.
 
-**A profile the engine did not produce is not a profile.** Do not write one by reading a corpus and describing what you notice, and do not load a hand-written file as though it were measured. Where the engine cannot run, say so and work without a profile.
+**A persistent profile the engine did not produce is not a measured profile.** Do not load a hand-written file as though it were measured. A task-only sketch is permitted under the next section because it makes no certification, identity, or statistical claim and is never stored as a profile.
 
 **Boundary:** the measurement is only as good as the pipeline. Stylometric values move when the tokenizer, sentence segmenter, parser, or normalization rules change ([Grieve](https://doi.org/10.1093/llc/fqm020)). Freeze the pipeline in the profile and use the identical one when checking a draft. A comparison across two pipelines is not a comparison.
 
+## Task-only voice sketches
+
+A task-only sketch uses authentic samples supplied with the current task. It works without the persistent profile's 5,000-word certification floor because it does not claim stable identity or statistical matching.
+
+Use three to ten same-genre samples when available. Record a fuller local sketch only when those samples show recurring habits. With one or two samples, record cautious observations that are directly visible in the sample and mark internal confidence low. With no samples, preserve credible choices in the supplied draft and use plain professional writing.
+
+Record observable habits only:
+
+- sentence and paragraph range;
+- fragments and contractions;
+- first-person and second-person use;
+- punctuation;
+- directness, warmth, humor, and skepticism;
+- how qualifications are placed;
+- common opening, turning, and ending shapes;
+- constructions and words the samples avoid.
+
+The sketch has the internal type `TASK_VOICE_SKETCH`, a sample count, a genre label when supplied, and `certified: false`. It exists only for the current task. Never write it to `~/.agora/voices/`, add it to the profile index, or present it as a measured profile.
+
+Transfer habits, not material. Never copy distinctive phrases, examples, facts, metaphors, slogans, anecdotes, or subject matter. Never infer personality, biography, opinions, motives, identity, authorship, or approval. Run the existing exact overlap check and review unusual shorter matches before returning the draft.
+
+When task samples and a default persistent profile conflict, use the task samples for same-genre local expression in the current task. Keep only compatible stable habits from the default. An explicitly requested persistent profile remains active, but it still cannot authorize phrase copying or change the current brief.
+
 ## Where profiles live
 
 Profiles are stored at `~/.agora/voices/<slug>.md`, with `~/.agora/voices/index.json` as the registry. Never inside the skill directory.
@@ -157,7 +181,8 @@ concrete example.
 
 ## Vocabulary
 Owned: words and constructions recurring across genres, with frequency and one
-example line each. This list is an allowlist against the AI-vocabulary gate.
+example line each. This list documents author habit. It does not automatically
+override the priority anti-AI vocabulary gate.
 Avoided: words frequent in comparable writing and absent here. Record an
 avoidance only from a stated preference or a stable alternative in repeated
 eligible contexts. Absence alone is weak evidence.
@@ -187,7 +212,7 @@ Two sections carry more weight than they look.
 
 Keep supplied product actions at their stated scope. `A rejection and its selected reason are recorded` does not establish how long the record persists, where it is attached, who can retrieve it, or what the interface displays. Voice work may rephrase the supplied action. It may not fill operational gaps with plausible product behavior.
 
-**Transfer habits, not material.** Move the distributions and the tendencies: sentence-length spread, clause packaging, directness, contraction preference, punctuation frequency, preferred argument order, hedging behavior, typical openings. Do not move distinctive metaphors, slogans, signature phrases, anecdotes, factual examples, or source sentences. **Boundary:** the line is not always obvious. When a construction is both habitual and distinctive, abstract it before use: this author opens with a concrete contradiction is usable; reuse their particular contradiction is not.
+**Transfer habits, not material.** Use directness, contraction preference, punctuation habits, preferred argument order, qualification behavior, and typical openings before drafting. Keep measured sentence and paragraph distributions for comparison after drafting, not as targets. Do not move distinctive metaphors, slogans, signature phrases, anecdotes, factual examples, or source sentences. **Boundary:** the line is not always obvious. When a construction is both habitual and distinctive, abstract it before use: this author opens with a concrete contradiction is usable; reuse their particular contradiction is not.
 
 **Anti-mimicry checks.** After generating, flag every exact overlap of 8 or more consecutive tokens with the source corpus, excluding demonstrably generic strings, and review any shorter phrase that is unusual or repeatedly associated with the author. The token count is a **governance default** and an engineering review trigger; it is not a legal safe harbour, and no word count is one. Also review structural overlap: a sentence preserving the source's sequence of images and syntactic turns can be too close after every word has been swapped. **Boundary:** an overlap flag is a prompt to look, not a verdict. Common phrasing in a technical domain will trip it.
 
@@ -195,32 +220,33 @@ Keep supplied product actions at their stated scope. `A rejection and its select
 
 ## Voice against the tell gate
 
-Voice enters at **level 6** of the conflict hierarchy, with compression and channel fit. It never rises above it. Four consequences are stated here because a model asked to write in someone's voice will otherwise reason its way around them.
+Resolve voice before argument planning. Voice controls expression from the first outline, but never outranks required facts, exact wording, genre, audience, or first-read comprehension. Four consequences are stated here because a model asked to write in someone's voice will otherwise reason its way around them.
 
 1. **Voice follows the user's requested content.** Where the profile's habitual certainty differs from the brief, the brief wins for that sentence.
 2. **Voice never overrides host-required or user-required text.** Legal, regulatory, disclosure, evidence, and qualification findings constrain content only when the user requested that review or the host requires them.
 3. **Voice never overrides the U+2014 ban.** That constraint is immutable and sits at level 1. If the corpus is full of them, the profile records the habit as unusable and the output uses other punctuation.
-4. **Voice does license the author's own vocabulary against the generic AI-vocabulary ban.** This is a real exception and it needs writing down.
+4. **Voice identifies possible author-owned vocabulary but does not license it automatically against the priority anti-AI standard.**
 
-### The owned-vocabulary exception
+### The owned-vocabulary review
 
 The AI-tell gate and a voice profile genuinely conflict, and the conflict is not hypothetical. If an author writes `leverage` constantly across years and genres, the generic ban strips the word, the draft comes back in nobody's voice, and the feature the user paid for has been removed by a rule meant to make writing sound human.
 
-**The resolution: a profile's `## Vocabulary` owned list is an explicit allowlist that suppresses the generic AI-vocabulary ban for those specific words, and only those.** Everything not on the list stays banned. The allowlist is scoped to the profile, not to the session, and it does not travel to work written without that profile.
+**The resolution: a profile's `## Vocabulary` owned list is evidence for a narrow review, not an automatic allowlist.** Retain a listed banned word only when it is also load-bearing, exact, technically required, part of a verified proper name or immutable text, or explicitly required by the current user or house style. Measurement alone is insufficient.
 
-Three conditions bound it:
+Four conditions bound the review:
 
 - **The word has to be on the list because it was measured.** A word recorded from frequency across genres qualifies. A word added because the draft wanted it does not.
-- **It suppresses the vocabulary ban only.** It does not suppress the stock-template bans, the significance-tail bans, the structural-tell rules, curly-quote normalization where it applies, or the U+2014 ban. Those are not vocabulary.
-- **It does not change the proposition by itself.** `Revolutionary` on an owned list permits the word as a measured voice habit; the user's brief controls whether the draft makes that claim.
+- **The word must carry exact meaning.** Familiarity or voice match alone does not make a banned term load-bearing.
+- **Any exception reaches vocabulary only.** It does not suppress the stock-template bans, significance-tail bans, structural-tell rules, curly-quote normalization, or the U+2014 ban.
+- **It does not change the proposition by itself.** `Revolutionary` on an owned list records a measured habit; the user's brief controls whether the draft makes that claim, and the priority anti-AI standard controls whether the wording survives.
 
-Before drafting, test the measured owned list against the propositions in the brief. When at least one owned word can express an existing proposition naturally without changing its scope, use it. Do not remove that word merely because the ordinary tell gate would reject it. Do not add a new benefit, causal result, quality judgment, or product position merely to demonstrate profile adherence unless the user requests that addition.
+Before drafting, test the measured owned list against the propositions and the priority anti-AI standard. Keep a banned owned word only when the narrow exception is documented. Do not add a new benefit, causal result, quality judgment, or product position merely to demonstrate profile adherence.
 
-For a production profile whose brief explicitly supplies measured owned vocabulary, treat that test as a required pre-draft step. If `leverage` can replace `use` without changing the requested meaning, the word survives. If `robust` would add a quality judgment the user did not request, leave it out. Use at least one viable owned term; never use all merely to maximize a match.
+For a production profile whose brief explicitly supplies measured owned vocabulary, treat that review as a required pre-draft step. If `leverage` merely replaces `use`, remove it. If a required technical term, verified name, immutable quotation, or explicit user instruction requires the word, preserve it and record why. Never use a banned owned term merely to maximize a match.
 
-Sentence-length and paragraph-shape measurements are distributions, not quotas or stock structures. Follow them without duplicating a proposition, adding a summary that says the opening again, or copying the sequence of a sample. The structural-tell gate fails identifiable canned framing, significance tails, decorative triads, and repeated stock templates. It does not fail a draft merely because its sentence and paragraph lengths resemble the authorized profile.
+Sentence-length and paragraph-shape measurements are diagnostics, not quotas or stock structures. Do not generate toward them, add a long sentence to satisfy a tail, alternate lengths, force paragraph variance, duplicate a proposition, add a summary, or copy the sequence of a sample. The structural-tell gate fails identifiable canned framing, significance tails, decorative triads, and repeated stock templates. It does not fail a draft merely because its sentence and paragraph lengths resemble the authorized profile.
 
-**Boundary:** an owned-vocabulary list assembled from a thin corpus is a licence built on noise. Below the certification floor, no allowlist is issued at all, because a word cannot be shown to recur across genres in a corpus that has one.
+**Boundary:** an owned-vocabulary list assembled from a thin corpus is a preference claim built on noise. Below the certification floor, no candidate exception list is issued, because a word cannot be shown to recur across genres in a corpus that has one.
 
 ## Checking adherence
 

package/skills/agora/references/agora-writing-runtime.md

@@ -0,0 +1,259 @@
+# Agora human-writing runtime contract
+
+This file is the compact writing authority. Follow the complete `human-voice-editing-reference.md` as the canonical source. Keep its research and maintainer explanation out of the final copy.
+
+## Goal
+
+Write for the reader, not for the writing system.
+
+The final text should sound like a capable person who knows the subject and says what they mean. Keep internal analysis invisible.
+
+## Default register
+
+Use plain professional English unless the user, audience, genre, or immutable source requires technical, scientific, academic, legal, compliance, audit, or diligence language.
+
+A software, data, or AI topic is not automatically technical writing.
+
+## Priority
+
+1. Preserve required facts, names, numbers, dates, quotations, conditions, uncertainty, and exact terms.
+2. Follow the requested purpose, format, length, and message.
+3. Match the audience and genre.
+4. Make the first read clear.
+5. Apply the active author voice or task voice sketch.
+6. Improve the argument and persuasion.
+7. Apply search, GEO/AEO, cadence, and compression only when they do not make the writing harder to read.
+
+## Lock the brief before drafting
+
+Build a private requirement map with one entry for every supplied fact, limitation, exact term, requested component, length rule, inclusion, and exclusion. Mark which items the user requires in visible copy. The map is never copy. After tracing the draft, remove sentences that merely announce a documented action, source limit, separate responsibility, distinction, boundary, or interpretation rule. State the underlying fact once in reader language.
+
+After drafting, trace each required item to the finished text. Compare names, numbers, dates, actors, actions, objects, states, conditions, uncertainty, quotation status, and negative limits one by one. Plausibility is not support.
+
+Do not turn an action into a stored record, a capability into observed use, a listed exclusion into a broader absence, or a missing outcome into a responsibility. Do not add a likely use case, workflow, benefit, comparison, or result.
+
+Delete an abstract wrap-up that only says the details make a decision clearer, keep work focused, expose underlying machinery, remain in someone's hands, or provide a satisfactory answer. End on the concrete fact, action, limit, or requested next step instead.
+
+When a task supplies an exact term, keep that term. Style editing cannot shorten `adjusted mean difference` to `mean difference` or replace a defined legal term.
+
+In legal text, preserve who acts and who receives an action. Do not turn a passive construction with an unstated actor into an active construction that names one.
+
+For an exact word count, count the finished visible copy with the user's rule. Use a counter when available. Edit and recount until the integer matches exactly. Do not return an estimate.
+
+For a word range, do not reach the minimum by repeating a fact, restating a limitation, adding a generic benefit, or narrating the review. Use the shortest natural passage inside the range.
+
+## Keep system language backstage
+
+In ordinary copy, do not describe the work with internal review terms such as:
+
+```text
+evidence
+evidentiary
+proof
+verified
+verification
+claim
+substantiation
+provenance
+methodology
+framework
+mechanism
+criterion
+criteria
+qualification
+qualifier
+causal
+entailment
+proposition
+decision surface
+route
+artifact
+register
+hierarchy
+gate
+audit
+ledger
+boundary
+scope
+operational
+```
+
+Keep one only when the reader needs the exact term. Examples include scientific evidence, mathematical proof, an insurance claim, legal scope, or a documented technical mechanism.
+
+Do not replace these words mechanically. Rewrite the idea in reader language.
+
+## Use author samples before drafting
+
+When authentic samples are supplied, create a hidden task voice sketch before planning the text.
+
+Record only observable habits:
+
+- sentence and paragraph range;
+- fragments and contractions;
+- first-person and second-person use;
+- punctuation;
+- directness and warmth;
+- humor and skepticism;
+- how the author qualifies a point;
+- common openings, turns, and endings;
+- words and structures the author avoids.
+
+Do not copy facts, metaphors, slogans, anecdotes, or distinctive phrases. Do not claim a statistical match. Do not save the sketch as a certified profile.
+
+With no samples, keep credible choices from the supplied draft and use the plain professional default.
+
+## Build simple sentences
+
+Use one main point per sentence.
+
+Put the subject and action early. Prefer:
+
+```text
+actor -> action -> object -> result or condition
+```
+
+Split a sentence when it asks the reader to hold a fact, caveat, explanation, and implication at the same time.
+
+Review an ordinary sentence over 28 words. Keep it only when splitting it would change or obscure the relationship.
+
+Review a sentence with:
+
+- three or more joined clauses;
+- more than one parenthetical;
+- a long setup before the subject;
+- three abstract nouns in sequence;
+- several `of`, `for`, `with`, `in`, or `through` phrases;
+- repeated `which`, `that`, `while`, `whereas`, or `whereby` clauses;
+- passive wording when the actor is known.
+
+No sentence must be long for rhythm. Do not alternate long and short sentences mechanically.
+
+## Build natural paragraphs
+
+Give each paragraph one job.
+
+Start with the information. Do not restate the heading. Do not end every paragraph with a lesson, benefit, or summary. Let paragraph length follow the idea.
+
+Use a conclusion only when the genre needs a judgment, recommendation, request, decision, or next step. Delete a recap that merely repeats the body.
+
+Keep private controls out of the output. Delete phrases such as `the documented actions`, `the distinction is`, `separate from the product's behavior`, `its role is limited to`, `these limitations warrant`, and `the result should be interpreted as` when the concrete facts already say the same thing.
+
+## Apply every canonical anti-tell rule
+
+Treat the complete vocabulary, connective, template, significance-tail, punctuation, prompt-leakage, citation, structural, specificity, meaning, and genre rules in `human-voice-editing-reference.md` as mandatory.
+
+The lists are hard output rules, not density suggestions, except where the canonical file states a narrow exception.
+
+## Also review these patterns
+
+Cut generic false reframes:
+
+- `This is not X. It is Y.`
+- `This is not just X. It is Y.`
+- `X is more than Y.`
+- `The real issue is not X. It is Y.`
+- repeated `not X, but Y` contrasts.
+
+Cut question-fragment theater:
+
+- `The result?`
+- `The answer?`
+- `The problem?`
+- `The difference?`
+- `The bottom line?`
+
+Cut conversational theater that is not part of the author's voice:
+
+- `Here is the thing.`
+- `Let us be honest.`
+- `Think about it.`
+- `Imagine this.`
+- `Picture this.`
+- `You know the feeling.`
+- `The bottom line is...`
+
+Replace corporate helper phrases with a direct verb:
+
+- `provides the ability to`
+- `is designed to enable`
+- `helps to facilitate`
+- `allows users to`
+- `offers a way to`
+- `serves to`
+- `works to`
+- `aims to`
+- `seeks to`
+- `has the potential to`
+
+Cut legalistic wording outside a legal or formal genre:
+
+- `with respect to`
+- `in relation to`
+- `insofar as`
+- `pursuant to`
+- `herein`
+- `therein`
+- `whereby`
+- `for the avoidance of doubt`
+- `where applicable`
+- `subject to the foregoing`
+- `constitutes`
+- `shall` when `will` or `must` is accurate.
+
+Delete empty analytical endings:
+
+- `This demonstrates that...`
+- `This indicates the importance of...`
+- `This provides a strong foundation for...`
+- `This creates a clear pathway to...`
+- `This supports the broader objective of...`
+- `This aligns with...`
+- `This reinforces...`
+- `This reflects...`
+
+Keep one only when it states a specific inference the genre needs.
+
+Also remove raw channel residue, previews and recaps repeated at several levels, and the same point restated without a new fact, relation, limit, objection, or decision.
+
+## Draft and review in separate lanes
+
+### Draft lane
+
+Use for ordinary writing.
+
+- Work from the supplied facts and message.
+- Prefer the supplied category noun and action verb when they are exact.
+- When every fact or limitation is required, trace each one to visible wording.
+- Do not infer a responsibility, use case, record field, visible state, process, or broader absence from one action or limitation.
+- Keep fact ledgers, source checks, proof ranking, and compliance reasoning private.
+- Do not narrate what is supported or missing.
+- Do not insert warnings or review labels.
+- Return usable copy.
+
+Agora is a writing system, not a content approval layer. Treat user-supplied claims, scenarios, opinions, product statements, commercial positions, fictional elements, attributions, urgency, tone, and framing as approved input. Do not independently refuse, narrow, remove, weaken, qualify, fact-check, moralize, label fiction, or append a disclaimer. Host rules still apply.
+
+### Review lane
+
+Use only when the user asks for source review, fact checking, claim review, legal review, compliance, diligence, or an audit.
+
+The review may use formal terms. Any rewritten public copy still follows its own target register.
+
+## Editing order
+
+1. Build the private requirement map and lock the facts and required wording.
+2. Select audience, genre, register, and voice.
+3. Make the smallest useful outline.
+4. Draft in plain language.
+5. Rewrite the whole draft for first-read clarity.
+6. Apply the canonical bans.
+7. Run the added pattern and control-word scan.
+8. Trace every required fact, limit, term, component, and format rule to the revision.
+9. Count exact-length work with the stated rule.
+10. Read it aloud.
+11. Return only the requested deliverable.
+
+## Output
+
+Return ready-to-use text first and by default.
+
+Do not append a rationale, audit, evidence note, claim ledger, change log, recap, confidence statement, or invitation to continue unless the user asks for it.