BitGrid-Rust Project Specs

1. Project Overview

BitGrid-Rust is a Rust from C systems-programming project. It reimplements the core ideas from a C-based Hitori puzzle assignment as a Rust command-line engine, while preserving the original project's low-level profile: compact board representation, row-major storage, bit-packed cell state, deterministic puzzle logic, graph validation, recursive search, CLI tooling, tests, and documentation.

The project intentionally evolves through three maturity levels:

School Assignment Baseline
  -> MVP Standalone Rust CLI
  -> MVP+ Systems-Style Portfolio Project

The project is not primarily a web app, UI product, or generic puzzle game. Its purpose is to demonstrate systems-style engineering and an AI-native builder workflow.

The central workflow claim is:

Codex is more than a coding agent. With the right workflow, context, and feedback loops, Codex can act as a tutor, implementer, reviewer, debugger, and documentation partner.

The central build loop is:

learn concept -> apply concept -> review implementation -> document lesson

Core framing:

This project intentionally preserves the same core profile across all maturity levels. The project grows in architecture, correctness, testing, tooling, and documentation, but it does not change identity: it remains a compact systems-style Hitori solver engine.

2. Origin: School-Style C Assignment

The project is inspired by a Computer Organization / C-programming course assignment based on Hitori puzzles.

The original assignment focused on low-level programming concepts:

transferring a heap-allocated 2D board into a compact row-major 1D array
storing puzzle cell values in individual bytes
using bit masks to encode additional state inside each cell
implementing blackout and circle deductions
implementing sandwich and doublet deductions
optionally implementing connectivity-aware gate deductions
checking heap memory cleanup with Valgrind

BitGrid-Rust keeps the same core problem and systems flavor, but reimplements the project as a modern Rust CLI engine with stronger modularity, tests, validation, and portfolio-ready documentation.

The school assignment is the seed. The Rust project is the independent expansion.

3. Project Identity: Rust from C

BitGrid-Rust should be understood as a Rust from C project, not just a standalone Rust exercise.

That means the project should explicitly translate C systems concepts into Rust systems concepts:

C concept	Rust counterpart
`typedef unsigned char Cell`	`struct Cell(u8)` newtype
`Cell *solution` row-major array	`Vec<Cell>` owned by `Board`
manual offset calculation	explicit row-major indexing helper
bit masks such as `0x80`, `0x40`, `0x1F`	Rust constants and methods on `Cell`
manual allocation/free	ownership, `Vec`, and `Drop` behavior
error codes / `error()` helper	`Result<T, BitGridError>`
recursive C functions	Rust methods with controlled mutation
Valgrind leak checking	ownership, tests, Clippy, optional Miri
ad hoc function organization	modules, traits/enums, testable APIs

The Rust version should not hide the original systems-programming concerns. Instead, it should make the translation visible through code, docs, tests, and phase closeouts.

4. Project Goals

The project has four main goals:

Preserve the core profile of the original systems-style assignment.
Progressively expand the project from school assignment to MVP to MVP+.
Demonstrate Rust systems-programming concepts through a concrete C-to-Rust transfer.
Demonstrate an AI-native phase-based workflow where Codex is used in multiple roles.

The technical goal is to build a Rust Hitori engine that shows:

compact board representation
row-major storage
bit-packed cell state
deterministic deduction rules
graph-based validation
recursive search
CLI usability
testing and benchmarking discipline

The workflow goal is to show that effective AI-native building depends on:

clear project context
explicit phase boundaries
tutor-before-build sequencing
proposal-before-implementation discipline
tests and feedback loops
human review
closeout documentation
progressive refinement rather than one-shot generation

5. Codex Roles

Codex should be intentionally used in multiple shapes, not only as a coding agent.

5.1 Tutor

Codex explains Rust concepts needed for the next implementation phase.

Examples:

ownership and borrowing
Vec<Cell> as owned board storage
newtype pattern with Cell(u8)
Result<T, E> error handling
module organization
traits vs enums for rule engines
recursion and cloning tradeoffs
testing and Clippy discipline

Tutor output should end with a checklist of what the human developer should understand before implementation begins.

5.2 Implementer

Codex implements only the approved build phase.

Implementation should be bounded by:

phase goal
files allowed to change
tests required
out-of-scope items
acceptance criteria

Codex should not build future phases early.

5.3 Reviewer

Codex reviews completed phase work for:

