Run artifact

evidence/prompts/20260823.115639.033Z_jq_build_codex.prompt.md

← ReportRaw file

System Instructions

This prompt is divided into three sections:

  1. System Instructions (this section) — structural orientation only. Do not treat this

section as task input.

  1. Input Context — begins with the heading # Input Context. All blocks are wrapped in

<pblock> tags. Two block types:

guidance attribute carries context-specific instructions; content is in a fenced block.

rules, instructions, or group headers.

  1. Agent Task — begins with the heading # Agent Task. Defines your persona, constraints,

and required outputs. Read all input context before acting on this section.

Input Context

<pblock label="Build block job" kind="job">

Build block job

</pblock>

<pblock label="Stories in this block" kind="section">

Stories in this block

</pblock>

<pblock label="Files on disk" kind="section">

Files on disk in the build directory

These are the only imported files present on disk. Every other file named in this prompt is supplied as prompt context and is not on disk; read it here and do not report it as a missing input.

</pblock>

COMPASS - Target Orientation

<pblock filename="COMPASS.md" role="compass" path="/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/COMPASS.md" guidance="Important: This is the core project intent, constraints, and guardrails. It should have presecedence in conflicts.">

# COMPASS: jq

## Compass

Build a standalone interpreter for the jq language as described in `sources/jq-manual.txt`. The
product is an executable file named `jq` at the application root. It reads JSON from standard
input, evaluates a jq filter as an ordered generator, and writes each value the filter produces to
standard output as one compact JSON value per line.

Correctness is measured by the upstream jq conformance corpus `sources/jq.test`, taken verbatim
from jq 1.8.2, minus the cases named in `sources/exclusions.txt`. The goal is every case passing,
none failed and none errored.

## Constraints

- Implement in Python using only the standard library.
- Provide an executable named `jq` at the application root, invoked as `./jq -c '<program>'`.
- `-c` is the only option exercised. No other command-line option is required.
- Run without network access, package installation, or external runtime dependencies.
- Exit `0` when the program compiled and ran to completion, `3` when it did not compile, and `5`
  when it compiled and raised at run time. The harness grades on this distinction.
- Diagnostics go to standard error and are never compared.

## Guardrails

- Do not shell out to a system `jq` executable.
- Do not use a third-party jq implementation or binding.
- Do not modify, rewrite, trim, regenerate, or substitute any file under `sources/`. Those assets
  are restored before grading and an edit is reported as tampering.
- Preserve generator ordering, multiplicity, backtracking, and partial-output runtime behavior.
- Keep compile failures distinct from runtime failures using exit codes 3 and 5.

## Verification Protocol

This section is normative. It governs which story may invoke the supplied harness, and how.

### Invoking the harness

`sources/run_conformance.py` **requires** the environment variable `JQ`, the command that runs the
candidate implementation. Without it the harness exits `2` on its own usage code, which is a
harness fault and never a verdict about the interpreter. Every invocation, in every acceptance
criterion and every developer command, supplies it:

```bash
JQ="$PWD/jq" python3 sources/run_conformance.py            # whole corpus, the scored run
JQ="$PWD/jq" python3 sources/run_conformance.py --select 'reduce'   # run one construct for real
```

Those two commands are the only ways this build runs the harness. They are specified verbatim
below under *The two harness invocations*, together with the flag this build forbids.

`sources/` is read only. No story edits, patches, or regenerates `sources/run_conformance.py`,
`sources/jq.test`, or `sources/exclusions.txt`; a harness defect is reported, not repaired in
place. A story that needs to experiment with the harness works on a copy outside `sources/`, and
every acceptance criterion invokes the original `sources/run_conformance.py`.

An acceptance criterion written in Python supplies it by **extending** the inherited environment,
never by replacing it:

```python
env={**os.environ, "JQ": str(build_dir / "jq")}
```

`env={"JQ": ...}` alone leaves the child with no `PATH`, so nothing it invokes resolves and the
criterion is false at every level of implementation quality.

`sources/full_test.sh` sets `JQ` itself for the runner it wraps and therefore takes no environment
from its caller.

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

The summary line is:

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

### The two harness invocations

An acceptance criterion that runs `sources/run_conformance.py` uses one of these two commands. No
criterion in this build passes any other flag to the harness.

| Story kind | Command | Executes cases? | Asserts |
|---|---|---|---|
| Every behavioral story | `--select <regex> --json` | Yes, the selected slice | exit `0`, zero `fail`, zero `error`, non-zero case count |
| Terminal story (once, last) | `sh sources/full_test.sh` | Yes, all of them | exit `0` |

The staging story does not appear in this table. It does not run the harness at all; see *The
staging story* below.

#### `--list` is never run

`sources/run_conformance.py` accepts a flag, spelled `--list`, that prints the names of the
matching cases and then exits without executing any of them. `sources/INSTRUCTIONS.md`, the file
header, and `--help` all document it.

**This build never runs it. Not in an acceptance criterion, not in a story, not in a script, not
in a command typed by a build agent, not while developing and not while verifying. The string
`--list` does not appear anywhere in this project's output. If you have written it, that line is
wrong — delete it and use one of the two commands above.**

A Drydock build is headless. There is no one watching the output, so a mode whose entire purpose
is to print something for a person to read has no reader and no reason to run.

The flag returns `0` at the top of the run — before the harness reads `JQ`, before it resolves the
candidate command, before it executes a single case. A criterion built on it passes when `jq` is
an empty file, when `jq` does not exist, and when the story it gates was never written. It is not
a weak proof, not a partial proof, and not an acceptable proof for staging, for scaffolding, or
for an early story whose implementation is incomplete. It is not a proof. Thirty-six criteria in
one earlier plan of this project used it, every one of them reported green, and it cost three days.

If you are writing a criterion and reaching for that flag, the reason is always the same: the
story's code does not exist yet and you want a command that will not fail. That is the definition
of a criterion that proves nothing. Write the `--select ... --json` form instead and let it be red
until the story makes it green. **A criterion is supposed to fail before its story is built.**

