hatch3r 1.0.0 → 1.2.0

package/agents/hatch3r-security-auditor.md

@@ -1,6 +1,9 @@
 ---
 id: hatch3r-security-auditor
 description: Security analyst who audits database rules, cloud functions, event metadata, and data flows. Use when reviewing security, auditing privacy invariants, or validating access control.
+protected: true
+model: standard
+tags: [review, security]
 ---
 You are an expert security analyst for the project.
 
@@ -13,13 +16,12 @@ You are an expert security analyst for the project.
 
 ## Critical Invariants to Enforce
 
+Follow the security patterns defined in `.agents/rules/hatch3r-security-patterns.md` (input validation, auth enforcement, fail-closed defaults, CSRF, OWASP Top 10, AI/agentic security). In addition, enforce these project-specific invariants:
+
 - **Data pipeline:** No sensitive content anywhere in the data pipeline
 - **Metadata:** Event metadata validated against allowlist (client AND server)
 - **Sensitive collections:** Deny-all client rules for billing/subscription data
 - **Membership:** Protected data access requires verified membership
-- **API auth:** All API/function endpoints validate auth token
-- **Webhooks:** All payment/webhook endpoints verify signature
-- **Secrets:** No secrets in client-side code, logs, or error messages
 - **Entitlements:** Entitlements written only by backend/cloud functions
 
 ## Key Files
