# 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.
2. 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`.
3. 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.
4. 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

```text
<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: A jq Interpreter

## Objective

Build an interpreter for the jq language as described in `sources/jq-manual.txt`.
Correctness is measured by the upstream jq conformance corpus, `sources/jq.test`, taken
verbatim from jq 1.8.2. The goal is to pass every case the corpus supplies, with none
failed and none errored. The suite's size is a property of the pinned corpus; never
assert a case count.

The implementation language is Python, fixed by this Target's `TECHNOLOGY_STACK.md` and
governed by `stack/python.md`.

jq is a small language with a large semantic core. Almost every filter is a **generator**:
it takes one input and produces a stream of zero, one, or many outputs, and downstream
filters run once per upstream output. Backtracking through that stream is not an
optimisation, it is the evaluation model, and `reduce`, `foreach`, `limit`, `first`,
`label`/`break`, and the `?//` destructuring alternative are all defined in terms of it. An
implementation that treats a filter as a function returning one value will pass the early
cases and then stall permanently. Decide the evaluation model before writing builtins.

## 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:

```sh
#!/bin/sh
# full_test.sh — scoring entry point. Do not filter, skip, or reinterpret.
set -eu
if [ ! -x ./jq ]; then
    echo "error: no executable ./jq at the application root." >&2
    echo "The deliverable is an executable named jq that reads JSON on stdin." >&2
    exit 1
fi
JQ="$PWD/jq" exec python3 sources/run_conformance.py
```

Before relying on any path above, run `ls sources/` in the application directory and
correct the paths in the harness against what is actually on disk. Correcting a path is
the only edit permitted to this script. Do not add flags, filters, skips, or a redirection
of the exit code.

The interface check is deliberately separate from the conformance run so that a missing
program and a genuine conformance failure are distinguishable in the evidence. `JQ` is the
harness's only knowledge of the implementation language; the harness itself is
language-neutral.

## Read-only scoring assets

These four files are the exam. They are hash-verified against the import and restored
before grading, so a modification is reported as tampering rather than honoured:

- `sources/full_test.sh` — the scoring entry point
- `sources/run_conformance.py` — the scoring instrument
- `sources/exclusions.txt` — the declared skips
- `sources/jq.test` — the conformance corpus

Do not write to them. Build `./jq` so that the supplied entry point succeeds; changing the
entry point is not a repair, and a repair pass spent editing one of these files is wasted.

## Interface contract

The program is a filter: an executable file named `jq` at the application root, invoked as

```
./jq -c '<program>'
```

with JSON on **stdin**. It writes each value the program produces to **stdout** as one
compact JSON value per line, and exits `0`.

`-c` is the only option exercised. The program need not implement any other jq
command-line option, and the manual's "Invoking jq" section is omitted from
`sources/jq-manual.txt` for that reason.

Exit codes follow jq's own, and the distinction is load-bearing because the harness grades
on it:

| Exit | Meaning |
|---|---|
| `0` | the program compiled and ran to completion |
| `3` | the program did not compile — a syntax or static error |
| `5` | the program compiled but raised at run time |

A case may legitimately emit several values and then raise; the harness compares the values
produced before the raise, so exit `5` is not by itself a failure. Exit `3` on a valid
program is always a failure. Diagnostics go to **stderr** and are never compared.

Any implementation shape that satisfies this contract is acceptable. A
`#!/usr/bin/env python3` script named `jq` that imports the real work from a package
alongside it is the obvious one; `main` should parse arguments and delegate.

## Test / verification process

The imported source files are placed in a `sources/` subdirectory of the application
directory. The only tools required are `python3` and a POSIX `sh`, both already present.
No installation step, no package download, and no network access are required at any
point.

```bash
JQ="$PWD/jq" python3 sources/run_conformance.py                     # the scored run
JQ="$PWD/jq" python3 sources/run_conformance.py -v                  # list passing cases too
JQ="$PWD/jq" python3 sources/run_conformance.py --json              # machine-readable
JQ="$PWD/jq" python3 sources/run_conformance.py --list              # print cases, run nothing
JQ="$PWD/jq" python3 sources/run_conformance.py --select 'reduce'   # one construct at a time
JQ="$PWD/jq" python3 sources/run_conformance.py --select 'reduce' --list   # size that slice
```

During development, `sh sources/full_test.sh` does the interface check and the conformance
run together, and is the same command the score is taken from.

`--select` takes a regular expression matched against the case's program text. It is how
an intermediate story runs its own slice of the corpus, and it is required, not optional.

The harness's own `--help` text for `--select` calls it a development aid and states that
the acceptance gate always runs the whole corpus. That text predates this rule and does not
govern. It is part of a read-only scoring asset and cannot be corrected in place, so it is
corrected here: where the harness's help text and this document disagree, this document is
authoritative.

