[ea-open-source]

Summary

CONTRACT.md named one import warning code (history_floor_clamped) where the server defines five, and two import_github_* error codes where the server defines eight. It also said a bad token answers 400 import_github_auth. On agile-tracker origin/main 79f2240e4, that code arrives as the error_code of a failed job, not as a 400.

This PR adds two tables to CONTRACT.md and pins both with tests. No src/ change: warningLine already renders all five server shapes correctly.

After the review panel, CONTRACT.md also does these things:

• It scopes the job-code rows to the listing queries and lists the exceptions verified on the server: the blockedBy rule (#384801), the first-error rule, a blockedBy follow-up page error, and a comment follow-up NOT_FOUND.
• It states the exact rate-limit retry behaviour. The server retries an HTTP refusal up to 3 times and never retries a GraphQL RATE_LIMITED.
• It quotes the stderr lines that the user sees, including the doubled import failed: prefix of a failed job. Another story covers that prefix.

Story: https://eastagiletracker.com/s/zewsdmja (#1124732)

Warning codes (ImportResult.warnings)

Code	Added by	GitHub import can raise it?
history_floor_clamped	#32239	Yes, any source with imported stories; the only code that carries floor_year
cross_reference_links_failed	#55746	Yes, GitHub only, only with include_pull_requests, committing run only (matches the dry-run paragraph from #81)
dependencies_fetch_failed	#163271	Yes, GitHub only, only with include_dependencies
dependencies_truncated	#146020	Yes, GitHub only, only with include_dependencies
estimates_unpointed_dropped	#558598	No. The GitHub connector sets no estimate on any row, and the server ignores check_unpointed_estimates for github

GitHub error codes

Code	Added by	Arrives as
import_github_no_token	#26479	400 response to the POST
import_github_shared_quota_low	#47448	400 response to the POST
import_github_auth	#14628	error_code of a failed job
import_github_forbidden	#14628	error_code of a failed job
import_github_not_found	#14628	error_code of a failed job
import_github_rate_limited	#14628	error_code of a failed job
import_github_rate_limited_platform	#47445	error_code of a failed job
import_github_unavailable	#1087819	error_code of a failed job

CONTRACT.md also says when the server raises each code. Every row was read from agile-tracker origin/main 79f2240e4 (validate_github_request, ensure_shared_pat_budget, github_fetch_error, job_error_parts, From<GithubImportError> for AppError, http_status_error, classify_gql_errors).

Amended acceptance criteria

The user widened the error list from four codes to all eight import_github_* codes on agile-tracker origin/main.

Tests

• history_floor_clamped renders its count and its floor year: one exact note: line.
• <code> renders its count and no floor year, once for each of the other four codes: one exact note: line, and the output contains no floor year.
• CONTRACT.md lists exactly the warning codes the renderer tests cover: set equality between the CONTRACT table and the five tested codes.
• CONTRACT.md marks estimates_unpointed_dropped as the one code a GitHub import cannot raise: the Yes/No column.
• CONTRACT.md's error-code table lists eight import_github_* codes and where each arrives: row count, sorted code column, then the arrival cell of each row. A duplicated row fails it.
• CONTRACT.md's warning counts match its warning table and CONTRACT.md's error-code counts match its error-code table: the prose counts come from the parsed tables.
• contractTable asserts the separator row and the cell count of every row.
• a warning with neither count nor floor_year renders the bare code.
• a 400 <code> refusal names its code on stderr, once for each of the two pre-job codes, with the server's own message. The quota body is 243 characters, so it runs past the client's 200-character cut.
• a failed job prints its error under a doubled import-failed prefix.

Red first:

• The three CONTRACT tests failed against the old CONTRACT.md (CONTRACT.md has no table headed ...).
• The five renderer tests passed on the first run, because the renderer already handles each shape. I proved that they can fail with three temporary mutations of warningLine:
  • Always print floor year: the four count-only tests fail.
  • Drop floor_year: the floor test fails.
  • Drop count: all five fail.
• I also mutated CONTRACT.md: removing a row, flipping No to Yes, and changing an arrival cell each turn the matching test red.
• Review round: each new or changed test failed against a mutation and passed after I restored the file. The mutations were a duplicated row in each table, each prose count, a broken separator, an extra cell, a 20-character body cut in the client, an always-parenthesized note, and a single error: prefix. The previous fromEntries test stayed green against the duplicated error row.

Gates:

• npm test: # tests 1300, # pass 1299, # fail 0, # skipped 1 (the opt-in e2e), rc 0
• npm run lint: Found 1 warning. Found 1 info. (both pre-existing: src/mockserver.js, biome.json), rc 0
• npm run typecheck: rc 0

🤖 Generated with Claude Code