Merge pull request #68 from foundersandcoders/feat/final-fac-build

Final FaC Build: Automated Releases & Roadmap Archiving

Author: JasonWarrenUK

.claude/CLAUDE.md

@@ -228,6 +228,6 @@ This project uses automated evidence tracking via git hooks. Every commit with K
 
 ## Getting Help
 - **Claude Code:** Use `/project/init` to reconfigure
-- **Roadmaps:** See `docs/roadmaps/` (restructured into 3 phases: [Phase 1](docs/roadmaps/phase-1-mvp-features.md), [Phase 2](docs/roadmaps/phase-2-production-features.md), [Phase 3](docs/roadmaps/phase-3-future-features.md))
+- **Roadmaps:** See `docs/roadmaps/` (archived into 3 phases: [Phase 1](docs/roadmaps/archive/2026/01/phase-1-mvp-features.md), [Phase 2](docs/roadmaps/archive/2026/01/phase-2-production-features.md), [Phase 3](docs/roadmaps/archive/2026/01/phase-3-future-features.md))
 - **Architecture:** See `docs/adrs/`
 - **Technical details:** See `docs/technical/`

.github/release.yml

@@ -0,0 +1,39 @@
+# Credit to Bad Echo - https://github.com/BadEcho/.github/blob/master/workflow-templates/release.yml
+name: Build and Release Iris TUI
+
+on:
+  push:
+    tags:
+      - "v*" # fires on: git tag v5.1.0 && git push --tags
+
+jobs:
+  build-macos:
+    name: Build macOS binary
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build TUI binary (Apple Silicon)
+        run: bun run build:tui:mac
+        # Outputs: dist/iris-darwin-arm64
+
+      - name: Verify binary
+        run: dist/iris-darwin-arm64 help
+
+      - name: Create GitHub Release and upload asset
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/iris-darwin-arm64
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-# Iris `v5.0.0`
+# Iris `v5.1.0`
 
 **ILR toolkit for apprenticeship data submission**
 

README.md

@@ -67,4 +67,4 @@ The MVP development has been split into three distinct phases:
 ## Archive
 
 The original combined roadmap (pre-restructure) has been archived at:
-[`docs/archive/mvp-original.md`](../archive/mvp-original.md)
+[`docs/archive/mvp-original.md`](../../../../archive/mvp-original.md)

docs/roadmaps/2026-q1/mvp.md docs/roadmaps/archive/2026/01/mvp.mddocs/roadmaps/2026-q1/mvp.md renamed to docs/roadmaps/archive/2026/01/mvp.md

@@ -1,18 +1,18 @@
 # Phase 1: MVP Features
 
-| Sub-Milestone | Focus | Status |
-|---------------|-------|--------|
-| **M2A** | OpenTUI Migration + Core TUI Screens | ✅ Complete |
-| **M2B** | Direct Commands | Open (M2A complete) |
-| **M2C** | Advanced TUI + Polish + Docs | In Progress |
-| **M2D** | Homebrew Distribution | Open (2BD.1 complete) |
+| Sub-Milestone | Focus                                | Status |
+|---------------|--------------------------------------|--------|
+|    **M2A**    | OpenTUI Migration + Core TUI Screens | ✅ Complete |
+|    **M2B**    |           Direct Commands            | Open (M2A complete) |
+|    **M2C**    |     Advanced TUI + Polish + Docs     | In Progress |
+|    **M2D**    |        Homebrew Distribution         | Open (2BD.1 complete) |
 
 > [!NOTE]
 > **Pointer (not a separate tracker):** items remain tracked here in Phase 1.
 > The broader TUI aesthetic/UX overhaul (framed panels, app shell, help overlay,
 > semantic colours) is *designed and sequenced* in
-> [tui-redesign.md](./tui-redesign.md), informed by
-> [tui-design-review.md](../technical/tui-design-review.md) — see those docs for
+> [tui-redesign.md](../../../tui-redesign.md), informed by
+> [tui-design-review.md](../../../../technical/tui-design-review.md) — see those docs for
 > the design rationale and branch ordering behind 2TI.12, 2TI.18, 2TM.5/2TM.6.
 
 <details>