correctness
Rust API design
unnecessary complexity
hidden panics
missing tests
docs drift
C-to-Rust translation quality

5.4 Debugger

Codex helps interpret:

compiler errors
borrow checker errors
failed tests
parser edge cases
recursion bugs
CLI behavior mismatches

Debugging should preserve learning value. Codex should explain why the bug happened, not only patch it.

5.5 Documentation Partner

Codex helps update:

README.md
AGENTS.md
AI_native_builder_journal.md
docs/architecture.md
docs/phase_catalog.md
docs/c_to_rust_translation.md
phase closeout notes

Documentation should capture what changed, why it changed, and what was learned.

6. Core Workflow Loop

Each paired phase should follow this loop:

learn concept -> apply concept -> review implementation -> document lesson

Step 1 — Learn Concept

Codex acts as tutor. The goal is to understand the Rust concepts needed for the next build phase.

Expected output:

concept explanation
C-to-Rust mapping
pitfalls to watch for
small examples only if useful
readiness checklist

Step 2 — Apply Concept

Codex acts as implementer. The goal is to implement the bounded phase.

Expected output before coding:

short plan
files likely to change
tests likely to add
risks
explicit out-of-scope list

Step 3 — Review Implementation

Codex acts as reviewer and debugger. The goal is to inspect the implementation and tests before moving on.

Expected output:

what looks correct
what needs improvement
whether the Rust design matches the C-to-Rust translation goal
tests run
failures or concerns

Step 4 — Document Lesson

Codex acts as documentation partner. The goal is to make the workflow visible.

Expected output:

phase closeout note
concepts learned
C concept translated
implementation summary
tests added
known follow-ups

7. Non-Goals

BitGrid-Rust is not intended to become:

a web application
a large visual puzzle game
a generic AI chatbot
a database-backed product app
a mobile app
a frontend-heavy portfolio project
a puzzle collection with many unrelated games
a one-shot AI-generated code dump

The project should remain centered on systems-style Rust engineering and AI-native workflow evidence.

8. Maturity Levels

BitGrid-Rust should be understood as a maturity ladder:

Level 0: School Assignment Baseline
Level 1: MVP Standalone Rust CLI
Level 2: MVP+ Systems-Style Portfolio Project

Each level preserves the same core project identity while increasing architectural seriousness, correctness, tests, tooling, documentation, and workflow evidence.

8.1 Level 0 — School Assignment Baseline

The baseline represents the original assignment-level project.

At this level, the project demonstrates that the developer can implement the core mechanics of a Hitori solver in a low-level programming context.

Expected capabilities:

load a Hitori puzzle file
represent board cells compactly
store board data in row-major order
use bit masks to distinguish number, blacked-out state, and circled state
implement blackout and circle propagation
implement sandwich deductions
implement doublet deductions
write a solution file
run basic manual tests against provided puzzles

Portfolio interpretation:

Level 0 proves exposure to the core problem and low-level concepts. It does not yet prove independent productization, architectural design, or full testing discipline.

This level is valuable as coursework, but it is not yet a standalone portfolio project.

8.2 Level 1 — MVP

The MVP turns the school-style assignment into a standalone Rust command-line tool.

The MVP should be small but complete. A reviewer should be able to clone the repository, run the tool, solve sample puzzles, validate outputs, and run tests.

Required MVP capabilities:

Rust project skeleton using Cargo
Cell representation backed by compact u8 storage
Board representation backed by row-major Vec<Cell>
parser for puzzle files
writer for solution files
blackout and circle propagation
sandwich deduction
doublet deduction
repeated deterministic solving loop
board validator
CLI command for solving puzzles
CLI command for validating solutions
unit tests for cell bit operations
unit tests for board indexing
parser and writer tests
integration tests for sample puzzles
README with setup, run commands, and current project status
AI-native builder journal entries for each paired phase

Expected MVP Commands

cargo run -- solve puzzles/practice.puz
cargo run -- validate solutions/practice.sol
cargo test

MVP Success Criteria

The MVP is complete when:

the project builds with cargo build
tests pass with cargo test
at least one provided puzzle can be solved or partially solved deterministically
validator catches invalid duplicate, adjacency, and connectivity cases
README accurately describes the current implementation
project structure is clean enough for future phases
the journal shows tutor/build/review/document loops for MVP phases

MVP Portfolio Interpretation

