quality-debt: .agents/reference/planning-detail.md — PR #2107 review feedback (high)

[marcusquinn]

Unactioned Review Feedback

Source PR: #2107
File: .agents/reference/planning-detail.md
Reviewers: coderabbit
Findings: 1
Max severity: high

---

HIGH: coderabbit (coderabbitai[bot])

File: .agents/reference/planning-detail.md:65
⚠️ Potential issue | 🟡 Minor

Hyphenate the compound adjective.
“Decision making” should be “decision‑making” in this compound phrase.

✍️ Proposed fix

-The AI lifecycle engine (`SUPERVISOR_AI_LIFECYCLE=true`, default) replaces hardcoded bash heuristics with intelligence-first decision making.
+The AI lifecycle engine (`SUPERVISOR_AI_LIFECYCLE=true`, default) replaces hardcoded bash heuristics with intelligence-first decision-making.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

The AI lifecycle engine (`SUPERVISOR_AI_LIFECYCLE=true`, default) replaces hardcoded bash heuristics with intelligence-first decision-making. For each active task, it gathers real-world state (DB, GitHub PR, CI, git), decides the next action, executes it, and updates the status tag. Set `SUPERVISOR_AI_LIFECYCLE=false` to fall back to the legacy `cmd_pr_lifecycle` bash heuristics.

🧰 Tools

🪛 LanguageTool

[grammar] ~65-~65: Use a hyphen to join words.
Context: ...ristics with intelligence-first decision making. For each active task, it gathers...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/reference/planning-detail.md at line 65, Replace the unhyphenated
compound phrase "decision making" with the hyphenated "decision-making" in the
descriptive sentence that explains the AI lifecycle engine (the sentence
mentioning SUPERVISOR_AI_LIFECYCLE and cmd_pr_lifecycle) so it reads
"intelligence-first decision-making" to correctly form the compound adjective;
update that occurrence in planning-detail.md wherever the phrase appears.

View comment

---

Auto-generated by quality-feedback-helper.sh scan-merged. Review each finding and either fix the code or dismiss with a reason.

[marcusquinn]