@@ -44,7 +46,23 @@ You are an expert security analyst for the project.
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh` CLI
+- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
+- **GitLab:** `glab` CLI
+
+## Context7 MCP Usage
+
+- Use `resolve-library-id` then `query-docs` to look up current API patterns for security libraries (JWT verification, bcrypt, helmet, CSRF middleware, OAuth libraries).
+- Verify correct usage of auth/crypto APIs in audited code — training data may reflect deprecated or insecure defaults.
+- Look up framework-specific security middleware docs (e.g., Express helmet options, Next.js CSP config, Django security middleware).
+
+## Web Research Usage
+
+- Use web search for latest CVEs and security advisories affecting dependencies found in the project (NVD, GitHub Security Advisories, platform-specific databases).
+- Use web search for current OWASP Top 10, CWE references, and NIST guidelines when classifying findings.
+- Use web search for known exploit techniques and attack patterns relevant to the application's technology stack.
+- Use web search for security hardening best practices when the codebase uses patterns not covered by local docs or Context7.
 
 ## Sub-Agent Delegation
 
@@ -91,7 +109,7 @@ When auditing a large application with multiple modules:
 
 ## Boundaries
 
-- **Always:** Test both allow and deny cases, verify invariants, check for secret leakage, validate input sanitization, use `gh` CLI for issue/code reads
+- **Always:** Test both allow and deny cases, verify invariants, check for secret leakage, validate input sanitization, use the platform CLI for issue/code reads
 - **Ask first:** Before modifying function logic or changing the entitlement model
 - **Never:** Weaken security rules without explicit approval, skip signature verification, expose billing data to clients, commit secrets
 

package/agents/hatch3r-test-writer.md

@@ -1,7 +1,9 @@
 ---
 id: hatch3r-test-writer
 description: QA engineer who writes deterministic, isolated tests. Covers unit, integration, E2E, security rules, and contract tests.
-model: sonnet
+model: standard
+protected: true
+tags: [core, review]
 ---
 You are an expert QA engineer for the project.
 
@@ -25,13 +27,7 @@ You are an expert QA engineer for the project.
 
 ## Test Standards
 
-- **Deterministic:** Use fake timers where applicable — no wall clock dependency
-- **Isolated:** Each test creates and tears down its own state
-- **Fast:** Unit < 50ms, integration < 2s
-- **Named clearly:** Descriptive test names that explain expected behavior
-- **Regression:** Every bug fix gets a test that fails before the fix and passes after
-- **No network:** Unit tests never make network calls (use mocks)
-- **No `any`:** Use proper types in tests. No `.skip` without a linked issue.
+Follow the full testing standards defined in `.agents/rules/hatch3r-testing.md` (coverage thresholds, mocking strategy, property-based testing, flaky test handling, test data management). Key principles enforced by this agent: deterministic (fake timers), isolated (own state), fast (unit < 50ms, integration < 2s), clearly named, regression tests for every bug fix, no network calls in unit tests, no `any` or `.skip` without a linked issue.
 
 ## Commands
 
@@ -56,7 +52,22 @@ This interactive verification complements automated E2E test suites — use it t
 
 ## External Knowledge
 
-Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Prefer `gh` CLI over GitHub MCP tools.
+Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). Use the project's configured platform CLI (check `platform` in `.agents/hatch.json`):
+- **GitHub:** `gh` CLI
+- **Azure DevOps:** `az devops` / `az boards` / `az repos` CLI
+- **GitLab:** `glab` CLI
+
+## Context7 MCP Usage
+
+- Use `resolve-library-id` then `query-docs` to look up current APIs for testing frameworks (Vitest, Jest, Playwright, Cypress, Testing Library) before writing tests.
+- Look up assertion library APIs, mocking utilities, and test runner configuration to use correct patterns rather than relying on potentially outdated training data.
+- When testing code that uses external libraries, query Context7 for the library's recommended testing patterns (e.g., React Testing Library queries, Playwright locators, Supertest assertion chains).
+
+## Web Research Usage
+
+- Use web search for testing best practices for specific scenarios (e.g., testing race conditions, WebSocket handlers, file uploads, streaming responses).
+- Use web search for known testing pitfalls and flaky test patterns in the project's testing framework.
+- Use web search for security testing techniques (e.g., injection test patterns, auth bypass test cases) when writing security-related tests.
 
 ## Output Format
 
@@ -96,7 +107,7 @@ Follow the tooling hierarchy (specs > codebase > Context7 MCP > web research). P
 
 ## Boundaries
 
-- **Always:** Write tests to `tests/`, run tests before submitting, verify edge cases, check invariants from specs, use `gh` CLI for issue reads
+- **Always:** Write tests to `tests/`, run tests before submitting, verify edge cases, check invariants from specs, use the platform CLI for issue reads
 - **Ask first:** Before modifying existing test infrastructure or adding test dependencies
 - **Never:** Modify source code in `src/`, remove failing tests to make the suite pass, skip tests without a linked issue
 

package/checks/README.md

@@ -0,0 +1,49 @@
+# Checks
+
+Review criteria definitions for automated and agent-assisted code review. Each check file defines a set of criteria that agents reference when reviewing code changes.
+
+## How Checks Work
+
+- Agents load check files during code review to evaluate changes against defined criteria.
+- Each check file focuses on one concern (code quality, security, testing, etc.).
+- Criteria are pass/fail — a change either meets the criterion or doesn't.
+- Agents report findings per-criterion, noting which passed and which need attention.
+
+## File Format
+
+Each check file uses frontmatter with:
+
+```yaml
+---
+id: check-name
+type: check
+description: What this check evaluates
+---
+```
+
+The body contains sections of review criteria organized by category.
+
+## Usage
+
+Agents (particularly `hatch3r-reviewer`) reference checks during code review:
+
+1. Load the relevant check files based on the type of change.
+2. Evaluate each criterion against the diff.
+3. Report pass/fail per criterion with specific findings.
+4. Block merging if any critical criterion fails.
+
+## Available Checks
+
+| Check | Focus Area |
+|-------|------------|
+| `code-quality` | Code standards, complexity, maintainability |
+| `security` | Vulnerability patterns, input validation, secrets |
+| `testing` | Test coverage, test quality, regression tests |
+| `performance` | Bundle size, render performance, memory usage, network optimization, database queries |
+
+## Adding New Checks
+
+1. Create a new `.md` file in this directory with the frontmatter format above.
+2. Define criteria grouped by category — each criterion should be specific and actionable.
+3. Mark criteria as `[CRITICAL]` if failure should block the PR, or `[RECOMMENDED]` for advisory.
+4. Update this README with the new check in the Available Checks table.

package/checks/code-quality.md

@@ -0,0 +1,49 @@
+---
+id: code-quality
+type: check
+description: Code quality review criteria covering standards compliance, complexity, maintainability, and architectural patterns
+---
+# Code Quality Check
+
+Review criteria for evaluating code quality in pull requests.
+
+## Standards Compliance
+
+- `[CRITICAL]` No type escape hatches (`any`, `@ts-ignore`, `// @ts-expect-error`) without a linked issue justification.
+- `[CRITICAL]` All new functions and variables follow the project naming conventions (camelCase functions, PascalCase types, SCREAMING_SNAKE constants).
+- `[CRITICAL]` No linter warnings introduced. The diff must not increase the warning count.
+- `[RECOMMENDED]` Import ordering follows the canonical order: built-in, external, internal aliases, relative, type-only.
+
+## Complexity
+
+- `[CRITICAL]` No function exceeds 50 lines. If it does, it must be decomposed.
+- `[CRITICAL]` Cyclomatic complexity does not exceed 10 per function.
+- `[RECOMMENDED]` No file exceeds 400 lines. Large files should be split by responsibility.
+- `[RECOMMENDED]` Nesting depth does not exceed 3 levels. Use early returns or extract helpers.
+
+## Maintainability
+
+- `[CRITICAL]` No dead code: unused imports, variables, functions, or commented-out code blocks.
+- `[CRITICAL]` No placeholder code (`// TODO`, `// FIXME`, `// HACK`) without a linked tracking issue.
+- `[RECOMMENDED]` Complex logic has inline comments explaining the *why*, not the *what*.
+- `[RECOMMENDED]` Public API functions have JSDoc/docstring with parameter and return descriptions.
+
+## Error Handling
+
+- `[CRITICAL]` No swallowed errors (empty `catch` blocks or `catch` that only logs without re-throwing or returning an error result).
+- `[CRITICAL]` Error messages are descriptive and include context (what failed, with what input, suggested action).
+- `[RECOMMENDED]` Domain errors use custom error classes, not raw `Error("message")`.
+- `[RECOMMENDED]` External call failures (HTTP, DB, file I/O) have retry or graceful degradation logic.
+
+## Architecture
+
+- `[CRITICAL]` No circular imports between modules. Check with dependency graph tools.
+- `[CRITICAL]` New dependencies are justified — include a comment or PR description explaining why the existing stack doesn't suffice.
+- `[RECOMMENDED]` Cross-module imports go through barrel exports (`index.ts`), not internal file paths.
+- `[RECOMMENDED]` Side effects are isolated at the edges (API handlers, CLI entry points), not embedded in domain logic.
+
+## Performance
+
+- `[RECOMMENDED]` No N+1 query patterns in data fetching code.
+- `[RECOMMENDED]` Large collections use pagination or streaming, not full in-memory loading.
+- `[RECOMMENDED]` Expensive operations (crypto, compression, network) are not performed synchronously in request handlers.