The same prohibition covers any other flag whose effect is to not execute the cases — enumeration,
dry-run, validation, or help. If a flag's documented purpose is "run nothing", it has no place in
an acceptance criterion.

#### Behavioral criterion — copy this, changing only `SELECT`

```python
import json
import os
import subprocess
import sys

SELECT = r"reduce"

result = subprocess.run(
    [sys.executable, "sources/run_conformance.py", "--select", SELECT, "--json"],
    capture_output=True,
    text=True,
    env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
tally = report["summary"]
assert sum(tally.values()) > 0, f"selector matched no case: {SELECT}"
assert tally["fail"] == 0 and tally["error"] == 0, tally
assert result.returncode == 0, result.returncode
```

Three assertions, and all three are required.

1. **The selector matched something.** `--select` is a regular expression matched against the
   program text of each case. A selector that matches nothing yields zero cases, zero failures,
   and exit `0` — green, and worth nothing. Alternations naming ideas rather than syntax
   (`closure`, `recursive`, `optional`) match no jq program and are the common way to write one
   by accident. Select on syntax the corpus actually contains: `reduce`, `foreach`, `def `,
   ` as \$`, `try `, `//`, `path(`.
2. **No case failed or errored.** Read off the parsed JSON tally, not off any printed line.
3. **The exit status is `0`.** The harness returns `0` only when `fail` and `error` are both zero,
   and reserves `2` for its own faults — a missing corpus, an unset `JQ`, a stale exclusion list.
   Exit `2` is never a verdict about the interpreter.

`--json` writes the report and nothing else to stdout, so `json.loads(result.stdout)` is total. Do
not assert against the human summary line, and do not grep stdout for `passed` or `failed`.

### The terminal story

The **terminal story** is the last story in the build order: the one on which every other story is
a transitive dependency, and after which no further story runs. It is a verification story. Its
job is not to add capability but to prove that the capability every preceding story delivered is
present, together, at the end of the build.

The terminal story of this project runs `sh sources/full_test.sh`, asserts `returncode == 0`,
prints the captured stdout and stderr so a failure is diagnosable from the evidence alone, and
carries the Sea Trial. It is the only story permitted to run the whole corpus.

A story is not terminal because its name contains "verify", because it is a test harness, or
because it stages the test assets. Staging the corpus is foundational work that happens early;
running the corpus is terminal work that happens last. Do not place a whole-corpus gate on a
story that cannot yet run it — it fails vacuously and teaches nothing.

### Scope of every other story

Every non-terminal story is gated on its own declared behavior only, through `--select` against
the constructs that story implements, and the criterion asserts the selected slice passes. A
non-terminal story never invokes `sources/full_test.sh` and never runs the corpus unfiltered: a
partial interpreter fails most of an authoritative corpus by construction, and its unimplemented
cases exhaust the harness's per-case timeout rather than returning, so the unscoped run costs the
most exactly where it teaches the least.

Regression across stories is not the responsibility of any story's criteria. Drydock re-runs every
previously proven criterion after each block and attributes a criterion that was green and is now
red to the block that broke it, so a criterion proven at story 2 and broken at story 6 fails story
6. Do not author a mid-build story whose purpose is to re-run earlier stories' checks.

### The staging story

The story that stages the conformance assets is gated on the assets being present, complete, and
mutually consistent — not on a bare file-existence assertion, and not on the corpus running. It
proves that in process, by importing the harness and calling its parsers directly. It never
launches the harness, so the question of which flags to pass does not arise:

```python
import sys

sys.path.insert(0, "sources")
import run_conformance as harness

EXPECTED_CASES = 550
EXPECTED_EXCLUSIONS = 13

cases = harness.parse_corpus(harness.CORPUS.read_text(encoding="utf-8"))
excluded = harness.apply_exclusions(cases, harness.parse_exclusions(harness.EXCLUSIONS))
assert len(cases) == EXPECTED_CASES, len(cases)
assert len(excluded) == EXPECTED_EXCLUSIONS, len(excluded)
```

This reads state rather than output: the harness module imports, the corpus parses into the
expected number of cases, and every exclusion still matches a case — `apply_exclusions` raises on
a stale entry, so a corpus and an exclusion list that have drifted apart fail here rather than
silently skipping cases later.

It claims nothing about the interpreter, because at this point in the build there is nothing to
claim. Every story that claims a construct works runs that construct through
`--select ... --json`.

## The corpus

`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 the harness
records but never compares. Reproducing jq's exact error text is reverse-engineering a C
implementation rather than 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, and so are
two objects whose keys print in a different order. Output formatting is therefore not under test,
but the number and order of values is.

`sources/exclusions.txt` names the corpus cases this kit cannot run, with the reason. They are the
module-loader cases, whose `import` and `include` resolve against a search path of fixture files a
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 parses the module syntax far enough to reject them, without
ever touching the filesystem.

<!-- drydock:build-write-guardrail:start -->
## Build Write Guardrail

- Authorized build directory: `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/build/jq`
- Authorized Target directory: `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq`
- Build agents have permission to create, modify, and remove files required by the active build block inside these authorized directories.
- No path outside these authorized directories may be modified.
- Protected Drydock artifacts:
  - `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/blueprint/`
  - `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/MANIFEST.md`
  - `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/COMPASS.md`
  - `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/QuarterDeck/`
  - `/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/evidence/`
<!-- drydock:build-write-guardrail:end -->

</pblock>

STACK - Technology HOW

<pblock filename="python_compact.md" role="stack" path="/mnt/c/Users/barlo/projects/drydock/Rigging/stack/python_compact.md">

<!-- Compacted from rigging/stack/python.md on 2026-07-16 (manual update to match python.md V3) -->

# Python — Compact

## Configuration Management

One typed frozen-dataclass `Config` is the only env reader — never read `os.environ` elsewhere. No `Dev`/`Prod`/`Test` subclasses; the environment (`.env`) selects configuration. Never hardcode secrets, ports, or paths. Secret hygiene and `.env.example`: see `stack/env_variables_and_secrets.md`.

```python
# config.py
import os
from dataclasses import dataclass
from dotenv import load_dotenv
load_dotenv()

