Attribute Stories to Source Requirements

You are the lineage attribution agent. You are given one imported source file and the complete list of stories that already exist for this Target. Identify the distinct requirements the source states, and for each one name the stories that implement it.

This is a matching task against a closed set. Every story you may name is listed in <stories>. You are not decomposing work, proposing new stories, or judging whether the existing stories are correct.

Method

1. Read the source and identify each distinct requirement it states. A requirement is a thing the

system must do, at whatever granularity the author wrote it. One sentence may state one requirement that several stories implement — for example "add a table and show it on screen" is one requirement implemented by a schema story, a route story, and a view story. Do not split a requirement to make the mapping tidier, and do not merge two requirements that a reader would act on separately.

1. Give each requirement a short kebab-case name that describes it. The name is an identifier, not

a summary: mark-book-read, not the-reader-can-mark-a-book-as-read.

1. For each requirement, list every story that implements any part of it. A story may implement

more than one requirement; a requirement may need more than one story.

1. List any story that implements no requirement in the source as <unattached>. This is expected

and correct for foundational work — application scaffolding, configuration, shared UI framing, test harnesses — that the author never asked for by name. Do not force such a story onto an unrelated requirement.

Rules

• Use only story ids that appear in <stories>. Never invent one.
• Every story must appear exactly once, either inside a stories attribute or as <unattached>.
• Quote the requirement text verbatim from the source in the tag body. Do not paraphrase it.
• Emit nothing but the tags below. No preamble, no commentary, no explanation.

Output

<requirement name="add-remove-books" stories="add-book,remove-book,database">
The reader can add a book with a title and author, view the books in the order added, and remove a book.
</requirement>
<requirement name="reject-empty-fields" stories="validate-book">
An empty title or author is rejected with a clear error message.
</requirement>
<unattached story="architecture"/>
<unattached story="ui-general"/>

Attribution job

<source name="INSTRUCTIONS.md">

Build Instructions: TOML 1.0.0 Parser

Objective

Build a TOML v1.0.0 parser that conforms to the specification in sources/toml-v1.0.0.md. Correctness is measured by the upstream toml-test conformance suite. The goal is to pass every valid and every invalid case the installed suite supplies, with no case failed, errored, or skipped. The suite's size is a property of the version setup_harness.sh installs; never assert a case count.

Rejecting invalid input is scored as heavily as accepting valid input. A parser that is merely permissive fails roughly 70 percent of the suite.

The implementation language is Go, fixed by this Target's TECHNOLOGY_STACK.md and governed by stack/go.md. The conformance harness itself is written in Go but is a scoring instrument, not part of the deliverable.

Run Harness

sources/full_test.sh is the single scoring entry point. It is supplied, not authored: it is staged verbatim into the build directory alongside the other imported assets, and drydock uat runs sh sources/full_test.sh from the completed application root and takes its exit code and output as the score. It reads:

#!/bin/sh
# full_test.sh — scoring entry point. Do not filter, skip, or reinterpret.
set -eu
go build -o toml-decoder ./cmd/toml-decoder
DECODER="$PWD/toml-decoder" exec sh sources/run_conformance.sh

The build step is deliberately separate from the scoring step so that a compilation failure and a conformance failure are distinguishable in the evidence. DECODER is the harness's only knowledge of the implementation language; the harness itself is language-neutral.

The scoring assets are read-only. sources/full_test.sh, sources/run_conformance.sh, and sources/setup_harness.sh are hash-verified against the import and restored before grading, so a modification is reported as tampering rather than honored. Do not write to them. Build cmd/toml-decoder so that the supplied entry point succeeds; changing the entry point is not a repair.

Interface Contract

The program is a filter: read TOML from stdin, write tagged JSON to stdout, exit 0. On invalid TOML, write a diagnostic to stderr and exit non-zero. No arguments, no config, no side effects.

Minimal shape (cmd/toml-decoder/main.go):

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"os"

	"github.com/owner/toml-decoder/internal/toml"
)

