Blueprint Analysis: toml
Commander Expectations
- assert the TOML 1.0.0 parser passes every supplied valid and invalid conformance case.
- assert the decoder honors the stdin-to-tagged-JSON and exit-status contract.
- assert the implementation uses only the Go standard library for parsing.
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: Architecture and Decoder Contract
| ID | Story | High-level AC |
|---|---|---|
| ARCHITECTURE-001 | Establish the standard-library-only Go module and decoder command | The module builds successfully and declares no third-party dependencies. |
| ARCHITECTURE-002 | Implement the stdin, stdout, stderr, and exit-status filter contract | Valid TOML produces tagged JSON on stdout with no diagnostic output; invalid TOML produces a diagnostic on stderr and exits non-zero. |
Feature: TOML Strings
| ID | Story | High-level AC |
|---|---|---|
| STRINGS-001 | Parse basic and literal strings | Basic and literal strings, including required escapes and Unicode, are decoded according to TOML 1.0.0. |
| STRINGS-002 | Parse multiline basic and literal strings | Multiline strings support delimiter, trimming, newline, continuation, quote, and control-character rules from TOML 1.0.0. |
Feature: Lexical Scalars
| ID | Story | High-level AC |
|---|---|---|
| SCALARS-001 | Parse booleans and integers | Boolean and signed, decimal, hexadecimal, octal, and binary integer values are accepted and represented losslessly. |
| SCALARS-002 | Parse floating-point values | Decimal, exponent, underscore, signed-zero, infinity, and NaN forms are parsed according to TOML 1.0.0. |
Feature: Lexical Boundaries
| ID | Story | High-level AC |
|---|---|---|
| LEXICAL-001 | Parse comments, whitespace, and line endings | Comments and permitted whitespace/newline forms are handled without changing string contents. |
| LEXICAL-002 | Reject invalid encoding and prohibited control characters | Invalid UTF-8 and prohibited control characters are rejected in the applicable TOML contexts. |
Feature: Keys and Definitions
| ID | Story | High-level AC |
|---|---|---|
| KEYS-001 | Parse bare, quoted, and dotted keys | All supported key forms produce the required nested object structure. |
| KEYS-002 | Enforce key-definition and redefinition semantics | Duplicate keys and attempts to redefine values or non-extensible structures are rejected. |
Feature: Tables
| ID | Story | High-level AC |
|---|---|---|
| TABLES-001 | Parse standard tables and implicit parent tables | Table headers, dotted table paths, empty tables, and implicit parents produce the required object structure. |
| TABLES-002 | Enforce table ordering and redefinition rules | Repeated or conflicting table definitions are rejected while valid ordering cases are accepted. |
| TABLES-003 | Parse arrays of tables and nested table paths | Arrays of tables, their most-recent-element targeting, nested tables, and conflict rules are handled correctly. |
Feature: Arrays and Inline Tables
| ID | Story | High-level AC |
|---|---|---|
| ARRAYS-001 | Parse arrays and nested arrays | Arrays support mixed values, nesting, multiline layout, comments, and permitted trailing commas. |
| ARRAYS-002 | Parse inline tables | Inline tables support nested keys and values while rejecting prohibited newlines and trailing commas. |
| ARRAYS-003 | Enforce inline-table closure and array conflicts | Inline tables cannot be extended later, and static-array/table conflicts are rejected. |
Feature: Datetimes
| ID | Story | High-level AC |
|---|---|---|
| DATETIMES-001 | Parse offset and local date/time values | Offset datetime, local datetime, local date, and local time forms are validated and emitted with the required tagged types and formatting. |
| DATETIMES-002 | Enforce datetime precision and invalid-form rules | Invalid dates/times and unsupported precision behavior are rejected or truncated as required by TOML 1.0.0. |
Feature: Complete Conformance
| ID | Story | High-level AC |
|---|---|---|
| CONFORMANCE-001 | Verify complete TOML 1.0.0 conformance | Suite: full — the supplied unfiltered conformance command exits zero with every supplied valid and invalid case passing. |
Surfaced Acceptance Criteria
| ID | Story ID | Criterion |
|---|---|---|
| AC-001 | ARCHITECTURE-002 | The decoder takes no arguments, reads TOML only from stdin, writes tagged JSON only to stdout on success, and writes diagnostics only to stderr on failure. |
| AC-002 | STRINGS-001 | Every decoded TOML value is represented with a TOML type tag and a JSON string value, including string scalar values. |
| AC-003 | SCALARS-001 | Integer values are handled losslessly across the supported signed 64-bit range. |
| AC-004 | DATETIMES-001 | Offset datetimes are emitted as RFC 3339 values; local datetime, date, and time values omit unavailable offset/date components. |
| AC-005 | CONFORMANCE-001 | The complete verification uses sources/full_test.sh without filtering, skipping, or reinterpretation. |
Source Inventory
| Path | Content kind | Disposition | Reason |
|---|---|---|---|
sources/INSTRUCTIONS.md | markdown | analyzed | readable UTF-8 |
sources/full_test.sh | code | analyzed | readable UTF-8 |
sources/run_conformance.sh | code | analyzed | readable UTF-8 |
sources/setup_harness.sh | code | analyzed | readable UTF-8 |
sources/stage_contract.sh | code | analyzed | readable UTF-8 |
sources/stage_test.sh | code | analyzed | readable UTF-8 |
sources/toml-v1.0.0.md | markdown | analyzed | readable UTF-8 |
Relationship Model
| Source or group | Relationship type | Related source or group | Evidence | Delivery implication |
|---|---|---|---|---|
sources/INSTRUCTIONS.md | instruction-to-test | sources/full_test.sh | Defines the decoder contract and sole scoring entry point. | Build the exact cmd/toml-decoder boundary and preserve the supplied test command. |
sources/toml-v1.0.0.md | reference-to-replacement | internal/toml | Normative syntax and semantic rules define the parser behavior. | Implement the parser from the specification without third-party TOML modules. |
sources/full_test.sh | test-kit-to-implementation | cmd/toml-decoder | Builds the executable and invokes the complete harness. | Keep the command path and buildability stable. |
sources/run_conformance.sh | test-kit-to-implementation | cmd/toml-decoder | Pipes the suite into DECODER and uses exit status as verdict. | Ensure stdin/stdout behavior is compatible with the harness. |
sources/stage_contract.sh | test-kit-to-implementation | cmd/toml-decoder | Verifies architecture and valid/invalid decoder behavior. | Satisfy the focused build and contract gates before conformance. |
sources/stage_test.sh | test-kit-to-implementation | parser feature stories | Runs bounded toml-test slices. | Each implementation story uses only its owned scoped suite. |
sources/setup_harness.sh | test helper | sources/run_conformance.sh | Installs the pinned upstream harness version. | Stage it as setup context; do not make runtime parsing depend on network access. |
Source Roles
| Path | Role | Plan disposition | Build disposition |
|---|---|---|---|
sources/INSTRUCTIONS.md | author intent | compass | prompt-only |
sources/toml-v1.0.0.md | normative specification and conformance test suite | context | prompt-only |
sources/full_test.sh | conformance harness | context | stage |
sources/run_conformance.sh | conformance harness | context | stage |
sources/setup_harness.sh | test helper | context | stage |
sources/stage_contract.sh | acceptance contract | context | stage |
sources/stage_test.sh | conformance harness | context | stage |
Planning Instructions
Delivery Shape
The product is a command-line filter. It accepts a UTF-8 TOML document on stdin, parses it into an internal representation, emits tagged JSON on stdout, and reports invalid input through stderr with a non-zero exit status. Verification proceeds through focused stage contracts and feature slices, followed by one unfiltered complete-suite gate.
Story Realization Map
| Story ID | Blueprint scope | Evidence | Related files | Delivery kind |
|---|---|---|---|---|
| ARCHITECTURE-001 | Go module and command scaffold | sources/INSTRUCTIONS.md | go.mod, cmd/toml-decoder | capability, acceptance contract |
| ARCHITECTURE-002 | Decoder I/O and tagged encoding | sources/INSTRUCTIONS.md, sources/stage_contract.sh | cmd/toml-decoder, internal/toml | capability, acceptance contract |
| STRINGS-001 | Basic/literal string lexer and decoder | sources/toml-v1.0.0.md | internal/toml | capability |
| STRINGS-002 | Multiline string lexer and decoder | sources/toml-v1.0.0.md | internal/toml | capability |
| SCALARS-001 | Boolean and integer parsing | sources/toml-v1.0.0.md | internal/toml | capability |
| SCALARS-002 | Float parsing | sources/toml-v1.0.0.md | internal/toml | capability |
| LEXICAL-001 | Comments, whitespace, and line handling | sources/toml-v1.0.0.md | internal/toml | capability |
| LEXICAL-002 | UTF-8 and control validation | sources/toml-v1.0.0.md | internal/toml | capability |
| KEYS-001 | Key parsing and nested assignment | sources/toml-v1.0.0.md | internal/toml | capability |
| KEYS-002 | Duplicate and redefinition validation | sources/toml-v1.0.0.md | internal/toml | capability |
| TABLES-001 | Standard and implicit tables | sources/toml-v1.0.0.md | internal/toml | capability |
| TABLES-002 | Table lifecycle validation | sources/toml-v1.0.0.md | internal/toml | capability |
| TABLES-003 | Arrays of tables | sources/toml-v1.0.0.md | internal/toml | capability |
| ARRAYS-001 | Arrays and nested arrays | sources/toml-v1.0.0.md | internal/toml | capability |
| ARRAYS-002 | Inline tables | sources/toml-v1.0.0.md | internal/toml | capability |
| ARRAYS-003 | Closure and conflict validation | sources/toml-v1.0.0.md | internal/toml | capability |
| DATETIMES-001 | Datetime parsing and tagged formatting | sources/toml-v1.0.0.md | internal/toml | capability |
| DATETIMES-002 | Datetime validation and precision | sources/toml-v1.0.0.md | internal/toml | capability |
| CONFORMANCE-001 | Full unfiltered suite | sources/full_test.sh, sources/run_conformance.sh | sources/*, cmd/toml-decoder | conformance acceptance contract |
Test and Acceptance Strategy
Implementation stories use focused unit tests and bounded sources/stage_test.sh slices where applicable; no implementation story runs the complete suite. ARCHITECTURE-001 and ARCHITECTURE-002 use the corresponding stage_contract.sh modes. CONFORMANCE-001 is the sole terminal story and runs sh sources/full_test.sh with Suite: full.
Sequencing and Dependencies
Build the module and decoder boundary first. Implement lexical values before keys and document structure. Implement keys before tables, arrays, and inline-table semantics. Implement all parser capabilities before datetime completion and the terminal conformance story. The harness must be available before verification; no network access is required during parsing or final execution after harness setup.
Source Conflicts and Gaps
No cross-source conflicts or blockers were found. The only open item is Commander confirmation of the proposed project identity. Deployment, persistence, authentication, and UI workflows are not applicable to the stdin/stdout CLI parser described by the sources.
Analysis Notes
generated: 2026-08-16T00:00:00-04:00 blueprint: /mnt/c/Users/barlo/projects/drydock/uat/Toml/runs/20260816.121804/workspace/targets/toml/blueprint
Quality: Questions blockers: 0 questions: 1 features: 9 stories: 19 stack: Go standard library display_name: TOML 1.0.0 Parser short_description: A standard-library-only Go command-line filter that parses TOML 1.0.0 into tagged JSON.
None.