@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/standards/migration-discipline/sqlalchemy.md

@@ -1,51 +0,0 @@
----
-tier: lite
-description: The SQLAlchemy sibling of .claude/rules/schema-management.md.
----
-
-# SQLAlchemy + Alembic — migration discipline
-
-The SQLAlchemy sibling of `.claude/rules/schema-management.md`. Loads when adopter's `tech_stack.orm` is `sqlalchemy`. For standalone Alembic (non-SQLAlchemy use), see `alembic.md`.
-
-## Non-negotiable rule
-
-**NEVER edit production schema directly via `Base.metadata.create_all()` or DB-side DDL.** SQLAlchemy's autogenerate is the migration source; bypassing it ships drift.
-
-## Workflow (Alembic via SQLAlchemy autogen)
-
-1. Edit the SQLAlchemy model in `models.py` (or wherever the adopter keeps declarative bases)
-2. Generate the migration: `alembic revision --autogenerate -m "descriptive_name"`
-3. **Review the generated migration before committing** — autogen misses many cases:
-   - Server-side defaults (`server_default=`) are detected only with explicit `compare_server_default=True` in env.py
-   - Enum changes need manual handling on Postgres
-   - Index renames are usually drop+create (data loss risk)
-   - Custom types (JSONB, ARRAY) need explicit handling
-4. Apply locally: `alembic upgrade head`
-5. Commit the migration file with the model change
-6. On deploy, CI runs `alembic upgrade head` against prod
-
-## After merging a branch with schema changes (MUST — not optional)
-
-1. `alembic upgrade head` — apply pending migrations locally
-2. Restart dev server — SQLAlchemy ORM models reload from source, but DB session connections may cache stale schema metadata
-3. If DB was reset: re-run seed / fixture scripts
-
-## Drift check
-
-```bash
-alembic current
-alembic history --indicate-current
-```
-
-If `alembic check` (Alembic 1.9+) reports model-vs-DB divergence, generate the missing migration.
-
-## Common pitfalls
-
-- **Autogen comparing on outdated metadata** — make sure `target_metadata = Base.metadata` in `env.py` reflects the latest import path
-- **Multiple heads** after parallel branches — resolve via `alembic merge` before further development
-- **`alembic stamp head`** is a footgun — only use it when you know the DB is already at that state; otherwise you skip migrations silently
-
-## Sources
-
-- Alembic docs (https://alembic.sqlalchemy.org/en/latest/)
-- SQLAlchemy migration discipline ports the operator's Prisma rule shape to the Python ecosystem.

package/substrate/standards/mobile-ephemeral-session.md

@@ -1,167 +0,0 @@
----
-tier: lite
-description: Autonomous sessions running in ephemeral environments — claude.ai/code mobile sandbox, CI runners executing agentic work, temporary dev containers — have different state-continuity constraints than desktop sessions.
----
-
-# Mobile / Ephemeral Session Standard
-
-Autonomous sessions running in ephemeral environments — claude.ai/code
-mobile sandbox, CI runners executing agentic work, temporary dev
-containers — have different state-continuity constraints than desktop
-sessions. This standard defines what must be true for ephemeral
-sessions to produce reviewable, recoverable work.
-
-## The core constraint
-
-Ephemeral sandbox state is destroyed when the session ends. Any
-artifact not committed AND pushed before exit is lost.
-
-This is different from desktop: desktop auto-save commits locally and
-pushes "when convenient." Ephemeral has no "later" — exit is terminal.
-
-## Detection
-
-**Primary (required for certainty)**: operator sets `CLAUDE_EPHEMERAL=1`
-as the first command in the session. No heuristics beat explicit
-opt-in.
-
-**Fallback heuristics** (if operator doesn't set the flag):
-- `pwd` doesn't start with `/Users/`
-- `hostname` doesn't match known machines
-- `$HOME` isn't the operator's real home
-- Tailscale CLI not installed at `/Applications/Tailscale.app/Contents/MacOS/Tailscale`
-- Fresh-clone reflog (very short history)
-
-≥2 heuristics firing → treat as ephemeral with surfaced warning.
-Single heuristic → surface but don't switch modes automatically.
-
-**Refine over time**: after the first few mobile sessions, update
-these heuristics based on actual claude.ai/code sandbox environment.
-
-## Rules (MUST)
-
-### 1. All session artifacts round-trip through git
-
-Chronicles, handoff docs, state files, diagnosis output, decomposition
-artifacts — everything MUST be committed AND pushed before the session
-naturally or unnaturally ends. Auto-save hooks in ephemeral mode must
-`git push` after every commit, not batch-push at exit.
-
-### 2. No filesystem-only markers
-
-Desktop hooks use `/tmp/claude-verify-[branch]` and similar markers.
-These are lost on sandbox death. Every filesystem marker MUST have a
-git-tracked equivalent that the hook also writes and reads. When
-running in ephemeral mode, the git-tracked form is authoritative.
-
-| Desktop | Ephemeral-compatible |
-|---------|---------------------|
-| `/tmp/claude-verify-[branch]` | `state/markers/verify/[branch]` (git-tracked, committed by /verify) |
-| Session lock at `.claude/SESSION_LOCK` | Same, but with ISO timestamp + TTL — stale locks auto-clear with ≥30min age |
-| Iteration state in `.claude/iteration-state` | Committed to repo, not gitignored |
-| Agent memory at `~/.claude/projects/...` | Either: (a) commit a memory export to `memory/` in repo, OR (b) accept per-session memory loss, rely on chronicles as context substitute |
-
-### 3. Auto-save pushes every commit
-
-Hook must:
-- Detect ephemeral mode (env var, hostname pattern, or explicit flag)
-- After each auto-save commit, invoke `git push origin HEAD` with
-  reasonable backoff on failure
-- Coalesce commits within the last 10 min to avoid thrashing git
-  history
-- If push fails (network, auth, conflict): retry once, then log
-  failure visibly — operator sees it in session output
-
-### 4. Session-lock TTL + ephemeral-safe
-
-Session locks must be:
-- Timestamp-bearing (ISO 8601 in UTC)
-- Stale-clearable (locks ≥30 min old are cleared with an announcement)
-- Git-committed if ephemeral (lives in the repo so other sessions
-  can see it)
-
-Stale-lock clearing rule: agent reads lock file, checks timestamp, if
-age > TTL, clears lock and announces in session output. No polling;
-one-shot check at session start.
-
-### 5. No credential-bearing tools in ephemeral
-
-Ephemeral sessions MUST NOT carry long-lived credentials:
-- No SSH keys for prod/staging boxes
-- No AWS access keys
-- No Tailscale auth tokens
-- No long-lived PATs (use fine-grained PATs with short TTL or
-  GitHub App installation tokens only)
-
-Agents in ephemeral sessions work at the git layer — clone, branch,
-commit, push, open PR. Deploy work happens in CI after PR merge,
-never from the ephemeral sandbox directly.
-
-### 6. Session-end rigor is absolute
-
-Ephemeral sessions MUST invoke `/session-end` explicitly before exit.
-Stop hook may not fire; operator may close the tab; sandbox may time
-out. Relying on shutdown hooks is the failure mode. Explicit
-session-end at natural stopping points is the rule.
-
-Session-end in ephemeral mode:
-1. Write chronicle (commit + push)
-2. Update whereami if changed (commit + push)
-3. Write any LinkedIn drafts (commit + push)
-4. Confirm working tree clean
-5. Confirm HEAD matches origin
-6. Exit only after verification
-
-## Rules (SHOULD)
-
-### 7. Recent-chronicle read at session start
-
-If project memory isn't available (no MCP memory server, no memory
-repo), read the last 2-3 chronicles at session start as context
-substitute. Substantial enough to recover current iteration state,
-open threads, and recent decisions.
-
-### 8. Conservative auto-mode in ephemeral
-
-Ephemeral sessions default to operator-gated even if orchestrator-
-gated was requested. The ephemeral constraint adds risk that deserves
-confirmation at decision points. Override with explicit
-`orchestrator-gated --ephemeral-ok` flag.
-
-### 9. Recipe for "hello world" mobile session
-
-First mobile session on any repo should be trivial: chronicle edit,
-doc fix, skill tweak, README update. Not a feature build. Validates
-the end-to-end loop (auth → clone → edit → commit → push → PR)
-before testing anything complex.
-
-## Rationale
-
-Mobile autonomous is valuable because it compresses the feedback
-loop for idea-to-artifact work (operator has an insight on phone;
-captures it via agent; agent produces artifact; operator reviews on
-desktop). The tax is state continuity — easy to lose work to
-sandbox death.
-
-The rules here make state continuity a build-time property of the
-substrate, not a run-time discipline the operator has to remember.
-Every hook, every skill, every rule that already exists keeps working
-as long as it respects these constraints.
-
-## Relationship to other standards
-
-- `standards/substrate-config-schema.md` — no secrets in
-  substrate.config.md (already required); ephemeral just makes
-  this more critical
-- `standards/deployment-topology.md` — deploy work happens in CI
-  post-PR, never from ephemeral session
-- `.claude/rules/blocked-items.md` — BLOCKED: protocol continues to
-  work in ephemeral; silence is not deferral in either mode
-
-## Enforcement
-
-Hook layer enforces what it can (auto-save push, marker git-tracking,
-session lock TTL). Agent behavior enforces the rest (explicit
-session-end, no credential tools, conservative auto-mode).
-Self-test skill could validate hook configuration when run in
-ephemeral mode.

package/substrate/standards/model-routing-discipline.md

@@ -1,160 +0,0 @@
----
-tier: lite
-description: - ADR-021 — anchor catalog selection (cameo engine model context, now operator-internal) - bassclef#853 Sub-bet 16 + Sub-bet 19 — model routing substrate primitive - bassclef#944 — Voyage matcher excision (operator-internal pinning moved to…
----
-
-# Model routing discipline
-
-## Sources read
-
-- ADR-021 — anchor catalog selection (cameo engine model context, now operator-internal)
-- bassclef#853 Sub-bet 16 + Sub-bet 19 — model routing substrate primitive
-- bassclef#944 — Voyage matcher excision (operator-internal pinning moved to bassclef-upstream)
-- `.claude/agents/*.md` existing tier declarations (Opus / Sonnet / Haiku across 13 agents)
-- Operator spec: provider-agnostic routing supporting 10+ providers
-
-## What this is
-
-Model routing is how bassclef's agents, skills, and subagents pick which LLM to call at dispatch time. The substrate names four capability tiers — `cheap-fast`, `balanced`, `capable`, `embedding`. Each provider maps its concrete models to those tiers in `config/model-routing.yaml`.
-
-Agents declare a tier in frontmatter. Skills can override per invocation. The substrate resolves the concrete model at dispatch time from the active provider + tier mapping.
-
-## Why this exists
-
-Three problems the old shape didn't solve:
-
-1. Agent frontmatter pinned vendor-specific model IDs (`claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`). Switching providers meant editing every agent file.
-2. Adopters using OpenAI, Gemini, Bedrock, etc. couldn't reuse bassclef's agent definitions without rewriting model declarations.
-3. Per-skill or per-call model selection had no clean override path. Operator env vars worked but weren't documented.
-
-This primitive fixes all three: agents declare a tier, not a vendor. Adopters edit `config/model-routing.yaml` to pick their provider. Per-invocation overrides cascade through a clear precedence stack.
-
-## The four capability tiers
-
-| Tier | When to use |
-|---|---|
-| **cheap-fast** | High-frequency, low-complexity, structured output. Checklist eval, file navigation, simple extraction, automation, runbook execution. |
-| **balanced** | Default for most agents. Code edits, planning, analysis, design, strategic reasoning. |
-| **capable** | High-complexity reasoning, architectural decisions, problem framing, synthesis across many docs. |
-| **embedding** | Vector embeddings for retrieval (semantic search, anchor matching). Not a chat model. |
-
-Tiers describe capability, not vendor. The same tier maps to different concrete models per provider.
-
-### Tiers are vocabulary, not benchmark
-
-The four tier names describe **intent**, not measured cross-provider equivalence. A `capable` model on one provider is not strictly equal to a `capable` model on another — output quality, latency, cost, and context window all vary. The tier abstraction picks the right shape of model for a workload; adopters validate the concrete mapping against their own workloads before pinning a provider.
-
-INSTEAD of treating tiers as benchmark guarantees: read them as design intent. "Use capable" means "this work needs the strongest reasoning the provider ships." Whether that's Claude Opus, GPT-o1, Gemini 2.0 Pro, or Mistral Large 2 depends on the provider's roadmap — and on what the adopter measures against their own jobs.
-
-This framing prevents the cross-provider semantic-equivalence misread: tiers are a coordination mechanism, not a quality contract.
-
-## How to declare
-
-### In an agent definition
-
-```yaml
----
-name: Closer
-model_tier: cheap-fast
-description: Administrative gate evaluation; checklists; retros.
----
-```
-
-### In a skill (optional per-call override)
-
-```yaml
----
-name: example-skill
-model_tier: capable  # overrides invoking agent's tier
----
-```
-
-### In substrate.config.md (per-repo provider default)
-
-```markdown
-## Model routing
-
-# Default provider for this repo. Tier-to-model mapping comes from
-# bassclef's config/model-routing.yaml unless overridden here.
-model_provider: anthropic
-```
-
-## Override precedence
-
-When resolving a model at dispatch, the substrate walks this stack from highest to lowest priority:
-
-| Priority | Source | Notes |
-|---|---|---|
-| 1 | `CLAUDE_MODEL_OVERRIDE` env var | Direct vendor model ID; bypasses tier resolution |
-| 2 | Per-invocation flag (skill arg) | `--model gpt-4o` style override |
-| 3 | Skill-level `model_tier:` declaration | Skill frontmatter |
-| 4 | Agent-level `model_tier:` declaration | Agent frontmatter |
-| 5 | Per-repo `model_provider:` in substrate.config.md | Repo default; pairs with tier above |
-| 6 | Substrate default in `config/model-routing.yaml` | `default_provider:` field |
-
-INSTEAD of hardcoding vendor model IDs in agent definitions: declare a tier; let the resolution stack pick the concrete model. The override path stays open at every layer for genuine reasons (vendor pinning, per-call experimentation, operator emergency override).
-
-## How adopters extend
-
-Adopters use any LLM provider — Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure OpenAI, Mistral, Cohere, DeepSeek, xAI, local LLaMA, or any future provider.
-
-To add a new provider:
-
-1. Edit `config/model-routing.yaml`. Add a provider block under `providers:` with tier mappings.
-2. Set `default_provider:` to the new provider (or leave the default and set per-repo).
-3. The agents work unchanged.
-
-No agent edits. No skill edits. The tier abstraction does the work.
-
-## What the substrate ships
-
-`config/model-routing.yaml` ships defaults for ten providers:
-
-- **Anthropic** — Claude family (Opus 4.7, Sonnet 4.6, Haiku 4.5)
-- **OpenAI** — GPT family
-- **Google Gemini** — Gemini family
-- **AWS Bedrock** — Bedrock-hosted Anthropic models
-- **Azure OpenAI** — Azure-hosted GPT
-- **Mistral** — Mistral family
-- **Cohere** — Command family + embed models
-- **DeepSeek** — DeepSeek-V3 / DeepSeek-Coder
-- **xAI** — Grok family
-- **local-llama** — Self-hosted Llama 3
-
-The defaults are starting points. Operator can pin specific versions, swap models within a tier, or add new providers via config edit.
-
-## How adopter-internal primitives reference this
-
-Operator-internal pinning decisions (anchor catalog model choices, embedding-vendor selection) stay in `bassclef-upstream/docs/operator-private/adrs/` per Tier 1 substrate. The pins reference this routing primitive: operator-internal substrate calls `state_routing_resolve(tier='embedding', purpose='<purpose>')` which reads the operator-internal config to pick the concrete embedding model.
-
-Adopters don't need the operator-internal pinning decisions. The substrate primitive gives them the tier abstraction; their config picks the concrete model.
-
-## What this primitive does NOT do
-
-- Does not choose a tier for you. Agent definitions declare the tier.
-- Does not call the LLM. The harness does that with the resolved model ID.
-- Does not handle rate limits, retries, or fallbacks. Those are runtime concerns (separate primitive — see bassclef#853 Sub-bet 20 parallel-dispatch ceiling).
-- Does not move secrets. Provider API keys live in `substrate.secrets.md` per `standards/secrets-lifecycle.md`. This primitive only routes between providers; the secrets layer authenticates each call.
-
-## Composes with
-
-- ADR-021 — anchor catalog selection (operator-internal; references this primitive)
-- ADR-023 — dependency-aware pre-flight dispatch (Sub-bet 13)
-- ADR-025 — atomic write-claim (Sub-bet 9)
-- bassclef#853 Sub-bet 17 — subagent isolation (different concern; both fire pre-dispatch)
-- bassclef#853 Sub-bet 18 — session marker handoff (different concern; both fire pre-dispatch)
-- bassclef#853 Sub-bet 20 — parallel-dispatch ceiling (caps concurrent agents per plan capacity)
-- `standards/vendor-bindings.md` — this primitive is the SENTINEL_bassclef_answer to "how do we stay portable across LLM vendors"
-- `standards/secrets-lifecycle.md` — provider API keys live there
-
-## Override path
-
-`SKIP_MODEL_ROUTING=1 <command>` — bypasses tier resolution entirely. Logged via trace-helper. Use only when debugging a routing bug or when a one-off vendor model is needed for a specific call that isn't worth a permanent config entry.
-
-## Retirement condition
-
-This primitive retires only if the harness ships a built-in tier abstraction that supersedes it. Until then, this discipline holds across all bassclef-substrate agents + skills + subagents.
-
-## Closes
-
-bassclef#853 Sub-bet 16 (model routing substrate primitive) + Sub-bet 19 (provider-agnostic extension across 10+ providers).

package/substrate/standards/ogilvy-writing-rules.md

@@ -1,225 +0,0 @@
----
-tier: lite
-title: Ogilvy writing rules — reference for the writing-craft discipline
-sources:
-  - David Ogilvy — "How to Write" internal memo (1982; 10 rules to Ogilvy and Mather management)
-  - Kenneth Roman + Joel Raphaelson — Writing That Works (Harper and Row, 1981)
-authoring_luminaries:
-  primary: [david-ogilvy]
-  supporting: [stephen-toulmin, rich-hickey, kent-beck]
-description: "This standard holds the 10 rules bassclef's writing-craft discipline references."
----
-
-# Ogilvy writing rules — bassclef reference
-
-This standard holds the 10 rules bassclef's writing-craft discipline references. Each rule names the test, the violation pattern, the fix. Grounded in David Ogilvy's 1982 "How to Write" memo and Kenneth Roman and Joel Raphaelson's *Writing That Works* (1981). No wording lifted from any other source — bassclef's own restatement of the public rules.
-
-Cited by:
-
-- `.claude/rules/writing-craft-discipline.md` — auto-loaded rule; first-person composition checks
-- `.claude/skills/ogilvy-writing-audit/SKILL.md` — audit skill; severity-tagged violations
-- `.claude/hooks/plain-english-steering.sh` (extension per ticket #935) — steering hook reads rule names from here
-
-## Sources read
-
-- David Ogilvy 1982 "How to Write" memo — public circulation
-- Kenneth Roman + Joel Raphaelson 1981 *Writing That Works* — published book
-- `.claude/luminaries/david-ogilvy.md` — full luminary shipping alongside this standard
-
-## The 10 rules
-
-### Rule 1 — Natural voice
-
-Read the sentence aloud. Would a real person say it that way to a respected peer?
-
-**Fails.**
-- "Pursuant to our earlier discussion..."
-- "It has come to my attention that..."
-- "Please be advised that..."
-- Passive voice where active would fit: "A decision was made" → "We decided"
-
-**Fixes.**
-- "As we discussed..."
-- "I noticed..."
-- Just state the point without the preamble.
-
-Natural does NOT mean casual. Lawyers and engineers have natural voices that sound like lawyers and engineers. Natural means the writer sounds like themselves, speaking to a peer.
-
-### Rule 2 — Short units
-
-Words, sentences, paragraphs — keep them short.
-
-**Word swaps (Ogilvy's list, extended).**
-- utilize → use
-- commence → start
-- endeavor → try
-- facilitate → help
-- terminate → end
-- implement → do
-- demonstrate → show
-- approximately → about
-- subsequent → next
-- in order to → to
-
-**Sentence rule.** If a sentence runs past 25 words, it hides two or three sentences. Split at the natural clause boundary.
-
-**Paragraph rule.** If a paragraph runs past 6 sentences (about 100 words), it covers more than one idea. Split.
-
-### Rule 3 — No jargon
-
-If a normal word would carry the same meaning, use the normal word. Ogilvy's list — "reconceptualize," "demassification," "attitudinally," "judgmentally" — extends into modern consulting speak.
-
-**Common offenders in agent output.**
-- leverage (as verb), synergies, verticals, circle back, deep dive
-- ideate, iterate (vague), pivot (metaphorical)
-- value-add, move the needle, boil the ocean
-- robust, scalable, holistic (outside biology)
-- stakeholder (often no referent)
-- operationalize, incentivize, strategize
-
-**When jargon is fine.** Technical writing where the term has a precise meaning the audience shares. "API rate limit" in dev docs stays.
-
-**When jargon is not fine.** Anywhere the writer is trying to sound important instead of be precise.
-
-### Rule 4 — Verify quotations
-
-Flag quotations for verification. Attributed quotes ("As Einstein said...") are misattributed 90 percent of the time.
-
-Bassclef does not usually quote outside sources. When we do — in journal entries, luminary bodies, R&R citations — verify the source.
-
-### Rule 5 — Read-aloud test
-
-Read the passage in your head. If it stumbles, rewrite.
-
-**Fails.**
-- Tongue-twisters: "The situation's specification specifies..."
-- Long lines with no comma rest — a 35-word sentence is physically hard to speak
-- Unintentional rhymes: "The initiation of the presentation caused frustration..."
-- Repeated words within one sentence: "review the review of the review process"
-
-**Fix.** Split, rearrange, cut. The passage should flow at reading speed.
-
-### Rule 6 — Clear ask
-
-If the message requests action, is the ask crystal clear? Can the reader state, in one sentence, what they should do next?
-
-**Fails.**
-- Information dump with no ask at the end
-- Buried ask: "...and if you could send over the Q3 numbers as well..."
-- Vague ask: "Let me know your thoughts."
-- Passive ask: "It would be great if someone could..."
-
-**Fix.** State the ask directly at the top or bottom. Name the decision, the format, the deadline.
-
-When no ask is needed — pure information — say so: "No action needed — sharing for awareness."
-
-### Rule 7 — Comprehension (Roman + Raphaelson)
-
-"People seldom act on what they cannot understand."
-
-Could the intended reader — not an insider, but the actual recipient — understand what is being said on first read?
-
-**Fails.**
-- Unexplained acronyms (especially internal ones — "the PM flagged KR slippage")
-- Assumed context: "as discussed in the offsite"
-- Compressed logic that skips steps
-- Pronouns without clear antecedents: "They said this would happen"
-
-**Fix.** Write for the reader who was not in the last meeting. Expand acronyms first mention. Name the people. Show the steps.
-
-Different from Rule 3 (jargon). Jargon is bad words. Comprehension is the bigger question: after reading the whole thing, does the reader actually know what is going on?
-
-### Rule 8 — Completeness (Roman + Raphaelson)
-
-"When you say something, make sure you have said it. The chances of your having said it are only fair."
-
-Did the writer actually state the thing they meant to state, or did they dance around it?
-
-**Fails.**
-- Questions implied but not asked
-- Requests implied but not made
-- Conclusions implied but not stated
-- Main point arrives halfway through
-
-**Diagnostic.** What is the ONE thing the reader needs to take from this? Is that thing actually written down, in plain language, somewhere the reader will see it?
-
-Overlaps with Rule 6 (clear ask) but broader. Rule 6 covers action. Rule 8 covers whether the message itself is fully delivered.
-
-### Rule 9 — Honesty / no hedging (Roman + Raphaelson)
-
-"Intelligent readers develop a nose for deceptive writing and are seldom taken in by it."
-"Bad news is not made better by being baffling as well as unwelcome."
-
-Is the writer saying what they mean, or hiding behind softening language?
-
-**Fails (euphemisms).**
-- "right-sizing" → layoffs
-- "we're going in a different direction" → we're rejecting your proposal
-- "challenging" → bad, failing
-- "opportunity for improvement" → problem
-- "reached out" → contacted, called, emailed
-
-**Fails (weasel words).**
-- "arguably," "somewhat," "perhaps," "it could be argued"
-- "we believe" as a shield for controversial claims
-- Hedging adverbs stacked: "potentially," "possibly," "likely"
-- Passive voice hiding the actor: "mistakes were made"
-
-**Fix.** Say the thing straight. Bad news arrives first, then the reason, then the next step.
-
-**When hedging IS fine.** Genuine uncertainty honestly acknowledged: "I'm not sure — it might be A or B" is fine. Calibrated confidence: "likely" used when the probability is around 70 percent is fine.
-
-### Rule 10 — Facts with context (Roman + Raphaelson)
-
-"Never present facts on their own, like unstrung gems."
-
-For each fact, number, or data point: does the reader know why it matters? Is it connected to a point?
-
-**Fails.**
-- "Revenue was 4.2M." (What matters? Up? Down? Compared to what?)
-- Bullet lists of numbers with no interpretation
-- "The data shows..." followed by data but no "therefore..."
-- Percentages without denominators: "engagement up 40 percent" (from what? over what period?)
-
-**Fix.** For every fact, ask "so what?" Answer inline.
-
-**Diagnostic.** R&R's metaphor: facts are building materials. Readers are not impressed by a pile of bricks. They want to see the building.
-
-## Severity guidance
-
-When flagging a violation, tag severity:
-
-- **🔴 Critical** — The violation actively undermines the message. The reader will be confused, misled, or fail to act. Must fix.
-- **🟡 Moderate** — The violation weakens the writing. A sharp reader will notice. Should fix.
-- **🟢 Minor** — A small stumble. The message works without fixing it. Optional polish.
-
-**Calibration examples.**
-
-- Jargon in a customer-facing headline = Critical. Jargon in paragraph 4 of a memo = Moderate.
-- Missing ask in an action-requesting email = Critical. Unclear ask in an FYI update = Moderate.
-- A 30-word sentence in dense technical copy = Moderate. A 30-word sentence in a memo intro = Critical.
-- A stray euphemism in a friendly update = Minor. A euphemism burying bad news = Critical.
-
-**When in doubt, ask.** Would the intended reader still take the intended action after reading this? If no, it's Critical.
-
-## What the rules do NOT cover
-
-Ogilvy's memo names four more behavioral rules that prose alone cannot audit:
-
-1. Have you read *Writing That Works* three times? (Ogilvy's Rule 1)
-2. Did you check your quotations? (Rule 6 in text form is above; the behavioral check is separate)
-3. Did you sleep on it? "Never send a letter or memo on the day you write it. Read it aloud the next morning, then edit." (Rule 7)
-4. If it is important, did you get a colleague to improve it? (Rule 8)
-5. If you want action, is writing actually the right medium? Ogilvy's Rule 10: "Don't write — go tell the person what you want."
-
-The audit surface — `/ogilvy-writing-audit` skill — flags these as reminders at the end of every audit, without trying to check them from text.
-
-## Rules bassclef adds on top
-
-- **`/kiss words` composes with this standard.** After `/ogilvy-writing-audit` flags the violations, `/kiss words` mechanical substitution fixes what a wordlist covers. The audit diagnoses; the fix skill applies.
-- **`standards/bassclef-internal-jargon.md` extends the Rule 3 list.** Bassclef adds business jargon Ogilvy's 1982 memo did not cover (leverage as verb, synergies, circle back, deep dive, ideate, value-add, robust, scalable, holistic, stakeholder without referent).
-- **`.claude/rules/plain-english-discipline.md` sits alongside.** Grade-level target (grade 8-9 today; grade 8 after ticket #935 lands). This standard covers writing craft; that rule covers vocabulary and grade.
-
-## Retirement condition
-
-This standard retires only if bassclef stops shipping operator-facing prose. The specific rules may evolve (the wordlist grows; severity calibration adjusts) but the discipline of prose-as-craft persists.