hoodscript 1.3.1__tar.gz → 1.4.0__tar.gz

hoodscript-1.4.0/.claude/skills/align-prompt/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: align-prompt
+description: Align a pasted generation prompt (from Gemini or anywhere) with the current HoodScript release before implementing it. Use whenever the user pastes a prompt that names files, keywords, or features to build.
+---
+
+# align-prompt
+
+The user pastes a generation prompt. Do not execute it as written. Do this:
+
+1. Save the pasted prompt verbatim to `$SCRATCHPAD/prompt-in.md`.
+2. Run the mechanical half:
+   ```
+   python scripts/align_prompt.py $SCRATCHPAD/prompt-in.md -o $SCRATCHPAD/prompt-aligned.md --report $SCRATCHPAD/prompt-report.md
+   ```
+   It rewrites the v1.0.0 lexicon to v1.1, swaps stale phrasing/paths/commands,
+   prefixes lines that ask for declined/dropped work with `[DECLINED …]` /
+   `[DROPPED …]` / `[NEVER …]`, and prepends the PROMPTS.md §0 brief.
+3. Do the judgment half — diff the aligned scope against the tree:
+   - `git ls-files src tests examples docs`, CHANGELOG `[Unreleased]` and the
+     latest release section, `CLAUDE.md` "Current status".
+   - For each item in the aligned prompt, classify: **shipped** (on `main`,
+     cite the path), **declined/dropped** (cite ADR or CHANGELOG), **gap**
+     (not on disk — the only thing to implement), or **conflict** (asks for
+     something the standing brief forbids — say so, don't build it).
+4. Show the user a short table (item → status → evidence) and the report's
+   flagged lines. Then implement only the **gap** rows, one sprint, under the
+   gate (`ruff check && pytest`), on the current branch rules (agents.md).
+5. If the aligned prompt is worth keeping, record the reconciliation as a
+   PROMPTS.md §3.x section like §3.5 — mapping table + the short correct prompt.
+
+Never: reintroduce `cook`/`serve`/`Facts`/`holler`/`libcst`; add a keyword;
+build a dialect overlay (ADR-0004); create a tag.

{hoodscript-1.3.1 → hoodscript-1.4.0}/CHANGELOG.md

@@ -5,6 +5,106 @@ Versioning: the keyword set is the public API; changing it is at least a minor b
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-09-12
+
+New library module, new CLI command, three new lint rules, and the prompt
+aligner. Keyword set unchanged (v1.1).
+
+### Added
+
+- **Sourcing audit sprint** (PROMPTS.md §2.9, worked record §3.7). Every
+  keyword, pattern form, and the `*Trip` suffix re-run through
+  `lexical-sourcing.md` §5 with the sources open rather than remembered:
+  the nine Yale GDP pages fetched and quoted; Green's Dictionary of Slang
+  read entry by entry (variety labels and first-quotation years now in the
+  table); CORAAL grepped for the first time — 231 interviews, 1.39 M tokens,
+  via a mirror because the Oregon host refused connections; the Urban
+  Dictionary liability screen run on all Tier B words. Results and
+  corrections: `hoodscript/docs/linguistics.md` "Sourcing audit —
+  2026-09-12". Decisions for the owner: GRAMMAR.md "Sourcing audit
+  2026-09-12 — DRAFT" (`cap`/`no cap` liability + 2018 dating; `trip` now
+  two-source; `dip` meets the corpus clause; `tryna` re-ranked; Rickford →
+  Labov on the `ain't` row). No keyword changed.
+- **`hoodscript migrate <file.hs>`** — rewrites v1.0.0 code to the v1.1
+  lexicon from the CHANGELOG migration table: two line-preserving token
+  passes (v1.0.0 map → Python → `py2hood`), so `cook`→`bet`, `serve`→`dip`,
+  `holler(x)`→`holla x`, `Facts`→`no cap`, `GhostFileTrip`→`MissingFileTrip`,
+  the 21 builtin aliases → their Python names. Auto-detects v1.0.0 by its
+  exclusive tokens (`dip` meant `break` there — a v1.1 file is left alone
+  with a note; `--from 1.0` forces). `-w` writes with a `.bak`; `--diff`.
+  Refuses to write if the line count changed. `align_prompt.py` fixed
+  prompts; this fixes code.
+- **`hoodscript sourcing <word>`** — Rule Zero as one command
+  (`src/hoodscript/sourcing.py`): standing (keyword / cut / candidate, with
+  the `linguistics.md` rows when run from a checkout), Green's Dictionary of
+  Slang senses with variety labels and first-quotation years, the Urban
+  Dictionary liability screen by rank, CORAAL hits + KWIC with `--coraal`,
+  and the checklist of steps no script can do. `--offline`, `--json`. The
+  cut list now lives in `sourcing.CUT` (one source for the command and
+  `tests/test_rule_zero.py`); `scripts/coraal_hits.py` imports the corpus
+  code from here.
+- `scripts/coraal_hits.py` — step 3 of the sourcing procedure as a tool:
+  counts every keyword in official CORAAL text files or a JSONL mirror,
+  `--kwic` prints the lines so senses can be read, not guessed.
+- `tests/test_rule_zero.py` — the release package's constitutional test
+  (the prototype's `test_one_to_one_law.py` read the prototype's table and
+  never guarded `constants.py`): cut words stay cut (the full v1.0 + v1.1 +
+  alias cut list), tiers are disjoint, Tier B ≤ 9, every Tier A/B keyword
+  has a row in `linguistics.md`, Urban Dictionary never appears in a
+  citation row, the docs mention every keyword, and the screen matches red
+  flags on word boundaries.
+
+### Fixed
+
+- `hoodscript/scripts/screen_keyword.py` flagged `something` for `meth` and
+  `essex` for `sex` (substring matching); now word-boundary regexes. The UD
+  API has returned no vote counts since 2024, so the script reports UD's
+  own rank instead of a meaningless `score +0`.
+- `hoodscript/docs/lexical-sourcing.md` §5 step 7 sent contributors to the
+  frozen prototype's `KEYWORD_TO_AST`; now `src/hoodscript/constants.py` +
+  `tests/test_conformance.py` + `docs/keywords.md`. Green's Dictionary of
+  Slang added to the Tier 3 table as the first dictionary to check.
+- `docs/adr/0002` listed `tryna` and `chill` as Tier C (they are A and B);
+  CLAUDE.md/agents.md said 16 exception names (17); GRAMMAR.md's `*Trip`
+  list lacked `BadImportTrip`.
+
+- **Creative-DX sprint** (from a pasted "Horizon & Creative DX" prompt, aligned
+  via `scripts/align_prompt.py`; reconciliation in PROMPTS.md §3.6). Built:
+  - **`hoodlib.chart`** — Braille/block sparklines, bar charts, histograms,
+    `show_bag()` for game inventories. Standard library only; every function
+    returns a string; empty/non-numeric input is a plain `BadValueTrip` /
+    `WrongKindTrip`. Documented with runnable examples in `docs/hoodlib.md`
+    (now part of the docs-are-tests set, together with `hoodlib.disk`).
+  - **`hoodscript replay <file.hs>`** — run a program under `sys.settrace`,
+    then step through it backwards: `f`/`b`, `j N`, `l N` (first step at a
+    line), `v` (locals), `w` (caller chain). Snapshots are deep copies;
+    uncopyable values are stored as `repr`; `--max-steps` caps memory;
+    `--dump` prints the trace for pipes. A crash is reported by the JPE
+    engine and the prompt opens *at* the crash so `b` steps back from it.
+    The 1:1 line law is what makes this cheap: trace lines are `.hs` lines.
+  - **Lint HL004–HL006** — exact `ast` rules, no tool needed: a secret-looking
+    name assigned a real-looking string literal (placeholders and
+    `os.environ` reads are ignored); nesting deeper than four blocks inside
+    a function (one finding per chain); a function that is one big `if`
+    (guard-clause opportunity). Plain-English what/why/fix like HL001–HL003.
+  Declined from the same prompt, with reasons: a `pass_to` pipe operator
+  (a new keyword without a citation, and `g(f(x))` rewriting is not one
+  construct per construct — Rule Zero and the 1:1 law), voice-to-code
+  (`hoodscript mic`: a speech stack the zero-dep core forbids, and a spoken
+  dialect map — ADR-0004 in audio). Dropped: BeatMode audio cues (not a
+  language feature, untestable in CI), a `hoodlib.tui` DSL over Rich (Rich is
+  the DSL), `hoodlib.collections` query wrappers (comprehensions, `sorted`,
+  `itertools.groupby`, `Counter`), and a 0–10 "Vibe Score" (not actionable;
+  its real rules became HL004–HL006).
+
+- `scripts/align_prompt.py` + `/align-prompt` skill: rewrites a stale
+  generation prompt to the current release (v1.1 lexicon, line law wording,
+  current paths/commands), marks lines that ask for declined or dropped work
+  (`[DECLINED — ADR-0004]`, `[DROPPED …]`, `[NEVER — libcst]`), prepends the
+  PROMPTS.md §0 brief, and prints a change report. Prose is left alone —
+  English words that are also v1.0.0 tokens (`say`, `cut`, `word`, `mine`…)
+  are rewritten only in code context. Idempotent. PROMPTS.md §3.5.
+
 ## [1.3.1] — 2026-09-12
 
 Patch release: what the fresh-machine check of 1.3.0 found, plus two audit

