chore(bmad):First story ready for dev!

Author: thelbane

docs/sprint-artifacts/1-1-scaffold-project-structure.md

@@ -0,0 +1,106 @@
+# Story 1.1: Scaffold Project Structure
+
+Status: ready-for-dev
+
+## Story
+
+As a developer,
+I want a standardized project layout,
+so that I can navigate and extend the compiler consistently.
+
+## Acceptance Criteria
+
+1. The repo contains `src/`, `tests/`, `grammar/`, `.github/workflows/ci.yml`, and `pyproject.toml`.
+2. The Python package uses `src/applejack/` layout with the modules and subpackages defined in `docs/architecture.md`.
+3. `tests/` and `tests/fixtures/` exist and follow `test_*.py` naming conventions.
+4. CLI entrypoint stubs exist at `src/applejack/cli.py` and `src/applejack/__main__.py`.
+5. All paths and names align with the architecture document.
+
+## Tasks / Subtasks
+
+- [ ] Create root structure files: `README.md`, `LICENSE`, `.gitignore`, `pyproject.toml`.
+- [ ] Create directories: `src/applejack/`, `grammar/`, `tests/`, `.github/workflows/`.
+- [ ] Add package skeleton under `src/applejack/`:
+  - [ ] `__init__.py`
+  - [ ] `__main__.py` (CLI stub)
+  - [ ] `cli.py` (CLI stub)
+  - [ ] `config.py`
+  - [ ] `errors.py`
+  - [ ] `lexer/`, `parser/`, `preprocessor/`, `transformer/`, `generator/`, `diagnostics/`, `utils/` (each with `__init__.py`)
+  - [ ] Placeholder modules: `lexer/tokens.py`, `parser/grammar_loader.py`, `parser/parse.py`, `parser/ast.py`,
+        `preprocessor/includes.py`, `preprocessor/macros.py`, `transformer/transform.py`, `generator/generate.py`,
+        `diagnostics/reporter.py`, `utils/io.py`
+- [ ] Add `tests/` skeleton with placeholder files: `test_grammar.py`, `test_parser.py`, `test_preprocessor.py`,
+      `test_transformer.py`, `test_generator.py`, `test_cli.py`, and `tests/fixtures/`.
+- [ ] Add `.github/workflows/ci.yml` stub to be finalized in Story 1.3.
+
+## Dev Notes
+
+### Developer Context (Scope)
+- This story is about scaffolding only; no feature implementations or parsing logic.
+- Keep modules empty or with minimal stubs that do not enforce behavior.
+- Hybrid CLI I/O is the architectural direction, but no runtime logic is needed here.
+
+### Technical Requirements
+- Language: Python 3.9+.
+- Follow PEP 8 naming conventions (snake_case, PascalCase, UPPER_SNAKE_CASE).
+- Keep filesystem I/O limited to CLI boundary and `utils/io.py` per architecture.
+- Errors should be raised internally and caught at the CLI boundary (no stdout errors).
+
+### Architecture Compliance
+- Maintain strict boundaries: Preprocessor → Parser → Transformer → Generator, no cross-layer imports.
+- AST definitions centralized in `parser/ast.py`.
+- Source code must live in `src/` (no top-level package modules).
+
+### Library/Framework Requirements
+- Architecture pins: Python 3.9.6, Lark 1.1.9, pytest 8.2.2.
+- CI uses GitHub Actions `actions/checkout@v4` and `actions/setup-python@v5`.
+- Web verification of latest versions was not conclusive; treat these pins as authoritative until explicitly updated.
+
+### File Structure Requirements
+- Must mirror the full tree documented in `docs/architecture.md` (see "Complete Project Directory Structure").
+- Ensure `grammar/` exists even if empty.
+- Ensure `tests/fixtures/` exists for future sample programs.
+
+### Testing Requirements
+- Provide empty test modules as placeholders; no tests required in this story.
+- Use `test_*.py` naming in `tests/`.
+
+### Latest Tech Information
+- Verify version pins before changing any tooling (current pins are from architecture).
+
+### Project Context Reference
+- No `project-context.md` found in repo.
+
+## Project Structure Notes
+
+- Alignment target is the architecture tree; deviations require explicit rationale.
+- CLI stubs should exist but remain thin until Story 1.2.
+
+### References
+
+- `docs/epics.md` — Epic 1, Story 1.1 acceptance criteria and notes.
+- `docs/architecture.md` — Project structure, boundaries, and tooling pins.
+- `docs/prd-applejack-v2.md` — Tech stack (Python, Lark, pytest) and Phase 1 scope.
+
+## Dev Agent Record
+
+### Context Reference
+
+- None (no context XML generated).
+
+### Agent Model Used
+
+gpt-5.2-codex
+
+### Debug Log References
+
+- None.
+
+### Completion Notes List
+
+- Ultimate context engine analysis completed - comprehensive developer guide created.
+
+### File List
+
+- `docs/sprint-artifacts/1-1-scaffold-project-structure.md`

