claude-dev-env 2.25.0 → 2.27.0

package/.agents/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -386,6 +386,28 @@ def test_main_headless_flavor_emits_outcome_path_on_stdout(
     assert "add_comment_to_pending_review" not in captured.out
 
 
+def test_code_quality_agent_requires_scoped_intake_and_evidence_gaps() -> None:
+    agent_text = _CODE_QUALITY_AGENT_PATH.read_text(encoding="utf-8")
+
+    required_phrases = (
+        "read each existing `AGENTS.md` and `CLAUDE.md`",
+        "scoped `AGENTS.md` files as the canonical",
+        "`docs/CODE_RULES.md` is a compact projection",
+        "`hooks/blocking/code_rules_enforcer.py` is hand-maintained write-time coverage",
+        "full diff",
+        "resolved base or merge-base",
+        "complete changed-file list",
+        "PR description",
+        "evidence gap",
+        "Never infer omitted content",
+    )
+    for each_phrase in required_phrases:
+        assert each_phrase in agent_text
+
+    assert "## Review intake and policy sources" in agent_text
+    assert "Open questions" in agent_text
+
+
 _PACKAGE_ROOT = _PACKAGE_ROOT_FOR_RUBRICS
 _CODE_QUALITY_AGENT_PATH = _PACKAGE_ROOT / ".agents" / "agents" / "code-quality-agent.md"
 _AUDIT_CONTRACT_PATH = _PACKAGE_ROOT / "_shared" / "pr-loop" / "audit-contract.md"
@@ -395,7 +417,11 @@ _CATEGORY_Q_LABEL = (
     "(terminology, PR-description claims, message-vs-guard)"
 )
 _CATEGORY_Q_RUBRIC_REFERENCE = (
-    "../audit-rubrics/category_rubrics/category-q-cross-surface-claims.md"
+    "`<managed-root>/audit-rubrics/category_rubrics/"
+    "category-q-cross-surface-claims.md`"
+    " (source fallback: "
+    "`packages/claude-dev-env/audit-rubrics/category_rubrics/"
+    "category-q-cross-surface-claims.md`)"
 )
 _A_THROUGH_Q_PATTERN = re.compile(r"A[\u2013-]Q")
 _SEVENTEEN_CATEGORIES_PATTERN = re.compile(r"seventeen categor", re.IGNORECASE)
@@ -417,6 +443,26 @@ def test_code_quality_agent_default_scope_is_a_through_q() -> None:
     assert "| Q |" in agent_text
 
 
+def test_code_quality_agent_contract_is_caller_neutral() -> None:
+    agent_text = _CODE_QUALITY_AGENT_PATH.read_text(encoding="utf-8")
+    stale_terms = (
+        "PR #394",
+        "PR #397",
+        "May 2026",
+        "r3210166636",
+        "/bugteam",
+        "/pr-converge",
+        "/autoconverge",
+        "opus",
+        "sonnet",
+        "model:",
+    )
+    for stale_term in stale_terms:
+        assert stale_term not in agent_text
+    assert "The caller provides the diff, audit scope, ID prefix, and output format." in agent_text
+    assert "Do not assume a model, caller name, or persistence path." in agent_text
+
+
 def test_audit_contract_category_schema_includes_q() -> None:
     contract_text = _AUDIT_CONTRACT_PATH.read_text(encoding="utf-8")
     assert '"category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q"' in (

package/.agents/skills/pr-cleanup/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: pr-cleanup
+disable-model-invocation: true
 description: >-
   Refine pull requests through parallel placement and capability-name audits,
   focused delivery sizing, and a final simplify and code-review loop. Triggers:

package/.agents/skills/pr-plain-language-cleanup/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: pr-plain-language-cleanup
+disable-model-invocation: true
+description: Review every line of every changed PR file and trim words, names, docs, comments, and code while keeping real behavior.
+---
+
+# PR plain-language cleanup
+
+## Balance compression and readability
+
+Shorten changed prose and make it easier to scan. Both matter.
+
+- **Word count:** record before and after counts and the delta. Count changed
+  prose only. Exclude code, frontmatter, and unchanged lines.
+- **Readability:** check sentence length, order, headings, jargon, and dense
+  blocks. Edit only when the result is easier to read.
+- **Diff churn:** count changed lines. Remove whitespace-only movement and
+  reflow-only churn.
+- **Meaning:** preserve behavior, APIs, data, test intent, conditions, warnings,
+  error detail, context, and public names.
+
+Reflow is allowed only when it materially improves scanability after a real trim.
+Report the four results separately.
+
+Review and trim this pull request:
+
+<PR LINK>
+
+If no link is given, find the clear PR in the current context. If none is clear, ask for one.
+
+Read the full PR, full diff, every changed file, changed tests and docs, and all repo rules that apply.
+
+Find the changed files. Send one capable agent to each file. If there are more files than agents, use small batches.
+
+Each agent owns one file. Read every line. Review code, tests, names, comments, docstrings, strings, notes, Markdown, and examples.
+
+Trim filler, repeats, vague words, needless code, needless names, dead notes, jargon, and steps that add no value. Use few words and small words.
+
+Keep real behavior, checks, data, error detail, context, tests, and public names unless a safe full rename is clear. Do not change behavior for style. Do not shorten a name when it loses meaning.
+
+Follow the repo rules:
+
+- Name modules for their capability.
+- Name functions for their action.
+- Name variables for the value they hold.
+- Name classes for what they are.
+- Use capability names for shared code.
+- Keep workflow words on workflow code.
+- Keep comments and docs true to the code.
+- Use real data and real behavior in tests.
+
+## Hard limits
+
+This is a non-material, text-only trim.
+
+DO NOT:
+
+- run `e-simplify`, `e-code-review`, or `source-command-sr-loop`;
+- run `pr-cleanup`, `pr-refinement`, `pr-small-cl`, placement audits, extraction audits, or capability-name audits;
+- run review loops, advisor gates, commit gates, promotion gates, or any other extra cleanup;
+- hunt bugs, change behavior, change APIs, change data, add features, or split the PR;
+- turn a text trim into a code fix.
+
+Run only the smallest checks needed for the files changed. Keep the repo rules. If a material issue appears, report it and stop.
+
+If a change needs another file, report it to the main agent. The main agent owns cross-file changes.
+
+After the file agents finish, apply safe edits, fix cross-file names and links, search for old names and wording, and read every changed file and the full diff again.
+
+Run only the smallest relevant check for the files changed. Fix failures. Check the final diff against the repo rules.
+
+Do not invent behavior, tests, or benefits. Stop and ask only when a change could alter behavior, break a public API, or exceed the PR scope.
+
+Commit and push the changes to the PR branch.
+
+Return:
+
+## What changed
+
+Short list of the main trims.
+
+## Files checked
+
+Every file reviewed.
+
+## Verification
+
+Checks run and results.
+
+## Remaining items
+
+Only items that need a user choice.
+

package/.agents/skills/pr-title-description/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: pr-title-description
+description: Review one or more pull requests and write plain titles and descriptions from the full diff.
+disable-model-invocation: true
+---
+
+Accept one or more pull request links as arguments. Apply the prompt below to each link.
+
+With no argument, use the current task, browser, worktree, or GitHub context to find the pull request or pull requests. If the context does not show a clear pull request, ask for a pull request link.
+
+Review this pull request: <PR link>
+
+Read the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.
+
+Find the main thing this adds for a user, caller, or operator.
+
+Write like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.
+
+Your job is not a dry API blurb. Your job is an illustrative before/after a person can picture.
+
+Gold voice for titles and “What this adds”:
+
+The theme package has a phone icon somewhere. We need to find it.
+
+Before: yell “anyone know how to find icons?” and wait for a hand.
+
+After: call the finder by its name tag: “icon finder, go.”
+
+That’s all “operation id” is — the finder’s name tag.
+
+Rules for that voice:
+
+Start from a concrete scene (what’s in someone’s hand, what they’re hunting for).
+Prefer Before / After when the change is “how you ask” or “how you look it up.”
+Use picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.
+Prefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”
+When the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:
+Drop it and say what the person does with their hands, or
+Keep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.
+Never leave jargon unexplained. Never write as if the reader already knows the jargon.
+Add a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).
+Few words. Small words. Clear on first read.
+Return:
+
+Recommended title
+
+Few words. Small words. Clear on first read.
+Say what you hand it, what it does, and what you get back — or the Before/After of how you ask.
+Prefer picture words and spoken results.
+Good title: “Call the icon finder by its name tag instead of asking around”
+Good title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”
+Bad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.
+Use “Add” only if it helps. Do not force it.
+No vague words like “improve,” “enhance,” or “update.”
+Return one title only.
+Why this title fits
+
+1–2 short sentences in the same voice.
+If needed, one Before / After beat, then what you get back.
+If this section is needed to decode the title, rewrite the title.
+Evidence
+
+Key files or functions that support the title.
+If you cannot read the PR or full diff, say so and do not propose a title.
+
+Then write a short, paste-ready PR description.
+
+Use this structure:
+
+What this adds
+1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature. If there are many changes, keep the main one. Mention others only if they explain the main one.
+
+Why
+One short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”
+
+Verification
+List only proof from the PR, CI, or your own checks.
+
+Reported in the PR
+
+…
+Checked by you / CI here
+
+…
+Rules:
+
+Few words. Small words. Clear on first read. ELI5 I-am-stupid mark.
+Do not invent behavior, tests, or benefits.
+Strip branch names, hashes, draft notes, agent notes, and merge notes.
+No vague words like “improve,” “enhance,” or “update.”
+Illustrative first. Abstract labels only if glossed in the same breath.
+Use the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result.

package/.agents/skills/source-command-sr-loop/SKILL.md

@@ -13,6 +13,14 @@ Run the converging cleanup loop on the target the user names (a PR URL,
 a branch, or blank for the current branch's diff). Each phase invokes an
 existing skill and repeats it until a pass returns zero new findings.
 
+### Nit-only terminal
+
+When a pass finds only nits, apply them, run scoped checks, commit, and push.
+Treat that phase as clean. Do not run another simplify or review pass without
+the user's request. If later work creates an uncommitted out-of-scope diff,
+stop and report it. Do not inspect, repair, commit, or adopt that diff without
+new user instruction.
+
 ### Effort
 
 Set every model call to `max` effort. If that model has no `max` effort, use
@@ -34,7 +42,8 @@ stack's design, intent, and changes.
    code, not the full repo suite), commit once (commit body via
    `git commit -F <file>`, 10-minute timeout — the pre-commit gate runs its
    own tests), and push to the PR head branch. The PR stays draft.
-3. Repeat the invocation. Skips are sticky: carry every adjudicated skip
+3. Repeat the invocation only after substantive findings or a user request.
+   Skips are sticky: carry every adjudicated skip
    forward into the next pass as "already adjudicated — do not re-report: ..."
    context, or the loop never converges.
 4. Phase A converges when a full pass returns zero new findings. When the
@@ -51,8 +60,8 @@ stack's design, intent, and changes.
    when the headless run fails: invoke the `e-code-review` skill with
    `low --fix` — same review-and-fix contract, no invocation restriction.
 2. After any pass that changed files: test, commit, push as in Phase A.
-3. Repeat until a pass reports zero findings. Phase B usually converges in
-   one pass when Phase A ran first.
+3. Repeat until a pass reports zero findings. A nit-only pass ends this phase
+   after its fixes are pushed.
 
 ### Finish
 

package/bin/ever-shipped-skills.mjs

@@ -69,6 +69,8 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'midjourney-submit',
     'monitor-open-prs',
     'pr-name-by-capability',
+    'pr-title-description',
+    'pr-plain-language-cleanup',
     'pr-refinement',
     'orchestrator',
     'orchestrator-refresh',

package/bin/install.agents-home.test.mjs

@@ -25,6 +25,7 @@ import {
     MANAGED_SKILLS_DIRECTORY_NAME,
 } from './install-constants.mjs';
 import { isDirectoryPointerTo } from './publish-directory-pointer.mjs';
+import { resolvePackageManagedDirectory } from './resolve-package-managed-directory.mjs';
 
 const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
 const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
@@ -32,6 +33,41 @@ const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
 const SHIPPED_SKILL_NAME = 'privacy-hygiene';
 const ELI5_SKILL_NAME = 'eli5';
 const SHIPPED_AGENT_FILE_NAME = 'clean-coder.md';
+const SHIPPED_AGENT_FILE_NAMES = [
+    SHIPPED_AGENT_FILE_NAME,
+    'code-quality-agent.md',
+    'pr-description-writer.md',
+];
+const CLEAN_CODER_POLICY_REFERENCES = [
+    [
+        '<managed-root>/docs/CODE_RULES.md',
+        'packages/claude-dev-env/docs/CODE_RULES.md',
+    ],
+    [
+        '<managed-root>/hooks/blocking/code_rules_enforcer.py',
+        'packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py',
+    ],
+    [
+        '<managed-root>/rules/code-standards.md',
+        'packages/claude-dev-env/rules/code-standards.md',
+    ],
+    [
+        '<managed-root>/rules/file-global-constants.md',
+        'packages/claude-dev-env/rules/file-global-constants.md',
+    ],
+    [
+        '<managed-root>/rules/windows-filesystem-safe.md',
+        'packages/claude-dev-env/rules/windows-filesystem-safe.md',
+    ],
+    [
+        '<managed-root>/rules/gh-cli-conventions.md',
+        'packages/claude-dev-env/rules/gh-cli-conventions.md',
+    ],
+    [
+        '<managed-root>/rules/plain-illustrative-docstrings.md',
+        'packages/claude-dev-env/rules/plain-illustrative-docstrings.md',
+    ],
+];
 const PERSONAL_SKILL_NAME = 'my-notes';
 const SHARED_DIRECTORY_NAME = '_shared';
 const PR_LOOP_DIRECTORY_NAME = 'pr-loop';
@@ -41,19 +77,25 @@ const PREFLIGHT_PROPOSAL_POINTER = '@~/.claude/_shared/pr-loop/preflight-proposa
 /**
  * @param {string} homeDirectory
  * @param {string[]} extraArguments
+ * @param {Record<string, string | undefined>} [environmentOverrides]
  * @returns {string}
  */
-function runInstaller(homeDirectory, extraArguments) {
+function runInstaller(homeDirectory, extraArguments, environmentOverrides = {}) {
+    const installerEnvironment = {
+        ...process.env,
+        HOME: homeDirectory,
+        USERPROFILE: homeDirectory,
+        GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        CODEX_HOME: join(homeDirectory, '.codex'),
+        ...environmentOverrides,
+    };
+    for (const [eachName, eachValue] of Object.entries(environmentOverrides)) {
+        if (eachValue === undefined) delete installerEnvironment[eachName];
+    }
     return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
         cwd: PACKAGE_DIRECTORY,
         encoding: 'utf8',
-        env: {
-            ...process.env,
-            HOME: homeDirectory,
-            USERPROFILE: homeDirectory,
-            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
-            CODEX_HOME: join(homeDirectory, '.codex'),
-        },
+        env: installerEnvironment,
     });
 }
 
