documenteer 2.4.1__tar.gz → 2.5.0b2__tar.gz

documenteer-2.5.0b2/.agents/skills/project-mechanics/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: project-mechanics
+description: Project-specific build/test/lint/typing commands for this repo. Read this skill at the start of any phase that runs validation (`stoker-work`, `stoker-fixup`, `stoker-rebase`).
+---
+
+# Project mechanics
+
+This file is the source of truth for how this repo runs tests, lint,
+and type-checking. Profile-shipped phase skills read it at the start
+of each phase and use the named commands verbatim.
+
+Tasks run through nox (via nox-uv). Invoke nox through uv so the runner
+group is provisioned automatically: `uv run --only-group=nox nox ...`.
+The `test`, `typing`, and `demo` sessions are parametrized over both
+Python (3.12, 3.13) and Sphinx (8, 9, dev), so their session IDs carry
+both factors, e.g. `test-3.13(sphinx='8')`. uv furnishes the requested
+interpreter on demand. Run `nox -l` to confirm the exact IDs.
+
+## Test commands
+
+- `focused_test`: `uv run --only-group=nox nox -s "test-3.13(sphinx='8')" -- -k <test_name>` (posargs after `--` pass through to pytest, so you can also use `uv run --only-group=nox nox -s "test-3.13(sphinx='8')" -- tests/foo_test.py::test_bar`)
+- `complete_test`: `uv run --only-group=nox nox -s "test-3.13(sphinx='8')" "test-3.13(sphinx='9')"`
+
+## Coverage
+
+Coverage is opt-in. The `test` session runs plain pytest by default, so no
+`.coverage*` files are written during normal validation. To collect coverage
+and print a combined report across the test sessions, set the
+`DOCUMENTEER_COVERAGE` environment variable, e.g.
+`DOCUMENTEER_COVERAGE=1 uv run --only-group=nox nox -s "test-3.13(sphinx='8')" "test-3.13(sphinx='9')"`.
+The `coverage-report` session (combine + report) is triggered automatically
+via `session.notify` when `DOCUMENTEER_COVERAGE` is set, and can also be run
+directly to re-display the last combined report. CI instead sets
+`DOCUMENTEER_COVERAGE_NO_COMBINE` in each matrix cell to skip the
+per-invocation combine and upload raw `.coverage.*` data for a central
+`coverage-combine` job; that flag is CI-only and not needed for local runs.
+
+## Lint
+
+- `lint_touched`: `uv run --only-group=lint prek run --files {files}`
+- `lint_all`: `uv run --only-group=nox nox -s lint`
+
+## Typing
+
+- `typing`: `uv run --only-group=nox nox -s "typing-3.13(sphinx='8')"`
+
+## Final validation
+
+End-of-task validation runs `uv run --only-group=nox nox -s
+"test-3.13(sphinx='8')" "test-3.13(sphinx='9')"` + `uv run --only-group=nox nox -s
+lint` + `uv run --only-group=nox nox -s "typing-3.13(sphinx='8')"` in that
+order, in the foreground, plus `uv run --only-group=nox nox -s
+"demo-3.13(sphinx='9')"` (end-to-end rst/md/ipynb demo technote builds)
+and `uv run --only-group=nox nox -s docs` (Documenteer's own Sphinx docs
+build).
+
+The full Python × Sphinx matrix (3.12/3.13 × Sphinx 8/9), `nox -s
+docs-linkcheck` (linkcheck), and `nox -s packaging` (build + twine
+check) are CI's responsibility, not the in-iteration gate.
+
+<!-- stoker-onboarded-from: github.com/lsst-sqre/rubin-stoker//profile@main
+     prompt-hash: 348ec538f8f7f6fa42da3569d855eab629174668ef28ea225f8b37511daac9d4
+     onboarded-at: 2026-06-23T21:19:20Z -->

