repo: add gitignore, photo-enhance review notes, and pi plans

- .gitignore: exclude VM state files (ephemeral, contain keys/IDs)
  and untrack the three existing state files already in history
- photo-enhance-review.md: findings review that drove the pipeline redesign
- pi/plans/: gt language planning documents

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

8 files changed, 266 insertions, 0 deletions

diff --git a/pi/plans/gt-boolean-numeric-coercion.md b/pi/plans/gt-boolean-numeric-coercion.md
new file mode 100644
index 0000000..3263302
--- /dev/null
+++ b/pi/plans/gt-boolean-numeric-coercion.md
@@ -0,0 +1,32 @@
+# GT – Boolean‑to‑Number Coercion (RPN) Implementation Plan
+
+## Overview
+The GT REPL will support arithmetic operations that involve booleans by automatically converting `true` → `1` and `false` → `0`.  This allows expressions such as `5 3 == 1 +` to evaluate correctly without explicit conversion steps.
+
+---
+
+## Examples
+The following REPL interactions illustrate how booleans are automatically coerced to numbers (`true` → 1, `false` → 0) and can participate in arithmetic operations.
+
+```
+> 5 3 == 1 +      # → 2
+> 5 3 > 10 +      # → 11
+> 0 false +       # → 0
+> true 2 *        # → 2
+> 9 3 > 4 5 < +   # → 2
+```
+
+In each case the boolean result is shown as `true`/`false` when printed, but when used as an operand it behaves as the corresponding numeric value.
+
+## Plan
+1. Extend the internal stack/value type to store a variant that can be either a `float64` or a `bool`.
+2. Add a helper `toNumber(v Value) float64` that returns `1` for `true`, `0` for `false`, or the numeric value otherwise.
+3. Update each arithmetic operator implementation (`Add`, `Subtract`, `Multiply`, `Divide`, `Modulo`, `Power`) to call `toNumber` on both operands before performing the calculation.
+4. Implement Boolean operators (`gt`, `lt`, `gte`, `lte`, `eq`, `neq`) to push a boolean `Value` onto the stack.
+5. Modify `Show` to display boolean values as `true`/`false` while still allowing them to be used in arithmetic via the coercion helper.
+6. Write unit tests covering mixed boolean‑numeric expressions, e.g. `5 3 == 1 +` → `2`, `0 false +` → `0`, `true 2 *` → `2`.
+7. Update `README.md` and godoc comments to document the automatic coercion rule and provide usage examples.
+8. Add the new test suite to CI, ensure it runs on every build, and bump the project version (e.g., to `v0.2.2`).
+
+---
+*This plan is stored at* `/home/paul/.pi/plans/gt-boolean-numeric-coercion.md` *and serves as the reference for any upcoming tasks.*
\ No newline at end of file
diff --git a/pi/plans/gt-boolean-operators-both-forms.md b/pi/plans/gt-boolean-operators-both-forms.md
new file mode 100644
index 0000000..d8c287b
--- /dev/null
+++ b/pi/plans/gt-boolean-operators-both-forms.md
@@ -0,0 +1,33 @@
+# GT – Boolean Operators (RPN) – Support Symbolic Forms
+
+## Rationale
+- The original design used the word tokens `gt`, `lt`, `gte`, `lte`, `eq`, `neq` because they are unambiguous when typed after the `rpn` command and avoid any shell‑level redirection issues (e.g., `>` can be interpreted by the shell if the user does not quote the expression).
+- Users coming from other RPN calculators or from infix languages naturally expect the symbolic forms (`>`, `<`, `>=`, `<=`, `==`, `!=`).  Providing both forms improves discoverability and ergonomics without breaking existing scripts that already use the word forms.
+- Adding symbolic aliases is straightforward: the `OperatorRegistry` already maps token strings to handler functions.  We can register the symbols as synonyms for the same implementation used by the word tokens.
+
+---
+## Example REPL syntax (both word and symbol forms)
+```text
+# Word forms
+> rpn 5 3 gt        # → true
+> rpn 7 7 eq        # → true
+> rpn a 5 3 gt =    # store true in variable "a"
+
+# Symbolic forms (quoted to avoid shell redirection if needed)
+> rpn 5 3 >          # → true
+> rpn 7 7 ==         # → true
+> rpn a 5 3 > =      # store true in variable "a"
+```
+Both `gt` and `>` (as well as the other operators) evaluate to the same result.
+
+---
+## Plan:
+1. Extend `OperatorRegistry` to register symbolic aliases: map `>` to the same handler as `gt`, `<` to `lt`, `>=` to `gte`, `<=` to `lte`, `==` to `eq`, and `!=` to `neq`.
+2. Implement the six Boolean operator handlers (`gt`, `lt`, `gte`, `lte`, `eq`, `neq`) if not already present, using the existing `Number` comparison methods.
+3. Ensure the RPN parser treats both word and symbol tokens as standard operators (no changes to tokenization needed).
+4. Add unit tests covering both forms for each operator, checking numeric and mixed‑type comparisons.
+5. Update documentation (`README.md` and godoc comments) to list both the word and symbolic tokens with usage examples.
+6. Update the CI pipeline to run the new tests and bump the project version (e.g., `v0.2.1`).
+
+---
+*This plan is stored at* `/home/paul/.pi/plans/gt-boolean-operators-both-forms.md` *and serves as the reference for any upcoming tasks.*
\ No newline at end of file
diff --git a/pi/plans/gt-boolean-operators-rpn-only-example.md b/pi/plans/gt-boolean-operators-rpn-only-example.md
new file mode 100644
index 0000000..4b55a75
--- /dev/null
+++ b/pi/plans/gt-boolean-operators-rpn-only-example.md
@@ -0,0 +1,30 @@
+# GT – Boolean Operators (RPN‑Only) – Example Syntax
+
+## Overview
+This plan adds a full set of Boolean comparison operators to the **gt** REPL, **exclusively** in RPN (postfix) form.  The operators will be registered in the RPN handler, the RPN value system will be extended to hold booleans, and the change will be documented with usage examples.
+
+---
+## Example REPL syntax
+```text
+> rpn 5 3 gt        # → true   (5 > 3)
+> rpn 3 5 lt        # → true   (3 < 5)
+> rpn 4 4 gte       # → true   (4 >= 4)
+> rpn 2 2 lte       # → true   (2 <= 2)
+> rpn 7 7 eq        # → true   (7 == 7)
+> rpn 5 7 neq       # → true   (5 != 7)
+> rpn 10 0 gt       # → false  (10 > 0 is false) 
+
+# Variable assignment with a Boolean result
+> rpn a 5 3 gt =    # stores true in variable "a"
+> rpn a              # → true
+```
+The operators `gt`, `lt`, `gte`, `lte`, `eq`, and `neq` are the only new tokens; all other REPL functionality remains unchanged.
+
+---
+## Plan
+1. Extend the internal RPN value type to represent booleans alongside numbers.
+2. Implement the six postfix Boolean operators (`gt`, `lt`, `gte`, `lte`, `eq`, `neq`) and register them in the RPN operator registry.
+3. Add unit tests and update documentation (godoc and README) with the example syntax above.
+
+---
+*This plan is stored at* `/home/paul/.pi/plans/gt-boolean-operators-rpn-only-example.md` *and serves as the reference for any future tasks.*
\ No newline at end of file
diff --git a/pi/plans/gt-boolean-operators-rpn-only.md b/pi/plans/gt-boolean-operators-rpn-only.md
new file mode 100644
index 0000000..9d9f641
--- /dev/null
+++ b/pi/plans/gt-boolean-operators-rpn-only.md
@@ -0,0 +1,31 @@
+# GT – Boolean Operators (RPN Only) Implementation Plan
+
+## Overview
+The **gt** project currently evaluates arithmetic and percentage expressions via a REPL that supports RPN (postfix) syntax.  To make the language more expressive we will add a full set of Boolean comparison operators, but **only** in the existing RPN form.  No infix parsing will be introduced.
+
+## Goals
+- Provide the six common comparison operators as postfix tokens:
+  - `gt`  → `>`  (greater than)
+  - `lt`  → `<`  (less than)
+  - `gte` → `>=` (greater‑than‑or‑equal)
+  - `lte` → `<=` (less‑than‑or‑equal)
+  - `eq`  → `==` (equal)
+  - `neq` → `!=` (not equal)
+- Extend the RPN stack to store boolean values alongside numbers.
+- Ensure the new operators work with all numeric types supported by the existing calculator (int, float, unsigned) and handle edge cases (NaN, Inf, division‑by‑zero). 
+- Add thorough unit tests and update documentation.
+- Integrate the changes into the CI pipeline and bump the project version.
+
+## Plan:
+1. Extend the REPL value system to support a boolean type for RPN stack values.
+2. Implement the postfix operator `gt` (greater‑than) as an RPN operator.
+3. Implement the postfix operator `lt` (less‑than) as an RPN operator.
+4. Implement the postfix operator `gte` (greater‑than‑or‑equal) as an RPN operator.
+5. Implement the postfix operator `lte` (less‑than‑or‑equal) as an RPN operator.
+6. Implement the postfix operator `eq` (equal) as an RPN operator.
+7. Implement the postfix operator `neq` (not‑equal) as an RPN operator.
+8. Register all new operators in the RPN operator registry.
+9. Update the existing `RPNHandler` to recognize and dispatch the new operator symbols.
+10. Add unit tests for each new operator covering numeric types, mixed‑type comparisons, and edge cases (NaN, Inf, zero divisor).
+11. Update godoc comments for each operator and extend `README.md` with a table of Boolean operators and RPN usage examples.
+12. Modify the CI pipeline to run the new tests, bump the module version to the next minor (e.g., `v0.2.0`), and add a changelog entry documenting the new Boolean operators.
diff --git a/pi/plans/gt-boolean-operators-syntax-examples.md b/pi/plans/gt-boolean-operators-syntax-examples.md
new file mode 100644
index 0000000..9751bb2
--- /dev/null
+++ b/pi/plans/gt-boolean-operators-syntax-examples.md
@@ -0,0 +1,52 @@
+# GT – Boolean Operators (RPN) – Syntax Examples
+
+## Overview
+We are extending the **gt** REPL with a full set of Boolean comparison operators, usable **only** in RPN (postfix) form.  The operators will be available in two token styles:
+- **Word form** – `gt`, `lt`, `gte`, `lte`, `eq`, `neq`
+- **Symbolic form** – `>`, `<`, `>=`, `<=`, `==`, `!=`
+
+Both forms map to the same underlying implementation, allowing users to pick the style they prefer while keeping backward compatibility.
+
+---
+## Example REPL syntax
+```text
+# Word forms
+> rpn 5 3 gt        # → true   (5 > 3)
+> rpn 7 7 eq        # → true   (7 == 7)
+> rpn a 10 2 lt =    # store true in variable "a"
+> rpn a               # → true
+
+# Symbolic forms (quote the expression if your shell would interpret the symbols)
+> rpn 5 3 >          # → true
+> rpn 7 7 ==         # → true
+> rpn a 10 2 < =      # store true in variable "a"
+> rpn a               # → true
+
+# Mixed usage across the same session
+> rpn 8 4 gte        # → true
+> rpn 8 4 >=         # → true
+> rpn 8 4 neq        # → false
+> rpn 8 4 !=         # → false
+```
+All operators push a **boolean** (`true`/`false`) onto the stack, which can be stored in variables or inspected with `show`.
+
+---
+## Goals
+1. Provide the six Boolean operators in both word and symbolic token forms.
+2. Extend the RPN value system to store booleans alongside numbers.
+3. Ensure existing REPL behavior (stack, variables, commands) stays unchanged.
+4. Document the syntax with clear examples (as shown above).
+5. Add comprehensive unit tests and CI verification.
+
+---
+## Plan
+1. Implement the Boolean operator handlers (`gt`, `lt`, `gte`, `lte`, `eq`, `neq`) using the `Number.Compare` method and push a boolean onto the stack.
+2. Register symbolic aliases (`>`, `<`, `>=`, `<=`, `==`, `!=`) in the `OperatorRegistry` as synonyms for the word forms.
+3. Extend the `Stack` (or introduce a new stack type) to hold a `Value` that can represent either a `float64` or a `bool`.
+4. Update `Show` to display booleans as `true`/`false` while preserving numeric formatting.
+5. Write unit tests for each operator, covering numeric, mixed‑type, and edge cases (NaN, Inf, zero).
+6. Add documentation to `README.md` and godoc comments, including the example syntax block above.
+7. Update the CI pipeline to run the new tests, bump the module version (e.g., `v0.2.1`), and generate a changelog entry.
+
+---
+*This plan is stored at* `/home/paul/.pi/plans/gt-boolean-operators-syntax-examples.md` *and serves as the reference for any upcoming tasks.*
\ No newline at end of file
diff --git a/pi/plans/gt-boolean-operators.md b/pi/plans/gt-boolean-operators.md
new file mode 100644
index 0000000..6518599
--- /dev/null
+++ b/pi/plans/gt-boolean-operators.md
@@ -0,0 +1,37 @@
+# GT – Boolean Operators Implementation Plan
+
+## Overview
+The **gt** project currently provides the `>` (greater‑than) operator for numeric comparisons.  To make the language richer and more expressive, we want to add a full suite of boolean comparison operators (e.g. `<`, `>=`, `<=`, `==`, `!=`).  These operators will be usable both from the REPL and in RPN scripts, and will follow the same design patterns as the existing `gt` implementation.
+
+## Goals
+1. **Feature completeness** – support the most common boolean operators:
+   - `>`  (greater than) – already present
+   - `<`  (less than)
+   - `>=` (greater‑than‑or‑equal)
+   - `<=` (less‑than‑or‑equal)
+   - `==` (equal)
+   - `!=` (not equal)
+2. **Unified operator model** – introduce an interface/registry so that new operators can be added with minimal friction.
+3. **REPL integration** – allow infix notation for all operators, with helpful auto‑completion and syntax highlighting.
+4. **RPN integration** – provide postfix forms (e.g. `gt`, `lt`, `gte`, `lte`, `eq`, `neq`).
+5. **Documentation** – update godoc, README, and example snippets for each operator.
+6. **Testing & quality** – comprehensive unit tests, property‑based tests for edge cases (different numeric types, nil handling, overflow), and benchmarks.
+7. **CI/Release** – ensure the CI pipeline verifies the new operators and bump the module version appropriately.
+
+## Plan
+1. **Design a generic Operator interface** and a registry that maps symbols (`>`, `<`, `>=`, …) and RPN names (`gt`, `lt`, …) to concrete implementations.
+2. **Implement operator structs** (`LessThan`, `GreaterThanOrEqual`, `LessThanOrEqual`, `Equal`, `NotEqual`) that satisfy the interface, reusing existing comparison logic where possible.
+3. **Update the REPL parser** to recognise the new symbols, perform tokenisation, and dispatch to the registry.
+4. **Extend the RPN parser** to support the new postfix operator tokens and map them to the same implementations.
+5. **Add unit tests** for each operator covering:
+   - Various numeric types (int, float, unsigned).
+   - Mixed‑type comparisons.
+   - Edge cases (NaN, overflow, nil values).
+   - Error handling for unsupported types.
+6. **Write benchmarks** comparing the performance of the existing `gt` operator with the new implementations.
+7. **Document the operators** in Godoc comments, update `README.md` with a comparison table, and add usage examples for REPL and RPN.
+8. **Integrate with CI** – add linting, run the new test suite, and verify that the binary builds correctly.
+9. **Version bump** – plan a minor version bump (e.g., `v0.2.0`) and prepare a changelog entry summarising the new boolean operators.
+
+---
+*This plan is stored at* `/home/paul/.pi/plans/gt-boolean-operators.md` *and serves as the reference for upcoming task creation.*
\ No newline at end of file
diff --git a/pi/plans/gt-plan.md b/pi/plans/gt-plan.md
new file mode 100644
index 0000000..7cf5a38
--- /dev/null
+++ b/pi/plans/gt-plan.md
@@ -0,0 +1,29 @@
+# Project gt – Gap Analysis and Improvement Plan
+
+## Overall Picture & Goals
+
+- Provide a reliable, well‑documented command‑line percentage calculator with RPN and rational number support.
+- Deliver a smooth developer experience: clear contribution guidelines, automated CI/CD, and proper versioning.
+- Ensure the codebase follows Go best practices, has comprehensive tests, and ships a stable binary.
+
+Plan:
+
+1. **Fix CI build step** – Update GitHub Actions workflow to build the correct binary path (`./cmd/gt` instead of `./cmd/perc`).
+2. **Update `go.mod` Go version** – Change the `go` directive to a supported version (e.g. `go 1.22`) to match the CI Go version.
+3. **Add `CONTRIBUTING.md`** – Provide guidelines for building, testing, using `mage`, and submitting pull requests.
+4. **Expand README** – Include concrete examples for rational‑mode (`rat on/off/toggle`) and hyper‑operators (`[+]`, `[*]`, etc.).
+5. **Add badges to README** – CI status, test coverage, and Go Report Card badges.
+6. **Add end‑to‑end CLI tests** – Test the built binary for commands like `gt version`, `gt 20% of 150`, and `gt help`.
+7. **Add REPL command tests** – Cover built‑in commands (`help`, `clear`, `quit`, `rat`) and variable management (`vars`, `clear`, `name d`).
+8. **Add `.goreleaser.yml`** – Set up automated release builds and GitHub releases.
+9. **Implement version bump workflow** – Use the `increment-version-and-push` skill to bump the version, tag, and push.
+10. **Document variable management** – Add a dedicated README section describing `vars`, `clear`, and variable deletion commands.
+11. **Update Magefile** – Add shortcuts for build, test, lint, and release.
+12. **Add missing Go documentation** – Ensure all exported functions in the REPL package (`NewREPL`, `RunREPL`, `executor`, `defaultExecutor`, `defaultCompleter`, `defaultGetCommandDescription`) have godoc comments.
+13. **Add go vet step to CI workflow** – Include a `go vet ./...` step in the GitHub Actions CI configuration to catch static analysis issues.
+14. **Add godoc comments for exported TTYChecker methods (IsTTY, EnsureTTY)**.
+15. **Add godoc comments for exported SignalHandler methods (Start, Stop)**.
+16. **Add SPDX license headers to all .go source files**.
+17. **Wrap errors with %w where appropriate for better error chaining**.
+18. **Design a nice logo for the gt project (e.g., stylized 'gt' with calculator motif)**.
+
diff --git a/pi/plans/gt-rpn-prefix-doc.md b/pi/plans/gt-rpn-prefix-doc.md
new file mode 100644
index 0000000..4af608e
--- /dev/null
+++ b/pi/plans/gt-rpn-prefix-doc.md
@@ -0,0 +1,22 @@
+# GT – RPN Prefix Optional – Documentation & Tests Plan
+
+## Background
+The REPL currently supports evaluating RPN expressions in three ways:
+1. Explicit `rpn` (or `calc`) prefix – `rpn 3 4 +`
+2. Implicit RPN when the input contains spaces – `3 4 +`
+3. Incremental operator handling – entering a single operator after previous tokens.
+
+Because of the second case, users can omit the `rpn` prefix entirely and still get RPN evaluation. This behavior is not clearly documented, which can lead to confusion.
+
+## Goal
+Make it explicit in the user‑facing documentation that the `rpn` prefix is optional and that any space‑separated expression is treated as RPN. Add unit tests to guard against regression.
+
+## Plan
+1. **Update README.md** – add a section titled *"RPN usage (prefix optional)"* with clear examples showing both prefixed and unprefixed forms.
+2. **Update godoc for `RPNHandler`** – clarify in the handler comment that it treats space‑separated inputs as RPN when no built‑in command matches.
+3. **Add unit tests** in `internal/repl/handlers_test.go` (or a new test file) that verify expressions like `"3 4 +"` and `"rpn 3 4 +"` produce the same result.
+4. **Ensure CI runs the new tests** – modify any test scripts if needed to include the new test file.
+5. **Add a changelog entry** indicating the documentation update and added tests (e.g., `v0.2.2 – clarified RPN prefix optional`).
+
+---
+*Plan file stored at* `/home/paul/.pi/plans/gt-rpn-prefix-doc.md` *for reference.*
\ No newline at end of file