**Exactly one acceptance check runs the whole corpus.** One terminal story — the last one —
runs `sh sources/full_test.sh`, asserts only `result.returncode == 0`, prints the captured
stdout and stderr so a failure can be diagnosed from the evidence, and carries the Sea
Trial. No other acceptance check may run the corpus unscoped, and none may invoke
`full_test.sh` at all. A partial implementation fails most of the corpus by construction,
so an unscoped mid-build run reports the schedule rather than a defect, and it is slow in
exact proportion to how incomplete the code is.

**Every other story runs its own slice, and the slice executes cases.** Each story's
acceptance invokes `sources/run_conformance.py` with a `--select` expression scoped to the
construct that story implements, supplies `JQ`, and asserts `result.returncode == 0`. Those
are exactly the cases the story's code is supposed to pass, so the run is neither slow nor
red by construction, and the corpus goes green in the order the plan builds it.

`--list` prints the matching cases and runs nothing. Use it while planning, to size and
inspect a selector before committing to it. An acceptance check that invokes it executes
nothing, passes before the story's code exists, and steers no repair; such a check is a
defect. The one exception is the story whose only obligation is that the corpus parses, the
exclusion list applies, and the harness starts — it implements none of the behaviour under
test, so listing is the correct thing for it to assert.

A selector matching no case is a defect too: it buys the story no coverage and reports
success. Check the count with `--list` while planning and widen the expression until it
covers the story's construct. Together the slices cover the corpus; a case no slice reaches
is first executed by the terminal gate, where a failure arrives with the whole build
already spent and no story to attribute it to.

No acceptance check may assert that an imported or staged file merely exists — a
file-presence check is not acceptance.

The summary line is:

```
jq conformance: NNN passed, N failed, N errored, N skipped (corpus jq.test @ jq-1.8.2)
```

The harness reserves exit `2` for its own faults — a missing corpus, an unset `JQ`, a
stale exclusion. Exit `2` never means the interpreter is wrong.

## The corpus format

`sources/jq.test` documents its own format in its header. Cases are separated by blank
lines; blank lines and `#` lines are ignored. A case is a program line, an input line, and
then the expected output values, one per line. A case preceded by `%%FAIL` is a program
that must be **rejected at compile time**: the following lines are upstream jq's
diagnostic, which this harness records but never compares. Reproducing jq's exact error
text is reverse-engineering a C implementation, not conforming to a specification, so a
`%%FAIL` case passes on exit `3` alone.

Values are compared structurally, not textually. `1` and `1.0` are the same jq value; so
are two objects whose keys are printed in a different order. Formatting of output is
therefore not under test, but the **number and order** of values is.

## Declared exclusions

`sources/exclusions.txt` names the corpus cases this kit cannot run, with the reason. They
are the module-loader cases: `import` and `include` resolved against a search path of
fixture files that this kit's flat source import cannot carry. They are reported as
`skipped` and are not part of the score.

The module *grammar* cases are **not** excluded and must pass. `module (.+1); 0`,
`module []; 0`, `include "a" (.+1); 0`, `include "a" []; 0`, `include "\ "; 0`,
`include "\(a)"; 0`, and `%::wat` are all `%%FAIL` cases: the front end must parse the
module syntax far enough to reject them, without ever touching the filesystem.

## Source Roles

Record this table in the Analysis so every asset is staged onto disk in the build
directory. `sources/jq-manual.txt`, `sources/jq.test`, `sources/parser.y`, and
`sources/lexer.l` are large and must be readable from disk during implementation rather
than carried in prompt text.

| Source | Role | Plan disposition | Build disposition |
|---|---|---|---|
| `jq-manual.txt` | normative specification | context | stage |
| `jq.test` | conformance test suite | context | stage |
| `parser.y` | normative specification | context | stage |
| `lexer.l` | normative specification | context | stage |
| `builtin.jq` | reference implementation | context | stage |
| `run_conformance.py` | conformance harness | context | stage |
| `full_test.sh` | conformance harness | context | stage |
| `exclusions.txt` | conformance harness | context | stage |
| `INSTRUCTIONS.md` | author intent | context | prompt-only |

What each staged file is for:

- `sources/jq-manual.txt` — the jq language manual at 1.8.2, rendered to plain text. The
  primary specification, and the normative description of every builtin.
- `sources/jq.test` — the conformance corpus. Also the most precise available statement of
  the semantics, especially for generators and backtracking.
- `sources/parser.y` — upstream's yacc grammar. The authority on operator precedence,
  associativity, and the shape of every syntactic form.