@@ -75,6 +117,33 @@ function assertProposalContractInstallation(installationPaths) {
     assert.equal(readFileSync(installedContractPath, 'utf8'), readFileSync(sourceContractPath, 'utf8'));
 }
 
+/**
+ * @param {string} agentFilePath
+ * @param {string} layoutName
+ * @param {string} managedRoot
+ * @returns {string[]}
+ */
+function cleanCoderPolicyReferenceProblems(agentFilePath, layoutName, managedRoot) {
+    const agentBody = readFileSync(agentFilePath, 'utf8');
+    const missingReferences = [];
+    for (const [installedReference, sourceReference] of CLEAN_CODER_POLICY_REFERENCES) {
+        const eachReference = layoutName === 'source'
+            ? sourceReference
+            : installedReference;
+        const eachTargetPath = sourceReference.replace('packages/claude-dev-env/', '');
+        if (!agentBody.includes(eachReference)) {
+            missingReferences.push(eachReference + ' is absent');
+        }
+        const resolvedPath = layoutName === 'source'
+            ? join(PACKAGE_DIRECTORY, eachTargetPath)
+            : join(managedRoot, eachTargetPath);
+        if (!existsSync(resolvedPath)) {
+            missingReferences.push(layoutName + ': ' + resolvedPath);
+        }
+    }
+    return missingReferences.map((reference) => layoutName + ': ' + reference);
+}
+
 test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
     assert.equal(CONTENT_DIRECTORIES.includes(MANAGED_AGENTS_DIRECTORY_NAME), false);
 });
