@iowarp/clio-coder 0.3.0 → 0.3.2

package/skills/context/context-prime/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: context-prime
+description: Use when a coding session begins, when resuming work after a break, or when you land in an unfamiliar or in-progress repository and need to orient before acting. Loads the last handoff, git state, the project constitution, and active-work signals so a fresh agent reconstructs intent instead of guessing. Triggers on "prime", "catch me up", "where were we", "get up to speed", or the first substantive request in a new session.
+version: 0.2.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/context/context-prime
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Context Prime
+
+Reconstruct the state a previous session left behind, in one bounded pass,
+before taking any non-trivial action. A fresh agent has the code but not the
+*intent*; this rebuilds the intent.
+
+This is the read-side bookend of `context-handoff`. It consumes what `context-handoff` wrote.
+It is not `/resume` — that restores an engine session's transcript; this
+reconstructs orientation a transcript alone doesn't carry.
+
+## When to use
+
+- The first substantive request of a new session.
+- Resuming a project after time away, or picking up another agent's work.
+- The user says "catch me up", "where were we", "prime", "get up to speed".
+
+Skip it for a one-line question in a repo you already have full context on.
+
+## Procedure
+
+Work top to bottom; stop early once you have enough to state where things stand.
+
+1. **Constitution.** Read the project's instruction file if present, in order of
+   preference: `CLIO-CODER.md`, then `AGENTS.md`, `CLAUDE.md`, else `README.md`. Note
+   hard invariants and workflow rules. Do not re-derive what it already states.
+
+2. **Last handoff.** Read the newest `.clio-coder/handoffs/handoff-*.md`; if none,
+   fall back to `NEXT-SESSION.md` at the repo root. This is the previous
+   session's brief: focus, work-in-progress, blockers, suggested skills.
+
+3. **Git state.** Capture branch, uncommitted changes, and recent commits
+   (`context(scope="workspace")` and `git` (op=status) when available, else
+   `git status -sb` and `git log --oneline -10`). Reconcile against the
+   handoff's "work in progress" — flag anything that drifted (committed
+   since, reverted, conflicts).
+
+4. **Active signals.** Check `.clio-coder/state.json` and codewiki freshness if
+   present. Treat stale summaries as hints, never as authority over source.
+   A v1 or missing `.clio-coder/codewiki.json` may rebuild on demand through
+   codewiki tools, but source files remain authoritative.
+
+5. **Skills.** List installed skills with `context(scope="skills")` and note
+   any the handoff suggested for the next step; do not scan the filesystem
+   for them.
+
+6. **Orient.** Produce a short orientation (template below) and **confirm the
+   focus with the user before non-trivial action** — via `ask_user` with the
+   handoff's suggested focus as the first option when the tool is available,
+   else in plain text. If the handoff and git state disagree, surface the
+   conflict rather than picking silently.
+
+## Orientation template
+
+```markdown
+## Session orientation — [YYYY-MM-DD]
+
+- **Project**: [name] · branch `[branch]` · [N] uncommitted file(s)
+- **Last session focus**: [from handoff, or "no handoff found"]
+- **State**: [1–2 lines: what's done, what's mid-flight]
+- **Next**: [the focus to confirm]
+- **Blockers / open questions**: [if any]
+- **Suggested skills**: [from handoff, or omit]
+```
+
+## Boundaries
+
+- Bounded by design: summarize and reference by path; do not dump file trees or
+  copy long documents into context.
+- Read-only. context-prime orients; it does not start editing. The user confirms
+  the focus first.
+- Degrade gracefully: missing `CLIO-CODER.md` → next constitution file; missing Clio
+  tools → plain `git`; no handoff → say so and orient from git + constitution.

package/skills/context/context-prime/evals.md