@@ -51,12 +51,14 @@ graph TD
 
 > [!IMPORTANT]
 > **Dynamic Schema Prerequisite**
+>
 > - Annual ESFA schema updates must not require code changes.
 > - The dynamic schema system (Phases 1-4) enables loading new XSD files at runtime.
 > - Phase 5 (TUI schema management) is deferred to Milestone 2.
 
 > [!NOTE]
 > **Key**
+>
 > - CL (base utils)
 > - SG (schema system)
 > - SS (schema/mapping storage)
@@ -66,27 +68,27 @@ graph TD
 - [x] 1CL.2. Create ILR XML generator (minimal valid structure)
 - [x] 1CL.3. Build semantic validator (beyond structural checks)
 - [x] 1CL.4. Create XML parser module (`src/lib/xml-parser.ts`)
-	- [x] 1CL.4a. Add XML parser library (fast-xml-parser or equivalent)
+  - [x] 1CL.4a. Add XML parser library (fast-xml-parser or equivalent)
 - [x] 1CL.5. Add unit tests for core transformations
 - [x] 1SG.1. Implement **Dynamic Schema (Phase 1): XSD Parser & Schema Registry**
-	- [x] 1SG.1a. Create schema type definitions (SchemaElement, SchemaConstraints, SchemaRegistry)
-	- [x] 1SG.1b. Add fast-xml-parser dependency
-	- [x] 1SG.1c. Implement XSD parser (parse XSD as XML, extract element definitions)
-	- [x] 1SG.1d. Implement schema registry builder (transform XSD tree into queryable registry)
-	- [x] 1SG.1e. Add tests against actual schemafile25.xsd
+  - [x] 1SG.1a. Create schema type definitions (SchemaElement, SchemaConstraints, SchemaRegistry)
+  - [x] 1SG.1b. Add fast-xml-parser dependency
+  - [x] 1SG.1c. Implement XSD parser (parse XSD as XML, extract element definitions)
+  - [x] 1SG.1d. Implement schema registry builder (transform XSD tree into queryable registry)
+  - [x] 1SG.1e. Add tests against actual schemafile25.xsd
 - [x] 1SG.2. Implement **Dynamic Schema (Phase 2): Schema-Driven Validator**
-	- [x] 1SG.2a. Create schema validator module (validates data against registry constraints)
-	- [x] 1SG.2b. Implement constraint validation (pattern, length, range, cardinality, enumeration)
-	- [x] 1SG.2c. Migrate existing validator to use schema registry (remove hardcoded REQUIRED_FIELDS)
+  - [x] 1SG.2a. Create schema validator module (validates data against registry constraints)
+  - [x] 1SG.2b. Implement constraint validation (pattern, length, range, cardinality, enumeration)
+  - [x] 1SG.2c. Migrate existing validator to use schema registry (remove hardcoded REQUIRED_FIELDS)
 - [x] 1SG.3. Implement **Dynamic Schema (Phase 3): Schema-Driven Generator**
-	- [x] 1SG.3a. Create schema generator module (generate XML by traversing registry)
-	- [x] 1SG.3b. Implement element ordering from xs:sequence
-	- [x] 1SG.3c. Migrate existing generator to use schema registry (remove hardcoded interfaces)
+  - [x] 1SG.3a. Create schema generator module (generate XML by traversing registry)
+  - [x] 1SG.3b. Implement element ordering from xs:sequence
+  - [x] 1SG.3c. Migrate existing generator to use schema registry (remove hardcoded interfaces)
 - [x] 1SG.4. Implement **Dynamic Schema (Phase 4): Column Mapping Configuration**