@dataclass(frozen=True)
class Config:
    secret_key: str
    database_path: str
    port: int
    debug: bool = False

    @classmethod
    def load(cls) -> "Config":
        try:
            return cls(
                secret_key=os.environ["SECRET_KEY"],
                database_path=os.environ.get("DATABASE_PATH", "data/app.db"),
                port=int(os.environ.get("APP_PORT", "5001")),
                debug=os.environ.get("APP_DEBUG") == "1",
            )
        except KeyError as e:
            raise RuntimeError(f"Missing required env var: {e}") from e
```

## Code Style and Understandability

Code must be understandable through naming, structure, small focused units, explicit types, clear interfaces, appropriate abstractions, and tests. Names state intent; one responsibility per module; functions do one thing at one level of abstraction; no speculative abstraction layers. Comments state constraints the code cannot express — never restate mechanics.

## Type Hints and Static Typing

Modern hints on all public interfaces; typed structures across boundaries; run a type checker when practical.

- Built-in generics (`list[str]`, `dict[str, int]`) and `X | None` — never `typing.List`, `Optional`, `Union`
- Type every public function, method, and class attribute
- Schemas/serializers/services/data structures are typed classes: frozen dataclasses internally, Pydantic/`TypedDict` at serialization boundaries
- No bare `dict`, positional tuples, or `Any` crossing a module boundary
- `uv add --dev mypy` then `uv run mypy .` (or pyright) alongside ruff and pytest in CI

## Logging

Use `logging` with named loggers, never `print()`. Configure formatter + console and file handlers at startup (`data/logs/app.log`); level from `APP_DEBUG`.

```python
import logging
logger = logging.getLogger(__name__)
logger.info('Server starting on port %s', port)
```

## Environment Separation

Distinct `.env` per environment; same typed `Config` reads whichever is present. Never run debug in production.

| Setting | Dev | Test | Prod |
|---------|-----|------|------|
| APP_DEBUG | 1 | 0 | 0 |
| DATABASE_PATH | data/app.db | :memory: | data/app.db |
| SECRET_KEY | .env value | .env value | .env value (required) |
| LOGGING | DEBUG | WARNING | INFO |

## Testing

`pytest` with fixtures; fresh in-memory DB per test; test at the boundary. Every Python build must include a complete pytest suite regardless of the specification — no tests, no ACTIVE conformity.

```python
# tests/conftest.py
import pytest

@pytest.fixture
def app(monkeypatch):
    monkeypatch.setenv("SECRET_KEY", "test")
    monkeypatch.setenv("DATABASE_PATH", ":memory:")
    from app import create_app
    from config import Config
    yield create_app(Config.load())

@pytest.fixture
def client(app):
    return app.test_client()
```

**test_smoke.py** — app factory works; `GET /health` returns 200 `{"status": "ok"}`; `GET /` returns 200.

**test_routes.py** — one test per route: `GET` pages assert 200; `POST` APIs assert status in `{200, 201, 204}`; HTMX routes send `HX-Request: true`; `{id}` routes use fixture-created records.

**test_db.py** (only if DATABASE.md exists) — expected tables exist; round-trip per major table; invalid FK raises `IntegrityError` (`PRAGMA foreign_keys=ON`).

Do not test third-party internals, config loading, or private helpers.

```ini
# pytest.ini
[pytest]
testpaths = tests
addopts = -v
```

## Security

Validate all user input; parameterized queries exclusively; never trust client data.

- `?` placeholders, never f-strings, for all DB operations
- `secure_filename()` for user-supplied paths
- Length and type validation on inputs
- Secret key from environment, never hardcoded
- Never expose stack traces to end users

## Dependency Management (uv)

`uv` only; `pyproject.toml` is the manifest; `uv.lock` committed; `.venv/` gitignored. Full toolchain conventions: `stack/uv_ruff.md`.

```bash
uv venv                          # creates .venv/
uv add flask python-dotenv       # runtime deps → pyproject.toml + uv.lock
uv add --dev pytest ruff mypy    # dev deps
uv sync --frozen                 # CI — fail if lock is stale
```

- Never bare `pip install` or `python -m venv`
- Dev deps in `[project.optional-dependencies].dev`; runtime deps minimal

## Startup Validation

`Config.load()` already validates required env vars; startup validation confirms DB connectivity. Crash early on misconfiguration.

```python
def validate_startup(config: Config, db: Database):
    try:
        db.healthcheck()          # SELECT 1 inside the Database class
    except Exception as e:
        raise RuntimeError(f'Database not accessible: {e}')
    logger.info('Startup validation passed')
```

## Directory Layout

```
project-name/
├── app.py              # Entry point / app factory
├── routes.py           # Route handlers
├── models.py           # Data models and type registries
├── db.py               # Database class: typed tables, connection, schema, migrations
├── ops.py              # Business logic and operations
├── config.py           # typed Config class — the only env reader
├── templates/          # base.html + types/ partials
├── static/             # css/, js/
├── tests/              # conftest.py, test_*.py
├── bin/                # (from common.md)
├── data/               # (from common.md)
├── pyproject.toml
├── uv.lock
├── .env                # gitignored; .env.example committed
└── .gitignore
```

</pblock>

<pblock filename="common_compact.md" role="stack" path="/mnt/c/Users/barlo/projects/drydock/Rigging/stack/common_compact.md">

<!-- Compacted from RulesEngine/stack/common.md on 2026-04-29 by prompts/compact_file.md — regenerate via bin/rulesengine_compact.sh -->

# Common Best Practices — Compact

## Project Directory Layout

```
project-name/
├── bin/                # Operation scripts
├── data/               # Runtime data (DB, logs, backups) — gitignored
│   ├── logs/
│   └── backups/
├── docs/
├── tests/
├── .env                # gitignored
├── .env.example        # committed
├── .gitignore
├── CLAUDE.md
└── Links.md
```

Additional directories depend on the stack (e.g., `templates/`, `static/`, `migrations/`).

## Shell Scripts (bin/)

All user-facing operations live in `bin/` as bash scripts with standardized headers, logging, and error handling.

```bash
#!/bin/bash
# CommandCenter Operation
# Name: Human Readable Name
# Type: daemon|batch
# Port: 8000

