janissary 0.5.0 → 0.5.2

package/ai/tasks/improve-style.md

@@ -0,0 +1,147 @@
+# Improve CSS Style (one fix per run)
+
+Your job: run the CSS linter, pick the single most valuable fix, assess its risk, and either apply it yourself or ask the user to approve it. Do exactly **one fix**, then verify.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Verify the baseline is green
+
+Run all three and read all output:
+
+```bash
+npx tsc --noEmit 2>&1
+npm test 2>&1
+npm run lint:css 2>&1
+```
+
+Record:
+- **Compiler:** must finish with **no errors**. If it errors, STOP and tell the user.
+- **Tests:** every test must pass. If any test is already failing, STOP and tell the user — do not fix CSS on a broken suite.
+- **CSS lint (`npm run lint:css`):** copy out the full finding list — every line. Write down the total count. **If there are no findings, report "No CSS issues found" and stop.**
+
+Always run these fresh. Do not trust earlier output in the conversation.
+
+---
+
+## Step 2 — Rank the findings
+
+Read the `npm run lint:css` output. Each finding looks like:
+
+```
+web/src/theme.css
+  137:27  ✖  Expected modern color-function notation   color-function-notation
+```
+
+Group findings by **stylelint rule name** (the last token on each line). For each rule, count how many findings it contributes.
+
+Rank from most valuable to fix first, using this order of priority:
+
+1. **Correctness** — deprecated values (`declaration-property-value-keyword-no-deprecated`), invalid syntax, unknown properties.
+2. **Modernisation** — outdated but valid notation (`color-function-notation`, `alpha-value-notation`, `color-function-alias-notation`, `value-keyword-case`).
+3. **Convention** — style rules the config-standard enables and that aren't purely about whitespace.
+
+Within each tier, prefer the rule with the **most findings** (highest bang-for-buck per edit).
+
+Write out your ranked list before picking.
+
+---
+
+## Step 3 — Pick exactly one rule to fix
+
+From the ranked list, pick the **top rule** — the highest-priority finding with the most occurrences.
+
+State: the rule name, how many findings it has, and in one sentence what the fix is.
+
+---
+
+## Step 4 — Plan the fix
+
+Write out every individual change the fix requires:
+
+- For each finding, the **file**, the **line**, what the current code is, and what it becomes.
+- If `--fix` can apply the change automatically, say so.
+
+Keep the diff as small as possible — do not reformat or tidy unrelated lines.
+
+---
+
+## Step 5 — Assess risk and decide
+
+Rate the plan **Low risk** or **High risk** using these criteria.
+
+**Low risk** (apply automatically, without asking):
+- The change is a mechanical substitution: rewriting a color notation, quoting a font name, replacing a deprecated keyword with its modern equivalent.
+- `--fix` applies it, or each change is a literal find-and-replace within the CSS file.
+- Zero TypeScript, zero test files, zero config files are touched.
+- The visual result in the browser is identical — no layout, color, or spacing change.
+
+**High risk** (skip and pick the next rule):
+- The fix could change rendered output — for example, changing a `color` value where the browser interprets the old and new forms differently, changing a `font-family` ordering, or restructuring a selector.
+- More than one file must be edited.
+- You are unsure whether the old and new forms are semantically identical.
+- The fix requires deleting or restructuring a rule block, not just rewriting a value.
+
+If **High risk**: do **not** apply the fix and do **not** ask the user. Go back to Step 3, remove this rule from the ranked list, and pick the next-ranked rule. If every rule is High risk, list all of them in your report under "Skipped (high risk)" and stop without making any changes.
+
+If **Low risk**: proceed directly to Step 6 without asking.
+
+---
+
+## Step 6 — Apply the fix
+
+**Back up the file first:**
+
+```bash
+cp web/src/theme.css web/src/theme.css.bak
+```
+
+Apply the fix:
+
+- If `--fix` covers it: run `npm run lint:css:fix`, then inspect the diff to confirm only the intended lines changed. If the diff touches anything unexpected, restore the backup and report what happened.
+- If manual: edit the file directly, changing only the lines listed in your plan.
+
+---
+
+## Step 7 — Verify (run in this order; everything must be green)
+
+```bash
+npx tsc --noEmit 2>&1
+npm test 2>&1
+npm run lint:css 2>&1
+```
+
+1. **Compiler — no errors.** If a type error appeared, the CSS change somehow affected a TypeScript file that wasn't supposed to change. Restore the backup and report.
+2. **Tests — all pass.** If a test fails, restore the backup and report. Never edit a test to make it pass.
+3. **CSS lint — the rule you fixed no longer appears.** The finding count must be lower than Step 1. If the same findings are still there, your fix did not take effect — restore the backup and report.
+
+When all three pass, delete the backup: `rm web/src/theme.css.bak`.
+
+---
+
+## Step 8 — Report
+
+```
+Rule fixed:    <rule name, or "none — all rules were high risk">
+Findings:      <count before> -> <count after>
+Changes:       <one line per edit: file:line old → new, or "none">
+Skipped:       <rules skipped as high risk, or "none">
+Tests:         all pass / <what failed>
+```
+
+Keep it brief. Done.

