@erclx/canon 4.0.0

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: docs-sync
+description: Scope boundary for consumer-facing prose against the agent-facing docs the ship chain syncs beside it
+---
+
+# Docs sync requirement
+
+## Gap
+
+Without this skill, a rename or a dropped flag ships with the README still describing the old surface. Nothing fails, because no test reads prose, so the doc stays wrong until a person hits it.
+
+Three failures belong to the sync itself rather than to the drift. A session that syncs by rewriting whole files churns sections the change never reached, which costs the reviewer the ability to tell the sync from the feature. A doc edited earlier in the same session reads as current while a later change leaves one of its sections stale, so file-level classification passes where section-level would not. And a hardcoded doc list never checks the file someone added after the list was written.
+
+The trigger is a failure of its own. "Sync the docs" names either corpus to the person saying it, so a description claiming the bare phrase takes the request meant for the planning surface its sibling owns, and the run rewrites a README nobody asked about while the `.claude/` docs it was called for stay stale.
+
+The quiet one is the baseline. A diff resolved against a bare local ref equals HEAD on `main` and on a branch before its first commit, so every committed change drops out of the set. The skill then reports nothing to sync, which reads as a clean result rather than as an admission that it could not see the work.
+
+## Must
+
+- Name the corpus in every trigger phrase, so a request naming neither reaches one skill of the pair rather than either
+- Resolve one merge base, prefer the remote ref over the local one, and reuse it everywhere the skill reads the diff
+- Say so in the output when the baseline degrades, rather than reporting a clean pass off a set it could not build
+- Discover the doc set by glob at run time
+- Classify and rewrite at section level, so a partly stale file is partly rewritten
+- Write immediately after the preview, since the tool permission dialog is the confirmation gate
+
+## Must not
+
+- Touch a section the change does not reach
+- Rewrite a doc to match the diff when the doc records an intent the diff departed from. That is a finding rather than a sync.
+
+## Guards
+
+- No committed change and no working-tree change stops the skill before it reads any doc
+
+## Out of scope
+
+- `.claude/` planning docs, tasks, plans, and context entries: `claude-docs`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- `CLAUDE.md` and the installed seed docs: `claude-seed-sync`, which reconciles them per section against the toolkit source
+- Changelog entries, which release tooling generates from commit messages
+- Whether the prose conforms to its standards. `claude-standards-audit` reports violations and fixes none, and this skill writes prose it does not audit.

package/claude/skills/docs-sync/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: docs-sync
+description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the `.claude/` planning surface, which `claude-docs` owns, or for changelog and `CLAUDE.md` updates.
+---
+
+# Docs sync
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+- `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: README structure, required sections, and content rules
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in Context and in Guards:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill reports nothing to sync rather than admitting it cannot see the work.
+
+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. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. `git diff --cached <base>` degrades to the staged set and `git status --short` still reports the working tree, so both reads stay at this skill's own scope. Say so in the preview with `⚠ Baseline unusable. Synced against the uncommitted set only.` The base ref is the only thing this change touches, and the `--cached` scope stays.
+
+## Context
+
+Run these commands in parallel:
+
+- `git diff --cached <base> -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+- `git diff --cached --name-only <base> 2>/dev/null || echo "NO_FILES"`
+- `git status --short 2>/dev/null || echo "NO_STATUS"`
+
+## Guards
+
+- If `git diff --cached <base>` output is empty and `git status --short` output is empty, stop: `❌ No changes since main. Nothing to sync.` Resolve the base ref first. A guard reading bare local `main` stops the skill on `main` before it reaches the corrected read.
+
+## Discovery
+
+Discover docs dynamically. Do not hardcode paths:
+
+- Glob `README.md` at project root
+- Glob `docs/**/*.md`
+
+Read each discovered file in parallel.
+
+## Analysis
+
+For each discovered doc, classify as one of:
+
+- `stale`: the diff touches something the doc describes
+- `departed`: the doc records a deliberate contract and the diff broke it
+- `unrelated`: no overlap between diff and doc content
+
+The split between `stale` and `departed` is whether the doc was describing or promising. A doc that trailed the code is `stale`. A doc stating a contract the code was meant to keep is `departed`, and rewriting it to match the diff would record the regression as the contract.
+
+Classify at the section level, not the file level. A doc edited earlier in the session can still be partially stale. For each diff surface, verify the corresponding section is synced.
+
+## Action
+
+Rewrite only the stale sections. Do not touch sections unrelated to the diff.
+
+Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+Never rewrite a `departed` section. Leave it as written and report it as a finding, since the repair belongs in the code rather than in the prose.
+
+## Response format
+
+### Preview
+
+**Changes since main:** `<n>` files
+**Docs discovered:** `<list>`
+
+| Doc         | Status    | Action |
+| ----------- | --------- | ------ |
+| README.md   | stale     | update |
+| docs/cli.md | departed  | report |
+| docs/api.md | unrelated | skip   |
+
+After outputting the preview, write all stale updates immediately.
+
+### Summary
+
+One line per file, using the same relative path format as the preview table (e.g. `README.md`, `docs/api.md`):
+
+```plaintext
+✅ Updated: <relative-path>
+⏭️  Skipped: <relative-path>
+⚠️ Departed: <relative-path> records <the contract>, and the diff <what it did>. Left unwritten.
+```

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