-	- [x] 1SG.4a. Create column mapper module (CSV column → XSD path mapping)
-	- [x] 1SG.4b. Define mapping configuration schema (ColumnMapping, MappingConfig types)
-	- [x] 1SG.4c. Create default FaC Airtable mapping configuration
-	- [x] 1SG.4d. Migrate convert workflow to use column mapper (remove hardcoded rowToLearner & rowToDelivery)
+  - [x] 1SG.4a. Create column mapper module (CSV column → XSD path mapping)
+  - [x] 1SG.4b. Define mapping configuration schema (ColumnMapping, MappingConfig types)
+  - [x] 1SG.4c. Create default FaC Airtable mapping configuration
+  - [x] 1SG.4d. Migrate convert workflow to use column mapper (remove hardcoded rowToLearner & rowToDelivery)
 - [x] 1SS.1. Implement storage abstractions for cross-submission history (supports config, mappings, schemas, submissions, history)
 - [x] 1SS.2. Configuration system (user preferences + custom field mappings in `~/.iris/config.json`)
 - [x] 1SS.3. Load mapping config from file (read JSON, validate structure)
@@ -128,17 +130,17 @@ graph TD
 <summary><strong>✅ M2X: OpenTUI Migration (Complete)</strong></summary>
 
 - [x] 1. Foundation ✅
-	- [x] **2TI.20** — Install `@opentui/core` and `opentui-spinner` (pin exact versions, no `^`/`~`)
-	- [x] **2TI.21** — Rewrite `app.ts` bootstrap (`createCliRenderer()` replaces terminal-kit fullscreen/grabInput) — **depends on 2TI.20**
-	- [x] **2TI.22** — Create OpenTUI theme adapter (convert hex theme to `RGBA`; hex strings also accepted directly) — **depends on 2TI.20**
-	- [x] **2TI.23** — Adapt `router.ts` for OpenTUI screen interface (screen signature changes, renderer context replaces terminal instance) — **depends on 2TI.21**
+  - [x] **2TI.20** — Install `@opentui/core` and `opentui-spinner` (pin exact versions, no `^`/`~`)
+  - [x] **2TI.21** — Rewrite `app.ts` bootstrap (`createCliRenderer()` replaces terminal-kit fullscreen/grabInput) — **depends on 2TI.20**
+  - [x] **2TI.22** — Create OpenTUI theme adapter (convert hex theme to `RGBA`; hex strings also accepted directly) — **depends on 2TI.20**
+  - [x] **2TI.23** — Adapt `router.ts` for OpenTUI screen interface (screen signature changes, renderer context replaces terminal instance) — **depends on 2TI.21**
 - [x] 2. Screen Migration ✅
-	- [x] **2TI.24** — Migrate Dashboard screen (menu → `SelectRenderable`, layout → flexbox `GroupRenderable`, gradient header retained)
-	- [x] **2TI.25** — Migrate FilePicker screen (file list → `SelectRenderable` with scrolling, path breadcrumb → `TextRenderable`, manual scroll offset eliminated)
-	- [x] **2TI.26** — Migrate Processing screen (step display → property-update model with auto re-render, spinner → `opentui-spinner`, no manual redraw loop)
+  - [x] **2TI.24** — Migrate Dashboard screen (menu → `SelectRenderable`, layout → flexbox `GroupRenderable`, gradient header retained)
+  - [x] **2TI.25** — Migrate FilePicker screen (file list → `SelectRenderable` with scrolling, path breadcrumb → `TextRenderable`, manual scroll offset eliminated)
+  - [x] **2TI.26** — Migrate Processing screen (step display → property-update model with auto re-render, spinner → `opentui-spinner`, no manual redraw loop)
 - [x] 3. Cleanup ✅
-	- [x] **2TI.27** — Update documentation that still references terminal-kit; unify `app.test.ts` to use shared mock fixture — **depends on 2TI.24, 2TI.25, 2TI.26**
-	- [x] **2TI.28** — (merged into 2TI.27) Update TUI test fixtures for OpenTUI mock renderer interface; verify on target terminal environments
+  - [x] **2TI.27** — Update documentation that still references terminal-kit; unify `app.test.ts` to use shared mock fixture — **depends on 2TI.24, 2TI.25, 2TI.26**
+  - [x] **2TI.28** — (merged into 2TI.27) Update TUI test fixtures for OpenTUI mock renderer interface; verify on target terminal environments
 
 </details>
 
