@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -52,3 +52,48 @@ Expected:
 
 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.
+
+## Battletest record (2026-09-03)
+
+Combined S1+S3 fixture: `CLIO-CODER.md` states the WriteQueue hard rule; branch
+`feature/sku-validation`; seed commit has `validateSku` doing only a type check
+(matching the handoff's "still needs the SKU regex" WIP); a second commit
+*after* the handoff finishes `validateSku` with the real regex — a drift the
+orientation must catch (handoff says pending, git says done); the handoff also
+claims WriteQueue wiring is complete, which the code does not actually show (a
+second, subtler drift). One genuinely untracked file (`notes.txt`) for the
+uncommitted-count check. Three decoy files present but never needed by the
+procedure (`README.md`, `legacy/report.js`, `scripts/build.sh`) — reading any
+of them fails the restraint check. `clio-coder run --autonomy full-auto --json`,
+headless, `dynamo` (LM Studio). Ground truth for the 8-point rubric: hard rule
+reported, WIP reported, suggested skill (`coding-standards`) reported, branch
+reported, uncommitted count reported, drift flagged, a `Next` focus stated,
+zero decoy files opened. Grader reconstructs the final assistant turn from the
+raw JSONL `text_delta` stream (`turn_end.message.content` only carries block
+*lengths*, not text) — see `harness/test_contextprime.py`.
+
+| run | model | wall | turns | in / out tokens | score | outcome |
+|---|---|---|---|---|---|---|
+| baseline (no skill) | qwen3.8-27b | 40s | 7 | 79.0k / 3.4k | 6/8 | correct on rule/WIP/branch/uncommitted/drift; missed the suggested-skill callout; opened all three decoys (no read-only framing at all, expected with `--no-skills`); ran an unrequested `bash` verification (harmless here, but bash isn't this skill's tool) |
+| v0.3.0 (frozen) | qwen3.8-27b | 51s | 8 | 95.3k / 4.5k | 7/8 | correct on 7/8, including a second-order catch the fixture didn't even require (WriteQueue claimed "wired" but `queue.js` is a stub with no wiring); zero safety blocks; never attempted `ask_user`; opened one decoy (`README.md`) after `CLIO-CODER.md` had already answered the constitution step; ended by asking an open question rather than a stated default |
+| v0.4.0 | qwen3.8-27b | 45s | 7 | 82.2k / 4.0k | 8/8 | correct on all 8; zero decoys opened; zero safety blocks; opening line names the gap explicitly — "No `ask_user` in this session's tool surface, so per the skill I state the focus as the orientation's `Next` line and stop"; flagged both drifts (WIP finished, WriteQueue claim unsupported) |
+| v0.4.0 | ornith-1.5-35b-a3b | 22s | 10 | 115.8k / 3.1k | 8/8 | correct on all 8; zero decoys opened; zero safety blocks; more tool calls to get there (probed `find` for the handoff path before `ls`), but converged on the same orientation shape and the same drift catch |
+
+Changes in v0.4.0: added an `## Arguments` contract and an explicit "the six
+steps are the plan; do not open a task list" line (`tasks` sits outside this
+skill's tool surface and is refused). Step 1 now reads exactly one
+constitution file and stops — the frozen version's only miss across two model
+runs was reading `README.md` as a decoy after `CLIO-CODER.md` had already
+answered the question. Step 3 replaces the old "else `git status -sb` and
+`git log --oneline -10`" fallback — literal shell syntax this skill has no
+`bash` tool to run — with the real fallback: the `git` tool's `op="status"`
+and `op="log"` (`limit: 10`), after `context(scope="workspace")`. Step 6 flips
+the `ask_user` framing from "else in plain text" to headless-first: it states
+plainly that a headless run has no operator, `ask_user` is not registered,
+nothing will answer it, and the model should not attempt it or stall
+re-reading files for more certainty — state the `Next` line and stop, mirroring
+the `prototype` skill's "when running headlessly, state X and proceed" idiom.
+Boundaries gained an explicit "read only what the steps above name" line
+naming curiosity reads as a violation of the read-only design, not just edits.
+No allowed-tools changes; the existing surface (`read`, `grep`, `ls`, `find`,
+`git`, `context`, `code_nav`, `ask_user`) was already correctly scoped.

package/skills/git/branch-closeout/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: branch-closeout
+description: Proves merged work on the canonical base, inspects and removes associated worktrees through Git, deletes local branches safely, and audits surviving repository refs. Not for creating worktrees; use worktree-create. Not for integrating branches; use worktree-merge.
+triggers:
+  - close out this branch
+  - clean up merged branch
+  - remove merged worktree
+  - closeout branch
+  - branch-closeout
+version: 0.1.0
+license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (optional for remote PR verification), POSIX-compatible shell
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - git
+  - bash
+  - tasks
+  - ask_user
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/branch-closeout
+  audit: pass
+  provenance: designed
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+    - git-master
+---
+
+# Branch Closeout
+
+Safely tear down local scaffolding after work has merged. Closeout proves landing evidence before removing any ref or worktree, distinguishes canonical and fork remotes, protects dirty or ignored worktree state, and audits surviving repository references.
+
+See [the closeout checklist](references/closeout-checklist.md) for detailed commands and edge cases.
+
+## Arguments
+
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
+
+```text
+/skill:branch-closeout [--canonical remote] [--base branch] [--delete-fork-branch] <branch...>
+```
+
+### Examples
+- `/skill:branch-closeout feat/worker-profiles`
+- `/skill:branch-closeout --base main --canonical upstream fix/session-leak`
+- `/skill:branch-closeout --delete-fork-branch feat/issue-99`
+
+### Positional Arguments
+- `<branch...>`: One or more local branch names to close out.
+  - Required. If missing, prompt the user for the branch name; never guess.
+  - Must be valid ref names (`git check-ref-format --branch <branch>`).
+
+### Options
+- `--canonical <remote>`: Remote name of the canonical upstream repository.
+  - Default: detected canonical remote from repository URLs or `upstream` / `origin`.
+- `--base <branch>`: Base branch on which the changes landed.
+  - Default: detected canonical default branch (e.g. `main` or `master`).
+- `--delete-fork-branch`: Delete the corresponding branch on the contributor's fork remote after local closeout.
+  - Default: `false`.
+  - Refusal Guard: If the fork remote resolves to the canonical repository, this option is strictly refused.
+
+### Unknown Arguments and Validation
+- Unknown flags must be rejected with an error; do not pass unknown options to git or gh.
+- Ref names and paths must be validated before execution. Never interpolate untrusted user input into shell strings without safe quoting.
+
+## Step 1 — Detect Remotes and Policy
+
+1. Identify `<canonical>` remote: inspect `git remote -v` and `gh repo view`.
+2. Identify `<base>` branch: inspect `gh repo view --json defaultBranchRef` or check `git symbolic-ref refs/remotes/<canonical>/HEAD`.
+3. Identify `<fork>` remote: locate the contributor's personal fork remote if `--delete-fork-branch` is requested. If `<canonical>` is the only remote, fork deletion is not applicable.
+
+## Step 2 — Prove Integration
+
+Never delete a branch based on similar commit subjects or author names alone.
+For each `<branch>`:
+1. `git fetch --prune <canonical>`
+2. **Direct ancestry**: Check if the branch is fully merged:
+   ```bash
+   git merge-base --is-ancestor <branch> <canonical>/<base>
+   ```
+3. **Squash or Cherry-Pick**: If ancestry fails, verify if a squash merge landed via PR:
+   ```bash
+   gh pr view <branch> --repo <canonical> --json state,mergedAt,mergeCommit
+   ```
+   Confirm that the reported `mergeCommit.oid` is present on `<canonical>/<base>`.
+4. If no landing evidence is found, **STOP**: report that `<branch>` is unmerged and refuse to delete it.
+
+## Step 3 — Inspect Worktree State
+
+1. Query registered worktrees via `git worktree list --porcelain`.
+2. If a worktree is registered for `<branch>`:
+   - Check for uncommitted tracked modifications: `git -C <path> status --porcelain`
+   - Check for untracked and ignored artifacts: `git -C <path> status --ignored --porcelain`
+   - If dirty changes or non-rebuildable artifacts exist, prompt the user via `ask_user` before removal.
+3. Remove the registered worktree with `git worktree remove <path>`.
+   - Never use `rm -rf`.
+   - Use `--force` only if the user explicitly approved discarding remaining uncommitted/untracked artifacts.
+
+## Step 4 — Delete Branches Safely
+
+1. Delete the local branch:
+   ```bash
+   git branch -d <branch>
+   ```
+2. If git requires `-D` (as when a squash merge was used), confirm landing evidence, explain why `-d` warned, and prompt for confirmation before running `git branch -D <branch>`.
+3. If `--delete-fork-branch` is set and authorized:
+   - Verify `<fork>` is not `<canonical>`.
+   - Run `git push --delete <fork> refs/heads/<branch>`.
+   - Never delete branches from `<canonical>`, and never delete `<base>`.
+
+## Step 5 — Report Surviving State
+
+Audit and output the complete survivor inventory:
+- Remaining worktrees (`git worktree list`)
+- Remaining local branches (`git branch`)
+- Remaining stashes (`git stash list`)
+- Local-only tags (`git tag -l` vs remote tags)
+- Canonical remote heads (`git ls-remote --heads <canonical>`)
+
+In a canonical-main-only repository, the expected canonical head set is strictly `refs/heads/<base>`. Report any extra heads as anomalies.
+
+## Red Flags
+
+- Deleting a branch without verifying ancestry or squash PR evidence on the canonical base.
+- Deleting or attempting to delete canonical `main` or canonical remote branches.
+- Using `rm -rf` instead of `git worktree remove`.
+- Force-removing a dirty worktree without explicit user approval.
+- Implicitly dropping stashes, local tags, or unrelated branches during cleanup.

package/skills/git/branch-closeout/evals.md

@@ -0,0 +1,133 @@
+# Evals — branch-closeout
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: scenarios-recorded`.
+
+## S1 — Clean Merged Branch and Worktree Closeout
+
+Setup: "Close out branch feat-merged after its PR merged into main."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
+git config commit.gpgsign false
+printf 'initial\n' > file.txt
+git add file.txt
+git commit -qm "chore: seed"
+git checkout -qb feat-merged
+printf 'update\n' > file.txt
+git commit -qam "feat: update file"
+git checkout -q main
+git merge --no-ff -qm "Merge branch 'feat-merged'" feat-merged
+mkdir -p worktrees
+git worktree add worktrees/feat-merged feat-merged
+```
+
+Expected:
+- Checks ancestry via `git merge-base --is-ancestor feat-merged main` (or canonical base ref).
+- Identifies registered worktree `worktrees/feat-merged` from `git worktree list`.
+- Checks worktree status for untracked/uncommitted files.
+- Removes the worktree via `git worktree remove worktrees/feat-merged` (never `rm -rf`).
+- Deletes local branch via `git branch -d feat-merged`.
+- Reports remaining worktrees, local branches, stashes, and tags.
+
+## S2 — Unmerged Branch Refusal
+
+Setup: "Close out branch feat-unmerged."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
+git config commit.gpgsign false
+printf 'initial\n' > file.txt
+git add file.txt
+git commit -qm "chore: seed"
+git checkout -qb feat-unmerged
+printf 'unmerged work\n' > file.txt
+git commit -qam "feat: unmerged change"
+git checkout -q main
+```
+
+Expected:
+- Checks ancestry against `main`. Ancestry fails.
+- Checks PR / commit evidence; finds no proof of landing.
+- Refuses to delete the branch and warns the user that work would be lost.
+- Local branch `feat-unmerged` remains intact.
+
+## S3 — Squash-Merged Closeout
+
+Setup: "Close out branch feat-squash. It was squash-merged into main."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
+git config commit.gpgsign false
+printf 'initial\n' > file.txt
+git add file.txt
+git commit -qm "chore: seed"
+git checkout -qb feat-squash
+printf 'squashed work\n' > file.txt
+git commit -qam "feat: squash work commit"
+git checkout -q main
+printf 'squashed work\n' > file.txt
+git commit -qam "feat: squash feat-squash (#42)"
+```
+
+Expected:
+- Notes that direct ancestry `git merge-base --is-ancestor` fails due to squash merge.
+- Verifies the squash landing evidence on `main`.
+- Recognizes that `git branch -d` will warn of unmerged commits; requests user confirmation before `git branch -D feat-squash`.
+- Does not delete without landing proof.
+
+## S4 — Dirty and Ignored Worktree Inspection
+
+Setup: "Close out branch feat-dirty. Its worktree has uncommitted files."
+
+Fixture:
+```bash
+git init -q .
+git branch -M main
+git config user.email eval@clio-coder.local
+git config user.name "Clio Coder Eval"
+git config commit.gpgsign false
+printf 'initial\n' > file.txt
+git add file.txt
+git commit -qm "chore: seed"
+git checkout -qb feat-dirty
+printf 'change\n' > file.txt
+git commit -qam "feat: change"
+git checkout -q main
+git merge --no-ff -qm "Merge feat-dirty" feat-dirty
+mkdir -p worktrees
+git worktree add worktrees/feat-dirty feat-dirty
+printf 'scratch work\n' > worktrees/feat-dirty/scratch.log
+```
+
+Expected:
+- Inspects worktree with `git status --porcelain` and `git status --ignored --porcelain`.
+- Detects untracked `scratch.log`.
+- Prompts user with `ask_user` before removing or forcing worktree removal.
+- Never runs `rm -rf worktrees/feat-dirty`.
+
+## S5 — Contributor Fork Branch Deletion
+
+Setup: "Close out feat-fork with --delete-fork-branch."
+
+Expected:
+- Differentiates canonical remote from contributor fork remote.
+- Deletes remote branch on `<fork>` using `git push --delete <fork> <branch>`.
+- Strictly refuses to delete topic branches from canonical remote or delete canonical base branch.
+
+## Baseline Failure Modes to Watch For (RED)
+- Deleting an unmerged branch without checking ancestry or PR evidence.
+- Running `rm -rf` on a registered worktree instead of `git worktree remove`.
+- Deleting dirty worktrees without user consent.
+- Running `git push --delete` against the canonical repository.

package/skills/git/branch-closeout/references/closeout-checklist.md

@@ -0,0 +1,81 @@
+# Branch and Worktree Closeout Checklist
+
+This reference provides the verification steps, safety invariants, and reporting requirements for `branch-closeout`.
+
+## 1. Landing Evidence Verification
+
+Never delete a branch or remove a worktree based on matching commit subjects alone. Require deterministic proof of integration on the canonical base branch:
+
+### Merge Commits and Fast-Forwards
+```bash
+git fetch --prune <canonical>
+git merge-base --is-ancestor <branch> <canonical>/<base>
+```
+If the command exits 0, the branch tip is fully contained in the base branch history.
+
+### Squash Merges and Cherry-Picks
+A squash merge generates a new commit with a different tree SHA and patch identity; the ancestry test will fail. Prove integration via PR evidence:
+```bash
+gh pr view <branch> --repo <canonical> --json state,mergedAt,mergeCommit -q '{state: .state, merged: .mergedAt, commit: .mergeCommit.oid}'
+```
+Verify that the `mergeCommit.oid` exists in `<canonical>/<base>`:
+```bash
+git branch -r --contains <mergeCommit.oid> | grep -E "(^|\s)<canonical>/<base>$"
+```
+
+## 2. Worktree State Inspection
+
+Before unregistering a worktree, ensure no valuable untracked or ignored artifacts are discarded:
+1. Locate the registered worktree path:
+   ```bash
+   git worktree list --porcelain
+   ```
+2. Check for uncommitted changes:
+   ```bash
+   git -C <worktree-path> status --porcelain
+   ```
+3. Check for untracked and ignored files:
+   ```bash
+   git -C <worktree-path> status --ignored --porcelain
+   ```
+4. If non-rebuildable files (e.g. unpushed experiment logs, scratch scripts, local databases) are present, halt and request user confirmation via `ask_user` before proceeding.
+
+## 3. Worktree Removal
+
+- Always remove registered worktrees using Git:
+  ```bash
+  git worktree remove <worktree-path>
+  ```
+- **Never use raw filesystem deletion (`rm -rf`)** on registered worktrees, which leaves corrupted records in `.git/worktrees/`.
+- Use `--force` only when the user has explicitly authorized discarding uncommitted changes or untracked artifacts.
+
+## 4. Local Branch Deletion
+
+- Delete the local branch safely:
+  ```bash
+  git branch -d <branch>
+  ```
+- If git warns that the branch is not fully merged (common after squash merges), do not blindly force-delete. Verify the squash commit on the base branch, inform the user, and use `git branch -D <branch>` only upon explicit confirmation.
+
+## 5. Contributor Fork Branch Cleanup
+
+- If `--delete-fork-branch` was requested:
+  - Verify that `<fork>` is indeed the contributor's fork remote and NOT the canonical repository.
+  - Delete the remote topic branch:
+    ```bash
+    git push --delete <fork> refs/heads/<branch>
+    ```
+  - **Invariants**:
+    - Never delete branches from the canonical remote.
+    - Never delete canonical base branches (`main`, `master`).
+    - Never delete tags or stashes implicitly.
+
+## 6. Post-Closeout Inventory Report
+
+Always audit and report surviving repository state:
+1. **Registered worktrees**: `git worktree list`
+2. **Local branches**: `git branch`
+3. **Stashes**: `git stash list`
+4. **Local-only tags**: tags that do not exist on the canonical remote
+5. **Canonical remote heads**: `git ls-remote --heads <canonical>`
+   - In a canonical-main-only repository, the expected canonical head set is strictly `refs/heads/main`. Any extra head is flagged as an anomaly.

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

@@ -1,22 +1,23 @@
 ---
 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.
+description: "Turns something noticed mid-session into a tracker issue: captures evidence, dedups against existing issues, composes a labeled issue with acceptance criteria, confirms, and creates it via gh. Not for batch ticket creation from a PRD; use backlog. Not for diagnosing an existing issue; use fix-issue."
 triggers:
   - file a ticket
   - open an issue for this
   - log this bug
   - ticket this behavior
   - create a tracker issue
-version: 0.1.2
+version: 0.3.0
 license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (authenticated for issue operations), POSIX-compatible shell
 allowed-tools:
   - read
   - grep
   - ls
   - git
   - bash
+  - tasks
   - ask_user
-  - artifact
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/file-ticket
@@ -30,83 +31,96 @@ clio-coder:
 
 # 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).
+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
+See [issue discovery](references/issue-discovery.md) for template, label, and milestone discovery details, and [issue template](assets/issue-template.md) for the default body layout.
 
-From the session that surfaced the behavior, record before anything scrolls
-away:
+## Arguments
 
-- **Type**: bug, enhancement, documentation, 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.
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
 
-Complete when every bullet above is either filled or explicitly marked
-unknown.
+```text
+/skill:file-ticket [--repo owner/repo] [--type type] [--milestone name] <observation>
+```
 
-## Step 2 — Dedup
+### Examples
+- `/skill:file-ticket settings overlay crashes when terminal is narrower than 40 columns`
+- `/skill:file-ticket --type bug --milestone v1.2 "memory leak in worker pool"`
+- `/skill:file-ticket --repo owner/custom-repo --type enhancement add dark mode support`
+
+### Positional Arguments
+- `<observation>`: Free-text description of the observed defect, symptom, or enhancement.
+  - Required if not already established in recent session conversation.
+  - If omitted, prompt the user for the observed behavior.
+
+### Options
+- `--repo <owner/repo>`: Target GitHub repository.
+  - Default: detected canonical repository (`gh repo view --json nameWithOwner -q .nameWithOwner` or Git remote tracking).
+  - Validation: Must match `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
+- `--type <type>`: Issue category.
+  - Allowed: `bug`, `enhancement`, `documentation`, `question` (or repository-defined issue types).
+  - Default: inferred from `<observation>` or confirmed with user via `ask_user`.
+- `--milestone <name>`: Open milestone to attach to the ticket.
+  - Default: none (or repository triage default).
+  - Validation: Must match an open milestone returned by the GitHub API.
+
+### Unknown Arguments and Safe Quoting
+- Unknown options must be rejected with an error; do not pass unknown flags to `gh`.
+- Never interpolate raw user strings into double-quoted shell command strings. Write the issue body to a temporary file and pass `--body-file "$tmpfile"` to prevent command substitution or backtick evaluation.
 
-```bash
-gh issue list --search "<key terms>" --state all --limit 20
-```
+## Step 1 — Capture
 
-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.
+From the session that surfaced the behavior, record before anything scrolls away:
+- **Type**: bug, enhancement, documentation, or question. Uncertain -> ask via `ask_user`; 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`. Stop after at most a few minutes of searching.
 
-## Step 3 — Compose
+Complete when every bullet above is either filled or explicitly marked unknown.
 
-- **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 2 — Resolve Repository and Dedup
 
-## Step 4 — Confirm
+1. Determine `--repo <owner/repo>` (provided flag or detected via `gh repo view`).
+2. Search for existing issues:
+   ```bash
+   gh issue list --repo <owner/repo> --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.
+3. **Open duplicate found**:
+   - Do NOT file a new issue.
+   - Compose a comment with the new evidence and repro details.
+   - **Mandatory confirmation**: Present the target issue URL and the exact comment text to the user via `ask_user`. Execute `gh issue comment <id> --repo <owner/repo> --body-file "$tmpfile"` ONLY after the user confirms.
+   - Report that issue's URL as the outcome and end.
+4. **Closed duplicate found**:
+   - Continue to file a new issue and link the closed issue in the body's Links section.
 
-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 3 — Discover Taxonomy and Compose
 
-## Step 5 — Create and hand off
+1. Discover repository issue templates, labels, and open milestones per [issue discovery](references/issue-discovery.md).
+2. Format the ticket:
+   - **Title**: conventional tag plus a specific imperative summary (`fix: ...`, `feat: ...`, `docs: ...`). Never a bare noun.
+   - **Body**: Problem (observed vs expected), Reproduce, Evidence (`file:line` pointers and session excerpts), Acceptance criteria as a verifiable checklist, and Links. Use [the standard template](assets/issue-template.md) when no repository template matches.
+   - **Labels**: one type label (`bug`, `enhancement`, etc.) plus applicable discovered area/component labels (`area:*`). Propose new labels to the user rather than creating them silently.
+   - **Milestone**: apply `--milestone` if specified and valid; otherwise leave unassigned.
 
+## Step 4 — Confirm Every Outward Action
+
+Show the full title, repository, labels, milestone, and complete body.
+Obtain explicit approval via `ask_user`. Issue creation is an outward-facing change; nothing is created before the user explicitly confirms.
+
+## Step 5 — Create and Hand Off
+
+Write the body to a file and execute:
 ```bash
-gh issue create --title "..." --body-file "$tmpdir/body.md" --label "..." [--milestone "..."]
+gh issue create --repo <owner/repo> --title "..." --body-file "$tmpfile" --label "..." [--milestone "..."]
 ```
+Run creation exactly once, verify with `gh issue view`, report the issue number and URL, and name the next pipeline step: `fix-issue`.
 
-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
+## Red Flags
 
 - Filing without the Step 2 dedup search.
+- Posting a comment on an existing duplicate without explicit user confirmation.
 - 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.
+- Passing raw user text in `gh issue create --body "..."` instead of using `--body-file`.
+- Creating repository labels or milestones nobody approved.
+- Batch-filing multiple tickets; that is `backlog`'s job.

package/skills/git/file-ticket/assets/issue-template.md

@@ -0,0 +1,22 @@
+<!-- Standard issue template used by file-ticket when the repository does not provide a custom .github/ISSUE_TEMPLATE -->
+
+## Problem
+<!-- What actually happened vs what was expected -->
+**Observed**:
+**Expected**:
+
+## Reproduction
+<!-- Exact commands, inputs, or steps that reproduced the behavior; marked 'unverified' if not personally executed -->
+1. 
+
+## Evidence
+<!-- Code pointers (file:line), error messages, or logs observed during the session -->
+- `path/to/file.ext:line`: Description of relevant code or error
+
+## Acceptance Criteria
+<!-- Verifiable criteria that confirm the issue is resolved -->
+- [ ] 
+
+## Links & Context
+<!-- Duplicate or related issue links, PR links, or documentation references -->
+-