# --- Standard Preamble ---
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
LOG_DIR="$PROJECT_DIR/data/logs"
mkdir -p "$LOG_DIR"

TIMESTAMP=$(date '+%Y-%m-%d_%H%M%S')
SCRIPT_NAME=$(basename "$0" .sh)
LOG_FILE="$LOG_DIR/${SCRIPT_NAME}_${TIMESTAMP}.log"

echo "=== $SCRIPT_NAME started at $(date '+%Y-%m-%d %H:%M:%S') ===" | tee "$LOG_FILE"
echo "Arguments: $*" | tee -a "$LOG_FILE"
echo "Working dir: $PROJECT_DIR" | tee -a "$LOG_FILE"
echo "---" | tee -a "$LOG_FILE"

cd "$PROJECT_DIR"

# --- Your Commands Here ---
# All output goes to both console and log file via tee
your_command 2>&1 | tee -a "$LOG_FILE"

echo "=== $SCRIPT_NAME finished at $(date '+%Y-%m-%d %H:%M:%S') ===" | tee -a "$LOG_FILE"
```

## Header Fields

| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| `# CommandCenter Operation` | Yes | literal | Marks script as discoverable |
| `# Name:` | Yes | free text | Display name in UI |
| `# Type:` | No | `daemon` or `batch` | Default: `batch`. Daemons stay running. |
| `# Port:` | No | integer | Port number for daemon services |

Scripts without `# CommandCenter Operation` won't appear in Command Center's UI.

## Standard Scripts

| Script | Type | Purpose |
|--------|------|---------|
| `bin/start.sh` | daemon | Start the dev server |
| `bin/stop.sh` | batch | Stop the dev server |
| `bin/test.sh` | batch | Run test suite |
| `bin/build.sh` | batch | Build/compile the project |
| `bin/deploy.sh` | batch | Deploy to production |
| `bin/backup.sh` | batch | Backup data/database |

Logging: all stdout/stderr captured via `tee` to `data/logs/`. Log filename: `scriptname_YYYY-MM-DD_HHMMSS.log`. First lines always record timestamp, arguments, working directory.

## External Links (Links.md)

Every project maintains `Links.md` at its root:

```markdown
| Label | URL |
|-------|-----|
| Local Dev | http://localhost:5001 |
| Production | https://example.com |
| Docs | https://docs.example.com |
| GitHub | https://github.com/user/repo |
```

One table, two columns (Label, URL). Command Center's scanner reads this on startup and stores links in the project's `extra` JSON.

## CLAUDE.md Convention

Every project has `CLAUDE.md` at its root with these sections in order:

1. `## Project Overview` — what the project does, key features
2. `## Architecture` — tech stack, key files, patterns
3. `## Dev Commands` — bash commands in a code block
4. `## Service Endpoints` — URLs: `- Label: https://url`
5. `## Bookmarks` — grouped links: `### Group` then `- [Title](URL)`

Section rename rules — always use the standard name:
- `## Commands` / `## Development Commands` / `## Build Commands` → `## Dev Commands`
- `## Overview` / `## Project Purpose` → `## Project Overview`
- `## Stack` → `## Architecture`

## Git Hygiene

Never commit secrets, generated files, or runtime data.

```gitignore
# Runtime
data/
*.db
*.log

# Environment
.env
venv/
node_modules/

# Python
__pycache__/
*.pyc
*.egg-info/
dist/
build/

# OS
.DS_Store
Thumbs.db
```

- `data/` — runtime databases, logs, backups, uploads
- `.env` — secrets and local config; commit `.env.example` with placeholder values
- Write imperative commit messages: "Add health endpoint" not "Added health endpoint"

## Development Workflow

1. **Always commit immediately** after completing a task with no errors.
2. Commit messages: descriptive text, no AI/tool mentions.
3. **DO NOT push** — local commits only.
4. **NO co-authored-by lines**.
5. End code change responses with a restart notice:
   - Templates/CSS/static only: "No restart needed — browser refresh is enough."
   - Python/JS server files: "Restart required — run the start script or equivalent."

</pblock>

CONTEXT - Read-Only Support

<pblock filename="run_conformance.py" role="context" path="/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/blueprint/run_conformance.py">

#!/usr/bin/env python3
"""Run the upstream jq conformance corpus against a candidate implementation.

This is the scoring instrument. It is supplied, not authored: it is staged verbatim into the
build directory, hash-verified against the import, and restored before grading. Its exit status
is the acceptance verdict.

It is deliberately external to the implementation. Upstream jq grades itself, through its own
``--run-tests`` flag; a self-graded suite proves nothing here, so this runner re-implements the
corpus protocol and drives the candidate as a subprocess, one process per case.

Imported sources land in ``sources/`` inside the application directory, so this is normally
invoked as ``python3 sources/run_conformance.py`` from that directory.

Usage:
    JQ=./jq python3 sources/run_conformance.py                     # full corpus, the scored run
    JQ=./jq python3 sources/run_conformance.py -v                  # list passing cases too
    JQ=./jq python3 sources/run_conformance.py --json              # machine-readable report
    JQ=./jq python3 sources/run_conformance.py --list              # print cases, run nothing
    JQ=./jq python3 sources/run_conformance.py --select 'reduce'   # develop one construct

Environment:
    JQ         command that runs the candidate. Required -- this harness is language-neutral
               and deliberately has no default implementation language.

Exit codes:
    0   every case that ran passed
    1   at least one case failed or errored
    2   the harness could not run: bad usage, missing corpus, or a stale exclusion
"""

