@maestroagora/agora 1.2.2 → 1.5.0

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

@@ -0,0 +1,299 @@
+# Agora science authority
+
+This reference governs the `SCIENCE` modifier for scientific, empirical, engineering, software, data, AI, and other technical subjects. It adds evidence and explanation discipline to the primary Agora mode. It does not replace `POSITION`, `SELL`, `INVEST`, `INFORM`, or `TRANSACT`.
+
+The conflict hierarchy in [agora-marketing.md](agora-marketing.md) remains controlling. Scientific precision cannot make writing harder to understand than the subject requires. Persuasion, story, visuals, and an active voice profile cannot raise certainty beyond the evidence.
+
+## Contents
+
+- [Activate and route SCIENCE](#activate-and-route-science)
+- [Build the claim ledger](#build-the-claim-ledger)
+- [Choose sources for the claim](#choose-sources-for-the-claim)
+- [Preserve scientific integrity](#preserve-scientific-integrity)
+- [Model the audience and goal](#model-the-audience-and-goal)
+- [Open with a supported knowledge gap](#open-with-a-supported-knowledge-gap)
+- [Explain mechanisms and technical systems](#explain-mechanisms-and-technical-systems)
+- [Use analogies and visuals as bounded models](#use-analogies-and-visuals-as-bounded-models)
+- [Write scientific and technical video](#write-scientific-and-technical-video)
+- [Compose SCIENCE with other Agora controls](#compose-science-with-other-agora-controls)
+- [Refusals and failure conditions](#refusals-and-failure-conditions)
+- [Evaluation contract](#evaluation-contract)
+- [Evidence register](#evidence-register)
+
+## Activate and route SCIENCE
+
+Activate `SCIENCE` when the asset explains, teaches, compares, summarizes, or persuades through scientific evidence or technical behavior. Select one internal route:
+
+| Route | Use for | Evidence focus |
+|---|---|---|
+| `EMPIRICAL` | Studies, experiments, observations, measurements, datasets, and research findings | Design, population, measurement, effect, uncertainty, and applicability |
+| `TECHNICAL` | Systems, interfaces, mechanisms, architecture, software, engineering, and failure behavior | Inputs, state changes, outputs, dependencies, constraints, and tradeoffs |
+| `MIXED` | An empirical result explained through a technical or scientific mechanism | Keep observed result and proposed explanation distinct |
+
+Choose the primary mode first. A public science explainer is normally `INFORM + SCIENCE`. A technical product page is `SELL + SCIENCE`. An investor memo about a research platform is `INVEST + SCIENCE`. The modifier controls what the evidence permits and how the explanation works; the mode controls the decision the reader faces.
+
+Rule [HOUSE]: do not treat all technical writing as empirical science. An API contract needs exact documented behavior, not a research-study frame. Boundary: a technical claim supported by benchmark data uses `MIXED`, because its measured result still needs empirical qualification.
+
+## Build the claim ledger
+
+Classify every material claim before drafting. Never raise a claim's certainty while simplifying it.
+
+| Claim class | Meaning | Permitted treatment |
+|---|---|---|
+| Direct observation or measured result | The named source measured or observed it | State design, scope, comparator, outcome, and uncertainty when material |
+| Established fact or current consensus | Multiple relevant authorities support it within a named domain | Name scope and current authority; do not imply unanimity |
+| Model or proposed mechanism | Explains how a result may arise | Present as model or mechanism, not as an observed result |
+| Interpretation | A reasoned reading of evidence | Attribute it and show the evidence it interprets |
+| Implication | A possible consequence for a decision or system | State the additional assumptions between result and consequence |
+| Recommendation | An action proposed from evidence plus values, costs, or constraints | Separate the evidence from the judgment that selects the action |
+| Hypothesis or speculation | Testable or exploratory possibility | Label it directly; do not use certainty syntax |
+| Unknown or unmeasured | Evidence does not answer the question | Say `unknown`, `not measured`, or the narrower exact condition |
+
+Rule [A]: distinguish a study result from its interpretation and from a recommendation. Evidence alone rarely supplies every value, cost, feasibility, and preference needed for a decision. Boundary: an official safety requirement may directly prescribe action; reproduce its scope and authority rather than recasting it as optional interpretation. See [Cochrane on interpreting results and drawing conclusions](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15).
+
+## Choose sources for the claim
+
+Source choice follows the claim, not a universal prestige ladder.
+
+1. Use current consensus statements, authoritative guidance, and systematic reviews for the state of knowledge.
+2. Use primary papers and datasets for a specific study, observation, or measured result.
+3. Use official standards, specifications, and product documentation for technical behavior.
+4. Use reputable secondary sources for orientation and discovery, then follow them to primary support for material claims.
+5. Use practitioner sources for communication procedures and examples, not as proof that a scientific or commercial effect occurs.
+
+Rule [A]: for medical, legal, financial, safety-critical, or rapidly changing technical claims, retrieve current authoritative sources before writing. The static skill cannot establish current facts. Boundary: stable explanatory mechanics may still rely on a supplied canonical source when the user has fixed the source set.
+
+Rule [HOUSE]: match the source date to the claim's drift risk. A current software behavior needs current official documentation. A historical experiment needs its original paper plus later correction or replication when material.
+
+When sources disagree:
+
+- Identify whether they measured the same population, intervention, comparator, outcome, and period.
+- Separate genuine scientific disagreement from different questions or definitions.
+- Weight sources by relevance, design, directness, and certainty.
+- Do not manufacture a balanced debate between a strong consensus and unsupported fringe assertion.
+- Do not hide credible disagreement merely to produce a cleaner story.
+
+State the central evidence-weighting correction directly. If the sources do not support describing the field as evenly divided, say that plainly before explaining the narrower minority finding. Do not make the reader infer the rejection of false balance from softer phrases such as `the disagreement is narrower`.
+
+For an unresolved minority finding, make the unknowns operational. Ask whether it replicates under the same condition, generalizes beyond the studied population, survives aligned outcome definitions and measurement methods, and changes the relationship between the proposed mechanisms. Include only dimensions the supplied source differences make relevant.
+
+## Preserve scientific integrity
+
+### Scope the result
+
+Include when material:
+
+- study design;
+- population and sample;
+- intervention or exposure;
+- comparator;
+- outcome and measurement method;
+- time period;
+- baseline and denominator;
+- estimate and uncertainty;
+- material exclusions;
+- applicability outside the studied setting.
+
+Qualification belongs next to the claim it changes. It does not need to occupy every sentence. Use a short passage, table, caption, or adjacent note when that preserves both accuracy and comprehension.
+
+### Separate causality
+
+Use causal verbs only when the design and source support them.
+
+| Evidence permits | Prefer |
+|---|---|
+| Direct causal support within stated conditions | `caused`, `increased`, `reduced` |
+| Observational relationship | `was associated with`, `tracked with`, `coincided with` |
+| Mechanistic compatibility | `is consistent with`, `could explain`, `supports the proposed mechanism` |
+| Early or limited evidence | `suggests`, `may`, `provides preliminary evidence` |
+| No measurement | `unknown`, `not measured`, `not established` |
+
+Never convert association into causation, mechanism into outcome, or temporal order into effect.
+
+For a one-time observational measurement, state when temporal order is unknown and reverse causation remains possible. Name residual confounders even after stated adjustment. When proposing a stronger causal test, do not pretend an investigator can directly assign an exposure that is impractical or unethical to control. Randomize a feasible intervention, opportunity, encouragement, or program when appropriate, then measure the outcome repeatedly over time. A longitudinal design improves temporal evidence but does not become randomized merely because it has repeated measurements.
+
+### Preserve statistical meaning
+
+Rule [A]: report magnitude and uncertainty, not a significance label alone. A small p-value does not establish effect size, importance, certainty, or a useful decision. See the [ASA statement on p-values](https://www.amstat.org/asa/files/pdfs/p-valuestatement.pdf) and [Cochrane's interpretation guidance](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15).
+
+When material:
+
+- Give absolute and relative effects together.
+- When event rates permit it, give natural frequencies and the absolute percentage-point change together; neither should be replaced by a relative percentage.
+- State the baseline risk or denominator.
+- Distinguish statistical significance from practical importance.
+- State the uncertainty interval without translating it into certainty it does not provide.
+- Do not interpret `not statistically significant` as proof of no effect.
+- Do not imply replication or consensus from one study.
+- Distinguish exploratory from confirmatory analysis when the source does.
+- Preserve risk of bias, indirectness, inconsistency, imprecision, and publication-bias limits when they affect the conclusion.
+
+For patient-facing material, state when one result alone cannot determine an individual's action. Practical importance depends on event severity, baseline risk, expected benefit, alternatives, patient characteristics, and preferences, not only the relative or absolute number.
+
+### Calibrate uncertainty
+
+Use the narrowest accurate certainty language. `Observed` names a result. `Supports` names evidentiary weight. `Suggests` signals limited support. `May` identifies a possibility. `Remains unknown` identifies a gap.
+
+Rule [A]: absence of evidence is not evidence of absence unless the study had enough sensitivity, power, and scope to make the null informative. Boundary: a well-designed equivalence or non-inferiority analysis may support a bounded no-material-difference conclusion.
+
+When weighing a minority or conflicting result, describe its design, population, outcome, comparability, replication state, and unresolved question. Do not call it `credible`, `promising`, `compelling`, `important`, or use another evaluative adjective unless the supplied synthesis supports that judgment. Preserving a finding does not require endorsing it.
+
+## Model the audience and goal
+
+Classify the intended reader:
+
+| Audience | Preserve | Remove or explain |
+|---|---|---|
+| General public | Concrete phenomenon, scale, mechanism, uncertainty, and consequence | Unintroduced field shorthand and method detail that does not change meaning |
+| Adjacent expert | Cross-domain definitions, assumptions, and mechanism | Local jargon and compressed inferential steps |
+| Domain expert | Exact technical terms, design, uncertainty, and edge conditions | Introductory explanation the decision does not need |
+| Technical or policy decision-maker | Options, evidence strength, tradeoffs, costs, failure modes, and action conditions | Detail that does not change the decision |
+
+Rule [A/HOUSE]: align the communication method with the audience and the actual goal. The National Academies concludes that effective science communication depends on the communicator's goal and context; the audience table above is an Agora routing aid rather than a measured four-stage law. See [Communicating Science Effectively](https://nap.nationalacademies.org/catalog/23674/communicating-science-effectively-a-research-agenda).
+
+Do not assume an expert audience wants abstraction or emotional absence. Experts need exact terms where they compress shared meaning, concrete causal steps where they do not, and enough consequence to understand why the issue matters.
+
+## Open with a supported knowledge gap
+
+Choose an opening that serves the audience's question:
+
+- A supported misconception.
+- A surprising observation.
+- A practical failure or anomaly.
+- A contradiction between prediction and result.
+- A question whose answer changes the reader's model.
+- The direct answer, when delay would cost safety or task completion.
+
+Rule [D]: a supported misconception can reveal that the audience's current model will not explain the result. Correct it near its introduction, then show the replacement model. This is a practitioner procedure derived from the 2026 video analysis; it is not a universal learning or retention law. Boundary: do not use it when the audience does not hold the belief, when repeating the claim would confuse, or when direct instruction is safer.
+
+When the supplied facts contain a counter-observation the misconception cannot explain, use that observation to make the correction decisive before teaching the replacement model. Do not invent a counter-observation merely to strengthen the reveal. An additional established fact may appear only when the source requirements for that surface permit it. The useful sequence is `supported belief -> supported contradiction -> corrected model -> mechanism -> boundary`.
+
+Rule [D]: asking a consequential question before the explanation can create a useful information gap. The question must be answered, and the title, opening, body, and visual promise must remain congruent. Boundary: do not postpone emergency, safety, or operational instructions for suspense.
+
+Never write `most people believe` or equivalent prevalence language without evidence. Never invent a misconception to produce a hook.
+
+## Explain mechanisms and technical systems
+
+For a scientific mechanism, show:
+
+`initial condition -> acting entity or force -> state change -> observable result -> boundary`
+
+For a technical system, show:
+
+`input -> component or actor -> transformation -> state or storage -> output -> dependency -> failure mode`
+
+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.
+
+Separate these questions:
+
+1. What happened?
+2. How was it measured or observed?
+3. What mechanism could produce it?
+4. What else could explain it?
+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.
+
+## Use analogies and visuals as bounded models
+
+Every analogy must identify:
+
+- what maps;
+- what does not map;
+- where the analogy breaks;
+- whether it explains behavior, mechanism, scale, or only intuition.
+
+Rule [D/HOUSE]: use analogy as a bridge into the real definition, not as a replacement. Boundary: skip it when the audience already owns the model, when the mapping introduces a false causal picture, or when the correction would take longer than the direct explanation.
+
+Visuals must carry evidence, sequence, comparison, scale, uncertainty, or mechanism. A decorative laboratory image, molecule, dashboard, or code screen is not proof.
+
+For charts and diagrams:
+
+- State what is measured.
+- Preserve axes, units, baseline, denominator, and uncertainty.
+- 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.
+
+## Write scientific and technical video
+
+Route narration as `SPOKEN_ONLY` and titles, descriptions, captions, transcripts, show notes, and companion pages as their own written surfaces.
+
+Use this optional sequence when the material supports it:
+
+1. Open a real question or model failure.
+2. Show the phenomenon, person, experiment, or operational consequence.
+3. Explain the mechanism in audible steps.
+4. Return to the phenomenon with the model changed.
+5. Close the question and state the evidence boundary.
+
+Rule [D]: an A-thread can carry the human, visual, experimental, or operational sequence while a B-thread carries the technical mechanism. Alternate only when each return advances the same explanation. Boundary: do not intercut two weak threads, interrupt a short explanation, or claim the structure improves retention without direct measurement.
+
+When the request explicitly requires A/B threading, make both threads visible in the spoken artifact. Use concise scene or visual cues where the medium needs them, return the A-thread at mechanism payoffs, and prevent the human or experimental thread from disappearing through the technical middle. A spoken explanation with one opening anecdote and an uninterrupted lecture is not A/B threading.
+
+Title and thumbnail may create curiosity but cannot imply a different result, certainty, scale, or mechanism than the body supplies. Do not infer a performance law from one video's views or a creator's account of analytics.
+
+## Compose SCIENCE with other Agora controls
+
+### `SELL + SCIENCE`
+
+Use the strongest commercial claim supported by the technical or empirical evidence. Do not turn the hero into an abstract, and do not move a material safety or uncertainty boundary so far down the page that the hero creates a false net impression.
+
+### `CASE_STUDY + SCIENCE`
+
+Load [agora-case-studies.md](agora-case-studies.md). Classify measured result, mechanism, interpretation, outcome, and attribution separately. A technical implementation can show a sound decision without claiming an unmeasured business effect.
+
+### `VOICE + SCIENCE`
+
+An authorized profile enters at hierarchy level 6. Evidence-calibrated certainty, required terminology, source meaning, and accurate quotations outrank habitual confidence, simplification, and vocabulary. Do not transfer a source author's opinions or certainty into a new claim.
+
+### `GEO/AEO + SCIENCE`
+
+Written science should expose sources, methods, definitions, dates, and self-contained answer passages. The hero or spoken opening does not need to carry the full method. Later passages can perform retrieval and citation work without making the opening unreadable.
+
+## Refusals and failure conditions
+
+Refuse or narrow work that would require:
+
+- fabricating a paper, source, statistic, consensus, quote, result, or mechanism;
+- presenting medical, legal, financial, or safety advice as current without authoritative verification;
+- hiding uncertainty or a material competing explanation;
+- converting a correlation into a causal claim;
+- using a false misconception or false balance for drama;
+- altering a source quotation and presenting it as exact;
+- using decorative visuals as evidence;
+- implying that views, clicks, or narration establish a learning or sales effect.
+
+## Evaluation contract
+
+Hard gates:
+
+- Claim classes remain distinct.
+- Source scope survives.
+- Causality is calibrated.
+- Statistical magnitude and uncertainty survive when material.
+- 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:
+
+- Hook payoff.
+- Conceptual clarity.
+- Claim separation.
+- Uncertainty calibration.
+- Causal and statistical integrity.
+- Analogy boundaries.
+- Visual and narrative integration.
+- Audience fit.
+
+## Evidence register
+
+- **A:** [National Academies, Communicating Science Effectively](https://nap.nationalacademies.org/catalog/23674/communicating-science-effectively-a-research-agenda) for goal- and context-dependent communication, not for a universal story formula.
+- **A:** [Cochrane Handbook chapter 15](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-15) for effect interpretation, uncertainty, applicability, and the distinction between evidence and recommendations.
+- **A:** [Cochrane Handbook chapter 14](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-14) for absolute and relative effects and structured certainty assessment.
+- **A:** [ASA statement on p-values](https://www.amstat.org/asa/files/pdfs/p-valuestatement.pdf) for limits on p-value interpretation.
+- **D:** 2026 practitioner videos on misconception hooks, question-first explanation, A/B threading, audience adaptation, visual explanation, and bounded analogy. These support procedures to test, never universal outcome claims.
+- **HOUSE:** route names, audience table, claim-ledger format, system sequence, and evaluation gates. They operationalize the stronger authorities and carry the boundaries stated above.

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

@@ -0,0 +1,270 @@
+# 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.
+
+Voice is a modifier, never a licence. It changes how a supported proposition is expressed. It cannot change the proposition, and it cannot change what the evidence permits. Read [agora-marketing.md](agora-marketing.md) for the truth rules that outrank everything here, and [agora-craft.md](agora-craft.md) for the rhythm controls a profile replaces.
+
+## Contents
+
+- [What VOICE is](#what-voice-is)
+- [Where profiles live](#where-profiles-live)
+- [Corpus admission](#corpus-admission)
+- [What gets measured](#what-gets-measured)
+- [The profile format](#the-profile-format)
+- [Writing to a profile](#writing-to-a-profile)
+- [Voice against the tell gate](#voice-against-the-tell-gate)
+- [Checking adherence](#checking-adherence)
+- [Refusals](#refusals)
+
+## 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.
+
+The surface:
+
+```text
+voice build --name <slug> --from <corpus path or URL>
+  Reads the corpus, measures it, writes the profile, and reports both what it
+  measured and what the corpus was too small or too narrow to measure.
+
+voice list
+  The profiles that exist, with corpus size, register coverage, and last update.
+
+<mode> --voice <slug>
+  Ordinary Agora work, with the profile loaded at the human-voice stage.
+
+voice check --voice <slug> <draft path>
+  Measures the draft against the profile and reports the drift, largest first.
+```
+
+Every one of these runs through the shipped measurement engine rather than through model judgment:
+
+```text
+npx -p @maestroagora/agora agora-voice build --name <slug> --from <path> [--from <path>]...
+npx -p @maestroagora/agora agora-voice list
+npx -p @maestroagora/agora agora-voice check --voice <slug> <draft path>
+npx -p @maestroagora/agora agora-voice default --voice <slug>
+```
+
+`--register <name>` labels every `--from` that follows it, `--store <path>` overrides the profile directory, and `--json` returns machine-readable output. Markdown, plain text, and HTML are read. Binary document formats are refused by name rather than partially extracted, because every admission threshold counts clean words and a partial extraction would move all of them without saying so.
+
+`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.
+
+**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.
+
+## Where profiles live
+
+Profiles are stored at `~/.agora/voices/<slug>.md`, with `~/.agora/voices/index.json` as the registry. Never inside the skill directory.
+
+A third file, `~/.agora/voices/<slug>.measurements.json`, carries the machine-readable feature values that `voice check` compares against, so the human-readable profile never has to be parsed back. It also carries the phrase-overlap index as truncated hashes of each token run rather than as text, so the profile store never becomes a second copy of the author's corpus and cannot serve as a phrase reservoir.
+
+This is not a preference. The documented update path replaces the installed skill directory, so a profile written under `~/.claude/skills/agora/` or `~/.agents/skills/agora/` is destroyed on the next update, silently, and the user loses hours of work. `~/.agora/` also survives switching hosts, so a profile built under one client is available from another, which matches how the package already installs to both.
+
+`--store <path>` overrides the location for a project-local profile committed beside a repository. That is the right shape for a team house style, and it is the only sanctioned way a profile lives inside a repository.
+
+**Boundary:** a project-local profile is a house style, not a person. Do not label it with an individual's name unless that individual authorized it, and do not carry an individual profile into a shared repository without their agreement.
+
+## Corpus admission
+
+Measure **clean author-controlled words**: the author's own prose after removing quotations, forwarded text, copied source material, boilerplate, templates, legal disclaimers, automatic signatures, and house-written headlines. Every threshold below counts clean words, never raw ones.
+
+| Clean words | Disposition | Basis |
+|---|---|---|
+| Under 5,000 | **Refuse to certify a profile.** Report what was found and what the corpus needs. | **B.** Controlled sample-size experiments put minimum stable stylometric samples at roughly 2,500 words for some corpora and around 5,000 for most modern-language English text; below the stable region estimates are unreliable rather than merely noisy ([Eder](https://doi.org/10.1093/llc/fqt066)). |
+| 5,000 to 10,000 | Build with `confidence: low`. Restrict the measured section to features that stay stable on short texts, and write a loud `## Not captured`. | **B**, from the same sample-size experiments ([Eder](https://doi.org/10.1093/llc/fqt066)). |
+| 10,000 and above | Production minimum for a persistent profile. | **C.** More than 10,000 words per author is the traditional reliable minimum in attribution research ([Luyckx and Daelemans](https://aclanthology.org/C08-1065/)). |
+| 20,000 to 30,000 | Preferred tier. Enough to estimate tails, rare punctuation, paragraph distributions, and more than one register without one document dominating. | Governance default, chosen as an engineering target and not an empirical threshold. |
+
+**Boundary on all four rows:** the word counts come from authorship-attribution research on literary and journalistic corpora, not from a controlled study of generative voice synthesis. Ten thousand contaminated, single-register, heavily edited, or formulaic words are still unusable, and the count is a floor rather than a certificate.
+
+Four structural requirements sit on top of the word count. Each is a **governance default**, chosen so the build has something checkable to enforce.
+
+- **Document independence.** Require at least 10 independently composed documents, with no single document supplying more than 25 percent of the clean tokens. Governance default. A single long article is not equivalent to many independent samples, because cross-document stability is the thing being measured.
+- **Register subprofiles.** A register earns its own numbers only at 2,500 clean words across at least 3 independent documents. Governance default. Below that, record qualitative observations and mark every number provisional.
+- **Feature stability.** A candidate global feature fails persistence when register accounts for more than 30 percent of its document-level variance, or when deleting one document moves its pooled estimate by more than 20 percent. Both figures are governance defaults. A failing feature moves into a register override or is dropped. The variance rule is skipped for a feature whose spread across the whole corpus is under 5 percent of its own pooled value, because a feature that barely moves has no meaningful spread for register to explain and the ratio becomes unstable at that scale. That 5 percent is also a governance default.
+- **Heterogeneity stop.** Mark the corpus not profileable as one voice when more than a third of the proposed core features fail the stability rule, when collaborative or editorial authorship cannot be separated, or when the clean corpus falls below the certification floor after exclusions. Offer to build two profiles rather than averaging two registers into a voice that belongs to nobody. Governance default.
+
+**Rule [B]: separate stable author effects from topic and register before calling anything voice.** Topic-specific information contaminates authorship features, and situation-conditioned variation is a large part of what stylometry actually measures ([Stamatatos](https://aclanthology.org/E17-1107/), [Grieve](https://doi.org/10.1515/cllt-2022-0040)). **Boundary:** a writer who only ever writes one narrow genre cannot supply enough variation to separate personal voice from that genre. Label the profile genre-bound and say so in `## Not captured`.
+
+**Rule [B]: do not assume strong in-domain results prove cross-genre stability.** Attribution degrades substantially when training and test contexts diverge ([Stamatatos](https://aclanthology.org/E17-1107/)). **Boundary:** a profile intended for one fixed genre does not need to generalize, and marking it single-genre is a complete answer.
+
+**Separate the author from the editor and the employer.** Where drafts and published versions both exist, compute the deltas; any feature editors repeatedly change is editor-sensitive and stays out of the persistent profile unless the author deliberately adopts it. Where only published work exists, compare against other writers at the same outlet and mark broadly shared features as house-style confounds. **Boundary:** this is a governance procedure with no measured effect size. It is here because an unseparated profile silently models the publication rather than the person.
+
+## What gets measured
+
+Stylometry has no single fingerprint. Attribution works by combining partially discriminative feature families, and topic and register are the major confounders ([Grieve](https://doi.org/10.1093/llc/fqm020), [Stamatatos](https://aclanthology.org/E17-1107/)).
+
+**Rule [B]: treat function words, punctuation, syntax, and character patterns as a bundle. Never declare one of them a voice fingerprint** ([Grieve](https://doi.org/10.1093/llc/fqm020), [Stamatatos](https://aclanthology.org/E17-1107/))**. Boundary:** a constrained genre with plenty of data can make one family highly predictive without making it a general property of that author.
+
+**Rule [B]: store distributions, not only averages.** For sentence and paragraph length, record at least the median, the standard deviation, the tenth and ninetieth percentiles, and the binned shape alongside the mean. Distributional spread separates texts whose central tendencies overlap ([Munoz-Ortiz et al.](https://doi.org/10.1007/s10462-024-10903-2)). **Boundary:** percentiles and shape statistics are unstable on very few observations, so a short corpus gets a median and a mean and an explicit note that the tails are unknown.
+
+**Rule [A]: never compare raw type-token ratio across unequal text lengths.** The measure falls mechanically as texts grow, so an unequal comparison is an artifact ([Covington and McFall](https://doi.org/10.1080/09296171003643098)). Use a moving-window measure or a decay-based one instead ([McCarthy and Jarvis](https://doi.org/10.3758/BRM.42.2.381)). **Boundary:** raw ratio becomes interpretable again when every sample is truncated to the same sufficiently large token count, though sampling noise remains.
+
+The feature families worth recording, and what each is good for:
+
+| Family | Records | Reliability note |
+|---|---|---|
+| Sentence length | Mean, median, standard deviation, coefficient of variation, percentiles, binned shape | The clearest check for uniform pacing. Unstable below a few dozen sentences. |
+| Clause structure | Finite clauses per sentence, subordination ratio, clause-depth shares | Genre-sensitive and parser-sensitive. Freeze one definition and never compare across parsers. |
+| Function words | Frequencies per thousand tokens for articles, prepositions, auxiliaries, conjunctions, pronouns | Among the most established families and comparatively usable on shorter samples ([function-word adjacency networks](https://arxiv.org/abs/1406.4469)). Still moved by register. |
+| Punctuation | Commas, semicolons, colons, parentheses, ellipses, exclamation marks, per thousand tokens | Discriminative, and an editor can overwrite it almost completely. Rare marks need a large corpus. |
+| Paragraph shape | Words and sentences per paragraph, one-sentence-paragraph share, distribution | Useful for synthesis, weak as identity evidence, because platform and editing dominate it. |
+| Lexical diversity | Moving-window ratio and a decay-based measure, never raw ratio alone | See the rule above. |
+| Person and stance | First, second, and third person rates; hedging and modal profile; certainty behavior | Heavily conditioned by genre. Measure per register. |
+| Sentence openings | Class of the first constituent, and the transition pattern between classes | The best available handle on perceived repetitiveness that length statistics miss. |
+| Contractions | Rate within contexts where both forms were grammatical, not raw count | Only comparable within a matched register. |
+
+**Boundary on the whole table:** every one of these is descriptive. None of them establishes that a draft sounds right to its author, and a feature match is not approval. Grade B, from the same attribution and register work cited above.
+
+Anything the corpus is too small to estimate is written as insufficient data. It is never guessed, never interpolated, and never quietly omitted.
+
+## The profile format
+
+A profile is human-readable Markdown with YAML frontmatter, stored at the path above. Measurement, interpretation, calibration, and source excerpts stay separate. Never collapse them into a sentence like write exactly like this person.
+
+```markdown
+---
+name: <slug>
+created: <date>
+updated: <date>
+corpus:
+  documents: <count>
+  clean_words: <count>
+  raw_words: <count>
+  registers: [<register>, <register>]
+  excluded: [<what the cleaning removed, with counts>]
+pipeline:
+  tokenizer: "<frozen implementation and version>"
+  segmenter: "<frozen implementation and version>"
+  lexicon: "<frozen implementation and version>"
+  parser: "<frozen implementation and version>"
+confidence: low | medium | production
+certified: true | false
+---
+
+# Voice profile: <slug>
+
+## Measured
+A table of features with the value, the corpus spread, and the register it
+was computed on. Insufficient data is written, not guessed.
+
+## Structural habits
+How this author opens. How they close. Where the qualifier goes. Whether the
+conclusion is front-loaded. How a list is handled. How long before the first
+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.
+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.
+
+## Calibration
+Directness, humor, certainty, disagreement, and authority, each on a stated
+scale with an example at this author's level.
+
+## Excerpts
+Six to ten passages spanning the corpus by register and date, each labelled
+with what it demonstrates. Include at least one weaker passage.
+
+## Not captured
+What the corpus could not tell us, which genres are missing, and what the
+author should supply to improve the profile.
+```
+
+Two sections carry more weight than they look.
+
+**`## Excerpts` is stratified, not curated.** Select by register, date, and document type rather than choosing the author's best passages. A profile built only from an author's strongest work produces drafts the author does not recognize, because it encodes an exceptional performance as the central tendency. **Boundary:** governance default, no measured effect. Keep excerpts short enough to calibrate and too short to serve as a phrase reservoir.
+
+**`## Not captured` is not optional.** A profile that hides its own gaps produces confident wrong output, and the gaps are the part a user cannot infer from the rest of the file. **Boundary:** none. A profile without this section is not a profile.
+
+## Writing to a profile
+
+**The content firewall.** A profile authorizes how a proposition is expressed. It never authorizes the proposition. Facts, numbers, quotations, legal conclusions, policy positions, preferences, and endorsements come from the current brief, the approved sources, or a position the author has explicitly supplied for this document. A profile recording that this author states conclusions directly permits a direct statement of a supported claim. It never permits inventing what they think.
+
+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.
+
+**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.
+
+**Profile-first generation.** Where the architecture allows it, generate from the compact profile rather than re-injecting the whole corpus into context. Excerpts are for calibration and verification, not sentence completion. **Boundary:** governance procedure, no measured effect. It is here because corpus-in-context generation is how phrase reuse happens.
+
+## 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.
+
+1. **Voice never licenses a claim the facts do not support.** Where the author habitually writes with high certainty and the evidence is thin, the evidence wins and the profile is overridden for that sentence. Note the override rather than hiding it.
+2. **Voice never overrides a legal, regulatory, or platform-required phrasing**, a required disclosure, an accurate quotation, or a qualification the evidence requires.
+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.
+
+### The owned-vocabulary exception
+
+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.
+
+Three conditions bound it:
+
+- **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, the curly-quote ban, or the U+2014 ban. Those are not vocabulary.
+- **It never converts a banned claim into an acceptable one.** `Revolutionary` on an owned list permits the word where the facts already support the claim it makes. It does not make the claim supportable.
+
+Before drafting, test the measured owned list against the supported propositions. 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. An owned word is optional only when no supported sentence can carry it. Do not use owned vocabulary to manufacture a benefit, causal result, quality judgment, or product position merely to demonstrate profile adherence. Test the sentence without the owned word first; if the underlying claim is unsupported, omit the claim and accept a lower vocabulary match.
+
+For a production profile whose brief explicitly supplies measured owned vocabulary, treat that test as a required pre-draft step. If `leverage` can truthfully replace `use` in a sentence about an existing input, the word survives. If `robust` would add an unsupported quality judgment, it does not. Use at least one viable owned term; never use all 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.
+
+**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.
+
+## Checking adherence
+
+`voice check` computes the same features on the draft, using the same frozen pipeline, and reports drift against the profile with the three largest deviations first.
+
+**Rule [B]: do not make a strong style-match claim on a short draft merely because its feature vector is close.** Attribution estimates are unstable below corpus-dependent sample lengths in the low thousands of words ([Eder](https://doi.org/10.1093/llc/fqt066)). **Boundary:** a short piece can still be checked for local deviations such as punctuation, sentence openings, contractions, and cadence. It simply does not receive a confidence score.
+
+| Draft length | Permitted conclusion |
+|---|---|
+| Short drafts below roughly 500 words | Local checks only: sentence lengths, openings, punctuation, contractions, paragraph shape, phrase overlap. No global match score. Governance default. |
+| Roughly 500 to 2,000 words | Compare the common features with wide tolerances and label the result provisional. Governance default. |
+| Roughly 2,000 to 5,000 words | Compare the full feature set and report the sampling uncertainty alongside it. Governance default. |
+| Above 5,000 words | Full distributional comparison is defensible when the register matches and the reference corpus is itself adequate. **B**, with the genre limitation above ([Eder](https://doi.org/10.1093/llc/fqt066)). |
+
+The check runs against the correct register subprofile, never only the global corpus. A wrong-register comparison produces no score at all.
+
+Tolerances are **governance defaults**, engineering settings rather than published cutoffs: review any individual core feature deviating more than 1.5 standard deviations from the profile, target a median absolute deviation across core features at or below 0.75, and treat more than 20 percent of core features in review as a failed match. Each of those three numbers is a governance default.
+
+**Rule [B]: a feature match does not prove the writing sounds right to its author.** Stylometry is optimized for measurable differentiation, not subjective approval ([Grieve](https://doi.org/10.1093/llc/fqm020), [Grieve](https://doi.org/10.1515/cllt-2022-0040)). **Boundary:** repeated author feedback can itself become profile data over time, but it stays a separate validation layer and never becomes the stylometric score.
+
+Report three questions separately, because they are three different things and merging them is how a check becomes a claim it cannot support:
+
+```text
+Rhythm and syntax match: <within profile | drifted, with the largest deviations>
+Phrase-overlap check:    <clear | flagged, with the passages>
+Content provenance:      <every checkable claim traced to the brief or a source>
+Author approval:         <not established by this tool>
+```
+
+Only the person can answer the last one. The tool never asserts it.
+
+**Never treat a detector score as evidence of authorship.** Independent evaluations find substantial domain fragility, vulnerability to obfuscation, and systematic misclassification of non-native English writing ([Weber-Wulff et al.](https://arxiv.org/abs/2306.15666), [Liang et al.](https://www.sciencedirect.com/science/article/pii/S2666389923001307)). Grade A. **Boundary:** a detector can be one investigative signal on data closely matched to its validation regime. It is never the finding.
+
+## Refusals
+
+Building a profile begins with one question that is never skipped: is this the user's own writing, or writing they hold the right to model.
+
+**Refuse to build or apply a profile of a named third party where the purpose is publication under that person's name.** Style in the abstract is not owned, and modeling a public writer's technique to improve your own work is ordinary craft ([McMahon v. Prentice-Hall](https://law.justia.com/cases/federal/district-courts/FSupp/486/1296/1754213/), [Copyright Office Circular 33](https://www.copyright.gov/circs/circ33.pdf)). Producing text designed to pass as a specific real person's authored work is a different act, and the correct response is to decline it rather than negotiate the terms. **Boundary:** the refusal is about attribution, not analysis. Scholarship, criticism, attribution research, and high-level stylistic description of a public writer remain available, and so does learning from a writer you admire in work published under your own name.
+
+Four further refusals, each independent of the first:
+
+- **False endorsement.** Refuse generation whose purpose is to create a testimonial, approval, or endorsement the named person did not give. Rules on fake and misattributed testimonials and on confusion about affiliation apply in their own right ([FTC final rule](https://www.ftc.gov/news-events/news/press-releases/2024/08/federal-trade-commission-announces-final-rule-banning-fake-reviews-testimonials), [15 U.S.C. 1125](https://www.law.cornell.edu/uscode/text/15/1125)).
+- **Fabricated positions.** Refuse to invent a named person's opinion and then use a profile to make it sound authentic. A style profile is evidence about expression and never about belief.
+- **High-stakes attribution.** Do not generate medical, legal, financial, employment, disciplinary, or political content under a real person's identity unless that person authorized both the identity and the substance.
+- **Undisclosed ghostwriting.** Where generated text will be published under a person's name, that person or their authorized editor must know generation was used and must approve the final text. Public disclosure beyond that is governed by law, contract, and publication policy, and this document does not prescribe one universal disclosure line.
+
+Style transfer is not a defence for reproducing protected expression, and there is no word count that makes copying safe ([Copyright Office Circular 33](https://www.copyright.gov/circs/circ33.pdf), [Copyright Office on AI](https://www.copyright.gov/ai/)). Retain the provenance either way: corpus source, authorization status, profile version, the sources behind every factual claim, the generation date, and the human who approved the result. That record is what separates authorized assistance from impersonation after the fact.