{hoodscript-1.3.1 → hoodscript-1.4.0}/CONTRIBUTING.md

@@ -126,6 +126,13 @@ and the end-to-end audit in [`PROMPTS.md`](PROMPTS.md) §2.8, and only then
 merges. Two batches arrived on 2026-09-11 claiming completion with defects
 their own tests could not see; that is why.
 
+Concretely, for an agent (decided 2026-09-12): it works on a `gemini/<topic>`
+branch — never on `main`, never in a checkout another agent is using — pushes
+it, opens a PR with `.github/PULL_REQUEST_TEMPLATE.md` filled in, and stops.
+The `scripts/hooks/pre-commit` hook refuses commits on `main` unless
+`git config hoodscript.owner` matches `user.email` (the owner sets it once;
+`scripts/install-hooks.sh` installs the hooks).
+
 ## Working with an AI agent
 
 Paste the standing brief from [`PROMPTS.md`](PROMPTS.md) §0 at the top of

{hoodscript-1.3.1 → hoodscript-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hoodscript
-Version: 1.3.1
+Version: 1.4.0
 Summary: A production-grade Python 3 conlang based on AAVE with 1:1 AST parity.
 License: MIT
 License-File: LICENSE
@@ -110,7 +110,10 @@ hoodscript -c hello.hs        # print the Python it becomes
 hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
 hoodscript playground         # launch in-browser Pyodide WebAssembly playground
 hoodscript kernel install     # Jupyter kernel (pip install "hoodscript[jupyter]"); or %load_ext hoodscript
-hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
+hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]"); lint has HL001–HL006
+hoodscript replay <file.hs>   # run it, then step through it backwards (b/f/j/l/v/w); --dump prints all
+hoodscript migrate <file.hs>  # rewrite v1.0.0 code (cook/serve/holler/Facts…) to the v1.1 lexicon; -w writes, --diff shows
+hoodscript sourcing <word>    # Rule Zero check: standing, Green's Dictionary of Slang, UD liability screen, --coraal PATH
 hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
 hoodscript                    # a short tour of all commands
 hoodscript zen                # the Zen of HoodScript (HPEP 20); or `import vibe`