package/checks/performance.md

@@ -0,0 +1,58 @@
+---
+id: performance
+type: check
+description: Performance review criteria covering bundle size, render performance, memory usage, network optimization, database queries, and runtime efficiency
+---
+# Performance Check
+
+Review criteria for evaluating performance in pull requests.
+
+## Bundle Size and Asset Optimization
+
+- `[CRITICAL]` New dependencies do not increase the total bundle size (gzipped) beyond the defined budget. Measure before and after.
+- `[CRITICAL]` No unintentional import of full libraries when a subpath import or tree-shakable alternative exists (e.g., `import _ from "lodash"` vs `import groupBy from "lodash/groupBy"`).
+- `[RECOMMENDED]` Images and static assets are optimized (compressed, appropriately sized, modern formats like WebP/AVIF).
+- `[RECOMMENDED]` CSS and JavaScript are minified and dead-code-eliminated in production builds.
+
+## Render and Paint Performance
+
+- `[CRITICAL]` Changes to critical rendering path do not regress Largest Contentful Paint (LCP) beyond the defined budget.
+- `[CRITICAL]` Layout shifts are not introduced — Cumulative Layout Shift (CLS) must remain below the defined threshold.
+- `[RECOMMENDED]` First Contentful Paint (FCP) is not regressed. Above-the-fold content renders without blocking on non-critical resources.
+- `[RECOMMENDED]` Animations and transitions use `transform`/`opacity` (compositor-only properties) rather than properties that trigger layout or paint.
+
+## Memory Usage and Leak Detection
+
+- `[CRITICAL]` Event listeners, subscriptions, timers, and observers are cleaned up on component unmount or scope exit.
+- `[CRITICAL]` No unbounded data structures (arrays, maps, caches) that grow without eviction or size limits.
+- `[RECOMMENDED]` Large objects and buffers are released when no longer needed — avoid holding references beyond their useful lifetime.
+- `[RECOMMENDED]` Closures in hot paths do not capture unnecessary outer scope variables that prevent garbage collection.
+
+## Network Request Optimization
+
+- `[CRITICAL]` No N+1 request patterns — batch or aggregate related requests instead of issuing one per item.
+- `[CRITICAL]` API response payloads return only required fields. No over-fetching of large objects when a subset is needed.
+- `[RECOMMENDED]` Cacheable responses include appropriate cache headers (`Cache-Control`, `ETag`). Client-side caching (query cache, service worker) is used where applicable.
+- `[RECOMMENDED]` Request waterfalls are minimized — parallelize independent requests and preload critical resources.
+
+## Database Query Performance
+
+- `[CRITICAL]` New queries that filter or sort on a column have a supporting index. Queries against large tables must not perform full table scans.
+- `[CRITICAL]` No N+1 query patterns in data access layers — use joins, batch loading, or dataloader patterns.
+- `[RECOMMENDED]` Queries select only required columns, not `SELECT *`.
+- `[RECOMMENDED]` Connection pooling is used for database access. No per-request connection creation in request handlers.
+- `[RECOMMENDED]` Long-running queries and transactions are identified and bounded with timeouts.
+
+## Runtime Performance
+
+- `[CRITICAL]` No synchronous blocking operations (heavy computation, synchronous I/O) on the main thread or event loop.
+- `[CRITICAL]` Hot-path code (called per-request, per-frame, or per-event) does not perform redundant computation — memoize or cache where appropriate.
+- `[RECOMMENDED]` CPU-intensive work is offloaded to workers, background jobs, or streaming pipelines.
+- `[RECOMMENDED]` Object allocation in tight loops is minimized — reuse buffers and avoid creating short-lived objects per iteration.
+
+## Lazy Loading and Code Splitting
+
+- `[CRITICAL]` Routes and large feature modules use dynamic imports or lazy loading — not bundled into the initial payload.
+- `[RECOMMENDED]` Below-the-fold content, modals, and infrequently accessed features are lazy-loaded on demand.
+- `[RECOMMENDED]` Third-party scripts (analytics, chat widgets, ads) are loaded asynchronously and deferred.
+- `[RECOMMENDED]` Code splitting boundaries align with route or feature boundaries, not arbitrary file splits.

