agentic-devtools 0.2.284__tar.gz → 0.2.285__tar.gz

{agentic_devtools-0.2.284 → agentic_devtools-0.2.285}/.github/copilot-instructions.md

@@ -1484,6 +1484,59 @@ recognised as a loadable Python source. Without the guard, the very first call
 problem. The explicit `RuntimeError` surfaces the actual path that failed, making failures
 trivially easy to diagnose.
 
+### Retry / backoff logic
+
+Retry helpers (e.g. `agentic_devtools/adapters/retry.py`, `agentic_devtools/cli/shared/retry.py`)
+have repeatedly shipped with the same set of pitfalls. When writing or modifying retry/backoff
+logic:
+
+- **Match transient-error conditions narrowly.** Don't classify an exception as transient by
+  doing a substring search for a status code (e.g. `"429" in str(exc)`) — this also matches
+  unrelated exceptions such as `ValueError("1429 rows")`. Check the actual status code /
+  exception type instead.
+- **Preserve the original traceback when re-raising after retries are exhausted.** Inside the
+  handler that caught the exception, use a bare `raise` to preserve the original traceback. If you
+  must re-raise outside that handler, capture the traceback and raise with
+  `exc.with_traceback(tb)` rather than `raise exc`/`raise last_exc`, which starts a new traceback.
+- **Retry only the failing step, not the whole operation.** If a multi-page or multi-step
+  operation (e.g. paginated search) is wrapped in a single retry decorator, a transient failure
+  on a later page restarts the entire operation from the beginning and discards progress/API
+  quota already spent. Scope the retry decorator to the smallest failing unit of work.
+- **Validate retry/backoff configuration parameters** (e.g. `jitter_factor`, base delay) at the
+  point they're accepted, not just in the docstring. An unvalidated negative `jitter_factor` can
+  produce a negative sleep duration passed to `random.uniform(...)`/`time.sleep(...)`.
+- **Name the exception raised when retries are exhausted after the actual failure**, not a
+  single catch-all like `ProviderRateLimitError` for every retryable exception type — a
+  misleading name makes the real cause harder to diagnose from logs/error reports.
+
+*Rationale: based on audit findings in PRs #2777 and #2801.*
+
+### Keep docstrings and comments synchronized with implementation
+
+Several PRs contained docstrings/comments describing behavior that no longer matched the code
+(e.g., a "diff direction" described backwards, a module docstring claiming a function builds a
+"hierarchical" structure when it just returns the input lists unchanged, a docstring pointing to
+the wrong function as the one wrapped by a decorator). When changing behavior, update the
+docstring/comment in the same change; when reviewing, treat a stale docstring as a defect, not
+a nit.
+
+Test docstrings must describe the actual behavior under test in plain language — do not use
+placeholder text (e.g., `"******"`) in place of the real assertion being made (such as which
+auth scheme takes precedence). Placeholder docstrings make test failures harder to interpret and
+provide no value over no docstring at all.
+
+*Rationale: based on audit findings in PRs #2777 and #2801 (8+ occurrences).*
+
+### Remove or wire up dead code
+
+Don't leave unused constants, unused compiled regexes, or no-op expressions (e.g., a stray
+triple-quoted string directly under a constant definition that is never assigned to a docstring
+attribute and never read) in the codebase. These artifacts read as if they are load-bearing
+(validation source-of-truth, documentation, etc.) but are not, which misleads future readers and
+maintainers. Either delete the dead artifact or wire it up to the behavior it appears to describe.
+
+*Rationale: based on audit findings in PRs #2777, #2801, and #2771.*
+
 ## 13. Testing
 
 **⚠️ AI AGENTS: ALWAYS use agdt-test commands, NEVER pytest directly!**

{agentic_devtools-0.2.284 → agentic_devtools-0.2.285}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.284
+Version: 0.2.285
 Summary: Agentic devtools integrate Jira, DevOps & more
 Author: ayaiayorg
 License-Expression: MIT

{agentic_devtools-0.2.284 → agentic_devtools-0.2.285}/agentic_devtools/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.284'
-__version_tuple__ = version_tuple = (0, 2, 284)
+__version__ = version = '0.2.285'
+__version_tuple__ = version_tuple = (0, 2, 285)
 
 __commit_id__ = commit_id = None

agentic_devtools-0.2.285/agentic_devtools/adapters/copilot-instructions.md

