#503 Implement .claude Config Tickets From an Operator Session

[b-at-neu]

Closes #503

SESSION REQUIRED: touches CLAUDE.md / .claude/** — a dispatched agent can't edit those

Summary

Adds a third route through the pipeline for tickets that can't be handed to a dispatched agent at all. Today that means anything touching CLAUDE.md or .claude/**, where the harness denies a subagent's Edit and settings.json cannot grant it back — but the mechanism is built around the routing, not the cause, so a future category reuses it by supplying a different reason.

plan-agent marks such a plan SESSION REQUIRED; the cockpit finds the marker and announces the command instead of dispatching stages 2 and 4. A new /implement skill runs those two stages in the operator's own named session, in a dedicated worktree, by reading and following the unmodified impl-agent.md / revise-agent.md plus a short, explicit list of subagent-only overrides.

Stages 1 and 3 are untouched — plan-agent and review-agent are read-only and work through gh, so a session-required ticket is not out of the pipeline. refresh branch still dispatches to revise-agent (a rebase and force-push edit no files).

The trigger label stays on the item and the skill performs the same label swaps the agent files already specify, so there are no new trigger semantics and recovery is still "re-apply the trigger". The cockpit gains one rule: the SESSION REQUIRED marker suppresses dispatch — a deliberate deviation from "a trigger label always means dispatch", documented as such.

One marker, no label

The signal is a single literal string, same rendering, on both surfaces:

> **SESSION REQUIRED:** touches `CLAUDE.md` / `.claude/**` — a dispatched agent can't edit those

Surface	Written by	Where
Issue	plan-agent	First line of the plan body, before ## Overview
PR	/implement	Directly under Closes #N

There is deliberately no label. The cockpit reads the marker from the body field of the trigger query it already runs (--json number,title,body), so the check costs no extra call and there is nothing to keep in sync. The string is the contract; the reason after the colon is free text and is the part that generalizes.

Bootstrap note: #503 is itself session-required and /implement did not exist yet, so this was implemented by hand from an operator session following impl-agent.md — the workflow being codified. This PR description carries the marker, as /implement would have written it.

Changes

• .claude/skills/implement/SKILL.md — new. Name the session, record the main checkout, resolve the stage from labels, create the worktree, follow the agent file, carry the marker into the PR, apply the six overrides, hand off.
• .claude/agents/plan-agent.md — emit the marker when ## Changes needs it, in revision mode too.
• .claude/skills/pipeline/SKILL.md — body added to the two trigger queries; a safety rail forbidding impl/revise dispatch for a marked item; announcement copy; status reporting.
• .claude/docs/PIPELINE.md — new "Session-required tickets" section (harness constraint, why settings.json can't grant it, the marker table, the route, the invariant deviation, session naming, the worktree requirement); the marker in the plan format; a Stages-table note; a runbook row.
• .claude/skills/worktree-clean/SKILL.md — impl-* worktrees are in scope alongside agent-*.
• CLAUDE.md — one line under "Worktrees & local dev" pointing at the new section.

Testing plan

• In the cockpit, work on #395 (interactive gate). The resulting plan's first line is the SESSION REQUIRED marker with a reason. Negative control: a source-only ticket's plan has no marker.
• Approve Document the Permissions Model #395's plan → the issue gets plan approved and no extra label; no impl-agent is dispatched (TaskList shows none); the announcement gives both claude -n "#395: …" and /implement 395.
• Next cockpit tick re-reports nothing for Document the Permissions Model #395 (announced once), and status lists it under the human-gated group tagged SESSION REQUIRED, with both commands.
• Launch claude -n "#395: <short name>" in a separate session and run /implement 395: the name shows in the prompt box / terminal title, the skill's first line re-states it, the worktree appears at .claude/worktrees/impl-395 on branch 395-…, the main checkout's working tree stays clean throughout (git status there), and labels go plan approved → in progress → pr opened.
• The resulting PR: base dev, title #395 …, body has Closes #395 and the marker directly under it, plus a Testing plan; assignee = the issue's assignee; label ready for review; commit subject matches #395 <lowercase imperative> with the Co-Authored-By trailer.
• The cockpit dispatches review-agent for that PR unchanged and posts a real review.
• Revise path: label the PR needs revision → the cockpit reads the marker from the PR body and announces /implement <pr>, dispatching nothing. Run it; the PR goes revising → ready for review and the addressed threads are resolved.
• Negative control: a normal source ticket at plan approved still auto-dispatches impl-agent; running /implement on it raises the double-dispatch confirmation first.
• Marker-stripped control: delete the marker line from a marked PR's description → the cockpit dispatches revise-agent again. Confirms the body is genuinely the signal.
• Self-reference: a session-required ticket that edits .claude/agents/impl-agent.md — the session's own behaviour doesn't shift mid-run, and the edit lands only on the worktree copy.
• /worktree-clean lists and reclaims .claude/worktrees/impl-395 after the PR merges.

Automated checks

npm run prettier:check, npm run eslint:check, npm run tsc:check all pass. npm run test needs Postgres (unavailable locally), so npm run test:unit was run instead: 146 passed. The diff is documentation and skill/agent instructions only — no runtime code.

Notes

• The marker is a convention, not an enforced one. Anyone editing a PR description can drop it, and the cockpit would then dispatch. That is the tradeoff taken for having one mechanism instead of two; the marker-stripped control above tests exactly this path.
• Override drift is the long-term risk: the agent files can change without the override list noticing. Mitigated by keeping the list short, quoting each rule it overrides, and putting it in exactly one place — the skill — with PIPELINE.md pointing at it rather than restating it.
• Session naming is advisory. -n is set at launch and a running session can neither read nor change its own display name, so the skill can only tell the operator the string; the cockpit's pre-filled command is what makes it happen.
• npm ci in the worktree costs minutes and disk even for a markdown-only ticket. Kept anyway — it makes the CI gate real for mixed tickets and removes an override. /worktree-clean is the reclamation path.
• Open probe, deliberately not blocking: whether claude --agent impl-agent (the runbook's manual escape hatch) carries the same restriction is untested; PIPELINE.md records it as unverified. If a future Claude Code version lifts the harness restriction, the whole route can be deleted — the marker is the only thing to unwind.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aplio	Ready	Preview	Aug 20, 2026 2:41am

[b-at-neu]

Code Review — Cycle 1 · needs revision

1 open — 1 🟠 Medium (see inline)

[b-at-neu]

Revision — Cycle 1

Fixed R1-M1: added body to the --json field lists in step 3's gh pr view/gh issue view calls, so the SESSION REQUIRED marker check right after has something to inspect. Commit 70551f0.

[b-at-neu]

Code Review — Cycle 2 · approved

0 open — prior R1-M1 resolved, no regressions

[b-at-neu]

Code Review — Cycle 3 · approved

0 open — prior R1-M1 stayed resolved, no regressions in the post-approval commit (docs/prose clarifications only)