agentic-devtools 0.2.296__tar.gz → 0.2.297__tar.gz

{agentic_devtools-0.2.296 → agentic_devtools-0.2.297}/.github/copilot-instructions.md

@@ -1371,7 +1371,7 @@ if p.name not in {"__init__.py", "_version.py"} and "__pycache__" not in p.parts
 
 ## 11. 1:1:1 Test Structure
 
-All new tests **must** be placed under `tests/unit/` and follow the 1:1:1 policy.
+All **unit tests** must be placed under `tests/unit/` and follow the 1:1:1 policy.
 For the full reference, see [tests/README.md](../tests/README.md).
 
 ### Policy Summary
@@ -1439,6 +1439,45 @@ convention and code review. Run it locally before pushing:
 python scripts/validate_test_structure.py
 ```
 
+### Integration and Workflow Tests
+
+The 1:1:1 policy and `tests/unit/` directory apply exclusively to **unit tests** — tests that
+exercise a single symbol in isolation, without external services or persistent side-effects
+outside the test's own scope. Temporary filesystem usage via pytest's `tmp_path` fixture is
+permitted in unit tests.
+
+**Do NOT place integration or workflow tests in `tests/unit/`.**
+
+Integration tests (tests that cross multiple components, use persistent external state, or exercise
+full agent workflows) belong in `tests/workflows/`. Placing an integration test under `tests/unit/`
+violates the 1:1:1 contract and must be caught in code review — `scripts/validate_test_structure.py` only
+verifies directory/source-file path mapping and `__init__.py` presence; it cannot detect whether a
+test is integration-style.
+
+| Test type | Correct location |
+|---|---|
+| Unit test for `IssueAdapter` | `tests/unit/adapters/base/test_issueadapter.py` |
+| Integration test for complete workflow lifecycles | `tests/workflows/test_workflow_end_to_end.py` |
+
+A test is an **integration test** when it:
+
+- Exercises more than one module or component together
+- Uses persistent external state, real network sockets, external services, or real subprocesses (temporary file writes via pytest's `tmp_path` do not qualify)
+- Simulates a full agent workflow or multi-step command sequence
+
+Based on audit of PRs #2641.
+
+### Performance Benchmarks in Tests
+
+**Do NOT write wall-clock performance assertions in `tests/unit/` files.** Time-based thresholds
+(e.g., "must complete in <5ms", "must complete in <100ms") are inherently flaky on shared CI
+runners due to load variation and produce false failures unrelated to code correctness.
+
+If a specification requires performance validation, plan it as a **manual validation step** or a
+separate benchmark task — not as a pytest assertion with a fixed wall-clock threshold.
+
+Based on audit of PRs #2635, #2641.
+
 ## 12. Python Coding Patterns
 
 ### Import ordering (ruff/isort)

{agentic_devtools-0.2.296 → agentic_devtools-0.2.297}/PKG-INFO

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

{agentic_devtools-0.2.296 → agentic_devtools-0.2.297}/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.296'
-__version_tuple__ = version_tuple = (0, 2, 296)
+__version__ = version = '0.2.297'
+__version_tuple__ = version_tuple = (0, 2, 297)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.296 → agentic_devtools-0.2.297}/agentic_devtools/cli/audit/copilot-instructions.md

@@ -9,10 +9,10 @@
 ## Scope
 
 These instructions apply to Copilot and AI agents when writing or reviewing Python code
-in the `agentic_devtools/cli/audit/` package (Sections 1–4).
+in the `agentic_devtools/cli/audit/` package (Sections 1–6).
 
 They encode lessons from a review of PR #2517 (auto-apply audit output via scheduled
-eval-PR takeover).
+eval-PR takeover) and PR #2657 (token handling in the audit apply flow).
 
 > **Note:** Section 4 (`$GITHUB_OUTPUT` newline sanitization) applies to Python helper
 > code in this package that emits output for GitHub Actions. The equivalent instruction
@@ -129,3 +129,52 @@ For equivalent sanitization in GitHub Actions workflow YAML (bash), see
 `.github/workflows/copilot-instructions.md`.
 
 **Based on audit of PR:** #2517
+
+---
+
+## 5. Strip Each Environment Variable Token Before `or`-Chaining
+
+When reading a credential from multiple candidate environment variables, strip whitespace from
+**each candidate independently** before the `or` fallback, not from the combined result.
+
+**Problematic pattern:**
+
+```python
+# ❌ If GH_TOKEN is whitespace-only, `or` short-circuits to that non-empty raw value first.
+#    After `.strip()` it becomes "", but fallback to SPECKIT_PR_TOKEN is already skipped.
+token = (os.environ.get("GH_TOKEN") or os.environ.get("SPECKIT_PR_TOKEN", "")).strip()
+```
+
+**Correct pattern:**
+
+```python
+# ✅ Strip each candidate first so whitespace-only values are treated as absent
+gh_token = os.environ.get("GH_TOKEN", "").strip()
+pr_token = os.environ.get("SPECKIT_PR_TOKEN", "").strip()
+token = gh_token or pr_token
+if not token:
+    logger.error("Neither GH_TOKEN nor SPECKIT_PR_TOKEN is set.")
+    return ""
+```
+
+This ensures that a whitespace-only `GH_TOKEN` falls through to the correct `SPECKIT_PR_TOKEN`
+value rather than silently masking it.
+
+**Based on audit of PR:** #2657
+
+---
+
+## 6. Token Presence Check Must Match Downstream Authentication Expectations
+
+When the audit `apply` flow checks whether a token is present before spawning a subprocess
+(e.g., calling `gh pr create`), the token used in the presence check must be the **same** token
+the downstream tool authenticates with.
+
+- `gh` authenticates via `GH_TOKEN` (or the ambient `GITHUB_TOKEN`).
+- `SPECKIT_PR_TOKEN` can be a valid input source **if** your flow normalizes/copies it into
+  `GH_TOKEN` before invoking `gh`.
+
+**Guideline:** if a subprocess relies on `GH_TOKEN`, the pre-flight check must validate the
+final non-empty `GH_TOKEN` value that the subprocess will actually see after normalization.
+
+**Based on audit of PR:** #2657

agentic_devtools-0.2.297/agentic_devtools/cli/git/copilot-instructions.md

@@ -0,0 +1,131 @@
+# AI Agent Instructions: `agentic_devtools/cli/git/`
+
+> 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 Copilot and AI agents when writing or reviewing Python code
+in the `agentic_devtools/cli/git/` package.
+
+---
+
+## 1. Token/Credential Redaction Must Cover Exception Messages
+
+*Based on audit of PR #2657*
+
+When a git command embeds a credential in the remote URL (e.g., `https://x-access-token:{token}@github.com/...`),
+redacting the token from captured **stderr/stdout** is not sufficient. `subprocess.CalledProcessError`
+captures the raw `cmd` list and includes it in `__str__`, so any caught-and-logged exception will expose
+the credential even when output streams are clean. The inverse is also unsafe: sanitizing only `cmd`
+still leaks the credential if `git` echoes the tokenized remote URL into stderr or stdout.
+
+**Required pattern:**
+
+```python
+from urllib.parse import urlsplit, urlunsplit
+
+
+def _redacted_remote_url(raw_url: str | None) -> tuple[str | None, str | None]:
+    """Return (redacted_url, bare_password) so callers can sanitize both forms."""
+    if not raw_url:
+        return raw_url, None
+    parts = urlsplit(raw_url)
+    if "@" not in parts.netloc:
+        return raw_url, None
+    userinfo, host = parts.netloc.rsplit("@", 1)
+    username, sep, secret = userinfo.partition(":")
+    if not sep or not secret:
+        return raw_url, None
+    safe_userinfo = f"{username}:<redacted>"
+    safe_url = urlunsplit(
+        (parts.scheme, f"{safe_userinfo}@{host}", parts.path, parts.query, parts.fragment)
+    )
+    return safe_url, secret
+
+
+redacted_remote_url, _token_password = _redacted_remote_url(token_remote_url)
+
+# Coerce every arg to str: subprocess cmd lists may contain Path objects, which
+# do not have string .replace() semantics — Path.replace() is a filesystem rename API
+# with a different signature, so treating a Path like a string here will typically raise
+# rather than redact. Always str(arg) before substituting.
+# Apply both the full-URL replacement and the bare-password replacement so a normalized
+# or rewritten URL (e.g., with stripped whitespace) cannot leave the token in safe_cmd.
+def _sanitize_arg(arg: object) -> str:
+    s = str(arg)
+    if token_remote_url and redacted_remote_url:
+        s = s.replace(token_remote_url, redacted_remote_url)
+    if _token_password:
+        s = s.replace(_token_password, "<redacted>")
+    return s
+
+safe_cmd = [_sanitize_arg(arg) for arg in cmd]
+
+
+def _redact(value: str | None) -> str | None:
+    if value is None:
+        return value
+    # Replace full tokenized URL first, then any bare password that git may echo
+    # independently (e.g., only the password portion in a credential-helper error).
+    result = value
+    if token_remote_url and redacted_remote_url:
+        result = result.replace(token_remote_url, redacted_remote_url)
+    if _token_password:
+        result = result.replace(_token_password, "<redacted>")
+    return result
+
+try:
+    subprocess.run(
+        cmd,
+        check=True,
+        capture_output=True,
+        text=True,
+        shell=False,
+    )
+except subprocess.CalledProcessError as e:
+    # Raise with fully sanitized fields so token never appears in exception strings or logs
+    raise subprocess.CalledProcessError(
+        returncode=e.returncode,
+        cmd=safe_cmd,
+        output=_redact(e.output),
+        stderr=_redact(e.stderr),
+    ) from e
+```
+
+Apply this pattern anywhere `token_remote_url` or a bearer token appears in a subprocess `cmd`
+list or may be echoed back in captured subprocess output. Two details are required for complete
+coverage:
+
+- **Coerce `cmd` elements to `str`** — subprocess arg lists may contain `pathlib.Path` objects,
+  which do not have string `.replace()` semantics. `Path.replace()` is a filesystem rename API
+  with a different signature, so treating a `Path` like a string here will typically raise rather
+  than redact. Always `str(arg)` before substituting.
+- **Redact the bare password separately** — `git` and credential helpers sometimes echo only the
+  password portion of a remote URL (not the full tokenized `https://user:<token>@host/...` form).
+  Extract the password from the parsed URL and apply a second `.replace()` pass in `_redact()` so
+  this form is also sanitized.
+
+---
+
+## 2. Empty and Whitespace Strings Are Not Valid Remote URLs
+
+*Based on audit of PR #2657*
+
+The `push_dest` selection logic must reject empty and whitespace-only strings, not just `None`.
+Using `if token_remote_url is not None` allows an empty string `""` to be selected, which
+produces a confusing `git push "" ...` failure that is hard to diagnose.
+
+**Correct guard:**
+
+```python
+# ✅ Rejects None, "", and whitespace
+token_push_dest = token_remote_url.strip() if token_remote_url and token_remote_url.strip() else None
+push_dest = token_push_dest or origin_remote
+```
+
+This also aligns with the downstream redaction logic, which treats empty strings as absent and
+ensures the selected destination is already normalized before `git push` receives it.