documenteer-2.5.0b2/.agents/skills/stoker-create-pr/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: stoker-create-pr
+description: Create or update a pull request with a Summary / Validation steps / References body, including `Closes #<task_issue>`, `PRD: #<parent_prd>`, and `Jira: <url>` trailers, and a `DM-XXXXX:`-prefixed title for ticket branches. Use when invoked from `stoker-implement`'s PR step or when the user asks to create a PR, open a pull request, or update a PR body — and you are working in a Rubin stoker-installed repo.
+---
+<!-- stoker-managed: skills:.agents/skills/stoker-create-pr/SKILL.md:f4cd55824c7492db -->
+
+# stoker-create-pr — the Rubin PR-creation primitive
+
+Create a pull request (or update one that already exists on this
+branch) using a fixed body template that the AFK loop and humans
+both produce identically. This skill is the single source of truth
+for the Rubin profile's PR shape: title format, body sections, and
+the `Closes #N` / `PRD: #N` / `Jira: <url>` trailer conventions.
+
+`stoker-implement` delegates here for its PR step. Humans invoke it
+directly for hand-driven PRs.
+
+This is the Rubin variant of the default `stoker-create-pr`. It keeps
+the default's create-vs-update logic and multi-task `Closes #N`
+regeneration verbatim, and layers two Rubin conventions on top: a
+`DM-XXXXX:`-prefixed title for `tickets/DM-XXXXX...` branches, and a
+`Jira: <url>` line in References.
+
+## Workflow
+
+### 1. Gather context
+
+Collect these values. Use the first available source for each:
+
+- **Task issue** — the `prd-task` whose work this PR delivers. Sources
+  in order: current conversation context (e.g. the implement-phase
+  prompt) > auto-detect by branch (see below) > ask the user
+  (optional — solo PRs without a tracked task are allowed).
+- **Parent PRD** — the task issue's `### Parent PRD` field, when the
+  task is part of a PRD breakdown. Optional.
+- **Branch** — the current branch (`git branch --show-current`).
+- **Jira key** — sources in order: current conversation context >
+  the branch name when it matches `tickets/<KEY>...` (the `<KEY>`
+  segment, e.g. `tickets/DM-12345-add-foo` → `DM-12345`) > the task
+  issue's `### Jira Key` field > none. Optional — `u/<login>/<desc>`
+  branches and ticket-less PRDs have no Jira key.
+- **Jira URL** — sources in order: the task issue's `### Jira URL`
+  field > constructed as `https://rubinobs.atlassian.net/browse/<key>`
+  when a Jira key is known > none.
+
+#### Auto-detecting the task issue
+
+If no task is in context, search by branch:
+
+```
+gh issue list --label prd-task --state open --json number,title,body --limit 50
+```
+
+Find the issue whose `### Branch` field matches the current branch
+name. Extract `### Parent PRD`, `### Jira Key`, and `### Jira URL`
+from that issue's body.
+
+### 2. Push the branch
+
+```
+git status -sb
+```
+
+If the branch has no remote tracking branch or has unpushed commits:
+
+```
+git push -u origin HEAD
+```
+
+If the push fails (non-fast-forward, permission denied, network),
+**do not retry or rebase from this skill**. Surface the failure to
+the caller (`stoker-implement` routes to the stuck path; humans get an
+error message).
+
+### 3. Detect existing PR
+
+```
+gh pr list --head <branch> --json number,title,body,state,baseRefName --limit 1
+```
+
+Three cases:
+
+- **No existing PR** → create a new one (step 4).
+- **Existing PR, state OPEN** → regenerate the body from the branch's
+  cumulative scope (step 5).
+- **Existing PR, state CLOSED or MERGED** → skip PR handling. Log
+  the fact and return.
+
+### 4. Create a new PR
+
+**Title.** Derive it from the branch's cumulative scope. This is the
+canonical title rule; step 5 regenerates the title under the same rule
+when a PR already exists.
+
+- When a **Jira key** is known, prefix the title: `DM-XXXXX: <concise
+  description>`. The description is a concise summary of what this PR
+  accomplishes; keep the whole title under 70 characters.
+- With **no Jira key** (a `u/<login>/<desc>` branch or ticket-less
+  work), use a plain concise descriptive title under 70 characters.
+
+**Body.** Use the template below verbatim.
+
+```
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+<body>
+EOF
+)"
+```
+
+### 5. Update an existing OPEN PR
+
+Regenerate the **title and body** from the branch's full scope so the
+title, Summary, Validation steps, and References all reflect every task
+that has landed, not just the first. The title is regenerated here (not
+left as the first task's title) so it does not go stale as tasks stack
+onto the PR.
+
+1. Enumerate every commit since the PR's base. Use `baseRefName` from
+   the `gh pr list` JSON; do not hardcode `origin/main`:
+
+   ```
+   git log origin/<baseRefName>..HEAD --format='%H%n%s%n%b---'
+   ```
+
+2. Take the union of `Closes #N` trailers from those commits, the
+   `Closes #N` lines already in the existing PR body's References
+   section, and the currently-picked task. (`Refs #N` trailers used
+   by stuck WIP commits naturally don't surface here, so stuck work
+   never leaks into References or Summary.)
+
+3. For each unique `N`, fetch the issue:
+
+   ```
+   gh issue view <N> --json number,title,body,state
+   ```
+
+   Pull manual-QA bullets from the issue's `### Acceptance criteria`
+   field (if present) for the Validation steps section. Also re-read
+   the `### Jira Key` / `### Jira URL` fields here so the `Jira:`
+   reference stays correct after the first task.
+
+4. Compose a fresh body using the template:
+
+   - **Summary** — 1–3 bullets (up to 5 if scope is genuinely
+     diverse). Collapse multiple commits advancing the same slice
+     into one bullet.
+   - **Validation steps** — union of manual-QA items from every
+     referenced task. Drop bullets CI already covers and bullets
+     superseded by later commits.
+   - **References** — one `Closes #N` per referenced task, sorted
+     ascending; then `PRD: #<parent_prd>` (omit if none); then
+     `Jira: <url>` (omit if no Jira key). Sorted + deduped is
+     idempotent by construction.
+
+5. Regenerate the title from the same cumulative branch scope, applying
+   the same rule as step 4 — including the `DM-XXXXX:` prefix when a
+   Jira key is known, and the same <70-character limit. Do **not**
+   reuse the existing PR title; recompute it so it reflects every task
+   that has landed. All tasks on a branch share one ticket, so the
+   `DM-XXXXX:` prefix is stable across regenerations — only the
+   description after it changes.
+
+6. Apply the title and body together (`--title` and `--body` in one
+   `gh pr edit`, so the title never lags the body):
+
+   ```
+   gh pr edit <pr_number> --title "<title>" --body "$(cat <<'EOF'
+   <body>
+   EOF
+   )"
+   ```
+
+### 6. Report the URL
+
+After create or edit, print the PR URL so the caller can surface it
+to the user (or the comment-and-close steps in `stoker-implement`).
+
+## PR body template
+
+```markdown
+## Summary
+
+<1–3 bullets describing what this PR does and why, in user / PRD-
+level language. Draw ground truth from the commits on this branch;
+draw user-facing framing from the task issue title.>
+
+## Validation steps
+
+<Bulleted manual-QA checklist for verifying the change. Omit anything
+CI runs automatically (no linting, type-checking, or automated test
+suite items). Only manual verification.>
+
+## References
+
+- Closes #<task_issue>
+- PRD: #<parent_prd>   <!-- omit if no parent PRD -->
+- Jira: <jira_url>     <!-- omit if no Jira key -->
+```
+
+Rules for the References section:
+
+- Use `Closes #<task_issue>` so the task auto-closes on merge.
+- Omit the `PRD:` line if there is no parent PRD.
+- Omit the `Closes #` line if there is no task issue (a hand-driven
+  PR with no tracked task).
+- Omit the `Jira:` line if there is no Jira key.
+- For multi-task branches, include one `Closes #N` per referenced
+  task, sorted ascending. There is a single `Jira:` line per PR (all
+  tasks on a branch share one ticket).
+
+## Example output
+
+For a branch `tickets/DM-45678-run-harness-flag`:
+
+```markdown
+## Summary
+
+- Add `--harness` flag to `stoker run` so an iteration can be locked
+  to a single harness regardless of profile defaults.
+- Validate the harness name against the registered-harness registry
+  and fail fast on unknown values.
+
+## Validation steps
+
+- Run `stoker run --harness codex 1` against a fixture issue and
+  confirm the implement+review phases both invoke codex.
+- Run `stoker run --harness foo 1` and confirm it exits with a
+  non-zero code before any container work starts.
+- Run `stoker run 1` (no flag) and confirm behavior is unchanged.
+
+## References
+
+- Closes #45
+- PRD: #41
+- Jira: https://rubinobs.atlassian.net/browse/DM-45678
+```
+
+The PR title for that branch would be
+`DM-45678: Add --harness flag to stoker run`.
+
+## Notes
+
+- This skill is the PR-creation primitive shared by `stoker-implement`
+  and direct human use. Keep the body shape stable — the AFK loop's
+  multi-task PR-update logic depends on the exact section names and
+  trailer format above.
+- This skill never calls Jira. The Jira URL comes entirely from the
+  task issue's `### Jira URL` field (written interactively by
+  `stoker-prd-to-issues`) or is constructed from the key in the branch
+  name. The sandbox AFK loop is GitHub-only — it has no Jira creds,
+  MCP, or firewall egress to Jira.
+- No `Co-authored-by:` trailer (signing, if configured, is
+  self-identifying).
+- No "Files changed" section — `git show` and the GitHub UI cover
+  that.

