diff --git a/docs/handoff/ADR-0085-content-style-pass-brief.md b/docs/handoff/ADR-0085-content-style-pass-brief.md new file mode 100644 index 00000000..a045c8e9 --- /dev/null +++ b/docs/handoff/ADR-0085-content-style-pass-brief.md @@ -0,0 +1,236 @@ +# ADR-0085 Content Style Pass — Brief + +**Audience:** A fresh dev agent (cheaper/faster tier). You have NO prior context — read this file plus `docs/decisions/ADR-0085-gloss-aware-cause.md` and act from there. + +**Mission:** Apply a fluency pass to the ratified gloss entries so the surfaces produced by the composer read as natural English. You are only editing JSONL gloss content. You are NOT implementing composer changes, NOT touching algebra, NOT changing pack schemas. + +**Estimated effort:** small — about 30–60 lines of JSONL edits across 13 packs. The closure rule already holds (`scripts/verify_definitional_closure.py` exits 0 today); your edits must keep it holding. + +--- + +## Why this exists + +ADR-0084 ratified per-lemma `gloss` text. ADR-0085 made the composer use those glosses for CAUSE intent. Today the runtime emits: + +``` +Light exists as visible medium that reveal truth. pack-grounded (...). +``` + +The shape is right, but `"reveal"` should be `"reveals"` (3sg present after `"medium that"`). Same lemma in DEFINITION shape: + +``` +Light is visible medium that reveal truth. pack-grounded (...). +``` + +Same fix needed. The gloss content is the locus — fixing the gloss text fixes both intents at once. + +The agent who wrote the initial glosses used bare lemma forms (uninflected dictionary forms) because the closure rule wants `definitional_atoms` to list LEMMAS. They conflated *atoms must be lemma form* with *gloss should use lemma form*. Those are different fields for different purposes — let them diverge correctly. + +--- + +## What you ARE changing + +For each gloss entry in `language_packs/data//glosses.jsonl` where the gloss reads ungrammatically when slotted into the composer's POS frame: + +| POS | Composer frame | Example before | Example after | +|---|---|---|---| +| NOUN | `{Lemma} is {gloss}.` | `Light is visible medium that reveal truth.` | `Light is a visible medium that reveals truth.` | +| VERB | `To {lemma} means {gloss}.` | `To recall means get memory from before.` | `To recall means to get memory from before.` | +| ADJ | `Something is {lemma} when it {gloss}.` | `Something is bad when it different from good.` | `Something is bad when it is different from good.` | + +The CAUSE frame (ADR-0085) uses the same gloss, so a single fix lifts both shapes: + +``` +CAUSE "Light exists as a visible medium that reveals truth." +DEFN "Light is a visible medium that reveals truth." +``` + +## What you are NOT changing + +| Field | Rule | +|---|---| +| `definitional_atoms` | NEVER change. Stays in lemma form. (`"reveal"` stays in atoms even when gloss becomes `"reveals"`.) | +| `predicates_invited` | NEVER change. | +| `pos` | NEVER change. | +| `lemma` | NEVER change. | +| `definition_version` | NEVER bump. Style edits aren't version-worthy. | +| `provenance_ids` | Append `"adr-0085-style:reviewed:2026-05-21"` to indicate the pass. | + +Any code, any pack schema, any composer, any algebra: **do not touch**. + +--- + +## Phase 1 — Inventory the issues + +Run this from the repo root to get an honest list: + +```bash +PYTHONPATH=. python3 - <<'EOF' +import json, re +from pathlib import Path +ROOT = Path('language_packs/data') + +# Patterns flagging fluency issues likely visible in the composer surface. +# These are heuristics — manually verify each hit. +SUSPECT_BARE_VERBS = { + 'support','reveal','know','show','cause','give','make','mean','follow', + 'happen','become','belong','depend','imply','verify','check','find', + 'explain','lack','do','see','feel','hold','work','serve','help','tell', + 'come','go','use','get','put','keep','have','leave','matter','live','die', +} +patterns = [ + ('3sg-agreement-after-relative', + re.compile(r'\b(what|who|that|which) (' + '|'.join(SUSPECT_BARE_VERBS) + r')\b')), + ('plural-after-quantifier', + re.compile(r'\b(two|three|many|several|some|few|all)\s+([a-z]+ing\b|[a-z]+(? /tmp/eval_post.json +diff /tmp/eval_post.json baseline.json +# Expected: empty diff +# (capture baseline.json with `core eval cognition > baseline.json` BEFORE +# starting any edits) + +# Smoke + packs lanes. +PYTHONPATH=. python3 -m core.cli test --suite smoke -q +PYTHONPATH=. python3 -m core.cli test --suite packs -q +# Expected: all green +``` + +If `core eval cognition` drifts byte-from-byte, **STOP**. That means a metric moved unexpectedly. Either: +- (a) Your fix changed term-capture by inflecting a word the cognition eval expects in lemma form. Roll the edit back. +- (b) You accidentally changed a `pos` or `definition_version`. Roll that back. + +The cognition eval staying byte-identical is the load-bearing invariant of this entire pass. + +--- + +## Deliverables + +1. The edited `glosses.jsonl` and updated `manifest.json` files on branch `feat/adr-0085-content-style-pass`. +2. A draft PR titled `feat(packs): ADR-0085 content style pass (fluency in glosses)`. Mark **Draft** — a human reviews before merge. +3. A report in the PR body with this shape: + +``` +## Style pass summary + +- packs touched: +- entries edited: +- total atoms: +- closure verifier: exit 0 +- cognition eval: byte-identical to baseline +- packs lane: pass + +## Sample edits (10 representative) + +| pack | lemma | before | after | +|---|---|---|---| +| en_core_cognition_v1 | light | `"visible medium that reveal truth"` | `"a visible medium that reveals truth"` | +| en_core_cognition_v1 | evidence | `"what support truth"` | `"what supports truth"` | +| ... + +## Open questions + +(anything unclear or that needed judgment — list here) +``` + +--- + +## Hard rules + +| Rule | Consequence if broken | +|---|---| +| Do NOT touch any code (`*.py`, `chat/`, `core/`, `algebra/`, `generate/`) | PR rejected | +| Do NOT touch Greek/Hebrew packs (`grc_*`, `he_*`) — they're not in the definitional layer | PR rejected | +| Do NOT touch the primitives pack (`packs/primitives/`) | PR rejected | +| Do NOT change `definitional_atoms`, `predicates_invited`, `pos`, `lemma`, `definition_version` | PR rejected | +| Do NOT bypass closure verification | PR rejected | +| Cognition eval must stay byte-identical | PR rejected, edits rolled back | +| Closure verifier must exit 0 | PR rejected, edits rolled back | + +If anything is unclear, **surface the question rather than guessing.**