docs/sprint-artifacts/sprint-status.yaml

@@ -36,8 +36,8 @@ tracking_system: file-system
 story_location: docs/sprint-artifacts
 
 development_status:
-  epic-1: backlog
-  1-1-scaffold-project-structure: backlog
+  epic-1: in-progress
+  1-1-scaffold-project-structure: ready-for-dev
   1-2-cli-skeleton-with-argparse: backlog
   1-3-ci-gate-with-pytest: backlog
   1-4-decide-parser-strategy-ast-shape: backlog

docs/sprint-artifacts/validation-report-2026-01-25.md

@@ -0,0 +1,207 @@
+# Validation Report
+
+**Document:** /Users/leefastenau/Code/applejack/docs/sprint-artifacts/1-1-scaffold-project-structure.md  
+**Checklist:** /Users/leefastenau/Code/applejack/.bmad/bmm/workflows/4-implementation/create-story/checklist.md  
+**Date:** 2026-01-25
+
+## Summary
+- Overall: 16/38 passed (42%)
+- Critical Issues: 4
+
+## Section Results
+
+### Critical Mission & Mistake Prevention
+Pass Rate: 5/8 (62%)
+
+⚠ **Reinventing wheels**  
+Evidence: Story focuses on scaffolding with explicit structure but no guidance on reuse of existing assets. Evidence of scope only.  
+Quote: "This story is about scaffolding only; no feature implementations or parsing logic." (L40)  
+Impact: Without reuse guidance, developers might recreate existing configuration or templates.
+
+✓ **Wrong libraries**  
+Evidence: Version pins and tooling are specified.  
+Quote: "Architecture pins: Python 3.9.6, Lark 1.1.9, pytest 8.2.2." (L55-L56)
+
+✓ **Wrong file locations**  
+Evidence: File structure is explicitly listed and required.  
+Quote: "Must mirror the full tree documented in `docs/architecture.md`" (L60-L62)
+
+⚠ **Breaking regressions**  
+Evidence: No regression guardrails beyond placeholder tests.  
+Quote: "Provide empty test modules as placeholders; no tests required in this story." (L65-L66)  
+Impact: No explicit guardrails against modifying existing files or CI changes.
+
+➖ **Ignoring UX**  
+Evidence: CLI-only context is implied but not explicitly stated in story.  
+Impact: UX concerns are non-applicable but should be explicitly noted.
+
+⚠ **Vague implementations**  
+Evidence: Tasks are listed but not scoped to "stub only" for each file.  
+Quote: "Keep modules empty or with minimal stubs that do not enforce behavior." (L41)  
+Impact: Some tasks could be interpreted as adding logic.
+
+➖ **Lying about completion**  
+Evidence: Story does not include completion verification mechanisms beyond acceptance criteria.  
+Impact: Not applicable for scaffolding-only story.
+
+✓ **Not learning from past work**  
+Evidence: Previous story intelligence is not applicable for Story 1.1.  
+Quote: "This story is about scaffolding only" (L40)
+
+### Exhaustive Analysis & Subprocesses
+Pass Rate: 0/3 (0%)
+
+➖ **Exhaustive analysis required**  
+Evidence: Instruction for validator, not a story requirement.
+
+➖ **Utilize subprocesses and subagents**  
+Evidence: Instruction for validator, not a story requirement.
+
+➖ **Competitive excellence mindset**  
+Evidence: Instruction for validator, not a story requirement.
+
+### Required Inputs & Workflow Context
+Pass Rate: 2/3 (66%)
+
+✓ **Story file provided**  
+Evidence: Story file exists with proper header and status.  
+Quote: "# Story 1.1: Scaffold Project Structure" (L1)
+
+✓ **Source documents referenced**  
+Evidence: References section includes epics, architecture, PRD.  
+Quote: "References ... `docs/epics.md` ... `docs/architecture.md` ... `docs/prd-applejack-v2.md`" (L80-L84)
+
+⚠ **Workflow variables and context**  
+Evidence: Story does not explicitly restate workflow variable context (story_dir, output_folder).  
+Impact: Not strictly required for dev implementation, but missing context.
+
+### Step 2 Source Analysis Coverage
+Pass Rate: 5/9 (56%)
+
+✓ **Epic objectives and business value**  
+Evidence: Story ties to epic value of standardized layout.  
+Quote: "As a developer, I want a standardized project layout..." (L7-L9)
+
+✓ **Story requirements and acceptance criteria**  
+Evidence: Acceptance criteria clearly listed.  
+Quote: "The repo contains `src/`, `tests/`, `grammar/`, ..." (L13-L17)
+
+✓ **Technical requirements and constraints**  
+Evidence: Python 3.9+, no runtime logic, PEP 8.  
+Quote: "Language: Python 3.9+." (L45)
+
+⚠ **Cross-story dependencies**  
+Evidence: Story mentions Story 1.2 for CLI logic but not other dependencies.  
+Quote: "CLI stubs should exist but remain thin until Story 1.2." (L77-L78)
+
+⚠ **Architecture deep-dive**  
+Evidence: Architecture constraints are included, but not all sections are summarized.  
+Quote: "Maintain strict boundaries: Preprocessor → Parser → Transformer → Generator" (L51-L52)  
+Impact: Some architecture constraints (logging, error handling) are partially captured.
+
+➖ **Previous story intelligence**  
+Evidence: Story 1.1 has no previous story.
+
+➖ **Git history analysis**  
+Evidence: Not applicable (no previous story).
+
+⚠ **Latest technical research**  
+Evidence: Notes indicate verification needed but no latest version findings.  
+Quote: "Web verification of latest versions was not conclusive" (L57-L58)  
+Impact: Missing current-version confirmation.
+
+✓ **Testing standards**  
+Evidence: Tests folder and naming specified.  
+Quote: "Use `test_*.py` naming in `tests/`." (L66-L67)
+
+### Disaster Prevention Gap Analysis
+Pass Rate: 3/8 (38%)
+
+⚠ **Reinvention prevention**  
+Evidence: No explicit reuse guidance or existing templates.  
+Impact: Developers may re-create structure inconsistently.
+
+✓ **Wrong libraries/frameworks**  
+Evidence: Version pins specified.  
+Quote: "Architecture pins: Python 3.9.6, Lark 1.1.9, pytest 8.2.2." (L55-L56)
+
+✓ **Wrong file locations**  
+Evidence: Structure requirements and architecture alignment.  
+Quote: "Must mirror the full tree documented in `docs/architecture.md`" (L60-L61)
+
+➖ **Database schema conflicts**  
+Evidence: Not applicable (no DB).
+
+⚠ **Security requirements**  
+Evidence: No explicit note that there is no auth/security model.  
+Impact: Could lead to unnecessary security scaffolding.
+
+⚠ **Performance requirements**  
+Evidence: Not mentioned in story.  
+Impact: Low for scaffolding but still a missing cross-cutting constraint.
+
+⚠ **Testing regressions**  
+Evidence: Placeholder tests only; no CI mention besides stub.  
+Quote: "Add `.github/workflows/ci.yml` stub" (L35)  
+Impact: CI expectations not reiterated.
+
+⚠ **Scope creep prevention**  
+Evidence: Scope noted but tasks include file creation without explicit "no logic".  
+Quote: "Keep modules empty or with minimal stubs" (L41)
+
+### LLM Optimization (Clarity & Structure)
+Pass Rate: 1/4 (25%)
+
+✓ **Scannable structure**  
+Evidence: Clear headings and bullets.  
+Quote: "## Acceptance Criteria" (L11) and "## Tasks / Subtasks" (L19)
+
+⚠ **Actionable instructions**  
+Evidence: Tasks are actionable, but some are large bundles (e.g., full module list).  
+Impact: Could be split for more explicit sequencing.
+
+⚠ **Unambiguous language**  
+Evidence: Some tasks imply creation but do not specify stub contents.  
+Impact: Risk of over-implementation.
+
+⚠ **Token efficiency**  
+Evidence: Story is concise, but lacks some critical signals (security, CI intent).  
+Impact: Adds ambiguity rather than verbosity.
+
+### Improvement Recommendations Section
+Pass Rate: 0/3 (0%)
+
+➖ **Critical misses list**  
+Evidence: Checklist expects recommendations in validation report, not story content.
+
+➖ **Enhancement opportunities list**  
+Evidence: Not applicable to story content.
+
+➖ **LLM optimization improvements**  
+Evidence: Not applicable to story content.
+
+## Failed Items
+
+- **Breaking regressions** — No explicit guardrails on preserving existing files/CI.  
+- **Latest technical research** — No validated latest versions beyond architecture pins.  
+- **Security requirements** — No explicit note that security/auth is out of scope.  
+- **Performance requirements** — No cross-cutting performance notes even as non-functional constraints.
+
+## Partial Items
+
+- **Reinventing wheels** — No reuse guidance; only scope.
+- **Vague implementations** — Some tasks can be misread as adding logic.
+- **Workflow variables and context** — Story does not restate artifact paths.
+- **Cross-story dependencies** — Only Story 1.2 called out.
+- **Architecture deep-dive** — Some architecture sections omitted (logging, error taxonomy).
+- **Testing regressions** — CI intent not explicit beyond stub.
+- **Scope creep prevention** — Scope written but task list could be more explicit.
+- **Actionable instructions** — Some tasks are large bundles.
+- **Unambiguous language** — Stub-only requirement not repeated per task.
+- **Token efficiency** — Missing critical constraints leads to ambiguity.
+
+## Recommendations
+
+1. **Must Fix:** Add explicit "no logic" guidance for each stub; add security/perf scope notes; clarify CI intent.  
+2. **Should Improve:** Call out no DB/auth explicitly; restate workflow artifact locations for dev reference.  
+3. **Consider:** Add explicit reuse guidance (don’t invent new structure beyond architecture).