Inspect Azure project field contracts before planning sync
Result
Agents can inspect an explicitly selected Azure project's fields, custom types, states, required/allowed/default values, relation capabilities and mapping incompatibilities before constructing a sync plan. Previously ado validate only checked configuration.
The typed discoverProjectContract SDK and pm ado contract --project Example --type Task --check-tracker use GET only and the host's JSON/TOON rendering. Tracker checks reuse complete-list certification, schema-list status contracts, and existing sync field/state conversions. Typed refusals include remedies and semantic exits. Scope-bound fingerprints are independent of server ordering and process locale. Effective write ACLs and conditional process rules remain explicitly unknown; live Azure acceptance is not claimed.
Type-filtered previews now count enabled other types in skipped_items; checked_items counts assessed items, while unknown/disabled types remain incompatibilities. SDK/internal read failures produce remote_failure/exit 3 rather than a configuration remedy. Discovery owns redirect rejection; shared sync fetch behavior matches main.
Acceptance and review evidence
| Criterion | Evidence |
|---|---|
| Read-only/custom fields, required/allowed/default values | Synthetic REST contracts in test/contracts.test.ts |
| Missing permissions and schema changes | 401/403 typed refusals, fail-closed malformed metadata, fingerprint drift exit 4 |
| No remote or authoritative tracker mutations; no git dependency | Actual CLI and real SDK trackers; git absent from PATH; GET logs and file hashes |
| Typed SDK, compact CLI, documentation | Export tests, actual JSON/TOON parser/renderer tests, README and docs/field-contracts.md |
| Full release gates | Passing review-fix CI: npm and Bun each pass 197/197 V8 plus 197/197 statement tests |
| Thread | Verified fix and regression |
|---|---|
PRRT_kwDOUMUq186vTrJV | Code-unit sorting throughout discovery; identical contracts from actual English/Swedish Node processes |
PRRT_kwDOUMUq186vTrJe | Enabled out-of-scope types skipped, unknown/disabled types diagnosed; real SDK items and actual CLI counting |
PRRT_kwDOUMUq186vTrJk | Typed refusals preserved; only known configuration errors use exit 2; a damaged real tracker returns remote_failure/exit 3 |
PRRT_kwDOUMUq186vTrJu | Private discovery transport rejects redirects; actual HTTP redirects still work through the shared sync client transport |
All four findings were valid; no additional instances were found in the complete PR diff for these defect classes.
Focused linked command: npm run build && npm run build:test && node --test test/contracts.test.ts — 16/16 pass, zero failures/skips/cancellations/todos, trusted source and no context mismatch. New-module targeted V8 lines/branches/functions remain 100%. Local typecheck, test typecheck, docstring lint (68/68), whitespace and changelog checks pass. Full gates run in CI because the development host CPU is saturated; no timeout was counted as success.
Behavioral revert proof: five isolated mutations each compile, then fail their targeted regression 1/1: locale-sensitive canonical sorting; removal of the type-filter skip; restoration of the catch-all configuration refusal; redirect rejection reintroduced in shared sync transport; redirects allowed in discovery. Restore every function and rebuild: all 16 focused scenarios pass. Exact test commands and outcomes are recorded on the pm item.
Full release-gate receipts
Final-head CI, commit 6cd7e4f0fb21845e0583a810bb971ad1590b8210:
| Gate | Measured result |
|---|---|
npm run release:check | 197/197 V8 tests plus 197/197 independent statement tests; zero failures/skips/cancellations/todos |
bun run release:check | 197/197 V8 tests plus 197/197 independent statement tests; zero failures/skips/cancellations/todos |
| Coverage, each runtime | Statements 992/992; V8 lines/branches/functions 100%; all six required sources; unchanged thresholds |
| Other release checks | 68/68 documented declarations; zero production vulnerabilities; package, changelog, publish-attestation and date checks pass |
| Runtime/security checks | Node 22, Node 26 and CodeQL pass |
Public real-data validation
Read-only non-git copy of the public unbraind/pm-ado tracker at main ae51ace8fcac8f560f2e282bc5eb128fba89713c, against synthetic Azure REST metadata through the installed CLI:
- 27 items checked in each format, zero skipped: 6 in progress, 2 open, 18 closed, 1 canceled.
- 72 authoritative files hashed, zero changed; eight GET requests, zero other methods.
- JSON: 3,835 bytes; TOON: 1,527 bytes, including explicit skipped-item accounting.
- One expected incompatibility:
Task/canceledlacks an export-state mapping, reported with a remedy andcompatible=false. - Source tracker untouched. Disposable host read caches may be created in the copy. No live Azure credentials or hosted data used.
Tracking and boundaries
Delivery: pm-ado-field-contracts.
Related reconciliation scope: pm-ado-nc7z.
Overlap checked against core CLI 2026.10.22 and sibling providers: core owns local schema and host command contracts; pm-jira/pm-linear own their provider metadata; Azure process discovery belongs here. The repository SDK pin and coverage thresholds are unchanged. No new PM CLI/SDK defect was established. An optional-schema corruption probe was recoverable in-process; the retained failure regression uses a genuinely invalid complete corpus.
No merge or release is requested. Local strict health previously reported inherited global-extension version skew and clone installation fence drift; clean CI installs provide the release evidence. No unrelated global extension, telemetry or merge-driver changes are included.