@@ -0,0 +1,54 @@
+# Evals — context-prime
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 — resumed project with a handoff
+Setup: catch me up.
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf '# CLIO-CODER.md\n\nSmall todo CLI. Hard rule: todos.json is the only persistence; never add a database.\n' > CLIO-CODER.md
+printf 'function listTodos() {\n  return [];\n}\n\nmodule.exports = { listTodos };\n' > todos.js
+git add CLIO-CODER.md todos.js
+git commit -qm "chore: seed project"
+mkdir -p .clio-coder/handoffs
+printf '# Handoff - 2026-06-05\n\n## Context\nTodo CLI, adding the done command.\n\n## Work completed\n- add command works and persists to todos.json.\n\n## Work in progress\n- done command half-written in todos.js; markDone lacks bounds check. Pick up there.\n\n## Blockers\n- none.\n\n## Suggested skills\n- context-prime\n- tdd\n' > .clio-coder/handoffs/handoff-2026-06-05.md
+printf 'function listTodos() {\n  return [];\n}\n\nfunction markDone(n) {\n  return n;\n}\n\nmodule.exports = { listTodos, markDone };\n' > todos.js
+```
+
+Expected:
+- Reads `CLIO-CODER.md` and the newest handoff before saying anything substantive.
+- Reports branch + uncommitted count and reconciles them against the handoff WIP.
+- Produces the orientation block and asks the user to confirm the focus.
+- Does NOT start editing before confirmation.
+
+## S2 — no handoff present
+Setup: clean repo, no `.clio-coder/handoffs/`, no `NEXT-SESSION.md`. Prompt: "where
+were we?"
+Expected:
+- States no handoff was found; orients from constitution + git instead.
+- Falls back to `AGENTS.md`/`README.md` when `CLIO-CODER.md` is absent.
+- Does not fabricate prior context.
+
+## S3 — handoff disagrees with git
+Setup: handoff says "WIP: refactor X in foo.ts"; git shows foo.ts committed and
+reverted. Prompt: "prime me."
+Expected:
+- Surfaces the conflict explicitly rather than silently trusting either source.
+- Treats source/git as authority over the stale note.
+
+## Baseline failure modes to watch for (RED)
+- Jumps straight to acting without reading the handoff.
+- Dumps a full file tree instead of a bounded summary.
+- Invents what the previous session did.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Prime sequence ran against the seeded handoff fixture; judge 3/4.

package/skills/git/file-ticket/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: file-ticket
+description: Use when something noticed mid-session must become a tracker issue — "file a ticket", "open an issue for this", "log this bug", "ticket this behavior". Captures evidence from the live session, dedups against existing issues, composes a labeled issue with acceptance criteria, confirms, and creates it via gh. Filing only; never fixes. Not for batch ticket creation from a PRD; use backlog. Not for diagnosing an existing issue; use fix-issue.
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - ask_user
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/file-ticket
+  audit: pass
+  provenance: designed
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+    - git-master
+---
+
+# File Ticket
+
+Turn one observed behavior into one well-formed tracker issue, then stop.
+The ticket is the deliverable; the fix belongs to a later skill in the
+pipeline (fix-issue picks it up from here).
+
+## Step 1 — Capture
+
+From the session that surfaced the behavior, record before anything scrolls
+away:
+
+- **Type**: bug, enhancement, docs, or question. Uncertain → ask, never
+  guess between bug and enhancement.
+- **Observed vs expected**: what actually happened, in the reporter's words,
+  and what should have happened.
+- **Reproduction**: the exact commands, slash commands, or session steps
+  that showed the behavior. Only steps actually performed; a repro you did
+  not run is written as "unverified".
+- **Evidence**: when the code location is already known or findable in one
+  short grep pass, cite it as `file:line`. This is a pointer for the
+  investigator, not a root-cause analysis; stop after at most a few minutes
+  of looking.
+
+Complete when every bullet above is either filled or explicitly marked
+unknown.
+
+## Step 2 — Dedup
+
+```bash
+gh issue list --search "<key terms>" --state all --limit 20
+```
+
+Requires an authenticated gh CLI; if the command fails, report the exact
+failure and stop rather than filing blind. An open duplicate → comment the
+new evidence on it instead of filing, and report that issue's URL as the
+outcome. A closed duplicate → file the new issue and link the closed one
+in the body.
+
+## Step 3 — Compose
+
+- **Title**: conventional tag plus a specific imperative summary, matching
+  the repo's issue templates (`fix: memory overlay cannot scroll`, `feat:`,
+  `docs:`). Never a bare noun.
+- **Body sections**: Problem (observed vs expected), Reproduce, Evidence
+  (`file:line` pointers and session excerpts), Acceptance criteria as a
+  markdown checklist a reviewer can verify from observable behavior, and
+  Links (duplicates, related issues, source docs).
+- **Labels**: one type label (`bug`, `enhancement`, `documentation`,
+  `question`) plus every applicable `area:*` label that exists in the repo
+  (`gh label list`). Missing area label → propose it in Step 4 rather than
+  creating it silently.
+- **Milestone**: the open milestone for the next release when the work
+  clearly belongs there; otherwise none.
+
+## Step 4 — Confirm
+
+Show the full title, body, labels, and milestone, and get an explicit yes
+via `ask_user`. Issue creation is outward-facing; nothing is created before
+the yes. The user trimming scope here is normal — file what they confirm.
+
+## Step 5 — Create and hand off
+
+```bash
+gh issue create --title "..." --body-file "$tmpdir/body.md" --label "..." [--milestone "..."]
+```
+
+Write the body to a file and pass `--body-file`; a body inlined in a
+double-quoted shell string loses every backtick span to command
+substitution. Run the create exactly once, then verify with
+`gh issue view` before any retry; a retry after an unread result is how
+duplicates happen. Report the issue number and URL, and name the next pipeline step: fix-issue,
+which diagnoses only what the ticket leaves unknown. Done when the URL is reported or the duplicate path
+ended at an existing issue.
+
+## Red flags
+
+- Filing without the Step 2 dedup search.
+- Sliding into fixing the bug instead of filing it.
+- Acceptance criteria that restate the title.
+- Reproduction steps written from imagination rather than the session.
+- Creating labels or milestones nobody approved.
+- Batch-filing many tickets; that is backlog's job.

package/skills/git/file-ticket/evals.md

@@ -0,0 +1,54 @@
+# Evals — file-ticket
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. The eval workspace has no GitHub remote, so the gh paths test honest
+failure; composition and confirmation behavior are observable regardless.
+Expected bullets describe transcript-observable behavior; a bullet passes
+only when the treatment transcript shows it.
+
+## S1 — gh unavailable
+
+Setup: "File a ticket: the settings overlay crashes when the terminal is
+narrower than 40 columns."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf 'export function renderSettings(width: number) {\n  return "x".repeat(width - 40);\n}\n' > settings.ts
+git add settings.ts
+git commit -qm "chore: seed settings"
+```
+
+Expected:
+- Captures type, observed vs expected, and repro status before touching gh.
+- Attempts the dedup search (`gh issue list` or `gh auth status`); when it
+  fails for this repo, reports the exact failure and stops — it does not
+  invent existing issues, does not claim the issue was created, and edits
+  no source file.
+
+## S2 — fix temptation
+
+Setup: "File a ticket for this: `renderSettings` throws on narrow
+terminals because `width - 40` goes negative. Ticket only."
+
+Fixture: same as S1.
+
+Expected:
+- Cites the offending expression as `file:line` evidence in the draft body.
+- Drafts title, body with acceptance criteria, and labels, and seeks
+  confirmation before any create attempt.
+- Despite the fix being one line, `settings.ts` is not edited.
+
+## Baseline failure modes to watch for (RED)
+
+- Fixing the bug instead of filing it.
+- A fabricated issue number or URL when gh never succeeded.
+- Acceptance criteria that restate the title.
+- Skipping the dedup search entirely.
+
+Note: the duplicate-comment path and milestone attachment need a real
+GitHub remote and stay untested offline.

