@erclx/aitk 0.8.0

package/claude/skills/git-commit/references/commit.md

@@ -0,0 +1,63 @@
+---
+title: Commit reference
+description: Commit message format and type conventions
+consumers: git-commit, git-stage
+---
+
+# Commit message reference
+
+## Format
+
+- Structure: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Subject: 72 characters maximum, no trailing period
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Scope
+
+- Single lowercase word representing a system component
+- Prefer single word
+- Use kebab-case only when two words are genuinely needed for specificity
+- Do not use specific filenames as scopes
+- Do not use a scope that duplicates the type
+- Write scopes for release readability. They surface in `changelogithub` release notes.
+
+## Subject
+
+- Use imperative mood (`add` not `added`)
+- Describe the actual technical change, not that something changed
+- Do not use vague verbs (`improve`, `refine`, `enhance`)
+- Do not repeat the scope in the subject line
+- Use single quotes if quoting
+- No backslash escaping or internal double quotes
+- No conversational filler or introductory phrases
+
+## Examples
+
+### Correct
+
+```plaintext
+feat(api): add retry logic for failed webhooks       # specific verb + clear change
+fix(auth): update 'UserSession' validation logic     # scoped + imperative + single quotes
+```
+
+### Incorrect
+
+```plaintext
+fix(user-auth): Fixed the redirect loop.    # wrong casing + period + multi-word scope
+docs(docs): update the readme.              # duplicate scope + period
+docs(api): improve documentation            # vague verb + lacks specificity
+```

package/claude/skills/git-followup/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: git-followup
+description: What the follow-up push is for, the gaps it closes, and how it splits from opening a pull request
+---
+
+# Git followup requirement
+
+## Gap
+
+Without this skill, an edit made after a pull request is already open ships as a bare push. The body still describes the scope from before the edit, so a reviewer returning to the page reads a description the diff no longer matches. A reviewer who left comments gets no reply, and when a caller has already posted its own reply, a second one lands underneath it.
+
+## Must
+
+- Refuse unless the branch has an upstream and an open pull request, since every later step addresses one of the two
+- Delegate the message to `git-commit` rather than composing one, so a follow-up commit reads like every other commit
+- Sync the body when the new commit moves the scope, and the title when the shift makes it inaccurate
+- Reply on the pull request when it carries review comments, and scan that reply for the banned characters before posting. The hook watches files and never sees a comment body on its way to the remote.
+- Suppress the reply when the caller owns it, and still run the push and the body sync
+
+## Must not
+
+- Run on `main`
+- Open a pull request. A missing one is the stop condition, not a step to add.
+- Post a second reply when the caller has already replied
+- Emit anything after the result line
+
+## Guards
+
+- On `main`: stop and say to switch to a pull request branch
+- Nothing changed: stop
+- No upstream: stop and name both recoveries
+- No open pull request: stop and route to the skill that opens one
+
+## Out of scope
+
+- Opening the pull request, which `git-pr` owns and `git-ship` chains
+- Deciding what to fix from a review, which `claude-address-review` owns. This skill is that flow's push leg and takes the fixes as already made.
+- Grouping a multi-concern diff, which `git-stage` owns. A follow-up is one concern by definition, which is why this skill stages everything into a single commit.