@@ -0,0 +1,235 @@
+# AI Agent Instructions: `agentic_devtools/adapters/`
+
+> Parent Instruction Chain
+>
+> 1. [agentic-devtools package instructions](../../.github/copilot-instructions.md)
+>
+> [`copilot-instructions.md` Precedence Model](../../docs/copilot-instructions-precedence-model.md)
+
+## Scope
+
+These instructions apply to all code under `agentic_devtools/adapters/`, including provider
+implementations (`github_provider.py`, `jira_provider.py`), the factory (`factory.py`),
+retry infrastructure (`retry.py`), and supporting utilities.
+
+## Provider and Factory Quality Requirements
+
+### Fail-Fast Validation at Construction Time
+
+Provider classes and the factory must validate required configuration values at the point of
+construction, not on first use. Silently accepting empty or invalid configuration leads to
+confusing runtime failures far from the source:
+
+```python
+# Wrong — empty owner_repo accepted; methods later fail with /repos//issues
+class GitHubProvider:
+    def __init__(self, owner_repo: str) -> None:
+        self._owner_repo = owner_repo
+
+# Correct — validate at construction, raise immediately
+class GitHubProvider:
+    def __init__(self, owner_repo: str) -> None:
+        if not owner_repo or "/" not in owner_repo:
+            raise ValueError(f"owner_repo must be in 'owner/repo' form, got: {owner_repo!r}")
+        self._owner_repo = owner_repo
+```
+
+The factory (`factory.py`) must raise `ConfigError` before instantiating any provider when
+required fields (e.g., `owner_repo`, `project_key`, `base_url`) are missing or empty. Strip
+whitespace before the emptiness check, but pass the stripped value to the provider:
+
+```python
+project_key = config.get("platform.jira.project_key", "").strip()
+if not project_key:
+    raise ConfigError("platform.jira.project_key is required but missing or empty")
+return JiraProvider(project_key=project_key, ...)
+```
+
+*Rationale: based on audit findings in PRs #2777 (8+ observations covering factory.py,
+github_provider.py, and jira_provider.py).*
+
+### Validate Numeric Parameters (Non-Negative Constraints)
+
+Functions that accept retry counts, delays, or timeout values must validate that those
+values are non-negative before use. Negative values can produce zero-iteration loops that
+then attempt `raise last_exc` when `last_exc is None`, causing a `TypeError` that is harder
+to diagnose than the original configuration error:
+
+```python
+# Wrong — max_retries=-1 causes loop to never execute, then raises TypeError
+def retry_on_transient(max_retries: int = 3, initial_delay: float = 1.0) -> ...:
+    ...
+
+# Correct — validate up front
+def retry_on_transient(max_retries: int = 3, initial_delay: float = 1.0) -> ...:
+    if max_retries < 0:
+        raise ValueError(f"max_retries must be >= 0, got {max_retries}")
+    if initial_delay < 0:
+        raise ValueError(f"initial_delay must be >= 0, got {initial_delay}")
+    ...
+```
+
+*Rationale: based on audit findings in PRs #2777, #2801 (3+ observations).*
+
+## Error Handling Requirements
+
+### Never Swallow `TransientError` with Bare `except Exception: pass`
+
+The adapters use `@retry_on_transient` decorators. A bare `except Exception: pass` inside
+a function decorated with `@retry_on_transient` silently swallows `TransientError` before it
+can propagate to the retry loop, preventing retries on transient failures:
+
+```python
+# Wrong — TransientError raised by _request() is swallowed; retries never fire
+try:
+    result = self._request(...)
+except Exception:
+    pass
+
+# Correct — catch only the specific exception you intend to handle
+try:
+    result = self._request(...)
+except KeyError:
+    result = None
+```
+
+When a broad catch is genuinely needed (e.g., during a best-effort lookup), explicitly
+re-raise `TransientError`:
+
+```python
+from agentic_devtools.adapters.retry import TransientError
+try:
+    result = self._request(...)
+except TransientError:
+    raise  # let the retry decorator handle it
+except Exception:
+    result = None  # swallow only non-transient errors
+```
+
+*Rationale: based on audit findings in PRs #2777, #2801 (5+ observations).*
+
+### Restrict HTTP Error Fallbacks to Expected Error Codes
+
+Fallback logic that catches HTTP errors must be scoped to the specific status codes that
+indicate the expected failure mode (e.g., 400 or 422 for validation errors). Catching
+all HTTP errors (including 401/403) masks authentication/authorization failures and can
+trigger unnecessary extra requests:
+
+```python
+# Wrong — any HTTP error triggers parent-field fallback, masking 401/403
+try:
+    self._update_epic_link(child_id, parent_id)
+except HTTPError:
+    self._set_parent_field(child_id, parent_id)
+
+# Correct — fallback only for expected validation codes
+try:
+    self._update_epic_link(child_id, parent_id)
+except HTTPError as exc:
+    if exc.response.status_code not in (400, 422):
+        raise
+    self._set_parent_field(child_id, parent_id)
+```
+
+*Rationale: based on audit findings in PR #2777 (jira_provider.py link_subissue).*
+
+### Transient Error Detection Must Use Explicit HTTP Code Patterns
+
+Substring matching against raw error messages (e.g., `"429" in stderr`) is fragile: it can
+misclassify unrelated errors whose text happens to contain those digits (e.g., "error code 1429").
+Use an explicit `"HTTP <code>"` pattern or check the numeric status code directly:
+
+```python
+# Wrong — matches "1429", "5029", or any string containing these digits
+TRANSIENT_CODES = ("429", "502", "503")
+if any(code in str(error_message) for code in TRANSIENT_CODES):
+    raise TransientError(...)
+
+# Correct — require the "HTTP <code>" prefix to avoid false positives
+import re
+if re.search(r"\bHTTP (429|502|503)\b", str(error_message)):
+    raise TransientError(...)
+```
+
+When checking `gh` CLI stderr directly, parse the JSON output and inspect the status code
+numerically rather than performing substring matching on the raw string.
+
+*Rationale: based on audit findings in PR #2777 (5+ observations across github_provider.py
+and retry.py).*
+
+### All Network Calls Must Include a Timeout
+
+HTTP requests without an explicit timeout can block indefinitely when a server stalls,
+causing background tasks to hang and preventing graceful shutdown. Always pass a `timeout`
+argument to `requests` calls and `subprocess`/`gh` CLI invocations:
+
+```python
+# Wrong — can block indefinitely
+response = self._session.get(url)
+
+# Correct — bound wait time explicitly
+response = self._session.get(url, timeout=30)
+```
+
+Use the repository's established timeout constants or shared helpers where they exist
+(e.g., `_SDK_TIMEOUT_SECONDS` in `agentic_devtools.cli.jira.sdk`) rather than inventing
+new magic numbers.
+
+*Rationale: based on audit findings in PR #2777 (jira_provider.py _request).*
+
+### Preserve Original Tracebacks When Re-Raising After Retry Exhaustion
+
+Using `raise last_exc` after a retry loop re-raises the exception with a new traceback
+starting at the `raise` statement, losing the original call-site context. Use a bare
+`raise` from within the `except` block, or capture the traceback and re-raise with
+`last_exc.with_traceback(last_tb)` when re-raising outside the handler:
+
+```python
+# Wrong — loses original traceback
+raise last_exc
+
+# Correct — preserves original traceback for debugging
+raise last_exc.with_traceback(last_tb)
+```
+
+*Rationale: based on audit findings in PR #2777 (retry.py).*
+
+## Docstring and Contract Accuracy Requirements
+
+### Docstrings Must Match the Implementation Exactly
+
+Docstrings that describe edge direction, parameter semantics, or module purpose must be
+verified against the implementation before committing. A mismatch between a docstring and
+the code misleads callers and can cause integration bugs that are hard to trace:
+
+- `detect_cycles`: the docstring must use the same edge-direction convention as the code
+  ("source must come before target" / "source is a prerequisite for target") — not the
+  opposite.
+- Module docstrings must not overstate behavior (e.g., claiming a function "builds a
+  hierarchical JSON manifest" when it simply returns the provided lists unchanged).
+- Protocol docstrings (`IssueProvider.create_issue`, etc.) must reflect the actual
+  parameter contract — including whether `orchestration_key` is a separate parameter or
+  must be embedded in `body`.
+
+When the PR description and the docstring disagree with the implementation, update the
+docstring and/or PR description to match the code. Open questions about the intended
+behavior belong in an explicit note, not in contradictory documentation.
+
+*Rationale: based on audit findings in PRs #2777, #2786 (6+ observations).*
+
+### GitHub GraphQL Responses Require Error-Array Checking
+
+GitHub GraphQL endpoints return HTTP 200 even when the operation failed; the actual error
+is reported inside a top-level `"errors"` array in the JSON body. Always check for this
+array and treat its presence as a failure:
+
+```python
+result = json.loads(output)
+if result.get("errors"):
+    raise ProviderError(f"GraphQL mutation failed: {result['errors']}")
+```
+
+Returning `status="linked"` or similar success indicators based solely on the exit code is
+incorrect for GraphQL calls.
+
+*Rationale: based on audit findings in PR #2777 (github_provider.py add_blocked_by).*

agentic_devtools-0.2.285/specs/1779-subtask-implement-schema-discovery/checklists/requirements.md

@@ -0,0 +1,44 @@
+# Specification Quality Checklist: Schema Discovery for GitHubIssuesAdapter
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-07-07
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1779
+
+## Content Quality
+
+- [ ] CHK001 Each user story (Label-Based Type Discovery, Issue Form YAML Extraction, Default Schema Fallback, Form-to-Type Mapping) clearly states the user value — why a developer or pipeline
+  consumer benefits from the capability
+- [ ] CHK002 All four user stories follow "A [role] needs to [goal] so that [benefit]" narrative format with explicit priority assignment (P1–P3)
+- [ ] CHK003 Priority assignments are justified — US1 (P1) cites universal label availability, US2 (P2) cites richness but optional nature, US4 (P3) cites dependency on P1+P2
+- [ ] CHK004 Functional requirements FR-001 through FR-009 focus on observable behavior and avoid unnecessary internal design constraints, while allowing explicitly justified constraints (for example,
+  instance-level caching semantics and synonym normalization)
+
+## Requirement Completeness
+
+- [ ] CHK005 Each acceptance scenario in US1–US4 is independently testable with mock `gh` CLI responses — no real network calls or repository access required
+- [ ] CHK006 Edge cases section covers all failure modes: `gh` CLI unavailable, API rate limits, malformed YAML, empty type name, 404 on ISSUE_TEMPLATE directory, and non-list `body` field
+- [ ] CHK007 All acceptance scenarios use Given/When/Then format with specific input conditions and verifiable output assertions (e.g., US2 scenario 1 specifies exact `allowed_values=["high",
+  "medium", "low"]`)
+- [ ] CHK008 Success criteria SC-001 through SC-006 include numeric thresholds (≥1 entry, ≥4 properties, 100% coverage, <5s execution, ≥90% field extraction, zero violations)
+- [ ] CHK009 Scope boundaries are defined — spec explicitly states GitHub Contents API only (no local filesystem), instance-level caching only (no persistent cache), and no new third-party
+  dependencies (NFR-004)
+- [ ] CHK010 Dependencies on existing infrastructure are documented: `IssueTypeInfo` TypedDict in `adapters/types.py`, `PropertySchema` type, `_exec()` method pattern, PyYAML already in package, and
+  parent epic #1769/#1770
+
+## Feature Readiness
+
+- [ ] CHK011 Every functional requirement (FR-001 through FR-009) has at least one corresponding acceptance scenario or edge case that validates it — specifically FR-006 (ValueError for empty
+  type_name) and FR-007 (RuntimeError on gh failure) are covered in Edge Cases
+- [ ] CHK012 User scenarios cover the full discovery matrix: labels-only repos (US1), forms-only repos (US2), repos with neither (US3), and repos with both sources requiring merge (US4)
+- [ ] CHK013 Success criteria SC-001 and SC-002 define measurable minimum guarantees (≥1 type, ≥4 properties) that can be asserted in automated tests without subjective judgment
+- [ ] CHK014 No implementation details leak into requirements — FR-005's synonym map specifies the WHAT (canonical mappings) and observable behavior (module-level constant) without dictating internal
+  data structures or control flow; NFR-001 specifies the deadline contract without prescribing threading or async patterns
+
+## Notes
+
+- This checklist was generated from the specification content for issue #1779
+- Items marked incomplete require spec updates before proceeding to planning
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

{agentic_devtools-0.2.284 → agentic_devtools-0.2.285}/specs/1779-subtask-implement-schema-discovery/spec.md

@@ -27,6 +27,34 @@ The absence of this capability creates a gap in the provider adapter framework (
 GitHub adapter, lacking equivalent discovery, cannot participate in cross-provider workflows that depend on knowing what fields and types are available. This subtask bridges that gap by implementing
 heuristic-based schema inference from labels and deterministic schema extraction from issue form YAML, with sensible defaults when neither source provides sufficient information.
 
+## Clarifications
+
+### Session 2026-07-07
+
+- Q: How should `get_issue_types()` fetch issue form templates — via the GitHub Contents API (`gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE`) to list and retrieve files, or via a local
+  filesystem read if in a worktree context? → A: Use the GitHub Contents API via `gh api` exclusively. The adapter operates remotely against any repository (not just the current worktree), so it MUST
+  fetch templates via `gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE` to list files, then `gh api` with the `Accept: application/vnd.github.raw` header to fetch individual YAML contents.
+  This keeps the adapter stateless with respect to local filesystem.
+
+- Q: Should schema discovery results be cached within the adapter instance to avoid redundant `gh` CLI calls when `get_issue_types()` and `get_type_properties()` are called multiple times in
+  succession? → A: Yes, implement simple instance-level caching. Cache the label list and parsed form templates on the adapter instance after the first successful fetch. Cache is invalidated only by
+  constructing a new adapter instance. This ensures the 10-second deadline is easily met on subsequent calls and avoids redundant API round-trips within a single session.
+
+- Q: What `PropertySchema.type` string values should be used when mapping GitHub issue form field types — should they mirror GitHub's exact type names (`textarea`, `input`, `dropdown`, `checkboxes`)
+  or be normalized to more generic types (`string`, `enum`, `boolean`)? → A: Use GitHub's exact type names (`textarea`, `input`, `dropdown`, `checkboxes`) as the `PropertySchema.type` values. This
+  preserves maximum fidelity for consumers that understand GitHub forms, while consumers needing generic types can apply their own mapping layer. The default properties (title, body, labels,
+  assignees) use the types `string` and `array` respectively, since they are not form-specific.
+
+- Q: For FR-005's synonym map, what is the complete set of synonym collapses beyond the two examples given (`bug_report` → `bug`, `enhancement` → `feature`)? → A: The initial synonym map MUST include
+  at minimum: `bug_report` → `bug`, `enhancement` → `feature`, `feature_request` → `feature`. Additional synonyms MAY be added during implementation if clearly justified (e.g., `defect` → `bug`), but
+  the map MUST be kept intentionally small and conservative — only well-established GitHub ecosystem conventions qualify. The map is a module-level constant and MUST be documented with a code comment
+  explaining its purpose.
+
+- Q: When `get_issue_types()` merges label-derived and form-derived types after slug normalization, which source takes priority for the `description` field when both sources produce the same canonical
+  slug? → A: The hardcoded description map (keyed by canonical slug) always takes priority for known slugs. For form-derived types whose slugs are NOT in the hardcoded description map, the form
+  template's `description` field (if present and non-empty) is used. If neither source provides a description, a generic default like `"GitHub issue type"` is used. This ensures consistent,
+  high-quality descriptions for well-known types regardless of repository-specific label or form metadata.
+
 ## User Scenarios & Testing
 
 ### User Story 1 - Label-Based Type Discovery (Priority: P1)
@@ -55,26 +83,28 @@ names and descriptions.
 
 ### User Story 2 - Issue Form YAML Extraction (Priority: P2)
 
-A developer needs to discover what structured fields are available for a specific issue type in a repository that uses GitHub issue form templates. When form YAML files (`*.yml` or `*.yaml`) exist under
-`.github/ISSUE_TEMPLATE/`, the adapter should parse them and return `PropertySchema` entries that describe each form field's name, type, whether it is required, and any constrained allowed values (for
-dropdowns).
+A developer needs to discover what structured fields are available for a specific issue type in a repository that uses GitHub issue form templates. When form YAML files (`*.yml` or `*.yaml`) exist
+under `.github/ISSUE_TEMPLATE/`, the adapter should parse them and return `PropertySchema` entries that describe each form field's name, type, whether it is required, and any constrained allowed
+values (for dropdowns).
 
 **Why this priority**: Issue forms provide the richest schema information available in the GitHub ecosystem. However, not all repositories use them, so this is secondary to the universally-available
 label-based discovery.
 
-**Independent Test**: Can be tested by providing mock `gh api` responses (or file contents) representing issue form YAML and verifying that parsed fields produce correct `PropertySchema` entries with
-accurate types, required flags, and dropdown options.
+**Independent Test**: Can be tested by providing mock `gh api` responses representing the Contents API directory listing and individual file YAML contents
+(including the raw YAML payload returned when fetching with `Accept: application/vnd.github.raw`) and verifying that parsed fields produce correct
+`PropertySchema` entries with accurate types, required flags, and dropdown options. Tests MUST NOT read from local disk — all form template content must be
+injected as mocked `gh api` output.
 
 **Acceptance Scenarios**:
 
 1. **Given** a repository with an issue form template containing a dropdown field with options ["high", "medium", "low"], **When** `get_type_properties("bug")` is called for the matching type,
    **Then** the returned `PropertySchema` list includes an entry with `allowed_values=["high", "medium", "low"]` and `type="dropdown"`.
 2. **Given** a repository with an issue form template containing a required
-   textarea field with `id: steps_to_reproduce` (label: "Steps to Reproduce"),
+   textarea field with `id: steps_to_reproduce` (attributes.label: "Steps to Reproduce"),
    **When** `get_type_properties("bug")` is called, **Then** the returned schema
    includes an entry with `name="steps_to_reproduce"`, `type="textarea"`, and
    `required=True`; when `id` is missing, the implementation falls back to a
-   deterministic slug of the label.
+   deterministic slug of `attributes.label`.
 3. **Given** a repository with an issue form YAML that is malformed or unparseable, **When** `get_type_properties()` is called, **Then** the adapter logs a warning and falls back to default properties
    without raising an exception.
 
@@ -124,6 +154,10 @@ types so that `get_issue_types()` returns a unified list that merges both source
 - How does the system handle issue form YAML that uses advanced features (e.g., conditional fields, nested validations) not representable in `PropertySchema`? Unsupported constructs should be silently
   skipped or mapped to a generic "string" type.
 - What happens when `get_type_properties("")` is called with an empty string? The adapter should raise `ValueError` for invalid type names, consistent with the ABC's documented contract.
+- What happens when the GitHub Contents API returns a 404 for `.github/ISSUE_TEMPLATE/` (directory does not exist)? The adapter should treat this as "no form templates available" and proceed with
+  label-only discovery without raising an error.
+- What happens when a form template YAML file has a `body` field that is not a list or is missing entirely? The adapter should treat it as having zero extractable fields and fall back to default
+  properties for that type.
 
 ## Requirements
 
@@ -152,21 +186,32 @@ types so that `get_issue_types()` returns a unified list that merges both source
   when such templates exist in the repository. The scan MUST explicitly exclude
   `.github/ISSUE_TEMPLATE/config.yml` and `.github/ISSUE_TEMPLATE/config.yaml`
   (GitHub's issue template chooser configuration file), which do not define
-  issue forms and MUST NOT be parsed for type or field discovery.
+  issue forms and MUST NOT be parsed for type or field discovery. Templates MUST be fetched via the GitHub Contents API (`gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE`) rather than
+  local filesystem reads, since the adapter operates remotely against any repository. A 404 response from the Contents API MUST be treated as "no form templates available" and MUST NOT raise an error.
 
 - **FR-003**: The `GitHubIssuesAdapter.get_type_properties()` method MUST parse issue form YAML to extract `PropertySchema` entries, mapping each form body element's `type` (textarea, input, dropdown,
-  checkboxes) to the corresponding `PropertySchema.type` value, and populating `required` and `allowed_values` from the form element's `validations` and `options` fields. Body elements with
-  `type: markdown` MUST be silently skipped and MUST NOT produce a `PropertySchema` entry, because `markdown` is non-interactive display content rather than a user-input field.
+  checkboxes) to the corresponding `PropertySchema.type` value using GitHub's exact type names, and populating `required` and `allowed_values` as follows:
+  - **`required`** for `textarea`, `input`, and `dropdown` elements: read from `validations.required` (boolean, default `False` when absent).
+  - **`required`** for `checkboxes` elements: `True` if `validations.required` is `True` **OR** if any entry in `attributes.options` has `required: true`
+    at the option level; `False` otherwise. Both paths MUST be checked and either condition MUST trigger `required=True`.
+  - **`allowed_values`** from `attributes.options`. For `dropdown` elements, `attributes.options` is a list of strings used directly as `allowed_values`.
+    For `checkboxes` elements, `attributes.options` is a list of objects (e.g. `{label: "Accept terms", required: true}`), so `allowed_values` MUST be
+    derived from each option object's `label` string — not the object itself — to satisfy `PropertySchema.allowed_values: list[str] | None`. Body elements with
+  `type: markdown` MUST be silently skipped and MUST NOT produce a `PropertySchema` entry, because `markdown` is non-interactive display content rather than a user-input field. The
+  `PropertySchema.name` MUST be derived from the form element's `id` field when present; when `id` is absent, it MUST fall back to a deterministic slug of
+  the element's `attributes.label` (using Phase 1 slugification from FR-005).
 
 - **FR-004**: The `GitHubIssuesAdapter.get_type_properties()` method MUST return a default set of properties (title, body, labels, assignees) when no matching issue form template is found for the
