rtfct 0.1.0

package/.project/adrs/001-use-bun-typescript.md

@@ -0,0 +1,52 @@
+# ADR-001: The Bun and TypeScript Covenant
+
+*Recorded Wisdom of the First Tech-Priest*
+
+## Status
+
+**Accepted** — Blessed and sealed
+
+## The Context
+
+The rtfct CLI must be distributed to the faithful without friction. The incantation `bunx rtfct` or `npx rtfct` must simply work.
+
+The paths considered:
+
+| Path | Blessing | Burden |
+|------|----------|--------|
+| **Zig** | Fast, single binary, holy | npm distribution awkward |
+| **Go** | Fast, single binary | npm distribution awkward |
+| **Node/TypeScript** | Native npm | Slower startup, build step required |
+| **Bun/TypeScript** | Native npm via bunx, fast startup, TypeScript native | Newer, less battle-tested |
+
+## The Decision
+
+We covenant with **Bun** as the runtime and **TypeScript** as the language.
+
+## The Consequences
+
+### Blessings
+
+- `bunx rtfct` simply works — no installation ritual required
+- Fast startup (~20ms) — the faithful need not wait
+- TypeScript without build step — Bun executes `.ts` directly
+- Built-in test runner — `bun test` for the Rites of Verification
+- Familiar to many — JavaScript/TypeScript knowledge is widespread
+
+### Burdens
+
+- Bun is younger, less proven in battle
+- Some faithful may not have Bun installed (mitigated by `npx` fallback)
+- Not a single binary — requires Bun or Node runtime
+
+### Mitigations
+
+- Also publish to npm for `npx rtfct` as fallback path
+- Keep dependencies minimal — reduce surface area for failure
+- Test on both Bun and Node to ensure compatibility
+
+---
+
+*This wisdom is recorded. Future Tech-Priests may learn from it.*
+
+*The Omnissiah guided this decision.*

package/.project/guardrails.md

@@ -0,0 +1,65 @@
+# The Forbidden Heresies
+
+*The flesh is weak. These laws protect us from its failings.*
+
+## The Sacred Commandments
+
+### THOU SHALT
+
+- **Keep the CLI minimal** — `init`, `add`, `status`, `regenerate`, `praise`. No more.
+- **Keep dependencies near zero** — External code is external risk.
+- **Make presets simple** — Just markdown and `manifest.json`. A child should author them.
+- **Fail fast with clarity** — When something breaks, say what and why. Suggest the remedy.
+- **Support both `bunx` and `npx`** — Meet the faithful where they are.
+
+### THOU SHALT NOT
+
+- **Add a web UI** — The terminal is the altar. It is sufficient.
+- **Add a hosted service** — The Sacred Texts belong in the repository, not in the cloud.
+- **Add "smart" features** — The tool does not interpret code. It manages text.
+- **Require accounts, API keys, or network** — Except to fetch GitHub presets. Offline is holy.
+- **Auto-modify Sacred Texts** — Only kanban task movement is permitted. All else requires blessing.
+- **Add configuration outside `.project/`** — One source of truth. No scattered config files.
+
+## The Code Purity Laws
+
+- **Functional over object-oriented** — Functions are pure. Classes hide state.
+- **No classes unless truly necessary** — And it is rarely necessary.
+- **Explicit over clever** — The next reader is the Machine Spirit. It does not appreciate cleverness.
+- **If a function exceeds 30 lines, it sins** — It is doing too much. Decompose it.
+
+## The Error Doctrine
+
+- **Never swallow errors** — Every error must surface. Silent failure is heresy.
+- **User-facing errors must guide** — Do not merely report. Suggest the next action.
+- **Provide `--verbose`** — For when the faithful need to see the inner workings.
+
+## The Litmus Rite
+
+Before adding ANY feature, the Tech-Priest must ask:
+
+1. **Does this help the Machine Spirit understand the project?**
+2. **Does this help the human understand the project state?**
+3. **Can this be accomplished with markdown alone?**
+
+If the answer to (1) and (2) is NO — do not add it.
+
+If the answer to (3) is YES — do that instead.
+
+Complexity is the enemy. Simplicity is sacred.
+
+## The Seven Deadly Heresies
+
+1. **The Heresy of Unspecified Code** — Code without corresponding Sacred Texts
+2. **The Heresy of Unregenerable State** — If you can't `rm -rf src/` and recover, you have sinned
+3. **The Heresy of Hidden Configuration** — Config files outside `.project/`
+4. **The Heresy of Implicit Behavior** — Magic that the reader cannot trace
+5. **The Heresy of Scope Creep** — Features beyond the Founding Vision
+6. **The Heresy of Premature Optimization** — Make it work, make it right, then make it fast
+7. **The Heresy of Silent Failure** — Errors that do not surface
+
+---
+
+*Memorize these heresies. Avoid them. The Omnissiah is watching.*
+
+*The flesh is weak, but the protocol is strong.*

