fix(workflows): apply the missing-specification guard to the bundled default

[Wirasm]

Summary

• Problem: fix(workflows): stop the issue-fix workflow on a missing specification #2499 fixed the bridge-artifacts warn-and-continue branch in the experimental copy only. The bundled archon-fix-github-issue.yaml — the workflow users actually get — carried the identical echo "WARNING: … implement may fail" + exit 0, so the refusal-reads-as-success path was still shipped.
• Why it matters: an AI node that declines its task still exits 0. If investigate/plan produce no artifact, the bundled workflow continues into implement with nothing to implement, and unlike the experimental copy it has no assert-implemented backstop — it proceeds to validate and create-pr.
• What changed: the same hard stop, plus capture-pr-number now clears .pr-number/.pr-url before validating so pr-exists reads the current attempt's result.
• What did NOT change (scope boundary): the bundled workflow's review tail needs no pr-exists gate — its synthesize uses trigger_rule: one_success, so a run that dies before create-pr leaves every reviewer skipped, zero successes, and the tail skips on its own. Only the experimental copy (which uses all_done) needed that gate. Adding an assert-implemented backstop to the bundled workflow is left to Epic: bundled defaults overhaul — curated 8-workflow SDLC set, 36→13 commands, code/agent separation #2123.

UX Journey

Before

  investigate ──(declines)──▶ exit 0 ✓
  bridge-artifacts ──"WARNING: … may fail"──▶ exit 0 ✓
  implement ──▶ validate ──▶ create-pr     ← no backstop in the bundled copy

After

  bridge-artifacts ──[no artifact? exit 1]──▶ *run stops*

Architecture Diagram

Before

  [experimental] bridge-artifacts (exit 1)   ← fixed in #2499
  [bundled]      bridge-artifacts (exit 0)   ← same bug, still shipped

After

  [experimental] bridge-artifacts (exit 1)
  [~][bundled]   bridge-artifacts (exit 1)   ← parity
  [~] capture-pr-number ──rm -f .pr-number──▶ validate ──▶ write

Connection inventory:

From	To	Status	Notes
bridge-artifacts (bundled)	implement	modified	unreachable with no specification
capture-pr-number	pr-exists	modified	.pr-number now reflects only the current validation
bundled-defaults.generated.ts	archon-fix-github-issue.yaml	unchanged	regenerated

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: workflows
• Module: workflows:defaults

Change Metadata

• Change type: bug
• Primary scope: workflows

Linked Issue

• Closes #
• Related fix(workflows): stop the issue-fix workflow on a missing specification #2499, feat(workflows): isolate AI-node skills and MCPs behind explicit YAML declarations #2498

Validation Evidence (required)

bun run cli validate workflows   # 66 valid, 0 with errors
bun run generate:bundled         # 37 commands, 21 workflows

• Evidence: found in CodeRabbit's review of fix(workflows): stop the issue-fix workflow on a missing specification #2499 and confirmed by reading .archon/workflows/defaults/archon-fix-github-issue.yaml:163-165 — byte-identical warn branch.
• Skipped: type-check/test — only the regenerated bundle is TypeScript, and check:bundled verifies it in CI.

Security Impact (required)

• New permissions/capabilities? No — narrows what a run will do.
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No (the rm -f targets two files the same node writes, inside $ARTIFACTS_DIR)

Compatibility / Migration

• Backward compatible? Yes for any run producing a specification; a run producing none now fails at bridge-artifacts rather than continuing.
• Config/env changes? No
• Database migration needed? No

Human Verification (required)

• Verified scenarios: read the bundled workflow's full node graph to confirm the tail differs from the experimental copy (one_success vs all_done) before deciding the pr-exists gate was not needed there; confirmed the bundled copy has no assert-implemented.
• Edge cases checked: trigger_rule: one_success on bridge-artifacts is unchanged, so the plan-path (non-bug issues, investigate skipped) still bridges plan.md → investigation.md.
• Not verified: end-to-end run of the bundled workflow. The experimental copy is what's under live test right now (run 68b832f4); the changed lines are identical.

Side Effects / Blast Radius (required)