The MVP demonstrates that the original assignment has been converted into a real Rust CLI project with clean structure, tests, and basic user-facing commands.

It is no longer only a class exercise, but it is still not the final portfolio version.

8.3 Level 2 — MVP+

The MVP+ expands the Rust CLI tool into a stronger systems-style engine.

MVP+ should demonstrate deeper architecture, stronger correctness guarantees, and clearer evidence of engineering discipline.

Required MVP+ capabilities:

modular rule engine
gate/connectivity-aware deductions
full board validation independent from solving
recursive backtracking fallback
contradiction detection
solver trace / explanation mode
benchmark command
structured solver statistics
improved error handling
larger puzzle corpus
stronger integration tests
documentation of architecture and design tradeoffs
C-to-Rust comparison notes
AI-native builder journal with paired phase closeouts

Expected MVP+ Commands

cargo run -- solve puzzles/practice.puz
cargo run -- solve puzzles/practice.puz --logic-only
cargo run -- solve puzzles/practice.puz --search
cargo run -- solve puzzles/practice.puz --explain
cargo run -- validate solutions/practice.sol
cargo run -- bench puzzles/
cargo test
cargo clippy

MVP+ Success Criteria

The MVP+ is complete when:

solver handles puzzles that require more than the basic assignment rules
search fallback works when deterministic deductions stall
validator is independent from solver logic
explanation mode produces deterministic, inspectable traces
benchmark mode reports solve time, deduction count, guesses, and recursion depth
documentation explains why Rust is appropriate for this project
C-to-Rust comparison notes are present
AI-native builder journal shows paired tutor/build/review/document workflow evidence

MVP+ Portfolio Interpretation

The MVP+ demonstrates a portfolio-level systems-style Rust project.

It shows compact representation, algorithmic reasoning, graph traversal, recursive search, CLI design, testing discipline, benchmarking, C-to-Rust transfer, and AI-native workflow control.

9. Core Domain: Hitori Puzzle Rules

A Hitori puzzle presents a grid of numbers. The solver must determine which cells should be blacked out so that:

No row contains more than one visible occurrence of the same number.
No column contains more than one visible occurrence of the same number.
Blacked-out cells are not horizontally or vertically adjacent.
All non-blacked-out cells remain connected horizontally or vertically.

BitGrid-Rust should preserve these rules as the core domain model.

10. Rust Implementation Direction

BitGrid-Rust should preserve the compact representation style of the original C assignment while using Rust's ownership and type system.

Expected representation:

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Cell(u8);

pub struct Board {
    rows: usize,
    cols: usize,
    cells: Vec<Cell>,
}

Expected bit layout:

bit 7      bit 6      bit 5      bits 4-0
BLACK      CIRCLE     RESERVED   NUMBER

Expected masks:

const BLACK_MASK: u8 = 0x80;
const CIRCLE_MASK: u8 = 0x40;
const NUMBER_MASK: u8 = 0x1F;

The Rust version should not hide the low-level representation behind unnecessary abstractions. The project should still make row-major indexing, bit masks, compact storage, and state transitions visible in the code and docs.

11. Planned Architecture

Planned module structure:

src/
├── main.rs
├── cell.rs
├── board.rs
├── parser.rs
├── writer.rs
├── solver.rs
├── rules.rs
├── validate.rs
├── search.rs
├── trace.rs
├── bench.rs
└── error.rs

Expected responsibilities:

cell.rs: compact cell representation and bit operations
board.rs: row-major board storage and safe access APIs
parser.rs: puzzle file parsing
writer.rs: solution output
rules.rs: deduction rules
solver.rs: solver loop and orchestration
validate.rs: Hitori correctness checks
search.rs: recursive backtracking fallback
trace.rs: explanation logging
bench.rs: benchmark runner
error.rs: shared error types

The architecture should keep puzzle I/O, board representation, solving, validation, search, tracing, and CLI code separated.

12. Data Model

Cell

A Cell stores both the puzzle number and solver state in a single byte.

Cell state:

number: lower 5 bits
blacked-out flag: high bit
circled flag: second-highest bit
reserved bit: available for future internal use

Expected behavior:

Cell::number() returns only the lower 5-bit number.
Cell::is_black() checks the black flag.
Cell::is_circled() checks the circle flag.
Cell::with_black() or equivalent marks a cell as black.
Cell::with_circle() or equivalent marks a cell as circled.
contradictory state transitions should be rejected at the board or solver layer.

Board

