hoodscript 1.3.0__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.0 → hoodscript-1.4.0}/CHANGELOG.md

@@ -5,6 +5,131 @@ 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
+leftovers. No keyword or API changes.
+
+### Fixed
+
+- Fresh-machine check of v1.3.0 (`pip install "hoodscript[all]"` in a clean
+  venv, `docs/onboarding.md` §2–§11 verbatim): everything passed except
+  `hoodfarm test` and `hoodarcade test`, which reported "No Sol" for every
+  level and **exited 0** — the reference solutions were not in the wheel and a
+  missing solution counted as a pass. The solutions now ship
+  (`hoodscript/data/solutions`, found by both CLIs after the repo checkout), a
+  missing one is a red `MISSING` row and a non-zero exit, and
+  `tests/test_wheel_contents.py` builds the wheel and asserts the runtime
+  data (curriculum, `vibe.py`, solutions) is inside it.
+
+- `hoodscript --sandbox run f.hs` now works (the flags may come before or after
+  `run`; `run` is recognised as the first positional, not only as `argv[0]`).
+- Jupyter: `%hood_tb` is honoured by the error card — the Python traceback
+  section opens by default and the plain-text fallback carries it too.
+- MANUAL §16 documents that `hoodscript fmt` writes `ain't nobody x` back as
+  `ain't x` (same Python, one canonical spelling).
+- `cli.py` had the `arcade` dispatch block twice; the copy is gone.
+
 ## [1.3.0] — 2026-09-12
 
 Three features that were on `main` but not on PyPI: the two games and the

{hoodscript-1.3.0 → 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.0 → hoodscript-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hoodscript
-Version: 1.3.0
+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.0 → 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.0 → 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.0 → 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.3.0 → hoodscript-1.4.0}/pyproject.toml

@@ -61,6 +61,9 @@ packages = ["src/hoodscript", "src/hoodlib", "src/hoodfarm", "src/hoodarcade"]
 "docs/curriculum.md" = "hoodscript/data/curriculum.md"
 # `import vibe` — the Zen of HoodScript, like `import this`.
 "src/vibe.py" = "vibe.py"
+# `hoodfarm test` / `hoodarcade test` benchmark the reference solutions; a pip
+# install has no examples/ tree, so ship them (found via hoodscript/data/solutions).
+"examples/solutions" = "hoodscript/data/solutions"
 
 [tool.hatch.build.targets.sdist]
 # The nested hoodscript/ prototype is reference material, not part of the distribution.