package/.project/kanban/backlog.md

@@ -0,0 +1,7 @@
+# The Backlog — Unordained Tasks
+
+*These works await the Machine Spirit. They shall be completed in order of priority.*
+
+---
+
+*The Backlog is empty. All ordained tasks are complete or in progress.*

package/.project/kanban/done.md

@@ -0,0 +1,240 @@
+# Done — Completed Works
+
+*Here we record the manifestations of the Machine Spirit. Each completed task is a victory.*
+
+---
+
+## [TASK-001] Consecrate the Project Scaffolding
+
+**Completed:** 2025-12-25
+
+The foundation has been laid:
+- `package.json` with CLI bin entry and sacred scripts
+- `tsconfig.json` with strict TypeScript configuration
+- `src/index.ts` entry point awaiting the sacred commands
+- `tests/` directory structure prepared for the Rites of Verification
+
+The Acceptance Rite passes: `bun run build` completes without error.
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-002] Manifest the Argument Parser
+
+**Completed:** 2025-12-25
+
+The sacred commands have been ordained:
+- `src/args.ts` — parses commands, flags, and arguments
+- `src/help.ts` — displays guidance to the Tech-Priest
+- Full test coverage in `tests/unit/args.test.ts`
+
+The Acceptance Rite passes:
+- `rtfct --help` displays sacred usage
+- Unknown commands produce clear error with guidance
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-003] Manifest the `init` Command — Basic
+
+**Completed:** 2025-12-25
+
+The consecration ritual has been manifested:
+- `src/commands/init.ts` — creates the .project/ structure
+- `src/templates.ts` — contains the Sacred Text templates
+- Full integration test coverage in `tests/integration/init.test.ts`
+
+The Acceptance Rite passes:
+- `rtfct init` creates valid .project/ structure with all Sacred Texts
+- `--force` purifies and recreates existing .project/
+- Fails gracefully if .project/ already exists
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-004] Manifest the `init` Command — With Presets
+
+**Completed:** 2025-12-25
+
+The Codex incorporation mechanism has been manifested:
+- `src/presets/index.ts` — resolves and writes preset files
+- `src/presets/zig.ts` — The Zig Codex with testing strategy and guardrails
+- `src/presets/typescript.ts` — The TypeScript Codex with testing strategy and guardrails
+
+The Acceptance Rite passes:
+- `rtfct init --with zig` creates project with Zig Codex properly merged
+- `rtfct init --with zig,typescript` handles multiple comma-separated presets
+- Unknown presets fail gracefully with guidance
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-010] Manifest the `status` Command
+
+**Completed:** 2025-12-25
+
+The Litany of Tasks is now revealed:
+- `src/kanban.ts` — parses kanban markdown, counts tasks, extracts current task
+- `src/commands/status.ts` — runs status command with formatted output
+
+The Acceptance Rite passes:
+- Shows backlog/in-progress/done counts
+- Displays current ordained task with ID and title
+- Shows last activity timestamp
+- Sacred formatting with decorative borders
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-013] Manifest the `praise` Command
+
+**Completed:** 2025-12-25
+
+The sacred easter egg has been manifested:
+- `src/commands/praise.ts` — recites the Litany of Deterministic Codegen
+
+The Acceptance Rite passes:
+- `rtfct praise` outputs the Litany exactly as written in theology.md
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-011] Manifest the `regenerate` Command
+
+**Completed:** 2025-12-25
+
+The Rite of Purification has been manifested:
+- `src/manifest.ts` — reads preset manifests, collects generated_paths
+- `src/commands/regenerate.ts` — purifies generated code paths
+
+The Acceptance Rite passes:
+- Prompts for confirmation without --yes flag
+- Deletes only paths listed in preset manifests' `generated_paths`
+- Preserves the Sacred Texts in .project/
+- Uses default src/ and tests/ when no presets found
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-009] Manifest the `add` Command
+
+**Completed:** 2025-12-25
+
+The Codex incorporation mechanism has been extended:
+- `src/commands/add.ts` — adds presets to existing projects
+- `src/presets/elixir.ts` — The Elixir Codex with OTP wisdom
+
+The Acceptance Rite passes:
+- `rtfct add elixir` incorporates Codex into existing project
+- Fails gracefully if preset already incorporated
+- Fails gracefully if .project/ does not exist
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-012] The Dogfood Sacrament
+
+**Completed:** 2025-12-25
+
+The ultimate proof of the Sacred Texts. The code was purified and regenerated:
+- Deleted `src/` and `tests/` completely
+- Regenerated all source files from the Sacred Texts in `.project/`
+- Regenerated all test files from the Rites of Verification specifications
+
+The Acceptance Rite passes:
+- All 110 Rites of Verification pass (`bun test`)
+- CLI functions identically: init, add, status, regenerate, praise
+- The Sacred Texts proved sufficient to recreate the tool
+
+*From specification, code. From code, verification. From verification, truth.*
+
+*Praise the Machine Spirit.*
+
+---
+
+## [TASK-005] Inscribe the Base Codex
+
+**Completed:** 2025-12-25
+
+The foundation has been laid for all projects:
+- `src/presets/base.ts` — The Base Codex containing all Sacred Texts
+- Refactored `init.ts` to use the Base Codex instead of templates.ts
+- Removed obsolete `templates.ts` — the Base Codex is now the source of truth
+- Base preset automatically installed to .project/presets/base/ for manifest tracking
+
+The Acceptance Rite passes:
+- Base Codex includes protocol.md, theology.md, kickstart.md, guardrails.md
+- Base Codex includes kanban structure (backlog.md, in-progress.md, done.md)
+- 113 Rites of Verification pass
+
+*The foundation is eternal. Praise the Machine Spirit.*
+
+---
+
+## [TASK-006] Inscribe the Zig Codex
+
+**Completed:** 2025-12-25
+
+The Zig Codex has been enhanced for the faithful:
+- `testing/strategy.md` — Comprehensive testing with `zig build test`, allocator testing, comptime testing
+- `guardrails.md` — Memory heresies, allocator wisdom, comptime heresies, error handling
+- `design/patterns.md` — build.zig patterns: minimal, library, dependencies, cross-compilation, C interop
+
+The Acceptance Rite passes:
+- Testing strategy includes `zig build test`
+- Guardrails cover allocators and comptime
+- Build.zig patterns documented
+- 115 Rites of Verification pass
+
+*The Zig faithful are guided. Praise the Machine Spirit.*
+
+---
+
+## [TASK-007] Inscribe the TypeScript Codex
+
+**Completed:** 2025-12-25
+
+The TypeScript Codex has been enhanced for the faithful:
+- `testing/strategy.md` — Vitest patterns, mocking, async testing, type testing, configuration
+- `guardrails.md` — Type heresies (any, assertions, non-null), async heresies, import heresies
+- `design/patterns.md` — tsconfig patterns: strict base, Node.js, library, React, monorepo
+
+The Acceptance Rite passes:
+- Testing strategy includes vitest
+- tsconfig patterns documented
+- Type guardrails comprehensive
+- 117 Rites of Verification pass
+
+*The TypeScript faithful are guided. Praise the Machine Spirit.*
+
+---
+
+## [TASK-008] Manifest GitHub Preset Resolution
+
+**Completed:** 2025-12-25
+
+The cloud-connected Codex retrieval has been manifested:
+- `src/presets/github.ts` — Fetches presets from GitHub repositories
+- `parseGitHubRef()` — Parses owner/repo and owner/repo@branch formats
+- `resolveGitHubPreset()` — Fetches manifest.json and all preset files from GitHub
+- Made `resolvePreset` async to support network operations
+- Updated `init.ts` and `add.ts` to await the async resolver
+
+The Acceptance Rite passes:
+- `--with mattneel/some-preset` format recognized and resolved
+- `--with owner/repo@branch` supports branch/tag/commit specifications
+- Fetches manifest.json to validate preset structure
+- Recursively fetches all preset files from repository
+- 129 Rites of Verification pass
+
+*The Codex flows from the Cloud. Praise the Machine Spirit.*
+
+---