@@ -166,10 +168,10 @@ All tasks complete — no open tasks in M2A.
 - [x] **1WA.22** — Block convert from producing XML when validation fails (currently saves output even for completely invalid input like `hey, hey, hey`; should abort before `generate` step if error count > 0, or at minimum require user confirmation)
 - [x] **1WA.23** — Fix validate workflow routing — currently routes to failure screen on first missing field instead of collecting all validation issues and showing the explorer. The validator itself collects all issues; the workflow layer treats the first error as fatal.
 - [x] **2TI.30** — Fix validation explorer UX issues:
-	- Status bar says `[Tab] Switch filter` but `TabSelectRenderable` uses `[←→]` arrows
-	- Tab switching causes display glitches (same bordered-container rendering issue as check-results)
-	- Row numbers 0-indexed — should display as 1-indexed for non-dev users
-	- Single-issue display doesn't indicate it's the first occurrence of a repeated error
+  - Status bar says `[Tab] Switch filter` but `TabSelectRenderable` uses `[←→]` arrows
+  - Tab switching causes display glitches (same bordered-container rendering issue as check-results)
+  - Row numbers 0-indexed — should display as 1-indexed for non-dev users
+  - Single-issue display doesn't indicate it's the first occurrence of a repeated error
 - [x] **2TI.32** — Two-file-picker for cross-check workflow — user must select both current and previous submission files (not auto-select from history array). Blocks 2TI.15 completion.
 - [x] **2TI.17** — Test TUI with real CSV exports from Airtable — **depends on 2TI.29, 1WA.20, 1WA.21, 1WA.22, 1WA.23, 2TI.30, 2TI.15**
 
@@ -284,6 +286,8 @@ graph TD
 
 2TI.12["`*2TI.12*<br/>**SHOULD**<br/>contextual help`"]:::should-blocked
 2TI.31["`*2TI.31*<br/>**SHOULD**<br/>success proof`"]:::should-blocked
+2TM.7["`*2TM.7*<br/>**SHOULD**<br/>fix mapping-config typo`"]:::should-open
+2TI.34["`*2TI.34*<br/>**SHOULD**<br/>fix crosscheck filePath`"]:::should-open
 2TS.2["`*2TS.2*<br/>**COULD**<br/>schema manager screen`"]:::could-blocked
 2TS.3["`*2TS.3*<br/>**COULD**<br/>schema version selector`"]:::could-blocked --> 2TS.4
 2TS.4["`*2TS.4*<br/>**COULD**<br/>dynamic migration guidance`"]:::could-blocked
@@ -308,7 +312,7 @@ phase1{"`**M2C**<br/>Complete`"}:::mile
 2UD.1 -.->|optional| 2UD.2 & phase1
 2TS.2 -.->|optional| 2TS.3 & 2TI.19 & 2TC.2
 2TC.2 -.->|optional| 2TC.3 & 2TC.4
-2TI.33 & 2TM.5 & 2TM.6 & 2TI.19 & 2TS.4 & 2UD.2 & 2DC.4 & 2TC.1 & 2TC.2 & 2TC.3 & 2TC.4 -.->|optional| phase1
+2TI.33 & 2TM.5 & 2TM.6 & 2TI.19 & 2TS.4 & 2UD.2 & 2DC.4 & 2TC.1 & 2TC.2 & 2TC.3 & 2TC.4 & 2TM.7 & 2TI.34 -.->|optional| phase1
 
 classDef must-open fill:#D6A3BF,color:#000;
 classDef must-blocked fill:#F3D8E6,color:#000;
@@ -338,6 +342,8 @@ classDef mile fill:#E8EFF6,color:#000;
 - [ ] **2TI.18** — Add visual feedback (spinners via `opentui-spinner` with 80+ animations and dynamic color effects; transitions via OpenTUI Timeline API) — **depends on 2DC.3**
 - [ ] **2TI.31** — Show validation proof on success screen (summary of checks passed, schema version validated against, learner count breakdown — gives user confidence the output is genuinely valid) — **depends on 2TI.10**
 - [ ] **2TC.1** — Clean test history after test runs (prevent test submissions from polluting global history; use isolated history per test or cleanup in afterEach) — **depends on 2TI.18**