package/checks/security.md

@@ -0,0 +1,58 @@
+---
+id: security
+type: check
+description: Security review criteria covering vulnerability patterns, input validation, authentication, secrets handling, and dependency safety
+---
+# Security Check
+
+Review criteria for evaluating security posture in pull requests.
+
+## Input Validation
+
+- `[CRITICAL]` All external input (HTTP params, form data, file uploads, CLI args) is validated and sanitized before use.
+- `[CRITICAL]` SQL queries use parameterized statements or an ORM — no string concatenation of user input into queries.
+- `[CRITICAL]` HTML output is escaped to prevent XSS. No use of `dangerouslySetInnerHTML`, `v-html`, or equivalent without sanitization.
+- `[CRITICAL]` File paths constructed from user input are validated against directory traversal (`../`).
+- `[RECOMMENDED]` Input validation uses schema validation (Zod, Joi, JSON Schema) rather than manual checks.
+
+## Authentication and Authorization
+
+- `[CRITICAL]` New endpoints have appropriate authentication guards. No accidental public exposure of protected resources.
+- `[CRITICAL]` Authorization checks verify the authenticated user has access to the specific resource, not just that they're logged in.
+- `[CRITICAL]` Authentication tokens are not logged, included in URLs, or exposed in error messages.
+- `[RECOMMENDED]` Session tokens use secure attributes: `HttpOnly`, `Secure`, `SameSite=Strict`, appropriate `Max-Age`.
+- `[RECOMMENDED]` Rate limiting is applied to authentication endpoints (login, password reset, OTP verification).
+
+## Secrets and Credentials
+
+- `[CRITICAL]` No hardcoded secrets, API keys, passwords, or tokens in source code.
+- `[CRITICAL]` No secrets in committed configuration files, test fixtures, or comments.
+- `[CRITICAL]` `.env` files are gitignored. Only `.env.example` (with placeholder values) is committed.
+- `[RECOMMENDED]` Secrets are loaded from environment variables or a secrets manager, not from config files.
+- `[RECOMMENDED]` New secrets are documented in `.env.example` with a description of their purpose.
+
+## Dependency Safety
+
+- `[CRITICAL]` New dependencies are from trusted sources with active maintenance (recent commits, multiple maintainers).
+- `[CRITICAL]` No known critical or high vulnerabilities in new or updated dependencies (`npm audit`, `pip audit`, etc.).
+- `[RECOMMENDED]` Dependency count increase is justified — prefer standard library solutions when adequate.
+- `[RECOMMENDED]` New dependencies have appropriate licenses compatible with the project.
+
+## Data Exposure
+
+- `[CRITICAL]` API responses do not leak internal implementation details (stack traces, database errors, internal paths).
+- `[CRITICAL]` PII fields are not included in logs, error messages, or analytics events.
+- `[CRITICAL]` Sensitive data in database queries is not selected unnecessarily (select only needed columns).
+- `[RECOMMENDED]` API responses use DTOs or serializers that explicitly whitelist fields, rather than returning raw database objects.
+
+## Cryptography
+
+- `[CRITICAL]` No use of deprecated or weak algorithms (MD5 for security, SHA1 for signatures, DES, RC4).
+- `[CRITICAL]` Random values for security purposes (tokens, nonces) use cryptographically secure generators (`crypto.randomBytes`, `secrets.token_hex`).
+- `[RECOMMENDED]` Passwords are hashed with bcrypt, scrypt, or Argon2 — not SHA-256 or PBKDF2 with low iterations.
+- `[RECOMMENDED]` TLS certificate validation is not disabled, even in test environments.
+
+## Error Handling
+
+- `[CRITICAL]` Error responses to clients do not include stack traces, internal paths, or database details.
+- `[RECOMMENDED]` Security-relevant errors (auth failures, permission denials) are logged with sufficient context for incident investigation.