-  requested type name.
+  requested type name. Default property types MUST be: `title` (type=`string`, required=`True`), `body` (type=`string`, required=`False`), `labels` (type=`array`, required=`False`), `assignees`
+  (type=`array`, required=`False`).
 
 - **FR-005**: The `GitHubIssuesAdapter.get_issue_types()` method MUST de-duplicate types by normalizing both label names and form template `name` fields to a canonical slug via a deterministic
   two-phase process before comparison:
   - **Phase 1 — Slugification**: lowercase the full text, replace whitespace and hyphens with underscores, strip any remaining non-alphanumeric characters except underscores (e.g., "Bug Report" →
     `"bug_report"`; "feature-request" → `"feature_request"`; "Bug" → `"bug"`).
-  - **Phase 2 — Synonym collapse**: apply a hardcoded synonym map to collapse well-known variant slugs to a single canonical form (e.g., `"bug_report"` → `"bug"`, `"enhancement"` → `"feature"`). Only
-    entries in this map are collapsed; all other slugs produced by Phase 1 are kept as-is.
+  - **Phase 2 — Synonym collapse**: apply a hardcoded synonym map to collapse well-known variant slugs to a single canonical form. The initial synonym map MUST include at minimum: `"bug_report"` →
+    `"bug"`, `"enhancement"` → `"feature"`, `"feature_request"` → `"feature"`. Additional synonyms MAY be added if clearly justified by well-established GitHub ecosystem conventions (e.g., `"defect"`
+    → `"bug"`), but the map MUST be kept intentionally small and conservative. The synonym map MUST be a module-level constant with a code comment explaining its purpose.
 
   Only types whose slugs match after both phases are merged into a single `IssueTypeInfo` entry. The resulting canonical slug is stored as `IssueTypeInfo.name`. The normalization MUST be applied
   consistently across both label-derived and form-derived type names.