documenteer-2.5.0b2/.agents/skills/stoker-fixup/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: stoker-fixup
+description: Apply a trusted blocking stoker-review's findings to one PR — read the latest review JSON from the PR, fix what you agree with, re-validate against this repo's project-mechanics, push, and post a follow-up comment for anything you skip. Use when invoked from the stoker fixup-phase prompt, or when the user asks to address a stoker review's findings on a PR — and you are working in a stoker-installed repo. Consumes project-mechanics (Phase 0.5 prelude) and MAY delegate to stoker-work.
+---
+<!-- stoker-managed: skills:.agents/skills/stoker-fixup/SKILL.md:af03e4d9e06dbebb -->
+
+# stoker-fixup — apply a review's findings to one PR
+
+You are the **fixup** primitive of the stoker AFK loop. A prior review
+phase posted a trusted **blocking** `stoker-review` on an open PR, and a
+selection phase picked that PR because its findings are still unaddressed
+(the review's `head_sha` still equals the PR's current head). The host
+has already checked out the PR's head branch. Your job is to address the
+review: apply the findings you agree with, re-validate, push, and explain
+anything you skip.
+
+You inspect the PR's **reviews** and its diff; you never read issue or PR
+**comments** — that is stoker's trust boundary. You may *post* a
+follow-up comment (writing is fine); you must never *read* comments.
+
+## Phase 0: Branch safety
+
+The host has already checked out the PR's head branch — confirm with
+`git branch --show-current` and verify it is **not** `main`. If you are
+somehow on `main`, stop and report the problem rather than committing
+there.
+
+## Phase 0.5: Read project mechanics
+
+Before continuing, read `.claude/skills/project-mechanics/SKILL.md`. It
+defines this repo's `focused_test` / `complete_test` / `lint_touched` /
+`lint_all` / `typing` commands and any monorepo selectors. If the file is
+missing, stop and ask the user how to run tests/lint in this repo before
+proceeding — do not guess.
+
+The phases below reference these command names verbatim. When you see
+`<lint_all>`, substitute the value from the `## Lint` section, and so on.
+
+## Phase 1: Read the review findings
+
+The PR number is in the prompt that invoked you. Read the PR's reviews
+(not its comments) and recover the latest `stoker-review` sentinel:
+
+```
+gh api /repos/<owner>/<name>/pulls/<PR_NUMBER>/reviews
+```
+
+Walk the reviews newest-first, find the most recent body containing a
+`<!-- stoker-review-begin v1 -->` … `<!-- stoker-review-end -->` block,
+and parse the fenced JSON. The `findings` array (each with `summary`,
+optional `severity` / `category` / `file` / `line_start` / `line_end` /
+`suggested_fix`) is your work list. Use `gh pr diff <PR_NUMBER>` and read
+the relevant source to understand each finding in context.
+
+## Phase 2: Apply the findings
+
+Work through the findings. For each one, decide whether you agree it
+should be fixed:
+
+- **Substantial findings** — a logic/correctness fix, a missing test, new
+  or changed behavior — warrant the full red/green/refactor discipline.
+  Delegate to the `stoker-work` skill (Phases 1–4) for those, so the fix
+  lands with a test and a clean validation fixpoint.
+- **Trivial findings** — a rename, a dead-code removal, a comment fix —
+  can be applied in place; you will re-validate in Phase 3 regardless.
+
+Keep a running list of which findings you **applied** and which you
+**skipped** (and why) — Phase 4 needs it.
+
+## Phase 3: Re-validate
+
+After applying the findings, reach a clean validation fixpoint against
+`project-mechanics` (skip this only if you applied nothing at all):
+
+1. `git add -N` any new untracked files so the full-tree tools see them.
+2. Run `<lint_all>`, then `<typing>`, then `<complete_test>`. Fix any
+   failure before continuing.
+3. If anything auto-fixed code, fixpoint-loop on `<lint_touched>` over the
+   touched files until it exits clean.
+4. `git reset HEAD` the intent-to-add files so the commit step stages
+   with intentionality.
+
+If validation cannot be made green within this phase, do not push broken
+state — commit what you have as a WIP, leave the branch un-pushed if
+appropriate, and report the blocker.
+
+## Phase 4: Explain skipped findings (disagreement path)
+
+For every finding you deliberately **skipped**, post a single follow-up
+comment on the PR explaining why — humans remain the final arbiter:
+
+```
+gh pr comment <PR_NUMBER> --body "<explanation>"
+```
+
+This is a plain comment (do **not** wrap it in a `stoker-review`
+sentinel — that would look like a new review to later iterations). If you
+applied every finding, skip this phase.
+
+## Phase 5: Commit and push
+
+Stage the files you changed (`git add <paths>`) and commit with a concise
+imperative message describing the findings you addressed, e.g.:
+
+```
+Address review findings on PR #<PR_NUMBER>
+```
+
+Commit plainly — **never** pass `--no-gpg-sign` / `-c
+commit.gpgsign=false` or otherwise disable signing (stoker configures
+signing before you run; a signing failure is a sandbox bug to report, not
+to bypass). Then push the branch:
+
+```
+git push
+```
+
+The push advances the PR's head past the reviewed `head_sha`, which is
+what clears this PR from the fixup-candidate set on the next iteration
+(review-once: stoker does not re-review after a fixup). If you applied no
+findings at all, there is nothing to push — the PR stays as a human
+decides.
+
+## Finish
+
+End your response with a single `<stoker-status>done</stoker-status>`
+marker once the fixup is complete, so the host knows the phase ran. Do
+not emit any `<stoker-pick>` or `stoker-review` markers.

