first round of specs and code cleanups/fixes