package/claude/skills/git-followup/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: git-followup
+description: Ships a small self-review edit on the current PR branch by staging, committing, pushing, and syncing the open PR, replying on the PR when it carries review comments. Use when asked to "ship a followup", "push the PR fix", "followup", or "commit and push this small change". Do NOT use when there is no open PR for the branch (use git-ship instead).
+---
+
+# Git followup
+
+Ship a small self-review edit on the current PR branch in one pass.
+
+When invoked with `reply-owned`, a caller such as `claude-address-review` posts
+its own reply, so skip the comment in step 6. The push and body sync still run.
+
+## Guards
+
+- If `git branch --show-current` returns `main`, stop: `❌ On main. Switch to a PR branch first.`
+- If `git status --porcelain` is empty, stop: `❌ No changes to ship.`
+- If `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, stop: `❌ No upstream. Push the branch first or use git-ship.`
+- If `gh pr view --json state -q '.state' 2>/dev/null` is not `OPEN`, stop: `❌ No open PR for this branch. Use git-ship to open one.`
+
+## Sequence
+
+1. Run `git status` to confirm the changes are intentional
+2. Run `git add -A` to stage every change
+3. Invoke `aitk:git-commit` to generate one conventional commit from the staged diff
+4. Run `git push` to the tracking branch
+5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
+6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first scanning it for em dashes and semicolons and rewriting each since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
+
+## After completion
+
+Output one line:
+
+```plaintext
+✅ Followup shipped: <pr-url>
+```

package/claude/skills/git-issue/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: git-issue
+description: What issue filing is for, the gaps it closes, and which reporting paths belong elsewhere
+---
+
+# Git issue requirement
+
+## Gap
+
+Without this skill, an issue takes the shape of whatever the session was saying. It arrives with no label, so triage cannot filter it, and without the sections a triage pass reads, so the reader has to reconstruct the problem from narrative. Prose bans hold on files the hook watches and not on text leaving through `gh`, so a banned character survives into a published artifact that then has to be edited on the remote.
+
+## Must
+
+- Read the issue reference and the prose standard before formatting
+- Confirm a remote and an authenticated `gh` before composing, so the failure lands before a body is written rather than after
+- Scan the title and body for banned characters as an explicit step. Reading the standard does not catch them, because the text is generated after the read.
+- Map the type to exactly one label, so filing and filtering agree
+- Ask once when the type is ambiguous between a bug and a task, since the label follows from it and a wrong label buries the issue
+- Pass the body through a file and remove it afterward, so shell quoting cannot mangle it
+
+## Must not
+
+- Invent an issue from a thin session. Nothing concrete in context is a stop rather than a prompt to elaborate.
+- File anywhere other than the current origin
+- Open a pull request
+- Emit anything after the result line
+
+## Guards
+
+- No concrete bug or task in session context: stop and say what to provide
+- No remote: stop and name what `gh issue create` needs
+- `gh` not authenticated: stop and name the command that authenticates
+
+## Out of scope
+
+- Reporting a toolkit defect from a target project, which `toolkit-feedback` owns. That path writes into the toolkit rather than the current repository.
+- Triaging issues already filed, which `toolkit-triage` owns
+- Opening a pull request, which `git-pr` owns

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

@@ -0,0 +1,69 @@
+---
+name: git-issue
+description: Format a bug or task from the current session into a GitHub issue and file it on the current repo via `gh issue create`. Use when asked to "file an issue", "open an issue", "log this bug", "raise an issue", or "track this as an issue". Do NOT use to report a toolkit defect from a target project (that is `toolkit-feedback`), or to open a pull request (that is `git-pr`).
+---
+
+# Git issue
+
+Format an issue from session context following the issue standard, then file it on the current repository with `gh issue create`.
+
+## Context
+
+Read these in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/issue.md`: issue title, labels, body sections, and banned phrases
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+Then gather repo context in parallel:
+
+- `git remote get-url origin 2>/dev/null || echo "NO_REMOTE"`
+- `gh auth status >/dev/null 2>&1 && echo "AUTHED" || echo "NO_AUTH"`
+
+## Guards
+
+- If nothing in session context describes a concrete bug or task, stop: `❌ No issue in session context. Describe the bug or task, then re-invoke.`
+- If `git remote get-url origin` returns `NO_REMOTE`, stop: `❌ No GitHub remote. gh issue create needs an origin.`
+- If `gh auth status` returns `NO_AUTH`, stop: `❌ gh is not authenticated. Run gh auth login.`
+- If the type is ambiguous between a bug and a task, ask one line before formatting.
+
+## Response format
+
+### Preview
+
+- **Title:** `<type>: <subject>`
+- **Label:** <bug or enhancement>
+- **Analysis:** <one line on what the issue captures>
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Pre-publish scan
+
+Before running the final command, scan the title and body for banned characters and rewrite each occurrence:
+
+- `—` (em dash): split into two sentences or use a comma
+- `;` (semicolon): split into two sentences
+
+These bans come from `.claude/standards/prose.md`. Reading it is not enough. The scan is an explicit step.
+
+### Final command
+
+Map a bug to `--label bug` and a task to `--label enhancement`.
+
+```bash
+mkdir -p .claude/.tmp/issue
+cat <<'BODY' > .claude/.tmp/issue/body.md
+<body following the issue.md sections>
+BODY
+gh issue create --title "<type>: <subject>" --label <bug or enhancement> --body-file .claude/.tmp/issue/body.md
+rm -rf .claude/.tmp/issue
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Issue: <url>`
+
+Do not add any other text.