• Affected: archon-fix-github-issue (bundled, ships to all users) and capture-pr-number in the experimental copy.
• Potential unintended effects: a bundled run whose investigate writes its artifact outside $ARTIFACTS_DIR now hard-fails instead of continuing. Intended.
• Guardrails: bun run cli validate workflows covers all 66.

Rollback Plan (required)

• Fast rollback: git revert <sha> then bun run generate:bundled.
• Feature flags: none.
• Observable failure symptoms: issue-fix runs failing at bridge-artifacts with a populated $ARTIFACTS_DIR.

Risks and Mitigations

• Risk: rm -f runs before the gh pr view check, so a transient gh failure now leaves no .pr-number where a stale one previously existed.
  • Mitigation: that is the intent — capture-pr-number already exits 1 in that case, so the file's absence and the node's failure agree instead of contradicting.

Summary by CodeRabbit

• Bug Fixes
  • Workflow processing now stops with a clear failure when required investigation or planning documents are missing, instead of continuing with a warning.
  • Pull request metadata is refreshed before use, preventing outdated pull request numbers or URLs from being reused across workflow runs.

[coderabbitai]

📝 Walkthrough

Walkthrough

The workflows now fail when required investigation artifacts are missing and remove stale pull request metadata before recording current branch information.

Changes

Workflow artifact correctness

Layer / File(s)	Summary
Required artifact validation .archon/workflows/defaults/archon-fix-github-issue.yaml	bridge-artifacts emits errors and stops when neither investigation.md nor plan.md exists.
Pull request metadata reset .archon/workflows/experimental/archon-fix-github-issue-experimental.yaml	capture-pr-number deletes existing .pr-number and .pr-url artifacts before writing current pull request metadata.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• coleam00/Archon#2262: Modifies the same experimental workflow and its pull request metadata handling.
• coleam00/Archon#2404: Extends deterministic pull request metadata handling in capture-pr-number.
• coleam00/Archon#2499: Modifies workflow behavior for missing specification artifacts.

Suggested labels: bug, area: workflows

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the workflow fix and the bundled default as the primary change.
Description check	✅ Passed	The description follows the required template and provides scope, diagrams, validation, risks, security, compatibility, and rollback details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/bundled-issue-workflow-guards

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml:
- Around line 526-530: Move the .pr-number and .pr-url removal into a dedicated
always-run node that executes before create-pr, including when upstream
validation fails or is skipped. Update the pr-exists condition to require
evidence that the current attempt successfully reset or captured the PR
artifacts, rather than relying on file presence alone; ensure cleanup failure
prevents stale artifacts from being treated as current.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 986b5fd4-f11e-483b-8ed5-8eb23f1f716a

📥 Commits

Reviewing files that changed from the base of the PR and between d91841b and ea715e4.

⛔ Files ignored due to path filters (1)

• packages/workflows/src/defaults/bundled-defaults.generated.ts is excluded by !**/*.generated.*

📒 Files selected for processing (2)

• .archon/workflows/defaults/archon-fix-github-issue.yaml
• .archon/workflows/experimental/archon-fix-github-issue-experimental.yaml

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Run stale-PR cleanup on every failure path.

Because capture-pr-number depends on create-pr at Line 540 without an all_done trigger, a failed or skipped create-pr skips this cleanup. In .archon/workflows/experimental/archon-fix-github-issue-experimental.yaml, Lines 555-563 then treat an old .pr-number file as current, so synthesize can run against a stale PR. An unchecked rm -f also does not prove that both files were removed.

Move cleanup to an always-run node before create-pr, and make pr-exists require a successful current-attempt reset or capture instead of file presence alone. This preserves the supplied workflow contract that .pr-number represents the current attempt.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.archon/workflows/experimental/archon-fix-github-issue-experimental.yaml
around lines 526 - 530, Move the .pr-number and .pr-url removal into a dedicated
always-run node that executes before create-pr, including when upstream
validation fails or is skipped. Update the pr-exists condition to require
evidence that the current attempt successfully reset or captured the PR
artifacts, rather than relying on file presence alone; ensure cleanup failure
prevents stale artifacts from being treated as current.