@@ -174,9 +219,16 @@ types so that `get_issue_types()` returns a unified list that merges both source
 - **FR-006**: The `GitHubIssuesAdapter.get_type_properties()` method MUST raise `ValueError` when called with an empty or whitespace-only `type_name` argument.
 
 - **FR-007**: Both methods MUST handle `gh` CLI failures gracefully, raising `RuntimeError` with a descriptive message consistent with the existing `_exec()` error pattern, and MUST NOT leave the
-  adapter in an inconsistent state after a failure.
+  adapter in an inconsistent state after a failure. Instance-level caches MUST NOT be populated with partial results from failed fetches.
+
+- **FR-008**: Issue form YAML parsing MUST tolerate malformed or invalid YAML content without propagating parse errors to callers. Behavior is method-specific:
+  - In `get_issue_types()`: malformed individual issue form templates MUST be silently skipped; discovery continues using remaining templates and label-derived type names for skipped entries.
+    A malformed template does NOT prevent other valid types from being discovered.
+  - In `get_type_properties()`: a malformed or unparseable template MUST cause the method to fall back to the default properties set (as if no form template existed), rather than raising an error.
+  - In both methods: a form template with a missing or non-list `body` field MUST be treated as having zero extractable fields (equivalent to an empty field list).
 
-- **FR-008**: Issue form YAML parsing MUST tolerate malformed or invalid YAML content by falling back to default properties rather than propagating parse errors to callers.
+- **FR-009**: Both `get_issue_types()` and `get_type_properties()` MUST implement instance-level caching of fetched label lists and parsed form templates. The cache is populated on first successful
+  fetch and reused on subsequent calls within the same adapter instance. Cache invalidation occurs only by constructing a new adapter instance. Partial or failed fetches MUST NOT populate the cache.
 
 ### Non-Functional Requirements
 