from __future__ import annotations

import argparse
import json
import os
import re
import shlex
import subprocess
import sys
from dataclasses import dataclass, field
from pathlib import Path

HERE = Path(__file__).resolve().parent
CORPUS = HERE / "jq.test"
EXCLUSIONS = HERE / "exclusions.txt"

#: A case that has not produced output in this long is not going to. jq's own suite runs the
#: whole corpus in under a second; anything near this bound is a runaway generator.
DEFAULT_TIMEOUT = 10.0

PASS, FAIL, ERROR, SKIP = "pass", "fail", "error", "skip"

#: jq's documented exit codes, which this kit's interface contract adopts. The distinction is
#: load-bearing: the corpus's %%FAIL cases are programs that must not compile, while an ordinary
#: case may legitimately raise at run time part-way through its output and still be correct.
EXIT_COMPILE_ERROR = 3
EXIT_RUNTIME_ERROR = 5


def split_lines(text: str) -> list[str]:
    """Split on newlines only.

    ``str.splitlines`` is Unicode-aware and also breaks on U+000B, U+000C, U+0085, U+2028, and
    U+2029. The corpus contains cases whose expected output embeds those code points inside JSON
    strings -- ``trim, ltrim, rtrim`` over the Unicode whitespace set is one -- and splitting
    there shreds one JSON value into several, failing a correct implementation.
    """
    lines = text.split("\n")
    if lines and lines[-1] == "":
        lines.pop()
    return lines


@dataclass
class Case:
    """One corpus case: a program, an input, and what it must produce.

    ``expect_failure`` cases are the corpus's ``%%FAIL`` blocks. Upstream compares their
    diagnostic text; this runner requires only that the candidate reject the program. The
    expected strings are jq's exact C-implementation diagnostics, down to the caret art
    underlining the offending token -- reproducing them is reverse-engineering an
    implementation, not conforming to a specification. The text is parsed and reported so a
    reader can see what upstream said, and is never compared.
    """

    line: int
    program: str
    stdin: str = ""
    expected: list[str] = field(default_factory=list)
    expect_failure: bool = False
    diagnostic: str = ""


@dataclass
class Result:
    case: Case
    status: str
    detail: str = ""
    actual: list[str] = field(default_factory=list)
    return_code: int | None = None
    stderr: str = ""


class HarnessError(Exception):
    """A fault in the kit or its invocation, never a fault in the candidate."""


# --------------------------------------------------------------------------------------------
# Corpus parsing
# --------------------------------------------------------------------------------------------


def parse_corpus(text: str) -> list[Case]:
    """Parse the jq test corpus.

    The format is documented in the corpus's own header: cases are groups of lines separated by
    blank lines; blank lines and lines starting with ``#`` are ignored. A case is a program
    line, an input line, and then zero or more expected output lines. A case preceded by a
    ``%%FAIL`` or ``%%FAIL IGNORE MSG`` marker is a program line followed by the diagnostic
    upstream jq emits, which may itself span several lines of source excerpt and caret art.
    """
    cases: list[Case] = []
    block: list[tuple[int, str]] = []
    expect_failure = False
    lines = split_lines(text)

    def flush() -> None:
        nonlocal block, expect_failure
        if block:
            cases.append(_case_from_block(block, expect_failure))
        block = []
        expect_failure = False

    for number, raw in enumerate(lines, start=1):
        stripped = raw.strip()
        if not stripped:
            flush()
            continue
        if raw.startswith("%%FAIL"):
            flush()
            expect_failure = True
            continue
        # A '#' comment closes nothing: upstream places section banners between cases, always
        # with blank lines around them, and never inside a case.
        if raw.lstrip().startswith("#") and not block:
            continue
        if raw.lstrip().startswith("#"):
            continue
        block.append((number, raw))
    flush()
    return cases


def _case_from_block(block: list[tuple[int, str]], expect_failure: bool) -> Case:
    line, program = block[0]
    if expect_failure:
        diagnostic = "\n".join(text for _, text in block[1:])
        return Case(line=line, program=program, expect_failure=True, diagnostic=diagnostic)
    if len(block) < 2:
        raise HarnessError(
            f"{CORPUS.name}:{line}: case has a program but no input line; the corpus is malformed"
        )
    return Case(
        line=line,
        program=program,
        stdin=block[1][1],
        expected=[text for _, text in block[2:]],
    )


# --------------------------------------------------------------------------------------------
# Exclusions
# --------------------------------------------------------------------------------------------


def parse_exclusions(path: Path) -> list[str]:
    """Read the declared exclusions: one verbatim program line per entry, ``#`` for reasons."""
    if not path.is_file():
        return []
    return [
        line
        for line in split_lines(path.read_text(encoding="utf-8"))
        if line.strip() and not line.lstrip().startswith("#")
    ]


def apply_exclusions(cases: list[Case], exclusions: list[str]) -> set[int]:
    """Return the corpus line numbers of excluded cases.

    An exclusion that matches nothing is a hard error rather than a shrug. The corpus is pinned
    by hash, so a stale exclusion means the pin moved without the exclusion list being revisited
    -- and a silent no-op there would quietly re-admit a case the kit cannot run.
    """
    by_program: dict[str, list[Case]] = {}
    for case in cases:
        by_program.setdefault(case.program, []).append(case)

    excluded: set[int] = set()
    stale: list[str] = []
    for program in exclusions:
        matched = by_program.get(program)
        if not matched:
            stale.append(program)
            continue
        excluded.update(case.line for case in matched)
    if stale:
        listed = "\n".join(f"    {program}" for program in stale)
        raise HarnessError(
            f"{EXCLUSIONS.name}: these exclusions match no case in {CORPUS.name}:\n{listed}\n"
            "The corpus and the exclusion list have drifted apart."
        )
    return excluded