A Board owns a row-major vector of cells.

Index calculation:

index = row * cols + col

The board should expose safe APIs for accessing and mutating cells. Internal helpers may assume validated indexes when appropriate, but public-facing APIs should avoid panics where recoverable errors are better.

Expected board behavior:

create board from dimensions and cells
reject invalid dimensions or mismatched cell counts
retrieve cells by row and column
mutate cells by row and column
iterate rows and columns where useful
clone board state for search fallback

13. CLI Requirements

The CLI should remain simple and engine-focused. It should not become a large interactive application.

MVP CLI

bitgrid solve <puzzle-file>
bitgrid validate <solution-file>

MVP+ CLI

bitgrid solve <puzzle-file> --logic-only
bitgrid solve <puzzle-file> --search
bitgrid solve <puzzle-file> --explain
bitgrid validate <solution-file>
bitgrid bench <puzzle-directory>
bitgrid inspect <puzzle-file>

CLI output should be readable, deterministic, and useful for testing.

Example solve output:

Solved: yes
Size: 8x8
Mode: search
Deductions: 93
Guesses: 2
Max recursion depth: 1
Validation: passed

14. Solver Requirements

The solver should support deterministic rule propagation first.

Required deterministic rules:

blackout propagation
circle propagation
sandwich deduction
doublet deduction

MVP+ rules:

gate/connectivity-aware deduction
contradiction detection
recursive backtracking fallback

The solver should support three result states:

solved
unsolved but valid
contradiction / invalid

The solver should distinguish between:

logic-only solving
search-assisted solving
validation of a final board state

15. Validation Requirements

The validator must be independent from the solver.

It should verify:

no duplicate visible number in any row
no duplicate visible number in any column
no adjacent black cells
all visible cells are connected

The connectivity check should use graph traversal over the grid.

The validator should be usable both:

internally by the solver
externally through the CLI

16. Testing Requirements

Testing should grow with each maturity level.

Level 0

manual tests using provided puzzles

MVP

unit tests for Cell
unit tests for Board
parser tests
writer tests
validator tests
integration test for solving a sample puzzle

MVP+

rule-specific tests
search tests
contradiction tests
connectivity tests
CLI tests if practical
benchmark smoke test
regression puzzle corpus

Default verification commands:

cargo test
cargo clippy
cargo fmt --check

Optional later verification:

cargo bench
cargo miri test

17. Documentation Requirements

Required docs:

README.md
AGENTS.md
AI_native_builder_journal.md
docs/project_specs.md
docs/architecture.md
docs/phase_catalog.md
docs/c_to_rust_translation.md

Optional later docs:

docs/c_vs_rust_notes.md
docs/solver_rules.md
docs/benchmark_results.md
docs/puzzle_format.md
docs/quality_hardening_plan.md

The README should always reflect the current project state.

The AI-native builder journal should record phase closeouts and make the workflow visible.

18. Paired Phase Catalog

Instead of a normal phase catalog, BitGrid-Rust uses paired phases:

R0-Tutor -> R0-Build
R1-Tutor -> R1-Build
R2-Tutor -> R2-Build
...

Each tutor phase teaches the Rust concept needed for the next build phase. Each build phase applies that concept to the project.

Each phase pair should close with review and documentation:

Tutor -> Build -> Review -> Document

18.1 School Assignment Baseline

S0-Context — Preserve Original Assignment Context

Goal:

capture the original C assignment's purpose, constraints, and low-level concepts
identify what should be preserved in Rust

Outputs:

docs/original_assignment_summary.md
docs/c_to_rust_translation.md initial version
journal entry explaining why the Rust project exists

S1-Comparison — Identify Core C Concepts to Translate

Goal:

map the original C concepts to Rust concepts
define which concepts are essential to the project's identity

Outputs:

C-to-Rust concept map
initial MVP boundary
initial MVP+ boundary

18.2 MVP Paired Phases

R0-Tutor — Rust Project Model, Cargo, Modules, Ownership Basics

Tutor goal:

explain the Rust project model
explain Cargo, crates, modules, src/main.rs, src/lib.rs, and tests
explain ownership at a high level using the board engine as the example

C concept translated:

C files, headers, Makefile, and manual build commands become Cargo project structure and Rust modules.

Readiness checklist:

understand what Cargo manages
understand where library code and CLI code should live
understand why the board should own its cell storage

R0-Build — Create Rust Repo Skeleton