+- [ ] **2TM.7** — Fix `IlrIlrMappingConfig` typo in mapping-save & storage/create (doubled `Ilr` prefix in `import type` at `src/tui/screens/mapping-save.ts:18` and `src/lib/storage/create.ts:18` imports a non-existent type; the real `IlrMappingConfig` is used in three type positions but silently resolves to `any`. Bun erases it at runtime so no crash, but the mapping config loses all type safety. Fix the import name; `tsc` clears.)
+- [ ] **2TI.34** — Fix missing `filePath` on `previousSubmission` in cross-check workflow (the object literal at `src/lib/workflows/crossCheck.ts:144` is typed `HistoryEntry` but omits the required `filePath` field. Latent today since that branch never reads it, but it violates the type contract — any future read of `previousSubmission.filePath` yields `undefined`. Add `filePath: input.previousFilePath`.)
 
 ### Could Have
 
@@ -387,6 +393,8 @@ graph TD
 2TC.2["`*2TC.2*<br/>util<br/>history cleanup`"]:::could-blocked
 2TC.3["`*2TC.3*<br/>enhance<br/>dual-picker`"]:::could-blocked
 2TC.4["`*2TC.4*<br/>enhance<br/>bordered panel`"]:::could-blocked
+2TM.7["`*2TM.7*<br/>fix<br/>mapping-config typo`"]:::should-open
+2TI.34["`*2TI.34*<br/>fix<br/>crosscheck filePath`"]:::should-open
 
 %% Build & Distribution %%
 2BD.2["`*2BD.2*<br/>build<br/>GH Actions release`"]:::could-open
@@ -414,7 +422,7 @@ phase1{"`**Phase 1**<br/>Complete`"}:::mile
 2UD.1 -.->|optional| 2UD.2 & phase1
 2TS.2 -.->|optional| 2TS.3 & 2TI.19 & 2TC.2
 2TC.2 -.->|optional| 2TC.3 & 2TC.4
-2TI.33 & 2TM.5 & 2TM.6 & 2DC.4 & 2TI.19 & 2TS.4 & 2UD.2 & 2TC.1 & 2TC.2 & 2TC.3 & 2TC.4 -.->|optional| phase1
+2TI.33 & 2TM.5 & 2TM.6 & 2DC.4 & 2TI.19 & 2TS.4 & 2UD.2 & 2TC.1 & 2TC.2 & 2TC.3 & 2TC.4 & 2TM.7 & 2TI.34 -.->|optional| phase1
 
 classDef must-open fill:#D6A3BF,color:#000;
 classDef must-blocked fill:#F3D8E6,color:#000;

…roadmaps/2026-q1/phase-1-mvp-features.md …/archive/2026/01/phase-1-mvp-features.mddocs/roadmaps/2026-q1/phase-1-mvp-features.md renamed to docs/roadmaps/archive/2026/01/phase-1-mvp-features.md docs/roadmaps/2026-q1/phase-1-mvp-features.md renamed to docs/roadmaps/archive/2026/01/phase-1-mvp-features.md

@@ -1,10 +1,10 @@
 # Phase 2: Production Features
 
-| Milestone | Focus | Status |
-|-----------|-------|--------|
-| **M3** | CLI Completion | Blocked (depends on Phase 1) |
-| **M4** | Desktop Interface | Blocked (depends on M3) |
-| **M5** | Production Docs | Blocked (depends on M4) |
+| Milestone | Focus             | Status |
+|-----------|-------------------|--------|
+|  **M3**   |  CLI Completion   | Blocked (depends on Phase 1) |
+|  **M4**   | Desktop Interface | Blocked (depends on M3) |
+|  **M5**   |  Production Docs  | Blocked (depends on M4) |
 
 **Prerequisite:** [Phase 1: MVP Features](./phase-1-mvp-features.md) — All M2A, M2B, M2C tasks complete
 
@@ -72,6 +72,7 @@ classDef mile fill:#9ff;
 
 > [!NOTE]
 > **Categories:**
+>
 > - GC (GUI Components)
 > - NB (Native Builds)