@@ -195,7 +247,7 @@ types so that `get_issue_types()` returns a unified list that merges both source
   are needed (e.g. label listing + template listing + template fetch). If
   `remaining <= 0` before a planned CLI invocation, the method MUST raise a
   descriptive `RuntimeError` before calling `_exec()` rather than passing a
-  non-positive timeout through to `subprocess.run(...)`.
+  non-positive timeout through to `subprocess.run(...)`. When results are served from the instance cache (FR-009), no `gh` CLI calls are made and the deadline does not apply.
 
 - **NFR-002**: All new code MUST achieve 100% per-file branch coverage with unit tests following the 1:1:1 test structure under `tests/unit/adapters/github_adapter/`.
 
@@ -213,7 +265,8 @@ types so that `get_issue_types()` returns a unified list that merges both source
   by FR-005's two-phase normalization (e.g. `"bug"`, `"feature_request"`): it
   is the identifier callers MUST pass to `get_type_properties()`, and it is
   used for sorting and deduplication. `IssueTypeInfo.description` carries the
-  human-readable explanation of the type and is for display only.
+  human-readable explanation of the type and is for display only. For well-known canonical slugs, the description comes from the hardcoded description map. For form-derived types not in the hardcoded
+  map, the form template's `description` field is used if present and non-empty; otherwise a generic default (`"GitHub issue type"`) is used.
 
   **Known semantic divergence from shared contract**: `agentic_devtools/adapters/types.py`
   and the sibling #1777 spec document `IssueTypeInfo.name` as a human-readable
