@erclx/aitk 0.81.0 → 0.82.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -9,6 +9,8 @@ description: What pull request generation is for, the gaps it closes, and what i
 
 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
@@ -21,6 +23,9 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - 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
 
@@ -28,12 +33,15 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - 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
 

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

@@ -11,6 +11,7 @@ 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_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `.claude/pr-labels.toml`.
 - `.claude/standards/prose.md` from the project root: voice and banned words for all generated text
 - `.claude/standards/markdown.md` from the project root: punctuation and formatting for all generated text
 - `.claude/standards/versioning.md` from the project root: phase label vs semver discipline
@@ -29,6 +30,7 @@ Then run these commands in parallel to gather git context:
 - `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"`
+- `git diff --name-only <base> HEAD 2>/dev/null || echo "NO_FILES"`
 
 ## Diff baseline
 
@@ -82,15 +84,24 @@ The lookup scopes to the base as well as the head. One head can carry open pull
 
 A detached HEAD gives `git branch --show-current` an empty result, which would read as no open pull request and create a second one. The branch-name guard above stops the run first, since an empty name does not match `<type>/<description>`.
 
+### Labels
+
+Read `.claude/pr-labels.toml` from the project root. A project that has not declared a map gets no labels and no warning, since a label set this skill supplied would be a guess about that project's surfaces.
+
+When the file resolves, match it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md` and write the comma-separated result into `pr_labels` below. Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
+
 ### Final command
 
 Detect an open pull request on the current head and branch: edit it in place when one exists, create it otherwise. This keeps the body in sync on a follow-up push instead of erroring on `gh pr create`.
 
+Labels apply after that branch converges, against a pull request that already exists. `gh pr create --label` refuses a label the remote does not carry and opens no pull request at all, so a mistyped row costs the run rather than the label. One command after the fact also covers the create and the edit path together.
+
 ```bash
 mkdir -p .claude/.tmp/pr
 cat <<'BODY' > .claude/.tmp/pr/body.md
 <body content following pr.md template exactly>
 BODY
+pr_labels="<comma-separated labels, empty when the map resolves to nothing>"
 git push -u origin HEAD || exit 1
 base_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
 pr_number=$(gh pr list --head "$(git branch --show-current)" --base "$base_branch" --state open --json number --jq '.[0].number // empty')
@@ -100,6 +111,10 @@ else
   pr_url=$(gh pr create --title "<title>" --body-file .claude/.tmp/pr/body.md) || exit 1
   pr_number=${pr_url##*/}
 fi
+if [ -n "$pr_labels" ]; then
+  gh pr edit "$pr_number" --add-label "$pr_labels" >/dev/null ||
+    printf 'Label apply failed. Create a missing label with: gh label create <name>\n' >&2
+fi
 rm -rf .claude/.tmp/pr
 printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
 ```
@@ -124,8 +139,12 @@ The number is what lets the merge close the task. Every merge on `main` is a squ
 
 ## After execution
 
-Respond with exactly one line, using the `url` the final command printed:
+Respond with one line, using the `url` the final command printed:
 
 `✅ PR: <url>`
 
+Add a second line only when the labelling command printed its warning, quoting the label `gh` refused:
+
+`⚠️ Labels not applied: <what gh reported>`
+
 Do not add any other text.

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

@@ -0,0 +1,59 @@
+---
+title: Label reference
+description: Path-to-label map format, prefix matching against the changed set, and the one-time label creation a map requires
+---
+
+# Label reference
+
+## Scope
+
+Governs the labels a pull request carries: the map a project declares, how a changed path resolves to a label, and what a label missing from the remote costs.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Branch naming: `branch.md`
+- Issue labels, which `git-issue` derives from the issue type rather than from a diff
+
+## Map format
+
+The map lives at `.claude/pr-labels.toml` in the project root. Each key under `[domains]` is a label name and its value is the list of path prefixes that earn it.
+
+```toml
+[domains]
+api = ["services/api/"]
+web = ["apps/web/", "packages/ui/"]
+```
+
+A label takes more than one prefix when two folders read as one surface. Two labels may claim overlapping prefixes, and a path under both earns both.
+
+The map is authored by hand and nothing detects a directory it fails to cover, so a surface added after the map was written labels nothing until someone adds a row.
+
+## Matching
+
+- Take the changed set from `git diff --name-only <base> HEAD`, resolved against the same base as the diff the body is written from
+- A path earns a label when the path starts with one of that label's prefixes
+- Collect the distinct labels across the whole set, ordered as the map declares them, so two runs over one branch produce one string
+- Pass the result as a single comma-separated value. An empty result runs no labelling step.
+
+## Applying
+
+Apply labels after the pull request resolves, never as a flag on the create. `gh pr create --label` fails whole on a label the remote does not carry, so a name the map got wrong opens no pull request at all and the run stops with the branch pushed and nothing to review. A `gh pr edit --add-label` against a pull request that already exists costs a warning instead, and it is one command across both the create and the edit path rather than two flags that have to stay in step.
+
+`--add-label` adds and never removes. A label a person applied by hand is not this skill's to strip, so a domain that stops applying between two pushes keeps its label until someone takes it off.
+
+## A label the remote does not carry
+
+Warn and continue rather than creating it, naming the command in the warning:
+
+```bash
+gh label create <name> --description "<text>"
+```
+
+Creating a label writes to the repository settings from a run the user invoked to open a pull request, and a label created from a typo in the map is harder to notice than a warning is.
+
+The refusal names the label it rejected and applies none of the set, so a warning that reaches nobody leaves the run reading exactly like one that labelled. Surface it beside the result line rather than letting the pull request URL stand alone.
+
+## Release pull requests
+
+Release automation opens its own pull requests without this skill and applies its own labels, so nothing here needs a skip condition for them.

package/docs/agents/markdown-audit.md

@@ -55,7 +55,9 @@ Every weight and depth measure counts the text a reader is shown. A link reduces
 
 A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
 
-The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 36 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 15 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 886 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+
+A sentence boundary closes on terminal punctuation ahead of a capital or a code span. The capital is what keeps a version pin and a decimal from each reading as two sentences, and the code span is admitted beside it because a command name opening a sentence carries no capital to find.
 
 The paragraph weight sits at 700 and the bullet weight at 400. Both shipped at 400, because the paragraph number was borrowed from the bullet rule when the two checks landed together, and each has since been read against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/markdown/structure.ts

@@ -15,8 +15,14 @@ const BLOCKQUOTE = /^\s*>/
  * one. An abbreviation ahead of a capitalized word still counts, which
  * over-reports by one on the sentence that carries it and is why this measure
  * reports rather than gates.
+ *
+ * A code span opens a sentence that carries no capital at all, since a command
+ * name is lowercase and the requirement above would catch nothing there. The
+ * backtick therefore stands alone rather than joining the delimiters a capital
+ * follows, and the price is that a span opening a fragment mid-paragraph reads
+ * as a sentence start.
  */
-const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+["'“(\[]*[A-Z]|\s*$)/g
+const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
 
 const NUMBER_WORDS: Record<string, number> = {
   one: 1,