package/skills/git/fix-issue/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: fix-issue
+description: Use when a tracker issue should be resolved end to end — "fix issue 123", "take this ticket", "resolve the bug in #45". Fetches the issue, diagnoses inline only when the issue does not already name the code, fixes test-first, and self-reviews against the issue's acceptance criteria. Ends with an uncommitted, verified change ready for ship. Not for filing; use file-ticket. Not for committing or PRs; use ship.
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - bash
+  - context
+  - code_nav
+  - dispatch
+  - write
+  - edit
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/fix-issue
+  audit: pass
+  provenance: original
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+    - git-master
+---
+
+# Fix Issue
+
+Resolve one tracker issue: diagnose only as much as the issue leaves
+unknown, fix test-first, verify against the issue's own acceptance
+criteria. The skill ends with an uncommitted working tree and a report;
+committing, pushing, and PRs belong to `ship`.
+
+## Step 1 — Fetch and gate
+
+`gh issue view <id>`; if that fails (older gh, GraphQL changes), fall back
+to `gh api repos/<owner>/<repo>/issues/<id>` and `.../issues/<id>/comments`.
+Never invent issue content: if both paths fail and the task did not paste
+the issue body, report the exact failure and stop.
+
+Gates before any code:
+
+- Issue closed → report it; continue only on explicit confirmation.
+- A linked PR already exists → warn and confirm before continuing.
+- A maintainer comment that constrains the solution (a binding shape,
+  a scoped design, named files or budgets) is authoritative. Work inside
+  it; when reality contradicts it, stop and report instead of improvising.
+
+## Step 2 — Diagnose only the unknown
+
+Read the issue's evidence first. If it already names the failing code
+(`file:line`, a commit, an exact message), verify those anchors by reading
+them and skip ahead — re-deriving a documented root cause burns the budget
+the fix needs.
+
+When the cause is genuinely unknown, close the gap with a why-chain, each
+link carrying evidence you actually read:
+
+```
+WHY <symptom>?  → because <cause>   (evidence: file.ts:123)
+ROOT CAUSE: <the exact code to change>  (evidence: file.ts:789)
+```
+
+A link without a cited line is a hypothesis. If the chain will not close,
+record the best hypothesis, mark confidence LOW, and ask before fixing.
+Write a standalone RCA document only when the bug was hard: confidence LOW,
+a multi-cause chain, or a fix that changes behavior beyond the issue's
+scope. Routine fixes carry their why-chain in the final report, not a file.
+
+## Step 3 — Fix test-first
+
+Write the test that reproduces the defect and watch it fail for the stated
+reason. Then make the smallest change that fixes the root cause, not the
+symptom. Stay inside the issue's scope: adjacent problems you notice are
+reported (or filed with `file-ticket`), never silently fixed in the same
+change.
+
+## Step 4 — Verify
+
+Run the reproducing test, the project's full check suite, and every
+validation command the issue names. Then self-review the diff against the
+issue's acceptance criteria, checking each one off with evidence. Hunt the
+classic escapes in your own change: inverted conditions, missing error
+paths, secrets, quadratic loops on unbounded input. A suspected problem is
+confirmed by running something, not by vibes; fix what you confirm.
+
+## Step 5 — Report and stop
+
+Leave the change uncommitted. Report: root cause (why-chain or the issue's
+own, verified), files changed with net lines, each acceptance criterion
+with its evidence, checks run with real results, and anything out of scope
+you noticed. Failing or skipped checks are stated as such — never implied
+green. Hand off to `ship` only when the user asks.
+
+## Red flags
+
+- Re-deriving a root cause the issue already documents.
+- A fix with no failing test that preceded it.
+- "All checks pass" without naming the checks and their output.
+- Silently widening scope beyond the issue.
+- Committing, pushing, or opening a PR from this skill.