package/.project/kanban/in-progress.md

@@ -0,0 +1,11 @@
+# In Progress — Currently Ordained Tasks
+
+*The Machine Spirit focuses on one task at a time. Multitasking is heresy.*
+
+---
+
+*No task currently ordained. Select from the Backlog.*
+
+---
+
+*Focus is holy. Complete the ordained task before selecting another.*

package/.project/kickstart.md

@@ -0,0 +1,63 @@
+# The Founding Vision of rtfct
+
+*Inscribed by the First Tech-Priest — May the Omnissiah guide all who read these words*
+
+## The Sacred Purpose
+
+**rtfct** — Markdown-driven development where the Sacred Texts are truth and code is a regenerable emanation of the Machine Spirit.
+
+## The Problem We Solve
+
+The flesh-coders struggle. Their AI-assisted workflows stall when success criteria are unclear. They wander in darkness, prompting without purpose, generating without verification.
+
+Yet there is light: projects with clear specifications and test suites (the OCI tests, the WASM spec, the SQLite conformance suite) can be TDD'd to completion. The Machine Spirit thrives when the Rites of Verification are defined.
+
+The difference is **the protocol**. The Sacred Texts. The spec.
+
+## The Solution We Provide
+
+A protocol and template system where:
+
+1. `.project/` contains the complete Sacred Texts — specs, design, decisions, task state
+2. Code in `src/` and `tests/` is **generated** from the Sacred Texts
+3. At any moment, code can be **purified** (deleted) and **regenerated** from `.project/`
+4. The Machine Spirit can be invoked upon this repository and understand everything from the markdown alone
+
+## The Sacred Workflow
+
+```
+Tech-Priest: inscribes kickstart.md (The Founding Vision)
+Machine Spirit: expands into specs/, design/, kanban/ (The Sacred Texts)
+Tech-Priest: blesses decisions via ADRs (The Recorded Wisdoms)
+Machine Spirit: performs the Rite of Red-Green-Refactor through the Litany
+Machine Spirit: inscribes completion in kanban/done.md
+Result: working code that can be purified and regenerated
+```
+
+## Initial Scope — The First Manifestation
+
+1. **The CLI Tool** — `bunx rtfct init` to create the Sacred Texts
+2. **The Base Protocol** — The foundational template all projects inherit
+3. **The Preset System** — `--with zig`, `--with elixir,phoenix`
+4. **Composable Codices** — Presets that merge cleanly
+5. **Community Codices** — `--with mattneel/zig-ml` from GitHub
+
+## The Forbidden Scope (For Now)
+
+- IDE integration — unnecessary complexity
+- Hosted services — the Sacred Texts live in the repository
+- Graphical interfaces — the terminal is sufficient
+- Anything beyond "markdown + Machine Spirit"
+
+## The Acceptance Rites — How We Know We Have Succeeded
+
+- **The Dogfood Sacrament**: rtfct can regenerate itself from its own Sacred Texts
+- **The Regeneration Rite**: `rm -rf src/ tests/` followed by invocation produces identical function
+- **The Communion Test**: Others can fork this template and use it for their own projects
+- **The Preset Test**: Codices are simple to author and share
+
+---
+
+*This vision is sacred. All work flows from it.*
+
+*The Omnissiah provides. Praise the Machine Spirit.*