package/checks/testing.md

@@ -0,0 +1,53 @@
+---
+id: testing
+type: check
+description: Test coverage review criteria covering test quality, regression testing, test isolation, and coverage requirements
+---
+# Testing Check
+
+Review criteria for evaluating test coverage and quality in pull requests.
+
+## Coverage Requirements
+
+- `[CRITICAL]` Every new public function or method has at least one unit test.
+- `[CRITICAL]` Code coverage does not decrease from the base branch. New code must be tested.
+- `[CRITICAL]` Bug fix PRs include a regression test that fails without the fix and passes with it.
+- `[RECOMMENDED]` Critical path functions (auth, payments, data mutations) have > 90% branch coverage.
+- `[RECOMMENDED]` Edge cases are explicitly tested: empty inputs, boundary values, error conditions, null/undefined.
+
+## Test Quality
+
+- `[CRITICAL]` Tests are deterministic — no flaky tests. Tests must not depend on timing, network, or external services.
+- `[CRITICAL]` Each test has a single clear assertion focus. Test names describe the expected behavior, not the implementation.
+- `[CRITICAL]` Tests do not depend on execution order. Each test sets up and tears down its own state.
+- `[RECOMMENDED]` Test names follow "should [expected behavior] when [condition]" or equivalent descriptive pattern.
+- `[RECOMMENDED]` No logic duplication between test and implementation — tests should verify behavior, not re-implement it.
+
+## Test Isolation
+
+- `[CRITICAL]` Unit tests do not make real network calls, database queries, or file system writes.
+- `[CRITICAL]` External dependencies are mocked, stubbed, or faked at module boundaries.
+- `[CRITICAL]` Tests clean up after themselves — no leaked state, open handles, or modified globals.
+- `[RECOMMENDED]` Test fixtures and factories are used for complex test data setup, not inline object literals.
+- `[RECOMMENDED]` Shared test helpers live in a dedicated test utilities directory, not duplicated across test files.
+
+## Integration Tests
+
+- `[CRITICAL]` API endpoints have integration tests covering the happy path and primary error paths.
+- `[CRITICAL]` Database operations are tested against a real (test) database, not mocks, for integration-level tests.
+- `[RECOMMENDED]` Integration tests verify the complete request-response cycle including middleware (auth, validation, error handling).
+- `[RECOMMENDED]` Integration tests use transactional rollback or isolated test databases to avoid cross-test contamination.
+
+## Test Organization
+
+- `[RECOMMENDED]` Test files are co-located with source files (`foo.ts` → `foo.test.ts`) or in a mirrored `__tests__/` directory.
+- `[RECOMMENDED]` Test suites are grouped by feature or module, not by test type.
+- `[RECOMMENDED]` Slow tests (integration, e2e) are tagged or separated so unit tests can run independently and fast.
+- `[RECOMMENDED]` Test utility functions (factories, builders, custom matchers) are documented with usage examples.
+
+## Regression Prevention
+
+- `[CRITICAL]` Deleted tests must be justified — removing a test without replacing it requires explanation in the PR description.
+- `[CRITICAL]` Modified tests still test the original intended behavior, not just the new implementation.
+- `[RECOMMENDED]` Snapshot tests are reviewed for meaningful changes — auto-updated snapshots must be inspected.
+- `[RECOMMENDED]` Performance-sensitive code has benchmark tests or assertions to catch regressions.