package/ai/tasks/improve-test-coverage.md

@@ -0,0 +1,178 @@
+# Improve Test Coverage (one file per run)
+
+Your job: add tests that raise this project's test coverage. Do exactly **one file's worth** of new tests, then verify it worked.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early if the project isn't green before you start (Step 1), or if every remaining candidate target is blocked (see "Blocked work" below).
+
+## What you may and may not do
+
+### Safe work — DO IT AUTOMATICALLY, never ask
+
+This work is always allowed. When your plan contains **only** safe work, you **must carry it out yourself, start to finish, without stopping.** Do **not** ask "Do you want me to proceed?". Do **not** pause to show the plan for approval. Do **not** wait for confirmation. Just write the tests and run them.
+
+Safe work is:
+
+- **Creating new test files** named `*.test.ts` or `*.test.tsx`, placed next to the file they test.
+- **Adding new `it(...)` / `describe(...)` blocks** to an existing test file.
+- Using a small mock for a **single** function or value when a test needs one.
+
+### Blocked work — skip and pick a different target
+
+Do **not** attempt any of the following. If your plan for the chosen file requires one of these, **go back to Step 3** and pick the next-lowest file instead. Never ask the user — just skip and move on.
+
+1. Editing, deleting, or rewriting an **existing test**.
+2. Changing **any file that is not a `*.test.ts(x)` file** (for example, editing real source code "to make it testable").
+3. Replacing a **whole module** with a mock (e.g. `vi.mock('./something.js')` for a module that many files import).
+4. Testing **security, password/crypto, shell command, PTY/terminal, or network** code (applies to `src/` files only — `web/src/` files have no restrictions).
+5. Writing **more than 3** new test files in one run.
+
+If every remaining candidate is blocked, report what you found (file, why it was blocked) and stop without writing any tests.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Run coverage and lint
+
+Run both commands and read all of their output:
+
+```bash
+npm run coverage 2>&1
+npm run lint 2>&1
+```
+
+Always run them fresh. Do not trust an old `coverage/` folder or earlier output in the conversation.
+
+- **Tests:** `npm run coverage` executes the whole test suite. Every test must be passing before you add anything. If any test is already failing, STOP and tell the user — do not build on a broken suite.
+- **Lint:** note the summary line — `✖ N problems (E errors, W warnings)`. Write down E and W. There must be **0 errors** to proceed. Warnings are pre-existing guidance and are expected.
+
+---
+
+## Step 2 — Read the coverage table
+
+At the bottom of the Step 1 output is a table with one row per file. The columns are:
+
+```
+File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
+```
+
+The **right-most column ("Uncovered Line #s")** lists the exact line numbers that have no test. This is all the information you need. **You do not need to open or parse `coverage/coverage-final.json`.**
+
+---
+
+## Step 3 — Pick exactly one target file
+
+Choose the target with this exact procedure:
+
+**First pass — `src/` (core logic):**
+
+1. Look at rows whose file path starts with **`src/`**.
+2. **Cross out** any row that is:
+   - `src/main.ts` (program entry point — nothing to test).
+   - `src/pty.ts` (only runs inside a real terminal).
+   - Already at **90% or higher** in the `% Lines` column.
+3. From the rows that remain, pick the **one with the lowest `% Lines`**.
+   - Tie? Pick the lower `% Branch`.
+   - Still tied? Pick the one with the most numbers in the "Uncovered Line #s" column.
+4. **Open that source file** and look at the uncovered lines from the table. If you discover the file can only run by launching a **real web browser (not JSDOM), a real terminal/PTY, a real network connection, or a real spawned program** (look for imports of `playwright`, `puppeteer`, `node-pty`, `ws`, `WebSocket`, or `child_process` / `node:child_process`), then skip it and go back to step 3 to take the next-lowest file.
+
+**Second pass — `web/src/` (frontend):**
+
+If **every `src/` row is crossed out** (all at ≥90% or blocked), repeat the procedure on rows whose file path starts with **`web/src/`**:
+1. **Cross out** any row already at **90% or higher** in the `% Lines` column.
+2. Pick the **one with the lowest `% Lines`** (same tie-breakers as above).
+3. **Open that source file.** No restrictions apply to `web/src/` files — proceed with testing any file you find.
+
+State your pick in one short paragraph: the file path, its current `% Lines`, and the uncovered line numbers you will target.
+
+---
+
+## Step 4 — Plan the tests (a quick note to yourself, then keep going)
+
+Jot down a short, plain list of the tests you will add. This is a note for yourself, not a message to send to the user — do **not** post it and wait for a reply.
+
+- One bullet per test: its name, the input you give it, and the output or behavior you expect.
+- Say which test file they go in. If no `*.test.ts` file exists next to the source file, you will create one.
+- If a test needs a mock, name the one function or value you will mock and what it returns. Keep mocks as small as possible so the real code still runs.
+
+Now check your plan against **What you may and may not do** above:
+
+- If any of points 1–5 applies → go back to Step 3 and pick a different file.
+- Otherwise (your plan is all **safe work**) → go straight to Step 5 and write the tests **now, on your own, without asking.**
+
+---
+
+## Step 5 — Write the tests
+
+Create or extend the test file. Match the project's existing style exactly:
+
+- Import test tools from vitest: `import { describe, it, expect } from 'vitest';` (add `vi` only if you mock).
+- **`src/` files:** Relative imports must end in `.js`, even though the source file is `.ts`. Example: to test `src/foo.ts`, import `from './foo.js'`.
+- **`web/src/` files:** Relative imports drop the extension. Example: to test `web/src/foo.ts`, import `from './foo'`.
+- Put the test file right next to the source file (same folder), named `<name>.test.ts` (or `.test.tsx` for a React component).
+
+Skeleton to copy:
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { functionUnderTest } from './FILENAME.js'; // .js on purpose
+
+describe('functionUnderTest', () => {
+  it('returns X when given Y', () => {
+    expect(functionUnderTest(Y)).toBe(X);
+  });
+});
+```
+
+---
+
+## Step 6 — Verify
+
+Run both commands again, in this order:
+
+```bash
+npm run lint 2>&1
+npm run coverage 2>&1
+```
+
+Fix any lint issues before looking at coverage — a lint error in a new test file will also distort the coverage output.
+
+Then check, in this order:
+
+1. **Lint is no worse** — errors must be 0 (same as Step 1). Warnings must be equal to or fewer than Step 1. If a new lint error or warning appeared in a file you added or edited, fix it in that file. Do **not** suppress with `eslint-disable` — fix the underlying code.
+2. **The whole test suite passes** — every test, including ones you did not write. Adding tests must **never** make a previously-passing test fail.
+   - If one of **your new** tests fails because the test itself is wrong, fix the test and re-run.
+   - If a test fails because the real source code looks buggy, do **not** change the source — stop and report the suspected bug to the user.
+   - If you broke a previously-passing test, or the suite will not go green without editing source code or other tests, **delete the test file(s) you added** and report what blocked you. Never edit source or existing tests just to make the suite pass.
+3. **Coverage went up** — the target file's `% Lines` is higher than in Step 2.
+
+---
+
+## Step 7 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Target file: <path>
+Tests added: <count> in <test file path>
+% Lines:    <before> -> <after>
+% Branch:   <before> -> <after>
+Lint:       <before E errors, W warnings> -> <after>
+Tests:      all pass / <what failed>
+```
+
+Keep it brief. Done.