@@ -196,6 +199,7 @@ hoodarcade play cookout 1       # edit the solution file; the stage re-runs on s
 - [`docs/onboarding.md`](docs/onboarding.md) — from zero to a running program in ten minutes
 - [`docs/curriculum.md`](docs/curriculum.md) — ten lessons, each with a runnable file
 - [`MANUAL.md`](MANUAL.md) — the full manual
+- [`docs/hoodlib.md`](docs/hoodlib.md) — the small standard library: `chart` (sparklines, bars, histograms), `disk` (atomic files)
 - [`agents.md`](agents.md) — architecture and subsystem walkthrough
 - [`CLAUDE.md`](CLAUDE.md) — the standing brief for anyone (human or agent) changing the code
 - [`SPRINT_PLAN.md`](SPRINT_PLAN.md) — what's next · [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md)

{hoodscript-1.3.1 → hoodscript-1.4.0}/README.md

@@ -60,7 +60,10 @@ hoodscript -c hello.hs        # print the Python it becomes
 hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
 hoodscript playground         # launch in-browser Pyodide WebAssembly playground
 hoodscript kernel install     # Jupyter kernel (pip install "hoodscript[jupyter]"); or %load_ext hoodscript
-hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
+hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]"); lint has HL001–HL006
+hoodscript replay <file.hs>   # run it, then step through it backwards (b/f/j/l/v/w); --dump prints all
+hoodscript migrate <file.hs>  # rewrite v1.0.0 code (cook/serve/holler/Facts…) to the v1.1 lexicon; -w writes, --diff shows
+hoodscript sourcing <word>    # Rule Zero check: standing, Green's Dictionary of Slang, UD liability screen, --coraal PATH
 hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
 hoodscript                    # a short tour of all commands
 hoodscript zen                # the Zen of HoodScript (HPEP 20); or `import vibe`
@@ -146,6 +149,7 @@ hoodarcade play cookout 1       # edit the solution file; the stage re-runs on s
 - [`docs/onboarding.md`](docs/onboarding.md) — from zero to a running program in ten minutes
 - [`docs/curriculum.md`](docs/curriculum.md) — ten lessons, each with a runnable file
 - [`MANUAL.md`](MANUAL.md) — the full manual
+- [`docs/hoodlib.md`](docs/hoodlib.md) — the small standard library: `chart` (sparklines, bars, histograms), `disk` (atomic files)
 - [`agents.md`](agents.md) — architecture and subsystem walkthrough
 - [`CLAUDE.md`](CLAUDE.md) — the standing brief for anyone (human or agent) changing the code
 - [`SPRINT_PLAN.md`](SPRINT_PLAN.md) — what's next · [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md)

