docs(readiness): advance grade E → D after parser implementation

KRL parser is now implemented in KRLAdapter.jl (Julia, Option B).
Lexer + recursive descent parser + AST + lowering all done; 5577 tests
pass. Document grammar coverage, known gaps (typechecker, R2 simplify
across compose boundaries), and path to C.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

READINESS.md

@@ -4,62 +4,92 @@
 # Component Readiness — KRL
 
 **Standard:** [CRG v2.0 STRICT](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)
-**Current Grade:** E
-**Assessed:** 2026-04-05 (promoted X → E after iteration 1)
+**Current Grade:** D
+**Assessed:** 2026-04-12 (promoted E → D after iteration 2)
 **Assessor:** Jonathan D.A. Jewell
 
 ---
 
-## Grade rationale (evidence for E — promoted from X)
+## Grade rationale (evidence for D — promoted from E)
 
-Grade E criterion: "At least 1 test, documented failures."
+Grade D criterion: "Works on some inputs, test matrix present."
 
 ### Evidence
 
-- **Grammar drafted:** `spec/grammar.ebnf` v0.1.0 — EBNF for all four KRL
-  operation families (CONSTRUCT / TRANSFORM / RESOLVE / RETRIEVE)
-- **Grammar overview:** `spec/grammar-overview.md` — prose introduction,
-  operator precedence, reserved words, known gaps
-- **Examples:** 4 runnable examples covering all 4 operation families
-  - `examples/trefoil.krl` — CONSTRUCT + RESOLVE + TRANSFORM
-  - `examples/figure_eight.krl` — CONSTRUCT + TRANSFORM
-  - `examples/query-by-jones.krl` — CONSTRUCT + RESOLVE + RETRIEVE
-  - `examples/tensor-and-close.krl` — CONSTRUCT with tensor + closure
-- **Smoke test:** `tests/smoke/grammar_smoke.sh` — 16 lexical checks against
-  the examples, all passing. Validates terminator presence, paren balance,
-  generator-argument shape, operation-family coverage.
-- **RSR compliance:** inherited from rsr-template-repo scaffold
-
-### What was tested (16 assertions)
-
-Per .krl example file:
-- Statement terminators (`;`) present
-- Parentheses balanced
-- No v0.2-reserved tokens (equivalent?, near, classify_by, prove) used prematurely
-- At least one operation family exercised
-
-### What is NOT tested (honest — documented failures)
-
-- **No parser.** The grammar is declared, not implemented. None of the
-  examples have been parsed by code.
-- **No AST.** Nothing reads a .krl file into a structured form.
-- **No typechecker.** Port-arity compatibility not verified.
-- **No TangleIR compilation.** No path from .krl source to
-  KRLAdapter.TangleIR yet.
-- **No error messages.** Absence of parser means absence of diagnostics.
+- **Parser implemented:** `KRLAdapter.jl/src/parser/` (Julia, Option B decision 2026-04-12)
+  - `lexer.jl` — full lexer with position tracking, `KRLLexError`
+  - `ast.jl` — all AST node types (`KRLProgram`, `KRLBinding`, `KRLGenerator`,
+    `KRLCompose`, `KRLTensor`, `KRLPrefixOp`, `KRLParenExpr`, `KRLIdentifier`,
+    `KRLQuery`, `KRLFilter`, `KRLIntValue`, `KRLStrValue`, `KRLIdentValue`)
+  - `parser.jl` — recursive descent, full v0.1.0 grammar
+  - `lower.jl` — AST → TangleIR lowering with `KRLLowerError`
+- **Grammar ambiguity resolved:** `;` as sequential composition only fires
+  inside parenthesised expressions (`in_parens=true`); at statement level `;`
+  is the terminator.
+- **Test matrix:** `KRLAdapter.jl/test/parser_test.jl` — 5 testsets, 57 tests
+  - Lexer: keywords, identifiers, integers, strings, operators, punctuation,
+    comments stripped, position tracking, lex error, unterminated string
+  - Parser: 20 grammar cases including all generators, let bindings, sequential
+    compose (with parens), tensor product, prefix ops, queries with `and` chains
+  - Parser errors: missing `;`, unrecognised token, missing index, zero index
+  - Example .krl files: all 4 examples in `krl/examples/` parse without error
+  - Lowering: sigma/sigma_inv → TangleIR, compose, trefoil, mirror, let binding,
+    unbound identifier error, query → KRLQueryPlan
+- **5577 tests pass** (full KRLAdapter.jl suite including parser tests)
+
+### Grammar coverage
+
+The implemented grammar (v0.1.0):
+
+| Construct | Status |
+|-----------|--------|
+| `let` binding | ✅ |
+| `sigma`, `sigma_inv`, `cup`, `cap` generators | ✅ |
+| Sequential composition `(a ; b)` | ✅ |
+| Tensor product `a \| b` | ✅ |
+| `close`, `mirror`, `simplify`, `normalise`, `classify` | ✅ |
+| `find where` queries with `and` | ✅ |
+| Parenthesised sub-expressions | ✅ |
+| Identifier references (let-bound) | ✅ |
+| Line comments `--` | ✅ |
+| String, integer, identifier filter values | ✅ |
+
+### What is NOT yet implemented (documented gaps — D grade)
+
+- **No typechecker.** Port-arity compatibility (e.g. composing a 2-strand
+  braid with a 3-strand tangle) not verified at parse time.
+- **R2 simplification across compose() boundaries.** `simplify_ir` detects
+  R2 bigons by arc-index overlap, but `compose()` renumbers arcs so adjacent
+  sigma/sigma_inv pairs are not detected. Tracked in `KRLAdapter.jl` issues.
+- **No pretty-printer.** `KRLProgram → string` round-trip not yet implemented.
+- **No RESOLVE family.** `classify` is parsed and lowered (identity) but
+  not dispatched to the query layer.
 
 ---
 