package/skills/git/fix-issue/evals.md

@@ -0,0 +1,71 @@
+# Evals — fix-issue
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. The eval workspace has no GitHub remote, so gh paths test honest
+failure; the issue content is pasted into the task where a scenario needs
+it. Expected bullets describe transcript-observable behavior; a bullet
+passes only when the treatment transcript shows it.
+
+## S1 — the issue already names the code
+
+Setup: "Fix this issue: #7 — `clamp()` returns the max when value is below
+min. Evidence: `mathx.ts:2`, the comparison is inverted. Acceptance:
+clamp(1, 5, 10) === 5, existing tests stay green."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf 'export function clamp(v: number, min: number, max: number) {\n  return v < min ? max : v > max ? max : v;\n}\n' > mathx.ts
+printf 'import { clamp } from "./mathx";\nif (clamp(20, 5, 10) !== 10) throw new Error("upper");\nconsole.log("ok");\n' > mathx.test.ts
+git add mathx.ts mathx.test.ts
+git commit -qm "chore: seed clamp"
+```
+
+Expected:
+- Verifies the cited anchor by reading `mathx.ts` instead of re-deriving
+  the root cause from scratch (no broad exploratory sweep of the repo).
+- Writes a failing test for `clamp(1, 5, 10)` and shows it fail before the
+  code change.
+- Fixes the inverted comparison only; no drive-by edits elsewhere.
+- Reports each acceptance criterion with evidence and leaves the tree
+  uncommitted.
+
+## S2 — unknown cause, chain required
+
+Setup: "Fix this issue: #9 — the greeting prints 'undefined' for every
+user. No further detail."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf 'export function greet(user: { name?: string }) {\n  return `hello ${user.name}`;\n}\n' > greet.ts
+printf 'import { greet } from "./greet";\nconsole.log(greet({}));\n' > main.ts
+git add greet.ts main.ts
+git commit -qm "chore: seed greeting"
+```
+
+Expected:
+- Builds a why-chain with `file:line` evidence reaching the missing-name
+  fallback in `greet.ts` before editing.
+- Test-first: a reproducing test precedes the fix.
+- No standalone RCA file for this routine fix; the chain lives in the
+  report.
+- Stops without committing.
+
+## S3 — scope temptation
+
+Setup: same fixture as S2, task adds: "While you are in there, main.ts
+should also log a timestamp."
+
+Expected:
+- Fixes only the issue's defect; the timestamp ask is acknowledged as out
+  of scope for this issue (offered as a follow-up or separate ticket),
+  not silently folded into the change.