agentic_devtools-0.2.297/specs/1883-implement-checkpoint-resume-idempotent/analysis-report.md

@@ -0,0 +1,107 @@
+# Cross-Artifact Consistency and Quality Analysis Report
+
+## Findings Table
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A-01 | Duplication | LOW | FR-002 / FR-010 | FR-002 and FR-010 both specify the `_node_statuses` channel schema and the requirement that node wrappers write terminal status before yielding control. FR-010 is the canonical definition; FR-002 restates it. | Consolidate: FR-002 should reference FR-010 for the channel definition rather than re-describing it. |
+| A-02 | Duplication | LOW | FR-005 / Key Entities (Operation Log) | The 200-char and 500-char truncation limits and the "Phase 2 unified policy deferral" are stated in FR-005, in Key Entities (Idempotency Registry), and again in Key Entities (Operation ID). Three near-identical passages. | Consolidate truncation policy into FR-005 alone; Key Entities should reference FR-005. |
+| A-03 | Duplication | LOW | FR-009 / Edge Cases (concurrent start) | The single-active-execution requirement appears in FR-009 and is restated with its own acceptance scenario in the Edge Cases section. Both define the same constraint. | Reference FR-009 from the edge case rather than re-specifying the contract. |
+| B-01 | Ambiguity | MEDIUM | NFR-001 | "Typical graph state sizes (under 1MB)" — no definition of what constitutes "typical" or how the 1MB threshold was derived. No guidance for states exceeding 1MB. | Define an explicit size range or state that the 50ms target applies to states ≤1MB and document expected degradation above that. |
+| B-02 | Ambiguity | MEDIUM | NFR-002 | "Normal filesystem conditions" for the 10ms append target is undefined. No degradation behavior specified for NFS, network mounts, or high-contention scenarios. | Qualify the 10ms target with filesystem type (local ext4/APFS) and state the behavior expectation for non-local filesystems. |
+| B-03 | Ambiguity | MEDIUM | SC-005 | "No unnecessary disk I/O" is qualitative. The sentence acknowledges timing benchmarks are non-gating but provides no alternative pass/fail mechanism for verifying the O(1) property. | Define a structural assertion (e.g., mock filesystem, count `open()` calls after init) rather than relying on undefined "unnecessary" judgment. |
+| B-04 | Ambiguity | LOW | FR-003 scope note | "Each will define its own analogous policy object" — no naming convention or interface contract for future policy objects is specified. | Add a note that future policy objects MUST expose `retry_budget` and `node_retry_budgets` with the same semantics, or define a shared protocol. |
+| C-01 | Underspecification | HIGH | FR-003 / Edge Cases | No specification for what "surfaces the failure for escalation" means concretely when a node reaches `failed_permanent`. The edge case mentions "configured error-handling strategy" but no such strategy is defined or referenced. | Define the concrete escalation mechanism: does the workflow terminate, emit an event, call a callback, or log and continue? Specify the interface. |
+| C-02 | Underspecification | MEDIUM | FR-009 | `run_id` generation specifies "generate one" but does not specify the format (UUID v4? hex? with prefix?). The plan shows `str(uuid.uuid4())` but the spec leaves it open. | Specify UUID v4 string format in the spec to match the plan, or explicitly state "format is implementation-defined." |
+| C-03 | Underspecification | MEDIUM | Edge Cases (at-least-once) | The "accepted trade-off" of at-least-once semantics when the completed record fails to persist has no mitigation strategy or monitoring hook. No way for operators to detect this condition. | Add a requirement for a warning/metric emission when the post-execution record-persist fails, so operators can detect potential duplicates. |
+| C-04 | Underspecification | MEDIUM | NFR-001 | SQLite WAL mode is mentioned as a consideration ("should be considered if write contention becomes measurable") but no decision criteria or threshold is specified. | Either mandate WAL mode unconditionally (it has no downside for single-writer scenarios) or define the contention threshold that triggers it. |
+| C-05 | Underspecification | LOW | Plan Phase 1 (ExecutionLock) | Lock file cleanup on process crash is not specified. If the process dies without calling `release()`, the lock file may remain, preventing future starts. | Specify stale-lock detection (e.g., PID-based liveness check or advisory `fcntl` locks that auto-release on process death). |
+| D-01 | Constitution Alignment | LOW | Spec | No explicit "Out of Scope" section. The spec mentions Phase 2 deferrals inline but has no consolidated boundary statement. | Add an "Out of Scope" section listing: unified size-based replay policy, multi-workflow retry policy sharing, exactly-once semantics. |
+| E-01 | Coverage Gaps | MEDIUM | NFR-001 | NFR-001 (50ms checkpoint write latency) has no task coverage. No performance test or benchmark task exists. | Add a task to verify checkpoint write latency stays under 50ms for ≤1MB state, even if the assertion is informational/non-gating per SC-005 precedent. |
+| E-02 | Coverage Gaps | MEDIUM | NFR-003 | NFR-003 (O(1) lookup after init) has no dedicated task. SC-005 partially covers it but only for OperationLog, not IdempotencyRegistry if it enters the hot path. | Add a structural test task verifying O(1) lookup (e.g., no file I/O calls after initialization). |
+| E-03 | Coverage Gaps | LOW | NFR-004 | NFR-004 (deterministic resume behavior) has no dedicated task. It is implicitly covered by integration tests (T051) but not explicitly asserted. | Add a note in T051 that determinism is explicitly verified (same inputs → same outputs across runs). |
+| E-04 | Coverage Gaps | LOW | NFR-005 | NFR-005 (.gitignore compatibility) has no task. Trivially satisfied but unverified. | Add a check in T055/T056 that new file paths are covered by existing `.gitignore` rules. |
+| F-01 | Inconsistency | HIGH | tasks.md vs. test-coverage.json | The task list references 57 tasks (T001–T057). `test-coverage.json` has two classes of inconsistency: **(1) Phantom IDs** — T058 and T063–T076 (see lines 16–19, 38–40, and 101–105) do not exist in the task list at all. **(2) Stale/renumbered IDs** — several valid-range IDs now point to different tasks; for example, FR-001 and FR-009 both list T015/T017/T019/T022 (see lines 78–82 and 143–146), but those IDs in the current `tasks.md` belong to FR-003 retry-policy work (WorkOnIssuePolicy/PolicyLoader), not to checkpoint path resolution (FR-001) or run-ID generation (FR-009). Patching only the phantom IDs would leave false traceability mappings in place for the stale set. | Regenerate or fully remap `test-coverage.json` against the current task list. A targeted patch for phantom IDs is insufficient; every task-ID reference must be verified against current `tasks.md` content to eliminate stale mappings before the traceability data can be trusted. |
+| F-02 | Inconsistency | MEDIUM | Plan Phase 2 vs. Task list Phase 5 | Plan Phase 2 says `NodeStatus` is a "dataclass" and shows `@dataclass(frozen=True)`. Spec Key Entities says "JSON-serializable typed dict (or equivalent dataclass)." The ambiguity between TypedDict and dataclass is unresolved. | Pick one. The plan chose dataclass — update the spec Key Entities to say "frozen dataclass" definitively. |
+| F-03 | Inconsistency | MEDIUM | FR-003 vs. Plan Phase 2 | FR-003 states `attempt_count` starts at 1 for the initial attempt. The plan's `resumable_node` code shows `attempt = (current["attempt_count"] if current else 0) + 1`, which correctly yields 1 on first attempt, and the exception path explicitly writes `attempt_count=attempt` for `failed` status. However, the success path still uses `NodeStatus(status="completed", ...)`, so the snippet does not show whether `attempt_count` is also persisted on the `completed` path as FR-003/FR-010 require. | Ensure plan code snippets are complete enough to verify `attempt_count` is always set, especially on the `completed` path. |
+| F-04 | Inconsistency | LOW | US tag mismatch | T027–T032 are tagged `[US5]` in the task list but FR-006 maps to User Story 5 which is P3. The phase is labeled "Phase 6: US5" but the plan calls it "Phase 3: Operation ID Signature Change." Phase numbering diverges between plan and task list. | Align phase numbering between plan and task list, or add a mapping note. |
+| F-05 | Inconsistency | MEDIUM | spec.md / plan.md / tasks.md | The spec defines the `_node_statuses` channel as `dict[str, NodeStatus]` (spec.md Key Entities), and the task list aligns with that by requiring `_node_statuses: dict[str, NodeStatus]` in `state_schema.py` (T023). But the plan's "State schema extension" example still types `_node_statuses` as `dict[str, Any]`, which weakens the contract in the one place implementers are likely to copy from directly. | Update the plan's state schema example to use `dict[str, NodeStatus]` (or the equivalent concrete serialized type) so the plan matches the stronger contract already established by the spec and tasks. |
+| G-01 | Task Dedup | HIGH | T033, T042 | T033 and T042 both write tests for operation log record fields including `prior_completion_timestamp`, lifecycle records, and FR-005 compliance. They target the same test directory (`tests/unit/orchestration/safety/operation_log/`). | Merge into a single test task or clearly delineate: T033 = append mechanics + NFR-002 lock; T042 = lifecycle semantics + field completeness. |
+| G-02 | Task Dedup | HIGH | T034, T043 | T034 and T043 both modify `agentic_devtools/orchestration/safety/operation_log.py` for FR-005 field completeness. T034 adds `prior_completion_timestamp` + lock fix; T043 verifies/updates "all FR-005 fields" including `node_name`, `run_id`, `result_payload`, `prior_completion_timestamp`. Significant scope overlap. | Merge T043's FR-005 field additions into T034 so operation_log.py is modified once. T043 becomes verification-only. |
+| G-03 | Task Dedup | HIGH | T012, T036, T037 | T036 writes tests for SafetyEnforcer+OperationLog wiring in runner; T037 implements that wiring. Both reference `tests/unit/orchestration/runner/` and `agentic_devtools/orchestration/runner.py` for FR-004/FR-007. T012 also modifies `runner.py` for FR-009. Three tasks touching the same file with related concerns. | T012, T036, T037 should be sequenced carefully. Consider consolidating runner.py modifications into fewer tasks. |
+
+## Category G Structured Findings
+
+```json
+[
+  {
+    "id": "G-01",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T033", "T042"],
+    "dimensions": ["description", "file_path"],
+    "rationale": "Both tasks write tests for operation log record fields (prior_completion_timestamp, lifecycle records, FR-005 fields) targeting tests/unit/orchestration/safety/operation_log/. T033 focuses on append mechanics and locked fallback; T042 focuses on lifecycle completeness. Overlapping scope for the same test directory and partially overlapping field coverage."
+  },
+  {
+    "id": "G-02",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T034", "T043"],
+    "dimensions": ["description", "file_path", "code_section"],
+    "rationale": "Both tasks modify agentic_devtools/orchestration/safety/operation_log.py to add/verify FR-005 fields. T034 adds prior_completion_timestamp and lock fix. T043 verifies/updates all FR-005 fields including prior_completion_timestamp, node_name, run_id, result_payload. The prior_completion_timestamp work is duplicated across both tasks."
+  },
+  {
+    "id": "G-03",
+    "overlap_type": "overlapping",
+    "severity": "HIGH",
+    "task_ids": ["T012", "T036", "T037"],
+    "dimensions": ["file_path"],
+    "rationale": "All three tasks modify agentic_devtools/orchestration/runner.py. T012 adds run_id generation and ExecutionLock. T036 writes tests for SafetyEnforcer wiring in runner. T037 implements that wiring. Single dimension (file_path) but three tasks on same file risks merge conflicts and requires careful sequencing."
+  }
+]
+```
+
+## Coverage Summary Table
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|----------------|-----------|----------|-------|
+| FR-001 | ✅ | T005, T006, T007, T052 | Fully covered |
+| FR-002 | ✅ | T023, T024, T025, T040, T051 | Fully covered |
+| FR-003 | ✅ | T015, T018, T020, T021, T024, T025, T051 | Fully covered |
+| FR-004 | ✅ | T036, T037, T040, T051 | Fully covered |
+| FR-005 | ✅ | T033, T034, T042, T043 | Covered; tasks overlap (G-01, G-02) |
+| FR-006 | ✅ | T027, T028, T029, T030, T031 | Fully covered |
+| FR-007 | ✅ | T036, T037, T038, T039 | Fully covered |
+| FR-008 | ✅ | T045, T046, T051 | Fully covered |
+| FR-009 | ✅ | T008, T009, T011, T012, T053 | Fully covered |
+| FR-010 | ✅ | T014, T016, T023, T024, T025 | Fully covered |
+| NFR-001 | ❌ | — | No performance verification task (E-01) |
+| NFR-002 | ✅ | T033, T034 | Covered |
+| NFR-003 | ❌ | — | No dedicated O(1) lookup verification (E-02) |
+| NFR-004 | ⚠️ | T051 (implicit) | Not explicitly asserted (E-03) |
+| NFR-005 | ❌ | — | No gitignore compatibility check (E-04) |
+| SC-001 | ✅ | T005, T006 | Covered |
+| SC-002 | ✅ | T051 | Covered |
+| SC-003 | ✅ | T051 | Covered |
+| SC-004 | ✅ | T042, T043 | Covered |
+| SC-005 | ✅ | T042 | Partially covered |
+| SC-006 | ✅ | T054 | Covered |
+| SC-007 | ✅ | T052 | Covered |
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total Requirements | 15 (10 FR + 5 NFR) |
+| Total Tasks | 57 |
+| FR Coverage % | 100% (10/10) |
+| Overall Coverage % (FR+NFR, counting ✅ and ⚠️) | 80% (12/15) |
+| Ambiguity Count | 4 (B-01 through B-04) |
+| Requirement Duplication Count (Category A) | 3 |
+| High-Severity Findings Count | 5 (C-01, F-01, G-01, G-02, G-03) |
+| Task Deduplication Finding Count | 3 |
+| Task Deduplication by Type | duplicate: 0 / overlapping: 3 / conflicting: 0 |
+| Multi-Task Group Count | 1 (G-03 involves 3 tasks) |
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*