package/ai/tasks/merge-change-to-master.md

@@ -0,0 +1,144 @@
+# Merge a Workspaced Change to master
+
+Your job: take the code changes present in this workspaced tab, package them into a pull request against `master` on GitHub, and **merge it once there are no conflicts** — rebasing past any conflicts. Do not wait on PR checks before merging.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+The changes may have been made manually or produced by a preceding task — either way, this runs in a workspaced agent tab. That tab is a disposable, independent `git clone` of the root repo's `origin` remote living under `.janissary/workspace/<name>/`, so **its `origin` already points at GitHub.**
+
+Every step is a script in `scripts/pr-*.sh`, invoked through the script runner. The steps below contain **no inline shell logic** — each one invokes its script.
+
+**Always run scripts in the foreground.** Never use `run_in_background` — each script must complete and return its exit code before the next step begins.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to do any part of this task on your behalf.
+
+**Do not ask the user for input at any point.** Make all decisions autonomously — branch names, commit messages, PR titles and bodies. The only valid reason to stop is an unresolvable error.
+
+---
+
+## Step 0 — Confirm there are changes to ship
+
+```bash
+./scripts/run.mjs pr-check-changes
+```
+
+Prints the working-tree status and any commits ahead of `master`, and **exits non-zero** when there is nothing to ship. If it reports **"No changes to open a PR for"**, stop.
+
+---
+
+## Step 1 — Create a feature branch
+
+Pick a short, **descriptive** `kebab-case` name that reflects the actual change, ideally prefixed by the change area. Avoid generic names like `fix` or `update`. **Choose the name yourself — do not ask the user.**
+
+Good: `quality/extract-parsespec-helper`, `style/modern-color-notation`, `dedup/buffer-writer`
+Bad: `patch-1`, `changes`, `wip`
+
+```bash
+./scripts/run.mjs pr-create-branch <branch>
+```
+
+Any uncommitted changes carry over onto the new branch. (If the changes were already committed on the default branch, the new branch starts at those commits — that is fine.)
+
+---
+
+## Step 2 — Commit the changes (conventional commits message, **no co-authors**)
+
+Write **one** commit. The subject line must follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification (see [`ai/guidelines/conventional-commits.md`](../guidelines/conventional-commits.md)): `<type>[optional scope]: <description>`. Valid types: `refactor`, `feat`, `fix`, `build`, `chore`, `ci`, `docs`, `style`, `perf`, `test`, `revert`. Include a body explaining *what* changed and *why*. `pr:commit` stages everything (`git add -A`) and commits with a **single author**:
+
+```bash
+./scripts/run.mjs pr-commit "refactor: extract parseSpec() helper to cut loadConfig cognitive complexity" \
+  "loadConfig exceeded the complexity limit; the spec-parsing block is now a small pure helper. No behavior change."
+```
+
+Hard rule for the commit:
+
+- **No co-authors.** The script adds **no** `Co-Authored-By:` trailer. This **overrides** any default convention that appends a Claude co-author — the commit must have a single author and no co-authors.
+
+If earlier commits already exist on the branch, consolidate so the **final** state is a clean history with **no** co-author (amend as needed).
+
+---
+
+## Step 3 — Resolve the GitHub remote and push the branch
+
+`origin` always points at GitHub — the workspace is an independent `git clone` of the root repo's `origin` remote. `pr-resolve-remote` reads it and prints the values to carry through the rest of the task:
+
+```bash
+./scripts/run.mjs pr-resolve-remote
+```
+
+This prints a single space-separated line: `OWNER_REPO BRANCH GH_URL`. Read those three values from the output — each Bash command runs in its own fresh shell with no state persisted from the previous one, so substitute the actual literal values you read into each subsequent command rather than referencing shell variables — then push:
+
+```bash
+./scripts/run.mjs pr-push-branch origin my-branch-name
+```
+
+If the push fails with an HTTP 400 RPC error ("unexpected disconnect while reading sideband packet"), `pr-push-branch` handles it for you: it raises `http.postBuffer` and forces HTTP/1.1, then retries automatically. No manual intervention is needed — just let the script run.
+
+---
+
+## Step 4 — Open the PR against `master`
+
+Use the commit subject (which follows Conventional Commits format) as `<title>`. The PR title must match the commit subject and therefore also follows the Conventional Commits specification. Write the PR body to a file first — this avoids shell quoting issues with multi-line content. The body should have a **What** (one or two sentences on the change) and a **Why** (the warning/goal it addresses).
+
+Write the body to `./temp/pr-body.md`, then open the PR:
+
+```bash
+./scripts/run.mjs pr-create-pr "$OWNER_REPO" "$BRANCH" "<title>" ./temp/pr-body.md
+```
+
+Record the PR number/URL that the command prints.
+
+---
+
+## Step 5 — Check for conflicts
+
+GitHub computes conflict status asynchronously; `pr:check-mergeable` polls until it is known:
+
+```bash
+./scripts/run.mjs pr-check-mergeable "$BRANCH" "$OWNER_REPO"
+```
+
+- `MERGEABLE` → **no conflicts with master.** Go to **Step 7 (merge)**.
+- `CONFLICTING` → **conflicts with master.** Go to **Step 6 (resolve conflicts)**.
+
+---
+
+## Step 6 — Resolve conflicts against master (repeat up to 5 times)
+
+`pr:rebase` fetches `master`, rebases your branch onto it, re-runs the check gate, and force-pushes (with `--force-with-lease`) when the result is clean:
+
+```bash
+./scripts/run.mjs pr-rebase origin my-branch-name
+```
+
+- **Exit 0** → rebased cleanly and pushed. Re-check conflict status (Step 5); when `MERGEABLE`, go to Step 7 (merge).
+- **Exit 2** → it stopped on conflicts and listed the files. Open each, resolve the markers correctly (preserve the intent of *both* sides; never blindly drop master's changes), then **re-run the same command** — it continues the in-progress rebase.
+
+Run this loop **at most 5 times**. If the PR is **still conflicting after 5 attempts**, **STOP**: report that conflicts could not be resolved automatically and leave the PR open for a human.
+
+---
+
+## Step 7 — Merge the PR
+
+The PR is `MERGEABLE` (no conflicts). Squash-merge it and delete the remote branch — **do not wait on PR checks**; merge as soon as the PR is mergeable:
+
+```bash
+./scripts/run.mjs pr-merge "$BRANCH" "$OWNER_REPO"
+```
+
+If the merge fails, report the error and leave the PR open for a human.
+
+---
+
+## Step 8 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Branch:         <branch>
+PR:             <url> (#<number>)
+Conflicts:      none | resolved in <n> rebase attempt(s) | unresolved after 5 attempts
+Status:         merged | open (merge failed — see error above) | open (conflicts unresolved after 5 attempts)
+```
+
+Keep it brief. Done.

package/ai/tasks/open-feature-pull-request.md

@@ -0,0 +1,161 @@
+# Open a Feature Pull Request
+
+Your job: take the uncommitted work in this repository, package it into a well-described pull request against `master` on GitHub, and open it. **Do not merge the PR** — just open it with a thorough description so reviewers understand exactly what changed and why.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Do not ask the user for input at any point.** Make all decisions autonomously — branch name, commit message, PR title and body. The only valid reason to stop is "No changes to open a PR for" (Step 0) or an unresolvable error.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+## The PR description
+
+The PR body is the deliverable. It must be **thorough and self-contained** — a reviewer should understand the feature without reading the code. Write it to `./temp/pr-body.md`, then pass that file to the create-PR script.
+
+The body must include **every section below**, in this order:
+
+### What
+
+Three to five paragraphs explaining the feature. Cover:
+- What the feature does from the user's perspective
+- What problem it solves or workflow it enables
+- Which parts of the system it touches (server, web, both) and at a high level how it fits into the architecture
+- Any design decisions worth calling out (e.g. "we chose a ref pattern instead of lifting state because…")
+
+### Behavior examples
+
+Show the feature in action. Use **CLI transcripts** (for CLI/server features) or **reproducible user flows** (for UI features):
+
+```
+# Before — the old behavior, if applicable
+$ some-command --flag
+<output showing the old/wrong/missing behavior>
+
+# After — the new behavior
+$ some-command --flag
+<output showing the new/correct behavior>
+```
+
+For UI changes, describe the flow step by step: what the user clicks, what they see, what happens next. Use ASCII diagrams when spatial relationships matter.
+
+### How to verify
+
+A short list of manual verification steps a reviewer can follow. Keep each step concrete and testable — "open the app, run `foo`, confirm you see `bar`" rather than "make sure it works." Include edge cases: empty states, error paths, interactions with existing features.
+
+### Files changed
+
+A concise summary of every file touched, grouped by area (`src/`, `web/src/`, `web/src/theme.css`, tests), with a one-line description of what changed in each.
+
+---
+
+## Step 0 — Confirm there are changes to ship
+
+```bash
+./scripts/run.mjs pr-check-changes
+```
+
+Prints the working-tree status and any commits ahead of `master`, and **exits non-zero** when there is nothing to ship. If it reports **"No changes to open a PR for"**, stop.
+
+---
+
+## Step 1 — Make the check gate pass
+
+This is the end-of-work gate. Run the full check:
+
+```bash
+./scripts/run.mjs pr-check-gate
+```
+
+The gate runs **hard** checks only: typecheck, lint errors, tests, CSS. It does not run the advisory quality checks (complexity, duplication, dead code) — those belong to the human end-of-work gate (`npm run check:full`), not this automated step.
+
+The hard checks **must pass**. If they fail **because of the changes**, fix the offending code and re-run until green. If you cannot get them green, **STOP** — do not open a PR on a red gate — and report exactly what failed. Never weaken a test or lint rule to make a hard check pass.
+
+---
+
+## Step 2 — Create a feature branch
+
+Pick a short, **descriptive** `kebab-case` name that reflects the feature, ideally prefixed by the change area. **Choose the name yourself — do not ask the user.**
+
+Good: `feature/unread-badge`, `cli/help-version-flags`, `ui/transcript-click-prefill`
+Bad: `patch-1`, `changes`, `wip`
+
+```bash
+./scripts/run.mjs pr-create-branch <branch>
+```
+
+Any uncommitted changes carry over onto the new branch.
+
+---
+
+## Step 3 — Commit the changes (conventional commits message, **no co-authors**)
+
+Write **one** commit. The subject line must follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification (see [`ai/guidelines/conventional-commits.md`](../guidelines/conventional-commits.md)): `<type>[optional scope]: <description>`. Valid types: `feat`, `fix`, `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`, `revert`. Include a body explaining *what* changed and *why*. `pr-commit` stages everything (`git add -A`) and commits with a **single author**:
+
+```bash
+./scripts/run.mjs pr-commit "feat(ui): add unread badge on inactive tabs" \
+  "When a background tab receives new transcript content (messages, command output, shell completion), a sparkle badge appears on the tab strip. Focusing the tab clears it. Covers all content-delivery paths (append, finishRunning, shell onDone) and all activation paths (click, next, reorderTab, closeTab)."
+```
+
+Hard rule for the commit:
+
+- **No co-authors.** The script adds **no** `Co-Authored-By:` trailer. The commit must have a single author and no co-authors.
+
+If earlier commits already exist on the branch, consolidate so the **final** state is a clean history with **no** co-author (amend as needed).
+
+---
+
+## Step 4 — Resolve the GitHub remote and push the branch
+
+`origin` always points at GitHub — the workspace is an independent `git clone` of the root repo's `origin` remote. `pr-resolve-remote` reads it and prints the values later steps need:
+
+```bash
+./scripts/run.mjs pr-resolve-remote
+```
+
+This prints a single space-separated line: `OWNER_REPO BRANCH GH_URL`. Read those three values directly from the command's stdout output. Each Bash command runs in its own fresh shell with no state persisted from the previous one, so do not reference them as shell variables in later commands — substitute the actual literal values you read into each subsequent command:
+
+```bash
+./scripts/run.mjs pr-push-branch origin my-branch-name
+```
+
+---
+
+## Step 5 — Write the PR body
+
+Write the full PR body to `./temp/pr-body.md` following the structure at the top of this document:
+
+1. **What** — 3-5 paragraphs
+2. **Behavior examples** — CLI transcripts or user flows
+3. **How to verify** — concrete manual verification steps
+5. **Files changed** — grouped summary
+
+Use natural line breaks — never wrap lines at a fixed column.
+
+---
+
+## Step 6 — Open the PR against `master`
+
+Use the commit subject (which follows Conventional Commits format) as `<title>`. The PR title must match the commit subject and therefore also follows the Conventional Commits specification. Substitute the actual `OWNER_REPO` and `BRANCH` values you read in Step 4, and pass the body file:
+
+```bash
+./scripts/run.mjs pr-create-pr owner/repo my-branch-name "<title>" ./temp/pr-body.md
+```
+
+Record the PR number and URL that the command prints.
+
+---
+
+## Step 7 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Branch:         <branch>
+PR:             <url> (#<number>)
+Check gate:     pass (warnings allowed) | see errors above
+Status:         open
+```
+
+Keep it brief. Done.