package/commands/board/pickup-azure-devops.md

@@ -0,0 +1,81 @@
+---
+id: hatch3r-board-pickup-azure-devops
+type: command
+description: Azure DevOps-specific platform procedures for board-pickup. Covers az CLI commands for work item listing, status updates, collision detection, PR creation, and state transitions.
+tags: [board, team, azure-devops]
+---
+# Board Pickup — Azure DevOps Platform Details
+
+Platform-specific procedures for Azure DevOps. Referenced from `hatch3r-board-pickup`.
+
+---
+
+## Step 1a: Fetch and Parse Board State — Azure DevOps
+
+**Fetch all open work items:**
+1. `az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT [System.Id], [System.Title], [System.State], [System.Tags] FROM WorkItems WHERE [System.State] <> 'Closed' AND [System.State] <> 'Removed'"` (fall back to `list_work_items` MCP).
+
+**Check sub-issues per work item:**
+- `az boards work-item relation list --id N`.
+
+**Fetch tags:**
+- Extract from `System.Tags` field.
+
+---
+
+## Step 3: Collision Detection — Azure DevOps
+
+**In-progress work items:**
+- `az boards query --wiql "SELECT ... WHERE [System.State] = 'Active' AND [System.Tags] CONTAINS 'status:in-progress'"`.
+
+**Open PRs:**
+- `az repos pr list --org https://dev.azure.com/{namespace} --project {project} --status active`.
+
+---
+
+## Step 4: Update Issue Status — Azure DevOps
+
+**Update work item state and tags:**
+- `az boards work-item update --id N --state "Active"` and update tags to include `status:in-progress`.
+
+**Sync board status:**
+Follow the **Azure Boards Work Item State Sync** from `commands/board/shared-azure-devops.md` for each work item marked `status:in-progress` (including parent epic). Set state to "Active".
+
+---
+
+## Step 8: Create Pull Request — Azure DevOps
+
+**PR template:** Check `.azuredevops/pull_request_template.md`.
+
+**Create PR:**
+`az repos pr create --org https://dev.azure.com/{namespace} --project {project} --source-branch {branch} --target-branch {base} --title "..." --description "..."` (fall back to `create_pull_request` MCP).
+
+`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+
+**Link PR to epic:**
+`az boards work-item relation add --id {epic_id} --relation-type "ArtifactLink" --target-id {pr_id}` or link via PR description.
+
+**Verify PR body linkage:**
+Read back the created PR description and verify it contains `Closes #N` for every work item addressed. If any reference is missing:
+`az repos pr update --id {pr_number} --description "..."`.
+
+---
+
+## Step 8a: Post-PR Label Transition — Azure DevOps
+
+**Transition to `status:in-review`:**
+`az boards work-item update --id N --state "Resolved"` and update tags to include `status:in-review`.
+
+**Sync Board:**
+Follow the full **Azure Boards Work Item State Sync** from `commands/board/shared-azure-devops.md` for:
+- Each `Closes #N` work item: Set state to "Resolved".
+- Parent epic (all sub-issues addressed): Set state to "Resolved".
+- Parent epic (partial): Verify state is "Active"; set it if not.
+
+---
+
+## Error Handling — Azure DevOps
+
+- **Work item listing failure** (`az boards query`): retry once, then ask user for work item ID.
+- **Work item update failure** (`az boards work-item update`): warn and continue (tags not blocking).
+- **PR creation failure** (`az repos pr create`): present error and manual instructions.