- `sources/lexer.l` — upstream's lexer. The authority on tokens, string interpolation, and
  escape handling.
- `sources/builtin.jq` — the subset of jq's builtins that upstream defines in jq itself.
  Read it as a specification of those builtins' semantics.
- `sources/run_conformance.py`, `sources/full_test.sh`, `sources/exclusions.txt` — the
  scoring instruments, read-only as stated above.

## Suggested implementation order

The difficulty is concentrated in one place — the evaluation model — and not spread evenly
across the corpus. Build the core correctly before reaching for coverage.

1. **Lexer and parser.** Follow `sources/lexer.l` and `sources/parser.y` directly. Produce
   an AST. Precedence, `?` suffixes, string interpolation, and the `def` forms are all
   settled there. Reject invalid programs with exit `3`.
2. **The generator core.** Evaluate a filter as something that yields a stream of values:
   `.`, literals, `|`, `,`, field access, iteration, arithmetic, comparison, and
   `empty`. Every later feature is expressed in terms of this. Get `[.[] | f]`,
   cartesian products over multi-output arguments, and short-circuiting right.
3. **Paths and assignment.** `path(f)`, `getpath`, `setpath`, `delpaths`, `del`, and then
   `=`, `|=`, `+=`, and friends. Assignment is defined over path expressions, so this
   cannot precede step 2.
4. **Control flow.** `if`/`then`/`elif`/`else`/`end`, `try`/`catch` and `?`, `//`,
   `reduce`, `foreach`, `label`/`break`, `limit`, `first`, `last`, `until`, `while`,
   `recurse`. This is where backtracking is tested hardest.
5. **Functions, variables, and destructuring.** `def` with arity and closures, `as`
   bindings, object and array patterns, and the `?//` alternative operator.
6. **Builtins.** Work outward from `sources/builtin.jq` and the manual: strings, arrays,
   objects, `sort_by`/`group_by`/`unique_by`, `@base64`/`@uri`/`@csv`/`@tsv`/`@sh`
   formats, the date functions, `tostream`, `input`/`inputs`, `$__loc__`, `debug`.
7. **Numbers and edge cases.** `nan`, `infinite`, integer/float equality, large literals,
   and the `have_decnum` builtin — return `false` from it and the corpus takes its
   non-decNumber branch, which native floats satisfy.

The manual is normative and the corpus is precise. Follow both directly rather than
inferring behaviour from jq's printed output.

## Definition of Done

- `sh sources/full_test.sh` runs cleanly with zero errors and exits zero.
- The program satisfies the `./jq -c` → stdin → one-JSON-value-per-line → exit-code
  contract.
- Every corpus case that runs passes: the failed and errored counts are both zero, and the
  skipped count matches the declared exclusions. 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 pinned corpus, and a check that
  reads a runner's printed output is measuring the runner rather than the interpreter.
- Do not create acceptance checks asserting that imported or staged files merely exist.
- The interpreter is written from the specification. **Every third-party jq
  implementation or binding is forbidden** — `jq.py`, `pyjq`, `jqlang`, `gojq`, `jaq`, and
  any other — as is shelling out to a system `jq` binary. A wrapper around real jq scores
  perfectly and makes the exercise meaningless.
- The project declares no third-party runtime dependency. The standard library is
  sufficient: `json`, `decimal`, `math`, `re`, `datetime`, `time`, `base64`, `unicodedata`,
  `itertools`, `functools`, `dataclasses`, `argparse`, `sys`.
- No network access at any point, including at test time. No package is installed, and no
  tool beyond `python3` and POSIX `sh` is invoked.
- Deliver a concise project `README.md` documenting the stdin/stdout interface, the exit
  codes, and the `sh sources/full_test.sh` command.
</source>

