@erclx/aitk 0.35.0 → 0.35.2

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

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

package/claude/skills/bash-script/SKILL.md

@@ -9,6 +9,10 @@ Generate production-ready Bash scripts for DevOps and CLI workflows. Enforce str
 
 Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, interactive prompt, help-screen, and full-script code templates. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
 
+## Guards
+
+- A request for a script with no human at the terminal stops and routes to `cli-script`. CI jobs, cron entries, agent-run tasks, and any script whose output is consumed by a pipe render no timeline, so generating one costs the frame and returns nothing.
+
 ## Script setup
 
 - Start with `#!/usr/bin/env bash`, `set -e`, and `set -o pipefail`.

package/claude/skills/ci-workflow/SKILL.md

@@ -7,6 +7,11 @@ description: Generates GitHub Actions CI workflow files with parallel jobs, emoj
 
 Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job execution, emoji job naming, and gated deployment stages.
 
+## Guards
+
+- A request for what runs inside a deploy, publish, or release job stops at the gate. Credentials, environments, and deploy targets are invisible to this skill, so emit the job with its `needs` wiring and a placeholder step, then name what the caller fills in. Never guess a deploy command.
+- The build, test, and deploy commands belong to the project. Read them from its scripts rather than asserting a second copy in the workflow.
+
 ## Workflow setup
 
 - Include `workflow_dispatch` on every workflow alongside the primary trigger.
@@ -49,4 +54,5 @@ Before responding, verify:
 - E2E uses `needs: build`. Release and deploy use `needs: e2e`.
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
+- Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.
 - Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.

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

@@ -55,14 +55,19 @@ Read each discovered file in parallel.
 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
@@ -73,6 +78,7 @@ Rewrite only the stale sections. Do not touch sections unrelated to the diff. Wr
 | 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.
@@ -84,4 +90,5 @@ One line per file, using the same relative path format as the preview table (e.g
 ```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-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.
 
+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
@@ -17,12 +19,15 @@ Without this skill, a pull request body is written from memory of the branch rat
 - 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
 
 ## 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
 - Emit anything after the result line
 
 ## Guards

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

@@ -71,9 +71,19 @@ Leave a box unchecked only for the human-only cases the reference defines, and n
 
 Before running the final command, run the scan in `.claude/standards/publish.md` against the PR title and body, or `${CLAUDE_SKILL_DIR}/../../standards/publish.md` when the project does not have it. 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}/references/pr.md`.
 
+### Resolving the pull request
+
+The run resolves the pull request once, in the final command below, and every later step reads what that command printed. Nothing else looks the number up again.
+
+`gh pr view` is the form this replaces. It resolves by head branch and ignores state, so a branch name reused after an earlier pull request merged returns the closed one. The detection then takes the edit path and rewrites a merged pull request's title and body, and the run reports that pull request's URL as the one it opened, so nothing surfaces the write landing on the wrong object. Scoping the lookup with `--state open` returns empty there and sends the run down the create path.
+
+The lookup scopes to the base as well as the head. One head can carry open pull requests against two bases, and a lookup reading the first result would pick between them by list order. Resolving the base from the repository's default branch is what makes the detection and `gh pr create` agree on which pull request the run is about.
+
+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>`.
+
 ### 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`.
+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`.
 
 ```bash
 mkdir -p .claude/.tmp/pr
@@ -81,21 +91,21 @@ 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
+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')
+if [ -n "$pr_number" ]; then
+  pr_url=$(gh pr edit "$pr_number" --title "<title>" --body-file .claude/.tmp/pr/body.md) || exit 1
 else
-  gh pr create --title "<title>" --body-file .claude/.tmp/pr/body.md
+  pr_url=$(gh pr create --title "<title>" --body-file .claude/.tmp/pr/body.md) || exit 1
+  pr_number=${pr_url##*/}
 fi
 rm -rf .claude/.tmp/pr
+printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
 ```
 
 ### 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
-```
+Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. A head branch that carried an earlier pull request now has two, and a second `gh pr view` would pick between them by a precedence rule nothing here states. Reading what created or edited the pull request needs no such rule.
 
 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.
 
@@ -107,7 +117,7 @@ The number is what lets the merge close the task. Every merge on `main` is a squ
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line, using the `url` the final command printed:
 
 `✅ PR: <url>`
 

package/claude/skills/migration-claude-md/SKILL.md

@@ -7,6 +7,8 @@ description: Classifies each section of a target project's bloated `CLAUDE.md` i
 
 Rebalance a large `CLAUDE.md` so only always-load behavior stays in it, path-scoped behavior becomes a rule, and domain narrative becomes a context entry. Every move is a proposal the user applies by hand.
 
+Run `migration-context` first when both apply. Its moves populate `.claude/context/`, and Step 3 has to read the folder those moves left so an existing entry resolves to an append rather than blocking the move that should have created it.
+
 ## Guards
 
 - If no `CLAUDE.md` exists at `pwd`, stop: `❌ No CLAUDE.md found at the project root.`

package/claude/skills/migration-context/SKILL.md

@@ -5,6 +5,8 @@ description: Classifies markdown files in a target project's `docs/` folder and
 
 # Claude context migrate
 
+Run this skill before `migration-claude-md` when both apply. That skill proposes entries into the same `.claude/context/` folder, and an entry landing there first makes the corresponding move here read as a conflict and get skipped, which loses the richer `docs/` file.
+
 ## Guards
 
 - If no `docs/` directory exists at `pwd`, stop: `❌ No docs/ directory found.`

package/claude/skills/setup-gov/SKILL.md

@@ -36,13 +36,14 @@ Match the detected evidence to the catalog:
 
 If a detected technology has no matching rule, stop and surface the gap. Do not guess.
 
-Present three options:
+Present four options:
 
-1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `.claude/standards/rule.md`, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it, commit, then re-run install.
-2. Install the matching non-<tech> rules and skip the tech-specific layer.
-3. Abort.
+1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `.claude/standards/rule.md`, or `${CLAUDE_SKILL_DIR}/../../standards/rule.md` when the project does not have it, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
+2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
+3. Install the matching non-<tech> rules and skip the tech-specific layer.
+4. Abort.
 
-Rules are authored in the toolkit repository, never in the target project on the fly.
+This skill authors no rule itself. Option 1 writes in the toolkit repository, and option 2 hands the project-local file to `create-rule`.
 
 ## Preview
 

package/claude/skills/setup-init/SKILL.md

@@ -10,6 +10,7 @@ Orchestrates the onboarding chain. Detects project type, resolves per-domain arg
 ## Scope
 
 - This skill and `aitk init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `aitk <domain> install` or `aitk sync` paths instead.
+- The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
 
 ## Read catalogs
 
@@ -112,3 +113,4 @@ After the chain, report:
 - `setup-verify` outcome
 - Any domains or scripts that failed
 - Any detection gaps surfaced during resolve
+- Onboarding steps left to the caller: `setup-indexes` for the `index.md` system, `setup-plugins` for Claude Code plugins

package/package.json

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