@rtorcato/repo-tooling 3.16.3 → 3.18.0

package/dist/base/checks.js

@@ -492,6 +492,20 @@ export async function checkClaudeSkills() {
             hint,
         };
     }
+    // A local fork is `ok` for the same reason a modified copied asset is (#448):
+    // it is somebody's deliberate work, so it is named once and never nagged as
+    // fixable — pointing at a `fix` that would refuse is worse than saying nothing.
+    if (status.contentState && status.contentState !== 'pristine') {
+        const why = status.contentState === 'modified'
+            ? `has local changes since ${status.installedVersion}`
+            : 'carries no content record, so a fork cannot be told from a stale copy';
+        return {
+            check,
+            status: 'ok',
+            detail: `${SHIPPED_SKILL} skill at ${status.file} ${why}; this package ships ${status.shippedVersion} and will not overwrite it`,
+            hint: `Diff it against the shipped copy, then run \`npx @rtorcato/repo-tooling fix claude-skills --force-skills\` to take the shipped version`,
+        };
+    }
     return {
         check,
         status: 'ok',

package/dist/base/fixers.js

@@ -76,6 +76,23 @@ async function resolveInstallDir(explicit, assumeYes) {
     const trimmed = typeof answer === 'string' ? answer.trim() : '';
     return trimmed ? path.resolve(trimmed) : null;
 }
+/**
+ * Why the install refused, and what to do about it. A bare "skipped" would be
+ * its own failure mode: the user still wants the update, and nothing on screen
+ * would say how to get it or what they would be giving up (#480).
+ */
+function describeSkillFork(result) {
+    const target = result.viaSymlink ? `${result.file} → ${result.realFile}` : result.realFile;
+    const why = result.contentState === 'modified'
+        ? `its content has diverged from the ${result.installedVersion} release it was installed from`
+        : 'it carries no content record, so a local fork and a stale copy are indistinguishable';
+    return [
+        `skipped — ${SHIPPED_SKILL} was not overwritten with ${result.shippedVersion}: ${why}`,
+        `  ${target}`,
+        `  compare:  diff "${result.realFile}" "${result.shippedFile}"`,
+        '  overwrite anyway:  fix claude-skills --force-skills',
+    ];
+}
 export const BASE_FIXERS = [
     {
         target: 'copied-assets',
@@ -321,15 +338,22 @@ export const BASE_FIXERS = [
         riskLevel: 'safe-add',
         explicitOnly: true,
         canFixDrift: true,
-        async run({ skillsDir, assumeYes }) {
+        async run({ skillsDir, forceSkills, assumeYes }) {
             const dir = await resolveInstallDir(skillsDir, assumeYes);
             if (!dir)
                 return { filesWritten: [] };
-            const result = await installClaudeSkill(dir);
+            const result = await installClaudeSkill(dir, SHIPPED_SKILL, { force: forceSkills });
             if (result.status === 'declined-downgrade') {
                 console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
                 return { filesWritten: [] };
             }
+            if (result.status === 'declined-fork') {
+                // Name `realFile`: through a stow symlink the overwrite would land in a
+                // *second* repo's working tree, and that is the path to look at (#480).
+                for (const line of describeSkillFork(result))
+                    console.error(chalk.yellow(`   ${line}`));
+                return { filesWritten: [] };
+            }
             if (result.status === 'up-to-date')
                 return { filesWritten: [] };
             // Report the resolved real path when the skill is a stow symlink: the bytes

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/fix.js

@@ -413,6 +413,7 @@ export async function fixCommand(target, options = {}) {
         // branch and records a skip, since one refusal must not abandon the rest.
         const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent, {
             skillsDir: options.skillsDir,
+            forceSkills: options.forceSkills,
             assumeYes,
         }).catch((err) => {
             if (!(err instanceof FixerAbort))
@@ -488,6 +489,7 @@ export async function fixCommand(target, options = {}) {
         try {
             outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
                 skillsDir: options.skillsDir,
+                forceSkills: options.forceSkills,
                 assumeYes,
             });
         }

package/dist/cli/generators/claude-skills.js

@@ -4,6 +4,7 @@
  * project on the machine. That difference drives all three rules below — the
  * version stamp, the symlink handling, and the fixer's opt-in `explicitOnly`.
  */
+import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
@@ -17,6 +18,19 @@ export const SHIPPED_SKILL = 'ai-issue-loop';
  * is wrong to do so.
  */
 export const VERSION_KEY = 'repo-tooling-version';
+/**
+ * The pristine sha256 of the content we wrote, stamped beside the version — the
+ * skills half of #448. The version alone cannot tell a stale copy from a
+ * deliberate local fork: a fork that is merely older than the package looks
+ * exactly like a copy waiting for an update, and gets overwritten (#480).
+ * With the hash, "installed content still matches what some release of this
+ * package shipped" is a fact rather than an inference.
+ *
+ * It lives in the file instead of `.repo-tooling.json` because skills are
+ * user-global — no one repo owns the record.
+ */
+export const HASH_KEY = 'repo-tooling-hash';
+const STAMP_KEYS = [VERSION_KEY, HASH_KEY];
 const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
 /**
  * Where to install. `explicit` is `--skills-dir`; otherwise the user-level
@@ -35,25 +49,64 @@ export async function resolveSkillsDir(explicit, home = os.homedir()) {
         return { dir: userDir, source: 'user' };
     return { dir: null, source: 'none' };
 }
+function readStamp(content, key) {
+    return content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
+}
 /** The version recorded in an installed copy, or null if it predates the stamp. */
 export function readSkillVersion(content) {
-    return content.match(new RegExp(`^${VERSION_KEY}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
+    return readStamp(content, VERSION_KEY);
+}
+/** The pristine hash recorded in an installed copy, or null if it predates it. */
+export function readSkillHash(content) {
+    return readStamp(content, HASH_KEY);
 }
 /**
- * Replace (or add) the version line in the frontmatter. Appending it last is
+ * Replace (or add) the stamp lines in the frontmatter. Appending them last is
  * safe even after a multi-line `description: |` block: an unindented key ends
- * the block scalar, which is exactly what this line is.
+ * the block scalar, which is exactly what these lines are.
+ *
+ * With no stamps this is the exact inverse of stamping, so a file we wrote
+ * strips back to the bytes we were given — which is what makes the hash
+ * comparable.
  */
-export function stampSkillVersion(content, version) {
-    const stamp = `${VERSION_KEY}: ${version}`;
+function setStamps(content, stamps) {
     const match = content.match(FRONTMATTER);
     if (!match)
-        return `---\n${stamp}\n---\n\n${content}`;
-    const fields = (match[1] ?? '')
+        return stamps.length === 0 ? content : `---\n${stamps.join('\n')}\n---\n\n${content}`;
+    const kept = (match[1] ?? '')
         .split('\n')
-        .filter((line) => !line.startsWith(`${VERSION_KEY}:`))
-        .join('\n');
-    return `---\n${fields}\n${stamp}\n---\n${content.slice(match[0].length)}`;
+        .filter((line) => !STAMP_KEYS.some((key) => line.startsWith(`${key}:`)));
+    return `---\n${[...kept, ...stamps].join('\n')}\n---\n${content.slice(match[0].length)}`;
+}
+/** An installed copy with this package's own bookkeeping lines removed. */
+export function stripSkillStamps(content) {
+    return setStamps(content, []);
+}
+/**
+ * The version stamp on its own — the shape releases before #480 wrote, and what
+ * `classifySkillContent` sees as `unknown`. Not the write path; `stampSkill` is.
+ */
+export function stampSkillVersion(content, version) {
+    return setStamps(content, [`${VERSION_KEY}: ${version}`]);
+}
+/** sha256 of the content this package shipped, ignoring the stamps it adds. */
+export function hashSkillContent(content) {
+    return createHash('sha256').update(stripSkillStamps(content)).digest('hex');
+}
+/** The version + hash stamps, as written to disk. */
+export function stampSkill(content, version) {
+    return setStamps(content, [
+        `${VERSION_KEY}: ${version}`,
+        `${HASH_KEY}: ${hashSkillContent(content)}`,
+    ]);
+}
+export function classifySkillContent(installed, shipped) {
+    if (stripSkillStamps(installed) === stripSkillStamps(shipped))
+        return 'pristine';
+    const recorded = readSkillHash(installed);
+    if (!recorded)
+        return 'unknown';
+    return recorded === hashSkillContent(installed) ? 'pristine' : 'modified';
 }
 function versionParts(version) {
     return version.split('.').map((n) => Number.parseInt(n, 10) || 0);
@@ -71,9 +124,10 @@ export function isNewerVersion(a, b) {
 /** The skill source and the package version that will be stamped into it. */
 export async function readShippedSkill(name = SHIPPED_SKILL) {
     const root = getPackageRoot();
-    const content = await fs.readFile(path.join(root, 'skills', name, 'SKILL.md'), 'utf8');
+    const file = path.join(root, 'skills', name, 'SKILL.md');
+    const content = await fs.readFile(file, 'utf8');
     const pkg = await fs.readJson(path.join(root, 'package.json'));
-    return { content, version: String(pkg.version) };
+    return { content, version: String(pkg.version), file };
 }
 /** Whether `file` is itself a symlink, as opposed to merely resolving through one. */
 async function isSymlink(file) {
@@ -94,7 +148,7 @@ async function isSymlink(file) {
  * rename *replaces* the symlink with a real file, orphaning the dotfiles copy
  * with no error at all, which is the split-brain this feature exists to end.
  */
-export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
+export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL, { force = false } = {}) {
     const shipped = await readShippedSkill(name);
     const file = path.join(skillsDir, name, 'SKILL.md');
     const existing = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : null;
@@ -102,8 +156,10 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
     const viaSymlink = await isSymlink(file);
     const base = {
         name,
+        contentState: existing === null ? null : classifySkillContent(existing, shipped.content),
         file,
         viaSymlink,
+        shippedFile: shipped.file,
         realFile: viaSymlink ? await fs.realpath(file) : file,
         installedVersion,
         shippedVersion: shipped.version,
@@ -111,7 +167,13 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
     if (installedVersion && isNewerVersion(installedVersion, shipped.version)) {
         return { ...base, status: 'declined-downgrade' };
     }
-    const next = stampSkillVersion(shipped.content, shipped.version);
+    // Only `pristine` content is provably ours to replace. Anything else is a
+    // fork (or unprovable, which for a destructive write is the same thing) and
+    // stays a human decision — the same rule `fix copied-assets` follows (#448).
+    if (!force && base.contentState !== null && base.contentState !== 'pristine') {
+        return { ...base, status: 'declined-fork' };
+    }
+    const next = stampSkill(shipped.content, shipped.version);
     if (existing === next)
         return { ...base, status: 'up-to-date' };
     await fs.ensureDir(path.dirname(file));
@@ -120,12 +182,13 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
 }
 /** Read-only counterpart of `installClaudeSkill`, for doctor. */
 export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
-    const { version } = await readShippedSkill(name);
+    const shipped = await readShippedSkill(name);
     const { dir } = await resolveSkillsDir(explicit);
     const absent = {
         installed: false,
         installedVersion: null,
-        shippedVersion: version,
+        shippedVersion: shipped.version,
+        contentState: null,
         needsInstall: true,
     };
     if (!dir)
@@ -133,12 +196,16 @@ export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
     const file = path.join(dir, name, 'SKILL.md');
     if (!(await fs.pathExists(file)))
         return { file, ...absent };
-    const installedVersion = readSkillVersion(await fs.readFile(file, 'utf8'));
+    const content = await fs.readFile(file, 'utf8');
+    const installedVersion = readSkillVersion(content);
+    const contentState = classifySkillContent(content, shipped.content);
+    const behind = installedVersion === null || isNewerVersion(shipped.version, installedVersion);
     return {
         file,
         installed: true,
         installedVersion,
-        shippedVersion: version,
-        needsInstall: installedVersion === null || isNewerVersion(version, installedVersion),
+        shippedVersion: shipped.version,
+        contentState,
+        needsInstall: behind && contentState === 'pristine',
     };
 }

package/dist/cli/index.js

@@ -329,6 +329,9 @@ program
     .option('--resync', 'Re-scaffold every file recorded in .repo-tooling.json')
     .option('--diff', 'Show a unified diff of each change before confirming')
     .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Required with --yes/--json when that directory does not exist')
+    // Deliberately not folded into --yes: unattended runs pass --yes, and this is
+    // the one overwrite that destroys work living outside the repo (#480).
+    .option('--force-skills', 'Let `fix claude-skills` overwrite a locally modified skill instead of refusing')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -338,6 +341,7 @@ program
     resync: options.resync,
     diff: options.diff,
     skillsDir: options.skillsDir,
+    forceSkills: options.forceSkills,
 }));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.16.3",
+	"version": "3.18.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