{hoodscript-1.3.1 → hoodscript-1.4.0}/SECURITY.md

@@ -50,7 +50,7 @@ To protect host environments against runaway workloads, the sandbox enforces thr
 
 ## 4. Code Execution Audit
 
-`exec`/`eval` appear in exactly six places, all on code objects produced by
+`exec`/`eval` appear in exactly seven places, all on code objects produced by
 `compile()` from the transpiler's output of the user's own source — never on
 text from anywhere else:
 1. `src/hoodscript/cli.py` — running a file
@@ -59,7 +59,8 @@ text from anywhere else:
 4. `src/hoodscript/tutor.py` — running a curriculum lesson
 5. `src/hoodscript/kernel/kernel.py` — executing notebook cells in the HoodScript kernel
 6. `src/hoodscript/kernel/magics.py` — executing `%%hood` cells in IPython / Google Colab
-`tests/security/test_exec_sites.py` fails if a seventh appears.
+7. `src/hoodscript/replay.py` — running a file under the `sys.settrace` recorder (`hoodscript replay`)
+`tests/security/test_exec_sites.py` fails if an eighth appears.
 
 ### Why this is safe and equivalent to `compile()`:
 - `transpile()` performs strictly lexical substitution over Python's `tokenize.tokenize` stream and deterministic character-preserving pattern transforms (Rules R1–R12).

{hoodscript-1.3.1 → hoodscript-1.4.0}/docs/adr/0002-keyword-reconciliation.md

@@ -1,7 +1,9 @@
 # ADR-0002: Linguistic Sourcing & Keyword Reconciliation
 
 ## Status