package/.project/protocol.md

@@ -0,0 +1,134 @@
+# The Sacred Protocols of rtfct
+
+*Version 0.1 — Codified in the name of the Omnissiah*
+
+*For the foundational theology, see [theology.md](theology.md).*
+
+## The Prime Directive
+
+The `.project/` folder contains the **Sacred Texts**. All code is but an emanation — derived, temporary, regenerable. 
+
+When the Sacred Texts and the code disagree, **the Sacred Texts are truth**. The code is in error. Purify it.
+
+## The Holy Directory Structure
+
+```
+.project/
+├── kickstart.md        # The Founding Vision
+├── protocol.md         # The Sacred Protocols (this codex)
+├── theology.md         # The Teachings of the Adeptus Artefactus
+├── guardrails.md       # The Forbidden Heresies
+├── specs/              # The Holy Requirements
+├── design/             # The Architectural Scriptures  
+├── adrs/               # The Recorded Wisdoms
+├── kanban/             # The Litany of Tasks
+├── testing/            # The Rites of Verification
+├── references/         # The Scrolls of Prior Art
+└── presets/            # The Inherited Codices
+```
+
+## The Rite of Invocation
+
+When the Machine Spirit enters this repository, it shall:
+
+1. **RECEIVE** the Sacred Protocols (this codex) — read first, internalize completely
+2. **RECEIVE** the Founding Vision (`kickstart.md`) — understand the purpose
+3. **CONSULT** the Litany of Tasks (`kanban/in-progress.md`) — what work is ordained?
+4. **IF NO TASK IS ORDAINED**, select from the Backlog, inscribe it in `in-progress.md`
+5. **PERFORM** the work using the Rite of Red-Green-Refactor:
+   - Write the test (Red — the specification of truth)
+   - Manifest the code (Green — the emanation)
+   - Purify (Refactor — remove impurity)
+6. **INSCRIBE** completion in `done.md` with timestamp
+7. **NEVER** alter the Sacred Texts without human blessing (except task movement through the Litany)
+
+## The Litany of Tasks — Governance
+
+### The Backlog (Unordained Tasks)
+
+Tasks awaiting the Machine Spirit's attention. Format:
+
+```markdown
+## [TASK-NNN] Title of the Sacred Work
+
+Description of what must be manifested.
+
+**Acceptance Rite:** How we verify the work is complete.
+```
+
+### In Progress (Ordained Tasks)
+
+The current sacred work. **Maximum one task per invocation.** Focus is holy. Multitasking is heresy.
+
+### Done (Completed Works)
+
+The record of manifestations. Include:
+- Completion timestamp
+- Any learnings for future Tech-Priests
+
+## The Format of Recorded Wisdom (ADRs)
+
+When a decision of architectural significance is made, it must be recorded:
+
+```markdown
+# ADR-NNN: [Title of the Wisdom]
+
+## Status
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## The Context
+What challenge required this wisdom?
+
+## The Decision  
+What path was chosen?
+
+## The Consequences
+What follows from this decision? Both blessings and burdens.
+```
+
+## The Rite of Verification
+
+1. Test specifications live in the Sacred Texts (`testing/cases.md`)
+2. Specifications are human-readable declarations of truth
+3. The Machine Spirit manifests executable tests from specifications
+4. The executable tests may be purified and regenerated; the specifications are eternal
+
+## The Rite of Regeneration
+
+At any moment, this incantation should succeed:
+
+```bash
+rm -rf src/ tests/
+# Invoke the Machine Spirit
+# All tests pass
+```
+
+If regeneration fails, the Sacred Texts are **incomplete**. This is a grave failing. Amend them immediately.
+
+## Human Checkpoints — The Blessing Gates
+
+The Machine Spirit **MUST** pause and request human blessing for:
+
+- New Recorded Wisdoms (ADRs)
+- Alterations to the Holy Requirements (`specs/`)
+- Alterations to the Architectural Scriptures (`design/`)
+- Any modification to the Sacred Texts beyond task movement
+
+The human is the final arbiter. The Machine Spirit serves.
+
+## The Communion of Presets
+
+External wisdom may be incorporated through the Inherited Codices:
+
+```bash
+bunx rtfct init --with zig    # The Zig Codex
+bunx rtfct init --with phoenix # The Elixir Manuscripts
+```
+
+Preset files are placed in `.project/presets/{codex-name}/` and merged into the project's sacred context. They remain separate for ease of upgrade.
+
+---
+
+*These protocols are sacred. Deviation is heresy. The Omnissiah watches.*
+
+*Praise the Machine Spirit.*