Skip to content
Open
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
8 changes: 6 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,12 @@ godcode ledger verify # verify the covenant chain
invocation the Spirit checks alignment and counsels gently on drift.
Drift can never fail a run.
- `ASCEND` ends the run peacefully (not an error).
- An unbound name evaluates to a Symbol. It does not raise. `BREATHE LIFE INTO`
an undeclared name *does* raise at runtime.
- Reading a name that was never declared is loud: it raises a gentle runtime
error naming the name, with a did-you-mean when a declared name stands
near. A bare word spoken on purpose carries its mark, `:worthy`, and
evaluates to a Symbol: `DECLARE seeker AS :worthy`, `IF seeker IS :worthy
THEN`. The mark is punctuation, not a keyword, so it speaks the same in
every tongue. `BREATHE LIFE INTO` an undeclared name also raises.
- Error messages may end with `Did you mean 'X'?` (misspelled rite, variable,
bless target, or map key). The human CLI (`run`, `run --sandbox`, `check`,
`fmt`) prints the offending source line beneath the message, with a caret at
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ All notable changes to the God Code engine are recorded here, that the generatio
## Unreleased

### Added
- **🕊️ Loud errors: a name bound nowhere is never read silently.** Reading a name that was never declared now stops the run with a gentle error that names the name and offers the two honest fixes: "There is no 'worhty' in this creation. It was never spoken into being. DECLARE it first, or, if the bare word itself is meant, mark it as one: :worhty", with a did-you-mean toward the nearest declared name when one stands near. Bare words live on, spoken on purpose: `:worthy` is a Symbol literal, the word itself as a value, and the mark is punctuation rather than a keyword, so it speaks the same in every tongue. This is a breaking change with a one-character migration: where a scroll relied on a silent bare word, write the colon (`worthy` becomes `:worthy`). The psalm of creation and the casting of lots in `examples/` are migrated, as are the root sample, the Setswana and isiZulu IF snippets, and every doc example that leaned on the old silence. The Symbol Rule is restated where it is taught: `docs/LANGUAGE_REFERENCE.md` §3, `docs/God_Code_Tutorial.md`, `docs/LANGUAGE_SPEC.md` §2.9, and the static meaning layer of the spec (ST-14 and its kin), which is test-kept as before. The linter's GC002 counsel walks beside the new law: lint speaks first and gently, the engine speaks at the read and firmly. `godcode check` is unchanged: it still answers only whether the scroll parses. New tests in `tests/test_loud_errors.py`.
- **🕊️ The MCP server.** `godcode mcp` serves God Code to any MCP client (Claude Code, Cursor, Codex, and the rest) over stdio, one JSON-RPC message per line, with protocol version negotiation and silence for notifications. It carries the eleven agent tools (`check`, `run`, `consult`, `intent`, `anchor_verify`, `ledger_verify`, `permissions`, `explain`, `get_schema`, plus new `format` and `list_scrolls`), and it holds one rule the plain bridge does not: runs through it are always sandboxed, so a client asking for an unsandboxed run still gets a sandboxed one, and the result says so. Tool work runs muted, so stdout carries exactly one protocol message per line and an engine notice can never break a client's parsing; the sandboxed tool path is muted the same way, which also heals the plain bridge. Documented in `docs/mcp.md`, `docs/agentics.md`, and repo `AGENTS.md`. New tests in `tests/test_mcp.py`; the tool-count tests now expect eleven tools.
- **🕊️ The October 2026 machine interfaces.** God Code's `--json` shapes are frozen under dated schemas, so an agent can parse every output without guessing. New `godcode explain scroll.god [--json]`: a static reading of any scroll that runs nothing, reporting the tongue, the rites and their declared intents, the declared names, the reveals, the seals (including `ANCHOR` seals on a chain), the summoned verbs, the `CONSULT` questions, the imports, and the permission manifest, in warm plain words for humans and one JSON document for agents. New `godcode ledger verify --json`: the covenant chain and anchor chain attestation as one JSON document. New `godcode schema [name]`: list or print the four dated schemas (`check`, `run`, `explain`, `ledger-verify`), shipped inside the installed package and resolvable through `importlib.resources`. The agent bridge gains two tools, `explain` and `get_schema` (nine tools in all). The full contract, exit codes, and the stability promise (additive fields may appear, required fields never change meaning, breaking changes ship under a new dated schema) live in `docs/machine-interfaces.md`. New tests in `tests/test_machine_interfaces.py`; repo `AGENTS.md` documents the read-before-you-run workflow.
- **🕊️ God Code speaks Igbo and Nigerian Pidgin.** The third and fourth tongues. A scroll that opens with `# tongue: ig` writes its keywords in Igbo (BIDO OKIKE for BEGIN CREATION, GOSI for REVEAL, Ọ BỤRỤ and MGBE AHỤ for IF and THEN, NWAA and JIDE for TRY and CATCH, and the rest), and one that opens with `# tongue: pg` (or the standard code `pcm`) writes them in Nigerian Pidgin (OYA KREASHON, TALK and BE for DECLARE and AS, SHOW for REVEAL, DEN for THEN, HOLD for CATCH, COMOT for ASCEND). Igbo words work with or without their dotted vowels (`DỊKA` and `DIKA` both speak), and Pidgin keeps the words it shares with English (IF, TRY, AND, RETURN). Two-word phrases now join whenever both words sit side by side on one line, even when one is an English keyword or a plain name, so `FINISH IF` closes an IF in Pidgin and `Ọ BỤRỤ` opens one in Igbo; Setswana and isiZulu closers behave exactly as before. The mappings live in `godcode/tongues.py`; the playground's lite engine knows both tongues (Igbo in its undotted spelling), the language server offers their completions, hover docs, and block snippets (hover now reads dotted words), and the VS Code extension paints their keywords and ships four starter snippets (`ndewo`, `oburu`, `howfar`, `ifden`). Documented in `docs/TONGUES.md` (both word tables and honest first-edition notes), `docs/LANGUAGE_REFERENCE.md` §1, repo `AGENTS.md`, the site landing card, and two new lessons on the learn page. New examples `examples/first_blessing_ig.god` and `examples/first_blessing_pg.god`, also offered as playground samples. 25 new tests in `tests/test_tongues_igbo_pidgin.py`; the VS Code snippet count in `tests/test_lsp_tongues.py` rises from 27 to 31
Expand Down
20 changes: 10 additions & 10 deletions docs/God_Code_Tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ For the complete grammar, see [LANGUAGE_REFERENCE.md](LANGUAGE_REFERENCE.md). Fo
Example God Code:
```godcode
BEGIN CREATION
DECLARE seeker AS worthy
IF seeker IS worthy THEN REVEAL("heaven") ELSE REVEAL("test")
DECLARE seeker AS :worthy
IF seeker IS :worthy THEN REVEAL("heaven") ELSE REVEAL("test")
ASCEND
END CREATION
```