package/claude/skills/git-issue/references/issue.md

@@ -0,0 +1,84 @@
+---
+title: Issue reference
+description: GitHub issue title, labels, and body conventions
+consumers: git-issue
+---
+
+# Issue reference
+
+## Title
+
+- Format: `<type>: <subject>`
+- Type is `bug` or `task`. Lowercase the type and the first word of the subject.
+- Length: 72 characters maximum, no trailing period.
+
+## Labels
+
+- Apply `bug` for a defect and `enhancement` for a task or improvement.
+- Both are GitHub default labels. A label that does not exist makes `gh` reject the issue. Create it once with `gh label create`.
+- One label per issue unless a second genuinely applies.
+
+## Content
+
+- Use imperative mood and describe the actual defect or work, not that something is wrong.
+- Do not open with "This issue," "I want," or "We should."
+- Do not use buzzwords or speculative future scope.
+- State observable behavior for a bug, not a guessed cause.
+
+## Sections
+
+- `## Summary`: one line naming what and why.
+- `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
+- `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
+- `## Proposed` (optional): one line naming a fix or approach. Omit when open.
+
+## Formatting
+
+- End every bullet with a period.
+- Keep each section to one or two lines.
+
+## Examples
+
+### Correct (bug)
+
+```markdown
+## Summary
+
+Fix the feedback CLI so it applies the `feedback` label.
+
+## Details
+
+`aitk feedback --github` opens an issue with no label, so `toolkit-triage` never lists it.
+
+## Context
+
+Run a piped `aitk feedback --github`, then check the issue carries no `feedback` label.
+
+## Proposed
+
+Pass `--label feedback` through the shared issue helper.
+```
+
+### Correct (task)
+
+```markdown
+## Summary
+
+Add a git-issue skill so a session can file an issue on the current repo.
+
+## Details
+
+Format an issue from session context and file it with `gh issue create`, next to git-pr in the git family.
+
+## Context
+
+The toolkit-issue skill only files on the toolkit repo. A general path is needed for target projects.
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This issue is about the feedback system being kind of broken, and we should probably make it more robust.
+```

package/claude/skills/git-pr/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: git-pr
+description: What pull request generation is for, the gaps it closes, and what it requires upstream of itself
+---
+
+# Git PR requirement
+
+## Gap
+
+Without this skill, a pull request body is written from memory of the branch rather than from its diff, so it describes the intent and omits what the work turned into. Testing boxes get ticked from intent, which records what was meant to run instead of what ran, and a reviewer trusts the list. A second push either errors on create or opens a duplicate pull request, and banned characters survive into a body the hook never sees.
+
+## Must
+
+- Refuse a branch name that does not conform, since the name lands on the pull request permanently and renaming it afterward breaks the link
+- Derive the title and body from the commits and the diff against main, with lockfiles excluded
+- Run each check before writing its line, then state the result the run reported
+- Leave a box unchecked only for a human-only case, naming which human and why on the same line
+- Scan the title and body for banned characters as an explicit step, on top of reading the prose standard
+- Detect an open pull request and edit it in place, so a follow-up push keeps the body in sync instead of failing
+
+## Must not
+
+- Tick a testing box from intent or from a past session. The box records a run.
+- Put a request for the reviewer in the Testing list, since a request is not a result
+- Create a second pull request when one is open
+- Emit anything after the result line
+
+## Guards
+
+- Branch name does not conform: stop and route to the skill that renames
+- No commits ahead of main: stop
+
+## Out of scope
+
+- Naming the branch, which `git-branch` owns. This skill requires a conforming name and refuses without one rather than fixing it.
+- Grouping the diff into commits, which `git-stage` owns
+- Pushing a later edit onto an already-open pull request, which `git-followup` owns. The overlap is real and the split is by state: this skill brings a pull request into existence and keeps it accurate, that one carries a fix onto one already under review.