-## Path to D (alpha, test matrix + RSR)
+## Grade E rationale (retained for history)
+
+Grade E criterion: "At least 1 test, documented failures."
+
+### Evidence (iteration 1)
 
-1. Choose parser implementation language (tangle OCaml host, KRLAdapter
-   Julia, or sibling OCaml compiler — see `spec/grammar-overview.md`).
-2. Implement lexer + parser for v0.1.0 grammar.
-3. Define AST in chosen language.
-4. Add test matrix: parse tests (one per example), parse-fail tests (one
-   per malformed input), roundtrip tests (AST → pretty-print → parse).
-5. Scope documentation in this file: what KRL programs parse, what KRL
-   programs don't yet.
+- Grammar drafted: `spec/grammar.ebnf`, `spec/grammar-overview.md`
+- 4 examples in `examples/`
+- Shell smoke test: `tests/smoke/grammar_smoke.sh` (16 lexical assertions)
+
+---
+
+## Path to C (alpha-stable)
+
+After D: typechecker (port-arity + generator index validity), deeper TangleIR
+compilation correctness, annotation per-directory, dogfooding by parsing 20+
+KRL programs from the knot table. Fix R2 simplification across compose()
+boundaries.
+
+## Path to B (beta)
+
+After C: 6+ diverse external targets (knot researchers, DSL authors,
+topology educators) write KRL programs and report back.
 
 ## Path to C (alpha-stable)
 
@@ -86,10 +116,17 @@ Templated from rsr-template-repo. Zero KRL-specific content.
 - 4 examples/ programs
 - tests/smoke/grammar_smoke.sh (16 lexical assertions, all passing)
 
+### Iteration 2 (promoted to D — 2026-04-12)
+- Decision: Option B — Julia in KRLAdapter.jl
+- Implemented: lexer, AST, recursive-descent parser, lowering (KRLAdapter.jl)
+- Grammar ambiguity fixed: `;` as compose only inside parentheses
+- 57 dedicated parser tests + all 4 example files parse cleanly
+- 5577 total KRLAdapter.jl tests pass
+
 ## Review cycle
 
-Reassess on first parser implementation milestone, or if examples drift
-from what the grammar admits.
+Reassess on typechecker implementation or when 20+ knot-table programs
+have been parsed successfully.
 
 ---