Locque Repo Orientation

Use this skill when starting work in the locque repo or when you need a reference for project conventions, tooling, and the "definition of done."

What Locque is

Locque is a dependently typed, keyword-led language with a strict CBPV split (values vs computations), a 1:1 M-expr ↔ S-expr mapping, explicit effects, and no implicit coercions. It is built almost entirely by LLMs.

Project layout

Tooling

The primary tool is smyth (installed at ~/.local/bin/smyth):

smyth test              # Run full test suite (entry: test/main.lq)
smyth test <file>       # Run one test file
smyth test --slow       # Show slowest test suites
smyth bench             # Run benchmarks (test/bench.lq)
smyth run <file>        # Type-check and run a .lq file
smyth dump core <file>  # Inspect elaborated output

Always run smyth test after any change — it is the gate for "done."

File conventions

• Source: .lq (M-expr, human-authored). Do NOT handwrite .lqs.
• Paths: lowercase only — lib/some/module.lq, test/some/module.lq
• Every lib/**/*.lq must have a matching test/**/*.lq
• Module name Some::Module maps to file lib/some/module.lq
• Test module Test::Some::Module maps to test/some/module.lq

Syntax quick-reference

# Definition
define transparent name as <Value>
define opaque       name as <Value>

# Function
define transparent inc as
  function x Natural returns Natural value
    Ar::add x 1
  end

# Computation value (effect-bearing)
define transparent main as compute
  perform (IO::print "hello")
end

# Data type
define transparent Option as data A Type0 in Type0
  case Option::none of-type Option A
  case Option::some of-type for-all x as A to Option A
end

# Match
match opt of-type (Option A) as ignored returns A
  case Option::none as fallback
  case Option::some with x A as x
end

# Import and qualify
import string as S   # Use S::concat, S::eq, etc.
open S exposing concat end  # Then use concat directly

Key rules:

• Qualification uses :: only (never .)
• Application is prefix, left-associative
• end closes every block (function, compute, match, data, module, open, bind, typeclass, instance, pack, unpack)
• List literals: [] and [a, b] (commas required); empty lists need of-type [] (List A) when no type is in scope
• Use ignored instead of _ for unused binders
• Effects are explicit: computation T type, bridged by perform; sequences via bind name from comp then ... end

Writing tests

import assert as A

module test::my_module contains
  define transparent run-tests as compute
    bind ignored from
      A::assert-eq Natural (Ar::add 1 2) 3
    then
      perform (IO::print "tests passed")
    end
  end
end

• Use A::assert-eq with an explicit type argument
• Add your test module to test/main.lq imports and the runner

What polecats do (and do not) change

Typical polecat work (library .lq files):

• New library functions in lib/
• New or updated tests in test/
• Syntax fixes, refactors within .lq files
• Adding/fixing data types, typeclasses, instances

Off-limits for polecats (interpreter):

• interpreter/ — Haskell source. Do NOT modify unless the bead explicitly asks for interpreter changes. The interpreter is a separate build (GHC required) and is rarely the right place to fix library-level issues.
• Do not add new primitives without explicit instruction from the bead.

Definition of done (checklist)

[ ] smyth test — all tests pass (no deletions to make tests pass)
[ ] New lib file has a matching test file
[ ] Paths are lowercase
[ ] No handwritten .lqs files
[ ] No changes to interpreter/ (unless bead explicitly requires it)
[ ] git status clean
[ ] gt done

Related skills

• locque-authoring — detailed authoring rules: data/match forms, module syntax, CBPV rules, templates