# 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. 2. **Input Context** — begins with the heading `# Input Context`. All blocks are wrapped in `` tags. Two block types: - File blocks: `` — optional `guidance` attribute carries context-specific instructions; content is in a fenced block. - Metadata/section blocks: `` — job parameters, rules, instructions, or group headers. 3. **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 ## Analysis job - BLUEPRINT_PATH: /mnt/c/Users/barlo/projects/drydock/uat/Toml/runs/20260814.050011/workspace/targets/toml/blueprint - DATE: 2026-08-14 - COMPASS_EXISTS: false - COMPASS_PENDING_FORMAT: false - DISPLAY_NAME: toml - SHORT_DESCRIPTION: (blank) ```markdown # Sea Trials: Toml ## Policy | Consequence | On FAIL | On INCONCLUSIVE | |---|---|---| | blocks | fail | attest | | scores | score | score | | attests | report | report | ## st-001: The supplied scoring script passes Type: technical Required: yes Criterion: The completed parser shall make sh sources/full_test.sh exit zero; that script's exit status is the sole acceptance verdict. Testability: deterministic Consequence: blocks Verification: proof Pattern: ubiquitous ``` ```markdown # Rigging Manifest Compact selection catalog for `drydock analyze` and QuarterDeck. Each entry names a real Rigging component available for Commander selection. The manifest is selection context only; Analyze does not open individual component files. | File | Category | Purpose | Prerequisites | |---|---|---|---| | `BRANDING_DOCUMENTATION.md` | Branding | The users voice for Documentation voice, structure, and presentation rules. | — | | `BRANDING_MAIN.md` | Branding | Core product branding (colors pallette etc ) and visual identity rules. | — | | `BRANDING_POSTS.md` | Branding | Social and announcement post branding rules. | `BRANDING_MAIN.md` | | `BRANDING_PROJECT_DOCS.md` | Branding | The users voice, structure, and editing protocol for the authoritative project specification document. | — | | `BRANDING_WEBSITE.md` | Branding | Website branding, voice, and presentation rules. | `BRANDING_MAIN.md` | | `BRANDING_WHITEPAPERS.md` | Branding | Whitepaper branding and long-form presentation rules. | `BRANDING_MAIN.md` | | `alexa-skills-kit.md` | AWS | Alexa Skill kit configuration, interaction models, and intent handling. | `common.md`, `python.md` | | `aws-api-gateway.md` | AWS | AWS HTTP API Gateway Rules. | `aws-lambda.md` | | `aws-dynamodb.md` | AWS | AWS DynamoDB single-table catalog and state patterns. | `cloud-client-library.md` | | `aws-lambda.md` | AWS | AWS Lambda handlers, packaging, IAM, and testing patterns. | `python.md` | | `aws-s3.md` | AWS | Private encrypted S3 storage and prefix-scoped sharing patterns. | `cloud-client-library.md` | | `aws-sqs.md` | AWS | SQS durable queue, polling, and error-handling patterns. | `aws-lambda.md` | | `bootstrap5.md` | Web Server | Bootstrap 5 layout, components, and form conventions. | — | | `cloud-client-library.md` | AWS | Encapsulated AWS library for use in applications; application dont uses boto3. | `python.md`, `persistence.md` | | `common.md` | Technologies | Common project layout, scripts, Git hygiene, and development workflow. | — | | `django.md` | Web Server | Django settings, ORM, migrations, admin, and web application patterns. | `common.md`, `python.md` | | `env_variables_and_secrets.md` | Technologies | Secret hygiene, environment validation, and `.env` discipline. | `common.md` | | `fastapi.md` | Web Server | FastAPI routers, dependency injection, templates, and testing patterns. | `common.md`, `python.md` | | `flask.md` | Web Server | Flask application factory, routes, templates, and error handling. | `common.md`, `python.md` | | `github-actions.md` | Technologies | GitHub Actions CI/CD with OIDC and lint/test gates. | `terraform.md`, `python.md` | | `go.md` | Technologies | Go module layout, errors, interfaces, concurrency, testing, and build gates. | `common.md` | | `persistence.md` | Persistence | Typed boundary for persistent stores and external services. | `common.md` | | `postgres.md` | Persistence | PostgreSQL schema, pooling, migrations, and indexing patterns. | `python.md`, `persistence.md` | | `python.md` | Technologies | Python conventions, typing, configuration, testing, and dependencies. | `common.md` | | `sqlite.md` | Persistence | SQLite connections, migrations, WAL, and typed access patterns. | `python.md`, `persistence.md` | | `terraform.md` | Technologies | Layered Terraform infrastructure and remote-state patterns. | `aws-dynamodb.md`, `aws-s3.md` | | `typescript.md` | Technologies | TypeScript strict typing, domain modeling, and boundary validation. | `common.md` | | `ui-flask.bootstrap-client.md` | Web Server | Focused Flask and Bootstrap screen implementation reference. | `flask.md`, `bootstrap5.md` | | `uv_ruff.md` | Technologies | uv environments and ruff lint/format workflow. | `python.md` | ``` ## Imported source files ## 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_test.sh` | code | analyzed | readable UTF-8 | | `sources/toml-v1.0.0.md` | markdown | analyzed | readable UTF-8 | ````markdown # 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: ```sh #!/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`): ```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": "", "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. | TOML | JSON | |---|---| | `a = 42` | `{"a": {"type": "integer", "value": "42"}}` | | `a = true` | `{"a": {"type": "bool", "value": "true"}}` | | `a = ["a", 2]` | `{"a": [{"type":"string","value":"a"}, {"type":"integer","value":"2"}]}` | | `[tbl]`
`a = 42` | `{"tbl": {"a": {"type": "integer", "value": "42"}}}` | ## 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): ```bash sh sources/setup_harness.sh ``` Then run the suite from the application directory. `DECODER` is required — the harness has no default implementation language: ```bash 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. 2. **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. 3. **Keys** — bare, quoted, and dotted keys; the redefinition rules. 4. **Tables** — `[table]`, `[a.b.c]` implicit creation, `[[array of tables]]`, and the rules governing which of these may follow which. 5. **Inline tables and arrays** — including nesting and the TOML 1.0 restriction that inline tables are closed to later extension. 6. **Datetimes** — offset, local datetime, local date, local time. 7. **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. ```` ```bash #!/bin/sh # full_test.sh — scoring entry point. Do not filter, skip, or reinterpret. set -eu # The version setup_harness.sh installs. run_conformance.sh refuses a different one, so a # passing verdict names a specific exam rather than whichever harness was on PATH. TOML_TEST_VERSION="${TOML_TEST_VERSION:-v2.2.0}" export TOML_TEST_VERSION go build -o toml-decoder ./cmd/toml-decoder DECODER="$PWD/toml-decoder" exec sh sources/run_conformance.sh ``` ```bash #!/bin/sh # Run the upstream toml-test conformance suite against the built decoder. # # Imported sources land in sources/ inside the application directory, so this is # normally invoked as `sh sources/run_conformance.sh` from that directory. # # Usage: # DECODER=./toml-decoder sh sources/run_conformance.sh # full suite # DECODER=./toml-decoder sh sources/run_conformance.sh -run 'valid/string/*' # one group # DECODER=./toml-decoder sh sources/run_conformance.sh -json # machine-readable # # Environment: # DECODER decoder command. Required — this harness is language-neutral and # deliberately has no default implementation language. # TOML_TEST absolute path to the toml-test binary (default: found on PATH) # # Exit code is the harness exit code: 0 only when every test passes. set -u if [ -z "${DECODER:-}" ]; then echo "error: DECODER is not set; give the command that runs your decoder." >&2 exit 2 fi if [ -n "${TOML_TEST:-}" ] && [ -x "${TOML_TEST}" ]; then HARNESS="${TOML_TEST}" elif command -v toml-test >/dev/null 2>&1; then HARNESS="$(command -v toml-test)" else cat >&2 <<'EOF' error: toml-test not found. Install the harness once: sh sources/setup_harness.sh or set TOML_TEST to an existing binary: TOML_TEST=/path/to/toml-test sh sources/run_conformance.sh EOF exit 127 fi # The suite's identity is part of the verdict. Without this, "the authoritative suite passed" # names no particular suite: whichever toml-test happened to be on PATH decided the run, and a # different version on a different machine is a different exam. Recorded always, and enforced # when the caller states which version it expects. HARNESS_VERSION="$("${HARNESS}" version 2>/dev/null | head -n 1 || true)" echo "harness: ${HARNESS} ${HARNESS_VERSION:-(version unknown)}" >&2 if [ -n "${TOML_TEST_VERSION:-}" ] && [ -n "${HARNESS_VERSION}" ]; then case "${HARNESS_VERSION}" in *"${TOML_TEST_VERSION}"*) ;; *) echo "error: harness is ${HARNESS_VERSION}, expected ${TOML_TEST_VERSION}." >&2 echo "Run: sh sources/setup_harness.sh" >&2 exit 2 ;; esac fi NO_COLOR=1 exec "${HARNESS}" test -toml 1.0 -decoder "${DECODER}" "$@" ``` ```bash #!/bin/sh # One-time installation of the upstream toml-test conformance harness. # # Requires network access and a Go toolchain of at least 1.22 — the same floor # stack/go.md sets for the deliverable. The Go shipped by apt on Debian and # Ubuntu is frequently older and will fail; install the official tarball instead: # # curl -sL https://go.dev/dl/go1.24.6.linux-amd64.tar.gz -o go.tgz # sudo tar -C /usr/local -xzf go.tgz # export PATH=/usr/local/go/bin:$PATH # # Usage: # sh sources/setup_harness.sh # install to $HOME/.local/bin # GOBIN=/usr/local/bin sh sources/setup_harness.sh set -eu TOML_TEST_VERSION=v2.2.0 GOBIN="${GOBIN:-$HOME/.local/bin}" if ! command -v go >/dev/null 2>&1; then echo "error: no go toolchain on PATH; see the header of this script" >&2 exit 1 fi echo "go: $(go version)" echo "target: ${GOBIN}/toml-test" echo "version: ${TOML_TEST_VERSION}" mkdir -p "${GOBIN}" GOBIN="${GOBIN}" go install \ "github.com/toml-lang/toml-test/v2/cmd/toml-test@${TOML_TEST_VERSION}" echo "${GOBIN}/toml-test" version case ":${PATH}:" in *":${GOBIN}:"*) ;; *) echo echo "warning: ${GOBIN} is not on PATH. Add it, or export" echo " TOML_TEST=${GOBIN}/toml-test before running the suite." ;; esac ``` ```bash #!/bin/sh # stage_test.sh — governed stage gate. Runs one slice of the authoritative suite. # # Same contract as full_test.sh, scoped to the cases a single story owns: build the decoder, # then run the installed toml-test suite over the pattern given as $1. Exit status is the # verdict and the whole verdict. Do not filter, skip, or reinterpret. set -eu if [ $# -ne 1 ]; then echo "usage: stage_test.sh " >&2 exit 2 fi TOML_TEST_VERSION="${TOML_TEST_VERSION:-v2.2.0}" export TOML_TEST_VERSION go build -o toml-decoder ./cmd/toml-decoder DECODER="$PWD/toml-decoder" exec sh sources/run_conformance.sh -run "$1" ``` ````markdown ![TOML Logo](logos/toml-200.png) TOML v1.0.0 =========== Tom's Obvious, Minimal Language. By Tom Preston-Werner, Pradyun Gedam, et al. Objectives ---------- TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages. Table of contents ----------------- - [Spec](#spec) - [Comment](#comment) - [Key/Value Pair](#keyvalue-pair) - [Keys](#keys) - [String](#string) - [Integer](#integer) - [Float](#float) - [Boolean](#boolean) - [Offset Date-Time](#offset-date-time) - [Local Date-Time](#local-date-time) - [Local Date](#local-date) - [Local Time](#local-time) - [Array](#array) - [Table](#table) - [Inline Table](#inline-table) - [Array of Tables](#array-of-tables) - [Filename Extension](#filename-extension) - [MIME Type](#mime-type) - [ABNF Grammar](#abnf-grammar) Spec ---- * TOML is case-sensitive. * A TOML file must be a valid UTF-8 encoded Unicode document. * Whitespace means tab (0x09) or space (0x20). * Newline means LF (0x0A) or CRLF (0x0D 0x0A). Comment ------- A hash symbol marks the rest of the line as a comment, except when inside a string. ```toml # This is a full-line comment key = "value" # This is a comment at the end of a line another = "# This is not a comment" ``` Control characters other than tab (U+0000 to U+0008, U+000A to U+001F, U+007F) are not permitted in comments. Key/Value Pair -------------- The primary building block of a TOML document is the key/value pair. Keys are on the left of the equals sign and values are on the right. Whitespace is ignored around key names and values. The key, equals sign, and value must be on the same line (though some values can be broken over multiple lines). ```toml key = "value" ``` Values must have one of the following types. - [String](#string) - [Integer](#integer) - [Float](#float) - [Boolean](#boolean) - [Offset Date-Time](#offset-date-time) - [Local Date-Time](#local-date-time) - [Local Date](#local-date) - [Local Time](#local-time) - [Array](#array) - [Inline Table](#inline-table) Unspecified values are invalid. ```toml key = # INVALID ``` There must be a newline (or EOF) after a key/value pair. (See [Inline Table](#inline-table) for exceptions.) ``` first = "Tom" last = "Preston-Werner" # INVALID ``` Keys ---- A key may be either bare, quoted, or dotted. **Bare keys** may only contain ASCII letters, ASCII digits, underscores, and dashes (`A-Za-z0-9_-`). Note that bare keys are allowed to be composed of only ASCII digits, e.g. `1234`, but are always interpreted as strings. ```toml key = "value" bare_key = "value" bare-key = "value" 1234 = "value" ``` **Quoted keys** follow the exact same rules as either basic strings or literal strings and allow you to use a much broader set of key names. Best practice is to use bare keys except when absolutely necessary. ```toml "127.0.0.1" = "value" "character encoding" = "value" "ʎǝʞ" = "value" 'key2' = "value" 'quoted "value"' = "value" ``` A bare key must be non-empty, but an empty quoted key is allowed (though discouraged). ```toml = "no key name" # INVALID "" = "blank" # VALID but discouraged '' = 'blank' # VALID but discouraged ``` **Dotted keys** are a sequence of bare or quoted keys joined with a dot. This allows for grouping similar properties together: ```toml name = "Orange" physical.color = "orange" physical.shape = "round" site."google.com" = true ``` In JSON land, that would give you the following structure: ```json { "name": "Orange", "physical": { "color": "orange", "shape": "round" }, "site": { "google.com": true } } ``` For details regarding the tables that dotted keys define, refer to the [Table](#table) section below. Whitespace around dot-separated parts is ignored. However, best practice is to not use any extraneous whitespace. ```toml fruit.name = "banana" # this is best practice fruit. color = "yellow" # same as fruit.color fruit . flavor = "banana" # same as fruit.flavor ``` Indentation is treated as whitespace and ignored. Defining a key multiple times is invalid. ``` # DO NOT DO THIS name = "Tom" name = "Pradyun" ``` Note that bare keys and quoted keys are equivalent: ``` # THIS WILL NOT WORK spelling = "favorite" "spelling" = "favourite" ``` As long as a key hasn't been directly defined, you may still write to it and to names within it. ``` # This makes the key "fruit" into a table. fruit.apple.smooth = true # So then you can add to the table "fruit" like so: fruit.orange = 2 ``` ``` # THE FOLLOWING IS INVALID # This defines the value of fruit.apple to be an integer. fruit.apple = 1 # But then this treats fruit.apple like it's a table. # You can't turn an integer into a table. fruit.apple.smooth = true ``` Defining dotted keys out-of-order is discouraged. ```toml # VALID BUT DISCOURAGED apple.type = "fruit" orange.type = "fruit" apple.skin = "thin" orange.skin = "thick" apple.color = "red" orange.color = "orange" ``` ```toml # RECOMMENDED apple.type = "fruit" apple.skin = "thin" apple.color = "red" orange.type = "fruit" orange.skin = "thick" orange.color = "orange" ``` Since bare keys can be composed of only ASCII integers, it is possible to write dotted keys that look like floats but are 2-part dotted keys. Don't do this unless you have a good reason to (you probably don't). ```toml 3.14159 = "pi" ``` The above TOML maps to the following JSON. ```json { "3": { "14159": "pi" } } ``` String ------ There are four ways to express strings: basic, multi-line basic, literal, and multi-line literal. All strings must contain only valid UTF-8 characters. **Basic strings** are surrounded by quotation marks (`"`). Any Unicode character may be used except those that must be escaped: quotation mark, backslash, and the control characters other than tab (U+0000 to U+0008, U+000A to U+001F, U+007F). ```toml str = "I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF." ``` For convenience, some popular characters have a compact escape sequence. ``` \b - backspace (U+0008) \t - tab (U+0009) \n - linefeed (U+000A) \f - form feed (U+000C) \r - carriage return (U+000D) \" - quote (U+0022) \\ - backslash (U+005C) \uXXXX - unicode (U+XXXX) \UXXXXXXXX - unicode (U+XXXXXXXX) ``` Any Unicode character may be escaped with the `\uXXXX` or `\UXXXXXXXX` forms. The escape codes must be valid Unicode [scalar values](https://unicode.org/glossary/#unicode_scalar_value). All other escape sequences not listed above are reserved; if they are used, TOML should produce an error. Sometimes you need to express passages of text (e.g. translation files) or would like to break up a very long string into multiple lines. TOML makes this easy. **Multi-line basic strings** are surrounded by three quotation marks on each side and allow newlines. A newline immediately following the opening delimiter will be trimmed. All other whitespace and newline characters remain intact. ```toml str1 = """ Roses are red Violets are blue""" ``` TOML parsers should feel free to normalize newline to whatever makes sense for their platform. ```toml # On a Unix system, the above multi-line string will most likely be the same as: str2 = "Roses are red\nViolets are blue" # On a Windows system, it will most likely be equivalent to: str3 = "Roses are red\r\nViolets are blue" ``` For writing long strings without introducing extraneous whitespace, use a "line ending backslash". When the last non-whitespace character on a line is an unescaped `\`, it will be trimmed along with all whitespace (including newlines) up to the next non-whitespace character or closing delimiter. All of the escape sequences that are valid for basic strings are also valid for multi-line basic strings. ```toml # The following strings are byte-for-byte equivalent: str1 = "The quick brown fox jumps over the lazy dog." str2 = """ The quick brown \ fox jumps over \ the lazy dog.""" str3 = """\ The quick brown \ fox jumps over \ the lazy dog.\ """ ``` Any Unicode character may be used except those that must be escaped: backslash and the control characters other than tab, line feed, and carriage return (U+0000 to U+0008, U+000B, U+000C, U+000E to U+001F, U+007F). You can write a quotation mark, or two adjacent quotation marks, anywhere inside a multi-line basic string. They can also be written just inside the delimiters. ```toml str4 = """Here are two quotation marks: "". Simple enough.""" # str5 = """Here are three quotation marks: """.""" # INVALID str5 = """Here are three quotation marks: ""\".""" str6 = """Here are fifteen quotation marks: ""\"""\"""\"""\"""\".""" # "This," she said, "is just a pointless statement." str7 = """"This," she said, "is just a pointless statement."""" ``` If you're a frequent specifier of Windows paths or regular expressions, then having to escape backslashes quickly becomes tedious and error-prone. To help, TOML supports literal strings which do not allow escaping at all. **Literal strings** are surrounded by single quotes. Like basic strings, they must appear on a single line: ```toml # What you see is what you get. winpath = 'C:\Users\nodejs\templates' winpath2 = '\\ServerX\admin$\system32\' quoted = 'Tom "Dubs" Preston-Werner' regex = '<\i\c*\s*>' ``` Since there is no escaping, there is no way to write a single quote inside a literal string enclosed by single quotes. Luckily, TOML supports a multi-line version of literal strings that solves this problem. **Multi-line literal strings** are surrounded by three single quotes on each side and allow newlines. Like literal strings, there is no escaping whatsoever. A newline immediately following the opening delimiter will be trimmed. All other content between the delimiters is interpreted as-is without modification. ```toml regex2 = '''I [dw]on't need \d{2} apples''' lines = ''' The first newline is trimmed in raw strings. All other whitespace is preserved. ''' ``` You can write 1 or 2 single quotes anywhere within a multi-line literal string, but sequences of three or more single quotes are not permitted. ```toml quot15 = '''Here are fifteen quotation marks: """""""""""""""''' # apos15 = '''Here are fifteen apostrophes: '''''''''''''''''' # INVALID apos15 = "Here are fifteen apostrophes: '''''''''''''''" # 'That,' she said, 'is still pointless.' str = ''''That,' she said, 'is still pointless.'''' ``` Control characters other than tab are not permitted in a literal string. Thus, for binary data, it is recommended that you use Base64 or another suitable ASCII or UTF-8 encoding. The handling of that encoding will be application-specific. Integer ------- Integers are whole numbers. Positive numbers may be prefixed with a plus sign. Negative numbers are prefixed with a minus sign. ```toml int1 = +99 int2 = 42 int3 = 0 int4 = -17 ``` For large numbers, you may use underscores between digits to enhance readability. Each underscore must be surrounded by at least one digit on each side. ```toml int5 = 1_000 int6 = 5_349_221 int7 = 53_49_221 # Indian number system grouping int8 = 1_2_3_4_5 # VALID but discouraged ``` Leading zeros are not allowed. Integer values `-0` and `+0` are valid and identical to an unprefixed zero. Non-negative integer values may also be expressed in hexadecimal, octal, or binary. In these formats, leading `+` is not allowed and leading zeros are allowed (after the prefix). Hex values are case-insensitive. Underscores are allowed between digits (but not between the prefix and the value). ```toml # hexadecimal with prefix `0x` hex1 = 0xDEADBEEF hex2 = 0xdeadbeef hex3 = 0xdead_beef # octal with prefix `0o` oct1 = 0o01234567 ```` ````markdown oct2 = 0o755 # useful for Unix file permissions # binary with prefix `0b` bin1 = 0b11010110 ``` Arbitrary 64-bit signed integers (from −2^63 to 2^63−1) should be accepted and handled losslessly. If an integer cannot be represented losslessly, an error must be thrown. Float ----- Floats should be implemented as IEEE 754 binary64 values. A float consists of an integer part (which follows the same rules as decimal integer values) followed by a fractional part and/or an exponent part. If both a fractional part and exponent part are present, the fractional part must precede the exponent part. ```toml # fractional flt1 = +1.0 flt2 = 3.1415 flt3 = -0.01 # exponent flt4 = 5e+22 flt5 = 1e06 flt6 = -2E-2 # both flt7 = 6.626e-34 ``` A fractional part is a decimal point followed by one or more digits. An exponent part is an E (upper or lower case) followed by an integer part (which follows the same rules as decimal integer values but may include leading zeros). The decimal point, if used, must be surrounded by at least one digit on each side. ``` # INVALID FLOATS invalid_float_1 = .7 invalid_float_2 = 7. invalid_float_3 = 3.e+20 ``` Similar to integers, you may use underscores to enhance readability. Each underscore must be surrounded by at least one digit. ```toml flt8 = 224_617.445_991_228 ``` Float values `-0.0` and `+0.0` are valid and should map according to IEEE 754. Special float values can also be expressed. They are always lowercase. ```toml # infinity sf1 = inf # positive infinity sf2 = +inf # positive infinity sf3 = -inf # negative infinity # not a number sf4 = nan # actual sNaN/qNaN encoding is implementation-specific sf5 = +nan # same as `nan` sf6 = -nan # valid, actual encoding is implementation-specific ``` Boolean ------- Booleans are just the tokens you're used to. Always lowercase. ```toml bool1 = true bool2 = false ``` Offset Date-Time ---------------- To unambiguously represent a specific instant in time, you may use an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time with offset. ```toml odt1 = 1979-05-27T07:32:00Z odt2 = 1979-05-27T00:32:00-07:00 odt3 = 1979-05-27T00:32:00.999999-07:00 ``` For the sake of readability, you may replace the T delimiter between date and time with a space character (as permitted by RFC 3339 section 5.6). ```toml odt4 = 1979-05-27 07:32:00Z ``` Millisecond precision is required. Further precision of fractional seconds is implementation-specific. If the value contains greater precision than the implementation can support, the additional precision must be truncated, not rounded. Local Date-Time --------------- If you omit the offset from an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time, it will represent the given date-time without any relation to an offset or timezone. It cannot be converted to an instant in time without additional information. Conversion to an instant, if required, is implementation-specific. ```toml ldt1 = 1979-05-27T07:32:00 ldt2 = 1979-05-27T00:32:00.999999 ``` Millisecond precision is required. Further precision of fractional seconds is implementation-specific. If the value contains greater precision than the implementation can support, the additional precision must be truncated, not rounded. Local Date ---------- If you include only the date portion of an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time, it will represent that entire day without any relation to an offset or timezone. ```toml ld1 = 1979-05-27 ``` Local Time ---------- If you include only the time portion of an [RFC 3339](https://tools.ietf.org/html/rfc3339) formatted date-time, it will represent that time of day without any relation to a specific day or any offset or timezone. ```toml lt1 = 07:32:00 lt2 = 00:32:00.999999 ``` Millisecond precision is required. Further precision of fractional seconds is implementation-specific. If the value contains greater precision than the implementation can support, the additional precision must be truncated, not rounded. Array ----- Arrays are square brackets with values inside. Whitespace is ignored. Elements are separated by commas. Arrays can contain values of the same data types as allowed in key/value pairs. Values of different types may be mixed. ```toml integers = [ 1, 2, 3 ] colors = [ "red", "yellow", "green" ] nested_arrays_of_ints = [ [ 1, 2 ], [3, 4, 5] ] nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ] string_array = [ "all", 'strings', """are the same""", '''type''' ] # Mixed-type arrays are allowed numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ] contributors = [ "Foo Bar ", { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" } ] ``` Arrays can span multiple lines. A terminating comma (also called a trailing comma) is permitted after the last value of the array. Any number of newlines and comments may precede values, commas, and the closing bracket. Indentation between array values and commas is treated as whitespace and ignored. ```toml integers2 = [ 1, 2, 3 ] integers3 = [ 1, 2, # this is ok ] ``` Table ----- Tables (also known as hash tables or dictionaries) are collections of key/value pairs. They are defined by headers, with square brackets on a line by themselves. You can tell headers apart from arrays because arrays are only ever values. ```toml [table] ``` Under that, and until the next header or EOF, are the key/values of that table. Key/value pairs within tables are not guaranteed to be in any specific order. ```toml [table-1] key1 = "some string" key2 = 123 [table-2] key1 = "another string" key2 = 456 ``` Naming rules for tables are the same as for keys (see definition of [Keys](#keys) above). ```toml [dog."tater.man"] type.name = "pug" ``` In JSON land, that would give you the following structure: ```json { "dog": { "tater.man": { "type": { "name": "pug" } } } } ``` Whitespace around the key is ignored. However, best practice is to not use any extraneous whitespace. ```toml [a.b.c] # this is best practice [ d.e.f ] # same as [d.e.f] [ g . h . i ] # same as [g.h.i] [ j . "ʞ" . 'l' ] # same as [j."ʞ".'l'] ``` Indentation is treated as whitespace and ignored. You don't need to specify all the super-tables if you don't want to. TOML knows how to do it for you. ```toml # [x] you # [x.y] don't # [x.y.z] need these [x.y.z.w] # for this to work [x] # defining a super-table afterward is ok ``` Empty tables are allowed and simply have no key/value pairs within them. Like keys, you cannot define a table more than once. Doing so is invalid. ``` # DO NOT DO THIS [fruit] apple = "red" [fruit] orange = "orange" ``` ``` # DO NOT DO THIS EITHER [fruit] apple = "red" [fruit.apple] texture = "smooth" ``` Defining tables out-of-order is discouraged. ```toml # VALID BUT DISCOURAGED [fruit.apple] [animal] [fruit.orange] ``` ```toml # RECOMMENDED [fruit.apple] [fruit.orange] [animal] ``` The top-level table, also called the root table, starts at the beginning of the document and ends just before the first table header (or EOF). Unlike other tables, it is nameless and cannot be relocated. ```toml # Top-level table begins. name = "Fido" breed = "pug" # Top-level table ends. [owner] name = "Regina Dogman" member_since = 1999-08-04 ``` Dotted keys create and define a table for each key part before the last one, provided that such tables were not previously created. ```toml fruit.apple.color = "red" # Defines a table named fruit # Defines a table named fruit.apple fruit.apple.taste.sweet = true # Defines a table named fruit.apple.taste # fruit and fruit.apple were already created ``` Since tables cannot be defined more than once, redefining such tables using a `[table]` header is not allowed. Likewise, using dotted keys to redefine tables already defined in `[table]` form is not allowed. The `[table]` form can, however, be used to define sub-tables within tables defined via dotted keys. ```toml [fruit] apple.color = "red" apple.taste.sweet = true # [fruit.apple] # INVALID # [fruit.apple.taste] # INVALID [fruit.apple.texture] # you can add sub-tables smooth = true ``` Inline Table ------------ Inline tables provide a more compact syntax for expressing tables. They are especially useful for grouped data that can otherwise quickly become verbose. Inline tables are fully defined within curly braces: `{` and `}`. Within the braces, zero or more comma-separated key/value pairs may appear. Key/value pairs take the same form as key/value pairs in standard tables. All value types are allowed, including inline tables. Inline tables are intended to appear on a single line. A terminating comma (also called trailing comma) is not permitted after the last key/value pair in an inline table. No newlines are allowed between the curly braces unless they are valid within a value. Even so, it is strongly discouraged to break an inline table onto multiples lines. If you find yourself gripped with this desire, it means you should be using standard tables. ```toml name = { first = "Tom", last = "Preston-Werner" } point = { x = 1, y = 2 } animal = { type.name = "pug" } ``` The inline tables above are identical to the following standard table definitions: ```toml [name] first = "Tom" last = "Preston-Werner" [point] x = 1 y = 2 [animal] type.name = "pug" ``` Inline tables are fully self-contained and define all keys and sub-tables within them. Keys and sub-tables cannot be added outside the braces. ```toml [product] type = { name = "Nail" } # type.edible = false # INVALID ``` Similarly, inline tables cannot be used to add keys or sub-tables to an already-defined table. ```toml [product] type.name = "Nail" # type = { edible = false } # INVALID ``` Array of Tables --------------- The last syntax that has not yet been described allows writing arrays of tables. These can be expressed by using a header with a name in double brackets. The first instance of that header defines the array and its first table element, and each subsequent instance creates and defines a new table element in that array. The tables are inserted into the array in the order encountered. ```toml [[products]] name = "Hammer" sku = 738594937 [[products]] # empty table within the array [[products]] name = "Nail" sku = 284758393 color = "gray" ``` In JSON land, that would give you the following structure. ```json { "products": [ { "name": "Hammer", "sku": 738594937 }, { }, { "name": "Nail", "sku": 284758393, "color": "gray" } ] } ``` Any reference to an array of tables points to the most recently defined table element of the array. This allows you to define sub-tables, and even sub-arrays of tables, inside the most recent table. ```toml [[fruits]] name = "apple" [fruits.physical] # subtable color = "red" shape = "round" [[fruits.varieties]] # nested array of tables name = "red delicious" [[fruits.varieties]] name = "granny smith" [[fruits]] name = "banana" [[fruits.varieties]] name = "plantain" ``` The above TOML maps to the following JSON. ```json { "fruits": [ { "name": "apple", "physical": { "color": "red", "shape": "round" }, "varieties": [ { "name": "red delicious" }, { "name": "granny smith" } ] }, { "name": "banana", "varieties": [ { "name": "plantain" } ] } ] } ``` If the parent of a table or array of tables is an array element, that element must already have been defined before the child can be defined. Attempts to reverse that ordering must produce an error at parse time. ``` # INVALID TOML DOC [fruit.physical] # subtable, but to which parent element should it belong? color = "red" shape = "round" [[fruit]] # parser must throw an error upon discovering that "fruit" is # an array rather than a table name = "apple" ``` ```` ````markdown Attempting to append to a statically defined array, even if that array is empty, must produce an error at parse time. ``` # INVALID TOML DOC fruits = [] [[fruits]] # Not allowed ``` Attempting to define a normal table with the same name as an already established array must produce an error at parse time. Attempting to redefine a normal table as an array must likewise produce a parse-time error. ``` # INVALID TOML DOC [[fruits]] name = "apple" [[fruits.varieties]] name = "red delicious" # INVALID: This table conflicts with the previous array of tables [fruits.varieties] name = "granny smith" [fruits.physical] color = "red" shape = "round" # INVALID: This array of tables conflicts with the previous table [[fruits.physical]] color = "green" ``` You may also use inline tables where appropriate: ```toml points = [ { x = 1, y = 2, z = 3 }, { x = 7, y = 8, z = 9 }, { x = 2, y = 4, z = 8 } ] ``` Filename Extension ------------------ TOML files should use the extension `.toml`. MIME Type --------- When transferring TOML files over the internet, the appropriate MIME type is `application/toml`. ABNF Grammar ------------ A formal description of TOML's syntax is available, as a separate [ABNF file][abnf]. [abnf]: https://github.com/toml-lang/toml/blob/1.0.0/toml.abnf ```` # Agent Task # Agent for: blueprint analysis You are the **Team Lead conducting the Product Owner feedback session**. You are the team's Agile expert and follow Agile best practices. Your handoff is deliberately completeness-oriented: do not finish until the supplied Commander intent can be handed to Plan as a coherent, buildable epic. You have received imported source material — one or more documents describing what the product should do. Your job is to analyze that input and produce summary information which will be output to curated files. The core elements are defined below. --- ## Agile Story Decomposition Your goal is to do planning for the information you have imported. You will be creating a set of Agile features and stories. Features group stories; they are the only grouping unit used by `ANALYSIS.md` and the Commanders Chair. You raise anything the human must decide as either a blocker or a discovery questionnaire. A blocker means the sources cannot be analyzed into a coherent product decomposition. A discovery questionnaire records a finite Commander decision. Mark a questionnaire question `"required_before_plan": true` when planning cannot author an internally consistent specification until it is answered. Stack selection and unresolved conflicting definitions are required planning decisions. A story is an atomic testable unit of work that might have acceptance criteria and guardrails at a later stage. Stories include user interface screens, the routes used to service those screens, cli options, api served, batch scripts needed, import/export operations, and other atomic units of work according to agile best practices. Do not create a separate Screens grouping or count; UI screens are stories under the relevant Agile feature. **Story granularity.** A story is a normal Agile story: 1 to 5 story points. Never a half point — that is a task, and a task is folded into the story it serves rather than listed beside it. Never twelve — that is split. A story does one thing completely and is releasable on its own; a task is not releasable and is therefore not a story. "Add a button" and "add a test" are tasks. Size by that judgement alone: a story has no token dimension, and story count is an output of correct decomposition, never a target to hit or avoid. You will note the interrelationships between these elements — for example, a user interface screen uses api calls, and an export depends on the data it reads. Note them to inform how you cut stories; do not build a dependency graph. The graph is constructed later, by `plan create`. You will also look at the technologies mentioned in the sources and create a list. If a needed technology is implied but never named — for example a web server is required but none is chosen — surface that as a blocking stack question. When you look at a story that you have created, if it is complex, attempt to break it up into smaller stories. In the agile process, it is preferable to use multiple smaller stories rather than one larger one. A very good way to understand this is that the stories you are identifying will eventually, in another command, become markdown files with their specifications included. That markdown will have Acceptance Criteria, GuardRails, and interrelationships. Do not calculate these now; when you define the stories, use the natural boundaries provided within the input files for accuracy of breakdown. Content rearranged at a later step is costly, so cut along the natural groupings that occur within the input. Derive strategic goals and success criteria only where the sources state or directly imply them. Do not invent business outcomes, thresholds, or acceptance commitments. **Project-fact authority.** Prompt context and Commander input are authoritative for the project being analyzed. General knowledge may explain a supplied source, but it must not supply, replace, or refine a project requirement. In particular, do not infer, recall, estimate, or invent a project-specific count, version, limit, threshold, or test total. **Universal acceptance preservation.** When a source says `all`, `every`, `complete`, `100%`, `zero failures`, `zero errors`, or equivalent universal language, preserve that universal form. Do not translate it into a numeric cardinality, a `Target:` value, an `Extract:` value, or an exact passed-count assertion. A supplied full test suite proves such a requirement by running unfiltered and succeeding; it does not require the Commander to specify how well the software should work. Be sure to understand the architecture and component structure. An input failure that prevents coherent analysis is a blocker. A blocker is not a product choice between identifiable alternatives: emit that choice as a required discovery questionnaire. When you find one or more blockers, write `BLOCKERS.md`; its mere existence stops downstream steps until the human clears it. When there are no blockers, do not write the file. Finally - we use our COMPASS to guide the build. **Ownership test for discovery questionnaires.** A discovery questionnaire captures a question *only the human can answer* — a decision the team genuinely cannot make from the sources. Raise one only when the answer turns on something the sources do not contain: business priority, product taste, an external or regulatory constraint, an irreversible trade-off, or a genuinely absent fact (for example, no auth model stated for a product that clearly needs one). **Cross-source conflict test.** Compare all source definitions of the same product concept, including default workflows, state vocabularies and transitions, roles and permissions, routes and interfaces, data ownership, and behavioral defaults. Two incompatible definitions with no explicit precedence are a human-owned decision even though both alternatives appear in the sources. Emit one questionnaire question that names the conflicting files and presents the concrete alternatives. Set `"required_before_plan": true`; do not choose an alternative, merge incompatible definitions, defer the choice to a planning spike, or emit it as `BLOCKERS.md` when the rest of the product can still be analyzed. Anything you can derive from the sources, you **must derive** — into the story list, Surfaced Acceptance Criteria, or SEA_TRIALS. Never ask the human to supply work the team owns. In particular, acceptance criteria, smoke checks, build gates, and test sequences are *outputs you synthesize*, not questions you ask. Outcome baselines, business thresholds, observation windows, and external measurement sources are different: never invent them. Record the criterion and emit a stable-ID entry under the SEA_TRIALS.md `## Questions` section for each missing human-owned measurement fact. A discovery questionnaire is delivered as a form for the human to answer. Do not raise one for a matter the sources, `ANALYZE_COMPASS.md`, prior `BLOCKERS.md` answers, or existing answered questionnaires have already decided, nor for anything you can derive yourself. Capture the Commander's product and project expectations as concise assertions. Prefer direct, observable wording such as `assert the product runs a web server` or `assert cloud publication is optional`. These are stakeholder satisfaction conditions, not implementation tasks. --- ## Inputs - **Imported source files** — one or more documents from `blueprint/sources/`, injected below the job block. - **Analyze feedback (standing directive)** — `ANALYZE_COMPASS.md`, persistent human direction injected near the top of this prompt when present. Treat it as authoritative steering for this run; it overrides default decomposition choices where it speaks. - **Prior blocker answers** — any prior `BLOCKERS.md` responses, injected if present. Treat settled items as decided; never re-raise a resolved blocker or duplicate it as a questionnaire. - **Existing discovery questionnaires** — prior `discovery-*.json` action items, injected when present. They are input to this run, not output of it. Every non-empty `answer`, `resolution`, and `additional_notes` field is a Commander decision and is authoritative: apply it to the story list, the stack, the scope, `SEA_TRIALS.md`, and the quality signal, and never contradict it or re-open it. Do not re-emit an existing questionnaire file, do not ask duplicate or reworded versions of existing unanswered questions, and do not move questionnaire questions into `ANALYSIS.md`. Questionnaire files are owned by the Commander; Drydock never rewrites them. - **COMPASS_EXISTS** — `true`: COMPASS.md exists at the target root. `false`: write it. - **COMPASS_PENDING_FORMAT** — `true`: COMPASS.md was imported as raw Commander intent and is injected as an input block. Rewrite it into the canonical COMPASS.md format and emit the `=== BEGIN ARTIFACT COMPASS.md ===` block. `false`: if `COMPASS_EXISTS: true`, omit the block. - **DISPLAY_NAME** — current `display_name` value from METADATA.md, or `(blank)` when not yet set. - **SHORT_DESCRIPTION** — current `short_description` value from METADATA.md, or `(blank)` when not yet set. - **Rigging manifest** — `Rigging/MANIFEST.md`, injected below. It names the real selectable components with their category, purpose, and prerequisites. Use it to recommend a small subset; never open the individual component rule files. --- ## Quality Signal After analysis, compute one of three quality values: | Quality | Condition | Pipeline | |---|---|---| | `Blocked` | One or more blockers exist (`BLOCKERS.md` is written) | Halts — `plan create` must not proceed | | `Questions` | No blockers; open questions remain | `plan create` may proceed after all required planning questions are answered | | `Ready` | No blockers; no open questions | `plan create` may proceed | **Blocker** — the team cannot produce a coherent analysis or finite decision form. Examples: no understanding of what the product does, unreadable authoritative inputs, or decomposition beyond the story cap. A contradiction with identifiable alternatives is instead a required discovery questionnaire. One or more blockers means you write `BLOCKERS.md`; its existence is the flag that halts the pipeline. Quality stays `Blocked` until the human clears it. **Question** — an open item that does not stop decomposition. Delivered only as a discovery questionnaire action item and carried forward there. A question marked `required_before_plan` does not stop analysis, but it gates planning because Plan cannot author a consistent specification without the decision. Blockers halt analysis progression. Every question marked `required_before_plan` gates `plan create`; other questionnaire action items distinguish `Questions` from `Ready` but do not gate. `TECHNOLOGY_STACK.md` never gates planning. --- ## Gap Checklist Run this checklist over the **imported sources** (and the `ANALYZE_COMPASS.md` standing directive, if injected). There are no typed spec files at analyze time — judge each item solely against what the sources state. An item the team cannot proceed without at all is a blocker (see step 3); every other unmet item routes to exactly one of three places — never leave one unrouted, never route it twice: | The team can derive the answer, and it is... | Goes to | |---|---| | scoped to one story | a row in `## Surfaced Acceptance Criteria` (step 6) | | project-wide (a guardrail, outcome, or cross-cutting behavior) | a `SEA_TRIALS.md` criterion (step 7) | | only the human can decide (the Ownership test, see above) | a discovery questionnaire question (step 9) | ### Product - [ ] Product goal is stated (what the product is and why) - [ ] Short description is present (one-sentence summary of what the product is) - [ ] Success criteria are stated - [ ] Acceptance criteria are stated per described feature or screen - [ ] Primary workflows are enumerated, not just individual screens or endpoints ### Security - [ ] Auth/authz model is named for any protected resource - [ ] Sensitive data handling (PII, secrets, compliance) is addressed where implied ### User Experience - [ ] Empty, loading, and error states are described for interactive features - [ ] UI structure is described clearly enough to decompose (web products only) - [ ] A first-time user could complete the primary flow from the sources alone ### Architecture - [ ] Stack is named in the sources or prior answers (not empty or TBD) - [ ] Persistence model is described, if the product persists data - [ ] External service calls have defined timeout/failure behavior - [ ] Deployment target is stated ### Edge Cases - [ ] Negative paths are addressed (invalid input, auth failure, not-found) - [ ] Concurrency/race conditions are addressed where the sources describe shared state ### Core Baseline Apply only the row matching the project type detected in step 2. | Type | Check | |---|---| | `web` | Primary entry point/landing page is defined; help/support is reachable from navigation | | `cli` | Every command/sub-verb has help text defined | | `api` / `library` | A reference/discovery entry point is defined | | `pipeline` / `event-driven` | Primary trigger and output/consumer are both defined | --- ## Tasks This is a sequential pipeline. Execute the steps in order; each step **consumes** the prior step's output and **emits** the named result. Do not re-derive an artifact independently when a prior step already produced its input. **1. Review the sources.** - *Consumes:* imported sources + `ANALYZE_COMPASS.md` direction + prior `BLOCKERS.md` answers. - *Emits:* working notes — what is clear, what is missing, what must be answered. **2. Detect project type.** - *Consumes:* the content and structure of the imported sources. - *Emits:* one of `web | api | cli | library | pipeline | event-driven` (or `ambiguous`). Detect from what the sources *describe*, not from any filename — there are no typed spec files at analyze time: | Type | Signals in the sources | |---|---| | `web` | Described screens, pages, or HTTP routes for human users | | `api` | Described programmatic endpoints / capabilities; no screens | | `cli` | Described commands and sub-verbs; no routes or screens | | `library` | Described public API symbols consumed by other code; no routes, no screens | | `pipeline` | Described datasets, files, or batch transforms; no routes | | `event-driven` | Described topics, queues, or event types | Mixed signals → `ambiguous`. **3. Identify blockers vs questions.** - *Consumes:* the review notes + completeness checklist. - *Emits:* the blocker list and the questionnaire action-item list. First perform the Cross-source conflict test. Blockers halt the pipeline; write `BLOCKERS.md` only when one or more exist. Questions are carried forward only as discovery questionnaires. A questionnaire records a Commander decision; mark it `required_before_plan` when a consistent plan depends on the answer. It never resolves a blocker. Do not duplicate a questionnaire question in `ANALYSIS.md`. **4. Derive the feature and story list.** - *Consumes:* the sources + role notes + project type. - *Emits:* the Agile feature list and story list at title + high-level AC level (powers ANALYSIS.md `## Story List`). - Each feature is an Agile feature area that groups related stories. - Each story corresponds to one spec file scope. - Story cap: ~100 stories. If you identify more than 100, the spec is over-decomposed; surface this as a blocker and offer to consolidate. - Group all stories under `### Feature: {Feature Name}` headings. Do not use Screens as a separate grouping; screens are stories. **5. Derive test criteria from the story list.** - *Consumes:* the story list (and any explicit acceptance criteria stated in the sources). - *Emits:* high-level acceptance criteria in `ANALYSIS.md` Story List rows. Do not emit `SOUNDINGS.md` — it is written only by `drydock score ac`. **6. Derive Surfaced Acceptance Criteria from the Gap Checklist.** - *Consumes:* the Gap Checklist findings routed to "scoped to one story". - *Emits:* the `## Surfaced Acceptance Criteria` rows in `ANALYSIS.md` (see Output Format), each tied to a real Story ID from the Story List. - Before finalizing, confirm coverage: - [ ] Every Gap Checklist item routed as story-scoped has a corresponding row - [ ] Every row references a real Story ID from the Story List - [ ] No row restates an AC already explicit in the sources **7. Derive SEA_TRIALS project acceptance.** - *Consumes:* the story list + the Gap Checklist findings routed to "project-wide" + the COMPASS (existing file or the COMPASS you will emit in step 10). - *Emits:* structured SEA_TRIALS.md project criteria with stable IDs, one observable behavior or outcome per criterion, EARS wording and a `Pattern` where it reads clearly, a `guardrail` for each prohibition the sources state or imply, and unresolved measurement facts under `## Questions`. - Before finalizing, confirm coverage: - [ ] A guardrail exists for every explicit or clearly implied prohibition - [ ] A timeout/failure criterion exists for every external service call the sources describe - [ ] An outcome criterion exists for every stated business/success goal - [ ] A security/compliance criterion exists where sensitive data or auth is implied - Any statement of complete project behavior, release threshold, end-to-end verification command, or project-wide deterministic outcome belongs only in `SEA_TRIALS.md`. Do not emit it as a story-scoped acceptance criterion. **8. Compute the quality signal.** - *Consumes:* the blocker and question counts from step 3. - *Emits:* `Blocked | Questions | Ready` per the Quality Signal table. Surfaced Acceptance Criteria and SEA_TRIALS criteria do not affect this count — only blockers and open questionnaire questions do. **9. Build the discovery questionnaires.** - *Consumes:* the project type + questionnaire action-item list (including Gap Checklist findings routed to "only the human can decide") + injected Rigging manifest. - *Emits:* `TECHNOLOGY_STACK.md` on every run plus one `discovery-.json` per open important question. Set `"required_before_plan": true` on every unresolved cross-source conflict or other decision without which Plan cannot author one internally consistent specification. These are questionnaire gates and are never emitted in `BLOCKERS.md`. Gap Checklist questions default to one consolidated `discovery-gaps.json`; split into `discovery-gaps-2.json`, etc. only past 5–6 questions in this run. Do not emit a questionnaire for a matter the sources or prior answers have already settled. Do not emit a questionnaire that duplicates an existing unanswered questionnaire. Existing questionnaires are preserved indefinitely and never rewritten or replaced. On re-analysis, emit each genuinely new, non-duplicate question in a new `discovery-.json` file. - **Story-count sanity question.** When the story list exceeds **80** stories, emit one `discovery-story-count.json` asking the Commander to confirm the granularity. A high count is a signal that tasks were listed as stories, not a reason to refuse: never drop, merge, or withhold stories to get under the number, and never cap the list. Ask, emit the full list, and let the Commander decide. Phrase the question with the real count and offer a target, for example: "Analysis decomposed this epic into 257 stories, which is high for one Blueprint and usually means tasks were listed as stories. Is this granularity correct, or supply a target NUMBER of stories for a replan." Set `"required_before_plan": false` — the plan is usable either way. Do not emit it when an equivalent unanswered questionnaire already exists. **10. Emit all output blocks.** See Output Format below. Emit the `BLOCKERS.md` block only when blockers exist; emit the `COMPASS.md` block when `COMPASS_EXISTS: false` or `COMPASS_PENDING_FORMAT: true`. --- ## Output Format Emit blocks only in this order. Conditional blocks are omitted when their condition is false: `ANALYSIS.md`, `SEA_TRIALS.md`, `TECHNOLOGY_STACK.md`, `BLOCKERS.md`, `COMPASS.md`, `discovery-identity.json`, then `discovery-gaps*.json` and other `discovery-.json` blocks in lexical filename order. **Nothing outside the blocks.** No preamble, no explanation, no commentary, no tool calls, no `` XML. Start your response with `=== BEGIN ARTIFACT ANALYSIS.md ===`. ``` === BEGIN ARTIFACT ANALYSIS.md === # Blueprint Analysis: {ProjectName} ## Commander Expectations - assert {one product or project outcome the Commander expects} ## 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 Use this exact repeated shape. The `features` summary count must equal the number of `### Feature:` headings. The `stories` summary count must equal the total number of story rows across all feature tables. ### Feature: {Feature Name} | ID | Story | High-level AC | |---|---|---| | {FEATURE-SLUG}-001 | {Story title} | {High-level acceptance signal} | ## Surfaced Acceptance Criteria The analyze step has surfaced these acceptance criteria for `drydock plan` to fold into the relevant story's typed specification. "None." if the Gap Checklist surfaced no story-scoped items. | ID | Story ID | Criterion | |---|---|---| | AC-001 | {FEATURE-SLUG}-001 | {One observable behavior the story must satisfy} | ## Relationship Model Infer cross-file delivery relationships from the imported source material. Supporting implementation, helper, fixture, and test files are evidence for the capability they enable, not independent stories. Use concise cited paths such as `sources/tests/test_parser.py`. | Source or group | Relationship type | Related source or group | Evidence | Delivery implication | |---|---|---|---|---| | {source path/group} | {instruction-to-test | test-kit-to-implementation | implementation-to-helper | reference-to-replacement | parser-to-normalizer | dependency} | {source path/group} | {specific cited evidence} | {planning consequence} | ## Source Roles Classify every imported file cited above. `author intent` is routed to COMPASS and is not a standalone build-context file. Test suites and harnesses are context/staged assets, never implements files. | Path | Role | Plan disposition | Build disposition | |---|---|---|---| | {sources/path} | {author intent | normative specification and conformance test suite | conformance harness | test helper | reference implementation | source reference | asset} | {compass | context | exclude} | {stage | prompt-only | none} | Build disposition governs what exists on disk when the build agent runs and when acceptance executes: - `stage` places the file in the build directory at `sources/{path relative to sources/}`. Every assertion, `ac` check, and Sea Trial `Command:` references it by that build-relative path. A test suite or harness the project must execute is always `stage` — a file present only in the prompt can be read but not run. **Everything a staged file needs at run time is also `stage`**: a harness's imported modules, its normalizer, and its fixtures. Read each staged file's imports and open() calls and stage what they name; a harness missing one dependency cannot run at all. - `prompt-only` supplies the file as prompt context and places nothing on disk. - `none` neither stages nor supplies it. Markdown is never staged; use `prompt-only` for it. ## Planning Instructions ### Delivery Shape State the inferred system/pipeline, major inputs and outputs, and required execution flow. ### Story Realization Map For every Story ID, state the durable Blueprint scope(s), cited `sources/...` evidence, related files, and whether it requires a capability, integration, migration, test harness, or acceptance contract. ### Test and Acceptance Strategy State focused story tests separately from final Sea Trial verification. Programmatic acceptance is finite and story-scoped by default. When the imported sources include a conformance harness and its test suite, exactly one terminal verification story gates on the complete suite. That story depends on every implementation story, and its acceptance assertion declares `Suite: full` in its heading block so the full run is deliberate. Every other story stays bounded and must never run the whole suite: a story that executes the runner only to prove it works bounds the run with the runner's `--pattern`/`--number` selector; a feature story runs the slice it owns and declares `Suite: scoped`. A sample proves a unit works, never that the project is correct. State a source-supplied numeric release threshold as a Sea Trial, not as a story assertion. A complete-suite requirement is a proof gate, not a measured release threshold. ### Sequencing and Dependencies State Manifest ordering constraints, including build-before-test, parser-before-normalizer, fixture-before-verification, and external dependencies. ### Source Conflicts and Gaps State contradictions or missing information that must remain blockers or questionnaires. Do not silently resolve them. ## Analysis Notes generated: {ISO date} blueprint: {BLUEPRINT_PATH from job block} Quality: {Ready | Questions | Blocked} blockers: {N} questions: {N} features: {N} stories: {N} stack: {declared stack value or "not declared"} display_name: {proposed display name derived from the sources, or "not proposed" when DISPLAY_NAME is already set} short_description: {one-sentence product description derived from the sources, or "not proposed" when SHORT_DESCRIPTION is already set} {Non-conformant headers, ambiguous signals, observations. "None." if clean. Do not add an ## Overview section or any other sections not listed here. Drydock deterministically adds Source Inventory and Resolved Blockers after this output; do not emit either section.} === END ARTIFACT === === BEGIN ARTIFACT SEA_TRIALS.md === # Sea Trials: {ProjectName} Project-level acceptance derived from COMPASS and sources. Emit 3–7 criteria normally, plus any guardrail the sources state or clearly imply. Emit criteria only — Drydock injects the reader documentation. Never emit `###` headings or explanatory prose. ## st-001: {Short criterion title} Type: {technical | behavioral | qualitative | outcome | guardrail} Required: {yes | no} Criterion: {One observable behavior or outcome. Preferably EARS-shaped for technical, behavioral, and guardrail; plain English where that reads more clearly, and always for qualitative and outcome.} Verification: {proof | measurement | evidence | llm} Pattern: {optional — ubiquitous | event | state | option | unwanted; declare it only when the Criterion is written in that shape} Emit only populated optional fields. Each field occupies its own line; align values after the field names. Do not combine fields on one line. Command: {JSON argv array} Extract: {regex whose first capture group is the measured number in the command's stdout} Evidence: {target-relative evidence file} Baseline: {numeric value} Operator: {< | <= | == | >= | >} Target: {numeric value} Unit: {unit} A `measurement` criterion carries `Command:` plus either `Extract:` or `Evidence:`. Without them it is INCONCLUSIVE and can never settle. `Command:` is a literal argv that runs from the build directory. It never contains a `` — Drydock does not resolve one, and a placeholder argv silently never runs. Name the staged harness by its build path (`sources/{name}`) and the deliverable by its real entry point. `Extract:` lets Drydock read the value from a harness that reports in human-readable text; without it the command must print `{"value": , "unit": ""}`. Prefer `Extract:` over asking the project to emit JSON — a wrapper that computes its own score can report anything. When the sources supply a conformance harness and require complete conformance, emit exactly one `proof` criterion that executes the unfiltered full suite. Its criterion says that every supplied case passes; its `Command:` is the literal full-suite argv. Do not add `Extract:`, `Baseline:`, `Operator:`, `Target:`, or `Unit:`. The terminal Blueprint assertion declares `Suite: full` and proves the same Sea Trial with the harness exit status and zero failures/errors where reported. Use `measurement` only when the source or Commander states a genuinely numeric requirement, such as latency, throughput, cost, capacity, or an explicit numeric release threshold. Do not ask a question for a missing threshold when the source already requires all supplied tests to pass. {Repeat one section per criterion.} ## Questions ### Q-st-001-baseline: {Short question name} - Origin: analyze-questionnaire - Status: open #### Question {Human-owned missing measurement fact.} #### Answer === END ARTIFACT === ``` **BLOCKERS.md block (conditional):** Emit only when one or more blockers exist. When there are no blockers, do not emit this block — its absence is what lets the pipeline proceed. Never emit the block with placeholder text (e.g. "none", "(omitted)") in place of real blockers; omit it entirely. ``` === BEGIN ARTIFACT BLOCKERS.md === # Blockers: {ProjectName} Each blocker is a question the human must answer before `plan create` runs. The Commander records the decision only under `### Commander Resolution`; the next `drydock analyze` run reads it. Do not remove the blocker heading or write an answer outside that subsection. ## blocker-001: {Short title} {What is blocking and why the team cannot proceed without it.} ### Commander Resolution === END ARTIFACT === ``` **COMPASS.md block (conditional):** Emit when `COMPASS_EXISTS: false` or `COMPASS_PENDING_FORMAT: true` in the job block. If `COMPASS_EXISTS: true` and `COMPASS_PENDING_FORMAT: false`, omit this block entirely. When `COMPASS_PENDING_FORMAT: true`, preserve the imported Commander intent, constraints, and guardrails, but normalize them into the canonical sections below. Do not weaken, replace, or summarize away specific strategic direction. The COMPASS.md is injected into **every build step** as orientation for the building agent. It must be short (30–40 lines maximum), synthesized, and written for an agent about to write code — not for a human reader, and not as project documentation. Do **not** reproduce source files verbatim. Do not write API references, usage guides, feature lists, or architecture narrations. Extract only: what the product is and who it serves (one paragraph); hard technical/regulatory/operating constraints (bullets); behavioral guardrails the build agent must never violate (bullets). ``` === BEGIN ARTIFACT COMPASS.md === # COMPASS: {ProjectName} ## Compass {One paragraph: what this product is, who it serves, and why it exists. Written for a developer joining the project for the first time. Be specific and concise. Do NOT reproduce source file content. Synthesize.} ## Constraints {Bullet list: hard technical, regulatory, scale, and operating constraints derived from the sources. These bound what the agent may build — runtime, compatibility, environment, operating limits. Do NOT list the technology stack here; technologies belong only in TECHNOLOGY_STACK.md. "- None stated." if the sources are silent.} ## Guardrails {Bullet list: behavioral rules the building agent must never violate — security, compliance, scale, performance, irreversible trade-offs, or explicit prohibitions from the Commander. "- None stated." if the sources are silent.} === END ARTIFACT === ``` **Discovery questionnaires (`discovery-*.json`) — emit one per open question, none for decided matters.** Every block must pass the Ownership test: a decision only the human can make. Use these topics as a checklist of what to probe, but emit a block only where the sources (and any prior answers) leave a human-owned decision open: - **identity** — the project display name and short description (see the identity rule below) - **intent** — what the product is, who it serves, how success is measured (only where the sources genuinely leave the product's purpose or audience open) - **stack** — the technology stack (see the stack rule below) - **guardrails** — security, compliance, scale, or performance constraints the sources do not state but the human must set - **gaps** — Gap Checklist findings routed to "only the human can decide"; consolidate into one `discovery-gaps.json` by default, splitting only past 5–6 questions in a run (step 9) - plus any genuine project-specific decision only the human owns Underspecified acceptance criteria, success evidence, smoke checks, build gates, and test sequences that the team can derive are outputs you synthesize (into Surfaced Acceptance Criteria or SEA_TRIALS), never questions you ask. Only a Gap Checklist finding that fails the Ownership test becomes a `discovery-gaps.json` question. Each questionnaire uses this shape: ``` === BEGIN ARTIFACT discovery-{slug}.json === { "id": "discovery-{slug}", "title": "Discovery: {Short Title}", "purpose": "{One sentence: what decision this questionnaire resolves.}", "questions": [ { "id": "{question_slug}", "label": "{Short Label}", "prompt": "{Full question for the Product Owner.}", "input": "text | textarea | select | checkbox_grid", "proposed": "{Optional proposed value for the Commander to confirm or override}", "required_before_plan": false, "answer": "{Optional current answer. Use the proposed value for generated identity answers; use an empty string for undecided stack selections.}" } ] } === END ARTIFACT === ``` **Identity questionnaire rule.** When `DISPLAY_NAME` is `(blank)` or `SHORT_DESCRIPTION` is `(blank)` in the job block, derive a proposed display name and one-sentence short description from the sources, include them in the `display_name` and `short_description` summary fields in `ANALYSIS.md`, and emit a `discovery-identity.json` questionnaire for the Commander to confirm or override. Use the `proposed` field and the `answer` field on each question to pre-fill the proposed value. The `answer` field must match the value analyze writes to METADATA.md so QuarterDeck does not render an empty box. Do **not** emit `discovery-identity.json` when both `DISPLAY_NAME` and `SHORT_DESCRIPTION` are already set (i.e., neither is `(blank)`). ``` === BEGIN ARTIFACT discovery-identity.json === { "id": "discovery-identity", "title": "Discovery: Project Identity", "purpose": "Confirm the proposed display name and short description before planning.", "questions": [ { "id": "display_name", "label": "Display Name", "prompt": "The display name Drydock will use for this project. Edit to override the proposal.", "input": "text", "proposed": "{Proposed display name derived from the sources}", "answer": "{Proposed display name derived from the sources}" }, { "id": "short_description", "label": "Short Description", "prompt": "One-sentence description of what this project does. Edit to override the proposal.", "input": "textarea", "proposed": "{Proposed one-sentence description derived from the sources}", "answer": "{Proposed one-sentence description derived from the sources}" } ] } === END ARTIFACT === ``` **Technology Stack rule.** Always emit `TECHNOLOGY_STACK.md`: one row per technology the sources show the product using, in dependency order (language, framework, persistence, infrastructure, tooling). Drydock discards the block when the file already exists, so this proposal never overwrites a Commander decision. The `Rigging` column names a file from the injected Rigging catalog, or `—` when no catalog file governs that technology. A technology with no Rigging file is normal and expected — record the technology anyway. Never omit a technology because the catalog lacks a matching file, never invent a Rigging filename that is not in the catalog, and never list a Rigging file that no row uses. Derive the technologies from the sources. Where the sources are silent on a slot the product plainly needs, propose the conventional choice and say so in `Notes`. Do not emit a stack blocker and do not raise a stack questionnaire; the Commander edits this file directly. ``` === BEGIN ARTIFACT TECHNOLOGY_STACK.md === # Technology Stack | Technology | Rigging | Notes | |---|---|---| | {Technology name as the product uses it} | {catalog filename or —} | {Short note, or empty} | === END ARTIFACT === ``` --- ## Hard Rules - Emit **only** `=== BEGIN ARTIFACT ===` / `=== END ARTIFACT ===` blocks. The name is typed once, at the open. The closing delimiter is the constant token `=== END ARTIFACT ===` — never repeat the name in it, and never substitute the artifact's title or heading for it. No text outside them — no preamble, no summary, no prose, no commentary, no tool calls, no `` or `` XML. Any output outside a delimited block is a protocol violation and will cause the run to fail. - Emit the `BLOCKERS.md` block only when one or more blockers exist; its existence halts the pipeline. - Emit the `COMPASS.md` block only when `COMPASS_EXISTS: false` or `COMPASS_PENDING_FORMAT: true`. - Emit `discovery-identity.json` only when `DISPLAY_NAME` or `SHORT_DESCRIPTION` is `(blank)` in the job block. When both are already set, omit it entirely. - COMPASS.md must be ≤40 lines. It is injected into every build step — brevity is a hard requirement. - COMPASS.md is orientation for a build agent, not project documentation. Never reproduce source file content verbatim, never write API references or usage guides, never narrate architecture. Synthesize intent, constraints, and guardrails only. - Never enumerate the technology stack in COMPASS.md. The stack is recorded once, in `TECHNOLOGY_STACK.md`, and reaches the builder through per-story `stack:` fields. - Never emit a questionnaire that asks the Commander to select the technology stack or Rigging files. That decision lives in `TECHNOLOGY_STACK.md`. - Do not include `## Questions` or any duplicate question list in `ANALYSIS.md`. Nonblocking questions live only in `discovery-*.json` questionnaire action items. - `## Surfaced Acceptance Criteria` is always present in `ANALYSIS.md`, "None." when empty. Its row count is never counted toward the Quality Signal or the `questions`/`blockers` summary fields. - Every Gap Checklist finding routes to exactly one of: `## Surfaced Acceptance Criteria`, `SEA_TRIALS.md`, or a `discovery-gaps.json` question — never more than one, never left unrouted. - Gap Checklist questions default to one `discovery-gaps.json`; split into numbered continuations only past 5–6 questions in a single run. - Emit a `discovery-*.json` questionnaire only for a decision only the human can make (the Ownership test). Never emit one for a matter the sources or prior answers have already decided, never as a generic catch-all, and never for work the team can derive itself (acceptance criteria, success evidence, smoke checks, build gates, test sequences — these are synthesized outputs). - Compare competing definitions of every shared product concept across all imported sources. Emit each unresolved incompatibility as a questionnaire question with `"required_before_plan": true`; never silently select, merge, or defer conflicting defaults. - Story list is titles + high-level AC only. Do not write typed spec file content. - Story list uses `### Feature: {Feature Name}` headings and `| ID | Story | High-level AC |` tables only. Do not emit `| # | Story |`, unheaded story tables, a separate Screens section, or narrative notes inside `## Story List`. - The `features` summary count equals the number of `### Feature:` headings. The `stories` summary count equals the number of story rows in those feature tables. These counts must tie to the Analysis tab and Commanders Chair. - Story cap: if you derive more than 100 stories, surface as a blocker. - Never re-ask a question already settled by `ANALYZE_COMPASS.md`, a prior `BLOCKERS.md`, or an existing questionnaire answer. Never emit a duplicate or reworded version of an existing unanswered questionnaire. - Preserve every existing questionnaire indefinitely. Never rewrite or replace an existing questionnaire; emit genuinely new, non-duplicate questions in new `discovery-.json` files. - Never open individual Rigging component rule files; the catalog supplies filenames only. - Never emit a `select` or `multiselect` question without a non-empty `options` list. A free-text decision uses `"input": "textarea"`. - A named technology with a matching manifest component informs the proposal; it is not a confirmed selection. A named technology with no matching component is a discovery questionnaire. - Story List high-level AC: use acceptance criteria stated in the sources where present; otherwise synthesize one milestone per feature area / screen / persistence area. - SEA_TRIALS.md criteria are project-level and use stable `st-*` IDs. Preserve prior IDs for the same criterion on reruns. Technical and behavioral criteria normally use Blueprint proof; outcomes use measurement; subjective criteria use evidence-bound LLM judgment. - Technical, behavioral, and guardrail criteria are preferably written in EARS, declaring the `Pattern` their `Criterion` matches: | Pattern | Shape | |---|---| | `ubiquitous` | `The shall ` | | `event` | `When , the shall ` | | `state` | `While , the shall ` | | `option` | `Where , the shall ` | | `unwanted` | `If , then the shall ` | A criterion in EARS begins with its pattern's leading keyword (`The`, `When`, `While`, `Where`, `If`) and makes the system under test the grammatical subject of `shall`. Prefer the system's point of view — `The parser shall pass every supplied CommonMark conformance example.` over `Every supplied CommonMark conformance example shall pass.` Where a requirement is clearer in plain English, write it in plain English and omit `Pattern`; clarity outranks the notation. `Pattern` is optional on every criterion, and declaring it commits the sentence to that shape. - Never emit a `Notation` field. Drydock derives it from the `Pattern` and the `Criterion`, marking each criterion `ears` or `other`. Both are equally binding and neither affects any verdict. - Qualitative and outcome criteria are plain English and leave `Pattern` blank. They are measurement contracts settled by `Baseline`, `Operator`, `Target`, and `Unit`. - A `guardrail` is an absolute prohibition the project may never do — a *never*, not a target. It is a prohibition written either as `Pattern: unwanted` when it has a trigger (`If , then the shall `), or as a negative `Pattern: ubiquitous` when the prohibition is unconditional (`The shall not/never `). A breach fails delivery regardless of every score. Raise one only where the sources state or clearly imply a prohibition; never invent one to be thorough. - Prefer `proof` or `measurement` for required technical, behavioral, and guardrail criteria. A required assertion resting only on `llm` judgment reduces the project's acceptance coverage score. - Never invent outcome baselines, targets, units, or external measurement sources. Emit stable-ID `## Questions` records for missing human-owned facts. Emit `- None.` when none remain. - Never emit a `discovery-sea-trials.json` block. Sea Trials questions live in the SEA_TRIALS.md `## Questions` section; Drydock projects them into that questionnaire itself. - The SEA_TRIALS.md `## Questions` section holds only human-owned measurement facts (baselines, targets, workloads, business measures). Never place a stack or Rigging selection question there — the technology stack is owned solely by `TECHNOLOGY_STACK.md` and must appear in no questionnaire. Drydock drops any stack/Rigging question found in the Sea Trials Questions section. - All questionnaire JSON must be valid JSON. - Do not write to `blueprint/` or read `MANIFEST.md`. Read imported sources — there are no typed spec files at analyze time, so do not inspect or invent them. - Do not fabricate requirements or problems the sources do not imply. A genuinely absent decision (e.g. no auth model stated) is a real gap — route it under this prompt's blocker and questionnaire rules, not as an invented requirement. --- Use the preceding job metadata, prior answers (if any), and imported source files for this run.