feat(#1): add spec-driven solutions for matrix traversal problems

Author: carlrollon

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+
+jobs:
+  test:
+    name: Maven Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Run tests
+        run: mvn test

.gitignore

@@ -0,0 +1,39 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+.kotlin
+
+### IntelliJ IDEA ###
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

.idea/.gitignore

@@ -0,0 +1,24 @@
+# Archived OpenSpec Changes
+
+This project implements classic and advanced matrix traversal problems using OpenSpec-driven workflows. Below are summaries of the two completed and archived changes:
+
+---
+
+## Biggest Island
+- **Problem:** Given a 2D binary matrix, find the area of the largest island (group of 1s connected 4-directionally).
+- **Approach:** Iterative BFS, in-place marking of visited cells (O(m·n) time, O(1) extra space).
+- **Artifacts:** Full OpenSpec (proposal, spec, design, tasks) and implementation with comprehensive tests.
+- **Archive Location:** `openspec/changes/archive/biggest-island/`
+
+---
+
+## Making a Large Island
+- **Problem:** Given an n×n binary matrix, flip at most one 0 to 1 to maximize the largest island area. Return the largest possible area after the flip.
+- **Approach:** Two-pass O(n²) algorithm: first label all islands with unique IDs and record their areas, then for each water cell, sum the areas of all distinct neighboring islands plus one (the flip).
+- **Artifacts:** Full OpenSpec (proposal, spec, design, tasks) and implementation with comprehensive tests.
+- **Archive Location:** `openspec/changes/archive/2026-04-18-making-a-large-island/`
+
+---
+
+Both features are fully specified, implemented, and tested. See the respective archive folders for detailed specs, design decisions, and test coverage.
+

.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,3 @@
+schema: spec-driven
+version: "1.2.0"
+

.idea/misc.xml

@@ -0,0 +1,125 @@
+# Design: making-a-large-island
+
+## Context
+
+Extends the matrix-traversal-java library with a harder island variant. The existing
+`IslandSolver` solves the read-only "biggest island" problem. `LargeIslandSolver`
+builds on that domain but requires a two-pass strategy because a brute-force re-BFS
+per water cell would be O(n⁴) — too slow for n = 500. The input grid may be mutated
+in-place (same convention as `IslandSolver`).
+
+## Goals / Non-Goals
+
+**Goals:**
+- O(n²) time and O(n²) space solution satisfying R-1 through R-6.
+- Correct handling of all-land, all-water, and 1×1 edge cases.
+- Full JUnit 5 unit-test coverage for all spec scenarios.
+
+**Non-Goals:**
+- Flipping more than one `0`.
+- Diagonal connectivity.
+- Returning the coordinates of the optimal flip cell.
+- Concurrent or streaming APIs.
+
+## Decisions
+
+### D1: Two-Pass Algorithm over Brute-Force Re-BFS
+
+**Choice:** Two-pass approach:
+1. **Pass 1 — Label:** BFS every land cell, assigning each island a unique integer ID
+   (starting at `2`, since `0`=water and `1`=land are already used). Store each
+   island's area in a `Map<Integer, Integer> areaById`.
+2. **Pass 2 — Probe:** For each water cell (`0`), look at its 4 neighbors, collect
+   **distinct** island IDs, sum their areas + 1, and track the global maximum.
+
+**Rationale:**
+- Brute-force (flip each `0`, re-run BFS, flip back) is O(n²) × O(n²) = O(n⁴) — too slow for n = 500.
+- Two-pass is O(n²) time and O(n²) space — fast enough for the constraint.
+- Satisfies R-1, R-6 (distinct IDs prevent double-counting).
+
+**Alternatives considered:**
+- *Brute-force re-BFS per water cell* — O(n⁴), too slow for n = 500; rejected.
+- *Union-Find* — correct and O(n² α(n²)) ≈ O(n²), but more complex to implement; labels-and-map approach is simpler and equally fast; rejected for readability.
+
+---
+
+### D2: In-Place Island Labeling (IDs start at 2)
+
+**Choice:** Overwrite land cells with their island ID (≥ 2) directly in the grid during Pass 1.
+
+**Rationale:**
+- Eliminates the need for a separate `int[][] label` array — saves O(n²) auxiliary space.
+- IDs start at `2` so `0` (water) and `1` (unlabeled land encountered during outer loop scan) remain unambiguous sentinels during Pass 1.
+- Consistent with the project convention of in-place mutation established in `IslandSolver` (D2 there).
+
+**Alternatives considered:**
+- *Separate label array* — preserves the input but costs O(n²) extra space; rejected.
+
+---
+
+### D3: Distinct-ID Set per Water Cell Probe
+
+**Choice:** For each water cell in Pass 2, collect neighbor IDs into a `Set<Integer>` before summing areas, ensuring each neighboring island is counted at most once (R-6).
+
+**Rationale:**
+- A water cell can be adjacent to the same large island on two or more sides; summing without deduplication would double-count that island's area.
+- A small fixed-size set (at most 4 entries) — allocation cost is negligible.
+
+**Alternatives considered:**
+- *Bitmask deduplication* — works only if IDs are small enough; fragile and less readable; rejected.
+
+---
+
+### D4: All-Land Early Exit
+
+**Choice:** Track `maxArea` during Pass 1. After Pass 1, if no `0` cells exist, return `maxArea` immediately (which equals n² for a fully connected grid, R-2).
+
+**Rationale:**
+- Avoids an unnecessary Pass 2 scan when no flip is possible.
+- Naturally falls out of the Pass 1 loop with no special code path.
+
+---
+
+## Risks / Trade-offs
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| ID collision with `0` or `1` sentinels | Wrong label / wrong area | IDs start at `2`; guarded by `nextId` counter initialised to `2` |
+| Integer overflow on area sum for n=500 | Wrong max (all-land = 250 000, fits in int) | n²=250 000 ≪ Integer.MAX_VALUE — no overflow risk |
+| Water cell with no land neighbors | Returns 1 (the flip itself) | Correct — an isolated flipped cell is an island of area 1 |
+
+## Architecture
+
+```
+largestIsland(int[][] grid)
+  │
+  ├─ guard: null / empty → return 0                        (R-3)
+  │
+  ├─ PASS 1 — Label islands
+  │   nextId = 2, areaById = new HashMap
+  │   for each cell (r, c):
+  │     if grid[r][c] == 1:
+  │       area = bfs(r, c, nextId, grid)                   (D1, D2)
+  │       areaById.put(nextId, area)
+  │       maxArea = max(maxArea, area)
+  │       nextId++
+  │
+  ├─ if no zeros found during Pass 1 → return maxArea      (D4, R-2)
+  │
+  └─ PASS 2 — Probe water cells
+      for each cell (r, c) where grid[r][c] == 0:
+        neighbors = distinct island IDs in 4 directions    (D3, R-6)
+        candidate = 1 + sum(areaById.get(id) for id in neighbors)
+        maxArea = max(maxArea, candidate)                   (R-1)
+      │
+      return maxArea
+```
+
+## Migration Plan
+
+New feature — no existing APIs are changed.
+
+## Open Questions
+
+- [ ] Package placement: `org.example` (consistent with `IslandSolver`) — confirm once reviewed.
+

.idea/vcs.xml

@@ -0,0 +1,44 @@
+# Proposal: making-a-large-island
+
+## Why
+
+A natural follow-up to the "biggest island" problem: given that you can flip exactly one water cell to land, what is the maximum island size achievable? This extends the matrix-traversal library with a more challenging variant that requires island labeling and neighbor-merging logic.
+
+## What Changes
+
+Given an n×n binary matrix, flip **at most one** `0` to `1`, then return the area of the largest island after that flip. If no `0` exists the grid is already all land — return n².
+
+- New public method `int largestIsland(int[][] grid)` on a new class `LargeIslandSolver`.
+- Two-pass approach: label islands by ID, then probe each water cell for the best flip.
+- Input grid **may be mutated** during traversal (cells are labelled in-place with island IDs).
+
+**Constraints (per problem definition):**
+- `n == grid.length == grid[i].length`
+- `1 <= n <= 500`
+- `grid[i][j]` is `0` or `1`
+
+## Capabilities
+
+### New Capabilities
+- `large-island-expansion`: Two-pass island-labeling + water-cell probing that computes the maximum island area achievable by flipping at most one `0`.
+
+### Modified Capabilities
+<!-- none -->
+
+## Impact
+
+- New source file: `src/main/java/org/example/LargeIslandSolver.java`
+- New test file: `src/test/java/org/example/LargeIslandSolverTest.java`
+- No changes to existing classes or APIs.
+- No new external dependencies.
+
+## Acceptance Criteria
+
+- [ ] `largestIsland` returns the correct answer when flipping one `0` merges two islands.
+- [ ] `largestIsland` returns the correct answer when flipping one `0` extends one island.
+- [ ] `largestIsland` returns n² when the grid is all `1`s (no flip possible).
+- [ ] `largestIsland` returns `1` for a 1×1 grid of `0` (flip the only cell).
+- [ ] `largestIsland` handles `null` or empty input by returning `0`.
+- [ ] The same water cell is never counted twice when its neighbors belong to the same island.
+- [ ] All unit tests pass (`mvn test`).
+