@@ -0,0 +1,38 @@
+---
+name: git-branch
+description: What branch naming is for, the gaps it closes, and where the family boundary sits
+---
+
+# Git branch requirement
+
+## Gap
+
+Without this skill, a branch name is invented once per session. The type prefix drifts from what the history already carries, the name runs past the width a pull request list renders, and a rename lands on a branch that already exists on the remote, which detaches every open pull request pointing at it.
+
+## Must
+
+- Read the branch format reference before generating, so the type vocabulary and the length limit come from one source
+- Derive the name from the commits ahead of main when the invocation carries no description
+- Resolve whether the branch exists on the remote before proposing a rename, since the hazard is invisible from local state
+- Show the name and its length against the limit before renaming
+- Execute immediately after the preview. The tool permission dialog is the confirmation gate.
+
+## Must not
+
+- Rename `main` or `master`
+- Rename when the current name already conforms. The skill is chained, so a conforming name has to pass through rather than churn the branch.
+- Rename a branch that exists on the remote. Local rename plus force push is not the same operation and it breaks the pull request.
+- Emit anything after the result line
+
+## Guards
+
+- On a protected branch: stop and say the branch is protected
+- Name already conforms: stop with a success marker, not a failure, since a chained caller continues past it
+- No commits and no description: stop and name both missing inputs
+- Branch exists on the remote: stop and route to the surface that preserves the pull request link
+
+## Out of scope
+
+- The commit message, which `git-commit` owns
+- Pushing and opening the pull request, which `git-pr` owns. That skill reads a conforming name as a precondition and refuses without one, so this skill runs first.
+- Splitting a branch whose commits span concerns, which `git-split` owns

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