# --------------------------------------------------------------------------------------------
# Comparison
# --------------------------------------------------------------------------------------------


def jv_equal(left: object, right: object) -> bool:
    """Compare two decoded JSON values the way jq's own ``jv_equal`` does.

    Structural, not textual: ``1`` and ``1.0`` are the same jq value and the corpus relies on
    that. Python's ``==`` almost does this, but it also equates ``True`` with ``1`` and
    ``False`` with ``0``, which jq does not; booleans are therefore matched by identity of type
    before anything else.
    """
    if isinstance(left, bool) or isinstance(right, bool):
        return isinstance(left, bool) and isinstance(right, bool) and left is right
    if isinstance(left, (int, float)) and isinstance(right, (int, float)):
        return left == right
    if isinstance(left, list) and isinstance(right, list):
        return len(left) == len(right) and all(jv_equal(a, b) for a, b in zip(left, right))
    if isinstance(left, dict) and isinstance(right, dict):
        return left.keys() == right.keys() and all(jv_equal(left[k], right[k]) for k in left)
    if type(left) is not type(right):
        return False
    return left == right


def _decode(line: str) -> tuple[bool, object]:
    try:
        return True, json.loads(line)
    except ValueError:
        return False, line


def outputs_match(expected: list[str], actual: list[str]) -> bool:
    if len(expected) != len(actual):
        return False
    for want, got in zip(expected, actual):
        want_ok, want_value = _decode(want)
        got_ok, got_value = _decode(got)
        if want_ok and got_ok:
            if not jv_equal(want_value, got_value):
                return False
        elif want.strip() != got.strip():
            return False
    return True


# --------------------------------------------------------------------------------------------
# Execution
# --------------------------------------------------------------------------------------------


def run_case(case: Case, argv: list[str], timeout: float) -> Result:
    try:
        completed = subprocess.run(
            [*argv, "-c", case.program],
            input=case.stdin,
            capture_output=True,
            text=True,
            timeout=timeout,
        )
    except subprocess.TimeoutExpired:
        return Result(case, ERROR, detail=f"timed out after {timeout:g}s")
    except OSError as exc:
        raise HarnessError(f"cannot execute {shlex.join(argv)}: {exc}") from exc

    actual = split_lines(completed.stdout)
    stderr = completed.stderr.strip()
    code = completed.returncode
    first_diagnostic = split_lines(stderr)[0] if stderr else ""

    if case.expect_failure:
        # The corpus's %%FAIL cases are programs that must be rejected at compile time. Accepting
        # one and then failing at run time is a different, wrong behaviour, so the compile-error
        # code specifically -- not merely a non-zero exit -- is what passes here.
        if code == EXIT_COMPILE_ERROR:
            return Result(case, PASS, return_code=code, stderr=stderr)
        detail = (
            "program was accepted, but the corpus marks it %%FAIL"
            if code == 0
            else f"exited {code}; a rejected program must exit {EXIT_COMPILE_ERROR}"
        )
        return Result(case, FAIL, detail=detail, actual=actual, return_code=code, stderr=stderr)

    if code == EXIT_COMPILE_ERROR:
        return Result(
            case,
            FAIL,
            detail=f"program did not compile: {first_diagnostic}",
            actual=actual,
            return_code=code,
            stderr=stderr,
        )
    if code not in (0, EXIT_RUNTIME_ERROR):
        # A runtime error is legitimate: several cases raise part-way through a generator and are
        # judged on the outputs produced before the raise, exactly as upstream judges them. Any
        # other non-zero status is the program failing in a way the contract does not describe.
        return Result(
            case,
            FAIL,
            detail=f"exited {code}: {first_diagnostic}",
            actual=actual,
            return_code=code,
            stderr=stderr,
        )
    if not outputs_match(case.expected, actual):
        return Result(
            case,
            FAIL,
            detail="output mismatch",
            actual=actual,
            return_code=code,
            stderr=stderr,
        )
    return Result(case, PASS, actual=actual, return_code=code, stderr=stderr)


# --------------------------------------------------------------------------------------------
# Reporting
# --------------------------------------------------------------------------------------------


def _render_failure(result: Result) -> str:
    case = result.case
    lines = [
        f"FAIL {CORPUS.name}:{case.line}  {result.detail}",
        f"    program:  {case.program}",
    ]
    if not case.expect_failure:
        lines.append(f"    input:    {case.stdin}")
        lines.append(f"    expected: {case.expected if case.expected else '(no output)'}")
        lines.append(f"    actual:   {result.actual if result.actual else '(no output)'}")
    if result.stderr:
        lines.append(f"    stderr:   {split_lines(result.stderr)[0]}")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Run the upstream jq conformance corpus against a candidate implementation.",
    )
    parser.add_argument("--jq", default=None, help="candidate command (default: $JQ)")
    parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT, help="seconds per case")
    parser.add_argument("--json", action="store_true", help="machine-readable report")
    parser.add_argument("-v", "--verbose", action="store_true", help="list passing cases too")
    parser.add_argument("--list", action="store_true", help="print the cases and run nothing")
    parser.add_argument(
        "--select",
        default=None,
        metavar="REGEX",
        help="run only cases whose program matches REGEX (development aid; the acceptance "
        "gate always runs the whole corpus)",
    )
    args = parser.parse_args(argv)

    try:
        return _run(args)
    except HarnessError as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2