@@ -226,8 +279,9 @@ types so that `get_issue_types()` returns a unified list that merges both source
   `get_type_properties()` ABC docstring MUST explicitly state that `type_name`
   values are expected to come from `IssueTypeInfo.name` entries returned by
   `get_issue_types()`.
-- **PropertySchema**: Represents a single field within an issue type's schema, including its `name`, `type`, `required` flag, and optional `allowed_values` constraint. For GitHub, these are extracted
-  from issue form YAML body elements or synthesized as defaults.
+- **PropertySchema**: Represents a single field within an issue type's schema, including its `name`, `type`, `required` flag, and optional `allowed_values` constraint. For GitHub form-derived fields,
+  `type` uses GitHub's exact form element type names (`textarea`, `input`, `dropdown`, `checkboxes`). For default properties (title, body, labels, assignees), `type` uses generic values (`string`,
+  `array`).
 
 ## Success Criteria
 

agentic_devtools-0.2.285/specs/1780-subtask-implement-schema-discovery/checklists/requirements.md

@@ -0,0 +1,41 @@
+# Specification Quality Checklist: Schema Discovery for MarkdownAdapter
+
+**Purpose**: Validate specification completeness before proceeding to planning
+**Created**: 2026-07-07
+**Feature**: [spec.md](../spec.md)
+**Source Issue**: #1780
+
+## Content Quality
+
+- [ ] CHK001 Each of the 3 user stories clearly articulates value to a specific consumer (orchestration component or team lead), not just technical behavior
+- [ ] CHK002 User Stories 1–3 follow "As a [role], I need to [action] so that [benefit]" format; Stories 1–2 share the "orchestration component" role
+  (type-list and property-list discovery), Story 3 uses the distinct "team lead" role for the configuration override scenario
+- [ ] CHK003 Priority assignments (P1 for Stories 1 & 2, P2 for Story 3) are justified with explicit "Why this priority" rationale explaining dependency ordering
+- [ ] CHK004 FR-001 through FR-007 describe observable behavior and interface-level constraints without prescribing internal data structures, algorithms, or class hierarchies; construction-time
+  validation and per-call config-loading constraints are allowed when externally observable
+
+## Requirement Completeness
+
+- [ ] CHK005 All 8 acceptance scenarios across Stories 1–3 use Given/When/Then format with concrete assertions (exact counts, specific names, specific exception types)
+- [ ] CHK006 Edge cases section addresses all 5 boundary conditions: case-insensitive matching, missing config file, zero-property types, invalid JSON, and duplicate type names after normalization
+- [ ] CHK007 Acceptance scenarios specify exact return shapes (e.g., Story 2 Scenario 1 lists all 7 property names with their `required` and `type` values)
+- [ ] CHK008 Success criteria SC-001 through SC-007 each include a numeric threshold or exact assertion (e.g., "exactly 4 entries", "100% pass rate", "0 uncovered branches")
+- [ ] CHK009 Scope boundaries are established by referencing parent issue #1770 (Provider Adapter Framework) and sibling #1777 (schema-discovery ABC contract), clarifying this is the
+  Markdown-specific implementation portion only
+- [ ] CHK010 Dependencies on `IssueTypeInfo` and `PropertySchema` TypedDicts from `agentic_devtools/adapters/types.py` and the ABC contract from #1777 are explicitly stated in the Problem Statement
+
+## Feature Readiness
+
+- [ ] CHK011 All 7 functional requirements (FR-001 through FR-007) have corresponding acceptance scenarios or success criteria that can verify compliance
+- [ ] CHK012 User scenarios cover the three primary consumption patterns: default discovery (Story 1), property lookup with error handling (Story 2), and configuration override (Story 3)
+- [ ] CHK013 SC-003 specifies exact 100% branch coverage measured by a named tool (`--cov-branch`), and SC-006 specifies 1000-iteration determinism benchmarks — both are objectively measurable
+- [ ] CHK014 Requirements describe the `schema_override` shape contract and `PropertySchema` fields as interface-level TypedDict contracts without prescribing internal storage mechanisms or method
+  implementations
+
+## Notes
+
+- This checklist was generated from the specification content for issue #1780
+- Items marked incomplete require spec updates before proceeding to planning
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*