@rtorcato/repo-tooling 3.16.2 → 3.17.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/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/commands/setup.js

@@ -108,7 +108,7 @@ export async function setupProject(options) {
     const interactive = !options.config && !options.preset;
     const dryRun = options.dryRun === true;
     if (interactive && !dryRun) {
-        console.log(chalk.cyan('\n🛠️  Welcome to JS Tooling Setup!\n'));
+        console.log(chalk.cyan('\n🛠️  Welcome to repo-tooling setup!\n'));
         console.log(chalk.gray(`Setting up tooling in: ${targetDir}\n`));
     }
     try {

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.2",
+	"version": "3.17.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

@@ -43,14 +43,12 @@ real approvals.
 
 The same constraint makes everything an agent posts *look* hand-written by the
 owner. So **every comment any agent leaves — review, blocked, gave-up, declined —
-opens with a `🤖 *Automated …*` italic header line** naming which agent wrote it,
-followed by a blank line. Non-negotiable: a detailed security review under a
-human's avatar misrepresents who reviewed the code.
+opens with a `🤖 *Automated …*` italic header line naming which agent wrote it**,
+then a blank line. Name the agent and stop there: a detailed security review
+under a human's avatar misrepresents who reviewed the code, but *why* it wears
+that avatar is read once and then reread on every comment forever.
 
-Spell the reason out rather than assuming the reader knows the convention — the
-header names the agent *and* says why it is wearing a human's face:
-
-`🤖 *Automated — <which agent> via ai-issue-loop. Posted under the owner's account by an agent; not a human message. There is no separate GitHub account for AI agents, so this appears under @<owner>'s avatar.*`
+`🤖 *Automated — <which agent> via ai-issue-loop.*`
 
 **Comment budget: ≤10 lines, and a clean outcome gets no comment at all.** A
 40-line comment on every PR trains the reader to skip all of them, including the
@@ -63,7 +61,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`. |
 | `ai-changes`, CI red, `ai-blocked` | ≤10 lines, action first, then the specific cause. |
-| Reviewer verdict | `### Before merging` plus at most 3 short paragraphs above it. |
+| Reviewer verdict | `### Before merging` plus ≤600 characters above it. |
 | Declining an issue | The one exception — a hard handoff needs its reasoning; see Pass 4. |
 
 ## Labels
@@ -448,7 +446,7 @@ ping-pong stop and an implementer handing back, leave it off for the same reason
 **Every `ai-blocked` must say why, and land in front of a human.** So reaping always
 does three things together — label, assign, comment — and the comment opens with
 
-`🤖 *Automated — \`ai-issue-loop\` Pass 2 (stall reaping). Posted under the owner's account; not a human message.*`
+`🤖 *Automated — \`ai-issue-loop\` Pass 2 (stall reaping).*`
 
 then a blank line. State which stall rule fired, how long the label sat, and whether a
 worktree was removed. A bare `ai-blocked` with no explanation is worse than no label:
@@ -506,20 +504,19 @@ Reviewer prompt template:
 > purpose. Also read the repo's `CLAUDE.md` if the diff plausibly touches a rule
 > it states.
 >
-> `<code-reviewer: Judge correctness, obvious bugs, and adherence to the repo's
-> stated conventions.>` / `<security-expert: Judge injection risk, leaked
-> secrets, unsafe shell/SQL construction, and dependency or supply-chain
-> changes.>`
+> `<code-reviewer: Judge correctness, obvious bugs, and adherence to the repo's stated
+> conventions.>` / `<security-expert: Judge injection risk, leaked secrets, unsafe
+> shell/SQL construction, and dependency or supply-chain changes.>` That is the
+> checklist to run, not an outline to write up.
 >
 > Post your verdict as a comment — **never** `--approve`, it errors on your own
 > PR:
 > `gh pr review <N> --comment --body "..."`
 >
-> The body **must** begin with this exact header line, then a blank line. Every
-> agent authenticates as the repo owner, so without it the timeline reads as if
-> a human wrote the review:
+> The body **must** begin with this exact header line, then a blank line — you
+> authenticate as the repo owner, so without it the review reads as a human's:
 >
-> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop. Posted under the owner's account; not a human review.*`
+> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*`
 >
 > The body **must end** with this section, as its last thing:
 >
@@ -538,13 +535,14 @@ Reviewer prompt template:
 > That section is what a human reads at merge time, so put anything you would
 > want them to know there rather than leaving it in the prose above — a finding
 > buried mid-paragraph does not survive the handoff. For the same reason, **cap
-> the body at that section plus at most 3 short paragraphs above it**: no process
-> narration, no restating the diff, no listing what you checked and found fine.
-> 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 observations, not praise, not
-> restating the diff. Writing `Nothing.` is a real verdict and the common one —
-> say it plainly rather than padding the section to look thorough.
+> the body at that section plus ≤600 characters above it**. Verify everything;
+> 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.
 >
 > Then apply exactly one verdict label, **clearing your claim label in the same
 > command**:
@@ -646,8 +644,8 @@ package/from/to table survives because it sits at the top; classify from that.
 > State in your comment which rule fired, name the packages that tripped it, and say
 > whether the body was truncated so the reader knows what you could and couldn't see.
 > Same `🤖 *Automated review — …*` header line, same closing `### Before merging`
-> section, same 3-paragraph cap on the body, and same one-verdict-label rule as
-> above — **including clearing your
+> section, same ≤600-character cap and no-negative-findings rule on the body, and same
+> one-verdict-label rule as above — **including clearing your
 > `<ai-reviewing-code|ai-reviewing-sec>` claim label in the same `gh pr edit`**.
 > Pass 3 claimed you with it before spawning you, and a claim left behind wedges
 > your half of the review until Pass 2 reaps it.
@@ -682,7 +680,7 @@ gh api "repos/$OWNER_REPO/issues/<N>/timeline" \
 ```
 
 If that count is **≥ 3**, stop looping. Comment the reason on the PR — opening with
-`🤖 *Automated — \`ai-issue-loop\` Pass 3. Posted under the owner's account; not a human message.*`
+`🤖 *Automated — \`ai-issue-loop\` Pass 3.*`
 and a blank line — naming what each round changed and why the reviewer kept objecting,
 then:
 
@@ -751,10 +749,9 @@ same issue gets re-triaged from scratch every time, and the reasoning that took
 real work to reach is lost.
 
 The comment opens with the standard `🤖 *Automated …*` header — see the top of this
-file; it must state that no GitHub account exists for AI agents, so the comment
-wears the owner's avatar. Then, in the body — **this is the one comment exempt
-from the ≤10-line budget, and only this one.** Declining is a hard handoff whose
-whole value is the reasoning; do not reach for this shape on a PR handoff:
+file. Then, in the body — **this is the one comment exempt from the ≤10-line
+budget, and only this one.** Declining is a hard handoff whose whole value is the
+reasoning; do not reach for this shape on a PR handoff:
 
 - **Why an agent cannot finish it**, concretely. "Not suitable" is useless. Name
   the blocker: binary assets it cannot author, a force-push past branch
@@ -879,7 +876,7 @@ Then spawn a background implementer agent:
 > **must** open with this exact line, then a blank line — you authenticate as the
 > owner, so without it the issue reads as if they wrote it themselves:
 >
-> `🤖 *Automated — implementer via ai-issue-loop. Posted under the owner's account; not a human message.*`
+> `🤖 *Automated — implementer via ai-issue-loop.*`
 >
 > Say what you tried, the exact error, and what a human would need to decide. "Could
 > not finish" with no detail wastes the handoff — the whole point of the label is that