Build goal:

create the Rust project skeleton
separate library code from CLI entrypoint
add initial README and test command

Expected outputs:

Cargo.toml
src/lib.rs
src/main.rs
basic README.md
first passing cargo test

Out of scope:

board implementation
parser
solver rules
CLI commands beyond a placeholder

R1-Tutor — Newtype Pattern, `u8` Bit Masks, Safe APIs

Tutor goal:

explain the Cell(u8) newtype pattern
explain bit masks in Rust
explain Copy, Clone, Debug, and PartialEq
explain safe method APIs around compact representation

C concept translated:

typedef unsigned char Cell plus C macros becomes a Rust Cell(u8) type with methods.

Readiness checklist:

understand why Cell(u8) preserves compact storage
understand how bit masks are expressed as constants
understand why methods are safer than exposing raw bit operations everywhere

R1-Build — Implement Cell and Board

Build goal:

implement compact Cell
implement row-major Board
add safe indexing and mutation APIs
add tests for bit operations and indexing

Expected outputs:

src/cell.rs
src/board.rs
tests for masks, state flags, number extraction, and row-major indexing

Out of scope:

file parsing
solving rules
CLI solve command

R2-Tutor — `Result`, Error Types, File I/O, Parsing

Tutor goal:

explain Rust error handling with Result<T, E>
explain custom error enums
explain file reading and parser boundaries

C concept translated:

C helper errors and manual failure exits become structured Rust errors.

Readiness checklist:

understand when to return Result
understand why parser code should not directly exit the program
understand how CLI can display parser errors later

R2-Build — Implement Parser and Writer

Build goal:

parse puzzle files into Board
write board/solution output
reject invalid dimensions, values, and malformed input
add parser and writer tests

Expected outputs:

src/parser.rs
src/writer.rs
src/error.rs
sample puzzle files
parser/writer tests

Out of scope:

solver logic
full CLI solve behavior

R3-Tutor — Borrowing and Mutation Patterns for Solver State

Tutor goal:

explain mutable borrowing for board updates
explain avoiding conflicting borrows during row/column scans
explain recursion risks in Rust mutation-heavy code

C concept translated:

direct mutation through pointers becomes controlled mutation through &mut Board.

Readiness checklist:

understand &Board vs &mut Board
understand how to collect affected cells before mutating when needed
understand how to avoid borrow checker conflicts in propagation logic

R3-Build — Implement Blackout/Circle Propagation

Build goal:

implement blackout operation
implement circle operation
implement contradiction detection
implement propagation between blackout and circle
add tests for mutual propagation and termination

Expected outputs:

src/solver.rs or src/state.rs
tests for blackout, circle, duplicate propagation, neighbor propagation, and contradictions

Out of scope:

sandwich/doublet rules
CLI solve command beyond internal tests

R4-Tutor — Rule Organization with Enums or Traits

Tutor goal:

explain options for organizing solver rules
compare enum-based rules vs trait-based rules
explain why a simple enum/function approach may be better early

C concept translated:

separate C helper functions become testable Rust rule functions with structured results.

Readiness checklist:

understand how each rule reports changed/no-change/contradiction
understand why rules should not own CLI behavior
understand how a repeated rule loop works

R4-Build — Implement Sandwich and Doublet Deductions

Build goal:

implement sandwich deduction
implement doublet deduction
implement repeated deterministic solve loop
add rule-specific tests

Expected outputs:

src/rules.rs
updates to src/solver.rs
tests for sandwich, doublet, and repeated solving

Out of scope:

gate deduction
backtracking search
explanation mode

R5-Tutor — Graph Traversal and Connectivity in Rust

Tutor goal:

explain BFS/DFS over a row-major grid
explain VecDeque
explain visited tracking with Vec<bool> or bitset-like storage

C concept translated:

manual queue/visited arrays become Rust-owned collections with explicit traversal logic.

Readiness checklist:

understand how grid neighbors are generated
understand why validator must be independent from solver
understand how connectivity relates to Hitori correctness

R5-Build — Implement Validator and Connectivity

Build goal:

validate duplicate row values
validate duplicate column values
validate adjacent black cells
validate connected visible cells
add validation tests

Expected outputs:

src/validate.rs
connectivity tests
invalid board fixtures

Out of scope:

gate deduction
backtracking
benchmark command

R6-Tutor — CLI Basics and Human-Usable Tool Boundaries