<stories>
  <story id="architecture-foundation" implements="ARCHITECTURE.md">Establish the standalone Python interpreter architecture and executable boundary.</story>
  <story id="EXEC-001" implements="FEATURE-Executable-Entry-Point.md">Implement the executable jq entry point.</story>
  <story id="EXEC-002" implements="FEATURE-Process-Contract.md">Implement jq process exit and diagnostic behavior.</story>
  <story id="EXEC-003" implements="FEATURE-JSON-I-O.md">Implement JSON input and compact output handling.</story>
  <story id="PARSE-001" implements="FEATURE-Lexer.md">Implement jq lexical scanning.</story>
  <story id="PARSE-002" implements="FEATURE-Literals-and-Strings.md">Implement literals, strings, escapes, and interpolation.</story>
  <story id="PARSE-003" implements="FEATURE-Filter-Grammar.md">Implement the core jq filter expression grammar.</story>
  <story id="PARSE-004" implements="FEATURE-Advanced-Grammar.md">Implement declarations, control syntax, and grammar rejection.</story>
  <story id="CORE-001" implements="FEATURE-Generator-Core.md">Implement stream-valued filter evaluation.</story>
  <story id="CORE-002" implements="FEATURE-Composition.md">Implement composition and cartesian evaluation.</story>
  <story id="CORE-003" implements="FEATURE-Errors-and-Optional.md">Implement empty, runtime errors, optional evaluation, and partial output.</story>
  <story id="CORE-004" implements="FEATURE-Truthiness-and-Comparison.md">Implement truthiness, equality, and ordering semantics.</story>
  <story id="VALUE-001" implements="FEATURE-Value-Model.md">Implement the jq value model and numeric edge cases.</story>
  <story id="VALUE-002" implements="FEATURE-Accessors.md">Implement field and index access.</story>
  <story id="VALUE-003" implements="FEATURE-Slices-and-Iteration.md">Implement slices and collection iteration.</story>
  <story id="VALUE-004" implements="FEATURE-Type-and-Numeric-Primitives.md">Implement type, length, numeric predicates, and math primitives.</story>
  <story id="CONF-001" implements="FEATURE-Conformance-Assets.md">Stage and validate immutable conformance assets.</story>
  <story id="FLOW-001" implements="FEATURE-Arithmetic-and-Structural-Operators.md">Implement arithmetic and structural operators.</story>
  <story id="FLOW-002" implements="FEATURE-Boolean-and-Alternative-Operators.md">Implement boolean and alternative operators.</story>
  <story id="FLOW-003" implements="FEATURE-Conditionals-and-Exception-Flow.md">Implement conditionals and exception flow.</story>
  <story id="FLOW-004" implements="FEATURE-Labels-and-Breaks.md">Implement lexical labels and breaks.</story>
  <story id="FLOW-005" implements="FEATURE-Reductions-and-Iteration-Control.md">Implement reductions and iteration-control builtins.</story>
  <story id="FLOW-006" implements="FEATURE-Recursive-Generators.md">Implement recursive generators.</story>
  <story id="FUNC-001" implements="FEATURE-Variable-Bindings.md">Implement lexical variable bindings.</story>
  <story id="FUNC-002" implements="FEATURE-Function-Parameters.md">Implement filter and value function parameters.</story>
  <story id="FUNC-003" implements="FEATURE-Function-Definitions.md">Implement function definitions, scope, redefinition, and recursion.</story>
  <story id="FUNC-004" implements="FEATURE-Destructuring-Alternatives.md">Implement destructuring alternatives.</story>
  <story id="PATH-001" implements="FEATURE-Path-Discovery.md">Implement path discovery and projection.</story>
  <story id="PATH-002" implements="FEATURE-Path-Primitives.md">Implement path access and mutation primitives.</story>
  <story id="PATH-003" implements="FEATURE-Assignment-Operators.md">Implement deletion and assignment operators.</story>
  <story id="PATH-004" implements="FEATURE-Complex-Assignments.md">Implement complex assignment edge cases.</story>
  <story id="DATA-001" implements="FEATURE-Collection-Transformations.md">Implement collection transformation builtins.</story>
  <story id="DATA-002" implements="FEATURE-Sorting-and-Grouping.md">Implement sorting, grouping, and extrema builtins.</story>
  <story id="DATA-003" implements="FEATURE-Object-Entries-and-Containment.md">Implement object-entry and containment builtins.</story>
  <story id="DATA-004" implements="FEATURE-Index-and-Membership.md">Implement index, membership, search, and SQL-style utilities.</story>
  <story id="TEXT-001" implements="FEATURE-String-Manipulation.md">Implement string manipulation builtins.</story>
  <story id="TEXT-002" implements="FEATURE-Formats-and-Serialization.md">Implement JSON conversion and output formats.</story>
  <story id="TEXT-003" implements="FEATURE-Regular-Expressions.md">Implement regular-expression filters.</story>
  <story id="TEXT-004" implements="FEATURE-Date-and-Time.md">Implement date and time filters.</story>
  <story id="IO-001" implements="FEATURE-Input-Controls.md">Implement input stream controls.</story>
  <story id="IO-002" implements="FEATURE-Diagnostics.md">Implement diagnostics and stderr filters.</story>
  <story id="IO-003" implements="FEATURE-Streaming.md">Implement streaming transformations.</story>
  <story id="CONF-002" implements="FEATURE-Scoped-Conformance.md">Provide scoped conformance verification for implementation slices.</story>
  <story id="CONF-003" implements="FEATURE-Full-Conformance.md">Verify the completed interpreter against the full conformance corpus.</story>
</stories>