documenteer-2.5.0b2/.agents/skills/stoker-implement/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: stoker-implement
+description: Drive a single pre-selected task through stoker-work's TDD cycle and commit/push/PR/close it (or stuck-mark it on failure). Use when invoked from the implement-phase prompt — the host has already picked the task and checked out its branch.
+---
+<!-- stoker-managed: skills:.agents/skills/stoker-implement/SKILL.md:a4de715878f733e0 -->
+
+# stoker-implement — drive one pre-selected stoker task to completion
+
+You are operating inside the **implementation** phase of a two-phase
+stoker iteration driven by `stoker run`. By the time this skill is
+invoked:
+
+- The host has already run a separate selection phase that picked
+  exactly one task.
+- The host has already checked out the task's branch inside the
+  container.
+- The implement-phase prompt you just received carries the picked
+  task's issue number, branch, full issue body, parent PRD body (if
+  any), and current git state.
+
+Your job is to take that one task from here through red/green/
+refactor, then commit/push/open-PR/close — or route to the stuck
+path on failure.
+
+If no other memo or instruction contradicts it, the commit / PR
+conventions in this skill are authoritative for this iteration.
+
+## Phase 1: Drive the task through TDD
+
+Follow **Phases 0.5–4** of `.claude/skills/stoker-work/SKILL.md`:
+
+- Phase 0.5 (Read project mechanics) — `stoker-work` will load
+  `.claude/skills/project-mechanics/SKILL.md` for the repo's command
+  names. If that file is missing, route to the stuck path (Phase 4
+  below).
+- Phase 1 (Understand the task) — read the issue body (provided in
+  the prompt), the parent PRD body (if provided), and relevant code.
+- Phase 2 (Plan) — only if not already pre-planned by the task body.
+- Phase 3 (Red/green/refactor) — one test, one behavior at a time.
+- Phase 4 (Final validation) — runs `<lint_all>` + `<typing>` +
+  `<complete_test>` against the project-mechanics commands and
+  guarantees a clean fixpoint, with the intent-to-add files reset
+  so this skill stages with intentionality.
+
+If `stoker-work` Phase 4 cannot be made green within this iteration
+(e.g. pre-existing test failures, missing upstream dependency, or
+the project-mechanics file is missing), route to the stuck path
+(Phase 4 of *this* skill) — do not push broken state.
+
+**Turn-end invariant.** Your turn must not end until you have either
+(success) committed, pushed, opened/updated the PR, and closed the
+issue, or (failure) taken the stuck path. Never end your turn with a
+dirty working tree, with validation still running in the background, or
+on a `Monitor` wait for a still-running command. This covers **any**
+project-mechanics command in **any** phase — including a Phase 3 Red/Green
+`<focused_test>`, not just Phase 4's final validation. Under `stoker run`
+the agent is single-shot headless, so ending your turn (or waiting on a
+backgrounded test via `Monitor`) kills the run before the work reports
+and leaves the tree dirty — the host's next iteration will abort on it.
+Run every such command in the foreground and block on it, however long
+it takes.
+
+## Phase 2: Commit (success path)
+
+`stoker-work` Phase 4 already left the working tree at a fixpoint with
+the original untracked-file state restored. Do not re-run
+`<lint_all>` here — that's the inverse of "fixpoint, then stage once
+with intentionality." Just stage and commit.
+
+Stage with `git add <paths>` listing every path that should land in
+this commit. `git add -A` is allowed only if you've already verified
+every working-tree change is intentional.
+
+Commit using this template verbatim — both `Key decisions:` and
+`Next-iteration notes:` are required sections so the next
+iteration's selection phase can parse them from `git log`:
+
+```
+<imperative subject, ≤70 chars>
+
+<1–2 sentence paragraph describing what this slice does and why.>
+
+Key decisions:
+- <non-obvious design choice>
+- <another, if any>
+
+Next-iteration notes:
+- <migrations to run, scaffolding left in place, assumed state — or "None.">
+
+Closes #<task_issue>
+```
+
+No `Co-authored-by:` trailer (signing, if configured, is
+self-identifying). No files-changed section (`git show` covers it).
+
+**Do not disable signing.** Whether commits are signed is controlled
+by `git config commit.gpgsign`, which `stoker run` configures from
+the profile's signing secrets before the agent ever runs. Run `git
+commit` plainly; never pass `-c commit.gpgsign=false`,
+`--no-gpg-sign`, or any other flag that disables signing on a single
+invocation. If a commit fails because signing is misconfigured, that
+is a sandbox / profile bug to escalate via the stuck path — not
+something to paper over per-commit.
+
+**Pre-commit hook retries:** if `git commit`'s hook fails (the
+staged-file run catches something `stoker-work` Phase 4's full-tree pass
+missed), fix the reported issue, re-stage, and create a **new**
+commit (never `--amend`, never `--no-verify`). After **3**
+consecutive failed commit attempts in this iteration, route to the
+stuck path.
+
+## Phase 3: Push, PR, close
+
+PR creation is delegated to the `stoker-create-pr` skill — it owns title
+format, body shape, the `Closes #N` / `PRD:` trailers, and the
+"create new vs. update existing OPEN PR" branching. Invoke it now,
+passing the picked task issue's number and parent PRD (if any) as
+context.
+
+`stoker-create-pr` will:
+
+- Push the branch.
+- Detect whether an open PR already exists for the branch.
+- Either create a new PR or regenerate the existing OPEN PR's body
+  from the branch's cumulative scope.
+- Skip handling if the PR is already MERGED / CLOSED.
+
+If `stoker-create-pr` reports a push failure (non-fast-forward, permission,
+network), **do not** retry or rebase from here. Route to the stuck
+path (Phase 4 of this skill).
+
+After `stoker-create-pr` returns the PR URL (or the merged-PR signal),
+proceed with the comment + close steps below.
+
+Comment on the task issue:
+
+```
+✓ Implemented in commit `<sha>` — PR #<pr_number>
+```
+
+Close the task issue:
+
+```
+gh issue close <task_issue>
+```
+
+Closing immediately (rather than waiting for PR merge) lets the
+next iteration's host filter see dependent tasks become eligible.
+If the PR is later rejected, the issue must be manually reopened —
+this tradeoff is accepted.
+
+## Phase 4: Stuck path
+
+Use this path when:
+
+- `stoker-work` Phase 4 validation cannot be made green in this iteration.
+- `stoker-create-pr` reports a push failure (non-fast-forward, permission,
+  network).
+- 3 consecutive pre-commit hook failures.
+- `.claude/skills/project-mechanics/SKILL.md` is missing and you
+  could not safely guess the test/lint commands.
+- Any other blocker that prevents a clean commit + push + close.
+
+(Branch-resolution failures are handled by the host before this
+skill is invoked, so you will not reach this path for a missing or
+malformed branch.)
+
+Steps:
+
+1. Stage what you have. Commit with the stuck template:
+
+   ```
+   WIP(stuck) <imperative subject>
+
+   <paragraph: what was attempted.>
+
+   Blocking:
+   - <why stuck>
+
+   Refs #<task_issue>
+   ```
+
+2. Push the branch.
+3. **Do not** create or update a PR.
+4. Comment on the task issue describing what was attempted and
+   what's blocking.
+5. Add the stuck label:
+
+   ```
+   gh issue edit <task_issue> --add-label agent-stuck
+   ```
+
+6. **Do not** close the issue.
+
+A human clears the `agent-stuck` label to re-enable the issue in
+later runs.
+
+After Phase 3 (success) or Phase 4 (stuck), simply end your response.
+The host loop owns the iteration sentinel and continues on its own.