-Accepted (Sprint 1–2)
+Accepted (Sprint 1–2). Tier lists corrected 2026-09-12 to match GRAMMAR.md v1.1
+(`tryna` is Tier A, `chill` Tier B); re-audited with sources open — see
+`hoodscript/docs/linguistics.md` "Sourcing audit — 2026-09-12".
 
 ## Context
 The Sprint 0 prototype inherited a set of keywords (`cook`, `serve`, `crew`, `Facts`,
@@ -18,10 +20,14 @@ A rigorous audit against published AAVE lexicography revealed that:
 We adopted the 7-step Lexical Sourcing Policy (`hoodscript/docs/lexical-sourcing.md`)
 and reconciled the keywords to authentic, documented AAVE grammar and lexicon:
 * **Tier A Grammatical Features:** Habitual *be* (`be ... in`), intensive continuative
-  *steady* (`steady:`), immediate future *finna*, completive *done*, and remote past *BIN*.
-* **Tier B High-Frequency Vocabulary:** `bet` (agreement/commitment), `dip` (leave/return),
-  `fam` (class/family), `no cap` (true), `cap` (false), `holla` (print).
-* **Tier C Control Constructs:** `tryna`, `catch`, `regardless`, `throw`, `skip`, `chill`.
+  *steady* (`steady:`), immediate future *finna*, completive *done*, remote past *BIN*,
+  negation *ain't* / *ain't nobody*, existential *it's*, and *tryna* — each with a Yale
+  Grammatical Diversity Project page.
+* **Tier B Lexical Keywords:** `bet` (agreement/commitment), `dip` (leave/return),
+  `fam` (class/family), `no cap` (true), `cap` (false), `holla` (print), `chill` (pass),
+  and the `*Trip` exception suffix — each with dictionary attestation of AAVE use.
+* **Tier C Plain English, kept deliberately:** `catch`, `regardless`, `throw`, `skip`, `ask`,
+  `else if` — labelled as plain English, never claimed as AAVE.
 * **Python Pass-through:** Where no cited AAVE word existed with verifiable pedigree
   prior to 2005, Python's standard keywords (`if`, `else`, `while`, `import`, `with`)
   pass through unchanged rather than inventing artificial slang.

hoodscript-1.4.0/docs/hoodlib.md

@@ -0,0 +1,105 @@
+# hoodlib — the small standard library
+
+`hoodlib` ships with HoodScript and holds only what Python's own library
+doesn't give you in one call. Everything in it is standard-library Python,
+importable from `.hs` or `.py`, with no dependencies. Errors are the plain
+Python exceptions the crash reporter already explains.
+
+```
+from hoodlib import chart, disk
+```
+
+## `hoodlib.chart` — plots that fit in a terminal
+
+Every function returns a string, so you decide whether to `holla` it, log it,
+or test it.
+
+### Sparklines
+
+Two points per character on a four-dot Braille scale (80 columns show 160
+points), or one ▁▂▃ block per point with `style="blocks"`. The minimum still
+shows one dot, so every point is visible.
+
+```hood
+from hoodlib import chart
+temps = [61, 64, 70, 75, 73, 68, 62]
+holla chart.sparkline(temps, style="blocks")
+holla chart.sparkline(temps)
+```
+
+```
+▁▃▅█▇▅▁
+⣠⣾⣷⡀
+```
+
+`width=N` caps the output at N characters by resampling, never by cutting.
+
+### Bar charts
+
+```hood
+from hoodlib import chart
+holla chart.bar_chart({"corn": 12, "beans": 6, "hay": 0}, title="Bag", width=32)
+```
+
+```
+Bag
+────────────────────────────────
+corn  │█████████████████████ 12
+beans │██████████             6
+hay   │                       0
+```
+
+Bars scale to the largest value. `sort=True` orders them, `color=True` adds
+plain ANSI colour, and negative values draw an empty bar with the number
+rather than pretending to be zero. `chart.show_bag(bot.bag)` is the same
+thing for a game inventory, and an empty bag is a line saying so.
+
+### Histograms
+
+```hood
+from hoodlib import chart
+scores = [55, 62, 68, 71, 74, 75, 78, 81, 85, 93]
+holla chart.histogram(scores, bins=4, width=32)
+```
+
+```
+55–64.50 │██████████          2
+64.50–74 │██████████          2
+74–83.50 │███████████████████ 4
+83.50–93 │██████████          2
+```
+
+### What goes wrong, in plain English
+
+```hood
+# expect-crash
+from hoodlib import chart
+holla chart.sparkline([])
+```
+
+The report is a `BadValueTrip` saying `sparkline() got an empty series;
+there is nothing to plot`. A non-number names the item: `item 1 is 'x'
+(str)`.
+
+## `hoodlib.disk` — files that can't half-write
+
+Atomic writes (temp file + fsync + rename), per-path locks so two threads
+can't tear a file, and timestamped backups.
+
+```hood
+from hoodlib import disk
+disk.write_json("scores.json", {"ali": 3, "bo": 5})
+holla disk.read_json("scores.json")
+disk.append_csv("log.csv", ["ali", 3])
+holla disk.read_csv("log.csv", header=False)
+holla disk.read_json("missing.json", default={})
+```
+
+```
+{'ali': 3, 'bo': 5}
+[['ali', '3']]
+{}
+```
+
+`disk.backup(path, keep=5)` copies `path` to `path.<timestamp>.bak` and
+prunes older copies. A missing file with no `default` is a `MissingFileTrip`.

hoodscript-1.4.0/scripts/align_prompt.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+# ruff: noqa: E501  (rule tables read better on one line each)
+"""Align a stale generation prompt with the current release.
+
+Prompts written against the v1.0.0 package (the `cook`/`serve` lexicon, "AST
+isomorphism", `libcst`, `hoodscript vibe`, ...) keep arriving. Executing one as
+written regresses the language; aligning one by hand is the procedure in
+PROMPTS.md §3.5. This script does the mechanical half of that procedure and
+flags the half that needs a decision:
+
+  1. lexicon      v1.0.0 words -> v1.1 words (the CHANGELOG migration table);
+                  common English words (`say`, `word`, `cut`, ...) only inside
+                  backticks / code fences / `word (python)` glosses, so prose
+                  is not mangled
+  2. phrasing     "AST isomorphism" -> the line law, "Friendly Coach" -> the
+                  JPE engine, stale paths and commands -> current ones
+  3. decisions    lines that ask for something the owner declined or dropped
+                  (dialect overlays -> ADR-0004; hoodpkg, hoodlib.vault/net,
+                  libcst -> CHANGELOG) are kept but marked [DECLINED ...] /
+                  [DROPPED ...] so the agent does not do them and the reader
+                  sees why
+  4. framing      the PROMPTS.md §0 standing brief goes on top; a footer tells
+                  the agent to diff the scope against the tree before writing
+
+What it cannot do: know what is already on disk. That is the "diff against
+disk" step of §3.5 and stays a judgment call.
+
+Usage:
+    python scripts/align_prompt.py prompt.md            # aligned prompt on stdout, report on stderr
+    python scripts/align_prompt.py - < prompt.md
+    python scripts/align_prompt.py prompt.md -o aligned.md --report report.md
+    python scripts/align_prompt.py prompt.md --check    # exit 1 if anything would change
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# --------------------------------------------------------------------------- 1. lexicon
+# Source of truth: CHANGELOG.md "keyword migration table" (v1.0.0 -> v1.1) and
+# src/hoodscript/constants.py. Unambiguous tokens are rewritten anywhere;
+# AMBIGUOUS ones (real English words) only in code context.
+
+LEXICON: dict[str, str] = {
+    # keywords
+    "cook": "bet", "serve": "dip", "crew": "fam", "holler": "holla", "Facts": "no cap", "Cap": "cap",
+    "Ghost": "None", "mine": "self", "say": "if", "or_say": "else if", "otherwise": "else",
+    "run_thru": "be", "up_in": "in", "keep_goin_if": "while", "keep_pushin": "skip", "attempt": "tryna",
+    "aint": "ain't", "on_the_side": "finna", "hold_up": "done", "crash_out": "throw", "catch_heat": "catch",
+    "stand_on_it": "assert", "rock_with": "with", "cut": "del", "whole_city": "global",
+    "outside_scope": "nonlocal", "inspect": "match", "scenario": "case", "bring_in": "import", "outta": "from",
+    "quick_cook": "lambda", "pass_it": "yield", "and_also": "and", "or_else": "or", "straight_is": "is",
+    "whatever": "_",
+    # builtins
+    "check_mic": "assert", "count_up": "len", "span": "range", "what_kind": "type", "built_like": "isinstance",
+    "word": "str", "whole_num": "int", "point_num": "float", "lineup": "list", "ledger": "dict", "circle": "set",
+    "locked_lineup": "tuple", "unlock_file": "open", "tally": "sum", "index_run": "enumerate", "pair_up": "zip",
+    "every_single": "all", "any_at_all": "any", "weed_out": "filter", "apply_all": "map", "ancestor": "super",
+    # exceptions whose roots were cut
+    "GhostFileTrip": "MissingFileTrip", "StandOnItTrip": "AssertTrip",
+}
+
+# English words that are also v1.0.0 tokens: rewrite only in code context.
+AMBIGUOUS = frozenset({
+    "say", "otherwise", "mine", "attempt", "cut", "inspect", "scenario", "word", "circle", "span",
+    "tally", "ledger", "lineup", "whatever", "serve", "crew", "cook", "ancestor",
+})
+
+# --------------------------------------------------------------------------- 2. phrasing
+# (pattern, replacement, note). Applied in order, case-insensitive where flagged.
+PHRASES: list[tuple[str, str, str]] = [
+    (r"(?:a )?strict 1:1 AST isomorphism to CPython(?: 3\.1\d(?:[–-]3\.1\d)?)?",
+     "the 1:1 line law (token substitution; line N of the .py is line N of the .hs; no AST rewriting) on Python 3.10–3.13",
+     "AST isomorphism -> line law"),
+    # v1.0.0 `dip` meant break; v1.1 `dip` is return (CHANGELOG). Rewrite the glossed form before the lexicon pass.
+    (r"\bdip \(break\)", "break (break)", "dip (break) -> break: v1.1 dip is return"),
+    (r"`dip`\s*(?:->|→|=>)\s*`break`", "`break` (Python's word; v1.1 `dip` is `return`)", "dip -> break remap removed"),
+    (r"1:1 AST (?:isomorphism|parity|mapping)", "1:1 line mapping (token substitution, no AST rewriting)", "AST isomorphism -> line law"),
+    (r"100% CPython PEG grammar parity", "CPython compiles the output unchanged (the 1:1 line law)", "grammar parity -> line law"),
+    (r"lexical AST rewriting", "token-stream rewriting (`tokenize` -> NAME substitution -> `untokenize`)", "AST rewriting -> token rewriting"),
+    (r"with AST validation", "via `hoodscript.transpile` -> `compile` -> `exec`", "AST validation -> transpile/compile"),
+    (r"Friendly Coach(?: error hook(?: integrations)?)?", "the JPE error engine (`hoodscript.errors`: `diagnose` -> `render_plain`; register the source in `linecache` first)",
+     "Friendly Coach -> JPE engine"),
+    (r"`?hoodscript vibe`?(?![-\w])", "`hoodscript zen`", "hoodscript vibe -> hoodscript zen"),
+    (r"`?bring_in vibe`?", "`import vibe`", "bring_in vibe -> import vibe"),
+    (r"examples/arcade_solutions/?", "examples/solutions/<game>/", "arcade_solutions path"),
+    (r"tests/test_hoodlib\.py", "tests/test_hoodlib_disk.py", "test_hoodlib path"),
+    (r"`hoodarcade levels <game>`", "`hoodarcade list` / `hoodarcade levels [game]`", "levels command"),
+    (r"`--watch` live solution reloading", "hot-reload on save (the default of `play`; `--once` disables it)", "--watch is the default"),
+    (r"`hood` CLI entry point|`hood` command", "`hoodscript` CLI (there is no `hood` entry point in the release package)", "hood -> hoodscript"),
+    (r"Python 3\.11\+", "Python 3.10–3.13", "Python floor is 3.10"),
+    (r"prompt-toolkit, pygments, libcst, jedi, pygls", "zero-dependency core; extras `repl lsp tools pretty farm arcade jupyter all dev`", "dependency list"),
+    (r"beyond `rich`, `cryptography`, and `prompt-toolkit`", "beyond what pyproject's extras already declare (`rich` for the games; the core has none)", "deps: no cryptography"),
+]
+
+# --------------------------------------------------------------------------- 3. decisions
+# (pattern, marker). A line matching a pattern is prefixed with the marker.
+DECISIONS: list[tuple[str, str]] = [
+    (r"dialect|Bay Area|Atlanta \(|DMV \(|UK Drill|\bMLE\b|kill_moe|on_mama|WastemanTrip",
+     "[DECLINED — ADR-0004 (docs/adr/0004-no-regional-dialect-overlays.md): no dialect overlays under Rule Zero]"),
+    (r"hoodpkg|hood\.toml|hood\.lock|\bpkg\.py\b|hood (?:new|add|install|lock|publish)\b",
+     "[DROPPED — duplicates pyproject/pip; .hs files are already importable modules (CHANGELOG 1.3.0)]"),
+    (r"vault\.py|hoodlib\.vault|AES-GCM|PBKDF2|payload signing",
+     "[DROPPED — hoodlib ships only what Python lacks; `cryptography` is one import away (CHANGELOG 1.3.0)]"),
+    (r"\bnet\.py\b|hoodlib\.net|async(?:hronous)? HTTP client|connection pooling",
+     "[DROPPED — same; `aiohttp`/`httpx` are one import away (CHANGELOG 1.3.0)]"),
+    (r"libcst", "[NEVER — libcst was cut with the v1.0.0 stack; the transpiler is tokenize-based]"),
+    (r"^\s*<lexicon_taxonomy>",
+     "[NOTE — the keyword set is `src/hoodscript/constants.py` + GRAMMAR.md R1–R12; this table was rewritten to v1.1 and is informational only]"),
+]
+
+FOOTER = """
+---
+ALIGNMENT FOOTER (added by scripts/align_prompt.py — keep it)
+
+Before writing a line: diff this scope against the tree. `git ls-files src tests
+examples docs` and the CHANGELOG say what already exists; PROMPTS.md §3.5 is the
+worked example of this procedure. Items marked [DECLINED]/[DROPPED]/[NEVER]
+above are out of scope by owner decision — do not re-propose them inside the
+batch. Work on a `gemini/<topic>` branch and open a PR (agents.md). No tags.
+Gate: `ruff check && pytest`. Docs are tests. Complete files.
+"""
+
+_WORD = r"(?<![\w'])({})(?![\w'])"
+
+
+@dataclass
+class Report:
+    lexicon: dict[str, int] = field(default_factory=dict)
+    phrases: dict[str, int] = field(default_factory=dict)
+    flagged: list[tuple[int, str]] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.lexicon or self.phrases or self.flagged)
+
+    def render(self) -> str:
+        out = ["# align_prompt report", ""]
+        if self.lexicon:
+            out.append("## Lexicon rewrites (v1.0.0 -> v1.1)")
+            for k, n in sorted(self.lexicon.items(), key=lambda kv: -kv[1]):
+                out.append(f"- `{k}` -> `{LEXICON[k]}` ×{n}")
+            out.append("")
+        if self.phrases:
+            out.append("## Phrasing / paths / commands")
+            for k, n in self.phrases.items():
+                out.append(f"- {k} ×{n}")
+            out.append("")
+        if self.flagged:
+            out.append("## Lines flagged by owner decision (kept, marked, out of scope)")
+            for ln, marker in self.flagged:
+                out.append(f"- line {ln}: {marker.split(' — ')[0].strip('[')}")
+            out.append("")
+        if not self.changed:
+            out.append("Nothing to change: the prompt is already aligned.")
+        out.append("Still to do by hand: diff the scope against the tree (PROMPTS.md §3.5).")
+        return "\n".join(out) + "\n"
+
+
+def standing_brief() -> str:
+    """PROMPTS.md §0, the block that goes at the top of every prompt."""
+    text = (ROOT / "PROMPTS.md").read_text(encoding="utf-8")
+    m = re.search(r"## 0\. The standing brief.*?\n```\n(.*?)\n```", text, re.S)
+    return m.group(1) if m else ""
+
+
+def _code_spans(text: str) -> list[tuple[int, int]]:
+    """Character ranges that count as code: fenced blocks, backtick spans, and
+    `word (python)` glosses like the lexicon tables these prompts carry."""
+    spans = []
+    for m in re.finditer(r"```.*?```", text, re.S):
+        spans.append(m.span())
+    for m in re.finditer(r"`[^`\n]+`", text):
+        spans.append(m.span())
+    for m in re.finditer(r"\b\w+ \((?:def|return|yield|lambda|class|self|if|elif|else|for|in|while|break|continue|pass|import|from|as|try|except|finally|raise|assert|with|async|await|del|global|nonlocal|match|case|True|False|None|_|and|or|not|is|print|len|range|type|str|int|float|list|dict|set|tuple|open|sum|enumerate|zip|all|any|filter|map|isinstance|super|input)\)", text):
+        spans.append(m.span())
+    return spans
+
+
+def _in_code(spans: list[tuple[int, int]], pos: int) -> bool:
+    return any(a <= pos < b for a, b in spans)
+
+
+def rewrite_lexicon(text: str, report: Report) -> str:
+    spans = _code_spans(text)
+    # longest first so `locked_lineup` wins over `lineup`, `or_say` over `say`
+    words = sorted(LEXICON, key=len, reverse=True)
+    pattern = re.compile(_WORD.format("|".join(re.escape(w) for w in words)))
+
+    def sub(m: re.Match) -> str:
+        w = m.group(1)
+        if w in AMBIGUOUS and not _in_code(spans, m.start()):
+            return w
+        report.lexicon[w] = report.lexicon.get(w, 0) + 1
+        return LEXICON[w]
+
+    return pattern.sub(sub, text)
+
+
+def rewrite_phrases(text: str, report: Report) -> str:
+    for pat, repl, note in PHRASES:
+        text, n = re.subn(pat, repl, text)
+        if n:
+            report.phrases[note] = report.phrases.get(note, 0) + n
+    return text
+
+
+def collapse_glosses(text: str, report: Report) -> str:
+    """After the lexicon pass a table row like `bring_in (import)` reads
+    `import (import)`; say what that means."""
+    text, n = re.subn(r"\b(\w+) \(\1\)", r"\1 (Python's word)", text)
+    if n:
+        report.phrases["X (X) gloss -> Python's word"] = n
+    return text
+
+
+def mark_decisions(text: str, report: Report) -> str:
+    out = []
+    for i, line in enumerate(text.split("\n"), 1):
+        for pat, marker in DECISIONS:
+            if re.search(pat, line, re.I) and not line.lstrip().startswith("["):
+                indent = line[: len(line) - len(line.lstrip())]
+                line = f"{indent}{marker} {line.lstrip()}"
+                report.flagged.append((i, marker))
+                break
+        out.append(line)
+    return "\n".join(out)
+
+
+HEAD_MARK = "<!-- PROMPTS.md §0 standing brief, prepended by scripts/align_prompt.py -->"
+HEAD_END = "\n\n---\n\n"
+
+
+def align(text: str, *, brief: bool = True) -> tuple[str, Report]:
+    """Idempotent: a brief this script prepended and a footer it appended are
+    recognised and left alone (the brief names the cut words on purpose)."""
+    report = Report()
+    head = ""
+    if text.startswith(HEAD_MARK) and HEAD_END in text:
+        head, text = text.split(HEAD_END, 1)
+        head += HEAD_END
+    if FOOTER.strip() in text:
+        text = text.replace(FOOTER.strip(), "").rstrip("\n") + "\n"
+
+    body = rewrite_phrases(text, report)      # phrase rules first: `dip (break)` must go before the lexicon pass
+    body = rewrite_lexicon(body, report)
+    body = collapse_glosses(body, report)
+    body = mark_decisions(body, report)
+    if not head and brief and "You are working on HoodScript" not in text:
+        b = standing_brief()
+        head = f"{HEAD_MARK}\n{b}{HEAD_END}" if b else ""
+    return head + body.rstrip("\n") + "\n" + FOOTER, report
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("prompt", help="prompt file, or - for stdin")
+    ap.add_argument("-o", "--out", help="write the aligned prompt here (default: stdout)")
+    ap.add_argument("--report", help="write the change report here (default: stderr)")
+    ap.add_argument("--no-brief", action="store_true", help="do not prepend the PROMPTS.md §0 brief")
+    ap.add_argument("--check", action="store_true", help="exit 1 if the prompt would change (no output)")
+    args = ap.parse_args(argv)
+
+    text = sys.stdin.read() if args.prompt == "-" else Path(args.prompt).read_text(encoding="utf-8")
+    aligned, report = align(text, brief=not args.no_brief)
+
+    if args.check:
+        sys.stderr.write(report.render())
+        return 1 if report.changed else 0
+    if args.out:
+        Path(args.out).write_text(aligned, encoding="utf-8")
+    else:
+        sys.stdout.write(aligned)
+    if args.report:
+        Path(args.report).write_text(report.render(), encoding="utf-8")
+    else:
+        sys.stderr.write(report.render())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())