coldstart — ADLC P2 Ticket Executability Gate

Checks whether a ticket is fully self-contained before a build agent touches it. A cheap-tier LLM plays the role of a fresh agent with no prior context and lists every question it would have to ask a human before it could start executing. Empty gap list → gate passes (exit 0). Non-empty → exit 2 with gaps per ticket.

This is ADLC phase C3 / P2 — the last check before a ticket enters the build queue. Pennies per ticket; catches the #1 cause of build-phase flailing.

Usage

coldstart <ticket-id> [options]
coldstart --all     [options]

Options

Exit codes

Verdict shapes — what counts as "readable"

The auditor is asked to reply {"gaps": [...]}. A bare array ([{"what": …, "why_blocking": …}] — the most common model deviation) is accepted as the gaps list, and a string entry is wrapped as {"what": "<text>", "why_blocking": "unspecified"}. Anything else is not a pass: {}, {"result": "ok"}, {"blockers": [...]}, {"gaps": null}, {"gaps": "two gaps found"}, or an entry without a string what makes coldstart exit 1 with coldstart: unreadable executability verdict — … — the tool could not read the verdict, so it reports an operational error, records nothing, and never caches. A previously cached entry whose stored gaps is not a readable list is skipped rather than served as a hit (issue #594). The ADLC_GATE_MOCK_RESPONSE test seam follows the same rule: an unparseable or shape-deviant mock is exit 1, not [].

Examples

# Check a single ticket
coldstart T1

# Check all tickets, output JSON
coldstart --all --json

# Print the exact prompt without calling an LLM (paste into any harness)
coldstart T1 --prompt-only

# Use a custom tickets file
coldstart T3 --tickets path/to/tickets.json

Caching

A real (non---prompt-only) audit records {ticketHash, model, gaps} into .adlc/manifest.jsonl after it runs. The NEXT run, for the SAME ticket, skips the LLM call entirely when it finds a matching entry: same ticketHash (the ticket's content is unchanged — editing anything about it produces a different hash) and same resolved model id (not just the same --tier — switching ADLC_MODEL_CHEAP invalidates the cache even though --tier cheap stays the same flag). A cached run reports "cached": true in --json output and (cached) in the human-readable report.

# First run audits for real and records the verdict
coldstart --all

# Second run, nothing changed: instant, no LLM calls
coldstart --all

# Force a fresh audit regardless of any cache entry
coldstart --all --force

# Don't trust anything cached more than a week ago
coldstart --all --max-age 7

Caching only applies to the real LLM path — --prompt-only (with or without --record-verdict) is unaffected, and the ADLC_GATE_MOCK_RESPONSE test seam never reads or writes the cache (a mocked verdict must never be able to shadow, or be shadowed by, a real one).

Recording the operator's prompt-only verdict

In Claude Code (and similar harnesses without a bare API key) --prompt-only is how coldstart is normally run: the tool prints the audit prompt, and the operator (the model itself) answers it and applies judgment. Without --record-verdict, that self-assessed verdict is never captured — only the fact that a prompt was printed is observable. --record-verdict <file|-> closes that gap: after printing the prompt(s) as usual, it reads the operator's answer from <file> (or stdin when -) and records it into .adlc/manifest.jsonl via @adlc/gate-manifest's own record() — reusing its hash-chaining/signing logic rather than reimplementing it.

# Operator writes their answer to a file, then records it
coldstart T1 --prompt-only --record-verdict verdict.txt

# Or pipe the answer straight from stdin
echo '{"gaps":[],"ticketHash":"<ticketHash from `adlc ticket show T1 --json`>"}' \
  | coldstart T1 --prompt-only --record-verdict -

--record-verdict requires --prompt-only (exit 1 otherwise). The recorded entry's gate is coldstart, data.verdict holds the operator's text verbatim, and data.ticketIds lists every ticket the prompt covered (useful with --all). The P0 gate (packages/runner/lib/assertions.mjs) further requires data.verdict to be JSON matching {"gaps":[...],"ticketHash":"…"} with an empty gaps array and a ticketHash matching the ticket's current definition — free-form prose (e.g. "PASS: no gaps found") records successfully but fails the P0 assertion as invalid JSON.

What counts as a gap?

The model is instructed that information derivable from the repo does not count as missing. Only genuine human-only questions are gaps:

• Data shapes referenced but not embedded (e.g. "use the UserSchema" with no schema)
• Contracts named but absent (edge points to a missing type file)
• Acceptance criteria that cannot be mechanically verified
• Vague scope ("improve", "clean up", "fix")
• Unstated target files when they cannot be inferred from context

JSON output schema

{
  "ok": true,
  "results": [
    {
      "id": "T1",
      "pass": true,
      "gaps": []
    },
    {
      "id": "T2",
      "pass": false,
      "gaps": [
        { "what": "UserSchema", "why_blocking": "Shape referenced in body but not defined." }
      ]
    }
  ]
}

Provider configuration

The tool auto-detects the first available provider in order: ANTHROPIC_API_KEY → OPENAI_API_KEY → GEMINI_API_KEY.

Force a provider: ADLC_PROVIDER=openai. Override the cheap-tier model: ADLC_MODEL_CHEAP=claude-haiku-4-5.

Without a provider, the tool exits 1 unless --prompt-only is passed.

ADLC phase served

C3 / P2 — ticket executability gate. Runs after spec-lint (C1) and before the ticket enters the build queue. Part of the Cheap Wins cluster alongside C1 and C5 (rails-guard).

Core gaps

@adlc/core provides activeTickets to filter completed tickets (dropping them and stripping edges pointing to them, keeping the remaining DAG valid) when auditing open backlog. A by-id coldstart still uses the full set, so you can always audit a completed ticket you name explicitly. Everything else is available in @adlc/core: loadTickets, complete, extractJson, parseArgs, pass, gateFail, opError, printJson, promptOnly, detectProvider.