Additional Review Feedback (PR #2423)

Reviewers: coderabbit
Findings: 1
Max severity: critical

---

CRITICAL: coderabbit (coderabbitai[bot])

File: .agents/reference/planning-detail.md:105
⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat -n .agents/reference/planning-detail.md | sed -n '95,110p'

Repository: marcusquinn/aidevops

Length of output: 1368

---

🏁 Script executed:

# Verify the exact gh-cli syntax and API structure
gh api --help 2>&1 | head -20

Repository: marcusquinn/aidevops

Length of output: 1199

---

🌐 Web query:

GitHub CLI gh api timeline cross-referenced events pull_request merge state

💡 Result:

To answer “was the cross‑referenced PR eventually merged?” you generally need (a) the timeline cross-referenced events, then (b) a PR lookup for merged/mergedAt (or PR timeline merged event).

Option A (REST): issue/PR timeline → find cross-referenced → fetch PR → check merge

1. Get timeline items (includes cross-referenced, merged, etc.) from the issue/PR:

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/timeline

GitHub documents this endpoint as “List timeline events for an issue” (GET /repos/{owner}/{repo}/issues/{issue_number}/timeline). [1]

2. Filter to just cross-referenced events and extract the referenced item:

gh api -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/timeline \
  --jq '.[] | select(.event=="cross-referenced") | .source.issue'

In REST timeline events, cross-referenced includes a source object (the issue/PR that created the cross-reference). GitHub’s “issue event types” docs describe the cross-referenced event shape and that the source is always an issue object; you can detect whether it’s a PR via the presence of source.issue.pull_request. [2]

3. If it’s a PR, fetch the PR and read merge state:

# if you have PR number:
gh api -H "X-GitHub-Api-Version: 2022-11-28" /repos/OWNER/REPO/pulls/PR_NUMBER \
  --jq '{state, merged, merged_at}'

# if you only have the REST URL in source.issue.pull_request.url:
gh api -H "X-GitHub-Api-Version: 2022-11-28" "$(gh api ... --jq '.source.issue.pull_request.url')" \
  --jq '{state, merged, merged_at}'

Option B (GraphQL): timelineItems(CROSS_REFERENCED_EVENT) → inline PR merged/state

GraphQL can return cross-referenced items and, when the source is a PR, inline merged (and optionally mergedAt, state):

gh api graphql -f query='
query($owner:String!, $name:String!, $number:Int!) {
  repository(owner:$owner, name:$name) {
    issueOrPullRequest(number:$number) {
      ... on Issue {
        timelineItems(first:100, itemTypes:CROSS_REFERENCED_EVENT) {
          nodes {
            ... on CrossReferencedEvent {
              source {
                ... on PullRequest { number title state merged mergedAt }
              }
            }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F name=REPO -F number=ISSUE_NUMBER

The timelineItems(... itemTypes: CROSS_REFERENCED_EVENT) + ... on CrossReferencedEvent { source ... on PullRequest { merged }} pattern is commonly used for exactly this. [3]

Note: you may also see a direct merged timeline event

GitHub’s issue/PR timeline event types also include a merged event for PRs. [2] So, depending on your goal, you can either:

• look for a merged event in the PR’s own timeline, or
• compute “merged?” from the PR fields (merged / merged_at / mergedAt) after discovering it via cross-referenced.

Sources: GitHub REST timeline endpoint docs [1]; GitHub “issue event types” (includes cross-referenced, merged, and the source.issue.pull_request hint) [2]; GraphQL example using timelineItems + CROSS_REFERENCED_EVENT with source ... on PullRequest { merged } [3].

---

🌐 Web query:

gh pr view json state MERGED syntax documentation

💡 Result:

state is a valid JSON field for gh pr view, and its value can be OPEN, CLOSED, or MERGED. You must request it via --json (comma-separated fields), then optionally filter with --jq. [1], [2]

Examples:

# Print just the state (e.g., "MERGED")
gh pr view 123 --json state --jq .state

# Boolean “is merged” check (robust for scripting)
gh pr view 123 --json mergedAt --jq '(.mergedAt != null)'

# Get multiple fields
gh pr view 123 --json state,mergedAt,closedAt --jq '{state, mergedAt, closedAt}'

Sources: GitHub CLI manual for gh pr view (JSON fields include state, mergedAt, etc.) [1] and GitHub CLI formatting docs for --json + --jq usage. [2]

---

Step 3 fallback must verify merged state, not just presence of cross-referenced PRs

The current command extracts PR URLs from cross-referenced timeline events but omits the critical check: verifying those PRs are actually MERGED. This allows open or closed-unmerged PRs to incorrectly satisfy the completion proof requirement.

The guidance states "If ANY source confirms a merged PR" but the command never checks the PR's merge state. GitHub timeline cross-references only establish a link—not merge status.

Corrected approach

-3. **Issue cross-reference** — check the linked issue for PR references in comments:
+3. **Issue cross-reference** — check the linked issue timeline for cross-referenced PRs, verify merge state:

-  gh api repos/<owner/repo>/issues/<issue_number>/timeline --jq '[.[] | select(.event=="cross-referenced") | .source.issue.pull_request.html_url // empty] | unique[]'
+  gh api repos/<owner/repo>/issues/<issue_number>/timeline \
+    --jq '[.[] | select(.event=="cross-referenced" and .source.issue.pull_request != null) | .source.issue.number // empty] | unique[]' \
+  | while read -r pr; do
+      gh pr view "$pr" --repo <owner/repo> --json mergedAt -q 'if (.mergedAt != null) then . else empty end'
+    done

This requires filtering cross-referenced events for actual PRs, then verifying mergedAt is populated (indicating merged state).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/reference/planning-detail.md around lines 98 - 105, The
cross-reference extraction command only collects PR URLs and doesn't verify
merge state; update the step that runs the gh timeline query (the command
starting with "gh api repos/<owner/repo>/issues/<issue_number>/timeline --jq
...") to (1) extract actual PR identifiers (e.g.
.source.issue.pull_request.number or URL -> PR number) and (2) for each
candidate PR call the pulls API (gh api repos/<owner/repo/pulls/<pr_number> --jq
'.merged_at' or equivalent) and accept the PR as evidence only if merged_at is
non-empty/true; ensure the docs explicitly state using the pulls endpoint to
confirm merged state rather than relying solely on cross-referenced timeline
events.

✅ Addressed in commit 44c353c

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[marcusquinn]

Additional Review Feedback (PR #2423)

Reviewers: coderabbit
Findings: 1
Max severity: critical

---

CRITICAL: coderabbit (coderabbitai[bot])

File: .agents/reference/planning-detail.md:105
⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat -n .agents/reference/planning-detail.md | sed -n '95,110p'

Repository: marcusquinn/aidevops

Length of output: 1368

---

🏁 Script executed:

# Verify the exact gh-cli syntax and API structure
gh api --help 2>&1 | head -20

Repository: marcusquinn/aidevops

Length of output: 1199

---

🌐 Web query:

GitHub CLI gh api timeline cross-referenced events pull_request merge state

💡 Result:

To answer “was the cross‑referenced PR eventually merged?” you generally need (a) the timeline cross-referenced events, then (b) a PR lookup for merged/mergedAt (or PR timeline merged event).

Option A (REST): issue/PR timeline → find cross-referenced → fetch PR → check merge

1. Get timeline items (includes cross-referenced, merged, etc.) from the issue/PR:

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/timeline

GitHub documents this endpoint as “List timeline events for an issue” (GET /repos/{owner}/{repo}/issues/{issue_number}/timeline). [1]

2. Filter to just cross-referenced events and extract the referenced item:

gh api -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/timeline \
  --jq '.[] | select(.event=="cross-referenced") | .source.issue'

In REST timeline events, cross-referenced includes a source object (the issue/PR that created the cross-reference). GitHub’s “issue event types” docs describe the cross-referenced event shape and that the source is always an issue object; you can detect whether it’s a PR via the presence of source.issue.pull_request. [2]

3. If it’s a PR, fetch the PR and read merge state:

# if you have PR number:
gh api -H "X-GitHub-Api-Version: 2022-11-28" /repos/OWNER/REPO/pulls/PR_NUMBER \
  --jq '{state, merged, merged_at}'

# if you only have the REST URL in source.issue.pull_request.url:
gh api -H "X-GitHub-Api-Version: 2022-11-28" "$(gh api ... --jq '.source.issue.pull_request.url')" \
  --jq '{state, merged, merged_at}'

Option B (GraphQL): timelineItems(CROSS_REFERENCED_EVENT) → inline PR merged/state

GraphQL can return cross-referenced items and, when the source is a PR, inline merged (and optionally mergedAt, state):

gh api graphql -f query='
query($owner:String!, $name:String!, $number:Int!) {
  repository(owner:$owner, name:$name) {
    issueOrPullRequest(number:$number) {
      ... on Issue {
        timelineItems(first:100, itemTypes:CROSS_REFERENCED_EVENT) {
          nodes {
            ... on CrossReferencedEvent {
              source {
                ... on PullRequest { number title state merged mergedAt }
              }
            }
          }
        }
      }
    }
  }
}' -F owner=OWNER -F name=REPO -F number=ISSUE_NUMBER

The timelineItems(... itemTypes: CROSS_REFERENCED_EVENT) + ... on CrossReferencedEvent { source ... on PullRequest { merged }} pattern is commonly used for exactly this. [3]

Note: you may also see a direct merged timeline event

GitHub’s issue/PR timeline event types also include a merged event for PRs. [2] So, depending on your goal, you can either:

• look for a merged event in the PR’s own timeline, or
• compute “merged?” from the PR fields (merged / merged_at / mergedAt) after discovering it via cross-referenced.

Sources: GitHub REST timeline endpoint docs [1]; GitHub “issue event types” (includes cross-referenced, merged, and the source.issue.pull_request hint) [2]; GraphQL example using timelineItems + CROSS_REFERENCED_EVENT with source ... on PullRequest { merged } [3].

---

🌐 Web query:

gh pr view json state MERGED syntax documentation

💡 Result:

state is a valid JSON field for gh pr view, and its value can be OPEN, CLOSED, or MERGED. You must request it via --json (comma-separated fields), then optionally filter with --jq. [1], [2]

Examples:

# Print just the state (e.g., "MERGED")
gh pr view 123 --json state --jq .state

# Boolean “is merged” check (robust for scripting)
gh pr view 123 --json mergedAt --jq '(.mergedAt != null)'

# Get multiple fields
gh pr view 123 --json state,mergedAt,closedAt --jq '{state, mergedAt, closedAt}'

Sources: GitHub CLI manual for gh pr view (JSON fields include state, mergedAt, etc.) [1] and GitHub CLI formatting docs for --json + --jq usage. [2]

---

Step 3 fallback must verify merged state, not just presence of cross-referenced PRs

The current command extracts PR URLs from cross-referenced timeline events but omits the critical check: verifying those PRs are actually MERGED. This allows open or closed-unmerged PRs to incorrectly satisfy the completion proof requirement.

The guidance states "If ANY source confirms a merged PR" but the command never checks the PR's merge state. GitHub timeline cross-references only establish a link—not merge status.

Corrected approach

-3. **Issue cross-reference** — check the linked issue for PR references in comments:
+3. **Issue cross-reference** — check the linked issue timeline for cross-referenced PRs, verify merge state:

-  gh api repos/<owner/repo>/issues/<issue_number>/timeline --jq '[.[] | select(.event=="cross-referenced") | .source.issue.pull_request.html_url // empty] | unique[]'
+  gh api repos/<owner/repo>/issues/<issue_number>/timeline \
+    --jq '[.[] | select(.event=="cross-referenced" and .source.issue.pull_request != null) | .source.issue.number // empty] | unique[]' \
+  | while read -r pr; do
+      gh pr view "$pr" --repo <owner/repo> --json mergedAt -q 'if (.mergedAt != null) then . else empty end'
+    done

This requires filtering cross-referenced events for actual PRs, then verifying mergedAt is populated (indicating merged state).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/reference/planning-detail.md around lines 98 - 105, The
cross-reference extraction command only collects PR URLs and doesn't verify
merge state; update the step that runs the gh timeline query (the command
starting with "gh api repos/<owner/repo>/issues/<issue_number>/timeline --jq
...") to (1) extract actual PR identifiers (e.g.
.source.issue.pull_request.number or URL -> PR number) and (2) for each
candidate PR call the pulls API (gh api repos/<owner/repo/pulls/<pr_number> --jq
'.merged_at' or equivalent) and accept the PR as evidence only if merged_at is
non-empty/true; ensure the docs explicitly state using the pulls endpoint to
confirm merged state rather than relying solely on cross-referenced timeline
events.

✅ Addressed in commit 44c353c

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[johnwaldo]

Recommend closing — cosmetic finding. 'decision making' vs 'decision-making' hyphenation in planning-detail.md is a style preference, not a functional issue.

[alex-solovyev]

Additional Review Feedback (PR #3893)

Reviewers: gemini
Findings: 1
Max severity: medium

---

MEDIUM: gemini (gemini-code-assist[bot])

File: .agents/reference/planning-detail.md:98

There appears to be a contradiction in the auto-subtasking threshold. The new 'Estimation Calibration' section on line 93 states ~2h is the threshold for auto-subtasking, but the 'Auto-Subtasking' section on line 98 still refers to the old >4h threshold and mentions a range of ~30m-4h. Please update the Auto-Subtasking section to align with the new calibrated estimates for consistency.

(t1188.2): Tasks with estimates >2h that have no existing subtasks are flagged as `needs-subtasking` in the eligibility assessment. The AI reasoner uses `create_subtasks` to break them into dispatchable units (~30m-2h each) before attempting dispatch. Tasks that already have subtasks are flagged as `has-subtasks` — the supervisor dispatches the subtasks instead.

View comment

---

Appended by quality-feedback-helper.sh scan-merged (cross-PR file dedup, t1411).

[marcusquinn]

Dispatching worker.

• Model: sonnet (default round-robin)
• Branch: bugfix/t3213-planning-detail-high
• Scope: Fix high-severity review feedback on .agents/reference/planning-detail.md from PR refactor: AI-driven task lifecycle engine replacing hardcoded bash heuristics #2107
• Attempt: 1 of 1
• Direction: Address all high-severity review findings from the original PR review

[github-actions]

Completed via PR #4686. Task t3213 merged to main.