Tutor goal:

explain CLI argument handling options
explain how CLI should call library code without owning solver logic
explain deterministic command output for tests

C concept translated:

assignment-style executable becomes a structured CLI wrapper over a library engine.

Readiness checklist:

understand why main.rs should stay thin
understand how command output should support review and testing

R6-Build — Basic CLI and MVP README Update

Build goal:

add solve command
add validate command
update README with current setup and usage
complete MVP closeout

Expected outputs:

src/main.rs CLI behavior
README current-state update
MVP closeout in journal

Out of scope:

advanced search
explanation trace
benchmarking

18.3 MVP+ Paired Phases

R7-Tutor — Connectivity-Aware Deductions and Temporary State

Tutor goal:

explain gate deductions conceptually
explain temporary board cloning vs rollback
explain how to test simulation without corrupting real board state

C concept translated:

extra-credit C gate deduction becomes a Rust connectivity-aware rule using safe temporary state.

R7-Build — Implement Gate Deduction

Build goal:

implement connectivity-aware gate deduction
integrate it into the deterministic rule loop
add focused tests

Expected outputs:

gate rule implementation
tests for temporary simulation and board preservation

R8-Tutor — Recursion, Cloning, and Backtracking Tradeoffs

Tutor goal:

explain recursive search in Rust
explain board cloning vs undo logs
explain how to return solved/failed/contradiction states

C concept translated:

recursive C search with manual state management becomes Rust search over cloned or explicitly restored board states.

R8-Build — Implement Backtracking Search

Build goal:

add search fallback when logic stalls
track guesses and recursion depth
integrate validator/contradiction checks
add search tests

Expected outputs:

src/search.rs
solver integration
tests for puzzles requiring search

R9-Tutor — Solver Traces and Observability

Tutor goal:

explain structured logging without mixing logging into business logic
explain trace events and deterministic output

C concept translated:

print-debugging or assignment output becomes structured solver trace events.

R9-Build — Implement Explanation Trace Mode

Build goal:

add trace event type
log deductions and search decisions
add --explain mode
add deterministic trace tests where practical

Expected outputs:

src/trace.rs
CLI explain mode
trace documentation

R10-Tutor — Benchmarking and Performance Measurement

Tutor goal:

explain timing, benchmark limitations, and stable output
explain what metrics matter for a solver engine

C concept translated:

systems performance awareness becomes explicit benchmark instrumentation.

R10-Build — Add Benchmark Command and Solver Statistics

Build goal:

add benchmark command over puzzle directory
report solve time, deductions, guesses, recursion depth, and validation result
add benchmark smoke test if practical

Expected outputs:

src/bench.rs
benchmarks/ output examples
README benchmark section

R11-Tutor — Rust Quality Tools and Hardening

Tutor goal:

explain cargo fmt, Clippy, optional Miri, and regression tests
explain how Rust's safety model changes the hardening process compared with C

C concept translated:

Valgrind/ASan-focused C hardening becomes Rust testing, Clippy, formatting, optional Miri, and careful panic/error review.

R11-Build — Expanded Tests and Regression Corpus

Build goal:

add broader puzzle fixtures
add regression tests
run cargo test, cargo clippy, and cargo fmt --check
document known limitations

Expected outputs:

expanded tests
TESTING.md or testing section
hardening closeout

R12-Tutor — C vs Rust Reflection and Portfolio Narrative

Tutor goal:

compare what C demonstrates vs what Rust demonstrates
explain ownership, safety, abstraction, and performance tradeoffs
help shape portfolio language honestly

C concept translated:

direct low-level C control becomes modern systems programming with ownership and safe abstractions.

R12-Build — Final Docs and MVP+ Packaging

Build goal:

finalize README
finalize architecture docs
finalize C-to-Rust comparison notes
finalize AI-native builder journal
prepare portfolio-ready closeout

Expected outputs:

README.md
docs/architecture.md
docs/c_to_rust_translation.md
docs/c_vs_rust_notes.md
AI_native_builder_journal.md
MVP+ closeout

R13-Tutor — Quality Hardening and C-Reference Alignment

Tutor goal:

explain the senior-review findings that remain after R12
explain why state-aware solution output matters for a Hitori CLI
explain the distinction between deterministic solving, search-assisted solving, stalled states, exhausted search, and contradiction
compare the Rust gate deduction with the hardened C reference rule
prepare a small-subphase hardening plan instead of one broad rewrite