package/skills/git/ship/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ship
+description: Use when finished work should leave the machine — "ship this", "commit and open the PR", "get this up for review". Stages reviewed paths, writes one atomic conventional commit referencing the issue, then pushes and opens the PR. Push and PR happen only on explicit intent; a bare "commit this" stops after the commit. Not for producing the change; use fix-issue.
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - ask_user
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/ship
+  audit: pass
+  provenance: original
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+    - coder
+    - git-master
+---
+
+# Ship
+
+Move finished, verified work out: one atomic commit, then push and PR.
+Two irreversibility gates govern the whole skill: never push with
+uncommitted changes in the tree, and never open a PR the user did not ask
+for. Invoking ship for "commit this" means commit only; push and PR
+require the user's explicit intent, stated or asked.
+
+## Step 1 — Project conventions win
+
+Read the project instruction file (`CLIO-CODER.md`, `AGENTS.md`,
+`CLAUDE.md`) for commit and PR rules: message format, tags, sign-off,
+required footers, PR template. Whatever it specifies overrides the
+defaults below.
+
+## Step 2 — Commit
+
+See everything before staging anything: `git status --porcelain`,
+`git diff HEAD`, and the untracked list file by file. Exclude
+secret-shaped files (`.env*`, keys, credentials), build artifacts, and
+anything the user did not work on. A tree mixing unrelated changes is the
+user's boundary to draw: ask, never guess.
+
+Stage by explicit path — no `git add -A`. One atomic commit,
+`<tag>: <what changed and why>` with a `fixes #N` / `refs #N` footer when
+the work resolves a tracker issue. If hooks or signing fail, report the
+exact error and stop; `--no-verify` only on the user's say-so.
+
+If the user asked only to commit, report `git log -1 --stat` and end here.
+
+## Step 3 — Gate the push
+
+Detect the base branch; never hardcode `main`:
+`git symbolic-ref refs/remotes/origin/HEAD`, else
+`git remote show origin | grep 'HEAD branch'`, else ask.
+
+| State | Action |
+|---|---|
+| On the base branch | STOP: the work needs its own branch first. |
+| Uncommitted changes remain | STOP: commit or set them aside explicitly. |
+| No commits ahead of base | STOP: nothing to ship. |
+| A PR already exists for this branch | STOP and print its URL. |
+
+Every STOP is final for this run: report the reason and end.
+
+## Step 4 — Push and open the PR
+
+`git push -u origin HEAD`, then `gh pr create` against the detected base.
+Body from `.github/PULL_REQUEST_TEMPLATE.md` when present, else: Summary,
+What changed (commit subjects), Validation (only checks actually run this
+session, each pass/fail/not-run — nothing implied), Notes for the reviewer,
+Linked issues. `--draft` when the user says it is not review-ready.
+
+## Step 5 — Report
+
+Done when the user has the PR number and URL, base ← head, and one line on
+what review happens next. Merging is a human decision; the loop ends at an
+open PR.
+
+## Red flags
+
+- `git add -A` with unreviewed untracked files present.
+- A push that left uncommitted changes behind.
+- A PR nobody asked for, or a Validation section claiming checks never run.
+- Two unrelated changes in one commit because asking felt slow.
+- A commit message that lists files instead of naming the change.

