Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .agents/commands/next-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
description: Pick up the next ready plan file and ship it to a PR
agent: build
---

Find the next plan in `.agents/plans/` where `status: ready`. Order by id
(A0 before A1 before A2; A before B). Skip plans whose status is `blocked`,
`in-progress`, `review`, `merged`, or `deferred`.

Show me the plan summary first:

- id and title
- direction
- branch and base
- success criteria (as a checklist)
- estimated effort (from your read of the plan)

Then ask whether to proceed.

If I confirm, load the `ship-a-plan` skill and execute it on that plan file.

If there are no ready plans, list the plans grouped by status so I can see
the current state of the pipeline.
75 changes: 75 additions & 0 deletions .agents/commands/open-pr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
description: Open a PR for the current branch using its matching plan file
agent: build
---

Current branch: !`git branch --show-current`

Recent commits on this branch (vs main): !`git log --oneline main..HEAD 2>/dev/null | head -10`

Diff stat: !`git diff --stat main...HEAD 2>/dev/null | tail -20`

Find the plan file under `.agents/plans/` whose frontmatter `branch:`
matches the current branch.

If no matching plan exists, ask me whether to:
1. Open the PR without a plan (and write the body manually).
2. Stop and create a plan first.

If a matching plan exists:

1. Verify its status is `in-progress` or `review`. If it's still `ready`,
ask whether `ship-a-plan` was started — there may be a missed step.

2. Generate the PR body from the plan. Template:

```markdown
## {Plan title}

Plan: [`.agents/plans/{id}-{slug}.md`](link to file at HEAD)
Closes #{issue from plan frontmatter}

### Goal
{From plan}

### Success criteria
{Render as checkboxes; check off the ones the diff actually achieves}

### Verification

- mix test: <count> passing, <count> failures
- mix test --only lua53: <count>/24 passing
- <other commands from plan's Verification section>

### Changes
{git diff --stat output}

### Out of scope (intentional)
{From plan's "Out of scope" section}

### Discoveries
{From plan's Discoveries section if non-empty, otherwise omit}
```

3. Open the PR:

```bash
gh pr create --title "{type}({id}): {plan title}" --body "$(cat <<'EOF'
...body...
EOF
)"
```

Where `{type}` is feat/fix/perf/chore/docs based on the plan's direction
and nature.

4. Update the plan file:
- Set frontmatter `status: review`.
- Set frontmatter `pr: <new PR number>`.
- Append `## What changed` if not already present.
- Commit this update with message `chore({id}): mark plan as review`.
- Push.

5. Output the PR URL.

Stop. Do not run `gh pr merge`. Wait for human review.
31 changes: 31 additions & 0 deletions .agents/commands/suite-status.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
description: Run the Lua 5.3 suite, report pass/fail counts, propose ROADMAP update if changed
agent: build
---

Run the Lua 5.3 official test suite and report results:

!`mix test --only lua53 2>&1 | tail -10`