@@ -0,0 +1,60 @@
+---
+name: git-branch
+description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
+---
+
+# Git branch
+
+Before generating a branch name, read:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/branch.md`: format, types, length limit, and constraints
+
+Follow it exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git branch --show-current 2>/dev/null || echo "NO_BRANCH"`
+- `git rev-parse --verify "origin/$(git branch --show-current)" 2>/dev/null && echo "EXISTS" || echo "LOCAL_ONLY"`
+- `git log main..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
+
+## Guards
+
+- If already on main or master, stop: `❌ Cannot rename a protected branch.`
+- If branch name already follows conventions, stop: `✅ Branch name already follows conventions.`
+- If no commits and no args provided, stop: `❌ No commits or description to derive a branch name from.`
+
+## Response format
+
+### Preview
+
+- **Current:** <current_branch>
+- **Suggested:** <suggested_name>
+- **Length:** <count>/50
+- **Status:** <LOCAL_ONLY | EXISTS on remote>
+- **Analysis:** <brief explanation of type choice>
+
+If EXISTS on remote, warn and stop:
+
+```plaintext
+⚠️ Branch exists on remote. Rename manually via GitHub UI or gh CLI to avoid breaking open PRs.
+```
+
+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.
+
+### Final command
+
+Only output if LOCAL_ONLY:
+
+```bash
+git branch -m <current> <suggested>
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Renamed: <current> → <suggested>`
+
+Do not add any other text.

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

@@ -0,0 +1,36 @@
+---
+name: git-commit
+description: What commit generation is for, the gaps it closes, and where the family boundary sits
+---
+
+# Git commit requirement
+
+## Gap
+
+Without this skill, a commit message takes whatever shape the session settled on. The type and scope drift from the convention the history already follows, the subject runs past the length the log renders, and a lockfile diff floods the context the message is derived from so the message describes the lockfile.
+
+A second failure is routing rather than shape. A plain request to commit reaches this skill and its grouping sibling alike, and the sibling's first step is to unstage everything and restage whole files, so a selection staged hunk by hand comes back widened to the files it sat in. The user reviewed one thing and shipped another, and nothing in the run says the set changed.
+
+## Must
+
+- Read the commit format reference and the versioning standard before generating, so the type, the scope, and the version discipline come from one source
+- Derive the message from the staged diff, with lockfiles excluded
+- Show the message and its length against the limit before committing, so an over-length subject is visible while it is still cheap to fix
+- Execute immediately after the preview. The tool permission dialog is the confirmation gate, and a second prompt trains the user to skim it.
+- Claim the single-concern and the hunk-level staged set in the description, and name the sibling for the multi-concern one. A boundary stated only here routes nothing, since the description is the field the choice is made from.
+
+## Must not
+
+- Stage anything. What is committed has to be what the user chose to stage.
+- Commit when nothing is staged
+- Emit anything after the result line. A commit is a step inside a longer flow and prose here buries the next one.
+
+## Guards
+
+- Nothing staged: stop and name the command that stages
+
+## Out of scope
+
+- Splitting a mixed diff across several commits, which `git-stage` owns. That skill restages whole files, so a hunk-level selection survives here and not there, and both descriptions carry the difference rather than leaving it stated only in these two files.
+- Naming the branch, which `git-branch` owns. The family shares its triggers and not its gaps: this one turns on the staged diff, the length limit, and lockfile exclusion, none of which a branch name has.
+- Pushing or opening a pull request, which `git-pr` owns

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

@@ -0,0 +1,49 @@
+---
+name: git-commit
+description: Generates one conventional commit message from the staged changes and commits them exactly as staged, so a hunk-level selection survives. Use when asked to "commit this" or "commit the staged changes" and the staged set covers one concern, or whenever the selection was staged hunk by hand. Do NOT use when the staged changes span several concerns and need separate commits. That is `git-stage`.
+---
+
+# Git commit
+
+Before generating a commit message, read:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/commit.md`: format, types, scopes, and constraints
+- `${CLAUDE_SKILL_DIR}/../../standards/versioning.md`: phase label vs semver discipline
+
+Follow them exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git diff --cached --name-status 2>/dev/null || echo "NO_STAGED_CHANGES"`
+- `git diff --cached -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+
+## Guards
+
+- If staged files output is `NO_STAGED_CHANGES`, stop and output:
+  `❌ No staged changes. Stage files first with git add before committing.`
+
+## Response format
+
+### Preview
+
+- **Files:** <if ≤3 list all, if >3 show first 3 + "+N more">
+- **Message:** `<type>(<scope>): <subject>`
+- **Length:** <count>/72
+
+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.
+
+### Final command
+
+```bash
+git commit -m "<type>(<scope>): <subject>"
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Committed: <type>(<scope>): <subject>`
+
+Do not add any other text.

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