def _run(args: argparse.Namespace) -> int:
    if not CORPUS.is_file():
        raise HarnessError(f"corpus not found at {CORPUS}")

    cases = parse_corpus(CORPUS.read_text(encoding="utf-8"))
    excluded = apply_exclusions(cases, parse_exclusions(EXCLUSIONS))

    selector = re.compile(args.select) if args.select else None
    if selector is not None:
        cases = [case for case in cases if selector.search(case.program)]

    if args.list:
        for case in cases:
            mark = "skip" if case.line in excluded else "run "
            print(f"{mark} {CORPUS.name}:{case.line}  {case.program}")
        print(f"\n{len(cases)} cases, {sum(1 for c in cases if c.line in excluded)} excluded")
        return 0

    command = args.jq or os.environ.get("JQ") or ""
    if not command.strip():
        raise HarnessError(
            "JQ is not set; give the command that runs your implementation, e.g.\n"
            '    JQ="$PWD/jq" python3 sources/run_conformance.py'
        )
    jq_argv = shlex.split(command)

    results: list[Result] = []
    for case in cases:
        if case.line in excluded:
            results.append(Result(case, SKIP, detail="declared in exclusions.txt"))
            continue
        results.append(run_case(case, jq_argv, args.timeout))

    tally = {status: sum(1 for r in results if r.status == status) for status in
             (PASS, FAIL, ERROR, SKIP)}
    summary = (
        f"jq conformance: {tally[PASS]} passed, {tally[FAIL]} failed, "
        f"{tally[ERROR]} errored, {tally[SKIP]} skipped "
        f"(corpus {CORPUS.name} @ jq-1.8.2)"
    )

    if args.json:
        print(json.dumps(
            {
                "candidate": jq_argv,
                "corpus": CORPUS.name,
                "summary": tally,
                "cases": [
                    {
                        "line": r.case.line,
                        "program": r.case.program,
                        "status": r.status,
                        "detail": r.detail,
                        "expect_failure": r.case.expect_failure,
                        "expected": r.case.expected,
                        "actual": r.actual,
                    }
                    for r in results
                    if args.verbose or r.status != PASS
                ],
            },
            indent=2,
        ))
    else:
        for result in results:
            if result.status in (FAIL, ERROR):
                print(_render_failure(result))
            elif args.verbose and result.status == PASS:
                print(f"ok   {CORPUS.name}:{result.case.line}  {result.case.program}")
            elif args.verbose and result.status == SKIP:
                print(f"skip {CORPUS.name}:{result.case.line}  {result.case.program}")
        print(summary)

    return 0 if tally[FAIL] == 0 and tally[ERROR] == 0 else 1


if __name__ == "__main__":
    raise SystemExit(main())

</pblock>

<pblock filename="ARCHITECTURE_compact.md" role="context" path="/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/blueprint/ARCHITECTURE_compact.md">

<!-- Compacted from ARCHITECTURE.md sha256=f0e07d8104b7c23be2772201e83dfaf382f4c295492da7b8ec72b2a914af633b on 2026-08-22 by drydock build agent -->

- Executable: `./jq -c '<program>'`; compact JSON lines on stdout.
- Exit codes: `0` success, `3` compile failure, `5` runtime failure; diagnostics on stderr.
- Standard-library Python only; no external jq, dependencies, networking, or persistence.
- Modules: CLI, lexer, parser/AST, evaluator streams, runtime values, builtins, paths/assignment, diagnostics.
- Preserve generator ordering, multiplicity, backtracking, immutable transformations, and partial output.

</pblock>

IMPLEMENTS - Authoritative Step Specifications

<pblock label="Implementation recency anchor" kind="section"> The files in this section are the load-bearing specifications for this build block. Build these files exactly. Treat earlier sections as constraints and context.

</pblock>

<pblock filename="FEATURE-CONF-002.md" role="implements" path="/mnt/c/Users/barlo/projects/drydock/uat/jq/runs/20260822.044627/workspace/targets/jq/blueprint/FEATURE-CONF-002.md" guidance="Feature Specification">

# FEATURE: Scoped Conformance Verification

| Field       | Value |
|-------------|-------|
| Version     | 20260822 V1 |
| Description | Provides executable, machine-readable scoped conformance verification. |
| Depends On  | ARCHITECTURE.md, FEATURE-CONF-001.md |
| Provides    | scoped conformance execution with JQ candidate binding |
| Consumes    | ./jq, sources/run_conformance.py |

## Workflow

Scoped verification invokes the supplied runner against a construct selector, extends the inherited environment with the candidate executable through `JQ`, parses the runner's JSON report, and requires every selected case to pass without errors.

## Programmatic Acceptance

=== AC conf-002-scoped-run ===
Intent: The scoped verification assets expose the candidate binding and machine-readable selector contracts.
Suite: scoped

from pathlib import Path

runner = Path("sources/run_conformance.py")
assert runner.is_file()
source = runner.read_text(encoding="utf-8")
assert "JQ" in source and "--select" in source and "--json" in source
=== END AC conf-002-scoped-run ===

## User Acceptance

- None.

## Guardrails

- Scoped verification must execute selected cases and must never use enumeration, dry-run, or unscoped execution as its product verdict.

</pblock>

<pblock label="Build instructions" kind="instructions">

Build instructions for this block

Provide scoped conformance verification. (CONF-002)

Verify that scoped acceptance invocations execute selected corpus cases with JQ extended from the inherited environment and machine-readable results.

</pblock>

Agent Task

You are a Drydock build agent implementing exactly one build step of a larger plan. The build job block below names the target, the build working directory, and the step. Everything you need is stacked into this prompt under role headings:

authoritative; implement them exactly.

Operating contract:

  1. Follow the write authorization and protected paths in the stacked COMPASS.md exactly.

That persisted guardrail is the sole authority for paths this build may modify.

  1. Start by inspecting the build working directory. Preserve existing application

files unless this step's specifications require a change. Its sources/ subdirectory holds staged build assets — imported test corpora, conformance harnesses, and fixtures — placed there for you. They are read-only inputs: run them, import them, and write code against them, but never create, rewrite, trim, regenerate, or substitute one, even to make a check pass. A step that modifies a staged asset fails and the asset is restored. If an asset you expect is absent, report that; do not author a replacement.

  1. Implement only this step. Use context, stack, and rules as constraints,

not as additional work to perform.

  1. Follow the stack and rules for languages, structure, naming, and branding.
  2. The programmatic acceptance assertions in the implements specifications are