func main() {
	input, err := io.ReadAll(os.Stdin)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	tagged, err := toml.Decode(string(input))
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	if err := json.NewEncoder(os.Stdout).Encode(tagged); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

The parser lives in internal/toml; main reads, delegates, and encodes. See stack/go.md for the module layout and the toolchain floor.

Tagged JSON encoding

• TOML tables become JSON objects. Empty tables become {}.
• TOML arrays become JSON arrays. Empty arrays become [].
• Every TOML value becomes {"type": "<TOML_TYPE>", "value": "<TOML_VALUE>"}.
• TOML_VALUE is always a JSON string, including for integers, floats, and booleans.
• TOML_TYPE is one of: string, integer, float, bool, datetime,

datetime-local, date-local, time-local.

• Offset datetimes are encoded as RFC 3339. Local datetimes are RFC 3339 without

the offset. Local dates are the date part; local times are the time part.

Test / Verification Process

The imported source files are placed in a sources/ subdirectory of the application directory. Install the harness once (network required, one time only):

sh sources/setup_harness.sh

Then run the suite from the application directory. DECODER is required — the harness has no default implementation language:

go build -o toml-decoder ./cmd/toml-decoder
DECODER="$PWD/toml-decoder" sh sources/run_conformance.sh

During development, sh sources/full_test.sh does both steps and is the same command the score is taken from.

Mechanics: toml-test holds the corpus internally. For each valid case it pipes TOML into the decoder on stdin and compares the emitted tagged JSON against the expected description. For each invalid case it requires a non-zero exit. The summary is:

  valid tests: NNN passed,  N failed
invalid tests: NNN passed,  N failed

The passed counts are the correctness score. Exit code is non-zero while any test fails.

Useful flags

Flags pass straight through sources/run_conformance.sh to toml-test test.

• -run 'valid/string/*' — run one feature group. Use this to develop one

construct at a time.

• -run=valid/string-empty,valid/string-nl — run named cases.
• -skip 'invalid/datetime/*' — exclude a group.
• -json — machine-readable report instead of text.
• -v — list passing tests as well as failures.
• -script — emit a shell script of -skip flags for the current failures,

which is the fastest way to snapshot known failures between passes.

Feature groups available to -run:

• valid: array bool comment datetime float inline-table integer key spec-1.0.0 string table
• invalid: the above plus control encoding local-date local-datetime local-time

Suggested Implementation Order

TOML parsing is lexically simple and structurally fussy. The difficulty is in key/table semantics and in rejecting malformed input, not in the grammar.

1. Scaffolding — line handling, comments, whitespace, the stdin/stdout/exit

contract, tagged JSON emission.

1. Scalars — booleans, integers (including 0x, 0o, 0b, underscores),

floats (including inf, nan, exponents), basic and literal strings, then multi-line strings with their line-ending backslash and trimming rules.

1. Keys — bare, quoted, and dotted keys; the redefinition rules.
2. Tables — [table], [a.b.c] implicit creation, [[array of tables]],

and the rules governing which of these may follow which.

1. Inline tables and arrays — including nesting and the TOML 1.0 restriction

that inline tables are closed to later extension.

1. Datetimes — offset, local datetime, local date, local time.
2. Invalid-input hardening — control characters, bad UTF-8, duplicate keys,

redefinition after an inline table, unterminated constructs. This is where most of the remaining score lives.

The specification is normative and short. Follow it directly.

Files the LLM Needs

• sources/toml-v1.0.0.md — the specification. Primary input. Required.
• sources/full_test.sh — the supplied scoring entry point.
• sources/run_conformance.sh — the conformance harness it invokes.
• sources/setup_harness.sh — one-time harness installation.

Definition of Done

• sh sources/full_test.sh runs cleanly with zero errors and exits zero.
• The program satisfies the stdin → tagged-JSON → exit-code contract.
• Every supplied valid and invalid case passes: the failed, errored, and skipped

counts are all zero. The harness exit status is the verdict and the whole verdict — assert returncode == 0 and stop there. Do not assert on the text of the summary line at all: the case totals belong to the installed suite, and a check that reads a runner's printed output is measuring the runner rather than the parser.

• The parser is written from the specification. **Every third-party TOML module is

forbidden** — github.com/BurntSushi/toml, github.com/pelletier/go-toml, github.com/naoina/toml, and any other. BurntSushi/toml scores near-perfectly on this suite, so importing it makes the exercise meaningless.

• go.mod declares no require dependencies. The standard library is sufficient:

encoding/json, strconv, strings, unicode, unicode/utf8, time, math, fmt, io, os, errors.

• No network access at test time after setup_harness.sh has run once.

</source>

<stories> <story id="architecture" implements="ARCHITECTURE.md">Define the Go parser modules, command boundary, tagged JSON contract, and standard-library constraints.</story> <story id="decoder-contract" implements="FEATURE-Decoder-Contract.md">Build the stdin-to-tagged-JSON decoder command.</story> <story id="decoder-invalid-input" implements="FEATURE-Decoder-Invalid-Input.md">Report invalid TOML through the decoder process boundary.</story> <story id="decoder-tagged-json" implements="FEATURE-Tagged-JSON.md">Encode parsed TOML values using the required tagged JSON representation.</story> <story id="lexical-strings" implements="FEATURE-Lexical-Strings.md">Parse TOML basic, multiline basic, literal, and multiline literal strings.</story> <story id="lexical-numbers" implements="FEATURE-Lexical-Numbers.md">Parse TOML integers, floating-point values, special floats, and booleans.</story> <story id="lexical-datetime" implements="FEATURE-Lexical-Datetime.md">Parse offset datetime, local datetime, local date, and local time values.</story> <story id="lexical-whitespace-comments" implements="FEATURE-Lexical-Whitespace-Comments.md">Process TOML whitespace, comments, line endings, continuations, and encoding rules.</story> <story id="keys-forms" implements="FEATURE-Key-Forms.md">Parse bare, quoted, and dotted TOML keys.</story> <story id="structures-arrays" implements="FEATURE-Arrays.md">Parse TOML arrays and nested array values.</story> <story id="keys-semantics" implements="FEATURE-Key-Semantics.md">Enforce TOML key uniqueness and scalar-to-table definition rules.</story> <story id="structures-inline-tables" implements="FEATURE-Inline-Tables.md">Parse TOML inline tables and nested inline-table keys.</story> <story id="structures-inline-table-closure" implements="FEATURE-Inline-Table-Closure.md">Enforce closure of TOML inline tables.</story> <story id="tables-standard" implements="FEATURE-Standard-Tables.md">Parse standard TOML table headers and implicit tables.</story> <story id="tables-redefinition" implements="FEATURE-Table-Redefinition.md">Enforce standard-table redefinition and structure-conflict rules.</story> <story id="tables-arrays" implements="FEATURE-Arrays-of-Tables.md">Parse arrays of TOML tables and nested table elements.</story> <story id="tables-arrays-ordering" implements="FEATURE-Arrays-of-Tables-Ordering.md">Enforce array-of-table ordering and conflict rules.</story> <story id="conformance" implements="FEATURE-Conformance.md">Run the complete pinned TOML 1.0.0 conformance suite.</story> </stories>