@@ -0,0 +1,43 @@
+---
+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.
+
+A caller that rebased the branch before handing over hits a rejected push, since the tracking branch no longer reaches the head. A branch entered through a worktree hits the opposite shape, carrying an open pull request with no tracking ref at all, which read as a branch that had never been pushed.
+
+A fix commit answering a review is the sharpest case of the first paragraph, since it always changes what shipped. The routing that once picked whether to sync the body keyed off the same branch that decides whether to reply, so reaching `reply-owned` or a nonzero comment count meant the sync never ran at all. The description a merge record carries was true when the pull request opened and false by the time review finished, with nothing between the two that read it back.
+
+## Must
+
+- Refuse unless the branch has an open pull request, since every later step addresses it
+- Set the tracking ref at the push when the branch has none, since a branch entered through a worktree carries an open pull request without one
+- 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 and internal phase labels 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
+- Force the push under a lease when the tracking branch no longer reaches the head, so a caller's rebase lands and a commit this session never read is not overwritten
+
+## 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 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,48 @@
+---
+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 7. 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 `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.`
+
+A missing tracking ref is no longer a guard. An open pull request proves the branch reached the remote, and a branch created by worktree entry has been measured carrying an open pull request with no tracking ref, where the old guard reported that the branch still needed pushing. That message describes a state the branch is not in, so the run stopped on a diagnosis nobody could act on. Step 4 sets the ref instead.
+
+## Sequence
+
+1. Run `git status` to confirm the changes are intentional
+2. Run `git add -A` to stage every change
+3. Invoke `canon:git-commit` to generate one conventional commit from the staged diff
+4. Push, in one of two cases.
+   - When `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null` is empty, the branch has an open pull request and no tracking ref, so run `git push -u origin HEAD` to send the commit and set the ref in one step.
+   - Otherwise push to the tracking branch with `git push`, and when `git merge-base --is-ancestor @{u} HEAD` exits non-zero, a caller rewrote the branch and a plain push is rejected, so push with `--force-with-lease` instead.
+
+   The lease is what stops the force from overwriting a commit this session never read. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
+
+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. Sync the body and title on every invocation, before the routing below decides on the reply.
+   - 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.
+   - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
+   - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
+7. Route on the invocation and the comment count for the reply alone.
+   - When invoked with `reply-owned`, skip this step: the caller posts its own 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 running the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against it, since the hook does not see an inline comment body. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 6 synced reaches it.
+   - If it is zero, nothing further runs. The sync in step 6 already did this branch's job.
+
+## 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 and internal phase labels 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 `canon-feedback-file` owns. That path writes into the toolkit rather than the current repository.
+- Triaging issues already filed, which `canon-feedback-triage` owns
+- Opening a pull request, which `git-pr` owns

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

@@ -0,0 +1,65 @@
+---
+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 `canon-feedback-file`), 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}/../../standards/issue.md`: issue title, labels, body sections, and banned phrases
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+
+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, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/../../standards/issue.md`.
+
+The `pull_request` check the git-pr surface carries reads a pull request's own title and body alone, so an issue reaches no check behind this scan either.
+
+### 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-pr/REQUIREMENT.md

@@ -0,0 +1,50 @@
+---
+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.
+
+Every pull request also lands unlabelled, so a merged list is a wall of titles with no way to filter it by surface. A reader looking for what changed in one domain reads all of them, and the conventional commit type in the title says what kind of change it is rather than where.
+
+A lookup that resolves by head branch alone carries its own failure. A branch name reused after an earlier pull request merged resolves to the closed one, so the run rewrites a merged pull request's title and body and reports its URL as the one it opened. Both fields are recoverable only through the issue timeline and the edit history, and nothing reports that the write landed on the wrong object.
+
+## 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 and internal phase labels 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
+- Scope that detection to an open pull request on the current head and the default base, so neither a reused branch name nor a second base resolves the wrong one
+- Resolve the pull request once and reuse what that resolution returned, so the number recorded never depends on how a lookup ranks two pull requests sharing a head
+- Label from the paths the branch changed, against a map the project declares, so the label set belongs to the project rather than to the skill
+- Apply labels after the pull request exists, so a label the remote does not carry costs a warning rather than the pull request
+- Report a refused label, since a warning nothing surfaces leaves the run indistinguishable from one that labelled
+
+## 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
+- Edit a pull request that is not open, or record its number on a task
+- Name a domain of any one project in the skill body or its references
+- Create a label the map names and the remote lacks
+- 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
+- No label map in the project: label nothing and warn nothing, since an absent map is a decision rather than a gap
+
+## 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.