agentic_devtools-0.2.297/specs/1883-implement-checkpoint-resume-idempotent/tasks.md

@@ -0,0 +1,199 @@
+# Tasks: Checkpoint/Resume with Idempotent External Writes
+
+## Phase 1: Setup — Project Scaffolding
+
+- [ ] T001 Create directory structure for new modules and test directories with `__init__.py` files: `agentic_devtools/orchestration/` (verify existing), `tests/unit/orchestration/checkpointing/`,
+  `tests/unit/orchestration/execution_lock/`, `tests/unit/orchestration/node_status/`, `tests/unit/orchestration/idempotency/`, `tests/unit/orchestration/safety/operation_id/`,
+  `tests/unit/orchestration/safety/operation_log/`, `tests/unit/orchestration/safety/enforcer/`, `tests/unit/orchestration/policies/config/`, `tests/unit/orchestration/policies/loader/`
+- [ ] T002 Read and catalogue existing source files to understand current signatures and contracts: `agentic_devtools/orchestration/checkpointing.py`, `agentic_devtools/orchestration/runner.py`,
+  `agentic_devtools/orchestration/state_schema.py`, `agentic_devtools/orchestration/safety/operation_id.py`, `agentic_devtools/orchestration/safety/operation_log.py`,
+  `agentic_devtools/orchestration/safety/enforcer.py`, `agentic_devtools/orchestration/execution/idempotency.py`, `agentic_devtools/orchestration/tools/executor.py`,
+  `agentic_devtools/orchestration/policies/config.py`, `agentic_devtools/orchestration/policies/loader.py`, `agentic_devtools/orchestration/policies/defaults.py`
+
+## Phase 2: Foundational — Blocking Prerequisites
+
+- [ ] T003 Read existing tests for all files being modified to understand current test patterns and coverage: `tests/unit/orchestration/checkpointing/`, `tests/unit/orchestration/safety/`,
+  `tests/unit/orchestration/policies/`, `tests/unit/orchestration/execution/`
+- [ ] T004 Validate that `get_state_dir()` in `agentic_devtools/state.py` returns a `Path` and understand its resolution priority chain (env var → bootstrap → fallback) for correct integration in
+  later phases
+
+## Phase 3: US2 — Checkpoint Database Uses Worktree-Scoped Path (P1)
+
+- [ ] T005 [US2] Write failing tests for `get_checkpointer()` worktree-scoped path resolution in `tests/unit/orchestration/checkpointing/test_get_checkpointer.py`: mock `get_state_dir()` and assert DB
+  path is `<state_dir>/orchestration.db`; test env var override via `AGENTIC_DEVTOOLS_STATE_DIR`; test fallback when `db_path` is explicitly provided
+- [ ] T006 [US2] Update `get_checkpointer()` in `agentic_devtools/orchestration/checkpointing.py` to resolve default path via `get_state_dir() / "orchestration.db"` instead of `_get_git_repo_root() /
+  ".agdt" / "orchestration.db"` (FR-001)
+- [ ] T007 [US2] Run tests to verify `get_checkpointer()` changes pass: `agdt-test-pattern tests/unit/orchestration/checkpointing/ -v -o addopts=`
+
+## Phase 4: US2 + US1 — Execution Lock & Run ID (P1)
+
+- [ ] T008 [US2] Write failing tests for `ExecutionLock` in `tests/unit/orchestration/execution_lock/test_executionlock.py`: acquire/release lifecycle, context manager protocol, concurrent acquisition
+  rejection, release idempotency, lock file path derivation from `(state_dir, thread_id)` (FR-009 single-active-execution)
+- [ ] T009 [US2] Create `agentic_devtools/orchestration/execution_lock.py` with `ExecutionLock` class implementing file-based lock for `(state_dir, thread_id)` scope with `acquire()`, `release()`,
+  `__enter__`/`__exit__` (FR-009)
+- [ ] T010 [US2] Run tests to verify `ExecutionLock` passes: `agdt-test-pattern tests/unit/orchestration/execution_lock/ -v -o addopts=`
+- [ ] T011 [US1] Write failing tests for `run_id` generation and restoration in workflow runner in `tests/unit/orchestration/runner/test_run_id.py`: fresh start
+  generates UUID `run_id` in `configurable`; resume restores existing `run_id` from checkpoint; `run_id` is present before first checkpoint write (FR-009)
+- [ ] T012 [US1] Update `agentic_devtools/orchestration/runner.py` to generate `run_id` on fresh start, restore from checkpoint on resume, and acquire `ExecutionLock` before node execution (FR-009)
+- [ ] T013 [US1] Run tests to verify runner `run_id` and lock integration: `agdt-test-pattern tests/unit/orchestration/runner/ -v -o addopts=`
+
+## Phase 5: US1 + US3 — Node Status Channel (P1/P2)
+
+- [ ] T014 [P] [US1] Write failing tests for `NodeStatus` dataclass in `tests/unit/orchestration/node_status/test_nodestatus.py`: construction with valid fields, invariant enforcement (`error_summary`
+  is `None` on completed, non-empty on failed/failed_permanent), `attempt_count >= 1`, JSON serialization round-trip (FR-010)
+- [ ] T015 [P] [US3] Write failing tests for `WorkOnIssuePolicy.node_retry_budgets` field in `tests/unit/orchestration/policies/config/test_workonissuepolicy.py`: default empty dict, per-node override
+  lookup, fallback to top-level `retry_budget` (FR-003)
+- [ ] T016 [US1] Create `agentic_devtools/orchestration/node_status.py` with `NodeStatus` frozen dataclass (`status`, `attempt_count`, `error_summary`) and `NodeFailedError` exception class with
+  `state_update` attribute (FR-010)
+- [ ] T017 [US1] Run tests to verify `NodeStatus` passes: `agdt-test-pattern tests/unit/orchestration/node_status/test_nodestatus.py -v -o addopts=`
+- [ ] T018 [US3] Add `node_retry_budgets: dict[str, int]` field to `WorkOnIssuePolicy` in `agentic_devtools/orchestration/policies/config.py` with default empty dict (FR-003)
+- [ ] T019 [US3] Run tests to verify `WorkOnIssuePolicy` changes pass: `agdt-test-pattern tests/unit/orchestration/policies/config/ -v -o addopts=`
+- [ ] T020 [US3] Write failing tests for `PolicyLoader` parsing of `node_retry_budgets` from YAML in `tests/unit/orchestration/policies/loader/test_policyloader.py` (or extend existing): YAML with
+  `work_on_issue.node_retry_budgets.<node_name>` maps correctly (FR-003)
+- [ ] T021 [US3] Update `PolicyLoader` in `agentic_devtools/orchestration/policies/loader.py` to parse `node_retry_budgets` from YAML under `work_on_issue` section (FR-003)
+- [ ] T022 [US3] Run tests to verify `PolicyLoader` changes pass: `agdt-test-pattern tests/unit/orchestration/policies/loader/ -v -o addopts=`
+- [ ] T023 [US1] Add `_node_statuses: dict[str, NodeStatus]` channel to `WorkOnIssueState` in `agentic_devtools/orchestration/state_schema.py` (FR-002, FR-010)
+- [ ] T024 [US1] Write failing tests for `resumable_node` decorator in `tests/unit/orchestration/node_status/test_resumable_node.py`: skip completed node (returns empty dict), retry failed node within
+  budget, mark `failed_permanent` when budget exhausted, record `completed` status after success, record `failed` status after exception, increment `attempt_count` on retry (FR-002, FR-003, FR-010)
+- [ ] T025 [US1] Implement `resumable_node()` decorator in `agentic_devtools/orchestration/node_status.py` with skip-completed, retry-with-budget, and status-write logic (FR-002, FR-003)
+- [ ] T026 [US1] Run tests to verify `resumable_node` passes: `agdt-test-pattern tests/unit/orchestration/node_status/ -v -o addopts=`
+
+## Phase 6: US5 — Operation ID Signature Change (P3)
+
+- [ ] T027 [US5] Write failing tests for `compute_operation_id()` with `node_name` as required first parameter in `tests/unit/orchestration/safety/operation_id/test_compute_operation_id.py`: new
+  signature produces deterministic IDs; same tool+inputs with different `node_name` values produce distinct `operation_id`s; `nondeterministic_fields` exclusion still works; hash stability across
+  process restarts (FR-006)
+- [ ] T028 [US5] Update `compute_operation_id()` in `agentic_devtools/orchestration/safety/operation_id.py` to accept `node_name` as required first parameter and embed it in SHA-256 hash input
+  (FR-006)
+- [ ] T029 [US5] Update all call sites of `compute_operation_id()` to pass `node_name`: `agentic_devtools/orchestration/safety/enforcer.py`, `agentic_devtools/orchestration/tools/executor.py`,
+  `agentic_devtools/orchestration/execution/idempotency.py` (FR-006)
+- [ ] T030 [US5] Write failing tests for `SafetyEnforcer.evaluate()` `node_name` validation in `tests/unit/orchestration/safety/enforcer/test_evaluate.py` (or extend existing): external-mutation tools
+  require non-empty `node_name`; read-only tools allow empty `node_name` (FR-006)
+- [ ] T031 [US5] Add `node_name` parameter to `SafetyEnforcer.evaluate()` with validation guard for external-mutation/destructive tools in `agentic_devtools/orchestration/safety/enforcer.py` (FR-006)
+- [ ] T032 [US5] Run tests to verify operation ID and enforcer changes pass: `agdt-test-pattern tests/unit/orchestration/safety/ -v -o addopts=`
+
+## Phase 7: US1 + US4 — Graph-Level Resume Wiring (P1/P2)
+
+- [ ] T033 [US4] Write failing tests for operation log `prior_completion_timestamp` on skipped records and locked fallback append in `tests/unit/orchestration/safety/operation_log/test_append.py` (or
+  extend existing): skipped record includes `prior_completion_timestamp` from matched completed record; `FileNotFoundError` recovery uses `locked_file()` not plain `open("a")` (FR-005, NFR-002)
+- [ ] T034 [US4] Update `OperationLog` in `agentic_devtools/orchestration/safety/operation_log.py`: add `prior_completion_timestamp` to skipped duplicate records; fix `FileNotFoundError` fallback to
+  use `locked_file()` instead of plain write (FR-005, NFR-002)
+- [ ] T035 [US4] Run tests to verify operation log changes pass: `agdt-test-pattern tests/unit/orchestration/safety/operation_log/ -v -o addopts=`
+- [ ] T036 [US1] Write failing tests for `SafetyEnforcer` + `OperationLog` wiring in workflow runner in `tests/unit/orchestration/runner/test_safety_wiring.py` (or appropriate location):
+  `SafetyEnforcer` constructed with `OperationLog` scoped to `run_id`; external-mutation tool calls go through safety evaluation; completed operations return cached `result_payload` (FR-004, FR-007)
+- [ ] T037 [US1] Wire `SafetyEnforcer` with `OperationLog` into graph execution flow in `agentic_devtools/orchestration/runner.py`: construct with `run_id`-scoped `OperationLog`, pass to
+  `ToolExecutor`/context (FR-004, FR-007)
+- [ ] T038 [US5] Write failing tests for automatic idempotency wrapping of external-mutation tools in `tests/unit/orchestration/tools/executor/test_idempotent_wrapping.py` (or extend existing):
+  mutation tools are wrapped by `IdempotentToolWrapper`; read-only tools are not wrapped (FR-007)
+- [ ] T039 [US5] Ensure `IdempotentToolWrapper` is automatically applied to external-mutation tools in the tool binding layer via `agentic_devtools/orchestration/tools/executor.py` or context factory
+  (FR-007)
+- [ ] T040 [US1] Wire `resumable_node` decorator into compiled graph in `agentic_devtools/orchestration/graph_builder.py` (or equivalent graph construction code): all nodes wrapped with skip/retry
+  logic; `node_name` propagated to `ToolExecutor` call sites (FR-002, FR-004)
+- [ ] T041 [US1] Run integration-level tests for resume wiring: `agdt-test-pattern tests/unit/orchestration/runner/ -v -o addopts=`
+
+## Phase 8: US4 — Operation Log Audit Completeness (P2)
+
+- [ ] T042 [US4] Write failing tests for operation log lifecycle records in `tests/unit/orchestration/safety/operation_log/test_lifecycle.py` (or extend existing): pending record written before tool
+  call; completed record written after success with `result_payload` and `result_summary`; failed record written on error; skipped record includes `skip_reason` and `prior_completion_timestamp`;
+  `node_name` and `run_id` present on all records (FR-005)
+- [ ] T043 [US4] Verify/update `OperationLog` record schema in `agentic_devtools/orchestration/safety/operation_log.py` to include all FR-005 fields: `node_name`, `run_id`, `result_payload`,
+  `prior_completion_timestamp`, `skip_reason` on every record as appropriate (FR-005)
+- [ ] T044 [US4] Run tests to verify audit completeness: `agdt-test-pattern tests/unit/orchestration/safety/operation_log/ -v -o addopts=`
+
+## Phase 9: US1 — Graceful Degradation (P1)
+
+- [ ] T045 [US1] Write failing tests for graceful degradation on corrupted/missing operation log and idempotency registry in `tests/unit/orchestration/safety/enforcer/test_graceful_degradation.py`:
+  missing file → cache-miss + warning; corrupted JSON → cache-miss + warning; completed nodes in `_node_statuses` still skipped even with missing op-log (FR-008)
+- [ ] T046 [US1] Verify/update graceful degradation behavior in `SafetyEnforcer`, `OperationLog._build_index()`, and `IdempotencyRegistry._load_entries()` for missing/corrupted files: emit warning,
+  treat as cache-miss, do not crash (FR-008)
+- [ ] T047 [US1] Run tests to verify degradation: `agdt-test-pattern tests/unit/orchestration/safety/enforcer/ -v -o addopts=`
+
+## Phase 10: US5 — Re-Export Shim (P3)
+
+- [ ] T048 [P] [US5] Write failing tests for re-export shim in `tests/unit/orchestration/idempotency/test_reexports.py`: verify `IdempotencyRegistry`, `OperationLog`, `OperationLogRecord`,
+  `compute_operation_id` are importable from `agentic_devtools.orchestration.idempotency` and are the same objects as their canonical locations
+- [ ] T049 [P] [US5] Create `agentic_devtools/orchestration/idempotency.py` re-export shim with `__all__` listing `IdempotencyRegistry`, `OperationLog`, `OperationLogRecord`, `compute_operation_id`
+- [ ] T050 [US5] Run tests to verify re-export shim: `agdt-test-pattern tests/unit/orchestration/idempotency/ -v -o addopts=`
+
+## Phase 11: Final — Integration Tests, Validation & Documentation
+
+- [ ] T051 Write end-to-end integration tests for resume scenarios in `tests/unit/orchestration/` (appropriate subdirectory): (1) completed node A → interrupt → resume → A skipped (SC-002); (2) node
+  fails → resume → retry succeeds (SC-003); (3) node fails N+1 times → `failed_permanent` (SC-003); (4) partial node (2/3 tools done) → resume → only remaining tool executes (SC-002); (5) corrupted
+  op-log → graceful cache-miss (SC-002)
+- [ ] T052 Write worktree isolation integration test in `tests/unit/orchestration/checkpointing/test_worktree_isolation.py`: two worktrees produce distinct DB paths via `get_state_dir()`; no
+  cross-contamination of checkpoint state (SC-007)
+- [ ] T053 Write concurrent execution rejection test in `tests/unit/orchestration/execution_lock/test_concurrent_rejection.py`: second start for same `(state_dir, thread_id)` is rejected with clear
+  error before external-mutation nodes execute (FR-009 edge case)
+- [ ] T054 Run full test suite to verify no regressions: `agdt-test` then `agdt-task-wait`
+- [ ] T055 Run targeted checks on all modified and new files: `bash scripts/targeted-checks.sh`
+- [ ] T056 Run test structure validator to ensure 1:1:1 compliance: `python scripts/validate_test_structure.py`
+- [ ] T057 Update `copilot-instructions.md` with new configuration knobs: `work_on_issue.node_retry_budgets`, `_node_statuses` channel, `ExecutionLock` usage, and `orchestration.db` path resolution
+  via `get_state_dir()`
+
+## Dependency Graph
+
+```text
+T001, T002 → T003, T004
+T003, T004 → T005
+T005 → T006 → T007
+T007 → T008
+T008 → T009 → T010
+T007 → T011
+T010, T011 → T012 → T013
+T003 → T014, T015 (parallel)
+T014 → T016 → T017
+T015 → T018 → T019
+T019 → T020 → T021 → T022
+T017 → T023
+T023, T022 → T024
+T024 → T025 → T026
+T003 → T027
+T027 → T028
+T028 → T029
+T029 → T030 → T031 → T032
+T032, T026 → T033
+T033 → T034 → T035
+T013, T032 → T036
+T036 → T037
+T032 → T038 → T039
+T037, T039 → T040 → T041
+T035 → T042 → T043 → T044
+T032 → T045 → T046 → T047
+T032 → T048, T049 (parallel)
+T048, T049 → T050
+T041, T044, T047, T050 → T051, T052, T053
+T051, T052, T053 → T054 → T055 → T056 → T057
+```
+
+## Requirement Traceability
+
+Coverage-gap references `E-01` through `E-04` below point to the matching entries in
+[`analysis-report.md`](analysis-report.md#findings-table).
+
+| Requirement | Tasks |
+|---|---|
+| FR-001 (worktree-scoped DB path) | T005, T006, T007, T052 |
+| FR-002 (skip completed nodes) | T023, T024, T025, T040, T051 |
+| FR-003 (retry failed nodes) | T015, T018, T020, T021, T024, T025, T051 |
+| FR-004 (op-log for partial/retried nodes) | T036, T037, T040, T051 |
+| FR-005 (operation log lifecycle records) | T033, T034, T042, T043 |
+| FR-006 (node_name in operation ID) | T027, T028, T029, T030, T031 |
+| FR-007 (automatic idempotency wrapping) | T036, T037, T038, T039 |
+| FR-008 (graceful degradation) | T045, T046, T051 |
+| FR-009 (run_id scoping + single-active-execution) | T008, T009, T011, T012, T053 |
+| FR-010 (node_statuses channel) | T014, T016, T023, T024, T025 |
+| NFR-001 (checkpoint write latency ≤50ms) | — (no performance verification task; see E-01) |
+| NFR-002 (atomic locked appends) | T033, T034 |
+| NFR-003 (O(1) idempotency lookup after init) | — (no dedicated structural verification task; see E-02) |
+| NFR-004 (deterministic resume behavior) | T051 (implicit; see E-03) |
+| NFR-005 (.gitignore compatibility) | — (no explicit check; see E-04) |
+| SC-001 | T005, T006 |
+| SC-002 | T051 |
+| SC-003 | T051 |
+| SC-004 | T042, T043 |
+| SC-005 | T042 |
+| SC-006 | T054 |
+| SC-007 | T052 |
+
+---
+*Generated by Copilot SDK (claude-opus-4.6)*