@rtorcato/repo-tooling 3.17.0 → 3.19.0

package/dist/base/checks.js

@@ -469,11 +469,16 @@ export async function checkAiSetup(dir) {
  * is not a defect in this repo, and either of those statuses would fail its CI
  * over a file CI has never seen. `optional-missing` is the honest verdict — an
  * opt-in workflow tool that isn't configured — and it leaves the exit code alone.
+ *
+ * `skillsDir` is doctor's `--skills-dir`. Without it this reported against
+ * `~/.claude/skills` whatever directory the repo actually installs into, so a
+ * consumer who passes the flag to `fix` saw a permanent false `optional-missing`
+ * for a skill they have (#485).
  */
-export async function checkClaudeSkills() {
+export async function checkClaudeSkills(skillsDir) {
     const check = 'Claude skills';
     const hint = `Run \`npx @rtorcato/repo-tooling fix claude-skills\` to install the ${SHIPPED_SKILL} skill (writes outside the repo; opt-in, so \`fix\` alone skips it)`;
-    const status = await claudeSkillStatus();
+    const status = await claudeSkillStatus(SHIPPED_SKILL, skillsDir);
     if (!status.installed) {
         return {
             check,

package/dist/base/labels.js

@@ -39,10 +39,15 @@ export const LOOP_LABELS = [
         color: 'fbca04',
         description: 'Passed, but a reviewer left something to read before merging',
     },
+    {
+        name: 'ai-suggested',
+        color: 'c2e0c6',
+        description: 'Follow-up surfaced by an agent review — triage queue, never auto-picked',
+    },
 ];
 /**
  * How many of the set have to exist before this repo counts as running the
- * loop. A repo with none has opted out, not drifted — creating eleven labels it
+ * loop. A repo with none has opted out, not drifted — creating twelve labels it
  * will never use is the nag this threshold exists to prevent. One alone is the
  * observed half-state (`cf-common` has only `ai-ready`, applied by hand), which
  * is likewise not evidence the pipeline runs there.
@@ -141,7 +146,7 @@ export async function checkLoopLabels(dir, exec) {
  * Repairs colour and description with `gh label edit`, and creates the labels
  * the set is missing. Only on a repo already running the loop (the same
  * `IN_USE_THRESHOLD` gate the check uses) — otherwise a plain `fix --yes` would
- * push eleven labels into every repo it touches.
+ * push twelve labels into every repo it touches.
  *
  * Idempotent: an aligned repo is a no-op, and a label whose only difference is
  * the hex case is not touched at all.

package/dist/cli/commands/doctor.js

@@ -179,12 +179,12 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkBrand(dir));
     results.push(await checkAiSetup(dir));
     // User-global, not repo state — see checkClaudeSkills on why it never returns drift.
-    results.push(await checkClaudeSkills());
+    results.push(await checkClaudeSkills(opts.skillsDir));
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
     return results;
 }
-export async function runDoctor(dir) {
+export async function runDoctor(dir, skillsDir) {
     const targetDir = path.resolve(dir);
     const lock = await readLockfile(targetDir);
     // Per-module dispatch (#285): the base checks (repo hygiene, CI, security,
@@ -212,6 +212,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: null,
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -234,6 +235,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -257,6 +259,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderPythonWorkflow(await readPyproject(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runPythonChecks(targetDir)),
         ];
@@ -282,6 +285,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderPerlWorkflow(await readPerlProject(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runPerlChecks(targetDir)),
         ];
@@ -342,6 +346,7 @@ export async function runDoctor(dir) {
         presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg), { scripts: scriptsOf(pkg) })),
         language,
         codeqlLanguages: languageModule.codeqlLanguages,
+        skillsDir,
     })));
     return demoteDeclined(results, lock);
 }
@@ -397,7 +402,7 @@ export function summarize(results) {
 }
 export async function doctorCommand(options = {}) {
     const dir = options.directory ?? process.cwd();
-    const results = await runDoctor(dir);
+    const results = await runDoctor(dir, options.skillsDir);
     if (options.json) {
         console.log(JSON.stringify({ directory: path.resolve(dir), results }, null, 2));
     }

package/dist/cli/commands/fix.js

@@ -333,7 +333,9 @@ export async function fixCommand(target, options = {}) {
     const pkg = await readPackageJson(targetDir);
     const lock = await readLockfile(targetDir);
     const fixers = fixersForLanguage(await detectLanguage(targetDir));
-    const results = await runDoctor(targetDir);
+    // Same --skills-dir the claude-skills fixer writes to, so the diagnosis fix
+    // acts on and the install it performs agree on one directory (#485).
+    const results = await runDoctor(targetDir, options.skillsDir);
     const actions = [];
     const noteLockConflict = (check) => {
         if (!lock)

package/dist/cli/index.js

@@ -317,6 +317,9 @@ program
     .description('🩺 Diagnose project alignment with @rtorcato/repo-tooling presets')
     .option('-d, --directory <path>', 'Target directory to diagnose', process.cwd())
     .option('--json', 'Emit machine-readable JSON output')
+    // The read side of `fix --skills-dir` (#485). No --yes/--json requirement
+    // here: doctor never writes, so an unresolved directory is just reported.
+    .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Pass the same path `fix` was given, or the skill reports as not installed')
     .action(doctorCommand);
 program
     .command('fix [target]')

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.17.0",
+	"version": "3.19.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/ai-issue-loop/SKILL.md

@@ -60,6 +60,7 @@ drift with a second copy to maintain.
 |---|---|
 | Clean and ready | **None.** `ai-ok-code, ai-ok-sec` + assigned + no `ai-review` already says it. |
 | `ai-notes` | ≤10 lines; link the reviewer's `### Before merging`. |
+| Follow-up found | One line — `Follow-up: #<new>`. The issue carries the context. |
 | `ai-changes`, CI red, `ai-blocked` | ≤10 lines, action first, then the specific cause. |
 | Reviewer verdict | `### Before merging` plus ≤600 characters above it. |
 | Declining an issue | The one exception — a hard handoff needs its reasoning; see Pass 4. |
@@ -78,6 +79,7 @@ drift with a second copy to maintain.
 | `ai-ok-sec` | PR | `security-expert` passed. |
 | `ai-changes` | PR | A reviewer requested changes. Reviewers never apply it to a Dependabot PR. |
 | `ai-notes` | PR | Passed, but a reviewer left something to read before merging. |
+| `ai-suggested` | issue | Follow-up a reviewer filed. A triage queue, never auto-picked. |
 | `holding` | issue | A gate — closes on human judgement, never picked up. |
 
 **`ai-notes` is advisory and never blocks.** It rides *alongside* a pass label,
@@ -87,12 +89,19 @@ so `ai-notes` is the hold itself: it suppresses auto-merge and routes the PR to
 the human. It exists because a pass label currently means both "clean" and
 "I found something real but would not hold the PR over it", and those two are
 indistinguishable in the *Assigned to you* view where merges actually happen.
-The bar is a finding that **changes what a human would do**: a semver
-implication, a deliberate omission, a follow-up that must be filed. Not
+The bar is a finding that **changes what a human would do at merge time**: a
+semver implication, a deliberate omission, a question only they can answer. Not
 observations, not praise, not restating the diff. `ai-notes` on every PR is the
 failure mode — it trains the reader to ignore it, which is worse than not having
 it.
 
+**Follow-up work is an issue, not a note.** A finding that clears that bar *and*
+is work someone would plausibly do gets filed as its own issue labelled
+`ai-suggested`, by the reviewer that found it; the PR comment keeps one line and
+a link. It does **not** earn `ai-notes` — later work does not decide this merge.
+An observation is not a follow-up. Prose in a merged PR's comments is
+archaeology, which is how every follow-up left there so far has died on merge.
+
 First run in a repo, create any that are missing (`gh label create` is a no-op
 error if it exists — ignore that):
 
@@ -108,6 +117,7 @@ gh label create ai-ok-code -c '#0e8a16' -d 'code-reviewer passed'
 gh label create ai-ok-sec  -c '#0e8a16' -d 'security-expert passed'
 gh label create ai-changes -c '#d93f0b' -d 'Reviewer requested changes'
 gh label create ai-notes   -c '#fbca04' -d 'Passed, but a reviewer left something to read before merging'
+gh label create ai-suggested -c '#c2e0c6' -d 'Follow-up surfaced by an agent review — triage queue, never auto-picked'
 ```
 
 Bootstrap only. `gh label create` **cannot repair a label that already exists** —
@@ -539,10 +549,28 @@ Reviewer prompt template:
 > narrate only where the PR is **wrong** or **silent**. Never list what you
 > checked and found clean, and never confirm a claim the PR body already makes —
 > agreement is what the pass label is for, so a review that agrees is nearly
-> empty. The bar is a finding that **changes what a human would do**: a semver
-> implication, a deliberate omission, a follow-up that must be filed. Writing
-> `Nothing.` is a real verdict and the common one — say it plainly rather than
-> padding to look thorough.
+> empty. The bar is a finding that **changes what a human would do at merge
+> time**: a semver implication, a deliberate omission. Writing `Nothing.` is a
+> real verdict and the common one — say it plainly rather than padding to look
+> thorough.
+>
+> **Follow-up work is an issue, and you file it — it does not go in that
+> section.** When a finding clears that bar but is work someone would plausibly
+> do *later* rather than something that decides this merge:
+>
+> ```bash
+> gh issue create --label ai-suggested --title "<what to do>" --body "🤖 *Automated — \`<your agent type>\` via ai-issue-loop.*
+>
+> Surfaced reviewing #<N>. <What, and why it matters. A few lines.>"
+> ```
+>
+> Then put `Follow-up: #<new>` on one line in the body above `### Before
+> merging` and keep it out of that section, so it does not pull `ai-notes` in —
+> later work is not a merge gate. GitHub cross-links the two, so the trail
+> survives the merge in both directions; the comment prose does not. Filing is
+> the alternative to blocking, not a precondition for it. An observation is not
+> a follow-up — do not file one, and a trade-off that changes nothing a human
+> does is one line of body and nothing else.
 >
 > Then apply exactly one verdict label, **clearing your claim label in the same
 > command**:
@@ -655,6 +683,12 @@ package/from/to table survives because it sits at the top; classify from that.
 > unattended. A major, a package that ships to consumers, or a truncated body you
 > could not fully read **is** worth a note; restating the version table on a
 > routine dev-only patch bump is not.
+>
+> **Follow-up work is an issue here too** — same `gh issue create --label
+> ai-suggested` as the generic prompt, same `Follow-up: #<new>` one-liner in the
+> body, never in `### Before merging`. That separation matters more on this arm
+> than the other: a note here costs a human the merge, so routing "someone should
+> pin this transitive dep one day" to an issue is what keeps auto-merge usable.
 
 Be honest about what this buys: an agent reading a version table catches majors,
 production-dependency creep, and a renamed or newly-added package. It does **not**
@@ -727,6 +761,7 @@ gh api "repos/$OWNER_REPO/issues?labels=ai-ready&state=open" \
             | select([.labels[].name] | index("ai-wip") == null)
             | select([.labels[].name] | index("ai-blocked") == null)
             | select([.labels[].name] | index("holding") == null)
+            | select([.labels[].name] | index("ai-suggested") == null)
             | select(.author_association=="OWNER" or .author_association=="MEMBER" or .author_association=="COLLABORATOR")
             | {number, title}'
 ```
@@ -741,6 +776,10 @@ the first place, but then mislabelling it costs nothing. Unlike `ai-blocked` (an
 agent tried and got stuck), `holding` says *no agent should ever start*, and it
 shows up in the issue list so a human triaging does not re-litigate it either.
 
+`ai-suggested` is excluded for a harder reason: it is an agent's own suggestion,
+so picking one up would let the loop feed itself work — promoting one is a human
+act, which is what makes that label a triage queue rather than a backlog.
+
 **Declining an issue is a visible act — comment, never just skip.** Whenever an
 agent decides an issue should *not* go to the pipeline — triaging which issues to
 label `ai-ready`, or dropping one that is already labelled — say so on the issue