C concept translated:

completed C project hardening becomes a Rust post-review hardening phase with explicit CLI behavior, stateful solution files, solver statuses, regression tests, and documentation closeout.

Readiness checklist:

understand why solve must display black/circle state to be inspectable
understand why validate <solution-file> should parse real solution state
understand why CLI search modes should expose the implemented recursive search
understand why gate deduction must not over-deduce from undecided connectivity
understand why R13 should be implemented as R13A through R13E, not as one large patch

R13-Build — Project-Ready Quality Hardening

Build goal:

harden the reviewed R12 project into a project-ready portfolio artifact
preserve the compact C-to-Rust systems profile
keep each hardening subphase small, testable, documented, and reviewable

Expected subphases:

R13A - state-aware solution output and validation
R13B - CLI --search and --logic-only solve modes
R13C - gate deduction hardening against the completed C reference
R13D - clearer solver result statuses
R13E - final docs refresh and R13 closeout

Expected outputs:

state-aware solution format and fixtures
CLI tests for search-assisted and logic-only solve modes
gate deduction positive and negative regression tests
solver status tests for solved, stalled, exhausted, contradiction, and invalid states
refreshed README, architecture, testing, and C-to-Rust translation docs
R13 closeout in AI_native_builder_journal.md and docs/phase_closeouts/

Out of scope:

web UI or GUI
puzzle generation
unrelated puzzle types
broad rewrites of Cell(u8) or row-major Board
Criterion benchmarks or performance optimization unless separately approved

Detailed plan:

docs/quality_hardening_plan.md

19. Phase Definition of Done

A phase is complete only when:

the tutor concept or build objective is complete
the intended behavior works locally if code was changed
tests are added or updated when behavior changed
documentation is updated if behavior, setup, or design changed
known limitations are recorded
the repository remains clean and reviewable
the AI-native builder journal receives a closeout note

Each phase should leave the repository in a working state.

20. Phase Closeout Template

Each paired phase should end with a journal entry using this structure:

## Phase R1 — Cell and Board

### Tutor Objective
Understand Rust newtypes, `u8` bit masks, and safe APIs for compact cell state.

### Build Objective
Implement `Cell` and `Board` with row-major storage and unit tests.

### Rust Concepts Learned
- `Cell(u8)` newtype
- `Copy` and `Clone`
- constants for bit masks
- safe indexing methods

### C Concept Translated
C `typedef unsigned char Cell` and `Cell*` row-major storage became Rust `Cell(u8)` and `Vec<Cell>` owned by `Board`.

### Implementation Summary
Added compact cell representation, row-major board storage, and tests.

### Review Notes
Checked bit masking behavior, indexing math, and public API boundaries.

### Tests Run
- `cargo test`
- `cargo fmt --check`

### Known Follow-Ups
Parser and writer remain out of scope until R2.

21. AI-Native Workflow Requirements

The project should be built through a phase-based AI-native workflow.

Codex should not be asked to build the whole project in one pass.

For each tutor phase, Codex should provide:

concept explanation
C-to-Rust mapping
common pitfalls
small examples only when useful
readiness checklist

For each build phase, Codex should first provide:

phase summary
implementation plan
files likely to change
tests likely to change
risks or scope questions
explicit out-of-scope list

Implementation should begin only after the human owner approves the phase plan.

After implementation, each phase should end with:

tests run
files changed
what was built
what was learned
known follow-ups
phase closeout note

The human developer remains responsible for:

project direction
architecture approval
scope control
reviewing generated code
deciding when a phase is complete
deciding what belongs in the public portfolio narrative

22. Portfolio Positioning

BitGrid-Rust should be positioned as:

A Rust-from-C systems-style constraint-solving engine that evolves from a school-style Hitori assignment into a tested, documented, CLI-based MVP and then into an MVP+ project with graph validation, recursive search, solver tracing, benchmarking, and phase-based AI-native development evidence.

The project should demonstrate:

Rust systems programming fundamentals
C-to-Rust concept transfer
compact data representation
algorithmic problem solving
graph traversal
recursive search
CLI tool design
testing discipline
AI-native workflow control

The intended final narrative is not simply:

I implemented Hitori in Rust.

The stronger narrative is:

I used a phase-based AI-native workflow to transfer a C systems-programming assignment into Rust, using Codex as tutor, implementer, reviewer, debugger, and documentation partner. The project demonstrates that effective AI-native building depends on workflow, context, and feedback loops, not just code generation.

