[Hafeok]

Refs #170. This PR implements the revised plan for option 2 (design change), as Emil approved it with three answers and one change. It also adds the bridge's GitHub environment, requested before landing. The record quotes each request verbatim.

The first six commits (c676b48 to 621fa59) are the runner design as first approved. The rework sits on top, and no history was rewritten. This PR changes a workflow, so it was written in a normal key-holding session.

What changes

• ADR-0014, rewritten, still proposed (ADR-0014-routine-issue-sessions.md).
  • The design. A Claude Code routine in Emil's key-holding environment does the work. A workflow only starts it, through the routine's API trigger.
  • The secrets. There are only ROUTINE_FIRE_URL and ROUTINE_FIRE_TOKEN. They live in the GitHub environment claude-routine, whose deployment branches are limited to main, never as repository secrets, so no workflow on another branch can read the token. Issue and comment starts run from main, so they are admitted.
  • The boundary is structural. Comments sessions post carry performed_via_github_app.slug == "claude"; comments Emil types carry none. The evidence on Issue sessions: the Claude Code action, started by the claude label (new ADR) #170 is recorded. Both the bridge's if: and the session's start check require performed_via_github_app == null, with the no-@claude rule as a second line of defence.
  • Limits. The fire API is experimental. A routine takes 30 starts an hour and an account 100; beyond that the API returns 429 with Retry-After. There is no idempotency; duplicates are contained by curl never retrying, the per-issue concurrency group, and the session's own duplicate check.
  • Alternatives. The runner design is rejected, with its six findings kept as the record. Polling is rejected for its latency. The routine's own Issue trigger is rejected because it offers no actor filter and no comment events. The earlier claim that a scheduled task has no signing key is corrected.
• .github/workflows/claude.yml, the bridge: one job in environment: claude-routine, with contents: read and a 5-minute timeout. It sends one curl with no retry and no anthropic-beta header, builds the payload with jq from env:, and keeps the response out of the public log.
• eng/routines/issue-session.md: the routine's prompt, version 1, which Emil pastes into the routine.
• claude-workflow, the gate, now reads both the workflow and the prompt. It fails when they disagree on the actor, label, prefixes or rule sections, or when the job lacks exactly environment: claude-routine. selftest plants 21 cases.
• AGENTS.md: how a session starts and is approved by hand, where its prompt and secrets live, and which issues must not get the label.
• releases/v0.8.0-preview.3.yaml, with accepted-by left for Emil.
• The record, docs/traceability/2026-11-06-issue-170-issue-sessions.md, in three parts.

Checks

• Each commit on its own, in a clean worktree: commits, adr-shape, adr-text, no-toolchain, claude-workflow and selftest all pass.
• Build, tests and smoke, at 645ad60: the build has 0 warnings and all 43 tests pass, and the linux-x64 AOT publish and smoke test pass. No source changed after that commit.
• The fire step, run against a local stand-in: on 200 it sends exactly the three headers and logs only the issue and event; on 429 it fails and prints the API's error. A value with a quote, a backslash and a newline arrives intact in valid JSON.
• Signatures: GitHub reports every commit verified, as Claude (Emil), attributed to Hafeok.

For Emil

1. Create the GitHub environment claude-routine before merging: deployment branches limited to main, no required reviewers. A job that names a missing environment creates it with no rules.
2. Create the routine with an API trigger only, paste the prompt, and generate its token.
3. Add the two secrets to the environment.

The first test run confirms that performed_via_github_app reaches the if:.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NbWSYRYCm8wULG3wF2NvgE

[Hafeok]

Change of design before I merge: option 2. A run no longer happens on a GitHub runner. It is a Claude Code routine in my cloud environment, which already holds the agent's signing key and the login. GitHub only starts it, through the routine's API trigger: POST https://api.anthropic.com/v1/claude_code/routines/{id}/fire, with an optional text body (docs: https://platform.claude.com/docs/en/api/claude-code/routines-fire). Routines' own GitHub trigger covers pull request and release events only, so the Action stays as a thin bridge for issues.

Please revise and post a new plan on #170 before changing the PR.

• claude.yml:

  • keep the if: exactly: only Hafeok, the claude label, or an issue comment starting @claude;
  • keep the concurrency group and a short timeout;
  • the job becomes one curl step to secrets.ROUTINE_FIRE_URL, with Authorization: Bearer ${{ secrets.ROUTINE_FIRE_TOKEN }} and anthropic-version: 2026-10-21. Its text carries the repository, the issue number, the event, and the comment id and author;
  • remove claude-code-action, CLAUDE_CODE_OAUTH_TOKEN and AGENT_SSH_SIGNING_KEY;
  • permissions drop to contents: read, since the job no longer writes anything;
  • pin actions/checkout only if the step needs it.

• The routine's prompt:

  • a committed file, eng/routines/issue-session.md, which I paste into the routine. It holds D5's rules as they now stand in claude_args, plus "the text you are started with names the issue: read it and its comments with gh";
  • a gate check that the workflow and that file agree on the actor and the plan-first rules, if that can be checked without duplicating the text.

• The ADR:

  • Rewrite it around the routine.
  • Signing: the session signs as today, in the environment.
  • The PR: the session opens it itself, so the gates run. Drop the close-and-reopen consequence.
  • The secrets: only the routine's URL and token. The token starts one routine and grants no read access; generating a new one revokes the old.
  • Limits:
    • the fire API is experimental;
    • each routine accepts 30 starts an hour, and further starts are dropped;
    • there is no idempotency, so a retried webhook starts two sessions. Say how the concurrency group and the session's own check of the newest plan comment contain that.
  • Alternatives:
    • anthropics/claude-code-action on a runner: rejected because the login and the key would have to be copied to GitHub. Keep finding 1 to 6 as the record of why;
    • the routine's own schedule trigger, polling hourly: rejected for its latency;
    • correct the earlier "a scheduled task has no signing key", which is wrong for a routine in my environment.

• The claude-workflow gate and its plants:

  • exactly one curl step to secrets.ROUTINE_FIRE_URL;
  • no other uses: except pinned checkout;
  • the actor checks present;
  • no secret but the two;
  • a timeout present.

  Plant the old action, and a third secret.

• AGENTS.md: how a run starts and where its prompt lives.

What I do after the revised plan is approved: create the routine in claude.ai/code/routines (repository product-cli, my key-holding environment, an API trigger), generate its token, and add ROUTINE_FIRE_URL and ROUTINE_FIRE_TOKEN. Keep the ADR number and version handling as before.

---

Generated by Claude Code

[Hafeok]

Approved the revised plan (6790423943) with the answers given; implemented in #171

[Hafeok]

Approved at b49df86