Add set literal documentation (Phase 7 of #164)

[andreasronge]

Summary

Add set literal documentation to PTC-Lisp specification and LLM guide, completing Phase 7 of the set literal epic (#164). This enables LLMs and developers to understand and use the new #{...} syntax.

Context

Architecture reference: Set Literal Implementation Plan - Section 5.8 (Phase 8: Documentation)
Dependencies: Phase 6 (#177) - Formatter support (completed)
Related issues: Epic #164

Current State

Based on codebase analysis:

• docs/ptc-lisp-specification.md line 212 states: "Not supported: Sets (#{}), Lists ('())"
• docs/ptc-lisp-llm-guide.md Data Types section lists vectors and maps but no sets
• Set literals are fully implemented (parser, analyzer, evaluator, runtime, formatter) but undocumented

Acceptance Criteria

• Remove "Sets (#{})" from "Not supported" line in specification (line 212)
• Add Section 3.8 "Sets" after Section 3.7 (Maps) in specification
• Update Section 8.6 (Type Predicates) to add set? predicate
• Update Section 14 (Grammar) to add set production rule AND add set to expression alternatives
• Add sets to Data Types section in LLM guide (inside <!-- PTC_PROMPT_START --> markers)
• Add set functions to Core Functions section in LLM guide
• Existing tests pass
• Documentation follows existing format/style conventions

Implementation Hints

Files to modify:

• docs/ptc-lisp-specification.md - Add Section 3.8, update grammar, update type predicates, remove from "Not supported"
• docs/ptc-lisp-llm-guide.md - Add sets to data types and functions reference (within PTC_PROMPT_START/PTC_PROMPT_END markers)

Content to add:

Section 3.8 Sets (for specification.md, after Section 3.7 Maps)

### 3.8 Sets

Unordered collections of unique values:

```clojure
#{}                    ; empty set
#{1 2 3}               ; set with 3 elements
#{1 1 2}               ; duplicates silently removed: equivalent to #{1 2}
#{:a :b :c}            ; keyword set

Sets are unordered - iteration order is not guaranteed.

Set operations:

Function	Signature	Description
set?	(set? x)	Returns true if x is a set
set	(set coll)	Convert collection to set
count	(count #{1 2})	Returns element count
empty?	(empty? #{})	Returns true if empty
contains?	(contains? #{1 2} 1)	Membership test (O(1))

Collection operations on sets: map, filter, remove, mapv work on sets but return vectors (not sets).

(map inc #{1 2 3})           ; returns vector [2 3 4] (order undefined)
(filter odd? #{1 2 3 4})     ; returns vector [1 3] (order undefined)

Not supported for sets: first, last, nth, sort, sort-by (sets are unordered).

### Grammar addition (Section 14)

Add to the EBNF grammar:

1. Add new production rule:
```ebnf
set         = "#{" expression* "}" ;

2. Update expression alternatives to include set:

expression  = literal
            | symbol
            | keyword
            | vector
            | set
            | map
            | list-expr ;

Type Predicates update (Section 8.6)

Add row to the type predicates table:

| `set?` | Is set? |

LLM guide additions (within PTC_PROMPT_START markers)

Data Types section:

#{1 2 3}               ; sets (unordered, unique values)

Core Functions section (add new "Sets" subsection):

; Sets
(set? x)               ; is x a set?
(set [1 2 2])          ; convert to set: #{1 2}
(contains? #{1 2} 1)   ; membership: true
(count #{1 2 3})       ; count: 3
(empty? #{})           ; empty check: true

Patterns to follow:

• Section 3.7 (Maps) structure for Section 3.8
• Existing function table format in Section 8.6
• Data type list format in LLM guide

Edge cases to consider:

• Ensure "Not supported" line only removes sets, keeps Lists ('())
• Grammar section: set must appear BEFORE map in expression alternatives (matches parser combinator ordering)

Test Plan

Manual verification:

• Grep for "Not supported" confirms sets removed
• Section numbering is correct (3.8 after 3.7)
• Grammar section includes set production and updated expression rule

Automated:

• Run mix docs to ensure documentation compiles
• Existing tests pass (mix test)

Out of Scope

• Adding new set operations beyond what's implemented (union, intersection, etc.)
• Updating architecture.md (not needed for this change)
• Creating new test files (tests exist from prior phases)

Documentation Updates

• docs/ptc-lisp-specification.md - Primary update
• docs/ptc-lisp-llm-guide.md - Secondary update

[andreasronge]

Issue Review: Add set literal documentation (Phase 7 of #164)

Summary: Well-specified documentation issue for completing set literal support. Minor corrections needed to implementation hints, now fixed.

Pre-Review Checks:

• Codebase health: pass (1010 tests, 0 failures)
• Higher-priority blockers: [From PR #175] Add test coverage for remove, mapv, empty?, and count on sets #176 and [From PR #172] Split eval_test.exs into multiple files #173 exist (from-pr-review, tech-debt) but are non-blocking nice-to-haves
• Issue claims verified: yes - line 212 confirms "Not supported: Sets", implementation confirmed in parser/analyzer/evaluator/runtime/formatter

Analysis:

1. Should This Be Done?: Yes. Sets are fully implemented but undocumented - LLMs will see outdated "Not supported" message causing confusion.

2. Simplifications: None needed. Documentation-only change with clear scope.

3. Codebase Research: Verified:

   • parser.ex:134-139, 169 - set combinator implemented
   • eval.ex:88 - set evaluation implemented
   • runtime.ex:30,33,39,48 - map/filter/remove/mapv work on sets (return vectors)
   • runtime.ex:65-67 - first/last/nth only work on lists (correct)
   • formatter.ex:35 - set formatting implemented

4. Reuse Opportunities: Follows existing Section 3.7 (Maps) pattern for Section 3.8.

5. Refactoring Needs: None.

6. Edge Cases:

   • Grammar update needs TWO changes: production rule AND expression alternatives (now documented)
   • LLM guide updates must be within PTC_PROMPT_START markers (now documented)

7. Issue Scope: Appropriate for one PR. Focused on two files.

8. Test Plan: Adequate - manual verification + existing test suite.

9. Solution Outline: Clear implementation hints with exact content to add.

Technical Issues Found & Fixed:

• Original issue stated "Not supported for sets: first, last, nth, map, filter, sort" but map/filter/remove DO work on sets (returning vectors). Fixed to match actual implementation.
• Added clarity that grammar needs both production rule AND expression alternatives update
• Added note about PTC_PROMPT_START markers in LLM guide

Recommended Labels: ready-for-implementation, claude-approved, documentation

Verdict: Ready for implementation

[andreasronge]

@claude Please implement this issue.

Key references:

• Read the set literal implementation plan: docs/ptc-lisp-set-literal-plan.md (Section 5.8)
• The issue body contains detailed implementation hints with exact content to add

Files to modify:

• docs/ptc-lisp-specification.md - Add Section 3.8 Sets, update grammar (Section 14), update type predicates (Section 8.6), remove sets from "Not supported" line
• docs/ptc-lisp-llm-guide.md - Add sets to data types and functions reference

Verification:

• Run mix test to ensure existing tests pass
• Run mix docs to verify documentation compiles

[andreasronge]

Implementation complete. All documentation updates have been made:

Changes:

• Added Section 3.8 Sets to ptc-lisp-specification.md describing set syntax, operations, and limitations
• Removed 'Sets (#{})' from the unsupported types list
• Added set? type predicate to Section 8.6 Type Predicates
• Updated Section 14 Grammar with set production rule: set = "#{" expression* "}" ;
• Updated ptc-lisp-llm-guide.md Data Types section to include sets
• Updated ptc-lisp-llm-guide.md Core Functions section with set operations (set?, set, contains?, count, empty?)

Verification:

• ✅ mix precommit passes (all format, compile, credo, and test checks)
• ✅ All 1010 existing tests pass with no failures
• ✅ Documentation compiles without errors

PR: #180