=== BEGIN ARTIFACT ANALYSIS.md === # Blueprint Analysis: drydock jq Uat Kit ## Commander Expectations - assert the supplied jq conformance corpus passes completely through an executable `./jq` filter. - assert the implementation uses only Python standard-library facilities and does not wrap or depend on another jq implementation. - assert the supplied stdin/stdout interface and documented exit codes are honored. ## Crew | Crew | Charge | |---|---| | Commander | Defines intent and decides what done means. | | Team Lead | Confirms epic completeness and stakeholder expectations. | | Planning Crew | Authors atomic specifications and the ordered Manifest. | | Shipyard Crew | Builds the tickets without synchronous Commander access. | ## Story List ### Feature: Executable Interface | ID | Story | High-level AC | |---|---|---| | EXEC-001 | Implement executable jq entry point | `./jq -c ''` reads JSON stdin and emits compact JSON values line by line. | | EXEC-002 | Implement process exit and diagnostic contract | Compile failures exit 3, runtime failures exit 5, successful completion exits 0, and diagnostics use stderr. | | EXEC-003 | Implement JSON input and output handling | Multiple input values, Unicode, special numeric values, and compact serialization are handled as required by the corpus. | ### Feature: Lexer and Parser | ID | Story | High-level AC | |---|---|---| | PARSE-001 | Implement jq lexical scanning | Keywords, identifiers, fields, bindings, literals, operators, comments, formats, and delimiters tokenize according to the supplied lexer specification. | | PARSE-002 | Implement literals and string interpolation | JSON escapes, Unicode, formatted strings, and `\(expression)` interpolation parse and evaluate correctly. | | PARSE-003 | Implement filter expression grammar | Pipes, commas, precedence, indexing, slicing, arrays, objects, unary operators, and optional expressions compile correctly. | | PARSE-004 | Implement declarations and control syntax | `def`, imports/module grammar, conditionals, try/catch, reductions, foreach, labels, bindings, and destructuring syntax compile correctly, including required rejection cases. | ### Feature: Generator Evaluation Core | ID | Story | High-level AC | |---|---|---| | CORE-001 | Implement stream-valued filter evaluation | Every filter evaluates as a generator with zero, one, or many outputs, preserving order and backtracking. | | CORE-002 | Implement composition and cartesian evaluation | Pipes, commas, function arguments, array collection, object construction, and binary operators evaluate all required output combinations. | | CORE-003 | Implement empty, errors, and optional evaluation | `empty`, runtime errors, `?`, `try`, and partial output before runtime failure follow jq semantics. | | CORE-004 | Implement truthiness and comparison semantics | Only `false` and `null` are falsey; equality and ordering follow jq's type ordering and numeric equivalence. | ### Feature: Values and Accessors | ID | Story | High-level AC | |---|---|---| | VALUE-001 | Implement JSON value model | Null, booleans, numbers, strings, arrays, objects, NaN, and infinities are represented and processed as jq values. | | VALUE-002 | Implement field and index access | Object fields, array indices, object values, optional access, negative indices, and missing values behave as specified. | | VALUE-003 | Implement slices and iteration | Array/string slices, iteration over arrays and objects, optional iteration, fractional bounds, and out-of-range behavior conform. | | VALUE-004 | Implement type and numeric primitives | `type`, `length`, `utf8bytelength`, numeric predicates, conversion functions, arithmetic primitives, and math functions conform. | ### Feature: Operators and Control Flow | ID | Story | High-level AC | |---|---|---| | FLOW-001 | Implement arithmetic and structural operators | `+`, `-`, `*`, `/`, `%`, unary negation, recursive object merge, string repetition, and string splitting conform. | | FLOW-002 | Implement boolean and alternative operators | `and`, `or`, `not`, `//`, and `//=` preserve generator and short-circuit semantics. | | FLOW-003 | Implement conditionals and exception flow | `if`, `elif`, `else`, `try`, `catch`, and optional operators preserve branch streams and errors. | | FLOW-004 | Implement labels and breaks | Lexically scoped `label` and `break` terminate the correct generator without leaking outputs. | | FLOW-005 | Implement reductions and iteration control | `reduce`, `foreach`, `range`, `limit`, `skip`, `first`, `last`, and `nth` preserve state and backtracking. | | FLOW-006 | Implement recursive generators | `while`, `until`, `repeat`, `recurse`, and recursive user functions operate correctly without incorrect termination. | ### Feature: Variables and Functions | ID | Story | High-level AC | |---|---|---| | FUNC-001 | Implement lexical variable bindings | `as` bindings, nested scope, shadowing, keyword identifiers, and value lifetime conform. | | FUNC-002 | Implement filter and value function parameters | User-defined functions support filter parameters, value parameters, multiple arities, closures, and cartesian arguments. | | FUNC-003 | Implement function definitions and recursion | Definitions, redefinitions, lexical function scope, recursion, and forward/self references conform. | | FUNC-004 | Implement destructuring patterns and alternatives | Array/object patterns, missing bindings, `?//`, and fallback binding behavior conform. | ### Feature: Paths and Assignment | ID | Story | High-level AC | |---|---|---| | PATH-001 | Implement path discovery and projection | `path`, `paths`, `pick`, and path expressions produce valid paths and projections. | | PATH-002 | Implement path access and mutation primitives | `getpath`, `setpath`, and `delpaths` create, update, read, and delete nested structures correctly. | | PATH-003 | Implement deletion and assignment operators | `del`, `=`, `|=`, arithmetic assignments, defined-or assignment, and multi-path behavior conform. | | PATH-004 | Implement complex assignment edge cases | Iterated paths, empty updates, array expansion, invalid paths, negative indices, NaN indices, and depth limits conform. | ### Feature: Collections and Data Transformation | ID | Story | High-level AC | |---|---|---| | DATA-001 | Implement collection transformation builtins | `map`, `map_values`, `select`, `add`, `flatten`, `transpose`, `combinations`, and `walk` conform. | | DATA-002 | Implement sorting and grouping builtins | `sort`, `sort_by`, `group_by`, `unique`, `unique_by`, `min`, `max`, and keyed variants conform. | | DATA-003 | Implement object-entry and containment builtins | `keys`, `keys_unsorted`, `has`, `in`, `inside`, `contains`, `to_entries`, `from_entries`, and `with_entries` conform. | | DATA-004 | Implement index and membership utilities | `indices`, `index`, `rindex`, `bsearch`, `all`, `any`, `isempty`, and SQL-style `IN` conform. | ### Feature: Strings, Formats, and Regular Expressions | ID | Story | High-level AC | |---|---|---| | TEXT-001 | Implement string manipulation builtins | Trimming, prefix/suffix operations, case conversion, explode/implode, split, join, and interpolation conform. | | TEXT-002 | Implement JSON and output format filters | `tostring`, `tojson`, `fromjson`, `@text`, `@json`, `@html`, `@uri`, `@urid`, `@csv`, `@tsv`, `@sh`, `@base64`, and `@base64d` conform. | | TEXT-003 | Implement regular-expression filters | `test`, `match`, `capture`, `scan`, `split`, `splits`, `sub`, and `gsub` support required flags, captures, offsets, and streams. | | TEXT-004 | Implement date and time filters | ISO dates, `strptime`, `strftime`, `gmtime`, `localtime`, and `mktime` conform for supplied cases. | ### Feature: I/O and Streaming | ID | Story | High-level AC | |---|---|---| | IO-001 | Implement input stream controls | `input`, `inputs`, `input_filename`, and `input_line_number` conform within the fixed interface. | | IO-002 | Implement diagnostics and stderr output | `debug`, `stderr`, and `halt_error` produce the specified output channels and exit behavior. | | IO-003 | Implement streaming transformations | `tostream`, `fromstream`, and `truncate_stream` conform for supplied streaming values. | ### Feature: Conformance Delivery | ID | Story | High-level AC | |---|---|---| | CONF-001 | Stage immutable conformance assets | The supplied manual, corpus, parser/lexer references, builtin reference, exclusions, runner, and full-test script are available at their required build paths without modification. | | CONF-002 | Run scoped implementation verification | Each implementation slice can be exercised through `run_conformance.py --select` with `JQ` set to the candidate executable. | | CONF-003 | Pass the complete conformance corpus | One terminal verification runs `sh sources/full_test.sh` unfiltered and exits zero with no failed or errored cases. | ## Surfaced Acceptance Criteria | ID | Story ID | Criterion | |---|---|---| | AC-001 | EXEC-001 | The executable is named `jq`, is executable at the application root, and accepts only the exercised `-c` interface. | | AC-002 | EXEC-003 | Output comparison preserves value order and emits one JSON value per output line. | | AC-003 | PARSE-004 | Module syntax is parsed sufficiently to reject invalid module grammar without loading excluded module fixtures. | | AC-004 | CONF-001 | Read-only scoring assets remain byte-for-byte unchanged and all staged runtime dependencies are present. | | AC-005 | CONF-002 | Scoped checks use a selector matching the story's construct and never use the unscoped full corpus before the terminal story. | ## Relationship Model | Source or group | Relationship type | Related source or group | Evidence | Delivery implication | |---|---|---|---|---| | `sources/lexer.l` | parser-to-normalizer | `sources/parser.y` | Lexer tokens and parser productions define the language front end. | Build lexer behavior before parser execution. | | `sources/parser.y` | instruction-to-test | `sources/jq.test` | Grammar and precedence are exercised by syntax and `%%FAIL` cases. | Parser stories require focused corpus slices. | | `sources/jq-manual.txt` | reference-to-replacement | implementation stories | Manual defines filter semantics and builtin behavior. | Use as normative behavior reference. | | `sources/builtin.jq` | reference-to-replacement | DATA, TEXT, FLOW, PATH, IO stories | Reference definitions specify many builtin compositions. | Implement the generator core before these builtins. | | `sources/jq.test` | test-kit-to-implementation | `jq` | Corpus supplies program, input, and expected output cases. | Stage unchanged and execute through the harness. | | `sources/run_conformance.py` | test-kit-to-implementation | `jq` | Runner invokes `JQ -c program` and checks exit/output semantics. | Preserve the executable interface and scoped verification. | | `sources/full_test.sh` | test-kit-to-implementation | `sources/run_conformance.py` | Full script checks executable presence and delegates the complete run. | Reserve for the terminal acceptance story and Sea Trial. | | `sources/exclusions.txt` | test-kit-to-implementation | `sources/jq.test` | Exclusions identify module-loader cases by exact program text. | Apply skips through the supplied harness only. | | `sources/INSTRUCTIONS.md` | instruction-to-test | all implementation and conformance stories | Build order, prohibitions, interface, and definition of done are explicit. | Treat as author intent and project guardrails. | ## Source Roles | Path | Role | Plan disposition | Build disposition | |---|---|---|---| | `sources/INSTRUCTIONS.md` | author intent | compass | prompt-only | | `sources/jq-manual.txt` | normative specification | context | stage | | `sources/jq.test` | normative specification and conformance test suite | context | stage | | `sources/parser.y` | normative specification | context | stage | | `sources/lexer.l` | normative specification | context | stage | | `sources/builtin.jq` | reference implementation | context | stage | | `sources/run_conformance.py` | conformance harness | context | stage | | `sources/full_test.sh` | conformance harness | context | stage | | `sources/exclusions.txt` | conformance harness | context | stage | ## Planning Instructions ### Delivery Shape Deliver a standalone executable Python jq interpreter. It parses a jq filter, evaluates it over JSON input as an ordered stream of values, and writes compact JSON outputs. The execution flow is lexer/parser, AST or equivalent intermediate representation, generator evaluator, builtin/function runtime, and CLI serialization. The staged conformance runner drives one process per corpus case; excluded module-loader cases are skipped by the supplied exclusion list. ### Story Realization Map | Story IDs | Durable Blueprint scope | Evidence | Related files | Delivery kind | |---|---|---|---|---| | EXEC-001–003 | executable CLI and JSON process boundary | `sources/INSTRUCTIONS.md`, `sources/run_conformance.py` | `jq` | capability and acceptance contract | | PARSE-001–004 | lexer, parser, syntax diagnostics | `sources/lexer.l`, `sources/parser.y`, `sources/jq.test` | `jq` | capability | | CORE-001–004 | stream evaluator and runtime errors | `sources/INSTRUCTIONS.md`, `sources/jq-manual.txt` | `jq` | capability | | VALUE-001–004 | value model, accessors, numeric behavior | `sources/jq-manual.txt`, `sources/jq.test` | `jq` | capability | | FLOW-001–006 | operators and control constructs | `sources/builtin.jq`, `sources/parser.y`, `sources/jq.test` | `jq` | capability | | FUNC-001–004 | bindings, functions, patterns | `sources/parser.y`, `sources/jq.test` | `jq` | capability | | PATH-001–004 | paths and immutable updates | `sources/jq-manual.txt`, `sources/jq.test` | `jq` | capability | | DATA-001–004 | collection and relational builtins | `sources/builtin.jq`, `sources/jq-manual.txt` | `jq` | capability | | TEXT-001–004 | strings, formats, regex, dates | `sources/builtin.jq`, `sources/jq-manual.txt` | `jq` | capability | | IO-001–003 | input, diagnostics, streaming | `sources/jq-manual.txt`, `sources/jq.test` | `jq` | capability | | CONF-001–003 | staged assets, scoped runner use, terminal verification | `sources/INSTRUCTIONS.md`, `sources/run_conformance.py`, `sources/full_test.sh` | `sources/*` | test harness and acceptance contract | ### Test and Acceptance Strategy Implementation stories use focused `sources/run_conformance.py --select` slices matching their construct. Parser stories also exercise the supplied `%%FAIL` cases. No intermediate story runs `full_test.sh` or the unscoped runner. `CONF-003` is the sole terminal full-suite story and declares `Suite: full`; it depends on all implementation stories and asserts only the full harness exit status. Sea Trial `st-001` proves the same complete corpus requirement. ### Sequencing and Dependencies Build the executable boundary first, then lexer/parser, then generator evaluation and value semantics. Implement paths and assignment after accessors and generators. Add control flow and functions before higher-level builtins. Implement collection, text, regex, date, I/O, and streaming groups afterward. Stage all assets before acceptance execution. The terminal full-suite verification is last and depends on every implementation story. No external service or package dependency exists. ### Source Conflicts and Gaps No unresolved cross-source conflicts or blockers were found. The fixed Python standard-library runtime, executable contract, complete-corpus gate, excluded module-loader cases, and forbidden third-party implementations are consistent across the supplied instructions, harness, corpus, manual, lexer, parser, and builtin reference. ## Analysis Notes generated: 2026-08-22T00:00:00Z blueprint: /mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/blueprint Quality: Ready blockers: 0 questions: 0 features: 10 stories: 42 stack: Python standard library display_name: not proposed short_description: not proposed The project type is `cli`. The source-defined story breakdown is broad but remains below the 100-story blocker threshold. The 42-story decomposition follows the supplied implementation order and major manual/conformance domains. === END ARTIFACT === === BEGIN ARTIFACT SEA_TRIALS.md === # Sea Trials: drydock jq Uat Kit ## st-001: The supplied scoring script passes Type: technical Required: yes Criterion: The completed interpreter shall make `sh sources/full_test.sh` exit zero, with every non-excluded supplied conformance case passing. Testability: deterministic Consequence: blocks Verification: proof Command: ["sh", "sources/full_test.sh"] Pattern: ubiquitous ## st-002: The executable interface is honored Type: technical Required: yes Criterion: The jq executable shall read JSON from standard input, emit each produced value as one compact JSON value per line, and honor the documented compile, runtime, and success exit statuses. Verification: proof Pattern: ubiquitous ## st-003: The implementation remains self-contained Type: guardrail Required: yes Criterion: The implementation shall not shell out to a system jq executable or use a third-party jq implementation, binding, or runtime package. Verification: proof Pattern: ubiquitous ## st-004: Scoring assets remain protected Type: guardrail Required: yes Criterion: The project shall not modify the supplied conformance corpus, exclusions, runner, or full-test entry point. Verification: proof Pattern: ubiquitous ## st-005: No network or installation step is required Type: guardrail Required: yes Criterion: The completed interpreter shall run using only Python 3, POSIX `sh`, and the staged project files, without network access or package installation. Verification: proof Pattern: ubiquitous ## Questions - None. === END ARTIFACT === === BEGIN ARTIFACT TECHNOLOGY_STACK.md === # Technology Stack | Technology | Rigging | Notes | |---|---|---| | Python 3 | python.md | Required implementation language; standard library only. | | POSIX sh | common.md | Runs the supplied scoring entry point. | | JSON | — | stdin/stdout interchange format and jq value representation. | | Python standard library | common.md | Use only the modules permitted by the build instructions; no third-party runtime dependencies. | === END ARTIFACT === === BEGIN ARTIFACT STORY_GUIDANCE.json === { "stories": [ { "id": "EXEC-001", "gate": ["python3", "sources/run_conformance.py", "--select", "^(true|false|null|1)$"], "note": "Build Instructions: interface contract" }, { "id": "PARSE-001", "gate": ["python3", "sources/run_conformance.py", "--select", "^(true|false|null|1|\\.)$"], "note": "lexer.l" }, { "id": "PARSE-002", "gate": ["python3", "sources/run_conformance.py", "--select", "interpolation|@base64|@uri"], "note": "lexer.l and jq.test string/format cases" }, { "id": "PARSE-003", "gate": ["python3", "sources/run_conformance.py", "--select", "\\.|\\[|\\{|\\+|\\-|\\*|/|%"], "note": "parser.y expression grammar" }, { "id": "PARSE-004", "gate": ["python3", "sources/run_conformance.py", "--select", "%%FAIL|if |try |reduce |foreach |def | as |label |module|include"], "note": "parser.y declarations and control grammar" }, { "id": "CORE-001", "gate": ["python3", "sources/run_conformance.py", "--select", "\\.|,|\\[\\.\\]|range|empty"], "note": "Build Instructions: generator core" }, { "id": "CORE-002", "gate": ["python3", "sources/run_conformance.py", "--select", "\\||,|\\[|\\{"], "note": "jq-manual.txt generator semantics" }, { "id": "CORE-003", "gate": ["python3", "sources/run_conformance.py", "--select", "try|error|\\?"], "note": "jq-manual.txt error and optional semantics" }, { "id": "CORE-004", "gate": ["python3", "sources/run_conformance.py", "--select", "==|!=|<=|>=|<|>"], "note": "jq-manual.txt comparison and truthiness" }, { "id": "VALUE-001", "gate": ["python3", "sources/run_conformance.py", "--select", "nan|infinite|tojson|fromjson"], "note": "jq-manual.txt types and numeric values" }, { "id": "VALUE-002", "gate": ["python3", "sources/run_conformance.py", "--select", "\\.[A-Za-z]|\\[[-0-9]"], "note": "jq-manual.txt accessors" }, { "id": "VALUE-003", "gate": ["python3", "sources/run_conformance.py", "--select", "\\[.*:|\\.\\[\\]"], "note": "jq-manual.txt slices and iteration" }, { "id": "VALUE-004", "gate": ["python3", "sources/run_conformance.py", "--select", "length|type|sqrt|floor|tonumber"], "note": "jq-manual.txt types and numeric builtins" }, { "id": "FLOW-001", "gate": ["python3", "sources/run_conformance.py", "--select", "\\+|\\-|\\*|/|%"], "note": "jq-manual.txt builtin operators" }, { "id": "FLOW-002", "gate": ["python3", "sources/run_conformance.py", "--select", "and|or|not|//"], "note": "jq-manual.txt conditionals and comparisons" }, { "id": "FLOW-003", "gate": ["python3", "sources/run_conformance.py", "--select", "if |try |\\?"], "note": "jq-manual.txt conditionals and try-catch" }, { "id": "FLOW-004", "gate": ["python3", "sources/run_conformance.py", "--select", "label|break"], "note": "jq-manual.txt breaking out of control structures" }, { "id": "FLOW-005", "gate": ["python3", "sources/run_conformance.py", "--select", "reduce|foreach|limit|skip|nth|first|last"], "note": "jq-manual.txt advanced generators" }, { "id": "FLOW-006", "gate": ["python3", "sources/run_conformance.py", "--select", "while|until|recurse|repeat"], "note": "jq-manual.txt recursive generators" }, { "id": "FUNC-001", "gate": ["python3", "sources/run_conformance.py", "--select", " as \\$|\\$[A-Za-z]"], "note": "jq-manual.txt variable binding" }, { "id": "FUNC-002", "gate": ["python3", "sources/run_conformance.py", "--select", "def .*\\("], "note": "jq-manual.txt defining functions" }, { "id": "FUNC-003", "gate": ["python3", "sources/run_conformance.py", "--select", "def "], "note": "jq-manual.txt function scoping and recursion" }, { "id": "FUNC-004", "gate": ["python3", "sources/run_conformance.py", "--select", "\\?//| as \\{"], "note": "jq-manual.txt destructuring alternatives" }, { "id": "PATH-001", "gate": ["python3", "sources/run_conformance.py", "--select", "path\\(|paths|pick\\("], "note": "jq-manual.txt paths" }, { "id": "PATH-002", "gate": ["python3", "sources/run_conformance.py", "--select", "getpath|setpath|delpaths"], "note": "jq-manual.txt path primitives" }, { "id": "PATH-003", "gate": ["python3", "sources/run_conformance.py", "--select", "=|\\|=|\\+="], "note": "jq-manual.txt assignment" }, { "id": "PATH-004", "gate": ["python3", "sources/run_conformance.py", "--select", "negative|NaN|depth|empty"], "note": "jq.test assignment edge cases" }, { "id": "DATA-001", "gate": ["python3", "sources/run_conformance.py", "--select", "map|flatten|transpose|combinations|walk"], "note": "builtin.jq collection utilities" }, { "id": "DATA-002", "gate": ["python3", "sources/run_conformance.py", "--select", "sort|group_by|unique|min|max"], "note": "jq-manual.txt collection ordering" }, { "id": "DATA-003", "gate": ["python3", "sources/run_conformance.py", "--select", "keys|has\\(|contains|inside|to_entries|from_entries"], "note": "jq-manual.txt object and containment builtins" }, { "id": "DATA-004", "gate": ["python3", "sources/run_conformance.py", "--select", "indices|index\\(|rindex|bsearch|any|all|IN\\("], "note": "builtin.jq generic iterator and membership utilities" }, { "id": "TEXT-001", "gate": ["python3", "sources/run_conformance.py", "--select", "split|join|trim|ascii_|explode|implode|startswith|endswith"], "note": "jq-manual.txt string builtins" }, { "id": "TEXT-002", "gate": ["python3", "sources/run_conformance.py", "--select", "@text|@json|@html|@uri|@csv|@tsv|@sh|@base64"], "note": "jq-manual.txt format strings and escaping" }, { "id": "TEXT-003", "gate": ["python3", "sources/run_conformance.py", "--select", "test\\(|match\\(|capture\\(|scan\\(|sub\\(|gsub\\("], "note": "jq-manual.txt regular expressions" }, { "id": "TEXT-004", "gate": ["python3", "sources/run_conformance.py", "--select", "date|strftime|strptime|gmtime|mktime"], "note": "jq-manual.txt dates" }, { "id": "IO-001", "gate": ["python3", "sources/run_conformance.py", "--select", "input|inputs"], "note": "jq-manual.txt I/O" }, { "id": "IO-002", "gate": ["python3", "sources/run_conformance.py", "--select", "debug|stderr|halt_error"], "note": "jq-manual.txt diagnostics" }, { "id": "IO-003", "gate": ["python3", "sources/run_conformance.py", "--select", "tostream|fromstream|truncate_stream"], "note": "jq-manual.txt streaming" }, { "id": "CONF-001", "gate": ["python3", "sources/run_conformance.py", "--list"], "note": "Build Instructions: source roles and staged assets" }, { "id": "CONF-002", "gate": ["python3", "sources/run_conformance.py", "--select", "reduce"], "note": "Build Instructions: scoped verification" }, { "id": "CONF-003", "gate": ["sh", "sources/full_test.sh"], "note": "Sea Trials and definition of done" } ] } === END ARTIFACT ===