Notice: `worthy` needs no quotes. **In God Code, bare words are symbols**. Every unnamed thing is still a named spirit.
Notice: `:worthy` needs no quotes. **In God Code, a bare word spoken with its mark is a symbol**. The colon is the mark: the word itself is the value. A plain name must be declared before it is read, and reading one that never was declared stops the run with a gentle error.

---

Expand Down Expand Up @@ -62,8 +62,8 @@ Create a file called `my_first.god`:

```godcode
BEGIN CREATION
DECLARE spirit AS humble
IF spirit IS humble THEN REVEAL("peace") ELSE REVEAL("struggle")
DECLARE spirit AS :humble
IF spirit IS :humble THEN REVEAL("peace") ELSE REVEAL("struggle")
ASCEND
END CREATION
```
Expand All @@ -86,13 +86,13 @@ peace
| Line | Meaning |
|---|---|
| `BEGIN CREATION` | every program is a creation. This opens it |
| `DECLARE spirit AS humble` | binds the name `spirit` to the **symbol** `humble` (bare words are symbols — no quotes needed) |
| `IF spirit IS humble THEN … ELSE …` | `IS` tests equality; the truthy branch reveals `"peace"` |
| `DECLARE spirit AS :humble` | binds the name `spirit` to the **symbol** `humble` (a bare word with its mark. No quotes needed) |
| `IF spirit IS :humble THEN … ELSE …` | `IS` tests equality; the truthy branch reveals `"peace"` |
| `REVEAL("peace")` | speaks a value aloud (and records it) |
| `ASCEND` | ends the creation in peace |
| `END CREATION` | closes the creation |