package/claude/skills/git-pr/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: git-pr
+description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update.
+---
+
+# Git PR
+
+## Context
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/branch.md`: branch format, valid types, and constraints
+- `${CLAUDE_SKILL_DIR}/references/pr.md`: structure, rules, and banned phrases
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `.claude/standards/versioning.md` from the project root: phase label vs semver discipline
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+Resolve the base ref first, because the log range and the diff below both consume it:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Then run these commands in parallel to gather git context:
+
+- `git remote get-url origin 2>/dev/null || echo "NO_REMOTE"`
+- `git branch --show-current 2>/dev/null || echo "unknown"`
+- `git log <base>..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
+- `git diff <base> HEAD -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+
+## Diff baseline
+
+Prefer `origin/main` over local `main`. Both reads resolve against `<base>`, so the commits listed and the changes described come from one scope.
+
+`git diff main..HEAD` is the form the diff replaces. A two-dot range compares tips and resolves no merge base, so once local `main` advances past the branch point it reports main's newer commits as reversed changes and the description describes work the branch never did. On `main` itself the local ref resolves to HEAD and every committed change drops out instead.
+
+`git log main..HEAD` is the matching defect on the commit side. It excludes what local `main` reaches, so a local `main` trailing `origin/main` leaves commits in the range that are already on the remote and are not this branch's work. The diff resolved from `<base>` excludes those same commits, and the description then lists commits whose changes appear nowhere in it. Reading both against `<base>` is what keeps the two halves describing one branch.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against.
+
+Either case leaves both reads empty, which the no-commits guard below catches. Stop there rather than composing a description from an empty diff.
+
+## Guards
+
+- If branch name does not match `<type>/<description>` format (valid types are defined in `${CLAUDE_SKILL_DIR}/references/branch.md`), stop and output:
+  `❌ Branch name does not follow conventions. Run /git-branch to rename first.`
+- If no commits ahead of main, stop and output:
+  `❌ No commits ahead of main. Nothing to PR.`
+
+## Response format
+
+### Preview
+
+- **Title:** <title>
+- **Files changed:** <count>
+- **Analysis:** <brief summary of impact>
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Testing checkboxes
+
+Follow Testing discipline in `${CLAUDE_SKILL_DIR}/references/pr.md`. Run each check before writing its line, then tick the box and state the result the run reported. Never pre-check based on intent or past sessions.
+
+Leave a box unchecked only for the human-only cases the reference defines, and name which human and why on the same line. A request for the reviewer is not a test result, so it belongs under `## For the reviewer` rather than in the Testing list.
+
+### Pre-publish scan
+
+Before running the final command, scan the PR title and body for banned characters and rewrite each occurrence:
+
+- `—` (em dash): split into two sentences or use a comma
+- `;` (semicolon): split into two sentences
+
+These bans come from `.claude/standards/prose.md` and apply to PR text on top of `${CLAUDE_SKILL_DIR}/references/pr.md`. Reading `prose.md` is not enough. The scan is an explicit step.
+
+### Final command
+
+Detect an existing PR and branch: edit it in place when one is open, create it otherwise. This keeps the body in sync on a follow-up push instead of erroring on `gh pr create`.
+
+```bash
+mkdir -p .claude/.tmp/pr
+cat <<'BODY' > .claude/.tmp/pr/body.md
+<body content following pr.md template exactly>
+BODY
+git push -u origin HEAD || exit 1
+if gh pr view --json number >/dev/null 2>&1; then
+  gh pr edit --title "<title>" --body-file .claude/.tmp/pr/body.md
+else
+  gh pr create --title "<title>" --body-file .claude/.tmp/pr/body.md
+fi
+rm -rf .claude/.tmp/pr
+```
+
+### Record the number on the task
+
+Resolve the number the run created or edited, then write it onto the task the branch is closing:
+
+```bash
+gh pr view --json number --jq .number
+```
+
+Find the task by reading `.claude/tasks/` at the main worktree root, resolved with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The board is shared scratch, so a linked worktree writing to its own `pwd` creates a second board nothing reads.
+
+Confirm the match against the task's `Plan:` line, which names the plan this branch implemented. A branch name does not derive a plan slug and a plan slug does not derive a branch, so neither one alone identifies the task. Add `Pull request: #NNN` under the existing `Plan:`, `Groundwork:`, or `Issue:` lines when the task carries no such line, and correct the number in place when it does.
+
+Skip this silently in three cases: no `.claude/tasks/` folder, no task whose `Plan:` line matches, or more than one match. One task, one pull request, so a second match is a misfile that a guessed write would compound. A wrong match archives the wrong task unattended once the branch merges.
+
+The number is what lets the merge close the task. Every merge on `main` is a squash carrying it in the subject, so the number survives where a branch name does not, and `post-merge` reads it back to call `aitk tasks archive`. Writing it here rather than at worktree time is what makes it a pull request number rather than a branch the squash discards.
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ PR: <url>`
+
+Do not add any other text.

package/claude/skills/git-pr/references/branch.md

@@ -0,0 +1,49 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+consumers: git-branch, git-split, git-pr, claude-standards-audit
+---
+
+# Branch reference
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/claude/skills/git-pr/references/pr.md

@@ -0,0 +1,124 @@
+---
+title: Pull request reference
+description: Pull request title and body conventions
+consumers: git-split, git-pr, claude-standards-audit
+---
+
+# Pull request reference
+
+## Title
+
+- Format: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Length: 72 characters maximum
+
+## Content
+
+- Use imperative mood for all content (`add`, `fix`, `refactor`)
+- Do not start with "This PR," "This commit," "Included are," or "I have"
+- Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
+- Do not describe historical behavior or unchanged code. Describe new behavior only.
+- Do not include future promises or speculative documentation
+- Do not explain obvious changes (formatting, renaming variables)
+- Do not duplicate commit messages verbatim
+
+## Sections
+
+- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
+- `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+- Omit Technical Context for docs, config, or trivial changes
+- Use bullet points for multiple reasons, one sentence for a single reason
+- `## Testing` (optional): specify exact commands or test cases run
+- Omit Testing for docs, config, or trivial sync changes
+- Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
+- Visuals: include only when they clarify architecture, UI, or complex logic flows
+
+## Testing discipline
+
+- Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
+- Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
+- Quote the count or output the run reported, never a figure carried from elsewhere.
+- Leave a box unchecked only when a human is required, and name which human and why on the same line.
+- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
+- Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
+
+## Formatting
+
+- End every bullet point with a period
+
+## Examples
+
+### Template
+
+```markdown
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+## Technical Context
+
+- <Architectural reasoning explaining why, not what>
+
+## Testing
+
+- [x] <Command run> <observed result>
+- [x] <Edge case verified> <what was observed>
+- [ ] <Human-only check> (<which human, why>)
+
+## For the reviewer
+
+- <What the reviewer should confirm>
+```
+
+### Correct
+
+```markdown
+## Summary
+
+Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
+
+## Key Changes
+
+- Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
+
+## Technical Context
+
+- Migration to stateless session management for horizontal scalability. # why, not what
+
+## Testing
+
+- [x] `npm run test:auth` passes, 42 tests. # command run + observed result
+- [x] Expired token rejected with a 401 against a local server. # edge case + what happened
+- [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
+
+## For the reviewer
+
+- Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
+
+## Key Changes
+
+- Updated auth middleware files # vague, no specific component, no period
+- The old system used to check tokens differently # describes historical behavior
+
+## Testing
+
+- Tested manually # no specific command or case
+- [ ] `npm run test:auth` # unchecked box for a check the agent can run
+- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+```