23. Future Expansion Options

Future expansion should preserve the core profile. Acceptable future directions include:

comparing C and Rust implementations
adding stronger benchmark reports
adding more puzzle files
adding optional JSON trace output
adding a second puzzle type only if the Hitori engine is already stable
documenting Rust-specific design tradeoffs

Future expansion should avoid:

converting the project into a web app too early
adding UI complexity that distracts from systems design
adding AI-generated puzzle reasoning as a replacement for deterministic rules
broadening into many unrelated puzzle types before the Hitori engine is strong

24. Final Success Definition

BitGrid-Rust succeeds when it clearly shows the full progression:

School assignment seed
  -> standalone Rust CLI MVP
  -> systems-style MVP+ portfolio project

It also succeeds when the build trail clearly shows the AI-native learning and implementation loop:

learn concept
  -> apply concept
  -> review implementation
  -> document lesson

The final project should make it obvious that the same core profile was preserved throughout:

compact representation
row-major board layout
bit-packed cell state
deterministic solving
graph validation
recursive search
CLI tooling
tests
documentation
C-to-Rust comparison
AI-native paired phase workflow

FilesExpand file tree

project_specs.md

Latest commit

History

project_specs.md

File metadata and controls

BitGrid-Rust Project Specs

1. Project Overview

2. Origin: School-Style C Assignment

3. Project Identity: Rust from C

4. Project Goals

5. Codex Roles

5.1 Tutor

5.2 Implementer

5.3 Reviewer

5.4 Debugger

5.5 Documentation Partner

6. Core Workflow Loop

Step 1 — Learn Concept

Step 2 — Apply Concept

Step 3 — Review Implementation

Step 4 — Document Lesson

7. Non-Goals

8. Maturity Levels

8.1 Level 0 — School Assignment Baseline

8.2 Level 1 — MVP

Expected MVP Commands

MVP Success Criteria

MVP Portfolio Interpretation

8.3 Level 2 — MVP+

Expected MVP+ Commands

MVP+ Success Criteria

MVP+ Portfolio Interpretation

9. Core Domain: Hitori Puzzle Rules

10. Rust Implementation Direction

11. Planned Architecture

12. Data Model

Cell

Board

13. CLI Requirements

MVP CLI

MVP+ CLI

14. Solver Requirements

15. Validation Requirements

16. Testing Requirements

Level 0

MVP

MVP+

17. Documentation Requirements

18. Paired Phase Catalog

18.1 School Assignment Baseline

S0-Context — Preserve Original Assignment Context

S1-Comparison — Identify Core C Concepts to Translate

18.2 MVP Paired Phases

R0-Tutor — Rust Project Model, Cargo, Modules, Ownership Basics

R0-Build — Create Rust Repo Skeleton

R1-Tutor — Newtype Pattern, u8 Bit Masks, Safe APIs

R1-Build — Implement Cell and Board

R2-Tutor — Result, Error Types, File I/O, Parsing

R2-Build — Implement Parser and Writer

R3-Tutor — Borrowing and Mutation Patterns for Solver State

R3-Build — Implement Blackout/Circle Propagation

R4-Tutor — Rule Organization with Enums or Traits

R4-Build — Implement Sandwich and Doublet Deductions

R5-Tutor — Graph Traversal and Connectivity in Rust

R5-Build — Implement Validator and Connectivity

R6-Tutor — CLI Basics and Human-Usable Tool Boundaries

R6-Build — Basic CLI and MVP README Update

18.3 MVP+ Paired Phases

R7-Tutor — Connectivity-Aware Deductions and Temporary State

R7-Build — Implement Gate Deduction

R8-Tutor — Recursion, Cloning, and Backtracking Tradeoffs

R8-Build — Implement Backtracking Search

R9-Tutor — Solver Traces and Observability

R9-Build — Implement Explanation Trace Mode

R10-Tutor — Benchmarking and Performance Measurement

R10-Build — Add Benchmark Command and Solver Statistics

R11-Tutor — Rust Quality Tools and Hardening

R11-Build — Expanded Tests and Regression Corpus

R12-Tutor — C vs Rust Reflection and Portfolio Narrative

R1-Tutor — Newtype Pattern, `u8` Bit Masks, Safe APIs

R2-Tutor — `Result`, Error Types, File I/O, Parsing