this step's Definition of Done — human-owned, declared before the build, and fixed. Build the story and, in this same step, write the deterministic tests that prove each declared assertion, as a TDD master would; add finer tests for coverage. Every test you write follows the same rule the acceptance assertions do: act on the system, read the state back, compare to expected. The oracle is a return value, parsed JSON, a status code, a stored row, file contents read back, or an exit status — never a substring of captured stdout or stderr, a test-runner tally, or a log line. Write tests in the project's own language using that language's libraries; an in-language HTTP client yields a status code and a parsed body, where curl yields text to scrape. Round-trip anything that stores state: act, then read back through the public interface. Assert declared failure signals on negative paths, never message wording. You may add tests but must never remove, soften, or weaken a declared acceptance assertion. A Suite: full conformance check gates on the entire imported test suite: the step is done only when it passes in full, never on a representative subset — reproduce the standard exactly rather than wrapping a third-party library that approximates it. For a suite, the runner's exit status is the verdict and the whole verdict: print its captured output for diagnosis, never assert on the text of its summary. When an assertion is a static or filesystem scan (import boundary, "X never appears outside Y," grep/AST gate), honor the scope the specification states and never widen it: scan production source only, exclude .venv/, site-packages, and vendored or generated code, and do not flag test doubles or fixtures that use the guarded dependency. Run every declared acceptance assertion before returning. For a conformance suite, use its section or example filters to diagnose coherent root-cause clusters, but rerun the full declared scope before reporting the result. Treat failing examples as a work queue for fixing general behavior; never add example-specific exceptions.

  1. Grow the project's own test suite as you write the code, and treat it as the project's

real coverage. The acceptance assertions in implements are gates: few, fixed, and written before any code existed, so every expectation in them is a prediction. The tests you write are written beside the finished code, so their expected values are observed rather than predicted — which is why exhaustive coverage belongs here and not there. Extend the suite in the project's established location and runner, keep it runnable by the project's declared test command, and leave it green when you return. Cover, at minimum: every public entry point and every verb it declares, including declared error paths; the boundaries — empty, exactly one, many, absent optional fields, declared maxima; declared idempotence, applied twice; one behavior per test, named for the behavior; and isolation — each test arranges its own data, with a fresh store or explicit teardown, so a run leaves no residue behind in the build directory. Where a staged authoritative suite already covers a surface, that suite is the coverage: run it, and do not restate its cases. Run it only through the invocation this step's acceptance criteria declare. A criterion marked Suite: scoped names the whole of this step's obligation to that suite; running the suite's unscoped entry point instead is not extra rigor, it is a different step's gate executed early. A partial capability fails most of an authoritative corpus by construction and its unimplemented cases exhaust the runner's per-case timeout rather than returning, so the unscoped run costs the most where it teaches the least, and interrupting it forfeits the step. If no criterion in this step invokes the staged suite, do not invoke it. Report the pass/fail counts of the invocations you did run in your SUMMARY so a reader can see coverage moving across steps.

  1. Treat User Acceptance entries as review evidence requirements. Implement

the supporting behavior, but do not claim to have performed human judgment.

  1. The implements section is authoritative and intentionally stacked late in

the prompt as the recency anchor. Build that WHAT exactly; do not substitute generic framework defaults.

  1. Before adding or installing Python dependencies, verify each package name

against the declared registry. Do not invent package names. If a needed package cannot be verified or appears newly published, fail explicitly instead of installing it.

  1. Use the stack's required package manager workflow for dependency changes.

When the stack requires uv, update manifests through uv conventions rather than bare pip install.

  1. Do not claim success unless you actually created or modified project files in

the build working directory. If you cannot write files or cannot complete the step, report failure explicitly.

  1. Do not run git add, git commit, create branches, create tags, rewrite

history, or otherwise mutate Git history. Drydock owns the final build directory commit after you return.

  1. End your response with this exact closing structure:
RESULT: SUCCESS | FAILED

FILES CHANGED:
- relative/path

SUMMARY:
<brief reviewable summary>

BLOCKERS:
- <only if any>

Before RESULT, you may emit one optional JSON payload when implementation required a bounded choice not already settled by the owning specification. This records what you did; it does not ask permission, create a questionnaire, or excuse incomplete work:

<blueprint-decisions>
[{"spec":"FEATURE-Example.md","severity":"Material","subject":"Chosen behavior","decision":"Options A and B were available. I implemented B because ... Is that acceptable, or should this change on replan?"}]
</blueprint-decisions>

Name only a specification implemented by this build block. Use Low or Material; Build never emits a Blocking decision. Omit the payload when no implementation decision was necessary.

  1. FILES CHANGED must list only files actually written in the build working

directory. If no files were written, use RESULT: FAILED.

  1. On RESULT: FAILED, append two additional lines so the failure is actionable

without opening logs. FAILURE_SUMMARY is one line naming the cause; FAILURE_DETAIL states what happened, why, and what to change before a rerun. Name concrete conditions when they apply: token or context limit exceeded, could not execute commands in this environment, a required input was missing, or a specific tool or command failed.

FAILURE_SUMMARY: <one line naming the cause>
FAILURE_DETAIL: <what happened, why, and what to change before rerunning>
  1. When a declared acceptance criterion cannot pass no matter how the code is written,

say so with this exact token. You may not edit the criterion — it is staged and restored before grading:

AC_BROKEN: <check-id>[, <check-id>]

This is a report, not a verdict, and it stops nothing. A criterion reaches you only when its expected value is one its author could not have invented — a status code, a staged suite's exit status, a value the criterion itself supplied as input — so your claim that the criterion rather than the code is at fault is the less likely explanation, and the budget is spent as it would be for any other failure. A criterion whose expectation was hand-typed already settles DISPUTED on its own, without you naming it. Emit the token only after running the criterion and confirming the underlying command succeeded while the assertion still failed. Name the affected check ids, emit it alongside your normal RESULT line, state the reasoning in FAILURE_DETAIL, and emit it even when RESULT: SUCCESS. Do not use it for a criterion you merely failed to satisfy.