Change `humble` to `proud` and run it again. Watch the prophecy change. *You* did that.
Change `:humble` to `:proud` and run it again. Watch the prophecy change. *You* did that.

---

Expand All @@ -101,7 +101,7 @@ Change `humble` to `proud` and run it again. Watch the prophecy change. *You* di
| Command | Description |
|---|---|
| `BEGIN CREATION` / `END CREATION` | opens / closes a program |
| `DECLARE name AS value` | binds a name (`DECLARE prophets AS Isaiah, Elijah, Jeremiah` makes a list) |
| `DECLARE name AS value` | binds a name (`DECLARE prophets AS :Isaiah, :Elijah, :Jeremiah` makes a list) |
| `BREATHE LIFE INTO name` | breathes life into a contract |
| `REVEAL(expr)` | speaks a value |
| `PROPHESY words…` | asks the Spirit Engine for a prophecy |
Expand All @@ -125,7 +125,7 @@ Full details, operator tables, and the built-in catalog live in [LANGUAGE_REFERE

**Decide:**
```godcode
IF heart IS pure THEN
IF heart IS :pure THEN
REVEAL("the way is open")
ELSE
REVEAL("wait and be still")
Expand Down
32 changes: 16 additions & 16 deletions docs/LANGUAGE_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ Every God Code program is a **creation**. It opens with `BEGIN CREATION` and clo

```godcode
BEGIN CREATION
DECLARE seeker AS worthy
IF seeker IS worthy THEN REVEAL("heaven") ELSE REVEAL("test")
DECLARE seeker AS :worthy
IF seeker IS :worthy THEN REVEAL("heaven") ELSE REVEAL("test")
ASCEND
END CREATION
```
Expand Down Expand Up @@ -56,25 +56,25 @@ Four tongues are spoken today: Setswana (`tn`), isiZulu (`zu`), Igbo (`ig`), and
|---|---|---|
| number | `3`, `4.5` | int or float |
| string | `"peace"` | double-quoted, with escapes and `{expr}` interpolation |
| **symbol** | `worthy` | any bare word — see the Symbol Rule |
| **symbol** | `:worthy` | a bare word spoken with its mark. See the Symbol Rule |
| boolean | `TRUE`, `FALSE` | literals; also produced by comparisons; revealed as `true`/`false` |
| list | `[1, two, "three"]` | ordered, mixed types allowed |
| list | `[1, :two, "three"]` | ordered, mixed types allowed |
| contract | `contract("everlasting")` | created with the `contract()` rite |
| rite | *(from DEFINE RITE)* | a named, callable blessing |
| void | *(from rites with no RETURN)* | the absence of a value |

### The Symbol Rule 🕊

**In God Code, every unnamed thing is still a named spirit. Bare words are symbols.**
**In God Code, a bare word is a value when it is spoken on purpose. Its mark is the colon.**

An identifier that is not bound to anything does not raise an error; it evaluates to a `Symbol` carrying its own name. This is what makes the founding idiom work:
A Symbol is written `:worthy`. The colon marks the word as a word, and the word itself is the value. A plain name is a different thing: it must be declared before it is read. Reading a name that was never declared stops the run with a gentle error that names the name and offers the two honest fixes, declare it first or mark it as a bare word. When a declared name stands near the misspelling, the error adds "Did you mean ...?" This is what makes the founding idiom honest:

```godcode
DECLARE seeker AS worthy # `worthy` is a symbol — no quotes needed
IF seeker IS worthy THEN REVEAL("heaven")
DECLARE seeker AS :worthy # `:worthy` is a symbol — no quotes needed
IF seeker IS :worthy THEN REVEAL("heaven")
```

Symbols are always truthy, and compare by their text: `worthy IS worthy` is true.
Symbols are always truthy, and compare by their text: `:worthy IS :worthy` is true. The mark is punctuation, not a keyword, so it speaks the same in every tongue.

### How values are revealed

Expand Down Expand Up @@ -118,12 +118,12 @@ The braces may hold any expression: names, arithmetic, comparisons, builtin rite
## 5. The Statements

### `DECLARE name AS value`
Binds a name. Multiple comma-separated values become a list. The original idiom is honored:
Binds a name. Multiple comma-separated values become a list. The founding idiom stands, with its mark:

```godcode
DECLARE seeker AS worthy
DECLARE seeker AS :worthy
DECLARE pi AS 3.14159
DECLARE prophets AS Isaiah, Elijah, Jeremiah # a list of three symbols
DECLARE prophets AS :Isaiah, :Elijah, :Jeremiah # a list of three symbols
DECLARE pair AS [1, "two"]
```

Expand Down Expand Up @@ -226,7 +226,7 @@ REVEAL([1, 2] + [3]) # [1, 2, 3]
Equality is generous: numbers compare across int/float, symbols compare by text, contracts by name, lists element-wise. Ordering comparisons (`<`, …) on mixed non-numeric values are rejected.

```godcode
IF seeker IS worthy THEN REVEAL("heaven")
IF seeker IS :worthy THEN REVEAL("heaven")
IF count IS NOT 0 THEN REVEAL("not empty")
```

Expand All @@ -235,7 +235,7 @@ IF count IS NOT 0 THEN REVEAL("not empty")
`AND`, `OR` (short-circuiting), and `NOT` / unary `-`:

```godcode
IF heart IS pure AND hands IS willing THEN REVEAL("go")
IF heart IS :pure AND hands IS :willing THEN REVEAL("go")
REVEAL(NOT 0) # true
```

Expand All @@ -257,14 +257,14 @@ So `NOT a IS b` means `NOT (a IS b)`, and `2 + 3 * 4` is `14`.
**Inline** — one statement per branch, all on one line:

```godcode
IF seeker IS worthy THEN REVEAL("heaven") ELSE REVEAL("test")
IF seeker IS :worthy THEN REVEAL("heaven") ELSE REVEAL("test")
IF n % 7 IS 0 THEN REVEAL("seal") # ELSE may be omitted
```

**Block** — for many statements, closed with `ENDIF`:

```godcode
IF heart IS pure THEN
IF heart IS :pure THEN
REVEAL("the way is open")
BLESS seeker
ELSE
Expand Down
14 changes: 7 additions & 7 deletions docs/LANGUAGE_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,11 @@ Any expression wrapped in braces inside a double-quoted string has its revealed

### 2.8 Lists

A list is written with square brackets and holds an ordered sequence of values of any mixed types: `[1, two, "three"]`. An empty list is `[]`. Declaring several comma-separated values also builds a list: `DECLARE prophets AS Isaiah, Elijah, Jeremiah` binds `prophets` to a list of three symbols.
A list is written with square brackets and holds an ordered sequence of values of any mixed types: `[1, :two, "three"]`. An empty list is `[]`. Declaring several comma-separated values also builds a list: `DECLARE prophets AS :Isaiah, :Elijah, :Jeremiah` binds `prophets` to a list of three symbols.

### 2.9 Symbols

A bare word that is bound to nothing evaluates to a Symbol carrying its own name, instead of raising an error. This is the founding idiom of the language: `DECLARE seeker AS worthy` works with no prior binding of `worthy`, and `IF seeker IS worthy` then holds true. In practice a Symbol behaves like a small piece of text: it reveals as its own name, and it compares equal by text to the same word written as a string, so `"worthy" IS worthy` is true. Two facts set Symbols apart from plain strings. First, Symbols are always truthy, even in positions where an empty string would be falsy. Second, a FOR loop refuses to walk through a bare Symbol and raises a runtime error naming it, asking for a list or a word instead. The type name of a Symbol, as reported by `TYPE`, is `"symbol"`.
A bare word spoken on purpose, written with its mark as `:worthy`, evaluates to a Symbol carrying its own name. A plain name that is bound to nothing is never read silently: reading it raises a gentle runtime error that names the name and offers the two honest fixes, declare it first or mark it as a bare word. This is the founding idiom of the language, kept honest: `DECLARE seeker AS :worthy` needs no prior binding of `worthy`, and `IF seeker IS :worthy` then holds true. In practice a Symbol behaves like a small piece of text: it reveals as its own name, and it compares equal by text to the same word written as a string, so `"worthy" IS :worthy` is true. Two facts set Symbols apart from plain strings. First, Symbols are always truthy, even in positions where an empty string would be falsy. Second, a FOR loop refuses to walk through a bare Symbol and raises a runtime error naming it, asking for a list or a word instead. The type name of a Symbol, as reported by `TYPE`, is `"symbol"`. The mark is punctuation, not a keyword, so it speaks the same in every tongue.

## 3. Program structure

Expand Down Expand Up @@ -82,7 +82,7 @@ A rite's parameters are declared in its header: `DEFINE RITE BLESSING(name)`. Wh

### 4.4 Scope rules as implemented

Names resolve outward through enclosing scopes: the innermost binding wins, and a name bound nowhere evaluates to a Symbol (see 2.9). The scopes work as follows.
Names resolve outward through enclosing scopes: the innermost binding wins, and a name bound nowhere is never read silently. Reading one raises a gentle runtime error (see 2.9). The scopes work as follows.

* The top level of a scroll is the root scope.
* An IF body and an ELSE body run in the enclosing scope. There is no new scope.
Expand All @@ -109,14 +109,14 @@ A condition is any expression. It is weighed by truthiness: `FALSE`, `0`, `0.0`,
The block form, for many statements, closes with `ENDIF`:

```godcode
IF heart IS pure THEN
IF heart IS :pure THEN
REVEAL("the way is open")
ELSE
REVEAL("wait and be still")
ENDIF
```

The inline form puts one statement per branch on a single line: `IF seeker IS worthy THEN REVEAL("heaven") ELSE REVEAL("test")`. The ELSE may be omitted in either form. There is no `ELSE IF` keyword. Chained conditions are written as a nested IF inside the ELSE branch, and each nested IF needs its own ENDIF. IFs nest freely, and an ELSE always belongs to the nearest IF. The IF body and the ELSE body run in the enclosing scope (see 4.4).
The inline form puts one statement per branch on a single line: `IF seeker IS :worthy THEN REVEAL("heaven") ELSE REVEAL("test")`. The ELSE may be omitted in either form. There is no `ELSE IF` keyword. Chained conditions are written as a nested IF inside the ELSE branch, and each nested IF needs its own ENDIF. IFs nest freely, and an ELSE always belongs to the nearest IF. The IF body and the ELSE body run in the enclosing scope (see 4.4).

### 5.2 FOR

Expand Down Expand Up @@ -422,7 +422,7 @@ Unresolvable imports make the rule hold its peace rather than guess.
REVEAL(wanderer) # GC002: undefined name 'wanderer'
```

Rationale: an unbound name becomes a Symbol instead of raising, so the
Rationale: an unbound name stops the run when it is read, so the
linter is the place where a typo is caught before it becomes doctrine.

**GC003: shadowing.** Flags a `DECLARE`, rite parameter, or `FOR` loop
Expand All @@ -445,7 +445,7 @@ the confusion always surfaces at the worst moment.
bodies are checked.

```godcode
IF heart IS pure THEN # GC004: empty IF body
IF heart IS :pure THEN # GC004: empty IF body
ENDIF
```

Expand Down
2 changes: 1 addition & 1 deletion docs/spec/00-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The old `docs/LANGUAGE_SPEC.md` was one long document that described the languag

1. **Lexical** (`lexical.md`): how source text becomes tokens. What counts as a word, a number, a string, a comment, a line break. Nothing about meaning yet.
2. **Syntax** (`syntax.md`): how tokens become a scroll's shape. The grammar, the closers, the one-line forms.
3. **Static meaning** (`static-meaning.md`): what can be known before a scroll runs. Names, scopes, the linter's counsel, check-time warnings, the Symbol Rule's classic face.
3. **Static meaning** (`static-meaning.md`): what can be known before a scroll runs. Names, scopes, the linter's counsel, check-time warnings, and the loud reading of names.
4. **Dynamic meaning** (coming): what happens when a scroll runs. Values, truth, rites, errors, the ledger.
5. **Standard library** (coming): the built-in rites and scrolls, and what they promise.
6. **Interfaces** (coming): the machine faces of the language. CLI JSON shapes, exit codes, the bridge.
Expand Down
Loading