Then run a fuller per-file survey using `triage-suite-failure`'s standalone
pattern (build a small Elixir script in /tmp, iterate over every file in
test/lua53_tests/*.lua with an 8-second timeout, capture PASS/FAIL with
short error message). Don't bother instrumenting individual failures —
this command is a status check, not a triage session.

Show me:

1. Pass count: N/24
2. Files passing
3. Files failing (with short error category)
4. Files timing out
5. Delta vs ROADMAP.md's "Status" line

If the count differs from `ROADMAP.md`, propose an edit (don't make the edit
without my confirmation):

- New status line
- Updated "Done" entries if any
- Any new "Deferred" notes if a file flipped from passing → failing

If the count is unchanged, just confirm.
87 changes: 87 additions & 0 deletions .agents/plans/A0-int-overflow-wrapping.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
id: A0
title: 64-bit integer overflow wrapping for arithmetic and bitwise ops
issue: null
pr: null
branch: feat/int-overflow-wrapping
base: main
status: ready
direction: A
unlocks:
- bitwise.lua
---

## Goal

Make integer operations wrap to signed 64-bit per the Lua 5.3 spec, so
`maxint + 1 == minint` and `1 << 63 == minint` instead of overflowing into
arbitrary-precision Erlang integers.

## Out of scope

- Float arithmetic (already IEEE 754 — leave as-is).
- Float-to-integer coercion edge cases beyond what's already implemented.
- Any compiler/codegen changes.
- Suite triage of `bitwise.lua` failures unrelated to overflow (those go in
a follow-up plan if any remain after this lands).

## Success criteria

- [ ] `mix test` passes (≥ 1273, no regressions)
- [ ] New unit tests in `test/lua/vm/arithmetic_test.exs`:
- `maxint + 1 == minint`
- `minint - 1 == maxint`
- `maxint * 2 == -2`
- `1 << 63 == minint`
- `~0 == -1`
- `bnot(0xffffffffffffffff) == 0`
- `0x8000000000000000 // 1 == minint` (no overflow into bignum)
- [ ] `mix test --only lua53` count is unchanged or improved (target:
`bitwise.lua` flips green if it was failing solely on this).

## Implementation notes

The historical `phase-17-suite-triage` branch (commit `796e384`) had this
fix. Its approach:

- Add a `to_signed_int64/1` helper in `lib/lua/vm/executor.ex` (or a new
`Lua.VM.Numeric` module if cleaner) that masks a value to 64 bits then
converts to Erlang's signed range:
```elixir
defp to_signed_int64(n) when is_integer(n) do
masked = Bitwise.band(n, 0xffffffffffffffff)
if masked >= 0x8000000000000000, do: masked - 0x10000000000000000, else: masked
end
```
- Apply to integer arithmetic results: `:add`, `:subtract`, `:multiply`,
`:floor_divide`, `:modulo`, unary `:negate`. Only when both operands are
integers (not floats).
- Apply to bitwise ops: `:band`, `:bor`, `:bxor`, `:bnot`, `:shift_left`,
`:shift_right`.
- The CPS executor (PR #156) reorganized these handlers — the helper goes
in the same file where they live now.

NOTE: Main has moved significantly since `796e384` was written. The CPS
executor refactor (PR #156) and earlier perf PRs (#153–#155) changed the
shape of `executor.ex`. Do NOT cherry-pick the old commit blindly — read
the current code, then write fresh patches that fit the new structure.

## Verification

```bash
mix format
mix compile --warnings-as-errors
mix test
mix test --only lua53
mix test test/lua/vm/arithmetic_test.exs
```

## Risks

- Float operations must be untouched. If the helper accidentally fires on
floats, IEEE 754 behavior breaks.
- Bitwise ops in Lua 5.3 are technically defined on 64-bit unsigned, but
the result is presented as signed. Make sure tests cover the boundary
cases (e.g. `0xffffffffffffffff + 1` should be `0` after wrapping).
- Some property tests in the existing test suite may rely on the current
(incorrect) bignum behavior — they'll need updating to match Lua 5.3.
99 changes: 99 additions & 0 deletions .agents/plans/A1-table-nil-on-missing-key.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
id: A1
title: Empty/missing-key table reads return nil instead of crashing
issue: null
pr: null
branch: fix/table-nil-on-missing-key
base: main
status: ready
direction: A
unlocks:
- errors.lua
- sort.lua
- strings.lua
- verybig.lua
- nextvar.lua
---

## Goal

Reading a missing key from a table must return `nil`, not raise
`Map.fetch!` (which currently surfaces as `Lua runtime error: key N not
found in: %{}`).

This is the highest-leverage Direction A fix: it unblocks at least 4 suite
files that all share the same root cause.

## Out of scope

- Metatable `__index` resolution (this is already implemented and must keep
working — fix must not break it).
- Performance optimization of table access.
- Any other suite failures that surface downstream of this fix; those go in
follow-up plans.
- Behavior of `rawget` (also already correct — don't touch).

## Success criteria

- [ ] `mix test` passes (≥ 1273, no regressions)
- [ ] New unit tests in `test/lua/vm/table_index_test.exs`:
- `local t = {}; return t[5]` → returns `[nil]`
- `local t = {1,2,3}; return t[10]` → returns `[nil]`
- `local t = {a=1}; return t.b` → returns `[nil]`
- `local t = {}; return t[5] == nil` → returns `[true]`
- Metatable `__index` still resolves correctly (regression test)
- [ ] `mix test --only lua53` count improves: at least 2 of the 4 listed
`unlocks:` files pass (some may surface new downstream failures —
that's acceptable; track in `## Discoveries`).

## Implementation notes

Find the failing path: it's currently a `Map.fetch!` in `executor.ex`
somewhere in the table-read instruction handler(s).

After the CPS executor refactor (PR #156), the relevant handlers are likely
named differently from the old design. Search for:

```bash
grep -nE "Map.fetch!|\\\\[.*\\\\]" lib/lua/vm/executor.ex
grep -nE "(get_field|get_table|get_index|table_get)" lib/lua/vm/executor.ex
```

Replace the offending `Map.fetch!(table.data, key)` with
`Map.get(table.data, key, nil)` — but only AFTER the metatable `__index`
chain has been consulted. The order is:

1. Direct lookup in `table.data`.
2. If not present and table has metatable with `__index`, walk the chain.
3. If still not found, return `nil`.

The bug is likely that step 1 raises instead of falling through to step 2,
or that step 3 never runs because step 1 raises.

Also check `lib/lua/vm/stdlib.ex` `pairs` / `ipairs` / `next` — they may
have similar `Map.fetch!` calls that should be `Map.get`.

## Verification

```bash
mix format
mix compile --warnings-as-errors
mix test
mix test --only lua53
mix test test/lua/vm/table_index_test.exs
```

Compare suite count before/after; capture in PR body.

## Risks

- If `__index` metamethod resolution depended on the raise (using
rescue/try as control flow), the metamethod path needs explicit reordering.
- A test may currently rely on the raise — search for it before changing,
update the test if needed.
- Some ipairs/next implementations may use the raise to detect end-of-array;
if so, switch them to explicit `Map.has_key?` checks.

## Discoveries

(populated during implementation)
71 changes: 71 additions & 0 deletions .agents/plans/A10-suite-timeouts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
id: A10
title: Investigate big.lua, closure.lua, utf8.lua timeouts
issue: null
pr: null
branch: fix/suite-timeouts
base: main
status: ready
direction: A
unlocks:
- big.lua
- closure.lua
- utf8.lua
---

## Goal

Diagnose why these three suite files hang past 8 seconds. They likely have
distinct root causes; this plan does the triage and either ships a fix or
splits into A10a/b/c.

## Out of scope

- Performance optimization (Direction B).
- Anything not directly causing the timeout.

## Success criteria

- [ ] `mix test` passes (≥ 1273, no regressions)
- [ ] Each timeout reduced to a fast-failing unit test (or fixed)
- [ ] At least 2 of 3 files complete (pass or proper failure) within 30s.

## Implementation notes

Triage workflow per file:

1. Add line-print instrumentation to find where it stops printing — that's
near the infinite loop.
2. Reduce to a unit test that hangs with the same pattern.
3. Investigate. Common timeout causes in this VM:
- For-loop exit condition that never trips (integer comparison vs
float comparison mismatch).
- Multi-return that produces an infinite stream because of a missing
base case.
- Recursive function with broken base case (likely in upvalue/closure
code, given `closure.lua` is one of them).
- `utf8.lua` repeats "testing UTF-8 library" — strongly suggests it
loops on the test setup itself.

If a single root cause unblocks all three, ship together. If they're
distinct, split.

## Verification

```bash
mix format
mix compile --warnings-as-errors
mix test
mix test --only lua53
```

## Risks

- Timeouts can mask real bugs. Make sure a fix doesn't just speed up a
buggy infinite loop; it should produce correct output.
- Some loops may be intentional stress tests (`big.lua` is named for
size); the suite expects them to complete in seconds, not minutes.

## Discoveries

(populated during implementation)
Loading
Loading