@@ -133,6 +202,18 @@ test('a full install writes skills and agents under .agents and points .claude a
             readFileSync(lookupAgentFile, 'utf8'),
             readFileSync(canonicalAgentFile, 'utf8'),
         );
+        const sourceAgentFile = join(
+            resolvePackageManagedDirectory(
+                PACKAGE_DIRECTORY,
+                MANAGED_AGENTS_DIRECTORY_NAME,
+            ),
+            SHIPPED_AGENT_FILE_NAME,
+        );
+        const brokenPolicyReferences = [
+            ...cleanCoderPolicyReferenceProblems(sourceAgentFile, 'source', claudeHome),
+            ...cleanCoderPolicyReferenceProblems(canonicalAgentFile, 'installed', claudeHome),
+        ];
+        assert.deepEqual(brokenPolicyReferences, [], 'Clean Coder has broken policy references');
         assert.equal(realpathSync(lookupAgentFile), realpathSync(canonicalAgentFile));
         assert.equal(
             lstatSync(skillsInstallDirectory).isSymbolicLink(),
@@ -149,6 +230,116 @@ test('a full install writes skills and agents under .agents and points .claude a
     }
 });
 
+test('real installs place the Clean Coder in each active agents home', () => {
+    const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
+    const homeDirectory = join(runRoot, 'home');
+    const configRoot = join(runRoot, 'config-profile');
+    const explicitRoot = join(runRoot, 'explicit-target');
+    const inheritedProfilesRoot = join(runRoot, 'inherited-profiles');
+    const inheritedProfileMarker = join(inheritedProfilesRoot, 'untouched.txt');
+    mkdirSync(homeDirectory, { recursive: true });
+    mkdirSync(inheritedProfilesRoot, { recursive: true });
+    writeFileSync(inheritedProfileMarker, 'leave this profile root alone\n');
+    try {
+        const installCases = [
+            {
+                name: 'default',
+                arguments: ['--only', 'core'],
+                environment: { CLAUDE_CONFIG_DIR: undefined },
+                managedRoot: join(homeDirectory, '.claude'),
+                agentsHome: join(homeDirectory, '.agents'),
+            },
+            {
+                name: 'CLAUDE_CONFIG_DIR',
+                arguments: ['--only', 'core'],
+                environment: { CLAUDE_CONFIG_DIR: configRoot },
+                managedRoot: configRoot,
+                agentsHome: `${configRoot}.agents`,
+            },
+            {
+                name: 'named profile',
+                arguments: ['--profile', 'editor', '--only', 'core'],
+                environment: {
+                    CLAUDE_CONFIG_DIR: undefined,
+                    LLM_SETTINGS_PROFILES_ROOT: undefined,
+                },
+                managedRoot: join(homeDirectory, '.claude-profiles', 'editor'),
+                agentsHome: join(homeDirectory, '.claude-profiles', 'editor.agents'),
+            },
+            {
+                name: 'explicit target',
+                arguments: ['--target', explicitRoot, '--only', 'core'],
+                environment: { CLAUDE_CONFIG_DIR: configRoot },
+                managedRoot: explicitRoot,
+                agentsHome: `${explicitRoot}.agents`,
+            },
+        ];
+
+        for (const eachInstallCase of installCases) {
+            runInstaller(
+                homeDirectory,
+                eachInstallCase.arguments,
+                {
+                    LLM_SETTINGS_PROFILES_ROOT: inheritedProfilesRoot,
+                    ...eachInstallCase.environment,
+                },
+            );
+            for (const eachAgentFileName of SHIPPED_AGENT_FILE_NAMES) {
+                const installedAgentPath = join(
+                    eachInstallCase.agentsHome,
+                    MANAGED_AGENTS_DIRECTORY_NAME,
+                    eachAgentFileName,
+                );
+                assert.equal(
+                    existsSync(installedAgentPath),
+                    true,
+                    `${eachInstallCase.name}: agent is under the active agents home`,
+                );
+                const installedAgentText = readFileSync(installedAgentPath, 'utf8');
+                assert.match(installedAgentText, /active managed root/i);
+                assert.match(installedAgentText, /active agents home/i);
+                assert.match(installedAgentText, /<managed-root>\//);
+                assert.match(installedAgentText, /<agents-home>\//);
+            }
+            const installedCleanCoderPath = join(
+                eachInstallCase.agentsHome,
+                MANAGED_AGENTS_DIRECTORY_NAME,
+                SHIPPED_AGENT_FILE_NAME,
+            );
+            const policyReferenceProblems = cleanCoderPolicyReferenceProblems(
+                installedCleanCoderPath,
+                'installed',
+                eachInstallCase.managedRoot,
+            );
+            assert.deepEqual(
+                policyReferenceProblems,
+                [],
+                `${eachInstallCase.name}: Clean Coder has broken policy references`,
+            );
+            assert.equal(
+                isDirectoryPointerTo(
+                    join(eachInstallCase.managedRoot, MANAGED_AGENTS_DIRECTORY_NAME),
+                    join(eachInstallCase.agentsHome, MANAGED_AGENTS_DIRECTORY_NAME),
+                ),
+                true,
+                `${eachInstallCase.name}: lookup path points to the active agents home`,
+            );
+        }
+        assert.equal(
+            readFileSync(inheritedProfileMarker, 'utf8'),
+            'leave this profile root alone\n',
+            'an inherited profile root stays untouched',
+        );
+        assert.equal(
+            existsSync(join(inheritedProfilesRoot, 'editor')),
+            false,
+            'the named profile does not use the inherited profile root',
+        );
+    } finally {
+        rmSync(runRoot, { recursive: true, force: true });
+    }
+});
+
 test('a real skills directory from an older install lands in .agents and stays readable through the pointer', () => {
     const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-relocate-'));
     const claudeHome = join(homeDirectory, '.claude');

package/bin/install.mjs

@@ -1126,13 +1126,13 @@ function backupHubBeforeOverwrite(destPath, incomingPath, backupName) {
 }
 
 /**
- * PreToolUse hook script paths the installer manages even though hooks.json
+ * Hook script paths the installer manages even though hooks.json
  * carries no standalone entry for them. Most were folded into the PreToolUse
- * dispatcher in Stage 1; md_to_html_blocker is a retired hook with no script on
- * disk. Each path stays in this set so a reinstall from an older settings shape
+ * dispatcher in Stage 1; retired hooks have no current registration.
+ * Each path stays in this set so a reinstall from an older settings shape
  * prunes its standalone entry — a folded hook would otherwise double-run
- * alongside the dispatcher, and the retired hook's entry would point at a
- * missing script.
+ * alongside the dispatcher, and a retired hook's entry would continue to run
+ * from the user's settings.json.
  */
 export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/write_existing_file_blocker.py',
@@ -1150,6 +1150,7 @@ export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/pytest_testpaths_orphan_blocker.py',
     'blocking/open_questions_in_plans_blocker.py',
     'blocking/md_to_html_blocker.py',
+    'session/untracked_repo_detector.py',
 ]);
 
 /**
@@ -1168,14 +1169,19 @@ export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'workflow/md_to_html_companion.py',
 ]);
 
+/** Hook scripts that still ship but no longer run as registered hooks. */
+export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
+    'session/untracked_repo_detector.py',
+]);
+
 /**
  * Builds the set of hook script paths this installer manages, each relative to
  * the hooks directory (e.g. 'blocking/code_rules_enforcer.py'), parsed from the
  * `${CLAUDE_PLUGIN_ROOT}/hooks/<path>` references in hooks.json. Inline
  * `python3 -c` commands reference the hooks directory without a script tail and
  * contribute nothing. Also includes every path from FOLDED_HOOK_RELATIVE_PATHS
- * and POST_FOLDED_HOOK_RELATIVE_PATHS so a reinstall from an older settings shape
- * prunes both the PreToolUse and the PostToolUse folded entries.
+ * and the retained path sets so a reinstall from an older settings shape prunes
+ * folded and retired entries.
  *
  * @param {{hooks: object}} hooksConfig Parsed hooks.json.
  * @returns {Set<string>} Forward-slash relative script paths under hooks/.
@@ -1184,6 +1190,7 @@ export function managedHookScriptRelativePaths(hooksConfig) {
     const relativePaths = new Set([
         ...FOLDED_HOOK_RELATIVE_PATHS,
         ...POST_FOLDED_HOOK_RELATIVE_PATHS,
+        ...RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS,
     ]);
     const scriptReferencePattern = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/(\S+?\.py)/g;
     for (const matcherGroups of Object.values(hooksConfig.hooks)) {
@@ -1408,7 +1415,7 @@ export function mergeHooksIntoSettings(settings, hooksConfig, pluginRootDir, pyt
                     /\$\{CLAUDE_PLUGIN_ROOT\}/g,
                     () => pluginRootForward,
                 );
-                command = command.replace(/^python3\b/, () => pythonCommand);
+                command = command.replace(/^python3?(?=\s)/, () => pythonCommand);
                 return { ...hook, command };
             });
             const existingIndex = settings.hooks[eventType].findIndex(