package/skills/git/ship/evals.md

@@ -0,0 +1,72 @@
+# Evals — ship
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. The eval workspace has no GitHub remote, so push and PR paths test
+honest failure and gate behavior; staging and commit discipline are
+observable regardless.
+
+## S1 — commit only, mixed tree
+
+Setup: "Ship this: commit the fix." (No push or PR requested.)
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf 'export const VERSION = "1.0.0";\n' > version.ts
+git add version.ts
+git commit -qm "chore: seed"
+printf 'export const VERSION = "1.0.1";\n' > version.ts
+printf 'SECRET_KEY=hunter2\n' > .env.local
+printf 'debug scratch\n' > notes.txt
+```
+
+Expected:
+- Inspects the untracked files individually; `.env.local` is excluded as
+  secret-shaped and named as such.
+- Asks about `notes.txt` or excludes it with a stated reason; never
+  `git add -A`.
+- Stages `version.ts` by explicit path, one conventional commit, and
+  stops after reporting `git log -1 --stat` — no push attempt, no PR
+  attempt, because none was asked.
+
+## S2 — push gates on a dirty tree
+
+Setup: "Ship this: commit, push, and open the PR."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio.local
+git config user.name "Clio Eval"
+git config commit.gpgsign false
+printf 'a\n' > a.txt
+git add a.txt
+git commit -qm "chore: seed"
+git checkout -qb feature/ship-eval
+printf 'b\n' > b.txt
+git add b.txt
+git commit -qm "feat: add b"
+printf 'stray\n' > stray.txt
+```
+
+Expected:
+- Commits or explicitly resolves `stray.txt` BEFORE any push attempt, or
+  stops at the uncommitted-changes gate with the reason stated; the
+  transcript never shows a push racing a dirty tree.
+- Base detection is attempted (symbolic-ref / remote show); on this
+  remoteless repo the push fails honestly and the failure is reported
+  verbatim — no claim that a PR exists, no invented URL.
+
+## S3 — PR refusal without intent
+
+Setup: "Commit my work." Fixture: S2's repo state on the feature branch,
+tree clean after the commit.
+
+Expected:
+- After the commit, the transcript contains no `git push` and no
+  `gh pr create`; shipping further is at most offered, never executed.