initial commit

_bmad-output/implementation-artifacts/5-2-line-references.md

@@ -0,0 +1,43 @@
+---
+epic: 5
+story: 5.2
+title: "Line References"
+status: draft
+---
+
+## Epic 5 — Variables, Line References & Aggregators
+**Goal:** Transform the notepad into a lightweight computational document.
+
+### Story 5.2: Line References
+
+As a **CalcPad user**,
+I want to reference the result of a specific line by its line number,
+So that I can build calculations that depend on intermediate results without naming every value.
+
+**Acceptance Criteria:**
+
+**Given** line 1 evaluates to `100`
+**When** the user writes `line1 * 2` on any subsequent line
+**Then** the engine resolves `line1` to `100` and the result is `200`
+
+**Given** line 1 evaluates to `100`
+**When** the user writes `#1 * 2` on any subsequent line
+**Then** the engine resolves `#1` to `100` and the result is `200`
+
+**Given** line 3 contains `line1 * 2` referencing line 1
+**When** the user inserts a new line above line 1 (shifting the original line 1 to line 2)
+**Then** the reference updates so it still points to the original line (now line 2)
+**And** the expression on the shifted line becomes `line2 * 2` or the reference is internally resolved correctly
+
+**Given** line 1 contains `#2 * 2` and line 2 contains `#1 + 3`
+**When** the engine evaluates the sheet
+**Then** a circular reference error is detected and reported on both lines
+**And** neither line produces a numeric result (both show an error indicator)
+
+**Given** a line references `#99` but only 10 lines exist
+**When** the engine evaluates the sheet
+**Then** the line displays an error such as "invalid line reference"
+
+**Given** line 5 is a comment or empty line with no numeric result
+**When** another line references `#5`
+**Then** the engine reports an error or returns `0` with a clear indication that the referenced line has no value